From 7ab221976462e48bf188730bf4e87ce7d0ce3aae Mon Sep 17 00:00:00 2001
From: tristan <tristan@yuno.malio.fr>
Date: Wed, 20 May 2026 08:13:37 +0200
Subject: [PATCH] =?UTF-8?q?docs=20:=20plan=20d'impl=C3=A9mentation=20du=20?=
 =?UTF-8?q?datepicker=20MalioDate=20(#MUI-33)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../plans/2026-05-20-datepicker.md            | 1440 +++++++++++++++++
 1 file changed, 1440 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-05-20-datepicker.md

diff --git a/docs/superpowers/plans/2026-05-20-datepicker.md b/docs/superpowers/plans/2026-05-20-datepicker.md
new file mode 100644
index 0000000..aa925c2
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-20-datepicker.md
@@ -0,0 +1,1440 @@
+# MalioDate (Datepicker) Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Composant `<MalioDate>` : champ readonly + popover calendrier (vue jours + vue mois), valeur ISO `YYYY-MM-DD`, bornes `min`/`max`, effacement.
+
+**Architecture:** Composant public `Date.vue` orchestrant 3 sous-composants internes (`CalendarHeader`, `MonthGrid`, `MonthPicker`) et 3 modules colocalisés (`dateFormat`, `useMonthMatrix`, `useCalendarPopover`). On construit du bas vers le haut : modules purs d'abord (TDD strict), puis sous-composants, puis composant public.
+
+**Tech Stack:** Nuxt 4 layer, Vue 3 `<script setup lang="ts">`, TypeScript strict, Tailwind (palette `m-*`), `tailwind-merge`, `@iconify/vue`, Vitest + `@vue/test-utils` (jsdom).
+
+**Répartition de travail :** L'utilisateur écrit l'implémentation. L'assistant écrit les tests. **Le test fait foi** : une implémentation est correcte dès qu'elle fait passer les tests de la tâche. Le code d'implémentation montré ci-dessous est une **référence** ; l'utilisateur peut l'adapter tant que les tests passent.
+
+**Référence spec :** `docs/superpowers/specs/2026-05-19-datepicker-design.md`
+
+---
+
+## Conventions partagées (à respecter par tests ET implémentation)
+
+**Attributs `data-test`** (ancrage des tests, n'apparaissent pas dans l'API publique) :
+
+| `data-test` | Élément |
+|---|---|
+| `date-input` | le champ `<input>` readonly |
+| `calendar-icon` | l'icône calendrier à droite |
+| `clear` | la croix d'effacement |
+| `popover` | conteneur du popover |
+| `header-prev` | chevron gauche du header |
+| `header-next` | chevron droit du header |
+| `header-toggle` | bouton central `Mois Année ⌄` |
+| `day` | une cellule jour cliquable (porte aussi `data-iso="YYYY-MM-DD"`) |
+| `week-number` | une cellule numéro de semaine |
+| `month` | une cellule mois dans `MonthPicker` (porte aussi `data-month="0..11"`) |
+
+**Libellés FR :**
+- Jours (en-tête grille) : `['Lun', 'Mar', 'Mer', 'Jeu', 'Ven', 'Sam', 'Dim']`
+- Mois courts (MonthPicker + header) : `['Janv', 'Févr', 'Mars', 'Avr', 'Mai', 'Juin', 'Juil', 'Août', 'Sept', 'Oct', 'Nov', 'Déc']`
+- Mois longs (header texte central) : `['janvier', 'février', 'mars', 'avril', 'mai', 'juin', 'juillet', 'août', 'septembre', 'octobre', 'novembre', 'décembre']`
+
+**Emplacement des fichiers :**
+```
+app/components/malio/date/
+  Date.vue
+  Date.test.ts
+  internal/
+    CalendarHeader.vue
+    MonthGrid.vue
+    MonthPicker.vue
+  composables/
+    dateFormat.ts
+    dateFormat.test.ts
+    useMonthMatrix.ts
+    useMonthMatrix.test.ts
+    useCalendarPopover.ts
+    useCalendarPopover.test.ts
+app/story/date/Date.story.vue
+.playground/pages/composant/date/date.vue
+```
+
+> Note : `vitest.config.ts` n'inclut que `app/**/*.test.ts`. Tous les tests vivent donc sous `app/` (les tests des composables sont bien dans `app/components/malio/date/composables/`). La page playground est auto-découverte par le glob `composant/**/*.vue` ; la catégorie de menu = nom du dossier (`date` → "Date"). **Aucune édition de `.playground/pages/index.vue` n'est nécessaire.**
+
+---
+
+## Task 1 : Module `dateFormat.ts` (fonctions pures)
+
+**Files:**
+- Create: `app/components/malio/date/composables/dateFormat.ts`
+- Test: `app/components/malio/date/composables/dateFormat.test.ts`
+
+- [ ] **Step 1 : Écrire les tests (échouent)** — *assistant*
+
+```ts
+import {describe, expect, it} from 'vitest'
+import {formatIsoToDisplay, isDateInRange, isValidIso, parseDisplayToIso} from './dateFormat'
+
+describe('dateFormat', () => {
+  describe('isValidIso', () => {
+    it('accepts a real ISO date', () => {
+      expect(isValidIso('2026-05-19')).toBe(true)
+    })
+    it('rejects a malformed string', () => {
+      expect(isValidIso('19/05/2026')).toBe(false)
+      expect(isValidIso('2026-5-9')).toBe(false)
+      expect(isValidIso('')).toBe(false)
+    })
+    it('rejects an impossible date', () => {
+      expect(isValidIso('2026-02-30')).toBe(false)
+      expect(isValidIso('2026-13-01')).toBe(false)
+    })
+    it('accepts Feb 29 on a leap year and rejects it otherwise', () => {
+      expect(isValidIso('2024-02-29')).toBe(true)
+      expect(isValidIso('2026-02-29')).toBe(false)
+    })
+  })
+
+  describe('formatIsoToDisplay', () => {
+    it('formats ISO to DD/MM/YYYY', () => {
+      expect(formatIsoToDisplay('2026-05-19')).toBe('19/05/2026')
+    })
+    it('returns empty string for null or invalid input', () => {
+      expect(formatIsoToDisplay(null)).toBe('')
+      expect(formatIsoToDisplay('nope')).toBe('')
+    })
+  })
+
+  describe('parseDisplayToIso', () => {
+    it('parses DD/MM/YYYY to ISO', () => {
+      expect(parseDisplayToIso('19/05/2026')).toBe('2026-05-19')
+    })
+    it('returns null for malformed or impossible input', () => {
+      expect(parseDisplayToIso('2026-05-19')).toBeNull()
+      expect(parseDisplayToIso('31/02/2026')).toBeNull()
+      expect(parseDisplayToIso('')).toBeNull()
+    })
+  })
+
+  describe('isDateInRange', () => {
+    it('returns true when no bounds are given', () => {
+      expect(isDateInRange('2026-05-19')).toBe(true)
+    })
+    it('respects the min bound (inclusive)', () => {
+      expect(isDateInRange('2026-05-19', '2026-05-19')).toBe(true)
+      expect(isDateInRange('2026-05-18', '2026-05-19')).toBe(false)
+    })
+    it('respects the max bound (inclusive)', () => {
+      expect(isDateInRange('2026-05-19', undefined, '2026-05-19')).toBe(true)
+      expect(isDateInRange('2026-05-20', undefined, '2026-05-19')).toBe(false)
+    })
+    it('respects both bounds', () => {
+      expect(isDateInRange('2026-05-15', '2026-05-10', '2026-05-20')).toBe(true)
+      expect(isDateInRange('2026-05-25', '2026-05-10', '2026-05-20')).toBe(false)
+    })
+  })
+})
+```
+
+- [ ] **Step 2 : Lancer les tests, vérifier l'échec**
+
+Run: `npm run test -- dateFormat`
+Expected: FAIL (`Failed to resolve import './dateFormat'`)
+
+- [ ] **Step 3 : Implémenter le module** — *utilisateur* (référence ci-dessous)
+
+```ts
+// app/components/malio/date/composables/dateFormat.ts
+
+export function isValidIso(iso: string): boolean {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(iso)) return false
+  const [y, m, d] = iso.split('-').map(Number)
+  const date = new Date(y, m - 1, d)
+  return date.getFullYear() === y && date.getMonth() === m - 1 && date.getDate() === d
+}
+
+export function formatIsoToDisplay(iso: string | null): string {
+  if (!iso || !isValidIso(iso)) return ''
+  const [y, m, d] = iso.split('-')
+  return `${d}/${m}/${y}`
+}
+
+export function parseDisplayToIso(display: string): string | null {
+  const match = /^(\d{2})\/(\d{2})\/(\d{4})$/.exec(display.trim())
+  if (!match) return null
+  const [, dd, mm, yyyy] = match
+  const iso = `${yyyy}-${mm}-${dd}`
+  return isValidIso(iso) ? iso : null
+}
+
+export function isDateInRange(iso: string, min?: string, max?: string): boolean {
+  if (min && iso < min) return false
+  if (max && iso > max) return false
+  return true
+}
+```
+
+- [ ] **Step 4 : Lancer les tests, vérifier le succès**
+
+Run: `npm run test -- dateFormat`
+Expected: PASS (toutes les assertions)
+
+- [ ] **Step 5 : Commit**
+
+```bash
+git add app/components/malio/date/composables/dateFormat.ts app/components/malio/date/composables/dateFormat.test.ts
+git commit -m "feat : utilitaires de format et validation de date (#MUI-33)"
+```
+
+---
+
+## Task 2 : Composable `useMonthMatrix.ts`
+
+**Files:**
+- Create: `app/components/malio/date/composables/useMonthMatrix.ts`
+- Test: `app/components/malio/date/composables/useMonthMatrix.test.ts`
+
+Types exportés :
+```ts
+export type DayCell = {
+  isoDate: string
+  day: number
+  isCurrentMonth: boolean
+  isToday: boolean
+}
+export type WeekRow = {
+  weekNumber: number
+  days: DayCell[]
+}
+```
+
+- [ ] **Step 1 : Écrire les tests (échouent)** — *assistant*
+
+```ts
+import {describe, expect, it, afterEach, beforeEach, vi} from 'vitest'
+import {ref} from 'vue'
+import {useMonthMatrix} from './useMonthMatrix'
+
+describe('useMonthMatrix', () => {
+  it('always produces 6 weeks of 7 days', () => {
+    const {weeks} = useMonthMatrix(ref(4), ref(2026)) // mai 2026
+    expect(weeks.value).toHaveLength(6)
+    weeks.value.forEach(week => expect(week.days).toHaveLength(7))
+  })
+
+  it('starts every week on a Monday', () => {
+    const {weeks} = useMonthMatrix(ref(4), ref(2026))
+    weeks.value.forEach(week => {
+      const first = new Date(`${week.days[0].isoDate}T00:00:00`)
+      expect(first.getDay()).toBe(1) // 1 = lundi
+    })
+  })
+
+  it('flags exactly the days of the current month', () => {
+    const {weeks} = useMonthMatrix(ref(4), ref(2026)) // mai = 31 jours
+    const currentMonthDays = weeks.value
+      .flatMap(w => w.days)
+      .filter(d => d.isCurrentMonth)
+    expect(currentMonthDays).toHaveLength(31)
+    expect(currentMonthDays.every(d => d.isoDate.startsWith('2026-05'))).toBe(true)
+  })
+
+  it('handles leap year February (29 days)', () => {
+    const {weeks} = useMonthMatrix(ref(1), ref(2024)) // février 2024
+    const days = weeks.value.flatMap(w => w.days).filter(d => d.isCurrentMonth)
+    expect(days).toHaveLength(29)
+  })
+
+  it('assigns ISO week 1 to the week containing Jan 4th', () => {
+    const {weeks} = useMonthMatrix(ref(0), ref(2026)) // janvier 2026
+    const weekWithJan4 = weeks.value.find(w =>
+      w.days.some(d => d.isoDate === '2026-01-04'),
+    )
+    expect(weekWithJan4?.weekNumber).toBe(1)
+  })
+
+  it('reacts to month/year changes', () => {
+    const month = ref(4)
+    const year = ref(2026)
+    const {weeks} = useMonthMatrix(month, year)
+    const mayCount = weeks.value.flatMap(w => w.days).filter(d => d.isCurrentMonth).length
+    month.value = 1 // février
+    year.value = 2024
+    const febCount = weeks.value.flatMap(w => w.days).filter(d => d.isCurrentMonth).length
+    expect(mayCount).toBe(31)
+    expect(febCount).toBe(29)
+  })
+
+  describe('isToday', () => {
+    beforeEach(() => {
+      vi.useFakeTimers()
+      vi.setSystemTime(new Date(2026, 4, 19)) // 19 mai 2026
+    })
+    afterEach(() => vi.useRealTimers())
+
+    it('flags only today', () => {
+      const {weeks} = useMonthMatrix(ref(4), ref(2026))
+      const todays = weeks.value.flatMap(w => w.days).filter(d => d.isToday)
+      expect(todays).toHaveLength(1)
+      expect(todays[0].isoDate).toBe('2026-05-19')
+    })
+  })
+})
+```
+
+- [ ] **Step 2 : Lancer les tests, vérifier l'échec**
+
+Run: `npm run test -- useMonthMatrix`
+Expected: FAIL (import non résolu)
+
+- [ ] **Step 3 : Implémenter le composable** — *utilisateur* (référence ci-dessous)
+
+```ts
+// app/components/malio/date/composables/useMonthMatrix.ts
+import {computed, type ComputedRef, type Ref} from 'vue'
+
+export type DayCell = {
+  isoDate: string
+  day: number
+  isCurrentMonth: boolean
+  isToday: boolean
+}
+export type WeekRow = {
+  weekNumber: number
+  days: DayCell[]
+}
+
+const toIso = (d: Date): string => {
+  const y = d.getFullYear()
+  const m = String(d.getMonth() + 1).padStart(2, '0')
+  const day = String(d.getDate()).padStart(2, '0')
+  return `${y}-${m}-${day}`
+}
+
+const isoWeek = (d: Date): number => {
+  const target = new Date(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()))
+  const dayNum = target.getUTCDay() || 7 // dimanche = 7
+  target.setUTCDate(target.getUTCDate() + 4 - dayNum) // jeudi de la semaine
+  const yearStart = new Date(Date.UTC(target.getUTCFullYear(), 0, 1))
+  return Math.ceil((((target.getTime() - yearStart.getTime()) / 86400000) + 1) / 7)
+}
+
+export function useMonthMatrix(
+  month: Ref<number>,
+  year: Ref<number>,
+): {weeks: ComputedRef<WeekRow[]>} {
+  const weeks = computed<WeekRow[]>(() => {
+    const todayIso = toIso(new Date())
+    const first = new Date(year.value, month.value, 1)
+    // recule jusqu'au lundi (getDay : 0 = dimanche)
+    const offset = (first.getDay() + 6) % 7
+    const start = new Date(year.value, month.value, 1 - offset)
+
+    const rows: WeekRow[] = []
+    const cursor = new Date(start)
+    for (let w = 0; w < 6; w++) {
+      const days: DayCell[] = []
+      for (let i = 0; i < 7; i++) {
+        const iso = toIso(cursor)
+        days.push({
+          isoDate: iso,
+          day: cursor.getDate(),
+          isCurrentMonth: cursor.getMonth() === month.value,
+          isToday: iso === todayIso,
+        })
+        cursor.setDate(cursor.getDate() + 1)
+      }
+      rows.push({weekNumber: isoWeek(new Date(`${days[0].isoDate}T00:00:00`)), days})
+    }
+    return rows
+  })
+
+  return {weeks}
+}
+```
+
+- [ ] **Step 4 : Lancer les tests, vérifier le succès**
+
+Run: `npm run test -- useMonthMatrix`
+Expected: PASS
+
+- [ ] **Step 5 : Commit**
+
+```bash
+git add app/components/malio/date/composables/useMonthMatrix.ts app/components/malio/date/composables/useMonthMatrix.test.ts
+git commit -m "feat : composable de matrice mensuelle avec n° de semaine ISO (#MUI-33)"
+```
+
+---
+
+## Task 3 : Composable `useCalendarPopover.ts`
+
+**Files:**
+- Create: `app/components/malio/date/composables/useCalendarPopover.ts`
+- Test: `app/components/malio/date/composables/useCalendarPopover.test.ts`
+
+- [ ] **Step 1 : Écrire les tests (échouent)** — *assistant*
+
+Le composable utilise `onMounted`/`onBeforeUnmount`, on le monte donc dans un composant hôte minimal pour avoir un contexte de cycle de vie.
+
+```ts
+import {describe, expect, it} from 'vitest'
+import {defineComponent, ref, h} from 'vue'
+import {mount} from '@vue/test-utils'
+import {useCalendarPopover} from './useCalendarPopover'
+
+const mountHost = () => {
+  const api: ReturnType<typeof useCalendarPopover> = {} as never
+  const Host = defineComponent({
+    setup() {
+      const root = ref<HTMLElement | null>(null)
+      Object.assign(api, useCalendarPopover(root))
+      return () => h('div', {ref: root}, 'host')
+    },
+  })
+  const wrapper = mount(Host, {attachTo: document.body})
+  return {wrapper, api}
+}
+
+describe('useCalendarPopover', () => {
+  it('starts closed in days view', () => {
+    const {api} = mountHost()
+    expect(api.isOpen.value).toBe(false)
+    expect(api.viewMode.value).toBe('days')
+  })
+
+  it('open() opens in days view', () => {
+    const {api} = mountHost()
+    api.open()
+    expect(api.isOpen.value).toBe(true)
+    expect(api.viewMode.value).toBe('days')
+  })
+
+  it('toggleView() switches between days and months', () => {
+    const {api} = mountHost()
+    api.open()
+    api.toggleView()
+    expect(api.viewMode.value).toBe('months')
+    api.toggleView()
+    expect(api.viewMode.value).toBe('days')
+  })
+
+  it('close() resets isOpen and viewMode', () => {
+    const {api} = mountHost()
+    api.open()
+    api.toggleView()
+    api.close()
+    expect(api.isOpen.value).toBe(false)
+    expect(api.viewMode.value).toBe('days')
+  })
+
+  it('closes on outside mousedown', async () => {
+    const {api} = mountHost()
+    api.open()
+    document.body.dispatchEvent(new MouseEvent('mousedown', {bubbles: true}))
+    expect(api.isOpen.value).toBe(false)
+  })
+
+  it('stays open on inside mousedown', async () => {
+    const {wrapper, api} = mountHost()
+    api.open()
+    wrapper.element.dispatchEvent(new MouseEvent('mousedown', {bubbles: true}))
+    expect(api.isOpen.value).toBe(true)
+  })
+})
+```
+
+- [ ] **Step 2 : Lancer les tests, vérifier l'échec**
+
+Run: `npm run test -- useCalendarPopover`
+Expected: FAIL (import non résolu)
+
+- [ ] **Step 3 : Implémenter le composable** — *utilisateur* (référence ci-dessous)
+
+```ts
+// app/components/malio/date/composables/useCalendarPopover.ts
+import {onBeforeUnmount, onMounted, ref, type Ref} from 'vue'
+
+export function useCalendarPopover(rootRef: Ref<HTMLElement | null>) {
+  const isOpen = ref(false)
+  const viewMode = ref<'days' | 'months'>('days')
+
+  const open = () => {
+    isOpen.value = true
+    viewMode.value = 'days'
+  }
+  const close = () => {
+    isOpen.value = false
+    viewMode.value = 'days'
+  }
+  const toggleView = () => {
+    viewMode.value = viewMode.value === 'days' ? 'months' : 'days'
+  }
+
+  const onMouseDown = (event: MouseEvent) => {
+    if (!isOpen.value || !rootRef.value) return
+    if (!rootRef.value.contains(event.target as Node)) close()
+  }
+
+  onMounted(() => document.addEventListener('mousedown', onMouseDown))
+  onBeforeUnmount(() => document.removeEventListener('mousedown', onMouseDown))
+
+  return {isOpen, viewMode, open, close, toggleView}
+}
+```
+
+- [ ] **Step 4 : Lancer les tests, vérifier le succès**
+
+Run: `npm run test -- useCalendarPopover`
+Expected: PASS
+
+- [ ] **Step 5 : Commit**
+
+```bash
+git add app/components/malio/date/composables/useCalendarPopover.ts app/components/malio/date/composables/useCalendarPopover.test.ts
+git commit -m "feat : composable d'état du popover calendrier (#MUI-33)"
+```
+
+---
+
+## Task 4 : Sous-composant `MonthGrid.vue`
+
+**Files:**
+- Create: `app/components/malio/date/internal/MonthGrid.vue`
+- Test: (couvert par `Date.test.ts` en Task 7 ; pas de test dédié pour ce sous-composant interne)
+
+Props : `month: number`, `year: number`, `selectedDate?: string | null`, `min?: string`, `max?: string`. Emit : `select` (payload `string` ISO).
+
+- [ ] **Step 1 : Implémenter le composant** — *utilisateur* (référence ci-dessous)
+
+```vue
+<template>
+  <div data-test="month-grid">
+    <div class="grid grid-cols-8">
+      <div class="flex h-8 items-center justify-center text-xs font-medium uppercase text-m-muted">
+        Sem
+      </div>
+      <div
+        v-for="d in dayLabels"
+        :key="d"
+        class="flex h-8 items-center justify-center text-xs font-medium uppercase text-m-muted"
+      >
+        {{ d }}
+      </div>
+
+      <template
+        v-for="week in weeks"
+        :key="week.days[0].isoDate"
+      >
+        <div
+          data-test="week-number"
+          class="flex h-10 items-center justify-center bg-m-primary/10 text-sm text-m-primary/70"
+        >
+          {{ week.weekNumber }}
+        </div>
+        <button
+          v-for="cell in week.days"
+          :key="cell.isoDate"
+          type="button"
+          data-test="day"
+          :data-iso="cell.isoDate"
+          :disabled="!inRange(cell.isoDate)"
+          :aria-label="ariaLabel(cell)"
+          :aria-disabled="!inRange(cell.isoDate)"
+          class="flex h-10 w-10 items-center justify-center text-sm transition-colors duration-100"
+          :class="cellClass(cell)"
+          @click="onSelect(cell.isoDate)"
+        >
+          {{ cell.day }}
+        </button>
+      </template>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import {computed, toRef} from 'vue'
+import {useMonthMatrix, type DayCell} from '../composables/useMonthMatrix'
+import {isDateInRange} from '../composables/dateFormat'
+
+defineOptions({name: 'MalioDateMonthGrid'})
+
+const props = withDefaults(
+  defineProps<{
+    month: number
+    year: number
+    selectedDate?: string | null
+    min?: string
+    max?: string
+  }>(),
+  {selectedDate: null, min: undefined, max: undefined},
+)
+
+const emit = defineEmits<{(e: 'select', iso: string): void}>()
+
+const dayLabels = ['Lun', 'Mar', 'Mer', 'Jeu', 'Ven', 'Sam', 'Dim']
+const monthsLong = ['janvier', 'février', 'mars', 'avril', 'mai', 'juin',
+  'juillet', 'août', 'septembre', 'octobre', 'novembre', 'décembre']
+
+const {weeks} = useMonthMatrix(toRef(props, 'month'), toRef(props, 'year'))
+
+const inRange = (iso: string) => isDateInRange(iso, props.min, props.max)
+
+const ariaLabel = (cell: DayCell) => {
+  const [, m, d] = cell.isoDate.split('-')
+  return `${Number(d)} ${monthsLong[Number(m) - 1]} ${cell.isoDate.slice(0, 4)}`
+}
+
+const cellClass = (cell: DayCell) => {
+  const selected = props.selectedDate === cell.isoDate
+  if (!inRange(cell.isoDate)) return 'text-m-muted/30 cursor-not-allowed'
+  if (selected) return 'bg-m-primary text-white font-medium rounded-full'
+  const parts = ['cursor-pointer hover:bg-m-primary/10 rounded-full']
+  if (cell.isToday) parts.push('border border-m-primary text-m-primary font-semibold')
+  else if (cell.isCurrentMonth) parts.push('text-black')
+  else parts.push('text-m-muted/50')
+  return parts.join(' ')
+}
+
+const onSelect = (iso: string) => {
+  if (!inRange(iso)) return
+  emit('select', iso)
+}
+</script>
+```
+
+- [ ] **Step 2 : Vérifier le lint**
+
+Run: `npm run lint`
+Expected: aucune nouvelle erreur (les warnings préexistants sont tolérés)
+
+- [ ] **Step 3 : Commit**
+
+```bash
+git add app/components/malio/date/internal/MonthGrid.vue
+git commit -m "feat : grille mensuelle du datepicker (#MUI-33)"
+```
+
+---
+
+## Task 5 : Sous-composant `CalendarHeader.vue`
+
+**Files:**
+- Create: `app/components/malio/date/internal/CalendarHeader.vue`
+
+Props : `viewMode: 'days' | 'months'`, `currentMonth: number`, `currentYear: number`. Emits : `prev`, `next`, `toggle-view`.
+
+- [ ] **Step 1 : Implémenter le composant** — *utilisateur* (référence ci-dessous)
+
+```vue
+<template>
+  <div class="flex h-12 items-center justify-between border-b border-m-primary/20 px-2">
+    <button
+      type="button"
+      data-test="header-prev"
+      class="rounded p-2 hover:bg-m-primary/10"
+      :aria-label="viewMode === 'days' ? 'Mois précédent' : 'Année précédente'"
+      @click="emit('prev')"
+    >
+      <Icon icon="mdi:chevron-left" :width="20" :height="20" />
+    </button>
+
+    <button
+      type="button"
+      data-test="header-toggle"
+      class="flex items-center gap-1 rounded px-2 py-1 text-base font-medium hover:bg-m-primary/10"
+      @click="emit('toggle-view')"
+    >
+      {{ label }}
+      <Icon icon="mdi:chevron-down" :width="16" :height="16" />
+    </button>
+
+    <button
+      type="button"
+      data-test="header-next"
+      class="rounded p-2 hover:bg-m-primary/10"
+      :aria-label="viewMode === 'days' ? 'Mois suivant' : 'Année suivante'"
+      @click="emit('next')"
+    >
+      <Icon icon="mdi:chevron-right" :width="20" :height="20" />
+    </button>
+  </div>
+</template>
+
+<script setup lang="ts">
+import {computed} from 'vue'
+import {Icon} from '@iconify/vue'
+
+defineOptions({name: 'MalioDateCalendarHeader'})
+
+const props = defineProps<{
+  viewMode: 'days' | 'months'
+  currentMonth: number
+  currentYear: number
+}>()
+
+const emit = defineEmits<{
+  (e: 'prev' | 'next' | 'toggle-view'): void
+}>()
+
+const monthsLong = ['janvier', 'février', 'mars', 'avril', 'mai', 'juin',
+  'juillet', 'août', 'septembre', 'octobre', 'novembre', 'décembre']
+
+const label = computed(() => {
+  const name = monthsLong[props.currentMonth]
+  return `${name.charAt(0).toUpperCase()}${name.slice(1)} ${props.currentYear}`
+})
+</script>
+```
+
+- [ ] **Step 2 : Vérifier le lint**
+
+Run: `npm run lint`
+Expected: aucune nouvelle erreur
+
+- [ ] **Step 3 : Commit**
+
+```bash
+git add app/components/malio/date/internal/CalendarHeader.vue
+git commit -m "feat : header de navigation du datepicker (#MUI-33)"
+```
+
+---
+
+## Task 6 : Sous-composant `MonthPicker.vue`
+
+**Files:**
+- Create: `app/components/malio/date/internal/MonthPicker.vue`
+
+Props : `selectedMonth?: number`. Emit : `select` (payload `number` 0-11).
+
+- [ ] **Step 1 : Implémenter le composant** — *utilisateur* (référence ci-dessous)
+
+```vue
+<template>
+  <div
+    data-test="month-picker"
+    class="grid grid-cols-4 gap-2 p-3"
+  >
+    <button
+      v-for="(name, index) in monthsShort"
+      :key="name"
+      type="button"
+      data-test="month"
+      :data-month="index"
+      class="rounded py-3 text-sm transition-colors duration-100"
+      :class="index === selectedMonth
+        ? 'bg-m-primary text-white'
+        : 'text-black hover:bg-m-primary/10'"
+      @click="emit('select', index)"
+    >
+      {{ name }}
+    </button>
+  </div>
+</template>
+
+<script setup lang="ts">
+defineOptions({name: 'MalioDateMonthPicker'})
+
+defineProps<{selectedMonth?: number}>()
+
+const emit = defineEmits<{(e: 'select', month: number): void}>()
+
+const monthsShort = ['Janv', 'Févr', 'Mars', 'Avr', 'Mai', 'Juin',
+  'Juil', 'Août', 'Sept', 'Oct', 'Nov', 'Déc']
+</script>
+```
+
+- [ ] **Step 2 : Vérifier le lint**
+
+Run: `npm run lint`
+Expected: aucune nouvelle erreur
+
+- [ ] **Step 3 : Commit**
+
+```bash
+git add app/components/malio/date/internal/MonthPicker.vue
+git commit -m "feat : sélecteur de mois du datepicker (#MUI-33)"
+```
+
+---
+
+## Task 7 : Composant public `Date.vue` + tests d'intégration
+
+**Files:**
+- Create: `app/components/malio/date/Date.vue`
+- Test: `app/components/malio/date/Date.test.ts`
+
+- [ ] **Step 1 : Implémenter le composant** — *utilisateur* (référence ci-dessous)
+
+```vue
+<template>
+  <div>
+    <div
+      ref="root"
+      :class="mergedGroupClass"
+    >
+      <input
+        :id="inputId"
+        :name="name"
+        data-test="date-input"
+        readonly
+        autocomplete="off"
+        :class="mergedInputClass"
+        :required="required"
+        :disabled="disabled"
+        :value="displayValue"
+        :aria-invalid="!!error"
+        :aria-describedby="describedBy"
+        :aria-expanded="isOpen"
+        aria-haspopup="dialog"
+        v-bind="attrs"
+        placeholder="_"
+        type="text"
+        @click="onFieldClick"
+      >
+
+      <label
+        v-if="label"
+        :for="inputId"
+        :class="mergedLabelClass"
+      >
+        {{ label }}
+      </label>
+
+      <div class="absolute right-3 top-1/2 flex -translate-y-1/2 items-center gap-1">
+        <button
+          v-if="showClear"
+          type="button"
+          data-test="clear"
+          class="text-m-muted hover:text-black"
+          aria-label="Effacer la date"
+          @click.stop="onClear"
+        >
+          <Icon icon="mdi:close" :width="16" :height="16" />
+        </button>
+        <Icon
+          data-test="calendar-icon"
+          icon="mdi:calendar-outline"
+          :width="20"
+          :height="20"
+          :class="iconStateClass"
+        />
+      </div>
+
+      <div
+        v-if="isOpen"
+        data-test="popover"
+        role="dialog"
+        class="absolute left-0 top-[calc(100%-4px)] z-20 min-w-[320px] rounded-b-md border border-t-0 bg-white"
+        :class="popoverBorderClass"
+      >
+        <CalendarHeader
+          :view-mode="viewMode"
+          :current-month="currentMonth"
+          :current-year="currentYear"
+          @prev="onPrev"
+          @next="onNext"
+          @toggle-view="toggleView"
+        />
+        <MonthGrid
+          v-if="viewMode === 'days'"
+          :month="currentMonth"
+          :year="currentYear"
+          :selected-date="modelValue ?? null"
+          :min="min"
+          :max="max"
+          @select="onSelectDay"
+        />
+        <MonthPicker
+          v-else
+          :selected-month="currentMonth"
+          @select="onSelectMonth"
+        />
+      </div>
+    </div>
+
+    <p
+      v-if="hint || hasError || hasSuccess"
+      :id="`${inputId}-describedby`"
+      :class="[
+        hasError ? 'text-m-danger' : hasSuccess ? 'text-m-success' : 'text-m-muted',
+        'mt-1 ml-[2px] text-xs',
+      ]"
+    >
+      {{ error || success || hint }}
+    </p>
+  </div>
+</template>
+
+<script setup lang="ts">
+import {computed, ref, useAttrs, useId, watch} from 'vue'
+import {Icon} from '@iconify/vue'
+import {twMerge} from 'tailwind-merge'
+import CalendarHeader from './internal/CalendarHeader.vue'
+import MonthGrid from './internal/MonthGrid.vue'
+import MonthPicker from './internal/MonthPicker.vue'
+import {useCalendarPopover} from './composables/useCalendarPopover'
+import {formatIsoToDisplay, isValidIso} from './composables/dateFormat'
+
+defineOptions({name: 'MalioDate', inheritAttrs: false})
+
+const props = withDefaults(
+  defineProps<{
+    id?: string
+    name?: string
+    label?: string
+    modelValue?: string | null
+    placeholder?: string
+    required?: boolean
+    disabled?: boolean
+    readonly?: boolean
+    hint?: string
+    error?: string
+    success?: string
+    min?: string
+    max?: string
+    clearable?: boolean
+    inputClass?: string
+    labelClass?: string
+    groupClass?: string
+  }>(),
+  {
+    id: '', name: '', label: '', modelValue: undefined, placeholder: 'JJ/MM/AAAA',
+    required: false, disabled: false, readonly: false, hint: '', error: '', success: '',
+    min: undefined, max: undefined, clearable: true,
+    inputClass: '', labelClass: '', groupClass: '',
+  },
+)
+
+const emit = defineEmits<{(e: 'update:modelValue', value: string | null): void}>()
+
+const attrs = useAttrs()
+const generatedId = useId()
+const root = ref<HTMLElement | null>(null)
+
+const {isOpen, viewMode, open, close, toggleView} = useCalendarPopover(root)
+
+const today = new Date()
+const currentMonth = ref(today.getMonth())
+const currentYear = ref(today.getFullYear())
+
+const inputId = computed(() => props.id?.toString() || `malio-date-${generatedId}`)
+const hasError = computed(() => !!props.error)
+const hasSuccess = computed(() => !!props.success && !hasError.value)
+const displayValue = computed(() => formatIsoToDisplay(props.modelValue ?? null))
+const isFilled = computed(() => displayValue.value.length > 0)
+
+const showClear = computed(() =>
+  props.clearable && isFilled.value && !props.disabled && !props.readonly,
+)
+
+const describedBy = computed(() =>
+  (props.hint || hasError.value || hasSuccess.value) ? `${inputId.value}-describedby` : undefined,
+)
+
+const syncViewToValue = () => {
+  const iso = props.modelValue
+  if (iso && isValidIso(iso)) {
+    currentMonth.value = Number(iso.slice(5, 7)) - 1
+    currentYear.value = Number(iso.slice(0, 4))
+  } else {
+    const now = new Date()
+    currentMonth.value = now.getMonth()
+    currentYear.value = now.getFullYear()
+  }
+}
+
+watch(() => props.modelValue, (val) => {
+  if (val && !isValidIso(val) && import.meta.dev) {
+    console.warn(`[MalioDate] modelValue invalide ignoré : "${val}"`)
+  }
+  if (isOpen.value) syncViewToValue()
+})
+
+const onFieldClick = () => {
+  if (props.disabled || props.readonly) return
+  if (isOpen.value) {
+    close()
+    return
+  }
+  syncViewToValue()
+  open()
+}
+
+const onClear = () => emit('update:modelValue', null)
+
+const onSelectDay = (iso: string) => {
+  emit('update:modelValue', iso)
+  close()
+}
+
+const onSelectMonth = (month: number) => {
+  currentMonth.value = month
+  toggleView()
+}
+
+const onPrev = () => {
+  if (viewMode.value === 'months') {
+    currentYear.value -= 1
+    return
+  }
+  if (currentMonth.value === 0) {
+    currentMonth.value = 11
+    currentYear.value -= 1
+  } else {
+    currentMonth.value -= 1
+  }
+}
+
+const onNext = () => {
+  if (viewMode.value === 'months') {
+    currentYear.value += 1
+    return
+  }
+  if (currentMonth.value === 11) {
+    currentMonth.value = 0
+    currentYear.value += 1
+  } else {
+    currentMonth.value += 1
+  }
+}
+
+const mergedGroupClass = computed(() =>
+  twMerge('relative flex h-12 w-full items-center', props.groupClass),
+)
+
+const mergedInputClass = computed(() =>
+  twMerge(
+    'floating-input peer min-h-[40px] w-full cursor-pointer rounded-md border bg-white py-1 pl-3 pr-10 text-lg outline-none placeholder:text-transparent',
+    isFilled.value ? 'border-black' : 'border-m-muted',
+    props.disabled ? 'cursor-not-allowed text-black/60 border-m-muted' : '',
+    hasError.value
+      ? 'border-m-danger'
+      : hasSuccess.value
+        ? 'border-m-success'
+        : 'focus:border-m-primary',
+    isOpen.value ? '!rounded-b-none !border-b-0 border-m-primary' : '',
+    props.inputClass,
+  ),
+)
+
+const mergedLabelClass = computed(() =>
+  twMerge(
+    'floating-label absolute left-3 top-2 mt-[5px] inline-block origin-left font-medium text-sm transition-transform duration-150',
+    (isFilled.value || isOpen.value) ? '-translate-y-[1.25rem] scale-90' : '',
+    hasError.value
+      ? 'text-m-danger'
+      : hasSuccess.value
+        ? 'text-m-success'
+        : 'peer-placeholder-shown:text-m-muted text-black',
+    props.labelClass,
+  ),
+)
+
+const iconStateClass = computed(() => {
+  if (hasError.value) return 'text-m-danger'
+  if (hasSuccess.value) return 'text-m-success'
+  if (isOpen.value) return 'text-m-primary'
+  if (isFilled.value) return 'text-black'
+  return 'text-m-muted'
+})
+
+const popoverBorderClass = computed(() =>
+  hasError.value ? 'border-m-danger' : hasSuccess.value ? 'border-m-success' : 'border-m-primary',
+)
+</script>
+
+<style scoped>
+.floating-label {
+  background: white;
+  padding: 0 0.25rem;
+}
+</style>
+```
+
+- [ ] **Step 2 : Écrire les tests d'intégration (échouent au départ si lancés avant l'impl)** — *assistant*
+
+```ts
+import {describe, expect, it, beforeEach, afterEach, vi} from 'vitest'
+import {mount} from '@vue/test-utils'
+import type {DefineComponent} from 'vue'
+import Date_ from './Date.vue'
+
+type DateProps = {
+  id?: string
+  name?: string
+  label?: string
+  modelValue?: string | null
+  placeholder?: string
+  required?: boolean
+  disabled?: boolean
+  readonly?: boolean
+  hint?: string
+  error?: string
+  success?: string
+  min?: string
+  max?: string
+  clearable?: boolean
+  inputClass?: string
+  labelClass?: string
+  groupClass?: string
+}
+
+const DateForTest = Date_ as DefineComponent<DateProps>
+const mountDate = (props: DateProps = {}) => mount(DateForTest, {props, attachTo: document.body})
+
+describe('MalioDate', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date(2026, 4, 19)) // 19 mai 2026
+  })
+  afterEach(() => vi.useRealTimers())
+
+  describe('rendu', () => {
+    it('renders the label and the calendar icon', () => {
+      const wrapper = mountDate({label: 'Date de naissance'})
+      expect(wrapper.get('label').text()).toBe('Date de naissance')
+      expect(wrapper.find('[data-test="calendar-icon"]').exists()).toBe(true)
+    })
+
+    it('displays the formatted value in the field', () => {
+      const wrapper = mountDate({modelValue: '2026-05-19'})
+      const input = wrapper.get('[data-test="date-input"]').element as HTMLInputElement
+      expect(input.value).toBe('19/05/2026')
+    })
+
+    it('does not show the popover initially', () => {
+      const wrapper = mountDate()
+      expect(wrapper.find('[data-test="popover"]').exists()).toBe(false)
+    })
+  })
+
+  describe('popover', () => {
+    it('opens on field click', async () => {
+      const wrapper = mountDate()
+      await wrapper.get('[data-test="date-input"]').trigger('click')
+      expect(wrapper.find('[data-test="popover"]').exists()).toBe(true)
+    })
+
+    it('opens on the current month when there is no value', async () => {
+      const wrapper = mountDate()
+      await wrapper.get('[data-test="date-input"]').trigger('click')
+      expect(wrapper.get('[data-test="header-toggle"]').text()).toContain('Mai 2026')
+    })
+
+    it('opens on the value month when a value is set', async () => {
+      const wrapper = mountDate({modelValue: '2025-12-25'})
+      await wrapper.get('[data-test="date-input"]').trigger('click')
+      expect(wrapper.get('[data-test="header-toggle"]').text()).toContain('Décembre 2025')
+    })
+
+    it('closes on outside mousedown', async () => {
+      const wrapper = mountDate()
+      await wrapper.get('[data-test="date-input"]').trigger('click')
+      document.body.dispatchEvent(new MouseEvent('mousedown', {bubbles: true}))
+      await wrapper.vm.$nextTick()
+      expect(wrapper.find('[data-test="popover"]').exists()).toBe(false)
+    })
+  })
+
+  describe('navigation jours', () => {
+    it('goes to the next month on the right chevron', async () => {
+      const wrapper = mountDate()
+      await wrapper.get('[data-test="date-input"]').trigger('click')
+      await wrapper.get('[data-test="header-next"]').trigger('click')
+      expect(wrapper.get('[data-test="header-toggle"]').text()).toContain('Juin 2026')
+    })
+
+    it('rolls December to January and bumps the year', async () => {
+      const wrapper = mountDate({modelValue: '2026-12-15'})
+      await wrapper.get('[data-test="date-input"]').trigger('click')
+      await wrapper.get('[data-test="header-next"]').trigger('click')
+      expect(wrapper.get('[data-test="header-toggle"]').text()).toContain('Janvier 2027')
+    })
+  })
+
+  describe('sélection', () => {
+    it('emits the ISO date and closes on day click', async () => {
+      const wrapper = mountDate()
+      await wrapper.get('[data-test="date-input"]').trigger('click')
+      await wrapper.get('[data-test="day"][data-iso="2026-05-19"]').trigger('click')
+      expect(wrapper.emitted('update:modelValue')?.at(-1)).toEqual(['2026-05-19'])
+      expect(wrapper.find('[data-test="popover"]').exists()).toBe(false)
+    })
+  })
+
+  describe('bornes min/max', () => {
+    it('disables days outside the range', async () => {
+      const wrapper = mountDate({min: '2026-05-10', max: '2026-05-20'})
+      await wrapper.get('[data-test="date-input"]').trigger('click')
+      const outside = wrapper.get('[data-test="day"][data-iso="2026-05-05"]')
+      expect((outside.element as HTMLButtonElement).disabled).toBe(true)
+      await outside.trigger('click')
+      expect(wrapper.emitted('update:modelValue')).toBeUndefined()
+    })
+  })
+
+  describe('vue mois', () => {
+    it('switches to month view on header toggle', async () => {
+      const wrapper = mountDate()
+      await wrapper.get('[data-test="date-input"]').trigger('click')
+      await wrapper.get('[data-test="header-toggle"]').trigger('click')
+      expect(wrapper.find('[data-test="month-picker"]').exists()).toBe(true)
+    })
+
+    it('navigates the year with chevrons in month view', async () => {
+      const wrapper = mountDate()
+      await wrapper.get('[data-test="date-input"]').trigger('click')
+      await wrapper.get('[data-test="header-toggle"]').trigger('click')
+      await wrapper.get('[data-test="header-next"]').trigger('click')
+      expect(wrapper.get('[data-test="header-toggle"]').text()).toContain('2027')
+    })
+
+    it('returns to day view on month click', async () => {
+      const wrapper = mountDate()
+      await wrapper.get('[data-test="date-input"]').trigger('click')
+      await wrapper.get('[data-test="header-toggle"]').trigger('click')
+      await wrapper.get('[data-test="month"][data-month="0"]').trigger('click')
+      expect(wrapper.find('[data-test="month-picker"]').exists()).toBe(false)
+      expect(wrapper.get('[data-test="header-toggle"]').text()).toContain('Janvier 2026')
+      expect(wrapper.emitted('update:modelValue')).toBeUndefined()
+    })
+  })
+
+  describe('effacement', () => {
+    it('shows the clear button when there is a value', () => {
+      const wrapper = mountDate({modelValue: '2026-05-19'})
+      expect(wrapper.find('[data-test="clear"]').exists()).toBe(true)
+    })
+
+    it('hides the clear button when empty', () => {
+      const wrapper = mountDate()
+      expect(wrapper.find('[data-test="clear"]').exists()).toBe(false)
+    })
+
+    it('emits null and does not open the popover on clear', async () => {
+      const wrapper = mountDate({modelValue: '2026-05-19'})
+      await wrapper.get('[data-test="clear"]').trigger('click')
+      expect(wrapper.emitted('update:modelValue')?.at(-1)).toEqual([null])
+      expect(wrapper.find('[data-test="popover"]').exists()).toBe(false)
+    })
+  })
+
+  describe('états', () => {
+    it('does not open when disabled', async () => {
+      const wrapper = mountDate({disabled: true})
+      await wrapper.get('[data-test="date-input"]').trigger('click')
+      expect(wrapper.find('[data-test="popover"]').exists()).toBe(false)
+    })
+
+    it('does not open when readonly', async () => {
+      const wrapper = mountDate({readonly: true, modelValue: '2026-05-19'})
+      await wrapper.get('[data-test="date-input"]').trigger('click')
+      expect(wrapper.find('[data-test="popover"]').exists()).toBe(false)
+    })
+  })
+
+  describe('accessibilité', () => {
+    it('sets aria-invalid and describedby on error', () => {
+      const wrapper = mountDate({error: 'Date requise'})
+      const input = wrapper.get('[data-test="date-input"]')
+      expect(input.attributes('aria-invalid')).toBe('true')
+      expect(input.attributes('aria-describedby')).toBeTruthy()
+      expect(wrapper.text()).toContain('Date requise')
+    })
+  })
+
+  describe('synchronisation externe', () => {
+    it('updates the displayed value when modelValue changes', async () => {
+      const wrapper = mountDate({modelValue: '2026-05-19'})
+      await wrapper.setProps({modelValue: '2026-12-25'})
+      const input = wrapper.get('[data-test="date-input"]').element as HTMLInputElement
+      expect(input.value).toBe('25/12/2026')
+    })
+  })
+})
+```
+
+- [ ] **Step 3 : Lancer les tests, vérifier le succès**
+
+Run: `npm run test -- Date`
+Expected: PASS (toutes les assertions). Si un test échoue, ajuster l'implémentation (les tests sont le contrat).
+
+- [ ] **Step 4 : Vérifier le lint et la suite complète**
+
+Run: `npm run lint && npm run test`
+Expected: 0 erreur de lint nouvelle ; toute la suite verte.
+
+- [ ] **Step 5 : Commit**
+
+```bash
+git add app/components/malio/date/Date.vue app/components/malio/date/Date.test.ts
+git commit -m "feat : composant MalioDate (datepicker) (#MUI-33)"
+```
+
+---
+
+## Task 8 : Story Histoire + page Playground
+
+**Files:**
+- Create: `app/story/date/Date.story.vue`
+- Create: `.playground/pages/composant/date/date.vue`
+
+- [ ] **Step 1 : Créer la story** — *utilisateur* (référence ci-dessous)
+
+```vue
+<template>
+  <Story title="Date/Date">
+    <div class="grid grid-cols-1 items-start gap-6 md:grid-cols-2">
+      <div class="rounded-lg border p-4">
+        <h2 class="mb-4 text-xl font-bold">Simple</h2>
+        <MalioDate v-model="simpleValue" label="Date de naissance" />
+      </div>
+
+      <div class="rounded-lg border p-4">
+        <h2 class="mb-4 text-xl font-bold">Valeur initiale</h2>
+        <MalioDate v-model="initialValue" label="Date du jour" />
+      </div>
+
+      <div class="rounded-lg border p-4">
+        <h2 class="mb-4 text-xl font-bold">Avec min/max</h2>
+        <MalioDate
+          v-model="boundedValue"
+          label="Date du rendez-vous"
+          :min="todayIso"
+          :max="maxIso"
+          hint="Entre aujourd'hui et +30 jours"
+        />
+      </div>
+
+      <div class="rounded-lg border p-4">
+        <h2 class="mb-4 text-xl font-bold">Non effaçable</h2>
+        <MalioDate v-model="initialValue" label="Date verrouillée" :clearable="false" />
+      </div>
+
+      <div class="rounded-lg border p-4">
+        <h2 class="mb-4 text-xl font-bold">Désactivé</h2>
+        <MalioDate v-model="initialValue" label="Désactivé" disabled />
+      </div>
+
+      <div class="rounded-lg border p-4">
+        <h2 class="mb-4 text-xl font-bold">Lecture seule</h2>
+        <MalioDate v-model="initialValue" label="Lecture seule" readonly />
+      </div>
+
+      <div class="rounded-lg border p-4">
+        <h2 class="mb-4 text-xl font-bold">Erreur</h2>
+        <MalioDate v-model="errorValue" label="Date limite" error="Date invalide" />
+      </div>
+
+      <div class="rounded-lg border p-4">
+        <h2 class="mb-4 text-xl font-bold">Succès</h2>
+        <MalioDate v-model="initialValue" label="Date confirmée" success="Enregistrée" />
+      </div>
+    </div>
+  </Story>
+</template>
+
+<script setup lang="ts">
+import {ref} from 'vue'
+import MalioDate from '../../components/malio/date/Date.vue'
+
+const pad = (n: number) => String(n).padStart(2, '0')
+const toIso = (d: Date) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`
+
+const now = new Date()
+const todayIso = toIso(now)
+const maxIso = toIso(new Date(now.getTime() + 30 * 86400000))
+
+const simpleValue = ref<string | null>(null)
+const initialValue = ref<string | null>(todayIso)
+const boundedValue = ref<string | null>(null)
+const errorValue = ref<string | null>(null)
+</script>
+```
+
+- [ ] **Step 2 : Créer la page playground** — *utilisateur* (référence ci-dessous)
+
+```vue
+<template>
+  <div class="max-w-md space-y-6">
+    <h1 class="text-2xl font-bold">MalioDate</h1>
+
+    <MalioDate
+      v-model="value"
+      label="Date de naissance"
+      hint="Clique pour ouvrir le calendrier"
+    />
+
+    <div class="rounded border p-3 text-sm">
+      <p>Valeur (ISO) : <code>{{ value ?? 'null' }}</code></p>
+    </div>
+
+    <div class="flex gap-2">
+      <button
+        type="button"
+        class="rounded bg-m-primary px-3 py-1.5 text-white"
+        @click="value = '2026-12-25'"
+      >
+        Forcer le 25/12/2026
+      </button>
+      <button
+        type="button"
+        class="rounded border px-3 py-1.5"
+        @click="value = null"
+      >
+        Réinitialiser
+      </button>
+    </div>
+
+    <MalioDate
+      v-model="bounded"
+      label="Date bornée"
+      :min="todayIso"
+      :max="maxIso"
+      hint="Entre aujourd'hui et +30 jours"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import {ref} from 'vue'
+
+const pad = (n: number) => String(n).padStart(2, '0')
+const toIso = (d: Date) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`
+const now = new Date()
+const todayIso = toIso(now)
+const maxIso = toIso(new Date(now.getTime() + 30 * 86400000))
+
+const value = ref<string | null>(null)
+const bounded = ref<string | null>(null)
+</script>
+```
+
+- [ ] **Step 3 : Vérification visuelle manuelle**
+
+Run: `npm run dev` (playground) puis ouvrir la page "Date" du menu.
+Vérifier : ouverture/fermeture, navigation mois, bascule vue mois, sélection, effacement, bornes grisées, état error/disabled/readonly.
+Run aussi : `npm run story:dev` pour la story Histoire.
+
+- [ ] **Step 4 : Lint final**
+
+Run: `npm run lint`
+Expected: aucune nouvelle erreur.
+
+- [ ] **Step 5 : Commit**
+
+```bash
+git add app/story/date/Date.story.vue .playground/pages/composant/date/date.vue
+git commit -m "feat : story et page playground du datepicker (#MUI-33)"
+```
+
+---
+
+## Self-Review (effectuée à l'écriture du plan)
+
+**Couverture spec :** modelValue ISO ✓ (T1), props/emits ✓ (T7), CalendarHeader ✓ (T5), MonthGrid + colonne semaine + min/max + today/sélection ✓ (T4), MonthPicker ✓ (T6), composables ✓ (T1-3), comportements ouverture/sélection/navigation/vue mois/fermeture/clear/états/synchro ✓ (T7 tests), a11y `aria-*` ✓ (T7), tests ✓ (T1-3, T7), story ✓ (T8), playground ✓ (T8). Reportés v2 (clavier, vue années, disabledDates, saisie éditable) : non planifiés, conforme.
+
+**Placeholders :** aucun TODO/TBD ; tout le code de référence est complet.
+
+**Cohérence des types :** `DayCell`/`WeekRow` définis en T2 et réutilisés en T4. `useCalendarPopover` renvoie `{isOpen, viewMode, open, close, toggleView}` (T3) — consommés tels quels en T7. `data-test` cohérents entre composants (T4-6) et tests (T7). Emit `select` (ISO string en T4, number en T6) consommés correctement par T7 (`onSelectDay`/`onSelectMonth`).
+
+**Écart assumé vs spec :** la spec mentionnait "lien ajouté dans index.vue" pour le playground ; en réalité le menu est auto-globé → aucune édition manuelle requise (noté en tête de plan).