495 lines
46 KiB
Markdown
495 lines
46 KiB
Markdown
# 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).
|
||
|
||
## Rev 4: owner trial 2026-11-14 (R2 validated; last adjustments, autonomous mandate)
|
||
|
||
Owner brief 2026-11-14: R2 main journeys validated. Accepted limits: same-instant move vs Back race, « Aller à » opens in
|
||
view mode, search kept across tabs, first outside tap only closes « Plus ». Android Back to verify on a real phone.
|
||
BLK-015 tracked separately. Probe (controller, pinned Chromium 156.0.8078.4, scratch page): a same-document `traverse`
|
||
`navigate` event is cancelable for a history-menu jump of -3 (CDP Page.navigateToHistoryEntry, userInitiated true), with
|
||
or without prior activation, and preventDefault keeps the page on its entry.
|
||
|
||
### Task 6: citing references moves to the edit mode (owner item 1)
|
||
- View mode (finding node): « Références citées » + « X références » (opens the side sheet) only; no « Citer une
|
||
référence », no remove. Family (category, no sheet per D2): label + read-only list, no « Retirer ».
|
||
- Edit mode (node and family): same label and button, plus the editable list of the DRAFT citations (each « Retirer »)
|
||
and « Citer une référence ». Citation changes live in the form draft (dirty check, « Abandonner les modifications ? »),
|
||
and « Enregistrer » writes names, descriptions, flag and citations as ONE undoable operation; pristine save none.
|
||
- The button always agrees with what the form shows: in edit mode it counts the draft and the sheet opened from the form
|
||
lists the draft's references. The side sheet becomes read-only for the finding: « Retirer de ce constat » leaves it
|
||
(removal only in the edit form); « Modifier » (the reference), « Aller à », « Tout afficher » stay.
|
||
- Creation dialog: no citations (unchanged). Tests: unit (view has no cite control; edit stages add/remove; one undo
|
||
restores names and citations together; Annuler with only a citation change asks), e2e on the finding dialog.
|
||
|
||
### Task 7: deletion, undo and Back; « Plus » keyboard focus (owner item 3, points 1 and 2)
|
||
- Deleting a finding (from its dialog or anywhere) closes its dialog by popping the dialog entry, never by replace: the
|
||
first Back after a deletion has a visible effect (limit 1 lifted). A later Forward onto the deleted element's entry
|
||
follows the existing gone rule.
|
||
- The first « Défaire » after a deletion restores the finding at once and visibly: its row exists, its branch expanded,
|
||
selected, scrolled into view and focused (Constats tab shown); no second « Défaire » needed. Same for « Refaire » of a
|
||
creation. Tests: unit + e2e (delete, one header « Défaire », row visible and selected; one Back after delete moves).
|
||
- « Plus »: choosing an entry (keyboard, also pointer) moves the focus to the new tab's panel (`role=tabpanel`,
|
||
`tabIndex=-1`, labelled by its tab) once the overlay is gone; focus ring only for keyboard (`:focus-visible`). Tests
|
||
unit + e2e at 375 (Enter on an entry: the panel of that tab is focused).
|
||
|
||
### Task 8: session tag in history; confirmation before a multi-entry leave (owner item 3, points 3 and 4)
|
||
- History entries carry `tag` (random 128-bit hex, crypto.getRandomValues) instead of `userId`; `sheetId` stays.
|
||
The tag lives in sessionStorage with the SHA-256 digest of the account id (crypto.subtle), reused only when the
|
||
digest matches the signed-in account, rotated on sign-out and on any account mismatch; storage failure → in-memory
|
||
tag (a reload then restores nothing). No tag yet → no restore (fail closed). The left-draft flag key uses the tag; flags
|
||
of a rotated tag are cleared. Entries with `userId` (older shape) read as foreign.
|
||
- Navigation API guard (`navigation` feature-detected): while a finding or reference dialog is dirty, a same-document
|
||
`traverse` whose destination leaves the editor route is cancelled when `event.cancelable`; the dialog's own
|
||
« Abandonner les modifications ? » shows; « Continuer la saisie » stays; « Abandonner » traverses to the destination
|
||
(`navigation.traverseTo(key)`) with no left-draft notice. Not cancelable or no API → the existing flag and notice.
|
||
In-editor traversals keep the existing refusal path. Tests: unit with a navigation stub; e2e with CDP
|
||
`Page.navigateToHistoryEntry` (jump of several entries out of the editor with a dirty dialog: confirm shown, URL and
|
||
draft kept; Abandonner lands on the destination).
|
||
|
||
### Task 9: R2 closure docs and the U2 orientation
|
||
- R2 validated by the owner's trial 2026-11-14: status lines (V1-2-6_U1_CORRECTIONS §R2, V1-2_ANATOMICAL_SHEETS notes),
|
||
limits (accepted list; lifted: delete dead Back, « Plus » focus to body; changed: tag, leave guard), §4.11 steps
|
||
adjusted, a §4.12 « Vérifications manuelles finales » list, labels, BROWSER_TESTS.
|
||
- U2 orientation (controller text, `u2-orientation.md` in the SDD folder) into V1-2-6_UX_PLAN §U2, V1-2-6_UX_DECISIONS
|
||
and docs/design/README.md (boards 02 to 06 and 13 to redraw at U2 planning, validated before U2 code).
|
||
|
||
## Rev 5: owner trial follow-up 2026-11-15 (two UX adjustments before R2 closure, autonomous mandate)
|
||
|
||
Owner brief 2026-11-15: the finding dialog's edit mode must not hold citations; a real references dialog, stacked over
|
||
the finding dialog, replaces the side sheet, with its own « Modifier ». One tab order on every width; « Plus » becomes a
|
||
vertical dropdown. Keep history, focus, Défaire/Refaire and the unsaved-changes protection (BDR-115, LRN-141).
|
||
Controller rulings (autonomous mandate, reported to the owner): families (categories) get the same dialog as nodes
|
||
(both hold citations; the edit form no longer does); the view mode is read only (no « Modifier » on its tiles); the
|
||
edit mode offers « Nouvelle référence » (created and cited in the draft); on phones the visible tabs are the first two
|
||
of the order (Général, Annotations), the rest under « Plus » in order.
|
||
|
||
### Task 10: one tab order, vertical « Plus » dropdown (owner item 2)
|
||
- `editor/tabs.ts` small tier: shown = first two of EDITOR_TABS (`general`, `annotations`), « Plus » = the rest in
|
||
order (`findings`, `references`, `verification`). initialTab and its comment follow (Général now shown on small).
|
||
- « Plus » shows the blocking-error count of Vérification while that tab sits under it (same text as the tab's badge).
|
||
- MoreList: a vertical list anchored under « Plus » (right-aligned to it), one entry per line, full-width rows
|
||
≥ 48 px high, comfortable padding, `rounded-lg` panel with shadow, max width `calc(100vw - 2rem)`, no sideways scroll
|
||
at 320 and 375 px. Active entry: accent background tint + check icon + `aria-current="true"` (text, not colour only).
|
||
Motion: opacity + 6 px slide + 0.98 scale from the top, ~160 ms ease-out in, ~120 ms out; none under reduced motion.
|
||
ArrowDown/ArrowUp (wrap), Home, End move the focus between entries. Every existing dismissal (Escape, outside
|
||
press, CloseWatcher, Tab-out, tab change) and the panel focus after a keyboard pick unchanged.
|
||
- Tests: unit (tabsFor order per tier; Plus count; arrows); e2e at 375 (row order, vertical list geometry: entries
|
||
stacked, each ≥ 44 px, inside the viewport; axe); update every spec that assumed the old small split.
|
||
|
||
### Task 11: the references dialog replaces the side sheet (view mode) (owner item 1)
|
||
- New `CitationsDialog` (components/editor/references): a `Dialog` (ModalDialog, D13) stacked over the finding dialog,
|
||
title « Références du constat », the finding path under it, hosted where CitationsSheet was (after the tab body,
|
||
before ReferenceDialog). Same history layer as the sheet (`finding.citations`), so Back, the leave cascade, the
|
||
reload restore and « Aller à » keep working; returnFocus = « X références ». CitationsSheet and its motion go.
|
||
- View mode: the cited references as tiles (expand to read, « Aller à » a citer), dangling ids named, « Tout afficher
|
||
dans l'onglet Références », close (✕, Escape, backdrop per Dialog, Back) back to the finding dialog. No « Modifier »
|
||
on tiles in this dialog (tile readOnly for edit actions); its own « Modifier » button (edit tier only, hidden when
|
||
read-only) switches to the edit mode (Task 12).
|
||
- Citable keys: categories and nodes (`isCitable`, replaces `isFindingNode` for citations, the references filter and
|
||
history read-back in navigation.ts, useEditorNavigation.ts, history/entry.ts, references/filter.ts as needed).
|
||
- Finding dialog: view and edit modes both show only « Références citées » + the « X références » button (count of
|
||
the document's citations, also at 0 so a reference can be added; zones none). FindingEditCitations, CitationList's
|
||
remove path, the family inline list and `editor/findings/citationDraft.ts` (shortcut store) go. FindingEditForm's
|
||
draft and patch no longer carry `reference_ids` (its save never rewrites citations).
|
||
- Tests: unit (dialog shows the cited tiles, no edit controls in view mode, button at 0, family opens it, the finding
|
||
edit patch keeps the current reference_ids); e2e editor-citations / editor-reference-journey / editor-finding-dialog
|
||
updated to the dialog (owner journey A → « 2 références » → « Tout afficher » → Back back on A with the references
|
||
dialog open; keyboard and touch at 375; axe).
|
||
|
||
### Task 12: edit mode of the references dialog (owner item 1)
|
||
- « Modifier » turns the dialog into a form (local mode, no history entry, like the finding dialog): the draft list
|
||
of cited references, each with « Modifier la référence » (the reference dialog stacked over this one, edits saved
|
||
by that dialog as today) and « Retirer » (dangling ids removable); « Citer une référence existante » (the library
|
||
references not cited yet); « Nouvelle référence » (the reference creation dialog stacked over this one: the
|
||
reducer allows `create_reference` over an open citations layer without leaving the tab; history read-back allows it;
|
||
on « Créer » the new id is appended to the draft). « Enregistrer » writes ONE `update` of the element's
|
||
`reference_ids` (one Défaire), pristine save none, then back to the view mode with « Enregistré » and focus on
|
||
« Modifier ». « Annuler » with changes asks « Abandonner les modifications ? ».
|
||
- Guard: a new layer name `citations` between `finding` and `reference` (LAYERS order = stacking). A dirty draft
|
||
refuses ✕, Escape, backdrop, Back and the editor leave cascade like the finding form (useFormDraft with layer
|
||
`citations`, FormActions, DiscardConfirm); the Back planner counts the citations layer as guarded only when it
|
||
holds a draft. « Tout afficher » and « Aller à » are not offered in edit mode.
|
||
- A finding edit draft under it and a references draft are independent (two fields of the same element, two saves,
|
||
two undo steps, neither overwrites the other). Undo/redo while the form is open follows the existing form rule.
|
||
- Tests: unit (stage add/remove/new, one save = one undo, pristine none, Annuler asks, guard refuses Back, creation
|
||
appends the new id, finding draft + references draft both saved); e2e (edit, cite, remove, save, one header
|
||
« Défaire »; dirty Back asks; stacked reference dialog from the edit list).
|
||
|
||
### Task 13: docs
|
||
- V1-2-6_U1_CORRECTIONS §R2 (subsection « Owner follow-up 2026-11-15 »; fix lines that describe the side sheet or
|
||
citing in the finding edit form), V1-2-6_OWNER_TRIAL (§4.11/§4.12 adjusted; new §4.13 « Vérification des deux
|
||
ajustements » short db:trial procedure), V1-2-6_R2_LABELS (keys added/removed), BROWSER_TESTS clauses,
|
||
docs/design/README.md (board 25 side sheet replaced by the references dialog; board 05 phone split changed by the
|
||
owner 2026-11-15).
|
||
|
||
### Rev 5 challenge rulings (binding on Tasks 10-13; 3 lenses, 2026-11-15)
|
||
- T10: keep the overlay geometry (`absolute inset-x-0 top-full`, no measuring) as a vertical `flex-col` list, rows ≥ 48 px,
|
||
accent tint + check icon + `aria-current`; motion unchanged in kind (light fade/slide, none under reduced motion). No
|
||
arrow-key navigation (Tab moves, Tab-out closes). `initialTab` drops its tier parameter. e2e locates « Plus » without an
|
||
exact name (it may carry the error count); checks at 320 and 375 (each entry box inside the viewport).
|
||
- T11: CitationsDialog = `Dialog layer` around CitationsPanel's body (keeps `data-place="citations"`, heading id
|
||
`editor-citations-title`, path, « Tout afficher », tiles with `readOnly` for edit actions, MissingRow, focus rescue);
|
||
CitationsSheet goes. `isFindingNode` widened to categories and nodes and renamed in place (`isCitable`). FindingEditCitations
|
||
and CitationList (with its remove path) MOVE to the dialog's edit mode (Task 12), not deleted. citationDraft.ts goes. If a
|
||
dirty finding form below refuses « Aller à » / « Tout afficher », the clean citations layer closes first so the question
|
||
is visible. Support helpers updated (`openTab` split, `findingDialog`, `showCitations`, `closeCitations`), sheet
|
||
geometry checks → dialog-in-viewport.
|
||
- T12: edit form keyed by `JSON.stringify(citedBy)`. Draft held as adds and removes, applied to the element's CURRENT
|
||
list at save (a reload never overwrites citations silently). Reuse useItemMode/useFocusEditButton (button id param),
|
||
keys `editor.findings.saved`, `editor.findings.reference_add`. Read-only flip: the draft stays, every control disabled,
|
||
only « Abandonner » (BDR-115). « Nouvelle référence »: the new id reaches the draft through a callback the open edit form
|
||
registers on the navigation (only for a creation it started); `added` is not set on that path; a `{create}` over the
|
||
citations layer is never read back from history (POP/reload drop it). A reference created then a draft abandoned stays
|
||
in the library uncited (its own undo step): tested and documented. Guard sites: `LAYERS` = finding, citations,
|
||
reference; `LAYERS_TOP_DOWN` (leftDraft.ts) derived from LAYERS; `leavingLayers` gets a citations condition (flag drops
|
||
or cited key changes); `closeCitations` asks the citations guard (user close refusable); `askLeave` clearAbove and
|
||
`refusePop` close only the layers above the refusing one (citations → reference). Tests: Back closing only the
|
||
citations dialog with a draft asks; topDirtyLayer order; citations under a clean reference dialog in POP and cascade;
|
||
jump-out cascade e2e (editor-leave-confirm) with dirty citations; sign-out flag for a citations draft.
|
||
- T13: also the CLAUDE.md folder-map line for the citations sheet.
|
||
|
||
## Rev 6: owner pre-closure adjustments 2026-11-15 (four items, autonomous mandate on the technique)
|
||
|
||
Owner brief 2026-11-15 « Avant la clôture définitive de R2 »: (1) a « Citer » button: the arrow keys only browse the
|
||
references, a citation joins the draft only on an explicit action; (2) a reference created from the references
|
||
dialog's edit mode is abandoned with the draft; an independent creation from the Références tab stays; (3) labels
|
||
follow the context (constat / famille), FR and EN; (4) the modal ✕ gets a 44 × 44 px touch area, harmonised in the
|
||
shared component. BLK-015 stays separate; the full sweep still fails and is never announced green.
|
||
Controller rulings (autonomous mandate, reported to the owner):
|
||
- A pending choice in the select is not part of the draft (no « Abandonner ? » for a choice never cited).
|
||
- Creation from the edit mode is deferred: the new reference lives in the draft and is written with the citations
|
||
by « Enregistrer », as ONE undoable operation (`commitBatch`: the inserts, then the element's update; no Rust
|
||
change). Abandon, Annuler, close, Back or leave drop it with the rest of the draft (asked first when dirty).
|
||
- « Modifier la référence » on an EXISTING reference keeps saving by its own dialog (a library change seen by every
|
||
citer, own undo step): stated to the owner as a choice, with the alternative (fold it into the draft).
|
||
- A reference still pending in the draft can be modified (same dialog, prefilled, nothing written) or removed
|
||
(« Retirer » drops it entirely).
|
||
|
||
### Task 14: « Citer » button, context labels, 44 px close (owner items 1, 3, 4)
|
||
- CitationsDraftList AddRow: the select (label « Citer une référence existante ») holds a local choice only (not in
|
||
the draft, not dirty); a « Citer » button (new key `editor.citations.cite`, fr « Citer », en « Cite ») beside it,
|
||
disabled while nothing is chosen; its click cites the choice, resets the select to the placeholder and puts the
|
||
focus back on the select. A choice no longer offered (cited, gone after an undo) resets to the placeholder. Arrow
|
||
keys and a pick on the select never change the draft. Read-only: select and « Citer » hidden (as the select today).
|
||
- Context labels: every label of the references dialog and of the filtered Références tab that names the cited
|
||
element gets a family variant chosen from the element's kind (`buildItems` kind / CiterItem.isFamily rule, one
|
||
helper): `editor.references.dialog_title`, `editor.citations.edit_title`, `editor.references.panel_count_one/other`,
|
||
`editor.references.panel_empty`, `editor.references.this_finding`, `editor.references.filter_chip`,
|
||
`editor.references.filter_remove`, `editor.references.filter_back`, `editor.references.filter_gone`. New keys
|
||
`<key>_family` (fr « Références de la famille », « Modifier les références de la famille », « … citée(s) par cette
|
||
famille », « Cette famille ne cite aucune référence. », « cette famille », « Références de la famille : {name} »,
|
||
« Retirer le filtre de la famille {name} », « Revenir à la famille », « La famille n'existe plus : le filtre est
|
||
retiré »; en the same with « family »). Finding wording unchanged.
|
||
- Dialog (components/ui/Dialog.tsx) close button: 44 × 44 px box (`grid h-11 w-11 place-items-center rounded-lg`,
|
||
visible focus ring), the same as MobileDrawer's close; header padding adjusted so the header does not grow more
|
||
than needed. Every Dialog of the app inherits it.
|
||
- Tests: unit (arrow/change on the select leaves the draft clean; « Citer » adds once and resets; disabled with no
|
||
choice; family vs finding titles, empty text, chip; ✕ box classes); e2e (keyboard: ArrowDown on the select then
|
||
close asks nothing, « Citer » then « Enregistrer » = one Défaire; ✕ bounding box ≥ 44 × 44 at 375 and 1280 in an
|
||
editor dialog and in the ui Dialog harness; axe).
|
||
|
||
### Task 15: a creation from the edit mode belongs to the draft (owner item 2)
|
||
- `citationEdits.ts`: the draft gains `created: readonly Reference[]` (references made in this draft, absent from the
|
||
document). Removing a created id drops it from `created` and `added`. `sameEdits` covers it.
|
||
- Reference dialog over the citations edit mode: a « draft » creation. `ReferenceMoves.start(opener, cite, initial?)`;
|
||
`cite` now receives the reference VALUE. In that mode ReferenceForm writes nothing: its save validates as today,
|
||
builds the value under a fresh id (`newElementId('ref')`, or the pending id when modifying a pending one), hands it
|
||
back, and the layer closes (forced, no replace, no library « added » notice, `held.cite` cleared). Submit label:
|
||
« Ajouter la référence » for a new one, « Valider » (new key `editor.reference.apply`, en « Apply ») when modifying a
|
||
pending one; title « Nouvelle référence » in both. An announcement says the reference is cited in the draft and
|
||
will be written with the citations (new key `editor.citations.created_draft`, `{citation}`).
|
||
- Draft list: a created reference shows its citation with a « Nouvelle » badge (new key `editor.citations.pending`),
|
||
« Modifier la référence » (draft mode, prefilled) and « Retirer ».
|
||
- Save: one `commitBatch` = an `insert` per created reference still cited, then the element's `update` with the
|
||
applied ids. `useEditCommand` gains `runBatch(field, build)` that regenerates the created ids once on
|
||
`duplicate_key` (as `runNew`), remapping them in the update. One Défaire undoes both the citations and the new
|
||
references; Refaire restores both.
|
||
- Everything else of the Rev 5 rules holds (guard layer `citations`, read-only flip keeps the draft, `{create}` over
|
||
citations never read back from history, focus).
|
||
- Tests: unit (create in draft → nothing in the document; save → references and citations in one undo step; abandon →
|
||
document unchanged; modify pending; remove pending; duplicate id retried; References tab « Ajouter » still writes at
|
||
once); e2e (owner path: « Nouvelle référence », « Abandonner » → library unchanged; « Nouvelle référence »,
|
||
« Enregistrer », one « Défaire » removes both).
|
||
|
||
### Task 16: docs
|
||
- V1-2-6_U1_CORRECTIONS §R2 (« Pre-closure adjustments 2026-11-15 »), V1-2-6_OWNER_TRIAL (limit 10 lifted, ✕ and arrow
|
||
limits lifted, §4.14 short manual checks), V1-2-6_R2_LABELS (new keys, totals), BROWSER_TESTS clauses.
|
||
|
||
### Rev 6 challenge rulings (binding on Tasks 14-16; 3 lenses, 2026-11-15)
|
||
- Family rule: one key helper `isFamilyKey(key) = key.kind === 'finding' && key.path.length === 1`, beside `isCitable`
|
||
(works for a vanished element). Sites: CitationsDialog titles (view, edit), CitationsPanel summary and empty line,
|
||
NoResult (new prop for the filtered element), CitersList (the current family row shows « cette famille » only, no
|
||
second « famille » badge), ReferenceToolbar chip / remove / back, useReferenceLibrary `filter_gone`, and
|
||
`editor.findings.gone` (family variant when a family's dialog closes because it vanished). Plural keys
|
||
`editor.references.panel_count_family_one/_other` through the unchanged plural helper; other keys `<key>_family`.
|
||
Unit: a filtered family removed by an undo announces the family variant.
|
||
- T14 ✕: `shrink-0` on the button, `min-w-0 break-words` and a gap on the h2; e2e measures the ✕ (≥ 44 × 44) at 320,
|
||
375 and 1280 with a long title (ui harness long-title case and one editor dialog with a long finding name).
|
||
- T14 select: the shown value is derived at render (`options.some(o => o.value === choice) ? choice : ''`), driving
|
||
the select and « Citer » (no effect). The choice state lives in the edit form (needed at save). « Citer » is
|
||
`type="button"`; its unit asserts the dialog stays in edit mode. « Enregistrer » with a chosen-but-not-cited
|
||
reference refuses: stays in edit mode, a line at the select (new key `editor.citations.pending_choice`, fr « Référence
|
||
choisie mais pas encore citée : choisissez « Citer » ou revenez au choix vide. »), focus on « Citer ». Closing with
|
||
only a choice asks nothing (no draft change).
|
||
- T15 channel: `ReferenceMoves`/`ReferenceLayer` get `drafting(): { initial: Reference | null, cite } | null` read
|
||
from `held` (never NavigationState, never history; `initial` cleared at every site that clears `cite`; draft mode
|
||
decided by `cite !== null` alone). ReferenceForm gets one optional `onValue(value)` that replaces `useWrite`, behind
|
||
the same once-only latch (double submit = one pending row, tested). Pending edit: ReferenceForm `reference` = the
|
||
pending value (prefill, id kept), title `editor.reference.new`, submit `common.confirm` (« Valider »); a new one keeps
|
||
`editor.reference.add`. No `editor.reference.apply` key.
|
||
- T15 validation: the draft-mode submit dry-runs the insert on the current document text with the pure `applyEdit`
|
||
(core/editOps.ts, nothing stored) and shows any refusal in the reference form as today. If the batch is refused at
|
||
« Enregistrer » anyway, the line names the pending reference.
|
||
- T15 notices: the draft-creation notice (`editor.citations.created_draft`) and a removed pending reference
|
||
(`editor.citations.pending_removed`, « Nouvelle référence retirée : {citation} ») go to the citations dialog's own
|
||
`role="status"` line, never `layer.announce`. Test: after an abandon and closing both dialogs, the live region holds
|
||
no « sera enregistrée ».
|
||
- T15 draft: one pure helper in citationEdits.ts adds or replaces a created value and its id together (one `set`).
|
||
`useEditCommand.runBatch(field, build: () => readonly EditCommand[])` calls `build()` once more on `duplicate_key`;
|
||
the citations save's `build` mints the created ids and maps them; no « still cited » filter (removeId keeps the
|
||
invariant). Save with the element unreadable (`!item`) is a refusal on the save line that keeps the draft, never the
|
||
pristine path. Dead Rev 5 write-and-cite path removed (`useCreated` citing branch, `CiteCreated` retyped to the
|
||
value, comments): `created()` is library-only again.
|
||
- Tests to update, named: e2e editor-citations.spec.ts:274-282 (`panel_empty` on « Dysfonction A », a family → family
|
||
text), :441-443 (cite through selectOption → choose + « Citer »); unit editor-citations-edit.test.tsx:185-189 (`cite`
|
||
helper), :416-440 and :442-459 inverted (CLARIFICATIONS 2026-11-15 b); editor-citations-guards.test.tsx:158-203
|
||
(cite through `created()` → the draft path).
|
||
- T16: document the durability change (a pending reference lives only in the open form until « Enregistrer »,
|
||
protected by the leave guards and beforeunload, no recovery copy), next to the other draft limits.
|
||
|
||
## Closure 2026-11-15
|
||
Owner validated R2 after the §4.13 and §4.14 db:trial checks; both offered choices ratified as built. Plan complete; no further task.
|