@blue-patterns/richtext 0.0.0-stage → 0.7.18

package/dist/markdownExtensions.js

@@ -0,0 +1,392 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @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 { $createParagraphNode, $createTextNode, $isLineBreakNode, $isParagraphNode, TextNode } from 'lexical';
+import { getMarkdownPluginCapabilities } from '@blue-patterns/core/Markdown/plugins';
+import { parseMarkdownAst } from '@blue-patterns/core/Markdown/parser';
+import { $createRichTextExtensionNode, $isRichTextExtensionNode, RichTextExtensionNode } from "./markdownExtensionNode.js";
+const extensionPlugin = Symbol('RichTextMarkdownExtension.plugin');
+
+/**
+ * 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.
+ */
+
+/** Why RichText refused a plugin or a configuration (spec:AST-064 FR4, FR6). */
+export class RichTextExtensionError extends Error {
+  /** The plugin RichText refused, or that a configuration claims twice. */
+
+  /** What RichText cannot honor: `transform`, or what was claimed twice. */
+
+  /** The transformer or second extension that claims the same thing. */
+
+  constructor(plugin, capability, claimant) {
+    super(claimant == null ? `RichText cannot adopt Markdown plugin "${plugin}": RichText does not run its ${capability}.` : `RichText cannot use Markdown plugin "${plugin}" with ${claimant}: both claim its ${capability}.`);
+    this.name = 'RichTextExtensionError';
+    this.plugin = plugin;
+    this.capability = capability;
+    this.claimant = claimant;
+  }
+}
+
+/**
+ * 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 function createRichTextExtension(plugin) {
+  const capabilities = getMarkdownPluginCapabilities(plugin);
+  if (capabilities.transform) {
+    throw new RichTextExtensionError(plugin.name, 'transform', null);
+  }
+  return Object.freeze({
+    name: plugin.name,
+    [extensionPlugin]: plugin
+  });
+}
+
+/**
+ * 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 function pluginsOf(extensions, transformers) {
+  const seen = new Set();
+  for (const extension of extensions) {
+    if (seen.has(extension.name)) {
+      throw new RichTextExtensionError(extension.name, 'syntax', `a second extension for "${extension.name}"`);
+    }
+    seen.add(extension.name);
+  }
+  const [first] = extensions;
+  if (first != null) {
+    transformers.forEach((transformer, index) => {
+      if ('dependencies' in transformer && transformer.dependencies.includes(RichTextExtensionNode)) {
+        throw new RichTextExtensionError(first.name, 'nodes', `transformer ${index} (${transformer.type})`);
+      }
+    });
+  }
+  return extensions.map(extension => extension[extensionPlugin]);
+}
+
+// ---------------------------------------------------------------------------
+// Shielding plugin source from Lexical's import
+// ---------------------------------------------------------------------------
+
+/** A plugin node core recognized, and the stand-in that holds its place. */
+
+const PRIVATE_USE_RANGES = [[0xe000, 0xf8ff], [0xf0000, 0xffffd], [0x100000, 0x10fffd]];
+
+/** Private-use characters that do not occur in `text`, in order. */
+export function* absentCharacters(text) {
+  const present = new Set(text);
+  for (const [first, last] of PRIVATE_USE_RANGES) {
+    for (let codePoint = first; codePoint <= last; codePoint++) {
+      const character = String.fromCodePoint(codePoint);
+      if (!present.has(character)) {
+        yield character;
+      }
+    }
+  }
+}
+
+/**
+ * The extension nodes core recognizes in `markdown`, in document order: inline
+ * nodes anywhere, and block nodes at the top level only (block syntax nested
+ * in a list item, quote, or table cell stays text in RichText).
+ */
+function recognizedNodes(markdown, plugins) {
+  const adoptable = [];
+  let total = 0;
+  const visit = (node, isTopLevel) => {
+    if (node == null || typeof node !== 'object') {
+      return;
+    }
+    const candidate = node;
+    if (candidate.type === 'extension') {
+      total++;
+      const extension = node;
+      if (typeof extension.source === 'string' && (extension.display === 'inline' || isTopLevel)) {
+        adoptable.push(extension);
+      }
+      return;
+    }
+    if (Array.isArray(candidate.children)) {
+      for (const child of candidate.children) {
+        visit(child, false);
+      }
+    }
+  };
+  const root = parseMarkdownAst(markdown, {
+    plugins: [...plugins]
+  });
+  for (const block of root.children) {
+    visit(block, true);
+  }
+  return {
+    adoptable,
+    total
+  };
+}
+
+/**
+ * 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 function shieldExtensionSources(markdown, plugins) {
+  const standIns = new Map();
+  if (plugins.length === 0) {
+    return {
+      markdown,
+      standIns
+    };
+  }
+  const {
+    adoptable,
+    total
+  } = recognizedNodes(markdown, plugins);
+  if (adoptable.length === 0) {
+    return {
+      markdown,
+      standIns
+    };
+  }
+  const versions = new Map(plugins.map(plugin => [plugin.name, plugin.apiVersion]));
+  const tokens = absentCharacters(markdown);
+  // How many recognized nodes with each source are still to be placed.
+  const remaining = new Map();
+  for (const node of adoptable) {
+    const source = node.source ?? '';
+    remaining.set(source, (remaining.get(source) ?? 0) + 1);
+  }
+  let text = markdown;
+  let shielded = 0;
+  let searchFrom = 0;
+  for (const node of adoptable) {
+    const source = node.source ?? '';
+    const token = tokens.next().value;
+    if (token == null || source === '') {
+      break;
+    }
+    const first = text.indexOf(source, searchFrom);
+    // When every remaining occurrence of the source is a node core
+    // recognized, the first occurrence is this node: no need to ask core.
+    const isEveryOccurrence = occurrences(text, source, searchFrom) === (remaining.get(source) ?? 0);
+    remaining.set(source, (remaining.get(source) ?? 1) - 1);
+    for (let at = first; at !== -1; at = text.indexOf(source, at + 1)) {
+      const candidate = text.slice(0, at) + token + text.slice(at + source.length);
+      // The right occurrence is the one whose replacement removes exactly
+      // this node from core's parse and leaves every other node in place.
+      if (isEveryOccurrence || recognizedNodes(candidate, plugins).total === total - shielded - 1) {
+        text = candidate;
+        shielded++;
+        searchFrom = at + token.length;
+        standIns.set(token, {
+          node,
+          apiVersion: versions.get(node.plugin) ?? 1
+        });
+        break;
+      }
+    }
+  }
+  return {
+    markdown: text,
+    standIns
+  };
+}
+
+/** How many times `source` occurs in `text` from `from`, overlaps included. */
+function occurrences(text, source, from) {
+  let count = 0;
+  for (let at = text.indexOf(source, from); at !== -1; at = text.indexOf(source, at + 1)) {
+    count++;
+  }
+  return count;
+}
+function $nodeFor({
+  node,
+  apiVersion
+}, format = 0) {
+  return $createRichTextExtensionNode({
+    plugin: node.plugin,
+    apiVersion,
+    name: node.name,
+    display: node.display,
+    data: node.data,
+    source: node.source ?? ''
+  }, format);
+}
+
+/**
+ * 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 function $restoreExtensionSources(holder, standIns) {
+  if (standIns.size === 0) {
+    return;
+  }
+  for (const textNode of holder.getAllTextNodes()) {
+    $restoreInText(textNode, holder, standIns);
+  }
+}
+function $restoreInText(textNode, holder, standIns) {
+  const text = textNode.getTextContent();
+  const offsets = new Set();
+  let offset = 0;
+  for (const character of text) {
+    if (standIns.has(character)) {
+      offsets.add(offset);
+      offsets.add(offset + character.length);
+    }
+    offset += character.length;
+  }
+  offsets.delete(0);
+  offsets.delete(text.length);
+  if (offsets.size === 0 && !standIns.has(text)) {
+    return;
+  }
+  const pieces = offsets.size === 0 ? [textNode] : textNode.splitText(...[...offsets].sort((a, b) => a - b));
+  for (const piece of pieces) {
+    const shielded = standIns.get(piece.getTextContent());
+    if (shielded == null) {
+      continue;
+    }
+    if (shielded.node.display === 'inline') {
+      // The node keeps the text formats its stand-in had: a node inside
+      // emphasis, strong, or strikethrough stays inside it.
+      piece.replace($nodeFor(shielded, piece.getFormat()));
+      continue;
+    }
+    const paragraph = piece.getParent();
+    if ($isParagraphNode(paragraph) && paragraph.getParent()?.is(holder) === true) {
+      $placeBlockNode(paragraph, piece, $nodeFor(shielded));
+    } else {
+      // A block stand-in that did not land in a top-level paragraph keeps
+      // the node's source as text.
+      piece.replace($createTextNode(shielded.node.source ?? ''));
+    }
+  }
+}
+
+/**
+ * Puts a block node where its stand-in sits in `paragraph`, splitting the
+ * paragraph around it: lines before the stand-in stay a paragraph, the node
+ * follows as its own top-level block, and lines after it become a new
+ * paragraph — as core reads a block that starts on the line after a paragraph
+ * line.
+ */
+function $placeBlockNode(paragraph, standIn, block) {
+  const after = standIn.getNextSiblings();
+  const before = standIn.getPreviousSiblings();
+  // The line breaks around the stand-in end and start the neighbouring lines.
+  if ($isLineBreakNode(before[before.length - 1])) {
+    before[before.length - 1]?.remove();
+  }
+  if ($isLineBreakNode(after[0])) {
+    after[0]?.remove();
+    after.shift();
+  }
+  standIn.remove();
+  if (after.length > 0) {
+    const rest = $createParagraphNode();
+    rest.append(...after);
+    paragraph.insertAfter(rest);
+  }
+  paragraph.insertAfter(block);
+  if (paragraph.getChildrenSize() === 0) {
+    paragraph.remove();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Export
+// ---------------------------------------------------------------------------
+
+const NEVER = /(?!)/;
+
+/**
+ * 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 const EXTENSION_EXPORT_TRANSFORMERS = [{
+  dependencies: [RichTextExtensionNode],
+  export: node => $isRichTextExtensionNode(node) && !node.isInline() ? node.getSource() : null,
+  regExp: NEVER,
+  replace: () => false,
+  type: 'element'
+}, {
+  dependencies: [RichTextExtensionNode],
+  export: node => $isRichTextExtensionNode(node) && node.isInline() ? node.getSource() : null,
+  importRegExp: NEVER,
+  regExp: NEVER,
+  replace: () => {},
+  type: 'text-match'
+}];
+
+/**
+ * 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 function extensionTextView(node, placeholder) {
+  const view = Object.create(TextNode.prototype);
+  // Reads of the view's format go to the node itself through its key.
+  Object.assign(view, {
+    __key: node.getKey()
+  });
+  view.getTextContent = () => placeholder;
+  view.getParent = () => node.getParent();
+  return view;
+}
+const withExport = new WeakMap();
+
+/**
+ * `transformers` with the plugin node export first, the same array for the
+ * same transformers so callers that cache by transformer list keep hitting.
+ */
+export function withExtensionExport(transformers) {
+  let combined = withExport.get(transformers);
+  if (combined == null) {
+    combined = [...EXTENSION_EXPORT_TRANSFORMERS, ...transformers];
+    withExport.set(transformers, combined);
+  }
+  return combined;
+}

package/dist/markdownHardLineBreak.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @file markdownHardLineBreak.ts
+ * @input Uses lexical (LineBreakNode) and @lexical/markdown
+ *   (TextMatchTransformer).
+ * @output Exports HARD_LINE_BREAK, the transformer that writes a line break
+ *   added in the editor (Shift+Enter) as a Markdown hard break, `\` and a
+ *   line ending, and drops a line break that ends its block.
+ * @position Part of DEFAULT_TRANSFORMERS (markdownTable.ts). Import joins
+ *   soft line breaks into their block (markdownSource.ts), so every line
+ *   break left in a paragraph, list item, or quote is a hard one. Lexical
+ *   writes the breaks it imported as hard with their own marker (two spaces
+ *   or a backslash); a break typed in the editor has none and would be
+ *   written as a plain line ending, which reads back as a soft break and
+ *   loses the line (spec:AST-062 FR3). Headings are one line in Markdown, so
+ *   a break typed in one keeps Lexical's plain line ending. A hard break has
+ *   no form at the end of a block: CommonMark reads its backslash as a
+ *   literal character there, and shows nothing for two trailing spaces. So a
+ *   line break that only other breaks or spaces follow is written as nothing.
+ */
+import type { TextMatchTransformer } from '@lexical/markdown';
+import { LineBreakNode } from 'lexical';
+/** Whether Lexical's Markdown import marked this line break as a hard one. */
+export declare function isMarkedHardLineBreak(node: LineBreakNode): boolean;
+export declare const HARD_LINE_BREAK: TextMatchTransformer;
+//# sourceMappingURL=markdownHardLineBreak.d.ts.map

package/dist/markdownHardLineBreak.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdownHardLineBreak.d.ts","sourceRoot":"","sources":["../src/markdownHardLineBreak.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,mBAAmB,CAAC;AAG5D,OAAO,EAAgC,aAAa,EAAC,MAAM,SAAS,CAAC;AAGrE,8EAA8E;AAC9E,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAMlE;AAkBD,eAAO,MAAM,eAAe,EAAE,oBAmB7B,CAAC"}

package/dist/markdownHardLineBreak.js

@@ -0,0 +1,59 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file markdownHardLineBreak.ts
+ * @input Uses lexical (LineBreakNode) and @lexical/markdown
+ *   (TextMatchTransformer).
+ * @output Exports HARD_LINE_BREAK, the transformer that writes a line break
+ *   added in the editor (Shift+Enter) as a Markdown hard break, `\` and a
+ *   line ending, and drops a line break that ends its block.
+ * @position Part of DEFAULT_TRANSFORMERS (markdownTable.ts). Import joins
+ *   soft line breaks into their block (markdownSource.ts), so every line
+ *   break left in a paragraph, list item, or quote is a hard one. Lexical
+ *   writes the breaks it imported as hard with their own marker (two spaces
+ *   or a backslash); a break typed in the editor has none and would be
+ *   written as a plain line ending, which reads back as a soft break and
+ *   loses the line (spec:AST-062 FR3). Headings are one line in Markdown, so
+ *   a break typed in one keeps Lexical's plain line ending. A hard break has
+ *   no form at the end of a block: CommonMark reads its backslash as a
+ *   literal character there, and shows nothing for two trailing spaces. So a
+ *   line break that only other breaks or spaces follow is written as nothing.
+ */
+
+import { $isHeadingNode } from '@lexical/rich-text';
+import { $findMatchingParent } from '@lexical/utils';
+import { $isLineBreakNode, $isTextNode, LineBreakNode } from 'lexical';
+/** Whether Lexical's Markdown import marked this line break as a hard one. */
+export function isMarkedHardLineBreak(node) {
+  const serialized = node.exportJSON();
+  return typeof serialized.$?.mdHardLineBreak === 'string' && serialized.$.mdHardLineBreak !== '';
+}
+
+/** Whether only line breaks and blank text follow `node` in its block. */
+function $endsItsBlock(node) {
+  for (let next = node.getNextSibling(); next != null; next = next.getNextSibling()) {
+    const isBlankText = $isTextNode(next) && next.getTextContent().trim() === '';
+    if (!$isLineBreakNode(next) && !isBlankText) {
+      return false;
+    }
+  }
+  return true;
+}
+export const HARD_LINE_BREAK = {
+  dependencies: [LineBreakNode],
+  export: node => {
+    if (!$isLineBreakNode(node) ||
+    // A heading is one line in Markdown; a break inside one has no
+    // hard-break form, so it keeps Lexical's plain line ending.
+    $findMatchingParent(node, $isHeadingNode) != null) {
+      return null;
+    }
+    if ($endsItsBlock(node)) {
+      return '';
+    }
+    return isMarkedHardLineBreak(node) ? null : '\\\n';
+  },
+  // Export only: Lexical's own import recognizes hard breaks.
+  regExp: /(?!)/,
+  type: 'text-match'
+};

package/dist/markdownHeading.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @file markdownHeading.ts
+ * @input Uses @lexical/markdown (Lexical's HEADING element transformer).
+ * @output Exports HEADING_MARKERS, Lexical's heading transformer reading an
+ *   ATX heading marker as CommonMark does.
+ * @position Part of DEFAULT_TRANSFORMERS (markdownTable.ts) in place of
+ *   Lexical's HEADING, whose pattern allows no indentation. Matches core
+ *   Markdown's ATX headings (CommonMark 0.31 §4.2). Typing shortcuts keep
+ *   Lexical's own trigger: `# ` makes a heading. Text that starts like a
+ *   marker is escaped on export by markdownSource.ts.
+ */
+import { type ElementTransformer } from '@lexical/markdown';
+/**
+ * An ATX heading marker: up to three spaces of indentation, then one to six
+ * `#` and a space, so `   # h` imports as a heading, as in core Markdown. A
+ * typed line becomes a heading only at Lexical's own `# `, so typing
+ * `   # ` changes nothing new.
+ */
+export declare const HEADING_MARKERS: ElementTransformer;
+//# sourceMappingURL=markdownHeading.d.ts.map

package/dist/markdownHeading.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdownHeading.d.ts","sourceRoot":"","sources":["../src/markdownHeading.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH,OAAO,EAAU,KAAK,kBAAkB,EAAC,MAAM,mBAAmB,CAAC;AAKnE;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,kBAO7B,CAAC"}

package/dist/markdownHeading.js

@@ -0,0 +1,30 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file markdownHeading.ts
+ * @input Uses @lexical/markdown (Lexical's HEADING element transformer).
+ * @output Exports HEADING_MARKERS, Lexical's heading transformer reading an
+ *   ATX heading marker as CommonMark does.
+ * @position Part of DEFAULT_TRANSFORMERS (markdownTable.ts) in place of
+ *   Lexical's HEADING, whose pattern allows no indentation. Matches core
+ *   Markdown's ATX headings (CommonMark 0.31 §4.2). Typing shortcuts keep
+ *   Lexical's own trigger: `# ` makes a heading. Text that starts like a
+ *   marker is escaped on export by markdownSource.ts.
+ */
+
+import { HEADING } from '@lexical/markdown';
+
+/** Lexical's own heading marker, which the typing shortcut keeps using. */
+const SHORTCUT_MARKER = /^(#{1,6})\s/;
+
+/**
+ * An ATX heading marker: up to three spaces of indentation, then one to six
+ * `#` and a space, so `   # h` imports as a heading, as in core Markdown. A
+ * typed line becomes a heading only at Lexical's own `# `, so typing
+ * `   # ` changes nothing new.
+ */
+export const HEADING_MARKERS = {
+  ...HEADING,
+  regExp: /^ {0,3}(#{1,6})\s/,
+  replace: (parentNode, children, match, isImport) => isImport || SHORTCUT_MARKER.test(match[0]) ? HEADING.replace(parentNode, children, match, isImport) : false
+};

package/dist/markdownLink.d.ts

@@ -0,0 +1,5 @@
+import { type TextMatchTransformer } from '@lexical/markdown';
+/** `url` as a Markdown destination that reads back as `url`. */
+export declare function markdownDestination(url: string): string;
+export declare const LINK_KEEPING_DESTINATIONS: TextMatchTransformer;
+//# sourceMappingURL=markdownLink.d.ts.map

package/dist/markdownLink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdownLink.d.ts","sourceRoot":"","sources":["../src/markdownLink.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAO,KAAK,oBAAoB,EAAC,MAAM,mBAAmB,CAAC;AA6BlE,gEAAgE;AAChE,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAUvD;AAED,eAAO,MAAM,yBAAyB,EAAE,oBAoBvC,CAAC"}

package/dist/markdownLink.js

@@ -0,0 +1,80 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file markdownLink.ts
+ * @input Uses @lexical/link and @lexical/markdown (LINK).
+ * @output Exports LINK_KEEPING_DESTINATIONS, Lexical's link transformer with
+ *   one change on export. Import is Lexical's own, which reads every
+ *   CommonMark destination and title shape, an angle-bracket destination
+ *   (`<https://e.com/a b>`) included, and decodes backslash escapes and
+ *   character references in both. A destination that needs no escape is
+ *   written by Lexical's export too, which escapes parentheses and an `&`
+ *   that starts a character reference (`https://e.com/a_(b)` as
+ *   `https://e.com/a_\(b\)`). One that holds whitespace or opens with `<`
+ *   is written here in angle brackets, and one with a backslash or
+ *   unbalanced parentheses with those escaped; both escape a
+ *   reference-starting `&` as Lexical does, so every link reads back as
+ *   the same link, whether it was imported or made in the editor
+ *   (spec:AST-062 FR3).
+ * @position Replaces Lexical's LINK in DEFAULT_TRANSFORMERS and in table
+ *   cells (markdownTable.ts).
+ */
+
+import { $isAutoLinkNode, $isLinkNode } from '@lexical/link';
+import { LINK } from '@lexical/markdown';
+
+/** Whether every `)` in `url` closes an earlier `(` and every `(` closes. */
+function isBalanced(url) {
+  let depth = 0;
+  for (const character of url) {
+    if (character === '(') {
+      depth++;
+    } else if (character === ')') {
+      depth--;
+      if (depth < 0) {
+        return false;
+      }
+    }
+  }
+  return depth === 0;
+}
+
+/**
+ * `value` with every `&` that would start a character reference written as
+ * `&#38;`, since import decodes references in a destination and a title.
+ */
+function escapeCharacterReferences(value) {
+  return value.replace(/&(?=#\d+;|#[Xx][\dA-Fa-f]+;|[A-Za-z][\dA-Za-z]*;)/g, '&#38;');
+}
+
+/** `url` as a Markdown destination that reads back as `url`. */
+export function markdownDestination(url) {
+  if (/\s/.test(url) || url.startsWith('<')) {
+    // Only an angle-bracket destination may hold a space or open with `<`
+    // (CommonMark §6.3).
+    return `<${url.replace(/[\\<>]/g, '\\$&')}>`;
+  }
+  // A backslash before punctuation would read back as an escape, so every
+  // backslash is written escaped; so is every parenthesis that does not
+  // balance.
+  return url.replace(isBalanced(url) ? /\\/g : /[\\()]/g, '\\$&');
+}
+export const LINK_KEEPING_DESTINATIONS = {
+  // Lexical's own import reads every CommonMark destination and title shape,
+  // an angle-bracket destination included.
+  ...LINK,
+  export: (node, exportChildren, exportFormat) => {
+    if (!$isLinkNode(node) || $isAutoLinkNode(node)) {
+      return null;
+    }
+    const url = node.getURL();
+    const destination = markdownDestination(url);
+    if (destination === url) {
+      return LINK.export?.(node, exportChildren, exportFormat) ?? null;
+    }
+    const text = exportChildren(node);
+    const written = escapeCharacterReferences(destination);
+    const title = node.getTitle();
+    return title == null || title === '' ? `[${text}](${written})` : `[${text}](${written} "${escapeCharacterReferences(title).replace(/([\\"])/g, '\\$1')}")`;
+  }
+};

package/dist/markdownListExport.d.ts

@@ -0,0 +1,3 @@
+import type { ElementTransformer } from '@lexical/markdown';
+export declare const LIST_EXPORT: ElementTransformer;
+//# sourceMappingURL=markdownListExport.d.ts.map

package/dist/markdownListExport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdownListExport.d.ts","sourceRoot":"","sources":["../src/markdownListExport.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,mBAAmB,CAAC;AAoD1D,eAAO,MAAM,WAAW,EAAE,kBAQzB,CAAC"}