chore(memory): R2 finish BDR-116, LRN-136..138, BLK-015 note, plan and contract
This commit is contained in:
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).
|
||||
Reference in new issue
Block a user