orcasvn-react-diagrams 0.2.1 → 0.2.2

package/README.md

@@ -1,88 +1,99 @@
-# 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/`.
+# 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: `>=20.17.0 <21.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',
+});
+```
+
+## Release Highlights (v0.2.2)
+
+- Includes all completed `v0.2.1` work plus `v0.2.2` additions in one release.
+- Shape system upgrade:
+  - class-based built-in shape behaviors
+  - runtime removal of `boundaryKind` branching
+  - additive rotation (`baseRotation` + instance rotation style)
+- Port movement enhancements:
+  - shape-aware border projection
+  - optional anchor-constrained movement (`portMovement.moveMode = 'anchors'`)
+  - orientation support with host-border normals and resize reprojection
+- Shape hover controls:
+  - generic control definitions with `targetKind` (`edge`, `vertex`, `midpoint`, `ellipse-midpoint`)
+  - trigger modes (`element-hover`, `target-hover`)
+  - interaction callbacks for click and drag lifecycle
+- Text layout improvements:
+  - owner/fixed bounds modes, wrap and overflow controls, and layout padding
+  - `textUpdated` lifecycle event with rendered display content
+- Additional lifecycle events:
+  - `portDeleted`, `linkDeleted`, `textDeleted`
+
+## 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,257 @@
-{
-  "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.2.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'",
+        "elementShapeHoverControls": "ElementShapeHoverControls",
+        "onElementShapeHoverControlInteraction": "(event: ElementShapeHoverControlInteractionEvent) => void",
+        "onElementShapeHoverControlActivated": "(event: ElementShapeHoverControlActivationEvent) => void",
+        "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",
+        "portMovement"
+      ],
+      "defaults": {
+        "portIds": [],
+        "textIds": [],
+        "parentId": null
+      }
+    },
+    "portData": {
+      "required": [
+        "id",
+        "elementId",
+        "position"
+      ],
+      "optional": [
+        "shapeId",
+        "size",
+        "style",
+        "textIds",
+        "moveMode",
+        "anchorCenter",
+        "orientToHostBorder",
+        "currentAnchorId"
+      ],
+      "defaults": {
+        "textIds": [],
+        "anchorCenter": true,
+        "orientToHostBorder": true
+      }
+    },
+    "linkData": {
+      "required": [
+        "id",
+        "sourcePortId",
+        "targetPortId",
+        "points"
+      ],
+      "optional": [
+        "routing",
+        "style",
+        "textIds"
+      ],
+      "defaults": {
+        "routing": "auto",
+        "textIds": []
+      }
+    },
+    "textData": {
+      "required": [
+        "id",
+        "content",
+        "position"
+      ],
+      "optional": [
+        "size",
+        "style",
+        "ownerId",
+        "layout",
+        "displayContent",
+        "displayOffset",
+        "displayClipSize"
+      ],
+      "defaults": {
+        "ownerId": null
+      }
+    },
+    "elementLayoutDefaults": {
+      "padding": 12,
+      "gap": 12,
+      "align": "center"
+    }
+  },
+  "additionalContracts": {
+    "portMovementPolicy": {
+      "moveMode": "'free' | 'inside' | 'border' | 'anchors'",
+      "anchorConstraint": "PortAnchorConstraint"
+    },
+    "portAnchorConstraint": {
+      "preset": "'vertices' | 'cardinal'",
+      "fallback": "'nearest'"
+    },
+    "textLayout": {
+      "boundsMode": "'owner-width' | 'owner-box' | 'fixed'",
+      "wrap": "'none' | 'word' | 'char'",
+      "overflow": "'clip' | 'ellipsis-end' | 'ellipsis-middle' | 'ellipsis-start'",
+      "padding": "number",
+      "maxLines": "number",
+      "fixedSize": "Size"
+    },
+    "shapeHoverControls": {
+      "targetKinds": [
+        "vertex",
+        "edge",
+        "midpoint",
+        "ellipse-midpoint"
+      ],
+      "visibilityTriggers": [
+        "element-hover",
+        "target-hover"
+      ],
+      "interactionEventTypes": [
+        "click",
+        "drag-start",
+        "drag-move",
+        "drag-end"
+      ]
+    }
+  },
+  "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",
+      "setElementShapeHoverControls",
+      "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",
+    "portDeleted": "PortDeletedEvent",
+    "linkDeleted": "LinkDeletedEvent",
+    "textDeleted": "TextDeletedEvent",
+    "textUpdated": "TextUpdatedEvent",
+    "elementSelected": "ElementSelectedEvent",
+    "elementLinkStarted": "ElementLinkStartedEvent",
+    "elementLinkConnecting": "ElementLinkConnectingEvent",
+    "elementLinkEnded": "ElementLinkEndedEvent",
+    "textSelected": "TextSelectedEvent"
+  }
+}