@lotics/ui 7.1.0 → 7.2.0

package/AGENTS.md

@@ -97,7 +97,9 @@ Pick by capability, not by name. (→ the source file for the API.)
   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`.
+  `StatusGrid` + `StatusLegend`, `Heatmap` (density: colour-only, "where does it cluster"),
+  `Matrix` (the PIVOT cross-tab: the NUMBER in each cell — optionally a heat wash behind it — plus
+  row/column/grand totals; press a cell to drill).
 - **Surfaces & layout** — `Card` (+ `CardHeader`/`CardHeaderTitle`/`CardHeaderMeta`/`CardBody`/
   `CardFooter`), `SectionCard`, `SectionHeading` (+ `SectionHeadingTitle`), `PageHeader` /
   `PageContent`, `Stack`, `Spacer`, `Divider`, `Accordion`, `Tabs`, `SegmentedControl`, `Stepper`.
@@ -713,8 +715,9 @@ 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_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).
+  paginated register → export) · `tpl_tower` (live `StatusGrid` wallboard) · `tpl_pivot` (the
+  `Matrix` cross-tab desk: one dimension × another, number + heat per cell + row/col/grand totals,
+  press a cell to drill the list behind it) · `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) ·
   `tpl_inventory` (threshold actions) · `tpl_dossier` (high-volume paginated register) ·
@@ -798,7 +801,7 @@ step_progress · timeline (heterogeneous event LOG — per-row icon + expandable
 alert · peek · empty_state · completion_state · callout (Callout · CalloutTitle ·
 CalloutText · CalloutActions) · kpi_card · kpi_strip · metric · trend_chip · sparkline ·
 bar_chart · line_chart · pie_chart · ring_gauge · progress_bar · stacked_progress_bar · breakdown ·
-status_grid (StatusGrid + StatusLegend) · heatmap · legend_item · remainder_meter · allocation_row ·
+status_grid (StatusGrid + StatusLegend) · heatmap (density cross-tab — colour-only, no numbers) · matrix (Matrix — the PIVOT cross-tab: band-compound `Matrix` root + `Matrix.Header` (corner + axis labels) + `Matrix.Grid` (`display` number|heat|both — the cells, pressable, the value IN the cell) + `Matrix.Totals` (row + column + grand) + `Matrix.Legend`; the data layer `matrixTotals`/`MatrixAxisItem`/`MatrixCellRef` import from `@lotics/ui/matrix_totals`. Pick over `Heatmap` when the NUMBER and totals matter, not just where it clusters) · legend_item · remainder_meter · allocation_row ·
 scan_field · file_dropzone · files_editor (FilesEditor — THE all-in-one attachment field: FileGrid + a toolbar (Upload primary · Select · Download all) that swaps into a batch SELECT mode (Select all · a Menu of Download/Share/Delete · Done) + built-in gallery + Alert-confirmed remove; host wires `files` + `onAdd`/`onRemove` (+ optional `uploads`, `onShareSelected`, `readOnly`, `labels`, `galleryLabels`); mirrors the frontend cell_files_editor. Use FileGrid/FileRows bare only when you own the chrome) · file_grid (FileGrid — the upload-aware grid: completed files + a live upload queue in one surface; FileUpload/PendingUpload types; the add-files default) · uploading_thumbnail (UploadingThumbnail — the single in-flight upload tile FileGrid renders; reach for it only when hand-rolling a non-grid upload layout) · file_thumbnail · file_thumbnail_grid · file_row · file_rows (FileRows — batteries-included file list: row press → built-in gallery + a ⋯ Download/Open-external/Remove menu; composes FileRow + ActionMenu + FileGalleryModal) · file_preview ·
 file_gallery_modal · image_gallery · use_selection_mode · share_or_download · rotate_image · avatar · skeleton · activity_indicator · loading · divider ·
 spacer · stack · section_card · page_header · page_content · calendar (calendar/index.ts) · gantt ·

package/examples/tpl_pivot.tsx

@@ -0,0 +1,249 @@
+import { useMemo, useState } from "react";
+import { Pressable, ScrollView, View } from "react-native";
+import { Text } from "@lotics/ui/text";
+import { colors } from "@lotics/ui/colors";
+import { Badge } from "@lotics/ui/badge";
+import { Card, CardFooter, CardHeader, CardHeaderTitle } from "@lotics/ui/card";
+import { Divider } from "@lotics/ui/divider";
+import { Drawer } from "@lotics/ui/drawer";
+import { EmptyState } from "@lotics/ui/empty_state";
+import { KPIStrip } from "@lotics/ui/kpi_strip";
+import { Chip } from "@lotics/ui/chip";
+import { Matrix } from "@lotics/ui/matrix";
+import { type MatrixCellRef } from "@lotics/ui/matrix_totals";
+import { PressableRow } from "@lotics/ui/pressable_row";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Template · Pivot desk — one dimension crossed against another, then drill.
+// The Matrix is the hero: warehouse × category, the number IN each cell and a
+// heat wash behind it so the concentration reads at a glance, row/column/grand
+// totals down the edges. Pressing a cell is a door — the register below filters
+// to exactly that intersection; a row there opens the item drawer. The pattern
+// for "how does X distribute across Y, and what's behind each bucket?".
+// ─────────────────────────────────────────────────────────────────────────────
+
+const WAREHOUSES = [
+  { key: "chi", label: "Chicago" },
+  { key: "dal", label: "Dallas" },
+  { key: "nwk", label: "Newark" },
+  { key: "reno", label: "Reno" },
+  { key: "atl", label: "Atlanta" },
+] as const;
+
+const CATEGORIES = [
+  { key: "apparel", label: "Apparel" },
+  { key: "home", label: "Home" },
+  { key: "elec", label: "Electronics" },
+  { key: "outdoor", label: "Outdoor" },
+] as const;
+
+type WarehouseKey = (typeof WAREHOUSES)[number]["key"];
+type CategoryKey = (typeof CATEGORIES)[number]["key"];
+
+interface Sku {
+  code: string;
+  name: string;
+  warehouse: WarehouseKey;
+  category: CategoryKey;
+  units: number;
+  status: "in_stock" | "low" | "backorder";
+}
+
+// Deterministic mock catalogue — integer hashing, stable across reloads.
+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;
+}
+
+const NAMES = ["Cotton tee", "Wool throw", "USB hub", "Trail flask", "Rain shell", "Desk lamp", "Sport sock", "Cast pan", "Earbuds", "Tent peg", "Linen shirt", "Throw pillow"];
+
+const SKUS: Sku[] = (() => {
+  const out: Sku[] = [];
+  // A deliberate concentration in Newark · Electronics so a hot cell has a story.
+  for (let i = 0; i < 64; i++) {
+    const wRoll = hash(i, 1) % 100;
+    const warehouse: WarehouseKey =
+      wRoll < 18 ? "chi" : wRoll < 36 ? "dal" : wRoll < 66 ? "nwk" : wRoll < 84 ? "reno" : "atl";
+    const cRoll = hash(i, 2) % 100;
+    const category: CategoryKey =
+      warehouse === "nwk" && cRoll < 55 ? "elec" : cRoll < 30 ? "apparel" : cRoll < 55 ? "home" : cRoll < 78 ? "elec" : "outdoor";
+    const units = hash(i, 3) % 40;
+    out.push({
+      code: `SKU-${String(1000 + i)}`,
+      name: NAMES[hash(i, 4) % NAMES.length],
+      warehouse,
+      category,
+      units,
+      status: units === 0 ? "backorder" : units < 6 ? "low" : "in_stock",
+    });
+  }
+  return out;
+})();
+
+const whOf = (k: WarehouseKey) => WAREHOUSES.find((w) => w.key === k)!;
+const catOf = (k: CategoryKey) => CATEGORIES.find((c) => c.key === k)!;
+
+const STATUS: Record<Sku["status"], { label: string; color: "emerald" | "amber" | "red" }> = {
+  in_stock: { label: "In stock", color: "emerald" },
+  low: { label: "Low", color: "amber" },
+  backorder: { label: "Backorder", color: "red" },
+};
+
+const count = (n: number) => n.toLocaleString("en-US");
+
+function KVRow({ label, children }: { label: string; children: React.ReactNode }) {
+  return (
+    <View style={{ flexDirection: "row", alignItems: "center", gap: 12, minHeight: 28 }}>
+      <Text size="sm" color="muted" style={{ flex: 1 }}>{label}</Text>
+      {children}
+    </View>
+  );
+}
+
+export function TplPivot() {
+  const [cell, setCell] = useState<MatrixCellRef | null>(null);
+  const [openIdx, setOpenIdx] = useState<number | null>(null);
+
+  // Cell value = how many SKUs sit at that warehouse × category.
+  const counts = useMemo(() => {
+    const m = new Map<string, number>();
+    for (const s of SKUS) m.set(`${s.warehouse}|${s.category}`, (m.get(`${s.warehouse}|${s.category}`) ?? 0) + 1);
+    return m;
+  }, []);
+  const value = (w: string, c: string) => counts.get(`${w}|${c}`) ?? 0;
+
+  // The drill register follows the pressed cell; no cell = the whole catalogue.
+  const items = useMemo(
+    () => (cell ? SKUS.filter((s) => s.warehouse === cell.row && s.category === cell.col) : SKUS),
+    [cell],
+  );
+  const open = openIdx !== null ? items[openIdx] : null;
+
+  const totalUnits = SKUS.reduce((s, x) => s + x.units, 0);
+  const lowOrOut = SKUS.filter((s) => s.status !== "in_stock").length;
+
+  return (
+    <ScrollView style={{ flex: 1, backgroundColor: colors.zinc[50] }} contentContainerStyle={{ padding: 28 }}>
+      <View style={{ width: "100%", maxWidth: 960, alignSelf: "center", gap: 16 }}>
+        <View style={{ gap: 2 }}>
+          <Text size="xl" weight="semibold">Stock distribution</Text>
+          <Text size="sm" color="muted">Where each category sits across the network — press a cell to list what's behind it</Text>
+        </View>
+
+        <KPIStrip
+          items={[
+            { label: "SKUs", value: SKUS.length, format: "number" },
+            { label: "Units on hand", value: totalUnits, format: "number" },
+            { label: "Low or backorder", value: lowOrOut, format: "number", tone: lowOrOut > 0 ? "warning" : "default", caption: "need attention" },
+            { label: "Warehouses", value: WAREHOUSES.length, format: "number" },
+          ]}
+        />
+
+        <Card style={{ padding: 0 }}>
+          <CardHeader>
+            <CardHeaderTitle info="Number of SKUs at each warehouse × category; the wash deepens with the count. Press a cell to filter the list below to that intersection.">
+              SKUs by warehouse × category
+            </CardHeaderTitle>
+          </CardHeader>
+          <View style={{ paddingHorizontal: 20, paddingVertical: 16 }}>
+            <Matrix
+              rows={WAREHOUSES.map((w) => ({ key: w.key, label: w.label }))}
+              cols={CATEGORIES.map((c) => ({ key: c.key, label: c.label }))}
+              value={value}
+              selected={cell}
+              onSelectCell={(c) => { setCell(c); setOpenIdx(null); }}
+              heatColor="indigo"
+              formatValue={count}
+            >
+              <Matrix.Header corner="Warehouse \ Category" totalLabel="Total" />
+              <Matrix.Grid display="both" />
+              <Matrix.Totals label="Total" />
+              <Matrix.Legend lessLabel="Fewer" moreLabel="More" />
+            </Matrix>
+          </View>
+        </Card>
+
+        <Card style={{ padding: 0 }}>
+          <CardHeader>
+            <CardHeaderTitle info="Items behind the selected cell. Press a row to open it.">
+              Items
+            </CardHeaderTitle>
+            {cell ? (
+              <Chip onDismiss={() => { setCell(null); setOpenIdx(null); }} dismissTooltip="Clear cell">
+                <Text size="xs" weight="medium" color="muted">{`${whOf(cell.row as WarehouseKey).label} · ${catOf(cell.col as CategoryKey).label}`}</Text>
+              </Chip>
+            ) : null}
+          </CardHeader>
+
+          <View style={{ flexDirection: "row", alignItems: "center", gap: 12, paddingHorizontal: 20, paddingVertical: 10 }}>
+            <Text size="xs" color="muted" style={{ width: 96 }}>Code</Text>
+            <Text size="xs" color="muted" style={{ flex: 1 }}>Item</Text>
+            <Text size="xs" color="muted" align="right" style={{ width: 64 }}>Units</Text>
+            <Text size="xs" color="muted" style={{ width: 96 }}>Status</Text>
+          </View>
+          <Divider />
+
+          {items.length === 0 ? (
+            <View style={{ paddingHorizontal: 20, paddingVertical: 16 }}>
+              <EmptyState message="No items in this cell" hint="Press another cell or clear the filter" />
+            </View>
+          ) : (
+            items.slice(0, 10).map((s, i) => (
+              <View key={s.code}>
+                {i > 0 ? <Divider /> : null}
+                <PressableRow onPress={() => setOpenIdx(i)} selected={openIdx === i}>
+                  <Pressable
+                    accessibilityRole="button"
+                    accessibilityLabel={`Open ${s.code}`}
+                    onPress={() => setOpenIdx(i)}
+                    style={{ flex: 1, flexDirection: "row", alignItems: "center", gap: 12, minHeight: 44 }}
+                  >
+                    <Text size="sm" weight="medium" tabular style={{ width: 96 }} numberOfLines={1}>{s.code}</Text>
+                    <Text size="sm" style={{ flex: 1 }} numberOfLines={1}>{s.name}</Text>
+                    <Text size="sm" tabular align="right" style={{ width: 64 }}>{count(s.units)}</Text>
+                    <View style={{ width: 96 }}>
+                      <Badge variant="dot" label={STATUS[s.status].label} color={STATUS[s.status].color} />
+                    </View>
+                  </Pressable>
+                </PressableRow>
+              </View>
+            ))
+          )}
+
+          <CardFooter>
+            <Text size="xs" color="muted" tabular style={{ flex: 1 }}>
+              {items.length > 10 ? `Showing 10 of ${count(items.length)}` : `${count(items.length)} item${items.length === 1 ? "" : "s"}`}
+            </Text>
+          </CardFooter>
+        </Card>
+      </View>
+
+      {open !== null && openIdx !== null ? (
+        <Drawer
+          open
+          onOpenChange={(o) => !o && setOpenIdx(null)}
+          title={open.code}
+          width={420}
+          onPrev={openIdx > 0 ? () => setOpenIdx(openIdx - 1) : undefined}
+          onNext={openIdx < Math.min(items.length, 10) - 1 ? () => setOpenIdx(openIdx + 1) : undefined}
+          position={`${openIdx + 1}/${Math.min(items.length, 10)}`}
+        >
+          <View key={open.code} style={{ flex: 1, padding: 24, gap: 12 }}>
+            <Badge variant="dot" label={STATUS[open.status].label} color={STATUS[open.status].color} />
+            <View style={{ gap: 6, paddingTop: 4 }}>
+              <KVRow label="Item"><Text size="sm">{open.name}</Text></KVRow>
+              <Divider />
+              <KVRow label="Warehouse"><Text size="sm">{whOf(open.warehouse).label}</Text></KVRow>
+              <Divider />
+              <KVRow label="Category"><Text size="sm">{catOf(open.category).label}</Text></KVRow>
+              <Divider />
+              <KVRow label="Units on hand"><Text size="sm" tabular>{count(open.units)}</Text></KVRow>
+            </View>
+          </View>
+        </Drawer>
+      ) : null}
+    </ScrollView>
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "7.1.0",
+  "version": "7.2.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -55,6 +55,8 @@
     "./breakdown": "./src/breakdown.tsx",
     "./status_grid": "./src/status_grid.tsx",
     "./heatmap": "./src/heatmap.tsx",
+    "./matrix": "./src/matrix.tsx",
+    "./matrix_totals": "./src/matrix_totals.ts",
     "./trend_footer": "./src/trend_footer.tsx",
     "./locale": "./src/locale.tsx",
     "./spacing": "./src/spacing.ts",

package/src/matrix.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect } from "vitest";
+import { matrixTotals, type MatrixAxisItem } from "./matrix_totals";
+
+const rows: MatrixAxisItem[] = [
+  { key: "msc", label: "MSC" },
+  { key: "one", label: "ONE" },
+];
+const cols: MatrixAxisItem[] = [
+  { key: "20", label: "20ft" },
+  { key: "40", label: "40ft" },
+];
+
+// MSC: 20→5, 40→3 ; ONE: 20→0, 40→7
+const grid: Record<string, Record<string, number>> = {
+  msc: { "20": 5, "40": 3 },
+  one: { "20": 0, "40": 7 },
+};
+const value = (r: string, c: string) => grid[r]?.[c] ?? 0;
+
+describe("matrixTotals", () => {
+  it("sums each row across its columns", () => {
+    const { rowTotals } = matrixTotals(rows, cols, value);
+    expect(rowTotals.get("msc")).toBe(8);
+    expect(rowTotals.get("one")).toBe(7);
+  });
+
+  it("sums each column across its rows", () => {
+    const { colTotals } = matrixTotals(rows, cols, value);
+    expect(colTotals.get("20")).toBe(5);
+    expect(colTotals.get("40")).toBe(10);
+  });
+
+  it("grand total equals the sum of every cell", () => {
+    expect(matrixTotals(rows, cols, value).grandTotal).toBe(15);
+  });
+
+  it("max is the largest single cell, for the heat scale", () => {
+    expect(matrixTotals(rows, cols, value).max).toBe(7);
+  });
+
+  it("is all-zero for an empty axis", () => {
+    const r = matrixTotals([], cols, value);
+    expect(r.grandTotal).toBe(0);
+    expect(r.max).toBe(0);
+    expect(r.colTotals.get("20")).toBeUndefined();
+  });
+
+  it("counts a fully-empty grid as zero without dividing by it", () => {
+    const zero = matrixTotals(rows, cols, () => 0);
+    expect(zero.grandTotal).toBe(0);
+    expect(zero.max).toBe(0);
+    expect(zero.rowTotals.get("msc")).toBe(0);
+  });
+});

package/src/matrix.tsx

@@ -0,0 +1,347 @@
+import { Children, createContext, isValidElement, useContext, useMemo, type ReactNode } from "react";
+import { StyleSheet, View } from "react-native";
+import { colors, withAlpha, type ColorName } from "./colors";
+import { Text } from "./text";
+import { FocusRingPressable } from "./focus_ring_pressable";
+import { matrixTotals, type MatrixAxisItem, type MatrixCellRef } from "./matrix_totals";
+
+type Display = "number" | "heat" | "both";
+
+interface MatrixContextValue {
+  rows: MatrixAxisItem[];
+  cols: MatrixAxisItem[];
+  value: (row: string, col: string) => number;
+  max: number;
+  rowTotals: Map<string, number>;
+  colTotals: Map<string, number>;
+  grandTotal: number;
+  hasTotals: boolean;
+  selected: MatrixCellRef | null;
+  onSelectCell?: (cell: MatrixCellRef | null) => void;
+  heatBase: string;
+  formatValue: (n: number) => string;
+  rowLabelWidth: number;
+  totalColWidth: number;
+}
+
+const MatrixContext = createContext<MatrixContextValue | null>(null);
+
+function useMatrix(): MatrixContextValue {
+  const ctx = useContext(MatrixContext);
+  if (!ctx) throw new Error("Matrix.* must be rendered inside <Matrix>");
+  return ctx;
+}
+
+const defaultFormat = (n: number): string => n.toLocaleString("en-US");
+
+export interface MatrixProps {
+  /** Row dimension (e.g. one shipping line per row). The consumer pre-sorts. */
+  rows: MatrixAxisItem[];
+  /** Column dimension (e.g. container size). Few, fixed — they share the width. */
+  cols: MatrixAxisItem[];
+  /** The cell value at an intersection. Pure — keep it a Map lookup, not a scan. */
+  value: (row: string, col: string) => number;
+  /** The inspected cell. Press the same cell again to clear. */
+  selected?: MatrixCellRef | null;
+  /** Omit for an informational matrix (no drill-down). */
+  onSelectCell?: (cell: MatrixCellRef | null) => void;
+  /** Heat hue. Intensity is alpha within it; zero cells go neutral. Default blue. */
+  heatColor?: ColorName;
+  formatValue?: (n: number) => string;
+  /** Width of the leading row-label column. Default 140 (room for long names). */
+  rowLabelWidth?: number;
+  children: ReactNode;
+}
+
+/**
+ * A two-dimensional cross-tab — the pivot of one dimension against another
+ * ("how many of each line × size?"). Band-compound: the root owns the data,
+ * the heat scale, the totals and the cell-selection; you compose the opt-in
+ * bands — `Matrix.Header` (axis labels + corner), `Matrix.Grid` (the cells:
+ * a number, a heat wash, or both), `Matrix.Totals` (row + column + grand),
+ * `Matrix.Legend` (the less→more scale). Pressing a cell selects it for the
+ * host to drill (a filtered list underneath) — every number is a door. Omit a
+ * band for a different combination: `<Grid display="heat"/>` + `<Legend/>` is a
+ * density heatmap; add `<Totals/>` and `display="both"` for a full pivot table.
+ */
+export function Matrix(props: MatrixProps) {
+  const {
+    rows,
+    cols,
+    value,
+    selected = null,
+    onSelectCell,
+    heatColor = "blue",
+    formatValue = defaultFormat,
+    rowLabelWidth = 140,
+    children,
+  } = props;
+
+  // Marker, not reference identity — a bundler that loads two copies of this
+  // module (or a HMR swap) would break `c.type === MatrixTotals`; the static
+  // flag travels with whichever function the element points at.
+  const hasTotals = useMemo(
+    () => Children.toArray(children).some((c) => isValidElement(c) && typeof c.type === "function" && "isMatrixTotals" in c.type),
+    [children],
+  );
+
+  const { max, rowTotals, colTotals, grandTotal } = useMemo(
+    () => matrixTotals(rows, cols, value),
+    [rows, cols, value],
+  );
+
+  const ctx: MatrixContextValue = {
+    rows,
+    cols,
+    value,
+    max: Math.max(1, max),
+    rowTotals,
+    colTotals,
+    grandTotal,
+    hasTotals,
+    selected,
+    onSelectCell,
+    heatBase: colors[heatColor][600],
+    formatValue,
+    rowLabelWidth,
+    totalColWidth: 64,
+  };
+
+  return (
+    <MatrixContext.Provider value={ctx}>
+      <View style={styles.container}>{children}</View>
+    </MatrixContext.Provider>
+  );
+}
+
+export interface MatrixHeaderProps {
+  /** Top-left corner label — name the two axes, e.g. "Line \ Size". */
+  corner?: ReactNode;
+  /** Header for the trailing total column (only shown when `Matrix.Totals` is present). */
+  totalLabel?: string;
+}
+
+function MatrixHeader({ corner, totalLabel = "Total" }: MatrixHeaderProps) {
+  const { cols, rowLabelWidth, totalColWidth, hasTotals } = useMatrix();
+  return (
+    <View style={styles.headRow}>
+      <View style={[styles.rowLabel, { width: rowLabelWidth }]}>
+        {typeof corner === "string" ? (
+          <Text size="xs" color="muted" numberOfLines={1}>
+            {corner}
+          </Text>
+        ) : (
+          corner
+        )}
+      </View>
+      {cols.map((c) => (
+        <Text key={c.key} size="xs" color="muted" align="center" numberOfLines={1} style={styles.colCell}>
+          {c.label}
+        </Text>
+      ))}
+      {hasTotals ? (
+        <Text size="xs" color="muted" weight="medium" align="center" numberOfLines={1} style={[styles.totalCol, { width: totalColWidth }]}>
+          {totalLabel}
+        </Text>
+      ) : null}
+    </View>
+  );
+}
+
+export interface MatrixGridProps {
+  /** What each cell shows. `both` = a heat wash behind the number. Default `both`. */
+  display?: Display;
+}
+
+function MatrixGrid({ display = "both" }: MatrixGridProps) {
+  const ctx = useMatrix();
+  const { rows, cols, value, hasTotals, rowTotals, formatValue, rowLabelWidth, totalColWidth } = ctx;
+  return (
+    <View style={styles.grid}>
+      {rows.map((r) => (
+        <View key={r.key} style={styles.row}>
+          <Text size="sm" color="muted" numberOfLines={1} style={[styles.rowLabel, { width: rowLabelWidth }]}>
+            {r.label}
+          </Text>
+          {cols.map((c) => (
+            <MatrixCell key={c.key} ctx={ctx} display={display} row={r} col={c} value={value(r.key, c.key)} />
+          ))}
+          {hasTotals ? (
+            <Text size="sm" weight="semibold" tabular align="center" numberOfLines={1} style={[styles.totalCol, { width: totalColWidth }]}>
+              {formatValue(rowTotals.get(r.key) ?? 0)}
+            </Text>
+          ) : null}
+        </View>
+      ))}
+    </View>
+  );
+}
+
+interface MatrixCellProps {
+  ctx: MatrixContextValue;
+  display: Display;
+  row: MatrixAxisItem;
+  col: MatrixAxisItem;
+  value: number;
+}
+
+function MatrixCell({ ctx, display, row, col, value }: MatrixCellProps) {
+  const { max, selected, onSelectCell, heatBase, formatValue } = ctx;
+  const showHeat = display === "heat" || display === "both";
+  const showNumber = display === "number" || display === "both";
+
+  // A gentler wash behind a number (keeps it legible); the full ramp when the
+  // colour IS the value (a pure heatmap).
+  const background = showHeat
+    ? value === 0
+      ? colors.zinc[100]
+      : withAlpha(heatBase, display === "both" ? 0.05 + 0.4 * (value / max) : 0.15 + 0.85 * (value / max))
+    : colors.background;
+
+  const isSelected = selected?.row === row.key && selected?.col === col.key;
+  const pressable = !!onSelectCell && value > 0;
+  const label = `${row.label} · ${col.label}: ${formatValue(value)}`;
+
+  const content = showNumber ? (
+    <Text size="sm" weight="medium" tabular align="center" color={value === 0 ? "zinc-500" : "default"}>
+      {value === 0 ? "" : formatValue(value)}
+    </Text>
+  ) : null;
+
+  if (!pressable) {
+    return (
+      <View style={[styles.cell, { backgroundColor: background, borderColor: "transparent" }]} accessibilityLabel={showNumber ? undefined : label}>
+        {content}
+      </View>
+    );
+  }
+
+  return (
+    <FocusRingPressable
+      accessibilityRole="button"
+      accessibilityState={{ selected: isSelected }}
+      accessibilityLabel={label}
+      onPress={() => onSelectCell?.(isSelected ? null : { row: row.key, col: col.key })}
+      style={(state) => [
+        styles.cell,
+        {
+          backgroundColor: background,
+          borderColor: isSelected ? colors.zinc[900] : state.hovered ? colors.zinc[400] : "transparent",
+        },
+      ]}
+    >
+      {content}
+    </FocusRingPressable>
+  );
+}
+
+export interface MatrixTotalsProps {
+  /** The row label for the totals band, e.g. "Total". */
+  label?: string;
+}
+
+function MatrixTotals({ label = "Total" }: MatrixTotalsProps) {
+  const { cols, colTotals, grandTotal, formatValue, rowLabelWidth, totalColWidth } = useMatrix();
+  return (
+    <View style={styles.totalsRow}>
+      <Text size="sm" weight="semibold" color="muted" numberOfLines={1} style={[styles.rowLabel, { width: rowLabelWidth }]}>
+        {label}
+      </Text>
+      {cols.map((c) => (
+        <Text key={c.key} size="sm" weight="semibold" tabular align="center" numberOfLines={1} style={styles.colCell}>
+          {formatValue(colTotals.get(c.key) ?? 0)}
+        </Text>
+      ))}
+      <Text size="sm" weight="semibold" tabular align="center" numberOfLines={1} style={[styles.totalCol, { width: totalColWidth }]}>
+        {formatValue(grandTotal)}
+      </Text>
+    </View>
+  );
+}
+
+export interface MatrixLegendProps {
+  lessLabel?: string;
+  moreLabel?: string;
+}
+
+function MatrixLegend({ lessLabel = "Less", moreLabel = "More" }: MatrixLegendProps) {
+  const { heatBase } = useMatrix();
+  return (
+    <View style={styles.scale}>
+      <Text size="xs" color="muted">
+        {lessLabel}
+      </Text>
+      {[0.15, 0.36, 0.57, 0.78, 1].map((alpha) => (
+        <View key={alpha} style={[styles.swatch, { backgroundColor: withAlpha(heatBase, alpha) }]} />
+      ))}
+      <Text size="xs" color="muted">
+        {moreLabel}
+      </Text>
+    </View>
+  );
+}
+
+Matrix.Header = MatrixHeader;
+Matrix.Grid = MatrixGrid;
+Matrix.Totals = Object.assign(MatrixTotals, { isMatrixTotals: true as const });
+Matrix.Legend = MatrixLegend;
+
+const styles = StyleSheet.create({
+  container: {
+    gap: 3,
+  },
+  headRow: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 3,
+    paddingBottom: 2,
+  },
+  grid: {
+    gap: 3,
+  },
+  row: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 3,
+  },
+  rowLabel: {
+    paddingRight: 8,
+  },
+  cell: {
+    flex: 1,
+    minWidth: 52,
+    height: 36,
+    borderRadius: 4,
+    borderWidth: 2,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  colCell: {
+    flex: 1,
+    minWidth: 52,
+  },
+  totalCol: {
+    paddingLeft: 4,
+  },
+  totalsRow: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 3,
+    marginTop: 3,
+    paddingTop: 8,
+    borderTopWidth: 1,
+    borderTopColor: colors.border,
+  },
+  scale: {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "flex-end",
+    gap: 4,
+    paddingTop: 8,
+  },
+  swatch: {
+    width: 14,
+    height: 10,
+    borderRadius: 3,
+  },
+});

package/src/matrix_totals.ts

@@ -0,0 +1,52 @@
+/**
+ * The data layer for `Matrix` — axis types + the cross-tab aggregation. Kept
+ * free of any React-Native import so it unit-tests directly (the component in
+ * `matrix.tsx` renders these numbers; a consumer can drive a KPI off the same
+ * `matrixTotals` it shows in the grid).
+ */
+
+export interface MatrixAxisItem {
+  key: string;
+  label: string;
+}
+
+/** The inspected cell — host renders its detail (a filtered list) underneath. */
+export interface MatrixCellRef {
+  row: string;
+  col: string;
+}
+
+export interface MatrixTotalsResult {
+  rowTotals: Map<string, number>;
+  colTotals: Map<string, number>;
+  grandTotal: number;
+  /** The largest single cell — the heat scale's upper bound. */
+  max: number;
+}
+
+/**
+ * Row sums, column sums, grand total, and the max single cell — computed in one
+ * pass. The single source of truth for the matrix's totals.
+ */
+export function matrixTotals(
+  rows: MatrixAxisItem[],
+  cols: MatrixAxisItem[],
+  value: (row: string, col: string) => number,
+): MatrixTotalsResult {
+  const rowTotals = new Map<string, number>();
+  const colTotals = new Map<string, number>();
+  let max = 0;
+  let grandTotal = 0;
+  for (const r of rows) {
+    let rowSum = 0;
+    for (const c of cols) {
+      const v = value(r.key, c.key);
+      rowSum += v;
+      colTotals.set(c.key, (colTotals.get(c.key) ?? 0) + v);
+      if (v > max) max = v;
+    }
+    rowTotals.set(r.key, rowSum);
+    grandTotal += rowSum;
+  }
+  return { rowTotals, colTotals, grandTotal, max };
+}