Files
faunosteo/.claude/tasks/plans/2026-11-12-r2-references-tab-1730.md
T

21 KiB
Raw Blame History

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 through useEditCommand → 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>; NEVER editor-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) AND anatomical_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 through pnpm 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 EditorTarget variant. It opens only through the action open_citations(citedBy, opener) (renamed open_references, citedBy required). Its DOM place name is citations (data-place, PlaceName member only for its heading and focus scope). R2.1 removes the panel target from EditorTarget, placeOf, placeKey, moveText and 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 via focusActiveTab() (« 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, no tabIndex=-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/react AnimatePresence, enter 180 ms decelerate, exit 140 ms accelerate, translateX only, scrim opacity same timings; useReducedMotion → no transition); onExitComplete lifts the page inert, keeps ReferencesOpenContext true until then, and applies the pending move. The panel is inert during exit and unmounted after. Focus helpers report « found » only when document.activeElement is 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 (never hidden: sticky must keep working) and NO open-state min-h toggle; the panel wrapper is absolute inset-y-0 right-0 w-[min(34rem,100%)], the panel inner sticky 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 uses preventScroll and 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 add editor.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; citationCounts derived 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 into ReferencesTab at R2.4; only ReferenceTile is shared.
  • P26 [C9] links: editor/references/safeLink.ts (http / https only; DOI → https://doi.org/<encoded doi>); target="_blank" rel="noopener noreferrer"; the catalogue's safeHref is 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.ts five tabs; SHOWN.small unchanged (« Plus » = general, findings, references); REFERENCES_BUTTON_ID removed. EditorTabs.tsx row may wrap (P11).
  • components/editor/tabs/ReferencesTab.tsx in EditorTabBody BODIES; h2 « Références » with data-place-heading; hosts ReferenceLibrary (list of the current cards, form, DeleteDialog, search), ids tab- (P14).
  • navigation.ts: reference keys → {place:'tab', tab:'references', key}; panel EditorTarget removed (P1); open_citations(citedBy, opener); show_all_references (P4); select_tab closes the panel (P21); pending move plumbing (P9) introduced here with the current (non-animated) panel so focus rules hold from R2.1.
  • verification.ts reference issues → tab; useEditorNavigation.ts landing 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); TABS five; each existing openReferences call mapped explicitly (R-24 table in the commit body) to openTab(…,'references') (library) or openCitations(page, dict, element) (panel), keeping today's narrow-width panel axe and overflow checks through openCitations at 320 / 375 / 768 / 800 px; warm-up.ts uses 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 body dl Type / DOI / URL via safeLink (P26) else « Aucun » / « Aucune »; « Citée {n} fois, par : » list from citersOf (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.ts sortReferenceIds pure (sheet / citation with Intl.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); ReferenceLibrary folded into ReferencesTab (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; ReferencesOpenContext until exit; read-only: no Modifier / Retirer.
  • E2E [C11][R7]: e2e/shell/editor-citations.spec.ts in THIS sub-lot: desktop + 375 px (full-width panel via « Plus » → Constats): open, filtered, Retirer + Défaire, Tout afficher, each close path with document.activeElement checked after exit, Escape (A5), inert during exit (keyboard cannot reach the page), reduced motion (emulateMedia), axe open (edit and read-only). Widths / shift only in editor-shell-layout.spec.ts [S6]: 1 024, 1 180, 1 279, 1 280 + 375, panel ≤ 34 rem and ≤ viewport, documentElement.scrollWidth / scrollHeight sampled 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.md Part II §II.2 rows (class C, phase n/a) for editor/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.md R2 db:trial protocol; CLAUDE.md tree.
  • 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(): boolean with 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 / editingId pruned of ids absent from the document on each render.
  • P27 [R2-5] Panel and workspace Escape handlers ignore isTextField(target) and isComposing (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 if onExitComplete has not fired.
  • P9' [C2-3] onExitComplete only sets state (exiting=false + pending move); focus is applied by the existing useMoveFocus effect after that commit (never inside the callback).
  • P16' [R2-8][C2-4][C2-5] overflow-x: clip on 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/react useReducedMotion (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 DOI 10.1892/0891-6640(2002)016<0697:toih>2.3.co;2.
  • P6' [R2-11] Trigger re-found by comparing dataset values, 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 the inert attribute, not a racing key press.
  • E3 [C2-10] R2.1 interim panel: its add form and search are dropped; gone wired to the P6 close path; onShowAll only 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.ts except editor-equine.spec.ts, written out in full in the command.