auto-loading-skeleton 1.0.2 → 2.0.0

package/src/hooks.js

@@ -0,0 +1,161 @@
+'use strict';
+
+/**
+ * hooks.js — V2
+ *
+ * useSkeleton        — basic loading state manager
+ * useSkeletonDelay   — avoids flash of skeleton for fast responses
+ * useSkeletonData    — async data fetcher that integrates loading state
+ * useSkeletonTimeout — shows skeleton for a minimum duration to avoid flicker
+ */
+
+var React = require('react');
+
+/**
+ * useSkeleton(initialLoading, options)
+ * Returns { loading, setLoading, skeletonProps }
+ */
+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),
+  };
+}
+
+/**
+ * useSkeletonDelay(loading, delay)
+ *
+ * Prevents skeleton flash for responses faster than `delay` ms.
+ * The skeleton only appears if loading has been true for longer than `delay`.
+ *
+ * Example: delay=200 means quick responses never show a skeleton at all.
+ */
+function useSkeletonDelay(loading, delay) {
+  delay = delay != null ? delay : 200;
+  var ref   = React.useRef(null);
+  var state = React.useState(false);
+  var show  = state[0];
+  var setShow = state[1];
+
+  React.useEffect(function() {
+    if (loading) {
+      ref.current = setTimeout(function() { setShow(true); }, delay);
+    } else {
+      if (ref.current) clearTimeout(ref.current);
+      setShow(false);
+    }
+    return function() { if (ref.current) clearTimeout(ref.current); };
+  }, [loading, delay]);
+
+  return show;
+}
+
+/**
+ * useSkeletonTimeout(loading, minDuration)
+ *
+ * Keeps the skeleton visible for at least `minDuration` ms even if data
+ * arrives early — avoids jarring instant transitions.
+ */
+function useSkeletonTimeout(loading, minDuration) {
+  minDuration    = minDuration != null ? minDuration : 500;
+  var startRef   = React.useRef(null);
+  var state      = React.useState(loading);
+  var show       = state[0];
+  var setShow    = state[1];
+
+  React.useEffect(function() {
+    if (loading) {
+      startRef.current = Date.now();
+      setShow(true);
+    } else {
+      var elapsed  = Date.now() - (startRef.current || Date.now());
+      var remaining = Math.max(0, minDuration - elapsed);
+      var tid = setTimeout(function() { setShow(false); }, remaining);
+      return function() { clearTimeout(tid); };
+    }
+  }, [loading, minDuration]);
+
+  return show;
+}
+
+/**
+ * useSkeletonData(fetchFn, deps)
+ *
+ * Runs an async fetch function and returns { data, loading, error }.
+ * fetchFn should return a Promise.
+ *
+ * Example:
+ *   const { data, loading } = useSkeletonData(() => fetch('/api/user').then(r => r.json()), [userId]);
+ */
+function useSkeletonData(fetchFn, deps) {
+  deps = deps || [];
+  var dataState  = React.useState(null);
+  var loadState  = React.useState(true);
+  var errState   = React.useState(null);
+  var data       = dataState[0]; var setData  = dataState[1];
+  var loading    = loadState[0]; var setLoad  = loadState[1];
+  var error      = errState[0];  var setError = errState[1];
+  var cancelRef  = React.useRef(false);
+
+  React.useEffect(function() {
+    cancelRef.current = false;
+    setLoad(true);
+    setError(null);
+    Promise.resolve(fetchFn()).then(function(result) {
+      if (!cancelRef.current) {
+        setData(result);
+        setLoad(false);
+      }
+    }).catch(function(err) {
+      if (!cancelRef.current) {
+        setError(err);
+        setLoad(false);
+      }
+    });
+    return function() { cancelRef.current = true; };
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, deps);
+
+  return { data: data, loading: loading, error: error };
+}
+
+/**
+ * withSkeleton(WrappedComponent, defaultOptions)
+ * Higher-order component version.
+ */
+function withSkeleton(WrappedComponent, defaultOptions) {
+  defaultOptions = defaultOptions || {};
+  var name       = WrappedComponent.displayName || WrappedComponent.name || 'Component';
+  var AutoSkeleton = require('./AutoSkeleton');
+
+  function WithSkeletonWrapper(props) {
+    var loading          = props.loading !== undefined ? props.loading : false;
+    var animation        = props.skeletonAnimation;
+    var theme            = props.skeletonTheme;
+    var themeOverrides   = props.skeletonThemeOverrides;
+    var count            = props.skeletonCount;
+    var rest = Object.assign({}, props);
+    delete rest.loading;
+    delete rest.skeletonAnimation;
+    delete rest.skeletonTheme;
+    delete rest.skeletonThemeOverrides;
+    delete rest.skeletonCount;
+    return React.createElement(AutoSkeleton, {
+      loading:       loading,
+      animation:     animation || defaultOptions.animation || 'shimmer',
+      theme:         theme     || defaultOptions.theme     || 'default',
+      themeOverrides:themeOverrides || defaultOptions.themeOverrides || {},
+      count:         count     || defaultOptions.count     || 1,
+    }, React.createElement(WrappedComponent, rest));
+  }
+  WithSkeletonWrapper.displayName = 'WithSkeleton(' + name + ')';
+  return WithSkeletonWrapper;
+}
+
+module.exports = { useSkeleton, useSkeletonDelay, useSkeletonTimeout, useSkeletonData, withSkeleton };

package/src/index.d.ts

@@ -1,51 +1,167 @@
-import { ReactNode, CSSProperties, FC } from 'react';
+import { ReactNode, CSSProperties, FC, Context, ComponentType } from 'react';
 
-export type SkeletonAnimation = 'shimmer' | 'pulse' | 'wave' | 'none';
+/* ── Animations ── */
+export type SkeletonAnimation = 'shimmer' | 'pulse' | 'wave' | 'glow' | 'none';
 
-export interface SkeletonTheme {
-  /** Base skeleton color. Default: #e2e8f0 */
-  baseColor?: string;
-  /** Highlight color for shimmer/wave. Default: #f8fafc */
-  highlightColor?: string;
+/* ── Theme presets ── */
+export type SkeletonThemePreset = 'default' | 'dark' | 'minimal' | 'soft' | 'brand' | 'warm';
+
+export interface SkeletonThemeOverrides {
+  baseColor?:       string;
+  highlightColor?:  string;
+  shimmerColor?:    string; // alias for highlightColor
+  duration?:        string;
+  borderRadius?:    string;
+  [cssVar: string]: string | undefined;
+}
+
+/* ── Context ── */
+export interface SkeletonContextValue {
+  animation:      SkeletonAnimation;
+  theme:          SkeletonThemePreset;
+  themeOverrides: SkeletonThemeOverrides;
+  fadeIn:         boolean;
+  maxDepth:       number;
+  detectRepeats:  boolean;
 }
 
+export declare const SkeletonContext: Context<SkeletonContextValue>;
+
+export interface SkeletonProviderProps {
+  animation?:      SkeletonAnimation;
+  theme?:          SkeletonThemePreset;
+  themeOverrides?: SkeletonThemeOverrides;
+  fadeIn?:         boolean;
+  maxDepth?:       number;
+  detectRepeats?:  boolean;
+  children:        ReactNode;
+}
+export declare const SkeletonProvider: FC<SkeletonProviderProps>;
+
+/* ── AutoSkeleton ── */
 export interface AutoSkeletonProps {
-  /** Show skeleton when true, render real children when false */
+  /** Show skeleton when true */
   loading: boolean;
   children: ReactNode;
-  /** Animation style. Default: 'shimmer' */
+  animation?:      SkeletonAnimation;
+  theme?:          SkeletonThemePreset;
+  themeOverrides?: SkeletonThemeOverrides;
+  /** Number of skeleton copies (for lists) */
+  count?:          number;
+  /** Gap between count copies */
+  gap?:            string;
+  /** Animate real content appearing with fade-in */
+  fadeIn?:         boolean;
+  /** Custom ARIA label */
+  ariaLabel?:      string;
+  /** Fired once when loading transitions to false */
+  onLoaded?:       () => void;
+  /** Render prop: full manual skeleton override */
+  renderSkeleton?: (opts: { animation: SkeletonAnimation }) => ReactNode;
+  /** Max recursion depth for analyzer */
+  maxDepth?:       number;
+  detectRepeats?:  boolean;
+  className?:      string;
+  style?:          CSSProperties;
+}
+export declare const AutoSkeleton: FC<AutoSkeletonProps>;
+
+/* ── Primitives ── */
+export interface SkeletonBlockProps {
+  width?:     string | number;
+  height?:    string | number;
+  shape?:     'circle' | 'pill' | 'rounded';
   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;
+  style?:     CSSProperties;
+}
+export declare const SkeletonBlock: FC<SkeletonBlockProps>;
+
+export interface SkeletonTextProps {
+  lines?:         number;
+  lineHeight?:    string;
+  gap?:           string;
+  lastLineWidth?: string;
+  animation?:     SkeletonAnimation;
+  style?:         CSSProperties;
+}
+export declare const SkeletonText: FC<SkeletonTextProps>;
+
+export interface SkeletonAvatarProps {
+  size?:      string | number;
+  animation?: SkeletonAnimation;
+  style?:     CSSProperties;
 }
+export declare const SkeletonAvatar: FC<SkeletonAvatarProps>;
 
-export type SkeletonItemType = 'text' | 'image' | 'avatar' | 'button' | 'input';
+export interface SkeletonImageProps {
+  height?:    string | number;
+  animation?: SkeletonAnimation;
+  style?:     CSSProperties;
+}
+export declare const SkeletonImage: FC<SkeletonImageProps>;
 
-export interface SkeletonItemProps {
-  type?: SkeletonItemType;
-  lines?: number;
-  width?: number | string;
-  height?: number | string;
-  /** For avatar type: shorthand for equal width and height */
-  size?: number;
+export declare const SkeletonBadge:  FC<{ width?: string; animation?: SkeletonAnimation; style?: CSSProperties }>;
+export declare const SkeletonButton: FC<{ width?: string; height?: string; animation?: SkeletonAnimation; style?: CSSProperties }>;
+export declare const SkeletonInput:  FC<{ height?: string; animation?: SkeletonAnimation; style?: CSSProperties }>;
+
+export interface SkeletonListProps {
+  count?:       number;
+  gap?:         string;
+  rowHeight?:   string;
+  animation?:   SkeletonAnimation;
+  renderItem?:  (opts: { animation: SkeletonAnimation; index: number }) => ReactNode;
+}
+export declare const SkeletonList: FC<SkeletonListProps>;
+
+export interface SkeletonFormProps {
+  fields?:    number;
   animation?: SkeletonAnimation;
-  theme?: SkeletonTheme;
-  style?: CSSProperties;
+  style?:     CSSProperties;
+}
+export declare const SkeletonForm: FC<SkeletonFormProps>;
+
+export interface SkeletonCardProps {
+  image?:       boolean;
+  avatar?:      boolean;
+  footer?:      boolean;
+  lines?:       number;
+  imageHeight?: string;
+  animation?:   SkeletonAnimation;
+  style?:       CSSProperties;
 }
+export declare const SkeletonCard: FC<SkeletonCardProps>;
 
-/** Main wrapper component — auto-generates a skeleton from its children */
-export const AutoSkeleton: FC<AutoSkeletonProps>;
+/* ── Hooks ── */
+export interface UseSkeletonReturn {
+  loading:       boolean;
+  setLoading:    (v: boolean) => void;
+  skeletonProps: { loading: boolean } & Partial<AutoSkeletonProps>;
+}
+export declare function useSkeleton(initialLoading?: boolean, options?: Partial<AutoSkeletonProps>): UseSkeletonReturn;
+
+/** Prevents flash of skeleton for fast responses (< delay ms). */
+export declare function useSkeletonDelay(loading: boolean, delay?: number): boolean;
+
+/** Keeps skeleton visible for at least minDuration ms. */
+export declare function useSkeletonTimeout(loading: boolean, minDuration?: number): boolean;
+
+export interface UseSkeletonDataReturn<T> {
+  data:    T | null;
+  loading: boolean;
+  error:   Error | null;
+}
+export declare function useSkeletonData<T>(fetchFn: () => Promise<T>, deps?: unknown[]): UseSkeletonDataReturn<T>;
 
-/** Primitive building block for manually-crafted skeletons */
-export const SkeletonItem: FC<SkeletonItemProps>;
+export declare function withSkeleton<P extends object>(
+  Component: ComponentType<P>,
+  defaultOptions?: Partial<AutoSkeletonProps>
+): FC<P & { loading?: boolean; skeletonAnimation?: SkeletonAnimation; skeletonTheme?: SkeletonThemePreset; skeletonCount?: number }>;
 
-/** Inject global CSS (called automatically; export for SSR use) */
-export function injectStyles(): void;
+/* ── Low-level / Advanced ── */
+export declare function analyzeElement(element: ReactNode, depth?: number, opts?: object): object | null;
+export declare function renderNode(descriptor: object | null, options?: object): ReactNode;
+export declare function injectStyles(): void;
+export declare function clearCache(): void;
 
-export default AutoSkeleton;
+export declare const THEMES: Record<SkeletonThemePreset, Record<string, string>>;

package/src/index.js

@@ -1,102 +1,52 @@
-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 };
+'use strict';
+
+/**
+ * auto-loading-skeleton v2
+ * Main entry point.
+ */
+
+var AutoSkeleton   = require('./AutoSkeleton');
+var primitives     = require('./primitives');
+var hooks          = require('./hooks');
+var context        = require('./context');
+var analyzer       = require('./analyzer');
+var renderer       = require('./renderer');
+var styles         = require('./styles');
+var cache          = require('./cache');
+
+module.exports = {
+  // Main component
+  AutoSkeleton,
+
+  // Provider
+  SkeletonProvider:  context.SkeletonProvider,
+  SkeletonContext:   context.SkeletonContext,
+
+  // Primitives
+  SkeletonBlock:   primitives.SkeletonBlock,
+  SkeletonText:    primitives.SkeletonText,
+  SkeletonAvatar:  primitives.SkeletonAvatar,
+  SkeletonImage:   primitives.SkeletonImage,
+  SkeletonBadge:   primitives.SkeletonBadge,
+  SkeletonButton:  primitives.SkeletonButton,
+  SkeletonInput:   primitives.SkeletonInput,
+  SkeletonList:    primitives.SkeletonList,
+  SkeletonForm:    primitives.SkeletonForm,
+  SkeletonCard:    primitives.SkeletonCard,
+
+  // Hooks
+  useSkeleton:        hooks.useSkeleton,
+  useSkeletonDelay:   hooks.useSkeletonDelay,
+  useSkeletonTimeout: hooks.useSkeletonTimeout,
+  useSkeletonData:    hooks.useSkeletonData,
+  withSkeleton:       hooks.withSkeleton,
+
+  // Low-level (for advanced use)
+  analyzeElement: analyzer.analyzeElement,
+  renderNode:     renderer.renderNode,
+  injectStyles:   styles.injectStyles,
+  clearCache:     cache.clear,
+
+  // Theme presets reference
+  THEMES: styles.THEMES,
+};