# Component reference
[README](../README.md) · [Integration guide](integration-guide.md)
This reference describes release **2.0.0**. Groups, undraggable nodes, viewport
resize notifications, link accents and dimming, and rank alignment are new in
2.0; the [changelog](../CHANGELOG.md) lists the migration from 1.x.
Components: [NodeEditor](#nodeeditor), [BaseNode](#basenode), [Pin](#pin),
[Link](#link), [BaseGroup](#basegroup), [GroupSheet](#groupsheet). Rust
helpers: [NodeEditorController](#nodeeditorcontroller),
[GeometryTracker](#geometrytracker), [GroupLogic](#grouplogic),
[Sugiyama layout](#sugiyama-layout).
## NodeEditor
`NodeEditor` inherits `FocusScope`; call `editor.focus()` to focus it
programmatically. For press focus, expose this function on the window:
```slint
public function focus-editor() {
editor.focus();
}
```
`wire_node_editor!` connects `NodeEditorInternalCallbacks.take-editor-focus`
to that function. Manual integrations must install the same synchronous
callback. Canvas, node, pin, minimap, and reserved marquee presses focus the
editor; embedded controls that accept the press retain their own focus.
Application callbacks may then move focus elsewhere. Do not defer this callback:
a delayed focus request can steal focus from a newly opened control.
Key bindings remain application-owned. Handle them in a parent `FocusScope`.
**Properties:**
```slint
in-out property <length> pan-x; // Pan offset (x)
in-out property <length> pan-y; // Pan offset (y)
in-out property <float> zoom; // Zoom factor (1.0 = 100%)
in property <float> min-zoom: 0.1; // Minimum zoom level
in property <float> max-zoom: 3.0; // Maximum zoom level
in property <bool> pinch-zoom-enabled: true;
in property <float> scroll-zoom-sensitivity: 0.002;
in property <length> world-content-size: 100000px;
// Host-side convenience values: pass these to custom node delegates that
// implement LOD or minimum sizing. NodeEditor does not resize nodes itself.
in property <float> lod-full-threshold: 0.5;
in property <float> lod-simplified-threshold: 0.25;
in property <length> min-node-width: 80px;
in property <length> min-node-height: 40px;
in property <length> grid-spacing: 24px; // Grid cell size
in property <color> grid-color: #404040; // Grid line color
in property <brush> background-color: #1a1a1a; // Background color
in property <brush> edge-fade-left: transparent;
in property <length> edge-fade-left-width: 0px;
in property <brush> edge-fade-right: transparent;
in property <length> edge-fade-right-width: 0px;
in property <bool> has-link-selection: false; // Enable host compute-link-at picking
in property <[LinkData]> links: [];
in property <length> link-hover-distance: 8px; // Click tolerance for links
in property <length> pin-hit-radius: 10px; // Hit radius for pins
in property <int> link-hit-samples: 20; // Bezier samples for hit-testing
in property <float> bezier-min-offset: 50.0; // Min horizontal offset for curves
in property <bool> box-selection-on-empty: true;
in property <BoxSelectionModifier> box-selection-modifier: BoxSelectionModifier.ctrl;
// Link colours: the palette LinkData.accent indexes from 1 (see Link)
in property <[color]> link-accent-colors: [];
// The fraction of its alpha a dimmed link keeps (see Link)
in property <float> dimmed-link-alpha: 0.25;
// Minimap
in property <bool> minimap-enabled: false;
in property <MinimapPosition> minimap-position: bottom-right;
in property <length> minimap-size-width: 180px;
in property <length> minimap-size-height: 135px;
in property <length> minimap-margin: 24px;
// Optional path rendering instead of minimap-nodes rectangles
in property <string> minimap-nodes-path: "";
in property <int> minimap-path-version: 0;
// Selection lives in the application — see "Callbacks (Selection)" below.
// The editor stores none of it; `selected` is per-row data on your node models
// and on LinkData.
// Geometry & Rendering
in-out property <string> grid-commands; // SVG path generated by wire_node_editor!
in-out property <int> geometry-version <=> GeometryVersion.version;
in property <[MinimapNode]> minimap-nodes: []; // Minimap data
// Groups: one GroupSheet per row below the links — see BaseGroup.
// Membership is the `group-id` on your node rows, not a list here.
in property <[GroupData]> groups: [];
in-out property <length> graph-min-x; // Graph bounds
in-out property <length> graph-max-x;
in-out property <length> graph-min-y;
in-out property <length> graph-max-y;
// Interaction state (outputs are read-only; link-end coordinates are writable)
out property <bool> is-selecting; // User is dragging selection box
out property <length> selection-x; // Selection box position
out property <length> selection-y;
out property <length> selection-width; // Selection box size
out property <length> selection-height;
out property <bool> is-creating-link; // User is dragging to create link
out property <length> link-start-x; // Link preview start
out property <length> link-start-y;
in-out property <length> link-end-x; // Link preview end
in-out property <length> link-end-y;
out property <int> link-start-pin-id; // Which pin started the link
out property <length> context-menu-x; // Right-click position
out property <length> context-menu-y;
out property <int> hovered-link-id; // -1 when no link
out property <int> hovered-node-id; // 0 when no node
```
**Callbacks (Computation):**
Link picking remains a host callback because it needs the host's link model.
Set `has-link-selection: true` and install `compute-link-at` to enable picking:
```slint
/// Compute which link is at world position (x, y)
callback compute-link-at(x: length, y: length) -> int;
```
For path-based minimap rendering, the callback belongs to `NodeEditor`, not
`NodeEditorComputations`. Expose it on the window for a Rust handler:
```slint
pure callback compute-minimap-nodes-path <=> editor.compute-minimap-nodes-path;
```
It takes `(version: int, scale: float, offset-x: float, offset-y: float)` and
returns SVG commands in minimap coordinates. Otherwise supply `minimap-nodes`
or `minimap-nodes-path` directly.
The standard Rust computations live on the exported
`NodeEditorComputations` global. `wire_node_editor!` installs their default
implementations and synchronizes `grid-spacing` and `bezier-min-offset` with
the controller. Applications that replace a handler do so on this global; the
last installed handler wins.
| `viewport-changed(zoom, pan-x, pan-y)` | Zoom or pan changes | Scale and logical-pixel pan offsets |
| `viewport-resized(width, height)` | Once after a batch of editor size changes | Final editor dimensions in logical pixels, before dividing by zoom |
| `request-grid-update()` | Viewport, size, or grid-spacing changes | None; requests grid regeneration |
The `NodeEditorComputations.viewport-resized` callback lets hosts
track the visible area even when no grid is drawn. The dimensions are those of the editor, which may occupy
only part of its window. `wire_node_editor!` leaves this handler to the host.
Notifications are deferred and are not replayed when a handler is connected.
Seed the host's initial size from the laid-out editor, as shown in the
[integration guide](integration-guide.md#viewport-size-and-transform).
```slint
NodeEditorComputations.compute-pin-at(world-x, world-y, world-radius);
NodeEditorComputations.compute-link-path(start-pin, end-pin, geometry-version); // world geometry
NodeEditorComputations.compute-link-preview-path(screen-start-x, screen-start-y,
screen-end-x, screen-end-y,
zoom, world-offset);
NodeEditorComputations.request-grid-update();
```
BaseNode and BaseGroup double-clicks, and the default sheet's collapse
toggle, are emitted through the exported public event global:
```slint
NodeEditorEvents.node-double-clicked(node-id) => { /* handle event */ }
// Group events
NodeEditorEvents.group-double-clicked(group-id) => { /* handle event */ }
/// The sheet asked for an explicit collapsed state; `wire_groups!` applies it.
NodeEditorEvents.group-collapse-requested(group-id, collapsed) => { /* … */ }
```
**Callbacks (Selection):**
Selection lives in the `selected` fields of your node rows, `LinkData` and
`GroupData`. The editor reports gestures and renders those flags;
`wire_selection!` updates them using the standard selection policy.
```slint
/// A node was clicked (or dragged while unselected):
/// replace the selection with it, or toggle it when shift-held
callback node-selected(node-id: int, shift-held: bool);
/// A link was clicked — same semantics
callback select-link(link-id: int, shift-held: bool);
/// A group sheet was clicked — same semantics; a plain click is exclusive
/// across nodes, links and groups
callback group-selected(group-id: int, shift-held: bool);
/// The background was clicked: drop the whole selection
callback selection-cleared();
/// A marquee was released over this world-coordinate rectangle:
/// hit-test it and select the hits, extending the selection when shift-held
callback box-selection-committed(x: length, y: length, w: length, h: length, shift-held: bool);
```
Handlers for selection intents that can affect a subsequent drag must update
the rows' `selected` flags before returning; the live multi-node preview and
drag commit read those flags. `wire_selection!` provides this behavior.
Applications that defer selection projection must also own their drag policy
and commit. Selection changes during an active drag are otherwise unspecified.
On the Rust side the `selection` module holds the policy — `resolve_click` and
`resolve_box` turn a gesture and the current set into the new set, and
`project_selection` writes a set into the rows. Every intent resolves to an
**absolute set**, never a delta, and both resolvers are order-stable.
`wire_selection!` composes them for the common case — rows with `id` and
`selected` fields — and keeps no state of its own. This wiring fragment uses
the models and setup constructed in the [quick start](integration-guide.md):
```rust
let setup = NodeEditorSetup::new({
let nodes = nodes.clone();
move |dragged, dx, dy| GraphLogic::commit_drag(&nodes, dragged, dx, dy)
});
wire_node_editor!(window, setup);
wire_selection!(window, setup, nodes); // nodes only
wire_selection!(window, setup, nodes, links); // …or nodes and links
wire_selection!(window, setup, nodes, links, groups); // …or with groups
```
Applications with several node models or their own gesture semantics wire the
callbacks by hand out of the `selection` module — see the `advanced`
example, which spans two node models sharing one id space.
`GraphLogic::commit_drag` moves the dragged
node plus every row the model shows as selected and draggable, which is the
same data the editor renders.
`box-selection-modifier` reserves a left-button marquee over every editor
surface, including links, nodes, pins, and controls embedded in nodes. `ctrl`
also accepts Command/Meta. `none` reserves no gestures; ordinary input reaches
each surface and `box-selection-on-empty` still controls background marquees.
The editor observes modifier keys without consuming them, so application
shortcuts continue to receive the same key events.
Pointer cancellation, release outside, focus loss, hiding, and disabling clear
transient drag, link, pan, context-menu, and marquee state. A host that removes
an editor conditionally should call `cancel-interactions()` before removal.
**Callbacks (Events):**
```slint
/// User completed a link (dragged from one pin to another)
callback link-requested(start-pin-id: int, end-pin-id: int);
/// Released without a target pin; coordinates are world-space floats
callback link-dropped(start-pin-id: int, world-x: float, world-y: float);
/// The host cancelled link creation through cancel-link-creation()
callback link-cancelled();
/// hovered-link-id changed: the pointer moved onto or off a link, or left the
/// canvas for a node drawn over it or for outside the window (-1)
callback link-hovered();
/// Hover changed; read hovered-node-id (0 when no node)
callback node-hovered();
/// User right-clicked (context menu)
callback context-menu-requested();
callback context-menu-dragged(x: length, y: length);
callback context-menu-released(x: length, y: length);
```
**Functions (Helper API):**
```slint
/// Report node geometry through the canonical lifecycle and schedule a refresh.
function report-node-rect(id: int, x: length, y: length, w: length, h: length);
/// Report pin geometry through the canonical lifecycle and schedule a refresh.
function report-pin-position(pin-id: int, node-id: int, pin-type: int, rel-x: length, rel-y: length);
/// Start link creation from a pin
function start-link-from-pin(pin_id: int, x: length, y: length);
/// Update link end position during creation
function update-link-end(x: length, y: length);
/// Complete link creation (checks for pin at end pos)
function complete-link-creation();
/// Force re-computation of all link paths
function refresh-links();
function cancel-link-creation();
function cancel-interactions();
function select-node(node-id: int, shift-held: bool);
function select-group(group-id: int, shift-held: bool);
function clear-selection();
```
## BaseNode
Base component for creating custom nodes. Provides drag handling and selection.
**Properties:**
```slint
in property <int> group-id: 0; // Group membership, 0 = none
out property <bool> hovered;
in property <int> node-id; // Unique node ID
in property <length> world-x; // X position in graph space
in property <length> world-y; // Y position in graph space
in property <bool> selected: false; // Selection state — bind it from your model row
in property <bool> draggable: true; // Off: only its group's drag moves it — bind it from your model row
in property <length> node-width: 150px;
in property <length> node-height: 100px;
out property <length> screen-x; // Includes the current global zoom/pan
out property <length> screen-y;
```
`BaseNode` reads zoom and pan from `ViewportState`; consumers do not pass those
values into each node.
A subclass's elements sit inside the node's drag area, so `hovered` stays true
while the pointer is over any of them — fields, labels, pins — and a press no
child takes still selects or drags the node. While a child holds a press, such
as a link dragged from one of its pins, the node stays hovered until the
release. Content drawn outside the node's `node-width` × `node-height` does not
hover it: the outer half of a pin centred on the node's edge leaves the node
unhovered. Size the node to include such content when its hover matters there.
With `draggable` off, a user drag moves the node only with its group. A left
drag starting on the node draws a marquee when the editor's
`box-selection-on-empty` is on and does nothing otherwise; the host sees no
`start-node-drag` or `end-node-drag`. A press still selects the node, and the
release is no click. A drag of other selected nodes leaves it in place, and a
group that moves, its sheet dragged or the group selected, carries it.
Bind `draggable` from the same row field your `MovableNode::draggable` returns,
as you bind `selected`: the node previews the drag from the property and
`GraphLogic::commit_drag` / `GroupLogic::commit_drag` read the trait, so two
sources let a node stand still under a drag and jump on release. A Slint
struct's `bool` field defaults to `false`, so a `draggable` field on a row
built with `Default` makes that node undraggable. Host writes to the rows,
such as a layout or an undo, are not governed by `draggable`.
## Pin
Represents a connection point on a node.
**Properties:**
```slint
in property <int> pin-id; // Pin ID (encoded by application)
in property <int> node-id; // Parent node ID
in property <int> pin-type; // PinTypes.input or .output (or custom)
in property <color> base-color: #888;
in property <color> hover-color: #aaa;
in property <length> node-screen-x; // Required for drag handling
in property <length> node-screen-y; // Required for drag handling
in property <length> parent-offset-x: 0px; // For pins inside wrappers
in property <length> parent-offset-y: 0px;
in property <int> refresh-trigger: 0; // Force geometry re-reporting
```
## Link
Renders a Bezier curve between two pins. Used internally by `NodeEditor` but can be used for custom rendering.
The element is sized to the curve, not to the canvas. That is what lets a
partial renderer repaint one link's strip instead of the whole graph — so a
`LinkPath` whose box does not contain what its `commands` draw leaves stale
pixels. `Link` pads the box for the stroke itself; the box is the centreline's.
**Properties:**
```slint
in property <LinkPath> geometry; // commands relative to x/y, plus the box
in property <color> link-color: #888;
in property <length> line-width: 2px;
in property <bool> selected: false;
in property <bool> hovered: false;
```
**Link colour.** `LinkData` contains `id`, `start-pin-id`,
`end-pin-id`, `color`, `line-width`, `selected`, `status`, `accent`, and `dimmed`.
`LinkData::new` constructs a 2px link with `status: -1`, `accent: 0`, and
`dimmed: false`. Struct defaults give `status: 0` (idle), which overrides `color`.
`LinkColor.of(link: LinkData, accents: [color], dimmed-alpha: float) -> color`
resolves colours in this order:
| Known status: idle (0), running (1), succeeded (2), failed (3) | Corresponding `LinkStatusColors` property |
| Otherwise, `accent` in `1..=accents.length` | `accents[accent - 1]` |
| Otherwise | `link.color` |
Last, `dimmed: true` multiplies the resolved alpha by `dimmed-alpha`, preserving
RGB. The editor supplies `link-accent-colors` and `dimmed-link-alpha` (default
0.25). Use a fraction from 0 to 1. An already translucent colour remains
proportionally translucent; hover and selection preserve that alpha.
```slint
// A host drawing its own links can apply the same rule:
link-color: LinkColor.of(link, [#4fc3f7, #ffb74d], 0.25);
```
The [custom-shapes example](../examples/custom-shapes) changes the palette
reactively and dims links outside Node A's focus.
**`LinkPath`:**
```slint
struct LinkPath {
commands: string, // SVG path, relative to x/y (e.g., "M 0 0 C 50 0 50 100 100 100")
x: length, y: length,
width: length, height: length,
}
```
`CubicBezier::to_link_path` takes a constructor closure so it works with either
the crate's `LinkPath` or a locally generated Slint type. Supply the endpoints
and your `LinkPath` type:
```rust
use slint_node_editor::path::CubicBezier;
let curve = CubicBezier::from_endpoints(sx, sy, ex, ey, 1.0, 50.0);
x,
y,
width,
height,
})
```
## BaseGroup
An association of nodes rendered as a backing sheet behind its members. A
group is not a node: it has no pins and cannot be linked. `BaseGroup` carries
the sheet's drag gesture, selection intent and geometry reporting, mirroring
`BaseNode`.
Membership lives on the nodes. A `BaseNode` whose `group-id` matches follows
the sheet's drag and hides while the group is collapsed. The sheet's rectangle
is the host's authoritative bounds: the library never resizes it. Collapsed,
the sheet shows only its header band, and that band is what a marquee and the
minimap see.
**Properties:**
```slint
in property <int> group-id;
in property <bool> selected: false; // Bind from your group row
in property <bool> collapsed: false; // Members hide while true
in property <length> world-x; // Authoritative bounds, world space
in property <length> world-y;
in property <length> group-width: 200px;
in property <length> group-height: 150px;
in property <length> header-height: GroupStyleDefaults.header-height;
in property <bool> header-only-input: false; // Only the header band takes input
out property <length> displayed-height; // header-height while collapsed
out property <length> screen-x;
out property <length> screen-y;
out property <bool> hovered;
```
**Where it renders.** `NodeEditor` instantiates a `GroupSheet` for every row of
its `groups` model *below the links*, so internal links stay visible, and below
the nodes, so members win the press. A host that wants a different look derives
from `BaseGroup` and places it among the editor's children; that renders above
the links, so keep the interior translucent. Hit testing is rectangular whatever
the subclass draws.
**Movement.** One rule decides what a drag moves, whether it started on a node
or on a sheet: the dragged item, every selected draggable node, every selected
group's sheet, and the members of every group that moves, draggable or not. The
editor asks the host the same question for its live preview
(`NodeEditorComputations.group-in-drag`) that the host's commit answers with
`GroupLogic`, so the preview and the committed positions cannot disagree.
Members are never marked selected to achieve this.
**Collapse** is a visibility projection, not a removal. Members are not
rendered, take no input, and report themselves hidden; the geometry cache keeps
their rectangles but excludes them from marquee, pin and link picking, and a
link with a hidden endpoint has no route and is not drawn. Boundary links that
terminate at the collapsed sheet are a later extension.
**Cancellation.** Collapsing, changing a membership, removing a member, or
removing the group during an active gesture cancels that gesture before the
projection changes; nothing is committed on the release.
**Lifecycle.** Hosts call `NodeEditorInternalCallbacks.remove-group(id)` when
removing a group row, as they call `remove-node` for a node.
## GroupSheet
The default look for `BaseGroup`: a translucent rounded rectangle with a
header band carrying the title and a collapse toggle. Below the
`lod-simplified-threshold` it is a flat box. The toggle emits
`NodeEditorEvents.group-collapse-requested(group-id, collapsed)` with an
explicit target value, so a repeated request is idempotent.
```slint
in property <string> title;
in property <color> sheet-color; // transparent = GroupStyleDefaults.sheet-color
in property <float> lod-simplified-threshold: 0.25;
```
Restyle every sheet through the `GroupStyleDefaults` global (`sheet-color`,
`body-opacity`, `header-opacity`, `header-height`, `border-radius`, border
widths and colours, title colour and size), one sheet through
`GroupData.color`, or derive from `BaseGroup` for another look.
**`GroupData`:**
```slint
struct GroupData {
id: int,
title: string,
x: length, y: length, width: length, height: length, // authoritative bounds
color: color, // transparent = defaults
collapsed: bool,
selected: bool, // the editor never writes it
}
```
## Rust helpers
The library provides Rust helpers to reduce boilerplate.
### NodeEditorController
The `NodeEditorController` is a high-level helper that manages geometry tracking, zoom state, and link path computation. It provides ready-to-use callback implementations.
```rust
// Fragment from the quick start linked above.
});
let controller = setup.controller().clone();
wire_node_editor!(window, setup);
```
Prefer `NodeEditorSetup` plus `wire_node_editor!` for the standard integration.
Use the cloned controller for host policies such as validation, custom picking
and deletion. If an application wires globals manually, the macro source in
[`src/lib.rs`](../src/lib.rs) is the canonical list of handlers and units.
Node and pin geometry is a projection of the application's graph model. Retire
that projection whenever the model removes an object, and reset it after
replacing the whole graph. This fragment uses the generated window and IDs
from the [quick start](integration-guide.md):
```rust
let lifecycle = window.global::<NodeEditorInternalCallbacks>();
// Remove connected logical links in the host model, then:
lifecycle.invoke_remove_pin(pin_id);
lifecycle.invoke_remove_node(node_id); // also retires pins owned by the node
// After installing another graph model (including one that reuses IDs):
lifecycle.invoke_reset_graph();
```
These functions also clear editor interactions that refer to retired objects.
The module exports `InteractionCancellation`, `BoxSelectionGesture`, and
`NodeEditorGestureConfig` so library functions and consumer components share
their state. `BoxSelectionGestureState` is exported by the Slint module as the
type of its internal marquee state. Hosts should use the lifecycle functions
above and the editor's gesture properties rather than modifying these internal
globals directly.
Retiring a pin or node also cancels an active forwarded marquee, since its
pointer grab may belong to the retired component; forwarded gestures do not
track their source ID.
Call the controller's `remove_pin`, `remove_node`, or `reset_graph` methods when
there is no Slint component instance. A hidden or disabled `Pin` remains
available to route existing links, but it is excluded from pin hit testing
until eligible again. Pin picking chooses the nearest eligible pin within the
radius; exact distance ties choose the lowest pin ID, independent of cache
insertion order.
### GeometryTracker
For lower-level integrations without `NodeEditorSetup`, `GeometryTracker`
provides callback closures that update a standalone cache. This fragment leaves
the application's IDs and world-space coordinates as local variables:
```rust
use slint_node_editor::GeometryTracker;
let tracker = GeometryTracker::new();
let report_node = tracker.node_rect_callback();
let report_pin = tracker.pin_position_callback();
report_node(node_id, x, y, width, height);
report_pin(pin_id, node_id, pin_type, relative_x, relative_y);
let cache = tracker.cache();
```
All coordinates in these callbacks are world-space `f32` values. When using
live `BaseNode` and `Pin` components, `wire_node_editor!` already installs the
equivalent lifecycle and a second tracker is unnecessary.
### GroupLogic
Operations on group rows and node membership, all plain functions over
models: there is no library-side membership index. Node rows implement
`MovableNode` and `GroupMember` (`group_id`, `set_group_id`); group rows
implement `GroupModel` (`id`, `bounds`, `set_bounds`, `selected`, `collapsed`,
`set_collapsed`), which the library implements for `GroupData`.
```rust
use slint_node_editor::{wire_groups, GroupLogic, NodeEditorSetup};
// One movement rule for both gestures: `dragged` is Dragged::Node or ::Group.
let setup = NodeEditorSetup::with_drag_commit({
let (nodes, groups) = (nodes.clone(), groups.clone());
move |dragged, dx, dy| GroupLogic::commit_drag(&nodes, &groups, dragged, dx, dy)
});
wire_node_editor!(window, setup);
wire_selection!(window, setup, nodes, links, groups);
wire_groups!(window, groups, nodes); // group-in-drag, group-collapsed, collapse requests
// Host policy on top:
let members = GroupLogic::selected_ungrouped(&*nodes); // do not reassign existing members
let bounds = GroupLogic::fit_bounds(&cache.borrow(), &members, 24.0);
GroupLogic::assign_members(&nodes, &members, id);
GroupLogic::set_bounds(&groups, id, bounds.unwrap());
GroupLogic::set_collapsed(&groups, &nodes, id, true, |n| &mut n.selected); // deselects hidden members
GroupLogic::remove_member(&nodes, node_id);
GroupLogic::dissolve_group(&nodes, &groups, id); // then remove-group(id) in Slint
```
`GroupLogic::moves` is the movement rule itself; `commit_node_drag` (once per
node model) and `commit_group_drag` (once) apply it for hosts with several
node models, which also install the three answers `wire_groups!` wires by
hand. `Bounds::enclosing` fits a sheet from rows a host sizes itself, so a
drag commit can refit synchronously — see the `groups` example.
### Sugiyama layout
Enable the `layout` Cargo feature to use these helpers.
`sugiyama_layout` accepts node-ID edges;
`sugiyama_layout_from_cache` accepts pin-ID edges resolved through a
`GeometryCache`. Both entry points produce the same canonical result: the
first size for each node ID wins, valid nodes and edges are ordered by ID,
and duplicate edges, self-loops, and edges with missing endpoints are ignored.
Nodes with non-finite or non-positive dimensions are omitted. Disconnected
components are ordered by their lowest node ID and packed along the axis
perpendicular to the layout direction without overlap. Positions are the
nodes' top-left corners, and each component's first rank starts at 0 on the
layer axis; 1.x returned centres. `SugiyamaConfig::rank_alignment` lines a
rank's nodes up on their centre (`RankAlignment::Center`, the default) or on the
rank's leading edge
(`RankAlignment::Start`), which matters when they differ in extent along the
layer axis.
The [sugiyama example](../examples/sugiyama) uses unequal node sizes and lets
you switch between centre and start alignment. Changing the choice applies
Auto Layout immediately; the button reapplies the current choice.