react-native-skelo 0.0.1 → 0.0.2

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

package/src/components/primitives/SkeletonImage.tsx

@@ -0,0 +1,50 @@
+import React from 'react';
+import { StyleSheet } from 'react-native';
+import type { ImageProps } from '../../types';
+import { AnimationWrapper } from '../../animations';
+import type { AnimationType } from '../../animations';
+
+/**
+ * Image skeleton primitive
+ *
+ * @example
+ * ```tsx
+ * <SkeletonImage width={80} height={80} borderRadius={40} />
+ * ```
+ */
+export function SkeletonImage({
+  width = 100,
+  height = 100,
+  borderRadius = 0,
+  style,
+  animation = 'shimmer',
+  baseColor,
+  highlightColor,
+  duration,
+}: ImageProps & {
+  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.image, style]}
+    />
+  );
+}
+
+const styles = StyleSheet.create({
+  image: {
+    overflow: 'hidden',
+  },
+});
+
+SkeletonImage.displayName = 'Skeleton.Image';

package/src/components/primitives/SkeletonText.tsx

@@ -0,0 +1,69 @@
+import React from 'react';
+import { View, StyleSheet } from 'react-native';
+import type { TextProps } from '../../types';
+import { AnimationWrapper } from '../../animations';
+import type { AnimationType } from '../../animations';
+
+/**
+ * Text skeleton primitive with multiple lines
+ *
+ * @example
+ * ```tsx
+ * <SkeletonText lines={3} fontSize={16} lastLineWidth="70%" />
+ * ```
+ */
+export function SkeletonText({
+  lines = 1,
+  fontSize = 14,
+  lineHeight,
+  width = '100%',
+  lastLineWidth = '60%',
+  style,
+  animation = 'shimmer',
+  baseColor,
+  highlightColor,
+  duration,
+}: TextProps & {
+  animation?: AnimationType;
+  baseColor?: string;
+  highlightColor?: string;
+  duration?: number;
+}) {
+  const calculatedLineHeight = lineHeight || fontSize * 1.4;
+
+  return (
+    <View style={style}>
+      {Array.from({ length: lines }).map((_, index) => {
+        const isLastLine = index === lines - 1;
+        const lineWidth = isLastLine && lines > 1 ? lastLineWidth : width;
+
+        return (
+          <AnimationWrapper
+            key={index}
+            animation={animation}
+            width={lineWidth}
+            height={fontSize}
+            borderRadius={4}
+            baseColor={baseColor}
+            highlightColor={highlightColor}
+            duration={duration}
+            style={[
+              styles.line,
+              {
+                marginBottom: index < lines - 1 ? calculatedLineHeight - fontSize : 0,
+              },
+            ]}
+          />
+        );
+      })}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  line: {
+    overflow: 'hidden',
+  },
+});
+
+SkeletonText.displayName = 'Skeleton.Text';

package/src/components/primitives/index.ts

@@ -0,0 +1,4 @@
+export { SkeletonBox } from './SkeletonBox';
+export { SkeletonText } from './SkeletonText';
+export { SkeletonImage } from './SkeletonImage';
+export { SkeletonCircle } from './SkeletonCircle';

package/src/components/withSkeleton.tsx

@@ -0,0 +1,62 @@
+import React from 'react';
+import type { ComponentType } from 'react';
+import type { SkeletonConfig } from '../types';
+import type { StyleInput } from '../core/generator/StyleSkeleton';
+import { Skeleton } from './Skeleton';
+
+export interface WithSkeletonOptions extends Partial<SkeletonConfig> {
+  /**
+   * Styles used to generate the skeleton while loading. Required when the
+   * wrapped component is opaque (a typical screen/component), since Skelo can't
+   * introspect its internals.
+   */
+  styles?: StyleInput;
+
+  /**
+   * Style keys to skip when generating the skeleton (e.g. layout containers).
+   */
+  excludeStyles?: string[];
+}
+
+/**
+ * Higher-order component that adds a loading skeleton to any component.
+ *
+ * The returned component accepts a `loading` prop (plus the wrapped
+ * component's own props). While `loading` is true it renders a skeleton
+ * derived from `options.styles`; otherwise it renders the real component.
+ *
+ * @example
+ * ```tsx
+ * const Home = withSkeleton(HomeScreen, { styles });
+ *
+ * <Home loading={isLoading} user={user} />
+ * ```
+ */
+export function withSkeleton<P extends object>(
+  Component: ComponentType<P>,
+  options: WithSkeletonOptions = {}
+) {
+  const WithSkeleton = (props: P & { loading: boolean }) => {
+    const { loading, ...componentProps } = props;
+
+    return (
+      <Skeleton
+        loading={loading}
+        styles={options.styles}
+        excludeStyles={options.excludeStyles}
+        animation={options.animation}
+        duration={options.duration}
+        baseColor={options.baseColor}
+        highlightColor={options.highlightColor}
+        borderRadius={options.borderRadius}
+      >
+        <Component {...(componentProps as unknown as P)} />
+      </Skeleton>
+    );
+  };
+
+  const name = Component.displayName || Component.name || 'Component';
+  WithSkeleton.displayName = `withSkeleton(${name})`;
+
+  return WithSkeleton;
+}

package/src/constants/defaults.ts

@@ -0,0 +1,38 @@
+import type { SkeletonConfig } from '../types';
+
+/**
+ * Default skeleton configuration
+ */
+export const DEFAULT_CONFIG: Required<SkeletonConfig> = {
+  animation: 'shimmer',
+  duration: 1200,
+  baseColor: '#E1E9EE',
+  highlightColor: '#F0F4F8',
+  borderRadius: 4,
+  debug: false,
+};
+
+/**
+ * Dark mode colors
+ */
+export const DARK_MODE_COLORS = {
+  baseColor: '#2A3F4F',
+  highlightColor: '#3A5364',
+};
+
+/**
+ * Default dimensions for components without explicit sizing
+ */
+export const DEFAULT_DIMENSIONS = {
+  image: {
+    width: 100,
+    height: 100,
+  },
+  text: {
+    fontSize: 14,
+    lineHeight: 20,
+  },
+  box: {
+    height: 50,
+  },
+};

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;
+}