@flikk/ui 1.0.0-beta.3 → 1.0.0-beta.31

package/dist/components/canvas/NodeCanvas.types.d.ts

@@ -0,0 +1,191 @@
+import type React from "react";
+/** A point in flow coordinates (the unbounded node space). */
+export interface XYPosition {
+    x: number;
+    y: number;
+}
+/** A node in the graph. `data` is an arbitrary user payload. */
+export interface NodeCanvasNode<TData = unknown> {
+    id: string;
+    /** Key into the `nodeTypes` registry. */
+    type: string;
+    /** Position in flow coordinates. */
+    position: XYPosition;
+    data: TData;
+    selected?: boolean;
+    /** Defaults to `true`. */
+    draggable?: boolean;
+}
+/** Edge routing style. */
+export type EdgeType = "bezier" | "step" | "smoothstep";
+/** An edge connecting two node handles. */
+export interface NodeCanvasEdge {
+    id: string;
+    source: string;
+    sourceHandle?: string;
+    target: string;
+    targetHandle?: string;
+    selected?: boolean;
+    /** Routing style. Defaults to `bezier`. */
+    type?: EdgeType;
+    /**
+     * Stroke color (any CSS color, e.g. `var(--color-primary-300)`). Selection
+     * still strokes `--color-primary`. Defaults to `--color-border`.
+     */
+    color?: string;
+}
+/** Emitted by `onConnect` before the consumer materializes an edge. */
+export interface NodeCanvasConnection {
+    source: string;
+    sourceHandle?: string;
+    target: string;
+    targetHandle?: string;
+}
+/** The viewport transform mapping flow space → screen space. */
+export interface NodeCanvasViewport {
+    x: number;
+    y: number;
+    zoom: number;
+}
+/** Props passed to a custom node component registered in `nodeTypes`. */
+export interface NodeProps<TData = unknown> {
+    id: string;
+    type: string;
+    data: TData;
+    selected: boolean;
+    position: XYPosition;
+    dragging: boolean;
+}
+export type HandleType = "source" | "target";
+export type HandlePosition = "top" | "right" | "bottom" | "left";
+/** Props for a `Handle` (port) declared inside a custom node. */
+export interface HandleProps {
+    type: HandleType;
+    id?: string;
+    position?: HandlePosition;
+    isConnectable?: boolean;
+    className?: string;
+    style?: React.CSSProperties;
+    /**
+     * Custom port visual (e.g. an icon badge). When present, the default dot
+     * styling is dropped — `className` owns size/shape/color entirely; the
+     * engine keeps placement, measurement, and connection behavior.
+     */
+    children?: React.ReactNode;
+}
+/** Props for a custom edge component (used from issue 3 onward). */
+export interface EdgeProps {
+    id: string;
+    source: string;
+    target: string;
+    selected?: boolean;
+}
+/** A registry mapping `node.type` → the component that renders it. */
+export type NodeCanvasNodeTypes = Record<string, React.ComponentType<NodeProps<never>>>;
+export type NodeChange = {
+    type: "position";
+    id: string;
+    position: XYPosition;
+    dragging?: boolean;
+} | {
+    type: "select";
+    id: string;
+    selected: boolean;
+} | {
+    type: "remove";
+    id: string;
+} | {
+    type: "add";
+    item: NodeCanvasNode;
+} | {
+    type: "dimensions";
+    id: string;
+    dimensions: {
+        width: number;
+        height: number;
+    };
+};
+export type EdgeChange = {
+    type: "select";
+    id: string;
+    selected: boolean;
+} | {
+    type: "remove";
+    id: string;
+} | {
+    type: "add";
+    item: NodeCanvasEdge;
+};
+/** Theme override slots for the canvas surface. */
+export interface NodeCanvasThemeOverrides {
+    /** The clipping pane that captures pan/zoom gestures. */
+    pane?: string;
+    /** The transformed "world" layer that holds nodes + edges. */
+    world?: string;
+}
+/**
+ * Setter accepting either a next viewport or an updater function.
+ * Zoom is always clamped to `[minZoom, maxZoom]`.
+ */
+export type SetViewport = (next: NodeCanvasViewport | ((prev: NodeCanvasViewport) => NodeCanvasViewport)) => void;
+export interface NodeCanvasProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onSelect"> {
+    /** Controlled nodes. */
+    nodes?: NodeCanvasNode[];
+    /** Controlled edges. */
+    edges?: NodeCanvasEdge[];
+    /** Controlled viewport. */
+    viewport?: NodeCanvasViewport;
+    /** Initial nodes when uncontrolled. */
+    defaultNodes?: NodeCanvasNode[];
+    /** Initial edges when uncontrolled. */
+    defaultEdges?: NodeCanvasEdge[];
+    /** Initial viewport when uncontrolled. Defaults to `{ x: 0, y: 0, zoom: 1 }`. */
+    defaultViewport?: NodeCanvasViewport;
+    /**
+     * Maps `node.type` → the component that renders it. Keep this map referentially
+     * stable (module scope or memoized) — an inline object defeats the per-node
+     * memoization and re-renders every node on every canvas update.
+     */
+    nodeTypes: NodeCanvasNodeTypes;
+    onNodesChange?: (changes: NodeChange[]) => void;
+    onEdgesChange?: (changes: EdgeChange[]) => void;
+    onConnect?: (connection: NodeCanvasConnection) => void;
+    onViewportChange?: (viewport: NodeCanvasViewport) => void;
+    onSelectionChange?: (selection: {
+        nodes: string[];
+        edges: string[];
+    }) => void;
+    onNodeClick?: (event: React.MouseEvent, node: NodeCanvasNode) => void;
+    onBeforeDelete?: (selection: {
+        nodes: NodeCanvasNode[];
+        edges: NodeCanvasEdge[];
+    }) => boolean;
+    /** Reject a candidate connection (e.g. enforce source→target rules). */
+    isValidConnection?: (connection: NodeCanvasConnection) => boolean;
+    /** Minimum zoom. Defaults to `0.25`. */
+    minZoom?: number;
+    /** Maximum zoom. Defaults to `2`. */
+    maxZoom?: number;
+    /** Fit all nodes into view on mount. Defaults to `false`. */
+    fitViewOnInit?: boolean;
+    /** Scroll the canvas instead of zooming. Defaults to `false`. */
+    panOnScroll?: boolean;
+    /** Zoom on wheel / pinch. Defaults to `true`. */
+    zoomOnScroll?: boolean;
+    /** Require a modifier key for wheel-zoom. Defaults to `null` (no key). */
+    zoomActivationKey?: "ctrl" | "meta" | "shift" | null;
+    /** Pan by dragging the empty canvas. Defaults to `true`. */
+    panOnDrag?: boolean;
+    /** Snap nodes to a grid while dragging. Defaults to `false`. */
+    snapToGrid?: boolean;
+    /** Grid step `[x, y]` in flow units when `snapToGrid`. Defaults to `[16, 16]`. */
+    snapGrid?: [number, number];
+    /**
+     * Show omnidirectional "+" connect handles on every node (hover-revealed) so any
+     * node can connect to any node from any side. Defaults to `true`. Set `false` to
+     * use only explicitly declared `<Handle>` ports.
+     */
+    autoConnect?: boolean;
+    className?: string;
+    theme?: NodeCanvasThemeOverrides;
+}

package/dist/components/canvas/NodeControls.d.ts

@@ -0,0 +1,25 @@
+declare const POSITIONS: {
+    readonly "bottom-left": "bottom-4 left-4";
+    readonly "bottom-right": "bottom-4 right-4";
+    readonly "top-left": "top-4 left-4";
+    readonly "top-right": "top-4 right-4";
+};
+export interface NodeControlsProps {
+    position?: keyof typeof POSITIONS;
+    showZoom?: boolean;
+    showFitView?: boolean;
+    showLock?: boolean;
+    /** Zoom step per click. Defaults to `1.2`. */
+    zoomStep?: number;
+    className?: string;
+}
+/**
+ * Opt-in control cluster: zoom in/out (anchored to canvas center), fit-view, and a
+ * lock toggle (disables pan / node drag / connections). Pane-level chrome — render
+ * as a child of `NodeCanvas`.
+ */
+export declare function NodeControls({ position, showZoom, showFitView, showLock, zoomStep, className, }: NodeControlsProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace NodeControls {
+    var displayName: string;
+}
+export {};

package/dist/components/canvas/NodeControls.js

@@ -0,0 +1,41 @@
+"use client";
+import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
+import { Plus, Minus, ArrowsOutSimple, Lock, LockOpen } from '@phosphor-icons/react';
+import { cn } from '../../utils/cn.js';
+import { Button } from '../core/Button/Button.js';
+import 'react';
+import { useCanvasApi } from './context/CanvasContext.js';
+import { clamp } from './utils.js';
+
+const POSITIONS = {
+    "bottom-left": "bottom-4 left-4",
+    "bottom-right": "bottom-4 right-4",
+    "top-left": "top-4 left-4",
+    "top-right": "top-4 right-4",
+};
+/**
+ * Opt-in control cluster: zoom in/out (anchored to canvas center), fit-view, and a
+ * lock toggle (disables pan / node drag / connections). Pane-level chrome — render
+ * as a child of `NodeCanvas`.
+ */
+function NodeControls({ position = "bottom-right", showZoom = true, showFitView = true, showLock = true, zoomStep = 1.2, className, }) {
+    const { setViewport, fitView, minZoom, maxZoom, paneRef, locked, setLocked } = useCanvasApi();
+    const zoomBy = (factor) => {
+        const pane = paneRef.current;
+        if (!pane)
+            return;
+        const r = pane.getBoundingClientRect();
+        const sx = r.width / 2;
+        const sy = r.height / 2;
+        setViewport((v) => {
+            const zoom = clamp(v.zoom * factor, minZoom, maxZoom);
+            const k = zoom / v.zoom;
+            return { zoom, x: sx - (sx - v.x) * k, y: sy - (sy - v.y) * k };
+        });
+    };
+    const ctrlBtn = "size-8 rounded-none";
+    return (jsxs("div", { "data-flikkui-controls": "", className: cn("absolute z-20 flex flex-col overflow-hidden rounded-lg border border-[var(--color-border)] divide-y divide-[var(--color-border)] bg-[var(--color-surface-overlay)]/60 backdrop-blur-lg shadow-real-lg", POSITIONS[position], className), children: [showZoom && (jsxs(Fragment, { children: [jsx(Button, { variant: "ghost", color: "mono", size: "sm", iconOnly: true, className: ctrlBtn, onClick: () => zoomBy(zoomStep), "aria-label": "Zoom in", children: jsx(Plus, { className: "size-4" }) }), jsx(Button, { variant: "ghost", color: "mono", size: "sm", iconOnly: true, className: ctrlBtn, onClick: () => zoomBy(1 / zoomStep), "aria-label": "Zoom out", children: jsx(Minus, { className: "size-4" }) })] })), showFitView && (jsx(Button, { variant: "ghost", color: "mono", size: "sm", iconOnly: true, className: ctrlBtn, onClick: () => fitView(), "aria-label": "Fit view", children: jsx(ArrowsOutSimple, { className: "size-4" }) })), showLock && (jsx(Button, { variant: locked ? "soft" : "ghost", color: locked ? "primary" : "mono", size: "sm", iconOnly: true, className: ctrlBtn, onClick: () => setLocked(!locked), "aria-label": locked ? "Unlock canvas" : "Lock canvas", "aria-pressed": locked, children: locked ? jsx(Lock, { className: "size-4" }) : jsx(LockOpen, { className: "size-4" }) }))] }));
+}
+NodeControls.displayName = "NodeControls";
+
+export { NodeControls };

package/dist/components/canvas/NodeRenderer.d.ts

@@ -0,0 +1,22 @@
+import React from "react";
+import type { NodeCanvasNode, NodeCanvasNodeTypes, NodeChange } from "./NodeCanvas.types";
+interface NodeRendererProps {
+    nodes: NodeCanvasNode[];
+    nodeTypes: NodeCanvasNodeTypes;
+    /** Show omnidirectional "+" connect handles on every node. */
+    autoConnect: boolean;
+    /** Emits drag `position` change-objects. */
+    onNodeChanges: (changes: NodeChange[]) => void;
+    /** Selection is owned by NodeCanvas so node/edge selection can cross-clear. */
+    onSelectNode: (id: string, additive: boolean) => void;
+    onNodeClick?: (event: React.MouseEvent, node: NodeCanvasNode) => void;
+}
+/**
+ * Renders nodes from data: maps each `node.type` to its registered component and
+ * wraps it in a positioned, focusable, draggable shell.
+ *
+ * Memoized (as is each `NodeWrapper`): viewport-only canvas renders bail here
+ * entirely, and a graph update re-renders only the nodes whose objects changed.
+ */
+export declare const NodeRenderer: React.NamedExoticComponent<NodeRendererProps>;
+export {};

package/dist/components/canvas/NodeRenderer.js

@@ -0,0 +1,126 @@
+"use client";
+import { jsx, Fragment, jsxs } from 'react/jsx-runtime';
+import React__default, { useCallback, useRef, useEffect } from 'react';
+import { Plus } from '@phosphor-icons/react';
+import { cn } from '../../utils/cn.js';
+import { NodeIdProvider } from './context/NodeIdContext.js';
+import { useCanvasApi } from './context/CanvasContext.js';
+import { useHandleRegistry, handleKey } from './context/HandleRegistry.js';
+import { useNodeDrag } from './hooks/useNodeDrag.js';
+import { useConnection } from './hooks/useConnection.js';
+
+/**
+ * Renders nodes from data: maps each `node.type` to its registered component and
+ * wraps it in a positioned, focusable, draggable shell.
+ *
+ * Memoized (as is each `NodeWrapper`): viewport-only canvas renders bail here
+ * entirely, and a graph update re-renders only the nodes whose objects changed.
+ */
+const NodeRenderer = React__default.memo(function NodeRenderer({ nodes, nodeTypes, autoConnect, onNodeChanges, onSelectNode, onNodeClick, }) {
+    return (jsx(Fragment, { children: nodes.map((node) => {
+            const NodeComponent = nodeTypes[node.type];
+            if (process.env.NODE_ENV !== "production" && !NodeComponent) {
+                console.warn(`[NodeCanvas]: no nodeTypes entry for type "${node.type}" (node "${node.id}")`);
+            }
+            if (!NodeComponent)
+                return null;
+            return (jsx(NodeWrapper, { node: node, NodeComponent: NodeComponent, autoConnect: autoConnect, emit: onNodeChanges, onSelect: onSelectNode, onNodeClick: onNodeClick }, node.id));
+        }) }));
+});
+NodeRenderer.displayName = "NodeRenderer";
+const AUTO_SIDES = ["top", "right", "bottom", "left"];
+const AUTO_SIDE_CLASSES = {
+    top: "top-0 left-1/2 -translate-x-1/2 -translate-y-1/2",
+    right: "right-0 top-1/2 translate-x-1/2 -translate-y-1/2",
+    bottom: "bottom-0 left-1/2 -translate-x-1/2 translate-y-1/2",
+    left: "left-0 top-1/2 -translate-x-1/2 -translate-y-1/2",
+};
+/**
+ * An omnidirectional connect-from-anywhere handle: a "+" on one node side, revealed
+ * on node hover, draggable to any other node. Registers its flow-coord offset like
+ * `Handle` so edges anchor to it, with `kind: 'auto'` so the connection rules allow
+ * any node → any node.
+ */
+function AutoHandle({ nodeId, position }) {
+    const ref = useRef(null);
+    const { register, unregister } = useHandleRegistry();
+    const { viewportRef, tool, locked } = useCanvasApi();
+    const handleId = `__${position}`;
+    const { onPointerDown } = useConnection({ nodeId, handleId, type: "source", kind: "auto" });
+    const disabled = tool === "pan" || locked;
+    useEffect(() => {
+        const el = ref.current;
+        if (!el)
+            return;
+        const nodeEl = el.closest("[data-flikkui-node]");
+        if (!nodeEl)
+            return;
+        const measure = () => {
+            const hr = el.getBoundingClientRect();
+            const nr = nodeEl.getBoundingClientRect();
+            const zoom = viewportRef.current.zoom || 1;
+            register(nodeId, {
+                id: handleId,
+                type: "source",
+                position,
+                kind: "auto",
+                offset: {
+                    x: (hr.left + hr.width / 2 - nr.left) / zoom,
+                    y: (hr.top + hr.height / 2 - nr.top) / zoom,
+                },
+            });
+        };
+        measure();
+        const ro = new ResizeObserver(measure);
+        ro.observe(nodeEl);
+        return () => {
+            ro.disconnect();
+            unregister(nodeId, handleKey("source", handleId));
+        };
+    }, [nodeId, handleId, position, register, unregister, viewportRef]);
+    return (jsx("button", { ref: ref, type: "button", "data-flikkui-handle": "", "data-node-id": nodeId, "data-handle-type": "source", "data-handle-id": handleId, "data-handle-kind": "auto", "aria-label": `Connect from ${position}`, className: cn("nodrag absolute z-20 grid place-items-center size-4 rounded-full", "bg-[var(--color-primary)] text-[var(--color-primary-contrast)] shadow-md ring-2 ring-[var(--color-surface)] cursor-crosshair", "opacity-0 scale-75 pointer-events-none transition-[opacity,transform,box-shadow] duration-150 ease-out", "hover:scale-110 hover:shadow-lg hover:ring-4 active:scale-95", !disabled &&
+            "group-hover:opacity-100 group-hover:scale-100 group-hover:pointer-events-auto group-focus-within:opacity-100 group-focus-within:scale-100 group-focus-within:pointer-events-auto", AUTO_SIDE_CLASSES[position]), onPointerDown: disabled ? undefined : onPointerDown, children: jsx(Plus, { className: "size-2.5" }) }));
+}
+// Memoized so unrelated graph updates (another node's data/position, selection
+// elsewhere) skip this node: `node` identity is preserved by applyNodeChanges,
+// and every callback prop is kept stable by NodeCanvas.
+const NodeWrapper = React__default.memo(function NodeWrapper({ node, NodeComponent, autoConnect, emit, onSelect, onNodeClick, }) {
+    const { tool } = useCanvasApi();
+    const getNode = useCallback(() => node, [node]);
+    const { dragging, onPointerDown, onPointerMove, onPointerUp } = useNodeDrag({
+        nodeId: node.id,
+        getNode,
+        emit,
+    });
+    const handlePointerDown = (e) => {
+        // In pan mode let the press fall through to the pane (which pans).
+        if (tool === "pan")
+            return;
+        // Select first (so dragging an unselected node grabs it), then begin drag.
+        if (e.button === 0)
+            onSelect(node.id, e.shiftKey);
+        onPointerDown(e);
+    };
+    const handleKeyDown = (e) => {
+        if (e.target !== e.currentTarget)
+            return; // ignore keys from inner controls
+        if (e.key === "Enter" || e.key === " ") {
+            e.preventDefault();
+            onSelect(node.id, e.shiftKey);
+        }
+    };
+    const selected = !!node.selected;
+    return (jsx("div", { className: cn("group absolute top-0 left-0 rounded-[var(--canvas-node-radius,0.75rem)]", "transition-[box-shadow,filter,opacity] duration-150 ease-out", "focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-primary)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--color-background)]", tool === "pan"
+            ? "cursor-grab"
+            : node.draggable !== false && "cursor-grab active:cursor-grabbing", 
+        // Selection visuals belong to the node component (BaseNode is the
+        // reference impl — border-secondary + primary whisper); the shell only
+        // marks state (data-selected) and keeps the keyboard focus-visible
+        // ring. A shell outline stacked on the card's border reads as a fat
+        // double frame.
+        dragging && "opacity-95 shadow-[0_18px_40px_rgba(0,0,0,0.16)]", (selected || dragging) && "z-10"), style: { transform: `translate(${node.position.x}px, ${node.position.y}px)` }, role: "group", "aria-roledescription": "node", "aria-label": `${node.type} node`, "data-flikkui-node": node.id, "data-selected": selected || undefined, "data-dragging": dragging || undefined, tabIndex: 0, onPointerDown: handlePointerDown, onPointerMove: onPointerMove, onPointerUp: onPointerUp, onKeyDown: handleKeyDown, onClick: onNodeClick ? (e) => onNodeClick(e, node) : undefined, children: jsxs(NodeIdProvider, { value: node.id, children: [jsx(NodeComponent, { id: node.id, type: node.type, data: node.data, selected: selected, position: node.position, dragging: dragging }), autoConnect &&
+                    AUTO_SIDES.map((side) => (jsx(AutoHandle, { nodeId: node.id, position: side }, side)))] }) }));
+});
+NodeWrapper.displayName = "NodeWrapper";
+
+export { NodeRenderer };

package/dist/components/canvas/changes.d.ts

@@ -0,0 +1,11 @@
+import type { EdgeChange, NodeCanvasEdge, NodeCanvasNode, NodeChange } from "./NodeCanvas.types";
+/**
+ * Fold a batch of {@link NodeChange}s into a nodes array, returning a new array.
+ * Consumers call this from `onNodesChange` when controlling node state.
+ *
+ * Note (issue 2): `dimensions` is accepted but not yet persisted on the node
+ * (real measured sizes are stored in issue 4); it is currently a no-op update.
+ */
+export declare function applyNodeChanges(changes: NodeChange[], nodes: NodeCanvasNode[]): NodeCanvasNode[];
+/** Fold a batch of {@link EdgeChange}s into an edges array, returning a new array. */
+export declare function applyEdgeChanges(changes: EdgeChange[], edges: NodeCanvasEdge[]): NodeCanvasEdge[];

package/dist/components/canvas/changes.js

@@ -0,0 +1,76 @@
+/**
+ * Fold a batch of {@link NodeChange}s into a nodes array, returning a new array.
+ * Consumers call this from `onNodesChange` when controlling node state.
+ *
+ * Note (issue 2): `dimensions` is accepted but not yet persisted on the node
+ * (real measured sizes are stored in issue 4); it is currently a no-op update.
+ */
+function applyNodeChanges(changes, nodes) {
+    if (changes.length === 0)
+        return nodes;
+    const byId = new Map(nodes.map((n) => [n.id, n]));
+    const removed = new Set();
+    const added = [];
+    for (const change of changes) {
+        switch (change.type) {
+            case "add":
+                added.push(change.item);
+                break;
+            case "remove":
+                removed.add(change.id);
+                break;
+            case "position": {
+                const node = byId.get(change.id);
+                if (node)
+                    byId.set(change.id, { ...node, position: change.position });
+                break;
+            }
+            case "select": {
+                const node = byId.get(change.id);
+                if (node)
+                    byId.set(change.id, { ...node, selected: change.selected });
+                break;
+            }
+        }
+    }
+    let next = nodes
+        .filter((n) => !removed.has(n.id))
+        .map((n) => { var _a; return (_a = byId.get(n.id)) !== null && _a !== void 0 ? _a : n; });
+    if (added.length > 0) {
+        next = next.concat(added.filter((a) => !nodes.some((n) => n.id === a.id)));
+    }
+    return next;
+}
+/** Fold a batch of {@link EdgeChange}s into an edges array, returning a new array. */
+function applyEdgeChanges(changes, edges) {
+    if (changes.length === 0)
+        return edges;
+    const byId = new Map(edges.map((e) => [e.id, e]));
+    const removed = new Set();
+    const added = [];
+    for (const change of changes) {
+        switch (change.type) {
+            case "add":
+                added.push(change.item);
+                break;
+            case "remove":
+                removed.add(change.id);
+                break;
+            case "select": {
+                const edge = byId.get(change.id);
+                if (edge)
+                    byId.set(change.id, { ...edge, selected: change.selected });
+                break;
+            }
+        }
+    }
+    let next = edges
+        .filter((e) => !removed.has(e.id))
+        .map((e) => { var _a; return (_a = byId.get(e.id)) !== null && _a !== void 0 ? _a : e; });
+    if (added.length > 0) {
+        next = next.concat(added.filter((a) => !edges.some((e) => e.id === a.id)));
+    }
+    return next;
+}
+
+export { applyEdgeChanges, applyNodeChanges };

package/dist/components/canvas/changes.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/canvas/context/CanvasContext.d.ts

@@ -0,0 +1,41 @@
+import type React from "react";
+import type { NodeCanvasNode, NodeCanvasViewport, SetViewport, XYPosition } from "../NodeCanvas.types";
+export interface CanvasContextValue {
+    /** Current nodes (for overview chrome like MiniMap). */
+    nodes: NodeCanvasNode[];
+    viewport: NodeCanvasViewport;
+    /** Always-current viewport, safe to read inside pointer handlers (e.g. node drag). */
+    viewportRef: React.MutableRefObject<NodeCanvasViewport>;
+    setViewport: SetViewport;
+    minZoom: number;
+    maxZoom: number;
+    /** The clipping pane element (gesture target + measurement origin). */
+    paneRef: React.RefObject<HTMLDivElement | null>;
+    /** Flow coords → pane-local screen coords. */
+    flowToScreen: (point: XYPosition) => XYPosition;
+    /** Pane-local screen coords → flow coords. */
+    screenToFlow: (point: XYPosition) => XYPosition;
+    /** Fit all nodes into the viewport. */
+    fitView: () => void;
+    /** When locked, pan, node drag, and connections are disabled (zoom still works). */
+    locked: boolean;
+    setLocked: (locked: boolean) => void;
+    /** Active snap grid `[x, y]` in flow units, or `null` when snapping is off. */
+    snapGrid: [number, number] | null;
+    /** Active tool: `select` (drag = select/move) or `pan` (drag anywhere = pan). */
+    tool: CanvasTool;
+    setTool: (tool: CanvasTool) => void;
+}
+export type CanvasTool = "select" | "pan";
+/** Per-frame slice: changes on every graph or viewport update. */
+export type CanvasStateValue = Pick<CanvasContextValue, "nodes" | "viewport" | "flowToScreen" | "screenToFlow">;
+/** Stable slice: refs, setters, and slow-moving interaction flags. */
+export type CanvasApiValue = Omit<CanvasContextValue, keyof CanvasStateValue>;
+export declare const CanvasStateProvider: React.Provider<CanvasStateValue | undefined>;
+export declare const CanvasApiProvider: React.Provider<CanvasApiValue | undefined>;
+/** Internal: per-frame canvas data (`nodes`, `viewport`, transforms). Throws outside `<NodeCanvas>`. */
+export declare function useCanvasState(): CanvasStateValue;
+/** Internal: stable canvas API (refs, setters, `locked`/`tool`/`snapGrid`). Throws outside `<NodeCanvas>`. */
+export declare function useCanvasApi(): CanvasApiValue;
+/** Access the canvas viewport + coordinate transforms. Throws outside `<NodeCanvas>`. */
+export declare function useNodeCanvasContext(): CanvasContextValue;

package/dist/components/canvas/context/CanvasContext.js

@@ -0,0 +1,34 @@
+"use client";
+import { createContext, useContext, useMemo } from 'react';
+
+const CanvasStateContext = createContext(undefined);
+const CanvasApiContext = createContext(undefined);
+const CanvasStateProvider = CanvasStateContext.Provider;
+const CanvasApiProvider = CanvasApiContext.Provider;
+/** Internal: per-frame canvas data (`nodes`, `viewport`, transforms). Throws outside `<NodeCanvas>`. */
+function useCanvasState() {
+    const ctx = useContext(CanvasStateContext);
+    if (!ctx) {
+        throw new Error("NodeCanvas compound parts must be used within <NodeCanvas>");
+    }
+    return ctx;
+}
+/** Internal: stable canvas API (refs, setters, `locked`/`tool`/`snapGrid`). Throws outside `<NodeCanvas>`. */
+function useCanvasApi() {
+    const ctx = useContext(CanvasApiContext);
+    if (!ctx) {
+        throw new Error("NodeCanvas compound parts must be used within <NodeCanvas>");
+    }
+    return ctx;
+}
+/** Access the canvas viewport + coordinate transforms. Throws outside `<NodeCanvas>`. */
+function useNodeCanvasContext() {
+    const api = useContext(CanvasApiContext);
+    const state = useContext(CanvasStateContext);
+    if (!api || !state) {
+        throw new Error("NodeCanvas compound parts must be used within <NodeCanvas>");
+    }
+    return useMemo(() => ({ ...api, ...state }), [api, state]);
+}
+
+export { CanvasApiProvider, CanvasStateProvider, useCanvasApi, useCanvasState, useNodeCanvasContext };

package/dist/components/canvas/context/ConnectionContext.d.ts

@@ -0,0 +1,33 @@
+import type { HandleType, XYPosition } from "../NodeCanvas.types";
+/** An in-progress connection drag (from a source handle toward the cursor). */
+export interface ConnectionState {
+    sourceNodeId: string;
+    sourceHandleId?: string;
+    sourceType: HandleType;
+    /** `auto` when started from an omnidirectional connect-from-anywhere handle. */
+    sourceKind?: "auto";
+    /** Source handle anchor, in flow coords. */
+    from: XYPosition;
+    /** Current cursor position, in flow coords. */
+    to: XYPosition;
+}
+/**
+ * Stable connection-drag actions consumed by `Handle`. The volatile connection
+ * *state* is passed to `EdgeLayer` as a prop (not via context) so that a connect
+ * drag re-renders only the edge layer, not every handle.
+ */
+export interface ConnectionActions {
+    beginConnection: (args: {
+        nodeId: string;
+        handleId?: string;
+        type: HandleType;
+        kind?: "auto";
+        clientX: number;
+        clientY: number;
+    }) => void;
+    updateConnection: (clientX: number, clientY: number) => void;
+    endConnection: (clientX: number, clientY: number) => void;
+    cancelConnection: () => void;
+}
+export declare const ConnectionActionsProvider: import("react").Provider<ConnectionActions | undefined>;
+export declare function useConnectionActions(): ConnectionActions;

package/dist/components/canvas/context/ConnectionContext.js

@@ -0,0 +1,14 @@
+"use client";
+import { createContext, useContext } from 'react';
+
+const ConnectionActionsContext = createContext(undefined);
+const ConnectionActionsProvider = ConnectionActionsContext.Provider;
+function useConnectionActions() {
+    const ctx = useContext(ConnectionActionsContext);
+    if (!ctx) {
+        throw new Error("<Handle> must be used within <NodeCanvas>");
+    }
+    return ctx;
+}
+
+export { ConnectionActionsProvider, useConnectionActions };

package/dist/components/canvas/context/HandleRegistry.d.ts

@@ -0,0 +1,24 @@
+import type React from "react";
+import type { HandlePosition, HandleType, XYPosition } from "../NodeCanvas.types";
+/** A measured handle: its side + offset in flow coords relative to its node origin. */
+export interface RegisteredHandle {
+    id?: string;
+    type: HandleType;
+    position: HandlePosition;
+    /** Center offset from the node's top-left, in flow units (zoom-independent). */
+    offset: XYPosition;
+    /** `auto` = omnidirectional connect-from-anywhere handle (any node ↔ any node). */
+    kind?: "auto";
+}
+export interface HandleRegistryValue {
+    register: (nodeId: string, handle: RegisteredHandle) => void;
+    unregister: (nodeId: string, key: string) => void;
+    /** nodeId → its registered handles. Read during edge anchoring. */
+    handlesRef: React.MutableRefObject<Map<string, RegisteredHandle[]>>;
+    /** Bumped on every register/unregister so consumers (EdgeLayer) recompute. */
+    version: number;
+}
+export declare const HandleRegistryProvider: React.Provider<HandleRegistryValue | undefined>;
+export declare function useHandleRegistry(): HandleRegistryValue;
+/** Stable registry key for a handle within its node. */
+export declare const handleKey: (type: HandleType, id?: string) => string;