@lotics/ui 11.5.0 → 11.7.0

package/AGENTS.md

@@ -39,6 +39,9 @@ doc before building any screen, **never from memory**. Exact props are the shipp
 - **Pure primitives only** — no i18n, analytics, or domain types in `src/` (pass `labels`,
   callbacks); Lotics-coupled UI belongs in `@lotics/ui-internal`.
 - **Every state designed** — skeleton (mirroring layout), empty, error; no layout shift.
+- **Copy states content, not mechanics** — a `description` names the section's content or one
+  domain rule; widget behavior ("edits in place, saves on its own") and selling points never
+  appear. Instructions live in empty states / form-field hints. → [composition.md §Microcopy](./docs/composition.md).
 
 ## Keeping this reference current
 

package/docs/catalog.md

@@ -121,7 +121,11 @@ Two columnar shapes, and the choice is about data size:
   headers via `SortHeader`; paired with `Pagination`) + read-only rows that open a `Drawer`
   to edit. It scales by PAGING — renders one page, never the whole set — so you FILTER +
   search, you don't group. Worked example: [`tpl_item_list`](../examples/tpl_item_list.tsx).
-  Never an HTML `<table>` or a `.map` of rows.
+  Never an HTML `<table>` or a `.map` of rows. The register adapts to its container on its
+  own — hides columns by `priority`, stacks rows below the two-column floor (see the `table`
+  inventory entry) — so a narrow screen or panel needs NO branching; compose a hand-designed
+  card pile (`PressableRow` + your own hierarchy) over `useScreenSize` only when a screen
+  deserves a better mobile shape than the automatic stack.
 - **Inline-managed grouped table** (MODERATE — hundreds, low-thousands — you MANAGE in view)
   — the `DataGrid` primitive: a grouped, sortable grid whose cells are LIVE inline editors
   (ANY field — a column is `{ key, label, width?, sortable?, cell: (item) => ReactNode }`,
@@ -331,7 +335,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   (12, fixed), no body component. `SectionHeadingTitle` is ALWAYS `##` (xl semibold;
   `weight="medium"` opt-down only) + `info` for an ⓘ provenance popover after the title,
   same as `CardHeaderTitle.info`. `SubsectionHeadingTitle` is the `###` lg-semibold level-3
-  title of a named group inside a section — heading-row siblings ride its right edge; the
+  title of a named group inside a section (same `info` ⓘ affordance as the section title) —
+  heading-row siblings ride its right edge; the
   heading ramp is FIXED: `#` xxl / `##` xl / `###` lg, no size props.
 - **`section`** — a SECOND, standalone `Section`: a self-contained titled block
   (`title`/`description`/`collapsible`/`icon`/`titleRight`, imperative
@@ -547,7 +552,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   label+value row for drawer/peek detail; in FORM mode (`labelWidth` set) the value column
   FILLS the row so a stack of inline editors all span the same width + none jumps wider on
   edit; optional `trailing` slot renders a right-side action/badge after the value (units
-  belong IN the value via `InlineNumberInput format`). `DetailTable`: the compound parent of
+  belong IN the value via `InlineNumberInput format`); optional `info` renders an ⓘ popover
+  hugging the label — the row-label member of the one `info` vocabulary (`CardHeaderTitle` /
+  `SectionHeadingTitle` / `SubsectionHeadingTitle`); pass `undefined` to hide it (callers may
+  gate it on their own state). `DetailTable`: the compound parent of
   a row STACK — `labelWidth` (default 130) / `trailingWidth` / `minHeight` (default 40, the
   inline-control grid) declared ONCE + the 6px row gap; with `trailingWidth` every row
   reserves the trailing column so value cells share one width and trailing items align at
@@ -582,6 +590,18 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`list_item`** — `ListItem`: the plain list row.
 - **`table`** — `Table` + `TableRow` + `TableCell`: the paginated high-volume register
   (columns defined once, `sortLabels` localizable; rows are `PressableRow`-based).
+  CONTAINER-RESPONSIVE with no prop (measures itself, like `Breakdown`/`DetailTable`): when
+  the width can't fit every column it hides columns by `TableColumn.priority` (higher drops
+  first; default = column order, rightmost first; column 0 — the identity — never drops), and
+  below the two-column floor every row STACKS: each cell renders as a `DetailRow`-spread
+  line (muted label left, value at the right edge — one vocabulary with the drawer's detail
+  rows), the lines sitting on the identity column's text edge, never under the checkbox;
+  the header band gives way, so sorting is a wide-container affordance. Rows carry TWO right-side slots: `action`
+  (the primary CTA `Button` — register: in the trailing gutter; stacked: closes the content,
+  right-aligned) and `trailing` (the ⋯ overflow — stays beside the identity on the top line).
+  On pressable rows dropped values stay one tap away — the row opens the record; a READ-ONLY
+  register (rows without `onPress`) has no door, so give the columns it can't afford to lose
+  a low `priority` (e.g. `priority: 1` — outlives its right-side neighbours).
 - **`sort_header`** — `SortHeader` + `SortState`/`SortDir` + `cycleSort` + `sortBy` +
   `SortHeaderLabels`: the sortable column header and the sort-state helpers `Table`/
   `DataGrid` consumers drive.

package/docs/composition.md

@@ -60,7 +60,8 @@ restyle a heading level per-page.
   `Section` with a `title` string prop — a different component. Import from `section_heading` for
   the grammar described here.
 - **Subsection title** — the level BELOW a section on a long record surface: `Subsection` ›
-  `SubsectionHeading` › `SubsectionHeadingTitle` (`###` — lg semibold; siblings — a `Badge`, a
+  `SubsectionHeading` › `SubsectionHeadingTitle` (`###` — lg semibold, with the same `info` ⓘ
+  affordance as `SectionHeadingTitle`; siblings — a `Badge`, a
   `SectionHeadingMeta`, an action — ride the heading row's right edge). Sibling subsections stack
   in a **`SubsectionStack`** (the same hairline law one step tighter: a fixed 24px beat + hairline
   between groups — no margins, no hand-rolled dividers); a headingless `Subsection` is the
@@ -437,3 +438,75 @@ disabled ink).
 Anything pressable is ≥ 40px tall (8px minimum gap between pressables). 16px between cards, 24–28
 canvas padding, 16–20 inside bands, 10–12 between content lines. Density comes from alignment +
 hierarchy, not cramming.
+
+## Microcopy — content, not mechanics
+
+UI copy states WHAT something is — domain content or one real rule — never how the widget
+behaves, and never a selling point. The control demonstrates its own behavior; copy that
+narrates it ("edits in place, saves on its own", "sửa tại chỗ, lưu ngay") is noise, and copy
+that praises it is marketing.
+
+- **Heading `description`s** name the section's content ("Các bên và điều khoản thương mại
+  của lô.") or one domain invariant ("Each invoice owns its charge lines — a charge never
+  lives apart from the document it bills on."). Never widget mechanics, never usage narration
+  ("drop to add, click to preview"), never feature-brag adjectives.
+- **Instructions live where action is needed** — empty states, callouts, form-field
+  descriptions: imperative, one concrete step ("Drop the CI + PL here."). A heading never
+  instructs.
+- **Restatement is the second noise mode.** A description that repeats what the screen already
+  shows — the title, the subsection names below it, the table's columns — carries zero
+  information and fails even though it "states content". Useful copy states an **invisible
+  truth**: an invariant of the data, a boundary ("P&L lives in the accounting app, not here"),
+  a linkage ("the HS code here feeds the customs declaration"), or a consequence ("past the
+  cut-off, the box misses the sailing").
+- **The deletion test**: if removing the line changes nothing for the reader, remove the line —
+  `description` is optional for a reason; when no invisible truth is worth stating, omit it.
+- **Plain language over jargon; effect over mechanism** ("Record visibility", not "Row-Level
+  Privacy") — if a term needs explaining, replace it. **One concept = one word everywhere** —
+  pick the term once and reuse it on every surface.
+- **Native language**: match the workspace language with native vocabulary — a Vietnamese ops
+  app reads like a Vietnamese ops tool, not a translated brochure. Sentence case; no
+  exclamation marks.
+
+### Error messages — what happened → what it means → what to do
+
+The consensus anatomy (GOV.UK · NN/g · Microsoft): state what happened, what it means for the
+user's data, and the one next step. Field errors go INLINE (`FormField error=`); a page-level
+failure is a `Callout tone="error"` (title = what happened, text = what to do, an action when
+one exists).
+
+- Never blame ("invalid", "you forgot"), never bare "An error occurred", never an error code
+  as the headline (put codes at the end, for support). No ALL-CAPS, no exclamation.
+- Say whether the user's input survived — and PRESERVE it (re-entering data is the real cost).
+- Empty required field → instruct ("Enter the hours you work a week"); constraint violation →
+  describe the constraint ("First name must be 35 characters or less").
+- Apology is reserved for genuine system failure — never for validation.
+- BAD: `Error: invalid input (0x643).` · GOOD: `Không tải được chứng từ lên — tệp vẫn còn trên
+  máy bạn. Thử lại; nếu vẫn lỗi, kiểm tra kết nối mạng.`
+
+### Empty states — confirm, orient, one action
+
+An empty region has three jobs (NN/g): confirm this is EMPTY (not loading, not broken), say
+what belongs here, and offer ONE next action — the `EmptyState` props are this anatomy
+(`message` = what's empty, `hint` = what to do about it, `action` = the one CTA). The three
+empties get DIFFERENT copy:
+
+- **First use** → teach + invite: message names what will live here, `action` creates the first
+  one ("Chưa có khoản phí" + "Thêm khoản thu/chi cho lô" + a Thêm phí button).
+- **User cleared it** → stay quiet: the user knows why it's empty; confirmation only, no tutorial.
+- **No search/filter results** → help recover: restate the scope ("Không có lô nào khớp
+  'ABC'"), hint the fix ("Thử từ khóa khác / xóa bộ lọc"). Never a blank panel or bare "No data".
+
+### Buttons & action labels — the outcome, verb-first
+
+A label names the OUTCOME of pressing — verb + object, 2–4 words (GOV.UK: "Save and continue",
+"Add another address"). Universal across every source; only casing forks by platform (this kit:
+sentence case, always).
+
+- Never "OK" / "Yes" / "Submit" / "Click here" — a `Button title` says what happens ("Tạo lô
+  hàng", "Xóa 3 tệp").
+- A dialog's confirm button RESTATES the action: "Xóa lô?" → `Xóa` / `Hủy` — never `OK` / `Hủy`
+  (the pair must answer the question without reading the body).
+- Destructive buttons name the object (`color="danger"` + "Xóa lô", not "Xóa") — the label is
+  the last safeguard.
+

package/examples/tpl_item_list.tsx

@@ -390,12 +390,8 @@ function HoSoRow({ hs, daThu, tasks, onTasksChange, suggestions, onDismissSugges
       minHeight={56}
       accessibilityLabel={`Open record ${hs.ma} — ${hs.khach}`}
       leading={<CheckboxInput accessibilityLabel={selectable ? `Select ${hs.ma}` : `${hs.ma} — awaiting docs, not ready to export`} checked={marked} disabled={!selectable} onChange={onToggle} />}
-      trailing={
-        <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
-          <Button title="Print" icon={docFor(hs, daThu).icon} color="secondary" onPress={() => {}} />
-          <ActionMenu items={menuFor(hs, daThu)} accessibilityLabel={`Actions for ${hs.ma}`} />
-        </View>
-      }
+      action={<Button title="Print" icon={docFor(hs, daThu).icon} color="secondary" onPress={() => {}} />}
+      trailing={<ActionMenu items={menuFor(hs, daThu)} accessibilityLabel={`Actions for ${hs.ma}`} />}
     >
       <TableCell>
         <Text size="sm" weight="semibold" tabular>{hs.ma}</Text>

package/examples/tpl_record.tsx

@@ -707,7 +707,7 @@ export function TplRecord() {
         <View onLayout={nav.register("details")}>
         <Section>
           <SectionHeading>
-            <SectionHeadingTitle description="Every value edits in place — click a chip, change it, it saves on its own.">Details</SectionHeadingTitle>
+            <SectionHeadingTitle description="The order's core facts — reference, dates, and the amounts every desk reads first.">Details</SectionHeadingTitle>
             <OwnerTag stage="sales" />
           </SectionHeading>
           <DetailTable labelWidth={150} trailingWidth={88}>
@@ -757,7 +757,7 @@ export function TplRecord() {
         <View onLayout={nav.register("customer")}>
         <Section>
           <SectionHeading>
-            <SectionHeadingTitle description="The bill-to. Its tax ID gates invoicing below — add it here.">Customer</SectionHeadingTitle>
+            <SectionHeadingTitle description="The bill-to party — its tax ID gates invoicing below.">Customer</SectionHeadingTitle>
             <OwnerTag stage="sales" />
             {customer && !editingCustomer ? (
               <Button title="Edit" color="secondary" icon="pencil" onPress={() => setEditingCustomer(true)} />
@@ -964,7 +964,7 @@ export function TplRecord() {
         <View onLayout={nav.register("files")}>
         <Section>
           <SectionHeading>
-            <SectionHeadingTitle description="The signed quote, the PO, photos — drop to add, click to preview.">Files</SectionHeadingTitle>
+            <SectionHeadingTitle description="The signed quote, the PO, photos — everything filed on the order.">Files</SectionHeadingTitle>
             <OwnerTag stage="operations" />
             {files.length > 0 ? <SectionHeadingMeta>{`${files.length} ${files.length === 1 ? "file" : "files"}`}</SectionHeadingMeta> : null}
           </SectionHeading>
@@ -1194,7 +1194,7 @@ export function TplRecord() {
         <View onLayout={nav.register("preferences")}>
         <Section>
           <SectionHeading>
-            <SectionHeadingTitle description="Applied as you change them — no Save.">Preferences</SectionHeadingTitle>
+            <SectionHeadingTitle description="Per-order handling and notification preferences.">Preferences</SectionHeadingTitle>
           </SectionHeading>
           <View style={{ flexDirection: "row", alignItems: "center", gap: 12, minHeight: 40 }}>
             <View style={{ flex: 1, gap: 1 }}>

package/package.json

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

package/src/detail_row.tsx

@@ -1,6 +1,8 @@
 import { createContext, ReactNode, useContext, useState } from "react";
 import { StyleProp, StyleSheet, View, ViewStyle } from "react-native";
 import { INLINE_CONTROL_HEIGHT } from "./inline_edit";
+import { InfoPopover } from "./info_popover";
+import { useLoticsLocale } from "./locale";
 import { Text } from "./text";
 
 interface DetailTableColumns {
@@ -103,6 +105,11 @@ export interface DetailRowProps {
   labelSize?: "xs" | "sm";
   /** Min row height. Default 28 (or the `DetailTable`'s `minHeight`). */
   minHeight?: number;
+  /** An ⓘ popover hugging the label — a short "what this field means" gloss,
+   *  the row-label member of the one `info` vocabulary
+   *  (`CardHeaderTitle` / `SectionHeadingTitle` / `SubsectionHeadingTitle`).
+   *  Pass `undefined` to hide the ⓘ (a caller can gate it on its own state). */
+  info?: string;
 }
 
 /**
@@ -116,10 +123,21 @@ export interface DetailRowProps {
  */
 export function DetailRow(props: DetailRowProps) {
   const table = useContext(DetailTableContext);
-  const { label, children, trailing, labelSize = "sm" } = props;
+  const { label, children, trailing, labelSize = "sm", info } = props;
   const labelWidth = props.labelWidth ?? table?.labelWidth;
   const minHeight = props.minHeight ?? table?.minHeight ?? 28;
   const form = labelWidth != null;
+  const words = useLoticsLocale();
+  // The ⓘ hugs the label text (flexShrink keeps long labels from pushing it
+  // out of the cell) — the label cell keeps its exact width either way.
+  const infoLabel = (cellStyle: StyleProp<ViewStyle>) => (
+    <View style={[styles.labelWithInfo, cellStyle]}>
+      <Text size={labelSize} color="muted" numberOfLines={1} style={styles.labelShrink}>
+        {label}
+      </Text>
+      <InfoPopover text={info ?? ""} accessibilityLabel={words.sectionHeading.info} />
+    </View>
+  );
   if (table?.stacked) {
     // Stacked mode wears the FORM grammar: the label renders exactly like a
     // `FormField` label (medium, default ink), so a narrow record surface
@@ -128,9 +146,18 @@ export function DetailRow(props: DetailRowProps) {
     // inline editor self-persists — only the look converges.
     return (
       <View style={styles.stackedRow}>
-        <Text weight="medium" numberOfLines={1}>
-          {label}
-        </Text>
+        {info != null ? (
+          <View style={styles.labelWithInfo}>
+            <Text weight="medium" numberOfLines={1} style={styles.labelShrink}>
+              {label}
+            </Text>
+            <InfoPopover text={info} accessibilityLabel={words.sectionHeading.info} />
+          </View>
+        ) : (
+          <Text weight="medium" numberOfLines={1}>
+            {label}
+          </Text>
+        )}
         <View style={[styles.stackedValueRow, { minHeight }]}>
           <View style={styles.value}>{children}</View>
           {trailing != null ? trailing : null}
@@ -140,9 +167,13 @@ export function DetailRow(props: DetailRowProps) {
   }
   return (
     <View style={[styles.row, { minHeight }]}>
-      <Text size={labelSize} color="muted" style={form ? { width: labelWidth } : styles.flexLabel}>
-        {label}
-      </Text>
+      {info != null ? (
+        infoLabel(form ? { width: labelWidth } : styles.flexLabel)
+      ) : (
+        <Text size={labelSize} color="muted" style={form ? { width: labelWidth } : styles.flexLabel}>
+          {label}
+        </Text>
+      )}
       {form ? <View style={styles.value}>{children}</View> : children}
       {table?.trailingWidth != null ? (
         <View style={[styles.trailingCell, { width: table.trailingWidth }]}>{trailing}</View>
@@ -171,6 +202,8 @@ const styles = StyleSheet.create({
     gap: 12,
   },
   flexLabel: { flex: 1 },
+  labelWithInfo: { flexDirection: "row", alignItems: "center", gap: 4 },
+  labelShrink: { flexShrink: 1 },
   // Form mode (labelWidth set): the value column FILLS the row so every inline
   // editor spans the SAME width — and none jumps wider when it swaps to the
   // (flex:1) edit control. A stretch column, so an InlineEditView / InlineStatic

package/src/section_heading.tsx

@@ -88,18 +88,23 @@ export interface SubsectionHeadingTitleProps {
   children: React.ReactNode;
   /** Heading rank. Defaults to 3 — one level under `SectionHeadingTitle`'s 2. */
   level?: HeadingLevel;
+  /** An ⓘ popover after the title — a short "what this is / where it came from"
+   * gloss, mirroring `SectionHeadingTitle`'s `info`. */
+  info?: string;
 }
 
 /** The subsection title — ALWAYS `###` (lg semibold), the fixed step under the
  * xl section title and above the md/sm body. Grows to push siblings (a
  * `SectionHeadingMeta`, a `Badge`, an action) to the right edge. */
 export function SubsectionHeadingTitle(props: SubsectionHeadingTitleProps) {
-  const { children, level = 3 } = props;
+  const { children, level = 3, info } = props;
+  const words = useLoticsLocale();
   return (
-    <View style={{ flex: 1 }}>
+    <View style={{ flex: 1, flexDirection: "row", alignItems: "center", gap: 6 }}>
       <Text level={level} size="lg" weight="semibold">
         {children}
       </Text>
+      {info ? <InfoPopover text={info} accessibilityLabel={words.sectionHeading.info} /> : null}
     </View>
   );
 }
@@ -139,6 +144,9 @@ export interface SectionHeadingTitleProps {
  * push any sibling actions to the right edge. */
 export function SectionHeadingTitle(props: SectionHeadingTitleProps) {
   const { children, description, icon, level = 2, weight = "semibold", info } = props;
+  // Hoisted — a hook inside the `info ?` ternary breaks hook ordering the
+  // render `info` appears or disappears.
+  const words = useLoticsLocale();
   return (
     <View style={{ flex: 1, gap: 2 }}>
       <View style={{ flexDirection: "row", alignItems: "center", gap: 6 }}>
@@ -146,7 +154,7 @@ export function SectionHeadingTitle(props: SectionHeadingTitleProps) {
         <Text level={level} weight={weight} size="xl">
           {children}
         </Text>
-        {info ? <InfoPopover text={info} accessibilityLabel={useLoticsLocale().sectionHeading.info} /> : null}
+        {info ? <InfoPopover text={info} accessibilityLabel={words.sectionHeading.info} /> : null}
       </View>
       {description ? (
         <Text color="zinc-500" size="sm">

package/src/table.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+import { computeTableFit, type TableFitColumn } from "./table_fit";
+
+// The canonical register's columns (tpl_item_list): a fixed identity column,
+// a flexible name column, then fixed data columns — plus a 24px leading
+// checkbox gutter and a 132px trailing actions gutter.
+const REGISTER: TableFitColumn[] = [
+  { key: "ma", width: 112 },
+  { key: "khach" }, // flex
+  { key: "trangThai", width: 112 },
+  { key: "viec", width: 82 },
+  { key: "phi", width: 116 },
+  { key: "ngayNhan", width: 72 },
+];
+
+function visible(fit: ReturnType<typeof computeTableFit>): string[] {
+  return REGISTER.filter((c) => fit.visibleKeys.has(c.key)).map((c) => c.key);
+}
+
+describe("computeTableFit", () => {
+  it("keeps every column when the container fits them all", () => {
+    const fit = computeTableFit(REGISTER, 24, 132, 1040);
+    expect(fit.stacked).toBe(false);
+    expect(visible(fit)).toEqual(["ma", "khach", "trangThai", "viec", "phi", "ngayNhan"]);
+  });
+
+  it("drops columns right-to-left by default, one at a time, until the rest fit", () => {
+    // 700px: the full set (908px) and the set minus "ngayNhan" (822px) overflow;
+    // minus "phi" too (692px) fits.
+    const fit = computeTableFit(REGISTER, 24, 132, 700);
+    expect(fit.stacked).toBe(false);
+    expect(visible(fit)).toEqual(["ma", "khach", "trangThai", "viec"]);
+  });
+
+  it("keeps a high-priority column alive while lower-priority ones drop", () => {
+    const withPriority = REGISTER.map((c) => (c.key === "phi" ? { ...c, priority: 1 } : c));
+    const fit = computeTableFit(withPriority, 24, 132, 700);
+    expect(fit.stacked).toBe(false);
+    // "phi" (priority 1) outlives "trangThai"/"viec"/"ngayNhan" (default = index).
+    expect(fit.visibleKeys.has("phi")).toBe(true);
+    expect(fit.visibleKeys.has("trangThai")).toBe(false);
+    expect(fit.visibleKeys.has("viec")).toBe(false);
+    expect(fit.visibleKeys.has("ngayNhan")).toBe(false);
+  });
+
+  it("never drops the first column", () => {
+    // Wide enough for exactly the identity + flex pair, no more.
+    const fit = computeTableFit(REGISTER, 0, 0, 320);
+    expect(fit.stacked).toBe(false);
+    expect(fit.visibleKeys.has("ma")).toBe(true);
+  });
+
+  it("never drops the first column even when it carries the worst priority", () => {
+    const hostile = REGISTER.map((c) => (c.key === "ma" ? { ...c, priority: 99 } : c));
+    const fit = computeTableFit(hostile, 24, 132, 700);
+    expect(fit.stacked).toBe(false);
+    expect(fit.visibleKeys.has("ma")).toBe(true);
+  });
+
+  it("stacks when even the minimum column set overflows (the phone case)", () => {
+    // A 390px phone minus the page padding: the canonical register's identity +
+    // customer + gutters still need ~470px.
+    const fit = computeTableFit(REGISTER, 24, 132, 334);
+    expect(fit.stacked).toBe(true);
+    // Stacked mode shows every column — vertical space is free.
+    expect(visible(fit)).toEqual(["ma", "khach", "trangThai", "viec", "phi", "ngayNhan"]);
+  });
+
+  it("counts the leading/trailing gutters and gaps in the fit math", () => {
+    // Two fixed columns: 40 padding + 100 + 100 + 1 gap (14) = 254 exactly.
+    const two: TableFitColumn[] = [
+      { key: "a", width: 100 },
+      { key: "b", width: 100 },
+    ];
+    expect(computeTableFit(two, 0, 0, 254).stacked).toBe(false);
+    expect(computeTableFit(two, 0, 0, 253).stacked).toBe(true);
+    // Adding a 24px leading gutter adds the gutter and one more gap.
+    expect(computeTableFit(two, 24, 0, 292).stacked).toBe(false);
+    expect(computeTableFit(two, 24, 0, 291).stacked).toBe(true);
+  });
+
+  it("a single-column table fits until the gutters overflow, then stacks", () => {
+    const one: TableFitColumn[] = [{ key: "a" }];
+    // 40 padding + 120 flex minimum = 160.
+    expect(computeTableFit(one, 0, 0, 200).stacked).toBe(false);
+    const tiny = computeTableFit(one, 0, 0, 100);
+    expect(tiny.stacked).toBe(true);
+    expect(tiny.visibleKeys.has("a")).toBe(true);
+  });
+});

package/src/table.tsx

@@ -1,6 +1,7 @@
 import {
   createContext,
   useContext,
+  useState,
   Children,
   cloneElement,
   isValidElement,
@@ -12,24 +13,26 @@ import { Text } from "./text";
 import { colors } from "./colors";
 import { PressableRow } from "./pressable_row";
 import { Divider } from "./divider";
+import { DetailRow } from "./detail_row";
 import { SortHeader, type SortState, type SortHeaderLabels } from "./sort_header";
 import { FOCUS_RING } from "./control_surface";
 import { useFocusRing } from "./use_focus_ring";
+import { COLUMN_GAP, ROW_GUTTER, computeTableFit, type TableFit, type TableFitColumn } from "./table_fit";
 
 /**
  * One column of a register — its width/flex/align/label/sortability defined ONCE,
- * here, instead of being re-typed in the header band AND every row.
+ * here, instead of being re-typed in the header band AND every row. The fit
+ * fields (`key`/`width`/`priority`) live on `TableFitColumn` — the pure fit
+ * layer in `table_fit.ts` that decides which columns survive a narrow container.
  */
-export interface TableColumn {
-  /** Stable id — also the `sortKey` when `sortable`. */
-  key: string;
-  /** Header label (uppercase eyebrow). Omit for a control column (a trailing ⋯). */
+export interface TableColumn extends TableFitColumn {
+  /** Header label (uppercase eyebrow). Omit for a control column (a trailing ⋯).
+   *  In stacked mode it renders as the eyebrow over the cell's value. */
   label?: string;
-  /** Fixed width in px; omit for a flexible column. */
-  width?: number;
   /** Flex grow when no `width` (default 1). */
   flex?: number;
   align?: "left" | "right";
+  /** The `key` doubles as the `sortKey`. */
   sortable?: boolean;
 }
 
@@ -37,6 +40,8 @@ interface TableCtx {
   columns: TableColumn[];
   leading: number;
   trailing: number;
+  visibleKeys: ReadonlySet<string>;
+  stacked: boolean;
 }
 const TableContext = createContext<TableCtx | null>(null);
 
@@ -73,34 +78,64 @@ export interface TableProps {
  * sortable column becomes a `SortHeader`) and its `TableRow` children,
  * `Divider`-separated. Compose `TableRow` / `TableCell` for the body. For a
  * non-columnar list (entity piles, card stacks) use `PressableRow` directly.
+ *
+ * The register is container-responsive with no prop: when the measured width
+ * can't fit every column it drops droppable columns by `priority`, and below
+ * the register floor rows stack (label over value, from the column `label`s) —
+ * the header band gives way (sorting rides the columns; a stacked register
+ * keeps its current order). See `computeTableFit`.
  */
 export function Table(props: TableProps) {
   const { columns, sort, onSort, sortLabels, selectAll, leading = 0, trailing = 0, children } = props;
   const rows = Children.toArray(children).filter(isValidElement);
 
+  // Measure-then-REVEAL (the `DetailTable` contract): the unmeasured first
+  // frame renders invisible, so the first PAINT is already in the right mode —
+  // no register→stacked reshuffle as the screen mounts.
+  const [width, setWidth] = useState<number | null>(null);
+  const fit: TableFit =
+    width == null
+      ? { visibleKeys: new Set(columns.map((c) => c.key)), stacked: false }
+      : computeTableFit(columns, leading, trailing, width);
+  const visibleColumns = columns.filter((c) => fit.visibleKeys.has(c.key));
+
   return (
-    <TableContext.Provider value={{ columns, leading, trailing }}>
+    <TableContext.Provider value={{ columns, leading, trailing, visibleKeys: fit.visibleKeys, stacked: fit.stacked }}>
       {/* ONE layout node: without this wrapper the header band + body land as two
           direct flex children of the app's container, and a parent column `gap`
           (the standard section spacing) opens a hole between the header and rows. */}
-      <View>
-        <View style={styles.headerBand}>
-          {leading > 0 ? <View style={{ width: leading }}>{selectAll}</View> : null}
-          {columns.map((col) => (
-            <View key={col.key} style={colStyle(col)}>
-              {col.label ? (
-                col.sortable && onSort ? (
-                  <SortHeader label={col.label} sortKey={col.key} sort={sort ?? null} onSort={onSort} align={col.align} labels={sortLabels} />
-                ) : (
-                  <Text size="xs" color="muted" transform="uppercase" numberOfLines={1}>
-                    {col.label}
-                  </Text>
-                )
-              ) : null}
+      <View
+        onLayout={(e) => setWidth(e.nativeEvent.layout.width)}
+        style={width == null ? styles.unmeasured : null}
+      >
+        {fit.stacked ? (
+          // Stacked mode has no column band — labels moved into the rows. The
+          // select-all checkbox keeps its band: it's the bulk-select entry point,
+          // aligned over the rows' leading checkboxes.
+          selectAll != null && leading > 0 ? (
+            <View style={styles.headerBand}>
+              <View style={{ width: leading }}>{selectAll}</View>
             </View>
-          ))}
-          {trailing > 0 ? <View style={{ width: trailing }} /> : null}
-        </View>
+          ) : null
+        ) : (
+          <View style={styles.headerBand}>
+            {leading > 0 ? <View style={{ width: leading }}>{selectAll}</View> : null}
+            {visibleColumns.map((col) => (
+              <View key={col.key} style={colStyle(col)}>
+                {col.label ? (
+                  col.sortable && onSort ? (
+                    <SortHeader label={col.label} sortKey={col.key} sort={sort ?? null} onSort={onSort} align={col.align} labels={sortLabels} />
+                  ) : (
+                    <Text size="xs" color="muted" transform="uppercase" numberOfLines={1}>
+                      {col.label}
+                    </Text>
+                  )
+                ) : null}
+              </View>
+            ))}
+            {trailing > 0 ? <View style={{ width: trailing }} /> : null}
+          </View>
+        )}
         <View style={styles.body}>
           {rows.map((row, i) => (
             <View key={i}>
@@ -120,9 +155,15 @@ export type TableRowProps = {
   marked?: boolean;
   /** Outside the door, BEFORE the cells (a selection checkbox) — width = Table `leading`. */
   leading?: ReactNode;
-  /** Outside the door, AFTER the cells (a ⋯ menu / a button) — width = Table `trailing`. */
+  /** Outside the door, AFTER the cells: the row's OVERFLOW chrome (a ⋯ `ActionMenu`).
+   *  Register mode renders it in the trailing gutter beside `action`; stacked mode keeps
+   *  it on the top line. Width = Table `trailing` (shared with `action`). */
   trailing?: ReactNode;
-  /** Min row height. Default 52. */
+  /** The row's primary action (a CTA `Button`). Register mode: in the trailing gutter,
+   *  before `trailing`; stacked mode: the content's bottom line, right-aligned — an action
+   *  reads at content scale, not as row chrome. Reserve Table `trailing` for it. */
+  action?: ReactNode;
+  /** Min row height (register mode; stacked rows size to their content). Default 52. */
   minHeight?: number;
   /** The `TableCell`s, one per column, in column order. */
   children: ReactNode;
@@ -151,34 +192,68 @@ export type TableRowProps = {
  * row, rounded to the register wash); mouse presses ride the `PressableRow`
  * surface, and nested controls claim their own. `leading`/`trailing` slots stay
  * independently pressable. Cells map to `Table`'s columns by position.
+ *
+ * In the Table's STACKED mode (container below the register floor) the same
+ * row renders as a pile: a top line of [leading] [first cell] [trailing], then
+ * the remaining cells as label-over-value blocks — same door, same wash, same
+ * slots, different geometry.
  */
 export function TableRow(props: TableRowProps) {
-  const { onPress, selected, marked, accessibilityLabel, leading, trailing, minHeight = 52, children } = props;
+  const { onPress, selected, marked, accessibilityLabel, leading, trailing, action, minHeight = 52, children } = props;
   const ctx = useContext(TableContext);
   if (!ctx) throw new Error("TableRow must be used within a Table");
 
-  const cells = (Children.toArray(children).filter(isValidElement) as ReactElement<TableCellProps>[]).map(
-    (cell, i) => cloneElement(cell, { _column: ctx.columns[i] }),
-  );
+  const cells = (Children.toArray(children).filter(isValidElement) as ReactElement<TableCellProps>[])
+    .map((cell, i) => ({ cell, column: ctx.columns[i] as TableColumn | undefined }))
+    // A dropped column drops its cell (stacked shows everything). Cells beyond
+    // the declared columns stay — same tolerance as the width mapping.
+    .filter(({ column }) => ctx.stacked || column == null || ctx.visibleKeys.has(column.key))
+    .map(({ cell, column }) => cloneElement(cell, { _column: column, _stacked: ctx.stacked }));
   const { focusVisible, focusProps } = useFocusRing();
 
+  const body = ctx.stacked ? (
+    <View style={styles.stackedBody}>
+      <View style={styles.stackedTopLine}>
+        {ctx.leading > 0 ? <View style={[styles.slot, { width: ctx.leading }]}>{leading}</View> : null}
+        <View style={styles.stackedPrimary}>{cells[0]}</View>
+        {trailing != null ? <View style={styles.slot}>{trailing}</View> : null}
+      </View>
+      {cells.length > 1 ? (
+        // The field lines sit on the identity column's text edge — indented
+        // past the leading gutter, never wrapping under the checkbox.
+        <View style={[styles.stackedFields, ctx.leading > 0 ? { paddingLeft: ctx.leading + COLUMN_GAP } : null]}>
+          {cells.slice(1)}
+        </View>
+      ) : null}
+      {action != null ? <View style={styles.stackedActionLine}>{action}</View> : null}
+    </View>
+  ) : null;
+
   // Read-only row (no `onPress`): a static, non-interactive row — no hover wash,
   // no pointer cursor, no focusable door — so a `Table` can present read-only
   // tabular data (a fee breakdown, a spec sheet) without implying the rows open
   // something. An interactive row (with `onPress`) keeps the full register surface.
   if (!onPress) {
+    if (ctx.stacked) {
+      return <View style={styles.staticStackedRow}>{body}</View>;
+    }
     return (
       <View style={styles.staticRow}>
         {ctx.leading > 0 ? <View style={{ width: ctx.leading }}>{leading}</View> : null}
         <View style={[styles.cells, { minHeight }]}>{cells}</View>
-        {ctx.trailing > 0 ? <View style={{ width: ctx.trailing, alignItems: "flex-end" }}>{trailing}</View> : null}
+        {ctx.trailing > 0 ? (
+          <View style={[styles.trailingSlot, { width: ctx.trailing }]}>
+            {action}
+            {trailing}
+          </View>
+        ) : null}
       </View>
     );
   }
 
   return (
     <PressableRow onPress={onPress} selected={selected} marked={marked} style={styles.row}>
-      {ctx.leading > 0 ? <View style={[styles.slot, { width: ctx.leading }]}>{leading}</View> : null}
+      {!ctx.stacked && ctx.leading > 0 ? <View style={[styles.slot, { width: ctx.leading }]}>{leading}</View> : null}
       {/* An absolutely-positioned sibling paints — and hit-tests — above in-flow
           content, which would swallow every cell control's press; the slots lift
           above it via zIndex 1 (z-index applies to flex items), so the door gets
@@ -191,8 +266,19 @@ export function TableRow(props: TableRowProps) {
         {...focusProps}
         style={[styles.door, focusVisible && { boxShadow: FOCUS_RING }]}
       />
-      <View style={[styles.cells, { minHeight }]}>{cells}</View>
-      {ctx.trailing > 0 ? <View style={[styles.slot, { width: ctx.trailing, alignItems: "flex-end" }]}>{trailing}</View> : null}
+      {ctx.stacked ? (
+        body
+      ) : (
+        <>
+          <View style={[styles.cells, { minHeight }]}>{cells}</View>
+          {ctx.trailing > 0 ? (
+            <View style={[styles.slot, styles.trailingSlot, { width: ctx.trailing }]}>
+              {action}
+              {trailing}
+            </View>
+          ) : null}
+        </>
+      )}
     </PressableRow>
   );
 }
@@ -201,11 +287,26 @@ export interface TableCellProps {
   children: ReactNode;
   /** @internal — injected by `TableRow` from the column at this cell's position. */
   _column?: TableColumn;
+  /** @internal — injected by `TableRow`; the Table is in stacked mode. */
+  _stacked?: boolean;
 }
 
-/** One cell — its width/align come from the column `TableRow` injects by position. */
+/** One cell — its width/align come from the column `TableRow` injects by position.
+ *  In stacked mode it IS a `DetailRow` (spread: muted label left, value at the
+ *  right edge) — the drawer's detail-row component, not a lookalike, so a
+ *  stacked register and the record workspace behind its door share one
+ *  vocabulary by construction. `DetailRow` values are arbitrary nodes (the
+ *  drawer renders badges, money stacks, editors, popover triggers in them), so
+ *  register cell content needs no adaptation. A label-less control column has
+ *  no line to spread — its content pins to the right edge. */
 export function TableCell(props: TableCellProps) {
-  const { children, _column } = props;
+  const { children, _column, _stacked } = props;
+  if (_stacked) {
+    if (!_column?.label) {
+      return <View style={styles.stackedBareCell}>{children}</View>;
+    }
+    return <DetailRow label={_column.label}>{children}</DetailRow>;
+  }
   return <View style={_column ? colStyle(_column) : undefined}>{children}</View>;
 }
 
@@ -213,11 +314,11 @@ const styles = StyleSheet.create({
   // A hairline under the column header anchors the columns; the rows below it are
   // Divider-separated.
   headerBand: {
-    paddingHorizontal: 20,
+    paddingHorizontal: ROW_GUTTER,
     paddingVertical: 10,
     flexDirection: "row",
     alignItems: "center",
-    gap: 14,
+    gap: COLUMN_GAP,
     borderBottomWidth: 1,
     borderColor: colors.border,
   },
@@ -226,15 +327,22 @@ const styles = StyleSheet.create({
     gap: 0,
   },
   row: {
-    gap: 14,
+    gap: COLUMN_GAP,
   },
   // Read-only row (a `TableRow` with no `onPress`): the register row's gutter +
   // layout so cells still align with the header, minus the hover/press surface.
   staticRow: {
     flexDirection: "row",
     alignItems: "center",
-    gap: 14,
-    paddingHorizontal: 20,
+    gap: COLUMN_GAP,
+    paddingHorizontal: ROW_GUTTER,
+  },
+  // Row-direction like the pressable path — the body fills the width via
+  // `flex: 1` on the horizontal axis and sizes its own height (a `flex: 1`
+  // child of an auto-height COLUMN parent risks collapsing to zero).
+  staticStackedRow: {
+    flexDirection: "row",
+    paddingHorizontal: ROW_GUTTER,
   },
   // The keyboard door: an empty overlay spanning the row — the tab stop + focus
   // ring live here, the cells are its SIBLINGS (see TableRow's doc). Radius
@@ -251,7 +359,7 @@ const styles = StyleSheet.create({
     flex: 1,
     flexDirection: "row",
     alignItems: "center",
-    gap: 14,
+    gap: COLUMN_GAP,
     zIndex: 1,
   },
   // Leading/trailing gutters carry their own controls — lifted above the door
@@ -259,4 +367,53 @@ const styles = StyleSheet.create({
   slot: {
     zIndex: 1,
   },
+  // Stacked (below the register floor): the row is a pile — top line keeps the
+  // leading/trailing slots on the first cell, the rest are label-over-value
+  // blocks. Vertical padding replaces the register's minHeight centering.
+  stackedBody: {
+    flex: 1,
+    gap: 10,
+    paddingVertical: 12,
+    zIndex: 1,
+  },
+  stackedFields: {
+    gap: 8,
+  },
+  // The register's trailing gutter composes [action, overflow] on one row —
+  // the gap matches the composite the templates previously hand-rolled.
+  trailingSlot: {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "flex-end",
+    gap: 8,
+  },
+  // Stacked mode: the CTA closes the content, right-aligned — content scale,
+  // not row chrome (the overflow ⋯ stays on the top line).
+  stackedActionLine: {
+    flexDirection: "row",
+    justifyContent: "flex-end",
+  },
+  stackedTopLine: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: COLUMN_GAP,
+    minHeight: 40,
+  },
+  stackedPrimary: {
+    flex: 1,
+    minWidth: 0,
+  },
+  // A label-less cell in stacked mode: no label to spread against — content
+  // pins right, on the `DetailRow` line rhythm.
+  stackedBareCell: {
+    flexDirection: "row",
+    justifyContent: "flex-end",
+    alignItems: "center",
+    minHeight: 28,
+  },
+  // Measure-then-reveal: invisible until the container width is known, so the
+  // first visible frame is already register OR stacked — never a reshuffle.
+  unmeasured: {
+    opacity: 0,
+  },
 });

package/src/table_fit.ts

@@ -0,0 +1,88 @@
+/**
+ * The fit layer for `Table` — the pure decision of which columns fit a measured
+ * container width, kept free of any React-Native import so it unit-tests
+ * directly (the register in `table.tsx` renders this result; see `matrix_totals`
+ * for the same split).
+ *
+ * The register degrades in two deterministic tiers instead of overflowing.
+ * Tier 1: everything fits → the columnar register, unchanged. Tier 2: drop
+ * droppable columns by `priority` until the rest fit (the row is a scannable
+ * index — the door opens the record where dropped values live). Tier 3: even
+ * the minimum column set can't fit (a phone) → every row STACKS, label above
+ * value. All of it derives from the container width (onLayout, not the
+ * viewport) so a register inside a half-width panel adapts exactly like one on
+ * a small screen — the same contract as `DetailTable` / `Breakdown`.
+ */
+
+/** The column fields the fit decision reads — `TableColumn` extends this. */
+export interface TableFitColumn {
+  /** Stable id. */
+  key: string;
+  /** Fixed width in px; omit for a flexible column. */
+  width?: number;
+  /** Drop precedence when the container can't fit every column: HIGHER numbers
+   *  drop first, ties drop right-to-left. Default = the column's index (so an
+   *  unannotated register sheds from the right). The FIRST column is the row's
+   *  identity — it never drops. */
+  priority?: number;
+}
+
+/** Gap between the header band's / a row's children — `table.tsx` styles consume
+ *  this, so the fit math and the rendered geometry can't drift. */
+export const COLUMN_GAP = 14;
+/** The register's horizontal gutter — mirrors `PressableRow`'s register variant
+ *  (`paddingHorizontal: 20`), the one geometry this file models but doesn't own.
+ *  `table.tsx` consumes it for the header band and static rows. */
+export const ROW_GUTTER = 20;
+const ROW_H_PADDING = ROW_GUTTER * 2;
+/** Fit-math width a flexible column needs to stay usable — below this the flex
+ *  column is crushed to ellipsis soup, so it counts as this wide when deciding
+ *  what fits. Layout still lets it grow (`flex`) or shrink (`minWidth: 0`). */
+const FLEX_MIN_WIDTH = 120;
+/** Fewer side-by-side columns than this stops being a register — stack instead. */
+const MIN_VISIBLE_COLUMNS = 2;
+
+export interface TableFit {
+  /** Keys of the columns that render side-by-side. All keys when `stacked`. */
+  visibleKeys: ReadonlySet<string>;
+  /** The minimum column set can't fit — rows render as label-over-value stacks. */
+  stacked: boolean;
+}
+
+/**
+ * Pure fit decision for a measured container width: which columns stay
+ * side-by-side, or whether the register stacks.
+ */
+export function computeTableFit(
+  columns: TableFitColumn[],
+  leading: number,
+  trailing: number,
+  width: number,
+): TableFit {
+  const requiredWidth = (cols: TableFitColumn[]): number => {
+    const slots = cols.length + (leading > 0 ? 1 : 0) + (trailing > 0 ? 1 : 0);
+    const gaps = Math.max(0, slots - 1) * COLUMN_GAP;
+    const colsWidth = cols.reduce((sum, c) => sum + (c.width ?? FLEX_MIN_WIDTH), 0);
+    return ROW_H_PADDING + (leading > 0 ? leading : 0) + (trailing > 0 ? trailing : 0) + colsWidth + gaps;
+  };
+
+  const allKeys = new Set(columns.map((c) => c.key));
+  const priorityOf = (c: TableFitColumn) => c.priority ?? columns.indexOf(c);
+  // Column 0 never enters the drop order — it's the row's identity.
+  const dropOrder = columns
+    .slice(1)
+    .sort((a, b) => priorityOf(b) - priorityOf(a) || columns.indexOf(b) - columns.indexOf(a));
+
+  const kept = new Set(allKeys);
+  const floor = Math.min(MIN_VISIBLE_COLUMNS, columns.length);
+  for (const col of dropOrder) {
+    if (kept.size <= floor) break;
+    if (requiredWidth(columns.filter((c) => kept.has(c.key))) <= width) break;
+    kept.delete(col.key);
+  }
+  if (requiredWidth(columns.filter((c) => kept.has(c.key))) > width) {
+    // Below the register floor: stack every column (vertical space is free).
+    return { visibleKeys: allKeys, stacked: true };
+  }
+  return { visibleKeys: kept, stacked: false };
+}