@elabs-ai/components-flow 4.1.0 → 5.0.0

package/dist/flow-weighted-edge/index.js

@@ -0,0 +1,34 @@
+"use client";
+import "../chunk-W3TQMUGX.js";
+import {
+  buildWeightedEdgeAriaLabel,
+  withWeightedEdgeAria
+} from "../chunk-FAFQ5KLB.js";
+import {
+  FlowWeightedEdge
+} from "../chunk-K5RPSVO6.js";
+import {
+  backEdgeDetour
+} from "../chunk-ZXZTLQIX.js";
+import {
+  EdgeLabelPill
+} from "../chunk-I53W3CFN.js";
+import {
+  DEFAULT_EDGE_WIDTH_RANGE,
+  computeEdgeWeightScale
+} from "../chunk-3BTU2VWZ.js";
+import "../chunk-YG3KXTZW.js";
+import "../chunk-ROJEIIA4.js";
+import "../chunk-T7S7NJFD.js";
+import "../chunk-KDVMGMAK.js";
+import "../chunk-SXXJV6YJ.js";
+export {
+  DEFAULT_EDGE_WIDTH_RANGE,
+  EdgeLabelPill,
+  FlowWeightedEdge,
+  backEdgeDetour,
+  buildWeightedEdgeAriaLabel,
+  computeEdgeWeightScale,
+  withWeightedEdgeAria
+};
+//# sourceMappingURL=index.js.map

package/dist/flow-weighted-edge/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/flow-weighted-edge/weight-scale.js

@@ -0,0 +1,10 @@
+"use client";
+import {
+  DEFAULT_EDGE_WIDTH_RANGE,
+  computeEdgeWeightScale
+} from "../chunk-3BTU2VWZ.js";
+export {
+  DEFAULT_EDGE_WIDTH_RANGE,
+  computeEdgeWeightScale
+};
+//# sourceMappingURL=weight-scale.js.map

package/dist/flow-weighted-edge/weight-scale.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/helper-lines/get-helper-lines.js

@@ -0,0 +1,8 @@
+"use client";
+import {
+  getHelperLines
+} from "../chunk-DNZRAJAQ.js";
+export {
+  getHelperLines
+};
+//# sourceMappingURL=get-helper-lines.js.map

package/dist/helper-lines/get-helper-lines.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/helper-lines/helper-lines.js

@@ -0,0 +1,9 @@
+"use client";
+"use client";
+import {
+  HelperLines
+} from "../chunk-BJ7UMCD3.js";
+export {
+  HelperLines
+};
+//# sourceMappingURL=helper-lines.js.map

package/dist/helper-lines/helper-lines.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/helper-lines/index.js

@@ -0,0 +1,17 @@
+"use client";
+import "../chunk-GE73WQUK.js";
+import {
+  useHelperLines
+} from "../chunk-ZATVF42E.js";
+import {
+  getHelperLines
+} from "../chunk-DNZRAJAQ.js";
+import {
+  HelperLines
+} from "../chunk-BJ7UMCD3.js";
+export {
+  HelperLines,
+  getHelperLines,
+  useHelperLines
+};
+//# sourceMappingURL=index.js.map

package/dist/helper-lines/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/helper-lines/use-helper-lines.js

@@ -0,0 +1,10 @@
+"use client";
+"use client";
+import {
+  useHelperLines
+} from "../chunk-ZATVF42E.js";
+import "../chunk-DNZRAJAQ.js";
+export {
+  useHelperLines
+};
+//# sourceMappingURL=use-helper-lines.js.map

package/dist/helper-lines/use-helper-lines.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/index.d.ts

@@ -35,6 +35,15 @@ interface CanvasShellProps<NodeType extends Node = Node, EdgeType extends Edge =
     fitViewKey?: string | number;
     /** Options for the {@link fitViewKey} re-fit. Ignored without one. */
     fitViewKeyOptions?: FitViewOptions;
+    /**
+     * Which nodes a CLAMPED {@link fitViewKey} re-fit keeps in view — typically where the
+     * diagram begins. A fit that cannot shrink far enough (a `minZoom` floor) is pinned to the
+     * content's top-left corner by default, which is where a top-down layout starts; a
+     * left-to-right layout starts at the left edge but at mid-height, so pinning to the top
+     * opens on an empty corner. With anchors, each overflowing axis centres the anchor nodes
+     * instead, without ever scrolling past the content's own edge. Unset: today's corner pin.
+     */
+    fitViewAnchorNodeIds?: readonly string[];
     /** Overlays rendered inside the flow (ZoomControls, Legend, Panels). */
     children?: ReactNode;
     className?: string;
@@ -762,7 +771,11 @@ interface LegendScaleProps {
     kind: "width" | "color";
     /** `[min, max]` of the underlying value the ramp represents. */
     domain: [number, number];
-    /** Formats a domain value for display at a tick. @default `(v) => v.toLocaleString()` */
+    /**
+     * Formats a domain value for display at a tick.
+     * @default the active `LocaleProvider` locale's `formatNumber` (host locale
+     * when no provider is mounted) — never a hardcoded `toLocaleString()`.
+     */
     format?: (value: number) => string;
     /**
      * Sample count for `kind: "width"`: `"minmax"` draws a min/max pair of
@@ -931,6 +944,93 @@ interface UseFlowGroupsResult {
  */
 declare function useFlowGroups<NodeType extends Node = Node, EdgeType extends Edge = Edge>(): UseFlowGroupsResult;
 
+/** Default token radius, in px. */
+declare const DEFAULT_EDGE_TOKEN_RADIUS = 4;
+interface FlowEdgeToken {
+    /** Stable identity (e.g. a case id). Keys the rendered marker, so a token keeps its element — and its transition — as it moves. */
+    id: string;
+    /** Position along the path's arc length: `0` = source end, `1` = target end. Clamped; a non-finite value sits at `0`. */
+    progress: number;
+    /** Marker radius in px — e.g. scaled by congestion. @default 4 */
+    radius?: number;
+}
+interface FlowEdgeTokensProps extends Omit<SVGProps<SVGGElement>, "ref" | "children"> {
+    /** SVG path `d` the tokens travel along — the same string the edge draws. */
+    path: string;
+    /** Tokens to place. The parent owns `progress`; this part keeps no clock. */
+    tokens: readonly FlowEdgeToken[];
+}
+/**
+ * Markers ("tokens") placed along an edge's path — the presentational primitive
+ * behind process replay. Each token is a circle at `progress` (0..1) of the
+ * path's arc length.
+ *
+ * **Parent-driven, no internal clock.** Nothing here animates on its own: the
+ * parent re-renders with new `progress` values (from a slider, a playback loop,
+ * a play function). Position is a pure function of `(path, progress)` — see
+ * `createEdgePathSampler` — so every render is deterministic and identical in
+ * jsdom, on the server and in the browser.
+ *
+ * Between two renders a token glides with a short `duration-fast` transform
+ * transition, so a parent stepping at a coarse rate still reads as motion. Under
+ * reduced motion (`useReducedMotion()`: the ThemeProvider preference, else the
+ * OS setting) the transition class is not rendered at all and a token jumps
+ * straight to its new position; the `duration-fast` token also collapses to
+ * `--motion-min` through the global motion gate (`data-motion-pref`).
+ *
+ * **Decorative to assistive technology.** The group is `aria-hidden` and ignores
+ * pointer events: a moving dot has no stable meaning to announce. The consumer
+ * owns the text alternative (a live case count, a summary). Colour is the one
+ * `--primary` fill for every token, with a `--background` halo so a token stays
+ * distinct from the edge stroke beneath it.
+ *
+ * Existing brand edges render this for you from `data.tokens`
+ * (`FlowWeightedEdge`, `FlowSelfLoopEdge`); a custom edge renders it after its
+ * `FlowEdgePath` with the same `path` string.
+ */
+declare const FlowEdgeTokens: react.ForwardRefExoticComponent<FlowEdgeTokensProps & react.RefAttributes<SVGGElement>>;
+
+/**
+ * Pure SVG path sampling — the position maths behind `FlowEdgeTokens`.
+ *
+ * `SVGGeometryElement.getPointAtLength` would do the same job in a browser, but
+ * it needs a mounted element (so a layout effect and a second render) and jsdom
+ * implements none of it. Parsing the `d` string here keeps a token's position a
+ * plain function of `(path, progress)`: identical on the server, in jsdom and in
+ * every browser, and testable without a DOM.
+ *
+ * Supports every path command (`M L H V C S Q T A Z`, absolute and relative) in
+ * the spellings React Flow's path helpers emit (`M0,0 C…`, `M 0,0L …`, `M0 0`).
+ * Curves and arcs are flattened into a polyline fine enough that a token sits on
+ * the drawn stroke; progress is measured along that polyline's arc length, so a
+ * token moves at an even speed regardless of how the curve's control points are
+ * spaced.
+ */
+interface EdgePathPoint {
+    x: number;
+    y: number;
+}
+interface EdgePathSampler {
+    /** Total arc length of the path, in px. */
+    length: number;
+    /** The point at `progress` (0..1) of the path's arc length. Out-of-range or non-finite progress is clamped. */
+    pointAt: (progress: number) => EdgePathPoint;
+}
+/**
+ * Flatten a path `d` string into subpath polylines. Each subpath starts at its
+ * `M`. Parsing stops at the first malformed argument; everything before it is kept.
+ */
+declare function flattenEdgePath(d: string): EdgePathPoint[][];
+/**
+ * Build a sampler for a path `d` string, or `null` when the string describes no
+ * geometry at all (empty, or not a path). A path that is a single point has
+ * length 0 and samples to that point for every progress.
+ *
+ * Subpaths are walked in order and the jump between them is not counted — a
+ * token never travels through the gap an `M` leaves.
+ */
+declare function createEdgePathSampler(d: string): EdgePathSampler | null;
+
 interface EdgeLabelPillProps extends ComponentPropsWithoutRef<"button"> {
     /** Primary label, e.g. a frequency count ("128×"). */
     label?: string;
@@ -1002,6 +1102,11 @@ interface FlowWeightedEdgeData extends Record<string, unknown> {
      * own root button from outside this component, without a new semantic prop here.
      */
     labelProps?: Omit<EdgeLabelPillProps, "label" | "secondaryLabel" | "x" | "y" | "selected">;
+    /**
+     * Markers travelling along this edge's computed path (see `FlowEdgeTokens`). The parent
+     * drives each token's `progress`; omitted or empty renders exactly the edge without them.
+     */
+    tokens?: readonly FlowEdgeToken[];
 }
 type BrandFlowWeightedEdge = Edge<FlowWeightedEdgeData, "weighted">;
 /**
@@ -1222,6 +1327,11 @@ interface FlowSelfLoopEdgeData extends Record<string, unknown> {
      * own root button from outside this component, without a new semantic prop here.
      */
     labelProps?: Omit<EdgeLabelPillProps, "label" | "secondaryLabel" | "x" | "y" | "selected">;
+    /**
+     * Markers travelling along the loop's computed arc (see `FlowEdgeTokens`). The parent
+     * drives each token's `progress`; omitted or empty renders exactly the edge without them.
+     */
+    tokens?: readonly FlowEdgeToken[];
 }
 type BrandFlowSelfLoopEdge = Edge<FlowSelfLoopEdgeData, "self-loop">;
 /**
@@ -1345,4 +1455,133 @@ interface SelfLoopHandleAnchor {
  */
 declare function selfLoopHandleArc(anchor: SelfLoopHandleAnchor, loopRadius: number): SelfLoopPath;
 
-export { type BackEdgeAxis, type BackEdgeNodeRect, type BrandFlowButtonEdge, type BrandFlowGroupNode, type BrandFlowNode, type BrandFlowPlaceholderNode, type BrandFlowSelfLoopEdge, type BrandFlowWeightedEdge, CanvasShell, type CanvasShellProps, type ClosestAnchors, type ClosestHandles, DEFAULT_EDGE_WIDTH_RANGE, DEFAULT_LOOP_RADIUS, EdgeLabelPill, type EdgeLabelPillProps, type EdgeParams, type EdgeWeightScaleOptions, FLOW_ALL_SIDE_HANDLES, FLOW_EDGE_FOCUS_CONTOUR_WIDTH, FLOW_EDGE_FOCUS_RING_WIDTH, FLOW_GROUP_NODE_TYPE, FLOW_HANDLE_ANCHOR_CLASS, type FloatingEdgeData, type FloatingNodeGeometry, FlowButtonEdge, type FlowButtonEdgeData, FlowEdge, FlowEdgePath, type FlowEdgePathProps, 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, FlowSelfLoopEdge, type FlowSelfLoopEdgeData, FlowSmartEdge, FlowWeightedEdge, type FlowWeightedEdgeData, type GroupNodesOptions, type GroupOptions, HANDLE_SIDES, type HandleAnchor, type HelperLineRect, HelperLines, type HelperLinesProps, type HelperLinesResult, InspectorPanel, type InspectorPanelProps, type LayoutAlgorithm, type LayoutOptions, type LayoutSpacing, Legend, type LegendCategoricalProps, type LegendItem, type LegendProps, type LegendScaleProps, type NodeRect, type SelfLoopAnchor, type SelfLoopHandleAnchor, type SelfLoopPath, type UseFlowGroupsResult, type UseFlowLayoutResult, type UseHelperLinesOptions, type UseHelperLinesResult, type WeightedEdgeAriaOptions, type WeightedEdgeLike, ZoomControls, type ZoomControlsProps, backEdgeDetour, buildWeightedEdgeAriaLabel, collapseGroup, computeEdgeWeightScale, expandGroup, getEdgeParams, getHelperLines, groupNodes, handlePoint, isFlowGroupProxyEdge, layoutFlow, layoutGraph, pickClosestAnchors, pickClosestHandles, positionToSide, selfLoopHandleArc, selfLoopPath, sideToPosition, toggleGroupCollapsed, ungroup, useAutoLayout, useFlowGroups, useFlowLayout, useHelperLines, withWeightedEdgeAria };
+/**
+ * One path through the graph to lay out on a single straight line (RM-067).
+ *
+ * Produced by {@link pinBackbone}, consumed by `layoutFlowElk`'s `backbone` option. Plain
+ * data, so it clones, serializes and memoizes like any other layout input.
+ */
+interface FlowElkBackbone {
+    /** Node ids on the pinned path, in path order. */
+    nodeIds: string[];
+    /** Ids of the edges joining consecutive pinned nodes, in path order. */
+    edgeIds: string[];
+}
+/**
+ * Pin a variant's activity sequence to one straight row (LR/RL) or column (TB/BT) — the
+ * Apromore-style "backbone" layout (RM-067).
+ *
+ * A pre-pass, not a layout: hand the result to `layoutFlowElk` as `backbone` and the rest of
+ * the graph lays out around it. ELK gets the joining edges at the highest straightness
+ * priority, then every layer holding a pinned node is translated as a whole along the
+ * cross axis so the pinned nodes share one line — a whole-layer shift, so no two nodes of
+ * a layer can ever be pushed onto each other.
+ *
+ * `variant` is the sequence of NODE IDS — for a process graph, the most frequent variant's
+ * activities, which are the activity nodes' ids. An id with no node is skipped; a repeated
+ * activity (rework inside the variant) is pinned once, at its first occurrence, because a
+ * node cannot sit on a straight line twice.
+ *
+ * @example
+ * ```ts
+ * const backbone = pinBackbone(nodes, edges, variants[0].activities);
+ * const { nodes: laidOut } = await layoutFlowElk(nodes, edges, { direction: "LR", backbone });
+ * ```
+ */
+declare function pinBackbone(nodes: readonly Node[], edges: readonly Edge[], variant: readonly string[]): FlowElkBackbone;
+
+/**
+ * elkjs layout adapter — RM-067.
+ *
+ * dagre has no self-loop layout, no edge routing and weak compound nodes. ELK (Eclipse
+ * Layout Kernel, EPL-2.0) has all three, and it is large — so it is an OPTIONAL peer of this
+ * package, reached ONLY through `import()` inside {@link layoutFlowElk}'s body. A consumer
+ * that never calls it never downloads it, and a consumer that calls it without installing
+ * elkjs gets `layoutFlow`'s dagre answer plus a development-only console warning, never a
+ * crash.
+ *
+ * The default engine runs inline on the calling thread (elkjs's own in-thread worker
+ * stand-in). The package deliberately ships NO worker entry: a `new Worker(new URL(…,
+ * import.meta.url))` pointing at a file the tsup build does not emit breaks some consumer
+ * bundlers at build time. A host that wants the layout off the main thread supplies
+ * `loadEngine` with its own worker, e.g.
+ *
+ * ```ts
+ * loadEngine: async () => {
+ *   const { default: ELK } = await import("elkjs/lib/elk-api.js");
+ *   return new ELK({ workerUrl: new URL("elkjs/lib/elk-worker.min.js", import.meta.url).href });
+ * }
+ * ```
+ *
+ * No remote origin is involved either way.
+ */
+/** Options for {@link layoutFlowElk}. */
+interface FlowLayoutElkOptions {
+    /** Layout direction. @default "TB" */
+    direction?: FlowLayoutDirection;
+    /** How ELK routes edges. @default "splines" */
+    edgeRouting?: "orthogonal" | "splines";
+    /** Route back-edges as ELK feedback edges (around the graph, not through it). @default true */
+    feedbackEdges?: boolean;
+    /** Gap between nodes in the same layer. @default 48 */
+    nodeSpacing?: number;
+    /** Gap between layers. @default 72 */
+    rankSpacing?: number;
+    /**
+     * Compound nodes. Each `id` names a node already in `nodes` (typically a `FlowGroupNode`);
+     * its `children` are laid out inside it and come back with `parentId` set, positioned
+     * relative to the group, and the group comes back sized to fit them.
+     */
+    groups?: {
+        id: string;
+        children: string[];
+    }[];
+    /** A pinned straight path — see `pinBackbone`. */
+    backbone?: FlowElkBackbone;
+    /**
+     * Supply the engine yourself: a host with its own worker URL, or a test. Rejecting (for
+     * example because elkjs is not installed) falls back to dagre exactly like the default
+     * loader does.
+     */
+    loadEngine?: () => Promise<FlowElkEngine>;
+}
+/** A graph in ELK's JSON format — the minimal shape this adapter reads and writes. */
+interface FlowElkGraph {
+    id: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    layoutOptions?: Record<string, string>;
+    children?: FlowElkGraph[];
+    edges?: {
+        id: string;
+        sources: string[];
+        targets: string[];
+        layoutOptions?: Record<string, string>;
+    }[];
+}
+/** A running ELK engine. `new ELK()` from elkjs satisfies it. */
+interface FlowElkEngine {
+    layout(graph: FlowElkGraph): Promise<FlowElkGraph>;
+}
+/** What {@link layoutFlowElk} answers — `layoutFlow`'s result plus which engine produced it. */
+interface FlowLayoutElkResult<NodeType extends Node = Node, EdgeType extends Edge = Edge> extends FlowLayoutResult<NodeType, EdgeType> {
+    /** `"elk"`, or `"dagre"` when elkjs could not be loaded or failed and dagre answered. */
+    engine: "elk" | "dagre";
+}
+/**
+ * Lay a graph out with ELK's layered algorithm — `layoutFlow`'s async sibling.
+ *
+ * Same result shape as `layoutFlow` (`nodes`, `edges`, `backEdges`, `selfLoops`), so a
+ * caller can swap engines without a different consumption path; `engine` says which one
+ * actually answered. Self-loops are laid out by ELK (it routes them around their node) and
+ * still reported in `selfLoops`; `backEdges` are the edges whose source sits at or after
+ * their target along the layout direction.
+ *
+ * elkjs is imported lazily inside this function. If it is not installed, or ELK throws,
+ * the result is `layoutFlow`'s dagre layout with `engine: "dagre"`.
+ */
+declare function layoutFlowElk<NodeType extends Node = Node, EdgeType extends Edge = Edge>(nodes: NodeType[], edges: EdgeType[], options?: FlowLayoutElkOptions): Promise<FlowLayoutElkResult<NodeType, EdgeType>>;
+
+export { type BackEdgeAxis, type BackEdgeNodeRect, type BrandFlowButtonEdge, type BrandFlowGroupNode, type BrandFlowNode, type BrandFlowPlaceholderNode, type BrandFlowSelfLoopEdge, type BrandFlowWeightedEdge, CanvasShell, type CanvasShellProps, type ClosestAnchors, type ClosestHandles, DEFAULT_EDGE_TOKEN_RADIUS, DEFAULT_EDGE_WIDTH_RANGE, DEFAULT_LOOP_RADIUS, EdgeLabelPill, type EdgeLabelPillProps, type EdgeParams, type EdgePathPoint, type EdgePathSampler, type EdgeWeightScaleOptions, FLOW_ALL_SIDE_HANDLES, FLOW_EDGE_FOCUS_CONTOUR_WIDTH, FLOW_EDGE_FOCUS_RING_WIDTH, FLOW_GROUP_NODE_TYPE, FLOW_HANDLE_ANCHOR_CLASS, type FloatingEdgeData, type FloatingNodeGeometry, FlowButtonEdge, type FlowButtonEdgeData, FlowEdge, FlowEdgePath, type FlowEdgePathProps, type FlowEdgeToken, FlowEdgeTokens, type FlowEdgeTokensProps, type FlowElkBackbone, type FlowElkEngine, type FlowElkGraph, FlowFloatingEdge, FlowGroupNode, type FlowGroupNodeData, type FlowGroupOperationResult, type FlowGroupProxyEdgeData, type FlowGroupTone, type FlowHandleSide, type FlowLayoutDirection, type FlowLayoutElkOptions, type FlowLayoutElkResult, type FlowLayoutOptions, type FlowLayoutResult, FlowMiniMap, type FlowMiniMapProps, FlowNode, type FlowNodeData, type FlowNodeHandles, FlowPlaceholderNode, type FlowPlaceholderNodeData, FlowSelfLoopEdge, type FlowSelfLoopEdgeData, FlowSmartEdge, FlowWeightedEdge, type FlowWeightedEdgeData, type GroupNodesOptions, type GroupOptions, HANDLE_SIDES, type HandleAnchor, type HelperLineRect, HelperLines, type HelperLinesProps, type HelperLinesResult, InspectorPanel, type InspectorPanelProps, type LayoutAlgorithm, type LayoutOptions, type LayoutSpacing, Legend, type LegendCategoricalProps, type LegendItem, type LegendProps, type LegendScaleProps, type NodeRect, type SelfLoopAnchor, type SelfLoopHandleAnchor, type SelfLoopPath, type UseFlowGroupsResult, type UseFlowLayoutResult, type UseHelperLinesOptions, type UseHelperLinesResult, type WeightedEdgeAriaOptions, type WeightedEdgeLike, ZoomControls, type ZoomControlsProps, backEdgeDetour, buildWeightedEdgeAriaLabel, collapseGroup, computeEdgeWeightScale, createEdgePathSampler, expandGroup, flattenEdgePath, getEdgeParams, getHelperLines, groupNodes, handlePoint, isFlowGroupProxyEdge, layoutFlow, layoutFlowElk, layoutGraph, pickClosestAnchors, pickClosestHandles, pinBackbone, positionToSide, selfLoopHandleArc, selfLoopPath, sideToPosition, toggleGroupCollapsed, ungroup, useAutoLayout, useFlowGroups, useFlowLayout, useHelperLines, withWeightedEdgeAria };