malio-layer-ui/docs/superpowers/specs/2026-05-27-select-heure-design.md

Design — MalioTimePicker (sélecteur d'heure molette, MUI-39)

Date : 2026-05-27 Branche : feature/MUI-39-developper-le-composant-select-heure Statut : validé (design), prêt pour plan d'implémentation

Contexte

MalioDateTime a été livré en version intérimaire (MUI-33) avec un <input type="time"> natif sous la grille du calendrier, volontairement isolé dans DateTime.vue en attendant une maquette pour le sélecteur d'heure dédié. La maquette est maintenant fournie (time.png à la racine) : c'est une molette de défilement style iOS avec bande de sélection centrale (pastille teintée), valeur centrée en noir/gras, voisins estompés.

Ce ticket développe ce sélecteur dédié comme nouveau composant et rebranche DateTime dessus.

Décisions (issues du brainstorming)

Sujet	Décision
Relation à MalioTime (champs texte HH/MM)	Nouveau composant séparé ; MalioTime reste intact
Nom public	MalioTimePicker (time/TimePicker.vue)
Mécanique	Molette iOS : scroll vertical, snap, bande centrale ; valeur centrée = sélection
Colonnes	2 molettes : heures 00–23, minutes 00–59, pas de 1
Format modelValue	"HH:MM" (24h) string | null
Bornes min/max	Non (YAGNI) — colonnes pleines
Interaction	Scroll + clic (recentre) + clavier (↑/↓) — accessible
Forme	Champ + popover (floating-label + icône horloge), comme Date/DateTime
Style panneau	Même style que le popover date mais sans rounded-b
Extrémités molette	Boucle infinie (23→00 sans fin)
Approche technique	CSS scroll-snap natif + repositionnement par bloc pour la boucle (zéro dépendance)
Rebranchement DateTime	Dans cette itération : retrait de l'<input type="time"> natif

Arborescence des fichiers

app/components/malio/time/
  TimePicker.vue              # NOUVEAU — public <MalioTimePicker> : champ + popover
  TimePicker.test.ts
  internal/
    TimeWheels.vue            # NOUVEAU — brique réutilisable : les 2 molettes (v-model "HH:MM")
    TimeWheel.vue             # NOUVEAU — une colonne molette infinie (v-model number)
  composables/
    useInfiniteWheel.ts       # NOUVEAU — scroll-snap + boucle infinie + index centré
    useInfiniteWheel.test.ts
    timeFormat.ts             # NOUVEAU — parse/format/pad/clamp "HH:MM"
    timeFormat.test.ts

Time.vue (MalioTime, champs texte) n'est pas modifié.

Composants & responsabilités

TimeWheel.vue (interne)

Une colonne molette infinie.

• Props : modelValue: number, values: number[] (ex. 0..23), ariaLabel: string.
• Emits : update:modelValue (value: number).
• Délègue scroll/snap/boucle/index-centré au composable useInfiniteWheel.
• Rendu : buffer de valeurs répété ; item centré en noir/gras, voisins estompés (opacité décroissante avec la distance au centre).
• Clic sur un item visible → recentre (scrollToValue).
• Clavier : ↑/↓ changent l'index (et scrollent), role="spinbutton", tabindex=0, aria-valuenow / aria-valuemin / aria-valuemax / aria-valuetext, aria-label.

TimeWheels.vue (interne — la brique partagée)

Compose les 2 molettes + la bande centrale.

• Props : modelValue: string ("HH:MM").
• Emits : update:modelValue (value: string).
• Splitte via timeFormat → heures + minutes ; passe à chaque TimeWheel ; recompose et émet à chaque changement.
• Bande centrale : pastille teintée (bg-m-primary/10 ou équivalent) en overlay positionné au centre, traversant les 2 colonnes ; le « : » séparateur entre les colonnes.
• C'est ce bloc qui est inséré dans DateTime (et dans le popover de TimePicker).

TimePicker.vue (public MalioTimePicker)

Champ + popover.

• Input lecture-seule affichant "HH:MM" (ou placeholder), floating-label, icône mdi:clock-outline, bouton clear (si clearable et rempli).
• Au clic → ouvre un popover au style du popover date sans rounded-b, contenant <TimeWheels v-model>.
• Props famille : id, name, label, modelValue, placeholder, required, disabled, readonly, hint, error, success, clearable, inputClass, labelClass, groupClass.
• Pattern contrôlé/non-contrôlé (isControlled = computed(() => props.modelValue !== undefined)).
• Fermeture au clic extérieur (handler local sur le root ; on ne réutilise pas useCalendarPopover qui porte une logique viewMode propre au calendrier).
• disabled/readonly n'ouvrent pas le popover.
• Ligne hint/error/success + aria-invalid/aria-describedby comme CalendarField.

useInfiniteWheel.ts (composable — cœur logique)

Toute la mécanique délicate, isolée et testable.

• Entrées : ref du conteneur scrollable, itemHeight, longueur des valeurs, valeur courante, callback de changement.
• Sorties : centeredIndex (round(scrollTop / itemHeight) % len), scrollToValue(value, smooth), handlers onScroll / onScrollEnd / clavier.
• Boucle infinie : buffer répété N fois ; quand scrollTop approche un bord, on repositionne scrollTop d'un bloc (hauteur d'un cycle de valeurs) sans animation, position visuelle identique → illusion d'infini.
• Garde anti-boucle entre scroll programmatique et émission modelValue.

timeFormat.ts (composable pur)

• parseTime(value: string | null): { hours: number; minutes: number } | null
• formatTime(hours: number, minutes: number): string (zéro-paddé "HH:MM")
• padSegment, clampHours (0–23), clampMinutes (0–59).

Flux de données

1. TimePicker détient modelValue "HH:MM" | null (contrôlé/non-contrôlé).
2. À l'ouverture, TimeWheels reçoit la valeur courante ; si vide, les molettes se centrent sur un défaut neutre 00:00 sans émettre. La 1ʳᵉ interaction (scroll/clic/clavier) committe et émet.
3. TimeWheels splitte "HH:MM" → 2 nombres → TimeWheel ; tout changement recompose "HH:MM" et remonte via update:modelValue.
4. Le bouton clear remet la valeur à vide/null.
5. Le popover reste ouvert pendant le réglage (cohérent avec DateTime) ; se ferme au clic extérieur.

Rebranchement DateTime.vue

• Remplacer le bloc <input type="time"> (lignes ~31-41) par : <TimeWheels :model-value="timeValue || '00:00'" @update:model-value="onTimeChange" />.
• onTimeChange(hhmm) reprend la logique existante de onTimeInput : si datePart présent → composeDateTime(datePart, hhmm) ; sinon → pendingTime.value = hhmm.
• Supprimer timeInputId et le handler onTimeInput natif. pendingTime / composeDateTime / splitDateTime inchangés.
• Mettre à jour DateTime.test.ts : l'ancien test ciblait data-test="time-input" / type="time" ; le réécrire pour interagir avec TimeWheels (émission de update:modelValue depuis la brique).

Accessibilité

• Molette : role="spinbutton", tabindex=0, aria-label « Heures » / « Minutes », aria-valuenow/valuemin/valuemax/valuetext, flèches ↑/↓.
• Champ : aria-haspopup="dialog", aria-expanded, popover role="dialog", aria-invalid + aria-describedby reliés à la ligne hint/error/success.
• Label lié for/id.

Stratégie de tests

• useInfiniteWheel.test.ts : index centré depuis scrollTop, scrollToValue, math du repositionnement de boucle (jump par bloc), modulo/clamp.
• TimeWheel.test.ts : flèches clavier changent la valeur & émettent, clic recentre, attributs aria (role, aria-valuenow...).
• TimeWheels.test.ts : split/compose "HH:MM", émission de la valeur combinée, 2 molettes rendues, séparateur.
• TimePicker.test.ts : rendu, label/id, ouverture popover au clic, affichage de modelValue, clear, contrôlé/non-contrôlé, disabled/readonly n'ouvrent pas, aria.
• timeFormat.test.ts : parse/format/pad/clamp (valeurs limites, null, invalides).
• DateTime.test.ts : mis à jour pour la brique molette.
• ⚠️ Limite jsdom : pas de scroll-snap réel. La mécanique est testée via le composable (métriques scrollTop/itemHeight mockées) ; les tests composant portent sur émissions/clavier/clic/aria, pas le snap pixel.
• ⚠️ Tests flaky connus (Date & InputRichText) : relancer 2–3× avant de conclure à une régression ; hook pre-commit parfois flaky → --no-verify documenté.

Livrables documentation (conventions projet)

• COMPONENTS.md : ajout MalioTimePicker + note « DateTime utilise désormais la molette ». (manuel)
• CHANGELOG.md : entrée. (manuel)
• Playground : page dédiée + entrée dans playground.nav.ts (routage Nuxt centralisé).
• Histoire : TimePicker.story.vue.
• Appui sur la skill creating-malio-component pendant l'implémentation.

Hors scope

• Bornes horaires min/max.
• Format 12h / AM-PM.
• Granularité minutes configurable (minuteStep).
• Colonne secondes.

Ces points pourront faire l'objet d'itérations ultérieures si le besoin métier émerge.