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

package/build/interactions/LottieInteractions.cjs

@@ -0,0 +1,41 @@
+const require_LottieInstanceContext = require("../animation/LottieInstanceContext.cjs");
+const require_LottieRegistryContext = require("../animation/LottieRegistryContext.cjs");
+const require_useInteractionsRunner = require("./useInteractionsRunner.cjs");
+let react = require("react");
+let react_jsx_runtime = require("react/jsx-runtime");
+//#region src/interactions/LottieInteractions.tsx
+/**
+* Attaches behaviours to animations, from any of three positions.
+*
+* Around a `<Lottie>` it drives every animation inside it, however deep and
+* however many, with no display of its own to place. Inside a `<Lottie>` it
+* drives that animation. Handed a `lottie` from the hook path it drives
+* exactly that one, like every other component here.
+*
+* ```jsx
+* <LottieInteractions interactions={[lottieInView({ once: true })]}>
+*   <Lottie src={anim} autoplay={false} />
+* </LottieInteractions>
+* ```
+*
+* The resolution is the nearest claim wins: the `lottie` prop, else the
+* animation whose `<Lottie>` this sits inside, else whatever renders below.
+* When one of the first two wins, the children pass through untouched, so an
+* animation below still reaches a wrapper further out. Wrapping nothing is
+* not an error, because the animations inside may mount later; it simply
+* does nothing yet.
+*/
+function LottieInteractions({ lottie, interactions, children }) {
+	const surrounding = (0, react.useContext)(require_LottieInstanceContext.LottieInstanceContext);
+	const explicit = lottie ?? surrounding;
+	const [store] = (0, react.useState)(require_LottieRegistryContext.createLottieRegistry);
+	const single = require_useInteractionsRunner.useSingleInstanceSource(explicit);
+	require_useInteractionsRunner.useInteractionsRunner(explicit !== null ? single : store, interactions);
+	if (explicit !== null) return children ?? null;
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_LottieRegistryContext.LottieRegistryContext.Provider, {
+		value: store,
+		children
+	});
+}
+//#endregion
+exports.LottieInteractions = LottieInteractions;

package/build/interactions/LottieInteractions.d.cts

@@ -0,0 +1,37 @@
+import { LottieInstance } from "../animation/types.cjs";
+import { LottieInteraction } from "./types.cjs";
+import { ReactNode } from "react";
+//#region src/interactions/LottieInteractions.d.ts
+/** What {@link LottieInteractions} owns. It renders no element of its own. */
+interface LottieInteractionsProps {
+  /** The animation to drive. Omit it around or inside `<Lottie>`. */
+  lottie?: LottieInstance;
+  /** The behaviours, each made by a factory such as `lottieInView(...)`. */
+  interactions: readonly LottieInteraction[];
+  /** Anything at all, rendered untouched. */
+  children?: ReactNode;
+}
+/**
+ * Attaches behaviours to animations, from any of three positions.
+ *
+ * Around a `<Lottie>` it drives every animation inside it, however deep and
+ * however many, with no display of its own to place. Inside a `<Lottie>` it
+ * drives that animation. Handed a `lottie` from the hook path it drives
+ * exactly that one, like every other component here.
+ *
+ * ```jsx
+ * <LottieInteractions interactions={[lottieInView({ once: true })]}>
+ *   <Lottie src={anim} autoplay={false} />
+ * </LottieInteractions>
+ * ```
+ *
+ * The resolution is the nearest claim wins: the `lottie` prop, else the
+ * animation whose `<Lottie>` this sits inside, else whatever renders below.
+ * When one of the first two wins, the children pass through untouched, so an
+ * animation below still reaches a wrapper further out. Wrapping nothing is
+ * not an error, because the animations inside may mount later; it simply
+ * does nothing yet.
+ */
+declare function LottieInteractions({ lottie, interactions, children }: LottieInteractionsProps): ReactNode;
+//#endregion
+export { LottieInteractions, LottieInteractionsProps };

package/build/interactions/LottieInteractions.d.ts

@@ -0,0 +1,37 @@
+import { LottieInstance } from "../animation/types.js";
+import { LottieInteraction } from "./types.js";
+import { ReactNode } from "react";
+//#region src/interactions/LottieInteractions.d.ts
+/** What {@link LottieInteractions} owns. It renders no element of its own. */
+interface LottieInteractionsProps {
+  /** The animation to drive. Omit it around or inside `<Lottie>`. */
+  lottie?: LottieInstance;
+  /** The behaviours, each made by a factory such as `lottieInView(...)`. */
+  interactions: readonly LottieInteraction[];
+  /** Anything at all, rendered untouched. */
+  children?: ReactNode;
+}
+/**
+ * Attaches behaviours to animations, from any of three positions.
+ *
+ * Around a `<Lottie>` it drives every animation inside it, however deep and
+ * however many, with no display of its own to place. Inside a `<Lottie>` it
+ * drives that animation. Handed a `lottie` from the hook path it drives
+ * exactly that one, like every other component here.
+ *
+ * ```jsx
+ * <LottieInteractions interactions={[lottieInView({ once: true })]}>
+ *   <Lottie src={anim} autoplay={false} />
+ * </LottieInteractions>
+ * ```
+ *
+ * The resolution is the nearest claim wins: the `lottie` prop, else the
+ * animation whose `<Lottie>` this sits inside, else whatever renders below.
+ * When one of the first two wins, the children pass through untouched, so an
+ * animation below still reaches a wrapper further out. Wrapping nothing is
+ * not an error, because the animations inside may mount later; it simply
+ * does nothing yet.
+ */
+declare function LottieInteractions({ lottie, interactions, children }: LottieInteractionsProps): ReactNode;
+//#endregion
+export { LottieInteractions, LottieInteractionsProps };

package/build/interactions/LottieInteractions.js

@@ -0,0 +1,41 @@
+import { LottieInstanceContext } from "../animation/LottieInstanceContext.js";
+import { LottieRegistryContext, createLottieRegistry } from "../animation/LottieRegistryContext.js";
+import { useInteractionsRunner, useSingleInstanceSource } from "./useInteractionsRunner.js";
+import { useContext, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/interactions/LottieInteractions.tsx
+/**
+* Attaches behaviours to animations, from any of three positions.
+*
+* Around a `<Lottie>` it drives every animation inside it, however deep and
+* however many, with no display of its own to place. Inside a `<Lottie>` it
+* drives that animation. Handed a `lottie` from the hook path it drives
+* exactly that one, like every other component here.
+*
+* ```jsx
+* <LottieInteractions interactions={[lottieInView({ once: true })]}>
+*   <Lottie src={anim} autoplay={false} />
+* </LottieInteractions>
+* ```
+*
+* The resolution is the nearest claim wins: the `lottie` prop, else the
+* animation whose `<Lottie>` this sits inside, else whatever renders below.
+* When one of the first two wins, the children pass through untouched, so an
+* animation below still reaches a wrapper further out. Wrapping nothing is
+* not an error, because the animations inside may mount later; it simply
+* does nothing yet.
+*/
+function LottieInteractions({ lottie, interactions, children }) {
+	const surrounding = useContext(LottieInstanceContext);
+	const explicit = lottie ?? surrounding;
+	const [store] = useState(createLottieRegistry);
+	const single = useSingleInstanceSource(explicit);
+	useInteractionsRunner(explicit !== null ? single : store, interactions);
+	if (explicit !== null) return children ?? null;
+	return /* @__PURE__ */ jsx(LottieRegistryContext.Provider, {
+		value: store,
+		children
+	});
+}
+//#endregion
+export { LottieInteractions };

package/build/interactions/coverProgress.cjs

@@ -0,0 +1,55 @@
+//#region src/interactions/coverProgress.ts
+/**
+* Where an element's journey across a viewport stands: 0 as its leading edge
+* reaches the viewport's far end, 1 as its trailing edge leaves the near end.
+*
+* This is the platform's `cover` range written out, which is what makes the
+* fallback and a real `ViewTimeline` agree wherever both can run. It reads
+* a rectangle rather than the live layout, so the caller decides where the
+* rectangle comes from and the arithmetic stays measurable.
+*/
+function coverProgress(rect, viewport, axis) {
+	const size = axis === "inline" ? viewport.width : viewport.height;
+	const leading = axis === "inline" ? rect.left : rect.top;
+	const span = size + (axis === "inline" ? rect.width : rect.height);
+	if (span === 0) return 0;
+	return Math.min(Math.max((size - leading) / span, 0), 1);
+}
+/**
+* The journey progress mapped into a band of it, clamped at the band's ends.
+*
+* Holding still below the band and holding still above it are what replace
+* v2's `stop` bands: they are not features, they are what clamping does.
+*/
+function bandProgress(progress, range) {
+	const [start, end] = range;
+	if (end === start) return progress < start ? 0 : 1;
+	return Math.min(Math.max((progress - start) / (end - start), 0), 1);
+}
+/**
+* Compares two banded samples and names the edges crossed between them.
+*
+* Inside means strictly between the clamps; a sample pinned at 0 or 1 is
+* outside, which is what makes leaving fire exactly when the scrub reaches
+* an end. The first sample of a gesture has no predecessor, and starting
+* already inside counts as entering forward. A single sample that crosses
+* the whole band reports both edges in its direction of travel.
+*/
+function bandEdges(previous, current) {
+	const isInside = current > 0 && current < 1;
+	if (previous === null) return isInside ? { enter: "forward" } : {};
+	const wasInside = previous > 0 && previous < 1;
+	const direction = current >= previous ? "forward" : "backward";
+	const events = {};
+	if (!wasInside && isInside) events.enter = direction;
+	if (wasInside && !isInside) events.leave = direction;
+	if (!wasInside && !isInside && previous !== current && previous <= 0 !== current <= 0) {
+		events.enter = direction;
+		events.leave = direction;
+	}
+	return events;
+}
+//#endregion
+exports.bandEdges = bandEdges;
+exports.bandProgress = bandProgress;
+exports.coverProgress = coverProgress;

package/build/interactions/coverProgress.js

@@ -0,0 +1,53 @@
+//#region src/interactions/coverProgress.ts
+/**
+* Where an element's journey across a viewport stands: 0 as its leading edge
+* reaches the viewport's far end, 1 as its trailing edge leaves the near end.
+*
+* This is the platform's `cover` range written out, which is what makes the
+* fallback and a real `ViewTimeline` agree wherever both can run. It reads
+* a rectangle rather than the live layout, so the caller decides where the
+* rectangle comes from and the arithmetic stays measurable.
+*/
+function coverProgress(rect, viewport, axis) {
+	const size = axis === "inline" ? viewport.width : viewport.height;
+	const leading = axis === "inline" ? rect.left : rect.top;
+	const span = size + (axis === "inline" ? rect.width : rect.height);
+	if (span === 0) return 0;
+	return Math.min(Math.max((size - leading) / span, 0), 1);
+}
+/**
+* The journey progress mapped into a band of it, clamped at the band's ends.
+*
+* Holding still below the band and holding still above it are what replace
+* v2's `stop` bands: they are not features, they are what clamping does.
+*/
+function bandProgress(progress, range) {
+	const [start, end] = range;
+	if (end === start) return progress < start ? 0 : 1;
+	return Math.min(Math.max((progress - start) / (end - start), 0), 1);
+}
+/**
+* Compares two banded samples and names the edges crossed between them.
+*
+* Inside means strictly between the clamps; a sample pinned at 0 or 1 is
+* outside, which is what makes leaving fire exactly when the scrub reaches
+* an end. The first sample of a gesture has no predecessor, and starting
+* already inside counts as entering forward. A single sample that crosses
+* the whole band reports both edges in its direction of travel.
+*/
+function bandEdges(previous, current) {
+	const isInside = current > 0 && current < 1;
+	if (previous === null) return isInside ? { enter: "forward" } : {};
+	const wasInside = previous > 0 && previous < 1;
+	const direction = current >= previous ? "forward" : "backward";
+	const events = {};
+	if (!wasInside && isInside) events.enter = direction;
+	if (wasInside && !isInside) events.leave = direction;
+	if (!wasInside && !isInside && previous !== current && previous <= 0 !== current <= 0) {
+		events.enter = direction;
+		events.leave = direction;
+	}
+	return events;
+}
+//#endregion
+export { bandEdges, bandProgress, coverProgress };

package/build/interactions/lottieInView.cjs

@@ -0,0 +1,109 @@
+const require_types = require("../animation/types.cjs");
+//#region src/interactions/lottieInView.ts
+function isInViewOptions(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if ("once" in value && typeof value.once !== "boolean") return false;
+	if ("amount" in value && typeof value.amount !== "number") return false;
+	return !("margin" in value && typeof value.margin !== "string");
+}
+/** Whether a play command would fight something that outranks it. */
+function playable(state) {
+	return state !== require_types.LottieState.loading && state !== require_types.LottieState.error && state !== require_types.LottieState.frozen;
+}
+function attachInView(context, raw) {
+	const options = isInViewOptions(raw) ? raw : {};
+	let observer = null;
+	let observedRoot = null;
+	let playedByUs = false;
+	let previousState = context.lottie.state;
+	let lastIntersecting = null;
+	const warnRedundant = () => {
+		if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
+			if (context.memory.warnedRedundant !== true && !playedByUs && context.lottie.state === require_types.LottieState.playing) {
+				context.memory.warnedRedundant = true;
+				console.warn("[lottie-react] an in-view trigger is watching an animation that already plays by itself. With autoplay on, the trigger has nothing left to start; drop one of the two.");
+			}
+		}
+	};
+	const playFromEntry = () => {
+		if (options.once === true) {
+			context.memory.entered = true;
+			observer?.disconnect();
+			observer = null;
+		}
+		playedByUs = true;
+		context.lottie.play();
+	};
+	const handleEntries = (entries) => {
+		const entry = entries.at(-1);
+		if (entry === void 0) return;
+		lastIntersecting = entry.isIntersecting;
+		const lottie = context.lottie;
+		if (entry.isIntersecting) {
+			if (options.once === true && context.memory.entered === true) return;
+			if (playable(lottie.state)) playFromEntry();
+		} else if (options.once !== true && lottie.state === require_types.LottieState.playing) lottie.pause();
+	};
+	const arm = () => {
+		const root = context.lottie.root;
+		if (root === observedRoot) return;
+		observer?.disconnect();
+		observer = null;
+		observedRoot = root;
+		if (root === null) return;
+		if (options.once === true && context.memory.entered === true) return;
+		try {
+			observer = new IntersectionObserver(handleEntries, {
+				threshold: options.amount ?? 0,
+				rootMargin: options.margin
+			});
+		} catch {
+			if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") console.warn(`[lottie-react] the margin ${JSON.stringify(options.margin)} was refused, so the trigger watches without it. A margin is written in px or %, the only lengths the platform accepts here.`);
+			observer = new IntersectionObserver(handleEntries, { threshold: options.amount ?? 0 });
+		}
+		observer.observe(root);
+	};
+	const stopListening = context.onChange(() => {
+		const state = context.lottie.state;
+		if (previousState === require_types.LottieState.loading && state === require_types.LottieState.playing) warnRedundant();
+		if (previousState === require_types.LottieState.loading && lastIntersecting === true && playable(state) && state !== require_types.LottieState.playing && !(options.once === true && context.memory.entered === true)) playFromEntry();
+		previousState = state;
+		arm();
+	});
+	warnRedundant();
+	arm();
+	return () => {
+		stopListening();
+		observer?.disconnect();
+	};
+}
+/**
+* Plays the animation when it scrolls into view and pauses it when it leaves,
+* or with `once`, plays on the first entry and never again.
+*
+* ```jsx
+* <LottieInteractions interactions={[lottieInView({ once: true })]}>
+*   <Lottie src={anim} autoplay={false} />
+* </LottieInteractions>
+* ```
+*
+* An entry seen while the animation is still loading plays as soon as the
+* load finishes, so an animation already on screen at page load starts by
+* itself.
+*
+* Leaving pauses rather than stops, so coming back resumes mid-motion instead
+* of restarting. The trigger never overrides a load still in flight or a
+* failed one, and it cannot tell its own pause from one a person asked for,
+* so re-entering resumes either.
+*/
+function lottieInView(options = {}) {
+	if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
+		if (options.amount === 1) console.warn("[lottie-react] amount: 1 never fires for an animation taller than the viewport, because such an element is never entirely visible. Use a smaller amount, or a negative margin for a centre band.");
+	}
+	return {
+		attach: attachInView,
+		options
+	};
+}
+//#endregion
+exports.lottieInView = lottieInView;

package/build/interactions/lottieInView.d.cts

@@ -0,0 +1,44 @@
+import { LottieInteraction } from "./types.cjs";
+//#region src/interactions/lottieInView.d.ts
+/** What {@link lottieInView} can be told. */
+interface LottieInViewOptions {
+  /**
+   * Play on the first entry and then stop watching for good, so scrolling
+   * past again replays nothing. Off unless asked for.
+   */
+  once?: boolean;
+  /**
+   * How much of the animation must be visible to count as entered, `0` to
+   * `1`. The default is `0`: a single visible pixel. `1` is accepted and
+   * warned about, because an element taller than the viewport can never be
+   * entirely visible, so a threshold of one silently never fires for it.
+   */
+  amount?: number;
+  /**
+   * Grows or shrinks the viewport the entry is measured against, in the
+   * platform's own `rootMargin` grammar: px or % only.
+   */
+  margin?: string;
+}
+/**
+ * Plays the animation when it scrolls into view and pauses it when it leaves,
+ * or with `once`, plays on the first entry and never again.
+ *
+ * ```jsx
+ * <LottieInteractions interactions={[lottieInView({ once: true })]}>
+ *   <Lottie src={anim} autoplay={false} />
+ * </LottieInteractions>
+ * ```
+ *
+ * An entry seen while the animation is still loading plays as soon as the
+ * load finishes, so an animation already on screen at page load starts by
+ * itself.
+ *
+ * Leaving pauses rather than stops, so coming back resumes mid-motion instead
+ * of restarting. The trigger never overrides a load still in flight or a
+ * failed one, and it cannot tell its own pause from one a person asked for,
+ * so re-entering resumes either.
+ */
+declare function lottieInView(options?: LottieInViewOptions): LottieInteraction;
+//#endregion
+export { LottieInViewOptions, lottieInView };

package/build/interactions/lottieInView.d.ts

@@ -0,0 +1,44 @@
+import { LottieInteraction } from "./types.js";
+//#region src/interactions/lottieInView.d.ts
+/** What {@link lottieInView} can be told. */
+interface LottieInViewOptions {
+  /**
+   * Play on the first entry and then stop watching for good, so scrolling
+   * past again replays nothing. Off unless asked for.
+   */
+  once?: boolean;
+  /**
+   * How much of the animation must be visible to count as entered, `0` to
+   * `1`. The default is `0`: a single visible pixel. `1` is accepted and
+   * warned about, because an element taller than the viewport can never be
+   * entirely visible, so a threshold of one silently never fires for it.
+   */
+  amount?: number;
+  /**
+   * Grows or shrinks the viewport the entry is measured against, in the
+   * platform's own `rootMargin` grammar: px or % only.
+   */
+  margin?: string;
+}
+/**
+ * Plays the animation when it scrolls into view and pauses it when it leaves,
+ * or with `once`, plays on the first entry and never again.
+ *
+ * ```jsx
+ * <LottieInteractions interactions={[lottieInView({ once: true })]}>
+ *   <Lottie src={anim} autoplay={false} />
+ * </LottieInteractions>
+ * ```
+ *
+ * An entry seen while the animation is still loading plays as soon as the
+ * load finishes, so an animation already on screen at page load starts by
+ * itself.
+ *
+ * Leaving pauses rather than stops, so coming back resumes mid-motion instead
+ * of restarting. The trigger never overrides a load still in flight or a
+ * failed one, and it cannot tell its own pause from one a person asked for,
+ * so re-entering resumes either.
+ */
+declare function lottieInView(options?: LottieInViewOptions): LottieInteraction;
+//#endregion
+export { LottieInViewOptions, lottieInView };

package/build/interactions/lottieInView.js

@@ -0,0 +1,109 @@
+import { LottieState } from "../animation/types.js";
+//#region src/interactions/lottieInView.ts
+function isInViewOptions(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if ("once" in value && typeof value.once !== "boolean") return false;
+	if ("amount" in value && typeof value.amount !== "number") return false;
+	return !("margin" in value && typeof value.margin !== "string");
+}
+/** Whether a play command would fight something that outranks it. */
+function playable(state) {
+	return state !== LottieState.loading && state !== LottieState.error && state !== LottieState.frozen;
+}
+function attachInView(context, raw) {
+	const options = isInViewOptions(raw) ? raw : {};
+	let observer = null;
+	let observedRoot = null;
+	let playedByUs = false;
+	let previousState = context.lottie.state;
+	let lastIntersecting = null;
+	const warnRedundant = () => {
+		if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
+			if (context.memory.warnedRedundant !== true && !playedByUs && context.lottie.state === LottieState.playing) {
+				context.memory.warnedRedundant = true;
+				console.warn("[lottie-react] an in-view trigger is watching an animation that already plays by itself. With autoplay on, the trigger has nothing left to start; drop one of the two.");
+			}
+		}
+	};
+	const playFromEntry = () => {
+		if (options.once === true) {
+			context.memory.entered = true;
+			observer?.disconnect();
+			observer = null;
+		}
+		playedByUs = true;
+		context.lottie.play();
+	};
+	const handleEntries = (entries) => {
+		const entry = entries.at(-1);
+		if (entry === void 0) return;
+		lastIntersecting = entry.isIntersecting;
+		const lottie = context.lottie;
+		if (entry.isIntersecting) {
+			if (options.once === true && context.memory.entered === true) return;
+			if (playable(lottie.state)) playFromEntry();
+		} else if (options.once !== true && lottie.state === LottieState.playing) lottie.pause();
+	};
+	const arm = () => {
+		const root = context.lottie.root;
+		if (root === observedRoot) return;
+		observer?.disconnect();
+		observer = null;
+		observedRoot = root;
+		if (root === null) return;
+		if (options.once === true && context.memory.entered === true) return;
+		try {
+			observer = new IntersectionObserver(handleEntries, {
+				threshold: options.amount ?? 0,
+				rootMargin: options.margin
+			});
+		} catch {
+			if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") console.warn(`[lottie-react] the margin ${JSON.stringify(options.margin)} was refused, so the trigger watches without it. A margin is written in px or %, the only lengths the platform accepts here.`);
+			observer = new IntersectionObserver(handleEntries, { threshold: options.amount ?? 0 });
+		}
+		observer.observe(root);
+	};
+	const stopListening = context.onChange(() => {
+		const state = context.lottie.state;
+		if (previousState === LottieState.loading && state === LottieState.playing) warnRedundant();
+		if (previousState === LottieState.loading && lastIntersecting === true && playable(state) && state !== LottieState.playing && !(options.once === true && context.memory.entered === true)) playFromEntry();
+		previousState = state;
+		arm();
+	});
+	warnRedundant();
+	arm();
+	return () => {
+		stopListening();
+		observer?.disconnect();
+	};
+}
+/**
+* Plays the animation when it scrolls into view and pauses it when it leaves,
+* or with `once`, plays on the first entry and never again.
+*
+* ```jsx
+* <LottieInteractions interactions={[lottieInView({ once: true })]}>
+*   <Lottie src={anim} autoplay={false} />
+* </LottieInteractions>
+* ```
+*
+* An entry seen while the animation is still loading plays as soon as the
+* load finishes, so an animation already on screen at page load starts by
+* itself.
+*
+* Leaving pauses rather than stops, so coming back resumes mid-motion instead
+* of restarting. The trigger never overrides a load still in flight or a
+* failed one, and it cannot tell its own pause from one a person asked for,
+* so re-entering resumes either.
+*/
+function lottieInView(options = {}) {
+	if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
+		if (options.amount === 1) console.warn("[lottie-react] amount: 1 never fires for an animation taller than the viewport, because such an element is never entirely visible. Use a smaller amount, or a negative margin for a centre band.");
+	}
+	return {
+		attach: attachInView,
+		options
+	};
+}
+//#endregion
+export { lottieInView };