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

package/build/animation/polymorphicForwardRef.js

@@ -0,0 +1,19 @@
+import { forwardRef } from "react";
+//#region src/animation/polymorphicForwardRef.ts
+/**
+* `forwardRef`, with the render function's own type parameters kept.
+*
+* A component that chooses its element through `as` is generic in that tag, and
+* React's `forwardRef` is not: its signature settles the props at one type, so
+* the tag is lost and `as="button" type="button"` stops typechecking while
+* invented props start passing. Handing the same runtime function a signature
+* that carries the parameters through is what restores per-element props.
+*
+* The assertion lives here, alone, so that there is one of it and so that what
+* removes it is written beside it. React 18 is the whole reason it exists,
+* because a function component receives a `ref` only through `forwardRef`
+* there.
+*/
+const polymorphicForwardRef = forwardRef;
+//#endregion
+export { polymorphicForwardRef };

package/build/animation/renderStyledElement.cjs

@@ -0,0 +1,31 @@
+const require_styleLayer = require("./styleLayer.cjs");
+const require_stylePrecedence = require("./stylePrecedence.cjs");
+let react = require("react");
+let react_jsx_runtime = require("react/jsx-runtime");
+//#region src/animation/renderStyledElement.tsx
+/**
+* Renders one element carrying a library class, together with the stylesheet
+* that class names.
+*
+* The class and the `href` are one string, so React deduplicates the rules by
+* the same name the rules are scoped to: two components can only collide in the
+* document if they already collide in CSS, which is visible rather than silent.
+*
+* Built through `createElement` rather than as JSX, because JSX cannot take an
+* element type that is still generic: `<Tag />` where the tag comes from `as`
+* is `TS2604, no construct or call signatures`. Narrowing to one concrete tag
+* instead needs an assertion, which this does not.
+*/
+function renderStyledElement({ tag, styleClass, styles, className, attributes, ref, children }) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [(0, react.createElement)(tag, {
+		...attributes,
+		className: className ? `${styleClass} ${className}` : styleClass,
+		ref
+	}, children), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("style", {
+		href: styleClass,
+		precedence: require_stylePrecedence.stylePrecedence,
+		children: `@layer ${require_styleLayer.styleLayer}{${styles}}`
+	})] });
+}
+//#endregion
+exports.renderStyledElement = renderStyledElement;

package/build/animation/renderStyledElement.js

@@ -0,0 +1,31 @@
+import { styleLayer } from "./styleLayer.js";
+import { stylePrecedence } from "./stylePrecedence.js";
+import { createElement } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/animation/renderStyledElement.tsx
+/**
+* Renders one element carrying a library class, together with the stylesheet
+* that class names.
+*
+* The class and the `href` are one string, so React deduplicates the rules by
+* the same name the rules are scoped to: two components can only collide in the
+* document if they already collide in CSS, which is visible rather than silent.
+*
+* Built through `createElement` rather than as JSX, because JSX cannot take an
+* element type that is still generic: `<Tag />` where the tag comes from `as`
+* is `TS2604, no construct or call signatures`. Narrowing to one concrete tag
+* instead needs an assertion, which this does not.
+*/
+function renderStyledElement({ tag, styleClass, styles, className, attributes, ref, children }) {
+	return /* @__PURE__ */ jsxs(Fragment, { children: [createElement(tag, {
+		...attributes,
+		className: className ? `${styleClass} ${className}` : styleClass,
+		ref
+	}, children), /* @__PURE__ */ jsx("style", {
+		href: styleClass,
+		precedence: stylePrecedence,
+		children: `@layer ${styleLayer}{${styles}}`
+	})] });
+}
+//#endregion
+export { renderStyledElement };

package/build/animation/resolveSeekTarget.cjs

@@ -0,0 +1,97 @@
+//#region src/animation/resolveSeekTarget.ts
+/**
+* Narrows an unknown value to a marker we can use.
+*
+* A marker whose After Effects comment parsed as JSON without a `name` fails
+* here, which matches the engine: such a marker cannot be addressed by name at
+* all, so a designer can label something the code has no way to reach.
+*/
+function isMarker(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("time" in value) || typeof value.time !== "number") return false;
+	if ("duration" in value) {
+		const { duration } = value;
+		if (duration !== void 0 && typeof duration !== "number") return false;
+	}
+	if (!("payload" in value)) return false;
+	const { payload } = value;
+	if (typeof payload !== "object" || payload === null) return false;
+	return "name" in payload && typeof payload.name === "string";
+}
+/**
+* The animation's markers, or an empty list when it has none we can read.
+*
+* The `in` check is what makes the undeclared property readable without a cast:
+* it narrows to a record whose value is `unknown`, which the guard above then
+* takes the rest of the way.
+*/
+function readMarkers(item) {
+	if (!("markers" in item)) return [];
+	const { markers } = item;
+	if (!Array.isArray(markers)) return [];
+	return markers.filter(isMarker);
+}
+function findMarker(item, name) {
+	for (const marker of readMarkers(item)) if (marker.payload.name === name) return marker;
+	return null;
+}
+/** The frame a target asks for, before it is held inside the playable range. */
+function requestedFrame(item, target) {
+	if (typeof target === "number") return target;
+	const { frame, percent, seconds, marker } = target;
+	if (frame !== void 0) return frame;
+	if (percent !== void 0) return item.totalFrames * percent / 100;
+	if (seconds !== void 0) return seconds * item.frameRate;
+	const found = marker === void 0 ? null : findMarker(item, marker);
+	return found === null ? null : found.time - item.firstFrame;
+}
+/**
+* Turns a seek target into a frame inside the playable range.
+*
+* Returns `null` when the target names nothing the animation has, which is an
+* unknown marker or a number that is not finite. `requested` is what was asked
+* for and `frame` is what is reachable, so a caller can tell that a position
+* was pulled back to the range without this having to say anything about it.
+*/
+function resolveSeekTarget(item, target) {
+	const requested = requestedFrame(item, target);
+	if (requested === null || !Number.isFinite(requested)) return null;
+	const last = Math.max(item.totalFrames - .001, 0);
+	return {
+		frame: Math.min(Math.max(requested, 0), last),
+		requested
+	};
+}
+/** Distinguishes one range from a list of them, which share an array type. */
+function isSingleRange(segments) {
+	return typeof segments[0] === "number";
+}
+/**
+* Turns what a caller passed into the list of ranges the engine takes.
+*
+* Returns `null` when nothing playable was described: a range whose ends are
+* equal or not finite, an empty list, an unknown marker, or a marker carrying
+* no duration. That last one is a labelled position rather than a labelled
+* span, and the engine would respond to it by playing the entire animation.
+*
+* A marker's frames are used as they are. Unlike a seek, a range endpoint is
+* absolute, so the correction that seeking needs would be wrong here.
+*
+* The result is always freshly built, never the caller's own arrays, because
+* the engine queues whatever it is handed and the input is typed `readonly`.
+*/
+function resolveSegments(item, segments) {
+	if ("marker" in segments) {
+		const marker = findMarker(item, segments.marker);
+		if (marker === null || !marker.duration) return null;
+		return [[marker.time, marker.time + marker.duration]];
+	}
+	const ranges = isSingleRange(segments) ? [segments] : segments;
+	if (ranges.length === 0) return null;
+	for (const [start, end] of ranges) if (!Number.isFinite(start) || !Number.isFinite(end) || start === end) return null;
+	return ranges.map(([start, end]) => [start, end]);
+}
+//#endregion
+exports.readMarkers = readMarkers;
+exports.resolveSeekTarget = resolveSeekTarget;
+exports.resolveSegments = resolveSegments;

package/build/animation/resolveSeekTarget.js

@@ -0,0 +1,95 @@
+//#region src/animation/resolveSeekTarget.ts
+/**
+* Narrows an unknown value to a marker we can use.
+*
+* A marker whose After Effects comment parsed as JSON without a `name` fails
+* here, which matches the engine: such a marker cannot be addressed by name at
+* all, so a designer can label something the code has no way to reach.
+*/
+function isMarker(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("time" in value) || typeof value.time !== "number") return false;
+	if ("duration" in value) {
+		const { duration } = value;
+		if (duration !== void 0 && typeof duration !== "number") return false;
+	}
+	if (!("payload" in value)) return false;
+	const { payload } = value;
+	if (typeof payload !== "object" || payload === null) return false;
+	return "name" in payload && typeof payload.name === "string";
+}
+/**
+* The animation's markers, or an empty list when it has none we can read.
+*
+* The `in` check is what makes the undeclared property readable without a cast:
+* it narrows to a record whose value is `unknown`, which the guard above then
+* takes the rest of the way.
+*/
+function readMarkers(item) {
+	if (!("markers" in item)) return [];
+	const { markers } = item;
+	if (!Array.isArray(markers)) return [];
+	return markers.filter(isMarker);
+}
+function findMarker(item, name) {
+	for (const marker of readMarkers(item)) if (marker.payload.name === name) return marker;
+	return null;
+}
+/** The frame a target asks for, before it is held inside the playable range. */
+function requestedFrame(item, target) {
+	if (typeof target === "number") return target;
+	const { frame, percent, seconds, marker } = target;
+	if (frame !== void 0) return frame;
+	if (percent !== void 0) return item.totalFrames * percent / 100;
+	if (seconds !== void 0) return seconds * item.frameRate;
+	const found = marker === void 0 ? null : findMarker(item, marker);
+	return found === null ? null : found.time - item.firstFrame;
+}
+/**
+* Turns a seek target into a frame inside the playable range.
+*
+* Returns `null` when the target names nothing the animation has, which is an
+* unknown marker or a number that is not finite. `requested` is what was asked
+* for and `frame` is what is reachable, so a caller can tell that a position
+* was pulled back to the range without this having to say anything about it.
+*/
+function resolveSeekTarget(item, target) {
+	const requested = requestedFrame(item, target);
+	if (requested === null || !Number.isFinite(requested)) return null;
+	const last = Math.max(item.totalFrames - .001, 0);
+	return {
+		frame: Math.min(Math.max(requested, 0), last),
+		requested
+	};
+}
+/** Distinguishes one range from a list of them, which share an array type. */
+function isSingleRange(segments) {
+	return typeof segments[0] === "number";
+}
+/**
+* Turns what a caller passed into the list of ranges the engine takes.
+*
+* Returns `null` when nothing playable was described: a range whose ends are
+* equal or not finite, an empty list, an unknown marker, or a marker carrying
+* no duration. That last one is a labelled position rather than a labelled
+* span, and the engine would respond to it by playing the entire animation.
+*
+* A marker's frames are used as they are. Unlike a seek, a range endpoint is
+* absolute, so the correction that seeking needs would be wrong here.
+*
+* The result is always freshly built, never the caller's own arrays, because
+* the engine queues whatever it is handed and the input is typed `readonly`.
+*/
+function resolveSegments(item, segments) {
+	if ("marker" in segments) {
+		const marker = findMarker(item, segments.marker);
+		if (marker === null || !marker.duration) return null;
+		return [[marker.time, marker.time + marker.duration]];
+	}
+	const ranges = isSingleRange(segments) ? [segments] : segments;
+	if (ranges.length === 0) return null;
+	for (const [start, end] of ranges) if (!Number.isFinite(start) || !Number.isFinite(end) || start === end) return null;
+	return ranges.map(([start, end]) => [start, end]);
+}
+//#endregion
+export { readMarkers, resolveSeekTarget, resolveSegments };

package/build/animation/styleLayer.cjs

@@ -0,0 +1,24 @@
+//#region src/animation/styleLayer.ts
+/**
+* The cascade layer every library stylesheet is wrapped in.
+*
+* The wrapper exists for consumers whose own CSS lives in cascade layers,
+* Tailwind 4 being the common case. Unlayered rules outrank all layered rules,
+* so without a layer of our own even a zero-specificity default beats every
+* utility class. Inside a layer, the defaults can be ranked below the
+* consumer's layers with one declaration written before their own styles load:
+*
+* ```css
+* @layer lottie-react;
+* ```
+*
+* A consumer whose CSS is unlayered needs nothing: unlayered rules beat
+* layered ones, so their styles keep winning as before.
+*
+* Named after the package, like the style precedence, because a name a
+* consumer already associates with the library cannot collide with a layer
+* ladder of their own.
+*/
+const styleLayer = "lottie-react";
+//#endregion
+exports.styleLayer = styleLayer;

package/build/animation/styleLayer.js

@@ -0,0 +1,24 @@
+//#region src/animation/styleLayer.ts
+/**
+* The cascade layer every library stylesheet is wrapped in.
+*
+* The wrapper exists for consumers whose own CSS lives in cascade layers,
+* Tailwind 4 being the common case. Unlayered rules outrank all layered rules,
+* so without a layer of our own even a zero-specificity default beats every
+* utility class. Inside a layer, the defaults can be ranked below the
+* consumer's layers with one declaration written before their own styles load:
+*
+* ```css
+* @layer lottie-react;
+* ```
+*
+* A consumer whose CSS is unlayered needs nothing: unlayered rules beat
+* layered ones, so their styles keep winning as before.
+*
+* Named after the package, like the style precedence, because a name a
+* consumer already associates with the library cannot collide with a layer
+* ladder of their own.
+*/
+const styleLayer = "lottie-react";
+//#endregion
+export { styleLayer };

package/build/animation/stylePrecedence.cjs

@@ -0,0 +1,12 @@
+//#region src/animation/stylePrecedence.ts
+/**
+* How React ranks every stylesheet this library renders.
+*
+* One value for all of them, so they sit together in a block a consumer can
+* rank their own CSS against as a unit. It names the package rather than a
+* position, because React treats a precedence it meets first as lower, so a
+* position would only be right by accident of render order.
+*/
+const stylePrecedence = "lottie-react";
+//#endregion
+exports.stylePrecedence = stylePrecedence;

package/build/animation/stylePrecedence.js

@@ -0,0 +1,12 @@
+//#region src/animation/stylePrecedence.ts
+/**
+* How React ranks every stylesheet this library renders.
+*
+* One value for all of them, so they sit together in a block a consumer can
+* rank their own CSS against as a unit. It names the package rather than a
+* position, because React treats a precedence it meets first as lower, so a
+* position would only be right by accident of render order.
+*/
+const stylePrecedence = "lottie-react";
+//#endregion
+export { stylePrecedence };

package/build/animation/types.cjs

@@ -0,0 +1,71 @@
+//#region src/animation/types.ts
+/**
+* The renderers lottie-web can draw an animation with.
+*
+* `svg` is the default and the only one the smaller builds contain. `canvas`
+* draws to a bitmap, and `html` builds real DOM nodes, which is the only
+* renderer that puts block content inside the display.
+*/
+const LottieRenderer = {
+	svg: "svg",
+	canvas: "canvas",
+	html: "html"
+};
+/**
+* What the animation is doing.
+*
+* `paused` means a person asked it to stop; `frozen` means the library stopped
+* it on the animation's behalf and will start it again. Nothing sets `frozen`
+* yet, and it is declared because adding a member to a union later breaks an
+* exhaustive `switch` in a consumer's code.
+*/
+const LottieState = {
+	loading: "loading",
+	playing: "playing",
+	paused: "paused",
+	stopped: "stopped",
+	frozen: "frozen",
+	error: "error"
+};
+/**
+* Which way the animation plays.
+*
+* lottie-web works in `1` and `-1`, which say nothing to a reader; the
+* translation happens once, where the engine is called.
+*/
+const LottieDirection = {
+	forward: "forward",
+	reverse: "reverse"
+};
+/**
+* Everything a consumer can subscribe to.
+*
+* `frame` is the only one that fires per frame, and it is deliberately the only
+* route to the current frame, because a value that changes sixty times a second
+* cannot be a value without re-rendering at that rate.
+*
+* `marker` announces the playhead passing a marker the animation's designer
+* placed, while it is travelling: a seek or a scrub puts the playhead somewhere
+* without passing anything, so it announces nothing.
+*
+* `ready` carries no payload. Everything that can subscribe already holds the
+* instance, either as the hook's return value or through `useLottieInstance`,
+* so the values it announces are read from there.
+*/
+const LottieSubscription = {
+	ready: "ready",
+	play: "play",
+	pause: "pause",
+	stop: "stop",
+	complete: "complete",
+	loopCompleted: "loopCompleted",
+	frame: "frame",
+	marker: "marker",
+	newState: "newState",
+	error: "error"
+};
+//#endregion
+exports.LottieDirection = LottieDirection;
+exports.LottieRenderer = LottieRenderer;
+exports.LottieState = LottieState;
+exports.LottieSubscription = LottieSubscription;