@lotics/ui 43.5.0 → 43.6.0

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), `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 — canvas + content column, heading altitude (incl. eyebrow vs group lead — a label is one or the other), 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), **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 — canvas + content column, heading altitude (incl. eyebrow vs group lead — a label is one or the other), 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 pair on ONE ROW starts at the SAME rung, a register's subject is `sm` over `xs` with values `sm`, and the subject leads by WEIGHT and its identity mark rather than by size), **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. |

package/docs/composition.md

@@ -1165,6 +1165,21 @@ wider pair then reads as though its second line shrank rather than stepped. Pick
 relative to the primary and the pair scales together. The probe: collect every primary/supporting
 pair on the screen and divide. A spread in the RATIOS is the finding, not a spread in the sizes.
 
+**And every pair ON ONE ROW sits at the SAME rungs — a register's row subject is `sm`, its
+supporting line `xs`, and a value in any other column is `sm` too.** "One rung below" is only half
+a rule: it constrains the STEP and says nothing about where the pair starts, so a subject placed a
+rung high stays compliant while dragging its whole column above the rest. Measured on a register
+that read as disproportionate: the identity column ran 16/14 while the column beside it ran 14/12
+— both correctly "one rung apart", one whole rung out of step with each other, and the first column
+shouted while everything else receded.
+
+**The subject leads by WEIGHT and by its identity mark, not by size.** `medium` against `regular`,
+plus the avatar or tile that answers "which row is this", is enough — and it is what
+`tpl_item_list` does. Money is the case that most often argues for a size step and should not get
+one: tabular figures and right alignment already mark it, and a lone larger value on a row reads as
+a mistake rather than as emphasis. One larger thing among peers is not emphasis; it is the thing
+that looks broken.
+
 **A CONTROL riding a text line must not resize that line.** A control is taller than the text it
 sits beside — a 24px `CopyButton` on an 18px `xs` line — so a flex row containing both is sized by
 the CONTROL, and `alignItems: "center"` then spends the difference above the text. The line's text

package/package.json

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

package/src/markdown.css

@@ -8,7 +8,7 @@
      carried before, written as an em so it scales with the rung instead of being
      a flat pixel value that drifts at every other size — and now ONE number
      shared with `Text` and the inputs rather than markdown's private one. */
-  letter-spacing: -0.028em;
+  letter-spacing: -0.006em;
   color: rgba(24, 24, 27, 1);
 }
 

package/src/metric.tsx

@@ -1,6 +1,7 @@
 import { View, StyleSheet, type TextStyle } from "react-native";
 import { Text } from "./text";
 import { colors } from "./colors";
+import { getTextColor } from "./text_utils";
 import { formatCompactNumber, formatMoney } from "./format_money";
 import { useMemo } from "react";
 
@@ -46,11 +47,6 @@ const TREND_UP = "↑";
 const TREND_DOWN = "↓";
 const TREND_FLAT = "→";
 
-const TONE_COLOR: Record<Exclude<MetricTone, "default">, string> = {
-  warning: colors.amber[600],
-  danger: colors.red[600],
-};
-
 export function Metric(props: MetricProps) {
   const {
     value,
@@ -107,7 +103,17 @@ export function Metric(props: MetricProps) {
           // none. (Tabular figures do not need it reset either — letter-spacing
           // adds a constant to every advance, so a tabular column stays aligned.)
           { fontVariantNumeric: "tabular-nums" } as TextStyle,
-          tone === "default" ? undefined : { color: TONE_COLOR[tone] },
+          // THE VALENCE INK COMES FROM `Text`, not a second map here. This kept
+          // its own — amber-600 and red-600 — while `getTextColor` answers
+          // amber-700 and red-900 for the same two words, so one `tone="warning"`
+          // rendered two different ambers depending on whether the number was a
+          // `Metric` or the sentence beside it.
+          //
+          // And the divergence was not cosmetic: amber-600 measures 3.19:1 on
+          // white, under the 4.5:1 AA floor for normal text, which is exactly
+          // what `getTextColor`'s own comment says the 700 rung exists to clear.
+          // A summary figure is the smallest, most glanced-at text on a register.
+          tone === "default" ? undefined : { color: getTextColor(tone) },
         ]}
       >
         {displayValue}

package/src/table.tsx

@@ -379,9 +379,19 @@ export type TableRowProps = {
    *  before `trailing`; stacked mode: the content's bottom line, right-aligned — an action
    *  reads at content scale, not as row chrome. Reserve Table `trailing` for it. */
   action?: ReactNode;
-  /** Min row height (register mode; stacked rows size to their content).
-   *  Defaults to the Table's rhythm — 52 `ruled`, 72 `airy` — so one prop on the
-   *  Table changes the whole register and no caller has to restate the beat. */
+  /**
+   * Min row height — a FLOOR, not a fixed height: a taller cell grows the row,
+   * so a two-line identity cell or a figure with a bar under it needs no
+   * override to fit. (Stacked rows size to their content and ignore this.)
+   *
+   * Defaults to `ROW_HEIGHT` (72), the register's rhythm. **Reach for this only
+   * when a surface genuinely needs more DENSITY than the beat** — and know that
+   * a number written against an older default silently becomes a shrink: an app
+   * carrying `minHeight={64}` from when the default was 52 now pulls that one
+   * register below every other on the screen, and it reads as cramped rather
+   * than as dense. If the reason you overrode it was "the content did not fit",
+   * delete the override.
+   */
   minHeight?: number;
   /**
    * The row's detail, revealed BENEATH it when `expanded` — the alternative to

package/src/text.css

@@ -46,39 +46,39 @@
 [data-text-size="xs"] {
   font-size: 12px;
   line-height: 18px;
-  letter-spacing: -0.02em;
+  letter-spacing: 0em;
 }
 [data-text-size="sm"] {
   font-size: 14px;
   line-height: 24px;
-  letter-spacing: -0.028em;
+  letter-spacing: -0.006em;
 }
 [data-text-size="md"] {
   font-size: 16px;
   line-height: 26px;
-  letter-spacing: -0.03em;
+  letter-spacing: -0.011em;
 }
 [data-text-size="lg"] {
   font-size: 18px;
   line-height: 28px;
-  letter-spacing: -0.032em;
+  letter-spacing: -0.014em;
 }
 /* Display ramp — the heading ladder: xl = `##` (section), xxl = `#`
    (page/record title), xxxl = hero numbers. */
 [data-text-size="xl"] {
   font-size: 22px;
   line-height: 28px;
-  letter-spacing: -0.035em;
+  letter-spacing: -0.018em;
 }
 [data-text-size="xxl"] {
   font-size: 28px;
   line-height: 34px;
-  letter-spacing: -0.038em;
+  letter-spacing: -0.021em;
 }
 [data-text-size="xxxl"] {
   font-size: 32px;
   line-height: 38px;
-  letter-spacing: -0.04em;
+  letter-spacing: -0.022em;
 }
 
 /* Refer to `use_screen_size` for breakpoints */

package/src/text_utils.ts

@@ -53,24 +53,22 @@ export function getTextColor(color?: TextColor): string {
 export { fontFamilyRegular, fontFamilyMedium, fontFamilySemiBold } from "./font_family";
 
 /**
- * Tracking for input text — the BODY rung of the curve in `text.css` (-0.028em),
- * in px because React Native's `letterSpacing` has no em unit. -0.4 IS that rung
- * at 14px; the ramp was anchored on this value rather than the other way round.
+ * Tracking for input text — the `sm` rung of Inter's curve (`TYPE_TRACKING.sm`,
+ * -0.006em) as px, because React Native's `letterSpacing` has no em unit.
  *
- * Six inputs each hard-coded it separately before this. The number did not
- * change; what changed is that there is now one of it, next to the line height,
- * because they are the same contract — an input is running text and sits at the
- * body rhythm on both axes.
+ * Six inputs each hard-coded their own value before this; there is one of it now,
+ * next to the line height, because they are the same contract — an input is
+ * running text and sits at the body rhythm on both axes.
  *
  * NOT derived, deliberately, unlike the line heights beside it. An input is 14px
  * on desktop and 16px on mobile, so no single px value is the em at both sizes —
  * computing one from a rung would pick a size and call the result exact. Written
- * out, it stays honestly an approximation: right at 14px, a hair light at 16px
- * (-0.4 against -0.45). `type_ramp.test.ts` pins it to within a hundredth of the
- * `sm` rung so it cannot drift away from the curve it belongs to; the exact form
- * (an `em` string through RN's style types) is not portable.
+ * out, it stays honestly an approximation: right at 14px, a hair light at 16px.
+ * `type_ramp.test.ts` pins it to within a hundredth of the `sm` rung so it cannot
+ * drift away from the curve it belongs to; the exact form (an `em` string through
+ * RN's style types) is not portable.
  */
-export const INPUT_LETTER_SPACING = -0.4;
+export const INPUT_LETTER_SPACING = -0.08;
 
 /**
  * Line height for mobile web — the input is 16px there (to defeat iOS-Safari

package/src/type_ramp.ts

@@ -24,18 +24,9 @@
  * every label, value and control gained about 4px of line box. Density was
  * traded for rhythm.
  *
- * TRACKING: negative throughout, steepening as the type grows. The body rung is
- * ANCHORED on -0.028em — the -0.4px this product already set on `.ui-markdown`
- * and on its inputs, expressed as an em so it scales. That value is the
- * product's own, arrived at by reading it in Vietnamese every day, and the rest
- * of the ramp is derived FROM it rather than imported from another design
- * system. Inter is drawn generously at default tracking, so untracked body reads
- * loose beside it, and what looks right at 14px looks slack at 32px.
- *
- * `xs` is the one rung held back (-0.02em rather than the full body value). 12px
- * is where Vietnamese stacked diacritics (ự, ộ, ế, ệ) and Inter's `1`/`l`/`i`
- * come closest to colliding, and tightening is the direction that makes both
- * worse.
+ * TRACKING: Inter's own dynamic-metrics curve, evaluated per rung — see
+ * `TYPE_TRACKING`. Near zero at 12px and steepening as the type grows, which is
+ * the shape the face is drawn for. It is derived, not chosen.
  *
  * Tracking is stated ONCE, in em, and is not repeated per breakpoint: an em
  * scales with the font size, so the same value is correct at both. Only the
@@ -75,15 +66,37 @@ export const TYPE_RAMP_DESKTOP = {
   xxxl: { size: 48, leading: 52 },
 } as const satisfies Record<keyof typeof TYPE_RAMP_MOBILE, TypeRung>;
 
-/** Tracking per rung, in em. Negative at every rung — see the header. */
+/**
+ * Tracking per rung, in em — INTER'S OWN dynamic metrics, not a house curve.
+ *
+ * Inter publishes the tracking it is drawn for as a function of size:
+ *
+ *     tracking(z) = a + b · e^(c · z)      a = -0.0223, b = 0.185, c = -0.1745
+ *
+ * evaluated at each rung's base size and rounded to a thousandth. The values
+ * below ARE that function; they are not tuned by eye and should not be. If a
+ * screen reads too tight or too loose, the answer is a size or a leading change,
+ * not a nudge here — the typeface's designer has already answered this question
+ * for this typeface, and second-guessing it per-rung is how a ramp ends up with
+ * seven independent opinions.
+ *
+ * The shape: near zero at 12px, steepening as the type grows, asymptotic to the
+ * -0.0223 the face is drawn to at display sizes. `xs` lands at 0.000, which is
+ * also the right answer for Vietnamese stacked diacritics (ự, ộ, ế, ệ) and for
+ * Inter's `1`/`l`/`i` at 12px — the sizes where tightening does the most damage
+ * are exactly the ones the curve leaves alone.
+ *
+ * One value per rung, not per breakpoint: an em already scales with the font
+ * size, and the curve's difference across a rung's two sizes is under 0.002em.
+ */
 export const TYPE_TRACKING = {
-  xs: -0.02,
-  sm: -0.028,
-  md: -0.03,
-  lg: -0.032,
-  xl: -0.035,
-  xxl: -0.038,
-  xxxl: -0.04,
+  xs: 0.000,
+  sm: -0.006,
+  md: -0.011,
+  lg: -0.014,
+  xl: -0.018,
+  xxl: -0.021,
+  xxxl: -0.022,
 } as const satisfies Record<keyof typeof TYPE_RAMP_MOBILE, number>;
 
 /** The rungs, in ladder order. `TextSize` in `text.tsx` is this set. */