@lexical/html 0.44.1-nightly.20260518.0 → 0.45.0

package/src/import/defineOverlayRules.ts

@@ -0,0 +1,105 @@
+/**
+ * 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 {AnyDOMImportRule} from './types';
+
+import {type CompiledDispatch, compileImportRules} from './compileImportRules';
+
+/**
+ * Opaque handle for a pre-compiled set of overlay rules. Produce one with
+ * {@link defineOverlayRules} and pass it to
+ * {@link DOMImportContext.$importChildren} via
+ * {@link ImportChildrenOpts.rules}.
+ *
+ * To merge two or more overlays into a single one, pass them (alongside
+ * raw {@link DOMImportRule}s if desired) to a fresh
+ * {@link defineOverlayRules} — earlier arguments are higher priority.
+ *
+ * The internal shape is intentionally not part of the public API: it's a
+ * compiled dispatch table tagged with `__type` so callers cannot pass a
+ * raw rule array where a compiled overlay is expected.
+ *
+ * @experimental
+ */
+export interface CompiledOverlayRules {
+  readonly __type: 'CompiledOverlayRules';
+  /** @internal */
+  readonly dispatch: CompiledDispatch;
+  /**
+   * @internal — flattened source rules retained so an overlay can be
+   * recompiled when it is passed to another {@link defineOverlayRules}
+   * call or as part of {@link DOMImportConfig.rules}.
+   */
+  readonly rules: readonly AnyDOMImportRule[];
+}
+
+/**
+ * An entry accepted everywhere rules are configured (overlay
+ * definitions, {@link DOMImportConfig.rules}). Either a single
+ * {@link DOMImportRule} or a {@link CompiledOverlayRules} produced by
+ * a previous {@link defineOverlayRules} call — passing the latter
+ * inlines the overlay's rules at this position in priority order.
+ *
+ * @experimental
+ */
+export type DOMImportRuleEntry = AnyDOMImportRule | CompiledOverlayRules;
+
+/** @internal */
+export function flattenRuleEntries(
+  entries: readonly DOMImportRuleEntry[],
+): AnyDOMImportRule[] {
+  const out: AnyDOMImportRule[] = [];
+  for (const entry of entries) {
+    if (isCompiledOverlayRules(entry)) {
+      for (const r of entry.rules) {
+        out.push(r);
+      }
+    } else {
+      out.push(entry);
+    }
+  }
+  return out;
+}
+
+function isCompiledOverlayRules(
+  entry: DOMImportRuleEntry,
+): entry is CompiledOverlayRules {
+  return (
+    typeof entry === 'object' &&
+    entry !== null &&
+    '__type' in entry &&
+    entry.__type === 'CompiledOverlayRules'
+  );
+}
+
+/**
+ * Pre-compile a set of {@link DOMImportRuleEntry}s into a
+ * {@link CompiledOverlayRules} handle that can be installed via
+ * `ctx.$importChildren(el, {rules: …})`.
+ *
+ * Entries can be raw {@link DOMImportRule}s or other
+ * {@link CompiledOverlayRules} (the latter are inlined at their
+ * position in priority order, so the same call composes any number of
+ * overlays). Earlier entries are higher priority.
+ *
+ * Overlay rules installed as a raw array would be re-compiled on every
+ * `$importChildren` call. For overlays that are reused (e.g. a GitHub
+ * code-table rule that wraps every matching table), call this once at
+ * module scope so the dispatch table is built up front.
+ *
+ * @experimental
+ */
+export function defineOverlayRules(
+  entries: readonly DOMImportRuleEntry[],
+): CompiledOverlayRules {
+  const rules = flattenRuleEntries(entries);
+  return {
+    __type: 'CompiledOverlayRules',
+    dispatch: compileImportRules(rules),
+    rules,
+  };
+}

package/src/import/index.ts

@@ -0,0 +1,96 @@
+/**
+ * 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,
+  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]);
+}