Three coupled bugs in zone interaction: 1. Clicks inside the head detail popup were ignored — EditorRoute looked up the clicked id in the main-SVG bones map only, so detail-only ids (point-mpbykomv et al.) returned undefined. 2. Spine zones did not open VertebraPicker on click; the picker was only reachable via the per-zone "Vertèbres…" button. 3. The new SVG hint data-anno-special="vertebral-precision" was present in Horse.svg but unread by the parser/UI. Parser now reads data-anno-special into Bone.special. EditorRoute parses the detail SVG on open and falls back to detailBones for id lookups. When bone.special === 'vertebral-precision', clicking adds the zone (if absent) and opens VertebraPicker for that zone index; toggle-off via main click is disabled for these zones (use ✕). The "Vertèbres…" button in ObservationCard is now shown only on zones that support it. Convention doc updated. Co-Authored-By: Claude <noreply@anthropic.com>
6.1 KiB
Anatomy SVG Convention
Status: Source of truth. All SVG assets and parser code must conform.
Required data attributes
Every clickable zone element must carry all four attributes:
| Attribute | Type | Description |
|---|---|---|
data-anno-id |
string |
Stable kebab-case identifier. Unique per bone. |
data-anno-name-fr |
string |
French anatomical label (e.g. "Colonne cervicale"). |
data-anno-name-en |
string |
English anatomical label (e.g. "Cervical spine"). |
data-anno-category |
BoneCategory |
One of the seven valid categories below. |
Optional data attributes
| Attribute | Type | Description |
|---|---|---|
data-anno-opens-detail |
string |
Id of the detail popup SVG to open on click. Key must exist in SpeciesManifest.details. |
data-anno-special |
string |
Free-form behavior hint consumed by the app. Known value: vertebral-precision → clicking the zone opens VertebraPicker. Opaque to the parser; new values can be added without code changes (just unused). |
Valid categories
| Value | Meaning |
|---|---|
articulation |
Joint space |
charniere |
Junctional / transitional zone |
spine-zone |
Vertebral region bloc — click opens VertebraPicker |
os |
Single bone |
os-overlay |
Overlapping bone layer |
head |
Head region (main SVG entry point for detail popup) |
cadran-crane |
Cranial quadrant (inside detail popup) |
Rendering patterns
Pattern 1 — Hitbox + visible twin
Used for: articulation, charniere, os-overlay, head.
Two sibling SVG elements share the same data-anno-id:
<!-- hitbox: transparent fill, receives pointer events -->
<polygon
data-anno-id="cervical-spine"
data-anno-name-fr="Colonne cervicale"
data-anno-name-en="Cervical spine"
data-anno-category="spine-zone"
class="bone-hitbox"
fill="transparent"
style="pointer-events: all; cursor: pointer"
/>
<!-- visible twin: colored fill, no pointer events -->
<polygon
data-anno-id="cervical-spine"
class="bone-visible"
fill="#c8d8e8"
style="pointer-events: none"
/>
- Hitbox must have
classcontaininghitbox(case-insensitive substring). - Visible twin must have
classcontainingvisible. - Order in DOM does not matter — parser groups by
data-anno-id.
Pattern 2 — Single element
Used for: spine-zone, standalone head zones inside detail SVGs.
One polygon carries everything:
<polygon
data-anno-id="thoracic-t1-t18"
data-anno-name-fr="Thoracique T1-T18"
data-anno-name-en="Thoracic T1-T18"
data-anno-category="spine-zone"
fill="#d4e8d4"
style="pointer-events: all; cursor: pointer"
/>
Parser behavior (src/anatomy/svgConvention.ts)
parseSvgBones(svgRoot)— walks all elements withdata-anno-id.- Groups by
data-anno-id→ oneBoneper id. - For each group, validates required attributes.
- Classifies elements into
hitboxEls(class contains "hitbox") andvisibleEls(class contains "visible"). Elements in neither class land invisibleElsby default. - Returns
Map<string, Bone>. - Throws
SvgConventionError(message, boneId, missingAttribute)on first violation.
Validated rules
data-anno-name-frmust be non-empty.data-anno-name-enmust be non-empty.data-anno-categorymust be one of the seven valid values.- If
data-anno-opens-detailis present, the value must be a non-empty string (runtime check against species manifest happens in the canvas component).
Click handling (delegated listener)
A single click listener on the root <svg> element:
event.target → walk up ancestors → find data-anno-id
→ if data-anno-opens-detail present → emit requestDetail({id})
→ else if data-anno-special === 'vertebral-precision' →
add zone to current observation (if absent) and open VertebraPicker
→ else → toggle bone in current observation
Never attach per-element click listeners — the SVG may have thousands of elements.
Note: data-anno-category is opaque to click handling — branching is
driven by data-anno-opens-detail and data-anno-special only.
Zone visual states
Applied as data-state attribute on all elements sharing a data-anno-id:
data-state |
Condition | Visual |
|---|---|---|
current |
Bone is in the active observation | Solid accent fill |
linked |
Bone is in another (non-active) observation | Faded dashed border, accent color of owning obs |
multi |
Bone is in ≥2 observations | Striped CSS background pattern + indicator badge |
| (absent) | Default / unselected | SVG original fill |
Accent colors cycle through 6 HSL tones (defined in src/styles/tokens.css):
terracotta → sauge → bleu canard → ambre → prune → ocre.
Detail popup mechanism
When a zone has data-anno-opens-detail="head":
- Canvas emits
requestDetail({ id: 'head' }). DetailModalresolves the path viaSpeciesManifest.details['head'].- Loads and renders the detail SVG inline.
- Clicks inside the modal add
ObservationZoneentries withdetailSourceId: 'head'. - The "entry" zone itself (the polygon that triggered the popup) is never persisted.
Vertebra picker trigger
When a bone has data-anno-special="vertebral-precision", clicking it adds the
zone to the active observation (if absent) and opens VertebraPicker:
- Region tabs: Cervicales (C1–C7), Thoraciques (T1–T18), Lombaires (L1–L6), Sacrales (S1–S5), Caudales (Cd1–Cd18).
- Multi-select chip grid, ≥40 px touch targets.
- Per-region "Tout cocher / Tout décocher".
- Stored as
vertebrae: Vertebra[]onObservationZone, replacing the bloc semantically. - PDF prints precise vertebrae: "T12, T15" instead of the zone label.
Adding a new SVG
- Place SVG at
public/species/<speciesId>/<filename>.svg. - Ensure every clickable element has the four required attributes.
- Use Pattern 1 or Pattern 2 consistently per category.
- Add to
SpeciesManifest.detailsif it is a detail popup SVG. - Run
pnpm test:run— the convention parser tests will catch missing attributes. - See
docs/ADDING-A-SPECIES.mdfor adding a full new species.