@kolosal-ai/rivet 0.1.0

package/dist/types-B8AAJ60T.d.ts

@@ -0,0 +1,515 @@
+import { ComponentType, CSSProperties } from 'react';
+
+/** A point in world (graph) space. */
+type Vec2 = {
+    x: number;
+    y: number;
+};
+/** An axis-aligned bounding box in world space. */
+type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * A snap/alignment guide line shown while dragging, in world space. `axis: "x"`
+ * is a vertical line at world-x `position`; `axis: "y"` is horizontal at world-y
+ * `position`. `start`/`end` are the perpendicular span (so it only spans the
+ * involved nodes).
+ */
+type AlignmentGuide = {
+    axis: "x" | "y";
+    position: number;
+    start: number;
+    end: number;
+};
+/**
+ * The viewport transform. Maps world space to screen space via
+ * `screen = world * zoom + { x, y }`.
+ */
+type Viewport = {
+    x: number;
+    y: number;
+    zoom: number;
+};
+type NodeId = string;
+type EdgeId = string;
+/** A graph node. `data` is passed straight through to the React renderer. */
+type RivetNode<TData = unknown> = {
+    id: NodeId;
+    /** Node type key, used to look up the React component that renders it. */
+    type?: string;
+    /**
+     * Position in world units. Relative to {@link parentId}'s top-left when this
+     * node has a parent; otherwise an absolute world position.
+     */
+    position: Vec2;
+    /** Measured size in world units; filled in after the DOM node mounts. */
+    size?: {
+        width: number;
+        height: number;
+    };
+    /** Explicit width in world units (set by {@link NodeResizer}); overrides measurement. */
+    width?: number;
+    /** Explicit height in world units (set by {@link NodeResizer}); overrides measurement. */
+    height?: number;
+    /**
+     * Parent node id. A child renders above its parent, is positioned relative to
+     * it, and (with `extent: "parent"`) is confined to it — the basis for sub-flows
+     * and inline nodes (e.g. SVG children over an SVG container).
+     */
+    parentId?: NodeId;
+    /** `"parent"` keeps this node inside its {@link parentId}'s bounds while dragging. */
+    extent?: "parent";
+    data: TData;
+    selected?: boolean;
+    /** True while the pointer is over the node (drives hover highlight). */
+    hovered?: boolean;
+    /** True while this node is being dragged. Set from `position` changes. */
+    dragging?: boolean;
+    /** When `false`, the node can't be dragged (still selectable). Defaults to `true`. */
+    draggable?: boolean;
+    /** When `false`, clicks and marquee never select the node. Defaults to `true`. */
+    selectable?: boolean;
+    /**
+     * Accessible name for the node (`aria-label` on its wrapper, and the name
+     * screen-reader announcements use). Falls back to the wrapper's text content
+     * when omitted.
+     */
+    ariaLabel?: string;
+    /**
+     * Id of the {@link Swimlane} this node belongs to. Reassigned automatically as
+     * the node is dragged across lane boundaries when swimlane clamping is on.
+     */
+    laneId?: string;
+};
+/** Per-edge stroke styling, applied by the renderer over the default look. */
+type EdgeStyle = {
+    /** Stroke color (any CSS color). Defaults to the theme's edge color. */
+    stroke?: string;
+    /** Stroke width in px. Defaults to `1.5`. */
+    strokeWidth?: number;
+    /** Dash pattern in px (e.g. `[6, 4]`). Omit for a solid line. */
+    strokeDasharray?: number[];
+    /** Stroke opacity `0..1`. Defaults to `1`. */
+    opacity?: number;
+};
+/** Arrowhead kind drawn at an edge end. `false` (default) draws none. */
+type EdgeMarker = "arrow" | "arrowclosed" | false;
+/** A directed connection between two nodes (optionally between handles). */
+type RivetEdge<TData = unknown> = {
+    id: EdgeId;
+    source: NodeId;
+    target: NodeId;
+    sourceHandle?: string;
+    targetHandle?: string;
+    /** Path shape key, resolved against the graph's `edgeTypes`. Defaults to `"bezier"`. */
+    type?: string;
+    /** Animate the stroke with a marching-dash effect. Defaults to `false`. */
+    animated?: boolean;
+    /** Per-edge stroke overrides. */
+    style?: EdgeStyle;
+    /** Arrowhead at the target end. */
+    markerEnd?: EdgeMarker;
+    /** Arrowhead at the source end. */
+    markerStart?: EdgeMarker;
+    /** Text drawn at the edge's midpoint (via the DOM label layer). */
+    label?: string;
+    /**
+     * CSS overrides merged over the built-in label chip (and over
+     * `defaultEdgeOptions.labelStyle`) — background, color, font, padding, etc.
+     */
+    labelStyle?: CSSProperties;
+    /** Whether clicking the edge selects it. Defaults to `true`. */
+    selectable?: boolean;
+    /** Whether this edge can be reconnected by dragging an endpoint. Overrides `edgesReconnectable`. */
+    reconnectable?: boolean;
+    data?: TData;
+    selected?: boolean;
+};
+/**
+ * Defaults merged into every edge that doesn't set the field itself. Passed to
+ * `<Rivet>` via `defaultEdgeOptions`.
+ */
+type DefaultEdgeOptions = {
+    type?: string;
+    animated?: boolean;
+    style?: EdgeStyle;
+    markerEnd?: EdgeMarker;
+    markerStart?: EdgeMarker;
+    /** Label chip CSS applied to every labeled edge (under per-edge `labelStyle`). */
+    labelStyle?: CSSProperties;
+};
+/** The current selection, reported to `onSelectionChange`. */
+type RivetSelection = {
+    nodes: RivetNode[];
+    edges: RivetEdge[];
+};
+/**
+ * A serializable snapshot of the graph the store owns — nodes, edges, and the
+ * viewport. Produced by {@link RivetInstance.toObject} and safe to `JSON.stringify`.
+ * Feed it back via the `nodes`/`edges` props and `defaultViewport` (or
+ * `setViewport`) to restore. Swimlanes are consumer-owned layout config (the
+ * `swimlane` prop), not part of the store — persist them alongside.
+ */
+type RivetSnapshot<TNodeData = unknown, TEdgeData = unknown> = {
+    nodes: RivetNode<TNodeData>[];
+    edges: RivetEdge<TEdgeData>[];
+    viewport: Viewport;
+};
+/**
+ * A single change to one node, emitted by the graph to `onNodesChange`. Apply a
+ * batch to your own state with {@link applyNodeChanges}. This is the controlled
+ * API: the graph tells you what it wants to change; you decide whether to honor
+ * it by feeding the result back in via the `nodes` prop.
+ */
+type NodeChange<TData = unknown> = {
+    type: "position";
+    id: NodeId;
+    position?: Vec2;
+    dragging?: boolean;
+} | {
+    type: "dimensions";
+    id: NodeId;
+    dimensions: Size;
+    resizing?: boolean;
+} | {
+    type: "select";
+    id: NodeId;
+    selected: boolean;
+} | {
+    type: "remove";
+    id: NodeId;
+} | {
+    type: "add";
+    item: RivetNode<TData>;
+} | {
+    type: "replace";
+    id: NodeId;
+    item: RivetNode<TData>;
+};
+/** A single change to one edge, emitted to `onEdgesChange`. See {@link NodeChange}. */
+type EdgeChange<TData = unknown> = {
+    type: "select";
+    id: EdgeId;
+    selected: boolean;
+} | {
+    type: "remove";
+    id: EdgeId;
+} | {
+    type: "add";
+    item: RivetEdge<TData>;
+} | {
+    type: "replace";
+    id: EdgeId;
+    item: RivetEdge<TData>;
+};
+/**
+ * What a handle may be when dragging a connection:
+ * - `"source"` — can only start an edge.
+ * - `"target"` — can only receive an edge.
+ * - `"either"` — can do both (acts as source or target as needed).
+ *
+ * A pair is valid when one end can source and the other can target.
+ */
+type HandleType = "source" | "target" | "either";
+type HandlePosition = "left" | "right" | "top" | "bottom";
+/** A registered connection point on a node. */
+type HandleRecord = {
+    nodeId: NodeId;
+    handleId: string;
+    type: HandleType;
+    /** Which side of the node the handle sits on; drives the edge's exit direction. */
+    position: HandlePosition;
+    /** Center offset from the node's top-left, in world units. */
+    offset: Vec2;
+};
+/** A proposed or committed link between two handles. */
+type Connection = {
+    source: NodeId;
+    target: NodeId;
+    sourceHandle: string | null;
+    targetHandle: string | null;
+};
+/** The in-progress connection being dragged (world coordinates). */
+type PendingConnection = {
+    source: NodeId;
+    sourceHandle: string;
+    sourceType: HandleType;
+    from: Vec2;
+    to: Vec2;
+    /**
+     * Side the loose end enters from — the snapped target handle's side while the
+     * drag is over a compatible handle, so the preview curves exactly like the edge
+     * it will commit to. Unset when hovering empty space (the end faces the source).
+     */
+    toPosition?: HandlePosition;
+    /** Set when this drag is reconnecting an existing edge (that edge is hidden). */
+    reconnecting?: EdgeId;
+};
+/** Inputs to an {@link EdgePathFn}: both ends in screen space, plus their sides. */
+type EdgePathParams = {
+    sourceX: number;
+    sourceY: number;
+    targetX: number;
+    targetY: number;
+    sourcePosition: HandlePosition;
+    targetPosition: HandlePosition;
+};
+/**
+ * The geometry an edge type produces: a polyline the renderer strokes (and picks
+ * against) plus the point where a label sits. Sampled polylines keep drawing,
+ * hit-testing, and labels uniform across built-in and custom edge types — and
+ * stay renderer-agnostic (any backend consumes the same points).
+ */
+type EdgePath = {
+    points: Vec2[];
+    labelX: number;
+    labelY: number;
+};
+/** A custom edge shape: pure geometry, drawable by any backend. */
+type EdgePathFn = (params: EdgePathParams) => EdgePath;
+/** Map of edge `type` keys to the path builder that shapes them. */
+type EdgeTypes = Record<string, EdgePathFn>;
+/** Which end of an edge a point is nearest — used for reconnection. */
+type EdgeEnd = "source" | "target";
+/**
+ * The runtime's reconnect gateway, bound on the store. `<Handle>` consults it on
+ * pointer-down: when a press lands within the endpoint radius of a
+ * *reconnectable* edge, the handle starts a reconnect drag for that edge instead
+ * of a new connection (hold Alt to force a new connection from an occupied
+ * handle).
+ */
+type ReconnectDelegate = {
+    /** The reconnectable edge endpoint near a client-space point, or null. */
+    pickEndpoint: (clientX: number, clientY: number) => {
+        edgeId: EdgeId;
+        end: EdgeEnd;
+    } | null;
+    /** Start the reconnect drag for that endpoint. */
+    begin: (edgeId: EdgeId, end: EdgeEnd) => void;
+};
+/** Extra per-frame inputs for the edge renderer. */
+type EdgeDrawExtras = {
+    handles?: Map<string, HandleRecord>;
+    pending?: PendingConnection | null;
+    /** Edge under the pointer, drawn with a hover highlight. */
+    hovered?: EdgeId | null;
+    /** Edge currently being reconnected — skipped so only its pending preview shows. */
+    reconnecting?: EdgeId | null;
+    /** Resolved world positions per node (parent chains applied); anchors use these. */
+    worldPositions?: ReadonlyMap<NodeId, Vec2>;
+    /**
+     * Hysteresis memory for per-frame side resolution, keyed by
+     * `"<edgeId>:<end>"`. The renderer reads the last displayed side of every
+     * auto-resolved end from here and writes the new one back, so near-diagonal
+     * layouts don't flicker. Owned by the store (`getDisplayedSides`) so a
+     * `"live"` alignment commit can re-side to exactly what was displayed.
+     */
+    displayedSides?: Map<string, HandlePosition>;
+    /**
+     * Nodes currently mid-drag under `edgeAlignment: "live"`. Every edge touching
+     * one renders both ends as auto (facing each other) for the frame; the
+     * resolved sides commit on drop, not here.
+     */
+    liveAlignNodes?: ReadonlySet<NodeId>;
+    /**
+     * Places an anchor end along `side` of its node — the anchor's stray-handle
+     * position as % of that side — or null when the anchor is unknown or
+     * unmeasured (the end falls back to the side's midpoint).
+     */
+    anchorPlacement?: (nodeId: NodeId, anchorId: string, side: HandlePosition) => number | null;
+};
+/**
+ * The seam that keeps graph and interaction code independent of how edges are
+ * drawn — swap the Canvas2D default for a custom backend without touching either.
+ */
+interface EdgeRenderer {
+    /** Draw all edges (and any in-progress connection) for the current frame. */
+    draw(edges: RivetEdge[], nodes: Map<NodeId, RivetNode>, viewport: Viewport, extras?: EdgeDrawExtras): void;
+    /** Screen-space label anchor per edge that has a label, from the last {@link draw}. */
+    getLabels(): Map<EdgeId, Vec2>;
+    /** Return the edge under a screen-space point, or null. `tolerance` overrides
+     * the backend's default pick distance (used for hover hysteresis). */
+    pick(x: number, y: number, tolerance?: number): EdgeId | null;
+    /** Return the edge endpoint under a screen-space point, or null (for reconnection). */
+    pickEndpoint(x: number, y: number): {
+        edgeId: EdgeId;
+        end: EdgeEnd;
+    } | null;
+    /**
+     * Screen-space endpoints per edge from the last {@link draw} — the runtime
+     * reads these to render the reconnect affordance. Optional so custom
+     * backends without it just don't get endpoint bubbles.
+     */
+    getEndpoints?(): ReadonlyMap<EdgeId, {
+        source: Vec2;
+        target: Vec2;
+    }>;
+    /** Resize backing buffers to match the container. */
+    resize(width: number, height: number, dpr: number): void;
+    /** Release GPU / canvas resources. */
+    dispose(): void;
+}
+/** Construction options shared by every {@link EdgeRenderer} backend. */
+type EdgeRendererOptions = {
+    /** Registry of custom edge path builders, merged over the built-ins. */
+    edgeTypes?: EdgeTypes;
+    /** Defaults merged into every edge (type, animated, style, markers). */
+    defaultEdgeOptions?: DefaultEdgeOptions;
+};
+/**
+ * Factory for an {@link EdgeRenderer} backend, passed to `<Rivet renderer={…}>`.
+ * Called once per edge canvas (committed edges + the foreground connection).
+ * Construction is synchronous; a backend that needs async setup should no-op
+ * its `draw` until ready. Defaults to Canvas2D.
+ */
+type EdgeRendererFactory = (canvas: HTMLCanvasElement, options: EdgeRendererOptions) => EdgeRenderer;
+/** Props passed to every node component registered in `nodeTypes`. */
+type NodeProps<TData = unknown> = {
+    id: NodeId;
+    type?: string;
+    data: TData;
+    selected: boolean;
+    hovered: boolean;
+    /**
+     * Current box width in world units — the explicit {@link RivetNode.width} set
+     * by {@link NodeResizer}, falling back to the measured size. `undefined` until
+     * the node has an explicit width or has been measured.
+     */
+    width?: number;
+    /** Current box height in world units. See {@link NodeProps.width}. */
+    height?: number;
+    /**
+     * The node's own position, in world units — relative to its
+     * {@link RivetNode.parentId}'s top-left when it has a parent, otherwise the
+     * same as {@link NodeProps.positionAbsolute}.
+     */
+    position: Vec2;
+    /** Absolute world position, with the parent chain resolved. */
+    positionAbsolute: Vec2;
+};
+type NodeComponent<TData = any> = ComponentType<NodeProps<TData>>;
+/** Map of node `type` keys to the React component that renders them. */
+type NodeTypes = Record<string, NodeComponent>;
+/** A width/height pair in world units. */
+type Size = {
+    width: number;
+    height: number;
+};
+/**
+ * One swimlane — a "file" within a {@link SwimlaneGroup} "folder". Lanes stack
+ * vertically below their group's header; a node lives inside exactly one lane.
+ */
+type Swimlane = {
+    id: string;
+    /** Text shown in the lane's sticky left label. */
+    label?: string;
+    /** Lane height in world units. */
+    size: number;
+    /** Optional fill tint for the lane band (any CSS color). */
+    color?: string;
+};
+/**
+ * A swimlane group — a "folder" of {@link Swimlane} "files". Rendered as a
+ * sticky top header band above its lanes. Groups are neither nodes nor edges;
+ * they're passed to `<Rivet>` via the `swimlane` prop.
+ */
+type SwimlaneGroup = {
+    id: string;
+    /** Text shown in the group's sticky header. */
+    label?: string;
+    /** Accent color (hex) for the header band and, by default, its lanes. */
+    color?: string;
+    /** Top-left origin of the group (its header top) in world space. */
+    position?: Vec2;
+    /** Nominal lane width in world units. Bands render full-viewport-width. */
+    length: number;
+    lanes: Swimlane[];
+};
+/**
+ * Inner clearance kept between a node and its lane's edges when clamping. A
+ * number applies to all sides; per-side values override it.
+ */
+type SwimlaneMargin = {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+};
+/** Passed to a custom `renderSwimlaneHeader`. */
+type SwimlaneHeaderProps = {
+    id: string;
+    label?: string;
+    /** The group's accent color, if any. */
+    color?: string;
+    /** True while the header is pinned to the pane top (scrolled into its band). */
+    sticky: boolean;
+};
+/** Passed to a custom `renderSwimlaneLabel`. */
+type SwimlaneLabelProps = {
+    id: string;
+    label?: string;
+    color?: string;
+    groupId: string;
+};
+/**
+ * Reported to `onSwimlaneSizeChange` when a lane's height changes — from a drag
+ * of its bottom handle or from auto-fit growing it to contain a node.
+ */
+type SwimlaneSizeChange = {
+    laneId: string;
+    /** The lane's new height in world units. */
+    height: number;
+    /** What caused the change. */
+    reason: "resize" | "autofit";
+};
+/** Reported to `onLaneChange` when a dragged node moves to a different lane. */
+type LaneChange = {
+    nodeId: NodeId;
+    /** The lane the node now belongs to, or null if dropped outside all lanes. */
+    laneId: string | null;
+    /** The lane it came from, or null if it had none. */
+    previousLaneId: string | null;
+};
+/** Options for {@link RivetControls.fitView}. */
+type FitViewOptions = {
+    /** Fraction of the pane to leave as empty margin on each side (default 0.1). */
+    padding?: number;
+    /** Never zoom in past this level when fitting (default: the graph's maxZoom). */
+    maxZoom?: number;
+    /** Animate the move over this many ms (default 0 — jump instantly). A user pan/zoom cancels it. */
+    duration?: number;
+};
+/** Options for {@link RivetControls.centerNode}. */
+type CenterNodeOptions = {
+    /** Absolute zoom to apply while centering (default: keep the current zoom). */
+    zoom?: number;
+    /** Animate the move over this many ms (default 0 — jump instantly). A user pan/zoom cancels it. */
+    duration?: number;
+};
+/**
+ * Imperative viewport controls, available via {@link useRivetControls} or on
+ * the context. Everything is clamped to the graph's `minZoom`/`maxZoom`.
+ */
+type RivetControls = {
+    /** Zoom in one step, anchored on the pane center. */
+    zoomIn: () => void;
+    /** Zoom out one step, anchored on the pane center. */
+    zoomOut: () => void;
+    /** Zoom to an absolute level, anchored on the pane center. */
+    zoomTo: (zoom: number) => void;
+    /** Frame all nodes within the pane. No-op when the graph is empty. */
+    fitView: (options?: FitViewOptions) => void;
+    /** Frame the currently selected nodes within the pane. No-op when nothing is selected. */
+    fitSelection: (options?: FitViewOptions) => void;
+    /** Frame an arbitrary world-space rect within the pane (e.g. a swimlane's bounds). */
+    fitBounds: (rect: Rect, options?: FitViewOptions) => void;
+    /** Pan (and optionally zoom) so a node sits at the pane center. No-op for an unknown id. */
+    centerNode: (id: NodeId, options?: CenterNodeOptions) => void;
+    getViewport: () => Viewport;
+    setViewport: (viewport: Viewport) => void;
+};
+
+export type { AlignmentGuide as A, EdgeMarker as B, Connection as C, DefaultEdgeOptions as D, EdgeChange as E, EdgePath as F, EdgePathParams as G, HandlePosition as H, EdgeStyle as I, FitViewOptions as J, NodeComponent as K, LaneChange as L, Swimlane as M, NodeId as N, PendingConnection as P, Rect as R, Size as S, Vec2 as V, RivetEdge as a, NodeChange as b, RivetNode as c, NodeProps as d, NodeTypes as e, HandleType as f, Viewport as g, EdgeTypes as h, EdgeRendererFactory as i, SwimlaneGroup as j, SwimlaneMargin as k, SwimlaneHeaderProps as l, SwimlaneLabelProps as m, SwimlaneSizeChange as n, RivetSelection as o, EdgeId as p, HandleRecord as q, ReconnectDelegate as r, RivetControls as s, RivetSnapshot as t, EdgeRenderer as u, EdgeRendererOptions as v, EdgeDrawExtras as w, EdgeEnd as x, EdgePathFn as y, CenterNodeOptions as z };

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@kolosal-ai/rivet",
+  "version": "0.1.0",
+  "description": "Canvas-rendered node graph for React: DOM nodes, Canvas2D edges, swimlanes, anchors, undo/redo",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KolosalAI/rivet.git",
+    "directory": "packages/rivet"
+  },
+  "homepage": "https://github.com/KolosalAI/rivet#readme",
+  "bugs": "https://github.com/KolosalAI/rivet/issues",
+  "keywords": [
+    "react",
+    "node-graph",
+    "node-editor",
+    "flow",
+    "canvas",
+    "diagram",
+    "swimlane",
+    "graph-editor"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./anchor": {
+      "types": "./dist/anchor/index.d.ts",
+      "import": "./dist/anchor/index.js"
+    },
+    "./svg": {
+      "types": "./dist/svg/index.d.ts",
+      "import": "./dist/svg/index.js"
+    },
+    "./swimlane": {
+      "types": "./dist/swimlane/index.d.ts",
+      "import": "./dist/swimlane/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": "^18.3.0 || ^19.0.0",
+    "react-dom": "^18.3.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.8",
+    "@types/react-dom": "^19.1.6",
+    "jsdom": "^26.0.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.0",
+    "@rivet/utils": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo"
+  }
+}