@lotics/ui 11.2.0 → 11.4.0

package/AGENTS.md

@@ -227,7 +227,18 @@ clicking floats a multi `OptionList` (checkbox rows), CLOSING commits the new se
 `onSave` — never a borderless `Select` posing as an inline field) — all
 on `useInlineEdit` + `InlineEditView` (custom inputs join via those). `onSave` is async: the
 saving spinner sits INSIDE the control (never a sibling — that reflows); an error shows inline
-without losing the edit. A STACK of rows lives in a `DetailTable` (label ·
+without losing the edit. To let a value be UNSET (a diff-write CLEAR — unassign, remove a due
+date, drop a select), pass **`onClear`** to `InlineSelect` / `InlineMemberSelect` /
+`InlineDatePicker`. It surfaces through each popover's OWN clear affordance — `InlineSelect` renders
+a compact left-aligned "Clear" `Button` below the `OptionList` (only while a value is set);
+`InlineDatePicker` reuses the calendar's own footer "Clear" button. NOT a bolted-on sibling row: that
+can't reach the option list's active-highlight (so the last-hovered option stays lit) and would
+double the footer hairline;
+and never a persistent ✕ on the resting cell (noise on a dense board, and a pressable nested in the
+view's button trigger is invalid DOM). `onSave`'s `next` stays non-null so a caller opts in per field;
+the clear fires `onClear`, which writes `null` (the app workflow must ACCEPT null on that input — a
+`select`/`date`/`member` field clears on null). `InlineTagSelect` (multi) needs no `onClear` — an
+empty set is already a valid `onSave`. A STACK of rows lives in a `DetailTable` (label ·
 value · trailing laid out like a TABLE: `labelWidth` / `trailingWidth` /
 `minHeight` set ONCE on the parent, plus the 6px row gap the zinc-50 chips
 need) holding `DetailRow`s — set `trailingWidth` when ANY row carries a
@@ -1065,7 +1076,7 @@ check_circle (CheckCircle — the completion ring: an empty ring that springs to
 floating_action_bar · filter_chip · column_filter (ColumnFilter — the typed per-column filter pill +
 columnFilterToConditions; for a register filtering on several columns) · chip_group · search_input ·
 sort_header · table · data_grid (DataGrid — the inline-managed grouped table: a grouped, sortable grid of LIVE inline-editor cells (`columns[].cell` → ANY field) + optional per-row `leading` (a CheckCircle) + `renderGroupFooter` (per-group add, align with the exported `gridRowStyle`) + `labels` (localize the sort-header a11y via `SortHeaderLabels`). Owns header/sections/rows; consumer owns data + sort/group/filter/collapse state + toolbar. Renders ALL rows — MODERATE data; 10k+ → the paginated `Table` register. Example: `tpl_task_board`) · pagination · accordion · stepper (Stepper + Step — done/current/upcoming/warning/complete progress on a track (horizontal) or spine (vertical); compound `<Step status>children` OR data `steps[]`+`current`; **navigable** via `Step.onPress` (both orientations — the whole step is the tap target) + `active` to wash the selected one, so it doubles as a section/phase switcher; the guided-run / agent-feed primitive — subsumes the old StepList) ·
-step_progress · timeline (heterogeneous event LOG — per-row icon + expandable details, models the past; NOT progress) · drawer (+ DrawerFooter) · dialog · modal (Modal + ModalHeader + ModalBody + ModalFooter — the full-bleed, edge-to-edge takeover: an OPAQUE surface that COVERS THE WHOLE SCREEN, so unlike Dialog (centered card WITH scrim) and Drawer (docked panel WITH scrim) there is nothing behind it to dim — NO scrim, NO backdrop. Lays children as a flex column: a pinned ModalHeader (eyebrow/title + an actions slot + close), a flex:1 scrolling ModalBody, a pinned ModalFooter (the commit bar, same chrome as DialogFooter/DrawerFooter). Reach for it for a focused capture / multi-step wizard / a console the user steps INTO, where surrounding chrome is a distraction; pick Dialog when the surface is a card the user can see context around) · screen_router (ScreenRouter + Screen + useScreenRouter — the SCREENS compound: a flat navigation stack (`navigate("/case/:id")` pushes, `goBack` pops, `canGoBack`, route `params`; stacked screens stay mounted `display:none` so scroll survives the round trip). Dialog BAKES a router in (`<Dialog><Screen route="">…`); ANY other container hosts the standalone `<ScreenRouter>` — and it wraps AROUND the container so the CHROME can read the stack: a Drawer drilling into a LINKED record swaps its header to a BACK IconButton + the pushed record's id while `canGoBack` (sequence ◀ ▶ hides — stepping the root from inside a linked record disorients), and the pushed `<Screen route="/case/:id">` is a REAL editable workspace with its own footer CTAs. Key the router by record id so stepping ◀ ▶ resets the stack. Worked example: `tpl_item_list` drawer) · popover (Popover + PopoverTrigger + PopoverContent — **PopoverContent already insets its body 12px; put content directly in it, NEVER add your own padding View (that double-pads). Title/actions via PopoverHeader / PopoverFooter**) · popover_nav (usePopoverNav + PopoverScreen + PopoverNavHeader — the popover's built-in mini-router: EVERY `Popover` provides the nav context (`navigate(route)` pushes, `goBack`, `currentRoute`, `canGoBack`; resets on close), `PopoverScreen route=""` is the root and screens render conditionally (unmounted when inactive — no scroll preservation), `PopoverNavHeader` is the title row whose back chevron auto-appears while `canGoBack` (`right` slot, `backLabel`). For a multi-screen menu inside ONE popover (an avatar/settings menu drilling into a sub-panel); route PATTERNS, `params`, and stacked-alive screens are `screen_router`'s job. Distinct from `Popover`'s plain `PopoverHeader` children container) · tooltip ·
+step_progress · timeline (heterogeneous event LOG — per-row icon + expandable details, models the past; NOT progress) · drawer (+ DrawerFooter) · dialog · modal (Modal + ModalHeader + ModalBody + ModalFooter — the full-bleed, edge-to-edge takeover: an OPAQUE surface that COVERS THE WHOLE SCREEN, so unlike Dialog (centered card WITH scrim) and Drawer (docked panel WITH scrim) there is nothing behind it to dim — NO scrim, NO backdrop. Lays children as a flex column: a pinned ModalHeader (eyebrow/title + an actions slot + close), a flex:1 scrolling ModalBody, a pinned ModalFooter (the commit bar, same chrome as DialogFooter/DrawerFooter). Reach for it for a focused capture / multi-step wizard / a console the user steps INTO, where surrounding chrome is a distraction; pick Dialog when the surface is a card the user can see context around) · screen_router (ScreenRouter + Screen + useScreenRouter — the SCREENS compound: a flat navigation stack (`navigate("/case/:id")` pushes, `goBack` pops, `canGoBack`, route `params`; stacked screens stay mounted `display:none` so scroll survives the round trip). Dialog BAKES a router in (`<Dialog><Screen route="">…`); ANY other container hosts the standalone `<ScreenRouter>` — and it wraps AROUND the container so the CHROME can read the stack: a Drawer drilling into a LINKED record swaps its header to a BACK IconButton + the pushed record's id while `canGoBack` (sequence ◀ ▶ hides — stepping the root from inside a linked record disorients), and the pushed `<Screen route="/case/:id">` is a REAL editable workspace with its own footer CTAs. Key the router by record id so stepping ◀ ▶ resets the stack. Worked example: `tpl_item_list` drawer) · popover (Popover + PopoverTrigger + PopoverContent — **NON-MODAL: the anchored popover has NO blocking overlay, so the rest of the page stays interactive; clicking another control both dismisses this popover AND activates that control in one click; clicking outside, scrolling an ancestor, or Escape dismisses. Only `small` (bottom sheet) is modal (scrim). PopoverContent already insets its body 12px; put content directly in it, NEVER add your own padding View (that double-pads). Title/actions via PopoverHeader / PopoverFooter**) · popover_nav (usePopoverNav + PopoverScreen + PopoverNavHeader — the popover's built-in mini-router: EVERY `Popover` provides the nav context (`navigate(route)` pushes, `goBack`, `currentRoute`, `canGoBack`; resets on close), `PopoverScreen route=""` is the root and screens render conditionally (unmounted when inactive — no scroll preservation), `PopoverNavHeader` is the title row whose back chevron auto-appears while `canGoBack` (`right` slot, `backLabel`). For a multi-screen menu inside ONE popover (an avatar/settings menu drilling into a sub-panel); route PATTERNS, `params`, and stacked-alive screens are `screen_router`'s job. Distinct from `Popover`'s plain `PopoverHeader` children container) · tooltip ·
 alert · peek · empty_state · completion_state · callout (Callout · CalloutTitle ·
 CalloutText · CalloutActions) · kpi_card · kpi_strip · summary_line (SummaryLine — the light inline summary of a register/list's FILTERED view, sits below the toolbar; NOT the boxed dashboard `kpi_strip` band) · metric · trend_chip · sparkline ·
 bar_chart · line_chart · pie_chart · ring_gauge · progress_bar · stacked_progress_bar · breakdown ·

package/examples/tpl_task_board.tsx

@@ -265,8 +265,8 @@ export function TplTaskBoard() {
   }
 
   const propertyCols: DataGridColumn<Task>[] = [
-    { key: "assignee", label: "Assignee", width: 160, sortable: true, cell: (t) => <InlineMemberSelect background="transparent" members={MEMBERS} value={t.ownerId} onSave={(id) => patch(t.id, { ownerId: id })} placeholder="Unassigned" accessibilityLabel="Assignee" /> },
-    { key: "due", label: "Due", width: 140, sortable: true, cell: (t) => <InlineDatePicker background="transparent" value={t.due} optionalTime onSave={(v) => patch(t.id, { due: v })} placeholder="No date" accessibilityLabel="Due date" /> },
+    { key: "assignee", label: "Assignee", width: 160, sortable: true, cell: (t) => <InlineMemberSelect background="transparent" members={MEMBERS} value={t.ownerId} onSave={(id) => patch(t.id, { ownerId: id })} onClear={() => patch(t.id, { ownerId: null })} placeholder="Unassigned" accessibilityLabel="Assignee" /> },
+    { key: "due", label: "Due", width: 140, sortable: true, cell: (t) => <InlineDatePicker background="transparent" value={t.due} optionalTime onSave={(v) => patch(t.id, { due: v })} onClear={() => patch(t.id, { due: null })} placeholder="No date" accessibilityLabel="Due date" /> },
     { key: "status", label: "Status", width: 130, sortable: true, cell: (t) => <InlineSelect background="transparent" value={t.status} options={STATUS_OPTIONS} onSave={(s) => patch(t.id, { status: s })} renderSelected={renderStatusBadge} renderOptionContent={renderStatusBadge} accessibilityLabel="Status" /> },
     { key: "tags", label: "Tags", width: 168, cell: (t) => <Select multi searchable allowCustom value={t.tags.map((tag) => tag.value)} onValueChange={(next) => patch(t.id, { tags: next.map(tagOf) })} options={TAG_OPTIONS} renderSelected={renderTagBadge} renderOptionContent={renderTagBadge} style={{ borderColor: "transparent" }} placeholder="Add tags" accessibilityLabel="Tags" /> },
   ];

package/package.json

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

package/src/date_calendar.tsx

@@ -7,6 +7,15 @@ import { Picker, PickerOption } from "./picker";
 import { IconButton } from "./icon_button";
 import { FOCUS_RING } from "./control_surface";
 import { useFocusRing } from "./use_focus_ring";
+import { useLoticsLocale } from "./locale";
+
+/** Accessible names for the calendar's month-navigation arrows. Backs the
+ *  `calendar` locale slice. (The month/weekday NAMES come from `Intl` + the
+ *  `locale` prop, not from here.) */
+export interface CalendarLabels {
+  previousMonth: string;
+  nextMonth: string;
+}
 
 function DayCell(props: {
   day: number;
@@ -237,6 +246,7 @@ function CalendarMonth(props: CalendarMonthProps) {
     firstDayOfWeek = 1, // Default to Monday
     locale,
   } = props;
+  const navLabels = useLoticsLocale().calendar;
 
   const names = getLocalizedNames(locale);
   const daysInMonth = getDaysInMonth(year, month);
@@ -314,14 +324,14 @@ function CalendarMonth(props: CalendarMonthProps) {
         {showNavigation && (
           <IconButton
             icon="chevron-left"
-            accessibilityLabel="Previous month"
+            accessibilityLabel={navLabels.previousMonth}
             onPress={handlePrevMonth}
           />
         )}
         {showLeftArrow && onPrevMonth && (
           <IconButton
             icon="chevron-left"
-            accessibilityLabel="Previous month"
+            accessibilityLabel={navLabels.previousMonth}
             onPress={onPrevMonth}
           />
         )}
@@ -348,14 +358,14 @@ function CalendarMonth(props: CalendarMonthProps) {
         {showNavigation && (
           <IconButton
             icon="chevron-right"
-            accessibilityLabel="Next month"
+            accessibilityLabel={navLabels.nextMonth}
             onPress={handleNextMonth}
           />
         )}
         {showRightArrow && onNextMonth && (
           <IconButton
             icon="chevron-right"
-            accessibilityLabel="Next month"
+            accessibilityLabel={navLabels.nextMonth}
             onPress={onNextMonth}
           />
         )}

package/src/date_picker.tsx

@@ -7,6 +7,7 @@ import { Calendar, CalendarRangeValue } from "./date_calendar";
 import { TimePicker } from "./time_picker";
 import { DateField } from "./date_field";
 import { SegmentLabels } from "./date_segments";
+import { useLoticsLocale } from "./locale";
 import { Icon } from "./icon";
 import { Button } from "./button";
 import { IconButton } from "./icon_button";
@@ -28,6 +29,10 @@ import {
 // Types
 // =============================================================================
 
+/** All translatable strings the date picker renders — the calendar popover's
+ *  quick actions + accessible names, plus the segmented field's per-segment
+ *  labels ({@link SegmentLabels}). Backs the `datePicker` locale slice; a caller
+ *  may still override per-instance via a `labels` prop. */
 export interface DatePickerLabels extends SegmentLabels {
   /** Quick action: set the value to today. Shown for the `date` format. */
   today: string;
@@ -51,25 +56,6 @@ export interface DatePickerLabels extends SegmentLabels {
   removeTime: string;
 }
 
-const DEFAULT_LABELS: DatePickerLabels = {
-  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",
-};
-
 export interface DatePickerProps {
   value?: string | null;
   onValueChange: (value: string) => void;
@@ -82,7 +68,9 @@ export interface DatePickerProps {
   /** Fires when the text input loses focus, after any typed value is committed. */
   onBlur?: () => void;
   testID?: string;
-  /** Translated labels for the popover quick actions and accessible names. Defaults to English. */
+  /** Per-instance label overrides (quick actions + accessible names). Anything
+   *  omitted resolves from the `datePicker` locale slice — English by default, or
+   *  the active `LoticsLocaleProvider` pack. */
   labels?: Partial<DatePickerLabels>;
   /** BCP-47 locale for the calendar's weekday/month names. Defaults to "en-US". */
   locale?: string;
@@ -119,7 +107,7 @@ export function DatePickerPanel(props: DatePickerPanelProps) {
   const optTime = !!optionalTime && !isRange;
   const valueHasTime = isoHasTime(value);
   const hasTime = optTime ? valueHasTime : hasTimeFormat(format);
-  const mergedLabels = { ...DEFAULT_LABELS, ...labels };
+  const mergedLabels = { ...useLoticsLocale().datePicker, ...labels };
 
   const [startIso, endIso] = useMemo<[string, string]>(() => {
     if (!value) return ["", ""];
@@ -342,9 +330,10 @@ export function DatePicker(props: DatePickerProps) {
   const optTime = !!optionalTime && !isRange;
   // The trigger's segments follow the value's shape in optionalTime mode.
   const hasTime = optTime ? isoHasTime(value) : hasTimeFormat(format);
+  const datePickerLabels = useLoticsLocale().datePicker;
   const mergedLabels = useMemo<DatePickerLabels>(
-    () => ({ ...DEFAULT_LABELS, ...labels }),
-    [labels],
+    () => ({ ...datePickerLabels, ...labels }),
+    [datePickerLabels, labels],
   );
 
   const [open, setOpen] = useState(false);

package/src/inline_date_picker.tsx

@@ -15,6 +15,11 @@ 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). */
+  onClear?: () => void | Promise<void>;
   /** "date" (default) or "datetime". */
   format?: "date" | "datetime";
   /** Let the user OPTIONALLY add a time to a date (the value's shape decides — date
@@ -37,7 +42,7 @@ export interface InlineDatePickerProps {
  * dismissing without a change reverts.
  */
 export function InlineDatePicker(props: InlineDatePickerProps) {
-  const { value, onSave, format = "date", optionalTime, placeholder, locale, disabled, accessibilityLabel , background } = props;
+  const { value, onSave, onClear, format = "date", optionalTime, placeholder, locale, disabled, accessibilityLabel , background } = props;
   const labels = useLoticsLocale().inline;
   const [open, setOpen] = useState(false);
   const [draft, setDraft] = useState<string | null>(value);
@@ -49,7 +54,23 @@ export function InlineDatePicker(props: InlineDatePickerProps) {
 
   const commit = useCallback(async () => {
     const next = draftRef.current;
-    if (next === value || !next) return;
+    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);
+      }
+      return;
+    }
     setSaving(true);
     setError(null);
     try {
@@ -59,7 +80,7 @@ export function InlineDatePicker(props: InlineDatePickerProps) {
     } finally {
       setSaving(false);
     }
-  }, [value, onSave]);
+  }, [value, onSave, onClear, labels.saveError]);
 
   const onOpenChange = useCallback(
     (next: boolean) => {
@@ -108,7 +129,11 @@ export function InlineDatePicker(props: InlineDatePickerProps) {
             format={format}
             optionalTime={optionalTime}
             locale={locale}
-            onRequestClose={() => setOpen(false)}
+            // 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)}
           />
         </PopoverContent>
       </Popover>

package/src/inline_member_select.tsx

@@ -16,6 +16,10 @@ interface InlineMemberSelectProps {
   /** Commit a new assignment (the picked member id). Throwing surfaces the
    *  inline error and reverts, like every inline editor. */
   onSave: (memberId: string) => void | Promise<void>;
+  /** Unassign — unset the field to empty. Provide it to make the assignment
+   *  clearable: a compact "Clear" button appears below the picker options when a
+   *  member is set. Kept separate from `onSave` (whose id is non-null). */
+  onClear?: () => void | Promise<void>;
   placeholder?: string;
   disabled?: boolean;
   accessibilityLabel?: string;

package/src/inline_select.tsx

@@ -13,6 +13,11 @@ import { useLoticsLocale } from "./locale";
 export interface InlineSelectProps<T extends string> {
   value: T | null;
   onSave: (next: T) => void | Promise<void>;
+  /** Unset the field to empty. Provide it to make the value clearable: a compact
+   *  "Clear" button appears below the options whenever there IS a value. Kept
+   *  separate from `onSave` (whose next is a non-null `T`) so an app opts in
+   *  without every caller having to handle null. */
+  onClear?: () => void | Promise<void>;
   options: PickerOption<T>[];
   /** Custom option content in the dropdown (icon + label, two-line, a badge…).
    *  Omit for a plain label list — both render through the same `OptionList`. */
@@ -39,7 +44,7 @@ export interface InlineSelectProps<T extends string> {
  * Pass `renderOptionContent` for rich options, or omit it for a plain label list.
  */
 export function InlineSelect<T extends string>(props: InlineSelectProps<T>) {
-  const { value, onSave, options, renderOptionContent, renderSelected, placeholder, disabled, accessibilityLabel, searchable = false, background } = props;
+  const { value, onSave, onClear, options, renderOptionContent, renderSelected, placeholder, disabled, accessibilityLabel, searchable = false, background } = props;
   const labels = useLoticsLocale().inline;
   const [open, setOpen] = useState(false);
   const [saving, setSaving] = useState(false);
@@ -64,6 +69,20 @@ export function InlineSelect<T extends string>(props: InlineSelectProps<T>) {
     [value, onSave],
   );
 
+  const clear = useCallback(async () => {
+    setOpen(false);
+    if (value == null || !onClear) return;
+    setSaving(true);
+    setError(null);
+    try {
+      await onClear();
+    } catch (e) {
+      setError(e instanceof Error && e.message ? e.message : labels.saveError);
+    } finally {
+      setSaving(false);
+    }
+  }, [value, onClear]);
+
   return (
     <View>
       <Popover open={open && !disabled} onOpenChange={setOpen} side="bottom" align="start" inheritTriggerWidth>
@@ -90,6 +109,7 @@ export function InlineSelect<T extends string>(props: InlineSelectProps<T>) {
             options={options}
             value={value}
             onValueChange={(next) => void pick(next)}
+            onClear={onClear ? () => void clear() : undefined}
             onRequestClose={() => setOpen(false)}
             renderOptionContent={renderOptionContent}
           />

package/src/locale.tsx

@@ -1,4 +1,6 @@
 import { createContext, useContext, type ReactNode } from "react";
+import { type DatePickerLabels } from "./date_picker";
+import { type CalendarLabels } from "./date_calendar";
 import { type PaginationLabels } from "./pagination";
 import { type SortHeaderLabels } from "./sort_header";
 import { type ConfidenceLabels } from "./confidence";
@@ -28,7 +30,9 @@ export interface LoticsLocale {
   /** `OptionList` (and everything built on it — `Select`, `Combobox`, the
    *  in-cell editors): the select-all/deselect-all links, the empty state, the
    *  internal search-field placeholder, and the `Combobox` recents header. */
-  optionList: { selectAll: string; deselectAll: string; noResults: string; recent: string; searchPlaceholder: string };
+  optionList: { selectAll: string; deselectAll: string; clear: string; noResults: string; recent: string; searchPlaceholder: string };
+  datePicker: DatePickerLabels;
+  calendar: CalendarLabels;
   /** `FilterChip` (and `ColumnFilter`): the generic clear affordance, used when
    *  a call site doesn't pass a dimension-specific `clearLabel`. */
   filterChip: { clear: string };
@@ -99,7 +103,9 @@ export const en: LoticsLocale = {
     ascending: ", ascending",
     descending: ", descending",
   },
-  optionList: { selectAll: "Select all", deselectAll: "Deselect all", noResults: "No results", recent: "Recent", searchPlaceholder: "Search…" },
+  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" },
+  calendar: { previousMonth: "Previous month", nextMonth: "Next month" },
   filterChip: { clear: "Clear" },
   formField: { optional: "Optional" },
   drawer: { previous: "Previous record", next: "Next record", close: "Close" },
@@ -176,7 +182,9 @@ export const vi: LoticsLocale = {
     ascending: " (tăng dần)",
     descending: " (giảm dần)",
   },
-  optionList: { selectAll: "Chọn tất cả", deselectAll: "Bỏ chọn tất cả", noResults: "Không có kết quả", recent: "Gần đây", searchPlaceholder: "Tìm…" },
+  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" },
+  calendar: { previousMonth: "Tháng trước", nextMonth: "Tháng sau" },
   filterChip: { clear: "Xóa" },
   formField: { optional: "Tùy chọn" },
   drawer: { previous: "Bản ghi trước", next: "Bản ghi sau", close: "Đóng" },

package/src/option_list.tsx

@@ -5,6 +5,7 @@ import { Text } from "./text";
 import { Icon } from "./icon";
 import { Checkbox } from "./checkbox";
 import { MenuButton } from "./menu_button";
+import { Button } from "./button";
 import { TextLink } from "./text_link";
 import { ActivityIndicator } from "./activity_indicator";
 import { TextInputField } from "./text_input_field";
@@ -25,6 +26,11 @@ export interface OptionListProps<T extends string = string, MULTI extends boolea
   accessibilityLabel?: string;
   selectAllLabel?: string;
   deselectAllLabel?: string;
+  /** Single-select only: unset the value. When provided AND a value is selected, a
+   *  "Clear" row shows below the options (a real `MenuButton`, so it shares the
+   *  option rows' height/hover/a11y). Hovering it moves the active highlight OFF
+   *  the options — hence it lives inside the list, not as a sibling. */
+  onClear?: () => void;
 }
 
 /**
@@ -39,7 +45,7 @@ export interface OptionListProps<T extends string = string, MULTI extends boolea
 export function OptionList<T extends string, MULTI extends boolean = false, D = unknown>(
   props: OptionListProps<T, MULTI, D>,
 ) {
-  const { testID, renderOptionContent, getOptionDescription, loading = false, accessibilityLabel, search } = props;
+  const { testID, renderOptionContent, getOptionDescription, loading = false, accessibilityLabel, search, onClear } = props;
   const loc = useLoticsLocale().optionList;
   const emptyText = props.emptyText ?? loc.noResults;
   const selectAllLabel = props.selectAllLabel ?? loc.selectAll;
@@ -47,6 +53,12 @@ export function OptionList<T extends string, MULTI extends boolean = false, D =
   const list = useOptionList(props);
   const { small } = useScreenSize();
 
+  // The option rows set `activeIndex` on hover but have no hover-OUT, so entering
+  // the Clear footer clears it here — otherwise the last-hovered option stays lit
+  // while the pointer is on Clear. RN's types don't declare mouse handlers;
+  // rn-web forwards them to the DOM (the boundary cast pressable_row.tsx uses).
+  const clearHover = { onMouseEnter: () => list.setActiveIndex(-1, false) } as object;
+
   const onSearchKeyPress = (e: { nativeEvent: { key: string }; preventDefault: () => void }) => {
     if (list.handleKey(e.nativeEvent.key)) e.preventDefault();
   };
@@ -157,6 +169,14 @@ export function OptionList<T extends string, MULTI extends boolean = false, D =
         )}
       </ScrollView>
 
+      {onClear && !props.multi && list.hasSelection ? (
+        // A plain compact Button (matches the inline date picker's footer "Clear"),
+        // not a full-width row.
+        <View style={styles.clearRow} {...clearHover}>
+          <Button title={loc.clear} color="muted" onPress={onClear} />
+        </View>
+      ) : null}
+
       {list.showSelectAll || list.showDeselectAll ? (
         <View style={styles.selectAllContainer}>
           {list.showSelectAll ? <TextLink onPress={list.selectAll}>{selectAllLabel}</TextLink> : null}
@@ -192,6 +212,14 @@ const styles = StyleSheet.create({
   option: {
     marginHorizontal: 0,
   },
+  // The single-select "Clear" footer — a left-aligned compact button, set off from
+  // the options above by the same hairline the select-all/deselect-all footer uses.
+  clearRow: {
+    flexDirection: "row",
+    paddingTop: 4,
+    borderTopWidth: 1,
+    borderTopColor: colors.border,
+  },
   statusRow: {
     alignItems: "center",
     justifyContent: "center",

package/src/popover.tsx

@@ -188,7 +188,7 @@ export interface PopoverContentProps {
    *  restores it on close. Set false for an anchored panel whose trigger must
    *  keep focus — e.g. a search-as-you-type combobox whose input lives outside
    *  the popover and drives the list via `aria-activedescendant`. Focus then
-   *  stays on the trigger; keyboard still reaches it through the overlay. */
+   *  stays on the trigger; keyboard still reaches the content. */
   manageFocus?: boolean;
 }
 
@@ -212,9 +212,9 @@ export function PopoverContent(props: PopoverContentProps) {
   const [isBottomSheetShown, setIsBottomSheetShown] = useState(false);
   const returnFocusRef = useRef<HTMLElement | null>(null);
   // Last known trigger geometry. The trigger can unmount while the popover is
-  // open — a hover-revealed menu button stops being rendered the moment our
-  // overlay covers its row and the hover ends — so positioning cannot rely on
-  // `triggerRef.current` still being live when it runs.
+  // open — a hover-revealed menu button stops being rendered once its row loses
+  // hover/focus — so positioning cannot rely on `triggerRef.current` still being
+  // live when it runs.
   const triggerRectRef = useRef<DOMRect | null>(null);
 
   const handleClose = useCallback(() => {
@@ -224,9 +224,9 @@ export function PopoverContent(props: PopoverContentProps) {
 
   // Snapshot the trigger geometry synchronously the moment we open, while it is
   // guaranteed to still be mounted. `calculatePosition` runs later in a rAF, by
-  // which point a hover-revealed trigger may already be gone (our overlay covers
-  // its row, hover ends, the button unmounts). Capturing here keeps the popover
-  // anchored to where the trigger was instead of stranding it off-screen.
+  // which point a hover-revealed trigger may already be gone (a hover-revealed row
+  // button can unmount once hover/focus leaves the row). Capturing here keeps the
+  // popover anchored to where the trigger was instead of stranding it off-screen.
   useLayoutEffect(() => {
     if (!open || small) return;
     if (triggerRef.current) {
@@ -249,7 +249,10 @@ export function PopoverContent(props: PopoverContentProps) {
       const firstFocusable = content.querySelector<HTMLElement>(
         'input, select, textarea, button, [role="button"], [role="menuitem"], [role="option"], [tabindex]:not([tabindex="-1"])',
       );
-      (firstFocusable ?? content).focus();
+      // preventScroll: focusing the content must never scroll an ancestor into
+      // view — that scroll would trip the scroll-to-dismiss listener and close the
+      // popover the instant it opens.
+      (firstFocusable ?? content).focus({ preventScroll: true });
     });
 
     return () => {
@@ -262,11 +265,11 @@ export function PopoverContent(props: PopoverContentProps) {
       // popover (a Picker/InlineSelect/menu) it is <body>; restoring there strands
       // focus and the next Tab jumps to the page's first focusable. Fall back to
       // the prior element only if the trigger is gone (e.g. a hover-revealed menu
-      // button that unmounted under the overlay).
+      // button that unmounted once its row lost hover).
       const trigger = triggerRef.current;
       const target = trigger && trigger.isConnected ? trigger : prior;
       if (target && typeof target.focus === "function") {
-        target.focus();
+        target.focus({ preventScroll: true });
       }
     };
   }, [open, manageFocus]);
@@ -313,6 +316,34 @@ export function PopoverContent(props: PopoverContentProps) {
     };
   }, [open, small, onOpenChange]);
 
+  // Outside-dismiss (NON-MODAL anchored popover): with no blocking overlay, the
+  // rest of the page stays interactive, so we close on a click that lands outside
+  // this popover's content AND its trigger. We listen on `click` (not pointerdown)
+  // in the CAPTURE phase so that clicking ANOTHER field's trigger completes that
+  // trigger's own press — the old popover dismisses AND the new one opens in a
+  // single click, instead of the press being cancelled mid-gesture. A click INSIDE
+  // a deeper (nested) popover keeps this one open — a Select opened inside a filter
+  // popover must not dismiss the filter. The bottom sheet (`small`) is modal and
+  // dismisses via its scrim, so it opts out here.
+  useEffect(() => {
+    if (!open || small) return;
+    const onOutsideClick = (e: MouseEvent) => {
+      const node = e.target instanceof Node ? e.target : null;
+      if (!node) return;
+      if (popoverRef.current?.contains(node)) return; // inside my content
+      if (triggerRef.current?.contains(node)) return; // on my trigger — its own press toggles
+      // Keep open when the click is inside a DEEPER popover (e.g. a Select opened
+      // inside this one). `data-popover-level` is the same nesting depth as z-index.
+      const myLevel = Number(popoverRef.current?.getAttribute("data-popover-level") ?? "0");
+      const el = node instanceof Element ? node : node.parentElement;
+      const hit = el?.closest("[data-popover]");
+      if (hit && Number(hit.getAttribute("data-popover-level") ?? "0") > myLevel) return; // deeper popover
+      onOpenChange(false);
+    };
+    document.addEventListener("click", onOutsideClick, true);
+    return () => document.removeEventListener("click", onOutsideClick, true);
+  }, [open, small, onOpenChange, triggerRef]);
+
   const calculatePosition = useCallback(() => {
     if (!popoverRef.current) return;
     if (small) return;
@@ -476,11 +507,26 @@ export function PopoverContent(props: PopoverContentProps) {
       }
     });
 
+    // Non-modal: the page can now scroll UNDER an open popover. A scroll of the
+    // page or any ancestor is a "moved on" signal, so we DISMISS (as native
+    // <select> and most menu systems do) rather than chase the trigger and risk a
+    // panel detached from an off-screen anchor. Scrolling the popover's OWN content
+    // (a long option list) must NOT close it. Capture catches nested scrollers.
+    const onScroll = (e: Event) => {
+      if (e.target instanceof Node && popoverRef.current?.contains(e.target)) return;
+      onOpenChange(false);
+    };
+    window.addEventListener("scroll", onScroll, true);
+    // A window resize just re-anchors (the layout moved, the intent didn't).
+    window.addEventListener("resize", calculatePosition);
+
     return () => {
       cancelAnimationFrame(frame);
       resizeObserver?.disconnect();
+      window.removeEventListener("scroll", onScroll, true);
+      window.removeEventListener("resize", calculatePosition);
     };
-  }, [open, calculatePosition, small]);
+  }, [open, calculatePosition, small, onOpenChange]);
 
   const handleOverlayClick = useCallback(
     (e: React.MouseEvent) => {
@@ -501,27 +547,32 @@ export function PopoverContent(props: PopoverContentProps) {
 
   return (
     <Portal>
-      {/* Overlay */}
-      <div
-        style={{
-          position: "fixed",
-          top: 0,
-          left: 0,
-          right: 0,
-          bottom: 0,
-          backgroundColor: small ? "rgba(0, 0, 0, 0.5)" : "transparent",
-          opacity: small ? (isBottomSheetShown ? 1 : 0) : 1,
-          transition: small ? "opacity 0.3s ease" : undefined,
-          zIndex: overlayZIndex,
-          pointerEvents: "auto",
-        }}
-        onClick={handleOverlayClick}
-        onMouseDown={(e) => e.stopPropagation()}
-      />
+      {/* Modal scrim — ONLY for the bottom-sheet (`small`) mode, which IS modal.
+          The anchored popover is NON-MODAL: no overlay, so the rest of the page
+          stays interactive; outside-dismiss is the click listener above. */}
+      {small && (
+        <div
+          style={{
+            position: "fixed",
+            top: 0,
+            left: 0,
+            right: 0,
+            bottom: 0,
+            backgroundColor: "rgba(0, 0, 0, 0.5)",
+            opacity: isBottomSheetShown ? 1 : 0,
+            transition: "opacity 0.3s ease",
+            zIndex: overlayZIndex,
+            pointerEvents: "auto",
+          }}
+          onClick={handleOverlayClick}
+          onMouseDown={(e) => e.stopPropagation()}
+        />
+      )}
       {/* Popover */}
       <div
         ref={popoverRef}
         data-popover="true"
+        data-popover-level={nestingLevel}
         data-testid={testID}
         role="dialog"
         aria-modal={small ? true : undefined}

package/src/use_option_list.ts

@@ -86,6 +86,8 @@ export interface UseOptionList<T extends string, D> {
   deselectAll: () => void;
   showSelectAll: boolean;
   showDeselectAll: boolean;
+  /** Whether anything is selected — single: a non-empty value; multi: ≥1. */
+  hasSelection: boolean;
   listboxId: string;
   scrollRef: React.RefObject<ScrollView | null>;
 }
@@ -351,6 +353,7 @@ export function useOptionList<T extends string, MULTI extends boolean = false, D
     deselectAll,
     showSelectAll,
     showDeselectAll,
+    hasSelection,
     listboxId,
     scrollRef,
   };