Release Announcement: v1.3.0

[draedful]

This release fixes long‑standing issues and makes the library easier to extend.

Features

Unified Selection service — PR #133

Originally the graph exposed only three entity types: blocks, connections, and anchors. After we introduced the public Layer API, it became natural to add custom entities too — groups, comments, and other UI elements. We wanted them to be selectable the same way as the built‑in ones, but selection logic was spread across different stores. We had to duplicate it, reset state per entity type by hand, and keep everything in sync. That was fragile and slowed development.

SelectionService fixes this in a single place. It centralizes selection across the app and defines consistent rules. A SelectionBucket is a per‑entity‑type selection store that encapsulates selection rules. Together they make selection predictable, extensible, and ready for new entity types. See: Selection Manager

Component roles:

• SelectionService — central coordinator. Registers buckets, coordinates their behavior (e.g. REPLACE clears other buckets), exposes a unified API, and provides an aggregated reactive selection state across all types.
• SelectionBucket — per‑type selection store with rules (single/multiple, validation, events). Can work standalone or be attached to the manager for cross‑type coordination.

Usage examples:

import {SelectionService, MultipleSelectionBucket, SingleSelectionBucket, ESelectionStrategy} from "src/services/selection";

// Create service and buckets
const selectionService = new SelectionService();
const blockBucket = new MultipleSelectionBucket<string>("block");
const anchorBucket = new SingleSelectionBucket<string>("anchor");

// Attach buckets to the service to enable cross-bucket coordination
blockBucket.attachToManager(selectionService);
anchorBucket.attachToManager(selectionService);

// Select/append blocks via bucket API (delegated to the service when attached)
blockBucket.select(["b1"], ESelectionStrategy.REPLACE);
blockBucket.select(["b2"], ESelectionStrategy.APPEND);

// Centralized API: select by entity type
selectionService.select("block", ["b3"], ESelectionStrategy.REPLACE);

// Read aggregated selection
const selectedBlocks = selectionService.$selection.value.get("block") ?? new Set<string>();

CameraService: viewport insets — PR #141

In many apps, side panels can cover part of the canvas. The graph’s geometry stays the same, but the perceived center shifts, so fit/center and zoom feel off. Previously we resized the canvas to work around this, which affected math and performance. Now the camera supports viewportInsets: a “focus frame” that defines a virtual center for user actions (zoom, fit/center). Insets affect only centering and fit calculations. They do not change camera geometry and are ignored by spatial culling.

Short example (see more in Camera Service):

// Overlay/panel covers 300px on the left — set focus
camera.setViewportInsets({ left: 300 });

// Fit/center with insets — centering is relative to the visible area
graph.api.zoomToViewPort({ padding: 24 });

// Resize the focus frame while keeping the same visible center over the same world point
camera.setViewportInsets({ left: 200, right: 100 }, { maintain: "center" });

// Read the visible rect (respects insets) and use it in your calculations
const visibleRect = camera.getVisibleCameraRect();

Non‑interactive components and affectsUsableRect

Some layer components are purely decorative: a grid, a watermark, or background frames. For these, it’s important they don’t intercept events and don’t enlarge the graph’s working area.

• interactive: false — the component does not take part in the event model. Events that hit it are not handled by the component and effectively bubble to the parent. In HTML mode, we also disable pointer‑events so clicks and hovers reach interactive elements underneath.
• affectsUsableRect: false — the component does not affect the overall usable rectangle (usableRect). This lets you place it “behind the background” and exclude it from scene‑size calculations.

Side effects:

• These components are excluded from zoomToViewport calculations (those use usableRect). If you want an element to be included in auto‑centering, keep affectsUsableRect: true or apply your own zoom‑to‑rect logic.
• Hit‑testing still works for interactive elements. If a component is non‑interactive, events pass through to the parent.

Example in a custom layer component:

class Watermark extends GraphComponent {
  constructor(props, parent) {
    super({ ...props, interactive: false, affectsUsableRect: false }, parent);
  }
}

// Make the component transparent to events
component.setInteractive(false);

Ports system — PR #128

Originally, connections were created between blocks and anchors. As the system evolved, we needed to connect arbitrary entities (groups, custom components, and more). Extending BaseConnection forever would be costly and fragile. We introduced ports instead — abstract connection endpoints. Now connections are made between ports, while blocks, anchors, and custom entities create and own their ports.

Ports also remove the strict initialization order. Before, it had to be “blocks first, then connections” because connections accessed block components. Now a port can exist on its own and be observed. When the owner appears and claims the port, it starts updating coordinates and the connection just works. This simplifies the lifecycle and makes the system more robust.

Ports are also created lazily. A connection can create a port even before its owner (block/anchor/custom entity) exists. Such a port stays in a temporary “lookup” (ownerless) state. Once the owner registers and claims it, the owner takes over coordinate updates and the connection uses the new data automatically.

More details: Canvas connection system.

Short examples:

// 1) Simple case: declare a connection between blocks — ports are resolved automatically
graph.setEntities({
  connections: [
    { id: "c1", sourceBlockId: "block-1", targetBlockId: "block-2" },
    // if anchorId is provided, anchor ports will be created
    { id: "c2", sourceBlockId: "block-1", sourceAnchorId: "out", targetBlockId: "block-2", targetAnchorId: "in" },
  ],
});

// 2) Advanced case: connect arbitrary entities via direct port IDs
graph.setEntities({
  connections: [
    { id: "c3", sourcePortId: "block-1_output", targetPortId: "group-1_connection_point" },
    { id: "c4", sourcePortId: "group-1_output", targetPortId: "custom-entity/input" },
  ],
});

Fixes

Correct lodash dependency declaration — PR #139

We used to declare lodash-es in package.json, while the code imported lodash. It often worked because lodash arrived transitively from other packages and happened to be in node_modules. This was brittle: in some setups the dependency could be missing. We now declare lodash, matching the code. This removes a hidden source of instability and makes dependencies predictable.