# Sélecteur d'année dans le calendrier (3ᵉ niveau de navigation)

**Date :** 2026-06-22
**Statut :** Design validé
**Composants concernés :** famille `date/` (`Date`, `DateRange`, `DateTime`, `DateWeek`) via le shell partagé `internal/CalendarField.vue`

## Contexte & objectif

Aujourd'hui le calendrier a deux vues : la grille de jours (`days`) et le sélecteur de
mois (`months`). En cliquant sur le libellé « Mai 2026 » du header, on bascule entre les
deux (`toggleView`).

On ajoute un **3ᵉ niveau** : depuis la vue mois, recliquer sur le header ouvre un
**sélecteur d'année**, visuellement calqué sur le sélecteur de mois. Le tout doit
fonctionner pour les 4 composants de la famille sans casser leur API publique.

### Flux cible

| Vue courante | Header affiche | Clic header → | Clic sur une cellule → |
|---|---|---|---|
| `days`   | « Mai 2026 »   | `months` | (jour) sélection + fermeture |
| `months` | « 2026 »       | `years`  | `days` (mois choisi) |
| `years`  | « 2020 – 2031 »| _rien_ (niveau le plus haut) | `months` (année choisie) |

## Décisions de design (validées)

1. **Grille d'années** : 12 ans en `grid-cols-3` (4 lignes), calquée sur `MonthPicker`,
   avec chevrons de pagination `±12 ans`.
2. **Header contextuel** : libellé adapté à la vue (voir tableau). Chevron-bas masqué en
   vue `years` (clic neutralisé).
3. **min/max respectés** : le sélecteur d'année **grise** les années hors `[min, max]`,
   ET on **corrige** le `MonthPicker` existant pour qu'il grise aussi les mois hors
   plage (asymétrie actuelle : aujourd'hui tous les mois sont cliquables).
4. **Cadrage de la fenêtre d'années** : centrée, `yearPageStart = currentYear − 5`
   (fenêtre `[courante−5 … courante+6]`), l'année courante apparaît ~au milieu.

## Architecture

Le shell `CalendarField` orchestre l'input, le popover, le header et la commutation de
vues. `MonthPicker` et le nouveau `YearPicker` sont rendus **dans** `CalendarField`
(contrairement à la grille de jours, fournie par chaque consommateur via slot scoped).

### 1. Machine à états des vues — `composables/useCalendarPopover.ts`

- `viewMode` : `'days' | 'months'` → **`'days' | 'months' | 'years'`**.
- Remplacer `toggleView()` par **`goToHigherView()`** (zoom arrière) :
  `days → months`, `months → years`, `years → years` (no-op).
- `open()` / `close()` repartent en `days` (inchangé).

### 2. Navigation & fenêtre d'années — `composables/useCalendarView.ts`

- Élargir le type `viewMode` à `'days' | 'months' | 'years'`.
- Nouveau ref **`yearPageStart`**.
- `watch(viewMode)` : à l'entrée en `years`, recentrer `yearPageStart = currentYear − 5`.
- `goToPrev` / `goToNext` : branche `years` → `yearPageStart ∓ 12`
  (`months` → année ±1, `days` → mois ±1 : inchangés).
- Nouveau **`selectYear(y)`** → `currentYear = y`.

### 3. Header — `internal/CalendarHeader.vue`

- Props : ajouter `yearPageStart: number`, élargir `viewMode`.
- `label` calculé :
  - `days` → « Mai 2026 »
  - `months` → « 2026 »
  - `years` → `` `${yearPageStart} – ${yearPageStart + 11}` ``
- Chevron-bas (`mdi:chevron-down`) masqué en vue `years` ; le bouton n'émet
  `toggle-view` que si `viewMode !== 'years'`.
- aria-labels prev/next adaptés : « Période précédente/suivante » en vue `years`.

### 4. Nouveau composant — `internal/YearPicker.vue`

Calque de `MonthPicker` :
- Props : `pageStart: number`, `selectedYear?: number`, `min?: string`, `max?: string`.
- `years = Array.from({length: 12}, (_, i) => pageStart + i)`.
- Pour chaque année : `disabled = !isYearInRange(year, min, max)` → `disabled`,
  `aria-disabled`, style muet (`text-m-muted/30`, `cursor-not-allowed`), pas d'émission.
- Année sélectionnée : `bg-m-primary text-white` (comme le mois sélectionné).
- Émet `select(year: number)`.
- `defineOptions({name: 'MalioDateYearPicker'})`.
- Attributs de test : `data-test="year-picker"`, `data-test="year"`, `data-year`.

### 5. Correction `MonthPicker` — `internal/MonthPicker.vue`

- Props : ajouter `currentYear: number`, `min?: string`, `max?: string`.
- Pour chaque mois `index` : `disabled = !isMonthInRange(currentYear, index, min, max)`
  → même traitement disabled que `YearPicker`.

### 6. Helpers purs — `composables/dateFormat.ts`

Comparaison par préfixe ISO (les chaînes ISO se comparent lexicographiquement) :

```ts
export function isMonthInRange(year: number, month: number, min?: string, max?: string): boolean {
  const ym = `${year}-${String(month + 1).padStart(2, '0')}`
  if (min && ym < min.slice(0, 7)) return false
  if (max && ym > max.slice(0, 7)) return false
  return true
}

export function isYearInRange(year: number, min?: string, max?: string): boolean {
  if (min && year < Number(min.slice(0, 4))) return false
  if (max && year > Number(max.slice(0, 4))) return false
  return true
}
```

### 7. Câblage — `internal/CalendarField.vue` + consommateurs

- `CalendarField` : ajouter props `min?: string`, `max?: string`.
- Récupérer `yearPageStart`, `selectYear`, `goToHigherView` des composables.
- Template du popover :
  - `<CalendarHeader … :year-page-start="yearPageStart" @toggle-view="goToHigherView" />`
  - slot jours `v-if="viewMode === 'days'"` (inchangé)
  - `<MonthPicker v-else-if="viewMode === 'months'" :selected-month :current-year :min :max @select="onSelectMonth" />`
  - `<YearPicker v-else :page-start="yearPageStart" :selected-year="currentYear" :min :max @select="onSelectYear" />`
- Handlers :
  - `onSelectMonth(m)` → `selectMonth(m)` puis vue `days`.
  - `onSelectYear(y)` → `selectYear(y)` puis vue `months`.
- Les 4 consommateurs bindent `:min` / `:max` sur `<CalendarField>` (déjà disponibles
  comme props ISO ; `DateTime` tronque via `.slice(0, 10)`). **Aucune API publique ne
  change.**

## Effets de bord & cohérence

- `month-change` (émis sur `[isOpen, currentMonth, currentYear]`) : la pagination
  d'années ne touche pas `currentYear` → pas d'émission parasite. Sélectionner une année
  change `currentYear` → un `month-change` est émis (comportement attendu : le
  consommateur peut recharger les données).
- Pas de navigation clavier dans les grilles (le `MonthPicker` actuel n'en a pas non
  plus) — hors scope.
- `Escape` ferme le popover quelle que soit la vue (inchangé).

## Plan de tests (TDD)

- `dateFormat.test.ts` : `isMonthInRange`, `isYearInRange` (bornes, sans min/max, hors
  plage par année et par mois).
- `useCalendarPopover.test.ts` : nouveau cycle `goToHigherView` (`days→months→years→years`),
  `close()` réinitialise à `days`.
- `useCalendarView.test.ts` : nav années `yearPageStart ±12`, `selectYear`, recentrage à
  l'entrée en vue `years`.
- `MonthPicker.test.ts` : mois hors plage grisés / non émis.
- `YearPicker.test.ts` (nouveau) : rend 12 années depuis `pageStart`, année sélectionnée,
  années hors plage grisées, émet `select`.
- Non-régression : `Date.test.ts`, `DateRange.test.ts`, `DateTime.test.ts`,
  `DateWeek.test.ts` doivent rester verts ; ajouter au moins un test de bout en bout du
  flux `days → months → years → months → days` dans `Date.test.ts`.
- Déterminisme : `vi.setSystemTime(new Date(2026, 4, 19))` comme l'existant.

## Livrables doc (convention projet)

- Maj manuelle de `COMPONENTS.md` (documenter le 3ᵉ niveau du calendrier).
- Entrée `CHANGELOG.md`.

## Non-objectifs (YAGNI)

- Pas de sélecteur de décennie/siècle (4ᵉ niveau).
- Pas de saisie clavier directe de l'année dans la grille.
- Pas de navigation au clavier (flèches) dans les grilles mois/années.