> Documentation version: main. [HTML page](index.html)

<a id="roc-graph-layout"></a>

# roc-graph-layout

roc-graph-layout computes deterministic node positions, edge routes and drawing
bounds for Roc programs. Your application supplies the graph and the actual
sizes of its nodes; the package does not choose fonts, measure labels or render
the result.

[Download this guide as a PDF](roc-graph-layout.pdf) ·
[API reference](https://lukewilliamboswell.github.io/roc-graph-layout/docs/) ·
[View roc-graph-layout on GitHub](https://github.com/lukewilliamboswell/roc-graph-layout).

<a id="graph-geometry"></a>

## Graph geometry, ready for your renderer

roc-graph-layout computes deterministic node positions, edge routes, and drawing
bounds. Your application supplies the graph and the actual sizes of its nodes;
the package does not choose fonts, measure labels, or render the result.

[See a build pipeline arranged into directed
stages by Layered layout.](https://lukewilliamboswell.github.io/roc-graph-layout/assets/build-pipeline.svg)

[Read the API reference](https://lukewilliamboswell.github.io/roc-graph-layout/docs/) for every layout family, its settings, and
the geometry it returns.

<a id="start-with-the-structure-you-know"></a>

### Start with the structure you know

- A directed pipeline or dependency graph: start with **Layered**.


- An existing hierarchy: use **Tree**.


- A general network: explore **Graph** layouts.


- Domain-specific alignment and separation rules: use **Constrained**.


- Nested groups: use **Compound**.


Read [Choosing a layout](#choosing-a-layout) for the
differences, or browse the [versioned API reference](https://lukewilliamboswell.github.io/roc-graph-layout/docs/) for complete
inputs and settings.

<a id="read-the-result"></a>

### Read the result

Positions are node centers and follow the input node order. Edge routes follow
the input edge order. A route can be a straight line, a polyline, or a chain of
cubic curves. Use the returned bounds to frame the drawing rather than assuming
all coordinates are positive.

For repeated solves of unchanged input and preparation settings, the prepared
APIs let you retain reusable work. Prepare again when the graph changes.

<a id="draw-mermaid-text"></a>

### Draw Mermaid text

The separate Mermaid package reads text, measures labels in Inter, computes
geometry and returns a picture or standalone SVG. The layout package remains
usable on its own with caller-supplied node sizes.

| Declaration | Supported content |
| --- | --- |
| ` flowchart ` or ` graph ` | Nodes, groups, labelled connections, cycles, directions and style classes. |
| ` sequenceDiagram ` | Participants and actors, messages and replies, notes, activations and nested interaction blocks. |
| ` erDiagram ` | Entities, attribute rows, keys and comments, identifying and non-identifying relationships, and cardinalities. |
| ` classDiagram ` | Classes, attributes, methods, annotations, multiplicities and distinct relationship markers. |
| ` stateDiagram ` or ` stateDiagram-v2 ` | States, initial/final markers, transitions, composite states, choice/fork/join markers and notes. |

` Mermaid.svg(source) ` selects the diagram family from its declaration.
` Mermaid.draw(source) ` returns the same drawing as paths and text for a custom
vector renderer. Each family also exposes ` parse ` for inspecting its
source-ordered model. Unknown or unsupported syntax returns problems rather
than a partially interpreted drawing. The family API documentation lists
its supported syntax and limitations; this is not full Mermaid compatibility.

<a id="choose-appearance-without-repeating-defaults"></a>

### Choose appearance without repeating defaults

Import ` mermaid.Mermaid ` and ` mermaid.Theme `, then supply only the properties
you want to change:

``` roc
options = Mermaid.Options.{
    theme: Theme.Options.{ font_size: 16, max_label_width: 180 },
}
svg = Mermaid.svg_with(source, options)
```

The defaults follow pinned Mermaid 12.2.0: white flowchart/state nodes,
coloured actor/table palettes, dark outlines and subtle shadows. The shared
14px font base preserves family proportions, including 16px sequence messages.
Colours, outlines, padding, corner radius and shadows can be overridden.
` wrapping: FamilyDefault ` follows the diagram role; ` Wrap ` uses
` max_label_width `, and ` NoWrap ` keeps explicit source line breaks only.
` corners ` likewise selects family defaults, rounded or square nodes. An empty
` node_palette ` uses the family palette; a one-entry list selects flat colours.
Sequence line/note/control colours use ` message_colors `; transition and
relationship backings use ` transition_label_background `. Flowchart label
backings use ` label_background ` and ` label_background_opacity `.

Sizing happens before placement with the selected typography. Source styles
are interpreted where supported; raw declarations remain in the parsed model,
including reference renderer quirks documented by each family. Arbitrary CSS
and alternate font families are not interpreted.

Invalid numeric theme properties are reported together. Display SVG with
Inter available so visible text matches the measured advances. The package
provides ` Mermaid.font_licence ` for distributions that include the font data.

<a id="choosing-a-layout"></a>

## Choosing a layout

Choose by what the connections mean, not just by the shape you want to draw.

<a id="directed-flows-layered"></a>

### Directed flows: Layered

Use Layered for pipelines, dependencies, and process diagrams. Direction, node
gap, and layer gap control the reading direction and spacing. Cycles are
supported. The exact crossing-reduction option has an effort limit and reports
whether it proved optimality; "exact" does not mean unlimited search.

<a id="hierarchies-tree"></a>

### Hierarchies: Tree

Use Tree when your input already describes a hierarchy. The level-by-level
layout emphasizes depth; the radial layout places the root at the center.
Do not turn an arbitrary network into a tree by silently dropping connections.

<a id="general-networks-graph"></a>

### General networks: Graph

- **Circular** places nodes on a ring, seating neighbors together.


- **Force** uses a seeded simulation to expose organic clusters.


- **Stress** makes drawn distances track graph distances.


- **Radial** emphasizes distance in hops from a selected root.


Keep seeds and settings fixed when comparing graph edits. Iteration limits
bound simulation work; more iterations are not a substitute for choosing the
right meaning for the input.

<a id="domain-rules-and-nested-groups"></a>

### Domain rules and nested groups

**Constrained** combines stress layout with axis separation, alignment, and
containment bands. **Compound** arranges nested groups from their completed
child boxes and routes connections across group boundaries.

<a id="geometry-after-placement"></a>

### Geometry after placement

Pack, Overlap, and Route are placement-independent passes. Metrics lets you
compare crossings, bends, stress, separation violations, and displacement.
Consult the [API reference](https://lukewilliamboswell.github.io/roc-graph-layout/docs/) for each pass’s contract before
composing it with a layout.

[Read the API reference](https://lukewilliamboswell.github.io/roc-graph-layout/docs/) or return to the
[introduction](#graph-geometry).