@lotics/ui 27.7.0 → 27.9.0

package/docs/catalog.md

@@ -340,7 +340,12 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`text_utils`** — text/typography plumbing: `getTextColor` (the TextColor→hex map incl.
   the AA-cleared valence set), the Inter `fontFamily*` stacks, and `getInputTextStyle` /
   `getInputLineHeight` — the 16px-mobile/14px-desktop input contract that stops Safari iOS
-  auto-zoom; only for hand-rolled raw inputs.
+  auto-zoom; only for hand-rolled raw inputs. It carries the **ink** as well as the size,
+  because omitting `color` on a native `<input>` does not inherit — it falls to the UA
+  default, pure black, against the `zinc-900` every resting value beside it uses. A field
+  whose text darkens the instant it is focused reads as the text MOVING (at 14px a darkness
+  change re-weights every stroke's antialiasing), which is a bug no box measurement can
+  see. Hand-rolling a raw input means taking this style, not just its font size.
 
 ### Theming, locale & tokens
 
@@ -715,7 +720,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   EVERY `Inline*` editor takes it. `trailing` is decoration only (a chevron, a spinner): it
   renders INSIDE the press target, so a button there would be a button in a button.
   With `actions` the field renders through ONE shell that owns the surface in BOTH modes — so
-  the verbs never move when the editor swaps to its input, the control inside goes `seamless`
+  the verbs never move when the editor opens, the control inside goes `seamless`
   (drawing no second box), hover is tracked on the box (react-native-web hands a parent's hover
   to the innermost pressable, so a control-tracked border drops out as the pointer crosses a
   verb), and the focus ring paints on the whole FIELD via focus-within, not on the value region.

package/docs/composition.md

@@ -286,6 +286,11 @@ leaves the reader no reason to open the chevron.
 
 ## No dead rows — registers & tables
 
+**The identifier leads.** A register's FIRST column is the thing the reader came to find the row
+by — its key, code, or id — because that is what they are scanning against a document, an email,
+or someone on the phone. Pushing it right of a name or a status makes every lookup a hunt across
+the row, and no other column can take its place: a name repeats, a status is shared by dozens.
+
 Every listed record is actionable. PRIMARY entity rows press-open the workspace `Drawer`
 (sequenced — see [master-detail](#master-detail--list--workspace-drawer-with-sequencing));
 read-only drill-downs expand via `Accordion` or glance via `Peek`; every other row gets an
@@ -770,6 +775,15 @@ Anything pressable is ≥ 40px tall (8px minimum gap between pressables). 16px b
 canvas padding, 16–20 inside bands, 10–12 between content lines. Density comes from alignment +
 hierarchy, not cramming.
 
+**The trim test — does this element RESTATE something already on the screen?** Run it over every
+screen before shipping: a per-row proportion bar when the percentage is already on the row; the
+percentage itself when the column holds four values and a total; a state line that only says
+nothing has happened; a gloss explaining the WIDGET rather than the domain. A gloss earns its
+place only by stating a truth that is otherwise INVISIBLE. This is the hardest slop to see and the
+most common, because it survives every other check: each piece is defensible alone, and only the
+question "what does this tell me that the screen does not already say" catches decoration wearing
+an information costume.
+
 ## Testing an overlay component — assert through the logic, prove in a browser
 
 **A `Popover`-backed surface does not mount under jsdom.** It positions in a `useLayoutEffect` +

package/docs/data_entry.md

@@ -46,8 +46,20 @@ narrow containers. A right-floated button aligns to nothing; only OVERLAY footer
 When the whole record is editable (a detail/record screen, dense settings), don't wrap it in a
 form mode or a preview↔edit card — make each VALUE inline-editable: it reads as a value on a quiet
 chip, hover reveals the input-family border (no extra grey wash, no pencil icon that shifts
-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"` (✓ / ✕).
+layout), click OR keyboard focus opens it for editing **with nothing moving** (zero reflow, the
+whole point), and it commits on blur (Enter saves, Escape reverts) or via `controls="buttons"`
+(✓ / ✕).
+
+**How "nothing moves" is achieved differs by editor, and the difference is a rule.** A field whose
+resting value is the RAW string (`InlineTextInput`) is ONE `<input>` in both states — it never
+swaps elements, and `editing` is a style state driven by focus. Two elements cannot be made to
+draw the same string identically: matching the padding, the border and the ink still leaves an
+`<input>` centring by FONT METRICS where a `<div>` positions by LINE BOX, a quarter-CSS-pixel
+residual that no property closes, is invisible to `getBoundingClientRect` (it reports the rounded
+box), and lands on a real device pixel at fractional scaling. Where the resting display is
+FORMATTED and the editor shows something else (`1,250 kg` → `1250`, `31/07/2026` → a segmented
+field), the string changes anyway, so those editors do swap and should. **The rule for a new
+editor: same string in both states ⇒ one element; different string ⇒ swap.**
 
 **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
@@ -77,15 +89,16 @@ 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
-input-swap editor — `InlineTextInput`, `InlineNumberInput`, `InlineTimePicker`,
-`InlineDatePicker` — opens edit mode immediately with the input focused; commit-on-blur then
-makes Tab itself the commit, so the chain is type → Tab → type with the next editor already
-open. Pointer focus never auto-opens (mousedown records "pointer" modality before focus fires
-— `interaction_modality.ts`), so the click path is exactly what it always was. When a
-**keyboard** close (Enter/Escape) leaves focus on `<body>`, the editor returns focus to its
-resting view so the next Tab continues from the field. A **pointer** close (click ✓/✕, or
-click away onto non-focusable space) does NOT restore — a mouse user has no next Tab to
-preserve, and a bare `.focus()` would scroll the target into view, jerking the page (the
+SWAP editor — `InlineNumberInput`, `InlineTimePicker`, `InlineDatePicker` — opens edit mode
+immediately with the input focused; commit-on-blur then makes Tab itself the commit, so the chain
+is type → Tab → type with the next editor already open. Pointer focus never auto-opens (mousedown
+records "pointer" modality before focus fires — `interaction_modality.ts`), so the click path is
+exactly what it always was. `InlineTextInput` needs none of this — its input is always mounted, so
+focus IS the edit by either route. When a **keyboard** close (Enter/Escape) leaves focus on
+`<body>`, a swap editor returns focus to its resting view so the next Tab continues from the
+field (the always-mounted one never loses focus, so there is nothing to restore). A **pointer**
+close (click ✓/✕, or click away onto non-focusable space) does NOT restore — a mouse user has no
+next Tab to preserve, and a bare `.focus()` would scroll the target into view, jerking the page (the
 restore is gated on modality via `shouldRestoreFocusOnClose`).
 
 **Typed dates.** `InlineDatePicker`'s keyboard mode is an internal segmented date field
@@ -131,10 +144,14 @@ One per type:
   a multi `OptionList` (checkbox rows), CLOSING commits the new set in one `onSave` — never a borderless `Select` posing as an inline
   field.
 
-They split across two shared shells. The same-height **input-swap** editors (`InlineTextInput`,
+They split across two shared shells. The same-height **typed** editors (`InlineTextInput`,
 `InlineNumberInput`, `InlineTimePicker`) render **`InlineEditFrame`** driven by the
-**`useInlineEdit`** hook (the view⇄edit toggle, draft buffer, and async save) — swap a custom
-input into that pair to join the family. The **popover** editors (`InlineSelect`,
+**`useInlineEdit`** hook (the draft buffer, async save, and — for the two that swap — the view⇄edit
+toggle) — pass a custom input to that pair to join the family. On the frame, **`editing` means an
+input is MOUNTED** (which element renders, and whether the surface drops its resting padding to
+host one); an always-mounted editor passes it constant and passes the real state as **`editOpen`**,
+which the ✓/✕ verbs read — they assert "there is an edit to accept or reject", so on a resting
+field they would be both a false claim and dead buttons. The **popover** editors (`InlineSelect`,
 `InlineMemberSelect`, `InlineDatePicker`) instead compose **`InlineEditView`**
 (the resting box, wired as the popover trigger) with their OWN `useState` for open/draft/saving/
 error — a pick, not a keystroke, is the edit, so `useInlineEdit` doesn't fit. `onSave` is async

package/package.json

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

package/src/inline_edit.tsx

@@ -34,7 +34,7 @@ export function useInlineEdit<T>(opts: {
   const { value, onSave, equals } = opts;
   const labels = useLoticsLocale().inline;
   const [editing, setEditing] = useState(false);
-  const [draft, setDraft] = useState<T>(value);
+  const [draft, setDraftState] = useState<T>(value);
   const [saving, setSaving] = useState(false);
   const [error, setError] = useState<string | null>(null);
   // Synchronous mirror of `editing`. The first exit (commit or cancel) flips it
@@ -42,8 +42,23 @@ export function useInlineEdit<T>(opts: {
   // input — is then a no-op, so the field commits/cancels exactly once.
   const active = useRef(false);
 
+  // A keystroke IS an edit, so writing the draft re-arms the field. `editing` and
+  // `draft` must never disagree: with `editing` false the field renders the STORED
+  // value, so the keystroke is swallowed AND the trailing blur no-ops — the user
+  // types into a dead field and the text is gone. That state was unreachable while
+  // an editor mounted on demand (Escape unmounted the input, so there was nothing
+  // left to type into); it exists the moment one stays mounted, which
+  // `InlineTextInput` now does — Escape reverts and keeps the caret. Re-arming
+  // cannot double-commit: the exactly-once guard exists to swallow the blur that
+  // TRAILS an exit, and a keystroke after that exit is a new edit that must save.
+  const setDraft = useCallback((next: T) => {
+    active.current = true;
+    setEditing(true);
+    setDraftState(next);
+  }, []);
+
   const begin = useCallback(() => {
-    setDraft(value);
+    setDraftState(value);
     setError(null);
     active.current = true;
     setEditing(true);
@@ -139,7 +154,19 @@ export function useInlineEditFocusRestore(editing: boolean, restore: () => void)
 export type InlineEditVariant = "framed" | "bare";
 
 interface InlineEditFrameProps {
+  /** An input is MOUNTED inside the frame — which element to render, and whether
+   *  the surface drops its resting padding to host one. For an editor that swaps
+   *  this is the same thing as "an edit is open", which is why it was one flag. */
   editing: boolean;
+  /**
+   * Whether an edit is actually OPEN, for an editor where that differs from
+   * `editing` — `InlineTextInput` mounts its input at REST, so it passes
+   * `editing` constant. Only the ✓/✕ verbs read this: they say "there is an edit
+   * to accept or reject", so on a resting field they are a false claim AND dead
+   * (`commit`/`cancel` both no-op with nothing active). Defaults to `editing`,
+   * which is the truth for every editor whose input arrives with the edit.
+   */
+  editOpen?: boolean;
   /** The formatted current value, shown in view mode. Empty → placeholder. */
   display: string;
   placeholder?: string;
@@ -467,6 +494,7 @@ export function InlineEditFrame(props: InlineEditFrameProps) {
   const labels = useLoticsLocale().inline;
   const {
     editing,
+    editOpen,
     display,
     placeholder,
     onBegin,
@@ -582,7 +610,7 @@ export function InlineEditFrame(props: InlineEditFrameProps) {
           ) : null}
         </View>
         )}
-        {controls === "buttons" ? (
+        {controls === "buttons" && (editOpen ?? editing) ? (
           <View style={styles.buttons}>
             <IconButton icon="check" color="primary" size="sm" tooltip={labels.save} onPress={onCommit} disabled={saving} />
             <IconButton icon="x" color="secondary" size="sm" tooltip={labels.cancel} onPress={onCancel} disabled={saving} />

package/src/inline_text_input.tsx

@@ -1,5 +1,6 @@
 import { useCallback, type ReactNode } from "react";
 import type { NativeSyntheticEvent, TextInputKeyPressEventData } from "react-native";
+import { colors } from "./colors";
 import { TextInputField } from "./text_input_field";
 import { type InlineEditVariant, InlineEditFrame, useInlineEdit, type InlineEditControls } from "./inline_edit";
 
@@ -13,15 +14,16 @@ export interface InlineTextInputProps {
    *  an explicit ✓ saves and ✕ reverts. */
   controls?: InlineEditControls;
   disabled?: boolean;
-  /** Strike + mute the resting value (a completed item that stays editable). */
+  /** Strike + mute the value (a completed item that stays editable). It stays
+   *  struck while being edited — the field is one element, so a treatment that
+   *  dropped on focus would be exactly the jump this control exists to avoid. */
   struck?: boolean;
   /** How much frame shows at rest — see {@link InlineEditVariant}. Default "framed". */
   variant?: InlineEditVariant;
   /**
    * Line budget for a value a reader has to read WHOLE rather than recognise —
    * a payment term, an address, a clause. Default 1 (the single-line field).
-   * Above 1 the resting value wraps to that many lines AND the editor opens
-   * multiline at the same height, so the row does not reflow on click. Enter
+   * Above 1 the field is that many lines tall and wraps, in both states. Enter
    * then inserts a newline; the field commits on blur (or the ✓ in "buttons").
    */
   numberOfLines?: number;
@@ -34,10 +36,14 @@ export interface InlineTextInputProps {
 }
 
 /**
- * An inline-editable single-line text value: reads as plain text, reveals an
- * edit affordance on hover, and swaps in-place to a text input on click — at the
- * same height, so the form never reflows. The preferred control for editing a
+ * An inline-editable single-line text value: reads as plain text, darkens on
+ * hover, and opens for editing on focus. The preferred control for editing a
  * value in a dense record / detail surface.
+ *
+ * It is ONE `<input>` in both states — never a resting view swapped for an
+ * editor — so nothing about the value can move when it is focused. See the
+ * comment on `editing` below for why that is load-bearing rather than an
+ * implementation detail.
  */
 export function InlineTextInput(props: InlineTextInputProps) {
   const { value, onSave, placeholder, controls = "blur", disabled, struck, accessibilityLabel , variant, actions, numberOfLines } = props;
@@ -64,7 +70,33 @@ export function InlineTextInput(props: InlineTextInputProps) {
 
   return (
     <InlineEditFrame
-      editing={edit.editing}
+      // ALWAYS the input — this editor never swaps elements, and `editing` is a
+      // STYLE state (focus) rather than a mount.
+      //
+      // The swap was the bug. A resting `Text` and an `<input>` must render the
+      // same string identically, and nothing enforces it: the padding drifted
+      // (8px), then the transparent border (1px), then the ink (zinc-900 vs the
+      // UA's black) — each fixed in turn, each revealing the next. The last one
+      // cannot be fixed at all: measured on an interior 4x crop with no border or
+      // ring in frame, the glyph mass sits 1 DEVICE pixel lower while editing
+      // (row centroid 12.985 -> 13.985, identical ink, identical column
+      // centroid). Both paths compute a 10px text top, so it is not a padding
+      // mistake — an `<input>` centres its text by FONT METRICS and a `<div>`
+      // positions it by LINE BOX, and the residual is a quarter of a CSS pixel.
+      // No amount of matching properties closes it; only rendering one element
+      // does. Hence: one element.
+      //
+      // Scope is this editor alone. Number, date and time keep the swap, because
+      // their resting display is FORMATTED (`1,250 kg`, `31/07/2026`) and their
+      // editor shows something else entirely — the string changes, so a quarter
+      // pixel is not perceptible and an always-input would buy nothing while
+      // costing reformat-on-blur inside a field the user is typing in.
+      editing
+      // ...but the ✓/✕ verbs still key off a REAL edit. `editing` above is a
+      // mount decision now, and the verbs are not: at rest there is nothing to
+      // 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}
       placeholder={placeholder}
       onBegin={edit.begin}
@@ -81,15 +113,44 @@ export function InlineTextInput(props: InlineTextInputProps) {
       actions={actions}
     >
       <TextInputField
-        value={edit.draft}
+        // The DRAFT only exists once editing has begun; before that the field
+        // must show the record's value, or an external update would be masked by
+        // a stale draft from the last edit (`begin` is what syncs them).
+        value={edit.editing ? edit.draft : value}
         onChangeText={edit.setDraft}
+        // Focus IS begin. There is no press-to-open any more: the element the
+        // user clicks is already the editor, so the gesture that used to mount it
+        // now just opens a draft on it. This is also why `autoFocus` is GONE —
+        // mounted permanently, it would have every text field on a record fight
+        // for focus on load.
+        onFocus={edit.begin}
         onBlur={onBlur}
         onKeyPress={onKeyPress}
-        autoFocus
         multiline={multiline}
         numberOfLines={numberOfLines}
         placeholder={placeholder}
         accessibilityLabel={accessibilityLabel}
+        // `disabled`, NOT `editable`: TextInputField derives editability as
+        // `!disabled || editable`, so passing `editable` alone can never turn it
+        // OFF. With the resting button gone, this is the only thing standing
+        // between a read-only field and a typable one.
+        disabled={disabled}
+        // Everything the resting VIEW used to draw, the input now draws, because
+        // there is no resting view left to draw it. Both of these were its job:
+        //
+        // `bare` — the transparent resting edge. Hover and the focus ring are
+        // applied after `style` inside `TextInputField`, so it still darkens on
+        // hover and still rings on focus, from the element that now owns it.
+        //
+        // `struck` — a completed item's value, line-through and muted. This was
+        // applied in `fieldContent`, which only ever runs in the resting view, so
+        // moving to one element silently dropped it: a done task on the board kept
+        // its title upright. Anything else the view used to render has to move the
+        // same way, or it goes the same way — quietly.
+        style={[
+          variant === "bare" ? { borderColor: "transparent", backgroundColor: "transparent" } : null,
+          struck ? { textDecorationLine: "line-through" as const, color: colors.zinc[500] } : null,
+        ]}
         // With verbs on the field, the FRAME owns the surface and the ring.
         seamless={actions != null}
       />

package/src/text_utils.ts

@@ -73,6 +73,25 @@ export const INPUT_LINE_HEIGHT_DESKTOP = 20;
 export const inputTextStyleWeb = {
   fontSize: "var(--input-font-size)",
   lineHeight: "var(--input-line-height)",
+  // THE INK IS PART OF THE CONTRACT, because leaving it out does not mean
+  // "inherit" — a native <input> ignores inherited colour and falls to the UA
+  // default, PURE BLACK, while every resting value beside it renders `zinc-900`.
+  // So a field's own text changed colour the instant it was focused: measured
+  // rgb(24,24,27) at rest against rgb(0,0,0) editing, on an unremarkable text
+  // field. Nothing moved — which is why box geometry, insets, line boxes, fonts
+  // and five widths all measured identical — but at 14px a darkness change
+  // re-weights the antialiasing of every stroke, and the eye reads that as the
+  // text shifting on focus. An EMPTY field hid it completely, since a placeholder
+  // sets its own colour and therefore never changed.
+  //
+  // It lives here rather than in one component because six inputs share this
+  // contract, and an ink re-picked per input is the drift that produced the bug.
+  // `getTextColor()` for the same reason — the default ink has ONE definition and
+  // an input is not the place to restate it. This is a DEFAULT, not a lock: every
+  // consumer applies the caller's `style` after this one, so an app that wants a
+  // different ink still sets it. (It is not the brand accent either way — the theme
+  // is deliberately accent-only, and body ink is not themed.)
+  color: getTextColor(),
 };
 
 /**
@@ -90,6 +109,8 @@ export const inputTextStyleRN = inputTextStyleWeb as unknown as TextStyle;
 const inputTextStyleNative: TextStyle = {
   fontSize: 14,
   lineHeight: 20,
+  // Same ink as the web contract above — an input's text is body ink, not black.
+  color: getTextColor(),
 };
 
 /**