react-native-skelo 0.0.1 → 0.0.3

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

package/src/core/generator/StyleSkeleton.tsx

@@ -0,0 +1,138 @@
+import React from 'react';
+import { StyleSheet, View } from 'react-native';
+import type { DimensionValue } from 'react-native';
+import type { SkeletonConfig } from '../../types';
+import { SkeletonBox, SkeletonText, SkeletonCircle } from '../../components/primitives';
+
+/**
+ * A single named style, or an ordered list of styles, or a whole StyleSheet
+ * object as returned by `StyleSheet.create`.
+ */
+export type StyleInput = Record<string, unknown> | unknown[];
+
+interface StyleSkeletonProps {
+  /**
+   * The styles to derive a skeleton from. Accepts a `StyleSheet.create` object
+   * (values used in definition order) or an array of styles (used in order).
+   */
+  styles: StyleInput;
+
+  /**
+   * Skeleton configuration (animation, colors, radius).
+   */
+  config: SkeletonConfig;
+
+  /**
+   * Optional list of style keys to skip (e.g. layout containers you don't want
+   * a skeleton for). Only applies when `styles` is a keyed object.
+   */
+  exclude?: string[];
+}
+
+interface FlatStyle {
+  width?: number | string;
+  height?: number | string;
+  borderRadius?: number;
+  fontSize?: number;
+  lineHeight?: number;
+  marginTop?: number;
+  marginBottom?: number;
+  aspectRatio?: number;
+}
+
+/**
+ * Turn one flattened style into the most appropriate skeleton primitive.
+ *
+ * Heuristics:
+ * - a `fontSize` with no explicit height  → text bar
+ * - square with radius ≥ half its size    → circle (avatar)
+ * - anything with width and/or height     → box
+ * - a pure layout container (no visual dimensions) → skipped (returns null)
+ */
+function styleToSkeleton(
+  rawStyle: unknown,
+  key: string | number,
+  config: SkeletonConfig
+): React.ReactElement | null {
+  const flat = (StyleSheet.flatten(rawStyle as never) || {}) as FlatStyle;
+  const { width, height, borderRadius, fontSize } = flat;
+
+  const anim = {
+    animation: config.animation,
+    baseColor: config.baseColor,
+    highlightColor: config.highlightColor,
+    duration: config.duration,
+  } as const;
+
+  const spacing = {
+    marginTop: flat.marginTop ?? 0,
+    marginBottom: flat.marginBottom ?? 12,
+  };
+
+  // Text-like: has a font size but isn't a fixed-height box.
+  if (fontSize != null && height == null) {
+    return (
+      <SkeletonText
+        key={key}
+        lines={1}
+        fontSize={fontSize}
+        lineHeight={flat.lineHeight}
+        width={(width as DimensionValue) ?? '60%'}
+        style={spacing}
+        {...anim}
+      />
+    );
+  }
+
+  // Circle / avatar: square with a radius that rounds it fully.
+  if (
+    typeof width === 'number' &&
+    width === height &&
+    typeof borderRadius === 'number' &&
+    borderRadius >= width / 2
+  ) {
+    return <SkeletonCircle key={key} size={width} style={spacing} {...anim} />;
+  }
+
+  // Box: anything with an explicit dimension.
+  if (width != null || height != null) {
+    return (
+      <SkeletonBox
+        key={key}
+        width={(width as DimensionValue) ?? '100%'}
+        height={(height as DimensionValue) ?? 20}
+        borderRadius={borderRadius ?? config.borderRadius ?? 4}
+        style={spacing}
+        {...anim}
+      />
+    );
+  }
+
+  // Pure layout container (no visual footprint) — nothing to draw.
+  return null;
+}
+
+/**
+ * Generates a skeleton directly from a set of styles.
+ *
+ * Because a StyleSheet is flat (no element hierarchy), the output is a vertical
+ * stack of skeleton shapes — one per style that has visual dimensions — sized
+ * from each style's own props. Layout-only styles are skipped.
+ */
+export function StyleSkeleton({ styles, config, exclude }: StyleSkeletonProps) {
+  const entries: Array<[string | number, unknown]> = Array.isArray(styles)
+    ? styles.map((s, i) => [i, s])
+    : Object.entries(styles || {}).filter(([name]) => !exclude || !exclude.includes(name));
+
+  const nodes = entries
+    .map(([key, style]) => styleToSkeleton(style, key, config))
+    .filter((n): n is React.ReactElement => n !== null);
+
+  return (
+    <View accessibilityRole="progressbar" accessible>
+      {nodes}
+    </View>
+  );
+}
+
+StyleSkeleton.displayName = 'Skeleton.FromStyles';

package/src/core/parser/Parser.ts

@@ -0,0 +1,86 @@
+import React, { isValidElement } from 'react';
+import type { ReactElement, ReactNode } from 'react';
+import type { ComponentNode } from '../../types';
+import { StyleResolver } from '../resolver';
+import { getComponentName, flattenChildren } from '../../utils';
+
+/**
+ * Parser class for traversing and analyzing React component trees
+ */
+export class Parser {
+  /**
+   * Parse a React element tree into a component node tree
+   *
+   * @param children - React children to parse
+   * @returns Array of component nodes
+   */
+  static parse(children: ReactNode): ComponentNode[] {
+    const flattened = flattenChildren(children);
+    const nodes: ComponentNode[] = [];
+
+    flattened.forEach(child => {
+      if (!isValidElement(child)) {
+        // Skip non-element children (strings, numbers, null, etc.)
+        return;
+      }
+
+      const node = this.parseElement(child);
+      if (node) {
+        nodes.push(node);
+      }
+    });
+
+    return nodes;
+  }
+
+  /**
+   * Parse a single React element
+   *
+   * @param element - React element
+   * @returns Component node or null
+   */
+  static parseElement(element: ReactElement): ComponentNode | null {
+    const type = getComponentName(element);
+    const props = element.props || {};
+    const style = StyleResolver.resolve(element);
+
+    // Parse children recursively
+    const children = props.children ? this.parse(props.children) : [];
+
+    return {
+      type,
+      props,
+      style,
+      children,
+      element,
+    };
+  }
+
+  /**
+   * Estimate number of text lines from content and style
+   *
+   * @param children - Text content
+   * @param style - Resolved style
+   * @returns Estimated number of lines
+   */
+  static estimateTextLines(children: ReactNode, _style?: any): number {
+    if (!children) {
+      return 1;
+    }
+
+    // Convert children to string
+    const text = React.Children.toArray(children)
+      .filter(child => typeof child === 'string' || typeof child === 'number')
+      .join('');
+
+    if (!text) {
+      return 1;
+    }
+
+    // Simple heuristic: ~40 characters per line
+    const avgCharsPerLine = 40;
+    const estimatedLines = Math.ceil(text.length / avgCharsPerLine);
+
+    return Math.max(1, Math.min(estimatedLines, 5)); // Cap at 5 lines
+  }
+}

package/src/core/parser/expandOffline.tsx

@@ -0,0 +1,83 @@
+import type { ReactElement } from 'react';
+import type { ComponentNode, ResolvedStyle } from '../../types';
+import { resolveStyle } from '../../utils/styleUtils';
+import { renderToHostTree } from './hostTreeReconciler';
+import type { HostTreeNode } from './hostTreeReconciler';
+
+/**
+ * Offline structural expansion.
+ *
+ * Renders an element (including opaque function/class components) through a
+ * JS-only `react-reconciler` renderer to recover its underlying host-element
+ * tree (View / Text / Image + resolved styles), then converts it to Skelo's
+ * `ComponentNode` tree.
+ *
+ * This is what lets `<Skeleton><AnyComponent/></Skeleton>` produce a *structured*
+ * skeleton without the developer inlining host elements — the core DX. No
+ * deprecated APIs, no `act()`.
+ *
+ * Caveats (inherent to rendering the real component):
+ * - The component's mount effects run during expansion. Effectful screens
+ *   should be guarded or given an explicit skeleton via `Skelo.register`.
+ * - It renders outside the app's providers, so context-dependent components may
+ *   throw — caught, returning null so the caller falls back to static parsing.
+ */
+
+/**
+ * Normalize a host instance type to a canonical name the renderer understands.
+ * On device, RN host components may surface as native names (e.g. RCTView,
+ * RCTSinglelineTextInputView); map them to View/Text/Image/etc.
+ */
+function normalizeType(type: string): string {
+  if (/image/i.test(type)) return 'Image';
+  if (/textinput/i.test(type)) return 'TextInput';
+  if (/text/i.test(type)) return 'Text';
+  if (/scroll/i.test(type)) return 'ScrollView';
+  if (/(flat|section|virtualized)list/i.test(type)) return 'FlatList';
+  // Everything else is treated as a plain container view.
+  return 'View';
+}
+
+function toComponentNode(node: HostTreeNode): ComponentNode | null {
+  if (node.type === '#text') {
+    return null; // text is folded into its parent's props.children
+  }
+
+  const textParts: string[] = [];
+  const elementChildren: HostTreeNode[] = [];
+  for (const child of node.children) {
+    if (child.type === '#text') {
+      if (child.text) textParts.push(child.text);
+    } else {
+      elementChildren.push(child);
+    }
+  }
+
+  const props: Record<string, unknown> = { ...node.props };
+  if (textParts.length > 0 && props.children == null) {
+    props.children = textParts.join('');
+  }
+
+  const style: ResolvedStyle = resolveStyle(node.props.style);
+
+  return {
+    type: normalizeType(node.type),
+    props,
+    style,
+    children: elementChildren.map(toComponentNode).filter((n): n is ComponentNode => n !== null),
+  };
+}
+
+/**
+ * Expand an element to a `ComponentNode[]` via offline rendering.
+ *
+ * @returns the host-tree nodes, or `null` if offline rendering is unavailable
+ *          (react-reconciler not installed) or the render failed.
+ */
+export function expandToComponentNodes(element: ReactElement): ComponentNode[] | null {
+  const tree = renderToHostTree(element);
+  if (!tree) {
+    return null;
+  }
+  return tree.map(toComponentNode).filter((n): n is ComponentNode => n !== null);
+}