malio-layer-ui/docs/superpowers/specs/2026-05-22-datetime-design.md

MalioDateTime — Design (version intérimaire)

Date : 2026-05-22 Ticket : #MUI-33 (famille Datepicker) Statut : validé, prêt pour le plan d'implémentation

Objectif

Ajouter un composant MalioDateTime à la famille temporelle de @malio/layer-ui, permettant de saisir une date ET une heure dans un seul champ avec popover.

Cette version est intérimaire : le sélecteur d'heure utilise un <input type="time"> natif, le temps que la maquette du sélecteur d'heure dédié soit fournie. Le bloc heure est volontairement isolé pour pouvoir être remplacé sans toucher au reste.

Valeur du modèle

modelValue: string | null au format ISO naïf sans fuseau : "YYYY-MM-DDTHH:MM:00" (ex. "2026-05-20T14:30:00").

• Heure murale locale : un picker n'a pas de notion de fuseau.
• Symfony (DateTimeNormalizer, RFC 3339) parse ce format et applique son fuseau configuré → zéro bug TZ/DST côté front.
• Les secondes sont toujours 00 (le natif type="time" par défaut n'expose pas les secondes).
• Cohérent avec MalioDate (YYYY-MM-DD) et MalioTime (HH:MM).

Architecture

Fine enveloppe autour du shell partagé internal/CalendarField.vue, comme MalioDate / MalioDateRange / MalioDateWeek.

MalioDateTime (Date/DateTime.vue)
  └─ CalendarField (champ + popover + header + navigation mois)
       slot #default={ currentMonth, currentYear, close }
         ├─ MonthGrid          (sélection du jour)
         └─ <input type="time"> (sélection de l'heure, sous la grille)

Le close du slot n'est pas appelé sur sélection (contrairement à MalioDate) : on a besoin de date ET heure, la fermeture se fait au clic extérieur (déjà gérée par CalendarField via useCalendarPopover).

Props

Identiques à MalioDate :

Prop	Type	Défaut	Note
id	string	''
name	string	''
label	string	''
modelValue	string | null	undefined	"YYYY-MM-DDTHH:MM:00"
placeholder	string	'JJ/MM/AAAA HH:MM'
required	boolean	false
disabled	boolean	false
readonly	boolean	false
hint	string	''
error	string	''
success	string	''
min	string	undefined	datetime ou date ; on borne la grille avec la partie date
max	string	undefined	idem
clearable	boolean	true
inputClass / labelClass / groupClass	string	''

Émissions : update:modelValue: string | null.

Affichage du champ

displayValue = formatIsoDateTimeToDisplay(modelValue) → "JJ/MM/AAAA HH:MM" (ex. 20/05/2026 14:30). Chaîne vide si modelValue nul ou invalide.

Flux de sélection

État : modelValue est la source de vérité. Une ref locale pendingTime: string ('HH:MM' ou '') sert de pont quand l'heure est réglée avant qu'un jour soit choisi.

• Partie date courante = splitDateTime(modelValue).date (ou null).
• Valeur de l'<input type="time"> = splitDateTime(modelValue).time si présent, sinon pendingTime.

Interactions :

1. Clic sur un jour iso :
   • heureEffective = partie heure de modelValue, sinon pendingTime, sinon '00:00'.
   • émet composeDateTime(iso, heureEffective) → "iso T heure:00".
   • le popover reste ouvert.
2. Changement de l'<input type="time"> (hhmm) :
   • si une partie date existe → émet composeDateTime(datePart, hhmm).
   • sinon → stocke hhmm dans pendingTime (pas d'émission tant qu'aucun jour n'est choisi).
   • si hhmm est vidé ('') et qu'une date existe → on garde la date avec 00:00 ? Non : on n'émet rien sur vidage, on conserve la dernière valeur émise (le natif renvoie rarement '' une fois rempli ; cas négligé pour l'intérim).
3. Effacer (croix) : émet null, pendingTime = ''.

Bornes min/max : passées à MonthGrid après slice de la partie date (min?.slice(0, 10)). Pas de borne sur l'heure dans cette version.

Composable composables/datetimeFormat.ts

Réutilise isValidIso de dateFormat.ts pour valider la partie date.

// "YYYY-MM-DDTHH:MM:00" complet et valide ?
export function isValidIsoDateTime(s: string): boolean

// "YYYY-MM-DDTHH:MM:00" -> "JJ/MM/AAAA HH:MM" (chaîne vide si invalide/nul)
export function formatIsoDateTimeToDisplay(s: string | null): string

// "YYYY-MM-DDTHH:MM:00" -> { date: "YYYY-MM-DD" | null, time: "HH:MM" | '' }
export function splitDateTime(s: string | null): { date: string | null; time: string }

// (date "YYYY-MM-DD", time "HH:MM") -> "YYYY-MM-DDTHH:MM:00"
export function composeDateTime(date: string, time: string): string

Règles :

• isValidIsoDateTime : regex ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$, partie date valide via isValidIso, heure 00–23, minutes 00–59, secondes 00–59.
• splitDateTime : si s nul ou ne matche pas le motif datetime → { date: null, time: '' }. Sinon découpe sur T, renvoie la date et HH:MM (5 premiers car. de la partie heure).
• composeDateTime(date, time) : ${date}T${time}:00. Si time vide → ${date}T00:00:00.
• formatIsoDateTimeToDisplay : si !isValidIsoDateTime → ''. Sinon ${dd}/${mm}/${yyyy} ${hh}:${min}.

Tests

Colocalisés, Vitest + @vue/test-utils (jsdom), vi.setSystemTime(new Date(2026, 4, 19)) pour déterminisme.

datetimeFormat.test.ts (helpers purs) :

• isValidIsoDateTime : accepte "2026-05-20T14:30:00" ; rejette "2026-05-20", "2026-13-01T00:00:00", "2026-05-20T24:00:00", "2026-05-20T14:60:00", "", format sans secondes.
• formatIsoDateTimeToDisplay : "2026-05-20T14:30:00" → "20/05/2026 14:30" ; nul/invalide → ''.
• splitDateTime : "2026-05-20T14:30:00" → { date: "2026-05-20", time: "14:30" } ; null → { date: null, time: '' } ; "2026-05-20" (date seule, non datetime) → { date: null, time: '' }.
• composeDateTime : ("2026-05-20", "14:30") → "2026-05-20T14:30:00" ; ("2026-05-20", "") → "2026-05-20T00:00:00".

DateTime.test.ts (composant) :

• Rendu : champ présent, placeholder JJ/MM/AAAA HH:MM, displayValue correct quand modelValue fourni.
• Ouverture popover au clic → MonthGrid + input[type=time] visibles.
• Clic sur un jour sans heure → émet "<iso>T00:00:00", popover reste ouvert.
• Clic sur un jour avec pendingTime réglé d'abord → émet "<iso>T<pendingTime>:00".
• Changement de l'heure avec date déjà choisie → émet "<date>T<nouvelleHeure>:00".
• Changement de l'heure sans date → aucune émission.
• clearable : croix émet null.
• min/max datetime → jours hors bornes désactivés dans la grille.
• Accessibilité : label lié, aria-invalid sur erreur.

Livrables

1. app/components/malio/date/composables/datetimeFormat.ts
2. app/components/malio/date/composables/datetimeFormat.test.ts
3. app/components/malio/date/DateTime.vue
4. app/components/malio/date/DateTime.test.ts
5. Page playground .playground/pages/composant/date/datetime.vue + entrée nav (playground.nav.ts)
6. Story app/story/date/dateTime.story.vue
7. COMPONENTS.md (section MalioDateTime)
8. CHANGELOG.md (ligne sous ### Added)

Hors périmètre (intérim)

• Sélecteur d'heure dédié / maquette → itération ultérieure ; on remplacera le bloc <input type="time"> isolé.
• Bornes horaires (min/max sur l'heure).
• Pas de minutes configurable (granularité native du navigateur).
• Secondes dans l'UI.