From a3ce570e0adc3f194f3a33919c56e10def02b367 Mon Sep 17 00:00:00 2001
From: NnamdiCyber <ogazi133@gmail.com>
Date: Thu, 23 Jul 2026 22:09:14 +0100
Subject: [PATCH] feat: accessible search combobox
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Implements app/components/SearchInput.tsx following the WAI-ARIA 1.2
combobox pattern (§5.9) with full keyboard navigation.

ARIA wiring
- role=combobox on input; aria-expanded, aria-haspopup=listbox,
  aria-autocomplete=list, aria-controls, aria-activedescendant
- role=option + aria-selected on each listbox item
- aria-live=polite status region announces result counts, loading,
  and empty states to screen-reader users
- Clear button has aria-label='Clear search' and is tab-accessible

Keyboard interaction
- ArrowDown / ArrowUp  navigate options with wrap-around
- Home / End           jump to first / last option
- Enter               confirm highlighted option or submit free-text
- Escape              close listbox; second press clears value
- Tab                 close listbox, natural focus flow

API
- Controlled (value + onChange) and uncontrolled modes
- suggestions[], onSelect, onSubmit, onOpen, onClose callbacks
- isLoading, disabled, maxSuggestions, aria-label, aria-labelledby props
- Design-system tokens (bg-popover, accent, border-input) with
  motion-safe: utilities for prefers-reduced-motion compliance

Tests (app/components/__tests__/SearchInput.test.tsx)
~50 focused cases covering ARIA wiring, all keyboard paths, click/hover,
clear button, loading/empty states, controlled vs uncontrolled, maxSuggestions,
disabled, live region, outside-click close, and a snapshot.

Docs: docs/SEARCH_INPUT.md — props table, keyboard table, usage examples,
comparison with the navbar-specific SearchInput.

Closes #477
---
 app/components/SearchInput.tsx                | 485 +++++++++++++++++
 app/components/__tests__/SearchInput.test.tsx | 514 ++++++++++++++++++
 docs/SEARCH_INPUT.md                          | 179 ++++++
 3 files changed, 1178 insertions(+)
 create mode 100644 app/components/SearchInput.tsx
 create mode 100644 app/components/__tests__/SearchInput.test.tsx
 create mode 100644 docs/SEARCH_INPUT.md

diff --git a/app/components/SearchInput.tsx b/app/components/SearchInput.tsx
new file mode 100644
index 00000000..3a764222
--- /dev/null
+++ b/app/components/SearchInput.tsx
@@ -0,0 +1,485 @@
+/**
+ * SearchInput
+ *
+ * An accessible search input that follows the ARIA combobox pattern (WAI-ARIA
+ * 1.2 §5.9).  Users can navigate suggestions with the arrow keys, select with
+ * Enter, and dismiss the listbox with Escape.
+ *
+ * Accessibility features
+ * ──────────────────────
+ * • Input carries role="combobox" with aria-expanded, aria-haspopup="listbox",
+ *   aria-autocomplete="list", and aria-controls pointing at the listbox.
+ * • aria-activedescendant tracks the keyboard-highlighted option.
+ * • Each option has role="option" and aria-selected.
+ * • The listbox label ("Search suggestions") is announced when it appears.
+ * • A live region announces result counts so screen-reader users know when
+ *   the list has changed.
+ * • The clear button is keyboard-reachable and has a descriptive aria-label.
+ * • Reduced-motion: the dropdown entrance animation respects
+ *   `prefers-reduced-motion: reduce`.
+ *
+ * Keyboard interaction
+ * ────────────────────
+ * ArrowDown   Move visual focus to the next option (wraps at end)
+ * ArrowUp     Move visual focus to the previous option (wraps at start)
+ * Home        Move to the first option
+ * End         Move to the last option
+ * Enter       Confirm the highlighted option (or submit raw query if none)
+ * Escape      Close the listbox and return focus to the input
+ * Tab         Close the listbox (natural focus movement)
+ */
+
+"use client";
+
+import React, {
+  useState,
+  useRef,
+  useId,
+  useMemo,
+  useCallback,
+  useEffect,
+} from "react";
+import { Search as SearchIcon, X as ClearIcon, Loader2 } from "lucide-react";
+import { cn } from "@/lib/utils";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/** A single suggestion item displayed in the listbox. */
+export interface SearchSuggestion {
+  /** Unique identifier for the item. */
+  id: string;
+  /** Primary label shown to the user. */
+  label: string;
+  /** Optional sub-label shown in a smaller font beneath the label. */
+  sublabel?: string;
+  /** Optional accessible icon rendered before the label (must carry aria-hidden). */
+  icon?: React.ReactNode;
+}
+
+export interface SearchInputProps {
+  /** Current value of the input (controlled). */
+  value?: string;
+  /** Called when the user changes the input value. */
+  onChange?: (value: string) => void;
+  /**
+   * Suggestions to display in the listbox.  The consumer is responsible for
+   * filtering / sorting; SearchInput renders whatever is provided.
+   */
+  suggestions?: SearchSuggestion[];
+  /**
+   * Called when the user confirms a suggestion (Enter key or click).
+   * Receives the confirmed suggestion object.
+   */
+  onSelect?: (suggestion: SearchSuggestion) => void;
+  /**
+   * Called when the user submits a free-text query (Enter with no suggestion
+   * highlighted, or Enter when suggestions is empty).
+   */
+  onSubmit?: (query: string) => void;
+  /** Called when the listbox opens. */
+  onOpen?: () => void;
+  /** Called when the listbox closes. */
+  onClose?: () => void;
+  /** Show a spinner inside the input to indicate loading. */
+  isLoading?: boolean;
+  /** Placeholder text for the input. */
+  placeholder?: string;
+  /** Additional class names for the outermost wrapper. */
+  className?: string;
+  /**
+   * Maximum number of suggestions to show.  Remaining items are hidden.
+   * @default 10
+   */
+  maxSuggestions?: number;
+  /** Whether the input should be disabled. */
+  disabled?: boolean;
+  /** id forwarded to the underlying <input>. Useful for <label htmlFor>. */
+  id?: string;
+  /** aria-label for the underlying <input>. */
+  "aria-label"?: string;
+  /** aria-labelledby for the underlying <input>. */
+  "aria-labelledby"?: string;
+}
+
+// ─── Component ────────────────────────────────────────────────────────────────
+
+/**
+ * Accessible search input with a combobox dropdown.
+ *
+ * @example
+ * ```tsx
+ * <SearchInput
+ *   value={query}
+ *   onChange={setQuery}
+ *   suggestions={filteredMarkets}
+ *   onSelect={(s) => router.push(`/events/${s.id}`)}
+ *   onSubmit={(q) => router.push(`/events?q=${q}`)}
+ *   placeholder="Search markets…"
+ * />
+ * ```
+ */
+export function SearchInput({
+  value: valueProp,
+  onChange,
+  suggestions = [],
+  onSelect,
+  onSubmit,
+  onOpen,
+  onClose,
+  isLoading = false,
+  placeholder = "Search…",
+  className,
+  maxSuggestions = 10,
+  disabled = false,
+  id,
+  "aria-label": ariaLabel,
+  "aria-labelledby": ariaLabelledBy,
+}: SearchInputProps) {
+  // ── Uncontrolled internal value when no `value` prop is supplied ──────────
+  const [internalValue, setInternalValue] = useState("");
+  const isControlled = valueProp !== undefined;
+  const value = isControlled ? valueProp : internalValue;
+
+  // ── Dropdown / selection state ─────────────────────────────────────────────
+  const [isOpen, setIsOpen] = useState(false);
+  const [activeIndex, setActiveIndex] = useState(-1);
+
+  // ── DOM refs ───────────────────────────────────────────────────────────────
+  const inputRef = useRef<HTMLInputElement>(null);
+  const listboxRef = useRef<HTMLUListElement>(null);
+  const wrapperRef = useRef<HTMLDivElement>(null);
+
+  // ── Stable IDs for ARIA wiring ─────────────────────────────────────────────
+  const uid = useId();
+  const listboxId = `${uid}-listbox`;
+  const liveId = `${uid}-live`;
+  const getOptionId = useCallback(
+    (index: number) => `${uid}-option-${index}`,
+    [uid],
+  );
+
+  // ── Visible suggestions (capped) ──────────────────────────────────────────
+  const visibleSuggestions = useMemo(
+    () => suggestions.slice(0, maxSuggestions),
+    [suggestions, maxSuggestions],
+  );
+
+  // ── Helpers ────────────────────────────────────────────────────────────────
+
+  const openDropdown = useCallback(() => {
+    setIsOpen(true);
+    onOpen?.();
+  }, [onOpen]);
+
+  const closeDropdown = useCallback(() => {
+    setIsOpen(false);
+    setActiveIndex(-1);
+    onClose?.();
+  }, [onClose]);
+
+  const commitValue = useCallback(
+    (newValue: string) => {
+      if (!isControlled) setInternalValue(newValue);
+      onChange?.(newValue);
+    },
+    [isControlled, onChange],
+  );
+
+  const handleClear = useCallback(() => {
+    commitValue("");
+    closeDropdown();
+    inputRef.current?.focus();
+  }, [commitValue, closeDropdown]);
+
+  // ── Close on outside click ─────────────────────────────────────────────────
+  useEffect(() => {
+    const handlePointerDown = (e: PointerEvent) => {
+      if (
+        wrapperRef.current &&
+        !wrapperRef.current.contains(e.target as Node)
+      ) {
+        closeDropdown();
+      }
+    };
+    document.addEventListener("pointerdown", handlePointerDown);
+    return () => document.removeEventListener("pointerdown", handlePointerDown);
+  }, [closeDropdown]);
+
+  // ── Scroll active option into view ────────────────────────────────────────
+  useEffect(() => {
+    if (activeIndex < 0 || !listboxRef.current) return;
+    const option = listboxRef.current.querySelector<HTMLLIElement>(
+      `[id="${getOptionId(activeIndex)}"]`,
+    );
+    option?.scrollIntoView({ block: "nearest" });
+  }, [activeIndex, getOptionId]);
+
+  // ── Event handlers ─────────────────────────────────────────────────────────
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const newVal = e.target.value;
+    commitValue(newVal);
+    setActiveIndex(-1);
+    if (newVal.trim() || visibleSuggestions.length > 0) {
+      openDropdown();
+    } else {
+      closeDropdown();
+    }
+  };
+
+  const handleFocus = () => {
+    if (visibleSuggestions.length > 0 || value.trim()) {
+      openDropdown();
+    }
+  };
+
+  const handleKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+    const last = visibleSuggestions.length - 1;
+
+    switch (e.key) {
+      case "ArrowDown":
+        e.preventDefault();
+        if (!isOpen) {
+          openDropdown();
+        }
+        setActiveIndex((prev) => (prev < last ? prev + 1 : 0));
+        break;
+
+      case "ArrowUp":
+        e.preventDefault();
+        if (!isOpen) {
+          openDropdown();
+        }
+        setActiveIndex((prev) => (prev > 0 ? prev - 1 : last));
+        break;
+
+      case "Home":
+        if (isOpen && visibleSuggestions.length > 0) {
+          e.preventDefault();
+          setActiveIndex(0);
+        }
+        break;
+
+      case "End":
+        if (isOpen && visibleSuggestions.length > 0) {
+          e.preventDefault();
+          setActiveIndex(last);
+        }
+        break;
+
+      case "Enter":
+        e.preventDefault();
+        if (isOpen && activeIndex >= 0 && activeIndex <= last) {
+          const selected = visibleSuggestions[activeIndex];
+          onSelect?.(selected);
+          commitValue(selected.label);
+          closeDropdown();
+        } else {
+          const trimmed = value.trim();
+          if (trimmed) {
+            onSubmit?.(trimmed);
+            closeDropdown();
+          }
+        }
+        break;
+
+      case "Escape":
+        e.preventDefault();
+        if (isOpen) {
+          closeDropdown();
+        } else {
+          commitValue("");
+        }
+        inputRef.current?.focus();
+        break;
+
+      case "Tab":
+        // Let Tab close the dropdown naturally without preventing default so
+        // focus can move to the next element in the page.
+        closeDropdown();
+        break;
+    }
+  };
+
+  const handleOptionClick = (suggestion: SearchSuggestion) => {
+    onSelect?.(suggestion);
+    commitValue(suggestion.label);
+    closeDropdown();
+    inputRef.current?.focus();
+  };
+
+  const handleOptionPointerEnter = (index: number) => {
+    setActiveIndex(index);
+  };
+
+  // ── Derived values for ARIA ────────────────────────────────────────────────
+  const activeDescendant =
+    isOpen && activeIndex >= 0 ? getOptionId(activeIndex) : undefined;
+
+  const liveMessage = (() => {
+    if (!isOpen) return "";
+    if (isLoading) return "Searching…";
+    if (visibleSuggestions.length === 0 && value.trim())
+      return "No results found.";
+    if (visibleSuggestions.length > 0)
+      return `${visibleSuggestions.length} suggestion${visibleSuggestions.length !== 1 ? "s" : ""} available. Use arrow keys to navigate.`;
+    return "";
+  })();
+
+  // ── Render ─────────────────────────────────────────────────────────────────
+
+  return (
+    <div ref={wrapperRef} className={cn("relative w-full", className)}>
+      {/* ── Screen-reader live region ── */}
+      <div
+        id={liveId}
+        role="status"
+        aria-live="polite"
+        aria-atomic="true"
+        className="sr-only"
+      >
+        {liveMessage}
+      </div>
+
+      {/* ── Input wrapper ── */}
+      <div className="relative flex items-center">
+        {/* Leading search icon */}
+        <SearchIcon
+          className="pointer-events-none absolute left-3 h-4 w-4 shrink-0 text-muted-foreground"
+          aria-hidden="true"
+        />
+
+        <input
+          ref={inputRef}
+          id={id}
+          role="combobox"
+          aria-expanded={isOpen}
+          aria-haspopup="listbox"
+          aria-autocomplete="list"
+          aria-controls={listboxId}
+          aria-activedescendant={activeDescendant}
+          aria-label={ariaLabel ?? (!ariaLabelledBy ? placeholder : undefined)}
+          aria-labelledby={ariaLabelledBy}
+          aria-busy={isLoading}
+          aria-disabled={disabled}
+          autoComplete="off"
+          spellCheck={false}
+          disabled={disabled}
+          value={value}
+          onChange={handleChange}
+          onFocus={handleFocus}
+          onKeyDown={handleKeyDown}
+          placeholder={placeholder}
+          className={cn(
+            "h-10 w-full rounded-md border border-input bg-background py-2 pl-9 pr-9 text-sm",
+            "text-foreground placeholder:text-muted-foreground",
+            "ring-offset-background",
+            "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+            "disabled:cursor-not-allowed disabled:opacity-50",
+            isLoading && "pr-16",
+          )}
+        />
+
+        {/* Trailing: spinner or clear button */}
+        <div className="absolute right-3 flex items-center gap-1">
+          {isLoading ? (
+            <Loader2
+              className="h-4 w-4 animate-spin text-muted-foreground"
+              aria-hidden="true"
+            />
+          ) : value ? (
+            <button
+              type="button"
+              onClick={handleClear}
+              aria-label="Clear search"
+              tabIndex={0}
+              className={cn(
+                "rounded-sm text-muted-foreground",
+                "hover:text-foreground",
+                "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1",
+                "transition-colors",
+              )}
+            >
+              <ClearIcon className="h-4 w-4" aria-hidden="true" />
+            </button>
+          ) : null}
+        </div>
+      </div>
+
+      {/* ── Listbox dropdown ── */}
+      {isOpen && (
+        <ul
+          ref={listboxRef}
+          id={listboxId}
+          role="listbox"
+          aria-label="Search suggestions"
+          className={cn(
+            "absolute top-full z-50 mt-1 max-h-64 w-full overflow-y-auto overscroll-contain",
+            "rounded-md border border-border bg-popover shadow-md",
+            "motion-safe:animate-in motion-safe:fade-in-0 motion-safe:zoom-in-95",
+            "focus:outline-none",
+          )}
+        >
+          {isLoading ? (
+            <li
+              role="option"
+              aria-selected="false"
+              aria-disabled="true"
+              className="flex cursor-default items-center gap-2 px-3 py-3 text-sm text-muted-foreground"
+            >
+              <Loader2 className="h-4 w-4 animate-spin" aria-hidden="true" />
+              Searching…
+            </li>
+          ) : visibleSuggestions.length === 0 ? (
+            <li
+              role="option"
+              aria-selected="false"
+              aria-disabled="true"
+              className="cursor-default px-3 py-3 text-sm text-muted-foreground"
+            >
+              No results found.
+            </li>
+          ) : (
+            visibleSuggestions.map((suggestion, index) => {
+              const isActive = index === activeIndex;
+
+              return (
+                <li
+                  key={suggestion.id}
+                  id={getOptionId(index)}
+                  role="option"
+                  aria-selected={isActive}
+                  onPointerEnter={() => handleOptionPointerEnter(index)}
+                  onClick={() => handleOptionClick(suggestion)}
+                  className={cn(
+                    "flex cursor-pointer select-none items-center gap-2.5 px-3 py-2.5 text-sm",
+                    "text-popover-foreground outline-none transition-colors",
+                    isActive
+                      ? "bg-accent text-accent-foreground"
+                      : "hover:bg-accent/60",
+                  )}
+                >
+                  {suggestion.icon && (
+                    <span className="shrink-0" aria-hidden="true">
+                      {suggestion.icon}
+                    </span>
+                  )}
+                  <span className="flex flex-col overflow-hidden">
+                    <span className="truncate font-medium">
+                      {suggestion.label}
+                    </span>
+                    {suggestion.sublabel && (
+                      <span className="truncate text-xs text-muted-foreground">
+                        {suggestion.sublabel}
+                      </span>
+                    )}
+                  </span>
+                </li>
+              );
+            })
+          )}
+        </ul>
+      )}
+    </div>
+  );
+}
diff --git a/app/components/__tests__/SearchInput.test.tsx b/app/components/__tests__/SearchInput.test.tsx
new file mode 100644
index 00000000..8a37aada
--- /dev/null
+++ b/app/components/__tests__/SearchInput.test.tsx
@@ -0,0 +1,514 @@
+/**
+ * SearchInput — focused test suite
+ *
+ * Covers:
+ *  • ARIA combobox wiring (role, aria-expanded, aria-haspopup, aria-controls,
+ *    aria-activedescendant, aria-autocomplete)
+ *  • Keyboard navigation: ArrowDown, ArrowUp, Home, End, Enter, Escape, Tab
+ *  • Option selection via click and Enter
+ *  • Free-text submit when no option is highlighted
+ *  • Clear button (keyboard + mouse)
+ *  • isLoading prop
+ *  • Controlled vs uncontrolled value
+ *  • maxSuggestions cap
+ *  • disabled state
+ *  • Screen-reader live region messages
+ *  • Outside-click closes the dropdown
+ */
+
+import React, { useState } from "react"
+import {
+  render,
+  screen,
+  fireEvent,
+  waitFor,
+  within,
+} from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { SearchInput, SearchSuggestion } from "../SearchInput"
+
+// ─── Fixture data ──────────────────────────────────────────────────────────
+
+const suggestions: SearchSuggestion[] = [
+  { id: "1", label: "Bitcoin price 2025", sublabel: "Crypto" },
+  { id: "2", label: "FIFA World Cup winner", sublabel: "Football" },
+  { id: "3", label: "US Election outcome", sublabel: "Politics" },
+  { id: "4", label: "Tesla stock Q4", sublabel: "Stocks" },
+  { id: "5", label: "Ethereum merge success", sublabel: "Crypto" },
+]
+
+// ─── Helpers ───────────────────────────────────────────────────────────────
+
+/** Render with standard suggestions. */
+function renderInput(props: Partial<React.ComponentProps<typeof SearchInput>> = {}) {
+  const onSelect = props.onSelect ?? jest.fn()
+  const onSubmit = props.onSubmit ?? jest.fn()
+  const result = render(
+    <SearchInput
+      suggestions={suggestions}
+      onSelect={onSelect}
+      onSubmit={onSubmit}
+      placeholder="Search markets"
+      {...props}
+    />
+  )
+  const input = screen.getByRole("combobox")
+  return { ...result, input, onSelect, onSubmit }
+}
+
+// ─── ARIA wiring ───────────────────────────────────────────────────────────
+
+describe("ARIA combobox wiring", () => {
+  it("has role=combobox on the input", () => {
+    renderInput()
+    expect(screen.getByRole("combobox")).toBeInTheDocument()
+  })
+
+  it("has aria-haspopup=listbox", () => {
+    renderInput()
+    expect(screen.getByRole("combobox")).toHaveAttribute("aria-haspopup", "listbox")
+  })
+
+  it("has aria-autocomplete=list", () => {
+    renderInput()
+    expect(screen.getByRole("combobox")).toHaveAttribute("aria-autocomplete", "list")
+  })
+
+  it("aria-expanded is false when closed", () => {
+    renderInput()
+    expect(screen.getByRole("combobox")).toHaveAttribute("aria-expanded", "false")
+  })
+
+  it("aria-expanded is true after ArrowDown opens the listbox", async () => {
+    const { input } = renderInput()
+    await userEvent.type(input, "bit")
+    await waitFor(() =>
+      expect(screen.getByRole("combobox")).toHaveAttribute("aria-expanded", "true")
+    )
+  })
+
+  it("aria-controls points to the listbox id", async () => {
+    const { input } = renderInput()
+    await userEvent.type(input, "bit")
+    const combobox = screen.getByRole("combobox")
+    const listboxId = combobox.getAttribute("aria-controls")!
+    expect(listboxId).toBeTruthy()
+    await waitFor(() =>
+      expect(document.getElementById(listboxId)).toHaveAttribute("role", "listbox")
+    )
+  })
+
+  it("uses the placeholder as aria-label when no aria-label prop is given", () => {
+    renderInput({ placeholder: "Find a market" })
+    expect(screen.getByRole("combobox")).toHaveAttribute("aria-label", "Find a market")
+  })
+
+  it("accepts a custom aria-label that overrides the placeholder", () => {
+    renderInput({ "aria-label": "Market search", placeholder: "Find a market" })
+    expect(screen.getByRole("combobox")).toHaveAttribute("aria-label", "Market search")
+  })
+
+  it("options have role=option and aria-selected", async () => {
+    const { input } = renderInput()
+    await userEvent.type(input, "bit")
+    await waitFor(() => {
+      const options = screen.getAllByRole("option")
+      options
+        .filter((o) => !o.getAttribute("aria-disabled"))
+        .forEach((opt) => expect(opt).toHaveAttribute("aria-selected"))
+    })
+  })
+
+  it("listbox has an accessible label", async () => {
+    const { input } = renderInput()
+    await userEvent.type(input, "bit")
+    await waitFor(() =>
+      expect(screen.getByRole("listbox")).toHaveAttribute(
+        "aria-label",
+        "Search suggestions"
+      )
+    )
+  })
+})
+
+// ─── Keyboard — ArrowDown / ArrowUp ────────────────────────────────────────
+
+describe("keyboard: ArrowDown / ArrowUp navigation", () => {
+  it("ArrowDown highlights the first option", async () => {
+    const { input } = renderInput()
+    await userEvent.type(input, "bit")
+    await waitFor(() => screen.getByRole("listbox"))
+    await userEvent.keyboard("{ArrowDown}")
+    const activeId = screen.getByRole("combobox").getAttribute("aria-activedescendant")
+    expect(activeId).toBeTruthy()
+    expect(document.getElementById(activeId!)).toBeInTheDocument()
+  })
+
+  it("ArrowDown advances through options", async () => {
+    const { input } = renderInput()
+    await userEvent.type(input, "bit")
+    await waitFor(() => screen.getByRole("listbox"))
+    await userEvent.keyboard("{ArrowDown}{ArrowDown}")
+    const options = screen.getAllByRole("option").filter((o) => !o.getAttribute("aria-disabled"))
+    expect(options[1]).toHaveAttribute("aria-selected", "true")
+  })
+
+  it("ArrowDown wraps from last to first option", async () => {
+    const { input } = renderInput()
+    await userEvent.type(input, "bit")
+    await waitFor(() => screen.getByRole("listbox"))
+    const options = screen.getAllByRole("option").filter((o) => !o.getAttribute("aria-disabled"))
+    const count = options.length
+    // Press ArrowDown count times to reach end, then one more to wrap
+    for (let i = 0; i <= count; i++) {
+      await userEvent.keyboard("{ArrowDown}")
+    }
+    expect(options[0]).toHaveAttribute("aria-selected", "true")
+  })
+
+  it("ArrowUp wraps from first to last option", async () => {
+    const { input } = renderInput()
+    await userEvent.type(input, "bit")
+    await waitFor(() => screen.getByRole("listbox"))
+    const options = screen.getAllByRole("option").filter((o) => !o.getAttribute("aria-disabled"))
+    // ArrowDown to first, then ArrowUp to wrap to last
+    await userEvent.keyboard("{ArrowDown}{ArrowUp}")
+    expect(options[options.length - 1]).toHaveAttribute("aria-selected", "true")
+  })
+
+  it("ArrowUp moves to previous option", async () => {
+    const { input } = renderInput()
+    await userEvent.type(input, "bit")
+    await waitFor(() => screen.getByRole("listbox"))
+    await userEvent.keyboard("{ArrowDown}{ArrowDown}{ArrowUp}")
+    const options = screen.getAllByRole("option").filter((o) => !o.getAttribute("aria-disabled"))
+    expect(options[0]).toHaveAttribute("aria-selected", "true")
+  })
+})
+
+// ─── Keyboard — Home / End ─────────────────────────────────────────────────
+
+describe("keyboard: Home / End navigation", () => {
+  it("Home moves to the first option", async () => {
+    const { input } = renderInput()
+    await userEvent.type(input, "bit")
+    await waitFor(() => screen.getByRole("listbox"))
+    await userEvent.keyboard("{ArrowDown}{ArrowDown}{Home}")
+    const options = screen.getAllByRole("option").filter((o) => !o.getAttribute("aria-disabled"))
+    expect(options[0]).toHaveAttribute("aria-selected", "true")
+  })
+
+  it("End moves to the last option", async () => {
+    const { input } = renderInput()
+    await userEvent.type(input, "bit")
+    await waitFor(() => screen.getByRole("listbox"))
+    await userEvent.keyboard("{End}")
+    const options = screen.getAllByRole("option").filter((o) => !o.getAttribute("aria-disabled"))
+    expect(options[options.length - 1]).toHaveAttribute("aria-selected", "true")
+  })
+})
+
+// ─── Keyboard — Enter ──────────────────────────────────────────────────────
+
+describe("keyboard: Enter to select / submit", () => {
+  it("Enter on a highlighted option calls onSelect with that suggestion", async () => {
+    const onSelect = jest.fn()
+    const { input } = renderInput({ onSelect })
+    await userEvent.type(input, "bit")
+    await waitFor(() => screen.getByRole("listbox"))
+    await userEvent.keyboard("{ArrowDown}{Enter}")
+    expect(onSelect).toHaveBeenCalledTimes(1)
+    expect(onSelect).toHaveBeenCalledWith(
+      expect.objectContaining({ id: expect.any(String), label: expect.any(String) })
+    )
+  })
+
+  it("Enter without a highlighted option calls onSubmit with the query", async () => {
+    const onSubmit = jest.fn()
+    const { input } = renderInput({ onSubmit, suggestions: [] })
+    await userEvent.type(input, "some query")
+    await userEvent.keyboard("{Enter}")
+    expect(onSubmit).toHaveBeenCalledWith("some query")
+  })
+
+  it("Enter on highlighted option closes the listbox", async () => {
+    const { input } = renderInput()
+    await userEvent.type(input, "bit")
+    await waitFor(() => screen.getByRole("listbox"))
+    await userEvent.keyboard("{ArrowDown}{Enter}")
+    await waitFor(() =>
+      expect(screen.queryByRole("listbox")).not.toBeInTheDocument()
+    )
+  })
+})
+
+// ─── Keyboard — Escape ────────────────────────────────────────────────────
+
+describe("keyboard: Escape", () => {
+  it("Escape closes the listbox when open", async () => {
+    const { input } = renderInput()
+    await userEvent.type(input, "bit")
+    await waitFor(() => screen.getByRole("listbox"))
+    await userEvent.keyboard("{Escape}")
+    await waitFor(() =>
+      expect(screen.queryByRole("listbox")).not.toBeInTheDocument()
+    )
+  })
+
+  it("Escape clears the value when the listbox is already closed", async () => {
+    const { input } = renderInput()
+    await userEvent.type(input, "bit")
+    await waitFor(() => screen.getByRole("listbox"))
+    // Close first
+    await userEvent.keyboard("{Escape}")
+    await waitFor(() => expect(screen.queryByRole("listbox")).not.toBeInTheDocument())
+    // Now clear
+    await userEvent.keyboard("{Escape}")
+    expect(input).toHaveValue("")
+  })
+
+  it("Escape does not steal focus from the input", async () => {
+    const { input } = renderInput()
+    await userEvent.type(input, "bit")
+    await userEvent.keyboard("{Escape}")
+    expect(document.activeElement).toBe(input)
+  })
+})
+
+// ─── Keyboard — Tab ───────────────────────────────────────────────────────
+
+describe("keyboard: Tab closes the listbox", () => {
+  it("Tab closes the listbox", async () => {
+    const { input } = renderInput()
+    await userEvent.type(input, "bit")
+    await waitFor(() => screen.getByRole("listbox"))
+    await userEvent.tab()
+    await waitFor(() =>
+      expect(screen.queryByRole("listbox")).not.toBeInTheDocument()
+    )
+  })
+})
+
+// ─── Mouse / pointer interaction ─────────────────────────────────────────
+
+describe("mouse interaction", () => {
+  it("clicking an option calls onSelect", async () => {
+    const onSelect = jest.fn()
+    const { input } = renderInput({ onSelect })
+    await userEvent.type(input, "bit")
+    await waitFor(() => screen.getByRole("listbox"))
+    const options = screen.getAllByRole("option").filter((o) => !o.getAttribute("aria-disabled"))
+    await userEvent.click(options[0])
+    expect(onSelect).toHaveBeenCalledTimes(1)
+  })
+
+  it("clicking an option closes the listbox", async () => {
+    const { input } = renderInput()
+    await userEvent.type(input, "bit")
+    await waitFor(() => screen.getByRole("listbox"))
+    const options = screen.getAllByRole("option").filter((o) => !o.getAttribute("aria-disabled"))
+    await userEvent.click(options[0])
+    await waitFor(() =>
+      expect(screen.queryByRole("listbox")).not.toBeInTheDocument()
+    )
+  })
+
+  it("hovering an option updates aria-activedescendant", async () => {
+    const { input } = renderInput()
+    await userEvent.type(input, "bit")
+    await waitFor(() => screen.getByRole("listbox"))
+    const options = screen.getAllByRole("option").filter((o) => !o.getAttribute("aria-disabled"))
+    fireEvent.pointerEnter(options[1])
+    expect(options[1]).toHaveAttribute("aria-selected", "true")
+  })
+
+  it("clicking outside the component closes the listbox", async () => {
+    const { input } = renderInput()
+    await userEvent.type(input, "bit")
+    await waitFor(() => screen.getByRole("listbox"))
+    fireEvent.pointerDown(document.body)
+    await waitFor(() =>
+      expect(screen.queryByRole("listbox")).not.toBeInTheDocument()
+    )
+  })
+})
+
+// ─── Clear button ─────────────────────────────────────────────────────────
+
+describe("clear button", () => {
+  it("shows a clear button when the input has a value", async () => {
+    const { input } = renderInput()
+    await userEvent.type(input, "hello")
+    expect(screen.getByRole("button", { name: /clear search/i })).toBeInTheDocument()
+  })
+
+  it("does not show a clear button when the input is empty", () => {
+    renderInput()
+    expect(screen.queryByRole("button", { name: /clear search/i })).not.toBeInTheDocument()
+  })
+
+  it("clicking clear resets the value", async () => {
+    const { input } = renderInput()
+    await userEvent.type(input, "hello")
+    await userEvent.click(screen.getByRole("button", { name: /clear search/i }))
+    expect(input).toHaveValue("")
+  })
+
+  it("clicking clear closes the listbox", async () => {
+    const { input } = renderInput()
+    await userEvent.type(input, "bit")
+    await waitFor(() => screen.getByRole("listbox"))
+    await userEvent.click(screen.getByRole("button", { name: /clear search/i }))
+    await waitFor(() =>
+      expect(screen.queryByRole("listbox")).not.toBeInTheDocument()
+    )
+  })
+
+  it("clicking clear returns focus to the input", async () => {
+    const { input } = renderInput()
+    await userEvent.type(input, "hello")
+    await userEvent.click(screen.getByRole("button", { name: /clear search/i }))
+    expect(document.activeElement).toBe(input)
+  })
+})
+
+// ─── isLoading ────────────────────────────────────────────────────────────
+
+describe("isLoading prop", () => {
+  it("shows a spinner when isLoading is true and the listbox is open", async () => {
+    const { input } = renderInput({ isLoading: true })
+    await userEvent.type(input, "bit")
+    await waitFor(() => screen.getByRole("listbox"))
+    // Spinner li carries aria-disabled=true and contains "Searching"
+    const loadingOption = screen.getByRole("option", { name: /searching/i })
+    expect(loadingOption).toBeInTheDocument()
+  })
+
+  it("sets aria-busy on the input when loading", () => {
+    renderInput({ isLoading: true })
+    expect(screen.getByRole("combobox")).toHaveAttribute("aria-busy", "true")
+  })
+})
+
+// ─── No results ───────────────────────────────────────────────────────────
+
+describe("no results state", () => {
+  it("shows 'No results found' when suggestions are empty and query is non-empty", async () => {
+    const { input } = renderInput({ suggestions: [] })
+    await userEvent.type(input, "xyz123")
+    await waitFor(() => {
+      expect(screen.getByRole("option", { name: /no results found/i })).toBeInTheDocument()
+    })
+  })
+})
+
+// ─── Controlled value ─────────────────────────────────────────────────────
+
+describe("controlled value", () => {
+  it("displays the externally controlled value", () => {
+    render(
+      <SearchInput
+        value="external"
+        onChange={jest.fn()}
+        suggestions={suggestions}
+        placeholder="Search"
+      />
+    )
+    expect(screen.getByRole("combobox")).toHaveValue("external")
+  })
+
+  it("calls onChange when the user types", async () => {
+    const onChange = jest.fn()
+    render(
+      <SearchInput value="" onChange={onChange} suggestions={[]} placeholder="Search" />
+    )
+    await userEvent.type(screen.getByRole("combobox"), "a")
+    expect(onChange).toHaveBeenCalledWith("a")
+  })
+})
+
+// ─── Uncontrolled value ───────────────────────────────────────────────────
+
+describe("uncontrolled value", () => {
+  it("updates its own value when uncontrolled", async () => {
+    render(<SearchInput suggestions={suggestions} placeholder="Search" />)
+    const input = screen.getByRole("combobox")
+    await userEvent.type(input, "hello")
+    expect(input).toHaveValue("hello")
+  })
+})
+
+// ─── maxSuggestions ───────────────────────────────────────────────────────
+
+describe("maxSuggestions cap", () => {
+  it("shows at most maxSuggestions options", async () => {
+    const { input } = renderInput({ maxSuggestions: 2 })
+    await userEvent.type(input, "a")
+    await waitFor(() => screen.getByRole("listbox"))
+    const interactiveOptions = screen
+      .getAllByRole("option")
+      .filter((o) => !o.getAttribute("aria-disabled"))
+    expect(interactiveOptions.length).toBeLessThanOrEqual(2)
+  })
+})
+
+// ─── Disabled state ───────────────────────────────────────────────────────
+
+describe("disabled state", () => {
+  it("disables the input when disabled=true", () => {
+    renderInput({ disabled: true })
+    expect(screen.getByRole("combobox")).toBeDisabled()
+  })
+
+  it("does not open the listbox when disabled", async () => {
+    const { input } = renderInput({ disabled: true })
+    await userEvent.click(input)
+    expect(screen.queryByRole("listbox")).not.toBeInTheDocument()
+  })
+})
+
+// ─── Live region ─────────────────────────────────────────────────────────
+
+describe("screen-reader live region", () => {
+  it("announces result count when suggestions are shown", async () => {
+    const { input } = renderInput()
+    await userEvent.type(input, "bit")
+    await waitFor(() => {
+      const liveRegion = screen
+        .getAllByRole("status")
+        .find((el) => el.getAttribute("aria-live") === "polite")
+      expect(liveRegion).toBeTruthy()
+      expect(liveRegion!.textContent).toMatch(/suggestion/)
+    })
+  })
+
+  it("announces 'No results found' when there are no matches", async () => {
+    const { input } = renderInput({ suggestions: [] })
+    await userEvent.type(input, "xyz123")
+    await waitFor(() => {
+      const liveRegion = screen
+        .getAllByRole("status")
+        .find((el) => el.getAttribute("aria-live") === "polite")
+      expect(liveRegion!.textContent).toMatch(/no results/i)
+    })
+  })
+})
+
+// ─── Sublabel ─────────────────────────────────────────────────────────────
+
+describe("sublabel", () => {
+  it("renders the sublabel beneath the main label", async () => {
+    const { input } = renderInput()
+    await userEvent.type(input, "bit")
+    await waitFor(() => screen.getByText("Crypto"))
+  })
+})
+
+// ─── Snapshot / regression ────────────────────────────────────────────────
+
+describe("snapshot", () => {
+  it("matches closed-state snapshot", () => {
+    const { container } = renderInput()
+    expect(container.firstChild).toMatchSnapshot()
+  })
+})
diff --git a/docs/SEARCH_INPUT.md b/docs/SEARCH_INPUT.md
new file mode 100644
index 00000000..0475ef83
--- /dev/null
+++ b/docs/SEARCH_INPUT.md
@@ -0,0 +1,179 @@
+# SearchInput
+
+An accessible search input that implements the
+[ARIA combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/)
+(WAI-ARIA 1.2 §5.9).
+
+**Source:** `app/components/SearchInput.tsx`  
+**Tests:** `app/components/__tests__/SearchInput.test.tsx`
+
+---
+
+## Features
+
+- **ARIA combobox** — `role="combobox"`, `aria-expanded`, `aria-haspopup="listbox"`,
+  `aria-autocomplete="list"`, `aria-controls`, and `aria-activedescendant` are
+  managed automatically.
+- **Full keyboard navigation** — arrow keys, Home/End, Enter, Escape, and Tab all
+  behave per the WAI-ARIA authoring guide.
+- **Live region** — result counts and loading / empty states are announced to
+  screen-reader users via an `aria-live="polite"` region.
+- **Clear button** — keyboard-reachable with a descriptive `aria-label`.
+- **Reduced-motion safe** — dropdown entrance animation is wrapped in
+  `motion-safe:` utilities and is suppressed when the user has
+  `prefers-reduced-motion: reduce` set.
+- **Controlled & uncontrolled** — use `value` + `onChange` for a controlled
+  input, or omit both for an internally-managed uncontrolled input.
+
+---
+
+## Usage
+
+### Minimal example
+
+```tsx
+import { SearchInput } from "@/app/components/SearchInput";
+
+function MyPage() {
+  const [query, setQuery] = React.useState("");
+
+  const suggestions = useMarketSearch(query); // your own hook
+
+  return (
+    <SearchInput
+      value={query}
+      onChange={setQuery}
+      suggestions={suggestions}
+      onSelect={(s) => router.push(`/events/${s.id}`)}
+      onSubmit={(q) => router.push(`/events?q=${encodeURIComponent(q)}`)}
+      placeholder="Search markets…"
+    />
+  );
+}
+```
+
+### With icons and subtext
+
+```tsx
+import { TrendingUp } from "lucide-react";
+
+const suggestions = markets.map((m) => ({
+  id: m.id,
+  label: m.title,
+  sublabel: m.category,
+  icon: <TrendingUp className="h-4 w-4 text-muted-foreground" aria-hidden />,
+}));
+
+<SearchInput suggestions={suggestions} onSelect={handleSelect} />;
+```
+
+### Loading state
+
+```tsx
+<SearchInput
+  value={query}
+  onChange={setQuery}
+  suggestions={results}
+  isLoading={isFetching}
+  placeholder="Search markets…"
+/>
+```
+
+### Uncontrolled
+
+```tsx
+<SearchInput
+  suggestions={staticSuggestions}
+  onSelect={handleSelect}
+  placeholder="Find a market"
+/>
+```
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | — | Controlled value. Omit for uncontrolled. |
+| `onChange` | `(value: string) => void` | — | Called on every keystroke (controlled). |
+| `suggestions` | `SearchSuggestion[]` | `[]` | Items to display in the listbox. Filter externally. |
+| `onSelect` | `(suggestion: SearchSuggestion) => void` | — | Called when the user confirms an option. |
+| `onSubmit` | `(query: string) => void` | — | Called on Enter with no option highlighted. |
+| `onOpen` | `() => void` | — | Called when the listbox opens. |
+| `onClose` | `() => void` | — | Called when the listbox closes. |
+| `isLoading` | `boolean` | `false` | Shows a spinner and sets `aria-busy`. |
+| `placeholder` | `string` | `"Search…"` | Input placeholder (also used as `aria-label` fallback). |
+| `className` | `string` | — | Extra classes for the outermost wrapper. |
+| `maxSuggestions` | `number` | `10` | Maximum rendered items. |
+| `disabled` | `boolean` | `false` | Disables the input. |
+| `id` | `string` | — | Forwarded to the `<input>` element. |
+| `aria-label` | `string` | `placeholder` | Overrides the auto-derived aria-label. |
+| `aria-labelledby` | `string` | — | Points to an external label element. |
+
+### `SearchSuggestion`
+
+```ts
+interface SearchSuggestion {
+  id: string;          // unique key
+  label: string;       // primary text
+  sublabel?: string;   // secondary text (smaller)
+  icon?: React.ReactNode; // decorative icon (must carry aria-hidden)
+}
+```
+
+---
+
+## Keyboard interaction
+
+| Key | Behaviour |
+|---|---|
+| `ArrowDown` | Open listbox; move focus to next option (wraps at end). |
+| `ArrowUp` | Open listbox; move focus to previous option (wraps at start). |
+| `Home` | Move focus to first option (when listbox is open). |
+| `End` | Move focus to last option (when listbox is open). |
+| `Enter` | Confirm highlighted option, or submit free-text query. |
+| `Escape` | Close listbox; if already closed, clear the value. |
+| `Tab` | Close listbox; move focus naturally. |
+
+---
+
+## Differences from `components/navbar/SearchInput`
+
+| Aspect | `components/navbar/SearchInput` | `app/components/SearchInput` |
+|---|---|---|
+| Scope | Navbar-specific (pinned actions, recent markets, slash commands, Cmd+K) | General-purpose, data-agnostic |
+| Suggestions | Pulled directly from `useEventsStore` | Consumer-provided `suggestions[]` |
+| Styling | Predictify brand colours, backdrop blur | Design-system tokens (`bg-popover`, `accent`) |
+| Use case | Drop-in navbar widget | Reusable in any page or form |
+
+---
+
+## Accessibility notes
+
+- The component is fully keyboard-operable with no mouse required.
+- Visual focus and `aria-activedescendant` are always in sync.
+- The listbox is rendered inline (no portal), so it is always reachable in the
+  natural DOM order.
+- The clear button (`aria-label="Clear search"`) is in the tab order when
+  visible.
+- The live region (`aria-live="polite"`, `aria-atomic="true"`) is always in
+  the DOM but only populated when the listbox is open, preventing spurious
+  announcements on page load.
+- The "No results" and loading states are rendered as disabled `role="option"`
+  elements inside the `listbox` so the combobox structure remains valid.
+
+---
+
+## Running the tests
+
+```bash
+# Run only the SearchInput test file
+pnpm test app/components/__tests__/SearchInput.test.tsx
+
+# Run the full suite
+pnpm test
+
+# With coverage
+pnpm test:coverage
+```