@byline/core 3.20.2 → 3.20.4

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/@types/collection-types.d.ts

@@ -993,9 +993,7 @@ export interface CollectionDefinition {
      *   Text fields contribute their value; `richText` fields are extracted to
      *   plain text via the registered `fields.richText.toText` seam. Each entry
      *   is a field path, or `{ field, boost }` to weight it for scoring
-     *   providers that support `capabilities.weighting`. Drives the admin
-     *   list-view search box (its `store_text` subset). Falls back to the
-     *   identity field (`useAsTitle`) when omitted.
+     *   providers that support `capabilities.weighting`.
      * - `facets` — relation field paths to controlled-vocabulary collections.
      *   Core resolves each target's `counter` field (the stable aggregation id)
      *   and its `useAsTitle` (the term, folded into searchable text). `{ field,
@@ -1015,6 +1013,27 @@ export interface CollectionDefinition {
         filters?: string[];
         zones?: string[];
     };
+    /**
+     * Admin list-view quick-search fields — the top-level text-store field
+     * names (`text` / `textArea` / `select`) the list route's search box
+     * matches with substring (`ILIKE`) queries against `store_text`.
+     *
+     * Deliberately separate from `search`, which configures provider indexing
+     * for site search: the two answer different questions ("find the row I
+     * mean" vs. "rank relevant published content") and need not name the same
+     * fields — a collection with a six-field weighted `search.body` typically
+     * wants only its identity field (plus maybe a serial/code field) here.
+     * Declaring one without the other is equally valid: `listSearch` with no
+     * `search` keeps the list box working on an unindexed collection.
+     *
+     * Falls back to the identity field (`useAsTitle`, else the first declared
+     * text field) when omitted — most collections need no declaration.
+     *
+     * Lives on the schema (not admin config) for the same reason as
+     * `useAsTitle`: the query layer (`findDocuments` in the db adapter)
+     * resolves it server-side from the `CollectionDefinition`.
+     */
+    listSearch?: string[];
     /**
      * The field that represents this document's identity — used anywhere a
      * single-line label for the document is needed: form headings, relation

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/dist/config/validate-collections.d.ts

@@ -33,6 +33,9 @@ export declare const RESERVED_FIELD_NAMES: ReadonlySet<string>;
  *  - A collection may not set both `tree: true` and `orderable: true`. A
  *    document-tree owns ordering per-parent on the tree edge, so
  *    `byline_documents.order_key` is inert for it.
+ *  - Each `listSearch` entry must name an existing top-level field whose
+ *    type is persisted to the text store (the admin list-view search box
+ *    is an `ILIKE` over `store_text`), and the field may not be virtual.
  *  - `virtual` fields must satisfy the constraints in
  *    {@link validateVirtualFields} (optional-or-default, no counters, no
  *    upload fields, not referenced by useAsTitle / useAsPath / search).

package/dist/config/validate-collections.js

@@ -5,6 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import { fieldTypeToStore } from '../storage/field-store-map.js';
 /**
  * Field names that cannot be declared in a collection schema because they
  * collide with system-managed attributes on `documentVersions`. Exported
@@ -21,6 +22,15 @@ const RESERVED_FIELD_HINTS = {
     path: "Use `useAsPath: '<sourceField>'` on the collection definition instead.",
     availableLocales: 'Use `advertiseLocales: true` on the collection definition instead.',
 };
+/**
+ * Field types `listSearch` may name — the types persisted to the text
+ * store, since the admin list-view search box is an `ILIKE` over
+ * `store_text`. Derived from the canonical field→store mapping so the two
+ * can't drift.
+ */
+const LIST_SEARCH_SOURCE_TYPES = new Set(Object.entries(fieldTypeToStore)
+    .filter(([, mapping]) => mapping?.storeType === 'text')
+    .map(([type]) => type));
 const USE_AS_PATH_SOURCE_TYPES = new Set([
     'text',
     'textArea',
@@ -180,6 +190,9 @@ function validateVirtualFields(collection) {
  *  - A collection may not set both `tree: true` and `orderable: true`. A
  *    document-tree owns ordering per-parent on the tree edge, so
  *    `byline_documents.order_key` is inert for it.
+ *  - Each `listSearch` entry must name an existing top-level field whose
+ *    type is persisted to the text store (the admin list-view search box
+ *    is an `ILIKE` over `store_text`), and the field may not be virtual.
  *  - `virtual` fields must satisfy the constraints in
  *    {@link validateVirtualFields} (optional-or-default, no counters, no
  *    upload fields, not referenced by useAsTitle / useAsPath / search).
@@ -205,6 +218,18 @@ export function validateCollections(collections) {
                 throw new Error(`Collection "${collection.path}" sets \`useAsPath: '${collection.useAsPath}'\` but field "${collection.useAsPath}" has type "${source.type}". Supported source types: ${[...USE_AS_PATH_SOURCE_TYPES].join(', ')}.`);
             }
         }
+        for (const name of collection.listSearch ?? []) {
+            const source = collection.fields.find((f) => 'name' in f && f.name === name);
+            if (source == null) {
+                throw new Error(`Collection "${collection.path}" names '${name}' in \`listSearch\` but no top-level field with that name exists.`);
+            }
+            if (!LIST_SEARCH_SOURCE_TYPES.has(source.type)) {
+                throw new Error(`Collection "${collection.path}" names '${name}' in \`listSearch\` but field "${name}" has type "${source.type}". The list-view search box matches text-store fields only (${[...LIST_SEARCH_SOURCE_TYPES].join(', ')}).`);
+            }
+            if (source.virtual === true) {
+                throw new Error(`Collection "${collection.path}" names virtual field '${name}' in \`listSearch\` — list-view search reads persisted values, which virtual fields never have.`);
+            }
+        }
         if (collection.advertiseLocales === true && !hasLocalizedField(collection.fields)) {
             throw new Error(`Collection "${collection.path}" sets \`advertiseLocales: true\` but has no localized fields. The available-locales control advertises content locales, which is only meaningful when at least one field is \`localized\`.`);
         }

package/dist/config/validate-collections.test.node.js

@@ -410,4 +410,46 @@ describe('validateCollections', () => {
         };
         expect(() => validateCollections([collection])).not.toThrow();
     });
+    it('accepts listSearch naming text-store fields', () => {
+        const collection = {
+            ...baseCollection,
+            listSearch: ['title', 'summary', 'kind'],
+            fields: [
+                { name: 'title', label: 'Title', type: 'text' },
+                { name: 'summary', label: 'Summary', type: 'textArea' },
+                {
+                    name: 'kind',
+                    label: 'Kind',
+                    type: 'select',
+                    options: [{ label: 'A', value: 'a' }],
+                },
+            ],
+        };
+        expect(() => validateCollections([collection])).not.toThrow();
+    });
+    it('rejects a listSearch entry referencing a missing field', () => {
+        expect(() => validateCollections([{ ...baseCollection, listSearch: ['nonexistent'] }])).toThrow(/listSearch.*no top-level field/s);
+    });
+    it('rejects a listSearch entry referencing a non-text-store field', () => {
+        const collection = {
+            ...baseCollection,
+            listSearch: ['count'],
+            fields: [
+                { name: 'title', label: 'Title', type: 'text' },
+                { name: 'count', label: 'Count', type: 'integer' },
+            ],
+        };
+        expect(() => validateCollections([collection])).toThrow(/text-store fields only/);
+    });
+    it('rejects a listSearch entry referencing a virtual field', () => {
+        const collection = {
+            ...baseCollection,
+            listSearch: ['ephemeral'],
+            fields: [
+                { name: 'title', label: 'Title', type: 'text' },
+                { name: 'ephemeral', label: 'Ephemeral', type: 'text', virtual: true, optional: true },
+            ],
+        };
+        expect(() => validateCollections([collection])).toThrow(/listSearch.*virtual/s);
+    });
 });

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.20.2",
+  "version": "3.20.4",
   "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.4"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",