@pixodesk/svg-animator-web 1.0.35 → 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 fromObject = createAnimator({ data: animationDoc, container: '#container' });
+const fromObject = createAnimator({ doc: animationDoc, container: '#container' });
 
 animator.play();
 animator.pause();
@@ -81,20 +81,21 @@ 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) |
-| `config`    | `object \| string`        | Per-instance playback override, deep-merged over the document's `animator` block — same shape as the file; `null` at a slot deletes that key. A JSON string is accepted too |
-| `resetDocDefaults` | `boolean`          | Ignore the document's playback settings and start from the player's defaults, with `config` on top |
-| `duration` · `delay` | `number`        | Shortcuts for `config.timeline.duration` / `.delay` (ms) |
-| `iterations` | `number \| 'infinite'`   | Shortcut for `config.timeline.iterations` |
-| `startOn`   | `StartOn`                 | Shortcut for `config.timeline.trigger.startOn` |
+| `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; `config` is for when
+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:
 
@@ -102,13 +103,14 @@ that autostarts everywhere except inside your own transport UI:
 const animator = createAnimator({
   src: '/animation.json',
   container: '#box',
-  config: { timeline: { iterations: 'infinite', trigger: { startOn: 'programmatic' } } },
+  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                                          |
@@ -118,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                                      |
@@ -127,15 +131,13 @@ 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 */ },
 });
 ```
 
@@ -145,7 +147,7 @@ createAnimator({
 
 - `'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; honours `timeline.frameRate`. Required for path morphing in Safari < 18.5.
+- `'js'` — the player's `requestAnimationFrame` loop only; honors `timeline.frameRate`. Required for path morphing in Safari < 18.5.
 
 ### Document format & effects
 
@@ -158,8 +160,8 @@ 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