@tangle-network/ui 11.33.0 → 11.34.0

package/dist/utils/format.d.ts

@@ -1,6 +1,12 @@
 //#region src/utils/format.d.ts
 /** Format a duration in milliseconds to a human-readable string. */
 export declare function formatDuration(ms: number): string;
+/**
+ * Markdown read as plain text, for a one-line preview: code fences, emphasis,
+ * headings, list and quote markers, and link syntax are removed, so a preview
+ * never shows `**` or `#`. Underscores inside words (`snake_case`) are kept.
+ */
+export declare function plainTextFromMarkdown(text: string): string;
 /** Truncate text to `max` characters, appending "..." if truncated. */
 export declare function truncateText(text: string, max: number): string;
 /**

package/dist/utils/format.js

@@ -8,6 +8,14 @@ function formatDuration(ms) {
 	const remaining = seconds % 60;
 	return remaining > 0 ? `${minutes}m ${remaining}s` : `${minutes}m`;
 }
+/**
+* Markdown read as plain text, for a one-line preview: code fences, emphasis,
+* headings, list and quote markers, and link syntax are removed, so a preview
+* never shows `**` or `#`. Underscores inside words (`snake_case`) are kept.
+*/
+function plainTextFromMarkdown(text) {
+	return text.replace(/```[^\n]*\n?([\s\S]*?)```/g, "$1").replace(/`([^`]*)`/g, "$1").replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/^[ \t]{0,3}(?:#{1,6}[ \t]+|>[ \t]?|[-*+][ \t]+|\d+[.)][ \t]+)/gm, "").replace(/(\*\*|__)(?=\S)([\s\S]*?\S)\1/g, "$2").replace(/(^|[^\w*])\*(?=\S)([^*\n]*?\S)\*(?![\w*])/g, "$1$2").replace(/(^|[^\w])_(?=\S)([^_\n]*?\S)_(?!\w)/g, "$1$2").replace(/~~(?=\S)([\s\S]*?\S)~~/g, "$1");
+}
 /** Truncate text to `max` characters, appending "..." if truncated. */
 function truncateText(text, max) {
 	const cleaned = text.replace(/\s+/g, " ").trim();
@@ -51,4 +59,4 @@ function formatBytes(bytes) {
 	return `${gb < 10 ? gb.toFixed(2) : gb.toFixed(1)} GB`;
 }
 //#endregion
-export { formatBytes, formatDuration, formatUptime, truncateText };
+export { formatBytes, formatDuration, formatUptime, plainTextFromMarkdown, truncateText };

package/dist/utils.d.ts

@@ -1,8 +1,8 @@
 import { copyText } from "./utils/copy-text.js";
-import { formatBytes, formatDuration, formatUptime, truncateText } from "./utils/format.js";
+import { formatBytes, formatDuration, formatUptime, plainTextFromMarkdown, truncateText } from "./utils/format.js";
 import { timeAgo } from "./utils/time-ago.js";
 import { TOOL_CATEGORY_ICONS, getToolCategory, getToolDisplayMetadata, getToolErrorText } from "./utils/tool-display.js";
 import { cn } from "./lib/utils.js";
 import { focusField, focusFieldInvalid, focusFieldWithin, focusRing, focusRingInset } from "./lib/focus.js";
 import { ixControl, ixControlAfter, ixControlSoft, ixField, ixRow, ixSelected, ixTabUnderline } from "./lib/interaction.js";
-export { TOOL_CATEGORY_ICONS, cn, copyText, focusField, focusFieldInvalid, focusFieldWithin, focusRing, focusRingInset, formatBytes, formatDuration, formatUptime, getToolCategory, getToolDisplayMetadata, getToolErrorText, ixControl, ixControlAfter, ixControlSoft, ixField, ixRow, ixSelected, ixTabUnderline, timeAgo, truncateText };
+export { TOOL_CATEGORY_ICONS, cn, copyText, focusField, focusFieldInvalid, focusFieldWithin, focusRing, focusRingInset, formatBytes, formatDuration, formatUptime, getToolCategory, getToolDisplayMetadata, getToolErrorText, ixControl, ixControlAfter, ixControlSoft, ixField, ixRow, ixSelected, ixTabUnderline, plainTextFromMarkdown, timeAgo, truncateText };

package/dist/utils.js

@@ -2,7 +2,7 @@ import { ixControl, ixControlAfter, ixControlSoft, ixField, ixRow, ixSelected, i
 import { focusField, focusFieldInvalid, focusFieldWithin, focusRing, focusRingInset } from "./lib/focus.js";
 import { cn } from "./lib/utils.js";
 import { TOOL_CATEGORY_ICONS, getToolCategory, getToolDisplayMetadata, getToolErrorText } from "./utils/tool-display.js";
-import { formatBytes, formatDuration, formatUptime, truncateText } from "./utils/format.js";
+import { formatBytes, formatDuration, formatUptime, plainTextFromMarkdown, truncateText } from "./utils/format.js";
 import { copyText } from "./utils/copy-text.js";
 import { timeAgo } from "./utils/time-ago.js";
-export { TOOL_CATEGORY_ICONS, cn, copyText, focusField, focusFieldInvalid, focusFieldWithin, focusRing, focusRingInset, formatBytes, formatDuration, formatUptime, getToolCategory, getToolDisplayMetadata, getToolErrorText, ixControl, ixControlAfter, ixControlSoft, ixField, ixRow, ixSelected, ixTabUnderline, timeAgo, truncateText };
+export { TOOL_CATEGORY_ICONS, cn, copyText, focusField, focusFieldInvalid, focusFieldWithin, focusRing, focusRingInset, formatBytes, formatDuration, formatUptime, getToolCategory, getToolDisplayMetadata, getToolErrorText, ixControl, ixControlAfter, ixControlSoft, ixField, ixRow, ixSelected, ixTabUnderline, plainTextFromMarkdown, timeAgo, truncateText };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/ui",
-  "version": "11.33.0",
+  "version": "11.34.0",
   "description": "Generic React UI components for Tangle products — primitives, chat, run, files, editor, markdown.",
   "type": "module",
   "license": "MIT",
@@ -150,7 +150,7 @@
   "peerDependencies": {
     "@hocuspocus/provider": ">=2.15.0 <5.0.0",
     "@nanostores/react": ">=0.8.4 <3.0.0",
-    "@tangle-network/brand": "^1.23.0",
+    "@tangle-network/brand": "^1.24.1",
     "@tiptap/core": ">=3.20.4 <4.0.0",
     "@tiptap/extension-collaboration": ">=3.20.4 <4.0.0",
     "@tiptap/extension-collaboration-caret": ">=3.7.0 <4.0.0",

package/src/editor/document-editor-pane.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { type ReactNode, useEffect, useMemo, useState } from "react";
+import { type KeyboardEvent, type ReactNode, useEffect, useMemo, useState } from "react";
 import type { UrlTransform } from "react-markdown";
 import { PencilLine, Save, Users, Wifi, WifiOff } from "lucide-react";
 import { Markdown } from "../markdown/markdown";
@@ -39,6 +39,12 @@ export interface DocumentEditorPaneProps
   markdown?: string;
   /** Persisted baseline when the host controls the current markdown draft. */
   savedMarkdown?: string;
+  /**
+   * Whether the draft has unsaved edits, when the host tracks that itself
+   * (for example against the file's full bytes, frontmatter included). It
+   * takes precedence over comparing the draft with `savedMarkdown`.
+   */
+  dirty?: boolean;
   /** Transform Markdown links and images through the shared URL policy. */
   urlTransform?: UrlTransform;
   mode?: DocumentEditorMode;
@@ -194,6 +200,7 @@ export function DocumentEditorPane({
   toolbar,
   markdown = "",
   savedMarkdown,
+  dirty,
   urlTransform,
   mode,
   defaultMode = "preview",
@@ -215,16 +222,32 @@ export function DocumentEditorPane({
     useState<DocumentEditorMode>(defaultMode);
   const activeMode = mode ?? uncontrolledMode;
   const isCollaborative = backend === "collaborative" && Boolean(collaboration);
-  const isDirty = normalizeMarkdown(draft) !== normalizeMarkdown(savedMarkdown ?? markdown);
+  const isDirty = dirty ?? normalizeMarkdown(draft) !== normalizeMarkdown(savedMarkdown ?? markdown);
+  const canSave = Boolean(onSave) && !readOnly && isDirty && !saving;
   const saveStateLabel = readOnly
     ? "Read only"
     : isCollaborative
       ? isDirty
         ? "Snapshot pending"
         : "Live document current"
-      : isDirty
-        ? "Unsaved changes"
-        : "Saved";
+      : saving
+        ? "Saving…"
+        : isDirty
+          ? "Unsaved changes"
+          : "Saved";
+
+  const save = () => {
+    if (canSave) void onSave?.(draft);
+  };
+
+  // Ctrl+S / Cmd+S saves from anywhere in the pane, the editor included.
+  const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    if (!onSave || readOnly) return;
+    if (!(event.metaKey || event.ctrlKey) || event.altKey || event.shiftKey) return;
+    if (event.key.toLowerCase() !== "s") return;
+    event.preventDefault();
+    save();
+  };
 
   useEffect(() => {
     setDraft(markdown);
@@ -271,26 +294,40 @@ export function DocumentEditorPane({
         </TabsTrigger>
       </TabsList>
 
-      <div className="flex flex-wrap items-center gap-2 text-xs text-muted-foreground">
+      {/* One save state: the status says whether the draft is saved, and the
+          Save button exists only while there is something to save. */}
+      <div className="flex flex-wrap items-center gap-2 text-sm text-muted-foreground">
         {toolbar}
-        <span className="rounded-full border border-border bg-card px-2.5 py-1 font-medium">
-          {isCollaborative ? "Live document" : "Local draft"}
-        </span>
-        <span className="rounded-full border border-border bg-background px-2.5 py-1">
+        {isCollaborative && (
+          <span className="rounded-full border border-border bg-card px-2.5 py-1 font-medium">
+            Live document
+          </span>
+        )}
+        <span
+          role="status"
+          aria-live="polite"
+          className={cn(
+            "rounded-full border px-2.5 py-1",
+            isDirty && !readOnly
+              ? "border-[var(--surface-warning-border)] bg-[var(--surface-warning-bg)] text-[var(--surface-warning-text)]"
+              : "border-border bg-background",
+          )}
+        >
           {saveStateLabel}
         </span>
-        {onSave && !readOnly && (
+        {onSave && !readOnly && (isDirty || saving) && (
           <button
             type="button"
-            onClick={() => void onSave(draft)}
-            disabled={saving || !isDirty}
+            onClick={save}
+            disabled={!canSave}
+            title="Save changes (Ctrl+S)"
             className={cn(
-              "inline-flex items-center gap-2 rounded-[var(--radius-full)] border border-border bg-card px-3 py-1.5 text-xs font-semibold text-foreground transition-colors hover:border-[var(--border-strong)] hover:text-foreground disabled:cursor-not-allowed disabled:opacity-50",
+              "inline-flex items-center gap-2 rounded-[var(--radius-full)] border border-primary bg-primary px-3 py-1.5 text-sm font-semibold text-primary-foreground transition-colors hover:bg-primary/90 disabled:cursor-not-allowed disabled:opacity-50",
               focusRing,
             )}
           >
-            <Save className="h-3.5 w-3.5" />
-            {saving ? "Saving..." : saveLabel}
+            <Save className="h-4 w-4" />
+            {saveLabel}
           </button>
         )}
       </div>
@@ -341,6 +378,7 @@ export function DocumentEditorPane({
     <Tabs
       value={activeMode}
       onValueChange={(nextValue) => setMode(nextValue as DocumentEditorMode)}
+      onKeyDown={handleKeyDown}
       className="h-full"
     >
       <ArtifactPane

package/src/editor/markdown-document-editor.tsx

@@ -7,11 +7,8 @@ import { retryableLazyEditor } from "./editor-lazy";
 import { EditorLoadingPlaceholder } from "./editor-loading";
 import { type DocumentEditorPeers, loadDocumentEditorPeers } from "./editor-peers";
 import { EditorToolbar } from "./editor-toolbar";
-import {
-  htmlToMarkdown,
-  markdownToHtml,
-  normalizeMarkdown,
-} from "./markdown-conversion";
+import { normalizeMarkdown } from "./markdown-conversion";
+import { createSourceMarkdownExtensions, SourceMarkdownSession } from "./source-markdown-editor";
 
 export interface MarkdownDocumentEditorProps {
   value?: string;
@@ -28,12 +25,18 @@ export interface MarkdownDocumentEditorProps {
  * Builds the local markdown editor against loaded tiptap namespaces. The
  * peers arrive as an argument so that this module reaches them through
  * type-only imports, which a bundler erases.
+ *
+ * The editor writes back the file's own bytes wherever the reader changed
+ * nothing (see `source-markdown.ts`): opening a file and leaving it reports no
+ * change, and an edit changes only the edited span. Blocks it cannot represent,
+ * such as tables, are shown read-only and kept verbatim.
  */
 export function createMarkdownDocumentEditor(
   peers: DocumentEditorPeers,
 ): ComponentType<MarkdownDocumentEditorProps> {
   const { EditorContent, useEditor } = peers.react;
   const StarterKit = peers.starterKit.default;
+  const sourceExtensions = createSourceMarkdownExtensions(peers.react);
 
   return function MarkdownDocumentEditor({
     value = "",
@@ -45,8 +48,13 @@ export function createMarkdownDocumentEditor(
     onChange,
     onReady,
   }: MarkdownDocumentEditorProps) {
-    const initialHtml = useMemo(() => markdownToHtml(value), []);
-    const lastAppliedMarkdownRef = useRef(normalizeMarkdown(value));
+    const sessionRef = useRef<SourceMarkdownSession | null>(null);
+    if (!sessionRef.current) sessionRef.current = new SourceMarkdownSession(peers.react, value);
+    const initialHtml = useMemo(() => sessionRef.current!.html, []);
+    // The Markdown last written by this editor or applied from `value`.
+    const lastMarkdownRef = useRef(value);
+    const onChangeRef = useRef(onChange);
+    onChangeRef.current = onChange;
 
     const editor = useEditor({
       extensions: [
@@ -56,7 +64,10 @@ export function createMarkdownDocumentEditor(
               class: "hljs",
             },
           },
+          // Markdown has no underline, so an underline could not be saved.
+          underline: false,
         }),
+        ...sourceExtensions,
       ],
       content: initialHtml,
       editable: !readOnly,
@@ -73,33 +84,37 @@ export function createMarkdownDocumentEditor(
         },
       },
       onUpdate: ({ editor: currentEditor }) => {
-        const nextMarkdown = normalizeMarkdown(htmlToMarkdown(currentEditor.getHTML()));
-        lastAppliedMarkdownRef.current = nextMarkdown;
-        onChange?.(nextMarkdown, currentEditor);
+        const nextMarkdown = sessionRef.current!.serialize(currentEditor.state.doc);
+        // A transaction that changes no Markdown (a selection, a trailing empty
+        // paragraph) is not an edit.
+        if (nextMarkdown === lastMarkdownRef.current) return;
+        lastMarkdownRef.current = nextMarkdown;
+        onChangeRef.current?.(nextMarkdown, currentEditor);
       },
       onCreate: ({ editor: currentEditor }) => {
+        sessionRef.current!.attach(currentEditor);
         onReady?.(currentEditor);
       },
     });
 
     useEffect(() => {
-      if (editor) {
-        editor.setEditable(!readOnly);
-      }
+      // No update event: toggling read-only is not an edit.
+      editor?.setEditable(!readOnly, false);
     }, [editor, readOnly]);
 
     useEffect(() => {
       if (!editor) {
         return;
       }
-
-      const normalizedValue = normalizeMarkdown(value);
-      if (normalizedValue === lastAppliedMarkdownRef.current) {
+      if (normalizeMarkdown(value) === normalizeMarkdown(lastMarkdownRef.current)) {
         return;
       }
 
-      editor.commands.setContent(markdownToHtml(value), { emitUpdate: false });
-      lastAppliedMarkdownRef.current = normalizedValue;
+      const session = new SourceMarkdownSession(peers.react, value);
+      sessionRef.current = session;
+      editor.commands.setContent(session.html, { emitUpdate: false });
+      session.attach(editor);
+      lastMarkdownRef.current = value;
     }, [editor, value]);
 
     return (

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

@@ -0,0 +1,156 @@
+import { act, render, waitFor } from "@testing-library/react";
+import type { Editor } from "@tiptap/react";
+import { describe, expect, it, vi } from "vitest";
+import { MarkdownDocumentEditor } from "./markdown-document-editor";
+import { CALL_SHEET, KITCHEN_SINK } from "./source-markdown.fixtures";
+
+// The first render imports tiptap for real; a cold import on a busy runner
+// takes several seconds.
+const PEERS_LOADED = { timeout: 15_000 };
+const LOADS_PEERS = 30_000;
+
+async function openEditor(value: string) {
+  const onChange = vi.fn<(markdown: string) => void>();
+  let editor: Editor | null = null;
+  const view = render(
+    <MarkdownDocumentEditor
+      value={value}
+      onChange={(markdown) => onChange(markdown)}
+      onReady={(ready) => {
+        editor = ready;
+      }}
+    />,
+  );
+  // The first mount after the peers load can replace its editor instance, so
+  // wait for a live one and hand back the latest.
+  await waitFor(() => {
+    expect(editor).not.toBeNull();
+    expect((editor as Editor | null)?.isDestroyed).toBe(false);
+  }, PEERS_LOADED);
+  return {
+    view,
+    get editor() {
+      return editor! as Editor;
+    },
+    onChange,
+    /** The Markdown the editor last reported, or the value it opened. */
+    saved: () => onChange.mock.calls.at(-1)?.[0] ?? value,
+  };
+}
+
+/** Document position at the start or end of the first text node containing `needle`. */
+function textPosition(editor: Editor, needle: string, edge: "start" | "end" = "end"): number {
+  let found = -1;
+  editor.state.doc.descendants((node, pos) => {
+    if (found >= 0) return false;
+    const index = node.isText ? (node.text ?? "").indexOf(needle) : -1;
+    if (index >= 0) found = pos + index + (edge === "end" ? needle.length : 0);
+    return true;
+  });
+  if (found < 0) throw new Error(`Not in the document: ${needle}`);
+  return found;
+}
+
+function insertAfter(editor: Editor, needle: string, text: string) {
+  act(() => {
+    editor.commands.insertContentAt(textPosition(editor, needle), text);
+  });
+}
+
+function tableRows(markdown: string) {
+  return markdown.split("\n").filter((line) => line.startsWith("|"));
+}
+
+describe("MarkdownDocumentEditor source preservation", () => {
+  it("opens every Markdown construct without reporting a change", async () => {
+    const { editor, onChange, view } = await openEditor(KITCHEN_SINK);
+    act(() => {
+      editor.commands.setTextSelection(1);
+      editor.setEditable(false);
+      editor.setEditable(true);
+    });
+    expect(onChange).not.toHaveBeenCalled();
+    // The table is shown as a table, read-only, instead of a run-on paragraph.
+    const table = view.container.querySelector('[data-md-kind="table"] table');
+    expect(table?.querySelectorAll("tbody tr")).toHaveLength(1);
+    expect(table?.textContent).toContain("Center");
+  }, LOADS_PEERS);
+
+  it.each([
+    ["a paragraph with escapes", "snake_case_name", " (edited)"],
+    ["a star bullet", "star bullet two", "!"],
+    ["a nested bullet", "nested four-space", " item"],
+    ["a paren-ordered item", "paren ordered", " list"],
+    ["a setext heading", "Setext heading", " again"],
+    ["a fenced code block", "const x = 1", "0"],
+    ["a tilde fence", "tilde fence", "d"],
+    ["a nested quote", "nested quote", "d"],
+    ["the last paragraph", "next line", "."],
+  ])("changes only the edited span when typing into %s", async (_name, needle, text) => {
+    const { editor, saved } = await openEditor(KITCHEN_SINK);
+    insertAfter(editor, needle, text);
+    expect(saved()).toBe(KITCHEN_SINK.replace(needle, needle + text));
+  }, LOADS_PEERS);
+
+  it("keeps every table row when the title is edited, the failure founders hit", async () => {
+    const { editor, saved } = await openEditor(CALL_SHEET);
+    act(() => {
+      editor.commands.insertContentAt(textPosition(editor, "Plausible Analytics:", "start"), "Draft: ");
+    });
+    expect(saved()).toBe(CALL_SHEET.replace("# Plausible", "# Draft: Plausible"));
+    expect(tableRows(saved())).toEqual(tableRows(CALL_SHEET));
+    expect(tableRows(saved())).toHaveLength(5);
+  }, LOADS_PEERS);
+
+  it("separates a paragraph added with Enter by a blank line", async () => {
+    const { editor, saved } = await openEditor(CALL_SHEET);
+    act(() => {
+      editor.chain().setTextSelection(textPosition(editor, "positioning Plausible.")).splitBlock().run();
+      editor.commands.insertContent("A new line of notes.");
+    });
+    expect(saved()).toBe(
+      CALL_SHEET.replace("positioning Plausible.\n", "positioning Plausible.\n\nA new line of notes.\n"),
+    );
+  }, LOADS_PEERS);
+
+  it("adds only the delimiters when a word is bolded", async () => {
+    const { editor, saved } = await openEditor(CALL_SHEET);
+    const end = textPosition(editor, "Who signs off");
+    act(() => {
+      editor.chain().setTextSelection({ from: end - "signs off".length, to: end }).toggleBold().run();
+    });
+    expect(saved()).toBe(CALL_SHEET.replace("Who signs off", "Who **signs off**"));
+  }, LOADS_PEERS);
+
+  it("adds an item in the list's own marker style", async () => {
+    const { editor, saved } = await openEditor(CALL_SHEET);
+    act(() => {
+      editor.chain().setTextSelection(textPosition(editor, "after the call")).splitListItem("listItem").run();
+      editor.commands.insertContent("Log the objections");
+    });
+    expect(saved()).toBe(CALL_SHEET.replace("after the call\n", "after the call\n* Log the objections\n"));
+  }, LOADS_PEERS);
+
+  it("removes only the table when its block is deleted", async () => {
+    const { editor, saved } = await openEditor(CALL_SHEET);
+    let tablePos = -1;
+    editor.state.doc.forEach((node, offset) => {
+      if (node.type.name === "markdownSource") tablePos = offset;
+    });
+    act(() => {
+      editor.chain().setNodeSelection(tablePos).deleteSelection().run();
+    });
+    const start = CALL_SHEET.indexOf("| Competitor");
+    const end = CALL_SHEET.indexOf("## Qualifying");
+    expect(saved()).toBe(CALL_SHEET.slice(0, start) + CALL_SHEET.slice(end));
+  }, LOADS_PEERS);
+
+  it("reports the original bytes again once an edit is undone", async () => {
+    const { editor, saved } = await openEditor(KITCHEN_SINK);
+    insertAfter(editor, "star bullet one", "?");
+    act(() => {
+      editor.commands.undo();
+    });
+    expect(saved()).toBe(KITCHEN_SINK);
+  }, LOADS_PEERS);
+});