@pixodesk/svg-animator-rn 1.0.30 → 1.0.35

package/README.md

@@ -1,5 +1,7 @@
 # animator-rn
 
+> 📖 Full user guide: [docs/library/react-native.md](../../docs/library/react-native.md) · [all docs](../../README.md#documentation)
+
 [![CI](https://github.com/pixodesk/pixodesk-svg-animator/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/pixodesk/pixodesk-svg-animator/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
@@ -21,8 +23,8 @@ native SVG, driven on the UI thread.
 - **One prop to render:** put the `.json` next to your component, import it, pass
   it as `doc`.
 - **Playback control:** declarative props (`autoplay`, `play`, `pause`,
-  `timeMs`) or an imperative ref (`play()`, `pause()`, `setCurrentTime()`, …).
-- **Sized by its container:** wrap it in a `View` with the dimensions you want.
+  `time`) or an imperative ref (`play()`, `pause()`, `setCurrentTime()`, …).
+- **No size of its own:** it fills whatever `View` you put it in — give that `View` a `width` and `height`.
 
 ## Quick start
 
@@ -49,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" />
@@ -153,13 +155,13 @@ const api = useRef<RnAnimatorApi>(null);
 
 ### Controlled time
 
-Scrub through the animation or pin a fixed frame:
+Move through the animation with a slider, or show one fixed frame:
 
 ```tsx
-const [timeMs, setTimeMs] = useState(0);
+const [time, setTime] = useState(0);
 
-<PixodeskSvgAnimator doc={doc} timeMs={timeMs} />
-<Slider minimumValue={0} maximumValue={2000} value={timeMs} onValueChange={setTimeMs} />
+<PixodeskSvgAnimator doc={doc} time={time} />
+<Slider minimumValue={0} maximumValue={2000} value={time} onValueChange={setTime} />
 ```
 
 ## Props
@@ -171,15 +173,14 @@ const [timeMs, setTimeMs] = useState(0);
 | `play` | `boolean` | Start playback, ignoring document triggers |
 | `pause` | `boolean` | Pause current playback |
 | `apiRef` | `RefObject<RnAnimatorApi>` | Ref for imperative control |
-| `time` | `number` | Seek to a fraction (0–1) of the whole timeline (duration × iterations) |
-| `timeMs` | `number` | Seek to a time in milliseconds |
-| `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`) |
+| `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 |
+| `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 |
@@ -188,7 +189,7 @@ const [timeMs, setTimeMs] = useState(0);
 | `onError` | `(error, componentStack?) => void` | Called when a document cannot be compiled or rendered |
 | `fallback` | `(error) => ReactElement \| null` | Rendered in place of a failed animation (default: nothing) |
 
-With none of `autoplay` / `play` / `pause` / `time` / `timeMs` set, the component
+With none of `autoplay` / `play` / `pause` / `progress` / `time` set, the component
 renders the animation statically (initial state, no playback).
 
 ### Failure handling
@@ -215,11 +216,11 @@ renderer never reaches JavaScript and cannot be caught — see
 
 | Prop | Why it differs |
 |---|---|
-| `mode` | Not accepted. There is no Web Animations API on RN; playback is always native-driven. |
-| `frameRate` | Not accepted. Reanimated runs at the display refresh rate. The analogous knob is sampling density — see `compileTracks`. |
-| `startOn` | Not accepted as a prop — the document's trigger is honoured via `autoplay` (`load`, `click`, `scrollIntoView`, `programmatic`). `mouseOver` has no touch equivalent. |
-| `className` / `style` | Not accepted. Size the animation with the container `View`. (`node.style` *inside* the document is supported.) |
-| `onRemove` | Not emitted. Use React's own unmount cleanup. |
+| `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. |
 
 ## How playback works
 
@@ -255,11 +256,11 @@ properties actually change over time.
 | `text`, `tspan` | ✅ | content via the `text` attribute |
 | `textPath` | ✅ | see *Text along a path* below |
 | `image` | ✅ | `href` accepts `data:` URIs; remote URLs are blocked by the sanitiser |
-| `use`, `symbol` | ✅ | animated targets are **inlined into real clones** before render — `<use>` does not propagate animation natively in RN |
+| `use`, `symbol` | ✅ | animated targets are **inlined into real clones** before render — `<use>` does not propagate animation natively in React Native |
 | `linearGradient`, `radialGradient`, `stop` | ✅ | |
 | `pattern`, `marker` | ✅ | static geometry verified; complex cases unverified on device |
 | `mask`, `clipPath` | ✅ | |
-| `filter` + all 22 `fe*` primitives | ✅ | `feGaussianBlur`, `feDropShadow`, `feColorMatrix`, `feMerge`, `feComponentTransfer` + `feFunc*`, … Requires the New Architecture; **visual parity with the web is unverified on device** |
+| `filter` + all 22 `fe*` primitives | ✅ | `feGaussianBlur`, `feDropShadow`, `feColorMatrix`, `feMerge`, `feComponentTransfer` + `feFunc*`, … **The visual result has not yet been checked on a real device** |
 | `foreignObject` | ❌ | blocked by the shared sanitiser (embeds arbitrary host content) |
 | `script` | ❌ | blocked by the shared sanitiser |
 
@@ -269,7 +270,7 @@ properties actually change over time.
 |---|---|---|
 | `opacity`, `fill-opacity`, `stroke-opacity` | ✅ | |
 | `fill`, `stroke`, `stop-color` | ✅ | interpolated as RGBA |
-| `stroke-width`, `stroke-dasharray`, `stroke-dashoffset` | ✅ | dash arrays are converted to the numeric form RN expects |
+| `stroke-width`, `stroke-dasharray`, `stroke-dashoffset` | ✅ | dash arrays are converted to the numeric form React Native expects |
 | `x`, `y`, `width`, `height`, `cx`, `cy`, `r`, `rx`, `ry` | ✅ | |
 | `d` (**path morphing**) | ✅ | keyframes must share command structure |
 | `transform` (unified parts record) | ✅ | `translate`, `rotate`, `skew`, `scale`, `origin` |
@@ -281,7 +282,7 @@ properties actually change over time.
 
 ### Effects (`node.effects`)
 
-All effects are materialised by the shared core before rendering, so the RN
+All effects are materialised by the shared core before rendering, so the React Native
 player sees plain nodes. **All are supported:**
 
 | Effect | Status | Notes |
@@ -294,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
 
@@ -305,8 +305,8 @@ 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 |
-| `node.style` (inline or named) | ✅ | resolved to props — RN has no CSS, so explicit attributes win |
+| `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
 
@@ -314,17 +314,17 @@ 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` — seek, including **while playing** | ✅ | playback continues from the new position |
+| `setCurrentTime` — jump to a time, including **while playing** | ✅ | playback continues from the new point |
 | `setPlaybackRate` — faster, slower and **reverse** (negative) | ✅ | composes with `direction` |
 | Trigger `load` / `programmatic` | ✅ | |
 | Trigger `click` | ✅ | wrapped in a `Pressable`; a second tap applies `outAction` |
-| Trigger `scrollIntoView` | ✅ | visibility sampled by measuring against the window (RN has no `IntersectionObserver`); honours `scrollIntoViewThreshold` and `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 RN — 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,43 +562,39 @@ 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,
   pause,
   apiRef,
+  progress: progressProp,
   time,
-  timeMs,
   onPlay,
   onStop,
   onPause,
@@ -608,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);
@@ -713,11 +710,11 @@ 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 (time !== void 0 || timeMs !== void 0) {
-      const seekMs = timeMs !== void 0 ? timeMs : (time != null ? time : 0) * totalDuration;
+    if (progressProp !== void 0 || time !== void 0) {
+      const seekMs = time !== void 0 ? time : (progressProp != null ? progressProp : 0) * totalDuration;
       api.setCurrentTime(seekMs);
       return;
     }
@@ -728,15 +725,15 @@ function PixodeskSvgAnimator({
       else api.play();
       return;
     }
-    if (autoplay && startOn === "load") {
+    if (autoplay && effectiveStartOn === "load") {
       api.play();
     }
-  }, [compiled, autoplay, play, pause, time, timeMs]);
+  }, [compiled, autoplay, play, pause, progressProp, time]);
   const scrollRef = (0, import_react3.useRef)(null);
   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 = () => {
@@ -753,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);
@@ -836,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();