@tangle-network/ui 11.33.0 → 11.34.0

package/src/editor/source-markdown-editor.ts

@@ -0,0 +1,296 @@
+/**
+ * The tiptap half of source-preserving Markdown editing (see
+ * `source-markdown.ts`): a read-only node for blocks the editor cannot
+ * represent, a block-id attribute on every top-level node, and the session
+ * that maps an editor document back onto the file's original bytes.
+ *
+ * tiptap arrives as an argument, so this module reaches it through type-only
+ * imports, which a bundler erases (see `editor-peers.ts`).
+ */
+
+import type * as TiptapReact from "@tiptap/react";
+import { marked, type Token, type Tokens } from "marked";
+import {
+  asReadOnlyDocument,
+  BLOCK_ID_ATTRIBUTE,
+  blockHtml,
+  blockMarkdown,
+  createBlockMerger,
+  parseSourceMarkdown,
+  serializeSourceMarkdown,
+  SOURCE_KIND_ATTRIBUTE,
+  SOURCE_RAW_ATTRIBUTE,
+  withReadOnlyBlocks,
+  type SourceBlockKind,
+  type SourceMarkdown,
+  type SourceNode,
+} from "./source-markdown";
+
+type Core = typeof TiptapReact;
+type Editor = TiptapReact.Editor;
+type PMNode = Editor["state"]["doc"];
+type Schema = Editor["schema"];
+type DOMOutputSpec = unknown[] | string;
+
+/** Name of the read-only node that holds a block's raw Markdown. */
+export const SOURCE_NODE = "markdownSource";
+
+/** Top-level node types that can carry a block id. */
+const BLOCK_TYPES = [
+  "paragraph",
+  "heading",
+  "bulletList",
+  "orderedList",
+  "blockquote",
+  "codeBlock",
+  "horizontalRule",
+  SOURCE_NODE,
+];
+
+const CAPTIONS: Record<SourceBlockKind, string> = {
+  table: "Table",
+  html: "HTML",
+  image: "Image",
+  checklist: "Checklist",
+  definition: "Link definition",
+  markdown: "Markdown",
+  paragraph: "Markdown",
+  heading: "Markdown",
+  code: "Markdown",
+  blockquote: "Markdown",
+  list: "Markdown",
+  hr: "Markdown",
+};
+
+function inlineText(tokens: Token[] | undefined): string {
+  return (tokens ?? [])
+    .map((token) => {
+      switch (token.type) {
+        case "image":
+          return (token as Tokens.Image).text;
+        case "br":
+          return " ";
+        case "html":
+          return "";
+        default: {
+          const children = (token as { tokens?: Token[] }).tokens;
+          return children ? inlineText(children) : (token as { text?: string }).text ?? "";
+        }
+      }
+    })
+    .join("");
+}
+
+function tablePreview(raw: string): DOMOutputSpec | null {
+  const table = marked.lexer(raw, { gfm: true }).find((token) => token.type === "table") as
+    | Tokens.Table
+    | undefined;
+  if (!table) return null;
+  const cell = (tag: "th" | "td", value: Tokens.TableCell) => [tag, {}, inlineText(value.tokens)];
+  return [
+    "table",
+    {},
+    ["thead", {}, ["tr", {}, ...table.header.map((value) => cell("th", value))]],
+    ["tbody", {}, ...table.rows.map((row) => ["tr", {}, ...row.map((value) => cell("td", value))])],
+  ];
+}
+
+function sourcePreview(raw: string, kind: SourceBlockKind): DOMOutputSpec[] {
+  const caption: DOMOutputSpec = [
+    "p",
+    { class: "not-prose m-0 mb-2 text-sm text-muted-foreground" },
+    `${CAPTIONS[kind] ?? "Markdown"} kept exactly as written. Edit it in the Markdown source.`,
+  ];
+  const table = kind === "table" ? tablePreview(raw) : null;
+  if (table) return [caption, ["div", { class: "overflow-x-auto" }, table]];
+  return [caption, ["pre", { class: "m-0 whitespace-pre-wrap" }, ["code", {}, raw]]];
+}
+
+/** The read-only source node and the block-id attribute, built from the loaded tiptap. */
+export function createSourceMarkdownExtensions(core: Core) {
+  const SourceBlock = core.Node.create({
+    name: SOURCE_NODE,
+    group: "block",
+    atom: true,
+    selectable: true,
+    draggable: false,
+    addAttributes() {
+      return {
+        raw: {
+          default: "",
+          parseHTML: (element: HTMLElement) => element.getAttribute(SOURCE_RAW_ATTRIBUTE) ?? "",
+          renderHTML: (attributes: Record<string, unknown>) => ({ [SOURCE_RAW_ATTRIBUTE]: attributes.raw }),
+        },
+        kind: {
+          default: "markdown",
+          parseHTML: (element: HTMLElement) => element.getAttribute(SOURCE_KIND_ATTRIBUTE) ?? "markdown",
+          renderHTML: (attributes: Record<string, unknown>) => ({ [SOURCE_KIND_ATTRIBUTE]: attributes.kind }),
+        },
+      };
+    },
+    parseHTML() {
+      return [{ tag: `div[${SOURCE_RAW_ATTRIBUTE}]` }];
+    },
+    renderHTML({ node, HTMLAttributes }) {
+      return [
+        "div",
+        core.mergeAttributes(HTMLAttributes, {
+          class: "my-3 rounded-lg border border-dashed border-border bg-muted/40 p-3",
+        }),
+        ...sourcePreview(String(node.attrs.raw ?? ""), node.attrs.kind as SourceBlockKind),
+      ] as never;
+    },
+  });
+
+  const BlockIdentity = core.Extension.create({
+    name: "markdownSourceBlockId",
+    addGlobalAttributes() {
+      return [
+        {
+          types: BLOCK_TYPES,
+          attributes: {
+            mdBlock: {
+              default: null,
+              // A split's new half is new text, not a copy of the source block.
+              keepOnSplit: false,
+              parseHTML: (element: HTMLElement) => element.getAttribute(BLOCK_ID_ATTRIBUTE),
+              renderHTML: (attributes: Record<string, unknown>) =>
+                attributes.mdBlock ? { [BLOCK_ID_ATTRIBUTE]: attributes.mdBlock } : {},
+            },
+          },
+        },
+      ];
+    },
+  });
+
+  return [SourceBlock, BlockIdentity];
+}
+
+function blockIdOf(node: PMNode): string | null {
+  const id = (node.attrs as { mdBlock?: unknown }).mdBlock;
+  return typeof id === "string" && id ? id : null;
+}
+
+function isEmptyParagraph(node: PMNode) {
+  return node.type.name === "paragraph" && node.content.size === 0;
+}
+
+function withoutBlockIds(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(withoutBlockIds);
+  if (!value || typeof value !== "object") return value;
+  const out: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (key === "mdBlock") continue;
+    out[key] = withoutBlockIds(entry);
+  }
+  return out;
+}
+
+/**
+ * One open file in the rich editor: its source blocks, the nodes they were
+ * first parsed into, and the Markdown written back for the current document.
+ */
+export class SourceMarkdownSession {
+  source: SourceMarkdown;
+  private readonly core: Core;
+  private readonly markdown: string;
+  private readonly initial = new Map<string, PMNode>();
+  private readonly mergers = new Map<string, (edited: string) => string | null>();
+
+  constructor(core: Core, markdown: string) {
+    this.core = core;
+    this.markdown = markdown;
+    this.source = parseSourceMarkdown(markdown);
+  }
+
+  get html() {
+    return this.source.html;
+  }
+
+  /**
+   * Records the nodes the editor parsed. A block the editor document does not
+   * hold as exactly one top-level node (dropped, split, or merged by the
+   * schema) is shown read-only instead, so no source byte can be lost.
+   */
+  attach(editor: Editor) {
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const unmapped = this.capture(editor.state.doc);
+      if (unmapped.size === 0) return;
+      this.source = attempt < 2 ? withReadOnlyBlocks(this.source, unmapped) : asReadOnlyDocument(this.markdown);
+      editor.commands.setContent(this.source.html, { emitUpdate: false });
+    }
+    this.capture(editor.state.doc);
+  }
+
+  private capture(doc: PMNode): Set<string> {
+    this.initial.clear();
+    this.mergers.clear();
+    const unmapped = new Set<string>();
+    let previous: string | null = null;
+    doc.forEach((node, _offset, index) => {
+      const id = blockIdOf(node);
+      if (id && this.source.byId.has(id)) {
+        if (this.initial.has(id)) unmapped.add(id);
+        else this.initial.set(id, node);
+        previous = id;
+        return;
+      }
+      if (index === doc.childCount - 1 && isEmptyParagraph(node)) return;
+      // A node with no id came out of the block before it (or the first block).
+      const owner = previous ?? this.source.blocks[0]?.id;
+      if (owner) unmapped.add(owner);
+    });
+    for (const block of this.source.blocks) {
+      if (!this.initial.has(block.id)) unmapped.add(block.id);
+    }
+    return unmapped;
+  }
+
+  private toMarkdown(node: PMNode, raw: string) {
+    const fragment = node.type.schema.topNodeType.create(null, node).content;
+    return blockMarkdown(this.core.getHTMLFromFragment(fragment, node.type.schema), raw);
+  }
+
+  private reparses(markdown: string, node: PMNode, schema: Schema) {
+    const html = blockHtml(markdown, this.source.links);
+    if (html === null) return false;
+    const parsed = this.core.createDocument(html, schema);
+    const nodes: PMNode[] = [];
+    parsed.forEach((child) => {
+      if (!isEmptyParagraph(child)) nodes.push(child);
+    });
+    return (
+      nodes.length === 1 &&
+      JSON.stringify(withoutBlockIds(nodes[0].toJSON())) === JSON.stringify(withoutBlockIds(node.toJSON()))
+    );
+  }
+
+  private mergerFor(id: string, initial: PMNode, raw: string) {
+    let merge = this.mergers.get(id);
+    if (!merge) {
+      merge = createBlockMerger(raw, this.toMarkdown(initial, raw));
+      this.mergers.set(id, merge);
+    }
+    return merge;
+  }
+
+  /** The file's Markdown for `doc`: original bytes wherever the reader changed nothing. */
+  serialize(doc: PMNode): string {
+    const nodes: SourceNode[] = [];
+    doc.forEach((node) => {
+      const id = blockIdOf(node);
+      const block = id ? this.source.byId.get(id) : undefined;
+      const initial = id ? this.initial.get(id) : undefined;
+      const raw = node.type.name === SOURCE_NODE ? String(node.attrs.raw ?? "") : null;
+      nodes.push({
+        block: initial ? block : undefined,
+        unchanged: Boolean(initial?.eq(node)),
+        sameType: initial?.type === node.type,
+        markdown: () => raw ?? this.toMarkdown(node, block?.raw ?? ""),
+        merge: (edited) => (initial && block ? this.mergerFor(block.id, initial, block.raw)(edited) : null),
+        reparses: (markdown) => this.reparses(markdown, node, node.type.schema),
+      });
+    });
+    return serializeSourceMarkdown(this.source, nodes);
+  }
+}

package/src/editor/source-markdown.fixtures.ts

@@ -0,0 +1,90 @@
+/**
+ * Markdown fixtures for the source-preserving editor tests.
+ */
+
+/**
+ * One of every block and inline construct, in the less common spellings too.
+ * Trailing spaces are written as \u0020 so an editor cannot strip them.
+ */
+export const KITCHEN_SINK = `
+
+# Title with \`code\` and **bold**
+
+Setext heading
+==============
+
+Paragraph with *star emphasis*, _underscore emphasis_, __double under__, snake_case_name, a\\_b escaped,
+a hard break here\u0020\u0020
+and a [link](https://example.com "Title"), a [ref link][ref], <https://auto.link>, and ~~strike~~.
+
+* star bullet one
+* star bullet two
+    * nested four-space
+
++ plus list
+
+1) paren ordered
+2) second
+
+3. starts at three
+4. four
+
+- [ ] task open
+- [x] task done
+
+> quote line one
+> > nested quote
+
+\`\`\`ts
+const x = 1 // fenced
+\`\`\`
+
+~~~
+tilde fence
+~~~
+
+    indented code
+
+***
+
+---
+___
+
+| Left | Center | Right |
+|:-----|:------:|------:|
+| a | **b** | [c](https://c.example) |
+
+<div align="center">raw html block</div>
+
+![image alt](images/pic.png "pic title")
+
+Text with inline <sup>html</sup> and an emoji 🚀 and trailing spaces\u0020\u0020\u0020
+
+[ref]: https://ref.example "Ref Title"
+
+Line with trailing backslash\\
+next line
+`;
+
+
+/** Shaped like an agent-written competitor call sheet: headings, prose and GFM tables. */
+export const CALL_SHEET = `# Plausible Analytics: competitor call sheet
+
+**Updated:** October 11, 2026 · **Use:** establish what the buyer is comparing before positioning Plausible.
+
+## Three deal paths
+
+| Competitor | Why a buyer may choose it | Call response |
+|---|---|---|
+| Google Analytics 4 | Standard GA4 is free of charge. ([GA4](https://example.com/ga4)) | **Acknowledge:** the no-cost offer is real. |
+| Fathom | Closest paid, cookie-free alternative. | Ask which reports they rely on today. |
+| Simple Analytics | Stricter no-identifier model. | Show the dashboard and ask what is missing. |
+
+## Qualifying questions
+
+1. Which reports do you open every week?
+2. Who signs off on analytics spend?
+
+* Keep the call to 20 minutes
+* Send the comparison after the call
+`;

package/src/editor/source-markdown.test.ts

@@ -0,0 +1,235 @@
+import { describe, expect, it } from "vitest";
+import {
+  blockHtml,
+  blockMarkdown,
+  diffText,
+  mergeBlockEdit,
+  parseSourceMarkdown,
+  serializeSourceMarkdown,
+  type SourceBlock,
+  type SourceMarkdown,
+  type SourceNode,
+} from "./source-markdown";
+import { KITCHEN_SINK } from "./source-markdown.fixtures";
+
+/** The serializer's view of a document nobody edited. */
+function untouched(source: SourceMarkdown): SourceNode[] {
+  return source.blocks.map((block) => ({
+    block,
+    unchanged: true,
+    sameType: true,
+    markdown: () => block.raw,
+    merge: () => block.raw,
+    reparses: () => true,
+  }));
+}
+
+/** A node whose Markdown changed to `edited`, merged the way the editor merges it. */
+function editedNode(block: SourceBlock, canonical: string, edited: string): SourceNode {
+  return {
+    block,
+    unchanged: false,
+    sameType: true,
+    markdown: () => edited,
+    merge: (text) => mergeBlockEdit(block.raw, canonical, text),
+    reparses: () => true,
+  };
+}
+
+function addedNode(markdown: string): SourceNode {
+  return {
+    unchanged: false,
+    sameType: false,
+    markdown: () => markdown,
+    merge: () => null,
+    reparses: () => true,
+  };
+}
+
+describe("parseSourceMarkdown", () => {
+  it("splits a file into blocks whose bytes reassemble it exactly", () => {
+    const source = parseSourceMarkdown(KITCHEN_SINK);
+    const rebuilt = source.prefix + source.blocks.map((block) => block.raw + block.gap).join("");
+    expect(rebuilt).toBe(KITCHEN_SINK);
+    expect(source.prefix).toBe("\n\n");
+  });
+
+  it("keeps blocks the editor cannot represent read-only, by what they are", () => {
+    const kinds = parseSourceMarkdown(KITCHEN_SINK)
+      .blocks.filter((block) => !block.editable)
+      .map((block) => block.kind);
+    expect(kinds).toEqual(["checklist", "table", "html", "image", "html", "definition"]);
+  });
+
+  it("gives the editor a source node for a table, carrying its raw text", () => {
+    const table = "| A | B |\n|---|---|\n| 1 | 2 |";
+    const source = parseSourceMarkdown(`Intro\n\n${table}\n`);
+    expect(source.html).toContain('data-md-kind="table"');
+    expect(source.html).toContain('data-md-raw="| A | B |\n|---|---|\n| 1 | 2 |"');
+    expect(source.html).toMatch(/^<p data-md-block="m[0-9a-z]+:0">Intro<\/p>/);
+  });
+
+  it("keeps CRLF line endings and a missing final newline", () => {
+    for (const file of ["one\r\n\r\n- a\r\n- b\r\n", "no final newline", "\ttab start\n\n-\ttab bullet"]) {
+      const source = parseSourceMarkdown(file);
+      expect(serializeSourceMarkdown(source, untouched(source))).toBe(file);
+    }
+  });
+
+  it("serializes an untouched file byte for byte", () => {
+    const source = parseSourceMarkdown(KITCHEN_SINK);
+    expect(serializeSourceMarkdown(source, untouched(source))).toBe(KITCHEN_SINK);
+  });
+
+  it("resolves reference links defined elsewhere when it re-reads one block", () => {
+    const source = parseSourceMarkdown("See [docs][d].\n\n[d]: https://docs.example\n");
+    expect(blockHtml("See [the docs][d].", source.links)).toContain('href="https://docs.example"');
+    expect(blockHtml("| a |\n|---|\n| 1 |")).toBeNull();
+  });
+});
+
+describe("mergeBlockEdit", () => {
+  it("keeps escapes the re-serialization would add, outside the edit", () => {
+    const raw = "Rename snake_case_name and *keep* it";
+    const canonical = "Rename snake\\_case\\_name and *keep* it";
+    expect(mergeBlockEdit(raw, canonical, "Rename snake\\_case\\_name and *keep* it now")).toBe(
+      "Rename snake_case_name and *keep* it now",
+    );
+  });
+
+  it("keeps the source's list markers and indentation around an edited item", () => {
+    const raw = "* star bullet one\n* star bullet two\n    * nested four-space";
+    const canonical = "- star bullet one\n- star bullet two\n  - nested four-space";
+    const edited = "- star bullet uno\n- star bullet two\n  - nested four-space";
+    expect(mergeBlockEdit(raw, canonical, edited)).toBe(
+      "* star bullet uno\n* star bullet two\n    * nested four-space",
+    );
+  });
+
+  it("keeps a setext heading's underline and underscore emphasis", () => {
+    expect(mergeBlockEdit("Setext heading\n==============", "# Setext heading", "# Setext heading two")).toBe(
+      "Setext heading two\n==============",
+    );
+    expect(mergeBlockEdit("an _emphasised_ word", "an *emphasised* word", "an *emphasised* word, edited")).toBe(
+      "an _emphasised_ word, edited",
+    );
+  });
+
+  it("keeps a reference link and a backslash hard break the canonical form spells differently", () => {
+    expect(
+      mergeBlockEdit(
+        "A [ref link][ref] here",
+        'A [ref link](https://ref.example "Ref Title") here',
+        'A [ref link](https://ref.example "Ref Title") here and there',
+      ),
+    ).toBe("A [ref link][ref] here and there");
+    expect(mergeBlockEdit("one\\\ntwo", "one  \ntwo", "one!  \ntwo")).toBe("one!\\\ntwo");
+  });
+
+  it("deletes the source's own spelling of a deleted span", () => {
+    expect(mergeBlockEdit("keep snake_case drop", "keep snake\\_case drop", "keep drop")).toBe("keep drop");
+  });
+
+  it("returns the original bytes when the edit was undone", () => {
+    expect(mergeBlockEdit("* a", "- a", "- a")).toBe("* a");
+  });
+});
+
+describe("diffText", () => {
+  // Seeded, so a failure reproduces.
+  function random(seed: number) {
+    let state = seed;
+    return () => {
+      state = (state * 1103515245 + 12345) % 2147483648;
+      return state / 2147483648;
+    };
+  }
+
+  it("turns the first text into the second for random edits", () => {
+    const next = random(42);
+    const alphabet = "ab *_-\n#[]()`\\";
+    for (let round = 0; round < 300; round++) {
+      const length = Math.floor(next() * 60);
+      let a = "";
+      for (let i = 0; i < length; i++) a += alphabet[Math.floor(next() * alphabet.length)];
+      let b = a;
+      const edits = 1 + Math.floor(next() * 4);
+      for (let e = 0; e < edits; e++) {
+        const at = Math.floor(next() * (b.length + 1));
+        const cut = Math.floor(next() * 4);
+        const insert = alphabet[Math.floor(next() * alphabet.length)].repeat(Math.floor(next() * 3));
+        b = b.slice(0, at) + insert + b.slice(at + cut);
+      }
+      const ops = diffText(a, b);
+      expect(ops).not.toBeNull();
+      expect(ops!.filter(([op]) => op !== 1).map(([, text]) => text).join("")).toBe(a);
+      expect(ops!.filter(([op]) => op !== -1).map(([, text]) => text).join("")).toBe(b);
+    }
+  });
+
+  it("gives up past its cost bound rather than allocating without limit", () => {
+    expect(diffText("a".repeat(400), "b".repeat(400), 100)).toBeNull();
+  });
+});
+
+describe("serializeSourceMarkdown", () => {
+  const file = "# Title\n\nFirst paragraph.\n\n* one\n* two\n\n| A |\n|---|\n| 1 |\n";
+
+  it("changes only the edited span of an edited block", () => {
+    const source = parseSourceMarkdown(file);
+    const nodes = untouched(source);
+    nodes[2] = editedNode(source.blocks[2], "- one\n- two", "- one\n- two\n- three");
+    expect(serializeSourceMarkdown(source, nodes)).toBe(
+      "# Title\n\nFirst paragraph.\n\n* one\n* two\n- three\n\n| A |\n|---|\n| 1 |\n",
+    );
+  });
+
+  it("separates an added block with a blank line and keeps the file's trailer", () => {
+    const source = parseSourceMarkdown(file);
+    const nodes = untouched(source);
+    nodes.splice(2, 0, addedNode("A new paragraph."));
+    nodes.push(addedNode("Closing line."));
+    expect(serializeSourceMarkdown(source, nodes)).toBe(
+      "# Title\n\nFirst paragraph.\n\nA new paragraph.\n\n* one\n* two\n\n| A |\n|---|\n| 1 |\n\nClosing line.\n",
+    );
+  });
+
+  it("drops a deleted block and its separator only", () => {
+    const source = parseSourceMarkdown(file);
+    const nodes = untouched(source).filter((_, i) => i !== 1);
+    expect(serializeSourceMarkdown(source, nodes)).toBe("# Title\n\n* one\n* two\n\n| A |\n|---|\n| 1 |\n");
+  });
+
+  it("skips an empty added paragraph, such as the editor's trailing one", () => {
+    const source = parseSourceMarkdown(file);
+    expect(serializeSourceMarkdown(source, [...untouched(source), addedNode("")])).toBe(file);
+  });
+
+  it("writes added text with the file's CRLF line endings", () => {
+    const source = parseSourceMarkdown("one\r\n");
+    expect(serializeSourceMarkdown(source, [...untouched(source), addedNode("two\nlines")])).toBe(
+      "one\r\n\r\ntwo\r\nlines\r\n",
+    );
+  });
+
+  it("falls back to the edited block when the merge does not read back as the edit", () => {
+    const source = parseSourceMarkdown("* one\n* two\n");
+    const node = editedNode(source.blocks[0], "- one\n- two", "- one\n- two\n- three");
+    node.reparses = () => false;
+    expect(serializeSourceMarkdown(source, [node])).toBe("- one\n- two\n- three\n");
+  });
+});
+
+describe("blockMarkdown", () => {
+  it("writes lists with one space after the marker, in the source's marker style", () => {
+    const html = "<ul><li><p>one</p></li><li><p>two</p></li></ul>";
+    expect(blockMarkdown(html)).toBe("- one\n- two");
+    expect(blockMarkdown(html, "* x")).toBe("* one\n* two");
+    expect(blockMarkdown('<ol start="3"><li><p>a</p></li><li><p>b</p></li></ol>', "3) a")).toBe("3) a\n4) b");
+  });
+
+  it("writes strikethrough and rules as GFM", () => {
+    expect(blockMarkdown("<p><s>gone</s></p>")).toBe("~~gone~~");
+    expect(blockMarkdown("<hr>")).toBe("---");
+  });
+});