Onboarding : bandeau de démarrage sur chaque page #397

New issue

Closed

opened 2026-10-07 23:49:58 +00:00 by maximus · 0 comments

maximus commented

2026-10-07 23:49:58 +00:00

Owner

Milestone planned-2026-10-06-onboarding-parcours-guide, issue 2/6. Phase 2 de l'onboarding (#391) : bandeau de démarrage sur chaque page, et cartes d'étape avec mise en évidence. La spec (spec-decisions-onboarding-parcours-guide.md et spec-plan-onboarding-parcours-guide.md) est locale et ignorée par git : ce corps est auto-suffisant.

Le bandeau remplace la barre compacte du tableau de bord et suit l'utilisateur partout : « Démarrage n/N · Étape suivante : <étape> → ». La liste détaillée se déplie depuis le bandeau. Paramètres → Utilisateurs lit l'état partagé.

À faire

src/components/onboarding/OnboardingBanner.tsx, piloté par props (testable par renderToStaticMarkup) :
- role="region", aria-label={t("onboarding.banner.label")}, icône Rocket (lucide) ;
- style de CategoriesV1DiscoveryBanner : border-[var(--primary)]/30 bg-[var(--primary)]/5 ;
- compteur onboarding.banner.progress, puis « Étape suivante : » et le libellé de l'étape (onboarding.checklist.items.<clé>) en lien vers nextStep.to. L'état de navigation vaut { onboarding: { focus: true } }, avec guided: true en plus pour manualCategory ;
- « Voir la liste » / « Fermer la liste » déplie en place OnboardingChecklist en mode expanded, avec aria-expanded ;
- « Masquer » appelle hide() ;
- mode complete : message onboarding.banner.complete, lien « Ouvrir le guide » vers /settings/users#gettingStarted (la section porte id={key}, DocsContent.tsx:124, clé gettingStarted à :25, défilement par le hash à :66-75) et « Fermer », qui appelle hide().
Montage dans AppShell, en tête de <main> avant <Outlet/>, dans le flux (pas de position fixe), quand useOnboarding().mode vaut banner ou complete. Le bandeau n'apparaît pas :
- quand le parcours est masqué ;
- sur le tableau de bord d'un profil sans transaction (D11 : la carte d'accueil suffit) ;
- sur une page en mode card ;
- avant le premier chargement.
Le compteur attend budgetReady, comme la barre compacte aujourd'hui (DashboardPage.tsx, garde budgetReady).
Tableau de bord : la barre compacte disparaît (D7). Retirer le mode compact d'OnboardingChecklist et ses tests. La carte d'accueil du profil vide (DashboardEmptyState) garde la liste détaillée.
OnboardingChecklist :
- états annoncés aux lecteurs d'écran (#384) par un texte masqué visuellement : onboarding.state.done, .skipped, .locked, .pending ;
- état « passée » : icône SkipForward, badge onboarding.checklist.skippedBadge, et lien onboarding.checklist.resume, qui appelle resume(key) puis navigue vers item.to avec l'état de focus ;
- les liens des lignes non faites portent aussi l'état de focus.
UsersSettingsPage :
- prend hidden et show dans useOnboarding() et ne lit plus la préférence elle-même (:23-40 aujourd'hui) ;
- garde seulement un drapeau local pour la confirmation ;
- le bouton de réaffichage se met à jour sur la page même, puisque le bandeau peut masquer le parcours depuis cette page ;
- nouveaux textes settings.users.onboarding.label et .confirmation.
CHANGELOG FR et EN : Added (le bandeau) et Changed (la barre compacte retirée, le réaffichage).

Textes (FR / EN)

Clé	FR	EN
`onboarding.banner.label`	Parcours de démarrage	Getting-started path
`onboarding.banner.progress`	Démarrage {{done}}/{{total}}	Getting started {{done}}/{{total}}
`onboarding.banner.next`	Étape suivante :	Next step:
`onboarding.banner.showList`	Voir la liste	Show the list
`onboarding.banner.hideList`	Fermer la liste	Close the list
`onboarding.banner.complete`	Démarrage terminé. Le guide d'utilisation vous accompagne pour la suite.	Getting started complete. The user guide takes it from here.
`onboarding.banner.openGuide`	Ouvrir le guide	Open the guide
`onboarding.state.done` / `.skipped` / `.locked` / `.pending`	(faite) / (passée) / (verrouillée) / (en attente)	(done) / (skipped) / (locked) / (pending)
`onboarding.checklist.skippedBadge`	Passée	Skipped
`onboarding.checklist.resume`	Reprendre	Resume
`settings.users.onboarding.label`	Parcours de démarrage	Getting-started path
`settings.users.onboarding.confirmation`	Le parcours de démarrage réapparaît en haut des pages	The getting-started path reappears at the top of the pages

« Masquer » réutilise onboarding.checklist.hide, et « Fermer » réutilise common.close.

Fichiers concernés

src/components/onboarding/OnboardingBanner.tsx (+ OnboardingBanner.render.test.tsx)
src/components/layout/AppShell.tsx
src/pages/DashboardPage.tsx
src/components/dashboard/OnboardingChecklist.tsx (+ OnboardingChecklist.test.tsx)
src/pages/settings/UsersSettingsPage.tsx
src/i18n/locales/fr.json, en.json
CHANGELOG.md, CHANGELOG.fr.md

Depends on

#396

Critères d'acceptation

OnboardingBanner (tests de rendu) : compteur ; lien vers nextStep.to avec son état ; aria-expanded selon la liste ; mode fin avec « Ouvrir le guide » et « Fermer » ; rien en mode none.
Bandeau absent sur le tableau de bord vide, quand le parcours est masqué et avant le premier chargement ; présent ailleurs. Comme CARD_PAGES est encore vide, il reste aussi sur /import, /transactions et /budget.
Plus de barre compacte ni de mode compact (tests retirés ou adaptés) ; DashboardEmptyState inchangé.
OnboardingChecklist (tests) : textes d'état annoncés, et ligne passée avec son badge et « Reprendre ».
UsersSettingsPage : le bouton de réaffichage apparaît dès que le parcours est masqué depuis le bandeau sur cette page, sans remontage.
Tous les textes en FR et en EN ; CHANGELOG FR et EN ; npm run build et npx vitest run verts.

Review caveats

Une pile mergée en partie ne doit retirer aucun guidage : tant qu'une page n'est pas dans CARD_PAGES, le bandeau y reste.
UsersSettingsPage ne doit plus lire la préférence elle-même : le fournisseur est le seul écrivain.

Décisions prises en planification

D1 : bandeau en haut de chaque page, dans le flux (WCAG 2.4.11).
D4 : message de fin, puis disparition par « Fermer », jusqu'à un réaffichage.
D7 : le bandeau remplace la barre compacte ; la liste détaillée reste dans la carte d'accueil et s'ouvre depuis le bandeau.
D11 : pas de bandeau sur le tableau de bord d'un profil vide.
D8 : un seul état masqué, la préférence onboarding_checklist_hidden par profil ; masquer le bandeau masque la liste, et le réaffichage depuis Paramètres → Utilisateurs rétablit tout.
Le fournisseur d'onboarding est le seul écrivain des préférences d'onboarding (hidden, étapes passées, initialisation).

Spec source

spec-plan-onboarding-parcours-guide.md (et spec-decisions-onboarding-parcours-guide.md)

Milestone `planned-2026-10-06-onboarding-parcours-guide`, issue 2/6. Phase 2 de l'onboarding (#391) : bandeau de démarrage sur chaque page, et cartes d'étape avec mise en évidence. La spec (`spec-decisions-onboarding-parcours-guide.md` et `spec-plan-onboarding-parcours-guide.md`) est locale et ignorée par git : ce corps est auto-suffisant. Le bandeau remplace la barre compacte du tableau de bord et suit l'utilisateur partout : « Démarrage n/N · Étape suivante : <étape> → ». La liste détaillée se déplie depuis le bandeau. Paramètres → Utilisateurs lit l'état partagé. ## À faire 1. **`src/components/onboarding/OnboardingBanner.tsx`**, piloté par props (testable par `renderToStaticMarkup`) : - `role="region"`, `aria-label={t("onboarding.banner.label")}`, icône `Rocket` (lucide) ; - style de `CategoriesV1DiscoveryBanner` : `border-[var(--primary)]/30 bg-[var(--primary)]/5` ; - compteur `onboarding.banner.progress`, puis « Étape suivante : » et le libellé de l'étape (`onboarding.checklist.items.<clé>`) en lien vers `nextStep.to`. L'état de navigation vaut `{ onboarding: { focus: true } }`, avec `guided: true` en plus pour `manualCategory` ; - « Voir la liste » / « Fermer la liste » déplie en place `OnboardingChecklist` en mode `expanded`, avec `aria-expanded` ; - « Masquer » appelle `hide()` ; - mode `complete` : message `onboarding.banner.complete`, lien « Ouvrir le guide » vers `/settings/users#gettingStarted` (la section porte `id={key}`, `DocsContent.tsx:124`, clé `gettingStarted` à `:25`, défilement par le hash à `:66-75`) et « Fermer », qui appelle `hide()`. 2. **Montage dans `AppShell`**, en tête de `<main>` avant `<Outlet/>`, dans le flux (pas de position fixe), quand `useOnboarding().mode` vaut `banner` ou `complete`. Le bandeau n'apparaît pas : - quand le parcours est masqué ; - sur le tableau de bord d'un profil sans transaction (D11 : la carte d'accueil suffit) ; - sur une page en mode `card` ; - avant le premier chargement. Le compteur attend `budgetReady`, comme la barre compacte aujourd'hui (`DashboardPage.tsx`, garde `budgetReady`). 3. **Tableau de bord** : la barre compacte disparaît (D7). Retirer le mode `compact` d'`OnboardingChecklist` et ses tests. La carte d'accueil du profil vide (`DashboardEmptyState`) garde la liste détaillée. 4. **`OnboardingChecklist`** : - états annoncés aux lecteurs d'écran (#384) par un texte masqué visuellement : `onboarding.state.done`, `.skipped`, `.locked`, `.pending` ; - état « passée » : icône `SkipForward`, badge `onboarding.checklist.skippedBadge`, et lien `onboarding.checklist.resume`, qui appelle `resume(key)` puis navigue vers `item.to` avec l'état de focus ; - les liens des lignes non faites portent aussi l'état de focus. 5. **`UsersSettingsPage`** : - prend `hidden` et `show` dans `useOnboarding()` et ne lit plus la préférence elle-même (`:23-40` aujourd'hui) ; - garde seulement un drapeau local pour la confirmation ; - le bouton de réaffichage se met à jour sur la page même, puisque le bandeau peut masquer le parcours depuis cette page ; - nouveaux textes `settings.users.onboarding.label` et `.confirmation`. 6. **CHANGELOG** FR et EN : Added (le bandeau) et Changed (la barre compacte retirée, le réaffichage). ## Textes (FR / EN) | Clé | FR | EN | |---|---|---| | `onboarding.banner.label` | Parcours de démarrage | Getting-started path | | `onboarding.banner.progress` | Démarrage {{done}}/{{total}} | Getting started {{done}}/{{total}} | | `onboarding.banner.next` | Étape suivante : | Next step: | | `onboarding.banner.showList` | Voir la liste | Show the list | | `onboarding.banner.hideList` | Fermer la liste | Close the list | | `onboarding.banner.complete` | Démarrage terminé. Le guide d'utilisation vous accompagne pour la suite. | Getting started complete. The user guide takes it from here. | | `onboarding.banner.openGuide` | Ouvrir le guide | Open the guide | | `onboarding.state.done` / `.skipped` / `.locked` / `.pending` | (faite) / (passée) / (verrouillée) / (en attente) | (done) / (skipped) / (locked) / (pending) | | `onboarding.checklist.skippedBadge` | Passée | Skipped | | `onboarding.checklist.resume` | Reprendre | Resume | | `settings.users.onboarding.label` | Parcours de démarrage | Getting-started path | | `settings.users.onboarding.confirmation` | Le parcours de démarrage réapparaît en haut des pages | The getting-started path reappears at the top of the pages | « Masquer » réutilise `onboarding.checklist.hide`, et « Fermer » réutilise `common.close`. ## Fichiers concernés - src/components/onboarding/OnboardingBanner.tsx (+ OnboardingBanner.render.test.tsx) - src/components/layout/AppShell.tsx - src/pages/DashboardPage.tsx - src/components/dashboard/OnboardingChecklist.tsx (+ OnboardingChecklist.test.tsx) - src/pages/settings/UsersSettingsPage.tsx - src/i18n/locales/fr.json, en.json - CHANGELOG.md, CHANGELOG.fr.md ## Depends on - #396 ## Critères d'acceptation - [ ] `OnboardingBanner` (tests de rendu) : compteur ; lien vers `nextStep.to` avec son état ; `aria-expanded` selon la liste ; mode fin avec « Ouvrir le guide » et « Fermer » ; rien en mode `none`. - [ ] Bandeau absent sur le tableau de bord vide, quand le parcours est masqué et avant le premier chargement ; présent ailleurs. Comme `CARD_PAGES` est encore vide, il reste aussi sur /import, /transactions et /budget. - [ ] Plus de barre compacte ni de mode `compact` (tests retirés ou adaptés) ; `DashboardEmptyState` inchangé. - [ ] `OnboardingChecklist` (tests) : textes d'état annoncés, et ligne passée avec son badge et « Reprendre ». - [ ] `UsersSettingsPage` : le bouton de réaffichage apparaît dès que le parcours est masqué depuis le bandeau sur cette page, sans remontage. - [ ] Tous les textes en FR et en EN ; CHANGELOG FR et EN ; `npm run build` et `npx vitest run` verts. ## Review caveats - Une pile mergée en partie ne doit retirer aucun guidage : tant qu'une page n'est pas dans `CARD_PAGES`, le bandeau y reste. - `UsersSettingsPage` ne doit plus lire la préférence elle-même : le fournisseur est le seul écrivain. ## Décisions prises en planification - D1 : bandeau en haut de chaque page, dans le flux (WCAG 2.4.11). - D4 : message de fin, puis disparition par « Fermer », jusqu'à un réaffichage. - D7 : le bandeau remplace la barre compacte ; la liste détaillée reste dans la carte d'accueil et s'ouvre depuis le bandeau. - D11 : pas de bandeau sur le tableau de bord d'un profil vide. - D8 : un seul état masqué, la préférence `onboarding_checklist_hidden` par profil ; masquer le bandeau masque la liste, et le réaffichage depuis Paramètres → Utilisateurs rétablit tout. - Le fournisseur d'onboarding est le seul écrivain des préférences d'onboarding (`hidden`, étapes passées, initialisation). ## Spec source spec-plan-onboarding-parcours-guide.md (et spec-decisions-onboarding-parcours-guide.md)