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

package/src/import/schemas.ts

@@ -0,0 +1,280 @@
+/**
+ * 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,
+  $isLineBreakNode,
+  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;
+}
+
+/**
+ * Apply a parent DOM element's `text-align` (when set to one of the
+ * supported {@link ElementFormatType} values) to each block-level child
+ * Lexical node that does not yet have its own format.
+ *
+ * Mirrors the part of the legacy `wrapContinuousInlines` that wrote
+ * `node.setFormat(textAlign)` onto pre-existing block children when the
+ * DOM parent carried `style.textAlign`. Pair with
+ * {@link $paragraphPackageRun} (which carries the same propagation onto
+ * paragraphs synthesized around inline runs) to fully replicate the
+ * legacy behavior on a run of mixed children.
+ *
+ * @experimental
+ */
+export function $propagateTextAlignToBlockChildren(
+  children: LexicalNode[],
+  domParent: Node | null,
+): LexicalNode[] {
+  if (!isHTMLElement(domParent)) {
+    return children;
+  }
+  const textAlign = domParent.style.textAlign;
+  if (!isAlignmentValue(textAlign)) {
+    return children;
+  }
+  for (const child of children) {
+    if ($isBlockElementNode(child) && child.getFormatType() === '') {
+      child.setFormat(textAlign);
+    }
+  }
+  return children;
+}
+
+/**
+ * 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[] {
+  // Mirror the legacy `$wrapInlineNodes` (driven by
+  // `selection.insertNodes`) shortcut where a lone `<br>` at this
+  // level (a `LineBreakNode` is the only thing in the rejected run)
+  // becomes an *empty* paragraph rather than a paragraph wrapping a
+  // visible line break — that's the form clipboard pastes ending in a
+  // trailing `<br>` (Google Docs, Gmail, …) rely on for the editor's
+  // "extra trailing empty line" expectation.
+  if (run.length === 1 && $isLineBreakNode(run[0])) {
+    run = [];
+  }
+  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',
+};

package/src/import/sel.ts

@@ -0,0 +1,314 @@
+/**
+ * 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 {
+  AttrMatchOptions,
+  CompiledSelector,
+  ElementSelectorBuilder,
+  StyleMatchOptions,
+} from './types';
+
+import invariant from '@lexical/internal/invariant';
+import {isDOMTextNode, isHTMLElement} from 'lexical';
+
+/**
+ * @internal
+ *
+ * A predicate that may write into the per-invocation `captures` map. Returns
+ * `true` if the rule matches; `false` otherwise.
+ */
+export type Predicate = (
+  node: Node,
+  captures: Record<string, RegExpMatchArray>,
+) => boolean;
+
+/** @internal */
+export type SelectorKind = 'element' | 'text' | 'comment';
+
+/** @internal The runtime shape of a {@link CompiledSelector}. */
+export interface SelectorImpl {
+  readonly kind: SelectorKind;
+  /**
+   * Uppercased tag names this selector is restricted to. Empty for wildcard
+   * element selectors and for text / comment selectors (dispatched by
+   * `kind`).
+   */
+  readonly tags: ReadonlySet<string>;
+  /** Composed predicate run against a candidate node. */
+  readonly predicate: Predicate;
+}
+
+const IMPL = Symbol.for('@lexical/html/SelectorImpl');
+
+/** @internal */
+export function getSelectorImpl(sel: CompiledSelector): SelectorImpl {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const impl = (sel as any)[IMPL] as SelectorImpl | undefined;
+  invariant(
+    impl !== undefined,
+    'match must be a CompiledSelector produced by sel.* or sel.css(); received a raw object.',
+  );
+  return impl;
+}
+
+function combinePredicates(preds: readonly Predicate[]): Predicate {
+  if (preds.length === 0) {
+    return isHTMLElement;
+  }
+  if (preds.length === 1) {
+    return preds[0];
+  }
+  return (node, captures) => {
+    for (const p of preds) {
+      if (!p(node, captures)) {
+        return false;
+      }
+    }
+    return true;
+  };
+}
+
+/**
+ * @internal
+ *
+ * Build a selector value from a tag set and a predicate list. Used by the
+ * combinator API and the CSS parser.
+ */
+export function buildSelector(
+  tags: ReadonlySet<string>,
+  predicates: readonly Predicate[],
+): ElementSelectorBuilder<HTMLElement> {
+  const impl: SelectorImpl = {
+    kind: 'element',
+    predicate: combinePredicates(predicates),
+    tags,
+  };
+  const refine = (additional: Predicate) =>
+    buildSelector(tags, [...predicates, additional]);
+  const builder = {
+    [IMPL]: impl,
+    attr: (name: string, value: unknown, options?: AttrMatchOptions) =>
+      refine(buildAttrPredicate(name, value, options)),
+    classAll: (...classes: readonly string[]) =>
+      refine(buildClassAllPredicate(classes)),
+    classAny: (...classes: readonly string[]) =>
+      refine(buildClassAnyPredicate(classes)),
+    styleAny: (prop: string, value: unknown, options?: StyleMatchOptions) =>
+      refine(buildStylePredicate(prop, value, options)),
+  };
+  // The runtime is fully type-erased; cast to satisfy the surface.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return builder as any;
+}
+
+function normalizeClassList(classes: readonly string[]): readonly string[] {
+  const out: string[] = [];
+  for (const c of classes) {
+    if (c) {
+      out.push(c);
+    }
+  }
+  return out;
+}
+
+/** @internal */
+export function buildClassAllPredicate(classes: readonly string[]): Predicate {
+  const ns = normalizeClassList(classes);
+  if (ns.length === 0) {
+    return () => true;
+  }
+  return node => {
+    if (!isHTMLElement(node)) {
+      return false;
+    }
+    const cl = node.classList;
+    for (const c of ns) {
+      if (!cl.contains(c)) {
+        return false;
+      }
+    }
+    return true;
+  };
+}
+
+/** @internal */
+export function buildClassAnyPredicate(classes: readonly string[]): Predicate {
+  const ns = normalizeClassList(classes);
+  if (ns.length === 0) {
+    return () => false;
+  }
+  return node => {
+    if (!isHTMLElement(node)) {
+      return false;
+    }
+    const cl = node.classList;
+    for (const c of ns) {
+      if (cl.contains(c)) {
+        return true;
+      }
+    }
+    return false;
+  };
+}
+
+/** @internal */
+export function buildAttrPredicate(
+  name: string,
+  value: unknown,
+  options?: AttrMatchOptions,
+): Predicate {
+  if (value === true) {
+    return node => isHTMLElement(node) && node.hasAttribute(name);
+  }
+  if (typeof value === 'string') {
+    return node => isHTMLElement(node) && node.getAttribute(name) === value;
+  }
+  if (value instanceof RegExp) {
+    const capture = options && options.capture;
+    const re = value;
+    return (node, captures) => {
+      if (!isHTMLElement(node)) {
+        return false;
+      }
+      const v = node.getAttribute(name);
+      if (v == null) {
+        return false;
+      }
+      const m = v.match(re);
+      if (m === null) {
+        return false;
+      }
+      if (capture !== undefined) {
+        captures[capture] = m;
+      }
+      return true;
+    };
+  }
+  invariant(
+    false,
+    'sel.attr(%s, ...) requires true, a string, or a RegExp',
+    JSON.stringify(name),
+  );
+}
+
+function buildStylePredicate(
+  prop: string,
+  value: unknown,
+  options?: StyleMatchOptions,
+): Predicate {
+  if (typeof value === 'string') {
+    return node =>
+      isHTMLElement(node) && node.style.getPropertyValue(prop) === value;
+  }
+  if (value instanceof RegExp) {
+    const capture = options && options.capture;
+    const re = value;
+    return (node, captures) => {
+      if (!isHTMLElement(node)) {
+        return false;
+      }
+      const v = node.style.getPropertyValue(prop);
+      if (!v) {
+        return false;
+      }
+      const m = v.match(re);
+      if (m === null) {
+        return false;
+      }
+      if (capture !== undefined) {
+        captures[capture] = m;
+      }
+      return true;
+    };
+  }
+  invariant(
+    false,
+    'sel.styleAny(%s, ...) requires a string or a RegExp',
+    JSON.stringify(prop),
+  );
+}
+
+const TEXT_SELECTOR_IMPL: SelectorImpl = {
+  kind: 'text',
+  predicate: isDOMTextNode,
+  tags: new Set(),
+};
+
+// The `as` cast is needed because `CompiledSelector` is an opaque
+// branded interface — neither the object literal nor a typed const can
+// declare the internal `IMPL` symbol without exposing it.
+const TEXT_SELECTOR = {[IMPL]: TEXT_SELECTOR_IMPL} as CompiledSelector<Text>;
+
+const COMMENT_SELECTOR_IMPL: SelectorImpl = {
+  kind: 'comment',
+  predicate: node => node.nodeType === 8 /* COMMENT_NODE */,
+  tags: new Set(),
+};
+
+const COMMENT_SELECTOR = {
+  [IMPL]: COMMENT_SELECTOR_IMPL,
+} as CompiledSelector<Comment>;
+
+/**
+ * Combinator API for building {@link CompiledSelector}s. The public
+ * `sel` is augmented from this in `./index.ts` (where the CSS parser is
+ * available without a circular import); consumers outside `@lexical/html`
+ * should always import the public `sel` from the package root.
+ *
+ * @internal
+ */
+export const selBase = {
+  /** Match any {@link HTMLElement}. */
+  any(): ElementSelectorBuilder<HTMLElement> {
+    return buildSelector(new Set(), []);
+  },
+
+  /** Match DOM {@link Comment} nodes. */
+  comment(): CompiledSelector<Comment> {
+    return COMMENT_SELECTOR;
+  },
+
+  /**
+   * Match by tag name(s). With one literal tag the element type is narrowed
+   * (e.g. `'a' → HTMLAnchorElement`); with multiple, it is the union of
+   * their `HTMLElementTagNameMap` entries.
+   */
+  tag<const Tags extends readonly string[]>(
+    ...tags: Tags
+  ): ElementSelectorBuilder<
+    Tags[number] extends keyof HTMLElementTagNameMap
+      ? HTMLElementTagNameMap[Tags[number]]
+      : HTMLElement
+  > {
+    invariant(tags.length > 0, 'sel.tag() requires at least one tag name');
+    const upper = new Set<string>();
+    for (const t of tags) {
+      upper.add(t.toUpperCase());
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return buildSelector(upper, []) as any;
+  },
+
+  /** Match DOM {@link Text} nodes. */
+  text(): CompiledSelector<Text> {
+    return TEXT_SELECTOR;
+  },
+} as const;
+
+/**
+ * Cross-frame-safe replacement for `node instanceof HTMLXxxElement`. Returns
+ * true when `node` is an HTMLElement whose `nodeName` equals `tag` (compared
+ * case-insensitively).
+ *
+ * @experimental
+ */
+export function isElementOfTag<T extends keyof HTMLElementTagNameMap>(
+  node: Node,
+  tag: T,
+): node is HTMLElementTagNameMap[T] {
+  return isHTMLElement(node) && node.nodeName === tag.toUpperCase();
+}