@pixodesk/svg-animator-web 1.0.34 → 1.0.39

package/README.md

@@ -63,11 +63,11 @@ import { createAnimator } from '@pixodesk/svg-animator-web';
 const animator = createAnimator({
   src: '/animation.json',
   container: '#container',
-  callbacks: { onFinish: () => console.log('done') },
+  onFinish: () => console.log('done'),
 });
 
 // Or from an already-loaded document object
-const animator = createAnimator({ data: animationDoc, container: '#container' });
+const fromObject = createAnimator({ doc: animationDoc, container: '#container' });
 
 animator.play();
 animator.pause();
@@ -81,16 +81,36 @@ animator.destroy();             // cleanup
 
 `createAnimator(options)` takes a single options object:
 
+<!-- px-check props PxAnimatorOptions pkg=web -->
 | Option | Type | Description |
 | ----------- | ------------------------- | -------------------------------------------------- |
-| `src`       | `string`                  | URL to fetch the animation document from (provide either `src` or `data`) |
-| `data`      | `PxAnimatedSvgDocument`   | Inline animation document object                    |
+| `src`       | `string`                  | URL to fetch the animation document from (provide either `src` or `doc`) |
+| `doc`       | `PxAnimatedSvgDocument`   | Inline animation document object                    |
 | `container` | `string \| Element`       | CSS selector or element to render the SVG into      |
-| `callbacks` | `PxAnimatorCallbacksConfig` | Lifecycle callbacks (see below)                   |
+| `onPlay` · `onPause` · `onCancel` · `onFinish` · `onRemove` · `onStop` | `() => void` | the lifecycle callbacks, inline — the same names the components take; plus `onWarn`, `onError`, `silent` for diagnostics. See [Callbacks](#callbacks) | <!-- px names=onPlay,onPause,onCancel,onFinish,onRemove,onStop,onWarn,onError,silent -->
 | `adapter`   | `PxPlatformAdapter`       | Custom attribute-writer for frame-loop rendering (advanced) |
+| `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` · `delay` | `number`        | Shortcuts for `timeline.duration` / `.delay` (ms) | <!-- px names=duration,delay -->
+| `iterations` | `number \| 'infinite'`   | Shortcut for `timeline.iterations` |
+| `startOn`   | `PxStartOn`               | Shortcut for `timeline.trigger.startOn` |
+
+The document plays the way it was designed with no configuration at all; `timeline` is for when
+one page needs it to play differently — the same file mounted twice at two speeds, or a file
+that autostarts everywhere except inside your own transport UI:
+
+```js
+const animator = createAnimator({
+  src: '/animation.json',
+  container: '#box',
+  timeline: { iterations: 'infinite', trigger: { startOn: 'programmatic' } },
+});
+animator.play();
+```
 
 It returns a `PxAnimatorAPI`:
 
+<!-- px-check props PxAnimatorAPI pkg=web -->
 | Method                  | Description                                                       |
 | ----------------------- | ----------------------------------------------------------------- |
 | `play()`                | Start or resume playback                                          |
@@ -100,6 +120,8 @@ It returns a `PxAnimatorAPI`:
 | `setPlaybackRate(rate)` | Change speed (1 = normal, 2 = double, -1 = reverse)               |
 | `getCurrentTime()`      | Current time in ms                                                |
 | `setCurrentTime(ms)`    | Jump to a point in the animation, in milliseconds from its start |
+| `getCurrentProgress()`  | The same position as 0–1 of the whole run (`null` before ready)   |
+| `setCurrentProgress(p)` | Jump to 0–1 of the whole run                                      |
 | `isPlaying()`           | Whether the animation is currently playing                        |
 | `isReady()`             | Whether the document has loaded (relevant for URL-based creation) |
 | `getRootElement()`      | The rendered SVG DOM element                                      |
@@ -109,25 +131,23 @@ It returns a `PxAnimatorAPI`:
 
 ```js
 createAnimator({
-  data: doc,
+  doc: doc,
   container: '#container',
-  callbacks: {
-    onPlay:   () => { /* started/resumed */ },
-    onPause:  () => { /* paused */ },
-    onCancel: () => { /* cancelled */ },
-    onFinish: () => { /* finished naturally (or via finish()) */ },
-    onRemove: () => { /* destroyed / cleaned up */ },
-  },
+  onPlay:   () => { /* started/resumed */ },
+  onPause:  () => { /* paused */ },
+  onCancel: () => { /* canceled */ },
+  onFinish: () => { /* finished naturally (or via finish()) */ },
+  onRemove: () => { /* destroyed / cleaned up */ },
 });
 ```
 
-### Engine modes
+### Engines
 
-`animator.mode` selects the playback engine:
+`animator.timeline.engine` selects how the animated attributes get updated:
 
-- `'auto'` (default) — try the Web Animations API, fall back to `requestAnimationFrame`.
-- `'waapi'` — Web Animations API only.
-- `'frames'` — `requestAnimationFrame` only; honours `animator.frameRate`. Required for path morphing.
+- `'auto'` (default) — the browser where it can (Web Animations API; its ScrollTimeline for scroll-driven documents), the player's frame loop where it must.
+- `'native'` — the browser only (Web Animations API).
+- `'js'` — the player's `requestAnimationFrame` loop only; honors `timeline.frameRate`. Required for path morphing in Safari < 18.5.
 
 ### Document format & effects
 
@@ -140,11 +160,11 @@ same shape as the JSON export. It comes in two modes:
 
 Elements may also carry a `node.effects` bucket (structural effects such as
 `transformBy`, `repeater`, `maskedBy`, `strokeTrim`, `clone`, `fillGradient` /
-`strokeGradient`, `textPath`). This player materialises and removes them at
-runtime before any other normalisation.
+`strokeGradient`, `textPath`). This player materializes and removes them at
+runtime before any other normalization.
 
 See the [JSON format reference](../../docs/format/README.md#json-format-reference) and
 [Player effects](../../docs/format/README.md#player-effects) for the full schema and
 examples (compact printable schema: [SCHEMA.md](../../SCHEMA.md)). The wire
-types live in [`PxAnimatorTypes.ts`](../svg-animator-core/src/PxAnimatorTypes.ts).
+types live in [`PxAnimatorTypes.ts`](../svg-animator-core/src/format/PxAnimatorTypes.ts).