Skip to content
D
Documentation

interfaces

reference
9 min readUpdated

Import these from @grafloria/renderer.

AffordanceOptions

ts
interface AffordanceOptions

Properties

NameTypeDefaultDescription
portAdd?boolean | ((port: PortModel, node: NodeModel) => boolean)"+" on unconnected output ports. true, or a predicate choosing which.
linkAdd?boolean"+" at a hovered link's midpoint.
linkDelete?booleanA delete button beside it.
linkButtons?'hover' | 'hover-and-selected' | 'selected'When a link's buttons show. 'hover' (default): while it is hovered. 'hover-and-selected': also while it is SELECTED (a click selects it), until the selection changes — the only way to reach them on a touch screen. 'selected': ONLY while it is selected — never on hover, so the whole line stays a click target (on a short link the hover buttons cover most of it).
portAddOffset?number | ((port: PortModel, node: NodeModel) => number)How far a free output's "+" sits from its port, in world px — a number, or per port (say, just past an output name drawn beside the card). Default 26.

ClipboardHooks

ts
interface ClipboardHooks

Members

  • onCopy?(data: ClipboardData, kind: 'copy' | 'cut'): void — After a copy or a cut: the diagram's payload, to keep wherever the host keeps its clipboard.
  • onPaste?(): ClipboardData | undefined | Promise<ClipboardData | undefined> — Before a paste: a payload to paste instead of the last copy (read back from the system clipboard, say). Undefined pastes the last copy.

ConnectionOptions

The connection option: how a connection drag finds its target.

ts
interface ConnectionOptions

Properties

NameTypeDefaultDescription
snapToNode?booleanReleasing over a node's BODY (or within snapRadius of it) connects to that node's first input port the rules accept — the first one no validator gives a reason against. While dragging, that node is marked (data-connect-snap on its HTML host, class connect-snap-accept|refuse on an SVG node), and a node whose inputs all refuse shows the first refusal's reason like a port does.
snapRadius?numberWorld px around a node's box that still counts as "on" it. Default 40.

DomEventBinderOptions

ts
interface DomEventBinderOptions

Properties

NameTypeDefaultDescription
enablePan?booleanMiddle-drag / space-drag / wheel-scroll panning. Default true.
enableZoom?booleanCtrl/⌘ + wheel zoom. Default true.
zoomSensitivity?numberRelative zoom step per wheel notch. Default 0.1 (a notch is ×1.1).
dragThreshold?numberCSS px the pointer must travel before a node drag commits. Default 4.
readonly?booleanIgnore every mutation-causing gesture (still pans/zooms). Default false. Through createDiagram/render it locks the document too — see DiagramInstance.setReadonly.
keyboard?boolean | KeyboardOptionsThe built-in key bindings. true (default): as always. false: none at all — the host binds its own. An object opts into owning them key by key ({@link KeyboardOptions.beforeKey}) and adds Ctrl/⌘ X = cut.
connection?ConnectionOptionsHow a connection drag finds its target; see {@link ConnectionOptions}.
nodeDropOnLink?booleanA single node dragged and released over a link emits link:insert-request { linkId, nodeId, clientPoint } and changes nothing; while it is over the link, the link is marked (link-drop-target). Off by default.

EdgeWarning

Why an edge from a spec did not land as written — reported, never thrown (the renderer:warning event). A document can hold a wire that is wrong: a file from an older version, a port that went away. Dropped without a word, the person can neither see it nor remove it.

  • edge-dropped: an end resolves to no port at all (no such node, or no such port and none on the fallback side), so the edge is not in the model.
  • edge-port-fallback: an end names a port the node does not have; the edge was attached to the port on the fallback side instead.
ts
interface EdgeWarning

Properties

NameTypeDefaultDescription
kind'edge-dropped' | 'edge-port-fallback'
edgeIdstring
end'source' | 'target'
nodeIdstring
handle?string
portId?stringThe port the end landed on (edge-port-fallback).
reasonstring

FlowPlaceOptions

ts
interface FlowPlaceOptions

Properties

NameTypeDefaultDescription
direction?'LR' | 'TB''LR' (default) or 'TB'.
rankGap?numberGap between consecutive steps along the flow. Default 80.
nodeGap?numberGap between siblings across the flow. Default 40.
animate?booleanTween the move. Default true (off under prefers-reduced-motion).
duration?numberTween length in ms. Default 280.

GroupFrameStyle

A zone's own frame — what makes a group look like the tinted, captioned regions of the diagrams AI tools draw instead of the theme's titled box. Declaring any of it replaces the theme frame (no title band).

ts
interface GroupFrameStyle

Properties

NameTypeDefaultDescription
fill?string
stroke?string
strokeWidth?number
strokeDasharray?string
borderRadius?number
color?stringCaption colour.
fontSize?numberCaption size in px. Default 11.
fontWeight?string | number
fontFamily?string
letterSpacing?numberCaption letter spacing in px.
textTransform?'none' | 'uppercase' | 'lowercase' | 'capitalize'

GroupSpec

A GROUP in the spec — a zone around some boxes. bounds pins its frame; without it the frame is fitted around children with padding. The children become the group's members (they travel with it). Stored as a GroupModel whose metadata.frameStyle carries style + labelPlacement, so it serializes.

ts
interface GroupSpec

Properties

NameTypeDefaultDescription
idstring
label?string
children?string[]
bounds?{ x: number; y: number; width: number; height: number }
padding?numberSpace between the children and the fitted frame. Default 20.
style?GroupFrameStyle
labelPlacement?GroupLabelPlacementDefault 'top-left'.
direction?'LR' | 'RL' | 'TB' | 'TD' | 'BT'How the zone lays its boxes out under a composing layout: 'LR' a row, 'TB' a column.

InsertNodeOnLinkOptions

ts
interface InsertNodeOnLinkOptions

Properties

NameTypeDefaultDescription
inPort?stringThe new node's port the upstream half enters. Default: its first input port, else its left port.
outPort?stringThe new node's port the downstream half leaves from. Default: its first output port, else its right port.
gap?numberFree space kept on each side of the new node along the flow, in world px. Default 60.
direction?'LR' | 'TB'The flow's axis. Default: from the link's own direction (wider than tall = 'LR').
labels?'upstream' | 'downstream' | 'none'Which half keeps the old link's labels — 'upstream' (default: a branch label such as "true" belongs to the source side), 'downstream', or 'none'.

InsertNodeOnLinkResult

ts
interface InsertNodeOnLinkResult

Properties

NameTypeDefaultDescription
nodeIdstring
upstreamLinkIdstringA → N
downstreamLinkIdstringN → B
movedstring[]Nodes shifted to make room (B and what lies downstream of it).

KeyboardOptions

The keyboard option as an object: the host owns the keyboard, key by key.

ts
interface KeyboardOptions

Members

  • beforeKey?(event: KeyboardEvent, action: KeyAction): boolean | void — Asked before every built-in key action, with the event and what it would do. Return false to cancel it (the binder then neither acts nor calls preventDefault) — e.g. to put the host's own Delete confirmation first.

LinkAddRequest

ts
interface LinkAddRequest

Properties

NameTypeDefaultDescription
linkIdstring
clientPoint{ x: number; y: number }

LoadTextHooks

Hooks a canvas binding gives loadTextInto around the reconcile.

ts
interface LoadTextHooks

Properties

NameTypeDefaultDescription
beforeNodes?() => unknownCalled just before the imported nodes are reconciled; its result goes to afterNodes.
afterNodes?(before: unknown) => voidCalled right after the nodes (and before the edges) are reconciled.
warnEdge?(warning: EdgeWarning) => voidReceives every edge the reconcile drops or re-attaches.

NodeSublabel

A node's second line, when it needs its own font or colour. See NodeSpec.sublabel.

ts
interface NodeSublabel

Properties

NameTypeDefaultDescription
textstring
fontFamily?stringA CSS font stack, or 'mono' for a monospace one.
fontSize?numberpx. Default: 0.85 of the label's size.
color?stringDefault: the theme's secondary text colour.
fontWeight?string | number

NodeTemplateContext

ts
interface NodeTemplateContext

Properties

NameTypeDefaultDescription
nodeNodeModel
zoomnumberThe camera zoom now.
compactbooleanTrue below compactBelow: draw the short form.

NodeTemplateDef

ts
interface NodeTemplateDef

Properties

NameTypeDefaultDescription
renderNodeTemplateFn
compactBelow?numberOverride the instance's compactBelow for this type.
portAnchor?'edge' | 'element'Where an anchored LEFT/RIGHT port sits across the card. 'edge' (default): on its side's edge, level with its element. 'element': at the element's centre, x as well as y — for a card that draws something past its edge (an output's name on the wire), so the wire starts where the element is. One element can ask for it alone with data-port-anchor="element".

Members

  • compact?(data: Record<string, unknown>, ctx: NodeTemplateContext): string | Node — The short form shown below compactBelow (an icon and a title, say). Default: render's html.

NodeTemplateOutput

ts
interface NodeTemplateOutput

Properties

NameTypeDefaultDescription
html?string | NodeThe card's content: markup (the host's own, used as given) or a DOM node.
ports?PortSpec[]The node's ports for this data, in order. Ids are kept stable by the template.
size?{ width: number; height: number }The node's size for this data.

PasteOptions

ts
interface PasteOptions

Properties

NameTypeDefaultDescription
offset?Point
selectPasted?boolean

PlaceNodesOptions

Also has every member of FlowPlaceOptions, listed on its own entry.

ts
interface PlaceNodesOptions extends FlowPlaceOptions

Properties

NameTypeDefaultDescription
after?stringPlace after this node (else after the first step that links into each new node).

PortAddRequest

ts
interface PortAddRequest

Properties

NameTypeDefaultDescription
nodeIdstring
portIdstring
clientPoint{ x: number; y: number }

RenderSchedulerStats

Cheap counters — a steady-state idle canvas should paint 0 frames.

ts
interface RenderSchedulerStats

Properties

NameTypeDefaultDescription
schedulednumberschedule() calls.
paintednumberFrames actually painted (onFrame ran).
skippednumberQueued frames dropped by shouldSkip().
coalescednumberschedule() calls that folded into an already-queued frame.
lastFrameMsnumberDuration (ms) of the most recent paint.

RunOverlay

ts
interface RunOverlay

Properties

NameTypeDefaultDescription
nodes?Record<string, { status?: RunStatus; badge?: string }>
links?Record<string, { label?: string; animate?: boolean }>

TextKit

ts
interface TextKit

Members

  • decorate(diagram: DiagramModel): void — Restyle the freshly imported model (before it reaches the canvas).
  • finalize?(instance: unknown): void — Optional wiring that needs the live instance (called after the load paints).

Was this page helpful?