@lotics/ui 1.13.4 → 1.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "1.13.4",
+  "version": "1.14.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -44,6 +44,7 @@
     "./button": "./src/button.tsx",
     "./checkbox": "./src/checkbox.tsx",
     "./combobox": "./src/combobox.tsx",
+    "./search_select": "./src/search_select.tsx",
     "./portal": "./src/portal.tsx",
     "./popover_nav": "./src/popover_nav.tsx",
     "./popover": "./src/popover.tsx",

package/src/combobox.tsx

@@ -1,11 +1,12 @@
 import { Pressable, StyleProp, ViewStyle, StyleSheet } from "react-native";
-import { useState, useCallback, useRef, useEffect } from "react";
+import { useState, useCallback } 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 { useDebouncedCallback } from "./use_debounced_callback";
 
 export interface ComboboxProps<T extends string = string> {
   /** The selected option. It carries its own label, so the trigger still shows
@@ -34,29 +35,6 @@ export interface ComboboxProps<T extends string = 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,

package/src/kanban/kanban_board.tsx

@@ -53,6 +53,15 @@ export interface KanbanBoardProps<T> {
   itemGap?: number;
   /** When true, cards can only be dropped into columns (highlights entire column), not between specific cards */
   columnOnlyCardDrop?: boolean;
+  /**
+   * Whether cards can be dragged. Defaults to whether `onCardMove` is provided —
+   * a card with no move handler does not initiate a drag (it can still be
+   * pressed via `onCardPress`). Pass `false` for a read-only / action-driven
+   * board.
+   */
+  cardDraggable?: boolean;
+  /** Whether columns can be reordered. Defaults to whether `onColumnMove` is provided. */
+  columnDraggable?: boolean;
 }
 
 /** Column registration data */
@@ -80,7 +89,15 @@ export function KanbanBoard<T>({
   itemHeight,
   itemGap = DEFAULT_ITEM_GAP,
   columnOnlyCardDrop = false,
+  cardDraggable,
+  columnDraggable,
 }: KanbanBoardProps<T>) {
+  // A card/column is draggable only when there is a handler to receive the
+  // move — an explicit prop overrides. This makes a read-only or action-driven
+  // board (no move handler) non-draggable without extra wiring.
+  const cardsDraggable = cardDraggable ?? onCardMove != null;
+  const columnsDraggable = columnDraggable ?? onColumnMove != null;
+
   // Helper to get height for an item
   const getHeight = useCallback(
     (item: T, index: number): number => {
@@ -571,6 +588,8 @@ export function KanbanBoard<T>({
               onCardPress={onCardPress}
               onAddCard={onAddCard}
               onAddCardAtIndex={onAddCardAtIndex}
+              cardDraggable={cardsDraggable}
+              columnDraggable={columnsDraggable}
               startCardDrag={startCardDrag}
               startColumnDrag={startColumnDrag}
               registerColumn={registerColumn}

package/src/kanban/kanban_card.tsx

@@ -15,6 +15,8 @@ interface KanbanCardProps<T> {
   isDropTarget: boolean;
   /** True when any card is being dragged (disables insert zones) */
   isDragInProgress: boolean;
+  /** When false, this card does not initiate a drag (press still works) */
+  cardDraggable: boolean;
   onCardPress?: (cardId: string, item: T, columnKey: string) => void;
   onAddCardAtIndex?: (columnKey: string, index: number) => void;
   renderInsertCardButton?: (props: KanbanRenderInsertCardButtonProps) => React.ReactNode;
@@ -45,6 +47,7 @@ function KanbanCardInner<T>({
   isDragging,
   isDropTarget,
   isDragInProgress,
+  cardDraggable,
   onCardPress,
   onAddCardAtIndex,
   renderInsertCardButton,
@@ -106,37 +109,43 @@ function KanbanCardInner<T>({
   }, []);
 
   // Handle pointer down - attached via useEffect on web
-  const handlePointerDown = useCallback((e: PointerEvent) => {
-    // Determine pointer type
-    const pointerType = e.pointerType as PointerType;
-    pointerTypeRef.current = pointerType;
+  const handlePointerDown = useCallback(
+    (e: PointerEvent) => {
+      // Determine pointer type
+      const pointerType = e.pointerType as PointerType;
+      pointerTypeRef.current = pointerType;
 
-    pressStartRef.current = { x: e.clientX, y: e.clientY };
-    hasDraggedRef.current = false;
-    wasCancelledRef.current = false;
-
-    // For touch/pen: require a delay before drag can start
-    // For mouse: drag can start immediately
-    const isTouch = pointerType === "touch" || pointerType === "pen";
-
-    if (isTouch) {
-      canDragRef.current = false;
-      setIsDragPending(true);
+      pressStartRef.current = { x: e.clientX, y: e.clientY };
+      hasDraggedRef.current = false;
+      wasCancelledRef.current = false;
 
-      delayTimerRef.current = setTimeout(() => {
+      // For touch/pen: require a delay before drag can start
+      // For mouse: drag can start immediately
+      const isTouch = pointerType === "touch" || pointerType === "pen";
+
+      if (!cardDraggable) {
+        // Card cannot be dragged — only a press is detected. Never enable drag.
+        canDragRef.current = false;
+      } else if (isTouch) {
+        canDragRef.current = false;
+        setIsDragPending(true);
+
+        delayTimerRef.current = setTimeout(() => {
+          canDragRef.current = true;
+          delayTimerRef.current = null;
+        }, TOUCH_DRAG_DELAY);
+      } else {
         canDragRef.current = true;
-        delayTimerRef.current = null;
-      }, TOUCH_DRAG_DELAY);
-    } else {
-      canDragRef.current = true;
-    }
+      }
 
-    // Measure element position
-    containerRef.current?.measureInWindow((x, y, width, height) => {
-      elementRectRef.current = { x, y, width, height };
-      setIsPressing(true);
-    });
-  }, []);
+      // Measure element position
+      containerRef.current?.measureInWindow((x, y, width, height) => {
+        elementRectRef.current = { x, y, width, height };
+        setIsPressing(true);
+      });
+    },
+    [cardDraggable],
+  );
 
   // Attach pointer down listener to DOM element on web
   // Must depend on isDragging because when isDragging=true, the element returns null

package/src/kanban/kanban_column.tsx

@@ -68,6 +68,10 @@ interface KanbanColumnProps<T> {
   onCardPress?: (cardId: string, item: T, columnKey: string) => void;
   onAddCard?: (columnKey: string) => void;
   onAddCardAtIndex?: (columnKey: string, index: number) => void;
+  /** Whether cards in this column can be dragged */
+  cardDraggable: boolean;
+  /** Whether this column can be reordered by dragging its header */
+  columnDraggable: boolean;
   startCardDrag: (
     cardId: string,
     columnKey: string,
@@ -115,6 +119,8 @@ function KanbanColumnInner<T>({
   onCardPress,
   onAddCard,
   onAddCardAtIndex,
+  cardDraggable,
+  columnDraggable,
   startCardDrag,
   startColumnDrag,
   registerColumn,
@@ -215,20 +221,24 @@ function KanbanColumnInner<T>({
     };
   }, [isHeaderPressing, columnKey, index, startColumnDrag]);
 
-  const handleHeaderPressIn = useCallback((event: GestureResponderEvent) => {
-    // Use clientX/clientY (viewport-relative) for consistency with mousemove events
-    const clientX = event.nativeEvent.pageX - window.scrollX;
-    const clientY = event.nativeEvent.pageY - window.scrollY;
-    headerPressStartRef.current = { x: clientX, y: clientY };
-    hasColumnDraggedRef.current = false;
+  const handleHeaderPressIn = useCallback(
+    (event: GestureResponderEvent) => {
+      if (!columnDraggable) return;
+      // Use clientX/clientY (viewport-relative) for consistency with mousemove events
+      const clientX = event.nativeEvent.pageX - window.scrollX;
+      const clientY = event.nativeEvent.pageY - window.scrollY;
+      headerPressStartRef.current = { x: clientX, y: clientY };
+      hasColumnDraggedRef.current = false;
 
-    const element = containerRef.current as unknown as HTMLElement | null;
-    if (element) {
-      const rect = element.getBoundingClientRect();
-      columnRectRef.current = rect;
-      setIsHeaderPressing(true);
-    }
-  }, []);
+      const element = containerRef.current as unknown as HTMLElement | null;
+      if (element) {
+        const rect = element.getBoundingClientRect();
+        columnRectRef.current = rect;
+        setIsHeaderPressing(true);
+      }
+    },
+    [columnDraggable],
+  );
 
   const handleScroll = useCallback(
     (event: NativeSyntheticEvent<NativeScrollEvent>) => {
@@ -325,6 +335,7 @@ function KanbanColumnInner<T>({
           isDragging={isCardDragging}
           isDropTarget={isCardDropTarget}
           isDragInProgress={isDragInProgress}
+          cardDraggable={cardDraggable}
           onCardPress={onCardPress}
           onAddCardAtIndex={onAddCardAtIndex}
           renderInsertCardButton={renderInsertCardButton}
@@ -342,6 +353,7 @@ function KanbanColumnInner<T>({
       onCardPress,
       onAddCardAtIndex,
       renderInsertCardButton,
+      cardDraggable,
       startCardDrag,
       getHeight,
       itemGap,

package/src/picker.tsx

@@ -8,11 +8,16 @@ import { Icon } from "./icon";
 import { Popover, PopoverTrigger, PopoverContent } from "./popover";
 import { PickerMenu } from "./picker_menu";
 
-export interface PickerOption<T extends string = string> {
+export interface PickerOption<T extends string = string, D = unknown> {
   label?: string;
   value: T;
   disabled?: boolean;
   testID?: string;
+  /** Arbitrary payload carried alongside the option. Lets a rich
+   *  `renderOptionContent` (and async/recents flows) render from the source
+   *  row without a side lookup keyed by `value`. Untyped by default; a
+   *  component generic over `D` surfaces it typed. */
+  data?: D;
 }
 
 export type PickerValue<T extends string, MULTI extends boolean> = MULTI extends true ? T[] : T;

package/src/popover.tsx

@@ -184,6 +184,12 @@ export interface PopoverContentProps {
   small?: boolean;
   /** Accessible name for the bottom-sheet close button. Default: "Close". Pass a translated string from the consumer. */
   closeLabel?: string;
+  /** When true (default), the popover moves focus into its content on open and
+   *  restores it on close. Set false for an anchored panel whose trigger must
+   *  keep focus — e.g. a search-as-you-type combobox whose input lives outside
+   *  the popover and drives the list via `aria-activedescendant`. Focus then
+   *  stays on the trigger; keyboard still reaches it through the overlay. */
+  manageFocus?: boolean;
 }
 
 export function PopoverContent(props: PopoverContentProps) {
@@ -195,6 +201,7 @@ export function PopoverContent(props: PopoverContentProps) {
     disableBodyScroll,
     small = false,
     closeLabel = "Close",
+    manageFocus = true,
   } = props;
   const { open, onOpenChange, triggerRef, side, align, offset, inheritTriggerWidth } =
     usePopoverContext();
@@ -232,7 +239,7 @@ export function PopoverContent(props: PopoverContentProps) {
   // When it closes, restore focus to the prior element so keyboard users don't
   // land at the top of the page.
   useEffect(() => {
-    if (!open) return;
+    if (!open || !manageFocus) return;
     const previouslyFocused = document.activeElement as HTMLElement | null;
     returnFocusRef.current = previouslyFocused;
 
@@ -253,7 +260,7 @@ export function PopoverContent(props: PopoverContentProps) {
         target.focus();
       }
     };
-  }, [open]);
+  }, [open, manageFocus]);
 
   // Separate header, footer, and body from children
   let header: React.ReactNode = null;

package/src/search_select.tsx

@@ -0,0 +1,295 @@
+import {
+  View,
+  ScrollView,
+  StyleSheet,
+  type StyleProp,
+  type ViewStyle,
+  type TextInput as RNTextInput,
+} from "react-native";
+import { useCallback, useEffect, useId, useRef, useState, type ReactNode } from "react";
+import { colors } from "./colors";
+import { Text } from "./text";
+import { Icon } from "./icon";
+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 SearchSelectProps<T extends string = string, D = unknown> {
+  /** Result options for the current query. The consumer refreshes these in
+   *  response to `onSearchChange` — search runs server-side, so the whole table
+   *  is never shipped to the client. */
+  options: PickerOption<T, D>[];
+  /** Debounced; fires as the user types. Drive a server re-query from it. */
+  onSearchChange: (query: string) => void;
+  /** Fires when the user picks a result or a recent. */
+  onValueChange: (option: PickerOption<T, D>) => void;
+  /** Shown — under a heading — when the box is focused but empty (e.g. the
+   *  output of `useRecents`). Omit for no recents. */
+  recentOptions?: PickerOption<T, D>[];
+  /** Render a rich row from the option (use its `data` payload). Falls back to
+   *  `option.label`. */
+  renderOptionContent?: (option: PickerOption<T, D>) => ReactNode;
+  /** Marks the matching row as the current selection (check + highlight). The
+   *  box itself stays a search affordance — the selection is shown by the host. */
+  selectedValue?: T | null;
+  /** Show a spinner while results are in flight. */
+  loading?: boolean;
+  /** Debounce for `onSearchChange`, in ms. Default 200. */
+  searchDebounceMs?: number;
+  placeholder?: string;
+  /** Heading above the recents list. Default "Recent". Pass a translated string. */
+  recentsLabel?: string;
+  /** No-results-for-query text. Default "No results". Pass a translated string. */
+  emptyText?: string;
+  /** Accessible name for the results listbox. Default "Results". */
+  accessibilityLabel?: string;
+  disabled?: boolean;
+  autoFocus?: boolean;
+  testID?: string;
+  style?: StyleProp<ViewStyle>;
+}
+
+const OPTION_HEIGHT = 44;
+
+/**
+ * Search-first combobox: an always-visible search input (the "panel") whose
+ * typing drives a debounced, server-side search; results drop into a Popover
+ * listbox below. Focused while empty, it offers `recentOptions`. Picking a row
+ * fires `onValueChange` and clears the box for the next search — the selection
+ * itself is rendered by the host (a summary above, details below).
+ *
+ * Focus stays on the input the whole time (Popover `manageFocus={false}`); the
+ * input owns the keyboard (↑/↓ move the active row via `aria-activedescendant`,
+ * Enter selects, Esc closes) — the ARIA combobox pattern, not a button trigger.
+ */
+export function SearchSelect<T extends string = string, D = unknown>(
+  props: SearchSelectProps<T, D>,
+) {
+  const {
+    options,
+    onSearchChange,
+    onValueChange,
+    recentOptions,
+    renderOptionContent,
+    selectedValue = null,
+    loading = false,
+    searchDebounceMs = 200,
+    placeholder,
+    recentsLabel = "Recent",
+    emptyText = "No results",
+    accessibilityLabel = "Results",
+    disabled = false,
+    autoFocus = false,
+    testID,
+    style,
+  } = props;
+
+  const [query, setQuery] = useState("");
+  const [open, setOpen] = useState(autoFocus);
+  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 searching = query.trim().length > 0;
+  const list = searching ? options : (recentOptions ?? []);
+
+  const debouncedSearch = useDebouncedCallback(onSearchChange, searchDebounceMs);
+
+  const scrollToIndex = useCallback((index: number) => {
+    scrollRef.current?.scrollTo({ y: Math.max(0, index * OPTION_HEIGHT - 80), animated: false });
+  }, []);
+
+  const handleSelect = useCallback(
+    (index: number) => {
+      const opt = list[index];
+      if (!opt || opt.disabled) return;
+      onValueChange(opt);
+      // The trailing search is irrelevant once a pick is made. Cancel it and
+      // tell the consumer the term is now empty (the box clears) so its query
+      // state matches and any search-driven fetch goes idle.
+      debouncedSearch.cancel();
+      setQuery("");
+      onSearchChange("");
+      setOpen(false);
+      // A click on a row blurs the input; keep it focused so the user can
+      // search again without re-clicking.
+      inputRef.current?.focus();
+    },
+    [list, onValueChange, onSearchChange, debouncedSearch],
+  );
+
+  const { activeIndex, setActiveIndex, handleKey } = useListKeyboardNav({
+    count: list.length,
+    isDisabled: (i) => list[i]?.disabled ?? false,
+    onSelect: handleSelect,
+    onClose: () => setOpen(false),
+    onActiveChange: scrollToIndex,
+  });
+
+  // Reset the active row when the visible list changes (new results, or toggling
+  // between results and recents). Keyed on primitives so a consumer re-render
+  // with an equal-but-new array doesn't reset mid-navigation.
+  const firstValue = list[0]?.value;
+  useEffect(() => {
+    setActiveIndex(0);
+  }, [searching, list.length, firstValue, setActiveIndex]);
+
+  const handleChangeText = useCallback(
+    (text: string) => {
+      setQuery(text);
+      if (!disabled) setOpen(true);
+      debouncedSearch(text);
+    },
+    [disabled, debouncedSearch],
+  );
+
+  const handleKeyPress = useCallback(
+    (e: { nativeEvent: { key: string }; preventDefault: () => void }) => {
+      const key = e.nativeEvent.key;
+      if (!open && (key === "ArrowDown" || key === "ArrowUp")) setOpen(true);
+      if (handleKey(key)) e.preventDefault();
+    },
+    [open, handleKey],
+  );
+
+  // Nothing to show ⇒ don't open an empty popover (focused box, no recents).
+  const showList = open && !disabled && (searching || list.length > 0);
+  const activeOptionId =
+    activeIndex >= 0 && activeIndex < list.length ? optionId(activeIndex) : undefined;
+  const listLabel = searching ? accessibilityLabel : recentsLabel;
+
+  return (
+    <View style={style}>
+      <View ref={triggerRef}>
+        <TextInputField
+          ref={inputRef}
+          testID={testID}
+          icon="search"
+          clearable
+          value={query}
+          onChangeText={handleChangeText}
+          onFocus={() => {
+            if (!disabled) setOpen(true);
+          }}
+          onKeyPress={handleKeyPress}
+          placeholder={placeholder}
+          placeholderTextColor={colors.zinc["400"]}
+          editable={!disabled}
+          autoFocus={autoFocus}
+          autoCapitalize="none"
+          autoCorrect={false}
+          role="combobox"
+          aria-expanded={showList}
+          aria-controls={listboxId}
+          aria-activedescendant={activeOptionId}
+          aria-autocomplete="list"
+        />
+      </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 && list.length > 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={listLabel}
+              keyboardShouldPersistTaps="handled"
+              // `listbox` is valid ARIA but absent from React Native's Role enum;
+              // react-native-web forwards it verbatim for assistive tech.
+              role={"listbox" as "list"}
+            >
+              {loading && searching ? (
+                <View style={styles.statusRow}>
+                  <ActivityIndicator />
+                </View>
+              ) : list.length === 0 ? (
+                <View style={styles.statusRow}>
+                  <Text size="sm" color="zinc-500">
+                    {emptyText}
+                  </Text>
+                </View>
+              ) : (
+                list.map((opt, i) => {
+                  const isSelected = opt.value === selectedValue;
+                  return (
+                    <MenuButton
+                      key={opt.value}
+                      nativeID={optionId(i)}
+                      testID={`search-option-${opt.value}`}
+                      role="option"
+                      title={
+                        renderOptionContent ? (
+                          renderOptionContent(opt)
+                        ) : (
+                          <Text userSelect="none" numberOfLines={1}>
+                            {opt.label ?? opt.value}
+                          </Text>
+                        )
+                      }
+                      accessibilityLabel={opt.label ?? opt.value}
+                      focused={i === activeIndex}
+                      selected={isSelected}
+                      right={
+                        isSelected ? (
+                          <Icon name="check" size={18} color={colors.zinc["950"]} />
+                        ) : undefined
+                      }
+                      disabled={opt.disabled}
+                      onPress={() => handleSelect(i)}
+                      onHoverIn={() => setActiveIndex(i)}
+                    />
+                  );
+                })
+              )}
+            </ScrollView>
+          </View>
+        </PopoverContent>
+      </Popover>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  menu: {
+    gap: 2,
+  },
+  sectionHeader: {
+    paddingHorizontal: 8,
+    paddingTop: 4,
+    paddingBottom: 2,
+  },
+  scroll: {
+    maxHeight: 320,
+  },
+  statusRow: {
+    alignItems: "center",
+    justifyContent: "center",
+    paddingVertical: 16,
+  },
+});

package/src/use_debounced_callback.ts

@@ -0,0 +1,35 @@
+import { useCallback, useEffect, useRef } from "react";
+
+/**
+ * Debounce a possibly-undefined callback. The latest `fn` is always invoked
+ * (captured by ref, so changing it between renders doesn't reset the timer),
+ * and any pending call is cleared on unmount. `cancel` drops a pending call —
+ * use it when a selection makes the trailing search irrelevant.
+ */
+export function useDebouncedCallback<A extends unknown[]>(
+  fn: ((...args: A) => void) | undefined,
+  ms: number,
+): ((...args: A) => void) & { cancel: () => void } {
+  const fnRef = useRef(fn);
+  fnRef.current = fn;
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const cancel = useCallback(() => {
+    if (timer.current) {
+      clearTimeout(timer.current);
+      timer.current = null;
+    }
+  }, []);
+
+  useEffect(() => cancel, [cancel]);
+
+  const debounced = useCallback(
+    (...args: A) => {
+      cancel();
+      timer.current = setTimeout(() => fnRef.current?.(...args), ms);
+    },
+    [ms, cancel],
+  );
+
+  return Object.assign(debounced, { cancel });
+}

package/src/use_list_keyboard_nav.test.ts

@@ -0,0 +1,106 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi } from "vitest";
+import { act, renderHook } from "@testing-library/react";
+import { useListKeyboardNav, type ListKeyboardNavOptions } from "./use_list_keyboard_nav";
+
+function setup(overrides: Partial<ListKeyboardNavOptions> = {}) {
+  const onSelect = vi.fn();
+  const onClose = vi.fn();
+  const onActiveChange = vi.fn();
+  const opts: ListKeyboardNavOptions = {
+    count: 4,
+    onSelect,
+    onClose,
+    onActiveChange,
+    ...overrides,
+  };
+  const view = renderHook((p: ListKeyboardNavOptions) => useListKeyboardNav(p), {
+    initialProps: opts,
+  });
+  return { view, onSelect, onClose, onActiveChange };
+}
+
+describe("useListKeyboardNav", () => {
+  it("starts at index 0", () => {
+    const { view } = setup();
+    expect(view.result.current.activeIndex).toBe(0);
+  });
+
+  it("ArrowDown / ArrowUp move within bounds and report handled", () => {
+    const { view } = setup();
+    let handled = false;
+    act(() => {
+      handled = view.result.current.handleKey("ArrowDown");
+    });
+    expect(handled).toBe(true);
+    expect(view.result.current.activeIndex).toBe(1);
+    act(() => void view.result.current.handleKey("ArrowUp"));
+    expect(view.result.current.activeIndex).toBe(0);
+  });
+
+  it("does not move past the ends", () => {
+    const { view } = setup({ count: 2 });
+    act(() => void view.result.current.handleKey("ArrowUp"));
+    expect(view.result.current.activeIndex).toBe(0);
+    act(() => void view.result.current.handleKey("ArrowDown"));
+    act(() => void view.result.current.handleKey("ArrowDown"));
+    expect(view.result.current.activeIndex).toBe(1);
+  });
+
+  it("skips disabled rows", () => {
+    const { view } = setup({ count: 4, isDisabled: (i) => i === 1 || i === 2 });
+    act(() => void view.result.current.handleKey("ArrowDown"));
+    expect(view.result.current.activeIndex).toBe(3);
+  });
+
+  it("Home / End jump to the first / last enabled row", () => {
+    const { view } = setup({ count: 4, isDisabled: (i) => i === 3 });
+    act(() => void view.result.current.handleKey("End"));
+    expect(view.result.current.activeIndex).toBe(2);
+    act(() => void view.result.current.handleKey("Home"));
+    expect(view.result.current.activeIndex).toBe(0);
+  });
+
+  it("Enter selects the active row", () => {
+    const { view, onSelect } = setup();
+    act(() => void view.result.current.handleKey("ArrowDown"));
+    act(() => void view.result.current.handleKey("Enter"));
+    expect(onSelect).toHaveBeenCalledWith(1);
+  });
+
+  it("Enter does not select a disabled active row", () => {
+    const { view, onSelect } = setup({ count: 2, isDisabled: () => true });
+    act(() => void view.result.current.handleKey("Enter"));
+    expect(onSelect).not.toHaveBeenCalled();
+  });
+
+  it("Escape closes and is handled; Tab closes but is not handled", () => {
+    const { view, onClose } = setup();
+    let escHandled = true;
+    let tabHandled = true;
+    act(() => {
+      escHandled = view.result.current.handleKey("Escape");
+    });
+    act(() => {
+      tabHandled = view.result.current.handleKey("Tab");
+    });
+    expect(onClose).toHaveBeenCalledTimes(2);
+    expect(escHandled).toBe(true);
+    expect(tabHandled).toBe(false);
+  });
+
+  it("reports unknown keys as not handled", () => {
+    const { view } = setup();
+    let handled = true;
+    act(() => {
+      handled = view.result.current.handleKey("a");
+    });
+    expect(handled).toBe(false);
+  });
+
+  it("notifies onActiveChange when the active row moves", () => {
+    const { view, onActiveChange } = setup();
+    act(() => void view.result.current.handleKey("ArrowDown"));
+    expect(onActiveChange).toHaveBeenCalledWith(1);
+  });
+});

package/src/use_list_keyboard_nav.ts

@@ -0,0 +1,90 @@
+import { useCallback, useState } from "react";
+
+export interface ListKeyboardNavOptions {
+  /** Number of rows in the list. */
+  count: number;
+  /** Whether the row at `index` is disabled (skipped by arrow nav). */
+  isDisabled?: (index: number) => boolean;
+  /** Activate the row at `index` (Enter, or a click the caller wires up). */
+  onSelect: (index: number) => void;
+  /** Dismiss the list (Escape, Tab). */
+  onClose?: () => void;
+  /** Fires when the active row changes — use it to scroll the row into view. */
+  onActiveChange?: (index: number) => void;
+}
+
+export interface ListKeyboardNav {
+  /** The virtually-focused row. The list stays visually highlighted here while
+   *  DOM focus remains on the controlling input (ARIA `aria-activedescendant`). */
+  activeIndex: number;
+  setActiveIndex: (index: number) => void;
+  /** Feed a key from the controlling input's `onKeyPress`. Returns true when it
+   *  handled the key, so the caller can `preventDefault()`. */
+  handleKey: (key: string) => boolean;
+}
+
+/**
+ * Roving keyboard navigation for a single-select option list driven by an
+ * external input (the combobox / command-menu pattern): Up/Down move past
+ * disabled rows, Home/End jump to the ends, Enter selects, Escape/Tab dismiss.
+ * Focus never leaves the input — this only tracks the active index.
+ */
+export function useListKeyboardNav(opts: ListKeyboardNavOptions): ListKeyboardNav {
+  const { count, isDisabled, onSelect, onClose, onActiveChange } = opts;
+  const [activeIndex, setActiveIndexState] = useState(0);
+
+  const setActiveIndex = useCallback(
+    (index: number) => {
+      setActiveIndexState(index);
+      onActiveChange?.(index);
+    },
+    [onActiveChange],
+  );
+
+  const handleKey = useCallback(
+    (key: string): boolean => {
+      const enabled = (i: number) => i >= 0 && i < count && !(isDisabled?.(i) ?? false);
+      switch (key) {
+        case "ArrowDown": {
+          let next = activeIndex + 1;
+          while (next < count && !enabled(next)) next++;
+          if (next < count) setActiveIndex(next);
+          return true;
+        }
+        case "ArrowUp": {
+          let prev = activeIndex - 1;
+          while (prev >= 0 && !enabled(prev)) prev--;
+          if (prev >= 0) setActiveIndex(prev);
+          return true;
+        }
+        case "Home": {
+          let first = 0;
+          while (first < count && !enabled(first)) first++;
+          if (first < count) setActiveIndex(first);
+          return true;
+        }
+        case "End": {
+          let last = count - 1;
+          while (last >= 0 && !enabled(last)) last--;
+          if (last >= 0) setActiveIndex(last);
+          return true;
+        }
+        case "Enter":
+          if (enabled(activeIndex)) onSelect(activeIndex);
+          return true;
+        case "Escape":
+          onClose?.();
+          return true;
+        case "Tab":
+          // Let focus move on, but dismiss the list.
+          onClose?.();
+          return false;
+        default:
+          return false;
+      }
+    },
+    [activeIndex, count, isDisabled, onSelect, onClose, setActiveIndex],
+  );
+
+  return { activeIndex, setActiveIndex, handleKey };
+}