@luispm/zflow-graph 0.1.0 → 0.2.0

package/docs/01-getting-started.md

@@ -153,6 +153,31 @@ flow.setNodeTasks(id, [{ text: 'done', done: true }]);
 flow.setNodeImage(id, 'https://...');
 ```
 
+## Load a graph from your own data model
+
+When your app already has `{ nodes, edges }` with string ids — services, components, whatever — use `loadGraph`. It wipes the canvas and inserts everything atomically (one `change` event, one undo snapshot) and resolves edges by your ids:
+
+```js
+flow.loadGraph({
+  nodes: [
+    { id: 'web',     kind: 'process', x: -200, y: 0, title: 'Web' },
+    { id: 'gateway', kind: 'process', x:    0, y: 0, title: 'Gateway' },
+    { id: 'svc',     kind: 'process', x:  200, y: 0, title: 'API',
+      data: { repo: 'github.com/acme/api' } },
+  ],
+  edges: [
+    { from: 'web', to: 'gateway' },
+    { from: 'gateway', to: 'svc' },
+  ],
+});
+
+// Find the zflow numeric id from your domain id later — no side table needed.
+flow.findNodeByUserId('svc');            // → some number
+flow.getNodeData(flow.findNodeByUserId('svc')).repo;   // → 'github.com/acme/api'
+```
+
+The `id` you provide is preserved through `toJSON()` / `loadJSON()` and remote Yjs edits. `data` is a free-form bag attached to every node for whatever metadata you need to round-trip.
+
 ## Listen to events
 
 ```js

package/docs/07-recipes.md

@@ -335,6 +335,108 @@ await load();
 
 ---
 
+## Recipe: load a graph from your own domain model
+
+Common case: your app has a `{ nodes, edges }` shape with **string ids** (`'svc_users'`, `'db_main'`, ...). You want to render it, let the user edit, and read it back without ever holding a `logicalId → zid` side table.
+
+```js
+const myGraph = {
+  nodes: [
+    { id: 'web',     kind: 'frontend', x: -200, y: -100, title: 'App web',     domain: { repo: 'github.com/acme/web' } },
+    { id: 'gateway', kind: 'gateway',  x:    0, y:    0, title: 'API gateway' },
+    { id: 'svc',     kind: 'service',  x:  200, y:    0, title: 'Users API'   },
+    { id: 'db',      kind: 'db',       x:  400, y:    0, title: 'PostgreSQL'  },
+  ],
+  edges: [
+    { from: 'web',     to: 'gateway', label: 'HTTPS' },
+    { from: 'gateway', to: 'svc' },
+    { from: 'svc',     to: 'db',      label: 'SELECT' },
+  ],
+};
+
+// Map domain fields into node.data so they survive every operation.
+flow.loadGraph({
+  nodes: myGraph.nodes.map(n => ({
+    id: n.id, kind: n.kind, x: n.x, y: n.y, title: n.title,
+    data: { domain: n.domain ?? null },
+  })),
+  edges: myGraph.edges,
+});
+
+// React to user edits — the runtime gives you back the zflow numeric id,
+// turn it back into your domain id via flow.data.
+flow.on('change', () => {
+  const out = { nodes: [], edges: [] };
+  for (let i = 0; i < flow.nodeCount(); i++) {
+    const d = flow.getNodeData(i) || {};
+    const p = flow.getNodePosition(i);
+    out.nodes.push({ id: d.__id, kind: flow.kinds[flow.V.kind[i]].name, x: p.x, y: p.y });
+  }
+  saveToBackend(out);
+});
+
+// When the user opens a context-menu action, jump back to your domain id:
+function onContextMenuClick(zid) {
+  const myId = flow.getNodeData(zid)?.__id;       // e.g. 'svc'
+  navigateToServicePage(myId);
+}
+```
+
+After this, the typical "wipe + repopulate" boilerplate every consumer used to write disappears.
+
+---
+
+## Recipe: a custom DOM overlay positioned over a node
+
+Want a React/Vue/raw-DOM popover that tracks a node as the user pans/zooms? Use the coordinate helpers and re-position from the `change` event (or on every animation frame for live drag).
+
+```js
+const overlay = document.createElement('div');
+Object.assign(overlay.style, {
+  position: 'absolute', pointerEvents: 'none',
+  padding: '6px 10px', background: '#161b27', color: '#e6edf3',
+  borderRadius: '6px', font: '12px Inter, ui-sans-serif',
+});
+overlay.textContent = 'attached';
+container.appendChild(overlay);
+
+const trackedId = 3;
+
+function positionOverlay() {
+  const p = flow.getNodePosition(trackedId);
+  if (!p) { overlay.style.display = 'none'; return; }
+  const top = flow.worldToScreen(p.x, p.y - p.h / 2 - 8);
+  const dpr = window.devicePixelRatio || 1;
+  overlay.style.left = (top.x / dpr) + 'px';
+  overlay.style.top  = (top.y / dpr) + 'px';
+}
+
+// Re-position on commits AND every frame (cheap — just a div transform).
+flow.on('change', positionOverlay);
+function loop() { positionOverlay(); requestAnimationFrame(loop); }
+loop();
+```
+
+---
+
+## Recipe: atomic edits without flooding listeners
+
+A common mistake: 1000 calls to `addNode` fire 1000 `change` events and push 1000 undo snapshots. Use `transaction`:
+
+```js
+flow.transaction(() => {
+  for (const row of bigPayload) {
+    flow.addNode({ kind: 'service', ...row });
+  }
+  flow.runAutoLayout();
+});
+// Listeners hear ONE 'change'. The whole batch is ONE undo.
+```
+
+This is what `loadGraph` and `addNodesBulk` do internally.
+
+---
+
 ## Next
 
 → [API Reference](./08-api.md) — every method, every event

package/docs/08-api.md

@@ -34,12 +34,55 @@ Detach all listeners, remove canvas, release WASM views.
 
 ---
 
+## Atomic loading
+
+```js
+flow.loadGraph({ nodes, edges }) → Map<userId, zid>
+flow.findNodeByUserId(userId) → number      // -1 if not found
+flow.transaction(fn) → result
+```
+
+`loadGraph` wipes the current graph and inserts everything as one atomic operation — single `change` event, single undo snapshot. Edges resolve `from`/`to` against the `id` you put on each node (string, number, anything).
+
+**`loadGraph` shape:**
+
+```js
+{
+  nodes: [
+    { id: 'a', kind: 'service', x: 0, y: 0, title: 'A', data: {...} },
+  ],
+  edges: [
+    { from: 'a', to: 'b', fp: 0, tp: 0, label: 'next' },
+  ],
+}
+```
+
+Each node's `id` is also stashed in `node.data.__id`, so `toJSON()` / `loadJSON()` and Yjs sync preserve it. Recover the zflow numeric id from any of:
+
+```js
+const idMap = flow.loadGraph({...});
+idMap.get('a');                 // → 0
+flow.findNodeByUserId('a');     // → 0  (works after loadJSON or remote edits)
+```
+
+**`transaction(fn)`** runs `fn` with events and snapshots suspended; emits a single `change` and pushes one snapshot at the end. Safe to nest — only the outermost call commits.
+
+```js
+flow.transaction(() => {
+  for (const row of payload) flow.addNode({ kind: 'service', ...row });
+  flow.runAutoLayout();
+});
+```
+
+---
+
 ## Mutation
 
 ```js
 flow.addNode(spec) → number          // returns node id or -1
 flow.addEdge(spec) → number          // returns edge id or -1
 flow.deleteSelection()
+flow.deleteNode(id)                  // delete one node, keep rest of selection
 flow.moveNode(id, x, y)
 flow.duplicateSelection(dx = 40, dy = 40)
 flow.addNodesBulk(specs) → number[]  // bulk insert (returns ids in order)
@@ -54,6 +97,7 @@ flow.addEdgesBulk(specs) → number[]
 - `title`, `color`, `description`, `tags`, `status`, `progress`
 - `image`, `checked`, `tasks`, `icon`, `links`
 - `portIn`, `portOut` — per-node port label override
+- `data` — free-form metadata, round-tripped through serialization
 - `animate: false` — skip pop-in animation
 
 **`addEdge` spec fields:**
@@ -63,11 +107,14 @@ flow.addEdgesBulk(specs) → number[]
 - `tp: number` — target port index (default 0)
 - `label: string` — edge label
 
+> **Compaction & remapping.** When a node is deleted, zflow compacts its internal arrays so the surviving range stays contiguous starting at 0. All JS-side maps (`titles`, `colors`, `data`, `bookmarks`, `breakpoints`, `_values`, metric buffers, edge labels, etc.) are remapped automatically. You **do not** need to maintain external `logicalId → zid` tables — store your id under `data.__id` (or use `loadGraph` which does it for you) and recover it with `findNodeByUserId`.
+
 ---
 
 ## Selection
 
 ```js
+flow.setSelection([ids])            // replace entire selection
 flow.setSelected(id, on)
 flow.toggleSelected(id)
 flow.clearSelection()
@@ -93,9 +140,12 @@ flow.setNodeChecked(id, bool)
 flow.setNodeTasks(id, [{text, done}, ...])
 flow.setNodeIcon(id, glyph)
 flow.setNodeLinks(id, [{url, label}, ...])
+flow.setNodeData(id, anyObject)     // free-form metadata bag
+flow.getNodeData(id) → any
 flow.setPortInLabels(id, labels)
 flow.setPortOutLabels(id, labels)
 flow.setEdgeLabel(eid, label)
+flow.startEditTitle(id)             // open the inline title editor
 ```
 
 ---
@@ -126,6 +176,21 @@ flow.runForceLayout(maxFrames = 220)
 
 ---
 
+## Coordinate space & camera
+
+The canvas uses **world space** (the coords you pass to `addNode`) and **screen space** (CSS pixels relative to the container). The pair of helpers converts between them.
+
+```js
+flow.screenToWorld(clientX, clientY) → { x, y }    // mouse / pointer event
+flow.worldToScreen(worldX, worldY)   → { x, y }    // CSS pixels
+flow.getCamera()                     → { x, y, zoom }    // immutable snapshot
+flow.getNodePosition(id)             → { x, y, w, h } | null
+```
+
+`screenToWorld` takes raw `clientX/Y` (e.g. from a `MouseEvent`); the helper handles `devicePixelRatio` and the canvas bounding rect internally. `getCamera()` returns a copy — mutating it does not move the camera (use `panTo` / `zoomTo`).
+
+---
+
 ## Locks & read-only
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luispm/zflow-graph",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "WASM-powered node-edge graph editor + runtime. No framework. 100k nodes at 60fps. Built-in execution engine, Yjs multiplayer, WebGL renderer.",
   "type": "module",
   "main": "./dist/zflow.umd.js",
@@ -77,11 +77,11 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/luisg/zflow-graph"
+    "url": "https://github.com/LuisPadre25/zflow-graph"
   },
-  "homepage": "https://github.com/luisg/zflow-graph#readme",
+  "homepage": "https://github.com/LuisPadre25/zflow-graph#readme",
   "bugs": {
-    "url": "https://github.com/luisg/zflow-graph/issues"
+    "url": "https://github.com/LuisPadre25/zflow-graph/issues"
   },
   "engines": {
     "node": ">=18"
@@ -95,6 +95,8 @@
     "vitest": "^1.6.0"
   },
   "peerDependenciesMeta": {
-    "yjs": { "optional": true }
+    "yjs": {
+      "optional": true
+    }
   }
 }