chore(memory): R2 finish BDR-116, LRN-136..138, BLK-015 note, plan and contract

This commit is contained in:
bchanot committed 2026-11-13 23:59:39 +01:00
1 parent 3a7ffa2f8b
commit afc1051313
6 files changed
+469

No files matched your search

@@ -0,0 +1,235 @@
# R2 UX finish — design and plan (rev 3a: rev 3 approved by the owner 2026-11-13, precisions folded)
Contract: `.claude/tasks/contracts/2026-11-13-r2-ux-finish-1624.md` (verbatim owner brief 2026-11-13, criteria 1-12).
Worktree `/home/bchanot/Documents/faunosteo-v1-2`, branch `feature/v1-2-anatomical-sheets`, base `36c6eb3`. Commit in place,
push by hook, never merge. Analysis: `.superpowers/sdd/r2-ux-finish/analysis.md`. Rev 1 challenged (FATAL 10 / FATAL 13 /
CONCERNS 3), rev 2 re-challenged (CONCERNS 10 / 8 / 3, no BLOCKER); rev 3 folds every rev 2 MAJOR (record at the end).
## Global rules (bind every task)
- No change under supabase/, crates/, docker/, scripts/, packages/supabase/src. No db:trial or DEV access. No merge, no deploy.
- Shell tests only on db:sandbox through the guarded wrapper (preflight refuses editor-equine, full-row guard):
`bash /home/bchanot/Documents/faunosteo-v1-2/.superpowers/sdd/r2-ux-finish/gate/run-shell.sh <label> e2e/shell/<spec>.spec.ts …`
(untracked copy; the brief checks it exists and stops if not). Never playwright directly, never editor-equine (its
helper edits are typecheck-only, said so). admin.spec red under BLK-015, never a gate. Each task's gate runs EVERY shell
spec that uses a helper, an i18n key, a test id or a component the task changes (grep, listed in the report), and
reports the grants its runs added.
- One modal primitive: ModalDialog / Dialog (D13). No hand-written trap, no new dependency. e2e waits for the open dialog
count to reach 0 before typing after a close (LRN-111/116). happy-dom 20.10.6 has no `:modal`, no inert, no popover API:
code detects open modals with `dialog[open]`, and behaviours needing real top-layer semantics are proved in e2e.
- No native modal inside a hidden KeptPlace. One ModalDialog instance per layer, kept across its modes and flips.
- Transactional forms on local draft state only (never TextField / blur-commit fields, never the change-commit checkbox):
« Abandonner », a move or a flip never commits.
- Document history (Défaire/Refaire) and browser history stay separate.
- i18n: fr.ts and en.ts, one line per key, no formatter on them (they are exempt from `prettier --check`: 188 pre-existing
lines over the print width; stated deviation); new EN labels provisional, rows in V1-2-6_R2_LABELS.md.
- Limits 25 logic lines / function, 100 chars / line, 5 params, 5 locals; `prettier --check` on every other touched file.
Every removed or rewritten assertion mapped (R-24). Motion: motion/react, reduced motion honoured, no permanent will-change.
## Design
### R2F-1 Browser history for the editor (item 5)
- History records only the editor VIEW, held by the navigation reducer (single holder): `EditorView = { tab, section,
finding: { key, citations: boolean } | { create: { kind, parent } } | null, reference: { edit: id } | { create: true } |
null, referenceFilter: ElementKey | null }`. Selection, expansion, search, sort, open tiles and a dialog's edit mode never
touch history.
- Moves dispatch at once (as today, through `go`); history follows from ONE reconcile effect, mounted as its own hook in
EditorWorkspace (no dependency of useEditorNavigation on a router; tolerant of MemoryRouter and a missing `idx`). It
compares the new view with the last written entry, read from a ref holding what it wrote (never `useLocation()`, which
lags one transition):
- a layer, tab or section ADDED by a user move → push `{ view, below }` (`below` = previous view);
- a layer REMOVED by a user move → `navigate(-1)` when the top entry's `below` equals the new view, else replace;
- replace hints: an arrow-key tab move, the chip removal, a creation turned into its element after « Créer » / save.
A second close finds no layer and does nothing; a held Escape is ignored by `event.repeat`; the exiting surface is inert
through motion `useIsPresent` (the CitationsLayer pattern). While a `back()` is pending the effect writes nothing; the
pending flag clears on the next POP of any kind or after 1 s.
- Pushes: a tab chosen by click / Enter / « Plus », an Annotations section, the finding dialog, a finding creation, the
citations sheet, the reference dialog (edit or create), « Tout afficher », « Aller à ». The move captures `scrollY`
synchronously before its dispatch into a map keyed by the leaving entry; a POP stores the leaving entry's scroll too.
- POP (Back / Forward): `restore_view(sanitize(view))` (vanished keys drop their layer; a node creation whose parent vanished
dropped), scroll from the map, then focus: a reopened layer → its dialog's first control; a closed layer → its return
target; a tab change with no layer → the active tab button. All POP focus uses `preventScroll`; announcements and
landings go through `afterModalsClosed` (R2F-2).
- Guards (a stack keyed by layer, replacing the single CanLeave slot): a UI close of a dirty form shows the inline
confirmation and never moves; « Abandonner » / « Enregistrer » pop their guard before closing; a push that would close a
dirty layer (« Tout afficher », « Aller à ») asks first; ANY POP that would remove a dirty layer, or that happens while a
non-layer modal (DeleteDialog, ConfirmDialog, ConflictDialog, views dialogs) is open, re-pushes the full pre-POP view
(below = the landed view) and keeps everything mounted, then the dirty layer shows its confirmation.
- Ownership (owner precision 3): every entry also stores `sheetId` and `userId`; an entry restores only when both match the
current sheet and signed-in account, otherwise the default view (a POP or mount onto a foreign entry replaces it).
Entries hold navigation only: never typed text, a search term or a draft.
- Mount: an entry carrying editor state is restored through sanitize WITHOUT form layers (creation, reference dialog,
finding edit mode is local anyway); an entry without one is replaced by the default view.
- Write failures: react-router's push turns a refused pushState into a page load; the adapter keeps a write budget
(sliding window, well under WebKit's 100 / 10 s) and, past it, keeps the view in memory without writing; replaces are
wrapped in try/catch. Stated: a refused push would reload (out of reach at one push per user move).
- Limits stated: leaving the editor by Back past its first entry is unguarded (BDR-078; recovery copy); a sheet reopened by
Back shows its tiles closed; Chromium's skippable-entry intervention after a script re-push and Android's close-watcher
grouping of two restored dialogs are untested (Playwright's goBack bypasses them), checked in the owner's phone trial.
### R2F-2 Shared dialog primitives
- ModalDialog re-shows (`showModal()`) only when its consumer REFUSED a close (`onClose` returns `'kept'`) and the
`<dialog>` was closed natively; never during an AnimatePresence exit (useIsPresent) or a history close. Unit: a Dialog
set closed then natively closed stays closed.
- `returnFocus?: (() => HTMLElement | null) | null`: a function resolves the target (focused with `preventScroll`, falling
back to the captured opener then its ancestors when it returns null); `null` skips the restore (the move owns focus).
- `afterModalsClosed(fn)`: runs `fn` once no `dialog[open]` remains (flushed from ModalDialog's cleanup / `close` event);
used by the announcer (queued messages joined into ONE announcement) and every focus landing that follows a close.
`focusRow` reports `found` only when the row actually holds focus.
- Escape with `event.repeat` ignored; Dialog's fade honours reduced motion.
- Return targets: tree rows get a `data-finding-key` attribute (no tabindex change); « X références » through the existing
`triggerOf` + `visibleElement`; tile headers by key; the add buttons by id.
- `useBeforeUnload(dirty)` extracted from useLeaveGuard's effect, used by dirty dialogs; leaveGuardStore untouched.
- Place-scoped dialogs (DeleteDialog …) stay valid: a POP while one is open is refused by re-push (R2F-1).
### R2F-3 Finding dialog (items 1, 3)
- Rendered by FindingsTab (owns selection, expansion, creation, deletion), gated by the place being visible, driven by
`nav.finding`. Row activation (click, Enter, Space) selects the row and opens the dialog. Tree, expansion and scroll never
change; on close focus returns to the row (`data-finding-key`, preventScroll). The detail below the tree and the inline
creation form are removed.
- View mode: type and status, names, descriptions, vet referral (read); « Références citées », « X références » (finding
nodes with citations; opens the sheet), « Aucune référence citée », « Citer une référence » (edit tier, immediate, one
history entry). No inline citation list for a finding node; a family keeps its list with « Retirer ». Actions (edit tier):
« Modifier », mark reviewed / reset, move up / down, « Supprimer » (DeleteDialog stacked, returnFocus null; the deletion
closes the finding layer in the same move by replace — no POP — and the nearest-row focus runs via afterModalsClosed).
- Edit mode local (no history entry), local draft state: names (required), descriptions, vet referral. « Enregistrer »:
pristine → view mode, no command; changed → ONE `update` command (one history entry), refusal on its field (focus
there), success → view mode with « Modifications enregistrées » in the dialog's status line. « Annuler » → view mode
(dirty: confirmation first).
- Creation (AddBar): `{ create: { kind, parent } }`, FindingCreateForm fields on local state; « Créer » → command, entry
replaced by `{ key }`, view mode of the new element (the `created` flow expands and selects behind).
- Dirty close request (✕, Annuler, Escape, scrim, Back, platform): footer confirmation « Abandonner les modifications ? »,
« Continuer la saisie » (focused), « Abandonner ». The confirmation is never inert.
- Read-only: view mode without actions. When the mode leaves edit while a form is open, the dialog keeps the draft, fields
`readOnly` + `aria-readonly`, « Enregistrer » disabled, and a notice worded from the mode (ModeNotice's wording: width
→ « Élargissez la fenêtre … », back on widening; frozen / inactive / rights → only « Abandonner »).
releaseEditFocus / refocusIfHidden return early when focus is inside an open dialog.
- Gone: if the element vanishes under the dialog (a reload after a conflict), the layer closes by replace with a queued
announcement « Ce constat n'existe plus ». « Aller à » (Vérification) opens view mode.
- While a dialog is open, Défaire/Refaire and the header save are unreachable (page inert): stated.
### R2F-4 Citations sheet (items 3, 4, 5)
Side sheet on MobileDrawer's pattern at the right edge (min(34 rem, 100 vw), full height, 0.18 s in / 0.14 s out),
rendered by the layer host placed AFTER the tab body in tree order (so it calls showModal after the finding dialog; e2e
asserts the top dialog after Back and Forward), stacked over the finding dialog; return focus « X références ». Content
kept (read tiles, « Modifier », « Retirer de ce constat », « Aller à », « Tout afficher »). « Tout afficher » pushes
`{ tab: references, referenceFilter: finding, no layer }` (search cleared, sort kept); « Aller à » pushes the references
tab with the tile focused through afterModalsClosed. Gone rule as R2F-3. Deleted with the section (tests mapped):
CitationsLayer and its geometry and cramped exception, the tab panels' `inert={open}`, useCitationsExit / PendingClose /
`afterExit`, useRequestClose, useCloseMoves, the panel branch of useTabSelect, focusAfterClose and focusIsFree (triggerOf
and visibleElement kept), the panel-only parts of useBodyEscape and the workspace Escape handler, the citationsOf gate of
useDecisionsOpen, useCloseWhenGone / dropCitations (replaced by the gone rule).
Interim until Task 3 (tiles still edit inline in the sheet): the sheet ignores Escape coming from a tile text field (A5 /
P27 kept), and every move that unmounts the sheet (✕, scrim, Back, « Tout afficher », « Aller à ») consults the tiles'
guard; a refusal cancels the move.
### R2F-5 Reference dialog and reading tiles (items 2, 9)
- Tiles: disclosure, « Modifier », « Supprimer » or the cited hint. Deleted (tests mapped): the inline edit view in tiles,
useReferenceEdit drafts and leave guard, DroppedNote / useDroppedDrafts / hostLeaving / `draft_dropped`, NewReferenceTile
and the « Annuler l'ajout » tile, useLeaveCheck, the interim sheet rules of R2F-4.
- ReferenceDialog (layer host, above the sheet): type, DOI, citation (required), URL (http/https), local draft, same
validation. « Enregistrer »: pristine → close, no command; changed → ONE add / update command, refusal on its field;
a creation's entry is replaced by `{ edit: id }` before closing. Dirty close and mode change: as R2F-3.
- After close: scroll, search, sort, filter, open tiles unchanged; focus to the opener. Edited tile pinned when it no
longer matches the search (C3 line kept). After a create: queued announcement and a visible notice « Référence ajoutée :
<citation> » with « Afficher » (useReferenceFocus); the list does not move.
- Residuals: no inline draft outside a dialog, Défaire/Refaire unreachable during a dialog: residual 9a and 9b cannot occur
(tests: an undo shortcut and a mode flip leave an open dialog's draft untouched).
### R2F-6 References filtered by a finding (item 4)
`referenceFilter` passed to shownPositions and the count. `isSheetView` requires no filter (reorder arrows off) and the pin
is applied only when there is no filter (a pinned tile outside the filter never shows). Toolbar chip « Références du
constat : <name> » with « × » (« Retirer le filtre du constat <name> », replace) and « Revenir au constat » while the filter
is set (pops when the entry below shows that finding, else pushes its dialog). Count within the filter; the no-result
notice keeps its clear actions; a vanished finding clears the filter with a queued announcement. BDR-114 A row updated in
RUST_ARCHITECTURE_REVIEW Part II.
### R2F-7 « Plus » dropdown (item 6) and sticky sidebar (item 7)
- The menu list renders as an overlay `absolute inset-x-0 top-full z-20` in the tab row made `relative` (full width: never
off-screen, no measuring, no layout shift), AnimatePresence: opacity + translateY(-4 px) in 0.15 s, out 0.12 s, instant
under reduced motion; closing entries are inert and never focused. Closes on selection, outside pointerdown (the closing
tap is stopped from reaching the page: no deselection), Escape (useMoreEscape, A5), any tab change, and the platform back request through a `CloseWatcher` created when the menu
opens, where the browser offers it (owner precision 4; feature-detected, unit-tested with a stub); without CloseWatcher
the Android back gesture goes back in history (stated limit).
- Sidebar aside `sticky top-0 h-dvh self-start overflow-y-auto` where shown (lg default, xl editor); drawer unchanged.
### R2F-8 App-wide review (item 8)
| Screen | Decision | Reason |
|---|---|---|
| Editor Constats, Références | modals | long lists, form far from its item |
| Editor categories, views, regions, Vertèbres | kept inline | short lists, form by its list |
| Admin species | already a modal | — |
| Admin access (grants) | kept: form above the list | nothing to lose; size is RR-13 |
| Clients, Animaux lists | pages kept; list context on Back not done | BDR-078 refused keeping the search term (personal data) to survive Back: owner choice |
| Relations | kept in-page | §11.4 ratified |
| Mon compte | kept inline | sections, no list |
### R2F-9 Ratified rules this design changes (owner, at the gate)
1. BDR-050: transactional forms in the finding and reference dialogs (one entry per changed save); U2b F9 to re-plan.
2. D2 / boards 24-25 / P16-P17: the citations panel becomes a modal side sheet over the finding dialog (still from a
finding only); its section geometry and the rotation cramped exception disappear.
3. A2: the editor's view layers live in the browser's session history; a reload keeps the tab, section, filter and
reading layers, never a form.
4. A3: « Tout afficher » filters by the finding (owner request). 5. Board 27 A: « Plus » becomes an overlay (owner request).
6. Design-reference rule: no new mockups; owner brief + this gate = validation, dated addendum in docs/design/README.md.
7. Open: clients/animals list context on Back would keep the search term (personal data) in browser history (BDR-078
refused it). Default: not done.
## Tasks (5)
### Task 1 — Shared dialog primitives and history foundations (tabs, sections, « Aller à »)
ModalDialog / Dialog (R2F-2: kept-refusal re-show, returnFocus, afterModalsClosed, repeat Escape, reduced motion),
announcer queue, focusRow check, useBeforeUnload extraction; history reconcile hook (R2F-1) wired to tab, section and
« Aller à » moves only (the citations panel and new layers are not in history yet), mount rule, scroll map, guard stack
(with the POP-refusal while a non-layer modal is open), write budget; residual 9c formatting. Unit (incl. the 6
editor-focus-request tests without a Router and the 14 MemoryRouter suites green) + new e2e/shell/editor-history.spec.ts
(tabs and sections back/forward, landing focus, arrow replace, reload, a DeleteDialog open + Back keeps it). Gate: grep-found
specs (EditorTabs, sections, dialogs app-wide incl. e2e/ui dialog, shell, clients, animals).
### Task 2 — Finding dialog and citations sheet (items 1, 3, 4 partly, 5)
Owner precision 2: the sheet over the finding dialog is proved by keyboard (Tab through every control, Escape closes the
sheet only, focus back on « X références ») and by touch (hasTouch taps at 375, the dialog underneath never activated).
R2F-3 and R2F-4 with the interim rules; history for the finding layer, creation, the sheet, « Tout afficher » (tab +
search cleared until Task 3 adds the filter) and « Aller à » from the sheet; deletions named; helpers (open a finding =
activate its row and wait for its dialog; openCitations / closeCitations on the sheet) and every spec using them. Unit +
e2e per R2F-3/R2F-4 (scroll and expansion identical after close at 1280; pristine save no entry, changed save one;
Abandonner and a flip commit nothing; dirty Escape and Back ask; flip 1280 → 900 → 1280 keeps draft and focus; delete from
the dialog lands on the nearest row; gone rule; sheet at 1280 and 375 read-only; top dialog after Back / Forward; owner
steps 1-4 with Back and Forward).
### Task 3 — Reference dialog, reading tiles, filter by finding, owner journey (items 2, 4, 5, 9)
R2F-5 and R2F-6, deletions named (interim sheet rules removed), history for the reference dialog and the filter. Unit +
e2e per R2F-5/R2F-6, then the owner's 8 steps at 1280 and on the phone project at 375 (Back → finding A with its sheet
open and on top; Forward → filtered tab), Back presses to leave = pushes made (no orphan), double clicks on ✕ and
« Enregistrer » and a held Escape pop at most one entry, a real `dialog.close()` on a dirty dialog keeps it with its
confirmation, a dirty dialog + Back (one step and a cross-tab jump) keeps the draft, reload then Back.
### Task 4 — « Plus » dropdown and sticky sidebar (items 6, 7)
R2F-7. Unit (open / close, outside pointerdown not reaching the page, Escape order) + e2e at 375 and 320 (boxes identical
open vs closed, axe menu open) and at 1280 / 1024 (sidebar first link in view after scrolling; own scroll at 1280 × 500;
no sideways scroll; axe from the top).
### Task 5 — Documentation and closure
docs/design/README.md (dated addendum = R2F-9), V1-2-6_U1_CORRECTIONS (§R2 « Finition 2026-11-13 »), V1-2-6_OWNER_TRIAL
(§4.11 short db:trial procedure, French, incl. the phone checks of the stated limits), V1-2-6_R2_LABELS, BROWSER_TESTS,
CLAUDE.md tree lines.
## Verification (controller)
Static gates, unit, e2e:ui, full shell sweep (all specs but editor-equine; admin.spec reported; grants added reported),
gates.sh, fresh verifier, security gate, opus xhigh review, memory, French final report with the db:trial procedure.
## Challenge record
Rev 1 → 2: latch and repeat Escape; below in entries; guard disarm; native-close re-show; return targets; queued
announcer; creation kind; finding dialog + sheet in one task; isSheetView; sections; scroll map; writes on view change
only; arrow replace; readOnly on flip; pristine save; own beforeunload; lists task dropped (BDR-078); local edit mode;
« Aller à » view mode; single filter holder; MobileDrawer and useReferenceFocus reuse; named deletions.
Rev 2 → 3: close-first + reconcile effect, no UI latch (sim-1, cor-1, rob-9); one re-push rule, no idx (sim-2, cor-6,
rob-5); mount id dropped, landed entry restored (sim-3, cor-3, rob-12); afterModalsClosed for focus and announcements,
focusRow checked (sim-4, cor-7, rob-8); push refusal reloads → write budget (sim-6, rob-2, cor-11); finding.citations
(sim-7); triggerOf / visibleElement and useBeforeUnload reused (sim-8); 5 tasks, journey in Task 3 (sim-9); plain overlay
for « Plus » (sim-5, cor-15, rob-13); re-show only on a kept refusal (rob-1); gone rule kept (rob-3, cor-8); host after
the tab body + top-dialog assertion (rob-4, cor-2); interim A5 / guard rules (rob-6, rob-7, cor-13); preventScroll on
resolved targets and POP landings, scroll captured before dispatch (rob-11, cor-4); non-layer modal open → POP refused
(cor-5); entry read from a ref (cor-10); guard stack (cor-12); happy-dom limits (cor-14); data-finding-key (cor-16);
creation replaced before close (cor-17); fr/en prettier exemption stated (cor-18); flip notice from the mode (rob-16);
announcer joins messages (rob-17); wrapper copied into the worktree (rob-14); skippable entry untested (rob-10);
adapter as its own hook, MemoryRouter-tolerant (rob-15); pin off under a filter (cor-9).