jfs-components 0.0.73 → 0.0.77

package/lib/commonjs/index.js

@@ -57,4 +57,16 @@ Object.keys(_utils).forEach(function (key) {
     }
   });
 });
+var _skeleton = require("./skeleton");
+Object.keys(_skeleton).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _skeleton[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _skeleton[key];
+    }
+  });
+});
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }

package/lib/commonjs/skeleton/Skeleton.js

@@ -0,0 +1,234 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _react = _interopRequireWildcard(require("react"));
+var _reactNative = require("react-native");
+var _reactNativeReanimated = _interopRequireWildcard(require("react-native-reanimated"));
+var _reactNativeSvg = _interopRequireWildcard(require("react-native-svg"));
+var _figmaVariablesResolver = require("../design-tokens/figma-variables-resolver");
+var _shimmerTokens = require("./shimmer-tokens");
+var _SkeletonGroup = require("./SkeletonGroup");
+var _jsxRuntime = require("react/jsx-runtime");
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
+// Solid-white overlay used by reduced-motion mode (also acts as the safe
+// fallback when SVG can't render or when the box hasn't been measured yet).
+// Allocated once at module scope so per-render allocation is zero.
+const SOLID_OVERLAY_COLOR = 'rgba(255, 255, 255, 1)';
+
+// `pointerEvents: 'none'` lives on the style (not the deprecated prop) so it
+// works on both native and React Native Web without warnings.
+const absoluteFillStyle = {
+  ..._reactNative.StyleSheet.absoluteFillObject,
+  overflow: 'hidden',
+  pointerEvents: 'none'
+};
+const solidOverlayStyle = {
+  ..._reactNative.StyleSheet.absoluteFillObject,
+  backgroundColor: SOLID_OVERLAY_COLOR
+};
+
+/**
+ * Atomic skeleton placeholder. Renders a base rectangle (background colour +
+ * radius per kind) plus an animated overlay that produces the shimmer.
+ *
+ * Two visual modes share the same engine:
+ *
+ *   - Normal mode (gradient: true): a soft 135° band translates diagonally
+ *     across the box end-to-end. Its alpha inside the moving band varies
+ *     33% → 100% → 33% via gradient stops. The sawtooth clock travels from
+ *     fully off-screen (−overshoot) to fully off-screen (+overshoot) so the
+ *     transparent gradient tails clear the box before the loop resets.
+ *
+ *   - Reduced-motion mode (gradient: false): a solid white overlay covers the
+ *     box and pulses opacity 33% → 100% → 33% in place, with no translation,
+ *     ease-in-out timing and no stagger.
+ *
+ * Critical for cross-platform consistency:
+ *
+ *   - The SVG gradient uses `gradientUnits="userSpaceOnUse"` with absolute
+ *     pixel coordinates that have Δx === Δy. This guarantees the visual angle
+ *     is exactly 45° in screen pixels (= 135° CSS) on ANY aspect ratio. With
+ *     the default `objectBoundingBox` units, the gradient line is normalised
+ *     to the box and tilts off-angle on non-square boxes.
+ *
+ *   - The whole animated overlay sits inside a clipping parent (`overflow:
+ *     hidden` + `borderRadius`). Translating an `Animated.View` is GPU-cheap
+ *     on both iOS/Android (Reanimated UI thread) and on web (CSS transforms).
+ *
+ *   - The SVG `id` for the gradient is per-instance (`useId`) so multiple
+ *     skeletons on a web page don't collide on `url(#…)` resolution.
+ */
+function SkeletonImpl({
+  kind = 'other',
+  width,
+  height,
+  style,
+  modes
+}) {
+  const {
+    active,
+    reducedMotion,
+    clock
+  } = (0, _SkeletonGroup.useSkeleton)();
+  const index = (0, _SkeletonGroup.useStaggerIndex)();
+  const reactId = (0, _react.useId)();
+  // SVG ids must match `^[A-Za-z][A-Za-z0-9_.-]*$`; React's useId returns
+  // colons which are illegal in fragment refs, so strip them.
+  const gradientId = `jfsSkeletonGradient-${reactId.replace(/[^A-Za-z0-9_-]/g, '')}`;
+
+  // Measured pixel size of the base box. The moving shimmer geometry depends
+  // on real layout so we capture it via onLayout. Before the first layout
+  // pass W and H are 0 and we render no overlay (the next render after layout
+  // fills it in).
+  const [layout, setLayout] = (0, _react.useState)({
+    width: 0,
+    height: 0
+  });
+  const radiusTokenName = _shimmerTokens.SKELETON_TOKEN.radius[kind];
+  const radius = (0, _figmaVariablesResolver.getVariableByName)(radiusTokenName, modes ?? {}) ?? _shimmerTokens.SKELETON_FALLBACK.radius[kind];
+  const backgroundColor = (0, _figmaVariablesResolver.getVariableByName)(_shimmerTokens.SKELETON_TOKEN.background, modes ?? {}) ?? _shimmerTokens.SKELETON_FALLBACK.backgroundColor;
+  const spec = reducedMotion ? _shimmerTokens.SHIMMER.reduced : _shimmerTokens.SHIMMER.normal;
+  // Convert the per-item stagger into a phase offset in [0, 1) (relative to
+  // one cycle). The sawtooth clock means a phase shift simply slides the
+  // start point of each skeleton's sweep, producing the cascade.
+  const phaseOffset = spec.durationMs > 0 ? (0, _shimmerTokens.staggerDelayMs)(index, spec) / spec.durationMs : 0;
+  const baseStyle = (0, _react.useMemo)(() => ({
+    backgroundColor,
+    borderRadius: radius,
+    overflow: 'hidden',
+    ...(width !== undefined ? {
+      width
+    } : {}),
+    ...(height !== undefined ? {
+      height
+    } : {})
+  }), [backgroundColor, radius, width, height]);
+
+  // --- Moving-shimmer geometry --------------------------------------------
+  //
+  // Overlay is 2× the box diagonal so the gradient still covers the clipped
+  // area at extreme translations. Overshoot (travel beyond each corner) is
+  // derived from the gradient stop layout via `computeShimmerMotion`.
+  const W = layout.width;
+  const H = layout.height;
+  const diag = Math.sqrt(W * W + H * H);
+  const overlaySize = diag * 2;
+  const motion = (0, _react.useMemo)(() => (0, _shimmerTokens.computeShimmerMotion)(W, H, overlaySize, _shimmerTokens.SHIMMER_GRADIENT_STOPS), [W, H, overlaySize]);
+  const padX = motion?.padX ?? 0;
+  const padY = motion?.padY ?? 0;
+  const kStart = motion?.kStart ?? 0;
+  const kEnd = motion?.kEnd ?? 0;
+  const kTravel = kEnd - kStart;
+  const overlayAnimatedStyle = (0, _reactNativeReanimated.useAnimatedStyle)(() => {
+    const t = (clock.value + phaseOffset) % 1;
+    if (spec.gradient) {
+      if (kTravel === 0) {
+        // Pre-layout: keep the overlay invisible so we don't flash a
+        // mis-sized gradient before onLayout fires.
+        return {
+          transform: [{
+            translateX: 0
+          }, {
+            translateY: 0
+          }],
+          opacity: 0
+        };
+      }
+      // Linear sawtooth: t = 0 → fully before entry, t = 1 → fully after exit.
+      // Equivalent to normalised phase p = −O + t·(1 + 2O) where O is the
+      // gradient-derived overshoot fraction from `computeShimmerMotion`.
+      const k = kStart + t * kTravel;
+      return {
+        transform: [{
+          translateX: k
+        }, {
+          translateY: k
+        }],
+        opacity: 1
+      };
+    }
+    // Reduced motion: stationary solid overlay, opacity triangle wave.
+    const wave = t < 0.5 ? t * 2 : (1 - t) * 2;
+    const [lo, hi] = spec.opacityRange;
+    return {
+      transform: [{
+        translateX: 0
+      }, {
+        translateY: 0
+      }],
+      opacity: (0, _reactNativeReanimated.interpolate)(wave, [0, 1], [lo, hi])
+    };
+  }, [phaseOffset, kStart, kTravel, spec.gradient, spec.opacityRange[0], spec.opacityRange[1]]);
+  const gradientOverlayContainerStyle = (0, _react.useMemo)(() => ({
+    position: 'absolute',
+    left: -padX,
+    top: -padY,
+    width: overlaySize,
+    height: overlaySize,
+    pointerEvents: 'none'
+  }), [padX, padY, overlaySize]);
+  if (!active) {
+    // Render nothing when the group is inactive. This lets users sprinkle
+    // <Skeleton /> blocks unconditionally inside their loaded UI without
+    // having to manually gate them — only the active group flips them on.
+    return null;
+  }
+  const onLayout = e => {
+    const {
+      width: w,
+      height: h
+    } = e.nativeEvent.layout;
+    if (w !== layout.width || h !== layout.height) {
+      setLayout({
+        width: w,
+        height: h
+      });
+    }
+  };
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+    style: [baseStyle, style],
+    accessibilityElementsHidden: true,
+    importantForAccessibility: "no-hide-descendants"
+    // Screen readers announce a loading state once via the group's owner;
+    // each individual skeleton is purely decorative.
+    ,
+    accessibilityRole: "none",
+    onLayout: onLayout,
+    children: spec.gradient ? layout.width > 0 ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNativeReanimated.default.View, {
+      style: [gradientOverlayContainerStyle, overlayAnimatedStyle],
+      children: /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNativeSvg.default, {
+        width: overlaySize,
+        height: overlaySize,
+        children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNativeSvg.Defs, {
+          children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNativeSvg.LinearGradient, {
+            id: gradientId,
+            x1: 0,
+            y1: 0,
+            x2: overlaySize,
+            y2: overlaySize,
+            gradientUnits: "userSpaceOnUse",
+            children: _shimmerTokens.SHIMMER_GRADIENT_STOPS.map((stop, i) => /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNativeSvg.Stop, {
+              offset: String(stop.offset),
+              stopColor: "#ffffff",
+              stopOpacity: stop.opacity
+            }, `${stop.offset}-${i}`))
+          })
+        }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNativeSvg.Rect, {
+          width: overlaySize,
+          height: overlaySize,
+          fill: `url(#${gradientId})`
+        })]
+      })
+    }) : null : /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNativeReanimated.default.View, {
+      style: [absoluteFillStyle, overlayAnimatedStyle],
+      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+        style: solidOverlayStyle
+      })
+    })
+  });
+}
+const Skeleton = /*#__PURE__*/_react.default.memo(SkeletonImpl);
+var _default = exports.default = Skeleton;

package/lib/commonjs/skeleton/SkeletonGroup.js

@@ -0,0 +1,140 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.SkeletonGroup = SkeletonGroup;
+exports.useSkeleton = useSkeleton;
+exports.useStaggerIndex = useStaggerIndex;
+var _react = _interopRequireWildcard(require("react"));
+var _reactNativeReanimated = require("react-native-reanimated");
+var _shimmerTokens = require("./shimmer-tokens");
+var _useReducedMotion = require("./useReducedMotion");
+var _jsxRuntime = require("react/jsx-runtime");
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
+/**
+ * Shape of the value carried by the SkeletonContext.
+ *
+ * The provider owns ONE Reanimated shared value per group; every child
+ * `<Skeleton>` reads it on the UI thread and computes its own opacity from
+ * `(clock + perItemPhaseOffset)`. That keeps per-skeleton work bounded to a
+ * single `useAnimatedStyle` and avoids per-block JS timers.
+ */
+
+const SkeletonContext = /*#__PURE__*/(0, _react.createContext)(null);
+/**
+ * Provider that flips an entire subtree into "loading" mode and supplies the
+ * shared shimmer clock + stagger index source to every descendant skeleton.
+ *
+ * Usage:
+ *   ```tsx
+ *   <SkeletonGroup loading={!data}>
+ *     <Card>...JFS primitives auto-skeletonize...</Card>
+ *   </SkeletonGroup>
+ *   ```
+ *
+ * Nesting is supported — an inner `<SkeletonGroup>` fully overrides the
+ * outer one for its subtree (its own clock, its own index counter).
+ */
+function SkeletonGroup({
+  loading,
+  reducedMotion: reducedMotionOverride,
+  children
+}) {
+  const systemReducedMotion = (0, _useReducedMotion.useReducedMotion)();
+  const reducedMotion = reducedMotionOverride ?? systemReducedMotion;
+  const clock = (0, _reactNativeReanimated.useSharedValue)(0);
+
+  // The duration depends on whether we're in reduced-motion mode; we
+  // intentionally restart the loop when either `loading` or `reducedMotion`
+  // changes so the new timing takes effect immediately.
+  (0, _react.useEffect)(() => {
+    if (!loading) {
+      (0, _reactNativeReanimated.cancelAnimation)(clock);
+      clock.value = 0;
+      return;
+    }
+    const spec = reducedMotion ? _shimmerTokens.SHIMMER.reduced : _shimmerTokens.SHIMMER.normal;
+    const easing = reducedMotion ? _reactNativeReanimated.Easing.inOut(_reactNativeReanimated.Easing.ease) : _reactNativeReanimated.Easing.linear;
+    clock.value = 0;
+    // Sawtooth loop (third arg = false). One-way ramp 0 -> 1, reset, repeat.
+    // The moving shimmer band traverses the box on each 0 -> 1 ramp; with the
+    // band's gradient fully faded at both extremes of the sweep, the reset is
+    // visually imperceptible.
+    clock.value = (0, _reactNativeReanimated.withRepeat)((0, _reactNativeReanimated.withTiming)(1, {
+      duration: spec.durationMs,
+      easing
+    }), -1, false);
+    return () => {
+      (0, _reactNativeReanimated.cancelAnimation)(clock);
+    };
+  }, [loading, reducedMotion, clock]);
+
+  // Stagger index counter — reset on each (re)mount so reorders and toggles
+  // get a fresh, deterministic ordering. The counter lives in a ref so
+  // React's commit phase doesn't shuffle it.
+  const indexRef = (0, _react.useRef)(0);
+  // Reset whenever loading flips on, so a freshly-displayed group cascades
+  // from index 0 again rather than picking up stale numbers.
+  (0, _react.useEffect)(() => {
+    if (loading) indexRef.current = 0;
+  }, [loading]);
+  const value = (0, _react.useMemo)(() => ({
+    active: loading,
+    reducedMotion,
+    clock,
+    nextIndex: () => {
+      const i = indexRef.current;
+      indexRef.current = i + 1;
+      return i;
+    }
+  }), [loading, reducedMotion, clock]);
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(SkeletonContext.Provider, {
+    value: value,
+    children: children
+  });
+}
+
+/**
+ * Internal hook used by skeleton-aware primitives (and by `<Skeleton>`
+ * itself) to read the surrounding context.
+ *
+ * Always returns a non-null value: when called outside any provider, the
+ * returned object has `active: false` so the consumer falls through to its
+ * normal render path. The fallback clock is a no-op shared value so any
+ * direct `<Skeleton>` usage outside a group still has something safe to read.
+ */
+function useSkeleton() {
+  const ctx = (0, _react.useContext)(SkeletonContext);
+  // Hook order must be stable — always allocate the fallback even when ctx
+  // exists; React only reads from `ctx` when it's non-null below.
+  const fallbackClock = (0, _reactNativeReanimated.useSharedValue)(0);
+  const fallbackIndexRef = (0, _react.useRef)(0);
+  const fallback = (0, _react.useMemo)(() => ({
+    active: false,
+    reducedMotion: false,
+    clock: fallbackClock,
+    nextIndex: () => {
+      const i = fallbackIndexRef.current;
+      fallbackIndexRef.current = i + 1;
+      return i;
+    }
+  }), [fallbackClock]);
+  return ctx ?? fallback;
+}
+
+/**
+ * Convenience wrapper around `useSkeleton().nextIndex()` that pins the
+ * returned value across re-renders. Each `<Skeleton>` calls this once on
+ * mount; subsequent renders re-use the same index from the closure.
+ */
+function useStaggerIndex() {
+  const {
+    nextIndex
+  } = useSkeleton();
+  const indexRef = (0, _react.useRef)(null);
+  if (indexRef.current === null) {
+    indexRef.current = nextIndex();
+  }
+  return indexRef.current;
+}

package/lib/commonjs/skeleton/index.js

@@ -0,0 +1,58 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "SHIMMER", {
+  enumerable: true,
+  get: function () {
+    return _shimmerTokens.SHIMMER;
+  }
+});
+Object.defineProperty(exports, "SKELETON_FALLBACK", {
+  enumerable: true,
+  get: function () {
+    return _shimmerTokens.SKELETON_FALLBACK;
+  }
+});
+Object.defineProperty(exports, "SKELETON_TOKEN", {
+  enumerable: true,
+  get: function () {
+    return _shimmerTokens.SKELETON_TOKEN;
+  }
+});
+Object.defineProperty(exports, "Skeleton", {
+  enumerable: true,
+  get: function () {
+    return _Skeleton.default;
+  }
+});
+Object.defineProperty(exports, "SkeletonGroup", {
+  enumerable: true,
+  get: function () {
+    return _SkeletonGroup.SkeletonGroup;
+  }
+});
+Object.defineProperty(exports, "useReducedMotion", {
+  enumerable: true,
+  get: function () {
+    return _useReducedMotion.useReducedMotion;
+  }
+});
+Object.defineProperty(exports, "useSkeleton", {
+  enumerable: true,
+  get: function () {
+    return _SkeletonGroup.useSkeleton;
+  }
+});
+Object.defineProperty(exports, "useStaggerIndex", {
+  enumerable: true,
+  get: function () {
+    return _SkeletonGroup.useStaggerIndex;
+  }
+});
+var _Skeleton = _interopRequireDefault(require("./Skeleton"));
+var _SkeletonGroup = require("./SkeletonGroup");
+var _useReducedMotion = require("./useReducedMotion");
+var _shimmerTokens = require("./shimmer-tokens");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }

package/lib/commonjs/skeleton/shimmer-tokens.js

@@ -0,0 +1,189 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.SKELETON_TOKEN = exports.SKELETON_FALLBACK = exports.SHIMMER_GRADIENT_STOPS = exports.SHIMMER = void 0;
+exports.computeShimmerMotion = computeShimmerMotion;
+exports.gradientPeakOffset = gradientPeakOffset;
+exports.gradientTransparentExtent = gradientTransparentExtent;
+exports.staggerDelayMs = staggerDelayMs;
+/**
+ * Single source of truth for the skeleton shimmer behaviour spec.
+ *
+ * The two modes mirror the documented design behaviour:
+ *
+ *   Normal:
+ *     - 1.5s linear sawtooth cycle (band sweeps end-to-end then resets)
+ *     - 135° gradient (top-left -> bottom-right), fixed angle on any aspect
+ *       ratio via SVG userSpaceOnUse coordinates
+ *     - Band alpha animates 33% -> 100% -> 33% across the band core;
+ *       transparent fades at the gradient edges hide the sawtooth reset
+ *     - 50–100ms per-item stagger
+ *
+ *   Reduced motion (system-level OS toggle):
+ *     - 3.0s ease-in-out cycle
+ *     - No translation — solid white overlay opacity pulses 33% -> 100% in
+ *       place (`opacityRange` below is consumed in this path)
+ *     - No gradient
+ *     - No stagger
+ *
+ * Centralising the spec here keeps `Skeleton.tsx` purely presentational and
+ * lets us tune the behaviour in one place if design ever updates it.
+ */
+
+const SHIMMER = exports.SHIMMER = {
+  normal: {
+    durationMs: 1500,
+    staggerMsRange: [50, 100],
+    gradient: true,
+    opacityRange: [0.33, 1.0]
+  },
+  reduced: {
+    durationMs: 3000,
+    staggerMsRange: [0, 0],
+    gradient: false,
+    opacityRange: [0.33, 1.0]
+  },
+  /**
+   * Gradient angle in degrees, measured the CSS way: 0deg points "up", 90deg
+   * "right", 135deg therefore points down-right (top-left corner to
+   * bottom-right corner).
+   */
+  gradientAngleDeg: 135,
+  /**
+   * Hard cap on the cumulative stagger delay so very long lists don't drift
+   * out forever; the wave wraps after this many ms.
+   */
+  maxStaggerMs: 600
+};
+
+/**
+ * Token names — referenced via `getVariableByName(...)` so the existing
+ * design-token resolver does its job (caching, mode resolution, etc.).
+ *
+ * The four tokens already live in the Figma export at
+ * `src/design-tokens/Coin Variables-variables-full.json`:
+ *
+ *   - `bg/defaultSkeleton`              -> base color for every skeleton block
+ *   - `cornerRadius/defaultSkeleton`    -> text & "other" (pill: 9999)
+ *   - `cornerRadius/imageSkeleton`      -> images (10)
+ *   - `cornerRadius/badgeSkeleton`      -> badges (4)
+ */
+const SKELETON_TOKEN = exports.SKELETON_TOKEN = {
+  background: 'bg/defaultSkeleton',
+  radius: {
+    text: 'cornerRadius/defaultSkeleton',
+    image: 'cornerRadius/imageSkeleton',
+    badge: 'cornerRadius/badgeSkeleton',
+    other: 'cornerRadius/defaultSkeleton'
+  }
+};
+
+/**
+ * Fallback constants used when the token resolver is unavailable (tests,
+ * SSR, etc.). Match the current Figma values.
+ */
+const SKELETON_FALLBACK = exports.SKELETON_FALLBACK = {
+  backgroundColor: 'rgb(245, 245, 246)',
+  radius: {
+    text: 9999,
+    image: 10,
+    badge: 4,
+    other: 9999
+  }
+};
+
+/**
+ * Compute a stable per-item delay from a 0-based registration index.
+ *
+ * We pick the midpoint of the documented range (75ms) so the cascade is
+ * deterministic for snapshot tests and visually identical between renders.
+ * The total delay is then wrapped at `maxStaggerMs` so deep lists don't
+ * drift past the cap.
+ */
+function staggerDelayMs(index, mode) {
+  const [min, max] = mode.staggerMsRange;
+  if (max <= 0) return 0;
+  const step = (min + max) / 2;
+  return index * step % SHIMMER.maxStaggerMs;
+}
+
+/** One stop on the moving shimmer gradient (offset 0–1 along the 135° axis). */
+
+/**
+ * Gradient stops for the normal-mode moving band. The peak sits at 0.5; fully
+ * transparent tails at 0 and 1. The 0.30 / 0.70 stops mark where the band
+ * reaches the documented 33 % alpha.
+ */
+const SHIMMER_GRADIENT_STOPS = exports.SHIMMER_GRADIENT_STOPS = [{
+  offset: 0,
+  opacity: 0
+}, {
+  offset: 0.30,
+  opacity: 0.33
+}, {
+  offset: 0.50,
+  opacity: 1
+}, {
+  offset: 0.70,
+  opacity: 0.33
+}, {
+  offset: 1.0,
+  opacity: 0
+}];
+
+/** Offset (0–1) of the brightest point on the gradient line. */
+function gradientPeakOffset(stops = SHIMMER_GRADIENT_STOPS) {
+  const peak = stops.find(s => s.opacity === 1);
+  return peak?.offset ?? 0.5;
+}
+
+/**
+ * How far the gradient extends from the peak to a fully transparent stop,
+ * expressed as a fraction of the gradient line (0–1). With the default stops
+ * this is 0.5 (peak at 0.5, transparent at 0 and 1).
+ *
+ * This value drives the overshoot: the band must travel this fraction of a
+ * full corner-to-corner sweep *beyond* each corner so the soft transparent
+ * tails fully clear the box before the sawtooth reset.
+ */
+function gradientTransparentExtent(stops = SHIMMER_GRADIENT_STOPS) {
+  const peak = gradientPeakOffset(stops);
+  const transparent = stops.filter(s => s.opacity === 0);
+  if (transparent.length === 0) return 0.5;
+  return Math.max(...transparent.map(s => Math.abs(s.offset - peak)));
+}
+/**
+ * Derive the moving-shimmer geometry from box size, overlay size, and the
+ * gradient stop layout.
+ *
+ * Coordinate model (135° / down-right):
+ *   - Peak stripe world diagonal sum: (W + H) / 2 + 2k
+ *   - Gradient offset 0 → 1 spans 2 × overlaySize in diagonal-sum units
+ *   - Transparent tail beyond peak: fadeExtent × 2 × overlaySize / 2
+ *     = fadeExtent × overlaySize in k units
+ *
+ * The sawtooth clock maps linearly kStart → kEnd so t = 0 and t = 1 both
+ * land with the entire gradient outside the box — no jitter on reset.
+ */
+function computeShimmerMotion(width, height, overlaySize, stops = SHIMMER_GRADIENT_STOPS) {
+  if (width <= 0 || height <= 0 || overlaySize <= 0) return null;
+  const fadeExtent = gradientTransparentExtent(stops);
+  const cornerTravelK = (width + height) / 2;
+  const baseSweepHalfK = cornerTravelK / 2;
+  const fadeBeyondPeakK = fadeExtent * overlaySize;
+  const kStart = -baseSweepHalfK - fadeBeyondPeakK;
+  const kEnd = baseSweepHalfK + fadeBeyondPeakK;
+  const overshootFraction = cornerTravelK > 0 ? fadeBeyondPeakK / cornerTravelK : 0;
+  return {
+    overlaySize,
+    padX: (overlaySize - width) / 2,
+    padY: (overlaySize - height) / 2,
+    kStart,
+    kEnd,
+    overshootFraction,
+    cornerTravelK,
+    fadeBeyondPeakK
+  };
+}