@byline/core 3.20.3 → 3.20.4

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-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.3",
+  "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.3"
+    "@byline/auth": "3.20.4"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",