@lotics/ui 11.2.0 → 11.3.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

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.3.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/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,
   };