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

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,110 @@
+import { useState, useRef } from 'react';
+import { useNodeCanvasContext } 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 } = useNodeCanvasContext();
+    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,189 @@
+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 };
+            pane.setPointerCapture(e.pointerId);
+            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,35 @@
+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 };

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

@@ -0,0 +1,14 @@
+export { NodeCanvas } from "./NodeCanvas";
+export { BaseNode, type BaseNodeProps } from "./BaseNode";
+export { Handle } from "./Handle";
+export { Background, type BackgroundProps, type BackgroundVariant } from "./Background";
+export { NodeControls, type NodeControlsProps } from "./NodeControls";
+export { MiniMap, type MiniMapProps } from "./MiniMap";
+export { CanvasToolbar, type CanvasToolbarProps, type CanvasToolbarNodeOption, } from "./CanvasToolbar";
+export { type CanvasTool } from "./context/CanvasContext";
+export { applyNodeChanges, applyEdgeChanges } from "./changes";
+export { layoutGraph, type LayoutOptions } from "./layout";
+export { useNodeCanvasContext } from "./context/CanvasContext";
+export { useCanvasInteraction } from "./context/InteractionContext";
+export { useNodeId } from "./context/NodeIdContext";
+export type { NodeCanvasProps, NodeCanvasNode, NodeCanvasEdge, EdgeType, NodeCanvasConnection, NodeCanvasViewport, NodeCanvasNodeTypes, NodeChange, EdgeChange, NodeProps, HandleProps, HandleType, HandlePosition, EdgeProps, XYPosition, SetViewport, NodeCanvasThemeOverrides, } from "./NodeCanvas.types";

package/dist/components/canvas/index.js

@@ -0,0 +1,12 @@
+export { NodeCanvas } from './NodeCanvas.js';
+export { BaseNode } from './BaseNode.js';
+export { Handle } from './Handle.js';
+export { Background } from './Background.js';
+export { NodeControls } from './NodeControls.js';
+export { MiniMap } from './MiniMap.js';
+export { CanvasToolbar } from './CanvasToolbar.js';
+export { applyEdgeChanges, applyNodeChanges } from './changes.js';
+export { layoutGraph } from './layout.js';
+export { useNodeCanvasContext } from './context/CanvasContext.js';
+export { useCanvasInteraction } from './context/InteractionContext.js';
+export { useNodeId } from './context/NodeIdContext.js';

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

@@ -0,0 +1,22 @@
+import type { NodeCanvasEdge, NodeCanvasNode } from "./NodeCanvas.types";
+export interface LayoutOptions {
+    /** `LR` = layers flow left→right (default); `TB` = top→bottom. */
+    direction?: "LR" | "TB";
+    /** Assumed node width / height for spacing (no real measurement). */
+    nodeWidth?: number;
+    nodeHeight?: number;
+    /** Gap between layers / within a layer. */
+    gapX?: number;
+    gapY?: number;
+    /** Top-left origin of the laid-out graph. */
+    originX?: number;
+    originY?: number;
+}
+/**
+ * A small dependency-free layered (Sugiyama-lite) auto-layout for DAGs: each node's
+ * layer is the longest path from a root, nodes stack within their layer. Cycles are
+ * tolerated (a back-edge just doesn't deepen the layer). Returns new nodes with
+ * updated `position`; other node fields are preserved. Good enough for tidy flow
+ * graphs without pulling in dagre/elk.
+ */
+export declare function layoutGraph(nodes: NodeCanvasNode[], edges: NodeCanvasEdge[], options?: LayoutOptions): NodeCanvasNode[];

package/dist/components/canvas/layout.js

@@ -0,0 +1,67 @@
+/**
+ * A small dependency-free layered (Sugiyama-lite) auto-layout for DAGs: each node's
+ * layer is the longest path from a root, nodes stack within their layer. Cycles are
+ * tolerated (a back-edge just doesn't deepen the layer). Returns new nodes with
+ * updated `position`; other node fields are preserved. Good enough for tidy flow
+ * graphs without pulling in dagre/elk.
+ */
+function layoutGraph(nodes, edges, options = {}) {
+    var _a, _b;
+    const { direction = "LR", nodeWidth = 200, nodeHeight = 100, gapX = 80, gapY = 40, originX = 0, originY = 0, } = options;
+    if (nodes.length === 0)
+        return nodes;
+    const ids = new Set(nodes.map((n) => n.id));
+    const preds = new Map();
+    for (const n of nodes)
+        preds.set(n.id, []);
+    for (const e of edges) {
+        if (ids.has(e.source) && ids.has(e.target) && e.source !== e.target) {
+            preds.get(e.target).push(e.source);
+        }
+    }
+    // layer = 1 + max(layer of predecessors); memoized, cycle-guarded.
+    const layerOf = new Map();
+    const inProgress = new Set();
+    const computeLayer = (id) => {
+        var _a;
+        const cached = layerOf.get(id);
+        if (cached !== undefined)
+            return cached;
+        if (inProgress.has(id))
+            return 0; // back-edge in a cycle
+        inProgress.add(id);
+        let max = -1;
+        for (const p of (_a = preds.get(id)) !== null && _a !== void 0 ? _a : [])
+            max = Math.max(max, computeLayer(p));
+        const layer = max + 1;
+        inProgress.delete(id);
+        layerOf.set(id, layer);
+        return layer;
+    };
+    for (const n of nodes)
+        computeLayer(n.id);
+    // Group by layer (preserving input order for stable stacking).
+    const byLayer = new Map();
+    for (const n of nodes) {
+        const l = (_a = layerOf.get(n.id)) !== null && _a !== void 0 ? _a : 0;
+        const list = (_b = byLayer.get(l)) !== null && _b !== void 0 ? _b : [];
+        list.push(n);
+        byLayer.set(l, list);
+    }
+    const positioned = new Map();
+    for (const [layer, layerNodes] of byLayer) {
+        layerNodes.forEach((n, i) => {
+            const along = i * (direction === "LR" ? nodeHeight + gapY : nodeWidth + gapX);
+            const across = layer * (direction === "LR" ? nodeWidth + gapX : nodeHeight + gapY);
+            positioned.set(n.id, direction === "LR"
+                ? { x: originX + across, y: originY + along }
+                : { x: originX + along, y: originY + across });
+        });
+    }
+    return nodes.map((n) => {
+        const p = positioned.get(n.id);
+        return p ? { ...n, position: p } : n;
+    });
+}
+
+export { layoutGraph };

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

@@ -0,0 +1,4 @@
+/** Clamp `value` to the inclusive range `[min, max]`. */
+export declare function clamp(value: number, min: number, max: number): number;
+/** True when an event target is a text input / contentEditable host. */
+export declare function isEditableTarget(target: EventTarget | null): boolean;

package/dist/components/canvas/utils.js

@@ -0,0 +1,16 @@
+/** Clamp `value` to the inclusive range `[min, max]`. */
+function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}
+/** True when an event target is a text input / contentEditable host. */
+function isEditableTarget(target) {
+    if (!(target instanceof HTMLElement))
+        return false;
+    const tag = target.tagName;
+    return (tag === "INPUT" ||
+        tag === "TEXTAREA" ||
+        tag === "SELECT" ||
+        target.isContentEditable);
+}
+
+export { clamp, isEditableTarget };