react-native-skelo 0.0.1 → 0.0.3

package/src/plugins/ViewPlugin.tsx

@@ -0,0 +1,67 @@
+import React from 'react';
+import { View } from 'react-native';
+import type { SkeletonPlugin } from '../types';
+import type { ViewProps } from 'react-native';
+
+/**
+ * Built-in plugin for React Native View component
+ *
+ * Renders View as:
+ * - SkeletonBox if has explicit width/height
+ * - Container with parsed children otherwise
+ */
+export const ViewPlugin: SkeletonPlugin<ViewProps> = {
+  name: 'View',
+  component: View,
+  version: '1.0.0',
+
+  strategy: (props, context) => {
+    const { primitives, parseChildren, config } = context;
+    const style = props.style || {};
+    const flatStyle = Array.isArray(style) ? Object.assign({}, ...style) : style;
+
+    const width = flatStyle.width;
+    const height = flatStyle.height;
+    const borderRadius = flatStyle.borderRadius ?? config.borderRadius;
+
+    // If View has explicit dimensions, render as box
+    if (width && height) {
+      return (
+        <primitives.Box
+          width={width}
+          height={height}
+          borderRadius={borderRadius}
+          animation={config.animation}
+          baseColor={config.baseColor}
+          highlightColor={config.highlightColor}
+          duration={config.duration}
+          style={flatStyle}
+        />
+      );
+    }
+
+    // If View has children, render as container
+    if (props.children) {
+      return <View style={flatStyle}>{parseChildren(props.children)}</View>;
+    }
+
+    // Empty View - render as small placeholder
+    return (
+      <primitives.Box
+        width={width ?? 100}
+        height={height ?? 20}
+        borderRadius={borderRadius}
+        animation={config.animation}
+        baseColor={config.baseColor}
+        highlightColor={config.highlightColor}
+        duration={config.duration}
+        style={flatStyle}
+      />
+    );
+  },
+
+  metadata: {
+    description: 'Automatic skeleton generation for View components',
+    author: 'Skelo',
+  },
+};

package/src/plugins/index.ts

@@ -0,0 +1,3 @@
+export { ViewPlugin } from './ViewPlugin';
+export { TextPlugin } from './TextPlugin';
+export { ImagePlugin } from './ImagePlugin';

package/src/types/index.ts

@@ -0,0 +1,14 @@
+export type { SkeletonProps, SkeletonConfig, ResolvedStyle, ComponentNode } from './skeleton';
+
+export type {
+  SkeletonPlugin,
+  SkeletonStrategy,
+  SkeletonContext,
+  SkeletonPrimitives,
+  SkeletonUtils,
+  PluginMetadata,
+  BoxProps,
+  TextProps,
+  ImageProps,
+  CircleProps,
+} from './plugin';

package/src/types/plugin.ts

@@ -0,0 +1,164 @@
+import type { ComponentType, ReactElement, ReactNode } from 'react';
+import type { DimensionValue } from 'react-native';
+import type { SkeletonConfig, ResolvedStyle } from './skeleton';
+
+/**
+ * Plugin for custom component skeleton generation
+ *
+ * @example
+ * ```tsx
+ * const AvatarPlugin: SkeletonPlugin<AvatarProps> = {
+ *   name: 'Avatar',
+ *   component: Avatar,
+ *   strategy: (props, { primitives }) => {
+ *     return <primitives.Circle size={props.size || 40} />;
+ *   },
+ * };
+ * ```
+ */
+export interface SkeletonPlugin<P = any> {
+  /**
+   * Unique identifier for the plugin
+   */
+  name: string;
+
+  /**
+   * Component type this plugin handles
+   */
+  component: ComponentType<P>;
+
+  /**
+   * Strategy function to generate skeleton
+   */
+  strategy: SkeletonStrategy<P>;
+
+  /**
+   * Optional: Plugin version
+   */
+  version?: string;
+
+  /**
+   * Optional: Plugin metadata
+   */
+  metadata?: PluginMetadata;
+}
+
+/**
+ * Strategy function signature
+ */
+export type SkeletonStrategy<P = any> = (props: P, context: SkeletonContext) => ReactElement | null;
+
+/**
+ * Context provided to plugin strategies
+ */
+export interface SkeletonContext {
+  /**
+   * Configuration from parent Skeleton component
+   */
+  config: SkeletonConfig;
+
+  /**
+   * Theme information (light/dark)
+   */
+  theme: 'light' | 'dark';
+
+  /**
+   * Recursively parse children
+   */
+  parseChildren: (children: ReactNode) => ReactNode;
+
+  /**
+   * Access to skeleton primitives
+   */
+  primitives: SkeletonPrimitives;
+
+  /**
+   * Utility functions
+   */
+  utils: SkeletonUtils;
+}
+
+/**
+ * Skeleton primitive components
+ */
+export interface SkeletonPrimitives {
+  Box: ComponentType<BoxProps>;
+  Text: ComponentType<TextProps>;
+  Image: ComponentType<ImageProps>;
+  Circle: ComponentType<CircleProps>;
+}
+
+/**
+ * Utility functions for plugins
+ */
+export interface SkeletonUtils {
+  /**
+   * Flatten and resolve styles
+   */
+  resolveStyle: (style: any) => ResolvedStyle;
+
+  /**
+   * Extract dimensions from a resolved style
+   */
+  extractDimensions: (style: ResolvedStyle) => {
+    width?: DimensionValue;
+    height?: DimensionValue;
+  };
+
+  /**
+   * Generate random width for natural look
+   */
+  randomWidth: (min?: number, max?: number) => string;
+}
+
+/**
+ * Plugin metadata
+ */
+export interface PluginMetadata {
+  author?: string;
+  description?: string;
+  repository?: string;
+  license?: string;
+}
+
+/**
+ * Animation and color props shared by all skeleton primitives
+ */
+export interface SkeletonAnimationProps {
+  animation?: 'shimmer' | 'pulse' | 'none';
+  baseColor?: string;
+  highlightColor?: string;
+  duration?: number;
+}
+
+/**
+ * Props for skeleton primitives
+ */
+export interface BoxProps extends SkeletonAnimationProps {
+  width?: DimensionValue;
+  height?: DimensionValue;
+  borderRadius?: number;
+  style?: any;
+  children?: ReactNode;
+}
+
+export interface TextProps extends SkeletonAnimationProps {
+  lines?: number;
+  fontSize?: number;
+  lineHeight?: number;
+  width?: DimensionValue;
+  lastLineWidth?: DimensionValue;
+  style?: any;
+}
+
+export interface ImageProps extends SkeletonAnimationProps {
+  width?: DimensionValue;
+  height?: DimensionValue;
+  borderRadius?: number;
+  style?: any;
+}
+
+export interface CircleProps extends SkeletonAnimationProps {
+  size?: number;
+  style?: any;
+}

package/src/types/skeleton.ts

@@ -0,0 +1,197 @@
+import type { ReactElement, ReactNode } from 'react';
+import type { DimensionValue, FlexAlignType } from 'react-native';
+
+/**
+ * Props for the main Skeleton component
+ *
+ * @example
+ * ```tsx
+ * <Skeleton loading={true} animation="shimmer">
+ *   <YourComponent />
+ * </Skeleton>
+ * ```
+ */
+export interface SkeletonProps {
+  /**
+   * Whether to show skeleton (true) or actual content (false)
+   */
+  loading: boolean;
+
+  /**
+   * Animation type
+   * - 'shimmer': Moving gradient animation (default)
+   * - 'pulse': Fade in/out animation
+   * - 'none': Static skeleton
+   *
+   * @default 'shimmer'
+   */
+  animation?: 'shimmer' | 'pulse' | 'none';
+
+  /**
+   * Animation duration in milliseconds
+   * @default 1200
+   */
+  duration?: number;
+
+  /**
+   * Base skeleton color
+   * @default Auto-detected based on color scheme (light/dark)
+   */
+  baseColor?: string;
+
+  /**
+   * Shimmer highlight color
+   * @default Auto-detected based on color scheme (light/dark)
+   */
+  highlightColor?: string;
+
+  /**
+   * Default border radius for skeleton elements
+   * @default 4
+   */
+  borderRadius?: number;
+
+  /**
+   * Components to render.
+   *
+   * When `styles` is provided, `children` is optional — the skeleton is derived
+   * from the styles instead of the child tree.
+   */
+  children?: ReactNode;
+
+  /**
+   * Generate the skeleton directly from a set of styles instead of from the
+   * child element tree. Accepts a `StyleSheet.create` object (values used in
+   * definition order) or an array of styles.
+   *
+   * Because a StyleSheet has no hierarchy, the result is a vertical stack of
+   * skeleton shapes — one per style that has visual dimensions.
+   *
+   * @example
+   * ```tsx
+   * <Skeleton loading={loading} styles={styles} />
+   * ```
+   */
+  styles?: Record<string, unknown> | unknown[];
+
+  /**
+   * When using `styles`, style keys to skip (e.g. layout containers).
+   */
+  excludeStyles?: string[];
+
+  /**
+   * Deep mode: expand opaque (custom) child components into their real
+   * host-element tree via offline rendering, producing a structured skeleton
+   * without inlining host elements.
+   *
+   * @experimental Renders the children offline to introspect them, so their
+   * mount effects run during expansion and they render outside your app's
+   * providers (navigation/theme/redux). Best for presentational trees; guard
+   * effectful/context-dependent screens or register a plugin for them. Falls
+   * back to static parsing if offline rendering is unavailable or fails.
+   * Requires `react-reconciler` to be installed.
+   *
+   * @default false
+   */
+  deep?: boolean;
+
+  /**
+   * Enable accessibility features
+   * @default true
+   */
+  accessible?: boolean;
+
+  /**
+   * Screen reader label
+   * @default "Loading content"
+   */
+  accessibilityLabel?: string;
+
+  /**
+   * Debug mode (development only)
+   * Shows component boundaries and names
+   * @default false
+   */
+  debug?: boolean;
+}
+
+/**
+ * Configuration options for SkeletonProvider
+ */
+export interface SkeletonConfig {
+  /**
+   * Default animation type
+   * @default 'shimmer'
+   */
+  animation?: 'shimmer' | 'pulse' | 'none';
+
+  /**
+   * Default animation duration in milliseconds
+   * @default 1200
+   */
+  duration?: number;
+
+  /**
+   * Default base color
+   */
+  baseColor?: string;
+
+  /**
+   * Default highlight color
+   */
+  highlightColor?: string;
+
+  /**
+   * Default border radius
+   * @default 4
+   */
+  borderRadius?: number;
+
+  /**
+   * Enable debug mode globally
+   * @default false
+   */
+  debug?: boolean;
+}
+
+/**
+ * Resolved style properties extracted from React Native styles
+ */
+export interface ResolvedStyle {
+  width?: DimensionValue;
+  height?: DimensionValue;
+  borderRadius?: number;
+  backgroundColor?: string;
+  fontSize?: number;
+  lineHeight?: number;
+  marginTop?: number;
+  marginBottom?: number;
+  marginLeft?: number;
+  marginRight?: number;
+  paddingTop?: number;
+  paddingBottom?: number;
+  paddingLeft?: number;
+  paddingRight?: number;
+  flexDirection?: 'row' | 'column';
+  alignItems?: FlexAlignType;
+  justifyContent?:
+    'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly';
+}
+
+/**
+ * Parsed component node in the tree
+ */
+export interface ComponentNode {
+  type: string;
+  props: any;
+  style: ResolvedStyle;
+  children: ComponentNode[];
+  /**
+   * The original React element this node was parsed from.
+   *
+   * Retained so the renderer can fall back to rendering-and-measuring the
+   * real element when it is an opaque (non-host) component the parser can't
+   * introspect. Excluded from debug serialization.
+   */
+  element?: ReactElement;
+}

package/src/utils/componentUtils.ts

@@ -0,0 +1,166 @@
+import React, { isValidElement } from 'react';
+import type { ReactElement, ReactNode } from 'react';
+import {
+  View,
+  Text,
+  Image,
+  ImageBackground,
+  ScrollView,
+  SafeAreaView,
+  FlatList,
+  SectionList,
+  VirtualizedList,
+  TouchableOpacity,
+  TouchableHighlight,
+  TouchableWithoutFeedback,
+  Pressable,
+  KeyboardAvoidingView,
+} from 'react-native';
+
+// Re-exported so consumers can access it from the skelo utils surface
+export { isValidElement };
+
+/**
+ * Reference map of React Native host components to their canonical names.
+ *
+ * Modern RN components (View/Text/Image/...) are `forwardRef`/`memo` objects,
+ * not plain functions or strings, so name/displayName sniffing is unreliable.
+ * Identifying them by reference is exact. This works across the library/app
+ * module boundary because Metro resolves a single `react-native` instance.
+ */
+const RN_COMPONENT_NAMES = new Map<unknown, string>([
+  [View, 'View'],
+  [Text, 'Text'],
+  [Image, 'Image'],
+  [ImageBackground, 'ImageBackground'],
+  [ScrollView, 'ScrollView'],
+  [SafeAreaView, 'SafeAreaView'],
+  [FlatList, 'FlatList'],
+  [SectionList, 'SectionList'],
+  [VirtualizedList, 'VirtualizedList'],
+  [TouchableOpacity, 'TouchableOpacity'],
+  [TouchableHighlight, 'TouchableHighlight'],
+  [TouchableWithoutFeedback, 'TouchableWithoutFeedback'],
+  [Pressable, 'Pressable'],
+  [KeyboardAvoidingView, 'KeyboardAvoidingView'],
+]);
+
+/**
+ * Get component display name or type name
+ *
+ * @param element - React element
+ * @returns Component name as string
+ */
+export function getComponentName(element: ReactElement): string {
+  const type: unknown = element.type;
+
+  if (type === React.Fragment) {
+    return 'Fragment';
+  }
+
+  // Exact identification of RN host components (forwardRef/memo objects).
+  const mapped = RN_COMPONENT_NAMES.get(type);
+  if (mapped) {
+    return mapped;
+  }
+
+  // Intrinsic host string (e.g. web/DOM or raw native tags).
+  if (typeof type === 'string') {
+    return type;
+  }
+
+  // Plain function/class components.
+  if (typeof type === 'function') {
+    const fn = type as { displayName?: string; name?: string };
+    return fn.displayName || fn.name || 'Anonymous';
+  }
+
+  // forwardRef / memo wrappers: unwrap to find a usable name.
+  if (typeof type === 'object' && type !== null) {
+    const obj = type as {
+      displayName?: string;
+      render?: { displayName?: string; name?: string };
+      type?: unknown;
+    };
+    if (obj.displayName) {
+      return obj.displayName;
+    }
+    if (obj.render) {
+      return obj.render.displayName || obj.render.name || 'Anonymous';
+    }
+    // memo(Component) nests the real component under `.type`.
+    if (obj.type) {
+      return getComponentName({ type: obj.type } as ReactElement);
+    }
+    return 'Anonymous';
+  }
+
+  return 'Unknown';
+}
+
+/**
+ * Check if element is a React Fragment
+ *
+ * @param element - React element
+ * @returns True if element is a Fragment
+ */
+export function isFragment(element: ReactElement): boolean {
+  return element.type === React.Fragment;
+}
+
+/**
+ * Flatten children, handling Fragments recursively
+ *
+ * @param children - React children
+ * @returns Flattened array of children
+ */
+export function flattenChildren(children: ReactNode): ReactNode[] {
+  const result: ReactNode[] = [];
+
+  React.Children.forEach(children, child => {
+    if (!isValidElement(child)) {
+      result.push(child);
+      return;
+    }
+
+    if (isFragment(child)) {
+      // Recursively flatten fragment children
+      const fragmentChildren = flattenChildren(child.props.children);
+      result.push(...fragmentChildren);
+    } else {
+      result.push(child);
+    }
+  });
+
+  return result;
+}
+
+/**
+ * Check if component is a touchable component
+ *
+ * @param element - React element
+ * @returns True if component is touchable
+ */
+export function isTouchableComponent(element: ReactElement): boolean {
+  const name = getComponentName(element);
+  const touchableTypes = [
+    'TouchableOpacity',
+    'TouchableHighlight',
+    'TouchableWithoutFeedback',
+    'TouchableNativeFeedback',
+    'Pressable',
+  ];
+  return touchableTypes.includes(name);
+}
+
+/**
+ * Generate random width percentage for natural skeleton look
+ *
+ * @param min - Minimum percentage (0-100)
+ * @param max - Maximum percentage (0-100)
+ * @returns Random percentage as string (e.g., "75%")
+ */
+export function randomWidth(min: number = 60, max: number = 90): string {
+  const random = Math.floor(Math.random() * (max - min + 1)) + min;
+  return `${random}%`;
+}

package/src/utils/index.ts

@@ -0,0 +1,9 @@
+export { resolveStyle, extractDimensions, isPercentage, percentageToNumber } from './styleUtils';
+
+export {
+  getComponentName,
+  isFragment,
+  flattenChildren,
+  isTouchableComponent,
+  randomWidth,
+} from './componentUtils';

package/src/utils/styleUtils.ts

@@ -0,0 +1,72 @@
+import { StyleSheet } from 'react-native';
+import type { DimensionValue } from 'react-native';
+import type { ResolvedStyle } from '../types';
+
+/**
+ * Flatten and resolve styles from React Native style prop
+ *
+ * @param style - Style prop (can be object, array, or StyleSheet reference)
+ * @returns Flattened style object
+ */
+export function resolveStyle(style: any): ResolvedStyle {
+  if (!style) {
+    return {};
+  }
+
+  try {
+    const flattened = StyleSheet.flatten(style);
+    return flattened as ResolvedStyle;
+  } catch (error) {
+    // Handle invalid styles gracefully
+    if (__DEV__) {
+      console.warn('[Skelo] Failed to resolve style:', error);
+    }
+    return {};
+  }
+}
+
+/**
+ * Extract dimensions from resolved style
+ *
+ * @param style - Resolved style object
+ * @returns Object with width and height (if present)
+ */
+export function extractDimensions(style: ResolvedStyle): {
+  width?: DimensionValue;
+  height?: DimensionValue;
+} {
+  return {
+    width: style.width,
+    height: style.height,
+  };
+}
+
+/**
+ * Check if a resolved style declares both an explicit width and height
+ *
+ * @param style - Resolved style object
+ * @returns True if both width and height are defined
+ */
+export function hasExplicitSize(style: ResolvedStyle): boolean {
+  return style.width !== undefined && style.height !== undefined;
+}
+
+/**
+ * Check if a value is a percentage string
+ *
+ * @param value - Value to check
+ * @returns True if value is a percentage string
+ */
+export function isPercentage(value: any): boolean {
+  return typeof value === 'string' && value.includes('%');
+}
+
+/**
+ * Convert percentage to number (strips %)
+ *
+ * @param value - Percentage string (e.g., "50%")
+ * @returns Number without % sign
+ */
+export function percentageToNumber(value: string): number {
+  return parseFloat(value.replace('%', ''));
+}