@lotics/ui 46.12.0 → 46.14.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), **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/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), **a status column earns its slot by carrying a REASON rather than a state** (the floor asks for the fact to be visible, not for a badge), 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 (a row whose halves both measure fine and whose text is cut) the summary-vs-facet check (a strip that keeps describing the unfiltered set) and the derivable-column test (a status badge its neighbour already answers). 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

@@ -1389,6 +1389,25 @@ reader can see, sort and filter — the column is the fact, the grouping is one
 Ship the column first, offer grouping as a control, and let `TableGroup` render whatever the reader
 picked. Everything below governs how the bands look and behave once they are on.
 
+**"The column is the floor" asks for the fact to be VISIBLE, not for a badge.** A status column
+earns its slot when it carries something the rest of the row cannot produce — a REASON, a name, a
+next step. When the state is already derivable from a neighbour, the badge is a second copy of one
+fact, free to disagree with the first, and it costs a column on every screen to say what the
+reader already read.
+
+The clean discriminator is what the badge would say that the row does not:
+
+- A gate register whose status reads *"paperwork not closed"* keeps its column. No other cell
+  yields that; it is the sentence the operator repeats to the person in front of them.
+- A ticket register pairing two timestamps in one cell (`in → out`) does not. A second timestamp
+  present means closed, absent means open — the state IS the shape of the cell, and an added
+  *Open / Closed* badge restates it in a column's worth of width.
+
+Two things usually carry the state better than a badge, and both are already on the row: the
+INTERVAL cell, where a missing second half is the open case, and the per-row ACTION, which exists
+only in one state and is the more useful signal because it can be pressed. Where the reader needs
+to isolate a state rather than spot it, that is the facet's job, not a column's.
+
 **A value's filter renders the value the same way its cell does.** If the status cell is a
 `Badge variant="dot"`, the status filter's options are dot badges too — same vocabulary, same
 colours, same shapes. Re-rendering it as plain text makes the reader translate between two

package/docs/reviewing.md

@@ -453,7 +453,60 @@ 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
+### 8e. Derivable columns — every column another cell already answers
+
+**Measure.** Per column, ask what it would say that its neighbours do not, and try to produce its
+value from them. A column you can compute from the row is not a column; it is a restatement that
+can drift from its source.
+
+The frequent one is a STATUS badge beside an interval: `start → end` already distinguishes open
+from closed, so *Open / Closed* spends a column repeating the shape of the cell next to it. Same
+test for a total beside its parts, a duration beside two timestamps, a "has attachments" tick
+beside a file count.
+
+**Keep it when the badge carries a REASON rather than a state** — "blocked: papers expired" is not
+derivable from any other cell, and it is the sentence the operator reads aloud.
+
+**Signature in the numbers:** a column whose distinct-value count across the register is 2 while a
+neighbouring cell varies with it one-for-one.
+
+→ [composition.md](./composition.md) §"A register that TRIAGES".
+
+### 8f. Does the summary describe WHAT'S SHOWN — press a facet, then re-read it
+
+**Measure.** Record the summary strip's numbers. Press one filter value. Record them again, and
+record how many rows the register now holds.
+
+- The row count changed and **the numbers did not** → the strip is summarising a set the reader
+  cannot see. It is aggregating the raw query rather than the view.
+- Also compare the `y` of the filter controls against the `y` of the strip. Controls must come
+  FIRST: the reader filters, then reads what the filter left.
+
+```js
+const y = (sel) => { const e = document.querySelector(sel); return e ? Math.round(e.getBoundingClientRect().top) : null }
+// facet chips vs the summary strip — chips must be the smaller number
+```
+
+**Why it survives every other check.** Both halves render perfectly, the numbers are real, and
+nothing overflows or errors — the strip is simply answering a question nobody asked. It reads as
+authoritative precisely because it is stated in the same place as the honest version.
+
+**Two shapes it takes, and the second is the one that hides.** A strip computed off the raw query
+never moves. A strip computed off a PARTIALLY filtered set moves for the search box and not for
+the facet, so it looks correct in the first test you run.
+
+**A count the facet already states is a different defect on the same strip** — the chips carry
+counts, so repeating them as summary items is one number in two places, free to disagree. Keep
+the aggregates no control states: the money, the extreme, the ratio.
+
+**Source-side signature:** an aggregate reading the query result (`q.rows`, `data`, the fetch
+hook's array) where the register renders a filtered derivative of it — and the two sitting far
+apart in the file, which is what lets them drift.
+
+→ [composition.md](./composition.md) §"Register / list" — the rule this measures is already
+written there; this probe exists because reading it is not the same as obeying it.
+
+### 8g. 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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "46.12.0",
+  "version": "46.14.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/popover.tsx

@@ -20,6 +20,9 @@ import {
   hasModalLayerAbove,
   isInLayerAbove,
   snapshotOpenModalLayers,
+  shouldDismissOnClick,
+  takePointerOrigin,
+  trackPointerOrigin,
 } from "./popover_layers";
 import { PopoverNavContext, type PopoverNavContextValue } from "./popover_nav";
 import { useLoticsLocale } from "./locale";
@@ -403,16 +406,28 @@ export function PopoverContent(props: PopoverContentProps) {
   // filter popover, or a file-preview Modal / Alert opened from within — those are
   // interactions WITH the popover's own flow, not a move away from it. The bottom
   // sheet (`small`) is modal and dismisses via its scrim, so it opts out here.
+  // Gắn một lần cho cả trang, KHÔNG chờ popover mở: cú pointerdown cần nhớ chính
+  // là cú mở popover ra.
+  useEffect(() => trackPointerOrigin(), []);
+
   useEffect(() => {
     if (!open || small) return;
     const onOutsideClick = (e: MouseEvent) => {
-      const node = e.target instanceof Node ? e.target : null;
-      if (!node) return;
-      if (popoverRef.current?.contains(node)) return; // inside my content
-      if (triggerRef.current?.contains(node)) return; // on my trigger — its own press toggles
-      const myLevel = Number(popoverRef.current?.getAttribute("data-popover-level") ?? "0");
-      if (isInLayerAbove(node, myLevel, modalsAtOpenRef.current)) return;
-      onOpenChange(false);
+      if (
+        shouldDismissOnClick({
+          clickTarget: e.target instanceof Node ? e.target : null,
+          // Where the gesture BEGAN. A `click` is dispatched to the common
+          // ancestor of the mousedown and mouseup elements, so a press on the
+          // trigger released over the panel targets NEITHER of them.
+          gestureOrigin: takePointerOrigin(),
+          popover: popoverRef.current,
+          trigger: triggerRef.current,
+          popoverLevel: Number(popoverRef.current?.getAttribute("data-popover-level") ?? "0"),
+          modalsAtOpen: modalsAtOpenRef.current,
+        })
+      ) {
+        onOpenChange(false);
+      }
     };
     document.addEventListener("click", onOutsideClick, true);
     return () => document.removeEventListener("click", onOutsideClick, true);

package/src/popover_layers.ts

@@ -55,3 +55,73 @@ export function hasModalLayerAbove(
   }
   return false;
 }
+
+/**
+ * The element the current pointer gesture STARTED on.
+ *
+ * A popover opens on the pointerdown of the gesture we later have to judge, so a
+ * listener installed once the popover is open has already missed it. One
+ * document-level listener, installed on first use and never removed, is enough
+ * for every popover on the page — and cheaper than one listener per instance.
+ *
+ * Non-DOM hosts (React Native) never install it and always read null, which
+ * degrades to judging a click on its own target — the behaviour before this
+ * existed.
+ */
+let lastPointerDownTarget: Node | null = null;
+let tracking = false;
+
+export function trackPointerOrigin(): void {
+  if (tracking || typeof document === "undefined") return;
+  tracking = true;
+  document.addEventListener(
+    "pointerdown",
+    (e) => {
+      lastPointerDownTarget = e.target instanceof Node ? e.target : null;
+    },
+    true,
+  );
+}
+
+/** Reads the origin and CONSUMES it: one pointerdown feeds one click, so a
+ *  keyboard-driven click that follows sees null and is judged on its own
+ *  target rather than inheriting an unrelated earlier gesture. */
+export function takePointerOrigin(): Node | null {
+  const origin = lastPointerDownTarget;
+  lastPointerDownTarget = null;
+  return origin;
+}
+
+/**
+ * Should an ambient click dismiss this popover?
+ *
+ * The subtlety is `clickTarget`. A browser fires `click` at the nearest COMMON
+ * ANCESTOR of the mousedown and mouseup elements — so a gesture that presses the
+ * trigger and releases over the popover (which opened on pointerdown, under the
+ * cursor) produces a click on neither of them. Judged on that target alone the
+ * popover dismisses itself on the very gesture that opened it, and only when the
+ * two happen to overlap: press where the panel will NOT appear and it behaves,
+ * which is why this reads as intermittent rather than broken.
+ *
+ * So the gesture's ORIGIN counts too. `gestureOrigin` is the last pointerdown
+ * target; pass null for a click with no pointer behind it (a keyboard Enter),
+ * and it falls back to the click target alone.
+ */
+export function shouldDismissOnClick(args: {
+  clickTarget: Node | null;
+  gestureOrigin: Node | null;
+  popover: Element | null;
+  trigger: Element | null;
+  popoverLevel: number;
+  modalsAtOpen: ReadonlySet<Element> | null;
+}): boolean {
+  const { clickTarget, gestureOrigin, popover, trigger, popoverLevel, modalsAtOpen } = args;
+  if (!clickTarget) return false;
+  const mine = (node: Node | null): boolean => {
+    if (!node) return false;
+    if (popover?.contains(node)) return true;
+    if (trigger?.contains(node)) return true;
+    return isInLayerAbove(node, popoverLevel, modalsAtOpen);
+  };
+  return !mine(clickTarget) && !mine(gestureOrigin);
+}

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