docs(MUI-39) : design du sélecteur d'heure molette MalioTimePicker

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

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

@@ -0,0 +1,173 @@
+# 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.