@byline/richtext-lexical 5.2.0 → 6.0.1

package/src/field/editor-context.regression.test.tsx

@@ -0,0 +1,124 @@
+import { act } from 'react'
+
+import { defineAdminConfig } from '@byline/core'
+import { MarkNode } from '@lexical/mark'
+import { OverflowNode } from '@lexical/overflow'
+import { HeadingNode } from '@lexical/rich-text'
+import type { LexicalEditor } from 'lexical'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { builtInExtensions } from './config/built-in-extension-names'
+import { defaultClientEditorConfig } from './config/default-extensions'
+import { EditorContext } from './editor-context'
+import { CoreNodesExtension } from './extensions/core-nodes/core-nodes-extension'
+import { READABLE_NODES } from './nodes'
+import { CaptureEditor } from './test-support/capture-editor'
+
+// biome-ignore lint/suspicious/noExplicitAny: React act environment flag
+;(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true
+
+// The editor's toolbar resolves the admin config unconditionally, so with
+// none registered the mount throws "Byline has not been configured yet".
+// Register a real minimal one rather than mocking `@byline/core` — the
+// same approach `@byline/admin`'s form tests take. It lives on a global,
+// so module scope runs it once.
+defineAdminConfig({
+  i18n: {
+    admin: { defaultLocale: 'en', locales: ['en'] },
+    content: { defaultLocale: 'en', locales: ['en'] },
+  },
+  collections: [
+    {
+      path: 'pages',
+      labels: { singular: 'Page', plural: 'Pages' },
+      fields: [{ name: 'title', label: 'Title', type: 'text' }],
+    },
+  ],
+})
+
+/**
+ * Mounts the REAL EditorContext. The shared jsdom builders in
+ * `test-support/build-test-editor.ts` compose their own root extension
+ * and so cannot see a blanket node list living in the shipped
+ * component — this test can, which is why the defect is pinned here.
+ */
+/** Every root mounted by this file, unmounted after each test. */
+const mounted: Array<{ root: Root; container: HTMLDivElement }> = []
+
+afterEach(async () => {
+  // Without this each test leaves a live editor and its listeners
+  // attached to the document, which leaks between tests.
+  for (const { root, container } of mounted.splice(0)) {
+    await act(async () => {
+      root.unmount()
+    })
+    container.remove()
+  }
+})
+
+async function mountEditor(removals: string[]): Promise<LexicalEditor> {
+  const extensions = defaultClientEditorConfig.extensions?.clone()
+  for (const name of removals) extensions.remove(name)
+
+  let editor: LexicalEditor | undefined
+  const container = document.createElement('div')
+  document.body.appendChild(container)
+  const root = createRoot(container)
+  mounted.push({ root, container })
+
+  // Async act: Lexical flushes listeners in a microtask and ToolbarPlugin
+  // sets state from them, so a synchronous act() leaves those updates
+  // outside its scope and React warns.
+  await act(async () => {
+    root.render(
+      <EditorContext
+        composerKey="regression"
+        editorConfig={{ ...defaultClientEditorConfig, extensions }}
+        onChange={() => {}}
+        readOnly={false}
+      >
+        <CaptureEditor
+          onEditor={(instance) => {
+            editor = instance
+          }}
+        />
+      </EditorContext>
+    )
+  })
+
+  if (editor == null) throw new Error('editor was never captured')
+  return editor
+}
+
+describe('EditorContext registers only what its extensions own', () => {
+  it('does not register headings when the heading extension is removed', async () => {
+    const editor = await mountEditor([builtInExtensions.Heading])
+    expect(editor.hasNode(HeadingNode)).toBe(false)
+  })
+
+  it('still registers headings with the default configuration', async () => {
+    const editor = await mountEditor([])
+    expect(editor.hasNode(HeadingNode)).toBe(true)
+  })
+
+  it('registers every readable node class with the default configuration', async () => {
+    const editor = await mountEditor([])
+    // The former blanket list, now the read vocabulary. Every class in it
+    // must still be reachable through an extension, or the default
+    // configuration has silently lost a feature.
+    const missing = READABLE_NODES.filter((klass) => !editor.hasNode(klass)).map((klass) =>
+      klass.getType()
+    )
+    expect(missing).toEqual([])
+  })
+
+  it('keeps the core nodes even when site code tries to remove them', async () => {
+    // `remove()` matches by name and accepts the extension object, so
+    // this is a removal a site could really attempt. The root injects
+    // CoreNodesExtension outside the configurable list, so it survives.
+    const editor = await mountEditor([CoreNodesExtension.name])
+    expect(editor.hasNode(MarkNode)).toBe(true)
+    expect(editor.hasNode(OverflowNode)).toBe(true)
+  })
+})

package/src/field/editor-context.tsx

@@ -22,12 +22,17 @@ import {
 
 import { defaultExtensionsList } from './config/default-extensions'
 import { EditorConfigContext } from './config/editor-config-context'
+import { rootDependencies } from './config/root-dependencies'
 import { MarkdownModeProvider } from './context/markdown-mode-context'
 import { SharedHistoryContext } from './context/shared-history-context'
 import { SharedOnChangeContext } from './context/shared-on-change-context'
 import { Editor } from './editor'
 import { InlineImageExtension } from './extensions/inline-image/inline-image-extension'
-import { Nodes } from './nodes'
+import { AdaptedNotice, UnsupportedContentNotice } from './normalize/adapted-notice'
+import {
+  NormalizationStatusProvider,
+  useNormalizationStatus,
+} from './normalize/normalization-status'
 import type { EditorConfig } from './config/types'
 
 // Catch any errors that occur during Lexical updates and log them
@@ -92,15 +97,30 @@ export function EditorContext(props: {
         collection: editorConfig.settings.inlineImageUploadCollection,
       })
     }
-    const dependencies = configured.toArray()
+    // Optional features plus mandatory infrastructure. See
+    // `rootDependencies` for why the core nodes are injected here rather
+    // than carried in the configurable list.
+    const dependencies = rootDependencies(configured)
 
     return defineExtension({
       name: '[root]',
       namespace: editorConfig.lexical.namespace,
-      nodes: [...Nodes],
+      // No `nodes` here on purpose. Every node class is owned by the
+      // extension that provides its feature, so removing an extension
+      // removes its controls, its behaviour AND its node registration.
+      // A blanket list here would let a field accept structures it does
+      // not offer — a field configured without headings would still
+      // store a heading pasted into it.
       theme: editorConfig.lexical.theme,
       editable,
-      $initialEditorState: value != null ? JSON.stringify(value) : undefined,
+      // No `$initialEditorState`. It is evaluated while the editor is
+      // being built, before the registered node types exist, so an
+      // unnormalized value would throw inside the builder with no chance
+      // to adapt it — and its function form runs inside an update, where
+      // `setEditorState` is unsafe (see apply-value-plugin.tsx). The
+      // value arrives through ApplyValuePlugin instead, which normalizes
+      // against the built editor's real capabilities and applies in a
+      // layout effect so nothing paints empty first.
       onError: (error: Error) => {
         throw error
       },
@@ -123,24 +143,72 @@ export function EditorContext(props: {
   // back inside their React tree.
   return (
     <EditorConfigContext config={editorConfig.settings}>
-      <SharedOnChangeContext onChange={onChange}>
-        <SharedHistoryContext>
-          <MarkdownModeProvider>
-            <LexicalExtensionComposer
-              extension={rootExtension}
-              contentEditable={null}
-              key={composerKey + editable}
-            >
-              <div className="editor-shell">
-                {beforeEditor}
-                <Editor minHeight={props.minHeight} maxHeight={props.maxHeight} />
-                {afterEditor}
-                {children}
-              </div>
-            </LexicalExtensionComposer>
-          </MarkdownModeProvider>
-        </SharedHistoryContext>
-      </SharedOnChangeContext>
+      <NormalizationStatusProvider>
+        <SharedOnChangeContext onChange={onChange}>
+          <SharedHistoryContext>
+            <MarkdownModeProvider>
+              <LexicalExtensionComposer
+                extension={rootExtension}
+                contentEditable={null}
+                key={composerKey + editable}
+              >
+                <EditorShell
+                  beforeEditor={beforeEditor}
+                  afterEditor={afterEditor}
+                  minHeight={props.minHeight}
+                  maxHeight={props.maxHeight}
+                >
+                  {children}
+                </EditorShell>
+              </LexicalExtensionComposer>
+            </MarkdownModeProvider>
+          </SharedHistoryContext>
+        </SharedOnChangeContext>
+      </NormalizationStatusProvider>
     </EditorConfigContext>
   )
 }
+
+/**
+ * The editor surface, or the read-only notice in its place.
+ *
+ * Content with no safe conversion is not adapted and not discarded: the
+ * field declines to edit it and says why. Sits inside the composer so it
+ * can read the status the apply plugin publishes.
+ */
+function EditorShell({
+  beforeEditor,
+  afterEditor,
+  minHeight,
+  maxHeight,
+  children,
+}: {
+  beforeEditor?: React.ReactNode[]
+  afterEditor?: React.ReactNode[]
+  minHeight?: number | string
+  maxHeight?: number | string
+  children?: React.ReactNode
+}): React.JSX.Element {
+  const { status } = useNormalizationStatus()
+
+  // `children` carries ApplyValuePlugin, so it stays mounted in BOTH
+  // branches. Unmounting it on refusal would strand the field: the plugin
+  // that applies values would be gone, so a later valid value could
+  // neither load nor clear the notice, and the only escape would be a
+  // full remount.
+  return (
+    <div className="editor-shell">
+      {status.kind === 'refused' ? (
+        <UnsupportedContentNotice unsupportedTypes={status.unsupportedTypes} />
+      ) : (
+        <>
+          {status.kind === 'adapted' && <AdaptedNotice />}
+          {beforeEditor}
+          <Editor minHeight={minHeight} maxHeight={maxHeight} />
+          {afterEditor}
+        </>
+      )}
+      {children}
+    </div>
+  )
+}

package/src/field/editor.tsx

@@ -11,18 +11,18 @@
 import type * as React from 'react'
 import { memo, useCallback, useEffect, useMemo, useState } from 'react'
 
+import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext'
 import { LexicalErrorBoundary } from '@lexical/react/LexicalErrorBoundary'
 import { HistoryPlugin } from '@lexical/react/LexicalHistoryPlugin'
 import { MarkdownShortcutPlugin } from '@lexical/react/LexicalMarkdownShortcutPlugin'
 import { OnChangePlugin } from '@lexical/react/LexicalOnChangePlugin'
 import { PlainTextPlugin } from '@lexical/react/LexicalPlainTextPlugin'
 import { RichTextPlugin } from '@lexical/react/LexicalRichTextPlugin'
-import {
-  useExtensionDependency,
-  useOptionalExtensionDependency,
-} from '@lexical/react/useExtensionComponent'
+import { useExtensionDependency } from '@lexical/react/useExtensionComponent'
 import type { EditorState, LexicalEditor } from 'lexical'
 
+import { transformersFor } from './capabilities/filter-transformers'
+import { supportsNodeType } from './capabilities/registered-node-types'
 import { useEditorConfig } from './config/editor-config-context'
 import { ContentEditable } from './content-editable'
 import { useMarkdownMode } from './context/markdown-mode-context'
@@ -33,7 +33,6 @@ import {
   BylineFloatingUIExtension,
   selectFloatingUIItems,
 } from './extensions/byline-floating-ui/byline-floating-ui-extension'
-import { TableExtension as BylineTableExtension } from './extensions/table/table-extension'
 import { BYLINE_TRANSFORMERS } from './markdown/transformers'
 // import { AiPlugin } from './plugins/ai-plugin'
 // import { DragDropPaste } from './plugins/drag-drop-paste-plugin'
@@ -67,11 +66,24 @@ export const Editor = memo(function Editor({
   const { markdownModeRef } = useMarkdownMode()
   const {
     config: {
-      options: { debug, richText, showTreeView, markdownShortcutPlugin },
+      mode,
+      markdownShortcuts,
+      controls: { treeView },
+      debug,
       placeholderText,
     },
   } = useEditorConfig()
-  const hasTableExtension = useOptionalExtensionDependency(BylineTableExtension) !== undefined
+  const richText = mode === 'richText'
+  const [editor] = useLexicalComposerContext()
+  // Table availability is structural, so it follows the registered node
+  // rather than extension-list membership: TableNode arrives through
+  // `@lexical/table` as a dependency of the Byline wrapper, and a
+  // membership test would miss any other route to the same node.
+  const hasTableNode = supportsNodeType(editor, 'table')
+  // Markdown shortcuts create nodes, so the transformer list must follow
+  // what this editor registered — an unregistered dependency throws for
+  // the whole pipeline, not just its own transformer.
+  const activeTransformers = useMemo(() => transformersFor(editor, BYLINE_TRANSFORMERS), [editor])
   // Merged floating-UI contributions from every extension in the graph.
   // Removing a contributing extension (e.g. `c.extensions.remove(LinkExtension)`)
   // automatically suppresses its floating UI — no separate boolean toggle.
@@ -132,10 +144,10 @@ export const Editor = memo(function Editor({
 
   const content = (
     <>
-      {hasTableExtension && <TablePlugin />}
+      {hasTableNode && <TablePlugin />}
       {richText && <ToolbarPlugin />}
       <div
-        className={`editor-container ${showTreeView ? 'tree-view' : ''} ${
+        className={`editor-container ${treeView ? 'tree-view' : ''} ${
           !richText ? 'plain-text' : ''
         }`}
       >
@@ -166,9 +178,7 @@ export const Editor = memo(function Editor({
               ErrorBoundary={LexicalErrorBoundary}
             />
             <HistoryPlugin externalHistoryState={historyState} />
-            {markdownShortcutPlugin && (
-              <MarkdownShortcutPlugin transformers={BYLINE_TRANSFORMERS} />
-            )}
+            {markdownShortcuts && <MarkdownShortcutPlugin transformers={activeTransformers} />}
             {floatingAnchorElem != null &&
               !isSmallWidthViewport &&
               floatingUIItems.map(({ id, Component }) => (

package/src/field/extensions/core-nodes/core-nodes-extension.test.tsx

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest'
+
+import { supportsNodeType } from '../../capabilities/registered-node-types'
+import { buildRestrictedEditor } from '../../test-support/build-test-editor'
+
+describe('CoreNodesExtension', () => {
+  it('keeps mark and overflow registered even in a fully stripped editor', () => {
+    const editor = buildRestrictedEditor()
+    expect(supportsNodeType(editor, 'mark')).toBe(true)
+    expect(supportsNodeType(editor, 'overflow')).toBe(true)
+    editor.dispose()
+  })
+})

package/src/field/extensions/core-nodes/core-nodes-extension.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 { MarkNode } from '@lexical/mark'
+import { OverflowNode } from '@lexical/overflow'
+import { defineExtension } from 'lexical'
+
+/**
+ * Owns the node classes that belong to no switchable feature.
+ *
+ * `MarkNode` and `OverflowNode` ship without an upstream extension, and
+ * neither corresponds to something a field can turn off. Without an
+ * owner both would lose their only registration once the editor root
+ * stopped registering a blanket node list.
+ *
+ * `EditorContext` injects this extension directly into the root's
+ * dependencies, outside `editorConfig.extensions`. Leaving it out of
+ * `builtInExtensions` would NOT have made it non-removable: this module
+ * is publicly exported and `ExtensionsList.remove()` accepts an
+ * extension object as readily as a name string, so site code could have
+ * removed it from the configurable list. Injection at the root is what
+ * enforces its presence.
+ */
+export const CoreNodesExtension = defineExtension({
+  name: '@byline/richtext-lexical/CoreNodes',
+  nodes: () => [MarkNode, OverflowNode],
+})

package/src/field/extensions/heading/heading-extension.test.tsx

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest'
+
+import { builtInExtensions } from '../../config/built-in-extension-names'
+import {
+  buildFullEditor,
+  buildRestrictedEditor,
+  parseHtmlToTypes,
+} from '../../test-support/build-test-editor'
+
+describe('heading and quote ownership', () => {
+  it('imports headings and quotes when both extensions are present', () => {
+    const editor = buildFullEditor()
+    expect(parseHtmlToTypes(editor, '<h1>Title</h1>').types).toEqual(['heading'])
+    expect(parseHtmlToTypes(editor, '<blockquote>Quoted</blockquote>').types).toEqual(['quote'])
+    editor.dispose()
+  })
+
+  it('degrades a pasted heading to a paragraph and keeps the text', () => {
+    const editor = buildRestrictedEditor([builtInExtensions.Heading])
+    const result = parseHtmlToTypes(editor, '<h1>Pasted title</h1>')
+    expect(result.types).toEqual(['paragraph'])
+    expect(result.text).toBe('Pasted title')
+    editor.dispose()
+  })
+
+  it('keeps headings while quotes are removed', () => {
+    const editor = buildRestrictedEditor([builtInExtensions.Quote])
+    expect(parseHtmlToTypes(editor, '<h1>Title</h1>').types).toEqual(['heading'])
+    expect(parseHtmlToTypes(editor, '<blockquote>Quoted</blockquote>').types).toEqual(['paragraph'])
+    editor.dispose()
+  })
+})

package/src/field/extensions/heading/heading-extension.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 { HeadingNode } from '@lexical/rich-text'
+import { defineExtension } from 'lexical'
+
+/**
+ * Owns `HeadingNode`.
+ *
+ * Byline deliberately does not adopt `@lexical/rich-text`'s
+ * `RichTextExtension` for this. That extension binds heading and quote
+ * registration to general rich-text behaviour, so adopting it would
+ * register headings in every rich-text field — and a field configured
+ * without headings would still accept one from a paste, which is the
+ * defect this package had. Owning the node here keeps headings
+ * removable on their own, independently of quotes and of rich-text
+ * behaviour itself.
+ */
+export const HeadingExtension = defineExtension({
+  name: '@byline/richtext-lexical/Heading',
+  nodes: () => [HeadingNode],
+})

package/src/field/extensions/quote/quote-extension.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 { QuoteNode } from '@lexical/rich-text'
+import { defineExtension } from 'lexical'
+
+/**
+ * Owns `QuoteNode`.
+ *
+ * Separate from {@link HeadingExtension} on purpose: a field may want
+ * headings without block quotes, or neither. See the heading extension
+ * for why Byline owns these nodes rather than adopting
+ * `RichTextExtension`.
+ */
+export const QuoteExtension = defineExtension({
+  name: '@byline/richtext-lexical/Quote',
+  nodes: () => [QuoteNode],
+})