Skip to content

Commit 74742c8

Browse files
laruisslaruiss
committed
docs(sidemenu): 📚 ajout de la documentation complète des composants de menu latéral
- Les composants de menu latéral DsfrSideMenu* n'avaient pas de documentation VitePress - Améliorer la découvrabilité et l'utilisation des composants de navigation latérale - Création de 5 fichiers de documentation pour les composants de menu latéral - DsfrSideMenu.md : composant principal de menu latéral avec collapse/expand - DsfrSideMenuList.md : liste de navigation avec support des sous-menus - DsfrSideMenuListItem.md : élément individuel dans une liste de menu - DsfrSideMenuButton.md : bouton pour contrôler l'expansion des sous-menus - DsfrSideMenuLink.md : lien automatique (interne/externe) dans les menus - Ajout des liens dans la configuration VitePress (.vitepress/config.ts) - Tous les documents suivent le gabarit standard avec DSFR, props TypeScript, exemples
1 parent 4458386 commit 74742c8

File tree

6 files changed

+441
-0
lines changed

6 files changed

+441
-0
lines changed

‎.vitepress/config.ts‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -340,6 +340,28 @@ const composants = [
340340
text: 'DsfrShare',
341341
link: '/composants/DsfrShare.md',
342342
},
343+
{
344+
text: 'DsfrSideMenu',
345+
link: '/composants/DsfrSideMenu.md',
346+
items: [
347+
{
348+
text: 'DsfrSideMenuButton',
349+
link: '/composants/DsfrSideMenuButton.md',
350+
},
351+
{
352+
text: 'DsfrSideMenuLink',
353+
link: '/composants/DsfrSideMenuLink.md',
354+
},
355+
{
356+
text: 'DsfrSideMenuList',
357+
link: '/composants/DsfrSideMenuList.md',
358+
},
359+
{
360+
text: 'DsfrSideMenuListItem',
361+
link: '/composants/DsfrSideMenuListItem.md',
362+
},
363+
],
364+
},
343365
{
344366
text: 'DsfrStepper',
345367
link: '/composants/DsfrStepper.md',

‎src/components/DsfrSideMenu/DsfrSideMenu.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Menu latéral - `DsfrSideMenu`
2+
3+
## 🌟 Introduction
4+
5+
Le menu latéral est un composant de navigation verticale qui peut être réduit/expandé. Il suit les spécifications du Système de Design Français (DSFR) pour les menus de navigation latérale.
6+
7+
Le composant `DsfrSideMenu` fournit une navigation latérale avec support du collapse/expand, gestion des éléments de menu imbriqués, et intégration avec le routeur Vue.
8+
9+
## 📐 Structure
10+
11+
Le menu latéral crée :
12+
13+
- Un élément `<nav>` avec la classe `fr-sidemenu`
14+
- Un bouton de toggle pour réduire/expandre le menu
15+
- Un conteneur collapsible avec les éléments de menu
16+
- Support des liens externes et internes avec le routeur Vue
17+
- Gestion automatique des états actifs et expandés
18+
19+
## 🛠️ Props
20+
21+
| nom | type | défaut | obligatoire | description |
22+
|-------------------|----------------------------|-------------------------|-------------|----------------------------------------------------------|
23+
| `buttonLabel` | `string` | `'Dans cette rubrique'` | | Texte du bouton de toggle |
24+
| `id` | `string` | `() => useRandomId(...)`| | Identifiant unique du menu |
25+
| `sideMenuListId` | `string` | `() => useRandomId(...)`| | Identifiant de la liste de menu |
26+
| `collapseValue` | `string` | `'-492px'` | | Valeur de collapse CSS |
27+
| `menuItems` | `DsfrSideMenuListItemProps[]` | `undefined` | | Éléments du menu (structure imbriquée) |
28+
| `headingTitle` | `string` | `''` | | Titre du menu |
29+
| `titleTag` | `string` | `'h3'` | | Balise HTML pour le titre |
30+
| `focusOnExpanding`| `boolean` | `true` | | Focus automatique lors de l'expansion |
31+
32+
## 📡 Événements
33+
34+
`DsfrSideMenu` déclenche l'événement suivant :
35+
36+
| nom | donnée (payload) | description |
37+
|---------------|------------------|--------------------------------------------------------------|
38+
| `toggleExpand`| `string` | Émis lors du toggle d'expansion d'un élément |
39+
40+
## 🧩 Slots
41+
42+
| nom | description |
43+
|----------|----------------------------------------------------------|
44+
| `default`| Contenu du menu latéral (remplace la liste par défaut) |
45+
46+
## 📝 Exemples
47+
48+
Exemple d'utilisation basique du menu latéral :
49+
50+
::: code-group
51+
52+
```vue
53+
<script setup lang="ts">
54+
import { ref } from 'vue'
55+
56+
const menuItems = ref([
57+
{ text: 'Accueil', to: '/' },
58+
{ text: 'À propos', to: '/about' },
59+
{
60+
text: 'Services',
61+
menuItems: [
62+
{ text: 'Service 1', to: '/service1' },
63+
{ text: 'Service 2', to: '/service2' },
64+
],
65+
},
66+
])
67+
68+
const onToggleExpand = (id: string) => {
69+
console.log('Toggle expand:', id)
70+
}
71+
</script>
72+
73+
<template>
74+
<DsfrSideMenu
75+
heading-title="Navigation"
76+
:menu-items="menuItems"
77+
@toggle-expand="onToggleExpand"
78+
/>
79+
</template>
80+
```
81+
82+
:::
83+
84+
## ⚙️ Code source du composant
85+
86+
::: code-group
87+
88+
<<< DsfrSideMenu.vue
89+
<<< DsfrSideMenu.types.ts
90+
91+
:::

‎src/components/DsfrSideMenu/DsfrSideMenuButton.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Bouton de menu latéral - `DsfrSideMenuButton`
2+
3+
## 🌟 Introduction
4+
5+
Le bouton de menu latéral est un composant qui crée un bouton cliquable pour contrôler l'expansion/réduction d'un sous-menu dans une navigation latérale.
6+
7+
Le composant `DsfrSideMenuButton` crée un élément `<button>` avec la classe `fr-sidemenu__btn` et gère les attributs ARIA pour l'accessibilité, notamment `aria-expanded` et `aria-controls`.
8+
9+
::: warning Important
10+
11+
Ce composant **NE devrait PAS être utilisé directement**, il est **utilisé en interne** par [**`DsfrSideMenuList`**](/composants/DsfrSideMenuList) pour les éléments de menu qui ont des sous-menus
12+
13+
:::
14+
15+
## 📐 Structure
16+
17+
Le bouton de menu latéral crée :
18+
19+
- Un élément `<button>` avec la classe `fr-sidemenu__btn`
20+
- Les attributs ARIA appropriés (`aria-expanded`, `aria-controls`)
21+
- L'attribut `aria-current="page"` si le bouton est actif
22+
- Un slot par défaut pour le texte du bouton
23+
24+
## 🛠️ Props
25+
26+
| nom | type | défaut | obligatoire | description |
27+
|-------------|-----------|---------|-------------|----------------------------------------------------------|
28+
| `active` | `boolean` | `false` | | Si le bouton représente l'élément actif |
29+
| `expanded` | `boolean` | `false` | | État d'expansion du sous-menu contrôlé |
30+
| `controlId` | `string` | | ✅ | ID de l'élément contrôlé par ce bouton |
31+
32+
## 📡 Événements
33+
34+
`DsfrSideMenuButton` déclenche l'événement suivant :
35+
36+
| nom | donnée (payload) | description |
37+
|---------------|------------------|--------------------------------------------------------------|
38+
| `toggleExpand`| `string` | Émis lors du clic avec l'ID de l'élément contrôlé |
39+
40+
## 🧩 Slots
41+
42+
| nom | description |
43+
|----------|----------------------------------------------------------|
44+
| `default`| Texte affiché dans le bouton |
45+
46+
## 📝 Exemples
47+
48+
Exemple d'utilisation de `DsfrSideMenuButton` dans un élément de menu :
49+
50+
::: code-group
51+
52+
```vue
53+
<script setup lang="ts">
54+
import { ref } from 'vue'
55+
56+
const isExpanded = ref(false)
57+
58+
const onToggleExpand = (id: string) => {
59+
if (id === 'submenu-1') {
60+
isExpanded.value = !isExpanded.value
61+
}
62+
}
63+
</script>
64+
65+
<template>
66+
<DsfrSideMenuListItem>
67+
<DsfrSideMenuButton
68+
control-id="submenu-1"
69+
:expanded="isExpanded"
70+
@toggle-expand="onToggleExpand"
71+
>
72+
Services
73+
</DsfrSideMenuButton>
74+
</DsfrSideMenuListItem>
75+
</template>
76+
```
77+
78+
:::
79+
80+
## ⚙️ Code source du composant
81+
82+
::: code-group
83+
84+
<<< DsfrSideMenuButton.vue
85+
<<< DsfrSideMenu.types.ts
86+
87+
:::

‎src/components/DsfrSideMenu/DsfrSideMenuLink.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Lien de menu latéral - `DsfrSideMenuLink`
2+
3+
## 🌟 Introduction
4+
5+
Le lien de menu latéral est un composant qui crée automatiquement un lien cliquable dans un menu latéral. Il gère les liens externes et internes avec le routeur Vue.
6+
7+
Le composant `DsfrSideMenuLink` crée dynamiquement un élément `<a>` pour les liens externes ou un `<RouterLink>` pour les liens internes, avec la classe `fr-sidemenu__link` et support de l'état actif.
8+
9+
::: warning Important
10+
11+
Ce composant **NE devrait PAS être utilisé directement**, il est **utilisé en interne** par [**`DsfrSideMenuList`**](/composants/DsfrSideMenuList)
12+
13+
:::
14+
15+
## 📐 Structure
16+
17+
Le lien de menu latéral crée dynamiquement :
18+
19+
- un élément `<a>` pour les liens externes (commençant par `http`)
20+
- un `<RouterLink>` pour les liens internes avec gestion automatique du routeur Vue
21+
- la classe CSS `fr-sidemenu__link` pour le styling DSFR
22+
- l'attribut `aria-current="page"` si le lien est actif
23+
24+
## 🛠️ Props
25+
26+
| nom | type | défaut | obligatoire | description |
27+
|----------|-----------|---------|-------------|----------------------------------------------------------|
28+
| `active` | `boolean` | `false` | | Si le lien représente la page active |
29+
| `to` | `string` | `''` | ✅ | URL ou route de destination |
30+
31+
## 📡 Événements
32+
33+
`DsfrSideMenuLink` ne déclenche pas d'événements.
34+
35+
## 🧩 Slots
36+
37+
| nom | description |
38+
|----------|----------------------------------------------------------|
39+
| `default`| Texte affiché du lien |
40+
41+
## 📝 Exemples
42+
43+
Exemple d'utilisation de `DsfrSideMenuLink` dans un élément de menu :
44+
45+
::: code-group
46+
47+
```vue
48+
<template>
49+
<DsfrSideMenuListItem>
50+
<DsfrSideMenuLink
51+
to="/"
52+
active
53+
>
54+
Accueil
55+
</DsfrSideMenuLink>
56+
</DsfrSideMenuListItem>
57+
<DsfrSideMenuListItem>
58+
<DsfrSideMenuLink to="https://www.service-public.fr">
59+
Service Public
60+
</DsfrSideMenuLink>
61+
</DsfrSideMenuListItem>
62+
</template>
63+
```
64+
65+
:::
66+
67+
## ⚙️ Code source du composant
68+
69+
::: code-group
70+
71+
<<< DsfrSideMenuLink.vue
72+
<<< DsfrSideMenu.types.ts
73+
74+
:::

‎src/components/DsfrSideMenu/DsfrSideMenuList.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# Liste de menu latéral - `DsfrSideMenuList`
2+
3+
## 🌟 Introduction
4+
5+
La liste de menu latéral est un composant qui gère une liste d'éléments de navigation dans un menu latéral. Elle supporte les éléments imbriqués et le collapse/expand automatique.
6+
7+
Le composant `DsfrSideMenuList` crée une liste `<ul>` avec la classe `fr-sidemenu__list` et gère automatiquement les liens externes/internes, les états actifs, et les sous-menus collapsibles.
8+
9+
::: warning Important
10+
11+
Ce composant **NE devrait PAS être utilisé directement**, il est **utilisé en interne** par son parent [**`DsfrSideMenu`**](/composants/DsfrSideMenu)
12+
13+
:::
14+
15+
## 📐 Structure
16+
17+
La liste de menu latéral crée :
18+
19+
- Un conteneur `<div>` avec support du collapse (si `collapsable`)
20+
- Une liste `<ul>` avec la classe `fr-sidemenu__list`
21+
- Des éléments `DsfrSideMenuListItem` pour chaque élément de menu
22+
- Support automatique des liens externes (`<a>`) et internes (`<RouterLink>`)
23+
- Gestion des sous-menus avec `DsfrSideMenuButton` pour les éléments parents
24+
25+
## 🛠️ Props
26+
27+
| nom | type | défaut | obligatoire | description |
28+
|-------------------|----------------------------|------------|-------------|----------------------------------------------------------|
29+
| `id` | `string` | | ✅ | Identifiant unique de la liste |
30+
| `collapsable` | `boolean` | `false` | | Si la liste peut être réduite/expandue |
31+
| `expanded` | `boolean` | `false` | | État d'expansion de la liste |
32+
| `menuItems` | `MenuItem[]` | `[]` | | Éléments du menu avec structure imbriquée |
33+
| `focusOnExpanding`| `boolean` | `false` | | Focus automatique lors de l'expansion |
34+
35+
## 📡 Événements
36+
37+
`DsfrSideMenuList` déclenche l'événement suivant :
38+
39+
| nom | donnée (payload) | description |
40+
|---------------|------------------|--------------------------------------------------------------|
41+
| `toggleExpand`| `string` | Émis lors du toggle d'expansion d'un élément |
42+
43+
## 🧩 Slots
44+
45+
| nom | description |
46+
|----------|----------------------------------------------------------|
47+
| `default`| Contenu personnalisé de la liste (remplace les éléments par défaut) |
48+
49+
## 📝 Exemples
50+
51+
Exemple d'utilisation de `DsfrSideMenuList` dans un menu latéral :
52+
53+
::: code-group
54+
55+
```vue
56+
<script setup lang="ts">
57+
import { ref } from 'vue'
58+
59+
const menuItems = ref([
60+
{ text: 'Accueil', to: '/', active: true },
61+
{ text: 'Services', menuItems: [
62+
{ text: 'Service 1', to: '/service1' },
63+
{ text: 'Service 2', to: '/service2' },
64+
] },
65+
])
66+
67+
const onToggleExpand = (id: string) => {
68+
console.log('Toggle expand:', id)
69+
}
70+
</script>
71+
72+
<template>
73+
<DsfrSideMenu heading-title="Navigation">
74+
<DsfrSideMenuList
75+
id="main-menu"
76+
:menu-items="menuItems"
77+
@toggle-expand="onToggleExpand"
78+
/>
79+
</DsfrSideMenu>
80+
</template>
81+
```
82+
83+
:::
84+
85+
## ⚙️ Code source du composant
86+
87+
::: code-group
88+
89+
<<< DsfrSideMenuList.vue
90+
<<< DsfrSideMenu.types.ts
91+
92+
:::

0 commit comments

Comments
 (0)