@byline/richtext-lexical 5.2.0 → 6.0.0

package/src/field/normalize/clipboard-equivalence.test.tsx

@@ -0,0 +1,330 @@
+import { $insertDataTransferForRichText } from '@lexical/clipboard'
+import { registerRichText } from '@lexical/rich-text'
+import {
+  $createParagraphNode,
+  $getRoot,
+  $getSelection,
+  type LexicalEditor,
+  type SerializedEditorState,
+} from 'lexical'
+import { describe, expect, it, vi } from 'vitest'
+
+import { registeredNodeTypes } from '../capabilities/registered-node-types'
+import { builtInExtensions } from '../config/built-in-extension-names'
+import { buildRestrictedEditor } from '../test-support/build-test-editor'
+import { normalizeValue } from './normalize-value'
+
+const NAMESPACE = 'LexicalRichText'
+
+const text = (value: string) => ({
+  detail: 0,
+  format: 0,
+  mode: 'normal',
+  style: '',
+  text: value,
+  type: 'text',
+  version: 1,
+})
+// biome-ignore lint/suspicious/noExplicitAny: serialized fixtures are structural
+const doc = (...children: unknown[]): any => ({
+  root: { children, direction: null, format: '', indent: 0, type: 'root', version: 1 },
+})
+
+function snapshot(editor: LexicalEditor): { types: string[]; text: string } {
+  let types: string[] = []
+  let content = ''
+  editor.getEditorState().read(() => {
+    types = $getRoot()
+      .getChildren()
+      .map((node) => node.getType())
+    content = $getRoot().getTextContent()
+  })
+  return { types, text: content }
+}
+
+/** Load `saved` through the normalizer and commit it. */
+function viaStorage(removals: string[] | undefined, saved: SerializedEditorState) {
+  const editor = buildRestrictedEditor(removals)
+  const result = normalizeValue(saved, registeredNodeTypes(editor))
+  if (result.status !== 'adapted') throw new Error(`expected adapted, got ${result.status}`)
+  editor.setEditorState(editor.parseEditorState(JSON.stringify(result.value)))
+  const out = snapshot(editor)
+  editor.dispose()
+  return out
+}
+
+const stubDataTransfer = (data: Record<string, string>) => ({
+  types: Object.keys(data),
+  getData: (type: string) => data[type] ?? '',
+})
+
+/** Paste a real clipboard payload through registerRichText's handler. */
+function pasteClipboard(
+  removals: string[] | undefined,
+  data: Record<string, string>
+): { types: string[]; text: string; threw: string; consoleErrors: string[] } {
+  const editor = buildRestrictedEditor(removals)
+  const consoleErrors: string[] = []
+  const spy = vi.spyOn(console, 'error').mockImplementation((...args) => {
+    consoleErrors.push(String((args[0] as Error)?.message ?? args[0]))
+  })
+
+  registerRichText(editor)
+  editor.update(
+    () => {
+      $getRoot().clear().append($createParagraphNode())
+      $getRoot().selectEnd()
+    },
+    { discrete: true }
+  )
+
+  let threw = 'none'
+  try {
+    editor.update(
+      () => {
+        // biome-ignore lint/suspicious/noExplicitAny: stub data transfer
+        $insertDataTransferForRichText(stubDataTransfer(data) as any, $getSelection()!, editor)
+      },
+      { discrete: true }
+    )
+  } catch (error) {
+    threw = (error as Error).message
+  }
+  spy.mockRestore()
+
+  const out = snapshot(editor)
+  editor.dispose()
+  return { ...out, threw, consoleErrors }
+}
+
+/** Paste HTML the way a real paste does: through insertion, not parsing. */
+function viaClipboardHtml(removals: string[] | undefined, html: string) {
+  return pasteClipboard(removals, { 'text/html': html, 'text/plain': '' })
+}
+
+const block = (type: string, children: unknown[], extra: Record<string, unknown> = {}) => ({
+  children,
+  direction: null,
+  format: '',
+  indent: 0,
+  type,
+  version: 1,
+  ...extra,
+})
+
+describe('clipboard and storage reach equivalent outcomes', () => {
+  // Every structure the specification lists as convertible, compared
+  // across both routes. Both go through real insertion — inspecting
+  // imported nodes before insertion would not evidence what a paste
+  // actually leaves in the document.
+  const cases: Array<{
+    name: string
+    saved: SerializedEditorState
+    html: string
+    /**
+     * The ordered block structure BOTH routes must produce. Pinned
+     * explicitly rather than compared route-to-route as sets: a set
+     * comparison treats one paragraph and three as equal, which is
+     * exactly the boundary loss this work fixed — two adjacent headings
+     * merging into a single paragraph would pass unnoticed.
+     */
+    expectedTypes: string[]
+    expectedText: string
+  }> = [
+    {
+      name: 'heading',
+      saved: doc(block('heading', [text('Title')], { tag: 'h1' })),
+      html: '<h1>Title</h1>',
+      expectedTypes: ['paragraph'],
+      expectedText: 'Title',
+    },
+    {
+      name: 'quote',
+      saved: doc(block('quote', [text('Quoted words')])),
+      html: '<blockquote>Quoted words</blockquote>',
+      expectedTypes: ['paragraph'],
+      expectedText: 'Quoted words',
+    },
+    {
+      name: 'code block',
+      saved: doc(block('code', [text('const x = 1')], { language: 'js' })),
+      html: '<pre>const x = 1</pre>',
+      expectedTypes: ['paragraph'],
+      expectedText: 'const x = 1',
+    },
+    {
+      name: 'bullet list',
+      saved: doc(
+        block(
+          'list',
+          [
+            block('listitem', [text('item one')], { value: 1 }),
+            block('listitem', [text('item two')], { value: 2 }),
+          ],
+          { listType: 'bullet', start: 1, tag: 'ul' }
+        )
+      ),
+      html: '<ul><li>item one</li><li>item two</li></ul>',
+      // TWO paragraphs, not one: each item keeps its own boundary.
+      expectedTypes: ['paragraph', 'paragraph'],
+      expectedText: 'item one\n\nitem two',
+    },
+    {
+      name: 'table',
+      saved: doc(
+        block(
+          'table',
+          [
+            block('tablerow', [
+              block('tablecell', [block('paragraph', [text('cell text')])], {
+                colSpan: 1,
+                rowSpan: 1,
+                headerState: 0,
+              }),
+            ]),
+          ],
+          {}
+        )
+      ),
+      html: '<table><tr><td>cell text</td></tr></table>',
+      expectedTypes: ['paragraph'],
+      expectedText: 'cell text',
+    },
+  ]
+
+  for (const { name, saved, html, expectedTypes, expectedText } of cases) {
+    it(`degrades a ${name} equivalently by either route`, () => {
+      const storage = viaStorage(undefined, saved)
+      const clipboard = viaClipboardHtml(undefined, html)
+
+      expect(clipboard.threw).toBe('none')
+      // Ordered structure, pinned — block count and order both matter.
+      expect(storage.types, `${name} via storage`).toEqual(expectedTypes)
+      expect(clipboard.types, `${name} via clipboard`).toEqual(expectedTypes)
+      expect(storage.text, `${name} via storage`).toBe(expectedText)
+      expect(clipboard.text, `${name} via clipboard`).toBe(expectedText)
+    })
+  }
+
+  it('drops a horizontal rule on both routes and keeps its neighbours', () => {
+    const storage = viaStorage(
+      undefined,
+      doc(
+        block('paragraph', [text('before')]),
+        { type: 'horizontalrule', version: 1 },
+        block('paragraph', [text('after')])
+      )
+    )
+    const clipboard = viaClipboardHtml(undefined, '<p>before</p><hr /><p>after</p>')
+
+    // Exactly the two neighbours, in order — the rule is gone and took
+    // nothing with it.
+    expect(storage.types).toEqual(['paragraph', 'paragraph'])
+    expect(clipboard.types).toEqual(['paragraph', 'paragraph'])
+    expect(storage.text).toBe('before\n\nafter')
+    expect(clipboard.text).toBe('before\n\nafter')
+  })
+
+  it('preserves the link URL on the storage route only, by design', () => {
+    const link = block('link', [text('link text')], {
+      version: 2,
+      attributes: { url: 'https://example.test/a' },
+    })
+    const storage = viaStorage([builtInExtensions.Link], doc(block('paragraph', [link])))
+    const clipboard = viaClipboardHtml(
+      [builtInExtensions.Link],
+      '<p><a href="https://example.test/a">link text</a></p>'
+    )
+
+    // Equivalent structure and text — NOT identical content.
+    expect(storage.types).toEqual(['paragraph'])
+    expect(clipboard.types).toEqual(['paragraph'])
+    expect(storage.text).toContain('link text')
+    expect(clipboard.text).toContain('link text')
+
+    // The intended difference, asserted from both sides so it cannot
+    // drift into either a "bug" or a silent regression.
+    expect(storage.text).toContain('https://example.test/a')
+    expect(clipboard.text).not.toContain('https://example.test/a')
+  })
+
+  it('preserves the admonition title on the storage route only', () => {
+    const storage = viaStorage(
+      [builtInExtensions.Admonition],
+      doc(block('admonition', [block('paragraph', [text('body copy')])], { title: 'Note title' }))
+    )
+    const clipboard = viaClipboardHtml(
+      [builtInExtensions.Admonition],
+      '<div data-type="note" data-title="Note title" class="admonition"><p>body copy</p></div>'
+    )
+
+    expect(clipboard.threw).toBe('none')
+    // Both keep the body...
+    expect(storage.text).toContain('body copy')
+    expect(clipboard.text).toContain('body copy')
+
+    // ...and only storage keeps the title, as its own leading line.
+    expect(storage.text).toContain('Note title')
+    expect(storage.text.indexOf('Note title')).toBeLessThan(storage.text.indexOf('body copy'))
+    expect(clipboard.text).not.toContain('Note title')
+  })
+})
+
+describe('Lexical-to-Lexical paste', () => {
+  const headingPayload = JSON.stringify({
+    namespace: NAMESPACE,
+    nodes: [
+      {
+        children: [text('Copied title')],
+        direction: null,
+        format: '',
+        indent: 0,
+        type: 'heading',
+        version: 1,
+        tag: 'h1',
+      },
+    ],
+  })
+
+  it('falls through to the HTML handler and degrades', () => {
+    // application/x-lexical-editor is tried FIRST (priority 0, ahead of
+    // text/html at 10) and does not use importDOM at all — it calls the
+    // same $parseSerializedNode that throws on an unregistered type.
+    // Byline gives every field the same namespace, so a copy between two
+    // Byline fields takes this branch.
+    const result = pasteClipboard(undefined, {
+      'application/x-lexical-editor': headingPayload,
+      'text/html': '<h1>Copied title</h1>',
+      'text/plain': 'Copied title',
+    })
+
+    expect(result.threw).toBe('none')
+    expect(result.types).toEqual(['paragraph'])
+    expect(result.text).toContain('Copied title')
+    // The fallthrough is internal, not a fault — assert it rather than
+    // suppress it, so a future Lexical change that makes it fatal is
+    // caught here.
+    expect(result.consoleErrors.join(' ')).toContain('not found')
+  })
+
+  it('survives a clipboard with no text/html at all', () => {
+    // A source application may offer only Lexical JSON and plain text.
+    // The guarantee must not depend on HTML being present.
+    const result = pasteClipboard(undefined, {
+      'application/x-lexical-editor': headingPayload,
+      'text/plain': 'Copied title',
+    })
+
+    expect(result.threw).toBe('none')
+    expect(result.types).toEqual(['paragraph'])
+    // Text preservation is the guarantee on this route; inline formatting
+    // is not, because plain text carries none.
+    expect(result.text).toContain('Copied title')
+  })
+
+  it('pastes plain text normally when that is all the clipboard holds', () => {
+    const result = pasteClipboard(undefined, { 'text/plain': 'just words' })
+    expect(result.threw).toBe('none')
+    expect(result.text).toContain('just words')
+  })
+})

package/src/field/normalize/content-labels.ts

@@ -0,0 +1,44 @@
+/**
+ * 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
+ */
+
+/**
+ * Translation keys for the node types a reader may be told about.
+ *
+ * Only types with NO declared conversion can reach a notice, which is
+ * why this map is small: everything else is adapted silently.
+ *
+ * A type absent here falls back to its own id. That is deliberate — a
+ * site or plugin contributing its own node should not have to supply a
+ * display name to get a usable message, and reaching this path at all is
+ * rare. The id is developer vocabulary, but it is accurate and
+ * searchable, which beats inventing a label for a node Byline knows
+ * nothing about.
+ */
+const CONTENT_LABEL_KEYS: Readonly<Record<string, string>> = {
+  'inline-image': 'richtext.content.image',
+  youtube: 'richtext.content.youtube',
+  vimeo: 'richtext.content.vimeo',
+}
+
+export function contentLabelKey(type: string): string | undefined {
+  return CONTENT_LABEL_KEYS[type]
+}
+
+/**
+ * Join labels the way the active locale writes a list.
+ *
+ * `Intl.ListFormat` is not available in every runtime this may render
+ * in, so fall back to a comma join rather than throwing over a notice.
+ */
+export function joinLabels(labels: string[], locale: string): string {
+  try {
+    return new Intl.ListFormat(locale, { style: 'long', type: 'conjunction' }).format(labels)
+  } catch {
+    return labels.join(', ')
+  }
+}

package/src/field/normalize/declared-conversions.test.node.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest'
+
+import { conversionFor, DECLARED_CONVERSIONS } from './declared-conversions'
+
+describe('declared conversions', () => {
+  it('declares one for every structure the spec lists as supported', () => {
+    for (const type of [
+      'heading',
+      'quote',
+      'code',
+      'listitem',
+      'table',
+      'tablerow',
+      'tablecell',
+      'list',
+      'layout-container',
+      'layout-item',
+      'admonition',
+      'link',
+      'autolink',
+      'horizontalrule',
+    ]) {
+      expect(conversionFor(type), type).toBeDefined()
+    }
+  })
+
+  it('declares none for media, embeds or unknown types', () => {
+    for (const type of ['inline-image', 'youtube', 'vimeo', 'acme-custom-node']) {
+      expect(conversionFor(type), type).toBeUndefined()
+    }
+  })
+
+  it('classifies each structure by what it contains', () => {
+    expect(DECLARED_CONVERSIONS.heading.kind).toBe('to-paragraph')
+    expect(DECLARED_CONVERSIONS.listitem.kind).toBe('to-paragraph')
+    expect(DECLARED_CONVERSIONS.table.kind).toBe('lift-blocks')
+    expect(DECLARED_CONVERSIONS.list.kind).toBe('lift-blocks')
+    expect(DECLARED_CONVERSIONS.link.kind).toBe('unwrap-inline')
+  })
+
+  it('preserves the admonition title', () => {
+    expect(
+      DECLARED_CONVERSIONS.admonition.preserveText({ type: 'admonition', title: 'Note title' })
+    ).toBe('Note title')
+    expect(DECLARED_CONVERSIONS.admonition.preserveText({ type: 'admonition' })).toBeUndefined()
+  })
+
+  it('preserves the link URL from either serialized shape', () => {
+    // v1 stored `url` at the top level; v2 nests it under `attributes`.
+    expect(DECLARED_CONVERSIONS.link.preserveText({ type: 'link', url: 'https://a.test' })).toBe(
+      'https://a.test'
+    )
+    expect(
+      DECLARED_CONVERSIONS.link.preserveText({
+        type: 'link',
+        attributes: { url: 'https://b.test' },
+      })
+    ).toBe('https://b.test')
+    expect(DECLARED_CONVERSIONS.link.preserveText({ type: 'link' })).toBeUndefined()
+  })
+
+  it('drops a horizontal rule without inventing text', () => {
+    const rule = conversionFor('horizontalrule')
+    expect(rule?.kind).toBe('drop')
+    expect(rule?.preserveText).toBeUndefined()
+  })
+})

package/src/field/normalize/declared-conversions.ts

@@ -0,0 +1,160 @@
+/**
+ * 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
+ */
+
+/** A serialized Lexical node, as stored. */
+export interface SerializedNode {
+  type: string
+  children?: SerializedNode[]
+  [key: string]: unknown
+}
+
+/**
+ * What a convertible structure CONTAINS, which is what decides a
+ * structurally valid replacement for it.
+ *
+ * - `to-paragraph` — a block holding inline content. Becomes exactly one
+ *   paragraph, so two adjacent headings stay two paragraphs and an empty
+ *   heading stays an empty paragraph instead of vanishing.
+ * - `lift-blocks` — a block holding blocks. Its children are lifted in
+ *   place, already block-level and already valid where the parent sat.
+ * - `unwrap-inline` — inline content. Its children are lifted inline and
+ *   stay inside the paragraph that held them.
+ * - `to-text` — a text-carrying leaf whose class is unsupported, such as
+ *   a syntax-highlighted code token. Becomes a plain text node with its
+ *   text and inline formats intact.
+ * - `drop` — removed entirely; neighbours are untouched.
+ */
+export type ConversionKind = 'to-paragraph' | 'lift-blocks' | 'unwrap-inline' | 'to-text' | 'drop'
+
+/**
+ * Serialized types Byline knows to be block-level.
+ *
+ * Needed because a converted node's children are not always inline: a
+ * `listitem` may hold a nested `list`, so turning every item straight
+ * into a paragraph would nest a block inside a paragraph.
+ */
+export const BLOCK_TYPES: ReadonlySet<string> = new Set([
+  'paragraph',
+  'heading',
+  'quote',
+  'code',
+  'list',
+  'listitem',
+  'table',
+  'tablerow',
+  'tablecell',
+  'layout-container',
+  'layout-item',
+  'admonition',
+  'horizontalrule',
+  'youtube',
+  'vimeo',
+])
+
+export function isBlockType(type: string): boolean {
+  return BLOCK_TYPES.has(type)
+}
+
+/**
+ * Serialized types Byline knows to be inline.
+ *
+ * The counterpart to {@link BLOCK_TYPES}, and the reason both lists
+ * exist rather than one: a node's structural role cannot be recovered
+ * from its serialized shape. An inline `link` and a block `quote` are
+ * both elements with `children`, `direction`, `format` and `indent`, so
+ * there is no reliable metadata to infer the role from.
+ *
+ * A SUPPORTED node can reach this test — it arrives as the child of an
+ * unsupported parent being converted — so "not a known block" cannot be
+ * read as "inline". A custom block from a downstream site would be
+ * wrapped into a paragraph and produce a tree Lexical rejects. When a
+ * type appears in neither list its role is unknown, and normalization
+ * refuses the document rather than guessing at it.
+ */
+export const INLINE_TYPES: ReadonlySet<string> = new Set([
+  'text',
+  'linebreak',
+  'tab',
+  'link',
+  'autolink',
+  'mark',
+  'overflow',
+  'code-highlight',
+  'inline-image',
+])
+
+export function isInlineType(type: string): boolean {
+  return INLINE_TYPES.has(type)
+}
+
+export interface DeclaredConversion {
+  kind: ConversionKind
+  /**
+   * Information carried on the node's own properties rather than in its
+   * children, which would otherwise be lost silently. Emitted as a
+   * leading paragraph for `lift-blocks` (an admonition title becomes the
+   * first line) and appended to the text for `unwrap-inline` (a link URL
+   * follows its text).
+   */
+  preserveText?: (node: SerializedNode) => string | undefined
+}
+
+const urlText = (node: SerializedNode): string | undefined => {
+  const attributes = node.attributes as { url?: unknown } | undefined
+  const url = typeof node.url === 'string' ? node.url : attributes?.url
+  return typeof url === 'string' && url.length > 0 ? url : undefined
+}
+
+/**
+ * How each convertible structure degrades when a field does not support
+ * it. Type strings are the node classes' own `getType()` values.
+ *
+ * A type absent from this table has NO conversion and is never guessed
+ * at — normalization refuses the document instead. That covers custom
+ * nodes from downstream sites as well as inline images and embeds, whose
+ * media relations and nested-editor captions cannot survive any
+ * structural rewrite.
+ */
+export const DECLARED_CONVERSIONS = {
+  // Blocks holding inline content.
+  heading: { kind: 'to-paragraph' },
+  quote: { kind: 'to-paragraph' },
+  code: { kind: 'to-paragraph' },
+  listitem: { kind: 'to-paragraph' },
+
+  // Blocks holding blocks.
+  table: { kind: 'lift-blocks' },
+  tablerow: { kind: 'lift-blocks' },
+  tablecell: { kind: 'lift-blocks' },
+  list: { kind: 'lift-blocks' },
+  'layout-container': { kind: 'lift-blocks' },
+  'layout-item': { kind: 'lift-blocks' },
+  admonition: {
+    kind: 'lift-blocks',
+    preserveText: (node) =>
+      typeof node.title === 'string' && node.title.length > 0 ? node.title : undefined,
+  },
+
+  // Text-carrying leaves. CodeHighlightNode is a TextNode subclass owned
+  // by the same extension as CodeNode, so removing code-highlight
+  // unregisters BOTH: without this entry a highlighted code block would
+  // be refused rather than adapted, contradicting the promise that code
+  // degrades to text.
+  'code-highlight': { kind: 'to-text' },
+
+  // Inline content.
+  link: { kind: 'unwrap-inline', preserveText: urlText },
+  autolink: { kind: 'unwrap-inline', preserveText: urlText },
+
+  // Decorative, with nothing to preserve.
+  horizontalrule: { kind: 'drop' },
+} as const satisfies Record<string, DeclaredConversion>
+
+export function conversionFor(type: string): DeclaredConversion | undefined {
+  return (DECLARED_CONVERSIONS as Record<string, DeclaredConversion | undefined>)[type]
+}