# Functions

Import these from `@grafloria/renderer`.

### `applyEdges`

```ts
function applyEdges(
  diagram: DiagramModel,
  specs: Array<EdgeSpec | LinkModel>,
  warn?: (warning: EdgeWarning) => void
): boolean
```

### `applyEdgeSpec`

Apply the mutable parts of an edge spec onto an existing link.

```ts
function applyEdgeSpec(link: LinkModel, spec: EdgeSpec): void
```

### `applyGroups`

Reconcile the diagram's groups against `specs` — add, update, remove — the
way {@link applyNodes} does for nodes. A live `GroupModel` passes through (a
Mermaid subgraph arrives that way). Removing a group never removes its boxes.

```ts
function applyGroups(diagram: DiagramModel, specs: Array<GroupSpec | GroupModel>): boolean
```

**Returns** whether anything changed.

### `applyNodes`

Reconcile the diagram's nodes against `specs`: add what is new, update what
moved, remove what disappeared. Live `NodeModel`s pass through untouched, so a
host can mix "give me the data" with "here is my own model".

```ts
function applyNodes(diagram: DiagramModel, specs: Array<NodeSpec | NodeModel>): boolean
```

**Returns** whether anything changed (i.e. whether a repaint is warranted).

### `applyNodeSpec`

Apply the mutable parts of a spec onto an existing node (the update path).

```ts
function applyNodeSpec(node: NodeModel, spec: NodeSpec): void
```

### `buildEdge`

Build a fresh `LinkModel` from a spec. Returns null when an endpoint is unresolvable.

```ts
function buildEdge(
  diagram: DiagramModel,
  spec: EdgeSpec,
  index: number,
  warn?: (warning: EdgeWarning) => void
): LinkModel | null
```

### `buildNode`

Build a fresh `NodeModel` from a spec, with deterministic ports.

```ts
function buildNode(spec: NodeSpec, index: number): NodeModel
```

### `buildPort`

Spec → `PortModel`, carrying the WHOLE port vocabulary through.

The gating spec is flattened onto the model's individual fields because that
is the shape `resolvePortConfig()` reads; `PortSpec.gating` is only the
ergonomic grouping of them.

A port with no explicit `side` and no `group` still lands on `right` (the
`PortModel` default) — but a port that names a group and no side is built
WITHOUT `side`, so `explicitSide` stays false and the group's side is
inherited, which is the entire reason that flag exists.

```ts
function buildPort(nodeId: string, spec: PortSpec, index: number): PortModel
```

### `contentBounds`

World bounding box of what the canvas draws — every visible node, every routed
link waypoint, every group frame with its caption — or null when there is
nothing to fit.

```ts
function contentBounds(model: DiagramModel): Rectangle | null
```

### `createDiagram`

```ts
function createDiagram(
  container: HTMLElement,
  options: CreateDiagramOptions = {}
): DiagramInstance
```

### `defaultPortId`

The deterministic id of a node's default port on `side`.

```ts
function defaultPortId(nodeId: string, side: (typeof PORT_SIDES)[number]): string
```

### `edgeSpecId`

Stable id for the nth edge of a spec list.

```ts
function edgeSpecId(spec: EdgeSpec, index: number): string
```

### `htmlLayerStyle`

The HTML layer's style for a given camera transform (see ViewportController).

```ts
function htmlLayerStyle(transform: string): string
```

### `isGroupModel`

True for a live `GroupModel`.

```ts
function isGroupModel(value: unknown): value is GroupModel
```

### `isLinkModel`

True for a live `LinkModel`.

```ts
function isLinkModel(value: unknown): value is LinkModel
```

### `isNodeModel`

True for a live `NodeModel` (vs a plain spec object).

```ts
function isNodeModel(value: unknown): value is NodeModel
```

### `keyActionOf`

Which built-in action a key would trigger — the same ladder `onKeyDown` climbs,
named for `beforeKey`. Null for a key the binder ignores.

```ts
function keyActionOf(event: KeyboardEvent): KeyAction | null
```

### `loadTextInto`

Parse Mermaid-compatible text (sidecar-aware) and reconcile it INTO a live model.

This is the one load path every canvas uses — `createDiagram().loadText` and the
framework canvases (Angular's `<grafloria-diagram-canvas>`) — so a fix here reaches
them all. It:
 - REFUSES text it cannot read before anything is applied (empty text, an
   unsupported diagram type, any parse error), leaving the model exactly as it was;
 - hands the reconcilers the imported MODELS (ports, styles and metadata survive);
 - reconciles groups and whiteboard ink, which ride in neither nodes nor edges;
 - adopts the diagram type and grammar metadata, so `exportText` writes the
   grammar the text came in (an erDiagram exports as an erDiagram).

It does not schedule a repaint — the caller does.

```ts
function loadTextInto(
  model: DiagramModel,
  text: string,
  options?: ImportTextOptions,
  hooks: LoadTextHooks = {}
): ImportTextResult
```

### `nodeHostStyle`

The style of one custom node's host element inside the HTML layer.

```ts
function nodeHostStyle(
  x: number,
  y: number,
  width: number,
  height: number
): string
```

### `nodeSpecId`

Stable id for the nth node of a spec list.

```ts
function nodeSpecId(spec: NodeSpec, index: number): string
```

### `registerTextKit`

Register the look for a diagram type loaded from text (`diagramType` metadata of
the imported model, e.g. `'erDiagram'`, `'classDiagram'`). The last registration
for a type wins. `@grafloria/element` registers its ER and UML kits on import.

```ts
function registerTextKit(diagramType: string, kit: TextKit): void
```

### `resolvePortId`

Resolve an edge endpoint to a PORT id. Accepts (in order): an explicit port id, a side name, or the node's default
port for `fallbackSide`. Returns undefined when the node does not exist.

```ts
function resolvePortId(
  diagram: DiagramModel,
  nodeOrPortId: string,
  handle: string | undefined,
  fallbackSide: (typeof PORT_SIDES)[number]
): string | undefined
```

### `textKitFor`

The kit registered for a diagram type, if any.

```ts
function textKitFor(diagramType: unknown): TextKit | undefined
```

### `toEdgeSpec`

Model → spec for a link. See {@link toNodeSpec} — no `selected` either, for the same reason.

```ts
function toEdgeSpec(link: LinkModel): EdgeSpec
```

### `toNodeSpec`

Model → spec: the projection a host needs to write model changes BACK into its
own state (a React `useState`, a Vue `ref`, a web-component property). Without
it a wrapper would have to reach into engine models, which is exactly the
coupling these specs exist to avoid.

It carries no `selected`. Selection is viewer state that changes on every
click, and `nodes:change` — when hosts store this projection — fires for the
document (a node added, removed, dropped), not for a click. A projected
`selected` therefore went stale the moment the user clicked elsewhere, and the
host's next write (a rename) selected the node again. Absent, writing the
projection back never touches the selection. A host that wants to DRIVE the
selection still sets `selected` in its own specs (`setNodes` applies it) and
reads it from `selection:change`.

```ts
function toNodeSpec(node: NodeModel): NodeSpec
```
