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>
7.6 KiB
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:
- SVG convention — new
data-anno-lateralattribute marks zones as bilateral or unpaired - Report schema — new
sidefield onObservationZonerecords which side - 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
bilateralorunpaired. Any other value →SvgConventionError. - If absent → treated as
unpairedat the application level (not by the parser — parser setsundefined, app code defaults).
Doc update
docs/ANATOMY-SVG-CONVENTION.md gains a row in the optional attributes table.
2. Schema Changes
ObservationZone
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:
sideis present only when the bone is bilateral- Unpaired zones never carry
side - Two zones with same
boneIdbut differentsidevalues are valid (left knee + right knee in same observation) - No schema version bump —
sideis additive and optional; old reports parse cleanly
Bone interface
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:
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'):
-
LateralityPicker modal opens with three options:
- Gauche / Left
- Droite / Right
- Les deux / Both
-
Selection behavior:
- "Left" → adds
ObservationZone { boneId, side: 'left' } - "Right" → adds
ObservationZone { boneId, side: 'right' } - "Both" → adds two entries:
{ boneId, side: 'left' }+{ boneId, side: 'right' }
- "Left" → adds
-
Duplicate prevention: if a zone with the same
boneId + side + detailSourceIdalready exists in the active observation, skip silently. -
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
Dialogcomponent for modal shell - Three
Buttoncomponents 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:
<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-lateralfrom selected element on select - Writes
data-anno-lateralattribute 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
sidefield 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 |