feat(app): application on the canonical sheet — report v3 store with v2 draft migration, bundled SheetProvider (SHEET_BUNDLE), annotation layer rendered from the document, zone interaction service, pickers and cards on the sheet index, PDF v3 export with v2 archive import; legacy registry, matchers, editors and assets removed
This commit is contained in:
1 parent
0a17e390cf
commit
ce2ec26112
114 files changed
+3560
-14637
No files matched your search
@@ -1,230 +0,0 @@
|
||||
# Adding a New Species
|
||||
|
||||
Faunosteo ships with one species (`equine`). Adding a new one is
|
||||
mostly authoring work — anatomy SVGs and a findings JSON — backed by a
|
||||
small amount of boilerplate that the project can scaffold for you.
|
||||
|
||||
> Throughout this document, replace `<id>` with the new species'
|
||||
> kebab-case id (e.g. `canine`, `feline`, `bovine`).
|
||||
|
||||
---
|
||||
|
||||
## Quick start — `pnpm scaffold:species`
|
||||
|
||||
```bash
|
||||
pnpm scaffold:species
|
||||
```
|
||||
|
||||
The interactive prompt asks for:
|
||||
|
||||
- species id (kebab-case, e.g. `canine`),
|
||||
- French and English display labels,
|
||||
- the asset folder under `public/species/` (defaults to the id),
|
||||
- the main SVG filename,
|
||||
- zero or more detail-popup SVG paths (mapped by `data-anno-opens-detail` key),
|
||||
- the vertebral formula (C / T / L / S / Cd).
|
||||
|
||||
It then writes:
|
||||
|
||||
```
|
||||
src/domain/species/<id>/
|
||||
index.ts ← SpeciesManifest with `export default`
|
||||
vertebrae.ts ← VertebralFormula constant
|
||||
pathologies.ts ← parses pathologies.json via SpeciesFindingsSchema
|
||||
pathologies.json ← minimal valid catalog skeleton
|
||||
public/species/<assetFolder>/ (directory created, empty)
|
||||
```
|
||||
|
||||
The script refuses to clobber existing files, so it is safe to rerun.
|
||||
|
||||
After scaffolding, drop the anatomy SVGs into the `public/species/...`
|
||||
folder, fill in `pathologies.json`, and the species shows up
|
||||
automatically in the species picker — see "How auto-discovery works"
|
||||
below.
|
||||
|
||||
---
|
||||
|
||||
## How auto-discovery works
|
||||
|
||||
`src/domain/species/registry.ts` no longer hard-codes species. It uses
|
||||
Vite's `import.meta.glob`:
|
||||
|
||||
```ts
|
||||
const modules = import.meta.glob<{ default: SpeciesManifest }>(
|
||||
'./*/index.ts',
|
||||
{ eager: true },
|
||||
)
|
||||
```
|
||||
|
||||
Every `src/domain/species/<id>/index.ts` that **default-exports** a
|
||||
`SpeciesManifest` is picked up at build time and registered by its
|
||||
`manifest.id`. Duplicates are warned about and the first one wins.
|
||||
|
||||
What this means in practice:
|
||||
|
||||
- **No registry edit needed.** Drop a properly-structured species
|
||||
folder and it appears in `AnimalForm`, `getSpecies(id)`, the editor,
|
||||
and the PDF exporter.
|
||||
- **The `id` must be unique.** Two folders default-exporting manifests
|
||||
with the same `id` triggers a console warning and the later module
|
||||
is ignored.
|
||||
- **A missing default export is silent.** If you forget
|
||||
`export default`, the species is invisible. The scaffold script
|
||||
emits the default export for you.
|
||||
|
||||
---
|
||||
|
||||
## Manual setup (without the script)
|
||||
|
||||
The scaffold script just writes the files below. If you'd rather do it
|
||||
by hand, the same workflow applies — make sure your `index.ts`
|
||||
default-exports the manifest so auto-discovery sees it.
|
||||
|
||||
### 1. Author the anatomy SVGs
|
||||
|
||||
All SVG assets must conform to
|
||||
[`docs/ANATOMY-SVG-CONVENTION.md`](./ANATOMY-SVG-CONVENTION.md). Every
|
||||
clickable element must carry:
|
||||
|
||||
| Attribute | Required | Notes |
|
||||
| -------------------------- | -------- | -------------------------------------------------------------------------------------- |
|
||||
| `data-anno-id` | yes | Stable identifier, unique within the SVG. The renderer treats it as opaque. |
|
||||
| `data-anno-name-fr` | yes | French anatomical label. |
|
||||
| `data-anno-name-en` | yes | English anatomical label. |
|
||||
| `data-anno-category` | yes | Must be one of the 7 valid values defined in [`ANATOMY-SVG-CONVENTION.md`](./ANATOMY-SVG-CONVENTION.md) (`articulation`, `charniere`, `spine-zone`, `os`, `os-overlay`, `head`, `cadran-crane`). Parser throws `SvgConventionError` on unknown values. |
|
||||
| `data-anno-opens-detail` | no | Key of a detail popup SVG. Must match a key in the manifest's `details` map. |
|
||||
| `data-anno-special` | no | Behavior hint. `vertebral-precision` opens the VertebraPicker on click. |
|
||||
|
||||
Drop the SVGs into:
|
||||
|
||||
```
|
||||
public/species/<assetFolder>/<Main>.svg
|
||||
public/species/<assetFolder>/<Main>_<detail>.svg
|
||||
```
|
||||
|
||||
The `public/` prefix is implicit at runtime — the manifest references
|
||||
files by absolute path starting with `/species/...`.
|
||||
|
||||
### 2. Create the species manifest
|
||||
|
||||
`src/domain/species/<id>/index.ts`:
|
||||
|
||||
```ts
|
||||
import type { SpeciesManifest } from '@/domain/species/types'
|
||||
import { CANINE_VERTEBRAL_FORMULA } from './vertebrae'
|
||||
|
||||
const canine: SpeciesManifest = {
|
||||
id: 'canine',
|
||||
labelFr: 'Chien',
|
||||
labelEn: 'Dog',
|
||||
mainSvg: '/species/canine/Dog.svg',
|
||||
details: {
|
||||
head: '/species/canine/Dog_head.svg',
|
||||
},
|
||||
vertebralFormula: CANINE_VERTEBRAL_FORMULA,
|
||||
findings: () => import('./pathologies'),
|
||||
}
|
||||
|
||||
export default canine // <- required for auto-discovery
|
||||
```
|
||||
|
||||
`details` keys must match every distinct `data-anno-opens-detail`
|
||||
attribute used in the main SVG. There is no filename convention — the
|
||||
mapping is explicit through this object.
|
||||
|
||||
### 3. Provide the vertebral formula
|
||||
|
||||
`src/domain/species/<id>/vertebrae.ts`:
|
||||
|
||||
```ts
|
||||
import type { VertebralFormula } from '@/domain/species/types'
|
||||
|
||||
export const CANINE_VERTEBRAL_FORMULA: VertebralFormula = {
|
||||
C: 7,
|
||||
T: 13,
|
||||
L: 7,
|
||||
S: 3,
|
||||
Cd: 20,
|
||||
}
|
||||
```
|
||||
|
||||
Cap `Cd` at a sensible maximum (caudal counts vary heavily across
|
||||
individuals).
|
||||
|
||||
### 4. Provide the findings catalog
|
||||
|
||||
Two files:
|
||||
|
||||
`src/domain/species/<id>/pathologies.json` — authored tree of zones,
|
||||
categories, sub-categories and leaves. The shape is defined by
|
||||
`src/domain/schema/findings.ts`, and the full authoring contract
|
||||
(structural rules, taxonomy patterns, v2.0 vet-referral policy,
|
||||
changelog) lives in
|
||||
[`docs/PATHOLOGIES-FORMAT.md`](./PATHOLOGIES-FORMAT.md). The scaffold
|
||||
script ships a minimal skeleton; populate the `zones` map by mirroring
|
||||
the equine reference at `src/domain/species/equine/pathologies.json`.
|
||||
|
||||
`src/domain/species/<id>/pathologies.ts` — loader:
|
||||
|
||||
```ts
|
||||
import {
|
||||
SpeciesFindingsSchema,
|
||||
type SpeciesFindings,
|
||||
} from '@/domain/schema/findings'
|
||||
import data from './pathologies.json'
|
||||
|
||||
const FINDINGS: SpeciesFindings = SpeciesFindingsSchema.parse(data)
|
||||
|
||||
export default FINDINGS
|
||||
```
|
||||
|
||||
The Zod parse runs on first import and **fails fast** if the JSON
|
||||
violates the schema (missing labels, malformed children, empty
|
||||
disclaimer, etc.). That is your validation gate — there is no separate
|
||||
lint step to run.
|
||||
|
||||
---
|
||||
|
||||
## Updating the findings JSON
|
||||
|
||||
The JSON is bundled into the app at build time, so updates flow
|
||||
through normal dev/deploy paths:
|
||||
|
||||
- **In dev (`pnpm dev`)**: edit the JSON, Vite HMR reloads the module,
|
||||
the editor picks up the new tree on the next interaction. A bad
|
||||
edit fails loudly because the Zod parse runs at module load.
|
||||
- **In prod**: rebuild and redeploy. The findings tree is statically
|
||||
imported and there is no backend serving JSON at runtime.
|
||||
|
||||
Snapshots in already-exported PDFs are unaffected — observations carry
|
||||
`labelFrSnapshot` / `labelEnSnapshot` copied at selection time, so
|
||||
catalog edits cannot retroactively rewrite past reports.
|
||||
|
||||
---
|
||||
|
||||
## How findings link back to clicked SVG zones
|
||||
|
||||
The catalog keys observations by stable JSON zone ids (e.g.
|
||||
`sphenoid`). SVG hitboxes carry opaque generator ids
|
||||
(e.g. `point-mpbymcln`). The bridge is the **FR/EN label** parsed from
|
||||
`data-anno-name-fr` / `data-anno-name-en`, matched against the JSON's
|
||||
`zone.name_fr` / `zone.name_en` via the fuzzy matcher in
|
||||
`src/lib/zoneMatch.ts`.
|
||||
|
||||
In practice you do not need to make the SVG ids meaningful; you just
|
||||
need each zone's label to match its catalog entry under normalization
|
||||
(lowercase + strip accents + drop non-alphanumerics) or be close
|
||||
enough that Levenshtein finds it.
|
||||
|
||||
---
|
||||
|
||||
## CI gate before merging
|
||||
|
||||
```bash
|
||||
pnpm lint
|
||||
pnpm typecheck
|
||||
pnpm test:run
|
||||
pnpm build
|
||||
```
|
||||
|
||||
All four must be green before the new species lands.
|
||||
@@ -1,179 +0,0 @@
|
||||
# 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.
|
||||
Reference in new issue
Block a user