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

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

@@ -0,0 +1,16 @@
+"use client";
+import { createContext, useContext } from 'react';
+
+const HandleRegistryContext = createContext(undefined);
+const HandleRegistryProvider = HandleRegistryContext.Provider;
+function useHandleRegistry() {
+    const ctx = useContext(HandleRegistryContext);
+    if (!ctx) {
+        throw new Error("<Handle> must be used within <NodeCanvas>");
+    }
+    return ctx;
+}
+/** Stable registry key for a handle within its node. */
+const handleKey = (type, id) => `${type}:${id !== null && id !== void 0 ? id : ""}`;
+
+export { HandleRegistryProvider, handleKey, useHandleRegistry };

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

@@ -0,0 +1,18 @@
+import type React from "react";
+/**
+ * Holds transient interaction state shared between the pane and the nodes/edges
+ * (node drag, connection drag). Kept separate from {@link CanvasContextValue} so
+ * that high-frequency interaction updates don't re-render viewport consumers.
+ *
+ * In the foundation this only tracks whether an interaction (node drag / connect)
+ * owns the current gesture, so the pane can decline to pan. Selection and
+ * connection state are layered on in later issues.
+ */
+export interface InteractionContextValue {
+    /** True while a node drag or connection drag owns the pointer gesture. */
+    interactingRef: React.MutableRefObject<boolean>;
+    setInteracting: (interacting: boolean) => void;
+}
+export declare const InteractionProvider: React.Provider<InteractionContextValue | undefined>;
+/** Access transient interaction state. Throws outside `<NodeCanvas>`. */
+export declare function useCanvasInteraction(): InteractionContextValue;

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

@@ -0,0 +1,15 @@
+"use client";
+import { createContext, useContext } from 'react';
+
+const InteractionContext = createContext(undefined);
+const InteractionProvider = InteractionContext.Provider;
+/** Access transient interaction state. Throws outside `<NodeCanvas>`. */
+function useCanvasInteraction() {
+    const ctx = useContext(InteractionContext);
+    if (!ctx) {
+        throw new Error("NodeCanvas compound parts must be used within <NodeCanvas>");
+    }
+    return ctx;
+}
+
+export { InteractionProvider, useCanvasInteraction };

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

@@ -0,0 +1,3 @@
+export declare const NodeIdProvider: import("react").Provider<string | undefined>;
+/** Read the id of the node a component is rendered inside. Throws if used outside a node. */
+export declare function useNodeId(): string;

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

@@ -0,0 +1,16 @@
+"use client";
+import { createContext, useContext } from 'react';
+
+/** Provides the current node's id to anything rendered inside it (e.g. `Handle`). */
+const NodeIdContext = createContext(undefined);
+const NodeIdProvider = NodeIdContext.Provider;
+/** Read the id of the node a component is rendered inside. Throws if used outside a node. */
+function useNodeId() {
+    const id = useContext(NodeIdContext);
+    if (id === undefined) {
+        throw new Error("<Handle> must be rendered inside a NodeCanvas node component");
+    }
+    return id;
+}
+
+export { NodeIdProvider, useNodeId };

package/dist/components/canvas/hooks/useConnection.d.ts

@@ -0,0 +1,17 @@
+import type React from "react";
+import type { HandleType } from "../NodeCanvas.types";
+interface UseConnectionParams {
+    nodeId: string;
+    handleId?: string;
+    type: HandleType;
+    kind?: "auto";
+}
+/**
+ * Wires a `Handle`'s pointer-down to a connection drag: begins the connection,
+ * tracks the cursor on `window` (so it follows past the handle), and completes /
+ * cancels on release. Stops propagation so the node neither drags nor selects.
+ */
+export declare function useConnection(params: UseConnectionParams): {
+    onPointerDown: (e: React.PointerEvent) => void;
+};
+export {};

package/dist/components/canvas/hooks/useConnection.js

@@ -0,0 +1,30 @@
+"use client";
+import { useConnectionActions } from '../context/ConnectionContext.js';
+
+/**
+ * Wires a `Handle`'s pointer-down to a connection drag: begins the connection,
+ * tracks the cursor on `window` (so it follows past the handle), and completes /
+ * cancels on release. Stops propagation so the node neither drags nor selects.
+ */
+function useConnection(params) {
+    const { nodeId, handleId, type, kind } = params;
+    const { beginConnection, updateConnection, endConnection } = useConnectionActions();
+    const onPointerDown = (e) => {
+        if (e.button !== 0)
+            return;
+        e.preventDefault();
+        e.stopPropagation();
+        beginConnection({ nodeId, handleId, type, kind, clientX: e.clientX, clientY: e.clientY });
+        const move = (ev) => updateConnection(ev.clientX, ev.clientY);
+        const up = (ev) => {
+            window.removeEventListener("pointermove", move);
+            window.removeEventListener("pointerup", up);
+            endConnection(ev.clientX, ev.clientY);
+        };
+        window.addEventListener("pointermove", move);
+        window.addEventListener("pointerup", up);
+    };
+    return { onPointerDown };
+}
+
+export { useConnection };

package/dist/components/canvas/hooks/useMarquee.d.ts

@@ -0,0 +1,25 @@
+import type React from "react";
+export interface MarqueeRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface UseMarqueeParams {
+    paneRef: React.RefObject<HTMLDivElement | null>;
+    lockedRef: React.MutableRefObject<boolean>;
+    /** Marquee is select-tool only. */
+    toolRef: React.MutableRefObject<"select" | "pan">;
+    /** Set true while marqueeing so the pane declines to pan. */
+    interactingRef: React.MutableRefObject<boolean>;
+    /** Replace selection with exactly these node ids (live, during the drag). */
+    onSelect: (nodeIds: string[]) => void;
+}
+/**
+ * Shift + drag on the empty canvas draws a selection rectangle and selects every
+ * intersecting node (live). Intersection is tested in screen coords against each
+ * node's real rendered rect, so it's accurate regardless of node size or zoom.
+ * Returns the pane-local rect to render, or `null` when inactive.
+ */
+export declare function useMarquee({ paneRef, lockedRef, toolRef, interactingRef, onSelect, }: UseMarqueeParams): MarqueeRect | null;
+export {};

package/dist/components/canvas/hooks/useMarquee.js

@@ -0,0 +1,92 @@
+"use client";
+import { useState, useEffect } from 'react';
+
+const IGNORE = "[data-flikkui-node],[data-flikkui-handle],[data-flikkui-edge],[data-flikkui-controls],[data-flikkui-nopan],[data-flikkui-portal]";
+/**
+ * Shift + drag on the empty canvas draws a selection rectangle and selects every
+ * intersecting node (live). Intersection is tested in screen coords against each
+ * node's real rendered rect, so it's accurate regardless of node size or zoom.
+ * Returns the pane-local rect to render, or `null` when inactive.
+ */
+function useMarquee({ paneRef, lockedRef, toolRef, interactingRef, onSelect, }) {
+    const [rect, setRect] = useState(null);
+    useEffect(() => {
+        const pane = paneRef.current;
+        if (!pane)
+            return;
+        let start = null;
+        let active = false;
+        const onDown = (e) => {
+            if (e.button !== 0 || !e.shiftKey || lockedRef.current || toolRef.current === "pan")
+                return;
+            const target = e.target;
+            if (target === null || target === void 0 ? void 0 : target.closest(IGNORE))
+                return; // only on empty canvas
+            const r = pane.getBoundingClientRect();
+            start = { x: e.clientX - r.left, y: e.clientY - r.top };
+            active = true;
+            interactingRef.current = true;
+            try {
+                pane.setPointerCapture(e.pointerId);
+            }
+            catch (_a) {
+                /* noop */
+            }
+            setRect({ x: start.x, y: start.y, width: 0, height: 0 });
+            e.preventDefault();
+        };
+        const onMove = (e) => {
+            if (!active || !start)
+                return;
+            const r = pane.getBoundingClientRect();
+            const cx = e.clientX - r.left;
+            const cy = e.clientY - r.top;
+            const x = Math.min(start.x, cx);
+            const y = Math.min(start.y, cy);
+            const width = Math.abs(cx - start.x);
+            const height = Math.abs(cy - start.y);
+            setRect({ x, y, width, height });
+            const mLeft = r.left + x;
+            const mTop = r.top + y;
+            const mRight = mLeft + width;
+            const mBottom = mTop + height;
+            const ids = [];
+            pane.querySelectorAll("[data-flikkui-node]").forEach((el) => {
+                const nr = el.getBoundingClientRect();
+                if (nr.left < mRight && nr.right > mLeft && nr.top < mBottom && nr.bottom > mTop) {
+                    const id = el.getAttribute("data-flikkui-node");
+                    if (id)
+                        ids.push(id);
+                }
+            });
+            onSelect(ids);
+        };
+        const onUp = (e) => {
+            if (!active)
+                return;
+            active = false;
+            start = null;
+            interactingRef.current = false;
+            setRect(null);
+            try {
+                pane.releasePointerCapture(e.pointerId);
+            }
+            catch (_a) {
+                /* noop */
+            }
+        };
+        pane.addEventListener("pointerdown", onDown);
+        pane.addEventListener("pointermove", onMove);
+        pane.addEventListener("pointerup", onUp);
+        pane.addEventListener("pointercancel", onUp);
+        return () => {
+            pane.removeEventListener("pointerdown", onDown);
+            pane.removeEventListener("pointermove", onMove);
+            pane.removeEventListener("pointerup", onUp);
+            pane.removeEventListener("pointercancel", onUp);
+        };
+    }, [paneRef, lockedRef, toolRef, interactingRef, onSelect]);
+    return rect;
+}
+
+export { useMarquee };

package/dist/components/canvas/hooks/useNodeDrag.d.ts

@@ -0,0 +1,23 @@
+import type React from "react";
+import type { NodeCanvasNode, NodeChange } from "../NodeCanvas.types";
+interface UseNodeDragParams {
+    nodeId: string;
+    getNode: () => NodeCanvasNode | undefined;
+    emit: (changes: NodeChange[]) => void;
+}
+interface UseNodeDragResult {
+    dragging: boolean;
+    onPointerDown: (e: React.PointerEvent) => void;
+    onPointerMove: (e: React.PointerEvent) => void;
+    onPointerUp: (e: React.PointerEvent) => void;
+}
+/**
+ * Canvas-owned pointer math for moving a single node. Converts screen deltas to
+ * flow deltas via the live zoom, emits `position` change-objects (with a `dragging`
+ * flag), and claims the gesture from the pane so it doesn't pan underneath.
+ *
+ * Drag never starts from interactive children (inputs, buttons, `.nodrag`), so
+ * controls inside custom nodes keep working.
+ */
+export declare function useNodeDrag(params: UseNodeDragParams): UseNodeDragResult;
+export {};

package/dist/components/canvas/hooks/useNodeDrag.js

@@ -0,0 +1,111 @@
+"use client";
+import { useState, useRef } from 'react';
+import { useCanvasApi } from '../context/CanvasContext.js';
+import { useCanvasInteraction } from '../context/InteractionContext.js';
+import { isEditableTarget } from '../utils.js';
+
+/** Drag won't start from these (interactive controls / opt-out hosts). */
+function isNoDragTarget(target) {
+    if (!(target instanceof HTMLElement))
+        return false;
+    if (isEditableTarget(target))
+        return true;
+    return target.closest("button, a, [data-nodrag], .nodrag") !== null;
+}
+const DRAG_THRESHOLD_PX = 3;
+/**
+ * Canvas-owned pointer math for moving a single node. Converts screen deltas to
+ * flow deltas via the live zoom, emits `position` change-objects (with a `dragging`
+ * flag), and claims the gesture from the pane so it doesn't pan underneath.
+ *
+ * Drag never starts from interactive children (inputs, buttons, `.nodrag`), so
+ * controls inside custom nodes keep working.
+ */
+function useNodeDrag(params) {
+    const { nodeId, getNode, emit } = params;
+    const { viewportRef, locked, snapGrid, tool } = useCanvasApi();
+    const { setInteracting } = useCanvasInteraction();
+    const [dragging, setDragging] = useState(false);
+    const snapPoint = (x, y) => snapGrid
+        ? {
+            x: Math.round(x / snapGrid[0]) * snapGrid[0],
+            y: Math.round(y / snapGrid[1]) * snapGrid[1],
+        }
+        : { x, y };
+    const drag = useRef(null);
+    const onPointerDown = (e) => {
+        if (e.button !== 0)
+            return;
+        if (locked || tool === "pan")
+            return;
+        if (isNoDragTarget(e.target))
+            return;
+        const node = getNode();
+        if (!node || node.draggable === false)
+            return;
+        e.stopPropagation(); // don't let the pane start panning
+        // Initialize drag state before capturing, so a capture failure can't abort it.
+        setInteracting(true);
+        drag.current = {
+            pointerId: e.pointerId,
+            startClient: { x: e.clientX, y: e.clientY },
+            startPos: { ...node.position },
+            zoom: viewportRef.current.zoom,
+            moved: false,
+        };
+        try {
+            e.currentTarget.setPointerCapture(e.pointerId);
+        }
+        catch (_a) {
+            /* capture unsupported / pointer inactive — drag still works via bubbling */
+        }
+    };
+    const onPointerMove = (e) => {
+        const s = drag.current;
+        if (!s || e.pointerId !== s.pointerId)
+            return;
+        const dxScreen = e.clientX - s.startClient.x;
+        const dyScreen = e.clientY - s.startClient.y;
+        if (!s.moved && Math.hypot(dxScreen, dyScreen) < DRAG_THRESHOLD_PX)
+            return;
+        if (!s.moved) {
+            s.moved = true;
+            setDragging(true);
+        }
+        emit([
+            {
+                type: "position",
+                id: nodeId,
+                position: snapPoint(s.startPos.x + dxScreen / s.zoom, s.startPos.y + dyScreen / s.zoom),
+                dragging: true,
+            },
+        ]);
+    };
+    const onPointerUp = (e) => {
+        const s = drag.current;
+        if (!s || e.pointerId !== s.pointerId)
+            return;
+        if (s.moved) {
+            emit([
+                {
+                    type: "position",
+                    id: nodeId,
+                    position: snapPoint(s.startPos.x + (e.clientX - s.startClient.x) / s.zoom, s.startPos.y + (e.clientY - s.startClient.y) / s.zoom),
+                    dragging: false,
+                },
+            ]);
+        }
+        drag.current = null;
+        setDragging(false);
+        setInteracting(false);
+        try {
+            e.currentTarget.releasePointerCapture(e.pointerId);
+        }
+        catch (_a) {
+            /* already released */
+        }
+    };
+    return { dragging, onPointerDown, onPointerMove, onPointerUp };
+}
+
+export { useNodeDrag };

package/dist/components/canvas/hooks/usePanZoom.d.ts

@@ -0,0 +1,30 @@
+import type React from "react";
+import type { SetViewport } from "../NodeCanvas.types";
+interface UsePanZoomParams {
+    paneRef: React.RefObject<HTMLDivElement | null>;
+    setViewport: SetViewport;
+    minZoom: number;
+    maxZoom: number;
+    /** When true, a node drag / connection owns the gesture — pane declines to pan. */
+    interactingRef: React.MutableRefObject<boolean>;
+    /** When locked, panning is disabled (zoom still works). */
+    lockedRef: React.MutableRefObject<boolean>;
+    /** Active tool — in `pan` mode, drag anywhere (even over nodes) pans. */
+    toolRef: React.MutableRefObject<"select" | "pan">;
+    panOnDrag: boolean;
+    panOnScroll: boolean;
+    zoomOnScroll: boolean;
+    zoomActivationKey: "ctrl" | "meta" | "shift" | null;
+}
+/**
+ * Attaches wheel/pinch zoom + pointer-drag pan to the canvas pane.
+ *
+ * - **Zoom** is anchored to the cursor (the flow point under the pointer stays put).
+ * - **Pinch** works via trackpad (`ctrlKey` wheel) and two-pointer touch.
+ * - **Pan** via pointer drag on the pane background or while `Space` is held.
+ *
+ * All viewport math uses functional `setViewport` updates, so there are no stale
+ * closures and the hook never needs to re-subscribe on viewport change.
+ */
+export declare function usePanZoom(params: UsePanZoomParams): void;
+export {};

package/dist/components/canvas/hooks/usePanZoom.js

@@ -0,0 +1,195 @@
+"use client";
+import { useEffect } from 'react';
+import { isEditableTarget, clamp } from '../utils.js';
+
+/** Wheel delta → zoom factor sensitivity. */
+const ZOOM_SENSITIVITY = 0.0015;
+/**
+ * Attaches wheel/pinch zoom + pointer-drag pan to the canvas pane.
+ *
+ * - **Zoom** is anchored to the cursor (the flow point under the pointer stays put).
+ * - **Pinch** works via trackpad (`ctrlKey` wheel) and two-pointer touch.
+ * - **Pan** via pointer drag on the pane background or while `Space` is held.
+ *
+ * All viewport math uses functional `setViewport` updates, so there are no stale
+ * closures and the hook never needs to re-subscribe on viewport change.
+ */
+function usePanZoom(params) {
+    const { paneRef, setViewport, minZoom, maxZoom, interactingRef, lockedRef, toolRef, panOnDrag, panOnScroll, zoomOnScroll, zoomActivationKey, } = params;
+    useEffect(() => {
+        const pane = paneRef.current;
+        if (!pane)
+            return;
+        const pointers = new Map();
+        const space = { pressed: false };
+        let panning = false;
+        let last = { x: 0, y: 0 };
+        let pinchDist = 0;
+        const matchesZoomKey = (e) => zoomActivationKey === "ctrl"
+            ? e.ctrlKey
+            : zoomActivationKey === "meta"
+                ? e.metaKey
+                : zoomActivationKey === "shift"
+                    ? e.shiftKey
+                    : false;
+        const zoomAt = (sx, sy, factor) => {
+            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 onWheel = (e) => {
+            e.preventDefault();
+            const rect = pane.getBoundingClientRect();
+            const sx = e.clientX - rect.left;
+            const sy = e.clientY - rect.top;
+            // Trackpad pinch arrives as a wheel event with ctrlKey set.
+            const pinch = e.ctrlKey;
+            const wantZoom = zoomOnScroll &&
+                (pinch || (zoomActivationKey ? matchesZoomKey(e) : !panOnScroll));
+            if (wantZoom) {
+                zoomAt(sx, sy, Math.exp(-e.deltaY * ZOOM_SENSITIVITY));
+            }
+            else if (panOnScroll) {
+                setViewport((v) => ({ ...v, x: v.x - e.deltaX, y: v.y - e.deltaY }));
+            }
+            else if (zoomOnScroll) {
+                zoomAt(sx, sy, Math.exp(-e.deltaY * ZOOM_SENSITIVITY));
+            }
+        };
+        const twoPointerDistance = () => {
+            const [a, b] = [...pointers.values()];
+            return Math.hypot(a.x - b.x, a.y - b.y);
+        };
+        const twoPointerMidpoint = () => {
+            const rect = pane.getBoundingClientRect();
+            const [a, b] = [...pointers.values()];
+            return { cx: (a.x + b.x) / 2 - rect.left, cy: (a.y + b.y) / 2 - rect.top };
+        };
+        const onPointerDown = (e) => {
+            pointers.set(e.pointerId, { x: e.clientX, y: e.clientY });
+            if (pointers.size === 2) {
+                panning = false;
+                pane.style.cursor = "";
+                pinchDist = twoPointerDistance();
+                return;
+            }
+            if (pointers.size > 2)
+                return;
+            // Only pan from the canvas background. If the press landed on a node, a
+            // handle, or a nested overlay, that element owns the gesture — decided from
+            // the DOM target so it's independent of React handler timing (the pane's
+            // native listener fires before React's stopPropagation could run).
+            const panMode = toolRef.current === "pan";
+            const target = e.target;
+            // In select mode, defer to nodes/handles/edges/chrome. In pan mode, pan over
+            // everything except the always-interactive chrome (controls, minimap, overlays).
+            if (target === null || target === void 0 ? void 0 : target.closest(panMode
+                ? "[data-flikkui-controls],[data-flikkui-nopan],[data-flikkui-portal]"
+                : "[data-flikkui-node],[data-flikkui-handle],[data-flikkui-edge],[data-flikkui-controls],[data-flikkui-nopan],[data-flikkui-portal]")) {
+                return;
+            }
+            // A node drag / connection has claimed this gesture.
+            if (interactingRef.current)
+                return;
+            // Shift+drag is reserved for marquee selection.
+            if (e.shiftKey && !space.pressed)
+                return;
+            if (lockedRef.current && !space.pressed)
+                return;
+            if (!panOnDrag && !space.pressed)
+                return;
+            if (e.button !== 0 && e.button !== 1)
+                return;
+            panning = true;
+            last = { x: e.clientX, y: e.clientY };
+            try {
+                pane.setPointerCapture(e.pointerId);
+            }
+            catch (_a) {
+                /* capture unsupported / pointer inactive — pan still works via bubbling */
+            }
+            pane.style.cursor = "grabbing";
+        };
+        const onPointerMove = (e) => {
+            if (pointers.has(e.pointerId)) {
+                pointers.set(e.pointerId, { x: e.clientX, y: e.clientY });
+            }
+            if (pointers.size >= 2) {
+                const dist = twoPointerDistance();
+                if (pinchDist > 0) {
+                    const { cx, cy } = twoPointerMidpoint();
+                    zoomAt(cx, cy, dist / pinchDist);
+                }
+                pinchDist = dist;
+                return;
+            }
+            if (!panning)
+                return;
+            const dx = e.clientX - last.x;
+            const dy = e.clientY - last.y;
+            last = { x: e.clientX, y: e.clientY };
+            setViewport((v) => ({ ...v, x: v.x + dx, y: v.y + dy }));
+        };
+        const endPointer = (e) => {
+            pointers.delete(e.pointerId);
+            if (pointers.size < 2)
+                pinchDist = 0;
+            if (pointers.size === 0) {
+                panning = false;
+                pane.style.cursor = space.pressed ? "grab" : "";
+                try {
+                    pane.releasePointerCapture(e.pointerId);
+                }
+                catch (_a) {
+                    /* pointer may already be released */
+                }
+            }
+        };
+        const onKeyDown = (e) => {
+            if (e.code === "Space" && !isEditableTarget(e.target)) {
+                space.pressed = true;
+                if (!panning)
+                    pane.style.cursor = "grab";
+            }
+        };
+        const onKeyUp = (e) => {
+            if (e.code === "Space") {
+                space.pressed = false;
+                if (!panning)
+                    pane.style.cursor = "";
+            }
+        };
+        pane.addEventListener("wheel", onWheel, { passive: false });
+        pane.addEventListener("pointerdown", onPointerDown);
+        pane.addEventListener("pointermove", onPointerMove);
+        pane.addEventListener("pointerup", endPointer);
+        pane.addEventListener("pointercancel", endPointer);
+        window.addEventListener("keydown", onKeyDown);
+        window.addEventListener("keyup", onKeyUp);
+        return () => {
+            pane.removeEventListener("wheel", onWheel);
+            pane.removeEventListener("pointerdown", onPointerDown);
+            pane.removeEventListener("pointermove", onPointerMove);
+            pane.removeEventListener("pointerup", endPointer);
+            pane.removeEventListener("pointercancel", endPointer);
+            window.removeEventListener("keydown", onKeyDown);
+            window.removeEventListener("keyup", onKeyUp);
+        };
+    }, [
+        paneRef,
+        setViewport,
+        minZoom,
+        maxZoom,
+        interactingRef,
+        lockedRef,
+        toolRef,
+        panOnDrag,
+        panOnScroll,
+        zoomOnScroll,
+        zoomActivationKey,
+    ]);
+}
+
+export { usePanZoom };

package/dist/components/canvas/hooks/useViewport.d.ts

@@ -0,0 +1,21 @@
+import type { NodeCanvasViewport, SetViewport } from "../NodeCanvas.types";
+interface UseViewportParams {
+    /** Controlled viewport (when defined, internal state is bypassed). */
+    controlled?: NodeCanvasViewport;
+    defaultViewport?: NodeCanvasViewport;
+    onChange?: (viewport: NodeCanvasViewport) => void;
+    minZoom: number;
+    maxZoom: number;
+}
+interface UseViewportResult {
+    viewport: NodeCanvasViewport;
+    setViewport: SetViewport;
+    /** Always-current viewport, safe to read inside event handlers. */
+    viewportRef: React.MutableRefObject<NodeCanvasViewport>;
+}
+/**
+ * Owns the viewport transform with a controlled/uncontrolled split (Accordion idiom).
+ * Zoom is clamped on every update; `onChange` always fires with the resolved value.
+ */
+export declare function useViewport(params: UseViewportParams): UseViewportResult;
+export {};

package/dist/components/canvas/hooks/useViewport.js

@@ -0,0 +1,36 @@
+"use client";
+import { useState, useRef, useCallback } from 'react';
+import { clamp } from '../utils.js';
+
+const DEFAULT_VIEWPORT = { x: 0, y: 0, zoom: 1 };
+/**
+ * Owns the viewport transform with a controlled/uncontrolled split (Accordion idiom).
+ * Zoom is clamped on every update; `onChange` always fires with the resolved value.
+ */
+function useViewport(params) {
+    const { controlled, defaultViewport, onChange, minZoom, maxZoom } = params;
+    const isControlled = controlled !== undefined;
+    const [internal, setInternal] = useState(() => { var _a; return (_a = controlled !== null && controlled !== void 0 ? controlled : defaultViewport) !== null && _a !== void 0 ? _a : DEFAULT_VIEWPORT; });
+    const viewport = isControlled ? controlled : internal;
+    const viewportRef = useRef(viewport);
+    viewportRef.current = viewport;
+    const onChangeRef = useRef(onChange);
+    onChangeRef.current = onChange;
+    const setViewport = useCallback((next) => {
+        var _a;
+        const prev = viewportRef.current;
+        const resolved = typeof next === "function" ? next(prev) : next;
+        const clamped = {
+            x: resolved.x,
+            y: resolved.y,
+            zoom: clamp(resolved.zoom, minZoom, maxZoom),
+        };
+        viewportRef.current = clamped;
+        if (!isControlled)
+            setInternal(clamped);
+        (_a = onChangeRef.current) === null || _a === void 0 ? void 0 : _a.call(onChangeRef, clamped);
+    }, [isControlled, minZoom, maxZoom]);
+    return { viewport, setViewport, viewportRef };
+}
+
+export { useViewport };