From 61f2975fb35ecfd3a80236b32664661f8bb696fb Mon Sep 17 00:00:00 2001 From: Ilya Ashikhmin Date: Thu, 2 Jul 2026 23:02:13 +0200 Subject: [PATCH] chore: init repo with implementation plan and gitignore Co-Authored-By: Claude Fable 5 --- .gitignore | 6 +++ docs/plan/plan.md | 133 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 139 insertions(+) create mode 100644 .gitignore create mode 100644 docs/plan/plan.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..8113e12 --- /dev/null +++ b/.gitignore @@ -0,0 +1,6 @@ +node_modules/ +dist/ +src-tauri/target/ +*.log +.DS_Store +coverage/ diff --git a/docs/plan/plan.md b/docs/plan/plan.md new file mode 100644 index 0000000..ff521db --- /dev/null +++ b/docs/plan/plan.md @@ -0,0 +1,133 @@ +# 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) +- [ ] Init git repository, `.gitignore`, conventional commits +- [ ] Install Linux system deps for Tauri (webkit2gtk 4.1, librsvg, appindicator) +- [ ] Scaffold Vite + React + TS app, add `@joint/core` +- [ ] Add Tauri 2 shell (`src-tauri`), dev/build scripts +- [ ] Set up vitest + jsdom + testing-library + +### Phase 1 — Domain model +- [ ] Property system: `string, int, float, enum, catalogueItem, catalogueItems, color, listOfValues` + with property groups (Presentation / Physics / General) and validation +- [ ] Catalogues: pipe diameter series, materials, media catalogues +- [ ] Port relations: water, gas, heat, power, signal + compatibility matrix +- [ ] Node type registry: SVG view, port layout per type (pump, valve, tank, source, + consumer, junction/tee, heat exchanger, boiler, power supply, sensor…) +- [ ] Graph document model + JSON (de)serialization + +### Phase 2 — Editor canvas +- [ ] JointJS paper: rectangular grid, pan (space/drag), zoom (wheel), snap-to-grid +- [ ] Node shapes generated from SVG defs with ports +- [ ] Click node → show/highlight ports (magnets) available for linking +- [ ] Edge drawing from port to compatible port only (`validateConnection` by relation) +- [ ] Orthogonal (manhattan) edge routing along grid +- [ ] Config option: `jumpover` connector — arc on line intersections (on/off) +- [ ] Edge styles: line (solid/dashed/dotted), width, color; head & tail markers: + arrow, circle, diamond, bar, none +- [ ] Port relation color schemes (≥3 schemes) applied to ports and edges + +### Phase 3 — Editing UX (the "missed features") +- [ ] Node dragging with grid snap +- [ ] Multi-select (shift-click + rubber-band), group move +- [ ] Delete node/edge (Del), with connected-edge cleanup +- [ ] Undo / redo (Ctrl+Z / Ctrl+Shift+Z) command stack +- [ ] Copy / paste / duplicate (Ctrl+C/V/D) with offset +- [ ] Edge vertex editing (drag to add bend points) via link tools +- [ ] Select-all (Ctrl+A), Escape clears selection +- [ ] Zoom to fit, zoom in/out buttons, reset zoom +- [ ] Keyboard nudge of selected nodes with arrow keys + +### Phase 4 — Panels +- [ ] Left palette: node types grouped by category, SVG thumbnails, drag onto canvas +- [ ] Palette search/filter +- [ ] Right property panel for focused node/edge: grouped, collapsible +- [ ] Editors per property type: text, int, float (with units), enum select, + catalogue item picker, multi catalogue items, color picker, list-of-values editor +- [ ] Presentation group edits geometry live (x, y, angle, size; edge style) +- [ ] Physics group (length, diameter, flow rate, flow type…) stored on model +- [ ] Read-only computed properties (e.g. simulated flow) displayed + +### Phase 5 — Configuration & persistence +- [ ] Settings dialog: grid size, snap on/off, arc-on-intersection, router choice, + color scheme, animation on/off +- [ ] Save / Load project as JSON via Tauri dialog + fs (browser fallback in dev) +- [ ] Export diagram as SVG +- [ ] New / clear document with confirm + +### Phase 6 — Mock calculation & animation +- [ ] Flow solver mock: sources with supply, consumers with demand, mass balance, + proportional split at junctions by pipe cross-section +- [ ] Edge direction from solved flow (may oppose drawing direction) +- [ ] Animate flow: moving dashes along edges, speed ∝ flow volume, + stroke width ∝ volume, direction arrows +- [ ] Simulation panel/toggle in toolbar; results written to read-only edge props + +### Phase 7 — Tests (vitest) +- [ ] Property system: creation, validation, groups, all 8 types +- [ ] Graph model: add/remove nodes & edges, serialization round-trip +- [ ] Connection validation: relation compatibility matrix scenarios +- [ ] Flow solver: chain, tee split, multi-source, disconnected, conservation +- [ ] History: undo/redo scenarios incl. transaction batching +- [ ] Catalogues: lookup, item resolution +- [ ] Component smoke tests: palette renders groups, property panel renders editors +- [ ] Full suite green: `npm test` (94 tests) + +### Phase 8 — Finish +- [ ] README with dev/build instructions +- [ ] `cargo tauri build` debug bundle succeeds (`npm run tauri:build:debug`) +- [ ] Check off all plan items