@flikk/ui 1.0.0-beta.27 → 1.0.0-beta.29

package/dist/components/canvas/NodeCanvas.js

@@ -0,0 +1,477 @@
+import { jsx, jsxs } from 'react/jsx-runtime';
+import React__default, { useRef, useState, useCallback, useEffect, useMemo } from 'react';
+import { cn } from '../../utils/cn.js';
+import { useIsClient } from '../../hooks/useIsClient.js';
+import { CanvasProvider } from './context/CanvasContext.js';
+import { InteractionProvider } from './context/InteractionContext.js';
+import { handleKey, HandleRegistryProvider } from './context/HandleRegistry.js';
+import { ConnectionActionsProvider } from './context/ConnectionContext.js';
+import { useViewport } from './hooks/useViewport.js';
+import { usePanZoom } from './hooks/usePanZoom.js';
+import { useMarquee } from './hooks/useMarquee.js';
+import { NodeRenderer } from './NodeRenderer.js';
+import { EdgeLayer } from './EdgeLayer.js';
+import { applyNodeChanges, applyEdgeChanges } from './changes.js';
+import { nodeCanvasTheme } from './NodeCanvas.theme.js';
+import { clamp, isEditableTarget } from './utils.js';
+
+/** Estimated node footprint used by `fitView` until real sizes are measured (issue 4). */
+const ESTIMATED_NODE_SIZE = { width: 180, height: 80 };
+const FIT_VIEW_PADDING = 0.85;
+/**
+ * The node-editor canvas: a pannable / zoomable viewport over an unbounded flow
+ * space. Renders nodes from `nodes` (via the `nodeTypes` registry) and edges from
+ * `edges`, supports drag-to-connect, and exposes everything through change-object
+ * callbacks. `children` are pane-level chrome (e.g. `Background`, controls) drawn
+ * over the canvas; nodes + edges live in the transformed world.
+ */
+const NodeCanvas = React__default.forwardRef(function NodeCanvas(props, ref) {
+    const { 
+    // data
+    nodes: nodesProp, defaultNodes, edges: edgesProp, defaultEdges, nodeTypes, onNodesChange, onEdgesChange, onConnect, onSelectionChange, onNodeClick, onBeforeDelete, isValidConnection, 
+    // viewport
+    viewport: viewportProp, defaultViewport, onViewportChange, 
+    // config
+    minZoom = 0.25, maxZoom = 2, fitViewOnInit = false, panOnScroll = false, zoomOnScroll = true, zoomActivationKey = null, panOnDrag = true, snapToGrid = false, snapGrid: snapGridProp, autoConnect = true, className, theme: themeOverrides, children, ...rest } = props;
+    useIsClient(); // SSR guard parity with the rest of the library
+    const snapGrid = snapToGrid
+        ? (snapGridProp !== null && snapGridProp !== void 0 ? snapGridProp : [16, 16])
+        : null;
+    const snapGridRef = useRef(snapGrid);
+    snapGridRef.current = snapGrid;
+    const paneRef = useRef(null);
+    React__default.useImperativeHandle(ref, () => paneRef.current, []);
+    const theme = { ...nodeCanvasTheme, ...(themeOverrides !== null && themeOverrides !== void 0 ? themeOverrides : {}) };
+    const { viewport, setViewport, viewportRef } = useViewport({
+        controlled: viewportProp,
+        defaultViewport,
+        onChange: onViewportChange,
+        minZoom,
+        maxZoom,
+    });
+    /* ----- node state ----- */
+    const nodesControlled = nodesProp !== undefined;
+    const [internalNodes, setInternalNodes] = useState(() => defaultNodes !== null && defaultNodes !== void 0 ? defaultNodes : []);
+    const nodes = nodesControlled ? nodesProp : internalNodes;
+    const nodesRef = useRef(nodes);
+    nodesRef.current = nodes;
+    const onNodesChangeRef = useRef(onNodesChange);
+    onNodesChangeRef.current = onNodesChange;
+    const onSelectionChangeRef = useRef(onSelectionChange);
+    onSelectionChangeRef.current = onSelectionChange;
+    const emitNodeChanges = useCallback((changes) => {
+        var _a;
+        if (!nodesControlled) {
+            setInternalNodes((prev) => applyNodeChanges(changes, prev));
+        }
+        (_a = onNodesChangeRef.current) === null || _a === void 0 ? void 0 : _a.call(onNodesChangeRef, changes);
+    }, [nodesControlled]);
+    /* ----- edge state ----- */
+    const edgesControlled = edgesProp !== undefined;
+    const [internalEdges, setInternalEdges] = useState(() => defaultEdges !== null && defaultEdges !== void 0 ? defaultEdges : []);
+    const edges = edgesControlled ? edgesProp : internalEdges;
+    const edgesRef = useRef(edges);
+    edgesRef.current = edges;
+    const onEdgesChangeRef = useRef(onEdgesChange);
+    onEdgesChangeRef.current = onEdgesChange;
+    const onBeforeDeleteRef = useRef(onBeforeDelete);
+    onBeforeDeleteRef.current = onBeforeDelete;
+    const emitEdgeChanges = useCallback((changes) => {
+        var _a;
+        if (!edgesControlled) {
+            setInternalEdges((prev) => applyEdgeChanges(changes, prev));
+        }
+        (_a = onEdgesChangeRef.current) === null || _a === void 0 ? void 0 : _a.call(onEdgesChangeRef, changes);
+    }, [edgesControlled]);
+    /* ----- handle registry ----- */
+    const handlesRef = useRef(new Map());
+    const [handleVersion, setHandleVersion] = useState(0);
+    const registerHandle = useCallback((nodeId, handle) => {
+        var _a;
+        const list = (_a = handlesRef.current.get(nodeId)) !== null && _a !== void 0 ? _a : [];
+        const key = handleKey(handle.type, handle.id);
+        handlesRef.current.set(nodeId, list
+            .filter((h) => handleKey(h.type, h.id) !== key)
+            .concat(handle));
+        setHandleVersion((v) => v + 1);
+    }, []);
+    const unregisterHandle = useCallback((nodeId, key) => {
+        const list = handlesRef.current.get(nodeId);
+        if (!list)
+            return;
+        const next = list.filter((h) => handleKey(h.type, h.id) !== key);
+        if (next.length)
+            handlesRef.current.set(nodeId, next);
+        else
+            handlesRef.current.delete(nodeId);
+        setHandleVersion((v) => v + 1);
+    }, []);
+    /* ----- coordinate transforms ----- */
+    const flowToScreen = useCallback((p) => ({
+        x: p.x * viewport.zoom + viewport.x,
+        y: p.y * viewport.zoom + viewport.y,
+    }), [viewport]);
+    const screenToFlow = useCallback((p) => ({
+        x: (p.x - viewport.x) / viewport.zoom,
+        y: (p.y - viewport.y) / viewport.zoom,
+    }), [viewport]);
+    const clientToFlow = useCallback((clientX, clientY) => {
+        const pane = paneRef.current;
+        const v = viewportRef.current;
+        if (!pane)
+            return { x: 0, y: 0 };
+        const r = pane.getBoundingClientRect();
+        return { x: (clientX - r.left - v.x) / v.zoom, y: (clientY - r.top - v.y) / v.zoom };
+    }, [viewportRef]);
+    const fitView = useCallback(() => {
+        const pane = paneRef.current;
+        if (!pane)
+            return;
+        const rect = pane.getBoundingClientRect();
+        const ns = nodesRef.current;
+        if (ns.length === 0) {
+            setViewport({ x: 0, y: 0, zoom: 1 });
+            return;
+        }
+        let minX = Infinity;
+        let minY = Infinity;
+        let maxX = -Infinity;
+        let maxY = -Infinity;
+        for (const n of ns) {
+            minX = Math.min(minX, n.position.x);
+            minY = Math.min(minY, n.position.y);
+            maxX = Math.max(maxX, n.position.x + ESTIMATED_NODE_SIZE.width);
+            maxY = Math.max(maxY, n.position.y + ESTIMATED_NODE_SIZE.height);
+        }
+        const bw = Math.max(maxX - minX, 1);
+        const bh = Math.max(maxY - minY, 1);
+        // Fit to view but never enlarge past 100% — so the canvas opens at 1:1 for
+        // graphs that already fit, and only zooms out for ones that don't.
+        const zoom = clamp(Math.min(rect.width / bw, rect.height / bh) * FIT_VIEW_PADDING, minZoom, Math.min(maxZoom, 1));
+        const cx = (minX + maxX) / 2;
+        const cy = (minY + maxY) / 2;
+        setViewport({
+            zoom,
+            x: rect.width / 2 - cx * zoom,
+            y: rect.height / 2 - cy * zoom,
+        });
+    }, [setViewport, minZoom, maxZoom]);
+    /* ----- interaction ----- */
+    const interactingRef = useRef(false);
+    const setInteracting = useCallback((interacting) => {
+        interactingRef.current = interacting;
+    }, []);
+    const [locked, setLocked] = useState(false);
+    const lockedRef = useRef(locked);
+    lockedRef.current = locked;
+    const [tool, setTool] = useState("select");
+    const toolRef = useRef(tool);
+    toolRef.current = tool;
+    const [liveMessage, setLiveMessage] = useState("");
+    /* ----- connection drag ----- */
+    const [connection, setConnection] = useState(null);
+    const connectionRef = useRef(null);
+    const setConn = useCallback((next) => {
+        connectionRef.current = next;
+        setConnection(next);
+    }, []);
+    const onConnectRef = useRef(onConnect);
+    onConnectRef.current = onConnect;
+    const isValidConnectionRef = useRef(isValidConnection);
+    isValidConnectionRef.current = isValidConnection;
+    const beginConnection = useCallback(({ nodeId, handleId, type, kind, clientX, clientY }) => {
+        var _a;
+        const node = nodesRef.current.find((n) => n.id === nodeId);
+        if (!node)
+            return;
+        const list = (_a = handlesRef.current.get(nodeId)) !== null && _a !== void 0 ? _a : [];
+        const h = handleId
+            ? list.find((x) => x.id === handleId)
+            : list.find((x) => x.type === type);
+        const from = h
+            ? { x: node.position.x + h.offset.x, y: node.position.y + h.offset.y }
+            : { ...node.position };
+        setConn({
+            sourceNodeId: nodeId,
+            sourceHandleId: handleId,
+            sourceType: type,
+            sourceKind: kind,
+            from,
+            to: clientToFlow(clientX, clientY),
+        });
+        setInteracting(true);
+    }, [clientToFlow, setConn, setInteracting]);
+    const updateConnection = useCallback((clientX, clientY) => {
+        const cur = connectionRef.current;
+        if (!cur)
+            return;
+        setConn({ ...cur, to: clientToFlow(clientX, clientY) });
+    }, [clientToFlow, setConn]);
+    const endConnection = useCallback((clientX, clientY) => {
+        var _a, _b, _c, _d;
+        const cur = connectionRef.current;
+        if (cur) {
+            const handleEl = (_a = document
+                .elementFromPoint(clientX, clientY)) === null || _a === void 0 ? void 0 : _a.closest("[data-flikkui-handle]");
+            if (handleEl) {
+                const targetNodeId = handleEl.getAttribute("data-node-id");
+                const targetType = handleEl.getAttribute("data-handle-type");
+                const targetHandleId = handleEl.getAttribute("data-handle-id") || undefined;
+                const targetKind = handleEl.getAttribute("data-handle-kind");
+                // Omnidirectional ("auto") handles connect any node to any node — direction is
+                // the drag order. Explicit ports still require opposite source/target types.
+                const isAuto = cur.sourceKind === "auto" || targetKind === "auto";
+                const typesOk = isAuto ? true : targetType !== cur.sourceType;
+                if (targetNodeId &&
+                    targetType &&
+                    typesOk &&
+                    targetNodeId !== cur.sourceNodeId) {
+                    const conn = cur.sourceType === "source"
+                        ? {
+                            source: cur.sourceNodeId,
+                            sourceHandle: cur.sourceHandleId,
+                            target: targetNodeId,
+                            targetHandle: targetHandleId,
+                        }
+                        : {
+                            source: targetNodeId,
+                            sourceHandle: targetHandleId,
+                            target: cur.sourceNodeId,
+                            targetHandle: cur.sourceHandleId,
+                        };
+                    if (!isValidConnectionRef.current || isValidConnectionRef.current(conn)) {
+                        (_b = onConnectRef.current) === null || _b === void 0 ? void 0 : _b.call(onConnectRef, conn);
+                        if (!edgesControlled) {
+                            const id = `${conn.source}:${(_c = conn.sourceHandle) !== null && _c !== void 0 ? _c : ""}__${conn.target}:${(_d = conn.targetHandle) !== null && _d !== void 0 ? _d : ""}`;
+                            emitEdgeChanges([{ type: "add", item: { id, ...conn } }]);
+                        }
+                        setLiveMessage(`Connected ${conn.source} to ${conn.target}`);
+                    }
+                }
+            }
+        }
+        setConn(null);
+        setInteracting(false);
+    }, [edgesControlled, emitEdgeChanges, setConn, setInteracting]);
+    const cancelConnection = useCallback(() => {
+        setConn(null);
+        setInteracting(false);
+    }, [setConn, setInteracting]);
+    /* ----- selection + delete ----- */
+    const selectNode = useCallback((id, additive) => {
+        const nodeChanges = [];
+        for (const n of nodesRef.current) {
+            const isTarget = n.id === id;
+            const next = additive ? (isTarget ? !n.selected : !!n.selected) : isTarget;
+            if (!!n.selected !== next) {
+                nodeChanges.push({ type: "select", id: n.id, selected: next });
+            }
+        }
+        if (nodeChanges.length)
+            emitNodeChanges(nodeChanges);
+        if (!additive) {
+            const edgeChanges = edgesRef.current
+                .filter((e) => e.selected)
+                .map((e) => ({ type: "select", id: e.id, selected: false }));
+            if (edgeChanges.length)
+                emitEdgeChanges(edgeChanges);
+        }
+    }, [emitNodeChanges, emitEdgeChanges]);
+    const selectEdge = useCallback((id, additive) => {
+        var _a;
+        const edgeChanges = [];
+        for (const e of edgesRef.current) {
+            const isTarget = e.id === id;
+            const next = additive ? (isTarget ? !e.selected : !!e.selected) : isTarget;
+            if (!!e.selected !== next) {
+                edgeChanges.push({ type: "select", id: e.id, selected: next });
+            }
+        }
+        if (edgeChanges.length)
+            emitEdgeChanges(edgeChanges);
+        if (!additive) {
+            const nodeChanges = nodesRef.current
+                .filter((n) => n.selected)
+                .map((n) => ({ type: "select", id: n.id, selected: false }));
+            if (nodeChanges.length)
+                emitNodeChanges(nodeChanges);
+        }
+        (_a = paneRef.current) === null || _a === void 0 ? void 0 : _a.focus();
+    }, [emitNodeChanges, emitEdgeChanges]);
+    const clearSelection = useCallback(() => {
+        const nodeChanges = nodesRef.current
+            .filter((n) => n.selected)
+            .map((n) => ({ type: "select", id: n.id, selected: false }));
+        const edgeChanges = edgesRef.current
+            .filter((e) => e.selected)
+            .map((e) => ({ type: "select", id: e.id, selected: false }));
+        if (nodeChanges.length)
+            emitNodeChanges(nodeChanges);
+        if (edgeChanges.length)
+            emitEdgeChanges(edgeChanges);
+    }, [emitNodeChanges, emitEdgeChanges]);
+    // Replace node selection with exactly `ids` (used by marquee, live during drag).
+    const selectNodesExact = useCallback((ids) => {
+        const set = new Set(ids);
+        const nodeChanges = nodesRef.current
+            .filter((n) => !!n.selected !== set.has(n.id))
+            .map((n) => ({ type: "select", id: n.id, selected: set.has(n.id) }));
+        if (nodeChanges.length)
+            emitNodeChanges(nodeChanges);
+    }, [emitNodeChanges]);
+    const moveSelectedNodes = useCallback((dx, dy) => {
+        const selected = nodesRef.current.filter((n) => n.selected && n.draggable !== false);
+        if (!selected.length)
+            return;
+        const grid = snapGridRef.current;
+        const snap = (x, y) => grid
+            ? { x: Math.round(x / grid[0]) * grid[0], y: Math.round(y / grid[1]) * grid[1] }
+            : { x, y };
+        emitNodeChanges(selected.map((n) => ({
+            type: "position",
+            id: n.id,
+            position: snap(n.position.x + dx, n.position.y + dy),
+        })));
+    }, [emitNodeChanges]);
+    const deleteSelection = useCallback(() => {
+        const selNodes = nodesRef.current.filter((n) => n.selected);
+        const selEdges = edgesRef.current.filter((e) => e.selected);
+        if (selNodes.length === 0 && selEdges.length === 0)
+            return;
+        if (onBeforeDeleteRef.current &&
+            onBeforeDeleteRef.current({ nodes: selNodes, edges: selEdges }) === false) {
+            return;
+        }
+        const removeIds = new Set(selNodes.map((n) => n.id));
+        // Cascade: also remove edges touching a removed node.
+        const edgeRemovals = edgesRef.current.filter((e) => e.selected || removeIds.has(e.source) || removeIds.has(e.target));
+        if (selNodes.length) {
+            emitNodeChanges(selNodes.map((n) => ({ type: "remove", id: n.id })));
+        }
+        if (edgeRemovals.length) {
+            emitEdgeChanges(edgeRemovals.map((e) => ({ type: "remove", id: e.id })));
+        }
+        const total = selNodes.length + edgeRemovals.length;
+        setLiveMessage(`Deleted ${total} item${total === 1 ? "" : "s"}`);
+    }, [emitNodeChanges, emitEdgeChanges]);
+    const deleteEdgeById = useCallback((id) => {
+        const edge = edgesRef.current.find((e) => e.id === id);
+        if (!edge)
+            return;
+        if (onBeforeDeleteRef.current &&
+            onBeforeDeleteRef.current({ nodes: [], edges: [edge] }) === false) {
+            return;
+        }
+        emitEdgeChanges([{ type: "remove", id }]);
+        setLiveMessage("Deleted 1 connection");
+    }, [emitEdgeChanges]);
+    const ARROW_DELTA = {
+        ArrowUp: [0, -1],
+        ArrowDown: [0, 1],
+        ArrowLeft: [-1, 0],
+        ArrowRight: [1, 0],
+    };
+    const onPaneKeyDown = useCallback((e) => {
+        var _a, _b;
+        if (isEditableTarget(e.target))
+            return;
+        if (e.key === "Delete" || e.key === "Backspace") {
+            e.preventDefault();
+            deleteSelection();
+            return;
+        }
+        // Arrow-key node movement — only when a node shell itself is focused.
+        const dir = ARROW_DELTA[e.key];
+        if (dir && ((_b = (_a = e.target) === null || _a === void 0 ? void 0 : _a.matches) === null || _b === void 0 ? void 0 : _b.call(_a, "[data-flikkui-node]"))) {
+            e.preventDefault();
+            const grid = snapGridRef.current;
+            const base = grid ? grid : [10, 10];
+            const mult = e.shiftKey ? 4 : 1;
+            moveSelectedNodes(dir[0] * base[0] * mult, dir[1] * base[1] * mult);
+        }
+    }, [deleteSelection, moveSelectedNodes]);
+    const onPanePointerDown = useCallback((e) => {
+        if (e.shiftKey)
+            return; // shift+drag is marquee — don't clear selection
+        const target = e.target;
+        if (!(target === null || target === void 0 ? void 0 : target.closest("[data-flikkui-node],[data-flikkui-handle],[data-flikkui-edge],[data-flikkui-controls],[data-flikkui-nopan]"))) {
+            clearSelection();
+        }
+    }, [clearSelection]);
+    // Fire onSelectionChange only when the selected id set actually changes.
+    const prevSelectionRef = useRef("");
+    useEffect(() => {
+        var _a;
+        const selection = {
+            nodes: nodes.filter((n) => n.selected).map((n) => n.id),
+            edges: edges.filter((e) => e.selected).map((e) => e.id),
+        };
+        const sig = JSON.stringify(selection);
+        if (sig !== prevSelectionRef.current) {
+            prevSelectionRef.current = sig;
+            (_a = onSelectionChangeRef.current) === null || _a === void 0 ? void 0 : _a.call(onSelectionChangeRef, selection);
+        }
+    }, [nodes, edges]);
+    usePanZoom({
+        paneRef,
+        setViewport,
+        minZoom,
+        maxZoom,
+        interactingRef,
+        lockedRef,
+        toolRef,
+        panOnDrag,
+        panOnScroll,
+        zoomOnScroll,
+        zoomActivationKey,
+    });
+    const marqueeRect = useMarquee({
+        paneRef,
+        lockedRef,
+        toolRef,
+        interactingRef,
+        onSelect: selectNodesExact,
+    });
+    useEffect(() => {
+        if (fitViewOnInit)
+            fitView();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    /* ----- context values ----- */
+    const canvasValue = useMemo(() => ({
+        nodes,
+        viewport,
+        viewportRef,
+        setViewport,
+        minZoom,
+        maxZoom,
+        paneRef,
+        flowToScreen,
+        screenToFlow,
+        fitView,
+        locked,
+        setLocked,
+        snapGrid,
+        tool,
+        setTool,
+    }), [nodes, viewport, viewportRef, setViewport, minZoom, maxZoom, flowToScreen, screenToFlow, fitView, locked, snapGrid === null || snapGrid === void 0 ? void 0 : snapGrid[0], snapGrid === null || snapGrid === void 0 ? void 0 : snapGrid[1], tool]);
+    const interactionValue = useMemo(() => ({ interactingRef, setInteracting }), [setInteracting]);
+    const handleRegistryValue = useMemo(() => ({
+        register: registerHandle,
+        unregister: unregisterHandle,
+        handlesRef,
+        version: handleVersion,
+    }), [registerHandle, unregisterHandle, handleVersion]);
+    const connectionActionsValue = useMemo(() => ({ beginConnection, updateConnection, endConnection, cancelConnection }), [beginConnection, updateConnection, endConnection, cancelConnection]);
+    return (jsx("div", { ref: paneRef, className: cn(theme.pane, "focus:outline-none", className), tabIndex: -1, onKeyDown: onPaneKeyDown, onPointerDown: onPanePointerDown, ...rest, children: jsx(CanvasProvider, { value: canvasValue, children: jsx(InteractionProvider, { value: interactionValue, children: jsx(HandleRegistryProvider, { value: handleRegistryValue, children: jsxs(ConnectionActionsProvider, { value: connectionActionsValue, children: [children, jsxs("div", { className: theme.world, style: {
+                                    transform: `translate(${viewport.x}px, ${viewport.y}px) scale(${viewport.zoom})`,
+                                }, children: [jsx(EdgeLayer, { nodes: nodes, edges: edges, connection: connection, onSelectEdge: selectEdge, onDeleteEdge: deleteEdgeById }), jsx(NodeRenderer, { nodes: nodes, nodeTypes: nodeTypes, autoConnect: autoConnect, onNodeChanges: emitNodeChanges, onSelectNode: selectNode, onNodeClick: onNodeClick })] }), marqueeRect && (jsx("div", { className: "absolute z-30 pointer-events-none rounded-md border border-[var(--color-primary)] bg-[var(--color-primary)]/10 shadow-inner-real-lg", style: {
+                                    left: marqueeRect.x,
+                                    top: marqueeRect.y,
+                                    width: marqueeRect.width,
+                                    height: marqueeRect.height,
+                                } })), jsx("div", { className: "sr-only", "aria-live": "polite", role: "status", children: liveMessage })] }) }) }) }) }));
+});
+NodeCanvas.displayName = "NodeCanvas";
+
+export { NodeCanvas };

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

@@ -0,0 +1,7 @@
+export interface NodeCanvasTheme {
+    /** The clipping pane that captures pan/zoom gestures. */
+    pane: string;
+    /** The transformed "world" layer that holds nodes + edges. */
+    world: string;
+}
+export declare const nodeCanvasTheme: NodeCanvasTheme;

package/dist/components/canvas/NodeCanvas.theme.js

@@ -0,0 +1,9 @@
+const nodeCanvasTheme = {
+    // Light: the recessed sunken plane, so cards float above an off-white floor
+    // (pure-white --color-background would make the canvas white-on-white).
+    // Dark: the true-black floor — sunken would lift the whole canvas to 12%.
+    pane: "relative w-full h-full overflow-hidden bg-[var(--color-background)] touch-none select-none cursor-grab [contain:strict]",
+    world: "absolute top-0 left-0 z-10 origin-top-left will-change-transform",
+};
+
+export { nodeCanvasTheme };

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

@@ -0,0 +1,187 @@
+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. */
+    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;
+}