Files
faunosteo/docs/development/V1-2-6_UX_FINDINGS_NAV.md
T
bchanot 00aaccfc79 docs(docs): complement boards compute the last names, decisions F17-F21
Verifier round 2: view chip and grasset names computed from the draft;
partial clears, out-of-filter count, zone picker order, dashed sibling
and result presentation listed as owner decisions.
2026-11-06 13:22:54 +01:00

21 KiB
Raw Blame History

V1-2.6 UX complement: navigation between annotations and findings

Status: PROPOSAL for the owner, 2026-11-06 (brief « Nouvelle exigence UX : navigation bidirectionnelle entre annotations et constats »). Design only: no application, Rust, SQL or worker change; nothing here authorises code. The U1 plan (.claude/tasks/plans/2026-11-06-v1-2-6-ux-u1.md, commit 2e46c14) is unchanged by this track. Contract: .claude/tasks/contracts/2026-11-06-v1-2-6-findings-nav-design.md. Boards: docs/design/v1-2-6-constats/ (17 to 22, after the 16 validated v1-2-6 boards).

Paths: core/ stands for crates/core/src/, app/ for apps/app/src/.

1. Audit of the existing relations (request C)

Link Held by Cardinality Core rule
annotation → view view_id on every annotation (core/domain/sheet/schema.rs:421, :447) many to one error annotation.view.missing (validate.rs:266-280)
detail view → parent view parent_view_id (schema.rs:270-271) many to one errors view.parent.missing, view.parent.cycle, view.unreachable (validate.rs:146-223)
detail trigger → view it opens opens_view_id (schema.rs:460-461) many to one: a trigger opens exactly one view, a detail view is opened by 1 to N triggers error annotation.opens_view.invalid (validate.rs:298-328, the target is a direct child of the trigger's view); view.unreachable asks for at least one trigger per detail view (validate.rs:200-223); no uniqueness rule; a trigger has no finding zone and no region by type (schema.rs:439-462)
annotation → annotation category category_id (schema.rs:423, :449) many to one error annotation.category.missing (validate.rs:282-296); the category has no link to findings
observable annotation → finding zone finding_zone_id: Option (schema.rs:432-433) an annotation names 0 or 1 zone; a zone is named by 0 to N annotations error annotation.finding_zone.missing when it dangles (validate.rs:330-346); warning annotation.no_findings when null (:367-386); warning finding_zone.unreferenced when no annotation names a zone (:437-457); no uniqueness rule, and docs/development/ANATOMICAL_SHEET_MODEL.md:102-103 says several annotations may share a zone
observable annotation → vertebral region vertebral_region_code (schema.rs:434-435) many to one error annotation.region.missing (validate.rs:348-365); a region has no link to findings, it opens the practitioner's vertebra picker (core/domain/editor/zone.rs:101-103)
finding zone → families → findings categories (schema.rs:592), FindingCategory with kind (:568-583), recursive FindingNode (:538-556) tree, depth ≤ 8 (edit.rs:397-420) ids unique among siblings (finding.id.duplicate, validate.rs:410-435); a finding is addressed by (zone, path) (keys.rs:42-46)
family kind FindingCategoryKind = dysfunction / consultation_reason / anamnesis / custom (schema.rs:558-566) on the category, never on nodes no rule per zone (no « one of each »)
findings → references reference_ids on categories and nodes (schema.rs:578-579, :550-551) many to many error finding.reference.missing (validate.rs:466-499)
laterality annotation only (unpaired / bilateral / left / right, schema.rs:393-402) none on zones or findings the side exists only in reports, for bilateral annotations (zone.rs:104-112)

There is no reverse link (zone → annotations) in the document, in the core index (core/domain/sheet/index.rs:25-33, index_data.rs:19-45, preview.rs:330-342) or in the editor. The only core computation that returns the annotations of a zone is sheet.dependents (edit.rs:894-977, relation links_zone), a free op over the whole document text, used for delete confirmations. BDR-031 already rejected an annotation_finding_map array.

1.2 Equine draft data (supabase/seed/anatomical-sheets/equine/draft/document.json)

  • 2 views (main, head detail), 28 annotations (22 points, 5 zones, 1 detail trigger), 27 finding zones, 811 families and findings (81 families, 730 findings, every zone with exactly one family of each of the three kinds, no custom family), depth 3, 48 references.
  • Every finding zone is named by exactly one annotation; no observable annotation lacks a zone; zone ids equal annotation ids; no left/right pair, no main + detail duplicate, no point + polygon on one zone. The duplicate cases of the request do not exist in this sheet; they exist only in synthetic core fixtures (crates/core/tests/oracles/r3/highlight.json, hip ×5; crates/core/tests/conformance/annotation-id-duplicate.json, atm ×2).
  • Labels repeat: 283 distinct French labels over 811 elements; the family name « Anamnèse / facteurs rapportés » is shared by all 27 zones, with three distinct subtrees (8 cranial zones, 9 spinal zones, 10 limb and pelvic zones), and « Restriction en flexion » appears 15 times. A search result without its zone would be ambiguous.
  • Grasset: annotation stifle (point, main view, bilateral) names zone stifle: 3 families, 29 findings (16, 7, 6), 3 with a veterinary referral flag, one reference cited.

1.3 What the editor and the core already offer

  • Editor: one selectedId on the canvas (app/editor/annotations/uiState.ts:14-67), one marked annotation (useCanvasBuild.ts:70-83); « Zone de constats » select in the annotation properties (AnnotationFields.tsx:162-187) and at creation (CreationFields.tsx:141-161); the Constats tab as an ARIA tree over buildItems (app/editor/findings/tree.ts:161-196), creation of zones, families and findings (FindingCreateForm.tsx); no search, no filter, no link between the two tabs; the Annotations tab cannot create a finding zone.
  • Read-only precedents: the catalogue's ZonePanel (app/components/catalogue/ZonePanel.tsx:62-133) shows the findings of the selected annotation's zone by family; the report editor de-duplicates by zone and side (app/components/observation/ObservationCard.tsx:78-93) and marks several annotations at once (app/components/canvas/AnatomyCanvas.tsx:79-85).
  • Core: no search op, no reverse map; the composed canvas tags every annotation with data-anno-zone (core/anatomy/layer.rs:176-208, contract docs/ANNOTATION-RENDERING.md:50-66).

1.4 Conclusion of the audit

The request needs no new association: an annotation already names its finding zone, the findings belong to the zone, and « the findings of an annotation » are the findings of that zone. « Gérer l'association anatomique » is the existing finding_zone_id field. Duplicates are handled by grouping on the zone id: findings are listed and counted once per zone, whatever the number of annotations naming it. No document structure change is proposed.

2. Design (boards 17 to 22)

Board Content
17 Annotations tab, an annotation selected: the side column gains a « Constats · n » segment beside « Propriétés »: the zone (with « Changer » and the other annotations that show it), the families of the zone in document order with their counts, « Ajouter un constat », « Ouvrir dans Constats »
18 From the selection: A, add a finding in the zone (family, parent, FR/EN names; « Ajouter » / « Abandonner »); B, edit a finding with the same fields and component as the Constats tab detail (C9)
19 Association: A, change the finding zone (searchable list, current zone first, « n annotations » per zone, the rule « no finding moves »); B, an annotation without zone (link to an existing zone, or create one for it); C, a detail trigger has no findings (segment disabled with its reason); D, a zone shown by two annotations (illustrative, absent from the equine draft)
20 Constats tab: instant search, result count over the total, « Filtrer sur le schéma », « Réinitialiser les filtres »; results shown in their tree (zone, family, ancestors in grey); each zone row links to the drawing (« Sur le schéma »)
21 « Filtrer sur le schéma »: non-modal right panel; views chosen as chips (one or more); click on points or zones to add or remove them; selection chips; the tree on the left updates at each click and combines with the text
22 States: no result (with the count outside the drawing filter and « Retirer le filtre du schéma »); keyboard list of the annotations with checkboxes; read-only (rights, frozen, historical); below 1 024 px, consultation with the list only

Bidirectional path: drawing → « Ouvrir dans Constats » (focus request on the zone or finding key); Constats → « Sur le schéma » (focus request on the annotation key, Constats segment open). Filters are interface state: kept while the page lives (U1 keeps the Constats tab mounted), never written to the document, never saved, never arming the leave guard.

3. U1 integration points (work item 1)

No integration point has to be added to U1, and no amendment of the U1 plan is proposed. The seams the feature needs are already in the plan:

  • navigate(target) with zone, finding and annotation keys (targetOfKey, U1 plan §1) gives both directions of the jump; PropertiesPanel receives navigate from Lot B1 (its unmeasured-view link is retargeted there).
  • The Constats tab stays mounted (U1 plan §2), so search and drawing filters survive tab changes without any store.
  • usePlaceVisible() and the « one composed copy of a view » rule (U1 plan §2) cover the filter panel's drawing: it detaches while its place is hidden, and the Annotations drawing is hidden while Constats is shown.
  • folded exported in Lot C (case- and accent-insensitive match) serves the findings search.
  • The secondary panel slot of the references panel (U1 plan §5) is where the filter panel goes; the reducer gains a second panel kind when this feature lands, a local change (owner precision 10: no global navigation rebuilt). Watch item for the U2b executors: the filter panel is a variant, not a copy: no scrim and no inert on the tab panels (F5: the tree stays live), unlike the references panel.

One watch item for the U1 executors, with no plan change: keep the Constats tab's selection, expansion and future filter state local to the kept-mounted FindingsTab (as the plan already does), not in the navigation reducer.

4. Placement (work item 2)

Recommended: a dedicated sub-step U2b · Annotations et constats, after U2 and before U3, on its own owner authorisation.

  • Why after U2: U2 rewrites the selection, pointer and keyboard model of the same canvas and the same PropertiesPanel; the Constats segment sits in that panel and the drawing filter reuses the pointer rules (§2 G of the UX plan: a second pointer cancels, arrows pan only on the canvas box).
  • Why before U3-U6: none of them changes the zone link or the findings tree; U3 and U6 touch AnnotationFields (colour, roles, region picker), not the zone field nor the Constats tab; U4 and U5 add views, which the view chips list by construction; U6's internal cat-access and the detail triggers never carry findings, so they never appear as filter choices.
  • Alternative: after U6 (less rework risk in AnnotationFields, later delivery).
  • Files: app/components/editor/annotations/{PropertiesPanel,EditableAnnotations,ConstatsSegment (new), ZoneLink (new)}.tsx, app/components/editor/tabs/FindingsTab.tsx, app/components/editor/findings/{FindingTree, FindingDetail,FindingContent,FindingCreateForm,FindingsSearch (new),SchemaFilterPanel (new)}.tsx, app/editor/findings/{tree,filter (new)}.ts, app/editor/annotations/zoneIndex.ts (new), the canvas marking state, docs/ANNOTATION-RENDERING.md (new page state for filter marks, updated first), i18n.
  • Rust ops: none. Wasm budget: unchanged (margin 7 857 B kept for U2, U5, U6, LRN-118).
  • Boundary (BDR-043, EVAL-034): the zone → annotations map is a group-by on a field the document already holds, and the search filters what the page displays; neither decides validity, accepts a change or computes a rule. Same kind of read as citationCounts (U1) and the catalogue's sheet-name search (filterCatalog, BDR-095). Every change made from the new surfaces goes through the existing sheet.edit commands (finding insert and update, annotation update), so the core keeps the last word. A core op would be justified only if a measure on a large sheet showed the page-side derivation over the 500 ms budget.
  • Acceptance (proposal): boards 17-22 built; A and B work with mouse, touch from 1 024 px and keyboard; every finding change undoable as one entry; filters never change the document; read-only modes show no edit control; axe clean.
  • Owner demo: select the grasset, read its 29 findings, add one, undo it; search « restriction »; filter on grasset and jarret; reset; jump both ways.
  • Rollback: revert of the sub-step's commits (no data, no schema).

5. Technical risks (work item 4)

Risk Probability Mitigation
Editing findings from annotation A changes them for every annotation naming the zone medium the segment names the zone and lists the other annotations (board 17, 19 D); edits go to the zone, never copied
Changing an annotation's zone changes what practitioners are offered and turns the annotation to_confirm (edit.rs:495-509) medium the change goes through the existing field and its review rule; old reports keep their zone id and path (core/domain/report/rebase.rs:148-157, BDR-010)
Search results ambiguous (repeated labels across 27 zones) high results always shown under their zone and family; the count names zones too
Count unit undefined (zones, families, findings, leaves) high decision F2 (recommendation: findings at any depth)
Multi-annotation marking needs a new page state on the composed canvas medium page-side restyle only (BDR-053), ANNOTATION-RENDERING.md updated before the code
A third composition of a view in the page (filter panel) medium U1's detach-while-hidden rule; one visible composition per view at a time
Kept-mounted Constats tab recomputing filters on each commit low memoised on the parsed document and the filter state; measured with the U1 commit-to-paint check (500 ms budget)
Duplicates never exercised by the equine data high unit and e2e fixtures with two annotations on one zone (main + detail, left + right), modelled on the core's synthetic fixtures
Terminology: « zone » is an annotation kind and a finding zone; « catégorie » is an annotation category and a family high labels « Zone de constats » and « Famille » proposed (decision F7), kept apart from « Zone » (shape) and « Catégorie » (colour category)
Creating a zone from an annotation is two changes (zone, link) medium one batch commit, all or nothing, one undo entry (decision F8)
Rework if U2, U3 or U6 change the panel structure afterwards medium placement after U2 (section 4)
Laterality: a left and a right annotation on one zone show the same findings low expected (findings carry no side; the report adds it); stated in the segment's help
Wasm budget low no core op (section 4)

6. Tests (work item 4)

  • Unit: zone index (zone → annotations, annotation → zone, triggers and null zones excluded); findings filter (text in FR and EN, accents and case, zone names, ancestors kept, counts per unit, combination with the drawing filter, empty result, reset); de-duplication with two annotations on one zone (main + detail, left + right); the Constats segment (families in order, counts, add and edit through the existing commands, one undo entry each, change of zone, null zone, detail trigger disabled with its reason, read-only in every read-only mode); « Ouvrir dans Constats » and « Sur le schéma » focus requests (found, kept, none); filters absent from the document text and from the leave guard; filter state kept across tab changes and pruned when an undo removes a filtered zone or annotation.
  • E2E (sandbox): grasset journey (select, read, add, undo, edit, change zone and back); search with count; drawing filter with mouse and touch at 1 024 and 1 180 px; keyboard-only filter through the list; reset; both jumps; narrow read-only at 375 px (search and list filter, no edit control); no horizontal scroll at 1 024, 1 180, 1 280, 375 px.
  • Accessibility: axe on the segment, the search, the filter panel open, the narrow mode; count in a polite live region after a typing pause; checkboxes named with annotation and zone; focus after each jump on its target, never body.
  • Regression: C9 (findings detail), C13 (recovery), C14 (history bound), C16 (narrow read-only), the U1 suites; the core suites unchanged (no core change); pnpm r5:import-equine --check unchanged.

7. Decisions to take (owner)

None is decided by this proposal; each has a recommendation (F1 to F21).

Id Question Recommendation
F1 Sub-step dedicated U2b after U2 (alternative: after U6)
F2 What the counters count findings at any depth; families and zones are not counted as findings; the result line also names the zones (« 108 constats sur 730, dans 26 zones »)
F3 Search scope finding names in French and English, accents and case ignored; a zone whose name matches shows all its findings; descriptions and references not searched
F4 Drawing filter semantics the chosen views give the drawings to pick on, and all their zones while nothing is picked; once one annotation is picked, only the picked zones count; text and drawing combine with AND; applied at each click, no « Appliquer »
F5 Filter panel non-modal right panel without scrim (the tree stays live); one secondary panel at a time (opening « Références » closes it, the filter stays active as a chip)
F6 Below 1 024 px consultation: search and filter available, zones chosen in a list (44 px targets), no selection on the drawing
F7 Labels « Accès : » as the name shown for a detail trigger (it has no name in the document), « Constats » for the segment, « Zone de constats » for the link, « Famille » for a finding category (today the Constats tab says « Catégorie », to align at the label review), « Filtrer sur le schéma », « Réinitialiser les filtres »
F8 Creating a zone from an annotation without one allowed, one batch (zone with the annotation's name, editable, then the link), one undo entry
F9 Editing a finding from the drawing in the side column, with the shared detail component; « Ouvrir dans Constats » for the tree context
F10 Filter lifetime kept while the page lives (tab changes included), cleared by « Réinitialiser les filtres » and on reload; a filtered zone or annotation removed by an undo leaves the filter silently narrower with its chip updated
F11 « Sur le schéma » from a zone named by several annotations selects the first in document order and lists the others in the segment
F12 Multi-annotation marking in the filter panel accent outline and check disc (board 21; F20 for the other annotation of a picked zone), a new page state recorded in docs/ANNOTATION-RENDERING.md before any code
F13 Finding detail while the filter panel is open hidden, the tree takes the width; it comes back when the panel closes (board 21)
F14 Grouping of the keyboard list of annotations by annotation category (colour), as the drawing shows them, with a caption saying so; not by finding family (board 22 B)
F15 Choosing a zone already shown by another annotation allowed, with a notice naming the other annotation before the change is applied (board 19 A)
F16 « Constats » segment of a detail trigger shown disabled with its reason rather than hidden, so the panel keeps the same layout (board 19 C)
F17 Partial clears beside the general reset « Effacer la sélection » in the filter panel (board 21), « Retirer le filtre du schéma » in the empty state (board 22 A), and a ✕ on each filter chip (« Texte », « Schéma ») to drop one filter; « Réinitialiser les filtres » clears all, same button on every board
F18 No-result state says how many findings match the text outside the drawing filter and offers to remove that filter (board 22 A)
F19 Zone picker of « Changer » current zone first with a « zone actuelle » tag, then the zones in document order, each with the number of annotations that show it (board 19 A)
F20 Other annotation of a picked zone in the filter dashed outline on the drawing, the zone counted once (board 19 D); completes F12
F21 How search results are shown in the tree: branches without a result folded, ancestors in grey, the matched text highlighted, a result count per zone and a « Sur le schéma » link (board 20); while the filter panel is open, a compact list per zone with the family as a prefix, because the panel takes the width (board 21)

8. Out of scope

Findings attached to several zones, moving findings between zones, drag and drop in the tree, bulk import (all level 2, contract §8.3 and §16.12); practitioner-side search (V1-3 reports); the catalogue (BDR-095 keeps its search to sheet names); any core op, schema change or V1-2.7 control.