@lotics/ui 18.1.0 → 19.0.0

package/src/task.tsx

@@ -1,80 +1,144 @@
 import { createContext, useContext, type ReactNode } from "react";
 import { StyleSheet, View } from "react-native";
 import { colors } from "./colors";
+import { DETAIL_LABEL_WIDTH } from "./detail_row";
+import { INLINE_CONTROL_HEIGHT } from "./inline_edit";
+import { Text } from "./text";
+import { TASK_ROW_BAND, TASK_ROW_GAP, taskGutter, taskTitleSlack } from "./task_metrics";
 
 /**
- * The TASK compound — a list of things to be done, at any depth and any layout.
+ * The TASK compound — a list of things to be done, at any depth.
  *
- * It replaces `Checklist`/`ChecklistRow`, which was a configuration object: eight slot props,
- * a `trailing`/`meta` pair that was mutually exclusive BY TYPE so an author had to predict
- * "wide surface" or "narrow" when writing the JSX, and a `subtasks` array of
- * `{label, checked}` a child could never outgrow. Every new task layout arrived as another
- * prop. Composition takes those decisions back:
- *
- *   <TaskList fieldsWidth={168}>
+ *   <TaskList>
  *     <TaskItem>
  *       <TaskStatus><CheckCircle …/></TaskStatus>
  *       <TaskTitle><InlineTextInput variant="cell" struck={done} …/></TaskTitle>
- *       <TaskFields><InlineDatePicker …/><InlineMemberSelect …/></TaskFields>
  *       <TaskActions><ActionMenu …/></TaskActions>
  *       <TaskCaption>Waiting on the signed copy</TaskCaption>
+ *       <TaskSubRow label="Portal account"><InlineTextInput …/></TaskSubRow>
+ *       <TaskSubRow label="Completed on"><InlineDatePicker …/></TaskSubRow>
  *       <TaskDetail>…</TaskDetail>
  *       <TaskList>…</TaskList>          ← subtasks ARE tasks
  *     </TaskItem>
+ *     <TaskItem>
+ *       <TaskStatus><CheckCircle …/></TaskStatus>
+ *       <TaskTitle struck={done}>Identity card</TaskTitle>   ← a read-only title is its STRING
+ *     </TaskItem>
  *   </TaskList>
  *
- * Two properties follow from the shape rather than from props:
+ * **A row carries its TITLE. The fields the reader can SET hang under it as sub-rows.** A task
+ * row is one thing said in one line; a field is a NAME and a VALUE, and the two belong side by
+ * side so the eye pairs them without travelling. This family spent a version trying to be a
+ * table — a shared value column every row reserved, an action gutter to keep that column
+ * straight, packing arithmetic to divide it — and the shape it produced put a two-word label a
+ * quarter of the surface away from the input it named. Alignment was never the goal; legibility
+ * was.
  *
- * **A subtask is a task.** Nesting a `TaskList` inside a `TaskItem` makes the child recursive
- * by construction, so it carries a due date, a menu, its own children — everything the parent
- * has. The old array shape made "subtasks need X" a permanent ticket queue.
+ * **Two GUTTERS, one content box.** Both of a row's pinned controls sit OUTSIDE the flow — the
+ * status in the LEFT gutter, the ⋯ in the RIGHT — and the item reserves each as padding: a gutter
+ * is its control's width plus the row gap (`taskGutter`), declared once on the list and inherited
+ * to every depth. What is left between them is ONE box, and every line the item renders spans
+ * exactly it: the title, a `TaskCaption`, a `TaskSubRow`, a `TaskDetail`, a nested `TaskList`.
+ * That is what holds the right edge straight on a list where only SOME rows carry a menu — the ⋯
+ * is a COLUMN the list reserves, not a width whichever row has one happens to stop before. A list
+ * whose rows carry no actions at all declines the column with `actionWidth={0}`.
  *
- * **The row reflows on its own.** `TaskTitle` claims a readable minimum width; when the row
- * cannot seat the title and the fields together, flex-wrap drops `TaskFields` onto its own
- * line. That is intrinsic — no viewport query, no measurement — so it behaves the same in a
- * drawer, a split pane and a phone, which a breakpoint cannot.
+ * **Belonging is INDENTATION** — the LEFT gutter, again. Everything a task owns, its fields and
+ * its subtasks, steps right by exactly one of them. That is the only device: no rules to draw, no
+ * width to declare, and it compounds correctly, so a sub-field of a subtask reads as one at a
+ * glance. The right gutter is the one that must NOT compound, so a nested list hands the parent's
+ * back before its own rows re-take it; otherwise the menu column walks inward a step per level.
+ * `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.
  *
- * **A value and a sentence are different things.** `TaskFields` holds the cells the reader
- * edits and scans DOWN a column (due, assignee), sized once by the list so they stay a column;
- * `TaskCaption` holds a sentence ABOUT the row ("Needs: Carrier, Vehicle plate") on its own
- * line under the title. The first cut of this family merged them, which pushed prose into the
- * value column where it aligned with nothing.
+ * **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.
+ *
+ * **A subtask is a task.** Nesting a `TaskList` inside a `TaskItem` makes the child recursive by
+ * construction, so it carries its own fields, a menu, children — everything the parent has. An
+ * array of `{label, checked}` made "subtasks need X" a permanent ticket queue.
+ *
+ * **The control column is straight because the first line is a BAND.** The leading control is
+ * pinned to the gutter, so its centre is a CONSTANT — half the density's band. The row's first
+ * line therefore has to BE that band, which is why `TaskTitle` claims it (and, for a plain-text
+ * title, pads it symmetrically so a WRAPPED title keeps its first line in place). Without that,
+ * anything hanging below the title — a caption, a sub-row, a nested list — grew the row, the
+ * wrapping content packed to the top, and the control sagged into the gap under the title it
+ * belongs to. The same law pins the ⋯ on the right. The geometry is `task_metrics.ts`, where it
+ * can be tested.
+ *
+ * **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.
  *
  * 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.
  */
 
 interface TaskListContextValue {
-  /** Width of the leading control column — nested lists and detail blocks indent by it. */
+  /** The LEFT gutter's control — the leading ring or checkbox. One indent step is its gutter. */
   controlWidth: number;
-  /** Shared width of every row's field cluster, so the cells form a COLUMN. */
-  fieldsWidth?: number;
+  /** The RIGHT gutter's control — the row's ⋯. `0` on a list whose rows carry no actions. */
+  actionWidth: number;
   /** 0 at the root. Any value above 0 means "I am rendered inside a task". */
   depth: number;
   density: TaskDensity;
 }
 
-export type TaskDensity = "comfortable" | "dense";
+export type TaskDensity = keyof typeof TASK_ROW_BAND;
+
+/**
+ * The ⋯ gutter's default: an `ActionMenu` — and any `IconButton` at its default `md` — is 28
+ * across. A constant rather than a required prop because the slot's occupant is KNOWN: every task
+ * surface in the product reserves the same column without declaring anything, and a list that
+ * forgot to declare would otherwise be the misaligned one. The failure it cannot have is silent —
+ * a list that reserves a column it does not use is 28px narrower; a list that reserves nothing
+ * puts every hanging line under its own menu.
+ */
+const TASK_ACTION_WIDTH = 28;
 
 const TaskListContext = createContext<TaskListContextValue>({
   controlWidth: 20,
+  actionWidth: TASK_ACTION_WIDTH,
   depth: 0,
   density: "comfortable",
 });
 
-/** Below this a title is unreadable, so the fields take their own line instead. */
-const TITLE_MIN_WIDTH = 180;
-/** The minimum comfortable tap target — a finger, not a pointer. */
-const TOUCH_TARGET = 44;
-/** A pointer-driven register trades the target for rows on screen. */
-const DENSE_ROW = 32;
-/** Horizontal rhythm between the row's slots. */
-const ROW_GAP = 12;
+/**
+ * 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,
+ * on a phone or in a narrow drawer, the value takes its OWN line under the label and gets the
+ * whole width instead of ellipsizing at seventeen characters beside it. A pair that fits only by
+ * hiding the value has not fitted.
+ */
+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, the detail, a nested list —
- * adds the same, so it lines up with the WORDS rather than with the editor's invisible box. A
- * plain-`Text` title carries it too, or it sits out of line with the editable titles around it.
+ * 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.
@@ -84,44 +148,52 @@ export const TASK_TEXT_INSET = 9;
 export interface TaskListProps {
   children: ReactNode;
   /**
-   * Width of every row's leading control — `CheckCircle` 20 (the default), `CheckboxInput`
-   * 24. Detail blocks and nested lists indent by it so they sit on the title's text edge.
-   * Set on the ROOT list; a nested list inherits it.
+   * Width of every row's leading control, which the LEFT gutter is reserved for — `CheckCircle`
+   * 20 (the default), `CheckboxInput` 24. It also sets the INDENT: everything hanging under a
+   * task — its sub-rows, a nested list — steps right by this plus the row gap. Set on the ROOT
+   * list; a nested list inherits it.
    */
   controlWidth?: number;
   /**
-   * `comfortable` (the default) gives every row a 44px minimum so a finger can hit it;
-   * `dense` drops to 32px for a pointer-driven register. Density belongs to the SURFACE, so
-   * it is set once here and inherited by nested lists.
+   * Width of every row's trailing action, which the RIGHT gutter is reserved for — an
+   * `ActionMenu` (or any default `IconButton`) 28 (the default), a `size="sm"` one 24. EVERY row
+   * reserves it, which is what keeps a list where only SOME rows carry a ⋯ straight: their
+   * content ends on the same x as the menu-less rows'. Pass `0` on a list whose rows carry no
+   * actions at all, so it pays nothing for a column it never uses. Set on the ROOT list; a
+   * nested list inherits it.
    */
-  density?: TaskDensity;
+  actionWidth?: number;
   /**
-   * Fixed width for every row's `TaskFields`, so the due/assignee cells line up as a COLUMN
-   * down the list instead of drifting with each title's length. Set it once here — a row
-   * with fewer cells still reserves the width, which is what keeps the column straight.
-   * Omit it and each cluster hugs its own content (fine for a single row, jittery in a list).
+   * `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
+   * pointer-driven register of TEXT rows (an inline editor carries its own 40px control band,
+   * which a 32px row cannot contain). Density belongs to the SURFACE, so
+   * it is set once here and inherited by nested lists.
    */
-  fieldsWidth?: number;
+  density?: TaskDensity;
   accessibilityLabel?: string;
 }
 
 /**
- * The list — owns geometry (control column, indent, density) for every descendant. Nest one
- * inside a `TaskItem` and its rows become that task's subtasks, indented one column.
+ * The list — owns geometry (the two gutters, the indent, density) for every descendant. Nest one
+ * inside a `TaskItem` and its rows become that task's subtasks, indented one step.
  */
 export function TaskList(props: TaskListProps) {
   const parent = useContext(TaskListContext);
   const isNested = parent.depth > 0;
   const controlWidth = props.controlWidth ?? parent.controlWidth;
+  const actionWidth = props.actionWidth ?? parent.actionWidth;
   const density = props.density ?? parent.density;
-  const fieldsWidth = props.fieldsWidth ?? parent.fieldsWidth;
   return (
-    <TaskListContext.Provider value={{ controlWidth, depth: parent.depth + 1, density, fieldsWidth }}>
+    <TaskListContext.Provider value={{ controlWidth, actionWidth, depth: parent.depth + 1, density }}>
       <View
         style={[
           styles.list,
-          // A nested list is a child-step list: indent it to the parent's title text edge.
-          isNested && { flexBasis: "100%", marginTop: 2, marginBottom: 2 },
+          // A nested list hands the PARENT's right gutter BACK, because its own rows are about to
+          // reserve one of their own: without it the ⋯ column would walk one gutter inward per
+          // level, and a subtask's menu would sit left of its parent's instead of under it. The
+          // LEFT gutter is not given back — there, stepping inward IS the indent.
+          isNested && [styles.nestedList, { marginRight: -taskGutter(parent.actionWidth) }],
         ]}
         role="list"
         accessibilityLabel={props.accessibilityLabel}
@@ -133,22 +205,34 @@ export function TaskList(props: TaskListProps) {
 }
 
 /**
- * One task. Its children lay out as a WRAPPING row — `TaskStatus`, `TaskTitle`, `TaskFields`,
- * `TaskActions` — while `TaskDetail` and a nested `TaskList` are full-width and fall beneath
- * it. Order in JSX is order on screen; nothing inspects child types.
+ * One task. Its two pinned controls — `TaskStatus`, `TaskActions` — sit in the gutters, out of
+ * the flow; everything else is a full-width LINE in the content box between them (`TaskTitle`
+ * first, then any `TaskCaption`, `TaskSubRow`, `TaskDetail` and nested `TaskList`), stacking in
+ * the order it was written. Order in JSX is order on screen; nothing inspects child types.
  */
 export function TaskItem(props: { children: ReactNode }) {
-  const { controlWidth } = useContext(TaskListContext);
-  // The control is taken OUT of the wrapping flow and pinned to the left gutter, so the row's
-  // content — title, fields, caption, detail, a nested list — all share ONE column. Anything
-  // that wraps therefore lands under the title instead of under the checkbox, which is what
-  // made a wrapped field cluster read as a row of its own, belonging to nothing.
+  const { controlWidth, actionWidth } = useContext(TaskListContext);
+  // BOTH controls are taken OUT of the wrapping flow and pinned to a gutter the item RESERVES —
+  // the same `taskGutter` on each edge — so the row's content, title through nested list, shares
+  // ONE box between them. Anything that hangs therefore lands under the title instead of under
+  // the checkbox (a wrapped block read as a row of its own, belonging to nothing) and stops where
+  // the title stops instead of running on under the ⋯ (the first line and every line beneath it
+  // ended at two different x's, which is what a self-sizing menu in the flow cost).
   //
-  // The minimum tap target is the ROW's, not each slot's: boxing every slot at 44px centred
-  // the title in it and pushed the caption ~13px below the words it describes.
+  // Pinned means the control's centre is a CONSTANT (half the band), so the row's FIRST LINE
+  // has to be that band or the two disagree the moment anything hangs below. Claiming it is
+  // `TaskTitle`'s job — the FIRST line's, and only its. Boxing EVERY slot at the band was the
+  // earlier attempt and it boxed the caption too, centring that line in its own 44 and pushing
+  // it half a band below the words it describes; hanging off the title's band costs the caption
+  // the band's bottom slack (12px) instead, the same for a text title and an editor one. The
+  // item itself carries the band only as its MINIMUM, which is what gives a one-line row its
+  // tap target.
   return (
     <View
-      style={[styles.item, { minHeight: useRowMinHeight(), paddingLeft: controlWidth + ROW_GAP }]}
+      style={[
+        styles.item,
+        { minHeight: useRowBand(), paddingLeft: taskGutter(controlWidth), paddingRight: taskGutter(actionWidth) },
+      ]}
       role="listitem"
     >
       {props.children}
@@ -156,52 +240,67 @@ export function TaskItem(props: { children: ReactNode }) {
   );
 }
 
-function useRowMinHeight(): number {
+/** The row's FIRST-LINE band, and so also its minimum height — with nothing hanging beneath
+ *  it, the first line IS the row. */
+function useRowBand(): number {
   const { density } = useContext(TaskListContext);
-  return density === "dense" ? DENSE_ROW : TOUCH_TARGET;
+  return TASK_ROW_BAND[density];
 }
 
-/** The leading control — a `CheckCircle`, a `CheckboxInput`, a status dot. Pinned to the
- *  list's control column so every title starts on the same edge. */
+/** The leading control — a `CheckCircle`, a `CheckboxInput`, a status dot. Pinned into the list's
+ *  LEFT gutter (`controlWidth`), the exact mirror of `TaskActions` on the right, so every title
+ *  starts on the same edge. That gutter is also the INDENT: what hangs under a task steps right
+ *  by one of it, which is the only thing that says "this belongs to the task above", at any
+ *  depth. */
 export function TaskStatus(props: { children: ReactNode }) {
   const { controlWidth } = useContext(TaskListContext);
-  // Pinned to the gutter and sized to the FIRST line, so it stays beside the title however
-  // tall the row grows underneath it.
+  // Pinned to the gutter and sized to the BAND — the row's first line, which `TaskTitle`
+  // claims — so the control centres on the title's first line however tall the row grows
+  // underneath it, and every row's control sits at the same y as its own title's words.
   return (
-    <View style={[styles.status, { width: controlWidth, height: useRowMinHeight() }]}>
+    <View style={[styles.status, { width: controlWidth, height: useRowBand() }]}>
       {props.children}
     </View>
   );
 }
 
-/** The task's identity — plain `Text` or an inline editor. Takes the row's spare width and
- *  claims a readable minimum, which is what makes `TaskFields` wrap rather than crush it. */
-export function TaskTitle(props: { children: ReactNode }) {
-  return (
-    <View style={styles.title}>{props.children}</View>
-  );
-}
+type TaskTitleProps =
+  // The title TEXT. `struck` belongs to this shape alone — a node carries its own treatment
+  // (an inline editor has its own `struck`), so typing it `never` there keeps the prop from
+  // being passed where nothing would read it.
+  | { children: string; struck?: boolean }
+  | { children: ReactNode; struck?: never };
 
 /**
- * The descriptor cluster — due date, assignee, chips, counts. Sits inline after the title
- * while the row has room and takes its own line when it does not.
+ * The task's identity — an inline editor (`variant="cell"`), or the title text itself.
+ *
+ * Pass a STRING and the title renders on the cell inset with the band's slack above and below
+ * it, so it lines up with the editable titles around it AND a title that wraps keeps its first
+ * line beside the control; `struck` strikes + mutes it for a finished task. Pass a node when
+ * the title is an editor or carries more than words — it centres in the band.
  *
- * Replaces the old `trailing` (wide) / `meta` (narrow) pair, which made the author pick one
- * at authoring time and be wrong on the other surface.
+ * Spans the row's content box — gutter to gutter, the same width as every line hung beneath it,
+ * so a long title wraps inside the box instead of running under the ⋯. And it claims the row's
+ * BAND, which is what keeps both gutter controls beside the title instead of sagging toward a
+ * caption below it.
  */
-export function TaskFields(props: { children: ReactNode }) {
-  const { fieldsWidth } = useContext(TaskListContext);
+export function TaskTitle(props: TaskTitleProps) {
+  const band = useRowBand();
+  if (typeof props.children === "string") {
+    return (
+      <View style={[styles.title, { minHeight: band, paddingHorizontal: TASK_TEXT_INSET, paddingVertical: taskTitleSlack(band) }]}>
+        <Text
+          size="sm"
+          color={props.struck ? "muted" : "default"}
+          decoration={props.struck ? "lineThrough" : undefined}
+        >
+          {props.children}
+        </Text>
+      </View>
+    );
+  }
   return (
-    <View
-      style={[
-        styles.fields,
-        // A reserved width is what makes a COLUMN: every row gives its cells the same box,
-        // so a row missing a due date does not pull its assignee leftward out of line.
-        fieldsWidth !== undefined && { width: fieldsWidth },
-      ]}
-    >
-      {props.children}
-    </View>
+    <View style={[styles.title, { minHeight: band }]}>{props.children}</View>
   );
 }
 
@@ -209,11 +308,10 @@ export function TaskFields(props: { children: ReactNode }) {
  * A second line under the title — what this task's STATE is, in words: "Needs: Carrier,
  * Vehicle plate", "Waiting on the yard", "3 of 5 papers received".
  *
- * Deliberately NOT part of `TaskFields`. A field is a VALUE the reader edits and scans down a
- * column; a caption is a SENTENCE about this row. Merging them (as the first cut of this
- * family did) pushes prose into the value column, where it aligns with nothing and squeezes
- * the cells. It always takes its own line, on the title's text edge — never inline, never
- * behind a disclosure, because a state the reader must open to see is a state they will miss.
+ * Deliberately NOT a `TaskSubRow`. A sub-row is a NAMED value the reader sets; a caption is a
+ * SENTENCE about this row, and prose given a label reads as a field nobody can edit. It always
+ * takes its own line, on the title's text edge — never inline, never behind a disclosure,
+ * because a state the reader must open to see is a state they will miss.
  */
 export function TaskCaption(props: { children: ReactNode }) {
   return (
@@ -221,16 +319,91 @@ export function TaskCaption(props: { children: ReactNode }) {
   );
 }
 
-/** The row's actions — an `ActionMenu`, an `IconButton`. A destructive item belongs behind
- *  the menu, never as a bare ✕ on the row, so a stray tap cannot destroy a task. */
+/**
+ * The row's actions — an `ActionMenu`, an `IconButton`. A destructive item belongs behind
+ * the menu, never as a bare ✕ on the row, so a stray tap cannot destroy a task.
+ *
+ * Pinned into the list's RIGHT gutter (`actionWidth`), the exact mirror of `TaskStatus` on the
+ * left: out of the flow, flush on the item's edge, centred on the first-line band. Because the
+ * ITEM reserves that column rather than this box claiming it, a row without a menu ends its
+ * content on the same x as a row with one, and every line hung under either of them ends there
+ * too. A self-sizing menu in the FLOW was the alternative and it cannot hold both: the first line
+ * stopped where the menu began while the full-width lines beneath it ran on to the container, so
+ * no two right edges on the surface agreed.
+ */
 export function TaskActions(props: { children: ReactNode }) {
+  const { actionWidth } = useContext(TaskListContext);
+  // The band as an explicit height is the pin: the menu's centre is half the band from the row's
+  // top however tall the row grows, which is where the title's first line and the gutter control
+  // are. Centring it in the ITEM instead would sink it toward a caption or a sub-row the moment
+  // one appeared.
+  return (
+    <View style={[styles.actions, { width: actionWidth, height: useRowBand() }]}>
+      {props.children}
+    </View>
+  );
+}
+
+/**
+ * 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 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.
+ *
+ * **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;
+}) {
+  // 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.
+  const band = Math.max(useRowBand(), INLINE_CONTROL_HEIGHT);
   return (
-    <View style={styles.actions}>{props.children}</View>
+    <View style={styles.subRow}>
+      <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) },
+        ]}
+      >
+        <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}
+      </View>
+    </View>
   );
 }
 
-/** A block beneath the row, indented to the title's text edge — an inline editor, a
- *  drill-down, the task's own fields. Render it only while open. */
+/**
+ * A block beneath the row, indented to the title's text edge — a chart, a table, a form with
+ * its own submit, a drill-down. Render it only while open.
+ *
+ * FREE-FORM content only: a label/value FIELD is a `TaskSubRow`. It is the one thing hung under
+ * a task that does NOT take the indent, because it has no label to put there — a rule down its
+ * left edge is what ties it to the row instead.
+ */
 export function TaskDetail(props: { children: ReactNode }) {
   return (
     <View style={[styles.detail, { marginLeft: TASK_TEXT_INSET }]}>{props.children}</View>
@@ -241,47 +414,86 @@ const styles = StyleSheet.create({
   // No gap: every row already carries the density's min-height, so the rhythm is the ROW,
   // not the space between rows. A gap on top of it made the list read as loose pairs.
   list: { gap: 0 },
+  // A nested list is a child-step list: its own rows take the indent, so it needs only its
+  // own line and a hair of air. `flexGrow` is what makes the give-back a give-back — a 100% basis
+  // pulled left by a negative margin would just occupy less of its line, so the list has to grow
+  // back INTO the parent's gutter to end where the parent's own edge is.
+  nestedList: { flexBasis: "100%", flexGrow: 1, marginTop: 2, marginBottom: 2 },
   item: {
+    // Both gutter controls position against THIS box — against its PADDING box, which is the
+    // reservation each of them sits in.
     position: "relative",
     flexDirection: "row",
     flexWrap: "wrap",
     alignItems: "center",
     // `align-items` centres within a LINE; with `flex-wrap: wrap` it is `align-content` that
-    // places the lines in the box. Without it a short row (a plain-text subtask, 20px) sat at
-    // the top of its 44px target while the gutter control centred — the control read as
-    // belonging to the row below.
+    // places the LINES in the box. It has slack to distribute only on a row whose content is
+    // SHORTER than the band — one with no title, since a title claims the band — and centring
+    // there keeps that row's content on the gutter control's centre. It is NOT what aligns a
+    // normal row: a centred block of lines moves with whatever hangs below it, which is
+    // exactly how the control came to sag under its own title.
     alignContent: "center",
-    columnGap: ROW_GAP,
-    // Lines inside ONE task are the same thought (title → caption → detail), so they sit
-    // tight; `gap` would have applied the 12px column rhythm vertically too.
+    columnGap: TASK_ROW_GAP,
+    // Lines inside ONE task are the same thought (title → caption → fields), so they sit
+    // tight; `gap` would have applied the 12px column rhythm vertically too. The first line is
+    // the exception by construction: it is the BAND, so what follows starts under the band's
+    // bottom edge, not under the title's last word.
     rowGap: 2,
   },
   status: { position: "absolute", left: 0, top: 0, justifyContent: "center", alignItems: "flex-start" },
-  // flexBasis at the minimum (not 0) is what drives the wrap: once title + fields cannot
-  // both fit, the fields — which never shrink — are pushed to the next line.
-  title: {
-    flexGrow: 1,
+  // The mirror of `status`, on the item's own right edge — an absolute box positions against the
+  // item's PADDING box, so `right: 0` puts it in the gutter the item reserved, exactly as
+  // `left: 0` does. `flex-end` seats a NARROWER control (a `size="sm"` ⋯ in a 28 gutter) flush on
+  // that edge, as `flex-start` does on the left.
+  actions: { position: "absolute", right: 0, top: 0, justifyContent: "center", alignItems: "flex-end" },
+  // The title IS the content box — one line spanning gutter to gutter, like every line hung
+  // beneath it. It claimed a readable MINIMUM while the ⋯ shared its line, which is what pushed
+  // the menu onto a line of its own rather than letting it crush the words; with the menu pinned
+  // in a gutter there is nothing left on the line to wrap against, and a minimum could then only
+  // overflow a narrow surface. The BAND arrives as an inline `minHeight`, and `center` seats a
+  // shorter child (an inline editor is 40 in a 44 band) on the band's centre — where the gutter
+  // control is.
+  title: { flexBasis: "100%", minWidth: 0, justifyContent: "center" },
+  // `flexBasis: "100%"` is the whole trick: the caption always breaks to its own line.
+  caption: { flexBasis: "100%" },
+  // Its own line (the caption's trick), then a NAME and a VALUE side by side on the same 12px
+  // 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.
+  subLabel: {
+    flexGrow: 0,
     flexShrink: 1,
-    flexBasis: TITLE_MIN_WIDTH,
-    minWidth: TITLE_MIN_WIDTH,
-    justifyContent: "center",
+    minWidth: SUB_LABEL_MIN,
+    maxWidth: SUB_LABEL_MAX,
+    paddingLeft: TASK_TEXT_INSET,
   },
-  fields: {
-    flexDirection: "row",
-    alignItems: "center",
-    justifyContent: "flex-end",
-    // NOWRAP: the cluster is a ROW of cells, and it wraps as a UNIT under the title. Letting
-    // it wrap internally split the cells across two lines with the ⋯ stranded between them.
-    // Too little room means the cells compress, never that they stack.
-    flexWrap: "nowrap",
-    gap: 8,
-    // Shrinkable, so a narrow container compresses the cells instead of shoving the ⋯ onto a
-    // line of its own. `fieldsWidth` still pins the column when a list wants one.
+  // FILLS the rest of the row, exactly as `DetailRow`'s value column does — a sub-row is the
+  // same label/value shape one surface down, and a value that stopped short of the container
+  // 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 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
+  // everything else — without it the one line that carries a rule was the one line that ran into
+  // the ⋯ gutter.
+  detail: {
+    flexBasis: "100%",
     flexShrink: 1,
-    minWidth: 0,
+    borderLeftWidth: 1,
+    borderLeftColor: colors.border,
+    paddingLeft: TASK_ROW_GAP,
   },
-  // `flexBasis: "100%"` is the whole trick: the caption always breaks to its own line.
-  caption: { flexBasis: "100%" },
-  actions: { flexGrow: 0, flexShrink: 0, justifyContent: "center" },
-  detail: { flexBasis: "100%", borderLeftWidth: 1, borderLeftColor: colors.border, paddingLeft: ROW_GAP },
 });