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

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,40 @@
+import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
+import { PlusIcon, MinusIcon, ArrowsPointingOutIcon, LockClosedIcon, LockOpenIcon } from '@heroicons/react/24/outline';
+import { cn } from '../../utils/cn.js';
+import { Button } from '../core/Button/Button.js';
+import 'react';
+import { useNodeCanvasContext } 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 } = useNodeCanvasContext();
+    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: "neutral", size: "sm", iconOnly: true, className: ctrlBtn, onClick: () => zoomBy(zoomStep), "aria-label": "Zoom in", children: jsx(PlusIcon, { className: "size-4" }) }), jsx(Button, { variant: "ghost", color: "neutral", size: "sm", iconOnly: true, className: ctrlBtn, onClick: () => zoomBy(1 / zoomStep), "aria-label": "Zoom out", children: jsx(MinusIcon, { className: "size-4" }) })] })), showFitView && (jsx(Button, { variant: "ghost", color: "neutral", size: "sm", iconOnly: true, className: ctrlBtn, onClick: () => fitView(), "aria-label": "Fit view", children: jsx(ArrowsPointingOutIcon, { className: "size-4" }) })), showLock && (jsx(Button, { variant: locked ? "soft" : "ghost", color: locked ? "primary" : "neutral", size: "sm", iconOnly: true, className: ctrlBtn, onClick: () => setLocked(!locked), "aria-label": locked ? "Unlock canvas" : "Lock canvas", "aria-pressed": locked, children: locked ? jsx(LockClosedIcon, { className: "size-4" }) : jsx(LockOpenIcon, { className: "size-4" }) }))] }));
+}
+NodeControls.displayName = "NodeControls";
+
+export { NodeControls };

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

@@ -0,0 +1,19 @@
+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.
+ */
+export declare function NodeRenderer({ nodes, nodeTypes, autoConnect, onNodeChanges, onSelectNode, onNodeClick, }: NodeRendererProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/canvas/NodeRenderer.js

@@ -0,0 +1,117 @@
+import { jsx, Fragment, jsxs } from 'react/jsx-runtime';
+import { useCallback, useRef, useEffect } from 'react';
+import { PlusIcon } from '@heroicons/react/16/solid';
+import { cn } from '../../utils/cn.js';
+import { NodeIdProvider } from './context/NodeIdContext.js';
+import { useNodeCanvasContext } 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.
+ */
+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));
+        }) }));
+}
+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 } = useNodeCanvasContext();
+    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-white 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(PlusIcon, { className: "size-2.5" }) }));
+}
+function NodeWrapper({ node, NodeComponent, autoConnect, emit, onSelect, onNodeClick, }) {
+    const { tool } = useNodeCanvasContext();
+    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)))] }) }));
+}
+
+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/context/CanvasContext.d.ts

@@ -0,0 +1,32 @@
+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";
+export declare const CanvasProvider: React.Provider<CanvasContextValue | undefined>;
+/** Access the canvas viewport + coordinate transforms. Throws outside `<NodeCanvas>`. */
+export declare function useNodeCanvasContext(): CanvasContextValue;

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

@@ -0,0 +1,14 @@
+import { createContext, useContext } from 'react';
+
+const CanvasContext = createContext(undefined);
+const CanvasProvider = CanvasContext.Provider;
+/** Access the canvas viewport + coordinate transforms. Throws outside `<NodeCanvas>`. */
+function useNodeCanvasContext() {
+    const ctx = useContext(CanvasContext);
+    if (!ctx) {
+        throw new Error("NodeCanvas compound parts must be used within <NodeCanvas>");
+    }
+    return ctx;
+}
+
+export { CanvasProvider, 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,13 @@
+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;

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

@@ -0,0 +1,15 @@
+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,14 @@
+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,15 @@
+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,29 @@
+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,91 @@
+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 };