@byline/richtext-lexical 3.14.0 → 3.15.0

package/dist/field/lexical-to-text.d.ts

@@ -0,0 +1,12 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Extract indexable plain text from a (possibly null / stringified)
+ * serialized Lexical editor state. Returns `''` when there is no content.
+ */
+export declare function lexicalToText(value: unknown): string;

package/dist/field/lexical-to-text.js

@@ -0,0 +1,82 @@
+const INLINE_CONTAINER_TYPES = new Set([
+    'link',
+    'autolink'
+]);
+const SKIP_TYPES = new Set([
+    'youtube',
+    'vimeo',
+    'horizontalrule',
+    'tab'
+]);
+class LexicalTextConverter {
+    addText(text) {
+        if (null != text) this.current += text;
+    }
+    endParagraph() {
+        const p = this.current.trim();
+        if (p.length > 0) this.paragraphs.push(p);
+        this.current = '';
+    }
+    getText() {
+        this.endParagraph();
+        return this.paragraphs.join('\n');
+    }
+    addBlockNodes(nodes) {
+        this.endParagraph();
+        for (const node of nodes ?? [])this.addNode(node);
+        this.endParagraph();
+    }
+    addInlineNodes(nodes) {
+        for (const node of nodes ?? [])this.addNode(node);
+    }
+    addNode(node) {
+        const type = node.type;
+        if ('text' === type || 'code-highlight' === type) return void this.addText(node.text);
+        if ('linebreak' === type) return void this.endParagraph();
+        if ('admonition' === type) {
+            this.endParagraph();
+            this.addText(node.title);
+            this.endParagraph();
+            this.addText(lexicalToText(node.content?.editorState).trim());
+            this.endParagraph();
+            return;
+        }
+        if ('inline-image' === type) {
+            this.endParagraph();
+            this.addText(node.altText);
+            if (node.showCaption) {
+                this.endParagraph();
+                this.addText(lexicalToText(node.caption?.editorState).trim());
+            }
+            this.endParagraph();
+            return;
+        }
+        if (null != type && SKIP_TYPES.has(type)) return;
+        if (null != type && INLINE_CONTAINER_TYPES.has(type)) return void this.addInlineNodes(node.children);
+        if (Array.isArray(node.children)) this.addBlockNodes(node.children);
+    }
+    constructor(){
+        this.paragraphs = [];
+        this.current = '';
+    }
+}
+function resolveRoot(value) {
+    let v = value;
+    if ('string' == typeof v) try {
+        v = JSON.parse(v);
+    } catch  {
+        return null;
+    }
+    if ('object' != typeof v || null === v) return null;
+    const obj = v;
+    const root = obj.root ?? obj;
+    return 'root' === root.type ? root : null;
+}
+function lexicalToText(value) {
+    const root = resolveRoot(value);
+    if (null == root) return '';
+    const converter = new LexicalTextConverter();
+    converter.addBlockNodes(root.children);
+    return converter.getText();
+}
+export { lexicalToText };

package/dist/server.d.ts

@@ -36,9 +36,10 @@
  * ```
  */
 import type { BylineClient } from '@byline/client';
-import type { RichTextEmbedFn, RichTextPopulateFn, RichTextToMarkdownFn } from '@byline/core';
+import type { RichTextEmbedFn, RichTextPopulateFn, RichTextToMarkdownFn, RichTextToTextFn } from '@byline/core';
 import { type LexicalNodeVisitor } from './field/lexical-populate-shared';
 export { defaultEditorConfig } from './field/config/default';
+export { lexicalToText } from './field/lexical-to-text';
 export { type LexicalToMarkdownOptions, type LexicalToMarkdownResult, type LexicalToMarkdownWarning, lexicalToMarkdown, } from './field/markdown/lexical-to-markdown';
 import { type LexicalToMarkdownOptions } from './field/markdown/lexical-to-markdown';
 export { inlineImageVisitor } from './field/extensions/inline-image/populate';
@@ -97,4 +98,12 @@ export declare function lexicalEditorPopulateServer(options: LexicalServerOption
  * for the dialect contract (GFM alerts, lossy-OK).
  */
 export declare function lexicalEditorToMarkdownServer(options?: LexicalToMarkdownOptions): RichTextToMarkdownFn;
+/**
+ * Plain-text extractor for search indexing, shaped for
+ * `ServerConfig.fields.richText.toText`. Pure and synchronous — flattens
+ * the stored editor JSON to indexable plain text via `lexicalToText` (a
+ * recursive text-node accumulator, no markdown). Consumed by core's
+ * `buildSearchDocument` to feed a collection's searchable `body`.
+ */
+export declare function lexicalEditorToTextServer(): RichTextToTextFn;
 export declare function lexicalEditorEmbedServer(options: LexicalServerOptions): RichTextEmbedFn;

package/dist/server.js

@@ -2,6 +2,7 @@ import { inlineImageVisitor } from "./field/extensions/inline-image/populate.js"
 import { linkVisitor } from "./field/extensions/link/populate.js";
 import { runLexicalPopulate } from "./field/lexical-populate-shared.js";
 import { lexicalToMarkdown } from "./field/markdown/lexical-to-markdown.js";
+import { lexicalToText } from "./field/lexical-to-text.js";
 function lexicalEditorPopulateServer(options) {
     const visitors = options.visitors ?? [
         inlineImageVisitor,
@@ -21,6 +22,9 @@ function lexicalEditorPopulateServer(options) {
 function lexicalEditorToMarkdownServer(options = {}) {
     return (ctx)=>lexicalToMarkdown(ctx.value, options).markdown;
 }
+function lexicalEditorToTextServer() {
+    return (ctx)=>lexicalToText(ctx.value);
+}
 function lexicalEditorEmbedServer(options) {
     const visitors = options.visitors ?? [
         inlineImageVisitor,
@@ -38,4 +42,4 @@ function lexicalEditorEmbedServer(options) {
     };
 }
 export { defaultEditorConfig } from "./field/config/default.js";
-export { inlineImageVisitor, lexicalEditorEmbedServer, lexicalEditorPopulateServer, lexicalEditorToMarkdownServer, lexicalToMarkdown, linkVisitor };
+export { inlineImageVisitor, lexicalEditorEmbedServer, lexicalEditorPopulateServer, lexicalEditorToMarkdownServer, lexicalEditorToTextServer, lexicalToMarkdown, lexicalToText, linkVisitor };

package/package.json

@@ -3,7 +3,7 @@
   "private": false,
   "type": "module",
   "license": "MPL-2.0",
-  "version": "3.14.0",
+  "version": "3.15.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -77,10 +77,10 @@
     "npm-run-all": "^4.1.5",
     "prism-react-renderer": "^2.4.1",
     "react-error-boundary": "^6.1.1",
-    "@byline/core": "3.14.0",
-    "@byline/client": "3.14.0",
-    "@byline/admin": "3.14.0",
-    "@byline/ui": "3.14.0"
+    "@byline/core": "3.15.0",
+    "@byline/client": "3.15.0",
+    "@byline/ui": "3.15.0",
+    "@byline/admin": "3.15.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/field/lexical-to-text.test.node.ts

@@ -0,0 +1,75 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import { lexicalToText } from './lexical-to-text'
+
+const state = (children: unknown[]) => ({ root: { type: 'root', children } })
+
+const para = (text: string) => ({
+  type: 'paragraph',
+  children: [{ type: 'text', text }],
+})
+
+describe('lexicalToText', () => {
+  it('returns empty string for null / undefined / non-editor values', () => {
+    expect(lexicalToText(null)).toBe('')
+    expect(lexicalToText(undefined)).toBe('')
+    expect(lexicalToText(42)).toBe('')
+    expect(lexicalToText({ not: 'an editor state' })).toBe('')
+  })
+
+  it('parses a stringified editor state', () => {
+    expect(lexicalToText(JSON.stringify(state([para('Hello world')])))).toBe('Hello world')
+  })
+
+  it('joins block-level nodes with newlines', () => {
+    expect(lexicalToText(state([para('First'), para('Second')]))).toBe('First\nSecond')
+  })
+
+  it('concatenates inline text and follows link children', () => {
+    const node = {
+      type: 'paragraph',
+      children: [
+        { type: 'text', text: 'See ' },
+        { type: 'link', children: [{ type: 'text', text: 'the docs' }] },
+        { type: 'text', text: ' now.' },
+      ],
+    }
+    expect(lexicalToText(state([node]))).toBe('See the docs now.')
+  })
+
+  it('recurses into headings, lists, and quotes', () => {
+    const heading = { type: 'heading', tag: 'h1', children: [{ type: 'text', text: 'Title' }] }
+    const list = {
+      type: 'list',
+      children: [
+        { type: 'listitem', children: [{ type: 'text', text: 'one' }] },
+        { type: 'listitem', children: [{ type: 'text', text: 'two' }] },
+      ],
+    }
+    expect(lexicalToText(state([heading, list]))).toBe('Title\none\ntwo')
+  })
+
+  it('skips embed-only nodes (youtube/vimeo)', () => {
+    expect(
+      lexicalToText(state([para('before'), { type: 'youtube', videoID: 'x' }, para('after')]))
+    ).toBe('before\nafter')
+  })
+
+  it('extracts nested editor states from inline-image captions', () => {
+    const node = {
+      type: 'inline-image',
+      altText: 'A diagram',
+      showCaption: true,
+      caption: { editorState: state([para('Figure 1')]) },
+    }
+    expect(lexicalToText(state([node]))).toBe('A diagram\nFigure 1')
+  })
+})

package/src/field/lexical-to-text.ts

@@ -0,0 +1,145 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * One-way Lexical → plain-text extractor for search indexing — flattens a
+ * stored `SerializedEditorState` to indexable plain text via a recursive
+ * text-node accumulator. No markdown syntax, no link URLs, no images: just
+ * the words, with paragraph breaks between block-level nodes.
+ *
+ * Registered through `ServerConfig.fields.richText.toText` (see
+ * `lexicalEditorToTextServer` in `../server`) and consumed by core's
+ * `buildSearchDocument` to feed a collection's searchable `body`. Walks the
+ * stored JSON directly — no editor instantiation, no DOM, no DB reads —
+ * exactly like the markdown serializer. Lossy by contract.
+ */
+
+type AnyNode = {
+  type?: string
+  text?: string
+  children?: AnyNode[]
+  // Nested editor states (admonition body, inline-image caption).
+  content?: { editorState?: unknown }
+  caption?: { editorState?: unknown }
+  title?: string
+  altText?: string
+  showCaption?: boolean
+}
+
+/** Inline node types whose children continue the current paragraph. */
+const INLINE_CONTAINER_TYPES = new Set(['link', 'autolink'])
+
+/** Leaf / embed node types that contribute no indexable text. */
+const SKIP_TYPES = new Set(['youtube', 'vimeo', 'horizontalrule', 'tab'])
+
+class LexicalTextConverter {
+  private paragraphs: string[] = []
+  private current = ''
+
+  private addText(text: string | null | undefined): void {
+    if (text != null) this.current += text
+  }
+
+  private endParagraph(): void {
+    const p = this.current.trim()
+    if (p.length > 0) this.paragraphs.push(p)
+    this.current = ''
+  }
+
+  getText(): string {
+    this.endParagraph()
+    return this.paragraphs.join('\n')
+  }
+
+  /** Block-level children: flush before and after so blocks separate. */
+  addBlockNodes(nodes: AnyNode[] | null | undefined): void {
+    this.endParagraph()
+    for (const node of nodes ?? []) this.addNode(node)
+    this.endParagraph()
+  }
+
+  /** Inline children: continue the current paragraph. */
+  private addInlineNodes(nodes: AnyNode[] | null | undefined): void {
+    for (const node of nodes ?? []) this.addNode(node)
+  }
+
+  private addNode(node: AnyNode): void {
+    const type = node.type
+
+    if (type === 'text' || type === 'code-highlight') {
+      this.addText(node.text)
+      return
+    }
+    if (type === 'linebreak') {
+      this.endParagraph()
+      return
+    }
+    if (type === 'admonition') {
+      this.endParagraph()
+      this.addText(node.title)
+      this.endParagraph()
+      this.addText(lexicalToText(node.content?.editorState).trim())
+      this.endParagraph()
+      return
+    }
+    if (type === 'inline-image') {
+      this.endParagraph()
+      this.addText(node.altText)
+      if (node.showCaption) {
+        this.endParagraph()
+        this.addText(lexicalToText(node.caption?.editorState).trim())
+      }
+      this.endParagraph()
+      return
+    }
+    if (type != null && SKIP_TYPES.has(type)) return
+
+    if (type != null && INLINE_CONTAINER_TYPES.has(type)) {
+      this.addInlineNodes(node.children)
+      return
+    }
+    // Default: any node with children is treated as block-level (paragraph,
+    // heading, quote, code, list, listitem, table*, layout*, …). Unknown
+    // childless nodes contribute nothing.
+    if (Array.isArray(node.children)) {
+      this.addBlockNodes(node.children)
+    }
+  }
+}
+
+/**
+ * Resolve a stored value (a `SerializedEditorState`, its `root`, or a
+ * stringified version of either) to the root node, mirroring the markdown
+ * serializer's `resolveRoot`.
+ */
+function resolveRoot(value: unknown): AnyNode | null {
+  let v = value
+  if (typeof v === 'string') {
+    try {
+      v = JSON.parse(v)
+    } catch {
+      return null
+    }
+  }
+  if (typeof v !== 'object' || v === null) return null
+  const obj = v as { root?: AnyNode } & AnyNode
+  const root = (obj.root ?? obj) as AnyNode
+  return root.type === 'root' ? root : null
+}
+
+/**
+ * Extract indexable plain text from a (possibly null / stringified)
+ * serialized Lexical editor state. Returns `''` when there is no content.
+ */
+export function lexicalToText(value: unknown): string {
+  const root = resolveRoot(value)
+  if (root == null) return ''
+  const converter = new LexicalTextConverter()
+  converter.addBlockNodes(root.children)
+  return converter.getText()
+}

package/src/server.ts

@@ -44,6 +44,7 @@ import type {
   RichTextPopulateContext,
   RichTextPopulateFn,
   RichTextToMarkdownFn,
+  RichTextToTextFn,
 } from '@byline/core'
 
 import { inlineImageVisitor } from './field/extensions/inline-image/populate'
@@ -57,6 +58,7 @@ import { type LexicalNodeVisitor, runLexicalPopulate } from './field/lexical-pop
 // their CSS imports; the `/server` subpath stays React-free.
 // ---------------------------------------------------------------------------
 export { defaultEditorConfig } from './field/config/default'
+export { lexicalToText } from './field/lexical-to-text'
 export {
   type LexicalToMarkdownOptions,
   type LexicalToMarkdownResult,
@@ -64,6 +66,7 @@ export {
   lexicalToMarkdown,
 } from './field/markdown/lexical-to-markdown'
 
+import { lexicalToText } from './field/lexical-to-text'
 import {
   type LexicalToMarkdownOptions,
   lexicalToMarkdown,
@@ -147,6 +150,17 @@ export function lexicalEditorToMarkdownServer(
   return (ctx) => lexicalToMarkdown(ctx.value, options).markdown
 }
 
+/**
+ * Plain-text extractor for search indexing, shaped for
+ * `ServerConfig.fields.richText.toText`. Pure and synchronous — flattens
+ * the stored editor JSON to indexable plain text via `lexicalToText` (a
+ * recursive text-node accumulator, no markdown). Consumed by core's
+ * `buildSearchDocument` to feed a collection's searchable `body`.
+ */
+export function lexicalEditorToTextServer(): RichTextToTextFn {
+  return (ctx) => lexicalToText(ctx.value)
+}
+
 export function lexicalEditorEmbedServer(options: LexicalServerOptions): RichTextEmbedFn {
   const visitors = options.visitors ?? [inlineImageVisitor, linkVisitor]
   return async (ctx: RichTextEmbedContext): Promise<void> => {