Autocomplete

Prezentare

Ajută la găsirea rapidă a unei valori dintr-o listă lungă, cu sugestii filtrate live și navigare completă din tastatură, peste un `<input>`/`<datalist>` nativ funcțional.

Când se folosește

• pentru selecția dintr-o listă lungă de opțiuni cunoscute (de exemplu, numele unei instituții), unde tastarea unor litere reduce rapid alegerile.

Când nu se folosește

• pentru liste scurte (sub 10-15 opțiuni) — un `select` simplu, fără nevoie de filtrare, e mai previzibil.

Anatomie

Un `<div class="sd-autocomplete" data-sd-autocomplete>` cu `<label>`, `<input data-sd-autocomplete-input list="…">`, `<datalist>` cu opțiunile sursă, `<div data-sd-autocomplete-menu hidden>` (meniul listbox construit de JavaScript) și un `<p aria-live="polite" data-sd-autocomplete-status>` pentru anunțarea numărului de sugestii.

Variante

• implicit — o singură variantă

Stări

• `aria-expanded="true|false"` pe input
• `aria-selected="true|false"` pe fiecare opțiune din meniu

Comportament

Fără JavaScript: inputul folosește `list="…"` către `<datalist>`, oferind autocompletare nativă a browserului — funcțional, deși fără meniul personalizat. Cu JavaScript (`enhanceAutocompletes`): elimină atributul `list`, transformă inputul în `role="combobox"` legat de un `role="listbox"` construit dinamic, filtrează opțiunile la fiecare tastă (comparație fără diacritice, primele 8 rezultate), navighează cu ArrowUp/ArrowDown (circular), selectează cu Enter sau clic, închide cu Escape sau blur, și anunță numărul de sugestii prin regiunea live.

Reguli de conținut

• eticheta fiecărei opțiuni e textul complet căutat de utilizator, nu un cod intern — utilizatorul filtrează după ce vede, nu după un ID ascuns.

Responsabilitățile implementatorului

• `<datalist>` trebuie populat complet înainte de inițializare — enhancement-ul citește opțiunile o singură dată, la pornire, dintr-un `<datalist>` static.

Cercetare

• https://github.com/ciprian-rus/sistem.digital/pull/52 (site extern)

Istoric

Structura completă a acestei secțiuni urmează șablonul canonic al paginii unei componente. Accesibilitatea (semantică, tastatură, focus) rămâne documentată separat, conform șablonului de accesibilitate.

Preview și markup canonic

Previzualizarea de mai jos redă exact șirul HTML afișat în exemplul de cod. Nu există o implementare paralelă pentru documentație.

Instalare și importuri

pnpm add @sistem-digital/tokens @sistem-digital/components

@import '@sistem-digital/components/interactive.css';

import { enhanceAutocompletes } from '@sistem-digital/components';

<div class="sd-autocomplete" data-sd-autocomplete><label class="sd-label" for="catalog-institution">Instituție</label><input class="sd-input" id="catalog-institution" list="catalog-options" data-sd-autocomplete-input><datalist id="catalog-options"><option value="Primăria Cluj-Napoca"></option><option value="Primăria Brașov"></option></datalist><div data-sd-autocomplete-menu hidden></div><p class="sd-visually-hidden" aria-live="polite" data-sd-autocomplete-status></p></div>

Contract și surse

• Documentația familiei Interactive
• Codul sursă (site extern)
• Changelog (site extern)

Schimbarea claselor publice, a markup-ului canonic sau a comportamentului helperelor necesită versionare și instrucțiuni de migrare.

Matricea design–cod

Disponibilitatea reală a acestei componente, calculată din pachetele publicate, conform schemei matricei design–cod. Rândurile Figma, testare cu tastatura și testare cu cititor de ecran rămân „Indisponibil” până la dovezi publicate separat (kit Figma, respectiv auditul manual de accesibilitate).