react-native-skelo 0.0.1 → 0.0.3

package/src/core/parser/hostTreeReconciler.tsx

@@ -0,0 +1,271 @@
+import React from 'react';
+import type { ReactElement } from 'react';
+
+/**
+ * A JS-only React renderer built on `react-reconciler`.
+ *
+ * It renders any element (including opaque function/class components) into a
+ * plain host-node tree — no native views, no `act()`, no deprecated APIs. Used
+ * to introspect a component's real View/Text/Image structure + styles so Skelo
+ * can generate a matching skeleton.
+ *
+ * Rendered as a synchronous LegacyRoot, so `updateContainer` flushes inline and
+ * we can read the tree immediately.
+ */
+
+export interface HostTreeNode {
+  type: string;
+  props: { style?: unknown; children?: unknown; [key: string]: unknown };
+  children: HostTreeNode[];
+  text?: string;
+}
+
+interface Container {
+  children: HostTreeNode[];
+}
+
+const NO_CONTEXT = {};
+
+const DefaultEventPriority = 32; // DefaultLane
+
+function makeHostConfig() {
+  // Reconciler 0.31 (React 19) tracks update priority via host methods.
+  let currentUpdatePriority = 0; // NoLane
+  return {
+    supportsMutation: true,
+    supportsPersistence: false,
+    supportsHydration: false,
+    isPrimaryRenderer: false,
+    noTimeout: -1,
+    now: () => Date.now(),
+    scheduleTimeout: setTimeout,
+    cancelTimeout: clearTimeout,
+    // Must be false: microtask scheduling defers the render, leaving the tree
+    // empty when we read it synchronously. Disabling it makes the LegacyRoot
+    // render commit inline inside updateContainer.
+    supportsMicrotasks: false,
+
+    getRootHostContext: () => NO_CONTEXT,
+    getChildHostContext: (parent: unknown) => parent,
+    getPublicInstance: (instance: unknown) => instance,
+    prepareForCommit: () => null,
+    resetAfterCommit: () => {},
+    preparePortalMount: () => {},
+
+    createInstance(type: string, props: HostTreeNode['props']): HostTreeNode {
+      return { type, props, children: [] };
+    },
+    createTextInstance(text: string): HostTreeNode {
+      return { type: '#text', props: {}, children: [], text };
+    },
+
+    appendInitialChild(parent: HostTreeNode, child: HostTreeNode) {
+      parent.children.push(child);
+    },
+    appendChild(parent: HostTreeNode, child: HostTreeNode) {
+      parent.children.push(child);
+    },
+    appendChildToContainer(container: Container, child: HostTreeNode) {
+      container.children.push(child);
+    },
+    insertBefore(parent: HostTreeNode, child: HostTreeNode, before: HostTreeNode) {
+      const i = parent.children.indexOf(before);
+      if (i === -1) parent.children.push(child);
+      else parent.children.splice(i, 0, child);
+    },
+    insertInContainerBefore(container: Container, child: HostTreeNode, before: HostTreeNode) {
+      const i = container.children.indexOf(before);
+      if (i === -1) container.children.push(child);
+      else container.children.splice(i, 0, child);
+    },
+    removeChild(parent: HostTreeNode, child: HostTreeNode) {
+      const i = parent.children.indexOf(child);
+      if (i !== -1) parent.children.splice(i, 1);
+    },
+    removeChildFromContainer(container: Container, child: HostTreeNode) {
+      const i = container.children.indexOf(child);
+      if (i !== -1) container.children.splice(i, 1);
+    },
+
+    finalizeInitialChildren: () => false,
+    shouldSetTextContent: () => false,
+    prepareUpdate: () => ({}),
+    commitUpdate(
+      instance: HostTreeNode,
+      _payload: unknown,
+      _type: string,
+      _old: unknown,
+      newProps: HostTreeNode['props']
+    ) {
+      instance.props = newProps;
+    },
+    commitTextUpdate(textInstance: HostTreeNode, _old: string, next: string) {
+      textInstance.text = next;
+    },
+    clearContainer(container: Container) {
+      container.children = [];
+    },
+    detachDeletedInstance: () => {},
+
+    // Required by React 18/19 reconcilers:
+    getCurrentEventPriority: () => DefaultEventPriority,
+    // Reconciler 0.31 (React 19) replaced the above with update-priority hooks;
+    // requestUpdateLane() calls these, so they must exist or it throws
+    // "undefined is not a function".
+    setCurrentUpdatePriority: (priority: number) => {
+      currentUpdatePriority = priority;
+    },
+    getCurrentUpdatePriority: () => currentUpdatePriority,
+    resolveUpdatePriority: () => currentUpdatePriority || DefaultEventPriority,
+    beforeActiveInstanceBlur: () => {},
+    afterActiveInstanceBlur: () => {},
+    prepareScopeUpdate: () => {},
+    getInstanceFromScope: () => null,
+    getInstanceFromNode: () => null,
+
+    // Newer reconciler (0.31 / React 19) additions — harmless on older versions:
+    maySuspendCommit: () => false,
+    startSuspendingCommit: () => {},
+    suspendInstance: () => {},
+    waitForCommitToBeReady: () => null,
+    NotPendingTransition: null,
+    // React 19 reads this context during render; it must be a real context.
+    HostTransitionContext: React.createContext(null),
+    resetFormInstance: () => {},
+    requestPostPaintCallback: () => {},
+    shouldAttemptEagerTransition: () => false,
+    trackSchedulerEvent: () => {},
+    resolveEventType: () => null,
+    resolveEventTimeStamp: () => -1.1,
+  };
+}
+
+class RenderBoundary extends React.Component<{ children: React.ReactNode }> {
+  static getDerivedStateFromError() {
+    return {};
+  }
+  render() {
+    return this.props.children;
+  }
+}
+
+let cachedReconciler:
+  | ((config: unknown) => {
+      createContainer: (...args: unknown[]) => unknown;
+      updateContainer: (...args: unknown[]) => unknown;
+    })
+  | null = null;
+
+function getReconciler() {
+  if (cachedReconciler) return cachedReconciler;
+
+  const Reconciler = require('react-reconciler');
+  cachedReconciler = Reconciler.default || Reconciler;
+  return cachedReconciler;
+}
+
+/**
+ * Render an element to a plain host-node tree, or return null if the reconciler
+ * is unavailable or rendering failed.
+ */
+export function renderToHostTree(element: ReactElement): HostTreeNode[] | null {
+  let Reconciler;
+  try {
+    Reconciler = getReconciler();
+  } catch {
+    return null;
+  }
+  if (!Reconciler) {
+    return null;
+  }
+
+  try {
+    // Wrap the host config so any method a newer reconciler calls that we
+    // didn't explicitly define resolves to a safe no-op instead of `undefined`
+    // (which throws "undefined is not a function"). All value-returning methods
+    // are defined above, so only side-effect methods hit this fallback.
+    const baseConfig = makeHostConfig() as Record<string, unknown>;
+    const noopFn = () => {};
+    const safeConfig = new Proxy(baseConfig, {
+      get(target, prop: string) {
+        if (prop in target) return target[prop];
+        return noopFn;
+      },
+    });
+    const reconciler = Reconciler(safeConfig);
+    const container: Container = { children: [] };
+    const noop = () => {};
+    // createContainer's signature differs across reconciler versions:
+    // React 19 (reconciler 0.31) added onUncaughtError/onCaughtError before
+    // onRecoverableError; React 18 (0.29) has a single onRecoverableError.
+    const isReact19 = parseInt(React.version, 10) >= 19;
+    const root = isReact19
+      ? reconciler.createContainer(
+          container,
+          0, // LegacyRoot -> synchronous
+          null,
+          false,
+          null,
+          '',
+          noop, // onUncaughtError
+          noop, // onCaughtError
+          noop, // onRecoverableError
+          null
+        )
+      : reconciler.createContainer(
+          container,
+          0,
+          null,
+          false,
+          null,
+          '',
+          noop, // onRecoverableError
+          null
+        );
+
+    const rc = reconciler as {
+      updateContainer: (...a: unknown[]) => unknown;
+      updateContainerSync?: (...a: unknown[]) => unknown;
+      flushSyncWork?: () => void;
+      flushSync?: (fn: () => void) => void;
+    };
+
+    const element0 = React.createElement(RenderBoundary, null, element);
+
+    // Render synchronously so the tree is populated before we read it.
+    // react-reconciler 0.31 (React 19) defers `updateContainer`; it exposes
+    // `updateContainerSync` + `flushSyncWork` for a guaranteed inline commit.
+    // Older 0.29 flushes inline via `flushSync(updateContainer)`.
+    if (typeof rc.updateContainerSync === 'function') {
+      rc.updateContainerSync(element0, root, null, noop);
+      rc.flushSyncWork?.();
+    } else if (typeof rc.flushSync === 'function') {
+      rc.flushSync(() => rc.updateContainer(element0, root, null, noop));
+    } else {
+      rc.updateContainer(element0, root, null, noop);
+    }
+
+    const tree = container.children.slice();
+
+    // Unmount to run cleanup.
+    if (typeof rc.updateContainerSync === 'function') {
+      rc.updateContainerSync(null, root, null, noop);
+      rc.flushSyncWork?.();
+    } else {
+      rc.updateContainer(null, root, null, noop);
+    }
+
+    if (__DEV__ && tree.length === 0) {
+      console.warn(
+        '[Skelo] Offline render produced an empty tree; falling back to static parsing.'
+      );
+    }
+
+    return tree;
+  } catch (error) {
+    if (__DEV__) {
+      console.warn('[Skelo] Offline render failed:', error);
+    }
+    return null;
+  }
+}

package/src/core/parser/index.ts

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

package/src/core/registry/SkeletonRegistry.ts

@@ -0,0 +1,111 @@
+import type { ComponentType } from 'react';
+import type { SkeletonPlugin } from '../../types';
+
+/**
+ * Registry for skeleton plugins
+ *
+ * Manages mapping between React components and their skeleton generation strategies
+ */
+export class SkeletonRegistry {
+  private plugins: Map<ComponentType<any>, SkeletonPlugin> = new Map();
+  private nameIndex: Map<string, SkeletonPlugin> = new Map();
+
+  /**
+   * Register a plugin for a component
+   *
+   * @param plugin - Plugin configuration
+   * @throws Error if plugin is invalid
+   */
+  register<P>(plugin: SkeletonPlugin<P>): void {
+    // Validation
+    if (!plugin.name) {
+      throw new Error('[Skelo] Plugin must have a name');
+    }
+
+    if (!plugin.component) {
+      throw new Error('[Skelo] Plugin must specify a component');
+    }
+
+    if (!plugin.strategy) {
+      throw new Error('[Skelo] Plugin must have a strategy function');
+    }
+
+    // Check for conflicts
+    if (this.plugins.has(plugin.component)) {
+      if (__DEV__) {
+        console.warn(`[Skelo] Plugin "${plugin.name}" is overriding existing plugin for component`);
+      }
+    }
+
+    // Register
+    this.plugins.set(plugin.component, plugin);
+    this.nameIndex.set(plugin.name, plugin);
+
+    if (__DEV__) {
+      console.log(`[Skelo] Registered plugin: ${plugin.name}`);
+    }
+  }
+
+  /**
+   * Unregister a plugin
+   *
+   * @param component - Component to unregister
+   */
+  unregister(component: ComponentType): void {
+    const plugin = this.plugins.get(component);
+    if (plugin) {
+      this.plugins.delete(component);
+      this.nameIndex.delete(plugin.name);
+    }
+  }
+
+  /**
+   * Get plugin for a component
+   *
+   * @param component - Component type
+   * @returns Plugin or undefined
+   */
+  getPlugin(component: ComponentType): SkeletonPlugin | undefined {
+    return this.plugins.get(component);
+  }
+
+  /**
+   * Get plugin by name
+   *
+   * @param name - Plugin name
+   * @returns Plugin or undefined
+   */
+  getPluginByName(name: string): SkeletonPlugin | undefined {
+    return this.nameIndex.get(name);
+  }
+
+  /**
+   * Check if component has a plugin
+   *
+   * @param component - Component type
+   * @returns True if plugin exists
+   */
+  hasPlugin(component: ComponentType): boolean {
+    return this.plugins.has(component);
+  }
+
+  /**
+   * Get all registered plugins
+   *
+   * @returns Array of all plugins
+   */
+  getAllPlugins(): SkeletonPlugin[] {
+    return Array.from(this.plugins.values());
+  }
+
+  /**
+   * Clear all plugins
+   */
+  clear(): void {
+    this.plugins.clear();
+    this.nameIndex.clear();
+  }
+}
+
+// Singleton instance
+export const registry = new SkeletonRegistry();

package/src/core/registry/index.ts

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

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