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

package/build/animation/useLottieAnimation.cjs

@@ -0,0 +1,434 @@
+const require_createLogger = require("../utils/createLogger.cjs");
+const require_SubscriptionManager = require("../utils/SubscriptionManager.cjs");
+const require_useStableValue = require("../utils/useStableValue.cjs");
+const require_collectMarkerCrossings = require("./collectMarkerCrossings.cjs");
+const require_hasExpressions = require("./hasExpressions.cjs");
+const require_LottieRegistryContext = require("./LottieRegistryContext.cjs");
+const require_normalizeAnimationSource = require("./normalizeAnimationSource.cjs");
+const require_resolveSeekTarget = require("./resolveSeekTarget.cjs");
+const require_types = require("./types.cjs");
+let react = require("react");
+//#region src/animation/useLottieAnimation.ts
+/** Nothing guarantees a thrown value is an `Error`, and a reason has to be one. */
+function toError(cause) {
+	return cause instanceof Error ? cause : new Error(String(cause));
+}
+/**
+* Everything the animation does, with no opinion about how it is rendered.
+*
+* It takes the engine as an argument so the same logic serves every build.
+* Reach it through `useLottie`, `useLottieSvg` or `useLottieLight` rather than
+* directly.
+*/
+function useLottieAnimation(lottie, options) {
+	const { src, renderer, rendererSettings, loop, speed, direction, autoplay = false, segment, assetsPath, debug = false, subscriptions } = options;
+	const [manager] = (0, react.useState)(() => new require_SubscriptionManager.SubscriptionManager());
+	const [display, setDisplay] = (0, react.useState)(null);
+	const setDisplayRef = (0, react.useCallback)((node) => {
+		setDisplay(node);
+	}, []);
+	const [root, setRoot] = (0, react.useState)(null);
+	const setRootRef = (0, react.useCallback)((node) => {
+		setRoot(node);
+	}, []);
+	const [animationItem, setAnimationItem] = (0, react.useState)(null);
+	const [state, setState] = (0, react.useState)(require_types.LottieState.loading);
+	const [error, setError] = (0, react.useState)(null);
+	const [loadAttempt, setLoadAttempt] = (0, react.useState)(1);
+	const reload = (0, react.useCallback)(() => {
+		setLoadAttempt((previous) => previous + 1);
+	}, []);
+	const [playableFrames, setPlayableFrames] = (0, react.useState)(0);
+	const [playableDuration, setPlayableDuration] = (0, react.useState)(0);
+	const [speedValue, setSpeedValue] = (0, react.useState)(speed ?? 1);
+	const [directionValue, setDirectionValue] = (0, react.useState)(direction ?? require_types.LottieDirection.forward);
+	const [loopValue, setLoopValue] = (0, react.useState)(loop ?? false);
+	const source = require_useStableValue.useStableValue(src);
+	const loadConfig = require_useStableValue.useStableValue({
+		renderer,
+		rendererSettings,
+		autoplay,
+		segment,
+		assetsPath
+	});
+	const itemRef = (0, react.useRef)(null);
+	const valuesRef = (0, react.useRef)({
+		speed: speedValue,
+		direction: directionValue,
+		loop: loopValue
+	});
+	valuesRef.current.speed = speedValue;
+	valuesRef.current.direction = directionValue;
+	valuesRef.current.loop = loopValue;
+	const stateRef = (0, react.useRef)(state);
+	stateRef.current = state;
+	const debugRef = (0, react.useRef)(debug);
+	debugRef.current = debug;
+	const subscriptionsRef = (0, react.useRef)(subscriptions);
+	subscriptionsRef.current = subscriptions;
+	const driversRef = (0, react.useRef)({});
+	const scrubbedFrom = (0, react.useRef)(null);
+	const markerMemory = (0, react.useRef)(null);
+	/**
+	* Warns once per field when a value is driven from a prop and from a setter.
+	*
+	* Both keep working, per field and last writer wins, but they will disagree
+	* the next time the prop changes, and that is worth saying out loud while
+	* someone is building rather than leaving them to find it.
+	*/
+	const noteDriver = (0, react.useCallback)((field, driver) => {
+		if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
+			const previous = driversRef.current[field];
+			if (previous === void 0) driversRef.current[field] = driver;
+			else if (previous !== driver && previous !== "both") {
+				driversRef.current[field] = "both";
+				console.warn(`[lottie-react] "${field}" is driven from both the ${field} prop and a setter. Both keep working and the last one to write wins, but they will disagree the next time the prop changes. Drive it from one place.`);
+			}
+		}
+	}, []);
+	const applySpeed = (0, react.useCallback)((next, driver) => {
+		noteDriver("speed", driver);
+		setSpeedValue(next);
+		itemRef.current?.setSpeed(next);
+	}, [noteDriver]);
+	const applyDirection = (0, react.useCallback)((next, driver) => {
+		noteDriver("direction", driver);
+		setDirectionValue(next);
+		itemRef.current?.setDirection(next === require_types.LottieDirection.forward ? 1 : -1);
+	}, [noteDriver]);
+	const applyLoop = (0, react.useCallback)((next, driver) => {
+		noteDriver("loop", driver);
+		setLoopValue(next);
+		const item = itemRef.current;
+		if (item) {
+			item.playCount = item.playDirection < 0 && typeof next === "number" ? next : 0;
+			item.loop = next;
+		}
+	}, [noteDriver]);
+	const setSpeed = (0, react.useCallback)((next) => {
+		applySpeed(typeof next === "function" ? next(valuesRef.current.speed) : next, "setter");
+	}, [applySpeed]);
+	const setDirection = (0, react.useCallback)((next) => {
+		applyDirection(typeof next === "function" ? next(valuesRef.current.direction) : next, "setter");
+	}, [applyDirection]);
+	const setLoop = (0, react.useCallback)((next) => {
+		applyLoop(typeof next === "function" ? next(valuesRef.current.loop) : next, "setter");
+	}, [applyLoop]);
+	/**
+	* Plays from wherever the animation is, or from the beginning if it is
+	* sitting at the end it plays towards.
+	*
+	* The restart is not a convenience. Playing forwards from the final frame
+	* does nothing, and playing in reverse from frame 0 does nothing either: the
+	* engine decides it has already finished, pauses, and reports completion
+	* without advancing. Both are the same fault seen from either end.
+	*/
+	const play = (0, react.useCallback)(() => {
+		const item = itemRef.current;
+		if (item === null) return;
+		const reverse = item.playDirection < 0;
+		const finished = reverse ? item.currentFrame <= 0 : item.currentFrame >= item.totalFrames - 1;
+		const numericLoop = typeof item.loop === "number" ? item.loop : null;
+		const exhausted = numericLoop !== null && (reverse ? item.playCount < 0 : item.playCount >= numericLoop);
+		if (finished || exhausted) item.playCount = reverse && numericLoop !== null ? numericLoop : 0;
+		if (finished) {
+			markerMemory.current = null;
+			item.goToAndPlay(reverse ? item.totalFrames : 0, true);
+		} else item.play();
+		setState(require_types.LottieState.playing);
+	}, []);
+	const pause = (0, react.useCallback)(() => {
+		const item = itemRef.current;
+		if (item === null) return;
+		item.pause();
+		setState(require_types.LottieState.paused);
+	}, []);
+	const stop = (0, react.useCallback)(() => {
+		const item = itemRef.current;
+		if (item === null) return;
+		markerMemory.current = null;
+		item.playCount = 0;
+		item.goToAndStop(0, true);
+		setState(require_types.LottieState.stopped);
+	}, []);
+	/**
+	* Reads the playable range, and how it is being played, back off the engine.
+	*
+	* A segment rewrites `firstFrame` and `totalFrames`, so the two values we
+	* report about length have to follow it or a progress bar keeps measuring
+	* whatever was playable before. It settles direction and speed as well: a
+	* range whose end precedes its start plays backwards, a forward range played
+	* while reversed turns the animation around, and a forward range at a
+	* negative speed flips the speed instead. Reporting what was asked for rather
+	* than what happened would make each of those a quiet lie.
+	*/
+	const refreshRange = (0, react.useCallback)((item) => {
+		setPlayableFrames(item.totalFrames);
+		setPlayableDuration(item.getDuration(false));
+		setDirectionValue(item.playDirection < 0 ? require_types.LottieDirection.reverse : require_types.LottieDirection.forward);
+		setSpeedValue(item.playSpeed);
+	}, []);
+	/**
+	* Resolves a seek target, and says so in development when it cannot.
+	*
+	* Shared by `seek` and `scrubTo` so both report the same way. The message is
+	* built inside the guard rather than passed in, because an argument built at
+	* a call site survives as a discarded expression even once the branch that
+	* used it has gone.
+	*/
+	const resolveOrWarn = (0, react.useCallback)((item, target) => {
+		const resolved = require_resolveSeekTarget.resolveSeekTarget(item, target);
+		if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
+			if (resolved === null) console.warn(`[lottie-react] the seek target ${JSON.stringify(target)} could not be resolved, so nothing moved. A marker name has to match one the animation carries, and every other unit has to be a finite number.`);
+			else if (resolved.frame !== resolved.requested && typeof target === "object" && target.marker !== void 0) console.warn(`[lottie-react] the marker "${target.marker}" lies outside the playable range, so the seek was held at frame ${resolved.frame}. Markers are placed against the whole animation, while seeking is relative to whatever a segment has left playable.`);
+		}
+		return resolved === null ? null : resolved.frame;
+	}, []);
+	const seek = (0, react.useCallback)((target) => {
+		const item = itemRef.current;
+		if (item === null) return;
+		const frame = resolveOrWarn(item, target);
+		if (frame === null) return;
+		markerMemory.current = null;
+		if (item.isPaused) item.goToAndStop(frame, true);
+		else item.goToAndPlay(frame, true);
+	}, [resolveOrWarn]);
+	const scrubStart = (0, react.useCallback)(() => {
+		const item = itemRef.current;
+		if (item === null) return;
+		scrubbedFrom.current = stateRef.current;
+		item.pause();
+		setState(require_types.LottieState.paused);
+	}, []);
+	const scrubTo = (0, react.useCallback)((frame) => {
+		const item = itemRef.current;
+		if (item === null) return;
+		const resolved = resolveOrWarn(item, frame);
+		if (resolved === null) return;
+		markerMemory.current = null;
+		item.goToAndStop(resolved, true);
+		setState(require_types.LottieState.paused);
+	}, [resolveOrWarn]);
+	const scrubEnd = (0, react.useCallback)(() => {
+		if (itemRef.current === null) return;
+		const before = scrubbedFrom.current;
+		scrubbedFrom.current = null;
+		if (before === require_types.LottieState.playing) play();
+	}, [play]);
+	const playSegments = (0, react.useCallback)((segments, options) => {
+		const item = itemRef.current;
+		if (item === null) return;
+		const ranges = require_resolveSeekTarget.resolveSegments(item, segments);
+		if (ranges === null) {
+			if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") console.warn(`[lottie-react] playSegments could not use ${JSON.stringify(segments)}, so nothing changed. A range is two different finite frame numbers, and a marker has to carry a duration. A marker without one labels a position rather than a span: seek to it and play instead.`);
+			return;
+		}
+		item.playSegments(ranges, options?.queue !== true || item.isPaused);
+		setState(require_types.LottieState.playing);
+	}, []);
+	const resetSegments = (0, react.useCallback)(() => {
+		const item = itemRef.current;
+		if (item === null) return;
+		const wasPlaying = !item.isPaused;
+		const { segment } = loadConfig;
+		if (segment === void 0) item.resetSegments(true);
+		else item.playSegments([[segment[0], segment[1]]], true);
+		if (!wasPlaying) item.pause();
+	}, [loadConfig]);
+	(0, react.useEffect)(() => {
+		const unsubscribers = [
+			manager.subscribe(require_types.LottieSubscription.ready, () => subscriptionsRef.current?.ready?.()),
+			manager.subscribe(require_types.LottieSubscription.play, () => subscriptionsRef.current?.play?.()),
+			manager.subscribe(require_types.LottieSubscription.pause, () => subscriptionsRef.current?.pause?.()),
+			manager.subscribe(require_types.LottieSubscription.stop, () => subscriptionsRef.current?.stop?.()),
+			manager.subscribe(require_types.LottieSubscription.complete, () => subscriptionsRef.current?.complete?.()),
+			manager.subscribe(require_types.LottieSubscription.loopCompleted, () => subscriptionsRef.current?.loopCompleted?.()),
+			manager.subscribe(require_types.LottieSubscription.frame, (event) => subscriptionsRef.current?.frame?.(event)),
+			manager.subscribe(require_types.LottieSubscription.marker, (event) => subscriptionsRef.current?.marker?.(event)),
+			manager.subscribe(require_types.LottieSubscription.newState, (event) => subscriptionsRef.current?.newState?.(event)),
+			manager.subscribe(require_types.LottieSubscription.error, (event) => subscriptionsRef.current?.error?.(event))
+		];
+		return () => {
+			for (const unsubscribe of unsubscribers) unsubscribe();
+		};
+	}, [manager]);
+	const notifiedState = (0, react.useRef)(state);
+	(0, react.useEffect)(() => {
+		const previous = notifiedState.current;
+		if (previous === state) return;
+		notifiedState.current = state;
+		manager.notify(require_types.LottieSubscription.newState, { state });
+		if (state === require_types.LottieState.playing) manager.notify(require_types.LottieSubscription.play);
+		else if (state === require_types.LottieState.paused) manager.notify(require_types.LottieSubscription.pause);
+		else if (state === require_types.LottieState.stopped && previous !== require_types.LottieState.loading) manager.notify(require_types.LottieSubscription.stop);
+	}, [state, manager]);
+	(0, react.useEffect)(() => {
+		if (display === null) return;
+		const logger = require_createLogger.createLogger(debugRef.current);
+		setState(require_types.LottieState.loading);
+		setError(null);
+		markerMemory.current = null;
+		const fail = (cause) => {
+			manager.notify(require_types.LottieSubscription.error, { error: cause });
+			setError(cause);
+			setState(require_types.LottieState.error);
+		};
+		const normalized = require_normalizeAnimationSource.normalizeAnimationSource(source);
+		if (normalized === null) {
+			fail(/* @__PURE__ */ new Error("lottie-react: `src` must be a non-empty path or a parsed animation object."));
+			return;
+		}
+		const chosenRenderer = loadConfig.renderer ?? require_types.LottieRenderer.svg;
+		const reducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+		const autoplayed = loadConfig.autoplay && !reducedMotion;
+		if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
+			if (loadConfig.autoplay && reducedMotion) console.warn("[lottie-react] autoplay was not started because this device asks for reduced motion. The animation is loaded and play() works; offer a control rather than starting it for them.");
+		}
+		logger.log("loading the animation", {
+			loadAttempt,
+			renderer: chosenRenderer,
+			autoplay: autoplayed,
+			loop: valuesRef.current.loop,
+			segment: loadConfig.segment
+		});
+		let item;
+		try {
+			item = lottie.loadAnimation({
+				...normalized,
+				container: display,
+				renderer: chosenRenderer,
+				rendererSettings: loadConfig.rendererSettings,
+				loop: valuesRef.current.loop,
+				autoplay: autoplayed,
+				initialSegment: loadConfig.segment === void 0 ? void 0 : [loadConfig.segment[0], loadConfig.segment[1]],
+				assetsPath: loadConfig.assetsPath
+			});
+		} catch (cause) {
+			fail(toError(cause));
+			return;
+		}
+		itemRef.current = item;
+		setAnimationItem(item);
+		item.setSpeed(valuesRef.current.speed);
+		item.setDirection(valuesRef.current.direction === require_types.LottieDirection.forward ? 1 : -1);
+		let sortedMarkers = [];
+		const onDomLoaded = () => {
+			sortedMarkers = require_resolveSeekTarget.readMarkers(item).sort((a, b) => a.time - b.time);
+			setPlayableFrames(item.totalFrames);
+			setPlayableDuration(item.getDuration(false));
+			if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
+				if (autoplayed) {
+					const repeats = valuesRef.current.loop;
+					if ((repeats === true ? Number.POSITIVE_INFINITY : item.getDuration(false) * (typeof repeats === "number" ? repeats + 1 : 1)) > 5) console.warn("[lottie-react] this animation starts by itself and moves for more than five seconds, which needs a way to pause it whenever anything else shares the page (WCAG 2.2.2, level A). <LottieControls> is one; any pause affordance satisfies it.");
+				}
+				if ("expressionsPlugin" in item && item.expressionsPlugin === null && "animationData" in item && require_hasExpressions.hasExpressions(item.animationData)) console.warn("[lottie-react] this animation uses expressions, which the light engine does not evaluate, so it renders without them. LottieSvg and useLottieSvg run them and still draw svg only; Lottie and useLottie run them with every renderer.");
+			}
+			setState(item.isPaused ? require_types.LottieState.stopped : require_types.LottieState.playing);
+			manager.notify(require_types.LottieSubscription.ready);
+		};
+		const onDataFailed = () => {
+			fail(/* @__PURE__ */ new Error("lottie-react: the animation could not be loaded. The engine reported no reason; check that the `src` path resolves and returns animation JSON."));
+		};
+		const onComplete = () => {
+			setState(require_types.LottieState.stopped);
+			manager.notify(require_types.LottieSubscription.complete);
+		};
+		const onLoopComplete = () => {
+			manager.notify(require_types.LottieSubscription.loopCompleted);
+		};
+		const onEnterFrame = () => {
+			const current = item.currentFrame;
+			manager.notify(require_types.LottieSubscription.frame, { currentFrame: current });
+			const previous = markerMemory.current;
+			markerMemory.current = current;
+			if (previous === null || sortedMarkers.length === 0) return;
+			const announce = (from, to) => {
+				const crossed = require_collectMarkerCrossings.collectMarkerCrossings(sortedMarkers, item.firstFrame, from, to);
+				if (crossed !== null) for (const name of crossed) manager.notify(require_types.LottieSubscription.marker, { marker: name });
+			};
+			const forward = item.playDirection >= 0;
+			if (!(forward ? current < previous : current > previous)) announce(previous, current);
+			else if (forward) {
+				announce(previous, item.totalFrames);
+				announce(-1, current);
+			} else {
+				announce(previous, -1);
+				announce(item.totalFrames, current);
+			}
+		};
+		const onSegmentStart = () => {
+			markerMemory.current = null;
+			refreshRange(item);
+		};
+		const listeners = [
+			["DOMLoaded", onDomLoaded],
+			["data_failed", onDataFailed],
+			["complete", onComplete],
+			["loopComplete", onLoopComplete],
+			["enterFrame", onEnterFrame],
+			["segmentStart", onSegmentStart]
+		];
+		for (const [name, handler] of listeners) item.addEventListener(name, handler);
+		return () => {
+			for (const [name, handler] of listeners) item.removeEventListener(name, handler);
+			item.destroy();
+			itemRef.current = null;
+			setAnimationItem(null);
+			logger.log("the animation was destroyed");
+		};
+	}, [
+		display,
+		source,
+		loadConfig,
+		lottie,
+		manager,
+		refreshRange,
+		loadAttempt
+	]);
+	(0, react.useEffect)(() => {
+		if (speed !== void 0) applySpeed(speed, "prop");
+	}, [speed, applySpeed]);
+	(0, react.useEffect)(() => {
+		if (direction !== void 0) applyDirection(direction, "prop");
+	}, [direction, applyDirection]);
+	(0, react.useEffect)(() => {
+		if (loop !== void 0) applyLoop(loop, "prop");
+	}, [loop, applyLoop]);
+	const instance = {
+		state,
+		error,
+		reload,
+		speed: speedValue,
+		direction: directionValue,
+		loop: loopValue,
+		playableFrames,
+		playableDuration,
+		play,
+		pause,
+		stop,
+		seek,
+		scrubStart,
+		scrubTo,
+		scrubEnd,
+		playSegments,
+		resetSegments,
+		setSpeed,
+		setDirection,
+		setLoop,
+		subscribe: manager.subscribe,
+		setDisplayRef,
+		setRootRef,
+		root,
+		animationItem
+	};
+	const registry = (0, react.useContext)(require_LottieRegistryContext.LottieRegistryContext);
+	const box = (0, react.useRef)({ current: instance }).current;
+	box.current = instance;
+	(0, react.useEffect)(() => registry?.register(box), [registry, box]);
+	(0, react.useEffect)(() => {
+		registry?.bump();
+	});
+	return instance;
+}
+//#endregion
+exports.useLottieAnimation = useLottieAnimation;

package/build/animation/useLottieAnimation.d.cts

@@ -0,0 +1,40 @@
+import { LottieDirection, LottieRenderer, LottieSubscriptions, RendererRows } from "./types.cjs";
+import "lottie-web";
+//#region src/animation/useLottieAnimation.d.ts
+/** The options both public hooks take. */
+interface UseLottieOptions<Renderer extends LottieRenderer = typeof LottieRenderer.svg> {
+  /**
+   * Where the animation comes from: a path or URL to fetch, or the parsed
+   * animation itself.
+   *
+   * Changing it loads a new animation, which is compared by content, so an
+   * object written inline at the call site is safe.
+   */
+  src: string | object;
+  /** Which renderer draws it. Load-time; changing it reloads. */
+  renderer?: Renderer;
+  /** Settings for the chosen renderer. Load-time; changing it reloads. */
+  rendererSettings?: RendererRows[Renderer]["settings"];
+  /**
+   * `false` for none, `true` for forever, or a number of repeats. Reactive,
+   * and a change counts from itself: a new number means that many repeats
+   * from now.
+   */
+  loop?: boolean | number;
+  /** Playback rate, where `1` is the animation's own speed. Reactive. */
+  speed?: number;
+  /** Which way it plays. Reactive. */
+  direction?: LottieDirection;
+  /** Whether it starts on its own. Load-time. */
+  autoplay?: boolean;
+  /** The frame range to play, as `[first, last]`. Load-time. */
+  segment?: readonly [number, number];
+  /** Where the animation's images live, if they are not beside it. Load-time. */
+  assetsPath?: string;
+  /** Traces the load lifecycle to the console. Off by default. */
+  debug?: boolean;
+  /** Handlers called as the animation reports things. */
+  subscriptions?: Partial<LottieSubscriptions>;
+}
+//#endregion
+export { UseLottieOptions };

package/build/animation/useLottieAnimation.d.ts

@@ -0,0 +1,40 @@
+import { LottieDirection, LottieRenderer, LottieSubscriptions, RendererRows } from "./types.js";
+import "lottie-web";
+//#region src/animation/useLottieAnimation.d.ts
+/** The options both public hooks take. */
+interface UseLottieOptions<Renderer extends LottieRenderer = typeof LottieRenderer.svg> {
+  /**
+   * Where the animation comes from: a path or URL to fetch, or the parsed
+   * animation itself.
+   *
+   * Changing it loads a new animation, which is compared by content, so an
+   * object written inline at the call site is safe.
+   */
+  src: string | object;
+  /** Which renderer draws it. Load-time; changing it reloads. */
+  renderer?: Renderer;
+  /** Settings for the chosen renderer. Load-time; changing it reloads. */
+  rendererSettings?: RendererRows[Renderer]["settings"];
+  /**
+   * `false` for none, `true` for forever, or a number of repeats. Reactive,
+   * and a change counts from itself: a new number means that many repeats
+   * from now.
+   */
+  loop?: boolean | number;
+  /** Playback rate, where `1` is the animation's own speed. Reactive. */
+  speed?: number;
+  /** Which way it plays. Reactive. */
+  direction?: LottieDirection;
+  /** Whether it starts on its own. Load-time. */
+  autoplay?: boolean;
+  /** The frame range to play, as `[first, last]`. Load-time. */
+  segment?: readonly [number, number];
+  /** Where the animation's images live, if they are not beside it. Load-time. */
+  assetsPath?: string;
+  /** Traces the load lifecycle to the console. Off by default. */
+  debug?: boolean;
+  /** Handlers called as the animation reports things. */
+  subscriptions?: Partial<LottieSubscriptions>;
+}
+//#endregion
+export { UseLottieOptions };