A tour of ireko

This tour shows the two ideas of ireko with live figures. Each figure starts from a short text in the text language. Select Open in the playground on a figure to change it.

A tree of boxes

A diagram in ireko is a tree. A node with no children is a box. A node with children puts its children on one side, and edges connect them.

root { a b c }

A root with three children. The default strategy is grid, and a linked grid is one row.Open in the playground →

A child can have its own children. The engine gives each subtree the space that it needs, so no two subtrees overlap.

root {
  a { a1 a2 a3 }
  b
  c { c1 c2 }
}

Each column is as wide as its subtree.Open in the playground →

The first idea: a mode for each node

Each node selects where its children go. In the linked mode (the default), the children are around the node. In the nested mode, the children are inside the box of the node. The box becomes a container.

root { a b c d }

linked: the children are below the root, with an edge to each child.Open in the playground →

The second idea: a strategy for each node

Each node also selects how to arrange its children. The built-in strategies are grid, radial, tree and layers. You can add your own.

root nested { a b c d e f }

grid: rows and columns. A nested grid is approximately square.Open in the playground →

Mix them

The strategy and the mode apply to one node only. Each container selects its own. This is the reason for the name: 入れ子 (ireko) is a set of boxes that fit inside each other.

app nested {
  web nested { home cart search account }
  api nested { auth orders payments }
  data nested { postgres redis kafka }
}

All containers use the default grid.Open in the playground →

Edges

The tree gives the edges of the linked children. Other edges go between any two nodes, in all containers. An edge statement is source -> target, with an optional label.

app nested grid(columns: 2) {
  web radial nested { home cart search }
  api { auth orders }
}
cart -> orders "checkout"
web -> api

The dashed edges come from the edge statements. The router draws each edge from border to border.Open in the playground →

The same layout in TypeScript

The text language is one way to write the input. The builder is another. Both give the same plain data.

import { grid, layout, radial } from "ireko";

const root = grid.nested("app", { columns: 2 },
  radial.nested("web", "home", "cart", "search"),
  grid("api", "auth", "orders"),
);
const result = layout({
  root,
  edges: [
    { source: "cart", target: "orders", label: "checkout" },
    { source: "web", target: "api" },
  ],
});

result.nodes;  // a box for each node: { id, x, y, width, height, container, depth, ... }
result.edges;  // a route for each edge: { source, target, kind, points }
result.issues; // the findings of the audit: [] for this input

The result is JSON. You can draw it with the renderers of ireko (SVG, the DOM, Canvas and React Flow), or with your own code.

Your turn

Change the text. The layout changes while you type. A syntax error gets a red underline, and the layout keeps the last text without errors.

# Change a word: grid, radial, tree, nested, linked.
shop nested grid(columns: 2) {
  front radial nested { home search cart account }
  back { orders stock payments }
  data nested { sql cache queue }
  ops radial { logs alerts }
}
cart -> orders
back -> data

17 boxes, 7 edges. The audit finds no defect.

Next steps

The quick start installs ireko and draws a layout in a page, in React, in React Flow or on a server.
Modes and fit and strategies explain each option.
Why two passes explains how the engine prevents overlaps.