npm - @lotics/ui - Versions diffs - 16.0.0 → 16.2.0 - Mend

@lotics/ui 16.0.0 → 16.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (21) hide show

package/AGENTS.md +1 -1
package/docs/catalog.md +47 -8
package/docs/composition.md +3 -1
package/docs/data_entry.md +41 -2
package/docs/templates.md +10 -2
package/examples/tpl_item_list.tsx +3 -3
package/examples/tpl_record.tsx +71 -17
package/package.json +4 -2
package/src/button.tsx +10 -11
package/src/checklist.tsx +275 -17
package/src/date_picker.tsx +21 -0
package/src/detail_row.tsx +14 -4
package/src/form_date_picker.tsx +3 -1
package/src/form_field.tsx +4 -1
package/src/icon.tsx +2 -0
package/src/icon_button.tsx +8 -9
package/src/inline_edit.tsx +41 -26
package/src/locale.tsx +26 -2
package/src/pending_commits.test.ts +68 -0
package/src/pending_commits.ts +45 -0
package/src/use_gated_press.ts +41 -0

package/AGENTS.md CHANGED Viewed

@@ -15,7 +15,7 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 | Doc | Read it for |
 |---|---|
 | [docs/catalog.md](./docs/catalog.md) | **The complete inventory** — Reach-by-role (each data role → the ONE canonical component) + every `@lotics/ui/<module>` entry point (incl. `@lotics/ui/vite`'s `loticsOptimizeDeps` for a custom-code app's `vite.config.ts`). Read before building any screen; reuse first. |
-| [docs/data_entry.md](./docs/data_entry.md) | Which editing pattern for which job — inline edit, fieldset forms, find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (incl. the three-way file INTAKE: CTA + `FileDropTarget` + `usePasteFiles`), stage gates. |
+| [docs/data_entry.md](./docs/data_entry.md) | Which editing pattern for which job — inline edit, fieldset forms, find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (incl. the three-way file INTAKE: CTA + `FileDropTarget` + `usePasteFiles`), stage gates, the commit-on-blur vs action-press ordering law (the kit gates the press — `pending_commits`). |
 | [docs/ai_patterns.md](./docs/ai_patterns.md) | AI acts, the human stays in charge — composer, live run feed (`AgentRun`), the one law's split (modify → review-before-apply; create → save-direct + the `ResultHeader` receipt), findings, provenance, confidence; the UI half of the SDK's [ai doc](../app-sdk/docs/ai.md). |
 | [docs/composition.md](./docs/composition.md) | The design-language contract — canvas + content column, heading altitude, banded cards, register vs inset rows, master-detail `Drawer`, view controls, color discipline, typography, whitespace. |
 | [docs/templates.md](./docs/templates.md) | The map of `examples/tpl_*.tsx` — what shape each template solves and which to start from (copy + adapt, never import) — plus the record-surface composition rules (pipeline order, static shape, decision budget). |

package/docs/catalog.md CHANGED Viewed

@@ -571,7 +571,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   select.
 - **`form_date_picker`** — `FormDatePicker`: `FormField` wrapping a `DatePicker` — one
   labeled date field. (Omits `style`; for a grid cell use a bare `FormField style={half}`
-  around `DatePicker`.)
+  around `DatePicker`.) Defaults the picker's `accessibilityLabel` to its own visible label
+  — the FormField label text is not otherwise associated with the segment inputs. A bare
+  `DatePicker` outside a FormField must be given `accessibilityLabel` explicitly; range
+  formats suffix each half with the locale's start/end-date names.
 - **`switch_button`** — `SwitchButton`: the full-ROW toggle — a `PressableHighlight` row
   (optional icon + medium title left, `Switch` pinned right) where the whole row IS the
   switch (`accessibilityRole="switch"`, the inner Switch read-only). The settings-panel/menu
@@ -605,13 +608,19 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 ### Inline editing & record surfaces
 - **`inline_edit`** — `useInlineEdit` + `InlineEditView` / `InlineEditFrame` +
-  `INLINE_CONTROL_HEIGHT` (40) + `inlineValueTextStyle`: the engine custom inline editors
+  `useInlineEditFocusRestore` (returns focus to the RESTING control when a KEYBOARD close drops
+  it to `<body>` — what an editor with its own resting shape, e.g. the checklist `note` line,
+  reaches for instead of the frame) + `INLINE_CONTROL_HEIGHT` (40) +
+  `inlineValueTextStyle`: the engine custom inline editors
   join through — a view ⇄ edit toggle, a draft buffer, async `onSave` with the spinner
   INSIDE the control and inline error, commit on blur (Enter saves, Escape reverts) or
   `controls="buttons"`; KEYBOARD focus on the closed view opens edit mode with the input
   focused (type → Tab → type — see the data-entry keyboard contract), pointer focus never
   does; **`variant: "form" | "cell"`** is THE axis that separates a form field from a data-grid
-  cell (see below).
+  cell (see below). Every commit registers in **`pending_commits`**, which
+  `Button`/`IconButton` wait on via **`use_gated_press`** so an action pressed in the same
+  gesture as the blur cannot read the record before the edit lands (data_entry.md § Inline
+  edit) — automatic, nothing to pass.
 - **`inline_text_input`**, **`inline_number_input`** (`format` for currency/units),
   **`inline_select`**, **`inline_member_select`**, **`inline_date_picker`**
   (`format="datetime"`, `optionalTime`; keyboard focus opens the TYPED segmented `DateField`
@@ -654,7 +663,11 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   label+value row for drawer/peek detail; in FORM mode (`labelWidth` set) the value column
   FILLS the row so a stack of inline editors all span the same width + none jumps wider on
   edit; optional `trailing` slot renders a right-side action/badge after the value (units
-  belong IN the value via `InlineNumberInput format`). The FIELD-ANNOTATION vocabulary (same
+  belong IN the value via `InlineNumberInput format`). The LABEL WRAPS inside its column and
+  is never clipped — a fixed `labelWidth` would otherwise ellipsize every long field name
+  ("Registered business address"), and a name the reader can't finish is worse than a taller
+  row; a wrapped label's FIRST line stays level with the value's first control line while a
+  one-line label still centers on it (both modes, no prop). The FIELD-ANNOTATION vocabulary (same
   names + meanings as `FormField`), always EXPLICIT — a row never hides guidance behind an ⓘ:
   **`description`** = a fact / persistent guidance (muted), under the VALUE (stacked mode
   mirrors the form order label · description · control); **`warning`** = a consequence to weigh
@@ -738,8 +751,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   filled check when done, distinct from the square checkbox; the task/to-do/checklist
   toggle.
 - **`checklist`** — `Checklist` + `ChecklistRow` — the record-scoped checklist COMPOUND: it
-  owns GEOMETRY only (row minHeight 32, gap 12, control/title alignment, the `meta`/
-  `expansion` indent, ONE `trailingWidth` so assignee cells column-align) while content
+  owns GEOMETRY only (row minHeight 32, gap 12, control/title alignment, the `note`/`meta`/
+  `subtasks`/`expansion` indent, ONE `trailingWidth` so assignee cells column-align) while content
   stays composed — `control` takes the `CheckCircle` (omit onChange = read-only ring; a
   PICKER list puts a `CheckboxInput` here and sets `controlWidth={24}` so the indent
   tracks), children the struck transparent `InlineTextInput` or plain `Text`, `trailing` an
@@ -748,8 +761,34 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   danger-styled and last, never a bare ✕ (omit on read-only rows). NARROW surfaces (a
   drawer/peek checklist) put the editors on the `meta` line instead of `trailing` — the
   second line indents to the title's text edge so the TITLE keeps the full width; wide
-  surfaces use `trailing`; never both. `expansion` is a BLOCK slot under the row on the
-  same indent — a transient inline fill editor, a drill-down — rendered only while open
+  surfaces use `trailing`; never both. **`note` is the row's own free-text line** —
+  `{value, onSave, addLabel?, editLabel?, placeholder?}` (`ChecklistRowNote`): the note
+  renders as a muted line directly under the title (above `meta`, on its text edge) and is
+  ALWAYS visible — never behind `expansion` — presses to edit in place, and saving EMPTY
+  removes it (`onSave("")`, whitespace trimmed first — clearing IS the delete, so a note
+  needs no ⋯ entry). A row with no note shows a small `sticky-note` add button instead,
+  which opens the focused empty editor. It composes with `trailing` AND `meta` (a second
+  LINE, not a replacement), the save may be async (spinner + inline error, editor stays
+  open), and chrome comes from the `checklist` locale slice (`addNote`, `editNote(note)` —
+  it wraps the text so the line announces with it — `notePlaceholder`). Never hand-roll a
+  muted sub-line + editor on a checklist row. **`subtasks` are the row's collapsible CHILD
+  STEPS** — `{items, expanded?, onToggleExpanded?, countLabel?}` (`ChecklistRowSubtasks`),
+  each item a `ChecklistSubtask` `{key, label, checked, onToggle}` and nothing more (no
+  note, no assignee, no ⋯: a step needing those is a TASK — give it a row). The parent grows
+  a chevron expander on the TRAILING side of the title (never the leading edge — that's
+  `control`, and a chevron there would knock the title off the text edge on every row
+  WITHOUT steps) carrying the count of UNCHECKED steps beside it; expanded, the children
+  render as compact `CheckboxInput` + label rows on the title's text edge, denser than the
+  parent (24 vs 32) and struck+muted when checked. `items: []` renders NOTHING, not even the
+  expander, so a row can pass the prop unconditionally. Expansion is controlled with
+  `expanded` + `onToggleExpanded`, or UNCONTROLLED (omit `expanded`): open on mount while any
+  step is unchecked, then the user's toggle wins — checking the last step must not yank the
+  list shut. A11y: the expander keeps ONE stable name (`countLabel(missing)` → the
+  `checklist` locale slice's `subtasks(missing)` → English) with `aria-expanded` carrying the
+  state, and the children sit in a `role="group"` named by the row's own title, so they are
+  announced UNDER their parent instead of as loose checkboxes. Never hand-roll indented child
+  rows with a bespoke chevron. `expansion` is a BLOCK slot under the row on
+  the same indent — a transient inline fill editor, a drill-down — rendered only while open
   (`tpl_record`'s Document set rows are the worked example). SUGGESTIONS are never rows:
   offer the commons as `SuggestionChip`s under the list. Close the list with `CaptureRow`.
   There is deliberately NO monolithic Task component — richer task-management rows compose

package/docs/composition.md CHANGED Viewed

@@ -440,7 +440,9 @@ gate's SCOPE, once** — never prose beside the button, never revealed only on p
   fact or consequence, never widget mechanics, never a second sentence; `warning` marks a
   consequence, not decoration. Rows share ONE
   alignment law: the row top-aligns and label · control · trailing each center within the
-  first control line — a tall value block never drags the label. A FLAT value row
+  first control line — a tall value block never drags the label, and a LABEL too long for its
+  column WRAPS (never clipped, never abbreviated to fit) with its first line still level with
+  the value. A FLAT value row
   (`InlineStatic`, plain `Text`) sets **`DetailRow flat`**: the annotation tucks up by the
   control band's slack so the perceived gap under the text equals the gap under a chip —
   the band's invisible bottom half must never read as a hole above the description.

package/docs/data_entry.md CHANGED Viewed

@@ -49,6 +49,31 @@ chip, hover reveals the input-family border (no extra grey wash, no pencil icon
 layout), click OR keyboard focus swaps the input in **at the same height** (zero reflow, the whole
 point), and it commits on blur (Enter saves, Escape reverts) or via `controls="buttons"` (✓ / ✕).
+**Commit-on-blur would race the press that caused it — the kit closes that race for you.**
+Pressing an action while an inline field is focused starts TWO things in ONE gesture: the
+field's write (the blur, on mousedown) and the button's handler (on mouseup). A handler that
+RE-READS the record — to print a document, mint an invoice, copy the row into a new one — would
+overtake the still-in-flight write and act on the PRE-EDIT value, silently: the new value on
+screen, the old one in the output. So **`useInlineEdit` registers every commit and
+`Button`/`IconButton` hold their press until the commits already in flight have settled**
+(`pending_commits.ts`), showing their busy spinner while they wait. Nothing to wire up: with no
+commit pending the press dispatches synchronously exactly as before, and a FAILED commit
+releases the gate too (the field surfaces its own error). A commit started after the press was
+taken is deliberately not waited for — the gate holds a press for the edit that caused it, never
+for later work.
+**What the gate cannot see — an action must take an ID, not a captured object.** Holding the
+press makes the STORE current; it cannot refresh a value the handler already closed over.
+`onPress={() => onIssue(invoice)}` captures the invoice as it was at press time, so the
+confirm dialog quotes — and the mint bills — the pre-edit total no matter how long the gate
+waits. Pass the KEY and resolve the object where it is used
+(`onPress={() => onIssue(invoice.key)}`, then `invoices.find(…)` at render): worked in
+`tpl_record`'s Billing band, whose charge cells are inline editors and whose Issue is
+irreversible. The same rule kills the variant with no race at all — a handler reading a server
+row the screen copied into `useState` (`app-sdk` `docs/mutations.md` § A read must not overtake
+an in-flight write) — as does a write started by something other than an inline commit (a
+dialog save, a debounced autosave).
 ### Keyboard entry — type → Tab → type
 Bulk entry never needs the mouse. KEYBOARD focus (Tab / Shift+Tab) landing on a closed
@@ -132,7 +157,9 @@ narrower than its neighbours'. Rows share ONE alignment law: the row top-aligns
 control · trailing each center within the first control line — annotations (the three tones
 under the value: `description` muted · `warning` amber · `error` danger, each indented to the
 chip's 8px text inset) grow the row downward without dragging the label. The full annotation
-vocabulary lives in composition.md §Field annotations.
+vocabulary lives in composition.md §Field annotations. A long LABEL wraps inside its column
+instead of clipping — never shorten a field name to fit the label width, and never reach for a
+tooltip to recover the tail; the wrapped label's first line stays level with the value.
 ### The editability affordance
@@ -236,7 +263,19 @@ struck transparent `InlineTextInput`, or plain `Text`), then EITHER a `trailing`
 surfaces (the per-task assignee `InlineMemberSelect`, sized by the list's `trailingWidth`) OR a
 `meta` line under the title on NARROW surfaces (a drawer/popover checklist — the two are mutually
 exclusive), plus a `menu` for the row's ⋯ options — never a decorative progress strip. `CaptureRow`
-closes the list as its add-affordance. A NEW record starts with an EMPTY checklist — tasks truly
+closes the list as its add-affordance. A task's own free text — the "why it's stuck" nothing else on
+the record holds — is the row's **`note`** (`{value, onSave}`): a muted line under the title, ALWAYS
+visible (a note behind an expansion gets written twice), pressed to edit in place, and REMOVED by
+saving it empty — so it needs no ⋯ entry and no second field. A note-less row carries a small add
+button that opens the focused editor. It composes with `trailing` AND `meta` — a second LINE, not a
+replacement — so a per-row note is never a hand-rolled sub-line, a comment thread, or an
+expansion. A task made of several ticks takes **`subtasks`** (`{items, expanded?,
+onToggleExpanded?, countLabel?}`) rather than N sibling rows: the parent grows a chevron + the
+count of unchecked steps, and the children — `{key, label, checked, onToggle}` and NOTHING else —
+render indented to the title's text edge when open. The line is sharp: a step that needs its own
+note, due date, assignee, or ⋯ menu is a TASK, so give it a row; subtasks are for the ticks that
+only make sense under their parent. Omit `expanded` and the row opens itself while work is left,
+then hands the state to the user. A NEW record starts with an EMPTY checklist — tasks truly
 vary. The commons split in two: MANDATORY tasks are seeded by the app (a workflow on create, per
 record type) — no human types them; common-but-OPTIONAL tasks appear as `SuggestionChip`s under
 the list — a PILL, never a row, so a suggestion can't be mistaken for a task (tap = materialize,

package/docs/templates.md CHANGED Viewed

@@ -292,7 +292,12 @@ billing, and quick-capture templates. Top → bottom:
   = `dueTone` — red past due, amber ≤3d, else muted), the assignee an **`avatarOnly`** bare avatar
   (dashed add-ghost when unset), sized to the list's `trailingWidth` so the title never overlaps.
   (Contrast the General section's dates/assignee, the same editors in the default `variant="form"`
-  — a zinc-50 chip + hover-border + the full member chip.)
+  — a zinc-50 chip + hover-border + the full member chip.) Two rows carry a **`note`** — the kit's
+  per-row muted second line (press to edit, save empty to remove); the rest show its add button.
+  ONE row ("Book the carrier") carries **`subtasks`** — four child ticks behind the kit's chevron +
+  remaining-count expander, open because work is left; every other row passes an EMPTY list, which
+  renders nothing at all. It is the line to copy: a booking's steps carry only a tick, so they stay
+  child rows — anything needing its own note/due/assignee would be a task instead.
 - **Documents** — the Agents "Document desk" pattern (this template is its worked example —
   see the Agents chapter below): the register `Table` (search · Add files) whose selection
   feeds the `FloatingActionBar` → ONE "Use AI" fork (extract / cross-check / edit-with-AI).
@@ -329,7 +334,10 @@ billing, and quick-capture templates. Top → bottom:
   scope, once — a band-local problem (charged line missing its method) in the band, a broken
   record premise (no customer / invalid tax ID) at the section top; self-evident empties
   stay silent, and NEVER prose beside a CTA. Issuing gates on record premises only — never
-  silently on stage.
+  silently on stage. It is also the worked example of **an irreversible action taking an ID,
+  not a captured object**: `onIssue(inv.key)` with the invoice resolved where the confirm
+  renders, so the quoted total is the one that will be billed even when the press was held
+  for a charge cell's write (data_entry.md § Inline edit).
 - **Document set — the OUTPUT desk, the last WORK section** (the composition rules' output
   law worked on the record surface: the top is intake, the bottom produces on demand).
   Forms group PER PARTY on the `SubsectionStack` beat — each party a `SubsectionHeading` +

package/examples/tpl_item_list.tsx CHANGED Viewed

@@ -2,7 +2,7 @@ import { useEffect, useState, useRef } from "react";
 import { ScrollView, View } from "react-native";
 import type { UIMessagePart, UIDataTypes, UITools } from "ai";
 import { Text } from "@lotics/ui/text";
-import { colors, type ColorName } from "@lotics/ui/colors";
+import { colors, solid, type ColorName } from "@lotics/ui/colors";
 import { ActionMenu, type ActionMenuItem } from "@lotics/ui/action_menu";
 import { Alert } from "@lotics/ui/alert";
 import { Badge } from "@lotics/ui/badge";
@@ -1391,12 +1391,12 @@ function EnterDataDialog({ open, onOpenChange, seedDocs, onCreate, onCreateMany
                   {[...landed].sort((a, b) => Number(b.refFlagged) - Number(a.refFlagged)).map((l) => (
                     <ListItem
                       key={l.id}
-                      left={<Icon name={l.refFlagged ? "circle-alert" : "circle-check"} size={18} color={l.refFlagged ? colors.amber[600] : colors.green[600]} />}
+                      left={<Icon name={l.refFlagged ? "circle-alert" : "circle-check"} size={18} color={l.refFlagged ? solid("amber") : solid("green")} />}
                       title={`Created ${l.title}`}
                       description={l.detail}
                       right={
                         <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
-                          {l.refFlagged ? <Text size="xs" weight="medium" style={{ color: colors.amber[600] }}>1 to check</Text> : null}
+                          {l.refFlagged ? <Text size="xs" weight="medium" style={{ color: solid("amber") }}>1 to check</Text> : null}
                           <Icon name="chevron-right" size={16} color={colors.zinc[400]} />
                         </View>
                       }

package/examples/tpl_record.tsx CHANGED Viewed

@@ -165,6 +165,16 @@ interface StageTask {
   /** ISO date (`""` = no due). The row shows it in a `variant="cell"` date field —
    *  no calendar glyph, coloured by urgency (`tone`), press to edit. */
   due: string;
+  /** The task's own note (`""` = none). The `ChecklistRow` `note` contract owns
+   *  the whole affordance — the muted second line, the tap-to-edit, the add
+   *  button on a note-less row, and removal by saving empty. */
+  note: string;
+  /** The task's CHILD STEPS (`[]` = none, and then nothing renders — not even
+   *  the expander). The `ChecklistRow` `subtasks` contract owns the whole
+   *  affordance: the chevron + remaining count on the parent, the open/closed
+   *  state, and the indented child rows. A step that needs its own note, due
+   *  date, or assignee is a TASK — give it a row, not a subtask. */
+  subtasks: { key: string; label: string; done: boolean }[];
 }
 // A due date N days from today — keeps the seeded urgency states (overdue / soon /
@@ -203,13 +213,23 @@ const newTaskId = () => `t_${(taskSeq += 1)}`;
 // The in-flight demo record's existing checklist (a NEW record gets []).
 const TASK_SEEDS: StageTask[] = [
-  { id: "t1", label: "Confirm pricing with the customer", stage: "sales", done: true, assignee: "mem_01", due: dueIn(-10) },
-  { id: "t2", label: "Attach the signed quote", stage: "sales", done: true, assignee: "mem_01", due: "" },
-  { id: "t3", label: "Verify the customer's tax ID", stage: "sales", done: false, assignee: null, due: dueIn(-2) },
-  { id: "t4", label: "Book the carrier", stage: "operations", done: false, assignee: "mem_02", due: dueIn(1) },
-  { id: "t5", label: "Attach the delivery documents", stage: "operations", done: false, assignee: null, due: dueIn(6) },
-  { id: "t6", label: "Issue every invoice", stage: "accounting", done: false, assignee: "mem_03", due: "" },
-  { id: "t7", label: "Reconcile the receipts", stage: "accounting", done: false, assignee: null, due: dueIn(14) },
+  { id: "t1", label: "Confirm pricing with the customer", stage: "sales", done: true, assignee: "mem_01", due: dueIn(-10), note: "", subtasks: [] },
+  { id: "t2", label: "Attach the signed quote", stage: "sales", done: true, assignee: "mem_01", due: "", note: "", subtasks: [] },
+  // two seeded NOTES — the "why it's stuck" a task carries and nothing else
+  // holds; every other row shows the add affordance instead
+  { id: "t3", label: "Verify the customer's tax ID", stage: "sales", done: false, assignee: null, due: dueIn(-2), note: "Their finance desk answers after 15:00 only.", subtasks: [] },
+  // the one task with SUBTASKS — a booking is a sequence, and its steps carry
+  // nothing but a tick, so they stay child rows instead of four more tasks
+  // (the row opens with work left; press the chevron to close it)
+  { id: "t4", label: "Book the carrier", stage: "operations", done: false, assignee: "mem_02", due: dueIn(1), note: "", subtasks: [
+    { key: "s1", label: "Confirm the pickup window", done: true },
+    { key: "s2", label: "Send the packing list", done: false },
+    { key: "s3", label: "Get the booking reference", done: false },
+    { key: "s4", label: "Share the reference with the customer", done: false },
+  ] },
+  { id: "t5", label: "Attach the delivery documents", stage: "operations", done: false, assignee: null, due: dueIn(6), note: "Waiting on the signed copy from the yard.", subtasks: [] },
+  { id: "t6", label: "Issue every invoice", stage: "accounting", done: false, assignee: "mem_03", due: "", note: "", subtasks: [] },
+  { id: "t7", label: "Reconcile the receipts", stage: "accounting", done: false, assignee: null, due: dueIn(14), note: "", subtasks: [] },
 ];
 // The assignable roster — an app feeds `useMembers()` here.
@@ -345,7 +365,10 @@ function InvoiceBand({
   gated: boolean;
   onAmount: (chKey: string, v: number) => Promise<void>;
   onMethod: (chKey: string, m: Method) => Promise<void>;
-  onIssue: (inv: Invoice) => void;
+  /** Takes the invoice's KEY, never the `inv` object: the press may be held while
+   *  a charge cell finishes writing (Button waits out an inline commit), and a
+   *  captured object would still be the pre-edit snapshot. Resolve at use. */
+  onIssue: (invKey: string) => void;
 }) {
   const total = invoiceTotal(inv);
   const state = invoiceStatus(inv);
@@ -410,10 +433,10 @@ function InvoiceBand({
         {state === "issued" ? (
           <>
             <Link size="xs" onPress={() => {}} accessibilityLabel={`Open invoice ${inv.ref}`}>{inv.ref}</Link>
-            <Button title="Re-issue" color="secondary" disabled={!ready} onPress={() => onIssue(inv)} />
+            <Button title="Re-issue" color="secondary" disabled={!ready} onPress={() => onIssue(inv.key)} />
           </>
         ) : (
-          <Button title="Issue invoice" color="primary" disabled={!ready} onPress={() => onIssue(inv)} />
+          <Button title="Issue invoice" color="primary" disabled={!ready} onPress={() => onIssue(inv.key)} />
         )}
       </View>
     </Subsection>
@@ -832,7 +855,9 @@ export function TplRecord() {
   // ── billing — the bill-to tax ID comes off the CUSTOMER
   const [invoices, setInvoices] = useState<Invoice[]>(BILLING_INITIAL);
   const [deposit, setDeposit] = useState(0);
-  const [confirmIssue, setConfirmIssue] = useState<Invoice | null>(null);
+  // The key, not the invoice: what the dialog shows and issues is derived below, so a
+  // charge that landed between the press and the confirm is reflected, never a stale total.
+  const [confirmIssueKey, setConfirmIssueKey] = useState<string | null>(null);
   const seq = useRef(414);
   const taxId = customer?.taxId ?? "";
   const taxIdValid = TAX_ID_RE.test(taxId);
@@ -1133,11 +1158,11 @@ export function TplRecord() {
   const addTask = () => {
     const label = newTask.trim();
     if (!label) return;
-    setTasks((prev) => [...prev, { id: newTaskId(), label, stage: captureDesk, done: false, assignee: null, due: "" }]);
+    setTasks((prev) => [...prev, { id: newTaskId(), label, stage: captureDesk, done: false, assignee: null, due: "", note: "", subtasks: [] }]);
     setNewTask("");
   };
   const addSuggested = (desk: Desk, label: string) =>
-    setTasks((prev) => [...prev, { id: newTaskId(), label, stage: desk, done: false, assignee: null, due: "" }]);
+    setTasks((prev) => [...prev, { id: newTaskId(), label, stage: desk, done: false, assignee: null, due: "", note: "", subtasks: [] }]);
   const removeTask = (tid: string) => setTasks((prev) => prev.filter((t) => t.id !== tid));
   const moveTask = (tid: string, desk: Desk) =>
     setTasks((prev) => prev.map((t) => (t.id === tid ? { ...t, stage: desk } : t)));
@@ -1148,6 +1173,15 @@ export function TplRecord() {
     setTasks((prev) => prev.map((t) => (t.id === tid ? { ...t, assignee: member } : t)));
   const dueTask = (tid: string, due: string) =>
     setTasks((prev) => prev.map((t) => (t.id === tid ? { ...t, due } : t)));
+  // Saving an EMPTY note is the removal — one write path, no separate delete.
+  const noteTask = (tid: string, note: string) =>
+    setTasks((prev) => prev.map((t) => (t.id === tid ? { ...t, note } : t)));
+  // A child step patches by key — the kit owns the expander and the count, the
+  // app owns nothing but the tick.
+  const toggleSubtask = (tid: string, key: string, done: boolean) =>
+    setTasks((prev) =>
+      prev.map((t) => (t.id === tid ? { ...t, subtasks: t.subtasks.map((s) => (s.key === key ? { ...s, done } : s)) } : t)),
+    );
   // The Task-list grammar: a clearable Group-by + filter chips derive the
   // sections; empty groups drop (except desks — the journey stays visible).
   const [taskGroup, setTaskGroup] = useState<"desk" | "assignee" | "status" | null>("desk");
@@ -1238,6 +1272,9 @@ export function TplRecord() {
       }, 350);
     });
+  // Resolved from the CURRENT invoices every render — the confirm dialog quotes the
+  // total that will actually be billed, including a charge that landed after the press.
+  const confirmIssue = invoices.find((i) => i.key === confirmIssueKey) ?? null;
   const grandTotal = invoices.reduce((sum, inv) => sum + invoiceTotal(inv), 0);
   const allMissing = invoices.flatMap(missingMethods);
   const issuedCount = invoices.filter((i) => invoiceStatus(i) === "issued").length;
@@ -1246,7 +1283,7 @@ export function TplRecord() {
     seq.current += 1;
     const ref = `INV-2026-${String(seq.current).padStart(4, "0")}`;
     setInvoices((prev) => prev.map((x) => (x.key === inv.key ? { ...x, ref } : x)));
-    setConfirmIssue(null);
+    setConfirmIssueKey(null);
     logActivity("credit-card", `Invoice ${ref} issued — ${inv.title}`, { description: formatMoney(invoiceTotal(inv)) });
   };
@@ -1858,6 +1895,23 @@ export function TplRecord() {
                             <InlineMemberSelect variant="cell" avatarOnly members={TEAM} value={t.assignee} onSave={(m) => assignTask(t.id, m)} accessibilityLabel={`Assignee · ${t.label}`} />
                           </View>
                         }
+                        // the row's own NOTE — the muted second line under the
+                        // title (the "why it's stuck" a task carries); the kit
+                        // owns the whole affordance, so nothing here hand-rolls
+                        // a line + editor. Empty = the add button on the row.
+                        note={{ value: t.note, onSave: (v) => noteTask(t.id, v), addLabel: `Add note: ${t.label}` }}
+                        // the row's CHILD STEPS — one task made of several
+                        // ticks. The kit renders the chevron + remaining count
+                        // on the parent and the indented child rows when open;
+                        // an EMPTY list renders nothing, so every row can pass
+                        // the prop unconditionally. Expansion is left
+                        // UNCONTROLLED: a row with work left opens itself.
+                        subtasks={{
+                          items: t.subtasks.map((s) => ({ key: s.key, label: s.label, checked: s.done, onToggle: (on) => toggleSubtask(t.id, s.key, on) })),
+                          // the row name matters once the list is long — the
+                          // locale default ("Subtasks: 3 left") can't know it
+                          countLabel: (missing) => (missing > 0 ? `Subtasks · ${t.label}: ${missing} left` : `Subtasks · ${t.label}: all done`),
+                        }}
                         menu={{ items: menuItems, accessibilityLabel: `Task options: ${t.label}` }}
                       >
                         <InlineTextInput
@@ -2124,7 +2178,7 @@ export function TplRecord() {
               gated={customer === null || !taxIdValid}
               onAmount={(chKey, v) => saveCharge(inv.key, chKey, { amount: v })}
               onMethod={(chKey, m) => saveCharge(inv.key, chKey, { method: m })}
-              onIssue={setConfirmIssue}
+              onIssue={setConfirmIssueKey}
             />
           ))}
@@ -2585,7 +2639,7 @@ export function TplRecord() {
       </Dialog>
       {/* issuing an e-invoice is irreversible — confirm in a Dialog (stage gate) */}
-      <Dialog width={460} open={confirmIssue !== null} onOpenChange={(o) => { if (!o) setConfirmIssue(null); }}>
+      <Dialog width={460} open={confirmIssue !== null} onOpenChange={(o) => { if (!o) setConfirmIssueKey(null); }}>
         <DialogHeader>
           <DialogHeaderTitle>{confirmIssue?.ref ? "Re-issue invoice?" : "Issue e-invoice?"}</DialogHeaderTitle>
         </DialogHeader>
@@ -2601,7 +2655,7 @@ export function TplRecord() {
           </Callout>
         </View>
         <DialogFooter>
-          <Button title="Cancel" color="secondary" onPress={() => setConfirmIssue(null)} />
+          <Button title="Cancel" color="secondary" onPress={() => setConfirmIssueKey(null)} />
           <Button title="Issue" color="primary" onPress={() => confirmIssue && issue(confirmIssue)} />
         </DialogFooter>
       </Dialog>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "16.0.0",
+  "version": "16.2.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -124,6 +124,7 @@
     "./menu_button": "./src/menu_button.tsx",
     "./menu_list_item": "./src/menu_list_item.tsx",
     "./pressable_highlight": "./src/pressable_highlight.tsx",
+    "./pending_commits": "./src/pending_commits.ts",
     "./pressable_row": "./src/pressable_row.tsx",
     "./press_door": "./src/press_door.tsx",
     "./floating_action_bar": "./src/floating_action_bar.tsx",
@@ -151,6 +152,7 @@
     "./use_screen_size": "./src/use_screen_size.ts",
     "./use_auto_grow_height": "./src/use_auto_grow_height.ts",
     "./use_focus_ring": "./src/use_focus_ring.ts",
+    "./use_gated_press": "./src/use_gated_press.ts",
     "./interaction_modality": "./src/interaction_modality.ts",
     "./inline_focus": "./src/inline_focus.ts",
     "./use_hover": "./src/use_hover.ts",
@@ -312,4 +314,4 @@
     "unified": "^11.0.5",
     "vite": "^7.2.4"
   }
-}
+}

package/src/button.tsx CHANGED Viewed

@@ -12,11 +12,12 @@ import { Text } from "./text";
 import { colors } from "./colors";
 import { CONTROL_RADIUS, FOCUS_RING } from "./control_surface";
 import { Icon, IconName } from "./icon";
-import { Ref, useCallback } from "react";
+import { Ref } from "react";
 import { TextColor } from "./text_utils";
 import { useTooltip, UseTooltipOptions } from "./tooltip";
 import { useFocusRing, composeHandler } from "./use_focus_ring";
 import { getButtonIconColor } from "./button_colors";
+import { useGatedPress } from "./use_gated_press";
 export type ButtonColor = "primary" | "secondary" | "danger" | "muted" | "danger-secondary";
 export type ButtonIconPosition = "left" | "right";
@@ -60,20 +61,18 @@ export function Button(props: ButtonProps) {
     accessibilityLabel,
   } = props;
-  const disabledOrLoading = disabled || loading;
+  // The press waits out an inline commit the same gesture started (pending_commits.ts)
+  // and reports busy while it does — so `busy`, not the `loading` prop alone, drives the
+  // spinner, aria-busy, and the double-press block.
+  const { handlePress, waiting } = useGatedPress<NativeSyntheticEvent<any>>(onPress);
+  const busy = loading || waiting;
+  const disabledOrLoading = disabled || busy;
   const tooltipProps = useTooltip(tooltip);
   const { focusVisible, focusProps } = useFocusRing();
-  const handlePress = useCallback(
-    (event: NativeSyntheticEvent<any>) => {
-      onPress?.(event);
-    },
-    [onPress],
-  );
   const children = (
     <>
-      {loading ? (
+      {busy ? (
         <ActivityIndicator color={getButtonIconColor(color)} />
       ) : (
         <>
@@ -107,7 +106,7 @@ export function Button(props: ButtonProps) {
         (typeof tooltip === "string" ? tooltip : tooltip?.text) ||
         undefined
       }
-      aria-disabled={disabledOrLoading || undefined} aria-busy={loading || undefined}
+      aria-disabled={disabledOrLoading || undefined} aria-busy={busy || undefined}
       disabled={disabledOrLoading}
       style={({ pressed, hovered }: PressableStateCallbackType & { hovered?: boolean }) => {
         const isPrimary = color === "primary" && !disabled;