docs(specs): add laterality support design spec

Defines per-zone bilateral/unpaired SVG attribute, ObservationZone.side
schema field, LateralityPicker UI flow, and SVG editor integration.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Bastien ChanotandClaude Opus 4.6 committed 2026-05-23 22:09:50 +02:00
1 parent a73d8da263
commit 880de17dbe
1 file changed
+234
@@ -0,0 +1,234 @@
# Laterality Support — Design Spec
**Date**: 2026-05-23
**Status**: Approved
**Approach**: A — per-zone SVG attribute + inline side picker + separate observation entries
---
## Problem
Anatomical zones have no laterality concept. A practitioner clicking "Genou" (knee) creates one observation zone without specifying left or right. Bilateral structures (knee, hip, shoulder) need side differentiation; midline/unpaired structures (spine, sternum) do not.
## Solution Overview
Three layers:
1. **SVG convention** — new `data-anno-lateral` attribute marks zones as bilateral or unpaired
2. **Report schema** — new `side` field on `ObservationZone` records which side
3. **UI** — LateralityPicker modal when clicking bilateral zones; badge display shows side
Backward-compatible: missing attribute = unpaired, `side` field is optional.
---
## 1. SVG Convention
New optional attribute on annotated elements:
| Attribute | Values | Default when absent |
|---|---|---|
| `data-anno-lateral` | `bilateral` \| `unpaired` | `unpaired` |
- `bilateral`: zone has left and right instances (e.g. knee, hip, shoulder)
- `unpaired`: zone has no laterality (e.g. sternum, sacrum) or laterality is not relevant
The parser reads and forwards this attribute like `data-anno-special` — optional, opaque string. The `Bone` interface gains a `lateral` field.
### Validation
- If present, value must be `bilateral` or `unpaired`. Any other value → `SvgConventionError`.
- If absent → treated as `unpaired` at the application level (not by the parser — parser sets `undefined`, app code defaults).
### Doc update
`docs/ANATOMY-SVG-CONVENTION.md` gains a row in the optional attributes table.
---
## 2. Schema Changes
### ObservationZone
```ts
export const LateralSideSchema = z.enum(['left', 'right'])
export type LateralSide = z.infer<typeof LateralSideSchema>
export const ObservationZoneSchema = z.object({
boneId: z.string().min(1),
detailSourceId: z.string().optional(),
vertebrae: z.array(VertebraSchema).optional(),
side: LateralSideSchema.optional(),
})
```
Rules:
- `side` is present only when the bone is bilateral
- Unpaired zones never carry `side`
- Two zones with same `boneId` but different `side` values are valid (left knee + right knee in same observation)
- No schema version bump — `side` is additive and optional; old reports parse cleanly
### Bone interface
```ts
export interface Bone {
id: string
fr: string
en: string
category: BoneCategory
opensDetail?: string
special?: string
lateral?: 'bilateral' | 'unpaired' // NEW
els: Element[]
}
```
---
## 3. SVG Parser Changes
`parseSvgBones()` reads `data-anno-lateral` from SVG elements and sets `Bone.lateral`:
```ts
const lateral = el.getAttribute('data-anno-lateral') ?? undefined
```
Merging logic (multiple elements sharing same `data-anno-id`): first non-undefined `lateral` value wins, same pattern as `special` and `opensDetail`.
No validation of the value in the parser — validation happens at the convention level if desired. The parser is permissive (accepts any string); the application layer checks for known values.
---
## 4. UX Flow — LateralityPicker
### Trigger
When practitioner clicks a bilateral zone (`bone.lateral === 'bilateral'`):
1. **LateralityPicker** modal opens with three options:
- Gauche / Left
- Droite / Right
- Les deux / Both
2. Selection behavior:
- "Left" → adds `ObservationZone { boneId, side: 'left' }`
- "Right" → adds `ObservationZone { boneId, side: 'right' }`
- "Both" → adds two entries: `{ boneId, side: 'left' }` + `{ boneId, side: 'right' }`
3. Duplicate prevention: if a zone with the same `boneId + side + detailSourceId` already exists in the active observation, skip silently.
4. Re-click behavior: if the zone already has one or both sides in the observation, the picker opens again so the user can add the missing side. If both sides already exist, clicking removes both (toggle off — matching current toggle behavior for unpaired zones).
### Component
`src/components/observation/LateralityPicker.tsx`
- Reuses `Dialog` component for modal shell
- Three `Button` components for the choices
- Receives `onSelect(sides: LateralSide[])` callback
- Small, focused modal — not a full-screen overlay
### Integration point
`EditorRoute.onZoneClick()` — after the `opensDetail` check and `vertebral-precision` check, before the toggle logic:
```
if bone.lateral === 'bilateral' → open LateralityPicker
→ onSelect callback adds zone(s) with side
else → existing toggle logic (unpaired zone)
```
---
## 5. Zone Badge Display
In `ObservationCard`, the `describeZone()` function appends a side suffix for bilateral zones:
- FR: `Genou (G)` for left, `Genou (D)` for right
- EN: `Knee (L)` for left, `Knee (R)` for right
The short labels come from i18n keys `lateral.left_short` / `lateral.right_short`.
Format: `{zoneName} ({sideShort})`
---
## 6. SVG Editor Changes
In the edit panel (`svg-editor-osteo-fields`), a new select dropdown after the category select:
```html
<label>Latéralité / Laterality</label>
<select id="svg-editor-edit-lateral">
<option value="">Impair / Unpaired</option>
<option value="bilateral">Bilatéral / Bilateral</option>
</select>
```
Behavior:
- Reads `data-anno-lateral` from selected element on select
- Writes `data-anno-lateral` attribute on change (removes attribute if "unpaired" selected)
- Propagates to sibling elements sharing same `data-anno-id` (same pattern as category/name propagation)
- Exported SVG includes the attribute
### Backward compatibility
Existing SVGs loaded in the editor: zones without `data-anno-lateral` show "Impair" (default). User can change to "Bilatéral" and re-export.
---
## 7. PDF Output
Zone labels in PDF include side when present:
- FR: `Genou (Gauche)`, `Genou (Droit)`
- EN: `Knee (Left)`, `Knee (Right)`
Uses full side name (not abbreviation) for PDF clarity.
The `describeZone()` helper used in PDF rendering checks `zone.side` and appends the localized label.
---
## 8. i18n Keys
New keys in `src/i18n/fr.ts` and `src/i18n/en.ts`:
| Key | FR | EN |
|---|---|---|
| `lateral.which_side` | Quel côté ? | Which side? |
| `lateral.left` | Gauche | Left |
| `lateral.right` | Droite | Right |
| `lateral.both` | Les deux | Both |
| `lateral.left_short` | G | L |
| `lateral.right_short` | D | R |
| `lateral.bilateral` | Bilatéral | Bilateral |
| `lateral.unpaired` | Impair | Unpaired |
---
## 9. Scope Exclusions
- No changes to findings tree — findings are zone-level, same pathologies apply to both sides
- No SVG visual differentiation between left/right — same zone highlights for both sides
- No auto-detection of laterality from zone names
- No report schema version bump — additive optional field
- No changes to PDF attachment format — JSON includes `side` field naturally
---
## 10. Files Touched
| File | Change |
|---|---|
| `src/anatomy/types.ts` | Add `lateral` to `Bone` interface |
| `src/anatomy/svgConvention.ts` | Read `data-anno-lateral` in parser |
| `src/domain/schema/observation.ts` | Add `LateralSideSchema`, `side` field |
| `src/components/observation/LateralityPicker.tsx` | NEW — modal component |
| `src/components/observation/ObservationCard.tsx` | Update `describeZone()` |
| `src/app/routes/EditorRoute.tsx` | Integrate LateralityPicker in click flow |
| `src/app/routes/SvgEditorRoute.tsx` | Add lateral dropdown in edit panel |
| `src/i18n/fr.ts` | Add lateral keys |
| `src/i18n/en.ts` | Add lateral keys |
| `src/pdf/render/observationPage.ts` | Update zone label rendering |
| `docs/ANATOMY-SVG-CONVENTION.md` | Document `data-anno-lateral` |
| `tests/unit/observation.test.ts` | Test side field parsing |