agtc-input implementation

Contexte

agtc-input est le deuxième composant du système. Il couvre la saisie de texte dans les formulaires — le point d'entrée le plus fréquent des données utilisateur.

Trois contraintes ont guidé les décisions :

1. Accessibilité — un champ de saisie sans label visible est inaccessible (WCAG 1.3.1). Chaque état (erreur, désactivé, lecture seule) doit être communiqué à l'arbre d'accessibilité, pas seulement visuellement.

2. Shadow DOM — l'association <label for="id"> ne traverse pas les frontières Shadow DOM. L'implémentation doit contourner cette limite.

3. Cohérence avec agtc-button — même approche icône hybride (propriété + slot), mêmes conventions d'événements, même structure de tokens.

Décisions

Décision 1 — Label et input colocalisés dans le Shadow DOM

Problème : <label for="id"> externe ne peut pas pointer vers un <input> dans le Shadow DOM.

Décision : Le label est rendu à l'intérieur du Shadow DOM avec un for pointant vers l'id interne de l'<input>. Un compteur statique garantit l'unicité des ids entre instances.

Alternative rejetée : aria-label sur l'input à la place du label visible. Rejeté : viole WCAG 1.3.1 (le label doit être persistant et visible, pas seulement déclaré pour les AT).

Décision 2 — Focus ring sur le wrapper .control, pas sur l'input

Problème : L'input natif a outline: none pour permettre un style custom. Le focus doit rester visible (WCAG 2.4.7).

Décision : Le wrapper .control porte le focus ring via :focus-within. outline: 2.5px solid + outline-offset: 2px — identique à agtc-button.

Justification : Le focus ring sur le wrapper est visuellement plus propre (encadre l'ensemble du contrôle incluant les icônes) et reste WCAG conforme car l'indicateur de focus est clairement visible.

Décision 3 — aria-describedby pour helper-text et error-message

Les ids {_id}-helper et {_id}-error sont toujours présents dans le DOM. aria-describedby est construit dynamiquement : seuls les ids pertinents sont inclus selon l'état du composant.

Le message d'erreur porte role="alert" pour annoncer l'erreur aux lecteurs d'écran dès qu'elle apparaît, sans nécessiter de navigation vers l'élément.

Parité Figma (2026-09-05) : un audit fichier-complet a révélé que helper-text était réellement cassé sur le ComponentSet Input — componentPropertyDefinitions listait la propriété, mais aucune variante ne la rendait réellement (prédit par une note de session antérieure, maintenant confirmé). Corrigé en ajoutant un nouveau calque TEXT helper-text sur les 15 variantes, positionné dans la pile auto-layout entre field et error-message (reflétant l'ordre DOM du code : contrôle → aide → erreur), lié à la propriété existante Helper Text pour son texte, plus une nouvelle propriété Boolean Show Helper Text (défaut false) pour la visibilité — même pattern que Show Label (Décision 7 ci-dessous). Vérifié seul et combiné avec un état d'erreur (empilement et couleurs corrects). error-message a été audité dans la même passe et confirmé déjà correctement câblé sur les 2 variantes State=Error — aucun bug, aucun changement nécessaire là.

Décision 4 — Toggle show/hide natif pour type="password"

Un bouton interne est rendu automatiquement quand type="password". Il bascule l'attribut type de l'input entre password et text.

Justification : Permettre à l'utilisateur de vérifier sa saisie est une exigence d'accessibilité (évite les erreurs sur les mots de passe masqués). L'aria-label du bouton bascule entre "Afficher le mot de passe" et "Masquer le mot de passe".

Le slot suffix reste disponible pour la composition libre si le consommateur veut remplacer le toggle natif.

Décision 5 — Directive live() pour la synchronisation de valeur

L'input utilise .value="${live(this.value)}" pour synchroniser la valeur de la propriété Lit avec la valeur native de l'input lors des re-renders.

Sans live(), Lit ne met pas à jour la valeur native si l'utilisateur a commencé à taper (DOM drift). live() compare toujours contre la valeur DOM actuelle, garantissant la cohérence.

Décision 6 — Suppression des spinners natifs sur type="number"

Les spinners CSS natifs (-webkit-inner-spin-button) sont supprimés. Le contrôle de la valeur numérique se fait via clavier (↑/↓) et saisie directe.

Justification : Les spinners natifs sont visuellement incohérents entre navigateurs et ne peuvent pas être stylés avec les tokens du système.

Décision 7 — hide-label : exception de label visuellement masqué pour les champs search clarifiés par une icône

Problème : les champs de recherche sont un pattern UX reconnu où un label flottant visible est souvent jugé redondant à côté d'une icône + placeholder (ex. une barre de recherche d'en-tête). La Décision 1 ci-dessus a déjà rejeté un label uniquement en aria-label — cette exception ne revient pas sur ce rejet.

Décision : hide-label conserve exactement le même vrai <label for="id"> de la Décision 1, pleinement présent dans le DOM et lié, et le masque uniquement *visuellement* via une classe .visually-hidden (positionnement absolu + clip 1×1px — la même technique déjà utilisée par le captionHidden de agtc-table), jamais display:none/visibility:hidden, qui supprimerait entièrement le nom accessible. Nécessite icon — sans icône visible, le rôle du champ ne serait plus univoque, selon la condition même de la technique W3C ARIA14 ("le contexte et l'apparence visuelle du contrôle rendent son objectif clair"). updated() émet un avertissement console si hide-label est posé sans icon, à l'image de l'avertissement déjà existant pour label manquant.

Pourquoi ça ne contredit pas la Décision 1 : la Décision 1 rejetait la suppression du label persistant et associé par programmation au profit d'un aria-label seul. hide-label conserve ce même élément label — seul son rendu visuel change, pas sa présence ni son association. Le WCAG 1.3.1 est respecté à l'identique de tout autre état de ce composant.

Approuvé via ux-pattern-review (ADR-036) le 2026-09-05 — voir la nouvelle ligne de pattern ci-dessous et guidelines/components/input.md § UX Patterns Reference pour la discussion complète des sources, y compris la réserve de NN/g selon laquelle le *champ lui-même* (pas seulement le label) doit rester visible.

Parité Figma (2026-09-05) : selon la règle 3 de figma-library-governance.md ("même architecture, mêmes options que dans le code"), hide-label est câblé comme une vraie propriété de composant Figma sur le ComponentSet Input, pas juste un exemple statique. Figma ne peut pas lier un booléen nié à l'état visible d'un calque, donc la propriété est nommée Show Label (Boolean, défaut true) — l'inverse de l'attribut code — et liée via componentPropertyReferences.visible sur le calque Label des 15 variantes. Show Label = false reproduit exactement hide-label (vérifié : label retiré du rendu, champ remonté en haut, hauteur 70→40). Le tableau Props sur la page Figma documente cette inversion de nommage directement pour qu'un designer réconciliant Figma avec le prop du code ne soit pas surpris par la polarité inversée.

Patterns UX de référence appliqués

Ajouté le 2026-06-01 via le workflow ux-pattern-review (ADR-036). Décision du Design System Lead : tous les patterns approuvés. Détail et liens dans guidelines/components/input.md § PATTERNS UX DE RÉFÉRENCE.

Périmètre de la version 1.0

Tokens utilisés