@lexical/mdast 0.0.0-bootstrap.0 → 0.47.0

package/src/MdastExport.ts

@@ -0,0 +1,545 @@
+/**
+ * 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 {CompiledMdast, MdastExportContext, MdastNode} from './types';
+import type {BaseSelection, ElementNode, LexicalNode} from 'lexical';
+import type {
+  BlockContent,
+  Break,
+  Code,
+  Heading,
+  Link,
+  List,
+  PhrasingContent,
+  Root,
+  RootContent,
+  ThematicBreak,
+} from 'mdast';
+import type {
+  Options as ToMarkdownExtension,
+  State,
+} from 'mdast-util-to-markdown';
+
+import {$sliceSelectedTextNodeContent} from '@lexical/selection';
+import {
+  $getRoot,
+  $getSelection,
+  $getState,
+  $isElementNode,
+  $isLineBreakNode,
+  $isRangeSelection,
+  $isTextNode,
+} from 'lexical';
+import {defaultHandlers, toMarkdown} from 'mdast-util-to-markdown';
+import {toString as mdastToString} from 'mdast-util-to-string';
+
+import {
+  $exportLineBreak,
+  $isBlockLevelNode,
+  exportText,
+  phrasingFromFormattedText,
+  TEXT_FORMAT_MASK,
+} from './handlers';
+import {
+  emphasisMarkerState,
+  paragraphBreakState,
+  strongMarkerState,
+} from './state';
+
+/**
+ * Runs `fn` with `state.options` temporarily overridden, restoring the
+ * previous values afterwards so a per-node override never leaks into the rest
+ * of the serialization.
+ */
+function withOptions<T>(
+  state: State,
+  overrides: State['options'],
+  fn: () => T,
+): T {
+  const {options} = state;
+  const saved: State['options'] = {};
+  for (const key of Object.keys(overrides) as (keyof State['options'])[]) {
+    saved[key] = options[key] as never;
+    options[key] = overrides[key] as never;
+  }
+  try {
+    return fn();
+  } finally {
+    for (const key of Object.keys(saved) as (keyof State['options'])[]) {
+      options[key] = saved[key] as never;
+    }
+  }
+}
+
+/**
+ * A to-markdown extension whose handlers reproduce the literal Markdown syntax
+ * captured on import (and stored on the Lexical nodes), by temporarily
+ * steering the default handlers with per-node options. Delegating to the
+ * defaults keeps all the indentation / nesting / disambiguation behavior
+ * intact while still honoring each node's original marker/fence. Nodes without
+ * captured syntax fall straight through to the defaults, so document-level
+ * options (and contributed `toMarkdownExtensions`) still apply to them.
+ */
+const SYNTAX_TO_MARKDOWN: ToMarkdownExtension = {
+  handlers: {
+    break(node: Break, parent, state, info) {
+      // Delegate first: the default handler substitutes a space when a real
+      // EOL is unsafe in the current construct (headings, table cells). Only
+      // when it chose the hard-break form does the preserved marker apply:
+      // trailing-space markers are reproduced, and the empty marker means the
+      // break is SOFT (a source newline or editor line break) and serializes
+      // as a plain newline rather than being upgraded to a hard break.
+      const result = defaultHandlers.break(node, parent, state, info);
+      if (result !== '\\\n') {
+        return result;
+      }
+      const marker = node.data && node.data.mdastBreak;
+      if (!marker) {
+        return '\n';
+      }
+      return /^ {2,}$/.test(marker) ? `${marker}\n` : result;
+    },
+    code(node: Code, parent, state, info) {
+      const fence = node.data && node.data.mdastFence;
+      if (!fence) {
+        return defaultHandlers.code(node, parent, state, info);
+      }
+      return withOptions(
+        state,
+        {fence: fence[0] === '~' ? '~' : '`', fences: true},
+        () => defaultHandlers.code(node, parent, state, info),
+      );
+    },
+    heading(node: Heading, parent, state, info) {
+      // `data.mdastSetext` is only present (true) for imported setext
+      // headings; everything else defers to the document-level option.
+      if (!(node.data && node.data.mdastSetext === true)) {
+        return defaultHandlers.heading(node, parent, state, info);
+      }
+      return withOptions(state, {setext: true}, () =>
+        defaultHandlers.heading(node, parent, state, info),
+      );
+    },
+    link(node: Link, parent, state, info) {
+      // `data.mdastLinkStyle` preserves the syntax the link was written in.
+      // A title can't be expressed in autolink/literal form, so links with a
+      // title always fall through to the default (resource form).
+      const style = node.data && node.data.mdastLinkStyle;
+      if (style === 'literal' && node.title == null) {
+        // A bare GFM autolink literal: emit the visible text as-is. The
+        // gfm-autolink-literal to-markdown extension keeps surrounding
+        // escaping consistent so it re-parses as the same literal.
+        return mdastToString(node);
+      }
+      if (style === 'inline') {
+        // Force `[text](url)` even when the text equals the URL (the
+        // default handler would normalize that to an autolink).
+        return withOptions(state, {resourceLink: true}, () =>
+          defaultHandlers.link(node, parent, state, info),
+        );
+      }
+      return defaultHandlers.link(node, parent, state, info);
+    },
+    list(node: List, parent, state, info) {
+      if (node.ordered) {
+        const ordered = node.data && node.data.mdastBulletOrdered;
+        if (ordered == null) {
+          return defaultHandlers.list(node, parent, state, info);
+        }
+        return withOptions(state, {bulletOrdered: ordered}, () =>
+          defaultHandlers.list(node, parent, state, info),
+        );
+      }
+      const bullet = node.data && node.data.mdastBullet;
+      if (bullet == null) {
+        return defaultHandlers.list(node, parent, state, info);
+      }
+      return withOptions(
+        state,
+        {bullet, bulletOther: bullet === '-' ? '*' : '-'},
+        () => defaultHandlers.list(node, parent, state, info),
+      );
+    },
+    thematicBreak(node: ThematicBreak, parent, state) {
+      const marker = node.data && node.data.mdastRule;
+      if (marker !== '-' && marker !== '*' && marker !== '_') {
+        return defaultHandlers.thematicBreak(node, parent, state);
+      }
+      return withOptions(state, {rule: marker}, () =>
+        defaultHandlers.thematicBreak(node, parent, state),
+      );
+    },
+  },
+};
+
+/**
+ * Accumulates adjacent plain text nodes that share a format so they serialize
+ * to a single delimiter pair (e.g. `**ab**` rather than `**a****b**`). Shared
+ * by the inline and block export walks.
+ */
+class TextRunAccumulator {
+  private format = -1;
+  private value = '';
+
+  /**
+   * Returns `true` when `child` was absorbed. A format change flushes the
+   * previous run into `out` first. The caller decides *which* text nodes
+   * are eligible (plain text with no export rule of its own); this only
+   * guards the node kind.
+   */
+  push(child: LexicalNode, out: PhrasingContent[]): boolean {
+    if (!$isTextNode(child)) {
+      return false;
+    }
+    const format = child.getFormat() & TEXT_FORMAT_MASK;
+    if (format === this.format) {
+      this.value += child.getTextContent();
+    } else {
+      this.flushInto(out);
+      this.format = format;
+      this.value = child.getTextContent();
+    }
+    return true;
+  }
+
+  flushInto(out: PhrasingContent[]): void {
+    if (this.format >= 0) {
+      out.push(phrasingFromFormattedText(this.value, this.format));
+    }
+    this.format = -1;
+    this.value = '';
+  }
+}
+
+function createNodeExporter(
+  compiled: CompiledMdast,
+  selection: BaseSelection | null = null,
+) {
+  const {exportHandlers} = compiled;
+  // Incremented whenever a selected leaf contributes output. Parents compare
+  // it before/after recursing to keep an element that is not itself selected
+  // but hosts selected content (the markdown analogue of extractWithChild).
+  let selectionHits = 0;
+
+  /**
+   * Whether the run accumulator may absorb `child`: a text node whose only
+   * export behavior would be the core text fallback. A node whose type has
+   * its own registered rule (or the core `'text'` rule, which the
+   * accumulator supersedes to merge adjacent runs) must not be swallowed —
+   * this keeps replaced/custom text nodes dispatching to their handlers.
+   */
+  function mayAccumulate(child: LexicalNode): boolean {
+    const handler = exportHandlers.get(child.getType());
+    return handler === undefined || handler === exportText;
+  }
+
+  /**
+   * Selection filter for one child. With no selection every child passes
+   * through unchanged. Leaves (text, line break, decorator) pass only when
+   * selected, a partially selected text node as a detached clone sliced to
+   * the selected range; `null` means skip. Elements always pass — they are
+   * judged after recursion by {@link $dispatchElement}.
+   */
+  function $filterChild(child: LexicalNode): LexicalNode | null {
+    if (selection === null || $isElementNode(child)) {
+      return child;
+    }
+    if (!child.isSelected(selection)) {
+      return null;
+    }
+    selectionHits++;
+    return $isTextNode(child)
+      ? $sliceSelectedTextNodeContent(selection, child, 'clone')
+      : child;
+  }
+
+  /**
+   * Whether `node` or any descendant is selected. See
+   * {@link MdastExportContext.isIncluded}.
+   */
+  function $isIncluded(node: LexicalNode): boolean {
+    if (selection === null || node.isSelected(selection)) {
+      return true;
+    }
+    if ($isElementNode(node)) {
+      for (const child of node.getChildren()) {
+        if ($isIncluded(child)) {
+          return true;
+        }
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Dispatches an element child, appending its output to `out` unless a
+   * selection is active and neither the element nor any descendant is
+   * selected.
+   */
+  function $dispatchElement(child: LexicalNode, out: MdastNode[]): void {
+    const selfSelected = selection !== null && child.isSelected(selection);
+    if (selfSelected) {
+      selectionHits++;
+    }
+    const before = selectionHits;
+    const result = $dispatch(child);
+    if (selection === null || selfSelected || selectionHits > before) {
+      out.push(...result);
+    }
+  }
+
+  const context: MdastExportContext = {
+    exportBlocks: node => $exportBlocks(node),
+    exportChildren: node => {
+      const out: MdastNode[] = [];
+      for (const child of node.getChildren()) {
+        const target = $filterChild(child);
+        if (target === null) {
+          continue;
+        }
+        if ($isElementNode(target)) {
+          $dispatchElement(target, out);
+        } else {
+          out.push(...$dispatch(target));
+        }
+      }
+      return out;
+    },
+    exportInline: node => $exportInline(node),
+    isIncluded: $isIncluded,
+  };
+
+  function $dispatch(node: LexicalNode): MdastNode[] {
+    const handler = exportHandlers.get(node.getType());
+    if (handler) {
+      const result = handler(node, context);
+      if (result != null) {
+        return Array.isArray(result) ? result : [result];
+      }
+    }
+    // Fallbacks keep unknown nodes from disappearing entirely; text and line
+    // breaks reuse the core handlers so their behavior can't drift.
+    const asText = exportText(node);
+    if (asText !== null) {
+      return [asText];
+    }
+    const asBreak = $exportLineBreak(node);
+    if (asBreak !== null) {
+      return [asBreak];
+    }
+    if ($isElementNode(node)) {
+      return context.exportChildren(node);
+    }
+    const text = node.getTextContent();
+    return text ? [{type: 'text', value: text}] : [];
+  }
+
+  /**
+   * Converts the inline children of `node` into phrasing content.
+   */
+  function $exportInline(node: ElementNode): PhrasingContent[] {
+    const result: PhrasingContent[] = [];
+    const runs = new TextRunAccumulator();
+    for (const child of node.getChildren()) {
+      const target = $filterChild(child);
+      if (target === null) {
+        continue;
+      }
+      if (!(mayAccumulate(target) && runs.push(target, result))) {
+        runs.flushInto(result);
+        if ($isElementNode(target)) {
+          // The registry erases types; phrasing output is the dispatch
+          // contract for inline children.
+          $dispatchElement(target, result as MdastNode[]);
+        } else {
+          result.push(...($dispatch(target) as PhrasingContent[]));
+        }
+      }
+    }
+    runs.flushInto(result);
+    return result;
+  }
+
+  /**
+   * Converts a container whose Lexical children are inline (block quote, list
+   * item) into mdast block content. A LineBreakNode marked as a paragraph
+   * boundary (set by the import handlers when joining sibling paragraphs)
+   * splits the content; any other LineBreakNode stays an inline `break`
+   * (hard or soft according to its marker). Nested block children pass
+   * through directly.
+   */
+  function $exportBlocks(node: ElementNode): BlockContent[] {
+    const blocks: BlockContent[] = [];
+    let inline: PhrasingContent[] = [];
+    const runs = new TextRunAccumulator();
+    const flushParagraph = () => {
+      runs.flushInto(inline);
+      if (inline.length > 0) {
+        blocks.push({children: inline, type: 'paragraph'});
+        inline = [];
+      }
+    };
+    for (const child of node.getChildren()) {
+      const target = $filterChild(child);
+      if (target === null) {
+        continue;
+      }
+      if ($isLineBreakNode(target)) {
+        const asBreak = $exportLineBreak(target);
+        if ($getState(target, paragraphBreakState) || asBreak === null) {
+          flushParagraph();
+        } else {
+          runs.flushInto(inline);
+          inline.push(asBreak);
+        }
+      } else if (mayAccumulate(target) && runs.push(target, inline)) {
+        continue;
+      } else if ($isBlockLevelNode(target)) {
+        flushParagraph();
+        if ($isElementNode(target)) {
+          // The registry erases types; block-level output is the dispatch
+          // contract for block children.
+          $dispatchElement(target, blocks as MdastNode[]);
+        } else {
+          blocks.push(...($dispatch(target) as BlockContent[]));
+        }
+      } else if ($isElementNode(target)) {
+        runs.flushInto(inline);
+        $dispatchElement(target, inline as MdastNode[]);
+      } else {
+        runs.flushInto(inline);
+        inline.push(...($dispatch(target) as PhrasingContent[]));
+      }
+    }
+    flushParagraph();
+    if (blocks.length === 0) {
+      blocks.push({children: [], type: 'paragraph'});
+    }
+    return blocks;
+  }
+
+  return {exportChildren: context.exportChildren};
+}
+
+/**
+ * Picks the document-level emphasis and strong delimiters from the first
+ * italic / bold text node that recorded a known delimiter on import, scanning
+ * the tree rooted at `node`. Mixing delimiters within one document is not
+ * supported by to-markdown's escaping, so a single choice is made per
+ * document; nodes with no recorded delimiter (created in the editor) are
+ * skipped so they cannot mask the document's authored style.
+ */
+function $dominantInlineMarkers(node: ElementNode): {
+  emphasis: '*' | '_' | undefined;
+  strong: '*' | '_' | undefined;
+} {
+  let emphasis: '*' | '_' | undefined;
+  let strong: '*' | '_' | undefined;
+  const visit = (element: ElementNode): void => {
+    for (const child of element.getChildren()) {
+      if ($isTextNode(child)) {
+        if (emphasis === undefined && child.hasFormat('italic')) {
+          const marker = $getState(child, emphasisMarkerState);
+          if (marker === '_') {
+            emphasis = '_';
+          }
+        }
+        if (strong === undefined && child.hasFormat('bold')) {
+          const marker = $getState(child, strongMarkerState);
+          if (marker === '_') {
+            strong = '_';
+          }
+        }
+      } else if ($isElementNode(child)) {
+        visit(child);
+      }
+      if (emphasis !== undefined && strong !== undefined) {
+        return;
+      }
+    }
+  };
+  visit(node);
+  return {emphasis, strong};
+}
+
+/**
+ * Creates a reusable exporter that converts the Lexical tree rooted at the
+ * supplied element (or the editor root) — or just the selected content —
+ * into a Markdown string.
+ */
+export function createMdastExport(compiled: CompiledMdast): {
+  $exportToMdast: (node?: ElementNode) => Root;
+  $exportToMarkdown: (node?: ElementNode) => string;
+  $exportSelectionToMarkdown: (selection?: BaseSelection | null) => string;
+} {
+  // The unfiltered exporter has no per-call state and is shared by every
+  // whole-document export; selection exports build a fresh one per call.
+  const documentExporter = createNodeExporter(compiled);
+
+  const $toMdast = (
+    root: ElementNode,
+    exporter: ReturnType<typeof createNodeExporter>,
+  ): Root => ({
+    // The registry erases types; root-level output is the dispatch contract
+    // for top-level children.
+    children: exporter.exportChildren(root) as RootContent[],
+    type: 'root',
+  });
+
+  const $serialize = (tree: Root, root: ElementNode): string => {
+    // Emphasis/strong delimiters are document-level; the delimiter recorded on
+    // import wins, otherwise contributed toMarkdownExtensions (and the '-'
+    // bullet baseline) decide. Defaults ride as the FIRST extension so that
+    // contributed extensions can override them; SYNTAX_TO_MARKDOWN runs last
+    // so its handlers reproduce the per-node syntax captured on import.
+    const {emphasis, strong} = $dominantInlineMarkers(root);
+    const defaults: ToMarkdownExtension = {bullet: '-'};
+    if (emphasis) {
+      defaults.emphasis = emphasis;
+    }
+    if (strong) {
+      defaults.strong = strong;
+    }
+    const out = toMarkdown(tree, {
+      extensions: [
+        defaults,
+        ...compiled.toMarkdownExtensions,
+        SYNTAX_TO_MARKDOWN,
+      ],
+    });
+    // toMarkdown always appends a trailing newline; drop it so callers get the
+    // same shape as `@lexical/markdown`'s `$convertToMarkdownString`.
+    return out.replace(/\n$/, '');
+  };
+
+  const $exportToMdast = (node?: ElementNode): Root =>
+    $toMdast(node || $getRoot(), documentExporter);
+
+  const $exportToMarkdown = (node?: ElementNode): string => {
+    const root = node || $getRoot();
+    return $serialize($toMdast(root, documentExporter), root);
+  };
+
+  const $exportSelectionToMarkdown = (
+    selection: BaseSelection | null = $getSelection(),
+  ): string => {
+    if (
+      selection === null ||
+      ($isRangeSelection(selection) && selection.isCollapsed())
+    ) {
+      return '';
+    }
+    const root = $getRoot();
+    return $serialize(
+      $toMdast(root, createNodeExporter(compiled, selection)),
+      root,
+    );
+  };
+
+  return {$exportSelectionToMarkdown, $exportToMarkdown, $exportToMdast};
+}

package/src/MdastExportExtension.ts

@@ -0,0 +1,122 @@
+/**
+ * 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 {BaseSelection, ElementNode} from 'lexical';
+import type {Root} from 'mdast';
+
+import {$getExtensionOutput} from '@lexical/extension';
+import {defineExtension} from 'lexical';
+
+import {createMdastExport} from './MdastExport';
+import {MdastImportExtension} from './MdastImportExtension';
+
+/**
+ * The runtime API exposed by {@link MdastExportExtension}. Obtain it inside a
+ * read/update with `$getExtensionOutput(MdastExportExtension)`, or use the
+ * {@link $convertToMarkdownString} shorthand.
+ * @experimental
+ */
+export interface MdastExportExtensionOutput {
+  /**
+   * Serializes the editor root (or `node`) to a Markdown string. Must be
+   * called inside an `editor.read()` or `editor.update()`.
+   */
+  $convertToMarkdownString(node?: ElementNode): string;
+  /**
+   * Exports the editor root (or `node`) to an mdast `Root` tree without
+   * serializing it, for interop with the unified/remark ecosystem (remark
+   * plugins, `remark-rehype`, tree diffing, ...). Must be called inside an
+   * `editor.read()` or `editor.update()`. Syntax preserved from import
+   * rides along as `data` fields on the nodes, mdast's sanctioned
+   * extension point.
+   */
+  $convertToMdast(node?: ElementNode): Root;
+  /**
+   * Serializes only the selected content (defaulting to the current
+   * selection) to a Markdown string: leaves outside the selection are
+   * skipped, partially selected text nodes are sliced to the selected
+   * range, and elements are kept when they or any descendant are selected.
+   * Returns `''` for a null or collapsed selection. Must be called inside
+   * an `editor.read()` or `editor.update()`.
+   */
+  $convertSelectionToMarkdownString(selection?: BaseSelection | null): string;
+}
+
+/**
+ * Markdown serialization for `@lexical/mdast`. Import
+ * (`MdastImportExtension` and the feature extensions that contribute to it) and
+ * export are separate extensions so that editors which only *parse* Markdown
+ * — never serialize back — don't bundle `mdast-util-to-markdown`.
+ *
+ * The export rules themselves are contributed by the same feature extensions
+ * that contribute import rules; this extension compiles the shared registry
+ * into a serializer:
+ * ```ts
+ * dependencies: [MdastCommonMarkExtension, MdastExportExtension]
+ * ```
+ * @experimental
+ */
+export const MdastExportExtension = /* @__PURE__ */ defineExtension<
+  Record<never, never>,
+  '@lexical/mdast/Export',
+  MdastExportExtensionOutput,
+  void
+>({
+  build(editor, config, state): MdastExportExtensionOutput {
+    const {registry} = state.getDependency(MdastImportExtension).output;
+    const {$exportSelectionToMarkdown, $exportToMdast, $exportToMarkdown} =
+      createMdastExport(registry);
+    return {
+      $convertSelectionToMarkdownString: $exportSelectionToMarkdown,
+      $convertToMarkdownString: $exportToMarkdown,
+      $convertToMdast: $exportToMdast,
+    };
+  },
+  dependencies: [MdastImportExtension],
+  name: '@lexical/mdast/Export',
+});
+
+/**
+ * Shorthand for
+ * `$getExtensionOutput(MdastExportExtension).$convertToMarkdownString`.
+ * Must be called inside an `editor.read()` or `editor.update()`. Throws if
+ * the editor was not built with {@link MdastExportExtension}.
+ * @experimental
+ */
+export function $convertToMarkdownString(node?: ElementNode): string {
+  return $getExtensionOutput(MdastExportExtension).$convertToMarkdownString(
+    node,
+  );
+}
+
+/**
+ * Shorthand for `$getExtensionOutput(MdastExportExtension).$convertToMdast`.
+ * Must be called inside an `editor.read()` or `editor.update()`. Throws if
+ * the editor was not built with {@link MdastExportExtension}.
+ * @experimental
+ */
+export function $convertToMdast(node?: ElementNode): Root {
+  return $getExtensionOutput(MdastExportExtension).$convertToMdast(node);
+}
+
+/**
+ * Shorthand for
+ * `$getExtensionOutput(MdastExportExtension).$convertSelectionToMarkdownString`.
+ * Serializes only the selected content (defaulting to the current selection)
+ * to a Markdown string; returns `''` for a null or collapsed selection.
+ * Must be called inside an `editor.read()` or `editor.update()`. Throws if
+ * the editor was not built with {@link MdastExportExtension}.
+ * @experimental
+ */
+export function $convertSelectionToMarkdownString(
+  selection?: BaseSelection | null,
+): string {
+  return $getExtensionOutput(
+    MdastExportExtension,
+  ).$convertSelectionToMarkdownString(selection);
+}

package/src/MdastExtension.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 {defineExtension} from 'lexical';
+
+import {MdastExportExtension} from './MdastExportExtension';
+import {MdastImportExtension} from './MdastImportExtension';
+
+/**
+ * Convenience bundle of {@link MdastImportExtension} and
+ * {@link MdastExportExtension}: Markdown parsing *and* serialization.
+ *
+ * Depend on this when you want both directions without thinking about it:
+ * ```ts
+ * dependencies: [MdastCommonMarkExtension, MdastExtension]
+ * ```
+ * Editors that never serialize back to Markdown can skip it (feature
+ * extensions already pull in {@link MdastImportExtension}) and avoid
+ * bundling the serializer (`mdast-util-to-markdown`).
+ * @experimental
+ */
+export const MdastExtension = /* @__PURE__ */ defineExtension({
+  dependencies: [MdastImportExtension, MdastExportExtension],
+  name: '@lexical/mdast/Mdast',
+});