orcasvn-diagrams

Reusable diagram editors, JSON helpers, and component-model services built on top of orcasvn-react-diagrams.

Install

npm install orcasvn-diagrams react react-dom

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

Package Surface

• Root API: orcasvn-diagrams
• React editor entrypoints: orcasvn-diagrams/editors
• Packaged styles: orcasvn-diagrams/styles.css
• Machine-readable docs manifest: orcasvn-diagrams/ai-manifest

Quick Start

import 'orcasvn-diagrams/styles.css';
import { DiagramEditor } from 'orcasvn-diagrams/editors';

export function Example() {
  return (
    <DiagramEditor
      title="Example Diagram"
      description="Host-managed reusable editor surface"
      initialState={{ elements: [], ports: [], links: [], texts: [] }}
      propertyPaneConfig={{
        enabled: false,
        emptyTitle: 'No Selection',
        emptyDescription: 'Select a diagram entity to inspect it.',
      }}
    />
  );
}

Public API Overview

• orcasvn-diagrams
  • typed JSON import/export helpers
  • component-diagram import, validation, sync, subset, and catalog services
  • shared utility services for toolbox, property pane, and context menu composition
• orcasvn-diagrams/editors
  • DiagramEditor
  • ComponentDiagramEditor
  • WebAppFeDiagramEditor
• orcasvn-diagrams/styles.css
  • bundled library UI stylesheet

Published Wrappers

• ComponentDiagramEditor persists canonical DiagramState through state / defaultState and onStateChange(nextState, meta).
• ComponentDiagramEditor also supports optional host-managed viewport, selectionIds, reloadToken, readOnly, and the narrow ref methods replaceState, zoomToFit, and exportImage.
• ComponentDiagramEditor accepts aligned direct parent-child boundary mappings from either drag direction and normalizes persisted runtime links back to the canonical parent-to-child boundary form.
• ComponentDiagramEditor opts into orcasvn-react-diagrams@^0.2.11 load-time color backfill for links that load without a usable style.stroke, while preserving explicit loaded strokes.
• ComponentDiagramEditor intentionally omits wrapper-owned outer title/description copy so host apps can render and style those lines themselves.
• WebAppFeDiagramEditor persists authored WebAppFeAuthoredDocument through document / defaultDocument and onDocumentChange(nextDocument, meta).
• WebAppFeDiagramEditor keeps runtime scaffold state internal; hosts should treat starterUnitType as a fresh create/reset seed only.
• WebAppFeDiagramEditor supports starterUnitType="web-component" and starterUnitType="code-unit"; Code Unit sessions expose boundary input/output authoring and the approved state/function auto-link flows through the packaged editor UI.
• WebAppFeDiagramEditor opts into the same ^0.2.11 missing-stroke load-time fill and persists resolved link strokes through authored-document links[].metadata.stroke so restore flows stay stable.
• WebAppFeDiagramEditor intentionally omits wrapper-owned outer title/description copy so host apps can render and style those lines themselves.
• Controlled prop echoes are synchronization, not reloads. Use reloadToken or the documented imperative replace methods when the host intentionally wants to replace the mounted editor content.
• default* props are mount-time seeds only. Changing them after mount does not replace the current document/state by itself.
• readOnly is a host-controlled runtime prop: toggling it after mount blocks authoring mutations while preserving inspection flows such as selection, viewport review, zoomToFit, and exportImage.

Host Integration Notes

• Host apps do not need to install tailwindcss.
• Host apps do need a normal CSS import pipeline and should import orcasvn-diagrams/styles.css when using public editor UI.
• The packaged UI is intended to style its own controls, menus, and panels without requiring a host-side CSS reset.
• Avoid aggressive global overrides on native controls such as button, input, select, and textarea that force browser chrome, custom borders, or custom appearance back onto descendants after the package stylesheet loads.
• If a host app uses broad global UI rules, verify packaged overlays such as context menus, toolbars, and property panes in a mounted browser flow, not only through type checks.
• react and react-dom are peer dependencies and must be provided by the host app.
• The package depends on orcasvn-react-diagrams@^0.2.11.

Reference Demos And Examples

• Public copy-paste examples live in examples/; the coverage map and deferred-scope notes live in examples/README.md.
• Browser-runnable validation for those examples lives in examples-vite/; setup and per-route verification notes live in examples-vite/README.md.
• The repository demo workspace remains the canonical richer reference-demo surface for the supported ComponentDiagramEditor and WebAppFeDiagramEditor wrappers.
• Example validation is release-tracked through npm run validate:public-examples, npm run validate:examples-vite, and npm run smoke:test-package.

Docs

• Docs index: docs/INDEX.md
• API contract: docs/API_CONTRACT.md
• Architecture: docs/ARCHITECTURE.md
• Capabilities: docs/CAPABILITIES.md
• Commands and events: docs/COMMANDS_EVENTS.md
• State invariants: docs/STATE_INVARIANTS.md
• Integration playbook: docs/INTEGRATION_PLAYBOOK.md
• Porting checklist: docs/PORTING_CHECKLIST.md
• Documentation workflow: docs/DOCUMENTATION_WORKFLOW.md
• Changelog: CHANGELOG.md