Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
180 lines
6.3 KiB
Markdown
180 lines
6.3 KiB
Markdown
# 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: 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 `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
|
||
<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`)
|
||
|
||
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<string, Bone>`.
|
||
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 `<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"`:
|
||
|
||
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/<speciesId>/<filename>.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.
|