169 lines
8.8 KiB
Markdown
169 lines
8.8 KiB
Markdown
# MalioDateWeek — Design Spec
|
|
|
|
Composant de sélection d'une **semaine ISO complète** (lundi→dimanche) via le shell calendrier partagé. Troisième brique de la famille temporelle.
|
|
|
|
**Ticket :** MUI-33 (suite)
|
|
**Branche :** `feature/MUI-33-developper-le-composant-datepicker`
|
|
**Specs liées :** `2026-05-19-datepicker-design.md`, `2026-05-20-daterange-design.md`
|
|
|
|
## Périmètre
|
|
|
|
Sélection d'une semaine entière en **un clic** (sur n'importe quel jour OU le numéro de semaine). Visuellement : la ligne de la semaine se surligne en pilule `bg-m-primary-light` (lundi arrondi gauche, dimanche arrondi droit), exactement comme une plage `DateRange` figée lun→dim. Survol = aperçu de la semaine. La cellule n° de la semaine sélectionnée passe en `bg-m-primary` (repère).
|
|
|
|
**Inclus :** clic jour/n° → semaine, hover de semaine, surlignage pilule, repère n° semaine, bornes `min`/`max` (semaine sélectionnable si elle chevauche), effacement, vue mois conservée.
|
|
|
|
**Reporté :** deux mois, saisie/navigation clavier.
|
|
|
|
## Donnée retournée
|
|
|
|
`modelValue: string | null` au format **ISO 8601 semaine `YYYY-Www`** (ex. `"2026-W21"`), comme l'`<input type="week">` natif. L'année est l'**année ISO de numérotation** (peut différer de l'année calendaire aux bords d'année). Affichage humain dans le champ : `"Semaine 21 (18/05 → 24/05/2026)"` (le `modelValue` reste `2026-W21`).
|
|
|
|
## Architecture (Approche 1 — réutilisation du rendu plage)
|
|
|
|
Une semaine sélectionnée **est** une plage lundi→dimanche : on réutilise le rendu pilule de `MonthGrid` (mode plage) en passant les bornes de la semaine active. Les events `select`/`hover` (jour) sont réutilisés ; l'enveloppe `DateWeek` mappe jour → semaine.
|
|
|
|
```
|
|
app/components/malio/date/
|
|
DateWeek.vue # NOUVEAU — enveloppe
|
|
DateWeek.test.ts # nouveau
|
|
internal/
|
|
MonthGrid.vue # étendu : interactiveWeekNumber + markedWeekStart (additifs)
|
|
CalendarField.vue # inchangé (shell réutilisé)
|
|
CalendarHeader.vue # inchangé
|
|
MonthPicker.vue # inchangé
|
|
composables/
|
|
dateWeek.ts # NOUVEAU — helpers semaine ISO (purs)
|
|
dateWeek.test.ts # nouveau
|
|
dateRange.ts # inchangé (rendu pilule réutilisé)
|
|
dateFormat.ts # inchangé
|
|
useCalendarView.ts # inchangé
|
|
useCalendarPopover.ts # inchangé
|
|
useMonthMatrix.ts # inchangé
|
|
app/story/date/dateWeek.story.vue
|
|
.playground/pages/composant/date/dateWeek.vue
|
|
```
|
|
|
|
Flux :
|
|
|
|
```
|
|
DateWeek.vue (enveloppe)
|
|
├─ état : hoverWeekStart (lundi de la semaine survolée)
|
|
├─ validWeek = isValidIsoWeek(modelValue) ? { monday: isoWeekToMonday(modelValue) } : null
|
|
├─ activeMonday = hoverWeekStart ?? validWeek.monday → activeSunday = sundayOf(activeMonday)
|
|
├─ displayValue = formatWeekDisplay(modelValue)
|
|
└─ <CalendarField :display-value :sync-to=validWeek.monday @clear @close>
|
|
└─ <MonthGrid
|
|
:range-start=activeMonday :range-end=activeSunday ← pilule lun→dim réutilisée
|
|
:marked-week-start=validWeek.monday ← repère n° semaine
|
|
interactive-week-number ← n° semaine cliquable/hoverable
|
|
:min :max
|
|
@select="(iso)=>onSelect(iso, close)" @hover="onHover" />
|
|
```
|
|
|
|
## `dateWeek.ts` (helpers purs)
|
|
|
|
```ts
|
|
function mondayOf(iso: string): string // "2026-05-20" → "2026-05-18"
|
|
function sundayOf(iso: string): string // "2026-05-20" → "2026-05-24"
|
|
function toIsoWeek(iso: string): string // "2026-05-20" → "2026-W21" (année ISO + n° semaine)
|
|
function isoWeekToMonday(week: string): string | null // "2026-W21" → "2026-05-18" ; invalide → null
|
|
function isValidIsoWeek(week: string): boolean // "2026-W21" → true ; "2026-W54"/"2026-21" → false
|
|
function formatWeekDisplay(week: string): string // "2026-W21" → "Semaine 21 (18/05 → 24/05/2026)" ; invalide → ""
|
|
```
|
|
|
|
- Algo ISO 8601 : jeudi de la semaine pour l'année de numérotation ; lundi de la semaine contenant le 4 janvier = semaine 1.
|
|
- `formatWeekDisplay` : `Semaine {n° sans zéro} ({JJ/MM lundi} → {JJ/MM/AAAA dimanche})`, réutilise `formatIsoToDisplay`.
|
|
- Cas pièges testés : `2025-12-31` → `2026-W01`, `2027-01-01` → `2026-W53`, `2026-01-01` → `2026-W01`.
|
|
|
|
## `MonthGrid.vue` — ajouts additifs
|
|
|
|
Nouvelles props optionnelles (n'altèrent pas les modes simple/plage) :
|
|
```ts
|
|
interactiveWeekNumber?: boolean // défaut false
|
|
markedWeekStart?: string | null // défaut null — lundi de la semaine repère
|
|
```
|
|
|
|
Quand `interactiveWeekNumber === true` :
|
|
- La cellule n° de semaine devient un `<button>` : `@click` émet `select(week.days[0].isoDate)`, `@mouseenter` émet `hover(week.days[0].isoDate)`. `:disabled` si `!weekSelectable`, où `weekSelectable = week.days.some(d => inRange(d.isoDate))`. `cursor-pointer` si sélectionnable.
|
|
- Repère : si `week.days[0].isoDate === markedWeekStart`, la cellule n° passe en `bg-m-primary text-white` (au lieu de `bg-m-primary-light`).
|
|
|
|
Toujours (inoffensif hors mode semaine) : la cellule n° porte `:data-week-start="week.days[0].isoDate"` et `:data-marked="week.days[0].isoDate === markedWeekStart"`.
|
|
|
|
Inchangé : rendu pilule des jours piloté par `rangeStart`/`rangeEnd` ; events `select`/`hover` jour ; quand `interactiveWeekNumber` est `false`, la cellule n° reste un `<div>` non cliquable (aucune régression `Date`/`DateRange`).
|
|
|
|
## `DateWeek.vue` (enveloppe)
|
|
|
|
**Props :** identiques à `Date` sauf `modelValue?: string | null` (`YYYY-Www`).
|
|
**Emit :** `update:modelValue` → `string | null`.
|
|
|
|
**État :**
|
|
```ts
|
|
hoverWeekStart = ref<string | null>(null)
|
|
const validWeek = computed(() =>
|
|
(props.modelValue && isValidIsoWeek(props.modelValue))
|
|
? {monday: isoWeekToMonday(props.modelValue) as string}
|
|
: null)
|
|
const activeMonday = computed(() => hoverWeekStart.value ?? validWeek.value?.monday ?? null)
|
|
const activeSunday = computed(() => activeMonday.value ? sundayOf(activeMonday.value) : null)
|
|
```
|
|
|
|
**Passé à `MonthGrid` :** `range-start=activeMonday`, `range-end=activeSunday`, `marked-week-start=validWeek?.monday ?? null`, `interactive-week-number`, `min`, `max`, month/year du slot.
|
|
|
|
**`displayValue`** = `validWeek ? formatWeekDisplay(modelValue) : ''`. **`syncTo`** = `validWeek?.monday ?? null`.
|
|
|
|
**Comportement (1 clic) :**
|
|
```
|
|
onSelect(iso, close): # jour OU n° de semaine (= lundi)
|
|
emit('update:modelValue', toIsoWeek(iso))
|
|
hoverWeekStart = null
|
|
close()
|
|
|
|
onHover(iso): # jour/n° survolé ; null au mouseleave
|
|
hoverWeekStart = iso ? mondayOf(iso) : null
|
|
|
|
onClose(): hoverWeekStart = null
|
|
onClear(): emit('update:modelValue', null) ; hoverWeekStart = null
|
|
```
|
|
|
|
- Survol → toute la ligne en pilule via `activeMonday`.
|
|
- Sélection en un clic → `YYYY-Www` + fermeture.
|
|
- Repère de la semaine committée conservé pendant le survol d'une autre.
|
|
- `modelValue` invalide → traité comme `null` + warning dev.
|
|
|
|
## Tests
|
|
|
|
### `dateWeek.test.ts` (~14)
|
|
- `mondayOf`/`sundayOf` : mercredi, lundi (idempotent), dimanche
|
|
- `toIsoWeek` : nominal + bords d'année (`2025-12-31`→`2026-W01`, `2027-01-01`→`2026-W53`, `2026-01-01`→`2026-W01`)
|
|
- `isoWeekToMonday` : `2026-W21`→`2026-05-18` ; round-trip ; invalide → null
|
|
- `isValidIsoWeek` : valide / `W00` / `W54` / format faux
|
|
- `formatWeekDisplay` : `2026-W21`→`"Semaine 21 (18/05 → 24/05/2026)"` ; invalide → `""`
|
|
|
|
### `DateWeek.test.ts` (~14, `setSystemTime(2026-05-19)`)
|
|
- Rendu label/icône, affichage `"Semaine ..."` si modelValue, champ vide sinon
|
|
- Ouverture sur le mois de la semaine du modelValue
|
|
- Clic d'un jour → émet le `YYYY-Www` de sa semaine + ferme
|
|
- Clic du n° de semaine (`[data-test="week-number"][data-week-start="..."]`) → émet + ferme
|
|
- Hover d'un jour → `data-range-role` start/in-range/end sur les 7 jours de la ligne ; autre ligne `none`
|
|
- Hover du n° de semaine → même surlignage
|
|
- Semaine committée → roles corrects + `data-marked="true"` sur la cellule n°
|
|
- `clear` → émet `null`
|
|
- min/max : semaine hors bornes n° désactivé + jours non cliquables ; semaine qui chevauche reste sélectionnable
|
|
- `disabled`/`readonly` → pas d'ouverture
|
|
- a11y : `aria-invalid` sur error
|
|
|
|
`Date.test.ts` / `DateRange.test.ts` restent verts (props additives).
|
|
|
|
### Story `dateWeek.story.vue`
|
|
Default vide, semaine initiale, min/max, états (disabled/readonly/error/success), non-clearable.
|
|
|
|
### Playground `.playground/pages/composant/date/dateWeek.vue`
|
|
Comparatif Large (480px) / ERP (396px), affichage `modelValue` + bornes du champ, boutons set/reset, cas borné.
|
|
|
|
## Découpage d'implémentation
|
|
|
|
1. `dateWeek.ts` (purs) + tests
|
|
2. Extension `MonthGrid.vue` (interactiveWeekNumber + markedWeekStart + data attrs)
|
|
3. `DateWeek.vue` + `DateWeek.test.ts`
|
|
4. Story + playground
|