Merge pull request #919 from dnum-mi/docs/improve-migrations-doc

docs: 📝 améliore la documentation de migration vers v6

.vscode/extensions.json

@@ -26,10 +26,6 @@
  // https://github.com/DavidAnson/vscode-markdownlint
  "DavidAnson.vscode-markdownlint",
 
- // Test `.unit.js` files on save with Jest
- // https://github.com/jest-community/vscode-jest
- "Orta.vscode-jest",
-
  // npm support for VS Code
  // https://github.com/Microsoft/vscode-npm-scripts
  "eg2.vscode-npm-script",

docs/guide/migrations.md

@@ -27,18 +27,104 @@ Pour rendre la migration la plus douce possible un composant `VIcon` a été ajo
 
 #### Implication et changements à faire sur vos projets
 
+##### Vue + vite
+
 Il vous suffira donc dans vos projets d’importer VIcon depuis `@gouvminint/vue-dsfr` dans tous les fichiers où vous utilisez VIcon de OhVueIcons.
 
-Il faudra peut-être dans certains cas renommer les icônes car la syntaxe attendue par `@iconify/vue` est `nom-de-collection:nom-d-icone` alors que `oh-vue-icon` attendait simplement `nom-de-collection-nom-d-icone`.
+Il faudra enlever les références à `oh-vue-icons`, par exemple dans `main.ts` :
+
+::: code-group
+
+```ts [main.ts]
+import '@gouvfr/dsfr/dist/core/core.main.min.css'
+import '@gouvfr/dsfr/dist/component/component.main.min.css'
+import '@gouvfr/dsfr/dist/utility/utility.main.min.css'
+import '@gouvminint/vue-dsfr/styles'
+
+import '@gouvfr/dsfr/dist/scheme/scheme.min.css'
+import '@gouvfr/dsfr/dist/utility/icons/icons.min.css'
+
+import { createApp } from 'vue'
+import { OhVueIcon, addIcons } from 'oh-vue-icons' // [!code --]
+
+import App from './App.vue'
+import router from './router/index'
+import * as icons from './icons' // [!code --]
+
+import './main.css'
+
+addIcons(...Object.values(icons)) // [!code --]
+
+createApp(App)
+ .use(router)
+ .component('VIcon', OhVueIcon) // [!code --]
+ .mount('#app')
+```
+
+:::
+
+Il faudra supprimer le fichier `icons.ts` qui n’est plus utile.
+
+Si vous importiez vous-même `OhVueIcon` de `oh-vue-icons` dans certains composants, il faudra remplacer le module de l’import par `@gouvminint/vue-dsfr` :
+
+```vue
+<script lang="ts" setup>
+import { OhVueIcon as VIcon } from 'oh-vue-icons' // [!code --]
+import { VIcon } from '@gouvminint/vue-dsfr' // [!code ++]
+</script>
+```
+
+Il faudra peut-être dans certains cas renommer les icônes car la syntaxe attendue par `@iconify/vue` est `nom-de-collection:nom-d-icone` alors que `oh-vue-icon` attendait simplement `nom-de-collection-nom-d-icone` et les noms de collections ne sont pas forcément identiques entre `oh-vue-icons` et `@iconify/vue`.
+
+::: tip Astuce
+Si vous en êtes resté aux icônes remix icons, le nom de la collection étant d’une part sans tiret `-` et d’autre part identique entre `oh-vue-icons` et `@iconify/vue` (`ri`), vous n’aurez rien à modifier. Idem pour Bootstrap Icons (`bi`).
+:::
+
+Dans les cas ou le nom de la collection ne contient pas de tiret `-`, alors le `-` est accepté en tant que séparateur entre le nom de collection et le nom d’icône.
+
+##### Nuxt
+
+Il faudra utiliser la [v2](https://github.com/laruiss/vue-dsfr-nuxt-module/releases/tag/v2.0.0) de [`vue-dsfr-nuxt-module`](https://github.com/laruiss/vue-dsfr-nuxt-module), et enlever `oh-vue-icons` des dépendances et supprimer les références à `oh-vue-icons` :
+
+Dans `nuxt.config.ts` :
+
+```diff
+-import * as icons from './icons'
+ // (...)
+ export default defineNuxtConfig({
+ // (...)
+- runtimeConfig: {
+- public: {
+- vueDsfr: {
+- icons: Object.values(icons),
+- },
+- },
+- },
+
+```
+
+et supprimer le fichier `icons.ts` si vous en avez un
+
+Il faudra peut-être dans certains cas renommer les icônes car la syntaxe attendue par `@iconify/vue` est `nom-de-collection:nom-d-icone` alors que `oh-vue-icon` attendait simplement `nom-de-collection-nom-d-icone` et les noms de collections ne sont pas forcément identiques entre `oh-vue-icons` et `@iconify/vue`.
 
 Dans les cas ou le nom de la collection ne contient pas de tiret `-`, alors le `-` est accepté en tant que séparateur entre le nom de collection et le nom d’icône.
 
+::: tip Astuce
+Si vous en êtes resté aux icônes remix icons, le nom de la collection étant d’une part sans tiret `-` et d’autre part identique entre `oh-vue-icons` et `@iconify/vue` (`ri`), vous n’aurez rien à modifier. Idem pour Bootstrap Icons (`bi`).
+:::
+
 ### Les onglets
 
 Avant la version 6.x de VueDsfr, pour activer un onglet particulier, il fallait passer la prop `selected` au bon titre d’onglet et à la bonne zone de contenu.
 
+Nous avions exposé un composable `useTabs()` pour faciliter un peu cette gestion. C’était pourtant déjà trop compliqué à notre goût.
+
 Désormais c’est beaucoup plus simple, il suffit d’utiliser `v-model` sur le composant parent `DsfrTabs`.
 
+### Les accordéons
+
+Désormais, comme pour les onglets, pour choisir un accordéon particulier à ouvrir, il faudra utiliser `v-model` sur le composant [`DsfrAccordionsGroup`](/composants/DsfrAccordionsGroup), tel que décrit dans la [documentation](/composants/DsfrAccordionsGroup).
+
 ## Migration vers 3.x (depuis 1.x ou 2.x)
 
 La migration de la version 1.x ou 2.x vers la version 3.x nécessite un certain nombre de changements

src/components/DsfrAccordion/DsfrAccordionsGroup.md

@@ -1,4 +1,4 @@
-# DsfrAccordionsGroup - Documentation Vue.js
+# Groupe d’accordéons - `DsfrAccordionsGroup`
 
 ## 🌟 Introduction
 
@@ -14,13 +14,17 @@ Le composant `DsfrAccordionsGroup` agit comme un conteneur pour les composants d
 
 | Nom de Prop | Type | Par défaut | Description |
 |-------------|------|------------|-------------|
-| `modelValue` | `number` | `-1` | Index de l'accordéon actuellement actif. Ce prop est utilisé pour le contrôle externe de l'accordéon sélectionné. |
+| `modelValue` | `number` | `-1` | Index de l'accordéon actuellement actif. Cette prop est utilisée pour le contrôle externe de l'accordéon ouvert (un seul peut être ouvert à la fois). |
 
 ## 📡 Événements
 
 | Nom de l'Événement | Payload | Description |
 |--------------------|---------|-------------|
-| `update:modelValue` | `number` | Émis lorsque l'accordéon actif change. Le payload est l'index du nouvel accordéon actif. |
+| `update:modelValue` | `number` | Émis lorsque l'accordéon actif change. Le payload est l'index du nouvel accordéon ouvert. |
+
+::: tip Astuce
+Il est donc possible (et recommandé) d’utiliser la directive `v-model` sur ce composant.
+:::
 
 ## 🧩 Slots