@graph8/sdk 0.362.0 → 0.373.0

package/blocks/_foundation/components/connect-graph8.tsx

@@ -0,0 +1,280 @@
+"use client";
+
+/**
+ * Connect graph8 (local preview only): the first-run screen of a created app when the server has no graph8 API
+ * key yet, and the place to replace or remove the key later.
+ *
+ * Calls this app's own `/api/g8-connect` route (g8/server/connect.ts), never graph8 directly:
+ *   GET    status: is a key configured, where from (server environment or the pasted file), whose is it
+ *   POST   { key }: the server checks the key with a free read (GET /me), then stores it in .g8/local-key
+ *   DELETE remove the stored key
+ * No billable, external or destructive graph8 operation (removing the local file only forgets the key here).
+ * The key goes from the input to the server once and is never kept in browser state after submit, storage or URL.
+ *
+ * Exports:
+ *   - ConnectGraph8Panel: the full-page panel (no required props).
+ *   - G8ConnectGate: wraps the app; in `next dev` it shows the screen until a key is connected, plus a small
+ *     "Local preview" button to manage the key. In a production build it renders its children and nothing else.
+ */
+
+import { useCallback, useEffect, useId, useState, type FormEvent, type ReactNode } from "react";
+import { CheckCircle2, ExternalLink, KeyRound, Loader2, X } from "lucide-react";
+import { Button, Input, cn } from "@graph8/sdk/ui";
+import { DEFAULT_BRAND, brandUrl, useBrand } from "../hooks/use-brand";
+
+export const CONNECT_PATH = "/api/g8-connect";
+/** Where API keys are managed, on the platform's web app (white-label: see hooks/use-brand). */
+const KEYS_PATH = "/studio/settings?tab=api";
+
+export interface ConnectStatus {
+  localPreview: boolean;
+  connected: boolean;
+  source: "env" | "file" | null;
+  keyHint?: string;
+  keyFile?: string;
+  account?: { name?: string; workspace?: string; scopes?: string[] };
+  problem?: string;
+}
+
+async function readJson(res: Response): Promise<Record<string, unknown>> {
+  return (await res.json().catch(() => ({}))) as Record<string, unknown>;
+}
+
+/** GET the status. Null when the route does not exist or refuses (production, not this machine). */
+export async function fetchConnectStatus(): Promise<ConnectStatus | null> {
+  try {
+    const res = await fetch(CONNECT_PATH, { headers: { accept: "application/json" }, cache: "no-store" });
+    if (!res.ok) return null;
+    const body = await readJson(res);
+    return body.localPreview === true ? (body as unknown as ConnectStatus) : null;
+  } catch {
+    return null;
+  }
+}
+
+function accountLine(s: ConnectStatus, platform = DEFAULT_BRAND.linkLabel): string {
+  const a = s.account ?? {};
+  return [a.name, a.workspace].filter(Boolean).join(" at ") || `a ${platform} key`;
+}
+
+export interface ConnectGraph8PanelProps {
+  /** Status from a previous GET (the gate passes it); fetched on mount when absent. */
+  status?: ConnectStatus | null;
+  /** Called after a key is stored or removed, with the new status. */
+  onChange?: (status: ConnectStatus) => void;
+  className?: string;
+}
+
+/** Paste, check and store the server's graph8 API key; replace or remove it. */
+export function ConnectGraph8Panel({ status: initial, onChange, className }: ConnectGraph8PanelProps) {
+  const [status, setStatus] = useState<ConnectStatus | null | undefined>(initial);
+  const [key, setKey] = useState("");
+  const [busy, setBusy] = useState<"save" | "remove" | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [replacing, setReplacing] = useState(false);
+  const inputId = useId();
+  const brand = useBrand();
+
+  useEffect(() => {
+    if (initial === undefined) void fetchConnectStatus().then(setStatus);
+  }, [initial]);
+
+  const apply = (next: ConnectStatus) => {
+    setStatus(next);
+    setReplacing(false);
+    onChange?.(next);
+  };
+
+  const submit = async (e: FormEvent) => {
+    e.preventDefault();
+    if (!key.trim() || busy) return;
+    setBusy("save");
+    setError(null);
+    try {
+      const res = await fetch(CONNECT_PATH, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ key: key.trim() }) });
+      const body = await readJson(res);
+      setKey("");
+      if (!res.ok) setError(typeof body.message === "string" ? body.message : `Could not save the key (HTTP ${res.status}).`);
+      else apply(body as unknown as ConnectStatus);
+    } catch {
+      setError("Could not reach this app's server. Is `npm run dev` still running?");
+    } finally {
+      setBusy(null);
+    }
+  };
+
+  const remove = async () => {
+    setBusy("remove");
+    setError(null);
+    try {
+      const res = await fetch(CONNECT_PATH, { method: "DELETE" });
+      const body = await readJson(res);
+      if (!res.ok) setError(typeof body.message === "string" ? body.message : `Could not remove the key (HTTP ${res.status}).`);
+      else apply(body as unknown as ConnectStatus);
+    } catch {
+      setError("Could not reach this app's server. Is `npm run dev` still running?");
+    } finally {
+      setBusy(null);
+    }
+  };
+
+  const connected = Boolean(status?.connected);
+  const fromEnv = status?.source === "env";
+  const showForm = !fromEnv && (!status?.source || replacing);
+
+  return (
+    <section aria-labelledby={`${inputId}-title`} className={cn("mx-auto flex w-full max-w-md flex-col gap-5 px-4 py-14", className)}>
+      <div className="flex flex-col gap-2">
+        <div aria-hidden className="flex size-10 items-center justify-center rounded-lg border border-border bg-muted text-foreground">
+          <KeyRound className="size-5" strokeWidth={1.5} />
+        </div>
+        <h1 id={`${inputId}-title`} className="text-lg font-medium text-foreground">
+          {connected ? `Connected to ${brand.linkLabel}` : `Connect ${brand.linkLabel}`}
+        </h1>
+        <p className="text-sm leading-5 text-text-color-muted">
+          This app reads and writes your {brand.linkLabel} data through its own server. Paste an API key once: the server checks
+          it and keeps it in <code className="text-xs">{status?.keyFile ?? ".g8/local-key"}</code> on this computer. The
+          browser never stores it.
+        </p>
+      </div>
+
+      {status?.source ? (
+        <div className="flex items-start gap-3 rounded-lg border border-border p-3 text-sm">
+          {connected ? (
+            <CheckCircle2 aria-hidden className="mt-0.5 size-4 shrink-0 text-positive-foreground" strokeWidth={1.5} />
+          ) : (
+            <X aria-hidden className="mt-0.5 size-4 shrink-0 text-error-foreground" strokeWidth={1.5} />
+          )}
+          <div className="flex min-w-0 flex-1 flex-col gap-0.5">
+            <span className="text-foreground">{connected ? accountLine(status, brand.linkLabel) : "The key no longer works"}</span>
+            <span className="text-xs text-text-color-muted">
+              Key {status.keyHint ?? ""} from {fromEnv ? "the server environment (.env.local)" : status.keyFile ?? ".g8/local-key"}
+              {status.problem ? `. ${status.problem}` : ""}
+            </span>
+            {fromEnv ? <span className="text-xs text-text-color-muted">To change it, edit .env.local and restart the dev server.</span> : null}
+          </div>
+        </div>
+      ) : null}
+
+      {showForm ? (
+        <form onSubmit={submit} className="flex flex-col gap-2">
+          <label htmlFor={inputId} className="text-sm font-medium text-foreground">
+            {brand.linkLabel} API key
+          </label>
+          <Input
+            id={inputId}
+            type="password"
+            autoComplete="off"
+            spellCheck={false}
+            value={key}
+            onChange={(e) => setKey(e.target.value)}
+            placeholder="Paste the key"
+            aria-invalid={error ? true : undefined}
+            aria-describedby={error ? `${inputId}-error` : undefined}
+          />
+          {error ? (
+            <p id={`${inputId}-error`} role="alert" className="text-xs text-error-foreground">
+              {error}
+            </p>
+          ) : null}
+          <div className="flex items-center gap-2 pt-1">
+            <Button type="submit" disabled={!key.trim() || busy !== null}>
+              {busy === "save" ? <Loader2 aria-hidden className="size-4 animate-spin" /> : null}
+              {busy === "save" ? "Checking" : "Connect"}
+            </Button>
+            {replacing ? (
+              <Button type="button" variant="ghost" onClick={() => setReplacing(false)}>
+                Cancel
+              </Button>
+            ) : null}
+          </div>
+        </form>
+      ) : status?.source === "file" ? (
+        <div className="flex flex-col gap-2">
+          <div className="flex items-center gap-2">
+            <Button type="button" variant="outline" onClick={() => setReplacing(true)} disabled={busy !== null}>
+              Replace key
+            </Button>
+            <Button type="button" variant="ghost" onClick={() => void remove()} disabled={busy !== null}>
+              {busy === "remove" ? <Loader2 aria-hidden className="size-4 animate-spin" /> : null}
+              Remove key
+            </Button>
+          </div>
+          {error ? (
+            <p role="alert" className="text-xs text-error-foreground">
+              {error}
+            </p>
+          ) : null}
+        </div>
+      ) : null}
+
+      <a href={brandUrl(brand, KEYS_PATH)} target="_blank" rel="noreferrer" className="inline-flex items-center gap-1 text-sm text-foreground underline-offset-4 hover:underline">
+        Get a key in {brand.linkLabel} (Settings, API)
+        <ExternalLink aria-hidden className="size-3.5" strokeWidth={1.5} />
+      </a>
+      <p className="text-xs leading-5 text-text-color-muted">
+        Local preview: this screen and the data routes only answer requests from this computer while you run the dev
+        server. Before you deploy, set <code>authorize</code> in app/api/g8/[...path]/route.ts and the key in your host&apos;s
+        environment; <code>npx @graph8/sdk doctor --production</code> checks both.
+      </p>
+    </section>
+  );
+}
+
+export interface G8ConnectGateProps {
+  children: ReactNode;
+  /** Hide the small "Local preview" button once connected. Default false. */
+  hideManageButton?: boolean;
+}
+
+/**
+ * In `next dev`: shows ConnectGraph8Panel instead of the app until a key is connected, and a small button to
+ * manage the key afterwards. In a production build (and when /api/g8-connect is missing or refuses) it is
+ * exactly its children: no request, no extra markup.
+ */
+export function G8ConnectGate({ children, hideManageButton = false }: G8ConnectGateProps) {
+  const dev = process.env.NODE_ENV !== "production";
+  const [status, setStatus] = useState<ConnectStatus | null | undefined>(dev ? undefined : null);
+  const [managing, setManaging] = useState(false);
+  const brand = useBrand();
+
+  useEffect(() => {
+    if (dev) void fetchConnectStatus().then(setStatus);
+  }, [dev]);
+
+  const changed = useCallback((next: ConnectStatus) => {
+    setStatus(next);
+    // Every screen loaded its data with the old (or no) key: start them again.
+    if (next.connected) window.location.reload();
+  }, []);
+
+  if (!status) return <>{children}</>;
+  if (!status.connected || managing) {
+    return (
+      <div className="relative">
+        {managing && status.connected ? (
+          <Button type="button" variant="ghost" size="sm" className="absolute right-4 top-4" onClick={() => setManaging(false)}>
+            Back to the app
+          </Button>
+        ) : null}
+        <ConnectGraph8Panel status={status} onChange={changed} />
+      </div>
+    );
+  }
+  return (
+    <>
+      {children}
+      {hideManageButton ? null : (
+        <button
+          type="button"
+          onClick={() => setManaging(true)}
+          title={`Local preview, connected as ${accountLine(status, brand.linkLabel)}. Manage the ${brand.linkLabel} key.`}
+          className="fixed bottom-3 right-3 z-40 inline-flex h-7 items-center gap-1.5 rounded-md border border-border bg-background px-2 text-xs text-text-color-muted hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        >
+          <KeyRound aria-hidden className="size-3.5" strokeWidth={1.5} />
+          Local preview
+        </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,9 +9,11 @@
 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";
+export * from "./record-link";
 export * from "./section-card";
 export * from "./sparkline";
 export * from "./split-view";