21 KiB
PLAN — R2 « Références » tab (V1-2.6) — rev 2
Contract: .claude/tasks/contracts/2026-11-12-r2-references-tab-1730.md. Sources: docs/development/V1-2-6_U1_CORRECTIONS.md
§R2 (D1-D4), docs/design/v1-2-6-r0/{ARBITRAGES.md A1-A5, REVUE.md, maquettes.html boards 23-27}, TODO R2 block
(a1d4084), BDR-114, BDR-107..110, BDR-113. Read-before digest: analyzer 2026-11-12.
Rev 2 = rev 1 + challenge round 1 (correctness FATAL(5), robustness FATAL(7), simplicity CONCERNS(1)); changes tagged
[Cn] / [Rn] / [Sn] with the finding number.
Plan form (deviation from writing-plans « full code », stated): ~30 files; each task gives files, behaviour, test cases and verification; executors write the code under TDD. Design = owner-validated boards (BDR-110), no brainstorm.
Global rules
- Limits: 25 logic lines / function, 100 chars, 5 params, 5 locals, no global state; i18n through
useT()with fr / en parity; edits only throughuseEditCommand→ store.commit (one history entry per action). - Never touch supabase/, crates/, scripts/db-trial*, docker/, packages/supabase/src, components/catalogue/ (reader unchanged) [C9]. No db:trial, no DEV.
- Shell runs:
pnpm db:sandbox e2e-shell <explicit spec list>; NEVEReditor-equine.spec.ts(owner §3). - Data guard [R6]: before and after each shell session, per-id snapshot of pre-existing rows of
anatomical_sheets(id, status, archived_at, updated_at) ANDanatomical_sheet_versions(id, status, the revision / updated_at columns, md5(content::text)); compared per id (changed or missing = stop); new rows counted and their sheet ids listed per run (owner §3 fixture tracking). Select-only throughpnpm db:sandbox sql. - Key removal [R10]: before removing any i18n key or helper, grep src, tests and e2e INCLUDING editor-equine; equine is reported « updated, not run ».
- R-24: every removed or rewritten assertion mapped in the sub-lot commit body.
- Design floor:
impeccable detect <changed .tsx>on R2.1-R2.4.
Decisions (owner answers marked [owner])
- P1 [S1] The panel is no navigation place: no
EditorTargetvariant. It opens only through the actionopen_citations(citedBy, opener)(renamedopen_references,citedByrequired). Its DOM place name iscitations(data-place, PlaceName member only for its heading and focus scope). R2.1 removes the panel target fromEditorTarget,placeOf,placeKey,moveTextand the panel's own focus-request handler. - P2 « Type » sort = REFERENCE_TYPES order, ties in sheet order.
- P3 « Aller à » a reference hidden by the tab search: clear the search only, open the tile, focus it (P8); other open tiles stay open (A2).
- P4 [C6] « Tout afficher dans l'onglet Références » = its own action
show_all_references: closes the panel, then (after exit, P9) selects the tab with a reset signal (search and sort reset, open tiles and a tile in edit kept), focus on the tab heading. Vérification's unresolved reference path selects the tab WITHOUT reset. - P5 [owner] family trigger → same panel, family words.
- P6 [C2][R2] focus fallbacks, in order: the trigger (re-found by
data-citations-trigger=<element key>) if shown → else the active tab button viafocusActiveTab()(« Plus » button below 640 px). Never a missing heading. - P7 panel: no search, add, delete, reorder (board 25).
- P8 [C8] focus target of a reference = the tile's disclosure button, carrying only
data-focus-key(natural tab stop, notabIndex=-1); the tile is opened first. - P9 [C1][R1][R8] Panel closing is uniform: every close (✕, Escape, scrim, « Tout afficher », « Aller à » from a panel
tile, element vanished, tab switch) records ONE pending move (target + focus) in the workspace; the panel animates out
(
motion/reactAnimatePresence, enter 180 ms decelerate, exit 140 ms accelerate, translateX only, scrim opacity same timings;useReducedMotion→ no transition);onExitCompletelifts the pageinert, keepsReferencesOpenContexttrue until then, and applies the pending move. The panel isinertduring exit and unmounted after. Focus helpers report « found » only whendocument.activeElementis the target. Page inert through exit is kept (approved CORRECTIONS §R2 text, owner « y compris pendant son animation de sortie »). - P10 editor-equine: helper calls updated, never run.
- P11 [owner] 640-1 023 px: five tabs, row may wrap, no horizontal scroll.
- P12 [R11] tab search: explicit Escape handler: non-empty query → clear +
preventDefault; empty → let it bubble (A5). - P13 trigger gains
aria-expanded+aria-controls="editor-citations-panel". - P14 tile ids prefixed by host (
tab-/panel-). - P15 [owner] « Retirer … » marks the element « À confirmer » (core rule); documented; one « Défaire » restores both.
- P16 [C4][C5][R5] Geometry: the Places container gets
overflow-x: clip(neverhidden: sticky must keep working) and NO open-statemin-htoggle; the panel wrapper isabsolute inset-y-0 right-0 w-[min(34rem,100%)], the panel innersticky top-14 h-full max-h-[calc(100dvh-3.5rem)]with its own scrolling list, so it never exceeds the container: document height and width never change on open / close / during motion. Heading focus on open usespreventScrolland happens after enter completes. - P17 labels table file:
docs/development/V1-2-6_R2_LABELS.md. - P18 [S4] count wording: reword
editor.references.cited_*in place to « Citée {n} fois » (capital) and addeditor.references.uncited« Non citée »; no parallel keys. - P19 [S3] one memoised
citersOf(doc): Map<refId, CiterItem[]>(families and nodes at any depth); tile count = list length;citationCountsderived from it (or removed with its last consumer). - P20 [C3][R2] After « Retirer … »: focus the next tile's disclosure button, else the previous, else the panel heading; zero citations left → the panel stays open with the line « Ce constat ne cite plus aucune référence. » / « Cette famille ne cite plus aucune référence. » (new provisional labels) + « Tout afficher »; close then follows P6 (the trigger is gone when its count is 0).
- P21 [C2][R2] Selecting a tab while the panel is open closes it (pending move = the tab; focus on the new tab button). Défaire / Refaire stay usable with the panel open; an undo that removes the element triggers P6.
- P22 [R3] Leaving edit is guarded: « Terminer », switching
editingId, « Ajouter » while another tile is in edit, and closing the panel with a tile in edit first commit the pending field; on refusal the tile stays in edit, the refused field shows its message and takes focus, and the leave is cancelled. - P23 [R4] Pinning: while
editingId(or the add draft) is set, that tile stays in the shown set at its current index whatever the sort or search, until it leaves edit. - P24 [C12] Add: « Ajouter une référence » resets search and sort, appends a draft tile in edit (Type « Choisir… », Citation focused); « Ajouter la référence » creates it in one modification; on success the tile stays open, leaves edit, focus on its disclosure button.
- P25 [S2]
ReferenceLibrary(R2.1 extraction) is folded intoReferencesTabat R2.4; onlyReferenceTileis shared. - P26 [C9] links:
editor/references/safeLink.ts(http / https only; DOI →https://doi.org/<encoded doi>);target="_blank" rel="noopener noreferrer"; the catalogue'ssafeHrefis not touched.
R2.0 — rename the panel's DOM place (no visible change) — refactor(editor): …
Scope [S1][C10]: the data-place / KeptPlace name="references" literal, the PlaceName member, headingOf,
ownedBy uses, DOM ids editor-references-panel / editor-references-title → editor-citations-*;
editor/annotations/deselect.ts only if it names the place; tests and e2e literals. Not renamed (deleted in R2.1): the
EditorTarget variant, MoveKinds.
E2E [S7]: library assertions routed through one helper (libraryRoot(page)) in e2e/support/editor.ts, so R2.1
changes one line; place(page,'citations') only at the true panel sites.
Proof [R9][C10]: grep -rnE "['\"]references['\"]" apps/app/src apps/app/tests apps/app/e2e reviewed hit by hit (each
remaining hit justified in the commit body), plus name="references" absent.
Gate: typecheck, lint, test:run, build; e2e:shell crossing, journeys, shell, structures, deselect, access,
shell-layout + data guard. Commit + push.
R2.1 — five tabs, navigation, library in the tab — feat(editor): …
tabs.tsfive tabs;SHOWN.smallunchanged (« Plus » = general, findings, references);REFERENCES_BUTTON_IDremoved.EditorTabs.tsxrow may wrap (P11).components/editor/tabs/ReferencesTab.tsxinEditorTabBodyBODIES; h2 « Références » withdata-place-heading; hostsReferenceLibrary(list of the current cards, form, DeleteDialog, search), idstab-(P14).navigation.ts: reference keys →{place:'tab', tab:'references', key}; panel EditorTarget removed (P1);open_citations(citedBy, opener);show_all_references(P4);select_tabcloses the panel (P21); pending move plumbing (P9) introduced here with the current (non-animated) panel so focus rules hold from R2.1.verification.tsreference issues → tab;useEditorNavigation.tslanding on the tab heading; fallbacks P6.- Header button, separator and props removed (HeaderActions, DraftHeader, EditorWorkspace).
- Trigger (FindingContent):
open_citations,data-citations-trigger,aria-expanded,aria-controls(P13). - i18n:
editor.tab.references; removals per [R10]. - E2E [C7][R7]: tier-aware
openTab(page, dict, tab)(opens « Plus » below 640 px);TABSfive; each existingopenReferencescall mapped explicitly (R-24 table in the commit body) toopenTab(…,'references')(library) oropenCitations(page, dict, element)(panel), keeping today's narrow-width panel axe and overflow checks throughopenCitationsat 320 / 375 / 768 / 800 px;warm-up.tsuses the tab (same commit). - Unit tests rewritten with R-24 mapping (editor-mode, editor-route, editor-references-panel → finding path only [S2], editor-tabs-lists, editor-navigation, editor-focus-request, editor-keep-alive, editor-escape (A5 panel layer through the trigger), editor-no-loss(-decisions), editor-route-recovery, editor-verification); new: select_tab closes panel, P6 fallbacks, Vérification « Aller à » reference → tab + focused row. Gate: typecheck, lint, test:run, build, e2e:ui, e2e:shell (editor-* except equine, admin, shell, journeys) + data guard; impeccable detect. Commit + push.
R2.2 — collapsible tiles — feat(editor): …
ReferenceTile.tsx(board 23 / 24 C / D / 27): header<button aria-expanded aria-controls>(≥ 44 px, P8), 2-line clamp, meta column (type badge, « Citée {n} fois » / « Non citée »), phone meta row; open bodydlType / DOI / URL viasafeLink(P26) else « Aucun » / « Aucune »; « Citée {n} fois, par : » list fromcitersOf(P19) with « famille » badge and « Aller à » (44 px) or the empty line; actions « Modifier »; « Supprimer » only uncited (existing DeleteDialog) else the hint; « Monter » / « Descendre » (R2.3 decides visibility).- Edit mode (24 D): title « Modifier la référence », Type | DOI, Citation textarea focused, « Adresse web (URL) », cited rows, only « Terminer » with the P22 guard; pinning P23.
- Tab state kept mounted (A2):
openIds,editingId; reset on editor reopen. - Read-only (24 C): no edit control; DOI, URL, « Aller à » kept.
- Unit: disclosure keyboard, several open, cited hint vs uncited Supprimer, edit hides actions, P22 refusals (schemeless
URL, blank citation) keep edit and focus the field, edit survives a tab change, read-only,
javascript:never a link, counts = list length including families, several findings citing one reference. - E2E: start
e2e/shell/editor-references.spec.ts(tiles closed / open / edit, read-only twin at 375 via « Plus », axe on closed / open / edit, keyboard walk through tile headers). Gate: as R2.1 + the new spec. Commit + push.
R2.3 — search, sort, count, add, reorder — feat(editor): …
editor/references/sort.tssortReferenceIdspure (sheet / citation withIntl.Collator(locale, {sensitivity:'base', numeric:true})/ count desc / type P2; ties in sheet order); new array, inputs untouched.- Toolbar (23 / 24 / 27 B): search + « Effacer la recherche » (focus back) + P12 Escape; « Trier par » external label + native select; count « {n} références » / « {n} références sur {total} »; « Ajouter une référence » (edit modes).
- No result (24 B): notice + « Effacer la recherche » button.
- A1 move buttons only in sheet order without search, else the hint line.
- Add P24; pinning P23; « Aller à » P3 / P8.
- Unit: each sort stable on a fixture (equal citations, accents, numbers, mixed types); document text + history length identical before / after every sort and search; clear button; no-result notice; A1 matrix; add flow; P23 (edit under citation sort and under search keeps the tile in place); Vérification « Aller à » hidden tile.
- E2E (editor-references.spec): four sorts visible order, search / clear / no result, A1, add, delete uncited, server document and revision unchanged after sorts / searches. Gate: as R2.2. Commit + push.
R2.4 — contextual panel — feat(editor): …
CitationsPanel.tsx(board 25): overlay geometry P16; header book icon + « Références citées » + ✕ 44×44 « Fermer les références »; path line; count line « {n} références citées par ce constat / cette famille » + « Tout afficher dans l'onglet Références » (P4); tiles (meta 132 px) with « Modifier », « Retirer de ce constat / cette famille » (P15, P20), « Aller à »; « ce constat / cette famille » badge; P7; zero state P20.- Motion and focus P9, P6, P21, P22 (close with a tile in edit);
ReferenceLibraryfolded intoReferencesTab(P25). - Unit: open only through the trigger; filtered; family words; Retirer removes only that id, reference stays, one undo
restores (and the review status); P20 focus chain and zero state; P4 reset + heading focus; every close path applies
its pending move after exit and the focused element is the expected one (activeElement); P21; P6 after undo; reduced
motion (no transition) vs normal; inert page and panel during exit;
ReferencesOpenContextuntil exit; read-only: no Modifier / Retirer. - E2E [C11][R7]:
e2e/shell/editor-citations.spec.tsin THIS sub-lot: desktop + 375 px (full-width panel via « Plus » → Constats): open, filtered, Retirer + Défaire, Tout afficher, each close path withdocument.activeElementchecked after exit, Escape (A5), inert during exit (keyboard cannot reach the page), reduced motion (emulateMedia), axe open (edit and read-only). Widths / shift only ineditor-shell-layout.spec.ts[S6]: 1 024, 1 180, 1 279, 1 280 + 375, panel ≤ 34 rem and ≤ viewport,documentElement.scrollWidth/scrollHeightsampled before, during (motion on) and after open and close [R5]. Gate: as R2.3 + citations spec + layout spec. Commit + push.
R2.5 — non-regression sweep — test(tests): … (only if changes are needed)
- Full gates on the final state: typecheck, lint, test:run, build, e2e:ui, e2e:shell ALL specs except
editor-equine.spec.ts(explicit list), the two new specs run twice; data guard; R-24 audit of the whole R2 diff (no assertion lost without a mapped replacement); gaps found here are fixed in this sub-lot.
R2.6 — docs, labels, closure — docs(…): …
docs/development/V1-2-6_R2_LABELS.md: every new / changed / removed key (key, FR, EN provisional, where, family variants, ambiguity notes).RUST_ARCHITECTURE_REVIEW.mdPart II §II.2 rows (class C, phase n/a) foreditor/references/{filter,citations,sort, safeLink}.ts+ §II.3 bullet (BDR-114 A).V1-2-6_U1_CORRECTIONS.md§R2 status (incl. P15 « À confirmer », P20, P21);BROWSER_TESTS.md(new specs, equine excluded);V1-2-6_OWNER_TRIAL.mdR2 db:trial protocol;CLAUDE.mdtree.- Then STEP 5 (fresh verifier on the enriched contract, security), STEP 6 code review (opus), doc sync, capitalize; stop at the checkpoint.
Verification per sub-lot
SDD per task (implementer sonnet + spec review + quality review) → sub-lot gate → commit + push; a red gate blocks the commit. Fresh verifier + security + code review on the whole of R2 at the end.
Risks kept
- Larger R-24 mapping load (13 unit files, 8 specs, warm-up) → per-commit tables.
- happy-dom cannot show layout, motion or inert focus loss → each is proven in Chromium in the same sub-lot.
- editor-equine updated but unverified until its separate fix.
Rev 3 — challenge round 2 (robustness FATAL(5), correctness CONCERNS(2)); these override rev 2 where they differ
- G1 [R2-1 BLOCKER] Shell commands use full paths only (
e2e/shell/<name>.spec.ts), never a bare token (shell,editor-match every file: Playwright args are regexes on the absolute path). Mandatory preflight before every run:pnpm db:sandbox e2e-shell --list <same args> | grep -q editor-equine && abort. Each gate below lists its exact files. - G2 Data guard queries run inside
begin transaction read only; … rollback;[R2-12]. - P22' [R2-2][C2-1] Leave guard covers EVERY edit field of the tile: fields expose their draft through a tile-level registry; leaving re-commits each field whose draft ≠ document value; any refusal blocks the leave and focuses that field. Unit: « A refused, then B committed OK, then Terminer » keeps edit.
- P22'' [R2-3][C2-2] The panel registers
canLeave(): booleanwith the workspace; every USER close (✕, Escape, scrim, Tout afficher, Aller à, tab click) calls it before recording the pending move; refusal cancels the whole close (tab not switched). FORCED closes (element vanished, read-only flip, conflict reload) proceed; a refused draft is dropped and announced in the live region (new provisional label « Saisie non appliquée : … »). - P23' [R2-4][R2-14] Pin only when sort ≠ sheet order or a search is active; in read-only the pin is suspended and the
tile renders read view; the add draft is kept in an EditOnly-style hidden container and resumes when editable;
openIds/editingIdpruned of ids absent from the document on each render. - P27 [R2-5] Panel and workspace Escape handlers ignore
isTextField(target)andisComposing(A5: a field keeps Escape); unit + e2e: Escape in a panel tile textarea neither closes nor commits. - P28 [R2-6][R2-7] During exit: a second close is a no-op; a tab select replaces the pending move; the pending focus is
skipped if the user moved focus off
body; a one-shot fallback timer (exit duration + 100 ms) lifts inert and applies the move ifonExitCompletehas not fired. - P9' [C2-3]
onExitCompleteonly sets state (exiting=false + pending move); focus is applied by the existinguseMoveFocuseffect after that commit (never inside the callback). - P16' [R2-8][C2-4][C2-5]
overflow-x: clipon the panel's absolute wrapper only (translateX on the inner panel); tab content keeps its focus rings. Places gets a PERMANENT (never toggled)min-h-[calc(100dvh-3.5rem)]so the panel and scrim reach the bottom as on board 25 and the document height never changes on open / close (shown at the gate). - P29 [C2-6] Reduced motion keeps the same AnimatePresence with zero-duration transitions (callbacks fire); focus on
open after enter completes in both modes. Deviation from the CORRECTIONS text (« Tailwind motion-reduce: » + « class »
test):
motion/reactuseReducedMotion(MobileDrawer precedent), shown at the gate. - P30 [R2-9] Dangling citation ids: the panel lists them as « Référence introuvable » rows with « Retirer » (new provisional label); trigger count, panel count and zero state use the same list.
- P31 [R2-10][C2-8] Tile UI state, DOM ids and focus keys use position + id (duplicates stay visible and distinct); sort works over positions.
- P26' [R2-13][C2-9] DOI link: strip a leading
doi:/https://doi.org//http://dx.doi.org/, link only^10\.\d{4,9}/\S+$, encode per segment keeping/; test with the seed DOI10.1892/0891-6640(2002)016<0697:toih>2.3.co;2. - P6' [R2-11] Trigger re-found by comparing
datasetvalues, never a raw attribute selector. - E1 [C2-7] e2e seeded shape gains one reference cited by one finding (counts in other specs checked); the two layout tests that opened the panel over the drawing are remapped: drawing box measured before open and after a P21 switch to Annotations (the panel no longer exists on Annotations).
- E2 [R2-15] Timing checks sampled in-page with a rAF loop started before the click (or
page.clock), asserting theinertattribute, not a racing key press. - E3 [C2-10] R2.1 interim panel: its add form and search are dropped;
gonewired to the P6 close path;onShowAllonly for « Tout afficher ».
Exact shell gate file lists (G1)
- R2.0: e2e/shell/editor-shell-crossing.spec.ts e2e/shell/editor-shell-journeys.spec.ts e2e/shell/editor-shell.spec.ts e2e/shell/editor-structures.spec.ts e2e/shell/editor-deselect.spec.ts e2e/shell/editor-access.spec.ts e2e/shell/editor-shell-layout.spec.ts
- R2.1-R2.4: the R2.0 list + e2e/shell/editor-annotations.spec.ts e2e/shell/editor-geometry.spec.ts e2e/shell/editor-journey.spec.ts e2e/shell/editor-recovery.spec.ts e2e/shell/editor-drawings.spec.ts e2e/shell/editor-signout.spec.ts e2e/shell/admin.spec.ts e2e/shell/shell.spec.ts + the new R2 specs as they land
- R2.5: every file of
ls e2e/shell/*.spec.tsexcept editor-equine.spec.ts, written out in full in the command.