@byline/richtext-lexical 3.20.0 → 3.20.2

package/dist/field/config/resolve-editor-config.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 type { EditorConfig } from './types';
+/**
+ * Merge a schema field's `editorConfig` over the registered editor's
+ * config (baked at registration via `lexicalEditor()`, or the package
+ * default).
+ *
+ * This is a MERGE, not a pick-one precedence — each layer can only express
+ * what its side is allowed to carry, so whole-object precedence would
+ * silently discard the rest:
+ *
+ *   - The field layer (schema side) is JSON-safe: `settings` + `lexical`
+ *     only, never `extensions`. It is the most specific layer, so its
+ *     values win — but ONLY for the keys it can express. Settings merge
+ *     per-key (including `settings.options`), so a field config produced
+ *     by a partial override keeps the registered layer's remaining flags.
+ *   - The registered layer is the only one that can carry an `extensions`
+ *     graph. Before this merge existed, a schema-side `editorConfig`
+ *     replaced the baked config wholesale, throwing away registration-time
+ *     extension changes (an added AI extension, removed Insert-menu
+ *     extensions, …) and silently falling back to the built-in list.
+ *
+ * Returns the registered config as-is when the field carries no
+ * `editorConfig`. Never mutates either input.
+ */
+export declare function resolveEditorConfig(fieldConfig: EditorConfig | undefined, registeredConfig: EditorConfig): EditorConfig;

package/dist/field/config/resolve-editor-config.js

@@ -0,0 +1,16 @@
+function resolveEditorConfig(fieldConfig, registeredConfig) {
+    if (null == fieldConfig) return registeredConfig;
+    return {
+        settings: {
+            ...registeredConfig.settings,
+            ...fieldConfig.settings,
+            options: {
+                ...registeredConfig.settings.options,
+                ...fieldConfig.settings?.options
+            }
+        },
+        lexical: fieldConfig.lexical ?? registeredConfig.lexical,
+        extensions: fieldConfig.extensions ?? registeredConfig.extensions
+    };
+}
+export { resolveEditorConfig };

package/dist/field/editor-context.js

@@ -16,9 +16,11 @@ function EditorContext(props) {
     const editable = true !== readOnly;
     const rootExtension = useMemo(()=>{
         const extensionsList = editorConfig.extensions ?? defaultExtensionsList();
-        const dependencies = extensionsList.clone().configure(InlineImageExtension, {
+        const configured = extensionsList.clone();
+        if (configured.has(InlineImageExtension)) configured.configure(InlineImageExtension, {
             collection: editorConfig.settings.inlineImageUploadCollection
-        }).toArray();
+        });
+        const dependencies = configured.toArray();
         return defineExtension({
             name: '[root]',
             namespace: editorConfig.lexical.namespace,

package/dist/lexical-editor.d.ts

@@ -20,9 +20,11 @@ type ConfigureFn = (config: LexicalEditorConfigureInput) => LexicalEditorConfigu
 /**
  * Returns a `RichTextEditorComponent` with editor settings baked in. Use
  * this at the registration site in your admin config when you want to
- * customise the editor across the whole installation; per-field
- * overrides via `RichTextField.editorConfig` continue to take precedence
- * at render time.
+ * customise the editor across the whole installation. Per-field overrides
+ * via `RichTextField.editorConfig` are MERGED over the baked config at
+ * render time (settings win per-key, most specific first) — but the baked
+ * `extensions` graph survives, since schema-side configs cannot carry
+ * extension references. See `resolveEditorConfig`.
  *
  * The returned component is lazy: the editor module graph (RichTextField
  * + every built-in extension + the Lexical core) is dynamically imported

package/dist/richtext-field.js

@@ -4,6 +4,7 @@ import { ErrorText, Label } from "@byline/ui/react";
 import classnames from "classnames";
 import { defaultEditorConfig } from "./field/config/default.js";
 import { defaultExtensionsList } from "./field/config/default-extensions.js";
+import { resolveEditorConfig } from "./field/config/resolve-editor-config.js";
 import { EditorField } from "./field/editor-field.js";
 import richtext_field_module from "./richtext-field.module.js";
 const RichTextField = ({ field, value, defaultValue, editorConfig, readonly = false, instanceKey, onChange, path, locale, featureBeforeEditor, featureAfterEditor, featureChildren })=>{
@@ -13,7 +14,7 @@ const RichTextField = ({ field, value, defaultValue, editorConfig, readonly = fa
     const incomingValue = value ?? fieldValue;
     const incomingDefault = defaultValue;
     const fieldId = instanceKey ? `${field.name}-${instanceKey}` : field.name;
-    const resolved = field.editorConfig ?? editorConfig ?? defaultEditorConfig;
+    const resolved = resolveEditorConfig(field.editorConfig, editorConfig ?? defaultEditorConfig);
     const baseEditorConfig = null != resolved.extensions ? resolved : {
         ...resolved,
         extensions: defaultExtensionsList()

package/package.json

@@ -3,7 +3,7 @@
   "private": false,
   "type": "module",
   "license": "MPL-2.0",
-  "version": "3.20.0",
+  "version": "3.20.2",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -73,10 +73,10 @@
     "lexical": "0.46.0",
     "npm-run-all": "^4.1.5",
     "react-error-boundary": "^6.1.2",
-    "@byline/admin": "3.20.0",
-    "@byline/core": "3.20.0",
-    "@byline/ui": "3.20.0",
-    "@byline/client": "3.20.0"
+    "@byline/core": "3.20.2",
+    "@byline/admin": "3.20.2",
+    "@byline/client": "3.20.2",
+    "@byline/ui": "3.20.2"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/field/config/extensions-list.test.node.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 type { AnyLexicalExtensionArgument } from '@lexical/extension'
+import { describe, expect, it } from 'vitest'
+
+import { ExtensionsList } from './extensions-list'
+
+// Structural stand-ins — ExtensionsList compares by `.name`, so plain
+// objects are sufficient and keep the heavy extension classes (React,
+// Lexical nodes) out of this node-mode test.
+const extA = { name: 'test/A' } as unknown as AnyLexicalExtensionArgument
+const extB = { name: 'test/B' } as unknown as AnyLexicalExtensionArgument
+
+describe('ExtensionsList', () => {
+  it('remove() by name string drops the entry; has() reflects it', () => {
+    const list = new ExtensionsList([extA, extB])
+    expect(list.has('test/A')).toBe(true)
+    list.remove('test/A')
+    expect(list.has('test/A')).toBe(false)
+    expect(list.has('test/B')).toBe(true)
+  })
+
+  it('configure() upserts — documented behaviour: absent extension is ADDED', () => {
+    const list = new ExtensionsList([extB])
+    // biome-ignore lint/suspicious/noExplicitAny: structural stand-in
+    list.configure(extA as any, {})
+    expect(list.has('test/A')).toBe(true)
+  })
+
+  it('REGRESSION: callers forwarding settings must gate configure() on has() — the clone survives a prior remove', () => {
+    // Mirrors editor-context.tsx: settings forwarding used to call
+    // `.configure(InlineImageExtension, …)` unconditionally, and the
+    // upsert resurrected an extension the registration had deliberately
+    // removed. The gated pattern must leave the removal intact.
+    const list = new ExtensionsList([extA, extB])
+    list.remove('test/A')
+
+    const configured = list.clone()
+    if (configured.has('test/A')) {
+      // biome-ignore lint/suspicious/noExplicitAny: structural stand-in
+      configured.configure(extA as any, {})
+    }
+
+    expect(configured.has('test/A')).toBe(false)
+    expect(configured.toArray().length).toBe(1)
+  })
+
+  it('clone() is independent — mutations do not leak back', () => {
+    const list = new ExtensionsList([extA, extB])
+    const copy = list.clone()
+    copy.remove('test/B')
+    expect(list.has('test/B')).toBe(true)
+    expect(copy.has('test/B')).toBe(false)
+  })
+})

package/src/field/config/resolve-editor-config.test.node.ts

@@ -0,0 +1,101 @@
+/**
+ * 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 { defaultEditorConfig } from './default'
+import { resolveEditorConfig } from './resolve-editor-config'
+import type { EditorConfig } from './types'
+
+/**
+ * Minimal stand-in for an ExtensionsList — resolveEditorConfig only passes
+ * the reference through, so identity is all these tests need.
+ */
+const fakeExtensions = { items: ['ext-a', 'ext-b'] } as unknown as NonNullable<
+  EditorConfig['extensions']
+>
+
+function clone(config: EditorConfig): EditorConfig {
+  return structuredClone(config)
+}
+
+describe('resolveEditorConfig', () => {
+  it('returns the registered config as-is when the field carries none', () => {
+    const registered = { ...clone(defaultEditorConfig), extensions: fakeExtensions }
+    expect(resolveEditorConfig(undefined, registered)).toBe(registered)
+  })
+
+  it('field settings win per-key; unspecified registered settings survive', () => {
+    const registered = clone(defaultEditorConfig)
+    registered.settings.options.markdownToggle = true
+    registered.settings.placeholderText = 'registered placeholder'
+
+    const fieldConfig = clone(defaultEditorConfig)
+    fieldConfig.settings.options.textStyle = false
+    fieldConfig.settings.options.undoRedo = false
+
+    const resolved = resolveEditorConfig(fieldConfig, registered)
+    // Field's flags applied…
+    expect(resolved.settings.options.textStyle).toBe(false)
+    expect(resolved.settings.options.undoRedo).toBe(false)
+    // …and since schema-side configs are complete objects, its values win
+    // for every key it carries (markdownToggle false from the default seed).
+    expect(resolved.settings.options.markdownToggle).toBe(false)
+    expect(resolved.settings.placeholderText).toBe(fieldConfig.settings.placeholderText)
+  })
+
+  it('REGRESSION: a schema-side settings-only config must not discard the registered extensions graph', () => {
+    // Before the merge existed, `field.editorConfig ?? registered` replaced
+    // the whole object: a compact/minimal settings preset baked into the
+    // schema silently dropped registration-time extension changes (removed
+    // Insert-menu extensions, an added AI extension) and the editor fell
+    // back to the built-in list.
+    const registered = { ...clone(defaultEditorConfig), extensions: fakeExtensions }
+    const fieldConfig = clone(defaultEditorConfig) // settings-only, no extensions
+
+    const resolved = resolveEditorConfig(fieldConfig, registered)
+    expect(resolved.extensions).toBe(fakeExtensions)
+  })
+
+  it('a field-carried extensions graph (advanced/manual) still wins', () => {
+    const fieldExtensions = { items: ['field-ext'] } as unknown as NonNullable<
+      EditorConfig['extensions']
+    >
+    const registered = { ...clone(defaultEditorConfig), extensions: fakeExtensions }
+    const fieldConfig = { ...clone(defaultEditorConfig), extensions: fieldExtensions }
+
+    const resolved = resolveEditorConfig(fieldConfig, registered)
+    expect(resolved.extensions).toBe(fieldExtensions)
+  })
+
+  it('lexical config: field wins when present, registered otherwise', () => {
+    const registered = clone(defaultEditorConfig)
+    const fieldConfig = clone(defaultEditorConfig)
+
+    const withField = resolveEditorConfig(fieldConfig, registered)
+    expect(withField.lexical).toBe(fieldConfig.lexical)
+
+    const withoutFieldLexical = resolveEditorConfig(
+      { settings: fieldConfig.settings } as EditorConfig,
+      registered
+    )
+    expect(withoutFieldLexical.lexical).toBe(registered.lexical)
+  })
+
+  it('does not mutate either input', () => {
+    const registered = { ...clone(defaultEditorConfig), extensions: fakeExtensions }
+    const fieldConfig = clone(defaultEditorConfig)
+    const registeredSnapshot = JSON.stringify({ ...registered, extensions: undefined })
+    const fieldSnapshot = JSON.stringify(fieldConfig)
+
+    resolveEditorConfig(fieldConfig, registered)
+
+    expect(JSON.stringify({ ...registered, extensions: undefined })).toBe(registeredSnapshot)
+    expect(JSON.stringify(fieldConfig)).toBe(fieldSnapshot)
+  })
+})

package/src/field/config/resolve-editor-config.ts

@@ -0,0 +1,53 @@
+/**
+ * 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 type { EditorConfig } from './types'
+
+/**
+ * Merge a schema field's `editorConfig` over the registered editor's
+ * config (baked at registration via `lexicalEditor()`, or the package
+ * default).
+ *
+ * This is a MERGE, not a pick-one precedence — each layer can only express
+ * what its side is allowed to carry, so whole-object precedence would
+ * silently discard the rest:
+ *
+ *   - The field layer (schema side) is JSON-safe: `settings` + `lexical`
+ *     only, never `extensions`. It is the most specific layer, so its
+ *     values win — but ONLY for the keys it can express. Settings merge
+ *     per-key (including `settings.options`), so a field config produced
+ *     by a partial override keeps the registered layer's remaining flags.
+ *   - The registered layer is the only one that can carry an `extensions`
+ *     graph. Before this merge existed, a schema-side `editorConfig`
+ *     replaced the baked config wholesale, throwing away registration-time
+ *     extension changes (an added AI extension, removed Insert-menu
+ *     extensions, …) and silently falling back to the built-in list.
+ *
+ * Returns the registered config as-is when the field carries no
+ * `editorConfig`. Never mutates either input.
+ */
+export function resolveEditorConfig(
+  fieldConfig: EditorConfig | undefined,
+  registeredConfig: EditorConfig
+): EditorConfig {
+  if (fieldConfig == null) return registeredConfig
+  return {
+    settings: {
+      ...registeredConfig.settings,
+      ...fieldConfig.settings,
+      options: {
+        ...registeredConfig.settings.options,
+        ...fieldConfig.settings?.options,
+      },
+    },
+    lexical: fieldConfig.lexical ?? registeredConfig.lexical,
+    // Schema-side configs never carry extensions (not JSON-safe); the
+    // registered editor's graph survives a field-level settings override.
+    extensions: fieldConfig.extensions ?? registeredConfig.extensions,
+  }
+}

package/src/field/editor-context.tsx

@@ -80,14 +80,19 @@ export function EditorContext(props: {
     const extensionsList = editorConfig.extensions ?? defaultExtensionsList()
 
     // Forward the inline-image upload collection from the settings facade
-    // onto the InlineImageExtension's typed config, but only when the
-    // user hasn't already configured the extension explicitly.
-    const dependencies = extensionsList
-      .clone()
-      .configure(InlineImageExtension, {
+    // onto the InlineImageExtension's typed config — but ONLY when the
+    // extension is actually present. `configure()` has upsert semantics
+    // (absent → added), so an ungated call here silently resurrected
+    // InlineImageExtension on every editor build for registrations that
+    // had deliberately removed it via
+    // `lexicalEditor((c) => c.extensions.remove(builtInExtensions.InlineImage))`.
+    const configured = extensionsList.clone()
+    if (configured.has(InlineImageExtension)) {
+      configured.configure(InlineImageExtension, {
         collection: editorConfig.settings.inlineImageUploadCollection,
       })
-      .toArray()
+    }
+    const dependencies = configured.toArray()
 
     return defineExtension({
       name: '[root]',

package/src/lexical-editor.tsx

@@ -71,9 +71,11 @@ function loadEditorBundle(): Promise<EditorBundle> {
 /**
  * Returns a `RichTextEditorComponent` with editor settings baked in. Use
  * this at the registration site in your admin config when you want to
- * customise the editor across the whole installation; per-field
- * overrides via `RichTextField.editorConfig` continue to take precedence
- * at render time.
+ * customise the editor across the whole installation. Per-field overrides
+ * via `RichTextField.editorConfig` are MERGED over the baked config at
+ * render time (settings win per-key, most specific first) — but the baked
+ * `extensions` graph survives, since schema-side configs cannot carry
+ * extension references. See `resolveEditorConfig`.
  *
  * The returned component is lazy: the editor module graph (RichTextField
  * + every built-in extension + the Lexical core) is dynamically imported

package/src/richtext-field.tsx

@@ -15,6 +15,7 @@ import cx from 'classnames'
 
 import { defaultEditorConfig } from './field/config/default'
 import { defaultExtensionsList } from './field/config/default-extensions'
+import { resolveEditorConfig } from './field/config/resolve-editor-config'
 import { EditorField } from './field/editor-field'
 import styles from './richtext-field.module.css'
 import type { EditorConfig } from './field/config/types'
@@ -70,18 +71,20 @@ export const RichTextField = ({
 
   const fieldId = instanceKey ? `${field.name}-${instanceKey}` : field.name
 
-  // Resolve the editor config with field-level priority:
-  //   1. `field.editorConfig` — set on the schema field itself (most specific).
-  //   2. `editorConfig` prop  — baked in at registration via `lexicalEditor()`.
-  //   3. `defaultEditorConfig` — package default.
-  // The schema-level value is typed as `unknown` at the `@byline/core` boundary,
-  // so the cast lives here where the Lexical config shape is known.
-  const resolved: EditorConfig =
-    (field.editorConfig as EditorConfig | undefined) ?? editorConfig ?? defaultEditorConfig
-  // Schema-side configs and the server-safe `defaultEditorConfig` carry no
-  // `extensions` field — extension references aren't JSON-safe. Materialise
-  // the package's client-only default list when one isn't already present so
-  // every render has a complete graph to feed `EditorContext`.
+  // Resolve the editor config by MERGING the schema field's `editorConfig`
+  // (settings-only, most specific) over the registered editor's config
+  // (baked via `lexicalEditor()`, the only layer that can carry an
+  // `extensions` graph) — see `resolveEditorConfig` for the full rationale.
+  // The schema-level value is typed as `unknown` at the `@byline/core`
+  // boundary, so the cast lives here where the Lexical config shape is known.
+  const resolved: EditorConfig = resolveEditorConfig(
+    field.editorConfig as EditorConfig | undefined,
+    editorConfig ?? defaultEditorConfig
+  )
+  // The server-safe `defaultEditorConfig` carries no `extensions` field —
+  // extension references aren't JSON-safe. Materialise the package's
+  // client-only default list when one isn't already present so every render
+  // has a complete graph to feed `EditorContext`.
   const baseEditorConfig: EditorConfig =
     resolved.extensions != null ? resolved : { ...resolved, extensions: defaultExtensionsList() }