From 28267909ff318408ef1984a921dde6b72fbae830 Mon Sep 17 00:00:00 2001
From: tristan <tristan@yuno.malio.fr>
Date: Tue, 26 May 2026 08:49:51 +0200
Subject: [PATCH] docs : story Histoire Modal (#MUI-36)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                    |  1 +
 COMPONENTS.md                   | 52 ++++++++++++++++++++++++
 app/story/modal/modal.story.vue | 70 +++++++++++++++++++++++++++++++++
 3 files changed, 123 insertions(+)
 create mode 100644 app/story/modal/modal.story.vue

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 50620d0..a5e9180 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -33,6 +33,7 @@ Liste des évolutions de la librairie Malio layer UI
 * [#MUI-34] Revoir le système de playground
 * [#MUI-33] Développer le composant Datepicker
 * [#MUI-33] Création du composant DateTime (date + heure, sélecteur d'heure natif intérimaire)
+* [#MUI-36] Création d'un composant modal (dialogue centré, focus-trap, scroll-lock, footer fixe)
 
 ### Changed
 * [#MUI-35] Refonte du composant drawer : slots `#header`/`#footer`, prop `side` (droite/gauche), `dismissable`, `closeOnEscape`, classes d'override, focus-trap, scroll-lock et fermeture au clavier. **Breaking** : la prop `title` est remplacée par le slot `#header`.
diff --git a/COMPONENTS.md b/COMPONENTS.md
index 5a03fbb..15bf628 100644
--- a/COMPONENTS.md
+++ b/COMPONENTS.md
@@ -779,6 +779,58 @@ Panneau latéral (drawer) qui s'ouvre depuis la droite ou la gauche avec backdro
 
 ---
 
+## MalioModal
+
+Boîte de dialogue modale centrée avec backdrop semi-transparent. Gère l'accessibilité (focus-trap, restitution du focus, `Échap`), le verrouillage du scroll de la page et un empilement correct de plusieurs modals. Structure : header fixe, body scrollable (`max-h-[85vh]`), footer fixe.
+
+| Prop | Type | Défaut | Description |
+|------|------|--------|-------------|
+| `id` | `string` | auto | Identifiant HTML |
+| `modelValue` | `boolean` | `undefined` | État ouvert/fermé (v-model) |
+| `showClose` | `boolean` | `true` | Afficher le bouton de fermeture (croix) |
+| `dismissable` | `boolean` | `true` | Fermer au clic sur le backdrop |
+| `closeOnEscape` | `boolean` | `true` | Fermer avec la touche `Échap` |
+| `ariaLabel` | `string` | `''` | Nom accessible de secours quand le slot `#header` est absent |
+| `modalClass` | `string` | `''` | Classes CSS panneau, ex. largeur `max-w-lg` (twMerge) |
+| `overlayClass` | `string` | `''` | Classes CSS backdrop (twMerge) |
+| `headerClass` | `string` | `''` | Classes CSS barre header (twMerge) |
+| `bodyClass` | `string` | `''` | Classes CSS zone scrollable (twMerge) |
+| `footerClass` | `string` | `''` | Classes CSS footer fixe (twMerge) |
+
+**Events :** `update:modelValue(value: boolean)`, `close()`
+
+**Slots :**
+- `header` — en-tête (titre, etc.). S'il est absent et que `showClose` est `true`, seule la croix est affichée.
+- `default` — contenu (zone scrollable).
+- `footer` — actions (boutons). Rendu en bas, fixe, séparé par une bordure. N'apparaît que si le slot est fourni.
+
+```vue
+<MalioModal v-model="isOpen">
+  <template #header>
+    <h2 class="text-[24px] font-bold">Détails</h2>
+  </template>
+  <p>Contenu de la modal</p>
+</MalioModal>
+
+<!-- Largeur custom + footer d'actions -->
+<MalioModal v-model="isOpen" modal-class="max-w-lg">
+  <template #header><h2>Nouveau contact</h2></template>
+  <MalioInputText label="Nom" />
+  <template #footer>
+    <MalioButton label="Annuler" variant="secondary" button-class="flex-1" @click="isOpen = false" />
+    <MalioButton label="Enregistrer" button-class="flex-1" @click="isOpen = false" />
+  </template>
+</MalioModal>
+
+<!-- Non fermable au backdrop / Échap (croix uniquement) -->
+<MalioModal v-model="isOpen" :dismissable="false" :close-on-escape="false">
+  <template #header><h2>Action requise</h2></template>
+  <p>Fermeture via la croix uniquement</p>
+</MalioModal>
+```
+
+---
+
 ## MalioDataTable
 
 Tableau de données presentational avec pagination, filtres par slots et lignes cliquables.
diff --git a/app/story/modal/modal.story.vue b/app/story/modal/modal.story.vue
new file mode 100644
index 0000000..c79f0df
--- /dev/null
+++ b/app/story/modal/modal.story.vue
@@ -0,0 +1,70 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+
+defineOptions({ name: 'ModalStory' })
+
+const showBase = ref(false)
+const showForm = ref(false)
+const showNoDismiss = ref(false)
+</script>
+
+<template>
+  <Story title="Overlay/Modal">
+    <Variant title="Simple">
+      <div class="p-4">
+        <button
+          class="rounded bg-m-btn-primary px-4 py-2 text-white"
+          @click="showBase = true"
+        >
+          Ouvrir
+        </button>
+        <MalioModal v-model="showBase">
+          <template #header>
+            <h2 class="text-xl font-bold">Détails</h2>
+          </template>
+          <p>Contenu simple de la modal.</p>
+        </MalioModal>
+      </div>
+    </Variant>
+
+    <Variant title="Avec footer d'actions">
+      <div class="p-4">
+        <button
+          class="rounded bg-m-btn-primary px-4 py-2 text-white"
+          @click="showForm = true"
+        >
+          Ouvrir le formulaire
+        </button>
+        <MalioModal v-model="showForm" modal-class="max-w-lg">
+          <template #header>
+            <h2 class="text-xl font-bold">Nouveau contact</h2>
+          </template>
+          <div class="flex flex-col gap-4 py-2">
+            <MalioInputText label="Nom" />
+            <MalioInputText label="Prénom" />
+          </div>
+          <template #footer>
+            <MalioButton label="Enregistrer" button-class="flex-1" @click="showForm = false" />
+          </template>
+        </MalioModal>
+      </div>
+    </Variant>
+
+    <Variant title="Non dismissable">
+      <div class="p-4">
+        <button
+          class="rounded bg-m-btn-primary px-4 py-2 text-white"
+          @click="showNoDismiss = true"
+        >
+          Ouvrir
+        </button>
+        <MalioModal v-model="showNoDismiss" :dismissable="false" :close-on-escape="false">
+          <template #header>
+            <h2 class="text-xl font-bold">Action requise</h2>
+          </template>
+          <p>Ni le backdrop ni Échap ne ferment cette modal. Utilisez la croix.</p>
+        </MalioModal>
+      </div>
+    </Variant>
+  </Story>
+</template>