Autocomplete

1/** @jsxImportSource hono/jsx */
2import { cn, type ClassValue } from "@/registry/lib/cn"
3 
4// Autocomplete — shadcn-htmx, htmx v4 + Tailwind v4.
5//
6// Free-text input with native typeahead suggestions: a real <input list>
7// bound to a <datalist>. The light, native sibling of the APG combobox —
8// where the combobox is a full listbox widget, this is the platform's own
9// "suggestion list" affordance with zero behavioural JS of our own.
10//
11// **Native-first.** The browser owns everything:
12//   - the suggestion dropdown UI and its positioning
13//   - substring filtering of <option> values as the user types
14//   - click + Up/Down + Enter selection, Escape to dismiss
15//   - focus management and the implicit listbox role of <datalist>
16// The value is always free text — an autocomplete *suggests*, it does not
17// constrain. (Use <select> / the listbox component when the value must be
18// one of a fixed set.)
19//   See repos/mdn/files/en-us/web/html/reference/elements/datalist/index.md
20//      ("<datalist> is not a replacement for <select>… The control can still
21//       accept any value that passes validation.")
22//      repos/mdn/files/en-us/web/html/reference/elements/input/index.md#list
23//      ("The values provided are suggestions, not requirements.")
24//
25// htmx wiring (server-streamed suggestions, verified against the vendored
26// v4 source). When `endpoint` is set we point htmx at this input and let the
27// server return a fresh <option> set on each keystroke:
28//   - hx-trigger="input changed delay:Nms" — debounce typing and ignore
29//     no-op keys (arrows). The leading `input` event covers every keystroke.
30//     See repos/htmx/www/src/content/reference/01-attributes/06-hx-trigger.md
31//        ("Events can be refined with filters and modifiers, e.g.
32//          `input changed delay:1s`")
33//   - hx-target="#<id>-list" + hx-swap="innerHTML" — swap the new options
34//     straight into the bound <datalist>; the input keeps focus and the
35//     browser re-renders the dropdown from the fresh list transparently.
36//   - hx-sync="this:replace" — abort the in-flight request when the next
37//     keystroke fires so a slow response can never clobber newer suggestions.
38//     See repos/htmx/www/src/content/reference/01-attributes/21-hx-sync.md
39//
40// Style analogues: registry/ui/combobox.tsx (the datalist sibling) and
41// registry/ui/input.tsx / registry/ui/active-search.tsx (the input chrome +
42// the htmx defaults + the .htmx-request dimming convention).
43//
44// … truncated