Merge pull request #946 from dnum-mi/docs/improve-docs

docs/improve docs

.vitepress/config.ts

@@ -235,6 +235,10 @@ const composants = [
  text: 'DsfrNotice',
  link: '/composants/DsfrNotice.md',
  },
+ {
+ text: 'DsfrPicture',
+ link: '/composants/DsfrPicture.md',
+ },
  {
  text: 'DsfrRadioButton',
  link: '/composants/DsfrRadioButton.md',
@@ -325,6 +329,14 @@ const composants = [
  text: 'DsfrTooltip',
  link: '/composants/DsfrTooltip.md',
  },
+ {
+ text: 'DsfrTranscription',
+ link: '/composants/DsfrTranscription.md',
+ },
+ {
+ text: 'DsfrVideo',
+ link: '/composants/DsfrVideo.md',
+ },
  {
  text: 'VIcon',
  link: '/composants/VIcon.md',

.vitepress/theme/style.css

@@ -187,6 +187,10 @@
  justify-content: center;
 }
 
+.gap-2 {
+ gap: 0.5rem;
+}
+
 .gap-4 {
  gap: 1rem;
 }

src/components/DsfrMedia/DsfrPicture.md

@@ -0,0 +1,64 @@
+# Image - `DsfrPicture`
+
+Les contenus médias désignent vos contenus photos et vidéos. Lorsqu’ils sont intégrés à une page de contenu, il est recommandé de suivre les règles décrites ci-dessous.
+
+🏅 La documentation sur les contenus médias sur le [DSFR](https://www.systeme-de-design.gouv.fr/elements-d-interface/composants/contenus-medias)
+
+<VIcon name="vi-file-type-storybook" /> La story sur le contenu média image (picture) sur le storybook de [VueDsfr](https://storybook.vue-ds.fr/?path=/docs/composants-dsfrpicture--docs)
+
+## 🌟 Introduction
+
+Le composant `DsfrPicture` permet d'afficher une image de manière responsive, avec une légende optionnelle. Il est conçu pour être flexible, offrant des options pour personnaliser la taille, le ratio, et le contenu de l'image. Ce composant est idéal pour intégrer des images dans une interface utilisateur tout en garantissant leur adaptabilité et accessibilité.
+
+Le `DsfrPicture` utilise une structure HTML sémantique avec `<figure>` et `<figcaption>` pour améliorer l'accessibilité. Il applique des classes CSS conditionnelles pour ajuster la taille et le ratio de l'image en fonction des props fournies. Le slot par défaut permet une personnalisation avancée du contenu de l'image.
+
+## 📐 Structure
+
+- `<DsfrPicture>` : Le composant principal.
+ - Affiche une image avec un ratio et une taille personnalisés.
+ - Inclut une légende sous l'image.
+ - Utilise un slot pour permettre l'insertion d'un contenu personnalisé, comme un SVG.
+
+## 🛠️ Props
+
+| Propriété | Type | Description | Valeur par défaut |
+|-----------|-------------------------------------|-----------------------------------------------------------|-------------------|
+| `alt` | `string` | Texte alternatif pour l'image, utilisé pour l'accessibilité. | `''` |
+| `legend` | `string` | Légende à afficher sous l'image. | `''` |
+| `size` | `'small' \| 'medium' \| 'large'` | Taille de l'image (petite, moyenne, ou grande). | `'medium'` |
+| `src` | `string` | URL de l'image à afficher. | `obligatoire` |
+| `title` | `string` | Titre de l'image, affiché au survol. | `''` |
+| `ratio` | `string` | Ratio de l'image (par exemple, '16x9'). | `'16x9'` |
+
+## 📡 Événements
+
+Ce composant ne déclenche pas d'événements spécifiques.
+
+## 🧩 Slots
+
+- `default` : Slot pour insérer un contenu personnalisé (comme une image SVG). Si aucun contenu n'est fourni, l'image spécifiée par `src` est utilisée.
+
+## 📝 Exemples
+
+::: code-group
+
+<Story data-title="Démo" min-h="400px">
+ <DsfrPictureDemo />
+</Story>
+
+<<< docs-demo/DsfrPictureDemo.vue [Code de la démo]
+
+:::
+
+## ⚙️ Code source du composant
+
+::: code-group
+
+<<< DsfrPicture.vue
+<<< DsfrMedia.types.ts
+
+:::
+
+<script setup lang="ts">
+import DsfrPictureDemo from './docs-demo/DsfrPictureDemo.vue'
+</script>

src/components/DsfrMedia/DsfrVideo.md

@@ -0,0 +1,64 @@
+# Video - `DsfrVideo`
+
+Les contenus médias désignent vos contenus photos et vidéos. Lorsqu’ils sont intégrés à une page de contenu, il est recommandé de suivre les règles décrites ci-dessous.
+
+🏅 La documentation sur les contenus médias sur le [DSFR](https://www.systeme-de-design.gouv.fr/elements-d-interface/composants/contenus-medias)
+
+<VIcon name="vi-file-type-storybook" /> La story sur le contenus média video sur le storybook de [VueDsfr](https://storybook.vue-ds.fr/?path=/docs/composants-dsfrvideo--docs)
+
+## 🌟 Introduction
+
+Le composant `DsfrVideo` permet d'intégrer une vidéo responsive avec une légende et une transcription. Il s'agit d'une solution complète pour afficher des vidéos dans une interface utilisateur, tout en fournissant des fonctionnalités d'accessibilité telles que la transcription du contenu vidéo.
+
+Le `DsfrVideo` utilise un élément `<iframe>` pour intégrer la vidéo de manière responsive. Il ajuste automatiquement la taille et le ratio de la vidéo en fonction des props fournies. Le composant inclut également un sous-composant `DsfrTranscription` pour afficher la transcription du contenu vidéo, améliorant ainsi l'accessibilité.
+
+## 📐 Structure
+
+- `<DsfrVideo>` : Le composant principal.
+ - Affiche une vidéo à partir d'une URL.
+ - Inclut une légende sous la vidéo.
+ - Intègre une transcription optionnelle via le composant `DsfrTranscription`.
+
+## 🛠️ Props
+
+| Propriété | Type | Description | Valeur par défaut |
+|------------------------|----------|--------------------------------------------------------------------------|-------------------|
+| `src` | `string` | URL de la vidéo à afficher. | `obligatoire` |
+| `legend` | `string` | Légende à afficher sous la vidéo. | `''` |
+| `size` | `'small' \| 'medium' \| 'large'` | Taille de la vidéo (petite, moyenne, ou grande). | `'medium'` |
+| `transcriptionTitle` | `string` | Titre de la transcription (si disponible). | `''` |
+| `transcriptionContent` | `string` | Contenu de la transcription (si disponible). | `''` |
+| `ratio` | `string` | Ratio de la vidéo (par exemple, '16x9'). | `'16x9'` |
+
+## 📡 Événements
+
+Ce composant ne déclenche pas d'événements spécifiques.
+
+## 🧩 Slots
+
+Ce composant n'utilise pas de slots.
+
+## 📝 Exemples
+
+::: code-group
+
+<Story data-title="Démo" min-h="400px">
+ <DsfrVideoDemo />
+</Story>
+
+<<< docs-demo/DsfrVideoDemo.vue [Code de la démo]
+
+:::
+
+## ⚙️ Code source du composant
+
+::: code-group
+
+<<< DsfrVideo.vue
+<<< DsfrMedia.types.ts
+
+:::
+
+<script setup lang="ts">
+import DsfrVideoDemo from './docs-demo/DsfrVideoDemo.vue'
+</script>

src/components/DsfrMedia/docs-demo/DsfrPictureDemo.vue

@@ -0,0 +1,22 @@
+<script lang="ts" setup>
+import DsfrPicture from '../DsfrPicture.vue'
+
+const size = 'medium'
+const src = 'https://loremflickr.com/300/200/cat'
+const alt = ''
+const title = 'Photographie d’un chaton'
+const legend = 'Photographie d’un chaton'
+const ratio = '16x9'
+</script>
+
+<template>
+ <DsfrPicture
+ :src="src"
+ :alt="alt"
+ :title="title"
+ :legend="legend"
+ :size="size"
+ :ratio="ratio"
+ style="max-width: 500px"
+ />
+</template>

src/components/DsfrMedia/docs-demo/DsfrVideoDemo.vue

@@ -0,0 +1,21 @@
+<script lang="ts" setup>
+import DsfrVideo from '../DsfrVideo.vue'
+
+const size = 'medium'
+const src = 'https://www.youtube.com/embed/HyirpmPL43I'
+const legend = 'Vidéo traitant du Service National Universel'
+const transcriptionTitle = 'Titre de la transcription'
+const transcriptionContent = 'Contenu de la transcription'
+const ratio = '16x9'
+</script>
+
+<template>
+ <DsfrVideo
+ :src="src"
+ :legend="legend"
+ :size="size"
+ :transcription-title="transcriptionTitle"
+ :transcription-content="transcriptionContent"
+ :ratio="ratio"
+ />
+</template>

src/components/DsfrTag/DsfrTag.md

@@ -48,19 +48,15 @@ Pas d'événements personnalisés pour ce composant. Il se repose sur les évén
 
 ## 📝 Exemples
 
-1. **Étiquette Basique :**
-
-```html
-<DsfrTag label="Bonjour VueDsfr !" />
-```
+::: code-group
 
-Affiche une simple étiquette avec le texte "Bonjour VueDsfr !".
+<Story data-title="Démo" min-h="400px">
+ <DsfrTagDemo />
+</Story>
 
-1. **Étiquette avec icône :**
+<<< docs-demo/DsfrTagDemo.vue [Code de la démo]
 
-```html
-<DsfrTag label="Vue Power" icon="fr-icon-success-line" />
-```
+:::
 
 ## ⚙️ Code source du composant
 
@@ -70,3 +66,7 @@ Affiche une simple étiquette avec le texte "Bonjour VueDsfr !".
 <<< DsfrTags.types.ts
 
 :::
+
+<script setup lang="ts">
+import DsfrTagDemo from './docs-demo/DsfrTagDemo.vue'
+</script>

src/components/DsfrTag/DsfrTag.vue

@@ -24,7 +24,7 @@ const linkProps = computed(() => {
 })
 
 const dsfrIcon = computed(() => typeof props.icon === 'string' && props.icon.startsWith('fr-icon-'))
-const defaultScale = 0.9
+const defaultScale = props.small ? 0.65 : 0.9
 const iconProps = computed(() => dsfrIcon.value ? undefined : typeof props.icon === 'string' ? { name: props.icon, scale: defaultScale } : { scale: defaultScale, ...(props.icon ?? {}) })
 </script>
 

src/components/DsfrTag/docs-demo/DsfrTagDemo.vue

@@ -0,0 +1,48 @@
+<script lang="ts" setup>
+import DsfrTag from '@/components/DsfrTag/DsfrTag.vue'
+</script>
+
+<template>
+ <div class="flex gap-2 fr-m-2v flex-wrap">
+ <DsfrTag
+ label="Vue Power"
+ />
+ <DsfrTag
+ label="DSFR"
+ icon="fr-icon-success-line"
+ />
+ <DsfrTag
+ label="Iconify Power"
+ icon="ri-bell-line"
+ />
+ <DsfrTag
+ label="Tag inactif (disabled)"
+ icon="ri-stop-line"
+ title="désactivé"
+ disabled
+ />
+ <DsfrTag
+ label="Icône seule"
+ title="Icône seule"
+ icon="ri-play-line"
+ icon-only
+ />
+ <DsfrTag
+ label="Petit tag"
+ title="Petite"
+ small
+ />
+ <DsfrTag
+ label="Petit tag avec icone DSFR"
+ title="Petite"
+ small
+ icon="fr-icon-success-line"
+ />
+ <DsfrTag
+ label="Petit tag avec icone Iconify"
+ title="Petite"
+ small
+ icon="ri-checkbox-circle-line"
+ />
+ </div>
+</template>

src/components/DsfrTranscription/DsfrTranscription.md

@@ -0,0 +1,58 @@
+# Transcription - `DsfrTranscription`
+
+🏅 La documentation sur la transcription sur le [DSFR](https://www.systeme-de-design.gouv.fr/elements-d-interface/composants/transcription)
+
+<VIcon name="vi-file-type-storybook" /> La story sur la transcription sur le storybook de [VueDsfr](https://storybook.vue-ds.fr/?path=/docs/composants-dsfrtranscription--docs)
+
+## 🌟 Introduction
+
+Le composant `DsfrTranscription` est conçu pour afficher la transcription du contenu d'une vidéo. Il permet aux utilisateurs d'accéder facilement au texte de la vidéo, offrant ainsi une meilleure accessibilité. Le composant peut afficher la transcription dans une section extensible ou dans une fenêtre modale pour une lecture plus confortable.
+
+Le `DsfrTranscription` peut afficher la transcription dans une section extensible ou la charger dans une fenêtre modale grâce à l'utilisation du composant `DsfrModal` et du `Teleport` pour un rendu à l'extérieur de la hiérarchie DOM parent.
+
+## 📐 Structure
+
+- `<DsfrTranscription>` : Le composant principal.
+ - Contient un bouton pour afficher ou masquer la transcription.
+ - Affiche la transcription dans une section extensible ou une fenêtre modale.
+
+## 🛠️ Props
+
+| Propriété | Type | Description | Valeur par défaut |
+|-----------|----------|------------------------------------------------------------|-------------------------------------|
+| `id` | `string` | ID unique pour le composant, utilisé pour l'accessibilité. | `getRandomId('transcription')` |
+| `title` | `string` | Titre de la transcription. | `'Titre de la vidéo'` |
+| `content` | `string` | Contenu de la transcription. | `'Transcription du contenu de la vidéo'` |
+
+## 📡 Événements
+
+Ce composant ne déclenche pas d'événements spécifiques.
+
+## 🧩 Slots
+
+- `default` : Slot pour insérer du contenu personnalisé à la place de la transcription par défaut.
+
+## 📝 Exemples
+
+::: code-group
+
+<Story data-title="Démo" min-h="400px">
+ <DsfrTranscriptionDemo />
+</Story>
+
+<<< docs-demo/DsfrTranscriptionDemo.vue [Code de la démo]
+
+:::
+
+## ⚙️ Code source du composant
+
+::: code-group
+
+<<< DsfrTranscription.vue
+<<< DsfrTranscription.types.ts
+
+:::
+
+<script setup lang="ts">
+import DsfrTranscriptionDemo from './docs-demo/DsfrTranscriptionDemo.vue'
+</script>

src/components/DsfrTranscription/DsfrTranscription.vue

@@ -4,6 +4,8 @@ import { computed, ref, watch } from 'vue'
 import { useCollapsable } from '../../composables'
 import { getRandomId } from '../../utils/random-utils'
 
+import DsfrModal from '../DsfrModal/DsfrModal.vue'
+
 import type { DsfrTranscriptionProps } from './DsfrTranscription.types'
 
 export type { DsfrTranscriptionProps }

src/components/DsfrTranscription/docs-demo/DsfrTranscriptionDemo.vue

@@ -0,0 +1,13 @@
+<script lang="ts" setup>
+import DsfrTranscription from '../DsfrTranscription.vue'
+
+const title = 'Titre de la transcription'
+const content = 'Contenu de la transcription'
+</script>
+
+<template>
+ <DsfrTranscription
+ :title="title"
+ :content="content"
+ />
+</template>