feat: allow custom collection sort (#714)

Author: stevenle

.changeset/gentle-sorts-add.md

@@ -0,0 +1,5 @@
+---
+'@blinkk/root-cms': patch
+---
+
+feat: add custom sort options to schema.collection()

docs/collections/Pages.schema.ts

@@ -19,6 +19,9 @@ export default schema.collection({
     },
   },
   autolock: true,
+  sortOptions: [
+    {id: 'title', label: 'Title A-Z', field: 'fields.meta.title'},
+  ],
 
   fields: [
     schema.object({

packages/root-cms/core/schema.test.ts

@@ -416,3 +416,4 @@ test('define schema', () => {
     }
   `);
 });
+

packages/root-cms/core/schema.ts

@@ -330,6 +330,23 @@ export type Collection = Schema & {
       src: string;
     };
   };
+  /**
+   * Custom sort options available when listing documents in the CMS.
+   *
+   * NOTE: a new DB index may need to be created for the sort option. The first
+   * time using the sort option, you will get an error that provides a link for
+   * creating the index.
+   */
+  sortOptions?: Array<{
+    /** Unique identifier for the sort option. */
+    id: string;
+    /** Label displayed in the CMS UI. */
+    label: string;
+    /** DB field path to sort by, e.g. 'fields.meta.title'. */
+    field: string;
+    /** Sort direction. Defaults to ascending. */
+    direction?: 'asc' | 'desc';
+  }>;
   /**
    * Regular expression used to validate document slugs. Should be provided as a
    * string so it can be serialized to the CMS UI.

packages/root-cms/ui/hooks/useDocsList.ts

@@ -41,6 +41,15 @@ export function useDocsList(collectionId: string, options: {orderBy: string}) {
       dbQuery = query(dbCollection, queryOrderby(documentId()));
     } else if (orderBy === 'slugDesc') {
       dbQuery = query(dbCollection, queryOrderby(documentId(), 'desc'));
+    } else {
+      const col = window.__ROOT_CTX.collections[collectionId] as any;
+      const custom = col?.sortOptions?.find((s: any) => s.id === orderBy);
+      if (custom) {
+        dbQuery =
+          custom.direction === 'desc'
+            ? query(dbCollection, queryOrderby(custom.field, 'desc'))
+            : query(dbCollection, queryOrderby(custom.field));
+      }
     }
     await notifyErrors(async () => {
       const snapshot = await getDocs(dbQuery);

packages/root-cms/ui/pages/CollectionPage/CollectionPage.tsx

@@ -153,6 +153,15 @@ CollectionPage.Collection = (props: CollectionProps) => {
     return <></>;
   }
 
+  const sortOptions = [
+    {value: 'slug', label: 'A-Z'},
+    {value: 'slugDesc', label: 'Z-A'},
+    {value: 'newest', label: 'Newest'},
+    {value: 'oldest', label: 'Oldest'},
+    {value: 'modifiedAt', label: 'Last modified'},
+    ...(collection.sortOptions?.map((s: any) => ({value: s.id, label: s.label})) || []),
+  ];
+
   const [loading, listDocs, docs] = useDocsList(props.collection, {orderBy});
 
   return (
@@ -193,13 +202,7 @@ CollectionPage.Collection = (props: CollectionProps) => {
                         onChange={(value: any) =>
                           setOrderBy(value || 'modifiedAt')
                         }
-                        data={[
-                          {value: 'slug', label: 'A-Z'},
-                          {value: 'slugDesc', label: 'Z-A'},
-                          {value: 'newest', label: 'Newest'},
-                          {value: 'oldest', label: 'Oldest'},
-                          {value: 'modifiedAt', label: 'Last modified'},
-                        ]}
+                        data={sortOptions}
                       />
                     </div>
                     <div className="CollectionPage__collection__docsTab__controls__newDoc">