react-native-skelo 0.0.1 → 0.0.2

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

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