@lotics/ui 19.0.1 → 20.0.0

package/MIGRATION.md

@@ -4,6 +4,41 @@ 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.
 
+## v20 from 19.x
+
+**`@lotics/ui/section` is DELETED.** Two modules exported a `Section` — the layout grammar's
+card-less region (`section_heading`) and a standalone titled block with its own `title` string,
+`collapsible` flag and imperative `SectionHandlers.expand/collapse`. The second one predated both
+the fixed heading ramp and the `Accordion` family, so a collapsible section had a heading that
+could not take the ramp's rungs and a disclosure that could not be driven from state.
+
+A collapsible section is now the `Accordion` family with a heading rung composed inside it — one
+heading family and one disclosure across static and collapsible. Replace the imperative handle
+with the controlled `expanded`/`onToggle` pair (or `defaultExpanded` when nothing outside needs to
+drive it).
+
+```tsx
+// BEFORE
+const ref = useRef<SectionHandlers>(null);
+<Section ref={ref} icon="eye-off" title="Hidden fields" collapsible initialCollapsed>
+  {body}
+</Section>
+// …elsewhere: ref.current?.expand()
+
+// AFTER
+<Accordion expanded={open} onToggle={setOpen}>
+  <AccordionHeader>
+    <DialogSectionHeadingTitle icon="eye-off">Hidden fields</DialogSectionHeadingTitle>
+  </AccordionHeader>
+  <AccordionContent>{body}</AccordionContent>
+</Accordion>
+```
+
+Pick the heading rung by where the surface sits, exactly as for a static section:
+`SectionHeadingTitle` (`##`), `SubsectionHeadingTitle` (`###`), `DialogSectionHeadingTitle`
+(`####`). The last one gained `icon` and `description` in this release, so every rung of the ramp
+now carries the same slots.
+
 ## v19 from 18.x
 
 **`TaskFields` is DELETED, with `fieldsWidth`.** A task row was carrying a
@@ -44,8 +79,9 @@ Porting a row, cell by cell:
 - **Every cell becomes one `TaskSubRow`, and it needs a NAME.** The column header the cells
   never had is now the label — write what the value IS ("Due", "Assignee", "Completed on"), not
   what it does.
-- **Drop the wrapper `View`s and the widths.** A sub-row's label column sizes itself to that
-  ONE task's labels and its value takes the slack up to a field's width; nothing is passed in.
+- **Drop the wrapper `View`s and the per-cell widths.** The label column is the LIST's
+  (`TaskList labelWidth`, default `DETAIL_LABEL_WIDTH`) and the value takes the slack, so a row
+  passes no width at all — set `labelWidth` once on the list if the vocabulary needs more.
 - **Drop `variant="cell"`.** A cell variant is for a grid; a sub-row's value is a form-variant
   `Inline*` editor (the default) — the zinc-50 chip that says "editable".
 - **A row that needed SCANNABLE columns — the same four values compared down twenty rows — was

package/docs/catalog.md

@@ -150,7 +150,10 @@ Two columnar shapes, and the choice is about data size:
 `TrendChip` (delta), `Sparkline`, `BarChart` / `LineChart` / `PieChart` (the canonical SVG
 set — no recharts), `RingGauge`, `ProgressBar` (its `compact` prop = ONE row, track + a
 plain sm tabular count beside it — the cell/heading/peek-trigger meter; a caption floating
-above a tiny bar reads misaligned) / `StackedProgressBar` / `StepProgress`, `Breakdown` (a
+above a tiny bar reads misaligned. **The track clamps at 100%, the caption does not** — over
+its max it reads `2,100 / 2,000 · 105%`, because a meter that says "100%" when you are over
+tells the reader they are exactly at the limit. Numbers format in the reader's locale, so
+never hand-format the value you pass in) / `StackedProgressBar` / `StepProgress`, `Breakdown` (a
 stacked bar + ranked share rows, pressable to drill; `maxRows` folds the long tail behind a
 "Show N more" toggle — `labels` to localize — so several facet cards align to one height in
 a row), `Funnel` (a CONVERSION funnel — ordered stages as bars that NARROW; the step
@@ -172,6 +175,8 @@ to drill).
 gap-spaced region + `SectionHeading`/`SectionHeadingTitle`/`SectionHeadingMeta`; no body
 component — children are the body), `Subsection` (+ `SubsectionHeading`/
 `SubsectionHeadingTitle` — the named group INSIDE a section, `###` lg-semibold title),
+`DialogSectionHeadingTitle` (`####` md-semibold — the rung for a surface inside a DIALOG, whose
+`DialogHeaderTitle` already occupies lg; composes with the Subsection layout),
 `SectionStack` (the flat page's content column — owns the fixed 56px beat + hairline between
 top-level blocks), `SubsectionStack` (a section's `Subsection` groups — fixed 32px beat,
 space-only while the groups are SHORT, `divided` once they run long), `SectionCard`, `PageHeader` /
@@ -334,9 +339,11 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   hand-rolled plain DOM/CSS (nothing injects them automatically; `@lotics/ui` components
   don't need them).
 - **`spacing`** — the `SPACE` scale + `SpaceToken`.
-- **`control_surface`** — `CONTROL_HEIGHT` (40) · `CONTROL_RADIUS` (10) · `FOCUS_RING` ·
-  `HOVER_BORDER` · `CONTROL_TRANSITION` · `chipSurfaceStyle` — the shared control-surface
-  tokens.
+- **`control_surface`** — `CONTROL_HEIGHT` (40) · `CONTROL_RADIUS` (10) · `CONTROL_TEXT_INSET`
+  (9 — how far a control insets its OWN text: 1px border + 8px padding; anything that must line
+  up with a control's WORDS rather than its box carries it, and `TASK_TEXT_INSET` IS it) ·
+  `FOCUS_RING` · `HOVER_BORDER` · `CONTROL_TRANSITION` · `chipSurfaceStyle` — the shared
+  control-surface tokens.
 - **`fonts.css`** — the Inter sheet (400/500/600, served by absolute URL so it resolves on
   every origin an app runs from); the app entry imports it ONCE or every `Text` falls back
   to system fonts.
@@ -376,19 +383,17 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `warning`/`error` render as an ARIA `alert`) — wrapping form fields in an alert is wrong.
   The law: **content + fields → `Inset`; a message → `Callout`.**
 - **`section_heading`** — `Section` · `SectionHeading` · `SectionHeadingTitle` ·
-  `SectionHeadingMeta` · `Subsection` · `SubsectionHeading` · `SubsectionHeadingTitle` — the
+  `SectionHeadingMeta` · `Subsection` · `SubsectionHeading` · `SubsectionHeadingTitle` ·
+  `DialogSectionHeadingTitle` — the
   card-less twin of the Card family, compound, owns no margin; spacing via the Section gap
   (16, fixed), no body component. `SectionHeadingTitle` is ALWAYS `##` (xl semibold;
   `weight="medium"` opt-down only) + `info` for an ⓘ provenance popover after the title,
   same as `CardHeaderTitle.info`. `SubsectionHeadingTitle` is the `###` lg-semibold level-3
   title of a named group inside a section (same `info` ⓘ affordance as the section title) —
-  heading-row siblings ride its right edge; the
-  heading ramp is FIXED: `#` xxl / `##` xl / `###` lg, no size props.
-- **`section`** — a SECOND, standalone `Section`: a self-contained titled block
-  (`title`/`description`/`collapsible`/`icon`/`titleRight`, imperative
-  `SectionHandlers.expand/collapse`). **Warning:** two modules export a `Section` — the
-  layout grammar's card-less region is the one in `section_heading`; import from
-  `@lotics/ui/section` only when you specifically want this collapsible titled block.
+  heading-row siblings ride its right edge. `DialogSectionHeadingTitle` is the `####`
+  md-semibold rung with the SAME `icon`/`description`/`info` slots as the section title, so a
+  dialog surface loses only the type size, never an affordance. The heading ramp is FIXED:
+  `#` xxl / `##` xl / `###` lg / `####` md, no size props.
 - **`section_stack`** — `SectionStack` · `SubsectionStack` — stacks that own the
   between-block law, skipping null children: `SectionStack` = a fixed 56px beat + a hairline
   `Divider` between top-level blocks; `SubsectionStack` = a fixed 32px beat, space-only while
@@ -708,9 +713,12 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   wire both); invalid/cross-field STATE = a co-located `Callout`; **`flat`**
   on a flat-text value row (`InlineStatic`, plain `Text`) tucks the annotation up by the
   control band's slack so its gap matches a chip row's.
+  The three annotations are ONE anatomy shared with a task's `TaskSubRow` — same names, same
+  order, same alert semantics — because a record's field and a task's field are the same thing
+  on two surfaces.
   `DetailTable`: the compound parent of
-  a row STACK — `labelWidth` (default `DETAIL_LABEL_WIDTH`, 130 — the kit's label column, also
-  the floor a `TaskSubRow`'s label sizes from) / `trailingWidth` / `minHeight` (default 40, the
+  a row STACK — `labelWidth` (default `DETAIL_LABEL_WIDTH`, 130 — THE kit's label column, and
+  a `TaskList`'s default too) / `trailingWidth` / `minHeight` (default 40, the
   inline-control grid) declared ONCE + the 8px row gap; with `trailingWidth` every row
   reserves the trailing column so value cells share one width and trailing items align at
   one x, like a table. RESPONSIVE with no prop: it measures its own container (onLayout, not
@@ -793,9 +801,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   from a 5-item drawer checklist to a grouped desk board. `TaskList` owns geometry only: the two
   GUTTERS — `controlWidth` (the left one, that every title aligns on, and so the INDENT step) and
   `actionWidth` (the right one, that every ⋯ pins into; `0` on a list whose rows carry no
-  actions) — plus `density` (`comfortable` = a 44px minimum tap target, `dense` = 32 for a
-  pointer-driven register). Everything else is composed, and JSX order is screen order — nothing
-  inspects child types.
+  actions) — plus `labelWidth` (the column every `TaskSubRow` renders its NAME in; default
+  `DETAIL_LABEL_WIDTH`, 130) and `density` (`comfortable` = a 44px minimum tap target, `dense` =
+  32 for a pointer-driven register). All four are inherited by nested lists. Everything else is
+  composed, and JSX order is screen order — nothing inspects child types.
 
   `TaskStatus` takes the `CheckCircle` (omit `onChange` for a read-only ring; a PICKER list
   puts a `CheckboxInput` here and sets `controlWidth={24}`). `TaskTitle` takes the
@@ -805,7 +814,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `TASK_TEXT_INSET` is never needed and a long title that wraps keeps its first line beside the
   control. It spans the content box between the gutters, like every line hung beneath it.
   `TaskCaption` is the row's state IN WORDS on its own line under the title — a
-  sentence, never a field. `TaskActions` carries the row's ⋯ `ActionMenu`, pinned into the RIGHT
+  sentence about the ROW, never a field, and never a sentence about one FIELD (that is the
+  sub-row's own `description` / `warning` / `error`).
+  `TaskActions` carries the row's ⋯ `ActionMenu`, pinned into the RIGHT
   gutter on the first line (Delete lives BEHIND it, danger-styled and last, never a bare ✕).
   `TaskDetail` is a FREE-FORM block under the row on the title's text edge — a chart, a table, a
   form with its own submit — rendered only while open. The module also exports
@@ -822,23 +833,35 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   step inward per level. Declare `actionWidth={0}` when NO row in the list carries actions.
 
   **THE ROW CARRIES THE TITLE; THE FIELDS THE USER CAN SET ARE SUB-ROWS BENEATH IT.** One task's
-  own fields hang under it as **`TaskSubRow`** (`label` · the control · an optional muted
-  `description`), indented ONE step — the same step a nested `TaskList` takes, because belonging
-  is expressed by indentation and there is only one device for it. Label and value sit ADJACENT
-  so the eye pairs them, and the sub-rows of ONE task share a label column sized to THEIR OWN
-  labels: nothing is declared on the list and no width is passed in, so a name is never sized for
-  a field three tasks further down. The value takes the slack between a readable minimum and a
-  field's maximum — on a phone or in a narrow drawer it drops onto its own line under the label
-  rather than ellipsizing beside it. Pass a form-variant `Inline*` editor (the default), not
-  `variant="cell"`: a cell variant belongs to a grid.
+  own fields hang under it as **`TaskSubRow`** (`label` · the control · `description` /
+  `warning` / `error`), indented ONE step — the same step a nested `TaskList` takes, because
+  belonging is expressed by indentation and there is only one device for it. Label and value sit
+  ADJACENT so the eye pairs them. **The label column is the LIST's, not the row's** — one
+  `labelWidth` for every sub-row at every depth, exactly as `DetailTable labelWidth` is the
+  record's — so every value on the surface starts on ONE x. A name longer than the column WRAPS
+  inside it and its value does not move; a column each row sized to its own words is not a
+  column (it started a short label's value at one x and a long one's at another, and any
+  vocabulary with longer field names staggered nearly every row). The value takes the slack from
+  a readable minimum — on a phone or in a narrow drawer it drops onto its own line under the
+  label rather than ellipsizing beside it. Pass a form-variant `Inline*` editor (the default),
+  not `variant="cell"`: a cell variant belongs to a grid.
+
+  **A TASK'S FIELD ANNOTATES EXACTLY LIKE A RECORD'S FIELD.** `description` (persistent
+  guidance), `warning` (a consequence to weigh — amber, announced) and `error` (field-level
+  failure — danger, alert semantics) are the same three props with the same order and a11y as
+  `DetailRow`'s, from ONE shared implementation. A fault in a single field belongs ON that
+  field; `TaskCaption` is a sentence about the whole ROW, so demoting a field fault into one
+  says something different.
 
   **ANYTHING THAT NEEDS SCANNABLE COLUMNS IS A `Table`, NOT A `TaskList`.** The compound spent a
   version carrying a declared value column so cells would line up down the list; it aligned and
   it read worse — each field's name ended up a quarter of the surface from its control, sized for
   the widest value on the page. If the job is comparing the same four values across twenty rows,
   that is a table, and `Table`/`DataGrid` are built for it. A `DetailTable labelWidth={…}` inside
-  a `TaskDetail` is the other shape to avoid: it declares a grid whose label and control land at
-  two x positions matching nothing above them — a form pasted into a list.
+  a `TaskDetail` is the other shape to avoid: the list ALREADY has a label column, so a second
+  one lands its label and its value at two more x positions matching nothing above them — a form
+  pasted into a list. Fields belonging to the task are `TaskSubRow`s, which annotate the same way
+  a `DetailRow` does, so there is nothing left that a nested `DetailTable` can say.
 
   **A row's FIRST LINE is a BAND** — 44px `comfortable`, 32 `dense`. Both gutter controls centre
   in it and `TaskTitle` claims it, which is what keeps both columns of

package/docs/composition.md

@@ -53,12 +53,14 @@ restyle a heading level per-page.
   slots carry each section's count and CTA); a `Text size="sm" weight="semibold"` stand-in is only
   for small sub-groups. Do NOT wrap each section in its own `CardHeader`, do NOT hand-roll
   sm-semibold lead lines on a flat page, and NEVER use a bare eyebrow as a section title.
-
-  **Warning:** two different `Section` components ship. The compound one described here comes from
-  `@lotics/ui/section_heading` (alongside `SectionHeading`/`SectionHeadingTitle`/
-  `SectionHeadingMeta`/`Subsection`/…). `@lotics/ui/section` exports a LEGACY collapsible
-  `Section` with a `title` string prop — a different component. Import from `section_heading` for
-  the grammar described here.
+- **Dialog section title** — the FOURTH rung, for a surface hosted in a dialog:
+  `DialogSectionHeadingTitle` (`####` — md semibold, with the same `icon`/`description`/`info`
+  slots as `SectionHeadingTitle`, so only the type size steps down). It exists because
+  `DialogHeaderTitle` is **lg** — the rung `SubsectionHeadingTitle` occupies — so a dialog holding
+  a multi-section surface otherwise ties with, or is outranked by, its own content. Compose it
+  with the SUBSECTION layout (`Subsection` › `SubsectionHeading` › this, in a `SubsectionStack`):
+  only the type size steps down, the 12px body gap and 32px beat are already right. The ladder
+  stays ABSOLUTE — this is one more fixed size, never a `size`/`compact` knob on a rung above.
 - **Subsection title** — the level BELOW a section on a long record surface: `Subsection` ›
   `SubsectionHeading` › `SubsectionHeadingTitle` (`###` — lg semibold, with the same `info` ⓘ
   affordance as `SectionHeadingTitle`; siblings — a `Badge`, a
@@ -233,10 +235,14 @@ below the pressed element — the composable `Accordion` family (`AccordionHeade
 / `AccordionMeta` / `AccordionContent`); a header-only accordion renders a plain row of identical
 rhythm, so lists mix expandable + static rows. The body is **flush** with the header's left edge
 (aligns with the title — like a `Section` body, no indent, no tinted well). `AccordionHeader` is a
-layout slot: `AccordionTitle`/`AccordionMeta` is the compact list-row heading, but for a
-**collapsible Section** (configurable font/level/description + count) compose the SAME
-`SectionHeadingTitle`/`SectionHeadingMeta` inside it — one heading family across static +
-collapsible.
+layout slot: `AccordionTitle`/`AccordionMeta` is the compact list-row heading, but a **collapsible
+SECTION** is this same family with the heading rung composed inside it — `SectionHeadingTitle` /
+`SubsectionHeadingTitle` / `DialogSectionHeadingTitle` (+ `SectionHeadingMeta`) in the
+`AccordionHeader`, the body in `AccordionContent`. There is no separate collapsible-section
+component: one heading family and one disclosure across static + collapsible. The disclosure
+header IS the section heading — name it for what it hides, never a generic bucket ("Advanced",
+"More", "Options") wrapped around one named section: that stacks two titles of the same rank and
+leaves the reader no reason to open the chevron.
 
 ## No dead rows — registers & tables
 

package/docs/data_entry.md

@@ -272,30 +272,46 @@ second line — hangs below it. That is what keeps a column of controls straight
 mixed-height rows, so a control never drifts into the gap under the title it belongs to.
 
 A task's own free text is its TITLE, a **`TaskCaption`** or a **`TaskDetail`** — there is no
-fourth place to write, because a fourth place gets written in twice. `TaskCaption` is the row's
-state IN WORDS ("3 of 5 papers received", "waiting on the yard") on its own line under the title;
-it is not a field, because a field is a NAMED VALUE the reader sets and a caption is a SENTENCE
-about one row — labelling prose makes it read as a field nobody can edit.
+fourth place to write about the TASK, because a fourth place gets written in twice. `TaskCaption`
+is the row's state IN WORDS ("3 of 5 papers received", "waiting on the yard") on its own line
+under the title; it is not a field, because a field is a NAMED VALUE the reader sets and a caption
+is a SENTENCE about one row — labelling prose makes it read as a field nobody can edit. A sentence
+about one FIELD is not a caption either: it is that sub-row's own `description` / `warning` /
+`error`, which is why the sub-row carries all three.
 
 **THE ROW CARRIES THE TITLE; THE FIELDS THE USER CAN SET ARE SUB-ROWS BENEATH IT.** A field
 belonging to ONE task — its due date, its assignee, a portal login, a reference number — hangs
-under it as a **`TaskSubRow`** (`label` · the control · an optional muted `description`), indented
-ONE step, with the NAME beside its VALUE so the eye pairs them. Belonging is expressed by that
-indentation, which is the same step a nested `TaskList` takes — one device, at every depth. The
-sub-rows of ONE task share a label column sized to THEIR OWN labels: nothing is declared on the
-list, no width is passed in, and no field is sized for a name three tasks further down. The value
-takes the slack between a readable minimum and a field's maximum, dropping onto its own line under
-the label on a surface too narrow to seat both. Use the form-variant `Inline*` editor (the
-default) — `variant="cell"` belongs to a grid.
+under it as a **`TaskSubRow`** (`label` · the control · `description` / `warning` / `error`),
+indented ONE step, with the NAME beside its VALUE so the eye pairs them. Belonging is expressed by
+that indentation, which is the same step a nested `TaskList` takes — one device, at every depth.
+
+**The label column belongs to the LIST, not to the row** — `TaskList labelWidth`, defaulting to
+`DETAIL_LABEL_WIDTH` (130), inherited to every depth, exactly as `DetailTable labelWidth` is the
+record's. Every sub-row on the surface therefore starts its value on ONE x, and a name longer than
+the column WRAPS inside it instead of pushing its own value right. A column each row sized to its
+own words is not a column: it lined up the labels of a task whose names happened to be short and
+staggered every other one, and a vocabulary with longer field names than English staggered nearly
+all of them. Raise it once, on the list, for a vocabulary that genuinely needs more. The value
+takes the slack from a readable minimum, dropping onto its own line under the label on a surface
+too narrow to seat both. Use the form-variant `Inline*` editor (the default) — `variant="cell"`
+belongs to a grid.
+
+**A TASK'S FIELD ANNOTATES EXACTLY LIKE A RECORD'S FIELD.** `TaskSubRow` carries the same
+`description` / `warning` / `error` as `DetailRow`, from one shared implementation — same tones,
+same severity order (error nearest the control, then warning, then the guidance), same alert
+semantics. A fault in ONE field says so on that field. Demoting it into a `TaskCaption` — a
+sentence about the whole ROW — says something different, and that asymmetry is what forced apps
+to do it.
 
 **Anything that needs SCANNABLE COLUMNS is a `Table`, not a `TaskList`.** The compound once
-carried a declared value column so cells lined up down the list; it aligned, and it read worse —
+carried a declared VALUE column so cells lined up down the list; it aligned, and it read worse —
 each name ended up a quarter of the surface from its control, sized for the widest value on the
 page. Comparing the same four values across twenty rows is a table's job. A `DetailTable` inside a
-`TaskDetail` is the same mistake in miniature: a grid whose label and control land at two x
-positions matching nothing above them, a form pasted into a list. `TaskDetail` keeps the FREE-FORM
-block (a chart, a table, a form with its own submit) — it has no name to hang on the indent, so a
-rule down its left edge is what ties it to the row.
+`TaskDetail` is the same mistake in miniature: the list already HAS a label column, so a second
+one lands a label and a control at two more x positions matching nothing above them — a form
+pasted into a list, and with sub-row annotations there is nothing left for it to say.
+`TaskDetail` keeps the FREE-FORM block (a chart, a table, a form with its own submit) — it has no
+name to hang on the indent, so a rule down its left edge is what ties it to the row.
 
 **The ⋯ is a COLUMN — the mirror of the control gutter.** Both pinned controls sit outside the
 row's flow and the ROW reserves each edge (`controlWidth` on the left, `actionWidth` on the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "19.0.1",
+  "version": "20.0.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -195,7 +195,6 @@
     "./dots_indicator": "./src/dots_indicator.tsx",
     "./list": "./src/list.tsx",
     "./list_item": "./src/list_item.tsx",
-    "./section": "./src/section.tsx",
     "./section_heading": "./src/section_heading.tsx",
     "./section_stack": "./src/section_stack.tsx",
     "./separator": "./src/separator.tsx",

package/src/accordion.tsx

@@ -103,7 +103,10 @@ export function AccordionHeader(props: AccordionHeaderProps) {
     <PressableHighlight
       focusRing      onPress={toggle}
       accessibilityRole="button"
-      accessibilityState={{ expanded }}
+      // The W3C prop, NOT `accessibilityState` — this react-native-web build drops the
+      // latter silently, so a disclosure shipped a `role="button"` that never announced
+      // whether its content was showing.
+      aria-expanded={expanded}
       accessibilityLabel={accessibilityLabel}
       style={[styles.headerRow, styles.pressable, style]}
     >

package/src/breakdown.tsx

@@ -113,7 +113,8 @@ export function Breakdown(props: BreakdownProps) {
         {collapsible ? (
           <PressableHighlight
               focusRing            accessibilityRole="button"
-            accessibilityState={{ expanded }}
+            // The W3C prop — `accessibilityState` is dropped by this react-native-web build.
+            aria-expanded={expanded}
             accessibilityLabel={expanded ? labels.less : labels.more(hidden)}
             onPress={() => setExpanded((e) => !e)}
             style={[styles.row, styles.pressable, styles.toggle]}

package/src/control_surface.ts

@@ -25,6 +25,16 @@ export const CONTROL_RADIUS = 10;
  *  one look. Apps building their own controls reuse it. */
 export const FOCUS_RING = `0 0 0 2px ${colors.zinc[900]}`;
 
+/**
+ * How far a control surface insets its OWN text: 1px of border (transparent on an
+ * inline editor at rest) plus 8px of padding. Anything that has to line up with a
+ * control's WORDS rather than with its invisible box — a field's annotation under
+ * its value, a caption hung beneath a title — carries this same number. It is 9,
+ * not 8: reading the padding alone and forgetting the border is what put a whole
+ * family of hanging lines 1px left of the text they belonged to.
+ */
+export const CONTROL_TEXT_INSET = 9;
+
 /** A bordered control's pointer-hover edge: the resting `border` darkens to this on
  *  hover — the premium "this is interactive" affordance that complements the focus
  *  ring (focus = the ring; hover = a darker border). Drive it with `useHover` on a

package/src/data_grid.tsx

@@ -75,7 +75,8 @@ export function DataGrid<T>(props: DataGridProps<T>) {
               <FocusRingPressable
                 onPress={() => onToggleCollapse?.(g.key)}
                 accessibilityRole="button"
-                accessibilityState={{ expanded: !isCollapsed }}
+                // The W3C prop — `accessibilityState` is dropped by this react-native-web build.
+                aria-expanded={!isCollapsed}
                 disabled={!onToggleCollapse}
                 style={({ hovered }: { hovered?: boolean }) => [styles.section, hovered && onToggleCollapse ? styles.sectionHover : null]}
               >

package/src/detail_row.tsx

@@ -1,5 +1,6 @@
 import { createContext, ReactNode, useContext, useState } from "react";
 import { StyleProp, StyleSheet, View, ViewStyle } from "react-native";
+import { FieldAnnotationProps, FieldAnnotations, hasFieldAnnotation } from "./field_annotations";
 import { INLINE_CONTROL_HEIGHT } from "./inline_edit";
 import { getInputLineHeight } from "./text_utils";
 import { Text } from "./text";
@@ -20,9 +21,11 @@ const DetailTableContext = createContext<DetailTableColumns | null>(null);
 const MIN_VALUE_WIDTH = 160;
 
 /** THE kit's label column — ~18 characters, where real field names live. It is
- *  this table's default AND the floor a `TaskSubRow`'s label sizes from, so a
- *  record's fields and a task's read as one language on a surface carrying
- *  both; that only holds while the two are ONE number. */
+ *  this table's default AND a `TaskList`'s, so a record's fields and a task's
+ *  read as one language on a surface carrying both; that only holds while the
+ *  two are ONE number. A name longer than the column WRAPS inside it: the
+ *  column belongs to the SURFACE, so no one field's name may push its own value
+ *  out of line with the field above it. */
 export const DETAIL_LABEL_WIDTH = 130;
 
 export interface DetailTableProps {
@@ -89,7 +92,7 @@ export function DetailTable(props: DetailTableProps) {
   );
 }
 
-export interface DetailRowProps {
+export interface DetailRowProps extends FieldAnnotationProps {
   /** The field label — rendered `sm muted`. */
   label: ReactNode;
   /** The value — any node (a `Text`, a `Badge`, a stack). */
@@ -110,23 +113,6 @@ export interface DetailRowProps {
   labelSize?: "xs" | "sm";
   /** Min row height. Default 28 (or the `DetailTable`'s `minHeight`). */
   minHeight?: number;
-  /** PERSISTENT guidance — what to enter, or the rule that applies ("Printed
-   *  on every document"). Renders under the VALUE (the label column has no
-   *  room for prose); stacked mode mirrors `FormField` (label · description ·
-   *  control). Always visible — field annotations are EXPLICIT, never a
-   *  hidden ⓘ gloss. Invalid STATE → `error` or a co-located `Callout`. Same
-   *  name, same meaning as `FormField.description`. */
-  description?: string;
-  /** A consequence the user should WEIGH before acting — renders in the same
-   *  annotation slot in amber (`Text color="warning"`), one tone between the
-   *  muted `description` and the danger `error`, announced on appearance. Same
-   *  name, same meaning as `FormField.warning`. */
-  warning?: string;
-  /** Field-level failure, under the value in danger ink with `FormField`'s
-   *  alert semantics (announced on appearance). For CONSUMER-validated state —
-   *  the `Inline*` editors already render their own transient save errors;
-   *  don't wire both to the same failure. */
-  error?: string;
   /** The value renders as FLAT text (an `InlineStatic`, a plain `Text`) rather
    *  than a control-height chip. Annotations then tuck up by the control
    *  band's slack, so the perceived gap under the TEXT equals the gap under a
@@ -153,7 +139,7 @@ export function DetailRow(props: DetailRowProps) {
   const form = labelWidth != null;
   // Annotations (description / warning / error) live UNDER THE VALUE — the row
   // grows, so the label + trailing center against the CONTROL LINE, not the block.
-  const annotated = description != null || warning != null || error != null;
+  const annotated = hasFieldAnnotation(props);
   // A FLAT value (no painted chip) centers its text in the control band,
   // leaving invisible slack below it — tuck the annotations up by that slack
   // so the perceived gap matches a chip row's. Horizontal mode only (stacked
@@ -170,29 +156,11 @@ export function DetailRow(props: DetailRowProps) {
       </Text>
     </View>
   );
-  // Severity descending from the control: error first (adjacent to the control
-  // that failed, FormField's alert semantics), then warning, then the guidance.
-  // Indented to the inline chip's OWN text inset (paddingHorizontal 8), so
-  // annotations align with the value's text.
-  const annotations = annotated ? (
-    <>
-      {error != null ? (
-        <Text size="xs" color="danger" accessibilityRole="alert" aria-live="polite" style={styles.annotation}>
-          {error}
-        </Text>
-      ) : null}
-      {warning != null ? (
-        <Text size="xs" color="warning" accessibilityRole="alert" aria-live="polite" style={styles.annotation}>
-          {warning}
-        </Text>
-      ) : null}
-      {description != null ? (
-        <Text size="xs" color="muted" style={styles.annotation}>
-          {description}
-        </Text>
-      ) : null}
-    </>
-  ) : null;
+  // THE field-annotation anatomy — severity, tones, a11y and the control's own
+  // text inset, defined once in `field_annotations` and rendered identically by
+  // a task's `TaskSubRow`. A record's field and a task's field are the same
+  // thing on two surfaces; they may not say a fault two different ways.
+  const annotations = <FieldAnnotations description={description} warning={warning} error={error} />;
   if (table?.stacked) {
     // Stacked mode wears the FORM grammar: the label renders exactly like a
     // `FormField` label (medium, default ink), so a narrow record surface
@@ -234,12 +202,12 @@ export function DetailRow(props: DetailRowProps) {
       {form ? (
         <View style={[styles.value, annotated && styles.valueStack]}>
           <View style={[styles.controlLine, { minHeight }]}>{children}</View>
-          {flatTuck !== 0 && annotations != null ? <View style={{ marginTop: flatTuck }}>{annotations}</View> : annotations}
+          {flatTuck !== 0 ? <View style={{ marginTop: flatTuck }}>{annotations}</View> : annotations}
         </View>
       ) : (
         <View style={annotated ? styles.valueStack : undefined}>
           <View style={[styles.controlLine, { minHeight }]}>{children}</View>
-          {flatTuck !== 0 && annotations != null ? <View style={{ marginTop: flatTuck }}>{annotations}</View> : annotations}
+          {flatTuck !== 0 ? <View style={{ marginTop: flatTuck }}>{annotations}</View> : annotations}
         </View>
       )}
       {table?.trailingWidth != null ? (
@@ -279,9 +247,9 @@ const styles = StyleSheet.create({
   // The first line of the value cell — the control centers in it exactly like
   // the label and trailing cells do.
   controlLine: { justifyContent: "center" },
+  // The 2px between the control line and the annotation block beneath it — the
+  // same rhythm `FieldAnnotations` puts between its own lines.
   valueStack: { gap: 2 },
-  // Aligns annotation text with the inline chip's text (its 8px inset).
-  annotation: { paddingLeft: 8 },
   // Form mode (labelWidth set): the value column FILLS the row so every inline
   // editor spans the SAME width — and none jumps wider when it swaps to the
   // (flex:1) edit control. A stretch column, so an InlineEditView / InlineStatic

package/src/field_annotations.tsx

@@ -0,0 +1,76 @@
+import { StyleSheet, View } from "react-native";
+import { CONTROL_TEXT_INSET } from "./control_surface";
+import { Text } from "./text";
+
+/**
+ * What a FIELD says about itself under its own value — ONE anatomy, shared by every field
+ * surface in the kit (`DetailRow` on a record, `TaskSubRow` on a task). A record's field and a
+ * task's field carry the same three tones, in the same order, with the same a11y, because they
+ * ARE the same thing on two surfaces: a name, a value the reader sets, and whatever has to be
+ * said about it. Where the two disagreed, an app with a field-level fault had to demote it into
+ * prose about the whole ROW — which says something different.
+ *
+ * Always VISIBLE. A field annotation is never a hidden ⓘ gloss: guidance nobody opens is
+ * guidance nobody reads, and a fault behind a disclosure is a fault the reader ships.
+ */
+export interface FieldAnnotationProps {
+  /** PERSISTENT guidance — what to enter, or the rule that applies ("Printed on every
+   *  document"). Muted, never announced: it is true before the reader touches the field and
+   *  stays true after. An invalid STATE is `error`, not a description written in the past
+   *  tense. Same name, same meaning as `FormField.description`. */
+  description?: string;
+  /** A consequence the reader should WEIGH before acting — amber, one tone between the muted
+   *  `description` and the danger `error`, announced on appearance. It does not block: the
+   *  value is accepted and something downstream is worse for it. Same name, same meaning as
+   *  `FormField.warning`. */
+  warning?: string;
+  /** Field-level FAILURE — danger ink, `FormField`'s alert semantics, announced on appearance.
+   *  For CONSUMER-validated state: the `Inline*` editors already render their own transient
+   *  save errors, so don't wire both to one failure. */
+  error?: string;
+}
+
+/** Does this field have anything to say? Hosts ask because an annotated field is a TALLER row,
+ *  and the label beside it still has to centre on the CONTROL line rather than on the block. */
+export function hasFieldAnnotation(props: FieldAnnotationProps): boolean {
+  return props.description != null || props.warning != null || props.error != null;
+}
+
+/**
+ * The stack itself — rendered directly beneath the value, `null` when the field has nothing to
+ * say.
+ *
+ * SEVERITY DESCENDS FROM THE CONTROL: error first (adjacent to the value that failed), then
+ * warning, then the guidance. All three can be present at once and none suppresses another —
+ * they answer different questions ("this is broken" / "this will cost you" / "this is what the
+ * field is for"), and hiding the rule that explains the failure is exactly the wrong economy.
+ */
+export function FieldAnnotations(props: FieldAnnotationProps) {
+  if (!hasFieldAnnotation(props)) return null;
+  return (
+    <View style={styles.stack}>
+      {props.error != null ? (
+        <Text size="xs" color="danger" accessibilityRole="alert" aria-live="polite">
+          {props.error}
+        </Text>
+      ) : null}
+      {props.warning != null ? (
+        <Text size="xs" color="warning" accessibilityRole="alert" aria-live="polite">
+          {props.warning}
+        </Text>
+      ) : null}
+      {props.description != null ? (
+        <Text size="xs" color="muted">
+          {props.description}
+        </Text>
+      ) : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  // The control's own text inset, so an annotation lines up with the value's WORDS rather than
+  // with the editor's invisible box — and the 2px that separates the lines from each other,
+  // which is the same rhythm the host puts between the control and this block.
+  stack: { gap: 2, paddingLeft: CONTROL_TEXT_INSET },
+});

package/src/progress_bar.tsx

@@ -1,6 +1,7 @@
 import { View, StyleSheet, type ViewStyle } from "react-native";
 import { Text } from "./text";
 import { colors } from "./colors";
+import { useLocaleTag } from "./locale";
 
 export type ProgressBarFormat = "percentage" | "fraction" | "none";
 
@@ -12,7 +13,8 @@ export interface ProgressBarProps {
    * it. */
   title?: string;
   /** Caption above-right of the bar: `percentage` → "50%", `fraction` →
-   * "1.250 / 2.500 · 50%". */
+   * "1,250 / 2,500 · 50%" (separators follow the reader's locale). Reports the
+   * TRUE ratio — over `max` it reads "105%" while the track stays clamped. */
   format?: ProgressBarFormat;
   color?: string;
   completeColor?: string;
@@ -40,12 +42,23 @@ export function ProgressBar(props: ProgressBarProps) {
     compact = false,
   } = props;
 
-  const percentage = max > 0 ? Math.min(100, Math.max(0, (value / max) * 100)) : 0;
-  const isComplete = percentage >= 100;
+  // The pack is locale-aware (see `RemainderMeter`); a hardcoded tag renders 2.100 for an
+  // English reader, which reads as 2.1.
+  const localeTag = useLocaleTag();
+  /**
+   * The TRACK clamps — a fill wider than its own track is meaningless. The CAPTION does not: a
+   * meter reading `2.100 / 2.000 · 100%` asserts a number that is false, and a reader scanning
+   * percentages sees "exactly at the limit" when they are over it. Progress-toward-completion
+   * never exceeds its max, so this only diverges for the over-allowance case, where the true
+   * figure is the whole point.
+   */
+  const ratio = max > 0 ? Math.max(0, (value / max) * 100) : 0;
+  const percentage = Math.min(100, ratio);
+  const isComplete = ratio >= 100;
 
   if (compact) {
     const label =
-      format === "percentage" ? `${Math.round(percentage)}%` : `${value.toLocaleString("vi-VN")}/${max.toLocaleString("vi-VN")}`;
+      format === "percentage" ? `${Math.round(ratio)}%` : `${value.toLocaleString(localeTag)}/${max.toLocaleString(localeTag)}`;
     return (
       <View style={styles.compactRow}>
         <View style={[styles.track, styles.compactTrack]}>
@@ -62,9 +75,9 @@ export function ProgressBar(props: ProgressBarProps) {
 
   const caption =
     format === "fraction"
-      ? `${value.toLocaleString("vi-VN")} / ${max.toLocaleString("vi-VN")} · ${Math.round(percentage)}%`
+      ? `${value.toLocaleString(localeTag)} / ${max.toLocaleString(localeTag)} · ${Math.round(ratio)}%`
       : format === "percentage"
-        ? `${Math.round(percentage)}%`
+        ? `${Math.round(ratio)}%`
         : null;
 
   return (

package/src/section_heading.tsx

@@ -110,6 +110,64 @@ export function SubsectionHeadingTitle(props: SubsectionHeadingTitleProps) {
   );
 }
 
+export interface DialogSectionHeadingTitleProps {
+  children: React.ReactNode;
+  /** Optional muted line under the title, as on `SectionHeadingTitle`. */
+  description?: string;
+  /** Leading glyph, as on `SectionHeadingTitle`. */
+  icon?: IconName;
+  /** Heading rank. Defaults to 4 — one level under `SubsectionHeadingTitle`'s 3. */
+  level?: HeadingLevel;
+  /** An ⓘ popover after the title, as on the two rungs above. */
+  info?: string;
+}
+
+/**
+ * The section title for a surface hosted in a DIALOG — ALWAYS `####` (md semibold), the fourth
+ * rung of the same fixed ladder.
+ *
+ * It exists because `DialogHeaderTitle` is `lg`, which is the rung `SubsectionHeadingTitle`
+ * occupies: a dialog holding a multi-section surface has its own title tying with, or being
+ * outranked by, its content. The ladder stays ABSOLUTE — this is one more fixed size, never a
+ * knob on an existing rung. Do not reach for a `size`/`compact` prop on the titles above; the same
+ * rank rendering at two sizes is exactly what the fixed ramp prevents.
+ *
+ * Compose it with the SUBSECTION layout — `Subsection` › `SubsectionHeading` › this, inside a
+ * `SubsectionStack`. Only the type size steps down; the 12px body gap and the 32px between-group
+ * beat are already right for a dialog, so duplicating them under a `Dialog*` name would add three
+ * exports that differ from their siblings in nothing.
+ *
+ *   <SubsectionStack divided>
+ *     <Subsection>
+ *       <SubsectionHeading>
+ *         <DialogSectionHeadingTitle info="…">Usage</DialogSectionHeadingTitle>
+ *         <SectionHeadingMeta>Aug 2 – Sep 2</SectionHeadingMeta>
+ *       </SubsectionHeading>
+ *       {body}
+ *     </Subsection>
+ *   </SubsectionStack>
+ */
+export function DialogSectionHeadingTitle(props: DialogSectionHeadingTitleProps) {
+  const { children, description, icon, level = 4, info } = props;
+  const words = useLoticsLocale();
+  return (
+    <View style={{ flex: 1, gap: 2 }}>
+      <View style={{ flexDirection: "row", alignItems: "center", gap: 6 }}>
+        {icon ? <Icon name={icon} size={16} /> : null}
+        <Text level={level} size="md" weight="semibold">
+          {children}
+        </Text>
+        {info ? <InfoPopover text={info} accessibilityLabel={words.sectionHeading.info} /> : null}
+      </View>
+      {description ? (
+        <Text color="zinc-500" size="sm">
+          {description}
+        </Text>
+      ) : null}
+    </View>
+  );
+}
+
 export interface SectionHeadingProps {
   children: React.ReactNode;
   style?: StyleProp<ViewStyle>;

package/src/select.tsx

@@ -228,11 +228,13 @@ function SelectTrigger<T extends string>({
       testID={testID}
       // Without a role this Pressable renders as an unfocusable <div> on web — the
       // trigger drops out of the tab order and Enter/Space can't open it. `button`
-      // makes it tab-focusable and maps keyboard activation to onPress; `expanded`
-      // announces open/closed to assistive tech.
+      // makes it tab-focusable and maps keyboard activation to onPress; `aria-expanded`
+      // announces open/closed to assistive tech. The W3C props, NOT `accessibilityState` —
+      // this react-native-web build drops the latter silently.
       accessibilityRole="button"
       accessibilityLabel={accessibilityLabel}
-      accessibilityState={{ expanded: open, disabled }}
+      aria-expanded={open}
+      aria-disabled={disabled}
       style={(state) => [styles.pressable, CONTROL_TRANSITION, open && styles.opened, disabled && styles.disabled, style, state.hovered && !disabled && { borderColor: HOVER_BORDER }]}
       onPress={!disabled ? onPress : undefined}
       disabled={disabled}

package/src/spreadsheet_view.tsx

@@ -9,7 +9,9 @@ function SheetTab(props: { selected: boolean; onPress: () => void; name: string
   return (
     <FocusRingPressable
       accessibilityRole="tab"
-      accessibilityState={{ selected: props.selected }}
+      // The W3C prop — `accessibilityState` is dropped by this react-native-web build, and a
+      // tab that never announces `aria-selected` leaves the tablist with no current item.
+      aria-selected={props.selected}
       onPress={props.onPress}
       style={[styles.tab, props.selected ? styles.tabActive : null]}
     >

package/src/task.tsx

@@ -1,7 +1,9 @@
 import { createContext, useContext, type ReactNode } from "react";
 import { StyleSheet, View } from "react-native";
 import { colors } from "./colors";
+import { CONTROL_TEXT_INSET } from "./control_surface";
 import { DETAIL_LABEL_WIDTH } from "./detail_row";
+import { FieldAnnotationProps, FieldAnnotations } from "./field_annotations";
 import { INLINE_CONTROL_HEIGHT } from "./inline_edit";
 import { Text } from "./text";
 import { TASK_ROW_BAND, TASK_ROW_GAP, taskGutter, taskTitleSlack } from "./task_metrics";
@@ -51,6 +53,14 @@ import { TASK_ROW_BAND, TASK_ROW_GAP, taskGutter, taskTitleSlack } from "./task_
  * `TaskDetail` is the exception that proves the indent — a free-form block has no label to hang
  * on it, so it keeps a rule instead.
  *
+ * **The sub-row LABEL column is the list's** (`labelWidth`, defaulting to the record surface's
+ * `DETAIL_LABEL_WIDTH`), inherited to every depth like the gutters. A name longer than it wraps
+ * INSIDE it and its value stays put. The column each sub-row sized to its OWN words looked
+ * shared on a list of two-word English names and was not one: a short label started its value at
+ * one x, a long one at another, and a vocabulary with longer words than English staggered nearly
+ * every row. A column that is not shared is not a column — and this is the label's, never the
+ * value's, which is the one this family deleted.
+ *
  * **A task list is not a table.** Anything the reader scans DOWN a column — six rows compared on
  * the same four values — is a `Table` or a `DataGrid`, which are built for it. A `TaskList` sized
  * for that is a table with a worse header.
@@ -70,10 +80,14 @@ import { TASK_ROW_BAND, TASK_ROW_GAP, taskGutter, taskTitleSlack } from "./task_
  *
  * **A value and a sentence are different things.** A `TaskSubRow` holds a NAMED value the reader
  * sets; `TaskCaption` holds a sentence ABOUT the row ("Missing 2 of 6") on its own line under the
- * title. Prose given a label reads as a field nobody can edit.
+ * title. Prose given a label reads as a field nobody can edit. Which is why a sub-row annotates
+ * like a record's field does — `description` · `warning` · `error`, the one anatomy in
+ * `field_annotations` — so a fault in ONE field says so on that field instead of being demoted
+ * into a sentence about the whole row.
  *
  * There is deliberately no `note` slot. A task's free text is its title, a caption, or detail;
- * a fourth place to write invited writing it twice.
+ * a fourth place to write about the TASK invited writing it twice. A sentence about one FIELD is
+ * that sub-row's own annotation, not a caption.
  */
 
 interface TaskListContextValue {
@@ -81,6 +95,8 @@ interface TaskListContextValue {
   controlWidth: number;
   /** The RIGHT gutter's control — the row's ⋯. `0` on a list whose rows carry no actions. */
   actionWidth: number;
+  /** The label column every `TaskSubRow` on the list renders its name in, at every depth. */
+  labelWidth: number;
   /** 0 at the root. Any value above 0 means "I am rendered inside a task". */
   depth: number;
   density: TaskDensity;
@@ -101,29 +117,11 @@ const TASK_ACTION_WIDTH = 28;
 const TaskListContext = createContext<TaskListContextValue>({
   controlWidth: 20,
   actionWidth: TASK_ACTION_WIDTH,
+  labelWidth: DETAIL_LABEL_WIDTH,
   depth: 0,
   density: "comfortable",
 });
 
-/**
- * A sub-row's label column. It is sized to its OWN content — no measurement, no width from the
- * list — between a floor and a ceiling, which is what makes the labels of ONE task line up with
- * each other: a field name is two or three words, every one of them lands under the floor, so
- * every value in that task starts on the same x. The floor IS the kit's label column
- * (`DETAIL_LABEL_WIDTH`, `DetailTable`'s default) — ~18 characters, where real field names live
- * ("Completed on", "Portal account", "Courier reference") — taken from that one constant rather
- * than matched to it, so a task's fields and a record's cannot drift apart on a surface carrying
- * both.
- *
- * The ceiling is the honest half of the deal. A label longer than the floor takes the width it
- * needs and its value sits outboard of its siblings' — until the ceiling, where it wraps instead,
- * so one verbose name cannot push the whole column off the surface. A TRUE shared column (every
- * label at the widest sibling's width, whatever that is) cannot be had in flexbox without
- * measuring text, and a measured column costs a layout pass, a re-render and a rule this file
- * could not state — for a case that mostly does not arise.
- */
-const SUB_LABEL_MIN = DETAIL_LABEL_WIDTH;
-const SUB_LABEL_MAX = 168;
 /**
  * The width a value claims before it would rather WRAP. It is set by what a real value needs —
  * an email address, a member's name, a three-word status all run to about 185px — so below it,
@@ -133,17 +131,14 @@ const SUB_LABEL_MAX = 168;
  */
 const SUB_VALUE_MIN = 200;
 /**
- * How far a `variant="cell"` control insets its own text: 1px of transparent border plus 8px
- * of padding. Everything that hangs beneath a row — the caption, a sub-row's label, the detail
- * block — adds the same, so it lines up with the WORDS rather than with the editor's invisible
- * box. A STRING title gets it from `TaskTitle`; only a custom title NODE that is not a
- * `variant="cell"` control has to add it, or it sits out of line with the editable titles
- * around it.
- *
- * It was 8 — the padding alone, forgetting the border — which put every caption, detail block
- * and nested list 1px left of the title it belonged to.
+ * How far a `variant="cell"` control insets its own text — the kit's `CONTROL_TEXT_INSET` under
+ * this family's name, because a task surface reaches for it constantly. Everything that hangs
+ * beneath a row — the caption, a sub-row's label, the detail block — adds the same, so it lines
+ * up with the WORDS rather than with the editor's invisible box. A STRING title gets it from
+ * `TaskTitle`; only a custom title NODE that is not a `variant="cell"` control has to add it, or
+ * it sits out of line with the editable titles around it.
  */
-export const TASK_TEXT_INSET = 9;
+export const TASK_TEXT_INSET = CONTROL_TEXT_INSET;
 
 export interface TaskListProps {
   children: ReactNode;
@@ -163,6 +158,20 @@ export interface TaskListProps {
    * nested list inherits it.
    */
   actionWidth?: number;
+  /**
+   * The width of the label column EVERY `TaskSubRow` on this list renders its name in, at every
+   * depth — the list's, never the row's, exactly as `DetailTable labelWidth` is the record's.
+   * Defaults to `DETAIL_LABEL_WIDTH` (130, ~18 characters), taken from that one constant rather
+   * than matched to it, so a task's fields and a record's cannot drift apart on a surface
+   * carrying both.
+   *
+   * A name longer than the column WRAPS inside it and its value stays put. That is the whole
+   * point: a column each row sized to its OWN words is not a column — it started a short label's
+   * value at one x and a long one's at another, on the same list, and a surface whose field
+   * names run long (any language with longer words than English) had a different value x on
+   * nearly every row. Raise it for a vocabulary that genuinely needs more, on the LIST, once.
+   */
+  labelWidth?: number;
   /**
    * `comfortable` (the default) gives every row a 44px first-line BAND — the tap target a
    * finger needs, and what the leading control centres in; `dense` drops to 32px for a
@@ -183,9 +192,10 @@ export function TaskList(props: TaskListProps) {
   const isNested = parent.depth > 0;
   const controlWidth = props.controlWidth ?? parent.controlWidth;
   const actionWidth = props.actionWidth ?? parent.actionWidth;
+  const labelWidth = props.labelWidth ?? parent.labelWidth;
   const density = props.density ?? parent.density;
   return (
-    <TaskListContext.Provider value={{ controlWidth, actionWidth, depth: parent.depth + 1, density }}>
+    <TaskListContext.Provider value={{ controlWidth, actionWidth, labelWidth, depth: parent.depth + 1, density }}>
       <View
         style={[
           styles.list,
@@ -344,32 +354,40 @@ export function TaskActions(props: { children: ReactNode }) {
   );
 }
 
+interface TaskSubRowProps extends FieldAnnotationProps {
+  /** The field's NAME, rendered muted in the LIST's label column. Longer than the column and it
+   *  WRAPS inside it — it is never clipped, and it never moves its own value. */
+  label: ReactNode;
+  /** The value's control — a form-variant `Inline*` editor, a `Text`. It FILLS the cell. */
+  children: ReactNode;
+}
+
 /**
  * ONE of the task's own FIELDS, hung under the row: its NAME, then its VALUE, adjacent, indented
  * one step so it reads as the task's.
  *
- * The sub-rows of one task share a label column sized to THEIR content — local to this task,
- * never a width the list declares and never one the caller passes. A label and its value sit
- * next to each other because that is how the eye pairs them; a column shared with every other
- * row on the surface put a two-word name a quarter of a screen from its input, and no amount of
- * alignment made that legible.
+ * **The label column belongs to the LIST** (`TaskList labelWidth`, defaulting to the kit's
+ * `DETAIL_LABEL_WIDTH`), so every sub-row on the surface starts its value on ONE x, at every
+ * depth — the same contract `DetailTable labelWidth` gives a record's fields, because a task's
+ * field and a record's field are the same thing on two surfaces. A label longer than the column
+ * wraps inside it and its value does not move. The column each row sized to its OWN words was
+ * the bug: it aligned the labels of a task whose names happened to be short and staggered every
+ * other one, and a surface whose field names run long had a different value x on nearly every
+ * row. A column that is not shared is not a column.
  *
  * The value takes the row's slack from a readable minimum: on a narrow surface it drops onto its
  * own line under the label rather than compressing to a few characters, and on a wide one it
  * FILLS the content box, ending on the same x as the title above it and the ⋯ gutter beside it.
  *
+ * It annotates exactly like a `DetailRow` — `description` · `warning` · `error`, one shared
+ * anatomy (`field_annotations`). A field-level fault says so ON THE FIELD; demoting it into a
+ * `TaskCaption`, which is a sentence about the ROW, says something different.
+ *
  * **Use `TaskDetail` instead when the block is not a label/value field** — a chart, a whole
  * table, a form with its own submit. (Subtasks are neither: they are a nested `TaskList`.)
  */
-export function TaskSubRow(props: {
-  /** The field's NAME, rendered muted beside its value. */
-  label: ReactNode;
-  /** The value's control — a form-variant `Inline*` editor, a `Text`. It FILLS the cell. */
-  children: ReactNode;
-  /** Persistent guidance under the value ("The password is never stored"), on the control's
-   *  own text inset. Not a state: a fault or a warning about the ROW is a `TaskCaption`. */
-  description?: string;
-}) {
+export function TaskSubRow(props: TaskSubRowProps) {
+  const { labelWidth } = useContext(TaskListContext);
   // The sub-row's own first-line band. The row's band, unless the density's band cannot contain
   // a form control (a `dense` 32 row against a 40px inline editor) — the label's slack and the
   // control's centre are then BOTH taken from 40, so they still meet on one y.
@@ -379,18 +397,17 @@ export function TaskSubRow(props: {
       <View
         style={[
           styles.subLabel,
-          // Symmetric slack, not centring — a field name long enough to WRAP keeps its first
-          // line on the control beside it, the same law `TaskTitle` follows against the ring.
-          { paddingVertical: taskTitleSlack(band) },
+          // The LIST's column, and symmetric slack rather than centring — a field name long
+          // enough to WRAP keeps its first line on the control beside it, the same law
+          // `TaskTitle` follows against the ring.
+          { width: labelWidth, paddingVertical: taskTitleSlack(band) },
         ]}
       >
         <Text size="sm" color="muted">{props.label}</Text>
       </View>
       <View style={styles.subValue}>
         <View style={[styles.subControl, { minHeight: band }]}>{props.children}</View>
-        {props.description !== undefined ? (
-          <Text size="xs" color="muted" style={styles.subDescription}>{props.description}</Text>
-        ) : null}
+        <FieldAnnotations description={props.description} warning={props.warning} error={props.error} />
       </View>
     </View>
   );
@@ -460,16 +477,18 @@ const styles = StyleSheet.create({
   // rhythm the row uses — and the same wrap: too narrow to seat both and the value drops to its
   // own line under the label.
   subRow: { flexBasis: "100%", flexDirection: "row", flexWrap: "wrap", columnGap: TASK_ROW_GAP },
-  // `flexBasis: auto` — the label is sized by its OWN words, clamped to the shared band the
-  // floor and ceiling define. `flexShrink` lets it give way before it overflows a container
-  // narrower than the floor. The inset puts its WORDS on the TITLE's x, not one step in: the
-  // control gutter already says which rows are tasks and which are their fields, so an indent
-  // on top of it only breaks the single left edge every line on the surface otherwise shares.
+  // A FIXED column, arriving as the list's `labelWidth` — never sized by this row's own words,
+  // which is what puts every value on one x. `flexShrink` is the safety valve alone: a
+  // container narrower than the whole column has no line to shrink against, so the label gives
+  // way rather than overflowing — and it gives way by the same amount on every row of that
+  // list. The inset puts its WORDS on the TITLE's x, not one step in: the control gutter
+  // already says which rows are tasks and which are their fields, so an indent on top of it
+  // only breaks the single left edge every line on the surface otherwise shares. It is INSIDE
+  // the column, so the value starts the same distance from the row's edge as a `DetailRow`'s
+  // does on a record.
   subLabel: {
     flexGrow: 0,
     flexShrink: 1,
-    minWidth: SUB_LABEL_MIN,
-    maxWidth: SUB_LABEL_MAX,
     paddingLeft: TASK_TEXT_INSET,
   },
   // FILLS the rest of the row, exactly as `DetailRow`'s value column does — a sub-row is the
@@ -477,13 +496,12 @@ const styles = StyleSheet.create({
   // left the row reading as a fragment floating under a full-width one. A control too wide for
   // its content is that CONTROL's business (and `DetailRow` would have the same complaint), not
   // a reason for this row to end early.
-  subValue: { flexGrow: 1, flexShrink: 1, flexBasis: SUB_VALUE_MIN, minWidth: 0 },
+  // The 2px `gap` is the air between the control line and any annotation block beneath it — the
+  // same rhythm `DetailRow` uses, and inert on the rows that say nothing.
+  subValue: { flexGrow: 1, flexShrink: 1, flexBasis: SUB_VALUE_MIN, minWidth: 0, gap: 2 },
   // The control CENTRES in the sub-row's band — the label's first line is pinned to the same
   // centre — and stretches to the cell's full width.
   subControl: { justifyContent: "center" },
-  // The control's own text inset, so the guidance lines up with the value it describes rather
-  // than with the editor's invisible box.
-  subDescription: { paddingLeft: TASK_TEXT_INSET, marginTop: 2 },
   // A full line like the rest, except that its inset arrives as a MARGIN (the rule has to sit on
   // the title's text edge, so it cannot be padding). A 100% basis plus that margin is 9px wider
   // than the line, so `flexShrink` gives the 9 back and the block ends on the content edge with

package/src/section.tsx

@@ -1,101 +0,0 @@
-import { Pressable, View } from "react-native";
-import { Text } from "./text";
-import { useState, useImperativeHandle } from "react";
-import { Icon, IconName } from "./icon";
-import { Spacer } from "./spacer";
-import { FOCUS_RING } from "./control_surface";
-import { useFocusRing } from "./use_focus_ring";
-
-export interface SectionHandlers {
-  expand: () => void;
-  collapse: () => void;
-}
-
-interface SectionProps {
-  children: React.ReactNode;
-  title: string;
-  description?: string;
-  collapsible?: boolean;
-  icon?: IconName;
-  titleRight?: React.ReactNode;
-  initialCollapsed?: boolean;
-  ref?: React.Ref<SectionHandlers>;
-}
-
-export function Section(props: SectionProps) {
-  const {
-    children,
-    title,
-    icon,
-    description,
-    collapsible,
-    titleRight,
-    initialCollapsed = false,
-    ref,
-  } = props;
-  const [collapsed, setCollapsed] = useState(collapsible && initialCollapsed);
-
-  useImperativeHandle(ref, () => ({
-    expand: () => {
-      if (collapsible) {
-        setCollapsed(false);
-      }
-    },
-    collapse: () => {
-      if (collapsible) {
-        setCollapsed(true);
-      }
-    },
-  }));
-
-  const { focusVisible, focusProps } = useFocusRing();
-
-  const titleComponent = collapsible ? (
-    <Pressable
-      {...focusProps}
-      style={[{ flexDirection: "row", alignItems: "center", gap: 8, flex: 1 }, focusVisible && { boxShadow: FOCUS_RING, borderRadius: 4 }]}
-      onPress={() => setCollapsed(!collapsed)}
-    >
-      <Icon name={collapsed ? "chevron-right" : "chevron-down"} size={20} />
-      {icon && <Icon name={icon} size={20} />}
-      <Text size="md" weight="medium" userSelect="none">
-        {title}
-      </Text>
-    </Pressable>
-  ) : (
-    <View style={{ flex: 1 }}>
-      <Text size="md" weight="medium">
-        {title}
-      </Text>
-    </View>
-  );
-
-  return (
-    <View>
-      <View
-        style={{
-          flexDirection: "row",
-          alignItems: "center",
-          height: 40,
-          paddingBottom: 8,
-        }}
-      >
-        {titleComponent}
-        {titleRight}
-      </View>
-      {!collapsed && (
-        <>
-          {!!description && (
-            <>
-              <Text size="sm" color="zinc-500">
-                {description}
-              </Text>
-              <Spacer size={16} />
-            </>
-          )}
-          {children}
-        </>
-      )}
-    </View>
-  );
-}