@byline/richtext-lexical 5.2.0 → 6.0.0

package/src/field/normalize/normalize-value.ts

@@ -0,0 +1,180 @@
+/**
+ * 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 { SerializedEditorState } from 'lexical'
+
+import {
+  conversionFor,
+  isBlockType,
+  isInlineType,
+  type SerializedNode,
+} from './declared-conversions'
+
+export type NormalizeResult =
+  | { status: 'unchanged' }
+  | { status: 'adapted'; value: SerializedEditorState; convertedTypes: string[] }
+  | { status: 'refused'; unsupportedTypes: string[] }
+
+const textNode = (text: string): SerializedNode => ({
+  detail: 0,
+  format: 0,
+  mode: 'normal',
+  style: '',
+  text,
+  type: 'text',
+  version: 1,
+})
+
+/** A plain text node carrying another node's own text and inline formats. */
+const textFromNode = (node: SerializedNode): SerializedNode => ({
+  detail: typeof node.detail === 'number' ? node.detail : 0,
+  format: typeof node.format === 'number' ? node.format : 0,
+  mode: typeof node.mode === 'string' ? node.mode : 'normal',
+  style: typeof node.style === 'string' ? node.style : '',
+  text: typeof node.text === 'string' ? node.text : '',
+  type: 'text',
+  version: 1,
+})
+
+const paragraphNode = (children: SerializedNode[]): SerializedNode => ({
+  children,
+  direction: null,
+  format: '',
+  indent: 0,
+  type: 'paragraph',
+  version: 1,
+})
+
+/**
+ * Adapt a stored value to what an editor can actually accept.
+ *
+ * Lexical throws `parseEditorState: type "X" + not found` on an
+ * unregistered type and the text is unrecoverable, so a field that no
+ * longer supports a structure would otherwise open blank and erroring.
+ *
+ * Only the unsupported nodes are converted. A supported node is copied
+ * with its own properties intact — it was already in a valid position in
+ * the saved document, so its position is never changed — while its
+ * children are still inspected, because a supported parent may hold an
+ * unsupported descendant. Re-encoding supported content to fix an
+ * unrelated structure is exactly what this must not do: an inline image
+ * sitting beside a heading would lose its media relation and its
+ * nested-editor caption as collateral.
+ *
+ * The input is never mutated. Refusal wins over any conversion, so the
+ * whole tree is walked before a decision is returned.
+ */
+export function normalizeValue(
+  value: SerializedEditorState,
+  supportedTypes: ReadonlySet<string>
+): NormalizeResult {
+  const converted = new Set<string>()
+  const refused = new Set<string>()
+
+  /**
+   * Wrap runs of inline nodes in paragraphs, leaving blocks where they
+   * are. A converted block's children are not guaranteed to be inline —
+   * a `listitem` may hold a nested `list` — so turning the whole lot
+   * into one paragraph would nest a block inside a paragraph.
+   *
+   * A node whose role is in neither list is refused rather than assumed
+   * inline: it may be a supported custom block from a downstream site,
+   * and wrapping one in a paragraph produces a tree Lexical rejects.
+   */
+  function groupIntoBlocks(nodes: SerializedNode[]): SerializedNode[] {
+    const out: SerializedNode[] = []
+    let run: SerializedNode[] = []
+    const flush = () => {
+      if (run.length > 0) {
+        out.push(paragraphNode(run))
+        run = []
+      }
+    }
+    for (const node of nodes) {
+      if (isInlineType(node.type)) {
+        run.push(node)
+        continue
+      }
+      if (!isBlockType(node.type)) {
+        // Unknown structural role — do not guess.
+        refused.add(node.type)
+      }
+      flush()
+      out.push(node)
+    }
+    flush()
+    return out
+  }
+
+  function visit(node: SerializedNode): SerializedNode[] {
+    const children = Array.isArray(node.children) ? (node.children as SerializedNode[]) : undefined
+
+    if (node.type === 'root' || supportedTypes.has(node.type)) {
+      return children == null ? [node] : [{ ...node, children: children.flatMap(visit) }]
+    }
+
+    // Unsupported with no declared conversion: never guessed at.
+    const conversion = conversionFor(node.type)
+    if (conversion == null) {
+      refused.add(node.type)
+      return [node]
+    }
+
+    converted.add(node.type)
+    const preserved = conversion.preserveText?.(node)
+    const inner = (children ?? []).flatMap(visit)
+
+    switch (conversion.kind) {
+      case 'drop':
+        return []
+
+      // One block in, at least one block out — so adjacent blocks stay
+      // separate and an empty one stays an empty line. Children are
+      // partitioned rather than assumed inline, because a list item may
+      // hold a nested list.
+      case 'to-paragraph': {
+        const children = preserved != null ? [...inner, textNode(` ${preserved}`)] : inner
+        const grouped = groupIntoBlocks(children)
+        return grouped.length > 0 ? grouped : [paragraphNode([])]
+      }
+
+      // A text-carrying leaf keeps its text and inline formats.
+      case 'to-text':
+        return [textFromNode(node)]
+
+      // Children are already blocks. Preserved text leads as its own
+      // paragraph, so an admonition title becomes the first line.
+      case 'lift-blocks':
+        return preserved != null ? [paragraphNode([textNode(preserved)]), ...inner] : inner
+
+      // Inline content stays inline, inside the paragraph that held it.
+      case 'unwrap-inline':
+        return preserved != null ? [...inner, textNode(` ${preserved}`)] : inner
+    }
+  }
+
+  const visited = visit(value.root as unknown as SerializedNode)[0]
+
+  if (refused.size > 0) return { status: 'refused', unsupportedTypes: [...refused] }
+  if (converted.size === 0) return { status: 'unchanged' }
+
+  // Lexical rejects an empty root — "setEditorState: the editor state is
+  // empty" — and conversion can empty one, for instance a document whose
+  // only node was a horizontal rule that this field drops.
+  const children = Array.isArray(visited.children) ? visited.children : []
+  const nextRoot: SerializedNode = {
+    ...visited,
+    children: children.length > 0 ? children : [paragraphNode([])],
+  }
+
+  return {
+    status: 'adapted',
+    value: { ...value, root: nextRoot } as unknown as SerializedEditorState,
+    convertedTypes: [...converted],
+  }
+}

package/src/field/normalize/notice-i18n.test.tsx

@@ -0,0 +1,128 @@
+import { act } from 'react'
+
+import { adminTranslations } from '@byline/i18n/admin'
+import { I18nProvider } from '@byline/i18n/react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { AdaptedNotice, UnsupportedContentNotice } from './adapted-notice'
+
+// biome-ignore lint/suspicious/noExplicitAny: React act environment flag
+;(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true
+
+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 renderWithBundle(
+  node: React.ReactNode,
+  // biome-ignore lint/suspicious/noExplicitAny: hand-built partial bundle
+  bundle: any,
+  locale: string
+): Promise<HTMLDivElement> {
+  const container = document.createElement('div')
+  document.body.appendChild(container)
+  const root = createRoot(container)
+  mounted.push({ root, container })
+  await act(async () => {
+    root.render(
+      <I18nProvider
+        bundle={bundle}
+        activeLocale={locale}
+        defaultLocale="en"
+        localeDefinitions={[{ code: 'en', name: 'English' }]}
+        onMissing={() => {}}
+      >
+        {node}
+      </I18nProvider>
+    )
+  })
+  return container
+}
+
+async function render(node: React.ReactNode, locale?: string): Promise<HTMLDivElement> {
+  const container = document.createElement('div')
+  document.body.appendChild(container)
+  const root = createRoot(container)
+  mounted.push({ root, container })
+
+  await act(async () => {
+    root.render(
+      locale == null ? (
+        node
+      ) : (
+        <I18nProvider
+          bundle={adminTranslations({ locales: ['en', 'fr'] })}
+          activeLocale={locale}
+          defaultLocale="en"
+          localeDefinitions={[
+            { code: 'en', name: 'English' },
+            { code: 'fr', name: 'Français' },
+          ]}
+        >
+          {node}
+        </I18nProvider>
+      )
+    )
+  })
+  return container
+}
+
+describe('notice translation', () => {
+  it('renders English without any provider', async () => {
+    // The editor can mount outside the admin shell, and `useTranslation`
+    // throws when no provider is present — a notice must never be the
+    // thing that breaks a field.
+    const container = await render(<AdaptedNotice />)
+    expect(container.textContent).toContain('no longer supports')
+    expect(container.textContent).not.toContain('richtext.adapted.notice')
+  })
+
+  it('renders English through the provider', async () => {
+    const container = await render(<AdaptedNotice />, 'en')
+    expect(container.textContent).toContain('no longer supports')
+  })
+
+  it('renders French through the provider', async () => {
+    const container = await render(<AdaptedNotice />, 'fr')
+    expect(container.textContent).toContain('ne prend plus en charge')
+    expect(container.textContent).not.toContain('no longer supports')
+  })
+
+  it('translates content names and joins them for the locale', async () => {
+    const container = await render(
+      <UnsupportedContentNotice unsupportedTypes={['inline-image', 'youtube']} />,
+      'fr'
+    )
+    expect(container.textContent).toContain('une image')
+    expect(container.textContent).toContain('YouTube')
+    // Joined the way the locale writes a list, not with a bare comma.
+    expect(container.textContent).toContain(' et ')
+  })
+
+  it('falls back to English when the provider bundle predates these keys', async () => {
+    // A site pinned to an older @byline/i18n has a provider but no such
+    // key. The formatter's last resort is the raw key, which would put
+    // `richtext.adapted.notice` in front of a reader.
+    const stale = { en: { 'byline-admin': { 'common.actions.save': 'Save' } } }
+    const container = await renderWithBundle(<AdaptedNotice />, stale, 'en')
+    expect(container.textContent).toContain('no longer supports')
+    expect(container.textContent).not.toContain('richtext.adapted.notice')
+  })
+
+  it('keeps an unknown type as its id in any locale', async () => {
+    const container = await render(
+      <UnsupportedContentNotice unsupportedTypes={['acme-callout']} />,
+      'fr'
+    )
+    expect(container.textContent).toContain('acme-callout')
+    expect(container.textContent).toContain('lecture seule')
+  })
+})

package/src/field/normalize/use-notice-text.ts

@@ -0,0 +1,82 @@
+'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 { useContext, useMemo } from 'react'
+
+import { I18nContext } from '@byline/i18n/react'
+
+/**
+ * English text for every key this package renders.
+ *
+ * These duplicate the `byline-admin` bundle on purpose, and cover two
+ * different failures:
+ *
+ *  - No provider at all. The editor can be mounted outside the admin
+ *    shell — a host embedding a field, an error boundary rendering
+ *    without its route's providers — and `useTranslation` throws when
+ *    none is present. A notice must never be the thing that breaks a
+ *    field.
+ *  - A provider whose bundle predates these keys, on a site pinned to an
+ *    older `@byline/i18n`. The formatter's last resort is the raw key,
+ *    so without this the reader would see `richtext.unsupported.notice`.
+ */
+const FALLBACKS: Readonly<Record<string, string>> = {
+  'richtext.adapted.notice':
+    'This content contains formatting this editor no longer supports. Saving edits will use the supported formatting.',
+  'richtext.unsupported.notice':
+    'This content contains {items}, which this field no longer supports. The field is read-only so the content is not lost.',
+  'richtext.unsupported.action':
+    'Ask an administrator to restore support for it, or to migrate the content.',
+  'richtext.content.image': 'an image',
+  'richtext.content.youtube': 'a YouTube embed',
+  'richtext.content.vimeo': 'a Vimeo embed',
+}
+
+export interface NoticeText {
+  t: (key: string, values?: Record<string, string>) => string
+  locale: string
+}
+
+/**
+ * Translate a notice, tolerating the absence of an I18nProvider.
+ *
+ * Reads `I18nContext` directly rather than calling `useTranslation`,
+ * which throws without a provider.
+ */
+export function useNoticeText(): NoticeText {
+  const context = useContext(I18nContext)
+
+  return useMemo(() => {
+    if (context == null) {
+      return {
+        locale: 'en',
+        t: (key, values) => interpolate(FALLBACKS[key] ?? key, values),
+      }
+    }
+    return {
+      locale: context.activeLocale,
+      t: (key, values) => {
+        const translated = context.formatter.t('byline-admin', key, values)
+        // The formatter's last resort is the raw key, which happens when
+        // a provider IS mounted but its bundle predates these keys — a
+        // site pinned to an older @byline/i18n. Falling back only on a
+        // missing provider would leave that reader looking at
+        // `richtext.unsupported.notice`, so treat a key echo as a miss.
+        return translated === key ? interpolate(FALLBACKS[key] ?? key, values) : translated
+      },
+    }
+  }, [context])
+}
+
+/** Minimal `{name}` substitution for the provider-less fallback path. */
+function interpolate(template: string, values?: Record<string, string>): string {
+  if (values == null) return template
+  return template.replace(/\{(\w+)\}/g, (match, name) => values[name] ?? match)
+}