maximus/Simpl-Resultat

Fork 0

feat(docs): sub-sections in the user guide and bank CSV export guides (#355) #381

Merged

maximus merged 1 commit from issue-355-docs-bank-guides into main

2026-10-04 12:51:44 +00:00

maximus commented

2026-10-04 00:00:49 +00:00

Owner

Fixes #355

Stacked on PR #380 (issue-354-sample-import-folders), itself on #379 → #378 → #377. Review only the last commit (e0ee09b); the base must be merged first.

What

DocsSubsections.tsx (new, pure, only useTranslation): reads docs.<sectionKey>.subsections with returnObjects and renders one block per entry — <div id> registered through registerRef, h4 title, italic status line when present, <ol> of steps, trailing note when present. Returns null when the key is absent (i18next echoes the key string in that case, so the check is Array.isArray, not truthiness). Same Tailwind tokens as the surrounding DocsContent blocks.
DocsContent.tsx: <DocsSubsections> inserted after the "Comment faire" block and before the tips; registerRef writes into sectionRefs.current[id], so the existing location.hash → scrollIntoView effect reaches #import-export, #import-bnc, etc. No other change.
fr.json / en.json: docs.import.subsections with the six entries import-export, import-desjardins, import-tangerine, import-rbc, import-bnc, import-bmo (EN = faithful translation, proper nouns kept). Only the Import section declares the key.
docs/guide-utilisateur.md: the same six blocks in chapter 4 (### Exporter un CSV depuis votre banque + five ####), the « Créer un dossier d'exemple » button mentioned in chapter 4 "Comment faire" (wording of #356), and chapter 1 "Démarrage rapide" rewritten as the six onboarding.checklist.items.* labels in the same order, each followed by a short gloss.
DocsSubsections.test.tsx: direct-call tests (pattern of FilterPanel.test.tsx).

Why

A new user needs to know how to get a CSV out of their bank before the import wizard is of any use; the guide now says so per bank, with an honest verification status (only Tangerine is confirmed by an official source; BMO's format is not recognised yet, #371). The sub-section anchors are what #356 will link to from the Import empty state.

Privacy

The BNC and BMO blocks ask the user to send a header line through the feedback form. All three copies (fr.json, en.json, markdown) carry the warning: never paste an account number, a balance or a real transaction — the feedback is a text message sent to a server, the only exception to the app working locally. No real bank data anywhere; the sample header is the literal one the detector expects.

Decisions worth a look

The issue writes « Paramètres → Systèmes → Rétroaction »; the shipped labels are « Système » / "System" and « Envoyer un feedback » / "Send feedback" (settings.systems.title, feedback.button), so the guide uses those.
docs.gettingStarted.steps and docs.import.steps in the JSON files are not rewritten: the issue lists only the markdown for those two changes and the acceptance criterion freezes the rendering of the eleven other sections. The in-app "Premiers pas" quick start therefore still shows the older seven steps; aligning it with the checklist is a one-line follow-up if wanted.
No CHANGELOG entry (centralised in #357). No DB migration.

How tested

npm test: 77 files, 1425 tests green (5 new in DocsSubsections.test.tsx: null without sub-sections, blocks + ids + ref registration, status/note present-or-absent, malformed entries dropped, missing key).
npm run build (tsc + vite): green.
Script check: both JSON files parse, docs.import.subsections has 6 entries with identical ids, identical per-entry key sets and identical step counts (4/5/5/5/2/5) in FR and EN; subsections appears under no other docs.* section; the BNC and BMO notes contain the warning in both languages.
Round-trip of the JSON files through json.dumps(indent=2) was verified identical before editing, so the diff is the 75 added lines per file and nothing else.

Generated autonomously by /autopilot run of 2026-10-03

🤖 Generated with Claude Code

Fixes #355 **Stacked on PR #380** (`issue-354-sample-import-folders`), itself on #379 → #378 → #377. Review only the last commit (`e0ee09b`); the base must be merged first. ## What - **`DocsSubsections.tsx`** (new, pure, only `useTranslation`): reads `docs.<sectionKey>.subsections` with `returnObjects` and renders one block per entry — `<div id>` registered through `registerRef`, `h4` title, italic status line when present, `<ol>` of steps, trailing note when present. Returns `null` when the key is absent (i18next echoes the key string in that case, so the check is `Array.isArray`, not truthiness). Same Tailwind tokens as the surrounding `DocsContent` blocks. - **`DocsContent.tsx`**: `<DocsSubsections>` inserted after the "Comment faire" block and before the tips; `registerRef` writes into `sectionRefs.current[id]`, so the existing `location.hash` → `scrollIntoView` effect reaches `#import-export`, `#import-bnc`, etc. No other change. - **`fr.json` / `en.json`**: `docs.import.subsections` with the six entries `import-export`, `import-desjardins`, `import-tangerine`, `import-rbc`, `import-bnc`, `import-bmo` (EN = faithful translation, proper nouns kept). Only the Import section declares the key. - **`docs/guide-utilisateur.md`**: the same six blocks in chapter 4 (`### Exporter un CSV depuis votre banque` + five `####`), the « Créer un dossier d'exemple » button mentioned in chapter 4 "Comment faire" (wording of #356), and chapter 1 "Démarrage rapide" rewritten as the six `onboarding.checklist.items.*` labels in the same order, each followed by a short gloss. - **`DocsSubsections.test.tsx`**: direct-call tests (pattern of `FilterPanel.test.tsx`). ## Why A new user needs to know how to get a CSV out of their bank before the import wizard is of any use; the guide now says so per bank, with an honest verification status (only Tangerine is confirmed by an official source; BMO's format is not recognised yet, #371). The sub-section anchors are what #356 will link to from the Import empty state. ## Privacy The BNC and BMO blocks ask the user to send a header line through the feedback form. All three copies (fr.json, en.json, markdown) carry the warning: never paste an account number, a balance or a real transaction — the feedback is a text message sent to a server, the only exception to the app working locally. No real bank data anywhere; the sample header is the literal one the detector expects. ## Decisions worth a look - The issue writes « Paramètres → Systèmes → Rétroaction »; the shipped labels are « Système » / "System" and « Envoyer un feedback » / "Send feedback" (`settings.systems.title`, `feedback.button`), so the guide uses those. - `docs.gettingStarted.steps` and `docs.import.steps` in the JSON files are **not** rewritten: the issue lists only the markdown for those two changes and the acceptance criterion freezes the rendering of the eleven other sections. The in-app "Premiers pas" quick start therefore still shows the older seven steps; aligning it with the checklist is a one-line follow-up if wanted. - No CHANGELOG entry (centralised in #357). No DB migration. ## How tested - `npm test`: 77 files, **1425 tests** green (5 new in `DocsSubsections.test.tsx`: null without sub-sections, blocks + ids + ref registration, status/note present-or-absent, malformed entries dropped, missing key). - `npm run build` (tsc + vite): green. - Script check: both JSON files parse, `docs.import.subsections` has 6 entries with identical ids, identical per-entry key sets and identical step counts (4/5/5/5/2/5) in FR and EN; `subsections` appears under no other `docs.*` section; the BNC and BMO notes contain the warning in both languages. - Round-trip of the JSON files through `json.dumps(indent=2)` was verified identical before editing, so the diff is the 75 added lines per file and nothing else. Generated autonomously by /autopilot run of 2026-10-03 🤖 Generated with [Claude Code](https://claude.com/claude-code)

maximus added 1 commit 2026-10-04 00:00:50 +00:00

feat(docs): sub-sections in the user guide and bank CSV export guides (#355 )

PR Check — Frontend / frontend (pull_request) Successful in 1m53s

Details

e0ee09bca7

Add an optional `subsections` array to a user-guide section, rendered by
the new pure `DocsSubsections` component between the "How to" block and
the tips. Each entry has an id, a title, an optional italic status line,
an ordered list of steps and an optional trailing note. The ids are
registered in `sectionRefs` of `DocsContent`, so the existing hash
navigation (`/settings/users#import-export`) reaches the sub-sections
too. Only the Import section declares the key; the eleven other
sections render exactly as before.

The Import section gets six blocks in French and English: a generic
"export a CSV from your bank" block, then Desjardins, Tangerine, RBC,
National Bank and BMO with their verification status. The National Bank
and BMO blocks, which ask the user to send a header line through the
feedback form, carry the warning never to paste an account number, a
balance or a real transaction, in the JSON files and in the markdown
guide alike.

`docs/guide-utilisateur.md` receives the same six blocks in chapter 4,
a mention of the "Create a sample folder" button in its "How to", and a
"Quick start" in chapter 1 rewritten as the six steps of the
getting-started checklist, same order and wording as
`onboarding.checklist.items.*`.

`DocsSubsections.test.tsx` calls the component directly (no jsdom):
null for a section without sub-sections, one block per entry with its
id and ref registration, status line and note rendered only when
present, malformed entries dropped.

Resolves #355

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

maximus added the

autopilot:pending-human

label 2026-10-04 00:00:57 +00:00

maximus commented

2026-10-04 00:02:10 +00:00

Author

Owner

Self-review (autopilot 2026-10-03) — Verdict: APPROVE

Reviewed the full pulls/381.diff (6 files, 555 lines) against issue #355.

Summary

Pure DocsSubsections component + one insertion point in DocsContent; six FR/EN blocks under docs.import.subsections only; the markdown guide carries the same six blocks, the sample-folder button mention and a six-step "Démarrage rapide" aligned on the checklist. No CHANGELOG, no migration, no hard-coded string in the components.

Acceptance criteria

Criterion	Status	Evidence
`DocsSubsections.test.tsx`: no `subsections` → `null`; with → one block per entry, ids set, status line present/absent	✅	3 component tests + 2 on `readSubsections`; `t` mock echoes the key like i18next, so the null path is the real one
`/settings/users#import-export` and `#import-bnc` scroll to the block	✅ (by code reading)	`registerRef` writes `sectionRefs.current[id]`; refs are attached at commit, before the `[location.hash]` effect runs; `scroll-mt-4` on each block like the sections. Not exercised in a browser (autopilot)
Six blocks FR + EN, same meaning; BNC and BMO carry « ne collez jamais… »	✅	Script check: 6/6 ids identical, step counts 4/5/5/5/2/5 in both, same key sets; warning present in the `note` of both blocks in both languages, and in the markdown (bold)
Eleven other sections render exactly as before	✅	`subsections` exists under `docs.import` only (checked in both files); `DocsSubsections` returns `null` for them; `docs.gettingStarted.steps` untouched
`guide-utilisateur.md` « Démarrage rapide » = six steps aligned on `onboarding.checklist.items.*`	✅	The six labels appear verbatim at the start of each line, same order (profil → dossier → source → fichier → classer à la main → budget)
`npm test`, `npm run build` green	✅	77 files / 1425 tests; tsc + vite build OK

Security / privacy

No real bank data: the only sample header is the literal Date;Description;Catégorie;Débit;Crédit;Solde the detector already expects.
The warning is in the three copies, attached to both blocks that send anything through the feedback form; it names the exception to the local-only principle explicitly.
The guide path uses the shipped labels (« Paramètres → Système → Envoyer un feedback ») rather than the issue's wording, so the reader lands on the right button.

Concerns (non-blocking)

The in-app "Premiers pas" quick start (docs.gettingStarted.steps) keeps its older seven steps while the markdown now has the six checklist steps. The issue scoped the rewrite to the markdown and freezes the other sections' rendering; aligning the JSON is a one-line follow-up if Max wants the three copies identical there.
The « Créer un dossier d'exemple » button described in chapter 4 ships with #356 (next link of the pile); the guide is one link ahead of the UI until that PR lands.
The BMO note is long (one paragraph of five sentences) because the JSON shape allows a single trailing note; readable, but a notes: string[] would be the extension if a seventh bank needs it.

Generated autonomously by /autopilot run of 2026-10-03

## Self-review (autopilot 2026-10-03) — Verdict: **APPROVE** Reviewed the full `pulls/381.diff` (6 files, 555 lines) against issue #355. ### Summary Pure `DocsSubsections` component + one insertion point in `DocsContent`; six FR/EN blocks under `docs.import.subsections` only; the markdown guide carries the same six blocks, the sample-folder button mention and a six-step "Démarrage rapide" aligned on the checklist. No CHANGELOG, no migration, no hard-coded string in the components. ### Acceptance criteria | Criterion | Status | Evidence | |---|---|---| | `DocsSubsections.test.tsx`: no `subsections` → `null`; with → one block per entry, ids set, status line present/absent | ✅ | 3 component tests + 2 on `readSubsections`; `t` mock echoes the key like i18next, so the null path is the real one | | `/settings/users#import-export` and `#import-bnc` scroll to the block | ✅ (by code reading) | `registerRef` writes `sectionRefs.current[id]`; refs are attached at commit, before the `[location.hash]` effect runs; `scroll-mt-4` on each block like the sections. Not exercised in a browser (autopilot) | | Six blocks FR + EN, same meaning; BNC and BMO carry « ne collez jamais… » | ✅ | Script check: 6/6 ids identical, step counts 4/5/5/5/2/5 in both, same key sets; warning present in the `note` of both blocks in both languages, and in the markdown (bold) | | Eleven other sections render exactly as before | ✅ | `subsections` exists under `docs.import` only (checked in both files); `DocsSubsections` returns `null` for them; `docs.gettingStarted.steps` untouched | | `guide-utilisateur.md` « Démarrage rapide » = six steps aligned on `onboarding.checklist.items.*` | ✅ | The six labels appear verbatim at the start of each line, same order (profil → dossier → source → fichier → classer à la main → budget) | | `npm test`, `npm run build` green | ✅ | 77 files / 1425 tests; tsc + vite build OK | ### Security / privacy - No real bank data: the only sample header is the literal `Date;Description;Catégorie;Débit;Crédit;Solde` the detector already expects. - The warning is in the three copies, attached to both blocks that send anything through the feedback form; it names the exception to the local-only principle explicitly. - The guide path uses the shipped labels (« Paramètres → Système → Envoyer un feedback ») rather than the issue's wording, so the reader lands on the right button. ### Concerns (non-blocking) 1. The in-app "Premiers pas" quick start (`docs.gettingStarted.steps`) keeps its older seven steps while the markdown now has the six checklist steps. The issue scoped the rewrite to the markdown and freezes the other sections' rendering; aligning the JSON is a one-line follow-up if Max wants the three copies identical there. 2. The « Créer un dossier d'exemple » button described in chapter 4 ships with #356 (next link of the pile); the guide is one link ahead of the UI until that PR lands. 3. The BMO `note` is long (one paragraph of five sentences) because the JSON shape allows a single trailing note; readable, but a `notes: string[]` would be the extension if a seventh bank needs it. Generated autonomously by /autopilot run of 2026-10-03

maximus referenced this pull request

2026-10-04 00:10:55 +00:00

feat(onboarding): Import empty states, sample folder button and guide links (#356) #382

maximus referenced this pull request

2026-10-04 00:26:59 +00:00

docs(onboarding): changelog, architecture, user guide and interactive QA checklist (#357) #383

maximus commented

2026-10-04 01:51:23 +00:00

Author

Owner

Revue adversariale — Verdict : APPROVE

Revue de e0ee09b contre sa base issue-354-sample-import-folders (PR #380). Toutes les affirmations de la PR ont été retracées à la source et re-exécutées ; aucune n'est réfutée, aucun constat bloquant.

Prouvé (pas relayé)

Suite rejouée sur une copie hors dépôt (git archive e0ee09b) : 77 fichiers / 1425 tests verts, tsc exit 0. CI check-frontend verte sur la tête (1m53s, build + tests) — PR stackée, mais le workflow n'a pas de filtre branches:, elle a donc eu sa CI.
Six mutations du relecteur, six détectées (base 5/5 verts, fichier restauré à l'identique) : retrait du return null → 1 rouge ; garde Array.isArray(steps) retirée → 1 ; ref de registration retiré → 1 ; statut rendu inconditionnellement → 1 ; attribut id retiré → 1 ; mauvaise clé lue (.subsection) → 2.
En-tête BNC du guide = labels du détecteur src/utils/bankSignatures.ts:178-189 (date/description/categorie/debit/credit/solde, ; ou ,).
« Paramètres → Système → Envoyer un feedback » = settings.systems.title / feedback.button dans les deux langues, cohérent avec les lignes 569/633/640 du guide (le bouton vit dans la carte Journaux sous Système). Corriger « Systèmes → Rétroaction » de l'issue était le bon choix.
Les six labels onboarding.checklist.items.* ouvrent chaque ligne du « Démarrage rapide », même ordre ; « édition Base et plus » pour le Budget = src/shared/entitlements.ts:24.
Bouton « Créer un dossier d'exemple » = texte exact de la tâche #356 ; « Exemple Desjardins » / « Exemple Tangerine » = constantes fs_commands.rs:179-180 posées par #380.
subsections n'existe que sous docs.import dans les deux fichiers ; parité 6/6 (ids, jeux de clés, 4/5/5/5/2/5 étapes). Aucun autre id="import-*" dans src/ ; l'effet [location.hash] lit sectionRefs.current après le commit, les refs des sous-sections y sont.
Timeline de #355 : pull_ref closes depuis #381, et Resolves #355 dans le message de commit — fermeture quel que soit le chemin de merge.
Le test lit block.props.ref : valide parce que React 19 expose ref comme prop ordinaire (^19.1.0). À savoir si le projet descendait un jour de version.

Suggestions (non bloquantes)

Provenance interne dans un texte affiché à l'utilisateur. Le status du bloc BMO dans fr.json / en.json dit « fournie par Max le 2026-10-03 … (#371) ». Dans le markdown c'est une trace utile ; dans l'app, un numéro d'issue Forgejo et le prénom du développeur ne parlent à personne. Le texte vient mot pour mot de l'issue : décision de planification, pas erreur du worker. À trancher par Max — « Procédure reconstituée d'après une description générale, à confirmer sur un compte réel ; format de fichier non encore reconnu » suffirait dans les JSON.
Les deux « Démarrage rapide » divergent : le markdown a les six étapes de la liste, l'in-app (docs.gettingStarted.steps) garde les sept anciennes ; de même docs.import.steps[1] ne mentionne pas le bouton d'exemple que le markdown décrit. Cadré ainsi par l'issue (gel des onze autres sections) ; suivi d'une ligne une fois #356 posé.
« le seed de mots-clés » (chapitre 1) est du jargon pour un guide utilisateur ; « les mots-clés fournis avec l'application ».
Le guide est un maillon en avance sur l'UI (#356) : merger la pile dans l'ordre, rien à changer ici.

Actions faites

Copies hors dépôt (pr381, pr381-mut) et JSON extraits supprimés ; aucun fichier /tmp/pr381-* restant.
Libellé de #355 déjà status:approved (self-review autopilot) : verdict concordant, inchangé.

## Revue adversariale — Verdict : **APPROVE** Revue de `e0ee09b` contre sa base `issue-354-sample-import-folders` (PR #380). Toutes les affirmations de la PR ont été retracées à la source et re-exécutées ; aucune n'est réfutée, aucun constat bloquant. ### Prouvé (pas relayé) - **Suite rejouée** sur une copie hors dépôt (`git archive e0ee09b`) : 77 fichiers / 1425 tests verts, `tsc` exit 0. CI `check-frontend` verte sur la tête (1m53s, build + tests) — PR stackée, mais le workflow n'a pas de filtre `branches:`, elle a donc eu sa CI. - **Six mutations du relecteur, six détectées** (base 5/5 verts, fichier restauré à l'identique) : retrait du `return null` → 1 rouge ; garde `Array.isArray(steps)` retirée → 1 ; `ref` de registration retiré → 1 ; statut rendu inconditionnellement → 1 ; attribut `id` retiré → 1 ; mauvaise clé lue (`.subsection`) → 2. - En-tête BNC du guide = labels du détecteur `src/utils/bankSignatures.ts:178-189` (`date/description/categorie/debit/credit/solde`, `;` ou `,`). - « Paramètres → Système → Envoyer un feedback » = `settings.systems.title` / `feedback.button` dans les deux langues, cohérent avec les lignes 569/633/640 du guide (le bouton vit dans la carte Journaux sous Système). Corriger « Systèmes → Rétroaction » de l'issue était le bon choix. - Les six labels `onboarding.checklist.items.*` ouvrent chaque ligne du « Démarrage rapide », même ordre ; « édition Base et plus » pour le Budget = `src/shared/entitlements.ts:24`. - Bouton « Créer un dossier d'exemple » = texte exact de la tâche #356 ; « Exemple Desjardins » / « Exemple Tangerine » = constantes `fs_commands.rs:179-180` posées par #380. - `subsections` n'existe que sous `docs.import` dans les deux fichiers ; parité 6/6 (ids, jeux de clés, 4/5/5/5/2/5 étapes). Aucun autre `id="import-*"` dans `src/` ; l'effet `[location.hash]` lit `sectionRefs.current` après le commit, les refs des sous-sections y sont. - Timeline de #355 : `pull_ref` `closes` depuis #381, et `Resolves #355` dans le message de commit — fermeture quel que soit le chemin de merge. - Le test lit `block.props.ref` : valide parce que React 19 expose `ref` comme prop ordinaire (`^19.1.0`). À savoir si le projet descendait un jour de version. ### Suggestions (non bloquantes) 1. **Provenance interne dans un texte affiché à l'utilisateur.** Le `status` du bloc BMO dans `fr.json` / `en.json` dit « fournie par Max le 2026-10-03 … (#371) ». Dans le markdown c'est une trace utile ; dans l'app, un numéro d'issue Forgejo et le prénom du développeur ne parlent à personne. Le texte vient mot pour mot de l'issue : décision de planification, pas erreur du worker. À trancher par Max — « Procédure reconstituée d'après une description générale, à confirmer sur un compte réel ; format de fichier non encore reconnu » suffirait dans les JSON. 2. Les deux « Démarrage rapide » divergent : le markdown a les six étapes de la liste, l'in-app (`docs.gettingStarted.steps`) garde les sept anciennes ; de même `docs.import.steps[1]` ne mentionne pas le bouton d'exemple que le markdown décrit. Cadré ainsi par l'issue (gel des onze autres sections) ; suivi d'une ligne une fois #356 posé. 3. « le seed de mots-clés » (chapitre 1) est du jargon pour un guide utilisateur ; « les mots-clés fournis avec l'application ». 4. Le guide est un maillon en avance sur l'UI (#356) : merger la pile dans l'ordre, rien à changer ici. ### Actions faites - Copies hors dépôt (`pr381`, `pr381-mut`) et JSON extraits supprimés ; aucun fichier `/tmp/pr381-*` restant. - Libellé de #355 déjà `status:approved` (self-review autopilot) : verdict concordant, inchangé.

maximus referenced this pull request

2026-10-04 12:47:32 +00:00

docs(onboarding): changelog, architecture, user guide and interactive QA checklist (#357) #383

maximus referenced this pull request from a commit

2026-10-04 12:47:33 +00:00

fix(onboarding): apply the three review follow-ups on the stack head

maximus changed target branch from issue-354-sample-import-folders to main

2026-10-04 12:51:39 +00:00

maximus merged commit e0ee09bca7 into main

2026-10-04 12:51:44 +00:00

~~maximus referenced this pull request 2026-10-04 12:52:55 +00:00~~

Onboarding phase 1 : suivis restants des revues #377-#383 (épingles, carte Transactions, messages d’Import, dérives de docs) #384