Skip to content
D
Documentation

functions

reference
3 min readUpdated

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 NodeModels 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

Was this page helpful?