Ports

Import these from @grafloria/engine.

On their own pages

• PortLayoutArgs

Functions

arePortDataTypesCompatible

Free-function facade over the singleton — what PortModel/validators import.

ts
Copy
function arePortDataTypesCompatible(from: string | undefined, to: string | undefined): boolean

buildDynamicPortCommands

The plan, as undoable commands. Empty array when nothing is due — so a caller can drive this on every link change without polluting the undo stack.

ts
Copy
function buildDynamicPortCommands(node: NodeModel, links?: LinkModel[]): Command[]

buildDynamicPortCommandsForDiagram

Every node in the diagram that owes the allocator work.

ts
Copy
function buildDynamicPortCommandsForDiagram(diagram: DiagramModel): Command[]

canConnectPortsWithRules

Boolean facade for call sites that don't care WHY.

ts
Copy
function canConnectPortsWithRules(
  source: PortModel,
  target: PortModel,
  context: ConnectionRuleContext = {}
): boolean

ensureSideAnchorPort

The hidden port a side-anchor handle names — created once per node and handle, then re-used (a re-applied spec must not grow a second one). Placed as a FRACTION of the node box, so it stays on its side when the node resizes. Returns null when handle is not a side anchor.

ts
Copy
function ensureSideAnchorPort(node: NodeModel, handle: string): string | null

evaluatePortConnection

May a link be created FROM source TO target? Directional — swapping the arguments is a different question and may well get a different answer.

ts
Copy
function evaluatePortConnection(
  source: PortModel,
  target: PortModel,
  context: ConnectionRuleContext = {}
): ConnectionVerdict

findPortGroup

Find the group a port belongs to: the node's own definitions first (most specific), then the registry for the node's type.

ts
Copy
function findPortGroup(
  port: PortModel,
  node: NodeModel | undefined
): PortGroupDefinition | undefined

getNodePortGroups

Per-node group definitions, stored in node metadata so they serialize with the diagram (a node can carry a one-off group without registering a node type).

ts
Copy
function getNodePortGroups(node: NodeModel | undefined): Record<string, PortGroupDefinition>

isSideAnchorPort

A port a side-anchor handle created (<node>__right@36).

ts
Copy
function isSideAnchorPort(portId: string | undefined): boolean

parseSideAnchor

'right@36' → { side: 'right', at: { px: 36 } }; 'left@50%' → { at: { pct: 50 } }; anything else → null.

ts
Copy
function parseSideAnchor(handle: string): { side: AnchorSide; at: { px?: number; pct?: number } } | null

planDynamicPorts

What must change so every dynamic group on node offers exactly spare free ports? Idempotent: run it on a settled node and it returns an empty plan.

A port is "free" when it carries no links. Only ports the allocator itself spawned (dynamic: true) are ever REMOVED — an authored port the user simply hasn't wired yet is not surplus, it is the design.

ts
Copy
function planDynamicPorts(node: NodeModel, links?: LinkModel[]): DynamicPortPlan

portTypeColor

Free-function facade over the singleton — what the renderer imports.

ts
Copy
function portTypeColor(name: string | undefined): string | undefined

resolvePortConfig

Fold a port's group into its own fields. THE resolution seam — the renderer, the layout engine and the connection validator all read the result of this function and never the raw port fields, so group inheritance can never silently apply in one place and not another.

ts
Copy
function resolvePortConfig(port: PortModel, node?: NodeModel): ResolvedPortConfig

setNodePortGroups

ts
Copy
function setNodePortGroups(node: NodeModel, groups: Record<string, PortGroupDefinition>): void

sideAnchorPortId

The id of the port a side-anchor handle names on nodeId.

ts
Copy
function sideAnchorPortId(nodeId: string, handle: string): string

Classes

PortGroupRegistry

Groups registered per node TYPE. A node type declares its port groups once ("the and-gate type has an in group and an out group"), and every node of that type inherits them.

ts
Copy
class PortGroupRegistry

Methods

• register(nodeType: string, group: PortGroupDefinition): void
• registerAll(nodeType: string, groups: PortGroupDefinition[]): void
• get(nodeType: string, groupId: string): PortGroupDefinition | undefined
• getAll(nodeType: string): PortGroupDefinition[]
• unregister(nodeType: string, groupId?: string): void
• clear(): void

PortTypeRegistry

ts
Copy
class PortTypeRegistry

Methods

• register(definition: PortDataTypeDefinition): void
• registerAll(definitions: PortDataTypeDefinition[]): void
• get(name: string): PortDataTypeDefinition | undefined
• has(name: string): boolean
• unregister(name: string): void
• clear(): void
• isCompatible(from: string | undefined, to: string | undefined): boolean — May a link carry from into to?

Compatibility is DIRECTIONAL on purpose: int → float is a widening that a host may well allow while float → int is a lossy one it may not.

• colorFor(name: string | undefined): string | undefined — The glyph colour for a data type, if one was registered.

Constants

ANY_PORT_TYPE

The wildcard: a port typed * (or declared compatible with *) fits anything.

ts
Copy
const ANY_PORT_TYPE: "*"

DEFAULT_PORT_GATING

ts
Copy
const DEFAULT_PORT_GATING: ResolvedPortGating

DEFAULT_PORT_LABEL_OFFSET

ts
Copy
const DEFAULT_PORT_LABEL_OFFSET: 6

DEFAULT_PORT_SPREAD_SPACING

ts
Copy
const DEFAULT_PORT_SPREAD_SPACING: 10

PORT_GROUPS_METADATA_KEY

Node metadata key holding per-node group definitions.

ts
Copy
const PORT_GROUPS_METADATA_KEY: "portGroups"

portGroupRegistry

The process-wide registry. Hosts register node-type groups at bootstrap.

ts
Copy
const portGroupRegistry: PortGroupRegistry

portTypeRegistry

The process-wide registry. Hosts register their data types at bootstrap.

ts
Copy
const portTypeRegistry: PortTypeRegistry

Interfaces

ConnectionRuleContext

ts
Copy
interface ConnectionRuleContext

Properties

ConnectionVerdict

ts
Copy
interface ConnectionVerdict

Properties

DynamicPortPlan

ts
Copy
interface DynamicPortPlan

Properties

DynamicPortSpec

Dynamic auto-ports: keep a group topped up with free ports so the user always has somewhere to drop the next link — the node-editor pattern (Blender / Unreal / n8n).

ts
Copy
interface DynamicPortSpec

Properties

PortDataTypeDefinition

ts
Copy
interface PortDataTypeDefinition

Properties

PortGatingSpec

Directional connectability.

Every field is optional and every default reproduces the old behaviour: isConnectableStart/End = true, from/toMaxLinks = null (unlimited), allowSelfLink = false, allowDuplicateLinks = true.

ts
Copy
interface PortGatingSpec

Properties

PortGroupDefinition

A named, reusable bundle of port config on a node type. Ports name their group and override ONLY what differs — replacing the old top/right/bottom/left-only PortsConfig, in which "eight typed inputs down the left edge, each with a label" could not be said at all.

ts
Copy
interface PortGroupDefinition

Properties

PortLabelSpec

ts
Copy
interface PortLabelSpec

Properties

PortLayoutSpec

ts
Copy
interface PortLayoutSpec

Properties

PortShapeSpec

ts
Copy
interface PortShapeSpec

Properties

PortSpot

ts
Copy
interface PortSpot

Properties

PortSpreadSpec

Spread N links landing on ONE port along that port's edge instead of piling them all on the centre point.

(Byte-stability.)

ts
Copy
interface PortSpreadSpec

Properties

ResolvedPortConfig

ts
Copy
interface ResolvedPortConfig

Properties

ResolvedPortGating

Gating with every question ANSWERED — no undefined anywhere, because a validator that has to ask "was this unset or set to false?" is a validator with a bug waiting in it. null is the explicit "unlimited" for the caps.

ts
Copy
interface ResolvedPortGating

Properties

Types

AnchorSide

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

ts
Copy
type AnchorSide = 'top' | 'right' | 'bottom' | 'left';

ConnectionRejectionReason

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

ts
Copy
type ConnectionRejectionReason =
  | 'self-port'
  | 'self-link'
  | 'not-connectable-start'
  | 'not-connectable-end'
  | 'node-not-connectable'
  | 'direction'
  | 'data-type'
  | 'allowed-types'
  | 'max-connections'
  | 'from-max-links'
  | 'to-max-links'
  | 'duplicate-link'
  | 'connection-group'
  | 'custom';

PortEdge

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

ts
Copy
type PortEdge = 'left' | 'right' | 'top' | 'bottom';

PortGlyphShape

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

The port's rendered marker.

path renders a caller-supplied SVG path (PortShapeSpec.path), authored in a box of size centred on the port's anchor point.

ts
Copy
type PortGlyphShape = 'circle' | 'square' | 'diamond' | 'triangle' | 'path';

PortLabelLayout

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

Where a port's label sits relative to the glyph.

• inside — pulled INTO the node body, opposite the port's outward normal.
• outside — pushed AWAY from the node, along the outward normal (default).
• orthogonal — offset perpendicular to the outward normal (reads along the edge, so a column of side ports doesn't stack labels on the same line).
• radial — offset along the ray from the node's centre through the port; the layout that actually works on ellipse / circle nodes, where "outward normal" and "away from centre" are the same thing only at the four cardinal points.

ts
Copy
type PortLabelLayout = 'inside' | 'outside' | 'orthogonal' | 'radial';

PortLayoutStrategyName

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

Named port-layout strategies. Every other strategy is an explicit opt-in that overrides it.

ts
Copy
type PortLayoutStrategyName =
  | 'shape'
  | 'absolute'
  | 'line'
  | 'sideLinear'
  | 'ellipse'
  | 'ellipseSpread';

PortSpotName

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

A named point on the port's glyph box. default means "whatever the port's side implies" — the outward-facing edge midpoint, which is the historical attachment behaviour (the glyph CENTRE, since the legacy glyph had no box).

ts
Copy
type PortSpotName =
  | 'default'
  | 'center'
  | 'top'
  | 'right'
  | 'bottom'
  | 'left'
  | 'topLeft'
  | 'topRight'
  | 'bottomLeft'
  | 'bottomRight';

PortVisibilityMode

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

ts
Copy
type PortVisibilityMode = 'always' | 'on-hover' | 'never' | 'hidden';