orcasvn-react-diagrams 0.2.0 → 0.2.1

package/README.md

@@ -1,78 +1,88 @@
-# orcasvn-react-diagrams
-
-Diagram editor library with a Konva-backed editor (`createDiagramEditor`) and an engine-only API (`createDiagramEngine`).
-
-## Install
-
-```bash
-npm install orcasvn-react-diagrams
-```
-
-Node engine for this repository/toolchain: `>=18.17.0 <19.0.0`.
-
-## Quick Start
-
-```ts
-import { createDiagramEditor } from 'orcasvn-react-diagrams';
-
-const editor = createDiagramEditor({
-  container: document.getElementById('diagram-root') as HTMLDivElement,
-  width: 960,
-  height: 600,
-  initialState: { elements: [], ports: [], links: [], texts: [] },
-});
-
-editor.addElement({
-  id: 'node-1',
-  position: { x: 80, y: 80 },
-  size: { width: 160, height: 100 },
-  shapeId: 'default',
-});
-```
-
-## API Docs
-
-- Human-first docs index: `docs/INDEX.md`
-- API contract: `docs/API_CONTRACT.md`
-- State invariants: `docs/STATE_INVARIANTS.md`
-- Integration: `docs/INTEGRATION_PLAYBOOK.md`
-
-Machine-readable docs shipped in npm package:
-
-- `ai/manifest.json`
-- `ai/api-contract.json`
-- `ai/invariants.json`
-
-UNPKG examples:
-
-- `https://unpkg.com/orcasvn-react-diagrams@<version>/ai/manifest.json`
-- `https://unpkg.com/orcasvn-react-diagrams@<version>/docs/INDEX.md`
-
-Node subpath export:
-
-- `orcasvn-react-diagrams/ai-manifest`
-
-## External Drag And Drop
-
-```ts
-const world = editor.clientToWorld(
-  { x: event.clientX, y: event.clientY },
-  stageContainer
-);
-
-editor.addElement({
-  id,
-  position: { x: world.x - width / 2, y: world.y - height / 2 },
-  size: { width, height },
-  shapeId,
-});
-```
-
-## Scripts (Repository Development)
-
-- `npm start`: run demo app.
-- `npm run start-doc`: serve `analysis/`.
-- `npm test`: run tests (watch mode).
-- `npm run typecheck`: run TypeScript checks.
-- `npm run build`: CRA build to `build/`.
-- `npm run rollup-build-lib`: library build to `dist/`.
+# orcasvn-react-diagrams
+
+Diagram editor library with a Konva-backed editor (`createDiagramEditor`) and an engine-only API (`createDiagramEngine`).
+
+## Install
+
+```bash
+npm install orcasvn-react-diagrams
+```
+
+Node engine for this repository/toolchain: `>=18.17.0 <19.0.0`.
+
+## Quick Start
+
+```ts
+import { createDiagramEditor } from 'orcasvn-react-diagrams';
+
+const editor = createDiagramEditor({
+  container: document.getElementById('diagram-root') as HTMLDivElement,
+  width: 960,
+  height: 600,
+  initialState: { elements: [], ports: [], links: [], texts: [] },
+});
+
+editor.addElement({
+  id: 'node-1',
+  position: { x: 80, y: 80 },
+  size: { width: 160, height: 100 },
+  shapeId: 'default',
+});
+```
+
+## DisplayBox Review Surface
+
+The published package also exposes the full demo review surface used by this repository's hosted example app:
+
+```ts
+import { DisplayBox, demoTabs } from 'orcasvn-react-diagrams/displaybox';
+```
+
+Use this entrypoint when you want to review the packaged demo scenarios from an installed npm dependency instead of importing repository source files directly.
+
+## API Docs
+
+- Human-first docs index: `docs/INDEX.md`
+- API contract: `docs/API_CONTRACT.md`
+- State invariants: `docs/STATE_INVARIANTS.md`
+- Integration: `docs/INTEGRATION_PLAYBOOK.md`
+
+Machine-readable docs shipped in npm package:
+
+- `ai/manifest.json`
+- `ai/api-contract.json`
+- `ai/invariants.json`
+
+UNPKG examples:
+
+- `https://unpkg.com/orcasvn-react-diagrams@<version>/ai/manifest.json`
+- `https://unpkg.com/orcasvn-react-diagrams@<version>/docs/INDEX.md`
+
+Node subpath export:
+
+- `orcasvn-react-diagrams/ai-manifest`
+
+## External Drag And Drop
+
+```ts
+const world = editor.clientToWorld(
+  { x: event.clientX, y: event.clientY },
+  stageContainer
+);
+
+editor.addElement({
+  id,
+  position: { x: world.x - width / 2, y: world.y - height / 2 },
+  size: { width, height },
+  shapeId,
+});
+```
+
+## Scripts (Repository Development)
+
+- `npm start`: run demo app.
+- `npm run start-doc`: serve `analysis/`.
+- `npm test`: run tests (watch mode).
+- `npm run typecheck`: run TypeScript checks.
+- `npm run build`: CRA build to `build/`.
+- `npm run rollup-build-lib`: library build to `dist/`.

package/ai/api-contract.json

@@ -1,205 +1,205 @@
-{
-  "schemaVersion": "1.1.0",
-  "typeSource": "src/api/types.ts",
-  "entrypoints": [
-    {
-      "name": "createDiagramEditor",
-      "source": "src/api/createDiagramEditor.ts",
-      "returns": "DiagramEditorHandle"
-    },
-    {
-      "name": "createDiagramEngine",
-      "source": "src/engine/DiagramEngine.ts",
-      "returns": "DiagramEngineHandle"
-    }
-  ],
-  "configs": {
-    "diagramEditorConfig": {
-      "required": {
-        "container": "HTMLDivElement | string"
-      },
-      "optional": {
-        "width": "number",
-        "height": "number",
-        "initialState": "DiagramState",
-        "elementShapes": "SimpleShape[]",
-        "portShapes": "SimpleShape[]",
-        "panKey": "'Control' | 'Shift' | 'Alt' | 'Meta'",
-        "onChange": "(event: EngineChangeEvent) => void",
-        "onSelection": "(event: EngineSelectionEvent) => void"
-      },
-      "defaults": {
-        "width": 900,
-        "height": 560,
-        "panKey": "Control"
-      }
-    },
-    "diagramEngineConfig": {
-      "required": {
-        "renderer": "Renderer"
-      },
-      "optional": {
-        "scheduler": "RenderScheduler",
-        "router": "RouterStrategy",
-        "snapper": "SnapStrategy",
-        "shapeRegistry": "ShapeRegistry",
-        "textMeasurer": "TextMeasurer"
-      },
-      "defaults": {
-        "scheduler": "RenderScheduler",
-        "router": "ObstacleRouter",
-        "snapper": "DefaultSnapper",
-        "shapeRegistry": "ShapeRegistry",
-        "textMeasurer": "CanvasTextMeasurer"
-      }
-    }
-  },
-  "stateTypes": {
-    "diagramState": {
-      "required": [
-        "elements",
-        "ports",
-        "links",
-        "texts"
-      ]
-    },
-    "elementData": {
-      "required": [
-        "id",
-        "position",
-        "size",
-        "shapeId"
-      ],
-      "optional": [
-        "style",
-        "portIds",
-        "textIds",
-        "parentId",
-        "moveMode",
-        "anchorCenter",
-        "layout"
-      ],
-      "defaults": {
-        "portIds": [],
-        "textIds": [],
-        "parentId": null
-      }
-    },
-    "portData": {
-      "required": [
-        "id",
-        "elementId",
-        "position"
-      ],
-      "optional": [
-        "shapeId",
-        "size",
-        "style",
-        "textIds",
-        "moveMode",
-        "anchorCenter"
-      ],
-      "defaults": {
-        "textIds": [],
-        "anchorCenter": true
-      }
-    },
-    "linkData": {
-      "required": [
-        "id",
-        "sourcePortId",
-        "targetPortId",
-        "points"
-      ],
-      "optional": [
-        "routing",
-        "style",
-        "textIds"
-      ],
-      "defaults": {
-        "routing": "auto",
-        "textIds": []
-      }
-    },
-    "textData": {
-      "required": [
-        "id",
-        "content",
-        "position"
-      ],
-      "optional": [
-        "size",
-        "style",
-        "ownerId"
-      ],
-      "defaults": {
-        "ownerId": null
-      }
-    },
-    "elementLayoutDefaults": {
-      "padding": 12,
-      "gap": 12,
-      "align": "center"
-    }
-  },
-  "handleMethods": {
-    "shared": [
-      "load",
-      "getState",
-      "getViewport",
-      "clientToWorld",
-      "createOverlayShape",
-      "on",
-      "addElement",
-      "moveElementTo",
-      "resizeElement",
-      "setElementLayout",
-      "removeElement",
-      "addPortToElement",
-      "movePortTo",
-      "removePort",
-      "addLink",
-      "updateLinkPoints",
-      "setLinkRoutingMode",
-      "rerouteAllLinks",
-      "rerouteLinks",
-      "removeLink",
-      "addText",
-      "updateText",
-      "moveTextTo",
-      "removeText",
-      "setSelection",
-      "setViewport",
-      "setRouting",
-      "setSnapping",
-      "registerShape",
-      "render"
-    ],
-    "editorOnly": [
-      "resize",
-      "destroy"
-    ]
-  },
-  "events": {
-    "change": "EngineChangeEvent",
-    "selection": "EngineSelectionEvent",
-    "config": "EngineConfigEvent",
-    "element-drop": "ElementDropEvent",
-    "elementDrop": "ElementDropEvent",
-    "paperClick": "PaperClickEvent",
-    "portMouseDown": "PortMouseEvent",
-    "portMouseUp": "PortMouseEvent",
-    "portMoved": "PortMovedEvent",
-    "portSelected": "PortSelectedEvent",
-    "elementClick": "ElementPointerEvent",
-    "elementDragged": "ElementDropEvent",
-    "elementMoved": "ElementMovedEvent",
-    "elementResized": "ElementResizedEvent",
-    "elementDeleted": "ElementDeletedEvent",
-    "elementSelected": "ElementSelectedEvent",
-    "elementLinkStarted": "ElementLinkStartedEvent",
-    "elementLinkConnecting": "ElementLinkConnectingEvent",
-    "elementLinkEnded": "ElementLinkEndedEvent",
-    "textSelected": "TextSelectedEvent"
-  }
-}
+{
+  "schemaVersion": "1.1.0",
+  "typeSource": "src/api/types.ts",
+  "entrypoints": [
+    {
+      "name": "createDiagramEditor",
+      "source": "src/api/createDiagramEditor.ts",
+      "returns": "DiagramEditorHandle"
+    },
+    {
+      "name": "createDiagramEngine",
+      "source": "src/engine/DiagramEngine.ts",
+      "returns": "DiagramEngineHandle"
+    }
+  ],
+  "configs": {
+    "diagramEditorConfig": {
+      "required": {
+        "container": "HTMLDivElement | string"
+      },
+      "optional": {
+        "width": "number",
+        "height": "number",
+        "initialState": "DiagramState",
+        "elementShapes": "SimpleShape[]",
+        "portShapes": "SimpleShape[]",
+        "panKey": "'Control' | 'Shift' | 'Alt' | 'Meta'",
+        "onChange": "(event: EngineChangeEvent) => void",
+        "onSelection": "(event: EngineSelectionEvent) => void"
+      },
+      "defaults": {
+        "width": 900,
+        "height": 560,
+        "panKey": "Control"
+      }
+    },
+    "diagramEngineConfig": {
+      "required": {
+        "renderer": "Renderer"
+      },
+      "optional": {
+        "scheduler": "RenderScheduler",
+        "router": "RouterStrategy",
+        "snapper": "SnapStrategy",
+        "shapeRegistry": "ShapeRegistry",
+        "textMeasurer": "TextMeasurer"
+      },
+      "defaults": {
+        "scheduler": "RenderScheduler",
+        "router": "ObstacleRouter",
+        "snapper": "DefaultSnapper",
+        "shapeRegistry": "ShapeRegistry",
+        "textMeasurer": "CanvasTextMeasurer"
+      }
+    }
+  },
+  "stateTypes": {
+    "diagramState": {
+      "required": [
+        "elements",
+        "ports",
+        "links",
+        "texts"
+      ]
+    },
+    "elementData": {
+      "required": [
+        "id",
+        "position",
+        "size",
+        "shapeId"
+      ],
+      "optional": [
+        "style",
+        "portIds",
+        "textIds",
+        "parentId",
+        "moveMode",
+        "anchorCenter",
+        "layout"
+      ],
+      "defaults": {
+        "portIds": [],
+        "textIds": [],
+        "parentId": null
+      }
+    },
+    "portData": {
+      "required": [
+        "id",
+        "elementId",
+        "position"
+      ],
+      "optional": [
+        "shapeId",
+        "size",
+        "style",
+        "textIds",
+        "moveMode",
+        "anchorCenter"
+      ],
+      "defaults": {
+        "textIds": [],
+        "anchorCenter": true
+      }
+    },
+    "linkData": {
+      "required": [
+        "id",
+        "sourcePortId",
+        "targetPortId",
+        "points"
+      ],
+      "optional": [
+        "routing",
+        "style",
+        "textIds"
+      ],
+      "defaults": {
+        "routing": "auto",
+        "textIds": []
+      }
+    },
+    "textData": {
+      "required": [
+        "id",
+        "content",
+        "position"
+      ],
+      "optional": [
+        "size",
+        "style",
+        "ownerId"
+      ],
+      "defaults": {
+        "ownerId": null
+      }
+    },
+    "elementLayoutDefaults": {
+      "padding": 12,
+      "gap": 12,
+      "align": "center"
+    }
+  },
+  "handleMethods": {
+    "shared": [
+      "load",
+      "getState",
+      "getViewport",
+      "clientToWorld",
+      "createOverlayShape",
+      "on",
+      "addElement",
+      "moveElementTo",
+      "resizeElement",
+      "setElementLayout",
+      "removeElement",
+      "addPortToElement",
+      "movePortTo",
+      "removePort",
+      "addLink",
+      "updateLinkPoints",
+      "setLinkRoutingMode",
+      "rerouteAllLinks",
+      "rerouteLinks",
+      "removeLink",
+      "addText",
+      "updateText",
+      "moveTextTo",
+      "removeText",
+      "setSelection",
+      "setViewport",
+      "setRouting",
+      "setSnapping",
+      "registerShape",
+      "render"
+    ],
+    "editorOnly": [
+      "resize",
+      "destroy"
+    ]
+  },
+  "events": {
+    "change": "EngineChangeEvent",
+    "selection": "EngineSelectionEvent",
+    "config": "EngineConfigEvent",
+    "element-drop": "ElementDropEvent",
+    "elementDrop": "ElementDropEvent",
+    "paperClick": "PaperClickEvent",
+    "portMouseDown": "PortMouseEvent",
+    "portMouseUp": "PortMouseEvent",
+    "portMoved": "PortMovedEvent",
+    "portSelected": "PortSelectedEvent",
+    "elementClick": "ElementPointerEvent",
+    "elementDragged": "ElementDropEvent",
+    "elementMoved": "ElementMovedEvent",
+    "elementResized": "ElementResizedEvent",
+    "elementDeleted": "ElementDeletedEvent",
+    "elementSelected": "ElementSelectedEvent",
+    "elementLinkStarted": "ElementLinkStartedEvent",
+    "elementLinkConnecting": "ElementLinkConnectingEvent",
+    "elementLinkEnded": "ElementLinkEndedEvent",
+    "textSelected": "TextSelectedEvent"
+  }
+}

package/ai/invariants.json

@@ -1,41 +1,41 @@
-{
-  "stateShape": [
-    "elements[]",
-    "ports[]",
-    "links[]",
-    "texts[]"
-  ],
-  "defaults": {
-    "port.anchorCenter": true,
-    "link.routing": "auto"
-  },
-  "entityRules": {
-    "element": [
-      "child element positions are parent-relative when parentId is set",
-      "deleting an element removes its ports, links via ports, and owned texts"
-    ],
-    "port": [
-      "port positions are relative to element",
-      "moving a port can be constrained by moveMode/moveAxis/moveBounds"
-    ],
-    "link": [
-      "manual routing preserves interior bend points on endpoint updates",
-      "auto routing normalizes first/last points to source/target port world positions"
-    ],
-    "text": [
-      "owner-bound text stores owner-relative position",
-      "orphan owner references are tolerated as standalone world text"
-    ]
-  },
-  "eventRules": [
-    "mutations emit change with patches and full state snapshot",
-    "setSelection emits selection plus derived selected entity events",
-    "setViewport emits viewport patch without immediate render"
-  ],
-  "verificationTests": [
-    "src/models/__tests__/DiagramModel.test.ts",
-    "src/engine/__tests__/DiagramEngine.test.ts",
-    "src/renderer/konva/__tests__/KonvaInteraction.test.ts"
-  ]
-}
-
+{
+  "stateShape": [
+    "elements[]",
+    "ports[]",
+    "links[]",
+    "texts[]"
+  ],
+  "defaults": {
+    "port.anchorCenter": true,
+    "link.routing": "auto"
+  },
+  "entityRules": {
+    "element": [
+      "child element positions are parent-relative when parentId is set",
+      "deleting an element removes its ports, links via ports, and owned texts"
+    ],
+    "port": [
+      "port positions are relative to element",
+      "moving a port can be constrained by moveMode/moveAxis/moveBounds"
+    ],
+    "link": [
+      "manual routing preserves interior bend points on endpoint updates",
+      "auto routing normalizes first/last points to source/target port world positions"
+    ],
+    "text": [
+      "owner-bound text stores owner-relative position",
+      "orphan owner references are tolerated as standalone world text"
+    ]
+  },
+  "eventRules": [
+    "mutations emit change with patches and full state snapshot",
+    "setSelection emits selection plus derived selected entity events",
+    "setViewport emits viewport patch without immediate render"
+  ],
+  "verificationTests": [
+    "src/models/__tests__/DiagramModel.test.ts",
+    "src/engine/__tests__/DiagramEngine.test.ts",
+    "src/renderer/konva/__tests__/KonvaInteraction.test.ts"
+  ]
+}
+