@graph8/sdk 0.370.0 → 0.374.0

package/blocks/forms/components/form-route-history.tsx

@@ -0,0 +1,72 @@
+"use client";
+
+/**
+ * FormRouteHistory: undo a routing change. Restore the route the form had before its latest save, or stop routing the
+ * form altogether. The form keeps CAPTURING either way; only where leads are delivered changes.
+ *
+ * SDK operations, in the order the screen uses them:
+ *   1. getFormOverview   GET    /forms/{form_key}/overview?source_id        (read; the current route version and destination)
+ *   2. rollbackFormRoute DELETE /forms/{form_key}/route { source_id, expected_current_version }                 (DESTRUCTIVE, confirmed: restores the previous route version)
+ *   3. rollbackFormRoute DELETE /forms/{form_key}/route { source_id, cancel_current: true, expected_current_version }   (DESTRUCTIVE, confirmed: removes the route)
+ *
+ * Stopping routing sends the version the screen last read, so a change made in the meantime is refused (409). Restoring the
+ * previous route is NOT version-checked by the API: it always restores the version before the current one, so look at the
+ * route version shown here before you confirm. A refused request reloads the route and says what happened.
+ */
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { useConfirmAction } from "@/g8/components/confirmed-action";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Delete, g8Get } from "@/g8/lib/g8-client";
+import type { FormOverview, FormRef } from "../lib/form-types";
+
+export interface FormRouteHistoryProps {
+  form: FormRef;
+  /** Called after the route changed, so the list and overview refresh. */
+  onChanged?: () => void;
+  className?: string;
+}
+
+export function FormRouteHistory({ form, onChanged, className }: FormRouteHistoryProps) {
+  const base = `/forms/${encodeURIComponent(form.form_key)}`;
+  const { ask, dialog, failure } = useConfirmAction();
+  const overview = useG8Query((signal) => g8Get<FormOverview>(`${base}/overview`, { source_id: form.source_id }, { signal }).then((r) => r.data), [form.form_key, form.source_id]);
+  const version = overview.data?.route?.version ?? undefined;
+  const list = overview.data?.destination?.list_name;
+  const done = (): void => { void overview.refetch(); onChanged?.(); };
+  const conflict = (err: unknown): unknown => {
+    if ((err as { status?: number })?.status !== 409) return err;
+    void overview.refetch();
+    return new Error("The API refused this: the route changed since it was loaded, or there is no earlier version to restore. The route shown here was reloaded: check it and try again.");
+  };
+
+  return (
+    <SectionCard className={className} title="Undo a routing change" description="Where this form's leads are delivered.">
+      {overview.error ? <ApiError error={overview.error} title="Could not load the route" onRetry={() => void overview.refetch()} /> : !overview.data ? <Skeleton className="h-16 w-full" aria-busy="true" /> : version === undefined ? (
+        <p className="text-sm">This form has no destination route to undo.</p>
+      ) : (
+        <div className="grid gap-3">
+          <KeyValueList columns={2} items={[{ label: "Route version", value: String(version) }, { label: "Destination list", value: list ?? "" }]} />
+          <div className="flex flex-wrap gap-2">
+            <Button variant="outline" disabled={version < 2} onClick={() => ask({
+              tier: "destructive", title: "Restore the previous route", confirmLabel: "Restore previous route",
+              description: `Replaces the current destination and field mapping with the ones this form had before its latest save. New leads follow the restored route; leads already delivered are not moved.`,
+              mapError: conflict, run: () => g8Delete(`${base}/route`, { body: { source_id: form.source_id } }), onDone: done,
+            })}>Restore the previous route</Button>
+            <Button variant="ghost" onClick={() => ask({
+              tier: "destructive", title: "Stop routing this form", confirmLabel: "Stop routing",
+              description: "Removes the destination and mapping. The form keeps capturing submissions, but they are not delivered to any list until you set a destination again.",
+              mapError: conflict, run: () => g8Delete(`${base}/route`, { body: { source_id: form.source_id, cancel_current: true, expected_current_version: version } }), onDone: done,
+            })}>Stop routing this form</Button>
+          </div>
+          {version < 2 ? <p className="text-muted-foreground text-xs">There is no earlier route to restore.</p> : null}
+        </div>
+      )}
+      {failure ? <ApiError error={failure} title="That did not work" onRetry={() => void overview.refetch()} /> : null}
+      <ConfirmSpendDialog {...dialog} />
+    </SectionCard>
+  );
+}

package/blocks/forms/components/form-saved-views.tsx

@@ -0,0 +1,81 @@
+"use client";
+
+/**
+ * FormSavedViews: save the current search and health filter of the forms list under a name, and bring it back with one
+ * click.
+ *
+ * SDK operations:
+ *   1. listSavedFormViews  GET /forms/views/saved                       (read)
+ *   2. saveFormView        PUT /forms/views/saved/{view_id} { name, filters }   (write; a new view gets a fresh id, saving over a view keeps its id)
+ *
+ * The filters saved are the ones this list has: `search` and, for failing / needs setup / live, `saved_view`. Applying a
+ * view hands those back to the screen; nothing is written when a view is applied.
+ */
+import { useState } from "react";
+import { Button, Input } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get, g8Put } from "@/g8/lib/g8-client";
+import { asRec, rowsOf, str } from "../lib/forms-extra";
+import type { Rec } from "../lib/forms-extra";
+
+export interface FormSavedViewsProps {
+  /** The list's current search text. */
+  search: string;
+  /** The list's current health filter ("" for all). */
+  health: string;
+  /** Apply a saved view back to the list. */
+  onApply: (view: { search: string; health: string }) => void;
+  className?: string;
+}
+
+/** Health values the API's `saved_view` filter understands. */
+const HEALTH_VIEWS = new Set(["failing", "needs_setup", "live"]);
+
+/** What a saved `saved_view` becomes in this list's health filter; values the list has no filter for map to "all". */
+export function healthOfView(view: string): string {
+  if (view === "failing" || view === "failures") return "failing";
+  if (view === "needs_setup") return "needs_setup";
+  if (view === "live" || view === "healthy") return "live";
+  return "";
+}
+
+/** The list filters a view cannot hold (paused, no data): saving would silently drop them. */
+export const UNSAVABLE_HEALTH = new Set(["paused", "no_data"]);
+
+export function savedFilters(search: string, health: string): Rec {
+  return { ...(search.trim() ? { search: search.trim() } : {}), ...(HEALTH_VIEWS.has(health) ? { saved_view: health } : {}) };
+}
+
+function newViewId(): string {
+  return globalThis.crypto?.randomUUID ? globalThis.crypto.randomUUID() : `view-${Date.now().toString(36)}`;
+}
+
+export function FormSavedViews({ search, health, onApply, className }: FormSavedViewsProps) {
+  const views = useG8Query((signal) => g8Get("/forms/views/saved", undefined, { signal }), []);
+  const rows = rowsOf<Rec>(views.data?.data, "views");
+  const [name, setName] = useState("");
+  const filters = savedFilters(search, health);
+  const existing = rows.find((v) => str(v.name) === name.trim());
+  // Saving under a name that already exists keeps that view's id (an update); a new name gets a fresh id.
+  const save = useG8Mutation(() => g8Put(`/forms/views/saved/${encodeURIComponent(existing ? str(existing.id) : newViewId())}`, { name: name.trim(), filters }), {
+    onSuccess: () => { setName(""); void views.refetch(); },
+  });
+  return (
+    <div className={className}>
+      <div className="flex flex-wrap items-center gap-2">
+        {rows.map((v) => {
+          const f = asRec(v.filters);
+          return <Button key={str(v.id)} size="sm" variant="outline" onClick={() => onApply({ search: str(f.search), health: healthOfView(str(f.saved_view)) })}>{str(v.name)}</Button>;
+        })}
+        <Input aria-label="Name for this view" className="h-8 w-40" placeholder="Save this view as" value={name} onChange={(e) => setName(e.target.value)} />
+        <Button size="sm" variant="outline" loading={save.loading} disabled={name.trim() === "" || Object.keys(filters).length === 0 || UNSAVABLE_HEALTH.has(health)} onClick={() => void save.mutate(undefined)}>Save view</Button>
+      </div>
+      {UNSAVABLE_HEALTH.has(health) ? <p role="note" className="text-muted-foreground mt-1 text-xs">A view cannot hold the Paused or No data filter. Pick another health, or clear it, to save this view.</p> : null}
+      {Object.keys(filters).length === 0 && name.trim() !== "" ? <p className="text-muted-foreground mt-1 text-xs">Set a search or a health filter first: a view with no filters would show everything.</p> : null}
+      {views.error ? <p role="note" className="text-muted-foreground mt-1 text-xs">Saved views could not be loaded. <button type="button" className="underline" onClick={() => void views.refetch()}>Reload views</button></p> : null}
+      {save.error ? <ApiError error={save.error} title="Could not save the view" /> : null}
+    </div>
+  );
+}

package/blocks/forms/components/forms-screen.tsx

@@ -9,12 +9,16 @@
  * Composes: ScreenLayout (title, tabs, stats), Toolbar (debounced search, health filter), SplitView +
  * DetailPanel (selected form, deep link `?id=<source_id>/<form_key>`, one submission `&submission=<id>`), FormEmbed
  * (Install tab, `?tab=install`), SiteAuditPanel (Site audit tab, `?tab=audit`), FormMappingEditor (Setup tab),
- * SubmissionsTable (Submissions tab).
+ * SubmissionsTable + SubmissionsExport (Submissions tab), FormBackfill + FormRouteHistory (Routing tab), FormActivity
+ * (Activity tab), FormGroups (Groups tab, `?tab=groups`), FormSavedViews (saved search and health filters).
  *
  * User flows: install the snippet and copy the ready-made lead form, see every captured form with its health and
  * counts, search and filter, open one to read capture and delivery numbers, rename it, pause or resume delivery
  * (confirmed), pick the destination list and map fields (suggest, preview, save, test), read submissions, trace
- * where a lead went and retry a failed delivery (confirmed), and find forms graph8 is not capturing.
+ * where a lead went and retry a failed delivery (confirmed), export submissions to CSV, deliver earlier leads through
+ * the route (preview, then a confirmed delivery), undo a routing change (confirmed), read a form's activity and the pages
+ * it appears on, group related forms, save a filtered view, load every form past the first page, and find forms graph8
+ * is not capturing. Creating a form is not possible: forms are captured from your site (an API limit, not a missing screen).
  *
  * SDK operations: listForms, getFormOverview, updateFormRegistry, pauseFormDelivery / resumeFormDelivery
  * (external, confirmed), searchFormSubmissions (read, to resolve a `&submission=` deep link that was not clicked
@@ -41,11 +45,20 @@ import { useUrlState } from "@/g8/hooks/use-url-state";
 import { g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
 import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { usePaginated } from "@/g8/hooks/use-paginated";
+import { pageOf } from "../lib/forms-extra";
 import { STATUS_LABEL, cellText, formLabel, formStatus, pageUrlText, pickItems, submissionFailed, submissionState } from "../lib/form-types";
 import type { FormListItem, FormOverview, FormRef, FormSubmission } from "../lib/form-types";
 import { FormEmbed } from "./form-embed";
+import { FormActivity } from "./form-activity";
+import { FormBackfill } from "./form-backfill";
+import { FormGroups } from "./form-groups";
 import { FormMappingEditor } from "./form-mapping-editor";
+import { FormRouteHistory } from "./form-route-history";
+import { FormSavedViews } from "./form-saved-views";
+import { MoreRows } from "./more-rows";
 import { SiteAuditPanel } from "./site-audit-panel";
+import { SubmissionsExport } from "./submissions-export";
 import { SubmissionsTable } from "./submissions-table";
 import { pluralWord } from "@/g8/lib/plural";
 import { useBrand } from "@/g8/hooks/use-brand";
@@ -53,12 +66,14 @@ import { useBrand } from "@/g8/hooks/use-brand";
 export interface FormsScreenProps {
   renderRowActions?: (form: FormListItem) => ReactNode;
   renderDetailActions?: (form: FormListItem) => ReactNode;
+  /** Extra buttons on an opened submission, next to its delivery state (open or add the person who submitted it). */
+  renderSubmissionActions?: (submission: FormSubmission, form: FormListItem) => ReactNode;
   extraDetailTabs?: { id: string; label: string; render: (form: FormListItem) => ReactNode }[];
   toolbarActions?: ReactNode;
   className?: string;
 }
 
-type Tab = "forms" | "install" | "audit";
+type Tab = "forms" | "install" | "audit" | "groups";
 const LIMIT = 100;
 /** How many of a form's latest submissions a deep link is looked up in. */
 const SUBMISSION_LOOKUP = 100;
@@ -151,7 +166,7 @@ function SubmissionNotFound({ form, submissionId }: { form: FormRef; submissionI
 }
 
 /** One submission in full: every submitted field, where it came from, its delivery, and the trace. */
-function SubmissionDetail({ form, submission, onChanged }: { form: FormRef; submission: FormSubmission; onChanged: () => void }) {
+function SubmissionDetail({ form, submission, onChanged, actions }: { form: FormRef; submission: FormSubmission; onChanged: () => void; actions?: ReactNode }) {
   const [retrying, setRetrying] = useState(false);
   const trace = useG8Query(
     (signal) => g8Get<{ capture_state?: string; receipts?: unknown[] }>(`/forms/${encodeURIComponent(form.form_key)}/submissions/${encodeURIComponent(submission.id)}/trace`, { source_id: form.source_id }, { signal }).then((r) => r.data),
@@ -167,6 +182,7 @@ function SubmissionDetail({ form, submission, onChanged }: { form: FormRef; subm
         <StatusPill tone={failed ? "negative" : submissionState(submission) === "delivered" ? "positive" : "neutral"}>{submissionState(submission)}</StatusPill>
         {submission.is_test ? <StatusPill tone="info">Test</StatusPill> : null}
         {failed && submission.delivery?.receipt_id ? <Button size="sm" variant="outline" onClick={() => { retry.reset(); setRetrying(true); }}>Retry delivery</Button> : null}
+        {actions}
       </div>
       <SectionCard title="Submitted fields">
         {fields.length === 0 ? <p className="text-muted-foreground text-sm">No fields were captured. Identifying fields may be redacted for your key.</p> : (
@@ -205,10 +221,10 @@ function SubmissionDetail({ form, submission, onChanged }: { form: FormRef; subm
   );
 }
 
-export function FormsScreen({ renderRowActions, renderDetailActions, extraDetailTabs, toolbarActions, className }: FormsScreenProps) {
+export function FormsScreen({ renderRowActions, renderDetailActions, renderSubmissionActions, extraDetailTabs, toolbarActions, className }: FormsScreenProps) {
   const brand = useBrand();
   const [tabParam, setTabParam] = useUrlState("tab", "forms");
-  const tab: Tab = tabParam === "install" || tabParam === "audit" ? tabParam : "forms";
+  const tab: Tab = tabParam === "install" || tabParam === "audit" || tabParam === "groups" ? tabParam : "forms";
   const setTab = (next: Tab): void => setTabParam(next === "forms" ? null : next);
   const [selectedKey, setSelectedKey] = useUrlState("id", "");
   const [view, setView] = useUrlState("view", "");
@@ -227,12 +243,18 @@ export function FormsScreen({ renderRowActions, renderDetailActions, extraDetail
   }, [text]);
 
   const closeForm = (): void => { setView(null); setSelectedKey(null); setSubmissionId(null); setOpenedSubmission(null); };
-  const forms = useG8Query(
-    (signal) => g8Get<{ items?: FormListItem[]; total?: number }>("/forms", { page: 1, per_page: LIMIT, search: search || undefined }, { signal }).then((r) => ({ items: pickItems<FormListItem>(r.data, "items"), total: (r.data as { total?: number } | undefined)?.total ?? 0 })),
-    [search],
-  );
-  const items = forms.data?.items ?? [];
-  const total = forms.data?.total ?? items.length;
+  // Every page of forms is reachable: the list loads LIMIT at a time and "Load more" appends the next page.
+  const [apiTotal, setTotal] = useState(0);
+  const forms = usePaginated<FormListItem>(async (cursor, signal) => {
+    const page = cursor ? Number(cursor) : 1;
+    const r = await g8Get<{ items?: FormListItem[]; total?: number }>("/forms", { page, per_page: LIMIT, search: search || undefined }, { signal });
+    const got = pickItems<FormListItem>(r.data, "items");
+    const all = (r.data as { total?: number } | undefined)?.total ?? 0;
+    setTotal(all);
+    return pageOf(got, got.length > 0 && page * LIMIT < all ? page + 1 : null);
+  }, [search]);
+  const items = forms.items;
+  const total = apiTotal || items.length;
   const shown = items.filter((f) => !health || formStatus(f) === health);
   const ref = parseRef(selectedKey);
   const selected: FormListItem | undefined = ref ? (items.find((f) => f.form_key === ref.form_key && f.source_id === ref.source_id) ?? { id: `${ref.source_id}:${ref.form_key}`, ...ref }) : undefined;
@@ -250,7 +272,7 @@ export function FormsScreen({ renderRowActions, renderDetailActions, extraDetail
   );
   const linkedSubmission: FormSubmission | null = !submissionId ? null : openedSubmission?.id === submissionId ? openedSubmission : ((lookup.data ?? []).find((x) => x.id === submissionId) ?? null);
 
-  const rows = forms.error ? <ApiError error={forms.error} title="Could not load forms" onRetry={() => void forms.refetch()} /> : forms.loading && !forms.data ? (
+  const rows = forms.error ? <ApiError error={forms.error} title="Could not load forms" onRetry={() => void forms.reload()} /> : forms.loading && forms.items.length === 0 ? (
     <div aria-busy="true" className="grid gap-2"><Skeleton className="h-16 w-full" /><Skeleton className="h-16 w-full" /><Skeleton className="h-16 w-full" /></div>
   ) : shown.length === 0 ? (
     <EmptyState
@@ -278,7 +300,7 @@ export function FormsScreen({ renderRowActions, renderDetailActions, extraDetail
           </li>
         );
       })}
-      {total > items.length ? <li className="text-muted-foreground text-xs">Showing the first {items.length} of {total.toLocaleString()} forms. Search to narrow down.</li> : null}
+      {forms.hasMore ? <li><MoreRows shown={items.length} noun={`of ${total.toLocaleString()} forms`} hasMore loading={forms.loadingMore} onMore={() => void forms.loadMore()} /></li> : null}
     </ul>
   );
 
@@ -291,9 +313,21 @@ export function FormsScreen({ renderRowActions, renderDetailActions, extraDetail
       onClose={() => closeForm()}
       {...expandProps}
       tabs={[
-        { id: "overview", label: "Overview", content: <FormOverviewTab key={refKey(selected)} form={selected} onChanged={() => void forms.refetch()} /> },
-        { id: "setup", label: "Destination and fields", content: <FormMappingEditor key={refKey(selected)} form={selected} onSaved={() => void forms.refetch()} /> },
-        { id: "submissions", label: "Submissions", content: <SubmissionsTable key={`${refKey(selected)}:${subsRefresh}`} form={selected} selectedId={submissionId || undefined} onOpen={(sub) => { setOpenedSubmission(sub); setSubmissionId(sub.id); }} /> },
+        { id: "overview", label: "Overview", content: <FormOverviewTab key={refKey(selected)} form={selected} onChanged={() => void forms.reload()} /> },
+        { id: "setup", label: "Destination and fields", content: <FormMappingEditor key={refKey(selected)} form={selected} onSaved={() => void forms.reload()} /> },
+        { id: "submissions", label: "Submissions", content: (
+          <div className="grid gap-3">
+            <SubmissionsExport form={selected} />
+            <SubmissionsTable key={`${refKey(selected)}:${subsRefresh}`} form={selected} selectedId={submissionId || undefined} onOpen={(sub) => { setOpenedSubmission(sub); setSubmissionId(sub.id); }} />
+          </div>
+        ) },
+        { id: "routing", label: "Routing", content: (
+          <div className="grid gap-4">
+            <FormBackfill key={`b${refKey(selected)}`} form={selected} />
+            <FormRouteHistory key={`r${refKey(selected)}`} form={selected} onChanged={() => void forms.reload()} />
+          </div>
+        ) },
+        { id: "activity", label: "Activity", content: <FormActivity key={refKey(selected)} form={selected} /> },
         ...(extraDetailTabs ?? []).map((t) => ({ id: t.id, label: t.label, content: t.render(selected) })),
       ]}
     />
@@ -305,7 +339,7 @@ export function FormsScreen({ renderRowActions, renderDetailActions, extraDetail
       title="Forms"
       description="Capture the forms already on your site, route every lead to a list, and watch what arrives."
       icon={<ClipboardList className="size-5" />}
-      tabs={[{ id: "forms", label: "Forms", count: total }, { id: "install", label: "Install" }, { id: "audit", label: "Site audit" }]}
+      tabs={[{ id: "forms", label: "Forms", count: total }, { id: "groups", label: "Groups" }, { id: "install", label: "Install" }, { id: "audit", label: "Site audit" }]}
       activeTab={tab}
       onTabChange={(id) => { setTab(id as Tab); closeForm(); }}
       stats={tab === "forms" ? [
@@ -315,6 +349,7 @@ export function FormsScreen({ renderRowActions, renderDetailActions, extraDetail
         { label: "Need setup", value: items.filter((f) => formStatus(f) === "needs_setup").length.toLocaleString(), tone: "info" },
       ] : undefined}
       toolbar={tab === "forms" ? (
+        <>
         <Toolbar
           search={{ value: text, onChange: setText, placeholder: "Search forms" }}
           filters={(
@@ -325,6 +360,8 @@ export function FormsScreen({ renderRowActions, renderDetailActions, extraDetail
           )}
           actions={toolbarActions}
         />
+        <FormSavedViews className="mt-2" search={text} health={health} onApply={(v) => { setText(v.search); setSearch(v.search.trim()); setHealth(v.health); }} />
+        </>
       ) : undefined}
     >
       <FormSheet
@@ -335,7 +372,7 @@ export function FormsScreen({ renderRowActions, renderDetailActions, extraDetail
       >
         {selected && submissionId ? (
           linkedSubmission ? (
-            <SubmissionDetail key={submissionId} form={selected} submission={linkedSubmission} onChanged={() => setSubsRefresh((n) => n + 1)} />
+            <SubmissionDetail key={submissionId} form={selected} submission={linkedSubmission} onChanged={() => setSubsRefresh((n) => n + 1)} actions={renderSubmissionActions?.(linkedSubmission, selected)} />
           ) : lookup.error ? (
             <ApiError error={lookup.error} title="Could not load this submission" onRetry={() => void lookup.refetch()} />
           ) : lookup.loading || !lookup.data ? (
@@ -345,7 +382,7 @@ export function FormsScreen({ renderRowActions, renderDetailActions, extraDetail
           )
         ) : null}
       </FormSheet>
-      {tab === "install" ? <FormEmbed /> : tab === "audit" ? <SiteAuditPanel /> : (
+      {tab === "install" ? <FormEmbed /> : tab === "audit" ? <SiteAuditPanel /> : tab === "groups" ? <FormGroups /> : (
         <SplitView list={rows} detail={detail} detailOpen={Boolean(selected)} onCloseDetail={() => closeForm()} expanded={view === "full"} onExpandedChange={(e) => setView(e ? "full" : null)} detailWidth="xl" />
       )}
     </ScreenLayout>

package/blocks/forms/components/more-rows.tsx

@@ -0,0 +1,30 @@
+"use client";
+
+/**
+ * MoreRows: the honest end of a list that the API pages. Shows how many rows are on screen and, while the API has
+ * another page, a "Load more" button. A list never ends silently: either every row is reachable or this says there are more.
+ * (Same contract as the foundation's LoadMore; kept local so the forms block does not wait on it.)
+ *
+ * SDK operations: none.
+ */
+import { Button } from "@graph8/sdk/ui";
+
+export interface MoreRowsProps {
+  /** Rows on screen. */
+  shown: number;
+  /** What the rows are, plural: "people". */
+  noun: string;
+  hasMore: boolean;
+  loading?: boolean;
+  onMore: () => void;
+}
+
+export function MoreRows({ shown, noun, hasMore, loading, onMore }: MoreRowsProps) {
+  if (!hasMore) return null;
+  return (
+    <div className="text-muted-foreground flex items-center justify-between gap-3 py-2 text-sm">
+      <span role="status">Showing {shown.toLocaleString()} {noun}</span>
+      <Button type="button" variant="outline" size="sm" loading={loading} onClick={onMore}>Load more</Button>
+    </div>
+  );
+}

package/blocks/forms/components/submissions-export.tsx

@@ -0,0 +1,67 @@
+"use client";
+
+/**
+ * SubmissionsExport: download a form's submissions as a CSV file (one column per submitted field).
+ *
+ * SDK operations:
+ *   1. searchFormSubmissions  POST /forms/{form_key}/submissions { page, per_page: 100, source_id }   (read; every page is fetched in turn)
+ *
+ * The export fetches up to `maxRows` submissions (default 5,000) and says so when the form has more: a truncated file
+ * is never presented as the whole thing. Identifying fields are redacted for keys without the Signals write capability,
+ * and the file carries the redacted values. Cells that start with = + - or @ are prefixed with ' so a spreadsheet does
+ * not run them as formulas.
+ */
+import { useState } from "react";
+import { Download } from "lucide-react";
+import { Button } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { g8Post } from "@/g8/lib/g8-client";
+import { submissionState } from "../lib/form-types";
+import type { FormRef, FormSubmission } from "../lib/form-types";
+import { submissionsCsv } from "../lib/forms-extra";
+
+export interface SubmissionsExportProps {
+  form: FormRef;
+  /** The most submissions one file holds. Default 5000. */
+  maxRows?: number;
+  className?: string;
+}
+
+const PER_PAGE = 100;
+
+export function SubmissionsExport({ form, maxRows = 5000, className }: SubmissionsExportProps) {
+  const [note, setNote] = useState("");
+  const run = useG8Mutation(async () => {
+    const rows: FormSubmission[] = [];
+    let total = 0;
+    for (let page = 1; rows.length < maxRows; page += 1) {
+      setNote(`Collecting submissions: ${rows.length.toLocaleString()}${total ? ` of ${total.toLocaleString()}` : ""}`);
+      const res = await g8Post<unknown>(`/forms/${encodeURIComponent(form.form_key)}/submissions`, { page, per_page: PER_PAGE, source_id: form.source_id });
+      const d = res.data as { submissions?: { items?: FormSubmission[]; total?: number }; items?: FormSubmission[]; total?: number } | undefined;
+      const block = d?.submissions ?? d;
+      const items = block?.items ?? [];
+      total = block?.total ?? total;
+      rows.push(...items);
+      if (items.length < PER_PAGE || (total && rows.length >= total)) break;
+    }
+    const file = rows.slice(0, maxRows);
+    const csv = submissionsCsv(file.map((s) => ({ id: s.id, received_at: s.received_at, is_test: s.is_test, delivery_state: submissionState(s), form_data: s.form_data })));
+    const url = URL.createObjectURL(new Blob([csv], { type: "text/csv;charset=utf-8" }));
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = `${form.form_key.replace(/[^a-z0-9-_]+/gi, "-").toLowerCase() || "form"}-submissions.csv`;
+    a.click();
+    URL.revokeObjectURL(url);
+    setNote(total > file.length ? `Downloaded the first ${file.length.toLocaleString()} of ${total.toLocaleString()} submissions. The file does not hold the rest.` : `Downloaded ${file.length.toLocaleString()} submissions.`);
+  });
+  return (
+    <div className={className}>
+      <div className="flex items-center gap-3">
+        <Button size="sm" variant="outline" loading={run.loading} onClick={() => void run.mutate(undefined)}><Download className="size-4" />Export CSV</Button>
+        {note ? <span role="status" className="text-muted-foreground text-xs">{note}</span> : null}
+      </div>
+      {run.error ? <ApiError error={run.error} title="Could not export the submissions" /> : null}
+    </div>
+  );
+}

package/blocks/forms/components/submissions-table.tsx

@@ -18,6 +18,7 @@ import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
 import { EmptyState } from "@/g8/components/empty-state";
 import { g8Get, g8Post } from "@/g8/lib/g8-client";
 import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useAllPages } from "@/g8/hooks/use-all-pages";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
 import { cellText, pickItems, submissionFailed, submissionState } from "../lib/form-types";
 import type { FormRef, FormSubmission } from "../lib/form-types";
@@ -64,19 +65,27 @@ function SubmissionTrace({ form, submission, onClose }: { form: FormRef; submiss
   );
 }
 
+/** Forms per read: every page is read, so the form picker offers all of them. */
+const FORM_PAGE = 100;
+
 export function SubmissionsTable({ form: given, pageSize = 20, maxFieldColumns = 4, onOpen, selectedId }: SubmissionsTableProps) {
   const brand = useBrand();
   const [picked, setPicked] = useState<FormRef | undefined>(undefined);
-  const forms = useG8Query((signal) => g8Get<unknown>("/forms", { per_page: 100 }, { signal }).then((r) => pickItems<FormRef & { display_name?: string | null }>(r.data, "items")), [], { enabled: !given });
+  const forms = useAllPages<FormRef & { display_name?: string | null }>(async (page, signal) => {
+    const r = await g8Get<unknown>("/forms", { page, per_page: FORM_PAGE }, { signal });
+    const rows = pickItems<FormRef & { display_name?: string | null }>(r.data, "items");
+    const total = (r.data as { total?: number } | undefined)?.total;
+    return { rows, hasNext: typeof total === "number" ? page * FORM_PAGE < total : rows.length >= FORM_PAGE };
+  }, [], { enabled: !given });
   const form = given ?? picked;
   if (!form) {
     if (forms.error) return <ApiError error={forms.error} title="Could not load forms" onRetry={() => void forms.refetch()} />;
-    if (forms.loading && !forms.data) return <Skeleton className="h-9 w-64" aria-busy="true" />;
-    if ((forms.data ?? []).length === 0) return <EmptyState title="No forms captured yet" description={`Install the ${brand.linkLabel} snippet on your site; forms appear after their first submission.`} />;
+    if (forms.loading && !forms.loaded) return <Skeleton className="h-9 w-64" aria-busy="true" />;
+    if (forms.items.length === 0) return <EmptyState title="No forms captured yet" description={`Install the ${brand.linkLabel} snippet on your site; forms appear after their first submission.`} />;
     return (
-      <select aria-label="Choose a form" className="border-input bg-background h-9 max-w-sm rounded-md border px-2 text-sm" defaultValue="" onChange={(e) => { const f = forms.data?.[Number(e.target.value)]; if (f) setPicked({ form_key: f.form_key, source_id: f.source_id }); }}>
+      <select aria-label="Choose a form" className="border-input bg-background h-9 max-w-sm rounded-md border px-2 text-sm" defaultValue="" onChange={(e) => { const f = forms.items[Number(e.target.value)]; if (f) setPicked({ form_key: f.form_key, source_id: f.source_id }); }}>
         <option value="" disabled>Choose a form</option>
-        {(forms.data ?? []).map((f, i) => <option key={`${f.source_id}:${f.form_key}`} value={i}>{f.display_name || f.form_key}</option>)}
+        {forms.items.map((f, i) => <option key={`${f.source_id}:${f.form_key}`} value={i}>{f.display_name || f.form_key}</option>)}
       </select>
     );
   }
@@ -136,7 +145,7 @@ function SubmissionsFor({ form, pageSize, maxFieldColumns, onOpen, selectedId }:
                 ) : <>{s.received_at ? new Date(s.received_at).toLocaleString() : ""}{s.is_test ? " (test)" : ""}</>}
               </TableCell>
               {columns.map((c) => <TableCell key={c}>{cellText(s.form_data?.[c])}</TableCell>)}
-              <TableCell className={submissionFailed(s) ? "text-red-700" : undefined}>{submissionState(s)}</TableCell>
+              <TableCell className={submissionFailed(s) ? "text-error-foreground" : undefined}>{submissionState(s)}</TableCell>
               <TableCell className="text-right">
                 <Button size="sm" variant="ghost" onClick={() => setTraceOf(s)}>Trace</Button>
                 {submissionFailed(s) && s.delivery?.receipt_id ? <Button size="sm" variant="ghost" onClick={() => { retry.reset(); setRetrying(s); }}>Retry</Button> : null}

package/blocks/forms/lib/forms-extra.ts

@@ -0,0 +1,67 @@
+"use client";
+
+/**
+ * Helpers for the forms management components (groups, activity, backfill, route history, saved views, export).
+ * These endpoints return open dicts, so every reader accepts what is present and ignores the rest.
+ */
+import type { PaginatedResponse } from "@graph8/sdk";
+
+export type Rec = Record<string, unknown>;
+
+export function asRec(value: unknown): Rec {
+  return value && typeof value === "object" && !Array.isArray(value) ? (value as Rec) : {};
+}
+
+export function str(value: unknown, fallback = ""): string {
+  return typeof value === "string" ? value : value == null ? fallback : String(value);
+}
+
+export function num(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+export function rowsOf<T = Rec>(data: unknown, ...keys: string[]): T[] {
+  if (Array.isArray(data)) return data as T[];
+  const rec = asRec(data);
+  for (const key of [...keys, "items"]) if (Array.isArray(rec[key])) return rec[key] as T[];
+  return [];
+}
+
+/** Wrap rows and the API's "next" marker (a page number, cursor or offset; null when there is no more) for `usePaginated`. */
+export function pageOf<T>(rows: T[], next: unknown): PaginatedResponse<T> {
+  return { data: rows, pagination: { next_cursor: next == null || next === "" ? null : String(next) } } as unknown as PaginatedResponse<T>;
+}
+
+export const when = (v: unknown): string => {
+  const d = new Date(str(v));
+  return Number.isNaN(d.getTime()) ? "" : d.toLocaleString();
+};
+
+/** `YYYY-MM-DD` from a date input to the UTC instant the API takes: start of that day, or the start of the NEXT day for an inclusive end. */
+export function dayInstant(day: string, endOfDay = false): string | undefined {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(day)) return undefined;
+  const d = new Date(`${day}T00:00:00Z`);
+  if (Number.isNaN(d.getTime())) return undefined;
+  if (endOfDay) d.setUTCDate(d.getUTCDate() + 1);
+  return d.toISOString();
+}
+
+/** A member of a form group, under whichever key names it used. */
+export function memberRef(m: Rec): { form_key: string; source_id: string } {
+  return { form_key: str(m.form_key), source_id: str(m.source_id) || str(m.source_key) };
+}
+
+/** One CSV cell: quoted when it holds a comma, quote or newline, and guarded against spreadsheet formulas. */
+export function csvCell(value: unknown): string {
+  let s = value == null ? "" : typeof value === "object" ? JSON.stringify(value) : String(value);
+  if (/^[=+\-@\t\r]/.test(s)) s = `'${s}`;
+  return /[",\n\r]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+}
+
+/** The CSV text for submissions: a fixed leading set of columns, then every submitted field seen, in first-seen order. */
+export function submissionsCsv(rows: Array<{ id: string; received_at?: string; is_test?: boolean; delivery_state: string; form_data?: Record<string, unknown> }>): string {
+  const fields = [...new Set(rows.flatMap((r) => Object.keys(r.form_data ?? {})))];
+  const head = ["submission_id", "received_at", "test", "delivery", ...fields];
+  const lines = rows.map((r) => [r.id, r.received_at ?? "", r.is_test ? "yes" : "no", r.delivery_state, ...fields.map((f) => r.form_data?.[f])].map(csvCell).join(","));
+  return [head.map(csvCell).join(","), ...lines].join("\r\n");
+}