@gogitcms/design-system 0.15.0-next.3

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

@@ -0,0 +1,142 @@
+// A mixed list has to read the key the content actually uses.
+//
+// The control looked for `_variant` and nothing else. Content that names its own
+// shapes — `type: hero`, written for the site's own templates long before any
+// CMS — matched no variant, so every item rendered as a bare variant dropdown
+// with none of its fields beneath it. On screen that is a list of empty rows,
+// indistinguishable from a document with nothing in it.
+
+import React from "react";
+import { fireEvent, render, screen } from "@testing-library/react";
+import { ThemeProvider } from "../ThemeProvider";
+import {
+  ContentBrowser,
+  type CmsEntry,
+  type CmsNavSection,
+  type EntryField,
+  type EntrySaveChange,
+} 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>;
+const sections: CmsNavSection[] = [
+  { title: "Content", items: [{ key: "pages", label: "Pages", icon: "newspaper" }] },
+];
+
+beforeEach(() => {
+  localStorage.clear();
+  refreshDrafts();
+});
+
+const variants = [
+  {
+    name: "hero",
+    label: "Hero",
+    fields: [
+      { name: "title", label: "Title", type: "string", value: "" },
+      { name: "subtitle", label: "Subtitle", type: "string", value: "" },
+    ],
+  },
+  { name: "news", label: "News & Updates", fields: [{ name: "title", label: "Title", type: "string", value: "" }] },
+];
+
+// The shape the content actually has: the variant named by `type`, no `_variant`
+// anywhere.
+const widgets = (discriminator?: string): EntryField => ({
+  name: "widgets",
+  label: "Widgets",
+  type: "array",
+  component: "mixedList",
+  discriminator,
+  value: [
+    { type: "hero", title: "Welcome", subtitle: "To our home" },
+    { type: "news", title: "Latest" },
+  ],
+  variants,
+}) as EntryField;
+
+function renderDoc(field: EntryField, onSaveEntry = jest.fn()) {
+  const entry: CmsEntry = { id: "a", path: "pages/home.json", title: "Home", body: "", fields: [field] };
+  render(
+    wrap(
+      <ContentBrowser
+        workspace={{ name: "acme/site", initials: "AC", branch: "main", changed: 0 }}
+        sections={sections}
+        activeNavKey="pages"
+        onSelectNav={() => {}}
+        entries={[entry]}
+        userInitials="ED"
+        onSaveEntry={onSaveEntry}
+      />
+    )
+  );
+  return onSaveEntry;
+}
+
+test("a field naming its own discriminator renders each item's fields", () => {
+  renderDoc(widgets("type"));
+
+  expect(screen.getByDisplayValue("Welcome")).toBeInTheDocument();
+  expect(screen.getByDisplayValue("To our home")).toBeInTheDocument();
+  expect(screen.getByDisplayValue("Latest")).toBeInTheDocument();
+  // Each item's dropdown shows which shape it is.
+  const pickers = screen.getAllByTestId("select-control") as HTMLSelectElement[];
+  expect(pickers.map((p) => p.value)).toEqual(["hero", "news"]);
+});
+
+test("without one, the same content matches no variant — the old behavior, on purpose", () => {
+  // Left as a test rather than deleted: it is what the default still does, and
+  // what every document written by this CMS relies on.
+  renderDoc(widgets(undefined));
+  expect(screen.queryByDisplayValue("Welcome")).not.toBeInTheDocument();
+});
+
+test("_variant stays the default for content that uses it", () => {
+  renderDoc({
+    ...widgets(undefined),
+    value: [{ _variant: "hero", title: "Welcome" }],
+  } as EntryField);
+  expect(screen.getByDisplayValue("Welcome")).toBeInTheDocument();
+});
+
+test("edits keep writing the key the content uses, not a second one", async () => {
+  const onSave = renderDoc(widgets("type"));
+
+  fireEvent.change(screen.getByDisplayValue("Welcome"), { target: { value: "Welcome home" } });
+  fireEvent.click(screen.getByTestId("save-entry"));
+
+  const change = (onSave.mock.calls[0] as [EntrySaveChange])[0];
+  expect(change.fields.widgets).toEqual([
+    { type: "hero", title: "Welcome home", subtitle: "To our home" },
+    { type: "news", title: "Latest" },
+  ]);
+});
+
+test("a new item is created under the field's own key", () => {
+  const onSave = renderDoc(widgets("type"));
+
+  fireEvent.click(screen.getByTestId("mixedlist-add"));
+  fireEvent.click(screen.getByTestId("save-entry"));
+
+  const change = (onSave.mock.calls[0] as [EntrySaveChange])[0];
+  const items = change.fields.widgets as Record<string, unknown>[];
+  expect(items[2]).toEqual({ type: "hero" });
+  expect(items[2]).not.toHaveProperty("_variant");
+});
+
+test("changing an item's variant rewrites that key rather than adding another", () => {
+  const onSave = renderDoc(widgets("type"));
+
+  const pickers = screen.getAllByTestId("select-control") as HTMLSelectElement[];
+  fireEvent.change(pickers[1], { target: { value: "hero" } });
+  fireEvent.click(screen.getByTestId("save-entry"));
+
+  const change = (onSave.mock.calls[0] as [EntrySaveChange])[0];
+  const items = change.fields.widgets as Record<string, unknown>[];
+  expect(items[1]).toEqual({ type: "hero" });
+});

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

@@ -0,0 +1,271 @@
+// Editing is explicit: edits accumulate as a local draft and reach the host
+// only when the author saves.
+//
+// The behaviour these pin is the reason for the change — a CMS backed by git
+// should not turn every keystroke into a commit — and the parts most likely to
+// be broken by a later refactor are the ones about *not* losing work: a draft
+// outlives the document being closed, and Discard is the only thing besides a
+// successful save that throws it away.
+import React from "react";
+import { render, screen, fireEvent, waitFor, act } from "@testing-library/react";
+import { ThemeProvider } from "../ThemeProvider";
+import { ContentBrowser, type CmsEntry, type CmsNavSection, type EntryField } from "../components/ContentBrowser";
+import { readDraft, refreshDrafts } from "../components/documentDrafts";
+
+// 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" }] },
+];
+
+const fields = (title = "Alpha"): EntryField[] => [
+  { name: "title", label: "Title", type: "string", value: title, required: true },
+  { name: "summary", label: "Summary", type: "string", value: "" },
+];
+
+const entry = (id = "doc-1", title = "Alpha"): CmsEntry => ({
+  id,
+  path: "posts/a.md",
+  title,
+  body: "",
+  fields: fields(title),
+});
+
+function renderBrowser(onSaveEntry = jest.fn(), e: CmsEntry = entry(), onEntryDraft?: jest.Mock) {
+  const base = {
+    workspace: { name: "acme/site", initials: "AC", branch: "main", changed: 0 },
+    sections,
+    activeNavKey: "posts",
+    onSelectNav: () => {},
+    entries: [e],
+    userInitials: "ED",
+  } as const;
+  const utils = render(
+    wrap(<ContentBrowser {...base} onSaveEntry={onSaveEntry} onEntryDraft={onEntryDraft} />),
+  );
+  return { ...utils, onSaveEntry, onEntryDraft };
+}
+
+// The draft write is debounced; these tests wait for it rather than racing it.
+const DRAFT_SETTLE = 600;
+
+function typeSummary(text: string) {
+  const input = screen.getByDisplayValue("") as HTMLInputElement;
+  fireEvent.change(input, { target: { value: text } });
+}
+
+beforeEach(() => {
+  // Clearing storage behind the store's back is exactly what refreshDrafts is
+  // for — without it the cached id set outlives the drafts it describes.
+  localStorage.clear();
+  refreshDrafts();
+});
+
+test("editing does not reach the host until the author saves", async () => {
+  const { onSaveEntry } = renderBrowser();
+
+  typeSummary("a first sentence");
+
+  // The old editor would have persisted this within a second. Waiting past that
+  // window is the point of the assertion.
+  await act(() => new Promise((r) => setTimeout(r, 1200)));
+  expect(onSaveEntry).not.toHaveBeenCalled();
+
+  fireEvent.click(screen.getByTestId("save-entry"));
+  await waitFor(() => expect(onSaveEntry).toHaveBeenCalledTimes(1));
+  expect(onSaveEntry.mock.calls[0][0].fields.summary).toBe("a first sentence");
+});
+
+test("an edit is written to storage so a closed tab does not lose it", async () => {
+  renderBrowser();
+  typeSummary("work in progress");
+
+  await waitFor(() => expect(readDraft("doc-1")?.values.summary).toBe("work in progress"), {
+    timeout: DRAFT_SETTLE,
+  });
+});
+
+test("reopening a document shows the unsaved edit, not the saved version", async () => {
+  const first = renderBrowser();
+  typeSummary("unsaved words");
+  await waitFor(() => expect(readDraft("doc-1")).not.toBeNull(), { timeout: DRAFT_SETTLE });
+  first.unmount();
+
+  // A fresh mount, as if the column had been closed and the document reopened.
+  renderBrowser();
+  expect(await screen.findByDisplayValue("unsaved words")).toBeInTheDocument();
+  expect(screen.getByTestId("autosave-indicator")).toHaveTextContent("Unsaved changes");
+});
+
+test("saving clears the draft, so the document reopens as saved", async () => {
+  const { onSaveEntry, unmount } = renderBrowser();
+  typeSummary("ready to publish");
+  await waitFor(() => expect(readDraft("doc-1")).not.toBeNull(), { timeout: DRAFT_SETTLE });
+
+  fireEvent.click(screen.getByTestId("save-entry"));
+  await waitFor(() => expect(onSaveEntry).toHaveBeenCalled());
+  await waitFor(() => expect(readDraft("doc-1")).toBeNull());
+
+  unmount();
+  renderBrowser();
+  // The host owns the saved values; with no draft the editor shows what it was
+  // given, which here is still the original empty summary.
+  expect(screen.getByDisplayValue("")).toBeInTheDocument();
+});
+
+test("a failed save keeps the draft", async () => {
+  const onSaveEntry = jest.fn().mockRejectedValue(new Error("the branch is protected"));
+  renderBrowser(onSaveEntry);
+  typeSummary("still mine");
+  await waitFor(() => expect(readDraft("doc-1")).not.toBeNull(), { timeout: DRAFT_SETTLE });
+
+  fireEvent.click(screen.getByTestId("save-entry"));
+  await waitFor(() => expect(screen.getByTestId("autosave-indicator")).toHaveTextContent("Save failed"));
+  // The work must survive the thing that went wrong.
+  expect(readDraft("doc-1")?.values.summary).toBe("still mine");
+  expect(screen.getByDisplayValue("still mine")).toBeInTheDocument();
+});
+
+test("discard drops the draft and restores the saved values", async () => {
+  renderBrowser();
+  typeSummary("never mind");
+  await waitFor(() => expect(readDraft("doc-1")).not.toBeNull(), { timeout: DRAFT_SETTLE });
+
+  fireEvent.click(screen.getByTestId("discard-changes"));
+
+  expect(readDraft("doc-1")).toBeNull();
+  expect(screen.queryByDisplayValue("never mind")).not.toBeInTheDocument();
+  expect(screen.queryByTestId("autosave-indicator")).not.toBeInTheDocument();
+});
+
+// The preview is fed from edits, and a discard is the one change to a document
+// that produces no edit — so without an explicit emission the preview keeps
+// rendering work the author just deleted.
+test("discarding tells the preview to go back to the saved version", async () => {
+  const onEntryDraft = jest.fn();
+  renderBrowser(jest.fn(), entry(), onEntryDraft);
+
+  typeSummary("about to be discarded");
+  await waitFor(() => expect(onEntryDraft).toHaveBeenCalled(), { timeout: DRAFT_SETTLE });
+  expect(onEntryDraft.mock.calls.at(-1)![0].fields.summary).toBe("about to be discarded");
+
+  fireEvent.click(screen.getByTestId("discard-changes"));
+
+  await waitFor(
+    () => expect(onEntryDraft.mock.calls.at(-1)![0].fields.summary).toBe(""),
+    { timeout: DRAFT_SETTLE },
+  );
+});
+
+test("save is offered only when there is something valid to save", async () => {
+  renderBrowser();
+  const save = screen.getByTestId("save-entry");
+  // Nothing edited yet.
+  expect(save).toBeDisabled();
+
+  // A required field emptied: the draft is still kept (the author's work is not
+  // the validator's business) but saving it is refused.
+  const title = screen.getByDisplayValue("Alpha") as HTMLInputElement;
+  fireEvent.change(title, { target: { value: "" } });
+  expect(screen.getByTestId("save-entry")).toBeDisabled();
+  await waitFor(() => expect(readDraft("doc-1")?.values.title).toBe(""), { timeout: DRAFT_SETTLE });
+
+  fireEvent.change(title, { target: { value: "Alpha again" } });
+  await waitFor(() => expect(screen.getByTestId("save-entry")).not.toBeDisabled());
+});
+
+// The list is where an author sees work they left somewhere else: a document
+// edited yesterday, or in another column, is otherwise indistinguishable from a
+// saved one until it is opened.
+test("a document with unsaved edits is badged in the list and counted in the header", async () => {
+  renderBrowser();
+
+  // Nothing pending: no badge, and no count to report.
+  expect(screen.queryByTestId("entry-draft-badge")).not.toBeInTheDocument();
+  expect(screen.queryByTestId("uncommitted-count")).not.toBeInTheDocument();
+
+  typeSummary("half a thought");
+
+  // Both appear on the first edit, without a reload — the list is subscribed to
+  // the draft store, not reading it once at mount.
+  expect(await screen.findByTestId("entry-draft-badge")).toBeInTheDocument();
+  expect(screen.getByTestId("uncommitted-count")).toHaveTextContent("1 uncommitted");
+});
+
+test("the badge and the count clear when the draft is discarded", async () => {
+  renderBrowser();
+  typeSummary("never mind this either");
+  expect(await screen.findByTestId("entry-draft-badge")).toBeInTheDocument();
+
+  fireEvent.click(screen.getByTestId("discard-changes"));
+
+  await waitFor(() => expect(screen.queryByTestId("entry-draft-badge")).not.toBeInTheDocument());
+  expect(screen.queryByTestId("uncommitted-count")).not.toBeInTheDocument();
+});
+
+test("the count survives a reload, because the drafts do", async () => {
+  const first = renderBrowser();
+  typeSummary("still here tomorrow");
+  await waitFor(() => expect(readDraft("doc-1")).not.toBeNull(), { timeout: DRAFT_SETTLE });
+  first.unmount();
+
+  renderBrowser();
+  expect(await screen.findByTestId("uncommitted-count")).toHaveTextContent("1 uncommitted");
+  expect(screen.getByTestId("entry-draft-badge")).toBeInTheDocument();
+});
+
+// Unsaved means "differs from what is saved". Both of these were reported as a
+// document that opens dirty: the stored draft is the one every client left
+// behind while a field could mark a document changed just by being written to.
+test("a draft that matches the saved document is dropped, not offered back", async () => {
+  localStorage.setItem(
+    "gitcms.draft.v1:doc-1",
+    JSON.stringify({ v: 1, values: { title: "Alpha", summary: "" }, at: Date.now() }),
+  );
+  refreshDrafts();
+
+  renderBrowser();
+
+  expect(screen.queryByTestId("autosave-indicator")).not.toBeInTheDocument();
+  expect(screen.getByTestId("save-entry")).toBeDisabled();
+  await waitFor(() => expect(readDraft("doc-1")).toBeNull());
+  expect(screen.queryByTestId("entry-draft-badge")).not.toBeInTheDocument();
+});
+
+test("typing back to the saved value leaves nothing to save", async () => {
+  renderBrowser();
+  const title = screen.getByDisplayValue("Alpha") as HTMLInputElement;
+
+  fireEvent.change(title, { target: { value: "Alphabet" } });
+  expect(screen.getByTestId("autosave-indicator")).toHaveTextContent("Unsaved changes");
+  await waitFor(() => expect(readDraft("doc-1")).not.toBeNull(), { timeout: DRAFT_SETTLE });
+
+  fireEvent.change(title, { target: { value: "Alpha" } });
+
+  expect(screen.queryByTestId("autosave-indicator")).not.toBeInTheDocument();
+  expect(screen.getByTestId("save-entry")).toBeDisabled();
+  // The stored copy goes too, or the document is dirty again on the next reload.
+  await waitFor(() => expect(readDraft("doc-1")).toBeNull());
+});
+
+test("a read-only document offers no save and writes no draft", async () => {
+  const base = {
+    workspace: { name: "acme/site", initials: "AC", branch: "main", changed: 0 },
+    sections,
+    activeNavKey: "posts",
+    onSelectNav: () => {},
+    entries: [entry()],
+    userInitials: "ED",
+    readOnly: true,
+  } as const;
+  render(wrap(<ContentBrowser {...base} onSaveEntry={jest.fn()} />));
+
+  expect(screen.queryByTestId("save-entry")).not.toBeInTheDocument();
+  expect(readDraft("doc-1")).toBeNull();
+});

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

@@ -0,0 +1,117 @@
+import React from "react";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { ThemeProvider } from "../ThemeProvider";
+import { ContentBrowser, type CmsEntry, type CmsNavSection, type EntryField } 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" }] },
+];
+
+const fields: EntryField[] = [
+  { name: "active", label: "Active", type: "boolean", component: "switch", value: false },
+  { name: "count", label: "Count", type: "integer", component: "stepper", min: 0, max: 5, value: "" },
+  { name: "status", label: "Status", type: "string", component: "select", enumValues: ["draft", "published"], value: "" },
+  { name: "publishedAt", label: "Published", type: "string", component: "date", value: "" },
+  { name: "tags", label: "Tags", type: "array", component: "list", of: "string", value: [] },
+  { name: "meta", label: "Meta", type: "object", component: "group", value: {}, fields: [{ name: "author", label: "Author", type: "string", value: "" }] },
+  {
+    name: "blocks", label: "Blocks", type: "array", component: "mixedList", value: [],
+    variants: [{ name: "hero", label: "Hero", fields: [{ name: "heading", label: "Heading", type: "string", value: "" }] }],
+  },
+];
+
+const entry: CmsEntry = { id: "a", path: "posts/a.md", title: "Alpha", body: "", fields };
+
+// No onSelectEntry / entriesEmpty → uncontrolled desktop mode auto-selects the
+// first entry, so its field editor renders without a click.
+const base = {
+  workspace: { name: "acme/site", initials: "AC", branch: "main", changed: 0 },
+  sections,
+  activeNavKey: "posts",
+  onSelectNav: () => {},
+  entries: [entry],
+  userInitials: "ED",
+} as const;
+
+function renderBrowser() {
+  return render(wrap(<ContentBrowser {...base} onSaveEntry={jest.fn()} />));
+}
+
+test("switch renders and toggles its checked state", () => {
+  renderBrowser();
+  const sw = screen.getByRole("switch");
+  expect(sw).toHaveAttribute("aria-checked", "false");
+  fireEvent.click(sw);
+  expect(sw).toHaveAttribute("aria-checked", "true");
+});
+
+test("stepper increments and clamps at the configured max", () => {
+  renderBrowser();
+  // From empty, one increment → 1.
+  fireEvent.click(screen.getByTestId("stepper-inc"));
+  expect(screen.getByDisplayValue("1")).toBeInTheDocument();
+  // Push past max (5) — the value clamps.
+  for (let i = 0; i < 10; i++) fireEvent.click(screen.getByTestId("stepper-inc"));
+  expect(screen.getByDisplayValue("5")).toBeInTheDocument();
+});
+
+test("select renders a constrained dropdown with a blank option for the optional field", () => {
+  renderBrowser();
+  const select = screen.getByTestId("select-control") as HTMLSelectElement;
+  // draft + published + one blank (—) because the field is optional.
+  expect(select.querySelectorAll("option")).toHaveLength(3);
+});
+
+test("date renders a native date input", () => {
+  renderBrowser();
+  expect(screen.getByTestId("date-control")).toHaveAttribute("type", "date");
+});
+
+test("list adds and removes items, respecting the add control", () => {
+  renderBrowser();
+  expect(screen.queryByTestId("list-remove-0")).not.toBeInTheDocument();
+  fireEvent.click(screen.getByTestId("list-add"));
+  expect(screen.getByTestId("list-remove-0")).toBeInTheDocument();
+  fireEvent.click(screen.getByTestId("list-remove-0"));
+  expect(screen.queryByTestId("list-remove-0")).not.toBeInTheDocument();
+});
+
+test("group pushes an in-column view and the back control returns", () => {
+  renderBrowser();
+  // The nested "author" field isn't visible until the group is opened.
+  expect(screen.queryByText("Author")).not.toBeInTheDocument();
+  fireEvent.click(screen.getByTestId("group-open-meta"));
+  expect(screen.getByTestId("group-back")).toBeInTheDocument();
+  expect(screen.getByText("Author")).toBeInTheDocument();
+  fireEvent.click(screen.getByTestId("group-back"));
+  expect(screen.queryByTestId("group-back")).not.toBeInTheDocument();
+  expect(screen.queryByText("Author")).not.toBeInTheDocument();
+});
+
+test("the field body scrolls while the header stays outside the scroll region", () => {
+  renderBrowser();
+  const scroll = screen.getByTestId("column-scroll");
+  // A field control lives inside the scrollable body...
+  expect(scroll).toContainElement(screen.getByTestId("date-control"));
+  // ...but the sticky header's close control does not.
+  expect(scroll).not.toContainElement(screen.getByTestId("column-close"));
+});
+
+test("mixed list adds an item (with its variant subform)", () => {
+  renderBrowser();
+  // The `tags` list is empty, so no item frame exists yet.
+  expect(screen.queryByTestId("list-remove-0")).not.toBeInTheDocument();
+  fireEvent.click(screen.getByTestId("mixedlist-add"));
+  // The new mixed-list item renders an ItemFrame (shared remove control) and the
+  // hero variant's "Heading" field.
+  expect(screen.getByTestId("list-remove-0")).toBeInTheDocument();
+  expect(screen.getByText("Heading")).toBeInTheDocument();
+});

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

@@ -0,0 +1,140 @@
+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 { MediaApi, MediaAsset, MediaResolution } from "../media";
+
+// 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 hero: MediaAsset = {
+  id: "m1",
+  set: "uploads",
+  repoPath: "public/uploads/hero.png",
+  publicPath: "/uploads/hero.png",
+  cdnPath: null,
+  mimeType: "image/png",
+  extension: "png",
+  kind: "image",
+  size: 2048,
+  width: 800,
+  height: 600,
+  pending: false,
+  url: "https://store.example.com/signed/hero.png",
+};
+
+function makeApi(over: Partial<MediaApi> = {}): MediaApi {
+  return {
+    sets: [{ name: "uploads", path: "public/uploads/**/*", mimeTypes: [], count: 1 }],
+    resolve: jest.fn(async (paths: string[]): Promise<MediaResolution[]> =>
+      paths.map((p) => ({ input: p, media: hero, aliasKind: "public", ambiguous: false, candidates: [] })),
+    ),
+    byId: jest.fn(async () => hero),
+    list: jest.fn(async () => [hero]),
+    ...over,
+  };
+}
+
+const sections: CmsNavSection[] = [
+  { title: "Content", items: [{ key: "posts", label: "Posts", icon: "newspaper" }] },
+];
+
+function renderWith(fields: EntryField[], api: MediaApi | undefined = makeApi()) {
+  const onSave = jest.fn();
+  const entry: CmsEntry = { id: "a", path: "content/posts/a.md", title: "Alpha", body: "", fields };
+  render(
+    <ThemeProvider>
+      <ContentBrowser
+        workspace={{ name: "acme/site", initials: "AC", branch: "main", changed: 0 }}
+        sections={sections}
+        activeNavKey="posts"
+        onSelectNav={() => {}}
+        entries={[entry]}
+        userInitials="ED"
+        media={api}
+        onSaveEntry={onSave}
+      />
+    </ThemeProvider>,
+  );
+  return onSave;
+}
+
+const galleryField: EntryField = {
+  name: "gallery",
+  label: "Gallery",
+  type: "array",
+  of: "string",
+  component: "list",
+  media: "uploads",
+  storeAs: "public",
+  value: ["/uploads/hero.png"],
+};
+
+// The gap this closes: an array's items used to be rebuilt with only
+// name/type/fields, dropping the display config — so a list of media rendered as
+// plain text inputs even though the config asked for pickers.
+test("array items render media pickers when the array names a media set", async () => {
+  const api = makeApi();
+  renderWith([galleryField], api);
+
+  const img = await screen.findByRole("img");
+  expect(img).toHaveAttribute("src", hero.url);
+  expect(screen.getByTestId("media-choose")).toBeInTheDocument();
+  // The array's own component is `list` — it must not be handed to the item as
+  // if it were a control the item could render.
+  expect(api.resolve).toHaveBeenCalledWith(["/uploads/hero.png"], "content/posts/a.md");
+});
+
+test("a list with no media set stays a plain list of inputs", () => {
+  renderWith([{ ...galleryField, media: undefined, storeAs: undefined, value: ["x"] }]);
+  expect(screen.queryByTestId("media-choose")).not.toBeInTheDocument();
+});
+
+test("each array item gets its own picker", async () => {
+  renderWith([{ ...galleryField, value: ["/uploads/hero.png", "/uploads/hero.png"] }]);
+  expect(await screen.findAllByTestId("media-choose")).toHaveLength(2);
+});
+
+test("picking into an array item writes that slot in the store_as form", async () => {
+  const onSave = renderWith([{ ...galleryField, value: ["", ""] }]);
+
+  const choosers = await screen.findAllByTestId("media-choose");
+  fireEvent.click(choosers[1]);
+  fireEvent.click(await screen.findByTestId("media-row-m1"));
+
+  // Editing no longer reaches the host on its own — the author saves.
+  fireEvent.click(await screen.findByTestId("save-entry"));
+
+  // The pick must land in the second slot and leave the first alone — a picker
+  // wired to the wrong index would silently overwrite a neighbouring image.
+  await waitFor(() => {
+    expect(onSave).toHaveBeenCalled();
+    const change = onSave.mock.calls[onSave.mock.calls.length - 1][0];
+    expect(change.fields.gallery).toEqual(["", "/uploads/hero.png"]);
+  });
+});
+
+// Media fields inside a group/object are reached through the same context, not a
+// drilled prop, so the document path still has to arrive.
+test("a media field nested in an object resolves against the document path", async () => {
+  const api = makeApi();
+  renderWith(
+    [
+      {
+        name: "author",
+        label: "Author",
+        type: "object",
+        component: "inlineGroup",
+        value: { avatar: "/uploads/hero.png" },
+        fields: [{ name: "avatar", type: "string", component: "media", media: "uploads", value: "" }],
+      },
+    ],
+    api,
+  );
+
+  await screen.findByRole("img");
+  expect(api.resolve).toHaveBeenCalledWith(["/uploads/hero.png"], "content/posts/a.md");
+});