@lotics/ui 11.4.0 → 11.6.0

package/docs/templates.md

@@ -0,0 +1,357 @@
+# Templates — the worked example screens
+
+The package ships full worked-example screens in `examples/tpl_*.tsx` — each a complete,
+runnable recipe for one screen **job**, built purely from `@lotics/ui` components plus mock
+data. This doc is the map: what shape each template solves, what it owns versus what its
+primitives own, and which one to start from. Read it when starting any new screen, then read
+the chosen template's source before writing code. Component contracts live in
+[the catalog](./catalog.md), the layout/color laws in [the composition grammar](./composition.md);
+the package index is [../AGENTS.md](../AGENTS.md).
+
+## How to use an example
+
+- **Read the source** at `node_modules/@lotics/ui/examples/<name>.tsx`. Each file is
+  self-contained: `react` + `react-native` + `@lotics/ui/<module>` imports only, mock data
+  constants at the top, one exported screen component.
+- **Copy and adapt — never import.** The `examples/` directory ships as `.tsx` source and is
+  **not** in the package's `exports` map: `import … from "@lotics/ui/examples/…"` fails module
+  resolution by design. Copy the bands you need into your app, keep the component imports,
+  and replace the mock constants with real reads.
+- **Pick by the job, not the domain.** Templates are scenario-flavoured (a pick run, cash
+  application, a delivery week) but generic-purpose — they teach the shape. Your orders /
+  items / customers screen starts from the template whose *job* matches, whatever the domain.
+- The templates encode the composition grammar (band order, toolbar law, color discipline,
+  status weight) as working code — when a template and your instinct disagree, the template
+  wins.
+
+## Picking by the job
+
+| You are building | Start from |
+| --- | --- |
+| Executive overview — KPIs, trends, an attention list | `tpl_dashboard` |
+| Monitoring a population too large to browse (drill-down → faceted register) | `tpl_stock` |
+| A live wallboard of hundreds of unit states | `tpl_tower` |
+| One dimension crossed against another, with drill | `tpl_pivot` |
+| Hierarchical totals chased down a tree | `tpl_rollup` |
+| A register / consolidated work-list (browse, per-row action, bulk action) | `tpl_item_list` |
+| A guided sequence of physical tasks (scan, confirm, next) | `tpl_pick` |
+| Splitting one source amount across many targets | `tpl_allocate` |
+| A record's create/edit surface — also the settings shape | `tpl_record` |
+| A personal to-do list | `tpl_tasks` |
+| A team task board (inline-managed grouped table) | `tpl_task_board` |
+| Financial statements | `tpl_statements` |
+| A scoped lookup report with export | `tpl_report` |
+| A week calendar + agenda | `tpl_calendar` |
+| An attendance desk | `tpl_attendance` |
+| Shift signup + staffing | `tpl_shifts` |
+| AI produces a visual artifact on a canvas | `tpl_dieline` |
+| AI ranks answers — look-up-and-explain | `tpl_lookup` |
+| AI over a record's documents (extract / cross-check / generate) | `tpl_documents` |
+
+## Analytics
+
+Read-mostly screens that answer a question about a population, then open doors into the
+records behind each number.
+
+### `tpl_dashboard` — the executive overview
+
+One screen answering "how is this period going, where is it stuck, who pays the bills".
+Bands: header + period · `KPIStrip` · a revenue chart (`BarChart`, emerald = money) beside
+the pipeline (`StackedProgressBar`, blue = pipeline) · a **Needs attention** `Accordion`
+(icon + label + count `Badge`; expanding opens the records behind the count, each row
+carrying its domain `⋯ ActionMenu`) · top customers (`Avatar` + revenue + margin badge; the
+name `Peek`s the dossier). Also exercises the wider chart family (`LineChart`, `PieChart`,
+`RingGauge`, `Sparkline`, `TrendFooter`, `Funnel`) and `DateRangeFilterField` — the date
+filter actually filters the KPI datasets. Start here for any "state of the operation"
+landing screen.
+
+### `tpl_stock` — the drill-down overview (large populations)
+
+Monitoring a population too large to browse (10,000+ units). The funnel: `KPIStrip`
+(population health) → `Breakdown` cards (composition by dimension; **pressing a segment IS
+the drill-down**) → dismissible facet chips + search → a **paginated** register (the data
+volume is the reason `Pagination` exists) → row press opens the sequenced unit `Drawer`, `⋯`
+carries quick operations. Facets combine across dimensions and each `Breakdown`'s counts
+respect the *other* dimensions' selections — true faceted search. Also the reference for
+color discipline: coherent dimensions take one hue family shaded by `ramp`; status colors
+carry meaning, one `ColorName` per state, no hand-picked hex.
+
+### `tpl_tower` — the status-grid wallboard
+
+Continuous monitoring of hundreds of live units (machines, gates, sensors). Three bands
+answer the three ops questions in order: `KPIStrip` + `StatusGrid` = "is everything OK right
+now?" (scan for red; the `StatusLegend` drills a state) · an exceptions rail = "where do I
+look first?" (severity, then longest unresolved) · a `Heatmap` = "when/where does it
+cluster?" (pressing a cell explains the day). Cells and exception rows open the SAME
+sequenced unit `Drawer` (with a `Timeline` of the unit's events). One semantic color
+reference per state — every weight (grid cell, legend dot, drawer badge) derives from that
+family name.
+
+### `tpl_pivot` — the cross-tab desk
+
+One dimension crossed against another, then drill. The `Matrix` is the hero: the number IN
+each cell plus a heat wash behind it so 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?".
+
+### `tpl_rollup` — hierarchical totals
+
+Totals with drill: three levels (e.g. region → site → lane), every level carrying the SAME
+aligned metric columns so a bad number can be chased down the tree ("which branch drags the
+total?"). Pure composition: nested `Accordion`s + a fixed-width column map; under-target
+branches are flagged at every level so the drill path is visible before expanding. Leaf rows
+open a sequenced `Drawer`.
+
+## Work
+
+Screens where the user executes: browse → act. **Every work screen is FLAT (no `Card`) and
+ONE of two shapes**: a register/list you WORK EACH of (press a row → workspace `Drawer`) or
+a list you ACT ON MANY of (tick rows → `FloatingActionBar`) — never a side-by-side
+master-detail panel.
+
+### `tpl_item_list` — THE canonical register
+
+The one work-execution list shape; it subsumes approvals, dispatch, batch-building, and run
+screens — register, per-row action, gated selection, and act-on-many in one. The page:
+
+- **One toolbar row** — search + a status `Select` + facet `FilterChip`s LEFT, the New CTA
+  RIGHT; a light `SummaryLine` of the filtered view below.
+- **A sortable, `Divider`-separated `Table`** where every row carries a leading checkbox; a
+  row that can't take the bulk action gets a **disabled** checkbox (the same gating as any
+  blocked line). A per-row action `Button` (here Print) is the row's primary action in the
+  trailing column, `⋯` its overflow. A select-all band, footer totals + `Pagination`, and a
+  `FloatingActionBar` carrying the bulk action while rows are ticked.
+- **A row press opens the PRODUCTION workspace `Drawer`**, which demonstrates the full
+  record-workspace anatomy section by section:
+  - **Details `DetailTable`** showing every inline field type — text, `InlineMemberSelect`,
+    dates incl. optional time, dot-select, money number, the `InlineTagSelect` tag field,
+    and `InlineStatic` + a System badge for read-only values. Detail rows earn trailing CTAs
+    where deserved (Phone → Call, Due → Today) — the case where `trailingWidth` IS set.
+  - **Linked records** — the customer's other records as `ListItem`s (title + description at
+    the column edge, badge · amount · chevron); pressing one PUSHES an **editable** workspace
+    for that record inside the drawer via the hosted `ScreenRouter` — while `canGoBack` the
+    drawer header swaps to a back button + the pushed id and the ◀ ▶ sequencer hides; back
+    pops with scroll preserved.
+  - **Files** with its own Add CTA — `FileRows` CRUD via `pickFiles`, plus an EXPECTED
+    document as a ghost `FileRow placeholder` with a Request action.
+  - **Payment** — the `Ledger` (charge/received groups with sums, peekable fee rows,
+    `LedgerTotal`) + a Record-payment popover that appends a receipt.
+  - **Activity** — the CRM touch-log shape: optional outcome pills (`ChipGroup`,
+    tap-to-deselect) over a MULTILINE note (the note IS the record and the one requirement),
+    an always-visible optional follow-up `InlineDatePicker`, an "Attach files" secondary
+    (`pickFiles` → removable `FileThumbnailGrid` in the composer), and the primary Log button
+    saying WHY when disabled. Below, a labelled History `Timeline` of outcome-typed entries,
+    newest first — an entry's attachments ride its expandable details as a thumbnail grid
+    whose press opens the shared `FileGalleryModal`.
+  - A closing `DangerZone`.
+
+### `tpl_pick` — the guided queue
+
+Work that is a SEQUENCE of physical tasks, not a list to browse: the run hands the operator
+the next location, they scan to verify (`ScanField`), confirm the count (`Counter`), and the
+next task takes its place. A single-focus column — the CURRENT task is the only thing in view;
+the whole path is a collapsible `Accordion` below, collapsed by default, so position is one
+tap away and never competes with the task. Can't-skip ordering, `Stepper` + `ProgressBar`
+progress, and a short-pick exception that flags-and-advances without stalling, ending in a
+`CompletionState`.
+
+### `tpl_allocate` — the split
+
+Apply ONE source across MANY targets until the remainder is zero (cash application,
+stock-to-orders, budget distribution). The inverse of a batch builder: batch SUMS parts up to
+a total; allocation SPLITS a fixed total DOWN with a remainder that must hit zero. The
+`RemainderMeter` is the spine — under (left on account) · exact (apply) · over (blocked).
+Oldest-first auto-allocates; each `AllocationRow` can be filled or typed.
+
+### `tpl_record` — THE record surface
+
+Create-then-refine taken all the way: **"New" is ONE CLICK** (no dialog, no form) — it
+creates a fresh Draft and the surface IS the editor; everything refines in place. It absorbed
+the old order-form, inline-record, intake, settings, billing, and quick-capture templates.
+Top → bottom:
+
+- A `RecordSummary` header (identity · status · the one metric) over its key-fact
+  `DetailTable`, then a Details `DetailTable` — one shared column grid, auto-stacking when
+  narrow.
+- **The customer section — TWO states, no swap mode.** Attached = the read-only-first card:
+  Edit/Done live in the SECTION HEADING and swap the fields to inline chips, where a trailing
+  Fetch fills contact + city from a registry lookup keyed by tax ID, un-gating billing;
+  Remove (danger) sits low and detaches the link (the customer stays in the book) → the
+  find-or-create search, whose custom row opens the create `Dialog` rendering the SAME
+  inline-chip table + Fetch.
+- **Files** — `FileDropzone` add, gallery preview, delete.
+- **Billing, owned by a later desk** (gated until the record reaches that stage), in the
+  inline vocabulary: each invoice is a hairline-set band; charge amounts are chips with the
+  list price as ghost placeholder + a one-tap "Standard …" suggestion pill while unset;
+  "How paid…" select chips; NO per-band totals — the collect band owns the number. The band's
+  action row sits BOTTOM-RIGHT as *hint → status dot → Issue*, the hint naming exactly what
+  blocks (fees → method → the customer gate). An ISSUED invoice keeps its lines editable and
+  offers Re-issue — a new lookup code replaces the old, confirmed in the same `Dialog`. Plus
+  a validated receipt and a separate refundable deposit.
+- **The lifecycle is a HANDOFF CHAIN** (e.g. Sales → Operations → Accounting → Closed): a
+  Tasks section speaking the full task-list grammar — a clearable Group-by `FilterChip`
+  (Desk/Assignee/Status) plus assignee/status filter chips derive the groups (empty groups
+  drop, EXCEPT desk groups — the journey stays visible; desk heads keep their owner dots,
+  assignee heads are `MemberChip`s), the add-a-task `CaptureRow` at the TOP landing on the
+  current desk, rows riding the `Checklist`/`ChecklistRow` compound with per-task
+  `InlineMemberSelect` assignees and a per-row `menu` (move to next desk · danger Delete),
+  and suggested tasks as `SuggestionChip`s. EVERY desk's rows edit — the stage gates the
+  handoff and Billing, never task editing (planning ahead on a later desk is normal work).
+  **Per-stage handoff CTAs are NEVER blocked** — open tasks warn and carry over.
+- Also the settings shape: Preferences switch rows + a `DangerZone`.
+- A LEFT OUTLINE RAIL (`MenuButton` + `useSectionNav`) jumps between the sections and
+  scroll-spies the active one; on narrow containers it becomes the pinned current-section
+  bar opening a section-picker `Modal`.
+
+### `tpl_tasks` — the quick list
+
+The personal to-do shape: quiet `CheckCircle` rows you tick to finish and tap to **expand in
+place** to edit (`Inline*` editors; the row is stable — the meta summary never shifts on
+expand), colour-dot tags (`OptionBadge`), an attachments field (`FilesEditor` — thumbnail
+grid, tap a tile for the gallery with download + confirmed remove, plus its Add button),
+search + a clearable group-by (✕ → ungrouped) + tag filter chips, and a primary
+Draft-from-notes CTA (`Composer` → `AgentRun` → `ChangeReview`). No assignee — the list is
+yours.
+
+**Warning — never a button in a button.** There is deliberately NO `Task` component: a task
+row varies too much to bake into one, so rows compose `CheckCircle` + `InlineTextInput` +
+inline-editor cells as **sibling** controls in a plain `View`. NEVER wrap the whole row in a
+`Pressable accessibilityRole="button"` (for tap-to-expand) with those controls nested inside:
+React Native Web renders the row AND each control as a `<button>`, so you get `<button>`s
+inside a `<button>` — invalid DOM, and the inner controls drop out of the keyboard tab order.
+Give "expand" its own affordance (a trailing `Pressable` over the meta/chevron), as
+`tpl_tasks` does.
+
+### `tpl_task_board` — the columns shape
+
+The manager's board: a search · group-by · filter toolbar over a grouped, sortable grid of
+LIVE inline-editable cells — assignee/due/status/tags set directly in the cell. It builds on
+the `DataGrid` primitive (the inline-managed grouped-table shape) and **owns only its data,
+toolbar, columns, and per-group add**; `DataGrid` owns the sortable header, the collapsible
+grouped sections, and the aligned rows. It demonstrates:
+
+- A **files cell** — thumbnail glance in the cell → a `Popover` hosting the full
+  `FilesEditor` → gallery.
+- A **dynamic action column** — a per-row underlined action link (`TextLink`) driven by each
+  row's `action` descriptor (attach / approve / open…), each wired in a real app to its OWN
+  workflow: one board, a different action per row; the link's pressable fills the cell to
+  match the inline editors.
+- A trailing `ActionMenu` (the `⋯` overflow — a `danger` Remove behind a confirm `Alert`).
+- CUSTOM pressable cells (files, the action link) hover with the control-surface BORDER
+  reveal (`HOVER_BORDER` from `@lotics/ui/control_surface`) — the same language as the
+  inline-editor cells beside them, never their own background wash.
+- Per-group add rows that pre-set the group's field (align with the exported `gridRowStyle`),
+  and the same Draft-from-notes CTA as `tpl_tasks`.
+
+Both `tpl_tasks` and `tpl_task_board`: filters/search left, primary CTA right, one toolbar
+row; group-by holds only real dimensions, ✕ clears to ungrouped (no "Nothing" option).
+
+**Altitude rule**: `tpl_task_board` is the inline-managed grouped table — MODERATE data you
+manage in view (group/sort/filter/edit-in-place; it renders ALL rows). For thousands+ you
+BROWSE — that's `tpl_item_list`'s paginated register, not this.
+
+## Finance
+
+### `tpl_statements` — the statement grammar
+
+The income statement, balance sheet, and cash flow statement in ONE statement grammar:
+right-aligned column captions over fixed money columns, items indented under group headers, a
+hairline rule above every subtotal, the grand total DOUBLE-RULED (the accounting convention),
+negatives in accounting parentheses, per-cell currency-free (the meta line names the currency
+once), no bars, no charts — the numbers are the interface. Composed from `Text` + `Divider`
+alone: it teaches a grammar, not a component. The three statements TIE — net income flows
+into retained earnings, closing cash IS the balance sheet's cash, the loan repayment moves
+the debt line. Keep your books reconciled when adapting the data, or the screen teaches the
+wrong thing.
+
+### `tpl_report` — the scope-first lookup report
+
+Answer a question by SCOPING a dataset, not by browsing it. The scope bar leads: a header
+period (`DateRangeFilterField`) + ONE search key chosen from several mutually-exclusive
+dimensions (`SegmentedControl` swaps the matching picker; switching the key resets the
+value). That scope drives everything below — KPI totals → a row of pressable `Breakdown`
+facets (the long-tail one folds behind `maxRows`) → the paginated register of matching lines
+→ an Export button. Leave the search empty and the period alone gives the whole-period
+report. The fee / transaction / usage lookup desk.
+
+## Scheduling
+
+### `tpl_calendar` — the week desk
+
+One real `CalendarView` week grid over the current week's events, then a "Today" agenda card
+of pressable rows. Every slot is a door: pressing a grid event or an agenda row opens the
+sequenced workspace `Drawer`; agenda rows also carry the `⋯` quick-actions menu. Event colors
+carry meaning (one `ColorName` per event kind). The mock data anchors to the real current
+week so the copied screen is evergreen.
+
+### `tpl_attendance` — the attendance desk
+
+Who is in, who is late, who is out, plus the weekly per-person grid. Header + month `Picker`
+· `KPIStrip` (the four counts) · `Tabs` Today / This week. "Today" = one banded roster
+`Card` — each row press-opens the person's workspace `Drawer` (◀ ▶ sequencing) and carries a
+`⋯ ActionMenu` with the day's quick fixes. "This week" = per-person `Accordion` rows: day
+markers expanding to the day-by-day detail in place. Presence is one accent; badge colors
+carry the status meaning.
+
+### `tpl_shifts` — two-sided staffing
+
+Members SIGN UP, the manager DECIDES and FILLS. Three bands reuse the execution grammar: the
+coverage board is the overview (shifts × days, each cell its filled/required state — press to
+open the slot), the signup rail is the APPROVALS pattern (in-hours = one-click Accept;
+overtime = a consequence `Dialog`; decline behind `⋯`), and the slot drawer fills gaps with
+the DISPATCH fit-gate (every candidate names their hours; same-slot members are excluded,
+double-shift days flagged). Accepting and assigning move the board live.
+
+## Agents
+
+Screens where AI does the work and the human reviews. `tpl_dieline` *produces* an artifact;
+`tpl_lookup` and `tpl_documents` *structure* information for a decision. The AI component
+contracts and the propose→review→apply loop live in [ai_patterns.md](./ai_patterns.md).
+
+### `tpl_dieline` — the design canvas
+
+The page IS the design: a parametric drawing fills the centre of a pannable/zoomable surface,
+a FLOATING `Composer` sits at the bottom, and a pinned PARAMS PANEL (a hand-composed
+label/value field card in live-edit mode) floats centre-right. Empty → drop a photo in the
+composer → the centre processes while the composer MORPHS into a progress pill
+(`AgentProgress`) → the drawing reveals, the params panel appears, the composer returns. Two
+ways to change it: prompt the agent ("5 mm taller") or edit a param directly — either
+re-flows the design in place. The geometry is deterministic (the app owns it); the agent only
+proposes parameters. The panel carries the single Download.
+
+### `tpl_lookup` — the answer desk
+
+Look-up-and-explain (classification, tariff/fee lookup, policy Q&A, a spec/compliance desk).
+Describe the subject on the LEFT (`Composer` + `AgentRun`), the agent RANKS the matching
+candidates (nearest matches, the top one wearing a Recommended `Badge`), you pick one and its
+structured ANSWER pins on the RIGHT — the code, the exact breakdown as hand-composed spec
+rows, policy `Callout`s, `Confidence`, and `Sources`. The flow is input → matches → pick, not
+a single confident verdict: classification is ambiguous, so the alternatives are first-class.
+Refine the description in a follow-up and the ranking updates.
+
+### `tpl_documents` — the document desk
+
+THE worked example for everything document-driven on a record. A record's files block feeds
+ONE **"Use AI"** entry — the one AI entry point, never per-row AI buttons (the per-row `⋯`
+menu holds only Rename/Download). Inside its dialog the run FORKS into three tasks as
+`CardSelectItem`s (select → a confirming footer CTA, never one-click):
+
+- **Extract** (read the documents, fill the record) — the open `ChangeFields` review: ONE
+  `Change` section per record whose body stacks a `ChangeField` per proposed value (label ·
+  the − band when replacing · the editable + value). **Editing IS the review**; an add has no
+  before, a removal is the − band alone, and a conflict shows the read-only outcome band over
+  candidate rows + a type-another-value third option. Proposed line items arrive as
+  `ChangeRecord` cards; Keep-all + one outcome-named Apply commit.
+- **Cross-check** (compare the documents against the record and each other) — ranked,
+  display-only `Finding`s the human acts on, closing in a recorded verdict.
+- **Edit with AI** — the `askAi` handoff: dialogue-shaped file iteration happens in the
+  platform chat (the documents attached to a fresh thread), not in the app.
+
+Separately, a **Create documents** action opens its own dialog: a readiness checklist
+(hand-composed rows — per-document missing inputs open a fill screen, saved values recompute
+readiness) → generation runs as a visible `AgentRun`, never a teleport → generated files stay
+PENDING (previewable) until the user commits them onto the record.
+
+All mock — `useState` plus a timer streams the `AgentRun`; a real app drives the same
+components from its live agent run.

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

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "11.4.0",
+  "version": "11.6.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -223,7 +223,8 @@
   "files": [
     "src",
     "examples",
-    "AGENTS.md"
+    "AGENTS.md",
+    "docs"
   ],
   "publishConfig": {
     "access": "public"

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