@lotics/ui 1.26.0 → 2.0.0

package/src/combobox.tsx

@@ -1,164 +1,420 @@
-import { Pressable, StyleProp, ViewStyle, StyleSheet } from "react-native";
-import { useState, useCallback } from "react";
+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 { colors } from "./colors";
 import { Text } from "./text";
 import { Icon } from "./icon";
-import { Popover, PopoverTrigger, PopoverContent } from "./popover";
-import { PickerMenu } from "./picker_menu";
-import { PickerOption } from "./picker";
+import { TextInputField } from "./text_input_field";
+import { MenuButton } from "./menu_button";
+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";
 
-export interface ComboboxProps<T extends string = string> {
-  /** The selected option. It carries its own label, so the trigger still shows
-   *  the selection even when that option is no longer in the current (async)
-   *  result set. */
-  value: PickerOption<T> | null;
-  onValueChange: (option: PickerOption<T>) => void;
-  /** Result options to show in the list. In server-search mode the consumer
-   *  refreshes these in response to `onSearchChange`. */
-  options: PickerOption<T>[];
-  /** Called (debounced) when the search text changes. Provide it to drive
-   *  server-side search — the consumer re-queries and updates `options`. Omit to
-   *  filter the given `options` locally (static list). */
+export interface ComboboxProps<T extends string = string, D = unknown> {
+  /** Result options for the current query. With `onSearchChange` the consumer
+   *  refreshes these server-side; without it, they're filtered locally by label. */
+  options: PickerOption<T, D>[];
+  /** Fires when the user picks an option (or a custom value, if `allowCustom`). */
+  onValueChange: (option: PickerOption<T, D>) => void;
+  /** Server-side search: debounced, fires as the user types. Omit for local
+   *  label filtering of `options`. */
   onSearchChange?: (query: string) => void;
-  /** Show a loading indicator while async results are in flight. */
+  /** 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). */
+  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. */
+  renderOptionContent?: (option: PickerOption<T, D>) => ReactNode;
+  /** Row subtitle pulled from the option (single-line, under the title). */
+  getOptionDescription?: (option: PickerOption<T, D>) => string | undefined;
+  /** Accept free text: when the query matches no option, offer it as a custom
+   *  value — `onValueChange` receives `{ value: query, label: query }`. */
+  allowCustom?: boolean;
+  /** Label for the free-entry row (default: `Add "<query>"`). Return null to
+   *  suppress it for a given query. */
+  customOptionLabel?: (query: string) => string | null;
+  /** Shown — under a heading — when the input is focused but empty. */
+  recentOptions?: PickerOption<T, D>[];
   loading?: boolean;
-  /** Debounce applied to `onSearchChange`, in ms. Default 200. */
   searchDebounceMs?: number;
   placeholder?: string;
-  searchPlaceholder?: string;
-  /** Shown when there are no results and not loading. Default: "No results". */
+  recentsLabel?: string;
   emptyText?: string;
-  /** Accept free entry: when the typed query matches no option, offer it as a
-   *  custom value. `onValueChange` then receives `{ value: query, label: query }`.
-   *  The consumer decides what an unknown value means (e.g. a manually-typed id). */
-  allowCustom?: boolean;
-  /** Label for the free-entry row (default: the raw query). Return `null` to
-   *  suppress it for a given query (e.g. still incomplete/invalid). */
-  customOptionLabel?: (query: string) => string | null;
+  accessibilityLabel?: string;
   disabled?: boolean;
   autoFocus?: boolean;
   testID?: string;
   style?: StyleProp<ViewStyle>;
 }
 
+const OPTION_HEIGHT = 52;
+const CUSTOM_VALUE = "__combobox_custom__";
+
 /**
- * Async-search select — a keyboard-accessible combobox. The trigger opens a
- * Popover with a search box and a result list (arrows to move, Enter to pick,
- * Esc to close; the trigger is tab-focusable and opens on Enter/Space).
+ * 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.
  *
- * Pass `onSearchChange` to drive search **server-side** (the consumer re-queries
- * and refreshes `options`) — the right pattern for large/growing datasets where
- * prefetching the whole table to the client is wrong. Omit it to filter the
- * given `options` locally, so the same component also serves static lists.
+ * For a "select from a known list" control (no search box, typeahead), use `Picker`.
  */
-export function Combobox<T extends string>(props: ComboboxProps<T>) {
+export function Combobox<T extends string = string, D = unknown>(props: ComboboxProps<T, D>) {
   const {
-    value,
-    onValueChange,
     options,
+    onValueChange,
     onSearchChange,
-    loading,
+    multi = false,
+    value,
+    onRemove,
+    reflectSelection = true,
+    renderOptionContent,
+    getOptionDescription,
+    allowCustom = false,
+    customOptionLabel,
+    recentOptions,
+    loading = false,
     searchDebounceMs = 200,
     placeholder,
-    searchPlaceholder,
-    emptyText,
-    allowCustom,
-    customOptionLabel,
+    recentsLabel = "Recent",
+    emptyText = "No results",
+    accessibilityLabel = "Results",
     disabled = false,
     autoFocus = false,
     testID,
     style,
   } = props;
 
+  const chips = multi && Array.isArray(value) ? value : [];
+  const single = !multi && value && !Array.isArray(value) ? value : null;
+
+  const [query, setQuery] = useState(
+    !multi && reflectSelection && single ? (single.label ?? single.value) : "",
+  );
   const [open, setOpen] = useState(autoFocus);
-  const debouncedSearch = useDebouncedCallback(onSearchChange, searchDebounceMs);
+  const triggerRef = useRef<View>(null);
+  const inputRef = useRef<RNTextInput>(null);
+  const scrollRef = useRef<ScrollView>(null);
+  const baseId = useId();
+  const listboxId = `${baseId}-listbox`;
+  const optionId = (i: number) => `${baseId}-option-${i}`;
 
-  const handleToggle = useCallback(() => {
-    if (!disabled) setOpen((o) => !o);
-  }, [disabled]);
+  const searching = query.trim().length > 0;
+  const isServer = onSearchChange !== undefined;
 
-  const handleSelect = useCallback(
-    (v: T) => {
-      const opt = options.find((o) => o.value === v);
-      if (opt) onValueChange(opt);
-      else if (allowCustom && v) onValueChange({ value: v, label: v });
+  // 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 label exactly.
+  const customRow = useMemo((): PickerOption<T, D> | null => {
+    if (!allowCustom || !searching) return null;
+    const q = query.trim();
+    const exact = options.some((o) => (o.label ?? o.value).toLowerCase() === q.toLowerCase());
+    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 ?? []);
+    return customRow ? [...base, customRow] : base;
+  }, [searching, filtered, recentOptions, customRow]);
+
+  const debouncedSearch = useDebouncedCallback(onSearchChange ?? (() => {}), searchDebounceMs);
+
+  const scrollToIndex = useCallback((index: number) => {
+    scrollRef.current?.scrollTo({ y: Math.max(0, index * OPTION_HEIGHT - 80), animated: false });
+  }, []);
+
+  const commit = useCallback(
+    (opt: PickerOption<T, D>) => {
+      onValueChange(opt);
+      if (isServer) {
+        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("");
+      }
       setOpen(false);
+      inputRef.current?.focus();
     },
-    [options, onValueChange, allowCustom],
+    [onValueChange, isServer, debouncedSearch, onSearchChange, multi, 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 firstValue = list[0]?.value;
+  useEffect(() => {
+    setActiveIndex(0);
+  }, [searching, list.length, firstValue, setActiveIndex]);
+
+  const handleChangeText = useCallback(
+    (text: string) => {
+      setQuery(text);
+      if (!disabled) setOpen(true);
+      if (isServer) debouncedSearch(text);
+    },
+    [disabled, isServer, debouncedSearch],
+  );
+
+  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();
+    },
+    [multi, query, chips, open, handleKey, onRemove],
+  );
+
+  const showList = open && !disabled && (searching || list.length > 0);
+  const activeOptionId =
+    activeIndex >= 0 && activeIndex < list.length ? optionId(activeIndex) : undefined;
+
   return (
-    <Popover
-      open={open && !disabled}
-      onOpenChange={setOpen}
-      side="bottom"
-      align="start"
-      inheritTriggerWidth={true}
-    >
-      <PopoverTrigger>
-        <Pressable
+    <View style={style}>
+      <View ref={triggerRef} style={multi ? styles.multiBox : 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}
+        <TextInputField
+          ref={inputRef}
           testID={testID}
-          // A bare Pressable renders as an unfocusable <div> on web; `button`
-          // puts it in the tab order and maps Enter/Space to onPress, while
-          // `expanded` announces open/closed.
-          accessibilityRole="button"
-          accessibilityState={{ expanded: open, disabled }}
-          style={[styles.trigger, open && styles.opened, disabled && styles.disabled, style]}
-          onPress={!disabled ? handleToggle : undefined}
-          disabled={disabled}
-        >
-          {value ? (
-            <Text userSelect="none" numberOfLines={1}>
-              {value.label ?? value.value}
-            </Text>
-          ) : (
-            <Text color="zinc-500" userSelect="none" numberOfLines={1}>
-              {placeholder}
-            </Text>
-          )}
-          <Icon name="chevron-down" size={18} color={colors.zinc["500"]} />
-        </Pressable>
-      </PopoverTrigger>
-      <PopoverContent>
-        <PickerMenu
-          options={options}
-          value={value?.value ?? null}
-          onValueChange={handleSelect}
-          onRequestClose={() => setOpen(false)}
-          enableSearch
-          allowCustom={allowCustom}
-          customOptionLabel={customOptionLabel}
-          onSearchChange={debouncedSearch}
-          // Local filtering is wrong when the consumer drives search server-side.
-          serverFiltered={onSearchChange !== undefined}
-          loading={loading}
-          emptyText={emptyText}
-          searchPlaceholder={searchPlaceholder}
+          icon={multi ? undefined : "search"}
+          value={query}
+          onChangeText={handleChangeText}
+          onFocus={() => {
+            if (!disabled) setOpen(true);
+          }}
+          onKeyPress={handleKeyPress}
+          placeholder={chips.length > 0 ? undefined : placeholder}
+          placeholderTextColor={colors.zinc["400"]}
+          editable={!disabled}
+          autoFocus={autoFocus}
+          autoCapitalize="none"
+          autoCorrect={false}
+          style={multi ? styles.multiInput : undefined}
+          role="combobox"
+          aria-expanded={showList}
+          aria-controls={listboxId}
+          aria-activedescendant={activeOptionId}
+          aria-autocomplete="list"
         />
-      </PopoverContent>
-    </Popover>
+      </View>
+      <Popover
+        open={showList}
+        onOpenChange={setOpen}
+        triggerRef={triggerRef}
+        side="bottom"
+        align="start"
+        offset={4}
+        inheritTriggerWidth
+      >
+        <PopoverContent manageFocus={false} disableBodyScroll testID={testID ? `${testID}-popover` : undefined}>
+          <View style={styles.menu}>
+            {!searching && (recentOptions?.length ?? 0) > 0 ? (
+              <View style={styles.sectionHeader}>
+                <Text size="xs" weight="medium" color="zinc-500">
+                  {recentsLabel}
+                </Text>
+              </View>
+            ) : null}
+            <ScrollView
+              ref={scrollRef}
+              style={styles.scroll}
+              nativeID={listboxId}
+              accessibilityLabel={searching ? accessibilityLabel : recentsLabel}
+              keyboardShouldPersistTaps="handled"
+              role={"listbox" as "list"}
+            >
+              {loading ? (
+                <View style={styles.statusRow}>
+                  <ActivityIndicator />
+                </View>
+              ) : list.length === 0 ? (
+                searching ? (
+                  <View style={styles.statusRow}>
+                    <Text size="sm" color="zinc-500">
+                      {emptyText}
+                    </Text>
+                  </View>
+                ) : null
+              ) : (
+                list.map((opt, i) => {
+                  const isCustom = opt.testID === CUSTOM_VALUE;
+                  const desc = !isCustom ? getOptionDescription?.(opt) : undefined;
+                  const label = opt.label ?? opt.value;
+                  const title =
+                    !isCustom && renderOptionContent ? (
+                      renderOptionContent(opt)
+                    ) : desc ? (
+                      <View>
+                        <Text userSelect="none" numberOfLines={1}>
+                          {label}
+                        </Text>
+                        <Text size="xs" color="zinc-500" numberOfLines={1}>
+                          {desc}
+                        </Text>
+                      </View>
+                    ) : (
+                      <Text userSelect="none" numberOfLines={1} color={isCustom ? "zinc-500" : undefined}>
+                        {label}
+                      </Text>
+                    );
+                  return (
+                    <MenuButton
+                      key={opt.value}
+                      nativeID={optionId(i)}
+                      testID={isCustom ? "combobox-custom-option" : `combobox-option-${opt.value}`}
+                      role="option"
+                      accessibilityLabel={label}
+                      icon={isCustom ? <Icon name="plus" size={16} color={colors.zinc["400"]} /> : undefined}
+                      title={title}
+                      focused={i === activeIndex}
+                      selected={!multi && !isCustom && single?.value === opt.value}
+                      disabled={opt.disabled}
+                      onPress={() => handleSelect(i)}
+                      onHoverIn={() => setActiveIndex(i)}
+                    />
+                  );
+                })
+              )}
+            </ScrollView>
+          </View>
+        </PopoverContent>
+      </Popover>
+    </View>
   );
 }
 
 const styles = StyleSheet.create({
-  trigger: {
+  multiBox: {
     flexDirection: "row",
+    flexWrap: "wrap",
     alignItems: "center",
-    justifyContent: "space-between",
-    gap: 6,
+    gap: 4,
     paddingHorizontal: 6,
+    paddingVertical: 4,
+    minHeight: 40,
     borderWidth: 1,
     borderColor: colors.border,
     borderRadius: 8,
-    height: 40,
+  },
+  multiInput: {
+    flexGrow: 1,
+    flexBasis: 80,
+    borderWidth: 0,
+    height: 28,
+  },
+  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",
   },
-  opened: {
-    borderColor: colors.zinc["900"],
+  menu: {
+    gap: 2,
+  },
+  sectionHeader: {
+    paddingHorizontal: 8,
+    paddingTop: 4,
+    paddingBottom: 2,
   },
-  disabled: {
-    opacity: 0.5,
-    cursor: "auto",
+  scroll: {
+    maxHeight: 320,
+  },
+  statusRow: {
+    alignItems: "center",
+    justifyContent: "center",
+    paddingVertical: 16,
   },
 });

package/src/dynamic_icon.tsx

@@ -0,0 +1,20 @@
+import { Icon, type IconName } from "./icon";
+
+interface DynamicIconProps {
+  /** Any Lucide icon name (kebab-case). */
+  name: string;
+  size?: number;
+  color?: string;
+  testID?: string;
+}
+
+/**
+ * Native variant of `DynamicIcon`. There's no lazy lucide loader on native, so
+ * names resolve against the curated `Icon` set (which falls back to a neutral
+ * glyph for names outside it). The web variant (`dynamic_icon.web.tsx`) renders
+ * the full Lucide library. The runtime name is a boundary value — `Icon` handles
+ * an unknown name gracefully.
+ */
+export function DynamicIcon({ name, size, color, testID }: DynamicIconProps) {
+  return <Icon name={name as IconName} size={size} color={color} testID={testID} />;
+}

package/src/dynamic_icon.web.tsx

@@ -0,0 +1,40 @@
+import { View } from "react-native";
+import { DynamicIcon as LucideDynamicIcon } from "lucide-react/dynamic";
+import { colors } from "./colors";
+
+type LucideIconName = React.ComponentProps<typeof LucideDynamicIcon>["name"];
+
+interface DynamicIconProps {
+  /** Any Lucide icon name (kebab-case). Unknown names render a blank placeholder. */
+  name: string;
+  size?: number;
+  color?: string;
+  testID?: string;
+}
+
+/**
+ * Renders any icon from the FULL Lucide library by runtime name. Web variant:
+ * lucide-react's lazy `DynamicIcon` code-splits per icon, so only icons actually
+ * shown are fetched — the full set costs ~nothing in the initial bundle. The
+ * native variant (`dynamic_icon.tsx`) resolves against the curated `Icon` set.
+ *
+ * Icons are decorative — the enclosing control carries the accessible name
+ * (matches `Icon`).
+ */
+export function DynamicIcon({ name, size = 24, color = colors.zinc["900"], testID }: DynamicIconProps) {
+  return (
+    <View
+      testID={testID}
+      accessibilityElementsHidden
+      importantForAccessibility="no-hide-descendants"
+      aria-hidden
+    >
+      <LucideDynamicIcon
+        name={name as LucideIconName}
+        size={size}
+        color={color}
+        fallback={() => <View style={{ width: size, height: size }} />}
+      />
+    </View>
+  );
+}

package/src/legend_item.tsx

@@ -14,8 +14,8 @@ interface LegendItemProps {
 
 /**
  * Color swatch + label + optional count. Used as the legend row below a
- * `StackedProgressBar`, a `ChartBar` with categorical colors, or any
- * other chart where consumers need to map color → meaning.
+ * `StackedProgressBar`, a `BarChart`/`PieChart` with per-series colors, or
+ * any other chart where consumers need to map color → meaning.
  *
  * Tabular nums on the value (via Metric) keep counts aligned when several
  * legend items sit in a row.