react-native-skelo 0.0.1 → 0.0.3

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';

package/src/components/SkeletonRenderer.tsx

@@ -0,0 +1,341 @@
+import React from 'react';
+import { View } from 'react-native';
+import type { ComponentNode, SkeletonConfig } from '../types';
+import { registry } from '../core/registry';
+import { SkeletonBox, SkeletonText, SkeletonImage, SkeletonCircle } from './primitives';
+import { MeasuredBlock } from './MeasuredBlock';
+import { resolveStyle, extractDimensions } from '../utils/styleUtils';
+import { randomWidth } from '../utils/componentUtils';
+
+/**
+ * Host component types the renderer knows how to skeletonize directly.
+ * Anything else is treated as an opaque component and measured at runtime.
+ */
+const HOST_CONTAINER_TYPES = new Set([
+  'View',
+  'ScrollView',
+  'SafeAreaView',
+  'KeyboardAvoidingView',
+  'TouchableOpacity',
+  'TouchableHighlight',
+  'TouchableWithoutFeedback',
+  'TouchableNativeFeedback',
+  'Pressable',
+  'Fragment',
+]);
+const HOST_LIST_TYPES = new Set(['FlatList', 'SectionList', 'VirtualizedList']);
+
+// Track which opaque component names we've already warned about (dev only).
+const warnedOpaqueTypes = new Set<string>();
+
+interface SkeletonRendererProps {
+  /**
+   * Parsed component tree
+   */
+  tree: ComponentNode[];
+
+  /**
+   * Skeleton configuration
+   */
+  config: SkeletonConfig;
+
+  /**
+   * Accessibility enabled
+   */
+  accessible?: boolean;
+
+  /**
+   * Accessibility label
+   */
+  accessibilityLabel?: string;
+
+  /**
+   * Debug mode
+   */
+  debug?: boolean;
+}
+
+/**
+ * Renders skeleton from parsed component tree
+ *
+ * Uses plugins to transform components into skeleton equivalents:
+ * - View -> SkeletonBox
+ * - Text -> SkeletonText
+ * - Image -> SkeletonImage
+ * - Custom components -> Plugin strategies
+ */
+export function SkeletonRenderer({
+  tree,
+  config,
+  accessible,
+  accessibilityLabel,
+  debug,
+}: SkeletonRendererProps) {
+  /**
+   * Render a single component node
+   */
+  const renderNode = (node: ComponentNode, index: number): React.ReactElement | null => {
+    if (__DEV__ && debug) {
+      console.log(`[Skelo] Rendering node: ${node.type}`, node);
+    }
+
+    // Skeleton.Ignore escape hatch: render the real children untouched.
+    if (node.type === 'Skeleton.Ignore') {
+      return <React.Fragment key={index}>{node.props?.children}</React.Fragment>;
+    }
+
+    // Check for registered plugin
+    const plugin = registry.getPluginByName(node.type);
+    if (plugin) {
+      try {
+        return (
+          <React.Fragment key={index}>
+            {plugin.strategy(node.props, {
+              config,
+              theme: 'light', // TODO: Add theme detection
+              parseChildren: children => {
+                const parsed =
+                  typeof children === 'object' && children !== null
+                    ? [children as unknown as ComponentNode]
+                    : [];
+                return parsed.map((child, i) => renderNode(child, i));
+              },
+              primitives: {
+                Box: SkeletonBox,
+                Text: SkeletonText,
+                Image: SkeletonImage,
+                Circle: SkeletonCircle,
+              },
+              utils: {
+                resolveStyle,
+                extractDimensions,
+                randomWidth,
+              },
+            })}
+          </React.Fragment>
+        );
+      } catch (error) {
+        if (__DEV__) {
+          console.error(`[Skelo] Plugin "${plugin.name}" failed:`, error);
+        }
+      }
+    }
+
+    // Built-in host component handling
+    switch (node.type) {
+      case 'Text':
+        return renderText(node, index);
+
+      case 'Image':
+        return renderImage(node, index);
+    }
+
+    if (HOST_LIST_TYPES.has(node.type) || node.type === 'ScrollView') {
+      return renderScrollableView(node, index);
+    }
+
+    if (HOST_CONTAINER_TYPES.has(node.type)) {
+      return renderView(node, index);
+    }
+
+    // Opaque component: the parser can't see inside it (a user-defined
+    // function/class component). Render it hidden and measure its real size,
+    // then overlay a size-matched shimmer.
+    return renderOpaque(node, index);
+  };
+
+  /**
+   * Render an opaque (non-host) component via runtime measurement.
+   */
+  const renderOpaque = (node: ComponentNode, index: number): React.ReactElement => {
+    if (__DEV__ && !warnedOpaqueTypes.has(node.type)) {
+      warnedOpaqueTypes.add(node.type);
+      console.warn(
+        `[Skelo] "${node.type}" is a custom component, so Skelo can't inspect ` +
+          `its internal View/Text/Image structure. It will be measured and ` +
+          `shown as a single size-matched skeleton block.\n` +
+          `For a structured skeleton, either compose "${node.type}" from host ` +
+          `elements directly inside <Skeleton>, register a plugin via ` +
+          `Skelo.register(${node.type}, ...), or provide a manual skeleton.`
+      );
+    }
+
+    // If we still have the original element, measure it. Otherwise fall back
+    // to a container/box render.
+    if (node.element) {
+      return (
+        <MeasuredBlock key={index} config={config}>
+          {node.element}
+        </MeasuredBlock>
+      );
+    }
+
+    return renderView(node, index);
+  };
+
+  /**
+   * Render View component
+   */
+  const renderView = (node: ComponentNode, index: number): React.ReactElement => {
+    const { width, height } = node.style;
+    const hasChildren = node.children && node.children.length > 0;
+
+    // If View has explicit dimensions, render as box
+    if (width && height) {
+      return (
+        <SkeletonBox
+          key={index}
+          width={width}
+          height={height}
+          borderRadius={node.style.borderRadius ?? config.borderRadius}
+          animation={config.animation}
+          baseColor={config.baseColor}
+          highlightColor={config.highlightColor}
+          duration={config.duration}
+          style={node.style}
+        />
+      );
+    }
+
+    // If View has children, render container with children
+    if (hasChildren) {
+      return (
+        <View key={index} style={node.style}>
+          {node.children.map((child, i) => renderNode(child, i))}
+        </View>
+      );
+    }
+
+    // Empty View with no dimensions - render as small box
+    return (
+      <SkeletonBox
+        key={index}
+        width={width ?? 100}
+        height={height ?? 20}
+        borderRadius={node.style.borderRadius ?? config.borderRadius}
+        animation={config.animation}
+        baseColor={config.baseColor}
+        highlightColor={config.highlightColor}
+        duration={config.duration}
+        style={node.style}
+      />
+    );
+  };
+
+  /**
+   * Render Text component
+   */
+  const renderText = (node: ComponentNode, index: number): React.ReactElement => {
+    const fontSize = (node.style.fontSize as number) ?? 14;
+    const lineHeight = (node.style.lineHeight as number) ?? fontSize * 1.4;
+
+    // Estimate number of lines from text content
+    const textContent = node.props.children;
+    const estimatedLines = estimateTextLines(textContent);
+
+    return (
+      <SkeletonText
+        key={index}
+        lines={estimatedLines}
+        fontSize={fontSize}
+        lineHeight={lineHeight}
+        width={node.style.width ?? '100%'}
+        animation={config.animation}
+        baseColor={config.baseColor}
+        highlightColor={config.highlightColor}
+        duration={config.duration}
+        style={node.style}
+      />
+    );
+  };
+
+  /**
+   * Render Image component
+   */
+  const renderImage = (node: ComponentNode, index: number): React.ReactElement => {
+    const width = node.style.width ?? 100;
+    const height = node.style.height ?? 100;
+    const borderRadius = node.style.borderRadius ?? 0;
+
+    // Check if it's a circular image (avatar)
+    const isCircle =
+      typeof width === 'number' &&
+      typeof height === 'number' &&
+      width === height &&
+      borderRadius === width / 2;
+
+    if (isCircle) {
+      return (
+        <SkeletonCircle
+          key={index}
+          size={width as number}
+          animation={config.animation}
+          baseColor={config.baseColor}
+          highlightColor={config.highlightColor}
+          duration={config.duration}
+          style={node.style}
+        />
+      );
+    }
+
+    return (
+      <SkeletonImage
+        key={index}
+        width={width}
+        height={height}
+        borderRadius={borderRadius as number}
+        animation={config.animation}
+        baseColor={config.baseColor}
+        highlightColor={config.highlightColor}
+        duration={config.duration}
+        style={node.style}
+      />
+    );
+  };
+
+  /**
+   * Render scrollable views
+   */
+  const renderScrollableView = (node: ComponentNode, index: number): React.ReactElement => {
+    // For scrollable views, render their children
+    return (
+      <View key={index} style={node.style}>
+        {node.children.map((child, i) => renderNode(child, i))}
+      </View>
+    );
+  };
+
+  /**
+   * Estimate number of lines from text content
+   */
+  const estimateTextLines = (children: any): number => {
+    if (!children) return 1;
+
+    if (typeof children === 'string' || typeof children === 'number') {
+      const text = String(children);
+      const avgCharsPerLine = 40;
+      const estimatedLines = Math.ceil(text.length / avgCharsPerLine);
+      return Math.max(1, Math.min(estimatedLines, 5)); // Cap at 5 lines
+    }
+
+    if (Array.isArray(children)) {
+      // Multiple text nodes - count as separate lines
+      return Math.min(children.length, 5);
+    }
+
+    return 1;
+  };
+
+  // Render the skeleton tree
+  return (
+    <View
+      accessible={accessible}
+      accessibilityLabel={accessibilityLabel}
+      accessibilityRole="progressbar"
+    >
+      {tree.map((node, index) => renderNode(node, index))}
+    </View>
+  );
+}
+
+SkeletonRenderer.displayName = 'SkeletonRenderer';

package/src/components/primitives/SkeletonBox.tsx

@@ -0,0 +1,53 @@
+import React from 'react';
+import { StyleSheet } from 'react-native';
+import type { BoxProps } from '../../types';
+import { AnimationWrapper } from '../../animations';
+import type { AnimationType } from '../../animations';
+
+/**
+ * Basic box skeleton primitive
+ *
+ * @example
+ * ```tsx
+ * <SkeletonBox width={100} height={50} borderRadius={8} />
+ * ```
+ */
+export function SkeletonBox({
+  width,
+  height,
+  borderRadius = 4,
+  style,
+  children,
+  animation = 'shimmer',
+  baseColor,
+  highlightColor,
+  duration,
+}: BoxProps & {
+  animation?: AnimationType;
+  baseColor?: string;
+  highlightColor?: string;
+  duration?: number;
+}) {
+  return (
+    <AnimationWrapper
+      animation={animation}
+      width={width}
+      height={height}
+      borderRadius={borderRadius}
+      baseColor={baseColor}
+      highlightColor={highlightColor}
+      duration={duration}
+      style={[styles.box, style]}
+    >
+      {children}
+    </AnimationWrapper>
+  );
+}
+
+const styles = StyleSheet.create({
+  box: {
+    overflow: 'hidden',
+  },
+});
+
+SkeletonBox.displayName = 'Skeleton.Box';

package/src/components/primitives/SkeletonCircle.tsx

@@ -0,0 +1,48 @@
+import React from 'react';
+import { StyleSheet } from 'react-native';
+import type { CircleProps } from '../../types';
+import { AnimationWrapper } from '../../animations';
+import type { AnimationType } from '../../animations';
+
+/**
+ * Circle skeleton primitive (useful for avatars)
+ *
+ * @example
+ * ```tsx
+ * <SkeletonCircle size={40} />
+ * ```
+ */
+export function SkeletonCircle({
+  size = 40,
+  style,
+  animation = 'shimmer',
+  baseColor,
+  highlightColor,
+  duration,
+}: CircleProps & {
+  animation?: AnimationType;
+  baseColor?: string;
+  highlightColor?: string;
+  duration?: number;
+}) {
+  return (
+    <AnimationWrapper
+      animation={animation}
+      width={size}
+      height={size}
+      borderRadius={size / 2}
+      baseColor={baseColor}
+      highlightColor={highlightColor}
+      duration={duration}
+      style={[styles.circle, style]}
+    />
+  );
+}
+
+const styles = StyleSheet.create({
+  circle: {
+    overflow: 'hidden',
+  },
+});
+
+SkeletonCircle.displayName = 'Skeleton.Circle';