@lexical/html 0.44.1-nightly.20260519.0 → 0.45.1-dev.0

package/src/import/types.ts

@@ -0,0 +1,471 @@
+/**
+ * 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 {DOMImportContextSymbol} from '../constants';
+import type {
+  AnyContextConfigPairOrUpdater,
+  ContextConfig,
+  ContextRecord,
+} from '../types';
+import type {CompiledOverlayRules} from './defineOverlayRules';
+import type {LexicalNode} from 'lexical';
+
+/**
+ * Phantom-typed branding so consumers cannot construct or mutate a
+ * {@link CompiledSelector} directly; the only way to obtain one is via the
+ * {@link sel} builder or {@link parseSelector}. The actual runtime shape is
+ * an internal implementation detail (see `./sel`).
+ *
+ * @experimental
+ */
+export declare const NodeBrand: unique symbol;
+/** @experimental */
+export declare const CaptureBrand: unique symbol;
+
+/**
+ * An opaque, compiled selector used as the `match` field of a
+ * {@link DOMImportRule}. The two phantom type parameters carry the matched
+ * Node subtype (`N`) and a record of named regex captures (`C`) so the
+ * importer body gets correctly-typed `ctx` and `node` arguments without
+ * casts.
+ *
+ * @experimental
+ */
+export interface CompiledSelector<
+  N extends Node = Node,
+  C extends Record<string, RegExpMatchArray> = Record<string, RegExpMatchArray>,
+> {
+  readonly [NodeBrand]?: N;
+  readonly [CaptureBrand]?: C;
+}
+
+/**
+ * The Node subtype matched by a selector (e.g. `HTMLAnchorElement` for
+ * `sel.tag('a')`, `Text` for `sel.text()`).
+ *
+ * @experimental
+ */
+export type NodeOfSelector<S> =
+  S extends CompiledSelector<infer N, Record<string, RegExpMatchArray>>
+    ? N
+    : Node;
+
+/**
+ * The named-capture map for a selector.
+ *
+ * @experimental
+ */
+export type CapturesOfSelector<S> =
+  S extends CompiledSelector<Node, infer C> ? C : Record<string, never>;
+
+/**
+ * Options bag for {@link ElementSelectorBuilder.attr} when the value is a
+ * regex. Future options will be added here without breaking existing
+ * call-sites.
+ *
+ * @experimental
+ */
+export interface AttrMatchOptions<K extends string = string> {
+  /**
+   * If provided, the {@link RegExpMatchArray} from the successful match is
+   * stored on `ctx.captures[capture]` for the importer to consume — saving
+   * a second regex execution.
+   */
+  readonly capture?: K;
+}
+
+/**
+ * Options bag for {@link ElementSelectorBuilder.styleAny} when the value is a
+ * regex. See {@link AttrMatchOptions} for capture semantics.
+ *
+ * @experimental
+ */
+export interface StyleMatchOptions<K extends string = string> {
+  readonly capture?: K;
+}
+
+/**
+ * Fluent builder for an element selector. The two type parameters carry the
+ * matched element type and the named-capture map; each call refines them.
+ *
+ * The builder itself implements {@link CompiledSelector} so it can be used
+ * directly as the `match` field of a rule — no `.build()` call needed.
+ *
+ * @experimental
+ */
+export interface ElementSelectorBuilder<
+  E extends HTMLElement,
+  C extends Record<string, RegExpMatchArray> = Record<string, never>,
+> extends CompiledSelector<E, C> {
+  /** Require every listed class to be present on the element. */
+  classAll(...classes: readonly string[]): ElementSelectorBuilder<E, C>;
+  /** Require at least one of the listed classes to be present. */
+  classAny(...classes: readonly string[]): ElementSelectorBuilder<E, C>;
+  /** Require the attribute to be present (any value). */
+  attr(name: string, value: true): ElementSelectorBuilder<E, C>;
+  /** Require the attribute to equal the given string. */
+  attr(name: string, value: string): ElementSelectorBuilder<E, C>;
+  /**
+   * Require the attribute to match the given regex. With
+   * `{capture: 'name'}` the match result is exposed on
+   * `ctx.captures.name`.
+   */
+  attr<const O extends AttrMatchOptions>(
+    name: string,
+    value: RegExp,
+    options?: O,
+  ): ElementSelectorBuilder<
+    E,
+    O extends {capture: infer K} ? C & Record<K & string, RegExpMatchArray> : C
+  >;
+  /** Require the inline-style declaration to equal `value`. */
+  styleAny(prop: string, value: string): ElementSelectorBuilder<E, C>;
+  /** Require the inline-style declaration to match `value`. */
+  styleAny<const O extends StyleMatchOptions>(
+    prop: string,
+    value: RegExp,
+    options?: O,
+  ): ElementSelectorBuilder<
+    E,
+    O extends {capture: infer K} ? C & Record<K & string, RegExpMatchArray> : C
+  >;
+}
+
+/**
+ * Argument to {@link DOMImportContext.branch} / `$importChildren({context})`
+ * — see {@link ContextConfigPair} / {@link ContextConfigUpdater}.
+ *
+ * @experimental
+ */
+export type ImportContextPairOrUpdater = AnyContextConfigPairOrUpdater<
+  typeof DOMImportContextSymbol
+>;
+
+/**
+ * A typed context-state key for the import pipeline. Create with
+ * {@link createImportState}.
+ *
+ * @experimental
+ */
+export type ImportStateConfig<V> = ContextConfig<
+  typeof DOMImportContextSymbol,
+  V
+>;
+
+/**
+ * A mutable, document-order-shared store for the import pipeline. Lets a
+ * rule visited early in the document write information that rules visited
+ * later can read — e.g. parse `<style>` or `<meta>` and influence
+ * subsequent matching.
+ *
+ * Implemented as the root-layer {@link ContextRecord} of the import walk:
+ * `ctx.session.set(cfg, v)` mutates the slot on that root record, and
+ * every unshadowed `ctx.get(cfg)` read in any branch picks it up. A
+ * `$importChildren({context: [...]})` branch that explicitly writes the
+ * same slot shadows the session value for the duration of that branch.
+ *
+ * @experimental
+ */
+export interface ImportSession {
+  /** Read the current value, returning the config's default if unset. */
+  get<V>(cfg: ImportStateConfig<V>): V;
+  /** Write `value` into the slot. */
+  set<V>(cfg: ImportStateConfig<V>, value: V): void;
+  /** Read-modify-write. */
+  update<V>(cfg: ImportStateConfig<V>, updater: (prev: V) => V): void;
+  /** Returns `true` if the slot has been written since session creation. */
+  has<V>(cfg: ImportStateConfig<V>): boolean;
+}
+
+/**
+ * Context exposed to a rule's `$import` function. Mirrors the existing render
+ * context (see {@link RenderContext}) but is import-scoped.
+ *
+ * @experimental
+ */
+export interface DOMImportContext<
+  C extends Record<string, RegExpMatchArray> = Record<string, never>,
+> {
+  /** Captures from this rule's selector. Fresh per rule invocation. */
+  readonly captures: Readonly<C>;
+  /**
+   * Mutable, document-order-shared store. Use to make information from
+   * earlier-visited nodes available to later-visited ones (e.g. a
+   * `<style>` or `<meta>` at the top of the document influencing how
+   * later elements are interpreted). One {@link ImportSession} instance
+   * is created per top-level `$generateNodesFromDOM` call and is shared
+   * across all recursive `$importChildren` / `$importOne` invocations.
+   */
+  readonly session: ImportSession;
+
+  /** Read a typed context value. */
+  get<V>(cfg: ImportStateConfig<V>): V;
+
+  /**
+   * Recursively import every child of `parent` and return the produced
+   * lexical nodes, optionally enforcing a {@link ChildSchema} and/or
+   * branching the import context for the duration of the call (via
+   * `opts.context`).
+   */
+  $importChildren(parent: ParentNode, opts?: ImportChildrenOpts): LexicalNode[];
+
+  /**
+   * Recursively import a single DOM node.
+   */
+  $importOne(node: Node, opts?: ImportNodeOpts): LexicalNode[];
+}
+
+/**
+ * Options accepted by {@link DOMImportContext.$importChildren}. The combination
+ * of `schema`, `$onChild`, and `$after` is sufficient to express every
+ * child-handling pattern in the legacy `forChild` / `after` / wrap-continuous
+ * machinery.
+ *
+ * @experimental
+ */
+export interface ImportChildrenOpts {
+  /**
+   * How to validate and (re)package produced children. Defaults to whichever
+   * schema the parent's importer passed; the top-level entry uses
+   * {@link BlockSchema}.
+   */
+  readonly schema?: ChildSchema;
+  /**
+   * Called for each produced lexical child immediately after its rule
+   * returned, with the chance to substitute or drop it. Equivalent to the
+   * old `forChild` hook but scoped to one `$importChildren` call.
+   */
+  readonly $onChild?: (child: LexicalNode) => LexicalNode | null | undefined;
+  /**
+   * Called once with the full child array after all DOM children have been
+   * recursively imported but before {@link ChildSchema.$packageRun} is
+   * applied. Equivalent to the old `after` hook.
+   */
+  readonly $after?: (children: LexicalNode[]) => LexicalNode[];
+  /** Context overrides scoped to the children traversal. */
+  readonly context?: readonly ImportContextPairOrUpdater[];
+  /**
+   * Additional {@link DOMImportRule}s active only for this children
+   * traversal (and any nested `$importChildren` calls that don't push
+   * their own overlay). The overlay is checked BEFORE the main
+   * dispatcher, so its rules take precedence; calling `$next()` from an
+   * overlay rule falls through to the next overlay-or-main rule.
+   *
+   * Use this to scope cost-bearing rules to where they apply. For
+   * example, a GitHub code-table rule installs an overlay that
+   * unwraps `<tr>` / `<td>` inside the table, without paying that
+   * predicate cost on every other `<tr>` / `<td>` paste.
+   *
+   * The value must be produced by
+   * {@link defineOverlayRules}; this forces the dispatcher to be
+   * compiled once at module scope and reused across
+   * `$importChildren` calls, instead of being recompiled per invocation.
+   */
+  readonly rules?: CompiledOverlayRules;
+}
+
+/** @experimental */
+export interface ImportNodeOpts {
+  readonly context?: readonly ImportContextPairOrUpdater[];
+}
+
+/**
+ * A {@link ChildSchema} encodes which lexical nodes a parent accepts as
+ * children and how to package or reject the rest. The legacy
+ * `wrapContinuousInlines` / `ArtificialNode__DO_NOT_USE` logic is the
+ * `BlockSchema` and `NestedBlockSchema` cases of this primitive.
+ *
+ * A schema only controls how the *children* are assembled before being
+ * appended to the parent the calling rule already chose. It cannot
+ * change the parent itself. Cases where the parent's shape needs to
+ * change in response to its children — e.g. an inline `<a>` that
+ * encloses a block `<h1>`, which must be lifted so the heading takes
+ * the link's place and the link is redistributed onto the heading's
+ * inline contents — belong in the rule body, not the schema. See the
+ * "Lifting blocks out of an inline parent" section of the docs.
+ *
+ * @experimental
+ */
+export interface ChildSchema {
+  /** Optional name for debug output. */
+  readonly name?: string;
+  /**
+   * Returns `true` if `child` is a valid child of `parent` in this position.
+   */
+  $accepts(child: LexicalNode, parent: LexicalNode | null): boolean;
+  /**
+   * Package a maximal run of non-accepted siblings into zero or more
+   * accepted nodes. The returned nodes replace the rejected run at the
+   * same position in the child list and are not re-checked against
+   * `$accepts` — the caller is trusted to return valid children. If
+   * omitted, or if it returns an empty array, {@link ChildSchema.onReject}
+   * is consulted instead.
+   */
+  $packageRun?(
+    rejected: LexicalNode[],
+    parent: LexicalNode | null,
+    domParent: Node | null,
+  ): LexicalNode[];
+  /**
+   * Fallback strategy for a run of non-accepted children when
+   * `$packageRun` is missing or returns an empty array:
+   *
+   * - `'drop'` (default) — silently discards the run. Use when the
+   *   schema is strict and rejected content is meaningless in this
+   *   position (e.g. text between table rows).
+   * - `'hoist'` — emits the rejected nodes unchanged at the same
+   *   position in the assembled child list. The caller's parent then
+   *   receives them as-is, which is only useful if the calling rule
+   *   intends to surface mixed content to *its* parent (a less common
+   *   pattern; usually `$packageRun` should re-shape the run first).
+   *
+   * `'hoist'` does NOT lift the run all the way up out of the calling
+   * rule's parent — that requires the rule itself to detect the
+   * situation and emit a different parent structure (see the
+   * "Lifting blocks out of an inline parent" section).
+   */
+  readonly onReject?: 'hoist' | 'drop';
+  /**
+   * Final pass over the assembled child list (after `$packageRun`). Returns
+   * the children to actually attach. Use to enforce structural invariants
+   * (e.g. drop empty runs, pad short table rows).
+   */
+  $finalize?(
+    children: LexicalNode[],
+    parent: LexicalNode | null,
+  ): LexicalNode[];
+}
+
+/**
+ * The middleware signature of an import rule. Call `$next()` to delegate to
+ * the next-matching rule for this node (returning its result, which may then
+ * be inspected or wrapped); return `[]` to drop the node.
+ *
+ * @experimental
+ */
+export type DOMImportFn<
+  E extends Node,
+  C extends Record<string, RegExpMatchArray> = Record<string, never>,
+> = (
+  ctx: DOMImportContext<C>,
+  node: E,
+  $next: () => readonly LexicalNode[],
+) => readonly LexicalNode[];
+
+/**
+ * An importer for a DOM node, dispatched by `match` and implemented by
+ * `$import`.
+ *
+ * @experimental
+ */
+export interface DOMImportRule<S extends CompiledSelector = CompiledSelector> {
+  /**
+   * Optional identifier surfaced in dev-mode logs, error messages, and
+   * introspection devtools. Convention: `'@scope/package/rule-id'` for
+   * library rules.
+   */
+  readonly name?: string;
+  /** A {@link CompiledSelector} produced by the {@link sel} builder. */
+  readonly match: S;
+  /** Middleware that converts the matched DOM node into lexical nodes. */
+  readonly $import: DOMImportFn<NodeOfSelector<S>, CapturesOfSelector<S>>;
+}
+
+/** @experimental */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyDOMImportRule = DOMImportRule<any>;
+
+/**
+ * Context exposed to a {@link DOMPreprocessFn}. Lets the preprocessor:
+ *
+ * - Write to the per-import {@link ImportSession} (the same
+ *   `ctx.session` rules see during the walk). Writes mutate the
+ *   root-layer context record, so they are visible to every scoped
+ *   `ctx.get(cfg)` read that hasn't been shadowed by a branch.
+ *
+ * @experimental
+ */
+export interface DOMPreprocessContext {
+  /**
+   * Document-order-shared store, same instance as `ctx.session` in
+   * rules. Use to pass info from the DOM preprocess phase (e.g.
+   * inspected `<meta>` tags, collected `<style>` text) to the
+   * importer rules.
+   */
+  readonly session: ImportSession;
+}
+
+/**
+ * A middleware step in the DOM-preprocess chain. Runs before walking
+ * begins and may:
+ *
+ * - Mutate the input DOM in place (e.g. inline stylesheets, strip
+ *   unsafe elements, normalize attributes).
+ * - Write to {@link DOMPreprocessContext.session} for rules to read
+ *   (and for unshadowed scoped reads to pick up).
+ * - Call `$next()` to defer to the next-lower preprocessor in the
+ *   stack; omit the call to short-circuit and skip the rest.
+ *
+ * The preprocess phase runs inside the same editor read / update
+ * context as the walk that follows, so a preprocess function may call
+ * `$`-prefixed Lexical APIs (e.g. `$getState`, `$getRoot`) as needed.
+ * The `$next` parameter is named with a `$` prefix to make that
+ * editor-context expectation visible to readers and lints.
+ *
+ * Append-style merge applies: an extension's preprocessors are appended
+ * to the existing stack, so later-registered preprocessors run first
+ * and may delegate to earlier (lower-priority) ones via `$next()`. Same
+ * convention as {@link ExportMimeTypeFunction} on the export side.
+ *
+ * @experimental
+ */
+export type DOMPreprocessFn = (
+  dom: Document | ParentNode,
+  ctx: DOMPreprocessContext,
+  $next: () => void,
+) => void;
+
+/**
+ * Per-call options to the extension's `$generateNodesFromDOM`.
+ *
+ * @experimental
+ */
+export interface GenerateNodesFromDOMOptions {
+  /**
+   * Context pairs/updaters applied for the duration of this import only —
+   * use to communicate per-call info such as the {@link ImportSource}.
+   */
+  readonly context?: readonly ImportContextPairOrUpdater[];
+  /**
+   * Additional preprocessors to run on this call only, on top of the
+   * extension's configured {@link DOMImportConfig.preprocess}. Per-call
+   * preprocessors run AFTER the configured ones.
+   */
+  readonly preprocess?: readonly DOMPreprocessFn[];
+}
+
+/**
+ * Output of {@link DOMImportExtension}.
+ *
+ * @experimental
+ */
+export interface DOMImportExtensionOutput {
+  /**
+   * Convert a {@link Document} or {@link ParentNode} into lexical nodes,
+   * using the dispatcher compiled from this extension's configured
+   * {@link DOMImportRule}s.
+   *
+   * Must be called within an `editor.update()` or `editor.read()` because
+   * the importers may invoke `$create...` helpers.
+   */
+  $generateNodesFromDOM(
+    dom: Document | ParentNode,
+    options?: GenerateNodesFromDOMOptions,
+  ): LexicalNode[];
+  /** @internal */
+  readonly defaults: undefined | ContextRecord<typeof DOMImportContextSymbol>;
+}