@lotics/ui 5.9.0 → 5.10.1

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/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 };

package/src/use_option_list.test.ts

@@ -0,0 +1,193 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi } from "vitest";
+import { act, renderHook } from "@testing-library/react";
+import { useOptionList, type UseOptionListParams } from "./use_option_list";
+
+const OPTS = [
+  { value: "a", label: "Apple" },
+  { value: "b", label: "Banana" },
+  { value: "c", label: "Cherry" },
+];
+
+function setupSingle(overrides: Partial<UseOptionListParams<string, false>> = {}) {
+  const onValueChange = vi.fn();
+  const onRequestClose = vi.fn();
+  const onCustomCommit = vi.fn();
+  const params: UseOptionListParams<string, false> = {
+    options: OPTS,
+    search: { mode: "none" },
+    onValueChange,
+    onRequestClose,
+    onCustomCommit,
+    ...overrides,
+  };
+  const view = renderHook((p: UseOptionListParams<string, false>) => useOptionList(p), {
+    initialProps: params,
+  });
+  return { view, onValueChange, onRequestClose, onCustomCommit };
+}
+
+function setupMulti(overrides: Partial<UseOptionListParams<string, true>> = {}) {
+  const onValueChange = vi.fn();
+  const onRequestClose = vi.fn();
+  const params: UseOptionListParams<string, true> = {
+    options: OPTS,
+    multi: true,
+    search: { mode: "none" },
+    onValueChange,
+    onRequestClose,
+    ...overrides,
+  };
+  const view = renderHook((p: UseOptionListParams<string, true>) => useOptionList(p), {
+    initialProps: params,
+  });
+  return { view, onValueChange, onRequestClose };
+}
+
+describe("useOptionList", () => {
+  it("none mode lists every option and seats the active row on the first one", () => {
+    const { view } = setupSingle();
+    const { rows, activeIndex } = view.result.current;
+    expect(rows.map((r) => r.option.value)).toEqual(["a", "b", "c"]);
+    expect(rows.every((r) => r.kind === "option")).toBe(true);
+    expect(activeIndex).toBe(0);
+  });
+
+  it("none mode seats the active row on the selected option", () => {
+    const { view } = setupSingle({ value: "c" });
+    expect(view.result.current.activeIndex).toBe(2);
+    expect(view.result.current.rows[2].selected).toBe(true);
+  });
+
+  it("single pick emits the value and requests close", () => {
+    const { view, onValueChange, onRequestClose } = setupSingle();
+    act(() => view.result.current.pickRow(1));
+    expect(onValueChange).toHaveBeenCalledWith("b");
+    expect(onRequestClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("multi pick toggles the value and stays open", () => {
+    const { view, onValueChange, onRequestClose } = setupMulti({ value: [] });
+    act(() => view.result.current.pickRow(0));
+    expect(onValueChange).toHaveBeenCalledWith(["a"]);
+    expect(onRequestClose).not.toHaveBeenCalled();
+  });
+
+  it("multi pick removes an already-selected value", () => {
+    const { view, onValueChange } = setupMulti({ value: ["a", "b"] });
+    act(() => view.result.current.pickRow(0)); // toggle off "a"
+    expect(onValueChange).toHaveBeenCalledWith(["b"]);
+  });
+
+  it("internal search filters the rows locally", () => {
+    const { view } = setupSingle({ search: { mode: "internal" } });
+    act(() => view.result.current.setQuery("ap"));
+    expect(view.result.current.rows.map((r) => r.option.value)).toEqual(["a"]);
+    expect(view.result.current.searching).toBe(true);
+  });
+
+  it("allowCustom adds a create row for an unmatched query; picking it commits the raw query", () => {
+    const { view, onCustomCommit } = setupSingle({
+      search: { mode: "internal" },
+      allowCustom: true,
+    });
+    act(() => view.result.current.setQuery("kiwi"));
+    const rows = view.result.current.rows;
+    const custom = rows.find((r) => r.kind === "custom");
+    expect(custom).toBeTruthy();
+    expect(custom?.option.label).toBe('Add "kiwi"');
+    act(() => view.result.current.pickRow(custom!.index));
+    expect(onCustomCommit).toHaveBeenCalledWith("kiwi");
+  });
+
+  it("keeps the active row on the first match, never the create row (placement top)", () => {
+    const { view } = setupSingle({
+      search: { mode: "internal" },
+      allowCustom: true,
+      customOptionPlacement: "top",
+    });
+    act(() => view.result.current.setQuery("ap")); // create row + the Apple match
+    const rows = view.result.current.rows;
+    expect(rows[0].kind).toBe("custom");
+    expect(rows[view.result.current.activeIndex].kind).toBe("option");
+  });
+
+  it("includeEmptyOption prepends a clear row that empties the value", () => {
+    const { view, onValueChange, onRequestClose } = setupSingle({
+      value: "a",
+      includeEmptyOption: true,
+    });
+    expect(view.result.current.rows[0].kind).toBe("empty");
+    act(() => view.result.current.pickRow(0));
+    expect(onValueChange).toHaveBeenCalledWith("");
+    expect(onRequestClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("select-all / deselect-all emit the full set and the empty set", () => {
+    const { view, onValueChange } = setupMulti({ value: ["a"], enableSelectAll: true });
+    expect(view.result.current.showSelectAll).toBe(true);
+    expect(view.result.current.showDeselectAll).toBe(true);
+    act(() => view.result.current.selectAll());
+    expect(onValueChange).toHaveBeenCalledWith(["a", "b", "c"]);
+    act(() => view.result.current.deselectAll());
+    expect(onValueChange).toHaveBeenLastCalledWith([]);
+  });
+
+  it("a none-mode multi toggle keeps the active row where it is (no re-seat on selection)", () => {
+    const onValueChange = vi.fn();
+    const params: UseOptionListParams<string, true> = {
+      options: OPTS,
+      multi: true,
+      search: { mode: "none" },
+      value: ["a"],
+      onValueChange,
+    };
+    const view = renderHook((p: UseOptionListParams<string, true>) => useOptionList(p), {
+      initialProps: params,
+    });
+    act(() => view.result.current.setActiveIndex(2)); // arrow down to "c"
+    act(() => view.result.current.pickRow(2)); // toggle "c" on, popover stays open
+    expect(onValueChange).toHaveBeenCalledWith(["a", "c"]);
+    view.rerender({ ...params, value: ["a", "c"] }); // consumer applies the new value
+    // Regression: must NOT jump back to the first selected option.
+    expect(view.result.current.activeIndex).toBe(2);
+  });
+
+  it("re-seats the active row to the first match when the search query changes", () => {
+    const view = renderHook((p: UseOptionListParams<string, false>) => useOptionList(p), {
+      initialProps: { options: OPTS, search: { mode: "internal" }, onValueChange: vi.fn() },
+    });
+    act(() => view.result.current.setActiveIndex(2));
+    expect(view.result.current.activeIndex).toBe(2);
+    act(() => view.result.current.setQuery("ban")); // filters to "Banana"
+    expect(view.result.current.rows.map((r) => r.option.value)).toEqual(["b"]);
+    expect(view.result.current.activeIndex).toBe(0);
+  });
+
+  it("matches options accent-insensitively (cafe -> Café, dieu -> Điều)", () => {
+    const view = renderHook((p: UseOptionListParams<string, false>) => useOptionList(p), {
+      initialProps: {
+        options: [
+          { value: "cf", label: "Café" },
+          { value: "dd", label: "Điều độ" },
+          { value: "x", label: "Other" },
+        ],
+        search: { mode: "internal" },
+        onValueChange: vi.fn(),
+      },
+    });
+    act(() => view.result.current.setQuery("dieu"));
+    expect(view.result.current.rows.map((r) => r.option.value)).toEqual(["dd"]);
+    act(() => view.result.current.setQuery("cafe"));
+    expect(view.result.current.rows.map((r) => r.option.value)).toEqual(["cf"]);
+  });
+
+  it("controlled server-filtered mode shows options as-is (no local re-filter)", () => {
+    const { view } = setupSingle({
+      // The server already filtered to one result; the hook must not re-filter it out.
+      options: [{ value: "z", label: "Zucchini" }],
+      search: { mode: "controlled", query: "xyz", serverFiltered: true },
+    });
+    expect(view.result.current.rows.map((r) => r.option.value)).toEqual(["z"]);
+  });
+});