@graph8/sdk 0.361.0 → 0.370.0

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

@@ -0,0 +1,125 @@
+"use client";
+
+/**
+ * SplitView: list on the left, the selected record on the right. On wide screens the detail is a
+ * fixed-width pane with a hairline; under `breakpoint` (default 1024px, any value works) it becomes a right Sheet so the list
+ * keeps its full width on tablets and phones. Pair it with `useUrlState("id")` so the open record
+ * survives reload and Back. `expanded` turns the detail into a full-page record screen (the list
+ * steps aside, a Back affordance returns to it); pair it with `useUrlState("view") === "full"` so
+ * `?id=X&view=full` deep-links to the full page.
+ *
+ * SDK operations: none.
+ */
+import { useEffect, useState, type CSSProperties, type ReactNode } from "react";
+import { ArrowLeft } from "lucide-react";
+import { Button, Sheet, SheetContent, SheetDescription, SheetTitle, cn } from "@graph8/sdk/ui";
+
+export interface SplitViewProps {
+  list: ReactNode;
+  detail?: ReactNode;
+  detailOpen: boolean;
+  onCloseDetail: () => void;
+  detailWidth?: "md" | "lg" | "xl";
+  /** Accessible name for the sheet on narrow screens. */
+  detailTitle?: string;
+  /** Pixel width under which the detail becomes a sheet. Default 1024. */
+  breakpoint?: number;
+  /** Full-page mode: the detail takes the whole content area and the list steps aside. */
+  expanded?: boolean;
+  /** Called with false from the Back affordance; wire it to `useUrlState("view")`. */
+  onExpandedChange?: (expanded: boolean) => void;
+  /** Label of the Back affordance in full-page mode. Default "Back to list". */
+  backLabel?: string;
+  className?: string;
+  listClassName?: string;
+  detailClassName?: string;
+}
+
+const WIDTH: Record<NonNullable<SplitViewProps["detailWidth"]>, { pane: string; sheet: string }> = {
+  md: { pane: "lg:w-[24rem] xl:w-[26rem]", sheet: "sm:max-w-md" },
+  lg: { pane: "lg:w-[30rem] xl:w-[34rem]", sheet: "sm:max-w-lg" },
+  xl: { pane: "lg:w-[36rem] xl:w-[42rem] 2xl:w-[48rem]", sheet: "sm:max-w-2xl" },
+};
+
+/**
+ * Pane width with a custom `breakpoint`: the `lg:`-prefixed classes above do not apply below 1024px, so the
+ * pane gets a fixed width (the `lg` step) capped at 60% of the row, and the list keeps the rest.
+ */
+const CUSTOM_PANE: Record<NonNullable<SplitViewProps["detailWidth"]>, CSSProperties> = {
+  md: { width: "24rem", maxWidth: "60%" },
+  lg: { width: "30rem", maxWidth: "60%" },
+  xl: { width: "36rem", maxWidth: "60%" },
+};
+
+/** SSR-safe media query: false on the server and the first client render, then live. */
+export function useMediaQuery(query: string): boolean {
+  const [matches, setMatches] = useState(false);
+  useEffect(() => {
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function") return;
+    const mql = window.matchMedia(query);
+    const update = () => setMatches(mql.matches);
+    update();
+    mql.addEventListener?.("change", update);
+    return () => mql.removeEventListener?.("change", update);
+  }, [query]);
+  return matches;
+}
+
+export function SplitView({ list, detail, detailOpen, onCloseDetail, detailWidth = "lg", detailTitle = "Details", breakpoint = 1024, expanded, onExpandedChange, backLabel = "Back to list", className, listClassName, detailClassName }: SplitViewProps) {
+  const narrow = useMediaQuery(`(max-width: ${breakpoint - 1}px)`);
+  const open = detailOpen && detail != null;
+  const w = WIDTH[detailWidth] ?? WIDTH.lg;
+  const defaultBreakpoint = breakpoint === 1024;
+
+  if (open && expanded) {
+    return (
+      <div className={cn("flex h-full min-h-0 w-full min-w-0 flex-col", className)} data-testid="split-view" data-detail-open="true" data-expanded="true">
+        <div className="flex shrink-0 items-center gap-2 border-b border-border bg-background px-2 py-1.5">
+          <Button
+            type="button"
+            variant="ghost"
+            size="sm"
+            className="h-7 gap-1.5 px-2 text-text-color-muted hover:text-foreground"
+            onClick={() => (onExpandedChange ? onExpandedChange(false) : onCloseDetail())}
+          >
+            <ArrowLeft className="size-4" strokeWidth={1.5} aria-hidden />
+            {backLabel}
+          </Button>
+        </div>
+        <div className={cn("flex min-h-0 flex-1 flex-col overflow-hidden", detailClassName)} data-testid="split-view-full">
+          {detail}
+        </div>
+      </div>
+    );
+  }
+
+  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>
+      {open && !narrow ? (
+        <aside
+          aria-label={detailTitle}
+          className={cn(
+            "min-h-0 shrink-0 flex-col overflow-hidden border-l border-border bg-background",
+            // The default breakpoint matches Tailwind's lg, so CSS keeps the pane hidden on narrow screens
+            // before the media query resolves (SSR), and the lg:/xl: width classes apply. A custom breakpoint
+            // relies on the media query alone and gets an explicit width so the list keeps its share.
+            defaultBreakpoint ? cn("hidden w-full lg:flex", w.pane) : "flex",
+            detailClassName,
+          )}
+          style={defaultBreakpoint ? undefined : (CUSTOM_PANE[detailWidth] ?? CUSTOM_PANE.lg)}
+          data-testid="split-view-detail"
+        >
+          {detail}
+        </aside>
+      ) : null}
+      <Sheet open={open && narrow} onOpenChange={(next) => (!next ? onCloseDetail() : undefined)}>
+        <SheetContent side="right" hideCloseButton className={cn("w-full gap-0 p-0 sm:w-full", w.sheet, detailClassName)} data-testid="split-view-sheet">
+          <SheetTitle className="sr-only">{detailTitle}</SheetTitle>
+          <SheetDescription className="sr-only">Selected record</SheetDescription>
+          <div className="flex h-full min-h-0 flex-col">{detail}</div>
+        </SheetContent>
+      </Sheet>
+    </div>
+  );
+}

package/blocks/_foundation/components/screen/stat-strip.tsx

@@ -0,0 +1,121 @@
+"use client";
+
+/**
+ * StatStrip: a row of KPI tiles (label, big number, delta, hint, sparkline) for the top of a screen.
+ * Numbers are ink; only a delta takes colour, and only through `tone` (good or bad FOR THE USER).
+ * A delta without a tone is an ink arrow and number.
+ *
+ * SDK operations: none.
+ */
+import type { ReactNode } from "react";
+import { ArrowDown, ArrowUp, Info } from "lucide-react";
+import { Skeleton, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, cn } from "@graph8/sdk/ui";
+import { Sparkline } from "./sparkline";
+import { TONE_CLASSES, type Tone } from "./status-pill";
+
+export interface StatItem {
+  label: string;
+  value: ReactNode;
+  /** Change versus the previous period, in percent (12 = up 12%). */
+  delta?: number;
+  /** Explanation shown in a tooltip on the label. */
+  hint?: string;
+  /** Colours the delta. Omit when the direction has no good or bad meaning. */
+  tone?: Tone;
+  sparkline?: number[];
+  /** Optional link or button rendered under the value ("View all"). */
+  footer?: ReactNode;
+  onClick?: () => void;
+}
+
+export interface StatStripProps {
+  items: StatItem[];
+  loading?: boolean;
+  /** Tiles per row on wide screens. Defaults to the number of items, up to 6. */
+  columns?: number;
+  className?: string;
+}
+
+export function formatDelta(delta: number): string {
+  const abs = Math.abs(delta);
+  const text = abs >= 100 ? abs.toFixed(0) : abs >= 10 ? abs.toFixed(1).replace(/\.0$/, "") : abs.toFixed(1).replace(/\.0$/, "");
+  return `${text}%`;
+}
+
+function Delta({ delta, tone }: { delta: number; tone?: Tone }) {
+  const Arrow = delta < 0 ? ArrowDown : ArrowUp;
+  const colour = tone ? TONE_CLASSES[tone].text : "text-foreground";
+  return (
+    <span className={cn("inline-flex items-center gap-0.5 text-xs font-medium tabular-nums", colour)} data-tone={tone ?? "ink"}>
+      {delta === 0 ? null : <Arrow className="size-3" strokeWidth={2} aria-hidden />}
+      <span className="sr-only">{delta < 0 ? "down" : delta > 0 ? "up" : "unchanged"}</span>
+      {formatDelta(delta)}
+    </span>
+  );
+}
+
+export function StatStrip({ items, loading, columns, className }: StatStripProps) {
+  const cols = Math.min(Math.max(columns ?? items.length, 1), 6);
+  const style = { ["--g8-stat-cols" as string]: String(cols) };
+  return (
+    <TooltipProvider delayDuration={150}>
+      <dl
+        className={cn(
+          "grid grid-cols-2 gap-px overflow-hidden rounded-lg border border-border bg-border",
+          "md:[grid-template-columns:repeat(var(--g8-stat-cols),minmax(0,1fr))]",
+          className,
+        )}
+        style={style}
+        data-testid="stat-strip"
+      >
+        {loading
+          ? Array.from({ length: cols }, (_, i) => (
+              <div key={i} className="bg-card px-4 py-3">
+                <Skeleton className="h-3 w-20" />
+                <Skeleton className="mt-3 h-7 w-16" />
+              </div>
+            ))
+          : items.map((item, i) => {
+              const Tag = item.onClick ? "button" : "div";
+              return (
+                <Tag
+                  key={`${item.label}-${i}`}
+                  type={item.onClick ? "button" : undefined}
+                  onClick={item.onClick}
+                  className={cn(
+                    "group min-w-0 bg-card px-4 py-3 text-left",
+                    item.onClick && "cursor-pointer transition-colors hover:bg-surface-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+                  )}
+                >
+                  <dt className="flex items-center gap-1 text-xs text-text-color-muted">
+                    <span className="truncate">{item.label}</span>
+                    {item.hint ? (
+                      <Tooltip>
+                        <TooltipTrigger asChild>
+                          <span tabIndex={0} className="inline-flex rounded-sm text-text-color-muted/70 hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring" aria-label={item.hint}>
+                            <Info className="size-3.5" strokeWidth={1.5} aria-hidden />
+                          </span>
+                        </TooltipTrigger>
+                        <TooltipContent side="top" className="max-w-xs text-xs">
+                          {item.hint}
+                        </TooltipContent>
+                      </Tooltip>
+                    ) : null}
+                  </dt>
+                  <dd className="mt-1 flex items-end justify-between gap-3">
+                    <div className="min-w-0">
+                      <div className="flex items-baseline gap-2">
+                        <span className="truncate text-2xl font-medium leading-none tracking-tight text-foreground tabular-nums">{item.value}</span>
+                        {item.delta != null ? <Delta delta={item.delta} tone={item.tone} /> : null}
+                      </div>
+                      {item.footer ? <div className="mt-1.5 text-xs text-text-color-muted">{item.footer}</div> : null}
+                    </div>
+                    {item.sparkline && item.sparkline.length > 1 ? <Sparkline data={item.sparkline} tone={item.tone} className="h-8 w-20 shrink-0" /> : null}
+                  </dd>
+                </Tag>
+              );
+            })}
+      </dl>
+    </TooltipProvider>
+  );
+}

package/blocks/_foundation/components/screen/status-pill.tsx

@@ -0,0 +1,104 @@
+"use client";
+
+/**
+ * StatusPill: a small state badge whose colour carries meaning (positive, warning, negative) or none
+ * (neutral, info). Use it for record states (active, paused, bounced, won). Unknown states render as
+ * `warning`, never as positive: being "active" is opt-in.
+ *
+ * SDK operations: none.
+ */
+import type { ReactNode } from "react";
+import { cn } from "@graph8/sdk/ui";
+
+export type Tone = "neutral" | "info" | "positive" | "warning" | "negative";
+
+export const TONES: readonly Tone[] = ["neutral", "info", "positive", "warning", "negative"];
+
+/** Tailwind classes per tone: the pill surface, its dot, and plain text. Shared by the kit. */
+export const TONE_CLASSES: Record<Tone, { pill: string; dot: string; text: string; bar: string }> = {
+  neutral: {
+    pill: "border-border bg-muted text-foreground",
+    dot: "bg-text-color-muted",
+    text: "text-text-color-muted",
+    bar: "bg-foreground/15",
+  },
+  info: {
+    pill: "border-transparent bg-info text-info-foreground",
+    dot: "bg-info-foreground",
+    text: "text-info-foreground",
+    bar: "bg-info-foreground",
+  },
+  positive: {
+    pill: "border-transparent bg-positive text-positive-foreground",
+    dot: "bg-positive-foreground",
+    text: "text-positive-foreground",
+    bar: "bg-positive-foreground",
+  },
+  warning: {
+    pill: "border-transparent bg-warning text-warning-foreground",
+    dot: "bg-warning-foreground",
+    text: "text-warning-foreground",
+    bar: "bg-warning-foreground",
+  },
+  negative: {
+    pill: "border-transparent bg-error text-error-foreground",
+    dot: "bg-error-foreground",
+    text: "text-error-foreground",
+    bar: "bg-error-foreground",
+  },
+};
+
+/** "scheduled_for_cancellation" -> "Scheduled for cancellation". */
+export function humanizeStatus(value: string | null | undefined): string {
+  if (!value) return "Unknown";
+  const text = String(value).replace(/[_-]+/g, " ").trim().toLowerCase();
+  return text.charAt(0).toUpperCase() + text.slice(1);
+}
+
+/**
+ * Map a raw API status to a tone. Only the listed good states are positive; anything unlisted is a
+ * warning so a new upstream value is visible instead of looking healthy.
+ */
+export function toneForStatus(
+  value: string | null | undefined,
+  overrides: Partial<Record<string, Tone>> = {},
+): Tone {
+  const key = String(value ?? "").toLowerCase();
+  if (overrides[key]) return overrides[key] as Tone;
+  if (["active", "connected", "won", "completed", "complete", "succeeded", "success", "delivered", "replied", "verified", "booked", "sent", "live", "published", "enabled", "healthy", "ok"].includes(key)) return "positive";
+  if (["paused", "inactive", "draft", "archived", "closed", "disabled", "cancelled", "canceled", "stopped", "ended", "done", "skipped", "none"].includes(key)) return "neutral";
+  if (["pending", "queued", "scheduled", "running", "in_progress", "processing", "syncing", "open", "new", "trial", "sending", "calling", "ringing"].includes(key)) return "info";
+  if (["failed", "error", "errored", "bounced", "lost", "rejected", "expired", "blocked", "suspended", "unsubscribed", "disconnected", "invalid", "overdue", "missed", "spam"].includes(key)) return "negative";
+  return "warning";
+}
+
+export interface StatusPillProps {
+  tone: Tone;
+  children: ReactNode;
+  /** Leading dot in the tone colour: use it in dense rows where the fill would be noisy. */
+  dot?: boolean;
+  /** `dot` alone renders only the dot and the text, with no pill surface. */
+  quiet?: boolean;
+  size?: "sm" | "md";
+  className?: string;
+  title?: string;
+}
+
+export function StatusPill({ tone, children, dot, quiet, size = "sm", className, title }: StatusPillProps) {
+  const t = TONE_CLASSES[tone] ?? TONE_CLASSES.neutral;
+  return (
+    <span
+      data-tone={tone}
+      title={title}
+      className={cn(
+        "inline-flex max-w-full items-center gap-1.5 whitespace-nowrap rounded-full font-medium leading-none",
+        size === "sm" ? "h-5 px-2 text-[11px]" : "h-6 px-2.5 text-xs",
+        quiet ? "px-0 text-foreground" : cn("border", t.pill),
+        className,
+      )}
+    >
+      {dot || quiet ? <span aria-hidden className={cn("size-1.5 shrink-0 rounded-full", t.dot)} /> : null}
+      <span className="truncate">{children}</span>
+    </span>
+  );
+}

package/blocks/_foundation/components/screen/time-series-chart-recharts.tsx

@@ -0,0 +1,65 @@
+"use client";
+
+/**
+ * The recharts half of TimeSeriesChart, in its own module so it is code-split: `time-series-chart.tsx`
+ * loads it on demand (React.lazy), and pages without a chart never download recharts. Import this file
+ * directly only if you need the chart rendered synchronously (it then joins your page bundle).
+ *
+ * SDK operations: none. Peer: recharts.
+ */
+import { useMemo } from "react";
+import { Area, AreaChart, Bar, BarChart, CartesianGrid, Line, LineChart, XAxis, YAxis } from "recharts";
+import { ChartContainer, ChartTooltip, ChartTooltipContent, cn, type ChartConfig } from "@graph8/sdk/ui";
+import { TONE_VAR, defaultFormatX, defaultFormatY } from "./time-series-format";
+import type { TimeSeries, TimeSeriesChartProps } from "./time-series-format";
+
+export function TimeSeriesChartRecharts({ data, xKey, series, kind = "line", height = 220, formatX = defaultFormatX, formatY = defaultFormatY, stacked, className }: TimeSeriesChartProps) {
+  const config = useMemo<ChartConfig>(
+    () => Object.fromEntries(series.map((s) => [s.key, { label: s.label ?? s.key, color: TONE_VAR[s.tone ?? "ink"] }])),
+    [series],
+  );
+  const axes = (
+    <>
+      <CartesianGrid vertical={false} strokeDasharray="0" stroke="var(--border)" strokeOpacity={0.9} />
+      <XAxis dataKey={xKey} tickLine={false} axisLine={false} tickMargin={8} minTickGap={24} tickFormatter={formatX} tick={{ fontSize: 11 }} />
+      <YAxis width={36} tickLine={false} axisLine={false} tickMargin={4} tickFormatter={formatY} tick={{ fontSize: 11 }} allowDecimals={false} />
+      <ChartTooltip cursor={{ stroke: "var(--border)" }} content={<ChartTooltipContent labelFormatter={(v) => formatX(v)} formatter={(v, name) => [`${formatY(Number(v))} `, String(config[String(name)]?.label ?? name)]} indicator="line" />} />
+    </>
+  );
+  const stroke = (s: TimeSeries) => ({
+    stroke: `var(--color-${s.key})`,
+    strokeWidth: s.tone === "prior" ? 1.25 : 1.5,
+    strokeDasharray: s.tone === "prior" ? "4 3" : undefined,
+    dot: false as const,
+    activeDot: { r: 3 },
+    isAnimationActive: false,
+  });
+  const style = { height } as const;
+
+  return (
+    <ChartContainer config={config} className={cn("aspect-auto w-full text-text-color-muted", className)} style={style} data-testid="time-series-chart">
+      {kind === "bar" ? (
+        <BarChart data={data} margin={{ top: 8, right: 8, left: 0, bottom: 0 }} barCategoryGap="25%">
+          {axes}
+          {series.map((s) => (
+            <Bar key={s.key} dataKey={s.key} name={s.key} stackId={stacked ? "a" : undefined} fill={`var(--color-${s.key})`} fillOpacity={s.tone ? 0.85 : 1} radius={[2, 2, 0, 0]} isAnimationActive={false} />
+          ))}
+        </BarChart>
+      ) : kind === "area" ? (
+        <AreaChart data={data} margin={{ top: 8, right: 8, left: 0, bottom: 0 }}>
+          {axes}
+          {series.map((s) => (
+            <Area key={s.key} type="monotone" dataKey={s.key} name={s.key} stackId={stacked ? "a" : undefined} fill={`var(--color-${s.key})`} fillOpacity={s.tone === "prior" ? 0 : 0.06} {...stroke(s)} />
+          ))}
+        </AreaChart>
+      ) : (
+        <LineChart data={data} margin={{ top: 8, right: 8, left: 0, bottom: 0 }}>
+          {axes}
+          {series.map((s) => (
+            <Line key={s.key} type="monotone" dataKey={s.key} name={s.key} {...stroke(s)} />
+          ))}
+        </LineChart>
+      )}
+    </ChartContainer>
+  );
+}

package/blocks/_foundation/components/screen/time-series-chart.tsx

@@ -0,0 +1,32 @@
+"use client";
+
+/**
+ * TimeSeriesChart: a line, area or bar chart over time (sent, replies, meetings by day). Ink by
+ * default; a series takes a tone only when it means good or bad (replies positive, bounces negative).
+ * A `prior` series is the dashed warm-grey comparison. Chrome is recessive: hairline gridlines, muted
+ * axis labels, no borders. Built on recharts through the UI kit's ChartContainer.
+ *
+ * recharts is code-split: the chart module (time-series-chart-recharts.tsx) loads on first render, with a
+ * same-height skeleton meanwhile, so a page that shows no chart never downloads it. Same props as before.
+ *
+ * SDK operations: none. Peer: recharts.
+ */
+import { Suspense, lazy } from "react";
+import { Skeleton, cn } from "@graph8/sdk/ui";
+import type { TimeSeriesChartProps } from "./time-series-format";
+
+export type { TimeSeries, TimeSeriesChartProps } from "./time-series-format";
+export { defaultFormatX, defaultFormatY } from "./time-series-format";
+
+const Recharts = lazy(() => import("./time-series-chart-recharts").then((m) => ({ default: m.TimeSeriesChartRecharts })));
+
+export function TimeSeriesChart(props: TimeSeriesChartProps) {
+  const fallback = (
+    <Skeleton className={cn("w-full", props.className)} style={{ height: props.height ?? 220 }} aria-label="Loading chart" data-testid="time-series-chart-loading" />
+  );
+  return (
+    <Suspense fallback={fallback}>
+      <Recharts {...props} />
+    </Suspense>
+  );
+}

package/blocks/_foundation/components/screen/time-series-format.ts

@@ -0,0 +1,57 @@
+"use client";
+
+/**
+ * Types and formatters shared by TimeSeriesChart and its lazily loaded recharts implementation.
+ * No recharts here, so importing them costs nothing.
+ */
+import type { Tone } from "./status-pill";
+
+export interface TimeSeries {
+  /** The field of each row to plot. */
+  key: string;
+  label?: string;
+  /** Ink unless the direction means good or bad. "prior" is the dashed comparison line. */
+  tone?: Tone | "prior";
+}
+
+export interface TimeSeriesChartProps {
+  data: Array<Record<string, unknown>>;
+  /** Field holding the x value (an ISO date, a label). */
+  xKey: string;
+  series: TimeSeries[];
+  kind?: "line" | "area" | "bar";
+  height?: number;
+  /** Format an x value for the axis ("2026-10-01" -> "Oct 1"). */
+  formatX?: (value: unknown) => string;
+  /** Format a y value for the axis and the tooltip. */
+  formatY?: (value: number) => string;
+  /** Stack bars/areas. */
+  stacked?: boolean;
+  className?: string;
+}
+
+export const TONE_VAR: Record<NonNullable<TimeSeries["tone"]> | "ink", string> = {
+  ink: "var(--foreground)",
+  neutral: "var(--text-color-muted)",
+  info: "var(--info-foreground)",
+  positive: "var(--positive-foreground)",
+  warning: "var(--warning-foreground)",
+  negative: "var(--error-foreground)",
+  prior: "var(--text-color-muted)",
+};
+
+export function defaultFormatX(value: unknown): string {
+  if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}/.test(value)) {
+    const d = new Date(value.length === 10 ? `${value}T00:00:00Z` : value);
+    if (!Number.isNaN(d.getTime())) return d.toLocaleDateString(undefined, { month: "short", day: "numeric", timeZone: value.length === 10 ? "UTC" : undefined });
+  }
+  return String(value ?? "");
+}
+
+export function defaultFormatY(value: number): string {
+  if (Math.abs(value) >= 1_000_000) return `${(value / 1_000_000).toFixed(1).replace(/\.0$/, "")}M`;
+  if (Math.abs(value) >= 10_000) return `${(value / 1_000).toFixed(0)}k`;
+  if (Math.abs(value) >= 1_000) return `${(value / 1_000).toFixed(1).replace(/\.0$/, "")}k`;
+  return value.toLocaleString();
+}
+

package/blocks/_foundation/components/screen/toolbar.tsx

@@ -0,0 +1,144 @@
+"use client";
+
+/**
+ * Toolbar: the row above a list. Left: debounced search and filters. Right: actions (bulk, export, the
+ * primary). The search calls `onChange` after `debounceMs` of quiet typing, immediately on Enter, and
+ * clears on Escape or the clear button. Out-of-order results are the list's job (useG8Query does it).
+ *
+ * SDK operations: none.
+ */
+import { useEffect, useRef, useState, type KeyboardEvent, type ReactNode } from "react";
+import { Search, X } from "lucide-react";
+import { Input, cn } from "@graph8/sdk/ui";
+
+export interface ToolbarSearch {
+  value: string;
+  onChange: (value: string) => void;
+  placeholder?: string;
+  /** Milliseconds of quiet typing before `onChange` fires. 0 fires on every keystroke. */
+  debounceMs?: number;
+  /** Accessible name; defaults to the placeholder or "Search". */
+  label?: string;
+  autoFocus?: boolean;
+}
+
+export interface ToolbarProps {
+  search?: ToolbarSearch;
+  /** Filter controls (selects, chips, a Filters button), rendered after the search. */
+  filters?: ReactNode;
+  /** Right-aligned actions; the primary action goes last. */
+  actions?: ReactNode;
+  /** A second row (applied filter chips, a selection summary). */
+  children?: ReactNode;
+  /** Result count or any status text, read by screen readers politely. */
+  status?: ReactNode;
+  className?: string;
+}
+
+export function ToolbarSearchInput({ value, onChange, placeholder = "Search", debounceMs = 250, label, autoFocus }: ToolbarSearch) {
+  const [text, setText] = useState(value);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const latest = useRef(onChange);
+  latest.current = onChange;
+  // Values sent to onChange that the parent has not echoed back yet (an async parent, e.g. router.push).
+  const sent = useRef<string[]>([]);
+
+  // The parent owns the value (URL, store): follow it when it changes from outside. A late echo of
+  // something we sent is ignored (it would drop characters typed since). A real outside change (a "Clear
+  // filters" button) wins, and cancels a pending debounce so the old text is not sent back afterwards.
+  useEffect(() => {
+    const i = sent.current.indexOf(value);
+    if (i !== -1) {
+      sent.current = sent.current.slice(i + 1);
+      return;
+    }
+    if (timer.current) {
+      clearTimeout(timer.current);
+      timer.current = null;
+    }
+    sent.current = [];
+    setText(value);
+  }, [value]);
+
+  useEffect(() => () => { if (timer.current) clearTimeout(timer.current); }, []);
+
+  const send = (next: string) => {
+    sent.current = [...sent.current.slice(-19), next];
+    latest.current(next);
+  };
+
+  const emit = (next: string, immediate = false) => {
+    if (timer.current) clearTimeout(timer.current);
+    if (immediate || debounceMs <= 0) {
+      timer.current = null;
+      send(next);
+      return;
+    }
+    timer.current = setTimeout(() => {
+      timer.current = null;
+      send(next);
+    }, debounceMs);
+  };
+
+  const onKeyDown = (e: KeyboardEvent<HTMLInputElement>) => {
+    if (e.key === "Enter") {
+      e.preventDefault();
+      emit(text, true);
+    } else if (e.key === "Escape" && text) {
+      e.preventDefault();
+      setText("");
+      emit("", true);
+    }
+  };
+
+  return (
+    <div className="relative w-full min-w-0 sm:w-72">
+      <Search className="pointer-events-none absolute left-2.5 top-1/2 size-4 -translate-y-1/2 text-text-color-muted" strokeWidth={1.5} aria-hidden />
+      <Input
+        type="search"
+        role="searchbox"
+        value={text}
+        autoFocus={autoFocus}
+        aria-label={label ?? placeholder}
+        placeholder={placeholder}
+        onChange={(e) => {
+          setText(e.target.value);
+          emit(e.target.value);
+        }}
+        onKeyDown={onKeyDown}
+        className="h-8 bg-background pl-8 pr-8 text-sm shadow-none [&::-webkit-search-cancel-button]:hidden"
+      />
+      {text ? (
+        <button
+          type="button"
+          aria-label="Clear search"
+          onClick={() => {
+            setText("");
+            emit("", true);
+          }}
+          className="absolute right-1.5 top-1/2 inline-flex size-5 -translate-y-1/2 items-center justify-center rounded-sm text-text-color-muted hover:bg-surface-hover hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        >
+          <X className="size-3.5" strokeWidth={1.5} aria-hidden />
+        </button>
+      ) : null}
+    </div>
+  );
+}
+
+export function Toolbar({ search, filters, actions, children, status, className }: ToolbarProps) {
+  return (
+    <div role="toolbar" aria-label="List tools" className={cn("flex flex-col gap-2", className)} data-testid="toolbar">
+      <div className="flex flex-wrap items-center gap-2">
+        {search ? <ToolbarSearchInput {...search} /> : null}
+        {filters ? <div className="flex flex-wrap items-center gap-1.5">{filters}</div> : null}
+        {status ? (
+          <span role="status" aria-live="polite" className="text-xs text-text-color-muted tabular-nums">
+            {status}
+          </span>
+        ) : null}
+        {actions ? <div className="ml-auto flex shrink-0 items-center gap-2">{actions}</div> : null}
+      </div>
+      {children ? <div className="flex flex-wrap items-center gap-1.5">{children}</div> : null}
+    </div>
+  );
+}