diagram-contracts 0.2.7 → 1.0.0-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -267,6 +267,18 @@ Cold start (first run, no JIT): ER Diagram 114ms / AWS 52ms. In browser Web embe
267
267
 
268
268
  Re-benchmark: `node scripts/bench.mjs --warmup 50 --iterations 200`
269
269
 
270
+ Interactive layer on a generated grid of components and boxes joined by
271
+ labelled connectors *(Node.js v22, Apple Silicon, median / p95 in parentheses)*:
272
+
273
+ | Stage | 4,481 nodes / 8,401 items | 17,921 nodes / 33,761 items |
274
+ |-------|---------------------------|-----------------------------|
275
+ | layout (for scale, one run) | 470ms | 2,452ms |
276
+ | diffArtifacts (one caption edited) | 5.4ms (9.7ms) | 31.8ms (52.7ms) |
277
+ | extractRenderItems (drawing every item's markup) | 6.5ms (13.4ms) | 55.8ms (81.1ms) |
278
+ | queryViewport, linear index (1280×800 + 300px overscan) | 0.10ms (0.12ms) | 0.46ms (1.65ms) |
279
+
280
+ Re-benchmark: `npm run build && node scripts/bench-interactive.mjs [--rows 40 --cols 25]` (the second column: `--rows 80 --cols 50`)
281
+
270
282
  ## CLI
271
283
 
272
284
  ```bash
@@ -324,6 +336,109 @@ const { artifact } = layout(ir, { tokens: {}, theme: { defaults: {}, variants: {
324
336
  const svgString = renderSvg(artifact);
325
337
  ```
326
338
 
339
+ ### Editing input: the Draw DSL tree
340
+
341
+ An editor keeps the **Draw DSL tree** — the diagram before components are
342
+ expanded — and re-renders it on every change. Import a source once, assigning
343
+ ids to every node, and keep the result:
344
+
345
+ ```typescript
346
+ import {
347
+ compileDrawTsx, parseDrawText, assignDslIds, createDslIdGenerator,
348
+ expandDsl, layout, renderSvg, defaultTokens, defaultTheme,
349
+ } from "diagram-contracts";
350
+
351
+ const { dsl, components } = compileDrawTsx(tsxSource); // or parseDrawText(textSource).dsl
352
+ const tree = assignDslIds(dsl, components); // ids are stored; inserting nodes never renumbers them
353
+ const newId = createDslIdGenerator(tree); // ids for nodes the editor adds: newId("box")
354
+
355
+ const ir = expandDsl(tree, components, []);
356
+ const { artifact } = layout(ir, { tokens: defaultTokens(), theme: defaultTheme() });
357
+ const svg = renderSvg(artifact, { interactive: true });
358
+ ```
359
+
360
+ With `interactive`, every node group carries `data-kind`, `data-id` and
361
+ `data-owner` — the id of the DSL node it came from (a node inside a component
362
+ reports the component's id) — plus an invisible hit area marked `data-role="hit"`:
363
+ a rect for a node, the path widened to a stroke for a connector.
364
+ Every DSL node must have an id. Without `interactive` the output is unchanged.
365
+
366
+ ### Interactive canvas: `createDiagramCanvas`
367
+
368
+ `diagram-contracts/interactive` draws a Draw DSL tree into the page and reports
369
+ what the user does to it. The application keeps the document and the
370
+ selection; the canvas keeps nothing of the document but its last layout:
371
+
372
+ ```typescript
373
+ import { createDiagramCanvas } from "diagram-contracts/interactive";
374
+
375
+ const canvas = createDiagramCanvas(mount, {
376
+ components, // the component definitions the tree's tags expand with
377
+ onEvent(event) { // NodeClick, ConnectorClick, Hover, NodeDrop, ConnectStart, ConnectEnd, NodeEdit
378
+ if (event.type === "NodeClick") selection = event.nodeId ? [event.nodeId] : [];
379
+ if (event.type === "NodeDrop") tree = move(tree, event.nodeId, event.parentId, event.index);
380
+ canvas.update(tree, { selection });
381
+ },
382
+ });
383
+ canvas.update(tree, { selection }); // the whole tree, every time; returns the diagnostics
384
+ canvas.setView({ x: 0, y: 0, zoom: 1.5 }); // pan / zoom: no layout
385
+ ```
386
+
387
+ - **Redrawing.** `update` lays the tree out again and redraws only the elements
388
+ whose drawing changed; every other DOM node stays as it was. The same input
389
+ always gives the same picture — the one `renderSvg` draws, painted in the
390
+ same order.
391
+ - **Events.** One listener on the SVG root. A pointer resolves to a Draw DSL
392
+ node — a component is one unit: a click inside it reports the component tag.
393
+ `NodeDrop` gives the new parent and the index among its children (counted
394
+ without the moved node); only an element that can hold the node is a target
395
+ (not `grid` / `flow` / `absolute`). Nothing is laid out while dragging.
396
+ - **Capabilities.** A node raises only the events it declares in
397
+ `interactions`: `selectable` (clicks, hover), `draggable` (`NodeDrop`),
398
+ `connectable` (connections, started on the band along its edge),
399
+ `editable` (double-click → `NodeEdit`). A node that declares nothing raises
400
+ nothing; a click on it goes to the nearest selectable node around it.
401
+ - **Overlay.** The selection passed to `update`, hover, the dragged node's
402
+ shadow and where it would go are drawn over the diagram, never into the
403
+ artifact (`canvas.artifact`) nor into what `renderSvg` writes from it.
404
+ - **View.** Only the items in view (plus a 300px overscan) are in the DOM;
405
+ text drawn smaller than it can be read is left out. The visible area follows
406
+ the mount's size.
407
+
408
+ `samples/interactive-canvas.html` is a working page: `npm run build`, serve
409
+ the repository root (`python3 -m http.server`) and open it.
410
+
411
+ ### Interactive layer: `diagram-contracts/interactive`
412
+
413
+ On every edit the editor lays the whole tree out again; the interactive layer
414
+ works out what to redraw and what is in view:
415
+
416
+ ```typescript
417
+ import { diffArtifacts, extractRenderItems, createLinearIndex, queryViewport } from "diagram-contracts/interactive";
418
+
419
+ const diff = diffArtifacts(previousArtifact, artifact);
420
+ // diff.added / diff.removed / diff.changed: keys of the nodes to create, remove and redraw;
421
+ // diff.documentChanged: the viewBox or background changed; diff.reordered: the paint order changed.
422
+
423
+ const items = extractRenderItems(artifact); // what each node draws (as renderSvg does) + its hit area, in paint order
424
+ const index = createLinearIndex(items);
425
+ const visible = queryViewport(index, { x: 0, y: 0, width: 1280, height: 800 }, { overscan: 300 });
426
+ ```
427
+
428
+ - A node is keyed by its DSL id; a node from a component template by its
429
+ component tag's id and its position in the template. A node is reported as
430
+ changed only when what it looks like changes (position, size, path, styles,
431
+ text, hit area).
432
+ - A connector yields separate items for its line, its labels and its hit
433
+ stroke, each with its own bounds, so culling keeps whichever reaches into
434
+ the viewport. Items carry a `layer` — `drawing` (everything drawn, in the
435
+ order `renderSvg` paints it) or `hit` (`RENDER_LAYERS` gives the full
436
+ back-to-front order) — and their SVG `markup`.
437
+ A node that draws nothing by itself has only its hit item; a table also
438
+ yields a `frame` item painted over its cells.
439
+ - `queryViewport` takes any `SpatialIndex` (`query(area)`); the linear index can
440
+ be swapped for an R-tree, grid or quadtree. `overscan` defaults to 300px.
441
+
327
442
  ## Browser
328
443
 
329
444
  ```html