docs(docs): V1-1.3 dialogs, browser tests and the D11 comparison

Contract §11.6: D13 final behaviour of the native modal dialog, D14 as built against the isolated stack, the three mobile navigation sources and their consequences for Clients and Animaux. BROWSER_TESTS.md: suites, prerequisites, guarantees, failures, limits. TEST_STRATEGY, SUPABASE §5.1, FRONTEND snapshot note, CLAUDE.md.
This commit is contained in:
bchanot committed 2026-10-25 23:37:00 +01:00
1 parent 9b2a4bc6fc
commit 9cd33f1217
6 files changed
+196 -16

No files matched your search

+56 -9
View File
@@ -1117,12 +1117,58 @@ project's design workflow.
Every field labelled; errors announced; focus to the page heading on
navigation and to the first error on submit; visible focus; nothing reachable
only by pointer; confirmation dialogs with focus containment (the `inert`
attribute on the rest of the page while open) and focus restored to the
opener, no new dependency (D13);
only by pointer; confirmation dialogs with focus containment and focus
restored to the opener, no new dependency (D13, final behaviour in §11.6);
status changes (saved, archived) announced through a live region; an axe check
per screen in the browser tests.
### 11.6 V1-1.3 as built (2026-10-25)
D13, final behaviour. `components/ui/ModalDialog.tsx` is the one modal
primitive, on the platform's `<dialog>` and `showModal()` (no dependency: none
of the project's dependencies holds an accessibility primitive, and the
browser's modal dialog is the proven one). `Dialog` and the mobile drawer are
built on it.
| Need | Behaviour |
|---|---|
| Name and description | the `<dialog>` is named by its visible title (`aria-labelledby`); `Dialog`'s optional `description` is wired with `aria-describedby`; the four confirmations pass their message there (photo removal, replace session, held session, sheet disclaimer); long bodies (forms, drawings) carry no description; the drawer is named « Navigation principale » |
| Opening | focus on the first control of the dialog (the close button for `Dialog`, the brand link for the drawer), set explicitly: Chromium would otherwise focus a scrollable panel when the content is long |
| Containment | the rest of the page is inert (top layer): no focus, no click, no screen-reader access; the page does not scroll behind (`html:has(dialog:modal)`); Tab past the last control reaches the browser's own interface for one step, then the first control again, never the page (the platform's choice, kept: no hand-written trap) |
| Escape and close requests | a request to the consumer through `onClose`, never a close by itself: the dialog leaves only when the consumer stops rendering it. The Escape keydown is cancelled, so Chromium's rule that closes a dialog on a second Escape after a cancelled one never applies; a close the platform forces anyway is reported to the consumer |
| Closing controls | the close button (« Fermer » / « Close »), the backdrop and the consumer's own buttons, all through the same request |
| Focus return | after the commit, to the opener when it can still take focus; otherwise to the first control of the opener's nearest container still on the page; nothing when the dialog opened without a focused opener (the disclaimer at editor load) |
| Pending actions | a confirmation whose action is in flight refuses to close (Escape, Cancel, backdrop) and closes when the action settles: the photo removal now does so, so focus moves past the vanished button instead of falling on the page |
Closing a dialog is never a save or a confirmed cancel: the consumer decides
what a request means. The V1-1 forms are full pages (§11.4), so the unsaved
changes confirmation of §11.3 belongs to the page, not to a dialog.
D14, as built. `@playwright/test` 1.64.1 and `@axe-core/playwright` 4.14.0
(axe-core 4.14.0), dev dependencies of `apps/app`, pinned; five packages in
the lockfile (Apache-2.0 for Playwright, MPL-2.0 for axe, used unmodified).
`pnpm e2e:ui` (no backend) and `pnpm e2e:shell` (the isolated stack), Chromium
desktop and 375 × 667; details, guarantees and limits in
`docs/development/BROWSER_TESTS.md`. Deviation from §12.5: the suites run
against the isolated stack, not against DEV, which holds neither M1 nor M2 and
stays untouched (owner choice, 2026-10-25).
D11, the mobile navigation conflict, documented for the decision before
V1-1.6 (owner, 2026-10-25: no tab bar in V1-1.3, current navigation kept, the
validated mockups unchanged).
| Source | Mobile navigation |
|---|---|
| Implemented | top bar (menu button, brand, language switcher, avatar link to Mon compte); the drawer (modal since V1-1.3) with the sidebar entries Tableau de bord, Mon compte, Outil de bilan, then the user badge and « Se déconnecter »; no bottom tab bar |
| Validated mockups (`docs/design/README.md` items 5 to 7) | the same drawer, plus a bottom tab bar on the dashboard and the profile: Accueil, Bilans, Agenda, Profil; the README places the bar « with the first list screens » |
| D11 recommendation (§13.3) | drawer only in V1-1; the mockup's tab bar arrives with Bilans (V1-3), when its entries lead somewhere |
| Option for the Clients and Animaux routes | Consequence |
|---|---|
| Drawer only (D11) | Clients and Animaux join the drawer and the sidebar; two taps from any page; no destination that leads nowhere; the README line moves to V1-3 once decided |
| The mockup's bar now | Bilans and Agenda lead nowhere until V1-3 and later (hidden or disabled tabs); Clients and Animaux stay in the drawer anyway; a fixed bottom bar competes with the save action that §11.4 keeps reachable with the keyboard open |
| A bar adapted to V1-1 (Accueil, Clients, Animaux, Profil) | one tap to the V1-1 screens; departs from the validated mockup, so it needs a new validated design file first; the bar changes again when Bilans and Agenda arrive |
---
## 12. Tests and Definition of Done
@@ -1205,8 +1251,9 @@ key parity.
### 12.5 Real browsers (Playwright and axe, D14)
A suite under `apps/app/e2e`, run against `pnpm dev` and the local stack on the
DEV origin. In V1-1: Chromium, desktop and a 375 × 667 phone viewport (Firefox,
A suite under `apps/app/e2e`, run against the isolated stack of
`pnpm db:sandbox` and a loopback dev server of its own (V1-1.3 deviation: DEV
holds neither M1 nor M2 and stays untouched, §11.6). In V1-1: Chromium, desktop and a 375 × 667 phone viewport (Firefox,
WebKit and 412 × 915 join at V1-5: WebKit's system libraries need `sudo`, a
user action, and desktop WebKit is not iOS Safari, which the owner's real
phone covers); journeys 1 to 7 of §11.2; the creation journey with the
@@ -1276,10 +1323,10 @@ Not ratified; recommendation and impact given.
| Id | Decision | Recommendation | Impact |
|---|---|---|---|
| D10 | Client information notice: text, and whether the app records that it was given | decide with the legal texts; nothing shown or recorded in V1-1 | none in V1-1; recording it later adds a column; required before public exposure |
| D11 | Mobile navigation | drawer only in V1-1; the mockup's tab bar (Accueil, Bilans, Agenda, Profil) arrives with Bilans (V1-3), since two of its four entries would lead nowhere today. `docs/design/README.md` says the tab bar comes "with the first list screens": the README line is updated once D11 is decided | UI |
| D11 | Mobile navigation (V1-1.3: current navigation kept, the three sources and their consequences in §11.6; decision before V1-1.6) | drawer only in V1-1; the mockup's tab bar (Accueil, Bilans, Agenda, Profil) arrives with Bilans (V1-3), since two of its four entries would lead nowhere today. `docs/design/README.md` says the tab bar comes "with the first list screens": the README line is updated once D11 is decided | UI |
| D12 | Dashboard tiles | the two real tiles (clients, animals) now, from live counts; bilans and appointments when their tables exist | UI |
| D13 | Shared `Dialog` focus containment and restore | fix it in V1-1 with `inert` and a restore to the opener, no dependency (it also improves the editor's dialogs; partial RR-7) | shared component |
| D14 | Real-browser test tooling | `@playwright/test` and `@axe-core/playwright` as dev dependencies of `apps/app`; Chromium only in V1-1, Firefox and WebKit at V1-5 | manifest and lockfile change at step V1-1.3; a browser download |
| D13 | Shared `Dialog` focus containment and restore | approved 2026-10-25, built in V1-1.3 on the native modal dialog (§11.6) | shared component |
| D14 | Real-browser test tooling | approved 2026-10-25, built in V1-1.3: Playwright 1.64.1 and axe 4.14.0, Chromium desktop and 375 px, against the isolated stack (§11.6) | manifest and lockfile; Chromium build 1248, no `sudo` |
| D17 | Bridge to the local tool (« start a bilan for this animal », prefill only) | no: V1-3 links bilans to animals properly; a prefill now would be a second path to delete later | none |
| U1 | Long lists | « Afficher plus » (keyset pages of 25), no numbered pages | UI |
| U2 | Archived records | one « archivés » toggle on each list, not a separate tab | UI |
@@ -1306,7 +1353,7 @@ validates after V1-1.1 and after the first UI step; nothing merges into
|---|---|
| V1-1.1 | Workspaces: M1 (with the correlation header cap), helpers, trigger, backfill, RLS, pgTAP `012`. Written and tested on an isolated stack (§8.1), awaiting the owner's checkpoint; not applied to DEV |
| V1-1.2 | Clients data: M2, RPCs, searches, D15 guards (budget per workspace, its lock), N9 audit policy, field limits and parity test, sandbox suite. Written and tested on the isolated stack (§8.2), awaiting the owner's checkpoint; not applied to DEV |
| V1-1.3 | UI foundations: Playwright Chromium and axe (D14), `Dialog` containment and restore (D13) |
| V1-1.3 | UI foundations: Playwright Chromium and axe (D14), `Dialog` containment and restore (D13). Built (§11.6), awaiting the owner's checkpoint |
| V1-1.4 | Animals and relations data: M3 with the species rows, RPCs, history rules, D9a proof |
| V1-1.5 | Clients UI: routes, forms, list and search, archive, navigation entry |
| V1-1.6 | Animals and relations UI, navigation (D11), dashboard tiles (D12), documents, Definition of Done |