@lotics/ui 11.7.4 → 11.8.0

package/AGENTS.md

@@ -25,7 +25,7 @@ doc before building any screen, **never from memory**. Exact props are the shipp
 | [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, stage gates. |
 | [docs/ai_patterns.md](./docs/ai_patterns.md) | AI proposes, the human decides — composer, live run feed (`AgentRun`), review-before-apply, 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). |
+| [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). |
 
 ## Iron rules
 

package/docs/catalog.md

@@ -516,7 +516,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 ### Dates & times
 
 - **`date_picker`** — `DatePicker` (+ `DatePickerPanel`, `DatePickerLabels`): the field-form
-  date (and datetime) picker.
+  date (and datetime) picker. The trigger is the segmented, locale-ordered `DateField`
+  (typed digits auto-advance; a typed separator advances a single-digit day/month) plus the
+  calendar popover.
 - **`date_calendar`** — `Calendar`: the bare month grid — `mode="single"` or `"range"`
   (`{start,end}` — two months side by side on desktop), month/year pickers + arrows,
   localized weekday/month names via BCP-47 `locale`, `firstDayOfWeek` (default Monday),
@@ -534,11 +536,15 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `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"`; `background="tint" | "transparent"` (the zinc-50 editability chip vs
+  `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; `background="tint" | "transparent"` (the zinc-50 editability chip vs
   flat for dense uniformly-editable surfaces).
 - **`inline_text_input`**, **`inline_number_input`** (`format` for currency/units),
   **`inline_select`**, **`inline_member_select`**, **`inline_date_picker`**
-  (`format="datetime"`, `optionalTime`), **`inline_time_picker`** — the Inline\* per-field
+  (`format="datetime"`, `optionalTime`; keyboard focus opens the TYPED segmented `DateField`
+  — locale field order, separator advances, Alt+ArrowDown floats the calendar; click still
+  opens the calendar popover), **`inline_time_picker`** — the Inline\* per-field
   editors; `InlineSelect`/`InlineMemberSelect` render the resting value like its option —
   `renderOptionContent` by default, `renderSelected` to override — a chip/badge at rest, not
   just text.
@@ -925,5 +931,12 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   input.
 - **`use_focus_ring`** — `useFocusRing`: keyboard-aware focus state for painting a control's
   own ring.
+- **`interaction_modality`** — the document-level keyboard-vs-pointer tracker behind
+  `useFocusRing` and the inline editors' focus-opens-edit: `getInteractionModality()` read
+  inside a focus handler tells a Tab-focus from a click-focus (the `:focus-visible` signal).
+- **`inline_focus`** — `shouldOpenOnFocus` + `FOCUS_OPEN_SUPPRESS_MS`: the inline
+  keyboard-entry gate — keyboard focus opens a closed editor, pointer focus never does, and
+  a programmatic focus restore inside the suppression window doesn't re-open the editor it
+  just closed.
 - **`json_panel`** — `JsonPanel` (`{title, value}`) + `stringifyData`: a labeled monospace
   panel for raw/JSON payloads (debug & developer surfaces).

package/docs/data_entry.md

@@ -29,8 +29,31 @@ in [the templates](./templates.md) (`examples/tpl_*.tsx`).
 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 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"` (✓ primary / ✕).
+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"` (✓ / ✕).
+
+### 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 an editor
+closes while its input still holds focus (Enter/Escape), it returns focus to its resting view
+— never `<body>` — so the next Tab continues from the field.
+
+**Typed dates.** `InlineDatePicker`'s keyboard mode is the kit's segmented `DateField`: type
+the date in the locale's own field order (dd/MM/yyyy where the locale says so — pass
+`locale`), digits auto-advance, and a typed separator (`/` `.` `-`) advances a single-digit
+day/month; Enter or blur commits, Escape reverts, Alt+ArrowDown floats the calendar. The
+calendar popover stays the pointer path (click the resting value, as ever) — it is no longer
+the only path. A PARTIAL entry never commits and never clears the stored value: the field
+stays in edit mode showing the `datePicker.invalidDate` inline error until fixed or Escaped.
+
+The POPOVER editors (`InlineSelect` / `InlineMemberSelect` / `InlineTagSelect`) deliberately
+do NOT auto-open on focus — a popup opening on Tab arrival traps traversal; per the WAI-ARIA
+combobox contract they open on Enter/Space from the keyboard.
 
 One per type:
 

package/docs/templates.md

@@ -48,6 +48,47 @@ the package index is [../AGENTS.md](../AGENTS.md).
 | AI ranks answers — look-up-and-explain | `tpl_lookup` |
 | AI over a record's documents (extract / cross-check / generate) | `tpl_documents` |
 
+## Composition rules — how a record surface is assembled
+
+Laws for any screen where a record's data is edited and a primary action produces its output
+(a document, a message, an export) — `tpl_record` is the worked example.
+
+1. **Pipeline order.** Data sections run top→bottom in the order work flows (intake/scan near
+   the top when AI-driven); the OUTPUT section — the primary action plus everything that
+   configures it — comes LAST. The primary action is the output step of the pipeline, never
+   header chrome.
+2. **Static shape.** The page never changes shape from output-selection state. Conditional
+   rendering is DATA-driven only (a control appears because two stored values differ), never
+   selection-driven. Relevance is an advisory `Callout` with a jump-to-section action — warn,
+   never hide, never hard-block.
+3. **Colocation & ownership.** Every output option (selections, print/export switches) lives in
+   the output section beside its action; a per-entity selection carries its owner's name in its
+   heading. Persisted record DATA never lives there — data belongs in data sections. Misfiled
+   data announces itself as callout special-cases; the exception disappearing is the sign the
+   model is right.
+4. **Resolved state.** Controls show the EFFECTIVE state, never raw storage: a derived/suggested
+   selection renders checked; the first manual change persists the full explicit set; a
+   reset-to-auto affordance appears only in explicit mode. What's shown = what happens.
+5. **Decision budget.** Every user decision earns its place — derive it, default it, or
+   conditionally render it; ask only the underivable. Suggestions are one-tap-save chips; a
+   placeholder states the honest effective fallback (what actually happens when empty), never
+   an example that lies.
+6. **Header = identity + provenance.** Id, the key identifier, created-at. No metrics or badges
+   duplicating data a section already owns.
+7. **Destructive placement.** Solid `danger`, bottom-left after the entity's fields, ONE
+   convention page-wide, confirmed by `Alert`. Never in a heading row, never one-tap.
+8. **Create-then-refine.** An add is one click creating a draft edited in place — drafts render
+   as empty inline editors with placeholders, never as fake data. No type-a-name-then-click
+   forms.
+9. **Optimistic feedback.** Every edit echoes locally, saves in the background, reconciles on
+   refetch, reverts + surfaces on error. Silent success, loud failure — no persistent "saved"
+   chrome.
+10. **Chrome discipline.** Kit spacing scale only; ONE divider rule (between sibling blocks,
+    never doubled with section hairlines, none trailing); no state-echo labels or filler
+    captions — explanations live in `info` popovers and empty states (→ [composition grammar
+    §Microcopy](./composition.md)). A "why" question about a control is answered by tracing
+    its consequences, not by swapping the control.
+
 ## Analytics
 
 Read-mostly screens that answer a question about a population, then open doors into the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "11.7.4",
+  "version": "11.8.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",

package/src/date_field.tsx

@@ -25,6 +25,15 @@ export interface DateFieldProps {
   onActivate?: () => void;
   /** Fires once focus leaves the whole field. */
   onBlur?: () => void;
+  /** Focus the first segment on mount (an inline editor entered by keyboard). */
+  autoFocus?: boolean;
+  /** Escape pressed in a segment — an inline editor cancels its session. */
+  onEscape?: () => void;
+  /** Alt+ArrowDown pressed in a segment — open the calendar popover. */
+  onOpenPicker?: () => void;
+  /** Reports whether ANY part holds a partial entry (typed but not yet a
+   *  complete valid date) — an inline editor blocks its commit on it. */
+  onIncompleteChange?: (incomplete: boolean) => void;
   /** Rendered inside the border, after the segments (the calendar button). */
   rightSlot?: React.ReactNode;
   /** Ref to the frame, used to anchor the popover. */
@@ -51,12 +60,17 @@ export function DateField(props: DateFieldProps) {
     testID,
     onActivate,
     onBlur,
+    autoFocus,
+    onEscape,
+    onOpenPicker,
+    onIncompleteChange,
     rightSlot,
     triggerRef,
     style,
   } = props;
 
   const [focused, setFocused] = useState(false);
+  const incompleteParts = useRef<boolean[]>([]);
   const { hovered, hoverProps } = useHover();
   const blurTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
 
@@ -89,6 +103,14 @@ export function DateField(props: DateFieldProps) {
     if (!disabled) onActivate?.();
   }, [disabled, onActivate]);
 
+  const handleIncomplete = useCallback(
+    (index: number, incomplete: boolean) => {
+      incompleteParts.current[index] = incomplete;
+      onIncompleteChange?.(incompleteParts.current.some(Boolean));
+    },
+    [onIncompleteChange],
+  );
+
   const config = useMemo(() => dateSegmentsConfig(locale ?? "en-US", hasTime), [locale, hasTime]);
 
   const isEmpty = parts.every((part) => !part);
@@ -122,9 +144,13 @@ export function DateField(props: DateFieldProps) {
               config={config}
               segmentLabels={segmentLabels}
               disabled={disabled}
+              autoFocus={autoFocus && index === 0}
               accessibilityLabel={partLabels?.[index]}
               onFocus={handleSegmentFocus}
               onBlur={handleSegmentBlur}
+              onEscape={onEscape}
+              onOpenPicker={onOpenPicker}
+              onIncompleteChange={onIncompleteChange ? (inc) => handleIncomplete(index, inc) : undefined}
             />
           </React.Fragment>
         ))}

package/src/date_picker.tsx

@@ -50,6 +50,8 @@ export interface DatePickerLabels extends SegmentLabels {
   endTime: string;
   /** Footer action: commit and close the popover. */
   done: string;
+  /** Inline error when a typed date is left incomplete/invalid (never committed). */
+  invalidDate: string;
   /** Quick action: add a time to a date-only value (`optionalTime`). */
   addTime: string;
   /** Accessible name + tooltip: drop the time, keeping the date (`optionalTime`). */

package/src/date_picker_value.test.ts

@@ -3,6 +3,7 @@ import {
   parsePart,
   partsToIso,
   parseText,
+  resolveDateCommit,
   timeText,
   splitTime,
   isoToDate,
@@ -165,3 +166,39 @@ describe("parseTimeString", () => {
     expect(parseTimeString("")).toBeNull();
   });
 });
+
+describe("resolveDateCommit — the inline editor's commit contract", () => {
+  it("a typed complete date commits the value", () => {
+    expect(
+      resolveDateCommit({ draft: "2026-03-15", value: "2026-01-01", incomplete: false, clearable: false }),
+    ).toEqual({ kind: "save", value: "2026-03-15" });
+    // …including onto an empty field.
+    expect(
+      resolveDateCommit({ draft: "2026-03-15", value: null, incomplete: false, clearable: false }),
+    ).toEqual({ kind: "save", value: "2026-03-15" });
+  });
+
+  it("a partial entry never commits and never clears the stored value", () => {
+    expect(
+      resolveDateCommit({ draft: "2026-01-01", value: "2026-01-01", incomplete: true, clearable: true }),
+    ).toEqual({ kind: "invalid" });
+  });
+
+  it("an unchanged draft exits without a write (a touched-but-equal date is not a diff)", () => {
+    expect(
+      resolveDateCommit({ draft: "2026-01-01", value: "2026-01-01", incomplete: false, clearable: true }),
+    ).toEqual({ kind: "none" });
+    expect(resolveDateCommit({ draft: "", value: null, incomplete: false, clearable: true })).toEqual({
+      kind: "none",
+    });
+  });
+
+  it("an emptied entry clears only when the field is clearable", () => {
+    expect(
+      resolveDateCommit({ draft: "", value: "2026-01-01", incomplete: false, clearable: true }),
+    ).toEqual({ kind: "clear" });
+    expect(
+      resolveDateCommit({ draft: "", value: "2026-01-01", incomplete: false, clearable: false }),
+    ).toEqual({ kind: "none" });
+  });
+});

package/src/date_picker_value.ts

@@ -123,6 +123,36 @@ export function dropTime(iso: string): string {
   return p ? partsToIso(p, false) : "";
 }
 
+/** What committing an inline date edit session should do. */
+export type InlineDateCommit =
+  | { kind: "save"; value: string }
+  | { kind: "clear" }
+  | { kind: "none" }
+  | { kind: "invalid" };
+
+/**
+ * Resolve an inline date editor's commit (blur / Enter / popover close).
+ * `draft` is the last COMPLETE value the session produced ("" when emptied);
+ * `incomplete` is true while the segments hold a partial entry (a typed day
+ * with no year). Partial input never commits and never wipes the stored value —
+ * the caller shows the error affordance and keeps the entry ("invalid"). An
+ * emptied draft clears only when the field is clearable; otherwise it reverts
+ * silently, matching the calendar's own Clear on a required date.
+ */
+export function resolveDateCommit(opts: {
+  draft: string;
+  value: string | null;
+  incomplete: boolean;
+  clearable: boolean;
+}): InlineDateCommit {
+  const { draft, value, incomplete, clearable } = opts;
+  if (incomplete) return { kind: "invalid" };
+  const stored = value ?? "";
+  if (draft === stored) return { kind: "none" };
+  if (draft === "") return clearable && stored ? { kind: "clear" } : { kind: "none" };
+  return { kind: "save", value: draft };
+}
+
 const TIME_RE = /^(\d{1,2}):(\d{2})$/;
 
 /**

package/src/date_segments.test.ts

@@ -7,6 +7,7 @@ import {
   from12h,
   typeDigit,
   incrementSegment,
+  separatorAdvances,
   setHourField,
   withDayPeriod,
   displayValue,
@@ -101,6 +102,50 @@ describe("typeDigit", () => {
   });
 });
 
+describe("typed date entry — the inline keyboard path", () => {
+  // Simulate the segment engine's typing pipeline: each keystroke flows through
+  // typeDigit in the locale's own field order; the buffer then resolves through
+  // segmentsToValue. This is the outcome contract behind "type 15/03/2026 into
+  // an inline date editor and it commits".
+  it("a typed dd/MM/yyyy date composes the committed ISO value (vi-VN order)", () => {
+    expect(fieldOrder(getDateLayout("vi-VN", false))).toEqual(["day", "month", "year"]);
+    const day = typeDigit("day", typeDigit("day", "", "1", false).text, "5", false);
+    expect(day).toEqual({ text: "15", value: 15, complete: true });
+    const month = typeDigit("month", typeDigit("month", "", "0", false).text, "3", false);
+    expect(month).toEqual({ text: "03", value: 3, complete: true });
+    let yearText = "";
+    for (const digit of ["2", "0", "2", "6"]) yearText = typeDigit("year", yearText, digit, false).text;
+    const buffer = { year: Number(yearText), month: month.value, day: day.value, hour: null, minute: null };
+    expect(segmentsToValue(buffer, false)).toBe("2026-03-15");
+  });
+
+  it("a single-digit d/M/yyyy entry advances on the separator and still commits", () => {
+    // "1/1/2026": neither "1" can auto-advance (a second digit could still
+    // fit — "12", "11") — the typed "/" is the explicit advance.
+    const day = typeDigit("day", "", "1", false);
+    expect(day.complete).toBe(false);
+    expect(separatorAdvances("/", day.text !== "")).toBe(true);
+    const month = typeDigit("month", "", "1", false);
+    expect(month.complete).toBe(false);
+    expect(separatorAdvances("/", month.text !== "")).toBe(true);
+    const buffer = { year: 2026, month: month.value, day: day.value, hour: null, minute: null };
+    expect(segmentsToValue(buffer, false)).toBe("2026-01-01");
+  });
+
+  it("separators advance only off a segment that has content", () => {
+    for (const key of ["/", ".", "-", ",", ":", " "]) {
+      expect(separatorAdvances(key, true)).toBe(true);
+      expect(separatorAdvances(key, false)).toBe(false);
+    }
+    expect(separatorAdvances("a", true)).toBe(false);
+    expect(separatorAdvances("ArrowDown", true)).toBe(false);
+  });
+
+  it("an impossible typed date never composes a value", () => {
+    expect(segmentsToValue({ year: 2026, month: 2, day: 30, hour: null, minute: null }, false)).toBeNull();
+  });
+});
+
 describe("incrementSegment", () => {
   it("wraps within range", () => {
     expect(incrementSegment("month", 12, 1, false)).toBe(1);

package/src/date_segments.ts

@@ -230,6 +230,17 @@ export function typeDigit(
   return { text, value, complete };
 }
 
+/**
+ * A typed separator ("15/3", "15.3.2026") advances to the next segment — the
+ * forgiveness that makes single-digit entry work: "1" alone can't auto-advance
+ * (it might be "12"), so the separator is the typist's explicit "done here".
+ * Only advances off a segment that HAS content (committed or in-progress);
+ * a leading separator is a no-op, matching native date inputs.
+ */
+export function separatorAdvances(key: string, segmentHasContent: boolean): boolean {
+  return segmentHasContent && (key === "/" || key === "." || key === "-" || key === "," || key === " " || key === ":");
+}
+
 /** Step a numeric segment up/down, wrapping within its range. */
 export function incrementSegment(
   type: SegmentType,

package/src/date_segments_field.tsx

@@ -21,6 +21,7 @@ import {
   fieldOrder,
   incrementSegment,
   placeholderFor,
+  separatorAdvances,
   setHourField,
   to12h,
   typeDigit,
@@ -44,6 +45,16 @@ export interface DateSegmentsProps {
   onFocus?: () => void;
   /** Fires when a segment in this group loses focus. */
   onBlur?: () => void;
+  /** Escape pressed in a segment (web) — an inline editor cancels its session. */
+  onEscape?: () => void;
+  /** Alt+ArrowDown pressed in a segment (web) — open the calendar popover
+   *  (the segment-field convention; plain ArrowDown steps the spinbutton). */
+  onOpenPicker?: () => void;
+  /** Reports whether the buffer holds a PARTIAL entry — non-empty but not yet a
+   *  complete valid date (a typed day with no year). Complete values emit
+   *  through `onChange`; an emptied buffer emits `""`; between the two, this is
+   *  the only signal — an inline editor blocks its commit on it. */
+  onIncompleteChange?: (incomplete: boolean) => void;
   style?: StyleProp<ViewStyle>;
 }
 
@@ -127,6 +138,9 @@ export function DateSegments(props: DateSegmentsProps) {
     accessibilityLabel,
     onFocus,
     onBlur,
+    onEscape,
+    onOpenPicker,
+    onIncompleteChange,
     style,
   } = props;
 
@@ -147,27 +161,43 @@ export function DateSegments(props: DateSegmentsProps) {
 
   const lastEmitted = useRef<string>(value);
   const fieldRefs = useRef<Partial<Record<SegmentType, RNTextInput | null>>>({});
+  const lastIncomplete = useRef(false);
+
+  const reportIncomplete = useCallback(
+    (incomplete: boolean) => {
+      if (incomplete === lastIncomplete.current) return;
+      lastIncomplete.current = incomplete;
+      onIncompleteChange?.(incomplete);
+    },
+    [onIncompleteChange],
+  );
 
   useEffect(() => {
     if (value !== lastEmitted.current) {
       lastEmitted.current = value;
       setBuffer(config.toBuffer(value));
       setActiveText("");
+      // An outside value (calendar pick, parent reset) is never partial.
+      reportIncomplete(false);
     }
-  }, [value, config]);
+  }, [value, config, reportIncomplete]);
 
   const commit = useCallback(
     (next: SegmentBuffer) => {
       const out = config.toValue(next);
       if (out !== null) {
         lastEmitted.current = out;
+        reportIncomplete(false);
         onChange(out);
       } else if (config.isEmpty(next)) {
         lastEmitted.current = "";
+        reportIncomplete(false);
         onChange("");
+      } else {
+        reportIncomplete(true);
       }
     },
-    [config, onChange],
+    [config, onChange, reportIncomplete],
   );
 
   const focusField = useCallback((type: SegmentType | undefined) => {
@@ -267,12 +297,26 @@ export function DateSegments(props: DateSegmentsProps) {
 
   const handleKeyPress = useCallback(
     (type: SegmentType, e: NativeSyntheticEvent<TextInputKeyPressEventData>) => {
-      const key = e.nativeEvent.key;
+      // On web the nativeEvent is the DOM KeyboardEvent — RN's type only carries
+      // `key`, so widen minimally at this boundary for the modifier read.
+      const native = e.nativeEvent as TextInputKeyPressEventData & { altKey?: boolean };
+      const key = native.key;
       if (/^[0-9]$/.test(key)) {
         e.preventDefault();
         handleDigit(type, key);
         return;
       }
+      // A typed separator ("15/3/2026", "14:30") advances past a segment that
+      // has content — the explicit "done" for a single-digit day/month that
+      // can't auto-advance on its own.
+      const hasContent =
+        (activeType === type && activeText !== "") || fieldNumeric(type, buffer, layout.hour12) != null;
+      if (separatorAdvances(key, hasContent)) {
+        e.preventDefault();
+        setActiveText("");
+        focusNext(type);
+        return;
+      }
       switch (key) {
         case "ArrowUp":
           e.preventDefault();
@@ -280,7 +324,16 @@ export function DateSegments(props: DateSegmentsProps) {
           break;
         case "ArrowDown":
           e.preventDefault();
-          handleStep(type, -1);
+          // Alt+ArrowDown opens the calendar (the segmented-field convention);
+          // plain ArrowDown keeps the spinbutton step.
+          if (native.altKey && onOpenPicker) onOpenPicker();
+          else handleStep(type, -1);
+          break;
+        case "Escape":
+          if (onEscape) {
+            e.preventDefault();
+            onEscape();
+          }
           break;
         case "ArrowLeft":
           e.preventDefault();
@@ -307,7 +360,7 @@ export function DateSegments(props: DateSegmentsProps) {
           }
       }
     },
-    [handleDigit, handleStep, handleBackspace, focusPrev, focusNext, setHalfDay],
+    [activeType, activeText, buffer, layout.hour12, handleDigit, handleStep, handleBackspace, focusPrev, focusNext, setHalfDay, onEscape, onOpenPicker],
   );
 
   const handleChangeText = useCallback(

package/src/inline_date_picker.tsx

@@ -1,24 +1,28 @@
-import { useCallback, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { View } from "react-native";
 import { Text } from "./text";
 import { Icon } from "./icon";
 import { colors } from "./colors";
 import { Popover, PopoverTrigger, PopoverContent } from "./popover";
 import { DatePickerPanel } from "./date_picker";
-import { isoHasTime } from "./date_picker_value";
+import { DateField } from "./date_field";
+import { isoHasTime, resolveDateCommit } from "./date_picker_value";
 import { formatDate } from "./format_date";
 import { ActivityIndicator } from "./activity_indicator";
 import { type InlineEditBackground, InlineEditView } from "./inline_edit";
 import { useLoticsLocale } from "./locale";
+import { getInteractionModality } from "./interaction_modality";
+import { shouldOpenOnFocus } from "./inline_focus";
 
 export interface InlineDatePickerProps {
   /** ISO date (`2026-05-22`) or datetime (`2026-05-22T14:30`). */
   value: string | null;
   onSave: (next: string) => void | Promise<void>;
   /** Unset the date to empty. Provide it to make the value clearable: the
-   *  calendar's own "Clear" button then unsets the field through this callback
-   *  (without `onClear` an empty selection is ignored — a required date can't be
-   *  emptied). Kept separate from `onSave` (whose next is a non-empty string). */
+   *  calendar's own "Clear" button and an emptied typed entry then unset the
+   *  field through this callback (without `onClear` an empty result is ignored —
+   *  a required date can't be emptied). Kept separate from `onSave` (whose next
+   *  is a non-empty string). */
   onClear?: () => void | Promise<void>;
   /** "date" (default) or "datetime". */
   format?: "date" | "datetime";
@@ -26,7 +30,7 @@ export interface InlineDatePickerProps {
    *  until a time is added). Ignored when `format` is "datetime" (time always on). */
   optionalTime?: boolean;
   placeholder?: string;
-  /** BCP-47 locale for the calendar and the displayed date. */
+  /** BCP-47 locale for the calendar, the displayed date, and the typed segment order. */
   locale?: string;
   disabled?: boolean;
   accessibilityLabel?: string;
@@ -35,105 +39,235 @@ export interface InlineDatePickerProps {
 }
 
 /**
- * An inline-editable date / datetime. The value reads as a formatted date;
- * clicking it floats the calendar (`DatePickerPanel`) in a popover anchored to
- * the view, so the row never changes height. The selection commits when the
- * panel closes (immediately for a single date, after time entry for datetime);
- * dismissing without a change reverts.
+ * An inline-editable date / datetime with TWO entry paths:
+ *
+ * - **Pointer** (unchanged): clicking the resting value floats the calendar
+ *   (`DatePickerPanel`) in a popover anchored to the view; the selection
+ *   commits when the panel closes, dismissing without a change reverts.
+ * - **Keyboard** (typed): Tab/keyboard focus swaps the value for the kit's
+ *   segmented `DateField` with the first segment focused — type the date in the
+ *   locale's own order (dd/MM/yyyy where the locale says so; separators advance
+ *   a single-digit day/month), Enter or blur commits, Escape reverts, and
+ *   Alt+ArrowDown still opens the calendar. A partial entry never commits and
+ *   never clears the stored value — the error affordance shows instead.
+ *
+ * The row never changes height in either mode.
  */
 export function InlineDatePicker(props: InlineDatePickerProps) {
   const { value, onSave, onClear, format = "date", optionalTime, placeholder, locale, disabled, accessibilityLabel , background } = props;
-  const labels = useLoticsLocale().inline;
+  const locales = useLoticsLocale();
+  const inlineLabels = locales.inline;
+  const dateLabels = locales.datePicker;
+
+  const [editing, setEditing] = useState(false);
   const [open, setOpen] = useState(false);
-  const [draft, setDraft] = useState<string | null>(value);
+  // Canonical session draft ("" when empty) — written by the segments AND the
+  // calendar panel, so both paths commit through the same resolution.
+  const [draft, setDraft] = useState<string>(value ?? "");
   const [saving, setSaving] = useState(false);
   const [error, setError] = useState<string | null>(null);
-  // The latest panel value, read at close time (the draft state can be stale in
-  // the close handler's closure).
-  const draftRef = useRef<string | null>(value);
-
-  const commit = useCallback(async () => {
-    const next = draftRef.current;
-    if (next === value) return;
-    // The panel's "Clear" empties the draft (onValueChange("")). Treat that as an
-    // explicit unset when the field is clearable (onClear + a current value);
-    // otherwise ignore an empty draft — a required date can't be emptied.
-    if (!next) {
-      if (!onClear || !value) return;
-      setSaving(true);
-      setError(null);
-      try {
-        await onClear();
-      } catch (e) {
-        setError(e instanceof Error && e.message ? e.message : labels.saveError);
-      } finally {
-        setSaving(false);
-      }
+
+  // The latest draft, read at commit time (state can be stale in the close
+  // handler's closure).
+  const draftRef = useRef<string>(value ?? "");
+  // True while the segments hold a partial typed entry (no complete value).
+  const incompleteRef = useRef(false);
+  // A commit in flight — a trailing blur/close must not commit twice.
+  const committing = useRef(false);
+  // Timestamp of the last programmatic focus restore (ours or the popover's) —
+  // that focus must not re-open the typing session. See `inline_focus.ts`.
+  const suppressedAt = useRef<number | null>(null);
+  // The popover anchor AND the focus-restore target: the resting view in view
+  // mode (via `PopoverTrigger`), the `DateField` frame while editing.
+  const anchorRef = useRef<View>(null);
+  const wasEditing = useRef(false);
+
+  const startSession = useCallback(() => {
+    draftRef.current = value ?? "";
+    setDraft(value ?? "");
+    incompleteRef.current = false;
+    setError(null);
+  }, [value]);
+
+  const updateDraft = useCallback((next: string) => {
+    draftRef.current = next;
+    setDraft(next);
+    setError(null);
+  }, []);
+
+  const commitSession = useCallback(async () => {
+    if (committing.current) return;
+    const decision = resolveDateCommit({
+      draft: draftRef.current,
+      value,
+      incomplete: incompleteRef.current,
+      clearable: !!onClear,
+    });
+    if (decision.kind === "invalid") {
+      // Partial typed entry: never commit, never wipe the stored value — show
+      // the error and keep the session (the entry stays fixable).
+      setError(dateLabels.invalidDate);
+      return;
+    }
+    if (decision.kind === "none") {
+      setEditing(false);
       return;
     }
+    committing.current = true;
     setSaving(true);
     setError(null);
     try {
-      await onSave(next);
+      if (decision.kind === "clear") {
+        if (onClear) await onClear();
+      } else {
+        await onSave(decision.value);
+      }
+      setEditing(false);
     } catch (e) {
-      setError(e instanceof Error && e.message ? e.message : labels.saveError);
+      // Stay in the session so the entry isn't lost — show the error.
+      setError(e instanceof Error && e.message ? e.message : inlineLabels.saveError);
     } finally {
+      committing.current = false;
       setSaving(false);
     }
-  }, [value, onSave, onClear, labels.saveError]);
+  }, [value, onSave, onClear, dateLabels.invalidDate, inlineLabels.saveError]);
+
+  const closeAndCommit = useCallback(() => {
+    setOpen(false);
+    // The popover restores focus to its trigger on close — that programmatic
+    // focus must not immediately re-open the typing session.
+    suppressedAt.current = Date.now();
+    void commitSession();
+  }, [commitSession]);
 
-  const onOpenChange = useCallback(
+  const handleOpenChange = useCallback(
     (next: boolean) => {
       if (next) {
-        draftRef.current = value;
-        setDraft(value);
+        // A fresh popover session from the resting view (the typing session,
+        // when editing, is already running on the same draft).
+        if (!editing) startSession();
         setOpen(true);
       } else {
-        setOpen(false);
-        void commit();
+        // Commit on panel close: a single-date pick and "Today" auto-close
+        // through onRequestClose → closeAndCommit; outside-click/Escape land here.
+        closeAndCommit();
       }
     },
-    [value, commit],
+    [editing, startSession, closeAndCommit],
   );
 
-  // `format` here is the field config (date vs datetime); the display formatter only needs
-  // whether to show a time → map it to the orthogonal `time` flag. In optionalTime mode the
-  // value's own shape decides.
+  // Keyboard focus on the resting value opens the TYPING session (popover shut,
+  // first segment focused). Pointer focus never lands here — mousedown records
+  // "pointer" modality before focus fires — so a click still opens the calendar
+  // exactly once, through the popover trigger press.
+  const handleViewFocus = useCallback(() => {
+    if (disabled) return;
+    if (!shouldOpenOnFocus(getInteractionModality(), suppressedAt.current, Date.now())) return;
+    startSession();
+    setEditing(true);
+  }, [disabled, startSession]);
+
+  // Pointer down in the segments area, or Alt+ArrowDown in a segment.
+  const openPicker = useCallback(() => {
+    if (!disabled) setOpen(true);
+  }, [disabled]);
+
+  // Commit once focus leaves the whole field — unless the calendar is open
+  // (it steals focus while it floats; its close commits instead).
+  const handleFieldBlur = useCallback(() => {
+    if (open) return;
+    void commitSession();
+  }, [open, commitSession]);
+
+  const handleEscape = useCallback(() => {
+    // With the calendar open, Escape belongs to the popover (its document-level
+    // handler closes it and commits through onOpenChange).
+    if (open) return;
+    setError(null);
+    setEditing(false);
+  }, [open]);
+
+  const handleIncompleteChange = useCallback((incomplete: boolean) => {
+    incompleteRef.current = incomplete;
+  }, []);
+
+  // When the typing session closes while a segment still holds focus (Enter,
+  // Escape), the unmount drops focus to <body> and the next Tab would restart
+  // from the top of the page. Return focus to the resting view, arming the
+  // suppression window so the restore doesn't re-open the session. A Tab-away
+  // blur-commit leaves focus on the next field, so this never steals it back.
+  useEffect(() => {
+    if (wasEditing.current && !editing && typeof document !== "undefined" && document.activeElement === document.body) {
+      suppressedAt.current = Date.now();
+      anchorRef.current?.focus();
+    }
+    wasEditing.current = editing;
+  }, [editing]);
+
+  // `format` is the field config (date vs datetime); the display/segments only need
+  // whether a time shows. In optionalTime mode the value's own shape decides — the
+  // resting view follows the stored value, the segments follow the session draft
+  // (the panel's "Add time" grows the segments live).
   const showTime = optionalTime ? isoHasTime(value) : format === "datetime";
   const display = formatDate(value, { time: showTime, locale, emptyLabel: "" });
+  const fieldHasTime = optionalTime ? isoHasTime(draft) : format === "datetime";
+
+  const trailing = saving ? (
+    <ActivityIndicator size={16} color={colors.zinc[400]} />
+  ) : (
+    <Icon name={format === "datetime" ? "calendar-clock" : "calendar"} size={18} color={colors.zinc[400]} />
+  );
 
   return (
     <View>
-      <Popover open={open && !disabled} onOpenChange={onOpenChange} side="bottom" align="start">
-        <PopoverTrigger>
-          <InlineEditView
-            background={background}
-            display={display}
-            placeholder={placeholder}
+      <Popover open={open && !disabled} onOpenChange={handleOpenChange} triggerRef={anchorRef} side="bottom" align="start">
+        {editing ? (
+          <DateField
+            triggerRef={anchorRef}
+            parts={[draft]}
+            onPartChange={(_, next) => updateDraft(next)}
+            hasTime={fieldHasTime}
+            segmentLabels={dateLabels}
+            locale={locale}
             disabled={disabled}
-            active={open && !disabled}
-            accessibilityLabel={accessibilityLabel}
-            // A rest affordance (like the select's chevron): a calendar glyph marks
-            // the field as a tappable date control even when empty — no hover / pointer
-            // cursor needed, so it reads as interactive on touch.
-            trailing={saving ? <ActivityIndicator size={16} color={colors.zinc[400]} /> : <Icon name={format === "datetime" ? "calendar-clock" : "calendar"} size={18} color={colors.zinc[400]} />}
+            placeholder={placeholder}
+            partLabels={accessibilityLabel ? [accessibilityLabel] : undefined}
+            autoFocus
+            onBlur={handleFieldBlur}
+            onEscape={handleEscape}
+            onOpenPicker={openPicker}
+            onIncompleteChange={handleIncompleteChange}
+            onActivate={openPicker}
+            rightSlot={trailing}
           />
-        </PopoverTrigger>
+        ) : (
+          <PopoverTrigger>
+            <InlineEditView
+              background={background}
+              display={display}
+              placeholder={placeholder}
+              disabled={disabled}
+              active={open && !disabled}
+              accessibilityLabel={accessibilityLabel}
+              onFocus={handleViewFocus}
+              // A rest affordance (like the select's chevron): a calendar glyph marks
+              // the field as a tappable date control even when empty — no hover / pointer
+              // cursor needed, so it reads as interactive on touch.
+              trailing={trailing}
+            />
+          </PopoverTrigger>
+        )}
         <PopoverContent>
           <DatePickerPanel
             value={draft}
-            onValueChange={(v) => {
-              draftRef.current = v;
-              setDraft(v);
-            }}
+            onValueChange={updateDraft}
             format={format}
             optionalTime={optionalTime}
             locale={locale}
             // Commit on panel close. A single-date pick and the "Today" button
-            // auto-close through here — route it through onOpenChange so commit
-            // runs. A bare setOpen(false) is a controlled close the Popover never
-            // reports to onOpenChange, so the pick/clear would be silently dropped.
-            onRequestClose={() => onOpenChange(false)}
+            // auto-close through here — a bare setOpen(false) would be a
+            // controlled close the Popover never reports, silently dropping it.
+            onRequestClose={closeAndCommit}
           />
         </PopoverContent>
       </Popover>

package/src/inline_edit.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useRef, useState, type ReactNode, type Ref } from "react";
+import { useCallback, useEffect, useRef, useState, type ReactNode, type Ref } from "react";
 import { View, StyleSheet, type GestureResponderEvent, type TextStyle } from "react-native";
 import { Text } from "./text";
 import { IconButton } from "./icon_button";
@@ -8,6 +8,8 @@ import { FocusRingPressable } from "./focus_ring_pressable";
 import { colors } from "./colors";
 import { FOCUS_RING, CONTROL_RADIUS, HOVER_BORDER, CONTROL_TRANSITION } from "./control_surface";
 import { fontFamilyRegular, getInputTextStyle } from "./text_utils";
+import { getInteractionModality } from "./interaction_modality";
+import { shouldOpenOnFocus } from "./inline_focus";
 
 /** The kit's standard control height (TextInputField, NumberInput, Picker, …).
  *  The view box matches it — same height, padding, and a 1px transparent border
@@ -132,6 +134,11 @@ interface InlineEditViewProps {
   /** True while the field's popover (select/date) is open: wears the 2px active
    *  ring so a mouse-opened trigger reads like a focused input (no `:focus-visible`). */
   active?: boolean;
+  /** Raw focus on the resting view, any modality. The input-swap editors use it
+   *  (via `InlineEditFrame`) to open edit mode on KEYBOARD focus; the popover
+   *  editors leave it unset — focus never auto-opens an overlay (the WAI-ARIA
+   *  combobox contract: the popup opens on Enter/Space, not on Tab arrival). */
+  onFocus?: () => void;
   /** Strike + mute the resting value (a completed/superseded item that stays editable). */
   struck?: boolean;
   /** Resting surface — see {@link InlineEditBackground}. Default "tint". */
@@ -150,7 +157,7 @@ interface InlineEditViewProps {
  * select/date inline editors (it forwards ref + onPress to a `PopoverTrigger`).
  */
 export function InlineEditView(props: InlineEditViewProps) {
-  const { display, placeholder, onPress, disabled, accessibilityLabel, trailing, active, struck, background = "tint", ref } = props;
+  const { display, placeholder, onPress, disabled, accessibilityLabel, trailing, active, struck, background = "tint", onFocus, ref } = props;
   // Stop the press here so an inline editor nested in a pressable row (a task
   // row that expands on press) edits the field instead of triggering the row.
   const handlePress = onPress
@@ -164,6 +171,7 @@ export function InlineEditView(props: InlineEditViewProps) {
       ref={ref}
       disabled={disabled}
       onPress={handlePress}
+      onFocus={onFocus}
       accessibilityRole="button"
       accessibilityLabel={accessibilityLabel}
       userSelect="none"
@@ -187,7 +195,9 @@ export function InlineEditView(props: InlineEditViewProps) {
 /**
  * The shared shell of an inline-editable INPUT (text, number). View mode is an
  * `InlineEditView`; on press it swaps to the input at the same height — no
- * layout shift — plus the optional save/cancel controls. Compose it with
+ * layout shift — plus the optional save/cancel controls. KEYBOARD focus on the
+ * closed view also opens edit mode (type → Tab → type through a form); pointer
+ * focus never does — the press handler owns the click path. Compose it with
  * `useInlineEdit`. (Overlay-based editors — select, date — use `InlineEditView`
  * directly as a `Popover` trigger instead.)
  */
@@ -211,13 +221,43 @@ export function InlineEditFrame(props: InlineEditFrameProps) {
     affordance,
   } = props;
 
+  const viewRef = useRef<View>(null);
+  const suppressedAt = useRef<number | null>(null);
+  const wasEditing = useRef(editing);
+
+  // Keyboard focus opens edit mode immediately; the input's own `autoFocus`
+  // then moves focus into it. Pointer focus never lands here (mousedown records
+  // "pointer" modality before focus fires), so a click still opens exactly once,
+  // through onPress.
+  const handleViewFocus = useCallback(() => {
+    if (disabled) return;
+    if (!shouldOpenOnFocus(getInteractionModality(), suppressedAt.current, Date.now())) return;
+    onBegin();
+  }, [disabled, onBegin]);
+
+  // When edit mode closes while its input (or a ✓/✕ button) still holds focus —
+  // Enter, Escape, the buttons — the unmount drops focus to <body> and the next
+  // Tab would restart from the top of the page. Return focus to the view button,
+  // arming the suppression window so the programmatic focus doesn't re-open the
+  // editor it just closed. A Tab-away blur-commit leaves focus on the next field
+  // (not <body>), so this never steals focus back.
+  useEffect(() => {
+    if (wasEditing.current && !editing && typeof document !== "undefined" && document.activeElement === document.body) {
+      suppressedAt.current = Date.now();
+      viewRef.current?.focus();
+    }
+    wasEditing.current = editing;
+  }, [editing]);
+
   if (!editing) {
     return (
       <InlineEditView
+        ref={viewRef}
         background={background}
         display={display}
         placeholder={placeholder}
         onPress={onBegin}
+        onFocus={handleViewFocus}
         disabled={disabled}
         accessibilityLabel={accessibilityLabel}
         struck={struck}

package/src/inline_focus.test.ts

@@ -0,0 +1,39 @@
+// @vitest-environment jsdom
+import { describe, it, expect } from "vitest";
+import { ensureModalityListeners, getInteractionModality } from "./interaction_modality";
+import { FOCUS_OPEN_SUPPRESS_MS, shouldOpenOnFocus } from "./inline_focus";
+
+describe("shouldOpenOnFocus — the inline keyboard-entry gate", () => {
+  it("keyboard focus opens the editor", () => {
+    expect(shouldOpenOnFocus("keyboard", null, 1_000)).toBe(true);
+  });
+
+  it("pointer focus never opens the editor — the click path stays press-driven", () => {
+    expect(shouldOpenOnFocus("pointer", null, 1_000)).toBe(false);
+    // …even outside any suppression window.
+    expect(shouldOpenOnFocus("pointer", 100, 100_000)).toBe(false);
+  });
+
+  it("a programmatic focus restore inside the suppression window does not re-open", () => {
+    const restoredAt = 5_000;
+    expect(shouldOpenOnFocus("keyboard", restoredAt, restoredAt)).toBe(false);
+    expect(shouldOpenOnFocus("keyboard", restoredAt, restoredAt + FOCUS_OPEN_SUPPRESS_MS - 1)).toBe(false);
+  });
+
+  it("suppression expires — a later Tab arrival opens again", () => {
+    const restoredAt = 5_000;
+    expect(shouldOpenOnFocus("keyboard", restoredAt, restoredAt + FOCUS_OPEN_SUPPRESS_MS)).toBe(true);
+  });
+});
+
+describe("interaction modality tracker", () => {
+  it("records keyboard on keydown and pointer on mousedown (Tab-vs-click focus)", () => {
+    ensureModalityListeners();
+    document.dispatchEvent(new KeyboardEvent("keydown", { key: "Tab" }));
+    expect(getInteractionModality()).toBe("keyboard");
+    document.dispatchEvent(new MouseEvent("mousedown"));
+    expect(getInteractionModality()).toBe("pointer");
+    document.dispatchEvent(new KeyboardEvent("keydown", { key: "a" }));
+    expect(getInteractionModality()).toBe("keyboard");
+  });
+});

package/src/inline_focus.ts

@@ -0,0 +1,40 @@
+// =============================================================================
+// Inline editor focus-entry policy
+//
+// The keyboard-entry contract for the input-swap inline editors (text, number,
+// time, date): a KEYBOARD focus landing on the closed editor opens edit mode
+// immediately with the input focused — a typist gets type → Tab → type without
+// pressing Enter on every field. Pointer focus never opens here: mousedown
+// records "pointer" modality before the focus event fires, and the press
+// handler already owns the click path — so a click can never double-trigger.
+//
+// A PROGRAMMATIC focus restore (the editor returning focus to its closed view
+// after Enter/Escape, or a popover restoring focus to its trigger on close)
+// arms a short suppression window first, so the restored focus doesn't
+// immediately re-open the editor it just closed.
+//
+// Pure logic, kept RN-free so it can be unit-tested directly.
+// =============================================================================
+
+import { type InteractionModality } from "./interaction_modality";
+
+/** How long (ms) after a programmatic focus restore a focus event is treated as
+ *  the restore itself rather than a fresh keyboard arrival. Restores run
+ *  synchronously (effect cleanup) or within a frame — 250ms covers both with
+ *  margin while never swallowing a real Tab press later. */
+export const FOCUS_OPEN_SUPPRESS_MS = 250;
+
+/**
+ * Should a focus event on a CLOSED inline editor open edit mode?
+ * `suppressedAt` is the timestamp of the last programmatic focus restore
+ * (null when none) — the caller keeps it in a ref and stamps it right before
+ * calling `.focus()`.
+ */
+export function shouldOpenOnFocus(
+  modality: InteractionModality,
+  suppressedAt: number | null,
+  now: number,
+): boolean {
+  if (modality !== "keyboard") return false;
+  return suppressedAt === null || now - suppressedAt >= FOCUS_OPEN_SUPPRESS_MS;
+}

package/src/interaction_modality.ts

@@ -0,0 +1,38 @@
+// =============================================================================
+// Interaction modality — the document-level keyboard-vs-pointer tracker
+//
+// `:focus-visible` is a MODALITY heuristic: a control reacts to keyboard focus
+// but not pointer focus. One focus event carries no modality, so it can only be
+// read at the document level: a single module-level tracker records the last
+// interaction. Consumed by `useFocusRing` (paint the ring on keyboard focus
+// only) and the inline editors (keyboard focus opens edit mode — type → Tab →
+// type — while pointer focus defers to the press handler). Web-only — on
+// native / SSR there is no `document`, so it stays "pointer" and everything
+// keyboard-gated stays off.
+// =============================================================================
+
+export type InteractionModality = "keyboard" | "pointer";
+
+let lastModality: InteractionModality = "pointer";
+let listenersInstalled = false;
+
+export function ensureModalityListeners(): void {
+  if (listenersInstalled) return;
+  if (typeof document === "undefined") return;
+  listenersInstalled = true;
+  // Capture phase so the modality is recorded BEFORE any control's focus handler
+  // runs. Installed once for the app's lifetime (the browser's own `:focus-visible`
+  // heuristic listens the same way) — per-mount add/remove would be the bug.
+  const opts = { capture: true, passive: true } as const;
+  document.addEventListener("keydown", () => { lastModality = "keyboard"; }, opts);
+  document.addEventListener("pointerdown", () => { lastModality = "pointer"; }, opts);
+  document.addEventListener("mousedown", () => { lastModality = "pointer"; }, opts);
+  document.addEventListener("touchstart", () => { lastModality = "pointer"; }, opts);
+}
+
+/** The modality of the most recent user interaction. Read it inside a focus
+ *  handler to tell a Tab-focus ("keyboard") from a click-focus ("pointer") —
+ *  the same signal the browser's `:focus-visible` uses. */
+export function getInteractionModality(): InteractionModality {
+  return lastModality;
+}

package/src/locale.tsx

@@ -107,7 +107,7 @@ export const en: LoticsLocale = {
     descending: ", descending",
   },
   optionList: { selectAll: "Select all", deselectAll: "Deselect all", clear: "Clear", noResults: "No results", recent: "Recent", searchPlaceholder: "Search…" },
-  datePicker: { today: "Today", now: "Now", clear: "Clear", done: "Done", openCalendar: "Open calendar", time: "Time", startTime: "Start time", endTime: "End time", addTime: "Add time", removeTime: "Remove time", year: "Year", month: "Month", day: "Day", hour: "Hour", minute: "Minute", dayPeriod: "AM/PM" },
+  datePicker: { today: "Today", now: "Now", clear: "Clear", done: "Done", openCalendar: "Open calendar", time: "Time", startTime: "Start time", endTime: "End time", addTime: "Add time", removeTime: "Remove time", year: "Year", month: "Month", day: "Day", hour: "Hour", minute: "Minute", dayPeriod: "AM/PM", invalidDate: "Enter a complete date" },
   calendar: { previousMonth: "Previous month", nextMonth: "Next month" },
   filterChip: { clear: "Clear" },
   floatingActionBar: { clear: "Clear" },
@@ -187,7 +187,7 @@ export const vi: LoticsLocale = {
     descending: " (giảm dần)",
   },
   optionList: { selectAll: "Chọn tất cả", deselectAll: "Bỏ chọn tất cả", clear: "Xóa", noResults: "Không có kết quả", recent: "Gần đây", searchPlaceholder: "Tìm…" },
-  datePicker: { today: "Hôm nay", now: "Bây giờ", clear: "Xóa", done: "Xong", openCalendar: "Mở lịch", time: "Giờ", startTime: "Giờ bắt đầu", endTime: "Giờ kết thúc", addTime: "Thêm giờ", removeTime: "Bỏ giờ", year: "Năm", month: "Tháng", day: "Ngày", hour: "Giờ", minute: "Phút", dayPeriod: "SA/CH" },
+  datePicker: { today: "Hôm nay", now: "Bây giờ", clear: "Xóa", done: "Xong", openCalendar: "Mở lịch", time: "Giờ", startTime: "Giờ bắt đầu", endTime: "Giờ kết thúc", addTime: "Thêm giờ", removeTime: "Bỏ giờ", year: "Năm", month: "Tháng", day: "Ngày", hour: "Giờ", minute: "Phút", dayPeriod: "SA/CH", invalidDate: "Nhập ngày đầy đủ" },
   calendar: { previousMonth: "Tháng trước", nextMonth: "Tháng sau" },
   filterChip: { clear: "Xóa" },
   floatingActionBar: { clear: "Bỏ chọn" },

package/src/use_focus_ring.ts

@@ -1,4 +1,5 @@
 import { useCallback, useState } from "react";
+import { ensureModalityListeners, getInteractionModality } from "./interaction_modality";
 
 /**
  * Combine two optional event handlers into one. Either may be undefined.
@@ -17,31 +18,6 @@ export function composeHandler<E>(
   };
 }
 
-// `:focus-visible` is a MODALITY heuristic: a control shows its ring on keyboard
-// focus but not pointer focus. The kit no longer carries a global `:focus-visible`
-// CSS rule, so every control paints its own ring — and needs that same signal. One
-// focus event carries no modality, so it can only be read at the document level:
-// a single module-level tracker records the last interaction. Web-only — on native
-// / SSR there is no `document`, so it stays "pointer" and the ring is keyboard-gated
-// off (text-like inputs opt back in with `always`).
-type Modality = "keyboard" | "pointer";
-let lastModality: Modality = "pointer";
-let listenersInstalled = false;
-
-function ensureModalityListeners(): void {
-  if (listenersInstalled) return;
-  if (typeof document === "undefined") return;
-  listenersInstalled = true;
-  // Capture phase so the modality is recorded BEFORE any control's focus handler
-  // runs. Installed once for the app's lifetime (the browser's own `:focus-visible`
-  // heuristic listens the same way) — per-mount add/remove would be the bug.
-  const opts = { capture: true, passive: true } as const;
-  document.addEventListener("keydown", () => { lastModality = "keyboard"; }, opts);
-  document.addEventListener("pointerdown", () => { lastModality = "pointer"; }, opts);
-  document.addEventListener("mousedown", () => { lastModality = "pointer"; }, opts);
-  document.addEventListener("touchstart", () => { lastModality = "pointer"; }, opts);
-}
-
 export interface UseFocusRingOptions {
   /**
    * Ring on ANY focus, not just keyboard focus. For text-like inputs, which the
@@ -69,12 +45,13 @@ export interface FocusRingState {
  * Replaces the kit's removed global `:focus-visible` CSS rule: each interactive
  * primitive calls this and renders `FOCUS_RING` (`control_surface.ts`) when
  * `focusVisible`. App authors do the same for their own raw focusable elements.
+ * The keyboard-vs-pointer signal lives in `interaction_modality.ts`.
  */
 export function useFocusRing(options?: UseFocusRingOptions): FocusRingState {
   ensureModalityListeners();
   const [focused, setFocused] = useState(false);
   const onFocus = useCallback(() => setFocused(true), []);
   const onBlur = useCallback(() => setFocused(false), []);
-  const focusVisible = focused && (options?.always === true || lastModality === "keyboard");
+  const focusVisible = focused && (options?.always === true || getInteractionModality() === "keyboard");
   return { focusVisible, focused, focusProps: { onFocus, onBlur } };
 }