@elabs-ai/components-flow 4.0.0

package/dist/index.d.ts

@@ -0,0 +1,634 @@
+import * as react from 'react';
+import { ReactNode, SVGAttributes } from 'react';
+import { Node, Edge, ReactFlowProps, NodeProps, EdgeProps, Position, NodeChange, MiniMapProps, PanelPosition } from '@xyflow/react';
+export { Background, Connection, Controls, Edge, EdgeProps, MiniMap, Node, NodeProps, Panel, Position, ReactFlow, ReactFlowProvider, addEdge, useEdgesState, useNodesState, useReactFlow } from '@xyflow/react';
+
+interface CanvasShellProps<NodeType extends Node = Node, EdgeType extends Edge = Edge> extends ReactFlowProps<NodeType, EdgeType> {
+    /** Render a branded dotted background grid. Defaults to true. */
+    background?: boolean;
+    /**
+     * Enable alignment guides + snapping while a single node is dragged. Off by
+     * default; when false, CanvasShell behaves exactly as before. When true,
+     * CanvasShell wires `useHelperLines` around your `onNodesChange` and renders
+     * the `<HelperLines>` overlay internally — pass `nodes` + `onNodesChange`
+     * (the standard controlled setup, e.g. via `useNodesState`). For full control
+     * use the exported `useHelperLines` + `<HelperLines>` directly.
+     */
+    helperLines?: boolean;
+    /** Overlays rendered inside the flow (ZoomControls, Legend, Panels). */
+    children?: ReactNode;
+    className?: string;
+}
+/**
+ * Branded React Flow canvas. Sets a token-driven background + sensible
+ * defaults; pass nodes/edges/handlers through as normal React Flow props.
+ *
+ * Consumers MUST import the React Flow stylesheet once at the app root:
+ *   import "@xyflow/react/dist/style.css";
+ *
+ * Children render inside the flow context, so <ZoomControls /> and React Flow
+ * <Panel>s work when placed here.
+ */
+declare function CanvasShell<NodeType extends Node = Node, EdgeType extends Edge = Edge>({ helperLines, ...props }: CanvasShellProps<NodeType, EdgeType>): react.JSX.Element;
+
+/** A node side that can carry a handle. Doubles as the handle's stable id. */
+type FlowHandleSide = "top" | "right" | "bottom" | "left";
+/**
+ * Which sides of a node expose source and/or target handles. When omitted,
+ * `FlowNode` keeps its default single top **target** + bottom **source**. When
+ * set, a `<Handle>` is rendered on each listed side with a **stable id equal to
+ * the side name** (`"top" | "right" | "bottom" | "left"`), addressable per
+ * handle type — so edges (e.g. `FlowSmartEdge`) can pick a specific anchor.
+ */
+interface FlowNodeHandles {
+    /** Sides exposing a source handle (handle `id` === side). */
+    source?: FlowHandleSide[];
+    /** Sides exposing a target handle (handle `id` === side). */
+    target?: FlowHandleSide[];
+}
+/**
+ * A `FlowNodeHandles` config exposing source **and** target anchors on all four
+ * sides. The recommended setup for `FlowSmartEdge` / `FlowFloatingEdge`: with
+ * anchors on every side, an edge connects on whichever side **faces** the other
+ * node (left/right when side-by-side, top/bottom when stacked) instead of always
+ * top/bottom. Spread onto a node's `data.handles`.
+ */
+declare const FLOW_ALL_SIDE_HANDLES: FlowNodeHandles;
+interface FlowNodeData extends Record<string, unknown> {
+    title: string;
+    subtitle?: string;
+    /** Short type label shown as an eyebrow, e.g. "Source", "Transform". */
+    kind?: string;
+    icon?: ReactNode;
+    tone?: "default" | "accent" | "success" | "warning" | "destructive";
+    /**
+     * Optional multi-side handle configuration. Absent → default top-target /
+     * bottom-source (unchanged, backward-compatible).
+     */
+    handles?: FlowNodeHandles;
+}
+type BrandFlowNode = Node<FlowNodeData, "brand">;
+/**
+ * Branded custom node. Register it in `nodeTypes={{ brand: FlowNode }}` and
+ * create nodes with `type: "brand"` and `data: FlowNodeData`.
+ */
+declare function FlowNode({ data, selected, sourcePosition, targetPosition, }: NodeProps<BrandFlowNode>): react.JSX.Element;
+
+/**
+ * Branded bezier edge using the `--flow-edge` token. Register it in
+ * `edgeTypes={{ brand: FlowEdge }}` and create edges with `type: "brand"`.
+ */
+declare function FlowEdge({ id, sourceX, sourceY, targetX, targetY, sourcePosition, targetPosition, markerEnd, style, }: EdgeProps): react.JSX.Element;
+
+/**
+ * Branded edge that picks the closest source/target handle pair (from a node's
+ * multi-side `FlowNodeHandles` config) and routes a bezier between them. Anchors
+ * are recomputed every render, so they flip as nodes are dragged. Register it in
+ * `edgeTypes={{ smart: FlowSmartEdge }}` and give the connected nodes a
+ * `data.handles` config. Uses the `--flow-edge` token, matching `FlowEdge`.
+ */
+declare function FlowSmartEdge({ id, source, target, markerEnd, style }: EdgeProps): react.JSX.Element | null;
+
+/** Axis-aligned node rectangle in absolute flow coordinates. */
+interface NodeRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** All four candidate handle sides, in a stable order. */
+declare const HANDLE_SIDES: FlowHandleSide[];
+/** Maps a handle side to the React Flow `Position` used for bezier control. */
+declare const sideToPosition: Record<FlowHandleSide, Position>;
+/** Absolute coordinate of a handle on the given side (the side's midpoint). */
+declare function handlePoint(rect: NodeRect, side: FlowHandleSide): {
+    x: number;
+    y: number;
+};
+/** The chosen source/target handle pair plus their absolute anchor points. */
+interface ClosestHandles {
+    sourceSide: FlowHandleSide;
+    targetSide: FlowHandleSide;
+    sx: number;
+    sy: number;
+    tx: number;
+    ty: number;
+}
+/**
+ * Picks the source/target handle pair (one handle per node) with the shortest
+ * straight-line distance between their anchor points. Empty side lists fall
+ * back to all four sides so an edge always resolves to a pair.
+ */
+declare function pickClosestHandles(source: NodeRect, sourceSides: FlowHandleSide[], target: NodeRect, targetSides: FlowHandleSide[]): ClosestHandles;
+
+/** Optional per-edge `data` for {@link FlowFloatingEdge}. */
+interface FloatingEdgeData {
+    /**
+     * Show a small anchor dot at each border connection point. On by default so the
+     * edge visibly terminates on the node's closest side (rather than a bare line
+     * touching the border with no anchor). Set `false` to hide.
+     */
+    anchors?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Branded floating edge: it attaches to the node **border** at the point facing
+ * the other node (no fixed handle), recomputed as nodes drag. Register it in
+ * `edgeTypes={{ floating: FlowFloatingEdge }}`; the connected nodes need no
+ * handle config. Uses the `--flow-edge` token, matching `FlowEdge`.
+ *
+ * A small **anchor dot** is drawn at each connection point (on by default) so the
+ * line clearly terminates on the node's closest border side — not at a bare,
+ * unanchored spot. Toggle per edge with `data.anchors: false`.
+ */
+declare function FlowFloatingEdge({ id, source, target, markerEnd, style, data }: EdgeProps): react.JSX.Element | null;
+
+/**
+ * The minimal live node geometry `getEdgeParams` needs. A React Flow
+ * `InternalNode` satisfies this structurally (`internals.positionAbsolute` +
+ * `measured`), so you can pass one directly; tests can pass a plain fake.
+ */
+interface FloatingNodeGeometry {
+    internals: {
+        positionAbsolute: {
+            x: number;
+            y: number;
+        };
+    };
+    measured: {
+        width?: number;
+        height?: number;
+    };
+}
+/** Border anchor points + `Position`s for a floating edge between two nodes. */
+interface EdgeParams {
+    sx: number;
+    sy: number;
+    tx: number;
+    ty: number;
+    sourcePos: Position;
+    targetPos: Position;
+}
+/**
+ * Computes where a floating edge attaches to each node's border — the
+ * intersection of the center-to-center line with each rectangle — plus the
+ * border `Position`. Recompute per render so anchors track dragging nodes.
+ */
+declare function getEdgeParams(source: FloatingNodeGeometry, target: FloatingNodeGeometry): EdgeParams;
+
+interface FlowPlaceholderNodeData extends Record<string, unknown> {
+    /** Label rendered inside the placeholder. @default "Add node" */
+    label?: string;
+    /** Called when the placeholder is activated (click, Enter, or Space). */
+    onActivate?: () => void;
+}
+type BrandFlowPlaceholderNode = Node<FlowPlaceholderNodeData, "placeholder">;
+/**
+ * Dashed, muted "add here" node — a clickable affordance that grows the
+ * graph. Register it in `nodeTypes={{ placeholder: FlowPlaceholderNode }}`
+ * and create nodes with `type: "placeholder"` and `data: FlowPlaceholderNodeData`.
+ *
+ * Renders a real `<button>` (keyboard-activatable via native Enter/Space) with
+ * an `aria-label`, and a single **target** `<Handle>` (top) so an existing
+ * edge can point at it. Fires `data.onActivate?.()` on activation — the
+ * typical handler converts the placeholder into a real `FlowNode` and grows a
+ * fresh placeholder beneath it (see the "Placeholder tail" story).
+ */
+declare function FlowPlaceholderNode({ data }: NodeProps<BrandFlowPlaceholderNode>): react.JSX.Element;
+
+interface FlowButtonEdgeData extends Record<string, unknown> {
+    /** aria-label for the insert button. @default "Insert node on edge" */
+    label?: string;
+    /** Called when the edge's "+" button is activated (click, Enter, or Space). */
+    onInsert?: () => void;
+}
+type BrandFlowButtonEdge = Edge<FlowButtonEdgeData, "button">;
+/**
+ * Branded bezier edge (matching `FlowEdge`'s `--flow-edge` token) with a
+ * centered "+" button rendered via `EdgeLabelRenderer` at the edge midpoint.
+ * Register it in `edgeTypes={{ button: FlowButtonEdge }}` and create edges
+ * with `type: "button"` and `data: FlowButtonEdgeData`.
+ *
+ * The button is a real `<button>` with an `aria-label`, keyboard-activatable
+ * via native Enter/Space. Fires `data.onInsert?.()` on activation — the
+ * typical handler splits the edge: insert a new node between source and
+ * target and rewire the two edges (see the "Insert between" story).
+ */
+declare function FlowButtonEdge({ id, sourceX, sourceY, targetX, targetY, sourcePosition, targetPosition, markerEnd, style, data, }: EdgeProps<BrandFlowButtonEdge>): react.JSX.Element;
+
+/** Direction dagre lays the graph out in — top-to-bottom, left-to-right, etc. */
+type FlowLayoutDirection = "TB" | "LR" | "BT" | "RL";
+interface FlowLayoutOptions {
+    /** Layout direction. @default "TB" */
+    direction?: FlowLayoutDirection;
+    /** Gap between nodes in the same rank (dagre `nodesep`). @default 48 */
+    nodeSpacing?: number;
+    /** Gap between ranks (dagre `ranksep`). @default 72 */
+    rankSpacing?: number;
+}
+interface FlowLayoutResult<NodeType extends Node = Node, EdgeType extends Edge = Edge> {
+    nodes: NodeType[];
+    edges: EdgeType[];
+}
+/**
+ * Pure dagre-powered auto layout. Computes new `position`s for `nodes` given
+ * `edges` — no React, no side effects, safe to call anywhere (including
+ * outside a component or in a test).
+ *
+ * Respects each node's **measured** size (`node.measured` — how React Flow
+ * v12 reports actual rendered dimensions), falling back to `node.width`/
+ * `node.height`, then a sensible default. Node identity and `data` are left
+ * untouched — only `position` changes.
+ *
+ * Pair with `useFlowLayout` to apply the result to a live canvas.
+ */
+declare function layoutFlow<NodeType extends Node = Node, EdgeType extends Edge = Edge>(nodes: NodeType[], edges: EdgeType[], options?: FlowLayoutOptions): FlowLayoutResult<NodeType, EdgeType>;
+
+interface UseFlowLayoutResult {
+    /**
+     * Auto-lay-out the current nodes/edges with dagre and fit the view. Safe to
+     * call repeatedly (e.g. from a toolbar button on every click). No-ops until
+     * React Flow has measured every node.
+     */
+    layout: (direction?: FlowLayoutDirection, options?: Omit<FlowLayoutOptions, "direction">) => void;
+    /** Whether nodes are measured and ready to be laid out. */
+    ready: boolean;
+    /** Whether a layout pass is currently running (true only for the duration of `layout()`). */
+    layouting: boolean;
+}
+/**
+ * Hook form of `layoutFlow`. Reads the live nodes/edges from `useReactFlow()`,
+ * waits for `useNodesInitialized()` so real (measured) node sizes are used —
+ * never lays out against 0×0 unmeasured nodes — applies the computed
+ * positions via `setNodes`, then calls `fitView()`.
+ *
+ * Must be called from a component rendered inside a `<CanvasShell>` /
+ * `<ReactFlow>` (React Flow context).
+ */
+declare function useFlowLayout<NodeType extends Node = Node, EdgeType extends Edge = Edge>(): UseFlowLayoutResult;
+
+/** Which generic graph-geometry algorithm `layoutGraph` should run. */
+type LayoutAlgorithm = "concentric" | "force" | "layered-lr" | "grid";
+/** Horizontal/vertical gap used by the `"grid"` and `"layered-lr"` algorithms. */
+interface LayoutSpacing {
+    x: number;
+    y: number;
+}
+interface LayoutOptions {
+    /** Which layout algorithm to run. */
+    algorithm: LayoutAlgorithm;
+    /**
+     * `"concentric"` only — the focal node placed at the origin. Defaults to the
+     * highest-degree node when omitted (or when the id doesn't match a node).
+     */
+    centerId?: string;
+    /** `"concentric"` only — radius of ring 1; ring N sits at `N × ringRadius`. @default 180 */
+    ringRadius?: number;
+    /** `"force"` only — number of synchronous simulation ticks to run. @default 300 */
+    iterations?: number;
+    /** `"grid"` / `"layered-lr"` — gap between nodes. @default {x:200,y:120} for grid. */
+    spacing?: LayoutSpacing;
+    /** Resolve a node's size by id. Falls back to `measured`/`width`/`height`/a sensible default. */
+    nodeSize?: (id: string) => {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Pure graph-geometry auto layout. Computes new `position`s for `nodes` given
+ * `edges` and a `LayoutAlgorithm` — no React, no DOM, no side effects, safe to
+ * call anywhere (including outside a component or in a test). Deterministic:
+ * identical `nodes`/`edges`/`options` always produce identical positions.
+ *
+ * Node identity and `data` are left untouched — only `position` changes.
+ * Pair with `useAutoLayout` for a memoized hook form.
+ *
+ * - `"layered-lr"` delegates to the dagre-powered `layoutFlow` (direction `"LR"`).
+ * - `"concentric"` places `centerId` (or the highest-degree node) at the
+ *   origin, with BFS shells at `ring × ringRadius`; disconnected nodes land in
+ *   one extra outer ring so positions are never `NaN`.
+ * - `"force"` runs `d3-force` synchronously for a fixed number of `iterations`,
+ *   seeded on a circle by index (no randomness) so runs are reproducible.
+ * - `"grid"` lays nodes out row-major using `spacing`.
+ */
+declare function layoutGraph<NodeType extends Node = Node, EdgeType extends Edge = Edge>(nodes: NodeType[], edges: EdgeType[], options: LayoutOptions): NodeType[];
+
+/**
+ * Memoized `layoutGraph` — pure graph-geometry layout (no live canvas access,
+ * no side effects). Recomputes only when `nodes`, `edges`, or `options`
+ * change; pass stable references (e.g. from `useNodesState`/`useEdgesState`
+ * and a memoized `options` object) to avoid recomputing every render.
+ *
+ * Use this when you want laid-out nodes to render with (e.g. feeding
+ * `useNodesState`'s initial value, or a derived/read-only view). To apply a
+ * layout to a *live* React Flow instance (read current nodes, set them back,
+ * fit the view), call `layoutGraph` directly from an event handler instead —
+ * see the `LayoutGraph` story.
+ */
+declare function useAutoLayout<NodeType extends Node = Node, EdgeType extends Edge = Edge>(nodes: NodeType[], edges: EdgeType[], options: LayoutOptions): NodeType[];
+
+/**
+ * Pure alignment-guide geometry for the helper-lines feature.
+ *
+ * Implemented fresh from the documented "helper lines" behaviour (the React Flow
+ * Pro example is paid — only the concept is reused): while a single node drags,
+ * compare its left / horizontal-center / right against every other node's
+ * left / center / right (and top / middle / bottom on the vertical axis). When a
+ * pair falls within `threshold` flow-coordinate pixels, record the guide's
+ * absolute coordinate and the snapped top-left position for the dragged node.
+ *
+ * Everything here is a pure function of plain rectangles so it is unit-testable
+ * without a live React Flow instance.
+ */
+/** A node's bounding box in absolute flow coordinates (top-left origin). */
+interface HelperLineRect {
+    /** Left edge (top-left x) in flow coordinates. */
+    x: number;
+    /** Top edge (top-left y) in flow coordinates. */
+    y: number;
+    width: number;
+    height: number;
+}
+interface HelperLinesResult {
+    /** New top-left x for the dragged node once snapped to the vertical guide. */
+    snapX?: number;
+    /** New top-left y for the dragged node once snapped to the horizontal guide. */
+    snapY?: number;
+    /** Absolute flow-x of the active vertical guide line, if any. */
+    vertical?: number;
+    /** Absolute flow-y of the active horizontal guide line, if any. */
+    horizontal?: number;
+}
+/**
+ * Compute the closest vertical + horizontal alignment guides (and the snapped
+ * position) for a dragged rectangle against the other rectangles.
+ *
+ * @param dragged   the dragged node's proposed bounding box (flow coordinates)
+ * @param others    every other node's bounding box
+ * @param threshold max distance (flow px) at which alignment engages; a pair at
+ *                  exactly `threshold` does NOT match (strict boundary)
+ */
+declare function getHelperLines(dragged: HelperLineRect, others: Iterable<HelperLineRect>, threshold?: number): HelperLinesResult;
+
+interface UseHelperLinesOptions {
+    /** Alignment threshold in flow coordinates. Defaults to 5. */
+    threshold?: number;
+}
+interface UseHelperLinesResult<NodeType extends Node = Node> {
+    /**
+     * Drop-in replacement for the consumer's `onNodesChange`: it snaps a dragged
+     * node onto any near-aligned edge/center, then forwards the (mutated) changes
+     * to the wrapped handler.
+     */
+    onNodesChange: (changes: NodeChange<NodeType>[]) => void;
+    /** Absolute flow-y of the active horizontal guide, or `undefined`. */
+    helperLineHorizontal: number | undefined;
+    /** Absolute flow-x of the active vertical guide, or `undefined`. */
+    helperLineVertical: number | undefined;
+}
+/**
+ * Decorate a consumer's `onNodesChange` with alignment guides + snapping.
+ *
+ * While a **single** node is dragged, the returned handler compares its
+ * left/center/right and top/middle/bottom against every other node; when a pair
+ * is within `threshold` flow px it (a) snaps the dragged node's position change
+ * onto the guide and (b) exposes the guide coordinates so `<HelperLines>` can
+ * draw them. Guides clear when the drag ends or nothing aligns.
+ *
+ * Must be called inside a React Flow context (a `<ReactFlowProvider>` or a
+ * component rendered under `<ReactFlow>`), since it reads the live node store.
+ *
+ * @example
+ *   const [nodes, , onNodesChange] = useNodesState(initialNodes);
+ *   const { onNodesChange: handle, helperLineHorizontal, helperLineVertical } =
+ *     useHelperLines(onNodesChange);
+ *   // <ReactFlow onNodesChange={handle}>
+ *   //   <HelperLines horizontal={helperLineHorizontal} vertical={helperLineVertical} />
+ */
+declare function useHelperLines<NodeType extends Node = Node>(onNodesChange?: (changes: NodeChange<NodeType>[]) => void, options?: UseHelperLinesOptions): UseHelperLinesResult<NodeType>;
+
+interface HelperLinesProps extends SVGAttributes<SVGSVGElement> {
+    /** Absolute flow-y of the horizontal guide (from `useHelperLines`). */
+    horizontal?: number;
+    /** Absolute flow-x of the vertical guide (from `useHelperLines`). */
+    vertical?: number;
+}
+/**
+ * Decorative alignment-guide overlay. Draws a full-width horizontal line at
+ * `horizontal` and/or a full-height vertical line at `vertical`, coloured with
+ * the `--flow-helper-line` token. It reads the live viewport transform
+ * (zoom + pan) so the guides sit on the real alignment position when the canvas
+ * is zoomed or panned.
+ *
+ * Render as a child of `<CanvasShell>` / `<ReactFlow>` (it must be inside the
+ * flow context to read the viewport). Purely decorative — hidden from AT.
+ */
+declare const HelperLines: react.ForwardRefExoticComponent<HelperLinesProps & react.RefAttributes<SVGSVGElement>>;
+
+type FlowMiniMapProps<NodeType extends Node = Node> = MiniMapProps<NodeType>;
+/**
+ * Branded preset over React Flow's `<MiniMap>` — sources node/mask colors from
+ * the `--flow-minimap-*` tokens so the overview stays theme-aware (the raw
+ * `MiniMap` re-export defaults to library colors and renders theme-blind,
+ * especially under a low-chroma theme). Every prop can still be overridden; render
+ * inside a `<CanvasShell>` (it needs the React Flow context via `useStore`).
+ */
+declare function FlowMiniMap<NodeType extends Node = Node>({ className, nodeColor, nodeStrokeColor, maskColor, ...props }: FlowMiniMapProps<NodeType>): react.JSX.Element;
+
+interface InspectorPanelProps {
+    title?: ReactNode;
+    children: ReactNode;
+    onClose?: () => void;
+    /** Empty-state shown when nothing is selected. */
+    emptyMessage?: ReactNode;
+    /** When false, render the empty state instead of children. */
+    hasSelection?: boolean;
+    /**
+     * Stable identity of the current selection (e.g. the selected node's id).
+     * When it changes, the body replays a quick fade so it reads as "details for
+     * THIS node". Pass the selected entity's id (or any stable key derived from
+     * the selected data).
+     */
+    selectionKey?: string | number;
+    /**
+     * Collapse (research 09 step 3 — converged on the shared `@elabs-ai/components-ui`
+     * `useCollapsiblePanel` base; the panel stays single-view, drill-in is
+     * ContextPanel-only). Controlled `open` / uncontrolled `defaultOpen`.
+     */
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Which edge the panel sits on (collapse slide direction). Default `"right"`. */
+    side?: "left" | "right";
+    /** Expanded width (any CSS length). Default `"18rem"` (the original `w-72`). */
+    width?: string;
+    className?: string;
+}
+/**
+ * Properties panel for the selected node/edge. Reusable beside a canvas (e.g.
+ * inside a <SplitPanel>) or as a React Flow <Panel>. Always mounted; collapses
+ * via the canonical `useCollapsiblePanel` width tween (CSS-gated, reduced-
+ * motion safe) when `open`/`defaultOpen` drive it.
+ */
+declare function InspectorPanel({ title, children, onClose, emptyMessage, hasSelection, selectionKey, open, defaultOpen, onOpenChange, side, width, className, }: InspectorPanelProps): react.JSX.Element;
+
+interface LegendItem {
+    label: string;
+    /** Any CSS color or token reference, e.g. "var(--chart-1)". */
+    color: string;
+}
+interface LegendProps {
+    items: LegendItem[];
+    title?: string;
+    className?: string;
+}
+/** Small legend mapping colors/types to labels for a canvas or chart. */
+declare function Legend({ items, title, className }: LegendProps): react.JSX.Element;
+
+interface ZoomControlsProps {
+    position?: PanelPosition;
+    className?: string;
+}
+/** Branded zoom in / out / fit controls. Render inside <CanvasShell>. */
+declare function ZoomControls({ position, className }: ZoomControlsProps): react.JSX.Element;
+
+/** Visual accent for a group container. */
+type FlowGroupTone = "default" | "accent" | "success" | "warning" | "destructive";
+interface FlowGroupNodeData extends Record<string, unknown> {
+    /** Header label for the group. */
+    title: string;
+    /** Optional leading glyph (a Lucide icon element, etc.). */
+    icon?: ReactNode;
+    /**
+     * Whether the group is collapsed to an overview chip. Managed by
+     * `useFlowGroups().collapseGroup` / `expandGroup`; the header toggle flips it.
+     */
+    collapsed?: boolean;
+    /**
+     * Fallback count shown next to the title. When omitted, the node counts its
+     * live direct children from the store, so the badge stays accurate as nodes
+     * are added or removed.
+     */
+    childCount?: number;
+    /** Accent tone for the header rule + count badge. */
+    tone?: FlowGroupTone;
+}
+type BrandFlowGroupNode = Node<FlowGroupNodeData, "group">;
+/**
+ * Branded group container node. Register it as `nodeTypes={{ group: FlowGroupNode }}`
+ * and create nodes with `type: "group"` + typed `data: FlowGroupNodeData`. Children
+ * are re-parented onto it (`parentId`, `extent: "parent"`) — see `useFlowGroups`.
+ *
+ * The header carries the title, a live child-count badge and a collapse/expand
+ * toggle (a real `<button>` with `aria-expanded`) that drives
+ * `useFlowGroups().collapseGroup` / `expandGroup`. When selected (and expanded)
+ * a `<NodeResizer>` lets the group be resized.
+ *
+ * The surface uses the FL-01 tokens `--flow-group` (fill) + `--flow-group-border`
+ * (border). Under a theme whose `--flow-group` is near-transparent, the
+ * drawn border does the work.
+ */
+declare function FlowGroupNode({ id, data, selected }: NodeProps<BrandFlowGroupNode>): react.JSX.Element;
+
+/**
+ * Pure, framework-agnostic grouping operations over `nodes`/`edges` arrays.
+ *
+ * Every function is a **pure transform** — it never mutates its inputs and
+ * returns a fresh `{ nodes, edges }`. This is the testable core; `useFlowGroups`
+ * is a thin hook that wires these to a live canvas via `useReactFlow()`.
+ */
+/** Node type used for the group container (matches `nodeTypes={{ group: FlowGroupNode }}`). */
+declare const FLOW_GROUP_NODE_TYPE = "group";
+interface GroupNodesOptions {
+    /** Id for the new group node. Required so the operation stays deterministic/testable. */
+    groupId: string;
+    /** Header title for the group. @default "Group" */
+    title?: string;
+    /** Accent tone for the group header. */
+    tone?: FlowGroupTone;
+    /** Padding (px) around the child bounds. @default 28 */
+    padding?: number;
+}
+interface FlowGroupOperationResult<NodeType extends Node = Node, EdgeType extends Edge = Edge> {
+    nodes: NodeType[];
+    edges: EdgeType[];
+}
+/** Marker + metadata written onto a proxy edge's `data`. */
+interface FlowGroupProxyEdgeData extends Record<string, unknown> {
+    __flowGroupProxy: true;
+    /** Id of the collapsed group this proxy edge stands in for. */
+    groupId: string;
+}
+/** True if `edge` is a proxy edge synthesized for a collapsed group. */
+declare function isFlowGroupProxyEdge(edge: Edge): boolean;
+/**
+ * Wrap `nodeIds` (assumed top-level) in a new `FlowGroupNode` parent.
+ *
+ * - Computes the child bounds with `getNodesBounds`.
+ * - Inserts the group node **before** its children in the array (React Flow
+ *   requires a parent to precede its children).
+ * - Re-parents each child (`parentId`, `extent: "parent"`) and rewrites its
+ *   position to be **relative to the group origin**.
+ */
+declare function groupNodes<NodeType extends Node = Node, EdgeType extends Edge = Edge>(nodes: NodeType[], edges: EdgeType[], nodeIds: string[], options: GroupNodesOptions): FlowGroupOperationResult<NodeType, EdgeType>;
+/**
+ * Dissolve a group: remove the group node and restore its **direct** children to
+ * absolute positions (dropping `parentId`/`extent`). If the group is currently
+ * collapsed it is expanded first, so ungrouping a collapsed group is safe.
+ */
+declare function ungroup<NodeType extends Node = Node, EdgeType extends Edge = Edge>(nodes: NodeType[], edges: EdgeType[], groupId: string): FlowGroupOperationResult<NodeType, EdgeType>;
+/**
+ * Collapse a group to an overview chip.
+ *
+ * - Hides every descendant (including nested groups and their subtrees).
+ * - Shrinks the group to a fixed overview size and marks `data.collapsed`.
+ * - Re-routes every edge that **crosses the collapse boundary** (exactly one
+ *   endpoint inside the collapsed subtree) to a **proxy edge** targeting the
+ *   group node; the original edge is hidden and stashed for restoration.
+ * - Edges fully inside or fully outside the subtree are left untouched.
+ *
+ * The full pre-collapse graph is stashed on the group's `data` so `expandGroup`
+ * is an exact inverse. Nested collapse is handled by snapshotting each
+ * descendant's exact prior state (a subgroup that was already collapsed stays
+ * collapsed on expand — no double-unhide).
+ */
+declare function collapseGroup<NodeType extends Node = Node, EdgeType extends Edge = Edge>(nodes: NodeType[], edges: EdgeType[], groupId: string): FlowGroupOperationResult<NodeType, EdgeType>;
+/**
+ * Expand a collapsed group — the exact inverse of `collapseGroup`. Restores the
+ * group node, un-hides the descendant subtree (to each node's exact prior
+ * state), removes this group's proxy edges and restores the original edges.
+ * No-op if the group isn't collapsed.
+ */
+declare function expandGroup<NodeType extends Node = Node, EdgeType extends Edge = Edge>(nodes: NodeType[], edges: EdgeType[], groupId: string): FlowGroupOperationResult<NodeType, EdgeType>;
+/** Collapse if expanded, expand if collapsed. */
+declare function toggleGroupCollapsed<NodeType extends Node = Node, EdgeType extends Edge = Edge>(nodes: NodeType[], edges: EdgeType[], groupId: string): FlowGroupOperationResult<NodeType, EdgeType>;
+
+/** Options for `groupNodes`/`groupSelection` with an optional generated id. */
+type GroupOptions = Partial<Pick<GroupNodesOptions, "groupId">> & Omit<GroupNodesOptions, "groupId">;
+interface UseFlowGroupsResult {
+    /**
+     * Wrap the given (top-level) node ids in a new `FlowGroupNode`. Returns the new
+     * group id, or `undefined` if nothing was grouped. Pass `options.groupId` for a
+     * deterministic id; otherwise one is generated.
+     */
+    groupNodes: (nodeIds: string[], options?: GroupOptions) => string | undefined;
+    /** Group the currently-selected nodes. Returns the new group id (or `undefined`). */
+    groupSelection: (options?: GroupOptions) => string | undefined;
+    /** Dissolve a group, restoring its children to absolute positions. */
+    ungroup: (groupId: string) => void;
+    /** Collapse a group to an overview chip (hides subtree, reroutes boundary edges). */
+    collapseGroup: (groupId: string) => void;
+    /** Expand a collapsed group (exact inverse of collapse). */
+    expandGroup: (groupId: string) => void;
+    /** Collapse if expanded, expand if collapsed. */
+    toggleCollapse: (groupId: string) => void;
+}
+/**
+ * Thin hook over the pure grouping operations in `group-operations.ts`. Reads and
+ * writes the live graph via `useReactFlow()`; all the logic lives in the pure,
+ * unit-tested core. Must be called inside a React Flow context (e.g. from a
+ * `<Panel>` child of `<CanvasShell>` or from within a custom node).
+ */
+declare function useFlowGroups<NodeType extends Node = Node, EdgeType extends Edge = Edge>(): UseFlowGroupsResult;
+
+export { type BrandFlowButtonEdge, type BrandFlowGroupNode, type BrandFlowNode, type BrandFlowPlaceholderNode, CanvasShell, type CanvasShellProps, type ClosestHandles, type EdgeParams, FLOW_ALL_SIDE_HANDLES, FLOW_GROUP_NODE_TYPE, type FloatingEdgeData, type FloatingNodeGeometry, FlowButtonEdge, type FlowButtonEdgeData, FlowEdge, FlowFloatingEdge, FlowGroupNode, type FlowGroupNodeData, type FlowGroupOperationResult, type FlowGroupProxyEdgeData, type FlowGroupTone, type FlowHandleSide, type FlowLayoutDirection, type FlowLayoutOptions, type FlowLayoutResult, FlowMiniMap, type FlowMiniMapProps, FlowNode, type FlowNodeData, type FlowNodeHandles, FlowPlaceholderNode, type FlowPlaceholderNodeData, FlowSmartEdge, type GroupNodesOptions, type GroupOptions, HANDLE_SIDES, type HelperLineRect, HelperLines, type HelperLinesProps, type HelperLinesResult, InspectorPanel, type InspectorPanelProps, type LayoutAlgorithm, type LayoutOptions, type LayoutSpacing, Legend, type LegendItem, type LegendProps, type NodeRect, type UseFlowGroupsResult, type UseFlowLayoutResult, type UseHelperLinesOptions, type UseHelperLinesResult, ZoomControls, type ZoomControlsProps, collapseGroup, expandGroup, getEdgeParams, getHelperLines, groupNodes, handlePoint, isFlowGroupProxyEdge, layoutFlow, layoutGraph, pickClosestHandles, sideToPosition, toggleGroupCollapsed, ungroup, useAutoLayout, useFlowGroups, useFlowLayout, useHelperLines };