@lotics/ui 44.10.2 → 44.11.0

package/AGENTS.md

@@ -15,9 +15,9 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 | Doc | Read it for |
 |---|---|
 | [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) | **a picker over a select field keeps the field's colours** (`optionPicker` — the hand-rolled `map` to `{value,label}` drops `color`, so a value reads coloured in a register and grey in the editor); Which editing pattern for which job — inline edit, fieldset forms, browser-autofill suppression (search controls only), find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (`InlineFiles` for a record ROW — list + one CTA, `multiple` decides add-vs-replace; the `FilesEditor` COMPOUND for a whole section — root owns selection/gallery/confirm, you compose the bar, a HOST verb reads `useFilesEditorSelection` — plus the three-way file INTAKE: CTA + `FileDropTarget` + `usePasteFiles`), stage gates, whether a multiline value keeps its fixed reserve or `autoGrow`s (who decides the length — the field, or whoever is typing), the commit-on-blur vs action-press ordering law (the kit gates the press — `pending_commits`). |
+| [docs/data_entry.md](./docs/data_entry.md) | **a picker over a select field keeps the field's colours** (`optionPicker` — the hand-rolled `map` to `{value,label}` drops `color`, so a value reads coloured in a register and grey in the editor); Which editing pattern for which job — inline edit, fieldset forms, choosing a CHOICE control by option count (and why "no selection" is a PLACEHOLDER, never an option valued `""` — the picker reads that as nothing chosen and renders down to its chevron), browser-autofill suppression (search controls only), find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (`InlineFiles` for a record ROW — list + one CTA, `multiple` decides add-vs-replace; the `FilesEditor` COMPOUND for a whole section — root owns selection/gallery/confirm, you compose the bar, a HOST verb reads `useFilesEditorSelection` — plus the three-way file INTAKE: CTA + `FileDropTarget` + `usePasteFiles`), stage gates, whether a multiline value keeps its fixed reserve or `autoGrow`s (who decides the length — the field, or whoever is typing), the commit-on-blur vs action-press ordering law (the kit gates the press — `pending_commits`). |
 | [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 (machine → a gate: a diff when something is being replaced, a full editable preview when records are being created from a document; human-typed → save-direct + the `ResultHeader` receipt), findings, provenance, confidence; **after the run** — a stored record that fills up from several writers (a person, a chat agent, an extraction, an automation) and remembers none of them: an unwritten value must not render like a written one, a machine's prose and a person's must not share a treatment, model markdown goes in `variant="embedded"`, and the read path must project every field the write paths set; the UI half of the SDK's [ai doc](../app-sdk/docs/ai.md), the whole run in a dialog (`AgentRunScope`/`AgentRunPane`/`AgentRunActions` — a parked question REPLACES the feed, actions in the footer, **Stop** while streaming), **stopping** (`cancel` stops the run, `abort` only stops listening — so closing a dialog must `cancel` or it keeps billing); **review surfaces compose from atoms** — `DiffValue` (a changed value, droppable in any cell/row/total), `DiffMark` (what happened to the row — ONE circular disc, every surface, its kind derived from before/after rather than a boolean "did this change" — an empty `before` is `added`, never `changed`), `useChangeSet` (accept/reject/undo bookkeeping, no layout) — see [MIGRATION.md](./MIGRATION.md) for the `ChangeReview` family they replace |
-| [docs/composition.md](./docs/composition.md) | The design-language contract — **the form comes before the treatment** (name what the subject IS — register, rail, board, timeline, deviation queue — before reaching for parts; a subject flattened into rows is well-typed and says nothing, and reuse-first is about not duplicating primitives, not about a screen's shape), canvas + content column, heading altitude (incl. eyebrow vs group lead — a label is one or the other, and a section heading's own row never wraps so a control label that repeats the title can squeeze the title+description into a narrow ribbon at phone width), banded cards, register vs inset rows (incl. the register laws a row centres its cells by: every cell a FIXED height, a pressable cell on the shared hover token, a column sized by what it carries), the button ladder and **what underlined text may mean** (it GOES somewhere or REVEALS something — never mutates; blue leaves the surface, muted stays on it, and the one in-prose disclosure exception is scoped there), master-detail `Drawer` on a LIST screen vs a child collection's row EXPANDING inside a record, view controls, RECORD EXTENT (one page, sections scrolled to and never routed to), **the register's rhythm** (no hairline between rows — their own height and the hover wash separate them; the register's one line is the band capping the columns, because that is the break whitespace cannot state. Density is `TableRow`'s `minHeight`, never a mode), **a register that TRIAGES** (`TableGroup` — titled bands ordered by what needs the reader now, grouped by what implies a different ACTION rather than by a category already in a column, and what the screen can CLASSIFY kept as a separate list from what it RENDERS, so a value omitted on purpose does not resurface under *Unclassified* and one added later does not vanish), **the register's own craft** (a column header treated as CHROME a step lighter than row metadata, sentence case in the table header too, and a supporting line one RUNG BELOW the line it supports rather than a fixed size — plus the half that rule was missing: every SUBJECT on one row starts at the same rung, the subject leads by WEIGHT and its identity mark rather than by size, and whether the supporting line drops a rung is decided by what else separates the pair; plus the two ways a `columns` array and a rendered row disagree — a partial `priority` annotation, and a conditional column whose cell was not hidden with it), **identity marks** (a mark that looks the same on every row carries nothing — `Avatar` derives its hue from the name and takes circle/square for person vs organization; the palette is ordered by contrast, not spectrum, and never paints a person red or amber), **where the accent goes** ("which of these" — a selected row, an active filter; never DATA and never the focus ring, while a page-scale position marker like an active TAB takes `primary`, the ink the kit already spends on "this is on"; and selection must not share a wash with hover), **theming is an app-level ESCAPE HATCH, not a product surface** (`applyLoticsTheme({ … })` once at boot, before `mount`, writing the `--lotics-*` roles on the document root; nothing in the platform writes a theme, and `apps.theme.color` is the launcher icon only — the five `var()` roles plus the three font rungs ARE the whole mechanism, and wrapping a component cannot replace them because RN-Web writes `fontFamily` per element and background/border do not inherit), color discipline, **typography** (the ramp is DATA in `type_ramp`, one table both platforms derive from; leading and tracking are baked per rung and a hand-set `letterSpacing` is always a second copy of the curve), whitespace, and how to TEST an overlay component (a `Popover`-backed surface never mounts under jsdom). |
+| [docs/composition.md](./docs/composition.md) | The design-language contract — **the form comes before the treatment** (name what the subject IS — register, rail, board, timeline, deviation queue — before reaching for parts; a subject flattened into rows is well-typed and says nothing, and reuse-first is about not duplicating primitives, not about a screen's shape; **a hierarchy in the DATA does not oblige one in the UI** — who MAINTAINS the structure decides, and a set the reader scans is a register whatever shape the data has), canvas + content column, heading altitude (incl. eyebrow vs group lead — a label is one or the other, and a section heading's own row never wraps so a control label that repeats the title can squeeze the title+description into a narrow ribbon at phone width), banded cards, register vs inset rows (incl. the register laws a row centres its cells by: every cell a FIXED height, a pressable cell on the shared hover token, a column sized by what it carries), the button ladder and **what underlined text may mean** (it GOES somewhere or REVEALS something — never mutates; blue leaves the surface, muted stays on it, and the one in-prose disclosure exception is scoped there), master-detail `Drawer` on a LIST screen vs a child collection's row EXPANDING inside a record, view controls, RECORD EXTENT (one page, sections scrolled to and never routed to), **the register's rhythm** (no hairline between rows — their own height and the hover wash separate them; the register's one line is the band capping the columns, because that is the break whitespace cannot state. Density is `TableRow`'s `minHeight`, never a mode), **a register that TRIAGES** (`TableGroup` — titled bands ordered by what needs the reader now, grouped by what implies a different ACTION rather than by a category already in a column, and what the screen can CLASSIFY kept as a separate list from what it RENDERS, so a value omitted on purpose does not resurface under *Unclassified* and one added later does not vanish), **the register's own craft** (a column header treated as CHROME a step lighter than row metadata, sentence case in the table header too, and a supporting line one RUNG BELOW the line it supports rather than a fixed size — plus the half that rule was missing: every SUBJECT on one row starts at the same rung, the subject leads by WEIGHT and its identity mark rather than by size, and whether the supporting line drops a rung is decided by what else separates the pair; plus the two ways a `columns` array and a rendered row disagree — a partial `priority` annotation, and a conditional column whose cell was not hidden with it), **identity marks** (a mark that looks the same on every row carries nothing — `Avatar` derives its hue from the name and takes circle/square for person vs organization; the palette is ordered by contrast, not spectrum, and never paints a person red or amber; a column of faces must not draw an UNBOUNDED audience as faces, and an overlapping stack separates with translucent INK rather than the surface colour, which a row's wash keeps changing out from under), **where the accent goes** ("which of these" — a selected row, an active filter; never DATA and never the focus ring, while a page-scale position marker like an active TAB takes `primary`, the ink the kit already spends on "this is on"; and selection must not share a wash with hover), **theming is an app-level ESCAPE HATCH, not a product surface** (`applyLoticsTheme({ … })` once at boot, before `mount`, writing the `--lotics-*` roles on the document root; nothing in the platform writes a theme, and `apps.theme.color` is the launcher icon only — the five `var()` roles plus the three font rungs ARE the whole mechanism, and wrapping a component cannot replace them because RN-Web writes `fontFamily` per element and background/border do not inherit), color discipline, **typography** (the ramp is DATA in `type_ramp`, one table both platforms derive from; leading and tracking are baked per rung and a hand-set `letterSpacing` is always a second copy of the curve), whitespace, **where a commit sits** (with its fields, never an overlay's footer — but a full-page editor is not a dialog, so a scrolling document keeps its commit pinned), and how to TEST an overlay component (a `Popover`-backed surface never mounts under jsdom). |
 | [docs/reviewing.md](./docs/reviewing.md) | **Reviewing a screen you built** — the other docs say what good looks like; this one says how to find out whether you achieved it, because "it looks fine" is the same claim as "it should work" made with the same evidence. Measure, never eyeball: render it, extract computed values, let the table show the defect. Two GATES that outrank every treatment question (**SUBTRACT** — what question does this element answer, and count FACTS not elements; **RIGHT CONTROL** — name the species before treating it), then 10 probes each naming what to COLLECT and the SIGNATURE in the numbers: type inventory (range, singletons, the label/value shrink war), ground+border+radius across siblings, what each RULE separates, gap RATIOS, the state diff (paint may change, geometry may not), alignment drift (incl. a centred child that moves while its container measures identical), the surface walk (open it, press it, read the settled string), the DATA probe (what is really in the table — incl. grepping rendered text for internal ids), the ABSENCE pass that catches "bland", and microcopy. Plus the extraction snippets, what measurement cannot see, and how to act on a finding (fix the CLASS, and never resolve one with "the docs say X"). |
 | [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. |
@@ -27,8 +27,9 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 - **Reuse first; the catalog can lag `src/`.** Before hand-rolling ANY capability, `ls src/` and
   grep for a match — a component in `src/` missing from the catalog is a doc bug to fix, not a
   license to hand-roll.
-- **One canonical component per data role** (member → `MemberChip`, who-is-this →
-  `MemberPeek`/`MemberProfileCard`, select → `OptionBadge`, files → `FilePreview` family, …) —
+- **One canonical component per data role** (member → `MemberChip`, SEVERAL of them →
+  `AvatarGroup`, who-is-this → `MemberPeek`/`MemberProfileCard`, select → `OptionBadge`,
+  files → `FilePreview` family, …) —
   the catalog's Reach-by-role outranks neighboring code.
 - **Responsive layout measures the CONTAINER, not the screen.** `useContainerSize()` reports the
   nearest `SizeBoundary`; wrap one around any region whose width stops tracking its parent's, and

package/docs/catalog.md

@@ -597,6 +597,14 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   and `avatar.web.tsx` implement. It lives in a third module because only one of them is ever
   compiled — `tsc` resolves `./avatar` to the native file while every browser loads the web one,
   so a prop declared on one side typechecks everywhere and silently does nothing in the browser.
+- **`label_tone`** — `labelTone(label)`: one stable `ColorName` per free-text label (a tag, a
+  topic, a category), for `Badge`. `avatarTone`'s sibling and the same discipline: pure and
+  NEVER STORED, so a set of labels can stay a `text[]` instead of earning a table the moment a
+  colour has to be chosen; `red` and `amber` excluded, because a palette that can paint an
+  arbitrary noun red makes every red on the screen ambiguous; hue-interleaved so two labels in
+  adjacent buckets still look different. Case- and space-folded, matching whatever normalizes the
+  set — two spellings of one label must not be two colours. Returns a NAME (not a hex like
+  `avatarTone`) because `Badge` owns the shade a dot is drawn at.
 - **`avatar_tone`** — `avatarTone(name)`: the initials ground, one stable hue per name, from a
   contrast-ordered palette that excludes `red` and `amber` (a person is not a warning). Pure and
   never stored, so one person is one colour on every screen. See composition.md §Identity marks.
@@ -606,6 +614,21 @@ 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`.
+- **`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.
+  `size` is the shared avatar scale with the same `md` default as `Avatar`/`MemberChip`, and the
+  marks, the overlap and the count's type all derive from it — no fixed pixels, so a stack at any
+  rung is the same object. Three rules it exists to carry: the caller passes only principals it
+  can NAME, so the overflow never counts a mark the reader sees is missing; a group is ONE mark
+  bearing the group's name, never its members' faces (expanding it states a membership the reader
+  may not be entitled to); and the separating hairline is **translucent ink, never the surface
+  colour** — a register row washes to `zinc[50]` on hover, `accent_wash` when open and
+  `zinc[200]` while pressed, so a ring painted the background is a halo in three of the four
+  states, while a dark edge darkens any ground (the trick `FileBadge` already uses). Marks
+  `announce` because they stand alone here. INERT — its home is a register row, and a row that
+  already presses must not hold a second destination (see `member_peek`). A single person →
+  `MemberChip`; a single group → `GroupAvatar`.
 - **`wave_avatar`** — `WaveAvatar`: decorative animated waveform avatar (voice/audit
   history); animates on web, renders a static fallback on native.
 - **`member_chip`** — `MemberChip`: avatar + name; the universal person render. `size` scales
@@ -916,7 +939,11 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   differs from the visible text is what breaks label-in-name.
 - **`select`** — `Select`: rich/custom-rendered, single/multi, select-all, chips via
   `renderSelected(item, { remove })` + `searchable` + `allowCustom` — the tag field is just
-  a multi Select; opens `OptionList`. Its trigger is `role="combobox"` (a `<div>`), never
+  a multi Select; opens `OptionList`. **Set `searchPlaceholder` whenever `allowCustom` is on**:
+  the create row only exists once there is a query, so on an untyped menu the placeholder is the
+  only always-visible place that can say a new value is allowed — a tag field reading "Search…"
+  tells the reader the vocabulary is closed. `customOptionLabel` names what the create row will
+  do, with the value in it. Its trigger is `role="combobox"` (a `<div>`), never
   `role="button"`: the chip box legitimately puts a remove button INSIDE the trigger, and a
   real `<button>` may not contain one. **Any trigger that renders caller-supplied content
   must not take `accessibilityRole="button"`** — react-native-web picks the element from the

package/docs/composition.md

@@ -18,6 +18,16 @@ should have been a rail is well-typed, well-spaced, correctly aligned and still
 order or progress, because a status column reports one word and leaves the reader to know which
 word comes after which.
 
+**A hierarchy in the DATA does not oblige a hierarchy in the UI.** A parent id, a materialized
+path, a folder column — each is a real structure, and none of them decides the screen's form. Ask
+what the reader DOES with the set: a population they walk (a chart of accounts, a bill of
+materials, a site → line → cell breakdown) is a tree or a drill; one they scan and search is a
+register, and the path becomes the row's supporting line rather than a place to travel to. The
+distinction is who maintains the structure. Where something else writes it — an importer, an
+integration, an agent — a drill-down makes the reader navigate a shape they did not choose and
+cannot see the whole of, while a flat register with the address on the row costs one line and
+loses nothing. Build the tree when walking it IS the task, not because the column exists.
+
 The pull toward a register is structural, not a lapse in taste: `Table`, `DetailRow`,
 `SummaryLine` and `Badge` are the most reachable things here, and they compose into something
 defensible for almost any data. That is exactly why the question has to be asked out loud. **Reuse
@@ -894,6 +904,12 @@ by what KIND of thing they are, so an avatar takes the same number rather than a
   `DialogFooter` default `align="end"`; `DrawerFooter` is right-aligned by construction. Primary
   at the right edge, secondary to its left. A confirm dialog (no fields) is all surface: its
   buttons ARE the dialog, and they belong in the footer.
+- **A full-page editor is not a dialog.** Where the body SCROLLS and one commit governs the whole
+  page, that commit stays pinned at the page's foot: there is no dialog for it to read as
+  belonging to, and inlining it makes a reader scroll a long document to the end to save an edit
+  made at the top. What the page's title row carries instead is the actions on the OBJECT — hand
+  it to the assistant, the overflow — so the pinned bar holds the commit alone and the two
+  clusters never compete for the same press.
 - **Empty result**: `<EmptyState message hint? icon? action?>` — never a bare muted Text.
 - **Inline status**: `<Callout tone="info|success|warning|error|neutral">` — compound (like
   Card): compose `CalloutTitle`/`CalloutText`/`CalloutActions` inside. `Callout` is INLINE;
@@ -1461,6 +1477,25 @@ correct.
   Only rows with genuinely no identity are exempt: a list of amounts, a log of events.
 - **The rung follows what the row is ABOUT**: `lg` where the entity is the row's subject, `md`
   where it is one field among columns (see `avatar_size`).
+- **A column of faces must not draw an UNBOUNDED audience as faces.** Where a cell answers "who
+  can reach this", the commonest state is often *everyone* — and three sampled avatars assert
+  something false about the one fact the column exists to be scanned for exceptions in. Draw the
+  unbounded grant as a mark that SAYS so, and people only where the set is genuinely enumerable;
+  cap the faces at a few and let the remainder be a `+N` — as the last mark IN the stack, since a
+  number trailing after the discs reads as a separate fact about the row. Drop anyone the row
+  already names in another column — the same person twice reads as two grants. A group is one
+  mark with the group's name, never its members' faces: expanding it states a membership the
+  reader may not be entitled to. And the faces stay INERT inside a pressable row, per
+  member_peek.tsx.
+- **An overlapping stack separates with translucent INK, never with the surface colour.** The
+  conventional facepile rings each mark in the page background so the discs read as distinct —
+  which binds the ring to a colour the row does not keep. A register row washes on hover, again
+  when it is the open record, and again while pressed, so a ring painted white is a halo in three
+  of the four states, and they are the states a reader is in when they are actually looking. 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. Use a `boxShadow`, not a
+  border — a border grows the box, and the stacked mark then measures wider than the identical
+  mark in the next column.
 
 The brand did not lose a home when the disc stopped carrying it — it moved to chrome, below.
 

package/docs/data_entry.md

@@ -392,6 +392,15 @@ neighbour, and variation in row WEIGHT reads as noise long before row COUNT does
 | More options, or long labels, or the value is set once and read after | **`InlineSelect`** | scales to any count; costs two presses (open, pick) and hides the alternatives until you do — put each option's gloss in `renderOptionContent`, where it is needed while CHOOSING rather than on every later read |
 | The choice IS the task — a wizard step, a short focused form | **`RadioPicker`** | full-width choices with their descriptions permanently visible. In a grid of many fields this is ~4 rows of height for one value; never use it as a row in a record's field table |
 
+**"No selection" is the PLACEHOLDER, never an option whose value is the empty string.** A picker
+reads `""` as *nothing chosen* — it is what its own clear affordance emits back through
+`onValueChange`, so the two readings cannot both hold. Model the unfiltered/unset state as an
+ABSENT value (`value={x ?? undefined}` + `placeholder`), and map an incoming `""` back to that
+absence at the call site. An `{ value: "", label: "All types" }` option instead leaves the control
+with no selection AND no placeholder, so the trigger renders down to its chevron — a filter that
+still works, sized at a few pixels, which reviews as a rendering glitch rather than a modelling
+error.
+
 **`SegmentedControl` is NOT a field control.** It belongs to the view-control vocabulary (a mode
 or parameter of the SAME view — see the composition grammar), and it fails as a value editor for
 two concrete reasons: it is a bounded TRACK, so in a value column that fills the row it either

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "44.10.2",
+  "version": "44.11.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -245,6 +245,8 @@
     "./tabs": "./src/tabs.tsx",
     "./segmented_control": "./src/segmented_control.tsx",
     "./auto_sizer": "./src/auto_sizer.tsx",
+    "./avatar_group": "./src/avatar_group.tsx",
+    "./label_tone": "./src/label_tone.ts",
     "./group_avatar": "./src/group_avatar.tsx",
     "./page_content": "./src/page_content.tsx",
     "./page_header": "./src/page_header.tsx",

package/src/avatar_group.tsx

@@ -0,0 +1,183 @@
+import { View, type StyleProp, type ViewStyle } from "react-native";
+import { Avatar } from "./avatar";
+import { GroupAvatar } from "./group_avatar";
+import { Text } from "./text";
+import { AVATAR_PX, AVATAR_TEXT, type AvatarSize } from "./avatar_size";
+import { colors } from "./colors";
+import { useLoticsLocale } from "./locale";
+
+/** 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
+ *  thing that tells a reader "this is a team, not a colleague". */
+export interface AvatarGroupPrincipal {
+  /** Stable identity — the React key. Never the display name: two colleagues
+   *  share a name far more often than they share an id. */
+  id: string;
+  name: string;
+  kind: "person" | "group";
+  /** A person's image; absent falls back to initials. Ignored for a group,
+   *  which has no likeness of its own. */
+  image?: string | null;
+}
+
+/** How many marks show before the rest become a count, when the caller does not
+ *  say. Three reads as "a few people"; past that the initials stop being
+ *  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,
+ * `accent_wash` 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.
+ *
+ * The rules that make this a component rather than a `.map()`, each of which a
+ * hand-rolled version gets wrong on its own:
+ *
+ * **It resolves before it caps.** A principal the caller could not name is
+ * dropped by the CALLER (pass only what you can name) — but the overflow is
+ * counted from what will actually render, so `+2` never counts a mark the
+ * reader can see is missing. Slicing first and rendering a blank for the
+ * unnameable ones is the bug this ordering exists to prevent.
+ *
+ * **A group is ONE mark bearing the group's NAME**, never its members' faces.
+ * Expanding a team into people states a membership the reader may not be
+ * entitled to, and turns one grant into several.
+ *
+ * **The marks OVERLAP, and the remainder is the last mark in the stack.** The
+ * set reads as one object rather than as N things that happen to be adjacent,
+ * and a `+2` trailing after the discs as loose text reads as a separate fact
+ * about the row instead of as the rest of this one. The first mark sits on top
+ * and each one after tucks beneath it, so scanning left to right crosses whole
+ * leading edges.
+ *
+ * **Every mark ANNOUNCES itself.** `Avatar` and `GroupAvatar` are decorative by
+ * default, because a mark usually sits beside the name in visible text and
+ * announcing both reads it twice. Here there is no name text anywhere — the
+ * marks ARE the content — so a decorative default would leave a screen reader
+ * with nothing but a `+2`.
+ *
+ * **It is INERT.** No peek, no press. Its home is a register row, and a row
+ * that already presses must not hold a second destination four pixels to the
+ * left (`member_peek.tsx` has the long version).
+ *
+ * Pure, like every mark in the family: pass resolved names and images in — this
+ * fetches nothing and knows no directory.
+ */
+export interface AvatarGroupProps {
+  principals: readonly AvatarGroupPrincipal[];
+  /** Marks shown before the remainder becomes `+N`. Default 3. */
+  max?: number;
+  /**
+   * A rung on the shared avatar scale — the SAME scale and the SAME default
+   * (`md`) as `Avatar`, `MemberChip` and `GroupAvatar`, because a set of people
+   * in one column is the same kind of thing as the one person in the next.
+   *
+   * Everything inside derives from it: the marks, how far they overlap, and the
+   * remainder's type. Nothing here is a fixed pixel, so a stack at `lg` is the
+   * same object as a stack at `sm` rather than a differently-proportioned one.
+   */
+  size?: AvatarSize;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}
+
+export function AvatarGroup(props: AvatarGroupProps) {
+  const { principals, max = DEFAULT_MAX, size = "md", style, testID } = props;
+  const locale = useLoticsLocale();
+
+  if (principals.length === 0) return null;
+
+  const shown = principals.slice(0, max);
+  const hidden = principals.length - shown.length;
+  const px = AVATAR_PX[size];
+  const overlap = Math.round(px * 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);
+
+  return (
+    <View testID={testID} style={[{ flexDirection: "row", alignItems: "center" }, style]}>
+      {shown.map((principal, index) => (
+        <View
+          key={principal.id}
+          style={{
+            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 and the
+            // REMAINDER ends up covering a person.
+            position: "relative",
+            zIndex: depth - index,
+            // The ring follows the mark's own silhouette — a square team mark
+            // ringed as a circle shows the ring cutting its corners off.
+            borderRadius: principal.kind === "group" ? px * 0.2 : px / 2,
+            boxShadow: MARK_RING,
+          }}
+        >
+          {principal.kind === "group" ? (
+            <GroupAvatar name={principal.name} size={size} announce />
+          ) : (
+            <Avatar
+              size={size}
+              name={principal.name}
+              announce
+              source={principal.image ? { uri: principal.image } : undefined}
+            />
+          )}
+        </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: px / 2,
+            // A ground of its own, and a NEUTRAL one: the remainder is the only
+            // mark in the stack that is not somebody, so it must not wear a
+            // colour the tone scale hands to people.
+            backgroundColor: colors.zinc["100"],
+            alignItems: "center",
+            justifyContent: "center",
+            boxShadow: MARK_RING,
+          }}
+        >
+          {/* The rung's own type — the same one initials take. A fixed size here
+              is how a stack ends up with a 14px count beside 12px initials. */}
+          <Text size={AVATAR_TEXT[size]} weight="medium" color="zinc-700" aria-hidden>
+            {`+${hidden}`}
+          </Text>
+        </View>
+      )}
+    </View>
+  );
+}

package/src/avatar_tone.ts

@@ -52,11 +52,20 @@ const IDENTITY_TONES: readonly string[] = [
  * The ground for `name`'s initials — stable for a given string, so one person
  * keeps one colour across every screen and every session.
  *
- * The hash MIXES rather than sums, which fixes ANAGRAMS specifically: a plain
- * character sum gives `Hai Dang` and `Dang Hai` the same disc, and reorderings
- * are common in names (family name first or last, with or without a middle
- * name). Multiplying by 31 per character makes position count; `|0` keeps it in
- * int32 so the result is identical on every engine.
+ * The hash MIXES rather than sums, which makes POSITION count: a plain character
+ * sum gives `Hai Dang` and `Dang Hai` the same disc, and reorderings are common
+ * in names (family name first or last, with or without a middle name).
+ * Multiplying by 31 per character separates most of them; `|0` keeps it in int32
+ * so the result is identical on every engine.
+ *
+ * It does NOT fix anagrams in general, and the claim used to read that it did.
+ * Swapping two adjacent characters changes the hash by a multiple of 30, and
+ * this palette has ten entries — 30 mod 10 is 0, so every two-character
+ * transposition still lands in the same bucket. Nothing is broken by that: ten
+ * buckets means one name pair in ten collides anyway, and the guarantee worth
+ * having is a SPREAD across a real roster, not distinctness per pair. Stated
+ * because a reader who believes the stronger claim will write a test asserting
+ * it, and the test will be wrong rather than the code.
  *
  * It is NOT what fixed the clustering seen on a real register — the sum was
  * already producing a healthy spread of buckets there, and the interleaved order

package/src/chip.tsx

@@ -2,7 +2,7 @@ import { Ref } from "react";
 import { IconButton } from "./icon_button";
 import { useLoticsLocale } from "./locale";
 import { PressableHighlight } from "./pressable_highlight";
-import { chipSurfaceStyle } from "./control_surface";
+import { chipSurfaceStyle, CONTROL_HEIGHT } from "./control_surface";
 import { StyleSheet, View } from "react-native";
 
 interface ChipProps {
@@ -18,6 +18,26 @@ interface ChipProps {
   ref?: Ref<View>;
 }
 
+/**
+ * The dismiss ✕ overlays the pill rather than sitting in its row, because the
+ * pill itself may be a `PressableHighlight` and a button cannot contain a
+ * button. That makes its geometry a function of the pill's HEIGHT, and it is
+ * derived from `CONTROL_HEIGHT` rather than written as four literals — a brief
+ * experiment with a shorter chip put a 36px button in a 28px pill and reserved
+ * 38px for it, which is what four independent magic numbers buy you.
+ */
+const DISMISS = (() => {
+  const iconBox = 28; // IconButton `md`
+  const wrapperPad = (CONTROL_HEIGHT - iconBox) / 2 - 2;
+  const box = iconBox + wrapperPad * 2;
+  const inset = (CONTROL_HEIGHT - box) / 2;
+  // `box + inset`, not `box + 2 * inset`: content must stop where the button
+  // STARTS. This reproduces the 38 that used to be hardcoded here, so no chip
+  // moves — the point of deriving it is that it follows `CONTROL_HEIGHT` if
+  // that ever changes, not that the number is new.
+  return { wrapperPad, inset, reservedRight: box + inset };
+})();
+
 export function Chip(props: ChipProps) {
   const { testID, children, onPress, accessibilityLabel, onDismiss, dismissTooltip, ref } = props;
   const labels = useLoticsLocale().chip;
@@ -31,15 +51,32 @@ export function Chip(props: ChipProps) {
           accessibilityRole="button"
           accessibilityLabel={accessibilityLabel}
           onPress={onPress}
-          style={(state) => [chipSurfaceStyle(state), styles.pillLayout, onDismiss && styles.pillWithDismiss]}
+          style={(state) => [
+            chipSurfaceStyle(state),
+            styles.pillLayout,
+            onDismiss && { paddingRight: DISMISS.reservedRight },
+          ]}
         >
           {children}
         </PressableHighlight>
       ) : (
-        <View style={[chipSurfaceStyle({}), styles.pillLayout, onDismiss && styles.pillWithDismiss]}>{children}</View>
+        <View
+          style={[
+            chipSurfaceStyle({}),
+            styles.pillLayout,
+            onDismiss && { paddingRight: DISMISS.reservedRight },
+          ]}
+        >
+          {children}
+        </View>
       )}
       {onDismiss && (
-        <View style={styles.dismissButton}>
+        <View
+          style={[
+            styles.dismissButton,
+            { top: DISMISS.inset, right: DISMISS.inset, padding: DISMISS.wrapperPad },
+          ]}
+        >
           <IconButton
             icon="x"
             tooltip={dismissTooltip}
@@ -62,14 +99,8 @@ const styles = StyleSheet.create({
     gap: 4,
     paddingHorizontal: 12,
   },
-  pillWithDismiss: {
-    paddingRight: 38,
-  },
   dismissButton: {
     position: "absolute",
-    top: 2,
-    right: 2,
-    padding: 4,
     borderRadius: 999,
     zIndex: 1,
   },

package/src/control_surface.ts

@@ -179,6 +179,13 @@ export function chipSurfaceStyle(
 ): ViewStyle {
   const selected = opts?.selected ?? false;
   return {
+    /**
+     * A chip is a CONTROL and takes the band's height, wherever it stands —
+     * including inside a `Select`'s chip box. The container is what adapts: the
+     * trigger sets `minHeight`, not `height`, and wraps its selection row, so a
+     * box of chips grows to seat them at full size rather than shrinking them
+     * to fit a single band.
+     */
     height: CONTROL_HEIGHT,
     justifyContent: "center",
     borderRadius: CONTROL_RADIUS,

package/src/file_badge.tsx

@@ -16,6 +16,19 @@ const MIME_MAP: Record<string, { label: string; color: string }> = {
   "application/x-zip-compressed": { label: "ZIP", color: "#a16207" },
   "application/vnd.openxmlformats-officedocument.wordprocessingml.document": { label: "DOCX", color: "#2563eb" },
   "application/msword": { label: "DOC", color: "#2563eb" },
+  // Text formats a document surface routinely holds — an HTML template, a
+  // markdown knowledge doc, a plain-text export. Without them each fell to the
+  // grey FILE default, which on a list where every row is one of these is a
+  // mark that looks the same on every row and therefore carries nothing.
+  "text/html": { label: "HTML", color: "#ea580c" },
+  "text/markdown": { label: "MD", color: "#0891b2" },
+  // An email MESSAGE, which is a kind of document a template produces and a
+  // mailbox exports. It is not `text/html`: an email carries recipients, a
+  // subject and a body, and badging one as HTML tells the reader it is a web
+  // page. The label is the extension, like every other entry here — the badge
+  // is 26px wide at 7px type, which fits four characters, not five.
+  "message/rfc822": { label: "EML", color: "#0d9488" },
+  "text/plain": { label: "TXT", color: "#71717a" },
   "image/png": { label: "PNG", color: "#7c3aed" },
   "image/jpeg": { label: "JPG", color: "#7c3aed" },
   "video/mp4": { label: "MP4", color: VIDEO_COLOR },

package/src/group_avatar.tsx

@@ -7,6 +7,15 @@ export interface GroupAvatarProps {
   name: string;
   /** A rung on the shared avatar scale. Default `md`. */
   size?: AvatarSize;
+  /**
+   * When true, the mark announces its `name` to assistive tech. Default false,
+   * and for the same reason `Avatar` defaults that way: a group mark almost
+   * always sits beside the group's name in visible text, and announcing both
+   * reads the team out twice. Pass it where the mark stands ALONE — an access
+   * column, a dense cell — because there the initials are all a screen reader
+   * would otherwise get, and "Su" is not the name of a team.
+   */
+  announce?: boolean;
 }
 
 /**
@@ -18,13 +27,21 @@ export interface GroupAvatarProps {
  * picker, a search result — read as the same kind of thing. A group left on a
  * single letter beside a person showing two was the tell that the two had
  * drifted apart.
+ *
+ * It also shares `Avatar`'s ACCESSIBILITY CONTRACT — decorative by default,
+ * naming itself under `announce`. Reading a person's mark and a group's mark
+ * must not differ in what they say any more than in how they look, and that
+ * includes when they say nothing.
  */
 export function GroupAvatar(props: GroupAvatarProps) {
-  const { name, size = "md" } = props;
+  const { name, size = "md", announce } = props;
   const px = AVATAR_PX[size];
 
   return (
     <View
+      accessible={announce}
+      accessibilityLabel={announce ? name : undefined}
+      aria-hidden={announce ? undefined : true}
       style={[
         styles.container,
         {
@@ -34,7 +51,7 @@ export function GroupAvatar(props: GroupAvatarProps) {
         },
       ]}
     >
-      <Text size={AVATAR_TEXT[size]} weight="medium">
+      <Text size={AVATAR_TEXT[size]} weight="medium" aria-hidden>
         {avatarInitials(name, size)}
       </Text>
     </View>

package/src/label_tone.ts

@@ -0,0 +1,67 @@
+import type { ColorName } from "./colors";
+
+/**
+ * THE LABEL PALETTE — the colour a free-text label (a tag, a category, a topic)
+ * is drawn in, derived from the label itself.
+ *
+ * The sibling of [`avatar_tone`](./avatar_tone.ts), and it exists for the same
+ * reason at a different scale: a column of labels rendered in one ink is a
+ * column you have to READ, while a column of coloured dots is one you can scan.
+ * Handing the hue to the string means a reader learns "the teal one is Vận
+ * hành" without being told, and learns it once across every screen.
+ *
+ * **Nothing is stored.** The colour is recomputed on every render on every
+ * client, and the only thing making one label one colour is that this function
+ * is pure. That property is what lets tags stay a `text[]` — the moment a
+ * colour had to be *chosen*, a tag would need a row to live in, and the join
+ * table it implies is the over-modelling the folder system already was.
+ * Reordering `LABEL_TONES` or editing the hash repaints every label.
+ *
+ * **`red` and `amber` are excluded, and that is the load-bearing part.** They
+ * mean danger and waiting everywhere else in this system. A palette that can
+ * paint an arbitrary noun red makes every red on the screen ambiguous, and the
+ * label that happens to hash there reads as urgent to a person who has never
+ * been told otherwise. `avatar_tone` excludes them for the same reason ("a
+ * person is not a warning"); a topic is not one either.
+ *
+ * **The order is interleaved, not spectral**, for the reason `avatar_tone`
+ * documents at length: listed by hue, six consecutive entries are six shades of
+ * the same purple, so two labels hashing to adjacent buckets come out looking
+ * identical. Adjacent indices here are far apart in hue.
+ *
+ * Returns a `ColorName` rather than a hex because its consumer is `Badge`,
+ * which owns the shade a dot is drawn at (`solid()`, the 500). `avatarTone`
+ * returns a hex instead because it grounds white text and therefore has to pick
+ * a per-family shade that clears AA — a real difference, not a missed
+ * abstraction.
+ */
+const LABEL_TONES: readonly ColorName[] = [
+  "blue",
+  "orange",
+  "violet",
+  "emerald",
+  "fuchsia",
+  "teal",
+  "indigo",
+  "pink",
+  "cyan",
+  "purple",
+];
+
+/**
+ * The colour for `label` — stable for a given string, so one tag keeps one
+ * colour across every screen and every session.
+ *
+ * The hash MIXES rather than sums (`h * 31 + c`), so anagrams and reorderings
+ * land in different buckets; `|0` keeps it int32 so every engine agrees.
+ *
+ * Case- and space-insensitive, which matters more here than for a name: the tag
+ * set folds `NOXH` and `noxh` to one label, so the two spellings must not come
+ * out as two colours in the window before a write normalizes them.
+ */
+export function labelTone(label: string): ColorName {
+  const s = label.trim().toLocaleLowerCase();
+  let h = 0;
+  for (let i = 0; i < s.length; i += 1) h = (h * 31 + s.charCodeAt(i)) | 0;
+  return LABEL_TONES[Math.abs(h) % LABEL_TONES.length];
+}

package/src/locale.tsx

@@ -149,7 +149,7 @@ export interface LoticsLocale {
   /** `Avatar`: the fallback name (initials + a11y label) shown when no `name`.
    *  `MemberChip` resolves the same blank through it, so a person with no name
    *  is called one thing on both. */
-  avatar: { unknown: string };
+  avatar: { unknown: string; more: (count: number) => string };
   /** `MemberProfileCard` + `MemberPeek`: the profile card's row labels, its
    *  "no groups" and departed notes, and the trigger's announced name. */
   memberProfile: Required<MemberProfileLabels>;
@@ -373,7 +373,7 @@ export const en: LoticsLocale = {
     download: "Download file",
     passwordProtected: "This file is password-protected and cannot be previewed",
   },
-  avatar: { unknown: "Unknown" },
+  avatar: { unknown: "Unknown", more: (count) => `${count} more` },
   memberProfile: {
     role: "Role",
     groups: "Groups",
@@ -560,7 +560,7 @@ export const vi: LoticsLocale = {
     passwordProtected: "Tệp có mật khẩu — không xem trước được",
   },
   mediaPlayer: { loadFailed: "Không tải được nội dung" },
-  avatar: { unknown: "Không rõ" },
+  avatar: { unknown: "Không rõ", more: (count) => `${count} người khác` },
   memberProfile: {
     role: "Vai trò",
     groups: "Nhóm",

package/src/select.tsx

@@ -33,6 +33,15 @@ export interface SelectProps<T extends string = string, MULTI extends boolean =
   allowCustom?: boolean;
   /** Label for the create row (default: `Add "<query>"`). */
   customOptionLabel?: (query: string) => string | null;
+  /**
+   * The search field's placeholder. Defaults to the locale's "Search…".
+   *
+   * Worth setting whenever `allowCustom` is on: the create row only appears
+   * once there is a query, so on an untyped menu the placeholder is the ONLY
+   * always-visible place that can say a new value is allowed at all. A tag
+   * field reading "Search…" tells a reader the vocabulary is closed.
+   */
+  searchPlaceholder?: string;
   style?: StyleProp<ViewStyle>;
   testID?: string;
   disabled?: boolean;
@@ -72,6 +81,7 @@ export function Select<T extends string, MULTI extends boolean = false, D = unkn
     getOptionDescription,
     searchable = false,
     allowCustom = false,
+    searchPlaceholder,
     customOptionLabel,
     includeEmptyOption,
     style,
@@ -140,7 +150,10 @@ export function Select<T extends string, MULTI extends boolean = false, D = unkn
           second scroll that also clips the autofocused search field's outset ring. */}
       <PopoverContent disableBodyScroll>
         <OptionList<T, MULTI, D>
-          search={{ mode: searchable || allowCustom ? "internal" : "none" }}
+          search={{
+            mode: searchable || allowCustom ? "internal" : "none",
+            placeholder: searchPlaceholder,
+          }}
           options={options}
           multi={multi}
           value={value}