@lab-anssi/ui-kit 1.61.3 → 1.62.0

package/README.md

@@ -19,17 +19,17 @@ Le **UI Kit du Lab. ANSSI** est une bibliothèque de composants **Svelte**, pens
 
 Cette bibliothèque propose à la fois des composants **Svelte** et leurs équivalents **WebComponents**, facilitant leur intégration dans différents environnements front-end.
 
-Le projet s’appuie sur des outils modernes tels que SvelteKit, Vite, Storybook et Vitest pour garantir une expérience de développement fluide, des tests robustes et une documentation interactive.
+Le projet s’appuie sur des outils modernes tels que **Svelte**, **Vite**, **Storybook** et **Vitest** pour garantir une expérience de développement fluide, des tests robustes et une documentation interactive.
 
 ## Pour commencer
 
 ### Prérequis
 
-- Node.js (version recommandée : >= 24)
-- Svelte (version recommandée : >= 5.37.3)
-- Vite (version recommandée : >= 7.0.6)
-- Storybook (version recommandée : >= 9.1.1)
-- pnpm (voir la version exacte spécifiée dans le `package.json`)
+- **Node.js** _(version recommandée : >= 24.21.0)_
+- **Svelte** _(version recommandée : >= 5.57.0)_
+- **Vite** _(version recommandée : >= 8.3.0)_
+- **Storybook** _(version recommandée : >= 10.6.1)_
+- **pnpm** en version 11+
 
 ### Développement en local
 
@@ -43,10 +43,10 @@ pnpm install
 
 ### Documentation interactive
 
-Storybook est intégré à ce dépôt afin de fournir des exemples d’utilisation, la liste des props et des cas d’usage pour chaque composant.<br/>
+**Storybook** est intégré à ce dépôt afin de fournir des exemples d’utilisation, la liste des props et des cas d’usage pour chaque composant.<br/>
 Les stories sont regroupées dans le dossier `stories/` et sont écrites en respectant [le format CSF](https://storybook.js.org/docs/writing-stories#component-story-format) de Storybook.
 
-Pour explorer et tester les composants en local, lancez Storybook à l'aide de la commande :
+Pour explorer et tester les composants en local, lancez **Storybook** à l'aide de la commande :
 
 ```bash
 pnpm run storybook:dev
@@ -55,39 +55,120 @@ pnpm run storybook:dev
 Suite à l'exécution de cette commande, Storybook se lancera automatiquement en ouvrant une fenêtre de votre navigateur par défaut vers l'url [http://localhost:6006](http://localhost:6006).
 
 > [!NOTE]
-> Le Storybook est également déployé en ligne sur GitHub Pages et est consultable à l'url suivante : [https://betagouv.github.io/lab-anssi-ui-kit/](https://betagouv.github.io/lab-anssi-ui-kit/)
+> Le **Storybook** de ce projet est également déployé en ligne sur **GitHub Pages** et est consultable à l'url suivante : [https://betagouv.github.io/lab-anssi-ui-kit/](https://betagouv.github.io/lab-anssi-ui-kit/)
 
 ## Usage
 
-L'intégralité des composants présents dans ce dépôts sont publiés sur NPM afin qu'ils puissent être consommés dans différents environnements front-end.<br/>
-La bibliothèque expose ses composants dans un dossier `dist/` qui est construit à l'aide de la commande `pnpm run build`.
+L’intégralité des composants présents dans ce dépôt sont publiés sur NPM afin qu’ils puissent être consommés dans différents environnements front-end.
 
-Ainsi, pour pouvoir consommer les éléments de cette librairie dans votre projet, vous devrez commencer par installer le package à l'aide de cette commande :
+La bibliothèque propose **deux modes de distribution** :
+
+| Mode                  | Format                     | Dossier                          | Cas d’usage                                         |
+| --------------------- | -------------------------- | -------------------------------- | --------------------------------------------------- |
+| **WebComponents**     | Bundle IIFE                | `dist/webcomponents/`            | Tout projet HTML/JS (React, Vue, Angular, vanilla…) |
+| **Composants Svelte** | ES modules (tree-shakable) | `dist/composants` et `dist/dsfr` | Projets Svelte 5                                    |
+
+Le dossier `dist/` est construit à l’aide de la commande `pnpm run build`.
+
+### WebComponents
+
+Les **WebComponents** sont disponibles sous forme de bundle IIFE dans `dist/webcomponents/` et peuvent être intégrés dans n’importe quel projet HTML/JS.
+
+L’utilisation des **WebComponents** dans un projet nécessite deux ressources :
+
+1. **La feuille de styles des variables DSFR** (`dsfr-variables.css`) — fournit les variables CSS nécessaires au rendu des composants
+2. **Le script de la librairie** (`lab-anssi-ui-kit.iife.js`) — enregistre les **WebComponents**
+
+#### Via le CDN
+
+```html
+<!-- Variables CSS du DSFR -->
+<link
+  href="https://lab-anssi-ui-kit-prod-s3-assets.cellar-c2.services.clever-cloud.com/{version}/dsfr-variables.css"
+  rel="stylesheet"
+  nonce="{nonce}"
+/>
+
+<!-- Script de la librairie -->
+<script
+  src="https://lab-anssi-ui-kit-prod-s3-assets.cellar-c2.services.clever-cloud.com/{version}/lab-anssi-ui-kit.iife.js"
+  defer
+  nonce="{nonce}"
+></script>
+```
+
+#### Via le package NPM
+
+```html
+<link
+  href="node_modules/@lab-anssi/ui-kit/dist/assets/dsfr-variables.css"
+  rel="stylesheet"
+  nonce="{nonce}"
+/>
+<script
+  src="node_modules/@lab-anssi/ui-kit/dist/webcomponents/lab-anssi-ui-kit.iife.js"
+  nonce="{nonce}"
+></script>
+```
+
+> [!NOTE]
+> Sans la feuille de styles `dsfr-variables.css`, les composants s’afficheront sans les couleurs et espacements du DSFR.
+
+> [!IMPORTANT]
+> L’attribut `nonce` est nécessaire pour que la feuille de styles et le script soient autorisés par la [Content Security Policy (CSP)](https://developer.mozilla.org/fr/docs/Web/HTTP/CSP) de votre application. Sa valeur doit correspondre au nonce généré par votre serveur et déclaré dans l’en-tête HTTP `Content-Security-Policy`.
+
+#### Exemple
+
+Une fois ces ressources chargées, les WebComponents sont prêts à être utilisés :
+
+```html
+<lab-anssi-centre-aide nom-service="MonService" liens="[...]"></lab-anssi-centre-aide>
+```
+
+### Composants Svelte
+
+#### Installation
 
 ```bash
 pnpm add -D @lab-anssi/ui-kit@latest
 ```
 
-Vous pouvez ensuite importer les composants dans vos projets **Svelte** ou utiliser les **WebComponents** générés dans n’importe quelle application web.
+> [!IMPORTANT]
+> Le package déclare `svelte` (>= 5.57.0) en `peerDependencies`. Assurez-vous que votre projet utilise une version compatible.
+
+#### Import
 
-### Exemple d’import Svelte
+Les composants sont importables directement depuis le point d’entrée du package :
 
 ```ts
 import { Alerte, CentreAide, ResumePssi } from "@lab-anssi/ui-kit";
 ```
 
-### Exemple d'utilisation des WebComponents
+Ils sont compilés par [`@sveltejs/package`](https://svelte.dev/docs/kit/packaging) et bénéficient du tree-shaking : seuls les composants importés sont inclus dans votre bundle final.
 
-Les **WebComponents** sont disponibles dans le dossier `dist/webcomponents` et peuvent être intégrés dans n’importe quel projet HTML/JS en commençant par importer la librairie WebComponents à l'aide du script suivant :
+#### Feuilles de styles
 
-```html
-<script src="https://lab-anssi-ui-kit-prod-s3-assets.cellar-c2.services.clever-cloud.com/1.23.2/lab-anssi-ui-kit.iife.js"></script>
+Certains composants DSFR nécessitent des feuilles de styles CSS pour fonctionner correctement.<br/> Importez-les dans le CSS global de votre application (layout, `+layout.svelte`, `app.css`, etc.) :
+
+```css
+/* Variables CSS du DSFR (couleurs, espacements, etc.) */
+@import "@lab-anssi/ui-kit/dist/assets/dsfr-variables.css";
+
+/* Classes d'icônes DSFR (nécessaire pour les composants utilisant des icônes) */
+@import "@lab-anssi/ui-kit/dist/assets/dsfr-icons.css";
 ```
 
-Une fois cet import effectué, les WebComponents sont prêts à être consommés dans votre projet :
+> [!NOTE]
+> Ces imports sont nécessaires car en contexte Svelte (sans Shadow DOM), les styles d'icônes ne sont pas injectés automatiquement dans le DOM.
+
+#### Exemple
 
-```html
-<lab-anssi-centre-aide nom-service="MonService" liens="[...]"></lab-anssi-centre-aide>
+```svelte
+<script>
+  import { Alerte } from "@lab-anssi/ui-kit";
+</script>
+
+<Alerte type="information">Ceci est une alerte informative.</Alerte>
 ```
 
 ## Release

package/dist/assets/assets.d.ts

@@ -0,0 +1 @@
+export declare const srcAsset: (cheminLocal: string) => string;

package/dist/assets/assets.js

@@ -0,0 +1 @@
+export const srcAsset = (cheminLocal) => `${import.meta.env.VITE_LAB_ANSSI_UI_KIT_ASSET_BASE}${cheminLocal}`;