orcasvn-react-diagrams 0.2.10 → 0.2.11

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this project are documented in this file.
 
+## [0.2.11] - 2026-06-20
+
+### Added
+- `LinkColorPoolPolicy.assignOnLoadWhenMissingStroke` for opt-in load-time random `style.stroke` assignment on links that load without a usable stroke value.
+
+### Changed
+- Load-time link color fill now preserves explicit loaded `style.stroke` values, treats missing/`null`/blank strokes as fill candidates, and uses the active custom-or-default color pool only when the policy is enabled.
+
+### Docs
+- Updated release highlights, public API/docs contract text, integration guidance, and machine-readable contract metadata for `v0.2.11`.
+
 ## [0.2.10] - 2026-05-27
 
 ### Changed

package/README.md

@@ -30,14 +30,13 @@ editor.addElement({
 });
 ```
 
-## Release Highlights (v0.2.10)
-
-- Includes all completed `v0.2.1` through `v0.2.9` work, plus `v0.2.10` updates.
-- `v0.2.10` element visibility/selectability policy:
-  - `ElementData.visible = false` keeps the element in state while removing its own body from built-in render, hit testing, selection, and fit/export bounds
-  - visible descendant elements under a hidden parent remain rendered and interactive if their own `visible` flag stays enabled
-  - direct-owned parent ports/texts still follow the hidden parent, and links remain visible when their endpoint ports are visible
-  - `ElementData.selectable = false` keeps the element visible while preventing built-in element-body click/marquee/programmatic selection from retaining that element id
+## 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
 
 ## API Docs
 

package/ai/api-contract.json

@@ -259,6 +259,7 @@
     "linkColorPoolPolicy": {
       "enabled": "boolean",
       "colors": "string[]",
+      "assignOnLoadWhenMissingStroke": "boolean",
       "defaultPoolSize": 20
     },
     "viewportFitOptions": {

package/ai/manifest.json

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

package/dist/cjs/examples.js

@@ -3486,55 +3486,96 @@ var labelStyleDemoConfig = {
 var createLinkColorPoolState = function () { return ({
     elements: [
         {
-            id: 'lc-off-source',
-            position: { x: 80, y: 170 },
+            id: 'lc-load-missing-source',
+            position: { x: 80, y: 160 },
             size: { width: 190, height: 120 },
             shapeId: 'default',
         },
         {
-            id: 'lc-off-target',
-            position: { x: 350, y: 170 },
+            id: 'lc-load-missing-target',
+            position: { x: 350, y: 160 },
             size: { width: 190, height: 120 },
             shapeId: 'default',
         },
         {
-            id: 'lc-default-source',
-            position: { x: 80, y: 360 },
+            id: 'lc-load-blank-source',
+            position: { x: 80, y: 350 },
             size: { width: 190, height: 120 },
             shapeId: 'panel',
         },
         {
-            id: 'lc-default-target',
-            position: { x: 350, y: 360 },
+            id: 'lc-load-blank-target',
+            position: { x: 350, y: 350 },
             size: { width: 190, height: 120 },
             shapeId: 'panel',
         },
         {
-            id: 'lc-custom-source',
-            position: { x: 620, y: 170 },
+            id: 'lc-load-explicit-source',
+            position: { x: 80, y: 540 },
             size: { width: 190, height: 120 },
             shapeId: 'default',
         },
         {
-            id: 'lc-custom-target',
-            position: { x: 620, y: 360 },
+            id: 'lc-load-explicit-target',
+            position: { x: 350, y: 540 },
             size: { width: 190, height: 120 },
             shapeId: 'default',
         },
+        {
+            id: 'lc-create-auto-source',
+            position: { x: 620, y: 250 },
+            size: { width: 190, height: 120 },
+            shapeId: 'default',
+        },
+        {
+            id: 'lc-create-auto-target',
+            position: { x: 620, y: 420 },
+            size: { width: 190, height: 120 },
+            shapeId: 'default',
+        },
+        {
+            id: 'lc-create-explicit-source',
+            position: { x: 870, y: 250 },
+            size: { width: 190, height: 120 },
+            shapeId: 'panel',
+        },
+        {
+            id: 'lc-create-explicit-target',
+            position: { x: 870, y: 420 },
+            size: { width: 190, height: 120 },
+            shapeId: 'panel',
+        },
     ],
     ports: [
-        { id: 'lc-off-source-port', elementId: 'lc-off-source', position: { x: 170, y: 60 }, shapeId: 'port-circle' },
-        { id: 'lc-off-target-port', elementId: 'lc-off-target', position: { x: 20, y: 60 }, shapeId: 'port-circle' },
-        { id: 'lc-default-source-port', elementId: 'lc-default-source', position: { x: 170, y: 60 }, shapeId: 'port-circle' },
-        { id: 'lc-default-target-port', elementId: 'lc-default-target', position: { x: 20, y: 60 }, shapeId: 'port-circle' },
-        { id: 'lc-custom-source-port', elementId: 'lc-custom-source', position: { x: 95, y: 110 }, shapeId: 'port-circle' },
-        { id: 'lc-custom-target-port', elementId: 'lc-custom-target', position: { x: 95, y: 10 }, shapeId: 'port-circle' },
+        { id: 'lc-load-missing-source-port', elementId: 'lc-load-missing-source', position: { x: 170, y: 60 }, shapeId: 'port-circle' },
+        { id: 'lc-load-missing-target-port', elementId: 'lc-load-missing-target', position: { x: 20, y: 60 }, shapeId: 'port-circle' },
+        { id: 'lc-load-blank-source-port', elementId: 'lc-load-blank-source', position: { x: 170, y: 60 }, shapeId: 'port-circle' },
+        { id: 'lc-load-blank-target-port', elementId: 'lc-load-blank-target', position: { x: 20, y: 60 }, shapeId: 'port-circle' },
+        { id: 'lc-load-explicit-source-port', elementId: 'lc-load-explicit-source', position: { x: 170, y: 60 }, shapeId: 'port-circle' },
+        { id: 'lc-load-explicit-target-port', elementId: 'lc-load-explicit-target', position: { x: 20, y: 60 }, shapeId: 'port-circle' },
+        { id: 'lc-create-auto-source-port', elementId: 'lc-create-auto-source', position: { x: 95, y: 110 }, shapeId: 'port-circle' },
+        { id: 'lc-create-auto-target-port', elementId: 'lc-create-auto-target', position: { x: 95, y: 10 }, shapeId: 'port-circle' },
+        { id: 'lc-create-explicit-source-port', elementId: 'lc-create-explicit-source', position: { x: 95, y: 110 }, shapeId: 'port-circle' },
+        { id: 'lc-create-explicit-target-port', elementId: 'lc-create-explicit-target', position: { x: 95, y: 10 }, shapeId: 'port-circle' },
     ],
     links: [
         {
-            id: 'lc-reference-link',
-            sourcePortId: 'lc-off-source-port',
-            targetPortId: 'lc-off-target-port',
+            id: 'lc-loaded-missing-link',
+            sourcePortId: 'lc-load-missing-source-port',
+            targetPortId: 'lc-load-missing-target-port',
+            points: [],
+        },
+        {
+            id: 'lc-loaded-blank-link',
+            sourcePortId: 'lc-load-blank-source-port',
+            targetPortId: 'lc-load-blank-target-port',
+            points: [],
+            style: { stroke: '   ', strokeWidth: 2 },
+        },
+        {
+            id: 'lc-loaded-explicit-link',
+            sourcePortId: 'lc-load-explicit-source-port',
+            targetPortId: 'lc-load-explicit-target-port',
             points: [],
             style: { stroke: '#374151', strokeWidth: 2 },
         },
@@ -3542,18 +3583,20 @@ var createLinkColorPoolState = function () { return ({
     texts: [
         {
             id: 'lc-intro',
-            content: 'Use Color Mode above: Off keeps baseline link color behavior. Default Pool enables random colors from the built-in 20-color pool. Custom Pool restricts random colors to #0b7285, #e8590c, #5f3dc4.',
+            content: 'Change Color Mode, then use Reload Demo State to compare load-time fill. The left column loads one missing-stroke link, one blank-stroke link, and one explicit-stroke link. The right column actions add new links so you can compare creation-time color assignment with explicit-stroke preservation under the same policy.',
             position: { x: 80, y: 86 },
         },
-        { id: 'lc-off-label', content: 'Off scenario pair', ownerId: 'lc-off-source', position: { x: 10, y: -16 } },
-        { id: 'lc-default-label', content: 'Default-pool scenario pair', ownerId: 'lc-default-source', position: { x: 10, y: -16 } },
-        { id: 'lc-custom-label', content: 'Custom-pool scenario pair', ownerId: 'lc-custom-source', position: { x: 10, y: -16 } },
+        { id: 'lc-load-missing-label', content: 'Loaded link with missing stroke', ownerId: 'lc-load-missing-source', position: { x: 10, y: -16 } },
+        { id: 'lc-load-blank-label', content: 'Loaded link with blank stroke', ownerId: 'lc-load-blank-source', position: { x: 10, y: -16 } },
+        { id: 'lc-load-explicit-label', content: 'Loaded link with explicit stroke', ownerId: 'lc-load-explicit-source', position: { x: 10, y: -16 } },
+        { id: 'lc-create-auto-label', content: 'Add new unstyled links here', ownerId: 'lc-create-auto-source', position: { x: 10, y: -16 } },
+        { id: 'lc-create-explicit-label', content: 'Add new explicit-stroke links here', ownerId: 'lc-create-explicit-source', position: { x: 10, y: -16 } },
     ],
 }); };
 var linkColorPoolDemoConfig = {
     id: 'link-color-pool',
     title: 'Link Color Pool',
-    description: 'Verify disabled/default/custom random link-color assignment on new links.',
+    description: 'Verify off/default/custom load-time fill for missing link strokes and compare it with creation-time color assignment.',
     createState: createLinkColorPoolState,
     elementShapes: baseElementShapes,
     portShapes: basePortShapes,
@@ -3561,38 +3604,30 @@ var linkColorPoolDemoConfig = {
     defaultPortShapeId: 'port-circle',
     actions: [
         {
-            id: 'add-link-off-pair',
-            label: 'Add link (off pair)',
-            run: function (editor) {
-                editor.addLink({
-                    id: "link-color-off-".concat(createId()),
-                    sourcePortId: 'lc-off-source-port',
-                    targetPortId: 'lc-off-target-port',
-                    points: [],
-                });
-            },
-        },
-        {
-            id: 'add-link-default-pair',
-            label: 'Add link (default pair)',
+            id: 'add-link-create-auto',
+            label: 'Add new unstyled link',
             run: function (editor) {
                 editor.addLink({
-                    id: "link-color-default-".concat(createId()),
-                    sourcePortId: 'lc-default-source-port',
-                    targetPortId: 'lc-default-target-port',
+                    id: "link-color-create-auto-".concat(createId()),
+                    sourcePortId: 'lc-create-auto-source-port',
+                    targetPortId: 'lc-create-auto-target-port',
                     points: [],
                 });
             },
         },
         {
-            id: 'add-link-custom-pair',
-            label: 'Add link (custom pair)',
+            id: 'add-link-create-explicit',
+            label: 'Add new explicit-stroke link',
             run: function (editor) {
                 editor.addLink({
-                    id: "link-color-custom-".concat(createId()),
-                    sourcePortId: 'lc-custom-source-port',
-                    targetPortId: 'lc-custom-target-port',
+                    id: "link-color-create-explicit-".concat(createId()),
+                    sourcePortId: 'lc-create-explicit-source-port',
+                    targetPortId: 'lc-create-explicit-target-port',
                     points: [],
+                    style: {
+                        stroke: '#111827',
+                        strokeWidth: 2,
+                    },
                 });
             },
         },
@@ -8043,6 +8078,10 @@ var DEFAULT_LINK_COLOR_POOL = [
     '#9c755f',
     '#bab0ab',
 ];
+var hasUsableLinkStroke = function (style) {
+    var stroke = style === null || style === void 0 ? void 0 : style.stroke;
+    return stroke !== undefined && stroke !== null && "".concat(stroke).trim().length > 0;
+};
 var normalizeLinkColorPoolPolicy = function (policy) {
     var _a;
     var enabled = Boolean(policy === null || policy === void 0 ? void 0 : policy.enabled);
@@ -8050,7 +8089,11 @@ var normalizeLinkColorPoolPolicy = function (policy) {
         .map(function (color) { return color.trim(); })
         .filter(function (color) { return color.length > 0; });
     var colors = normalizedColors.length > 0 ? normalizedColors : __spreadArray([], DEFAULT_LINK_COLOR_POOL, true);
-    return { enabled: enabled, colors: colors };
+    return {
+        enabled: enabled,
+        colors: colors,
+        assignOnLoadWhenMissingStroke: Boolean(policy === null || policy === void 0 ? void 0 : policy.assignOnLoadWhenMissingStroke),
+    };
 };
 var DiagramEngine = /** @class */ (function () {
     function DiagramEngine(config) {
@@ -8096,8 +8139,9 @@ var DiagramEngine = /** @class */ (function () {
     DiagramEngine.prototype.load = function (state) {
         var _this = this;
         var patches = this.commandQueue.run(createLoadCommand(state), this.model);
+        var linkColorPatches = this.assignOptionalLinkColorsOnLoad();
         var mutationPatches = this.mutationPipeline.run({
-            basePatches: patches,
+            basePatches: __spreadArray(__spreadArray([], patches, true), linkColorPatches, true),
             layoutSteps: [function () { return _this.applyAllLayouts(); }],
             includeEmptyLinkRouting: true,
         });
@@ -9455,21 +9499,41 @@ var DiagramEngine = /** @class */ (function () {
         return this.linkRoutingService.routeLinksWithEmptyPoints();
     };
     DiagramEngine.prototype.applyOptionalLinkColor = function (link) {
-        if (!this.linkColorPoolPolicy.enabled)
-            return link;
-        var existingStyle = link.style;
-        var hasExplicitStroke = existingStyle !== undefined &&
-            Object.prototype.hasOwnProperty.call(existingStyle, 'stroke') &&
-            existingStyle.stroke !== undefined &&
-            existingStyle.stroke !== null &&
-            "".concat(existingStyle.stroke).trim().length > 0;
-        if (hasExplicitStroke)
+        var style = this.resolveOptionalLinkColorStyle(link.style);
+        if (style === link.style)
             return link;
+        return __assign(__assign({}, link), { style: style });
+    };
+    DiagramEngine.prototype.assignOptionalLinkColorsOnLoad = function () {
+        var _this = this;
+        if (!this.linkColorPoolPolicy.enabled || !this.linkColorPoolPolicy.assignOnLoadWhenMissingStroke) {
+            return [];
+        }
+        var patches = [];
+        this.model.links.forEach(function (link) {
+            var style = _this.resolveOptionalLinkColorStyle(link.style);
+            if (style === link.style)
+                return;
+            link.style = style;
+            patches.push(patchUpdate('link', link.id, { style: style }));
+        });
+        return patches;
+    };
+    DiagramEngine.prototype.resolveOptionalLinkColorStyle = function (style) {
+        if (!this.linkColorPoolPolicy.enabled || hasUsableLinkStroke(style)) {
+            return style;
+        }
+        var stroke = this.pickOptionalLinkColor();
+        if (!stroke)
+            return style;
+        return __assign(__assign({}, (style !== null && style !== void 0 ? style : {})), { stroke: stroke });
+    };
+    DiagramEngine.prototype.pickOptionalLinkColor = function () {
         var colors = this.linkColorPoolPolicy.colors;
         if (colors.length === 0)
-            return link;
+            return undefined;
         var index = Math.max(0, Math.min(colors.length - 1, Math.floor(Math.random() * colors.length)));
-        return __assign(__assign({}, link), { style: __assign(__assign({}, (existingStyle !== null && existingStyle !== void 0 ? existingStyle : {})), { stroke: colors[index] }) });
+        return colors[index];
     };
     DiagramEngine.prototype.refreshLinksForRenderCycle = function () {
         if (this.linkRouteRefreshPolicy.mode !== 'redraw-two-endpoint-change')
@@ -16493,9 +16557,10 @@ var LinkColorPoolDemo = function () {
     var linkColorPoolPolicy = React.useMemo(function () {
         if (mode === 'off')
             return undefined;
-        if (mode === 'default')
-            return { enabled: true };
-        return { enabled: true, colors: customPool };
+        if (mode === 'default') {
+            return { enabled: true, assignOnLoadWhenMissingStroke: true };
+        }
+        return { enabled: true, assignOnLoadWhenMissingStroke: true, colors: customPool };
     }, [mode]);
     return (React.createElement(SimpleDemo, { demo: linkColorPoolDemoConfig, linkColorPoolPolicy: linkColorPoolPolicy, beforeStage: React.createElement("div", { style: {
                 marginBottom: 12,
@@ -16507,9 +16572,10 @@ var LinkColorPoolDemo = function () {
             React.createElement("label", { htmlFor: "link-color-mode", style: { display: 'inline-flex', alignItems: 'center', gap: 8, fontWeight: 600 } },
                 "Color Mode",
                 React.createElement("select", { id: "link-color-mode", value: mode, onChange: function (event) { return setMode(event.target.value); } },
-                    React.createElement("option", { value: "off" }, "Off (default behavior)"),
-                    React.createElement("option", { value: "default" }, "Default 20-color pool"),
-                    React.createElement("option", { value: "custom" }, "Custom pool (#0b7285, #e8590c, #5f3dc4)")))) }));
+                    React.createElement("option", { value: "off" }, "Off (no load fill)"),
+                    React.createElement("option", { value: "default" }, "Default pool load fill"),
+                    React.createElement("option", { value: "custom" }, "Custom pool load fill (#0b7285, #e8590c, #5f3dc4)"))),
+            React.createElement("p", { style: { margin: '8px 0 0', fontSize: 13 } }, "Switching modes recreates the demo so the seeded loaded links can prove whether missing and blank strokes are filled, while explicit loaded strokes stay untouched.")) }));
 };
 
 var sidePositions = {

package/dist/cjs/index.js

@@ -3809,6 +3809,10 @@ var DEFAULT_LINK_COLOR_POOL = [
     '#9c755f',
     '#bab0ab',
 ];
+var hasUsableLinkStroke = function (style) {
+    var stroke = style === null || style === void 0 ? void 0 : style.stroke;
+    return stroke !== undefined && stroke !== null && "".concat(stroke).trim().length > 0;
+};
 var normalizeLinkColorPoolPolicy = function (policy) {
     var _a;
     var enabled = Boolean(policy === null || policy === void 0 ? void 0 : policy.enabled);
@@ -3816,7 +3820,11 @@ var normalizeLinkColorPoolPolicy = function (policy) {
         .map(function (color) { return color.trim(); })
         .filter(function (color) { return color.length > 0; });
     var colors = normalizedColors.length > 0 ? normalizedColors : __spreadArray([], DEFAULT_LINK_COLOR_POOL, true);
-    return { enabled: enabled, colors: colors };
+    return {
+        enabled: enabled,
+        colors: colors,
+        assignOnLoadWhenMissingStroke: Boolean(policy === null || policy === void 0 ? void 0 : policy.assignOnLoadWhenMissingStroke),
+    };
 };
 var DiagramEngine = /** @class */ (function () {
     function DiagramEngine(config) {
@@ -3862,8 +3870,9 @@ var DiagramEngine = /** @class */ (function () {
     DiagramEngine.prototype.load = function (state) {
         var _this = this;
         var patches = this.commandQueue.run(createLoadCommand(state), this.model);
+        var linkColorPatches = this.assignOptionalLinkColorsOnLoad();
         var mutationPatches = this.mutationPipeline.run({
-            basePatches: patches,
+            basePatches: __spreadArray(__spreadArray([], patches, true), linkColorPatches, true),
             layoutSteps: [function () { return _this.applyAllLayouts(); }],
             includeEmptyLinkRouting: true,
         });
@@ -5221,21 +5230,41 @@ var DiagramEngine = /** @class */ (function () {
         return this.linkRoutingService.routeLinksWithEmptyPoints();
     };
     DiagramEngine.prototype.applyOptionalLinkColor = function (link) {
-        if (!this.linkColorPoolPolicy.enabled)
-            return link;
-        var existingStyle = link.style;
-        var hasExplicitStroke = existingStyle !== undefined &&
-            Object.prototype.hasOwnProperty.call(existingStyle, 'stroke') &&
-            existingStyle.stroke !== undefined &&
-            existingStyle.stroke !== null &&
-            "".concat(existingStyle.stroke).trim().length > 0;
-        if (hasExplicitStroke)
+        var style = this.resolveOptionalLinkColorStyle(link.style);
+        if (style === link.style)
             return link;
+        return __assign(__assign({}, link), { style: style });
+    };
+    DiagramEngine.prototype.assignOptionalLinkColorsOnLoad = function () {
+        var _this = this;
+        if (!this.linkColorPoolPolicy.enabled || !this.linkColorPoolPolicy.assignOnLoadWhenMissingStroke) {
+            return [];
+        }
+        var patches = [];
+        this.model.links.forEach(function (link) {
+            var style = _this.resolveOptionalLinkColorStyle(link.style);
+            if (style === link.style)
+                return;
+            link.style = style;
+            patches.push(patchUpdate('link', link.id, { style: style }));
+        });
+        return patches;
+    };
+    DiagramEngine.prototype.resolveOptionalLinkColorStyle = function (style) {
+        if (!this.linkColorPoolPolicy.enabled || hasUsableLinkStroke(style)) {
+            return style;
+        }
+        var stroke = this.pickOptionalLinkColor();
+        if (!stroke)
+            return style;
+        return __assign(__assign({}, (style !== null && style !== void 0 ? style : {})), { stroke: stroke });
+    };
+    DiagramEngine.prototype.pickOptionalLinkColor = function () {
         var colors = this.linkColorPoolPolicy.colors;
         if (colors.length === 0)
-            return link;
+            return undefined;
         var index = Math.max(0, Math.min(colors.length - 1, Math.floor(Math.random() * colors.length)));
-        return __assign(__assign({}, link), { style: __assign(__assign({}, (existingStyle !== null && existingStyle !== void 0 ? existingStyle : {})), { stroke: colors[index] }) });
+        return colors[index];
     };
     DiagramEngine.prototype.refreshLinksForRenderCycle = function () {
         if (this.linkRouteRefreshPolicy.mode !== 'redraw-two-endpoint-change')

package/dist/cjs/types/api/types.d.ts

@@ -193,6 +193,7 @@ export type LinkRouteRefreshPolicy = {
 export type LinkColorPoolPolicy = {
     enabled?: boolean;
     colors?: string[];
+    assignOnLoadWhenMissingStroke?: boolean;
 };
 export type ElementLayoutMode = 'manual' | 'horizontal' | 'vertical' | 'grid';
 export type ElementLayoutAlign = 'start' | 'center' | 'end';

package/dist/cjs/types/displaybox/demos/linkColorPoolDemo.d.ts

@@ -1,2 +1,4 @@
+import type { DiagramState } from '../../api';
 import type { DemoConfig } from '../types';
+export declare const createLinkColorPoolState: () => DiagramState;
 export declare const linkColorPoolDemoConfig: DemoConfig;

package/dist/cjs/types/engine/DiagramEngine.d.ts

@@ -165,6 +165,9 @@ export default class DiagramEngine {
     private projectPointToHostBorder;
     private routeLinksWithEmptyPoints;
     private applyOptionalLinkColor;
+    private assignOptionalLinkColorsOnLoad;
+    private resolveOptionalLinkColorStyle;
+    private pickOptionalLinkColor;
     private refreshLinksForRenderCycle;
     private normalizePortsForHostPolicies;
     private computeRemovalDiff;