@lotics/ui 5.8.0 → 5.10.0

package/src/combobox.tsx

@@ -2,14 +2,13 @@ import {
   View,
   ScrollView,
   StyleSheet,
-  Pressable,
   type StyleProp,
   type ViewStyle,
   type TextInput as RNTextInput,
 } from "react-native";
-import { useCallback, useEffect, useId, useMemo, useRef, useState, type ReactNode } from "react";
+import { useCallback, useRef, useState, type ReactNode } from "react";
 import { colors } from "./colors";
-import { ACTIVE_RING, CONTROL_RADIUS } from "./control_surface";
+import { FOCUS_RING } from "./control_surface";
 import { Text } from "./text";
 import { Icon, type IconName } from "./icon";
 import { TextInputField } from "./text_input_field";
@@ -18,7 +17,7 @@ import { ActivityIndicator } from "./activity_indicator";
 import { Popover, PopoverContent } from "./popover";
 import type { PickerOption } from "./picker";
 import { useDebouncedCallback } from "./use_debounced_callback";
-import { useListKeyboardNav } from "./use_list_keyboard_nav";
+import { useOptionList } from "./use_option_list";
 
 export interface ComboboxProps<T extends string = string, D = unknown> {
   /** Result options for the current query. With `onSearchChange` the consumer
@@ -29,23 +28,17 @@ export interface ComboboxProps<T extends string = string, D = unknown> {
   /** Server-side search: debounced, fires as the user types. Omit for local
    *  label filtering of `options`. */
   onSearchChange?: (query: string) => void;
-  /** Multi-select: selected options render as dismissible chips inside the input;
-   *  the input stays a search field. Pair with `value` (the selected array) and
-   *  `onRemove`. */
-  multi?: boolean;
-  /** Selected option(s). Single → the option to reflect in the input (or null).
-   *  Multi → the array of selected options rendered as chips. */
-  value?: PickerOption<T, D> | PickerOption<T, D>[] | null;
-  /** Multi: remove a selected chip. */
-  onRemove?: (option: PickerOption<T, D>) => void;
-  /** Single only: reflect the picked label in the input (classic autocomplete).
-   *  Default true. Set false to keep the input a pure search and render the
-   *  selection yourself (e.g. in a list below). */
+  /** The selected option to reflect in the input (or null). */
+  value?: PickerOption<T, D> | null;
+  /** Reflect the picked label in the input (classic autocomplete). Default true.
+   *  Set false to keep the input a pure search and render the selection yourself
+   *  (e.g. in a list below). For a multi-value CHIP field use `Select multi`
+   *  (its `renderSelected` returns a removable `Chip`). */
   reflectSelection?: boolean;
   /** Custom rendering of an option row in the dropdown. The input itself is a
    *  plain text field (it can only show the label string) — to display a
    *  selection with custom rendering, use `reflectSelection={false}` and render
-   *  the picked option(s) yourself below. */
+   *  the picked option yourself below. */
   renderOptionContent?: (option: PickerOption<T, D>) => ReactNode;
   /** Row subtitle pulled from the option (single-line, under the title). */
   getOptionDescription?: (option: PickerOption<T, D>) => string | undefined;
@@ -68,16 +61,16 @@ export interface ComboboxProps<T extends string = string, D = unknown> {
   /** Leading icon inside the input. OMIT (the default) for a SELECT — no leading
    *  glyph, a trailing chevron — so a "pick a code/record" combobox reads as a
    *  picker, not a free-text search box. Opt IN to the search-box look explicitly
-   *  with `icon="search"` (leading glyph, no chevron). Multi-select shows neither. */
+   *  with `icon="search"` (leading glyph, no chevron). */
   icon?: IconName;
   placeholder?: string;
   recentsLabel?: string;
   emptyText?: string;
   accessibilityLabel?: string;
   disabled?: boolean;
-  /** Single-select only: show an in-input clear ✕ whenever the input has text
-   *  (a reflected selection or a typed query). Pressing it empties the input,
-   *  resets the search, and fires `onClear` so the consumer can deselect. */
+  /** Show an in-input clear ✕ whenever the input has text (a reflected selection
+   *  or a typed query). Pressing it empties the input, resets the search, and
+   *  fires `onClear` so the consumer can deselect. */
   clearable?: boolean;
   /** Fired when the clear ✕ is pressed (the input + search are reset first). */
   onClear?: () => void;
@@ -88,31 +81,24 @@ export interface ComboboxProps<T extends string = string, D = unknown> {
   style?: StyleProp<ViewStyle>;
 }
 
-const OPTION_HEIGHT = 52;
-const CUSTOM_VALUE = "__combobox_custom__";
-
 /**
  * The ARIA combobox: an editable input whose typing drives a (debounced) search,
  * with results in a Popover listbox below. The input owns the keyboard (↑/↓ move
- * the active row, Enter selects, Esc closes) — not a button trigger.
- *
- * Selection display is flexible:
- *  - single (default): the picked label reflects into the input (`reflectSelection`),
- *    or set `reflectSelection={false}` to keep the input a pure search and render
- *    the selection below yourself;
- *  - `multi`: selected options render as dismissible chips inside the input and
- *    the input stays a search field.
+ * the active row, Enter selects, Esc closes) — not a button trigger; on an empty
+ * field it browses the full set (or `recentOptions`). Shares the `useOptionList`
+ * row model + nav with the rest of the kit's selectors.
  *
- * For a "select from a known list" control (no search box, typeahead), use `Picker`.
+ * Selection display: the picked label reflects into the input (`reflectSelection`),
+ * or set `reflectSelection={false}` to keep the input a pure search and render the
+ * selection below yourself. For a "pick from a known list" control use `Picker`
+ * (native, plain) or `Select` (rich/multi, or a chip box via `renderSelected`).
  */
 export function Combobox<T extends string = string, D = unknown>(props: ComboboxProps<T, D>) {
   const {
     options,
     onValueChange,
     onSearchChange,
-    multi = false,
     value,
-    onRemove,
     reflectSelection = true,
     renderOptionContent,
     getOptionDescription,
@@ -136,66 +122,34 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
     style,
   } = props;
 
-  const chips = multi && Array.isArray(value) ? value : [];
-  const single = !multi && value && !Array.isArray(value) ? value : null;
+  const single = value ?? null;
+  const reflectedText = single ? (single.label ?? single.value) : "";
 
-  const [query, setQuery] = useState(
-    !multi && reflectSelection && single ? (single.label ?? single.value) : "",
-  );
+  const [query, setQuery] = useState(reflectSelection && single ? reflectedText : "");
   const [open, setOpen] = useState(autoFocus);
   const triggerRef = useRef<View>(null);
   const inputRef = useRef<RNTextInput>(null);
-  const scrollRef = useRef<ScrollView>(null);
   // Options are focusable (RN-Web Pressable), so a mouse-press on one blurs the
   // input; commit then refocuses it to keep the textbox focus (aria pattern),
   // which would re-fire onFocus and reopen the popover. This one-shot flag lets
-  // that programmatic refocus pass without reopening — set on a single-select
-  // commit, consumed by the next onFocus, and cleared on blur (the keyboard
-  // path never blurs, so the refocus is a no-op and onFocus never fires).
+  // that programmatic refocus pass without reopening — set on commit, consumed by
+  // the next onFocus, and cleared on blur (the keyboard path never blurs, so the
+  // refocus is a no-op and onFocus never fires).
   const suppressFocusOpenRef = useRef(false);
-  const baseId = useId();
-  const listboxId = `${baseId}-listbox`;
-  const optionId = (i: number) => `${baseId}-option-${i}`;
 
-  const searching = query.trim().length > 0;
   const isServer = onSearchChange !== undefined;
-
-  // Local filtering when not server-driven. Reflected single value shouldn't
-  // filter the list to itself, so only filter once the query diverges.
-  const filtered = useMemo(() => {
-    if (isServer || !searching) return options;
-    if (!multi && reflectSelection && single && query === (single.label ?? single.value)) {
-      return options;
-    }
-    const q = query.toLowerCase();
-    return options.filter((o) => (o.label ?? o.value).toLowerCase().includes(q));
-  }, [isServer, searching, options, multi, reflectSelection, single, query]);
-
-  // Free-entry row, appended when the query matches no option exactly. Match
-  // both label AND value — a query equal to an option's value (e.g. a code typed
-  // in full) must NOT also offer "Add <code>", or the two share a key.
-  const customRow = useMemo((): PickerOption<T, D> | null => {
-    if (!allowCustom || !searching) return null;
-    const q = query.trim();
-    const ql = q.toLowerCase();
-    const exact = options.some((o) => (o.label ?? o.value).toLowerCase() === ql || String(o.value).toLowerCase() === ql);
-    if (exact) return null;
-    const label = customOptionLabel ? customOptionLabel(q) : `Add "${q}"`;
-    if (label === null) return null;
-    return { value: q as T, label, testID: CUSTOM_VALUE };
-  }, [allowCustom, searching, query, options, customOptionLabel]);
-
-  const list = useMemo(() => {
-    const base = searching ? filtered : (recentOptions ?? []);
-    if (!customRow) return base;
-    return customOptionPlacement === "top" ? [customRow, ...base] : [...base, customRow];
-  }, [searching, filtered, recentOptions, customRow, customOptionPlacement]);
-
   const debouncedSearch = useDebouncedCallback(onSearchChange ?? (() => {}), searchDebounceMs);
 
-  const scrollToIndex = useCallback((index: number) => {
-    scrollRef.current?.scrollTo({ y: Math.max(0, index * OPTION_HEIGHT - 80), animated: false });
-  }, []);
+  // The displayed text equals the reflected selection until the user types — show
+  // ALL options then (browse), not the list filtered to the selected label.
+  const filterQuery = reflectSelection && single && query === reflectedText ? "" : query;
+
+  const findOption = useCallback(
+    (val: T): PickerOption<T, D> =>
+      options.find((o) => o.value === val) ??
+      recentOptions?.find((o) => o.value === val) ?? { value: val, label: val },
+    [options, recentOptions],
+  );
 
   const commit = useCallback(
     (opt: PickerOption<T, D>) => {
@@ -204,59 +158,28 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
         debouncedSearch.cancel();
         onSearchChange?.("");
       }
-      if (multi) {
-        // Input stays a search field; the chip is rendered from `value`.
-        setQuery("");
-      } else if (reflectSelection) {
-        setQuery(opt.label ?? opt.value);
-      } else {
-        setQuery("");
-      }
+      setQuery(reflectSelection ? (opt.label ?? opt.value) : "");
       setOpen(false);
-      // Single-select: the refocus below must not reopen the just-closed menu.
-      // Multi-select keeps the menu open to add more, so it isn't suppressed.
-      if (!multi) suppressFocusOpenRef.current = true;
+      // The refocus below must not reopen the just-closed menu.
+      suppressFocusOpenRef.current = true;
       inputRef.current?.focus();
     },
-    [onValueChange, isServer, debouncedSearch, onSearchChange, multi, reflectSelection],
+    [onValueChange, isServer, debouncedSearch, onSearchChange, reflectSelection],
   );
 
-  const handleSelect = useCallback(
-    (index: number) => {
-      const opt = list[index];
-      if (!opt || opt.disabled) return;
-      // The custom row displays `Add "x"` but emits the raw query as both value
-      // and label (so it reflects/round-trips as the typed text, not "Add …").
-      const emitted =
-        opt.testID === CUSTOM_VALUE
-          ? ({ value: opt.value, label: opt.value } as PickerOption<T, D>)
-          : opt;
-      commit(emitted);
-    },
-    [list, commit],
-  );
-
-  const { activeIndex, setActiveIndex, handleKey } = useListKeyboardNav({
-    count: list.length,
-    isDisabled: (i) => list[i]?.disabled ?? false,
-    onSelect: handleSelect,
-    onClose: () => setOpen(false),
-    onActiveChange: scrollToIndex,
+  const list = useOptionList<T, false, D>({
+    options,
+    value: single?.value ?? null,
+    onValueChange: (val) => commit(findOption(val)),
+    onCustomCommit: (q) => commit({ value: q as T, label: q }),
+    onRequestClose: () => setOpen(false),
+    search: { mode: "controlled", query: filterQuery, serverFiltered: isServer },
+    recentOptions,
+    allowCustom,
+    customOptionLabel,
+    customOptionPlacement,
   });
 
-  // Default the keyboard highlight to the first real (non-custom, enabled)
-  // option, so a free-entry "Create…" row — wherever it sits — is never the
-  // Enter target while a match exists (Enter on a partial picks the match, not
-  // a duplicate). Only when the custom row is the sole option does it lead.
-  const firstValue = list[0]?.value;
-  const defaultIndex = useMemo(() => {
-    const i = list.findIndex((o) => o.testID !== CUSTOM_VALUE && !o.disabled);
-    return i >= 0 ? i : 0;
-  }, [list]);
-  useEffect(() => {
-    setActiveIndex(defaultIndex);
-  }, [searching, list.length, firstValue, defaultIndex, setActiveIndex]);
-
   const handleChangeText = useCallback(
     (text: string) => {
       setQuery(text);
@@ -269,57 +192,34 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
   const handleKeyPress = useCallback(
     (e: { nativeEvent: { key: string }; preventDefault: () => void }) => {
       const key = e.nativeEvent.key;
-      // Backspace on an empty query removes the last chip (token-input idiom).
-      if (multi && key === "Backspace" && query.length === 0 && chips.length > 0) {
-        onRemove?.(chips[chips.length - 1]);
-        return;
-      }
       if (!open && (key === "ArrowDown" || key === "ArrowUp")) setOpen(true);
-      if (handleKey(key)) e.preventDefault();
+      if (list.handleKey(key)) e.preventDefault();
     },
-    [multi, query, chips, open, handleKey, onRemove],
+    [open, list],
   );
 
-  const showList = open && !disabled && (searching || list.length > 0);
-  const activeOptionId =
-    activeIndex >= 0 && activeIndex < list.length ? optionId(activeIndex) : undefined;
+  const showList = open && !disabled && (list.searching || list.rows.length > 0);
+  const showRecentsHeader = !list.searching && (recentOptions?.length ?? 0) > 0;
   // Select mode (no leading icon): show a trailing chevron so the field reads as
   // a picker, not a free-text search. The clear ✕ owns the right slot when
   // present, so suppress the chevron then.
-  const showChevron = !multi && !icon && !clearable;
+  const showChevron = !icon && !clearable;
 
   return (
     <View style={style}>
-      <View ref={triggerRef} style={multi ? [styles.multiBox, showList && styles.openRing] : undefined}>
-        {multi
-          ? chips.map((chip) => (
-              <View key={chip.value} style={styles.chip}>
-                <Text size="sm" numberOfLines={1}>
-                  {chip.label ?? chip.value}
-                </Text>
-                <Pressable
-                  accessibilityRole="button"
-                  accessibilityLabel={`Remove ${chip.label ?? chip.value}`}
-                  onPress={() => onRemove?.(chip)}
-                  style={styles.chipRemove}
-                >
-                  <Icon name="x" size={12} color={colors.zinc["500"]} />
-                </Pressable>
-              </View>
-            ))
-          : null}
+      <View ref={triggerRef}>
         <TextInputField
           ref={inputRef}
           testID={testID}
-          icon={multi ? undefined : icon}
+          icon={icon}
           value={query}
-          clearable={!multi && clearable}
+          clearable={clearable}
           clearLabel={clearLabel}
           onClear={onClear}
           onChangeText={handleChangeText}
           onFocus={() => {
-            // A programmatic refocus right after a single-select commit must not
-            // reopen the menu; consume the one-shot flag instead of opening.
+            // A programmatic refocus right after a commit must not reopen the
+            // menu; consume the one-shot flag instead of opening.
             if (suppressFocusOpenRef.current) {
               suppressFocusOpenRef.current = false;
               return;
@@ -332,26 +232,24 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
             suppressFocusOpenRef.current = false;
           }}
           onKeyPress={handleKeyPress}
-          placeholder={chips.length > 0 ? undefined : placeholder}
+          placeholder={placeholder}
           placeholderTextColor={colors.zinc["400"]}
           editable={!disabled}
           autoFocus={autoFocus}
           autoCapitalize="none"
           autoCorrect={false}
           style={[
-            multi ? styles.multiInput : showChevron ? styles.selectInput : undefined,
-            // Single-select wears the open ring on the input (which holds the
-            // border); multi wears it on the wrapper above (the input is borderless).
+            showChevron ? styles.selectInput : undefined,
             // Gate on `showList`, not `open`: an empty query with no options has
             // `open=true` but renders NO dropdown, so a ring tied to `open` would
             // show with nothing below it AND linger after blur (no popover fires a
             // close). The ring must mean "a dropdown is up".
-            !multi && showList ? styles.openRing : undefined,
+            showList ? styles.openRing : undefined,
           ]}
           role="combobox"
           aria-expanded={showList}
-          aria-controls={listboxId}
-          aria-activedescendant={activeOptionId}
+          aria-controls={list.listboxId}
+          aria-activedescendant={showList ? list.activeId : undefined}
           aria-autocomplete="list"
         />
         {showChevron ? (
@@ -365,7 +263,7 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
         onOpenChange={(next) => {
           setOpen(next);
           // An outside dismiss closes the menu but leaves the textbox focused, so
-          // a keyboard `:focus-visible` ring would linger. Drop focus when the
+          // the input's keyboard focus ring would linger. Drop focus when the
           // popover closes ITSELF — a commit refocuses through its own path
           // (`commit` sets `open` directly), never through `onOpenChange`.
           if (!next) inputRef.current?.blur();
@@ -378,7 +276,7 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
       >
         <PopoverContent manageFocus={false} disableBodyScroll testID={testID ? `${testID}-popover` : undefined}>
           <View style={styles.menu}>
-            {!searching && (recentOptions?.length ?? 0) > 0 ? (
+            {showRecentsHeader ? (
               <View style={styles.sectionHeader}>
                 <Text size="xs" weight="medium" color="zinc-500">
                   {recentsLabel}
@@ -386,10 +284,10 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
               </View>
             ) : null}
             <ScrollView
-              ref={scrollRef}
+              ref={list.scrollRef}
               style={styles.scroll}
-              nativeID={listboxId}
-              accessibilityLabel={searching ? accessibilityLabel : recentsLabel}
+              nativeID={list.listboxId}
+              accessibilityLabel={list.searching ? accessibilityLabel : recentsLabel}
               keyboardShouldPersistTaps="handled"
               role={"listbox" as "list"}
             >
@@ -397,8 +295,8 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
                 <View style={styles.statusRow}>
                   <ActivityIndicator />
                 </View>
-              ) : list.length === 0 ? (
-                searching ? (
+              ) : list.rows.length === 0 ? (
+                list.searching ? (
                   <View style={styles.statusRow}>
                     <Text size="sm" color="zinc-500">
                       {emptyText}
@@ -406,8 +304,9 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
                   </View>
                 ) : null
               ) : (
-                list.map((opt, i) => {
-                  const isCustom = opt.testID === CUSTOM_VALUE;
+                list.rows.map((row) => {
+                  const isCustom = row.kind === "custom";
+                  const opt = row.option;
                   const desc = !isCustom ? getOptionDescription?.(opt) : undefined;
                   const label = opt.label ?? opt.value;
                   const title =
@@ -429,18 +328,18 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
                     );
                   return (
                     <MenuButton
-                      key={opt.value}
-                      nativeID={optionId(i)}
+                      key={`${row.kind}-${opt.value}`}
+                      nativeID={row.nativeID}
                       testID={isCustom ? "combobox-custom-option" : `combobox-option-${opt.value}`}
                       role="option"
                       accessibilityLabel={label}
                       icon={isCustom ? <Icon name="plus" size={16} color={colors.zinc["600"]} /> : undefined}
                       title={title}
-                      focused={i === activeIndex}
-                      selected={!multi && !isCustom && single?.value === opt.value}
+                      focused={row.index === list.activeIndex}
+                      selected={row.selected}
                       disabled={opt.disabled}
-                      onPress={() => handleSelect(i)}
-                      onHoverIn={() => setActiveIndex(i, false)}
+                      onPress={() => list.pickRow(row.index)}
+                      onHoverIn={() => list.setActiveIndex(row.index, false)}
                     />
                   );
                 })
@@ -454,26 +353,8 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
 }
 
 const styles = StyleSheet.create({
-  multiBox: {
-    flexDirection: "row",
-    flexWrap: "wrap",
-    alignItems: "center",
-    gap: 4,
-    paddingHorizontal: 6,
-    paddingVertical: 4,
-    minHeight: 40,
-    borderWidth: 1,
-    borderColor: colors.border,
-    borderRadius: CONTROL_RADIUS,
-  },
-  multiInput: {
-    flexGrow: 1,
-    flexBasis: 80,
-    borderWidth: 0,
-    height: 28,
-  },
   openRing: {
-    boxShadow: ACTIVE_RING,
+    boxShadow: FOCUS_RING,
   },
   // Select mode: room on the right for the trailing chevron.
   selectInput: {
@@ -487,22 +368,6 @@ const styles = StyleSheet.create({
     justifyContent: "center",
     pointerEvents: "none",
   },
-
-  chip: {
-    flexDirection: "row",
-    alignItems: "center",
-    gap: 4,
-    paddingLeft: 8,
-    paddingRight: 4,
-    paddingVertical: 2,
-    borderRadius: 6,
-    backgroundColor: colors.zinc["100"],
-  },
-  chipRemove: {
-    padding: 2,
-    borderRadius: 4,
-    cursor: "pointer",
-  },
   menu: {
     gap: 2,
   },

package/src/confidence.tsx

@@ -4,13 +4,23 @@ import { Text } from "./text";
 
 export type ConfidenceLevel = "high" | "medium" | "low";
 
+export interface ConfidenceLabels {
+  /** The full level phrase — shown beside the meter and read out. Default "High confidence" etc.,
+   *  so the meter reads as what it is, not a bare "High". One phrase per level (translates cleanly). */
+  high: string;
+  medium: string;
+  low: string;
+}
+
 export interface ConfidenceProps {
   /** Pass a level directly, or a 0–1 `score` (≥0.8 high · ≥0.5 medium · else low). */
   level?: ConfidenceLevel;
   score?: number;
+  /** Translated level phrases. Defaults to English ("High confidence" …). */
+  labels?: Partial<ConfidenceLabels>;
 }
 
-const LABEL: Record<ConfidenceLevel, string> = { high: "High", medium: "Medium", low: "Low" };
+const DEFAULT_LABELS: ConfidenceLabels = { high: "High confidence", medium: "Medium confidence", low: "Low confidence" };
 const FILLED: Record<ConfidenceLevel, number> = { high: 3, medium: 2, low: 1 };
 // high emerald, medium amber, low zinc (unsure — not an error). One family per
 // level; the fill count AND the colour both carry it.
@@ -30,17 +40,18 @@ export function levelFromScore(score: number): ConfidenceLevel {
  */
 export function Confidence(props: ConfidenceProps) {
   const level = props.level ?? (props.score != null ? levelFromScore(props.score) : "medium");
+  const l = { ...DEFAULT_LABELS, ...props.labels };
   const filled = FILLED[level];
   const fill = solid(COLOR[level]);
   return (
-    <View style={styles.row} accessibilityLabel={`${LABEL[level]} confidence`}>
+    <View style={styles.row} accessibilityLabel={l[level]}>
       <View style={styles.meter}>
         {[0, 1, 2].map((i) => (
           <View key={i} style={[styles.tick, { backgroundColor: i < filled ? fill : colors.zinc[200] }]} />
         ))}
       </View>
       <Text size="xs" weight="medium" style={{ color: fill }}>
-        {LABEL[level]}
+        {l[level]}
       </Text>
     </View>
   );

package/src/control_surface.ts

@@ -16,13 +16,28 @@ export const CONTROL_HEIGHT = 40;
  *  (avatars, dots, switches, sliders, progress, icon buttons) stay full. */
 export const CONTROL_RADIUS = 10;
 
-/** The active/open edge for an interactive control — a 2px zinc-900 ring flush
- *  against the box (offset 0), MIRRORING the keyboard `:focus-visible` outline
- *  (index.css). A mouse-opened popover trigger (Picker / Combobox / InlineSelect /
- *  InlineDatePicker) never receives `:focus-visible`, so apply this on its open
- *  state to read identically to a focused input — a lone 1px border looks thin
- *  beside the kit's focus outline and selected-pill ring. */
-export const ACTIVE_RING = `0 0 0 2px ${colors.zinc[900]}`;
+/** THE focus ring — a 2px zinc-900 box-shadow flush against the box (offset 0),
+ *  layout-neutral (never reflows). The kit no longer ships a global `:focus-visible`
+ *  CSS rule, so every interactive control paints THIS inline when keyboard-focused
+ *  (via `useFocusRing`). It doubles as the active/open edge: a mouse-opened popover
+ *  trigger (Picker / Combobox / InlineSelect / InlineDatePicker) wears it on its open
+ *  state so an open trigger reads identically to a keyboard-focused one — one token,
+ *  one look. Apps building their own controls reuse it. */
+export const FOCUS_RING = `0 0 0 2px ${colors.zinc[900]}`;
+
+/** A bordered control's pointer-hover edge: the resting `border` darkens to this on
+ *  hover — the premium "this is interactive" affordance that complements the focus
+ *  ring (focus = the ring; hover = a darker border). Drive it with `useHover` on a
+ *  TextInput/select, or a Pressable's built-in `hovered` state. Pair with
+ *  `CONTROL_TRANSITION` so the change eases in. */
+export const HOVER_BORDER = colors.zinc[400];
+
+/** The ease applied to a bordered control's interactive edges (border + ring), so
+ *  hover/focus transitions read smooth, not snapped. Web-only; ignored on native. */
+export const CONTROL_TRANSITION = {
+  transitionProperty: "border-color, box-shadow",
+  transitionDuration: "0.12s",
+};
 
 /** THE review-card surface — the bordered white card every "AI proposes, you
  *  decide" surface wears (`ReviewCard`, and the whole-set `ChangeReview`), so the