@depup/lottie-react 2.4.1-depup.0 → 3.0.0-depup.0

package/build/overlays/LottieLoading.js

@@ -0,0 +1,87 @@
+import { renderStyledElement } from "../animation/renderStyledElement.js";
+import { useLottieInstance } from "../animation/useLottieInstance.js";
+import { LottieState } from "../animation/types.js";
+import { overlayStyles } from "./overlayStyles.js";
+import { forwardRef } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/overlays/LottieLoading.tsx
+/**
+* The class the overlay carries, and the name React deduplicates its stylesheet
+* by. One string does both, so two components can only collide in the document
+* if they already collide in CSS.
+*/
+const lottieLoadingClass = "lottie-loading";
+/** The class the built-in indicator carries. */
+const spinnerClass = "lottie-spinner";
+const spinKeyframes = "lottie-spin";
+const loadingInKeyframes = "lottie-loading-in";
+/** The two knobs a consumer's stylesheet can set. `showAfter` writes the first. */
+const delayProperty = "--lottie-loading-delay";
+/**
+* The overlay's own defaults, at zero specificity and inside the library's
+* cascade layer, so that any rule the consumer
+* writes beats them per property.
+*
+* The indicator is drawn in `currentColor` and sized in `em`, so it takes the
+* surrounding text's colour and size rather than any this library picked.
+*
+* Three of these are load-bearing.
+*
+* The wait is expressed as a fade **in** from a keyframe, never as a hidden
+* element the animation reveals. The two look equivalent and are not: with the
+* element hidden by its own rule, anything that switches the animation off
+* leaves it hidden for good, while written this way the same switch shows it
+* immediately, which is the right way round for an indicator.
+*
+* Both durations read a custom property with the default in the fallback, which
+* is what lets a stylesheet change either one, at any level from the element to
+* the document. `showAfter` sets the same property, so the prop and the CSS are
+* one mechanism rather than two that can disagree.
+*
+* Under a reduced-motion preference the indicator is **slowed rather than
+* stopped**, because the preference asks for less motion and a stationary
+* indicator no longer says the page is working.
+*/
+const lottieLoadingStyles = `${overlayStyles(lottieLoadingClass)}:where(.${lottieLoadingClass}) > :where(.${spinnerClass}){box-sizing:border-box;width:2em;height:2em;border:0.15em solid currentColor;border-top-color:transparent;border-radius:50%;animation-name:${spinKeyframes};animation-duration:0.8s;animation-timing-function:linear;animation-iteration-count:infinite}:where(.${lottieLoadingClass}){animation-name:${loadingInKeyframes};animation-duration:var(--lottie-loading-fade,150ms);animation-delay:var(${delayProperty},400ms);animation-fill-mode:both}@media (prefers-reduced-motion:reduce){:where(.${lottieLoadingClass}) > :where(.${spinnerClass}){animation-duration:1.6s}}@keyframes ${spinKeyframes}{to{transform:rotate(360deg)}}@keyframes ${loadingInKeyframes}{from{opacity:0}}`;
+/**
+* What to show while the animation loads.
+*
+* Render it among the children of a component that publishes an animation, or
+* anywhere at all with the result of `useLottie`. It covers the box it sits in
+* while the animation is loading and renders nothing the rest of the time.
+*
+* ```jsx
+* <Lottie src="/hero.json">
+*   <LottieDisplay />
+*   <LottieLoading />
+* </Lottie>
+* ```
+*
+* It takes every attribute of the `div` it renders, and `ref` names that same
+* element. Its own rules are all zero-specificity, so any of them can be
+* replaced one property at a time from your own stylesheet. If your CSS lives
+* in cascade layers, declare `@layer lottie-react;` before your own styles so
+* the library's layer ranks below them.
+*/
+const LottieLoading = forwardRef(function LottieLoading({ lottie, className, children, showAfter, style, ...rest }, ref) {
+	const { state } = useLottieInstance(lottie);
+	if (state !== LottieState.loading) return null;
+	return renderStyledElement({
+		tag: "div",
+		styleClass: lottieLoadingClass,
+		styles: lottieLoadingStyles,
+		className,
+		attributes: {
+			role: "status",
+			...rest,
+			style: showAfter === void 0 ? style : {
+				[delayProperty]: `${String(showAfter)}ms`,
+				...style
+			}
+		},
+		ref,
+		children: children ?? /* @__PURE__ */ jsx("div", { className: spinnerClass })
+	});
+});
+//#endregion
+export { LottieLoading, lottieLoadingClass, lottieLoadingStyles };

package/build/overlays/overlayStyles.cjs

@@ -0,0 +1,33 @@
+//#region src/overlays/overlayStyles.ts
+/**
+* The rules that put an overlay over the animation, scoped to the class it is
+* given.
+*
+* Both overlays cover the same box in the same way, and each still ships its
+* own copy under its own name, because the class and the stylesheet's `href`
+* are one string. Sharing the class instead would mean two names on one element
+* and a second stylesheet to order against the first.
+*
+* The overlay anchors to whichever ancestor is positioned, which is the element
+* `<Lottie>` renders around its children.
+*
+* Three details are not free choices. The four edges are written out rather than
+* as `inset`, because the test environment does not expand that shorthand, so a
+* rule written with it could never be shown to apply. And `z-index` is what
+* decides the overlay wins against the animation whichever order the two are
+* written in, since without it a display rendered afterwards paints on top.
+*
+* The third is the background. An overlay spans everything the animation's box
+* holds, the control bar included, so with no background of its own the buttons
+* and the seek bar read straight through the message it is there to show. It is
+* mixed from `Canvas`, the system colour for page background, rather than from
+* `currentColor`, because a scrim has to move towards the surface behind it and
+* `currentColor` is the text, which would lighten the overlay on a dark page and
+* darken it on a light one. Partly transparent, so what is underneath stays
+* visible as context rather than disappearing.
+*/
+function overlayStyles(styleClass) {
+	return `:where(.${styleClass}){position:absolute;top:0;right:0;bottom:0;left:0;z-index:1;display:flex;align-items:center;justify-content:center;background:color-mix(in srgb,Canvas 80%,transparent)}`;
+}
+//#endregion
+exports.overlayStyles = overlayStyles;

package/build/overlays/overlayStyles.js

@@ -0,0 +1,33 @@
+//#region src/overlays/overlayStyles.ts
+/**
+* The rules that put an overlay over the animation, scoped to the class it is
+* given.
+*
+* Both overlays cover the same box in the same way, and each still ships its
+* own copy under its own name, because the class and the stylesheet's `href`
+* are one string. Sharing the class instead would mean two names on one element
+* and a second stylesheet to order against the first.
+*
+* The overlay anchors to whichever ancestor is positioned, which is the element
+* `<Lottie>` renders around its children.
+*
+* Three details are not free choices. The four edges are written out rather than
+* as `inset`, because the test environment does not expand that shorthand, so a
+* rule written with it could never be shown to apply. And `z-index` is what
+* decides the overlay wins against the animation whichever order the two are
+* written in, since without it a display rendered afterwards paints on top.
+*
+* The third is the background. An overlay spans everything the animation's box
+* holds, the control bar included, so with no background of its own the buttons
+* and the seek bar read straight through the message it is there to show. It is
+* mixed from `Canvas`, the system colour for page background, rather than from
+* `currentColor`, because a scrim has to move towards the surface behind it and
+* `currentColor` is the text, which would lighten the overlay on a dark page and
+* darken it on a light one. Partly transparent, so what is underneath stays
+* visible as context rather than disappearing.
+*/
+function overlayStyles(styleClass) {
+	return `:where(.${styleClass}){position:absolute;top:0;right:0;bottom:0;left:0;z-index:1;display:flex;align-items:center;justify-content:center;background:color-mix(in srgb,Canvas 80%,transparent)}`;
+}
+//#endregion
+export { overlayStyles };

package/build/utils/SubscriptionManager.cjs

@@ -0,0 +1,42 @@
+//#region src/utils/SubscriptionManager.ts
+/**
+* A typed event emitter, small enough to avoid a dependency and precise enough
+* that a wrong payload is a compile error rather than a runtime surprise.
+*
+* The map it is given must be declared as a `type` rather than an `interface`,
+* because an interface has no implicit index signature and cannot satisfy the
+* constraint above.
+*
+* Both methods are fields rather than prototype methods so they can be handed
+* out on their own, which is how `subscribe` reaches a consumer.
+*/
+var SubscriptionManager = class {
+	listeners = {};
+	/** Registers a handler and returns the function that removes it. */
+	subscribe = (type, handler) => {
+		let handlers = this.listeners[type];
+		if (!handlers) {
+			handlers = /* @__PURE__ */ new Set();
+			this.listeners[type] = handlers;
+		}
+		handlers.add(handler);
+		return () => {
+			this.listeners[type]?.delete(handler);
+		};
+	};
+	/**
+	* Calls every handler registered for an event.
+	*
+	* The set is walked in place rather than copied, because `frame` is notified
+	* once per rendered frame and a copy per notification would allocate at that
+	* rate. A handler that removes itself while being called is safe; one that
+	* subscribes during its own notification may be called in the same pass.
+	*/
+	notify = (type, ...args) => {
+		this.listeners[type]?.forEach((handler) => {
+			handler(...args);
+		});
+	};
+};
+//#endregion
+exports.SubscriptionManager = SubscriptionManager;

package/build/utils/SubscriptionManager.d.cts

@@ -0,0 +1,30 @@
+//#region src/utils/SubscriptionManager.d.ts
+/** The shape a subscription map has to have: a handler per event name. */
+type HandlerMap = Record<string, (...args: never[]) => void>;
+/**
+ * A typed event emitter, small enough to avoid a dependency and precise enough
+ * that a wrong payload is a compile error rather than a runtime surprise.
+ *
+ * The map it is given must be declared as a `type` rather than an `interface`,
+ * because an interface has no implicit index signature and cannot satisfy the
+ * constraint above.
+ *
+ * Both methods are fields rather than prototype methods so they can be handed
+ * out on their own, which is how `subscribe` reaches a consumer.
+ */
+declare class SubscriptionManager<Subscriptions extends HandlerMap> {
+  private readonly listeners;
+  /** Registers a handler and returns the function that removes it. */
+  subscribe: <Type extends keyof Subscriptions>(type: Type, handler: Subscriptions[Type]) => (() => void);
+  /**
+   * Calls every handler registered for an event.
+   *
+   * The set is walked in place rather than copied, because `frame` is notified
+   * once per rendered frame and a copy per notification would allocate at that
+   * rate. A handler that removes itself while being called is safe; one that
+   * subscribes during its own notification may be called in the same pass.
+   */
+  notify: <Type extends keyof Subscriptions>(type: Type, ...args: Parameters<Subscriptions[Type]>) => void;
+}
+//#endregion
+export { SubscriptionManager };

package/build/utils/SubscriptionManager.d.ts

@@ -0,0 +1,30 @@
+//#region src/utils/SubscriptionManager.d.ts
+/** The shape a subscription map has to have: a handler per event name. */
+type HandlerMap = Record<string, (...args: never[]) => void>;
+/**
+ * A typed event emitter, small enough to avoid a dependency and precise enough
+ * that a wrong payload is a compile error rather than a runtime surprise.
+ *
+ * The map it is given must be declared as a `type` rather than an `interface`,
+ * because an interface has no implicit index signature and cannot satisfy the
+ * constraint above.
+ *
+ * Both methods are fields rather than prototype methods so they can be handed
+ * out on their own, which is how `subscribe` reaches a consumer.
+ */
+declare class SubscriptionManager<Subscriptions extends HandlerMap> {
+  private readonly listeners;
+  /** Registers a handler and returns the function that removes it. */
+  subscribe: <Type extends keyof Subscriptions>(type: Type, handler: Subscriptions[Type]) => (() => void);
+  /**
+   * Calls every handler registered for an event.
+   *
+   * The set is walked in place rather than copied, because `frame` is notified
+   * once per rendered frame and a copy per notification would allocate at that
+   * rate. A handler that removes itself while being called is safe; one that
+   * subscribes during its own notification may be called in the same pass.
+   */
+  notify: <Type extends keyof Subscriptions>(type: Type, ...args: Parameters<Subscriptions[Type]>) => void;
+}
+//#endregion
+export { SubscriptionManager };

package/build/utils/SubscriptionManager.js

@@ -0,0 +1,42 @@
+//#region src/utils/SubscriptionManager.ts
+/**
+* A typed event emitter, small enough to avoid a dependency and precise enough
+* that a wrong payload is a compile error rather than a runtime surprise.
+*
+* The map it is given must be declared as a `type` rather than an `interface`,
+* because an interface has no implicit index signature and cannot satisfy the
+* constraint above.
+*
+* Both methods are fields rather than prototype methods so they can be handed
+* out on their own, which is how `subscribe` reaches a consumer.
+*/
+var SubscriptionManager = class {
+	listeners = {};
+	/** Registers a handler and returns the function that removes it. */
+	subscribe = (type, handler) => {
+		let handlers = this.listeners[type];
+		if (!handlers) {
+			handlers = /* @__PURE__ */ new Set();
+			this.listeners[type] = handlers;
+		}
+		handlers.add(handler);
+		return () => {
+			this.listeners[type]?.delete(handler);
+		};
+	};
+	/**
+	* Calls every handler registered for an event.
+	*
+	* The set is walked in place rather than copied, because `frame` is notified
+	* once per rendered frame and a copy per notification would allocate at that
+	* rate. A handler that removes itself while being called is safe; one that
+	* subscribes during its own notification may be called in the same pass.
+	*/
+	notify = (type, ...args) => {
+		this.listeners[type]?.forEach((handler) => {
+			handler(...args);
+		});
+	};
+};
+//#endregion
+export { SubscriptionManager };

package/build/utils/createLogger.cjs

@@ -0,0 +1,25 @@
+//#region src/utils/createLogger.ts
+const PREFIX = "[lottie-react]";
+const noop = () => void 0;
+/**
+* Builds a logger that says nothing unless the caller asked for it.
+*
+* This is tracing rather than diagnosis, and it deliberately reports only what
+* no subscription can: the configuration actually handed to the engine, and the
+* teardown. Anything a consumer can already subscribe to is not repeated here,
+* and nothing per frame is ever written.
+*
+* There is no `warn`, because everything worth warning about reaches the
+* consumer through the `error` subscription with the reason attached.
+*
+* Unlike a development-only warning this survives into a production build on
+* purpose, so a problem that appears only in one can still be looked at.
+*/
+function createLogger(debug) {
+	if (!debug) return { log: noop };
+	return { log: (message, ...rest) => {
+		console.log(`${PREFIX} ${message}`, ...rest);
+	} };
+}
+//#endregion
+exports.createLogger = createLogger;

package/build/utils/createLogger.js

@@ -0,0 +1,25 @@
+//#region src/utils/createLogger.ts
+const PREFIX = "[lottie-react]";
+const noop = () => void 0;
+/**
+* Builds a logger that says nothing unless the caller asked for it.
+*
+* This is tracing rather than diagnosis, and it deliberately reports only what
+* no subscription can: the configuration actually handed to the engine, and the
+* teardown. Anything a consumer can already subscribe to is not repeated here,
+* and nothing per frame is ever written.
+*
+* There is no `warn`, because everything worth warning about reaches the
+* consumer through the `error` subscription with the reason attached.
+*
+* Unlike a development-only warning this survives into a production build on
+* purpose, so a problem that appears only in one can still be looked at.
+*/
+function createLogger(debug) {
+	if (!debug) return { log: noop };
+	return { log: (message, ...rest) => {
+		console.log(`${PREFIX} ${message}`, ...rest);
+	} };
+}
+//#endregion
+export { createLogger };

package/build/utils/isSameJson.cjs

@@ -0,0 +1,37 @@
+//#region src/utils/isSameJson.ts
+/** Narrows without a cast: any array can be read as a list of unknowns. */
+function isJsonArray(value) {
+	return Array.isArray(value);
+}
+/** Narrows without a cast: any plain object can be read as unknown-valued. */
+function isJsonObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Compares two JSON values by content: objects, arrays, and the primitives JSON
+* can hold. Key order does not matter, and `NaN` equals itself.
+*
+* Deliberately narrower than a general deep-equality function. It has no
+* understanding of `Map`, `Set`, `Date`, `RegExp` or typed arrays, and treating
+* one as a plain object would report two different values as the same. Animation
+* data is parsed JSON, so none of them can appear in it.
+*
+* It recurses, so a value that refers to itself overflows the stack rather than
+* returning. JSON cannot express one.
+*/
+function isSameJson(a, b) {
+	if (Object.is(a, b)) return true;
+	if (isJsonArray(a)) {
+		if (!isJsonArray(b) || a.length !== b.length) return false;
+		return a.every((item, index) => isSameJson(item, b[index]));
+	}
+	if (isJsonObject(a)) {
+		if (!isJsonObject(b)) return false;
+		const keys = Object.keys(a);
+		if (keys.length !== Object.keys(b).length) return false;
+		return keys.every((key) => Object.hasOwn(b, key) && isSameJson(a[key], b[key]));
+	}
+	return false;
+}
+//#endregion
+exports.isSameJson = isSameJson;

package/build/utils/isSameJson.js

@@ -0,0 +1,37 @@
+//#region src/utils/isSameJson.ts
+/** Narrows without a cast: any array can be read as a list of unknowns. */
+function isJsonArray(value) {
+	return Array.isArray(value);
+}
+/** Narrows without a cast: any plain object can be read as unknown-valued. */
+function isJsonObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Compares two JSON values by content: objects, arrays, and the primitives JSON
+* can hold. Key order does not matter, and `NaN` equals itself.
+*
+* Deliberately narrower than a general deep-equality function. It has no
+* understanding of `Map`, `Set`, `Date`, `RegExp` or typed arrays, and treating
+* one as a plain object would report two different values as the same. Animation
+* data is parsed JSON, so none of them can appear in it.
+*
+* It recurses, so a value that refers to itself overflows the stack rather than
+* returning. JSON cannot express one.
+*/
+function isSameJson(a, b) {
+	if (Object.is(a, b)) return true;
+	if (isJsonArray(a)) {
+		if (!isJsonArray(b) || a.length !== b.length) return false;
+		return a.every((item, index) => isSameJson(item, b[index]));
+	}
+	if (isJsonObject(a)) {
+		if (!isJsonObject(b)) return false;
+		const keys = Object.keys(a);
+		if (keys.length !== Object.keys(b).length) return false;
+		return keys.every((key) => Object.hasOwn(b, key) && isSameJson(a[key], b[key]));
+	}
+	return false;
+}
+//#endregion
+export { isSameJson };

package/build/utils/mergeRefs.cjs

@@ -0,0 +1,37 @@
+//#region src/utils/mergeRefs.ts
+/**
+* Sends one element to several refs.
+*
+* An element has a single `ref` slot, so any element that both this library and
+* the person using it want a handle on needs one callback that feeds both.
+*
+* Teardown is the part that is not boilerplate, because the two supported React
+* versions differ. React 19 treats a function returned from a ref callback as
+* its cleanup and then never calls that ref with `null`, while React 18
+* discards the return and calls with `null`. So each ref gets its own cleanup
+* where it returned one and a `null` call where it did not, and the combined
+* teardown is returned for React 19 to run. React 18 ignores it and calls this
+* callback with `null` instead, which does the same work.
+*/
+function mergeRefs(...refs) {
+	return (node) => {
+		const teardowns = refs.map((ref) => {
+			if (typeof ref === "function") {
+				const cleanup = ref(node);
+				return typeof cleanup === "function" ? cleanup : () => ref(null);
+			}
+			if (ref) {
+				ref.current = node;
+				return () => {
+					ref.current = null;
+				};
+			}
+			return () => void 0;
+		});
+		return () => {
+			for (const teardown of teardowns) teardown();
+		};
+	};
+}
+//#endregion
+exports.mergeRefs = mergeRefs;

package/build/utils/mergeRefs.js

@@ -0,0 +1,37 @@
+//#region src/utils/mergeRefs.ts
+/**
+* Sends one element to several refs.
+*
+* An element has a single `ref` slot, so any element that both this library and
+* the person using it want a handle on needs one callback that feeds both.
+*
+* Teardown is the part that is not boilerplate, because the two supported React
+* versions differ. React 19 treats a function returned from a ref callback as
+* its cleanup and then never calls that ref with `null`, while React 18
+* discards the return and calls with `null`. So each ref gets its own cleanup
+* where it returned one and a `null` call where it did not, and the combined
+* teardown is returned for React 19 to run. React 18 ignores it and calls this
+* callback with `null` instead, which does the same work.
+*/
+function mergeRefs(...refs) {
+	return (node) => {
+		const teardowns = refs.map((ref) => {
+			if (typeof ref === "function") {
+				const cleanup = ref(node);
+				return typeof cleanup === "function" ? cleanup : () => ref(null);
+			}
+			if (ref) {
+				ref.current = node;
+				return () => {
+					ref.current = null;
+				};
+			}
+			return () => void 0;
+		});
+		return () => {
+			for (const teardown of teardowns) teardown();
+		};
+	};
+}
+//#endregion
+export { mergeRefs };

package/build/utils/useStableValue.cjs

@@ -0,0 +1,26 @@
+const require_isSameJson = require("./isSameJson.cjs");
+let react = require("react");
+//#region src/utils/useStableValue.ts
+/**
+* Keeps a value stable until its **content** changes, so it can be depended on.
+*
+* A value written inline at a call site is a new value on every render, and an
+* effect that depends on it therefore re-runs on every render. Where that
+* effect also sets state, the component re-renders, the value is built again,
+* and it never settles.
+*
+* The reference is compared first, so a caller who passes something they
+* already hold pays nothing at all. Only a caller who rebuilds an equal value
+* pays for the comparison, which is exactly the case being rescued.
+*
+* Assigning state during render is React's own answer to adjusting state when a
+* prop changes: the component renders again immediately, before anything is
+* committed, so the intermediate result is never seen.
+*/
+function useStableValue(value) {
+	const [stable, setStable] = (0, react.useState)(value);
+	if (stable !== value && !require_isSameJson.isSameJson(stable, value)) setStable(value);
+	return stable;
+}
+//#endregion
+exports.useStableValue = useStableValue;

package/build/utils/useStableValue.js

@@ -0,0 +1,26 @@
+import { isSameJson } from "./isSameJson.js";
+import { useState } from "react";
+//#region src/utils/useStableValue.ts
+/**
+* Keeps a value stable until its **content** changes, so it can be depended on.
+*
+* A value written inline at a call site is a new value on every render, and an
+* effect that depends on it therefore re-runs on every render. Where that
+* effect also sets state, the component re-renders, the value is built again,
+* and it never settles.
+*
+* The reference is compared first, so a caller who passes something they
+* already hold pays nothing at all. Only a caller who rebuilds an equal value
+* pays for the comparison, which is exactly the case being rescued.
+*
+* Assigning state during render is React's own answer to adjusting state when a
+* prop changes: the component renders again immediately, before anything is
+* committed, so the intermediate result is never seen.
+*/
+function useStableValue(value) {
+	const [stable, setStable] = useState(value);
+	if (stable !== value && !isSameJson(stable, value)) setStable(value);
+	return stable;
+}
+//#endregion
+export { useStableValue };

package/changes.json

@@ -1,10 +1,5 @@
 {
-  "bumped": {
-    "lottie-web": {
-      "from": "^5.10.2",
-      "to": "^5.13.0"
-    }
-  },
-  "timestamp": "2026-03-18T22:40:32.392Z",
-  "totalUpdated": 1
+  "bumped": {},
+  "timestamp": "2026-08-16T00:26:02.638Z",
+  "totalUpdated": 0
 }