@lotics/ui 7.0.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`.
@@ -171,7 +173,7 @@ This is the most common thing to get right. Match the JOB to the pattern:
 ### Inline edit — the preferred way to edit an existing record
 When the whole record is editable (a detail/record screen, dense settings), don't wrap it in a
 form mode or a preview↔edit card — make each VALUE inline-editable: it reads as plain text,
-hover tints it (no pencil — that shifts), click swaps the input in **at the same height** (zero
+hover reveals its border (it's a field — no grey tint, no pencil that shifts), click swaps the input in **at the same height** (zero
 reflow, the whole point), and it commits on blur (Enter saves, Escape reverts) or via
 `controls="buttons"` (✓ primary / ✕). One per type — `InlineTextInput` · `InlineNumberInput`
 (`format` for currency/units) · `InlineSelect` (plain options OR `renderOptionContent`; floats an
@@ -547,9 +549,10 @@ was only ever about the review surfaces' sparkles/severity glyphs, not functiona
   resets the native outline. Every interactive control paints its OWN ring; nothing rings unless it
   opts in. Three ways, pick by base:
   - **`FocusRingPressable`** (`@lotics/ui/focus_ring_pressable`) — a `Pressable` that rings on keyboard
-    focus; the default for a raw interactive element (cell, tile, nav button, menu option). Forwards
-    all `PressableProps` (onPress, accessibilityRole/Label/State, ref, style). Reach for this before
-    hand-rolling a Pressable + the hook.
+    focus, WITHOUT the hover wash; the base for any control whose hover affordance is its BORDER not a wash
+    (inputs/selects, the inline editors, cells, tiles, nav buttons, menu options). Forwards all
+    `PressableProps`; its state-fn `style` exposes `hovered`/`focusVisible` so the control paints its own
+    border-hover. Reach for this before hand-rolling a Pressable + the hook.
   - **`PressableHighlight`** — set the opt-in **`focusRing`** prop (or read `state.focusVisible` from
     its style-fn / children for a bespoke treatment, e.g. `CardSelectItem` which rings on hover/press/focus).
   - **`useFocusRing`** (`@lotics/ui/use_focus_ring`) — the underlying hook for inputs / custom surfaces.
@@ -562,14 +565,26 @@ was only ever about the review surfaces' sparkles/severity glyphs, not functiona
   its open state so it reads identically to a keyboard-focused control. **Coverage is a contract:** EVERY
   interactive control must ring (a focusable control with no focus treatment is a bug — the per-Pressable
   audit is the gate); a surface that shouldn't ring is a non-control → `tabIndex={-1}`, not a missing ring.
-- **A trigger's hover/focus is a contract too — build it on `PressableHighlight`, never a raw `Pressable`.**
-  Every popover/menu/select anchor (`Select`, `FilterChip`, `Switcher`, the inline editors, a custom
-  `PopoverTrigger`) rides `PressableHighlight` (or `FocusRingPressable`): it paints the hover **wash** +
-  focus ring AROUND the caller's `style`, so a borderless in-cell override (`style={{ borderColor:
-  "transparent" }}` on a `Select`) keeps the wash and reads like its inline neighbours. A raw `Pressable`
-  that hand-rolls its own hover is the bug — a caller's `borderColor` then erases the affordance. Layer the
-  hover-border BEFORE `style` (a transparent edge suppresses it → wash only) and the open ring (`FOCUS_RING`)
-  on the open state.
+- **Hover intensifies a control's OWN resting signature — never a foreign affordance. Pick the base by WHAT THE SURFACE IS; never a raw `Pressable`.** The one rule behind every interactive control:
+  - **Fields** (type into / pick from) — `TextInputField`, `Picker`, `Select`, `Combobox`'s input,
+    `NumberInput`, `DateField`/`TimePicker`, `DateRangeFilterField`, the inline editors
+    (`InlineSelect`/`InlineDatePicker` via `InlineEditView`) — signature is a BORDER → hover DARKENS it to
+    `HOVER_BORDER` (a borderless in-cell field REVEALS one). Build on **`FocusRingPressable`** (ring + a11y
+    + a `state.hovered`/`focusVisible` style-fn, NO wash); layer the hover-border AFTER `style` so it wins
+    over the caller's resting edge; put the open ring (`FOCUS_RING`) on the open state. **A field NEVER
+    greys its content.**
+  - **Actions** — `Button`, `IconButton` — signature is a FILL → hover DARKENS the fill (own colour logic).
+    Never a border, never a wash.
+  - **Pills / toggles** — `Chip`/`ChipGroup`/`FilterChip` (via `chipSurfaceStyle`), `SegmentedControl`,
+    `Tabs`, `Switcher`, `RadioPicker` — signature is a pill SURFACE → hover WASHES it (white→zinc-100);
+    selected adds a ring/fill.
+  - **Surfaces** — `PressableRow`, `MenuButton`, list/menu items, `CardSelectItem`, `Card`, `Accordion` —
+    signature is a row/card SURFACE → hover WASHES it. Build on **`PressableHighlight`** — the grey wash IS
+    the affordance (its whole job; it's in the name).
+  - The bug this prevents: a FIELD built on `PressableHighlight` inherits the wash AND its own border →
+    it greys *and* animates its edge while its siblings only border-hover (`Select`/`DateRangeFilterField`/
+    the inline editors did exactly this pre-7.x). Reach for `PressableHighlight` on a bordered/input control
+    and you've made it.
 - **Cards are banded — and composable** (all from `@lotics/ui/card`):
   ```tsx
   <Card style={{ padding: 0 }}>
@@ -700,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) ·
@@ -785,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.0.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/date_range_filter_field.tsx

@@ -5,7 +5,7 @@ import { colors } from "./colors";
 import { CONTROL_RADIUS, HOVER_BORDER, CONTROL_TRANSITION } from "./control_surface";
 import { Icon } from "./icon";
 import { Button } from "./button";
-import { PressableHighlight } from "./pressable_highlight";
+import { FocusRingPressable } from "./focus_ring_pressable";
 import { Popover, PopoverTrigger, PopoverContent, PopoverFooter } from "./popover";
 import { DateFilter, DateFilterValue, DateFilterLabels } from "./date_filter";
 import { formatDate } from "./format_date";
@@ -120,8 +120,7 @@ export function DateRangeFilterField(props: DateRangeFilterFieldProps) {
   return (
     <Popover open={open} onOpenChange={setOpen} side="bottom" align="start">
       <PopoverTrigger>
-        <PressableHighlight
-          focusRing
+        <FocusRingPressable
           testID={testID}
           accessibilityRole="button"
           accessibilityLabel={labels.selectDateRange}
@@ -143,7 +142,7 @@ export function DateRangeFilterField(props: DateRangeFilterFieldProps) {
             {display}
           </Text>
           <Icon name="chevron-down" size={14} color={colors.zinc[400]} />
-        </PressableHighlight>
+        </FocusRingPressable>
       </PopoverTrigger>
       <PopoverContent disableBodyScroll>
         <DateFilter

package/src/focus_ring_pressable.tsx

@@ -2,20 +2,37 @@ import { Pressable, type PressableProps, type StyleProp, type View, type ViewSty
 import { type Ref } from "react";
 import { FOCUS_RING } from "./control_surface";
 import { useFocusRing, composeHandler } from "./use_focus_ring";
+import { type PressableHighlightState } from "./pressable_highlight";
 
-export interface FocusRingPressableProps extends PressableProps {
+export interface FocusRingPressableProps extends Omit<PressableProps, "style"> {
   ref?: Ref<View>;
+  /**
+   * Narrows the state-function `style` to `PressableHighlightState`, so a control can
+   * read the web-only `hovered` (to paint its OWN border-hover) and `focusVisible`,
+   * exactly like `PressableHighlight` — the wash-free base still hands controls the
+   * flags they need to drive their edge.
+   */
+  style?: StyleProp<ViewStyle> | ((state: PressableHighlightState) => StyleProp<ViewStyle>);
+  /**
+   * `"none"` on a value/text surface (an inline-edit box) — a pressable is a button,
+   * not a selection surface, so a drag-click edits instead of starting a text
+   * selection. Exposed because RN types only carry `userSelect` on `TextStyle` while
+   * react-native-web applies it to any element.
+   */
+  userSelect?: "auto" | "none";
 }
 
 /**
  * A `Pressable` that paints the kit `FOCUS_RING` on keyboard focus — the raw-control
  * counterpart to `PressableHighlight`'s `focusRing` prop, for interactive elements
- * that DON'T want the hover wash (cells, tiles, nav buttons, menu options). Forwards
- * every `PressableProps` (onPress, accessibilityRole/Label/State, ref, …) and merges
- * the ring with the caller's `style` (object or state-function) + onFocus/onBlur.
- * Reach for this before hand-rolling a one-off Pressable + `useFocusRing`.
+ * that DON'T want the hover wash (the inputs/selects, cells, tiles, nav buttons, menu
+ * options). Forwards every `PressableProps` (onPress, accessibilityRole/Label/State,
+ * ref, …); its state-function `style` exposes `hovered`/`focusVisible` so a control
+ * paints its own border-hover, and it merges the focus ring + onFocus/onBlur. Reach
+ * for this for ANY interactive control whose hover affordance is its border (never a
+ * wash) — `PressableHighlight` is only for rows/menus/cards.
  */
-export function FocusRingPressable({ ref, style, onFocus, onBlur, ...rest }: FocusRingPressableProps) {
+export function FocusRingPressable({ ref, style, onFocus, onBlur, userSelect, ...rest }: FocusRingPressableProps) {
   const { focusVisible, focusProps } = useFocusRing();
   return (
     <Pressable
@@ -25,7 +42,8 @@ export function FocusRingPressable({ ref, style, onFocus, onBlur, ...rest }: Foc
       onBlur={composeHandler(onBlur ?? undefined, focusProps.onBlur)}
       style={(state) =>
         [
-          typeof style === "function" ? style(state) : style,
+          userSelect ? ({ userSelect } as ViewStyle) : null,
+          typeof style === "function" ? style({ ...state, focusVisible }) : style,
           focusVisible ? { boxShadow: FOCUS_RING } : null,
         ] as StyleProp<ViewStyle>
       }

package/src/inline_edit.tsx

@@ -3,9 +3,9 @@ import { View, StyleSheet, type GestureResponderEvent } from "react-native";
 import { Text } from "./text";
 import { IconButton } from "./icon_button";
 import { ActivityIndicator } from "./activity_indicator";
-import { PressableHighlight } from "./pressable_highlight";
+import { FocusRingPressable } from "./focus_ring_pressable";
 import { colors } from "./colors";
-import { FOCUS_RING, CONTROL_RADIUS } from "./control_surface";
+import { FOCUS_RING, CONTROL_RADIUS, HOVER_BORDER, CONTROL_TRANSITION } from "./control_surface";
 import { fontFamilyRegular, getInputTextStyle } from "./text_utils";
 
 /** The kit's standard control height (TextInputField, NumberInput, Picker, …).
@@ -124,7 +124,8 @@ interface InlineEditViewProps {
 
 /**
  * The view-mode box of an inline-editable field: the value as plain text in a
- * `PressableHighlight` (hover tints it; the pointer cursor signals it's
+ * `FocusRingPressable` (an input, so it hovers via its BORDER — the transparent
+ * edge reveals on hover, never a grey wash; the pointer cursor signals it's
  * editable), at the kit's control height with a transparent border — so
  * swapping to an input, or floating a dropdown above it, never shifts the
  * layout. Used by `InlineEditFrame`, and as the overlay trigger for the
@@ -141,15 +142,17 @@ export function InlineEditView(props: InlineEditViewProps) {
       }
     : undefined;
   return (
-    <PressableHighlight
-      focusRing
+    <FocusRingPressable
       ref={ref}
       disabled={disabled}
       onPress={handlePress}
       accessibilityRole="button"
       accessibilityLabel={accessibilityLabel}
       userSelect="none"
-      style={[styles.view, active && styles.viewActive]}
+      // An inline-edit field is an input — it hovers via its BORDER, not a grey
+      // wash: the transparent edge reveals on hover (the kit's hover-border),
+      // then fills + rings when open. Suppressed while open (the ring leads).
+      style={(state) => [styles.view, CONTROL_TRANSITION, active && styles.viewActive, !active && state.hovered && !disabled && styles.viewHovered]}
     >
       {typeof display === "string" ? (
         <Text numberOfLines={1} style={[viewTextStyle, display ? null : styles.placeholder, struck ? styles.struck : null]}>
@@ -159,7 +162,7 @@ export function InlineEditView(props: InlineEditViewProps) {
         <View style={styles.viewNode}>{display}</View>
       )}
       {trailing != null ? trailing : null}
-    </PressableHighlight>
+    </FocusRingPressable>
   );
 }
 
@@ -250,6 +253,11 @@ const styles = StyleSheet.create({
     borderColor: colors.border,
     boxShadow: FOCUS_RING,
   },
+  // Hover (not open): reveal the kit hover-border on the transparent edge — the
+  // input-family affordance, no grey wash.
+  viewHovered: {
+    borderColor: HOVER_BORDER,
+  },
   placeholder: { color: colors.zinc[400] },
   struck: { textDecorationLine: "line-through", color: colors.zinc[500] },
   viewNode: { flex: 1, minWidth: 0 },

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 };
+}

package/src/select.tsx

@@ -2,7 +2,7 @@ import { StyleSheet, View, type GestureResponderEvent, type StyleProp, type View
 import { useState, useCallback, useMemo, type ReactNode, type Ref } from "react";
 import { colors } from "./colors";
 import { FOCUS_RING, CONTROL_RADIUS, HOVER_BORDER, CONTROL_TRANSITION } from "./control_surface";
-import { PressableHighlight } from "./pressable_highlight";
+import { FocusRingPressable } from "./focus_ring_pressable";
 import { Text } from "./text";
 import { Popover, PopoverTrigger, PopoverContent } from "./popover";
 import { OptionList } from "./option_list";
@@ -217,13 +217,13 @@ function SelectTrigger<T extends string>({
   const hasSelection = selectedItems.length > 0;
 
   return (
-    // PressableHighlight owns the hover wash + keyboard focus ring (layered AROUND
-    // the caller's `style`, so a borderless override — `borderColor:"transparent"`
-    // for an in-cell Select — keeps the wash and reads like its inline neighbours).
-    // The hover-border sits BEFORE `style` so a transparent border suppresses it
-    // (wash only), while a bordered Select darkens its edge.
-    <PressableHighlight
-      focusRing
+    // The wash-free control base (FOCUS_RING + a11y, NO grey wash) — a Select is an
+    // input, so its hover affordance is its BORDER, never a content wash. The
+    // hover-border sits AFTER `style` so it wins over the caller's resting border:
+    // a bordered Select darkens its edge, and a borderless in-cell Select
+    // (`borderColor:"transparent"`) REVEALS one — both reading as "interactive",
+    // neither greying its content.
+    <FocusRingPressable
       ref={ref}
       testID={testID}
       // Without a role this Pressable renders as an unfocusable <div> on web — the
@@ -233,7 +233,7 @@ function SelectTrigger<T extends string>({
       accessibilityRole="button"
       accessibilityLabel={accessibilityLabel}
       accessibilityState={{ expanded: open, disabled }}
-      style={(state) => [styles.pressable, CONTROL_TRANSITION, open && styles.opened, disabled && styles.disabled, state.hovered && !disabled && { borderColor: HOVER_BORDER }, style]}
+      style={(state) => [styles.pressable, CONTROL_TRANSITION, open && styles.opened, disabled && styles.disabled, style, state.hovered && !disabled && { borderColor: HOVER_BORDER }]}
       onPress={!disabled ? onPress : undefined}
       disabled={disabled}
     >
@@ -267,7 +267,7 @@ function SelectTrigger<T extends string>({
           {placeholder}
         </Text>
       )}
-    </PressableHighlight>
+    </FocusRingPressable>
   );
 }