react-native-skelo 0.0.1 → 0.0.2

package/src/core/resolver/StyleResolver.ts

@@ -0,0 +1,80 @@
+import type { ReactElement } from 'react';
+import type { DimensionValue } from 'react-native';
+import type { ResolvedStyle } from '../../types';
+import { resolveStyle, extractDimensions } from '../../utils';
+
+/**
+ * StyleResolver class for extracting and resolving component styles
+ */
+export class StyleResolver {
+  /**
+   * Resolve styles from a React element
+   *
+   * @param element - React element
+   * @returns Resolved style object
+   */
+  static resolve(element: ReactElement): ResolvedStyle {
+    const props = element.props || {};
+    const style = props.style;
+
+    return resolveStyle(style);
+  }
+
+  /**
+   * Get dimensions from element props and style
+   *
+   * @param element - React element
+   * @returns Object with width and height
+   */
+  static getDimensions(element: ReactElement): {
+    width?: DimensionValue;
+    height?: DimensionValue;
+  } {
+    const style = this.resolve(element);
+    return extractDimensions(style);
+  }
+
+  /**
+   * Check if element has explicit dimensions
+   *
+   * @param element - React element
+   * @returns True if both width and height are defined
+   */
+  static hasExplicitDimensions(element: ReactElement): boolean {
+    const { width, height } = this.getDimensions(element);
+    return width !== undefined && height !== undefined;
+  }
+
+  /**
+   * Get border radius from style
+   *
+   * @param element - React element
+   * @returns Border radius value or undefined
+   */
+  static getBorderRadius(element: ReactElement): number | undefined {
+    const style = this.resolve(element);
+    return style.borderRadius;
+  }
+
+  /**
+   * Get font size from style
+   *
+   * @param element - React element
+   * @returns Font size value or undefined
+   */
+  static getFontSize(element: ReactElement): number | undefined {
+    const style = this.resolve(element);
+    return style.fontSize;
+  }
+
+  /**
+   * Get line height from style
+   *
+   * @param element - React element
+   * @returns Line height value or undefined
+   */
+  static getLineHeight(element: ReactElement): number | undefined {
+    const style = this.resolve(element);
+    return style.lineHeight;
+  }
+}

package/src/core/resolver/index.ts

@@ -0,0 +1 @@
+export { StyleResolver } from './StyleResolver';

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

@@ -0,0 +1,30 @@
+/**
+ * Skelo - Automatic skeleton loading for React Native
+ *
+ * Write your UI once. Skelo builds the loading state automatically.
+ *
+ * @packageDocumentation
+ */
+
+// Main component
+export { Skeleton } from './components/Skeleton';
+export { SkeletonIgnore } from './components/SkeletonIgnore';
+export { withSkeleton } from './components/withSkeleton';
+export type { WithSkeletonOptions } from './components/withSkeleton';
+export { StyleSkeleton } from './core/generator/StyleSkeleton';
+export type { StyleInput } from './core/generator/StyleSkeleton';
+
+// Global API
+export { Skelo } from './Skelo';
+
+// Types
+export type {
+  SkeletonProps,
+  SkeletonConfig,
+  SkeletonPlugin,
+  SkeletonStrategy,
+  SkeletonContext,
+} from './types';
+
+// Primitives (for plugin development)
+export { SkeletonBox, SkeletonText, SkeletonImage, SkeletonCircle } from './components/primitives';

package/src/plugins/ImagePlugin.tsx

@@ -0,0 +1,65 @@
+import React from 'react';
+import { Image } from 'react-native';
+import type { SkeletonPlugin } from '../types';
+import type { ImageProps } from 'react-native';
+
+/**
+ * Built-in plugin for React Native Image component
+ *
+ * Renders Image as:
+ * - SkeletonCircle if circular (avatar-like)
+ * - SkeletonImage otherwise
+ */
+export const ImagePlugin: SkeletonPlugin<ImageProps> = {
+  name: 'Image',
+  component: Image,
+  version: '1.0.0',
+
+  strategy: (props, context) => {
+    const { primitives, config } = context;
+    const style = props.style || {};
+    const flatStyle = Array.isArray(style) ? Object.assign({}, ...style) : style;
+
+    const width = flatStyle.width ?? 100;
+    const height = flatStyle.height ?? 100;
+    const borderRadius = flatStyle.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 (
+        <primitives.Circle
+          size={width as number}
+          animation={config.animation}
+          baseColor={config.baseColor}
+          highlightColor={config.highlightColor}
+          duration={config.duration}
+          style={flatStyle}
+        />
+      );
+    }
+
+    return (
+      <primitives.Image
+        width={width}
+        height={height}
+        borderRadius={borderRadius as number}
+        animation={config.animation}
+        baseColor={config.baseColor}
+        highlightColor={config.highlightColor}
+        duration={config.duration}
+        style={flatStyle}
+      />
+    );
+  },
+
+  metadata: {
+    description: 'Automatic skeleton generation for Image components',
+    author: 'Skelo',
+  },
+};

package/src/plugins/TextPlugin.tsx

@@ -0,0 +1,71 @@
+import React from 'react';
+import { Text } from 'react-native';
+import type { SkeletonPlugin } from '../types';
+import type { TextProps } from 'react-native';
+
+/**
+ * Built-in plugin for React Native Text component
+ *
+ * Renders Text as SkeletonText with:
+ * - Estimated line count from text content
+ * - Font size from style
+ * - Line height from style
+ */
+export const TextPlugin: SkeletonPlugin<TextProps> = {
+  name: 'Text',
+  component: Text,
+  version: '1.0.0',
+
+  strategy: (props, context) => {
+    const { primitives, config } = context;
+    const style = props.style || {};
+    const flatStyle = Array.isArray(style) ? Object.assign({}, ...style) : style;
+
+    const fontSize = flatStyle.fontSize ?? 14;
+    const lineHeight = flatStyle.lineHeight ?? fontSize * 1.4;
+
+    // Estimate number of lines from text content
+    const textContent = props.children;
+    const estimatedLines = estimateTextLines(textContent);
+
+    return (
+      <primitives.Text
+        lines={estimatedLines}
+        fontSize={fontSize}
+        lineHeight={lineHeight}
+        width={flatStyle.width ?? '100%'}
+        animation={config.animation}
+        baseColor={config.baseColor}
+        highlightColor={config.highlightColor}
+        duration={config.duration}
+        style={flatStyle}
+      />
+    );
+  },
+
+  metadata: {
+    description: 'Automatic skeleton generation for Text components',
+    author: 'Skelo',
+  },
+};
+
+/**
+ * Estimate number of lines from text content
+ */
+function 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;
+}

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