GIF Autocomplete — Full Design

Inline search suggestions powered by Klipy's autocomplete endpoint

Architecture Overview

Component & Data Flow
Component Tree
GifPickerDialog
└─ GifPickerBody
├─ GifPickerHeader
│ ├─ TextField.Input (search box)
│ └─ GifAutocompleteSuggestions ← NEW
├─ GifPickerPlaceholder
└─ GifPickerGrid
Data Flow
1. User types → rawSearch state
2. rawSearch throttled @ 200ms → autocomplete query
3. rawSearch throttled @ 500ms → GIF search query
4. Autocomplete response → suggestion strings
5. User taps suggestion → fills input + fires search
6. Suggestions hide when input matches a selected term

New Files

+ src/lib/constants.ts — add GIF_KLIPY_AUTOCOMPLETE endpoint
+ src/state/queries/klipy.ts — add useKlipyAutocompleteQuery hook
+ src/features/gifPicker/hooks/useGifAutocomplete.ts — orchestration hook (throttle + query + keyboard state)
+ src/features/gifPicker/components/GifAutocompleteSuggestions.tsx — inline suggestion list UI
~ src/features/gifPicker/components/GifPickerHeader.tsx — render suggestions below input
~ src/features/gifPicker/GifPickerDialog.tsx — wire up autocomplete state

Interaction Flow

1. Idle — no suggestions
🔍 Search GIFs
Featured GIFs
2. Typing — suggestions appear
🔍 hap|
🔍 happy birthday
🔍 happy
🔍 happy easter
3. Selected — GIFs load
🔍 happy birthday ✕
Results for "happy birthday"

Keyboard Navigation (Web)

ArrowDown / ArrowUp — move active highlight through suggestions
Enter — select highlighted suggestion (fills input, fires search)
Escape — dismiss suggestions (existing behavior closes dialog)
Continue typing — resets active index to 0, re-fetches suggestions

ARIA: input gets role="combobox" + aria-controls, list gets role="listbox", items get role="option" + aria-selected. ~30 lines of onKeyDown handling on web only.

Visibility Rules

SHOW when: rawSearch.length ≥ 1 AND suggestions.length > 0 AND user hasn't just selected a suggestion
HIDE when: rawSearch is empty OR user selected a suggestion OR user clears input
RE-SHOW when: user edits the input after a selection (e.g., backspace to modify)

Scope Boundaries

In Scope

  • Klipy autocomplete endpoint integration
  • Inline suggestion list in GifPickerHeader
  • 200ms throttle for autocomplete, independent of 500ms search throttle
  • Keyboard navigation on web (arrow keys, enter, escape)
  • ARIA accessibility attributes
  • Tap-to-select on native

Out of Scope

  • Tenor autocomplete (Klipy only)
  • Trending/popular suggestions on empty input
  • Search history / recents
  • Categories or tag browsing