Merge branch 'develop' into feature/MUI-33-developper-le-composant-datepicker
This commit is contained in:
146
docs/superpowers/specs/2026-05-21-drawer-redesign-design.md
Normal file
146
docs/superpowers/specs/2026-05-21-drawer-redesign-design.md
Normal file
@@ -0,0 +1,146 @@
|
||||
# Refonte du composant `<MalioDrawer>` — Design
|
||||
|
||||
> Ticket : MUI-35 — Revoir le design du composant Drawer
|
||||
> Date : 2026-05-21
|
||||
> Statut : design validé, à implémenter
|
||||
|
||||
## Contexte & problème
|
||||
|
||||
Le `<MalioDrawer>` actuel fait le strict minimum et ne tient pas la comparaison
|
||||
avec les drawers des libs modernes (shadcn/Sheet, PrimeVue, Element Plus, Nuxt UI) :
|
||||
|
||||
- glisse **uniquement depuis la droite**, pas de choix de côté ;
|
||||
- **un seul slot** (le contenu), pas de header/footer structurés ;
|
||||
- **aucune accessibilité réelle** : pas de focus-trap, pas de restitution du focus,
|
||||
pas de fermeture au clavier (Échap) ;
|
||||
- **pas de scroll-lock** du body quand le drawer est ouvert.
|
||||
|
||||
Objectif : refondre le composant en gardant l'esprit du layer Malio
|
||||
(hand-rollé, 1 composant `.vue`, props communes, `twMerge`), sans introduire de
|
||||
dépendance ni refondre les autres composants.
|
||||
|
||||
## Décisions structurantes
|
||||
|
||||
- **Hand-rollé**, pas de dépendance type Reka UI. Cohérence avec le reste du layer.
|
||||
- **Un seul composant** `<MalioDrawer>` (props + slots). Pas de primitives composables.
|
||||
- **Breaking change assumé** → bump de version **majeure** via semantic-release.
|
||||
Les apps consommatrices migreront (cf. section Migration).
|
||||
- Périmètre : **le drawer uniquement**. Les autres composants ne bougent pas.
|
||||
|
||||
## API
|
||||
|
||||
### Slots
|
||||
|
||||
| Slot | Rôle |
|
||||
|------|------|
|
||||
| `#header` | Contenu d'en-tête (titre + ce que veut le consommateur). **Aucune prop `title`.** |
|
||||
| _défaut_ | Le body, dans la zone scrollable. |
|
||||
| `#footer` | Rendu **dans la zone scrollable**, juste après le body. **Aucune classe de positionnement imposée.** |
|
||||
|
||||
### Props
|
||||
|
||||
| Prop | Type | Défaut | Rôle |
|
||||
|------|------|--------|------|
|
||||
| `modelValue` | `boolean` | `undefined` | v-model d'ouverture (pattern contrôlé/non-contrôlé Malio) |
|
||||
| `id` | `string` | `''` (auto) | id du composant |
|
||||
| `side` | `'right' \| 'left'` | `'right'` | côté d'apparition |
|
||||
| `showClose` | `boolean` | `true` | affiche le bouton de fermeture (croix) |
|
||||
| `dismissable` | `boolean` | `true` | clic sur le backdrop ferme le drawer |
|
||||
| `closeOnEscape` | `boolean` | `true` | touche Échap ferme le drawer |
|
||||
| `ariaLabel` | `string` | `''` | nom accessible de secours quand `#header` est absent |
|
||||
| `drawerClass` | `string` | `''` | override du panneau (largeur réglée ici, ex. `max-w-2xl`) |
|
||||
| `overlayClass` | `string` | `''` | override du backdrop |
|
||||
| `headerClass` | `string` | `''` | override de la barre header |
|
||||
| `bodyClass` | `string` | `''` | override de la zone scrollable |
|
||||
| `footerClass` | `string` | `''` | override du wrapper du `#footer` |
|
||||
|
||||
> **Largeur/hauteur** : pas de prop `size`. Tout se règle via `drawerClass`
|
||||
> (comme aujourd'hui).
|
||||
|
||||
### Emits
|
||||
|
||||
| Event | Payload | Quand |
|
||||
|-------|---------|-------|
|
||||
| `update:modelValue` | `boolean` | ouverture/fermeture |
|
||||
| `close` | — | à la fermeture (pratique pour la logique appelante) |
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
┌─────────────────────────────┐
|
||||
│ [slot #header] [ ✕ ] │ ← barre header (rendue si #header OU showClose)
|
||||
├─────────────────────────────┤
|
||||
│ │
|
||||
│ slot par défaut (body) │ ← zone scrollable (flex-1, overflow-y-auto)
|
||||
│ [slot #footer] │ ← rendu juste après le body, dans le même scroll,
|
||||
│ │ SANS classe de position par défaut
|
||||
└─────────────────────────────┘
|
||||
```
|
||||
|
||||
- La **barre header** n'est rendue que si le slot `#header` est fourni **ou** si
|
||||
`showClose` est vrai. Le bouton croix vit dans cette barre, à droite. L'icône de
|
||||
fermeture est **`mdi:cancel-bold`** (on conserve l'icône actuelle ; c'est le test
|
||||
qui sera adapté).
|
||||
- La **zone scrollable** (`flex-1 overflow-y-auto`) contient le slot par défaut
|
||||
puis, si fourni, le wrapper `#footer`.
|
||||
- Le **`#footer`** n'a **aucune** classe `sticky`/`flex-shrink-0`/position. Par défaut
|
||||
il scrolle avec le contenu. Pour le coller en bas, le consommateur passe
|
||||
`footer-class="sticky bottom-0 bg-white"`.
|
||||
|
||||
## Comportements (les manques actuels corrigés)
|
||||
|
||||
1. **Échap** ferme le drawer si `closeOnEscape` (listener `keydown` global, ajouté à
|
||||
l'ouverture, retiré à la fermeture).
|
||||
2. **Scroll-lock du body** : `overflow: hidden` sur `document.body` à l'ouverture,
|
||||
restauré à la fermeture.
|
||||
3. **Focus-trap** : à l'ouverture, focus sur le premier élément focusable du panneau
|
||||
(ou le panneau lui-même) ; `Tab`/`Shift+Tab` bouclent à l'intérieur du panneau.
|
||||
4. **Restitution du focus** : mémoriser `document.activeElement` à l'ouverture, le
|
||||
restaurer à la fermeture.
|
||||
5. **ARIA** :
|
||||
- `role="dialog"`, `aria-modal="true"` sur le panneau ;
|
||||
- `aria-labelledby` pointant sur l'id du wrapper `#header` **si** le slot est fourni ;
|
||||
- sinon `aria-label` = prop `ariaLabel` (fallback accessible).
|
||||
|
||||
## Transition
|
||||
|
||||
- Backdrop : fondu (`opacity`).
|
||||
- Panneau : translation selon `side` —
|
||||
- `right` : `translateX(100%)` → `0` ;
|
||||
- `left` : `translateX(-100%)` → `0`.
|
||||
- Conserver le pattern actuel `<Teleport to="body">` + `<Transition>` +
|
||||
`isRendered` (démontage après l'animation de sortie).
|
||||
|
||||
## Migration (breaking)
|
||||
|
||||
| Avant | Après |
|
||||
|-------|-------|
|
||||
| `title="Titre"` | `<template #header><h2>Titre</h2></template>` (ou composant de titre Malio) |
|
||||
| `<MalioDrawer>contenu</MalioDrawer>` | inchangé (slot par défaut = body) |
|
||||
| `drawer-class` | inchangé |
|
||||
| `show-close` | inchangé |
|
||||
| _(nouveau)_ | `side`, `dismissable`, `closeOnEscape`, `ariaLabel`, slots `#header`/`#footer` |
|
||||
|
||||
Les défauts des nouvelles props reproduisent au plus près le comportement actuel
|
||||
(`side="right"`, `showClose=true`, `dismissable=true`).
|
||||
|
||||
## Tests (Vitest + @vue/test-utils, jsdom)
|
||||
|
||||
À couvrir, en plus des tests de rendu/props/emits existants :
|
||||
|
||||
- rendu des 3 slots (`#header`, défaut, `#footer`) ;
|
||||
- `side` left/right → classes/transition attendues ;
|
||||
- `showClose` toggle la croix ; clic croix → ferme + emit ;
|
||||
- `dismissable` : clic backdrop ferme / ne ferme pas ;
|
||||
- `closeOnEscape` : Échap ferme / ne ferme pas ;
|
||||
- scroll-lock : `body` `overflow:hidden` à l'ouverture, restauré à la fermeture ;
|
||||
- focus-trap : focus initial dans le panneau ; restitution au déclencheur ;
|
||||
- ARIA : `aria-labelledby` quand `#header`, `aria-label` sinon ;
|
||||
- pattern contrôlé/non-contrôlé.
|
||||
|
||||
## Hors périmètre (YAGNI)
|
||||
|
||||
- côtés `top`/`bottom` (sheets) — extensible plus tard via `side` ;
|
||||
- prop `size` sémantique — `drawerClass` suffit ;
|
||||
- hook `before-close` ;
|
||||
- empilement de plusieurs drawers (un seul scroll-lock géré simplement).
|
||||
Reference in New Issue
Block a user