@graph8/sdk 0.370.0 → 0.374.0

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;
+    },
+  };
+}

package/blocks/_foundation/hooks/use-url-filters.ts

@@ -0,0 +1,93 @@
+"use client";
+
+/**
+ * useUrlFilters: the filter state of a list screen, kept in the URL so a filtered view survives reload, Back and sharing.
+ *
+ *   const f = useUrlFilters(["email", "city"] as const, { prefix: "c_" });
+ *   <input value={f.draft.email} onChange={(e) => f.set("email", e.target.value)} />
+ *   g8Get("/contacts", { page, ...f.query });      // f.query holds only the filters that are set, debounced
+ *
+ * Typing is local (`draft`, instant); the debounced `filters` are what the list reads, and they are written to the URL as
+ * `<prefix><key>=...`. A URL that already carries filters is the starting value, with no flash of an unfiltered list and
+ * no wipe at mount. It is read through `useSyncExternalStore` (like useUrlState), so it is hydration-safe: the server and
+ * the first hydration render both see empty filters, React then re-renders with the URL's. In that first hydration render
+ * `ready` is false: hold the list read until it is true (`enabled: filters.ready`), so no unfiltered read goes out. On a
+ * client-only render `ready` is true from the start. `clear()` empties everything. Params of other hooks (id, view, tab)
+ * are never touched.
+ *
+ * SDK operations: none.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { readUrlParam, writeUrlParam } from "./use-url-state";
+
+export interface UseUrlFiltersOptions {
+  /** URL param prefix, so two screens on one page do not share names. Default "". */
+  prefix?: string;
+  /** Milliseconds of quiet typing before the list reads the new filters. Default 300. */
+  debounceMs?: number;
+}
+
+export interface UseUrlFilters<K extends string> {
+  /** What the inputs show (instant). */
+  draft: Record<K, string>;
+  /** What the list reads (debounced after an edit). */
+  filters: Record<K, string>;
+  /** Only the filters that are set, ready to spread into a query. */
+  query: Partial<Record<K, string>>;
+  set: (key: K, value: string) => void;
+  clear: () => void;
+  /** Some filter is set (draft). */
+  active: boolean;
+  /** How many of `keys` are set (draft). */
+  count: number;
+  /** The URL's filters have been read (false only in the first hydration render): hold the list read until true. */
+  ready: boolean;
+}
+
+const noSubscribe = (): (() => void) => () => {};
+
+export function useUrlFilters<K extends string>(keys: readonly K[], options: UseUrlFiltersOptions = {}): UseUrlFilters<K> {
+  const prefix = options.prefix ?? "";
+  const ms = options.debounceMs ?? 300;
+  const sig = keys.join(",");
+  const empty = useCallback((): Record<K, string> => Object.fromEntries(keys.map((k) => [k, ""])) as Record<K, string>, [sig]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // The URL's filters as one string, frozen at the first client read. The server (and the first hydration render) sees "".
+  const frozen = useRef<string | null>(null);
+  const urlSnap = useSyncExternalStore(
+    noSubscribe,
+    () => (frozen.current ??= JSON.stringify(keys.map((k) => readUrlParam(prefix + k) ?? ""))),
+    () => JSON.stringify(keys.map(() => "")),
+  );
+  const ready = useSyncExternalStore(noSubscribe, () => true, () => false);
+  const fromUrl = useMemo(() => {
+    const values = JSON.parse(urlSnap) as string[];
+    return Object.fromEntries(keys.map((k, i) => [k, values[i] ?? ""])) as Record<K, string>;
+  }, [urlSnap, sig]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // `edited` is null until the person types: until then the filters ARE the URL's (no debounce lag, nothing to write back).
+  const [edited, setEdited] = useState<Record<K, string> | null>(null);
+  const [settled, setSettled] = useState<Record<K, string> | null>(null);
+  const draft = edited ?? fromUrl;
+  const filters = settled ?? fromUrl;
+  const latest = useRef(draft);
+  latest.current = draft;
+
+  useEffect(() => {
+    if (edited === null) return;
+    const t = setTimeout(() => setSettled(edited), ms);
+    return () => clearTimeout(t);
+  }, [edited, ms]);
+
+  // The settled filters are the URL's value; writeUrlParam skips an unchanged value, so mounting writes nothing.
+  useEffect(() => {
+    if (!ready) return;
+    for (const k of keys) writeUrlParam(prefix + k, filters[k] || null);
+  }, [ready, filters]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const set = useCallback((key: K, value: string) => setEdited({ ...latest.current, [key]: value }), []);
+  const clear = useCallback(() => setEdited(empty()), [empty]);
+  const query = Object.fromEntries(keys.filter((k) => filters[k]).map((k) => [k, filters[k]])) as Partial<Record<K, string>>;
+  const count = keys.filter((k) => draft[k]).length;
+  return { draft, filters, query, set, clear, active: count > 0, count, ready };
+}

package/blocks/_foundation/lib/paging.ts

@@ -0,0 +1,57 @@
+"use client";
+
+/**
+ * Paging helpers: adapt the API's several paging dialects (`page`, `offset`, `cursor`) to the one shape
+ * `usePaginated` loads ("load more" appends the next page). No operation is called here; the caller's component
+ * performs and declares the read.
+ *
+ *   const list = usePaginated(byOffset(PAGE, async (offset, signal) => {
+ *     const env = await g8Get("/landing-pages", { limit: PAGE, offset }, { signal });
+ *     return { rows: listOf(env.data), hasNext: hasNextOf(env, PAGE) };
+ *   }), [status]);
+ */
+import type { PaginatedResponse } from "@graph8/sdk";
+
+/** One page of rows and whether another follows (omit `hasNext` and a full page is taken to mean "maybe more"). */
+export interface RowsPage<T> {
+  rows: T[];
+  hasNext?: boolean;
+}
+
+type Fetcher<T> = (cursor: string | undefined, signal: AbortSignal) => Promise<PaginatedResponse<T>>;
+
+/**
+ * `trustHasNext`: when the page says `hasNext: true` believe it even if it carries no rows (a page-number list whose rows
+ * were filtered client-side can be empty while the server still has more). Offset lists cannot: an empty page does not
+ * advance the offset, so they stop on an empty page.
+ */
+function toResponse<T>(page: RowsPage<T>, size: number, next: number, trustHasNext = false): PaginatedResponse<T> {
+  const more = page.hasNext ?? page.rows.length >= size;
+  const go = more && (page.rows.length > 0 || (trustHasNext && page.hasNext === true));
+  return { data: page.rows, pagination: { next_cursor: go ? String(next) : null } } as unknown as PaginatedResponse<T>;
+}
+
+/** `?page=N` lists: the cursor carries the next page number. */
+export function byPage<T>(size: number, read: (page: number, signal: AbortSignal) => Promise<RowsPage<T>>): Fetcher<T> {
+  return async (cursor, signal) => {
+    const page = cursor ? Number(cursor) || 1 : 1;
+    return toResponse(await read(page, signal), size, page + 1, true);
+  };
+}
+
+/** `?offset=N` (or skip) lists: the cursor carries the next offset. */
+export function byOffset<T>(size: number, read: (offset: number, signal: AbortSignal) => Promise<RowsPage<T>>): Fetcher<T> {
+  return async (cursor, signal) => {
+    const offset = cursor ? Number(cursor) || 0 : 0;
+    const page = await read(offset, signal);
+    return toResponse(page, size, offset + page.rows.length);
+  };
+}
+
+/** Whether an API envelope says another page follows: `pagination.has_next`, then `next_cursor`, then a full page. */
+export function hasNextOf(env: unknown, size: number, rows?: number): boolean | undefined {
+  const p = (env as { pagination?: { has_next?: boolean; next_cursor?: string | null; total?: number; page?: number } } | null)?.pagination;
+  if (typeof p?.has_next === "boolean") return p.has_next;
+  if (p && "next_cursor" in p && p.next_cursor !== undefined) return Boolean(p.next_cursor);
+  return rows === undefined ? undefined : rows >= size;
+}

package/blocks/_foundation/lib/use-debounced-value.ts

@@ -0,0 +1,13 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+/** `value`, but only after it has stopped changing for `ms` (foundation-local: the pickers block has its own copy). */
+export function useDebounced<T>(value: T, ms = 250): T {
+  const [v, setV] = useState(value);
+  useEffect(() => {
+    const t = setTimeout(() => setV(value), ms);
+    return () => clearTimeout(t);
+  }, [value, ms]);
+  return v;
+}