flet-box 1.1.0 → 1.1.2

package/src/animations/color.js

@@ -0,0 +1,91 @@
+/**
+ * color.js - The one color reader both animation engines use.
+ *
+ * The declarative engine (`AnimatedBox`) and the imperative one (`animate`) each
+ * grew a color mixer, and they disagreed: one parsed hex and `rgb()` and wrote an
+ * unclamped `rgba()`, the other parsed hex only. A caller who moved a working
+ * `from: "rgba(255, 0, 0, 0.4)"` from one to the other got the string `"NaNpx"`
+ * written every frame, which the browser drops silently — the animation looked
+ * like it ran and changed nothing. One parser, one output, both engines.
+ *
+ * @module animations/color
+ */
+
+/**
+ * The channels of a CSS color, or `null` when the value is not a color this
+ * module can blend.
+ *
+ * Hex (3- and 6-digit) and `rgb()`/`rgba()` are the shapes a design token
+ * actually arrives in. A named color (`"tomato"`) is not: blending it needs a
+ * lookup table for 148 names, and the honest answer is to refuse rather than to
+ * interpolate towards black.
+ *
+ * @param {string} value - A hex or `rgb()`/`rgba()` color.
+ * @returns {[number, number, number, number]|null} `[red, green, blue, alpha]`,
+ *   with the channels in `[0, 255]` and alpha in `[0, 1]`.
+ */
+export const parseColor = (value) => {
+  if (typeof value !== "string") return null;
+  const text = value.trim();
+
+  const hex = text.match(/^#?([a-f\d]{3,4}|[a-f\d]{6}|[a-f\d]{8})$/i);
+  if (hex) {
+    const digits = hex[1];
+    if (digits.length <= 4) {
+      // `#rgb` and `#rgba` are the short forms of the same eight digits.
+      const channel = (index) => parseInt(digits[index], 16) * 0x11;
+      const alpha = digits.length === 4 ? parseInt(digits[3], 16) / 255 : 1;
+      return [channel(0), channel(1), channel(2), alpha];
+    }
+    const channel = (offset) => parseInt(digits.slice(offset, offset + 2), 16);
+    const alpha = digits.length === 8 ? channel(6) / 255 : 1;
+    return [channel(0), channel(2), channel(4), alpha];
+  }
+
+  const rgb = text.match(
+    /^rgba?\(\s*([\d.]+)(?:%?)\s*[,\s]\s*([\d.]+)(?:%?)\s*[,\s]\s*([\d.]+)(?:%?)\s*(?:[,/]\s*([\d.]+)\s*%?)?\)$/i,
+  );
+  if (rgb) {
+    const channels = [Number(rgb[1]), Number(rgb[2]), Number(rgb[3])];
+    if (channels.some((n) => !Number.isFinite(n))) return null;
+    const alpha = rgb[4] === undefined ? 1 : Number(rgb[4]);
+    return [...channels, Number.isFinite(alpha) ? alpha : 1];
+  }
+
+  return null;
+};
+
+/**
+ * True when this module knows how to blend the value.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export const isColor = (value) => parseColor(value) !== null;
+
+/**
+ * Linearly interpolates between two CSS colors.
+ *
+ * A curve that overshoots runs past 1, and an `rgb()` channel outside 0–255 makes
+ * the browser drop the whole declaration — the color would blink, not overshoot.
+ * Both channels and alpha are therefore clamped, so the value is always writable.
+ *
+ * @param {string} from   - Starting color (hex or `rgb()`/`rgba()`).
+ * @param {string} to     - Ending color.
+ * @param {number} t      - Interpolation factor; values outside `[0, 1]` are clamped.
+ * @returns {string} The blended color as `"rgba(r, g, b, a)"`, or the starting
+ *   color when either side is not a color this module parses.
+ */
+export const mixColor = (from, to, t) => {
+  const a = parseColor(from);
+  const b = parseColor(to);
+  if (!a || !b) return from;
+  const progress = Math.min(1, Math.max(0, t));
+  const channel = (start, end) =>
+    Math.round(Math.min(255, Math.max(0, start + (end - start) * progress)));
+  const alpha = Math.min(1, Math.max(0, a[3] + (b[3] - a[3]) * progress));
+  return `rgba(${channel(a[0], b[0])}, ${channel(a[1], b[1])}, ${channel(
+    a[2],
+    b[2],
+  )}, ${Number(alpha.toFixed(3))})`;
+};

package/src/animations/easings.js

@@ -0,0 +1,275 @@
+/**
+ * easings.js - The curves the imperative engine knows.
+ *
+ * A curve is the difference between an element arriving and an element being
+ * teleported. Four names (`linear`, `easeIn`, `easeOut`, `easeInOut`) cover
+ * almost nothing, and the gap gets filled by hand-written `requestAnimationFrame`
+ * loops in app code — a second animation system, which this repo already has one
+ * of. So the standard set lives here.
+ *
+ * Two rules the shapes obey:
+ * - An **entrance** decelerates (`easeOut*`, `spring`): it leaves the start line
+ *   fast, which is what reads as responsive.
+ * - Anything the user presses repeatedly either has no curve at all (no
+ *   animation) or a short `easeOut`; `easeIn*` starts slow and feels broken.
+ *
+ * Overshoot curves (`*Back`, `Elastic`, `Bounce`, an underdamped spring) return
+ * values outside `[0, 1]`. That is the point — the element travels slightly past
+ * its resting place — and every consumer handles it: numbers and units
+ * extrapolate, colors clamp, `scale` accepts any positive factor.
+ *
+ * @module animations/easings
+ */
+
+/**
+ * Overshoot amount for the `Back` family — 1.70158 is the value the CSS easing
+ * community settled on (`1.70158 * 1.525` for the in-out variant).
+ * @type {number}
+ */
+const BACK_OVERSHOOT = 1.70158;
+
+/**
+ * Solves a cubic Bézier timing function for x, using Newton-Raphson with a
+ * bisection fallback, and returns the curve as an easing function.
+ *
+ * This is the bridge between the two easing vocabularies in the framework:
+ * `AnimatedBox({ timing })` and `ParallaxBox({ easing })` hand a string to CSS,
+ * while `animate(..., easing)` reads a name. `cubicBezier()` gives the imperative
+ * side the exact curve a stylesheet would use, so a screen can share one motion
+ * language across declarative and imperative motion.
+ *
+ * @param {number} x1 - First control point x (must be in `[0, 1]`).
+ * @param {number} y1 - First control point y (any value; >1 overshoots).
+ * @param {number} x2 - Second control point x (must be in `[0, 1]`).
+ * @param {number} y2 - Second control point y.
+ * @returns {(t: number) => number} Easing function, `t` in `[0, 1]`.
+ */
+export const cubicBezier = (x1, y1, x2, y2) => {
+  const px = (t) => 3 * t * (1 - t) * (1 - t) * x1 + 3 * t * t * (1 - t) * x2 + t * t * t;
+  const py = (t) => 3 * t * (1 - t) * (1 - t) * y1 + 3 * t * t * (1 - t) * y2 + t * t * t;
+  // Derivative of px, used to walk the parameter toward the requested x.
+  const dx = (t) =>
+    3 * (1 - t) * (1 - t) * x1 + 6 * t * (1 - t) * (x2 - x1) + 3 * t * t * (1 - x2);
+
+  return (progress) => {
+    if (!(progress > 0)) return 0;
+    if (progress >= 1) return 1;
+    let parameter = progress;
+    for (let i = 0; i < 8; i++) {
+      const error = px(parameter) - progress;
+      if (Math.abs(error) < 1e-5) return py(parameter);
+      const slope = dx(parameter);
+      if (Math.abs(slope) < 1e-6) break;
+      parameter -= error / slope;
+    }
+    // Newton wandered off the curve; bisect between the ends, which cannot fail.
+    let low = 0;
+    let high = 1;
+    parameter = progress;
+    for (let i = 0; i < 20; i++) {
+      const value = px(parameter);
+      if (Math.abs(value - progress) < 1e-5) break;
+      if (value > progress) high = parameter;
+      else low = parameter;
+      parameter = (low + high) / 2;
+    }
+    return py(parameter);
+  };
+};
+
+/**
+ * The named curves `animate()`, `animateAsync()` and the presets accept.
+ * Read off the standard Penner set, plus the four Material timing shapes.
+ *
+ * `easeIn` / `easeOut` / `easeInOut` keep their original quadratic shapes so any
+ * animation already in an app moves exactly as it did before.
+ *
+ * @type {Object<string, (t: number) => number>}
+ */
+export const EASINGS = {
+  linear: (t) => t,
+
+  easeIn: (t) => t * t,
+  easeOut: (t) => t * (2 - t),
+  easeInOut: (t) => (t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t),
+
+  easeInCubic: (t) => t * t * t,
+  easeOutCubic: (t) => 1 - (1 - t) ** 3,
+  easeInOutCubic: (t) =>
+    t < 0.5 ? 4 * t * t * t : 1 - (-2 * t + 2) ** 3 / 2,
+
+  easeInQuart: (t) => t ** 4,
+  easeOutQuart: (t) => 1 - (1 - t) ** 4,
+  easeInOutQuart: (t) => (t < 0.5 ? 8 * t ** 4 : 1 - (-2 * t + 2) ** 4 / 2),
+
+  easeInExpo: (t) => (t === 0 ? 0 : 2 ** (10 * t - 10)),
+  easeOutExpo: (t) => (t === 1 ? 1 : 1 - 2 ** (-10 * t)),
+  easeInOutExpo: (t) =>
+    t === 0 || t === 1
+      ? t
+      : t < 0.5
+        ? 2 ** (20 * t - 10) / 2
+        : (2 - 2 ** (-20 * t + 10)) / 2,
+
+  easeInCirc: (t) => 1 - Math.sqrt(1 - t * t),
+  easeOutCirc: (t) => Math.sqrt(1 - (t - 1) ** 2),
+  easeInOutCirc: (t) =>
+    t < 0.5
+      ? (1 - Math.sqrt(1 - (2 * t) ** 2)) / 2
+      : (Math.sqrt(1 - (-2 * t + 2) ** 2) + 1) / 2,
+
+  easeInBack: (t) => (BACK_OVERSHOOT + 1) * t ** 3 - BACK_OVERSHOOT * t * t,
+  easeOutBack: (t) =>
+    1 + (BACK_OVERSHOOT + 1) * (t - 1) ** 3 + BACK_OVERSHOOT * (t - 1) ** 2,
+  easeInOutBack: (t) => {
+    const c = BACK_OVERSHOOT * 1.525;
+    return t < 0.5
+      ? ((2 * t) ** 2 * ((c + 1) * 2 * t - c)) / 2
+      : ((2 * t - 2) ** 2 * ((c + 1) * (2 * t - 2) + c) + 2) / 2;
+  },
+
+  easeInElastic: (t) => {
+    if (t === 0 || t === 1) return t;
+    const c4 = (2 * Math.PI) / 3;
+    return -(2 ** (10 * t - 10)) * Math.sin((t * 10 - 10.75) * c4);
+  },
+  easeOutElastic: (t) => {
+    if (t === 0 || t === 1) return t;
+    const c4 = (2 * Math.PI) / 3;
+    return 2 ** (-10 * t) * Math.sin((t * 10 - 0.75) * c4) + 1;
+  },
+  easeOutBounce: (t) => {
+    const n1 = 7.5625;
+    const d1 = 2.75;
+    if (t < 1 / d1) return n1 * t * t;
+    if (t < 2 / d1) return n1 * (t - 1.5 / d1) ** 2 + 0.75;
+    if (t < 2.5 / d1) return n1 * (t - 2.25 / d1) ** 2 + 0.9375;
+    return n1 * (t - 2.625 / d1) ** 2 + 0.984375;
+  },
+
+  // Material 3 shapes, as the curves rather than the CSS strings, so an
+  // imperative call can match a stylesheet on the same screen.
+  standard: cubicBezier(0.2, 0, 0, 1),
+  emphasized: cubicBezier(0.3, 0, 0.1, 1),
+  emphasizedDecelerate: cubicBezier(0.05, 0.7, 0.1, 1),
+  emphasizedAccelerate: cubicBezier(0.3, 0, 0.8, 0.15),
+};
+
+/**
+ * Every accepted easing name, in the order they are documented.
+ * @type {string[]}
+ */
+export const EASING_NAMES = Object.keys(EASINGS);
+
+/**
+ * Resolves whatever a caller passed as `easing` into a curve.
+ *
+ * A function is used as given — that is how a `spring()` or a `cubicBezier()`
+ * reaches `animate()`. An unknown name falls back to `linear` with a warning:
+ * silently linear is how a hand-typed `'ease-out'` (a CSS name, not a framework
+ * one) ends up moving like a machine on a screen that was supposed to glide.
+ *
+ * @param {string|((t: number) => number)} [easing] - A name or a curve.
+ * @returns {(t: number) => number}
+ */
+export const resolveEasing = (easing) => {
+  if (typeof easing === "function") return easing;
+  if (easing === undefined || easing === null || easing === "") return EASINGS.linear;
+  const curve = EASINGS[easing];
+  if (!curve) {
+    console.warn(
+      `⚠️ [easings] "${easing}" is not a FletBox easing. Known names: ${EASING_NAMES.join(", ")}. Falling back to "linear". Note that CSS names ("ease-out") and cubic-bezier() strings belong to AnimatedBox({ timing }), not here.`,
+    );
+    return EASINGS.linear;
+  }
+  return curve;
+};
+
+/**
+ * A damped harmonic oscillator: the curve a real object follows when it is
+ * pulled to a target and released.
+ *
+ * Springs are why an interface feels physical instead of scripted — the movement
+ * has no fixed end time, it settles. That also makes them the one thing a
+ * duration-based API cannot express, so `spring()` returns both halves: the curve
+ * and the duration it needs to settle within `epsilon`.
+ *
+ * @param {object}  [options]
+ * @param {number}  [options.stiffness=170] - Spring constant `k`. Higher snaps.
+ * @param {number}  [options.damping=26]    - Damping `c`. Lower keeps bouncing.
+ * @param {number}  [options.mass=1]        - Mass `m`. Heavier lags.
+ * @param {number}  [options.initialVelocity=0] - Starting velocity; a flick hands
+ *   the spring the pointer's speed so the entrance continues the gesture.
+ * @param {number}  [options.epsilon=0.001] - How close to the target counts as settled.
+ * @param {number}  [options.maxDuration=2000] - Ceiling, in ms: an underdamped
+ *   spring with a lot of energy is still not a 4s modal.
+ * @returns {{ easing: (t: number) => number, duration: number, overshoot: boolean }}
+ *   `easing` is a function, so it goes straight into `animate(...)`'s last
+ *   argument; `duration` is the `animate(...)` duration to pass with it.
+ */
+export const spring = ({
+  stiffness = 170,
+  damping = 26,
+  mass = 1,
+  initialVelocity = 0,
+  epsilon = 0.001,
+  maxDuration = 2000,
+} = {}) => {
+  const k = Math.max(0.0001, Number(stiffness) || 0);
+  const c = Math.max(0, Number(damping) || 0);
+  const m = Math.max(0.0001, Number(mass) || 0);
+  const v0 = Number(initialVelocity) || 0;
+  const eps = Math.min(0.5, Math.max(0.000001, Number(epsilon) || 0.001));
+
+  const omega0 = Math.sqrt(k / m);
+  const zeta = c / (2 * Math.sqrt(k * m));
+
+  // The unit-step response: 0 at t = 0, 1 once settled, with the overshoot the
+  // damping allows in between. Each branch is the closed form for that regime.
+  const position = (seconds) => {
+    if (seconds <= 0) return 0;
+    if (zeta < 1) {
+      const omegaD = omega0 * Math.sqrt(1 - zeta * zeta);
+      const envelope = Math.exp(-zeta * omega0 * seconds);
+      return (
+        1 -
+        envelope *
+          (Math.cos(omegaD * seconds) +
+            ((zeta * omega0 - v0) / omegaD) * Math.sin(omegaD * seconds))
+      );
+    }
+    if (zeta === 1) {
+      const envelope = Math.exp(-omega0 * seconds);
+      return 1 - envelope * (1 + (omega0 - v0) * seconds);
+    }
+    const root = omega0 * Math.sqrt(zeta * zeta - 1);
+    const r1 = -zeta * omega0 + root;
+    const r2 = -zeta * omega0 - root;
+    const c1 = (r2 - v0) / (r2 - r1);
+    const c2 = (v0 - r1) / (r2 - r1);
+    return 1 - (c1 * Math.exp(r1 * seconds) + c2 * Math.exp(r2 * seconds));
+  };
+
+  // Time for the exponential envelope to fall inside epsilon. The overdamped
+  // tail is slower than its envelope, so solve that branch numerically instead.
+  const settleSeconds = () => {
+    if (zeta > 0) {
+      const estimate = -Math.log(eps) / (zeta * omega0);
+      if (zeta < 1) return estimate;
+    }
+    let seconds = 0.001;
+    while (seconds < 10 && Math.abs(position(seconds) - 1) > eps) seconds += 0.001;
+    return seconds;
+  };
+
+  const duration = Math.min(
+    Math.max(1, Math.round(settleSeconds() * 1000)),
+    Math.max(1, Number(maxDuration) || 2000),
+  );
+
+  return {
+    easing: (progress) => (progress >= 1 ? 1 : position(progress * (duration / 1000))),
+    duration,
+    overshoot: zeta < 1,
+  };
+};

package/src/animations/index.js

@@ -16,6 +16,8 @@ export { MatrixRain } from "./MatrixRain.js";
 export {
 	animate,
 	animateAsync,
+	animateSpring,
+	animateSpringAsync,
 	stopAnimation,
 	fadeOut,
 	fadeIn,
@@ -24,3 +26,22 @@ export {
 	fadeInAsync,
 	pulseAsync,
 } from "./animate.js";
+export {
+	slideIn,
+	slideInAsync,
+	slideOut,
+	slideOutAsync,
+	popIn,
+	popInAsync,
+	shake,
+	shakeAsync,
+} from "./transitions.js";
+export {
+	prefersReducedMotion,
+	getMotionMode,
+	setMotionMode,
+	onMotionModeChange,
+	motionDuration,
+	stagger,
+} from "./motion.js";
+export { EASING_NAMES, cubicBezier, spring } from "./easings.js";

package/src/animations/motion.js

@@ -0,0 +1,204 @@
+/**
+ * motion.js - The one motion preference the whole app shares.
+ *
+ * `prefers-reduced-motion` is a real accessibility requirement, not a style
+ * note: vestibular disorders make parallax, spin and large-scale movement
+ * physically unpleasant. FletBox answers it at the engine level rather than in
+ * each widget, because an animation that asks the widget to opt in is an
+ * animation that ships without the check.
+ *
+ * Three modes:
+ * - `"auto"` (default) — follow the operating system.
+ * - `"reduce"` — no movement, regardless of what the OS says.
+ * - `"full"` — always animate, for an app that owns a "motion" setting.
+ *
+ * `markMotionLoop(element)` is the shared hook for anything that writes a CSS
+ * `animation`: a JS check is read at build time and cannot reach a loop already
+ * running, so the preference is also answered by one injected media rule.
+ *
+ * Everything here is lazy: `window` and `matchMedia` are touched inside the
+ * functions, never at module scope, so `flet-box` stays importable in Node.
+ *
+ * @module animations/motion
+ */
+
+const MODES = new Set(["auto", "reduce", "full"]);
+
+/**
+ * The mode an app or the previous conversation settled on. `auto` means
+ * "whatever the system says", which is what a screen shipped without an
+ * opinion about motion should do.
+ * @type {"auto"|"reduce"|"full"}
+ */
+let mode = "auto";
+
+/**
+ * Listeners notified when the mode changes, so a widget holding a live loop can
+ * stop it the moment the user turns motion off instead of waiting to unmount.
+ * @type {Set<(reduced: boolean) => void>}
+ */
+const listeners = new Set();
+
+/** Cached `MediaQueryList` for the system preference, created on first read. */
+let systemQuery = null;
+
+/**
+ * Reads the system preference, wiring the change listener once.
+ *
+ * @returns {boolean} True when the OS asks for reduced motion.
+ */
+const systemPrefersReduce = () => {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return false;
+  }
+  if (!systemQuery) {
+    systemQuery = window.matchMedia("(prefers-reduced-motion: reduce)");
+    // The user can flip the OS setting while the app is open; notifying keeps
+    // `prefersReducedMotion()` honest without a poll.
+    if (typeof systemQuery.addEventListener === "function") {
+      systemQuery.addEventListener("change", () => notify());
+    }
+  }
+  return systemQuery.matches === true;
+};
+
+/**
+ * @param {boolean} reduced - The value every listener should now act on.
+ * @returns {void}
+ */
+const notify = (reduced) => {
+  const value = reduced === undefined ? prefersReducedMotion() : reduced;
+  listeners.forEach((listener) => {
+    try {
+      listener(value);
+    } catch (error) {
+      console.warn("⚠️ [motion] A motion-mode listener threw:", error);
+    }
+  });
+};
+
+/**
+ * Whether anything animated right now should skip its movement.
+ *
+ * @returns {boolean} True for `"reduce"`, and for `"auto"` when the system asks.
+ */
+export const prefersReducedMotion = () =>
+  mode === "reduce" || (mode === "auto" && systemPrefersReduce());
+
+/**
+ * The active mode.
+ *
+ * @returns {"auto"|"reduce"|"full"}
+ */
+export const getMotionMode = () => mode;
+
+/**
+ * Sets the app-wide motion mode.
+ *
+ * `"reduce"` is what a settings switch turns on; `"full"` is what an app with an
+ * "animations" toggle turns on for a user who wants motion even though their OS
+ * says otherwise. Anything unrecognized leaves the mode untouched and warns.
+ *
+ * @param {"auto"|"reduce"|"full"} next - The mode to apply.
+ * @returns {"auto"|"reduce"|"full"} The mode now in effect.
+ */
+export const setMotionMode = (next) => {
+  if (!MODES.has(next)) {
+    console.warn(
+      `⚠️ [motion] Unknown motion mode "${next}". Use "auto", "reduce" or "full".`,
+    );
+    return mode;
+  }
+  if (next === mode) return mode;
+  mode = next;
+  notify();
+  return mode;
+};
+
+/**
+ * Subscribes to motion-mode changes (including the system flipping its own
+ * setting while the app is open).
+ *
+ * @param {(reduced: boolean) => void} listener - Called with the new answer.
+ * @returns {() => void} Unsubscribe — call it from the widget's `onUnmount`.
+ */
+export const onMotionModeChange = (listener) => {
+  if (typeof listener !== "function") return () => {};
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+};
+
+/**
+ * The `id` of the one stylesheet that answers the operating-system preference.
+ * @type {string}
+ */
+const REDUCED_MOTION_RULE_ID = "fletbox-reduced-motion";
+
+/**
+ * Marks an element as carrying a CSS animation, and injects — once — the media
+ * rule that stops every such animation when the reader asks for reduced motion.
+ *
+ * A JS check is read when the widget builds, so it cannot reach an element that
+ * is already looping. The OS preference can flip mid-session, and this rule is
+ * the browser answering live, with no listener to register and none to leak.
+ * The JS path stays: it is what covers an app's own `setMotionMode('reduce')`,
+ * which CSS cannot see.
+ *
+ * @param {HTMLElement} element - The element about to be given a CSS animation.
+ * @returns {void}
+ */
+export const markMotionLoop = (element) => {
+  if (!element || typeof element.setAttribute !== "function") return;
+  element.setAttribute("data-fb-anim", "");
+  if (typeof document === "undefined") return;
+  if (document.getElementById(REDUCED_MOTION_RULE_ID)) return;
+  const style = document.createElement("style");
+  style.id = REDUCED_MOTION_RULE_ID;
+  style.textContent = `@media (prefers-reduced-motion: reduce) {
+  [data-fb-anim] {
+    animation-duration: 0.01ms !important;
+    animation-delay: 0s !important;
+    animation-iteration-count: 1 !important;
+  }
+}`;
+  document.head.appendChild(style);
+};
+
+/**
+ * The duration an animation should actually run under the current mode.
+ *
+ * `0` is not a shortcut for "skip it": the engine's single frame writes the end
+ * value and resolves, so a state change still lands where the caller expects it
+ * and an `await` never hangs. Only the movement disappears.
+ *
+ * @param {number} duration - The duration the caller asked for, in ms.
+ * @returns {number} `0` when motion is reduced, otherwise `duration` sanitized.
+ */
+export const motionDuration = (duration) => {
+  const safe = Math.max(0, Number(duration) || 0);
+  return prefersReducedMotion() ? 0 : safe;
+};
+
+/**
+ * The delay for item `index` of an entrance, capped so a long list cannot turn
+ * into a wait.
+ *
+ * Staggering is the difference between a screen arriving and a screen loading,
+ * and the failure mode is arithmetic: 20 rows at 60ms is a 1.2s entrance. Beyond
+ * `max` every item shares the same delay, so the tail appears at once.
+ *
+ * @param {number} index             - Position in the list, 0-based.
+ * @param {object}  [options]
+ * @param {number}  [options.start=0]  - Delay the first item gets, in ms.
+ * @param {number}  [options.step=60]  - Extra delay per item, in ms.
+ * @param {number}  [options.max=8]    - Index past which the delay stops growing.
+ * @returns {number} Delay in ms, ready to use as an `animations[].delay` or a
+ *   `setTimeout` argument.
+ */
+export const stagger = (index, { start = 0, step = 60, max = 8 } = {}) => {
+  const position = Math.max(0, Number(index) || 0);
+  const capped = Math.min(position, Math.max(0, Number(max) || 0));
+  const safeStart = Math.max(0, Number(start) || 0);
+  const safeStep = Math.max(0, Number(step) || 0);
+  return safeStart + capped * safeStep;
+};