@graph8/sdk 0.370.0 → 0.373.0

package/README.md

@@ -512,6 +512,25 @@ npx @graph8/sdk create mailchimp my-app   # then: cd my-app && cp .env.local.exa
 
 Every available stack is proven by `npm run build && npm run e2e:create -- <stack>`, which packs the SDK, scaffolds the app with the built CLI, installs it and requires `next build` to pass. More stacks appear here as their blocks land; `create` refuses a stack that is not available yet.
 
+### Branding: your Brand Kit, automatically
+
+If your graph8 organization already has a Brand Kit (Studio), `create` uses it. With a key in `G8_API_KEY` (environment or `.env.local`), the new app gets your organization's name, primary colour and logo without any flags; the logo is downloaded into `public/brand/` (never hot-linked), and the colour becomes `--brand` / `--primary` with button text checked for WCAG AA.
+
+```bash
+G8_API_KEY=... npx @graph8/sdk create apollo my-app           # picks up the Brand Kit
+npx @graph8/sdk create apollo my-app --no-org-brand            # skip it
+npx @graph8/sdk create apollo my-app --brand-color "#0f62fe"   # your colour wins; the kit still fills the name and logo
+npx @graph8/sdk brand --from-org                               # brand an existing app from the kit
+```
+
+| Brand Kit field (Developer API) | App brand input |
+|---|---|
+| `GET /me` `org_name` | `--name` (`g8.config.ts` `name`) |
+| `GET /brand-kit` `design_tokens.colors.primary` (else `brand`, `accent`, button background) | `--brand-color` |
+| `GET /brand-kit` `logo_url` (one logo; no light, dark or icon variant) | `--logo` (`public/brand/logo.*`) |
+
+Explicit flags always win, field by field. With no key, a missing or empty kit, no `campaigns:read` scope or no network, the app keeps the default look and the CLI prints one info line; it never fails. The key is never printed or written. Fonts, tagline and voice traits are in the kit but have no brand input, so they are not applied. Icons stay Lucide.
+
 ## UI kit (`@graph8/sdk/ui`)
 
 The React component kit and design tokens behind the graph8 app (primitives, light and dark

package/blocks/_foundation/README.md

@@ -238,6 +238,20 @@ Rules the kit encodes, so screens stay consistent:
 - Loading is visible and distinct from empty: `StatStrip loading`, `Skeleton` rows.
 - Dates show short text; the full timestamp is the `title` of a `<time dateTime>`.
 
+## Long lists: paging, notices and filters (no silent truncation)
+
+A list read that sends a `limit` must page or say it stopped. The foundation ships the pieces:
+
+| Need | Use |
+|---|---|
+| Show rows with a "Load more" button (the API pages by `page` or `offset`) | `useLoadMoreList(byPage(size, read))` or `byOffset(size, read)` (`lib/paging.ts`), then `<LoadMore>` under the rows |
+| The API has only a `limit` (no paging) | `<FirstNotice shown={rows.length} limit={LIMIT} noun="mailboxes" />`: "Showing the first N ..." appears only when the read came back full |
+| A screen needs EVERY row (a lookup by id, a full dropdown) | `useAllPages(read, deps)`: reads page after page, reports `truncated` if the page cap cut it short |
+| Choose one audience list | crm's `ListSelect`: a native select with server search and "Load more lists" |
+| Filters for a list screen | `useUrlFilters(keys, { prefix })` keeps them in the URL (`c_email=...`); `TextFilter`, `SelectFilter`, `RangeFilter` and `MoreFilters` (a "More filters" disclosure) go in the Toolbar `filters` slot |
+
+`tests/blocks/list-paging-guard.test.ts` in the SDK repo fails on a new `g8Get(..., { limit })` read that does none of these.
+
 ## Prerequisites
 
 - `G8_API_KEY` in the server env; verify with `recipes/verify-proxy-key.ts`.

package/blocks/_foundation/block.json

@@ -155,6 +155,27 @@
       "purpose": "White-label context: the app's name, logo, and what the platform is called and where it lives, for every block's copy and link-outs. Fields left out stay graph8's.",
       "operations": [],
       "tiers": []
+    },
+    {
+      "name": "ListSelect",
+      "file": "components/list-select.tsx",
+      "purpose": "Audience-list dropdown, searchable and paged (native select + server search + Load more). It owns no API call: the block that uses it passes a `read` (crm ships ListSelect with the /lists read wired in).",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "FirstNotice",
+      "file": "components/paging-notices.tsx",
+      "purpose": "FirstNotice (\"Showing the first N ...\" when a read without paging came back full) and LoadMore (\"Showing N\" + Load more): the two honest endings of a capped list.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "TextFilter",
+      "file": "components/screen/filter-controls.tsx",
+      "purpose": "Toolbar filter controls: TextFilter, SelectFilter, RangeFilter (from/to) and MoreFilters (a disclosure that opens by itself when a hidden filter is set).",
+      "operations": [],
+      "tiers": []
     }
   ],
   "hooks": [
@@ -192,6 +213,21 @@
       "name": "useBrand",
       "file": "hooks/use-brand.ts",
       "purpose": "The current brand ({ name, appUrl, linkLabel, logo }) from the nearest BrandProvider, else graph8's defaults; brandUrl(brand, path) builds a link-out."
+    },
+    {
+      "name": "useAllPages",
+      "file": "hooks/use-all-pages.ts",
+      "purpose": "Read every page of a list a screen needs in full (lookups, full dropdowns), up to a page cap, and report when the cap cut it short."
+    },
+    {
+      "name": "useLoadMoreList",
+      "file": "hooks/use-load-more-list.ts",
+      "purpose": "A list read with Load more: the shape of a useG8Query list (data, loading, error, refetch) plus hasMore / loadMore. Pair with byPage / byOffset and the LoadMore notice."
+    },
+    {
+      "name": "useUrlFilters",
+      "file": "hooks/use-url-filters.ts",
+      "purpose": "List-screen filters kept in the URL (debounced, prefixed, SSR-safe): draft for the inputs, query for the read, clear()."
     }
   ],
   "lib": [
@@ -218,6 +254,14 @@
     {
       "file": "lib/plural.ts",
       "purpose": "plural(n, 'contact') -> '1 contact' / '2 contacts' (and pluralWord): one correct plural helper for titles, counts and bulk dialogs."
+    },
+    {
+      "file": "lib/paging.ts",
+      "purpose": "byPage / byOffset adapt page-number and offset lists to usePaginated's cursor shape; hasNextOf reads the API's has_next / next_cursor."
+    },
+    {
+      "file": "lib/use-debounced-value.ts",
+      "purpose": "useDebounced: a value after it stopped changing (foundation-local copy)."
     }
   ],
   "server": [

package/blocks/_foundation/components/confirm-spend-dialog.tsx

@@ -39,6 +39,13 @@ const TIER_COPY: Record<ConfirmTier, { badge: string; confirm: string; note: str
 };
 
 /** True for the tiers an app should confirm before calling. read/write never need it. */
+/** The tier badge: ember for what cannot be undone, ochre for spend and outreach. Token classes only. */
+const TIER_BADGE: Record<ConfirmTier, string> = {
+  billable: "bg-warning text-warning-foreground",
+  external: "bg-warning text-warning-foreground",
+  destructive: "bg-error text-error-foreground",
+};
+
 export function tierRequiresConfirmation(tier: string): tier is ConfirmTier {
   return tier === "billable" || tier === "external" || tier === "destructive";
 }
@@ -83,7 +90,7 @@ export function ConfirmSpendDialog(props: ConfirmSpendDialogProps) {
         showCloseButton={false}
         data-tier={tier}
         style={interactive}
-        className={`max-w-md sm:max-w-md bg-white p-5 shadow-xl ${props.className ?? ""}`}
+        className={`max-w-md gap-4 border-border bg-background p-5 shadow-xl sm:max-w-md ${props.className ?? ""}`}
         onOpenAutoFocus={(event) => {
           event.preventDefault();
           openerRef.current = document.activeElement instanceof HTMLElement ? document.activeElement : null;
@@ -98,15 +105,15 @@ export function ConfirmSpendDialog(props: ConfirmSpendDialogProps) {
         onInteractOutside={(event) => event.preventDefault()}
         onEscapeKeyDown={(event) => confirming && event.preventDefault()}
       >
-        <span className="inline-block w-fit rounded bg-gray-100 px-2 py-0.5 text-xs font-medium text-gray-700">
+        <span className={`inline-flex h-5 w-fit items-center rounded-full px-2 text-[11px] font-medium leading-none ${TIER_BADGE[tier]}`}>
           {copy.badge}
         </span>
-        <DialogTitle className="text-base font-semibold text-gray-900">{title}</DialogTitle>
+        <DialogTitle className="text-base font-medium leading-6 text-foreground">{title}</DialogTitle>
         <DialogDescription asChild>
-          <div className="space-y-2 text-sm text-gray-600">
+          <div className="space-y-2 text-sm leading-5 text-muted-foreground">
             {description ? <div>{description}</div> : null}
             {summary.length > 0 ? (
-              <ul className="list-disc pl-5 text-gray-900">
+              <ul className="list-disc space-y-0.5 pl-5 tabular-nums text-foreground">
                 {summary.map((line) => (
                   <li key={line}>{line}</li>
                 ))}
@@ -115,14 +122,14 @@ export function ConfirmSpendDialog(props: ConfirmSpendDialogProps) {
             <p>{copy.note}</p>
           </div>
         </DialogDescription>
-        <div className="flex justify-end gap-2">
+        <div className="flex justify-end gap-2 pt-1">
           <button
             ref={cancelRef}
             type="button"
             disabled={confirming}
             onClick={onCancel}
             style={interactive}
-            className="rounded border border-gray-300 px-3 py-1.5 text-sm text-gray-700 disabled:opacity-50"
+            className="inline-flex h-8 items-center rounded-md border border-border bg-background px-3 text-sm font-medium text-foreground transition-colors hover:bg-surface-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
           >
             {props.cancelLabel ?? "Cancel"}
           </button>
@@ -131,7 +138,7 @@ export function ConfirmSpendDialog(props: ConfirmSpendDialogProps) {
             disabled={confirming}
             onClick={onConfirm}
             style={interactive}
-            className="rounded bg-gray-900 px-3 py-1.5 text-sm font-medium text-white disabled:opacity-50"
+            className={`inline-flex h-8 items-center rounded-md px-3 text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:opacity-50 ${tier === "destructive" ? "bg-destructive text-destructive-foreground hover:bg-destructive/90" : "bg-primary text-primary-foreground hover:bg-primary/90"}`}
           >
             {confirming ? "Working..." : (props.confirmLabel ?? copy.confirm)}
           </button>

package/blocks/_foundation/components/empty-state.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import type { ReactNode } from "react";
+import { Inbox } from "lucide-react";
 import { cn } from "@graph8/sdk/ui";
 
 export interface EmptyStateProps {
@@ -24,6 +25,8 @@ export interface EmptyStateProps {
  * these filters.", with a Clear filters action). An ink icon in a quiet well, one sentence, one action.
  */
 export function EmptyState({ title, description, action, icon, className, secondaryAction, compact, bordered }: EmptyStateProps) {
+  // No icon passed: a quiet default, so an empty area never reads as a blank page. `icon={null}` hides it.
+  const mark = icon === undefined ? <Inbox strokeWidth={1.5} /> : icon;
   return (
     <div
       role="status"
@@ -35,12 +38,12 @@ export function EmptyState({ title, description, action, icon, className, second
         className,
       )}
     >
-      {icon ? (
+      {mark ? (
         <div
           aria-hidden
           className="mb-1 flex size-10 items-center justify-center rounded-lg border border-border bg-muted text-foreground [&_svg]:size-5 [&_svg]:stroke-[1.5]"
         >
-          {icon}
+          {mark}
         </div>
       ) : null}
       <h3 className="text-sm font-medium text-foreground">{title}</h3>

package/blocks/_foundation/components/list-select.tsx

@@ -0,0 +1,112 @@
+"use client";
+
+/**
+ * ListSelect: the audience-list dropdown, searchable and paged. It replaces a `<select>` fed by one capped
+ * `GET /lists?limit=200` read, which could not reach the 201st list. It is still a native `<select>` (keyboard,
+ * mobile and form behaviour unchanged, and the same accessible name the old select had), now with:
+ *
+ *  - paging: `pageSize` lists per read (default 100); "Load more lists" appends the next page, nothing is dropped;
+ *  - search: once there is more than one page, a "Search lists" box looks lists up on the server (`search=`);
+ *  - the chosen list always stays an option, even when it is not on a loaded page (`valueLabel` names it).
+ *
+ * The paging engine is useLoadMoreList (the same byPage / hasNextOf contract ContactPicker's usePickerPages follows).
+ * It lives in foundation, not in the opt-in pickers block, so crm / forms / newsletter / nurture / sequencer can use
+ * it without a new block dependency.
+ *
+ * SDK operations: none here. The foundation holds no API scope of its own, so the list read comes in as `read`; the crm block
+ * ships a ready-made `ListSelect` (@/g8/crm/components/list-select) that passes GET /lists?search&page&limit (listLists, read).
+ */
+import { useEffect, useRef, useState } from "react";
+import { Button, Input } from "@graph8/sdk/ui";
+import { byPage } from "../lib/paging";
+import type { RowsPage } from "../lib/paging";
+import { useLoadMoreList } from "../hooks/use-load-more-list";
+import { ApiError } from "./api-error";
+
+/** A list as a select option. */
+export interface ListSelectOption {
+  id: number;
+  title: string;
+  type?: string | null;
+  contact_count?: number | null;
+  company_count?: number | null;
+  total?: number | null;
+}
+
+/** Reads one page of lists: `q` is the server search, `page` starts at 1. */
+export type ListsReader = (q: string, page: number, pageSize: number, signal: AbortSignal) => Promise<RowsPage<ListSelectOption>>;
+
+export interface ListSelectProps {
+  /** Reads a page of lists (see crm's ListSelect, which wires GET /lists). */
+  read: ListsReader;
+  /** The chosen list id (controlled); "" / null / undefined = none. */
+  value?: number | string | null;
+  /** Called with the chosen list, or null when the blank option is chosen. */
+  onChange: (list: ListSelectOption | null) => void;
+  /** Accessible name of the select (what the old select was called). */
+  label: string;
+  /** Text of the blank option ("Audience list (required)"). */
+  emptyOption?: string;
+  /** Option text for a list; default the title. */
+  optionLabel?: (list: ListSelectOption) => string;
+  /** Hide lists of the other type. Default: every list. */
+  type?: "contacts" | "companies";
+  /** Lists per read. Default 100. */
+  pageSize?: number;
+  /** Name for `value` before its list has been loaded. */
+  valueLabel?: string;
+  /** Hold the read (for example until a wizard step is reached). Default true. */
+  enabled?: boolean;
+  disabled?: boolean;
+  /** Id of the select, so a <label htmlFor> can name it. */
+  id?: string;
+  className?: string;
+  /** Class of the select element itself. */
+  selectClassName?: string;
+}
+
+const SELECT = "border-input bg-background h-9 rounded-md border px-2 text-sm";
+
+export function ListSelect(props: ListSelectProps) {
+  const { read, value, onChange, label, emptyOption = "Choose a list", optionLabel, type, pageSize = 100, valueLabel, enabled = true, disabled, id, className, selectClassName } = props;
+  const [search, setSearch] = useState("");
+  const [q, setQ] = useState("");
+  useEffect(() => {
+    const t = setTimeout(() => setQ(search.trim()), 250);
+    return () => clearTimeout(t);
+  }, [search]);
+  const list = useLoadMoreList(byPage<ListSelectOption>(pageSize, async (page, signal) => {
+    const got = await read(q, page, pageSize, signal);
+    return { rows: got.rows.filter((l) => !type || !l.type || l.type === type), hasNext: got.hasNext };
+  }), [q, pageSize, type], { enabled });
+  // A page that held only lists of the other type is empty after the filter but the server may have more: keep going.
+  useEffect(() => { if (list.data && list.data.length === 0 && list.hasMore && !list.loadingMore && !list.loading) list.loadMore(); }, [list.data, list.hasMore, list.loadingMore, list.loading]); // eslint-disable-line react-hooks/exhaustive-deps
+  const pages = { rows: list.data ?? [], hasMore: list.hasMore, loadingMore: list.loadingMore, loadMore: list.loadMore, error: list.error, refetch: () => { void list.refetch(); }, q, search, setSearch };
+  const key = value == null ? "" : String(value);
+  const rows = pages.rows;
+  const known = rows.some((l) => String(l.id) === key);
+  const text = optionLabel ?? ((l: ListSelectOption) => l.title);
+  // The search box appears once the lists run past one page and then stays, so it does not vanish under the cursor.
+  const seenMore = useRef(false);
+  if (pages.hasMore) seenMore.current = true;
+  const searchable = seenMore.current || pages.q !== "" || pages.search !== "";
+  return (
+    <div className={`flex flex-col gap-1 ${className ?? ""}`}>
+      {searchable ? <Input type="text" aria-label="Search lists" placeholder="Search lists" value={pages.search} onChange={(e) => pages.setSearch(e.target.value)} className="h-8 text-sm" /> : null}
+      <select
+        id={id}
+        aria-label={label}
+        className={selectClassName ?? SELECT}
+        value={key}
+        disabled={disabled}
+        onChange={(e) => onChange(rows.find((l) => String(l.id) === e.target.value) ?? null)}
+      >
+        <option value="">{emptyOption}</option>
+        {key && !known ? <option value={key}>{valueLabel ?? `List ${key}`}</option> : null}
+        {rows.map((l) => <option key={l.id} value={l.id}>{text(l)}</option>)}
+      </select>
+      {pages.error ? <ApiError error={pages.error} title="Could not load lists" onRetry={pages.refetch} /> : null}
+      {pages.hasMore ? <Button type="button" variant="ghost" size="sm" loading={pages.loadingMore} onClick={pages.loadMore}>Load more lists</Button> : null}
+    </div>
+  );
+}

package/blocks/_foundation/components/paging-notices.tsx

@@ -0,0 +1,55 @@
+"use client";
+
+/**
+ * FirstNotice and LoadMore: the two honest answers to a list that is longer than one read.
+ *
+ *  - LoadMore: the API pages (page / offset / cursor): show how many rows are on screen and a "Load more" button.
+ *  - FirstNotice: the API has no paging for this list: when the read came back full, say "Showing the first N".
+ *
+ * A capped list must never end silently; one of these is on every list read that sends a limit.
+ * SDK operations: none.
+ */
+import { Button, cn } from "@graph8/sdk/ui";
+
+export interface FirstNoticeProps {
+  /** Rows on screen. */
+  shown: number;
+  /** The limit the read was sent with. */
+  limit: number;
+  /** What the rows are, plural: "mailboxes". */
+  noun: string;
+  /** Decide it yourself when the loader knows rows were cut off (useAllPages `truncated`): true shows, false hides, whatever the counts. */
+  force?: boolean;
+  className?: string;
+}
+
+/** Renders only when `shown` reached `limit` (a full read: there may be more), or when `force` says so. */
+export function FirstNotice({ shown, limit, noun, force, className }: FirstNoticeProps) {
+  if (!(force ?? shown >= limit)) return null;
+  return (
+    <p role="note" className={cn("text-xs text-muted-foreground", className)}>
+      Showing the first {(force ? shown : limit).toLocaleString()} {noun}. There may be more: narrow the list with a search or a filter to find the rest.
+    </p>
+  );
+}
+
+export interface LoadMoreProps {
+  /** Rows on screen. */
+  shown: number;
+  noun: string;
+  hasMore: boolean;
+  loading?: boolean;
+  onLoadMore: () => void;
+  className?: string;
+}
+
+/** "Showing 100 landing pages" with a "Load more" button while the API has another page. */
+export function LoadMore({ shown, noun, hasMore, loading, onLoadMore, className }: LoadMoreProps) {
+  if (!hasMore) return null;
+  return (
+    <div className={cn("flex items-center justify-between gap-3 py-2 text-sm text-muted-foreground", className)}>
+      <span role="status">Showing {shown.toLocaleString()} {noun}</span>
+      <Button type="button" variant="outline" size="sm" loading={loading} onClick={onLoadMore}>Load more</Button>
+    </div>
+  );
+}

package/blocks/_foundation/components/screen/detail-panel.tsx

@@ -71,7 +71,6 @@ export function DetailPanel({ title, subtitle, avatar, badges, actions, tabs, ac
             {badges ? <div className="mt-1.5 flex flex-wrap items-center gap-1.5">{badges}</div> : null}
           </div>
           <div className="flex shrink-0 items-center gap-1">
-            {actions}
             {onCollapse ? (
               <Button type="button" variant="ghost" size="icon" className="size-8 text-text-color-muted hover:text-foreground" aria-label="Back to split view" onClick={onCollapse}>
                 <Minimize2 className="size-4" strokeWidth={1.5} aria-hidden />
@@ -88,6 +87,8 @@ export function DetailPanel({ title, subtitle, avatar, badges, actions, tabs, ac
             ) : null}
           </div>
         </div>
+        {/* Record actions get their own row, so the record's name is never squeezed out by them. */}
+        {actions ? <div className="mt-3 flex flex-wrap items-center gap-1.5" data-testid="detail-panel-actions">{actions}</div> : null}
         {summary ? <div className="mt-3">{summary}</div> : null}
       </header>
       {tabs && tabs.length > 0 ? (

package/blocks/_foundation/components/screen/filter-controls.tsx

@@ -0,0 +1,92 @@
+"use client";
+
+/**
+ * Filter controls for a Toolbar: a text box, a select, a from/to range, and a "More filters" disclosure that keeps the
+ * toolbar to one row until a person asks for the rest (it opens by itself when a hidden filter is already set).
+ * They are plain controlled inputs; useUrlFilters keeps their values in the URL.
+ *
+ * SDK operations: none.
+ */
+import { useEffect, useState, type ReactNode } from "react";
+import { Button, cn } from "@graph8/sdk/ui";
+
+const BOX = "h-9 rounded-md border bg-background px-3 text-sm";
+
+export interface TextFilterProps {
+  label: string;
+  value: string;
+  onChange: (value: string) => void;
+  placeholder?: string;
+  type?: "text" | "number" | "date" | "email";
+  className?: string;
+}
+
+/** One text box; the accessible name is "Filter by <label>". */
+export function TextFilter({ label, value, onChange, placeholder, type = "text", className }: TextFilterProps) {
+  return <input type={type} aria-label={`Filter by ${label}`} placeholder={placeholder ?? label} className={cn(BOX, "w-36", className)} value={value} onChange={(e) => onChange(e.target.value)} />;
+}
+
+export interface SelectFilterProps {
+  label: string;
+  value: string;
+  onChange: (value: string) => void;
+  /** Text of the "no filter" option, for example "Any seniority". */
+  any: string;
+  options: ReadonlyArray<string | { value: string; label: string }>;
+  className?: string;
+}
+
+/** One select; the accessible name is "Filter by <label>". */
+export function SelectFilter({ label, value, onChange, any, options, className }: SelectFilterProps) {
+  return (
+    <select aria-label={`Filter by ${label}`} className={cn(BOX, "px-2", className)} value={value} onChange={(e) => onChange(e.target.value)}>
+      <option value="">{any}</option>
+      {options.map((o) => { const v = typeof o === "string" ? o : o.value; return <option key={v} value={v}>{typeof o === "string" ? o : o.label}</option>; })}
+    </select>
+  );
+}
+
+export interface RangeFilterProps {
+  label: string;
+  min: string;
+  max: string;
+  onMinChange: (value: string) => void;
+  onMaxChange: (value: string) => void;
+  type?: "number" | "date";
+  className?: string;
+}
+
+/** A from / to pair; the accessible names are "<label> from" and "<label> to". */
+export function RangeFilter({ label, min, max, onMinChange, onMaxChange, type = "number", className }: RangeFilterProps) {
+  return (
+    <span role="group" aria-label={label} className={cn("flex items-center gap-1", className)}>
+      <input type={type} aria-label={`${label} from`} placeholder={`${label} min`} className={cn(BOX, "w-28")} value={min} onChange={(e) => onMinChange(e.target.value)} />
+      <span className="text-muted-foreground text-xs" aria-hidden>to</span>
+      <input type={type} aria-label={`${label} to`} placeholder={`${label} max`} className={cn(BOX, "w-28")} value={max} onChange={(e) => onMaxChange(e.target.value)} />
+    </span>
+  );
+}
+
+export interface MoreFiltersProps {
+  /** How many of the hidden filters are set (shown on the button, and opens the panel when it is above zero at mount). */
+  activeCount: number;
+  children: ReactNode;
+  label?: string;
+  className?: string;
+}
+
+/** A "More filters" button and the second row of controls it reveals. Put it in Toolbar `filters`. */
+export function MoreFilters({ activeCount, children, label = "More filters", className }: MoreFiltersProps) {
+  const [open, setOpen] = useState(activeCount > 0);
+  // Filters adopted from the URL right after mount (a reload, a shared link) open the panel too.
+  const hasActive = activeCount > 0;
+  useEffect(() => { if (hasActive) setOpen(true); }, [hasActive]);
+  return (
+    <>
+      <Button type="button" variant="outline" size="sm" aria-expanded={open} onClick={() => setOpen((o) => !o)}>
+        {label}{activeCount > 0 ? ` (${activeCount})` : ""}
+      </Button>
+      {open ? <div role="group" aria-label={label} className={cn("flex w-full flex-wrap items-center gap-2", className)}>{children}</div> : null}
+    </>
+  );
+}

package/blocks/_foundation/components/screen/index.ts

@@ -9,6 +9,7 @@
 export * from "./bar-list";
 export * from "./detail-panel";
 export * from "./entity-avatar";
+export * from "./filter-controls";
 export * from "./form-sheet";
 export * from "./key-value-list";
 export * from "./screen-layout";

package/blocks/_foundation/components/screen/split-view.tsx

@@ -95,7 +95,7 @@ export function SplitView({ list, detail, detailOpen, onCloseDetail, detailWidth
 
   return (
     <div className={cn("flex h-full min-h-0 w-full min-w-0", className)} data-testid="split-view" data-detail-open={open ? "true" : "false"}>
-      <div className={cn("min-h-0 min-w-0 flex-1", listClassName)}>{list}</div>
+      <div className={cn("min-h-0 min-w-0 flex-1", listClassName)} data-g8-list="">{list}</div>
       {open && !narrow ? (
         <aside
           aria-label={detailTitle}

package/blocks/_foundation/hooks/use-all-pages.ts

@@ -0,0 +1,54 @@
+"use client";
+
+/**
+ * useAllPages: read every page of a list that a screen needs IN FULL (a lookup by id, a dropdown that must offer every
+ * row), instead of one call with a hopeful `limit`. Pages are fetched one after the other until the API says there is no
+ * next page, or `maxPages` is reached; then `truncated` is true and the screen must say so (see FirstNotice).
+ *
+ * It calls no operation itself: `fetchPage` does, so the caller's component declares the operation.
+ */
+import { useG8Query } from "./use-g8-query";
+import type { RowsPage } from "../lib/paging";
+
+export interface UseAllPagesOptions {
+  enabled?: boolean;
+  /** Stop after this many pages (default 20) so a runaway list cannot loop forever. */
+  maxPages?: number;
+  /** The page size you read with: when a page does not say `hasNext`, a full page of this size means "maybe more". */
+  pageSize?: number;
+}
+
+export interface UseAllPages<T> {
+  items: T[];
+  loading: boolean;
+  /** The first read has finished (a row list may still be empty). */
+  loaded: boolean;
+  error: unknown;
+  /** The page limit was reached with more rows still on the server: some rows are NOT in `items`. */
+  truncated: boolean;
+  refetch: () => void;
+}
+
+interface All<T> { items: T[]; truncated: boolean }
+
+export function useAllPages<T>(
+  fetchPage: (page: number, signal: AbortSignal) => Promise<RowsPage<T>>,
+  deps: readonly unknown[],
+  options: UseAllPagesOptions = {},
+): UseAllPages<T> {
+  const max = options.maxPages ?? 20;
+  const q = useG8Query<All<T>>(async (signal) => {
+    const items: T[] = [];
+    for (let page = 1; page <= max; page++) {
+      const got = await fetchPage(page, signal);
+      items.push(...got.rows);
+      if (got.hasNext === false || got.rows.length === 0) return { items, truncated: false };
+      if (got.hasNext === undefined && (options.pageSize === undefined || got.rows.length < options.pageSize)) return { items, truncated: false }; // could not tell, and not a full page
+    }
+    return { items, truncated: true };
+  }, deps, { enabled: options.enabled });
+  return { items: q.data?.items ?? EMPTY, loading: q.loading, loaded: q.data !== undefined, error: q.error, truncated: q.data?.truncated ?? false, refetch: () => { void q.refetch(); } };
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const EMPTY: any[] = [];

package/blocks/_foundation/hooks/use-load-more-list.ts

@@ -0,0 +1,61 @@
+"use client";
+
+/**
+ * useLoadMoreList: a list read that never stops at its first page. It has the shape of a plain `useG8Query` list
+ * (`data`, `loading`, `error`, `refetch`) plus `hasMore` / `loadMore` / `loadingMore`, so a screen that read one capped
+ * page can adopt it by swapping the hook and rendering <LoadMore> under the rows.
+ *
+ *   const list = useLoadMoreList(byOffset(100, async (offset, signal) => {
+ *     const env = await g8Get("/landing-pages", { limit: 100, offset }, { signal });
+ *     const rows = listOf(env.data);
+ *     return { rows, hasNext: hasNextOf(env, 100, rows.length) };
+ *   }), [status]);
+ *   ...
+ *   <LoadMore shown={rows.length} noun="landing pages" hasMore={list.hasMore} loading={list.loadingMore} onLoadMore={list.loadMore} />
+ *
+ * Built on usePaginated (changing `deps` starts over, stale responses are dropped). It calls no operation itself.
+ */
+import { useRef } from "react";
+import { usePaginated } from "./use-paginated";
+import type { UsePaginatedOptions } from "./use-paginated";
+import type { PaginatedResponse } from "@graph8/sdk";
+
+export interface UseLoadMoreList<T> {
+  /** The rows loaded so far; undefined until the first page arrives. */
+  data: T[] | undefined;
+  loading: boolean;
+  loadingMore: boolean;
+  error: unknown;
+  hasMore: boolean;
+  loadMore: () => void;
+  /** Start over from the first page; resolves with that first page of rows (what a poll needs to decide), undefined if it failed. */
+  refetch: () => Promise<T[] | undefined>;
+}
+
+export function useLoadMoreList<T>(
+  fetchPage: (cursor: string | undefined, signal: AbortSignal) => Promise<PaginatedResponse<T>>,
+  deps: readonly unknown[],
+  options: UsePaginatedOptions = {},
+): UseLoadMoreList<T> {
+  const first = useRef<T[] | undefined>(undefined);
+  const p = usePaginated<T>(async (cursor, signal) => {
+    const page = await fetchPage(cursor, signal);
+    if (cursor === undefined) first.current = [...(page.data ?? [])];
+    return page;
+  }, deps, options);
+  return {
+    data: p.loading && p.items.length === 0 ? undefined : p.items,
+    loading: p.loading,
+    loadingMore: p.loadingMore,
+    error: p.error,
+    hasMore: p.hasMore,
+    loadMore: () => { void p.loadMore(); },
+    // Resolves with the FIRST page of the new load (first.current is set by the wrapped fetcher above), not the whole list:
+    // enough for a poll that only asks "is anything still generating?".
+    refetch: async () => {
+      first.current = undefined;
+      await p.reload();
+      return first.current;
+    },
+  };
+}