diagrams-fable-tauri/docs/plan/plan.md

# Pipeline Network Diagram Editor — Implementation Plan

Desktop diagram editor for pipeline networks (water, gas, heat, power) built with
**Tauri 2** + **React 18** + **TypeScript** + **Vite** + **JointJS core (@joint/core, MPL-2.0)**.

## Library selection (done via web research)

JointJS core was selected over React Flow, AntV X6, GoJS because it is the only
open-source option with all hard requirements built in:

- SVG-markup-defined nodes with **port groups** and `validateConnection` / `validateMagnet`
  hooks → relation-based connection rules (water/gas/power…).
- `manhattan` / `orthogonal` / `rightAngle` **routers** → edges follow rectangular grid.
- `jumpover` **connector** → arcs at line intersections, toggleable per configuration.
- Rich link styling: source/target markers (arrows, circles, diamonds), dash patterns.
- Framework-agnostic core; React used for panels/UI around the canvas.

Rejected: GoJS (commercial license), React Flow (no built-in orthogonal routing or
line jumps), AntV X6 (no jumpover arcs, weaker docs in English).

## Architecture

```
src/                      # frontend (React + TS)
  model/                  # pure domain model — no JointJS imports, fully unit-testable
    properties.ts         # typed property system + groups
    catalog.ts            # catalogues (pipe series, materials…)
    nodeTypes.ts          # node type registry: SVG, ports, default props
    graph.ts              # document model: nodes, edges, (de)serialization
    validation.ts         # port relation compatibility rules
  editor/                 # JointJS integration
    shapes.ts             # JointJS element/link factories from node types
    paper.ts              # paper setup: grid, routing, jumpover, interactions
    edgeStyles.ts         # line styles, arrowheads/tails: arrow|circle|diamond|bar|none
    colorSchemes.ts       # port-relation color schemes (default/dark/high-contrast/mono)
  sim/
    flow.ts               # mock flow distribution solver (mass balance at junctions)
    animation.ts          # dash-offset flow animation, speed & width ∝ flow volume
  state/
    store.ts              # app state, selection, config
    history.ts            # undo/redo command stack
    clipboard.ts          # copy/paste
  ui/
    Palette.tsx           # grouped node palette, drag & drop onto canvas
    PropertyPanel.tsx     # grouped typed property editors
    Toolbar.tsx           # file ops, undo/redo, zoom, grid, simulate
    SettingsDialog.tsx    # configuration (arc-on-intersection, schemes, grid…)
    Canvas.tsx            # JointJS paper host
src-tauri/                # Rust shell, fs dialogs, save/load
tests/                    # vitest unit + component tests
```

## Actionable items

### Phase 0 — Research & scaffolding
- [x] Web research: select diagramming library (JointJS core)
- [x] Write implementation plan (this document)
- [x] Init git repository, `.gitignore`, conventional commits
- [x] Install Linux system deps for Tauri (webkit2gtk 4.1, librsvg, appindicator)
- [x] Scaffold Vite + React + TS app, add `@joint/core`
- [x] Add Tauri 2 shell (`src-tauri`), dev/build scripts
- [x] Set up vitest + jsdom + testing-library

### Phase 1 — Domain model
- [x] Property system: `string, int, float, enum, catalogueItem, catalogueItems, color, listOfValues`
      with property groups (Presentation / Physics / General) and validation
- [x] Catalogues: pipe diameter series, materials, media catalogues
- [x] Port relations: water, gas, heat, power, signal + compatibility matrix
- [x] Node type registry: SVG view, port layout per type (pump, valve, tank, source,
      consumer, junction/tee, heat exchanger, boiler, power supply, sensor…)
- [x] Graph document model + JSON (de)serialization

### Phase 2 — Editor canvas
- [x] JointJS paper: rectangular grid, pan (space/drag), zoom (wheel), snap-to-grid
- [x] Node shapes generated from SVG defs with ports
- [x] Click node → show/highlight ports (magnets) available for linking
- [x] Edge drawing from port to compatible port only (`validateConnection` by relation)
- [x] Orthogonal (manhattan) edge routing along grid
- [x] Config option: `jumpover` connector — arc on line intersections (on/off)
- [x] Edge styles: line (solid/dashed/dotted), width, color; head & tail markers:
      arrow, circle, diamond, bar, none
- [x] Port relation color schemes (≥3 schemes) applied to ports and edges

### Phase 3 — Editing UX (the "missed features")
- [x] Node dragging with grid snap
- [x] Multi-select (shift-click + rubber-band), group move
- [x] Delete node/edge (Del), with connected-edge cleanup
- [x] Undo / redo (Ctrl+Z / Ctrl+Shift+Z) command stack
- [x] Copy / paste / duplicate (Ctrl+C/V/D) with offset
- [x] Edge vertex editing (drag to add bend points) via link tools
- [x] Select-all (Ctrl+A), Escape clears selection
- [x] Zoom to fit, zoom in/out buttons, reset zoom
- [x] Keyboard nudge of selected nodes with arrow keys

### Phase 4 — Panels
- [x] Left palette: node types grouped by category, SVG thumbnails, drag onto canvas
- [x] Palette search/filter
- [x] Right property panel for focused node/edge: grouped, collapsible
- [x] Editors per property type: text, int, float (with units), enum select,
      catalogue item picker, multi catalogue items, color picker, list-of-values editor
- [x] Presentation group edits geometry live (x, y, angle, size; edge style)
- [x] Physics group (length, diameter, flow rate, flow type…) stored on model
- [x] Read-only computed properties (e.g. simulated flow) displayed

### Phase 5 — Configuration & persistence
- [x] Settings dialog: grid size, snap on/off, arc-on-intersection, router choice,
      color scheme, animation on/off
- [x] Save / Load project as JSON via Tauri dialog + fs (browser fallback in dev)
- [x] Export diagram as SVG
- [x] New / clear document with confirm

### Phase 6 — Mock calculation & animation
- [x] Flow solver mock: sources with supply, consumers with demand, mass balance,
      proportional split at junctions by pipe cross-section
- [x] Edge direction from solved flow (may oppose drawing direction)
- [x] Animate flow: moving dashes along edges, speed ∝ flow volume,
      stroke width ∝ volume, direction arrows
- [x] Simulation panel/toggle in toolbar; results written to read-only edge props

### Phase 7 — Tests (vitest)
- [x] Property system: creation, validation, groups, all 8 types
- [x] Graph model: add/remove nodes & edges, serialization round-trip
- [x] Connection validation: relation compatibility matrix scenarios
- [x] Flow solver: chain, tee split, multi-source, disconnected, conservation
- [x] History: undo/redo scenarios incl. transaction batching
- [x] Catalogues: lookup, item resolution
- [x] Component smoke tests: palette renders groups, property panel renders editors
- [x] Full suite green: `npm test` (77 tests)

### Phase 8 — Finish
- [x] README with dev/build instructions
- [x] `cargo tauri build` debug bundle succeeds (`npm run tauri:build:debug`)
- [x] Check off all plan items