Nested diagrams

One picture cannot show a system and the inside of every part of it. Give a node a diagram: and the reader can look inside it in two ways: expand it, so the whole inner diagram appears right there as a group, or open it, moving into that diagram with its own views, scenarios and player, and coming back to exactly where they were.

Try it. Click the order service to see a picture of what is inside it. Then expand it, expand the stock card inside it, and open the stock card and use Back.

The shop at a glance. Cards with an Expand and an Open strip on their bottom edge hold a whole diagram of their own: click one to see a picture of it, expand it to see it right here as a group, or open it to move into it and play its scenarios. Back (or the trail above) returns here.

HTTP request / responseQueue / broker

Loading diagram…

Pick a scenario to watch it play.

Declare it

Name the diagram folder, as it is under diagrams/:

nodes:
  orders:
    kind: service
    title: Order service
    diagram: nest-orders

That is all. The inner diagram is an ordinary diagram with its own diagram.yaml, nodes, views and scenarios. Several nodes, in several diagrams, can open the same one.

To open it on a particular view or scenario, use the long form:

  payments:
    title: Payments
    diagram: { name: payments, scenario: pay }

Key	Meaning
`name`	The folder name of the diagram to open.
`view`	The view to show first. Defaults to the scenario’s own view, then the first view.
`scenario`	A scenario to select when it opens. It starts paused, at the beginning.
`mode`	`both` (the default), `expand` or `open`: which of the two ways the reader gets.
`expanded`	`true` to start expanded in place.

Expand or open

Expand shows the node’s diagram in place. The card becomes a group named after the node, with the whole inner diagram inside it, laid out at its own size, and everything around it moves aside. Inside, nodes can be clicked for their details, and a node that holds a diagram of its own can be expanded too, as deep as the system goes. Collapse folds the group back into one card.

Open moves into the diagram instead: it takes the whole frame, with its own views, scenarios and player, and a trail leads back.

Use expand to see how the parts fit together without losing the picture around them, and open to play the inner diagram’s scenarios. Both are offered by default, and an author can choose:

  stock:
    diagram: { name: nest-stock, expanded: true }   # starts expanded
  reports:
    diagram: { name: nest-orders, mode: open }      # can only be opened

The stock service starts expanded: its whole diagram is a group right here. The report can only be opened, because its author did not want it shown in place.

HTTP request / responseQueue / broker

Loading diagram…

Pick a scenario to watch it play.

A node that is expanded behaves as one box for the outer diagram: its edges end on the group, and the outer scenarios arrive at it. An expanded diagram shows one view, the one the node names or, failing that, the first. Its scenarios are played by opening it.

What the reader sees

On the card, a strip with Expand and Open, and a stacked edge, so a node that holds a diagram looks different from one that does not.
In the drawer, clicking the node shows the diagram it holds as a picture, drawn from its real layout and scaled to fit, with its name and how much is in it. The same two are icon buttons beside it, with names for screen readers, so this is the way in for the keyboard too. Once the node is expanded, the diagram itself is on the canvas, so the drawer keeps the buttons (Collapse and Open) and drops the picture.
Expanded, the group has a header with Collapse and Open. The camera glides to it so the reader sees what appeared.
After opening, the diagram zooms in from the card, and a trail appears above it: Online shop › Order service › Stock. Back goes up one level, any crumb jumps straight to that level, and Esc goes up one level too (unless the drawer is open, which closes first). Opening a node that sits inside an expanded group opens every level on the way, so the trail still says where you are.
After going back, the parent is exactly as it was left: same view, same scenario and step, same open drawer, same groups expanded. The card that was opened pulses once, so the eye finds its place.

While a level is covered by one opened from it, its scenario pauses.

The inner diagram’s description, if it has one, is shown above it when it is opened, since the page around it was not written for that diagram.

Deep links

The way down is part of the address, so a link can open straight inside:

#nest-shop~=orders/stock&nest-shop/nest-orders/nest-stock=reserve.3

The first part is the nodes to open, level by level. The second is the scenario and step of the diagram at that level, named by the path of diagrams that leads to it. What is expanded is part of the link too, as #nest-shop+=orders,orders/stock: the paths of the expanded nodes, or none when the author’s own expanded nodes have all been folded.

Rules

A diagram cannot be inside itself. idocs check reports a node that opens its own diagram, or diagrams that open each other in a circle, and names the circle. It also reports a name, view or scenario that does not exist, at the line that wrote it.

Embedding

There is nothing to set up. When the diagrams of a project are loaded, each diagram that opens others carries them inside itself, as nested, so wherever the diagram goes its insides go with it. <Diagram> and <DiagramView> both read them from the diagram:

import { loadProject } from '@the-package-labs/idocs-core/node'

const { diagrams } = loadProject(root)

<DiagramView diagram={diagrams.shop} />

A diagram that opens nothing carries nothing extra. A node whose diagram is missing is drawn like any other node. See props and options.