@lotics/ui 44.10.0 → 44.10.1

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/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.1",
   "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}`}