@lotics/ui 46.0.0 → 46.0.2

package/AGENTS.md

@@ -17,7 +17,7 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 | [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` + `loticsResolve()` — the pre-bundle list and the whole `resolve` block a custom-code app's `vite.config.ts` imports rather than hand-carries, dev-link included). 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, choosing a CHOICE control by option count, find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (`InlineFiles` for a record ROW, the `FilesEditor` COMPOUND for a whole section, plus the three-way file INTAKE), stage gates, and the commit-on-blur vs action-press ordering law. |
 | [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 — it turns on WHO supplied the values; findings, provenance, confidence; **after the run** — a stored record that fills up from several writers; the whole run in a dialog, **stopping**; **review surfaces compose from atoms** — `DiffValue`, `DiffMark`, `useChangeSet`. |
-| [docs/composition.md](./docs/composition.md) | The design-language contract — **the form comes before the treatment** (name what the subject IS before reaching for parts), canvas + content column, heading altitude, register vs inset rows, the button ladder, master-detail `Drawer`, the register's rhythm, craft and TRIAGE bands, where the accent goes, theming as an app-level ESCAPE HATCH, color discipline, typography, and where a commit sits. |
+| [docs/composition.md](./docs/composition.md) | The design-language contract — **the form comes before the treatment** (name what the subject IS before reaching for parts), canvas + content column, heading altitude, register vs inset rows, the button ladder, master-detail `Drawer`, the register's rhythm, craft and TRIAGE bands, where the accent goes, theming as an app-level ESCAPE HATCH, color discipline, typography, **one fact one surface** (a chooser over the thing it chooses is a SELECTOR, not a second card grid; a control that only swaps one number for another is replaced by showing both), and where a commit sits. |
 | [docs/reviewing.md](./docs/reviewing.md) | **Reviewing a screen you built** — the other docs say what good looks like; this one says how to find out whether you achieved it. GATES that outrank every treatment question, then 11 probes each naming what to COLLECT and the SIGNATURE in the numbers. Plus the extraction snippets, what measurement cannot see, and how to act on a finding. |
 | [docs/testing.md](./docs/testing.md) | Driving the kit in a browser — the three anatomies where the a11y tree says one thing and a driver must do another: a `PressDoor` row whose named button always intercepts pointer events (by design), portalled overlays that render at the top of the DOM, and custom pointer drag that `dragTo` cannot move. |
 | [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) and the ACTIVITY shape — a communications feed where the row's label is the GIST and the body varies by medium, one anatomy rather than a row type per kind. |

package/docs/composition.md

@@ -467,6 +467,28 @@ INFORMATIONAL — they never filter or navigate (that's the tabs/chips' job); if
 cross-cutting numbers, drop them. Do NOT put a `KPIStrip` on a register page or a `SummaryLine` on
 a dashboard. Card stat rails use `KPICard`.
 
+## One fact, one surface — and no control that only reveals a number
+
+Two rules that catch the same defect from opposite ends: a screen saying one thing twice.
+
+**A selector and a detail view must not carry the same fact at the same weight.** When a compact
+chooser sits above the thing it chooses — a set of presets over the options they combine, a filter
+row over the facets it sets — the chooser is a SELECTOR and gets one line per item, and the surface
+below carries the detail. Render both as cards and the reader has to work out that the parts add up
+to the whole they already read, which is a puzzle the screen created for them. The tell is a section
+whose two halves are the same height: whichever one is a *shortcut* to the other should be a
+fraction of it.
+
+**A control whose only job is to swap one number for another is more machinery than showing both.**
+A billing-cycle toggle, a unit switch, a per-seat/per-month flip — each hides one figure behind a
+click and adds a piece of state the rest of the screen has to respect. State both: the primary as
+the headline, the alternative as a line under it. This also fixes an ordering problem the toggle
+creates, because it asks the reader to decide something secondary (how it is counted) before they
+have decided the thing itself (which one they want).
+
+The toggle earns its place when the two states differ in more than a number — different rows,
+different units, a different shape of answer. Swapping `1.700.000` for `2.000.000` is not that.
+
 ## Numbers, money, dates
 
 - Free-standing numerals: `<Text tabular>` — always.

package/docs/data_entry.md

@@ -186,6 +186,19 @@ row the screen copied into `useState` (`app-sdk` `docs/mutations.md` § A read m
 an in-flight write) — as does a write started by something other than an inline commit (a
 dialog save, a debounced autosave).
 
+**A field counts its own committed value as current until `value` catches up.** A caller updates
+its stored copy only when the write RETURNS, so for the length of that round trip the `value` prop
+still reads PRE-EDIT. Anything that re-opens the field in that window — a keyboard focus restore,
+a second tap, a click into the neighbouring control — must not re-arm from that stale prop, because
+the next blur would commit it as a fresh edit and the field would silently UNDO the edit it just
+saved. `useInlineEdit` holds what it last sent and treats that as the current value for both the
+re-arm and the "unchanged?" test, so a trailing commit of an already-sent value is a no-op; it also
+renders that value (`edit.current`), so the old number never flashes back mid-write. The held copy
+is dropped the moment `value` moves — whether it echoes the edit back or takes a different value
+entirely — so it can never mask a change the field did not make. Nothing to wire up. This is not
+theoretical: re-arming from the stale prop put a fee back to its pre-edit amount ~3s after an
+operator corrected it, and the irreversible document minted seconds later billed the wrong figure.
+
 ### Keyboard entry — type → Tab → type
 
 Bulk entry never needs the mouse. KEYBOARD focus (Tab / Shift+Tab) landing on a closed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "46.0.0",
+  "version": "46.0.2",
   "type": "module",
   "exports": {
     "./vite": {

package/src/inline_edit.tsx

@@ -37,6 +37,29 @@ export function useInlineEdit<T>(opts: {
   const [draft, setDraftState] = useState<T>(value);
   const [saving, setSaving] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const eq = useCallback((a: T, b: T) => (equals ? equals(a, b) : a === b), [equals]);
+
+  // What this field last handed to `onSave`, held until `value` catches up to it.
+  //
+  // `value` is the caller's stored copy, and a caller does not update it until its
+  // write returns — so for the length of that round trip the prop still reads the
+  // PRE-EDIT value. Anything that re-opens the field in that window (a focus
+  // restore, a second tap) would otherwise seed the draft from a value the user
+  // has already replaced, and the next blur would commit it as if it were a fresh
+  // edit: the field silently undoes the edit it just saved. In an app where the
+  // field holds an amount that is about to be invoiced, that writes the wrong
+  // number to a document nobody can re-issue.
+  //
+  // `before` is what `value` read at commit time. The moment `value` differs from
+  // it the parent has moved on — whether by echoing this edit back or by taking a
+  // different value from somewhere else — and the pending copy is dropped rather
+  // than masking a change the field did not make.
+  const pending = useRef<{ committed: T; before: T } | null>(null);
+  const held = pending.current;
+  const awaitingEcho = held !== null && eq(held.before, value);
+  if (held !== null && !awaitingEcho) pending.current = null;
+  /** The value the field must behave as if it holds — see `pending`. */
+  const current = awaitingEcho && held !== null ? held.committed : value;
   // Synchronous mirror of `editing`. The first exit (commit or cancel) flips it
   // false; any trailing call — e.g. the blur that fires as Escape unmounts the
   // input — is then a no-op, so the field commits/cancels exactly once.
@@ -58,11 +81,11 @@ export function useInlineEdit<T>(opts: {
   }, []);
 
   const begin = useCallback(() => {
-    setDraftState(value);
+    setDraftState(current);
     setError(null);
     active.current = true;
     setEditing(true);
-  }, [value]);
+  }, [current]);
 
   const cancel = useCallback(() => {
     if (!active.current) return;
@@ -75,8 +98,9 @@ export function useInlineEdit<T>(opts: {
     async (next?: T) => {
       if (!active.current) return;
       const candidate = next === undefined ? draft : next;
-      const unchanged = equals ? equals(candidate, value) : candidate === value;
-      if (unchanged) {
+      // Against `current`, not `value`: re-committing what this field already
+      // saved is a no-op, not an edit back to the stored copy.
+      if (eq(candidate, current)) {
         active.current = false;
         setEditing(false);
         return;
@@ -84,6 +108,7 @@ export function useInlineEdit<T>(opts: {
       active.current = false;
       setSaving(true);
       setError(null);
+      pending.current = { committed: candidate, before: value };
       try {
         // 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 —
@@ -92,6 +117,9 @@ export function useInlineEdit<T>(opts: {
         await trackCommit((async () => onSave(candidate))());
         setEditing(false);
       } catch (e) {
+        // Nothing was stored, so there is no echo to wait for — drop the pending
+        // copy or the field would keep reporting a value the caller never took.
+        pending.current = null;
         // Stay in edit mode so the entry isn't lost — show the error, re-arm.
         setError(e instanceof Error && e.message ? e.message : labels.saveError);
         active.current = true;
@@ -99,10 +127,13 @@ export function useInlineEdit<T>(opts: {
         setSaving(false);
       }
     },
-    [draft, value, onSave, equals],
+    [draft, value, current, onSave, eq, labels.saveError],
   );
 
-  return { editing, draft, setDraft, saving, error, begin, cancel, commit };
+  // `current` is what the field must SHOW as well as what it re-arms from: while a
+  // save is in flight the caller's `value` still reads pre-edit, and rendering that
+  // flashes the old number back at the operator mid-write.
+  return { editing, draft, setDraft, saving, error, begin, cancel, commit, current };
 }
 
 /**

package/src/inline_markdown.tsx

@@ -57,7 +57,7 @@ export function InlineMarkdown(props: InlineMarkdownProps) {
       // ...but the ✓/✕ verbs still key off a REAL edit: at rest there is nothing
       // to accept and nothing to revert.
       editOpen={edit.editing}
-      display={value}
+      display={edit.current}
       placeholder={placeholder}
       onBegin={edit.begin}
       controls="blur"

package/src/inline_number_input.tsx

@@ -45,7 +45,9 @@ export function InlineNumberInput(props: InlineNumberInputProps) {
     void edit.commit();
   }, [controls, edit]);
 
-  const display = format ? format(value) : value == null ? "" : String(value);
+  // `edit.current` rather than `value`: while a save is in flight the caller's
+  // copy still reads pre-edit, and showing that flashes the old number back.
+  const display = format ? format(edit.current) : edit.current == null ? "" : String(edit.current);
 
   return (
     <InlineEditFrame

package/src/inline_text_input.tsx

@@ -158,7 +158,7 @@ export function InlineTextInput(props: InlineTextInputProps) {
       // accept and nothing to revert, so rendering them would both claim
       // otherwise and hand the user two buttons that no-op.
       editOpen={edit.editing}
-      display={value}
+      display={edit.current}
       placeholder={placeholder}
       onBegin={edit.begin}
       controls={controls}