@lexical/html 0.44.1-nightly.20260518.0 → 0.45.0

package/src/import/runImport.ts

@@ -0,0 +1,245 @@
+/**
+ * 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 {
+  ChildSchema,
+  DOMImportContext,
+  ImportChildrenOpts,
+  ImportNodeOpts,
+  ImportSession,
+  ImportStateConfig,
+} from './types';
+
+import {isDOMDocumentNode, type LexicalEditor, type LexicalNode} from 'lexical';
+
+import {
+  type CompiledDispatch,
+  type CompiledRule,
+  getDispatchIndices,
+} from './compileImportRules';
+import {
+  $getImportContextValue,
+  $withImportContext,
+  ImportOverlays,
+} from './ImportContext';
+import {$applySchema, RootSchema} from './schemas';
+
+const __DEV__ = process.env.NODE_ENV !== 'production';
+
+const NO_CAPTURES: Record<string, RegExpMatchArray> = Object.freeze(
+  {} as Record<string, RegExpMatchArray>,
+);
+
+interface Runtime {
+  readonly dispatch: CompiledDispatch;
+  readonly editor: LexicalEditor;
+  readonly session: ImportSession;
+  /**
+   * Stack of overlay dispatchers installed via `$importChildren({rules})`.
+   * The most recently pushed overlay is at the highest index and is
+   * tried first; rules within an overlay are dispatched in their own
+   * registration order. When all overlay rules for a node have been
+   * exhausted (or have called `$next()` to defer), the main dispatcher
+   * is consulted. This lets app rules scope cost-bearing predicates to
+   * the subtrees where they apply.
+   */
+  readonly overlays: CompiledDispatch[];
+}
+
+function makeContext(
+  runtime: Runtime,
+  captures: Readonly<Record<string, RegExpMatchArray>>,
+): DOMImportContext<Record<string, RegExpMatchArray>> {
+  const ctx: DOMImportContext<Record<string, RegExpMatchArray>> = {
+    $importChildren: (parent, opts) =>
+      $importChildrenInternal(runtime, parent, opts),
+    $importOne: (node, opts) => $importOneInternal(runtime, node, opts),
+    captures,
+    get<V>(cfg: ImportStateConfig<V>): V {
+      return $getImportContextValue(cfg, runtime.editor);
+    },
+    session: runtime.session,
+  };
+  return ctx;
+}
+
+function $importChildrenInternal(
+  runtime: Runtime,
+  parent: ParentNode,
+  opts: ImportChildrenOpts | undefined,
+): LexicalNode[] {
+  const overlay = opts && opts.rules ? opts.rules.dispatch : undefined;
+  if (overlay) {
+    runtime.overlays.push(overlay);
+  }
+  try {
+    const run = () => $importChildrenRun(runtime, parent, opts);
+    return opts && opts.context
+      ? $withImportContext(opts.context, runtime.editor)(run)
+      : run();
+  } finally {
+    if (overlay) {
+      runtime.overlays.pop();
+    }
+  }
+}
+
+function $importChildrenRun(
+  runtime: Runtime,
+  parent: ParentNode,
+  opts: ImportChildrenOpts | undefined,
+): LexicalNode[] {
+  const onChild = opts && opts.$onChild;
+  const collected: LexicalNode[] = [];
+  for (const child of Array.from(parent.childNodes)) {
+    const produced = $importOneInternal(runtime, child, undefined);
+    for (const lex of produced) {
+      const result = onChild ? onChild(lex) : lex;
+      if (result != null) {
+        collected.push(result);
+      }
+    }
+  }
+  const afterApplied = opts && opts.$after ? opts.$after(collected) : collected;
+  const schema: ChildSchema | undefined = opts && opts.schema;
+  if (!schema) {
+    return afterApplied;
+  }
+  return $applySchema(schema, afterApplied, null, parent);
+}
+
+function $importOneInternal(
+  runtime: Runtime,
+  node: Node,
+  opts: ImportNodeOpts | undefined,
+): LexicalNode[] {
+  const run = () => $dispatch(runtime, node);
+  const out =
+    opts && opts.context
+      ? $withImportContext(opts.context, runtime.editor)(run)
+      : run();
+  // Surface to callers as a mutable array per the DOMImportContext contract.
+  return out as LexicalNode[];
+}
+
+/**
+ * Build the candidate (dispatch, indices) list for `node`. Overlays are
+ * tried first in top-of-stack order; the main dispatcher comes last. The
+ * `$next()` chain walks through all of them in sequence — an overlay rule
+ * can defer to a lower overlay rule, or all the way through to a main
+ * rule, just by calling `$next()`.
+ */
+function getCandidates(
+  runtime: Runtime,
+  node: Node,
+): readonly {dispatch: CompiledDispatch; indices: readonly number[]}[] {
+  const candidates: {
+    dispatch: CompiledDispatch;
+    indices: readonly number[];
+  }[] = [];
+  for (let i = runtime.overlays.length - 1; i >= 0; i--) {
+    const d = runtime.overlays[i];
+    const idx = getDispatchIndices(d, node);
+    if (idx.length > 0) {
+      candidates.push({dispatch: d, indices: idx});
+    }
+  }
+  const mainIdx = getDispatchIndices(runtime.dispatch, node);
+  if (mainIdx.length > 0) {
+    candidates.push({dispatch: runtime.dispatch, indices: mainIdx});
+  }
+  return candidates;
+}
+
+function $dispatch(runtime: Runtime, node: Node): readonly LexicalNode[] {
+  const candidates = getCandidates(runtime, node);
+  if (candidates.length === 0) {
+    return $hoistChildrenOf(runtime, node);
+  }
+  let groupCursor = 0;
+  let ruleCursor = 0;
+  const $next = (): readonly LexicalNode[] => {
+    while (groupCursor < candidates.length) {
+      const {dispatch, indices} = candidates[groupCursor];
+      while (ruleCursor < indices.length) {
+        const idx = indices[ruleCursor++];
+        const rule: CompiledRule = dispatch.rules[idx];
+        const captures: Record<string, RegExpMatchArray> = {};
+        if (rule.predicate(node, captures)) {
+          const ctx = makeContext(
+            runtime,
+            Object.keys(captures).length === 0 ? NO_CAPTURES : captures,
+          );
+          try {
+            return rule.$import(ctx, node, $next);
+          } catch (e) {
+            if (__DEV__) {
+              console.error(
+                `[lexical] DOM import rule "${rule.name}" threw on node`,
+                node,
+                e,
+              );
+            }
+            throw e;
+          }
+        }
+      }
+      groupCursor++;
+      ruleCursor = 0;
+    }
+    return $hoistChildrenOf(runtime, node);
+  };
+  return $next();
+}
+
+/**
+ * Fallback when no rule matched and `$next()` was called past the end of the
+ * chain: hoist the element's children to take its place, recursively. Pure
+ * elements with no rule become invisible, matching the legacy
+ * `$createNodesFromDOM` hoisting behavior.
+ */
+function $hoistChildrenOf(runtime: Runtime, node: Node): LexicalNode[] {
+  if (node.childNodes.length === 0) {
+    return [];
+  }
+  const collected: LexicalNode[] = [];
+  for (const child of Array.from(node.childNodes)) {
+    const produced = $importOneInternal(runtime, child, undefined);
+    for (const lex of produced) {
+      collected.push(lex);
+    }
+  }
+  return collected;
+}
+
+/**
+ * Top-level walker for a compiled dispatcher. Iterates the DOM children of
+ * `dom` (using the document body if a {@link Document} is passed) and
+ * applies `RootSchema` to the produced lexical nodes so runs of inlines are
+ * wrapped in paragraphs — same shape as the legacy `$generateNodesFromDOM`.
+ *
+ * @internal
+ */
+export function $runImport(
+  dispatch: CompiledDispatch,
+  editor: LexicalEditor,
+  dom: Document | ParentNode,
+  session: ImportSession,
+): LexicalNode[] {
+  // Prime the overlay stack with any overlays a preprocess wrote to
+  // ImportOverlays. These remain in effect for the entire walk; nested
+  // `$importChildren({rules})` calls push on top.
+  const installed = session.get(ImportOverlays);
+  const runtime: Runtime = {
+    dispatch,
+    editor,
+    overlays: installed.map(o => o.dispatch),
+    session,
+  };
+  const rootParent: ParentNode = isDOMDocumentNode(dom) ? dom.body : dom;
+  return $importChildrenRun(runtime, rootParent, {schema: RootSchema});
+}

package/src/import/schemas.ts

@@ -0,0 +1,236 @@
+/**
+ * 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 {ChildSchema} from './types';
+
+import {
+  $createParagraphNode,
+  $isBlockElementNode,
+  $isDecoratorNode,
+  $isElementNode,
+  type ElementNode,
+  isHTMLElement,
+  type LexicalNode,
+} from 'lexical';
+
+import {isAlignmentValue} from './coreImportRules';
+
+/**
+ * True if the node fills a block slot at the root or inside another
+ * block — covers both ElementNode-style blocks (paragraph, heading,
+ * quote) and block-level DecoratorNodes (HorizontalRuleNode,
+ * ImageNode-as-block, etc.). Used by {@link BlockSchema},
+ * {@link RootSchema}, and {@link NestedBlockSchema}.
+ *
+ * @experimental
+ */
+export function $isBlockLevel(node: LexicalNode): boolean {
+  return (
+    $isBlockElementNode(node) || ($isDecoratorNode(node) && !node.isInline())
+  );
+}
+
+/**
+ * Distribute an inline wrapper (`LinkNode`, `MarkNode`, …) across a
+ * heterogeneous run of children produced by `$importChildren`, lifting
+ * any block children to the top level while keeping the wrapper around
+ * the leaf inline content.
+ *
+ * Use from a rule whose DOM source is an inline element that the
+ * browser permitted to enclose block elements — the canonical case is
+ * `<a href="…"><h1>title</h1><div>body</div></a>`, which a link rule
+ * wants to surface as two block siblings (heading + paragraph), each
+ * with its own link wrapping the original inline content. Schemas
+ * can't express this because they reason about a parent's children
+ * only — they cannot lift the parent out of itself.
+ *
+ * For each top-level child:
+ * - **Inline children** are collected into runs; each run is wrapped
+ *   in a single fresh wrapper (from `$makeWrapper()`).
+ * - **Block children** are descended into: their own children are
+ *   recursively distributed with `$makeWrapper`, then re-attached so
+ *   the block keeps its position at the top level.
+ *
+ * The returned list will contain a mix of blocks and wrapped inline
+ * runs. The enclosing schema (typically {@link BlockSchema}) will
+ * then package those inline wrappers into paragraphs as usual.
+ *
+ * @experimental
+ */
+export function $distributeInlineWrapper(
+  children: readonly LexicalNode[],
+  $makeWrapper: () => ElementNode,
+): LexicalNode[] {
+  const out: LexicalNode[] = [];
+  let inlineRun: LexicalNode[] = [];
+
+  const flushInline = () => {
+    if (inlineRun.length === 0) {
+      return;
+    }
+    out.push($makeWrapper().splice(0, 0, inlineRun));
+    inlineRun = [];
+  };
+
+  for (const child of children) {
+    if ($isBlockLevel(child)) {
+      flushInline();
+      // Recursively distribute the wrapper into the block's own
+      // children. A block DecoratorNode (no children) is left alone.
+      if ($isElementNode(child)) {
+        const wrapped = $distributeInlineWrapper(
+          child.getChildren(),
+          $makeWrapper,
+        );
+        child.splice(0, child.getChildrenSize(), wrapped);
+      }
+      out.push(child);
+    } else {
+      inlineRun.push(child);
+    }
+  }
+  flushInline();
+  return out;
+}
+
+/**
+ * Apply a {@link ChildSchema} to a flat list of children produced by
+ * `$importChildren`. Walks the list once, partitions into accepted vs.
+ * rejected runs, packages or drops rejected runs, then runs `$finalize`.
+ *
+ * @internal
+ */
+export function $applySchema(
+  schema: ChildSchema,
+  children: LexicalNode[],
+  parent: LexicalNode | null,
+  domParent: Node | null,
+): LexicalNode[] {
+  const out: LexicalNode[] = [];
+  let run: LexicalNode[] | null = null;
+
+  const flushRun = () => {
+    if (run === null) {
+      return;
+    }
+    const rejected = run;
+    run = null;
+    if (schema.$packageRun) {
+      const packaged = schema.$packageRun(rejected, parent, domParent);
+      if (packaged.length > 0) {
+        for (const n of packaged) {
+          out.push(n);
+        }
+        return;
+      }
+    }
+    // No $packageRun (or it returned []) — apply onReject. 'drop' (default)
+    // discards the run. 'hoist' lets it through unchanged at this level.
+    if (schema.onReject === 'hoist') {
+      for (const n of rejected) {
+        out.push(n);
+      }
+    }
+  };
+
+  for (const child of children) {
+    if (schema.$accepts(child, parent)) {
+      flushRun();
+      out.push(child);
+    } else {
+      if (run === null) {
+        run = [];
+      }
+      run.push(child);
+    }
+  }
+  flushRun();
+
+  return schema.$finalize ? schema.$finalize(out, parent) : out;
+}
+
+/**
+ * Wrap a run of inline lexical nodes in a fresh paragraph, propagating the
+ * `text-align` of `domParent` as the paragraph's format type (matching the
+ * legacy `wrapContinuousInlines` behavior).
+ */
+function $paragraphPackageRun(
+  run: LexicalNode[],
+  _parent: LexicalNode | null,
+  domParent: Node | null,
+): LexicalNode[] {
+  const paragraph = $createParagraphNode();
+  if (isHTMLElement(domParent)) {
+    const textAlign = domParent.style.textAlign;
+    if (isAlignmentValue(textAlign)) {
+      paragraph.setFormat(textAlign);
+    }
+  }
+  return [paragraph.splice(0, 0, run)];
+}
+
+/**
+ * Default schema for block-level positions (root of the document, the body
+ * of a block element node). Accepts block lexical nodes; packages runs of
+ * inline children into fresh paragraph nodes.
+ *
+ * @experimental
+ */
+export const BlockSchema: ChildSchema = {
+  $accepts: $isBlockLevel,
+  $packageRun: $paragraphPackageRun,
+  name: 'BlockSchema',
+};
+
+/**
+ * Schema for inline-only positions (the body of an inline lexical node such
+ * as a link). Accepts non-block lexical nodes; runs of block children are
+ * dropped (`onReject: 'drop'` is the default).
+ *
+ * @experimental
+ */
+export const InlineSchema: ChildSchema = {
+  $accepts: child => !$isBlockLevel(child),
+  name: 'InlineSchema',
+};
+
+/**
+ * Schema for nested block positions — the equivalent of the legacy
+ * `ArtificialNode__DO_NOT_USE` flow used when a block DOM element appears
+ * inside another block lexical ancestor. Accepts block nodes; runs of inline
+ * children are emitted with a line break between consecutive runs (instead
+ * of being wrapped in a paragraph, which would introduce an extra level of
+ * nesting).
+ *
+ * @experimental
+ */
+export const NestedBlockSchema: ChildSchema = {
+  $accepts: $isBlockLevel,
+  /**
+   * Pass an inline run through unchanged. Because the schema iterator only
+   * groups *maximal* rejected runs (each separated from the next by an
+   * accepted block child), the legacy "linebreak between adjacent inline
+   * groups" case never arises — adjacent inline siblings are already
+   * coalesced into one run.
+   */
+  $packageRun: run => run,
+  name: 'NestedBlockSchema',
+};
+
+/**
+ * Schema for the topmost level of `$generateNodesFromDOM`. Identical to
+ * {@link BlockSchema}; aliased for clarity at the entry point and so it can
+ * be overridden separately in the future (e.g. to synthesize a `ListNode`
+ * around runs of orphan `ListItemNode`s).
+ *
+ * @experimental
+ */
+export const RootSchema: ChildSchema = {
+  $accepts: $isBlockLevel,
+  $packageRun: $paragraphPackageRun,
+  name: 'RootSchema',
+};