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 +115 -0
- package/dist/cli.mjs +573 -461
- package/dist/diagram-contracts.browser.mjs +18763 -18649
- package/dist/index.d.ts +109 -858
- package/dist/index.mjs +594 -461
- package/dist/interactive.d.ts +355 -0
- package/dist/interactive.mjs +5521 -0
- package/dist/types-Di6zXSmH.d.ts +888 -0
- package/package.json +6 -2
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
|