@pixodesk/svg-animator-rn 1.0.30 → 1.0.35

package/src/PixodeskSvgAnimator.tsx

@@ -3,19 +3,7 @@
  * Licensed under the MIT License. See the LICENSE file in the project root for details.
  *---------------------------------------------------------------------------------------*/
 
-import {
-    generateNewIds,
-    getAnimatorConfig,
-    getDefs,
-    materialiseAllInTree,
-    validateNodeEffects,
-    PxAnimatorEngine,
-    type FillMode,
-    type OutAction,
-    type PlaybackDirection,
-    type PxAnimatedSvgDocument,
-    type PxNode,
-} from '@pixodesk/svg-animator-core';
+import { reportDocumentDiagnostics, generateNewIds, getAnimatorConfig, getDefs, materialiseAllInTree, validateNodeEffects, PxTimelineEngine, type FillMode, type OutAction, type PlaybackDirection, type PxAnimatedSvgDocument, type PxAnimatorConfigPatch, type PxNode, type StartOn, applyAnimatorConfig, foldAnimatorConfigShortcuts } from '@pixodesk/svg-animator-core';
 import React, { createElement, useEffect, useImperativeHandle, useMemo, useRef, useState, type ComponentType, type ReactElement, type ReactNode } from 'react';
 import { Dimensions, Platform, Pressable, View } from 'react-native';
 import Animated, {
@@ -83,20 +71,22 @@ export interface PixodeskSvgAnimatorProps {
     /** 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;
-
-    /** Snap back to the start state after a natural finish. */
-    resetOnFinish?: boolean;
+    /** Shortcut for `config.timeline.trigger.startOn`. */
+    startOn?: StartOn;
 
     /**
-     * What a second tap does when `startOn: 'click'` is active.
-     * Defaults to the document's `trigger.outAction`, else `'pause'`.
+     * Per-instance override of the document's `animator` config — the same shape as `animator`
+     * in SCHEMA.md, deep-merged over what the document says; `null` at a slot deletes it.
+     * Replaces the former flat `fill` / `direction` / `resetOnFinish` / `outAction` props, so
+     * every surface takes one vocabulary. Also accepts a JSON string.
+     *
+     * `timeline.engine` is accepted but ignored here: React Native always materialises the
+     * WAAPI-style flattening, because react-native-svg has no `<use>` shadow-tree propagation.
      */
-    outAction?: OutAction;
+    config?: PxAnimatorConfigPatch | string;
+
+    /** Start from the player's defaults instead of the document's playback settings. */
+    resetDocDefaults?: boolean;
 
     // -- Declarative control --------------------------------------------------
 
@@ -117,10 +107,10 @@ export interface PixodeskSvgAnimatorProps {
     // -- Controlled (external) time -------------------------------------------
 
     /** Seek to a fraction (0–1) of the whole timeline (duration × iterations). */
-    time?: number;
+    progress?: number;
 
     /** Seek to a specific time in milliseconds. */
-    timeMs?: number;
+    time?: number;
 
     // -- Callbacks ------------------------------------------------------------
 
@@ -285,12 +275,12 @@ function SampledSubtree({
 
 /** Overrides that shadow the document's own `animator` config. */
 interface ConfigOverrides {
+    config?: PxAnimatorConfigPatch | string;
+    resetDocDefaults?: boolean;
     duration?: number;
     delay?: number;
     iterations?: number | 'infinite';
-    fill?: FillMode;
-    direction?: PlaybackDirection;
-    resetOnFinish?: boolean;
+    startOn?: StartOn;
 }
 
 interface Compiled {
@@ -312,9 +302,21 @@ const EMPTY_TRACKS: PxCompiledTracks = {
  * whole thing sits behind one try/catch, and so it can be tested directly.
  */
 function compileDocument(doc: PxAnimatedSvgDocument, overrides: ConfigOverrides): Compiled {
-    const { duration, delay, iterations, fill, direction, resetOnFinish } = overrides;
+    const { config, resetDocDefaults, duration, delay, iterations, startOn } = overrides;
     const warnings = validateNodeEffects(doc as PxNode);
     for (const w of warnings) console.warn('[PixodeskSvgAnimator] effects shape warning:', w);
+    // The whole-document boundary diagnostic — see the note in the web player's entry.
+    reportDocumentDiagnostics(doc, '[PixodeskSvgAnimator]');
+
+    // The per-instance override, applied to the WIRE document BEFORE anything reads the
+    // config — `materialiseAllInTree` samples motion paths against `duration`, so a later
+    // patch would be read by none of the pipeline. Same call, same rules, on every surface.
+    const patch = foldAnimatorConfigShortcuts(config, { duration, delay, iterations, startOn });
+    if (patch !== undefined || resetDocDefaults) {
+        const applied = applyAnimatorConfig(doc, patch ?? {}, { resetDefaults: !!resetDocDefaults });
+        for (const w of applied.warnings) console.warn('[PixodeskSvgAnimator] config override:', w);
+        doc = applied.doc;
+    }
 
     // `waapi` = the FULLY-FLATTENED materialisation: effects + loops +
     // sampled motion paths + animated `<use>` inlined into real `<g>`
@@ -323,7 +325,7 @@ function compileDocument(doc: PxAnimatedSvgDocument, overrides: ConfigOverrides)
     // live references, which only work because the DOM propagates
     // attribute writes through `<use>` shadow trees. react-native-svg has
     // no such live propagation, so an animated `<use>` would render frozen.
-    let prepared = materialiseAllInTree(doc, PxAnimatorEngine.waapi);
+    let prepared = materialiseAllInTree(doc, PxTimelineEngine.native);
 
     // Sidestep a react-native-svg NATIVE crash (see PxRnSafety). Guarded on
     // the platform because the DOM renders this case correctly and the web
@@ -332,21 +334,6 @@ function compileDocument(doc: PxAnimatedSvgDocument, overrides: ConfigOverrides)
         prepared = openClosedTextPathTargets(prepared as PxNode) as PxAnimatedSvgDocument;
     }
 
-    // Apply prop overrides onto the animator config (mirrors the react wrapper).
-    const animator = getAnimatorConfig(prepared) || {};
-    prepared = {
-        ...prepared,
-        animator: {
-            ...animator,
-            duration: duration !== undefined ? duration : animator.duration,
-            delay: delay !== undefined ? delay : animator.delay,
-            iterations: iterations !== undefined ? iterations : animator.iterations,
-            fill: fill !== undefined ? fill : animator.fill,
-            direction: direction !== undefined ? direction : animator.direction,
-            resetOnFinish: resetOnFinish !== undefined ? resetOnFinish : animator.resetOnFinish,
-        },
-    };
-
     prepared = generateNewIds(prepared);
     const tracks = compileTracks(prepared, { native: NATIVE_SVG_VIEWS });
     return { doc: prepared, tracks, error: null };
@@ -366,18 +353,25 @@ function compileDocument(doc: PxAnimatedSvgDocument, overrides: ConfigOverrides)
  * indexing the precompiled tracks. No JS-thread frame loop.
  */
 export function PixodeskSvgAnimator({
-    doc, duration, delay, iterations, fill, direction, resetOnFinish, outAction: outActionProp,
-    autoplay, play, pause, apiRef, time, timeMs,
+    doc, config, resetDocDefaults, duration, delay, iterations, startOn,
+    // (`progress` prop aliased — the name is taken by the internal reanimated SharedValue)
+    autoplay, play, pause, apiRef, progress: progressProp, time,
     onPlay, onStop, onPause, onCancel, onFinish, onError, fallback,
 }: PixodeskSvgAnimatorProps): ReactElement | null {
 
     // -- Compile the document (once per doc/override change) ------------------
 
+    // `config` is an object prop: a fresh literal every render would otherwise recompile the
+    // whole document (materialise + compile tracks), which is the expensive path. Key on its
+    // CONTENT instead — the override is small, the document is not.
+    const configKey = typeof config === 'string' ? config : JSON.stringify(config ?? null);
+
+
     const compiled = useMemo((): Compiled => {
         try {
             return compileDocument(
                 doc,
-                { duration, delay, iterations, fill, direction, resetOnFinish }
+                { config, resetDocDefaults, duration, delay, iterations, startOn }
             );
         } catch (e) {
             // A malformed document must not take the host screen down with it.
@@ -385,7 +379,9 @@ export function PixodeskSvgAnimator({
             console.warn('[PixodeskSvgAnimator] could not compile the document:', error.message);
             return { doc: null, tracks: EMPTY_TRACKS, error };
         }
-    }, [doc, duration, delay, iterations, fill, direction, resetOnFinish]);
+        // `config` is an object prop, so a fresh literal each render would recompile the whole
+        // document. Key on its CONTENT — the override is small, unlike the document.
+    }, [doc, configKey, resetDocDefaults, duration, delay, iterations, startOn]);
 
     const tracks: PxCompiledTracks = compiled.tracks;
     const totalDuration = tracks.duration * (tracks.iterations === Infinity ? 1 : tracks.iterations);
@@ -513,13 +509,15 @@ export function PixodeskSvgAnimator({
 
     // -- Declarative control --------------------------------------------------
 
+    // The EFFECTIVE trigger, read back off the COMPILED document — so it already reflects the
+    // `config` override and the `startOn` shortcut, both merged in before compilation.
     const trigger = compiled.doc ? getAnimatorConfig(compiled.doc)?.trigger : undefined;
-    const startOn = trigger?.startOn ?? 'load';
-    const outAction = outActionProp ?? trigger?.outAction ?? 'pause';
+    const effectiveStartOn = trigger?.startOn ?? 'load';
+    const effectiveOutAction = trigger?.outAction ?? 'pause';
 
     useEffect(() => {
-        if (time !== undefined || timeMs !== undefined) {
-            const seekMs = timeMs !== undefined ? timeMs : (time ?? 0) * totalDuration;
+        if (progressProp !== undefined || time !== undefined) {
+            const seekMs = time !== undefined ? time : (progressProp ?? 0) * totalDuration;
             api.setCurrentTime(seekMs);
             return;
         }
@@ -531,11 +529,11 @@ export function PixodeskSvgAnimator({
             return;
         }
         // 'click' and 'scrollIntoView' start from their own handlers below.
-        if (autoplay && startOn === 'load') {
+        if (autoplay && effectiveStartOn === 'load') {
             api.play();
         }
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [compiled, autoplay, play, pause, time, timeMs]);
+    }, [compiled, autoplay, play, pause, progressProp, time]);
 
     // `startOn: 'scrollIntoView'` — react-native has no IntersectionObserver, so
     // visibility is sampled by measuring the view against the window box. The
@@ -544,7 +542,7 @@ export function PixodeskSvgAnimator({
     const scrollRef = useRef<View | null>(null);
     const inViewRef = useRef(false);
     useEffect(() => {
-        if (!autoplay || startOn !== 'scrollIntoView') return;
+        if (!autoplay || effectiveStartOn !== 'scrollIntoView') return;
         const threshold = trigger?.scrollIntoViewThreshold ?? 0;
         inViewRef.current = false;
 
@@ -562,9 +560,9 @@ export function PixodeskSvgAnimator({
                 if (isIn) {
                     if (rateRef.current < 0) api.setPlaybackRate(Math.abs(rateRef.current));
                     api.play();
-                } else if (outAction === 'reset') api.cancel();
-                else if (outAction === 'reverse') { api.setPlaybackRate(-Math.abs(rateRef.current || 1)); api.play(); }
-                else if (outAction !== 'continue') api.pause();
+                } else if (effectiveOutAction === 'reset') api.cancel();
+                else if (effectiveOutAction === 'reverse') { api.setPlaybackRate(-Math.abs(rateRef.current || 1)); api.play(); }
+                else if (effectiveOutAction !== 'continue') api.pause();
             });
         };
 
@@ -572,7 +570,7 @@ export function PixodeskSvgAnimator({
         const id = setInterval(check, 200);
         return () => clearInterval(id);
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [compiled, autoplay, startOn, outAction]);
+    }, [compiled, autoplay, effectiveStartOn, effectiveOutAction]);
 
     // Stop cleanly on unmount / doc swap.
     useEffect(() => {
@@ -671,17 +669,17 @@ export function PixodeskSvgAnimator({
     // so both are left to the host app.
     let content: ReactElement | null = root;
 
-    if (autoplay && startOn === 'scrollIntoView' && root) {
+    if (autoplay && effectiveStartOn === 'scrollIntoView' && root) {
         // `collapsable={false}` keeps the view in the native tree so it can be measured.
         content = <View ref={scrollRef} collapsable={false}>{root}</View>;
-    } else if (autoplay && startOn === 'click' && root) {
+    } else if (autoplay && effectiveStartOn === 'click' && root) {
         content = (
             <Pressable
                 onPress={() => {
                     if (playingRef.current) {
-                        if (outAction === 'reset') api.cancel();
-                        else if (outAction === 'reverse') { api.setPlaybackRate(-Math.abs(rateRef.current || 1)); api.play(); }
-                        else if (outAction !== 'continue') api.pause();
+                        if (effectiveOutAction === 'reset') api.cancel();
+                        else if (effectiveOutAction === 'reverse') { api.setPlaybackRate(-Math.abs(rateRef.current || 1)); api.play(); }
+                        else if (effectiveOutAction !== 'continue') api.pause();
                     } else {
                         if (rateRef.current < 0) api.setPlaybackRate(Math.abs(rateRef.current));
                         api.play();

package/src/PxRnTracks.test.ts

@@ -4,7 +4,7 @@
  *---------------------------------------------------------------------------------------*/
 
 import { describe, expect, it } from 'vitest';
-import { generateNewIds, materialiseAllInTree, PxAnimatorEngine, type PxAnimatedSvgDocument } from '@pixodesk/svg-animator-core';
+import { generateNewIds, materialiseAllInTree, PxTimelineEngine, type PxAnimatedSvgDocument } from '@pixodesk/svg-animator-core';
 import { compileTracks, sampleProps } from './PxRnTracks';
 import { toRnPropName } from './PxRnPropNames';
 
@@ -12,7 +12,7 @@ function makeDoc(): PxAnimatedSvgDocument {
     return {
         type: 'svg',
         viewBox: '0 0 200 200',
-        animator: { mode: 'frames', duration: 1000, iterations: 2, direction: 'alternate' },
+        animator: { timeline: { engine: 'js', duration: 1000, iterations: 2, direction: 'alternate' } },
         children: [
             {
                 type: 'rect',
@@ -37,7 +37,7 @@ function makeDoc(): PxAnimatedSvgDocument {
 }
 
 function compile(doc = makeDoc(), opts?: Parameters<typeof compileTracks>[1]) {
-    const materialised = generateNewIds(materialiseAllInTree(doc, PxAnimatorEngine.frames));
+    const materialised = generateNewIds(materialiseAllInTree(doc, PxTimelineEngine.js));
     return compileTracks(materialised, opts);
 }
 
@@ -150,13 +150,13 @@ describe('length-list props (stroke-dasharray)', () => {
     it('compiles stroke-dasharray into number arrays (rn-svg native shape)', () => {
         const doc: PxAnimatedSvgDocument = {
             type: 'svg', viewBox: '0 0 100 100',
-            animator: { mode: 'frames', duration: 1000 },
+            animator: { timeline: { engine: 'js', duration: 1000 } },
             children: [{
                 type: 'path', id: 'p', d: 'M 0 50 L 100 50', stroke: '#000', fill: 'none',
                 effects: { strokeTrim: { range: { keyframes: [{ time: 0, value: [0, 0.1] }, { time: 1000, value: [0, 1] }] } } },
             }],
         };
-        const materialised = generateNewIds(materialiseAllInTree(doc, PxAnimatorEngine.waapi));
+        const materialised = generateNewIds(materialiseAllInTree(doc, PxTimelineEngine.native));
         const tracks = compileTracks(materialised);
         const el = tracks.elements.find(e => 'strokeDasharray' in e.props)!;
         expect(el).toBeDefined();
@@ -171,17 +171,17 @@ describe('animated <use> flattening (waapi materialisation)', () => {
     it('inlines animated <use> clones so no live references remain', () => {
         const doc: PxAnimatedSvgDocument = {
             type: 'svg', viewBox: '0 0 300 200',
-            animator: { mode: 'frames', duration: 2000 },
+            animator: { timeline: { engine: 'js', duration: 2000 } },
             children: [
                 { type: 'defs', children: [{ type: 'g', id: 'sym', children: [{
                     type: 'circle', id: 'c', cx: 30, cy: 40, r: 16, fill: '#f59e0b',
                     animate: { cy: { keyframes: [{ time: 0, value: 40 }, { time: 2000, value: 160 }] } },
                 }] }] },
                 { type: 'use', id: 'u1', href: '#sym' },
-                { type: 'use', id: 'u2', href: '#sym', x: 80, effects: { clone: { sourceId: '#sym', retime: { start: -600 } } } },
+                { type: 'use', id: 'u2', href: '#sym', x: 80, effects: { clone: { source: '#sym', retime: { start: -600 } } } },
             ],
         };
-        const materialised = generateNewIds(materialiseAllInTree(doc, PxAnimatorEngine.waapi));
+        const materialised = generateNewIds(materialiseAllInTree(doc, PxTimelineEngine.native));
         const countUse = (n: any): number =>
             (n.type === 'use' ? 1 : 0) + (n.children || []).reduce((s: number, c: any) => s + countUse(c), 0);
         expect(countUse(materialised)).toBe(0);

package/src/PxRnTracks.ts

@@ -8,7 +8,7 @@ import {
     getAnimatorConfig,
     getNormalisedBindings,
     DEFAULT_DURATION_MS,
-    PxAnimatorEngine,
+    PxTimelineEngine,
     type PxAnimatedSvgDocument,
     type PxAnimationDefinition,
 } from '@pixodesk/svg-animator-core';
@@ -99,7 +99,7 @@ export function compileTracks(doc: PxAnimatedSvgDocument, opts?: CompileTracksOp
     };
     indexTags(doc);
 
-    const bindings = getNormalisedBindings(doc, PxAnimatorEngine.frames) || [];
+    const bindings = getNormalisedBindings(doc, PxTimelineEngine.js) || [];
 
     const elements: Array<PxElementTracks> = [];
     for (const binding of bindings) {