# Fonctionnement du widget : architecture, commandes et déploiement

::::summary{title="En bref" audience="Développeurs qui reprennent, font évoluer ou déploient le widget." reading="8 min" updated="12 novembre 2026"}

Le dossier widget/, les routes, le script d'intégration, le moteur de calcul, le contrat des partenaires, les tests et le déploiement.

:::details[Données utilisées]
Le jeu embarqué de Plutôt là (packages/data/generated/), lu par le moteur du widget dans le navigateur.
:::

::::

## Vue d'ensemble

`widget/` est une application Vite et React du monorepo (`@flux/widget-app`), à côté de `app/` (Plutôt là). C'est une **coquille** : son code vit dans deux paquets, `@flux/widget` (`packages/widget/` : moteur, composant, script d'intégration, sans Mantine) et `@flux/widget-editeur` (`packages/widget-editeur/` : les écrans du site et `routesWidget`). Elle a **deux entrées** :

1. **l'application** (`index.html`) : l'accueil, l'éditeur, les pages des partenaires et la liste des exemples ;
2. **le script d'intégration** (`widget/src/embed.ts`, qui réexporte `@flux/widget/embed`, soit `packages/widget/src/embed/index.ts`), publié à une adresse stable, `/embed/plutot-la-widget.js`, que les offices collent dans leurs pages.

Les deux affichent le **même composant** `WidgetPlutotLa` (`packages/widget/src/widget/`), nourri par le **même moteur** (`packages/widget/src/moteur/`).

```mermaid
flowchart TB
  accTitle: Architecture de l'application widget
  accDescr: Le dossier widget contient deux entrées. L'application, avec ses routes accueil, éditeur, page du partenaire et exemples, lit et écrit les partenaires dans le stockage du navigateur. Le script d'intégration définit l'élément plutot-la-widget dans un Shadow DOM et lit la configuration dans la page. Les deux affichent le composant WidgetPlutotLa, nourri par le moteur, qui s'appuie sur les paquets flux core et flux data.
  subgraph APP["Application (index.html)"]
    R1["/ accueil"]
    R2["/editor"]
    R3["/:slug<br/>page du partenaire"]
    R4["/examples"]
  end
  subgraph EMB["Script d'intégration<br/>/embed/plutot-la-widget.js"]
    E1["élément plutot-la-widget<br/>Shadow DOM"]
  end
  S[("localStorage<br/>partenaires")]
  W["WidgetPlutotLa<br/>@flux/widget"]
  M["Moteur<br/>@flux/widget/moteur"]
  C["@flux/core<br/>affluence, alternatives"]
  D["@flux/data<br/>jeu embarqué"]
  R2 <--> S
  R3 --> S
  APP --> W
  E1 --> W
  W --> M
  M --> C
  M --> D
```

:::howto{caption="Source : widget/vite.config.ts, widget/src/App.tsx, packages/widget/"}
Les deux entrées (l'application et le script d'intégration) affichent le même composant, qui demande ses chiffres au moteur, lequel s'appuie sur les paquets partagés avec Plutôt là. Seule l'application lit et écrit le stockage du navigateur.
:::

## Les routes de l'application

| Route | Écran | Fichier |
|---|---|---|
| `/` | Accueil : ce qu'est le widget, les partenaires, les exemples | `packages/widget-editeur/src/pages/Accueil.tsx` |
| `/editor`, `/editor/:slug` | Éditeur des partenaires (Thème, Contenu, Intégration) | `packages/widget-editeur/src/editor/` |
| `/examples` | Liste des pages d'exemple (fichiers statiques `widget/public/examples/`) | `packages/widget-editeur/src/pages/Exemples.tsx` |
| `/:slug` | Page d'un partenaire, à ses couleurs : sa variante choisie, les trois variantes et son code | `packages/widget-editeur/src/pages/PagePartenaire.tsx` |
| `/:slug` d'un partenaire inconnu | Page introuvable, avec le bouton « Créer ce partenaire dans l'éditeur » (qui ouvre `/editor/:slug` quand l'adresse a la forme d'un identifiant) | `packages/widget-editeur/src/pages/PageIntrouvable.tsx` |

:::howto{caption="Source : widget/src/App.tsx, packages/widget-editeur/src/routes.tsx"}
Le routage se fait par chemin (React Router, `createBrowserRouter`), sans dièse : `widget/vercel.json` renvoie toute adresse inconnue vers `index.html`, sauf `/embed/`, `/assets/` et `/examples/`.
:::

![L'accueil de l'application du widget, sur fond blanc : logo « Plutôt là widget », menu Éditeur, Exemples, Documentation ; « Pour les offices de tourisme et les sites », titre « Le widget Plutôt là » et trois phrases (deux lignes de code, ce que voit le visiteur, sans API ni compte) ; le bouton plein « Créer mon widget » et le bouton à contour « Voir les exemples » ; l'Éclaireur au chapeau ; puis « Aperçu en direct » avec le choix « Jour chargé » (choisi) ou « Aujourd'hui », la liste de ce que montre le widget (d'abord le verdict, les sept prochains jours, la courbe de la journée, des coins plus calmes, un lien vers l'application) et la carte du lac de Paladru : « Très fréquenté », les 7 jours, les barres heure par heure, « Plus calme à côté »](/widgets/accueil.png)

:::howto{caption="Source : packages/widget-editeur/src/pages/Accueil.tsx, capture du 12 novembre 2026"}
La promesse en trois phrases, les deux chemins (l'éditeur en bouton plein, les exemples en bouton à contour) et un aperçu vivant du partenaire `plutot-la`. Plus bas, hors de la capture : les partenaires et « Comment ça marche ». Le lien « Documentation » mène à cet onglet du portail.
:::

## Le script d'intégration

| Fichier de `packages/widget/src/embed/` | Rôle |
|---|---|
| `index.ts` | L'entrée du build : définit l'élément `plutot-la-widget` (constante `ELEMENT_WIDGET`), une seule fois même si le script est chargé deux fois |
| `element.tsx` | L'élément personnalisé : il ouvre un Shadow DOM, y monte React et suit ses attributs, son script JSON enfant et, sur la même adresse que l'éditeur, le stockage du navigateur |
| `resolution.ts` | L'ordre de résolution de la configuration (attribut `config`, script JSON, stockage, partenaires livrés, défaut), puis les attributs `lieu`, `variante`, `disposition`, `alternatives`, `langue` ; l'ancien attribut `mode` n'est plus lu |
| `base64url.ts` | L'encodage de l'attribut `config` : JSON de la configuration, en UTF-8, en base64url |
| `format.ts` | Le format 3 de la configuration (`ConfigurationWidget`) et sa lecture, versions 1 à 3 comprises (`lireConfiguration`) |
| `migration.ts` | L'écriture au format 3 (`versConfiguration`) et la conversion d'une ancienne configuration (`migrerConfiguration`), pour l'éditeur et le code à copier |
| `snippet.ts` | `codeIntegration(partenaire, { origine, avecConfig })` : le code à copier, utilisé par l'éditeur et la page du partenaire ; au-delà de 50 Ko, le logo et l'icône sont retirés |
| `styles.ts` | Les styles du widget, injectés dans chaque Shadow DOM |
| `Embed.module.css` | La remise à zéro dans le Shadow DOM (`:host`, casse, interligne, taille de base de 16 px) |
| `polices.ts` | Les polices Fredoka et Nunito (paquets `@fontsource-variable`), déclarées dans la page hôte si le thème les demande |
| `preambule-dev.ts` | Développement seulement : pose le « préambule » du rechargement à chaud de React, absent des pages statiques `/examples/`, pour que le widget s'y affiche avec `pnpm dev:widget` ; vide dans le build |
| `RenduEmbed.tsx` | Le rendu : calcule le résumé du lieu, le refait toutes les 10 minutes, affiche `WidgetPlutotLa` |

:::howto{caption="Source : packages/widget/src/embed/"}
Dans l'ordre où ils interviennent. Le comportement vu par l'office (attributs, ordre de résolution) est décrit dans le [tutoriel](/widgets/integrer).
:::

- **Shadow DOM** : chaque widget est dessiné dans un sous-arbre isolé (mode ouvert). La feuille de style de la page hôte ne l'atteint pas, et les styles du widget ne débordent pas sur la page. `:host { all: initial; display: block }` puis la racine interne remettent à zéro les propriétés héritées (casse, interligne, espacement des lettres, alignement) ; seules la police (réglage « Police du site ») et la couleur du texte passent. La page hôte garde la main sur la boîte de l'élément (marge, largeur).
- **Les styles** : ce sont les mêmes fichiers `*.module.css` que dans l'application. Chacun est aussi importé en texte (`?inline` de Vite, mêmes noms de classes), puis posé dans chaque Shadow DOM par une feuille construite partagée (`adoptedStyleSheets`), ou par une balise de style sur les navigateurs anciens. En développement, `verifierClasses()` avertit si une classe manque. Les couleurs du partenaire arrivent par des variables CSS posées sur la racine du widget.
- **Les polices** : une police déclarée dans un Shadow DOM n'est pas prise en compte par les navigateurs. Si le thème demande Fredoka ou Nunito, le script ajoute donc une fois, dans l'en-tête de la page hôte, les déclarations `@font-face` (latin et latin étendu), qui pointent vers les fichiers servis par l'adresse du widget.
- **Sans Mantine** : le composant `WidgetPlutotLa` n'utilise pas la bibliothèque de composants de l'application, pour garder le script léger et indépendant du site hôte.
- **Sans animation ni mascotte** : les moments vivants de l'application (Éclaireur qui réagit, jauge qui se remplit, tampon) ne viennent pas dans le widget, par décision du 12 novembre 2026. Il reste une information sobre, posée à plat dans la page du partenaire.
- **Chargement en deux temps** : le script lui-même est léger (`dist/embed/plutot-la-widget.js` : 32 684 octets, environ 7,8 Ko compressés, build du 12 novembre 2026 ; budget de 36 864 octets, soit 36 Ko, contrôlé après chaque build par `scripts/check-embed.mjs` ; relevé de 32 à 36 Ko le 12 novembre 2026, quand il ne restait que 84 octets de marge : de la place pour une correction, pas pour un nouvel import) ; le calcul (`packages/widget/src/moteur/calcul.ts`, qui tire `@flux/core`) et le jeu de données (`prechargerJeu()` de `@flux/data/leger`) arrivent par import dynamique, une seule fois pour tous les widgets de la page (`packages/widget/src/moteur/charger.ts`).
- **Tailles** : les feuilles du widget n'emploient jamais `rem` seul, qui suit la taille de texte de la page hôte (souvent 10 px). Toutes les longueurs passent par `calc(N * var(--pl-w-rem, 1rem))` ; le script d'intégration fixe `--pl-w-rem: 16px`, l'application la laisse à `1rem`. Vérifié sur une page hôte réglée à `html { font-size: 10px }` : le widget garde sa taille.
- **Mise à jour en direct** : l'élément suit ses attributs (`observedAttributes`), son script JSON enfant (un `MutationObserver`) et, sur la même adresse que l'éditeur, le stockage du navigateur (événement `storage`) ; plusieurs changements à la suite donnent un seul rendu.
- **Diagnostic** : l'élément porte l'attribut `data-config` (`attribut`, `script`, `stockage`, `integre` ou `defaut`) ; dans le Shadow DOM, la racine du widget porte `data-variante`, `data-etat` (`chargement`, `pret`, `erreur`) et `lang` (plus de `data-sombre` : le widget est toujours clair). Toute valeur ignorée donne un avertissement `[plutot-la-widget]` dans la console, jamais une exception chez le partenaire.

## Le moteur

`chargerResume(lieuId, date?)` (`packages/widget/src/moteur/index.ts`) rend un `ResumeLieu`, ou une `ErreurMoteur` (`lieu-inconnu`, `donnees-indisponibles`) que le widget affiche en clair :

| Champ de `ResumeLieu` | Contenu |
|---|---|
| `maintenant` | L'heure et le niveau prévu maintenant (ou à l'ouverture, hors de 8 h à 20 h) |
| `journee` | Le niveau et un indice de 0 à 1 000 (déduit) pour chaque heure de 8 h à 20 h |
| `meilleurMoment` | Le créneau le plus calme de la journée, le plus tôt à égalité |
| `semaine` | Les 7 prochains jours : niveau du pic, jour férié, vacances |
| `alternatives` | Les lieux plus calmes à proximité : nom, commune, distance, niveau au même moment, raison |
| `fiabilite`, `sources` | Une phrase sur la fiabilité et les fichiers sources |

**Itinéraire du jour** (bloc facultatif, `contenu.itineraire`) : `useItineraire` (`packages/widget/src/moteur/itineraire.ts`) charge à la demande les sorties embarquées de Plutôt là et en choisit une (`itineraireDuLieu`, `itineraire-choix.ts`). Seules les sorties au récit relu et validé comptent ; la sortie doit passer par le lieu suivi (une de ses étapes est une fiche de ce lieu). À plusieurs, le widget préfère une sortie d'un seul jour, puis la saison la plus proche de la date regardée, puis l'ordre des identifiants : le choix est stable. Il rend le titre, la durée, le nombre d'étapes et le lien vers le récit dans l'application (`#/itineraires/<identifiant>`). Bloc non activé : rien n'est chargé, et le premier fichier du script d'intégration ne grossit pas.

:::howto{caption="Source : packages/widget/src/moteur/types.ts · (déduit)"}
Le calcul réutilise la logique de Plutôt là (`@flux/core`) et son jeu de données embarqué (`@flux/data`), chargé à la demande. Détail des méthodes : l'onglet [Matching](/matching), et [Algorithmes](/plutotla/algorithmes) et [Données](/plutotla/donnees) de l'onglet Plutôt là.
:::

## Le contrat des partenaires

Un **partenaire** (`Partenaire`, `packages/core/src/partenaires/types.ts`, entrée `@flux/core/partenaires`) est un objet JSON. Ce que l'éditeur écrit (attribut `config`, fichier téléchargé) suit la **version 3** du format (`ConfigurationWidget`, `packages/widget/src/embed/format.ts`) ; une version 1 ou 2 est encore lue et convertie (`migrerConfiguration`) :

- `slug` (identifiant d'adresse), `nom`, `siteWeb`, `logo` et `icone` (images en _data URL_) ;
- `theme` : 13 couleurs, rayons, polices, graisse des titres, bordure. La version 3 n'a plus `mode`, `couleursSombre` ni `ombre` : dans un code plus ancien, ils sont ignorés (le widget est toujours clair, sans ombre) ;
- `contenu` (`ContenuWidget`) : lieu, variante, disposition, titre, message, éléments affichés, lieux alternatifs (quand, combien, pourquoi), bouton, langue, et `itineraire` (facultatif). Un code copié avant ce réglage n'a pas le champ : son widget ne change pas.

`themeEnVariables(theme)` transforme le thème en **variables CSS** posées sur la racine du widget : `--pl-w-primaire`, `--pl-w-texte`, `--pl-w-carte`… (une par couleur), `--pl-w-rayon-conteneur`, `--pl-w-rayon-carte`, `--pl-w-rayon-bouton`, `--pl-w-police-titres`, `--pl-w-police-texte`, `--pl-w-graisse-titres`, `--pl-w-bordure` (plus de `--pl-w-ombre` : le widget n'a plus d'ombre). Les feuilles `*.module.css` du widget n'utilisent que ces variables : aucune couleur n'est écrite dans le code, sauf les préréglages de `packages/core/src/partenaires/presets.ts`.

Le stockage (`packages/stockage/src/partenaires.ts`, entrée `@flux/stockage/partenaires`) garde les partenaires dans le `localStorage`, clé `plutot-la-widget:partenaires:v1`, et prévient les autres onglets à chaque changement. Les partenaires livrés avec l'application (`plutot-la` et cinq partenaires de démonstration : `alpes-isere`, `chartreuse`, `grenoble-alpes-tourisme`, `pays-voironnais`, `societe-lac-paladru`) sont toujours disponibles ; une version enregistrée les remplace.

## Commandes

Depuis la racine du dépôt (pnpm 12.15) :

```bash
npx --yes pnpm@12.15.0 install          # une fois
pnpm dev:widget                          # application sur http://localhost:5176 (/editor, /examples…)
pnpm --filter @flux/widget-app build     # vérification des types, puis dist/ (application + dist/embed/plutot-la-widget.js)
pnpm --filter @flux/widget-app typecheck # types de l'application ; --filter @flux/widget pour le paquet d'intégration
pnpm exec vitest run packages/widget packages/widget-editeur   # tests du widget et de son site
node scripts/check-styles.mjs --strict   # CSS séparé, et design simplifié : aucune ombre hors élément flottant, aucun mode sombre
pnpm check                               # biome, CSS séparé, couches des paquets et types de tout le monorepo
```

En développement, `/embed/plutot-la-widget.js` est servi directement par la source (`widget/src/embed.ts`, extension de `vite.config.ts`) : les pages `/examples/…` marchent aussi avec `pnpm dev:widget`. Le port 3003 est réservé au portail : ne pas y lancer le widget.

## Déploiement sur Vercel

Un projet Vercel **à part**, sur le même dépôt, comme l'application Plutôt là :

| Réglage du projet | Valeur |
|---|---|
| Root Directory | `widget` |
| Include source files outside of the Root Directory | activé (le widget importe `packages/*`) |
| Framework Preset | Vite (repris de `widget/vercel.json`) |
| Commandes | celles de `widget/vercel.json` : installation pnpm 12.15 figée, `pnpm run build`, sortie `dist` |
| Variables d'environnement | **aucune** |

:::howto{caption="Source : widget/vercel.json"}
Rien à saisir à la main en dehors du Root Directory et de l'option des fichiers hors du dossier : le reste est dans `widget/vercel.json`.
:::

`widget/vercel.json` règle aussi les en-têtes :

- `/embed/…` : `Access-Control-Allow-Origin: *` (tout site peut charger le script en module) et un cache court de 5 minutes, pour que les offices reçoivent vite les nouvelles versions ;
- `/assets/…` : même autorisation, cache d'un an (les noms de fichiers changent à chaque version) ;
- `/examples/…` : `X-Robots-Tag: noindex, nofollow`, pour que les copies de pages d'offices ne soient pas indexées ;
- partout : `X-Content-Type-Options: nosniff` et `Referrer-Policy: strict-origin-when-cross-origin`.

Un push sur `main` déclenche le déploiement : il se fait seulement à la demande de l'équipe.

## Limites

:::limits
- Le widget charge le jeu de données complet de Plutôt là (1,8 Mo, environ 300 Ko compressés, mesurés sur le build du 10 novembre 2026), même pour un badge d'une ligne. Des fichiers de prévisions précalculés par lieu (proposition `/donnees/v1/lieux/…` de la page [Intégration et écosystème](/plutotla/integration-et-ecosysteme)) l'allégeraient.
- La police et la couleur du texte de la page hôte traversent le Shadow DOM (voulu pour « Police du site ») ; le reste est remis à zéro, mais un site qui pose des styles très particuliers sur l'élément lui-même (`plutot-la-widget { … }`) peut encore en changer la boîte. Les déclarations des polices Fredoka et Nunito sont posées dans l'en-tête de la page hôte : sous une politique de sécurité stricte, elles demandent `style-src 'unsafe-inline'` (voir le [tutoriel](/widgets/integrer)).
- Pas de version dans l'adresse du script (`/embed/plutot-la-widget.js`) : un changement incompatible du format des partenaires toucherait tous les sites. Le champ `version` du format sert à le détecter.
- Aucun serveur : pas de signalement en direct, pas de statistiques d'usage, pas de partage des réglages entre personnes.
:::
