auto-loading-skeleton 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Your Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,242 @@
+# auto-loading-skeleton 🦴
+
+> Automatically generate loading skeleton UIs from your existing React components — no manual skeleton screens needed.
+
+[![npm version](https://img.shields.io/npm/v/auto-loading-skeleton.svg)](https://www.npmjs.com/package/auto-loading-skeleton)
+[![license](https://img.shields.io/npm/l/auto-loading-skeleton.svg)](LICENSE)
+
+---
+
+## The Problem
+
+Every React developer has written this pattern manually:
+
+```jsx
+// ❌ The old way — maintain TWO versions of every component
+{loading ? <SkeletonCard /> : <ProductCard product={data} />}
+```
+
+This means duplicating structure, breaking skeletons every time the real component changes, and wasting hours on boilerplate.
+
+---
+
+## The Solution
+
+```jsx
+// ✅ The new way — one wrapper, zero effort
+import { AutoSkeleton } from 'auto-loading-skeleton';
+
+<AutoSkeleton loading={loading}>
+  <ProductCard product={data} />
+</AutoSkeleton>
+```
+
+`AutoSkeleton` analyzes your component tree and automatically renders matching skeleton placeholders — preserving layout, spacing, and proportions.
+
+---
+
+## Installation
+
+```bash
+npm install auto-loading-skeleton
+# or
+yarn add auto-loading-skeleton
+```
+
+**Peer dependencies:** React >= 16.8
+
+---
+
+## Quick Start
+
+```jsx
+import React, { useState, useEffect } from 'react';
+import { AutoSkeleton } from 'auto-loading-skeleton';
+
+function App() {
+  const [loading, setLoading] = useState(true);
+  const [product, setProduct] = useState(null);
+
+  useEffect(() => {
+    fetchProduct().then(data => {
+      setProduct(data);
+      setLoading(false);
+    });
+  }, []);
+
+  return (
+    <AutoSkeleton loading={loading}>
+      <ProductCard product={product} />
+    </AutoSkeleton>
+  );
+}
+```
+
+---
+
+## API Reference
+
+### `<AutoSkeleton>`
+
+| Prop        | Type      | Default      | Description                                          |
+|-------------|-----------|--------------|------------------------------------------------------|
+| `loading`   | `boolean` | **required** | Show skeleton when true, real content when false     |
+| `animation` | `string`  | `'shimmer'`  | `'shimmer'` / `'pulse'` / `'wave'` / `'none'`       |
+| `theme`     | `object`  | `{}`         | CSS custom property overrides (see Theming)          |
+| `count`     | `number`  | `1`          | Repeat the skeleton N times (great for lists)        |
+| `className` | `string`  | `''`         | Extra CSS class on the wrapper                       |
+| `style`     | `object`  | `{}`         | Extra inline styles on the wrapper                   |
+
+```jsx
+<AutoSkeleton loading={isLoading} animation="wave" count={3}
+  theme={{ baseColor: '#f0f0f0', duration: '1.2s' }}>
+  <ArticleCard article={article} />
+</AutoSkeleton>
+```
+
+---
+
+### `<SkeletonBlock>`
+
+A single configurable skeleton rectangle, circle, or pill.
+
+```jsx
+import { SkeletonBlock } from 'auto-loading-skeleton';
+
+<SkeletonBlock width="200px" height="20px" />
+<SkeletonBlock width="48px" height="48px" shape="circle" />
+<SkeletonBlock width="120px" height="36px" shape="pill" animation="pulse" />
+```
+
+---
+
+### `<SkeletonText>`
+
+One or more text-line placeholders.
+
+```jsx
+import { SkeletonText } from 'auto-loading-skeleton';
+<SkeletonText lines={4} lastLineWidth="50%" />
+```
+
+---
+
+### `<SkeletonAvatar>`
+
+A circular avatar placeholder.
+
+```jsx
+import { SkeletonAvatar } from 'auto-loading-skeleton';
+<SkeletonAvatar size="56px" animation="pulse" />
+```
+
+---
+
+### `useSkeleton` hook
+
+```jsx
+const { loading, setLoading, skeletonProps } = useSkeleton(true);
+
+<AutoSkeleton {...skeletonProps} animation="wave">
+  <ProfileCard />
+</AutoSkeleton>
+```
+
+---
+
+### `withSkeleton` HOC
+
+```jsx
+const SkeletonProductCard = withSkeleton(ProductCard, { animation: 'shimmer' });
+
+// Just pass a `loading` prop alongside your component's own props
+<SkeletonProductCard loading={isLoading} product={data} />
+```
+
+---
+
+## Animations
+
+| Value     | Description                         |
+|-----------|-------------------------------------|
+| `shimmer` | Left-to-right light sweep (default) |
+| `pulse`   | Gentle fade in / fade out           |
+| `wave`    | Soft ripple wave effect             |
+| `none`    | Static blocks, no animation         |
+
+---
+
+## Theming
+
+```jsx
+<AutoSkeleton loading={loading} theme={{
+  baseColor:    '#dde3ea',
+  shimmerColor: 'rgba(255,255,255,0.6)',
+  duration:     '1.2s',
+  borderRadius: '6px',
+}}>
+  <MyComponent />
+</AutoSkeleton>
+```
+
+Or globally via CSS custom properties:
+
+```css
+:root {
+  --ask-base-color:    #dde3ea;
+  --ask-shimmer-color: rgba(255, 255, 255, 0.6);
+  --ask-duration:      1.2s;
+  --ask-border-radius: 6px;
+}
+```
+
+Dark mode is handled automatically via `@media (prefers-color-scheme: dark)`.
+
+---
+
+## How It Works
+
+1. **Analyze** — Traverses the React element tree when `loading` is `true`
+2. **Classify** — Tags each node as `text`, `image`, `avatar`, `button`, `input`, `icon`, or `container`
+3. **Render** — Converts each node into a proportional skeleton block
+4. **Animate** — Injects CSS animations once into `<head>`
+
+### Element Detection
+
+| Element / Pattern                     | Detected As   |
+|---------------------------------------|---------------|
+| `<img>`                               | IMAGE         |
+| `<img className="avatar">`            | AVATAR        |
+| `<button>`, `role="button"`           | BUTTON        |
+| `<input>`, `<textarea>`, `<select>`   | INPUT         |
+| `<svg>`, `.icon-*`                    | ICON          |
+| `<h1>`–`<h6>` with text              | TEXT (heading)|
+| `<p>`, `<span>` with text             | TEXT          |
+| Any element with children             | CONTAINER     |
+
+---
+
+## List Skeletons
+
+```jsx
+<AutoSkeleton loading={loading} count={5}>
+  <ProductCard product={sampleProduct} />
+</AutoSkeleton>
+```
+
+---
+
+## Low-Level API
+
+```js
+import { analyzeElement, renderNode, injectStyles } from 'auto-loading-skeleton';
+
+const tree = analyzeElement(<MyComponent />);
+const skeletonEl = renderNode(tree, { animation: 'shimmer' });
+```
+
+---
+
+## License
+
+MIT © Your Name

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "auto-loading-skeleton",
+  "version": "1.0.0",
+  "description": "Automatically generate loading skeleton UIs from your existing React components \u2014 no manual skeleton screens needed.",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "types": "./src/index.d.ts"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "echo \"Run tests with your preferred test runner\""
+  },
+  "keywords": [
+    "react",
+    "skeleton",
+    "loading",
+    "placeholder",
+    "ui",
+    "shimmer",
+    "auto-skeleton",
+    "loading-skeleton",
+    "skeleton-screen",
+    "pulse",
+    "wave"
+  ],
+  "author": "Your Name <you@example.com>",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": ">=16.8.0",
+    "react-dom": ">=16.8.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yourusername/auto-loading-skeleton.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yourusername/auto-loading-skeleton/issues"
+  },
+  "homepage": "https://github.com/yourusername/auto-loading-skeleton#readme"
+}

package/src/AutoSkeleton.jsx

@@ -0,0 +1,72 @@
+/**
+ * AutoSkeleton.jsx
+ * Main wrapper component.
+ *
+ * Usage:
+ *   <AutoSkeleton loading={isLoading}>
+ *     <ProductCard />
+ *   </AutoSkeleton>
+ */
+
+import React, { useEffect, useMemo } from 'react';
+import { analyzeTree } from './analyzer.js';
+import { renderSkeletonNodes } from './renderer.js';
+import { injectStyles } from './styles.js';
+
+/**
+ * @typedef {Object} AutoSkeletonProps
+ * @property {boolean}           loading       - Show skeleton when true
+ * @property {React.ReactNode}   children      - The real UI component(s)
+ * @property {'shimmer'|'pulse'|'wave'|'none'} [animation='shimmer']
+ * @property {number}            [repeat=1]    - Repeat skeleton N times (e.g. list items)
+ * @property {object}            [theme]       - { baseColor, highlightColor }
+ * @property {React.CSSProperties} [style]     - Wrapper style
+ * @property {string}            [className]   - Wrapper className
+ * @property {string}            [ariaLabel]   - aria-label for the skeleton wrapper
+ */
+
+export function AutoSkeleton({
+  loading = false,
+  children,
+  animation = 'shimmer',
+  repeat = 1,
+  theme = {},
+  style,
+  className,
+  ariaLabel = 'Loading…',
+}) {
+  // Inject global CSS once
+  useEffect(() => { injectStyles(); }, []);
+
+  // Analyse the child tree once (memoised — re-runs only when children change)
+  const skeletonNodes = useMemo(() => {
+    if (!loading) return null;
+    const childArray = React.Children.toArray(children);
+    return childArray.flatMap(child => analyzeTree(child));
+  }, [loading, children]);
+
+  if (!loading) return children;
+
+  const options = { animation, theme };
+  const units = Array.from({ length: repeat }, (_, i) =>
+    React.createElement(
+      'div',
+      { key: i, style: i > 0 ? { marginTop: 16 } : undefined },
+      renderSkeletonNodes(skeletonNodes, options)
+    )
+  );
+
+  return React.createElement(
+    'div',
+    {
+      role: 'status',
+      'aria-busy': true,
+      'aria-label': ariaLabel,
+      style,
+      className,
+    },
+    ...units
+  );
+}
+
+export default AutoSkeleton;

package/src/SkeletonItem.jsx

@@ -0,0 +1,99 @@
+/**
+ * SkeletonItem.jsx
+ * Low-level primitive for manual skeleton building if needed.
+ *
+ * Usage:
+ *   <SkeletonItem type="text" lines={2} />
+ *   <SkeletonItem type="avatar" size={48} />
+ *   <SkeletonItem type="image" width="100%" height={200} />
+ */
+
+import React, { useEffect } from 'react';
+import { buildClassName, injectStyles } from './styles.js';
+
+export function SkeletonItem({
+  type = 'text',
+  lines = 1,
+  width,
+  height,
+  size,
+  animation = 'shimmer',
+  theme = {},
+  style: extraStyle = {},
+}) {
+  useEffect(() => { injectStyles(); }, []);
+
+  const cssVars = {
+    ...(theme.baseColor && { '--skeleton-base-color': theme.baseColor }),
+    ...(theme.highlightColor && { '--skeleton-highlight-color': theme.highlightColor }),
+    ...extraStyle,
+  };
+
+  switch (type) {
+    case 'text': {
+      const cls = buildClassName(animation, 'auto-skeleton-text-line');
+      if (lines === 1) {
+        return React.createElement('div', {
+          className: cls,
+          style: { width: width || '80%', ...cssVars },
+          'aria-hidden': true,
+        });
+      }
+      const lineEls = Array.from({ length: lines }, (_, i) =>
+        React.createElement('div', {
+          key: i,
+          className: cls,
+          style: { width: i === lines - 1 ? '65%' : '100%', ...cssVars },
+          'aria-hidden': true,
+        })
+      );
+      return React.createElement('div', {
+        className: 'auto-skeleton-text-block',
+        style: cssVars,
+        'aria-hidden': true,
+      }, ...lineEls);
+    }
+
+    case 'avatar': {
+      const px = size ? `${size}px` : (width || '40px');
+      return React.createElement('div', {
+        className: buildClassName(animation, 'auto-skeleton-avatar-block'),
+        style: { width: px, height: size ? `${size}px` : (height || px), ...cssVars },
+        'aria-hidden': true,
+      });
+    }
+
+    case 'image': {
+      return React.createElement('div', {
+        className: buildClassName(animation, 'auto-skeleton-image-block'),
+        style: {
+          width: width || '100%',
+          ...(height ? { paddingTop: 0, height } : {}),
+          ...cssVars,
+        },
+        'aria-hidden': true,
+      });
+    }
+
+    case 'button': {
+      return React.createElement('div', {
+        className: buildClassName(animation, 'auto-skeleton-button-block'),
+        style: { width: width || 100, ...cssVars },
+        'aria-hidden': true,
+      });
+    }
+
+    case 'input': {
+      return React.createElement('div', {
+        className: 'auto-skeleton-input-block',
+        style: cssVars,
+        'aria-hidden': true,
+      });
+    }
+
+    default:
+      return null;
+  }
+}
+
+export default SkeletonItem;

package/src/analyzer.js

@@ -0,0 +1,113 @@
+const ELEMENT_TYPES = {
+  TEXT:      'text',
+  IMAGE:     'image',
+  AVATAR:    'avatar',
+  BUTTON:    'button',
+  INPUT:     'input',
+  CONTAINER: 'container',
+  ICON:      'icon',
+};
+
+function inferType(element) {
+  if (!element || typeof element !== 'object') return ELEMENT_TYPES.TEXT;
+  var type = element.type;
+  var props = element.props || {};
+  var tag = typeof type === 'string' ? type.toLowerCase() : '';
+  var cls = (props.className || '').toLowerCase();
+  var alt = (props.alt || '').toLowerCase();
+  var role = (props.role || '').toLowerCase();
+
+  if (tag === 'img') {
+    var isAvatar = cls.includes('avatar') || cls.includes('profile') || alt.includes('avatar');
+    return isAvatar ? ELEMENT_TYPES.AVATAR : ELEMENT_TYPES.IMAGE;
+  }
+  if (tag === 'button' || role === 'button') return ELEMENT_TYPES.BUTTON;
+  if (tag === 'input' || tag === 'textarea' || tag === 'select') return ELEMENT_TYPES.INPUT;
+  if (tag === 'svg' || cls.includes('icon')) return ELEMENT_TYPES.ICON;
+  if (cls.includes('avatar') || cls.includes('profile-pic')) return ELEMENT_TYPES.AVATAR;
+  return ELEMENT_TYPES.CONTAINER;
+}
+
+function isTextLeaf(element) {
+  if (!element || typeof element !== 'object') return false;
+  var children = element.props && element.props.children;
+  if (typeof children === 'string') return true;
+  if (typeof children === 'number') return true;
+  if (Array.isArray(children)) {
+    return children.every(function(c) { return typeof c === 'string' || typeof c === 'number'; });
+  }
+  return false;
+}
+
+function extractStyleHints(element) {
+  var props = (element && element.props) || {};
+  var style = props.style || {};
+  return {
+    width: style.width,
+    height: style.height,
+    borderRadius: style.borderRadius,
+    display: style.display,
+    flexDirection: style.flexDirection,
+    alignItems: style.alignItems,
+    gap: style.gap,
+    padding: style.padding,
+    margin: style.margin,
+  };
+}
+
+function analyzeElement(element, depth) {
+  depth = depth || 0;
+  if (element === null || element === undefined) return null;
+  if (typeof element === 'string' || typeof element === 'number') {
+    return { nodeType: ELEMENT_TYPES.TEXT, content: String(element), depth: depth };
+  }
+  if (typeof element === 'boolean') return null;
+
+  if (Array.isArray(element)) {
+    return element.map(function(el) { return analyzeElement(el, depth); }).filter(Boolean);
+  }
+
+  var type = element.type;
+  var props = element.props || {};
+  var styleHints = extractStyleHints(element);
+
+  // Structural elements take priority over text-leaf detection
+  var earlyType = inferType(element);
+  if (earlyType === ELEMENT_TYPES.BUTTON || earlyType === ELEMENT_TYPES.INPUT) {
+    var lbl = earlyType === ELEMENT_TYPES.BUTTON && typeof props.children === 'string' ? props.children : '';
+    return { nodeType: earlyType, label: lbl, styleHints: styleHints, depth: depth };
+  }
+
+  if (isTextLeaf(element)) {
+    var tag = typeof type === 'string' ? type.toLowerCase() : '';
+    var isHeading = /^h[1-6]$/.test(tag);
+    return { nodeType: ELEMENT_TYPES.TEXT, isHeading: isHeading, tag: tag, content: String(props.children), styleHints: styleHints, depth: depth };
+  }
+
+  var nodeType = inferType(element);
+
+  if (nodeType === ELEMENT_TYPES.IMAGE || nodeType === ELEMENT_TYPES.AVATAR || nodeType === ELEMENT_TYPES.ICON) {
+    return { nodeType: nodeType, styleHints: styleHints, depth: depth };
+  }
+  if (nodeType === ELEMENT_TYPES.BUTTON) {
+    return { nodeType: ELEMENT_TYPES.BUTTON, label: typeof props.children === 'string' ? props.children : '', styleHints: styleHints, depth: depth };
+  }
+  if (nodeType === ELEMENT_TYPES.INPUT) {
+    return { nodeType: ELEMENT_TYPES.INPUT, styleHints: styleHints, depth: depth };
+  }
+
+  var rawChildren = props.children;
+  var children = [];
+  if (rawChildren) {
+    var arr = Array.isArray(rawChildren) ? rawChildren : [rawChildren];
+    arr.forEach(function(child) {
+      var result = analyzeElement(child, depth + 1);
+      if (Array.isArray(result)) { result.forEach(function(r) { if (r) children.push(r); }); }
+      else if (result) children.push(result);
+    });
+  }
+
+  return { nodeType: ELEMENT_TYPES.CONTAINER, tag: typeof type === 'string' ? type : 'div', styleHints: styleHints, children: children, depth: depth };
+}
+
+module.exports = { analyzeElement: analyzeElement, ELEMENT_TYPES: ELEMENT_TYPES };

package/src/index.d.ts

@@ -0,0 +1,51 @@
+import { ReactNode, CSSProperties, FC } from 'react';
+
+export type SkeletonAnimation = 'shimmer' | 'pulse' | 'wave' | 'none';
+
+export interface SkeletonTheme {
+  /** Base skeleton color. Default: #e2e8f0 */
+  baseColor?: string;
+  /** Highlight color for shimmer/wave. Default: #f8fafc */
+  highlightColor?: string;
+}
+
+export interface AutoSkeletonProps {
+  /** Show skeleton when true, render real children when false */
+  loading: boolean;
+  children: ReactNode;
+  /** Animation style. Default: 'shimmer' */
+  animation?: SkeletonAnimation;
+  /** Repeat the skeleton pattern N times. Useful for lists. Default: 1 */
+  repeat?: number;
+  /** Theme overrides */
+  theme?: SkeletonTheme;
+  style?: CSSProperties;
+  className?: string;
+  /** Accessible label for the loading region. Default: 'Loading…' */
+  ariaLabel?: string;
+}
+
+export type SkeletonItemType = 'text' | 'image' | 'avatar' | 'button' | 'input';
+
+export interface SkeletonItemProps {
+  type?: SkeletonItemType;
+  lines?: number;
+  width?: number | string;
+  height?: number | string;
+  /** For avatar type: shorthand for equal width and height */
+  size?: number;
+  animation?: SkeletonAnimation;
+  theme?: SkeletonTheme;
+  style?: CSSProperties;
+}
+
+/** Main wrapper component — auto-generates a skeleton from its children */
+export const AutoSkeleton: FC<AutoSkeletonProps>;
+
+/** Primitive building block for manually-crafted skeletons */
+export const SkeletonItem: FC<SkeletonItemProps>;
+
+/** Inject global CSS (called automatically; export for SSR use) */
+export function injectStyles(): void;
+
+export default AutoSkeleton;

package/src/index.js

@@ -0,0 +1,102 @@
+const React = require('react');
+const { analyzeElement } = require('./analyzer');
+const { renderNode } = require('./renderer');
+const { injectStyles, blockClass, buildThemeVars } = require('./styles');
+
+function AutoSkeleton(props) {
+  var loading = props.loading;
+  var animation = props.animation || 'shimmer';
+  var theme = props.theme || {};
+  var count = props.count || 1;
+  var children = props.children;
+  var className = props.className || '';
+  var style = props.style || {};
+
+  React.useEffect(function() { injectStyles(); }, []);
+  if (typeof document !== 'undefined') injectStyles();
+
+  if (!loading) return children;
+
+  var cssVarStyle = {};
+  var varMap = { baseColor: '--ask-base-color', shimmerColor: '--ask-shimmer-color', duration: '--ask-duration', borderRadius: '--ask-border-radius' };
+  Object.entries(theme).forEach(function(pair) { if (varMap[pair[0]]) cssVarStyle[varMap[pair[0]]] = pair[1]; });
+
+  var descriptor = analyzeElement(children);
+  var skeletonEl = renderNode(descriptor, { animation: animation });
+
+  var items = [];
+  for (var i = 0; i < Math.max(1, count); i++) {
+    items.push(React.createElement('div', { key: i, style: i < count - 1 ? { marginBottom: '16px' } : {} }, skeletonEl));
+  }
+
+  return React.createElement('div', {
+    className: 'ask-wrapper' + (className ? ' ' + className : ''),
+    style: Object.assign({}, style, cssVarStyle),
+    'aria-busy': 'true',
+    'aria-label': 'Loading\u2026',
+  }, items);
+}
+
+function SkeletonBlock(props) {
+  var width = props.width || '100%';
+  var height = props.height || '16px';
+  var shape = props.shape;
+  var animation = props.animation || 'shimmer';
+  var style = props.style || {};
+  var className = props.className || '';
+  React.useEffect(function() { injectStyles(); }, []);
+  if (typeof document !== 'undefined') injectStyles();
+  return React.createElement('span', {
+    className: blockClass(animation, shape) + (className ? ' ' + className : ''),
+    style: Object.assign({ width: width, height: height, display: 'block' }, style),
+    'aria-hidden': 'true',
+  });
+}
+
+function SkeletonText(props) {
+  var lines = props.lines || 3;
+  var animation = props.animation || 'shimmer';
+  var lastLineWidth = props.lastLineWidth || '60%';
+  var lineHeight = props.lineHeight || '1em';
+  var gap = props.gap || '8px';
+  var style = props.style || {};
+  React.useEffect(function() { injectStyles(); }, []);
+  if (typeof document !== 'undefined') injectStyles();
+  var lineEls = [];
+  for (var i = 0; i < lines; i++) {
+    lineEls.push(React.createElement('span', { key: i, className: blockClass(animation), style: { display: 'block', width: i === lines - 1 ? lastLineWidth : '100%', height: lineHeight, marginBottom: i < lines - 1 ? gap : 0 }, 'aria-hidden': 'true' }));
+  }
+  return React.createElement('div', { style: style, 'aria-hidden': 'true' }, lineEls);
+}
+
+function SkeletonAvatar(props) {
+  var size = props.size || '40px';
+  return React.createElement(SkeletonBlock, { width: size, height: size, shape: 'circle', animation: props.animation || 'shimmer', style: props.style || {} });
+}
+
+function useSkeleton(initialLoading, options) {
+  initialLoading = initialLoading !== undefined ? initialLoading : true;
+  options = options || {};
+  var state = React.useState(initialLoading);
+  var loading = state[0];
+  var setLoading = state[1];
+  return { loading: loading, setLoading: setLoading, skeletonProps: Object.assign({ loading: loading }, options) };
+}
+
+function withSkeleton(WrappedComponent, defaultOptions) {
+  defaultOptions = defaultOptions || {};
+  var displayName = WrappedComponent.displayName || WrappedComponent.name || 'Component';
+  function WithSkeletonWrapper(props) {
+    var loading = props.loading !== undefined ? props.loading : false;
+    var skeletonAnimation = props.skeletonAnimation;
+    var skeletonTheme = props.skeletonTheme;
+    var skeletonCount = props.skeletonCount;
+    var rest = Object.assign({}, props);
+    delete rest.loading; delete rest.skeletonAnimation; delete rest.skeletonTheme; delete rest.skeletonCount;
+    return React.createElement(AutoSkeleton, { loading: loading, animation: skeletonAnimation || defaultOptions.animation || 'shimmer', theme: skeletonTheme || defaultOptions.theme || {}, count: skeletonCount || defaultOptions.count || 1 }, React.createElement(WrappedComponent, rest));
+  }
+  WithSkeletonWrapper.displayName = 'WithSkeleton(' + displayName + ')';
+  return WithSkeletonWrapper;
+}
+
+module.exports = { AutoSkeleton, SkeletonBlock, SkeletonText, SkeletonAvatar, useSkeleton, withSkeleton, analyzeElement, renderNode, injectStyles };

package/src/renderer.js

@@ -0,0 +1,84 @@
+const React = require('react');
+const { ELEMENT_TYPES } = require('./analyzer');
+const { blockClass } = require('./styles');
+
+const DEFAULTS = {
+  text:    { width: '80%',  height: '1em'   },
+  heading: { width: '60%',  height: '1.4em' },
+  image:   { width: '100%', height: '200px' },
+  avatar:  { width: '40px', height: '40px'  },
+  button:  { width: '100px',height: '36px'  },
+  input:   { width: '100%', height: '38px'  },
+  icon:    { width: '24px', height: '24px'  },
+};
+
+let _key = 0;
+function nk() { return 'ask-' + (++_key); }
+
+function bStyle(def, hints, extra) {
+  hints = hints || {};
+  extra = extra || {};
+  return Object.assign({ width: hints.width || def.width, height: hints.height || def.height, display: 'block', margin: hints.margin || '0' }, extra);
+}
+
+function renderNode(node, options) {
+  if (!node) return null;
+  options = options || {};
+  var animation = options.animation || 'shimmer';
+  var nodeType = node.nodeType;
+  var hints = node.styleHints || {};
+
+  if (nodeType === ELEMENT_TYPES.TEXT) {
+    var isHeading = node.isHeading;
+    var def = isHeading ? DEFAULTS.heading : DEFAULTS.text;
+    var len = (node.content || '').length;
+    var lines = Math.min(Math.max(1, Math.round(len / 40)), 4);
+    if (lines <= 1) {
+      return React.createElement('span', { key: nk(), className: blockClass(animation), style: bStyle(def, hints, { width: hints.width || (len > 60 ? '95%' : def.width) }), 'aria-hidden': 'true' });
+    }
+    var lineEls = [];
+    for (var i = 0; i < lines; i++) {
+      lineEls.push(React.createElement('span', { key: nk(), className: blockClass(animation), style: { display: 'block', width: i === lines-1 ? '65%' : '100%', height: def.height, marginBottom: '6px' }, 'aria-hidden': 'true' }));
+    }
+    return React.createElement('div', { key: nk() }, lineEls);
+  }
+
+  if (nodeType === ELEMENT_TYPES.IMAGE) {
+    return React.createElement('span', { key: nk(), className: blockClass(animation, 'rounded'), style: bStyle(DEFAULTS.image, hints), 'aria-hidden': 'true' });
+  }
+
+  if (nodeType === ELEMENT_TYPES.AVATAR) {
+    return React.createElement('span', { key: nk(), className: blockClass(animation, 'circle'), style: bStyle(DEFAULTS.avatar, hints), 'aria-hidden': 'true' });
+  }
+
+  if (nodeType === ELEMENT_TYPES.ICON) {
+    return React.createElement('span', { key: nk(), className: blockClass(animation, 'circle'), style: bStyle(DEFAULTS.icon, hints), 'aria-hidden': 'true' });
+  }
+
+  if (nodeType === ELEMENT_TYPES.BUTTON) {
+    return React.createElement('span', { key: nk(), className: blockClass(animation, 'pill'), style: bStyle(DEFAULTS.button, hints), 'aria-hidden': 'true' });
+  }
+
+  if (nodeType === ELEMENT_TYPES.INPUT) {
+    return React.createElement('span', { key: nk(), className: blockClass(animation, 'rounded'), style: bStyle(DEFAULTS.input, hints), 'aria-hidden': 'true' });
+  }
+
+  if (nodeType === ELEMENT_TYPES.CONTAINER) {
+    var children = (node.children || []).map(function(c) { return renderNode(c, options); }).filter(Boolean);
+    var tag = node.tag || 'div';
+    var cStyle = {};
+    if (hints.display) cStyle.display = hints.display;
+    if (hints.flexDirection) cStyle.flexDirection = hints.flexDirection;
+    if (hints.gap) cStyle.gap = hints.gap;
+    if (hints.padding) cStyle.padding = hints.padding;
+    if (hints.margin) cStyle.margin = hints.margin;
+    if (children.length === 0) {
+      return React.createElement('span', { key: nk(), className: blockClass(animation), style: bStyle({ width: '100%', height: '20px' }, hints), 'aria-hidden': 'true' });
+    }
+    return React.createElement(tag, { key: nk(), style: cStyle, className: 'ask-wrapper' }, children);
+  }
+
+  return null;
+}
+
+module.exports = { renderNode };

package/src/styles.js

@@ -0,0 +1,76 @@
+const STYLE_ID = 'auto-skeleton-styles';
+
+const CSS = `
+.ask-block {
+  display: inline-block;
+  position: relative;
+  overflow: hidden;
+  background-color: var(--ask-base-color, #e2e8f0);
+  border-radius: var(--ask-border-radius, 4px);
+  vertical-align: middle;
+}
+.ask-shimmer::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  transform: translateX(-100%);
+  background: linear-gradient(90deg, transparent 0%, var(--ask-shimmer-color, rgba(255,255,255,0.55)) 50%, transparent 100%);
+  animation: ask-shimmer var(--ask-duration, 1.4s) infinite;
+}
+@keyframes ask-shimmer { 100% { transform: translateX(100%); } }
+.ask-pulse { animation: ask-pulse var(--ask-duration, 1.8s) ease-in-out infinite; }
+@keyframes ask-pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.45; } }
+.ask-wave::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  transform: translateX(-100%);
+  background: linear-gradient(90deg, transparent 0%, var(--ask-shimmer-color, rgba(255,255,255,0.8)) 50%, transparent 100%);
+  animation: ask-wave var(--ask-duration, 1.6s) ease-in-out infinite;
+  overflow: hidden;
+}
+@keyframes ask-wave { 0% { transform: translateX(-100%); } 100% { transform: translateX(150%); } }
+@media (prefers-color-scheme: dark) {
+  .ask-block { background-color: var(--ask-base-color-dark, #2d3748); }
+}
+.ask-circle  { border-radius: 50%; }
+.ask-rounded { border-radius: 8px; }
+.ask-pill    { border-radius: 9999px; }
+.ask-wrapper { pointer-events: none; user-select: none; }
+`;
+
+let injected = false;
+
+function injectStyles() {
+  if (injected || typeof document === 'undefined') return;
+  if (document.getElementById(STYLE_ID)) { injected = true; return; }
+  const style = document.createElement('style');
+  style.id = STYLE_ID;
+  style.textContent = CSS;
+  document.head.appendChild(style);
+  injected = true;
+}
+
+function blockClass(animation, shape) {
+  animation = animation || 'shimmer';
+  const parts = ['ask-block'];
+  if (animation !== 'none') parts.push('ask-' + animation);
+  if (shape) parts.push('ask-' + shape);
+  return parts.join(' ');
+}
+
+function buildThemeVars(theme) {
+  theme = theme || {};
+  const map = {
+    baseColor:    '--ask-base-color',
+    shimmerColor: '--ask-shimmer-color',
+    duration:     '--ask-duration',
+    borderRadius: '--ask-border-radius',
+  };
+  return Object.entries(theme)
+    .filter(function(pair) { return map[pair[0]]; })
+    .map(function(pair) { return map[pair[0]] + ':' + pair[1]; })
+    .join(';');
+}
+
+module.exports = { injectStyles, blockClass, buildThemeVars, CSS };