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

package/src/import/DOMImportExtension.ts

@@ -0,0 +1,221 @@
+/**
+ * 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 {ContextRecord} from '../types';
+import type {DOMImportRuleEntry} from './defineOverlayRules';
+import type {
+  DOMImportExtensionOutput,
+  DOMPreprocessContext,
+  DOMPreprocessFn,
+  GenerateNodesFromDOMOptions,
+  ImportContextPairOrUpdater,
+} from './types';
+
+import {$getExtensionOutput} from '@lexical/extension';
+import {defineExtension, type LexicalNode, shallowMergeConfig} from 'lexical';
+
+import {DOMImportContextSymbol, DOMImportExtensionName} from '../constants';
+import {$withFullContext, contextFromPairs} from '../ContextRecord';
+import {type CompiledDispatch, compileImportRules} from './compileImportRules';
+import {defineImportRule} from './defineImportRule';
+import {flattenRuleEntries} from './defineOverlayRules';
+import {ImportSessionImpl} from './ImportContext';
+import {$inlineStylesFromStyleSheets} from './inlineStylesFromStyleSheets';
+import {$runImport} from './runImport';
+import {selBase} from './sel';
+
+/**
+ * Configuration for {@link DOMImportExtension}.
+ *
+ * @experimental
+ */
+export interface DOMImportConfig {
+  /**
+   * The set of rules contributed by this extension and its dependencies.
+   * Entries can be raw {@link DOMImportRule}s or a
+   * {@link CompiledOverlayRules} produced by {@link defineOverlayRules}
+   * (the latter is inlined in priority order — useful for libraries
+   * that already publish a compiled overlay).
+   *
+   * Rules are dispatched in priority order: rules contributed by
+   * extensions merged later (i.e. closer to the editor root) run first
+   * and may call `$next()` to delegate to lower-priority rules.
+   *
+   * `mergeConfig` prepends `partial.rules` to existing `rules`, so later
+   * configuration carries higher priority.
+   */
+  readonly rules: readonly DOMImportRuleEntry[];
+  /**
+   * Default context pairs applied to every `$generateNodesFromDOM` call.
+   * Per-call overrides can be supplied via
+   * {@link GenerateNodesFromDOMOptions.context}.
+   */
+  readonly contextDefaults: readonly ImportContextPairOrUpdater[];
+  /**
+   * Functions run in order on the DOM before walking begins, mutating in
+   * place. The default config registers
+   * {@link $inlineStylesFromStyleSheets} (resolves `<style>` rules to
+   * inline styles so the rules' style-driven matchers see them); apps
+   * append additional preprocessors (e.g. strip unsafe elements,
+   * normalize attributes, resolve relative URLs).
+   *
+   * `mergeConfig` appends, so each contributing extension's preprocessors
+   * run in dependency order. Per-call preprocessors registered via
+   * {@link GenerateNodesFromDOMOptions.preprocess} run AFTER these.
+   */
+  readonly preprocess: readonly DOMPreprocessFn[];
+}
+
+/**
+ * Drive a stack of {@link DOMPreprocessFn}s top-to-bottom: the highest-
+ * index fn runs first and may call `$next()` to defer to the next-lower
+ * one. Matches the export-side `callExportMimeTypeFunctionStack` shape.
+ */
+function $runPreprocessStack(
+  stack: readonly DOMPreprocessFn[],
+  dom: Document | ParentNode,
+  ctx: DOMPreprocessContext,
+): void {
+  let i = stack.length - 1;
+  const $next = () => {
+    while (i >= 0) {
+      const cur = stack[i--];
+      cur(dom, ctx, $next);
+      return;
+    }
+  };
+  $next();
+}
+
+/**
+ * Lowest-priority catch-all rule used as the default `config.rules` entry
+ * for {@link DOMImportExtension}: descends into the element's children
+ * and returns whatever they produced. With no other matching rule, an
+ * element vanishes and its contents are inserted in its place — the
+ * legacy `$createNodesFromDOM` hoisting behavior, but now expressed as a
+ * regular rule that apps can override (e.g. with a `sel.any()` rule that
+ * captures and discards unknown elements).
+ *
+ * @experimental
+ */
+export const DefaultHoistRule = defineImportRule({
+  $import: (ctx, el) => ctx.$importChildren(el),
+  match: selBase.any(),
+  name: '@lexical/html/default-hoist',
+});
+
+/**
+ * @experimental
+ *
+ * Extension-based replacement for the legacy `importDOM` / `DOMConversion`
+ * machinery. Rules are contributed via configuration (see
+ * {@link DOMImportConfig.rules}), compiled into a tag-bucketed dispatcher at
+ * editor build time, and consumed via the extension's
+ * {@link DOMImportExtensionOutput.$generateNodesFromDOM} output.
+ *
+ * The legacy `$generateNodesFromDOM` continues to work in parallel; the
+ * intent is to migrate node packages over to this extension incrementally.
+ */
+export const DOMImportExtension = defineExtension<
+  DOMImportConfig,
+  typeof DOMImportExtensionName,
+  DOMImportExtensionOutput,
+  void
+>({
+  build(editor, config) {
+    const dispatch: CompiledDispatch = compileImportRules(
+      flattenRuleEntries(config.rules),
+    );
+    const defaults = contextFromPairs(config.contextDefaults, undefined);
+    const configPreprocess = config.preprocess;
+    return {
+      $generateNodesFromDOM: (
+        dom: Document | ParentNode,
+        options?: GenerateNodesFromDOMOptions,
+      ) => {
+        // The session record IS the root layer of the walk's context.
+        // Start with per-call options.context applied on top of the
+        // editor's contextDefaults, then ensure we have a *fresh*
+        // mutable child (never the shared defaults record) so
+        // session.set writes never leak into the editor's config.
+        const fromOpts =
+          options && options.context
+            ? contextFromPairs(options.context, defaults)
+            : defaults;
+        const sessionRecord: ContextRecord<typeof DOMImportContextSymbol> =
+          fromOpts !== undefined && fromOpts !== defaults
+            ? fromOpts
+            : Object.create(defaults || null);
+        const session = new ImportSessionImpl(sessionRecord);
+        const preprocessCtx: DOMPreprocessContext = {session};
+        // Stack of preprocessors: config-level first, then per-call.
+        // Top of stack (last in array) runs first; `next()` defers to
+        // the next-lower one. Matches the GetClipboardDataExtension
+        // convention so app-registered preprocessors can wrap built-in
+        // ones via `next()`. Preprocess writes via `ctx.session.set`
+        // mutate the session record directly.
+        const stack: readonly DOMPreprocessFn[] =
+          options && options.preprocess
+            ? [...configPreprocess, ...options.preprocess]
+            : configPreprocess;
+        $runPreprocessStack(stack, dom, preprocessCtx);
+        return $withFullContext(
+          DOMImportContextSymbol,
+          sessionRecord,
+          () => $runImport(dispatch, editor, dom, session),
+          editor,
+        );
+      },
+      defaults,
+    };
+  },
+  config: {
+    contextDefaults: [],
+    preprocess: [$inlineStylesFromStyleSheets],
+    rules: [DefaultHoistRule],
+  },
+  mergeConfig(config, partial) {
+    return shallowMergeConfig(config, {
+      ...partial,
+      ...(partial.contextDefaults && {
+        contextDefaults: [
+          ...config.contextDefaults,
+          ...partial.contextDefaults,
+        ],
+      }),
+      ...(partial.preprocess && {
+        preprocess: [...config.preprocess, ...partial.preprocess],
+      }),
+      ...(partial.rules && {
+        rules: [...partial.rules, ...config.rules],
+      }),
+    });
+  },
+  name: DOMImportExtensionName,
+});
+
+/**
+ * Look up the editor's {@link DOMImportExtension} and run its
+ * `$generateNodesFromDOM`. Designed as a drop-in replacement for the
+ * legacy `$generateNodesFromDOM(editor, dom)` signature so it can be
+ * supplied to `ClipboardImportExtension.$generateNodesFromDOM` (or any
+ * other consumer that wants to route through the extension pipeline).
+ *
+ * Throws if the editor was not built with {@link DOMImportExtension} as a
+ * dependency.
+ *
+ * @experimental
+ */
+export function $generateNodesFromDOMViaExtension(
+  dom: Document | ParentNode,
+  options?: GenerateNodesFromDOMOptions,
+): LexicalNode[] {
+  return $getExtensionOutput(DOMImportExtension).$generateNodesFromDOM(
+    dom,
+    options,
+  );
+}

package/src/import/HorizontalRuleImportExtension.ts

@@ -0,0 +1,52 @@
+/**
+ * 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 {
+  $createHorizontalRuleNode,
+  HorizontalRuleExtension,
+} from '@lexical/extension';
+import {configExtension, defineExtension} from 'lexical';
+
+import {defineImportRule} from './defineImportRule';
+import {DOMImportExtension} from './DOMImportExtension';
+import {selBase} from './sel';
+
+const HorizontalRuleRule = defineImportRule({
+  $import: () => [$createHorizontalRuleNode()],
+  match: selBase.tag('hr'),
+  name: '@lexical/html/hr',
+});
+
+/**
+ * Import rules for {@link HorizontalRuleNode}.
+ *
+ * @experimental
+ */
+export const HorizontalRuleImportRules = [HorizontalRuleRule];
+
+/**
+ * Bundles {@link HorizontalRuleImportRules} together with the runtime
+ * {@link HorizontalRuleExtension}. The application is expected to
+ * already have `CoreImportExtension` (or some equivalent) in its
+ * dependency graph — the core/text/paragraph/inline-format rules are a
+ * shared baseline, not something this leaf importer should re-declare.
+ *
+ * Lives in `@lexical/html` (not `@lexical/extension`) because
+ * {@link DOMImportExtension} itself is in `@lexical/html`, and
+ * `@lexical/extension` is upstream of `@lexical/html` in the dependency
+ * graph.
+ *
+ * @experimental
+ */
+export const HorizontalRuleImportExtension = defineExtension({
+  dependencies: [
+    HorizontalRuleExtension,
+    configExtension(DOMImportExtension, {rules: HorizontalRuleImportRules}),
+  ],
+  name: '@lexical/html/HorizontalRuleImport',
+});

package/src/import/ImportContext.ts

@@ -0,0 +1,339 @@
+/**
+ * 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 {ContextRecord} from '../types';
+import type {CompiledOverlayRules} from './defineOverlayRules';
+import type {DOMImportExtension} from './DOMImportExtension';
+import type {
+  ImportContextPairOrUpdater,
+  ImportSession,
+  ImportStateConfig,
+} from './types';
+
+import {getPeerDependencyFromEditor} from '@lexical/extension';
+import {
+  $getEditor,
+  isBlockDomNode,
+  isDOMTextNode,
+  isHTMLElement,
+  isInlineDomNode,
+  type LexicalEditor,
+} from 'lexical';
+
+import {DOMImportContextSymbol, DOMImportExtensionName} from '../constants';
+import {
+  $withContext,
+  createContextState,
+  getContextRecord,
+  getContextValue,
+} from '../ContextRecord';
+
+type ImportContextRecord = ContextRecord<typeof DOMImportContextSymbol>;
+
+/**
+ * Create an import context state. The phantom symbol prevents accidental
+ * use of a render-context state in an import context (and vice versa).
+ *
+ * Note: to support the value-or-updater pattern, `V` cannot be a function
+ * type; wrap it in an array or object if needed.
+ *
+ * `getDefaultValue` is called **once at state creation** and the result is
+ * shared between every session that reads the state without first writing
+ * a value. Defaults must therefore be immutable (primitives, frozen
+ * objects, or read-only arrays / records). If your state needs mutable
+ * per-session storage, lazily initialize it inside your rule (e.g.
+ * `if (!ctx.session.has(cfg)) ctx.session.set(cfg, new …())`).
+ *
+ * @experimental
+ * @__NO_SIDE_EFFECTS__
+ */
+export function createImportState<V>(
+  name: string,
+  getDefaultValue: () => V,
+  isEqual?: (a: V, b: V) => boolean,
+): ImportStateConfig<V> {
+  return createContextState(
+    DOMImportContextSymbol,
+    name,
+    getDefaultValue,
+    isEqual,
+  );
+}
+
+/**
+ * The kind of operation that produced this import. Lets rules adapt
+ * their behavior (e.g. preserve more whitespace on `'paste'`).
+ * Defaults to `'unknown'`. Apps that need a different vocabulary can
+ * define their own {@link ImportStateConfig} with whatever value type
+ * they want.
+ *
+ * @experimental
+ */
+export type ImportSourceKind = 'paste' | 'unknown';
+
+/**
+ * Built-in import-context state identifying how this import was initiated.
+ * Callers of `$generateNodesFromDOM` should set it via the `context` option.
+ *
+ * @experimental
+ */
+export const ImportSource: ImportStateConfig<ImportSourceKind> =
+  createImportState<ImportSourceKind>('importSource', () => 'unknown');
+
+/**
+ * Built-in import-context state holding the {@link DataTransfer} the
+ * import was sourced from, if any. `null` outside paste/drop flows.
+ *
+ * The clipboard import pipeline passes the original `DataTransfer`
+ * through to its per-MIME-type handler stack (see
+ * {@link ImportMimeTypeFunction}); handlers that route HTML through
+ * the {@link DOMImportExtension} pipeline should forward it into the
+ * walk via `context: [contextValue(ImportSourceDataTransfer,
+ * dataTransfer)]` so rules and preprocessors can call
+ * `ctx.get(ImportSourceDataTransfer)` to inspect companion MIME types
+ * (e.g. an `'application/rtf'` alternative or an attached
+ * `'application/x-officedrawing'` payload), the file list, or any
+ * custom drag-and-drop slot.
+ *
+ * Use sparingly: the safer pattern is to decide *which* MIME-type
+ * payload to walk in the clipboard handler stack and hand a finalized
+ * DOM to the rules; only fall back to peeking at `ImportSourceDataTransfer`
+ * when the source-detection signal genuinely lives in a companion
+ * slot.
+ *
+ * @experimental
+ */
+export const ImportSourceDataTransfer: ImportStateConfig<DataTransfer | null> =
+  createImportState<DataTransfer | null>(
+    'importSourceDataTransfer',
+    () => null,
+  );
+
+/**
+ * Built-in import-context state holding the bit-packed
+ * {@link TextFormatType} formats that should apply to {@link TextNode}s
+ * produced during the current subtree. Used by inline-format wrappers
+ * (`<b>`, `<i>`, `<u>`, …) to propagate formatting through the context
+ * record instead of via the legacy `forChild` chain.
+ *
+ * @experimental
+ */
+export const ImportTextFormat: ImportStateConfig<number> = createImportState(
+  'textFormat',
+  () => 0,
+);
+
+/**
+ * Built-in import-context state holding a parsed CSS-style record
+ * (the {@link getStyleObjectFromCSS} shape) that should apply to
+ * {@link TextNode}s produced during the current subtree. Mirrors the
+ * format-bit propagation in {@link ImportTextFormat} for properties
+ * that don't fit into the format bit mask — `color`, `font-family`,
+ * `font-size`, etc.
+ *
+ * Ancestor rules that contribute a style branch the context with a
+ * merged record; the core `#text` rule materializes the non-empty
+ * record to a CSS string and calls `setStyle` on the new TextNode.
+ * Once TextNode adopts a parsed style record, the materialization
+ * step will go away.
+ *
+ * @experimental
+ */
+export const ImportTextStyle: ImportStateConfig<
+  Readonly<Record<string, string>>
+> = createImportState<Readonly<Record<string, string>>>(
+  'textStyle',
+  () => ({}),
+);
+
+/**
+ * Determines whether a given DOM element should be treated as preserving
+ * whitespace (i.e. text content under it is not collapsed and is split on
+ * `\n` / `\t` into `LineBreakNode` / `TabNode`). The default matches the
+ * legacy behavior: the element itself is `<pre>` or its inline
+ * `white-space` style begins with `'pre'`.
+ *
+ * @experimental
+ */
+export type IsPreserveWhitespaceDom = (node: Node) => boolean;
+
+/**
+ * Determines whether a given DOM node sits on the same visual line as its
+ * adjacent text siblings, governing whether leading/trailing whitespace in
+ * a `#text` is collapsed against neighbors. The default consults
+ * {@link isInlineDomNode} from `lexical` (style.display or a fixed inline
+ * tag-name set) and additionally treats elements with an explicit
+ * non-inline `display` style as block.
+ *
+ * @experimental
+ */
+export type IsInlineForWhitespace = (node: Node) => boolean;
+
+/**
+ * Configuration for the core text whitespace-collapse logic. Override via
+ * {@link ImportWhitespaceConfig} either as a `contextDefaults` entry on
+ * the {@link DOMImportExtension} or per-call on `$generateNodesFromDOM`'s
+ * `context` option.
+ *
+ * @experimental
+ */
+export interface WhitespaceImportConfig {
+  /** See {@link IsPreserveWhitespaceDom}. */
+  readonly preservesWhitespace: IsPreserveWhitespaceDom;
+  /** See {@link IsInlineForWhitespace}. */
+  readonly isInline: IsInlineForWhitespace;
+}
+
+/**
+ * Default {@link WhitespaceImportConfig.preservesWhitespace}: matches
+ * `<pre>` and any element with `white-space: pre*`.
+ *
+ * @experimental
+ */
+export function defaultPreservesWhitespace(node: Node): boolean {
+  if (!isHTMLElement(node)) {
+    return false;
+  }
+  if (node.nodeName === 'PRE') {
+    return true;
+  }
+  const ws = node.style.whiteSpace;
+  return typeof ws === 'string' && ws.startsWith('pre');
+}
+
+/**
+ * Default {@link WhitespaceImportConfig.isInline}: treats an element as
+ * inline iff its inline `display` style is `inline*` OR (no explicit
+ * non-inline display) its nodeName is a known inline tag (`isInlineDomNode`).
+ * Text nodes are always inline; comments and other non-elements are not.
+ *
+ * @experimental
+ */
+export function defaultIsInline(node: Node): boolean {
+  if (isDOMTextNode(node)) {
+    return true;
+  }
+  if (!isHTMLElement(node)) {
+    return false;
+  }
+  const display = node.style.display;
+  if (display) {
+    return display.startsWith('inline');
+  }
+  if (isBlockDomNode(node)) {
+    return false;
+  }
+  return isInlineDomNode(node);
+}
+
+/**
+ * Built-in import-context state controlling text-node whitespace handling
+ * (collapse vs. preserve, what counts as an inline sibling). Override per
+ * editor via {@link DOMImportConfig.contextDefaults} or per call via
+ * {@link GenerateNodesFromDOMOptions.context}.
+ *
+ * @experimental
+ */
+export const ImportWhitespaceConfig: ImportStateConfig<WhitespaceImportConfig> =
+  createImportState<WhitespaceImportConfig>('whitespaceConfig', () => ({
+    isInline: defaultIsInline,
+    preservesWhitespace: defaultPreservesWhitespace,
+  }));
+
+/**
+ * Built-in session slot for runtime overlay rules that should be in
+ * effect for the entire walk. A preprocessor writes here when it wants
+ * to conditionally install handling for a particular paste source
+ * (e.g. "if the Microsoft Word generator meta tag is present, push the
+ * Word-paste overlay"). Each entry contributes an overlay dispatcher
+ * to the runtime's overlay stack; later array entries are higher
+ * priority. Use `ctx.session.update(ImportOverlays, prev => […])` to
+ * append.
+ *
+ * This is the walk-wide counterpart to
+ * `$importChildren({rules: …})` (which scopes an overlay to one
+ * subtree): write to {@link ImportOverlays} when the overlay should
+ * apply for the whole document; use `$importChildren`'s `rules` when
+ * the overlay should only apply for a deeper region.
+ *
+ * @experimental
+ */
+export const ImportOverlays: ImportStateConfig<
+  readonly CompiledOverlayRules[]
+> = createImportState<readonly CompiledOverlayRules[]>(
+  'importOverlays',
+  () => [],
+);
+
+/**
+ * The session IS the root-layer {@link ContextRecord} of the walk. Reads
+ * fall through the prototype chain to the editor's `contextDefaults`,
+ * writes mutate the record's own properties, and any branch pushed by
+ * `$importChildren({context})` sits above this layer and can shadow
+ * (but does not overwrite) slots.
+ *
+ * @internal
+ */
+export class ImportSessionImpl implements ImportSession {
+  constructor(readonly record: ImportContextRecord) {}
+  get<V>(cfg: ImportStateConfig<V>): V {
+    return getContextValue(this.record, cfg);
+  }
+  set<V>(cfg: ImportStateConfig<V>, value: V): void {
+    this.record[cfg.key] = value;
+  }
+  update<V>(cfg: ImportStateConfig<V>, updater: (prev: V) => V): void {
+    this.record[cfg.key] = updater(getContextValue(this.record, cfg));
+  }
+  has<V>(cfg: ImportStateConfig<V>): boolean {
+    return Object.prototype.hasOwnProperty.call(this.record, cfg.key);
+  }
+}
+
+function getDefaultImportContext(
+  editor: LexicalEditor,
+): undefined | ContextRecord<typeof DOMImportContextSymbol> {
+  const dep = getPeerDependencyFromEditor<typeof DOMImportExtension>(
+    editor,
+    DOMImportExtensionName,
+  );
+  return dep ? dep.output.defaults : undefined;
+}
+
+function getImportContext(
+  editor: LexicalEditor,
+): undefined | ContextRecord<typeof DOMImportContextSymbol> {
+  return (
+    getContextRecord(DOMImportContextSymbol, editor) ||
+    getDefaultImportContext(editor)
+  );
+}
+
+/**
+ * Read an import context value during an import operation.
+ * @experimental
+ */
+export function $getImportContextValue<V>(
+  cfg: ImportStateConfig<V>,
+  editor: LexicalEditor = $getEditor(),
+): V {
+  return getContextValue(getImportContext(editor), cfg);
+}
+
+/**
+ * Run `f` with the given context pairs applied on top of the editor's
+ * current import context.
+ *
+ * @experimental
+ */
+export const $withImportContext: (
+  cfg: readonly ImportContextPairOrUpdater[],
+  editor?: LexicalEditor,
+) => <T>(f: () => T) => T = $withContext(
+  DOMImportContextSymbol,
+  getDefaultImportContext,
+);