@lotics/ui 17.0.1 → 18.0.0

package/MIGRATION.md

@@ -4,6 +4,26 @@ Breaking changes, newest first — normally per major, plus the rare minor that
 anyway (recorded under its exact version). The current contract lives in `AGENTS.md` + `docs/`;
 this file exists only to move an app from one release to the next.
 
+## v18 from 17.x
+
+**`TimePicker` is a segmented field, not `<input type="time">`.** A native time input takes
+its 12- vs 24-hour form from the BROWSER's UI locale and ignores the `lang` attribute
+entirely, so a Vietnamese screen on an en-US browser rendered "01:45 PM" beside its own
+24-hour text. It now uses the same segment engine as `DateField`, with the format derived
+from a `locale` prop (defaulting to the active `LoticsLocaleProvider` locale).
+
+The value is unchanged — canonical 24-hour `"HH:mm"` either way. Two prop changes:
+
+- **`onKeyDown` is GONE.** It typed the DOM input's key events, which no longer exist. Use
+  `onEscape` for cancel; a completed entry emits through `onValueChange` as before.
+- **`onIncompleteChange` is NEW** and matters for inline editors: segments emit only a
+  COMPLETE `"HH:mm"`, so a half-typed entry (an hour, no minute) arrives as `""` and would
+  otherwise commit as a silent clear. Block the commit on it — `InlineTimePicker` does, and
+  surfaces the new `datePicker.invalidTime` label.
+
+`DatePickerLabels` gains **`invalidTime`**; a caller that builds the label bag by hand (rather
+than spreading the locale pack) must add it.
+
 ## v17 from 16.x
 
 **`Checklist` / `ChecklistRow` are DELETED.** They are replaced by the `Task` compound

package/docs/catalog.md

@@ -600,11 +600,19 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   localized weekday/month names via BCP-47 `locale`, `firstDayOfWeek` (default Monday),
   `ref.navigateToMonth`. The engine `DatePicker`/`DateFilter` wrap in field chrome — reach
   for it bare only when the calendar lives permanently on the surface, not behind a field.
-- **`date_filter`** — `DateFilter`: the single/range date+time filter panel — presets
+- **`date_filter`** — `DateFilter`: the date+time period filter panel — presets
   (`PresetId`), calendar, optional time segments; the body `DateRangeFilterField` opens.
+  **One selection rule, no modes**: a click OPENS a range, the next CLOSES it (in either
+  order — bounds come back sorted), and a single day is the same day clicked twice
+  (`start`/`end` equal — which is how a consumer detects "one day" and how the trigger
+  renders it as a single date). Both bounds always show, so a half-picked range names the
+  end that is still open.
 - **`date_range_filter_field`** — `DateRangeFilterField`: the register's period filter field
   (presets + footer + time-segment a11y; localized via the `dateRange` locale slice).
-- **`time_picker`** — `TimePicker`: the time-of-day input.
+- **`time_picker`** — `TimePicker`: the time-of-day field. Segments (hour / minute / AM-PM),
+  **12- vs 24-hour derived from `locale`** — never from the browser, which is why this is not
+  an `<input type="time">`. The value is always canonical 24-hour `"HH:mm"`; `locale` changes
+  only what is displayed and typed.
 
 ### Inline editing & record surfaces
 

package/docs/templates.md

@@ -355,9 +355,11 @@ billing, and quick-capture templates. Top → bottom:
   HOME stays their DATA section (the colocation law) with descriptions naming their
   consumers ("printed on the delivery note"). The picker rows ride `TaskList`/`TaskItem`
   (`controlWidth={24}` for the `CheckboxInput` in `TaskStatus`) — the compound owns the row
-  geometry and the indent; hand-rolling the anatomy is how alignment drifts. Warning and fix are CO-LOCATED on the row. The mark NAMES what's missing (the
-  `TaskFields` line: 13px `circle-alert` + "Needs: …" the actual field labels — muted at rest so
-  gaps show WITHOUT checking, warning once checked because it now blocks). The FIX sits
+  geometry and the indent; hand-rolling the anatomy is how alignment drifts. Warning and fix are CO-LOCATED on the row. The mark NAMES what's missing — a
+  **`TaskCaption`**, not a field cell: 13px `circle-alert` + "Needs: …" the actual field labels,
+  muted at rest so gaps show WITHOUT checking, warning once checked because it now blocks. It is
+  a SENTENCE about the row, and `TaskFields` is the column the reader edits and scans down, so
+  prose put there lines up with nothing and reads as a control it is not. The FIX sits
   right under it in the row's `TaskDetail` — an `Inset` (a FORM surface, NEVER a `Callout`:
   a warning Callout is an ARIA `alert`, wrong around a form) with a `FormTextInput` per gap
   (label + the consumer hint as `description`) and a "Save fields" (secondary — the section

package/examples/tpl_record.tsx

@@ -32,7 +32,7 @@ import { CheckCircle } from "@lotics/ui/check_circle";
 import { ProgressBar } from "@lotics/ui/progress_bar";
 import { FilterChip } from "@lotics/ui/filter_chip";
 import { CaptureRow } from "@lotics/ui/capture_row";
-import { TaskActions, TaskDetail, TaskFields, TaskItem, TaskList, TaskStatus, TaskTitle } from "@lotics/ui/task";
+import { TaskActions, TaskCaption, TaskDetail, TaskFields, TaskItem, TaskList, TaskStatus, TaskTitle, TASK_TEXT_INSET } from "@lotics/ui/task";
 import { ActionMenu, type ActionMenuItem } from "@lotics/ui/action_menu";
 import { SuggestionChip } from "@lotics/ui/suggestion_chip";
 import { OptionList } from "@lotics/ui/option_list";
@@ -1900,7 +1900,10 @@ export function TplRecord() {
                                   <CheckCircle state={sub.done ? "done" : "none"} onChange={(on) => toggleSubtask(t.id, sub.key, on)} accessibilityLabel={sub.label} />
                                 </TaskStatus>
                                 <TaskTitle>
-                                  <Text size="sm" color={sub.done ? "muted" : "default"} decoration={sub.done ? "lineThrough" : undefined}>{sub.label}</Text>
+                                  {/* The parent's title is an inline editor, which insets its
+                                      own text; a plain `Text` child must add the same or the
+                                      two columns of titles do not line up. */}
+                                  <Text size="sm" color={sub.done ? "muted" : "default"} decoration={sub.done ? "lineThrough" : undefined} style={{ paddingHorizontal: TASK_TEXT_INSET }}>{sub.label}</Text>
                                 </TaskTitle>
                               </TaskItem>
                             ))}
@@ -2261,15 +2264,23 @@ export function TplRecord() {
                             <CheckboxInput accessibilityLabel={f.label} checked={checked} onChange={(on) => toggleForm(f.id, on)} />
                           </TaskStatus>
                           <TaskTitle>
-                            <Text size="sm" style={{ flexShrink: 1 }}>{f.label}</Text>
+                            {/* A plain-`Text` title carries the cell inset itself, or it sits
+                                out of line with the editable titles elsewhere on the page and
+                                with its own caption below. */}
+                            <Text size="sm" style={{ flexShrink: 1, paddingHorizontal: TASK_TEXT_INSET }}>{f.label}</Text>
                           </TaskTitle>
+                          {/* "Needs: Tax ID, Delivery address" is a SENTENCE about this row, so it
+                              is a `TaskCaption` — its own line under the title. It was a
+                              `TaskFields` cell, which is the column the reader EDITS and scans
+                              down: prose there lines up with nothing, squeezes the cells beside
+                              it, and reads as a control it is not. */}
                           {missing.length > 0 ? (
-                            <TaskFields>
-                            <View style={{ flexDirection: "row", alignItems: "flex-start", gap: 5 }}>
-                              <Icon name="circle-alert" size={13} color={checked ? colors.amber[500] : colors.zinc[400]} />
-                              <Text size="xs" color={checked ? "warning" : "muted"} style={{ flexShrink: 1 }}>{`Needs: ${missing.map((k) => NEEDS[k].label).join(", ")}`}</Text>
-                            </View>
-                            </TaskFields>
+                            <TaskCaption>
+                              <View style={{ flexDirection: "row", alignItems: "flex-start", gap: 5 }}>
+                                <Icon name="circle-alert" size={13} color={checked ? colors.amber[500] : colors.zinc[400]} />
+                                <Text size="xs" color={checked ? "warning" : "muted"} style={{ flexShrink: 1 }}>{`Needs: ${missing.map((k) => NEEDS[k].label).join(", ")}`}</Text>
+                              </View>
+                            </TaskCaption>
                           ) : null}
                           {checked && missing.length > 0 ? (
                             <TaskDetail>

package/package.json

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

package/src/date_calendar.tsx

@@ -8,6 +8,7 @@ import { IconButton } from "./icon_button";
 import { FOCUS_RING } from "./control_surface";
 import { useFocusRing } from "./use_focus_ring";
 import { useLoticsLocale, useLocaleTag } from "./locale";
+import { nextRangeSelection } from "./date_range_selection";
 
 /** Accessible names for the calendar's month-navigation arrows. Backs the
  *  `calendar` locale slice. (The month/weekday NAMES come from `Intl` + the
@@ -529,28 +530,14 @@ function RangeCalendar(props: RangeCalendarInternalProps) {
   const rightYear = leftMonth === 11 ? leftYear + 1 : leftYear;
   const rightMonth = leftMonth === 11 ? 0 : leftMonth + 1;
 
-  // Track which part of range we're selecting
-  const [selectingEnd, setSelectingEnd] = useState(false);
-
+  // Which half of the range a click lands on is READ from the value (a range is
+  // open exactly when it has a start and no end), never tracked alongside it —
+  // a separate flag can disagree with the value the parent actually holds.
   const handleDateSelect = useCallback(
     (date: Date) => {
-      if (!value.start || (value.start && value.end) || !selectingEnd) {
-        // Start new selection
-        onValueChange({ start: date, end: null });
-        setSelectingEnd(true);
-      } else {
-        // Complete selection
-        const start = value.start;
-        // Ensure start is before end
-        if (date < start) {
-          onValueChange({ start: date, end: start });
-        } else {
-          onValueChange({ start, end: date });
-        }
-        setSelectingEnd(false);
-      }
+      onValueChange(nextRangeSelection(value, date));
     },
-    [value, onValueChange, selectingEnd],
+    [value, onValueChange],
   );
 
   const handleMonthChange = useCallback((year: number, month: number) => {

package/src/date_filter.tsx

@@ -6,15 +6,12 @@ import { CONTROL_RADIUS } from "./control_surface";
 import { MenuButton } from "./menu_button";
 import { Calendar, CalendarRangeValue, CalendarRef } from "./date_calendar";
 import { TimePicker } from "./time_picker";
-import { Switch } from "./switch";
 import { useScreenSize } from "./use_screen_size";
 import { SegmentLabels } from "./date_segments";
 import { PresetId, PRESET_IDS, getPresetValue } from "./date_filter_presets";
 import { formatDate } from "./format_date";
 import { useLoticsLocale, useLocaleTag } from "./locale";
 
-type SelectionMode = "single" | "range";
-
 // =============================================================================
 // Types
 // =============================================================================
@@ -39,7 +36,9 @@ export interface DateFilterLabels extends SegmentLabels {
   custom: string;
   from: string;
   to: string;
+  /** Accessible name of the field that OPENS this panel (`DateRangeFilterField`). */
   selectDateRange: string;
+  /** Stands in for a bound that has no date yet — the open half of a range. */
   selectDate: string;
 }
 
@@ -83,6 +82,46 @@ function formatDateDisplay(date: Date | null, locale: string | undefined): strin
   return formatDate(date, { format: "medium", locale });
 }
 
+/**
+ * One end of the range: its name, its date (or a placeholder while it is still
+ * open), and — under `includeTime` — its time. The time field is rendered
+ * disabled rather than omitted while the bound has no date, so picking a date
+ * never shifts the panel under the pointer.
+ */
+function RangeBound(props: {
+  label: string;
+  placeholder: string;
+  bound: { date: Date | null; time: string | null };
+  includeTime: boolean;
+  localeTag: string;
+  segmentLabels: SegmentLabels;
+  onTimeChange: (time: string) => void;
+}) {
+  const { label, placeholder, bound, includeTime, localeTag, segmentLabels, onTimeChange } = props;
+  return (
+    <View style={styles.rangeItem}>
+      <Text size="xs" color="zinc-500">
+        {label}
+      </Text>
+      <Text size="sm" weight="medium" color={bound.date ? "default" : "muted"}>
+        {bound.date ? formatDateDisplay(bound.date, localeTag) : placeholder}
+      </Text>
+      {includeTime && (
+        <View style={{ marginTop: 4 }}>
+          <TimePicker
+            value={bound.time || ""}
+            onValueChange={onTimeChange}
+            disabled={!bound.date}
+            accessibilityLabel={label}
+            locale={localeTag}
+            segmentLabels={segmentLabels}
+          />
+        </View>
+      )}
+    </View>
+  );
+}
+
 // =============================================================================
 // Main Component
 // =============================================================================
@@ -97,52 +136,46 @@ export function DateFilter(props: DateFilterProps) {
   );
   const screenSize = useScreenSize();
   const calendarRef = useRef<CalendarRef>(null);
-  const [selectionMode, setSelectionMode] = useState<SelectionMode>(() => {
-    if (value.start.date && value.end.date) {
-      if (value.start.date.toDateString() !== value.end.date.toDateString()) {
-        return "range";
-      }
-    }
-    return "single";
-  });
+
+  // A half-picked range is held HERE and never emitted — the same rule
+  // `DatePickerPanel` follows. Emitting it would filter on an open-ended range
+  // the user never asked for (everything from that day onward) the moment they
+  // click a start, which reads as "filtered to that day" while being nothing of
+  // the kind. The panel still shows the pending bound; the filter does not move
+  // until the range is closed. The popover unmounts on close, so this starts
+  // fresh each session.
+  const [pendingStart, setPendingStart] = useState<Date | null>(null);
+
+  /** What the panel DISPLAYS: the pending pick if there is one, else the value. */
+  const shown = useMemo<DateFilterValue>(
+    () =>
+      pendingStart
+        ? { start: { date: pendingStart, time: value.start.time }, end: { date: null, time: value.end.time } }
+        : value,
+    [pendingStart, value],
+  );
 
   const calendarValue: CalendarRangeValue = useMemo(
-    () => ({ start: value.start.date, end: value.end.date }),
-    [value.start.date, value.end.date],
+    () => ({ start: shown.start.date, end: shown.end.date }),
+    [shown.start.date, shown.end.date],
   );
 
+  // The calendar owns which bound a click lands on (see `nextRangeSelection`);
+  // this decides whether that lands in the value or stays pending, and carries
+  // the times across, since a click never changes them.
   const handleCalendarChange = useCallback(
     (newValue: CalendarRangeValue) => {
-      // In single mode, one click selects a single date immediately
-      if (selectionMode === "single" && newValue.start && !newValue.end) {
-        onValueChange({
-          start: { date: newValue.start, time: value.start.time },
-          end: { date: newValue.start, time: value.end.time },
-        });
+      if (newValue.start && !newValue.end) {
+        setPendingStart(newValue.start);
         return;
       }
+      setPendingStart(null);
       onValueChange({
         start: { date: newValue.start, time: value.start.time },
         end: { date: newValue.end, time: value.end.time },
       });
     },
-    [onValueChange, value.start.time, value.end.time, selectionMode],
-  );
-
-  const handleModeChange = useCallback(
-    (isRange: boolean) => {
-      const newMode: SelectionMode = isRange ? "range" : "single";
-      setSelectionMode(newMode);
-
-      // Switching to single: collapse range to start date
-      if (newMode === "single" && value.start.date) {
-        onValueChange({
-          start: value.start,
-          end: { date: value.start.date, time: value.start.time },
-        });
-      }
-    },
-    [value, onValueChange],
+    [onValueChange, value.start.time, value.end.time],
   );
 
   const handleStartTimeChange = useCallback(
@@ -178,6 +211,8 @@ export function DateFilter(props: DateFilterProps) {
 
   const handlePresetSelect = useCallback(
     (id: PresetId) => {
+      // A preset replaces the whole range, so any half-picked start is abandoned.
+      setPendingStart(null);
       // Re-clicking the active preset clears the filter
       if (activePresetId === id) {
         onValueChange({ start: { date: null, time: null }, end: { date: null, time: null } });
@@ -191,13 +226,6 @@ export function DateFilter(props: DateFilterProps) {
         return;
       }
 
-      // Auto-switch to range mode for multi-day presets
-      if (presetValue.start.date && presetValue.end.date) {
-        const isSingleDay =
-          presetValue.start.date.toDateString() === presetValue.end.date.toDateString();
-        if (!isSingleDay && selectionMode === "single") setSelectionMode("range");
-      }
-
       onValueChange(presetValue);
 
       if (presetValue.start.date) {
@@ -207,7 +235,7 @@ export function DateFilter(props: DateFilterProps) {
         );
       }
     },
-    [onValueChange, activePresetId, selectionMode],
+    [onValueChange, activePresetId],
   );
 
   const renderPreset = (id: PresetId) => {
@@ -243,56 +271,28 @@ export function DateFilter(props: DateFilterProps) {
           locale={localeTag}
         />
 
-        {selectionMode === "range" ? (
-          <View style={styles.rangeDisplay}>
-            {value.start.date ? (
-              <View style={styles.rangeItem}>
-                <Text size="xs" color="zinc-500">
-                  {labels.from}
-                </Text>
-                <Text size="sm" weight="medium">
-                  {formatDateDisplay(value.start.date, localeTag) || labels.selectDate}
-                </Text>
-                {includeTime && (
-                  <View style={{ marginTop: 4 }}>
-                    <TimePicker
-                      value={value.start.time || ""}
-                      onValueChange={handleStartTimeChange}
-                    />
-                  </View>
-                )}
-              </View>
-            ) : (
-              <View style={styles.rangeItem} />
-            )}
-            {value.end.date ? (
-              <View style={styles.rangeItem}>
-                <Text size="xs" color="zinc-500">
-                  {labels.to}
-                </Text>
-                <Text size="sm" weight="medium">
-                  {formatDateDisplay(value.end.date, localeTag) || labels.selectDate}
-                </Text>
-                {includeTime && value.end.date && (
-                  <View style={{ marginTop: 4 }}>
-                    <TimePicker
-                      value={value.end.time || ""}
-                      onValueChange={handleEndTimeChange}
-                    />
-                  </View>
-                )}
-              </View>
-            ) : (
-              <View style={styles.rangeItem} />
-            )}
-          </View>
-        ) : null}
-
-        <View style={styles.modeToggle}>
-          <Switch value={selectionMode === "range"} onChange={handleModeChange} />
-          <Text size="sm" color="muted">
-            {labels.selectDateRange}
-          </Text>
+        {/* Both bounds are ALWAYS shown: they are what tells the user a range is
+            half-picked and which end is still open. Hiding the empty one (or the
+            whole row) is how a click stops explaining itself. */}
+        <View style={styles.rangeDisplay}>
+          <RangeBound
+            label={labels.from}
+            placeholder={labels.selectDate}
+            bound={shown.start}
+            includeTime={includeTime}
+            localeTag={localeTag}
+            segmentLabels={labels}
+            onTimeChange={handleStartTimeChange}
+          />
+          <RangeBound
+            label={labels.to}
+            placeholder={labels.selectDate}
+            bound={shown.end}
+            includeTime={includeTime}
+            localeTag={localeTag}
+            segmentLabels={labels}
+            onTimeChange={handleEndTimeChange}
+          />
         </View>
       </View>
 
@@ -343,18 +343,11 @@ const styles = StyleSheet.create({
   mainContent: {
     flex: 1,
   },
-  modeToggle: {
-    flexDirection: "row",
-    alignItems: "center",
-    gap: 8,
-    paddingTop: 8,
-    paddingBottom: 8,
-    paddingLeft: 8,
-  },
   rangeDisplay: {
     flexDirection: "row",
     gap: 16,
     paddingTop: 8,
+    paddingBottom: 8,
   },
   rangeItem: {
     flex: 1,

package/src/date_picker.tsx

@@ -56,6 +56,8 @@ export interface DatePickerLabels extends SegmentLabels {
   done: string;
   /** Inline error when a typed date is left incomplete/invalid (never committed). */
   invalidDate: string;
+  /** Inline error when a typed time is left half-entered (never committed). */
+  invalidTime: string;
   /** Quick action: add a time to a date-only value (`optionalTime`). */
   addTime: string;
   /** Accessible name + tooltip: drop the time, keeping the date (`optionalTime`). */
@@ -228,6 +230,7 @@ export function DatePickerPanel(props: DatePickerPanelProps) {
                     accessibilityLabel={mergedLabels.startTime}
                     value={timeText(startIso)}
                     onValueChange={(t) => handleRangeTime("start", t)}
+                    locale={locale}
                   />
                 </View>
                 <View style={styles.timeCol}>
@@ -238,6 +241,7 @@ export function DatePickerPanel(props: DatePickerPanelProps) {
                     accessibilityLabel={mergedLabels.endTime}
                     value={timeText(endIso)}
                     onValueChange={(t) => handleRangeTime("end", t)}
+                    locale={locale}
                   />
                 </View>
               </>
@@ -261,6 +265,7 @@ export function DatePickerPanel(props: DatePickerPanelProps) {
                   accessibilityLabel={mergedLabels.time}
                   value={timeText(value ?? "")}
                   onValueChange={handleSingleTime}
+                  locale={locale}
                 />
               </View>
             )}

package/src/date_range_selection.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect } from "vitest";
+import { nextRangeSelection, type DateRangeSelection } from "./date_range_selection";
+
+const d = (day: number): Date => new Date(2026, 6, day);
+const ymd = (x: Date | null): string =>
+  x ? `${x.getFullYear()}-${String(x.getMonth() + 1).padStart(2, "0")}-${String(x.getDate()).padStart(2, "0")}` : "null";
+const EMPTY: DateRangeSelection = { start: null, end: null };
+
+describe("nextRangeSelection", () => {
+  it("opens a range on the first click", () => {
+    const next = nextRangeSelection(EMPTY, d(14));
+    expect(ymd(next.start)).toBe("2026-07-14");
+    expect(next.end).toBeNull();
+  });
+
+  it("closes the open range on the second click", () => {
+    const next = nextRangeSelection({ start: d(14), end: null }, d(20));
+    expect(ymd(next.start)).toBe("2026-07-14");
+    expect(ymd(next.end)).toBe("2026-07-20");
+  });
+
+  it("orders the bounds when the later day is clicked first", () => {
+    const next = nextRangeSelection({ start: d(20), end: null }, d(14));
+    expect(ymd(next.start)).toBe("2026-07-14");
+    expect(ymd(next.end)).toBe("2026-07-20");
+  });
+
+  // The whole point of dropping the single/range mode: a range must be
+  // reachable from EVERY starting value, including one that is already a
+  // single day. Under the mode, a single-day value silently disabled range
+  // selection entirely — two clicks just moved the one day around.
+  it("reaches a range from a single-day value", () => {
+    const singleDay: DateRangeSelection = { start: d(31), end: d(31) };
+    const opened = nextRangeSelection(singleDay, d(1));
+    const closed = nextRangeSelection(opened, d(20));
+    expect(ymd(closed.start)).toBe("2026-07-01");
+    expect(ymd(closed.end)).toBe("2026-07-20");
+  });
+
+  it("reaches a range from a closed multi-day range", () => {
+    const opened = nextRangeSelection({ start: d(1), end: d(5) }, d(10));
+    expect(ymd(opened.start)).toBe("2026-07-10");
+    expect(opened.end).toBeNull();
+    expect(ymd(nextRangeSelection(opened, d(12)).end)).toBe("2026-07-12");
+  });
+
+  // Selecting one day is clicking it twice — the replacement for the mode.
+  it("selects a single day when the same day is clicked twice", () => {
+    const next = nextRangeSelection(nextRangeSelection(EMPTY, d(14)), d(14));
+    expect(ymd(next.start)).toBe("2026-07-14");
+    expect(ymd(next.end)).toBe("2026-07-14");
+  });
+
+  it("never mutates the selection it is given", () => {
+    const current: DateRangeSelection = { start: d(14), end: null };
+    nextRangeSelection(current, d(20));
+    expect(ymd(current.start)).toBe("2026-07-14");
+    expect(current.end).toBeNull();
+  });
+});

package/src/date_range_selection.ts

@@ -0,0 +1,32 @@
+// Pure click→range math for the range calendar. Kept free of React/RN so the
+// selection contract can be unit-tested directly rather than through a
+// component.
+
+/** The two bounds a range calendar edits. `end` is null while a range is open. */
+export interface DateRangeSelection {
+  start: Date | null;
+  end: Date | null;
+}
+
+/**
+ * The selection after clicking `date`.
+ *
+ * One rule, no modes: a click either OPENS a range (when none is open) or
+ * CLOSES the open one. Selecting a single day is clicking the same day twice —
+ * there is deliberately no separate single-day mode, because a mode that
+ * changes what a click means is a mode the user can get stuck in with no way
+ * to express a range at all.
+ *
+ * Bounds come back ordered, so clicking the later day first is just another way
+ * to select rather than an error the caller has to undo.
+ */
+export function nextRangeSelection(
+  current: DateRangeSelection,
+  date: Date,
+): DateRangeSelection {
+  // Nothing picked yet, or the last range is already closed → open a new one.
+  if (!current.start || current.end) return { start: date, end: null };
+  return date < current.start
+    ? { start: date, end: current.start }
+    : { start: current.start, end: date };
+}

package/src/date_segments.test.ts

@@ -3,6 +3,8 @@ import { resolveLocaleTag, en as enLocale, vi as viLocale } from "./locale";
 import {
   getDateLayout,
   getTimeLayout,
+  timeSegmentsConfig,
+  segmentsToTime,
   fieldOrder,
   to12h,
   from12h,
@@ -285,3 +287,49 @@ describe("getTimeLayout", () => {
     expect(vn.hour12).toBe(false);
   });
 });
+
+// -----------------------------------------------------------------------------
+// Time-only field. The point of the segmented time field is that 12/24-hour is
+// OUR locale's decision — a native `<input type="time">` takes it from the
+// browser's UI locale and ignores `lang`, so a Vietnamese screen on an en-US
+// browser rendered "01:45 PM" beside its own 24-hour text.
+// -----------------------------------------------------------------------------
+
+describe("timeSegmentsConfig", () => {
+  it("derives 24-hour display from the locale, not the runtime", () => {
+    expect(timeSegmentsConfig("vi-VN").layout.hour12).toBe(false);
+    expect(timeSegmentsConfig("de-DE").layout.hour12).toBe(false);
+  });
+
+  it("derives 12-hour display where the locale uses one", () => {
+    const layout = timeSegmentsConfig("en-US").layout;
+    expect(layout.hour12).toBe(true);
+    expect(layout.segments.some((s) => s.kind === "field" && s.type === "dayPeriod")).toBe(true);
+  });
+
+  it("keeps the value canonical 24-hour under a 12-hour locale", () => {
+    const cfg = timeSegmentsConfig("en-US");
+    expect(cfg.toValue(cfg.toBuffer("13:45"))).toBe("13:45");
+    expect(cfg.toValue(cfg.toBuffer("00:30"))).toBe("00:30");
+  });
+
+  it("round-trips every hour of the day", () => {
+    const cfg = timeSegmentsConfig("en-US");
+    for (let h = 0; h < 24; h++) {
+      const iso = `${String(h).padStart(2, "0")}:15`;
+      expect(cfg.toValue(cfg.toBuffer(iso))).toBe(iso);
+    }
+  });
+
+  it("reads an empty or unparseable time as empty", () => {
+    const cfg = timeSegmentsConfig("vi-VN");
+    for (const bad of ["", "banana", "25:00", "12:99"]) {
+      expect(cfg.isEmpty(cfg.toBuffer(bad))).toBe(true);
+    }
+  });
+
+  it("emits nothing while only half the time is typed", () => {
+    expect(segmentsToTime({ year: null, month: null, day: null, hour: 13, minute: null })).toBeNull();
+    expect(segmentsToTime({ year: null, month: null, day: null, hour: null, minute: 45 })).toBeNull();
+  });
+});

package/src/date_segments.ts

@@ -356,3 +356,37 @@ export function dateSegmentsConfig(locale: string, hasTime: boolean): SegmentsCo
     parse: (text) => parseText(text, hasTime),
   };
 }
+
+// -----------------------------------------------------------------------------
+// Time-only field — same engine, no date part. The canonical value is 24-hour
+// "HH:mm" REGARDLESS of how the locale displays it: `hour12` decides whether the
+// user sees "01:45 PM" or "13:45", never what is stored or emitted.
+// -----------------------------------------------------------------------------
+
+const TIME_RE = /^(\d{1,2}):(\d{2})/;
+
+/** "HH:mm" → buffer. Anything unparseable or out of range reads as empty. */
+export function timeToSegments(time: string): SegmentBuffer {
+  const m = TIME_RE.exec(time);
+  if (!m) return emptyBuffer();
+  const hour = Number(m[1]);
+  const minute = Number(m[2]);
+  if (hour > 23 || minute > 59) return emptyBuffer();
+  return { year: null, month: null, day: null, hour, minute };
+}
+
+/** Buffer → canonical "HH:mm", or null while either half is still missing. */
+export function segmentsToTime(buffer: SegmentBuffer): string | null {
+  if (buffer.hour == null || buffer.minute == null) return null;
+  return `${pad(buffer.hour)}:${pad(buffer.minute)}`;
+}
+
+export function timeSegmentsConfig(locale: string): SegmentsConfig {
+  return {
+    layout: getTimeLayout(locale),
+    toBuffer: timeToSegments,
+    toValue: segmentsToTime,
+    isEmpty: (buffer) => buffer.hour == null && buffer.minute == null,
+    parse: (text) => segmentsToTime(timeToSegments(text.trim())),
+  };
+}

package/src/inline_time_picker.tsx

@@ -1,8 +1,8 @@
-import { useCallback } from "react";
-import type { KeyboardEvent } from "react";
+import { useCallback, useRef } from "react";
 import { Icon } from "./icon";
 import { colors } from "./colors";
 import { TimePicker } from "./time_picker";
+import { useLoticsLocale } from "./locale";
 import { type InlineEditVariant, InlineEditFrame, useInlineEdit, type InlineEditControls } from "./inline_edit";
 
 export interface InlineTimePickerProps {
@@ -27,17 +27,15 @@ export interface InlineTimePickerProps {
 export function InlineTimePicker(props: InlineTimePickerProps) {
   const { value, onSave, placeholder, controls = "blur", disabled, accessibilityLabel , variant } = props;
   const edit = useInlineEdit<string>({ value, onSave });
-
-  const onKeyDown = useCallback(
-    (e: KeyboardEvent<HTMLInputElement>) => {
-      if (e.key === "Escape") edit.cancel();
-      else if (e.key === "Enter") void edit.commit();
-    },
-    [edit],
-  );
+  const dateLabels = useLoticsLocale().datePicker;
+  // Segments emit ONLY on a complete "HH:mm", so a half-typed entry (an hour and
+  // no minute) reaches the draft as "" and would otherwise commit as a silent
+  // clear. Blocking on it keeps the entry fixable instead of wiping the value.
+  const incomplete = useRef(false);
 
   const onBlur = useCallback(() => {
     if (controls === "buttons") return;
+    if (incomplete.current) return;
     void edit.commit();
   }, [controls, edit]);
 
@@ -52,7 +50,7 @@ export function InlineTimePicker(props: InlineTimePickerProps) {
       onCommit={() => void edit.commit()}
       onCancel={edit.cancel}
       saving={edit.saving}
-      error={edit.error}
+      error={edit.error ?? (incomplete.current ? dateLabels.invalidTime : null)}
       disabled={disabled}
       accessibilityLabel={accessibilityLabel}
       affordance={<Icon name="clock" size={18} color={colors.zinc[400]} />}
@@ -61,7 +59,8 @@ export function InlineTimePicker(props: InlineTimePickerProps) {
         value={edit.draft}
         onValueChange={edit.setDraft}
         onBlur={onBlur}
-        onKeyDown={onKeyDown}
+        onEscape={edit.cancel}
+        onIncompleteChange={(next) => { incomplete.current = next; }}
         autoFocus
         accessibilityLabel={accessibilityLabel}
       />

package/src/locale.tsx

@@ -162,7 +162,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", startDate: "Start date", endDate: "End date", addTime: "Add time", removeTime: "Remove time", year: "Year", month: "Month", day: "Day", hour: "Hour", minute: "Minute", dayPeriod: "AM/PM", invalidDate: "Enter a complete date" },
+  datePicker: { today: "Today", now: "Now", clear: "Clear", done: "Done", openCalendar: "Open calendar", time: "Time", startTime: "Start time", endTime: "End time", startDate: "Start date", endDate: "End date", addTime: "Add time", removeTime: "Remove time", year: "Year", month: "Month", day: "Day", hour: "Hour", minute: "Minute", dayPeriod: "AM/PM", invalidDate: "Enter a complete date", invalidTime: "Enter a complete time" },
   calendar: { previousMonth: "Previous month", nextMonth: "Next month" },
   filterChip: { clear: "Clear" },
   floatingActionBar: { clear: "Clear" },
@@ -260,7 +260,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", startDate: "Ngày bắt đầu", endDate: "Ngày 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 đủ" },
+  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", startDate: "Ngày bắt đầu", endDate: "Ngày 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 đủ", invalidTime: "Nhập giờ đầy đủ" },
   calendar: { previousMonth: "Tháng trước", nextMonth: "Tháng sau" },
   filterChip: { clear: "Xóa" },
   floatingActionBar: { clear: "Bỏ chọn" },

package/src/time_picker.tsx

@@ -1,56 +1,114 @@
-import type { KeyboardEvent } from "react";
-import { colors } from "@lotics/ui/colors";
-import { fontFamilyRegular, inputTextStyleWeb } from "@lotics/ui/text_utils";
+import { useMemo, useState } from "react";
+import { StyleSheet, View } from "react-native";
+import { colors } from "./colors";
 import { CONTROL_RADIUS, FOCUS_RING, HOVER_BORDER } from "./control_surface";
-import { useFocusRing } from "./use_focus_ring";
 import { useHover } from "./use_hover";
+import { DateSegments } from "./date_segments_field";
+import { SegmentLabels, timeSegmentsConfig } from "./date_segments";
+import { useLoticsLocale, useLocaleTag } from "./locale";
+
 export interface TimePickerProps {
+  /** Canonical 24-hour "HH:mm", `""` when empty — independent of how it displays. */
   value?: string;
   onValueChange: (value: string) => void;
   onBlur?: () => void;
-  /** Web key handler — e.g. an inline editor committing on Enter / reverting on Escape. */
-  onKeyDown?: (e: KeyboardEvent<HTMLInputElement>) => void;
   autoFocus?: boolean;
   disabled?: boolean;
   accessibilityLabel?: string;
+  /**
+   * BCP-47 locale deciding 12- vs 24-hour DISPLAY. Defaults to the active
+   * `LoticsLocaleProvider` locale.
+   *
+   * This is the whole reason the field is segments and not `<input type="time">`:
+   * a native time input takes its 12/24-hour form from the BROWSER's UI locale
+   * and ignores `lang` entirely, so a Vietnamese screen on an en-US browser read
+   * "01:45 PM" next to its own 24-hour "13:45 02/01/2023".
+   */
+  locale?: string;
+  /** Accessible names per segment. Defaults to the `datePicker` locale slice. */
+  segmentLabels?: SegmentLabels;
+  /** Escape pressed in a segment — an inline editor cancels its session. */
+  onEscape?: () => void;
+  /** True while the entry is non-empty but still half-typed (an hour, no minute).
+   *  An inline editor blocks its commit on this. */
+  onIncompleteChange?: (incomplete: boolean) => void;
+  testID?: string;
 }
 
+/**
+ * A time of day. The value is always canonical 24-hour "HH:mm"; the locale only
+ * decides what the user sees and types (an AM/PM segment appears only where the
+ * locale uses one).
+ */
 export function TimePicker(props: TimePickerProps) {
-  const { value, onValueChange, onBlur, onKeyDown, autoFocus, disabled, accessibilityLabel } = props;
-  const { focusVisible, focusProps } = useFocusRing({ always: true });
+  const {
+    value = "",
+    onValueChange,
+    onBlur,
+    autoFocus,
+    disabled,
+    accessibilityLabel,
+    locale,
+    onEscape,
+    onIncompleteChange,
+    testID,
+  } = props;
+  const localeTag = useLocaleTag(locale);
+  const loc = useLoticsLocale().datePicker;
+  const segmentLabels = props.segmentLabels ?? loc;
+  const config = useMemo(() => timeSegmentsConfig(localeTag), [localeTag]);
   const { hovered, hoverProps } = useHover();
+  const [focused, setFocused] = useState(false);
 
   return (
-    <input
-      value={value}
-      onChange={(e) => {
-        onValueChange(e.target.value);
-      }}
-      type="time"
-      {...hoverProps}
-      onFocus={focusProps.onFocus}
-      onBlur={() => { focusProps.onBlur(); onBlur?.(); }}
-      onKeyDown={onKeyDown}
-      autoFocus={autoFocus}
-      disabled={disabled}
-      aria-label={accessibilityLabel}
-      style={{
-        height: 40,
-        paddingLeft: 8,
-        paddingRight: 8,
-        borderRadius: CONTROL_RADIUS,
-        borderWidth: 1,
-        borderStyle: "solid",
-        borderColor: hovered && !disabled ? HOVER_BORDER : colors.border,
-        backgroundColor: colors.background,
-        fontFamily: fontFamilyRegular,
-        ...inputTextStyleWeb,
-        letterSpacing: -0.4,
-        boxShadow: focusVisible ? FOCUS_RING : "none",
-        outline: "none",
-        boxSizing: "border-box",
-        transition: "border-color 0.12s, box-shadow 0.12s",
-      }}
-    />
+    <View
+      {...(hoverProps as object)}
+      style={[
+        styles.frame,
+        hovered && !disabled && styles.frameHovered,
+        focused && !disabled && styles.frameFocused,
+        disabled && styles.frameDisabled,
+      ]}
+      testID={testID}
+    >
+      <DateSegments
+        value={value}
+        onChange={onValueChange}
+        config={config}
+        segmentLabels={segmentLabels}
+        disabled={disabled}
+        autoFocus={autoFocus}
+        accessibilityLabel={accessibilityLabel}
+        onFocus={() => setFocused(true)}
+        onBlur={() => {
+          setFocused(false);
+          onBlur?.();
+        }}
+        onEscape={onEscape}
+        onIncompleteChange={onIncompleteChange}
+      />
+    </View>
   );
 }
+
+const styles = StyleSheet.create({
+  frame: {
+    flexDirection: "row",
+    alignItems: "center",
+    height: 40,
+    paddingHorizontal: 8,
+    borderRadius: CONTROL_RADIUS,
+    borderWidth: 1,
+    borderColor: colors.border,
+    backgroundColor: colors.background,
+  },
+  frameHovered: {
+    borderColor: HOVER_BORDER,
+  },
+  frameFocused: {
+    boxShadow: FOCUS_RING,
+  },
+  frameDisabled: {
+    backgroundColor: colors.zinc[50],
+  },
+});