@byline/richtext-lexical 5.2.0 → 6.0.0

package/src/field/hooks/markdown-source-mode.test.tsx

@@ -0,0 +1,221 @@
+import { act } from 'react'
+
+import { defineAdminConfig } from '@byline/core'
+import { CodeNode } from '@lexical/code'
+import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext'
+import { $createParagraphNode, $createTextNode, $getRoot, 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 { useMarkdownToggle } from './use-markdown-toggle'
+
+// biome-ignore lint/suspicious/noExplicitAny: React act environment flag
+;(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true
+
+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' }],
+    },
+  ],
+})
+
+interface Harness {
+  editor: LexicalEditor
+  container: HTMLDivElement
+  toggle: () => Promise<void>
+  isMarkdown: () => boolean
+  /**
+   * Editor updates wrapped in an async act() so React state settles.
+   * Lexical flushes its listeners in a microtask, and ToolbarPlugin sets
+   * state from them, so a synchronous act() leaves those updates outside
+   * the scope and React warns.
+   */
+  update: (fn: () => void) => Promise<void>
+  changes: Array<{ text: string }>
+}
+
+const mounted: Array<{ root: Root; container: HTMLDivElement }> = []
+
+afterEach(async () => {
+  for (const { root, container } of mounted.splice(0)) {
+    await act(async () => {
+      root.unmount()
+    })
+    container.remove()
+  }
+})
+
+async function mount(
+  removals: string[],
+  options: { markdownToggleControl?: boolean } = {}
+): Promise<Harness> {
+  const extensions = defaultClientEditorConfig.extensions?.clone()
+  for (const name of removals) extensions.remove(name)
+
+  const settings = {
+    ...defaultClientEditorConfig.settings,
+    controls: {
+      ...defaultClientEditorConfig.settings.controls,
+      // Default the preference ON so a missing button proves the
+      // capability gate, not a preference left switched off.
+      markdownToggle: options.markdownToggleControl ?? true,
+    },
+  }
+
+  const changes: Array<{ text: string }> = []
+
+  let editor: LexicalEditor | undefined
+  let toggleMarkdown: (() => void) | undefined
+  let isMarkdown = false
+
+  function Probe(): null {
+    const [instance] = useLexicalComposerContext()
+    const markdown = useMarkdownToggle()
+    editor = instance
+    toggleMarkdown = markdown.toggleMarkdown
+    isMarkdown = markdown.isMarkdown
+    return null
+  }
+
+  const container = document.createElement('div')
+  document.body.appendChild(container)
+  const root = createRoot(container)
+  mounted.push({ root, container })
+
+  await act(async () => {
+    root.render(
+      <EditorContext
+        composerKey="markdown"
+        editorConfig={{ ...defaultClientEditorConfig, settings, extensions }}
+        onChange={(editorState) => {
+          editorState.read(() => {
+            changes.push({ text: $getRoot().getTextContent() })
+          })
+        }}
+        readOnly={false}
+      >
+        <Probe />
+      </EditorContext>
+    )
+  })
+
+  if (editor == null || toggleMarkdown == null) throw new Error('probe never ran')
+  const instance = editor
+  return {
+    editor: instance,
+    container,
+    changes,
+    toggle: async () => {
+      await act(async () => {
+        toggleMarkdown?.()
+      })
+    },
+    isMarkdown: () => isMarkdown,
+    update: async (fn: () => void) => {
+      await act(async () => {
+        instance.update(fn, { discrete: true })
+      })
+    },
+  }
+}
+
+function text(editor: LexicalEditor): string {
+  let value = ''
+  editor.read(() => {
+    value = $getRoot().getTextContent()
+  })
+  return value
+}
+
+function blockTypes(editor: LexicalEditor): string[] {
+  let types: string[] = []
+  editor.read(() => {
+    types = $getRoot()
+      .getChildren()
+      .map((node) => node.getType())
+  })
+  return types
+}
+
+async function seedParagraph(harness: Harness, value: string): Promise<void> {
+  await harness.update(() => {
+    $getRoot()
+      .clear()
+      .append($createParagraphNode().append($createTextNode(value)))
+  })
+}
+
+describe('Markdown source mode follows the editor capabilities', () => {
+  it('round-trips with headings removed, preserving text and producing no heading', async () => {
+    const harness = await mount([builtInExtensions.Heading])
+    await seedParagraph(harness, 'Body text')
+
+    await harness.toggle()
+    expect(harness.isMarkdown()).toBe(true)
+    // While in source mode the surface is a single CodeNode of raw text.
+    expect(blockTypes(harness.editor)).toEqual(['code'])
+
+    // Edit the source, introducing Markdown for a structure this field
+    // no longer supports.
+    await harness.update(() => {
+      const code = $getRoot().getFirstChild()
+      code?.selectEnd().insertRawText('\n\n# Smuggled heading')
+    })
+
+    await harness.toggle()
+    expect(harness.isMarkdown()).toBe(false)
+    expect(blockTypes(harness.editor)).not.toContain('heading')
+    expect(text(harness.editor)).toContain('Smuggled heading')
+  })
+
+  it('hides the toggle button when the code node is unregistered', async () => {
+    // The preference is ON in this fixture, so an absent button proves
+    // the capability gate rather than a switched-off preference.
+    const withCode = await mount([])
+    expect(withCode.container.querySelector('.markdown-toggle')).not.toBeNull()
+
+    const withoutCode = await mount([builtInExtensions.CodeHighlight])
+    expect(withoutCode.editor.hasNodes([CodeNode])).toBe(false)
+    expect(withoutCode.container.querySelector('.markdown-toggle')).toBeNull()
+  })
+
+  it('a rejected toggle leaves the field still able to persist', async () => {
+    // CodeHighlightExtension owns CodeNode, and source mode holds its
+    // text in one. Without it, $createCodeNode throws.
+    const harness = await mount([builtInExtensions.CodeHighlight])
+    expect(harness.editor.hasNodes([CodeNode])).toBe(false)
+
+    const before = blockTypes(harness.editor)
+    await expect(harness.toggle()).resolves.toBeUndefined()
+    expect(harness.isMarkdown()).toBe(false)
+    expect(blockTypes(harness.editor)).toEqual(before)
+
+    // `isMarkdown` and `markdownModeRef` are separate state, and it is
+    // the ref that suppresses persistence. Setting it before the throwing
+    // call would leave the field silently unable to save, which this
+    // catches: ordinary editing after a rejected toggle must still reach
+    // onChange.
+    harness.changes.length = 0
+    await seedParagraph(harness, 'typed after the rejected toggle')
+
+    expect(harness.changes.length).toBeGreaterThan(0)
+    expect(harness.changes.at(-1)?.text).toContain('typed after the rejected toggle')
+  })
+
+  it('offers source mode with the default configuration', async () => {
+    const harness = await mount([])
+    expect(harness.editor.hasNodes([CodeNode])).toBe(true)
+    await harness.toggle()
+    expect(harness.isMarkdown()).toBe(true)
+  })
+})

package/src/field/hooks/use-markdown-toggle.ts

@@ -10,11 +10,12 @@
 
 import { useCallback, useEffect, useRef } from 'react'
 
-import { $createCodeNode, $isCodeNode } from '@lexical/code'
+import { $createCodeNode, $isCodeNode, CodeNode } from '@lexical/code'
 import { $convertFromMarkdownString, $convertToMarkdownString } from '@lexical/markdown'
 import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext'
-import { $getRoot, type EditorState, RootNode } from 'lexical'
+import { $getRoot, type EditorState, type LexicalEditor, RootNode } from 'lexical'
 
+import { transformersFor } from '../capabilities/filter-transformers'
 import { APPLY_VALUE_TAG } from '../constants'
 import { useMarkdownMode } from '../context/markdown-mode-context'
 import { BYLINE_TRANSFORMERS } from '../markdown/transformers'
@@ -42,6 +43,23 @@ function normalize(markdown: string): string {
  *  - Edits made in markdown produce a single conversion back to rich
  *    nodes on exit, emitting one field value change → **one patch**.
  */
+/**
+ * Whether this editor can offer Markdown source mode.
+ *
+ * Source mode holds the Markdown text in a `CodeNode`, so it needs that
+ * class registered — `$createCodeNode()` throws
+ * "Attempted to create node CodeNode that was not configured to be used
+ * on the editor" otherwise. A field with the code-highlight extension
+ * removed therefore cannot offer the toggle.
+ *
+ * The fix is to withhold the control, NOT to register `CodeNode` for the
+ * toggle's benefit: registering it would let code blocks back in through
+ * paste and storage, which is the acceptance hole this work closed.
+ */
+export function canUseMarkdownSourceMode(editor: LexicalEditor): boolean {
+  return editor.hasNodes([CodeNode])
+}
+
 export function useMarkdownToggle(): {
   isMarkdown: boolean
   toggleMarkdown: () => void
@@ -58,6 +76,7 @@ export function useMarkdownToggle(): {
   const unregisterTransformRef = useRef<(() => void) | null>(null)
 
   const registerRootGuard = useCallback(() => {
+    if (!canUseMarkdownSourceMode(editor)) return
     unregisterTransformRef.current?.()
     // Safety net: keep the root as exactly one markdown CodeNode so the user
     // can't split it into sibling root nodes while editing source.
@@ -82,12 +101,23 @@ export function useMarkdownToggle(): {
   }, [])
 
   const enterMarkdown = useCallback(() => {
+    // Guard before touching any state. `markdownModeRef` suppresses
+    // persistence, so setting it first and then throwing inside the
+    // update would leave the editor silently unable to save.
+    if (!canUseMarkdownSourceMode(editor)) return
+
     originalEditorStateRef.current = editor.getEditorState()
     // Suppress persistence *before* mutating so the code-block snapshot is
     // never emitted to the form.
     markdownModeRef.current = true
     editor.update(() => {
-      const markdown = $convertToMarkdownString(BYLINE_TRANSFORMERS, undefined, true)
+      // Filtered in both directions so source mode never offers syntax
+      // this field cannot import back.
+      const markdown = $convertToMarkdownString(
+        transformersFor(editor, BYLINE_TRANSFORMERS),
+        undefined,
+        true
+      )
       originalMarkdownRef.current = markdown
       const codeNode = $createCodeNode(MARKDOWN_LANGUAGE)
       $getRoot().clear().append(codeNode)
@@ -118,7 +148,12 @@ export function useMarkdownToggle(): {
       // emitted to the form (one field change → one patch).
       markdownModeRef.current = false
       editor.update(() => {
-        $convertFromMarkdownString(currentMarkdown, BYLINE_TRANSFORMERS, undefined, true)
+        $convertFromMarkdownString(
+          currentMarkdown,
+          transformersFor(editor, BYLINE_TRANSFORMERS),
+          undefined,
+          true
+        )
       })
     }
 

package/src/field/hooks/use-platform-modifier.test.tsx

@@ -0,0 +1,81 @@
+import { act } from 'react'
+
+import { hydrateRoot } from 'react-dom/client'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+// The client believes it is on a Mac. The SERVER never does — it has no
+// `navigator` — so this mock reproduces the split that caused the
+// mismatch: markup rendered without the platform, hydrated with it.
+vi.mock('../shared/environment', () => ({ IS_APPLE: true }))
+
+import { IS_APPLE } from '../shared/environment'
+import { useIsApplePlatform } from './use-platform-modifier'
+
+// biome-ignore lint/suspicious/noExplicitAny: React act environment flag
+;(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true
+
+/** The label a server renders: platform unknown, so the non-Apple form. */
+const SERVER_MARKUP = '<button type="button" title="Bold (Ctrl+B)"></button>'
+
+function ViaHook(): React.JSX.Element {
+  const isApple = useIsApplePlatform()
+  return <button type="button" title={isApple ? 'Bold (⌘B)' : 'Bold (Ctrl+B)'} />
+}
+
+/** How the toolbar read the platform before: straight from the constant. */
+function ViaConstant(): React.JSX.Element {
+  return <button type="button" title={IS_APPLE ? 'Bold (⌘B)' : 'Bold (Ctrl+B)'} />
+}
+
+const mounted: Array<{ root: { unmount: () => void }; container: HTMLDivElement }> = []
+
+afterEach(async () => {
+  for (const { root, container } of mounted.splice(0)) {
+    await act(async () => {
+      root.unmount()
+    })
+    container.remove()
+  }
+})
+
+async function hydrate(element: React.JSX.Element): Promise<{
+  container: HTMLDivElement
+  errors: string[]
+}> {
+  const errors: string[] = []
+  const spy = vi.spyOn(console, 'error').mockImplementation((...args) => {
+    errors.push(String(args[0]))
+  })
+
+  const container = document.createElement('div')
+  container.innerHTML = SERVER_MARKUP
+  document.body.appendChild(container)
+
+  let root: ReturnType<typeof hydrateRoot>
+  await act(async () => {
+    root = hydrateRoot(container, element)
+  })
+  // biome-ignore lint/style/noNonNullAssertion: assigned inside act
+  mounted.push({ root: root!, container })
+  spy.mockRestore()
+  return { container, errors }
+}
+
+describe('useIsApplePlatform', () => {
+  it('hydrates server markup without a mismatch, then adopts the platform', async () => {
+    const { container, errors } = await hydrate(<ViaHook />)
+
+    expect(errors.join(' ')).not.toMatch(/did not match|hydrat/i)
+    // Adopted after hydration, which is the whole point: the label is
+    // right for the reader without the first render disagreeing.
+    expect(container.querySelector('button')?.title).toBe('Bold (⌘B)')
+  })
+
+  it('CONTROL: reading the constant during render does mismatch', async () => {
+    // Pins why the hook exists. React reports this and, as it warns,
+    // does not patch the attribute up — leaving a Mac user looking at
+    // `Ctrl+B`, and a screen reader announcing it.
+    const { errors } = await hydrate(<ViaConstant />)
+    expect(errors.join(' ')).toMatch(/did not match|hydrat/i)
+  })
+})

package/src/field/hooks/use-platform-modifier.ts

@@ -0,0 +1,41 @@
+'use client'
+
+/**
+ * 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 { useSyncExternalStore } from 'react'
+
+import { IS_APPLE } from '../shared/environment'
+
+/** Never changes after load, so nothing to subscribe to. */
+const subscribe = () => () => {}
+
+/**
+ * Whether to label keyboard shortcuts the Apple way.
+ *
+ * `IS_APPLE` is resolved at module scope from `navigator.platform`, which
+ * is false on the server and true on a Mac client. Reading it directly
+ * during render therefore produced markup the server and client
+ * disagreed about — React reported a hydration mismatch on the toolbar's
+ * `title` and `aria-label` attributes and, as it warns, did not patch
+ * them up: a Mac user could be shown `Ctrl+B`, and a screen reader could
+ * announce it.
+ *
+ * `useSyncExternalStore` uses its server snapshot for the initial client
+ * render as well as for SSR, so the first client render matches the
+ * server exactly and the real platform is adopted immediately after.
+ */
+export function useIsApplePlatform(): boolean {
+  return useSyncExternalStore(
+    subscribe,
+    () => IS_APPLE,
+    // Server, and the hydrating client render: the platform is unknown
+    // to the server, so both must agree on the same answer.
+    () => false
+  )
+}

package/src/field/markdown/transformers.ts

@@ -42,8 +42,9 @@ import {
   TableNode,
   TableRowNode,
 } from '@lexical/table'
-import { $createParagraphNode, $isParagraphNode, $isTextNode } from 'lexical'
+import { $createParagraphNode, $getEditor, $isParagraphNode, $isTextNode } from 'lexical'
 
+import { transformersFor } from '../capabilities/filter-transformers'
 import {
   $createAdmonitionNode,
   $isAdmonitionNode,
@@ -82,6 +83,9 @@ export const TABLE: ElementTransformer = {
           // Cell content is itself markdown; escape literal newlines so the
           // row stays on one line.
           rowOutput.push(
+            // Unfiltered on purpose: export only ever meets nodes that
+            // are already in the tree, so an unregistered dependency
+            // simply never matches. Only the import direction can throw.
             $convertToMarkdownString(BYLINE_TRANSFORMERS, cell).replace(/\n/g, '\\n').trim()
           )
           if (cell.hasHeaderState(TableCellHeaderStates.ROW)) {
@@ -188,7 +192,10 @@ function getTableColumnsSize(table: TableNode): number {
 const $createTableCell = (textContent: string): TableCellNode => {
   const content = textContent.replace(/\\n/g, '\n')
   const cell = $createTableCellNode(TableCellHeaderStates.NO_STATUS)
-  $convertFromMarkdownString(content, BYLINE_TRANSFORMERS, cell)
+  // Filter to what this editor registered: a nested cell import creates
+  // nodes just as the top-level one does, so an unregistered dependency
+  // throws here too.
+  $convertFromMarkdownString(content, transformersFor($getEditor(), BYLINE_TRANSFORMERS), cell)
   return cell
 }
 
@@ -228,7 +235,7 @@ const ADMONITION_END_REG_EXP = /^:::\s*$/
 // paragraph bodies round-trip without any element transformer. Excluding the
 // block transformers here is what keeps headings / lists / tables / nested
 // admonitions out of an admonition body at parse time.
-const ADMONITION_BODY_TRANSFORMERS: Array<Transformer> = [...TEXT_FORMAT_TRANSFORMERS, LINK]
+export const ADMONITION_BODY_TRANSFORMERS: Array<Transformer> = [...TEXT_FORMAT_TRANSFORMERS, LINK]
 
 export const ADMONITION: MultilineElementTransformer = {
   dependencies: [AdmonitionNode],
@@ -241,6 +248,7 @@ export const ADMONITION: MultilineElementTransformer = {
 
     // The body is real children of `node` — export its subtree directly with
     // the same engine.
+    // Unfiltered on purpose — see the note on the table-cell export above.
     const body = $convertToMarkdownString(ADMONITION_BODY_TRANSFORMERS, node).trim()
 
     const heading = title ? `:::${type}[${title}]` : `:::${type}`
@@ -272,7 +280,13 @@ export const ADMONITION: MultilineElementTransformer = {
       // Import / toggle path: body arrives as raw text between the fences.
       const body = linesInBetween.join('\n').trim()
       if (body) {
-        $convertFromMarkdownString(body, ADMONITION_BODY_TRANSFORMERS, node)
+        // ADMONITION_BODY_TRANSFORMERS carries LINK, so this breaks when
+        // the link extension is removed unless it is filtered.
+        $convertFromMarkdownString(
+          body,
+          transformersFor($getEditor(), ADMONITION_BODY_TRANSFORMERS),
+          node
+        )
       }
     }
 

package/src/field/nodes/index.ts

@@ -23,7 +23,17 @@ import { AutoLinkNode, LinkNode } from '../extensions/link'
 import { VimeoNode } from '../extensions/vimeo/vimeo-node'
 import { YouTubeNode } from '../extensions/youtube/youtube-node'
 
-export const Nodes: Array<Klass<LexicalNode>> = [
+/**
+ * Every node class Byline knows how to READ.
+ *
+ * This is not a registration list — registration belongs to the
+ * extension that owns each node, so that removing an extension removes
+ * what the field accepts as well as what it offers. This array is the
+ * vocabulary the normalizer and the capability manifest work from, so a
+ * stored document can still be inspected by a field that supports far
+ * less than the document contains.
+ */
+export const READABLE_NODES: Array<Klass<LexicalNode>> = [
   HeadingNode,
   ListNode,
   ListItemNode,

package/src/field/normalize/adapted-notice.css

@@ -0,0 +1,52 @@
+@layer base,
+  byline-base,
+  theme,
+  byline-theme,
+  byline-functional,
+  byline-typography,
+  components,
+  byline-components,
+  utilities,
+  byline-utilities;
+
+/**
+ * Content-adaptation notices.
+ *
+ * Colours come from the UI kit's semantic tokens rather than literals so
+ * both notices follow the admin's theme. Hardcoded light values render
+ * as dark text on a pale block against the dark theme, which is the
+ * state these notices are least able to afford: one of them is the only
+ * thing a reader sees when a field will not open.
+ *
+ * Declared in `byline-components` so the layer order the admin
+ * establishes governs them, rather than Tailwind's preflight.
+ */
+@layer byline-components {
+  .byline-richtext-notice {
+    border-radius: var(--border-radius-sm, 4px);
+    font-size: var(--font-size-sm, 0.8125rem);
+    line-height: 1.4;
+    margin-bottom: 8px;
+    padding: 8px 10px;
+  }
+
+  .byline-richtext-notice p {
+    margin: 0;
+  }
+
+  .byline-richtext-notice p + p {
+    margin-top: 4px;
+  }
+
+  .byline-richtext-notice--adapted {
+    background-color: var(--fill-warning-weak);
+    border: 1px solid var(--stroke-warning);
+    color: var(--text-on-warning-weak);
+  }
+
+  .byline-richtext-notice--refused {
+    background-color: var(--fill-danger-weak);
+    border: 1px solid var(--stroke-danger);
+    color: var(--text-on-danger-weak);
+  }
+}

package/src/field/normalize/adapted-notice.tsx

@@ -0,0 +1,63 @@
+'use client'
+
+/**
+ * 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 * as React from 'react'
+
+import { contentLabelKey, joinLabels } from './content-labels'
+import { useNoticeText } from './use-notice-text'
+
+import './adapted-notice.css'
+
+/**
+ * Shown when stored content held a structure this field no longer
+ * supports and it was adapted for editing.
+ *
+ * Inline and non-blocking: the content is editable, and the adaptation
+ * only reaches storage if the reader actually saves an edit.
+ */
+export function AdaptedNotice(): React.JSX.Element {
+  const { t } = useNoticeText()
+  return (
+    <div className="byline-richtext-notice byline-richtext-notice--adapted" role="status">
+      {t('richtext.adapted.notice')}
+    </div>
+  )
+}
+
+/**
+ * Shown when stored content holds something with no safe conversion —
+ * an image, an embed, or a node type this build does not know.
+ *
+ * Those carry information no structural rewrite can preserve: an inline
+ * image has a media relation and a caption held in a nested editor.
+ * Discarding them silently would be worse than declining to edit, so the
+ * field opens read-only rather than adapting.
+ */
+export function UnsupportedContentNotice({
+  unsupportedTypes,
+}: {
+  unsupportedTypes: string[]
+}): React.JSX.Element {
+  const { t, locale } = useNoticeText()
+
+  // Known types get a readable name; anything else keeps its id, so a
+  // node from a site's own extension still produces a usable message.
+  const labels = unsupportedTypes.map((type) => {
+    const key = contentLabelKey(type)
+    return key != null ? t(key) : type
+  })
+
+  return (
+    <div className="byline-richtext-notice byline-richtext-notice--refused" role="alert">
+      <p>{t('richtext.unsupported.notice', { items: joinLabels(labels, locale) })}</p>
+      <p>{t('richtext.unsupported.action')}</p>
+    </div>
+  )
+}