react-native-smart-skeleton 0.0.1

package/src/components/Skeleton.tsx

@@ -0,0 +1,218 @@
+import React, { useCallback, useContext, useState } from "react";
+import {
+    I18nManager,
+    View,
+    type LayoutChangeEvent,
+    type StyleProp,
+    type ViewStyle,
+} from "react-native";
+import Animated from "react-native-reanimated";
+
+import { SkeletonContext } from "../providers/SkeletonProvider";
+import { useSkeletonTheme } from "../hooks/useSkeletonTheme";
+import { useReducedMotion } from "../hooks/useReducedMotion";
+import { useShimmerTransform } from "../animations/shimmer";
+import { usePulseStyle } from "../animations/pulse";
+import { useWaveTransform } from "../animations/wave";
+import { useBreathingStyle } from "../animations/breathing";
+import { buildSweepGradient } from "../utils/colors";
+import type { SkeletonAnimation, SkeletonProps } from "../types";
+
+const LinearGradientComponent = (() => {
+    try {
+        return require("expo-linear-gradient").LinearGradient as React.ComponentType<any>;
+    } catch {
+        try {
+            return require("react-native-linear-gradient").default as React.ComponentType<any>;
+        } catch {
+            return View as unknown as React.ComponentType<any>;
+        }
+    }
+})();
+
+const AnimatedLinearGradient = Animated.createAnimatedComponent(LinearGradientComponent);
+
+/**
+ * The base building block of react-native-smart-skeleton. Renders a single
+ * rectangular (optionally rounded) placeholder shape with the requested
+ * animation, fully theme-aware and accessible.
+ *
+ * Most consumers will reach for `Skeleton.Rect`, `Skeleton.Circle`,
+ * `Skeleton.Square`, or `Skeleton.Pill` instead of this directly, but those
+ * are all thin wrappers around this component.
+ *
+ * @example
+ * <Skeleton width={200} height={20} animation="shimmer" />
+ */
+export default function Skeleton({
+    width = "100%",
+    height = 16,
+    borderRadius = 4,
+    backgroundColor,
+    highlightColor,
+    gradientColors,
+    animation,
+    duration,
+    delay = 0,
+    rtl,
+    colorVariant,
+    style,
+    accessibilityLabel = "Loading content",
+    accessible = true,
+    testID,
+}: SkeletonProps) {
+    const ctx = useContext(SkeletonContext);
+    const themeColors = useSkeletonTheme(colorVariant);
+    const osReducedMotion = useReducedMotion();
+
+    const [measuredWidth, setMeasuredWidth] = useState(0);
+
+    const onLayout = useCallback((e: LayoutChangeEvent) => {
+        setMeasuredWidth(e.nativeEvent.layout.width);
+    }, []);
+
+    // Resolve effective settings, falling back through: prop -> provider -> library default.
+    const resolvedAnimation: SkeletonAnimation =
+        animation ?? ctx?.animation ?? "shimmer";
+    const resolvedDuration = duration ?? ctx?.duration ?? 1200;
+    const resolvedPerformanceMode = ctx?.performanceMode ?? "balanced";
+    const reducedMotion = ctx?.reducedMotion ?? osReducedMotion;
+    const resolvedRtl = rtl ?? ctx?.rtl ?? I18nManager.isRTL;
+
+    const bg = backgroundColor ?? themeColors.background;
+    const highlight = highlightColor ?? themeColors.highlight;
+    const colors = gradientColors ?? buildSweepGradient(bg, highlight);
+
+    // Reduced motion: never run shimmer/wave/pulse at full intensity. Fall back to a
+    // slow "breathing" effect unless the consumer explicitly asked for "none".
+    const effectiveAnimation: SkeletonAnimation =
+        reducedMotion && resolvedAnimation !== "none" ? "breathing" : resolvedAnimation;
+
+    const disabled = effectiveAnimation === "none";
+
+    const shimmer = useShimmerTransform(measuredWidth, {
+        duration: resolvedDuration,
+        delay,
+        disabled: disabled || effectiveAnimation !== "shimmer",
+        performanceMode: resolvedPerformanceMode,
+    });
+
+    const wave = useWaveTransform(measuredWidth, {
+        duration: resolvedDuration,
+        delay,
+        disabled: disabled || effectiveAnimation !== "wave",
+        performanceMode: resolvedPerformanceMode,
+    });
+
+    const pulseStyle = usePulseStyle({
+        duration: resolvedDuration,
+        delay,
+        disabled: disabled || effectiveAnimation !== "pulse",
+        performanceMode: resolvedPerformanceMode,
+    });
+
+    const breathingStyle = useBreathingStyle({
+        duration: reducedMotion ? resolvedDuration * 1.6 : resolvedDuration,
+        delay,
+        disabled: disabled || effectiveAnimation !== "breathing",
+        performanceMode: resolvedPerformanceMode,
+        // Reduced-motion breathing should be extra subtle.
+        minScale: reducedMotion ? 0.99 : 0.97,
+        minOpacity: reducedMotion ? 0.92 : 0.85,
+    });
+
+    const containerStyle: StyleProp<ViewStyle> = [
+        {
+            width,
+            height,
+            borderRadius,
+            overflow: "hidden" as const,
+            backgroundColor: bg,
+        } as ViewStyle,
+        style,
+    ];
+    const renderOverlay = () => {
+        if (disabled) return null;
+
+        if (effectiveAnimation === "pulse") {
+            return (
+                <Animated.View
+                    pointerEvents="none"
+                    style={[
+                        {
+                            position: "absolute",
+                            top: 0,
+                            right: 0,
+                            bottom: 0,
+                            left: 0,
+                            backgroundColor: highlight,
+                        },
+                        pulseStyle,
+                    ]}
+                />
+            );
+        }
+
+        if (effectiveAnimation === "breathing") {
+            return (
+                <Animated.View
+                    pointerEvents="none"
+                    style={[
+                        {
+                            position: "absolute",
+                            top: 0,
+                            right: 0,
+                            bottom: 0,
+                            left: 0,
+                            backgroundColor: highlight,
+                        },
+                        breathingStyle,
+                    ]}
+                />
+            );
+        }
+
+        if (effectiveAnimation === "shimmer" || effectiveAnimation === "wave") {
+            const transform = effectiveAnimation === "shimmer" ? shimmer : wave;
+            const flip = resolvedRtl ? { transform: [{ scaleX: -1 }] } : null;
+
+            return (
+                <Animated.View
+                    pointerEvents="none"
+                    style={[
+                        { position: "absolute", top: 0, bottom: 0, left: 0 },
+                        { width: transform.sweepWidth },
+                        transform.style,
+                        flip,
+                    ]}
+                >
+                    <AnimatedLinearGradient
+                        colors={colors as any}
+                        start={{ x: 0, y: 0 }}
+                        end={{ x: 1, y: 0 }}
+                        style={{ flex: 1 }}
+                    />
+                </Animated.View>
+            );
+        }
+
+        return null;
+    };
+
+    return (
+        <View
+            onLayout={onLayout}
+            style={containerStyle}
+            accessible={accessible}
+            accessibilityRole={accessible ? "image" : undefined}
+            accessibilityLabel={accessible ? accessibilityLabel : undefined}
+            accessibilityState={accessible ? { busy: true } : undefined}
+            // importantForAccessibility keeps these decorative-but-informative
+            // nodes from over-announcing on Android when nested in lists.
+            importantForAccessibility={accessible ? "yes" : "no-hide-descendants"}
+            testID={testID}
+        >
+            {renderOverlay()}
+        </View>
+    );
+}

package/src/components/Square.tsx

@@ -0,0 +1,13 @@
+import React from "react";
+import Skeleton from "./Skeleton";
+import type { SkeletonSquareProps } from "../types";
+
+/**
+ * A square skeleton placeholder with equal width and height.
+ *
+ * @example
+ * <Skeleton.Square size={64} borderRadius={8} />
+ */
+export default function Square({ size = 50, borderRadius = 4, ...props }: SkeletonSquareProps) {
+    return <Skeleton width={size} height={size} borderRadius={borderRadius} {...props} />;
+}

package/src/hooks/useReducedMotion.ts

@@ -0,0 +1,46 @@
+import { useEffect, useState } from "react";
+import { AccessibilityInfo } from "react-native";
+
+/**
+ * Tracks the OS-level "reduce motion" accessibility setting
+ * (Reduce Motion on iOS, Remove Animations on Android) and keeps it
+ * up to date if the user changes the setting while the app is running.
+ *
+ * Skeleton animations should fall back to a static or near-static
+ * appearance (or the "breathing" animation at a slow, low-amplitude
+ * rate) when this returns true.
+ */
+export function useReducedMotion(): boolean {
+    const [reducedMotion, setReducedMotion] = useState(false);
+
+    useEffect(() => {
+        let isMounted = true;
+
+        AccessibilityInfo.isReduceMotionEnabled?.()
+            .then((enabled) => {
+                if (isMounted) setReducedMotion(!!enabled);
+            })
+            .catch(() => {
+                // Some platforms/environments (e.g. older RN, web shims) may not
+                // implement this — default to false (animations enabled).
+            });
+
+        const subscription = AccessibilityInfo.addEventListener(
+            "reduceMotionChanged",
+            (enabled: boolean) => {
+                setReducedMotion(!!enabled);
+            }
+        );
+
+        return () => {
+            isMounted = false;
+            // RN >= 0.65 returns an EmitterSubscription with `.remove()`.
+            // Older versions returned void and relied on removeEventListener.
+            if (subscription && typeof (subscription as any).remove === "function") {
+                (subscription as any).remove();
+            }
+        };
+    }, []);
+
+    return reducedMotion;
+}

package/src/hooks/useSkeletonTheme.ts

@@ -0,0 +1,45 @@
+import { useContext, useMemo } from "react";
+import { useColorScheme } from "react-native";
+import { SkeletonContext } from "../providers/SkeletonProvider";
+import { getDefaultThemeColors } from "../utils/theme";
+import { resolveThemeColors } from "../utils/colors";
+import type { ResolvedSkeletonTheme } from "../types";
+
+/**
+ * Resolves the active light/dark colors for a skeleton.
+ *
+ * If used inside a <SkeletonProvider>, honors its `theme` prop ("light" | "dark" | "system")
+ * and any registered brand `colors`. If used standalone (no provider), falls back to the
+ * device's OS color scheme and the library's default palette.
+ *
+ * @param colorVariant optional brand color variant name registered on the provider
+ */
+export function useSkeletonTheme(colorVariant?: string): ResolvedSkeletonTheme {
+    const ctx = useContext(SkeletonContext);
+    const systemScheme = useColorScheme();
+
+    return useMemo(() => {
+        if (ctx) {
+            const colors = ctx.getVariantColors(colorVariant);
+            return {
+                isDark: ctx.isDark,
+                background: colors.background,
+                highlight: colors.highlight,
+            };
+        }
+
+        const isDark = systemScheme === "dark";
+        const fallback = getDefaultThemeColors(isDark);
+
+        const colors = resolveThemeColors({
+            isDark,
+            ambient: fallback,
+        });
+
+        return {
+            isDark,
+            background: colors.background,
+            highlight: colors.highlight,
+        };
+    }, [ctx, systemScheme, colorVariant]);
+}

package/src/index.ts

@@ -0,0 +1,94 @@
+import SkeletonBase from "./components/Skeleton";
+import Rect from "./components/Rect";
+import Circle from "./components/Circle";
+import Square from "./components/Square";
+import Pill from "./components/Pill";
+import Group from "./components/Group";
+
+import Profile from "./presets/Profile";
+import Card from "./presets/Card";
+import Chat from "./presets/Chat";
+import Product from "./presets/Product";
+import Video from "./presets/Video";
+
+import SkeletonClone from "./clone/SkeletonClone";
+
+export { SkeletonProvider, SkeletonContext } from "./providers/SkeletonProvider";
+export { useSkeletonTheme } from "./hooks/useSkeletonTheme";
+export { useReducedMotion } from "./hooks/useReducedMotion";
+
+export type {
+    SkeletonAnimation,
+    SkeletonPerformanceMode,
+    SkeletonThemeMode,
+    SkeletonThemeColors,
+    SkeletonBrandColors,
+    ResolvedSkeletonTheme,
+    SkeletonProps,
+    SkeletonCircleProps,
+    SkeletonSquareProps,
+    SkeletonPillProps,
+    SkeletonGroupProps,
+    SkeletonContextValue,
+    SkeletonProviderProps,
+    SkeletonCloneShape,
+    SkeletonCloneNode,
+    SkeletonCloneProps,
+    SkeletonPresetProps,
+    SkeletonProfilePresetProps,
+    SkeletonCardPresetProps,
+    SkeletonChatPresetProps,
+    SkeletonProductPresetProps,
+    SkeletonVideoPresetProps,
+    ScreenSizeClass,
+} from "./types";
+
+/**
+ * `Skeleton` is the library's primary export: a callable base component
+ * (`<Skeleton />`) that also carries every shape, the layout-grouping
+ * helper, and every smart preset as static properties — so you only ever
+ * need a single import.
+ *
+ * @example
+ * import { Skeleton, SkeletonProvider } from "react-native-smart-skeleton";
+ *
+ * <SkeletonProvider>
+ *   <Skeleton.Rect width={200} height={20} />
+ *   <Skeleton.Circle size={48} />
+ *   <Skeleton.Profile lines={2} />
+ * </SkeletonProvider>
+ */
+type SkeletonComponent = typeof SkeletonBase & {
+    Rect: typeof Rect;
+    Circle: typeof Circle;
+    Square: typeof Square;
+    Pill: typeof Pill;
+    Group: typeof Group;
+    Clone: typeof SkeletonClone;
+    Profile: typeof Profile;
+    Card: typeof Card;
+    Chat: typeof Chat;
+    Product: typeof Product;
+    Video: typeof Video;
+};
+
+const Skeleton = SkeletonBase as SkeletonComponent;
+
+Skeleton.Rect = Rect;
+Skeleton.Circle = Circle;
+Skeleton.Square = Square;
+Skeleton.Pill = Pill;
+Skeleton.Group = Group;
+Skeleton.Clone = SkeletonClone;
+Skeleton.Profile = Profile;
+Skeleton.Card = Card;
+Skeleton.Chat = Chat;
+Skeleton.Product = Product;
+Skeleton.Video = Video;
+
+export { Skeleton };
+export { SkeletonBase };
+export { Rect, Circle, Square, Pill, Group, SkeletonClone };
+export { Profile, Card, Chat, Product, Video };
+
+export default Skeleton;

package/src/presets/Card.tsx

@@ -0,0 +1,56 @@
+import React from "react";
+import { View } from "react-native";
+import Skeleton from "../components/Skeleton";
+import Circle from "../components/Circle";
+import Group from "../components/Group";
+import type { SkeletonCardPresetProps, SkeletonProps } from "../types";
+
+/**
+ * A ready-made skeleton block mimicking a typical content card: an image
+ * area on top, optionally a small avatar + name row, then body text lines.
+ *
+ * @example
+ * <Skeleton.Card imageHeight={160} lines={3} />
+ */
+export default function Card({
+    imageHeight = 160,
+    lines = 3,
+    showAvatar = false,
+    count = 1,
+    gap = 20,
+    animation,
+    style,
+    testID,
+}: SkeletonCardPresetProps) {
+    return (
+        <View style={style} testID={testID}>
+            {Array.from({ length: count }).map((_, blockIndex) => (
+                <View key={blockIndex} style={{ marginTop: blockIndex === 0 ? 0 : gap }}>
+                    <Skeleton width="100%" height={imageHeight} borderRadius={12} animation={animation} />
+
+                    {showAvatar && (
+                        <View style={{ flexDirection: "row", alignItems: "center", marginTop: 12 }}>
+                            <Circle size={32} animation={animation} />
+                            <Skeleton width="40%" height={12} style={{ marginLeft: 8 }} animation={animation} />
+                        </View>
+                    )}
+
+                    <Group
+                        staggerDelay={60}
+                        animation={animation}
+                        style={{ marginTop: showAvatar ? 12 : 16 }}
+                    >
+                        {Array.from({ length: lines }, (__, lineIndex) => {
+                            const lineProps: SkeletonProps = {
+                                width: lineIndex === lines - 1 ? "50%" : "100%",
+                                height: 12,
+                                style: { marginTop: lineIndex === 0 ? 0 : 8 },
+                            };
+                            return <Skeleton key={lineIndex} {...lineProps} />;
+                        })}
+                    </Group>
+                </View>
+            ))}
+        </View>
+    );
+}

package/src/presets/Chat.tsx

@@ -0,0 +1,52 @@
+import React from "react";
+import { View } from "react-native";
+import Skeleton from "../components/Skeleton";
+import type { SkeletonChatPresetProps } from "../types";
+
+const BUBBLE_WIDTHS = ["55%", "70%", "45%", "62%"];
+
+/**
+ * A ready-made skeleton block mimicking a chat conversation: a series of
+ * message bubbles, alternating left/right alignment by default to read as
+ * a two-party conversation while loading.
+ *
+ * @example
+ * <Skeleton.Chat messages={5} />
+ */
+export default function Chat({
+    messages = 4,
+    alternate = true,
+    gap = 12,
+    animation,
+    style,
+    testID,
+}: SkeletonChatPresetProps) {
+    return (
+        <View style={style} testID={testID}>
+            {Array.from({ length: messages }).map((_, index) => {
+                const isRight = alternate && index % 2 === 1;
+                const width = BUBBLE_WIDTHS[index % BUBBLE_WIDTHS.length];
+                const height = 18 + ((index % 3) * 6);
+
+                return (
+                    <View
+                        key={index}
+                        style={{
+                            flexDirection: "row",
+                            justifyContent: isRight ? "flex-end" : "flex-start",
+                            marginTop: index === 0 ? 0 : gap,
+                        }}
+                    >
+                        <Skeleton
+                            width={width}
+                            height={height}
+                            borderRadius={14}
+                            animation={animation}
+                            delay={index * 70}
+                        />
+                    </View>
+                );
+            })}
+        </View>
+    );
+}

package/src/presets/Product.tsx

@@ -0,0 +1,45 @@
+import React from "react";
+import { View } from "react-native";
+import Skeleton from "../components/Skeleton";
+import { getRecommendedColumns } from "../utils/responsive";
+import type { SkeletonProductPresetProps } from "../types";
+
+/**
+ * A ready-made skeleton grid mimicking a product listing (e.g. e-commerce
+ * catalog or search results): square-ish image, title line, and price line,
+ * tiled into a responsive grid.
+ *
+ * @example
+ * <Skeleton.Product count={6} columns={2} />
+ */
+export default function Product({
+    imageHeight = 140,
+    columns,
+    count = 4,
+    gap = 16,
+    animation,
+    style,
+    testID,
+}: SkeletonProductPresetProps) {
+    const resolvedColumns = columns ?? getRecommendedColumns();
+    const itemWidth = `${100 / resolvedColumns}%`;
+
+    return (
+        <View style={[{ flexDirection: "row", flexWrap: "wrap" }, style]} testID={testID}>
+            {Array.from({ length: count }).map((_, index) => (
+                <View
+                    key={index}
+                    style={{
+                        width: itemWidth as any,
+                        paddingHorizontal: gap / 2,
+                        marginBottom: gap,
+                    }}
+                >
+                    <Skeleton width="100%" height={imageHeight} borderRadius={10} animation={animation} delay={index * 40} />
+                    <Skeleton width="80%" height={12} style={{ marginTop: 8 }} animation={animation} delay={index * 40} />
+                    <Skeleton width="40%" height={12} style={{ marginTop: 6 }} animation={animation} delay={index * 40} />
+                </View>
+            ))}
+        </View>
+    );
+}

package/src/presets/Profile.tsx

@@ -0,0 +1,54 @@
+import React from "react";
+import { View } from "react-native";
+import Skeleton from "../components/Skeleton";
+import Circle from "../components/Circle";
+import Group from "../components/Group";
+import type { SkeletonProfilePresetProps, SkeletonProps } from "../types";
+
+/**
+ * A ready-made skeleton block mimicking a profile header: a circular avatar
+ * beside a name line and one or more secondary text lines (e.g. handle/bio).
+ *
+ * @example
+ * <Skeleton.Profile avatarSize={56} lines={2} />
+ */
+export default function Profile({
+    avatarSize = 56,
+    lines = 2,
+    count = 1,
+    gap = 16,
+    animation,
+    style,
+    testID,
+}: SkeletonProfilePresetProps) {
+    return (
+        <View style={style} testID={testID}>
+            {Array.from({ length: count }).map((_, blockIndex) => (
+                <View
+                    key={blockIndex}
+                    style={{
+                        flexDirection: "row",
+                        alignItems: "center",
+                        marginTop: blockIndex === 0 ? 0 : gap,
+                    }}
+                >
+                    <Circle size={avatarSize} animation={animation} />
+                    <Group
+                        staggerDelay={60}
+                        animation={animation}
+                        style={{ marginLeft: 12, flex: 1 }}
+                    >
+                        {Array.from({ length: lines }, (__, lineIndex) => {
+                            const lineProps: SkeletonProps = {
+                                width: lineIndex === 0 ? "60%" : `${85 - lineIndex * 15}%`,
+                                height: lineIndex === 0 ? 16 : 12,
+                                style: { marginTop: lineIndex === 0 ? 0 : 8 },
+                            };
+                            return <Skeleton key={lineIndex} {...lineProps} />;
+                        })}
+                    </Group>
+                </View>
+            ))}
+        </View>
+    );
+}

package/src/presets/Video.tsx

@@ -0,0 +1,53 @@
+import React from "react";
+import { View } from "react-native";
+import Skeleton from "../components/Skeleton";
+import Circle from "../components/Circle";
+import type { SkeletonVideoPresetProps } from "../types";
+
+/**
+ * A ready-made skeleton block mimicking a video list item: a video
+ * thumbnail at a given aspect ratio, optionally followed by a channel
+ * avatar + title row and a meta line (views / date).
+ *
+ * @example
+ * <Skeleton.Video aspectRatio={16 / 9} showTitle showMeta />
+ */
+export default function Video({
+    aspectRatio = 16 / 9,
+    showTitle = true,
+    showMeta = true,
+    count = 1,
+    gap = 20,
+    animation,
+    style,
+    testID,
+}: SkeletonVideoPresetProps) {
+    return (
+        <View style={style} testID={testID}>
+            {Array.from({ length: count }).map((_, index) => (
+                <View key={index} style={{ marginTop: index === 0 ? 0 : gap }}>
+                    <View style={{ width: "100%", aspectRatio }}>
+                        <Skeleton width="100%" height="100%" borderRadius={10} animation={animation} />
+                    </View>
+
+                    {(showTitle || showMeta) && (
+                        <View style={{ flexDirection: "row", marginTop: 10 }}>
+                            <Circle size={36} animation={animation} />
+                            <View style={{ marginLeft: 10, flex: 1 }}>
+                                {showTitle && <Skeleton width="90%" height={14} animation={animation} />}
+                                {showMeta && (
+                                    <Skeleton
+                                        width="50%"
+                                        height={11}
+                                        style={{ marginTop: 6 }}
+                                        animation={animation}
+                                    />
+                                )}
+                            </View>
+                        </View>
+                    )}
+                </View>
+            ))}
+        </View>
+    );
+}