@lotics/ui 19.0.0 → 19.1.0

package/MIGRATION.md

@@ -44,8 +44,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

@@ -334,9 +334,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.
@@ -708,9 +710,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 +798,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 +811,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 +830,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/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.0",
+  "version": "19.1.0",
   "type": "module",
   "exports": {
     "./vite": {

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/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/sources.tsx

@@ -75,7 +75,7 @@ function SourceChip({ source, openable }: { source: SourceRef; openable?: boolea
       <View style={[styles.iconDisc, { backgroundColor: tint(k.color, 0.14) }]}>
         <Icon name={k.icon} size={13} color={solid(k.color)} />
       </View>
-      <Text size="xs" weight="medium" numberOfLines={1}>
+      <Text size="xs" weight="medium" numberOfLines={1} style={styles.label}>
         {source.label}
       </Text>
       {source.detail ? (
@@ -93,6 +93,14 @@ const styles = StyleSheet.create({
   chip: {
     flexDirection: "row",
     alignItems: "center",
+    // A source label is a document TITLE and can be long — "Thành phần hồ sơ
+    // mua NOXH — Khoản 7 — Sĩ quan, hạ sĩ quan, quân nhân chuyên nghiệp". The
+    // chip must never exceed its row: `numberOfLines` alone cannot truncate a
+    // flex child that is free to grow, so the chip is capped and the label is
+    // the part that gives way (`flexShrink`), keeping the icon, the locator and
+    // the open glyph intact — they are what make the chip readable once the
+    // title is clipped.
+    maxWidth: "100%",
     gap: 8,
     paddingLeft: 5,
     paddingRight: 10,
@@ -102,8 +110,10 @@ const styles = StyleSheet.create({
     borderColor: colors.border,
     backgroundColor: colors.white,
   },
+  label: { flexShrink: 1 },
   iconDisc: {
     width: 24,
+    flexShrink: 0,
     height: 24,
     borderRadius: 7,
     alignItems: "center",

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