@byline/core 3.15.0 → 3.15.2

package/dist/services/build-search-document.d.ts

@@ -5,7 +5,36 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import type { CollectionDefinition, RichTextToTextFn, SearchDocument } from '../@types/index.js';
+/**
+ * `buildSearchDocument` — the document-grain assembler for the
+ * `SearchProvider` seam. Walks a collection's role-based `search` config
+ * against one locale-resolved document and emits a single, type-enriched
+ * `SearchDocument` for a driver to index. See
+ * `docs/05-reading-and-delivery/07-search.md`.
+ *
+ * Role-based and explicit: only the fields named in `search.{body,facets,
+ * filters}` are projected — nothing is auto-pulled, so unindexed content
+ * never leaks into the index. Core derives each field's `SearchFieldType`
+ * from the schema (the "type enrichment") so a driver can map it onto its
+ * own index without re-inspecting the collection definition.
+ *
+ * Pure and synchronous, like `documentToMarkdown`: the rich-text plain-text
+ * extractor is the editor-agnostic `toText` seam passed via options, and
+ * relation targets are resolved through a caller-supplied definition
+ * resolver — no globals, no DB reads. The caller is responsible for handing
+ * in a document whose `facets` relation fields are already populated (depth
+ * 1) with the target's identity + counter fields.
+ *
+ * `search.{facets,filters}` name **top-level** fields. `search.body` may name
+ * a top-level field of any kind: scalar / `richText` leaves index directly,
+ * and container fields (`blocks` / `array` / `group`) are walked recursively —
+ * every nested `richText` and text (`text` / `textArea`) leaf is flattened and
+ * concatenated into one searchable body string. Nested non-text leaves
+ * (`select`, `relation`, numbers, booleans, dates, files) are skipped so block
+ * configuration never pollutes the index — the same "content, not
+ * configuration" rule the markdown assembler follows.
+ */
+import { type CollectionDefinition, type RichTextToTextFn, type SearchDocument } from '../@types/index.js';
 /** A locale-resolved document fed to the assembler — one locale's view. */
 export interface SearchSourceDocument {
     /** Stable document id (shared across versions and locales). */

package/dist/services/build-search-document.js

@@ -25,9 +25,16 @@
  * in a document whose `facets` relation fields are already populated (depth
  * 1) with the target's identity + counter fields.
  *
- * v1 scope: `search.{body,facets,filters}` name **top-level** fields. Deep
- * paths into blocks / arrays are a follow-up.
+ * `search.{facets,filters}` name **top-level** fields. `search.body` may name
+ * a top-level field of any kind: scalar / `richText` leaves index directly,
+ * and container fields (`blocks` / `array` / `group`) are walked recursively —
+ * every nested `richText` and text (`text` / `textArea`) leaf is flattened and
+ * concatenated into one searchable body string. Nested non-text leaves
+ * (`select`, `relation`, numbers, booleans, dates, files) are skipped so block
+ * configuration never pollutes the index — the same "content, not
+ * configuration" rule the markdown assembler follows.
  */
+import { isArrayField, isBlocksField, isGroupField, } from '../@types/index.js';
 import { resolveIdentityField } from './populate.js';
 /**
  * Assemble one type-enriched `SearchDocument` from a locale-resolved
@@ -46,19 +53,7 @@ export function buildSearchDocument(doc, definition, options = {}) {
         const field = definition.fields.find((f) => f.name === name);
         if (field == null)
             continue;
-        let value;
-        if (field.type === 'richText') {
-            value = options.richTextToText
-                ? nonEmpty(options.richTextToText({
-                    value: resolveLocalized(fieldsData[name], locale),
-                    fieldPath: name,
-                    collectionPath: definition.path,
-                }))
-                : null;
-        }
-        else {
-            value = stringValue(resolveLocalized(fieldsData[name], locale));
-        }
+        const value = collectBodyText(field, fieldsData[name], definition.path, locale, options);
         if (value != null) {
             fields.push(withBoost({ name, type: 'text', role: 'body', value }, decl));
         }
@@ -113,6 +108,83 @@ function withBoost(field, decl) {
     const boost = typeof decl === 'string' ? undefined : decl.boost;
     return boost != null ? { ...field, boost } : field;
 }
+/** Text-bearing scalar leaves collected when walking into a container field. */
+const TEXT_LEAF_TYPES = new Set(['text', 'textArea']);
+/**
+ * Resolve a single `search.body` field to its searchable text. A scalar /
+ * `richText` leaf indexes directly (preserving the original top-level
+ * behaviour); a container (`group` / `array` / `blocks`) is walked
+ * recursively, flattening every nested text leaf into one string.
+ */
+function collectBodyText(field, rawValue, collectionPath, locale, options) {
+    const value = resolveLocalized(rawValue, locale);
+    if (isGroupField(field) || isArrayField(field) || isBlocksField(field)) {
+        return collectContainerText(field, value, collectionPath, locale, options);
+    }
+    return collectLeafText(field, value, collectionPath, options, /* permissive */ true);
+}
+/** Walk a container field, concatenating the text of its nested leaves. */
+function collectContainerText(field, value, collectionPath, locale, options) {
+    if (isGroupField(field)) {
+        return collectFieldSetText(field.fields, asRecord(value), collectionPath, locale, options);
+    }
+    if (isArrayField(field)) {
+        if (!Array.isArray(value))
+            return null;
+        return joinTexts(value.map((item) => collectFieldSetText(field.fields, asRecord(item), collectionPath, locale, options)));
+    }
+    // blocks: resolve each item's block definition by `_type`, then walk it.
+    if (!isBlocksField(field) || !Array.isArray(value))
+        return null;
+    const parts = [];
+    for (const item of value) {
+        const record = asRecord(item);
+        const block = field.blocks.find((b) => b.blockType === record._type);
+        if (block == null)
+            continue;
+        parts.push(collectFieldSetText(block.fields, record, collectionPath, locale, options));
+    }
+    return joinTexts(parts);
+}
+/** Collect text from every text-bearing leaf in a field set (one container level). */
+function collectFieldSetText(fields, data, collectionPath, locale, options) {
+    const parts = [];
+    for (const field of fields) {
+        const value = resolveLocalized(data?.[field.name], locale);
+        if (isGroupField(field) || isArrayField(field) || isBlocksField(field)) {
+            parts.push(collectContainerText(field, value, collectionPath, locale, options));
+        }
+        else {
+            // Nested leaves: only text-bearing types contribute — skip configuration
+            // (select, relation, numbers, booleans, dates, files).
+            parts.push(collectLeafText(field, value, collectionPath, options, /* permissive */ false));
+        }
+    }
+    return joinTexts(parts);
+}
+/**
+ * Extract text from a single leaf field. `richText` flows through the `toText`
+ * seam. For other scalars, `permissive` distinguishes a field the implementor
+ * named directly in `search.body` (index any scalar value, as before) from a
+ * leaf reached by walking into a container (restricted to text/textArea so
+ * block configuration values never leak into the index).
+ */
+function collectLeafText(field, value, collectionPath, options, permissive) {
+    if (field.type === 'richText') {
+        return options.richTextToText
+            ? nonEmpty(options.richTextToText({ value, fieldPath: field.name, collectionPath }))
+            : null;
+    }
+    if (permissive || TEXT_LEAF_TYPES.has(field.type)) {
+        return stringValue(value);
+    }
+    return null;
+}
+/** Join non-empty text parts with newlines, or null when there is nothing. */
+function joinTexts(parts) {
+    const filtered = parts.filter((p) => p != null && p.length > 0);
+    return filtered.length > 0 ? filtered.join('\n') : null;
+}
 /** A populated single relation or array of relations → array of envelopes. */
 function toEnvelopeArray(value) {
     if (Array.isArray(value))

package/dist/services/build-search-document.test.node.js

@@ -162,3 +162,114 @@ describe('buildSearchDocument', () => {
         expect(out.title).toBe('Restauration');
     });
 });
+// A collection whose prose lives inside a `blocks` field (the docs shape):
+// RichTextBlock (richText + a checkbox toggle) and PhotoBlock (text alt +
+// richText caption + a select + a relation). Mirrors the real-world case where
+// the searchable body is nested, not top-level.
+const blocksCollection = {
+    path: 'articles',
+    labels: { singular: 'Article', plural: 'Articles' },
+    useAsTitle: 'title',
+    fields: [
+        { name: 'title', label: 'Title', type: 'text', localized: true },
+        {
+            name: 'content',
+            label: 'Content',
+            type: 'blocks',
+            blocks: [
+                {
+                    blockType: 'richTextBlock',
+                    label: 'Richtext Block',
+                    fields: [
+                        { name: 'richText', label: 'Richtext', type: 'richText', localized: true },
+                        { name: 'constrainedWidth', label: 'Constrained', type: 'checkbox' },
+                    ],
+                },
+                {
+                    blockType: 'photoBlock',
+                    label: 'Photo Block',
+                    fields: [
+                        {
+                            name: 'display',
+                            label: 'Display',
+                            type: 'select',
+                            options: [
+                                { label: 'Default', value: 'default' },
+                                { label: 'Wide', value: 'wide' },
+                            ],
+                        },
+                        { name: 'photo', label: 'Photo', type: 'relation', targetCollection: 'media' },
+                        { name: 'alt', label: 'Alt', type: 'text' },
+                        { name: 'caption', label: 'Caption', type: 'richText', localized: true },
+                    ],
+                },
+            ],
+        },
+    ],
+    search: { body: [{ field: 'title', boost: 2 }, 'content'] },
+};
+describe('buildSearchDocument — container (blocks) body', () => {
+    function blockSource() {
+        return {
+            documentId: 'art-1',
+            locale: 'en',
+            status: 'published',
+            path: 'forests',
+            fields: {
+                title: 'Forests',
+                content: [
+                    {
+                        _type: 'richTextBlock',
+                        _id: 'b1',
+                        richText: { text: 'None of this is certain. But it reflects what we observed.' },
+                        constrainedWidth: true,
+                    },
+                    {
+                        _type: 'photoBlock',
+                        _id: 'b2',
+                        display: 'wide',
+                        photo: { _resolved: true, document: { fields: { title: 'A tree' } } },
+                        alt: 'A tall redwood',
+                        caption: { text: 'Old growth in the valley.' },
+                    },
+                ],
+            },
+        };
+    }
+    const doc = buildSearchDocument(blockSource(), blocksCollection, { richTextToText });
+    it('walks the blocks field and flattens nested richText + text leaves', () => {
+        const content = fieldByName(doc.fields, 'content');
+        expect(content).toMatchObject({ name: 'content', type: 'text', role: 'body' });
+        const value = content?.value;
+        expect(value).toContain('it reflects what we observed');
+        expect(value).toContain('A tall redwood');
+        expect(value).toContain('Old growth in the valley.');
+    });
+    it('skips nested non-text leaves (select, relation, checkbox) — no config noise', () => {
+        const value = fieldByName(doc.fields, 'content')?.value;
+        expect(value).not.toContain('wide'); // select
+        expect(value).not.toContain('A tree'); // relation target title
+        expect(value).not.toContain('true'); // checkbox
+    });
+    it('preserves top-level scalar body fields alongside the container', () => {
+        expect(fieldByName(doc.fields, 'title')).toMatchObject({ value: 'Forests', boost: 2 });
+    });
+    it('omits the container body field entirely when no toText seam is registered', () => {
+        // With no richText extractor, the only text-bearing leaves left are the
+        // PhotoBlock `alt` text.
+        const out = buildSearchDocument(blockSource(), blocksCollection);
+        const value = fieldByName(out.fields, 'content')?.value;
+        expect(value).toBe('A tall redwood');
+    });
+    it('produces no content field when a block field set has no text', () => {
+        const empty = {
+            ...blockSource(),
+            fields: {
+                title: 'Forests',
+                content: [{ _type: 'photoBlock', _id: 'b3', display: 'wide' }],
+            },
+        };
+        const out = buildSearchDocument(empty, blocksCollection, { richTextToText });
+        expect(fieldByName(out.fields, 'content')).toBeUndefined();
+    });
+});

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.15.0",
+  "version": "3.15.2",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -79,7 +79,7 @@
     "sharp": "^0.34.5",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@byline/auth": "3.15.0"
+    "@byline/auth": "3.15.2"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",