docs(plans): add laterality support implementation plan

10 tasks: schema, parser, i18n, LateralityPicker, EditorRoute integration,
ObservationCard display, PDF output, SVG editor dropdown, docs, verification.

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:12:06 +02:00
1 parent 880de17dbe
commit c73af46c33
1 file changed
+738
@@ -0,0 +1,738 @@
# Laterality Support Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Add bilateral/unpaired laterality to anatomical zones so practitioners can specify left/right side on bilateral structures.
**Architecture:** New `data-anno-lateral` SVG attribute parsed into `Bone.lateral`. New `side` field on `ObservationZone` schema. LateralityPicker modal triggered on bilateral zone clicks. Side displayed in zone badges and PDF output. SVG editor gets a laterality dropdown.
**Tech Stack:** React 19, TypeScript strict, Zustand 5, Zod 3, Tailwind v4, pdf-lib, vitest
---
### Task 1: Schema + Bone Type — Add `side` to ObservationZone and `lateral` to Bone
**Files:**
- Modify: `src/domain/schema/observation.ts`
- Modify: `src/anatomy/types.ts`
- Test: `tests/unit/schema.observation.test.ts`
- [ ] **Step 1: Write failing tests for LateralSideSchema and side field**
Add to `tests/unit/schema.observation.test.ts`:
```ts
import {
ObservationSchema,
ObservationZoneSchema,
LateralSideSchema,
VertebraSchema,
SeveritySchema,
FindingSchema,
} from '@/domain/schema/observation'
describe('LateralSideSchema', () => {
it('accepts left and right', () => {
expect(LateralSideSchema.parse('left')).toBe('left')
expect(LateralSideSchema.parse('right')).toBe('right')
})
it('rejects unknown side', () => {
expect(() => LateralSideSchema.parse('both')).toThrow()
expect(() => LateralSideSchema.parse('')).toThrow()
})
})
describe('ObservationZoneSchema with side', () => {
it('accepts a zone without side (unpaired)', () => {
expect(() => ObservationZoneSchema.parse({ boneId: 'sternum' })).not.toThrow()
})
it('accepts a zone with side left', () => {
const parsed = ObservationZoneSchema.parse({ boneId: 'knee', side: 'left' })
expect(parsed.side).toBe('left')
})
it('accepts a zone with side right', () => {
const parsed = ObservationZoneSchema.parse({ boneId: 'knee', side: 'right' })
expect(parsed.side).toBe('right')
})
it('accepts two zones with same boneId but different sides', () => {
const obs = {
id: 'obs-1',
zones: [
{ boneId: 'knee', side: 'left' },
{ boneId: 'knee', side: 'right' },
],
findings: [],
freeTextFindings: [],
comment: '',
}
expect(() => ObservationSchema.parse(obs)).not.toThrow()
})
})
```
- [ ] **Step 2: Run tests to verify they fail**
Run: `pnpm test:run -- tests/unit/schema.observation.test.ts`
Expected: FAIL — `LateralSideSchema` is not exported
- [ ] **Step 3: Add LateralSideSchema and side field to observation.ts**
In `src/domain/schema/observation.ts`, add after the `VertebraSchema` definition:
```ts
export const LateralSideSchema = z.enum(['left', 'right'])
export type LateralSide = z.infer<typeof LateralSideSchema>
```
Add `side` to `ObservationZoneSchema`:
```ts
export const ObservationZoneSchema = z.object({
boneId: z.string().min(1),
detailSourceId: z.string().optional(),
vertebrae: z.array(VertebraSchema).optional(),
side: LateralSideSchema.optional(),
})
```
- [ ] **Step 4: Add `lateral` field to Bone interface**
In `src/anatomy/types.ts`, add to `Bone` interface after `special?`:
```ts
lateral?: 'bilateral' | 'unpaired'
```
- [ ] **Step 5: Run tests to verify they pass**
Run: `pnpm test:run -- tests/unit/schema.observation.test.ts`
Expected: ALL PASS
- [ ] **Step 6: Run full typecheck**
Run: `pnpm typecheck`
Expected: No errors
- [ ] **Step 7: Commit**
```bash
git add src/domain/schema/observation.ts src/anatomy/types.ts tests/unit/schema.observation.test.ts
git commit -m "feat(schema): add LateralSideSchema and Bone.lateral for laterality support"
```
---
### Task 2: SVG Parser — Read `data-anno-lateral` attribute
**Files:**
- Modify: `src/anatomy/svgConvention.ts`
- Test: `tests/unit/anatomy.svgConvention.test.ts`
- [ ] **Step 1: Write failing tests for lateral parsing**
Add to `tests/unit/anatomy.svgConvention.test.ts`, update the `FIXTURE` and add tests:
Update `FIXTURE` — add a bilateral element:
```xml
<circle data-anno-id="point-knee" data-anno-name-fr="Genou" data-anno-name-en="Knee"
data-anno-category="articulations" data-anno-lateral="bilateral" />
```
Add tests:
```ts
it('captures data-anno-lateral when present', () => {
const map = parseSvgBones(svgFromString(FIXTURE))
expect(map.get('point-knee')?.lateral).toBe('bilateral')
})
it('leaves lateral undefined when attribute absent', () => {
const map = parseSvgBones(svgFromString(FIXTURE))
expect(map.get('point-shoulder')?.lateral).toBeUndefined()
})
```
- [ ] **Step 2: Run tests to verify they fail**
Run: `pnpm test:run -- tests/unit/anatomy.svgConvention.test.ts`
Expected: FAIL — `lateral` is undefined for knee
- [ ] **Step 3: Update parseSvgBones to read data-anno-lateral**
In `src/anatomy/svgConvention.ts`, in `parseSvgBones()`, add after the `special` read:
```ts
const lateral = el.getAttribute('data-anno-lateral') as
| 'bilateral'
| 'unpaired'
| undefined ?? undefined
```
In the `else` branch (new Bone creation), add `lateral` to the object:
```ts
map.set(id, {
id,
fr,
en,
category,
opensDetail,
special,
lateral,
els: [el],
})
```
In the `existing` merge branch, add:
```ts
if (lateral && !existing.lateral) {
existing.lateral = lateral
}
```
- [ ] **Step 4: Run tests to verify they pass**
Run: `pnpm test:run -- tests/unit/anatomy.svgConvention.test.ts`
Expected: ALL PASS
- [ ] **Step 5: Commit**
```bash
git add src/anatomy/svgConvention.ts tests/unit/anatomy.svgConvention.test.ts
git commit -m "feat(anatomy): parse data-anno-lateral attribute from SVG"
```
---
### Task 3: i18n — Add laterality translation keys
**Files:**
- Modify: `src/i18n/fr.ts`
- Modify: `src/i18n/en.ts`
- Test: `tests/unit/i18n.dicts.test.ts` (existing test verifies key parity)
- [ ] **Step 1: Add keys to fr.ts**
Add after the vertebra section in `src/i18n/fr.ts`:
```ts
// laterality
'lateral.which_side': 'Quel côté ?',
'lateral.left': 'Gauche',
'lateral.right': 'Droite',
'lateral.both': 'Les deux',
'lateral.left_short': 'G',
'lateral.right_short': 'D',
'lateral.bilateral': 'Bilatéral',
'lateral.unpaired': 'Impair',
```
- [ ] **Step 2: Add keys to en.ts**
Add after the vertebra section in `src/i18n/en.ts`:
```ts
// laterality
'lateral.which_side': 'Which side?',
'lateral.left': 'Left',
'lateral.right': 'Right',
'lateral.both': 'Both',
'lateral.left_short': 'L',
'lateral.right_short': 'R',
'lateral.bilateral': 'Bilateral',
'lateral.unpaired': 'Unpaired',
```
- [ ] **Step 3: Run i18n key parity test**
Run: `pnpm test:run -- tests/unit/i18n.dicts.test.ts`
Expected: PASS (both dicts have same keys)
- [ ] **Step 4: Commit**
```bash
git add src/i18n/fr.ts src/i18n/en.ts
git commit -m "feat(i18n): add laterality translation keys (FR/EN)"
```
---
### Task 4: LateralityPicker Component
**Files:**
- Create: `src/components/observation/LateralityPicker.tsx`
- [ ] **Step 1: Create LateralityPicker component**
Create `src/components/observation/LateralityPicker.tsx`:
```tsx
import Dialog from '@/components/ui/Dialog'
import Button from '@/components/ui/Button'
import type { LateralSide } from '@/domain/schema/observation'
import { useT } from '@/i18n/useT'
export interface LateralityPickerProps {
open: boolean
onClose: () => void
onSelect: (sides: LateralSide[]) => void
title: string
/** Sides already present in the active observation for this boneId. */
existingSides: LateralSide[]
}
export default function LateralityPicker({
open,
onClose,
onSelect,
title,
existingSides,
}: LateralityPickerProps) {
const t = useT()
const hasLeft = existingSides.includes('left')
const hasRight = existingSides.includes('right')
return (
<Dialog open={open} onClose={onClose} title={title} size="sm">
<div className="space-y-4">
<p className="text-sm text-[var(--color-ink-muted)]">
{t('lateral.which_side')}
</p>
<div className="flex gap-3 justify-center">
<Button
variant={hasLeft ? 'ghost' : 'default'}
disabled={hasLeft}
onClick={() => onSelect(['left'])}
>
{t('lateral.left')}
</Button>
<Button
variant={hasRight ? 'ghost' : 'default'}
disabled={hasRight}
onClick={() => onSelect(['right'])}
>
{t('lateral.right')}
</Button>
<Button
variant={hasLeft && hasRight ? 'ghost' : 'default'}
disabled={hasLeft && hasRight}
onClick={() => {
const sides: LateralSide[] = []
if (!hasLeft) sides.push('left')
if (!hasRight) sides.push('right')
onSelect(sides)
}}
>
{t('lateral.both')}
</Button>
</div>
</div>
</Dialog>
)
}
```
- [ ] **Step 2: Run typecheck**
Run: `pnpm typecheck`
Expected: No errors
- [ ] **Step 3: Commit**
```bash
git add src/components/observation/LateralityPicker.tsx
git commit -m "feat(ui): add LateralityPicker modal component"
```
---
### Task 5: EditorRoute — Integrate LateralityPicker into zone click flow
**Files:**
- Modify: `src/app/routes/EditorRoute.tsx`
- [ ] **Step 1: Add laterality state and imports**
Add imports at top of `EditorRoute.tsx`:
```ts
import LateralityPicker from '@/components/observation/LateralityPicker'
import type { LateralSide } from '@/domain/schema/observation'
```
Add state after `vertebraTarget` state:
```ts
const [lateralTarget, setLateralTarget] = useState<{
boneId: string
detailSourceId?: string
} | null>(null)
```
- [ ] **Step 2: Modify onZoneClick to handle bilateral zones**
In `onZoneClick()`, after the `vertebral-precision` block and before the unpaired toggle logic, add:
```ts
if (bone.lateral === 'bilateral') {
setLateralTarget({
boneId,
...(detailSourceId ? { detailSourceId } : {}),
})
return
}
```
- [ ] **Step 3: Add LateralityPicker to JSX**
Add before the closing `</main>` tag, after the VertebraPicker block:
```tsx
{lateralTarget && activeObs && (
<LateralityPicker
open
onClose={() => setLateralTarget(null)}
title={boneLabel(
allBones.get(lateralTarget.boneId),
locale,
lateralTarget.boneId,
)}
existingSides={
activeObs.zones
.filter(
(z) =>
z.boneId === lateralTarget.boneId &&
z.detailSourceId === lateralTarget.detailSourceId &&
z.side,
)
.map((z) => z.side!) as LateralSide[]
}
onSelect={(sides) => {
const fresh =
useReportStore.getState().report?.observations[activeIndex]
if (!fresh) {
setLateralTarget(null)
return
}
let nextZones = [...fresh.zones]
for (const side of sides) {
const exists = nextZones.some(
(z) =>
z.boneId === lateralTarget.boneId &&
z.detailSourceId === lateralTarget.detailSourceId &&
z.side === side,
)
if (!exists) {
nextZones.push({
boneId: lateralTarget.boneId,
...(lateralTarget.detailSourceId
? { detailSourceId: lateralTarget.detailSourceId }
: {}),
side,
})
}
}
updateObservation(activeIndex, { ...fresh, zones: nextZones })
setLateralTarget(null)
}}
/>
)}
```
- [ ] **Step 4: Handle re-click toggle for bilateral zones**
The current flow in `onZoneClick` for the bilateral case:
- If both sides already exist → remove both (toggle off)
- If one or zero sides → open picker
Update the bilateral block:
```ts
if (bone.lateral === 'bilateral') {
const sidesPresent = activeObs.zones
.filter(
(z) =>
z.boneId === boneId &&
z.detailSourceId === detailSourceId,
)
.map((z) => z.side)
.filter(Boolean) as LateralSide[]
if (sidesPresent.includes('left') && sidesPresent.includes('right')) {
const nextZones = activeObs.zones.filter(
(z) =>
!(z.boneId === boneId && z.detailSourceId === detailSourceId),
)
updateObservation(activeIndex, { ...activeObs, zones: nextZones })
return
}
setLateralTarget({
boneId,
...(detailSourceId ? { detailSourceId } : {}),
})
return
}
```
- [ ] **Step 5: Run typecheck**
Run: `pnpm typecheck`
Expected: No errors
- [ ] **Step 6: Commit**
```bash
git add src/app/routes/EditorRoute.tsx
git commit -m "feat(editor): integrate LateralityPicker in zone click flow"
```
---
### Task 6: ObservationCard — Display side in zone badges
**Files:**
- Modify: `src/components/observation/ObservationCard.tsx`
- [ ] **Step 1: Update describeZone to show side suffix**
In `ObservationCard.tsx`, update the `describeZone` function:
```ts
function describeZone(
z: ObservationZone,
bones: Map<string, Bone>,
locale: Locale,
t: (key: string) => string,
): string {
const label = boneLabel(bones.get(z.boneId), locale, z.boneId)
if (z.vertebrae?.length) {
const vs = z.vertebrae
.map((v: Vertebra) => `${v.region}${v.index}`)
.join(', ')
return `${label} (${vs})`
}
if (z.side) {
const sideLabel = t(
z.side === 'left' ? 'lateral.left_short' : 'lateral.right_short',
)
return `${label} (${sideLabel})`
}
return label
}
```
- [ ] **Step 2: Update describeZone call sites to pass t**
In the JSX, update the two places `describeZone` is called:
In the zone badges list:
```tsx
{describeZone(z, bones, locale, t)}
```
- [ ] **Step 3: Run typecheck**
Run: `pnpm typecheck`
Expected: No errors
- [ ] **Step 4: Commit**
```bash
git add src/components/observation/ObservationCard.tsx
git commit -m "feat(ui): display laterality side in zone badges"
```
---
### Task 7: PDF Output — Include side in zone labels
**Files:**
- Modify: `src/pdf/render/observationPage.ts`
- [ ] **Step 1: Update zone label rendering**
In `addObservationPage()`, find the `zonesText` construction (around line 369-379). Update to include side:
```ts
const zonesText = observation.zones
.map((z) => {
const pair = zoneLabels.get(z.boneId)
const label = pair
? (locale === 'en' ? pair.en || pair.fr : pair.fr || pair.en) || z.boneId
: z.boneId
const v = z.vertebrae?.length
? ` (${z.vertebrae.map((x) => `${x.region}${x.index}`).join(', ')})`
: ''
const side = z.side
? ` (${dict[z.side === 'left' ? 'lateral.left' : 'lateral.right']})`
: ''
return `${label}${v}${side}`
})
.join(' · ')
```
- [ ] **Step 2: Run typecheck**
Run: `pnpm typecheck`
Expected: No errors
- [ ] **Step 3: Commit**
```bash
git add src/pdf/render/observationPage.ts
git commit -m "feat(pdf): include laterality side in zone labels"
```
---
### Task 8: SVG Editor — Add laterality dropdown
**Files:**
- Modify: `src/app/routes/SvgEditorRoute.tsx`
- Modify: `src/i18n/fr.ts`
- Modify: `src/i18n/en.ts`
- [ ] **Step 1: Add SVG editor i18n keys**
In `src/i18n/fr.ts`, add:
```ts
'svg_editor.lateral': 'Latéralité',
'svg_editor.lateral_unpaired': 'Impair (pas de côté)',
'svg_editor.lateral_bilateral': 'Bilatéral (gauche / droite)',
```
In `src/i18n/en.ts`, add:
```ts
'svg_editor.lateral': 'Laterality',
'svg_editor.lateral_unpaired': 'Unpaired (no side)',
'svg_editor.lateral_bilateral': 'Bilateral (left / right)',
```
- [ ] **Step 2: Add dropdown to SvgEditorRoute JSX**
In `SvgEditorRoute.tsx`, inside the `svg-editor-osteo-fields` div, after the category `<select>`, add:
```tsx
<label>{t('svg_editor.lateral')}</label>
<select id="svg-editor-edit-lateral">
<option value="">{t('svg_editor.lateral_unpaired')}</option>
<option value="bilateral">{t('svg_editor.lateral_bilateral')}</option>
</select>
```
- [ ] **Step 3: Wire up event listener in initSvgEditor**
In `setupGlobalListeners()`, add the lateral select to the change listener array:
```ts
;['svg-editor-edit-fr', 'svg-editor-edit-en', 'svg-editor-edit-category', 'svg-editor-edit-lateral'].forEach(
(id) => {
getEl(id).addEventListener('change', applyEdit, sig)
},
)
```
- [ ] **Step 4: Read lateral in showEditPanel**
In `showEditPanel()`, after reading category, add:
```ts
;(getEl('svg-editor-edit-lateral') as HTMLSelectElement).value =
svgEl.getAttribute('data-anno-lateral') || ''
```
- [ ] **Step 5: Write lateral in applyEdit**
In `applyEdit()`, after reading `cat`, add:
```ts
const lateral = (getEl('svg-editor-edit-lateral') as HTMLSelectElement).value
```
In the siblings loop, inside the non-opens-detail branch (where `data-anno-name-fr` etc. are set), add after the special attribute logic:
```ts
if (lateral) {
s.setAttribute('data-anno-lateral', lateral)
} else {
s.removeAttribute('data-anno-lateral')
}
```
- [ ] **Step 6: Propagate lateral when creating new elements**
In `addCircleAt()`, after setting `data-anno-special` on both `hit` and `vis`, add for each:
```ts
if (CATEGORIES[cat]?.lateral) hit.setAttribute('data-anno-lateral', CATEGORIES[cat].lateral!)
```
Wait — categories don't carry lateral. Lateral is per-element, not per-category. New elements start as unpaired (no attribute). The user sets it via the edit panel. No change needed for addCircleAt/finalizePolygon.
- [ ] **Step 7: Run typecheck and i18n test**
Run: `pnpm typecheck && pnpm test:run -- tests/unit/i18n.dicts.test.ts`
Expected: No errors, i18n parity PASS
- [ ] **Step 8: Commit**
```bash
git add src/app/routes/SvgEditorRoute.tsx src/i18n/fr.ts src/i18n/en.ts
git commit -m "feat(editor): add laterality dropdown to SVG editor"
```
---
### Task 9: Documentation — Update ANATOMY-SVG-CONVENTION.md
**Files:**
- Modify: `docs/ANATOMY-SVG-CONVENTION.md`
- [ ] **Step 1: Add data-anno-lateral to optional attributes table**
In the "Optional data attributes" table, add a row:
```markdown
| `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. |
```
- [ ] **Step 2: Commit**
```bash
git add docs/ANATOMY-SVG-CONVENTION.md
git commit -m "docs(anatomy): document data-anno-lateral attribute"
```
---
### Task 10: Full Verification
- [ ] **Step 1: Run full test suite**
Run: `pnpm test:run`
Expected: ALL PASS
- [ ] **Step 2: Run typecheck**
Run: `pnpm typecheck`
Expected: No errors
- [ ] **Step 3: Run lint**
Run: `pnpm lint`
Expected: No errors
- [ ] **Step 4: Build**
Run: `pnpm build`
Expected: Build succeeds