@pixodesk/svg-animator-rn 1.0.21

package/dist/index.d.cts

@@ -0,0 +1,158 @@
+import { PxAnimatedSvgDocument, FillMode, PlaybackDirection, PxNode } from '@pixodesk/svg-animator-core';
+import React, { ReactElement, ComponentType, ReactNode } from 'react';
+
+/** Imperative playback API — mirrors ReactAnimatorApi from svg-animator-react. */
+interface RnAnimatorApi {
+    /** 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;
+    /** 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. */
+    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;
+}
+interface PixodeskSvgAnimatorProps {
+    /** The animation document to render. */
+    doc: PxAnimatedSvgDocument;
+    /** Duration of a single iteration in milliseconds. */
+    duration?: number;
+    /** Delay before the animation starts, in milliseconds. */
+    delay?: number;
+    /** Number of iterations, or 'infinite' for endless looping. */
+    iterations?: number | 'infinite';
+    /** Defines the element's state when the animation is not active. */
+    fill?: FillMode;
+    /** Playback direction. */
+    direction?: PlaybackDirection;
+    /** When true, honours the document trigger (`startOn: 'load'` plays on mount). */
+    autoplay?: boolean;
+    /** Starts playback unconditionally. */
+    play?: boolean;
+    /** Pauses current playback. */
+    pause?: boolean;
+    /** Ref populated with the imperative playback API. */
+    apiRef?: React.RefObject<RnAnimatorApi | null>;
+    /** Seek to a fraction (0–1) of the whole timeline (duration × iterations). */
+    time?: number;
+    /** Seek to a specific time in milliseconds. */
+    timeMs?: number;
+    onPlay?: () => void;
+    onStop?: () => void;
+    onPause?: () => void;
+    onCancel?: () => void;
+    onFinish?: () => void;
+}
+/**
+ * React Native component for rendering and controlling Pixodesk SVG animations.
+ *
+ * The document is materialised once through the shared core pipeline (effects,
+ * loops, motion-path sampling, animated-`<use>` inlining — identical to the
+ * web frames engine), compiled into densely sampled per-element tracks, and
+ * played back natively: a single reanimated progress value driven by
+ * `withTiming`/`withRepeat` on the UI thread, with per-element worklets
+ * indexing the precompiled tracks. No JS-thread frame loop.
+ */
+declare function PixodeskSvgAnimator({ doc, duration, delay, iterations, fill, direction, autoplay, play, pause, apiRef, time, timeMs, onPlay, onStop, onPause, onCancel, onFinish, }: PixodeskSvgAnimatorProps): ReactElement | null;
+
+interface RenderRnNodeOptions {
+    /** Collects non-fatal issues (unsupported tags, dropped attrs). */
+    warnings?: Array<string>;
+    /**
+     * Wraps the created element for animated nodes: receives the resolved
+     * component + static props and returns the element to mount (the animator
+     * substitutes an Animated component wired to its tracks). Return undefined
+     * to keep the plain static element.
+     */
+    decorate?: (node: PxNode, Component: ComponentType<any>, props: Record<string, any>, children: ReactNode) => ReactElement | undefined;
+}
+/**
+ * Converts core-normalised wire props into react-native-svg props: RN prop
+ * naming, sanitisation (same security rules as the web renderer), numeric
+ * coercion where possible.
+ */
+declare function toRnProps(props: Record<string, any>, warnings?: Array<string>): Record<string, any>;
+/**
+ * Renders a (materialised) PxNode tree to react-native-svg elements.
+ * Mirrors the web `renderNode` contract: unsupported/dangerous tags are
+ * skipped with a warning, never a crash.
+ */
+declare function renderRnNode(node: PxNode, opts?: RenderRnNodeOptions, key?: string | number): ReactElement | null;
+
+/**
+ * Sampled animation tracks for ONE element: prop name → per-sample values.
+ *
+ * The compiler densely samples every animated property through core's
+ * `calcAnimationValues` — the exact function the web frames engine renders
+ * with — so RN playback is value-identical to the web player. Easing, loops,
+ * transform composition, colour interpolation and path morphing are all baked
+ * into the samples at compile time; the UI-thread worklet only indexes arrays.
+ */
+interface PxElementTracks {
+    /** Element id (after id regeneration). */
+    id: string;
+    /** react-native-svg prop name → one value per sample. */
+    props: Record<string, Array<string | number | Array<number>>>;
+}
+interface PxCompiledTracks {
+    /** Per-iteration duration, ms. */
+    duration: number;
+    /** Iteration count (Infinity for 'infinite'). */
+    iterations: number;
+    /** 'normal' | 'reverse' | 'alternate' | 'alternate-reverse' */
+    direction: string;
+    /** Delay before start, ms (positive = wait). */
+    delay: number;
+    /** WAAPI-style fill mode (default 'forwards'). */
+    fill: string;
+    /** Sample step, ms. */
+    stepMs: number;
+    /** Number of samples per iteration (>= 2; sample i is at time i*stepMs). */
+    sampleCount: number;
+    /** Tracks for every animated element. */
+    elements: Array<PxElementTracks>;
+}
+interface CompileTracksOptions {
+    /** Target sample rate, samples/second. Default 60 (one per frame). */
+    sampleRate?: number;
+    /** Hard cap on samples per iteration (memory guard). Default 600. */
+    maxSamples?: number;
+}
+/**
+ * Compiles a MATERIALISED document (run `materialiseAllInTree(doc, 'frames')`
+ * + `generateNewIds` first) into densely sampled per-element tracks.
+ */
+declare function compileTracks(doc: PxAnimatedSvgDocument, opts?: CompileTracksOptions): PxCompiledTracks;
+/**
+ * Worklet-safe sample lookup: returns the per-prop values at time `tMs`
+ * (already mapped into a single iteration by the caller). Kept deliberately
+ * trivial — runs on the UI thread every frame.
+ */
+declare function sampleProps(tracks: PxElementTracks, tMs: number, stepMs: number, sampleCount: number): Record<string, string | number | Array<number>>;
+
+/**
+ * Converts one normalised wire attribute name (camelCase after core's
+ * `getNormalizedProps`, or kebab-case raw) to a react-native-svg prop name.
+ * Returns undefined for props that must be dropped.
+ *
+ * Pure (no react-native-svg import) so the track compiler and its tests
+ * don't need a React Native environment.
+ */
+declare function toRnPropName(attrName: string): string | undefined;
+
+/**
+ * SVG tag → react-native-svg component. Tags not in this map are skipped at
+ * render time (with a warning collected by the renderer) — they go on the
+ * feature-gap list rather than crashing the tree.
+ */
+declare const RN_SVG_COMPONENTS: Record<string, ComponentType<any>>;
+
+export { type CompileTracksOptions, PixodeskSvgAnimator, type PixodeskSvgAnimatorProps, type PxCompiledTracks, type PxElementTracks, RN_SVG_COMPONENTS, type RenderRnNodeOptions, type RnAnimatorApi, compileTracks, PixodeskSvgAnimator as default, renderRnNode, sampleProps, toRnPropName, toRnProps };

package/dist/index.d.ts

@@ -0,0 +1,158 @@
+import { PxAnimatedSvgDocument, FillMode, PlaybackDirection, PxNode } from '@pixodesk/svg-animator-core';
+import React, { ReactElement, ComponentType, ReactNode } from 'react';
+
+/** Imperative playback API — mirrors ReactAnimatorApi from svg-animator-react. */
+interface RnAnimatorApi {
+    /** 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;
+    /** 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. */
+    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;
+}
+interface PixodeskSvgAnimatorProps {
+    /** The animation document to render. */
+    doc: PxAnimatedSvgDocument;
+    /** Duration of a single iteration in milliseconds. */
+    duration?: number;
+    /** Delay before the animation starts, in milliseconds. */
+    delay?: number;
+    /** Number of iterations, or 'infinite' for endless looping. */
+    iterations?: number | 'infinite';
+    /** Defines the element's state when the animation is not active. */
+    fill?: FillMode;
+    /** Playback direction. */
+    direction?: PlaybackDirection;
+    /** When true, honours the document trigger (`startOn: 'load'` plays on mount). */
+    autoplay?: boolean;
+    /** Starts playback unconditionally. */
+    play?: boolean;
+    /** Pauses current playback. */
+    pause?: boolean;
+    /** Ref populated with the imperative playback API. */
+    apiRef?: React.RefObject<RnAnimatorApi | null>;
+    /** Seek to a fraction (0–1) of the whole timeline (duration × iterations). */
+    time?: number;
+    /** Seek to a specific time in milliseconds. */
+    timeMs?: number;
+    onPlay?: () => void;
+    onStop?: () => void;
+    onPause?: () => void;
+    onCancel?: () => void;
+    onFinish?: () => void;
+}
+/**
+ * React Native component for rendering and controlling Pixodesk SVG animations.
+ *
+ * The document is materialised once through the shared core pipeline (effects,
+ * loops, motion-path sampling, animated-`<use>` inlining — identical to the
+ * web frames engine), compiled into densely sampled per-element tracks, and
+ * played back natively: a single reanimated progress value driven by
+ * `withTiming`/`withRepeat` on the UI thread, with per-element worklets
+ * indexing the precompiled tracks. No JS-thread frame loop.
+ */
+declare function PixodeskSvgAnimator({ doc, duration, delay, iterations, fill, direction, autoplay, play, pause, apiRef, time, timeMs, onPlay, onStop, onPause, onCancel, onFinish, }: PixodeskSvgAnimatorProps): ReactElement | null;
+
+interface RenderRnNodeOptions {
+    /** Collects non-fatal issues (unsupported tags, dropped attrs). */
+    warnings?: Array<string>;
+    /**
+     * Wraps the created element for animated nodes: receives the resolved
+     * component + static props and returns the element to mount (the animator
+     * substitutes an Animated component wired to its tracks). Return undefined
+     * to keep the plain static element.
+     */
+    decorate?: (node: PxNode, Component: ComponentType<any>, props: Record<string, any>, children: ReactNode) => ReactElement | undefined;
+}
+/**
+ * Converts core-normalised wire props into react-native-svg props: RN prop
+ * naming, sanitisation (same security rules as the web renderer), numeric
+ * coercion where possible.
+ */
+declare function toRnProps(props: Record<string, any>, warnings?: Array<string>): Record<string, any>;
+/**
+ * Renders a (materialised) PxNode tree to react-native-svg elements.
+ * Mirrors the web `renderNode` contract: unsupported/dangerous tags are
+ * skipped with a warning, never a crash.
+ */
+declare function renderRnNode(node: PxNode, opts?: RenderRnNodeOptions, key?: string | number): ReactElement | null;
+
+/**
+ * Sampled animation tracks for ONE element: prop name → per-sample values.
+ *
+ * The compiler densely samples every animated property through core's
+ * `calcAnimationValues` — the exact function the web frames engine renders
+ * with — so RN playback is value-identical to the web player. Easing, loops,
+ * transform composition, colour interpolation and path morphing are all baked
+ * into the samples at compile time; the UI-thread worklet only indexes arrays.
+ */
+interface PxElementTracks {
+    /** Element id (after id regeneration). */
+    id: string;
+    /** react-native-svg prop name → one value per sample. */
+    props: Record<string, Array<string | number | Array<number>>>;
+}
+interface PxCompiledTracks {
+    /** Per-iteration duration, ms. */
+    duration: number;
+    /** Iteration count (Infinity for 'infinite'). */
+    iterations: number;
+    /** 'normal' | 'reverse' | 'alternate' | 'alternate-reverse' */
+    direction: string;
+    /** Delay before start, ms (positive = wait). */
+    delay: number;
+    /** WAAPI-style fill mode (default 'forwards'). */
+    fill: string;
+    /** Sample step, ms. */
+    stepMs: number;
+    /** Number of samples per iteration (>= 2; sample i is at time i*stepMs). */
+    sampleCount: number;
+    /** Tracks for every animated element. */
+    elements: Array<PxElementTracks>;
+}
+interface CompileTracksOptions {
+    /** Target sample rate, samples/second. Default 60 (one per frame). */
+    sampleRate?: number;
+    /** Hard cap on samples per iteration (memory guard). Default 600. */
+    maxSamples?: number;
+}
+/**
+ * Compiles a MATERIALISED document (run `materialiseAllInTree(doc, 'frames')`
+ * + `generateNewIds` first) into densely sampled per-element tracks.
+ */
+declare function compileTracks(doc: PxAnimatedSvgDocument, opts?: CompileTracksOptions): PxCompiledTracks;
+/**
+ * Worklet-safe sample lookup: returns the per-prop values at time `tMs`
+ * (already mapped into a single iteration by the caller). Kept deliberately
+ * trivial — runs on the UI thread every frame.
+ */
+declare function sampleProps(tracks: PxElementTracks, tMs: number, stepMs: number, sampleCount: number): Record<string, string | number | Array<number>>;
+
+/**
+ * Converts one normalised wire attribute name (camelCase after core's
+ * `getNormalizedProps`, or kebab-case raw) to a react-native-svg prop name.
+ * Returns undefined for props that must be dropped.
+ *
+ * Pure (no react-native-svg import) so the track compiler and its tests
+ * don't need a React Native environment.
+ */
+declare function toRnPropName(attrName: string): string | undefined;
+
+/**
+ * SVG tag → react-native-svg component. Tags not in this map are skipped at
+ * render time (with a warning collected by the renderer) — they go on the
+ * feature-gap list rather than crashing the tree.
+ */
+declare const RN_SVG_COMPONENTS: Record<string, ComponentType<any>>;
+
+export { type CompileTracksOptions, PixodeskSvgAnimator, type PixodeskSvgAnimatorProps, type PxCompiledTracks, type PxElementTracks, RN_SVG_COMPONENTS, type RenderRnNodeOptions, type RnAnimatorApi, compileTracks, PixodeskSvgAnimator as default, renderRnNode, sampleProps, toRnPropName, toRnProps };