@lotics/ui 4.8.0 → 5.0.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "4.8.0",
+  "version": "5.0.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -61,14 +61,14 @@
     "./agent_run": "./src/agent_run.tsx",
     "./agent_progress": "./src/agent_progress.tsx",
     "./confidence": "./src/confidence.tsx",
-    "./suggestion": "./src/suggestion.tsx",
+    "./review_card": "./src/review_card.tsx",
     "./change_review": "./src/change_review.tsx",
     "./clarify": "./src/clarify.tsx",
     "./choice_list": "./src/choice_list.tsx",
     "./sources": "./src/sources.tsx",
-    "./record_review": "./src/record_review.tsx",
+    "./record_fields": "./src/record_fields.tsx",
     "./spec_list": "./src/spec_list.tsx",
-    "./match_row": "./src/match_row.tsx",
+    "./match_sides": "./src/match_sides.tsx",
     "./finding": "./src/finding.tsx",
     "./discrepancy": "./src/discrepancy.tsx",
     "./triage_row": "./src/triage_row.tsx",

package/src/agent_run.tsx

@@ -40,7 +40,7 @@ export interface AgentRunProps {
  * tinted disc behind a full-colour icon, fading in as each step arrives. A
  * running step spins (blue); a finished step settles to an emerald check; a
  * failure to a red alert. Pair with `Composer` (the command that starts a
- * run) and `Suggestion` (the result to review). Unlike `StepList` (a known,
+ * run) and `ReviewCard` (the result to review). Unlike `StepList` (a known,
  * guided run of fixed steps) the steps here arrive unknown-ahead.
  */
 export function AgentRun(props: AgentRunProps) {