# 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). | | `data-anno-lateral` | `string` | Laterality hint: `bilateral` (zone has left/right instances, e.g. knee) or `unpaired` (no laterality). Default when absent: `unpaired`. Used by the report editor to prompt side selection on bilateral zones. | --- ## 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`: ```xml ``` - Hitbox must have `class` containing `hitbox` (case-insensitive substring). - Visible twin must have `class` containing `visible`. - 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: ```xml ``` --- ## Parser behavior (`src/anatomy/svgConvention.ts`) 1. `parseSvgBones(svgRoot)` — walks all elements with `data-anno-id`. 2. Groups by `data-anno-id` → one `Bone` per id. 3. For each group, validates required attributes. 4. Classifies elements into `hitboxEls` (class contains "hitbox") and `visibleEls` (class contains "visible"). Elements in neither class land in `visibleEls` by default. 5. Returns `Map`. 6. Throws `SvgConventionError(message, boneId, missingAttribute)` on first violation. ### Validated rules - `data-anno-name-fr` must be non-empty. - `data-anno-name-en` must be non-empty. - `data-anno-category` must be one of the seven valid values. - If `data-anno-opens-detail` is 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 `` 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"`: 1. Canvas emits `requestDetail({ id: 'head' })`. 2. `DetailModal` resolves the path via `SpeciesManifest.details['head']`. 3. Loads and renders the detail SVG inline. 4. Clicks inside the modal add `ObservationZone` entries with `detailSourceId: 'head'`. 5. 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[]` on `ObservationZone`, replacing the bloc semantically. - PDF prints precise vertebrae: "T12, T15" instead of the zone label. --- ## Adding a new SVG 1. Place SVG at `public/species//.svg`. 2. Ensure every clickable element has the four required attributes. 3. Use Pattern 1 or Pattern 2 consistently per category. 4. Add to `SpeciesManifest.details` if it is a detail popup SVG. 5. Run `pnpm test:run` — the convention parser tests will catch missing attributes. 6. See `docs/ADDING-A-SPECIES.md` for adding a full new species.