Files
faunosteo/docs/ANATOMY-SVG-CONVENTION.md
T
Bastien ChanotandClaude b9da4fa04a fix(anatomy,editor): detail-popup clicks + spine zones open VertebraPicker via data-anno-special
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>
2026-05-19 04:58:04 +02:00

179 lines
6.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`:
```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.