orcasvn-react-diagrams 0.2.11 → 0.2.13

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to this project are documented in this file.
 
+## [0.2.13] - 2026-07-07
+
+### Added
+- Host-callable `focusElement(elementId, options?)` editor helper for centering one target element and optionally applying an explicit zoom.
+- Observational `elementDoubleClick` event for element-body double click / double tap without replacing ordinary click selection or text-edit precedence.
+- Cancellable `elementDeleting`, `portDeleting`, `linkDeleting`, and `textDeleting` lifecycle events that fire before direct, selection-driven, or cascade removals commit.
+
+### Changed
+- Delete requests now evaluate the full cascade plan before mutation commit, so a veto from any dependent `...Deleting` handler aborts that root delete request while unrelated selected roots can still continue deleting.
+- `focusElement(...)` resolves nested and hidden elements by explicit id, preserves the current zoom by default, and uses the same viewport patch path as `setViewport(...)`.
+
+### Docs
+- Updated release highlights, architecture/API/event docs, integration guidance, and machine-readable contract/invariant metadata for `v0.2.13`.
+
+## [0.2.12] - 2026-06-26
+
+### Added
+- Optional `onCreateLinkTargetPort(context)` editor config callback for customizing the auto-created destination port when a link completes onto an element body.
+- Supported link labels through ordinary link-owned `TextData` (`ownerId = link.id`) without introducing a separate `LinkData.label` field.
+
+### Changed
+- Link-to-element placeholder preview, pointer-drop commit, and programmatic `completeLinkToElement(...)` now share the same target-port draft resolution and normalization flow before `elementLinkConnecting` runs.
+- Link-owned text now behaves as an explicit public label contract: midpoint-relative positioning is preserved across drag, reroute, export-fit bounds, and link-removal cascade deletion.
+
+### Docs
+- Updated release highlights, API/integration docs, state invariants, and machine-readable contract metadata for `v0.2.12`.
+
 ## [0.2.11] - 2026-06-20
 
 ### Added

package/README.md

@@ -30,13 +30,21 @@ editor.addElement({
 });
 ```
 
-## Release Highlights (v0.2.11)
-
-- Includes all completed `v0.2.1` through `v0.2.10` work, plus `v0.2.11` updates.
-- `v0.2.11` link color pool load-time fill:
-  - `linkColorPoolPolicy.assignOnLoadWhenMissingStroke = true` backfills loaded links whose `style.stroke` is missing, `null`, or blank after trimming
-  - explicit non-empty loaded `style.stroke` values are preserved exactly as loaded
-  - the fill uses normalized custom `colors` when provided, otherwise the built-in 20-color pool
+## Release Highlights (v0.2.13)
+
+- Includes all completed `v0.2.1` through `v0.2.12` work, plus `v0.2.13` updates.
+- `v0.2.13` delete lifecycle guards:
+  - subscribe to `elementDeleting`, `portDeleting`, `linkDeleting`, or `textDeleting` to inspect a delete request before it commits
+  - each guard receives `trigger`, `root`, `cancel()`, and `cancelled` so hosts can veto direct, selection, or cascade removals
+  - a veto aborts the current root delete request without preventing unrelated selected roots from continuing
+- `v0.2.13` viewport navigation helper:
+  - `focusElement(elementId, options?)` centers one target element by id
+  - current zoom is preserved by default, or hosts may pass `zoom`
+  - nested and hidden elements still resolve through the same world-position logic as the rest of the editor
+- `v0.2.13` element double click event:
+  - subscribe to `elementDoubleClick` to observe double click / double tap on element bodies
+  - ordinary click selection still works as before
+  - text double click continues to prioritize built-in text editing
 
 ## API Docs
 

package/ai/api-contract.json

@@ -28,6 +28,7 @@
         "elementShapeHoverControls": "ElementShapeHoverControls",
         "onElementShapeHoverControlInteraction": "(event: ElementShapeHoverControlInteractionEvent) => void",
         "onElementShapeHoverControlActivated": "(event: ElementShapeHoverControlActivationEvent) => void",
+        "onCreateLinkTargetPort": "(context: LinkTargetPortCreationContext) => Partial<LinkTargetPortDraft> | void",
         "onChange": "(event: EngineChangeEvent) => void",
         "onSelection": "(event: EngineSelectionEvent) => void",
         "linkRouteRefreshPolicy": "LinkRouteRefreshPolicy",
@@ -138,6 +139,11 @@
       "defaults": {
         "routing": "auto",
         "textIds": []
+      },
+      "ownershipSemantics": {
+        "linkLabels": "Represent link labels as TextData with ownerId = link.id",
+        "linkTextIds": "LinkData.textIds is the owner-side index only",
+        "dedicatedLabelField": "No LinkData.label or LinkData.labels field"
       }
     },
     "textData": {
@@ -158,6 +164,12 @@
       ],
       "defaults": {
         "ownerId": null
+      },
+      "ownershipSemantics": {
+        "elementOwnedPosition": "owner-relative local position",
+        "portOwnedPosition": "owner-relative local position",
+        "linkOwnedPosition": "local offset from the owning link midpoint",
+        "missingOwner": "falls back to standalone world-position text"
       }
     },
     "elementLayoutDefaults": {
@@ -202,7 +214,8 @@
       "overflow": "'clip' | 'ellipsis-end' | 'ellipsis-middle' | 'ellipsis-start'",
       "padding": "number",
       "maxLines": "number",
-      "fixedSize": "Size"
+      "fixedSize": "Size",
+      "linkOwnedDefault": "link-owned text does not implicitly default to owner-width or owner-box bounds"
     },
     "textInteractionPolicy": {
       "movable": "boolean",
@@ -262,6 +275,42 @@
       "assignOnLoadWhenMissingStroke": "boolean",
       "defaultPoolSize": 20
     },
+    "linkTargetPortCreation": {
+      "phase": "'preview' | 'commit'",
+      "draft": "Omit<PortData, 'id' | 'elementId'>",
+      "context": {
+        "phase": "LinkTargetPortCreationPhase",
+        "pointer": "Point",
+        "sourcePortId": "string",
+        "sourceElementId": "string",
+        "targetElementId": "string",
+        "sourcePort": "PortData",
+        "targetElement": "ElementData",
+        "defaultPort": "LinkTargetPortDraft"
+      },
+      "result": "Partial<LinkTargetPortDraft> | void",
+      "behavior": [
+        "runs only for link-to-element completion, not port-to-port linking or direct addPortToElement",
+        "preview and commit both invoke the callback before final target-port normalization against the target element",
+        "elementLinkConnecting remains the only cancellation surface"
+      ]
+    },
+    "linkLabelOwnership": {
+      "creation": "Create a link label with addText({ ownerId: linkId, ... })",
+      "storage": "Persist TextData.position as midpoint-relative local offset for link-owned text",
+      "rerouteBehavior": "Keep the stored local offset and recompute world position from the latest link midpoint",
+      "events": [
+        "textUpdated",
+        "textDeleted"
+      ]
+    },
+    "focusElementOptions": {
+      "zoom": "number",
+      "behavior": [
+        "omitted zoom preserves the current viewport zoom",
+        "provided zoom is clamped to the same normalized fit-zoom bounds"
+      ]
+    },
     "viewportFitOptions": {
       "padding": "number",
       "minZoom": "number",
@@ -281,6 +330,40 @@
       "beforeGridTemplate": "number[]",
       "afterGridTemplate": "number[]"
     },
+    "elementDoubleClickEvent": {
+      "elementId": "string",
+      "pointer": "EnginePointerInfo",
+      "isMulti": "boolean"
+    },
+    "deletionLifecycle": {
+      "trigger": "'direct' | 'selection' | 'cascade'",
+      "root": {
+        "entity": "'element' | 'port' | 'link' | 'text'",
+        "id": "string"
+      },
+      "sharedFields": [
+        "trigger",
+        "root",
+        "cancel",
+        "cancelled"
+      ],
+      "elementDeleting": {
+        "elementId": "string"
+      },
+      "portDeleting": {
+        "portId": "string",
+        "elementId": "string"
+      },
+      "linkDeleting": {
+        "linkId": "string",
+        "sourcePortId": "string",
+        "targetPortId": "string"
+      },
+      "textDeleting": {
+        "textId": "string",
+        "ownerId": "string | null"
+      }
+    },
     "diagramImageExportOptions": {
       "mimeType": "string",
       "quality": "number",
@@ -332,6 +415,7 @@
       "completeLinkToElement",
       "cancelLink",
       "zoomToFitElements",
+      "focusElement",
       "exportImage",
       "resize",
       "setElementShapeHoverControls",
@@ -350,13 +434,18 @@
     "portMoved": "PortMovedEvent",
     "portSelected": "PortSelectedEvent",
     "elementClick": "ElementPointerEvent",
+    "elementDoubleClick": "ElementDoubleClickEvent",
     "elementDragged": "ElementDropEvent",
     "elementMoved": "ElementMovedEvent",
     "elementResized": "ElementResizedEvent",
     "gridLayoutChanged": "GridLayoutChangedEvent",
+    "elementDeleting": "ElementDeletingEvent",
     "elementDeleted": "ElementDeletedEvent",
+    "portDeleting": "PortDeletingEvent",
     "portDeleted": "PortDeletedEvent",
+    "linkDeleting": "LinkDeletingEvent",
     "linkDeleted": "LinkDeletedEvent",
+    "textDeleting": "TextDeletingEvent",
     "textDeleted": "TextDeletedEvent",
     "textUpdated": "TextUpdatedEvent",
     "elementSelected": "ElementSelectedEvent",

package/ai/invariants.json

@@ -28,10 +28,12 @@
     "link": [
       "link visible-state requires both endpoint ports to remain visible",
       "manual routing preserves interior bend points on endpoint updates",
-      "auto routing normalizes first/last points to source/target port world positions"
+      "auto routing normalizes first/last points to source/target port world positions",
+      "deleting a link removes any link-owned text"
     ],
     "text": [
       "owner-bound text stores owner-relative position",
+      "link-owned text stores position as an offset from the owning link midpoint",
       "owned text visible-state follows its resolved owner visibility",
       "orphan owner references are tolerated as standalone world text",
       "displayContent/displayOffset/displayClipSize may be derived from text layout rules"
@@ -41,7 +43,9 @@
     "mutations emit change with patches and full state snapshot",
     "setSelection/toggleSelection normalize away hidden element bodies, direct-owned hidden artifacts, and selectable=false element ids before emitting selection",
     "setSelection emits selection plus derived selected entity events",
-    "setViewport emits viewport patch without immediate render"
+    "setViewport emits viewport patch without immediate render",
+    "delete mutators emit cancellable elementDeleting/portDeleting/linkDeleting/textDeleting before commit and matching deleted events after successful removal",
+    "deleteSelection can skip a vetoed selected root while continuing unrelated selected roots"
   ],
   "verificationTests": [
     "src/models/__tests__/DiagramModel.test.ts",

package/ai/manifest.json

@@ -30,5 +30,5 @@
     "analysis/White paper/Overview.md",
     "analysis/White paper/Requirements-Functional.md"
   ],
-  "updatedAt": "2026-06-20"
+  "updatedAt": "2026-07-07"
 }