@gogitcms/design-system 0.16.0-next.1 → 0.16.0-next.11

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

@@ -0,0 +1,433 @@
+// Restoring a field from a past version, in a live session.
+//
+// In collab the shared document is the source of truth: every collab control
+// prefers its binding to the value the host passes in. So a restore written only
+// to local form state was displayed for one frame and then overwritten by the
+// CRDT's unchanged value — the field visibly snapped back, and nothing about the
+// restore reached the room or the peers in it.
+
+import React from "react";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { ThemeProvider } from "../ThemeProvider";
+import {
+  ContentBrowser,
+  type CmsEntry,
+  type CmsNavSection,
+  type CollabApi,
+  type CollabRegister,
+  type CollabText,
+  type FieldSlotArgs,
+} from "../components/ContentBrowser";
+import type { DocumentChange } from "../components/ChangeDetail";
+import type { HistoryApi } from "../history";
+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>;
+
+/**
+ * An in-memory stand-in for @gogitcms/realtime's DocCollab, seeded with what the
+ * room already holds. Bindings are memoized per path and the empty peer list is
+ * shared, because useSyncExternalStore re-renders until a snapshot is stable.
+ */
+function fakeCollab(seed: Record<string, unknown> = {}) {
+  const values = new Map<string, unknown>(Object.entries(seed));
+  const listeners = new Map<string, Set<() => void>>();
+  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 b = textCache.get(path);
+    if (!b) {
+      textCache.set(path, (b = {
+        get: () => String(values.get(path) ?? ""),
+        set: (next) => { values.set(path, next); notify(path); },
+        peers: () => noPeers,
+        subscribe: (cb) => listen(path, cb),
+      }));
+    }
+    return b;
+  };
+
+  const regCache = new Map<string, CollabRegister>();
+  const register = (path: string): CollabRegister => {
+    let b = regCache.get(path);
+    if (!b) {
+      regCache.set(path, (b = {
+        get: () => values.get(path),
+        set: (next) => { values.set(path, next); notify(path); },
+        subscribe: (cb) => listen(path, cb),
+      }));
+    }
+    return b;
+  };
+
+  const collab: CollabApi = {
+    text, register,
+    setFocus: () => {},
+    peersAt: () => noPeers,
+    peersUnder: () => noPeers,
+    participants: () => noPeers,
+    awarenessVersion: () => 0,
+    subscribeAwareness: () => () => {},
+    ydoc: {},
+    awareness: {},
+  };
+  return { collab, room: values };
+}
+
+// A restore commits, and committing records a draft. Without clearing them each
+// test seeds its form from the PREVIOUS test's restore — which reads as a field
+// that was already rolled back and so has nothing left to write.
+beforeEach(() => {
+  localStorage.clear();
+  refreshDrafts();
+});
+
+const sections: CmsNavSection[] = [
+  { title: "Content", items: [{ key: "posts", label: "Posts", icon: "newspaper" }] },
+];
+
+const version = {
+  sha: "3b7de1098877",
+  shortSha: "3b7de10",
+  message: "Draft the post",
+  authorName: "Ada",
+  authoredAt: "2026-02-01T12:00:00Z",
+  url: "",
+  filesChanged: 1,
+};
+
+function makeApi(detail: DocumentChange): HistoryApi {
+  return { list: jest.fn(async () => [version]), get: jest.fn(async () => detail) };
+}
+
+async function openHistory(entry: CmsEntry, detail: DocumentChange, renderField?: (a: FieldSlotArgs) => React.ReactNode) {
+  render(
+    wrap(
+      <ContentBrowser
+        workspace={{ name: "acme/site", initials: "AC", branch: "main", changed: 0 }}
+        sections={sections}
+        activeNavKey="posts"
+        onSelectNav={jest.fn()}
+        entries={[entry]}
+        selectedEntryId={entry.id}
+        onSelectEntry={jest.fn()}
+        userInitials="ED"
+        onSaveEntry={jest.fn(async () => {})}
+        renderField={renderField}
+        history={makeApi(detail)}
+      />,
+    ),
+  );
+  fireEvent.click(screen.getByTestId("document-history-toggle"));
+  await screen.findByTestId("change-detail");
+}
+
+// The regression, end to end: the restored value has to be what the control
+// shows once the CRDT has had its say — not for one frame before it.
+test("a restored string lands in the room, and stays on screen", async () => {
+  const { collab, room } = fakeCollab({ status: "published" });
+  const entry: CmsEntry = {
+    id: "a", path: "posts/a.md", title: "Alpha", body: "", collab,
+    fields: [{ name: "status", type: "string", label: "Status", value: "published" }],
+  };
+  await openHistory(entry, {
+    path: "posts/a.md", status: "M", label: "Alpha", added: 1, removed: 1,
+    fields: [{ name: "status", kind: "changed", before: "draft", after: "published" }],
+  });
+
+  fireEvent.click(screen.getByTestId("restore-field-status"));
+  fireEvent.click(screen.getByTestId("restore-apply"));
+
+  // Written where a string lives — the Y.Text, which is what the control reads.
+  expect(room.get("status")).toBe("draft");
+  await waitFor(() => expect(screen.getByDisplayValue("draft")).toBeInTheDocument());
+});
+
+// Which shared type a value lives in follows its shape, mirroring what the
+// server seeds: a string is a text, everything else is a register. Writing to
+// the wrong one is not an error anyone sees — it is a value that lands where
+// nothing is looking.
+test("non-string values restore into the register, not the text", async () => {
+  const { collab, room } = fakeCollab({ weight: 20, tags: ["b"], live: true });
+  const entry: CmsEntry = {
+    id: "a", path: "posts/a.md", title: "Alpha", body: "", collab,
+    fields: [
+      { name: "weight", type: "integer", value: 20 },
+      { name: "tags", type: "array", of: "string", value: ["b"] },
+      { name: "live", type: "boolean", value: true },
+    ],
+  };
+  await openHistory(entry, {
+    path: "posts/a.md", status: "M", label: "Alpha", added: 1, removed: 1,
+    fields: [
+      { name: "weight", kind: "changed", before: 10, after: 20 },
+      { name: "tags", kind: "changed", before: ["a"], after: ["b"] },
+      { name: "live", kind: "changed", before: false, after: true },
+    ],
+  });
+
+  fireEvent.click(screen.getByTestId("restore-field-weight"));
+  fireEvent.click(screen.getByTestId("restore-field-tags"));
+  fireEvent.click(screen.getByTestId("restore-field-live"));
+  fireEvent.click(screen.getByTestId("restore-apply"));
+
+  expect(room.get("weight")).toBe(10);
+  expect(room.get("tags")).toEqual(["a"]);
+  expect(room.get("live")).toBe(false);
+});
+
+// A group's children are addressed by dotted path in the room, exactly as the
+// server writes them — a group restored as one object still has to reach the
+// individual leaves its controls read.
+test("a restored group writes its children at their dotted paths", async () => {
+  const { collab, room } = fakeCollab({ "seo.title": "New", "seo.weight": 2 });
+  const entry: CmsEntry = {
+    id: "a", path: "posts/a.md", title: "Alpha", body: "", collab,
+    fields: [{
+      name: "seo", type: "object", component: "group",
+      fields: [
+        { name: "title", type: "string", value: "New" },
+        { name: "weight", type: "integer", value: 2 },
+      ],
+      value: { title: "New", weight: 2 },
+    }],
+  };
+  await openHistory(entry, {
+    path: "posts/a.md", status: "M", label: "Alpha", added: 1, removed: 1,
+    fields: [{
+      name: "seo", kind: "changed",
+      before: { title: "Old", weight: 1 },
+      after: { title: "New", weight: 2 },
+    }],
+  });
+
+  fireEvent.click(screen.getByTestId("restore-field-seo"));
+  fireEvent.click(screen.getByTestId("restore-apply"));
+
+  expect(room.get("seo.title")).toBe("Old");
+  expect(room.get("seo.weight")).toBe(1);
+});
+
+// Only the new value's leaves say what to write; only the old value's leaves say
+// what to CLEAR. A group that loses a child would otherwise keep a shared value
+// nobody can see any more.
+test("leaves the restored version does not have are cleared in the room", async () => {
+  const { collab, room } = fakeCollab({ "seo.title": "New", "seo.blurb": "extra", subtitle: "here" });
+  const entry: CmsEntry = {
+    id: "a", path: "posts/a.md", title: "Alpha", body: "", collab,
+    fields: [
+      { name: "seo", type: "object", component: "group", fields: [{ name: "title", type: "string", value: "New" }], value: { title: "New", blurb: "extra" } },
+      { name: "subtitle", type: "string", value: "here" },
+    ],
+  };
+  await openHistory(entry, {
+    path: "posts/a.md", status: "M", label: "Alpha", added: 1, removed: 1,
+    fields: [
+      // The old version's group had no `blurb` at all…
+      { name: "seo", kind: "changed", before: { title: "Old" }, after: { title: "New", blurb: "extra" } },
+      // …and had no `subtitle` field whatsoever.
+      { name: "subtitle", kind: "added", before: undefined, after: "here" },
+    ],
+  });
+
+  fireEvent.click(screen.getByTestId("restore-field-seo"));
+  fireEvent.click(screen.getByTestId("restore-field-subtitle"));
+  fireEvent.click(screen.getByTestId("restore-apply"));
+
+  expect(room.get("seo.title")).toBe("Old");
+  // Emptied rather than left holding a value the restored version never had.
+  expect(room.get("seo.blurb")).toBe("");
+  expect(room.get("subtitle")).toBe("");
+});
+
+// The body is a ProseMirror fragment, not a text binding: in a session it
+// ignores the `value` it is handed and mirrors the shared fragment, so "the
+// value changed" is not something it can observe. It is told instead.
+test("restoring the body signals the body editor to replace its content", async () => {
+  const { collab } = fakeCollab({});
+  const seen: FieldSlotArgs[] = [];
+  const renderField = (args: FieldSlotArgs) => {
+    if (args.field.source !== "body") return undefined;
+    seen.push(args);
+    return <div data-testid="body-slot" />;
+  };
+  const entry: CmsEntry = {
+    id: "a", path: "posts/a.md", title: "Alpha", body: "Now.", collab,
+    fields: [
+      { name: "status", type: "string", value: "published" },
+      { name: "content", type: "string", component: "body", source: "body", value: "Now." },
+    ],
+  };
+  await openHistory(entry, {
+    path: "posts/a.md", status: "M", label: "Alpha", added: 1, removed: 1,
+    fields: [{ name: "status", kind: "changed", before: "draft", after: "published" }],
+    bodyBefore: "Then.", bodyAfter: "Now.",
+  }, renderField);
+
+  const before = seen[seen.length - 1].resetNonce;
+
+  fireEvent.click(screen.getByTestId("restore-field-body"));
+  fireEvent.click(screen.getByTestId("restore-apply"));
+
+  await waitFor(() => {
+    const last = seen[seen.length - 1];
+    expect(last.value).toBe("Then.");
+    expect(last.resetNonce).not.toBe(before);
+  });
+});
+
+// Restoring some other field must not make the body editor replace itself — a
+// peer could be mid-sentence in it.
+test("restoring another field leaves the body editor's signal alone", async () => {
+  const { collab } = fakeCollab({ status: "published" });
+  const seen: FieldSlotArgs[] = [];
+  const renderField = (args: FieldSlotArgs) => {
+    if (args.field.source !== "body") return undefined;
+    seen.push(args);
+    return <div data-testid="body-slot" />;
+  };
+  const entry: CmsEntry = {
+    id: "a", path: "posts/a.md", title: "Alpha", body: "Now.", collab,
+    fields: [
+      { name: "status", type: "string", value: "published" },
+      { name: "content", type: "string", component: "body", source: "body", value: "Now." },
+    ],
+  };
+  await openHistory(entry, {
+    path: "posts/a.md", status: "M", label: "Alpha", added: 1, removed: 1,
+    fields: [{ name: "status", kind: "changed", before: "draft", after: "published" }],
+    bodyBefore: "Then.", bodyAfter: "Now.",
+  }, renderField);
+
+  const before = seen[seen.length - 1].resetNonce;
+
+  fireEvent.click(screen.getByTestId("restore-field-status"));
+  fireEvent.click(screen.getByTestId("restore-apply"));
+
+  await waitFor(() => expect(screen.getByTestId("column-scroll")).toBeInTheDocument());
+  expect(seen[seen.length - 1].resetNonce).toBe(before);
+});
+
+// ---- discard, in a live session -------------------------------------------
+//
+// Discard has the same shape of problem as a restore, and had the same bug: it
+// reverted the local form and left the discarded work sitting in the CRDT,
+// where the control read it straight back. In a session a discard is a change
+// to the ROOM — the unsaved work is the collective state every client is
+// looking at, not one screen's private draft.
+
+async function openEditor(entry: CmsEntry, renderField?: (a: FieldSlotArgs) => React.ReactNode) {
+  render(
+    wrap(
+      <ContentBrowser
+        workspace={{ name: "acme/site", initials: "AC", branch: "main", changed: 0 }}
+        sections={sections}
+        activeNavKey="posts"
+        onSelectNav={jest.fn()}
+        entries={[entry]}
+        selectedEntryId={entry.id}
+        onSelectEntry={jest.fn()}
+        userInitials="ED"
+        onSaveEntry={jest.fn(async () => {})}
+        renderField={renderField}
+      />,
+    ),
+  );
+  await screen.findByTestId("column-scroll");
+}
+
+test("discarding puts the saved value back in the room, not just on screen", async () => {
+  const { collab, room } = fakeCollab({ status: "published" });
+  const entry: CmsEntry = {
+    id: "a", path: "posts/a.md", title: "Alpha", body: "", collab,
+    fields: [{ name: "status", type: "string", label: "Status", value: "published" }],
+  };
+  await openEditor(entry);
+
+  fireEvent.change(screen.getByDisplayValue("published"), { target: { value: "scratch" } });
+  await waitFor(() => expect(room.get("status")).toBe("scratch"));
+
+  fireEvent.click(await screen.findByTestId("discard-changes"));
+
+  // The room is back to the document, so the control has nothing to read back.
+  expect(room.get("status")).toBe("published");
+  await waitFor(() => expect(screen.getByDisplayValue("published")).toBeInTheDocument());
+});
+
+// The body is a fragment the editor mirrors, so a discard has to tell it rather
+// than write a binding it does not read.
+test("discarding signals the body editor to rebuild from the saved document", async () => {
+  const { collab } = fakeCollab({ status: "published" });
+  const seen: FieldSlotArgs[] = [];
+  const renderField = (args: FieldSlotArgs) => {
+    if (args.field.source !== "body") return undefined;
+    seen.push(args);
+    return <div data-testid="body-slot" />;
+  };
+  const entry: CmsEntry = {
+    id: "a", path: "posts/a.md", title: "Alpha", body: "Saved.", collab,
+    fields: [
+      { name: "status", type: "string", value: "published" },
+      { name: "content", type: "string", component: "body", source: "body", value: "Saved." },
+    ],
+  };
+  await openEditor(entry, renderField);
+
+  const before = seen[seen.length - 1].resetNonce;
+  // An edit to the body, as the editor itself would report one.
+  seen[seen.length - 1].onChange("Scratch.");
+
+  fireEvent.click(await screen.findByTestId("discard-changes"));
+
+  await waitFor(() => {
+    const last = seen[seen.length - 1];
+    expect(last.value).toBe("Saved.");
+    expect(last.resetNonce).not.toBe(before);
+  });
+});
+
+// A discard replaces the whole document, but only the fields that actually
+// moved should be written: churning the rest costs CRDT operations and can
+// nudge the cursor of a peer working in a field nobody discarded.
+test("discarding leaves untouched fields alone in the room", async () => {
+  const { collab } = fakeCollab({ status: "published", subtitle: "untouched" });
+  const writes: string[] = [];
+  const wrapped: CollabApi = {
+    ...collab,
+    text: (p) => {
+      const b = collab.text(p);
+      return { ...b, set: (n) => { writes.push(p); b.set(n); } };
+    },
+  };
+  const entry: CmsEntry = {
+    id: "a", path: "posts/a.md", title: "Alpha", body: "", collab: wrapped,
+    fields: [
+      { name: "status", type: "string", label: "Status", value: "published" },
+      { name: "subtitle", type: "string", label: "Subtitle", value: "untouched" },
+    ],
+  };
+  await openEditor(entry);
+
+  fireEvent.change(screen.getByDisplayValue("published"), { target: { value: "scratch" } });
+  await waitFor(() => expect(screen.getByDisplayValue("scratch")).toBeInTheDocument());
+  writes.length = 0;
+
+  fireEvent.click(await screen.findByTestId("discard-changes"));
+
+  expect(writes).toContain("status");
+  expect(writes).not.toContain("subtitle");
+});

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

@@ -0,0 +1,179 @@
+import React from "react";
+import { render, screen, fireEvent, waitFor } from "@testing-library/react";
+import { ThemeProvider } from "../ThemeProvider";
+import { ContentBrowser, type CmsEntry, type CmsNavSection, type EntryField } from "../components/ContentBrowser";
+import type { ReferenceApi, ReferenceDef, ReferenceTarget } from "../references";
+
+// 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 ada: ReferenceTarget = { id: "au1", collection: "authors", path: "content/authors/ada.md", key: "content/authors/ada.md", label: "Ada Lovelace" };
+const bob: ReferenceTarget = { id: "au2", collection: "authors", path: "content/authors/bob.md", key: "content/authors/bob.md", label: "Bob" };
+const byKey: Record<string, ReferenceTarget> = { [ada.key]: ada, [bob.key]: bob };
+
+function makeApi(over: Partial<ReferenceApi> = {}): ReferenceApi {
+  return {
+    search: jest.fn(async ({ query }) => [ada, bob].filter((t) => !query || t.label.toLowerCase().includes(query.toLowerCase()))),
+    resolve: jest.fn(async (_collections: string[], _key: string, keys: string[]) =>
+      keys.map((k) => ({ key: k, target: byKey[k] ?? null, ambiguous: false, candidates: [] })),
+    ),
+    referrers: jest.fn(async () => [{ id: "d2", collection: "articles", path: "content/articles/other.md", label: "Other", fieldPath: "related.0" }]),
+    ...over,
+  };
+}
+
+// The editor keeps unsaved edits per document id in localStorage, and every
+// test here renders document "a": clear it so one test's pick never seeds the
+// next test's field.
+beforeEach(() => {
+  window.localStorage.clear();
+});
+
+const sections: CmsNavSection[] = [
+  { title: "Content", items: [{ key: "articles", label: "Articles", icon: "newspaper" }] },
+];
+
+const authorDef: ReferenceDef = { collections: ["authors"], key: "_path", keyName: "ref", embed: [], onDelete: "restrict" };
+const embedDef: ReferenceDef = {
+  collections: ["authors"], key: "_path", keyName: "ref", onDelete: "restrict",
+  embed: [{ name: "name", source: "name" }, { name: "url", source: "/authors/{{slug}}/" }],
+};
+
+// `null` renders without a references seam; the default is a working one.
+// (A default parameter also fires for an explicit `undefined`, so the no-seam
+// case has to be spelled `null`.)
+function renderWith(fields: EntryField[], api: ReferenceApi | null = makeApi()) {
+  const onSave = jest.fn();
+  const entry: CmsEntry = { id: "a", path: "content/articles/a.md", title: "Alpha", body: "", fields };
+  render(
+    <ThemeProvider>
+      <ContentBrowser
+        workspace={{ name: "acme/site", initials: "AC", branch: "main", changed: 0 }}
+        sections={sections}
+        activeNavKey="articles"
+        onSelectNav={() => {}}
+        entries={[entry]}
+        userInitials="ED"
+        references={api ?? undefined}
+        onSaveEntry={onSave}
+      />
+    </ThemeProvider>,
+  );
+  return onSave;
+}
+
+test("a string reference resolves its key to the target's label", async () => {
+  const api = makeApi();
+  renderWith([{ name: "author", label: "Author", type: "string", component: "reference", reference: authorDef, value: ada.key }], api);
+  expect(await screen.findByText("Ada Lovelace")).toBeInTheDocument();
+  expect(screen.getByTestId("reference-key")).toHaveTextContent(ada.key);
+  expect(api.resolve).toHaveBeenCalledWith(["authors"], "_path", [ada.key]);
+});
+
+test("a key naming nothing shows the missing state and keeps the key", async () => {
+  renderWith([{ name: "author", label: "Author", type: "string", component: "reference", reference: authorDef, value: "content/authors/gone.md" }]);
+  expect(await screen.findByTestId("reference-missing")).toBeInTheDocument();
+  expect(screen.getByTestId("reference-key")).toHaveTextContent("content/authors/gone.md");
+});
+
+test("picking a document from the picker writes its key", async () => {
+  const api = makeApi();
+  renderWith([{ name: "author", label: "Author", type: "string", component: "reference", reference: authorDef, value: "" }], api);
+  expect(screen.getByText("No document selected")).toBeInTheDocument();
+
+  fireEvent.click(screen.getByTestId("reference-choose"));
+  fireEvent.click(await screen.findByTestId(`reference-row-${bob.id}`));
+
+  // The control now holds Bob's key and resolves it.
+  expect(await screen.findByText("Bob")).toBeInTheDocument();
+  expect(screen.getByTestId("reference-key")).toHaveTextContent(bob.key);
+  expect(api.search).toHaveBeenCalledWith(expect.objectContaining({ collections: ["authors"], key: "_path" }));
+});
+
+test("an object reference shows its embedded copies read-only and picks by key child", async () => {
+  renderWith([
+    {
+      name: "author", label: "Author", type: "object", component: "reference", reference: embedDef,
+      fields: [
+        { name: "ref", type: "string", value: undefined },
+        { name: "name", label: "Name", type: "string", value: undefined },
+        { name: "url", label: "URL", type: "string", value: undefined },
+      ],
+      value: { ref: ada.key, name: "Ada Lovelace", url: "/authors/ada/" },
+    },
+  ]);
+  expect(await screen.findByTestId("reference-target")).toHaveTextContent("Ada Lovelace");
+  const copies = screen.getByTestId("reference-copies");
+  expect(copies).toHaveTextContent("/authors/ada/");
+  expect(copies).toHaveTextContent("Copied from Ada Lovelace");
+  // No input is offered for a copy: the server owns them.
+  expect(screen.queryByDisplayValue("/authors/ada/")).not.toBeInTheDocument();
+
+  fireEvent.click(screen.getByTestId("reference-choose"));
+  fireEvent.click(await screen.findByTestId(`reference-row-${bob.id}`));
+  expect(screen.getByTestId("reference-key")).toHaveTextContent(bob.key);
+  // The old copies stay until the server replaces them on save; once the new
+  // key resolves the caption names the new target.
+  await waitFor(() => expect(screen.getByTestId("reference-copies")).toHaveTextContent("Copied from Bob"));
+  expect(screen.getByTestId("reference-copies")).toHaveTextContent("/authors/ada/");
+});
+
+test("an array of references renders a picker per item", async () => {
+  renderWith([
+    { name: "related", label: "Related", type: "array", of: "string", component: "list", reference: authorDef, value: [ada.key, bob.key] },
+  ]);
+  expect(await screen.findAllByTestId("reference-choose")).toHaveLength(2);
+  expect(await screen.findByText("Bob")).toBeInTheDocument();
+});
+
+test("the Details modal shows the document's metadata and its references both ways", async () => {
+  renderWith([
+    { name: "title", label: "Title", type: "string", value: "Alpha" },
+    { name: "author", label: "Author", type: "string", component: "reference", reference: authorDef, value: ada.key },
+    { name: "editor", label: "Editor", type: "string", component: "reference", reference: authorDef, value: "content/authors/gone.md" },
+  ]);
+  // Nothing about references sits in the document body itself.
+  await screen.findByText("Ada Lovelace");
+  expect(screen.queryByText("Referenced by")).not.toBeInTheDocument();
+
+  fireEvent.click(screen.getByTestId("detail-menu"));
+  fireEvent.click(screen.getByTestId("detail-details"));
+  const modal = await screen.findByTestId("document-details");
+  expect(modal).toHaveTextContent("content/articles/a.md");
+  expect(modal).toHaveTextContent("Articles");
+
+  const refs = await screen.findByTestId("details-references");
+  await waitFor(() => expect(refs).toHaveTextContent("Ada Lovelace"));
+  expect(refs).toHaveTextContent("author");
+  expect(refs).toHaveTextContent("content/authors/gone.md — missing");
+
+  const referrers = await screen.findByTestId("details-referrers");
+  await waitFor(() => expect(referrers).toHaveTextContent("Other"));
+  expect(referrers).toHaveTextContent("related.0");
+
+  fireEvent.click(screen.getByTestId("details-close"));
+  expect(screen.queryByTestId("document-details")).not.toBeInTheDocument();
+});
+
+test("without a references seam the field renders read-only", async () => {
+  renderWith([{ name: "author", label: "Author", type: "string", component: "reference", reference: authorDef, value: ada.key }], null);
+  // Nothing resolves and the picker cannot open: the key shows raw.
+  expect(await screen.findByTestId("reference-key")).toHaveTextContent(ada.key);
+  fireEvent.click(screen.getByTestId("reference-choose"));
+  await new Promise((r) => setTimeout(r, 50));
+  expect(screen.queryByText("Choose a document")).not.toBeInTheDocument();
+  expect(screen.queryByTestId("reference-target")).not.toBeInTheDocument();
+  expect(screen.queryByTestId("reference-missing")).not.toBeInTheDocument();
+
+  // Details still opens — it is a read — with the metadata and the raw key,
+  // but claims nothing about what the key resolves to.
+  fireEvent.click(screen.getByTestId("detail-menu"));
+  fireEvent.click(screen.getByTestId("detail-details"));
+  const modal = await screen.findByTestId("document-details");
+  expect(modal).toHaveTextContent("content/articles/a.md");
+  expect(screen.getByTestId("details-references")).toHaveTextContent(ada.key);
+  expect(screen.queryByTestId("details-referrers")).not.toBeInTheDocument();
+});