@pixodesk/svg-animator-web 1.0.35 → 1.0.40

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,20 @@ 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)                   |
-| `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` |
-
-The document plays the way it was designed with no configuration at all; `config` is for when
+| `onPlay` · `onPause` · `onCancel` · `onFinish` · `onRemove` · `onStop` | `() => void` | the lifecycle callbacks, inline — the same names the components take; plus `onWarn`, `onError`, `muteWarn`, `muteError` for diagnostics. See [Callbacks](#callbacks) | <!-- px names=onPlay,onPause,onCancel,onFinish,onRemove,onStop,onWarn,onError,muteWarn,muteError -->
+| `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:
 
@@ -102,13 +102,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 +119,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 +130,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 +146,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
 
@@ -154,12 +155,12 @@ same shape as the JSON export. It comes in two modes:
 
 - **Self-contained document** — has `children`: the player renders the SVG tree and animates it.
 - **Bind-by-id document** — no `children`: the player animates a pre-existing SVG DOM, mapping
-  element ids to animation specs via `animator.animateById`.
+  each `bindings` entry names an element (`target`, `#id`) and the named animations it plays (`animateWith`).
 
 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

package/dist/chunk-RK3CEIRB.min.js

@@ -0,0 +1 @@
+var e=Object.defineProperty,r=Object.defineProperties,t=Object.getOwnPropertyDescriptors,o=Object.getOwnPropertySymbols,a=Object.prototype.hasOwnProperty,l=Object.prototype.propertyIsEnumerable,n=(r,t,o)=>t in r?e(r,t,{enumerable:!0,configurable:!0,writable:!0,value:o}):r[t]=o,c=(e,r)=>{for(var t in r||(r={}))a.call(r,t)&&n(e,t,r[t]);if(o)for(var t of o(r))l.call(r,t)&&n(e,t,r[t]);return e},f=(e,o)=>r(e,t(o)),i=(e,r)=>{var t={};for(var n in e)a.call(e,n)&&r.indexOf(n)<0&&(t[n]=e[n]);if(null!=e&&o)for(var n of o(e))r.indexOf(n)<0&&l.call(e,n)&&(t[n]=e[n]);return t},p="doc";export{c as __spreadValues,f as __spreadProps,i as __objRest,p as PX_ANIMATOR_DOC_KEY};

package/dist/chunk-TNWZIIVG.js

@@ -0,0 +1,42 @@
+var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+var __objRest = (source, exclude) => {
+  var target = {};
+  for (var prop in source)
+    if (__hasOwnProp.call(source, prop) && exclude.indexOf(prop) < 0)
+      target[prop] = source[prop];
+  if (source != null && __getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(source)) {
+      if (exclude.indexOf(prop) < 0 && __propIsEnum.call(source, prop))
+        target[prop] = source[prop];
+    }
+  return target;
+};
+
+// src/shared/PxAnimatorKeys.ts
+var PX_ANIMATOR_DOC_KEY = "doc";
+
+export {
+  __spreadValues,
+  __spreadProps,
+  __objRest,
+  PX_ANIMATOR_DOC_KEY
+};
+//# sourceMappingURL=chunk-TNWZIIVG.js.map

package/dist/chunk-TNWZIIVG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/shared/PxAnimatorKeys.ts"],"sourcesContent":["/*---------------------------------------------------------------------------------------\n * Copyright (c) Pixodesk LTD.\n * Licensed under the MIT License. See the LICENSE file in the project root for details.\n *---------------------------------------------------------------------------------------*/\n\n/**\n * Wire keys shared by every entry point.\n *\n * These live here rather than in `PxAnimator.ts` on purpose: that module used to end with a\n * top-level `if (typeof window !== 'undefined')` block publishing `createAnimator` /\n * `loadTagAnimators` as globals. A module-level side effect cannot be tree-shaken, so\n * importing ANY symbol from `PxAnimator.ts` pulled the entire full player in with it —\n * which silently made the pre-rendered builds the same size as the full one until this\n * constant was moved out. See PRERENDERED-PLAYER-BUILDS.md.\n *\n * That block is gone (API review §4) and the package now declares `\"sideEffects\": false`, but\n * keeping these here costs nothing and removes the trap for good.\n */\n\n/**\n * Key under which `createAnimator` options carry the inline animation document. The editor\n * writes it into every exported SVG+JS — `createAnimator({\"doc\": …})` — so it is part of the\n * export format, which is why it is a named constant and not a literal.\n * @internal\n */\nexport const PX_ANIMATOR_DOC_KEY = 'doc';\n\n/** Key under which `createAnimator` options carry the per-instance `timeline` override. */\nexport const PX_ANIMATOR_TIMELINE_KEY = 'timeline';\n\n/** Key that makes the override start from the player's default timeline instead of the document's. */\nexport const PX_ANIMATOR_RESET_KEY = 'resetTimeline';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyBO,IAAM,sBAAsB;","names":[]}