@pixerate/editor 0.9.0 → 0.11.0

package/dist/canvas/index.d.ts

@@ -0,0 +1,277 @@
+import { R as Rect, d as CanvasNode, X as XYPosition, b as CanvasEdge, I as IncrementalLayoutOptions, S as Side, c as CanvasLayoutOptions, P as PlaceBesideOptions, T as TrajectoryFunction, F as FanOutTrajectoryOptions, N as NodeTransition, k as ReflowDisplacementOptions, D as DirectionalDisplacementOptions, C as CanvasClipboardPayload } from '../types-lGtRobRV.js';
+export { a as CanvasDockingCallbacks, e as CollapseNodeOptions, f as DisplacementDirection, g as DockStrategy, E as ExplodeNodeOptions, h as ExplosionSnapshot, G as GraphDifferences, i as Point, j as Position, l as TrajectoryPoint } from '../types-lGtRobRV.js';
+
+declare const DEFAULT_NODE_WIDTH = 200;
+declare const DEFAULT_NODE_HEIGHT = 60;
+declare const DEFAULT_PLACEMENT_GAP = 48;
+/**
+ * Calculates upper-left flow coordinate for an element to be centered in the viewport.
+ */
+declare function getCenteredNodePosition(width: number | undefined, height: number | undefined, screenToFlowPosition: (position: XYPosition) => XYPosition, screenDimensions?: {
+    width: number;
+    height: number;
+}): XYPosition;
+/**
+ * Updates positions of nodes so their collective bounding box is centered in the current viewport.
+ */
+declare function centerNodes<TNode extends CanvasNode = CanvasNode>(nodes: TNode[], screenToFlowPosition: (position: XYPosition) => XYPosition, getNodesBounds: (nodes: TNode[]) => Rect, screenDimensions?: {
+    width: number;
+    height: number;
+}): TNode[];
+/**
+ * Automatically calculates directed hierarchical layout of nodes and edges using Dagre.
+ */
+declare function getLayoutedNodes<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge>(nodes: TNode[], edges: TEdge[], getNodesBounds?: (nodes: TNode[]) => Rect, options?: CanvasLayoutOptions): TNode[];
+/**
+ * Heuristic text-based node size estimator when DOM measurement is not available.
+ */
+declare function estimateNodeSize(node: CanvasNode, defaultWidth?: number, defaultHeight?: number): {
+    width: number;
+    height: number;
+};
+/**
+ * Computes bounding rectangle of an array of rectangles.
+ */
+declare function boundsOf(rects: Rect[]): Rect | null;
+/**
+ * Center coordinate of a rectangle.
+ */
+declare function centre(r: Rect): XYPosition;
+/**
+ * Determines whether two rectangles overlap, including an optional padding distance.
+ */
+declare function overlaps(a: Rect, b: Rect, pad?: number): boolean;
+/**
+ * Maps directed layout flow to its natural forward growth side.
+ */
+declare function flowSide(direction?: 'LR' | 'TB' | 'RL' | 'BT'): Side;
+/**
+ * Incremental layout blending:
+ * Keeps established/manual node positions intact. Runs Dagre on the entire graph,
+ * computes the centroid translation offset between auto and stored positions of existing nodes,
+ * and places unpositioned/new nodes at (auto + offset).
+ */
+declare function ensureLayout<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge>(nodes: TNode[], edges: TEdge[], options?: IncrementalLayoutOptions): TNode[];
+/**
+ * Finds a free top-left coordinate for a node of `size` adjacent to `nearNodeId` (or the cluster),
+ * sliding along the perpendicular axis past any intersecting bounding boxes to guarantee non-overlapping placement.
+ */
+declare function placeBeside(rects: Record<string, Rect>, size: {
+    width: number;
+    height: number;
+}, side: Side, nearNodeId?: string, options?: PlaceBesideOptions): XYPosition;
+
+/**
+ * The time source that canvas animations and agent performances play on.
+ *
+ * Defaults to `realClock` (requestAnimationFrame and setTimeout).
+ * A `ManualClock` moves only when told to via `advance(ms)` or `tick(fps)`,
+ * enabling deterministic frame-by-frame stepping for testing, video generation,
+ * or headless server environments.
+ */
+interface Clock {
+    /** Current time in milliseconds. */
+    now(): number;
+    /** Resolves on the next animation frame. */
+    frame(): Promise<void>;
+    /** Resolves after `ms` milliseconds of this clock's time. */
+    sleep(ms: number): Promise<void>;
+    /**
+     * Whether the clock follows wall time. Live clocks stop or degrade when the
+     * tab is in the background (browsers pause animation frames), so transitions
+     * can commit immediately rather than leaving operations hanging.
+     */
+    readonly live: boolean;
+}
+/** Whether the browser tab is hidden (where RAF pauses). */
+declare const pageHidden: () => boolean;
+/** Real-time clock using requestAnimationFrame and setTimeout. */
+declare const realClock: Clock;
+/**
+ * A deterministic clock that only moves forward when `advance` or `tick` is called.
+ * Allows step-by-step frame testing and video rendering without waiting for real time.
+ */
+declare class ManualClock implements Clock {
+    readonly live = false;
+    private time;
+    private frames;
+    private sleepers;
+    private seq;
+    constructor(start?: number);
+    now(): number;
+    frame(): Promise<void>;
+    sleep(ms: number): Promise<void>;
+    /** Whether any frames or sleep timers are currently pending. */
+    get pending(): boolean;
+    /** Advances time by `ms`, resolving due sleep timers in order, followed by queued frames. */
+    advance(ms: number): Promise<void>;
+    /** Convenience method to advance by 1 frame at a given fps (default: 60fps = 16.67ms). */
+    tick(fps?: number): Promise<void>;
+}
+
+/**
+ * Standard cubic ease-out function (pure math, framework-agnostic).
+ */
+declare const defaultEasing: (t: number) => number;
+/**
+ * Standard linear trajectory: straight line interpolation with linear scale & opacity progression.
+ */
+declare const linearTrajectory: TrajectoryFunction;
+/**
+ * Linear position trajectory: pure position interpolation without altering scale or opacity.
+ */
+declare const linearPositionTrajectory: TrajectoryFunction;
+/**
+ * Creates a fan-out trajectory where nodes arc outward from origin to target.
+ */
+declare function createFanOutTrajectory(options?: FanOutTrajectoryOptions): TrajectoryFunction;
+/**
+ * Creates a custom quadratic Bezier trajectory with a specified control point resolver.
+ */
+declare function createBezierTrajectory(getControlPoint: (origin: XYPosition, target: XYPosition) => XYPosition): TrajectoryFunction;
+
+/**
+ * Coordinates and animates multiple node transitions simultaneously with zero per-frame array allocations.
+ */
+declare function runMultiNodeTransition<TNode extends CanvasNode = CanvasNode>(transitions: NodeTransition<TNode>[], options?: {
+    defaultDuration?: number;
+    defaultEasing?: (t: number) => number;
+    clock?: Clock;
+    onUpdate?: () => void;
+    onComplete?: () => void;
+}): () => void;
+
+/**
+ * Calculates a bounding rectangle for a set of nodes if not provided by getNodesBounds.
+ */
+declare function computeNodesBoundingBox<TNode extends CanvasNode = CanvasNode>(nodes: TNode[], defaultWidth?: number, defaultHeight?: number): Rect;
+/**
+ * Pure directional displacement calculation.
+ * Shifts downstream or surrounding nodes along an axis to clear space for newly inserted child nodes.
+ */
+declare function calculateDirectionalDisplacement<TNode extends CanvasNode = CanvasNode>(params: {
+    existingNodes: TNode[];
+    originNode: TNode;
+    childNodes: TNode[];
+    getNodesBounds?: (nodes: TNode[]) => Rect;
+    options?: DirectionalDisplacementOptions;
+}): Map<string, XYPosition>;
+/**
+ * Calculates Dagre reflow displacement preserving the position of an anchor node.
+ */
+declare function calculateDagreReflowDisplacement<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge>(params: {
+    currentNodes: TNode[];
+    currentEdges: TEdge[];
+    futureNodes: TNode[];
+    futureEdges: TEdge[];
+    options: ReflowDisplacementOptions;
+    getNodesBounds?: (nodes: TNode[]) => Rect;
+}): Map<string, XYPosition>;
+
+/**
+ * Checks if an event originated from a text input, textarea, contenteditable element, or rich editor.
+ */
+declare function isEventFromTextInput(event: Event | {
+    target: EventTarget | null;
+}): boolean;
+/**
+ * Validates that an object conforms to minimal CanvasNode shape.
+ */
+declare function isValidCanvasNode(obj: unknown): obj is CanvasNode;
+/**
+ * Checks if a string is a valid HTTP/HTTPS URL.
+ */
+declare function isValidUrl(url: string): boolean;
+/**
+ * Serializes nodes and optional edges into clipboard JSON payload.
+ */
+declare function serializeCanvasNodes<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge>(nodes: TNode[], edges?: TEdge[]): string;
+/**
+ * Parses raw JSON string into a CanvasClipboardPayload if valid.
+ */
+declare function parseCanvasClipboardData<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge>(raw: string): CanvasClipboardPayload<TNode, TEdge> | null;
+/**
+ * Generates unique new IDs for pasted nodes and updates edge references accordingly.
+ */
+declare function remapPastedNodes<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge>(nodes: TNode[], edges?: TEdge[], offset?: XYPosition, idGenerator?: () => string): {
+    nodes: TNode[];
+    edges: TEdge[];
+};
+/**
+ * Repositions nodes so their bounding box origin matches the given target position.
+ */
+declare function repositionNodesTo<TNode extends CanvasNode = CanvasNode>(nodes: TNode[], targetOrigin: XYPosition): TNode[];
+
+interface StreamingLayoutManagerOptions {
+    throttleMs?: number;
+    glideDurationMs?: number;
+    connectedOnly?: boolean;
+    clock?: Clock;
+    layoutOptions?: IncrementalLayoutOptions;
+    onLayoutUpdated?: (positions: Map<string, XYPosition>) => void;
+}
+/**
+ * Manages throttled incremental layout recalculation and smooth tweened node gliding
+ * during active streaming (e.g. LLM streaming or graph generation).
+ */
+declare class StreamingLayoutManager<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge> {
+    private throttleMs;
+    private glideDurationMs;
+    private connectedOnly;
+    private clock;
+    private layoutOptions;
+    private onLayoutUpdated?;
+    private pendingTimer;
+    private activeTransitionCancel;
+    private targetPositions;
+    constructor(options?: StreamingLayoutManagerOptions);
+    /**
+     * Feed incoming nodes and edges into the streaming manager.
+     * Coalesces rapid streaming bursts and triggers smooth layout gliding.
+     */
+    pushStreamUpdate(nodes: TNode[], edges: TEdge[], currentPositions: Map<string, XYPosition>): void;
+    /**
+     * Forces immediate calculation and cancels pending throttled timers.
+     */
+    flush(nodes: TNode[], edges: TEdge[], currentPositions: Map<string, XYPosition>): void;
+    private recalculateAndGlide;
+    destroy(): void;
+}
+
+interface CanvasHeightOptions {
+    /** Smallest height returned (default 320). */
+    min?: number;
+    /** Largest height returned; taller content is scaled/zoomed (default 560). */
+    max?: number;
+    /** Extra padding around the content (default 48). */
+    padding?: number;
+}
+/**
+ * Calculates the bounding box extent of all positioned nodes, or `null` for an empty graph.
+ */
+declare function layoutBounds<TNode extends CanvasNode = CanvasNode>(nodes: TNode[]): Rect | null;
+/**
+ * Returns a clamped container height that fits the layout at 1:1 scale without overflow.
+ */
+declare function canvasHeight<TNode extends CanvasNode = CanvasNode>(nodes: TNode[], options?: CanvasHeightOptions): number;
+/**
+ * Estimates the container height to reserve before layout calculation finishes,
+ * based on node and edge counts alone. Prevents layout shift (CLS).
+ */
+declare function estimateCanvasHeight<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge>(nodes: TNode[], edges: TEdge[], options?: CanvasHeightOptions): number;
+/**
+ * Interpolates node positions and sizes between two layouts partway at progress `t` (0 = from, 1 = to).
+ * Nodes present in both interpolate smoothly; nodes newly added in `to` snap to target.
+ */
+declare function blendLayout<TNode extends CanvasNode = CanvasNode>(from: TNode[], to: TNode[], t: number): TNode[];
+/**
+ * Filters out nodes that are not touched by any edge.
+ *
+ * During LLM streaming, nodes often arrive a chunk or token before the edge
+ * that connects them. Displaying them immediately causes them to be placed as root
+ * nodes only to jump into their correct position once the edge arrives.
+ * Hiding orphan nodes during active streaming keeps the layout calm and jitter-free.
+ */
+declare function connectedOnly<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge>(nodes: TNode[], edges: TEdge[]): TNode[];
+
+export { CanvasClipboardPayload, CanvasEdge, type CanvasHeightOptions, CanvasLayoutOptions, CanvasNode, type Clock, DEFAULT_NODE_HEIGHT, DEFAULT_NODE_WIDTH, DEFAULT_PLACEMENT_GAP, DirectionalDisplacementOptions, FanOutTrajectoryOptions, IncrementalLayoutOptions, ManualClock, NodeTransition, PlaceBesideOptions, Rect, ReflowDisplacementOptions, Side, StreamingLayoutManager, type StreamingLayoutManagerOptions, TrajectoryFunction, XYPosition, blendLayout, boundsOf, calculateDagreReflowDisplacement, calculateDirectionalDisplacement, canvasHeight, centerNodes, centre, computeNodesBoundingBox, connectedOnly, createBezierTrajectory, createFanOutTrajectory, defaultEasing, ensureLayout, estimateCanvasHeight, estimateNodeSize, flowSide, getCenteredNodePosition, getLayoutedNodes, isEventFromTextInput, isValidCanvasNode, isValidUrl, layoutBounds, linearPositionTrajectory, linearTrajectory, overlaps, pageHidden, parseCanvasClipboardData, placeBeside, realClock, remapPastedNodes, repositionNodesTo, runMultiNodeTransition, serializeCanvasNodes };