Interaction — interfaces a–t

reference

11 min readUpdated 2026-10-05

Interfaces A–T

Import these from @grafloria/renderer.

Interfaces

`AddWaypointResult`

Result of adding a waypoint

ts
interface AddWaypointResult

Properties

Name	Type	Default	Description
`newPoints`	`Point[]`
`waypointIndex`	`number`
`segmentIndex`	`number`

`AlignmentGuide`

A single alignment snapline. position is the aligned coordinate.

ts
interface AlignmentGuide

Properties

Name	Type	Description
`orientation`	`'vertical' \| 'horizontal'`
`position`	`number`	World x (vertical guide) or world y (horizontal guide).
`from`	`number`	Extent of the drawn line along the other axis.
`to`	`number`
`kind`	`'edge' \| 'center'`

`Announcement`

ts
interface Announcement

Properties

Name	Type	Description
`message`	`string`
`politeness`	`'polite' \| 'assertive'`	`assertive` interrupts the screen reader (errors); default polite.
`seq`	`number`	Monotonic counter — hosts re-announce only when this changes.

`ControlPoint`

Control point information

ts
interface ControlPoint

Properties

Name	Type	Description
`point`	`Point`	Position of the control point
`segmentIndex`	`number`	Index of the segment this control point belongs to
`type`	`'control1' \| 'control2'`	Type of control point (control1 or control2)
`anchor`	`Point`	Anchor point (from/to) that this control point affects

`ControlPointHitResult`

Result of hit testing a control point

ts
interface ControlPointHitResult

Properties

Name	Type	Description
`segmentIndex`	`number`	Index of the segment
`controlType`	`'control1' \| 'control2'`	Type of control point
`point`	`Point`	Position of the control point
`anchor`	`Point`	Anchor point

`DrawToolOptions`

ts
interface DrawToolOptions

Properties

Name	Type	Description
`color?`	`string`
`width?`	`number`
`opacity?`	`number`	Highlighter ink is translucent.
`simplifyEpsilon?`	`number`	Douglas-Peucker tolerance at commit. Omit to use the model's tuned default.
`label?`	`string`	An author label for the committed ink — makes it a NAMED annotation in the a11y tree.
`active?`	`boolean`

`EraserToolOptions`

ts
interface EraserToolOptions

Properties

Name	Type	Default	Description
`radius?`	`number`		Extra hit radius in world units around the eraser path. Default 8.
`active?`	`boolean`

`FocusRing`

What the host draws as the visible focus ring.

ts
interface FocusRing

Properties

Name	Type	Description
`type`	`FocusTargetType`
`id`	`string`
`bounds?`	`Rectangle`	Nodes: the padded world box.
`rotation?`	`number`
`points?`	`Point[]`	Links: the routed polyline.
`label`	`string`	The accessible name announced for this target.

`FocusTarget`

ts
interface FocusTarget

Properties

Name	Type	Default	Description
`type`	`FocusTargetType`
`id`	`string`

`Highlighter`

ts
interface Highlighter

Properties

Name	Type	Description
`id`	`string`	Stable key for the host's keyed list.
`kind`	`HighlighterKind`
`entity`	`'node' \| 'link'`
`entityId`	`string`
`bounds?`	`Rectangle`	Node highlighters: the padded world box to outline.
`rotation?`	`number`	Node highlighters: rotation (deg) about the box centre.
`points?`	`Point[]`	Link highlighters: the routed polyline to trace.
`severity?`	`'error' \| 'warning'`
`message?`	`string`	Validation message (also the accessible description).
`className`	`string`	Suggested CSS class, so a host can theme without re-deriving the kind.

`HighlighterConfig`

ts
interface HighlighterConfig

Properties

Name	Type	Description
`hoverPadding`	`number`	World padding around a node's box, per kind.
`selectionPadding`	`number`
`validationPadding`	`number`
`showHover`	`boolean`
`showSelection`	`boolean`
`showValidation`	`boolean`
`showConnectTargets`	`boolean`

`InkOverlayOptions`

ts
interface InkOverlayOptions

Properties

Name	Type	Default	Description
`root`	`HTMLElement`		The mounted diagram's root (`.grafloria-diagram-root`).
`viewport`	`ViewportController`

`InkPreviewStyle`

How a preview should look while it is being drawn.

ts
interface InkPreviewStyle

Properties

Name	Type	Description
`color`	`string`
`width`	`number`
`opacity?`	`number`
`dashed?`	`boolean`	Dashed outline, for the rectangle tool's rubber-band.

`KeyboardConnectState`

The keyboard-connect state machine.

ts
interface KeyboardConnectState

Properties

Name	Type	Description
`phase`	`'source' \| 'target'`
`sourceNodeId`	`string`
`sourcePortId`	`string`
`targetNodeId?`	`string`
`targetPortId?`	`string`
`valid`	`boolean`	True when the current source/target pair is a legal link.

`KeyboardNavConfig`

ts
interface KeyboardNavConfig

Properties

Name	Type	Description
`nudgeStep`	`number`	Fine nudge step, world units (arrow key).
`coarseNudgeStep`	`number`	Coarse nudge step, world units (Shift + arrow).
`wrapFocus`	`boolean`	Focus wraps around at the ends of the order.
`focusRingPadding`	`number`	World padding of the focus ring around a node's box.

`LinkPartHit`

Part-aware link hit result: a link plus WHICH sub-part of it was hit (body / label / endpoint / arrow) and local info (label index, or the 0-1 position t along the path for body hits). Downstream edge features (inline label editing, endpoint reconnection, edge toolbar) key off part.

ts
interface LinkPartHit

Properties

Name	Type	Default	Description
`link`	`LinkModel`
`part`	`LinkPart`
`labelIndex?`	`number`
`t?`	`number`

`PathHitResult`

Result of hit testing a path segment

ts
interface PathHitResult

Properties

Name	Type	Default	Description
`segmentIndex`	`number`
`insertPosition`	`Point`
`insertIndex`	`number`
`distance`	`number`

`Point`

Point in 2D space

ts
interface Point

Properties

Name	Type	Default	Description
`x`	`number`
`y`	`number`

`PortHit`

A port the magnet found, with its owner.

ts
interface PortHit

Properties

Name	Type	Description
`port`	`PortModel`
`node`	`NodeModel`
`position`	`Point`	World position of the port.
`distance`	`number`

`ProximityCandidate`

A proximity-connect candidate: link source → target if the user drops here.

ts
interface ProximityCandidate

Properties

Name	Type	Default	Description
`sourcePort`	`PortModel`
`targetPort`	`PortModel`
`sourceNodeId`	`string`
`targetNodeId`	`string`
`distance`	`number`

`RectangleToolOptions`

ts
interface RectangleToolOptions

Properties

Name	Type	Description
`fill?`	`string`
`stroke?`	`string`
`strokeWidth?`	`number`
`minSize?`	`number`	Below this size (world px) the drag is treated as a mis-click and no node is made.
`label?`	`string`
`active?`	`boolean`

`ResizeOptions`

ts
interface ResizeOptions

Properties

Name	Type	Description
`minWidth?`	`number`
`minHeight?`	`number`
`maxWidth?`	`number`	Upper bound on the dragged size, clamped DURING the gesture. Default ∞.
`maxHeight?`	`number`
`keepAspect?`	`boolean`	Preserve the starting aspect ratio (corner handles only).
`aspect?`	`number`	Explicit width÷height ratio to lock to (corner handles only). Set by a per-node aspect lock; overrides the start ratio and implies keepAspect.

`SelectionToolLayer`

Everything the host needs to draw the tool layer for the current selection.

ts
interface SelectionToolLayer

Properties

Name	Type	Description
`bounds`	`Rectangle \| null`	World bbox of the selection; null when nothing is selected.
`rotation`	`number`	Rotation (deg) of the single selected node; 0 otherwise.
`center`	`Point \| null`	World centre the bounds rotate about (the frame outline follows it).
`nodeIds`	`string[]`
`linkIds`	`string[]`
`handles`	`ToolHandle[]`

`SelectionToolsConfig`

ts
interface SelectionToolsConfig

Properties

Name	Type	Description
`handleSize`	`number`	Side of a square resize handle, in SCREEN px.
`rotateHandleOffset`	`number`	Distance from the selection's top edge to the rotate handle, SCREEN px.
`haloGap`	`number`	Gap between the selection box and the halo column, SCREEN px.
`haloButtonSize`	`number`	Diameter of a halo button, SCREEN px.
`showHalo`	`boolean`	Show the Halo context toolbar.
`showResizeHandles`	`boolean`	Show the 8 resize handles (single-node selection only).
`showRotateHandle`	`boolean`	Show the rotate handle (single-node selection, `behavior.rotatable`).
`showRemoveButton`	`boolean`	Show the ✕ remove button.
`showLinkTools`	`boolean`	Show link endpoint / vertex tools for a selected link.
`minWidth`	`number`	Smallest width/height a resize may produce, WORLD units.
`minHeight`	`number`
`rotationSnapDegrees`	`number`	Rotation snap while a modifier is held, in degrees.
`resolveNodeToolbar?`	`ToolbarResolver`	Per-TYPE toolbar policy. Layered on top of each node's own `metadata.toolbar`; lets a host decide which tools a node type exposes without touching per-node data. Omit for "every tool, every node".

`SnapConfig`

Framework-agnostic and pure w.r.t. the geometry it is handed: computeSnap takes the moving box + the boxes it may align to and returns the corrected box PLUS the guides a host should draw. Nothing here renders, and nothing mutates the model — except the explicit port-highlight helper, which sets the same isHighlighted / isValidTarget flags the renderer already draws for connection dragging.

Everything is measured in WORLD units. Hosts that want a constant on-screen feel pass snapThreshold: px / zoom (see DiagramCanvasComponent).

ts
interface SnapConfig

Properties

Name	Type	Description
`enabled`	`boolean`	Master switch for alignment snaplines + equal spacing.
`snapToGrid`	`boolean`	Quantise the box to a grid (applied when no alignment guide claims an axis).
`gridSize`	`number`
`snapThreshold`	`number`	Distance (world units) within which an alignment candidate snaps.
`equalSpacing`	`boolean`	Emit equal-spacing guides (Figma/GoJS-style distribution hints).
`keepInBounds`	`Rectangle \| null`	World rectangle the moving box must stay inside (null = unbounded).
`snapToPortRadius`	`number`	Magnetic port radius — the engine's `snapToPortRadius` lives here.
`proximityConnectRadius`	`number`	Drop-a-node-near-a-port auto-link radius (React-Flow proximity connect).

`SnapResult`

ts
interface SnapResult

Properties

Name	Type	Description
`box`	`Rectangle`	The corrected box (grid / alignment / spacing / bounds applied).
`dx`	`number`	Correction applied to the input box.
`dy`	`number`
`guides`	`AlignmentGuide[]`
`spacing`	`SpacingGuide[]`

`SpacingGuide`

An equal-spacing hint: two or more equal gaps, each with a distance label.

ts
interface SpacingGuide

Properties

Name	Type	Description
`orientation`	`'horizontal' \| 'vertical'`
`gap`	`number`	The equal gap, in world units.
`label`	`string`	Human label the host draws at the segment's midpoint (e.g. "40").
`segments`	`Array<{ x1: number; y1: number; x2: number; y2: number }>`	The measured gaps, as segments to draw.

`StrokeEditToolOptions`

ts
interface StrokeEditToolOptions

Properties

Name	Type	Description
`tolerance?`	`number`	Extra hit radius in world units around the ink. Default 6 — finger-friendly.
`highlightColor?`	`string`	Highlight colour for the selected stroke's ghost.
`active?`	`boolean`

`TextEditSession`

ts
interface TextEditSession

Properties

Name	Type	Description
`target`	`TextEditTarget`
`value`	`string`	The text the editor opens with.
`bounds`	`Rectangle`	World rectangle the editor should cover.
`center`	`Point`	World point the editor centres on (labels have no box of their own).
`multiline`	`boolean`	Node labels wrap; link labels are single-line.

`TextEditTarget`

ts
interface TextEditTarget

Properties

Name	Type	Description
`type`	`TextEditTargetType`
`nodeId?`	`string`	Node being edited (`type: 'node'`).
`linkId?`	`string`	Link owning the label (`type: 'link-label'`).
`labelIndex?`	`number`	Which label on that link. Links carry TWO label dialects: the positioned `labels[]` collection, and the DISPLAY label every spec input writes (`edges: [{label}]` → `metadata.label`, painted at the path midpoint).

`ToolModifierState`

Modifier snapshot a host forwards from its pointer events.

ts
interface ToolModifierState

Properties

Name	Type	Default	Description
`shift?`	`boolean`
`alt?`	`boolean`
`ctrl?`	`boolean`
`meta?`	`boolean`

`TouchGestureHost`

Everything the gesture controller needs from its host (keeps it DI-free).

ts
interface TouchGestureHost

Properties

Name	Type	Default	Description
`viewport`	`ViewportController`
`interaction`	`InteractionController`

Members

getEngine(): DiagramEngine | null
getRect(): CanvasRect
requestRender(): void
emit(event: string, payload: unknown): void
isReadonly(): boolean — Live read — read-only can be toggled while the canvas is mounted.

`TouchGestureOptions`

ts
interface TouchGestureOptions

Properties

Name	Type	Description
`enablePan?`	`boolean`
`enableZoom?`	`boolean`
`longPressMs?`	`number`	ms a finger must rest before it becomes a context-menu gesture. Default 500.
`moveTolerancePx?`	`number`	CSS px of travel that cancels a long-press / promotes a tap to a drag. Default 10.
`tapMaxMs?`	`number`	Max ms for a press+release to count as a tap. Default 300.

Was this page helpful?

ADocs generated by Atloria — from the code, always in sync →