@lotics/ui 4.7.0 → 4.9.0

package/AGENTS.md

@@ -56,7 +56,9 @@ Pick by capability, not by name. (→ the source file for the API.)
   with `Pagination`). Never an HTML `<table>` or a `.map` of rows.
 - **Numbers & charts** — `KPIStrip` / `KPICard` / `Metric` (headline figures), `TrendChip`
   (delta), `Sparkline`, `BarChart` / `LineChart` / `PieChart` (the canonical SVG set — no
-  recharts), `RingGauge`, `ProgressBar` / `StackedProgressBar` / `StepProgress`, `Breakdown`,
+  recharts), `RingGauge`, `ProgressBar` / `StackedProgressBar` / `StepProgress`, `Breakdown`
+  (a stacked bar + ranked share rows, pressable to drill; `maxRows` folds the long tail behind a
+  "Show N more" toggle — `labels` to localize — so several facet cards align to one height in a row),
   `StatusGrid` + `StatusLegend`, `Heatmap`.
 - **Surfaces & layout** — `Card` (+ `CardHeader`/`CardHeaderTitle`/`CardHeaderMeta`/`CardBody`/
   `CardFooter`), `SectionCard`, `SectionHeading` (+ `SectionHeadingTitle`), `PageHeader` /
@@ -414,8 +416,10 @@ was only ever about the review surfaces' sparkles/severity glyphs, not functiona
   highlight (and `marked` — a resting blue tint — for a bulk-ticked row). `Peek` is ONLY for
   secondary references, never the primary row press.
 - **One view-control vocabulary** (all 40px, `sm` labels, in one wrapping band):
-  · `SearchInput` is THE search box — a rounded white pill with a thin zinc-300 border. Never a
-    bare `TextInputField` + search icon.
+  · `SearchInput` is THE search box — a white `TextInputField` preset (rounded-8 like every other
+    input, a thin zinc-300 border, the leading search glyph + a clear ✕). It reads as search by its
+    ICON + white fill, not a distinct shape, so a toolbar of controls stays one consistent band.
+    Never a bare `TextInputField` + search icon.
   · `ChipGroup` is THE one-of-N lens (≤ ~10 options the user flips between; include "All"; counts in
     the label). Filters ONE list to a SUBSET — including by process stage / lifecycle state.
   · `FilterPill` is THE secondary-dimension filter — a compact pill that opens a composed popover
@@ -462,7 +466,9 @@ Full worked-example screens ship in the package — **read the source at
 recipe for a screen JOB; copy and adapt). Pick by the job:
 
 - **Monitor & decide** — `tpl_dashboard` (KPIStrip + trends + attention list) · `tpl_stock`
-  (10k-record faceted funnel) · `tpl_tower` (live `StatusGrid` wallboard) · `tpl_rollup`
+  (10k-record faceted funnel) · `tpl_report` (scope-first lookup report — a header period +
+  one-of-N dimension search drives KPIs → aligned facets w/ a `maxRows` long-tail toggle →
+  paginated register → export) · `tpl_tower` (live `StatusGrid` wallboard) · `tpl_rollup`
   (hierarchical totals).
 - **Work execution** — `app_orders` (stage-gated work queue) · `tpl_crm_desk` (assign & work +
   `FloatingActionBar`) · `tpl_callsheet` (call console) · `tpl_convert` (staged conversion) ·

package/examples/tpl_report.tsx

@@ -0,0 +1,413 @@
+import { useMemo, useState } from "react";
+import { ScrollView, View } from "react-native";
+import { Text } from "@lotics/ui/text";
+import { colors, ramp, solid, type ColorName } from "@lotics/ui/colors";
+import { Badge } from "@lotics/ui/badge";
+import { Breakdown } from "@lotics/ui/breakdown";
+import { Button } from "@lotics/ui/button";
+import { Card, CardFooter, CardHeader, CardHeaderTitle } from "@lotics/ui/card";
+import { Combobox } from "@lotics/ui/combobox";
+import { type PickerOption } from "@lotics/ui/picker";
+import { DateRangeFilterField } from "@lotics/ui/date_range_filter_field";
+import { type DateFilterValue } from "@lotics/ui/date_filter";
+import { Divider } from "@lotics/ui/divider";
+import { EmptyState } from "@lotics/ui/empty_state";
+import { KPIStrip } from "@lotics/ui/kpi_strip";
+import { Link } from "@lotics/ui/link";
+import { Pagination } from "@lotics/ui/pagination";
+import { PillButton } from "@lotics/ui/pill_button";
+import { SegmentedControl, type SegmentOption } from "@lotics/ui/segmented_control";
+import { formatMoney } from "@lotics/ui/format_money";
+import { formatDate, parseDate } from "@lotics/ui/format_date";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Template · Lookup report — answer a question by SCOPING a dataset, not by
+// browsing it. The scope bar leads: a period (header band) + ONE search key
+// chosen from several mutually-exclusive dimensions (SegmentedControl → the
+// matching picker; switching the key resets the value). That scope drives
+// everything below — KPI totals → a row of pressable Breakdown facets (the
+// long-tail one folds behind a "Show more") → the paginated register of
+// matching lines → Export. The fee / transaction / usage lookup desk: leave the
+// search empty and a period alone gives the whole-period report.
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Search DIMENSIONS — the one-of-N axis you look up by (distinct from the facets
+// you slice by below). Two are entities you pick from a list, one is a free-text
+// code — the SegmentedControl swaps the picker.
+type Dimension = "customer" | "reference" | "operator";
+const DIMENSIONS: SegmentOption<Dimension>[] = [
+  { label: "Customer", value: "customer" },
+  { label: "Reference", value: "reference" },
+  { label: "Operator", value: "operator" },
+];
+
+// Facets — attributes you SLICE the scoped set by. Method/status carry meaning
+// (each its own ColorName); category is coherent (one hue, shaded by `ramp`).
+const METHODS = [
+  { key: "transfer", label: "Bank transfer", color: "emerald" },
+  { key: "card", label: "Card", color: "blue" },
+  { key: "cash", label: "Cash", color: "amber" },
+  { key: "wallet", label: "E-wallet", color: "violet" },
+  { key: "cheque", label: "Cheque", color: "zinc" },
+] as const satisfies readonly { key: string; label: string; color: ColorName }[];
+
+const STATUSES = [
+  { key: "settled", label: "Settled", color: "emerald" },
+  { key: "pending", label: "Pending", color: "amber" },
+  { key: "refunded", label: "Refunded", color: "zinc" },
+] as const satisfies readonly { key: string; label: string; color: ColorName }[];
+
+const CATEGORIES = [
+  { key: "rent", label: "Rent" },
+  { key: "payroll", label: "Payroll" },
+  { key: "supplies", label: "Supplies" },
+  { key: "utilities", label: "Utilities" },
+  { key: "freight", label: "Freight" },
+  { key: "insurance", label: "Insurance" },
+  { key: "marketing", label: "Marketing" },
+  { key: "travel", label: "Travel" },
+  { key: "misc", label: "Misc" },
+] as const;
+const CATEGORY_RAMP = ramp("teal", CATEGORIES.length);
+
+const CUSTOMERS = [
+  "Atlas Trading Co.", "Brightway Logistics", "Crest Manufacturing", "Delta Foods",
+  "Evergreen Supply", "Northstar Retail", "Pioneer Energy", "Sunrise Imports",
+] as const;
+const OPERATORS = [
+  "Avery Cole", "Bianca Ross", "Caleb Munoz", "Dana Pham", "Elliot Shaw",
+  "Farah Idris", "Grace Tan", "Hugo Berg", "Isla Reyes", "Jonah Webb", "Kira Adams",
+] as const;
+
+type MethodKey = (typeof METHODS)[number]["key"];
+type StatusKey = (typeof STATUSES)[number]["key"];
+type CategoryKey = (typeof CATEGORIES)[number]["key"];
+
+interface Payment {
+  id: string;
+  customer: string;
+  operator: string;
+  method: MethodKey;
+  status: StatusKey;
+  category: CategoryKey;
+  date: string; // ISO yyyy-MM-dd
+  amount: number;
+  receipt: string | null; // settled payments carry a receipt no.
+}
+
+// 56 deterministic payments — integer hashing (not Math.random) so the page is
+// stable across reloads. Distributions are intentionally uneven, the way a real
+// ledger is: transfers dominate, most settled, a long tail of categories.
+function hash(i: number, salt: number): number {
+  let x = (i + 1) * 2654435761 + salt * 40503;
+  x = ((x >>> 16) ^ x) * 0x45d9f3b;
+  x = ((x >>> 16) ^ x) * 0x45d9f3b;
+  return (x >>> 16) % 1000;
+}
+function pick<T>(i: number, salt: number, weighted: [T, number][]): T {
+  const total = weighted.reduce((s, [, w]) => s + w, 0);
+  let roll = hash(i, salt) % total;
+  for (const [item, w] of weighted) {
+    if (roll < w) return item;
+    roll -= w;
+  }
+  return weighted[0][0];
+}
+
+const PAYMENTS: Payment[] = Array.from({ length: 56 }, (_, i) => {
+  const method = pick<MethodKey>(i, 1, [["transfer", 44], ["card", 24], ["wallet", 14], ["cash", 11], ["cheque", 7]]);
+  const status = pick<StatusKey>(i, 2, [["settled", 74], ["pending", 18], ["refunded", 8]]);
+  const category = pick<CategoryKey>(i, 3, [["freight", 22], ["supplies", 18], ["payroll", 14], ["rent", 12], ["utilities", 10], ["insurance", 8], ["marketing", 7], ["travel", 5], ["misc", 4]]);
+  const customer = CUSTOMERS[hash(i, 4) % CUSTOMERS.length];
+  const operator = OPERATORS[hash(i, 5) % OPERATORS.length];
+  const day = 1 + (hash(i, 6) % 28);
+  const amount = (3 + (hash(i, 7) % 96)) * 500_000; // 1.5M – 49.5M ₫
+  return {
+    id: `PMT-${String(1042 + i)}`,
+    customer, operator, method, status, category,
+    date: `2026-05-${String(day).padStart(2, "0")}`,
+    amount,
+    receipt: status === "settled" ? `RC-${String(8800 + i)}` : null,
+  };
+});
+
+const PAGE_SIZE = 10;
+const REFERENCES = PAYMENTS.map((p) => p.id);
+const methodOf = (k: MethodKey) => METHODS.find((m) => m.key === k)!;
+const statusOf = (k: StatusKey) => STATUSES.find((s) => s.key === k)!;
+
+// A bound's date as a day-start / day-end instant, so the period includes both
+// endpoints whole. (A real app sends these to the server; here it filters rows.)
+function periodBounds(v: DateFilterValue): { start: number | null; end: number | null } {
+  const start = v.start.date ? new Date(v.start.date).setHours(0, 0, 0, 0) : null;
+  const end = v.end.date ? new Date(v.end.date).setHours(23, 59, 59, 999) : null;
+  return { start, end };
+}
+
+export function TplReport() {
+  // Scope: a period (header) + one search dimension's value (scope bar).
+  const [period, setPeriod] = useState<DateFilterValue>({
+    start: { date: new Date(2026, 4, 1), time: null },
+    end: { date: new Date(2026, 4, 31), time: null },
+  });
+  const [dimension, setDimension] = useState<Dimension>("customer");
+  const [customer, setCustomer] = useState<string | null>(null);
+  const [operator, setOperator] = useState<string | null>(null);
+  const [reference, setReference] = useState<string | null>(null);
+
+  // Facets (slice the scoped set) — combine with AND.
+  const [method, setMethod] = useState<string | null>(null);
+  const [status, setStatus] = useState<string | null>(null);
+  const [category, setCategory] = useState<string | null>(null);
+  const [page, setPage] = useState(0);
+
+  // Switching the search dimension clears the value (one key at a time).
+  const switchDimension = (d: Dimension) => {
+    if (d === dimension) return;
+    setDimension(d); setCustomer(null); setOperator(null); setReference(null); setPage(0);
+  };
+  const setFacet = (set: (v: string | null) => void) => (v: string | null) => { set(v); setPage(0); };
+
+  const inScope = useMemo(() => {
+    const { start, end } = periodBounds(period);
+    return (p: Payment) => {
+      const t = parseDate(p.date)?.getTime() ?? 0;
+      if (start !== null && t < start) return false;
+      if (end !== null && t > end) return false;
+      if (dimension === "customer" && customer && p.customer !== customer) return false;
+      if (dimension === "operator" && operator && p.operator !== operator) return false;
+      if (dimension === "reference" && reference && p.id !== reference) return false;
+      return true;
+    };
+  }, [period, dimension, customer, operator, reference]);
+
+  // Each facet's totals respect the OTHER facets (and the scope) — the slice you
+  // could still drill into, not the unfiltered universe.
+  const facetMatch = (p: Payment, skip: "method" | "status" | "category") =>
+    (skip === "method" || !method || p.method === method) &&
+    (skip === "status" || !status || p.status === status) &&
+    (skip === "category" || !category || p.category === category);
+
+  const { byMethod, byStatus, byCategory, rows, total, customers } = useMemo(() => {
+    const byMethod = new Map<string, number>();
+    const byStatus = new Map<string, number>();
+    const byCategory = new Map<string, number>();
+    const rows: Payment[] = [];
+    const customers = new Set<string>();
+    let total = 0;
+    for (const p of PAYMENTS) {
+      if (!inScope(p)) continue;
+      if (facetMatch(p, "method")) byMethod.set(p.method, (byMethod.get(p.method) ?? 0) + p.amount);
+      if (facetMatch(p, "status")) byStatus.set(p.status, (byStatus.get(p.status) ?? 0) + p.amount);
+      if (facetMatch(p, "category")) byCategory.set(p.category, (byCategory.get(p.category) ?? 0) + p.amount);
+      if (facetMatch(p, "method") && facetMatch(p, "status") && facetMatch(p, "category")) {
+        rows.push(p); total += p.amount; customers.add(p.customer);
+      }
+    }
+    return { byMethod, byStatus, byCategory, rows, total, customers };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [inScope, method, status, category]);
+
+  const pageRows = rows.slice(page * PAGE_SIZE, (page + 1) * PAGE_SIZE);
+
+  const chips: { key: string; label: string; clear: () => void }[] = [
+    ...(method ? [{ key: "m", label: methodOf(method as MethodKey).label, clear: () => setFacet(setMethod)(null) }] : []),
+    ...(status ? [{ key: "s", label: statusOf(status as StatusKey).label, clear: () => setFacet(setStatus)(null) }] : []),
+    ...(category ? [{ key: "c", label: CATEGORIES.find((c) => c.key === category)!.label, clear: () => setFacet(setCategory)(null) }] : []),
+  ];
+
+  return (
+    <ScrollView style={{ flex: 1, backgroundColor: colors.zinc[50] }} contentContainerStyle={{ padding: 28 }}>
+      <View style={{ width: "100%", maxWidth: 1100, alignSelf: "center", gap: 16 }}>
+        {/* header band — title + the persistent period + the one primary action */}
+        <View style={{ flexDirection: "row", gap: 16, alignItems: "flex-start", flexWrap: "wrap", zIndex: 20 }}>
+          <View style={{ gap: 2, flex: 1, minWidth: 260 }}>
+            <Text size="xl" weight="semibold">Payments</Text>
+            <Text size="sm" color="muted">Look up payments by customer, reference, or operator across a period — totals, facets, and the matching lines</Text>
+          </View>
+          <View style={{ flexDirection: "row", gap: 12, alignItems: "center", flexWrap: "wrap" }}>
+            <View style={{ minWidth: 240 }}>
+              <DateRangeFilterField value={period} onValueChange={setPeriod} locale="en-US" />
+            </View>
+            <Button icon="download" title="Export" color="primary" onPress={() => {}} />
+          </View>
+        </View>
+
+        {/* scope bar — choose a dimension, then a value (the picker swaps) */}
+        <Card>
+          <View style={{ paddingHorizontal: 20, paddingVertical: 16, gap: 10, zIndex: 10 }}>
+            <View style={{ flexDirection: "row", gap: 12, flexWrap: "wrap", alignItems: "center" }}>
+              <SegmentedControl
+                accessibilityLabel="Search dimension"
+                options={DIMENSIONS}
+                value={dimension}
+                onValueChange={switchDimension}
+              />
+              <View style={{ flexGrow: 1, flexBasis: 300, minWidth: 240 }}>
+                {dimension === "customer" ? (
+                  <NamePicker key="customer" names={CUSTOMERS} selected={customer} onSelect={(v) => { setCustomer(v); setPage(0); }} placeholder="Search a customer…" label="customer" />
+                ) : dimension === "operator" ? (
+                  <NamePicker key="operator" names={OPERATORS} selected={operator} onSelect={(v) => { setOperator(v); setPage(0); }} placeholder="Search an operator…" label="operator" />
+                ) : (
+                  <NamePicker key="reference" names={REFERENCES} selected={reference} onSelect={(v) => { setReference(v); setPage(0); }} placeholder="Search a reference…" label="reference" />
+                )}
+              </View>
+            </View>
+            <Text size="xs" color="muted">Leave the search empty to report on every payment in the period.</Text>
+          </View>
+        </Card>
+
+        {/* the scoped totals — follow the period + search, not the facets below */}
+        <KPIStrip
+          items={[
+            { label: "Total", value: total, format: "currency", info: "Sum of every payment matching the period + search — not affected by the facet selections below." },
+            { label: "Payments", value: rows.length, format: "number" },
+            { label: "Customers", value: customers.size, format: "number", info: "Distinct customers in the matching set." },
+          ]}
+        />
+
+        {/* facets — press a segment to filter the register; selections combine */}
+        <View style={{ flexDirection: "row", gap: 16, alignItems: "stretch", flexWrap: "wrap" }}>
+          <Card style={{ padding: 0, flexGrow: 1, flexBasis: 300 }}>
+            <CardHeader><CardHeaderTitle info="Payment value by method. Press a method to filter the lines below — combines with status and category.">By method</CardHeaderTitle></CardHeader>
+            <View style={{ paddingHorizontal: 20, paddingVertical: 16 }}>
+              <Breakdown
+                items={METHODS.map((m) => ({ key: m.key, label: m.label, value: byMethod.get(m.key) ?? 0, color: solid(m.color) })).filter((e) => e.value > 0)}
+                selectedKey={method}
+                onSelect={setFacet(setMethod)}
+                formatValue={(n) => formatMoney(n, { compact: true })}
+              />
+            </View>
+          </Card>
+          <Card style={{ padding: 0, flexGrow: 1, flexBasis: 300 }}>
+            <CardHeader><CardHeaderTitle info="Where each payment stands — pending and refunded are the slices to watch.">By status</CardHeaderTitle></CardHeader>
+            <View style={{ paddingHorizontal: 20, paddingVertical: 16 }}>
+              <Breakdown
+                items={STATUSES.map((s) => ({ key: s.key, label: s.label, value: byStatus.get(s.key) ?? 0, color: solid(s.color) })).filter((e) => e.value > 0)}
+                selectedKey={status}
+                onSelect={setFacet(setStatus)}
+                formatValue={(n) => formatMoney(n, { compact: true })}
+              />
+            </View>
+          </Card>
+          <Card style={{ padding: 0, flexGrow: 1, flexBasis: 300 }}>
+            <CardHeader><CardHeaderTitle info="Value by spend category. The long tail folds behind a toggle so the card stays the same height as its neighbours.">By category</CardHeaderTitle></CardHeader>
+            <View style={{ paddingHorizontal: 20, paddingVertical: 16 }}>
+              <Breakdown
+                items={CATEGORIES.map((c, i) => ({ key: c.key, label: c.label, value: byCategory.get(c.key) ?? 0, color: CATEGORY_RAMP[i] })).filter((e) => e.value > 0).sort((a, b) => b.value - a.value)}
+                selectedKey={category}
+                onSelect={setFacet(setCategory)}
+                formatValue={(n) => formatMoney(n, { compact: true })}
+                maxRows={5}
+              />
+            </View>
+          </Card>
+        </View>
+
+        {/* the register — paginated; scope + facets feed it */}
+        <Card style={{ padding: 0 }}>
+          <CardHeader>
+            <CardHeaderTitle info="Every payment matching the scope + facets. The receipt links the settled ones.">Payments</CardHeaderTitle>
+            {chips.length > 0 ? (
+              <View style={{ flexDirection: "row", alignItems: "center", gap: 8, flexWrap: "wrap" }}>
+                {chips.map((c) => (
+                  <PillButton key={c.key} onDismiss={c.clear} dismissTooltip="Clear filter">
+                    <Text size="xs" weight="medium" color="muted">{c.label}</Text>
+                  </PillButton>
+                ))}
+              </View>
+            ) : null}
+          </CardHeader>
+
+          {/* eyebrow columns */}
+          <View style={{ flexDirection: "row", alignItems: "center", gap: 12, paddingHorizontal: 20, paddingVertical: 10 }}>
+            <Text size="xs" color="muted" transform="uppercase" style={{ width: 92 }}>Reference</Text>
+            <Text size="xs" color="muted" transform="uppercase" style={{ flex: 1.3 }}>Customer</Text>
+            <Text size="xs" color="muted" transform="uppercase" style={{ flex: 1 }}>Operator</Text>
+            <Text size="xs" color="muted" transform="uppercase" style={{ width: 70 }}>Date</Text>
+            <Text size="xs" color="muted" transform="uppercase" tabular align="right" style={{ width: 116 }}>Amount</Text>
+            <Text size="xs" color="muted" transform="uppercase" style={{ width: 92 }}>Receipt</Text>
+            <Text size="xs" color="muted" transform="uppercase" style={{ width: 96 }}>Status</Text>
+          </View>
+          <Divider />
+
+          {pageRows.length === 0 ? (
+            <EmptyState message="No payments match this scope" hint="Widen the period, change the search, or clear a facet chip" />
+          ) : (
+            pageRows.map((p, i) => (
+              <View key={p.id}>
+                {i > 0 ? <Divider /> : null}
+                <View style={{ flexDirection: "row", alignItems: "center", gap: 12, paddingHorizontal: 20, minHeight: 56 }}>
+                  <Text size="sm" weight="medium" tabular style={{ width: 92 }}>{p.id}</Text>
+                  <View style={{ flex: 1.3, gap: 2 }}>
+                    <Text size="sm" numberOfLines={1}>{p.customer}</Text>
+                    <Text size="xs" color="muted">{methodOf(p.method).label}</Text>
+                  </View>
+                  <Text size="sm" color="muted" numberOfLines={1} style={{ flex: 1 }}>{p.operator}</Text>
+                  <Text size="sm" tabular style={{ width: 70 }}>{formatDate(p.date, { format: "dayMonth", locale: "en-US" })}</Text>
+                  <Text size="sm" weight="medium" tabular align="right" style={{ width: 116 }}>{formatMoney(p.amount)}</Text>
+                  <View style={{ width: 92 }}>
+                    {p.receipt ? (
+                      <Link onPress={() => {}} accessibilityLabel={`Open receipt ${p.receipt}`}>{p.receipt}</Link>
+                    ) : (
+                      <Text size="sm" color="muted">—</Text>
+                    )}
+                  </View>
+                  <View style={{ width: 96 }}>
+                    <Badge variant="dot" label={statusOf(p.status).label} color={statusOf(p.status).color} />
+                  </View>
+                </View>
+              </View>
+            ))
+          )}
+
+          <CardFooter>
+            <Text size="xs" color="muted" tabular style={{ flex: 1 }}>
+              {`${rows.length.toLocaleString("en-US")} payments · ${formatMoney(total, { compact: true })}${chips.length > 0 ? " (filtered)" : ""}`}
+            </Text>
+            <Pagination
+              page={page}
+              pageSize={PAGE_SIZE}
+              rowCount={pageRows.length}
+              hasMore={(page + 1) * PAGE_SIZE < rows.length}
+              total={rows.length}
+              onPageChange={setPage}
+            />
+          </CardFooter>
+        </Card>
+      </View>
+    </ScrollView>
+  );
+}
+
+// A pick-from-list search — a Combobox over a fixed name list, filtered as you
+// type, with an inline clear. The scope bar's entity dimensions (customer,
+// operator) use it; the code dimension (reference) uses a free-text SearchInput.
+function NamePicker(props: {
+  names: readonly string[];
+  selected: string | null;
+  onSelect: (v: string | null) => void;
+  placeholder: string;
+  label: string;
+}) {
+  const { names, selected, onSelect, placeholder, label } = props;
+  const [q, setQ] = useState("");
+  const options = useMemo<PickerOption<string>[]>(() => {
+    const needle = q.trim().toLowerCase();
+    return names.filter((n) => !needle || n.toLowerCase().includes(needle)).map((n) => ({ value: n, label: n }));
+  }, [names, q]);
+  return (
+    <Combobox<string>
+      options={options}
+      value={selected ? { value: selected, label: selected } : null}
+      clearable
+      clearLabel={`Clear ${label}`}
+      onClear={() => onSelect(null)}
+      onSearchChange={setQ}
+      onValueChange={(opt) => onSelect(opt.value)}
+      placeholder={placeholder}
+      emptyText={`No ${label} matches`}
+      accessibilityLabel={`Search ${label}`}
+    />
+  );
+}

package/examples/tpl_stock.tsx

@@ -56,6 +56,11 @@ const DEPOTS = [
   { key: "northgate", label: "Northgate" },
   { key: "riverside", label: "Riverside" },
   { key: "southbay", label: "Southbay" },
+  { key: "westpoint", label: "Westpoint" },
+  { key: "harborview", label: "Harborview" },
+  { key: "lakeside", label: "Lakeside" },
+  { key: "midvale", label: "Midvale" },
+  { key: "fairlawn", label: "Fairlawn" },
 ] as const;
 const DEPOT_RAMP = ramp("violet", DEPOTS.length);
 
@@ -101,7 +106,7 @@ const TYPE_BASE_VALUE: Record<TypeKey, number> = {
 const UNITS: Unit[] = Array.from({ length: 10_482 }, (_, i) => {
   const type = pick<TypeKey>(i, 1, [["dry40", 34], ["dry20", 26], ["hc40", 18], ["reefer", 12], ["opentop", 7], ["tank", 3]]);
   const status = pick<StatusKey>(i, 2, [["leased", 52], ["yard", 18], ["transit", 14], ["repair", 9], ["idle", 7]]);
-  const depot = pick<DepotKey>(i, 3, [["eastport", 38], ["northgate", 27], ["riverside", 21], ["southbay", 14]]);
+  const depot = pick<DepotKey>(i, 3, [["eastport", 26], ["northgate", 19], ["riverside", 15], ["southbay", 11], ["westpoint", 9], ["harborview", 7], ["lakeside", 5], ["midvale", 4], ["fairlawn", 4]]);
   const ageYears = 1 + (hash(i, 4) % 12);
   const day = 1 + (hash(i, 5) % 28);
   const month = status === "idle" ? 1 + (hash(i, 6) % 4) : 4 + (hash(i, 6) % 3);
@@ -241,10 +246,13 @@ export function TplStock() {
               </CardHeaderTitle>
             </CardHeader>
             <View style={{ paddingHorizontal: 20, paddingVertical: 16 }}>
+              {/* maxRows caps the long tail behind a "Show N more" toggle, so a
+                  many-depot facet stays the same height as its neighbours. */}
               <Breakdown
                 items={DEPOTS.map((d, i) => ({ key: d.key, label: d.label, value: byDepot.get(d.key) ?? 0, color: DEPOT_RAMP[i] }))}
                 selectedKey={depot}
                 onSelect={setFacet(setDepot)}
+                maxRows={5}
               />
             </View>
           </Card>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "4.7.0",
+  "version": "4.9.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",

package/src/breakdown.tsx

@@ -1,5 +1,7 @@
+import { useState } from "react";
 import { StyleSheet, View } from "react-native";
 import { colors, withAlpha } from "./colors";
+import { Icon } from "./icon";
 import { PressableHighlight } from "./pressable_highlight";
 import { StackedProgressBar } from "./stacked_progress_bar";
 import { Text } from "./text";
@@ -12,6 +14,15 @@ export interface BreakdownItem {
   color: string;
 }
 
+/** Expand/collapse labels for a capped breakdown (`maxRows`). Localized
+ *  downstream — the kit ships English defaults. */
+export interface BreakdownLabels {
+  /** The expand affordance, given how many rows are currently hidden. */
+  more: (hidden: number) => string;
+  /** The collapse affordance. */
+  less: string;
+}
+
 export interface BreakdownProps {
   items: BreakdownItem[];
   /** The drilled-in segment. While set, the other segments dim. */
@@ -20,9 +31,17 @@ export interface BreakdownProps {
    * render an informational breakdown. */
   onSelect?: (key: string | null) => void;
   formatValue?: (n: number) => string;
+  /** Cap the visible rows; the rest fold behind a "show more" toggle. Keeps a
+   *  long-tail breakdown a fixed height (so several align in a row) while staying
+   *  fully drillable on expand. The stacked bar always reflects ALL items. Omit
+   *  to show every row. */
+  maxRows?: number;
+  /** Expand/collapse labels (defaults to English). */
+  labels?: BreakdownLabels;
 }
 
 const defaultFormat = (n: number): string => n.toLocaleString("en-US");
+const DEFAULT_LABELS: BreakdownLabels = { more: (hidden) => `Show ${hidden} more`, less: "Show less" };
 
 /**
  * Composition browser for LARGE populations — the answer to "what is my
@@ -34,8 +53,15 @@ const defaultFormat = (n: number): string => n.toLocaleString("en-US");
  * full faceted overview; selections combine in the host's filter state.
  */
 export function Breakdown(props: BreakdownProps) {
-  const { items, selectedKey = null, onSelect, formatValue = defaultFormat } = props;
+  const { items, selectedKey = null, onSelect, formatValue = defaultFormat, maxRows, labels = DEFAULT_LABELS } = props;
   const total = items.reduce((sum, item) => sum + item.value, 0);
+  const [expanded, setExpanded] = useState(false);
+  // Cap the rows when `maxRows` is set and the tail is longer; the bar still
+  // reflects every item, only the ranked list folds.
+  const cap = maxRows ?? items.length;
+  const collapsible = items.length > cap;
+  const hidden = items.length - cap;
+  const visible = collapsible && !expanded ? items.slice(0, cap) : items;
 
   return (
     <View style={styles.container}>
@@ -49,7 +75,7 @@ export function Breakdown(props: BreakdownProps) {
         }))}
       />
       <View>
-        {items.map((item) => {
+        {visible.map((item) => {
           const share = total > 0 ? Math.round((item.value / total) * 100) : 0;
           const selected = selectedKey === item.key;
           const dimmed = selectedKey !== null && !selected;
@@ -84,6 +110,20 @@ export function Breakdown(props: BreakdownProps) {
             </View>
           );
         })}
+        {collapsible ? (
+          <PressableHighlight
+            accessibilityRole="button"
+            accessibilityState={{ expanded }}
+            accessibilityLabel={expanded ? labels.less : labels.more(hidden)}
+            onPress={() => setExpanded((e) => !e)}
+            style={[styles.row, styles.pressable, styles.toggle]}
+          >
+            <Text size="sm" weight="medium" color="muted">
+              {expanded ? labels.less : labels.more(hidden)}
+            </Text>
+            <Icon name={expanded ? "chevron-up" : "chevron-down"} size={16} color={colors.zinc[400]} />
+          </PressableHighlight>
+        ) : null}
       </View>
     </View>
   );
@@ -96,7 +136,7 @@ const styles = StyleSheet.create({
   row: {
     flexDirection: "row",
     alignItems: "center",
-    gap: 10,
+    gap: 8,
     minHeight: 36,
   },
   pressable: {
@@ -116,6 +156,10 @@ const styles = StyleSheet.create({
     flex: 1,
   },
   share: {
-    width: 36,
+    width: 30,
+  },
+  toggle: {
+    gap: 4,
+    minHeight: 32,
   },
 });

package/src/combobox.tsx

@@ -290,7 +290,7 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
 
   return (
     <View style={style}>
-      <View ref={triggerRef} style={multi ? [styles.multiBox, open && styles.openRing] : undefined}>
+      <View ref={triggerRef} style={multi ? [styles.multiBox, showList && styles.openRing] : undefined}>
         {multi
           ? chips.map((chip) => (
               <View key={chip.value} style={styles.chip}>
@@ -342,7 +342,11 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
             multi ? styles.multiInput : showChevron ? styles.selectInput : undefined,
             // Single-select wears the open ring on the input (which holds the
             // border); multi wears it on the wrapper above (the input is borderless).
-            !multi && open ? styles.openRing : undefined,
+            // Gate on `showList`, not `open`: an empty query with no options has
+            // `open=true` but renders NO dropdown, so a ring tied to `open` would
+            // show with nothing below it AND linger after blur (no popover fires a
+            // close). The ring must mean "a dropdown is up".
+            !multi && showList ? styles.openRing : undefined,
           ]}
           role="combobox"
           aria-expanded={showList}
@@ -358,7 +362,14 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
       </View>
       <Popover
         open={showList}
-        onOpenChange={setOpen}
+        onOpenChange={(next) => {
+          setOpen(next);
+          // An outside dismiss closes the menu but leaves the textbox focused, so
+          // a keyboard `:focus-visible` ring would linger. Drop focus when the
+          // popover closes ITSELF — a commit refocuses through its own path
+          // (`commit` sets `open` directly), never through `onOpenChange`.
+          if (!next) inputRef.current?.blur();
+        }}
         triggerRef={triggerRef}
         side="bottom"
         align="start"

package/src/search_input.tsx

@@ -49,25 +49,27 @@ export function SearchInput(props: SearchInputProps) {
         onKeyPress={handleKeyPress}
         icon="search"
         clearable
-        style={styles.pill}
+        style={styles.search}
       />
     </View>
   );
 }
 
 const styles = StyleSheet.create({
-  // Search reads as a view-control by SHAPE (rounded pill + the leading
-  // search glyph). White fill pops against the zinc-50 canvas where most
-  // toolbars live; a zinc-300 border (one step up from the form-input
-  // hairline) keeps it defined on white cards too, where the fill alone
-  // would vanish. 40px (TextInputField default) — the system control height
-  // every band aligns to.
-  pill: {
-    borderRadius: 999,
+  // Search reads as a view-control by its leading search glyph + white fill —
+  // NOT by a distinct shape. It shares the rounded-8 radius of every other
+  // input/picker (TextInputField, Combobox, the date filter), so a toolbar of
+  // controls reads as one consistent band. The white fill still pops against
+  // the zinc-50 canvas where most toolbars live; a zinc-300 border (one step up
+  // from the form-input hairline) keeps it defined on white cards too, where
+  // the fill alone would vanish. 40px (TextInputField default) — the system
+  // control height every band aligns to.
+  search: {
+    borderRadius: 8,
     backgroundColor: colors.white,
-    // A thin 1px resting border (TextInputField's default width) — emphasis on
-    // interaction comes from the input's own focus outline, so the pill stays
-    // quiet at rest. zinc-300 keeps it defined on white cards.
+    // A thin 1px resting border (TextInputField's default width) — interaction
+    // emphasis comes from the input's own focus outline, so it stays quiet at
+    // rest. zinc-300 keeps it defined on white cards.
     borderColor: colors.zinc[300],
   },
 });