# Interfaces

Import these from `@grafloria/renderer`.

### `AffordanceOptions`

```ts
interface AffordanceOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `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?` | `boolean` |  | A 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**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `snapToNode?` | `boolean` |  | Releasing 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?` | `number` |  | World px around a node's box that still counts as "on" it. Default 40. |

### `DomEventBinderOptions`

```ts
interface DomEventBinderOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `enablePan?` | `boolean` |  | Middle-drag / space-drag / wheel-scroll panning. Default true. |
| `enableZoom?` | `boolean` |  | Ctrl/⌘ + wheel zoom. Default true. |
| `zoomSensitivity?` | `number` |  | Relative zoom step per wheel notch. Default 0.1 (a notch is ×1.1). |
| `dragThreshold?` | `number` |  | CSS px the pointer must travel before a node drag commits. Default 4. |
| `readonly?` | `boolean` |  | Ignore every mutation-causing gesture (still pans/zooms). Default false. Through `createDiagram`/`render` it locks the document too — see `DiagramInstance.setReadonly`. |
| `keyboard?` | `boolean \| KeyboardOptions` |  | The 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?` | `ConnectionOptions` |  | How a connection drag finds its target; see {@link ConnectionOptions}. |
| `nodeDropOnLink?` | `boolean` |  | A 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**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `kind` | `'edge-dropped' \| 'edge-port-fallback'` |  |  |
| `edgeId` | `string` |  |  |
| `end` | `'source' \| 'target'` |  |  |
| `nodeId` | `string` |  |  |
| `handle?` | `string` |  |  |
| `portId?` | `string` |  | The port the end landed on (`edge-port-fallback`). |
| `reason` | `string` |  |  |

### `FlowPlaceOptions`

```ts
interface FlowPlaceOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `direction?` | `'LR' \| 'TB'` |  | `'LR'` (default) or `'TB'`. |
| `rankGap?` | `number` |  | Gap between consecutive steps along the flow. Default 80. |
| `nodeGap?` | `number` |  | Gap between siblings across the flow. Default 40. |
| `animate?` | `boolean` |  | Tween the move. Default true (off under `prefers-reduced-motion`). |
| `duration?` | `number` |  | Tween 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**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fill?` | `string` |  |  |
| `stroke?` | `string` |  |  |
| `strokeWidth?` | `number` |  |  |
| `strokeDasharray?` | `string` |  |  |
| `borderRadius?` | `number` |  |  |
| `color?` | `string` |  | Caption colour. |
| `fontSize?` | `number` |  | Caption size in px. Default 11. |
| `fontWeight?` | `string \| number` |  |  |
| `fontFamily?` | `string` |  |  |
| `letterSpacing?` | `number` |  | Caption 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**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `label?` | `string` |  |  |
| `children?` | `string[]` |  |  |
| `bounds?` | `{ x: number; y: number; width: number; height: number }` |  |  |
| `padding?` | `number` |  | Space between the children and the fitted frame. Default 20. |
| `style?` | `GroupFrameStyle` |  |  |
| `labelPlacement?` | `GroupLabelPlacement` |  | Default '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**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `inPort?` | `string` |  | The new node's port the upstream half enters. Default: its first `input` port, else its left port. |
| `outPort?` | `string` |  | The new node's port the downstream half leaves from. Default: its first `output` port, else its right port. |
| `gap?` | `number` |  | Free 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**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodeId` | `string` |  |  |
| `upstreamLinkId` | `string` |  | A → N |
| `downstreamLinkId` | `string` |  | N → B |
| `moved` | `string[]` |  | 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**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `linkId` | `string` |  |  |
| `clientPoint` | `{ x: number; y: number }` |  |  |

### `LoadTextHooks`

Hooks a canvas binding gives `loadTextInto` around the reconcile.

```ts
interface LoadTextHooks
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `beforeNodes?` | `() => unknown` |  | Called just before the imported nodes are reconciled; its result goes to `afterNodes`. |
| `afterNodes?` | `(before: unknown) => void` |  | Called right after the nodes (and before the edges) are reconciled. |
| `warnEdge?` | `(warning: EdgeWarning) => void` |  | Receives 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**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | `string` |  |  |
| `fontFamily?` | `string` |  | A CSS font stack, or `'mono'` for a monospace one. |
| `fontSize?` | `number` |  | px. Default: 0.85 of the label's size. |
| `color?` | `string` |  | Default: the theme's secondary text colour. |
| `fontWeight?` | `string \| number` |  |  |

### `NodeTemplateContext`

```ts
interface NodeTemplateContext
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `node` | `NodeModel` |  |  |
| `zoom` | `number` |  | The camera zoom now. |
| `compact` | `boolean` |  | True below `compactBelow`: draw the short form. |

### `NodeTemplateDef`

```ts
interface NodeTemplateDef
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `NodeTemplateFn` |  |  |
| `compactBelow?` | `number` |  | Override 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**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `html?` | `string \| Node` |  | The 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**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `offset?` | `Point` |  |  |
| `selectPasted?` | `boolean` |  |  |

### `PlaceNodesOptions`

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

```ts
interface PlaceNodesOptions extends FlowPlaceOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `after?` | `string` |  | Place after this node (else after the first step that links into each new node). |

### `PortAddRequest`

```ts
interface PortAddRequest
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodeId` | `string` |  |  |
| `portId` | `string` |  |  |
| `clientPoint` | `{ x: number; y: number }` |  |  |

### `RenderSchedulerStats`

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

```ts
interface RenderSchedulerStats
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `scheduled` | `number` |  | `schedule()` calls. |
| `painted` | `number` |  | Frames actually painted (`onFrame` ran). |
| `skipped` | `number` |  | Queued frames dropped by `shouldSkip()`. |
| `coalesced` | `number` |  | `schedule()` calls that folded into an already-queued frame. |
| `lastFrameMs` | `number` |  | Duration (ms) of the most recent paint. |

### `RunOverlay`

```ts
interface RunOverlay
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `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).
