Part I · Principles

5 Visual grammar

How a graph is drawn: the canvas, the shape and size of every kind of node, pins, wires, colour and what is drawn over what.

Normative · Level 3Draft 0.120 requirements · Roswaal meets 18

A renderer conforming at level 3 (§1.3) draws a graph as this chapter says. Its numbers are canvas units (§1.4).

5.1 The canvas and its grid

A graph is drawn on an unbounded canvas that pans and zooms. Nodes and comments have positions on it; wires are computed from those positions and are never stored (§9.2).

Generated from core/canvasLayers.ts.

The grid MAY be drawn as dots at each grid point or as ruled lines, and at more than one strength; Roswaal offers both, with dots the default.

5.2 Node geometry

An ordinary node is a header and a body of rows. Its size and the place of every pin follow from these numbers alone, never from measuring text, so a node is the same size in every implementation, every font and at every zoom.

Generated from core/nodeMetrics.ts.

Height

A node's height is its header's height, plus rowHeight for each row, plus footer. The number of rows is the larger of its inputs and its outputs, leaving out the flow pins that ride on the header (§5.5). A node whose only pins ride on the header has no rows; a node with no pins at all has one.

Where a pin is

• The nth row's centre is headerHeight + n × rowHeight + rowHeight / 2 below the node's top, counting from 0.
• A flow pin on the header is centred headerHeight / 2 below the node's top.
• A data pin is centred on the node's left or right edge.
• A flow pin's triangle is 13.86 wide (pinSlot × execAspect) and stands execGap clear of the edge, outside the node. Its wire meets it at the triangle's centre, execGap + width / 2 from the edge.

5.3 Node kinds and shapes

Shape is the first thing read about a node, so each kind has one of its own.

A renderer MAY offer square corners as a preference. A value's corner then squares with a step's, so the two keep their difference in proportion; a capsule, a pill and a knot keep their shapes, which are what say what they are.

5.4 Headers and the category tab

• A step's header is a tint of its category's colour over the node's body: 14% of it in a light theme and 24% in a dark one, with a line at twice that along its lower edge. Its title is drawn in the theme's text colour.
• In the header's left corner is the category tab: tab wide, the full height of the header, filled with the category's colour, holding the category's glyph at 18 units in white. Glyphs are drawn as strokes 2.2 wide on a 24-unit grid, scaled to fit.
• The title starts 8 units after the tab and is cut short with an ellipsis rather than wrapped. A second line, where a node has one, is set smaller under the title, in a monospaced face.
• A value has no tab: its glyph, at 15 units, and its title are drawn in the category's colour, mixed with the text colour enough to stay readable on the body.

Which categories exist, their colours and their glyphs belong to the profile (§10.1). A node that starts or ends a flow, or declares a function, takes the profile's colour and glyph for that, whatever its category, so a graph's entry points can be found first.

5.5 Pins, shapes and type chips

Flow pins

• A flow pin is an equilateral triangle pointing right, drawn outside the node (§5.2), in the colour of a flow wire. It is drawn hollow until a wire is connected and solid after.
• A node's first input, if it is an unnamed flow pin, rides on the header, and so does its first output. Every other flow pin, and every named one, such as Body or True, has a row, because its name is what says where that flow goes.

Data pins

A data pin is centred on the node's edge, in its type's colour, and its shape is its type's family (§6.2):

Generated from core/typeFamily.ts.

Each shape is drawn open while nothing is wired to it and filled once something is, with a thin ring of a dark well colour around it, so it keeps its colour against the node's body on one side and the canvas on the other.

Labels and type chips

• A pin's name is drawn beside it, inside the node, nearly in the text colour.
• An output also shows its type, as a chip: a short name in a rounded box tinted with the type's colour. The chip is left out when the pin is untyped or generic, and when the pin's name already says the type, so a type is never said twice.
• A long type name MAY be shortened on the chip; the profile says how (§10.1).
• A reroute knot, a getter and an operator pill are too small to hold a chip beside their one output, so theirs is centred under them, outside the node, where it takes no part in the node's size or its wires.

5.6 Wires and how they route

• A wire runs from an output to an input. A flow wire is drawn in the theme's flow-wire colour; a data wire in the colour of the pin it leaves.
• A flow wire is drawn heavier than a data wire.

Roswaal offers three routes, as a preference: curved, a cubic curve that leaves and enters its pins horizontally, its control points at least 70 units out; rigid, horizontal and vertical runs; and angular, which cuts its corners. Curved is the default.

5.7 Colour tokens and themes

Every colour on the canvas comes from a theme, a set of named colours, except a category's colour and a type's, which come from the profile. A theme names these roles:

Generated from core/theme.ts.

A theme says whether it is light or dark, and the translucent overlays (hover, the grid, the header tint) are worked out from that rather than chosen, so no theme can make one invisible.

5.8 States and layering

What is drawn over what

Generated from core/canvasLayers.ts.

The panels around the canvas are outside this stack, above it.

Problems are seen first

Other states