@lexical/html 0.44.1-nightly.20260518.0 → 0.45.0

package/dist/import/ImportContext.d.ts

@@ -0,0 +1,208 @@
+/**
+ * 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 { ImportContextPairOrUpdater, ImportSession, ImportStateConfig } from './types';
+import { type LexicalEditor } from 'lexical';
+import { DOMImportContextSymbol } from '../constants';
+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 declare function createImportState<V>(name: string, getDefaultValue: () => V, isEqual?: (a: V, b: V) => boolean): ImportStateConfig<V>;
+/**
+ * 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 declare const ImportSource: ImportStateConfig<ImportSourceKind>;
+/**
+ * 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 declare const ImportSourceDataTransfer: ImportStateConfig<DataTransfer | 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 declare const ImportTextFormat: ImportStateConfig<number>;
+/**
+ * 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 declare const ImportTextStyle: ImportStateConfig<Readonly<Record<string, string>>>;
+/**
+ * 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 declare function defaultPreservesWhitespace(node: Node): boolean;
+/**
+ * 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 declare function defaultIsInline(node: Node): boolean;
+/**
+ * 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 declare const ImportWhitespaceConfig: ImportStateConfig<WhitespaceImportConfig>;
+/**
+ * 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 declare const ImportOverlays: ImportStateConfig<readonly CompiledOverlayRules[]>;
+/**
+ * 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 declare class ImportSessionImpl implements ImportSession {
+    readonly record: ImportContextRecord;
+    constructor(record: ImportContextRecord);
+    get<V>(cfg: ImportStateConfig<V>): V;
+    set<V>(cfg: ImportStateConfig<V>, value: V): void;
+    update<V>(cfg: ImportStateConfig<V>, updater: (prev: V) => V): void;
+    has<V>(cfg: ImportStateConfig<V>): boolean;
+}
+/**
+ * Read an import context value during an import operation.
+ * @experimental
+ */
+export declare function $getImportContextValue<V>(cfg: ImportStateConfig<V>, editor?: LexicalEditor): V;
+/**
+ * Run `f` with the given context pairs applied on top of the editor's
+ * current import context.
+ *
+ * @experimental
+ */
+export declare const $withImportContext: (cfg: readonly ImportContextPairOrUpdater[], editor?: LexicalEditor) => <T>(f: () => T) => T;
+export {};

package/dist/import/compileImportRules.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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, DOMImportFn } from './types';
+import { type Predicate } from './sel';
+/** @internal */
+export interface CompiledRule {
+    readonly name: string;
+    readonly predicate: Predicate;
+    readonly $import: DOMImportFn<Node, Record<string, RegExpMatchArray>>;
+}
+/** @internal */
+export interface CompiledDispatch {
+    /** All rules in registration order. Index = registration order. */
+    readonly rules: readonly CompiledRule[];
+    /**
+     * For each (uppercased) HTML tag name, the ordered list of rule indices
+     * considered when dispatching that tag. Includes interleaved wildcard
+     * element rules so a single iteration handles both.
+     */
+    readonly byTag: ReadonlyMap<string, readonly number[]>;
+    /** Indices of rules whose match has no tag restriction. */
+    readonly wildcardIndices: readonly number[];
+    /** Indices of rules whose match is `sel.text()`. */
+    readonly textIndices: readonly number[];
+    /** Indices of rules whose match is `sel.comment()`. */
+    readonly commentIndices: readonly number[];
+}
+/**
+ * Compile an ordered list of {@link DOMImportRule}s into the dispatch tables
+ * used by the import runtime. The rule at index 0 is the highest-priority
+ * (`mergeConfig` prepends partial.rules so later-merged extensions land
+ * first).
+ *
+ * @internal
+ */
+export declare function compileImportRules(rules: readonly AnyDOMImportRule[]): CompiledDispatch;
+/**
+ * Look up the (already interleaved) rule indices relevant to `node`. Element
+ * nodes hit `byTag` (with wildcards merged in) or fall back to the wildcard
+ * bucket if no tag-specific rules exist; text and comment nodes use their
+ * own buckets.
+ *
+ * @internal
+ */
+export declare function getDispatchIndices(dispatch: CompiledDispatch, node: Node): readonly number[];

package/dist/import/coreImportRules.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 ElementFormatType } from 'lexical';
+/**
+ * True if `value` is a non-empty {@link ElementFormatType} (matches one of
+ * the supported `text-align` / legacy `align`-attribute values).
+ *
+ * @internal
+ */
+export declare function isAlignmentValue(value: string): value is ElementFormatType;
+/**
+ * Rules covering the {@link ParagraphNode}, {@link TextNode},
+ * {@link LineBreakNode}, and {@link TabNode} cases that the legacy
+ * `importDOM` machinery in `@lexical/lexical` handled. Intended to be
+ * registered as a dependency of every editor that uses
+ * {@link DOMImportExtension}.
+ *
+ * @experimental
+ */
+export declare const CoreImportRules: (import("./types").DOMImportRule<import("./types").ElementSelectorBuilder<HTMLElement | HTMLSpanElement, Record<string, never>>> | import("./types").DOMImportRule<import("./types").CompiledSelector<Text, Record<string, RegExpMatchArray>>>)[];

package/dist/import/defineImportRule.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 { CompiledSelector, DOMImportFn, DOMImportRule } from './types';
+/**
+ * Identity helper that infers a rule's matched node type and capture map
+ * from its `match` selector and threads them into the `$import` signature.
+ * Usage:
+ *
+ * ```ts
+ * defineImportRule({
+ *   name: '@lexical/list/li',
+ *   match: sel.tag('li'),
+ *   $import: (ctx, el, $next) => {
+ *     // el: HTMLLIElement
+ *     return [$createListItemNode()];
+ *   },
+ * });
+ * ```
+ *
+ * @experimental
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function defineImportRule<const S extends CompiledSelector>(rule: {
+    readonly name?: string;
+    readonly match: S;
+    readonly $import: DOMImportFn<S extends CompiledSelector<infer N, Record<string, RegExpMatchArray>> ? N : Node, S extends CompiledSelector<Node, infer C> ? C : Record<string, never>>;
+}): DOMImportRule<S>;

package/dist/import/defineOverlayRules.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 } 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 declare function flattenRuleEntries(entries: readonly DOMImportRuleEntry[]): AnyDOMImportRule[];
+/**
+ * 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 declare function defineOverlayRules(entries: readonly DOMImportRuleEntry[]): CompiledOverlayRules;

package/dist/import/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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';
+/**
+ * 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 declare const sel: {
+    readonly any: () => import("./types").ElementSelectorBuilder<HTMLElement>;
+    readonly comment: () => import("./types").CompiledSelector<Comment>;
+    /**
+     * Parse a reduced CSS-selector subset and return a builder you can chain
+     * combinator methods off of.
+     */
+    readonly css: typeof parseSelector;
+    readonly tag: <const Tags extends readonly string[]>(...tags: Tags) => import("./types").ElementSelectorBuilder<Tags[number] extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[Tags[number]] : HTMLElement>;
+    readonly text: () => import("./types").CompiledSelector<Text>;
+};
+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/dist/import/inlineStylesFromStyleSheets.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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';
+/**
+ * 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 declare const $inlineStylesFromStyleSheets: DOMPreprocessFn;
+export declare function $inlineStylesFromStyleSheetsDOM(dom: Document | ParentNode): void;

package/dist/import/parseCss.d.ts

@@ -0,0 +1,18 @@
+import type { ElementSelectorBuilder } from './types';
+/**
+ * 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 declare function parseSelector(source: string): ElementSelectorBuilder<HTMLElement>;

package/dist/import/runImport.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 { ImportSession } from './types';
+import { type LexicalEditor, type LexicalNode } from 'lexical';
+import { type CompiledDispatch } from './compileImportRules';
+/**
+ * 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 declare function $runImport(dispatch: CompiledDispatch, editor: LexicalEditor, dom: Document | ParentNode, session: ImportSession): LexicalNode[];

package/dist/import/schemas.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 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 { type ElementNode, type LexicalNode } from 'lexical';
+/**
+ * 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 declare function $isBlockLevel(node: LexicalNode): boolean;
+/**
+ * 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 declare function $distributeInlineWrapper(children: readonly LexicalNode[], $makeWrapper: () => ElementNode): LexicalNode[];
+/**
+ * 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 declare function $applySchema(schema: ChildSchema, children: LexicalNode[], parent: LexicalNode | null, domParent: Node | null): LexicalNode[];
+/**
+ * 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 declare const BlockSchema: ChildSchema;
+/**
+ * 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 declare const InlineSchema: ChildSchema;
+/**
+ * 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 declare const NestedBlockSchema: ChildSchema;
+/**
+ * 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 declare const RootSchema: ChildSchema;

package/dist/import/sel.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 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 } from './types';
+/**
+ * @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;
+}
+/** @internal */
+export declare function getSelectorImpl(sel: CompiledSelector): SelectorImpl;
+/**
+ * @internal
+ *
+ * Build a selector value from a tag set and a predicate list. Used by the
+ * combinator API and the CSS parser.
+ */
+export declare function buildSelector(tags: ReadonlySet<string>, predicates: readonly Predicate[]): ElementSelectorBuilder<HTMLElement>;
+/** @internal */
+export declare function buildClassAllPredicate(classes: readonly string[]): Predicate;
+/** @internal */
+export declare function buildClassAnyPredicate(classes: readonly string[]): Predicate;
+/** @internal */
+export declare function buildAttrPredicate(name: string, value: unknown, options?: AttrMatchOptions): Predicate;
+/**
+ * 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 declare const selBase: {
+    /** Match any {@link HTMLElement}. */
+    readonly any: () => ElementSelectorBuilder<HTMLElement>;
+    /** Match DOM {@link Comment} nodes. */
+    readonly comment: () => CompiledSelector<Comment>;
+    /**
+     * 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.
+     */
+    readonly tag: <const Tags extends readonly string[]>(...tags: Tags) => ElementSelectorBuilder<Tags[number] extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[Tags[number]] : HTMLElement>;
+    /** Match DOM {@link Text} nodes. */
+    readonly text: () => CompiledSelector<Text>;
+};
+/**
+ * Cross-frame-safe replacement for `node instanceof HTMLXxxElement`. Returns
+ * true when `node` is an HTMLElement whose `nodeName` equals `tag` (compared
+ * case-insensitively).
+ *
+ * @experimental
+ */
+export declare function isElementOfTag<T extends keyof HTMLElementTagNameMap>(node: Node, tag: T): node is HTMLElementTagNameMap[T];