Feat - collection sorting (#1212)

* refactor collection item sorting into a separate function

* refactor: update sorting function to use a new type for collection items

* test: add unit tests for sortCollectionItems function

* refactor: update sortCollectionItems function to accept an object parameter

* enhance unit tests for sortCollectionItems with additional sorting scenarios

* refactor: move sorting logic to a dedicated sortCollectionItems function and add comprehensive unit tests

* fix: correct import path for SortableCardProps in sortCollectionItems tests

* fix: update test assertion

* test: add "arrange", "act", "assert" comment for better structuring

* refactor: enhance sortCollectionItems function to support sorting by title and date with improved logic

* add defaultSortBy and defaultSortDirection options to CollectionPagePageSchema for enhanced sorting capabilities

* update props type source + pass in props accordingly

* refactor: make sortBy and sortDirection optional in GetCollectionItemsProps

* refactor: simplify SortCollectionItemsProps by extending from GetCollectionItemsProps

* refactor: update defaultSortDirection to extend props type in page router

* refactor: change defaultSortDirection from "asc" to "desc" in page router for improved sorting behavior

* refactor: enhance CollectionPagePageSchema by adding metadata to defaultSortBy and defaultSortDirection options

* refactor: simplify assertions in sortCollectionItems tests

* update test name

* refactor: enhance sorting logic in sortCollectionItems to handle numeric title comparisons

* fix: correct sorting logic and default direction in sortCollectionItems for accurate item ordering

* refactor: improve sorting logic in sortCollectionItems to handle date and title comparisons more effectively

* fix type

* feat: add category sorting to sortCollectionItems with title as tiebreaker

* fix: handle equal dates in sortCollectionItems to ensure stable sorting

Author: adriangohjw

apps/studio/src/server/modules/page/page.router.ts

@@ -1,4 +1,7 @@
-import type { IsomerSchema } from "@opengovsg/isomer-components"
+import type {
+  CollectionPagePageProps,
+  IsomerSchema,
+} from "@opengovsg/isomer-components"
 import {
   getLayoutMetadataSchema,
   ISOMER_USABLE_PAGE_LAYOUTS,
@@ -809,8 +812,8 @@ export const pageRouter = router({
                 title: parent.title,
                 subtitle: `Read more on ${parent.title.toLowerCase()} here.`,
                 defaultSortBy: "date",
-                defaultSortDirection: "asc",
-              },
+                defaultSortDirection: "desc",
+              } as CollectionPagePageProps,
               content: [],
               version: "0.1.0",
             }

packages/components/src/templates/next/layouts/Collection/Collection.tsx

@@ -61,9 +61,14 @@ const CollectionLayout = ({
   LinkComponent,
   ScriptComponent,
 }: CollectionPageSchemaType) => {
-  const { permalink } = page
+  const { permalink, defaultSortBy, defaultSortDirection } = page
 
-  const items = getCollectionItems(site, permalink)
+  const items = getCollectionItems({
+    site,
+    permalink,
+    sortBy: defaultSortBy,
+    sortDirection: defaultSortDirection,
+  })
   const processedItems = processedCollectionItems(items)
   const breadcrumb = getBreadcrumbFromSiteMap(
     site.siteMap,

packages/components/src/templates/next/layouts/Collection/utils/__tests__/sortCollectionItems.test.ts

@@ -0,0 +1,302 @@
+import { beforeAll, describe, expect, it } from "vitest"
+
+import type { SortableCardProps } from "../sortCollectionItems"
+import { sortCollectionItems } from "../sortCollectionItems"
+
+describe("sortCollectionItems", () => {
+  let itemCounter = 0
+
+  const createItem = ({
+    title = "Test Item",
+    date,
+    variant = "article",
+    url = "",
+    category = "Others",
+  }: {
+    title?: string
+    date?: Date
+    variant?: "file" | "link" | "article"
+    url?: string
+    category?: string
+  }): SortableCardProps => {
+    itemCounter++
+    return {
+      id: `test-${itemCounter}`,
+      title,
+      rawDate: date,
+      variant,
+      url,
+      description: "",
+      category,
+      site: {
+        siteMap: {
+          id: "root",
+          title: "Test Site",
+          summary: "",
+          lastModified: "2024-01-01",
+          permalink: "/",
+          layout: "homepage",
+        },
+        siteName: "Test Site",
+        theme: "isomer-next",
+        logoUrl: "",
+        search: {
+          type: "localSearch",
+          searchUrl: "/search",
+        },
+        navBarItems: [],
+        footerItems: {
+          siteNavItems: [],
+          privacyStatementLink: "/privacy",
+          termsOfUseLink: "/terms",
+        },
+        lastUpdated: "2024-01-01",
+      },
+    } as SortableCardProps
+  }
+
+  it("should sort items by date (newest first)", () => {
+    // Arrange
+    const items = [
+      createItem({ title: "Oldest", date: new Date("2023-01-01") }),
+      createItem({ title: "Newest", date: new Date("2023-12-31") }),
+      createItem({ title: "Middle", date: new Date("2023-06-15") }),
+    ]
+
+    // Act
+    const sorted = sortCollectionItems({ items })
+
+    // Assert
+    const expectedTitles = ["Newest", "Middle", "Oldest"]
+    expect(sorted.map((item) => item.title)).toEqual(expectedTitles)
+  })
+
+  it("should sort by title when dates are equal", () => {
+    // Arrange
+    const sameDate = new Date("2023-01-01")
+    const items = [
+      createItem({ title: "Charlie", date: sameDate }),
+      createItem({ title: "Alice", date: sameDate }),
+      createItem({ title: "Bob", date: sameDate }),
+    ]
+
+    // Act
+    const sorted = sortCollectionItems({ items })
+
+    // Assert
+    const expectedTitles = ["Alice", "Bob", "Charlie"]
+    expect(sorted.map((item) => item.title)).toEqual(expectedTitles)
+  })
+
+  it("should sort by title when dates are equal and take into account numbers in the title", () => {
+    // Arrange
+    const sameDate = new Date("2023-01-01")
+    const items = [
+      createItem({ title: "2 ogpeople", date: sameDate }),
+      createItem({ title: "1 ogpeople", date: sameDate }),
+      createItem({ title: "10 ogpeople", date: sameDate }),
+    ]
+
+    // Act
+    const sorted = sortCollectionItems({
+      items,
+      sortBy: "title",
+      sortDirection: "desc",
+    })
+
+    // Assert
+    const expectedTitles = ["10 ogpeople", "2 ogpeople", "1 ogpeople"]
+    expect(sorted.map((item) => item.title)).toEqual(expectedTitles)
+  })
+
+  describe("should place items without dates at the end, sorted alphabetically by title:", () => {
+    let items: SortableCardProps[]
+
+    beforeAll(() => {
+      items = [
+        createItem({ title: "No Date" }),
+        createItem({ title: "Newest", date: new Date("2023-12-31") }),
+        createItem({ title: "Also No Date" }),
+        createItem({ title: "Oldest", date: new Date("2023-01-01") }),
+      ]
+    })
+
+    it("sortBy is title", () => {
+      // Act
+      const sorted = sortCollectionItems({
+        items,
+        sortBy: "title",
+        sortDirection: "asc",
+      })
+
+      // Assert
+      const expectedTitles = ["Newest", "Oldest", "Also No Date", "No Date"]
+      expect(sorted.map((item) => item.title)).toEqual(expectedTitles)
+    })
+
+    it("sortBy is category", () => {
+      // Act
+      const sorted = sortCollectionItems({
+        items,
+        sortBy: "category",
+        sortDirection: "asc",
+      })
+
+      // Assert
+      const expectedTitles = ["Newest", "Oldest", "Also No Date", "No Date"]
+      expect(sorted.map((item) => item.title)).toEqual(expectedTitles)
+    })
+
+    it("sortBy is date", () => {
+      // Act
+      const sorted = sortCollectionItems({
+        items,
+        sortBy: "date",
+        sortDirection: "desc",
+      })
+
+      // Assert
+      const expectedTitles = ["Newest", "Oldest", "Also No Date", "No Date"]
+      expect(sorted.map((item) => item.title)).toEqual(expectedTitles)
+    })
+  })
+
+  describe("should sort by title with date as tiebreaker (newest first) when sortBy is title and", () => {
+    let items: SortableCardProps[]
+
+    beforeAll(() => {
+      // Arrange
+      const sameDate = new Date("2023-01-01")
+      items = [
+        createItem({
+          title: "Charlie",
+          date: new Date("2023-12-30"),
+          url: "/charlie-2023-12-30",
+        }),
+        createItem({
+          title: "Charlie",
+          date: new Date("2023-12-31"),
+          url: "/charlie-2023-12-31",
+        }),
+        createItem({ title: "Alice", date: new Date("2022-01-01") }),
+        createItem({ title: "Bob", date: sameDate }),
+        createItem({ title: "David", date: sameDate }),
+      ]
+    })
+
+    it("sortDirection is desc", () => {
+      // Act
+      const sorted = sortCollectionItems({
+        items,
+        sortBy: "title",
+        sortDirection: "desc",
+      })
+
+      // Assert
+      const expectedTitles = ["David", "Charlie", "Charlie", "Bob", "Alice"]
+      expect(sorted.map((item) => item.title)).toEqual(expectedTitles)
+      expect(sorted[1]?.url).toEqual("/charlie-2023-12-31")
+      expect(sorted[2]?.url).toEqual("/charlie-2023-12-30")
+    })
+
+    it("sortDirection is asc", () => {
+      // Act
+      const sorted = sortCollectionItems({
+        items,
+        sortBy: "title",
+        sortDirection: "asc",
+      })
+
+      // Assert
+      const expectedTitles = ["Alice", "Bob", "Charlie", "Charlie", "David"]
+      expect(sorted.map((item) => item.title)).toEqual(expectedTitles)
+      expect(sorted[2]?.url).toEqual("/charlie-2023-12-31")
+      expect(sorted[3]?.url).toEqual("/charlie-2023-12-30")
+    })
+  })
+
+  describe("should sort by category with title as tiebreaker (alphabetically) when sortBy is category and", () => {
+    let items: SortableCardProps[]
+
+    beforeAll(() => {
+      items = [
+        createItem({ category: "2000" }),
+        createItem({ category: "2001", title: "Alice" }),
+        createItem({ category: "2001", title: "Bob" }),
+        createItem({ category: "2002" }),
+      ]
+    })
+
+    it("sortDirection is desc", () => {
+      // Act
+      const sorted = sortCollectionItems({
+        items,
+        sortBy: "category",
+        sortDirection: "desc",
+      })
+
+      // Assert
+      const expectedCategories = ["2002", "2001", "2001", "2000"]
+      expect(sorted.map((item) => item.category)).toEqual(expectedCategories)
+      expect(sorted[1]?.title).toEqual("Alice")
+      expect(sorted[2]?.title).toEqual("Bob")
+    })
+
+    it("sortDirection is asc", () => {
+      // Act
+      const sorted = sortCollectionItems({
+        items,
+        sortBy: "category",
+        sortDirection: "asc",
+      })
+
+      // Assert
+      const expectedCategories = ["2000", "2001", "2001", "2002"]
+      expect(sorted.map((item) => item.category)).toEqual(expectedCategories)
+      expect(sorted[1]?.title).toEqual("Alice")
+      expect(sorted[2]?.title).toEqual("Bob")
+    })
+  })
+
+  describe("should sort by date with title as tiebreaker (alphabetically) when sortBy is date and", () => {
+    let items: SortableCardProps[]
+
+    beforeAll(() => {
+      // Arrange
+      const sameDate = new Date("2023-01-01")
+      items = [
+        createItem({ title: "Newest", date: new Date("2023-12-31") }),
+        createItem({ title: "Charlie", date: sameDate }),
+        createItem({ title: "Alice", date: sameDate }),
+        createItem({ title: "Bob", date: sameDate }),
+        createItem({ title: "Oldest", date: new Date("2022-01-01") }),
+      ]
+    })
+
+    it("sortDirection is desc", () => {
+      // Act
+      const sorted = sortCollectionItems({
+        items,
+        sortBy: "date",
+        sortDirection: "desc",
+      })
+
+      // Assert
+      const expectedTitles = ["Newest", "Alice", "Bob", "Charlie", "Oldest"]
+      expect(sorted.map((item) => item.title)).toEqual(expectedTitles)
+    })
+
+    it("sortDirection is asc", () => {
+      // Act
+      const sorted = sortCollectionItems({
+        items,
+        sortBy: "date",
+        sortDirection: "asc",
+      })
+
+      // Assert
+      const expectedTitles = ["Oldest", "Alice", "Bob", "Charlie", "Newest"]
+      expect(sorted.map((item) => item.title)).toEqual(expectedTitles)
+    })
+  })
+})