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

package/build/interactions/useInteractionsRunner.js

@@ -0,0 +1,141 @@
+import { isSameJson } from "../utils/isSameJson.js";
+import { useStableValue } from "../utils/useStableValue.js";
+import { createLottieRegistry } from "../animation/LottieRegistryContext.js";
+import { useEffect, useRef, useState } from "react";
+//#region src/interactions/useInteractionsRunner.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* The options with every function replaced by a marker, so the whole slot can
+* be compared by content. A callback's identity changes on every render at an
+* inline call site, which must not read as a configuration change; a callback
+* appearing or disappearing must.
+*/
+function projectData(value) {
+	if (typeof value === "function") return "[function]";
+	if (Array.isArray(value)) return value.map(projectData);
+	if (isRecord(value)) {
+		const projected = {};
+		for (const [key, entry] of Object.entries(value)) projected[key] = projectData(entry);
+		return projected;
+	}
+	return value;
+}
+/**
+* Arms every interaction on every animation a source holds, and keeps that
+* true as animations come and go, options change, and values move.
+*
+* The granularity is deliberate: an animation arriving arms only itself, a
+* changed option re-arms only its own slot on each animation, and a moved
+* value re-arms nothing and only signals `onChange`. A re-arm caused by an
+* option change hands the new attachment the old one's `memory` when the
+* implementation is the same one, which is what lets a once-latch survive
+* reconfiguration.
+*/
+function useInteractionsRunner(source, interactions) {
+	const latest = useRef(interactions);
+	latest.current = interactions;
+	const projected = useStableValue(interactions.map((interaction) => ({
+		attach: interaction.attach,
+		options: projectData(interaction.options)
+	})));
+	const runtime = useRef(/* @__PURE__ */ new Map()).current;
+	const armSlot = (box, slot, memory) => {
+		const interaction = latest.current[slot];
+		const record = {
+			key: projected[slot],
+			attachIdentity: interaction.attach,
+			cleanup: void 0,
+			listeners: /* @__PURE__ */ new Set(),
+			memory: memory ?? {}
+		};
+		const context = {
+			get lottie() {
+				return box.current;
+			},
+			options: () => latest.current[slot]?.options,
+			onChange: (listener) => {
+				record.listeners.add(listener);
+				return () => {
+					record.listeners.delete(listener);
+				};
+			},
+			memory: record.memory
+		};
+		record.cleanup = interaction.attach(context, interaction.options);
+		return record;
+	};
+	const armRef = useRef(armSlot);
+	armRef.current = armSlot;
+	useEffect(() => {
+		const attachBox = (box) => {
+			runtime.set(box, projected.map((_, slot) => armRef.current(box, slot)));
+		};
+		const syncSlots = () => {
+			for (const [box, attachments] of runtime) {
+				for (let slot = 0; slot < projected.length; slot += 1) {
+					const existing = attachments[slot];
+					if (existing !== void 0 && isSameJson(existing.key, projected[slot])) continue;
+					const inherited = existing !== void 0 && existing.attachIdentity === latest.current[slot]?.attach ? existing.memory : void 0;
+					existing?.cleanup?.();
+					attachments[slot] = armRef.current(box, slot, inherited);
+				}
+				for (const removed of attachments.splice(projected.length)) removed.cleanup?.();
+			}
+		};
+		const syncBoxes = () => {
+			const current = new Set(source.boxes());
+			for (const box of current) if (!runtime.has(box)) attachBox(box);
+			for (const [box, attachments] of [...runtime]) if (!current.has(box)) {
+				for (const attachment of attachments) attachment.cleanup?.();
+				runtime.delete(box);
+			}
+		};
+		const notifyChange = () => {
+			for (const attachments of runtime.values()) for (const attachment of attachments) for (const listener of [...attachment.listeners]) listener();
+		};
+		syncSlots();
+		syncBoxes();
+		return source.subscribe(() => {
+			syncBoxes();
+			notifyChange();
+		});
+	}, [
+		source,
+		projected,
+		runtime
+	]);
+	useEffect(() => {
+		return () => {
+			for (const attachments of runtime.values()) for (const attachment of attachments) attachment.cleanup?.();
+			runtime.clear();
+		};
+	}, [runtime]);
+}
+/**
+* A source holding exactly one animation, for the positions where the
+* component or the hook was handed an instance rather than wrapping a subtree.
+* Mirrors the registration the animation itself performs toward a surrounding
+* wrapper, so the runner cannot tell the two apart.
+*/
+function useSingleInstanceSource(instance) {
+	const [store] = useState(createLottieRegistry);
+	const box = useRef(null);
+	if (instance !== null) {
+		if (box.current === null) box.current = { current: instance };
+		else box.current.current = instance;
+	}
+	const present = instance !== null;
+	useEffect(() => {
+		const current = box.current;
+		if (!present || current === null) return;
+		return store.register(current);
+	}, [store, present]);
+	useEffect(() => {
+		if (present) store.bump();
+	});
+	return store;
+}
+//#endregion
+export { useInteractionsRunner, useSingleInstanceSource };

package/build/interactions/useLottieInteractions.cjs

@@ -0,0 +1,21 @@
+const require_useInteractionsRunner = require("./useInteractionsRunner.cjs");
+//#region src/interactions/useLottieInteractions.ts
+/**
+* Attaches behaviours to one animation on the hook path.
+*
+* ```jsx
+* const lottie = useLottie({ src, autoplay: false });
+* useLottieInteractions(lottie, [lottieScrollScrub({ range: [0.2, 0.45] })]);
+* ```
+*
+* The list is safe to write inline: implementations compare by identity and
+* options by content, so a fresh array every render re-arms nothing, and a
+* changed option re-arms only its own behaviour. The same runner serves
+* `<LottieInteractions>`, so the two paths cannot drift.
+*/
+function useLottieInteractions(lottie, interactions) {
+	const single = require_useInteractionsRunner.useSingleInstanceSource(lottie);
+	require_useInteractionsRunner.useInteractionsRunner(single, interactions);
+}
+//#endregion
+exports.useLottieInteractions = useLottieInteractions;

package/build/interactions/useLottieInteractions.d.cts

@@ -0,0 +1,19 @@
+import { LottieInstance } from "../animation/types.cjs";
+import { LottieInteraction } from "./types.cjs";
+//#region src/interactions/useLottieInteractions.d.ts
+/**
+ * Attaches behaviours to one animation on the hook path.
+ *
+ * ```jsx
+ * const lottie = useLottie({ src, autoplay: false });
+ * useLottieInteractions(lottie, [lottieScrollScrub({ range: [0.2, 0.45] })]);
+ * ```
+ *
+ * The list is safe to write inline: implementations compare by identity and
+ * options by content, so a fresh array every render re-arms nothing, and a
+ * changed option re-arms only its own behaviour. The same runner serves
+ * `<LottieInteractions>`, so the two paths cannot drift.
+ */
+declare function useLottieInteractions(lottie: LottieInstance, interactions: readonly LottieInteraction[]): void;
+//#endregion
+export { useLottieInteractions };

package/build/interactions/useLottieInteractions.d.ts

@@ -0,0 +1,19 @@
+import { LottieInstance } from "../animation/types.js";
+import { LottieInteraction } from "./types.js";
+//#region src/interactions/useLottieInteractions.d.ts
+/**
+ * Attaches behaviours to one animation on the hook path.
+ *
+ * ```jsx
+ * const lottie = useLottie({ src, autoplay: false });
+ * useLottieInteractions(lottie, [lottieScrollScrub({ range: [0.2, 0.45] })]);
+ * ```
+ *
+ * The list is safe to write inline: implementations compare by identity and
+ * options by content, so a fresh array every render re-arms nothing, and a
+ * changed option re-arms only its own behaviour. The same runner serves
+ * `<LottieInteractions>`, so the two paths cannot drift.
+ */
+declare function useLottieInteractions(lottie: LottieInstance, interactions: readonly LottieInteraction[]): void;
+//#endregion
+export { useLottieInteractions };

package/build/interactions/useLottieInteractions.js

@@ -0,0 +1,21 @@
+import { useInteractionsRunner, useSingleInstanceSource } from "./useInteractionsRunner.js";
+//#region src/interactions/useLottieInteractions.ts
+/**
+* Attaches behaviours to one animation on the hook path.
+*
+* ```jsx
+* const lottie = useLottie({ src, autoplay: false });
+* useLottieInteractions(lottie, [lottieScrollScrub({ range: [0.2, 0.45] })]);
+* ```
+*
+* The list is safe to write inline: implementations compare by identity and
+* options by content, so a fresh array every render re-arms nothing, and a
+* changed option re-arms only its own behaviour. The same runner serves
+* `<LottieInteractions>`, so the two paths cannot drift.
+*/
+function useLottieInteractions(lottie, interactions) {
+	const single = useSingleInstanceSource(lottie);
+	useInteractionsRunner(single, interactions);
+}
+//#endregion
+export { useLottieInteractions };

package/build/overlays/LottieError.cjs

@@ -0,0 +1,74 @@
+const require_renderStyledElement = require("../animation/renderStyledElement.cjs");
+const require_useLottieInstance = require("../animation/useLottieInstance.cjs");
+const require_types = require("../animation/types.cjs");
+const require_overlayStyles = require("./overlayStyles.cjs");
+let react = require("react");
+//#region src/overlays/LottieError.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 lottieErrorClass = "lottie-error";
+/**
+* What it says when nobody has said otherwise.
+*
+* A sentence written for whoever is looking at the page rather than for whoever
+* wrote it: the reason itself is on the animation as `error`, and it describes
+* a path or a payload, which is a developer's problem and not a reader's.
+* Anything else, in any language, is passed as children.
+*/
+const defaultMessage = "The animation could not be loaded.";
+/**
+* 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.
+*
+* There is nothing here beyond the shared positioning. It appears immediately,
+* unlike the loading overlay, which waits: waiting exists so that a load
+* finishing quickly is never announced, and a failure has already finished.
+*/
+const lottieErrorStyles = require_overlayStyles.overlayStyles(lottieErrorClass);
+/**
+* What to show when the animation could not be loaded.
+*
+* 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
+* once a load has failed and renders nothing the rest of the time.
+*
+* ```jsx
+* <Lottie src="/hero.json">
+*   <LottieDisplay />
+*   <LottieError />
+* </Lottie>
+* ```
+*
+* The reason is on the animation as `error`, and `reload()` is what tries
+* again, so a button of your own passed as children can offer both.
+*
+* 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 LottieError = (0, react.forwardRef)(function LottieError({ lottie, className, children, ...rest }, ref) {
+	const { state } = require_useLottieInstance.useLottieInstance(lottie);
+	if (state !== require_types.LottieState.error) return null;
+	return require_renderStyledElement.renderStyledElement({
+		tag: "div",
+		styleClass: lottieErrorClass,
+		styles: lottieErrorStyles,
+		className,
+		attributes: {
+			role: "alert",
+			...rest
+		},
+		ref,
+		children: children ?? defaultMessage
+	});
+});
+//#endregion
+exports.LottieError = LottieError;
+exports.lottieErrorClass = lottieErrorClass;
+exports.lottieErrorStyles = lottieErrorStyles;

package/build/overlays/LottieError.d.cts

@@ -0,0 +1,40 @@
+import { FixedElementProps, LottieInstance } from "../animation/types.cjs";
+import { ReactNode } from "react";
+//#region src/overlays/LottieError.d.ts
+/** What this component owns. Every other prop belongs to the element. */
+interface LottieErrorOwnProps {
+  /** The animation to watch. Omit it inside a component that publishes one. */
+  lottie?: LottieInstance;
+  /** What to show when it fails. A short sentence unless you say otherwise. */
+  children?: ReactNode;
+  /** Added to the library's class rather than replacing it. */
+  className?: string;
+}
+/** What {@link LottieError} accepts. */
+type LottieErrorProps = FixedElementProps<LottieErrorOwnProps, "div">;
+/**
+ * What to show when the animation could not be loaded.
+ *
+ * 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
+ * once a load has failed and renders nothing the rest of the time.
+ *
+ * ```jsx
+ * <Lottie src="/hero.json">
+ *   <LottieDisplay />
+ *   <LottieError />
+ * </Lottie>
+ * ```
+ *
+ * The reason is on the animation as `error`, and `reload()` is what tries
+ * again, so a button of your own passed as children can offer both.
+ *
+ * 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.
+ */
+declare const LottieError: import("react").ForwardRefExoticComponent<LottieErrorOwnProps & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof LottieErrorOwnProps> & import("react").RefAttributes<HTMLDivElement>>;
+//#endregion
+export { LottieError, LottieErrorProps };

package/build/overlays/LottieError.d.ts

@@ -0,0 +1,40 @@
+import { FixedElementProps, LottieInstance } from "../animation/types.js";
+import { ReactNode } from "react";
+//#region src/overlays/LottieError.d.ts
+/** What this component owns. Every other prop belongs to the element. */
+interface LottieErrorOwnProps {
+  /** The animation to watch. Omit it inside a component that publishes one. */
+  lottie?: LottieInstance;
+  /** What to show when it fails. A short sentence unless you say otherwise. */
+  children?: ReactNode;
+  /** Added to the library's class rather than replacing it. */
+  className?: string;
+}
+/** What {@link LottieError} accepts. */
+type LottieErrorProps = FixedElementProps<LottieErrorOwnProps, "div">;
+/**
+ * What to show when the animation could not be loaded.
+ *
+ * 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
+ * once a load has failed and renders nothing the rest of the time.
+ *
+ * ```jsx
+ * <Lottie src="/hero.json">
+ *   <LottieDisplay />
+ *   <LottieError />
+ * </Lottie>
+ * ```
+ *
+ * The reason is on the animation as `error`, and `reload()` is what tries
+ * again, so a button of your own passed as children can offer both.
+ *
+ * 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.
+ */
+declare const LottieError: import("react").ForwardRefExoticComponent<LottieErrorOwnProps & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof LottieErrorOwnProps> & import("react").RefAttributes<HTMLDivElement>>;
+//#endregion
+export { LottieError, LottieErrorProps };

package/build/overlays/LottieError.js

@@ -0,0 +1,72 @@
+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";
+//#region src/overlays/LottieError.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 lottieErrorClass = "lottie-error";
+/**
+* What it says when nobody has said otherwise.
+*
+* A sentence written for whoever is looking at the page rather than for whoever
+* wrote it: the reason itself is on the animation as `error`, and it describes
+* a path or a payload, which is a developer's problem and not a reader's.
+* Anything else, in any language, is passed as children.
+*/
+const defaultMessage = "The animation could not be loaded.";
+/**
+* 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.
+*
+* There is nothing here beyond the shared positioning. It appears immediately,
+* unlike the loading overlay, which waits: waiting exists so that a load
+* finishing quickly is never announced, and a failure has already finished.
+*/
+const lottieErrorStyles = overlayStyles(lottieErrorClass);
+/**
+* What to show when the animation could not be loaded.
+*
+* 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
+* once a load has failed and renders nothing the rest of the time.
+*
+* ```jsx
+* <Lottie src="/hero.json">
+*   <LottieDisplay />
+*   <LottieError />
+* </Lottie>
+* ```
+*
+* The reason is on the animation as `error`, and `reload()` is what tries
+* again, so a button of your own passed as children can offer both.
+*
+* 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 LottieError = forwardRef(function LottieError({ lottie, className, children, ...rest }, ref) {
+	const { state } = useLottieInstance(lottie);
+	if (state !== LottieState.error) return null;
+	return renderStyledElement({
+		tag: "div",
+		styleClass: lottieErrorClass,
+		styles: lottieErrorStyles,
+		className,
+		attributes: {
+			role: "alert",
+			...rest
+		},
+		ref,
+		children: children ?? defaultMessage
+	});
+});
+//#endregion
+export { LottieError, lottieErrorClass, lottieErrorStyles };

package/build/overlays/LottieLoading.cjs

@@ -0,0 +1,89 @@
+const require_renderStyledElement = require("../animation/renderStyledElement.cjs");
+const require_useLottieInstance = require("../animation/useLottieInstance.cjs");
+const require_types = require("../animation/types.cjs");
+const require_overlayStyles = require("./overlayStyles.cjs");
+let react = require("react");
+let react_jsx_runtime = require("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 = `${require_overlayStyles.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 = (0, react.forwardRef)(function LottieLoading({ lottie, className, children, showAfter, style, ...rest }, ref) {
+	const { state } = require_useLottieInstance.useLottieInstance(lottie);
+	if (state !== require_types.LottieState.loading) return null;
+	return require_renderStyledElement.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__ */ (0, react_jsx_runtime.jsx)("div", { className: spinnerClass })
+	});
+});
+//#endregion
+exports.LottieLoading = LottieLoading;
+exports.lottieLoadingClass = lottieLoadingClass;
+exports.lottieLoadingStyles = lottieLoadingStyles;

package/build/overlays/LottieLoading.d.cts

@@ -0,0 +1,45 @@
+import { FixedElementProps, LottieInstance } from "../animation/types.cjs";
+import { ReactNode } from "react";
+//#region src/overlays/LottieLoading.d.ts
+/** What this component owns. Every other prop belongs to the element. */
+interface LottieLoadingOwnProps {
+  /** The animation to watch. Omit it inside a component that publishes one. */
+  lottie?: LottieInstance;
+  /** What to show while it loads. A turning indicator unless you say otherwise. */
+  children?: ReactNode;
+  /** Added to the library's class rather than replacing it. */
+  className?: string;
+  /**
+   * How long to wait before appearing, in milliseconds.
+   *
+   * An animation that arrives sooner is never covered at all, which is what
+   * stops a fast load showing an indicator nobody can read. Setting `0` shows
+   * it at once.
+   */
+  showAfter?: number;
+}
+/** What {@link LottieLoading} accepts. */
+type LottieLoadingProps = FixedElementProps<LottieLoadingOwnProps, "div">;
+/**
+ * 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.
+ */
+declare const LottieLoading: import("react").ForwardRefExoticComponent<LottieLoadingOwnProps & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof LottieLoadingOwnProps> & import("react").RefAttributes<HTMLDivElement>>;
+//#endregion
+export { LottieLoading, LottieLoadingProps };

package/build/overlays/LottieLoading.d.ts

@@ -0,0 +1,45 @@
+import { FixedElementProps, LottieInstance } from "../animation/types.js";
+import { ReactNode } from "react";
+//#region src/overlays/LottieLoading.d.ts
+/** What this component owns. Every other prop belongs to the element. */
+interface LottieLoadingOwnProps {
+  /** The animation to watch. Omit it inside a component that publishes one. */
+  lottie?: LottieInstance;
+  /** What to show while it loads. A turning indicator unless you say otherwise. */
+  children?: ReactNode;
+  /** Added to the library's class rather than replacing it. */
+  className?: string;
+  /**
+   * How long to wait before appearing, in milliseconds.
+   *
+   * An animation that arrives sooner is never covered at all, which is what
+   * stops a fast load showing an indicator nobody can read. Setting `0` shows
+   * it at once.
+   */
+  showAfter?: number;
+}
+/** What {@link LottieLoading} accepts. */
+type LottieLoadingProps = FixedElementProps<LottieLoadingOwnProps, "div">;
+/**
+ * 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.
+ */
+declare const LottieLoading: import("react").ForwardRefExoticComponent<LottieLoadingOwnProps & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof LottieLoadingOwnProps> & import("react").RefAttributes<HTMLDivElement>>;
+//#endregion
+export { LottieLoading, LottieLoadingProps };