Intégrer une story de votre Storybook

Une diapositive peut afficher une story d'un Storybook publié en ligne, dans un cadre chargé à l'ouverture de la diapositive. Le composant présenté est donc celui que publie le Storybook ce jour-là : dans une présentation écrite pour une revue de conception, vous montrez l'état de la branche, et chaque correction publiée y apparaît.

Les exemples de cette page affichent le Storybook public de react-dsfr, les composants React du Système de Design de l'État.

L'adresse du Storybook

La clé storybook de l'en-tête donne l'adresse du dossier publié, celui qui contient index.html et iframe.html.

---
title: Le parcours de dépôt
storybook: https://design.example.fr/storybook/branch/parcours-depot/
---

Quand votre intégration continue publie un Storybook par branche, chaque branche a son adresse. Indiquez celle de la branche de l'écran en cours de conception, ou celle de la branche principale pour montrer les composants livrés. Ouvrez-la dans le navigateur avant de l'écrire : le nom de la branche y est souvent transformé, feat/parcours-depot en feat-parcours-depot par exemple. Une fois la branche fusionnée et son Storybook supprimé, remplacez l'adresse par celle de la branche principale.

L'identifiant d'une story

Une story a un identifiant de la forme composant--story, comme components-button--default. Vous le trouvez dans l'adresse de la story ouverte dans le Storybook, après /story/ : ?path=/story/composants-carte--par-defaut donne composants-carte--par-defaut. Selon sa version et son hébergement, un Storybook publie aussi le fichier index.json, qui liste chaque story sous la clé entries.

Copiez l'identifiant tel quel, accents compris : un titre Système de design donne un identifiant qui commence par système-de-design.

Afficher une story

À côté du texte ou sous le titre, l'annotation :layout reçoit l'identifiant dans story et la place de la story dans media (voir Les mises en page). lightbox ouvre la story en plein écran au clic. Dans l'éditeur, vous pouvez aussi coller l'identifiant dans le champ « Story du Storybook » du panneau « Mise en page ».

---
storybook: https://components.react-dsfr.codegouv.studio
---

### L'en-tête du site

:layout{media="bottom" story="components-header--header-with-quick-access-items" lightbox}

Le bloc Marianne, le nom du service et les accès rapides.

Dans le texte de la diapositive, sous un paragraphe par exemple, le composant StoryFrame place la story à l'endroit où vous l'écrivez, avec une légende dans label.

---
storybook: https://components.react-dsfr.codegouv.studio
---

### Le bandeau d'information

Le service l'affiche en haut de chaque page.

::StoryFrame{story="components-notice--default" ratio="5/1" viewport="1000" label="Bandeau d'information importante"}
::

ratio donne la forme du cadre, par un nom comme wide (16/9) et portrait (3/4), ou par un rapport comme 5/1. viewport donne la largeur, en pixels, de la page de la story avant sa réduction à la taille du cadre : une valeur plus grande montre une plus grande partie de la page, une valeur plus petite grossit le composant.

Pour plusieurs stories côte à côte, Screens range ses composants StoryFrame en cols colonnes.

---
storybook: https://components.react-dsfr.codegouv.studio
---

### Les trois variantes du bouton

:::Screens{cols="3"}
::StoryFrame{story="components-button--default" ratio="wide" viewport="260" label="Principal"}
::
::StoryFrame{story="components-button--button-secondary" ratio="wide" viewport="260" label="Secondaire"}
::
::StoryFrame{story="components-button--button-tertiary" ratio="wide" viewport="260" label="Tertiaire"}
::
:::

La référence de @vignettes/storybook décrit leurs autres attributs.

Quand le cadre affiche une erreur

• « Couldn't find story matching » : l'identifiant ne correspond à aucune story. Recopiez-le depuis l'adresse de la story ouverte dans le Storybook.
• « Indiquez une story, avec la clé storybook dans l'en-tête de la présentation… » : l'en-tête n'a pas de clé storybook. Une annotation :layout avec story n'affiche alors aucun cadre.
• Une page 404 : l'adresse de la clé storybook ne mène à aucun Storybook. Le Storybook de la branche est peut-être en cours de publication, ou supprimé avec la branche.
• Un cadre vide, ou la page d'erreur du navigateur : l'adresse est en http://, ou le serveur du Storybook interdit son affichage dans une autre page. Il doit servir le Storybook sans en-tête X-Frame-Options, ou avec l'adresse du studio et celle des présentations dans la directive frame-ancestors de son en-tête Content-Security-Policy. GitHub Pages sert un Storybook sans ces en-têtes ; pour un autre hébergement, demandez à l'équipe qui le publie d'autoriser ces deux adresses.