@gogitcms/design-system 0.15.0-next.3

package/src/__tests__/ContentBrowser.collab.test.tsx

@@ -0,0 +1,322 @@
+// A collaborator's edit has to reach everything a local edit reaches.
+//
+// The controls bind straight to the CRDT, so a peer's change always *rendered*
+// correctly — and told the host nothing. Two things depended on being told: the
+// draft channel that feeds the preview (so a preview only ever rebuilt for
+// whoever typed) and the value map a save serializes (so the next save wrote the
+// field back as it was before the peer touched it, losing their work with both
+// screens showing the newer text).
+
+import React from "react";
+import { act, fireEvent, render, screen } from "@testing-library/react";
+import { ThemeProvider } from "../ThemeProvider";
+import {
+  ContentBrowser,
+  type CmsEntry,
+  type CmsNavSection,
+  type CollabApi,
+  type CollabRegister,
+  type CollabText,
+  type OpenTab,
+} from "../components/ContentBrowser";
+import { readDraft, refreshDrafts } from "../components/documentDrafts";
+
+jest.mock("../ThemeProvider", () => {
+  const actual = jest.requireActual("../ThemeProvider");
+  return { ...actual, useResponsive: () => ({ width: 1300, height: 900, isDesktop: true, isMobile: false }) };
+});
+
+const wrap = (ui: React.ReactElement) => <ThemeProvider>{ui}</ThemeProvider>;
+
+/**
+ * An in-memory stand-in for @gogitcms/realtime's DocCollab.
+ *
+ * `remote` is the whole point: it writes a value the way a peer's update does —
+ * into the shared store, notifying subscribers, without going near the control's
+ * own onChange. That is exactly the path that used to end at the rendered input.
+ */
+function fakeCollab(seed: Record<string, string> = {}) {
+  const values = new Map<string, unknown>(Object.entries(seed));
+  const listeners = new Map<string, Set<() => void>>();
+  // Every snapshot getter below has to return a stable value for an unchanged
+  // store — useSyncExternalStore re-renders until it does. The real DocCollab
+  // memoizes its bindings per path and hands out one frozen empty peer list;
+  // a fake that allocates per call loops instead of testing anything.
+  const noPeers: never[] = [];
+
+  const notify = (path: string) => listeners.get(path)?.forEach((l) => l());
+  const listen = (path: string, cb: () => void) => {
+    let set = listeners.get(path);
+    if (!set) listeners.set(path, (set = new Set()));
+    set.add(cb);
+    return () => void set!.delete(cb);
+  };
+
+  const textCache = new Map<string, CollabText>();
+  const text = (path: string): CollabText => {
+    let binding = textCache.get(path);
+    if (!binding) {
+      textCache.set(path, (binding = {
+        get: () => String(values.get(path) ?? ""),
+        set: (next) => {
+          values.set(path, next);
+          notify(path);
+        },
+        peers: () => noPeers,
+        subscribe: (cb) => listen(path, cb),
+      }));
+    }
+    return binding;
+  };
+
+  const regCache = new Map<string, CollabRegister>();
+  const register = (path: string): CollabRegister => {
+    let binding = regCache.get(path);
+    if (!binding) {
+      regCache.set(path, (binding = {
+        get: () => values.get(path),
+        set: (next) => {
+          values.set(path, next);
+          notify(path);
+        },
+        subscribe: (cb) => listen(path, cb),
+      }));
+    }
+    return binding;
+  };
+
+  const api: CollabApi = {
+    text,
+    register,
+    setFocus: () => {},
+    peersAt: () => noPeers,
+    peersUnder: () => noPeers,
+    participants: () => noPeers,
+    awarenessVersion: () => 0,
+    subscribeAwareness: () => () => {},
+    ydoc: {},
+    awareness: {},
+  };
+
+  return {
+    collab: api,
+    /** One peer's change, or several in a single transaction. */
+    remote(next: Record<string, unknown>) {
+      act(() => {
+        for (const [path, value] of Object.entries(next)) {
+          values.set(path, value);
+          notify(path);
+        }
+      });
+    },
+  };
+}
+
+const sections: CmsNavSection[] = [
+  { title: "Content", items: [{ key: "posts", label: "Posts", icon: "newspaper" }] },
+];
+
+const base = {
+  workspace: { name: "acme/site", initials: "AC", branch: "main", changed: 0 },
+  sections,
+  activeNavKey: "posts",
+  onSelectNav: () => {},
+  entries: [{ id: "a", path: "posts/a.md", title: "Alpha", body: "", fields: [] } as CmsEntry],
+  userInitials: "ED",
+} as const;
+
+function docWith(collab: CollabApi, extra: CmsEntry["fields"] = []): CmsEntry {
+  return {
+    id: "a",
+    path: "posts/a.md",
+    title: "Alpha",
+    body: "hello",
+    collab,
+    fields: [
+      { name: "title", type: "string", label: "Title", value: "Alpha" },
+      ...(extra ?? []),
+      { name: "content", type: "string", source: "body", value: "hello" },
+    ],
+  };
+}
+
+describe("a collaborator's edit", () => {
+  beforeEach(() => jest.useFakeTimers());
+  afterEach(() => jest.useRealTimers());
+
+  it("reaches the draft channel, so every viewer's preview rebuilds", () => {
+    const { collab, remote } = fakeCollab({ title: "Alpha" });
+    const onEntryDraft = jest.fn();
+    render(
+      wrap(
+        <ContentBrowser
+          {...base}
+          openTabs={[{ id: "a", collection: "posts", entry: docWith(collab) } as OpenTab]}
+          activeTabId="a"
+          onEntryDraft={onEntryDraft}
+        />
+      )
+    );
+
+    // Mounting in sync says nothing: the host seeded its map from this document,
+    // and an edit event here would mark an untouched document unsaved.
+    act(() => void jest.advanceTimersByTime(500));
+    expect(onEntryDraft).not.toHaveBeenCalled();
+
+    remote({ title: "Alpha, from the other tab" });
+    act(() => void jest.advanceTimersByTime(500));
+
+    expect(onEntryDraft).toHaveBeenCalledTimes(1);
+    expect(onEntryDraft.mock.calls[0][0]).toEqual({
+      id: "a",
+      fields: { title: "Alpha, from the other tab" },
+      body: "hello",
+    });
+  });
+
+  it("is what the next save writes, rather than the value it replaced", async () => {
+    const { collab, remote } = fakeCollab({ title: "Alpha" });
+    const onSaveEntry = jest.fn();
+    render(
+      wrap(
+        <ContentBrowser
+          {...base}
+          openTabs={[{ id: "a", collection: "posts", entry: docWith(collab) } as OpenTab]}
+          activeTabId="a"
+          onSaveEntry={onSaveEntry}
+          onEntryDraft={jest.fn()}
+        />
+      )
+    );
+
+    remote({ title: "Alpha, from the other tab" });
+    act(() => void jest.advanceTimersByTime(500));
+
+    // Save enables once the document is dirty — which a peer's edit makes it,
+    // because the document has genuinely diverged from disk.
+    act(() => void fireEvent.click(screen.getByTestId("save-entry")));
+
+    expect(onSaveEntry).toHaveBeenCalledTimes(1);
+    expect(onSaveEntry.mock.calls[0][0].fields).toEqual({ title: "Alpha, from the other tab" });
+  });
+
+  it("survives arriving alongside others in one transaction", () => {
+    // Several fields in a single update — a peer pasting across a form, and what
+    // a document's first sync looks like. They re-render together and commit in
+    // one flush, so an edit that spread the map its own render closed over would
+    // keep the last field and drop the rest.
+    const { collab, remote } = fakeCollab({ title: "Alpha", subtitle: "Beta", author: "Cass" });
+    const onEntryDraft = jest.fn();
+    render(
+      wrap(
+        <ContentBrowser
+          {...base}
+          openTabs={[
+            {
+              id: "a",
+              collection: "posts",
+              entry: docWith(collab, [
+                { name: "subtitle", type: "string", label: "Subtitle", value: "Beta" },
+                { name: "author", type: "string", label: "Author", value: "Cass" },
+              ]),
+            } as OpenTab,
+          ]}
+          activeTabId="a"
+          onEntryDraft={onEntryDraft}
+        />
+      )
+    );
+
+    remote({ title: "one", subtitle: "two", author: "three" });
+    act(() => void jest.advanceTimersByTime(500));
+
+    const last = onEntryDraft.mock.calls[onEntryDraft.mock.calls.length - 1][0];
+    expect(last.fields).toEqual({ title: "one", subtitle: "two", author: "three" });
+  });
+
+  it("does not make a local keystroke arrive twice", () => {
+    // The mirror settles the value on its way out, so the CRDT echo of the
+    // user's own typing is not read back as somebody else's change.
+    const { collab } = fakeCollab({ title: "Alpha" });
+    const onEntryDraft = jest.fn();
+    render(
+      wrap(
+        <ContentBrowser
+          {...base}
+          openTabs={[{ id: "a", collection: "posts", entry: docWith(collab) } as OpenTab]}
+          activeTabId="a"
+          onEntryDraft={onEntryDraft}
+        />
+      )
+    );
+
+    const input = screen.getAllByRole("textbox")[0];
+    act(() => void fireEvent.change(input, { target: { value: "Alpha edited" } }));
+    act(() => void jest.advanceTimersByTime(500));
+
+    expect(onEntryDraft).toHaveBeenCalledTimes(1);
+    expect(onEntryDraft.mock.calls[0][0].fields).toEqual({ title: "Alpha edited" });
+  });
+});
+
+// A collaborative field is bound to the CRDT, and the CRDT is empty until the
+// provider's first sync arrives. So every field on the page changes shortly
+// after mount — from nothing to the value the server already had — and a save
+// state set by "something changed" reported an untouched document as unsaved
+// the moment it opened. The author had a Discard button and an unsaved badge
+// for work nobody had done.
+describe("the first sync of a document", () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+    localStorage.clear();
+    refreshDrafts();
+  });
+  afterEach(() => jest.useRealTimers());
+
+  it("leaves the document clean, because nothing has changed from what is saved", () => {
+    // Seeded empty: the room has not synced yet, which is what every load looks
+    // like for the moment before the socket answers.
+    const { collab, remote } = fakeCollab();
+    render(
+      wrap(
+        <ContentBrowser
+          {...base}
+          openTabs={[{ id: "a", collection: "posts", entry: docWith(collab) } as OpenTab]}
+          activeTabId="a"
+          onSaveEntry={jest.fn()}
+        />
+      )
+    );
+
+    // The sync lands, carrying the document the server already has.
+    remote({ title: "Alpha", content: "hello" });
+    act(() => void jest.advanceTimersByTime(1000));
+
+    expect(screen.queryByTestId("autosave-indicator")).not.toBeInTheDocument();
+    expect(screen.queryByTestId("discard-changes")).not.toBeInTheDocument();
+    expect(screen.getByTestId("save-entry")).toBeDisabled();
+    expect(readDraft("a")).toBeNull();
+  });
+
+  it("still leaves a peer's genuine edit dirty", () => {
+    // The guard is a value comparison, not a window of silence after mount: an
+    // edit that arrives in the same breath as the sync is still an edit.
+    const { collab, remote } = fakeCollab();
+    render(
+      wrap(
+        <ContentBrowser
+          {...base}
+          openTabs={[{ id: "a", collection: "posts", entry: docWith(collab) } as OpenTab]}
+          activeTabId="a"
+          onSaveEntry={jest.fn()}
+        />
+      )
+    );
+
+    remote({ title: "Alpha, from the other tab", content: "hello" });
+    act(() => void jest.advanceTimersByTime(1000));
+
+    expect(screen.getByTestId("autosave-indicator")).toHaveTextContent("Unsaved changes");
+    expect(screen.getByTestId("save-entry")).not.toBeDisabled();
+  });
+});

package/src/__tests__/ContentBrowser.collabsync.test.tsx

@@ -0,0 +1,264 @@
+// The window between a field mounting and the shared document arriving.
+//
+// Every collab-bound control read its binding in that window and got nothing —
+// not because the field was empty but because the room had yet to answer — so a
+// saved document rendered blank for as long as the handshake took. And an edit
+// made in that moment went into the doc *ahead* of the server's seeded value,
+// where a Y.Text does not replace but merges: choosing "draft" in a field that
+// turns out to hold "shipped" left "shippeddraft" behind in the document.
+//
+// The fake below is built to catch exactly that second one — its `sync` inserts
+// the seed alongside whatever the client has written, the way two concurrent
+// inserts at position 0 actually converge.
+
+import React from "react";
+import { act, fireEvent, render, screen } from "@testing-library/react";
+import { ThemeProvider } from "../ThemeProvider";
+import {
+  ContentBrowser,
+  type CmsEntry,
+  type CmsNavSection,
+  type CollabApi,
+  type CollabRegister,
+  type CollabText,
+  type EntryField,
+  type OpenTab,
+} from "../components/ContentBrowser";
+import { refreshDrafts } from "../components/documentDrafts";
+
+jest.mock("../ThemeProvider", () => {
+  const actual = jest.requireActual("../ThemeProvider");
+  return { ...actual, useResponsive: () => ({ width: 1300, height: 900, isDesktop: true, isMobile: false }) };
+});
+
+const wrap = (ui: React.ReactElement) => <ThemeProvider>{ui}</ThemeProvider>;
+
+function fakeCollab() {
+  const texts = new Map<string, string>();
+  const regs = new Map<string, unknown>();
+  const listeners = new Map<string, Set<() => void>>();
+  const syncListeners = new Set<() => void>();
+  let synced = false;
+  const noPeers: never[] = [];
+
+  const notify = (path: string) => listeners.get(path)?.forEach((l) => l());
+  const listen = (path: string, cb: () => void) => {
+    let set = listeners.get(path);
+    if (!set) listeners.set(path, (set = new Set()));
+    set.add(cb);
+    return () => void set!.delete(cb);
+  };
+
+  const textCache = new Map<string, CollabText>();
+  const text = (path: string): CollabText => {
+    let binding = textCache.get(path);
+    if (!binding) {
+      textCache.set(path, (binding = {
+        get: () => texts.get(path) ?? "",
+        set: (next) => { texts.set(path, next); notify(path); },
+        peers: () => noPeers,
+        subscribe: (cb) => listen(path, cb),
+      }));
+    }
+    return binding;
+  };
+  const regCache = new Map<string, CollabRegister>();
+  const register = (path: string): CollabRegister => {
+    let binding = regCache.get(path);
+    if (!binding) {
+      regCache.set(path, (binding = {
+        get: () => regs.get(path),
+        set: (next) => { regs.set(path, next); notify(path); },
+        subscribe: (cb) => listen(path, cb),
+      }));
+    }
+    return binding;
+  };
+
+  const collab: CollabApi = {
+    text,
+    register,
+    setFocus: () => {},
+    peersAt: () => noPeers,
+    peersUnder: () => noPeers,
+    participants: () => noPeers,
+    awarenessVersion: () => 0,
+    subscribeAwareness: () => () => {},
+    synced: () => synced,
+    subscribeSynced: (cb) => {
+      syncListeners.add(cb);
+      return () => void syncListeners.delete(cb);
+    },
+    ydoc: {},
+    awareness: {},
+  };
+
+  return {
+    collab,
+    /**
+     * The server's seeded state arriving. A seeded string is *inserted*, not
+     * assigned: anything the client wrote first survives next to it, which is
+     * the merge that produced the corrupted values.
+     */
+    sync(seed: { text?: Record<string, string>; reg?: Record<string, unknown> } = {}) {
+      act(() => {
+        synced = true;
+        for (const [p, v] of Object.entries(seed.text ?? {})) {
+          texts.set(p, v + (texts.get(p) ?? ""));
+          notify(p);
+        }
+        for (const [p, v] of Object.entries(seed.reg ?? {})) {
+          if (regs.get(p) === undefined) regs.set(p, v);
+          notify(p);
+        }
+        syncListeners.forEach((cb) => cb());
+      });
+    },
+    doc: {
+      text: (path: string) => texts.get(path),
+      reg: (path: string) => regs.get(path),
+    },
+  };
+}
+
+const sections: CmsNavSection[] = [
+  { title: "Content", items: [{ key: "posts", label: "Posts", icon: "newspaper" }] },
+];
+
+const base = {
+  workspace: { name: "acme/site", initials: "AC", branch: "main", changed: 0 },
+  sections,
+  activeNavKey: "posts",
+  onSelectNav: () => {},
+  entries: [{ id: "a", path: "posts/a.md", title: "Alpha", body: "", fields: [] } as CmsEntry],
+  userInitials: "ED",
+} as const;
+
+function renderDoc(fields: EntryField[], collab: CollabApi) {
+  const entry: CmsEntry = { id: "a", path: "posts/a.md", title: "Alpha", body: "", collab, fields };
+  return render(
+    wrap(
+      <ContentBrowser
+        {...base}
+        openTabs={[{ id: "a", collection: "posts", entry } as OpenTab]}
+        activeTabId="a"
+        onSaveEntry={jest.fn()}
+      />
+    )
+  );
+}
+
+// An edit in one test is a stored draft the next one would open the document
+// with — every case here starts from the saved document.
+beforeEach(() => {
+  localStorage.clear();
+  refreshDrafts();
+});
+
+const field = (over: Partial<EntryField>): EntryField =>
+  ({ name: "f", label: "F", type: "string", value: "", ...over }) as EntryField;
+
+describe("an edit made before the room has synced", () => {
+  it("replaces the seeded value rather than merging into it", () => {
+    const { collab, sync, doc } = fakeCollab();
+    renderDoc(
+      [field({ name: "status", type: "string", component: "select", enumValues: ["draft", "shipped"], value: "shipped" })],
+      collab
+    );
+
+    // The author changes their mind before the socket has finished its
+    // handshake. Nothing is written yet — there is no document to write to.
+    fireEvent.change(screen.getByTestId("select-control"), { target: { value: "draft" } });
+    expect(doc.text("status")).toBeUndefined();
+    expect((screen.getByTestId("select-control") as HTMLSelectElement).value).toBe("draft");
+
+    // The seed lands and the held edit goes through on top of it.
+    sync({ text: { status: "shipped" } });
+    expect(doc.text("status")).toBe("draft");
+    expect((screen.getByTestId("select-control") as HTMLSelectElement).value).toBe("draft");
+  });
+
+  it("does the same for a text field, which is where it corrupted the value", () => {
+    const { collab, sync, doc } = fakeCollab();
+    renderDoc([field({ name: "title", type: "string", value: "Alpha" })], collab);
+
+    const input = screen.getByDisplayValue("Alpha");
+    fireEvent.change(input, { target: { value: "Beta" } });
+    expect(doc.text("title")).toBeUndefined();
+
+    sync({ text: { title: "Alpha" } });
+    // Not "AlphaBeta".
+    expect(doc.text("title")).toBe("Beta");
+    expect(screen.getByDisplayValue("Beta")).toBeInTheDocument();
+  });
+});
+
+describe("before the room has synced, a field shows the document's own value", () => {
+  it("for a text input", () => {
+    const { collab } = fakeCollab();
+    renderDoc([field({ name: "title", type: "string", value: "Alpha" })], collab);
+    expect(screen.getByDisplayValue("Alpha")).toBeInTheDocument();
+  });
+
+  it("for a textarea", () => {
+    const { collab } = fakeCollab();
+    renderDoc([field({ name: "summary", type: "string", component: "textarea", value: "In short." })], collab);
+    expect(screen.getByDisplayValue("In short.")).toBeInTheDocument();
+  });
+
+  it("for a switch", () => {
+    const { collab } = fakeCollab();
+    renderDoc([field({ name: "featured", type: "boolean", component: "switch", value: true })], collab);
+    expect(screen.getByRole("switch")).toHaveAttribute("aria-checked", "true");
+  });
+
+  it("for a stepper", () => {
+    const { collab } = fakeCollab();
+    renderDoc([field({ name: "count", type: "integer", component: "stepper", value: 7 })], collab);
+    expect(screen.getByDisplayValue("7")).toBeInTheDocument();
+  });
+
+  it("for a date", () => {
+    const { collab } = fakeCollab();
+    renderDoc([field({ name: "publishedAt", type: "string", component: "date", value: "2026-03-04" })], collab);
+    expect(screen.getByTestId("date-control")).toHaveValue("2026-03-04");
+  });
+
+  it("for a list, and never writes one into the room itself", () => {
+    const { collab, sync, doc } = fakeCollab();
+    renderDoc([field({ name: "tags", type: "array", component: "list", of: "string", value: ["a", "b"] })], collab);
+
+    expect(screen.getByTestId("list-remove-1")).toBeInTheDocument();
+    expect(doc.reg("tags")).toBeUndefined();
+
+    // Seeding a list is the server's job (collab's seedDoc). A client that did
+    // it wrote the empty list it had before its values loaded, and that empty
+    // list outlived the session in the room's snapshot.
+    sync();
+    expect(doc.reg("tags")).toBeUndefined();
+    expect(screen.getByTestId("list-remove-1")).toBeInTheDocument();
+  });
+});
+
+describe("once the room has arrived", () => {
+  it("a peer's value wins over the document's, including an emptied one", () => {
+    const { collab, sync } = fakeCollab();
+    renderDoc([field({ name: "title", type: "string", value: "Alpha" })], collab);
+    sync({ text: { title: "Alpha" } });
+
+    act(() => collab.text("title").set("Alpha, from the other tab"));
+    expect(screen.getByDisplayValue("Alpha, from the other tab")).toBeInTheDocument();
+
+    act(() => collab.text("title").set(""));
+    expect(screen.queryByDisplayValue("Alpha")).not.toBeInTheDocument();
+  });
+
+  it("an edit goes straight to the document again", () => {
+    const { collab, sync, doc } = fakeCollab();
+    renderDoc([field({ name: "title", type: "string", value: "Alpha" })], collab);
+    sync({ text: { title: "Alpha" } });
+
+    fireEvent.change(screen.getByDisplayValue("Alpha"), { target: { value: "Beta" } });
+    expect(doc.text("title")).toBe("Beta");
+  });
+});

package/src/__tests__/ContentBrowser.contentslot.test.tsx

@@ -0,0 +1,53 @@
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import { Text } from "../components/Text";
+import { ThemeProvider } from "../ThemeProvider";
+import { ContentBrowser, type CmsEntry, type CmsNavSection } from "../components/ContentBrowser";
+
+// Force the desktop layout (jsdom reports width 0 → mobile otherwise).
+jest.mock("../ThemeProvider", () => {
+  const actual = jest.requireActual("../ThemeProvider");
+  return { ...actual, useResponsive: () => ({ width: 1300, height: 900, isDesktop: true, isMobile: false }) };
+});
+
+const wrap = (ui: React.ReactElement) => <ThemeProvider>{ui}</ThemeProvider>;
+
+const sections: CmsNavSection[] = [
+  { title: "Content", items: [{ key: "posts", label: "Posts", icon: "newspaper" }] },
+  { title: "Plugins", items: [{ key: "plugin:hello/hello", label: "Hello plugin", icon: "braces" }] },
+];
+const entries: CmsEntry[] = [{ id: "a", path: "posts/a.md", title: "Alpha", body: "" }];
+
+const base = {
+  workspace: { name: "acme/site", initials: "AC", branch: "main", changed: 0 },
+  sections,
+  activeNavKey: "plugin:hello/hello",
+  onSelectNav: () => {},
+  entries,
+  userInitials: "ED",
+} as const;
+
+test("contentSlot replaces the list/detail panes and keeps the sidebar", () => {
+  render(
+    wrap(
+      <ContentBrowser
+        {...base}
+        contentSlot={<Text testID="plugin-screen">Hello from a plugin</Text>}
+      />
+    )
+  );
+  // The plugin pane renders the slot…
+  expect(screen.getByTestId("pane-plugin")).toBeInTheDocument();
+  expect(screen.getByTestId("plugin-screen")).toBeInTheDocument();
+  // …the sidebar (with the plugin link) stays…
+  expect(screen.getByText("Hello plugin")).toBeInTheDocument();
+  expect(screen.getByText("Posts")).toBeInTheDocument();
+  // …and the entry list/detail panes are gone.
+  expect(screen.queryByTestId("pane-entries")).not.toBeInTheDocument();
+});
+
+test("without contentSlot the normal panes render", () => {
+  render(wrap(<ContentBrowser {...base} activeNavKey="posts" />));
+  expect(screen.queryByTestId("pane-plugin")).not.toBeInTheDocument();
+  expect(screen.getByTestId("pane-entries")).toBeInTheDocument();
+});