jfs-components 0.0.73 → 0.0.77

package/src/skeleton/shimmer-tokens.ts

@@ -0,0 +1,221 @@
+/**
+ * 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.
+ */
+
+export type SkeletonKind = 'text' | 'image' | 'badge' | 'other';
+
+export interface ShimmerModeSpec {
+  durationMs: number;
+  /** Per-item delay range. Min/max in milliseconds. */
+  staggerMsRange: readonly [number, number];
+  gradient: boolean;
+  /** Opacity range applied to the moving "blob" overlay. */
+  opacityRange: readonly [number, number];
+}
+
+export const SHIMMER = {
+  normal: {
+    durationMs: 1500,
+    staggerMsRange: [50, 100] as const,
+    gradient: true,
+    opacityRange: [0.33, 1.0] as const,
+  } satisfies ShimmerModeSpec,
+  reduced: {
+    durationMs: 3000,
+    staggerMsRange: [0, 0] as const,
+    gradient: false,
+    opacityRange: [0.33, 1.0] as const,
+  } satisfies ShimmerModeSpec,
+  /**
+   * 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,
+} as const
+
+/**
+ * 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)
+ */
+export const SKELETON_TOKEN = {
+  background: 'bg/defaultSkeleton',
+  radius: {
+    text: 'cornerRadius/defaultSkeleton',
+    image: 'cornerRadius/imageSkeleton',
+    badge: 'cornerRadius/badgeSkeleton',
+    other: 'cornerRadius/defaultSkeleton',
+  } satisfies Record<SkeletonKind, string>,
+} as const
+
+/**
+ * Fallback constants used when the token resolver is unavailable (tests,
+ * SSR, etc.). Match the current Figma values.
+ */
+export const SKELETON_FALLBACK = {
+  backgroundColor: 'rgb(245, 245, 246)',
+  radius: {
+    text: 9999,
+    image: 10,
+    badge: 4,
+    other: 9999,
+  } satisfies Record<SkeletonKind, number>,
+} as const
+
+/**
+ * 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.
+ */
+export function staggerDelayMs(index: number, mode: ShimmerModeSpec): number {
+  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). */
+export interface ShimmerGradientStop {
+  offset: number
+  opacity: number
+}
+
+/**
+ * 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.
+ */
+export const SHIMMER_GRADIENT_STOPS: readonly ShimmerGradientStop[] = [
+  { 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 },
+] as const
+
+/** Offset (0–1) of the brightest point on the gradient line. */
+export function gradientPeakOffset(
+  stops: readonly ShimmerGradientStop[] = SHIMMER_GRADIENT_STOPS,
+): number {
+  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.
+ */
+export function gradientTransparentExtent(
+  stops: readonly ShimmerGradientStop[] = SHIMMER_GRADIENT_STOPS,
+): number {
+  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)))
+}
+
+export interface ShimmerMotionGeometry {
+  /** Square overlay side length (gradient is painted on this). */
+  overlaySize: number
+  /** Padding to centre the overlay on the box. */
+  padX: number
+  padY: number
+  /** Translation (k, k) when the band is fully off-screen before entry. */
+  kStart: number
+  /** Translation (k, k) when the band is fully off-screen after exit. */
+  kEnd: number
+  /**
+   * Normalised overshoot on each side of the corner-to-corner sweep. A value
+   * of 0.5 means the travel extends 50 % past each corner; at reset the
+   * clock jumps from `1 + overshoot` to `-overshoot` while the box still
+   * shows only the base skeleton colour.
+   */
+  overshootFraction: number
+  /** k distance from peak-at-TL to peak-at-BR. */
+  cornerTravelK: number
+  /** k distance from peak to fully transparent tail on the gradient. */
+  fadeBeyondPeakK: number
+}
+
+/**
+ * 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.
+ */
+export function computeShimmerMotion(
+  width: number,
+  height: number,
+  overlaySize: number,
+  stops: readonly ShimmerGradientStop[] = SHIMMER_GRADIENT_STOPS,
+): ShimmerMotionGeometry | null {
+  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,
+  }
+}

package/src/skeleton/useReducedMotion.ts

@@ -0,0 +1,72 @@
+import { useEffect, useState } from 'react'
+import { AccessibilityInfo, Platform } from 'react-native'
+
+/**
+ * Cross-platform "prefers reduced motion" hook.
+ *
+ *  - Native: reads `AccessibilityInfo.isReduceMotionEnabled()` and subscribes
+ *    to `reduceMotionChanged` events so the value stays live as the user
+ *    toggles the OS setting.
+ *  - Web: uses `window.matchMedia('(prefers-reduced-motion: reduce)')`,
+ *    subscribing to its `change` event.
+ *  - Anywhere either API is missing: returns `false` (no reduction).
+ *
+ * The hook never throws — every native API access is defensively guarded so
+ * the skeleton system stays safe in tests, SSR, and constrained sandboxes.
+ */
+export function useReducedMotion(): boolean {
+  const [reduced, setReduced] = useState<boolean>(false)
+
+  useEffect(() => {
+    let cancelled = false
+
+    if (Platform.OS === 'web') {
+      if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
+        return
+      }
+      const mql = window.matchMedia('(prefers-reduced-motion: reduce)')
+      const update = (matches: boolean) => {
+        if (!cancelled) setReduced(matches)
+      }
+      update(mql.matches)
+      const listener = (e: MediaQueryListEvent) => update(e.matches)
+      if (typeof mql.addEventListener === 'function') {
+        mql.addEventListener('change', listener)
+        return () => {
+          cancelled = true
+          mql.removeEventListener('change', listener)
+        }
+      }
+      const legacyMql = mql as MediaQueryList & {
+        addListener?: (l: (e: MediaQueryListEvent) => void) => void;
+        removeListener?: (l: (e: MediaQueryListEvent) => void) => void;
+      }
+      legacyMql.addListener?.(listener)
+      return () => {
+        cancelled = true
+        legacyMql.removeListener?.(listener)
+      }
+    }
+
+    if (typeof AccessibilityInfo?.isReduceMotionEnabled === 'function') {
+      AccessibilityInfo.isReduceMotionEnabled()
+        .then((value: boolean) => {
+          if (!cancelled) setReduced(!!value)
+        })
+        .catch(() => {})
+    }
+    const sub =
+      typeof AccessibilityInfo?.addEventListener === 'function'
+        ? AccessibilityInfo.addEventListener('reduceMotionChanged', (value: boolean) => {
+            if (!cancelled) setReduced(!!value)
+          })
+        : null
+
+    return () => {
+      cancelled = true
+      sub?.remove?.()
+    }
+  }, [])
+
+  return reduced
+}