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

package/src/import/index.ts

@@ -0,0 +1,97 @@
+/**
+ * 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 {parseSelector} from './parseCss';
+import {selBase} from './sel';
+
+/**
+ * Combinator-and-parser-based builder for {@link CompiledSelector}s. The
+ * runtime shape returned by these factory methods is opaque; consumers
+ * should never inspect or construct selector objects directly.
+ *
+ * @experimental
+ */
+export const sel = {
+  any: selBase.any,
+  comment: selBase.comment,
+  /**
+   * Parse a reduced CSS-selector subset and return a builder you can chain
+   * combinator methods off of.
+   */
+  css: parseSelector,
+  tag: selBase.tag,
+  text: selBase.text,
+} as const;
+
+export {CoreImportExtension} from './CoreImportExtension';
+export {CoreImportRules} from './coreImportRules';
+export {defineImportRule} from './defineImportRule';
+export {
+  type CompiledOverlayRules,
+  defineOverlayRules,
+  type DOMImportRuleEntry,
+} from './defineOverlayRules';
+export {
+  $generateNodesFromDOMViaExtension,
+  type DOMImportConfig,
+  DOMImportExtension,
+} from './DOMImportExtension';
+export {
+  HorizontalRuleImportExtension,
+  HorizontalRuleImportRules,
+} from './HorizontalRuleImportExtension';
+export {
+  $getImportContextValue,
+  $withImportContext,
+  createImportState,
+  defaultIsInline,
+  defaultPreservesWhitespace,
+  ImportOverlays,
+  ImportSource,
+  ImportSourceDataTransfer,
+  type ImportSourceKind,
+  ImportTextFormat,
+  ImportTextStyle,
+  ImportWhitespaceConfig,
+  type IsInlineForWhitespace,
+  type IsPreserveWhitespaceDom,
+  type WhitespaceImportConfig,
+} from './ImportContext';
+export {$inlineStylesFromStyleSheets} from './inlineStylesFromStyleSheets';
+export {parseSelector} from './parseCss';
+export {
+  $distributeInlineWrapper,
+  $isBlockLevel,
+  $propagateTextAlignToBlockChildren,
+  BlockSchema,
+  InlineSchema,
+  NestedBlockSchema,
+  RootSchema,
+} from './schemas';
+export {isElementOfTag} from './sel';
+export type {
+  AnyDOMImportRule,
+  AttrMatchOptions,
+  CapturesOfSelector,
+  ChildSchema,
+  CompiledSelector,
+  DOMImportContext,
+  DOMImportExtensionOutput,
+  DOMImportFn,
+  DOMImportRule,
+  DOMPreprocessContext,
+  DOMPreprocessFn,
+  ElementSelectorBuilder,
+  GenerateNodesFromDOMOptions,
+  ImportChildrenOpts,
+  ImportContextPairOrUpdater,
+  ImportNodeOpts,
+  ImportSession,
+  ImportStateConfig,
+  NodeOfSelector,
+  StyleMatchOptions,
+} from './types';

package/src/import/inlineStylesFromStyleSheets.ts

@@ -0,0 +1,104 @@
+/**
+ * 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 {DOMPreprocessFn} from './types';
+
+import {objectKlassEquals} from '@lexical/utils';
+import {isDOMDocumentNode, isHTMLElement} from 'lexical';
+
+/**
+ * Inlines CSS rules from `<style>` tags onto matching elements as inline
+ * styles.
+ *
+ * Used by apps like Excel that generate HTML where styles live in
+ * class-based `<style>` rules (e.g. `.xl65 { background: #FFFF00; color:
+ * blue; }`) rather than inline styles. Since Lexical's import converters
+ * read inline styles, we resolve stylesheet rules into inline styles
+ * before conversion.
+ *
+ * Mutates the DOM in-place. Original inline styles always take
+ * precedence over stylesheet rules (matching CSS specificity behavior).
+ *
+ * No-op for {@link ParentNode}s that are not {@link Document}s — only a
+ * full document carries `styleSheets` we can iterate.
+ *
+ * @experimental
+ */
+export const $inlineStylesFromStyleSheets: DOMPreprocessFn = (
+  dom,
+  _ctx,
+  $next,
+) => {
+  $inlineStylesFromStyleSheetsDOM(dom);
+  $next();
+};
+
+export function $inlineStylesFromStyleSheetsDOM(
+  dom: Document | ParentNode,
+): void {
+  if (!isDOMDocumentNode(dom)) {
+    return;
+  }
+  const doc = dom;
+  if (doc.querySelector('style') === null) {
+    return;
+  }
+
+  const originalInlineStyles = new Map<HTMLElement, Set<string>>();
+
+  function getOriginalInlineProps(el: HTMLElement): Set<string> {
+    let props = originalInlineStyles.get(el);
+    if (props === undefined) {
+      props = new Set<string>();
+      for (let i = 0; i < el.style.length; i++) {
+        props.add(el.style[i]);
+      }
+      originalInlineStyles.set(el, props);
+    }
+    return props;
+  }
+
+  try {
+    for (const sheet of Array.from(doc.styleSheets)) {
+      let rules: CSSRuleList;
+      try {
+        rules = sheet.cssRules;
+      } catch {
+        continue;
+      }
+      for (const rule of Array.from(rules)) {
+        if (!objectKlassEquals(rule, CSSStyleRule)) {
+          continue;
+        }
+        let elements: NodeListOf<Element>;
+        try {
+          elements = doc.querySelectorAll(rule.selectorText);
+        } catch {
+          continue;
+        }
+        for (const el of Array.from(elements)) {
+          if (!isHTMLElement(el)) {
+            continue;
+          }
+          const originalProps = getOriginalInlineProps(el);
+          for (let i = 0; i < rule.style.length; i++) {
+            const prop = rule.style[i];
+            if (!originalProps.has(prop)) {
+              el.style.setProperty(
+                prop,
+                rule.style.getPropertyValue(prop),
+                rule.style.getPropertyPriority(prop),
+              );
+            }
+          }
+        }
+      }
+    }
+  } catch {
+    // styleSheets API not supported in this environment
+  }
+}

package/src/import/parseCss.ts

@@ -0,0 +1,219 @@
+/**
+ * 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 {Predicate} from './sel';
+import type {ElementSelectorBuilder} from './types';
+
+import invariant from '@lexical/internal/invariant';
+
+import {buildAttrPredicate, buildClassAllPredicate, buildSelector} from './sel';
+
+const IDENT_CHAR = /[A-Za-z0-9_-]/;
+
+class Cursor {
+  constructor(
+    public readonly source: string,
+    public pos: number,
+  ) {}
+  peek(offset = 0): string {
+    return this.source[this.pos + offset] || '';
+  }
+  consume(): string {
+    return this.source[this.pos++] || '';
+  }
+  eof(): boolean {
+    return this.pos >= this.source.length;
+  }
+  skipWhitespace(): void {
+    while (!this.eof() && /\s/.test(this.peek())) {
+      this.pos++;
+    }
+  }
+  readIdent(): string {
+    const start = this.pos;
+    while (!this.eof() && IDENT_CHAR.test(this.peek())) {
+      this.pos++;
+    }
+    return this.source.slice(start, this.pos);
+  }
+  readQuoted(): string {
+    const quote = this.consume();
+    this.assert(quote === '"' || quote === "'", 'expected quote');
+    const start = this.pos;
+    while (!this.eof() && this.peek() !== quote) {
+      if (this.peek() === '\\') {
+        this.pos += 2;
+      } else {
+        this.pos++;
+      }
+    }
+    this.assert(!this.eof(), 'unterminated string');
+    const value = this.source.slice(start, this.pos);
+    this.pos++; // consume closing quote
+    return value.replace(/\\(.)/g, '$1');
+  }
+  /**
+   * `invariant(cond, fmt, …)`-flavored assertion that also surfaces the
+   * cursor's position context. Use for parse-time errors so a malformed
+   * CSS selector gets a useful, position-annotated message.
+   */
+  assert(cond: boolean, msg: string): asserts cond {
+    invariant(
+      cond,
+      'invalid CSS selector at col %s: %s in %s',
+      String(this.pos + 1),
+      msg,
+      this.source,
+    );
+  }
+}
+
+interface ParsedSimpleSelector {
+  readonly tags: Set<string>;
+  readonly predicates: Predicate[];
+}
+
+function parseSimpleSelector(c: Cursor): ParsedSimpleSelector {
+  const tags = new Set<string>();
+  const predicates: Predicate[] = [];
+  const classes: string[] = [];
+
+  c.skipWhitespace();
+
+  // Optional tag or '*'
+  if (c.peek() === '*') {
+    c.consume();
+  } else if (IDENT_CHAR.test(c.peek())) {
+    const tag = c.readIdent();
+    if (tag) {
+      tags.add(tag.toUpperCase());
+    }
+  }
+
+  // Zero or more refinements: .class, #id, [attr]
+  while (!c.eof()) {
+    const ch = c.peek();
+    if (ch === '.') {
+      c.consume();
+      const cls = c.readIdent();
+      c.assert(cls !== '', 'expected class name after "."');
+      classes.push(cls);
+    } else if (ch === '#') {
+      c.consume();
+      const id = c.readIdent();
+      c.assert(id !== '', 'expected id after "#"');
+      predicates.push(buildAttrPredicate('id', id));
+    } else if (ch === '[') {
+      c.consume();
+      c.skipWhitespace();
+      const name = c.readIdent();
+      c.assert(name !== '', 'expected attribute name after "["');
+      c.skipWhitespace();
+      let value: true | string = true;
+      if (c.peek() === '=') {
+        c.consume();
+        c.skipWhitespace();
+        const next = c.peek();
+        if (next === '"' || next === "'") {
+          value = c.readQuoted();
+        } else {
+          value = c.readIdent();
+          c.assert(value !== '', 'expected attribute value');
+        }
+        c.skipWhitespace();
+      }
+      c.assert(c.peek() === ']', 'expected "]"');
+      c.consume();
+      predicates.push(buildAttrPredicate(name, value));
+    } else {
+      break;
+    }
+  }
+
+  if (classes.length > 0) {
+    predicates.push(buildClassAllPredicate(classes));
+  }
+
+  return {predicates, tags};
+}
+
+/**
+ * Parse a reduced CSS-selector subset and return a {@link CompiledSelector}.
+ * Supported:
+ * - Tag (`p`), wildcard (`*`).
+ * - Tag list (`h1, h2, h3`).
+ * - Class (`.foo`, `.foo.bar`).
+ * - ID (`#foo`).
+ * - Attribute presence (`[name]`).
+ * - Attribute equality (`[name="value"]`, `[name=value]`).
+ *
+ * Anything outside the subset (regex attribute, inline-style match,
+ * combinators, pseudo-classes) is intentionally rejected — chain combinator
+ * methods off the returned builder instead.
+ *
+ * @experimental
+ */
+export function parseSelector(
+  source: string,
+): ElementSelectorBuilder<HTMLElement> {
+  const c: Cursor = new Cursor(source, 0);
+  const groups: ParsedSimpleSelector[] = [];
+
+  while (true) {
+    const group = parseSimpleSelector(c);
+    if (group.tags.size === 0 && group.predicates.length === 0) {
+      // Empty group with neither tag nor refinement — only OK if it came
+      // from the lone `*` (which produces zero tags but no preds either).
+      // We accept this as "wildcard element".
+    }
+    groups.push(group);
+    c.skipWhitespace();
+    if (c.eof()) {
+      break;
+    }
+    c.assert(
+      c.peek() === ',',
+      'expected "," (selector lists are the only supported combinator)',
+    );
+    c.consume();
+    c.skipWhitespace();
+  }
+
+  if (groups.length === 1) {
+    return buildSelector(groups[0].tags, groups[0].predicates);
+  }
+
+  // Comma-separated list. Merge tag sets and OR-combine the per-group
+  // refinement predicates so that each candidate node satisfies *some*
+  // group entirely.
+  const tags = new Set<string>();
+  for (const g of groups) {
+    for (const t of g.tags) {
+      tags.add(t);
+    }
+  }
+  const orPredicate: Predicate = (node, captures) => {
+    for (const g of groups) {
+      const upper = node.nodeName;
+      if (g.tags.size > 0 && !g.tags.has(upper)) {
+        continue;
+      }
+      let ok = true;
+      for (const p of g.predicates) {
+        if (!p(node, captures)) {
+          ok = false;
+          break;
+        }
+      }
+      if (ok) {
+        return true;
+      }
+    }
+    return false;
+  };
+  return buildSelector(tags, [orPredicate]);
+}

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});
+}