@byline/core 3.20.2 → 3.20.3

package/dist/@types/admin-types.d.ts

@@ -54,6 +54,22 @@ export interface ColumnDefinition<T = any> {
     className?: string;
     formatter?: ColumnFormatter<T>;
 }
+/**
+ * Default sort for a collection's list view, applied when the URL carries
+ * no explicit `order`/`desc` search params. An explicit param always wins
+ * (a shared link opens exactly as sent).
+ *
+ * `field` is a top-level schema field name (e.g. `'publicationDate'`) or a
+ * document-level column (`'createdAt'`, `'updatedAt'`, `'path'`). Validated
+ * at boot by `validateAdminConfigs`. Not allowed on `orderable: true`
+ * collections — manual ordering already owns their default sort
+ * (`order_key asc`).
+ */
+export interface ListDefaultSort<T = any> {
+    field: keyof T | 'createdAt' | 'updatedAt' | 'path';
+    /** Defaults to `'asc'`. */
+    direction?: 'asc' | 'desc';
+}
 /**
  * A single tab inside a tab set.
  */
@@ -181,6 +197,21 @@ export interface CollectionAdminConfig<T = any> {
     group?: string;
     /** Column definitions for the collection list view. */
     columns?: ColumnDefinition<T>[];
+    /**
+     * Default sort for the list view when the URL carries no explicit
+     * `order`/`desc` search params — e.g. a publications library that should
+     * open newest-publication-first:
+     *
+     * ```ts
+     * defaultSort: { field: 'publicationDate', direction: 'desc' },
+     * ```
+     *
+     * Precedence: explicit URL params → this default → `created_at desc`.
+     * Boot-validated: `field` must be a top-level schema field or a document
+     * column (`createdAt` / `updatedAt` / `path`), and the option is rejected
+     * on `orderable: true` collections (manual ordering owns their default).
+     */
+    defaultSort?: ListDefaultSort<T>;
     /**
      * Column definitions for rendering this collection as a compact **item
      * row / tile** wherever a single document is shown outside its own list —

package/dist/config/validate-admin-configs.d.ts

@@ -24,6 +24,11 @@ import type { CollectionAdminConfig, CollectionDefinition } from '../@types/inde
  *     schema field names; groups exclude tabSets and nested groups.
  *  6. `fields` map sanity — every key in `admin.fields` matches a top-level
  *     schema field name.
+ *  7. `defaultSort` sanity — `field` resolves to a top-level schema field
+ *     or a document-level column (`createdAt` / `updatedAt` / `path`), the
+ *     direction (when given) is `asc` | `desc`, and the option is rejected
+ *     on `orderable: true` collections (manual ordering owns their default
+ *     sort and the drag-to-reorder canonical-view check assumes it).
  *
  * Throws a plain `Error` (not a `BylineError`) because configuration
  * validation runs at startup, before the logger and error registry are

package/dist/config/validate-admin-configs.js

@@ -23,6 +23,11 @@
  *     schema field names; groups exclude tabSets and nested groups.
  *  6. `fields` map sanity — every key in `admin.fields` matches a top-level
  *     schema field name.
+ *  7. `defaultSort` sanity — `field` resolves to a top-level schema field
+ *     or a document-level column (`createdAt` / `updatedAt` / `path`), the
+ *     direction (when given) is `asc` | `desc`, and the option is rejected
+ *     on `orderable: true` collections (manual ordering owns their default
+ *     sort and the drag-to-reorder canonical-view check assumes it).
  *
  * Throws a plain `Error` (not a `BylineError`) because configuration
  * validation runs at startup, before the logger and error registry are
@@ -57,6 +62,26 @@ function validateOne(admin, collectionsByPath) {
         if ('name' in field)
             topLevelFieldNames.add(field.name);
     }
+    // Rule 7 — defaultSort sanity. The list read applies this spec verbatim
+    // (host list server fn → parseSort), so a bad field name would silently
+    // fall back to `created_at desc` at request time — fail loudly at boot
+    // instead.
+    if (admin.defaultSort != null) {
+        const { field, direction } = admin.defaultSort;
+        const documentColumns = new Set(['createdAt', 'updatedAt', 'path']);
+        if (collection.orderable === true) {
+            fail(`defaultSort is not allowed on an orderable collection — manual ordering owns the default sort (order_key asc).`);
+        }
+        if (typeof field !== 'string' || field.length === 0) {
+            fail(`defaultSort.field must be a non-empty string.`);
+        }
+        if (!topLevelFieldNames.has(field) && !documentColumns.has(field)) {
+            fail(`defaultSort.field "${String(field)}" is not a top-level schema field or a document column (createdAt, updatedAt, path).`);
+        }
+        if (direction != null && direction !== 'asc' && direction !== 'desc') {
+            fail(`defaultSort.direction must be 'asc' or 'desc' (got "${String(direction)}").`);
+        }
+    }
     // Build primitive lookup tables.
     const tabSets = admin.tabSets ?? [];
     const rows = admin.rows ?? [];

package/dist/config/validate-admin-configs.test.node.js

@@ -201,6 +201,43 @@ describe('validateAdminConfigs', () => {
         };
         expect(() => validateAdminConfigs([admin], [collection])).toThrow(/not a top-level schema field/);
     });
+    // Rule 7 — defaultSort sanity.
+    it('accepts a defaultSort on a schema field', () => {
+        const admin = {
+            ...baseAdmin,
+            defaultSort: { field: 'title', direction: 'desc' },
+        };
+        expect(() => validateAdminConfigs([admin], [collection])).not.toThrow();
+    });
+    it('accepts a defaultSort on a document column', () => {
+        const admin = {
+            ...baseAdmin,
+            defaultSort: { field: 'updatedAt' },
+        };
+        expect(() => validateAdminConfigs([admin], [collection])).not.toThrow();
+    });
+    it('rejects a defaultSort field that resolves to nothing', () => {
+        const admin = {
+            ...baseAdmin,
+            defaultSort: { field: 'nonexistent' },
+        };
+        expect(() => validateAdminConfigs([admin], [collection])).toThrow(/defaultSort\.field "nonexistent"/);
+    });
+    it('rejects a defaultSort direction outside asc/desc', () => {
+        const admin = {
+            ...baseAdmin,
+            defaultSort: { field: 'title', direction: 'sideways' },
+        };
+        expect(() => validateAdminConfigs([admin], [collection])).toThrow(/defaultSort\.direction must be 'asc' or 'desc'/);
+    });
+    it('rejects a defaultSort on an orderable collection', () => {
+        const orderableCollection = { ...collection, orderable: true };
+        const admin = {
+            ...baseAdmin,
+            defaultSort: { field: 'title' },
+        };
+        expect(() => validateAdminConfigs([admin], [orderableCollection])).toThrow(/not allowed on an orderable collection/);
+    });
     // Layout omitted — bookkeeping skipped, primitive declarations still checked.
     it('skips placement bookkeeping when layout is omitted', () => {
         const admin = {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.20.2",
+  "version": "3.20.3",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -76,7 +76,7 @@
     "pino": "^10.3.1",
     "sharp": "^0.35.3",
     "zod": "^4.4.3",
-    "@byline/auth": "3.20.2"
+    "@byline/auth": "3.20.3"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",