@pixodesk/svg-animator-web 1.0.6

package/dist/index.d.cts

@@ -0,0 +1,396 @@
+type FillMode = 'forwards' | 'backwards' | 'both' | 'none';
+type PlaybackDirection = 'normal' | 'reverse' | 'alternate' | 'alternate-reverse';
+declare const PX_ANIM_SRC_ATTR_NAME = "data-px-animation-src";
+declare const PX_ANIM_ATTR_NAME = "_px_animator";
+/**
+ * Easing function definition.
+ * Can be a named reference to a predefined easing or a cubic-bezier array [x1, y1, x2, y2].
+ *
+ * @example "ease-in" | "easeOut" | [0.68, -0.55, 0.265, 1.55]
+ */
+type PxEasingOrRef = string | [number, number, number, number];
+/**
+ * A single animation keyframe defining the state at a specific point in time.
+ * Supports both full property names and short aliases for compact notation.
+ */
+interface PxKeyframe {
+    /** Timestamp in milliseconds from animation start */
+    time?: number;
+    /** Short alias for "time" */
+    t?: number;
+    /** The value of the animated property at this keyframe */
+    value?: any;
+    /** Short alias for "value" */
+    v?: any;
+    /** Easing function to use when transitioning to this keyframe from the previous one */
+    easing?: PxEasingOrRef;
+    /** Short alias for "easing" */
+    e?: PxEasingOrRef;
+}
+/**
+ * Animation definition for a single CSS/SVG property.
+ * Contains an array of keyframes that define how the property changes over time.
+ */
+interface PxPropertyAnimation {
+    /** Array of keyframes defining the animation timeline */
+    keyframes?: PxKeyframe[];
+    /** Short alias for "keyframes" */
+    kfs?: PxKeyframe[];
+}
+/**
+ * Complete animation definition containing one or more property animations.
+ * Each key is a CSS/SVG property name (e.g., "opacity", "scale", "rotate").
+ *
+ * @example
+ * {
+ *   "opacity": { keyframes: [...] },
+ *   "scale": { keyframes: [...] }
+ * }
+ */
+interface PxAnimationDefinition {
+    [property: string]: PxPropertyAnimation;
+}
+/**
+ * Defines when and how an animation should be triggered.
+ */
+interface PxTrigger {
+    /** Event that starts the animation */
+    startOn?: 'load' | 'mouseOver' | 'click' | 'scrollIntoView' | 'programmatic';
+    /** Action to take when the trigger condition is no longer met (e.g., mouse leaves) */
+    outAction?: 'continue' | 'pause' | 'reset' | 'reverse';
+    /** Percentage of element visibility required to trigger (0-1). Only applies to scrollIntoView. */
+    scrollIntoViewThreshold?: number;
+}
+/**
+ * Global animation configuration that applies to all animations in the document.
+ * Defines timing, playback behavior, and rendering strategy.
+ */
+interface PxAnimatorConfig {
+    /** JavaScript animation implementation strategy */
+    mode?: "auto" | "webapi" | "frames";
+    /** Total animation duration in milliseconds */
+    duration?: number;
+    /** Delay before animation starts in milliseconds */
+    delay?: number;
+    /** Number of times to repeat the animation. Use "infinite" for endless loop. */
+    iterations?: number | "infinite";
+    /** Defines which values are applied before/after the animation */
+    fill?: FillMode;
+    /** Direction of animation playback */
+    direction?: PlaybackDirection;
+    /** Target frame rate for frame-based animations (only applicable when mode="frames") */
+    frameRate?: number;
+    /** Trigger configuration for when animation should start */
+    trigger?: PxTrigger;
+    debug?: boolean;
+    debugInstName?: string;
+}
+/**
+ * Reusable definitions library for easings, animations, and styles.
+ * Allows to define once and referencing by name.
+ */
+interface PxDefs {
+    /** Named cubic-bezier easing functions */
+    easings?: {
+        [name: string]: [number, number, number, number];
+    };
+    /** Named animation definitions that can be referenced by elements */
+    animations?: {
+        [name: string]: PxAnimationDefinition;
+    };
+    /**
+     * FIXME - do we need it?
+     * Named style presets for common styling patterns
+     */
+    styles?: {
+        [name: string]: Record<string, string | number>;
+    };
+}
+/**
+ * Element animation specification.
+ * Can be:
+ * - A string referencing a named animation from defs
+ * - An array of named animation references
+ * - An inline PxAnimationDefinition object
+ * - A mixed array of references and inline definitions
+ *
+ * @example
+ * "fadeIn"
+ * ["fadeIn", "spin"]
+ * { opacity: { keyframes: [...] } }
+ * ["fadeIn", { scale: { keyframes: [...] } }]
+ */
+type PxElementAnimation = string | string[] | PxAnimationDefinition | (string | PxAnimationDefinition)[];
+/**
+ * Base interface for all SVG elements.
+ * Represents a node in the SVG tree with optional animations and children.
+ */
+interface PxNode {
+    /** SVG element type (e.g., "circle", "rect", "path", "g") */
+    type: string;
+    /** Child elements (for container elements like <g>) */
+    children?: PxNode[];
+    /** Animation applied to this element */
+    animate?: PxElementAnimation;
+    /**
+     * FIXME - do we need it?
+     * Style applied to this element (named reference or inline object)
+     */
+    style?: string | Record<string, string | number>;
+    /** All other SVG attributes (cx, cy, r, fill, stroke, etc.) */
+    [key: string]: any;
+}
+/**
+ * Binds animations to existing DOM elements via CSS selectors.
+ * Used when the SVG tree is pre-rendered and animations are applied separately.
+ */
+interface PxBinding {
+    /** ID targeting elements in the DOM (data-px-id="...") */
+    id: string;
+    /** Animation to apply to matched elements */
+    animate: PxElementAnimation;
+}
+/**
+ * Root SVG element containing the entire animated graphic.
+ * Extends PxNode with SVG-specific properties and global configuration.
+ */
+interface PxSvgNode extends PxNode {
+    /** FIXME - do we need it?
+     * SVG viewport width */
+    width?: number;
+    /** FIXME - do we need it?
+     * SVG viewport height */
+    height?: number;
+    /** FIXME - do we need it?
+     * SVG viewBox attribute defining coordinate system */
+    viewBox?: string;
+    /** Global animation configuration */
+    animator?: PxAnimatorConfig;
+    /** Reusable definitions library */
+    defs?: PxDefs;
+    /** Animation bindings for pre-rendered DOM elements */
+    bindings?: PxBinding[];
+    design?: PxNode;
+}
+/**
+ * The complete animated SVG document.
+ * This is the root type for the entire file format.
+ */
+interface PxAnimatedSvgDocument extends PxSvgNode {
+}
+/** A configuration object for animation lifecycle callbacks. */
+interface PxAnimatorCallbacksConfig {
+    /** Callback executed when the animation starts or resumes. */
+    onPlay?: () => void;
+    /** Callback executed when the animation is paused. */
+    onPause?: () => void;
+    /** Callback executed when the animation is cancelled. */
+    onCancel?: () => void;
+    /** Callback executed when the animation finishes naturally. */
+    onFinish?: () => void;
+    /** Callback executed when the animation is removed. */
+    onRemove?: () => void;
+}
+type PxPoint2D = Array<number>;
+/** Represents a vector path for SVG shape animations. */
+interface PxBezierPath {
+    /** An array of vertex points [[x, y], ...]. */
+    v: Array<PxPoint2D>;
+    /** An array of 'in' tangent handles for each vertex [[x, y], ...]. */
+    i?: Array<PxPoint2D>;
+    /** An array of 'out' tangent handles for each vertex [[x, y], ...]. */
+    o?: Array<PxPoint2D>;
+    /** A boolean indicating if the path is closed. */
+    c?: boolean;
+}
+/** Basic animation controls common to all animator types. */
+interface PxBasicAnimatorAPI {
+    isReady(): boolean;
+    /** Returns the root HTML element for the animation. */
+    getRootElement(): Element | null;
+    /** Returns true if the animation is currently running. */
+    isPlaying(): boolean;
+    /** Starts or resumes the animation. */
+    play(): void;
+    /** Pauses the animation at its current state. */
+    pause(): void;
+    /** Stops the animation and resets it to its initial state. */
+    cancel(): void;
+}
+/** The full programmatic control interface for an animation. */
+interface PxAnimatorAPI extends PxBasicAnimatorAPI {
+    /** Jumps to the end of the animation and holds the final state. */
+    finish(): void;
+    /** Changes the speed of the animation. 1 is normal, 2 is double, -1 is reverse. */
+    setPlaybackRate(rate: number): void;
+    /** Returns the current playback time in milliseconds. */
+    getCurrentTime(): number | null;
+    /** Jumps to a specific time (in milliseconds) in the animation. */
+    setCurrentTime(time: number): void;
+    /** Stops the animation and cleans up all associated resources. */
+    destroy(): void;
+}
+declare function isPxElementFileFormat(fileJson: any): fileJson is PxAnimatedSvgDocument;
+interface PxValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Deep validation of PxAnimatedSvgDocument.
+ * Validates all nested properties against their type definitions.
+ * @returns PxValidationResult with valid flag and array of error messages
+ */
+declare function isPxElementFileFormatDeep(fileJson: any): PxValidationResult;
+declare function getAnimatorConfig(doc: PxAnimatedSvgDocument): PxAnimatorConfig | undefined;
+declare function getDefs(doc: PxAnimatedSvgDocument): PxDefs | undefined;
+declare function getBindings(doc: PxAnimatedSvgDocument): PxBinding[] | undefined;
+declare function getChildren(doc: PxAnimatedSvgDocument): PxNode[] | undefined;
+
+/**
+ * Platform adapter interface for abstracting DOM-specific operations.
+ */
+interface PxPlatformAdapter {
+    /** Check if the root element is still connected/mounted */
+    isConnected(): boolean;
+    /** Set an attribute on an element by id */
+    setAttribute(id: string, attrName: string, value: string): void;
+}
+/**
+ * Creates an animator instance that uses a frame loop for animations.
+ * This is the abstract/platform-agnostic version.
+ *
+ * @param adapter Platform adapter for DOM/environment operations.
+ * @param callbacks Optional lifecycle callbacks.
+ * @returns A PxAnimatorAPI instance.
+ */
+declare function createBasicFrameLoopAnimator(doc: PxAnimatedSvgDocument, adapter: PxPlatformAdapter, callbacks?: PxAnimatorCallbacksConfig): PxAnimatorAPI;
+/**
+ * Creates an animator instance that uses a requestAnimationFrame loop for animations.
+ * This is the browser DOM-specific version.
+ *
+ * @param {PxAnimatorCallbacksConfig=} callbacks Optional lifecycle callbacks.
+ * @param {Element=} rootElement Optional pre-rendered root element.
+ * @returns {PxAnimatorAPI} A PxAnimatorAPI instance.
+ */
+declare function createFrameLoopAnimator(doc: PxAnimatedSvgDocument, adapter?: PxPlatformAdapter, callbacks?: PxAnimatorCallbacksConfig, rootElement?: Element | null): PxAnimatorAPI;
+
+/**
+ * Regenerates all IDs in the document and updates references.
+ *
+ * This function:
+ * 1. Deep clones the document to avoid mutating the original
+ * 2. Traverses all nodes and regenerates IDs, keeping a mapping of old → new
+ * 3. Updates all references to old IDs in attributes:
+ *    - Hash references: "#old-id" → "#new-id" (href, xlink:href)
+ *    - URL references: "url(#old-id)" → "url(#new-id)" (fill, clip-path, mask, marker, etc.)
+ *    - Style URL references: { offsetPath: "url(#old-id)" }
+ *
+ * @param doc - The animated SVG document to process
+ * @returns A new document with regenerated IDs
+ */
+declare function generateNewIds(doc: PxAnimatedSvgDocument): PxAnimatedSvgDocument;
+/**
+ * Creates an animator instance from an AnimatedSvgDocument.
+ *
+ * This function serves as the main entry point for the animation library. It automatically
+ * chooses the best animation engine available ('webapi' or 'frames') or can be
+ * forced to use a specific one.
+ *
+ * @param doc The animated SVG document.
+ * @param callbacks Optional object with callback functions for animation lifecycle events (play, pause, finish, etc.).
+ * @param containerElement Optional selector or element to render the SVG into.
+ * @returns An PxAnimatorAPI instance to programmatically control the animation.
+ */
+declare function createAnimatorImpl(doc: PxAnimatedSvgDocument, adapter?: PxPlatformAdapter, callbacks?: PxAnimatorCallbacksConfig, containerElement?: string | Element): PxAnimatorAPI;
+/**
+ * Creates an animator instance to control SVG animations.
+ * Accepts either a document object or a URL to fetch.
+ *
+ * @param docOrUrl The animated SVG document or URL to fetch it from.
+ * @param callbacks Optional object with callback functions for animation lifecycle events.
+ * @param containerElement Optional selector or element to render the SVG into.
+ * @returns An PxAnimatorAPI instance to programmatically control the animation.
+ */
+declare function createAnimator(docOrUrl: PxAnimatedSvgDocument | string, adapter?: PxPlatformAdapter, callbacks?: PxAnimatorCallbacksConfig, containerElement?: string | Element): PxAnimatorAPI;
+/**
+ * Scan and load for tags, e.g.
+ *  <div data-px-animation-src="animation.json"></div>
+ */
+declare function loadTagAnimators(): void;
+
+/**
+ * Converts a color from a [r, g, b, a] array (where values are 0-1) to an rgba() or rgb() CSS string.
+ * @param color The color array.
+ */
+declare function toRGBA(color: Array<number>): string;
+declare const COLOUR_ATTR_NAMES: Set<string>;
+declare const TRANSFORM_FN_NAMES: Set<string>;
+declare const STYLE_ATTR_NAMES: Set<string>;
+/**
+ * Converts a camelCase string to kebab-case.
+ * @param camel The camelCase string.
+ */
+declare function camelCaseToKebabWordIfNeeded(camel: string): string;
+
+/**
+ * Sets up event-based triggers for an animation.
+ *
+ * This function attaches event listeners to the animation's root element based on the
+ * provided configuration, allowing animations to be started by user interactions
+ * or visibility changes.
+ *
+ * ### Trigger Options (startOn):
+ * - 'load': Starts after the page loads.
+ * - 'mouseOver': Starts on mouse enter.
+ * - 'click': Toggles play/end action on click.
+ * - 'scrollIntoView': Starts when the element scrolls into the viewport.
+ * - 'programmatic': No automatic start. Must be controlled via the API.
+ *
+ * ### End Action Options (outAction):
+ * Defines behavior when the trigger condition ends (e.g., mouse leave).
+ * - 'continue': Animation continues playing.
+ * - 'pause': Pauses the animation.
+ * - 'reset': Cancels the animation, resetting it to the start.
+ * - 'reverse': Reverses the animation playback.
+ *
+ * @param {!PxAnimatorAPI} api The animator API instance to control.
+ * @param {!PxTrigger} config The trigger configuration object.
+ * @returns {!PxAnimatorAPI} The same animator API instance, for chaining.
+ */
+declare function setupAnimationTriggers(api: PxAnimatorAPI, config: PxTrigger): PxAnimatorAPI;
+
+/**
+ * Normalizes a PxAnimatedSvgDocument to a PxAnimatorConfig for the animation engines.
+ * This is the main entry point for converting the new API format to internal format.
+ * Resolves animation/easing references.
+ */
+declare function getNormalisedBindings(doc: PxAnimatedSvgDocument): PxBinding[];
+/**
+ * Calculates interpolated attribute values for an animation definition.
+ * @param animDef The animation definition (with resolved refs and normalized times)
+ * @param progress The current animation progress (0-1)
+ * @returns Object with computed attribute name/value pairs
+ */
+declare function calcAnimationValues(animDef: PxAnimationDefinition, progress: number): Record<string, string>;
+
+declare function getNormalizedProps(props: Record<string, any>): Record<string, any>;
+/**
+ * Renders a PxNode tree to DOM elements.
+ */
+declare function renderNode(node: PxNode, defs?: PxDefs): Element | null;
+
+/**
+ * Creates an animator instance that uses the native Web Animations API.
+ *
+ * This is the preferred, more performant animator. It will return null if the
+ * animation configuration contains properties not supported by the browser's
+ * Web Animations API implementation, unless forceEvenIfHasUnsupportedAttrs is true.
+ *
+ * @param callbacks Optional lifecycle callbacks.
+ * @param rootElement Root element.
+ * @param forceEvenIfHasUnsupportedAttrs If true, an animator will be created even if some CSS properties are not supported.
+ * @returns An PxAnimatorAPI instance, or null if unsupported features are used and not forced.
+ */
+declare function createWebApiAnimator(doc: PxAnimatedSvgDocument, callbacks?: PxAnimatorCallbacksConfig, rootElement?: Element | null, forceEvenIfHasUnsupportedAttrs?: boolean): PxAnimatorAPI | null;
+
+export { COLOUR_ATTR_NAMES, type FillMode, PX_ANIM_ATTR_NAME, PX_ANIM_SRC_ATTR_NAME, type PlaybackDirection, type PxAnimatedSvgDocument, type PxAnimationDefinition, type PxAnimatorAPI, type PxAnimatorCallbacksConfig, type PxAnimatorConfig, type PxBezierPath, type PxBinding, type PxDefs, type PxElementAnimation, type PxKeyframe, type PxNode, type PxPlatformAdapter, type PxPropertyAnimation, type PxSvgNode, type PxTrigger, type PxValidationResult, STYLE_ATTR_NAMES, TRANSFORM_FN_NAMES, calcAnimationValues, camelCaseToKebabWordIfNeeded, createAnimator, createAnimatorImpl, createBasicFrameLoopAnimator, createFrameLoopAnimator, createWebApiAnimator, generateNewIds, getAnimatorConfig, getBindings, getChildren, getDefs, getNormalizedProps, isPxElementFileFormat, isPxElementFileFormatDeep, loadTagAnimators, getNormalisedBindings as normalizeDocument, renderNode, setupAnimationTriggers, toRGBA };