8a1d2d0da6
Records the library research (JointJS core chosen), tech stack, and a milestone checklist covering nodes, ports, edges, properties, catalogue, mock flow and editing UX. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
120 lines
5.5 KiB
Markdown
120 lines
5.5 KiB
Markdown
# Pipeline Network Diagram Editor — Implementation Plan
|
|
|
|
An Electron desktop application for drawing and analyzing **pipeline / network
|
|
diagrams** (water lines, power lines, gas, etc.). Nodes are SVG symbols with
|
|
typed connection ports; edges are routed orthogonally along a grid and can
|
|
carry an animated mock flow.
|
|
|
|
## Tech stack (decided after research)
|
|
|
|
| Concern | Choice | Why |
|
|
|--------------------|-------------------------------|-----|
|
|
| Shell | **Electron** | Required by task |
|
|
| Diagram engine | **JointJS core (`@joint/core`, MPL-2.0)** | Only free engine with custom SVG nodes **+** built-in ports **+** manhattan router **+** `jumpover` connector (arc-on-intersection). |
|
|
| UI panels / shell | **React 18 + TypeScript** | Ergonomic typed property panel & stencil. |
|
|
| Build | **electron-vite (Vite 6)** | Fast HMR, TS, main/preload/renderer split. |
|
|
| Tests | **Vitest + jsdom** | Headless testing of graph model, validation, flow, properties. |
|
|
|
|
Research sources:
|
|
- https://www.jointjs.com/blog/javascript-diagramming-libraries
|
|
- https://reactflow.dev/
|
|
- https://portalzine.de/visualize-this-open-source-diagram-tools-to-replace-gojs/
|
|
|
|
---
|
|
|
|
## Milestones & actionable checklist
|
|
|
|
### M0 — Project scaffold
|
|
- [ ] Initialize `package.json`, TypeScript, electron-vite config
|
|
- [ ] Electron main process + secure preload bridge (contextIsolation)
|
|
- [ ] React renderer boots inside Electron with 3-pane layout (stencil | canvas | properties)
|
|
- [ ] `npm run dev` launches, `npm run build` produces bundles
|
|
- [ ] Vitest configured, sample test green
|
|
|
|
### M1 — Diagram canvas (JointJS host)
|
|
- [ ] `DiagramController` wraps a JointJS `Graph` + `Paper`
|
|
- [ ] Rectangular background grid, configurable size
|
|
- [ ] Pan (space/drag) + zoom (wheel/buttons), fit-to-content
|
|
- [ ] Selection model (click, marquee, multi-select)
|
|
|
|
### M2 — Node system (SVG symbols + ports)
|
|
- [ ] Symbol registry: each symbol = SVG markup + port layout + default props
|
|
- [ ] Seed symbol library grouped by domain (source, sink, junction, valve, pump, tank, meter…)
|
|
- [ ] Custom JointJS element renders symbol SVG + ports
|
|
- [ ] Ports carry a **relation/medium** (water, power, gas, signal…) with color scheme
|
|
- [ ] Focused node reveals its ports as connectable magnets
|
|
|
|
### M3 — Node panel (stencil)
|
|
- [ ] Left panel lists symbols grouped by category, collapsible
|
|
- [ ] Search/filter symbols
|
|
- [ ] Drag symbol → drop onto canvas creates node at grid-snapped position
|
|
- [ ] Live SVG preview thumbnails
|
|
|
|
### M4 — Edges / connectors
|
|
- [ ] Draw edge by dragging from a port; snap to a compatible target port
|
|
- [ ] **Connection validation** by port relation (compatible media only)
|
|
- [ ] Orthogonal (manhattan) routing along the grid
|
|
- [ ] Config toggle: **arc (jumpover) on line intersections** vs plain crossing
|
|
- [ ] Edge style presets: line style (solid/dashed), width, color
|
|
- [ ] Head/tail markers: none, arrow, circle, diamond, bar
|
|
- [ ] Vertices editable; re-route on node move
|
|
|
|
### M5 — Property panel (typed, grouped)
|
|
- [ ] Reflects focused node **or** edge
|
|
- [ ] Property groups (Presentation / Identity / Physics …)
|
|
- [ ] Editors for types: `string`, `int`, `float`, `enum`, `color`,
|
|
`catalogueItem`, `catalogueItems`, `listOfValues`
|
|
- [ ] Two-way binding: edit → model → canvas re-render
|
|
- [ ] Validation (min/max, required, units)
|
|
|
|
### M6 — Catalogue system
|
|
- [ ] Catalogue store (e.g. pipe materials, pump models) with typed fields
|
|
- [ ] `catalogueItem` picker (single) and `catalogueItems` (multi)
|
|
- [ ] Selecting a catalogue item can seed physics defaults (diameter, roughness…)
|
|
|
|
### M7 — Mock calculation & flow animation
|
|
- [ ] Flow solver mock: assign a flow value + direction to each edge
|
|
(conservation-ish distribution from sources to sinks)
|
|
- [ ] Animate flow direction along edges (marching ants / motion)
|
|
- [ ] Animation speed & dash density encode flow **volume**
|
|
- [ ] Color edges by flow magnitude (legend)
|
|
- [ ] Run / stop / step controls in toolbar
|
|
|
|
### M8 — Editing UX & configuration
|
|
- [ ] Move/drag nodes with grid snapping
|
|
- [ ] Delete (nodes+incident edges), copy/paste, duplicate
|
|
- [ ] Undo / redo (command history)
|
|
- [ ] Keyboard shortcuts (Del, Ctrl+Z/Y, Ctrl+C/V, Ctrl+A, arrows nudge)
|
|
- [ ] Context menu on node/edge/canvas
|
|
- [ ] Save / load diagram to JSON; New; export SVG/PNG
|
|
- [ ] Settings dialog: grid size, snapping, jumpover on/off, color scheme,
|
|
theme (light/dark)
|
|
- [ ] Alignment/distribution helpers, z-order
|
|
|
|
### M9 — Tests (typical scenarios)
|
|
- [ ] Symbol registry & port relation resolution
|
|
- [ ] Connection validation (compatible vs incompatible media)
|
|
- [ ] Property model get/set, type coercion & validation
|
|
- [ ] Catalogue pick seeds defaults
|
|
- [ ] Add node / connect / delete lifecycle on the graph model
|
|
- [ ] Serialization round-trip (save → load)
|
|
- [ ] Flow solver conservation & direction
|
|
- [ ] Router/jumpover configuration switch
|
|
|
|
### M10 — Polish & docs
|
|
- [ ] README with screenshots / run instructions
|
|
- [ ] Sample diagram bundled
|
|
- [ ] Final plan checkmarks updated
|
|
|
|
---
|
|
|
|
## Features added beyond the original brief
|
|
- Undo/redo command history, copy/paste/duplicate, keyboard shortcuts
|
|
- Marquee multi-select, alignment/distribution, z-order
|
|
- Save/load (JSON) + export (SVG/PNG)
|
|
- Settings dialog (grid, snapping, jumpover, color scheme, light/dark theme)
|
|
- Minimap / fit-to-content, zoom controls
|
|
- Catalogue-driven physics defaults
|
|
- Flow legend and run/step/stop controls
|
|
- Symbol search in the stencil
|