@pixodesk/svg-animator-rn 1.0.34 → 1.0.35

package/README.md

@@ -51,7 +51,7 @@ document says so.
 
 ```tsx
 // Play once when a screen opens, then hold the last frame
-<PixodeskSvgAnimator doc={doc} autoplay iterations={1} fill="forwards" />
+<PixodeskSvgAnimator doc={doc} autoplay iterations={1} config={{ timeline: { fillMode: 'forwards' } }} />
 
 // Loop forever regardless of what the document says
 <PixodeskSvgAnimator doc={doc} autoplay iterations="infinite" />
@@ -175,13 +175,12 @@ const [time, setTime] = useState(0);
 | `apiRef` | `RefObject<RnAnimatorApi>` | Ref for imperative control |
 | `progress` | `number` | show the frame at this position in the whole timeline (duration × iterations): `0` is the first frame, `0.5` the middle, `1` the last |
 | `time` | `number` | show the frame at that time, in milliseconds from the start |
-| `duration` | `number` | Duration override (ms) |
-| `delay` | `number` | Delay before start (ms) |
-| `iterations` | `number \| 'infinite'` | Loop count |
-| `fill` | `FillMode` | Fill behaviour |
-| `direction` | `PlaybackDirection` | Playback direction |
-| `resetOnFinish` | `boolean` | Snap back to the start after a natural finish |
-| `outAction` | `OutAction` | What a second tap does with the `click` trigger (default: the document's, else `pause`) |
+| `config` | `object \| string` | Per-instance override of the document's `animator` block, deep-merged over it — same shape as the file (`{ timeline: { fillMode, direction, trigger: { outAction, finishAction, … } } }`); `null` at a slot deletes that key. A JSON string is accepted too. `timeline.engine` is accepted but ignored here |
+| `resetDocDefaults` | `boolean` | Ignore the document's playback settings and start from the player's defaults, with `config` on top |
+| `duration` | `number` | Shortcut for `config.timeline.duration` (ms) |
+| `delay` | `number` | Shortcut for `config.timeline.delay` (ms) |
+| `iterations` | `number \| 'infinite'` | Shortcut for `config.timeline.iterations` |
+| `startOn` | `StartOn` | Shortcut for `config.timeline.trigger.startOn`. `mouseOver` has no touch equivalent and is ignored |
 | `onPlay` | `() => void` | Called on play/resume |
 | `onPause` | `() => void` | Called on pause |
 | `onFinish` | `() => void` | Called on natural finish |
@@ -217,9 +216,9 @@ renderer never reaches JavaScript and cannot be caught — see
 
 | Prop | Why it differs |
 |---|---|
-| `mode` | Not accepted. There is no Web Animations API on React Native; playback is always native-driven. |
-| `frameRate` | Not accepted. The screen's own refresh rate is used. The player does not compute values frame by frame: when the document loads it works out the animated values in advance, as a list of snapshots (60 per second of animation), and each screen refresh shows the nearest one. The closest thing to a frame rate is how many snapshots per second are prepared — `compileTracks({ sampleRate })`, only available when you use the lower-level API instead of the component. |
-| `startOn` | Not accepted as a prop — the document's trigger is honoured via `autoplay` (`load`, `click`, `scrollIntoView`, `programmatic`). `mouseOver` has no touch equivalent. |
+| `timeline.engine` | Accepted inside `config` but ignored. There is no Web Animations API on React Native; playback is always native-driven. |
+| `timeline.frameRate` | Ignored. The screen's own refresh rate is used. The player does not compute values frame by frame: when the document loads it works out the animated values in advance, as a list of snapshots (60 per second of animation), and each screen refresh shows the nearest one. The closest thing to a frame rate is how many snapshots per second are prepared — `compileTracks({ sampleRate })`, only available when you use the lower-level API instead of the component. |
+| `startOn: 'mouseOver'` | Has no touch equivalent, so it is not honoured. The other four values (`load`, `click`, `scrollIntoView`, `programmatic`) work as they do on the web, from the file or from the `startOn` prop. |
 | `className` / `style` | Not accepted — you cannot style the component itself. It fills whatever `View` you put it in, so to set its size, give that `View` a `width` and `height`. Styling *inside* the document (`style` on an element in the JSON) is supported. |
 | `onRemove` | Never called. On the web it tells you the animator was thrown away; here there is nothing to tell — when the component leaves the screen, React removes it and everything it created. To run code at that moment, use a `useEffect` cleanup function in your own component. |
 
@@ -296,8 +295,7 @@ player sees plain nodes. **All are supported:**
 | `clone` + `retime` | ✅ | each clone keeps its own time shift, incl. `retime.timeCrop` (a visibility window on the document timeline) |
 | `fillGradient` / `strokeGradient` | ✅ | animated stops **and animated geometry** (`animate.gradientX1`/`Cx`/`R`, …); `gradientTransform` is static (core-wide) |
 | `textPath` | ✅ | incl. animated `startOffset` |
-| `text.useGlyphs` | ✅ | text becomes `<path>` outlines from `definitions.glyphs` — no font needed |
-| `isCombinedShape` | ✅ | |
+| `text.useGlyphs` | ✅ | text becomes `<path>` outlines from `definitions.fonts` — no font needed |
 
 ### Motion, timing and references
 
@@ -307,7 +305,7 @@ player sees plain nodes. **All are supported:**
 | **Text along a path** | ✅ two ways | native `textPath` (incl. animated `startOffset`), or **per-letter motion paths** for smooth results — the example app uses the latter, since animating native `startOffset` is janky in `react-native-svg` |
 | Per-property `loop` (incl. `alternate` pingpong) | ✅ | expanded before playback |
 | Easing (cubic-bezier and named refs) | ✅ | baked into the sampled tracks |
-| `definitions.animations` / `easings` / `styles` / `glyphs` | ✅ | named refs resolved; `style` presets applied as props |
+| `definitions.animations` / `easings` / `styles` / `fonts` | ✅ | named refs resolved; `style` presets applied as props |
 | `node.style` (inline or named) | ✅ | resolved to props — React Native has no CSS, so explicit attributes win |
 
 ### Playback and triggers
@@ -316,8 +314,8 @@ player sees plain nodes. **All are supported:**
 |---|---|---|
 | `duration`, `delay`, `iterations` (incl. `'infinite'`) | ✅ | |
 | `direction` — all four values | ✅ | |
-| `fill` — `forwards` / `backwards` / `both` / `none` | ✅ | |
-| `resetOnFinish` | ✅ | |
+| `fillMode` — `forwards` / `backwards` / `both` / `none` | ✅ | |
+| `trigger.finishAction: 'reset'` | ✅ | |
 | `play` / `pause` / `cancel` / `finish` | ✅ | |
 | `setCurrentTime` — jump to a time, including **while playing** | ✅ | playback continues from the new point |
 | `setPlaybackRate` — faster, slower and **reverse** (negative) | ✅ | composes with `direction` |
@@ -325,8 +323,8 @@ player sees plain nodes. **All are supported:**
 | Trigger `click` | ✅ | wrapped in a `Pressable`; a second tap applies `outAction` |
 | Trigger `scrollIntoView` | ✅ | visibility sampled by measuring against the window (React Native has no `IntersectionObserver`); honours `scrollIntoViewThreshold` and `outAction` |
 | Trigger `mouseOver` | ❌ | no touch equivalent — use `click`, or drive `play` yourself |
-| `frameRate` | n/a | reanimated runs at the display refresh rate; use `compileTracks({sampleRate})` to trade memory for temporal precision |
-| `mode` (`waapi` / `frames`) | n/a | there is no Web Animations API on React Native — playback is always native-driven |
+| `timeline.frameRate` | n/a | reanimated runs at the display refresh rate; use `compileTracks({sampleRate})` to trade memory for temporal precision |
+| `timeline.engine` (`auto` / `native` / `js`) | n/a | there is no Web Animations API on React Native — playback is always native-driven |
 
 ### Known limitations
 

package/dist/index.cjs

@@ -199,7 +199,7 @@ function compileTracks(doc, opts) {
     ((_a2 = n == null ? void 0 : n.children) != null ? _a2 : []).forEach(indexTags);
   };
   indexTags(doc);
-  const bindings = (0, import_svg_animator_core2.getNormalisedBindings)(doc, import_svg_animator_core2.PxAnimatorEngine.frames) || [];
+  const bindings = (0, import_svg_animator_core2.getNormalisedBindings)(doc, import_svg_animator_core2.PxTimelineEngine.js) || [];
   const elements = [];
   for (const binding of bindings) {
     const animDef = binding.animate;
@@ -562,37 +562,32 @@ var EMPTY_TRACKS = {
   elements: []
 };
 function compileDocument(doc, overrides) {
-  const { duration, delay, iterations, fill, direction, resetOnFinish } = overrides;
+  const { config, resetDocDefaults, duration, delay, iterations, startOn } = overrides;
   const warnings = (0, import_svg_animator_core5.validateNodeEffects)(doc);
   for (const w of warnings) console.warn("[PixodeskSvgAnimator] effects shape warning:", w);
-  let prepared = (0, import_svg_animator_core5.materialiseAllInTree)(doc, import_svg_animator_core5.PxAnimatorEngine.waapi);
+  (0, import_svg_animator_core5.reportDocumentDiagnostics)(doc, "[PixodeskSvgAnimator]");
+  const patch = (0, import_svg_animator_core5.foldAnimatorConfigShortcuts)(config, { duration, delay, iterations, startOn });
+  if (patch !== void 0 || resetDocDefaults) {
+    const applied = (0, import_svg_animator_core5.applyAnimatorConfig)(doc, patch != null ? patch : {}, { resetDefaults: !!resetDocDefaults });
+    for (const w of applied.warnings) console.warn("[PixodeskSvgAnimator] config override:", w);
+    doc = applied.doc;
+  }
+  let prepared = (0, import_svg_animator_core5.materialiseAllInTree)(doc, import_svg_animator_core5.PxTimelineEngine.native);
   if (NATIVE_SVG_VIEWS) {
     prepared = openClosedTextPathTargets(prepared);
   }
-  const animator = (0, import_svg_animator_core5.getAnimatorConfig)(prepared) || {};
-  prepared = __spreadProps(__spreadValues({}, prepared), {
-    animator: __spreadProps(__spreadValues({}, animator), {
-      duration: duration !== void 0 ? duration : animator.duration,
-      delay: delay !== void 0 ? delay : animator.delay,
-      iterations: iterations !== void 0 ? iterations : animator.iterations,
-      fill: fill !== void 0 ? fill : animator.fill,
-      direction: direction !== void 0 ? direction : animator.direction,
-      resetOnFinish: resetOnFinish !== void 0 ? resetOnFinish : animator.resetOnFinish
-    })
-  });
   prepared = (0, import_svg_animator_core5.generateNewIds)(prepared);
   const tracks = compileTracks(prepared, { native: NATIVE_SVG_VIEWS });
   return { doc: prepared, tracks, error: null };
 }
 function PixodeskSvgAnimator({
   doc,
+  config,
+  resetDocDefaults,
   duration,
   delay,
   iterations,
-  fill,
-  direction,
-  resetOnFinish,
-  outAction: outActionProp,
+  startOn,
   // (`progress` prop aliased — the name is taken by the internal reanimated SharedValue)
   autoplay,
   play,
@@ -609,18 +604,19 @@ function PixodeskSvgAnimator({
   fallback
 }) {
   var _a, _b, _c, _d;
+  const configKey = typeof config === "string" ? config : JSON.stringify(config != null ? config : null);
   const compiled = (0, import_react3.useMemo)(() => {
     try {
       return compileDocument(
         doc,
-        { duration, delay, iterations, fill, direction, resetOnFinish }
+        { config, resetDocDefaults, duration, delay, iterations, startOn }
       );
     } catch (e) {
       const error = e instanceof Error ? e : new Error(String(e));
       console.warn("[PixodeskSvgAnimator] could not compile the document:", error.message);
       return { doc: null, tracks: EMPTY_TRACKS, error };
     }
-  }, [doc, duration, delay, iterations, fill, direction, resetOnFinish]);
+  }, [doc, configKey, resetDocDefaults, duration, delay, iterations, startOn]);
   const tracks = compiled.tracks;
   const totalDuration = tracks.duration * (tracks.iterations === Infinity ? 1 : tracks.iterations);
   const progress = (0, import_react_native_reanimated.useSharedValue)(0);
@@ -714,8 +710,8 @@ function PixodeskSvgAnimator({
   };
   (0, import_react3.useImperativeHandle)(apiRef, () => api, [compiled]);
   const trigger = compiled.doc ? (_a = (0, import_svg_animator_core5.getAnimatorConfig)(compiled.doc)) == null ? void 0 : _a.trigger : void 0;
-  const startOn = (_b = trigger == null ? void 0 : trigger.startOn) != null ? _b : "load";
-  const outAction = (_c = outActionProp != null ? outActionProp : trigger == null ? void 0 : trigger.outAction) != null ? _c : "pause";
+  const effectiveStartOn = (_b = trigger == null ? void 0 : trigger.startOn) != null ? _b : "load";
+  const effectiveOutAction = (_c = trigger == null ? void 0 : trigger.outAction) != null ? _c : "pause";
   (0, import_react3.useEffect)(() => {
     if (progressProp !== void 0 || time !== void 0) {
       const seekMs = time !== void 0 ? time : (progressProp != null ? progressProp : 0) * totalDuration;
@@ -729,7 +725,7 @@ function PixodeskSvgAnimator({
       else api.play();
       return;
     }
-    if (autoplay && startOn === "load") {
+    if (autoplay && effectiveStartOn === "load") {
       api.play();
     }
   }, [compiled, autoplay, play, pause, progressProp, time]);
@@ -737,7 +733,7 @@ function PixodeskSvgAnimator({
   const inViewRef = (0, import_react3.useRef)(false);
   (0, import_react3.useEffect)(() => {
     var _a2;
-    if (!autoplay || startOn !== "scrollIntoView") return;
+    if (!autoplay || effectiveStartOn !== "scrollIntoView") return;
     const threshold = (_a2 = trigger == null ? void 0 : trigger.scrollIntoViewThreshold) != null ? _a2 : 0;
     inViewRef.current = false;
     const check = () => {
@@ -754,17 +750,17 @@ 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") {
+        } else if (effectiveOutAction === "reset") api.cancel();
+        else if (effectiveOutAction === "reverse") {
           api.setPlaybackRate(-Math.abs(rateRef.current || 1));
           api.play();
-        } else if (outAction !== "continue") api.pause();
+        } else if (effectiveOutAction !== "continue") api.pause();
       });
     };
     check();
     const id = setInterval(check, 200);
     return () => clearInterval(id);
-  }, [compiled, autoplay, startOn, outAction]);
+  }, [compiled, autoplay, effectiveStartOn, effectiveOutAction]);
   (0, import_react3.useEffect)(() => {
     return () => {
       (0, import_react_native_reanimated.cancelAnimation)(progress);
@@ -837,19 +833,19 @@ function PixodeskSvgAnimator({
   }, [failure]);
   if (failure) return fallback ? fallback(failure) : null;
   let content = root;
-  if (autoplay && startOn === "scrollIntoView" && root) {
+  if (autoplay && effectiveStartOn === "scrollIntoView" && root) {
     content = /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react_native.View, { ref: scrollRef, collapsable: false, children: root });
-  } else if (autoplay && startOn === "click" && root) {
+  } else if (autoplay && effectiveStartOn === "click" && root) {
     content = /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
       import_react_native.Pressable,
       {
         onPress: () => {
           if (playingRef.current) {
-            if (outAction === "reset") api.cancel();
-            else if (outAction === "reverse") {
+            if (effectiveOutAction === "reset") api.cancel();
+            else if (effectiveOutAction === "reverse") {
               api.setPlaybackRate(-Math.abs(rateRef.current || 1));
               api.play();
-            } else if (outAction !== "continue") api.pause();
+            } else if (effectiveOutAction !== "continue") api.pause();
           } else {
             if (rateRef.current < 0) api.setPlaybackRate(Math.abs(rateRef.current));
             api.play();