@blue-patterns/richtext 0.0.0-stage → 0.7.18

package/src/markdownListExport.ts

@@ -0,0 +1,85 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file markdownListExport.ts
+ * @input Uses @lexical/list (ListNode, ListItemNode) and @lexical/markdown
+ *   (ElementTransformer).
+ * @output Exports LIST_EXPORT, which writes lists the way Lexical's list
+ *   transformers do except for nesting: a nested list is indented to its
+ *   parent item's content column instead of four spaces per level, and each
+ *   task item writes `[ ]` or `[x]` (markdownTaskList.ts).
+ * @position Part of DEFAULT_TRANSFORMERS (markdownTable.ts), ahead of
+ *   Lexical's list transformers, which still import. Import reads nesting the
+ *   CommonMark way (markdownListIndentation.ts), so a child written four
+ *   spaces under `100. parent` (content column five) would read back at the
+ *   parent's level; indenting to the content column keeps an edited list's
+ *   structure when it is read again (spec:AST-062 FR3).
+ */
+
+import {
+  $isListItemNode,
+  $isListNode,
+  ListItemNode,
+  ListNode,
+} from '@lexical/list';
+import type {ElementTransformer} from '@lexical/markdown';
+import type {ElementNode} from 'lexical';
+import {$getTaskState} from './markdownTaskList';
+
+/** The bullet Lexical recorded for a list on import (`-`, `*`, or `+`). */
+function bulletOf(list: ListNode): string {
+  // The export may hand over a view of the list (an object inheriting from
+  // the node, see markdownSource.ts); Lexical validates the fields of the
+  // node it serializes, so read the recorded state from the node itself.
+  const serialized = list.getLatest().exportJSON() as {
+    $?: {mdListMarker?: unknown};
+  };
+  const marker = serialized.$?.mdListMarker;
+  return marker === '*' || marker === '+' ? marker : '-';
+}
+
+function exportList(
+  list: ListNode,
+  exportChildren: (node: ElementNode) => string,
+  indent: string,
+): string {
+  const lines: Array<string> = [];
+  const type = list.getListType();
+  let index = 0;
+  // Where a nested list goes: the content column of the item before it.
+  let childIndent = `${indent}  `;
+  for (const item of list.getChildren()) {
+    if (!$isListItemNode(item)) {
+      continue;
+    }
+    const first = item.getFirstChild();
+    if (item.getChildrenSize() === 1 && $isListNode(first)) {
+      lines.push(exportList(first, exportChildren, childIndent));
+      continue;
+    }
+    const marker =
+      type === 'number' ? `${list.getStart() + index}. ` : `${bulletOf(list)} `;
+    // A task item, in any bulleted list, writes its box.
+    const task = type === 'number' ? null : $getTaskState(item);
+    const checkbox = task == null ? '' : `[${task === 'checked' ? 'x' : ' '}] `;
+    let text = exportChildren(item);
+    if (type !== 'number') {
+      // As Lexical does: keep `1. ` at the start of a bullet item literal.
+      text = text.replace(/^(\s{0,3}\d+)(\.\s)/, '$1\\$2');
+    }
+    lines.push(indent + marker + checkbox + text);
+    childIndent = indent + ' '.repeat(marker.length);
+    index++;
+  }
+  return lines.join('\n');
+}
+
+export const LIST_EXPORT: ElementTransformer = {
+  dependencies: [ListNode, ListItemNode],
+  export: (node, exportChildren) =>
+    $isListNode(node) ? exportList(node, exportChildren, '') : null,
+  // Export only: Lexical's list transformers import.
+  regExp: /(?!)/,
+  replace: () => false,
+  type: 'element',
+};

package/src/markdownListIndentation.ts

@@ -0,0 +1,105 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file markdownListIndentation.ts
+ * @input Markdown source text.
+ * @output Exports normalizeListIndentation, which rewrites the indentation of
+ *   every list item line so its nesting reads the same to Lexical as it does
+ *   to CommonMark.
+ * @position Used by markdownSource.ts on the text it imports (never on the
+ *   bytes it records). Lexical nests a list item one level per four spaces or
+ *   one tab; CommonMark nests an item under the item whose content it is
+ *   indented to, so `- a` / `  - b` (two spaces) and `1. a` / `   1. b`
+ *   (three) are nested lists that Lexical would flatten (spec:AST-061 FR5).
+ */
+
+/** A list item line: indentation, marker, and the spaces after it. */
+const LIST_ITEM = /^([ \t]*)([-+*]|\d{1,9}[.)])( {1,4}|\t|$)/;
+const FENCE_OPEN = /^[ \t]*(`{3,}|~{3,})/;
+const BLANK_LINE = /^[ \t]*\r?$/;
+/** A thematic break after its indentation: three or more of one marker. */
+const THEMATIC_BREAK_CONTENT = /^([-*_])(?:[ \t]*\1){2,}[ \t]*\r?$/;
+
+/** Columns of leading whitespace, with tabs stopping every four columns. */
+function columnsOf(whitespace: string): number {
+  let columns = 0;
+  for (const character of whitespace) {
+    columns = character === '\t' ? columns + 4 - (columns % 4) : columns + 1;
+  }
+  return columns;
+}
+
+/**
+ * Rewrites each list item line's indentation as four spaces per CommonMark
+ * nesting level, leaving every other line, and every line inside fenced code,
+ * as it is. The line count and every line's content after its indentation
+ * are unchanged.
+ */
+export function normalizeListIndentation(markdown: string): string {
+  const lines = markdown.split('\n');
+  // The content column of each open list item, outermost first.
+  const open: Array<number> = [];
+  let fence: string | null = null;
+  let afterBlankLine = false;
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index];
+    if (fence != null) {
+      if (
+        new RegExp(`^[ \\t]*${fence[0]}{${fence.length},}[ \\t]*\\r?$`).test(
+          line,
+        )
+      ) {
+        fence = null;
+      }
+      continue;
+    }
+    if (BLANK_LINE.test(line)) {
+      afterBlankLine = true;
+      continue;
+    }
+    const leading = /^[ \t]*/.exec(line)?.[0] ?? '';
+    const indent = columnsOf(leading);
+    if (THEMATIC_BREAK_CONTENT.test(line.slice(leading.length))) {
+      // A thematic break, never an item, even where an item could start
+      // (CommonMark 0.31 §4.1). Lexical shows it only as a block of its own,
+      // so a break inside an item loses its indentation and reads as one.
+      while (open.length > 0 && indent < open[open.length - 1]) {
+        open.pop();
+      }
+      if (open.length > 0) {
+        lines[index] = line.slice(leading.length);
+      }
+      afterBlankLine = false;
+      continue;
+    }
+    const item = LIST_ITEM.exec(line);
+    if (item == null) {
+      const opening = FENCE_OPEN.exec(line);
+      if (opening != null) {
+        fence = opening[1];
+      }
+      // A line after a blank line belongs to the items it is indented into;
+      // without a blank line it continues the last item's paragraph lazily.
+      if (afterBlankLine) {
+        while (open.length > 0 && indent < open[open.length - 1]) {
+          open.pop();
+        }
+      }
+      afterBlankLine = false;
+      continue;
+    }
+    afterBlankLine = false;
+    // An item nests under every open item whose content it reaches.
+    while (open.length > 0 && indent < open[open.length - 1]) {
+      open.pop();
+    }
+    const depth = open.length;
+    // The content column, counted across the whole prefix so a tab after
+    // the marker stops at the right column; a marker that ends the line has
+    // its content one column after it.
+    const markerEnd = columnsOf(item[0]) + (item[3] === '' ? 1 : 0);
+    open.push(markerEnd);
+    lines[index] = ' '.repeat(depth * 4) + line.slice(item[1].length);
+  }
+  return lines.join('\n');
+}

package/src/markdownOrderedList.ts

@@ -0,0 +1,60 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file markdownOrderedList.ts
+ * @input Uses @lexical/list (ListNode, ListItemNode) and @lexical/markdown
+ *   (ORDERED_LIST).
+ * @output Exports ORDERED_LIST_KEEPING_START, Lexical's ordered list
+ *   transformer with one change: a nested numbered list starts at the number
+ *   its first item was written with.
+ * @position Replaces Lexical's ORDERED_LIST in DEFAULT_TRANSFORMERS
+ *   (markdownTable.ts). Lexical nests an indented item under a numbered list
+ *   by indenting it into a new list that starts at 1, so `27.` written as the
+ *   first item of a nested list read as `1.` (or `a.` under spec:AST-061
+ *   DEC-6). Markdown keeps every list's start, nested or not (DEC-6), so this
+ *   sets the new nested list's start from the marker. A later item in the same
+ *   nested list continues its sequence, as Lexical's does.
+ */
+
+import {$isListItemNode, $isListNode, type ListNode} from '@lexical/list';
+import {ORDERED_LIST, type ElementTransformer} from '@lexical/markdown';
+
+/**
+ * The list `item` was indented into: the last item under `list`, followed
+ * down through the wrapper items Lexical nests lists in.
+ */
+function nestedListOfLastItem(list: ListNode): ListNode {
+  let current = list;
+  for (;;) {
+    const last = current.getLastChild();
+    const nested = $isListItemNode(last) ? last.getFirstChild() : null;
+    if (
+      !$isListItemNode(last) ||
+      last.getChildrenSize() !== 1 ||
+      !$isListNode(nested)
+    ) {
+      return current;
+    }
+    current = nested;
+  }
+}
+
+export const ORDERED_LIST_KEEPING_START: ElementTransformer = {
+  ...ORDERED_LIST,
+  replace: (parentNode, children, match, isImport) => {
+    const previous = parentNode.getPreviousSibling();
+    const result = ORDERED_LIST.replace(parentNode, children, match, isImport);
+    if ($isListNode(previous) && previous.getListType() === 'number') {
+      const nested = nestedListOfLastItem(previous);
+      // The new item opened this nested list: start it at its own number.
+      if (
+        nested !== previous &&
+        nested.getListType() === 'number' &&
+        nested.getChildrenSize() === 1
+      ) {
+        nested.setStart(Number(match[2]));
+      }
+    }
+    return result;
+  },
+};

package/src/markdownQuote.ts

@@ -0,0 +1,35 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file markdownQuote.ts
+ * @input Uses @lexical/markdown (Lexical's QUOTE element transformer).
+ * @output Exports QUOTE_MARKERS, Lexical's quote transformer reading a block
+ *   quote marker as CommonMark does.
+ * @position Part of DEFAULT_TRANSFORMERS (markdownTable.ts) in place of
+ *   Lexical's QUOTE, whose pattern needs a space after `>` and no indentation.
+ *   Matches core Markdown's block quote marker (CommonMark 0.31 §5.1). Typing
+ *   shortcuts keep Lexical's own trigger: `> ` makes a quote. Text that starts
+ *   like a marker is escaped on export by markdownSource.ts.
+ */
+
+import {QUOTE, type ElementTransformer} from '@lexical/markdown';
+
+/** Lexical's own quote marker, which the typing shortcut keeps using. */
+const SHORTCUT_MARKER = /^>\s/;
+
+/**
+ * A block quote marker: up to three spaces of indentation, then `>` and the
+ * one space or tab that may follow it, so `>a` and `   > a` import as quotes,
+ * as in core Markdown. A typed line becomes a quote only at Lexical's own
+ * `> `, so typing `>` and Enter, or `   > `, changes nothing new. RichText
+ * quotes do not nest: the marker of a quote inside a quote stays in the
+ * outer quote's text.
+ */
+export const QUOTE_MARKERS: ElementTransformer = {
+  ...QUOTE,
+  regExp: /^ {0,3}>[ \t]?/,
+  replace: (parentNode, children, match, isImport) =>
+    isImport || SHORTCUT_MARKER.test(match[0])
+      ? QUOTE.replace(parentNode, children, match, isImport)
+      : false,
+};

package/src/markdownSerializers.ts

@@ -0,0 +1,108 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file markdownSerializers.ts
+ * @input Uses @lexical/headless (createHeadlessEditor), @lexical/markdown
+ *   (transformer types), the shared DEFAULT_NODES set, DEFAULT_TRANSFORMERS,
+ *   and the source-preserving import and export in markdownSource.ts.
+ * @output Standalone Markdown <-> serialized EditorState helpers:
+ *   markdownToEditorStateJSON, editorStateJSONToMarkdown.
+ * @position Exported from the server-safe `@blue-patterns/richtext/markdown`
+ *   entry and re-exported from the @blue-patterns/richtext barrel. Complements the ref's getMarkdown() by working WITHOUT a mounted
+ *   editor (e.g. to produce a `defaultValue` from Markdown on the server).
+ *
+ * SYNC: When modified, update:
+ * - /packages/richtext/src/index.ts (exports)
+ * - /packages/richtext/src/RichTextEditor.doc.mjs (usage notes)
+ * - /packages/richtext/src/RichTextEditor.test.tsx (tests)
+ *
+ * NOTE: `@lexical/headless`, `@lexical/markdown`, and `lexical` are OPTIONAL
+ * peer dependencies. Install them to use these helpers. `@lexical/headless`
+ * runs Lexical without a DOM, so these work in Node / SSR contexts.
+ */
+
+import {createHeadlessEditor} from '@lexical/headless';
+import {type Transformer} from '@lexical/markdown';
+import {DEFAULT_NODES} from './editorNodes';
+import {
+  $exportMarkdownKeepingSource,
+  importMarkdownKeepingSource,
+} from './markdownSource';
+import {DEFAULT_TRANSFORMERS} from './markdownTable';
+import {pluginsOf, type RichTextMarkdownExtension} from './markdownExtensions';
+import type {Klass, LexicalNode} from 'lexical';
+
+/** Options shared by the Markdown serializer helpers. */
+export interface MarkdownSerializerOptions {
+  /**
+   * Markdown transformers to use. Defaults to the editor's default set: the
+   * standard `@lexical/markdown` `TRANSFORMERS` plus GFM tables. Pass the same
+   * array you give `RichTextEditor`'s `transformers` prop so content
+   * round-trips consistently.
+   */
+  transformers?: ReadonlyArray<Transformer>;
+  /**
+   * Extra Lexical nodes to register beyond the default OSS set, mirroring the
+   * editor's `nodes` prop. Required for custom node types to serialize.
+   */
+  nodes?: ReadonlyArray<Klass<LexicalNode>>;
+  /**
+   * Markdown plugins to recognize, each adopted with `createRichTextExtension`
+   * (spec:AST-064). Their syntax becomes extension nodes holding its exact
+   * source; without them, plugin syntax stays text. Pass the same extensions
+   * the surfaces that show the document use.
+   */
+  extensions?: ReadonlyArray<RichTextMarkdownExtension>;
+}
+
+function createSerializerEditor(nodes?: ReadonlyArray<Klass<LexicalNode>>) {
+  return createHeadlessEditor({
+    namespace: 'astryx-editor-serializer',
+    nodes: nodes ? [...DEFAULT_NODES, ...nodes] : [...DEFAULT_NODES],
+    onError(error: Error) {
+      throw error;
+    },
+  });
+}
+
+/**
+ * Convert a Markdown string to a serialized Lexical `EditorState` JSON string
+ * — the same shape `RichTextEditor`'s `defaultValue` expects. Runs headless
+ * (no DOM), so it is safe in Node / SSR.
+ *
+ * @example
+ * ```
+ * const value = markdownToEditorStateJSON('# Title\n\nHello');
+ * <RichTextEditor label="Notes" defaultValue={value} />
+ * ```
+ */
+export function markdownToEditorStateJSON(
+  markdown: string,
+  options: MarkdownSerializerOptions = {},
+): string {
+  const {transformers = DEFAULT_TRANSFORMERS, nodes, extensions = []} = options;
+  const plugins = pluginsOf(extensions, transformers);
+  const editor = createSerializerEditor(nodes);
+  importMarkdownKeepingSource(editor, markdown, [...transformers], plugins);
+  return JSON.stringify(editor.getEditorState().toJSON());
+}
+
+/**
+ * Convert a serialized Lexical `EditorState` JSON string (e.g. the value
+ * produced by `RichTextEditor`'s `onChange` or `defaultValue`) to a Markdown
+ * string. Runs headless (no DOM), so it is safe in Node / SSR.
+ *
+ * @example
+ * ```
+ * const md = editorStateJSONToMarkdown(savedJson);
+ * ```
+ */
+export function editorStateJSONToMarkdown(
+  editorStateJSON: string,
+  options: MarkdownSerializerOptions = {},
+): string {
+  const {transformers = DEFAULT_TRANSFORMERS, nodes} = options;
+  const editor = createSerializerEditor(nodes);
+  const state = editor.parseEditorState(editorStateJSON);
+  return state.read(() => $exportMarkdownKeepingSource([...transformers]));
+}