Layout — interfaces a–h

reference

11 min readUpdated 2026-10-05

Interfaces A–H

Import these from @grafloria/engine.

Interfaces

`ApplyLayoutConfig`

Configuration for applying a layout

ts
interface ApplyLayoutConfig

Properties

Name	Type	Description
`adapter`	`'dagre' \| 'elk' \| LayoutAdapter`	Layout adapter to use (name or instance)
`options?`	`Partial<LayoutOptions>`	Layout-specific options
`animate?`	`boolean`	Whether to animate to new positions
`animationDuration?`	`number`	Animation duration in milliseconds
`fit?`	`boolean`	Whether to fit viewport after layout
`canvasDimensions?`	`{ width: number; height: number }`	Canvas dimensions for viewport fitting
`onProgress?`	`(progress: number) => void`	Progress callback for long-running layouts

`AutoLayoutResult`

Also has every member of LayoutResult, listed on its own entry.

ts
interface AutoLayoutResult extends LayoutResult

Properties

Name	Type	Default	Description
`selection`	`LayoutSelectionReport`		Why this layout, and what the alternatives scored.

`Boundary`

Boundary definition for constraining node movement

ts
interface Boundary

Properties

Name	Type	Description
`minX?`	`number`	Minimum X coordinate (inclusive)
`maxX?`	`number`	Maximum X coordinate (inclusive)
`minY?`	`number`	Minimum Y coordinate (inclusive)
`maxY?`	`number`	Maximum Y coordinate (inclusive)

`BundledEdgePath`

Bundled edge path with control points

ts
interface BundledEdgePath

Properties

Name	Type	Description
`edgeId`	`string`	Edge ID
`controlPoints`	`Point2D[]`	Control points for smooth curve
`bundleId?`	`string`	Bundle ID this edge belongs to
`strength`	`number`	Bundling strength applied (0-1)

`CandidateScore`

Every number behind one candidate's verdict.

ts
interface CandidateScore

Properties

Name	Type	Description
`id`	`string`
`name`	`string`
`options`	`UnifiedLayoutOptions`
`score`	`number`	Final weighted score, 0-100.
`quality`	`LayoutQualityResult`	The classic metrics (crossings, overlap, symmetry, …).
`portRespect`	`number`	Requirement 1: do edges leave in the direction their port faces? 0-100.
`labelClearance`	`number`	Requirement 2: do edge labels stay off the nodes? 0-100.
`bends`	`number \| undefined`	Total bends across the engine's routes; undefined if it reported none.
`area`	`number`	Bounding-box area in px².
`error?`	`string`	Failed to run — kept in the report rather than hidden.

`CircularLayoutOptions`

Also has every member of UnifiedLayoutOptions, LayoutOptions, LayoutRunOptions, listed on their own entries.

ts
interface CircularLayoutOptions extends UnifiedLayoutOptions

Properties

Name	Type	Default	Description
`radius?`	`number`		Force a radius. By default it is derived so nodes never overlap.

`CommunityLayoutOptions`

Also has every member of LayoutOptions, listed on its own entry.

Community detection layout options

ts
interface CommunityLayoutOptions extends LayoutOptions

Properties

Name	Type	Description
`algorithm?`	`'louvain' \| 'label-propagation'`	Community detection algorithm (default: 'louvain')
`resolution?`	`number`	Resolution parameter for community detection (default: 1.0)
`separateCommunities?`	`boolean`	Separate communities visually (default: true)
`communitySpacing?`	`number`	Spacing between communities (default: 200)
`communityLayout?`	`'circular' \| 'grid' \| 'force'`	Layout algorithm for communities (default: 'circular')
`innerLayout?`	`'force' \| 'circular'`	Layout algorithm within communities (default: 'force')
`forceOptions?`	`{ iterations?: number; repulsion?: number; attraction?: number; }`	Force layout options for inner layout

`CompoundLayoutOptions`

ts
interface CompoundLayoutOptions

Properties

Name	Type	Description
`defaultAlgorithm?`	`CompoundAlgorithm`	Default algorithm for groups without an explicit / 'inherit' choice.
`adapters?`	`Record<string, LayoutAdapter \| undefined>`	Injected adapters used as black boxes, keyed by name. Unknown → grid.
`defaultPadding?`	`number`	Fallback padding for groups without their own padding.
`gridGap?`	`number`	Gap between units in the built-in grid.
`layoutTopLevel?`	`boolean`	Also arrange the top level (root groups + ungrouped nodes). Default false.
`layoutOptions?`	`UnifiedLayoutOptions`	Base options in the ONE unified vocabulary (direction / nodeSpacing / rankSpacing / seed), translated per level into whatever that level's engine calls them. Per-group `layoutOptions` are merged OVER these.
`groupOverrides?`	`Record<string, Partial<GroupInfo>>`	Per-group overrides keyed by group id — honors the GroupInfo contract for callers that don't want to store config on the GroupModel. Merged over the group's own `subgraphLayout`.

`CompoundLayoutResult`

ts
interface CompoundLayoutResult

Properties

Name	Type	Description
`laidOut`	`string[]`	Groups laid out, in the order processed (deepest first).
`skipped`	`string[]`	Groups skipped: fixed, collapsed, or inside a collapsed container.
`collapsed`	`string[]`	Groups skipped specifically because they are collapsed (a leaf, not a container).
`groupBounds`	`Map<string, Rect>`	group id → final outer bounds.
`nodePositions`	`Map<string, { x: number; y: number }>`	Final node positions — the LayoutResult contract, so the registry can commit.
`bounds`	`Rect`	Bounding box of everything laid out.

`DagreLayoutOptions`

Also has every member of LayoutOptions, listed on its own entry.

Dagre-specific layout options

ts
interface DagreLayoutOptions extends LayoutOptions

Properties

Name	Type	Description
`rankdir`	`'TB' \| 'BT' \| 'LR' \| 'RL'`	Layout direction
`align?`	`'UL' \| 'UR' \| 'DL' \| 'DR'`	Alignment for rank nodes
`nodesep`	`number`	Separation between adjacent nodes on the same rank (pixels)
`edgesep`	`number`	Separation between adjacent edges (pixels)
`ranksep`	`number`	Separation between ranks (pixels)
`marginx`	`number`	Horizontal margin (pixels)
`marginy`	`number`	Vertical margin (pixels)
`acyclicer?`	`'greedy' \| undefined`	Acyclic strategy for breaking cycles
`ranker`	`'network-simplex' \| 'tight-tree' \| 'longest-path'`	Algorithm for assigning ranks to nodes
`deepRankThreshold?`	`number`	DEEP-GRAPH FAST PATH — rank-count threshold (default 300).

`DiagramLayoutEvent`

Layout event data

ts
interface DiagramLayoutEvent

Properties

Name	Type	Default	Description
`type`	`LayoutEventType`
`algorithmType`	`LayoutAlgorithmType`
`data?`	`any`

`EdgeBundlingOptions`

Configuration for edge bundling

ts
interface EdgeBundlingOptions

Properties

Name	Type	Description
`enabled`	`boolean`	Enable edge bundling
`strategy?`	`EdgeBundlingStrategy`	Bundling strategy to use
`strength?`	`number`	Bundling strength (0 = no bundling, 1 = maximum bundling)
`controlPoints?`	`number`	Number of control points per edge
`smoothness?`	`number`	Smoothness of bundled curves (0-1)
`iterations?`	`number`	Number of iterations for force-directed bundling
`springConstant?`	`number`	Spring constant for force-directed bundling
`compatibilityThreshold?`	`number`	Compatibility threshold (0-1) for bundling edges together
`respectGroups?`	`boolean`	Whether to bundle only edges in same group
`minEdgeLength?`	`number`	Minimum edge length for bundling

`EdgeBundlingResult`

Result of edge bundling computation

ts
interface EdgeBundlingResult

Properties

Name	Type	Description
`bundledPaths`	`Map<string, BundledEdgePath>`	Map of edge ID to bundled path
`bundleCount`	`number`	Number of bundles created
`bundledEdges`	`string[]`	Edges that were bundled
`unbundledEdges`	`string[]`	Edges that were not bundled
`strategy`	`EdgeBundlingStrategy`	Strategy used
`strength`	`number`	Actual strength applied

`EdgeInfo`

Edge information for bundling

ts
interface EdgeInfo

Properties

Name	Type	Description
`id`	`string`	Edge unique identifier
`sourceNodeId`	`string`	Source node ID
`targetNodeId`	`string`	Target node ID
`sourcePortId?`	`string`	Source port ID (optional)
`targetPortId?`	`string`	Target port ID (optional)
`weight?`	`number`	Edge weight/importance
`group?`	`string`	Group identifier for related edges

`ForceDirectedOptions`

Force-directed layout options (for future implementation)

ts
interface ForceDirectedOptions

Properties

Name	Type	Description
`iterations?`	`number`	Number of simulation iterations (default: 100)
`repulsionStrength?`	`number`	Strength of repulsive force between nodes (default: 5000)
`attractionStrength?`	`number`	Strength of attraction between connected nodes (default: 0.01)
`damping?`	`number`	Velocity damping factor (0-1, default: 0.9)
`temperature?`	`number`	Initial temperature for simulation (default: 100)
`coolingFactor?`	`number`	Cooling factor per iteration (default: 0.95)
`minDistance?`	`number`	Minimum distance between nodes (default: 50)
`maxDistance?`	`number`	Maximum distance for force calculation (default: 500)
`centerGravity?`	`number`	Center gravity strength (pulls towards center, default: 0.1)
`pinExistingNodes?`	`boolean`	Pin existing nodes (don't move them)

`ForceLayoutOptions`

Also has every member of LayoutOptions, listed on its own entry.

Force-directed layout options

ts
interface ForceLayoutOptions extends LayoutOptions

Properties

Name	Type	Description
`repulsion?`	`number`	Repulsion strength between nodes (default: 100)
`attraction?`	`number`	Attraction strength along edges (default: 0.2)
`gravity?`	`number`	Gravity pulling nodes to center (default: 0.1)
`temperature?`	`number`	Initial temperature (default: 100)
`cooling?`	`number`	Cooling factor per iteration (default: 0.95)
`iterations?`	`number`	Number of iterations (default: 300)
`threshold?`	`number`	Minimum movement to continue (default: 0.1)
`useBarnesHut?`	`boolean`	Use Barnes-Hut approximation for large graphs (default: true)
`theta?`	`number`	Barnes-Hut theta parameter (default: 0.9)
`linkDistance?`	`number`	Edge length (default: 100)
`randomize?`	`boolean`	Randomize initial positions (default: true)
`removeOverlaps?`	`boolean`	The engine-wide "give me the algorithm's raw output" escape hatch (see UnifiedLayoutOptions in layout-registry.ts). `false` skips the adapter's snapshot-time residual-overlap cleanup too, so what comes back is literally the simulation state — same meaning as everywhere else.

`GraphComponent`

One connected component: its nodes, and the links that live entirely inside it.

ts
interface GraphComponent

Properties

Name	Type	Default	Description
`nodes`	`NodeModel[]`
`links`	`LinkModel[]`

`GraphShape`

What kind of graph is this? Used to pick which candidates are worth RUNNING (a bake-off over five algorithms on a 5,000-node graph is not free) — never to pick the winner. The winner is always decided by measurement.

ts
interface GraphShape

Properties

Name	Type	Description
`nodeCount`	`number`
`linkCount`	`number`
`density`	`number`	links / max-possible-links.
`isTree`	`boolean`	No cycles, and every node has at most one parent.
`isDAG`	`boolean`	Directed, acyclic.
`components`	`number`	Number of connected components.
`hasDeclaredPorts`	`boolean`	Any node carries author-declared ports.
`hasEdgeLabels`	`boolean`	Any link carries a label.

`GridLayoutOptions`

Grid layout options

ts
interface GridLayoutOptions

Properties

Name	Type	Description
`columns?`	`number \| 'auto'`	Number of columns (auto-calculated if not specified)
`startPosition?`	`Point`	Starting position
`horizontalSpacing?`	`number`	Horizontal spacing between nodes
`verticalSpacing?`	`number`	Vertical spacing between nodes
`nodeSize?`	`Size`	Node size for calculations (uses actual size if not specified)
`alignment?`	`'start' \| 'center' \| 'end'`	Alignment within grid cells
`direction?`	`'row' \| 'column'`	Direction of grid filling

`GridLayoutPortfolioOptions`

Also has every member of UnifiedLayoutOptions, LayoutOptions, LayoutRunOptions, listed on their own entries.

ts
interface GridLayoutPortfolioOptions extends UnifiedLayoutOptions

Properties

Name	Type	Default	Description
`columns?`	`number`		Columns in the grid. Defaults to ceil(sqrt(n)) — a roughly square block.

`GroupInfo`

Group/container information for layout

ts
interface GroupInfo

Properties

Name	Type	Description
`id`	`string`	Unique group identifier
`parentId?`	`string`	Parent group ID (if nested)
`memberNodeIds`	`string[]`	Node IDs that belong to this group
`childGroupIds?`	`string[]`	Child group IDs (if this group contains other groups)
`padding?`	`{ top?: number; right?: number; bottom?: number; left?: number; }`	Padding inside the group container
`minSize?`	`{ width: number; height: number; }`	Minimum size for the group
`maxSize?`	`{ width: number; height: number; }`	Maximum size for the group
`fixed?`	`boolean`	Fixed position (group doesn't move during layout)
`fixedSize?`	`boolean`	Fixed size (group size doesn't change to fit content)
`layoutAlgorithm?`	`'dagre' \| 'elk' \| 'inherit'`	Layout algorithm to use for this group's contents
`layoutOptions?`	`any`	Layout options specific to this group
`collapsed?`	`boolean`	Whether this group should collapse its members visually

`HierarchicalOptions`

Hierarchical layout options (for future implementation)

ts
interface HierarchicalOptions

Properties

Name	Type	Description
`direction?`	`'TB' \| 'BT' \| 'LR' \| 'RL'`	Direction of hierarchy
`nodeSpacing?`	`number`	Spacing between nodes in same rank
`rankSpacing?`	`number`	Spacing between ranks/levels
`rankAlgorithm?`	`'longest-path' \| 'coffman-graham'`	Algorithm for rank assignment
`minimizeCrossings?`	`boolean`	Whether to minimize edge crossings
`preserveMentalMap?`	`boolean`	Preserve mental map when re-layouting

`HostLayoutResult`

Also has every member of LayoutResult, listed on its own entry.

ts
interface HostLayoutResult extends LayoutResult

Properties

Name	Type	Description
`algorithm`	`string`
`nodePositions`	`Map<string, { x: number; y: number }>`	Map of node IDs to their new positions
`bounds`	`{ x: number; y: number; width: number; height: number }`	Bounding box of the laid-out graph
`partial`	`boolean`	True when this is a best-so-far answer rather than a finished one.
`reason?`	`LayoutStopReason`
`iteration`	`number`
`totalIterations`	`number`

`HybridOptions`

Hybrid layout options

ts
interface HybridOptions

Properties

Name	Type	Description
`fallbackAlgorithm?`	`'grid' \| 'force-directed' \| 'hierarchical'`	Fallback algorithm if pattern detection fails or confidence is low
`enableAutoSwitch?`	`boolean`	Enable automatic algorithm switching based on pattern detection (default: true)
`analysisThreshold?`	`number`	Confidence threshold for pattern detection (0-1, default: 0.7) If confidence is below this, fallback algorithm is used
`gridOptions?`	`GridLayoutOptions`	Options for each sub-algorithm
`forceDirectedOptions?`	`ForceDirectedOptions`
`hierarchicalOptions?`	`HierarchicalOptions`

Was this page helpful?

ADocs generated by Atloria — from the code, always in sync →