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

package/dist/components/canvas/CanvasToolbar.js

@@ -0,0 +1,35 @@
+"use client";
+import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
+import { CursorArrowRaysIcon, HandRaisedIcon, PlusIcon } from '@heroicons/react/24/outline';
+import { cn } from '../../utils/cn.js';
+import { Button } from '../core/Button/Button.js';
+import 'react';
+import { Dropdown } from '../core/Dropdown/Dropdown.js';
+import '../core/Dropdown/DropdownTrigger.js';
+import '../core/Dropdown/DropdownMenu.js';
+import '../core/Dropdown/DropdownItem.js';
+import '../core/Dropdown/DropdownSection.js';
+import '../core/Dropdown/DropdownSeparator.js';
+import '../core/Dropdown/Dropdown.theme.js';
+import { useCanvasApi } from './context/CanvasContext.js';
+
+const POSITIONS = {
+    bottom: "bottom-6 left-1/2 -translate-x-1/2",
+    top: "top-6 left-1/2 -translate-x-1/2",
+};
+const Divider = () => (jsx("span", { className: "mx-0.5 h-6 w-px bg-[var(--color-border)]", "aria-hidden": "true" }));
+/**
+ * A floating, bottom-center canvas toolbar (FigJam/tldraw style). Built-in **Select /
+ * Hand** tool toggle (drives the engine `tool` mode) and a single **"+ Add node"**
+ * trigger opening a Dropdown menu of `nodeOptions`; a `children` slot holds
+ * app-specific actions. Marked `data-flikkui-nopan` so the pane never pans or steals
+ * clicks from it (the Dropdown menu portals with `data-flikkui-portal`, same rule).
+ */
+function CanvasToolbar({ nodeOptions, onAddNode, showTools = true, position = "bottom", className, children, }) {
+    const { tool, setTool } = useCanvasApi();
+    const hasNodes = !!(nodeOptions === null || nodeOptions === void 0 ? void 0 : nodeOptions.length);
+    return (jsxs("div", { "data-flikkui-nopan": "", className: cn("absolute z-30 flex items-center gap-1 rounded-full border border-[var(--color-border)] bg-[var(--color-surface-overlay)]/60 backdrop-blur-lg p-1 shadow-real-lg", POSITIONS[position], className), children: [showTools && (jsxs(Fragment, { children: [jsx(Button, { variant: tool === "select" ? "soft" : "ghost", color: "neutral", size: "sm", iconOnly: true, onClick: () => setTool("select"), "aria-label": "Select tool", "aria-pressed": tool === "select", className: cn("rounded-full", tool === "select" && "shadow-inner"), children: jsx(CursorArrowRaysIcon, { className: "size-4" }) }), jsx(Button, { variant: tool === "pan" ? "soft" : "ghost", color: "neutral", size: "sm", iconOnly: true, onClick: () => setTool("pan"), "aria-label": "Hand (pan) tool", "aria-pressed": tool === "pan", className: cn("rounded-full", tool === "pan" && "shadow-inner"), children: jsx(HandRaisedIcon, { className: "size-4" }) })] })), showTools && hasNodes && jsx(Divider, {}), hasNodes && (jsxs(Dropdown, { placement: "top", offset: 10, onAction: (type) => onAddNode === null || onAddNode === void 0 ? void 0 : onAddNode(type), children: [jsx(Dropdown.Trigger, { children: jsxs(Button, { variant: "ghost", color: "neutral", size: "sm", className: "rounded-full gap-1.5", children: [jsx(PlusIcon, { className: "size-4" }), "Add node"] }) }), jsx(Dropdown.Menu, { "aria-label": "Add node", children: nodeOptions === null || nodeOptions === void 0 ? void 0 : nodeOptions.map((opt) => (jsx(Dropdown.Item, { itemKey: opt.type, startContent: opt.icon && (jsx("span", { className: "size-4 grid place-items-center text-[var(--color-text-muted)]", children: opt.icon })), children: opt.label }, opt.type))) })] })), children && (jsxs(Fragment, { children: [(showTools || hasNodes) && jsx(Divider, {}), children] }))] }));
+}
+CanvasToolbar.displayName = "CanvasToolbar";
+
+export { CanvasToolbar };

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

@@ -0,0 +1,32 @@
+import React from "react";
+import type { EdgeType, HandlePosition, XYPosition } from "./NodeCanvas.types";
+/** Cubic-bezier path curving out from each handle's side. */
+export declare function buildBezierPath(source: XYPosition, sourceSide: HandlePosition, target: XYPosition, targetSide: HandlePosition): string;
+/** Build an orthogonal path, optionally rounding the corners (smoothstep). */
+export declare function buildStepPath(source: XYPosition, sourceSide: HandlePosition, target: XYPosition, rounded: boolean, radius?: number): string;
+/** The on-curve midpoint of an edge (for placing the × delete button). */
+export declare function edgeMidpoint(type: EdgeType, source: XYPosition, sourceSide: HandlePosition, target: XYPosition, targetSide: HandlePosition): XYPosition;
+/** Dispatch to the routing builder for the given edge type. */
+export declare function buildEdgePath(type: EdgeType, source: XYPosition, sourceSide: HandlePosition, target: XYPosition, targetSide: HandlePosition): string;
+export interface EdgeRenderProps {
+    id?: string;
+    type?: EdgeType;
+    source: XYPosition;
+    sourcePosition: HandlePosition;
+    target: XYPosition;
+    targetPosition: HandlePosition;
+    selected?: boolean;
+    /** Stroke color override (any CSS color). Selection still strokes `--color-primary`. */
+    color?: string;
+    /** Render dashed (used for the in-progress connection ghost). */
+    dashed?: boolean;
+    /** When provided, the edge is interactive (a wide transparent hit-path is rendered). */
+    onPointerDown?: (e: React.PointerEvent) => void;
+}
+/**
+ * A single edge (bezier / step / smoothstep). Uses `vectorEffect="non-scaling-stroke"`
+ * so the line keeps a constant on-screen width at any zoom. When `onPointerDown` is
+ * set, a wide transparent hit-path makes it easy to click, and the visible stroke
+ * emphasizes on hover (via the group) and when selected.
+ */
+export declare const Edge: React.NamedExoticComponent<EdgeRenderProps>;

package/dist/components/canvas/Edge.js

@@ -0,0 +1,113 @@
+"use client";
+import { jsxs, jsx } from 'react/jsx-runtime';
+import React__default from 'react';
+import { cn } from '../../utils/cn.js';
+
+function controlPoint(p, side, dist) {
+    switch (side) {
+        case "left":
+            return { x: p.x - dist, y: p.y };
+        case "right":
+            return { x: p.x + dist, y: p.y };
+        case "top":
+            return { x: p.x, y: p.y - dist };
+        case "bottom":
+            return { x: p.x, y: p.y + dist };
+    }
+}
+/** Cubic-bezier path curving out from each handle's side. */
+function buildBezierPath(source, sourceSide, target, targetSide) {
+    const dist = Math.max(Math.hypot(target.x - source.x, target.y - source.y) * 0.4, 30);
+    const c1 = controlPoint(source, sourceSide, dist);
+    const c2 = controlPoint(target, targetSide, dist);
+    return `M ${source.x},${source.y} C ${c1.x},${c1.y} ${c2.x},${c2.y} ${target.x},${target.y}`;
+}
+/** Orthogonal waypoints routed through a mid-line based on the source handle axis. */
+function stepWaypoints(source, sourceSide, target) {
+    const horizontal = sourceSide === "left" || sourceSide === "right";
+    if (horizontal) {
+        const mx = (source.x + target.x) / 2;
+        return [source, { x: mx, y: source.y }, { x: mx, y: target.y }, target];
+    }
+    const my = (source.y + target.y) / 2;
+    return [source, { x: source.x, y: my }, { x: target.x, y: my }, target];
+}
+/** Build an orthogonal path, optionally rounding the corners (smoothstep). */
+function buildStepPath(source, sourceSide, target, rounded, radius = 8) {
+    const pts = stepWaypoints(source, sourceSide, target);
+    if (!rounded) {
+        return (`M ${pts[0].x},${pts[0].y} ` +
+            pts.slice(1).map((p) => `L ${p.x},${p.y}`).join(" "));
+    }
+    let d = `M ${pts[0].x},${pts[0].y}`;
+    for (let i = 1; i < pts.length - 1; i++) {
+        const p0 = pts[i - 1];
+        const p1 = pts[i];
+        const p2 = pts[i + 1];
+        const len1 = Math.hypot(p1.x - p0.x, p1.y - p0.y) || 1;
+        const len2 = Math.hypot(p2.x - p1.x, p2.y - p1.y) || 1;
+        const r = Math.min(radius, len1 / 2, len2 / 2);
+        const a = { x: p1.x - ((p1.x - p0.x) / len1) * r, y: p1.y - ((p1.y - p0.y) / len1) * r };
+        const b = { x: p1.x + ((p2.x - p1.x) / len2) * r, y: p1.y + ((p2.y - p1.y) / len2) * r };
+        d += ` L ${a.x},${a.y} Q ${p1.x},${p1.y} ${b.x},${b.y}`;
+    }
+    const last = pts[pts.length - 1];
+    d += ` L ${last.x},${last.y}`;
+    return d;
+}
+/** The on-curve midpoint of an edge (for placing the × delete button). */
+function edgeMidpoint(type, source, sourceSide, target, targetSide) {
+    if (type === "step" || type === "smoothstep") {
+        const pts = stepWaypoints(source, sourceSide, target);
+        return { x: (pts[1].x + pts[2].x) / 2, y: (pts[1].y + pts[2].y) / 2 };
+    }
+    // Cubic bezier evaluated at t = 0.5.
+    const dist = Math.max(Math.hypot(target.x - source.x, target.y - source.y) * 0.4, 30);
+    const c1 = controlPoint(source, sourceSide, dist);
+    const c2 = controlPoint(target, targetSide, dist);
+    return {
+        x: 0.125 * source.x + 0.375 * c1.x + 0.375 * c2.x + 0.125 * target.x,
+        y: 0.125 * source.y + 0.375 * c1.y + 0.375 * c2.y + 0.125 * target.y,
+    };
+}
+/** Dispatch to the routing builder for the given edge type. */
+function buildEdgePath(type, source, sourceSide, target, targetSide) {
+    if (type === "step")
+        return buildStepPath(source, sourceSide, target, false);
+    if (type === "smoothstep")
+        return buildStepPath(source, sourceSide, target, true);
+    return buildBezierPath(source, sourceSide, target, targetSide);
+}
+/**
+ * A single edge (bezier / step / smoothstep). Uses `vectorEffect="non-scaling-stroke"`
+ * so the line keeps a constant on-screen width at any zoom. When `onPointerDown` is
+ * set, a wide transparent hit-path makes it easy to click, and the visible stroke
+ * emphasizes on hover (via the group) and when selected.
+ */
+const Edge = React__default.memo(function Edge({ id, type = "bezier", source, sourcePosition, target, targetPosition, selected, color, dashed, onPointerDown, }) {
+    const d = buildEdgePath(type, source, sourcePosition, target, targetPosition);
+    // Inline stroke beats the class strokes below; selection keeps priority.
+    const colorStyle = color && !selected ? { stroke: color } : undefined;
+    return (jsxs("g", { className: "group", children: [onPointerDown && (jsx("path", { d: d, fill: "none", stroke: "transparent", strokeWidth: 16, strokeLinecap: "round", "data-flikkui-edge": "", "data-edge-id": id, style: { pointerEvents: "stroke", cursor: "pointer" }, onPointerDown: onPointerDown })), jsx("path", { d: d, fill: "none", strokeWidth: selected ? 8 : 6, strokeLinecap: "round", strokeLinejoin: "round", vectorEffect: "non-scaling-stroke", strokeDasharray: dashed ? "5 4" : undefined, style: colorStyle, className: cn("pointer-events-none opacity-0 transition-opacity duration-150", selected
+                    ? "opacity-20 stroke-[var(--color-primary)]"
+                    : "stroke-[var(--color-primary)] group-hover:opacity-10") }), jsx("path", { d: d, fill: "none", strokeWidth: selected ? 2.5 : 1.5, strokeLinecap: "round", strokeLinejoin: "round", vectorEffect: "non-scaling-stroke", strokeDasharray: dashed ? "5 4" : undefined, style: colorStyle, className: cn("transition-[stroke,stroke-width] duration-150", selected
+                    ? "stroke-[var(--color-primary)]"
+                    : "stroke-[var(--color-border)] group-hover:stroke-[var(--color-border-hover)]") })] }));
+}, 
+// EdgeLayer allocates fresh anchor point objects every render, so `source`/
+// `target` must be compared by value — default shallow memo would never bail.
+(prev, next) => prev.id === next.id &&
+    prev.type === next.type &&
+    prev.selected === next.selected &&
+    prev.color === next.color &&
+    prev.dashed === next.dashed &&
+    prev.onPointerDown === next.onPointerDown &&
+    prev.sourcePosition === next.sourcePosition &&
+    prev.targetPosition === next.targetPosition &&
+    prev.source.x === next.source.x &&
+    prev.source.y === next.source.y &&
+    prev.target.x === next.target.x &&
+    prev.target.y === next.target.y);
+Edge.displayName = "Edge";
+
+export { Edge, buildBezierPath, buildEdgePath, buildStepPath, edgeMidpoint };

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

@@ -0,0 +1,19 @@
+import React from "react";
+import type { ConnectionState } from "./context/ConnectionContext";
+import type { NodeCanvasEdge, NodeCanvasNode } from "./NodeCanvas.types";
+interface EdgeLayerProps {
+    nodes: NodeCanvasNode[];
+    edges: NodeCanvasEdge[];
+    connection: ConnectionState | null;
+    onSelectEdge: (id: string, additive: boolean) => void;
+    onDeleteEdge: (id: string) => void;
+}
+/**
+ * SVG layer (inside the zoom-scaled world) that draws every edge, the in-progress
+ * connection ghost, and a delete (×) button at the midpoint of hovered/selected
+ * edges. Anchors come from `node.position + handleOffset`, so edges stay locked to
+ * handles through pan / zoom / node drag. The × is counter-scaled so it stays a
+ * constant on-screen size.
+ */
+export declare const EdgeLayer: React.NamedExoticComponent<EdgeLayerProps>;
+export {};

package/dist/components/canvas/EdgeLayer.js

@@ -0,0 +1,121 @@
+"use client";
+import { jsxs, jsx } from 'react/jsx-runtime';
+import React__default, { useState, useMemo, useCallback } from 'react';
+import { edgeMidpoint, Edge } from './Edge.js';
+import { useHandleRegistry } from './context/HandleRegistry.js';
+import { useCanvasState } from './context/CanvasContext.js';
+
+const SIDE_NORMAL = {
+    top: [0, -1],
+    right: [1, 0],
+    bottom: [0, 1],
+    left: [-1, 0],
+};
+/**
+ * SVG layer (inside the zoom-scaled world) that draws every edge, the in-progress
+ * connection ghost, and a delete (×) button at the midpoint of hovered/selected
+ * edges. Anchors come from `node.position + handleOffset`, so edges stay locked to
+ * handles through pan / zoom / node drag. The × is counter-scaled so it stays a
+ * constant on-screen size.
+ */
+const EdgeLayer = React__default.memo(function EdgeLayer({ nodes, edges, connection, onSelectEdge, onDeleteEdge, }) {
+    const { handlesRef, version } = useHandleRegistry();
+    const { viewport } = useCanvasState();
+    const [hoveredEdge, setHoveredEdge] = useState(null);
+    const nodeMap = useMemo(() => new Map(nodes.map((n) => [n.id, n])), [nodes]);
+    // One stable handler for every edge (reads the id stamped on the hit path)
+    // so memo(Edge) can bail on unrelated re-renders.
+    const onEdgePointerDown = useCallback((e) => {
+        const id = e.currentTarget.getAttribute("data-edge-id");
+        if (!id)
+            return;
+        e.stopPropagation();
+        onSelectEdge(id, e.shiftKey);
+    }, [onSelectEdge]);
+    const anchorAt = (node, h) => ({
+        point: { x: node.position.x + h.offset.x, y: node.position.y + h.offset.y },
+        position: h.position,
+    });
+    /** Node center (in flow coords), derived from the 4 auto-handle side-centers. */
+    const nodeCenter = (node) => {
+        var _a;
+        const auto = ((_a = handlesRef.current.get(node.id)) !== null && _a !== void 0 ? _a : []).filter((h) => h.kind === "auto");
+        if (auto.length) {
+            const sum = auto.reduce((a, h) => ({ x: a.x + h.offset.x, y: a.y + h.offset.y }), {
+                x: 0,
+                y: 0,
+            });
+            return { x: node.position.x + sum.x / auto.length, y: node.position.y + sum.y / auto.length };
+        }
+        return { x: node.position.x + 90, y: node.position.y + 40 };
+    };
+    /**
+     * Anchor an edge end. An explicit (non-auto) `<Handle>` is honored; otherwise the
+     * edge "floats" — it anchors to whichever auto-handle side faces `toward`, so edges
+     * route cleanly and re-route as nodes move.
+     */
+    const anchorFor = (nodeId, handleId, type, toward) => {
+        var _a;
+        const node = nodeMap.get(nodeId);
+        if (!node)
+            return null;
+        const list = (_a = handlesRef.current.get(nodeId)) !== null && _a !== void 0 ? _a : [];
+        const explicit = handleId
+            ? list.find((h) => h.id === handleId && h.kind !== "auto")
+            : list.find((h) => h.type === type && h.kind !== "auto");
+        if (explicit)
+            return anchorAt(node, explicit);
+        // Float: pick the auto-handle whose side best faces the other node.
+        const auto = list.filter((h) => h.kind === "auto");
+        if (auto.length) {
+            const center = nodeCenter(node);
+            const dir = { x: toward.x - center.x, y: toward.y - center.y };
+            let best = auto[0];
+            let bestDot = -Infinity;
+            for (const h of auto) {
+                const n = SIDE_NORMAL[h.position];
+                const dot = n[0] * dir.x + n[1] * dir.y;
+                if (dot > bestDot) {
+                    bestDot = dot;
+                    best = h;
+                }
+            }
+            return anchorAt(node, best);
+        }
+        return { point: { ...node.position }, position: type === "source" ? "right" : "left" };
+    };
+    const resolveEdge = (edge) => {
+        const sNode = nodeMap.get(edge.source);
+        const tNode = nodeMap.get(edge.target);
+        if (!sNode || !tNode)
+            return null;
+        const s = anchorFor(edge.source, edge.sourceHandle, "source", nodeCenter(tNode));
+        const t = anchorFor(edge.target, edge.targetHandle, "target", nodeCenter(sNode));
+        if (!s || !t)
+            return null;
+        return { s, t };
+    };
+    let ghost = null;
+    if (connection) {
+        // Ghost source floats toward the cursor.
+        ghost = anchorFor(connection.sourceNodeId, connection.sourceHandleId, connection.sourceType, connection.to);
+    }
+    return (jsxs("svg", { className: "absolute top-0 left-0 overflow-visible pointer-events-none", style: { width: 1, height: 1 }, children: [edges.map((edge) => {
+                var _a;
+                const resolved = resolveEdge(edge);
+                if (!resolved)
+                    return null;
+                const { s, t } = resolved;
+                const showDelete = !connection && (edge.selected || hoveredEdge === edge.id);
+                const mid = showDelete
+                    ? edgeMidpoint((_a = edge.type) !== null && _a !== void 0 ? _a : "bezier", s.point, s.position, t.point, t.position)
+                    : null;
+                return (jsxs("g", { onPointerEnter: () => setHoveredEdge(edge.id), onPointerLeave: () => setHoveredEdge((h) => (h === edge.id ? null : h)), children: [jsx(Edge, { id: edge.id, type: edge.type, source: s.point, sourcePosition: s.position, target: t.point, targetPosition: t.position, selected: edge.selected, color: edge.color, onPointerDown: onEdgePointerDown }), showDelete && mid && (jsxs("g", { transform: `translate(${mid.x} ${mid.y}) scale(${1 / viewport.zoom})`, style: { pointerEvents: "auto", cursor: "pointer" }, className: "group/delete", onPointerDown: (e) => {
+                                e.stopPropagation();
+                                onDeleteEdge(edge.id);
+                            }, "aria-label": "Delete connection", children: [jsx("circle", { r: 9, className: "fill-[var(--color-surface)] stroke-[var(--color-border)] drop-shadow-sm transition-colors group-hover/delete:fill-[var(--color-danger)] group-hover/delete:stroke-[var(--color-danger)]", strokeWidth: 1 }), jsx("path", { d: "M -3 -3 L 3 3 M 3 -3 L -3 3", className: "stroke-[var(--color-danger)] transition-colors group-hover/delete:stroke-white", strokeWidth: 1.5, strokeLinecap: "round", fill: "none" })] }))] }, edge.id));
+            }), connection && ghost && (jsx(Edge, { source: ghost.point, sourcePosition: ghost.position, target: connection.to, targetPosition: connection.to.x >= ghost.point.x ? "left" : "right", dashed: true, selected: true }))] }));
+});
+EdgeLayer.displayName = "EdgeLayer";
+
+export { EdgeLayer };

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

@@ -0,0 +1,11 @@
+import type { HandleProps } from "./NodeCanvas.types";
+/**
+ * A connection port, declared inside a custom node. Registers its center offset
+ * (in flow coords, relative to the node) so edges and connection drags anchor to
+ * `node.position + offset` — stable under pan/zoom/drag. Measured once after
+ * render and again only when the node's size changes.
+ */
+export declare function Handle({ type, id, position, isConnectable, className, style, children, }: HandleProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace Handle {
+    var displayName: string;
+}

package/dist/components/canvas/Handle.js

@@ -0,0 +1,64 @@
+"use client";
+import { jsx } from 'react/jsx-runtime';
+import { useRef, useEffect } from 'react';
+import { cn } from '../../utils/cn.js';
+import { useNodeId } from './context/NodeIdContext.js';
+import { useHandleRegistry, handleKey } from './context/HandleRegistry.js';
+import { useCanvasApi } from './context/CanvasContext.js';
+import { useConnection } from './hooks/useConnection.js';
+
+const 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",
+};
+/**
+ * A connection port, declared inside a custom node. Registers its center offset
+ * (in flow coords, relative to the node) so edges and connection drags anchor to
+ * `node.position + offset` — stable under pan/zoom/drag. Measured once after
+ * render and again only when the node's size changes.
+ */
+function Handle({ type, id, position = type === "source" ? "right" : "left", isConnectable = true, className, style, children, }) {
+    const nodeId = useNodeId();
+    const ref = useRef(null);
+    const { register, unregister } = useHandleRegistry();
+    const { viewportRef, locked } = useCanvasApi();
+    const { onPointerDown } = useConnection({ nodeId, handleId: id, type });
+    const connectable = isConnectable && !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,
+                type,
+                position,
+                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(type, id));
+        };
+    }, [nodeId, id, type, position, register, unregister, viewportRef]);
+    return (jsx("div", { ref: ref, "data-flikkui-handle": "", "data-node-id": nodeId, "data-handle-type": type, "data-handle-id": id !== null && id !== void 0 ? id : "", className: cn("nodrag absolute z-10", children
+            ? "grid place-items-center"
+            : "size-3 rounded-full border-2 bg-[var(--color-surface)] border-[var(--color-primary)]", SIDE_CLASSES[position], connectable ? "cursor-crosshair" : "opacity-50", className), style: style, onPointerDown: connectable ? onPointerDown : undefined, children: children }));
+}
+Handle.displayName = "Handle";
+
+export { Handle };

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

@@ -0,0 +1,22 @@
+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 MiniMapProps {
+    position?: keyof typeof POSITIONS;
+    width?: number;
+    height?: number;
+    className?: string;
+}
+/**
+ * Overview map: all nodes + the current viewport rectangle, scaled to fit. Click or
+ * drag inside it to recenter the canvas on that point. Pane-level chrome (`z-20`),
+ * opted out of canvas panning via `data-flikkui-nopan`.
+ */
+export declare function MiniMap({ position, width, height, className, }: MiniMapProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace MiniMap {
+    var displayName: string;
+}
+export {};

package/dist/components/canvas/MiniMap.js

@@ -0,0 +1,106 @@
+"use client";
+import { jsx, jsxs } from 'react/jsx-runtime';
+import { useRef } from 'react';
+import { cn } from '../../utils/cn.js';
+import { useNodeCanvasContext } from './context/CanvasContext.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",
+};
+/** Estimated node footprint (node sizes aren't measured yet — issue 4 fast-follow). */
+const NODE_W = 180;
+const NODE_H = 80;
+const PADDING = 40;
+/**
+ * Overview map: all nodes + the current viewport rectangle, scaled to fit. Click or
+ * drag inside it to recenter the canvas on that point. Pane-level chrome (`z-20`),
+ * opted out of canvas panning via `data-flikkui-nopan`.
+ */
+function MiniMap({ position = "bottom-left", width = 200, height = 140, className, }) {
+    var _a, _b;
+    const { nodes, viewport, setViewport, paneRef } = useNodeCanvasContext();
+    const svgRef = useRef(null);
+    const dragging = useRef(false);
+    const pane = paneRef.current;
+    const paneW = (_a = pane === null || pane === void 0 ? void 0 : pane.clientWidth) !== null && _a !== void 0 ? _a : 0;
+    const paneH = (_b = pane === null || pane === void 0 ? void 0 : pane.clientHeight) !== null && _b !== void 0 ? _b : 0;
+    // Current viewport rectangle in flow coords.
+    const vx = -viewport.x / viewport.zoom;
+    const vy = -viewport.y / viewport.zoom;
+    const vw = paneW / viewport.zoom;
+    const vh = paneH / viewport.zoom;
+    // Bounds = union of node bounds and the viewport rect, padded.
+    let minX = vx;
+    let minY = vy;
+    let maxX = vx + vw;
+    let maxY = vy + vh;
+    for (const n of nodes) {
+        minX = Math.min(minX, n.position.x);
+        minY = Math.min(minY, n.position.y);
+        maxX = Math.max(maxX, n.position.x + NODE_W);
+        maxY = Math.max(maxY, n.position.y + NODE_H);
+    }
+    minX -= PADDING;
+    minY -= PADDING;
+    maxX += PADDING;
+    maxY += PADDING;
+    const bw = Math.max(maxX - minX, 1);
+    const bh = Math.max(maxY - minY, 1);
+    const scale = Math.min(width / bw, height / bh);
+    const ox = (width - bw * scale) / 2;
+    const oy = (height - bh * scale) / 2;
+    const toMM = (x, y) => ({
+        x: (x - minX) * scale + ox,
+        y: (y - minY) * scale + oy,
+    });
+    const recenter = (clientX, clientY) => {
+        var _a;
+        const r = (_a = svgRef.current) === null || _a === void 0 ? void 0 : _a.getBoundingClientRect();
+        if (!r)
+            return;
+        const flowX = (clientX - r.left - ox) / scale + minX;
+        const flowY = (clientY - r.top - oy) / scale + minY;
+        setViewport((v) => ({
+            zoom: v.zoom,
+            x: paneW / 2 - flowX * v.zoom,
+            y: paneH / 2 - flowY * v.zoom,
+        }));
+    };
+    const onPointerDown = (e) => {
+        var _a;
+        e.stopPropagation();
+        dragging.current = true;
+        recenter(e.clientX, e.clientY);
+        try {
+            (_a = svgRef.current) === null || _a === void 0 ? void 0 : _a.setPointerCapture(e.pointerId);
+        }
+        catch (_b) {
+            /* pointer inactive — drag still tracked via pointermove */
+        }
+    };
+    const onPointerMove = (e) => {
+        if (dragging.current)
+            recenter(e.clientX, e.clientY);
+    };
+    const onPointerUp = (e) => {
+        var _a;
+        dragging.current = false;
+        try {
+            (_a = svgRef.current) === null || _a === void 0 ? void 0 : _a.releasePointerCapture(e.pointerId);
+        }
+        catch (_b) {
+            /* noop */
+        }
+    };
+    const view = toMM(vx, vy);
+    return (jsx("div", { "data-flikkui-nopan": "", className: cn("absolute z-20 overflow-hidden rounded-lg border border-[var(--color-border)] bg-[var(--color-surface-overlay)] shadow-md", POSITIONS[position], className), style: { width, height }, children: jsxs("svg", { ref: svgRef, width: width, height: height, className: "cursor-pointer touch-none", onPointerDown: onPointerDown, onPointerMove: onPointerMove, onPointerUp: onPointerUp, children: [nodes.map((n) => {
+                    const p = toMM(n.position.x, n.position.y);
+                    return (jsx("rect", { x: p.x, y: p.y, width: NODE_W * scale, height: NODE_H * scale, rx: 2, className: cn(n.selected ? "fill-[var(--color-primary)]" : "fill-[var(--color-border)]") }, n.id));
+                }), jsx("rect", { x: view.x, y: view.y, width: vw * scale, height: vh * scale, className: "fill-[var(--color-primary)]/10 stroke-[var(--color-primary)]", strokeWidth: 1.5 })] }) }));
+}
+MiniMap.displayName = "MiniMap";
+
+export { MiniMap };

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

@@ -0,0 +1,10 @@
+import React from "react";
+import type { NodeCanvasProps } from "./NodeCanvas.types";
+/**
+ * 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.
+ */
+export declare const NodeCanvas: React.ForwardRefExoticComponent<NodeCanvasProps & React.RefAttributes<HTMLDivElement>>;