@lexical/html 0.44.1-nightly.20260518.0 → 0.45.0

package/src/ContextRecord.ts

@@ -0,0 +1,243 @@
+/**
+ * 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 {
+  AnyContextConfigPairOrUpdater,
+  AnyContextSymbol,
+  ContextConfig,
+  ContextConfigPair,
+  ContextConfigUpdater,
+  ContextRecord,
+} from './types';
+
+import {$getEditor, createState, type LexicalEditor} from 'lexical';
+
+let activeContext: undefined | EditorContext;
+
+type WithContext<Ctx extends AnyContextSymbol> = {
+  [K in Ctx]?: undefined | ContextRecord<Ctx>;
+};
+
+/**
+ * @experimental
+ *
+ * The LexicalEditor with context
+ */
+export type EditorContext = {
+  editor: LexicalEditor;
+} & WithContext<AnyContextSymbol>;
+
+/**
+ * @experimental
+ *
+ * @param contextRecord The ContextRecord
+ * @param cfg The configuration
+ * @returns The value or defaultValue of cfg
+ */
+export function getContextValue<Ctx extends AnyContextSymbol, V>(
+  contextRecord: undefined | ContextRecord<Ctx>,
+  cfg: ContextConfig<Ctx, V>,
+): V {
+  const {key} = cfg;
+  return contextRecord && key in contextRecord
+    ? (contextRecord[key] as V)
+    : cfg.defaultValue;
+}
+
+/**
+ * @experimental
+ *
+ * Read and delete cfg from this layer of context
+ *
+ * @param contextRecord The ContextRecord
+ * @param cfg The configuration
+ * @returns The value of the configuration that was removed
+ */
+export function popOwnContextValue<Ctx extends AnyContextSymbol, V>(
+  contextRecord: ContextRecord<Ctx>,
+  cfg: ContextConfig<Ctx, V>,
+): undefined | V {
+  const rval = getOwnContextValue(contextRecord, cfg);
+  delete contextRecord[cfg.key];
+  return rval;
+}
+
+/**
+ * @experimental
+ *
+ * Get the value without a default
+ *
+ * @param contextRecord The ContextRecord
+ * @param cfg The configuration
+ * @returns The current value in this context or `undefined` if not set
+ */
+export function getOwnContextValue<Ctx extends AnyContextSymbol, V>(
+  contextRecord: ContextRecord<Ctx>,
+  cfg: ContextConfig<Ctx, V>,
+): undefined | V {
+  const {key} = cfg;
+  return key in contextRecord ? (contextRecord[key] as V) : undefined;
+}
+
+function getEditorContext(editor: LexicalEditor): undefined | EditorContext {
+  return activeContext && activeContext.editor === editor
+    ? activeContext
+    : undefined;
+}
+
+/**
+ * @experimental
+ *
+ * @param sym The symbol for this ContextRecord (e.g. DOMRenderContextSymbol)
+ * @param editor The editor
+ * @returns The current context or undefined
+ */
+export function getContextRecord<Ctx extends AnyContextSymbol>(
+  sym: Ctx,
+  editor: LexicalEditor,
+): undefined | ContextRecord<Ctx> {
+  const editorContext = getEditorContext(editor);
+  return editorContext && editorContext[sym];
+}
+
+function toPair<Ctx extends AnyContextSymbol, V>(
+  contextRecord: undefined | ContextRecord<Ctx>,
+  pairOrUpdater: ContextConfigPair<Ctx, V> | ContextConfigUpdater<Ctx, V>,
+): ContextConfigPair<Ctx, V> {
+  if ('cfg' in pairOrUpdater) {
+    const {cfg, updater} = pairOrUpdater;
+    return [cfg, updater(getContextValue(contextRecord, cfg))];
+  }
+  return pairOrUpdater;
+}
+
+/**
+ * Construct a new context from a parent context and pairs
+ *
+ * @param pairs The pairs and updaters to build the context from
+ * @param parent The parent context
+ * @returns The new context
+ */
+export function contextFromPairs<Ctx extends AnyContextSymbol>(
+  pairs: readonly AnyContextConfigPairOrUpdater<Ctx>[],
+  parent: undefined | ContextRecord<Ctx>,
+): undefined | ContextRecord<Ctx> {
+  let rval = parent;
+  for (const pairOrUpdater of pairs) {
+    const [k, v] = toPair(rval, pairOrUpdater);
+    const key = k.key;
+    if (rval === parent && getContextValue(rval, k) === v) {
+      continue;
+    }
+    // If we haven't branched away from `parent` yet, create a fresh child
+    // context so we never mutate the caller's parent record. Subsequent
+    // pairs in this loop accumulate into the same child. Inside the loop
+    // `rval` is non-null after the first iteration, since createChildContext
+    // never returns null/undefined.
+    const ctx: ContextRecord<Ctx> =
+      rval === parent || rval === undefined ? createChildContext(parent) : rval;
+    ctx[key] = v;
+    rval = ctx;
+  }
+  return rval;
+}
+
+function createChildContext<Ctx extends AnyContextSymbol>(
+  parent: undefined | ContextRecord<Ctx>,
+): ContextRecord<Ctx> {
+  return Object.create(parent || null);
+}
+
+/**
+ * Create a context config pair that sets a value in the render context.
+ * @experimental
+ */
+export function contextValue<Ctx extends AnyContextSymbol, V>(
+  cfg: ContextConfig<Ctx, V>,
+  value: V,
+): ContextConfigPair<Ctx, V> {
+  return [cfg, value];
+}
+
+/**
+ * Create a context config updater that transforms a value in the render context.
+ * @experimental
+ */
+export function contextUpdater<Ctx extends AnyContextSymbol, V>(
+  cfg: ContextConfig<Ctx, V>,
+  updater: (prev: V) => V,
+): ContextConfigUpdater<Ctx, V> {
+  return {cfg, updater};
+}
+
+/**
+ * @internal
+ * @experimental
+ * @__NO_SIDE_EFFECTS__
+ */
+export function $withFullContext<Ctx extends AnyContextSymbol, T>(
+  sym: Ctx,
+  contextRecord: ContextRecord<Ctx>,
+  f: () => T,
+  editor: LexicalEditor = $getEditor(),
+): T {
+  const prevDOMContext = activeContext;
+  const parentEditorContext = getEditorContext(editor);
+  try {
+    activeContext = {...parentEditorContext, editor, [sym]: contextRecord};
+    return f();
+  } finally {
+    activeContext = prevDOMContext;
+  }
+}
+
+/**
+ * @internal
+ * @experimental
+ * @__NO_SIDE_EFFECTS__
+ */
+export function $withContext<Ctx extends AnyContextSymbol>(
+  sym: Ctx,
+  $defaults: (editor: LexicalEditor) => undefined | ContextRecord<Ctx> = () =>
+    undefined,
+) {
+  return (
+    cfg: readonly AnyContextConfigPairOrUpdater<Ctx>[],
+    editor = $getEditor(),
+  ): (<T>(f: () => T) => T) => {
+    return f => {
+      const parentEditorContext = getEditorContext(editor);
+      const parentContextRecord =
+        parentEditorContext && parentEditorContext[sym];
+      const contextRecord = contextFromPairs(
+        cfg,
+        parentContextRecord || $defaults(editor),
+      );
+      if (!contextRecord || contextRecord === parentContextRecord) {
+        return f();
+      }
+      return $withFullContext(sym, contextRecord, f, editor);
+    };
+  };
+}
+
+/**
+ * @experimental
+ * @internal
+ * @__NO_SIDE_EFFECTS__
+ */
+export function createContextState<Tag extends symbol, V>(
+  tag: Tag,
+  name: string,
+  getDefaultValue: () => V,
+  isEqual?: (a: V, b: V) => boolean,
+): ContextConfig<Tag, V> {
+  return Object.assign(
+    createState(Symbol(name), {isEqual, parse: getDefaultValue}),
+    {[tag]: true} as const,
+  );
+}

package/src/DOMRenderExtension.ts

@@ -0,0 +1,96 @@
+/**
+ * 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 {DOMRenderConfig, DOMRenderExtensionOutput} from './types';
+import type {InitialEditorConfig} from 'lexical';
+
+import {defineExtension, RootNode, shallowMergeConfig} from 'lexical';
+
+import {compileDOMRenderConfigOverrides} from './compileDOMRenderConfigOverrides';
+import {DOMRenderExtensionName} from './constants';
+import {
+  createEditorContextRecord,
+  DOMRenderRuntimeImpl,
+  filterEditorInstalled,
+} from './DOMRenderRuntime';
+
+/** @internal The result returned from {@link DOMRenderExtension}'s `init`. */
+interface DOMRenderInitResult {
+  /**
+   * The `nodes` and base `dom` captured from the editor config before `dom`
+   * is overwritten with the compiled config — the only fields the runtime
+   * needs to recompile.
+   */
+  initialEditorConfig: Pick<InitialEditorConfig, 'nodes' | 'dom'>;
+}
+
+/**
+ * @experimental
+ *
+ * An extension that allows overriding the render and export behavior for an
+ * editor. This is highly experimental and subject to change from one version
+ * to the next.
+ **/
+export const DOMRenderExtension = defineExtension<
+  DOMRenderConfig,
+  typeof DOMRenderExtensionName,
+  DOMRenderExtensionOutput,
+  DOMRenderInitResult
+>({
+  build(editor, config, state) {
+    const {initialEditorConfig} = state.getInitResult();
+    const editorContext = createEditorContextRecord(config.contextDefaults);
+    const runtime = new DOMRenderRuntimeImpl(
+      editor,
+      initialEditorConfig,
+      config.overrides,
+      editorContext,
+    );
+    return {defaults: editorContext, runtime};
+  },
+  config: {
+    contextDefaults: [],
+    overrides: [],
+  },
+  html: {
+    // Define a RootNode export for $generateDOMFromRoot
+    export: new Map([
+      [
+        RootNode,
+        () => {
+          const element = document.createElement('div');
+          element.role = 'textbox';
+          return {element};
+        },
+      ],
+    ]),
+  },
+  init(editorConfig, config) {
+    // Capture the user's base `dom` (before we overwrite it) and `nodes` so the
+    // runtime can recompile from scratch when overrides toggle.
+    const initialEditorConfig: DOMRenderInitResult['initialEditorConfig'] = {
+      dom: editorConfig.dom,
+      nodes: editorConfig.nodes,
+    };
+    const editorContext = createEditorContextRecord(config.contextDefaults);
+    const installed = filterEditorInstalled(config.overrides, editorContext);
+    editorConfig.dom = compileDOMRenderConfigOverrides(editorConfig, {
+      overrides: installed,
+    });
+    return {initialEditorConfig};
+  },
+  mergeConfig(config, partial) {
+    const merged = shallowMergeConfig(config, partial);
+    for (const k of ['overrides', 'contextDefaults'] as const) {
+      if (partial[k]) {
+        (merged[k] as unknown[]) = [...config[k], ...partial[k]];
+      }
+    }
+    return merged;
+  },
+  name: DOMRenderExtensionName,
+});

package/src/DOMRenderRuntime.ts

@@ -0,0 +1,265 @@
+/**
+ * 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,
+  AnyRenderStateConfigPairOrUpdater,
+  ContextRecord,
+  DOMRenderRuntime,
+  RenderContextReader,
+  RenderStateConfig,
+} from './types';
+import type {
+  EditorDOMRenderConfig,
+  InitialEditorConfig,
+  Klass,
+  LexicalEditor,
+  LexicalNode,
+} from 'lexical';
+
+import {
+  $fullReconcile,
+  $isLexicalNode,
+  DEFAULT_EDITOR_DOM_CONFIG,
+} from 'lexical';
+
+import {compileDOMRenderConfigOverrides} from './compileDOMRenderConfigOverrides';
+import {DOMRenderContextSymbol} from './constants';
+import {
+  contextFromPairs,
+  getContextRecord,
+  getContextValue,
+} from './ContextRecord';
+
+type RenderContextRecord = ContextRecord<typeof DOMRenderContextSymbol>;
+
+function makeReader(record: RenderContextRecord): RenderContextReader {
+  return {
+    get<V>(cfg: RenderStateConfig<V>): V {
+      return getContextValue(record, cfg);
+    },
+  };
+}
+
+/**
+ * The mutable, writable editor-level context record. Reads of a render state
+ * during reconciliation (and as the base layer of a session) fall through to
+ * this record, and it is the layer the `disabledForEditor` predicates read.
+ *
+ * @internal
+ */
+export function createEditorContextRecord(
+  contextDefaults: readonly AnyRenderStateConfigPairOrUpdater[],
+): RenderContextRecord {
+  const parent = Object.create(null) as RenderContextRecord;
+  return contextFromPairs(contextDefaults, parent) || parent;
+}
+
+/**
+ * Filter the configured overrides down to those that are resident in the
+ * editor's render config, removing any whose `disabledForEditor` predicate
+ * returns `true` for the given editor context.
+ *
+ * @internal
+ */
+export function filterEditorInstalled(
+  overrides: readonly AnyDOMRenderMatch[],
+  record: RenderContextRecord,
+): AnyDOMRenderMatch[] {
+  const reader = makeReader(record);
+  return overrides.filter(
+    o => !(o.disabledForEditor && o.disabledForEditor(reader)),
+  );
+}
+
+function sameOverrides(
+  a: readonly AnyDOMRenderMatch[],
+  b: readonly AnyDOMRenderMatch[],
+): boolean {
+  if (a.length !== b.length) {
+    return false;
+  }
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function symmetricDiff(
+  prev: readonly AnyDOMRenderMatch[],
+  next: readonly AnyDOMRenderMatch[],
+): AnyDOMRenderMatch[] {
+  const prevSet = new Set(prev);
+  const nextSet = new Set(next);
+  const changed: AnyDOMRenderMatch[] = [];
+  for (const o of prev) {
+    if (!nextSet.has(o)) {
+      changed.push(o);
+    }
+  }
+  for (const o of next) {
+    if (!prevSet.has(o)) {
+      changed.push(o);
+    }
+  }
+  return changed;
+}
+
+/**
+ * Build a predicate matching the nodes an override targets — `'*'` matches
+ * everything, a node class matches by `instanceof`, and a guard is used as-is.
+ */
+function nodeMatcher(o: AnyDOMRenderMatch): (node: LexicalNode) => boolean {
+  if (o.nodes === '*') {
+    return () => true;
+  }
+  const matchers = o.nodes.map(match => {
+    const klass = match as Klass<LexicalNode>;
+    return $isLexicalNode(klass.prototype)
+      ? (node: LexicalNode) => node instanceof klass
+      : (match as (node: LexicalNode) => boolean);
+  });
+  return node => matchers.some(f => f(node));
+}
+
+/**
+ * Build a predicate matching the nodes whose DOM must be recreated for the
+ * given override change, or `null` when no live re-render is needed.
+ *
+ * `$createDOM`/`$getDOMSlot` produce the element and slot, and `$decorateDOM`
+ * may add DOM that only a fresh `$createDOM` can revert — so toggling any of
+ * them recreates the affected nodes. `$updateDOM` is diff-driven and applies on
+ * the next node update, and export-only hooks ($exportDOM/$shouldInclude/…)
+ * don't touch the live DOM, so neither needs a re-render. Recreating every
+ * affected node is the simple, always-correct choice; toggles are rare, so the
+ * cost is acceptable and can be optimized later if needed.
+ */
+function recreatePredicate(
+  changed: readonly AnyDOMRenderMatch[],
+): ((node: LexicalNode) => boolean) | null {
+  const matchers: ((node: LexicalNode) => boolean)[] = [];
+  for (const o of changed) {
+    if (o.$createDOM || o.$getDOMSlot || o.$decorateDOM) {
+      matchers.push(nodeMatcher(o));
+    }
+  }
+  return matchers.length === 0 ? null : node => matchers.some(f => f(node));
+}
+
+/**
+ * Per-editor runtime backing {@link DOMRenderExtension}'s conditional
+ * overrides and imperative editor context. See {@link DOMRenderRuntime}.
+ *
+ * @internal
+ */
+export class DOMRenderRuntimeImpl implements DOMRenderRuntime {
+  readonly editor: LexicalEditor;
+  /**
+   * The `nodes` and base `dom` captured at `init` (before `dom` was
+   * overwritten with the compiled config) — the clean base for every recompile.
+   */
+  readonly initialEditorConfig: Pick<InitialEditorConfig, 'nodes' | 'dom'>;
+  readonly overrides: readonly AnyDOMRenderMatch[];
+  readonly editorContext: RenderContextRecord;
+  readonly hasSessionGates: boolean;
+  installed: readonly AnyDOMRenderMatch[];
+
+  /** Memoized session configs keyed by the set of session-disabled overrides. */
+  private readonly sessionCache = new Map<string, EditorDOMRenderConfig>();
+
+  constructor(
+    editor: LexicalEditor,
+    initialEditorConfig: Pick<InitialEditorConfig, 'nodes' | 'dom'>,
+    overrides: readonly AnyDOMRenderMatch[],
+    editorContext: RenderContextRecord,
+  ) {
+    this.editor = editor;
+    this.initialEditorConfig = initialEditorConfig;
+    this.overrides = overrides;
+    this.editorContext = editorContext;
+    this.installed = filterEditorInstalled(overrides, editorContext);
+    this.hasSessionGates = overrides.some(o => o.disabledForSession);
+  }
+
+  setContextValue<V>(cfg: RenderStateConfig<V>, value: V): void {
+    const prev = this.installed;
+    this.editorContext[cfg.key] = value;
+    const next = filterEditorInstalled(this.overrides, this.editorContext);
+    if (sameOverrides(prev, next)) {
+      return;
+    }
+    const changed = symmetricDiff(prev, next);
+    this.installed = next;
+    this.sessionCache.clear();
+    const dom = compileDOMRenderConfigOverrides(this.initialEditorConfig, {
+      overrides: next as AnyDOMRenderMatch[],
+    });
+    this.editor._config.dom = dom;
+
+    const recreate = recreatePredicate(changed);
+    if (!recreate) {
+      // $updateDOM-only or export-only change: the recompiled config is enough.
+      return;
+    }
+
+    // Re-render through a full reconcile, which reuses the existing node
+    // instances (no node-map mutation, so no spurious mutation/collaboration
+    // changes). The affected nodes must be unmounted and recreated — the removed
+    // override may have produced or decorated DOM that only a fresh $createDOM
+    // reverts — so install a transient $updateDOM that reports a recreate for
+    // matching nodes.
+    //
+    // This mutates the (shared) active config, so the reconcile MUST run and
+    // finish synchronously before the original is restored on the next line —
+    // hence `discrete`, and hence this must not be called from within an
+    // editor.update (where the commit would defer). A deferred update would
+    // either restore the wrapper before the reconcile reads it (no recreate) or
+    // leave it armed across a window where an unrelated reconcile would
+    // spuriously recreate matching nodes. No history tag is needed: a full
+    // reconcile marks no nodes dirty, which history merges/discards without
+    // pushing.
+    const base = dom.$updateDOM;
+    dom.$updateDOM = (nextNode, prevNode, el, editor) =>
+      recreate(nextNode) ? true : base(nextNode, prevNode, el, editor);
+    this.editor.update($fullReconcile, {discrete: true});
+    dom.$updateDOM = base;
+  }
+
+  getSessionConfig(): EditorDOMRenderConfig {
+    const resident = this.editor._config.dom || DEFAULT_EDITOR_DOM_CONFIG;
+    if (!this.hasSessionGates) {
+      return resident;
+    }
+    const reader = makeReader(
+      getContextRecord(DOMRenderContextSymbol, this.editor) ||
+        this.editorContext,
+    );
+    const disabledKeys: string[] = [];
+    const sessionSet: AnyDOMRenderMatch[] = [];
+    this.installed.forEach((o, i) => {
+      if (o.disabledForSession && o.disabledForSession(reader)) {
+        disabledKeys.push(String(i));
+      } else {
+        sessionSet.push(o);
+      }
+    });
+    if (disabledKeys.length === 0) {
+      return resident;
+    }
+    const key = disabledKeys.join(',');
+    let cfg = this.sessionCache.get(key);
+    if (!cfg) {
+      cfg = compileDOMRenderConfigOverrides(this.initialEditorConfig, {
+        overrides: sessionSet,
+      });
+      this.sessionCache.set(key, cfg);
+    }
+    return cfg;
+  }
+}