@pixodesk/svg-animator-rn 1.0.35 → 1.0.40

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} config={{ timeline: { fillMode: 'forwards' } }} />
+<PixodeskSvgAnimator doc={doc} autoplay iterations={1} timeline={{ fillMode: 'forwards' }} />
 
 // Loop forever regardless of what the document says
 <PixodeskSvgAnimator doc={doc} autoplay iterations="infinite" />
@@ -166,6 +166,7 @@ const [time, setTime] = useState(0);
 
 ## Props
 
+<!-- px-check props PixodeskSvgAnimatorProps pkg=rn -->
 | Prop | Type | Description |
 |---|---|---|
 | `doc` | `PxAnimatedSvgDocument` | The animation document to render (required) |
@@ -175,18 +176,22 @@ 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 |
-| `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 |
+| `timeline` | `object \| string` | per-instance override of the document's `timeline` block, deep-merged over it — same shape as the file; `null` at any slot deletes that key. A JSON string is accepted too. See [Playback overrides](#playback-overrides) |
+| `resetTimeline` | `boolean` | ignore the document's own timeline and start from the player's default timeline, with `timeline` on top |
+| `duration` | `number` | Shortcut for `timeline.duration` (ms) |
+| `delay` | `number` | Shortcut for `timeline.delay` (ms) |
+| `iterations` | `number \| 'infinite'` | Shortcut for `timeline.iterations` |
+| `startOn` | `PxStartOn` | Shortcut for `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 |
+| `onFinish` | `() => void` | Called when the animation reaches its end — every iteration played, or `finish()` was called |
 | `onCancel` | `() => void` | Called on cancel |
-| `onStop` | `() => void` | Called whenever playback halts (pause / cancel / finish) |
-| `onError` | `(error, componentStack?) => void` | Called when a document cannot be compiled or rendered |
+| `onRemove` | `() => void` | Called when the animator is thrown away — the component unmounted, or a new `doc` replaced it |
+| `onStop` | `() => void` | Called whenever playback halts (pause / cancel / finish / remove) |
+| `onError` | `(diagnostic) => void` | this instance will not play — the document could not be compiled or rendered; `fallback` shows instead. `diagnostic.error` is the Error, `diagnostic.detail.componentStack` when the error boundary caught it |
+| `onWarn` | `(diagnostic) => void` | it plays, but something was ignored, degraded or misspelled; without it → `console.warn` |
+| `muteWarn` | `boolean` | switch the `console.warn` fallback off — for when you know the player has something to say about this document and are prepared to tolerate it. `onWarn`, if you gave it, still fires: mute is about the console, not about you |
+| `muteError` | `boolean` | the same switch for `console.error` |
 | `fallback` | `(error) => ReactElement \| null` | Rendered in place of a failed animation (default: nothing) |
 
 With none of `autoplay` / `play` / `pause` / `progress` / `time` set, the component
@@ -196,14 +201,14 @@ renders the animation statically (initial state, no playback).
 
 The component never throws for a bad document. Compilation and rendering both
 run inside `try`/`catch`, and the rendered tree sits behind an error boundary,
-so a failure is reported through `onError` and shows `fallback` while the
-surrounding screen keeps working.
+so a failure is reported through `onError` — the shared diagnostic (`diagnostic.error` is the
+Error), exactly as on the web — and shows `fallback` while the surrounding screen keeps working.
 
 ```tsx
 <PixodeskSvgAnimator
     doc={doc}
     autoplay
-    onError={e => console.warn('animation failed:', e.message)}
+    onError={d => console.warn('animation failed:', d.message)}
     fallback={() => <Text>could not play this animation</Text>}
 />
 ```
@@ -214,11 +219,12 @@ renderer never reaches JavaScript and cannot be caught — see
 
 ### Differences from the React package
 
+<!-- px-check off differences from React, prose -->
 | Prop | Why it differs |
 |---|---|
-| `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. |
+| `timeline.engine` | Accepted inside `timeline` 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, which the player fixes at 60. |
+| `startOn: 'mouseOver'` | Has no touch equivalent, so it is not honored. 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. |
 
@@ -228,9 +234,9 @@ There is **no JavaScript frame loop** — the JS thread is idle while an
 animation runs.
 
 1. **Once per document:** the shared core flattens it
-   (`materialiseAllInTree` → effects, loops, motion-path sampling, animated
+   (`materializeAllInTree` → effects, loops, motion-path sampling, animated
    `<use>` inlining), then a track compiler densely samples every animated
-   property with `calcAnimationValues` — the same function the web frames engine
+   property with `calcAnimationValues` — the same function the web frame-loop engine
    renders with, so values match the web player exactly.
 2. **Per frame:** one reanimated progress value, driven by
    `withTiming`/`withRepeat` on the UI thread, and a tiny worklet per animated
@@ -243,73 +249,78 @@ converts it into plain values ahead of time instead of fighting the platform.
 ## Feature support
 
 Every row below was verified by running the document through the real
-pipeline (`materialiseAllInTree` → track compilation) and checking that the
+pipeline (`materializeAllInTree` → track compilation) and checking that the
 element maps to a `react-native-svg` component and that its animated
 properties actually change over time.
 
 ### Elements
 
+<!-- px-check off support matrix, prose -->
 | Element | Renders | Notes |
 |---|---|---|
 | `svg`, `g`, `defs` | ✅ | |
 | `rect`, `circle`, `ellipse`, `line`, `path`, `polygon`, `polyline` | ✅ | |
-| `text`, `tspan` | ✅ | content via the `text` attribute |
+| `text`, `tspan` | ✅ | content via `textContent` |
 | `textPath` | ✅ | see *Text along a path* below |
-| `image` | ✅ | `href` accepts `data:` URIs; remote URLs are blocked by the sanitiser |
+| `image` | ✅ | `href` accepts `data:` URIs; remote URLs are blocked by the sanitizer |
 | `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*`, … **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 |
+| `foreignObject` | ❌ | blocked by the shared sanitizer (embeds arbitrary host content) |
+| `script` | ❌ | blocked by the shared sanitizer |
 
 ### Animatable attributes
 
+<!-- px-check off support matrix, prose -->
 | Attribute | Animates | Notes |
 |---|---|---|
-| `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 React Native expects |
+| `opacity`, `fillOpacity`, `strokeOpacity` | ✅ | |
+| `fill`, `stroke`, `stopColor` | ✅ | interpolated as RGBA |
+| `strokeWidth`, `strokeDasharray`, `strokeDashoffset` | ✅ | 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` |
 | `translate` / `rotate` / `scale` (legacy per-key form) | ✅ | |
-| `offset` and `stop-color` on gradient stops | ✅ | |
+| `offset` and `stopColor` on gradient stops | ✅ | |
 | filter primitive attrs (e.g. `stdDeviation`) | ✅ | compiles correctly; on-device rendering unverified |
-| `font-size` | ✅ | |
+| `fontSize` | ✅ | |
 | Any other numeric SVG attribute | ✅ | interpolated numerically and written straight through |
 
 ### Effects (`node.effects`)
 
-All effects are materialised by the shared core before rendering, so the React Native
+All effects are materialized by the shared core before rendering, so the React Native
 player sees plain nodes. **All are supported:**
 
+<!-- px-check schema PxEffectsSchema -->
 | Effect | Status | Notes |
 |---|---|---|
 | `transformBy` | ✅ | all parts animatable, including `skew` |
-| `repeater` | ✅ | copies materialised as real elements; per-copy params animatable |
+| `repeater` | ✅ | copies materialized as real elements; per-copy params animatable |
 | `maskedBy` | ✅ | including an animated mask source |
 | `clipPath` | ✅ | including animated clip geometry |
 | `strokeTrim` | ✅ | incl. `offset` and `subPaths: 'combined'` |
 | `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) |
+| `fillGradient` / `strokeGradient` | ✅ | animated stops **and animated geometry** (`animate.gradientX1`/`Cx`/`R`, …); `gradientTransform` is static (core-wide) | <!-- px names=fillGradient,strokeGradient -->
 | `textPath` | ✅ | incl. animated `startOffset` |
 | `text.useGlyphs` | ✅ | text becomes `<path>` outlines from `definitions.fonts` — no font needed |
 
 ### Motion, timing and references
 
+<!-- px-check off support matrix, prose -->
 | Feature | Status | Notes |
 |---|---|---|
 | **Motion along a path** + `autoOrient` | ✅ | **sampled** by the core into plain transform keyframes — `react-native-svg` has no native path motion |
 | **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` / `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 |
+| `definitions.animations` / `easings` / `fonts` | ✅ | named refs resolved |
+| `node.style` (inline record) | ✅ | applied as props — React Native has no CSS, so explicit attributes win |
 
 ### Playback and triggers
 
+<!-- px-check off support matrix, prose -->
 | Feature | Status | Notes |
 |---|---|---|
 | `duration`, `delay`, `iterations` (incl. `'infinite'`) | ✅ | |
@@ -321,9 +332,9 @@ player sees plain nodes. **All are supported:**
 | `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 (React Native has no `IntersectionObserver`); honours `scrollIntoViewThreshold` and `outAction` |
+| Trigger `scrollIntoView` | ✅ | visibility sampled by measuring against the window (React Native has no `IntersectionObserver`); honors `scrollIntoViewThreshold` and `outAction` |
 | Trigger `mouseOver` | ❌ | no touch equivalent — use `click`, or drive `play` yourself |
-| `timeline.frameRate` | n/a | reanimated runs at the display refresh rate; use `compileTracks({sampleRate})` to trade memory for temporal precision |
+| `timeline.frameRate` | n/a | reanimated runs at the display refresh rate; the player prepares 60 snapshots per second of animation |
 | `timeline.engine` (`auto` / `native` / `js`) | n/a | there is no Web Animations API on React Native — playback is always native-driven |
 
 ### Known limitations
@@ -342,7 +353,7 @@ player sees plain nodes. **All are supported:**
   glyph placement by `startOffset … startOffset + pathLength` instead of
   `0 … pathLength`, so glyphs past the end of the path reach a lookup that
   returns `NSNotFound`. On native the player gives such a `<textPath>` its own
-  open copy of the path (`openClosedTextPathTargets`), which restores the
+  open copy of the path, which restores the
   correct bounds. Text that would have wrapped around past the end of the loop
   is clipped instead. Web is unaffected and left untouched.
 
@@ -381,25 +392,6 @@ config.resolver.resolveRequest = (context, moduleName, platform) => {
 A complete config is in
 [`examples/react-native-preview-player/metro.config.js`](../../examples/react-native-preview-player/metro.config.js).
 
-## Advanced exports
-
-For custom rendering or diagnostics:
-
-- `renderRnNode(node, opts)` — render a `PxNode` tree to `react-native-svg`
-  elements, with a `decorate` hook for wrapping animated elements.
-- `compileTracks(doc, { sampleRate, maxSamples, native })` — build the sampled
-  tracks yourself; `sampleRate` trades memory for temporal precision
-  (default 60/s). `native` selects the value form: the default is the SVG/DOM
-  one, `true` gives what the native views want (a `transform` becomes a
-  6-number matrix).
-- `sampleProps(tracks, tMs, stepMs, sampleCount, native)` — the worklet-safe
-  lookup. `native` renames `transform` to the native views' `matrix`; pass it
-  only for values going through reanimated's animated-props path on a device.
-- `openClosedTextPathTargets(doc, warnings?)` — the closed-path `<textPath>`
-  workaround described under [Known limitations](#known-limitations).
-- `PxRnErrorBoundary` — the boundary the component wraps itself in.
-- `RN_SVG_COMPONENTS`, `toRnPropName` — the tag and attribute maps.
-
 ## Example app
 
 A full preview player with six animations and transport controls: