Files
faunosteo/docs/development/V1-2-6_U1_CORRECTIONS.md
T

187 lines
20 KiB
Markdown

# V1-2.6 U1 corrections after the owner's first trial
Status: PROPOSAL, 2026-11-09. Owner brief « V1-2.6 UX — Arbitrages du premier essai propriétaire » (2026-11-09),
answering the trial diagnosis of the same day. Design, documentation and plan only: nothing here authorises code.
Lot R0 (boards) is delivered in `docs/design/v1-2-6-r0/` and awaits the owner's graphic validation; R1 to R4 start
only on their own explicit authorisation. Contract: `.claude/tasks/contracts/2026-11-09-v1-2-6-trial-arbitrations.md`.
Companion: `TRIAL_STACK.md` (the dedicated manual trial stack, request §5).
## 1. Owner decisions (2026-11-09)
| # | Decision |
|---|---|
| D1 | A fifth main tab « Références » between Constats and Vérification becomes the main access to the reference library. The header « Références » button is removed. |
| D2 | A contextual panel stays, opened from a finding's detail, filtered on its citations, with « Tout afficher » leading to the tab. About 34 rem wide within the available space, a lateral slide of 150 to 200 ms, `prefers-reduced-motion` honoured. |
| D3 | The tab shows collapsible tiles: closed = short citation, type, citation count; open = full information, DOI, URL, actions. Instant search with a clear button. Sort by document order (default), A to Z, citation count or type. Sorting never changes the document; reorder commands only while document order is shown. |
| D4 | Kept: unsaved changes, focus, « Aller à », permissions, read-only mode, accessibility tests. Below 640 px, Références goes in the « Plus » menu. Boards validated before any UI code. |
| D5 | History reads « Défaire » / « Refaire » instead of « Annuler » / « Rétablir », with explicit accessible names, the keyboard shortcuts kept and the distinction from dialog « Annuler » buttons kept. |
| D6 | A « Désélectionner » button near « Supprimer ». Escape deselects when no dialog, priority panel, menu or tracing in progress consumes it. Deselecting is interface state: no document change, no history entry. A click on an empty part of the drawing is left to U2. |
| D7 | Sheet list: instant search with clear, sort by last modification (default) or name, the last-modification date visible, better Administration home cards. No section built on UUIDs, names, slugs or test conventions; generic for every species; no artificial test filter. |
| D8 | A dedicated, persistent manual trial stack, separate from the automated sandbox: technical plan only, nothing created, reset or deleted now (`TRIAL_STACK.md`). |
| D9 | Three separate test anomalies tracked apart from U1 and U2: A fictitious fingerprints, B working copy never archived by `sheets-admin.sandbox.ts`, C integrity failure invisible in catalogue cards (section 5). |
| D10 | Lots R0 (boards), R1 (history labels, deselect), R2 (References tab), R3 (sheet list), R4 (catalogue integrity warning, independent fix). Any SQL schema or Rust core change needs its own checkpoint. |
## 2. What these decisions supersede
| Earlier validated item | Where | New state |
|---|---|---|
| U1 AC1: « no … « Références » … tab remains » | U1 contract `.claude/tasks/contracts/2026-11-06-v1-2-6-ux-u1-1123.md:373-375` | Five tabs (D1). |
| U1 AC3: panel opened from the header button and from a finding; focus back to the opener, else the header button | same contract :381-389 | Opened from a finding only; focus back to the finding's « n référence(s) » button. Scrim, `inert` tab panels, Escape / ✕ / scrim close and read-only behaviour unchanged. |
| U1 AC4 and T15 (history part): visible « Annuler » / « Rétablir », name « Annuler la dernière modification » | contract :390-397, `V1-2-6_UX_DECISIONS.md:309-322` | « Défaire » / « Refaire » (D5). T15's form wording (« Abandonner », « Abandonner les modifications ») unchanged. |
| U1 AC10: no horizontal scroll with the references panel open | contract :420-421 | Kept, re-checked with the 34 rem panel. |
| U1 AC12, AC13: « Aller à » a reference opens the side panel | contract :425-431 | « Aller à » a reference opens the Références tab, the tile open and focused. |
| U1 AC17: panel tests « open from header and finding »; keyboard order with the panel | contract :439-446 | Tests rewritten for the tab and the finding-only panel; the panel keeps its place in the keyboard order when open. |
| Checkpoint choice 5: Général and Constats under « Plus » below 640 px | `V1-2-6_UX_U1_CHECKPOINT.md:24` | Général, Constats and Références under « Plus ». |
| Checkpoint choice 10: search on citation, DOI and URL; ↑/↓ only on the unfiltered list | same file :29 | Carried to the tab: same search fields; reorder only in document order and without an active search. |
| Checkpoint choice 15: « Références » announced as a panel | same file :34 | Announced as a tab, like the four others. |
| Board 11 (references side panel as the main access) | `docs/design/v1-2-6/11-constats-references-desktop.png` | Replaced by boards 23 to 27 once validated. |
| BDR-099 item 5 (collapsible references rejected) | memory | Not contradicted: it concerned the catalogue page on a phone (`docs/design/README.md`, accepted deviation 2), not the editor. |
| U2b F5 (filter panel in the references panel's slot) | `V1-2-6_UX_FINDINGS_NAV.md:104-126` | Unaffected: the panel slot stays, used by the contextual references panel now and by the filter panel in U2b. |
## 3. Lots
Every lot: one commit or more per coherent change, pushed; gates in this order: `pnpm typecheck`, `pnpm lint`,
`pnpm test:run`, `pnpm build`, `pnpm e2e:ui`, then the shell suite on the sandbox as it stands, with its exact result
(the suite is not green today: four `admin.spec.ts:717` failures from the taken working-copy slot, anomaly B). Every
removed or rewritten assertion is mapped to its replacement in the commit message (R-24). Design gates: the boards of
R0 as validated, `impeccable detect` on the changed components, a fresh design review before the lot closes.
### R0 — Boards and owner validation (this delivery)
Boards 23 to 30 in `docs/design/v1-2-6-r0/` (sources, data generated from the equine draft, `REVUE.md`). Exit: the
owner validates each board, or asks for corrections; the validated boards then join `docs/design/README.md` as the
reference of R1 to R4.
### R1 — History labels and deselection (D5, D6)
- Labels: `editor.history.*` keys in `apps/app/src/i18n/fr.ts` and `en.ts` (FR « Défaire » / « Refaire », names
« Défaire la dernière modification » and « Refaire la dernière modification défaite »; EN « Undo » / « Redo »
unchanged); `HistoryButtons.tsx` keeps its structure. Shortcuts unchanged: Ctrl/⌘+Z undo, Ctrl/⌘+Maj+Z redo
(`apps/app/src/editor/useUndoShortcuts.ts:19-23`). Every prose string that names the history « Annuler » is
reworded; dialog « Annuler » buttons untouched.
- « Désélectionner »: a secondary button beside « Supprimer » (`PropertiesPanel.tsx:257-284`), shown while an
annotation is selected, in read-only modes too (selection is interface state); it dispatches the existing
« no selection » path that « Toutes les annotations » uses (`PropertiesPanel.tsx:93-108`).
- Escape: today a tracing consumes it when the canvas box has focus (`usePlacement.ts:82`), the references panel
when not already handled (`ReferencesPanel.tsx:234`), dialogs natively (`ModalDialog.tsx:111`). One handler on the
workspace, at the bubbling phase, deselects only when `event.defaultPrevented` is false, no dialog is open, no menu
is open and no tracing runs; each consumer marks the key handled. The « Plus » menu's own Escape path is checked
first (it has no explicit handler today).
- Unit tests: deselect leaves the document text and the history length unchanged; undo after a deselect undoes the
previous edit; the Escape matrix (dialog, menu, panel, tracing, nothing open) with one consumer each time; focus
after « Désélectionner »: the annotation's list row if it still exists, else the drawing, with no new selection
and a polite announcement (A6 as ratified); accessible names of both history buttons in FR and EN; read-only modes
show « Désélectionner » and no « Supprimer ».
- E2E: the journeys that name « Annuler » / « Rétablir » rewritten one for one; a new desktop spec for the button and
Escape; axe on Annotations with a selection.
### R2 — The Références tab (D1 to D4)
- Tab model: `EDITOR_TABS` gains `references` between `findings` and `verification` (`apps/app/src/editor/tabs.ts:6-11`),
`SHOWN.small` keeps it under « Plus » (:18). The id collides with the panel's `data-place` name `references`: the
panel place is renamed first (internal name, no visible effect). Touched with it: `navigation.ts` `targetOfKey`
(:65-81, reference keys go to the tab), `focusRequest.ts:19-22`, `useEditorNavigation.ts`, `EditorTabBody.tsx:16-23`,
`EditorWorkspace.tsx:85-131`, `verification.ts`, i18n keys.
- Tab content: tiles built from `ReferenceRow` / `ReferenceForm` (`components/editor/references/`), a disclosure
button per tile (`aria-expanded`, `aria-controls`), the toolbar with a search field and its explicit clear button
(focus back to the field), a native `<select>` with its external « Trier par » label. Tile count reads « Citée N
fois » (citations from families and findings, as `citations.ts` counts them); the open tile names a family as a family.
A cited reference shows no « Supprimer » (the core refuses it): a hint explains how to delete it once each citation
is removed (« Aller à », then « Retirer » in the finding's or family's detail); an uncited reference keeps « Supprimer » (owner verdict,
board 23).
« Ajouter une référence » appends in document order, resets search and sort, opens the new tile in edit with focus
on its citation field. Sorting is a pure function over the reference ids that never
touches the document: document order; citation A to Z with `Intl.Collator` of the current language; citation count
descending, ties in document order; type in the order of the type list, ties in document order. Search keeps
`filter.ts` (citation, DOI, URL, `folded`).
- Panel: opened only from a finding (`EditorWorkspace.tsx:94` width becomes `min(34rem, 100%)`), slide from the right
in 150 to 200 ms with a shorter exit, no slide under `prefers-reduced-motion` (Tailwind `motion-reduce:`); the panel
stays mounted during its exit and the page stays `inert` until the exit ends (LRN-085); no permanent `will-change`
(LRN-045). The header button and its focus fallback are removed (`HeaderActions.tsx`, `REFERENCES_BUTTON_ID` in
`tabs.ts:57`).
- Unit tests (about 15 files today assert the four-tab structure or the panel): five tabs and the « Plus » tier at
500 px; each sort, stable, document untouched (text compared before and after); reorder commands present only in
document order without search; clear button; tile disclosure and focus; « Aller à » from Vérification opens the
tab, the tile open and focused; « Aller à » from a tile reaches the finding; a cited tile has no « Supprimer » and
shows the hint, an uncited tile keeps it; the panel from a finding: filtered, « Retirer de ce constat » removes only
that citation (the reference stays in the document) and one undo restores it, « Tout afficher » opens the tab with search and sort reset and focus on its heading, close returns focus to the
finding's button; unsaved edits in a tile form survive a tab change (kept-mounted places); no edit control in any
read-only mode or without the editor right; the reduced-motion class.
- E2E: `TABS` helper (`e2e/support/editor.ts:327`) to five; `editor-shell-journeys.spec.ts:116-125` count 4 to 5;
layout specs with the panel open at 1 024, 1 180, 1 279, 1 280 px (no horizontal scroll); 375 px « Plus »;
axe on the tab (tiles closed and open) and on the panel; keyboard walk of the new order; about 28 panel open/close
calls rewritten.
### R3 — Sheet list and Administration home (D7)
- `AdminSheetsRoute.tsx`: search on the sheet name in both languages (`folded`, accents ignored) with a clear
button, a « Trier par » select (last modification descending by default, name A to Z by `Intl.Collator`), the
result count, the date on each row; the four filters unchanged (`apps/app/src/admin/filters.ts`).
- `AdminHomeRoute.tsx` « Fiches officielles » card (`CARD_SHEETS = 5`, :25): the five most recently modified sheets
with species, status and date, and « Voir les N fiches ».
- Date source (arbitration A7): the list payload carries `anatomical_sheets.updated_at`
(`supabase/migrations/20261102100000_sheet_admin_reads.sql:54`), which a draft save does not move:
`save_sheet_draft` writes `anatomical_sheet_versions` only (`20261028110000_sheet_review_workflow.sql:569-630`). On
the sandbox, 28 of 219 official sheets have a version newer than the sheet row. A true « dernière modification »
needs one read change in SQL (a `last_modified_at` field, greatest of the sheet's and its versions' `updated_at`,
in `private.official_sheet_admin_summary`; no table, policy or privilege change), hence an SQL checkpoint, pgTAP,
regenerated types, and its application to a stack, which needs the owner's go for that operation. Ratified (A7):
the dedicated checkpoint is `V1-2-6_R3_SQL_CHECKPOINT.md`; R3 ships in two steps, search and name sort with no date
first, the date, the date sort and the « most recent » card only once the SQL change is authorised and applied.
- Search and sort run in the browser on the full list: `shortcut:` until RR-13 pages the list on the server, where
search and sort move with it.
- Tests: unit for search (accents, both languages, empty, clear), sort (date ties by name, collation), date format
FR/EN, the home card (at most five, sorted); e2e admin list search and sort at desktop and 375 px with axe; the four
filters unchanged.
### R4 — Integrity warning in catalogue cards (D9 C, independent fix)
- The card already runs the integrity check: `useCardDetails` calls `loadVersion` and drops a failed load in
silence (`apps/app/src/catalogue/useCardDetails.ts`, `if (!load.ok) return`). R4 keeps the failure kind in the
card's state and shows a warning inside the card; the sheet page's `CatalogueFailureNotice` is unchanged. No SQL,
no Rust: the check stays the core's `check_published`, never bypassed.
- Tests: unit for a card whose load fails with `fingerprint_mismatch` (warning shown, link kept) and with a transport
failure (its own line and « Réessayer », arbitration A10); e2e on a catalogue entry whose stored fingerprint differs, built by
the test itself (never by editing an existing sheet); axe on the list.
- Its own commit and verification, kept out of the U1 shell lots.
## 4. Order and dependencies
R0 first (validation). R1 is independent of R2 and can ship first. R2 depends on the validated boards 23 to 27. R3
ships search and name sort first; its date part waits for the SQL checkpoint (A7 ratified).
R4 is independent and may run any time after its board (30) is validated. Anomaly B (section 5) should land before
the gates of R2 and R3 are read, since its taken slot fails four admin specs on every run.
## 5. Test anomalies tracked apart (D9)
| Item | Cause | Constraint |
|---|---|---|
| A. Fictitious fingerprints | Worker stand-ins publish with `'a'.repeat(64)`: `packages/supabase/tests/sandbox/sheet-fixtures.ts:115` (`openRound`), `sheets-concurrency.sandbox.ts:168`, `sheets-perf.sandbox.ts:169`. Seven published or deprecated versions on the sandbox fail `check_published`; the owner opened three of them on 2026-11-09. | Compute the real fingerprint through the core as the catalogue e2e does (`fingerprintOf`), never weaken the publish gate or the reader's check. |
| B. Working copy never archived | `packages/supabase/tests/sandbox/sheets-admin.sandbox.ts:181-195` creates the historical sheet's working copy (`8c315a12-…`, 2026-11-08 21:00:30) and never archives it; the single slot then disables « Créer une copie de travail » (`WorkingCopyAction.tsx:88`) and fails `admin.spec.ts:717` four times. | Make the suite independent (its own cleanup, or a precondition it creates and removes); the existing copy is not touched before the owner authorises it. |
| C. Silent card failure | Section 3, R4. | Show the failure, never hide or route around it. |
## 6. Arbitrations
Status as of the brief « R0 — Décisions propriétaire et dernière validation graphique » (2026-11-09, BDR-108) and the
owner's graphic verdict « R0 — Verdict de revue graphique propriétaire » (2026-11-09, BDR-109): every arbitration is settled.
The owner-facing table with consequences, in French: `docs/design/v1-2-6-r0/ARBITRAGES.md`.
| # | Question | Recommendation | Status |
|---|---|---|---|
| A1 | Reorder commands with a search active in document order | Hidden, as checkpoint choice 10 already rules (moving among a hidden subset is ambiguous); one hint line. | RATIFIED 2026-11-09 (BDR-109), exact recommendation |
| A2 | Tiles open at once; how long open state, search and sort last | Several open at once; kept while the editor stays open (kept-mounted tab), reset when it reopens. | RATIFIED 2026-11-09 (BDR-109), exact recommendation |
| A3 | Actions in the contextual panel | « Modifier », « Retirer de ce constat », « Aller à »; no add, no reorder, no « Supprimer » (always refused by the core there). « Tout afficher » opens the tab with search and sort reset, focus on its heading. | RATIFIED: « Retirer de ce constat » removes only the finding's citation of the reference, never the reference; undoable through the editor history |
| A4 | Closed tile content | Citation on two lines at most, type, « Citée N fois » or « Non citée » (the count includes families). | RATIFIED 2026-11-09 (BDR-109), exact recommendation |
| A5 | Escape priority | Dialog, then open menu, then contextual panel, then tracing in progress, then selection. | RATIFIED 2026-11-09 (BDR-109), exact recommendation |
| A5b | « Toutes les annotations » already clears the selection | Keep both (D6). | RATIFIED 2026-11-09 (BDR-109), exact recommendation |
| A6 | Focus after « Désélectionner » | The annotation's row in the list. | RATIFIED with precision: the row if it still exists, else the drawing; focus never selects again; an accessible announcement |
| A7 | Source of the last-modification date | SQL read change `last_modified_at`, own checkpoint. | RATIFIED: dedicated SQL checkpoint `V1-2-6_R3_SQL_CHECKPOINT.md`; until then no creation date shown as a modification date and no misleading sort |
| A8 | Date format | Absolute, « 9 nov. 2026, 12:06 » (EN « 9 Nov 2026, 12:06 »). | RATIFIED 2026-11-09 (BDR-109), exact recommendation; shown only after the SQL checkpoint |
| A9 | Administration home card | The five most recently modified sheets with species, status and date, then « Voir les N fiches ». | RATIFIED 2026-11-09 (BDR-109), exact recommendation; final state after the SQL checkpoint |
| A10 | Catalogue warning wording | FR « Contrôle d'intégrité échoué : cette version ne peut pas être affichée. », a distinct line with « Réessayer » for a load that failed for another reason. | R4 ACCEPTED; wording RATIFIED 2026-11-09 (BDR-109), exact recommendation |
| A11 | Trial stack command | `pnpm db:trial`, prefix `faunosteo_trial_`, ports 58xxx and 5194. | RATIFIED 2026-11-09 (BDR-109), exact recommendation (name, prefix, ports) |
| A12 | Old `db:sandbox trial*` commands | Remove once the trial stack is validated. | DECIDED otherwise: kept for now, neither removed nor silently redirected |
| A13 | Trial accounts | `admin` with catalogue rights, `owner` if needed. | DECIDED 2026-11-09: two accounts; practitioner = technical `admin` + `sheet_editor`, no owner, reviewer or publisher; not a production practitioner profile; O1 unchanged |
| A14 | Key lifetime and secret renewal | One year, `rotate-keys`. | DECIDED 2026-11-09: one-year keys on the dedicated local stack, documented rotation, no secret in Git or logs, security review of the renewal |
| A15 | Backup before every `migrate` | Automatic, kept, never pruned without the owner. | RATIFIED 2026-11-09 (BDR-109), exact recommendation |