@lotics/ui 1.13.1 → 1.13.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "1.13.1",
+  "version": "1.13.3",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -43,6 +43,7 @@
     "./tooltip": "./src/tooltip.tsx",
     "./button": "./src/button.tsx",
     "./checkbox": "./src/checkbox.tsx",
+    "./combobox": "./src/combobox.tsx",
     "./portal": "./src/portal.tsx",
     "./popover_nav": "./src/popover_nav.tsx",
     "./popover": "./src/popover.tsx",

package/src/combobox.tsx

@@ -0,0 +1,177 @@
+import { Pressable, StyleProp, ViewStyle, StyleSheet } from "react-native";
+import { useState, useCallback, useRef, useEffect } 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";
+
+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). */
+  onSearchChange?: (query: string) => void;
+  /** Show a loading indicator while async results are in flight. */
+  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". */
+  emptyText?: string;
+  disabled?: boolean;
+  autoFocus?: boolean;
+  testID?: string;
+  style?: StyleProp<ViewStyle>;
+}
+
+/** Debounce a possibly-undefined callback; cleared on unmount. */
+function useDebouncedCallback<A extends unknown[]>(
+  fn: ((...args: A) => void) | undefined,
+  ms: number,
+) {
+  const fnRef = useRef(fn);
+  fnRef.current = fn;
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(
+    () => () => {
+      if (timer.current) clearTimeout(timer.current);
+    },
+    [],
+  );
+  return useCallback(
+    (...args: A) => {
+      if (timer.current) clearTimeout(timer.current);
+      timer.current = setTimeout(() => fnRef.current?.(...args), ms);
+    },
+    [ms],
+  );
+}
+
+/**
+ * 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).
+ *
+ * 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.
+ */
+export function Combobox<T extends string>(props: ComboboxProps<T>) {
+  const {
+    value,
+    onValueChange,
+    options,
+    onSearchChange,
+    loading,
+    searchDebounceMs = 200,
+    placeholder,
+    searchPlaceholder,
+    emptyText,
+    disabled = false,
+    autoFocus = false,
+    testID,
+    style,
+  } = props;
+
+  const [open, setOpen] = useState(autoFocus);
+  const debouncedSearch = useDebouncedCallback(onSearchChange, searchDebounceMs);
+
+  const handleToggle = useCallback(() => {
+    if (!disabled) setOpen((o) => !o);
+  }, [disabled]);
+
+  const handleSelect = useCallback(
+    (v: T) => {
+      const opt = options.find((o) => o.value === v);
+      if (opt) onValueChange(opt);
+      setOpen(false);
+    },
+    [options, onValueChange],
+  );
+
+  return (
+    <Popover
+      open={open && !disabled}
+      onOpenChange={setOpen}
+      side="bottom"
+      align="start"
+      inheritTriggerWidth={true}
+    >
+      <PopoverTrigger>
+        <Pressable
+          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
+          onSearchChange={debouncedSearch}
+          // Local filtering is wrong when the consumer drives search server-side.
+          serverFiltered={onSearchChange !== undefined}
+          loading={loading}
+          emptyText={emptyText}
+          searchPlaceholder={searchPlaceholder}
+        />
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+const styles = StyleSheet.create({
+  trigger: {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "space-between",
+    gap: 6,
+    paddingHorizontal: 6,
+    borderWidth: 1,
+    borderColor: colors.border,
+    borderRadius: 8,
+    height: 40,
+    cursor: "pointer",
+  },
+  opened: {
+    outlineColor: colors.black,
+    outlineWidth: 2,
+    outlineStyle: "solid",
+    outlineOffset: -2,
+  },
+  disabled: {
+    opacity: 0.5,
+    cursor: "auto",
+  },
+});

package/src/picker.tsx

@@ -109,7 +109,12 @@ function StandardPicker<T extends string>(props: PickerProps<T, false>) {
         placeholder={placeholder}
         enabled={!disabled}
       >
-        {(!value || includeEmptyOption) && <RNPicker.Item label="" value="" />}
+        {(!value || includeEmptyOption) && (
+          // Show the placeholder as the empty option (the standard
+          // `<option value="" selected>Placeholder</option>` pattern) so a
+          // native select hints what to choose.
+          <RNPicker.Item label={!value ? (placeholder ?? "") : ""} value="" />
+        )}
         {options.map((option) =>
           option ? (
             <RNPicker.Item
@@ -259,6 +264,13 @@ function PickerTrigger<T extends string>({
     <Pressable
       ref={ref}
       testID={testID}
+      // Without a role this Pressable renders as an unfocusable <div> on web —
+      // the trigger drops out of the tab order and Enter/Space can't open it.
+      // `button` makes it tab-focusable and maps keyboard activation to onPress;
+      // `expanded` announces open/closed to assistive tech. The accessible name
+      // comes from the visible selection/placeholder text below.
+      accessibilityRole="button"
+      accessibilityState={{ expanded: open, disabled }}
       style={[
         styles.pressable,
         open && !enableSearch && styles.opened,

package/src/picker_menu.tsx

@@ -7,6 +7,7 @@ import { Checkbox } from "./checkbox";
 import { Spacer } from "./spacer";
 import { TextInputField } from "./text_input_field";
 import { MenuButton } from "./menu_button";
+import { ActivityIndicator } from "./activity_indicator";
 import { PickerOption, PickerValue, PickerOnValueChange, PickerOnClose } from "./picker";
 import { useScreenSize } from "./use_screen_size";
 
@@ -23,6 +24,17 @@ export interface PickerMenuProps<T extends string = string, MULTI extends boolea
   enableSearch?: boolean;
   enableSelectAll?: boolean;
   includeEmptyOption?: boolean;
+  /** Called whenever the search text changes. Provide it to drive server-side
+   *  search — the consumer refreshes `options` in response. Omit for the default
+   *  local filtering of `options`. */
+  onSearchChange?: (query: string) => void;
+  /** When true, `options` are treated as already filtered (server-side), so the
+   *  local label filter is skipped and the full result set shows. */
+  serverFiltered?: boolean;
+  /** Show a loading indicator (e.g. while async results are in flight). */
+  loading?: boolean;
+  /** Shown when there are no options and not loading. Default: "No results". */
+  emptyText?: string;
   /** Placeholder for the search input. Pass a translated string. Default: "Search..." */
   searchPlaceholder?: string;
   /** Label for the "select all" link in multi-select mode. Default: "Select all" */
@@ -50,6 +62,10 @@ export function PickerMenu<T extends string, MULTI extends boolean = false>(
     enableSelectAll,
     enableSearch,
     includeEmptyOption,
+    onSearchChange,
+    serverFiltered,
+    loading,
+    emptyText = "No results",
     searchPlaceholder = "Search...",
     selectAllLabel = "Select all",
     deselectAllLabel = "Deselect all",
@@ -78,7 +94,9 @@ export function PickerMenu<T extends string, MULTI extends boolean = false>(
 
   const filteredOptions = useMemo(() => {
     let result = options;
-    if (enableSearch && searchQuery) {
+    // Skip the local filter in server-driven mode — `options` already reflect
+    // the query for `searchQuery`.
+    if (enableSearch && searchQuery && !serverFiltered) {
       const query = searchQuery.toLowerCase();
       result = options.filter((opt) => opt && opt.label?.toLowerCase().includes(query));
     }
@@ -90,7 +108,7 @@ export function PickerMenu<T extends string, MULTI extends boolean = false>(
       result = [emptyOption, ...result];
     }
     return result;
-  }, [options, enableSearch, searchQuery, includeEmptyOption]);
+  }, [options, enableSearch, searchQuery, includeEmptyOption, serverFiltered]);
 
   const [focusedIndex, setFocusedIndex] = useState<number>(() => {
     const selectedIndex = filteredOptions.findIndex((opt) => {
@@ -105,10 +123,14 @@ export function PickerMenu<T extends string, MULTI extends boolean = false>(
     return firstValid >= 0 ? firstValid : 0;
   });
 
-  const handleSearchChange = useCallback((text: string) => {
-    setSearchQuery(text);
-    setFocusedIndex(0);
-  }, []);
+  const handleSearchChange = useCallback(
+    (text: string) => {
+      setSearchQuery(text);
+      setFocusedIndex(0);
+      onSearchChange?.(text);
+    },
+    [onSearchChange],
+  );
 
   const handleClose = useCallback(() => {
     onRequestClose?.();
@@ -256,6 +278,18 @@ export function PickerMenu<T extends string, MULTI extends boolean = false>(
         />
       )}
       <ScrollView ref={scrollViewRef} style={styles.optionsList}>
+        {loading && (
+          <View style={styles.statusRow}>
+            <ActivityIndicator />
+          </View>
+        )}
+        {!loading && filteredOptions.length === 0 && (
+          <View style={styles.statusRow}>
+            <Text color="zinc-500" size="sm">
+              {emptyText}
+            </Text>
+          </View>
+        )}
         {filteredOptions.map((item, index) => {
           if (!item) return null;
 
@@ -334,4 +368,9 @@ const styles = StyleSheet.create({
   option: {
     marginHorizontal: 0,
   },
+  statusRow: {
+    alignItems: "center",
+    justifyContent: "center",
+    paddingVertical: 16,
+  },
 });