react-native-skelo 0.0.1 → 0.0.2

package/src/animations/ShimmerAnimation.tsx

@@ -0,0 +1,169 @@
+import React, { useEffect } from 'react';
+import type { DimensionValue, StyleProp, ViewStyle } from 'react-native';
+import { StyleSheet, View } from 'react-native';
+import Animated, {
+  useSharedValue,
+  useAnimatedStyle,
+  withRepeat,
+  withTiming,
+  interpolate,
+  Easing,
+} from 'react-native-reanimated';
+import { LinearGradient } from 'react-native-linear-gradient';
+
+interface ShimmerProps {
+  /**
+   * Width of the shimmer container
+   */
+  width?: DimensionValue;
+
+  /**
+   * Height of the shimmer container
+   */
+  height?: DimensionValue;
+
+  /**
+   * Base color of the skeleton
+   * @default '#E1E9EE'
+   */
+  baseColor?: string;
+
+  /**
+   * Highlight color that shimmers across
+   * @default '#F2F8FC'
+   */
+  highlightColor?: string;
+
+  /**
+   * Animation duration in milliseconds
+   * @default 1500
+   */
+  duration?: number;
+
+  /**
+   * Border radius
+   */
+  borderRadius?: number;
+
+  /**
+   * Additional styles
+   */
+  style?: StyleProp<ViewStyle>;
+
+  /**
+   * Child content (rendered on top of shimmer)
+   */
+  children?: React.ReactNode;
+}
+
+/**
+ * Shimmer animation component using Reanimated 3
+ *
+ * Creates a smooth left-to-right shimmer effect using:
+ * - Shared values for performance
+ * - Worklets for 60 FPS on UI thread
+ * - Linear gradient for shimmer effect
+ *
+ * @example
+ * ```tsx
+ * <ShimmerAnimation
+ *   width={200}
+ *   height={20}
+ *   borderRadius={4}
+ * />
+ * ```
+ */
+export function ShimmerAnimation({
+  width,
+  height,
+  baseColor = '#E1E9EE',
+  highlightColor = '#F2F8FC',
+  duration = 1500,
+  borderRadius = 4,
+  style,
+  children,
+}: ShimmerProps) {
+  // Shared value for animation progress (0 to 1)
+  const progress = useSharedValue(0);
+
+  useEffect(() => {
+    // Start infinite shimmer animation
+    progress.value = withRepeat(
+      withTiming(1, {
+        duration,
+        easing: Easing.linear,
+      }),
+      -1, // Infinite repeat
+      false // Don't reverse
+    );
+  }, [duration, progress]);
+
+  // Animated style for shimmer overlay
+  const animatedStyle = useAnimatedStyle(() => {
+    'worklet';
+
+    // Calculate shimmer position
+    // Interpolate from -100% to 100% to create left-to-right sweep
+    const translateX = interpolate(progress.value, [0, 1], [-1, 1]);
+
+    return {
+      transform: [{ translateX: translateX * (typeof width === 'number' ? width : 200) }],
+    };
+  }, [width]);
+
+  return (
+    <View
+      style={[
+        styles.container,
+        {
+          width,
+          height,
+          borderRadius,
+          backgroundColor: baseColor,
+        },
+        style,
+      ]}
+    >
+      {/* Shimmer gradient overlay */}
+      <Animated.View
+        style={[
+          StyleSheet.absoluteFill,
+          {
+            overflow: 'hidden',
+            borderRadius,
+          },
+        ]}
+      >
+        <Animated.View
+          style={[
+            styles.shimmer,
+            {
+              width: typeof width === 'number' ? width : '100%',
+              height: '100%',
+            },
+            animatedStyle,
+          ]}
+        >
+          <LinearGradient
+            colors={[baseColor, highlightColor, highlightColor, baseColor]}
+            start={{ x: 0, y: 0 }}
+            end={{ x: 1, y: 0 }}
+            style={StyleSheet.absoluteFill}
+          />
+        </Animated.View>
+      </Animated.View>
+
+      {/* Child content */}
+      {children}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    overflow: 'hidden',
+  },
+  shimmer: {
+    position: 'absolute',
+  },
+});

package/src/animations/index.ts

@@ -0,0 +1,4 @@
+export { ShimmerAnimation } from './ShimmerAnimation';
+export { PulseAnimation } from './PulseAnimation';
+export { AnimationWrapper } from './AnimationWrapper';
+export type { AnimationType } from './AnimationWrapper';

package/src/components/MeasuredBlock.tsx

@@ -0,0 +1,85 @@
+import React, { useState } from 'react';
+import type { LayoutChangeEvent } from 'react-native';
+import { StyleSheet, View } from 'react-native';
+import type { ReactNode } from 'react';
+import type { SkeletonConfig } from '../types';
+import { AnimationWrapper } from '../animations';
+
+interface MeasuredBlockProps {
+  /**
+   * The real element to render (hidden) and measure.
+   */
+  children: ReactNode;
+
+  /**
+   * Skeleton configuration (animation, colors, etc.)
+   */
+  config: SkeletonConfig;
+}
+
+interface Size {
+  width: number;
+  height: number;
+}
+
+/**
+ * Renders an opaque (non-host) component hidden so it lays out at its real
+ * size, measures that size via `onLayout`, then overlays a shimmer block of
+ * exactly those dimensions.
+ *
+ * This is Skelo's runtime-measurement fallback: when the parser can't
+ * introspect a component (e.g. a user-defined function component), we can't
+ * know its internal View/Text/Image structure without native view-tree access,
+ * but we *can* render it off-screen and reproduce its footprint accurately.
+ *
+ * The result is a single, correctly-sized skeleton block rather than a
+ * misleading fixed-size placeholder.
+ */
+export function MeasuredBlock({ children, config }: MeasuredBlockProps) {
+  const [size, setSize] = useState<Size | null>(null);
+
+  const handleLayout = (event: LayoutChangeEvent) => {
+    const { width, height } = event.nativeEvent.layout;
+    setSize(prev =>
+      prev && prev.width === width && prev.height === height ? prev : { width, height }
+    );
+  };
+
+  return (
+    <View>
+      {/* Real content, rendered invisibly purely to occupy space + measure. */}
+      <View
+        style={styles.hidden}
+        pointerEvents="none"
+        importantForAccessibility="no-hide-descendants"
+        accessibilityElementsHidden
+        onLayout={handleLayout}
+      >
+        {children}
+      </View>
+
+      {/* Size-matched shimmer overlay, shown once measured. */}
+      {size && size.width > 0 && size.height > 0 && (
+        <View style={StyleSheet.absoluteFill} pointerEvents="none">
+          <AnimationWrapper
+            animation={config.animation}
+            width={size.width}
+            height={size.height}
+            baseColor={config.baseColor}
+            highlightColor={config.highlightColor}
+            duration={config.duration}
+            borderRadius={config.borderRadius}
+          />
+        </View>
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  hidden: {
+    opacity: 0,
+  },
+});
+
+MeasuredBlock.displayName = 'Skeleton.MeasuredBlock';

package/src/components/Skeleton.tsx

@@ -0,0 +1,149 @@
+import React, { useMemo } from 'react';
+import type { SkeletonProps } from '../types';
+import { Parser } from '../core/parser';
+import { SkeletonRenderer } from './SkeletonRenderer';
+import { SkeletonIgnore } from './SkeletonIgnore';
+import { StyleSkeleton } from '../core/generator/StyleSkeleton';
+import { getDeepExpander } from '../core/deepRegistry';
+import { DEFAULT_CONFIG } from '../constants/defaults';
+
+/**
+ * Main Skeleton component
+ *
+ * Automatically generates skeleton loading states for your React Native components.
+ * Wraps your UI and shows skeleton placeholders while loading.
+ *
+ * @example
+ * ```tsx
+ * <Skeleton loading={isLoading}>
+ *   <ProfileScreen />
+ * </Skeleton>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <Skeleton
+ *   loading={isLoading}
+ *   animation="pulse"
+ *   baseColor="#f0f0f0"
+ *   highlightColor="#ffffff"
+ * >
+ *   <View>
+ *     <Text>Hello World</Text>
+ *     <Image source={avatar} />
+ *   </View>
+ * </Skeleton>
+ * ```
+ */
+export function Skeleton({
+  loading,
+  children,
+  styles,
+  excludeStyles,
+  deep = false,
+  animation = DEFAULT_CONFIG.animation,
+  duration = DEFAULT_CONFIG.duration,
+  baseColor = DEFAULT_CONFIG.baseColor,
+  highlightColor = DEFAULT_CONFIG.highlightColor,
+  borderRadius = DEFAULT_CONFIG.borderRadius,
+  accessible = true,
+  accessibilityLabel = 'Loading content',
+  debug = false,
+}: SkeletonProps) {
+  // Parse component tree and generate skeleton.
+  // Hooks must run unconditionally (rules of hooks), but parsing stays lazy:
+  // we skip the work entirely when not loading or in styles-driven mode.
+  const skeletonTree = useMemo(() => {
+    if (!loading || styles) {
+      return [];
+    }
+
+    if (__DEV__ && debug) {
+      console.log('[Skelo] Parsing component tree...');
+    }
+
+    try {
+      // Deep mode: expand opaque components into their real host tree via the
+      // opt-in expander (registered by importing 'react-native-skelo/deep').
+      // Falls back to static parsing if unavailable or it returns nothing.
+      if (deep) {
+        const expand = getDeepExpander();
+        if (expand) {
+          const expanded = expand(<>{children}</>);
+          if (expanded && expanded.length > 0) {
+            return expanded;
+          }
+          if (__DEV__) {
+            console.warn('[Skelo] deep expansion returned nothing; falling back to static parsing.');
+          }
+        } else if (__DEV__) {
+          console.warn(
+            "[Skelo] `deep` requires react-reconciler. Install it and add `import 'react-native-skelo/deep';` in your app entry."
+          );
+        }
+      }
+
+      const parsed = Parser.parse(children);
+
+      if (__DEV__ && debug) {
+        // Log a lightweight summary: the raw nodes hold React elements
+        // (`element`) and arbitrary props that aren't safely serializable.
+        const summarize = (nodes: typeof parsed): unknown =>
+          nodes.map(node => ({
+            type: node.type,
+            style: node.style,
+            children: summarize(node.children),
+          }));
+        console.log('[Skelo] Parsed tree:', JSON.stringify(summarize(parsed), null, 2));
+      }
+
+      return parsed;
+    } catch (error) {
+      if (__DEV__) {
+        console.error('[Skelo] Failed to parse component tree:', error);
+      }
+      return [];
+    }
+  }, [loading, styles, deep, children, debug]);
+
+  // Create skeleton config
+  const config = useMemo(
+    () => ({
+      animation,
+      duration,
+      baseColor,
+      highlightColor,
+      borderRadius,
+    }),
+    [animation, duration, baseColor, highlightColor, borderRadius]
+  );
+
+  // If not loading, render the real children directly.
+  if (!loading) {
+    return <>{children}</>;
+  }
+
+  // Styles-driven mode: derive the skeleton from the provided styles instead of
+  // introspecting the child tree (useful when children are opaque components).
+  if (styles) {
+    return <StyleSkeleton styles={styles} config={config} exclude={excludeStyles} />;
+  }
+
+  return (
+    <SkeletonRenderer
+      tree={skeletonTree}
+      config={config}
+      accessible={accessible}
+      accessibilityLabel={accessibilityLabel}
+      debug={debug}
+    />
+  );
+}
+
+Skeleton.displayName = 'Skeleton';
+
+/**
+ * Escape hatch to keep children as real content inside a loading `<Skeleton>`.
+ * @see SkeletonIgnore
+ */
+Skeleton.Ignore = SkeletonIgnore;

package/src/components/SkeletonIgnore.tsx

@@ -0,0 +1,27 @@
+import React from 'react';
+import type { ReactNode } from 'react';
+
+interface SkeletonIgnoreProps {
+  children?: ReactNode;
+}
+
+/**
+ * Escape hatch that renders its children as real content, even inside a
+ * loading `<Skeleton>`. Use it for elements that should stay visible during
+ * loading — section headings, static labels, action buttons, etc.
+ *
+ * @example
+ * ```tsx
+ * <Skeleton loading={loading}>
+ *   <Skeleton.Ignore>
+ *     <Text>Profile</Text>       // stays as real text
+ *   </Skeleton.Ignore>
+ *   <ProfileCard />              // becomes a skeleton
+ * </Skeleton>
+ * ```
+ */
+export function SkeletonIgnore({ children }: SkeletonIgnoreProps) {
+  return <>{children}</>;
+}
+
+SkeletonIgnore.displayName = 'Skeleton.Ignore';