Files
faunosteo/.claude/tasks/plans/2026-11-13-r2-ux-finish-1624.md

495 lines
46 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.