react-native-skelo 0.1.0-alpha.0 → 0.1.0

package/src/animations/PulseAnimation.tsx

@@ -1,77 +1,19 @@
-import React, { useEffect } from 'react';
+import React, { useEffect, useRef } from 'react';
 import type { DimensionValue, StyleProp, ViewStyle } from 'react-native';
-import { StyleSheet } from 'react-native';
-import Animated, {
-  useSharedValue,
-  useAnimatedStyle,
-  withRepeat,
-  withSequence,
-  withTiming,
-  Easing,
-} from 'react-native-reanimated';
+import { Animated, Easing, StyleSheet } from 'react-native';
 
 interface PulseProps {
-  /**
-   * Width of the pulse container
-   */
   width?: DimensionValue;
-
-  /**
-   * Height of the pulse container
-   */
   height?: DimensionValue;
-
-  /**
-   * Base color of the skeleton
-   * @default '#E1E9EE'
-   */
   baseColor?: string;
-
-  /**
-   * Highlight color for pulse
-   * @default '#F2F8FC'
-   */
   highlightColor?: string;
-
-  /**
-   * Animation duration in milliseconds
-   * @default 1000
-   */
   duration?: number;
-
-  /**
-   * Border radius
-   */
   borderRadius?: number;
-
-  /**
-   * Additional styles
-   */
   style?: StyleProp<ViewStyle>;
-
-  /**
-   * Child content (rendered inside pulse)
-   */
   children?: React.ReactNode;
 }
 
-/**
- * Pulse animation component using Reanimated 3
- *
- * Creates a subtle breathing/pulsing effect using:
- * - Shared values for performance
- * - Worklets for 60 FPS on UI thread
- * - Opacity animation for pulse effect
- *
- * @example
- * ```tsx
- * <PulseAnimation
- *   width={200}
- *   height={20}
- *   borderRadius={4}
- * />
- * ```
- */
+// Breathing opacity loop using React Native's built-in Animated (native driver).
 export function PulseAnimation({
   width,
   height,
@@ -81,48 +23,34 @@ export function PulseAnimation({
   style,
   children,
 }: PulseProps) {
-  // Shared value for opacity (0 to 1)
-  const opacity = useSharedValue(1);
+  const opacity = useRef(new Animated.Value(1)).current;
 
   useEffect(() => {
-    // Start infinite pulse animation
-    // Sequence: fade out -> fade in
-    opacity.value = withRepeat(
-      withSequence(
-        withTiming(0.5, {
+    const loop = Animated.loop(
+      Animated.sequence([
+        Animated.timing(opacity, {
+          toValue: 0.5,
           duration: duration / 2,
           easing: Easing.inOut(Easing.ease),
+          useNativeDriver: true,
         }),
-        withTiming(1, {
+        Animated.timing(opacity, {
+          toValue: 1,
           duration: duration / 2,
           easing: Easing.inOut(Easing.ease),
-        })
-      ),
-      -1, // Infinite repeat
-      false // Don't reverse
+          useNativeDriver: true,
+        }),
+      ])
     );
+    loop.start();
+    return () => loop.stop();
   }, [duration, opacity]);
 
-  // Animated style for pulse effect
-  const animatedStyle = useAnimatedStyle(() => {
-    'worklet';
-
-    return {
-      opacity: opacity.value,
-    };
-  }, []);
-
   return (
     <Animated.View
       style={[
         styles.container,
-        {
-          width,
-          height,
-          borderRadius,
-          backgroundColor: baseColor,
-        },
-        animatedStyle,
+        { width, height, borderRadius, backgroundColor: baseColor, opacity },
         style,
       ]}
     >

package/src/animations/ShimmerAnimation.tsx

@@ -1,78 +1,21 @@
-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';
+import React, { useEffect, useRef, useState } from 'react';
+import type { DimensionValue, LayoutChangeEvent, StyleProp, ViewStyle } from 'react-native';
+import { Animated, Easing, StyleSheet, View } from 'react-native';
 
 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}
- * />
- * ```
- */
+// Zero-dependency shimmer: a highlight band (dim/bright/dim segments to fake a
+// soft gradient) sweeps across the base, driven by React Native's built-in
+// Animated native driver. Plain Views only — guaranteed to render and animate.
 export function ShimmerAnimation({
   width,
   height,
@@ -83,77 +26,49 @@ export function ShimmerAnimation({
   style,
   children,
 }: ShimmerProps) {
-  // Shared value for animation progress (0 to 1)
-  const progress = useSharedValue(0);
+  const progress = useRef(new Animated.Value(0)).current;
+  const [measuredWidth, setMeasuredWidth] = useState(0);
 
   useEffect(() => {
-    // Start infinite shimmer animation
-    progress.value = withRepeat(
-      withTiming(1, {
+    const loop = Animated.loop(
+      Animated.timing(progress, {
+        toValue: 1,
         duration,
         easing: Easing.linear,
-      }),
-      -1, // Infinite repeat
-      false // Don't reverse
+        useNativeDriver: true,
+      })
     );
+    loop.start();
+    return () => loop.stop();
   }, [duration, progress]);
 
-  // Animated style for shimmer overlay
-  const animatedStyle = useAnimatedStyle(() => {
-    'worklet';
+  const onLayout = (event: LayoutChangeEvent) => {
+    const w = event.nativeEvent.layout.width;
+    setMeasuredWidth(prev => (prev === w ? prev : w));
+  };
 
-    // Calculate shimmer position
-    // Interpolate from -100% to 100% to create left-to-right sweep
-    const translateX = interpolate(progress.value, [0, 1], [-1, 1]);
+  const containerWidth = typeof width === 'number' ? width : measuredWidth || 200;
+  const bandWidth = Math.max(containerWidth * 0.6, 80);
 
-    return {
-      transform: [{ translateX: translateX * (typeof width === 'number' ? width : 200) }],
-    };
-  }, [width]);
+  const translateX = progress.interpolate({
+    inputRange: [0, 1],
+    outputRange: [-bandWidth, containerWidth],
+  });
 
   return (
     <View
-      style={[
-        styles.container,
-        {
-          width,
-          height,
-          borderRadius,
-          backgroundColor: baseColor,
-        },
-        style,
-      ]}
+      onLayout={onLayout}
+      style={[styles.container, { width, height, borderRadius, backgroundColor: baseColor }, style]}
     >
-      {/* Shimmer gradient overlay */}
       <Animated.View
-        style={[
-          StyleSheet.absoluteFill,
-          {
-            overflow: 'hidden',
-            borderRadius,
-          },
-        ]}
+        pointerEvents="none"
+        style={[styles.band, { width: bandWidth, transform: [{ translateX }] }]}
       >
-        <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>
+        <View style={[styles.segment, { backgroundColor: highlightColor, opacity: 0.25 }]} />
+        <View style={[styles.segment, { backgroundColor: highlightColor, opacity: 0.9 }]} />
+        <View style={[styles.segment, { backgroundColor: highlightColor, opacity: 0.25 }]} />
       </Animated.View>
 
-      {/* Child content */}
       {children}
     </View>
   );
@@ -163,7 +78,13 @@ const styles = StyleSheet.create({
   container: {
     overflow: 'hidden',
   },
-  shimmer: {
+  band: {
     position: 'absolute',
+    top: 0,
+    bottom: 0,
+    flexDirection: 'row',
+  },
+  segment: {
+    flex: 1,
   },
 });

package/src/components/Skeleton.tsx

@@ -4,8 +4,9 @@ import { Parser } from '../core/parser';
 import { SkeletonRenderer } from './SkeletonRenderer';
 import { SkeletonIgnore } from './SkeletonIgnore';
 import { StyleSkeleton } from '../core/generator/StyleSkeleton';
-import { expandToComponentNodes } from '../core/parser/expandOffline';
-import { DEFAULT_CONFIG } from '../constants/defaults';
+import { getDeepExpander } from '../core/deepRegistry';
+import { expandListPlaceholders } from '../core/parser/expandLists';
+import { useSkeletonTheme } from './SkeletonProvider';
 
 /**
  * Main Skeleton component
@@ -35,21 +36,24 @@ import { DEFAULT_CONFIG } from '../constants/defaults';
  * </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) {
+export function Skeleton(props: SkeletonProps) {
+  const theme = useSkeletonTheme();
+  const {
+    loading,
+    children,
+    styles,
+    excludeStyles,
+    deep,
+    count = 6,
+    animation = theme.animation,
+    duration = theme.duration,
+    baseColor = theme.baseColor,
+    highlightColor = theme.highlightColor,
+    borderRadius = theme.borderRadius,
+    accessible = true,
+    accessibilityLabel = 'Loading content',
+    debug = theme.debug,
+  } = props;
   // 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.
@@ -63,19 +67,31 @@ export function Skeleton({
     }
 
     try {
-      // Deep mode: expand opaque components into their real host tree by
-      // rendering them offline. Falls back to static parsing on failure.
-      if (deep) {
-        const expanded = expandToComponentNodes(<>{children}</>);
+      // Turn FlatList/SectionList into placeholder rows so lists show a
+      // skeleton even though their data (and rows) don't exist yet.
+      const prepared = expandListPlaceholders(children, count);
+
+      // Deep mode: expand opaque components into their real host tree via the
+      // opt-in expander (registered by importing 'react-native-skelo/deep').
+      // When `deep` is not set explicitly, it's used automatically whenever the
+      // expander is available. Falls back to static parsing otherwise.
+      const expand = getDeepExpander();
+      const wantDeep = deep === undefined ? expand !== null : deep;
+      if (wantDeep && expand) {
+        const expanded = expand(<>{prepared}</>);
         if (expanded && expanded.length > 0) {
           return expanded;
         }
         if (__DEV__) {
           console.warn('[Skelo] deep expansion returned nothing; falling back to static parsing.');
         }
+      } else if (deep === true && !expand && __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);
+      const parsed = Parser.parse(prepared);
 
       if (__DEV__ && debug) {
         // Log a lightweight summary: the raw nodes hold React elements
@@ -96,7 +112,7 @@ export function Skeleton({
       }
       return [];
     }
-  }, [loading, styles, deep, children, debug]);
+  }, [loading, styles, deep, count, children, debug]);
 
   // Create skeleton config
   const config = useMemo(

package/src/components/SkeletonProvider.tsx

@@ -0,0 +1,40 @@
+import React, { createContext, useContext, useMemo } from 'react';
+import type { ReactNode } from 'react';
+import type { SkeletonConfig } from '../types';
+import { DEFAULT_CONFIG } from '../constants/defaults';
+
+const SkeletonThemeContext = createContext<Required<SkeletonConfig>>(DEFAULT_CONFIG);
+
+export interface SkeletonProviderProps extends SkeletonConfig {
+  children: ReactNode;
+}
+
+/** App-wide skeleton defaults. Nested providers inherit unspecified values. */
+export function SkeletonProvider({
+  children,
+  animation,
+  duration,
+  baseColor,
+  highlightColor,
+  borderRadius,
+  debug,
+}: SkeletonProviderProps) {
+  const parent = useContext(SkeletonThemeContext);
+  const value = useMemo(
+    () => ({
+      animation: animation ?? parent.animation,
+      duration: duration ?? parent.duration,
+      baseColor: baseColor ?? parent.baseColor,
+      highlightColor: highlightColor ?? parent.highlightColor,
+      borderRadius: borderRadius ?? parent.borderRadius,
+      debug: debug ?? parent.debug,
+    }),
+    [parent, animation, duration, baseColor, highlightColor, borderRadius, debug]
+  );
+
+  return <SkeletonThemeContext.Provider value={value}>{children}</SkeletonThemeContext.Provider>;
+}
+
+export function useSkeletonTheme() {
+  return useContext(SkeletonThemeContext);
+}

package/src/components/withSkeleton.tsx

@@ -44,6 +44,7 @@ export function withSkeleton<P extends object>(
         loading={loading}
         styles={options.styles}
         excludeStyles={options.excludeStyles}
+        debug={options.debug}
         animation={options.animation}
         duration={options.duration}
         baseColor={options.baseColor}

package/src/core/deepRegistry.ts

@@ -0,0 +1,16 @@
+import type { ReactElement } from 'react';
+import type { ComponentNode } from '../types';
+
+// Deep expansion is opt-in so the core bundle never depends on react-reconciler.
+// `react-native-skelo/deep` registers the expander; Skeleton reads it here.
+type DeepExpander = (element: ReactElement) => ComponentNode[] | null;
+
+let expander: DeepExpander | null = null;
+
+export function setDeepExpander(fn: DeepExpander): void {
+  expander = fn;
+}
+
+export function getDeepExpander(): DeepExpander | null {
+  return expander;
+}

package/src/core/parser/expandLists.tsx

@@ -0,0 +1,77 @@
+import React, { isValidElement } from 'react';
+import type { ReactElement, ReactNode } from 'react';
+import { View } from 'react-native';
+import { getComponentName } from '../../utils/componentUtils';
+
+// List components whose rows come from `renderItem` (not JSX children).
+const LIST_TYPES = new Set(['FlatList', 'SectionList', 'VirtualizedList', 'FlashList']);
+
+const NOOP_SEPARATORS = {
+  highlight: () => {},
+  unhighlight: () => {},
+  updateProps: () => {},
+};
+
+// Renders `count` sample rows from a list's `renderItem` so there's something
+// to skeletonize while the real data is still loading (the rows don't exist in
+// the tree yet). Rows that throw on placeholder data are skipped.
+function renderSampleRows(list: ReactElement, count: number): ReactNode {
+  const props = (list.props || {}) as {
+    renderItem?: (info: {
+      item: unknown;
+      index: number;
+      section?: unknown;
+      separators: typeof NOOP_SEPARATORS;
+    }) => ReactNode;
+    data?: unknown[];
+    contentContainerStyle?: unknown;
+  };
+
+  const data = Array.isArray(props.data) ? props.data : [];
+  const sample = data.length > 0 ? data[0] : {};
+
+  const rows: ReactNode[] = [];
+  for (let i = 0; i < count; i++) {
+    try {
+      const row = props.renderItem?.({
+        item: sample,
+        index: i,
+        section: {},
+        separators: NOOP_SEPARATORS,
+      });
+      if (row) {
+        rows.push(<React.Fragment key={i}>{row}</React.Fragment>);
+      }
+    } catch {
+      // Row couldn't render with placeholder data — skip it.
+    }
+  }
+
+  return <View style={props.contentContainerStyle as never}>{rows}</View>;
+}
+
+// Walks a child tree and replaces FlatList/SectionList with sample rows so a
+// plain `<Skeleton><FlatList/></Skeleton>` produces a skeleton while loading.
+export function expandListPlaceholders(children: ReactNode, count: number): ReactNode {
+  return React.Children.map(children, child => {
+    if (!isValidElement(child)) {
+      return child;
+    }
+
+    const name = getComponentName(child);
+    const props = (child.props || {}) as { children?: ReactNode };
+
+    if (
+      LIST_TYPES.has(name) &&
+      typeof (props as { renderItem?: unknown }).renderItem === 'function'
+    ) {
+      return renderSampleRows(child, count);
+    }
+
+    if (props.children) {
+      return React.cloneElement(child, undefined, expandListPlaceholders(props.children, count));
+    }
+
+    return child;
+  });
+}

package/src/deep.ts

@@ -0,0 +1,12 @@
+// Opt-in deep mode. Import once in your app entry to enable `<Skeleton deep>`:
+//
+//   import 'react-native-skelo/deep';
+//
+// This is the only module that pulls in react-reconciler, so apps that don't
+// use deep mode never bundle it. Requires `react-reconciler` to be installed.
+import { setDeepExpander } from './core/deepRegistry';
+import { expandToComponentNodes } from './core/parser/expandOffline';
+
+setDeepExpander(expandToComponentNodes);
+
+export const deepEnabled = true;

package/src/index.ts

@@ -6,7 +6,13 @@
  * @packageDocumentation
  */
 
+// Auto-register deep expansion (react-reconciler ships as a dependency), so
+// `<Skeleton deep>` / opaque components work with zero setup.
+import './deep';
+
 // Main component
+export { SkeletonProvider } from './components/SkeletonProvider';
+export type { SkeletonProviderProps } from './components/SkeletonProvider';
 export { Skeleton } from './components/Skeleton';
 export { SkeletonIgnore } from './components/SkeletonIgnore';
 export { withSkeleton } from './components/withSkeleton';

package/src/types/skeleton.ts

@@ -79,6 +79,15 @@ export interface SkeletonProps {
    */
   excludeStyles?: string[];
 
+  /**
+   * Number of placeholder rows to render for a `FlatList` / `SectionList`
+   * while its data is still loading (its rows don't exist yet, so Skelo calls
+   * `renderItem` with a placeholder and repeats it `count` times).
+   *
+   * @default 6
+   */
+  count?: number;
+
   /**
    * Deep mode: expand opaque (custom) child components into their real
    * host-element tree via offline rendering, producing a structured skeleton