@lotics/ui 46.9.0 → 46.13.0

package/AGENTS.md

@@ -17,8 +17,8 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 | [docs/catalog.md](./docs/catalog.md) | **The complete inventory** — Reach-by-role (each data role → the ONE canonical component) + every `@lotics/ui/<module>` entry point (incl. `@lotics/ui/vite`'s `loticsOptimizeDeps` + `loticsResolve()` — the pre-bundle list and the whole `resolve` block a custom-code app's `vite.config.ts` imports rather than hand-carries, dev-link included). Read before building any screen; reuse first. |
 | [docs/data_entry.md](./docs/data_entry.md) | Which editing pattern for which job — inline edit, fieldset forms, choosing a CHOICE control by option count, find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (`InlineFiles` for a record ROW, the `FilesEditor` COMPOUND for a whole section, plus the three-way file INTAKE), stage gates, and the commit-on-blur vs action-press ordering law. |
 | [docs/ai_patterns.md](./docs/ai_patterns.md) | AI acts, the human stays in charge — composer, live run feed (`AgentRun`), the one law's split — it turns on WHO supplied the values; findings, provenance, confidence; **after the run** — a stored record that fills up from several writers; the whole run in a dialog, **stopping**; **review surfaces compose from atoms** — `DiffValue`, `DiffMark`, `useChangeSet`. |
-| [docs/composition.md](./docs/composition.md) | The design-language contract — **the form comes before the treatment** (name what the subject IS before reaching for parts), canvas + content column, heading altitude, register vs inset rows, the button ladder, master-detail `Drawer`, the register's rhythm, craft and TRIAGE bands, where the accent goes, theming as an app-level ESCAPE HATCH, color discipline, typography, **one fact one surface** (a chooser over the thing it chooses is a SELECTOR, not a second card grid; a control that only swaps one number for another is replaced by showing both), and where a commit sits. |
-| [docs/reviewing.md](./docs/reviewing.md) | **Reviewing a screen you built — and the answer when one "looks bad"** — the other docs say what good looks like; this one says how to find out whether you achieved it. Run it BEFORE the deploy: a typecheck, a lint, a test and `app check` are all blind to how a screen reads. GATES that outrank every treatment question, then 11 probes each naming what to COLLECT and the SIGNATURE in the numbers. Plus the extraction snippets, what measurement cannot see, and how to act on a finding. |
+| [docs/composition.md](./docs/composition.md) | The design-language contract — **the form comes before the treatment** (name what the subject IS before reaching for parts), canvas + content column, heading altitude, register vs inset rows, the button ladder, master-detail `Drawer`, the register's rhythm, craft and TRIAGE bands, where the accent goes, theming as an app-level ESCAPE HATCH, color discipline, typography, **one fact one surface** (a chooser over the thing it chooses is a SELECTOR, not a second card grid; a control that only swaps one number for another is replaced by showing both), **a width floor answers can this be READ and never can this be operated** (the operating question passes a row whose every string is already cut), and where a commit sits. |
+| [docs/reviewing.md](./docs/reviewing.md) | **Reviewing a screen you built — and the answer when one "looks bad"** — the other docs say what good looks like; this one says how to find out whether you achieved it. Run it BEFORE the deploy: a typecheck, a lint, a test and `app check` are all blind to how a screen reads. GATES that outrank every treatment question, then the probes, each naming what to COLLECT and the SIGNATURE in the numbers — including the truncation sweep, the only one that catches a row whose halves both measure fine and whose text is cut. Plus the extraction snippets, what measurement cannot see, and how to act on a finding. |
 | [docs/testing.md](./docs/testing.md) | Driving the kit in a browser — the three anatomies where the a11y tree says one thing and a driver must do another: a `PressDoor` row whose named button always intercepts pointer events (by design), portalled overlays that render at the top of the DOM, and custom pointer drag that `dragTo` cannot move. |
 | [docs/templates.md](./docs/templates.md) | The map of `examples/tpl_*.tsx` — what shape each template solves and which to start from (copy + adapt, never import) — plus the record-surface composition rules (pipeline order, static shape, decision budget) and the ACTIVITY shape — a communications feed where the row's label is the GIST and the body varies by medium, one anatomy rather than a row type per kind. |
 

package/docs/catalog.md

@@ -125,6 +125,28 @@ someone wants `md`. Initials are the first and **last** word of the name — "V
 Watson" → MW — because a Vietnamese name's first two words are the family and middle names
 that a whole office shares.
 
+### Several THINGS in one cell — `ThumbnailStack`
+
+`ThumbnailStack` is `AvatarGroup`'s sibling over a different subject: a capped, overlapping set
+of PICTURES answering "an order of what?", "which parts?", "what arrived?" in one register cell.
+Pass `{ id, label, image }` per thing; `max` (default 3) caps it and the rest become the `+N`
+mark at the end of the stack. Both components read their separating edge from `mark_stack.ts`,
+so a row carrying people in one column and goods in the next reads as one device used twice
+rather than two — but they **tuck by different fractions, and that is deliberate**: a face is
+edge-anchored and survives being covered two thirds of the way, while a product shot centres its
+subject in studio margin, so the facepile's ratio lands the remainder on top of the last
+photograph. Both ratios live in `mark_stack.ts` beside each other, with the reason.
+
+What differs from a facepile follows from a thing not being a person: the marks are ROUNDED
+SQUARES (round is the shape the kit spends on a face), and there is **no initials fallback** —
+"CA" is not a stand-in for a bag of coffee, so a thing with no picture renders a neutral
+placeholder and its `label` carries the meaning to a screen reader. Inert, like the facepile:
+its home is a pressable row and it must not hold a second destination.
+
+**Reach for it wherever a row states a COUNT of things it could show instead.** A register whose
+rows carry a bare number reads as a ledger of nothing in particular; the pictures are the row's
+own data, and they say what the business is before a word is read.
+
 ### A select-field value
 
 `OptionBadge` (a stored `select` value as its CONFIGURED colored badge) — never hand-map
@@ -691,6 +713,19 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`group_avatar`** — `GroupAvatar`: a name's initials in a zinc rounded square (`size` — the
   same rung scale AND the same initials rule as `Avatar`, default `md`); the avatar for
   image-less entities — groups, organizations. A person → `Avatar`/`MemberChip`.
+- **`thumbnail_stack`** — `ThumbnailStack`: the same capped stack over THINGS rather than
+  parties — a set of product, document or unit pictures answering "an order of what?" in one
+  register cell. Takes `{ id, label, image? }`, shows `max` (default 3) and makes the rest the
+  `+N` mark at the END of the stack. Rounded squares, not discs, and **no initials fallback**: a
+  name is a fair stand-in for a face and a useless one for a bag of coffee, so a picture-less
+  thing renders a neutral placeholder while its `label` carries the meaning to a screen reader.
+  Marks `announce` (the stack shows no text) and it is INERT, for the same reason the facepile
+  is. Reach for it wherever a row states a COUNT of things it could show instead.
+- **`mark_stack`** — the constants a capped stack of marks is built from: `MARK_RING` (the
+  translucent separating edge, shared, so the two stacks read as one device) plus a tuck ratio
+  EACH — `MARK_OVERLAP_RATIO` for faces and the shallower `THUMBNAIL_OVERLAP_RATIO` for things,
+  because a face survives being covered two thirds of the way and a centred product shot does
+  not. They sit together so the difference reads as a decision rather than a typo.
 - **`avatar_group`** — `AvatarGroup`: a SET of parties as overlapping marks — "who is on this" in
   one cell. Takes `{ id, name, kind: "person" | "group", image? }`, shows `max` of them (default
   3) and makes the rest a `+N` that is the LAST MARK IN THE STACK, not loose text beside it.

package/docs/composition.md

@@ -992,6 +992,31 @@ by what KIND of thing they are.
   list. A tab earns a `status` dot (the optional `TabOption.status`, a `ColorName`) only when its
   area needs attention (a blocker / missing item) — the resting state has none.
   **`SegmentedControl`** chooses a MODE/PARAMETER of the SAME view (2–4 peers, no panel swap).
+- **ONE tab strip per surface. A `Tabs` never opens onto another `Tabs`.** The second strip is not
+  navigation any more — it is a filter wearing navigation's clothes, and it charges the reader a
+  second click plus a second thing to keep in their head to reach a list that was always a sibling
+  of the first. Below a tab strip the switch is a `ChipGroup` (a lens on what is already on
+  screen) or a `SegmentedControl` (a mode of it); if neither fits because the two panels really
+  are different content, that tab was **two destinations wearing one name** and the fix is to
+  promote both into the strip above.
+  **The label confesses it before the layout does: a tab named "X and Y" is two tabs.** Reach for
+  the domain's own list of things — the entities its people already name one at a time — and give
+  each one a tab; a pair invented to keep the strip short buys nothing, because the pair has to be
+  taken apart again one level down. A flat strip of six beats five that hide two.
+- **A tab is a DESTINATION, and it has to earn one. Measure what it holds for a SCOPED reader,
+  never for yourself.** The account building the thing usually sees everything; the person using it
+  sees one team's, one site's, one region's slice. A tab that looks like a list while you develop
+  can be a single row in the field — and a top-level slot spent on one row is a slot the reader
+  pays for on every visit. Open the app as someone whose scope actually bites before deciding the
+  strip is right.
+- **The second question is who OWNS what the tab edits.** A screen belongs in the app where its
+  owner works, not wherever it was convenient to build. When a tab lets one role edit another
+  role's master data — the org's catalogue reachable from a site-level tool — the fix is not a
+  permission check bolted on top; it is that the screen is in the wrong app. Move it to the one its
+  owner already opens, and put it BESIDE the thing it is about rather than in a tab of its own: a
+  record and the people attached to it are one subject and belong on one screen. Moving it to a new
+  tab in the new app just relocates the mistake.
+
 - **Layout**: search + secondary filters LEFT, the primary CTA RIGHT, in ONE band. A `ChipGroup`
   one-of-N lens is fine ONLY when the band has no `SearchInput`; once a search is present, the
   status filter becomes a `Select`/`FilterChip` dropdown — never a row of pills competing with the
@@ -1466,6 +1491,24 @@ question to answer per register is "what is the last column standing", and the a
 always the figure the register exists to compare — so give that one the lowest number and work
 outwards.
 
+**A width floor answers "can this be READ", never "can this be operated" — and the second
+question passes screens the first one fails.** The two numbers look interchangeable and are not: a
+control's floor is what it takes to still click and type in something, a value's is what it takes
+to still read the sentence inside it. Ask the operating question about a column and it reports a
+fit at a width where the content is already ellipsis: a name needing 221 gets 104, a status phrase
+needing 165 gets 117, and BOTH HALVES MEASURE FINE while the row is unreadable — there is no
+overflow, no clipped container, nothing a layout probe sees. What gets cut is the tail of the
+phrase, which in a status column is the part that carries the meaning: the reason, not the noun.
+
+Two corollaries, because this is a family of bugs rather than one:
+
+- **Shed a neighbour before crushing the flexible column.** A column is flex BECAUSE its content
+  is variable-length — it is the one that asked for the slack, so it is the last that should be
+  squeezed to buy room for a fixed neighbour the author already marked droppable.
+- **Below the width where the last pair can both be read, the row is not a narrow row — it is a
+  stack.** Vertical space is free; horizontal space is not. Fewer, taller rows that say everything
+  beat more rows that say half.
+
 **A conditional column and its cell are ONE decision.** A register may hide a column whose data
 no row carries yet — that is data-driven shape, and it is allowed. What breaks is that the
 `columns` entry and the row's `TableCell` are two edits in two files, so it is natural to make

package/docs/data_entry.md

@@ -471,7 +471,7 @@ first earns a chooser. For the second, render the path most readers take and off
 secondary action beside that form's submit, where it is visible without being in the way.
 
 The tell is that people press the chooser far more than once each. The
-measurement is in [reviewing.md](./reviewing.md) probe 8b.
+measurement is in [reviewing.md](./reviewing.md) probe 8c.
 
 And when you do offer the alternative beside the submit, **give it its own treatment**: an
 alternative WAY IN and a recovery link ("forgot your password") are different roles, and two

package/docs/reviewing.md

@@ -374,7 +374,52 @@ A resting register is the cheapest thing to screenshot and the least likely to h
 - **Ask of every value: could this exist in the data?** Name the column. No answer means the block
   goes.
 
-### 8b. First paint — count the controls the task actually needs
+### 8a. Navigation depth — count the tab strips on one screen
+
+**Measure.** `document.querySelectorAll('[role="tablist"]').length` on every top-level
+destination, not just the landing one. More than **one** on any screen is a finding: the second
+strip is a filter wearing navigation's clothes, and it costs a click and a place to remember on
+the way to a list that was a sibling of the first all along.
+
+```js
+[...document.querySelectorAll('[role="tablist"]')].map(t => ({
+  labels: [...t.querySelectorAll('[role="tab"]')].map(x => x.textContent.trim()).join(' | '),
+  top: Math.round(t.getBoundingClientRect().top),
+}))
+```
+
+**Walk every tab before concluding.** The nesting usually hides behind one or two of them, so a
+landing screen measuring `1` proves nothing — the app that prompted this rule was flat on four of
+its five destinations and nested on the other two.
+
+**The cheaper signature, before you open a browser at all: grep the tab LABELS for "and" / "và".**
+A destination named for two things is two destinations, and the second strip is where the pair
+gets taken apart again. The same grep over the source (`<Tabs` per file) finds it without a
+running app: more than one file rendering `Tabs` in one app is the same defect at rest.
+
+→ [composition.md](./composition.md) §"Choice, filter & navigation controls" (one strip per surface).
+
+### 8b. Does each tab earn its slot — count its rows AS A SCOPED READER
+
+**Measure.** For every top-level destination, count what it holds for a reader whose scope actually
+bites — not for the build account, which usually sees everything. A tab holding **one row** for a
+real user is not a destination; it is a record, and it belongs beside the thing it is about.
+
+Where a surface is scoped by membership, the build account is the worst possible reader to judge
+from: it is typically on every team/site, so a one-row tab renders as a full list and looks fine.
+Drive it as a scoped member (an app-level view-as flag if the platform has one, or read the query's
+own filter and count what a single-membership reader would match).
+
+**Then ask who owns the data.** A tab that edits master data belonging to a DIFFERENT role is in
+the wrong app — a site-level tool editing the organisation's catalogue. That is not fixed by a
+permission check; the screen moves to the app its owner already opens.
+
+**Source-side signature:** a screen whose list query filters by the viewer's membership, over a
+table the domain describes as organisation-wide.
+
+→ [composition.md](./composition.md) §"Choice, filter & navigation controls".
+
+### 8c. First paint — count the controls the task actually needs
 - **On any screen whose job is ENTRY, count `input`/`select`/`textarea` on first paint.** Zero is
   the finding: something is gating the task behind a press, and every probe above reads whatever
   that gate rendered instead — a two-item menu measures perfectly as a two-item menu.
@@ -389,6 +434,48 @@ A resting register is the cheapest thing to screenshot and the least likely to h
 - **The same count catches the inverse**: a screen that opens on twelve inputs where the task
   needs three. Count what the FIRST decision requires, not what the record can hold.
 
+### 8d. Dead counts — every summary number that names a set you cannot reach
+
+**Measure.** Read the summary strip, then the filter band above it, and pair them off. Every
+`warning`/`danger`-toned item, and every item phrased as "N missing / N overdue / N unassigned",
+must have a filter that isolates exactly that set. An item with no partner is a dead count.
+
+**Then press the filter and count rows, because a rendered chip proves nothing.** Filtering to a
+set the data says is empty must EMPTY the list; filtering to one that matches everything must
+change nothing. Both readings are needed — a chip that binds its label but never narrows looks
+identical to a working one. (Found exactly that way: a chip whose summary read back correctly and
+whose list stayed at nine of nine, because the `useMemo` computing the list never listed the
+filter in its dependency array. Typecheck, lint and a screenshot all passed it.)
+
+**The cheap source-side signature:** a `SummaryLine` item carrying `tone` in a file whose filter
+band has only a `SearchInput`.
+
+→ [composition.md](./composition.md) §"Choice, filter & navigation controls"; the rule itself is in
+`src/summary_line.tsx`'s contract.
+
+### 8e. Truncation — every string the layout cut, at the width a phone actually is
+
+**Measure.** At 375 (and again at 320), walk every leaf node and compare `scrollWidth` to
+`clientWidth`. Anything wider is being cut, and the page reports no overflow while it happens:
+
+```js
+[...document.querySelectorAll("*")]
+  .filter((el) => !el.children.length && el.scrollWidth > el.clientWidth + 1 && el.textContent.trim())
+  .map((el) => ({ txt: el.textContent.trim(), needs: el.scrollWidth, got: el.clientWidth }))
+```
+
+An empty array is the pass. This is the ONE probe that catches a width floor answering the wrong
+question — see composition.md, "A width floor answers can this be READ" — because every other
+signal is green: no horizontal scroll, no console error, the container fits, the screenshot at a
+glance looks like a table. Only the string is short.
+
+**Read the result by WHAT was cut, not how much.** A trimmed heading is cosmetic. A trimmed
+*status*, *reason*, or *error* is a functional defect: those phrases front-load the category and
+back-load the meaning, so the half that survives is the half the reader already knew.
+
+**Source-side signature:** a fit or stack decision that reaches for a control/usability constant
+(`MIN_CONTROL_WIDTH`, a flex minimum) where the thing being measured holds prose.
+
 ### 9. The absence pass — what catches "bland"
 Every probe above reads an element that EXISTS. None fires on a screen where nothing is wrong and
 nothing is right, which is the screen reported as bland. Defect-removal converges on *inoffensive*;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "46.9.0",
+  "version": "46.13.0",
   "type": "module",
   "exports": {
     "./accordion": "./src/accordion.tsx",
@@ -171,6 +171,7 @@
     "./list_item": "./src/list_item.tsx",
     "./loading": "./src/loading.tsx",
     "./locale": "./src/locale.tsx",
+    "./mark_stack": "./src/mark_stack.ts",
     "./markdown": {
       "react-native": "./src/markdown.tsx",
       "default": "./src/markdown.web.tsx"
@@ -279,6 +280,7 @@
       "react-native": "./src/theme.ts",
       "default": "./src/theme.web.ts"
     },
+    "./thumbnail_stack": "./src/thumbnail_stack.tsx",
     "./time_columns": "./src/time_columns.tsx",
     "./time_options": "./src/time_options.ts",
     "./time_picker": "./src/time_picker.tsx",

package/src/avatar_group.tsx

@@ -5,6 +5,7 @@ import { Text } from "./text";
 import { AVATAR_PX, AVATAR_TEXT, type AvatarSize } from "./avatar_size";
 import { colors } from "./colors";
 import { useLoticsLocale } from "./locale";
+import { MARK_OVERLAP_RATIO, MARK_RING } from "./mark_stack";
 
 /** One party in the set. A PERSON takes the disc; a group or an organization
  *  takes the rounded square, which is `Avatar`'s own shape axis and the one
@@ -25,34 +26,6 @@ export interface AvatarGroupPrincipal {
  *  separable at a glance and a number is the more honest summary. */
 const DEFAULT_MAX = 3;
 
-/**
- * How far each mark tucks under the one before it, as a fraction of the rung.
- *
- * A FRACTION, not a pixel constant, so the stack is the same object at every
- * rung — a fixed inset barely stacks at `lg` and eats the marks at `sm`. Just
- * under a third leaves each mark's whole leading edge, which is as much of an
- * image or a pair of initials as the reader needs to tell the parties apart.
- */
-const OVERLAP_RATIO = 0.3;
-
-/**
- * The hairline separating each mark from the one it covers.
- *
- * TRANSLUCENT INK, never the surface colour — and that is what lets this
- * component overlap at all. The conventional facepile rings each mark in the
- * page background so the discs read as separate, which binds the ring to a
- * colour the row does not keep: a register row washes to `zinc[50]` on hover,
- * `zinc[100]` as the open record and `zinc[200]` while pressed, so a white
- * ring is a halo in three of the four states — and those are the states a
- * reader is in when they are actually looking at the row. A translucent dark
- * edge DARKENS whatever is behind it instead of matching it, so it holds on
- * every ground. `FileBadge` separates itself from its own surface the same way.
- *
- * A `boxShadow` rather than a border, because a border grows the box: a stacked
- * mark would render 2px wider than the identical mark in the next column.
- */
-const MARK_RING = "0 0 0 1px rgba(0,0,0,0.12)";
-
 /**
  * A SET of parties as marks — the answer to "who is on this" in one cell.
  *
@@ -116,7 +89,7 @@ export function AvatarGroup(props: AvatarGroupProps) {
   const shown = principals.slice(0, max);
   const hidden = principals.length - shown.length;
   const px = AVATAR_PX[size];
-  const overlap = Math.round(px * OVERLAP_RATIO);
+  const overlap = Math.round(px * MARK_OVERLAP_RATIO);
   // Descending, so the FIRST mark ends up on top. The remainder is one more
   // thing to lay under, hence its own slot in the depth.
   const depth = shown.length + (hidden > 0 ? 1 : 0);

package/src/mark_stack.ts

@@ -0,0 +1,54 @@
+/**
+ * The two constants a capped stack of marks is built from.
+ *
+ * They live here, side by side, because there are two stacks — a set of PARTIES
+ * (`avatar_group`) and a set of THINGS (`thumbnail_stack`) — and the decision
+ * each constant encodes is only legible NEXT TO the other one. The edge is
+ * shared: a stack that separated itself differently would read as a second
+ * device rather than as the same one over a different subject. The tuck is NOT,
+ * and the two ratios sitting together is what stops the difference looking like
+ * a typo in one of them.
+ */
+
+/**
+ * How far one FACE tucks under the one before it, as a fraction of the rung.
+ *
+ * A FRACTION, not a pixel constant, so the stack is the same object at every
+ * rung — a fixed inset barely stacks at `lg` and eats the marks at `sm`. Just
+ * under a third leaves each mark's whole leading edge, which is as much of an
+ * image or a pair of initials as the reader needs to tell the marks apart.
+ */
+export const MARK_OVERLAP_RATIO = 0.3;
+
+/**
+ * The same tuck, for a stack of THINGS — and it is deliberately shallower.
+ *
+ * A face is edge-anchored: hair, a jaw, a colour, all readable from the leading
+ * third, which is what lets a facepile overlap so hard. A product shot is the
+ * opposite — the subject is CENTRED with studio margin around it, so a third of
+ * the tile is exactly the part that carries the object. At the face ratio the
+ * remainder lands on top of the last photograph and reads as covering it rather
+ * than as following it, which is the one thing the mark must not do: it is a
+ * statement ABOUT the set, not a member of it competing for the same glance.
+ *
+ * Shallow rather than zero, because the marks still have to read as one object.
+ */
+export const THUMBNAIL_OVERLAP_RATIO = 0.15;
+
+/**
+ * The hairline separating each mark from the one it covers.
+ *
+ * TRANSLUCENT INK, never the surface colour — and that is what lets a stack
+ * overlap at all. The conventional facepile rings each mark in the page
+ * background so the marks read as separate, which binds the ring to a colour
+ * the row does not keep: a register row washes to `zinc[50]` on hover,
+ * `zinc[100]` as the open record and `zinc[200]` while pressed, so a white ring
+ * is a halo in three of the four states — and those are the states a reader is
+ * in when they are actually looking at the row. A translucent dark edge
+ * DARKENS whatever is behind it instead of matching it, so it holds on every
+ * ground. `FileBadge` separates itself from its own surface the same way.
+ *
+ * A `boxShadow` rather than a border, because a border grows the box: a stacked
+ * mark would render 2px wider than the identical mark in the next column.
+ */
+export const MARK_RING = "0 0 0 1px rgba(0,0,0,0.12)";

package/src/summary_line.tsx

@@ -55,6 +55,15 @@ export interface SummaryLineProps {
  * that gathers children (a consol of house shipments, an order of lines) may carry one
  * above THAT list.
  *
+ * **A count here is a PROMISE that the subset is reachable.** An item the reader
+ * would act on — anything tinted `warning`/`danger`, and any "N missing / N
+ * overdue / N unassigned" — names a set, and the strip renders it as text with no
+ * press target. So the band ABOVE must carry the filter that isolates it: the
+ * same split, the same words. Without one the screen says *something here needs
+ * attention* and then hides the rows, which is worse than staying silent — the
+ * reader now knows there is a problem and has only the scrollbar to find it.
+ * A neutral total ("12 lines", "45 seats") promises nothing and needs no filter.
+ *
  * **Never on a record's identity band, reporting that record's own state.** Derived
  * verdicts about one record — "documents incomplete", "2 fields need checking", "no
  * next milestone" — are a checklist, and a record does not carry a checklist

package/src/table_fit.ts

@@ -1,8 +1,14 @@
+import { MIN_VALUE_WIDTH } from "./control_surface";
+
 /**
  * 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).
+ * container width, kept free of any React-Native import at RUNTIME so it
+ * unit-tests directly (the register in `table.tsx` renders this result; see
+ * `matrix_totals` for the same split). That is now a property of a CHAIN rather
+ * than of this file: `control_surface` is imported for {@link MIN_VALUE_WIDTH},
+ * and it stays importable here only while its own React-Native import remains
+ * type-only. Give it a runtime one and this module stops being pure with
+ * nothing here to say so.
  *
  * The register degrades in two deterministic tiers instead of overflowing.
  * Tier 1: everything fits → the columnar register, unchanged. Tier 2: drop
@@ -77,12 +83,33 @@ export const ROW_HEIGHT = 72;
  */
 export const ROW_GUTTER = 0;
 const ROW_H_PADDING = ROW_GUTTER * 2;
-/** Width a flexible column needs to stay usable — below this it is crushed to
- *  ellipsis soup. `Table` counts a flex column as this wide when deciding what
- *  fits; `DataGrid`, which sheds nothing, uses it as the column's hard floor so
- *  the squeeze overflows the grid instead of erasing its identity column.
- *  Exported so the two cannot drift. */
+/** Width a flexible column needs to stay OPERABLE — below this it is crushed to
+ *  ellipsis soup. `DataGrid`, which sheds nothing, uses it as the column's hard
+ *  floor so the squeeze overflows the grid instead of erasing its identity
+ *  column. `Table` can shed, so it asks the harder question instead — see
+ *  {@link FLEX_READ_WIDTH}. */
 export const FLEX_MIN_WIDTH = 120;
+/**
+ * What `Table` counts a flex column as needing — what it takes to READ one, not
+ * what it takes to operate one.
+ *
+ * The two questions are different, and the kit has answered this one before:
+ * `DetailRow` asked a CONTROL's floor whether a value column was wide enough,
+ * and "both halves measured fine and the row was unreadable" — which is why
+ * {@link MIN_VALUE_WIDTH} exists. `Table` is the surface that fix missed. Asking
+ * {@link FLEX_MIN_WIDTH} let a register declare itself fitted while handing its
+ * one flexible column 120px: a 375 phone kept two columns and gave the second
+ * 117, so a status phrase needing 165 came out "Quầy chưa ch…" and the reason a
+ * vehicle could not leave was the half that got cut.
+ *
+ * A flex column is flex BECAUSE its content is variable-length — it is the one
+ * column that asked for the slack, so it is the last one that should be crushed
+ * to buy room for a fixed neighbour the author already marked droppable. Shed
+ * one more column first; stack only when even the two-column floor cannot seat a
+ * readable one. `DataGrid` keeps {@link FLEX_MIN_WIDTH} because it sheds
+ * nothing, so for it the honest question really is "can this still be operated".
+ */
+const FLEX_READ_WIDTH = MIN_VALUE_WIDTH;
 /** Fewer side-by-side columns than this stops being a register — stack instead. */
 const MIN_VISIBLE_COLUMNS = 2;
 
@@ -106,7 +133,7 @@ export function computeTableFit(
   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);
+    const colsWidth = cols.reduce((sum, c) => sum + (c.width ?? FLEX_READ_WIDTH), 0);
     return ROW_H_PADDING + (leading > 0 ? leading : 0) + (trailing > 0 ? trailing : 0) + colsWidth + gaps;
   };
 

package/src/thumbnail_stack.tsx

@@ -0,0 +1,151 @@
+import { Image, View, type StyleProp, type ViewStyle } from "react-native";
+import { Icon } from "./icon";
+import { Text } from "./text";
+import { AVATAR_PX, AVATAR_TEXT, type AvatarSize } from "./avatar_size";
+import { colors } from "./colors";
+import { useLoticsLocale } from "./locale";
+import { MARK_RING, THUMBNAIL_OVERLAP_RATIO } from "./mark_stack";
+
+/** One THING in the set — a product, a document, a unit. Not a party: a thing
+ *  has no initials worth reading, so it is its picture or it is a placeholder. */
+export interface ThumbnailStackItem {
+  /** Stable identity — the React key. */
+  id: string;
+  /** What the thing is, for the screen reader. The stack shows no text. */
+  label: string;
+  /** The thing's own picture. Absent renders the neutral placeholder. */
+  image?: string | null;
+}
+
+/** Three reads as "a few"; past that the pictures stop being separable at a
+ *  glance and a number is the more honest summary. Same default as a facepile,
+ *  for the same reason. */
+const DEFAULT_MAX = 3;
+
+/**
+ * A SET of THINGS as pictures — the answer to "an order of what?" in one cell.
+ *
+ * The sibling of `AvatarGroup`, over a different subject. The two share their
+ * separating edge (`mark_stack.ts`) so a row carrying both reads as one device
+ * used twice. What differs is everything that follows from a thing not being a
+ * person — including how hard they tuck:
+ *
+ * **A shallower overlap.** A face is edge-anchored and survives being covered
+ * two thirds of the way; a product shot centres its subject in studio margin,
+ * so the face ratio puts the remainder on top of the last photograph. Both
+ * ratios live in `mark_stack.ts` beside each other, with the reason.
+ *
+ * **Square, not round.** Round is the shape the kit spends on a person's face.
+ * A rounded square is what `Avatar` already gives an organization, and a crate
+ * of goods belongs on that side of the axis.
+ *
+ * **No initials.** `Avatar` falls back to a person's initials because a name is
+ * a reasonable stand-in for a face. "CA" is not a stand-in for a bag of coffee
+ * — it is noise wearing the shape of information — so a thing with no picture
+ * renders a neutral placeholder that says only "something is here", and the
+ * label carries the meaning to anyone listening.
+ *
+ * **The remainder is the last mark IN the stack**, not text after it: `+9`
+ * trailing the pictures as loose type reads as a separate fact about the row
+ * instead of as the rest of this one.
+ *
+ * **It is INERT.** Its home is a register row, and a row that already presses
+ * must not hold a second destination four pixels to the left.
+ *
+ * **It caps what it was GIVEN.** The overflow counts from what will actually
+ * render, so `+9` never counts a mark the reader can see is missing. Drop what
+ * you cannot show before you pass it in.
+ *
+ * Pure: pass resolved labels and image urls; this fetches nothing.
+ */
+export interface ThumbnailStackProps {
+  items: readonly ThumbnailStackItem[];
+  /** Pictures shown before the remainder becomes `+N`. Default 3. */
+  max?: number;
+  /**
+   * A rung on the shared avatar scale — the same scale the marks in the
+   * neighbouring columns take, so a row of goods and a row of people sit on one
+   * beat. Everything inside derives from it; nothing here is a fixed pixel.
+   */
+  size?: AvatarSize;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}
+
+export function ThumbnailStack(props: ThumbnailStackProps) {
+  const { items, max = DEFAULT_MAX, size = "md", style, testID } = props;
+  const locale = useLoticsLocale();
+
+  if (items.length === 0) return null;
+
+  const shown = items.slice(0, max);
+  const hidden = items.length - shown.length;
+  const px = AVATAR_PX[size];
+  const overlap = Math.round(px * THUMBNAIL_OVERLAP_RATIO);
+  const radius = Math.round(px * 0.2);
+  // Descending, so the FIRST picture ends up on top and the remainder lies
+  // under everything rather than covering one of the things it is counting.
+  const depth = shown.length + (hidden > 0 ? 1 : 0);
+
+  return (
+    <View testID={testID} style={[{ flexDirection: "row", alignItems: "center" }, style]}>
+      {shown.map((item, index) => (
+        <View
+          key={item.id}
+          accessible
+          accessibilityLabel={item.label}
+          style={{
+            width: px,
+            height: px,
+            marginLeft: index === 0 ? 0 : -overlap,
+            // `zIndex` needs a positioned box to take effect in
+            // react-native-web; without it the marks stack in DOM order.
+            position: "relative",
+            zIndex: depth - index,
+            borderRadius: radius,
+            overflow: "hidden",
+            backgroundColor: colors.zinc["100"],
+            alignItems: "center",
+            justifyContent: "center",
+            boxShadow: MARK_RING,
+          }}
+        >
+          {item.image ? (
+            <Image
+              source={{ uri: item.image }}
+              style={{ width: px, height: px }}
+              resizeMode="cover"
+              accessibilityIgnoresInvertColors
+            />
+          ) : (
+            <Icon name="package" size={Math.round(px * 0.5)} color={colors.zinc["400"]} />
+          )}
+        </View>
+      ))}
+      {hidden > 0 && (
+        <View
+          accessible
+          accessibilityLabel={locale.avatar.more(hidden)}
+          style={{
+            width: px,
+            height: px,
+            marginLeft: shown.length === 0 ? 0 : -overlap,
+            position: "relative",
+            zIndex: 0,
+            borderRadius: radius,
+            backgroundColor: colors.zinc["100"],
+            alignItems: "center",
+            justifyContent: "center",
+            boxShadow: MARK_RING,
+          }}
+        >
+          {/* The rung's own type — a fixed size here is how a stack ends up
+              with a 14px count beside 12px marks. */}
+          <Text size={AVATAR_TEXT[size]} weight="medium" color="zinc-700" aria-hidden>
+            {`+${hidden}`}
+          </Text>
+        </View>
+      )}
+    </View>
+  );
+}