orcasvn-react-diagrams

Diagram editor library with a Konva-backed editor (createDiagramEditor) and an engine-only API (createDiagramEngine).

Install

npm install orcasvn-react-diagrams

Node engine for this repository/toolchain: >=20.17.0 <21.0.0.

Quick Start

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.12)

• Includes all completed v0.2.1 through v0.2.11 work, plus v0.2.12 updates.
• v0.2.12 link labels via owned text:
  • create a link label with addText({ ..., ownerId: linkId })
  • link-owned text is stored midpoint-relative, so labels stay attached when the link reroutes or endpoints move
  • no separate LinkData.label or LinkData.labels field is required
• v0.2.12 link-created target port customization:
  • createDiagramEditor({ onCreateLinkTargetPort }) lets hosts shape auto-created destination ports for link-to-element completion
  • the callback runs for both pointer drag and programmatic completeLinkToElement(...), in preview and commit phases
  • elementLinkConnecting remains the cancellation surface; the callback customizes the target-port draft only

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

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/.