@lotics/ui 5.8.0 → 5.10.0

package/src/table.tsx

@@ -12,6 +12,8 @@ import { Text } from "./text";
 import { Divider } from "./divider";
 import { PressableRow } from "./pressable_row";
 import { SortHeader, type SortState, type SortHeaderLabels } from "./sort_header";
+import { FOCUS_RING } from "./control_surface";
+import { useFocusRing } from "./use_focus_ring";
 
 /**
  * One column of a register — its width/flex/align/label/sortability defined ONCE,
@@ -132,6 +134,7 @@ export function TableRow(props: TableRowProps) {
   const cells = (Children.toArray(children).filter(isValidElement) as ReactElement<TableCellProps>[]).map(
     (cell, i) => cloneElement(cell, { _column: ctx.columns[i] }),
   );
+  const { focusVisible, focusProps } = useFocusRing();
 
   return (
     <PressableRow onPress={onPress ?? noop} selected={selected} style={styles.row}>
@@ -140,7 +143,8 @@ export function TableRow(props: TableRowProps) {
         accessibilityRole={onPress ? "button" : undefined}
         accessibilityLabel={accessibilityLabel}
         onPress={onPress}
-        style={[styles.door, { minHeight }]}
+        {...focusProps}
+        style={[styles.door, { minHeight }, focusVisible && { boxShadow: FOCUS_RING }]}
       >
         {cells}
       </Pressable>

package/src/tabs.tsx

@@ -110,8 +110,8 @@ function TabButton<T extends string>(props: TabButtonProps<T>) {
 
   return (
     <PressableHighlight
-      ref={ref}
-      style={{
+      focusRing
+      ref={ref}      style={{
         borderBottomWidth: 3,
         borderBottomColor: selected ? colors.zinc["700"] : "transparent",
         backgroundColor: "transparent",

package/src/text_input_field.tsx

@@ -5,7 +5,9 @@ import {
   View,
 } from "react-native";
 import { colors } from "./colors";
-import { CONTROL_RADIUS } from "./control_surface";
+import { CONTROL_RADIUS, FOCUS_RING, HOVER_BORDER, CONTROL_TRANSITION } from "./control_surface";
+import { useFocusRing, composeHandler } from "./use_focus_ring";
+import { useHover } from "./use_hover";
 import { Ref, useCallback } from "react";
 import { Icon, IconName } from "./icon";
 import { IconButton } from "./icon_button";
@@ -68,6 +70,12 @@ export function TextInputField(props: TextInputFieldProps) {
   const { small } = useScreenSize();
   const lineHeight = getInputLineHeight(small);
   const binding = useFormField();
+  // Text-like input: ring on ANY focus (browsers treat typing-capable fields as
+  // focus-visible even on pointer focus), so a clicked field shows its ring.
+  const { focusVisible, focusProps } = useFocusRing({ always: true });
+  // Premium hover affordance: the resting border darkens, signalling interactivity.
+  // Tracked on the wrapping View (RN-Web forwards mouse events there reliably).
+  const { hovered, hoverProps } = useHover();
 
   // Describedby chains description and error so both are read. We join them
   // explicitly here because React Native Web does not flatten array attrs.
@@ -108,7 +116,7 @@ export function TextInputField(props: TextInputFieldProps) {
   );
 
   return (
-    <View>
+    <View {...(hoverProps as object)}>
       {icon && (
         <View style={styles.icon}>
           <Icon name={icon} size={20} color={colors.zinc[400]} />
@@ -120,20 +128,23 @@ export function TextInputField(props: TextInputFieldProps) {
         ref={mergedRef}
         value={value}
         onChangeText={handleChangeText}
-        onFocus={inputProps.onFocus}
-        onBlur={inputProps.onBlur}
+        onFocus={composeHandler(inputProps.onFocus, focusProps.onFocus)}
+        onBlur={composeHandler(inputProps.onBlur, focusProps.onBlur)}
         nativeID={binding?.inputId ?? inputProps.nativeID}
         accessibilityLabelledBy={binding?.labelId ?? inputProps.accessibilityLabelledBy}
         aria-describedby={describedBy}
         aria-invalid={binding?.invalid || undefined}
         style={[
           styles.input,
+          CONTROL_TRANSITION,
           getInputTextStyle(),
           height ? { height } : undefined,
           autoGrow && !autoGrowResult.scrollEnabled && { overflow: "hidden" as const },
           !editable && styles.disabled,
           icon && styles.withIcon,
+          hovered && editable && { borderColor: HOVER_BORDER },
           style,
+          focusVisible && { boxShadow: FOCUS_RING },
         ]}
         multiline={(numberOfLines && numberOfLines > 1) || multiline}
         focusable={editable}

package/src/time_picker.tsx

@@ -1,7 +1,9 @@
 import type { KeyboardEvent } from "react";
 import { colors } from "@lotics/ui/colors";
 import { fontFamilyRegular, inputTextStyleWeb } from "@lotics/ui/text_utils";
-import { CONTROL_RADIUS } from "./control_surface";
+import { CONTROL_RADIUS, FOCUS_RING, HOVER_BORDER } from "./control_surface";
+import { useFocusRing } from "./use_focus_ring";
+import { useHover } from "./use_hover";
 export interface TimePickerProps {
   value?: string;
   onValueChange: (value: string) => void;
@@ -15,6 +17,8 @@ export interface TimePickerProps {
 
 export function TimePicker(props: TimePickerProps) {
   const { value, onValueChange, onBlur, onKeyDown, autoFocus, disabled, accessibilityLabel } = props;
+  const { focusVisible, focusProps } = useFocusRing({ always: true });
+  const { hovered, hoverProps } = useHover();
 
   return (
     <input
@@ -23,7 +27,9 @@ export function TimePicker(props: TimePickerProps) {
         onValueChange(e.target.value);
       }}
       type="time"
-      onBlur={onBlur}
+      {...hoverProps}
+      onFocus={focusProps.onFocus}
+      onBlur={() => { focusProps.onBlur(); onBlur?.(); }}
       onKeyDown={onKeyDown}
       autoFocus={autoFocus}
       disabled={disabled}
@@ -35,14 +41,15 @@ export function TimePicker(props: TimePickerProps) {
         borderRadius: CONTROL_RADIUS,
         borderWidth: 1,
         borderStyle: "solid",
-        borderColor: colors.border,
+        borderColor: hovered && !disabled ? HOVER_BORDER : colors.border,
         backgroundColor: colors.background,
         fontFamily: fontFamilyRegular,
         ...inputTextStyleWeb,
         letterSpacing: -0.4,
-        boxShadow: "none",
+        boxShadow: focusVisible ? FOCUS_RING : "none",
         outline: "none",
         boxSizing: "border-box",
+        transition: "border-color 0.12s, box-shadow 0.12s",
       }}
     />
   );

package/src/timeline.tsx

@@ -85,7 +85,7 @@ export function Timeline(props: TimelineProps) {
 
             <View style={styles.contentColumn}>
               {hasDetails ? (
-                <PressableHighlight onPress={() => toggleItem(item.id)} style={styles.pressableRow}>
+                <PressableHighlight focusRing onPress={() => toggleItem(item.id)} style={styles.pressableRow}>
                   {row}
                 </PressableHighlight>
               ) : (

package/src/uploading_thumbnail.tsx

@@ -0,0 +1,212 @@
+// UploadingThumbnail — the in-flight upload tile (loading / paused / retrying /
+// error states). Pure: reuses the file display primitives (DocumentCard,
+// MediaCard, RemoveButton) and is i18n-free (status text comes in via `labels`).
+// Pairs with FileGrid, which interleaves these with completed FileThumbnails.
+
+import { Icon } from "./icon";
+import { Text } from "./text";
+import { IconButton } from "./icon_button";
+import { colors } from "./colors";
+import { DocumentCard, MediaCard, RemoveButton, getMediaIcon } from "./file_thumbnail";
+import { ActivityIndicator, Image, StyleSheet, View } from "react-native";
+import { isImageMimeType } from "./mime";
+
+/** In-flight upload states (everything except a completed file). */
+export type UploadStatus = "preparing" | "queued" | "uploading" | "paused_offline" | "retrying" | "error";
+
+/** Status text for the non-happy-path states. i18n-free defaults (English); the
+ *  Lotics host injects translations. The common `uploading` state stays text-free
+ *  (a spinner is self-evident) — only states that need attention get a word. */
+export interface UploadStatusLabels {
+  /** Upload paused because the device is offline. Default "Paused". */
+  paused?: string;
+  /** Upload is being retried. Default "Retrying". */
+  retrying?: string;
+  /** Upload failed but can be retried. Default "Upload failed". */
+  failed?: string;
+  /** Upload failed and retry is futile (dead file ref / empty bytes — re-pick). Default "Can't upload". */
+  unavailable?: string;
+  /** Accessible label on the retry control. Default "Retry upload". */
+  retry?: string;
+}
+
+interface UploadingThumbnailProps {
+  filename: string;
+  mimeType: string;
+  previewUrl?: string;
+  status: UploadStatus;
+  /** True when retry would hit the same failure on the same input: the picker
+   * File reference is dead (Android SAF eviction) or the file has zero bytes
+   * (empty clipboard paste). The user must re-pick or re-copy the file. */
+  staleFile?: boolean;
+  /** Explicit pixel size. When omitted, fills container. */
+  size?: number;
+  onRemove?: () => void;
+  onRetry?: () => void;
+  labels?: UploadStatusLabels;
+}
+
+/** Below this tile size the status word can't fit — show the icon/spinner alone. */
+const LABEL_MIN_SIZE = 72;
+
+/**
+ * Displays a file during upload with loading/error states.
+ */
+export function UploadingThumbnail(props: UploadingThumbnailProps) {
+  const { filename, mimeType, previewUrl, status, staleFile, size, onRemove, onRetry, labels } = props;
+  const compact = size !== undefined && size < LABEL_MIN_SIZE;
+
+  const rootStyle =
+    size !== undefined ? { width: size, height: size } : { width: "100%" as const, aspectRatio: 1 };
+
+  const overlay = (
+    <UploadOverlay
+      status={status}
+      staleFile={staleFile === true}
+      compact={compact}
+      labels={labels}
+      onRetry={onRetry}
+    />
+  );
+
+  if (isImageMimeType(mimeType) && previewUrl) {
+    return (
+      <View style={[styles.uploadingContainer, rootStyle]}>
+        <Image source={{ uri: previewUrl }} style={styles.uploadingImage} resizeMode="cover" />
+        {overlay}
+        {onRemove && <RemoveButton onPress={onRemove} />}
+      </View>
+    );
+  }
+
+  const mediaIcon = getMediaIcon(mimeType);
+
+  return (
+    <View style={rootStyle}>
+      {mediaIcon !== undefined ? (
+        <MediaCard mimeType={mimeType} filename={filename} icon={mediaIcon} overlay={overlay} />
+      ) : (
+        <DocumentCard mimeType={mimeType} filename={filename} overlay={overlay} />
+      )}
+      {onRemove && <RemoveButton onPress={onRemove} />}
+    </View>
+  );
+}
+
+function UploadOverlay(props: {
+  status: UploadStatus;
+  staleFile: boolean;
+  compact: boolean;
+  labels?: UploadStatusLabels;
+  onRetry?: () => void;
+}) {
+  const { status, staleFile, compact, labels, onRetry } = props;
+
+  if (status === "preparing" || status === "queued" || status === "uploading") {
+    return (
+      <View style={styles.overlay} pointerEvents="none">
+        <ActivityIndicator size="small" color={colors.white} />
+      </View>
+    );
+  }
+
+  if (status === "paused_offline") {
+    return (
+      <OverlayStack compact={compact} label={labels?.paused ?? "Paused"}>
+        <Icon name="pause" size={20} color={colors.white} />
+      </OverlayStack>
+    );
+  }
+
+  if (status === "retrying") {
+    return (
+      <OverlayStack compact={compact} label={labels?.retrying ?? "Retrying"}>
+        <ActivityIndicator size="small" color={colors.white} />
+      </OverlayStack>
+    );
+  }
+
+  // error, retry is futile — the user must re-pick the file
+  if (staleFile) {
+    return (
+      <OverlayStack tone="error" compact={compact} label={labels?.unavailable ?? "Can't upload"}>
+        <Icon name="circle-alert" size={20} color={colors.white} />
+      </OverlayStack>
+    );
+  }
+
+  // error, retryable
+  return (
+    <View style={[styles.overlay, styles.overlayError]} pointerEvents="box-none">
+      <View style={styles.stack}>
+        {onRetry && (
+          <IconButton
+            icon="rotate-cw"
+            size={compact ? "sm" : "md"}
+            elevated
+            accessibilityLabel={labels?.retry ?? "Retry upload"}
+            onPress={(e) => {
+              e.stopPropagation();
+              onRetry();
+            }}
+          />
+        )}
+        {!compact && <OverlayLabel>{labels?.failed ?? "Upload failed"}</OverlayLabel>}
+      </View>
+    </View>
+  );
+}
+
+function OverlayStack(props: { tone?: "error"; compact: boolean; label: string; children: React.ReactNode }) {
+  return (
+    <View style={[styles.overlay, props.tone === "error" && styles.overlayError]} pointerEvents="none">
+      <View style={styles.stack}>
+        {props.children}
+        {!props.compact && <OverlayLabel>{props.label}</OverlayLabel>}
+      </View>
+    </View>
+  );
+}
+
+function OverlayLabel({ children }: { children: string }) {
+  return (
+    <Text size="xs" weight="medium" color="inverted" numberOfLines={2} style={styles.overlayLabel} userSelect="none">
+      {children}
+    </Text>
+  );
+}
+
+const styles = StyleSheet.create({
+  uploadingContainer: {
+    position: "relative",
+  },
+  uploadingImage: {
+    width: "100%",
+    height: "100%",
+    borderRadius: 10,
+  },
+  overlay: {
+    position: "absolute",
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    borderRadius: 10,
+    backgroundColor: "rgba(24, 24, 27, 0.55)",
+    justifyContent: "center",
+    alignItems: "center",
+    padding: 8,
+  },
+  // Error states get a red wash — the at-a-glance "this didn't work" signal —
+  // dark enough that the white label + elevated retry button stay legible.
+  overlayError: {
+    backgroundColor: "rgba(153, 27, 27, 0.66)",
+  },
+  stack: {
+    alignItems: "center",
+    gap: 6,
+  },
+  overlayLabel: {
+    textAlign: "center",
+  },
+});

package/src/use_focus_ring.ts

@@ -0,0 +1,80 @@
+import { useCallback, useState } from "react";
+
+/**
+ * Combine two optional event handlers into one. Either may be undefined.
+ * Used to layer a focus-ring handler on top of a caller's (or a tooltip's)
+ * `onFocus`/`onBlur` so neither silently clobbers the other.
+ */
+export function composeHandler<E>(
+  a: ((event: E) => void) | undefined,
+  b: ((event: E) => void) | undefined,
+): ((event: E) => void) | undefined {
+  if (!a) return b;
+  if (!b) return a;
+  return (event: E) => {
+    a(event);
+    b(event);
+  };
+}
+
+// `:focus-visible` is a MODALITY heuristic: a control shows its ring on keyboard
+// focus but not pointer focus. The kit no longer carries a global `:focus-visible`
+// CSS rule, so every control paints its own ring — and needs that same signal. One
+// focus event carries no modality, so it can only be read at the document level:
+// a single module-level tracker records the last interaction. Web-only — on native
+// / SSR there is no `document`, so it stays "pointer" and the ring is keyboard-gated
+// off (text-like inputs opt back in with `always`).
+type Modality = "keyboard" | "pointer";
+let lastModality: Modality = "pointer";
+let listenersInstalled = false;
+
+function ensureModalityListeners(): void {
+  if (listenersInstalled) return;
+  if (typeof document === "undefined") return;
+  listenersInstalled = true;
+  // Capture phase so the modality is recorded BEFORE any control's focus handler
+  // runs. Installed once for the app's lifetime (the browser's own `:focus-visible`
+  // heuristic listens the same way) — per-mount add/remove would be the bug.
+  const opts = { capture: true, passive: true } as const;
+  document.addEventListener("keydown", () => { lastModality = "keyboard"; }, opts);
+  document.addEventListener("pointerdown", () => { lastModality = "pointer"; }, opts);
+  document.addEventListener("mousedown", () => { lastModality = "pointer"; }, opts);
+  document.addEventListener("touchstart", () => { lastModality = "pointer"; }, opts);
+}
+
+export interface UseFocusRingOptions {
+  /**
+   * Ring on ANY focus, not just keyboard focus. For text-like inputs, which the
+   * browser treats as focus-visible even on pointer focus, so a clicked field shows
+   * its ring immediately. Plain controls omit this — they ring on keyboard only.
+   */
+  always?: boolean;
+}
+
+export interface FocusRingState {
+  /**
+   * True while the element should show its focus ring: focused AND (unless
+   * `always`) the last interaction was the keyboard. Drive a `boxShadow` off this,
+   * composing with any existing one — e.g. `focusVisible ? FOCUS_RING : undefined`.
+   */
+  focusVisible: boolean;
+  /** Raw focus state, regardless of modality. */
+  focused: boolean;
+  /** Spread onto the focusable element, or compose with `composeHandler`. */
+  focusProps: { onFocus: () => void; onBlur: () => void };
+}
+
+/**
+ * Keyboard-aware focus state for painting a control's own focus ring inline.
+ * Replaces the kit's removed global `:focus-visible` CSS rule: each interactive
+ * primitive calls this and renders `FOCUS_RING` (`control_surface.ts`) when
+ * `focusVisible`. App authors do the same for their own raw focusable elements.
+ */
+export function useFocusRing(options?: UseFocusRingOptions): FocusRingState {
+  ensureModalityListeners();
+  const [focused, setFocused] = useState(false);
+  const onFocus = useCallback(() => setFocused(true), []);
+  const onBlur = useCallback(() => setFocused(false), []);
+  const focusVisible = focused && (options?.always === true || lastModality === "keyboard");
+  return { focusVisible, focused, focusProps: { onFocus, onBlur } };
+}

package/src/use_hover.ts

@@ -0,0 +1,26 @@
+import { useCallback, useState } from "react";
+
+export interface HoverState {
+  hovered: boolean;
+  /**
+   * Spread onto the element (or its wrapping View). `onMouseEnter`/`onMouseLeave`
+   * are forwarded to the DOM by react-native-web on View/TextInput/etc.; on native
+   * they're ignored, so `hovered` stays false (no hover on touch — correct).
+   */
+  hoverProps: { onMouseEnter: () => void; onMouseLeave: () => void };
+}
+
+/**
+ * Pointer-hover state for a premium hover affordance (a border darken / shadow on
+ * bordered inputs, selects, and other interactive surfaces — signalling "this is
+ * interactive" the same way the focus ring signals "this is focused"). Mirrors
+ * `useFocusRing`. For `Pressable`-based controls prefer the built-in `hovered`
+ * style state; reach for this on TextInput / the native `<select>` / raw DOM inputs
+ * that don't expose it.
+ */
+export function useHover(): HoverState {
+  const [hovered, setHovered] = useState(false);
+  const onMouseEnter = useCallback(() => setHovered(true), []);
+  const onMouseLeave = useCallback(() => setHovered(false), []);
+  return { hovered, hoverProps: { onMouseEnter, onMouseLeave } };
+}

package/src/use_list_keyboard_nav.test.ts

@@ -26,6 +26,11 @@ describe("useListKeyboardNav", () => {
     expect(view.result.current.activeIndex).toBe(0);
   });
 
+  it("seats the initial active row at initialIndex", () => {
+    const { view } = setup({ initialIndex: 2 });
+    expect(view.result.current.activeIndex).toBe(2);
+  });
+
   it("ArrowDown / ArrowUp move within bounds and report handled", () => {
     const { view } = setup();
     let handled = false;
@@ -111,3 +116,69 @@ describe("useListKeyboardNav", () => {
     expect(onActiveChange).not.toHaveBeenCalled();
   });
 });
+
+describe("useListKeyboardNav typeahead", () => {
+  const labels = ["Apple", "Banana", "Blueberry", "Cherry"];
+  function setupTypeahead(overrides: Partial<ListKeyboardNavOptions> = {}) {
+    return setup({
+      count: labels.length,
+      typeahead: { labelAt: (i) => labels[i] },
+      ...overrides,
+    });
+  }
+
+  it("jumps to the first label-prefix match and reports the key handled", () => {
+    const { view } = setupTypeahead();
+    let handled = false;
+    act(() => {
+      handled = view.result.current.handleKey("c");
+    });
+    expect(handled).toBe(true);
+    expect(view.result.current.activeIndex).toBe(3); // Cherry
+  });
+
+  it("accumulates the buffer while typing", () => {
+    vi.useFakeTimers();
+    try {
+      const { view } = setupTypeahead();
+      act(() => void view.result.current.handleKey("b")); // "b" → Banana
+      expect(view.result.current.activeIndex).toBe(1);
+      act(() => void view.result.current.handleKey("l")); // "bl" → Blueberry
+      expect(view.result.current.activeIndex).toBe(2);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("resets the buffer after the idle timeout", () => {
+    vi.useFakeTimers();
+    try {
+      const { view } = setupTypeahead();
+      act(() => void view.result.current.handleKey("b")); // "b" → Banana
+      expect(view.result.current.activeIndex).toBe(1);
+      act(() => {
+        vi.advanceTimersByTime(700);
+      });
+      act(() => void view.result.current.handleKey("c")); // fresh "c" → Cherry, not "bc"
+      expect(view.result.current.activeIndex).toBe(3);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("skips disabled rows when jumping", () => {
+    const { view } = setupTypeahead({ isDisabled: (i) => i === 1 }); // Banana disabled
+    act(() => void view.result.current.handleKey("b"));
+    expect(view.result.current.activeIndex).toBe(2); // Blueberry, the first enabled b*
+  });
+
+  it("without a typeahead option, a printable key is not handled and does not move the row", () => {
+    const { view } = setup(); // no typeahead
+    let handled = true;
+    act(() => {
+      handled = view.result.current.handleKey("b");
+    });
+    expect(handled).toBe(false);
+    expect(view.result.current.activeIndex).toBe(0);
+  });
+});

package/src/use_list_keyboard_nav.ts

@@ -1,4 +1,4 @@
-import { useCallback, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 
 export interface ListKeyboardNavOptions {
   /** Number of rows in the list. */
@@ -11,6 +11,21 @@ export interface ListKeyboardNavOptions {
   onClose?: () => void;
   /** Fires when the active row changes — use it to scroll the row into view. */
   onActiveChange?: (index: number) => void;
+  /** The row active on first render (default 0). Read once — seat the initial
+   *  highlight here instead of via a post-mount effect, so an open list shows the
+   *  right row with no flash. */
+  initialIndex?: number;
+  /** Opt-in native-`<select>`-style typeahead: a printable key jumps the active
+   *  row to the first enabled label that starts with the typed buffer (the buffer
+   *  accumulates as you keep typing, then resets after `timeoutMs` of inactivity).
+   *  Absent ⇒ printable keys are reported NOT handled, so a list driven by a real
+   *  search field lets those keys flow to the input instead of jumping rows. */
+  typeahead?: {
+    /** The label to match for row `index` (undefined ⇒ the row is skipped). */
+    labelAt: (index: number) => string | undefined;
+    /** Idle window before the buffer resets, in ms. Default 600 (native parity). */
+    timeoutMs?: number;
+  };
 }
 
 export interface ListKeyboardNav {
@@ -33,8 +48,18 @@ export interface ListKeyboardNav {
  * 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 { count, isDisabled, onSelect, onClose, onActiveChange, typeahead, initialIndex } = opts;
+  const [activeIndex, setActiveIndexState] = useState(() => initialIndex ?? 0);
+  // Typeahead buffer + its idle-reset timer. Refs so they survive renders and the
+  // handler stays referentially stable; the timer is cleared on unmount.
+  const typeaheadBufferRef = useRef("");
+  const typeaheadTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  useEffect(
+    () => () => {
+      if (typeaheadTimerRef.current) clearTimeout(typeaheadTimerRef.current);
+    },
+    [],
+  );
 
   const setActiveIndex = useCallback(
     (index: number, scrollIntoView = true) => {
@@ -86,11 +111,33 @@ export function useListKeyboardNav(opts: ListKeyboardNavOptions): ListKeyboardNa
           // Let focus move on, but dismiss the list.
           onClose?.();
           return false;
-        default:
+        default: {
+          // Native-select typeahead — only when opted in. A printable key
+          // (single character) extends the buffer and jumps to the first enabled
+          // label that starts with it; otherwise the key isn't ours (a real
+          // search field, if any, consumes it).
+          if (typeahead && key.length === 1) {
+            if (typeaheadTimerRef.current) clearTimeout(typeaheadTimerRef.current);
+            typeaheadBufferRef.current += key.toLowerCase();
+            const buffer = typeaheadBufferRef.current;
+            for (let i = 0; i < count; i++) {
+              if (!enabled(i)) continue;
+              const label = typeahead.labelAt(i);
+              if (label && label.toLowerCase().startsWith(buffer)) {
+                setActiveIndex(i);
+                break;
+              }
+            }
+            typeaheadTimerRef.current = setTimeout(() => {
+              typeaheadBufferRef.current = "";
+            }, typeahead.timeoutMs ?? 600);
+            return true;
+          }
           return false;
+        }
       }
     },
-    [activeIndex, count, isDisabled, onSelect, onClose, setActiveIndex],
+    [activeIndex, count, isDisabled, onSelect, onClose, setActiveIndex, typeahead],
   );
 
   return { activeIndex, setActiveIndex, handleKey };