jfs-components 0.0.73 → 0.0.77

package/src/icons/Icon.tsx

@@ -3,6 +3,8 @@ import { View, AccessibilityProps, type StyleProp, type ViewStyle } from 'react-
 import Svg, { Path } from 'react-native-svg';
 import { getIcon, hasIcon } from './registry';
 import MediaSource, { type UnifiedSource } from '../utils/MediaSource';
+import Skeleton from '../skeleton/Skeleton';
+import { useSkeleton } from '../skeleton/SkeletonGroup';
 
 type IconProps = AccessibilityProps & {
   /**
@@ -22,6 +24,12 @@ type IconProps = AccessibilityProps & {
   size?: number;
   color?: string;
   style?: StyleProp<ViewStyle>;
+  /**
+   * Explicit per-instance loading override. When `true`, renders a square
+   * skeleton at the icon's size; when `false`, the surrounding
+   * `<SkeletonGroup>` is ignored. Defaults to inheriting from the group.
+   */
+  loading?: boolean;
 };
 
 /**
@@ -54,8 +62,13 @@ function Icon({
   size = 24,
   color = '#141414',
   style,
+  loading,
   ...rest
 }: IconProps) {
+  // Skeleton context — always read; we short-circuit below.
+  const { active: groupActive } = useSkeleton();
+  const isLoading = loading ?? groupActive;
+
   const containerStyle: StyleProp<ViewStyle> = [
     {
       width: size,
@@ -66,6 +79,10 @@ function Icon({
     style,
   ];
 
+  if (isLoading) {
+    return <Skeleton kind="other" width={size} height={size} style={style as any} />;
+  }
+
   const iconData = name && hasIcon(name) ? getIcon(name) : null;
 
   if (iconData) {

package/src/icons/registry.ts

@@ -4,7 +4,7 @@
  * Auto-generated from SVG files in src/icons/
  * DO NOT EDIT MANUALLY - Run "npm run icons:generate" to regenerate
  * 
- * Generated: 2026-05-15T16:18:56.427Z
+ * Generated: 2026-05-25T10:18:38.037Z
  */
 
 // Icon name to SVG data mapping

package/src/index.ts

@@ -3,3 +3,4 @@ export * as Icons from './icons';
 export * from './design-tokens';
 export * from './Containers';
 export * from './utils';
+export * from './skeleton';

package/src/skeleton/Skeleton.tsx

@@ -0,0 +1,298 @@
+import React, { useId, useMemo, useState } from 'react'
+import {
+  type LayoutChangeEvent,
+  StyleSheet,
+  View,
+  type DimensionValue,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native'
+import Animated, {
+  interpolate,
+  useAnimatedStyle,
+} from 'react-native-reanimated'
+import Svg, {
+  Defs,
+  LinearGradient as SvgLinearGradient,
+  Rect,
+  Stop,
+} from 'react-native-svg'
+import { getVariableByName } from '../design-tokens/figma-variables-resolver'
+import {
+  SHIMMER,
+  SHIMMER_GRADIENT_STOPS,
+  SKELETON_FALLBACK,
+  SKELETON_TOKEN,
+  computeShimmerMotion,
+  staggerDelayMs,
+  type SkeletonKind,
+} from './shimmer-tokens'
+import { useSkeleton, useStaggerIndex } from './SkeletonGroup'
+
+export interface SkeletonProps {
+  /**
+   * Visual category — controls only the corner-radius token. Sizes are still
+   * supplied via `width`/`height`. Defaults to `'other'`.
+   */
+  kind?: SkeletonKind;
+  /** Width of the rectangular placeholder. Numbers are dp, strings are RN dimensions. */
+  width?: DimensionValue;
+  /** Height of the rectangular placeholder. */
+  height?: DimensionValue;
+  /**
+   * Optional style overrides merged onto the base layer (e.g. `marginTop`,
+   * `alignSelf`). Avoid `backgroundColor` and `borderRadius` here — use the
+   * design tokens instead so the system stays consistent.
+   */
+  style?: StyleProp<ViewStyle>;
+  /**
+   * Modes for token resolution (forwarded to `getVariableByName`). Most
+   * consumers can omit this — defaults work for every standard mode.
+   */
+  modes?: Record<string, any>;
+}
+
+// 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: ViewStyle = {
+  ...StyleSheet.absoluteFillObject,
+  overflow: 'hidden',
+  pointerEvents: 'none',
+}
+
+const solidOverlayStyle: ViewStyle = {
+  ...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,
+}: SkeletonProps) {
+  const { active, reducedMotion, clock } = useSkeleton()
+  const index = useStaggerIndex()
+  const reactId = 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] = useState({ width: 0, height: 0 })
+
+  const radiusTokenName = SKELETON_TOKEN.radius[kind]
+  const radius =
+    (getVariableByName(radiusTokenName, modes ?? {}) as number | null) ??
+    SKELETON_FALLBACK.radius[kind]
+
+  const backgroundColor =
+    (getVariableByName(SKELETON_TOKEN.background, modes ?? {}) as
+      | string
+      | null) ?? SKELETON_FALLBACK.backgroundColor
+
+  const spec = reducedMotion ? SHIMMER.reduced : 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 ? staggerDelayMs(index, spec) / spec.durationMs : 0
+
+  const baseStyle = useMemo<ViewStyle>(
+    () => ({
+      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 = useMemo(
+    () => computeShimmerMotion(W, H, overlaySize, 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 = 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 },
+          ] as unknown as ViewStyle['transform'],
+          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 },
+        ] as unknown as ViewStyle['transform'],
+        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 },
+      ] as unknown as ViewStyle['transform'],
+      opacity: interpolate(wave, [0, 1], [lo, hi]),
+    }
+  }, [
+    phaseOffset,
+    kStart,
+    kTravel,
+    spec.gradient,
+    spec.opacityRange[0],
+    spec.opacityRange[1],
+  ])
+
+  const gradientOverlayContainerStyle = useMemo<ViewStyle>(
+    () => ({
+      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: LayoutChangeEvent) => {
+    const { width: w, height: h } = e.nativeEvent.layout
+    if (w !== layout.width || h !== layout.height) {
+      setLayout({ width: w, height: h })
+    }
+  }
+
+  return (
+    <View
+      style={[baseStyle, style]}
+      accessibilityElementsHidden
+      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}
+    >
+      {spec.gradient ? (
+        layout.width > 0 ? (
+          <Animated.View
+            style={[gradientOverlayContainerStyle, overlayAnimatedStyle]}
+          >
+            <Svg width={overlaySize} height={overlaySize}>
+              <Defs>
+                <SvgLinearGradient
+                  id={gradientId}
+                  x1={0}
+                  y1={0}
+                  x2={overlaySize}
+                  y2={overlaySize}
+                  gradientUnits="userSpaceOnUse"
+                >
+                  {SHIMMER_GRADIENT_STOPS.map((stop, i) => (
+                    <Stop
+                      key={`${stop.offset}-${i}`}
+                      offset={String(stop.offset)}
+                      stopColor="#ffffff"
+                      stopOpacity={stop.opacity}
+                    />
+                  ))}
+                </SvgLinearGradient>
+              </Defs>
+              <Rect
+                width={overlaySize}
+                height={overlaySize}
+                fill={`url(#${gradientId})`}
+              />
+            </Svg>
+          </Animated.View>
+        ) : null
+      ) : (
+        <Animated.View style={[absoluteFillStyle, overlayAnimatedStyle]}>
+          <View style={solidOverlayStyle} />
+        </Animated.View>
+      )}
+    </View>
+  )
+}
+
+const Skeleton = React.memo(SkeletonImpl)
+
+export default Skeleton

package/src/skeleton/SkeletonGroup.tsx

@@ -0,0 +1,193 @@
+import React, {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  type ReactNode,
+} from 'react'
+import {
+  cancelAnimation,
+  Easing,
+  useSharedValue,
+  withRepeat,
+  withTiming,
+  type SharedValue,
+} from 'react-native-reanimated'
+import { SHIMMER } from './shimmer-tokens'
+import { useReducedMotion as useSystemReducedMotion } from './useReducedMotion'
+
+/**
+ * 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.
+ */
+export interface SkeletonContextValue {
+  /** Whether the surrounding group is currently in loading state. */
+  active: boolean;
+  /**
+   * Whether reduced-motion treatment should be applied. May be auto-detected
+   * from the OS or explicitly overridden via the `reducedMotion` prop on
+   * `<SkeletonGroup>`.
+   */
+  reducedMotion: boolean;
+  /**
+   * Shared phase value driven on the UI thread. Sawtooth: ramps linearly
+   * (or eased) from 0 -> 1 over one `SHIMMER.*.durationMs` period, then
+   * jumps back to 0 and repeats. Sawtooth is required so that the moving
+   * shimmer band sweeps from end to end at a constant heading and resets
+   * cleanly; a ping-pong clock would produce a discontinuity in
+   * `(clock + phaseOffset) % 1` at the apex, which translates to a visible
+   * jump in the band's position when stagger offsets are non-zero.
+   */
+  clock: SharedValue<number>;
+  /**
+   * Atomically registers a child skeleton and returns its registration index.
+   * The order is stable for the life of the parent group; the counter is held
+   * in a ref so React's render lifecycle doesn't reshuffle it.
+   */
+  nextIndex(): number;
+}
+
+const SkeletonContext = createContext<SkeletonContextValue | null>(null)
+
+export interface SkeletonGroupProps {
+  /** When true, descendant skeleton-aware primitives render placeholders. */
+  loading: boolean;
+  /**
+   * Override the auto-detected reduced-motion preference. Pass `undefined` to
+   * use the system value (default). Pass `true`/`false` to force.
+   */
+  reducedMotion?: boolean;
+  children?: ReactNode;
+}
+
+/**
+ * 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).
+ */
+export function SkeletonGroup({
+  loading,
+  reducedMotion: reducedMotionOverride,
+  children,
+}: SkeletonGroupProps) {
+  const systemReducedMotion = useSystemReducedMotion()
+  const reducedMotion = reducedMotionOverride ?? systemReducedMotion
+  const clock = 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.
+  useEffect(() => {
+    if (!loading) {
+      cancelAnimation(clock)
+      clock.value = 0
+      return
+    }
+    const spec = reducedMotion ? SHIMMER.reduced : SHIMMER.normal
+    const easing = reducedMotion
+      ? Easing.inOut(Easing.ease)
+      : 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 = withRepeat(
+      withTiming(1, { duration: spec.durationMs, easing }),
+      -1,
+      false,
+    )
+    return () => {
+      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 = useRef(0)
+  // Reset whenever loading flips on, so a freshly-displayed group cascades
+  // from index 0 again rather than picking up stale numbers.
+  useEffect(() => {
+    if (loading) indexRef.current = 0
+  }, [loading])
+
+  const value = useMemo<SkeletonContextValue>(
+    () => ({
+      active: loading,
+      reducedMotion,
+      clock,
+      nextIndex: () => {
+        const i = indexRef.current
+        indexRef.current = i + 1
+        return i
+      },
+    }),
+    [loading, reducedMotion, clock],
+  )
+
+  return (
+    <SkeletonContext.Provider value={value}>
+      {children}
+    </SkeletonContext.Provider>
+  )
+}
+
+/**
+ * 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.
+ */
+export function useSkeleton(): SkeletonContextValue {
+  const ctx = 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 = useSharedValue(0)
+  const fallbackIndexRef = useRef(0)
+  const fallback = useMemo<SkeletonContextValue>(
+    () => ({
+      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.
+ */
+export function useStaggerIndex(): number {
+  const { nextIndex } = useSkeleton()
+  const indexRef = useRef<number | null>(null)
+  if (indexRef.current === null) {
+    indexRef.current = nextIndex()
+  }
+  return indexRef.current
+}

package/src/skeleton/index.ts

@@ -0,0 +1,10 @@
+export { default as Skeleton, type SkeletonProps } from './Skeleton'
+export {
+  SkeletonGroup,
+  useSkeleton,
+  useStaggerIndex,
+  type SkeletonGroupProps,
+  type SkeletonContextValue,
+} from './SkeletonGroup'
+export { useReducedMotion } from './useReducedMotion'
+export { SHIMMER, SKELETON_TOKEN, SKELETON_FALLBACK, type SkeletonKind } from './shimmer-tokens'