react-native-smart-skeleton 0.0.1

package/src/animations/breathing.tsx

@@ -0,0 +1,81 @@
+import { useEffect } from "react";
+import {
+    Easing,
+    cancelAnimation,
+    useAnimatedStyle,
+    useSharedValue,
+    withDelay,
+    withRepeat,
+    withTiming,
+} from "react-native-reanimated";
+import type { SkeletonPerformanceMode } from "../types";
+
+export interface BreathingOptions {
+    duration?: number;
+    delay?: number;
+    disabled?: boolean;
+    performanceMode?: SkeletonPerformanceMode;
+    /** Smallest scale factor during the "exhale" phase. Defaults to 0.97. */
+    minScale?: number;
+    /** Largest scale factor during the "inhale" phase. Defaults to 1. */
+    maxScale?: number;
+    /** Paired opacity dip alongside the scale-down. Defaults to 0.85. */
+    minOpacity?: number;
+}
+
+/**
+ * A slow, very gentle scale + opacity oscillation — softer and slower than
+ * "pulse" — intended as the most reduced-motion-friendly animation. This is
+ * the animation `Skeleton` falls back to (at a slowed rate) when the OS
+ * reduce-motion setting is on and the consumer hasn't explicitly chosen "none".
+ */
+export function useBreathingStyle({
+    duration = 2200,
+    delay = 0,
+    disabled = false,
+    performanceMode = "balanced",
+    minScale = 0.97,
+    maxScale = 1,
+    minOpacity = 0.85,
+}: BreathingOptions) {
+    const progress = useSharedValue(0);
+
+    useEffect(() => {
+        if (disabled) {
+            progress.value = 0;
+            return;
+        }
+
+        const effectiveDuration =
+            performanceMode === "battery-saver" ? duration * 1.2 : duration;
+
+        progress.value = 0;
+        progress.value = withDelay(
+            delay,
+            withRepeat(
+                withTiming(1, {
+                    duration: effectiveDuration / 2,
+                    easing: Easing.inOut(Easing.ease),
+                }),
+                -1,
+                true
+            )
+        );
+
+        return () => {
+            cancelAnimation(progress);
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [duration, delay, disabled, performanceMode]);
+
+    const style = useAnimatedStyle(() => {
+        const scale = minScale + progress.value * (maxScale - minScale);
+        const opacity = minOpacity + progress.value * (1 - minOpacity);
+        return {
+            opacity,
+            transform: [{ scale }],
+        };
+    }, [minScale, maxScale, minOpacity]);
+
+    return style;
+}

package/src/animations/pulse.tsx

@@ -0,0 +1,75 @@
+import { useEffect } from "react";
+import {
+    Easing,
+    cancelAnimation,
+    useAnimatedStyle,
+    useSharedValue,
+    withDelay,
+    withRepeat,
+    withTiming,
+} from "react-native-reanimated";
+import type { SkeletonPerformanceMode } from "../types";
+
+export interface PulseOptions {
+    duration?: number;
+    delay?: number;
+    disabled?: boolean;
+    performanceMode?: SkeletonPerformanceMode;
+    /** Minimum opacity of the "dim" phase. Defaults to 0.4. */
+    minOpacity?: number;
+    /** Maximum opacity of the "bright" phase. Defaults to 1. */
+    maxOpacity?: number;
+}
+
+/**
+ * Classic fade in/out pulse: opacity oscillates between minOpacity and
+ * maxOpacity using an ease-in-out curve, looping indefinitely.
+ *
+ * Returns an animated style with just `opacity`, ready to spread onto the
+ * skeleton's base View.
+ */
+export function usePulseStyle({
+    duration = 1000,
+    delay = 0,
+    disabled = false,
+    performanceMode = "balanced",
+    minOpacity = 0.4,
+    maxOpacity = 1,
+}: PulseOptions) {
+    const progress = useSharedValue(0);
+
+    useEffect(() => {
+        if (disabled) {
+            progress.value = 0;
+            return;
+        }
+
+        const effectiveDuration =
+            performanceMode === "battery-saver" ? duration * 1.3 : duration;
+
+        progress.value = 0;
+        progress.value = withDelay(
+            delay,
+            withRepeat(
+                withTiming(1, {
+                    duration: effectiveDuration / 2,
+                    easing: Easing.inOut(Easing.ease),
+                }),
+                -1,
+                true // reverse, giving the fade-in/fade-out loop
+            )
+        );
+
+        return () => {
+            cancelAnimation(progress);
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [duration, delay, disabled, performanceMode]);
+
+    const style = useAnimatedStyle(() => {
+        const opacity = minOpacity + progress.value * (maxOpacity - minOpacity);
+        return { opacity };
+    }, [minOpacity, maxOpacity]);
+
+    return style;
+}

package/src/animations/shimmer.tsx

@@ -0,0 +1,88 @@
+import { useEffect } from "react";
+import {
+    Easing,
+    cancelAnimation,
+    useAnimatedStyle,
+    useSharedValue,
+    withDelay,
+    withRepeat,
+    withTiming,
+} from "react-native-reanimated";
+import type { SkeletonPerformanceMode } from "../types";
+
+export interface ShimmerOptions {
+    duration?: number;
+    delay?: number;
+    /** When true, freezes the animation at progress 0 (used for reduced motion / "none"). */
+    disabled?: boolean;
+    performanceMode?: SkeletonPerformanceMode;
+}
+
+/**
+ * Drives a 0 -> 1 -> 0 progress value looping indefinitely, intended to be
+ * mapped (by the consuming component) onto a translateX of a gradient
+ * overlay to create the classic "shimmer sweep" effect.
+ *
+ * Returns both the raw shared value-derived animated style (opacity passthrough,
+ * so it can be spread directly) and the progress itself isn't exposed —
+ * components should use `useShimmerTransform` below to get a transform style
+ * sized to their own width.
+ */
+export function useShimmerProgress({
+    duration = 1200,
+    delay = 0,
+    disabled = false,
+    performanceMode = "balanced",
+}: ShimmerOptions) {
+    const progress = useSharedValue(0);
+
+    useEffect(() => {
+        if (disabled) {
+            progress.value = 0;
+            return;
+        }
+
+        const effectiveDuration =
+            performanceMode === "battery-saver" ? duration * 1.4 : duration;
+
+        progress.value = 0;
+        progress.value = withDelay(
+            delay,
+            withRepeat(
+                withTiming(1, {
+                    duration: effectiveDuration,
+                    easing: Easing.linear,
+                }),
+                -1,
+                false
+            )
+        );
+
+        return () => {
+            cancelAnimation(progress);
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [duration, delay, disabled, performanceMode]);
+
+    return progress;
+}
+
+/**
+ * Convenience hook: given a measured width, returns an animated style that
+ * translates a highlight overlay (assumed ~60% of `width` wide) from off-screen
+ * left to off-screen right, looping. Use on an absolutely-positioned overlay
+ * View/LinearGradient layered on top of the base skeleton rect.
+ */
+export function useShimmerTransform(width: number, options: ShimmerOptions) {
+    const progress = useShimmerProgress(options);
+    const sweepWidth = Math.max(width, 1) * 0.6;
+
+    const style = useAnimatedStyle(() => {
+        const translateX = -sweepWidth + progress.value * (width + sweepWidth);
+        return {
+            transform: [{ translateX }],
+        };
+    }, [width, sweepWidth]);
+
+    return { style, sweepWidth };
+}

package/src/animations/wave.tsx

@@ -0,0 +1,74 @@
+import { useEffect } from "react";
+import {
+    Easing,
+    cancelAnimation,
+    interpolate,
+    useAnimatedStyle,
+    useSharedValue,
+    withDelay,
+    withRepeat,
+    withTiming,
+} from "react-native-reanimated";
+import type { SkeletonPerformanceMode } from "../types";
+
+export interface WaveOptions {
+    duration?: number;
+    delay?: number;
+    disabled?: boolean;
+    performanceMode?: SkeletonPerformanceMode;
+}
+
+/**
+ * Similar to shimmer, but drives a smoother sine-like sweep (ease-in-out
+ * instead of linear) intended for a softer "ripple" look, typically paired
+ * with a wider, lower-contrast gradient than shimmer uses.
+ *
+ * Returns a translateX-based animated style for a given measured width.
+ */
+export function useWaveTransform(width: number, options: WaveOptions) {
+    const { duration = 1500, delay = 0, disabled = false, performanceMode = "balanced" } = options;
+    const progress = useSharedValue(0);
+
+    useEffect(() => {
+        if (disabled) {
+            progress.value = 0;
+            return;
+        }
+
+        const effectiveDuration =
+            performanceMode === "battery-saver" ? duration * 1.4 : duration;
+
+        progress.value = 0;
+        progress.value = withDelay(
+            delay,
+            withRepeat(
+                withTiming(1, {
+                    duration: effectiveDuration,
+                    easing: Easing.inOut(Easing.sin),
+                }),
+                -1,
+                false
+            )
+        );
+
+        return () => {
+            cancelAnimation(progress);
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [duration, delay, disabled, performanceMode]);
+
+    const sweepWidth = Math.max(width, 1) * 0.8;
+
+    const style = useAnimatedStyle(() => {
+        const translateX = interpolate(
+            progress.value,
+            [0, 1],
+            [-sweepWidth, width + sweepWidth]
+        );
+        return {
+            transform: [{ translateX }],
+        };
+    }, [width, sweepWidth]);
+
+    return { style, sweepWidth };
+}

package/src/clone/SkeletonClone.tsx

@@ -0,0 +1,82 @@
+import React from "react";
+import { View } from "react-native";
+import Skeleton from "../components/Skeleton";
+import type { SkeletonCloneNode, SkeletonCloneProps } from "../types";
+
+function renderNode(node: SkeletonCloneNode, animation: SkeletonCloneProps["animation"], keyPrefix: string) {
+    const { shape = "rect", width, height, borderRadius, style, children, direction = "column", gap = 8 } = node;
+
+    let resolvedBorderRadius = borderRadius;
+    if (shape === "circle") {
+        const numericSize = typeof width === "number" ? width : typeof height === "number" ? height : 50;
+        resolvedBorderRadius = numericSize / 2;
+    } else if (shape === "pill") {
+        const numericHeight = typeof height === "number" ? height : 24;
+        resolvedBorderRadius = resolvedBorderRadius ?? numericHeight / 2;
+    }
+
+    if (children && children.length > 0) {
+        return (
+            <View
+                key={keyPrefix}
+                style={[
+                    { flexDirection: direction === "row" ? "row" : "column" },
+                    style,
+                ]}
+            >
+                {children.map((child, i) => (
+                    <View
+                        key={`${keyPrefix}-${i}`}
+                        style={
+                            direction === "row"
+                                ? { marginLeft: i === 0 ? 0 : gap }
+                                : { marginTop: i === 0 ? 0 : gap }
+                        }
+                    >
+                        {renderNode(child, animation, `${keyPrefix}-${i}`)}
+                    </View>
+                ))}
+            </View>
+        );
+    }
+
+    return (
+        <Skeleton
+            width={width ?? "100%"}
+            height={height ?? 16}
+            borderRadius={resolvedBorderRadius ?? 4}
+            animation={animation}
+            style={style}
+        />
+    );
+}
+
+/**
+ * Clones an arbitrary layout tree as skeleton placeholders. Useful when you
+ * have a complex, bespoke screen layout and don't want to hand-place a
+ * Skeleton for every element — instead describe the rough shape once as a
+ * `SkeletonCloneNode` tree (mirroring your real layout's structure) and let
+ * SkeletonClone render matching placeholders.
+ *
+ * @example
+ * <SkeletonClone
+ *   layout={{
+ *     direction: "row",
+ *     gap: 12,
+ *     children: [
+ *       { shape: "circle", width: 48, height: 48 },
+ *       {
+ *         direction: "column",
+ *         gap: 6,
+ *         children: [
+ *           { width: 120, height: 14 },
+ *           { width: 80, height: 12 },
+ *         ],
+ *       },
+ *     ],
+ *   }}
+ * />
+ */
+export default function SkeletonClone({ layout, animation, style, testID }: SkeletonCloneProps) {
+    return <View style={style} testID={testID}>{renderNode(layout, animation, "clone-root")}</View>;
+}

package/src/components/Circle.tsx

@@ -0,0 +1,13 @@
+import React from "react";
+import Skeleton from "./Skeleton";
+import type { SkeletonCircleProps } from "../types";
+
+/**
+ * A circular skeleton placeholder, commonly used for avatars.
+ *
+ * @example
+ * <Skeleton.Circle size={48} />
+ */
+export default function Circle({ size = 50, ...props }: SkeletonCircleProps) {
+    return <Skeleton width={size} height={size} borderRadius={size / 2} {...props} />;
+}

package/src/components/Group.tsx

@@ -0,0 +1,55 @@
+import React, { Children, isValidElement, cloneElement } from "react";
+import { View } from "react-native";
+import type { SkeletonGroupProps } from "../types";
+
+/**
+ * Groups multiple skeleton children together and automatically staggers
+ * their animation start so they don't all pulse/shimmer perfectly in sync —
+ * a subtle touch that reads as more natural for lists of skeleton rows.
+ *
+ * Any direct child that accepts a `delay` prop (i.e. any Skeleton.* shape,
+ * or a custom component that forwards `delay` to one) will have an
+ * incremental delay injected automatically. Children that already specify
+ * their own `delay` are left untouched.
+ *
+ * @example
+ * <Skeleton.Group staggerDelay={80}>
+ *   <Skeleton.Rect width="100%" height={16} />
+ *   <Skeleton.Rect width="80%" height={16} />
+ *   <Skeleton.Rect width="60%" height={16} />
+ * </Skeleton.Group>
+ */
+export default function Group({
+    children,
+    staggerDelay = 80,
+    animation,
+    direction = "column",
+    style,
+    testID,
+}: SkeletonGroupProps) {
+    const items = Children.toArray(children);
+
+    return (
+        <View
+            style={[{ flexDirection: direction === "row" ? "row" : "column" }, style]}
+            testID={testID}
+        >
+            {items.map((child, index) => {
+                if (!isValidElement(child)) return child;
+
+                const existingProps = child.props as Record<string, unknown>;
+                const injectedProps: Record<string, unknown> = {};
+
+                if (existingProps.delay === undefined) {
+                    injectedProps.delay = index * staggerDelay;
+                }
+
+                if (animation && existingProps.animation === undefined) {
+                    injectedProps.animation = animation;
+                }
+
+                return cloneElement(child, { key: child.key ?? index, ...injectedProps });
+            })}
+        </View>
+    );
+}

package/src/components/Pill.tsx

@@ -0,0 +1,23 @@
+import React from "react";
+import Skeleton from "./Skeleton";
+import type { SkeletonPillProps } from "../types";
+
+/**
+ * A fully-rounded "pill" skeleton placeholder, commonly used for buttons,
+ * tags/chips, or badges. Border radius is automatically derived from height
+ * unless overridden.
+ *
+ * @example
+ * <Skeleton.Pill width={80} height={28} />
+ */
+export default function Pill({ width = 80, height = 24, borderRadius, ...props }: SkeletonPillProps) {
+    const numericHeight = typeof height === "number" ? height : 24;
+    return (
+        <Skeleton
+            width={width}
+            height={height}
+            borderRadius={borderRadius ?? numericHeight / 2}
+            {...props}
+        />
+    );
+}

package/src/components/Rect.tsx

@@ -0,0 +1,15 @@
+import React from "react";
+import Skeleton from "./Skeleton";
+import type { SkeletonProps } from "../types";
+
+/**
+ * A rectangular skeleton placeholder. Equivalent to `<Skeleton />` directly,
+ * provided for a consistent, explicit naming convention alongside
+ * `Skeleton.Circle`, `Skeleton.Square`, and `Skeleton.Pill`.
+ *
+ * @example
+ * <Skeleton.Rect width={200} height={20} />
+ */
+export default function Rect(props: SkeletonProps) {
+    return <Skeleton {...props} />;
+}