Select et Overlay

Objectif

Select remplace le contrôle natif initial par une sélection accessible et réutilisable, adaptée aux formulaires métier. Il accepte des options locales, une recherche facultative et une source distante asynchrone.

Overlay reste indépendant du métier. Il fournit le portail et le positionnement nécessaires aux listes, menus, popovers et futurs pickers.

API principale

<Select
  name="status"
  options={[
    { value: "active", label: "Actif" },
    { value: "pending", label: "En attente" },
  ]}
  searchable
  clearable
  onValueChange={(value, option) => console.log(value, option)}
/>

Une option peut fournir description, disabled et keywords. La valeur est contrôlée avec value, ou non contrôlée avec defaultValue. Quand name est présent, une entrée cachée conserve la compatibilité avec les formulaires HTML.

La recherche locale ignore accents et casse — « sen » trouve « Sénégal » — avec looseIncludes de @sia-ui/utils. Elle porte sur le libellé, la description et les keywords. Après un filtrage qui écarte la valeur en vigueur, la première option devient active : Entrée choisit le premier résultat plutôt que de ne rien faire.

Logé dans un autre contrôle

variant="embedded" retire bordure, fond et pleine largeur du déclencheur ; renderValue choisit ce qu'il affiche quand la liste est fermée. Le panneau, lui, reste celui du Select — même recherche, même clavier, même thème.

<Select
  variant="embedded"
  searchable
  options={pays} // « 🇨🇲 Cameroun (+237) »
  renderValue={(option) => <>{drapeau} {indicatif}</>} // « 🇨🇲 +237 »
/>

C'est ainsi que PhoneInput choisit l'indicatif et Pagination la taille de page : un seul composant de liste déroulante dans le système. Le <select> natif qu'utilisait PhoneInput ne cherchait pas et ignorait le thème.

Chargement distant

<Select
  fetcher={(query, signal) => api.searchStatuses({ query, signal })}
  debounce={250}
  placeholder="Rechercher un statut"
/>

• fetcher active automatiquement le champ de recherche;
• les saisies sont temporisées avec debounce;
• la requête précédente est annulée à chaque nouvelle recherche ou fermeture;
• les états chargement, vide et erreur ont chacun un contenu personnalisable;
• la dernière option sélectionnée reste affichée lorsque les résultats changent.

Clavier et accessibilité

• le déclencheur expose le rôle combobox et contrôle une listbox;
• ArrowUp et ArrowDown parcourent les options actives;
• Home, End, Enter et Escape sont pris en charge;
• Backspace ou Delete efface une sélection clearable lorsque la liste est fermée;
• les options désactivées sont ignorées par la navigation;
• le focus revient au déclencheur après une sélection.

Responsabilités de Overlay

Overlay utilise une position fixed, suit le scroll et le redimensionnement, reste dans le viewport et bascule au-dessus du déclencheur quand l'espace manque. Il se ferme avec Escape ou une interaction extérieure. Il ne gère ni options, ni sélection, ni recherche.

Cette séparation doit être réutilisée lors de la modernisation de MultiSelect, Autocomplete, TreeSelect, DatePicker, Popover et des menus.