@lotics/ui 5.9.0 → 5.10.0

package/src/use_option_list.ts

@@ -0,0 +1,354 @@
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+import type { ScrollView } from "react-native";
+import { useListKeyboardNav } from "./use_list_keyboard_nav";
+import type { PickerOption, PickerValue, PickerOnValueChange, PickerOnClose } from "./picker";
+
+const OPTION_HEIGHT = 40;
+
+/**
+ * How the option list is searched — the seam between the two keyboard-ownership
+ * models. `none`: no filtering, native-`<select>` typeahead jumps rows (the body
+ * owns a hidden capture input). `internal`: the body renders its OWN search field
+ * and filters locally. `controlled`: a consumer's external input owns the query
+ * (the Combobox pattern) — `onServerSearch` present ⇒ server-side (no local
+ * filter), absent ⇒ local filter of the passed `options`.
+ */
+export type OptionListSearch =
+  | { mode: "none" }
+  | { mode: "internal"; placeholder?: string }
+  | {
+      mode: "controlled";
+      /** The filter query, owned by the consumer's external input (Combobox). */
+      query: string;
+      /** `options` are ALREADY filtered (a server search) — skip local filtering. */
+      serverFiltered?: boolean;
+    };
+
+/** A row's nature. `option`: a real choice. `custom`: the free-entry "create" row.
+ *  `empty`: the leading "clear" row from `includeEmptyOption`. */
+export type OptionRowKind = "option" | "custom" | "empty";
+
+export interface OptionRow<T extends string, D> {
+  kind: OptionRowKind;
+  /** For `custom`, value/label carry the typed query + its create label; for
+   *  `empty`, both are "". */
+  option: PickerOption<T, D>;
+  /** Flat index into the keyboard-nav space (and `optionId`). */
+  index: number;
+  /** Already chosen — multi ⇒ a checkbox, single ⇒ a trailing check. */
+  selected: boolean;
+  /** DOM id for `aria-activedescendant` wiring. */
+  nativeID: string;
+}
+
+export interface UseOptionListParams<
+  T extends string = string,
+  MULTI extends boolean = false,
+  D = unknown,
+> {
+  options: (PickerOption<T, D> | undefined | false)[];
+  multi?: MULTI;
+  value?: PickerValue<T, MULTI> | null;
+  onValueChange?: PickerOnValueChange<T, MULTI>;
+  /** Multi: commit-on-close. Single: fired (with the picked value) after a pick. */
+  onClose?: PickerOnClose<T, MULTI>;
+  /** Dismiss the surrounding popover (Escape, Tab, a single-select pick). */
+  onRequestClose?: () => void;
+  search: OptionListSearch;
+  /** Shown when the query is empty (e.g. a Combobox's recents). */
+  recentOptions?: PickerOption<T, D>[];
+  /** Offer a "create" row when the query matches no option. */
+  allowCustom?: boolean;
+  customOptionLabel?: (query: string) => string | null;
+  customOptionPlacement?: "top" | "bottom";
+  /** Commit the typed query as a new value (the create row was picked). */
+  onCustomCommit?: (rawQuery: string) => void;
+  /** Single-select: a leading "" row that clears the value. */
+  includeEmptyOption?: boolean;
+  enableSelectAll?: boolean;
+}
+
+export interface UseOptionList<T extends string, D> {
+  rows: OptionRow<T, D>[];
+  activeIndex: number;
+  /** `rows[activeIndex].nativeID` — feed to the controlling input's `aria-activedescendant`. */
+  activeId: string | undefined;
+  /** Move the active row; pass `false` on mouse hover so it doesn't self-scroll. */
+  setActiveIndex: (index: number, scrollIntoView?: boolean) => void;
+  /** Feed from the controlling input's `onKeyPress`; returns true when handled. */
+  handleKey: (key: string) => boolean;
+  /** Activate a row (a click, or Enter) — resolves custom/empty/multi/single. */
+  pickRow: (index: number) => void;
+  query: string;
+  setQuery: (query: string) => void;
+  searching: boolean;
+  selectAll: () => void;
+  deselectAll: () => void;
+  showSelectAll: boolean;
+  showDeselectAll: boolean;
+  listboxId: string;
+  scrollRef: React.RefObject<ScrollView | null>;
+}
+
+const defaultCustomLabel = (query: string) => `Add "${query}"`;
+
+/** Fold case + diacritics for matching, so option search is forgiving: `cafe`
+ *  matches `Café`, `dieu` matches `Điều`. Still substring-based (predictable —
+ *  no subsequence/typo noise); the typed value keeps its original accents. */
+function normalizeForSearch(s: string): string {
+  return s
+    .toLowerCase()
+    .normalize("NFD")
+    .replace(/\p{Diacritic}/gu, "")
+    .replaceAll(String.fromCharCode(0x111), "d");
+}
+
+/**
+ * The headless core of the kit's option listbox — filtering, the custom/empty
+ * rows, single/multi selection + select-all, and keyboard nav + typeahead — with
+ * no rendering. `OptionList` is the visual default over it; `Combobox` consumes it
+ * directly so its own input keeps DOM focus (`aria-activedescendant`). The single
+ * source of truth for "what's in the list and what Enter does" across every kit
+ * selector.
+ */
+export function useOptionList<T extends string, MULTI extends boolean = false, D = unknown>(
+  params: UseOptionListParams<T, MULTI, D>,
+): UseOptionList<T, D> {
+  const {
+    options,
+    multi = false as MULTI,
+    value,
+    onValueChange,
+    onClose,
+    onRequestClose,
+    search,
+    recentOptions,
+    allowCustom = false,
+    customOptionLabel,
+    customOptionPlacement = "bottom",
+    onCustomCommit,
+    includeEmptyOption = false,
+    enableSelectAll = false,
+  } = params;
+
+  const baseId = useId();
+  const listboxId = `${baseId}-listbox`;
+  const optionId = useCallback((i: number) => `${baseId}-option-${i}`, [baseId]);
+  const scrollRef = useRef<ScrollView | null>(null);
+
+  // --- query (mode-dependent) ---
+  const searchMode = search.mode;
+  const serverFiltered = search.mode === "controlled" && search.serverFiltered === true;
+
+  const [internalQuery, setInternalQuery] = useState("");
+  const query =
+    search.mode === "controlled" ? search.query : search.mode === "internal" ? internalQuery : "";
+  const searching = query.trim().length > 0;
+
+  const setQuery = useCallback(
+    (next: string) => {
+      // Only the internal-search body owns its query state; `none` (typeahead
+      // capture) and `controlled` (the Combobox's external input) callers own theirs.
+      if (searchMode === "internal") setInternalQuery(next);
+    },
+    [searchMode],
+  );
+
+  // --- selection model ---
+  const { multiValue, singleValue } = useMemo(() => {
+    if (multi) {
+      return { multiValue: (Array.isArray(value) ? value : []) as T[], singleValue: undefined };
+    }
+    return {
+      multiValue: [] as T[],
+      singleValue: (Array.isArray(value) ? value[0] : value) as T | undefined | null,
+    };
+  }, [multi, value]);
+  const selectedSet = useMemo(() => new Set(multiValue), [multiValue]);
+
+  // --- filtering ---
+  const cleanOptions = useMemo(
+    () => options.filter((o): o is PickerOption<T, D> => !!o),
+    [options],
+  );
+  const filtered = useMemo(() => {
+    if (searchMode === "none" || serverFiltered) return cleanOptions;
+    if (!searching) {
+      // Empty query: a controlled (Combobox) field browses recents, else its full
+      // local set; an internal field shows everything.
+      return searchMode === "controlled" ? (recentOptions ?? cleanOptions) : cleanOptions;
+    }
+    const q = normalizeForSearch(query);
+    return cleanOptions.filter((o) => normalizeForSearch(o.label ?? o.value).includes(q));
+  }, [searchMode, serverFiltered, searching, cleanOptions, recentOptions, query]);
+
+  // --- the free-entry "create" row ---
+  const customRow = useMemo((): PickerOption<T, D> | null => {
+    if (!allowCustom || !searching) return null;
+    const q = query.trim();
+    const ql = normalizeForSearch(q);
+    const exact = cleanOptions.some(
+      (o) => normalizeForSearch(o.label ?? o.value) === ql || normalizeForSearch(String(o.value)) === ql,
+    );
+    if (exact) return null;
+    const label = customOptionLabel ? customOptionLabel(q) : defaultCustomLabel(q);
+    if (label === null) return null;
+    return { value: q as T, label };
+  }, [allowCustom, searching, query, cleanOptions, customOptionLabel]);
+
+  // --- the flat, ordered row list ---
+  const rows = useMemo<OptionRow<T, D>[]>(() => {
+    const out: OptionRow<T, D>[] = [];
+    const push = (kind: OptionRowKind, option: PickerOption<T, D>) => {
+      // The create row is never "selected"; a real option and the empty/clear row
+      // reflect the current value (the clear row shows checked when value is "").
+      const selected =
+        kind !== "custom" && (multi ? selectedSet.has(option.value) : option.value === singleValue);
+      out.push({ kind, option, index: out.length, selected, nativeID: optionId(out.length) });
+    };
+    if (includeEmptyOption && !multi && !searching) push("empty", { value: "" as T, label: "" });
+    if (customRow && customOptionPlacement === "top") push("custom", customRow);
+    for (const o of filtered) push("option", o);
+    if (customRow && customOptionPlacement === "bottom") push("custom", customRow);
+    return out;
+  }, [
+    filtered,
+    customRow,
+    customOptionPlacement,
+    includeEmptyOption,
+    multi,
+    searching,
+    selectedSet,
+    singleValue,
+    optionId,
+  ]);
+
+  // The first selectable real option (selection-INDEPENDENT — its value only moves
+  // when the filtered set does, never on a toggle).
+  const firstRealIndex = useMemo(() => {
+    const real = rows.findIndex((r) => r.kind === "option" && !r.option.disabled);
+    if (real >= 0) return real;
+    const any = rows.findIndex((r) => !r.option.disabled);
+    return any >= 0 ? any : 0;
+  }, [rows]);
+
+  // The row to highlight on OPEN: the selected option when browsing (none mode, so
+  // an open Select lands on the current value), else the first real option. Read
+  // once via the nav hook's `initialIndex`.
+  const initialActiveIndex = useMemo(() => {
+    if (searchMode === "none") {
+      const sel = rows.findIndex((r) => r.selected && !r.option.disabled);
+      if (sel >= 0) return sel;
+    }
+    return firstRealIndex;
+  }, [searchMode, rows, firstRealIndex]);
+
+  const scrollToIndex = useCallback((index: number) => {
+    if (index >= 0) scrollRef.current?.scrollTo({ y: index * OPTION_HEIGHT - 80, animated: false });
+  }, []);
+
+  const requestClose = useCallback(() => {
+    onRequestClose?.();
+    if (onClose) {
+      if (multi) (onClose as (v: T[]) => void)(multiValue);
+      else (onClose as (v: T) => void)((singleValue ?? "") as T);
+    }
+  }, [onRequestClose, onClose, multi, multiValue, singleValue]);
+
+  const pickRow = useCallback(
+    (i: number) => {
+      const row = rows[i];
+      if (!row || row.option.disabled) return;
+      if (row.kind === "custom") {
+        onCustomCommit?.(query.trim());
+        // Reset an internal search after creating, so the field is ready for the
+        // next add (a controlled/Combobox caller manages its own input instead).
+        if (searchMode === "internal") setInternalQuery("");
+        return;
+      }
+      if (row.kind === "empty") {
+        if (!multi) (onValueChange as ((v: T) => void) | undefined)?.("" as T);
+        requestClose();
+        return;
+      }
+      if (multi) {
+        if (!onValueChange) return;
+        const next = selectedSet.has(row.option.value)
+          ? multiValue.filter((v) => v !== row.option.value)
+          : [...multiValue, row.option.value];
+        (onValueChange as (v: T[]) => void)(next);
+        // Multi stays open so more rows can be toggled.
+      } else {
+        (onValueChange as ((v: T) => void) | undefined)?.(row.option.value);
+        requestClose();
+      }
+    },
+    [rows, multi, onValueChange, onCustomCommit, query, multiValue, selectedSet, requestClose, searchMode],
+  );
+
+  const { activeIndex, setActiveIndex, handleKey } = useListKeyboardNav({
+    count: rows.length,
+    isDisabled: (i) => rows[i]?.option.disabled ?? false,
+    onSelect: pickRow,
+    onClose: requestClose,
+    onActiveChange: scrollToIndex,
+    initialIndex: initialActiveIndex,
+    // Typeahead only when the body owns a hidden capture input — in search modes a
+    // printable key is a query character, so it must flow to the input instead.
+    typeahead:
+      searchMode === "none"
+        ? { labelAt: (i) => rows[i]?.option.label ?? rows[i]?.option.value }
+        : undefined,
+  });
+
+  // After the initial seat, re-home the active row to the first real option ONLY
+  // when the FILTER changes (a new search) — so Enter on a partial query picks a
+  // match, never the create row. Keyed on the filtered set, NOT on selection: a
+  // multi toggle keeps the popover open and must leave the active row where it is.
+  const filterKey = useMemo(
+    () => filtered.map((o) => o.value).join("") + "
" + (customRow?.value ?? ""),
+    [filtered, customRow],
+  );
+  const seatedRef = useRef(false);
+  useEffect(() => {
+    if (!seatedRef.current) {
+      seatedRef.current = true; // mount already seated via initialIndex
+      return;
+    }
+    if (searchMode !== "none") setActiveIndex(firstRealIndex);
+  }, [filterKey, firstRealIndex, searchMode, setActiveIndex]);
+
+  const selectAll = useCallback(() => {
+    if (!multi || !onValueChange) return;
+    (onValueChange as (v: T[]) => void)(
+      cleanOptions.filter((o) => !o.disabled).map((o) => o.value),
+    );
+  }, [multi, onValueChange, cleanOptions]);
+  const deselectAll = useCallback(() => {
+    if (!multi || !onValueChange) return;
+    (onValueChange as (v: T[]) => void)([]);
+  }, [multi, onValueChange]);
+
+  const hasOptions = rows.some((r) => r.kind === "option" && !r.option.disabled);
+  const hasSelection = multi ? multiValue.length > 0 : singleValue != null && singleValue !== "";
+  const showSelectAll = !!multi && enableSelectAll && hasOptions;
+  const showDeselectAll = showSelectAll && hasSelection;
+
+  return {
+    rows,
+    activeIndex,
+    activeId: rows[activeIndex]?.nativeID,
+    setActiveIndex,
+    handleKey,
+    pickRow,
+    query,
+    setQuery,
+    searching,
+    selectAll,
+    deselectAll,
+    showSelectAll,
+    showDeselectAll,
+    listboxId,
+    scrollRef,
+  };
+}

package/src/command_menu.tsx

@@ -1,205 +0,0 @@
-import { StyleSheet, View, ScrollView } from "react-native";
-import { useState, useCallback, useMemo, useRef, useId } from "react";
-import { colors } from "./colors";
-import { TextInputField } from "./text_input_field";
-import { MenuButton } from "./menu_button";
-import { Text } from "./text";
-import { useScreenSize } from "./use_screen_size";
-
-export interface CommandOption {
-  value: string;
-  label: string;
-  disabled?: boolean;
-}
-
-interface CommandMenuProps {
-  options: CommandOption[];
-  onSelect: (value: string) => void;
-  onRequestClose?: () => void;
-  enableSearch?: boolean;
-  /** Search input placeholder. Default: "Search...". Pass a translated string from the consumer. */
-  searchPlaceholder?: string;
-  /** Accessible name for the list. Default: "Options". Pass a translated string from the consumer. */
-  accessibilityLabel?: string;
-}
-
-export function CommandMenu(props: CommandMenuProps) {
-  const {
-    options,
-    onSelect,
-    onRequestClose,
-    enableSearch,
-    searchPlaceholder = "Search...",
-    accessibilityLabel,
-  } = props;
-  const scrollViewRef = useRef<ScrollView>(null);
-  const screenSize = useScreenSize();
-  const OPTION_HEIGHT = 40;
-
-  const baseId = useId();
-  const listboxId = `${baseId}-listbox`;
-  const optionId = (index: number) => `${baseId}-option-${index}`;
-
-  const [searchQuery, setSearchQuery] = useState("");
-
-  const filteredOptions = useMemo(() => {
-    if (!enableSearch || !searchQuery) return options;
-    const query = searchQuery.toLowerCase();
-    return options.filter((opt) => opt.label.toLowerCase().includes(query));
-  }, [options, enableSearch, searchQuery]);
-
-  const [focusedIndex, setFocusedIndex] = useState(0);
-
-  const handleSearchChange = useCallback((text: string) => {
-    setSearchQuery(text);
-    setFocusedIndex(0);
-  }, []);
-
-  const handleSelect = useCallback(
-    (value: string) => {
-      onSelect(value);
-    },
-    [onSelect],
-  );
-
-  const scrollToIndex = useCallback((index: number) => {
-    if (scrollViewRef.current && index >= 0) {
-      scrollViewRef.current.scrollTo({ y: index * OPTION_HEIGHT - 80, animated: false });
-    }
-  }, []);
-
-  const handleKeyNavigation = useCallback(
-    (key: string): boolean => {
-      switch (key) {
-        case "ArrowDown": {
-          let next = focusedIndex + 1;
-          while (next < filteredOptions.length) {
-            if (!filteredOptions[next].disabled) {
-              setFocusedIndex(next);
-              scrollToIndex(next);
-              break;
-            }
-            next++;
-          }
-          return true;
-        }
-        case "ArrowUp": {
-          let next = focusedIndex - 1;
-          while (next >= 0) {
-            if (!filteredOptions[next].disabled) {
-              setFocusedIndex(next);
-              scrollToIndex(next);
-              break;
-            }
-            next--;
-          }
-          return true;
-        }
-        case "Home":
-          setFocusedIndex(0);
-          scrollToIndex(0);
-          return true;
-        case "End": {
-          const last = filteredOptions.length - 1;
-          setFocusedIndex(last);
-          scrollToIndex(last);
-          return true;
-        }
-        case "Enter":
-          if (focusedIndex >= 0 && focusedIndex < filteredOptions.length) {
-            const opt = filteredOptions[focusedIndex];
-            if (opt && !opt.disabled) handleSelect(opt.value);
-          }
-          return true;
-        case "Escape":
-          onRequestClose?.();
-          return true;
-        case "Tab":
-          onRequestClose?.();
-          return false;
-        default:
-          return false;
-      }
-    },
-    [focusedIndex, filteredOptions, handleSelect, onRequestClose, scrollToIndex],
-  );
-
-  const handleSearchKeyPress = useCallback(
-    (e: { nativeEvent: { key: string }; preventDefault: () => void }) => {
-      if (handleKeyNavigation(e.nativeEvent.key)) {
-        e.preventDefault();
-      }
-    },
-    [handleKeyNavigation],
-  );
-
-  const listLabel = accessibilityLabel ?? "Options";
-  const activeOptionId =
-    focusedIndex >= 0 && focusedIndex < filteredOptions.length ? optionId(focusedIndex) : undefined;
-
-  return (
-    <View style={[styles.container, screenSize.small ? { flex: 1 } : { maxHeight: 480 }]}>
-      {enableSearch && (
-        <TextInputField
-          autoFocus={!screenSize.small}
-          icon="search"
-          value={searchQuery}
-          onChangeText={handleSearchChange}
-          placeholder={searchPlaceholder}
-          placeholderTextColor={colors.zinc["400"]}
-          autoCapitalize="none"
-          autoCorrect={false}
-          onKeyPress={handleSearchKeyPress}
-          accessibilityLabel={listLabel}
-          role="combobox"
-          aria-expanded
-          aria-controls={listboxId}
-          aria-activedescendant={activeOptionId}
-          aria-autocomplete="list"
-        />
-      )}
-      <ScrollView
-        ref={scrollViewRef}
-        style={styles.optionsList}
-        nativeID={listboxId}
-        accessibilityLabel={listLabel}
-        // Boundary adapter: `listbox` is a valid ARIA role but missing from
-        // React Native's `Role` enum, so TypeScript cannot accept the literal
-        // here. `react-native-web` forwards the attribute verbatim, which is
-        // what assistive technology reads on web.
-        role={"listbox" as "list"}
-      >
-        {filteredOptions.map((item, index) => (
-          <MenuButton
-            key={item.value}
-            nativeID={optionId(index)}
-            testID={`command-option-${item.value}`}
-            title={
-              <Text userSelect="none" numberOfLines={1}>
-                {item.label}
-              </Text>
-            }
-            accessibilityLabel={item.label}
-            role="option"
-            right={undefined}
-            focused={index === focusedIndex}
-            selected={index === focusedIndex}
-            disabled={item.disabled}
-            onPress={() => handleSelect(item.value)}
-            onHoverIn={() => setFocusedIndex(index)}
-          />
-        ))}
-      </ScrollView>
-    </View>
-  );
-}
-
-const styles = StyleSheet.create({
-  container: {
-    gap: 4,
-  },
-  optionsList: {
-    flex: 1,
-    gap: 4,
-  },
-});