@lotics/ui 44.10.0 → 44.10.2

package/AGENTS.md

@@ -17,7 +17,7 @@ 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) | **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/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), **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), **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), 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/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. |
@@ -51,7 +51,11 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 - **Annotate every droppable table column, or none.** A partial `priority` is the trap: an
   unannotated column sorts above the whole hand-written range, so one annotation makes every
   other column drop first, and one unannotated column among annotated ones goes first however
-  important it is. → [composition.md §The register's own craft](./docs/composition.md).
+  important it is. **A conditionally hidden column is the same family**: the `columns` entry and
+  the row's `TableCell` are two edits, dropping only the first leaves the body one cell longer
+  than the header and shifts every column after it under its neighbour's title — derive both from
+  one value so they cannot be edited apart. →
+  [composition.md §The register's own craft](./docs/composition.md).
 - **A section's ADD rides its heading row, right edge** — Add files, Add fee, New line: a
   `primary` `Button` beside `SectionHeadingTitle`, rendered empty or full. Under the rows it
   extends, the verb MOVES with the row count and vanishes off-screen on a long list; a heading is

package/MIGRATION.md

@@ -4,6 +4,79 @@ Breaking changes, newest first — normally per major, plus the rare minor that
 anyway (recorded under its exact version). The current contract lives in `AGENTS.md` + `docs/`;
 this file exists only to move an app from one release to the next.
 
+**`FileRow`'s `leading` slot is a SIBLING of the press door, not inside it.** No API change;
+a row with `onPress` now has a slightly smaller press target, excluding the leading mark.
+
+`trailing`'s own docstring already stated the rule — *"an independently-interactive SIBLING:
+never swallowed by the row press (a button never nests in the door button)"* — while `leading`
+recommended *"a selection checkbox"* and rendered inside the `Pressable`. So the documented
+usage produced an interactive control nested in a `button`: invalid ARIA, and one press with two
+owners, since ticking the box also opened the file. A slot the docs tell you to put a control in
+cannot be inside the control.
+
+## 44.9.3 — an option's description stops being erased, and a pivot's headers rejoin the ramp
+
+**`OptionList` no longer suppresses `getOptionDescription` when `renderOptionContent` is set.**
+The two are independent facts about an option — how its value renders, and a subtitle under it —
+and one was erasing the other. A caller who wanted both had one slot for two things, so they put
+the subtitle inside the custom render; `Select` and `InlineSelect` then reuse that render as the
+RESTING trigger display, which turned a gloss meant for the open menu into a two-line control on
+every read (measured at 55px against 40px for every other editor in the same table). Pass no
+`getOptionDescription` if you want no subtitle. The documented `renderSelected` →
+`renderOptionContent` → `label` fallback is unchanged; it was never the defect.
+
+**`Matrix`'s column headers are `sm` / `muted` / `medium`, matching `SortHeader`.** They were
+`xs` / regular — which composition.md already names as the failure: *"a column header is a LABEL
+at the body size… dropped to `xs` and lightened past `muted` it stops being legible and starts
+reading as a caption that lost its value."* A screen carrying both a `Table` and a `Matrix`
+rendered the same structural role two ways.
+
+## 44.9.3 — the rules probe could not see a rule
+
+**`docs/reviewing.md`'s probe 3 collector missed border-drawn rules and counted transparent
+spacers.** Docs only, no code change — but this is the method app authors run, so it shipped a
+blind spot: it selected on "thin and wide" with no paint check, which counts a zero-height flex
+spacer as a rule and misses a band drawn as a `borderBottom` on a full-height header row. A
+surface with a visible rule under its column headers therefore reported **zero**, and zero reads
+as a clean result rather than a blind probe.
+
+The snippet now requires actual paint, accepts a single-sided border on a box of any height,
+excludes four-sided boxes (a control's own edge is not a rule), reads the line's y from the border
+edge rather than the box origin, and reports what each rule SEPARATES — which is what probe 3
+actually asks.
+
+## 44.9.2 — a pivot's figures actually align, and a ledger row keeps its own name
+
+**`Matrix.Grid`'s cell stretches its figure instead of centring it, so 44.9.1's right-alignment
+actually applies.** A `Text` centred by its parent shrink-wraps, so the `align="right"` added in
+44.9.1 had nothing to align against and the value cells never moved — while the headers and totals,
+which are not centred, did. Measured on a real pivot as shipped in 44.9.1, figures in one column
+ended across a **47px** spread; with the cell stretched, **0**. `Matrix.Header`'s column cell also
+gains a 2px right padding, matching the inset the cell's own border imposes, so a header and the
+numbers beneath it end on one x rather than two pixels apart.
+
+**`Ledger` measures itself and `LedgerRow` stops rendering `meta` in a row too tight for it.**
+No API change; a narrow ledger simply shows fewer captions.
+
+44.9.1 made the caption yield to the label first, which was the right ORDER and not a floor:
+shrinking indefinitely still starves the identity. Measured at 375, a 30-character caption
+wanted 184px of a ~250px text budget and clipped anyway, ellipsising a 74px label at 71px. The
+row now drops the caption entirely below the width where a label, a caption and a figure can
+all be seated (`FLEX_MIN_WIDTH` for the identity, ~100 for the money column, ~80 before a
+caption stops being worth rendering).
+
+Measured across the three states in a 180px row, the label kept 31px, then 55px, then 74px of
+the 77 it needs.
+
+`Ledger` measures its own box via `onLayout`, the way `Table` / `DetailTable` / `Breakdown`
+already do — not the window, and once for the whole ledger rather than per row. A ledger in a
+narrow column on a wide screen is exactly the case a window-sized answer gets wrong. Two
+separate app authors had already worked around this by dropping `meta` at small widths in their
+own code; that is the component's job.
+
+`LedgerBasis` is unaffected — it stacks its caption UNDER the label, so the two never compete
+for one line.
+
 ## 44.9.1 — a pivot's figures align, and a ledger row stops losing its own name
 
 No API is removed and nothing fails to compile. Three renders change.
@@ -11,10 +84,16 @@ No API is removed and nothing fails to compile. Three renders change.
 **`Matrix` right-aligns its figures instead of centring them.** Every value, column
 header and total was `align="center"` while the cells also set `tabular` — and tabular
 figures exist so digits line up in a column, which centring throws away. Measured on a
-real pivot: centred, 24 figures painted across **14 distinct right edges**; right-aligned,
-**12** — exactly one per column. No `align` prop came with this: a matrix is one measure
-across two dimensions, so its cells cannot want different alignments, and a prop for a
-centred case nobody has is surface without a consumer.
+**This was only half the fix — see 44.9.2.** `Matrix.Grid`'s cell sets `alignItems: "center"`,
+which makes the figure inside SHRINK-WRAP, and `align="right"` on a box exactly as wide as its
+own glyphs does nothing. So this release right-aligned the headers and totals (which carry no
+such centring) and left the value cells centred — worse than either end state, since a figure
+could then sit up to 45px left of its own column header's right edge. The measurement quoted
+below counted distinct right edges across ALL figures rather than the spread WITHIN a column,
+which is why it read as an improvement. Measured on a real pivot: centred, 24 figures painted
+across 14 distinct right edges; right-aligned, 12. No `align` prop came with this: a matrix is
+one measure across two dimensions, so its cells cannot want different alignments, and a prop for
+a centred case nobody has is surface without a consumer.
 
 **`Matrix` row labels carry default ink, not `muted`.** A pivot whose rows are entities
 rendered every entity name a step quieter than the numbers about it, inverting how the

package/docs/composition.md

@@ -1284,6 +1284,18 @@ column is a sort wearing chrome: it spends a band per value to repeat the cell b
 - **Watch the ratio of headings to rows.** Four bands over ten rows is a lot of chrome for a
   little content, and the shape only pays off as the register grows. A register that will never
   hold more than a screenful is usually better flat.
+- **What the screen KNOWS and what it SHOWS are two lists, never one.** A register that bands on
+  an enumerated field usually also wants to omit some of that field's values — the settled ones,
+  the archived ones — and the tempting shortcut is to let the band list double as the vocabulary,
+  treating "matches no band" as "unrecognised". It breaks in both directions at once. The values
+  you deliberately left out now match nothing, so they resurface under whatever heading catches
+  the remainder — *Unclassified*, *Other* — which is louder than the bands they were removed from
+  and states something false about them. Fix that by treating "known" as "shown" instead, and a
+  value added to the field later silently disappears from the one screen that would have shown it.
+  Keep a set of values the screen can classify and a list of bands it renders: a value in the
+  first but not the second is omitted on purpose, and a value in neither gets a visible band,
+  because a register that quietly files what it does not understand is how a stale row stays
+  invisible. Both lists are ALLOWLISTS — `else` is where the second one goes wrong.
 
 Banding also changes what the COLUMNS have to carry, and the check is worth running afterwards: a
 column that exists to signal presence ("is there a next step?") is now stated by the band, so it
@@ -1325,6 +1337,16 @@ 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 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
+only the first: the header band loses a heading, the row still renders the cell, and from there
+every column right of the gap sits under its neighbour's title. Nothing is null, nothing throws,
+and both files read as correct on their own — the defect exists only in the pair. Derive both from
+one value (`const showX = …`, used for the `columns` filter AND passed to the row) so they cannot
+be edited apart. The signature when reviewing a render: the header has one fewer cell than the
+body, and the columns after the hidden one are shifted by exactly one slot.
+
 **A row's SUBJECT is `medium`, never semibold.** Semibold is the heading ladder's weight — `#`,
 `##`, `###` are all semibold — so a register whose row subjects are semibold renders its content
 at heading weight once per row, in the same font CUT as the page title (`Inter_600SemiBold` is a

package/docs/reviewing.md

@@ -187,7 +187,9 @@ rule behind it lives in the area doc named beside it; this file never restates o
 → [composition.md](./composition.md) §"Color discipline", §"Buttons & action labels", §"Every number is a door", §"Hover grammar".
 
 ### 3. Rules — ask what each one SEPARATES
-**Collect** every border/divider with weight, colour and width.
+**Collect** every border/divider with weight, colour and width — including the ones drawn as a
+border on a box of ordinary height, which is how a column band is usually painted. A collector that
+matches only thin boxes reports zero rules on a surface that has one, and zero reads as clean.
 
 The test is not how big the break is. A rule between two rows divides **like from like** —
 whitespace says that just as well, which is why a register can drop every internal rule and read
@@ -441,25 +443,59 @@ that has none, or a clean tally on a screen with an untracked component still on
 
 ### Separator beats — is the biggest boundary the widest?
 
+**A rule is a painted LINE, and it is drawn two ways.** Selecting "thin and wide" alone gets both
+halves wrong, and both wrongs are silent: a transparent zero-height flex spacer matches it and is
+counted, while a border on a box of ordinary height does not and is missed. The second is the one
+that bites — a component that draws its column band as a `borderBottom` on a full-height header row
+then reports **zero rules on a surface that visibly has one**, and a count of `0` reads as a clean
+result rather than a blind probe.
+
 ```js
 () => {
-  const rules = [...new Set([...document.querySelectorAll('div')]
-    .filter(e => { const r = e.getBoundingClientRect(); return r.height <= 1.5 && r.width > 200; })
-    .map(e => Math.round(e.getBoundingClientRect().y)))].sort((a, b) => a - b);
+  const CLEAR = v => !v || v === 'rgba(0, 0, 0, 0)' || v === 'transparent';
+  const lineOf = e => {
+    const r = e.getBoundingClientRect(), cs = getComputedStyle(e);
+    if (!(r.width > 200 && e.checkVisibility?.())) return null;
+    if (r.height <= 1.5) {                       // a hairline BOX
+      if (!CLEAR(cs.backgroundColor)) return { y: r.y, paint: cs.backgroundColor };
+      for (const s of ['Top', 'Bottom'])         // …or a hairline drawn as a border
+        if (parseFloat(cs[`border${s}Width`]) > 0 && !CLEAR(cs[`border${s}Color`]))
+          return { y: r.y, paint: cs[`border${s}Color`] };
+      return null;                               // painted nothing: a spacer, not a rule
+    }
+    const sides = ['Top', 'Bottom'].filter(s =>
+      parseFloat(cs[`border${s}Width`]) > 0 && !CLEAR(cs[`border${s}Color`]));
+    const boxed = ['Left', 'Right'].every(s =>
+      parseFloat(cs[`border${s}Width`]) > 0 && !CLEAR(cs[`border${s}Color`])) && sides.length === 2;
+    if (boxed || sides.length !== 1) return null; // a control's own edge is not a rule
+    // The LINE's y is the border's edge, never the box's origin.
+    return { y: sides[0] === 'Top' ? r.y : r.bottom, paint: cs[`border${sides[0]}Color`] };
+  };
+  const rules = [...document.querySelectorAll('div,hr')]
+    .map(lineOf).filter(Boolean)
+    .map(l => ({ y: Math.round(l.y), paint: l.paint }))
+    .sort((a, b) => a.y - b.y);
   const blocks = [...document.querySelectorAll('*')]
     .filter(e => e.children.length === 0 && e.textContent.trim())
-    .map(e => { const r = e.getBoundingClientRect(); return { y: Math.round(r.y), b: Math.round(r.bottom) }; });
-  return rules.map(y => ({
-    rule: y,
-    above: y - Math.max(...blocks.filter(o => o.b <= y).map(o => o.b), -Infinity),
-    below: Math.min(...blocks.filter(o => o.y >= y).map(o => o.y), Infinity) - y,
+    .map(e => { const r = e.getBoundingClientRect(); return { y: Math.round(r.y), b: Math.round(r.bottom), t: e.textContent.trim().slice(0, 24) }; });
+  return rules.map(({ y, paint }) => ({
+    rule: y, paint,
+    above: y - Math.max(...blocks.filter(o => o.b <= y + 1).map(o => o.b), -Infinity),
+    below: Math.min(...blocks.filter(o => o.y >= y - 1).map(o => o.y), Infinity) - y,
+    separates: [blocks.filter(o => o.b <= y + 1).sort((a, c) => c.b - a.b)[0]?.t,
+                blocks.filter(o => o.y >= y - 1).sort((a, c) => a.y - c.y)[0]?.t].join(' | '),
   }));
 }
 ```
 
+Read `separates` first — probe 3 asks what each rule DIVIDES, and a rule whose two neighbours are
+the same kind of thing is the one to delete however important the break feels.
+
 Unequal `above`/`below` on one rule, or a rule with a visibly tighter beat than its neighbours, is
-the finding. A hand-rolled `Divider` sitting in a parent's uniform `gap` next to a `SectionStack`
-is the usual cause.
+the other finding. A hand-rolled `Divider` sitting in a parent's uniform `gap` next to a
+`SectionStack` is the usual cause. Asymmetry is not automatically wrong: a rule that BELONGS to
+the element above it sits tight under it and loose before the next, and that gap is what says
+which side owns it — the finding is asymmetry nobody chose.
 
 ### Clipping, overflow, collision
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "44.10.0",
+  "version": "44.10.2",
   "type": "module",
   "exports": {
     "./vite": {

package/src/file_row.tsx

@@ -40,6 +40,14 @@ export interface FileRowProps {
    * Leading slot, BEFORE the badge — a `DiffMark` saying what happened to this
    * document, a selection checkbox, a status dot.
    *
+   * A SIBLING of the row's press door, like `trailing` — not inside it. It used
+   * to render within the `Pressable`, which made the documented checkbox an
+   * interactive control nested in a `button`: invalid ARIA, and two owners for
+   * one press, since ticking the box also opened the file. The cost of the fix
+   * is that the mark itself is no longer part of the door; that is the correct
+   * trade, because a slot the docs tell you to put a control in cannot be
+   * inside the control.
+   *
    * It sits outside the badge rather than on it because it must line up DOWN
    * the list: a mark drawn over a 30px badge moves with the badge's size, and
    * `sm` and `md` rows would stop agreeing. Give every row the same slot,
@@ -91,7 +99,6 @@ export function FileRow({
 
   const content = (
     <>
-      {leading}
       <FileBadge size={md ? 38 : 30} mimeType={mimeType} placeholder={placeholder} isTemplate={isTemplate} />
       <View style={styles.text}>
         <Text size="sm" weight="medium" numberOfLines={1}>
@@ -114,6 +121,7 @@ export function FileRow({
   if (!onPress) {
     return (
       <View style={[styles.row, md && styles.rowMd]}>
+        {leading}
         {content}
         {trailing}
       </View>
@@ -130,6 +138,7 @@ export function FileRow({
       ]}
       {...mouseProps}
     >
+      {leading}
       <Pressable
         onPress={onPress}
         {...focusProps}

package/src/ledger.tsx

@@ -1,4 +1,4 @@
-import { createContext, useContext, type ReactNode } from "react";
+import { createContext, useContext, useState, type ReactNode } from "react";
 import { StyleProp, StyleSheet, View, ViewStyle } from "react-native";
 import { colors } from "./colors";
 import { Divider } from "./divider";
@@ -31,8 +31,17 @@ import { Text } from "./text";
 //     <LedgerTotal label="Outstanding" value={due} tone="danger" zeroLabel="Paid in full" />
 //   </Ledger>
 
+/** Below this the row cannot seat a label, a caption and a figure at once.
+ *  Derived, not chosen: the identity needs a flex column's usable floor
+ *  (`FLEX_MIN_WIDTH`, 120), a money column runs ~100, and a caption is not worth
+ *  rendering under ~80 — plus the row's own gaps. Under that the caption is
+ *  taking room from the one string the reader needs. */
+const META_MIN_ROW_WIDTH = 320;
+
 interface LedgerContextValue {
   format: (n: number) => string;
+  /** The row is too tight to carry a caption as well — see `META_MIN_ROW_WIDTH`. */
+  dropMeta: boolean;
 }
 
 const LedgerContext = createContext<LedgerContextValue | null>(null);
@@ -61,9 +70,25 @@ export interface LedgerProps {
 
 export function Ledger(props: LedgerProps) {
   const { formatValue, children, style } = props;
+  // MEASURES ITSELF, like `Table`/`DetailTable`/`Breakdown` — not the window,
+  // and not per row. A ledger in a narrow column on a wide screen is the case a
+  // window-sized answer gets wrong, and one `onLayout` on the container serves
+  // every row in it.
+  //
+  // 0 until first layout, which reads as "not yet too narrow" — a caption that
+  // appears on the second frame is a far smaller wrong than one that flashes
+  // away, and a ledger wide enough to matter answers on that frame anyway.
+  const [width, setWidth] = useState(0);
   return (
-    <LedgerContext.Provider value={{ format: formatValue }}>
-      <View style={[styles.ledger, style]}>{children}</View>
+    <LedgerContext.Provider
+      value={{ format: formatValue, dropMeta: width > 0 && width < META_MIN_ROW_WIDTH }}
+    >
+      <View
+        style={[styles.ledger, style]}
+        onLayout={(e) => setWidth(e.nativeEvent.layout.width)}
+      >
+        {children}
+      </View>
     </LedgerContext.Provider>
   );
 }
@@ -230,13 +255,20 @@ export interface LedgerRowProps {
 export function LedgerRow(props: LedgerRowProps) {
   const { label, meta, value, tone = "default", peek, peekWidth = 300, reference, accessibilityLabel } = props;
   const rowDetails = useLoticsLocale().ledger.rowDetails;
-  const { format } = useLedger();
+  const { format, dropMeta } = useLedger();
+  // The caption goes entirely rather than shrinking to nothing. Yielding first
+  // (below) is the right ORDER but not a floor: measured at 375, a 30-character
+  // caption still wanted 184px of a ~250px text budget and clipped — and took
+  // the label down with it, ellipsising a 74px identity at 71px. Two separate
+  // authors had already worked around this by dropping `meta` at small widths
+  // in their own apps, which is the component's job.
+  const showMeta = meta != null && meta !== "" && !dropMeta;
   const content = (
     <>
       <Text size="sm" numberOfLines={1} style={styles.shrink}>
         {label}
       </Text>
-      {meta ? (
+      {showMeta ? (
         <Text size="xs" color="muted" numberOfLines={1} style={styles.yield}>
           {meta}
         </Text>

package/src/matrix.tsx

@@ -143,12 +143,12 @@ function MatrixHeader({ corner, totalLabel }: MatrixHeaderProps) {
         )}
       </View>
       {cols.map((c) => (
-        <Text key={c.key} size="xs" color="muted" align="right" numberOfLines={1} style={styles.colCell}>
+        <Text key={c.key} size="sm" color="muted" weight="medium" align="right" numberOfLines={1} style={styles.colCell}>
           {c.label}
         </Text>
       ))}
       {hasTotals ? (
-        <Text size="xs" color="muted" weight="medium" align="right" numberOfLines={1} style={[styles.totalCol, { width: totalColWidth }]}>
+        <Text size="sm" color="muted" weight="medium" align="right" numberOfLines={1} style={[styles.totalCol, { width: totalColWidth }]}>
           {resolvedTotalLabel}
         </Text>
       ) : null}
@@ -325,12 +325,23 @@ const styles = StyleSheet.create({
     height: 36,
     borderRadius: 4,
     borderWidth: 2,
-    alignItems: "center",
+    // STRETCH, not center. The figure inside sets `align="right"`, and a Text
+    // centred by its parent SHRINK-WRAPS — so it is exactly as wide as its own
+    // glyphs and has nothing to align against. Right-aligning the text while
+    // this said `center` therefore changed the headers and totals (which carry
+    // no such centring) and left the cells where they were, so a figure sat up
+    // to 45px left of its own column header's right edge. `justifyContent`
+    // still centres vertically: in a column-direction box that is the main
+    // axis, and only `alignItems` decides the horizontal.
+    alignItems: "stretch",
     justifyContent: "center",
   },
   colCell: {
     flex: 1,
     minWidth: 52,
+    // Matches the 2px the cell's own border insets its figure by, so a header
+    // and the numbers under it end on ONE x rather than two pixels apart.
+    paddingRight: 2,
   },
   totalCol: {
     paddingLeft: 4,

package/src/option_list.tsx

@@ -157,7 +157,21 @@ export function OptionList<T extends string, MULTI extends boolean = false, D =
             // description — is `MenuListItem`: the listbox row that GROWS. `MenuButton` is
             // the fixed-height single-line menu row, and stays that for plain options.
             return content || desc ? (
-              <MenuListItem key={`${row.kind}-${opt.value}`} {...shared} title={content ?? label} description={content ? undefined : desc} />
+              <MenuListItem
+                key={`${row.kind}-${opt.value}`}
+                {...shared}
+                title={content ?? label}
+                // A custom render and a description are INDEPENDENT facts about
+                // an option — how its value looks, and a subtitle under it — so
+                // one does not erase the other. Suppressing `desc` whenever
+                // `renderOptionContent` was set left a caller who wanted both
+                // with one slot for two things: they crammed the subtitle into
+                // the custom render, which `Select`/`InlineSelect` then reuse
+                // as the RESTING trigger display, so a gloss meant for the menu
+                // became a two-line control on every read. A caller who wants no
+                // subtitle passes no `getOptionDescription`.
+                description={desc}
+              />
             ) : (
               <MenuButton
                 key={`${row.kind}-${opt.value}`}