@blue-patterns/richtext 0.0.0-stage → 0.7.18

package/src/markdownCodeFence.ts

@@ -0,0 +1,216 @@
+// 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,
+  type ElementTransformer,
+  type MultilineElementTransformer,
+} from '@lexical/markdown';
+import {
+  $createTextNode,
+  $getState,
+  $setState,
+  createState,
+  type ElementNode,
+} 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: unknown): string | null =>
+    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: unknown): string | null =>
+    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: unknown): string | null =>
+    typeof value === 'string' && value !== '' ? value : null,
+});
+
+/** The language core Markdown reads from an info string, or null. */
+function languageOf(info: string): string | null {
+  return /^\S+/.exec(info.trimStart())?.[0] ?? null;
+}
+
+/** An opening fence line: its indentation, its fence, and the info string. */
+interface Opening {
+  readonly indentation: number;
+  readonly fence: string;
+  readonly 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: string): Opening | null {
+  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: string, character: '`' | '~'): number {
+  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: ElementNode,
+  lines: ReadonlyArray<string>,
+  startLineIndex: number,
+  opening: Opening,
+): number {
+  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: ElementTransformer['export'] = 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: MultilineElementTransformer = {
+  ...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: MultilineElementTransformer = {
+  ...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/src/markdownExtensionNode.ts

@@ -0,0 +1,339 @@
+// 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,
+  type DOMConversionMap,
+  type DOMConversionOutput,
+  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 function factsFrom(
+  value: Record<string, unknown>,
+): RichTextExtensionNodeFacts {
+  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) as MarkdownPluginData,
+    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.
+ */
+export type RichTextExtensionNodeDecorator = (
+  facts: RichTextExtensionNodeFacts,
+  format: number,
+  nodeKey: NodeKey,
+) => unknown;
+
+const decorators = new WeakMap<LexicalEditor, RichTextExtensionNodeDecorator>();
+
+/** Sets how `editor` draws plugin nodes; returns a function that unsets it. */
+export function setRichTextExtensionNodeDecorator(
+  editor: LexicalEditor,
+  decorator: RichTextExtensionNodeDecorator,
+): () => void {
+  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: RichTextExtensionNode): string {
+  return JSON.stringify({...node.__facts, format: node.__format});
+}
+
+function convertExtensionElement(element: HTMLElement): DOMConversionOutput {
+  let node: RichTextExtensionNode | null = null;
+  try {
+    const parsed: unknown = JSON.parse(
+      element.getAttribute(FACTS_ATTRIBUTE) ?? '',
+    );
+    if (parsed != null && typeof parsed === 'object') {
+      const value = parsed as Record<string, unknown>;
+      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: HTMLElement) =>
+  element.hasAttribute(FACTS_ATTRIBUTE)
+    ? {conversion: convertExtensionElement, priority: 4 as const}
+    : null;
+
+export 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 {
+    return 'astryx-markdown-extension';
+  }
+
+  static clone(node: RichTextExtensionNode): RichTextExtensionNode {
+    return new RichTextExtensionNode(node.__facts, node.__format, node.__key);
+  }
+
+  static importJSON(
+    serialized: SerializedLexicalNode & Record<string, unknown>,
+  ): RichTextExtensionNode {
+    // 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(): DOMConversionMap {
+    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: RichTextExtensionNodeFacts = factsFrom({}),
+    format = 0,
+    key?: NodeKey,
+  ) {
+    super(key);
+    this.__facts = facts;
+    this.__format = facts.display === 'inline' ? format : 0;
+  }
+
+  exportJSON(): SerializedRichTextExtensionNode {
+    const latest = this.getLatest();
+    return {
+      ...super.exportJSON(),
+      ...latest.__facts,
+      format: latest.__format,
+    };
+  }
+
+  /** The node's identity, data, and source. */
+  getFacts(): RichTextExtensionNodeFacts {
+    return this.getLatest().__facts;
+  }
+
+  /** The exact Markdown the node was read from. */
+  getSource(): string {
+    return this.getLatest().__facts.source;
+  }
+
+  /** The text formats the node sits inside, as a text node's format bits. */
+  getFormat(): number {
+    return this.getLatest().__format;
+  }
+
+  hasFormat(type: TextFormatType): boolean {
+    return (this.getFormat() & TEXT_TYPE_TO_FORMAT[type]) !== 0;
+  }
+
+  /** Puts the node inside, or takes it out of, one text format. */
+  setFormatFlag(type: TextFormatType, isOn: boolean): this {
+    const writable = this.getWritable();
+    const flag = TEXT_TYPE_TO_FORMAT[type];
+    writable.__format = isOn
+      ? writable.__format | flag
+      : writable.__format & ~flag;
+    return writable;
+  }
+
+  createDOM(config: EditorConfig): HTMLElement {
+    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: unknown = config.theme.markdownExtensionBlock;
+      if (typeof className === 'string' && className !== '') {
+        element.className = className;
+      }
+    }
+    return element;
+  }
+
+  exportDOM(): DOMExportOutput {
+    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: RichTextExtensionNode, dom: HTMLElement): false {
+    // 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(): boolean {
+    return this.__facts.display === 'inline';
+  }
+
+  /** The node's text is its source, so plain-text copies and search see it. */
+  getTextContent(): string {
+    return this.getLatest().__facts.source;
+  }
+
+  decorate(editor: LexicalEditor): unknown {
+    return (
+      decorators.get(editor)?.(this.__facts, this.__format, this.__key) ??
+      this.__facts.source
+    );
+  }
+}
+
+export function $createRichTextExtensionNode(
+  facts: RichTextExtensionNodeFacts,
+  format = 0,
+): RichTextExtensionNode {
+  return new RichTextExtensionNode(facts, format);
+}
+
+export function $isRichTextExtensionNode(
+  node: LexicalNode | null | undefined,
+): node is RichTextExtensionNode {
+  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: RangeSelection): TextNode | null {
+  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: TextNode | undefined = 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: RangeSelection | NodeSelection,
+): RichTextExtensionNode[] | null {
+  if ($isNodeSelection(selection)) {
+    const selected = selection.getNodes();
+    return selected.length > 0 &&
+      selected.every(node => $isRichTextExtensionNode(node) && node.isInline())
+      ? (selected as RichTextExtensionNode[])
+      : null;
+  }
+  const nodes = selection
+    .getNodes()
+    .filter(
+      (node): node is RichTextExtensionNode =>
+        $isRichTextExtensionNode(node) && node.isInline(),
+    );
+  return nodes.length > 0 && $firstSelectedText(selection) == null
+    ? nodes
+    : null;
+}