@pixerate/editor 0.280.0 → 0.282.0

package/dist/canvas/edgeAnimation.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Animated canvas edges: dots travelling along an edge, marching dashes, beams of light and a
+ * pulsing glow. An edge's animation is data (`edge.data.animation`, a {@link CanvasEdgeAnimation}),
+ * so it saves, undoes and copies with the edge. {@link getCanvasEdgeAnimationRender} turns it into a
+ * framework-neutral list of SVG elements with SMIL timing, which `<AnimatedEdge>` /
+ * `<EdgeAnimation>` (React and Svelte) render; {@link sampleCanvasEdgeAnimation} gives the same
+ * picture at a moment in time without a browser (thumbnails, exports, tests, reduced motion).
+ */
+import type { CanvasConnectionLineType } from './connectors.js';
+import { type MeasuredSvgPath, type SvgPathPoint } from './edgePaths.js';
+/** What travels along the edge. */
+export type CanvasEdgeAnimationKind = 'dots' | 'dash' | 'beam' | 'pulse';
+/** Which way the animation runs: source → target, target → source, or back and forth. */
+export type CanvasEdgeAnimationDirection = 'forward' | 'reverse' | 'alternate';
+/** An edge's animation, stored at `edge.data.animation`. Every field but `kind` is optional. */
+export interface CanvasEdgeAnimation {
+    kind: CanvasEdgeAnimationKind;
+    /** Travel speed in canvas units per second (`dots`, `dash`, `beam`). Defaults per kind. */
+    speed?: number;
+    /** Length of one cycle in ms; overrides `speed` (and is the only timing for `pulse`). */
+    duration?: number;
+    /** Default `forward` (source → target). */
+    direction?: CanvasEdgeAnimationDirection;
+    /** CSS colour. Default: the edge's stroke. */
+    color?: string;
+    /** Dot radius, or the stroke width of dashes, beams and the pulse, in canvas units. Defaults per kind. */
+    size?: number;
+    /** Number of dots or beams on the edge at once. Defaults per kind. */
+    count?: number;
+    /** Dash or beam length, in canvas units. Defaults per kind. */
+    length?: number;
+    /** Gap between dashes, in canvas units (`dash`). Default 6. */
+    gap?: number;
+    /** Glow radius (a blur behind the moving part), in canvas units. 0 is none. Defaults per kind. */
+    glow?: number;
+    /** Opacity of the edge's own stroke under the animation, 0–1. Default 1. */
+    trackOpacity?: number;
+    /** Held still at its first frame. Default false. */
+    paused?: boolean;
+}
+export interface CanvasEdgeAnimationKindInfo {
+    kind: CanvasEdgeAnimationKind;
+    title: string;
+    description: string;
+    /** The values used for fields an animation leaves out. */
+    defaults: Required<Omit<CanvasEdgeAnimation, 'kind' | 'color' | 'duration' | 'paused'>> & {
+        duration?: number;
+    };
+}
+/** The animation kinds, with what they look like and their defaults. */
+export declare const CANVAS_EDGE_ANIMATION_KINDS: readonly CanvasEdgeAnimationKindInfo[];
+/**
+ * Checks an animation and returns a clean copy (unknown fields dropped). Throws an error that says
+ * which field is wrong and what it accepts.
+ */
+export declare function normalizeCanvasEdgeAnimation(input: unknown): CanvasEdgeAnimation;
+/** The edge's animation, or null when it has none or it is not valid. */
+export declare function getCanvasEdgeAnimation(edge: {
+    data?: Record<string, any>;
+} | null | undefined): CanvasEdgeAnimation | null;
+/** A copy of the edge with its animation set (checked first), or removed when `animation` is null. */
+export declare function setCanvasEdgeAnimation<TEdge extends {
+    data?: Record<string, any>;
+}>(edge: TEdge, animation: CanvasEdgeAnimation | null): TEdge;
+/** The animation with every default filled in, as it will play. */
+export declare function resolveCanvasEdgeAnimation(animation: CanvasEdgeAnimation): Required<Omit<CanvasEdgeAnimation, 'color' | 'duration'>> & Pick<CanvasEdgeAnimation, 'color' | 'duration'>;
+/** SMIL timing for an element: rendered as `<animate>` / `<animateMotion>` children. */
+export interface CanvasEdgeAnimationTiming {
+    /** Seconds per cycle (SMIL `dur`). */
+    dur: number;
+    /** Start offset in seconds; negative starts part-way through (SMIL `begin`). */
+    begin: number;
+}
+/** One SVG element of an animated edge. Coordinates are canvas units. */
+export type CanvasEdgeAnimationElement = {
+    type: 'dot';
+    key: string;
+    r: number;
+    fill: string;
+    filter?: string;
+    /** Where the dot is at the first frame (used when paused or with reduced motion). */
+    at: SvgPathPoint;
+    /** Travel along the path: `keyPoints` / `keyTimes` for `<animateMotion>`. */
+    motion: CanvasEdgeAnimationTiming & {
+        keyPoints: string;
+        keyTimes: string;
+    };
+} | {
+    type: 'stroke';
+    key: string;
+    stroke: string;
+    strokeWidth: number;
+    strokeLinecap: 'round' | 'butt';
+    strokeDasharray?: string;
+    strokeDashoffset?: number;
+    opacity?: number;
+    filter?: string;
+    /** `<animate>`s to add: attribute, values (`;`-separated, SMIL), timing. */
+    animate: Array<CanvasEdgeAnimationTiming & {
+        attributeName: 'stroke-dashoffset' | 'stroke-opacity' | 'stroke-width';
+        values: string;
+    }>;
+};
+export interface CanvasEdgeAnimationRender {
+    kind: CanvasEdgeAnimationKind;
+    /** Path length in canvas units. */
+    length: number;
+    /** Opacity for the edge's own stroke. */
+    trackOpacity: number;
+    /** Whether the elements should move (false when paused, reduced motion or a zero-length path). */
+    moving: boolean;
+    /**
+     * A blur filter to define in `<defs>` when anything glows. Its region is in user space (canvas
+     * units, `filterUnits="userSpaceOnUse"`): a straight edge has a zero-height box, and a filter
+     * sized to the box would hide it.
+     */
+    glowFilter?: {
+        id: string;
+        stdDeviation: number;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    elements: CanvasEdgeAnimationElement[];
+}
+export interface CanvasEdgeAnimationRenderOptions {
+    /** SVG path data of the edge (`getCanvasEdgePath(...).path` or the path your edge draws). */
+    path: string;
+    /** A unique id for this edge's defs (the edge id). */
+    id: string;
+    /** Colour used when the animation has none (the edge's stroke). Default `currentColor`. */
+    stroke?: string;
+    /** Draw the first frame without movement (honour `prefers-reduced-motion`). Default false. */
+    reducedMotion?: boolean;
+    /** A measured path to reuse, when you already have one for `path`. */
+    measured?: MeasuredSvgPath;
+}
+/**
+ * How to draw an animated edge: SVG elements and SMIL timing, computed from the path. Dots use
+ * `<animateMotion>` along the path, dashes and beams animate `stroke-dashoffset`, the pulse animates
+ * opacity and width. Nothing here needs a DOM; the React and Svelte `<EdgeAnimation>` render it.
+ */
+export declare function getCanvasEdgeAnimationRender(animation: CanvasEdgeAnimation, options: CanvasEdgeAnimationRenderOptions): CanvasEdgeAnimationRender;
+/** The animated part of an edge at one moment. */
+export interface CanvasEdgeAnimationFrame {
+    kind: CanvasEdgeAnimationKind;
+    length: number;
+    /** Dot positions (`dots`). */
+    dots: SvgPathPoint[];
+    /** Visible stretches of the path as [from, to] distances (`dash`, `beam`), clipped to the path. */
+    segments: Array<[number, number]>;
+    /** Stroke opacity and width (`pulse`). */
+    opacity: number;
+    strokeWidth: number;
+}
+/**
+ * Where everything is `timeMs` into the animation: the same picture the SVG shows at that time,
+ * computed without a browser (for thumbnails, exports, canvas renderers and tests). A paused
+ * animation always returns its first frame.
+ */
+export declare function sampleCanvasEdgeAnimation(animation: CanvasEdgeAnimation, path: string | MeasuredSvgPath, timeMs: number): CanvasEdgeAnimationFrame;
+/** Edge path styles `<AnimatedEdge>` can draw (read from `edge.data.pathType`). */
+export type CanvasAnimatedEdgePathType = CanvasConnectionLineType;

package/dist/canvas/edgePaths.d.cts

@@ -0,0 +1,63 @@
+/**
+ * Edge path geometry for canvas edges, matching xyflow's (`getBezierPath`, `getStraightPath`,
+ * `getSimpleBezierPath`, `getSmoothStepPath`) so the same path is drawn with or without React Flow /
+ * Svelte Flow, plus a small SVG path measurer (`measureSvgPath`) for placing things along a path.
+ * No DOM and no xyflow import.
+ */
+import type { CanvasConnectionLineType } from './connectors.cjs';
+import type { Position } from './types.cjs';
+export interface CanvasEdgePathParams {
+    sourceX: number;
+    sourceY: number;
+    targetX: number;
+    targetY: number;
+    /** Side of the source node the edge leaves from. Default `bottom`. */
+    sourcePosition?: Position;
+    /** Side of the target node the edge enters. Default `top`. */
+    targetPosition?: Position;
+    /** Path style, as xyflow's edge `type`. Default `default` (bézier). */
+    type?: CanvasConnectionLineType;
+    /** Bézier curvature (`default`). Default 0.25. */
+    curvature?: number;
+    /** Corner radius for `smoothstep`, in canvas units. Default 5 (`step` is 0). */
+    borderRadius?: number;
+    /** Distance the step paths run straight out of a handle before turning, in canvas units. Default 20. */
+    offset?: number;
+}
+export interface CanvasEdgePath {
+    /** SVG path data. */
+    path: string;
+    /** Where a label sits (xyflow's `labelX` / `labelY`). */
+    labelX: number;
+    labelY: number;
+}
+/**
+ * The SVG path of a canvas edge, the same as xyflow draws for that edge `type` (`default` bézier,
+ * `straight`, `step`, `smoothstep`, `simplebezier`), with the label position.
+ */
+export declare function getCanvasEdgePath(params: CanvasEdgePathParams): CanvasEdgePath;
+/** A point on a path with the direction of travel there (radians, 0 = +x). */
+export interface SvgPathPoint {
+    x: number;
+    y: number;
+    angle: number;
+}
+export interface MeasuredSvgPath {
+    /** Total length in path units. */
+    length: number;
+    /** Bounding box of the flattened path. */
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** The point `distance` along the path (clamped to [0, length]). */
+    pointAt(distance: number): SvgPathPoint;
+}
+/**
+ * Measures SVG path data (M, L, H, V, C, S, Q, T, Z, absolute or relative; arcs are drawn as
+ * straight lines). Curves are flattened to `segments` pieces each (default 24), which is well under
+ * a canvas unit of error for edge-sized curves.
+ */
+export declare function measureSvgPath(d: string, segments?: number): MeasuredSvgPath;

package/dist/canvas/edgePaths.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Edge path geometry for canvas edges, matching xyflow's (`getBezierPath`, `getStraightPath`,
+ * `getSimpleBezierPath`, `getSmoothStepPath`) so the same path is drawn with or without React Flow /
+ * Svelte Flow, plus a small SVG path measurer (`measureSvgPath`) for placing things along a path.
+ * No DOM and no xyflow import.
+ */
+import type { CanvasConnectionLineType } from './connectors.js';
+import type { Position } from './types.js';
+export interface CanvasEdgePathParams {
+    sourceX: number;
+    sourceY: number;
+    targetX: number;
+    targetY: number;
+    /** Side of the source node the edge leaves from. Default `bottom`. */
+    sourcePosition?: Position;
+    /** Side of the target node the edge enters. Default `top`. */
+    targetPosition?: Position;
+    /** Path style, as xyflow's edge `type`. Default `default` (bézier). */
+    type?: CanvasConnectionLineType;
+    /** Bézier curvature (`default`). Default 0.25. */
+    curvature?: number;
+    /** Corner radius for `smoothstep`, in canvas units. Default 5 (`step` is 0). */
+    borderRadius?: number;
+    /** Distance the step paths run straight out of a handle before turning, in canvas units. Default 20. */
+    offset?: number;
+}
+export interface CanvasEdgePath {
+    /** SVG path data. */
+    path: string;
+    /** Where a label sits (xyflow's `labelX` / `labelY`). */
+    labelX: number;
+    labelY: number;
+}
+/**
+ * The SVG path of a canvas edge, the same as xyflow draws for that edge `type` (`default` bézier,
+ * `straight`, `step`, `smoothstep`, `simplebezier`), with the label position.
+ */
+export declare function getCanvasEdgePath(params: CanvasEdgePathParams): CanvasEdgePath;
+/** A point on a path with the direction of travel there (radians, 0 = +x). */
+export interface SvgPathPoint {
+    x: number;
+    y: number;
+    angle: number;
+}
+export interface MeasuredSvgPath {
+    /** Total length in path units. */
+    length: number;
+    /** Bounding box of the flattened path. */
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** The point `distance` along the path (clamped to [0, length]). */
+    pointAt(distance: number): SvgPathPoint;
+}
+/**
+ * Measures SVG path data (M, L, H, V, C, S, Q, T, Z, absolute or relative; arcs are drawn as
+ * straight lines). Curves are flattened to `segments` pieces each (default 24), which is well under
+ * a canvas unit of error for edge-sized curves.
+ */
+export declare function measureSvgPath(d: string, segments?: number): MeasuredSvgPath;