@lexical/html 0.44.1-nightly.20260518.0 → 0.45.0

package/src/RenderContext.ts

@@ -0,0 +1,168 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+import type {EditorDOMRenderConfig} from 'lexical';
+
+import {getPeerDependencyFromEditor} from '@lexical/extension';
+import {$getEditor, $getEditorDOMRenderConfig, LexicalEditor} from 'lexical';
+
+import {DOMRenderContextSymbol, DOMRenderExtensionName} from './constants';
+import {
+  $withContext,
+  createContextState,
+  getContextRecord,
+  getContextValue,
+} from './ContextRecord';
+import {DOMRenderExtension} from './DOMRenderExtension';
+import {
+  AnyRenderStateConfigPairOrUpdater,
+  ContextRecord,
+  RenderStateConfig,
+} from './types';
+
+/**
+ * Create a context state to be used during render.
+ *
+ * Note that to support the ValueOrUpdater pattern you can not use a
+ * function for V (but you may wrap it in an array or object).
+ *
+ * @experimental
+ * @__NO_SIDE_EFFECTS__
+ */
+export function createRenderState<V>(
+  name: string,
+  getDefaultValue: () => V,
+  isEqual?: (a: V, b: V) => boolean,
+): RenderStateConfig<V> {
+  return createContextState(
+    DOMRenderContextSymbol,
+    name,
+    getDefaultValue,
+    isEqual,
+  );
+}
+
+/**
+ * Render context state that is true if the export was initiated from the root of the document.
+ * @experimental
+ */
+export const RenderContextRoot = createRenderState('root', Boolean);
+
+/**
+ * Render context state that is true if this is an export operation ($generateHtmlFromNodes).
+ * @experimental
+ */
+export const RenderContextExport = createRenderState('isExport', Boolean);
+
+function getDefaultRenderContext(
+  editor: LexicalEditor,
+): undefined | ContextRecord<typeof DOMRenderContextSymbol> {
+  const dep = getPeerDependencyFromEditor<typeof DOMRenderExtension>(
+    editor,
+    DOMRenderExtensionName,
+  );
+  return dep ? dep.output.defaults : undefined;
+}
+
+function getRenderContext(
+  editor: LexicalEditor,
+): undefined | ContextRecord<typeof DOMRenderContextSymbol> {
+  return (
+    getContextRecord(DOMRenderContextSymbol, editor) ||
+    getDefaultRenderContext(editor)
+  );
+}
+
+/**
+ * Get a render context value during a DOM render or export operation.
+ * @experimental
+ */
+export function $getRenderContextValue<V>(
+  cfg: RenderStateConfig<V>,
+  editor: LexicalEditor = $getEditor(),
+): V {
+  return getContextValue(getRenderContext(editor), cfg);
+}
+
+function getRuntime(editor: LexicalEditor) {
+  const dep = getPeerDependencyFromEditor<typeof DOMRenderExtension>(
+    editor,
+    DOMRenderExtensionName,
+  );
+  return dep ? dep.output.runtime : undefined;
+}
+
+/**
+ * Imperatively set a value in the persistent editor render context.
+ *
+ * Unlike {@link $withRenderContext} (which scopes values to a callback), this
+ * persists on the editor. If the change flips any override's
+ * `disabledForEditor` result, the resident render config is recompiled and the
+ * affected nodes are re-rendered. No-op if {@link DOMRenderExtension} is not
+ * installed.
+ *
+ * @experimental
+ */
+export function $setRenderContextValue<V>(
+  cfg: RenderStateConfig<V>,
+  value: V,
+  editor: LexicalEditor = $getEditor(),
+): void {
+  const runtime = getRuntime(editor);
+  if (runtime) {
+    runtime.setContextValue(cfg, value);
+  }
+}
+
+/**
+ * Imperatively update a value in the persistent editor render context with an
+ * updater function. See {@link $setRenderContextValue}.
+ *
+ * @experimental
+ */
+export function $updateRenderContextValue<V>(
+  cfg: RenderStateConfig<V>,
+  updater: (prev: V) => V,
+  editor: LexicalEditor = $getEditor(),
+): void {
+  const runtime = getRuntime(editor);
+  if (runtime) {
+    runtime.setContextValue(
+      cfg,
+      updater(getContextValue(runtime.editorContext, cfg)),
+    );
+  }
+}
+
+/**
+ * Resolve the {@link EditorDOMRenderConfig} to use for the current
+ * export/generate session, applying any `disabledForSession` overrides against
+ * the active session context. Falls back to the editor's resident config when
+ * {@link DOMRenderExtension} is not installed.
+ *
+ * @experimental
+ */
+export function $getSessionDOMRenderConfig(
+  editor: LexicalEditor = $getEditor(),
+): EditorDOMRenderConfig {
+  const runtime = getRuntime(editor);
+  return runtime
+    ? runtime.getSessionConfig()
+    : $getEditorDOMRenderConfig(editor);
+}
+
+/**
+ * Execute a callback within a render context with the given config pairs.
+ * @experimental
+ */
+export const $withRenderContext: (
+  cfg: readonly AnyRenderStateConfigPairOrUpdater[],
+  editor?: LexicalEditor,
+) => <T>(f: () => T) => T = $withContext(
+  DOMRenderContextSymbol,
+  getDefaultRenderContext,
+);

package/src/compileDOMRenderConfigOverrides.ts

@@ -0,0 +1,416 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+import {getKnownTypesAndNodes} from '@lexical/extension';
+import invariant from '@lexical/internal/invariant';
+import {
+  $isLexicalNode,
+  DEFAULT_EDITOR_DOM_CONFIG,
+  type EditorDOMRenderConfig,
+  getStaticNodeConfig,
+  InitialEditorConfig,
+  Klass,
+  LexicalEditor,
+  type LexicalNode,
+} from 'lexical';
+
+import {ALWAYS_TRUE} from './constants';
+import {AnyDOMRenderMatch, DOMRenderConfig, DOMRenderMatch} from './types';
+
+interface TypeRecord {
+  readonly klass: Klass<LexicalNode>;
+  readonly types: {[NodeAndSubclasses in string]?: boolean};
+}
+
+type TypeTree = {
+  [NodeType in string]?: TypeRecord;
+};
+
+export function buildTypeTree(
+  editorConfig: Pick<InitialEditorConfig, 'nodes'>,
+): TypeTree {
+  const t: TypeTree = {};
+  const {nodes} = getKnownTypesAndNodes(editorConfig);
+  for (const klass of nodes) {
+    const type = klass.getType();
+    t[type] = {klass, types: {}};
+  }
+  for (const baseRec of Object.values(t)) {
+    if (baseRec) {
+      const baseType = baseRec.klass.getType();
+      for (
+        let {klass} = baseRec;
+        $isLexicalNode(klass.prototype);
+        klass = Object.getPrototypeOf(klass)
+      ) {
+        const {ownNodeType} = getStaticNodeConfig(klass);
+        const superRec = ownNodeType && t[ownNodeType];
+        if (superRec) {
+          superRec.types[baseType] = true;
+        }
+      }
+    }
+  }
+  return t;
+}
+
+type PredicateOrTypes =
+  | ((node: LexicalNode) => boolean)
+  | {[NodeType in string]?: true};
+type TypeRender<T> = {[NodeType in string]?: T[]};
+type AnyRender<T> =
+  | readonly [(node: LexicalNode) => boolean, T]
+  | readonly ['types', TypeRender<T>];
+
+type PreEditorDOMRenderConfig = {
+  [K in keyof EditorDOMRenderConfig]: AnyRender<AnyDOMRenderMatch[K]>[];
+};
+
+function buildNodePredicate<T extends LexicalNode>(klass: Klass<T>) {
+  return (node: LexicalNode): node is T => node instanceof klass;
+}
+
+function getPredicate(
+  typeTree: TypeTree,
+  {nodes}: DOMRenderMatch<LexicalNode>,
+): {[NodeType in string]?: true} | ((node: LexicalNode) => boolean) {
+  if (nodes === '*') {
+    return ALWAYS_TRUE;
+  }
+  let types: undefined | {[NodeType in string]?: true} = {};
+  const predicates: ((node: LexicalNode) => boolean)[] = [];
+  for (const klassOrPredicate of nodes) {
+    if ('getType' in klassOrPredicate) {
+      const type = klassOrPredicate.getType();
+      if (types) {
+        const tree = typeTree[type];
+        invariant(
+          tree !== undefined,
+          'Node class %s with type %s not registered in editor',
+          klassOrPredicate.name,
+          type,
+        );
+        types = Object.assign(types, tree.types);
+      }
+      predicates.push(buildNodePredicate(klassOrPredicate));
+    } else {
+      types = undefined;
+      predicates.push(klassOrPredicate);
+    }
+  }
+  if (types) {
+    return types;
+  } else if (predicates.length === 1) {
+    return predicates[0];
+  }
+  return (node: LexicalNode): boolean => {
+    for (const predicate of predicates) {
+      if (predicate(node)) {
+        return true;
+      }
+    }
+    return false;
+  };
+}
+
+function makePrerender(): PreEditorDOMRenderConfig {
+  return {
+    $createDOM: [],
+    $decorateDOM: [],
+    $exportDOM: [],
+    $extractWithChild: [],
+    $getDOMSlot: [],
+    $shouldExclude: [],
+    $shouldInclude: [],
+    $updateDOM: [],
+  };
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AccFn<T, N extends LexicalNode, Args extends any[]> = (
+  node: N,
+  ...rest: [...Args, editor: LexicalEditor]
+) => T;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type GetOverrideFn<T, N extends LexicalNode, Args extends any[]> = (
+  n: N,
+) => undefined | OverrideFn<T, N, Args>;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type OverrideFn<T, N extends LexicalNode, Args extends any[]> = (
+  node: N,
+  ...rest: [...Args, $next: () => T, editor: LexicalEditor]
+) => T;
+
+function ignoreNext2<T, N extends LexicalNode>(
+  acc: AccFn<T, N, []>,
+): OverrideFn<T, N, []> {
+  return (node: N, _$next: () => T, editor: LexicalEditor) => acc(node, editor);
+}
+function ignoreNext3<T, N extends LexicalNode, A>(
+  acc: AccFn<T, N, [A]>,
+): OverrideFn<T, N, [A]> {
+  return (node: N, a: A, _$next: () => T, editor: LexicalEditor) =>
+    acc(node, a, editor);
+}
+function ignoreNext4<T, N extends LexicalNode, A, B>(
+  acc: AccFn<T, N, [A, B]>,
+): OverrideFn<T, N, [A, B]> {
+  return (node: N, a: A, b: B, _$next: () => T, editor: LexicalEditor) =>
+    acc(node, a, b, editor);
+}
+function ignoreNext5<T, N extends LexicalNode, A, B, C>(
+  acc: AccFn<T, N, [A, B, C]>,
+): OverrideFn<T, N, [A, B, C]> {
+  return (node: N, a: A, b: B, c: C, _$next: () => T, editor: LexicalEditor) =>
+    acc(node, a, b, c, editor);
+}
+
+function merge2<T, N extends LexicalNode>(
+  $acc: AccFn<T, N, []>,
+  $getOverride: GetOverrideFn<T, N, []>,
+): typeof $acc {
+  return (node, editor) => {
+    const $next = () => $acc(node, editor);
+    const $override = $getOverride(node);
+    return $override ? $override(node, $next, editor) : $next();
+  };
+}
+
+function merge3<T, N extends LexicalNode, A>(
+  acc: AccFn<T, N, [A]>,
+  $getOverride: GetOverrideFn<T, N, [A]>,
+): typeof acc {
+  return (node, a, editor) => {
+    const $next = () => acc(node, a, editor);
+    const $override = $getOverride(node);
+    return $override ? $override(node, a, $next, editor) : $next();
+  };
+}
+
+const merge3GetDOMSlot = merge3 as (
+  acc: EditorDOMRenderConfig['$getDOMSlot'],
+  $getOverride: (n: LexicalNode) => DOMRenderMatch<LexicalNode>['$getDOMSlot'],
+) => EditorDOMRenderConfig['$getDOMSlot'];
+
+const ignoreNext3GetDOMSlot = ignoreNext3 as (
+  fn: EditorDOMRenderConfig['$getDOMSlot'],
+) => DOMRenderMatch<LexicalNode>['$getDOMSlot'];
+
+function merge4<T, N extends LexicalNode, A, B>(
+  $acc: AccFn<T, N, [A, B]>,
+  $getOverride: GetOverrideFn<T, N, [A, B]>,
+): typeof $acc {
+  return (node, a, b, editor) => {
+    const $next = () => $acc(node, a, b, editor);
+    const $override = $getOverride(node);
+    return $override ? $override(node, a, b, $next, editor) : $next();
+  };
+}
+
+function merge5<T, N extends LexicalNode, A, B, C>(
+  acc: AccFn<T, N, [A, B, C]>,
+  $getOverride: GetOverrideFn<T, N, [A, B, C]>,
+): typeof acc {
+  return (node, a, b, c, editor) => {
+    const $next = () => acc(node, a, b, c, editor);
+    const $override = $getOverride(node);
+    return $override ? $override(node, a, b, c, $next, editor) : $next();
+  };
+}
+
+function sequence4<N extends LexicalNode, A, B>(
+  $acc: AccFn<void, N, [A, B]>,
+  $getOverride: (n: N) => undefined | AccFn<void, N, [A, B]>,
+): typeof $acc {
+  return (node, a, b, editor) => {
+    $acc(node, a, b, editor);
+    const $override = $getOverride(node);
+    if ($override) {
+      $override(node, a, b, editor);
+    }
+  };
+}
+
+function compilePrerenderKey<K extends keyof PreEditorDOMRenderConfig>(
+  prerender: PreEditorDOMRenderConfig,
+  k: K,
+  defaults: EditorDOMRenderConfig,
+  mergeFunction: (
+    $acc: EditorDOMRenderConfig[K],
+    $getOverride: (node: LexicalNode) => AnyDOMRenderMatch[K],
+  ) => typeof $acc,
+  ignoreNextFunction: (fn: EditorDOMRenderConfig[K]) => AnyDOMRenderMatch[K],
+): void {
+  let acc = defaults[k];
+  for (const pair of prerender[k]) {
+    if (typeof pair[0] === 'function') {
+      const [$predicate, $override] = pair;
+      acc = mergeFunction(
+        acc,
+        node => ($predicate(node) && $override) || undefined,
+      );
+    } else {
+      const typeOverrides = pair[1];
+      const compiled: Record<string, undefined | EditorDOMRenderConfig[K]> = {};
+      for (const type in typeOverrides) {
+        const arr = typeOverrides[type];
+        if (arr) {
+          compiled[type] = arr.reduce(
+            ($acc, $override) => mergeFunction($acc, () => $override),
+            acc,
+          );
+        }
+      }
+      acc = mergeFunction(acc, node => {
+        const f = compiled[node.getType()];
+        return f && ignoreNextFunction(f);
+      });
+    }
+  }
+  defaults[k] = acc;
+}
+
+function addOverride<K extends keyof PreEditorDOMRenderConfig>(
+  prerender: PreEditorDOMRenderConfig,
+  k: K,
+  predicateOrTypes: PredicateOrTypes,
+  override: AnyDOMRenderMatch[K],
+): void {
+  if (!override) {
+    return;
+  }
+  const arr = prerender[k];
+  if (typeof predicateOrTypes === 'function') {
+    arr.push([predicateOrTypes, override]);
+  } else {
+    const last = arr[arr.length - 1];
+    let types: TypeRender<AnyDOMRenderMatch[K]>;
+    if (last && last[0] === 'types') {
+      types = last[1];
+    } else {
+      types = {};
+      arr.push(['types', types]);
+    }
+    for (const type in predicateOrTypes) {
+      const typeArr = types[type] || [];
+      types[type] = typeArr;
+      typeArr.push(override);
+    }
+  }
+}
+
+type NormalizedDOMRenderMatch<T> = Omit<
+  DOMRenderMatch<LexicalNode>,
+  'nodes'
+> & {
+  nodes: T;
+};
+
+function isWildcard(
+  override: DOMRenderMatch<LexicalNode>,
+): override is NormalizedDOMRenderMatch<'*'> {
+  return override.nodes === '*';
+}
+
+function sortedOverrides(
+  overrides: DOMRenderMatch<LexicalNode>[],
+): DOMRenderMatch<LexicalNode>[] {
+  const byWildcard: NormalizedDOMRenderMatch<'*'>[] = [];
+  const byPredicate: NormalizedDOMRenderMatch<
+    [(node: LexicalNode) => node is LexicalNode]
+  >[] = [];
+  const byNode: NormalizedDOMRenderMatch<[Klass<LexicalNode>]>[] = [];
+  for (const override of overrides) {
+    if (isWildcard(override)) {
+      byWildcard.push(override);
+    } else if (Array.isArray(override.nodes)) {
+      for (const klassOrPredicate of override.nodes) {
+        if ($isLexicalNode(klassOrPredicate.prototype)) {
+          byNode.push(
+            override.nodes.length === 1
+              ? (override as NormalizedDOMRenderMatch<[Klass<LexicalNode>]>)
+              : {...override, nodes: [klassOrPredicate]},
+          );
+        } else {
+          byPredicate.push(
+            override.nodes.length === 1
+              ? (override as NormalizedDOMRenderMatch<
+                  [(node: LexicalNode) => node is LexicalNode]
+                >)
+              : {...override, nodes: [klassOrPredicate]},
+          );
+        }
+      }
+    }
+  }
+  const depths = new Map<Klass<LexicalNode>, number>();
+  const depthOf = (klass: Klass<LexicalNode>): number => {
+    let depth = depths.get(klass);
+    if (depth === undefined) {
+      depth = 0;
+      for (
+        let k: Klass<LexicalNode> = klass;
+        $isLexicalNode(k.prototype);
+        k = Object.getPrototypeOf(k)
+      ) {
+        depth++;
+      }
+      depths.set(klass, depth);
+    }
+    return depth;
+  };
+  byNode.sort((a, b) => depthOf(a.nodes[0]) - depthOf(b.nodes[0]));
+  return [...byNode, ...byPredicate, ...byWildcard];
+}
+
+export function precompileDOMRenderConfigOverrides(
+  editorConfig: Pick<InitialEditorConfig, 'nodes'>,
+  overrides: DOMRenderConfig['overrides'],
+): PreEditorDOMRenderConfig {
+  const typeTree = buildTypeTree(editorConfig);
+  const prerender = makePrerender();
+  for (const override of sortedOverrides(overrides)) {
+    const predicateOrTypes = getPredicate(typeTree, override);
+    for (const k_ in prerender) {
+      const k = k_ as keyof typeof prerender;
+      addOverride(prerender, k, predicateOrTypes, override[k]);
+    }
+  }
+  return prerender;
+}
+
+function identity<T>(v: T) {
+  return v;
+}
+
+export function compileDOMRenderConfigOverrides(
+  editorConfig: Pick<InitialEditorConfig, 'nodes' | 'dom'>,
+  {overrides}: Pick<DOMRenderConfig, 'overrides'>,
+): EditorDOMRenderConfig {
+  const prerender = precompileDOMRenderConfigOverrides(editorConfig, overrides);
+  const dom = {
+    ...DEFAULT_EDITOR_DOM_CONFIG,
+    ...editorConfig.dom,
+  };
+  compilePrerenderKey(prerender, '$createDOM', dom, merge2, ignoreNext2);
+  compilePrerenderKey(prerender, '$exportDOM', dom, merge2, ignoreNext2);
+  compilePrerenderKey(prerender, '$extractWithChild', dom, merge5, ignoreNext5);
+  compilePrerenderKey(
+    prerender,
+    '$getDOMSlot',
+    dom,
+    merge3GetDOMSlot,
+    ignoreNext3GetDOMSlot,
+  );
+  compilePrerenderKey(prerender, '$shouldExclude', dom, merge3, ignoreNext3);
+  compilePrerenderKey(prerender, '$shouldInclude', dom, merge3, ignoreNext3);
+  compilePrerenderKey(prerender, '$updateDOM', dom, merge4, ignoreNext4);
+  compilePrerenderKey(prerender, '$decorateDOM', dom, sequence4, identity);
+  return dom;
+}

package/src/constants.ts

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+export const DOMRenderExtensionName = '@lexical/html/DOM';
+export const DOMRenderContextSymbol = Symbol.for(
+  '@lexical/html/DOMExportContext',
+);
+
+export const DOMImportExtensionName = '@lexical/html/DOMImport';
+export const DOMImportContextSymbol = Symbol.for(
+  '@lexical/html/DOMImportContext',
+);
+
+export const ALWAYS_TRUE = () => true as const;

package/src/domOverride.ts

@@ -0,0 +1,46 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+import type {
+  AnyDOMRenderMatch,
+  DOMOverrideOptions,
+  DOMRenderMatch,
+  DOMRenderMatchConfig,
+  NodeMatch,
+} from './types';
+import type {LexicalNode} from 'lexical';
+
+/**
+ * A convenience function for type inference when constructing DOM overrides for
+ * use with {@link DOMRenderExtension}.
+ *
+ * The optional `options` argument controls *whether* the override is installed
+ * based only on render context — `disabledForEditor` gates residency in the
+ * editor's render pipeline (reconciliation), `disabledForSession` gates
+ * participation in a single export/generate session. See {@link DOMOverrideOptions}.
+ *
+ * @experimental
+ * @__NO_SIDE_EFFECTS__
+ */
+
+export function domOverride(
+  nodes: '*',
+  config: DOMRenderMatchConfig<LexicalNode>,
+  options?: DOMOverrideOptions,
+): DOMRenderMatch<LexicalNode>;
+export function domOverride<T extends LexicalNode>(
+  nodes: readonly NodeMatch<T>[],
+  config: DOMRenderMatchConfig<T>,
+  options?: DOMOverrideOptions,
+): DOMRenderMatch<T>;
+export function domOverride(
+  nodes: AnyDOMRenderMatch['nodes'],
+  config: Omit<AnyDOMRenderMatch, 'nodes' | keyof DOMOverrideOptions>,
+  options?: DOMOverrideOptions,
+): AnyDOMRenderMatch {
+  return {...config, ...options, nodes};
+}

package/src/import/CoreImportExtension.ts

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+import {configExtension, defineExtension} from 'lexical';
+
+import {CoreImportRules} from './coreImportRules';
+import {DOMImportExtension} from './DOMImportExtension';
+
+/**
+ * Bundles {@link CoreImportRules} into a {@link DOMImportExtension}-aware
+ * extension. Depend on this from your editor (directly or via richer
+ * extensions like `RichTextImportExtension`) to get the equivalent of the
+ * legacy core `importDOM` behavior for `<p>`, `<span>`, `<b>`,
+ * `<strong>`, `<em>`, `<i>`, `<code>`, `<mark>`, `<s>`, `<sub>`, `<sup>`,
+ * `<u>`, `<br>`, and `#text`.
+ *
+ * @experimental
+ */
+export const CoreImportExtension = defineExtension({
+  dependencies: [configExtension(DOMImportExtension, {rules: CoreImportRules})],
+  name: '@lexical/html/CoreImport',
+});