orcasvn-react-diagrams 0.2.8 → 0.2.9

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

@@ -269,6 +269,8 @@ export type ElementData = {
     style?: Record<string, unknown>;
     portIds?: string[];
     textIds?: string[];
+    visible?: boolean;
+    selectable?: boolean;
     parentId?: string | null;
     moveMode?: MoveConstraint;
     anchorCenter?: boolean;

package/dist/esm/types/displaybox/demos/elementVisibilitySelectionDemo.d.ts

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

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

@@ -76,6 +76,11 @@ export default class DiagramEngine {
     setSelection(ids: string[]): void;
     toggleSelection(id: string): void;
     getSelection(): string[];
+    isElementVisible(id: string): boolean;
+    isElementSelectable(id: string): boolean;
+    isPortVisible(id: string): boolean;
+    isLinkVisible(id: string): boolean;
+    isTextVisible(id: string): boolean;
     getElementWorldPosition(id: string): Point | null;
     getElementRotation(id: string): number;
     normalizeElementResize(id: string, proposal: {
@@ -146,6 +151,9 @@ export default class DiagramEngine {
     private resolveTextPresentation;
     private resolveAllTextPresentationPatches;
     private emitSelection;
+    private normalizeSelectionIds;
+    private isSelectableId;
+    private syncSelectionToPolicies;
     private applyLayoutForParent;
     private applyLayoutCascade;
     private applyAllLayouts;

package/dist/esm/types/models/DiagramModel.d.ts

@@ -13,14 +13,19 @@ export default class DiagramModel {
     load(state: DiagramState): void;
     toState(): DiagramState;
     getElement(id: string): ElementModel | undefined;
+    isElementVisible(id: string): boolean;
+    isElementSelectable(id: string): boolean;
     setElementLayout(id: string, layout: ElementData['layout']): void;
     getChildren(parentId: string): ElementModel[];
     getElementWorldPosition(id: string): Point | null;
     getPort(id: string): PortModel | undefined;
+    isPortVisible(id: string): boolean;
     getPortWorldPosition(id: string): Point | null;
     getLink(id: string): LinkModel | undefined;
+    isLinkVisible(id: string): boolean;
     getLinkMidpoint(id: string): Point | null;
     getText(id: string): TextModel | undefined;
+    isTextVisible(id: string): boolean;
     getTextWorldPosition(id: string): Point | null;
     addElement(data: ElementData): ElementModel;
     moveElement(id: string, position: Point): void;

package/dist/esm/types/models/ElementModel.d.ts

@@ -7,6 +7,8 @@ export default class ElementModel {
     style?: Record<string, unknown>;
     portIds: string[];
     textIds: string[];
+    visible?: boolean;
+    selectable?: boolean;
     parentId: string | null;
     moveMode?: MoveConstraint;
     anchorCenter?: boolean;

package/dist/examples.d.ts

@@ -242,6 +242,8 @@ type ElementData = {
     style?: Record<string, unknown>;
     portIds?: string[];
     textIds?: string[];
+    visible?: boolean;
+    selectable?: boolean;
     parentId?: string | null;
     moveMode?: MoveConstraint;
     anchorCenter?: boolean;

package/dist/index.d.ts

@@ -269,6 +269,8 @@ type ElementData = {
     style?: Record<string, unknown>;
     portIds?: string[];
     textIds?: string[];
+    visible?: boolean;
+    selectable?: boolean;
     parentId?: string | null;
     moveMode?: MoveConstraint;
     anchorCenter?: boolean;
@@ -543,6 +545,8 @@ declare class ElementModel {
     style?: Record<string, unknown>;
     portIds: string[];
     textIds: string[];
+    visible?: boolean;
+    selectable?: boolean;
     parentId: string | null;
     moveMode?: MoveConstraint;
     anchorCenter?: boolean;
@@ -640,14 +644,19 @@ declare class DiagramModel {
     load(state: DiagramState): void;
     toState(): DiagramState;
     getElement(id: string): ElementModel | undefined;
+    isElementVisible(id: string): boolean;
+    isElementSelectable(id: string): boolean;
     setElementLayout(id: string, layout: ElementData['layout']): void;
     getChildren(parentId: string): ElementModel[];
     getElementWorldPosition(id: string): Point | null;
     getPort(id: string): PortModel | undefined;
+    isPortVisible(id: string): boolean;
     getPortWorldPosition(id: string): Point | null;
     getLink(id: string): LinkModel | undefined;
+    isLinkVisible(id: string): boolean;
     getLinkMidpoint(id: string): Point | null;
     getText(id: string): TextModel | undefined;
+    isTextVisible(id: string): boolean;
     getTextWorldPosition(id: string): Point | null;
     addElement(data: ElementData): ElementModel;
     moveElement(id: string, position: Point): void;

package/docs/API_CONTRACT.md

@@ -62,12 +62,22 @@ Defaults:
 
 ### `ElementData`
 - Required: `id`, `position`, `size`, `shapeId`
-- Optional: `style`, `portIds`, `textIds`, `parentId`, `moveMode`, `anchorCenter`, `layout`, `childElementInteraction`, `portMovement`
+- Optional: `style`, `portIds`, `textIds`, `visible`, `selectable`, `parentId`, `moveMode`, `anchorCenter`, `layout`, `childElementInteraction`, `portMovement`
 - Defaults at runtime/model:
   - `portIds`: `[]`
   - `textIds`: `[]`
   - `parentId`: `null`
 
+### `ElementData.visible` and `ElementData.selectable`
+- Optional `visible?: boolean` (default behavior: `true`)
+- Optional `selectable?: boolean` (default behavior: `true`)
+- Semantics:
+  - `visible: false` removes the element body from built-in render, hit testing, marquee selection, persisted selection, `zoomToFitElements`, and `exportImage({ fitToContent })`
+  - hidden-scene propagation also hides owned ports, owned texts, and links whose source/target ports belong to hidden elements
+  - `selectable: false` prevents built-in element-body click selection, marquee selection, and programmatic `setSelection(...)` / `toggleSelection(...)` from retaining that element id
+  - `selectable: false` does not hide the element
+  - visible ports on a visible-but-unselectable element remain interactable/selectable unless separately constrained
+
 ### `ElementLayout`
 - Required: `mode: 'manual' | 'horizontal' | 'vertical' | 'grid'`
 - Optional: `padding?: number | { x: number; y: number }`, `gap?: number`, `align?: 'start' | 'center' | 'end'`
@@ -261,7 +271,9 @@ Defaults:
 - Missing IDs in most mutators are no-op (non-throwing).
 - `setViewport` emits a `change` patch with `entity: 'viewport'` and skips immediate render scheduling.
 - `zoomToFitElements` computes bounds from `elements[]` only, ignores ports/links/texts for fit expansion, and no-ops when no elements exist.
+- `zoomToFitElements` ignores hidden elements when computing fit bounds.
 - `zoomToFitElements` applies its result through `setViewport`, so hosts observe the standard viewport patch/change path.
+- `exportImage({ fitToContent })` derives crop bounds from visible scene entities only.
 - Built-in empty-paper panning now starts from plain primary-button drag and no longer requires `panKey`; marquee selection uses `Shift + primary drag`.
 - `clientToWorld` uses: `world = (client - containerRect - pan) / zoom`, with zoom fallback to `1` when zoom is `0`.
 - `rerouteLinks(ids)` skips manual links unless `options.includeManual === true`.
@@ -269,6 +281,9 @@ Defaults:
 - `updateLinkPoints` always marks the link as manual routing.
 - `linkColorPoolPolicy` is opt-in and applies only to newly created links; explicitly provided non-empty `style.stroke` values are preserved.
 - `gridLayoutChanged` is additive and does not replace standard `change` / `elementResized` flows.
+- `ElementData.visible = false` hides the element plus owned ports/texts and endpoint-dependent links from built-in renderer sync, hit testing, marquee selection, persisted selection, and fit/export helpers.
+- `ElementData.selectable = false` blocks built-in element-body selection while still allowing visible owned ports to participate in their normal interaction flows.
+- `setSelection(...)` and `toggleSelection(...)` normalize away unknown IDs, hidden scene members, and unselectable elements before emitting `selection`.
 - `ElementData.childElementInteraction.movable = false` suppresses built-in drag only for direct child elements; programmatic `moveElementTo(...)` and layout/ancestor-driven repositioning remain allowed.
 - `TextData.interaction.movable = false` blocks built-in drag only; selection still works and programmatic movement remains allowed.
 - `TextData.interaction.editable = false` blocks built-in textarea editing only; selection still works and programmatic text updates remain allowed.

package/docs/CAPABILITIES.md

@@ -17,6 +17,7 @@
 - Auto-layout parent resize policy (`grow` / `grow-shrink`) and child size constraints.
 - Optional grid-child width topology editing with `gridLayoutChanged` host events.
 - Parent-owned direct-child drag suppression through `ElementData.childElementInteraction`.
+- Element-level visibility/selectability policy through `ElementData.visible` and `ElementData.selectable`, including hidden-scene propagation to owned ports/texts and endpoint-dependent links.
 - Element shape hover controls with edge/vertex/midpoint targets and interaction callbacks.
 - Optional random link color assignment from configurable pools during link creation.
 - Per-text interaction policy for suppressing built-in text drag and/or built-in text editing.

package/docs/COMMANDS_EVENTS.md

@@ -38,10 +38,11 @@
   - Plus `textDeleted` on removal (including cascade removal)
 - `setSelection/toggleSelection/deleteSelection`
   - `selection` plus derived selected entity events
+  - hidden scene members and `selectable:false` element IDs are filtered out before selection persists/emits
 - `setViewport`
   - `change` with viewport patch (`render: false`)
 - `zoomToFitElements`
-  - delegates to `setViewport` when at least one element exists
+  - delegates to `setViewport` when at least one visible element exists
   - emits the same viewport `change` patch path
 - `setRouting/setSnapping/registerShape`
   - `config` events
@@ -64,6 +65,7 @@
 ## Failure Modes
 - Unknown IDs do not emit entity-specific movement/selection events.
 - Canceled link creation emits `elementLinkEnded` with `cancelled=true` and no link creation.
+- Built-in element-body selection emits no persisted element selection when the target element is hidden or sets `selectable = false`.
 - Built-in drag on a direct child element emits no move/drop mutation when its parent sets `childElementInteraction.movable = false`.
 - `textUpdated` emits only when target text exists; missing IDs remain no-op.
 

package/docs/DOCUMENTATION_WORKFLOW.md

@@ -59,7 +59,7 @@ When resuming later:
 5. Re-run packaging verification.
 
 ## 6. Current Status
-- Last updated: 2026-05-24
+- Last updated: 2026-05-27
 - Last completed step: 10
 - Next step: 7 (optional additional fixture coverage for deeper nested/manual-route scenarios)
 - Owner: Codex (with repository maintainers)
@@ -87,3 +87,4 @@ When resuming later:
 - 2026-05-14: Completed release-doc pass for `v0.2.6`; refreshed release highlights, API contract updates (`zoomToFitElements`, `ViewportFitOptions`, `gridChildWidthResizeEnabled`, `gridLayoutChanged`, `TextInteractionPolicy`), and machine-readable contract metadata.
 - 2026-05-18: Completed release-doc pass for `v0.2.7`; refreshed release highlights, API contract updates (`ElementChildInteractionPolicy`, `childElementInteraction`, and built-in pan gesture behavior), and machine-readable contract metadata.
 - 2026-05-24: Completed release-doc pass for `v0.2.8`; refreshed release highlights and publish-facing workflow metadata for the nested grid slot-preservation fix.
+- 2026-05-27: Completed release-doc pass for `v0.2.9`; refreshed release highlights, visibility/selectability API docs, state/event integration notes, and machine-readable contract metadata.

package/docs/INTEGRATION_PLAYBOOK.md

@@ -19,6 +19,7 @@ Embed this library into another diagram host while preserving deterministic stat
 6. Use `zoomToFitElements(options?)` when the host needs library-owned fit-to-elements navigation instead of recomputing viewport math externally.
 7. Set `TextData.interaction` when some labels must remain read-only or fixed in place while still using library selection behavior.
 8. Set `ElementData.childElementInteraction` on parent elements when direct child nodes should stay selectable but not be draggable through built-in interaction.
+9. Set `ElementData.visible` and `ElementData.selectable` when hosts need hidden-but-retained nodes or visible-but-nonselectable element bodies; hidden elements also suppress owned ports/texts and endpoint-dependent links from built-in view helpers.
 
 ## Path B: Engine-Only Adapter
 1. Implement `Renderer`:

package/docs/PORTING_CHECKLIST.md

@@ -8,6 +8,7 @@
   - `PortData`
   - `LinkData`
   - `TextData`
+- Confirm host mapping for `ElementData.visible` / `ElementData.selectable` if hidden or non-selectable nodes must retain state.
 - Confirm owner-relative semantics for ports/texts.
 
 ## 2. Match Coordinate Semantics

package/docs/STATE_INVARIANTS.md

@@ -12,6 +12,9 @@
 - Position is local to parent if `parentId` exists; otherwise world.
 - World position resolves by summing ancestor positions.
 - If `anchorCenter=true`, world top-left is shifted by half size.
+- `visible` and `selectable` behave as enabled when omitted.
+- `visible=false` excludes the element from the visible scene, and ancestor hidden state propagates to descendant elements.
+- `selectable=false` prevents the element ID from persisting in engine selection state.
 - Deleting an element cascades to:
   - child ports
   - links connected through removed ports
@@ -21,6 +24,7 @@
 - Port position is local to owner element.
 - Default `anchorCenter=true` in model constructor.
 - Default `orientToHostBorder=true` in model constructor.
+- Port visible-state is derived from owning element visibility.
 - Moving ports can be constrained by:
   - `moveMode: inside|border`
   - element-level `portMovement.moveMode: free|inside|border|anchors`
@@ -34,11 +38,13 @@
 - Auto routing recomputes from router strategy and normalized endpoints.
 - Manual routing preserves interior bends on endpoint movement.
 - Links with unresolved source/target world positions are skipped by reroute/update paths.
+- Link visible-state requires both endpoint ports to remain visible.
 
 ## Text
 - `ownerId` can reference element, port, or link.
 - Owned text position is stored owner-relative.
 - Text with missing owner behaves as standalone world-position text.
+- Owned text visible-state follows its owner visibility when the owner resolves to an element, port, or link.
 - Text interaction policy is persisted separately from style/layout metadata.
 - `interaction.movable = false` suppresses built-in drag without blocking selection or programmatic movement.
 - `interaction.editable = false` suppresses built-in editing without blocking selection or programmatic content updates.
@@ -49,8 +55,10 @@
 - `setSelection` emits:
   - `selection`
   - plus derived `elementSelected`/`portSelected`/`textSelected`
+- `setSelection` and `toggleSelection` normalize IDs against current visibility/selectability rules before persisting or emitting selection.
 - `setViewport` emits `change` with `entity=viewport` and does not force render directly.
-- `zoomToFitElements` derives viewport fit from `elements[]` bounds only and applies the result through `setViewport`.
+- `zoomToFitElements` derives viewport fit from visible `elements[]` bounds only and applies the result through `setViewport`.
+- `exportImage({ fitToContent })` derives crop bounds from visible scene entities only.
 
 ## Failure Modes
 - Non-existent target IDs: operation is no-op.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orcasvn-react-diagrams",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "dependencies": {
     "eventemitter3": "^5.0.1",
     "flatten-js": "^0.6.9",

package/src/displaybox/demos/elementVisibilitySelectionDemo.ts

@@ -0,0 +1,128 @@
+import type { DiagramState } from '../../api';
+import type { DemoConfig } from '../types';
+import { baseElementShapes, basePortShapes } from './shared';
+
+export const createElementVisibilitySelectionState = (): DiagramState => ({
+  elements: [
+    {
+      id: 'policy-normal',
+      position: { x: 120, y: 160 },
+      size: { width: 180, height: 120 },
+      shapeId: 'default',
+      style: { fill: '#dbeafe', stroke: '#1d4ed8', strokeWidth: 2 },
+    },
+    {
+      id: 'policy-unselectable',
+      position: { x: 410, y: 160 },
+      size: { width: 180, height: 120 },
+      shapeId: 'default',
+      selectable: false,
+      style: { fill: '#e2e8f0', stroke: '#334155', strokeWidth: 2 },
+    },
+    {
+      id: 'policy-hidden',
+      position: { x: 700, y: 140 },
+      size: { width: 180, height: 120 },
+      shapeId: 'default',
+      visible: false,
+      style: { fill: '#fee2e2', stroke: '#dc2626', strokeWidth: 2 },
+    },
+  ],
+  ports: [
+    {
+      id: 'policy-normal-port',
+      elementId: 'policy-normal',
+      position: { x: 180, y: 60 },
+      shapeId: 'port-circle',
+    },
+    {
+      id: 'policy-unselectable-port',
+      elementId: 'policy-unselectable',
+      position: { x: 0, y: 60 },
+      shapeId: 'port-circle',
+    },
+    {
+      id: 'policy-hidden-port',
+      elementId: 'policy-hidden',
+      position: { x: 0, y: 60 },
+      shapeId: 'port-circle',
+    },
+  ],
+  links: [
+    {
+      id: 'policy-visible-link',
+      sourcePortId: 'policy-normal-port',
+      targetPortId: 'policy-unselectable-port',
+      points: [
+        { x: 300, y: 220 },
+        { x: 410, y: 220 },
+      ],
+      style: { stroke: '#2563eb', strokeWidth: 3 },
+    },
+    {
+      id: 'policy-hidden-link',
+      sourcePortId: 'policy-normal-port',
+      targetPortId: 'policy-hidden-port',
+      points: [
+        { x: 300, y: 220 },
+        { x: 700, y: 200 },
+      ],
+      style: { stroke: '#dc2626', strokeWidth: 3 },
+    },
+  ],
+  texts: [
+    {
+      id: 'policy-tip',
+      content:
+        'Blue node is normal. Slate node is visible but its body ignores click and marquee. Its port stays interactive. Hidden node, its port, and its attached red link stay in state but are suppressed from scene, selection, zoom-to-fit, and fit-to-content export.',
+      position: { x: 80, y: 72 },
+      size: { width: 760, height: 44 },
+      style: { fontSize: 14, fill: '#0f172a' },
+    },
+    {
+      id: 'policy-normal-label',
+      content: 'Normal selectable element',
+      position: { x: 16, y: 14 },
+      ownerId: 'policy-normal',
+    },
+    {
+      id: 'policy-unselectable-label',
+      content: 'Visible but body is unselectable',
+      position: { x: 16, y: 14 },
+      ownerId: 'policy-unselectable',
+    },
+    {
+      id: 'policy-hidden-label',
+      content: 'Hidden in state',
+      position: { x: 16, y: 14 },
+      ownerId: 'policy-hidden',
+    },
+  ],
+});
+
+export const elementVisibilitySelectionDemoConfig: DemoConfig = {
+  id: 'element-visibility-selection',
+  title: 'Element Visibility + Selectability',
+  description:
+    'QA scene for visible-but-unselectable element bodies, hidden-in-state elements, and port/link propagation. Shift + drag marquee to confirm only eligible items are collected.',
+  createState: createElementVisibilitySelectionState,
+  elementShapes: baseElementShapes,
+  portShapes: basePortShapes,
+  defaultElementShapeId: 'default',
+  defaultPortShapeId: 'port-circle',
+  actions: [
+    {
+      id: 'policy-filtered-selection',
+      label: 'Try filtered API selection',
+      run: (editor) => {
+        editor.setSelection([
+          'policy-normal',
+          'policy-unselectable',
+          'policy-hidden',
+          'policy-unselectable-port',
+          'policy-hidden-link',
+        ]);
+      },
+    },
+  ],
+};

package/src/displaybox/demos/index.tsx

@@ -5,7 +5,8 @@ import { linkPortCreationDemoConfig } from './linkPortCreationDemo';
 import { nestedDemoConfig } from './nestedDemo';
 import { customDemoConfig } from './customDemo';
 import { textDemoConfig } from './textDemo';
-import { selectionDemoConfig } from './selectionDemo';
+import { selectionDemoConfig } from './selectionDemo';
+import { elementVisibilitySelectionDemoConfig } from './elementVisibilitySelectionDemo';
 import { eventHandlersDemoConfig } from './eventHandlersDemo';
 import { engineEventsDemoConfig } from './engineEventsDemo';
 import { linkCancelDemoConfig } from './linkCancelDemo';
@@ -94,12 +95,18 @@ export const demoTabs: DemoDefinition[] = [
     description: textDemoConfig.description,
     Component: TextLayoutDemo,
   },
-  {
-    id: selectionDemoConfig.id,
-    title: selectionDemoConfig.title,
-    description: selectionDemoConfig.description,
-    Component: wrapSimpleDemo(selectionDemoConfig),
-  },
+  {
+    id: selectionDemoConfig.id,
+    title: selectionDemoConfig.title,
+    description: selectionDemoConfig.description,
+    Component: wrapSimpleDemo(selectionDemoConfig),
+  },
+  {
+    id: elementVisibilitySelectionDemoConfig.id,
+    title: elementVisibilitySelectionDemoConfig.title,
+    description: elementVisibilitySelectionDemoConfig.description,
+    Component: wrapSimpleDemo(elementVisibilitySelectionDemoConfig),
+  },
   {
     id: eventHandlersDemoConfig.id,
     title: eventHandlersDemoConfig.title,