react-native-smart-skeleton 0.0.1

package/src/providers/SkeletonProvider.tsx

@@ -0,0 +1,67 @@
+import React, { createContext, useMemo } from "react";
+import { I18nManager, useColorScheme } from "react-native";
+import { useReducedMotion } from "../hooks/useReducedMotion";
+import { resolveIsDark, getDefaultThemeColors } from "../utils/theme";
+import { resolveThemeColors } from "../utils/colors";
+import type { SkeletonContextValue, SkeletonProviderProps, SkeletonThemeColors } from "../types";
+
+export const SkeletonContext = createContext<SkeletonContextValue | null>(null);
+
+/**
+ * Global configuration provider for react-native-smart-skeleton.
+ *
+ * Wrap your app (or a subtree) once to set defaults for theme, animation,
+ * duration, performance mode, RTL, reduced-motion override, and brand colors.
+ * Any individual Skeleton component can still override these via its own props.
+ *
+ * @example
+ * <SkeletonProvider theme="system" animation="shimmer" duration={1200}>
+ *   <App />
+ * </SkeletonProvider>
+ */
+export function SkeletonProvider({
+    children,
+    theme = "system",
+    animation = "shimmer",
+    duration = 1200,
+    performanceMode = "balanced",
+    rtl,
+    reducedMotion: reducedMotionOverride,
+    colors,
+}: SkeletonProviderProps) {
+    const systemScheme = useColorScheme();
+    const osReducedMotion = useReducedMotion();
+
+    const isDark = resolveIsDark(theme, systemScheme);
+    const reducedMotion = reducedMotionOverride ?? osReducedMotion;
+    const resolvedRtl = rtl ?? I18nManager.isRTL;
+
+    const value = useMemo<SkeletonContextValue>(() => {
+        const ambient = getDefaultThemeColors(isDark);
+
+        const getVariantColors = (variant?: string): SkeletonThemeColors =>
+            resolveThemeColors({
+                colorVariant: variant,
+                isDark,
+                brandColors: colors,
+                ambient,
+            });
+
+        return {
+            theme,
+            isDark,
+            animation,
+            duration,
+            performanceMode,
+            reducedMotion,
+            rtl: resolvedRtl,
+            colors,
+            resolvedColors: ambient,
+            getVariantColors,
+        };
+    }, [theme, isDark, animation, duration, performanceMode, reducedMotion, resolvedRtl, colors]);
+
+    return <SkeletonContext.Provider value={value}>{children}</SkeletonContext.Provider>;
+}
+
+export default SkeletonProvider;

package/src/types/index.ts

@@ -0,0 +1,246 @@
+import type React from "react";
+import type {
+    ViewStyle,
+    StyleProp,
+    DimensionValue,
+} from "react-native";
+
+export type SkeletonDimensionValue = number | string | "auto" | undefined;
+
+/* -------------------------------------------------------------------------- */
+/*  Animations                                                               */
+/* -------------------------------------------------------------------------- */
+
+export type SkeletonAnimation =
+    | "shimmer"
+    | "pulse"
+    | "wave"
+    | "breathing"
+    | "none";
+
+/* -------------------------------------------------------------------------- */
+/*  Performance                                                              */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Controls how much work the animation driver does.
+ * - "high": full fidelity (gradients, smooth easing)
+ * - "balanced": default, good fidelity with cheaper easing curves
+ * - "battery-saver": reduces frame work, simpler interpolations, longer durations
+ */
+export type SkeletonPerformanceMode = "high" | "balanced" | "battery-saver";
+
+/* -------------------------------------------------------------------------- */
+/*  Theme                                                                    */
+/* -------------------------------------------------------------------------- */
+
+export type SkeletonThemeMode = "light" | "dark" | "system";
+
+export interface SkeletonThemeColors {
+    background: string;
+    highlight: string;
+}
+
+export interface SkeletonBrandColors {
+    light: SkeletonThemeColors;
+    dark: SkeletonThemeColors;
+}
+
+export interface ResolvedSkeletonTheme extends SkeletonThemeColors {
+    isDark: boolean;
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Shared shape props                                                       */
+/* -------------------------------------------------------------------------- */
+
+export interface SkeletonProps {
+    /** Width of the skeleton. */
+    width?: SkeletonDimensionValue;
+
+    /** Height of the skeleton. */
+    height?: SkeletonDimensionValue;
+
+    borderRadius?: number;
+
+    backgroundColor?: string;
+    highlightColor?: string;
+    gradientColors?: string[];
+
+    animation?: SkeletonAnimation;
+    duration?: number;
+    delay?: number;
+    rtl?: boolean;
+    colorVariant?: string;
+
+    /** Style overrides */
+    style?: StyleProp<ViewStyle>;
+
+    accessibilityLabel?: string;
+
+    accessible?: boolean;
+    testID?: string;
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Shape-specific props                                                     */
+/* -------------------------------------------------------------------------- */
+
+export interface SkeletonCircleProps extends Omit<SkeletonProps, "width" | "height" | "borderRadius"> {
+    /** Diameter of the circle. Defaults to 50. */
+    size?: number;
+}
+
+export interface SkeletonSquareProps extends Omit<SkeletonProps, "width" | "height"> {
+    /** Side length of the square. Defaults to 50. */
+    size?: number;
+}
+
+export interface SkeletonPillProps extends SkeletonProps {
+    /** Width of the pill. Defaults to 80. */
+    width?: SkeletonDimensionValue;
+
+    /** Height of the pill. Defaults to 24. */
+    height?: SkeletonDimensionValue;
+}
+/* -------------------------------------------------------------------------- */
+/*  Group / stagger                                                          */
+/* -------------------------------------------------------------------------- */
+
+export interface SkeletonGroupProps {
+    children: React.ReactNode;
+    /** Delay added between each direct child's animation start, in ms. Defaults to 80. */
+    staggerDelay?: number;
+    /** Animation applied to all children unless a child overrides it. */
+    animation?: SkeletonAnimation;
+    /** Layout direction for stagger ordering. Defaults to "column". */
+    direction?: "row" | "column";
+    style?: ViewStyle;
+    testID?: string;
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Provider / context                                                      */
+/* -------------------------------------------------------------------------- */
+
+export interface SkeletonContextValue {
+    theme: SkeletonThemeMode;
+    isDark: boolean;
+    animation: SkeletonAnimation;
+    duration: number;
+    performanceMode: SkeletonPerformanceMode;
+    reducedMotion: boolean;
+    rtl: boolean;
+    colors?: Record<string, SkeletonBrandColors>;
+    resolvedColors: SkeletonThemeColors;
+    getVariantColors: (variant?: string) => SkeletonThemeColors;
+}
+
+export interface SkeletonProviderProps {
+    children: React.ReactNode;
+    /** "light" | "dark" | "system" (default). */
+    theme?: SkeletonThemeMode;
+    /** Default animation for all descendant skeletons. Defaults to "shimmer". */
+    animation?: SkeletonAnimation;
+    /** Default animation loop duration in ms. Defaults to 1200. */
+    duration?: number;
+    /** Default performance mode. Defaults to "balanced". */
+    performanceMode?: SkeletonPerformanceMode;
+    /** Force-enable/disable RTL mirroring. Defaults to following I18nManager. */
+    rtl?: boolean;
+    /** Force reduced-motion behavior regardless of OS setting. */
+    reducedMotion?: boolean;
+    /** Named brand color palettes, keyed by variant name, each with light/dark colors. */
+    colors?: Record<string, SkeletonBrandColors>;
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Layout cloning                                                          */
+/* -------------------------------------------------------------------------- */
+
+export type SkeletonCloneShape = "rect" | "circle" | "pill";
+
+// export interface SkeletonCloneNode {
+//     /** Shape to render for this node. Defaults to "rect". */
+//     shape?: SkeletonCloneShape;
+//     width?: number | string;
+//     height?: number | string;
+//     borderRadius?: number;
+//     style?: ViewStyle;
+//     /** Nested children, laid out according to `direction`. */
+//     children?: SkeletonCloneNode[];
+//     /** Layout direction for this node's children. Defaults to "column". */
+//     direction?: "row" | "column";
+//     /** Gap between this node's children, in dp. Defaults to 8. */
+//     gap?: number;
+// }
+
+
+export interface SkeletonCloneNode {
+    shape?: "rect" | "circle" | "pill";
+    width?: SkeletonDimensionValue;
+    height?: SkeletonDimensionValue;
+
+    borderRadius?: number;
+    style?: StyleProp<ViewStyle>;
+
+    children?: SkeletonCloneNode[];
+    direction?: "row" | "column";
+    gap?: number;
+}
+
+export interface SkeletonCloneProps {
+    /** Declarative layout tree describing the real content's shape. */
+    layout: SkeletonCloneNode;
+    animation?: SkeletonAnimation;
+    style?: ViewStyle;
+    testID?: string;
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Presets                                                                  */
+/* -------------------------------------------------------------------------- */
+
+export interface SkeletonPresetProps {
+    /** Number of times to repeat this preset block. Defaults to 1. */
+    count?: number;
+    /** Gap between repeated blocks, in dp. Defaults to 16. */
+    gap?: number;
+    animation?: SkeletonAnimation;
+    style?: ViewStyle;
+    testID?: string;
+}
+
+export interface SkeletonProfilePresetProps extends SkeletonPresetProps {
+    avatarSize?: number;
+    lines?: number;
+}
+
+export interface SkeletonCardPresetProps extends SkeletonPresetProps {
+    imageHeight?: number;
+    lines?: number;
+    showAvatar?: boolean;
+}
+
+export interface SkeletonChatPresetProps extends SkeletonPresetProps {
+    messages?: number;
+    /** Alternate bubble alignment left/right to mimic a real conversation. Defaults to true. */
+    alternate?: boolean;
+}
+
+export interface SkeletonProductPresetProps extends SkeletonPresetProps {
+    imageHeight?: number;
+    columns?: number;
+}
+
+export interface SkeletonVideoPresetProps extends SkeletonPresetProps {
+    aspectRatio?: number;
+    showTitle?: boolean;
+    showMeta?: boolean;
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Responsive utils                                                        */
+/* -------------------------------------------------------------------------- */
+
+export type ScreenSizeClass = "compact" | "regular" | "wide";

package/src/utils/colors.ts

@@ -0,0 +1,132 @@
+import type { SkeletonBrandColors, SkeletonThemeColors } from "../types";
+
+/**
+ * Default light/dark palettes used when no brand colors or explicit
+ * backgroundColor/highlightColor are supplied.
+ */
+export const DEFAULT_LIGHT_COLORS: SkeletonThemeColors = {
+    background: "#E5E7EB",
+    highlight: "#F3F4F6",
+};
+
+export const DEFAULT_DARK_COLORS: SkeletonThemeColors = {
+    background: "#2D3748",
+    highlight: "#4A5568",
+};
+
+/**
+ * Clamp a number between 0 and 255.
+ */
+function clampChannel(value: number): number {
+    return Math.max(0, Math.min(255, Math.round(value)));
+}
+
+/**
+ * Parse a hex color (#RGB, #RRGGBB, #RRGGBBAA) into r/g/b/a channels.
+ * Returns null if the string isn't a parseable hex color.
+ */
+export function parseHexColor(
+    hex: string
+): { r: number; g: number; b: number; a: number } | null {
+    const normalized = hex.trim().replace("#", "");
+
+    if (normalized.length === 3) {
+        const r = parseInt(normalized[0] + normalized[0], 16);
+        const g = parseInt(normalized[1] + normalized[1], 16);
+        const b = parseInt(normalized[2] + normalized[2], 16);
+        return { r, g, b, a: 1 };
+    }
+
+    if (normalized.length === 6) {
+        const r = parseInt(normalized.slice(0, 2), 16);
+        const g = parseInt(normalized.slice(2, 4), 16);
+        const b = parseInt(normalized.slice(4, 6), 16);
+        return { r, g, b, a: 1 };
+    }
+
+    if (normalized.length === 8) {
+        const r = parseInt(normalized.slice(0, 2), 16);
+        const g = parseInt(normalized.slice(2, 4), 16);
+        const b = parseInt(normalized.slice(4, 6), 16);
+        const a = parseInt(normalized.slice(6, 8), 16) / 255;
+        return { r, g, b, a };
+    }
+
+    return null;
+}
+
+/**
+ * Convert an rgb/rgba channel set back into a CSS rgba() string.
+ */
+export function toRgbaString(r: number, g: number, b: number, a: number): string {
+    return `rgba(${clampChannel(r)}, ${clampChannel(g)}, ${clampChannel(b)}, ${Math.max(
+        0,
+        Math.min(1, a)
+    )})`;
+}
+
+/**
+ * Lighten or darken a hex color by a percentage (-1 to 1).
+ * Positive amount lightens, negative darkens. Non-hex input is returned unchanged.
+ */
+export function shadeColor(hex: string, amount: number): string {
+    const parsed = parseHexColor(hex);
+    if (!parsed) return hex;
+
+    const { r, g, b, a } = parsed;
+    const factor = amount;
+
+    const adjust = (channel: number) =>
+        factor >= 0
+            ? channel + (255 - channel) * factor
+            : channel + channel * factor;
+
+    return toRgbaString(adjust(r), adjust(g), adjust(b), a);
+}
+
+/**
+ * Given a hex/rgba color, return a translucent rgba() version at the given opacity.
+ * Falls back to the original string if it isn't parseable (e.g. already rgba(), or a named color).
+ */
+export function withOpacity(color: string, opacity: number): string {
+    const parsed = parseHexColor(color);
+    if (!parsed) return color;
+    return toRgbaString(parsed.r, parsed.g, parsed.b, opacity);
+}
+
+/**
+ * Resolve the {background, highlight} pair to use for a skeleton, given (in priority order):
+ * 1. explicit backgroundColor/highlightColor props
+ * 2. a brand color variant (colorVariant + colors map from the provider)
+ * 3. the ambient theme colors resolved from useSkeletonTheme
+ */
+export function resolveThemeColors(params: {
+    backgroundColor?: string;
+    highlightColor?: string;
+    colorVariant?: string;
+    isDark: boolean;
+    brandColors?: Record<string, SkeletonBrandColors>;
+    ambient: SkeletonThemeColors;
+}): SkeletonThemeColors {
+    const { backgroundColor, highlightColor, colorVariant, isDark, brandColors, ambient } = params;
+
+    let base: SkeletonThemeColors = ambient;
+
+    if (colorVariant && brandColors && brandColors[colorVariant]) {
+        const variant = brandColors[colorVariant];
+        base = isDark ? variant.dark : variant.light;
+    }
+
+    return {
+        background: backgroundColor ?? base.background,
+        highlight: highlightColor ?? base.highlight,
+    };
+}
+
+/**
+ * Build a 3-stop gradient color array from a background/highlight pair,
+ * matching the classic skeleton "sweep" look: base -> highlight -> base.
+ */
+export function buildSweepGradient(background: string, highlight: string): string[] {
+    return [background, highlight, background];
+}

package/src/utils/responsive.ts

@@ -0,0 +1,73 @@
+import { Dimensions, PixelRatio } from "react-native";
+import type { ScreenSizeClass } from "../types";
+
+/**
+ * Breakpoints (in dp) used to classify the current screen width.
+ * Roughly: phones -> "compact", small tablets / large phones landscape -> "regular",
+ * tablets / desktop-like windows -> "wide".
+ */
+const BREAKPOINTS = {
+    regular: 480,
+    wide: 768,
+};
+
+/**
+ * Returns the current window width, with a safe fallback for environments
+ * where Dimensions may not be ready (e.g. very early app boot, tests).
+ */
+export function getScreenWidth(): number {
+    try {
+        const { width } = Dimensions.get("window");
+        return width || 0;
+    } catch {
+        return 0;
+    }
+}
+
+/**
+ * Classify the current screen width into a coarse size bucket, useful for
+ * preset components that want to adapt column counts or avatar sizes.
+ */
+export function getScreenSizeClass(width: number = getScreenWidth()): ScreenSizeClass {
+    if (width >= BREAKPOINTS.wide) return "wide";
+    if (width >= BREAKPOINTS.regular) return "regular";
+    return "compact";
+}
+
+/**
+ * Scale a base dp value by the size class, useful for nudging preset
+ * dimensions (avatar size, line height) up slightly on larger screens.
+ */
+export function scaleBySize(base: number, sizeClass: ScreenSizeClass): number {
+    switch (sizeClass) {
+        case "wide":
+            return Math.round(base * 1.25);
+        case "regular":
+            return Math.round(base * 1.1);
+        default:
+            return base;
+    }
+}
+
+/**
+ * Resolve a recommended column count for grid-style presets (e.g. Product),
+ * based on the current screen size class.
+ */
+export function getRecommendedColumns(sizeClass: ScreenSizeClass = getScreenSizeClass()): number {
+    switch (sizeClass) {
+        case "wide":
+            return 4;
+        case "regular":
+            return 3;
+        default:
+            return 2;
+    }
+}
+
+/**
+ * Snap a dp value to the nearest physical pixel, reducing anti-aliased/blurry
+ * edges on skeleton borders, similar to React Native's own hairline handling.
+ */
+export function pixelSnap(value: number): number {
+    return PixelRatio.roundToNearestPixel(value);
+}

package/src/utils/theme.ts

@@ -0,0 +1,35 @@
+import { Appearance } from "react-native";
+import type { SkeletonThemeMode } from "../types";
+import { DEFAULT_DARK_COLORS, DEFAULT_LIGHT_COLORS } from "./colors";
+
+/**
+ * Resolve a SkeletonThemeMode ("light" | "dark" | "system") plus the current
+ * OS color scheme into a concrete isDark boolean.
+ */
+export function resolveIsDark(mode: SkeletonThemeMode, systemScheme: "light" | "dark" | null | undefined): boolean {
+    if (mode === "light") return false;
+    if (mode === "dark") return true;
+    return systemScheme === "dark";
+}
+
+/**
+ * Synchronous read of the current system color scheme, for use outside
+ * of component render (e.g. computing an initial value).
+ */
+export function getSystemColorScheme():
+    | "light"
+    | "dark"
+    | null {
+    try {
+        return Appearance.getColorScheme() ?? null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Default theme colors for a resolved dark/light state.
+ */
+export function getDefaultThemeColors(isDark: boolean) {
+    return isDark ? DEFAULT_DARK_COLORS : DEFAULT_LIGHT_COLORS;
+}