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

24 KiB
Raw Permalink Blame History

CONTRACT — r2-ux-finish

  • date: 2026-11-13 | flow: ship-feature | branch: feature/v1-2-anatomical-sheets (worktree /home/bchanot/Documents/faunosteo-v1-2)
  • status: active

REQUEST (verbatim — IMMUTABLE)

J'ai terminé mon essai manuel de R2 sur db:trial.

Globalement, tout fonctionne et je suis satisfait du résultat. J'ai néanmoins plusieurs améliorations UX à apporter avant de clôturer R2.

Je te laisse autonome sur l'analyse, la conception technique, le découpage, les tests et l'implémentation. Tu connais le projet, ses contrats et son architecture. Utilise ton processus habituel de développement, de relecture et de validation.

L'objectif général est de rendre l'éditeur plus fluide, en évitant les déplacements inutiles dans la page et en conservant le contexte de navigation.

1. Constats : utiliser des modales

Actuellement, lorsqu'on clique sur un constat pour le consulter ou le modifier, son contenu s'affiche plus bas dans la page.

Quand il existe beaucoup de constats, c'est contraignant : il faut descendre, effectuer la modification, puis retrouver sa position précédente.

Je souhaite que le clic sur un constat ouvre une modale contenant son détail.

De même, l'ajout et la modification d'un constat devraient utiliser une modale.

Comportement attendu :

  • Ouverture du constat directement devant l'utilisateur.
  • Consultation et modification dans la modale.
  • Enregistrement, annulation ou fermeture.
  • Retour à l'endroit exact où l'utilisateur se trouvait, avec la même position de défilement et les mêmes filtres.
  • Conservation du contexte de sélection.

L'utilisateur ne doit pas devoir rechercher à nouveau son constat après avoir fermé la modale.

2. Références : modales pour l'ajout et la modification

Dans l'onglet Références, les tuiles dépliables fonctionnent bien pour consulter les informations.

En revanche, je préfère que les formulaires d'ajout et de modification s'ouvrent dans des modales.

Les tuiles restent utilisées pour la consultation.

L'utilisateur doit retrouver exactement sa position dans la liste lorsqu'il enregistre, annule ou ferme une modale.

3. Simplifier les références affichées dans un constat

Actuellement, lorsqu'un constat possède des références, leurs informations apparaissent directement dans son détail.

Or il existe déjà un bouton « X références » qui ouvre le volet latéral.

Cela fait doublon.

Je souhaite conserver uniquement :

  • Un libellé « Références citées ».
  • Le bouton « X références », qui ouvre le volet existant.
  • La possibilité de lier une référence existante au constat, comme actuellement.

La liste détaillée des références n'a plus besoin d'apparaître directement dans le constat.

4. « Tout afficher dans l'onglet Références » : filtrer automatiquement

Actuellement, ce bouton ouvre correctement l'onglet Références, mais affiche toutes les références.

Je voudrais qu'il affiche uniquement les références citées par le constat depuis lequel on vient.

Exemple :

Je consulte le constat A, qui cite les références 12 et 25.

Je clique sur « Tout afficher dans l'onglet Références ».

L'application ouvre l'onglet Références et n'affiche que les références 12 et 25.

Le filtre doit être clairement visible, par exemple :

« Références du constat : [Nom du constat] × »

L'utilisateur doit pouvoir retirer ce filtre pour retrouver toutes les références.

La recherche et le tri existants doivent rester utilisables avec ce filtre.

5. Navigation Précédent et historique du navigateur

C'est un point important.

Je veux que la navigation interne fonctionne naturellement avec le bouton Précédent du navigateur, y compris sur téléphone.

Exemple de parcours :

  1. Je suis dans l'onglet Constats.
  2. J'ouvre le constat A.
  3. Je clique sur « 2 références ».
  4. Le volet des références citées s'ouvre.
  5. Je clique sur « Tout afficher dans l'onglet Références ».
  6. J'arrive dans l'onglet Références, filtré sur les deux références du constat A.
  7. J'appuie sur Précédent dans mon navigateur ou sur mon téléphone.
  8. Je reviens au constat A, avec son volet de références ouvert, dans l'état où je l'avais quitté.

Je souhaite aussi que les changements d'onglet et les autres navigations significatives soient cohérents avec l'historique du navigateur.

Tu peux prévoir un bouton de retour visible lorsque cela améliore l'expérience.

Choisis une solution adaptée au routeur et à l'architecture existante, sans accumuler d'entrées d'historique inutiles.

6. Menu « Plus » sur téléphone

Le menu « Plus » des onglets devrait fonctionner comme un véritable menu déroulant.

Je souhaite une ouverture et une fermeture fluides, avec une animation légère et naturelle.

L'objectif est que la navigation mobile paraisse moins rigide et soit plus agréable.

7. Menu principal latéral gauche

Actuellement, le menu principal latéral gauche défile avec le contenu de la page.

Je souhaite qu'il reste fixe à l'écran pendant que l'utilisateur fait défiler le contenu.

Le menu principal ne doit pas disparaître lorsqu'on descend dans une longue page.

Adapte naturellement le comportement aux différentes tailles d'écran. Si son contenu dépasse la hauteur disponible, il peut disposer de son propre défilement.

8. Principe général pour les formulaires

Plus généralement, je souhaite privilégier les modales pour les opérations d'ajout et de modification lorsque c'est pertinent.

Cela concerne notamment les écrans présentant de longues listes, où les formulaires intégrés au milieu ou au bas de la page rendent la navigation pénible.

Il ne s'agit pas de transformer aveuglément tous les formulaires en modales.

Analyse les composants existants et applique ce principe là où il améliore réellement l'expérience.

L'objectif est d'avoir un comportement cohérent dans l'ensemble de l'application :

  • Consulter facilement.
  • Ajouter ou modifier sans perdre sa position.
  • Enregistrer ou annuler.
  • Retrouver immédiatement son contexte précédent.
  • Utiliser naturellement Précédent et Suivant dans le navigateur.

Pense également au focus clavier, à l'accessibilité, aux erreurs de validation et aux modifications non enregistrées.

9. Finition de R2

Tu peux intégrer à ce travail les limites résiduelles déjà relevées au checkpoint R2, notamment :

  • Les saisies remplacées silencieusement pendant Défaire/Refaire.
  • Les annonces accessibles lorsque plusieurs brouillons sont abandonnés.
  • Les derniers petits problèmes de formatage.

Pour BLK-015, conserve le diagnostic établi sur l'accumulation des droits dans la sandbox et le suivi du chantier séparé de pagination.

Organisation

Je te laisse choisir le découpage le plus pertinent, mutualiser les composants et prendre les décisions techniques nécessaires.

Tu peux apporter des améliorations complémentaires si elles servent directement les objectifs UX décrits.

Évite de multiplier les checkpoints intermédiaires pour des détails que tu peux résoudre par ton analyse et tes relectures habituelles.

Si une décision modifie réellement le fonctionnement métier, les droits, les données ou une règle importante déjà ratifiée, présente-moi le choix.

Sinon, avance de manière autonome.

À la fin, fournis-moi :

  • Le résumé des changements.
  • Les principaux choix UX et techniques.
  • Les tests et les résultats.
  • Les éventuelles limites restantes.
  • Une courte procédure pour tester les changements sur db:trial.

Je veux pouvoir essayer cette nouvelle navigation avant de considérer R2 définitivement terminé.

CLARIFICATIONS

Q: Standing restrictions from the earlier R2 briefs still bind? / A: yes (owner briefs 2026-11-12 and 2026-11-13): no SQL migration, Rust, worker, roles, MFA or secrets change; no db:trial or DEV access (the owner's trial app is left running, untouched); automated tests only on db:sandbox through the guarded wrapper (preflight, full-row guard), editor-equine never run; no merge, no deploy; the untracked faunosteo-v1-2-6-revue-ux-chatgpt.md kept; R3, R4, U2, U2b not started; BLK-015 diagnosis kept, grant pagination stays in RR-13. Q: Pass B open choices (visible wording, placement, animation timings, dialog layouts, URL parameter names q, species, archived, the « Revenir au constat » button, the post-create notice) / A: delegated — defaults of plan rev 1 (R2F-1 to R2F-9), reported in the final French report with the FR/EN table [gated 2026-11-13] Q: Pass A gaps? / A: none. The owner delegated analysis, design, split, tests and implementation; choices touching business behaviour, rights, data or an important ratified rule are presented once, at the plan validation gate.

Q: Plan rev 3 and choices 1-5 / A: approved by the owner 2026-11-13 (« je valide le plan et les choix 1 à 5 »), choice 6 = default (no list search kept, BDR-078); precisions 1-5 folded as criteria 13-17 [gated 2026-11-13]

ACCEPTANCE CRITERIA

  1. Constats: activating a tree item opens a modal dialog with its detail in front of the user; add and edit of a finding happen in a modal dialog; save, cancel and close are available; after any of them the page scroll position, the tree's expanded branches and the selection are those before the dialog opened, and focus returns to the opener (no re-search).
  2. Références: tiles stay the reading surface; adding and editing a reference happen in a modal dialog; after save, cancel or close the list scroll position, search, sort, filter and open tiles are those before the dialog opened.
  3. A finding's detail no longer lists its cited references inline: it shows the label « Références citées », the « X références » button opening the citations panel, and the control linking an existing reference.
  4. « Tout afficher dans l'onglet Références » opens the Références tab filtered to the references cited by the source finding, with a visible removable chip « Références du constat : [name] × »; search and sort keep working with the filter; removing the chip shows every reference. CHECK: cd /home/bchanot/Documents/faunosteo-v1-2/apps/app && grep -q "editor.references.filter_chip" src/i18n/fr.ts && grep -q "editor.references.filter_chip" src/i18n/en.ts && echo FILTER_KEY_OK EXPECT: FILTER_KEY_OK EVIDENCE: MET exit=0 marker-found :: FILTER_KEY_OK
  5. Browser Back and Forward follow the editor's internal navigation (tab changes, the finding dialog, the citations panel, the filtered Références tab), desktop and phone, with no duplicate or orphan entries; the owner's 8-step journey ends, after Back, on finding A with its panel open as left (e2e).
  6. The phone « Plus » tab menu opens and closes as a dropdown with a light animation (none under reduced motion), closes on outside click and Escape, keyboard and screen-reader usable.
  7. The main left sidebar stays in view while the page scrolls (sizes where it is shown), with its own scroll when taller than the viewport; no sideways scroll introduced.
  8. App-wide review of add/edit forms recorded (each candidate with its decision and reason); modals applied where the review says they help; focus, accessibility, validation errors and unsaved changes handled in every new dialog (no silent loss).
  9. R2 residuals: no typed text is replaced or dropped silently by Défaire/Refaire or by a read-only flip; announcements of several abandoned drafts are all heard (or the cause removed); prettier --check passes on the e2e and source files this run touches (fr.ts and en.ts exempt: pre-existing long lines, one line per new key; owner gate 2026-11-13). CHECK: cd /home/bchanot/Documents/faunosteo-v1-2/apps/app && pnpm -s exec prettier --check e2e/shell/editor-shell-layout.spec.ts >/dev/null && echo PRETTIER_LAYOUT_OK EXPECT: PRETTIER_LAYOUT_OK EVIDENCE: MET exit=0 marker-found :: PRETTIER_LAYOUT_OK
  10. Gates: typecheck, lint, test:run, build, e2e:ui green; e2e:shell on db:sandbox through the guarded wrapper without editor-equine, every failure other than admin.spec (BLK-015) fixed; no pre-existing sandbox row changed, metadata included.
  11. No change under supabase/, crates/, docker/, scripts/, packages/supabase/src; no db:trial or DEV access; no merge. CHECK: cd /home/bchanot/Documents/faunosteo-v1-2 && [ -z "$(git diff --name-only 36c6eb3..HEAD -- supabase crates docker scripts packages/supabase/src)" ] && echo SCOPE3_OK EXPECT: SCOPE3_OK EVIDENCE: MET exit=0 marker-found :: SCOPE3_OK
  12. Final French report: summary of changes, main UX and technical choices, tests and results, remaining limits, short db:trial test procedure.
  13. [gated 2026-11-13] A changed « Enregistrer » in the finding or reference dialog is exactly ONE undoable operation (undo length +1, one Défaire restores the prior state); a pristine « Enregistrer » and every « Annuler » / « Abandonner » add none (unit + e2e).
  14. [gated 2026-11-13] The citations sheet stacked over the finding dialog is fully usable by keyboard (Tab reaches every control, Escape closes the sheet only, focus returns to « X références ») and by touch (taps on its controls at 375 with hasTouch, the dialog underneath not activated) (e2e).
  15. [gated 2026-11-13] Browser history entries hold navigation state only (tab, section, open layers by element key, references filter by finding key): no typed text, no search term, no draft; an entry restores only for the same sheet and the same signed-in account, otherwise the editor opens on its default view (unit: entry state shape and mismatch rules). CHECK: cd /home/bchanot/Documents/faunosteo-v1-2/apps/app && f=src/editor/history/entry.ts && [ -f "$f" ] && grep -q "sheetId" "$f" && grep -q "tag" "$f" && ! grep -Eq "^\s*(query|draft|text|search)??\s*:" src/editor/history/*.ts && echo HISTORY_SHAPE_OK EXPECT: HISTORY_SHAPE_OK EVIDENCE: MET exit=0 marker-found :: HISTORY_SHAPE_OK
  16. [gated 2026-11-13] With the « Plus » menu open, the platform back request (CloseWatcher where the browser offers it) closes the menu before any navigation; without CloseWatcher the limit is stated (unit with a CloseWatcher stub).
  17. [gated 2026-11-13] No user modification is lost silently in any documented limit (owner condition on the stated limits).
  18. [gated 2026-11-13] Clients and Animaux lists keep no search term in browser history (BDR-078; choice 6 = default).

FILE SCOPE

apps/app/src/editor/** (navigation, history adapter, references view and filter), apps/app/src/components/editor/** (findings, references, citations, tabs, workspace, layers), apps/app/src/components/ui/{ModalDialog,Dialog}.tsx (only if a shared fix is needed), apps/app/src/components/shell/{ShellChrome,AppLayout}.tsx, apps/app/src/clients/useClientList.ts, apps/app/src/animals/useAnimalList.ts and their list routes (if the app-wide review keeps them), apps/app/src/i18n/{fr,en}.ts, apps/app/src/styles/** (only if needed), apps/app/tests/, apps/app/e2e/{support,shell,ui}/, docs/development/{V1-2-6_U1_CORRECTIONS,V1-2-6_OWNER_TRIAL,V1-2-6_R2_LABELS,BROWSER_TESTS,V1-2_ANATOMICAL_SHEETS}.md, docs/design/README.md, this contract, the plan, .claude/tasks/TODO.md, memory.

ORACLE AMENDMENT 2026-11-13 (controller): criterion 4 key renamed to the shipped key editor.references.filter_chip (chip « Références du constat : {name} »); criterion 15 path is src/editor/history/entry.ts (folder split in Task 1) and the forbidden-field scan covers every file of src/editor/history. Same assertions, no weakening.

Owner trial 2026-11-14 (brief « Retour de mon essai propriétaire R2 »): additional criteria

  1. [gated 2026-11-14] Finding view mode shows « Références citées » and « X références » only (no cite or remove control); edit mode adds and removes citations in the form draft; one changed « Enregistrer » = one undoable operation covering names and citations; the side sheet has no « Retirer de ce constat » (unit + e2e).
  2. [gated 2026-11-14] After deleting a finding, the first « Défaire » restores it at once, selected, visible and focused; the first Back after a deletion has a visible effect (unit + e2e).
  3. [gated 2026-11-14] Choosing a « Plus » entry by keyboard moves the focus to the new tab's panel (e2e at 375).
  4. [gated 2026-11-14] History entries hold a random session tag, never an account id; accounts stay separated (tag bound to the account by a digest, rotated on sign-out and on mismatch); left-draft flag keyed by the tag (unit). CHECK: cd /home/bchanot/Documents/faunosteo-v1-2/apps/app && ! grep -q "userId" src/editor/history/entry.ts && ! grep -q "userId" src/editor/leftDraft.ts && grep -q "tag" src/editor/history/entry.ts && echo SESSION_TAG_OK EXPECT: SESSION_TAG_OK EVIDENCE: MET SESSION_TAG_OK (controller 2026-11-14, rc 0; verifier rerun)
  5. [gated 2026-11-14] With a dirty dialog, a multi-entry traversal leaving the editor asks « Abandonner les modifications ? » before anything is lost where the Navigation API can cancel it (Chromium, e2e via CDP history jump); elsewhere the after-the-fact notice stays (unit).
  6. [gated 2026-11-14] R2 closure docs: validated status, limits accepted and lifted, a short list of final manual checks (incl. Android Back on a real phone, the leave confirmation, the fallback browsers).
  7. [gated 2026-11-14] U2 orientation recorded in the U2 plan, the UX decisions and the design README (annotation property modals with direct manipulation kept; boards to redraw and validate before U2 code); U2 not started.

ORACLE AMENDMENT 2026-11-14 (controller): criterion 15 now reads « same sheet and same session tag » (owner decision 2026-11-14 replaces the account id); its oracle checks sheetId and tag instead of userId.

SCOPE AMENDMENT 2026-11-14 (controller): apps/app/src/app/providers/AuthProvider.tsx joins FILE SCOPE (Task 8: the session tag rotates on sign-out for the app lifetime; an editor-local subscription would miss a sign-out while the editor is unmounted).

SCOPE AMENDMENT 2026-11-14 (controller): docs/development/V1-2-6_UX_PLAN.md and V1-2-6_UX_DECISIONS.md join FILE SCOPE (required by criterion 25); CLAUDE.md folder map lines, useLeaveGuard.ts and components/ui/afterModalsClosed.ts accepted (helpers named by the plan).

Owner follow-up 2026-11-15 (brief « Suite de mon essai propriétaire R2 »): additional criteria

  1. [gated 2026-11-15] Tab order is Général, Annotations, Constats, Références, Vérification at every width; on phones the « Plus » entries keep that relative order (unit tabsFor + e2e 375).
  2. [gated 2026-11-15] « Plus » opens a vertical dropdown (entries stacked top to bottom, touch rows ≥ 44 px, active entry marked by more than colour, light motion, none under reduced motion, inside the viewport at 320/375, no sideways scroll); existing dismissals and keyboard focus kept (unit + e2e + axe).
  3. [gated 2026-11-15] The finding dialog, in view and edit modes, shows only « Références citées » and « X références »; its « Modifier » edits the finding's properties only (no citation list or control) and its save never rewrites citations (unit + e2e).
  4. [gated 2026-11-15] « X références » opens a modal references dialog stacked over the finding dialog, replacing the side sheet; view mode reads the cited references (no modifying control), close returns to the finding dialog with focus on « X références »; Back, reload restore, « Tout afficher » and « Aller à » keep working (unit + e2e, keyboard and touch, axe).
  5. [gated 2026-11-15] The references dialog's own « Modifier » edits the associations in a draft: cite an existing reference, remove one, create a new one (cited in the draft), open a reference's edit dialog; « Enregistrer » = ONE undoable operation, pristine none, « Annuler »/close/Back/leave with changes asks first (no silent loss) (unit + e2e).
  6. [gated 2026-11-15] Docs: R2 follow-up recorded, limits and labels updated, a short db:trial check procedure for both adjustments. CHECK: cd /home/bchanot/Documents/faunosteo-v1-2 && grep -q "4.13" docs/development/V1-2-6_OWNER_TRIAL.md && echo FOLLOWUP_DOCS_OK EXPECT: FOLLOWUP_DOCS_OK EVIDENCE: MET FOLLOWUP_DOCS_OK (controller 2026-11-15, rc 0; verifier rerun)

CLARIFICATIONS 2026-11-15 (controller, owner brief 2026-11-15): the tests removed or reduced in b41c24b..HEAD (editor-shell-layout.spec.ts sheet edge geometry, editor-finding-dialog / editor-findings citation controls in the finding form, editor-initial-tab tier parameter, editor-reference-dialog reference over the side sheet, editor-references-panel sheet scrim and header) cover behaviour the owner asked to remove (side sheet, citing in the finding form, phone split); their replacements live in editor-citations-edit.test.tsx, editor-citations-guards.test.tsx and the updated e2e specs. These assertion drops are authorized.

Owner pre-closure brief 2026-11-15 (« Avant la clôture définitive de R2 »): additional criteria

  1. [gated 2026-11-15] In the references dialog's edit mode, the select only browses: arrow keys or a pick never change the draft; a « Citer » button adds the chosen reference (unit + e2e keyboard). CHECK: cd /home/bchanot/Documents/faunosteo-v1-2/apps/app && grep -q "'editor.citations.cite'" src/i18n/fr.ts && grep -q "'editor.citations.cite'" src/i18n/en.ts && echo CITE_KEY_OK EXPECT: CITE_KEY_OK EVIDENCE: MET CITE_KEY_OK (controller 2026-11-15 rc 0; verifier rerun)
  2. [gated 2026-11-15] A reference created from the references dialog's edit mode is written only by its « Enregistrer », together with the citations, as ONE undoable operation; abandoning the draft leaves the library unchanged; « Ajouter une référence » in the Références tab still creates an independent reference at once (unit + e2e).
  3. [gated 2026-11-15] Labels follow the cited element's kind: « Références du constat » / « Ce constat ne cite aucune référence. » for a finding, « Références de la famille » / « Cette famille ne cite aucune référence. » for a family, same logic in EN and in the filtered Références tab (unit). CHECK: cd /home/bchanot/Documents/faunosteo-v1-2/apps/app && grep -q "Références de la famille" src/i18n/fr.ts && grep -q "Cette famille ne cite aucune référence." src/i18n/fr.ts && grep -q "'editor.references.panel_empty_family'" src/i18n/en.ts && echo FAMILY_LABELS_OK EXPECT: FAMILY_LABELS_OK EVIDENCE: MET FAMILY_LABELS_OK (controller 2026-11-15 rc 0; verifier rerun)
  4. [gated 2026-11-15] The shared Dialog ✕ has a touch area of at least 44 × 44 px (e2e bounding box at 375 and 1280, axe). CHECK: cd /home/bchanot/Documents/faunosteo-v1-2/apps/app && grep -q "h-11 w-11" src/components/ui/Dialog.tsx && echo CLOSE_44_OK EXPECT: CLOSE_44_OK EVIDENCE: MET CLOSE_44_OK (controller 2026-11-15 rc 0; verifier rerun)
  5. [gated 2026-11-15] Docs: limits lifted, labels table, short manual checks for db:trial; the full sweep reported with its failures (never as all green).

CLARIFICATIONS 2026-11-15 b (controller, owner pre-closure brief): the Rev 5 unit tests in apps/app/tests/unit/editor-citations-edit.test.tsx asserting that a reference created from the edit mode is in the library before « Enregistrer » (two undo steps) and stays uncited after an abandon are inverted by Task 15 (owner item 2 asks the opposite behaviour); the inversion is authorized, the new assertions are stricter (library unchanged, one undo step).

SCOPE AMENDMENT 2026-11-15 (controller): apps/app/e2e/harness/dialog.tsx joins FILE SCOPE (the ui Dialog harness gains the long-title case for criterion 35; dev-server only, never built).

CLARIFICATIONS 2026-11-15 c (controller, owner pre-closure brief: « Le balayage complet présente toujours des échecs et ne doit pas être annoncé comme entièrement vert »): for criterion 10, full-sweep failures that are browser crashes (« Target crashed ») or navigation timeouts under the accumulated sandbox load, and that pass when their spec runs alone, are reported to the owner with their counts and names, as the BLK-015 family; they are not counted as fixed and the sweep is never announced green.

CLOSURE 2026-11-15 (owner brief « Clôture R2 »)

Owner: db:trial manual checks done, all pass; R2 validated functionally and graphically, no further correction. Choices ratified: « Modifier la référence » on a saved reference keeps its own dialog and Défaire; an unsaved new reference is lost on an abrupt browser close (as other unsaved forms). Criteria 1-36: MET, with criterion 10 reported as is: final sweep 52d5613 273 passed, 163 skipped, 6 failed (admin.spec, BLK-015 open, RR-13); never announced green. Status: CLOSED. No merge, no deployment authorized.