Purged from docs/superpowers by the gitflow finish of step 1 (BDR-065); that path is purged at every finish, so the records live under docs/history/superpowers/ instead. References updated.
388 lines
13 KiB
Markdown
388 lines
13 KiB
Markdown
# Pathology Editor — Design Spec
|
|
|
|
**Date**: 2026-05-22
|
|
**Status**: Draft
|
|
**Scope**: Standalone HTML tool for editing species pathology JSON via SVG-based zone selection
|
|
|
|
---
|
|
|
|
## 1. Overview
|
|
|
|
Single-file standalone HTML tool (`pathology-editor.html` at project root) that lets users visually select anatomical zones on an SVG and edit the corresponding pathology tree in the species JSON. Same architectural pattern as `editor.html` (SVG editor): vanilla JS/CSS, no build step, no dependencies.
|
|
|
|
The tool never modifies source files. It works on an in-memory copy and exports a downloadable JSON file.
|
|
|
|
---
|
|
|
|
## 2. Layout
|
|
|
|
Two-panel horizontal layout, identical to SVG editor:
|
|
|
|
| Panel | Width | Content |
|
|
|-------|-------|---------|
|
|
| Left (canvas) | flex: 1 | SVG display, click-to-select zones |
|
|
| Right (sidebar) | 380px | Source picker → zone info → tree editor → export |
|
|
|
|
Sidebar is scrollable. Canvas contains the SVG with auto-viewBox (same logic as `editor.html`).
|
|
|
|
---
|
|
|
|
## 3. Source Selection
|
|
|
|
On launch, sidebar shows source picker with two modes:
|
|
|
|
### 3a. Pre-wired list
|
|
|
|
Two-step selection:
|
|
1. **Species dropdown** — lists registered species (MVP: "Cheval" only)
|
|
2. **View dropdown** — lists available SVGs for selected species
|
|
|
|
Hardcoded config (easily extensible):
|
|
|
|
```javascript
|
|
const SPECIES_CONFIG = [
|
|
{
|
|
id: 'equine',
|
|
label: 'Cheval',
|
|
jsonPath: '/species/equine/pathologies.json',
|
|
views: [
|
|
{ label: 'Corps complet', svgPath: '/species/equine/Horse.svg' },
|
|
{ label: 'Tête (détail)', svgPath: '/species/equine/Horse_head.svg' },
|
|
],
|
|
},
|
|
];
|
|
```
|
|
|
|
**Pre-requisite**: `pathologies.json` must be copied (or symlinked) to `public/species/equine/pathologies.json` so it's accessible via HTTP when served statically. The source of truth remains `src/domain/species/equine/pathologies.json` — the public copy is read-only for the editor.
|
|
|
|
"Charger" button fetches both files. If either fetch fails, show error with HTTP status.
|
|
|
|
All views of a species share the same JSON. Switching view reloads SVG only, keeps JSON state.
|
|
|
|
### 3b. Manual upload
|
|
|
|
Two file inputs:
|
|
- "Fichier SVG" — accepts `.svg`
|
|
- "Fichier JSON" — accepts `.json`
|
|
|
|
Both required. If only one provided, "Charger" button disabled with message: "Les deux fichiers (SVG et JSON) sont obligatoires."
|
|
|
|
Files read via `FileReader` as UTF-8 text.
|
|
|
|
### Source switch
|
|
|
|
After loading, sidebar transitions to editing mode. A "Changer de source" link at the top returns to the source picker. Switching source discards current edits (with confirmation if modifications exist).
|
|
|
|
---
|
|
|
|
## 4. SVG Display
|
|
|
|
### Loading
|
|
|
|
Parse SVG text, inject into canvas container as inline SVG. Auto-viewBox: if `viewBox` attribute missing, compute from SVG `width`/`height` or `getBBox()` and set it (same as `editor.html` pattern).
|
|
|
|
### Zone detection
|
|
|
|
Walk all SVG elements. An element is a clickable zone if it has `data-anno-id` AND at least one of `data-anno-name-fr` or `data-anno-name-en`.
|
|
|
|
### Interaction
|
|
|
|
- **Hover**: subtle opacity/highlight change on annotated elements
|
|
- **Click**: select zone (see section 5)
|
|
- **Selected state**: distinct highlight color (blue outline or fill overlay), persists until another zone clicked
|
|
|
|
No editing of SVG content. SVG is read-only visual selector.
|
|
|
|
---
|
|
|
|
## 5. Zone Selection Logic
|
|
|
|
When user clicks an annotated SVG element:
|
|
|
|
### Step 1 — Read SVG attributes
|
|
|
|
Extract from clicked element (walk up DOM to find `data-anno-id` parent if needed):
|
|
- `data-anno-id`
|
|
- `data-anno-name-fr`
|
|
- `data-anno-name-en`
|
|
- `data-anno-opens-detail` (if present)
|
|
- `data-anno-special` (if present)
|
|
|
|
### Step 2 — Special attribute handling
|
|
|
|
| Attribute | Behavior |
|
|
|-----------|----------|
|
|
| `data-anno-opens-detail` present | Show info message: "Zone de navigation vers un SVG de détail — non éditable ici. Chargez le SVG de détail pour éditer ses zones." Do NOT open tree editor. |
|
|
| `data-anno-special` present (e.g., `vertebral-precision`) | Treat as normal editable zone. `special` attribute is irrelevant to pathology editing. |
|
|
|
|
### Step 3 — Fuzzy match to JSON zone
|
|
|
|
Match SVG `name_fr`/`name_en` against `zones[*].name_fr`/`name_en` in loaded JSON.
|
|
|
|
Matching algorithm (port from `src/lib/zoneMatch.ts`):
|
|
|
|
1. Normalize both strings: `str.normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase().replace(/[^a-z0-9]/g, '')`
|
|
2. Score pairs (SVG label vs JSON zone label):
|
|
- Exact match → score 0
|
|
- Substring containment → score 1
|
|
- Levenshtein distance ≤ 25% of max length (min 2 edits) → score 2 + distance
|
|
3. Priority: EN-on-EN first, FR-on-FR second, cross-language last
|
|
4. Take lowest score. If no candidate below threshold → no match.
|
|
|
|
### Step 4 — Result
|
|
|
|
| Result | Sidebar action |
|
|
|--------|---------------|
|
|
| Match found | Select zone, show tree editor for matched zone |
|
|
| No match | Show "Aucune zone correspondante dans le JSON" + "Créer cette zone" button |
|
|
|
|
### Creating a new zone
|
|
|
|
"Créer cette zone" pre-fills:
|
|
- `id`: generated from `name_en` (fallback `name_fr`) → kebab-case (see section 7 for ID generation)
|
|
- `name_fr`: from SVG `data-anno-name-fr`
|
|
- `name_en`: from SVG `data-anno-name-en`
|
|
- `categories`: empty array `[]`
|
|
|
|
Zone added to in-memory JSON `zones` object immediately.
|
|
|
|
---
|
|
|
|
## 6. Pathology Tree Editor
|
|
|
|
### Zone header
|
|
|
|
When a zone is selected, sidebar shows:
|
|
- Zone name: `name_fr` / `name_en` (read-only display, not editable — zone names come from SVG)
|
|
- Zone ID: displayed as badge (read-only)
|
|
- Zone stats: count of categories, total node count
|
|
|
|
### Tree display
|
|
|
|
Recursive collapsible tree rendering all `categories` and their nested `children`:
|
|
|
|
```
|
|
📁 Dysfonctions ostéopathiques [+ Ajouter enfant] [✏️] [🗑️]
|
|
📁 Lésions de mobilité [+ Ajouter enfant] [✏️] [🗑️]
|
|
🔹 En flexion (rotation externe) [✏️] [🗑️]
|
|
🔹 En extension (rotation interne) [✏️] [🗑️]
|
|
📁 Lésions intra-osseuses [+ Ajouter enfant] [✏️] [🗑️]
|
|
🔹 Compression intra-osseuse [✏️] [🗑️]
|
|
📁 Observations / motifs de consultation [+ Ajouter enfant] [✏️] [🗑️]
|
|
...
|
|
```
|
|
|
|
Visual conventions:
|
|
- 📁 = node with `children` (category/intermediate) — collapsible
|
|
- 🔹 = leaf node (no `children` or empty `children`) — selectable by practitioner in main app
|
|
- Indentation: 20px per level
|
|
- Collapse state: all collapsed by default, expand on click
|
|
|
|
### Node operations
|
|
|
|
#### Edit node (✏️)
|
|
|
|
Click edit icon → inline form expands below the node:
|
|
|
|
| Field | Type | Required |
|
|
|-------|------|----------|
|
|
| `name_fr` | text input | yes |
|
|
| `name_en` | text input | yes |
|
|
| `description_fr` | textarea | no |
|
|
| `description_en` | textarea | no |
|
|
| `requires_vet_referral` | checkbox | no (default false) |
|
|
| Sources | repeatable row group | no |
|
|
|
|
Each source row:
|
|
- `type`: select dropdown (`manual`, `journal`, `database`, `web`)
|
|
- `citation`: text input
|
|
- `url`: text input (optional)
|
|
- [Remove source] button
|
|
|
|
[Add source] button below sources list.
|
|
|
|
"Enregistrer" saves changes to in-memory JSON. "Annuler" discards form.
|
|
|
|
When saving, `id` is NOT editable — it was set at creation and remains stable.
|
|
|
|
#### Add child node (+ Ajouter enfant)
|
|
|
|
Available on any node. Opens inline form (same as edit) for the new child.
|
|
|
|
On save:
|
|
- New node inserted as last child of parent
|
|
- `id` auto-generated from `name_en` (see section 7)
|
|
- If parent was a leaf (no `children`), it becomes a category (gets `children` array)
|
|
|
|
#### Add root category (+ Ajouter catégorie)
|
|
|
|
Button at bottom of zone's tree. Creates new top-level category in `categories` array.
|
|
|
|
#### Delete node (🗑️)
|
|
|
|
Click delete → confirmation dialog: "Supprimer « {name_fr} » et tous ses enfants ({N} nœuds) ?"
|
|
|
|
On confirm: remove node and entire subtree from parent's `children` (or from zone's `categories` if root-level).
|
|
|
|
### No reordering
|
|
|
|
Drag-and-drop reordering excluded from this version. Node order matches JSON array order.
|
|
|
|
---
|
|
|
|
## 7. ID Generation
|
|
|
|
Auto-generate `id` for new nodes and zones:
|
|
|
|
```javascript
|
|
function generateId(nameEn, nameFr, existingSiblingIds) {
|
|
const source = (nameEn || nameFr || 'node').trim();
|
|
let slug = source
|
|
.normalize('NFD')
|
|
.replace(/[̀-ͯ]/g, '') // strip accents
|
|
.toLowerCase()
|
|
.replace(/[^a-z0-9]+/g, '-') // non-alnum → hyphen
|
|
.replace(/^-|-$/g, ''); // trim leading/trailing hyphens
|
|
|
|
if (!slug) slug = 'node';
|
|
|
|
// Ensure uniqueness among siblings
|
|
let candidate = slug;
|
|
let counter = 2;
|
|
while (existingSiblingIds.includes(candidate)) {
|
|
candidate = `${slug}-${counter}`;
|
|
counter++;
|
|
}
|
|
return candidate;
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 8. JSON Export
|
|
|
|
### Trigger
|
|
|
|
"Télécharger JSON" button — always visible in sidebar header area, enabled once source is loaded.
|
|
|
|
### Output
|
|
|
|
- Full JSON object with all root fields preserved: `schema_version`, `scope_disclaimer`, `species`, `zones`
|
|
- ALL zones included (modified + unmodified)
|
|
- UTF-8 encoding, 2-space indentation
|
|
- Filename: `pathologies-{speciesId}-{YYYYMMDD-HHmmss}.json` (or `pathologies-custom-{timestamp}.json` for manual uploads)
|
|
|
|
### Implementation
|
|
|
|
```javascript
|
|
const blob = new Blob(
|
|
[JSON.stringify(jsonData, null, 2)],
|
|
{ type: 'application/json;charset=utf-8' }
|
|
);
|
|
const url = URL.createObjectURL(blob);
|
|
// trigger download via <a> element
|
|
```
|
|
|
|
### Integrity rules
|
|
|
|
- Never drop fields from nodes (even if empty/optional — omit only if truly absent)
|
|
- Never reorder zone keys (use insertion order from original parse)
|
|
- `schema_version` preserved as-is (no auto-bump)
|
|
- Empty `children: []` on a leaf is valid and preserved if originally present
|
|
|
|
---
|
|
|
|
## 9. Unsaved Changes Protection
|
|
|
|
Track modification state (dirty flag). When user attempts to:
|
|
- Switch source → confirm dialog: "Des modifications non enregistrées seront perdues. Continuer ?"
|
|
- Close/navigate away → `beforeunload` event handler
|
|
|
|
---
|
|
|
|
## 10. Error Handling
|
|
|
|
| Scenario | Behavior |
|
|
|----------|----------|
|
|
| SVG fetch fails (pre-wired) | Show error: "Impossible de charger le SVG: {status}" |
|
|
| JSON fetch fails (pre-wired) | Show error: "Impossible de charger le JSON: {status}" |
|
|
| JSON parse error | Show error: "Le fichier JSON est invalide: {error.message}" |
|
|
| JSON missing required root fields | Show error: "Structure JSON invalide: champ '{field}' manquant" |
|
|
| SVG has no annotated elements | Show warning: "Aucun élément annoté (data-anno-*) trouvé dans ce SVG" |
|
|
| Uploaded file too large (>10MB) | Show error: "Fichier trop volumineux (max 10 Mo)" |
|
|
|
|
---
|
|
|
|
## 11. Styling
|
|
|
|
Consistent with `editor.html` aesthetic:
|
|
- Dark header bar with tool title
|
|
- White sidebar background, light gray canvas background
|
|
- System font stack: `-apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif`
|
|
- Buttons: solid background (blue primary, red destructive, gray secondary)
|
|
- Inputs: bordered, rounded, consistent padding
|
|
- Tree nodes: hover highlight, selected state with left border accent
|
|
- Responsive: min-width 900px, below that show a "use larger screen" message
|
|
|
|
---
|
|
|
|
## 12. File Structure
|
|
|
|
Single file: `pathology-editor.html` at project root (same level as `editor.html`).
|
|
|
|
No external dependencies. All CSS inline in `<style>`. All JS inline in `<script>`.
|
|
|
|
Approximate structure:
|
|
```html
|
|
<!DOCTYPE html>
|
|
<html lang="fr">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<meta name="robots" content="noindex,nofollow">
|
|
<title>Faunosteo — Éditeur de pathologies</title>
|
|
<style>/* all styles */</style>
|
|
</head>
|
|
<body>
|
|
<header><!-- title bar --></header>
|
|
<main>
|
|
<div id="canvas"><!-- SVG container --></div>
|
|
<aside id="sidebar"><!-- source picker / tree editor --></aside>
|
|
</main>
|
|
<script>/* all logic */</script>
|
|
</body>
|
|
</html>
|
|
```
|
|
|
|
---
|
|
|
|
## 13. Out of Scope
|
|
|
|
- Node drag-and-drop reordering
|
|
- Undo/redo history
|
|
- Multi-zone selection
|
|
- Zone name editing (names come from SVG, not JSON)
|
|
- SVG modification or export
|
|
- Schema version auto-bumping
|
|
- Diff/merge between JSON versions
|
|
- Integration as React route (standalone only)
|
|
|
|
---
|
|
|
|
## 14. Acceptance Criteria
|
|
|
|
1. Pre-wired source loads SVG + JSON from local paths, displays SVG with clickable zones
|
|
2. Manual upload accepts SVG + JSON files, rejects incomplete uploads
|
|
3. Clicking annotated SVG zone matches to JSON zone via fuzzy matching
|
|
4. Clicking `data-anno-opens-detail` zone shows navigation info, not tree editor
|
|
5. Tree editor displays full recursive hierarchy for selected zone
|
|
6. Can add node at any level (root category, intermediate, leaf)
|
|
7. Can edit all node fields (name_fr, name_en, descriptions, vet referral, sources)
|
|
8. Can delete node with confirmation, removes entire subtree
|
|
9. New node IDs auto-generated as unique kebab-case slugs
|
|
10. "Créer cette zone" works for SVG zones with no JSON match
|
|
11. Downloaded JSON contains all zones (modified + unmodified) with root fields preserved
|
|
12. Downloaded JSON is valid UTF-8 with 2-space indentation
|
|
13. Unsaved changes trigger confirmation on source switch and page close
|
|
14. All error scenarios show user-facing French messages
|