From 8a1d2d0da634d9fd5e20e95194fef23cc01d7725 Mon Sep 17 00:00:00 2001 From: Ilya Ashikhmin Date: Thu, 2 Jul 2026 23:13:45 +0200 Subject: [PATCH] docs: add pipeline editor implementation plan 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) --- docs/plan/README.md | 119 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 docs/plan/README.md diff --git a/docs/plan/README.md b/docs/plan/README.md new file mode 100644 index 0000000..344f890 --- /dev/null +++ b/docs/plan/README.md @@ -0,0 +1,119 @@ +# 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