@pixodesk/svg-animator-web 1.0.41 → 1.0.44

package/dist/index.prerendered-waapi.umd.js

@@ -575,14 +575,18 @@ var PixodeskAnimator = (() => {
     alternate: "alternate",
     alternateReverse: "alternate-reverse"
   };
-  var PxStartOn = {
+  var PxTriggerStart = {
     load: "load",
     mouseOver: "mouseOver",
     click: "click",
-    scrollIntoView: "scrollIntoView",
-    programmatic: "programmatic"
+    none: "none"
   };
-  var PxOutAction = {
+  var PxOffScreenAction = {
+    pause: "pause",
+    continue: "continue",
+    reset: "reset"
+  };
+  var PxMouseOutAction = {
     continue: "continue",
     pause: "pause",
     reset: "reset",
@@ -641,16 +645,20 @@ var PixodeskAnimator = (() => {
     auto: "auto"
   });
   var PX_TRIGGER_DEFAULTS = {
-    startOn: "load",
-    outAction: "continue",
-    scrollIntoViewThreshold: 0
+    start: "load",
+    offScreen: "pause",
+    mouseOut: "continue",
+    visibilityThreshold: 0.5,
+    visibilityDebounce: 150
   };
   function resolveTrigger(trigger) {
-    var _a, _b, _c;
+    var _a, _b, _c, _d, _e;
     return {
-      startOn: (_a = trigger == null ? void 0 : trigger.startOn) != null ? _a : PX_TRIGGER_DEFAULTS.startOn,
-      outAction: (_b = trigger == null ? void 0 : trigger.outAction) != null ? _b : PX_TRIGGER_DEFAULTS.outAction,
-      scrollIntoViewThreshold: (_c = trigger == null ? void 0 : trigger.scrollIntoViewThreshold) != null ? _c : PX_TRIGGER_DEFAULTS.scrollIntoViewThreshold
+      start: (_a = trigger == null ? void 0 : trigger.start) != null ? _a : PX_TRIGGER_DEFAULTS.start,
+      offScreen: (_b = trigger == null ? void 0 : trigger.offScreen) != null ? _b : PX_TRIGGER_DEFAULTS.offScreen,
+      mouseOut: (_c = trigger == null ? void 0 : trigger.mouseOut) != null ? _c : PX_TRIGGER_DEFAULTS.mouseOut,
+      visibilityThreshold: (_d = trigger == null ? void 0 : trigger.visibilityThreshold) != null ? _d : PX_TRIGGER_DEFAULTS.visibilityThreshold,
+      visibilityDebounce: (_e = trigger == null ? void 0 : trigger.visibilityDebounce) != null ? _e : PX_TRIGGER_DEFAULTS.visibilityDebounce
     };
   }
   var PxLoopRepeatAt = {
@@ -768,9 +776,9 @@ var PixodeskAnimator = (() => {
     } else {
       if (timeline.duration !== void 0) flat.duration = timeline.duration;
       if (timeline.trigger !== void 0) {
-        const _b = timeline.trigger, { finishAction } = _b, restTrigger = __objRest(_b, ["finishAction"]);
+        const _b = timeline.trigger, { finish } = _b, restTrigger = __objRest(_b, ["finish"]);
         if (Object.keys(restTrigger).length) flat.trigger = restTrigger;
-        if (finishAction !== void 0) flat.resetOnFinish = finishAction === "reset";
+        if (finish !== void 0) flat.resetOnFinish = finish === "reset";
       }
       if (timeline.delay !== void 0) flat.delay = timeline.delay;
       if (timeline.iterations !== void 0) flat.iterations = timeline.iterations;
@@ -871,13 +879,15 @@ var PixodeskAnimator = (() => {
     PxAnimationDefinitionSchema
   ]));
   var PxTriggerSchema = implementsInterface()(px.object({
-    startOn: px.enum([PxStartOn.load, PxStartOn.mouseOver, PxStartOn.click, PxStartOn.scrollIntoView, PxStartOn.programmatic], PX_TRIGGER_DEFAULTS.startOn).optional(),
-    outAction: px.enum([PxOutAction.continue, PxOutAction.pause, PxOutAction.reset, PxOutAction.reverse], PX_TRIGGER_DEFAULTS.outAction).optional(),
+    start: px.enum([PxTriggerStart.load, PxTriggerStart.mouseOver, PxTriggerStart.click, PxTriggerStart.none], PX_TRIGGER_DEFAULTS.start).optional(),
+    offScreen: px.enum([PxOffScreenAction.pause, PxOffScreenAction.continue, PxOffScreenAction.reset], PX_TRIGGER_DEFAULTS.offScreen).optional(),
+    mouseOut: px.enum([PxMouseOutAction.continue, PxMouseOutAction.pause, PxMouseOutAction.reset, PxMouseOutAction.reverse], PX_TRIGGER_DEFAULTS.mouseOut).optional(),
     // What happens after a NATURAL finish — `'hold'` (default: keep the end state per
-    // `fill`) or `'reset'` (snap back to the start state). Pairs with `outAction` ("what
-    // happens when the trigger condition ends"); both end-of-life knobs now read alike.
-    finishAction: px.enum([PxFinishAction.hold, PxFinishAction.reset]).optional(),
-    scrollIntoViewThreshold: px.number().optional()
+    // `fill`) or `'reset'` (snap back to the start state). One of four occasion keys
+    // (`start`, `offScreen`, `mouseOut`, `finish`), all named the same way.
+    finish: px.enum([PxFinishAction.hold, PxFinishAction.reset]).optional(),
+    visibilityThreshold: px.number().optional(),
+    visibilityDebounce: px.number().optional()
   }));
   var PxGlyphSchema = implementsInterface()(px.object({
     width: px.number(),
@@ -2440,7 +2450,6 @@ var PixodeskAnimator = (() => {
   }
 
   // ../svg-animator-core/src/playback/PxPlaybackTime.ts
-  var PX_RATE_REJECTED = "setPlaybackRate: rate must be finite and non-zero";
   function isValidPlaybackRate(rate) {
     return Number.isFinite(rate) && rate !== 0;
   }
@@ -2486,32 +2495,34 @@ var PixodeskAnimator = (() => {
     /** The player failed where it did not expect to — report it to us. */
     internal: "internal"
   };
-  function asError(error) {
-    return typeof error === "string" ? new Error(error) : error;
+  var DOCS_URL = "https://github.com/pixodesk/pixodesk-svg-animator/blob/main/docs/diagnostics.md";
+  function codeLine(code) {
+    return "PX" + code + " " + DOCS_URL + "#px" + code;
+  }
+  function errorIn(data) {
+    return data.find((d) => d instanceof Error);
   }
   function createDiagnostics(config, prefix) {
     const tag = prefix ? prefix + " " : "";
     return {
-      warn: (kind, message, detail) => {
+      warn: (kind, code, ...data) => {
+        const message = codeLine(code);
         if (config == null ? void 0 : config.onWarn) {
-          config.onWarn({ kind, message, detail });
+          config.onWarn({ code, kind, data, message });
           return;
         }
         if (config == null ? void 0 : config.muteWarn) return;
-        const line = tag + kind + ": " + message;
-        if (detail === void 0) console.warn(line);
-        else console.warn(line, detail);
+        console.warn(tag + kind + " " + message, ...data);
       },
-      error: (kind, error, detail) => {
-        const err = asError(error);
+      error: (kind, code, ...data) => {
+        const message = codeLine(code);
+        const error = errorIn(data);
         if (config == null ? void 0 : config.onError) {
-          config.onError({ kind, message: err.message, error: err, detail });
+          config.onError({ code, kind, data, message, error });
           return;
         }
         if (config == null ? void 0 : config.muteError) return;
-        const line = tag + kind + ": " + err.message;
-        if (detail === void 0) console.error(line);
-        else console.error(line, detail);
+        console.error(tag + kind + " " + message, ...data);
       }
     };
   }
@@ -2564,6 +2575,196 @@ var PixodeskAnimator = (() => {
     return e instanceof Error ? e : new Error(String(e));
   }
 
+  // src/registry/PxAnimatorRegistry.ts
+  var STORE_KEY = /* @__PURE__ */ Symbol.for("@pixodesk/svg-animator-web:animators");
+  var GLOBAL_NAME = "__pixodeskAnimators";
+  function store() {
+    const g = globalThis;
+    let s = g[STORE_KEY];
+    if (!s) {
+      const animators = /* @__PURE__ */ new Set();
+      const listeners = /* @__PURE__ */ new Set();
+      s = {
+        animators,
+        listeners,
+        getAll: () => Array.from(animators),
+        subscribe: (listener) => {
+          listeners.add(listener);
+          return () => {
+            listeners.delete(listener);
+          };
+        }
+      };
+      g[STORE_KEY] = s;
+      if (g[GLOBAL_NAME] === void 0) g[GLOBAL_NAME] = s;
+    }
+    return s;
+  }
+  function notify(event, animator) {
+    for (const listener of store().listeners) {
+      try {
+        listener(event, animator);
+      } catch (e) {
+        setTimeout(() => {
+          throw e;
+        }, 0);
+      }
+    }
+  }
+  function registerAnimator(animator) {
+    const s = store();
+    if (s.animators.has(animator)) return;
+    s.animators.add(animator);
+    notify("add", animator);
+    const destroy = animator.destroy.bind(animator);
+    animator.destroy = () => {
+      destroy();
+      if (s.animators.delete(animator)) notify("remove", animator);
+    };
+  }
+  function withRegistryEvents(callbacks, api) {
+    const fire = (event) => {
+      const a = api();
+      if (a) notify(event, a);
+    };
+    return __spreadProps(__spreadValues({}, callbacks), {
+      onPlay: () => {
+        var _a;
+        (_a = callbacks == null ? void 0 : callbacks.onPlay) == null ? void 0 : _a.call(callbacks);
+        fire("play");
+      },
+      onPause: () => {
+        var _a;
+        (_a = callbacks == null ? void 0 : callbacks.onPause) == null ? void 0 : _a.call(callbacks);
+        fire("pause");
+      },
+      onCancel: () => {
+        var _a;
+        (_a = callbacks == null ? void 0 : callbacks.onCancel) == null ? void 0 : _a.call(callbacks);
+        fire("cancel");
+      },
+      onFinish: () => {
+        var _a;
+        (_a = callbacks == null ? void 0 : callbacks.onFinish) == null ? void 0 : _a.call(callbacks);
+        fire("finish");
+      }
+    });
+  }
+
+  // src/triggers/PxVisibilityGate.ts
+  var PLAY_WHEN_VISIBLE_DEFAULTS = {
+    offScreen: PX_TRIGGER_DEFAULTS.offScreen,
+    visibilityThreshold: PX_TRIGGER_DEFAULTS.visibilityThreshold,
+    visibilityDebounce: PX_TRIGGER_DEFAULTS.visibilityDebounce
+  };
+  var THRESHOLD_STEPS = Array.from({ length: 21 }, (_, i) => i / 20);
+  function effectiveRatio(entry) {
+    var _a, _b;
+    const target = entry.boundingClientRect;
+    const visible = entry.intersectionRect;
+    if (!(target == null ? void 0 : target.height) || !visible) return entry.intersectionRatio;
+    const live = typeof window !== "undefined" && window.innerHeight ? window.innerHeight : Infinity;
+    const declared = (_b = (_a = entry.rootBounds) == null ? void 0 : _a.height) != null ? _b : Infinity;
+    const viewport = Math.min(live, declared);
+    const denom = Math.min(target.height, Number.isFinite(viewport) ? viewport : target.height);
+    return denom > 0 ? visible.height / denom : entry.intersectionRatio;
+  }
+  function openGate(host) {
+    return {
+      requestStart: () => host.play(),
+      dispose: () => {
+      }
+    };
+  }
+  function isGated(offScreen) {
+    return offScreen !== PxOffScreenAction.continue;
+  }
+  function createVisibilityGate(root, trigger, host) {
+    if (!isGated(trigger.offScreen)) return openGate(host);
+    if (typeof IntersectionObserver === "undefined") return openGate(host);
+    const threshold = trigger.visibilityThreshold;
+    const debounceMs = trigger.visibilityDebounce;
+    let isOpen = void 0;
+    let startPending = false;
+    let pausedByGate = false;
+    let lastRatio = 0;
+    let openTimer;
+    const cancelPendingOpen = () => {
+      if (openTimer !== void 0) {
+        clearTimeout(openTimer);
+        openTimer = void 0;
+      }
+    };
+    const open = () => {
+      openTimer = void 0;
+      if (isOpen === true) return;
+      isOpen = true;
+      if (startPending || pausedByGate) {
+        startPending = false;
+        pausedByGate = false;
+        host.play();
+      }
+    };
+    const close = () => {
+      cancelPendingOpen();
+      if (isOpen === false) return;
+      isOpen = false;
+      if (!host.isPlaying()) return;
+      if (trigger.offScreen === PxOffScreenAction.reset) {
+        host.cancel();
+      } else {
+        host.pause();
+      }
+      pausedByGate = true;
+    };
+    const apply = (ratio) => {
+      lastRatio = ratio;
+      if (typeof document !== "undefined" && document.visibilityState === "hidden") {
+        close();
+        return;
+      }
+      if (ratio >= threshold) {
+        if (isOpen === true || openTimer !== void 0) return;
+        if (debounceMs > 0) openTimer = setTimeout(open, debounceMs);
+        else open();
+        return;
+      }
+      if (ratio <= 0) {
+        close();
+        return;
+      }
+      if (isOpen !== true) cancelPendingOpen();
+    };
+    const observer = new IntersectionObserver((entries) => {
+      const last = entries[entries.length - 1];
+      if (last) apply(last.isIntersecting ? effectiveRatio(last) : 0);
+    }, { threshold: THRESHOLD_STEPS });
+    observer.observe(root);
+    const onVisibilityChange = () => {
+      apply(lastRatio);
+    };
+    const hasDocument = typeof document !== "undefined";
+    if (hasDocument) document.addEventListener("visibilitychange", onVisibilityChange);
+    return {
+      requestStart: (immediate) => {
+        if (immediate || isOpen === true) {
+          cancelPendingOpen();
+          isOpen = true;
+          startPending = false;
+          pausedByGate = false;
+          host.play();
+          return;
+        }
+        startPending = true;
+      },
+      dispose: () => {
+        cancelPendingOpen();
+        observer.disconnect();
+        if (hasDocument) document.removeEventListener("visibilitychange", onVisibilityChange);
+      }
+    };
+  }
+
   // src/triggers/PxAnimatorTriggers.ts
   function setupAnimationTriggers(api, trigger, diag) {
     const report = diag != null ? diag : createDiagnostics(void 0, "[PxAnimator]");
@@ -2571,10 +2772,10 @@ var PixodeskAnimator = (() => {
     const dispose = () => {
       for (const undo of cleanups.splice(0)) undo();
     };
-    const { startOn, outAction, scrollIntoViewThreshold } = resolveTrigger(trigger);
+    const resolved = resolveTrigger(trigger);
     const root = api.getRootElement();
     if (!root) {
-      report.warn(PxDiagnosticKind.host, "setupAnimationTriggers: No root element found for animation.");
+      report.warn(PxDiagnosticKind.host, 1201 /* triggersNoRoot */);
       return dispose;
     }
     let reversed = false;
@@ -2585,27 +2786,34 @@ var PixodeskAnimator = (() => {
       }
       api.play();
     };
-    const handleEndAction = () => {
-      switch (outAction) {
-        case "pause":
+    const gate = createVisibilityGate(root, resolved, {
+      isPlaying: () => api.isPlaying(),
+      play: start,
+      pause: () => api.pause(),
+      cancel: () => api.cancel()
+    });
+    cleanups.push(() => gate.dispose());
+    const handleMouseOut = () => {
+      switch (resolved.mouseOut) {
+        case PxMouseOutAction.pause:
           api.pause();
           break;
-        case "reset":
+        case PxMouseOutAction.reset:
           api.cancel();
           break;
-        case "reverse":
+        case PxMouseOutAction.reverse:
           reversed = true;
           api.setPlaybackRate(-1);
           api.play();
           break;
-        case "continue":
+        case PxMouseOutAction.continue:
         default:
           break;
       }
     };
-    switch (startOn) {
-      case "load": {
-        const startHandler = () => start();
+    switch (resolved.start) {
+      case PxTriggerStart.load: {
+        const startHandler = () => gate.requestStart(false);
         if (document.readyState === "complete") {
           startHandler();
         } else {
@@ -2614,14 +2822,14 @@ var PixodeskAnimator = (() => {
         }
         break;
       }
-      case "mouseOver": {
+      case PxTriggerStart.mouseOver: {
         let enteredOnce = false;
         const mouseOverHandler = () => {
           enteredOnce = true;
-          start();
+          gate.requestStart(true);
         };
         const mouseOutHandler = () => {
-          if (enteredOnce) handleEndAction();
+          if (enteredOnce) handleMouseOut();
         };
         root.addEventListener("mouseenter", mouseOverHandler);
         root.addEventListener("mouseleave", mouseOutHandler);
@@ -2631,51 +2839,16 @@ var PixodeskAnimator = (() => {
         });
         break;
       }
-      case "click": {
+      case PxTriggerStart.click: {
         const clickHandler = () => {
-          if (api.isPlaying()) {
-            handleEndAction();
-          } else {
-            start();
-          }
+          if (api.isPlaying()) api.pause();
+          else gate.requestStart(true);
         };
         root.addEventListener("click", clickHandler);
         cleanups.push(() => root.removeEventListener("click", clickHandler));
         break;
       }
-      case "scrollIntoView": {
-        const effectiveRatio = (entry) => {
-          var _a, _b;
-          const target = entry.boundingClientRect;
-          const visible = entry.intersectionRect;
-          if (!(target == null ? void 0 : target.height) || !visible) return entry.intersectionRatio;
-          const live = typeof window !== "undefined" && window.innerHeight ? window.innerHeight : Infinity;
-          const declared = (_b = (_a = entry.rootBounds) == null ? void 0 : _a.height) != null ? _b : Infinity;
-          const viewport = Math.min(live, declared);
-          const denom = Math.min(target.height, Number.isFinite(viewport) ? viewport : target.height);
-          return denom > 0 ? visible.height / denom : entry.intersectionRatio;
-        };
-        const thresholdSteps = Array.from({ length: 21 }, (_, i) => i / 20);
-        let wasIntersecting = false;
-        const observer = new IntersectionObserver(
-          (entries) => {
-            entries.forEach((entry) => {
-              if (entry.isIntersecting && effectiveRatio(entry) >= scrollIntoViewThreshold) {
-                wasIntersecting = true;
-                start();
-              } else if (wasIntersecting) {
-                wasIntersecting = false;
-                handleEndAction();
-              }
-            });
-          },
-          { threshold: thresholdSteps }
-        );
-        observer.observe(root);
-        cleanups.push(() => observer.disconnect());
-        break;
-      }
-      case "programmatic":
+      case PxTriggerStart.none:
         break;
     }
     return dispose;
@@ -2683,7 +2856,12 @@ var PixodeskAnimator = (() => {
 
   // src/engines/PxAnimatorFrameLoop.ts
   function getSelector(id) {
-    return "#" + id;
+    return "#" + escapeCssId(id);
+  }
+  function escapeCssId(id) {
+    const css = globalThis.CSS;
+    if (typeof (css == null ? void 0 : css.escape) === "function") return css.escape(id);
+    return id.replace(/^([0-9])/, (_all, digit) => "\\3" + digit + " ").replace(/([^\w\-\\ ])/g, "\\$1");
   }
 
   // src/engines/PxAnimatorWebApi.ts
@@ -2790,9 +2968,9 @@ var PixodeskAnimator = (() => {
       if (doc.id) {
         const rootSelector = getSelector(doc.id);
         rootElement = document.querySelector(rootSelector);
-        if (!rootElement) diag.warn(PxDiagnosticKind.host, "createWebApiAnimator: No root element found for selector: " + rootSelector);
+        if (!rootElement) diag.warn(PxDiagnosticKind.host, 1202 /* noRootForSelector */, rootSelector);
       } else {
-        diag.warn(PxDiagnosticKind.host, "createWebApiAnimator: No root element provided");
+        diag.warn(PxDiagnosticKind.host, 1203 /* noRootElement */);
       }
     }
     const bindings = normalizeBindings(doc, PxTimelineEngine.native);
@@ -2805,18 +2983,18 @@ var PixodeskAnimator = (() => {
     let finishNotified = false;
     let removeCalled = false;
     if (!(bindings == null ? void 0 : bindings.length)) {
-      diag.warn(PxDiagnosticKind.document, "createWebApiAnimator: No animation bindings defined");
+      diag.warn(PxDiagnosticKind.document, 1105 /* noBindings */);
     }
     for (const binding of bindings || []) {
       const animDef = binding.animate;
       if (!animDef || typeof animDef !== "object" || Array.isArray(animDef)) {
-        diag.warn(PxDiagnosticKind.document, "createWebApiAnimator: Empty or unresolved binding", binding);
+        diag.warn(PxDiagnosticKind.document, 1106 /* unresolvedBinding */, binding);
         continue;
       }
       const selector = getSelector(binding.id);
       const elements = (rootElement == null ? void 0 : rootElement.querySelectorAll(selector)) || document.querySelectorAll(selector);
       if (elements.length === 0) {
-        diag.warn(PxDiagnosticKind.host, 'createWebApiAnimator: No elements found for selector "' + selector + '"');
+        diag.warn(PxDiagnosticKind.host, 1206 /* noElementsForSelector */, selector);
       }
       const keyframesMap = convertToWebApiKeyframes(animDef, unsupportedSet, config);
       const positiveDelay = config.delay && config.delay > 0 ? config.delay : void 0;
@@ -2865,14 +3043,14 @@ var PixodeskAnimator = (() => {
               }
               animations.push(anim);
             } catch (e) {
-              diag.warn(PxDiagnosticKind.internal, "createWebApiAnimator: could not build the animation", e);
+              diag.warn(PxDiagnosticKind.internal, 1004 /* animationBuildFailed */, e);
             }
           }
         }
       }
     }
     if (!forceEvenIfHasUnsupportedAttrs && unsupportedSet.size) {
-      diag.warn(PxDiagnosticKind.platform, "Unsupported CSS attrs: " + [...unsupportedSet].join(", "));
+      diag.warn(PxDiagnosticKind.platform, 1104 /* unsupportedAnimatedAttrs */, [...unsupportedSet].join(", "));
       return null;
     }
     const api = {
@@ -2917,7 +3095,7 @@ var PixodeskAnimator = (() => {
       },
       "setPlaybackRate": (rate) => {
         if (!isValidPlaybackRate(rate)) {
-          diag.warn(PxDiagnosticKind.usage, PX_RATE_REJECTED);
+          diag.warn(PxDiagnosticKind.usage, 1401 /* rateRejected */);
           return api;
         }
         animations.forEach((a) => a.playbackRate = rate);
@@ -2957,7 +3135,7 @@ var PixodeskAnimator = (() => {
       }
     };
     if (config.timelineSource === "scroll") {
-      if (config.trigger) diag.warn(PxDiagnosticKind.usage, "scroll timeline: `animator.trigger` is ignored (triggers do not apply to scroll-driven playback)");
+      if (config.trigger) diag.warn(PxDiagnosticKind.usage, 1306 /* scrollTriggerIgnored */);
     } else {
       const detachTriggers = setupAnimationTriggers(api, (_b = config.trigger) != null ? _b : {}, diag);
       const destroyEngine = api.destroy.bind(api);
@@ -3001,20 +3179,25 @@ var PixodeskAnimator = (() => {
       return build();
     } catch (e) {
       const err = asThrownError(e);
-      createDiagnostics(options, "[PxAnimator]").error(PxDiagnosticKind.internal, "createAnimator: could not build the player \u2014 " + err.message, err);
+      createDiagnostics(options, "[PxAnimator]").error(PxDiagnosticKind.internal, 1001 /* buildFailed */, err);
       return createInertAnimator();
     }
   }
+  function registered(options, build) {
+    let apiRef;
+    const api = build(withRegistryEvents(toEngineCallbacks(options), () => apiRef));
+    if (api.isReady()) {
+      apiRef = api;
+      registerAnimator(api);
+    }
+    return api;
+  }
   function createPrerenderedWaapiAnimator(options) {
     const doc = requireDoc(options);
-    return buildOrReport(options, () => {
+    return registered(options, (callbacks) => buildOrReport(options, () => {
       const animatorConfig = getAnimatorConfig(doc) || {};
-      return finaliseAnimator(
-        animatorConfig,
-        toEngineCallbacks(options),
-        (cb) => createWebApiAnimator(doc, cb, null, true)
-      );
-    });
+      return finaliseAnimator(animatorConfig, callbacks, (cb) => createWebApiAnimator(doc, cb, null, true));
+    }));
   }
 
   // src/shared/PxAnimatorKeys.ts