@byline/richtext-lexical 5.2.0 → 6.0.1

package/src/scan/capability-manifest.test.tsx

@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'vitest'
+
+import { builtInExtensions } from '../field/config/built-in-extension-names'
+import { defaultClientEditorConfig } from '../field/config/default-extensions'
+import { buildManifest, capabilitiesFor } from './capability-manifest'
+import { scanDocument } from './scan-documents'
+
+function configWithout(...names: string[]) {
+  const extensions = defaultClientEditorConfig.extensions?.clone()
+  for (const name of names) extensions.remove(name)
+  return { ...defaultClientEditorConfig, extensions }
+}
+
+describe('capabilitiesFor', () => {
+  it('reports what the default configuration accepts', () => {
+    const caps = capabilitiesFor('pages', 'body', defaultClientEditorConfig)
+    for (const type of ['root', 'paragraph', 'text', 'heading', 'list', 'table', 'link']) {
+      expect(caps.supportedTypes, type).toContain(type)
+    }
+  })
+
+  it('omits a removed extensions node types', () => {
+    const caps = capabilitiesFor('pages', 'title', configWithout(builtInExtensions.Heading))
+    expect(caps.supportedTypes).not.toContain('heading')
+    expect(caps.supportedTypes).toContain('paragraph')
+  })
+
+  it('includes nodes contributed through dependencies, not just declared ones', () => {
+    // Table and list nodes arrive from @lexical/table and @lexical/list as
+    // dependencies of the Byline wrappers, so a manifest derived by
+    // walking declared `nodes` would miss them.
+    const caps = capabilitiesFor('pages', 'body', defaultClientEditorConfig)
+    expect(caps.supportedTypes).toContain('table')
+    expect(caps.supportedTypes).toContain('tablecell')
+    expect(caps.supportedTypes).toContain('listitem')
+  })
+
+  it('includes the always-on core nodes', () => {
+    const caps = capabilitiesFor(
+      'pages',
+      'body',
+      configWithout(...Object.values(builtInExtensions))
+    )
+    expect(caps.supportedTypes).toContain('mark')
+    expect(caps.supportedTypes).toContain('overflow')
+  })
+
+  it('feeds the scanner, which then agrees with the editor', () => {
+    const caps = capabilitiesFor('publications', 'title', configWithout(builtInExtensions.Heading))
+    // biome-ignore lint/suspicious/noExplicitAny: serialized fixture
+    const saved: any = {
+      root: {
+        children: [
+          {
+            children: [],
+            direction: null,
+            format: '',
+            indent: 0,
+            type: 'heading',
+            version: 1,
+            tag: 'h1',
+          },
+        ],
+        direction: null,
+        format: '',
+        indent: 0,
+        type: 'root',
+        version: 1,
+      },
+    }
+    const finding = scanDocument(saved, caps, { documentId: 'doc-1', versionId: 'ver-1' })
+    expect(finding?.adaptedTypes).toEqual(['heading'])
+  })
+})
+
+describe('buildManifest', () => {
+  it('stamps when it was generated', () => {
+    const manifest = buildManifest([capabilitiesFor('pages', 'body', defaultClientEditorConfig)])
+    expect(manifest.fields).toHaveLength(1)
+    expect(Number.isNaN(Date.parse(manifest.generatedAt))).toBe(false)
+  })
+})

package/src/scan/capability-manifest.ts

@@ -0,0 +1,81 @@
+'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 { buildEditorFromExtensions } from '@lexical/extension'
+import { ReactPluginHostExtension } from '@lexical/react/ReactPluginHostExtension'
+import { defineExtension } from 'lexical'
+
+import { registeredNodeTypes } from '../field/capabilities/registered-node-types'
+import { defaultExtensionsList } from '../field/config/default-extensions'
+import { rootDependencies } from '../field/config/root-dependencies'
+import type { EditorConfig } from '../field/config/types'
+import type { CapabilityManifest, FieldCapabilities } from './types'
+
+/**
+ * What one field accepts, measured by BUILDING its editor.
+ *
+ * Deliberately not derived by walking declared `nodes` on the extension
+ * list: that would recreate the resolver — dependency-contributed nodes,
+ * conflicts, replacements and always-on core nodes — and a manifest that
+ * disagrees with the runtime is worse than no manifest. This is the same
+ * construction `EditorContext` performs, so the two cannot drift.
+ *
+ * Requires a DOM and a React-capable module graph, because several
+ * extensions host React decorators. It therefore runs in a browser or
+ * jsdom, never in a plain Node script — which is why the manifest is a
+ * file handed to the scanner rather than something the scanner derives.
+ */
+export function capabilitiesFor(
+  collectionPath: string,
+  fieldPath: string,
+  config: Pick<EditorConfig, 'extensions' | 'lexical'>
+): FieldCapabilities {
+  const extensions = config.extensions ?? defaultExtensionsList()
+  const editor = buildEditorFromExtensions(
+    defineExtension({
+      name: '[capability-manifest]',
+      namespace: config.lexical?.namespace ?? 'LexicalRichText',
+      // Through the same seam the live editor uses — a manifest that
+      // disagreed about the always-on core nodes would misreport every
+      // document containing one.
+      // biome-ignore lint/suspicious/noExplicitAny: extension arguments are heterogeneous
+      dependencies: [ReactPluginHostExtension, ...rootDependencies(extensions)] as any,
+    })
+  )
+  const supportedTypes = [...registeredNodeTypes(editor)].sort()
+  editor.dispose()
+  return { collectionPath, fieldPath, supportedTypes }
+}
+
+/** Assemble a manifest from per-field capabilities. */
+export function buildManifest(fields: FieldCapabilities[]): CapabilityManifest {
+  return { generatedAt: new Date().toISOString(), fields }
+}
+
+/**
+ * What a live editor accepts.
+ *
+ * `capabilitiesFor` needs a resolved `EditorConfig`, which is not always
+ * reachable: `lexicalEditor()` closes over its configure callback inside
+ * a lazy component, so a site's own preset exposes no config to inspect.
+ * Measuring a mounted editor works for any field however its editor was
+ * registered, which is what a manifest walk over real collections needs.
+ */
+export function capabilitiesFromEditor(
+  collectionPath: string,
+  fieldPath: string,
+  editor: Parameters<typeof registeredNodeTypes>[0]
+): FieldCapabilities {
+  return {
+    collectionPath,
+    fieldPath,
+    supportedTypes: [...registeredNodeTypes(editor)].sort(),
+  }
+}

package/src/scan/scan-documents.test.node.ts

@@ -0,0 +1,125 @@
+import { describe, expect, it } from 'vitest'
+
+import { scanDocument, summarise } from './scan-documents'
+import type { FieldCapabilities } from './types'
+
+const caps: FieldCapabilities = {
+  collectionPath: 'publications',
+  fieldPath: 'title',
+  supportedTypes: ['root', 'paragraph', 'text'],
+}
+const ids = { documentId: 'doc-1', versionId: 'ver-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 },
+})
+const heading = () => ({
+  children: [],
+  direction: null,
+  format: '',
+  indent: 0,
+  type: 'heading',
+  version: 1,
+  tag: 'h1',
+})
+
+describe('scanDocument', () => {
+  it('reports nothing for a clean document', () => {
+    const clean = doc({
+      children: [],
+      direction: null,
+      format: '',
+      indent: 0,
+      type: 'paragraph',
+      version: 1,
+    })
+    expect(scanDocument(clean, caps, ids)).toBeUndefined()
+  })
+
+  it('reports nothing for an absent value', () => {
+    expect(scanDocument(undefined, caps, ids)).toBeUndefined()
+    expect(scanDocument(null, caps, ids)).toBeUndefined()
+  })
+
+  it('reports an adaptable heading', () => {
+    const finding = scanDocument(doc(heading()), caps, ids)
+    expect(finding?.adaptedTypes).toEqual(['heading'])
+    expect(finding?.refusedTypes).toEqual([])
+  })
+
+  it('reports a refusing inline image separately', () => {
+    const finding = scanDocument(doc({ type: 'inline-image', version: 1 }), caps, ids)
+    expect(finding?.refusedTypes).toContain('inline-image')
+    expect(finding?.adaptedTypes).toEqual([])
+  })
+
+  it('keeps the stored instance path so sibling values are distinguishable', () => {
+    // Two captions in one block field share a declaration path; only the
+    // instance path tells them apart.
+    const first = scanDocument(doc(heading()), caps, {
+      ...ids,
+      instancePath: 'content.1.photoBlock.caption',
+    })
+    const second = scanDocument(doc(heading()), caps, {
+      ...ids,
+      instancePath: 'content.3.photoBlock.caption',
+    })
+    expect(first?.instancePath).toBe('content.1.photoBlock.caption')
+    expect(second?.instancePath).toBe('content.3.photoBlock.caption')
+    expect(first?.fieldPath).toBe(second?.fieldPath)
+  })
+
+  it('reports findings against a localized, nested field path', () => {
+    const nested = { ...caps, fieldPath: 'content.1.photoBlock.caption' }
+    const finding = scanDocument(doc(heading()), nested, { ...ids, locale: 'fr' })
+    expect(finding?.fieldPath).toBe('content.1.photoBlock.caption')
+    expect(finding?.locale).toBe('fr')
+  })
+
+  it('reports an archived version distinctly from the current one', () => {
+    const current = scanDocument(doc(heading()), caps, { documentId: 'doc-1', versionId: 'ver-2' })
+    const archived = scanDocument(doc(heading()), caps, { documentId: 'doc-1', versionId: 'ver-1' })
+    expect(current?.versionId).toBe('ver-2')
+    expect(archived?.versionId).toBe('ver-1')
+  })
+
+  it('reports a field whose capabilities were never measured, rather than silence', () => {
+    const unknown: FieldCapabilities = {
+      ...caps,
+      supportedTypes: null,
+      unresolvedReason: 'no editor',
+    }
+    const finding = scanDocument(doc(heading()), unknown, ids)
+    expect(finding?.unmapped).toBe(true)
+    expect(finding?.adaptedTypes).toEqual([])
+    expect(finding?.refusedTypes).toEqual([])
+  })
+
+  it('reports unmapped even for content that would otherwise look clean', () => {
+    const unknown: FieldCapabilities = { ...caps, supportedTypes: null }
+    const clean = doc({
+      children: [],
+      direction: null,
+      format: '',
+      indent: 0,
+      type: 'paragraph',
+      version: 1,
+    })
+    // The point of the rule: a clean-looking document under unknown
+    // capabilities is still unexamined.
+    expect(scanDocument(clean, unknown, ids)?.unmapped).toBe(true)
+  })
+
+  it('separates what will adapt from what will open read-only', () => {
+    const findings = [
+      scanDocument(doc(heading()), caps, ids),
+      scanDocument(doc({ type: 'youtube', version: 1 }), caps, { ...ids, versionId: 'ver-2' }),
+    ].filter((finding): finding is NonNullable<typeof finding> => finding != null)
+
+    const { adapted, refused, unmapped } = summarise(findings)
+    expect(adapted).toHaveLength(1)
+    expect(refused).toHaveLength(1)
+    expect(unmapped).toHaveLength(0)
+    expect(refused[0]?.refusedTypes).toContain('youtube')
+  })
+})

package/src/scan/scan-documents.ts

@@ -0,0 +1,78 @@
+/**
+ * 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 { normalizeValue } from '../field/normalize/normalize-value'
+import type { FieldCapabilities, ScanFinding } from './types'
+
+/**
+ * Report what a field's current configuration will do with one stored
+ * value.
+ *
+ * Runs the same `normalizeValue` the editor runs, rather than a parallel
+ * rule set, so the report cannot drift from the behaviour it predicts.
+ * Pure: no database, no DOM, no editor.
+ */
+export function scanDocument(
+  value: SerializedEditorState | null | undefined,
+  capabilities: FieldCapabilities,
+  ids: { documentId: string; versionId: string; locale?: string; instancePath?: string }
+): ScanFinding | undefined {
+  if (value == null) return undefined
+
+  // Capabilities that could not be measured produce a finding, never
+  // silence. Skipping here would report the document clean on the
+  // strength of never having looked at it.
+  if (capabilities.supportedTypes == null) {
+    const unmapped: ScanFinding = {
+      collectionPath: capabilities.collectionPath,
+      fieldPath: capabilities.fieldPath,
+      documentId: ids.documentId,
+      versionId: ids.versionId,
+      adaptedTypes: [],
+      refusedTypes: [],
+      unmapped: true,
+    }
+    if (ids.locale != null) unmapped.locale = ids.locale
+    if (ids.instancePath != null) unmapped.instancePath = ids.instancePath
+    return unmapped
+  }
+
+  const result = normalizeValue(value, new Set(capabilities.supportedTypes))
+  if (result.status === 'unchanged') return undefined
+
+  const finding: ScanFinding = {
+    collectionPath: capabilities.collectionPath,
+    fieldPath: capabilities.fieldPath,
+    documentId: ids.documentId,
+    versionId: ids.versionId,
+    adaptedTypes: result.status === 'adapted' ? result.convertedTypes : [],
+    refusedTypes: result.status === 'refused' ? result.unsupportedTypes : [],
+  }
+  if (ids.locale != null) finding.locale = ids.locale
+  if (ids.instancePath != null) finding.instancePath = ids.instancePath
+  return finding
+}
+
+/** Group findings for a report: what will adapt, and what will open read-only. */
+export function summarise(findings: ScanFinding[]): {
+  adapted: ScanFinding[]
+  refused: ScanFinding[]
+  unmapped: ScanFinding[]
+} {
+  return {
+    adapted: findings.filter(
+      (finding) => finding.unmapped !== true && finding.refusedTypes.length === 0
+    ),
+    refused: findings.filter(
+      (finding) => finding.unmapped !== true && finding.refusedTypes.length > 0
+    ),
+    unmapped: findings.filter((finding) => finding.unmapped === true),
+  }
+}

package/src/scan/types.ts

@@ -0,0 +1,66 @@
+/**
+ * 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
+ */
+
+/** What one richtext field accepts, as its resolved editor reports it. */
+export interface FieldCapabilities {
+  collectionPath: string
+  /**
+   * Declaration path of the field, so one nested in a block or array is
+   * addressable — `content.photoBlock.caption`, not just `caption`.
+   * Stored values carry instance paths (`content.1.photoBlock.caption`);
+   * eliding the selectors yields this.
+   */
+  fieldPath: string
+  /**
+   * Node types the field accepts, or `null` when they could not be
+   * measured.
+   *
+   * A field whose capabilities are unknown is NOT the same as a field
+   * with none. The scanner reports it as unmapped rather than treating
+   * its documents as clean, because reporting a document safe when it
+   * was never examined is the one failure an upgrade check must not
+   * have.
+   */
+  supportedTypes: string[] | null
+  /** Why the capabilities could not be measured, when they could not. */
+  unresolvedReason?: string
+}
+
+/**
+ * Field capabilities for a whole installation, produced where the client
+ * config can be loaded and consumed where the database can.
+ */
+export interface CapabilityManifest {
+  generatedAt: string
+  fields: FieldCapabilities[]
+}
+
+/** One stored value that this field's current configuration cannot take as-is. */
+export interface ScanFinding {
+  collectionPath: string
+  /** Declaration path — the manifest key this value was matched against. */
+  fieldPath: string
+  /**
+   * Instance path as stored, when the caller knows it —
+   * `content.1.photoBlock.caption`. Two affected captions in one version
+   * share a declaration path and are told apart only by this.
+   */
+  instancePath?: string
+  documentId: string
+  versionId: string
+  locale?: string
+  /** Structures that will be converted when the field opens this value. */
+  adaptedTypes: string[]
+  /** Structures with no conversion — the field will open read-only. */
+  refusedTypes: string[]
+  /**
+   * Set when the field's capabilities were never measured, so this value
+   * was not examined. Neither adapted nor refused: unknown.
+   */
+  unmapped?: true
+}

package/src/scan.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
+ */
+
+/**
+ * Pre-upgrade scanning, without the editor.
+ *
+ * This entry is deliberately **runtime-free**: it carries the pure
+ * scanning logic and its types, and imports no React, no Lexical
+ * extension and no CSS. A Node script can therefore read it, which the
+ * root barrel makes impossible — importing that pulls the editor graph
+ * and fails on the first `.css` import.
+ *
+ * The other half, measuring what a field accepts, needs a DOM and lives
+ * on the root entry as `capabilitiesFor` / `capabilitiesFromEditor`.
+ * That split is the same boundary the manifest crosses: capabilities are
+ * measured in a browser, written to a file, and consumed here.
+ *
+ * See docs/09-admin-ui/04-richtext-capabilities.md.
+ */
+
+export { scanDocument, summarise } from './scan/scan-documents'
+export type { CapabilityManifest, FieldCapabilities, ScanFinding } from './scan/types'