@gogitcms/design-system 0.15.0-next.3 → 0.16.0-next.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gogitcms/design-system",
-  "version": "0.15.0-next.3",
+  "version": "0.16.0-next.0",
   "main": "src/index.ts",
   "types": "src/index.ts",
   "// exports": "The root entry is the react-native source the SPAs, desktop app and mobile app consume. ./web is the plain-DOM build for server-rendered surfaces (the Astro docs site) that don't run react-native-web, and ./css ships the tokens as custom properties. The trailing wildcard keeps deep paths resolvable — plugin bundling and the Vite aliases reach into src/ directly.",

package/src/__tests__/FormsBrowser.test.tsx

@@ -0,0 +1,248 @@
+import React from "react";
+import { render, screen, fireEvent, waitFor } from "@testing-library/react";
+import { ThemeProvider } from "../ThemeProvider";
+import { FormsBrowser } from "../components/FormsBrowser";
+import type { FormInfo, FormsApi, SubmissionInfo } from "../forms";
+import { FORMS_NAV_KEY, formsNavKey, isFormsNavKey, parseFormsNavKey, summaryLine } from "../forms";
+
+const contact: FormInfo = {
+  name: "contact",
+  label: "Contact us",
+  description: "General enquiries.",
+  fields: [
+    { name: "email", label: "Email", type: "string" },
+    { name: "reason", label: "Reason", type: "string" },
+    { name: "orderNumber", label: "Order number", type: "string" },
+  ],
+  fieldCount: 3,
+  submissionCount: 2,
+  versioned: true,
+  storePath: "content/submissions/contact/*.json",
+  canDelete: true,
+};
+
+const newsletter: FormInfo = {
+  name: "newsletter",
+  label: "Newsletter",
+  fields: [{ name: "email", type: "string" }],
+  fieldCount: 1,
+  submissionCount: 308,
+  versioned: false,
+  canDelete: false,
+};
+
+const submissions: SubmissionInfo[] = [
+  {
+    id: "s1",
+    form: "contact",
+    fields: { email: "priya@example.test", reason: "support", orderNumber: "A-1" },
+    submittedAt: "2026-08-28T12:00:00Z",
+    status: "received",
+    path: "content/submissions/contact/s1.json",
+  },
+  {
+    // reason is "sales", so orderNumber was never asked for — it is ABSENT
+    // rather than null, which the detail view must show as such.
+    id: "s2",
+    form: "contact",
+    fields: { email: "sam@example.test", reason: "sales" },
+    submittedAt: "2026-08-27T09:30:00Z",
+    status: "received",
+  },
+];
+
+function makeApi(over: Partial<FormsApi> = {}): FormsApi {
+  return {
+    forms: [contact, newsletter],
+    list: jest.fn(async ({ status }) =>
+      status === "spam" ? [] : submissions,
+    ),
+    count: jest.fn(async ({ status }) => (status === "spam" ? 0 : submissions.length)),
+    ...over,
+  };
+}
+
+function renderBrowser(props: Partial<React.ComponentProps<typeof FormsBrowser>> = {}) {
+  const api = props.api ?? makeApi();
+  const onSelectForm = props.onSelectForm ?? jest.fn();
+  const utils = render(
+    <ThemeProvider>
+      <FormsBrowser
+        api={api}
+        form={props.form ?? null}
+        onSelectForm={onSelectForm}
+        selectedId={props.selectedId}
+        onSelectSubmission={props.onSelectSubmission}
+        variant={props.variant ?? "desktop"}
+      />
+    </ThemeProvider>,
+  );
+  return { ...utils, api, onSelectForm };
+}
+
+// ── nav keys ────────────────────────────────────────────────────────────────
+
+describe("the forms nav-key space", () => {
+  it("cannot collide with a collection, because a collection name has no colon", () => {
+    expect(isFormsNavKey("forms")).toBe(false); // a collection literally named "forms"
+    expect(isFormsNavKey(FORMS_NAV_KEY)).toBe(true);
+    expect(isFormsNavKey(formsNavKey("contact"))).toBe(true);
+  });
+
+  it("tells the Forms button apart from a chosen form", () => {
+    expect(parseFormsNavKey(FORMS_NAV_KEY)).toBeNull();
+    expect(parseFormsNavKey(formsNavKey("contact"))).toBe("contact");
+    expect(parseFormsNavKey("posts")).toBeNull();
+  });
+});
+
+// ── the forms list ──────────────────────────────────────────────────────────
+
+describe("the forms list", () => {
+  it("shows each form's name, description, field count and submission count", () => {
+    renderBrowser();
+    expect(screen.getByText("Contact us")).toBeTruthy();
+    expect(screen.getByText("General enquiries.")).toBeTruthy();
+    expect(screen.getByText("3 fields")).toBeTruthy();
+    expect(screen.getByText("2")).toBeTruthy();
+    expect(screen.getByText("308")).toBeTruthy();
+  });
+
+  it("opens a form when its row is pressed", () => {
+    const { onSelectForm } = renderBrowser();
+    fireEvent.click(screen.getByTestId("form-row-contact"));
+    expect(onSelectForm).toHaveBeenCalledWith("contact");
+  });
+
+  it("says so when the branch declares no forms", () => {
+    renderBrowser({ api: makeApi({ forms: [] }) });
+    expect(screen.getByText(/declares no forms/i)).toBeTruthy();
+  });
+});
+
+// ── submissions ─────────────────────────────────────────────────────────────
+
+describe("a form's submissions", () => {
+  it("lists them with a summary line built from what the person wrote", async () => {
+    renderBrowser({ form: "contact" });
+    await waitFor(() => expect(screen.getByTestId("submission-row-s1")).toBeTruthy());
+    // The email is preferred: it is what a reader scans an inbox for.
+    expect(screen.getByText("priya@example.test")).toBeTruthy();
+    expect(screen.getByText("sam@example.test")).toBeTruthy();
+  });
+
+  it("reports a tap so the host can bind it to the URL", async () => {
+    const onSelectSubmission = jest.fn();
+    renderBrowser({ form: "contact", onSelectSubmission });
+    await waitFor(() => expect(screen.getByTestId("submission-row-s1")).toBeTruthy());
+    fireEvent.click(screen.getByTestId("submission-row-s1"));
+    expect(onSelectSubmission).toHaveBeenCalledWith("s1");
+  });
+
+  it("goes back to the forms list", async () => {
+    const { onSelectForm } = renderBrowser({ form: "contact" });
+    await waitFor(() => expect(screen.getByTestId("forms-back")).toBeTruthy());
+    fireEvent.click(screen.getByTestId("forms-back"));
+    expect(onSelectForm).toHaveBeenCalledWith(null);
+  });
+
+  it("has somewhere to see spam, since a honeypot hit is recorded not discarded", async () => {
+    const { api } = renderBrowser({ form: "contact" });
+    await waitFor(() => expect(screen.getByTestId("forms-status-toggle")).toBeTruthy());
+    fireEvent.click(screen.getByTestId("forms-status-toggle"));
+    await waitFor(() =>
+      expect(api.list).toHaveBeenCalledWith(expect.objectContaining({ status: "spam" })),
+    );
+    await waitFor(() => expect(screen.getByText(/Nothing caught as spam/i)).toBeTruthy());
+  });
+});
+
+// ── the read-only submission ────────────────────────────────────────────────
+
+describe("a selected submission", () => {
+  it("renders every value read-only, with no editable control", async () => {
+    renderBrowser({ form: "contact", selectedId: "s1" });
+    await waitFor(() => expect(screen.getByText("A-1")).toBeTruthy());
+    // The email shows twice — once as the row's summary line, once as the
+    // detail's value — which is what a list beside a detail looks like.
+    expect(screen.getAllByText("priya@example.test").length).toBeGreaterThan(0);
+    expect(screen.getByText("support")).toBeTruthy();
+    // A submission is a record of what someone sent, not a document with
+    // editing switched off.
+    expect(screen.queryByDisplayValue("priya@example.test")).toBeNull();
+  });
+
+  it("distinguishes a field that was never asked for from one left blank", async () => {
+    renderBrowser({ form: "contact", selectedId: "s2" });
+    await waitFor(() => expect(screen.getByTestId("submission-not-asked-orderNumber")).toBeTruthy());
+    expect(screen.getByText("Not asked")).toBeTruthy();
+  });
+
+  it("shows where a versioned submission lives in the repository", async () => {
+    renderBrowser({ form: "contact", selectedId: "s1" });
+    await waitFor(() =>
+      expect(screen.getByText("content/submissions/contact/s1.json")).toBeTruthy(),
+    );
+  });
+
+  it("omits the repository path for a submission git does not hold", async () => {
+    renderBrowser({ form: "contact", selectedId: "s2" });
+    await waitFor(() => expect(screen.getByText("Not asked")).toBeTruthy());
+    expect(screen.queryByText(/In the repository/i)).toBeNull();
+  });
+});
+
+// ── the summary line ────────────────────────────────────────────────────────
+
+describe("summaryLine", () => {
+  it("prefers an email-ish value, then the first readable text", () => {
+    expect(summaryLine(submissions[0], contact)).toBe("priya@example.test");
+    expect(
+      summaryLine(
+        { ...submissions[0], fields: { reason: "support", orderNumber: "A-1" } },
+        contact,
+      ),
+    ).toBe("support");
+  });
+
+  it("says so rather than rendering an empty row", () => {
+    expect(summaryLine({ ...submissions[0], fields: { agreed: true } }, contact)).toBe("(no text)");
+  });
+});
+
+// A form can legitimately fail to list — local mode answers NO_SUBMISSION_STORE
+// for a form that keeps its submissions in a database it does not have. Before
+// this had somewhere to go, the promise rejected and the pane spun forever.
+describe("a form whose submissions cannot be listed", () => {
+  const failing = (): FormsApi => ({
+    forms: [contact],
+    list: jest.fn().mockRejectedValue(
+      Object.assign(new Error("network"), {
+        graphQLErrors: [{ message: "form \"newsletter\" keeps its submissions in a database" }],
+      }),
+    ),
+    count: jest.fn().mockRejectedValue(new Error("network")),
+  });
+
+  it("stops loading instead of spinning forever", async () => {
+    renderBrowser({ api: failing(), form: "contact" });
+    await waitFor(() => expect(screen.getByTestId("forms-error")).toBeTruthy());
+  });
+
+  it("shows the server's own sentence, which says what to change", async () => {
+    renderBrowser({ api: failing(), form: "contact" });
+    await waitFor(() =>
+      expect(screen.getByText(/keeps its submissions in a database/)).toBeTruthy(),
+    );
+  });
+
+  it("falls back to something readable when the error carries no message", async () => {
+    const api: FormsApi = {
+      forms: [contact],
+      list: jest.fn().mockRejectedValue({}),
+      count: jest.fn().mockRejectedValue({}),
+    };
+    renderBrowser({ api, form: "contact" });
+    await waitFor(() => expect(screen.getByText(/could not be loaded/)).toBeTruthy());
+  });
+});

package/src/components/ContentBrowser.tsx

@@ -31,6 +31,8 @@ import {
 import { clamp, reorder, slotAtX } from "./reorder";
 import { MediaField, MediaProvider, DocumentPathProvider } from "./MediaField";
 import { MediaBrowser } from "./MediaBrowser";
+import { FormsBrowser } from "./FormsBrowser";
+import { FORMS_NAV_KEY, formsNavKey, isFormsNavKey, parseFormsNavKey, type FormsApi } from "../forms";
 import {
   MEDIA_NAV_KEY,
   mediaNavKey,
@@ -334,6 +336,14 @@ export type ContentBrowserProps = {
   // store gets.
   media?: MediaApi;
 
+  // Forms data seam, the same split (docs/forms.md §10.2). Omitted → the Forms
+  // surface never renders, which is what a config declaring no forms looks like.
+  forms?: FormsApi;
+  // The selected submission's id, and the reporter for taps — bound to the URL
+  // by the host exactly as document selection is.
+  selectedSubmissionId?: string | null;
+  onSelectSubmission?: (id: string | null) => void;
+
   // When provided, field/body edits autosave 1s after the last keystroke and an
   // autosave indicator appears in the detail header. Omitted → edits stay local
   // (the demo/read-only behavior).
@@ -3599,6 +3609,10 @@ function DesktopBrowser(props: ContentBrowserProps) {
   const mediaShowing = isMediaNavKey(activeNavKey);
   const mediaSet = parseMediaNavKey(activeNavKey);
   const mediaSets = props.media?.sets ?? [];
+  // Forms occupy their own prefixed nav-key space, mirroring media's — a
+  // collection name cannot contain a colon, so neither can collide.
+  const formsShowing = isFormsNavKey(activeNavKey);
+  const activeForm = parseFormsNavKey(activeNavKey);
   // "Browsing" mode (collection-driven): nothing auto-selected, empty states shown.
   const browsing = entriesEmpty !== undefined;
   // Controlled selection: when the host wired onSelectEntry, selection lives in
@@ -4129,6 +4143,30 @@ function DesktopBrowser(props: ContentBrowserProps) {
   // lists the media sets exactly where a collection's documents would be, and the
   // details pane holds the browser for whichever set is selected. Selecting a set
   // goes through onSelectNav, so it lands in the URL like any other selection.
+  // Forms take the whole content area rather than the three-pane model: the
+  // surface is already two levels deep (forms → submissions → one submission),
+  // and threading that through panes designed for collection → document → editor
+  // would mean a pane whose meaning changes with the level.
+  if (formsShowing && props.forms) {
+    return (
+      <AppShell testID="desktop-shell" topBar={topBar} banner={readOnlyBanner}>
+        {navPane}
+        <ResizeHandle width={navW} min={180} max={420} onChange={setNavW} testID="resize-nav" />
+        <Pane flex={1} testID="pane-forms" scroll={false}>
+          <FormsBrowser
+            api={props.forms}
+            form={activeForm}
+            onSelectForm={(name) => onSelectNav(name ? formsNavKey(name) : FORMS_NAV_KEY)}
+            selectedId={props.selectedSubmissionId ?? null}
+            onSelectSubmission={props.onSelectSubmission}
+            variant="desktop"
+          />
+        </Pane>
+        {applyModal}
+      </AppShell>
+    );
+  }
+
   if (mediaShowing) {
     return (
       <AppShell testID="desktop-shell" topBar={topBar} banner={readOnlyBanner}>
@@ -4436,6 +4474,8 @@ function MobileBrowser(props: ContentBrowserProps) {
   const mediaShowing = isMediaNavKey(activeNavKey);
   const mediaSet = parseMediaNavKey(activeNavKey);
   const mediaSets = props.media?.sets ?? [];
+  const formsShowing = isFormsNavKey(activeNavKey);
+  const activeForm = parseFormsNavKey(activeNavKey);
   // A plugin screen renders as its own drilled-in screen; Back returns to the
   // nav list like any other selection.
   if (props.contentSlot != null) {
@@ -4455,6 +4495,40 @@ function MobileBrowser(props: ContentBrowserProps) {
       </MobileScreen>
     );
   }
+  if (formsShowing && props.forms) {
+    return (
+      <MobileScreen
+        testID="mobile-forms"
+        header={
+          <>
+            {/* Back steps up one level, not out to the nav — the same rule the
+                media and collection screens follow. */}
+            <IconButton
+              name="chevronLeft"
+              onPress={() => (activeForm ? onSelectNav(FORMS_NAV_KEY) : backToNav())}
+              size="md"
+              label="Back"
+            />
+            <Text variant="body" weight="semibold" style={{ flex: 1 }}>
+              {activeForm
+                ? props.forms.forms.find((f) => f.name === activeForm)?.label || activeForm
+                : "Forms"}
+            </Text>
+          </>
+        }
+      >
+        <FormsBrowser
+          api={props.forms}
+          form={activeForm}
+          onSelectForm={(name) => onSelectNav(name ? formsNavKey(name) : FORMS_NAV_KEY)}
+          selectedId={props.selectedSubmissionId ?? null}
+          onSelectSubmission={props.onSelectSubmission}
+          variant="mobile"
+        />
+      </MobileScreen>
+    );
+  }
+
   if (mediaShowing) {
     if (!mediaSet) {
       return (
@@ -4553,8 +4627,11 @@ function MobileBrowser(props: ContentBrowserProps) {
           </View>
         ) : null}
         {readOnlyBanner}
-        {sections.map((section) => (
-          <View key={section.title}>
+        {sections.map((section, i) => (
+          // Keyed with the index as a fallback: an untitled section renders its
+          // button without a heading, and there is more than one of those now
+          // (Media, Forms), so the title alone is not unique.
+          <View key={section.title || `section-${i}`}>
             <SectionLabel>{section.title}</SectionLabel>
             {section.items.map((item, i) => (
               <NavRow

package/src/components/FormsBrowser.tsx

@@ -0,0 +1,545 @@
+import React from "react";
+import { FlatList, Pressable, TextInput, View } from "react-native";
+import { useTheme } from "../ThemeProvider";
+import { Text } from "./Text";
+import { Icon } from "./Icon";
+import { Spinner } from "./Spinner";
+import {
+  type FormInfo,
+  type FormsApi,
+  type SubmissionInfo,
+  summaryLine,
+} from "../forms";
+
+// The Forms surface: a list of forms, a form's submissions, and one submission
+// rendered read-only (docs/forms.md §10.2).
+//
+// ── Why this does not reuse FieldControl ────────────────────────────────────
+//
+// The obvious move is to render a submission with the same controls the
+// document editor uses, in readOnly mode. Two reasons not to.
+//
+// FieldControl reaches ~18 sibling components inside ContentBrowser.tsx, most of
+// them collaboration-aware (CollabInput, CollabArrayField, GroupPresence…).
+// Extracting it into a shared module so a second consumer could import it is a
+// large refactor of a 5,000-line file, and a submission needs none of what it
+// would drag along: no CRDT session, no draft state, no onChange, no media
+// picker interaction.
+//
+// And it would be worse to read. A submission is a record of what somebody sent,
+// not a document with editing switched off, so a row of disabled inputs is the
+// wrong presentation for it — a label-and-value read view says "this is what
+// they wrote" in a way a greyed-out form never does.
+
+const PAGE_SIZE = 50;
+
+export type FormsBrowserProps = {
+  api: FormsApi;
+  /** The form being browsed, from the nav key. Null shows the forms list. */
+  form: string | null;
+  /** Open a form (null returns to the list). The host binds this to the URL. */
+  onSelectForm: (form: string | null) => void;
+  /** The selected submission's id, and the reporter for taps. */
+  selectedId?: string | null;
+  onSelectSubmission?: (id: string | null) => void;
+  variant?: "desktop" | "mobile";
+};
+
+export function FormsBrowser(props: FormsBrowserProps) {
+  const { api, form, onSelectForm, selectedId, onSelectSubmission, variant = "desktop" } = props;
+  const t = useTheme();
+  const isDesktop = variant === "desktop";
+
+  const active = form ? api.forms.find((f) => f.name === form) ?? null : null;
+
+  if (!form || !active) {
+    return <FormList forms={api.forms} onSelect={onSelectForm} />;
+  }
+  return (
+    <SubmissionsView
+      api={api}
+      form={active}
+      onBack={() => onSelectForm(null)}
+      selectedId={selectedId ?? null}
+      onSelect={onSelectSubmission}
+      isDesktop={isDesktop}
+    />
+  );
+}
+
+// ── The forms list ──────────────────────────────────────────────────────────
+
+// Each row reads like a folder in the hierarchical content models, because that
+// is what a form is here: a container you open to find what is inside it.
+function FormList({ forms, onSelect }: { forms: FormInfo[]; onSelect: (name: string) => void }) {
+  const t = useTheme();
+  if (forms.length === 0) {
+    return (
+      <View style={{ padding: t.space(6) }}>
+        <Text color="secondary">This branch declares no forms.</Text>
+      </View>
+    );
+  }
+  return (
+    <View style={{ flex: 1 }}>
+      <View style={{ paddingHorizontal: t.space(4), paddingVertical: t.space(3) }}>
+        <Text variant="label" color="tertiary">
+          {forms.length} {forms.length === 1 ? "form" : "forms"}
+        </Text>
+      </View>
+      <FlatList
+        data={forms}
+        keyExtractor={(f) => f.name}
+        renderItem={({ item }) => <FormRow form={item} onPress={() => onSelect(item.name)} />}
+      />
+    </View>
+  );
+}
+
+function FormRow({ form, onPress }: { form: FormInfo; onPress: () => void }) {
+  const t = useTheme();
+  const [hover, setHover] = React.useState(false);
+  return (
+    <Pressable
+      onPress={onPress}
+      onHoverIn={() => setHover(true)}
+      onHoverOut={() => setHover(false)}
+      testID={`form-row-${form.name}`}
+      style={{
+        flexDirection: "row",
+        alignItems: "center",
+        gap: t.space(3),
+        paddingHorizontal: t.space(4),
+        paddingVertical: t.space(3),
+        borderBottomWidth: 1,
+        borderBottomColor: t.color.borderSubtle,
+        backgroundColor: hover ? t.color.surfaceHover : "transparent",
+      }}
+    >
+      <Icon name="listTree" size={16} color={t.color.textTertiary} />
+      <View style={{ flex: 1, gap: 2 }}>
+        <View style={{ flexDirection: "row", alignItems: "center", gap: t.space(2) }}>
+          <Text numberOfLines={1}>{form.label || form.name}</Text>
+          {form.versioned ? (
+            <Icon name="gitBranch" size={12} color={t.color.textTertiary} />
+          ) : null}
+        </View>
+        {form.description ? (
+          <Text variant="sm" color="tertiary" numberOfLines={1}>
+            {form.description}
+          </Text>
+        ) : null}
+      </View>
+      {/* The two numbers the request asks for: how much has come in, and how
+          much the form asks for. */}
+      <Text variant="monoSm" color="tertiary">
+        {form.fieldCount} {form.fieldCount === 1 ? "field" : "fields"}
+      </Text>
+      <Text variant="monoSm" color="secondary" style={{ minWidth: 48, textAlign: "right" }}>
+        {form.submissionCount}
+      </Text>
+      <Icon name="chevronRight" size={14} color={t.color.textTertiary} />
+    </Pressable>
+  );
+}
+
+// ── One form's submissions ──────────────────────────────────────────────────
+
+function SubmissionsView({
+  api,
+  form,
+  onBack,
+  selectedId,
+  onSelect,
+  isDesktop,
+}: {
+  api: FormsApi;
+  form: FormInfo;
+  onBack: () => void;
+  selectedId: string | null;
+  onSelect?: (id: string | null) => void;
+  isDesktop: boolean;
+}) {
+  const t = useTheme();
+  const [items, setItems] = React.useState<SubmissionInfo[]>([]);
+  const [total, setTotal] = React.useState<number | null>(null);
+  const [loading, setLoading] = React.useState(true);
+  // A form can legitimately fail to list: local mode answers
+  // NO_SUBMISSION_STORE for a form that keeps its submissions in a database it
+  // does not have. Without somewhere to put that, the promise rejected and the
+  // pane spun forever — which is a worse answer than the empty inbox this was
+  // written to avoid.
+  const [failure, setFailure] = React.useState<string | null>(null);
+  const [loadingMore, setLoadingMore] = React.useState(false);
+  const [exhausted, setExhausted] = React.useState(false);
+  const [search, setSearch] = React.useState("");
+  const [status, setStatus] = React.useState<"received" | "spam">("received");
+
+  // Switching form, filter or search is a different result set: reset rather
+  // than paging one query's offsets into another's.
+  React.useEffect(() => {
+    let alive = true;
+    setLoading(true);
+    setExhausted(false);
+    setFailure(null);
+    Promise.all([
+      api.list({ form: form.name, status, search, limit: PAGE_SIZE, offset: 0 }),
+      api.count({ form: form.name, status, search }),
+    ])
+      .then(([rows, n]) => {
+        if (!alive) return;
+        setItems(rows);
+        setTotal(n);
+        setExhausted(rows.length >= n);
+      })
+      .catch((err: unknown) => {
+        if (!alive) return;
+        setItems([]);
+        setTotal(null);
+        // The server's own sentence, which for the case that actually happens
+        // says what to change in the config. A generic "couldn't load" would
+        // throw that away.
+        setFailure(messageOf(err));
+      })
+      .finally(() => alive && setLoading(false));
+    return () => {
+      alive = false;
+    };
+  }, [api, form.name, status, search]);
+
+  const loadMore = React.useCallback(() => {
+    if (loadingMore || exhausted || loading) return;
+    setLoadingMore(true);
+    api
+      .list({ form: form.name, status, search, limit: PAGE_SIZE, offset: items.length })
+      .then((rows) => {
+        setItems((prev) => [...prev, ...rows]);
+        if (rows.length < PAGE_SIZE) setExhausted(true);
+      })
+      .finally(() => setLoadingMore(false));
+  }, [api, form.name, status, search, items.length, loading, loadingMore, exhausted]);
+
+  const selected = selectedId ? items.find((s) => s.id === selectedId) ?? null : null;
+
+  const list = (
+    <View style={{ flex: 1, minWidth: 0 }}>
+      <View
+        style={{
+          flexDirection: "row",
+          alignItems: "center",
+          gap: t.space(2),
+          paddingHorizontal: t.space(3),
+          paddingVertical: t.space(2),
+          borderBottomWidth: 1,
+          borderBottomColor: t.color.borderSubtle,
+        }}
+      >
+        <Pressable onPress={onBack} testID="forms-back" style={{ padding: t.space(1) }}>
+          <Icon name="chevronLeft" size={16} color={t.color.textSecondary} />
+        </Pressable>
+        <Text numberOfLines={1} style={{ flex: 1 }}>
+          {form.label || form.name}
+        </Text>
+        <Text variant="monoSm" color="tertiary">
+          {total ?? "—"}
+        </Text>
+      </View>
+
+      <View
+        style={{
+          flexDirection: "row",
+          alignItems: "center",
+          gap: t.space(2),
+          paddingHorizontal: t.space(3),
+          paddingVertical: t.space(2),
+        }}
+      >
+        <TextInput
+          value={search}
+          onChangeText={setSearch}
+          placeholder="Search submissions"
+          placeholderTextColor={t.color.textTertiary}
+          testID="forms-search"
+          style={{
+            flex: 1,
+            height: t.control.sm,
+            paddingHorizontal: t.space(2),
+            borderWidth: 1,
+            borderColor: t.color.borderDefault,
+            borderRadius: t.radius.sm,
+            color: t.color.textPrimary,
+          }}
+        />
+        {/* Spam is recorded rather than discarded (a honeypot also catches
+            browser autofill), so it needs somewhere to be seen. */}
+        <Pressable
+          onPress={() => setStatus(status === "received" ? "spam" : "received")}
+          testID="forms-status-toggle"
+          style={{
+            height: t.control.sm,
+            justifyContent: "center",
+            paddingHorizontal: t.space(2),
+            borderWidth: 1,
+            borderColor: status === "spam" ? t.color.borderStrong : t.color.borderDefault,
+            borderRadius: t.radius.sm,
+          }}
+        >
+          <Text variant="monoSm" color={status === "spam" ? "primary" : "tertiary"}>
+            Spam
+          </Text>
+        </Pressable>
+      </View>
+
+      {loading ? (
+        <View style={{ padding: t.space(6), alignItems: "center" }}>
+          <Spinner />
+        </View>
+      ) : failure ? (
+        <View style={{ padding: t.space(6) }} testID="forms-error">
+          <Text color="secondary">{failure}</Text>
+        </View>
+      ) : items.length === 0 ? (
+        <View style={{ padding: t.space(6) }}>
+          <Text color="secondary">
+            {status === "spam" ? "Nothing caught as spam." : "No submissions yet."}
+          </Text>
+        </View>
+      ) : (
+        <FlatList
+          data={items}
+          keyExtractor={(s) => s.id}
+          onEndReached={loadMore}
+          onEndReachedThreshold={0.4}
+          ListFooterComponent={
+            loadingMore ? (
+              <View style={{ padding: t.space(4), alignItems: "center" }}>
+                <Spinner />
+              </View>
+            ) : null
+          }
+          renderItem={({ item }) => (
+            <SubmissionRow
+              submission={item}
+              form={form}
+              selected={item.id === selectedId}
+              onPress={() => onSelect?.(item.id)}
+            />
+          )}
+        />
+      )}
+    </View>
+  );
+
+  if (!isDesktop) {
+    // Mobile pushes: the list, or the submission on top of it.
+    return selected ? (
+      <SubmissionDetail submission={selected} form={form} onBack={() => onSelect?.(null)} />
+    ) : (
+      list
+    );
+  }
+
+  return (
+    <View style={{ flex: 1, flexDirection: "row", minWidth: 0 }}>
+      <View
+        style={{
+          width: t.layout.column,
+          borderRightWidth: 1,
+          borderRightColor: t.color.borderSubtle,
+        }}
+      >
+        {list}
+      </View>
+      <View style={{ flex: 1, minWidth: 0 }}>
+        {selected ? (
+          <SubmissionDetail submission={selected} form={form} />
+        ) : (
+          <View style={{ padding: t.space(6) }}>
+            <Text color="secondary">Select a submission</Text>
+          </View>
+        )}
+      </View>
+    </View>
+  );
+}
+
+function SubmissionRow({
+  submission,
+  form,
+  selected,
+  onPress,
+}: {
+  submission: SubmissionInfo;
+  form: FormInfo;
+  selected: boolean;
+  onPress: () => void;
+}) {
+  const t = useTheme();
+  const [hover, setHover] = React.useState(false);
+  return (
+    <Pressable
+      onPress={onPress}
+      onHoverIn={() => setHover(true)}
+      onHoverOut={() => setHover(false)}
+      testID={`submission-row-${submission.id}`}
+      style={{
+        gap: 2,
+        paddingHorizontal: t.space(4),
+        paddingVertical: t.space(3),
+        borderBottomWidth: 1,
+        borderBottomColor: t.color.borderSubtle,
+        backgroundColor: selected
+          ? t.color.surfaceActive
+          : hover
+            ? t.color.surfaceHover
+            : "transparent",
+      }}
+    >
+      <Text numberOfLines={1}>{summaryLine(submission, form)}</Text>
+      <View style={{ flexDirection: "row", alignItems: "center", gap: t.space(2) }}>
+        <Text variant="monoSm" color="tertiary">
+          {formatWhen(submission.submittedAt)}
+        </Text>
+        {submission.status === "spam" ? (
+          <Text variant="monoSm" color={t.color.diffDelFg}>
+            spam
+          </Text>
+        ) : null}
+      </View>
+    </Pressable>
+  );
+}
+
+// ── One submission, read-only ───────────────────────────────────────────────
+
+function SubmissionDetail({
+  submission,
+  form,
+  onBack,
+}: {
+  submission: SubmissionInfo;
+  form: FormInfo;
+  onBack?: () => void;
+}) {
+  const t = useTheme();
+  return (
+    <View style={{ flex: 1 }}>
+      <View
+        style={{
+          flexDirection: "row",
+          alignItems: "center",
+          gap: t.space(2),
+          paddingHorizontal: t.space(4),
+          paddingVertical: t.space(3),
+          borderBottomWidth: 1,
+          borderBottomColor: t.color.borderSubtle,
+        }}
+      >
+        {onBack ? (
+          <Pressable onPress={onBack} testID="submission-back" style={{ padding: t.space(1) }}>
+            <Icon name="chevronLeft" size={16} color={t.color.textSecondary} />
+          </Pressable>
+        ) : null}
+        <View style={{ flex: 1, gap: 2 }}>
+          <Text numberOfLines={1}>{summaryLine(submission, form)}</Text>
+          <Text variant="monoSm" color="tertiary">
+            {formatWhen(submission.submittedAt)}
+          </Text>
+        </View>
+      </View>
+
+      <View style={{ padding: t.space(4), gap: t.space(4) }}>
+        {form.fields.map((f) => {
+          const present = Object.prototype.hasOwnProperty.call(submission.fields, f.name);
+          return (
+            <View key={f.name} style={{ gap: t.space(1) }}>
+              <Text variant="label" color="tertiary">
+                {f.label || f.name}
+              </Text>
+              {present ? (
+                <FieldValue value={submission.fields[f.name]} />
+              ) : (
+                // The visible payoff of storing an inapplicable field as ABSENT
+                // rather than null: "we never asked" is a different fact from
+                // "they left it blank", and the record can say which.
+                <Text variant="sm" color="disabled" testID={`submission-not-asked-${f.name}`}>
+                  Not asked
+                </Text>
+              )}
+            </View>
+          );
+        })}
+
+        {submission.path ? (
+          <View style={{ gap: t.space(1), paddingTop: t.space(2) }}>
+            <Text variant="label" color="tertiary">
+              In the repository
+            </Text>
+            <Text variant="monoSm" color="secondary">
+              {submission.path}
+            </Text>
+          </View>
+        ) : null}
+      </View>
+    </View>
+  );
+}
+
+// FieldValue renders one stored value for reading. Deliberately small: the
+// shapes a submission can hold are the config's field types, and each has an
+// obvious read form.
+function FieldValue({ value }: { value: unknown }) {
+  const t = useTheme();
+  if (value === null || value === undefined || value === "") {
+    return (
+      <Text variant="sm" color="disabled">
+        —
+      </Text>
+    );
+  }
+  if (typeof value === "boolean") {
+    return <Text>{value ? "Yes" : "No"}</Text>;
+  }
+  if (Array.isArray(value)) {
+    return (
+      <View style={{ gap: t.space(1) }}>
+        {value.map((v, i) => (
+          <Text key={i}>• {typeof v === "object" ? JSON.stringify(v) : String(v)}</Text>
+        ))}
+      </View>
+    );
+  }
+  if (typeof value === "object") {
+    return (
+      <View style={{ gap: t.space(1) }}>
+        {Object.entries(value as Record<string, unknown>).map(([k, v]) => (
+          <View key={k} style={{ flexDirection: "row", gap: t.space(2) }}>
+            <Text variant="monoSm" color="tertiary">
+              {k}
+            </Text>
+            <Text style={{ flex: 1 }}>{typeof v === "object" ? JSON.stringify(v) : String(v)}</Text>
+          </View>
+        ))}
+      </View>
+    );
+  }
+  return <Text>{String(value)}</Text>;
+}
+
+// messageOf digs the human sentence out of whatever the host's api threw. An
+// Apollo error carries the server's message on graphQLErrors; everything else
+// is an Error, or something that is not.
+function messageOf(err: unknown): string {
+  const gql = (err as { graphQLErrors?: { message?: string }[] })?.graphQLErrors;
+  if (Array.isArray(gql) && gql[0]?.message) return gql[0].message!;
+  if (err instanceof Error && err.message) return err.message;
+  return "These submissions could not be loaded.";
+}
+
+// formatWhen renders a timestamp the way an inbox does. Falls back to the raw
+// string rather than showing "Invalid Date" for anything unparseable.
+export function formatWhen(iso: string): string {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return iso;
+  return d.toLocaleString();
+}

package/src/forms.ts

@@ -0,0 +1,118 @@
+// Forms in the editor: the nav-key space they occupy and the data seam the host
+// fills (docs/forms.md §10).
+//
+// The scheme mirrors media's exactly, and for the same reason: a collection name
+// is restricted to [A-Za-z0-9_-] by the config schema, so it can never contain a
+// colon — not even a collection literally named "forms".
+//
+//   "forms:"          the Forms button — the list of forms
+//   "forms:contact"   one form's submissions, which is what makes it deep-linkable
+const FORMS_NAV_PREFIX = "forms:";
+
+/** FORMS_NAV_KEY is the Forms button's own key — forms with none selected. */
+export const FORMS_NAV_KEY = FORMS_NAV_PREFIX;
+
+/** formsNavKey returns the nav key for a form, or for the Forms button. */
+export function formsNavKey(form?: string): string {
+  return form ? FORMS_NAV_PREFIX + form : FORMS_NAV_PREFIX;
+}
+
+/**
+ * isFormsNavKey reports whether a nav key addresses forms at all — true for the
+ * Forms button and for any form beneath it. This is what a host checks to know
+ * the forms surface is showing.
+ */
+export function isFormsNavKey(key: string | null | undefined): boolean {
+  return !!key && key.startsWith(FORMS_NAV_PREFIX);
+}
+
+/**
+ * parseFormsNavKey returns the form a nav key selects: null for an ordinary
+ * collection, and also null for the bare Forms button (forms are showing, but no
+ * form is chosen). Pair it with isFormsNavKey to tell those two apart.
+ */
+export function parseFormsNavKey(key: string | null | undefined): string | null {
+  if (!isFormsNavKey(key)) return null;
+  const form = key!.slice(FORMS_NAV_PREFIX.length);
+  return form.length > 0 ? form : null;
+}
+
+/** One field of a form, as the editor needs to render a submission. */
+export type FormFieldInfo = {
+  name: string;
+  label?: string | null;
+  /** string | integer | float | boolean | array | object */
+  type: string;
+  component?: string | null;
+};
+
+/** One form, with the summary numbers the Forms list shows. */
+export type FormInfo = {
+  name: string;
+  label?: string | null;
+  description?: string | null;
+  fields: FormFieldInfo[];
+  fieldCount: number;
+  submissionCount: number;
+  lastSubmissionAt?: string | null;
+  /** True when the form writes its submissions to git. */
+  versioned: boolean;
+  storePath?: string | null;
+  canDelete: boolean;
+};
+
+/** One submission, read-only by construction — a record of what someone sent. */
+export type SubmissionInfo = {
+  id: string;
+  form: string;
+  /** Field name → value, missing entirely for a field whose condition was false. */
+  fields: Record<string, unknown>;
+  submittedAt: string;
+  /** "received" | "spam" */
+  status: string;
+  /** Where it lives in the repository, when the form versions its submissions. */
+  path?: string | null;
+};
+
+/**
+ * FormsApi is the data seam between the design system and its host: the DS owns
+ * the browsing UI, the host owns fetching (Apollo on web/mobile, REST on
+ * desktop). Omitting it from ContentBrowser hides the Forms surface entirely,
+ * which is what a config declaring no forms should look like.
+ */
+export interface FormsApi {
+  /** The forms on this branch, with their summary numbers. */
+  forms: FormInfo[];
+  /** One page of a form's submissions, newest first. */
+  list: (params: {
+    form: string;
+    status?: string;
+    search?: string;
+    limit?: number;
+    offset?: number;
+  }) => Promise<SubmissionInfo[]>;
+  /** How many match, ignoring paging — the total behind "12 of 340". */
+  count: (params: { form: string; status?: string; search?: string }) => Promise<number>;
+  /** Delete submissions. Omit to hide the affordance. */
+  remove?: (ids: string[]) => Promise<void>;
+}
+
+/**
+ * summaryLine builds the one-line label a submission row shows.
+ *
+ * A submission has no title — what makes one recognisable is what the person
+ * wrote — so the first field carrying readable text is used, preferring an
+ * email-ish value because that is what a reader scans an inbox for.
+ */
+export function summaryLine(sub: SubmissionInfo, form?: FormInfo): string {
+  const order = form ? form.fields.map((f) => f.name) : Object.keys(sub.fields);
+  let firstText = "";
+  for (const name of order) {
+    const v = sub.fields[name];
+    if (typeof v !== "string" || v.trim() === "") continue;
+    if (v.includes("@")) return v.trim();
+    if (!firstText) firstText = v.trim();
+  }
+  if (firstText) return firstText.length > 80 ? firstText.slice(0, 79) + "…" : firstText;
+  return "(no text)";
+}

package/src/index.ts

@@ -196,3 +196,14 @@ export type {
   CollabPeer,
   CollabParticipant,
 } from "./components/ContentBrowser";
+
+export { FormsBrowser } from "./components/FormsBrowser";
+export type { FormsBrowserProps } from "./components/FormsBrowser";
+export {
+  FORMS_NAV_KEY,
+  formsNavKey,
+  isFormsNavKey,
+  parseFormsNavKey,
+  summaryLine,
+} from "./forms";
+export type { FormsApi, FormInfo, FormFieldInfo, SubmissionInfo } from "./forms";