API Reference

Complete reference for kaykay components, types, and configuration.

Components

Canvas

The main component that renders the flow diagram.

<Canvas
  nodes={nodes}
  edges={edges}
  nodeTypes={nodeTypes}
  callbacks={callbacks}
  config={config}
>
  {#snippet background()}
    <!-- Custom background -->
  {/snippet}
  {#snippet controls()}
    <Controls />
  {/snippet}
  {#snippet children()}
    <Minimap />
  {/snippet}
</Canvas>

Prop	Type	Description
`nodes`	`FlowNode[]`	Array of node definitions
`edges`	`FlowEdge[]`	Array of edge definitions
`nodeTypes`	`NodeTypes`	Map of node type names to components
`callbacks`	`FlowCallbacks`	Event callback handlers
`config`	`FlowConfig`	Optional configuration
`class`	`string?`	Additional CSS class
`background`	`Snippet?`	Custom background snippet
`controls`	`Snippet?`	Controls snippet (e.g., zoom controls)
`children`	`Snippet?`	Additional children (e.g., Minimap)

Handle

Connection point on a node for edges.

<Handle
  id="input-1"
  type="input"
  port="data"
  position="left"
  label="Input"
/>

Prop	Type	Description
`id`	`string`	Unique ID within the node
`type`	`'input' \| 'output'`	Handle direction
`port`	`string`	Port type for connection matching
`position`	`'left' \| 'right' \| 'top' \| 'bottom'`	Position on the node
`label`	`string?`	Optional label text
`accept`	`string[]?`	Additional port types to accept

HandleGroup

Groups multiple handles on one side of a node.

<HandleGroup position="left">
  <Handle id="in-1" type="input" port="data" />
  <Handle id="in-2" type="input" port="data" />
</HandleGroup>

GroupNode

Built-in component for creating visual node groups.

import { GroupNode } from 'kaykay';

const nodeTypes = {
  group: GroupNode,
  // ... other types
};

Minimap

Optional minimap for navigation. Click or drag to pan viewport.

<Canvas {nodes} {edges} {nodeTypes}>
  {#snippet children()}
    <Minimap width={200} height={150} />
  {/snippet}
</Canvas>

Prop	Type	Description
`width`	`number`	Width in pixels (default: 200)
`height`	`number`	Height in pixels (default: 150)
`backgroundColor`	`string?`	Background color override
`nodeColor`	`string?`	Node rectangle color override
`viewportColor`	`string?`	Viewport indicator color override
`class`	`string?`	Additional CSS class

Controls

Zoom controls with optional fit view and lock toggle.

<Canvas {nodes} {edges} {nodeTypes}>
  {#snippet controls()}
    <Controls position="bottom-left" />
  {/snippet}
</Canvas>

Prop	Type	Description
`position`	`'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'`	Position on canvas (default: 'bottom-left')
`showZoomLevel`	`boolean`	Show zoom percentage (default: true)
`showFitView`	`boolean`	Show fit view button (default: true)
`showLock`	`boolean`	Show lock toggle button (default: true)
`class`	`string?`	Additional CSS class

Types

FlowNode

interface FlowNode<T = Record<string, unknown>> {
  id: string;
  type: string;
  position: { x: number; y: number };
  data: T;
  width?: number;
  height?: number;
  selected?: boolean;
  parent_id?: string;  // For grouping
  z_index?: number;
}

FlowEdge

interface FlowEdge {
  id: string;
  source: string;
  source_handle: string;
  target: string;
  target_handle: string;
  type?: 'bezier' | 'straight' | 'step';
  style?: 'solid' | 'dashed' | 'dotted';
  color?: string;
  animated?: boolean;
  label?: string;
  waypoints?: Position[];
}

NodeProps

interface NodeProps<T = Record<string, unknown>> {
  id: string;
  data: T;
  selected: boolean;
}

FlowCallbacks

interface FlowCallbacks {
  on_node_click?: (node_id: string) => void;
  on_node_drag_start?: (node_id: string) => void;
  on_node_drag_end?: (node_id: string, position: Position) => void;
  on_connect?: (edge: FlowEdge) => void;
  on_edge_click?: (edge_id: string) => void;
  on_delete?: (node_ids: string[], edge_ids: string[]) => void;
  on_viewport_change?: (viewport: Viewport) => void;
}

FlowConfig

interface FlowConfig {
  min_zoom?: number;      // Default: 0.1
  max_zoom?: number;      // Default: 4
  snap_to_grid?: boolean; // Default: false
  grid_size?: number;     // Default: 20
  allow_delete?: boolean; // Default: true
  default_edge_type?: EdgeType;
  locked?: boolean;       // Prevent modifications
}

Flow State Methods

Access the flow state via canvas.getFlow():

Node Operations

flow.addNode(node: FlowNode): void
flow.removeNode(nodeId: string): void
flow.getNode(nodeId: string): NodeState | undefined
flow.updateNodePosition(nodeId: string, position: Position): void
flow.updateNodeData(nodeId: string, data: Partial<T>): void
flow.updateNodeDimensions(nodeId: string, width: number, height: number): void
flow.getChildNodes(parentId: string): NodeState[]
flow.getAbsolutePosition(nodeId: string): Position
flow.setNodeParent(nodeId: string, parentId: string | undefined): void

Edge Operations

flow.addEdge(edge: FlowEdge): boolean
flow.removeEdge(edgeId: string): void
flow.getEdge(edgeId: string): FlowEdge | undefined
flow.updateEdge(edgeId: string, updates: Partial<FlowEdge>): void

// Waypoints for custom edge routing
flow.addEdgeWaypoint(edgeId: string, position: Position, index?: number): void
flow.updateEdgeWaypoint(edgeId: string, waypointIndex: number, position: Position): void
flow.removeEdgeWaypoint(edgeId: string, waypointIndex: number): void
flow.clearEdgeWaypoints(edgeId: string): void

Selection

flow.selectNode(nodeId: string, additive?: boolean): void
flow.selectEdge(edgeId: string, additive?: boolean): void
flow.clearSelection(): void
flow.deleteSelected(): void

// Read selected IDs
flow.selected_node_ids: Set<string>
flow.selected_edge_ids: Set<string>

Viewport

flow.setViewport(viewport: Viewport): void
flow.pan(dx: number, dy: number): void
flow.zoom(delta: number, center: Position): void
flow.zoomIn(step?: number): void
flow.zoomOut(step?: number): void
flow.resetZoom(): void
flow.setZoom(zoom: number): void
flow.fitView(padding?: number): void

// Read viewport state
flow.viewport: Viewport  // { x, y, zoom }

Lock State

flow.locked: boolean        // Read lock state
flow.setLocked(locked: boolean): void
flow.toggleLocked(): void

Handle Operations

flow.getHandle(nodeId: string, handleId: string): HandleState | undefined
flow.getHandlePosition(nodeId: string, handleId: string): Position | undefined

Import/Export

const json: Flow = flow.toJSON()
flow.fromJSON(json: Flow): void