@pixodesk/svg-animator-web 1.0.39 → 1.0.41

package/README.md

@@ -87,8 +87,7 @@ animator.destroy();             // cleanup
 | `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      |
-| `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) |
+| `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 -->
@@ -108,9 +107,9 @@ const animator = createAnimator({
 animator.play();
 ```
 
-It returns a `PxAnimatorAPI`:
+It returns a `PxAnimatorApi`:
 
-<!-- px-check props PxAnimatorAPI pkg=web -->
+<!-- px-check props PxAnimatorApi pkg=web -->
 | Method                  | Description                                                       |
 | ----------------------- | ----------------------------------------------------------------- |
 | `play()`                | Start or resume playback                                          |
@@ -156,15 +155,23 @@ 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 materializes and removes them at
 runtime before any other normalization.
 
+When you want the markup without a player — a static first frame, a thumbnail, a snapshot —
+`renderNode` is that one step on its own: hand it a node and it returns the DOM element for it, or
+`null` when the node renders to nothing. Give it the document's `animator.definitions` as the
+second argument so named fonts resolve, and a diagnostics channel as the third to hear about
+anything it skips. It renders; it does not animate. `toDomProps(props)` is the attribute half of
+that step on its own: a node's attributes, resolved to what the DOM receives.
+
 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/format/PxAnimatorTypes.ts).
+examples, and [Schema at a glance](../../docs/format/README.md#schema-at-a-glance) for the whole
+format as typings. The wire types live in
+[`PxAnimatorTypes.ts`](../svg-animator-core/src/format/PxAnimatorTypes.ts).
 

package/dist/PxAnimator-yjuSFhQw.d.cts

@@ -0,0 +1,73 @@
+import { PxAnimatorApi as PxAnimatorApi$1, PxPlaybackApi as PxPlaybackApi$1, PxPlaybackOverride, PxAnimatorCallbacks, PxAnimatedSvgDocument, PxPlatformAdapter } from '@pixodesk/svg-animator-core';
+
+/**
+ * DOM specializations of the platform-neutral animator API types.
+ * `getRootElement()` returns a DOM `Element` on the web — these aliases keep
+ * the historical (pre-core-extraction) signatures for web consumers.
+ * @public
+ */
+type PxPlaybackApi = PxPlaybackApi$1<Element>;
+/** @public */
+type PxAnimatorApi = PxAnimatorApi$1<Element>;
+
+/**
+ * Everything `createAnimator` takes. The playback override (`timeline`, `resetTimeline` and the
+ * four shortcuts) and the callbacks are core's shared shapes — the SAME names, inline, as the
+ * React, Vue and React Native components take (review §9) — so only what is web-specific is
+ * declared here.
+ * @public
+ */
+interface PxAnimatorOptions extends PxPlaybackOverride, PxAnimatorCallbacks {
+    /** URL to fetch the animation document from. Provide either this or `doc`, not both. */
+    src?: string;
+    /** The animation document, inline (see docs/format/README.md). Provide either this or `src`, not both. */
+    doc?: PxAnimatedSvgDocument;
+    /** CSS selector or element to render the SVG into. */
+    container?: string | Element;
+}
+/**
+ * What the framework COMPONENTS build the player with: the public options plus the `adapter`
+ * that routes the frame loop's attribute writes to the elements they rendered themselves.
+ *
+ * NOT part of the public API (review §25.14). The React and Vue packages are its only callers;
+ * `createAnimator`'s signature says `PxAnimatorOptions` on purpose — a page has a DOM to write
+ * to, so for anyone else the option would only be a way to hold the player wrong. Exported as a
+ * type so those packages can name it; never documented as an option.
+ * @internal
+ */
+interface PxInternalAnimatorOptions extends PxAnimatorOptions {
+    /** A custom render target for the frame-loop engine (`PxPlatformAdapter`). */
+    adapter?: PxPlatformAdapter;
+}
+/**
+ * Creates an animator instance to control SVG animations.
+ *
+ * @param options.src URL to fetch the animation document from.
+ * @param options.doc The animation document, inline.
+ * @param options.container CSS selector or element to render the SVG into.
+ * @returns A PxAnimatorApi instance to programmatically control the animation.
+ * @public
+ */
+declare function createAnimator(options: PxAnimatorOptions): PxAnimatorApi;
+/**
+ * Scan and load for tags, e.g.
+ *  <div data-px-animation-src="animation.json"></div>
+ */
+/**
+ * Everything `createAnimator` takes except the three the tag supplies (`src`, `container`) or
+ * forbids (`data`): callbacks, the diagnostics channel, a playback override and its shortcuts.
+ * @public
+ */
+type PxTagAnimatorOptions = Omit<PxAnimatorOptions, 'src' | 'doc' | 'container'>;
+/**
+ * Scan the page for `<div data-px-animation-src="animation.json">` and create one player per
+ * match, rendered into that element and stored on it. Safe to call repeatedly: elements that
+ * already carry a player are skipped.
+ *
+ * `options` applies to EVERY player this call creates (review §15) — the same callbacks, the
+ * same override. Omit it for the zero-config path.
+ * @public
+ */
+declare function loadTagAnimators(options?: PxTagAnimatorOptions): void;
+
+export { type PxAnimatorApi as P, type PxAnimatorOptions as a, type PxPlaybackApi as b, type PxTagAnimatorOptions as c, createAnimator as d, type PxInternalAnimatorOptions as e, loadTagAnimators as l };

package/dist/PxAnimator-yjuSFhQw.d.ts

@@ -0,0 +1,73 @@
+import { PxAnimatorApi as PxAnimatorApi$1, PxPlaybackApi as PxPlaybackApi$1, PxPlaybackOverride, PxAnimatorCallbacks, PxAnimatedSvgDocument, PxPlatformAdapter } from '@pixodesk/svg-animator-core';
+
+/**
+ * DOM specializations of the platform-neutral animator API types.
+ * `getRootElement()` returns a DOM `Element` on the web — these aliases keep
+ * the historical (pre-core-extraction) signatures for web consumers.
+ * @public
+ */
+type PxPlaybackApi = PxPlaybackApi$1<Element>;
+/** @public */
+type PxAnimatorApi = PxAnimatorApi$1<Element>;
+
+/**
+ * Everything `createAnimator` takes. The playback override (`timeline`, `resetTimeline` and the
+ * four shortcuts) and the callbacks are core's shared shapes — the SAME names, inline, as the
+ * React, Vue and React Native components take (review §9) — so only what is web-specific is
+ * declared here.
+ * @public
+ */
+interface PxAnimatorOptions extends PxPlaybackOverride, PxAnimatorCallbacks {
+    /** URL to fetch the animation document from. Provide either this or `doc`, not both. */
+    src?: string;
+    /** The animation document, inline (see docs/format/README.md). Provide either this or `src`, not both. */
+    doc?: PxAnimatedSvgDocument;
+    /** CSS selector or element to render the SVG into. */
+    container?: string | Element;
+}
+/**
+ * What the framework COMPONENTS build the player with: the public options plus the `adapter`
+ * that routes the frame loop's attribute writes to the elements they rendered themselves.
+ *
+ * NOT part of the public API (review §25.14). The React and Vue packages are its only callers;
+ * `createAnimator`'s signature says `PxAnimatorOptions` on purpose — a page has a DOM to write
+ * to, so for anyone else the option would only be a way to hold the player wrong. Exported as a
+ * type so those packages can name it; never documented as an option.
+ * @internal
+ */
+interface PxInternalAnimatorOptions extends PxAnimatorOptions {
+    /** A custom render target for the frame-loop engine (`PxPlatformAdapter`). */
+    adapter?: PxPlatformAdapter;
+}
+/**
+ * Creates an animator instance to control SVG animations.
+ *
+ * @param options.src URL to fetch the animation document from.
+ * @param options.doc The animation document, inline.
+ * @param options.container CSS selector or element to render the SVG into.
+ * @returns A PxAnimatorApi instance to programmatically control the animation.
+ * @public
+ */
+declare function createAnimator(options: PxAnimatorOptions): PxAnimatorApi;
+/**
+ * Scan and load for tags, e.g.
+ *  <div data-px-animation-src="animation.json"></div>
+ */
+/**
+ * Everything `createAnimator` takes except the three the tag supplies (`src`, `container`) or
+ * forbids (`data`): callbacks, the diagnostics channel, a playback override and its shortcuts.
+ * @public
+ */
+type PxTagAnimatorOptions = Omit<PxAnimatorOptions, 'src' | 'doc' | 'container'>;
+/**
+ * Scan the page for `<div data-px-animation-src="animation.json">` and create one player per
+ * match, rendered into that element and stored on it. Safe to call repeatedly: elements that
+ * already carry a player are skipped.
+ *
+ * `options` applies to EVERY player this call creates (review §15) — the same callbacks, the
+ * same override. Omit it for the zero-config path.
+ * @public
+ */
+declare function loadTagAnimators(options?: PxTagAnimatorOptions): void;
+
+export { type PxAnimatorApi as P, type PxAnimatorOptions as a, type PxPlaybackApi as b, type PxTagAnimatorOptions as c, createAnimator as d, type PxInternalAnimatorOptions as e, loadTagAnimators as l };

package/dist/chunk-BYDBNKO7.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-BYDBNKO7.js.map

package/dist/chunk-BYDBNKO7.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 dev-docs/plans/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":[]}

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};