@tangle-network/ui 11.5.0 → 11.7.0

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

@@ -0,0 +1,121 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import { Component, type ReactNode } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { MarkdownDocumentEditor } from "./markdown-document-editor";
+import type * as EditorPeers from "./editor-peers";
+
+class ErrorTrap extends Component<{ children: ReactNode }, { message: string | null }> {
+  state = { message: null as string | null };
+
+  static getDerivedStateFromError(error: Error) {
+    return { message: error.message };
+  }
+
+  render() {
+    return this.state.message ?? this.props.children;
+  }
+}
+
+/**
+ * Imports the editor with a fresh module graph, so its module-scope `lazy`
+ * has not resolved yet. `loadDocumentEditorPeers` is replaced by `load`.
+ */
+async function freshEditor(load: () => Promise<EditorPeers.DocumentEditorPeers>) {
+  vi.resetModules();
+  vi.doMock("./editor-peers", async () => ({
+    ...(await vi.importActual<typeof EditorPeers>("./editor-peers")),
+    loadDocumentEditorPeers: load,
+  }));
+  return (await import("./markdown-document-editor")).MarkdownDocumentEditor;
+}
+
+afterEach(() => {
+  vi.doUnmock("./editor-peers");
+  vi.resetModules();
+});
+
+describe("MarkdownDocumentEditor", () => {
+  it("renders the real tiptap surface once the peers load", async () => {
+    const { container } = render(
+      <MarkdownDocumentEditor value={"# Title\n\nBody text."} />,
+    );
+
+    await waitFor(() => {
+      expect(container.querySelector(".ProseMirror")).not.toBeNull();
+    });
+
+    const surface = container.querySelector(".ProseMirror");
+    expect(surface?.querySelector("h1")?.textContent).toBe("Title");
+    expect(surface?.textContent).toContain("Body text.");
+    // StarterKit arrives through `peers.starterKit.default`. A broken hand-off
+    // leaves the document without the heading node that StarterKit configures.
+    expect(screen.getByTitle(/^Bold/)).toBeInTheDocument();
+  });
+
+  it("holds a placeholder while the peers are still loading", async () => {
+    let releasePeers: (() => void) | null = null;
+    const gate = new Promise<void>((resolve) => {
+      releasePeers = resolve;
+    });
+    const HeldEditor = await freshEditor(async () => {
+      await gate;
+      const actual = await vi.importActual<typeof EditorPeers>("./editor-peers");
+      return actual.loadDocumentEditorPeers();
+    });
+
+    const { container } = render(<HeldEditor value="# Title" />);
+
+    // A live region, so a screen reader hears that the editor is still coming.
+    expect(screen.getByRole("status")).toHaveTextContent("Loading editor…");
+    expect(container.querySelector(".ProseMirror")).toBeNull();
+
+    releasePeers?.();
+
+    await waitFor(() => {
+      expect(container.querySelector(".ProseMirror h1")?.textContent).toBe("Title");
+    });
+    expect(screen.queryByText("Loading editor…")).toBeNull();
+  });
+
+  it("applies a new value prop to the loaded editor without reporting a change", async () => {
+    const onChange = vi.fn();
+    const { container, rerender } = render(
+      <MarkdownDocumentEditor value="start" onChange={onChange} />,
+    );
+
+    await waitFor(() => {
+      expect(container.querySelector(".ProseMirror")).not.toBeNull();
+    });
+
+    // The editor reports once when it parses the initial content. What must
+    // not grow is the count across a value-prop write: pushing that back
+    // through onChange makes a controlled parent echo its own write.
+    const callsAfterMount = onChange.mock.calls.length;
+
+    rerender(<MarkdownDocumentEditor value="# Changed" onChange={onChange} />);
+
+    await waitFor(() => {
+      expect(container.querySelector(".ProseMirror h1")?.textContent).toBe("Changed");
+    });
+    expect(onChange).toHaveBeenCalledTimes(callsAfterMount);
+  });
+
+  it("fails with the install list when the peers cannot be loaded", async () => {
+    const missing = "install @tiptap/react and @tiptap/starter-kit";
+    const LoadFailingEditor = await freshEditor(async () => {
+      throw new Error(missing);
+    });
+
+    render(
+      <ErrorTrap>
+        <LoadFailingEditor value="start" />
+      </ErrorTrap>,
+    );
+
+    // Loud, and only here: the consumer's build already succeeded without the
+    // peers, so this render is the first place the gap can surface.
+    await waitFor(() => {
+      expect(screen.getByText(missing)).toBeInTheDocument();
+    });
+  });
+});

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

@@ -1,9 +1,11 @@
 "use client";
 
-import { type Editor, EditorContent, useEditor } from "@tiptap/react";
-import StarterKit from "@tiptap/starter-kit";
-import { useEffect, useMemo, useRef } from "react";
+import type { Editor } from "@tiptap/react";
+import { type ComponentType, Suspense, useEffect, useMemo, useRef } from "react";
 import { cn } from "../lib/utils";
+import { retryableLazyEditor } from "./editor-lazy";
+import { EditorLoadingPlaceholder } from "./editor-loading";
+import { type DocumentEditorPeers, loadDocumentEditorPeers } from "./editor-peers";
 import { EditorToolbar } from "./editor-toolbar";
 import {
   htmlToMarkdown,
@@ -22,89 +24,100 @@ export interface MarkdownDocumentEditorProps {
   onReady?: (editor: Editor) => void;
 }
 
-export function MarkdownDocumentEditor({
-  value = "",
-  placeholder = "Start writing...",
-  readOnly = false,
-  autoFocus = false,
-  className,
-  contentClassName,
-  onChange,
-  onReady,
-}: MarkdownDocumentEditorProps) {
-  const initialHtml = useMemo(() => markdownToHtml(value), []);
-  const lastAppliedMarkdownRef = useRef(normalizeMarkdown(value));
-
-  const editor = useEditor({
-    extensions: [
-      StarterKit.configure({
-        codeBlock: {
-          HTMLAttributes: {
-            class: "hljs",
+/**
+ * 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.
+ */
+export function createMarkdownDocumentEditor(
+  peers: DocumentEditorPeers,
+): ComponentType<MarkdownDocumentEditorProps> {
+  const { EditorContent, useEditor } = peers.react;
+  const StarterKit = peers.starterKit.default;
+
+  return function MarkdownDocumentEditor({
+    value = "",
+    placeholder = "Start writing...",
+    readOnly = false,
+    autoFocus = false,
+    className,
+    contentClassName,
+    onChange,
+    onReady,
+  }: MarkdownDocumentEditorProps) {
+    const initialHtml = useMemo(() => markdownToHtml(value), []);
+    const lastAppliedMarkdownRef = useRef(normalizeMarkdown(value));
+
+    const editor = useEditor({
+      extensions: [
+        StarterKit.configure({
+          codeBlock: {
+            HTMLAttributes: {
+              class: "hljs",
+            },
           },
+        }),
+      ],
+      content: initialHtml,
+      editable: !readOnly,
+      autofocus: autoFocus,
+      editorProps: {
+        attributes: {
+          class: cn(
+            "prose prose-sm sm:prose-base max-w-none focus:outline-none",
+            "prose-headings:text-foreground prose-p:text-foreground prose-li:text-foreground",
+            "prose-strong:text-foreground prose-code:text-foreground prose-pre:text-foreground",
+            contentClassName,
+          ),
+          "data-placeholder": placeholder,
         },
-      }),
-    ],
-    content: initialHtml,
-    editable: !readOnly,
-    autofocus: autoFocus,
-    editorProps: {
-      attributes: {
-        class: cn(
-          "prose prose-sm sm:prose-base max-w-none focus:outline-none",
-          "prose-headings:text-foreground prose-p:text-foreground prose-li:text-foreground",
-          "prose-strong:text-foreground prose-code:text-foreground prose-pre:text-foreground",
-          contentClassName,
-        ),
-        "data-placeholder": placeholder,
       },
-    },
-    onUpdate: ({ editor: currentEditor }) => {
-      const nextMarkdown = normalizeMarkdown(htmlToMarkdown(currentEditor.getHTML()));
-      lastAppliedMarkdownRef.current = nextMarkdown;
-      onChange?.(nextMarkdown, currentEditor);
-    },
-    onCreate: ({ editor: currentEditor }) => {
-      onReady?.(currentEditor);
-    },
-  });
-
-  useEffect(() => {
-    if (editor) {
-      editor.setEditable(!readOnly);
-    }
-  }, [editor, readOnly]);
-
-  useEffect(() => {
-    if (!editor) {
-      return;
-    }
-
-    const normalizedValue = normalizeMarkdown(value);
-    if (normalizedValue === lastAppliedMarkdownRef.current) {
-      return;
-    }
-
-    editor.commands.setContent(markdownToHtml(value), { emitUpdate: false });
-    lastAppliedMarkdownRef.current = normalizedValue;
-  }, [editor, value]);
+      onUpdate: ({ editor: currentEditor }) => {
+        const nextMarkdown = normalizeMarkdown(htmlToMarkdown(currentEditor.getHTML()));
+        lastAppliedMarkdownRef.current = nextMarkdown;
+        onChange?.(nextMarkdown, currentEditor);
+      },
+      onCreate: ({ editor: currentEditor }) => {
+        onReady?.(currentEditor);
+      },
+    });
 
-  return (
-    <div
-      className={cn(
-        "flex min-h-[14rem] w-full flex-col overflow-hidden rounded-lg border border-border bg-background",
-        className,
-      )}
-    >
-      <EditorToolbar
-        editor={editor}
-        className="border-border bg-card px-2 py-2"
-      />
-      <div className="min-h-0 flex-1 overflow-auto px-5 py-4">
-        <EditorContent editor={editor} />
-      </div>
+    useEffect(() => {
+      if (editor) {
+        editor.setEditable(!readOnly);
+      }
+    }, [editor, readOnly]);
+
+    useEffect(() => {
+      if (!editor) {
+        return;
+      }
+
+      const normalizedValue = normalizeMarkdown(value);
+      if (normalizedValue === lastAppliedMarkdownRef.current) {
+        return;
+      }
 
-      <style>{`
+      editor.commands.setContent(markdownToHtml(value), { emitUpdate: false });
+      lastAppliedMarkdownRef.current = normalizedValue;
+    }, [editor, value]);
+
+    return (
+      <div
+        className={cn(
+          "flex min-h-[14rem] w-full flex-col overflow-hidden rounded-lg border border-border bg-background",
+          className,
+        )}
+      >
+        <EditorToolbar
+          editor={editor}
+          className="border-border bg-card px-2 py-2"
+        />
+        <div className="min-h-0 flex-1 overflow-auto px-5 py-4">
+          <EditorContent editor={editor} />
+        </div>
+
+        <style>{`
         .ProseMirror p.is-editor-empty:first-child::before {
           content: attr(data-placeholder);
           float: left;
@@ -132,6 +145,25 @@ export function MarkdownDocumentEditor({
           padding: 0;
         }
       `}</style>
-    </div>
+      </div>
+    );
+  };
+}
+
+const lazyMarkdownDocumentEditor = retryableLazyEditor(async () =>
+  createMarkdownDocumentEditor(await loadDocumentEditorPeers()),
+);
+
+/** Local markdown editor. Loads its tiptap peers on first render. */
+export function MarkdownDocumentEditor(props: MarkdownDocumentEditorProps) {
+  const LazyMarkdownDocumentEditor = lazyMarkdownDocumentEditor();
+  return (
+    <Suspense
+      fallback={
+        <EditorLoadingPlaceholder className={cn("min-h-[14rem]", props.className)} />
+      }
+    >
+      <LazyMarkdownDocumentEditor {...props} />
+    </Suspense>
   );
 }

package/src/editor/tiptap-editor.test.tsx

@@ -0,0 +1,228 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import { Component, type ReactNode } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Doc } from "yjs";
+import type * as EditorPeers from "./editor-peers";
+import { createEditorProvider } from "./editor-provider";
+import { createTiptapEditor } from "./tiptap-editor";
+
+class ErrorTrap extends Component<{ children: ReactNode }, { message: string | null }> {
+  state = { message: null as string | null };
+
+  static getDerivedStateFromError(error: Error) {
+    return { message: error.message };
+  }
+
+  render() {
+    return this.state.message ?? this.props.children;
+  }
+}
+
+class StubHocuspocusProvider {
+  static instances: StubHocuspocusProvider[] = [];
+
+  awareness = {
+    clientID: 1,
+    getStates: () => new Map(),
+    getLocalState: () => ({}),
+    setLocalStateField: vi.fn(),
+    on: vi.fn(),
+    off: vi.fn(),
+  };
+  connect = vi.fn();
+  disconnect = vi.fn();
+  destroy = vi.fn();
+
+  constructor(readonly options: { document: Doc }) {
+    StubHocuspocusProvider.instances.push(this);
+  }
+}
+
+/** A tiptap extension records what the editor configured it with. */
+function stubExtension(name: string) {
+  const calls: Record<string, unknown>[] = [];
+  return {
+    calls,
+    default: {
+      configure(options: Record<string, unknown>) {
+        calls.push(options);
+        return { name, options };
+      },
+    },
+  };
+}
+
+/**
+ * Only the members the collaborative editor calls. yjs is the real package,
+ * because the provider and the editor must agree on one document.
+ */
+function collaborationStubs() {
+  const starterKit = stubExtension("starterKit");
+  const collaboration = stubExtension("collaboration");
+  const collaborationCaret = stubExtension("collaborationCaret");
+  const editorOptions: Record<string, unknown>[] = [];
+  const editor = {
+    setEditable: vi.fn(),
+    isEmpty: true,
+    commands: { setContent: vi.fn() },
+  };
+
+  const peers = {
+    react: {
+      useEditor: (options: Record<string, unknown>) => {
+        editorOptions.push(options);
+        return editor;
+      },
+      EditorContent: () => <div data-testid="editor-content" />,
+    },
+    starterKit,
+    collaboration,
+    collaborationCaret,
+    hocuspocus: { HocuspocusProvider: StubHocuspocusProvider },
+    yjs: { Doc },
+  } as unknown as EditorPeers.CollaborationPeers;
+
+  return { peers, starterKit, collaboration, collaborationCaret, editorOptions, editor };
+}
+
+function renderCollaborativeEditor(stubs: ReturnType<typeof collaborationStubs>) {
+  const EditorProvider = createEditorProvider(stubs.peers);
+  const TiptapEditor = createTiptapEditor(stubs.peers);
+  return render(
+    <EditorProvider
+      websocketUrl="wss://collab.example/ws"
+      documentName="doc:readme"
+      token="jwt"
+      user={{ name: "Ada" }}
+    >
+      <TiptapEditor />
+    </EditorProvider>,
+  );
+}
+
+afterEach(() => {
+  StubHocuspocusProvider.instances = [];
+  vi.doUnmock("./editor-peers");
+  vi.resetModules();
+});
+
+describe("createTiptapEditor", () => {
+  it("renders the editor surface from the loaded namespaces", () => {
+    renderCollaborativeEditor(collaborationStubs());
+
+    expect(screen.getByTestId("editor-content")).toBeInTheDocument();
+    expect(screen.getByText("Connecting...")).toBeInTheDocument();
+  });
+
+  it("gives Collaboration the document fragment the provider shares", () => {
+    const stubs = collaborationStubs();
+    renderCollaborativeEditor(stubs);
+
+    const [provider] = StubHocuspocusProvider.instances;
+    // The extensions rebuild once the transport arrives, so read the last
+    // configuration: the transport and the editor must bind to one Y.Doc, or
+    // remote edits never reach the surface.
+    expect(stubs.collaboration.calls.at(-1)?.fragment).toBe(
+      provider.options.document.getXmlFragment("prosemirror"),
+    );
+  });
+
+  it("gives CollaborationCaret the provider and a named user", () => {
+    const stubs = collaborationStubs();
+    renderCollaborativeEditor(stubs);
+
+    const [provider] = StubHocuspocusProvider.instances;
+    // The caret joins only once the provider carries awareness.
+    expect(stubs.collaborationCaret.calls).toHaveLength(1);
+    const [caretOptions] = stubs.collaborationCaret.calls;
+    expect(caretOptions.provider).toBe(provider);
+    // The stub awareness carries no local user yet, so the editor names the
+    // fallback rather than passing undefined into the caret renderer.
+    expect(caretOptions.user).toEqual({ name: "Anonymous", color: "#808080" });
+  });
+
+  it("passes every configured extension to the editor", () => {
+    const stubs = collaborationStubs();
+    renderCollaborativeEditor(stubs);
+
+    expect(stubs.starterKit.calls.at(-1)).toMatchObject({ history: false });
+    const options = stubs.editorOptions.at(-1);
+    expect(
+      (options?.extensions as { name: string }[]).map((one) => one.name),
+    ).toEqual(["starterKit", "collaboration", "collaborationCaret"]);
+  });
+});
+
+describe("TiptapEditor", () => {
+  it("holds a placeholder while the peers are still loading", async () => {
+    let releasePeers: (() => void) | null = null;
+    const gate = new Promise<void>((resolve) => {
+      releasePeers = resolve;
+    });
+    const stubs = collaborationStubs();
+    vi.resetModules();
+    vi.doMock("./editor-peers", async () => ({
+      ...(await vi.importActual<typeof EditorPeers>("./editor-peers")),
+      loadCollaborationPeers: async () => {
+        await gate;
+        return stubs.peers;
+      },
+    }));
+    const { TiptapEditor } = await import("./tiptap-editor");
+    // Both modules come from the reset graph, so the provider and the editor
+    // share one EditorContext. A provider built from the loaded peers
+    // directly, because the exported EditorProvider waits on the same gate and
+    // would render nothing at all.
+    const freshProvider = await import("./editor-provider");
+    const ResolvedProvider = freshProvider.createEditorProvider(stubs.peers);
+
+    render(
+      <ResolvedProvider
+        websocketUrl="wss://collab.example/ws"
+        documentName="doc:readme"
+        token="jwt"
+        user={{ name: "Ada" }}
+      >
+        <TiptapEditor />
+      </ResolvedProvider>,
+    );
+
+    expect(screen.getByText("Loading editor…")).toBeInTheDocument();
+    expect(screen.queryByTestId("editor-content")).toBeNull();
+
+    releasePeers?.();
+
+    await waitFor(() => {
+      expect(screen.getByTestId("editor-content")).toBeInTheDocument();
+    });
+    expect(screen.queryByText("Loading editor…")).toBeNull();
+  });
+
+  it("fails with the install list when the collaboration peers cannot be loaded", async () => {
+    const missing =
+      "@tangle-network/ui/editor needs its optional collaboration peers. Install yjs.";
+    vi.resetModules();
+    vi.doMock("./editor-peers", async () => {
+      const actual = await vi.importActual<typeof EditorPeers>("./editor-peers");
+      return {
+        ...actual,
+        loadCollaborationPeers: async () => {
+          throw new actual.MissingEditorPeersError(missing);
+        },
+      };
+    });
+    const { TiptapEditor } = await import("./tiptap-editor");
+
+    // The wrapper reaches its loader before it reads the editor context, so
+    // the install list surfaces without a provider around it.
+    render(
+      <ErrorTrap>
+        <TiptapEditor />
+      </ErrorTrap>,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText(missing)).toBeInTheDocument();
+    });
+  });
+});