@statelyai/layout

Native TypeScript graph layout algorithms built directly on @statelyai/graph.

This is not a new graph interchange format. Public APIs consume Graph and return VisualGraph; positions remain node fields and routes remain GraphEdge.points.

Status

The native layered implementation currently supports flat graphs, cycles, ports, self-loops, four directions, typed constraints, padding, orthogonal routes, and replaceable phases. Native fixed, rectangle-packing, and initial SPOrE implementations are also available. ELK Box SIMPLE placement and seeded Random node placement are translated from Java. Partial, incremental, route-only, and native compound layout remain explicit unimplemented capabilities.

Install

pnpm add @statelyai/layout @statelyai/graph

Quick start

import { createGraph } from "@statelyai/graph";
import { getLayeredLayout, getLayout } from "@statelyai/layout";

const graph = createGraph({
  nodes: [{ id: "a" }, { id: "b" }],
  edges: [{ id: "ab", sourceId: "a", targetId: "b" }],
});

const visualGraph = getLayeredLayout(graph, { direction: "right" });

const result = await getLayout({
  graph,
  algorithm: "layered",
  options: { direction: "right" },
});

result.graph;
result.patches;
result.diagnostics;
result.metrics;

elkjs compatibility

Legacy consumers can migrate through an isolated compatibility entry point:

import ELK from "@statelyai/layout/elkjs";

const elk = new ELK();
const legacyResult = await elk.layout(elkJsonGraph);

The adapter accepts ELK JSON and option aliases, translates to @statelyai/graph, runs native algorithms, and translates the result back. Native algorithms never consume ELK JSON directly.

Parity lab

The browser lab compares 15 already-laid-out graphs in two renderers: a coordinate-faithful SVG geometry inspector and the @statelyai/sdk project embed. It covers all 11 algorithm families exposed by the elkjs 0.11.1 demonstrator surface plus cycle, long-edge, named-port, and compound layered cases. Native and oracle-backed graphs are labeled separately; elkjs is never bundled into the browser.

The SVG layer displays exact node dimensions and coordinates, edge label rectangles, route points, routing modes, and node-relative ports. The SDK layer then shows how the same serialized @statelyai/graph value appears in the Viz project view.

pnpm demo:generate
pnpm demo

The embed target defaults to http://localhost:3000. Override it with ?editor=http://localhost:4864 when the Viz editor runs elsewhere.

Extensibility

Layered phases are replaceable independently:

• breakCycles
• assignLayers
• minimizeCrossings
• placeNodes
• routeEdges

Strategies exchange typed artifacts keyed by graph entity IDs. They never convert the public graph into an ELK-shaped API.

const result = getLayeredLayout(graph, {
  strategies: {
    routeEdges(input, orientation, placement) {
      return myRouter(input, orientation, placement);
    },
  },
});

See Architecture, Roadmap, and Upstream and provenance. Parity tracks API coverage separately from native algorithm fidelity.

Development

pnpm install
pnpm verify
pnpm bench
pnpm demo

pnpm verify checks Oxfmt, Oxlint, source and repository TypeScript projects, generated corpus freshness, tests, declarations/runtime builds, the demo bundle, and the packed package surface.