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

package/build/animation/LottieSvg.d.cts

@@ -0,0 +1,24 @@
+import { AnyTag, LottieRenderer, RendererInSvg } from "./types.cjs";
+import { LottieComponent, LottieComponentProps } from "./createLottieComponent.cjs";
+import { ReactNode } from "react";
+//#region src/animation/LottieSvg.d.ts
+/**
+ * What {@link LottieSvg} accepts. Identical to `LottieProps` except that
+ * `renderer` admits only what the svg build contains.
+ */
+type LottieSvgProps<As extends AnyTag = "div", Children extends ReactNode = undefined, Renderer extends RendererInSvg = typeof LottieRenderer.svg> = LottieComponentProps<As, Children, Renderer>;
+/**
+ * Renders an animation using the svg build of the engine.
+ *
+ * Identical to {@link Lottie} except that `svg` is the only renderer, which the
+ * type enforces: the svg build does not contain the other two, and asking it
+ * for one throws at runtime while its own declarations claim otherwise.
+ *
+ * It sits between the other two builds: smaller than the full one because it
+ * carries a single renderer, and unlike {@link LottieLight} it keeps the
+ * expression engine, so an animation whose properties are driven by
+ * expressions plays as designed.
+ */
+declare const LottieSvg: LottieComponent<"svg">;
+//#endregion
+export { LottieSvg, LottieSvgProps };

package/build/animation/LottieSvg.d.ts

@@ -0,0 +1,24 @@
+import { AnyTag, LottieRenderer, RendererInSvg } from "./types.js";
+import { LottieComponent, LottieComponentProps } from "./createLottieComponent.js";
+import { ReactNode } from "react";
+//#region src/animation/LottieSvg.d.ts
+/**
+ * What {@link LottieSvg} accepts. Identical to `LottieProps` except that
+ * `renderer` admits only what the svg build contains.
+ */
+type LottieSvgProps<As extends AnyTag = "div", Children extends ReactNode = undefined, Renderer extends RendererInSvg = typeof LottieRenderer.svg> = LottieComponentProps<As, Children, Renderer>;
+/**
+ * Renders an animation using the svg build of the engine.
+ *
+ * Identical to {@link Lottie} except that `svg` is the only renderer, which the
+ * type enforces: the svg build does not contain the other two, and asking it
+ * for one throws at runtime while its own declarations claim otherwise.
+ *
+ * It sits between the other two builds: smaller than the full one because it
+ * carries a single renderer, and unlike {@link LottieLight} it keeps the
+ * expression engine, so an animation whose properties are driven by
+ * expressions plays as designed.
+ */
+declare const LottieSvg: LottieComponent<"svg">;
+//#endregion
+export { LottieSvg, LottieSvgProps };

package/build/animation/LottieSvg.js

@@ -0,0 +1,19 @@
+"use client";
+import { createLottieComponent } from "./createLottieComponent.js";
+import { svgEngine } from "./useLottieSvg.js";
+//#region src/animation/LottieSvg.tsx
+/**
+* Renders an animation using the svg build of the engine.
+*
+* Identical to {@link Lottie} except that `svg` is the only renderer, which the
+* type enforces: the svg build does not contain the other two, and asking it
+* for one throws at runtime while its own declarations claim otherwise.
+*
+* It sits between the other two builds: smaller than the full one because it
+* carries a single renderer, and unlike {@link LottieLight} it keeps the
+* expression engine, so an animation whose properties are driven by
+* expressions plays as designed.
+*/
+const LottieSvg = createLottieComponent(svgEngine);
+//#endregion
+export { LottieSvg };

package/build/animation/collectMarkerCrossings.cjs

@@ -0,0 +1,38 @@
+//#region src/animation/collectMarkerCrossings.ts
+/**
+* The markers a playhead movement passed, in the order it passed them.
+*
+* Positions are compared in the playable range's own coordinates: a marker sits
+* at `time - firstFrame`, which follows a segment the way the playhead does.
+* Moving forward passes a marker when the playhead goes from before it to on or
+* beyond it, so landing exactly on one announces it and the next movement away
+* does not repeat it; moving backward mirrors that. A loop's wrap is not a
+* movement this understands: the caller splits it into the two straight runs it
+* really is and calls twice.
+*
+* The markers must be sorted ascending by `time`, which is what lets a scan
+* stop at the first one past the movement. Returns `null` rather than an empty
+* list when nothing was passed, so the per-frame path allocates nothing.
+*/
+function collectMarkerCrossings(markers, firstFrame, previous, current) {
+	if (markers.length === 0 || previous === current) return null;
+	let crossed = null;
+	if (current > previous) for (const marker of markers) {
+		const frame = marker.time - firstFrame;
+		if (frame <= previous) continue;
+		if (frame > current) break;
+		if (crossed === null) crossed = [];
+		crossed.push(marker.payload.name);
+	}
+	else for (let index = markers.length - 1; index >= 0; index -= 1) {
+		const marker = markers[index];
+		const frame = marker.time - firstFrame;
+		if (frame >= previous) continue;
+		if (frame < current) break;
+		if (crossed === null) crossed = [];
+		crossed.push(marker.payload.name);
+	}
+	return crossed;
+}
+//#endregion
+exports.collectMarkerCrossings = collectMarkerCrossings;

package/build/animation/collectMarkerCrossings.js

@@ -0,0 +1,38 @@
+//#region src/animation/collectMarkerCrossings.ts
+/**
+* The markers a playhead movement passed, in the order it passed them.
+*
+* Positions are compared in the playable range's own coordinates: a marker sits
+* at `time - firstFrame`, which follows a segment the way the playhead does.
+* Moving forward passes a marker when the playhead goes from before it to on or
+* beyond it, so landing exactly on one announces it and the next movement away
+* does not repeat it; moving backward mirrors that. A loop's wrap is not a
+* movement this understands: the caller splits it into the two straight runs it
+* really is and calls twice.
+*
+* The markers must be sorted ascending by `time`, which is what lets a scan
+* stop at the first one past the movement. Returns `null` rather than an empty
+* list when nothing was passed, so the per-frame path allocates nothing.
+*/
+function collectMarkerCrossings(markers, firstFrame, previous, current) {
+	if (markers.length === 0 || previous === current) return null;
+	let crossed = null;
+	if (current > previous) for (const marker of markers) {
+		const frame = marker.time - firstFrame;
+		if (frame <= previous) continue;
+		if (frame > current) break;
+		if (crossed === null) crossed = [];
+		crossed.push(marker.payload.name);
+	}
+	else for (let index = markers.length - 1; index >= 0; index -= 1) {
+		const marker = markers[index];
+		const frame = marker.time - firstFrame;
+		if (frame >= previous) continue;
+		if (frame < current) break;
+		if (crossed === null) crossed = [];
+		crossed.push(marker.payload.name);
+	}
+	return crossed;
+}
+//#endregion
+export { collectMarkerCrossings };

package/build/animation/configureLottie.cjs

@@ -0,0 +1,50 @@
+"use client";
+//#region src/animation/configureLottie.ts
+/**
+* The engine builds by the name lottie-web gives each, which is the suffix a
+* build's element IDs carry.
+*/
+const LottieEngineName = {
+	full: "lottie",
+	svg: "lottie_svg",
+	light: "lottie_light"
+};
+let idPrefix = "lottie-react";
+let quality;
+const engines = /* @__PURE__ */ new Map();
+function apply(player, name) {
+	player.setIDPrefix(`${idPrefix}-${name}`);
+	if (quality !== void 0) player.setQuality(quality);
+}
+/**
+* Sets what is global to the engine rather than to one animation: the prefix
+* of the element IDs it mints, and how finely it draws curves.
+*
+* ```ts
+* configureLottie({ idPrefix: "crm", quality: "low" });
+* ```
+*
+* Set it once, at startup, before animations load. It takes effect at once on
+* every engine that has loaded an animation, and on the others when they first
+* do, and it reaches what is already on screen: element IDs for everything the
+* engines build from then on, the drawing quality of every animation on them.
+* A field left out keeps its value.
+*/
+function configureLottie(options) {
+	if (options.idPrefix !== void 0) idPrefix = options.idPrefix;
+	if (options.quality !== void 0) quality = options.quality;
+	for (const [player, name] of engines) apply(player, name);
+}
+/**
+* Brings one engine up to the current settings and remembers it for later
+* calls to {@link configureLottie}. The load path calls it right before
+* `loadAnimation`.
+*/
+function applyEngineSettings(engine) {
+	engines.set(engine.player, engine.name);
+	apply(engine.player, engine.name);
+}
+//#endregion
+exports.LottieEngineName = LottieEngineName;
+exports.applyEngineSettings = applyEngineSettings;
+exports.configureLottie = configureLottie;

package/build/animation/configureLottie.d.cts

@@ -0,0 +1,38 @@
+import "lottie-web";
+//#region src/animation/configureLottie.d.ts
+/** What {@link configureLottie} can be told. */
+interface ConfigureLottieOptions {
+  /**
+   * The base of every element ID the engine mints, so that two copies of the
+   * library on one page can be told apart. Each engine build appends its own
+   * suffix (`-lottie`, `-lottie_svg`, `-lottie_light`), so the three builds
+   * never share an ID with each other. `lottie-react` unless set.
+   */
+  idPrefix?: string;
+  /**
+   * How finely curves are drawn: `low`, `medium`, `high`, or a number of
+   * segments above 1. Left alone, the engine draws with 150, between `medium`
+   * (50) and `high` (200); the named levels trade smoothness for work. Set it
+   * once, before animations load: the engine reads it whenever it builds a
+   * curve, so a change reaches every animation on the engine, running ones
+   * included.
+   */
+  quality?: "low" | "medium" | "high" | number;
+}
+/**
+ * Sets what is global to the engine rather than to one animation: the prefix
+ * of the element IDs it mints, and how finely it draws curves.
+ *
+ * ```ts
+ * configureLottie({ idPrefix: "crm", quality: "low" });
+ * ```
+ *
+ * Set it once, at startup, before animations load. It takes effect at once on
+ * every engine that has loaded an animation, and on the others when they first
+ * do, and it reaches what is already on screen: element IDs for everything the
+ * engines build from then on, the drawing quality of every animation on them.
+ * A field left out keeps its value.
+ */
+declare function configureLottie(options: ConfigureLottieOptions): void;
+//#endregion
+export { ConfigureLottieOptions, configureLottie };

package/build/animation/configureLottie.d.ts

@@ -0,0 +1,38 @@
+import "lottie-web";
+//#region src/animation/configureLottie.d.ts
+/** What {@link configureLottie} can be told. */
+interface ConfigureLottieOptions {
+  /**
+   * The base of every element ID the engine mints, so that two copies of the
+   * library on one page can be told apart. Each engine build appends its own
+   * suffix (`-lottie`, `-lottie_svg`, `-lottie_light`), so the three builds
+   * never share an ID with each other. `lottie-react` unless set.
+   */
+  idPrefix?: string;
+  /**
+   * How finely curves are drawn: `low`, `medium`, `high`, or a number of
+   * segments above 1. Left alone, the engine draws with 150, between `medium`
+   * (50) and `high` (200); the named levels trade smoothness for work. Set it
+   * once, before animations load: the engine reads it whenever it builds a
+   * curve, so a change reaches every animation on the engine, running ones
+   * included.
+   */
+  quality?: "low" | "medium" | "high" | number;
+}
+/**
+ * Sets what is global to the engine rather than to one animation: the prefix
+ * of the element IDs it mints, and how finely it draws curves.
+ *
+ * ```ts
+ * configureLottie({ idPrefix: "crm", quality: "low" });
+ * ```
+ *
+ * Set it once, at startup, before animations load. It takes effect at once on
+ * every engine that has loaded an animation, and on the others when they first
+ * do, and it reaches what is already on screen: element IDs for everything the
+ * engines build from then on, the drawing quality of every animation on them.
+ * A field left out keeps its value.
+ */
+declare function configureLottie(options: ConfigureLottieOptions): void;
+//#endregion
+export { ConfigureLottieOptions, configureLottie };

package/build/animation/configureLottie.js

@@ -0,0 +1,48 @@
+"use client";
+//#region src/animation/configureLottie.ts
+/**
+* The engine builds by the name lottie-web gives each, which is the suffix a
+* build's element IDs carry.
+*/
+const LottieEngineName = {
+	full: "lottie",
+	svg: "lottie_svg",
+	light: "lottie_light"
+};
+let idPrefix = "lottie-react";
+let quality;
+const engines = /* @__PURE__ */ new Map();
+function apply(player, name) {
+	player.setIDPrefix(`${idPrefix}-${name}`);
+	if (quality !== void 0) player.setQuality(quality);
+}
+/**
+* Sets what is global to the engine rather than to one animation: the prefix
+* of the element IDs it mints, and how finely it draws curves.
+*
+* ```ts
+* configureLottie({ idPrefix: "crm", quality: "low" });
+* ```
+*
+* Set it once, at startup, before animations load. It takes effect at once on
+* every engine that has loaded an animation, and on the others when they first
+* do, and it reaches what is already on screen: element IDs for everything the
+* engines build from then on, the drawing quality of every animation on them.
+* A field left out keeps its value.
+*/
+function configureLottie(options) {
+	if (options.idPrefix !== void 0) idPrefix = options.idPrefix;
+	if (options.quality !== void 0) quality = options.quality;
+	for (const [player, name] of engines) apply(player, name);
+}
+/**
+* Brings one engine up to the current settings and remembers it for later
+* calls to {@link configureLottie}. The load path calls it right before
+* `loadAnimation`.
+*/
+function applyEngineSettings(engine) {
+	engines.set(engine.player, engine.name);
+	apply(engine.player, engine.name);
+}
+//#endregion
+export { LottieEngineName, applyEngineSettings, configureLottie };

package/build/animation/createLottieComponent.cjs

@@ -0,0 +1,131 @@
+const require_mergeRefs = require("../utils/mergeRefs.cjs");
+const require_polymorphicForwardRef = require("./polymorphicForwardRef.cjs");
+const require_renderStyledElement = require("./renderStyledElement.cjs");
+const require_LottieInstanceContext = require("./LottieInstanceContext.cjs");
+const require_LottieDisplay = require("./LottieDisplay.cjs");
+const require_useLottieAnimation = require("./useLottieAnimation.cjs");
+let react = require("react");
+let react_jsx_runtime = require("react/jsx-runtime");
+//#region src/animation/createLottieComponent.tsx
+/**
+* The class the element around the animation carries when you place the
+* animation yourself, and the name React deduplicates its stylesheet by.
+*/
+const lottieRootClass = "lottie-root";
+/**
+* The rules that element carries, at zero specificity and inside the library's
+* cascade layer, so any rule the consumer writes beats them per property.
+*
+* The column is what puts the controls below the animation, and `position` is
+* what the overlays anchor to. The second rule is what lets the animation take
+* the space the controls leave, since the display's own default height is a
+* full 100% that would otherwise push them out of the box.
+*
+* The descendant rule is written as two separate `:where()` selectors rather
+* than one wrapping the combinator. The two are identical CSS at identical zero
+* specificity, so the split form costs nothing and reads as two independent
+* claims about specificity.
+*
+* The third rule is what this element looks like once it fills the screen. A
+* browser paints a black backdrop behind whatever goes fullscreen and leaves
+* the element itself transparent, so without a surface of its own the animation
+* sits on black and the control bar, whose colours are all inherited, keeps the
+* page's dark text and becomes close to unreadable. Measured in Chromium
+* against the real bar. `Canvas` and `CanvasText` are the system page colours
+* and are taken as a pair, so the two can never contradict each other the way a
+* background without a matching foreground can; they follow the consumer's
+* declared colour scheme rather than a colour this library picked, and the rule
+* is zero-specificity like every other, so one line of their own CSS replaces
+* either. It cannot be verified here, since this environment has no Fullscreen
+* API at all.
+*/
+const lottieRootStyles = `:where(.${lottieRootClass}){position:relative;display:flex;flex-direction:column}:where(.${lottieRootClass}) > :where(.${require_LottieDisplay.lottieDisplayClass}){flex:1;height:auto}:where(.${lottieRootClass}:fullscreen){background:Canvas;color:CanvasText}`;
+/**
+* Builds the component all three public ones are: the full, svg and light
+* builds differ in the engine they load and in the renderers they admit, and in
+* nothing else.
+*
+* `Renderers` is what narrows a smaller build to the renderers it actually
+* contains, so asking it for one it does not have is a compile error rather
+* than a blank animation and a runtime throw.
+*/
+function createLottieComponent(engine) {
+	return require_polymorphicForwardRef.polymorphicForwardRef(function Lottie({ as, children, className, lottieRef, src, renderer, rendererSettings, loop, speed, direction, autoplay, segment, assetsPath, debug, subscriptions, ...rest }, ref) {
+		const instance = require_useLottieAnimation.useLottieAnimation(engine, {
+			src,
+			renderer,
+			rendererSettings,
+			loop,
+			speed,
+			direction,
+			autoplay,
+			segment,
+			assetsPath,
+			debug,
+			subscriptions
+		});
+		const { setDisplayRef, setRootRef } = instance;
+		(0, react.useImperativeHandle)(lottieRef, () => ({
+			reload: instance.reload,
+			play: instance.play,
+			pause: instance.pause,
+			stop: instance.stop,
+			seek: instance.seek,
+			scrubStart: instance.scrubStart,
+			scrubTo: instance.scrubTo,
+			scrubEnd: instance.scrubEnd,
+			playSegments: instance.playSegments,
+			resetSegments: instance.resetSegments,
+			setSpeed: instance.setSpeed,
+			setDirection: instance.setDirection,
+			setLoop: instance.setLoop,
+			animationItem: instance.animationItem
+		}));
+		const attached = (0, react.useRef)(0);
+		const countDisplay = (0, react.useCallback)((node) => {
+			attached.current += node === null ? -1 : 1;
+			setDisplayRef(node);
+		}, [setDisplayRef]);
+		const published = (0, react.useMemo)(() => ({
+			...instance,
+			setDisplayRef: countDisplay
+		}), [instance, countDisplay]);
+		const hasChildren = children !== void 0;
+		(0, react.useEffect)(() => {
+			if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
+				if (!hasChildren || attached.current === 1) return;
+				if (attached.current === 0) console.warn("[lottie-react] <Lottie> was given children and none of them is a <LottieDisplay>, so the animation has nowhere to be drawn. Add one where the animation should go. A display rendered conditionally has not appeared yet on this pass, which is the one case where this warning is expected.");
+				else console.warn(`[lottie-react] <Lottie> was given ${attached.current} <LottieDisplay> children and an animation can only be drawn in one of them, so the last to attach is the one that gets it. Render one display per animation.`);
+			}
+		}, [hasChildren]);
+		const attachDisplay = (0, react.useMemo)(() => require_mergeRefs.mergeRefs(ref, countDisplay, setRootRef), [
+			ref,
+			countDisplay,
+			setRootRef
+		]);
+		const attachWrapper = (0, react.useMemo)(() => require_mergeRefs.mergeRefs(ref, setRootRef), [ref, setRootRef]);
+		const tag = typeof as === "string" ? as : "div";
+		if (!hasChildren) return require_renderStyledElement.renderStyledElement({
+			tag,
+			styleClass: require_LottieDisplay.lottieDisplayClass,
+			styles: require_LottieDisplay.lottieDisplayStyles,
+			className,
+			attributes: rest,
+			ref: attachDisplay
+		});
+		return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_LottieInstanceContext.LottieInstanceContext.Provider, {
+			value: published,
+			children: require_renderStyledElement.renderStyledElement({
+				tag,
+				styleClass: lottieRootClass,
+				styles: lottieRootStyles,
+				className,
+				attributes: rest,
+				ref: attachWrapper,
+				children
+			})
+		});
+	});
+}
+//#endregion
+exports.createLottieComponent = createLottieComponent;

package/build/animation/createLottieComponent.d.cts

@@ -0,0 +1,45 @@
+import "./configureLottie.cjs";
+import { AnyTag, ElementProps, LottieHandle, LottieRenderer } from "./types.cjs";
+import { UseLottieOptions } from "./useLottieAnimation.cjs";
+import { ReactNode, Ref } from "react";
+//#region src/animation/createLottieComponent.d.ts
+/**
+ * What a Lottie component owns, on top of everything the animation takes.
+ *
+ * Every name here is checked against the attributes of the elements `as`
+ * permits, so none of them can quietly take an attribute away from a consumer.
+ */
+interface LottieOwnProps<Children extends ReactNode, Renderer extends LottieRenderer> extends UseLottieOptions<Renderer> {
+  /** Which element to render. A `div` unless you say otherwise. */
+  as?: unknown;
+  /**
+   * Anything at all. Passing children means you place the animation yourself
+   * with `<LottieDisplay>`, and this component renders only the box around it.
+   */
+  children?: Children;
+  /** Added to the library's class rather than replacing it. */
+  className?: string;
+  /**
+   * Where to put the imperative handle: the commands, without the values.
+   *
+   * `ref` names the element, because this component accepts that element's
+   * whole attribute set, so the handle needs somewhere of its own to go. Write
+   * `useRef<LottieHandle>(null)`; no ref type is exported.
+   */
+  lottieRef?: Ref<LottieHandle>;
+}
+/** What a Lottie component accepts for a given element. */
+type LottieComponentProps<As extends AnyTag, Children extends ReactNode, Renderer extends LottieRenderer> = ElementProps<LottieOwnProps<Children, Renderer>, As, Children, Renderer>;
+/**
+ * A component that renders an animation, still generic in its element, its
+ * children and its renderer once the engine has been chosen.
+ *
+ * Written out as a call signature rather than inferred, because a function that
+ * returns a component would otherwise settle those parameters at the moment the
+ * component is created and hand back something that is no longer polymorphic.
+ */
+type LottieComponent<Renderers extends LottieRenderer> = <As extends AnyTag = "div", Children extends ReactNode = undefined, Renderer extends Renderers = Extract<Renderers, typeof LottieRenderer.svg>>(props: LottieComponentProps<As, Children, Renderer> & {
+  ref?: Ref<HTMLElement>;
+}) => ReactNode;
+//#endregion
+export { LottieComponent, LottieComponentProps, LottieOwnProps };

package/build/animation/createLottieComponent.d.ts

@@ -0,0 +1,45 @@
+import "./configureLottie.js";
+import { AnyTag, ElementProps, LottieHandle, LottieRenderer } from "./types.js";
+import { UseLottieOptions } from "./useLottieAnimation.js";
+import { ReactNode, Ref } from "react";
+//#region src/animation/createLottieComponent.d.ts
+/**
+ * What a Lottie component owns, on top of everything the animation takes.
+ *
+ * Every name here is checked against the attributes of the elements `as`
+ * permits, so none of them can quietly take an attribute away from a consumer.
+ */
+interface LottieOwnProps<Children extends ReactNode, Renderer extends LottieRenderer> extends UseLottieOptions<Renderer> {
+  /** Which element to render. A `div` unless you say otherwise. */
+  as?: unknown;
+  /**
+   * Anything at all. Passing children means you place the animation yourself
+   * with `<LottieDisplay>`, and this component renders only the box around it.
+   */
+  children?: Children;
+  /** Added to the library's class rather than replacing it. */
+  className?: string;
+  /**
+   * Where to put the imperative handle: the commands, without the values.
+   *
+   * `ref` names the element, because this component accepts that element's
+   * whole attribute set, so the handle needs somewhere of its own to go. Write
+   * `useRef<LottieHandle>(null)`; no ref type is exported.
+   */
+  lottieRef?: Ref<LottieHandle>;
+}
+/** What a Lottie component accepts for a given element. */
+type LottieComponentProps<As extends AnyTag, Children extends ReactNode, Renderer extends LottieRenderer> = ElementProps<LottieOwnProps<Children, Renderer>, As, Children, Renderer>;
+/**
+ * A component that renders an animation, still generic in its element, its
+ * children and its renderer once the engine has been chosen.
+ *
+ * Written out as a call signature rather than inferred, because a function that
+ * returns a component would otherwise settle those parameters at the moment the
+ * component is created and hand back something that is no longer polymorphic.
+ */
+type LottieComponent<Renderers extends LottieRenderer> = <As extends AnyTag = "div", Children extends ReactNode = undefined, Renderer extends Renderers = Extract<Renderers, typeof LottieRenderer.svg>>(props: LottieComponentProps<As, Children, Renderer> & {
+  ref?: Ref<HTMLElement>;
+}) => ReactNode;
+//#endregion
+export { LottieComponent, LottieComponentProps, LottieOwnProps };