@blue-patterns/richtext 0.0.0-stage → 0.7.18

package/dist/markdownCodeFence.d.ts

@@ -0,0 +1,4 @@
+import { type MultilineElementTransformer } from '@lexical/markdown';
+export declare const BACKTICK_CODE: MultilineElementTransformer;
+export declare const TILDE_CODE: MultilineElementTransformer;
+//# sourceMappingURL=markdownCodeFence.d.ts.map

package/dist/markdownCodeFence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdownCodeFence.d.ts","sourceRoot":"","sources":["../src/markdownCodeFence.ts"],"names":[],"mappings":"AAyBA,OAAO,EAGL,KAAK,2BAA2B,EACjC,MAAM,mBAAmB,CAAC;AAuJ3B,eAAO,MAAM,aAAa,EAAE,2BAqB3B,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,2BAYxB,CAAC"}

package/dist/markdownCodeFence.js

@@ -0,0 +1,167 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file markdownCodeFence.ts
+ * @input Uses @lexical/markdown (CODE) and @lexical/code.
+ * @output Exports BACKTICK_CODE and TILDE_CODE, the transformers for fenced
+ *   code blocks opened with backticks and with tildes.
+ * @position Part of DEFAULT_TRANSFORMERS (markdownTable.ts): BACKTICK_CODE
+ *   stands in for Lexical's CODE, and TILDE_CODE reads the `~~~` fences CODE
+ *   does not (CommonMark 0.31 §4.5, spec:AST-061 FR5). Both read the opening
+ *   line as core Markdown does: the rest of the line after the fence is the
+ *   info string, never code; the language is its first word, after any
+ *   spaces (so `~~~ c++` reads `c++`), as core and CommonMark read it. A
+ *   block closes at
+ *   a fence of its own character at least as long, or at the end of the
+ *   document, and its code is exactly the lines between, blank lines
+ *   included, each less as much indentation as the opening fence has (up to
+ *   three spaces), as core reads it. Each keeps its fence and info
+ *   string (spec:AST-062): an edited block exports them as written, with its
+ *   language first when that was changed, and its fence lengthened when its
+ *   code holds a run of the fence's character that long.
+ *   A one-line backtick block (```` ```code``` ````) stays Lexical's.
+ */
+
+import { $createCodeNode, $isCodeNode } from '@lexical/code';
+import { CODE } from '@lexical/markdown';
+import { $createTextNode, $getState, $setState, createState } from 'lexical';
+
+/**
+ * The tilde fence a code block was opened with; null for a backtick block.
+ * Lexical's own fence state holds only backtick fences.
+ */
+const tildeFence = createState('astryxTildeFence', {
+  parse: value => typeof value === 'string' && /^~{3,}$/.test(value) ? value : null
+});
+
+/**
+ * The backtick fence a code block was opened with, when longer than three:
+ * Lexical's own fence state is set only by its transformer, which this file
+ * does not use to build blocks.
+ */
+const backtickFence = createState('astryxBacktickFence', {
+  parse: value => typeof value === 'string' && /^`{4,}$/.test(value) ? value : null
+});
+
+/** The info string a code block's opening fence carried, as written. */
+const fenceInfo = createState('astryxFenceInfo', {
+  parse: value => typeof value === 'string' && value !== '' ? value : null
+});
+
+/** The language core Markdown reads from an info string, or null. */
+function languageOf(info) {
+  return /^\S+/.exec(info.trimStart())?.[0] ?? null;
+}
+
+/** An opening fence line: its indentation, its fence, and the info string. */
+
+/**
+ * Reads an opening fence line: up to three spaces of indentation, then the
+ * fence (CommonMark 0.31 §4.5), as core Markdown reads it.
+ */
+function readOpening(line) {
+  const match = /^( {0,3})(`{3,}|~{3,})(.*)$/.exec(line);
+  if (match == null) {
+    return null;
+  }
+  const [, indentation, fence, info] = match;
+  // A backtick fence's info string holds no backtick.
+  return fence.startsWith('`') && info.includes('`') ? null : {
+    indentation: indentation.length,
+    fence,
+    info
+  };
+}
+
+/** The longest run of three or more of `character` in `text`, or 0. */
+function longestFenceRun(text, character) {
+  return Math.max(0, ...(text.match(character === '`' ? /`{3,}/g : /~{3,}/g) ?? []).map(run => run.length));
+}
+
+/**
+ * Builds the code block an opening line starts, from the lines after it up
+ * to its closing fence, and returns the index of the last line it used.
+ */
+function $importFencedCode(rootNode, lines, startLineIndex, opening) {
+  const {
+    indentation,
+    fence,
+    info
+  } = opening;
+  const closing = new RegExp(`^ {0,3}${fence[0] === '`' ? '`' : '~'}{${fence.length},}[ \\t]*$`);
+  // Each code line loses as much indentation as the opening fence has.
+  const fenceIndentation = new RegExp(`^ {0,${indentation}}`);
+  let end = startLineIndex + 1;
+  while (end < lines.length && !closing.test(lines[end])) {
+    end++;
+  }
+  // A fence left open runs to the end of the document, whose final line
+  // ending starts no line of code (CommonMark 0.31 §4.5), as core reads it.
+  const codeEnd = end === lines.length && end > startLineIndex + 1 && lines[end - 1] === '' ? end - 1 : end;
+  // The code is the lines between the fences, exactly: Lexical's own
+  // transformer trims a space from the first line and drops blank first and
+  // last lines, adjustments meant for its own reading of the opening line.
+  const block = $createCodeNode(languageOf(info) ?? undefined);
+  block.append($createTextNode(lines.slice(startLineIndex + 1, codeEnd).map(line => line.replace(fenceIndentation, '')).join('\n')));
+  rootNode.append(block);
+  if (fence.startsWith('~')) {
+    $setState(block, tildeFence, fence);
+  } else if (fence.length > 3) {
+    $setState(block, backtickFence, fence);
+  }
+  $setState(block, fenceInfo, info.trimEnd());
+  return Math.min(end, lines.length - 1);
+}
+
+/** Writes a code block that keeps its fence or info string; null otherwise. */
+const exportFencedCode = node => {
+  if (!$isCodeNode(node)) {
+    return null;
+  }
+  const tilde = $getState(node, tildeFence);
+  const backticks = $getState(node, backtickFence);
+  const info = $getState(node, fenceInfo);
+  if (tilde == null && backticks == null && info == null) {
+    return null;
+  }
+  const text = node.getTextContent();
+  const language = node.getLanguage() ?? '';
+  let written = info ?? '';
+  if ((languageOf(written) ?? '') !== language) {
+    // The language changed: it leads, before the rest of the info string.
+    const previous = languageOf(written);
+    const rest = previous == null ? '' : written.trimStart().slice(previous.length).trim();
+    written = rest === '' ? language : `${language} ${rest}`;
+  }
+  // A fence outlasts any run of its character in the code.
+  const fence = tilde != null ? '~'.repeat(Math.max(tilde.length, longestFenceRun(text, '~') + 1)) : '`'.repeat(Math.max((backticks ?? '```').length, longestFenceRun(text, '`') + 1));
+  return `${fence}${written}${text === '' ? '' : `\n${text}`}\n${fence}`;
+};
+export const BACKTICK_CODE = {
+  ...CODE,
+  handleImportAfterStartMatch: args => {
+    const opening = readOpening(args.lines[args.startLineIndex]);
+    if (opening == null) {
+      return CODE.handleImportAfterStartMatch?.(args) ?? null;
+    }
+    return [true, $importFencedCode(args.rootNode, args.lines, args.startLineIndex, opening)];
+  },
+  export: (node, exportChildren) => exportFencedCode(node, exportChildren) ?? CODE.export?.(node, exportChildren) ?? null
+};
+export const TILDE_CODE = {
+  ...CODE,
+  regExpStart: /^( {0,3}~{3,})(.*)$/,
+  regExpEnd: {
+    optional: true,
+    regExp: /^ {0,3}~{3,}[ \t]*$/
+  },
+  handleImportAfterStartMatch: ({
+    lines,
+    rootNode,
+    startLineIndex
+  }) => {
+    const opening = readOpening(lines[startLineIndex]);
+    return opening == null ? null : [true, $importFencedCode(rootNode, lines, startLineIndex, opening)];
+  },
+  export: (node, exportChildren) => exportFencedCode(node, exportChildren) ?? null
+};

package/dist/markdownExtensionNode.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @file markdownExtensionNode.ts
+ * @input Uses lexical (DecoratorNode, node serialization, text formats).
+ * @output Exports RichTextExtensionNode, the editor node for one Markdown
+ *   plugin node, with $createRichTextExtensionNode and
+ *   $isRichTextExtensionNode.
+ * @position Registered with every RichText surface and serializer
+ *   (editorNodes.ts), so stored state holding plugin nodes always loads. A
+ *   node is atomic — the editor cannot type into it — and keeps the exact
+ *   source it was read from, which is what it exports (spec:AST-064 FR7,
+ *   FR10). Stored state keeps that source, the plugin's name and protocol
+ *   version, the data the plugin derived for rendering (FR11), and the text
+ *   formats the node sits inside, so a node inside emphasis, strong, or
+ *   strikethrough stays inside it. Imports no React: the client surfaces
+ *   register how an editor draws plugin nodes.
+ */
+import { DecoratorNode, type DOMConversionMap, type DOMExportOutput, type EditorConfig, type LexicalEditor, type LexicalNode, type NodeKey, type NodeSelection, type RangeSelection, type TextNode, type SerializedLexicalNode, type Spread, type TextFormatType } from 'lexical';
+import type { MarkdownPluginData } from '@blue-patterns/core/Markdown/plugins';
+/** What one plugin node is: the parsed node's identity, data, and source. */
+export interface RichTextExtensionNodeFacts {
+    readonly plugin: string;
+    readonly apiVersion: number;
+    readonly name: string;
+    readonly display: 'inline' | 'block';
+    readonly data: MarkdownPluginData;
+    readonly source: string;
+}
+export type SerializedRichTextExtensionNode = Spread<RichTextExtensionNodeFacts & {
+    /** The text formats the node sits inside, as a text node's format bits. */
+    readonly format: number;
+}, SerializedLexicalNode>;
+/** Reads stored facts defensively: a missing field becomes an empty value. */
+export declare function factsFrom(value: Record<string, unknown>): RichTextExtensionNodeFacts;
+/**
+ * Draws a plugin node's content in one editor, inside the text formats the
+ * node sits in; `nodeKey` lets it select the node. The client surfaces
+ * register one (MarkdownExtensionsPlugin); without one, a node shows its
+ * source.
+ */
+export type RichTextExtensionNodeDecorator = (facts: RichTextExtensionNodeFacts, format: number, nodeKey: NodeKey) => unknown;
+/** Sets how `editor` draws plugin nodes; returns a function that unsets it. */
+export declare function setRichTextExtensionNodeDecorator(editor: LexicalEditor, decorator: RichTextExtensionNodeDecorator): () => void;
+export declare class RichTextExtensionNode extends DecoratorNode<unknown> {
+    __facts: RichTextExtensionNodeFacts;
+    /**
+     * The text formats the node sits inside, as a text node's format bits. Only
+     * inline nodes carry any.
+     */
+    __format: number;
+    static getType(): string;
+    static clone(node: RichTextExtensionNode): RichTextExtensionNode;
+    static importJSON(serialized: SerializedLexicalNode & Record<string, unknown>): RichTextExtensionNode;
+    static importDOM(): DOMConversionMap;
+    constructor(facts?: RichTextExtensionNodeFacts, format?: number, key?: NodeKey);
+    exportJSON(): SerializedRichTextExtensionNode;
+    /** The node's identity, data, and source. */
+    getFacts(): RichTextExtensionNodeFacts;
+    /** The exact Markdown the node was read from. */
+    getSource(): string;
+    /** The text formats the node sits inside, as a text node's format bits. */
+    getFormat(): number;
+    hasFormat(type: TextFormatType): boolean;
+    /** Puts the node inside, or takes it out of, one text format. */
+    setFormatFlag(type: TextFormatType, isOn: boolean): this;
+    createDOM(config: EditorConfig): HTMLElement;
+    exportDOM(): DOMExportOutput;
+    updateDOM(prevNode: RichTextExtensionNode, dom: HTMLElement): false;
+    isInline(): boolean;
+    /** The node's text is its source, so plain-text copies and search see it. */
+    getTextContent(): string;
+    decorate(editor: LexicalEditor): unknown;
+}
+export declare function $createRichTextExtensionNode(facts: RichTextExtensionNodeFacts, format?: number): RichTextExtensionNode;
+export declare function $isRichTextExtensionNode(node: LexicalNode | null | undefined): node is RichTextExtensionNode;
+/**
+ * The first text node a range selects characters of, as Lexical's formatText
+ * reads it: a range that starts at the end of a text node starts in the next.
+ * Null when the range selects no text, only nodes.
+ */
+export declare function $firstSelectedText(selection: RangeSelection): TextNode | null;
+/**
+ * The inline plugin nodes a selection holds when it holds nothing else: a
+ * range that selects no text, only nodes, or a node selection of plugin
+ * nodes alone. Null otherwise. A format shown or toggled then belongs to
+ * them.
+ */
+export declare function $selectedExtensionNodesOnly(selection: RangeSelection | NodeSelection): RichTextExtensionNode[] | null;
+//# sourceMappingURL=markdownExtensionNode.d.ts.map

package/dist/markdownExtensionNode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdownExtensionNode.d.ts","sourceRoot":"","sources":["../src/markdownExtensionNode.ts"],"names":[],"mappings":"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"}

package/dist/markdownExtensionNode.js

@@ -0,0 +1,248 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file markdownExtensionNode.ts
+ * @input Uses lexical (DecoratorNode, node serialization, text formats).
+ * @output Exports RichTextExtensionNode, the editor node for one Markdown
+ *   plugin node, with $createRichTextExtensionNode and
+ *   $isRichTextExtensionNode.
+ * @position Registered with every RichText surface and serializer
+ *   (editorNodes.ts), so stored state holding plugin nodes always loads. A
+ *   node is atomic — the editor cannot type into it — and keeps the exact
+ *   source it was read from, which is what it exports (spec:AST-064 FR7,
+ *   FR10). Stored state keeps that source, the plugin's name and protocol
+ *   version, the data the plugin derived for rendering (FR11), and the text
+ *   formats the node sits inside, so a node inside emphasis, strong, or
+ *   strikethrough stays inside it. Imports no React: the client surfaces
+ *   register how an editor draws plugin nodes.
+ */
+
+import { $isNodeSelection, $isTextNode, DecoratorNode, TEXT_TYPE_TO_FORMAT } from 'lexical';
+
+/** What one plugin node is: the parsed node's identity, data, and source. */
+
+/** Reads stored facts defensively: a missing field becomes an empty value. */
+export function factsFrom(value) {
+  const {
+    plugin,
+    apiVersion,
+    name,
+    display,
+    data,
+    source
+  } = value;
+  return {
+    plugin: typeof plugin === 'string' ? plugin : '',
+    apiVersion: typeof apiVersion === 'number' ? apiVersion : 0,
+    name: typeof name === 'string' ? name : '',
+    display: display === 'block' ? 'block' : 'inline',
+    data: data ?? null,
+    source: typeof source === 'string' ? source : ''
+  };
+}
+
+/**
+ * Draws a plugin node's content in one editor, inside the text formats the
+ * node sits in; `nodeKey` lets it select the node. The client surfaces
+ * register one (MarkdownExtensionsPlugin); without one, a node shows its
+ * source.
+ */
+
+const decorators = new WeakMap();
+
+/** Sets how `editor` draws plugin nodes; returns a function that unsets it. */
+export function setRichTextExtensionNodeDecorator(editor, decorator) {
+  decorators.set(editor, decorator);
+  return () => {
+    if (decorators.get(editor) === decorator) {
+      decorators.delete(editor);
+    }
+  };
+}
+
+/**
+ * The attribute that carries a node's facts and formats in its element, so
+ * copying it as HTML — the browser's own copy, or the editor's HTML export —
+ * and pasting it into any RichText editor brings back the same node with the
+ * same source and marks.
+ */
+const FACTS_ATTRIBUTE = 'data-markdown-extension';
+function factsAttribute(node) {
+  return JSON.stringify({
+    ...node.__facts,
+    format: node.__format
+  });
+}
+function convertExtensionElement(element) {
+  let node = null;
+  try {
+    const parsed = JSON.parse(element.getAttribute(FACTS_ATTRIBUTE) ?? '');
+    if (parsed != null && typeof parsed === 'object') {
+      const value = parsed;
+      node = $createRichTextExtensionNode(factsFrom(value), typeof value.format === 'number' ? value.format : 0);
+    }
+  } catch {
+    node = null;
+  }
+  return {
+    node,
+    // The element's content is the node's rendering, not more document.
+    forChild: () => null
+  };
+}
+const importExtensionElement = element => element.hasAttribute(FACTS_ATTRIBUTE) ? {
+  conversion: convertExtensionElement,
+  priority: 4
+} : null;
+export class RichTextExtensionNode extends DecoratorNode {
+  /**
+   * The text formats the node sits inside, as a text node's format bits. Only
+   * inline nodes carry any.
+   */
+
+  static getType() {
+    return 'astryx-markdown-extension';
+  }
+  static clone(node) {
+    return new RichTextExtensionNode(node.__facts, node.__format, node.__key);
+  }
+  static importJSON(serialized) {
+    // Stored state is read defensively, so a damaged node still loads.
+    const {
+      format
+    } = serialized;
+    return $createRichTextExtensionNode(factsFrom(serialized), typeof format === 'number' ? format : 0).updateFromJSON(serialized);
+  }
+  static importDOM() {
+    return {
+      span: importExtensionElement,
+      div: importExtensionElement
+    };
+  }
+
+  // The Yjs binding and `$create` call the constructor with no arguments.
+  // The binding reads each class's default properties from that node.
+  // With no facts, the node gets the values that damaged stored facts get.
+  constructor(facts = factsFrom({}), format = 0, key) {
+    super(key);
+    this.__facts = facts;
+    this.__format = facts.display === 'inline' ? format : 0;
+  }
+  exportJSON() {
+    const latest = this.getLatest();
+    return {
+      ...super.exportJSON(),
+      ...latest.__facts,
+      format: latest.__format
+    };
+  }
+
+  /** The node's identity, data, and source. */
+  getFacts() {
+    return this.getLatest().__facts;
+  }
+
+  /** The exact Markdown the node was read from. */
+  getSource() {
+    return this.getLatest().__facts.source;
+  }
+
+  /** The text formats the node sits inside, as a text node's format bits. */
+  getFormat() {
+    return this.getLatest().__format;
+  }
+  hasFormat(type) {
+    return (this.getFormat() & TEXT_TYPE_TO_FORMAT[type]) !== 0;
+  }
+
+  /** Puts the node inside, or takes it out of, one text format. */
+  setFormatFlag(type, isOn) {
+    const writable = this.getWritable();
+    const flag = TEXT_TYPE_TO_FORMAT[type];
+    writable.__format = isOn ? writable.__format | flag : writable.__format & ~flag;
+    return writable;
+  }
+  createDOM(config) {
+    const element = document.createElement(this.__facts.display === 'inline' ? 'span' : 'div');
+    element.setAttribute(FACTS_ATTRIBUTE, factsAttribute(this));
+    if (this.__facts.display === 'block') {
+      // A block node is spaced and measured as Markdown spaces its block.
+      const className = config.theme.markdownExtensionBlock;
+      if (typeof className === 'string' && className !== '') {
+        element.className = className;
+      }
+    }
+    return element;
+  }
+  exportDOM() {
+    const element = document.createElement(this.__facts.display === 'inline' ? 'span' : 'div');
+    element.setAttribute(FACTS_ATTRIBUTE, factsAttribute(this));
+    element.textContent = this.__facts.source;
+    return {
+      element
+    };
+  }
+  updateDOM(prevNode, dom) {
+    // A mark toggled on the node changes what its element carries.
+    if (prevNode.__format !== this.__format) {
+      dom.setAttribute(FACTS_ATTRIBUTE, factsAttribute(this));
+    }
+    return false;
+  }
+  isInline() {
+    return this.__facts.display === 'inline';
+  }
+
+  /** The node's text is its source, so plain-text copies and search see it. */
+  getTextContent() {
+    return this.getLatest().__facts.source;
+  }
+  decorate(editor) {
+    return decorators.get(editor)?.(this.__facts, this.__format, this.__key) ?? this.__facts.source;
+  }
+}
+export function $createRichTextExtensionNode(facts, format = 0) {
+  return new RichTextExtensionNode(facts, format);
+}
+export function $isRichTextExtensionNode(node) {
+  return node instanceof RichTextExtensionNode;
+}
+
+/**
+ * The first text node a range selects characters of, as Lexical's formatText
+ * reads it: a range that starts at the end of a text node starts in the next.
+ * Null when the range selects no text, only nodes.
+ */
+export function $firstSelectedText(selection) {
+  const texts = selection.getNodes().filter($isTextNode);
+  const isBackward = selection.isBackward();
+  const start = isBackward ? selection.focus : selection.anchor;
+  const end = isBackward ? selection.anchor : selection.focus;
+  let first = texts[0];
+  let startOffset = start.type === 'element' ? 0 : start.offset;
+  if (first != null && start.type === 'text' && startOffset === first.getTextContentSize()) {
+    first = texts[1];
+    startOffset = 0;
+  }
+  const last = texts[texts.length - 1];
+  if (first == null || last == null) {
+    return null;
+  }
+  const endOffset = end.type === 'text' ? end.offset : last.getTextContentSize();
+  return first.is(last) && startOffset === endOffset ? null : first;
+}
+
+/**
+ * The inline plugin nodes a selection holds when it holds nothing else: a
+ * range that selects no text, only nodes, or a node selection of plugin
+ * nodes alone. Null otherwise. A format shown or toggled then belongs to
+ * them.
+ */
+export function $selectedExtensionNodesOnly(selection) {
+  if ($isNodeSelection(selection)) {
+    const selected = selection.getNodes();
+    return selected.length > 0 && selected.every(node => $isRichTextExtensionNode(node) && node.isInline()) ? selected : null;
+  }
+  const nodes = selection.getNodes().filter(node => $isRichTextExtensionNode(node) && node.isInline());
+  return nodes.length > 0 && $firstSelectedText(selection) == null ? nodes : null;
+}

package/dist/markdownExtensions.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @file markdownExtensions.ts
+ * @input Uses core's server-safe plugin protocol (getMarkdownPluginCapabilities)
+ *   and parser (parseMarkdownAst), lexical, and RichTextExtensionNode.
+ * @output Exports createRichTextExtension, RichTextExtensionError, and the
+ *   RichTextMarkdownExtension type; and, for RichText's own Markdown import and
+ *   export, the configuration check, the source shielding and restoring that
+ *   puts core-recognized plugin nodes into the editor, and the transformers
+ *   that export them.
+ * @position Implements spec:AST-064 FR1–FR6 and FR10 for RichText's Markdown
+ *   import and export. Server-safe: imports no React, DOM, or client module.
+ *
+ * A plugin is the entry core's createMarkdownPlugin returns; RichText adopts it
+ * as it is (FR1), refusing a plugin that declares a transform (FR4, DEC-3).
+ * Before Lexical imports a chunk of Markdown, core's parser finds the adopted
+ * plugins' nodes in it, and each node's exact source becomes a private-use
+ * stand-in that Lexical's transformers read as plain text (FR5, DEC-4). Core
+ * reports where a top-level block node sits but not an inline one, so each
+ * node is placed at the occurrence of its source that core itself recognizes:
+ * replacing that occurrence, and only that one, removes exactly that node from
+ * core's parse. After the import, each stand-in becomes an atomic
+ * RichTextExtensionNode holding the node's source and data.
+ */
+import type { Transformer } from '@lexical/markdown';
+import { TextNode, type ElementNode } from 'lexical';
+import { type MarkdownExtensionNode, type MarkdownPluginEntry } from '@blue-patterns/core/Markdown/plugins';
+import { RichTextExtensionNode } from './markdownExtensionNode.js';
+declare const extensionPlugin: unique symbol;
+/**
+ * One Markdown plugin adopted by RichText. Opaque: create it with
+ * `createRichTextExtension`, and pass it to the surfaces and serializers that
+ * should recognize the plugin's syntax.
+ */
+export interface RichTextMarkdownExtension {
+    /** The adopted plugin's name. */
+    readonly name: string;
+    readonly [extensionPlugin]: MarkdownPluginEntry;
+}
+/** Why RichText refused a plugin or a configuration (spec:AST-064 FR4, FR6). */
+export declare class RichTextExtensionError extends Error {
+    /** The plugin RichText refused, or that a configuration claims twice. */
+    readonly plugin: string;
+    /** What RichText cannot honor: `transform`, or what was claimed twice. */
+    readonly capability: string;
+    /** The transformer or second extension that claims the same thing. */
+    readonly claimant: string | null;
+    constructor(plugin: string, capability: string, claimant: string | null);
+}
+/**
+ * Adopts a Markdown plugin for RichText (spec:AST-064 FR1, FR4). RichText
+ * recognizes the plugin's syntax with core's parser and keeps each node's
+ * source; it never runs the plugin's immutable transform, so a plugin that
+ * declares one is refused with a `RichTextExtensionError` here, before any
+ * surface uses it.
+ *
+ * @example
+ * ```
+ * const mentions = createRichTextExtension(mentionsPlugin);
+ * markdownToEditorStateJSON(markdown, {extensions: [mentions]});
+ * ```
+ */
+export declare function createRichTextExtension(plugin: MarkdownPluginEntry): RichTextMarkdownExtension;
+/**
+ * The plugins behind `extensions`, after checking that the configuration is
+ * one RichText can honor (spec:AST-064 FR6): no plugin adopted twice, and no
+ * transformer that imports or exports plugin nodes.
+ */
+export declare function pluginsOf(extensions: ReadonlyArray<RichTextMarkdownExtension>, transformers: ReadonlyArray<Transformer>): ReadonlyArray<MarkdownPluginEntry>;
+/** A plugin node core recognized, and the stand-in that holds its place. */
+export interface ShieldedNode {
+    readonly node: MarkdownExtensionNode;
+    readonly apiVersion: number;
+}
+export interface ShieldedMarkdown {
+    /** The Markdown with a stand-in in place of each recognized node. */
+    readonly markdown: string;
+    /** What each stand-in holds the place of. */
+    readonly standIns: ReadonlyMap<string, ShieldedNode>;
+}
+/** Private-use characters that do not occur in `text`, in order. */
+export declare function absentCharacters(text: string): Generator<string>;
+/**
+ * Replaces the source of every plugin node core recognizes in `markdown` with
+ * a stand-in, so Lexical's transformers never read plugin source as base
+ * Markdown (spec:AST-064 FR5). A node whose source core does not recognize at
+ * any one occurrence — a span split across a container's line markers — stays
+ * text.
+ */
+export declare function shieldExtensionSources(markdown: string, plugins: ReadonlyArray<MarkdownPluginEntry>): ShieldedMarkdown;
+/**
+ * Puts a RichTextExtensionNode in place of every stand-in Lexical imported
+ * into `holder`: inline nodes where their stand-in is, and a block node in
+ * place of the paragraph that holds only its stand-in.
+ */
+export declare function $restoreExtensionSources(holder: ElementNode, standIns: ReadonlyMap<string, ShieldedNode>): void;
+/**
+ * Exports every plugin node as its exact source (spec:AST-064 FR10). Always
+ * part of RichText's export, whatever transformers the caller passes, so no
+ * transformer set can drop a plugin node's source.
+ */
+export declare const EXTENSION_EXPORT_TRANSFORMERS: ReadonlyArray<Transformer>;
+/**
+ * A text view of an inline plugin node for Lexical's exporter: it reads as
+ * text holding `placeholder`, with the node's formats, so emphasis, strong, or
+ * strikethrough around the node wraps it instead of closing before it. The
+ * caller writes the node's source in place of the placeholder.
+ */
+export declare function extensionTextView(node: RichTextExtensionNode, placeholder: string): TextNode;
+/**
+ * `transformers` with the plugin node export first, the same array for the
+ * same transformers so callers that cache by transformer list keep hitting.
+ */
+export declare function withExtensionExport(transformers: ReadonlyArray<Transformer>): Array<Transformer>;
+export {};
+//# sourceMappingURL=markdownExtensions.d.ts.map

package/dist/markdownExtensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdownExtensions.d.ts","sourceRoot":"","sources":["../src/markdownExtensions.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAKL,QAAQ,EACR,KAAK,WAAW,EAGjB,MAAM,SAAS,CAAC;AACjB,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACzB,MAAM,sCAAsC,CAAC;AAE9C,OAAO,EAGL,qBAAqB,EACtB,MAAM,yBAAyB,CAAC;AAEjC,QAAA,MAAM,eAAe,eAA6C,CAAC;AAEnE;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,CAAC,eAAe,CAAC,EAAE,mBAAmB,CAAC;CACjD;AAED,gFAAgF;AAChF,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;gBAErB,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;CAWxE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,mBAAmB,GAC1B,yBAAyB,CAM3B;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,UAAU,EAAE,aAAa,CAAC,yBAAyB,CAAC,EACpD,YAAY,EAAE,aAAa,CAAC,WAAW,CAAC,GACvC,aAAa,CAAC,mBAAmB,CAAC,CA4BpC;AAMD,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CACtD;AAQD,oEAAoE;AACpE,wBAAiB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAUjE;AAgDD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,aAAa,CAAC,mBAAmB,CAAC,GAC1C,gBAAgB,CAuDlB;AAgCD;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,GAC1C,IAAI,CAON;AA2FD;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,EAAE,aAAa,CAAC,WAAW,CAsBpE,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,qBAAqB,EAC3B,WAAW,EAAE,MAAM,GAClB,QAAQ,CAOV;AAOD;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,aAAa,CAAC,WAAW,CAAC,GACvC,KAAK,CAAC,WAAW,CAAC,CAOpB"}