@lotics/ui 16.0.0 → 16.1.0

package/AGENTS.md

@@ -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

@@ -611,7 +611,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `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`

package/docs/data_entry.md

@@ -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

package/docs/templates.md

@@ -329,7 +329,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

@@ -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

@@ -345,7 +345,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 +413,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 +835,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);
@@ -1238,6 +1243,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 +1254,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)) });
   };
 
@@ -2124,7 +2132,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 +2593,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 +2609,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

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "16.0.0",
+  "version": "16.1.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",

package/src/button.tsx

@@ -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;

package/src/icon_button.tsx

@@ -4,8 +4,9 @@ import { colors } from "./colors";
 import { PressableHighlight } from "./pressable_highlight";
 import { type ButtonColor } from "./button";
 import { getButtonIconColor } from "./button_colors";
-import { Ref, useCallback } from "react";
+import { Ref } from "react";
 import { TooltipSide } from "./tooltip";
+import { useGatedPress } from "./use_gated_press";
 
 interface IconButtonBase {
   ref?: Ref<View>;
@@ -61,14 +62,12 @@ export function IconButton(props: IconButtonProps) {
     style,
   } = props;
 
-  const handlePress = useCallback(
-    (event: GestureResponderEvent) => {
-      onPress?.(event);
-    },
-    [onPress],
-  );
+  // The press waits out an inline commit the same gesture started (pending_commits.ts)
+  // and reports busy while it does — `busy` drives the spinner + the double-press block.
+  const { handlePress, waiting } = useGatedPress<GestureResponderEvent>(onPress);
+  const busy = loading || waiting;
 
-  const disabledOrLoading = disabled || loading;
+  const disabledOrLoading = disabled || busy;
   const tint =
     iconColor ??
     (color === "none" ? colors.zinc[700] : color === "white" ? colors.white : getButtonIconColor(color));
@@ -88,7 +87,7 @@ export function IconButton(props: IconButtonProps) {
       // without shifting surrounding layouts.
       hitSlop={size === "lg" ? 0 : size === "sm" ? 8 : 6}
     >
-      {loading ? (
+      {busy ? (
         <ActivityIndicator size="small" color={tint} />
       ) : (
         <Icon size={size === "sm" ? 14 : size === "lg" ? 20 : 18} name={icon} color={tint} />

package/src/inline_edit.tsx

@@ -10,6 +10,7 @@ import { FOCUS_RING, CONTROL_RADIUS, HOVER_BORDER, CONTROL_TRANSITION } from "./
 import { fontFamilyRegular, getInputTextStyle, getTextColor, type TextColor } from "./text_utils";
 import { getInteractionModality } from "./interaction_modality";
 import { shouldOpenOnFocus, shouldRestoreFocusOnClose } from "./inline_focus";
+import { trackCommit } from "./pending_commits";
 
 /** The kit's standard control height (TextInputField, NumberInput, Picker, …).
  *  The view box matches it — same height, padding, and a 1px transparent border
@@ -69,7 +70,11 @@ export function useInlineEdit<T>(opts: {
       setSaving(true);
       setError(null);
       try {
-        await onSave(candidate);
+        // Registered so an action pressed in the SAME gesture (the press that caused
+        // this blur) waits for the write instead of reading the pre-edit record —
+        // see pending_commits.ts. The IIFE starts `onSave` synchronously, so the
+        // write still leaves on mousedown, and turns a sync throw into a rejection.
+        await trackCommit((async () => onSave(candidate))());
         setEditing(false);
       } catch (e) {
         // Stay in edit mode so the entry isn't lost — show the error, re-arm.

package/src/pending_commits.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from "vitest";
+import { pendingCommits, trackCommit } from "./pending_commits";
+
+/** A field write that lands in `stored` after `ms`, like a save round trip. */
+const commit = (stored: { value: string }, next: string, ms: number) =>
+  new Promise<void>((resolve) =>
+    setTimeout(() => {
+      stored.value = next;
+      resolve();
+    }, ms),
+  );
+
+/** Let the registry's own settle callback run before asserting on it. */
+const tick = () => new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+describe("pendingCommits", () => {
+  it("is null with nothing in flight — a press keeps its synchronous path", () => {
+    expect(pendingCommits()).toBeNull();
+  });
+
+  it("holds until a commit still in flight has landed", async () => {
+    const stored = { value: "BKG CŨ: " };
+    void trackCommit(commit(stored, "BKG CŨ:  SGNA52926200", 20));
+    const gate = pendingCommits();
+    expect(gate).not.toBeNull();
+    await gate;
+    expect(stored.value).toBe("BKG CŨ:  SGNA52926200");
+  });
+
+  it("holds for EVERY commit in flight, not just the first", async () => {
+    const landed: string[] = [];
+    const land = (name: string, ms: number) =>
+      new Promise<void>((resolve) =>
+        setTimeout(() => {
+          landed.push(name);
+          resolve();
+        }, ms),
+      );
+    void trackCommit(land("slow", 30));
+    void trackCommit(land("fast", 5));
+    await pendingCommits();
+    expect([...landed].sort()).toEqual(["fast", "slow"]);
+  });
+
+  it("releases again once the commits have landed", async () => {
+    await trackCommit(Promise.resolve());
+    await tick();
+    expect(pendingCommits()).toBeNull();
+  });
+
+  it("is released by a FAILED commit too — a stuck gate would wedge every action", async () => {
+    const failed = trackCommit(Promise.reject(new Error("Save failed")));
+    // The caller owns the error: the inline editor keeps the edit and shows it.
+    await expect(failed).rejects.toThrow("Save failed");
+    await expect(pendingCommits() ?? Promise.resolve()).resolves.toBeUndefined();
+    await tick();
+    expect(pendingCommits()).toBeNull();
+  });
+
+  it("ignores a commit started AFTER the gate was taken — it holds the press for the edit that caused it, not later work", async () => {
+    const stored = { value: "before" };
+    void trackCommit(commit(stored, "first", 5));
+    const gate = pendingCommits();
+    void trackCommit(commit(stored, "later", 40));
+    await gate;
+    expect(stored.value).toBe("first");
+  });
+});

package/src/pending_commits.ts

@@ -0,0 +1,45 @@
+/**
+ * Inline commits that are still writing, app-wide.
+ *
+ * An inline editor commits on BLUR, so pressing an action while a field is focused
+ * starts TWO things in ONE gesture: the field's write (the blur, on mousedown) and
+ * the action's handler (on mouseup). A handler that re-reads the record — to print a
+ * document, mint an invoice, copy the row — otherwise overtakes the still-in-flight
+ * write and acts on the PRE-EDIT value. It fails silently: the screen shows the new
+ * value and the output carries the old one.
+ *
+ * `useInlineEdit` registers every commit here and `Button`/`IconButton` hold their
+ * press for the ones already in flight, so the press lands AFTER the edit that caused
+ * it. There is nothing for an app to wire up, and nothing it can forget.
+ */
+
+const inFlight = new Set<Promise<void>>();
+
+/**
+ * Register a commit. Returns it UNCHANGED — the caller keeps its own result and error
+ * handling; the gate only needs to know when the write SETTLED, so a failed commit
+ * releases it just like a successful one (the field surfaces its own error).
+ */
+export function trackCommit<T>(commit: Promise<T>): Promise<T> {
+  const settled = commit.then(
+    () => undefined,
+    () => undefined,
+  );
+  inFlight.add(settled);
+  void settled.then(() => {
+    inFlight.delete(settled);
+  });
+  return commit;
+}
+
+/**
+ * The commits in flight RIGHT NOW, or `null` when there are none — a caller takes its
+ * synchronous path on `null`, so a press with nothing pending behaves exactly as it
+ * always did. Commits started after this call are deliberately NOT awaited: the gate
+ * holds a press for the edit that caused it, never for later work.
+ */
+export function pendingCommits(): Promise<void> | null {
+  if (inFlight.size === 0) return null;
+  const snapshot = Array.from(inFlight);
+  return Promise.all(snapshot).then(() => undefined);
+}

package/src/use_gated_press.ts

@@ -0,0 +1,41 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { pendingCommits } from "./pending_commits";
+
+/**
+ * Makes an action's press land AFTER any inline commit the same gesture started —
+ * see {@link pendingCommits} for the race it closes.
+ *
+ * With nothing in flight the press dispatches SYNCHRONOUSLY, exactly as before, so the
+ * gate is invisible outside the racing case. While waiting the action reports busy, so
+ * the gesture reads as "working" rather than "ignored" and cannot double-fire.
+ */
+export function useGatedPress<E>(onPress?: (event: E) => void) {
+  const [waiting, setWaiting] = useState(false);
+  // Re-armed on mount: a StrictMode remount must not leave the ref stuck at false.
+  const mounted = useRef(true);
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+
+  const handlePress = useCallback(
+    (event: E) => {
+      const pending = pendingCommits();
+      if (!pending) {
+        onPress?.(event);
+        return;
+      }
+      setWaiting(true);
+      void pending.then(() => {
+        if (!mounted.current) return;
+        setWaiting(false);
+        onPress?.(event);
+      });
+    },
+    [onPress],
+  );
+
+  return { handlePress, waiting };
+}