docs(docs): restore 2026-05 design specs and plans under docs/history
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.
This commit is contained in:
1 parent
8673475293
commit
02052f3622
12 files changed
+8581
-3
No files matched your search
@@ -0,0 +1,387 @@
|
||||
# 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
|
||||
Reference in new issue
Block a user