3758164635
- Scaffold Vite React-TS frontend and Tauri v2 shell - Install JointJS (@joint/core), Zustand, Vitest + Testing Library - Configure Vite (fixed port 1420) and Vitest (jsdom, coverage) - Add docs/plan with milestone checklist and JointJS rationale Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
136 lines
6.3 KiB
Markdown
136 lines
6.3 KiB
Markdown
# Pipeline Network Diagram Editor — Implementation Plan
|
|
|
|
A desktop diagram editor for designing pipeline networks (water, power, gas …),
|
|
built with **Tauri v2 + React + TypeScript + Vite**, using **JointJS
|
|
(`@joint/core`, MPL-2.0)** as the diagramming engine.
|
|
|
|
## Why JointJS
|
|
|
|
Chosen over React Flow / Rete / GoJS after research because it uniquely covers
|
|
every hard requirement out of the box:
|
|
|
|
- Framework-agnostic SVG canvas with **custom SVG markup** for nodes → matches
|
|
"nodes are defined by an SVG set with port configuration".
|
|
- First-class **port model** with port groups + `validateConnection` →
|
|
relation-based connectability & color schemes.
|
|
- Built-in **grid/orthogonal routers** (`manhattan`, `orthogonal`) and a
|
|
**`jumpover` connector with `jump: 'arc'`** → "lines drawn along rectangular
|
|
grids" and the configurable "arc on intersection of lines".
|
|
- Rich **link markup / markers** → arrow / circle / diamond heads and tails.
|
|
- SVG attrs animation → animated flow direction & volume for the mock solver.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
src/
|
|
model/ domain types: node & edge type defs, port types, relations,
|
|
property schema, catalogues, color schemes (pure, unit-tested)
|
|
canvas/ JointJS shapes, paper/graph setup, routing, selection, tools
|
|
calc/ mock flow-distribution solver + animation controller (unit-tested)
|
|
store/ Zustand app store (selection, config, catalogues, document)
|
|
panels/ React UI: NodePalette, PropertiesPanel, Toolbar, ConfigPanel
|
|
io/ serialize / deserialize document, export PNG/SVG, Tauri fs bridge
|
|
test/ vitest setup
|
|
src-tauri/ Tauri v2 Rust shell (file dialogs, fs plugin)
|
|
```
|
|
|
|
---
|
|
|
|
## Milestones & Tasks
|
|
|
|
### M0 — Project setup & tooling
|
|
- [x] Research & select diagramming library (JointJS)
|
|
- [x] Scaffold Tauri v2 + Vite + React + TS
|
|
- [x] Install deps (@joint/core, zustand, vitest, testing-library, tauri plugins)
|
|
- [x] Configure Vite (port 1420) + Vitest (jsdom, coverage)
|
|
- [x] Write this plan
|
|
- [ ] Base app shell layout (palette | canvas | properties, top toolbar)
|
|
- [ ] CI-style scripts: `test`, `test:run`, `lint`, `typecheck`
|
|
|
|
### M1 — Domain model (pure, tested)
|
|
- [ ] Port types & **relation registry** (which port types may connect)
|
|
- [ ] Connection validation function (`canConnect(source, target, relations)`)
|
|
- [ ] **Color schemes** mapping port/relation types → colors (multiple presets)
|
|
- [ ] Property schema types: `string,int,float,enum,catalogueItem,catalogueItems,color,list`
|
|
- [ ] Property groups (presentation / identity / physics)
|
|
- [ ] Catalogue model (named collections of catalogue items)
|
|
- [ ] Node type definitions with SVG markup + port layout (pump, valve, tank,
|
|
junction, source, sink, …)
|
|
- [ ] Edge style definitions (line styles + source/target markers)
|
|
- [ ] Default property values & validation/coercion per type
|
|
|
|
### M2 — Canvas engine (JointJS)
|
|
- [ ] Paper + graph init, background grid, snap-to-grid
|
|
- [ ] Custom `PipelineNode` element (renders node-type SVG + ports)
|
|
- [ ] Custom `PipelineLink` with configurable markers & line styles
|
|
- [ ] Port rendering; show ports only when node focused/hovered
|
|
- [ ] Draw edge from a port; live validation highlight (valid/invalid)
|
|
- [ ] Grid routing (`manhattan`) + **config toggle for `jumpover` arc connector**
|
|
- [ ] Selection (single, multi, rubber-band) & focus highlighting
|
|
- [ ] Element tools: remove, boundary, resize; link tools: vertices, arrowheads, remove
|
|
|
|
### M3 — Node palette
|
|
- [ ] Grouped, collapsible stencil of node types (vector previews)
|
|
- [ ] Search/filter
|
|
- [ ] Drag-and-drop node from palette to canvas (drop at cursor, snap)
|
|
|
|
### M4 — Properties panel
|
|
- [ ] Reflects current selection (node or edge), empty state otherwise
|
|
- [ ] Grouped property editors, one per property type
|
|
- [ ] Editors: string, int, float, enum(select), color(picker),
|
|
catalogueItem(select), catalogueItems(multi), list(add/remove rows)
|
|
- [ ] Two-way binding: edits write back to element & update canvas presentation
|
|
- [ ] Geometry props (position/size/rotation) & title reflected live
|
|
|
|
### M5 — Editing UX (the "typical scenarios" often missed)
|
|
- [ ] Undo / redo (command stack)
|
|
- [ ] Delete, copy / cut / paste, duplicate
|
|
- [ ] Keyboard shortcuts (Del, Ctrl+Z/Y, Ctrl+C/V/X/D, Ctrl+A, Esc)
|
|
- [ ] Zoom (buttons + ctrl-wheel), pan (space/mmb drag), fit-to-content, reset
|
|
- [ ] Grid + snap toggles, background config
|
|
- [ ] Context menu on nodes/edges/canvas
|
|
- [ ] Rename via inline / properties title
|
|
|
|
### M6 — Configuration
|
|
- [ ] Config panel: color scheme, arc-on-intersection, grid size/visibility,
|
|
snap, router type, animation speed
|
|
- [ ] Persist config; live-apply to paper & links
|
|
|
|
### M7 — Persistence & export
|
|
- [ ] Serialize document (graph + metadata + config) to JSON
|
|
- [ ] Save / Open via Tauri dialog + fs (graceful fallback to download/localStorage in browser)
|
|
- [ ] New document
|
|
- [ ] Export canvas to SVG and PNG
|
|
|
|
### M8 — Mock calculation & flow animation
|
|
- [ ] Build network graph from nodes/edges (respect port direction)
|
|
- [ ] Assign supplies/demands from node physics props
|
|
- [ ] **Flow-distribution solver** (conservation at junctions, proportional split)
|
|
- [ ] Map per-edge flow → direction (sign) + volume (magnitude)
|
|
- [ ] Animate flow along edges (dash animation; speed ∝ volume, dir ∝ sign)
|
|
- [ ] Color/width edges by flow volume; run / stop / reset controls
|
|
- [ ] Report unbalanced nodes / disconnected components
|
|
|
|
### M9 — Testing
|
|
- [ ] Unit: relation validation & color schemes
|
|
- [ ] Unit: property schema coercion/validation & catalogue resolution
|
|
- [ ] Unit: flow-distribution solver (linear, split, merge, cycle, unbalanced)
|
|
- [ ] Unit: document serialize/deserialize round-trip
|
|
- [ ] Component: palette renders groups; properties panel renders & edits
|
|
- [ ] Component: store actions (add node, connect, select, undo/redo)
|
|
- [ ] `npm run test:run` green; typecheck & lint clean
|
|
|
|
### M10 — Polish & docs
|
|
- [ ] Seed demo network on first launch
|
|
- [ ] README with run/test instructions & feature list
|
|
- [ ] App icon / window sizing
|
|
|
|
---
|
|
|
|
## Definition of done
|
|
- `npm run test:run` passes; `npm run typecheck` clean.
|
|
- `npm run dev` shows a working editor: drag nodes, connect ports with
|
|
validation, edit grouped properties, toggle arc routing & color schemes,
|
|
run the mock solver with animated flow, save/open/export.
|
|
- Conventional atomic commits throughout.
|