feat(web): moteur de tutoriel guidé driver.js (#42) #60

Merged

kyuno merged 1 commit from feat/tour-engine into main

2026-09-06 06:53:24 +02:00

kyuno commented

2026-09-06 06:34:38 +02:00

Owner

Le moteur front du tutoriel guidé, sur le socle backend de #42/#44 (PRs #58 + #59). Deux tours : orientation générale (auto sur /) et correction des métadonnées de recette (auto à l'ouverture du premier popover de correction).

Contenu

Dépendance driver.js (~5 ko gzippé, MIT, zéro dépendance — cf. le comparatif de l'issue #42).
features/tour/tour-engine.ts — wrapper vanilla (aucun React) autour de driver.js. driver.js gère le halo/popover et attend qu'une cible soit montée (waitForElement) ; ce wrapper ajoute les deux choses qu'il ne fait pas seul :
- navigation inter-routes : avant de passer à une étape dont la route diffère du chemin courant, navigate() ;
- une issue unique : onFinish appelé exactement une fois, "completed" seulement si on atteint la fin, "skipped" pour la croix / Échap / clic sur l'overlay.
features/tour/TourContext.tsx — TourProvider (charge scénarios + progression, effet keyed sur user?.id comme ThemeContext) et useTour() (startTour(key) / isTourCompleted(key) / tours / isReady).
- isReady est calculé au render contre l'id utilisateur pour lequel les données ont été chargées — pas stocké dans un state. Sans ça, une course réelle : à l'instant où user arrive, les effets enfants tournent avant celui du parent, donc l'auto-déclenchement voyait isReady === true avec un completedKeys encore vide (chargé déconnecté) et relançait le tour même s'il avait déjà été vu. (Reproduit puis corrigé — cf. le scénario Cypress « un tour déjà vu ne se relance pas ».)
main.tsx — <TourProvider> sous ThemeProvider.
Attributs data-tour : liens de nav (AppLayout), grille du planning + bouton + du 1er créneau + bouton « Cuisiner » (PlanningPage), page liste de courses (ShoppingListPage), description d'étape éditable + section technique du popover (StepDescription / TechStepCorrectionPopover).
Déclenchement auto : tour general sur / (PlanningPage, useRef pour ne tirer qu'une fois par montage), tour techStepMetadata quand activeCorrection passe non-null en mode éditable (StepDescription). startTour no-ope si déjà vu / déjà en cours.
Section « Revoir un tutoriel » dans /parametres/preferences-utilisateur — un map sur tours, un bouton « Revoir » par scénario (scale à un 3e tour sans changement).
tour.scss re-skinne le popover driver.js sur les tokens du thème.
i18n tour.* — chrome uniquement (boutons du popover, section « Revoir ») ; le contenu des étapes vient de la base (texte libre administrable, cf. #44).

Le tour techStepMetadata reste court (2 étapes) : #36 (popover qui se ferme en pleine sélection) est ouvert — v1 ne couvre que les gestes qui marchent déjà.

Tests

cypress/e2e/tour.feature (5) : auto-démarrage + élément surligné (.driver-active-element) pour un nouveau venu ; « Terminé » → complétion enregistrée skipped:false ; croix → skipped:true ; un tour déjà vu ne se relance pas ; « Revoir » le relance depuis les paramètres. 5/5 en local, + 35 spécs de non-régression (smoke/layout/planning-page/sidebar/recipes/user-preferences) vertes. pnpm build + pnpm lint verts.

Suite

Page admin /admin/didacticiels (l'UI CRUD par-dessus l'API #59) — prête, poussée juste après.

Refs #42

🤖 Generated with Claude Code

Le moteur front du tutoriel guidé, sur le socle backend de #42/#44 (PRs #58 + #59). Deux tours : **orientation générale** (auto sur `/`) et **correction des métadonnées de recette** (auto à l'ouverture du premier popover de correction). ## Contenu - **Dépendance `driver.js`** (~5 ko gzippé, MIT, zéro dépendance — cf. le comparatif de l'issue #42). - **`features/tour/tour-engine.ts`** — wrapper vanilla (aucun React) autour de `driver.js`. `driver.js` gère le halo/popover et attend qu'une cible soit montée (`waitForElement`) ; ce wrapper ajoute les deux choses qu'il ne fait pas seul : - **navigation inter-routes** : avant de passer à une étape dont la `route` diffère du chemin courant, `navigate()` ; - **une issue unique** : `onFinish` appelé exactement une fois, `"completed"` seulement si on atteint la fin, `"skipped"` pour la croix / Échap / clic sur l'overlay. - **`features/tour/TourContext.tsx`** — `TourProvider` (charge scénarios + progression, effet keyed sur `user?.id` comme `ThemeContext`) et `useTour()` (`startTour(key)` / `isTourCompleted(key)` / `tours` / `isReady`). - `isReady` est **calculé au render** contre l'id utilisateur pour lequel les données ont été chargées — pas stocké dans un state. Sans ça, une course réelle : à l'instant où `user` arrive, les effets enfants tournent *avant* celui du parent, donc l'auto-déclenchement voyait `isReady === true` avec un `completedKeys` encore vide (chargé déconnecté) et relançait le tour même s'il avait déjà été vu. (Reproduit puis corrigé — cf. le scénario Cypress « un tour déjà vu ne se relance pas ».) - **`main.tsx`** — `<TourProvider>` sous `ThemeProvider`. - **Attributs `data-tour`** : liens de nav (`AppLayout`), grille du planning + bouton `+` du 1er créneau + bouton « Cuisiner » (`PlanningPage`), page liste de courses (`ShoppingListPage`), description d'étape éditable + section technique du popover (`StepDescription` / `TechStepCorrectionPopover`). - **Déclenchement auto** : tour `general` sur `/` (`PlanningPage`, `useRef` pour ne tirer qu'une fois par montage), tour `techStepMetadata` quand `activeCorrection` passe non-null en mode éditable (`StepDescription`). `startTour` no-ope si déjà vu / déjà en cours. - **Section « Revoir un tutoriel »** dans `/parametres/preferences-utilisateur` — un `map` sur `tours`, un bouton « Revoir » par scénario (scale à un 3e tour sans changement). - **`tour.scss`** re-skinne le popover `driver.js` sur les tokens du thème. - **i18n `tour.*`** — chrome uniquement (boutons du popover, section « Revoir ») ; le contenu des étapes vient de la base (texte libre administrable, cf. #44). Le tour `techStepMetadata` reste court (2 étapes) : #36 (popover qui se ferme en pleine sélection) est ouvert — v1 ne couvre que les gestes qui marchent déjà. ## Tests `cypress/e2e/tour.feature` (5) : auto-démarrage + élément surligné (`.driver-active-element`) pour un nouveau venu ; « Terminé » → complétion enregistrée `skipped:false` ; croix → `skipped:true` ; **un tour déjà vu ne se relance pas** ; « Revoir » le relance depuis les paramètres. **5/5 en local**, + 35 spécs de non-régression (`smoke`/`layout`/`planning-page`/`sidebar`/`recipes`/`user-preferences`) vertes. `pnpm build` + `pnpm lint` verts. ## Suite Page admin `/admin/didacticiels` (l'UI CRUD par-dessus l'API #59) — prête, poussée juste après. Refs #42 🤖 Generated with [Claude Code](https://claude.com/claude-code)

kyuno added 1 commit 2026-09-06 06:34:38 +02:00

feat(web): moteur de tutoriel guidé driver.js (#42 )

CI / lint (push) Successful in 3m55s

Details

CI / build (push) Successful in 4m53s

Details

CI / intent-service-test (push) Successful in 5m52s

Details

CI / e2e (push) Successful in 10m30s

Details

CI / test (push) Successful in 18m43s

Details

38fcf03417

Consomme le socle backend de #42/#44 (`GET /reference/tours`,
`GET/POST /profile/tours`). Deux tours : orientation générale (auto sur
`/`) et correction des métadonnées de recette (auto à l'ouverture du
premier popover de correction).

- Dépendance `driver.js` (~5 ko, MIT, zéro dépendance).
- `features/tour/tour-engine.ts` : wrapper vanilla autour de `driver.js` —
  gère ce que la lib ne fait pas seule : la navigation React Router entre
  étapes situées sur des routes différentes, et un `onFinish` unique
  (`"completed"` seulement si on atteint la fin, `"skipped"` pour la croix
  / Échap / clic sur l'overlay).
- `features/tour/TourContext.tsx` : `TourProvider` (charge scénarios +
  progression, keyed sur `user?.id` comme `ThemeContext`) et `useTour()`
  (`startTour(key)` / `isTourCompleted(key)` / `tours` / `isReady`).
  `isReady` est **calculé au render** contre l'id utilisateur chargé — pas
  stocké — pour qu'un changement de `user` le repasse à `false`
  immédiatement, avant qu'un effet enfant (l'auto-déclenchement) ne tourne
  sur des données de complétion périmées.
- `main.tsx` : `<TourProvider>` sous `ThemeProvider`.
- Attributs `data-tour-*` : liens de nav (`AppLayout`), grille / bouton `+`
  du 1er créneau / bouton Cuisiner (`PlanningPage`), page liste de courses
  (`ShoppingListPage`), description d'étape + section technique du popover
  (`StepDescription` / `TechStepCorrectionPopover`).
- Déclenchement auto : tour `general` sur `/` (`PlanningPage`, ref-gardé),
  tour `techStepMetadata` à `activeCorrection` non-null (`StepDescription`).
- Section « Revoir un tutoriel » dans `/parametres/preferences-utilisateur`
  — un `map` sur `tours`, un bouton « Revoir » par scénario.
- `tour.scss` re-skinne le popover `driver.js` sur les tokens du thème.
- i18n `tour.*` (chrome uniquement : boutons du popover, section « Revoir » ;
  le contenu des étapes vient de la base).

Tests Cypress (`tour.feature`, 5 scénarios) : auto-démarrage + élément
surligné pour un nouveau venu ; « Terminé » → complétion enregistrée
`skipped:false` ; croix → `skipped:true` ; un tour déjà vu ne se relance
pas ; « Revoir » le relance depuis les paramètres. Vérifié 5/5 en local.
`pnpm build` + `pnpm lint` verts.

Refs #42
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>