feat: ✨ remanie DsfrTabs pour pouvoir utiliser v-model

BREAKING CHANGE: Gros changements dans `DsfrTabs`. Se reporter à la documentation

Author: laruiss

demo-app/views/AppTabs.vue

@@ -11,32 +11,24 @@ const tabTitles = [
   { title: 'Onglet avec accordéon', icon: 'ri-checkbox-circle-line', tabId: 'tab-0', panelId: 'tab-content-0' },
   { title: 'Titre 2', icon: 'ri-checkbox-circle-line', tabId: 'tab-1', panelId: 'tab-content-1' },
 ]
-const selectedTabIndex = ref(0)
-const asc = ref(true)
+const selectedTabIndex = ref(1)
 const initialSelectedIndex = 0
 const title1 = 'Un titre d’accordéon 1'
 const title2 = 'Un titre d’accordéon 2'
 const title3 = 'Un titre d’accordéon 3'
 const expandedId = ref(undefined)
-
-function selectTab (idx) {
-  asc.value = selectedTabIndex.value < idx
-  selectedTabIndex.value = idx
-}
 </script>
 
 <template>
   <DsfrTabs
+    v-model="selectedTabIndex"
     :tab-list-name="tabListName"
     :tab-titles="tabTitles"
     :initial-selected-index="initialSelectedIndex"
-    @select-tab="selectTab"
   >
     <DsfrTabContent
       panel-id="tab-content-0"
       tab-id="tab-0"
-      :selected="selectedTabIndex === 0"
-      :asc="asc"
     >
       <DsfrAccordionsGroup>
         <li>
@@ -74,14 +66,11 @@ function selectTab (idx) {
     <DsfrTabContent
       panel-id="tab-content-1"
       tab-id="tab-1"
-      :selected="selectedTabIndex === 1"
-      :asc="asc"
     >
       <DsfrCard
-        detail="detail"
-        description="description"
-        img-src="https://loremflickr.com/300/200/cat"
-        title="title"
+        detail="Détails de la carte"
+        description="Description de la carte : lorem ipsum dolor, sit amet consectetur adipisicing elit. Dolore dignissimos deleniti, velit ut cupiditate rem odit nobis iste eos qui itaque necessitatibus ab nostrum quibusdam veniam accusamus deserunt earum perspiciatis."
+        title="Titre de la carte"
       />
     </DsfrTabContent>
   </DsfrTabs>

src/components/DsfrTabs/DsfrTabContent.stories.ts

@@ -1,3 +1,4 @@
+import DsfrTabs from './DsfrTabs.vue'
 import DsfrTabContent from './DsfrTabContent.vue'
 
 export default {
@@ -29,6 +30,7 @@ export default {
 
 export const ContenuDOnglet = (args) => ({
   components: {
+    DsfrTabs,
     DsfrTabContent,
   },
 
@@ -37,21 +39,26 @@ export const ContenuDOnglet = (args) => ({
   },
 
   template: `
-    <div class="fr-tabs" style="overflow: visible">
+    <DsfrTabs
+      v-model="selectedTabIndex"
+      :tab-list-name="tabListName"
+      :tab-titles="tabTitles"
+    >
       <DsfrTabContent
-        panel-id="tab-content-3"
-        tab-id="tab-3"
-        :selected="selected"
-        :asc="asc"
+        panel-id="tab-content-0"
+        tab-id="tab-0"
       >
         <div>Contenu personnalisé</div>
       </DsfrTabContent>
-    </div>
+    </DsfrTabs>
   `,
 })
 ContenuDOnglet.args = {
   panelId: 'tab-content-0',
   tabId: 'tab-0',
-  selected: true,
-  asc: true,
+  selectedTabIndex: 0,
+  tabListName: 'Liste d’onglet',
+  tabTitles: [
+    { title: 'Titre 1', icon: 'ri-checkbox-circle-line', tabId: 'tab-0', panelId: 'tab-content-0' },
+  ],
 }

src/components/DsfrTabs/DsfrTabContent.vue

@@ -1,17 +1,20 @@
 <script setup lang="ts">
-import { computed } from 'vue'
+import { computed, inject, toRef } from 'vue'
 
 import type { DsfrTabContentProps } from './DsfrTabs.types'
+import { registerTabKey } from './injection-key'
 
 export type { DsfrTabContentProps }
 
 const props = defineProps<DsfrTabContentProps>()
 
 const values = { true: '100%', false: '-100%' }
+const useTab = inject(registerTabKey)!
+const { isVisible, asc } = useTab(toRef(() => props.tabId))
 // @ts-expect-error this will be fine
-const translateValueFrom = computed(() => values[String(props.asc)])
+const translateValueFrom = computed(() => values[String(asc?.value)])
 // @ts-expect-error this will be fine
-const translateValueTo = computed(() => values[String(!props.asc)])
+const translateValueTo = computed(() => values[String(!asc?.value)])
 </script>
 
 <template>
@@ -20,15 +23,15 @@ const translateValueTo = computed(() => values[String(!props.asc)])
     mode="in-out"
   >
     <div
-      v-show="selected"
+      v-show="isVisible"
       :id="panelId"
       class="fr-tabs__panel"
       :class="{
-        'fr-tabs__panel--selected': selected,
+        'fr-tabs__panel--selected': isVisible,
       }"
       role="tabpanel"
       :aria-labelledby="tabId"
-      :tabindex="selected ? 0 : -1"
+      :tabindex="isVisible ? 0 : -1"
     >
       <!-- @slot Slot par défaut pour le contenu de l’onglet. Sera dans `<div class="fr-tabs__panel">` -->
       <slot />

src/components/DsfrTabs/DsfrTabItem.vue

@@ -1,8 +1,9 @@
 <script lang="ts" setup>
-import { ref, watch } from 'vue'
+import { inject, ref, toRef, watch } from 'vue'
 import VIcon from '../VIcon/VIcon.vue'
 
 import type { DsfrTabItemProps } from './DsfrTabs.types'
+import { registerTabKey } from './injection-key'
 
 export type { DsfrTabItemProps }
 
@@ -11,7 +12,7 @@ const props = withDefaults(defineProps<DsfrTabItemProps>(), {
 })
 
 const emit = defineEmits<{
-  (e: 'click', payload: MouseEvent): void
+  (e: 'click', tabId: string): void
   (e: 'next'): void
   (e: 'previous'): void
   (e: 'first'): void
@@ -43,6 +44,9 @@ function onKeyDown (event: KeyboardEvent) {
     emit(eventToEmit)
   }
 }
+
+const useTab = inject(registerTabKey)!
+const { isVisible } = useTab(toRef(() => props.tabId))
 </script>
 
 <template>
@@ -54,12 +58,12 @@ function onKeyDown (event: KeyboardEvent) {
       ref="button"
       :data-testid="`test-${tabId}`"
       class="fr-tabs__tab"
-      :tabindex="selected ? 0 : -1"
+      :tabindex="isVisible ? 0 : -1"
       role="tab"
       type="button"
-      :aria-selected="selected"
+      :aria-selected="isVisible"
       :aria-controls="panelId"
-      @click.prevent="$emit('click', $event)"
+      @click.prevent="$emit('click', tabId)"
       @keydown="onKeyDown($event)"
     >
       <span

src/components/DsfrTabs/DsfrTabs.md

@@ -12,55 +12,112 @@ Bonjour les artistes du code ! Voici `DsfrTabs`, le composant d'onglets Vue qui
 
 | Nom                  | Type                      | Défaut       | Obligatoire | Description                                                |
 |----------------------|---------------------------|--------------|-------------|------------------------------------------------------------|
-| `'tabContents'`          | `string[]`                   | `[]`   |             | Contenus des onglets.                                      |
-| `'initialSelectedIndex'` | `number`                  | `0`          |             | Index de l'onglet sélectionné au chargement.               |
-| `'tabTitles'`            | `string[]`                   | `[]`   |             | Titres des onglets avec les id des panneaux et onglets associés. |
+| `tabContents`          | `string[]`                   | `[]`   |             | Contenus (simples) des onglets.                                      |
+| `modelValue` | `number`                  | `0`          |             | Index de l'onglet sélectionné au chargement (*existe depuis VueDsfr v6.0.0*).               |
+| `tabTitles`            | `string[]`                   | `[]`   |             | Titres des onglets avec les id des panneaux et onglets associés. |
+>>>>>>> 8171671 (feat: :sparkles: remanie DsfrTabs pour pouvoir utiliser v-model)
 
 ## 📡 Événements
 
 |  nom                   |   donnée (*payload*) | détail de la donnée
 | ---------------------- |  ---------            | --- |
-| `'select-tab '` |       *`string`*       | Émis lorsqu'un onglet est sélectionné. Envoyant l'index de l'onglet sélectionné. |
+| `'update:modelValue'` |       *`number`*       | Émis lorsqu'un onglet est sélectionné. Envoyant l'index de l'onglet sélectionné. |
+
+::: warning Important
+Depuis la v6, le composant `DsfrTabs` déclarant la prop `modelValue` et émettant l’événement `update:modelValue`, il est recommandé d’utiliser la directive `v-model`. Elle contient l’index (commençant à 0) de l’onglet à afficher. Aussi, plus besoin, depuis la v6, d’utiliser le composable `useTabs()`. Cf. les exemples ci-dessous.
+:::
 
 ## 🧩 Slots
 
 | Nom          | Description                                                        |
 |--------------|--------------------------------------------------------------------|
-| `'tab-items'`    | Slot nommé pour insérer des titres d’onglets personnalisés. Si rempli, la prop `tabTitles` n’a aucun effet. |
-| `'default'`      | Slot par défaut pour le contenu des onglets.                       |
+| `tab-items`    | Slot nommé pour insérer des titres d’onglets personnalisés. Si rempli, la prop `tabTitles` n’a aucun effet. |
+| `default`      | Slot par défaut pour le contenu des onglets.                       |
 
 ## Les méthodes exposées
 
 - `DsfrTabs#renderTabs()`: permet de forcer le recalcul de la hauteur de l’onglet
-- `DsfrTabs#selectIndex()`: permet d’indiquer quel onglet doit être sélectionné (commence à 0)
+
+::: warning Important depuis la v6
+
+Méthodes supprimées :
+
 - `DsfrTabs#selectFirst` : permet de sélectionner le premier onglet (raccourci de `selectIndex(0)`)
 - `DsfrTabs#selectLast` : permet de sélectionner le dernier onglet (raccourci de `selectIndex(tabs.length - 1)`)
+- `DsfrTabs#selectIndex()`: n’existe plus : utiliser directement la *ref* utilisée dans le `v-model` de `DsfrTabs`
 
-## 📝 Exemples
+Au lieu de :
 
-1. **Onglets Simples :**
+```vue
+<script lang="ts">
+import { ref } from 'vue'
 
-::: code-group
+const tabs = ref<HTMLElement>()
+
+// Quelque part dans le code :
+tabs.value.selectFirst()
+tabs.value.selectLast()
+tabs.value.selectIndex(n)
+
+// (...)
+</script>
+
+<template>
+  <!-- eslint-disable-next-line vue/no-unused-refs -->
+  <DsfrTabs ref="tabs">
+    <!-- (...) -->
+  </DsfrTabs>
+</template>
+```
+
+Utiliser :
 
-<Story data-title="Démo" min-h="160px">
-  <DsfrTabsDemoSimple />
-</Story>
+```vue
+<script lang="ts">
+import { ref } from 'vue'
 
-<<< docs-demo/DsfrTabsDemoSimple.vue [Code de la démo]
+const activeTab = ref(0)
+// Quelque part dans le code :
+activeTab.value = 0 // active le premier onglet
+activeTab.value = n // active l’onglet n
+activeTab.value = tabTitles.length - 1 // active le dernier onglet
+
+// (...)
+</script>
+
+<template>
+  <DsfrTabs v-model="activeTab">
+    <!-- (...) -->
+  </DsfrTabs>
+</template>
+```
 
 :::
 
+## 📝 Exemples
+
+1. **Onglets Simples :**
+
+  ::: code-group
+
+  <Story data-title="Démo" min-h="160px">
+    <DsfrTabsDemoSimple />
+  </Story>
+
+  <<< docs-demo/DsfrTabsDemoSimple.vue [Code de la démo]
+
+  :::
 2. **Onglets Complexes :**
 
-::: code-group
+  ::: code-group
 
-<Story data-title="Démo" min-h="260px">
-  <DsfrTabsDemoComplex />
-</Story>
+  <Story data-title="Démo" min-h="260px">
+    <DsfrTabsDemoComplex />
+  </Story>
 
-<<< docs-demo/DsfrTabsDemoComplex.vue [Code de la démo]
+  <<< docs-demo/DsfrTabsDemoComplex.vue [Code de la démo]
 
-:::
+  :::
 
 ## ⚙️ Code source des composants
 

src/components/DsfrTabs/DsfrTabs.spec.ts

@@ -1,6 +1,7 @@
 import VIcon from '../VIcon/VIcon.vue'
 import { fireEvent } from '@testing-library/dom'
 import { render } from '@testing-library/vue'
+import { ref } from 'vue'
 
 // import '@gouvfr/dsfr/dist/core/core.module.js'
 
@@ -13,6 +14,7 @@ describe('DsfrTabs', () => {
     const title1 = 'Titre 1'
     const title2 = 'Titre 2'
     const title3 = 'Titre 3'
+    const modelValue = ref(0)
 
     const tabTitles = [
       { title: title1, tabId: 'tab1' },
@@ -24,7 +26,7 @@ describe('DsfrTabs', () => {
     const tabContents = ['Contenu1', 'Contenu2', 'Contenu3', 'Contenu4']
 
     // When
-    const { getByText, getByTestId, getAllByRole, getByRole } = render(DsfrTabs, {
+    const { getByText, getByTestId, getAllByRole, getByRole, emitted } = render(DsfrTabs, {
       global: {
         components: {
           VIcon,
@@ -34,6 +36,7 @@ describe('DsfrTabs', () => {
         tabListName,
         tabTitles,
         tabContents,
+        modelValue: modelValue.value,
       },
     })
 
@@ -60,15 +63,9 @@ describe('DsfrTabs', () => {
     await fireEvent.click(thirdTabEl)
     await fireEvent.click(secondTabEl)
 
-    i = 0
-    for (const tabItemEl of tabItemEls) {
-      if (i === 1) {
-        expect(tabItemEl).toHaveAttribute('aria-selected', 'true')
-      } else {
-        expect(tabItemEl).toHaveAttribute('aria-selected', 'false')
-      }
-      i++
-    }
+    expect(emitted()['update:modelValue']).toBeTruthy()
+    expect(emitted()['update:modelValue'][1]).toEqual([2]) // 2nd tab
+    expect(emitted()['update:modelValue'][2]).toEqual([1]) // 2nd tab
 
     // Then
     expect(tabTitleEls[0]).toContainElement(firstTabEl)