shimmer-trace 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,224 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React from 'react';
+import React__default, { ReactNode, RefObject } from 'react';
+
+/**
+ * Represents a measured rectangle of a traced DOM element,
+ * positioned relative to the Master Shimmer container.
+ */
+interface ShimmerRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    borderRadius: string;
+}
+/** Available animation types for the shimmer effect. */
+type AnimationType = 'wave' | 'pulse' | 'shine' | 'glow' | 'gradient';
+/** Configuration options for the shimmer effect (all optional). */
+interface ShimmerConfig {
+    /** Animation style. Defaults to 'wave'. */
+    animation?: AnimationType;
+    /** Base color of the shimmer blocks. Defaults to '#e0e0e0'. */
+    baseColor?: string;
+    /** Highlight color of the shimmer animation. Defaults to '#f5f5f5'. */
+    highlightColor?: string;
+    /** Animation duration in seconds. Defaults to 1.5. */
+    speed?: number;
+    /** Global border-radius override. If omitted, auto-detected from each element (defaults to 4px if detection is 0px). */
+    borderRadius?: string;
+    /**
+     * Keep container backgrounds, borders, and padding visible while loading.
+     * When `true` (default), only text and media leaves are hidden via
+     * `color:transparent` / `opacity:0` so card backgrounds, borders, and
+     * spacing remain visible underneath the shimmer overlay.
+     *
+     * Set `false` for legacy behavior (`visibility:hidden` on whole tree).
+     */
+    preserveBackground?: boolean;
+}
+/** Props for the Shimmer component. */
+interface ShimmerProps extends ShimmerConfig {
+    /** Whether the loading state is active. */
+    loading?: boolean;
+    /** The children to trace and render shimmer over. */
+    children: ReactNode;
+    /**
+     * Number of placeholder clones to generate for list-like loading states.
+     *
+     * When `loading=true` and `dummyLength` is set, Shimmer grabs the first
+     * available child (or a cached template from the last loaded render) and
+     * clones it `dummyLength` times to produce skeleton placeholders.
+     *
+     * When `loading=false`, children are rendered as-is.
+     */
+    dummyLength?: number;
+    /**
+     * Props injected into each child element while `loading=true` so the
+     * skeleton renders with realistic shape without requiring real data.
+     *
+     * Example:
+     * ```tsx
+     * <Shimmer
+     *   loading={loading}
+     *   dummyData={{ user: { name: 'Loading...', role: '...', avatar: '' } }}
+     * >
+     *   <UserCard user={user} />
+     * </Shimmer>
+     * ```
+     *
+     * While loading, each direct child is cloned with these props merged on top
+     * of its own props. Ignored when `loading=false`.
+     */
+    dummyData?: Record<string, any>;
+    /**
+     * Component used to auto-generate skeleton elements while `loading=true`.
+     *
+     * When set, Shimmer ignores `children` during loading and renders
+     * `dummyLength` (defaults to 1) instances of `<as {...dummyData} />`
+     * to derive shape. Real children render once `loading=false`.
+     *
+     * ```tsx
+     * <Shimmer
+     *   loading={loading}
+     *   as={MovieCard}
+     *   dummyData={{ movie: movieTemplate }}
+     *   dummyLength={10}
+     * >
+     *   {movies.map((m) => <MovieCard movie={m} key={m.id} />)}
+     * </Shimmer>
+     * ```
+     */
+    as?: React__default.ComponentType<any>;
+    /** Force this Shimmer to be a Master renderer even if nested inside another Shimmer. */
+    stopPropagation?: boolean;
+    /**
+     * className applied to the Master container div.
+     * Use to control layout (e.g. display:flex) without losing position:relative.
+     */
+    className?: string;
+    /**
+     * Inline styles merged into the Master container div.
+     * position:relative is always applied; everything else is overridable.
+     */
+    style?: React__default.CSSProperties;
+}
+
+/**
+ * The main Shimmer component.
+ *
+ * Auto-detects **Master** (no parent Shimmer) vs **Reporter** (nested).
+ * - Master: renders children hidden, traces DOM, paints overlay.
+ * - Reporter: measures own rects, reports to parent Master.
+ *
+ * ### Skeleton shape via `dummyData`
+ *
+ * Pass `dummyData` so children render with realistic data while loading.
+ * No render-prop, no manual `data || fallback` in JSX.
+ *
+ * ```tsx
+ * const userTemplate = { name: 'Loading...', role: '...', avatar: '' };
+ *
+ * <Shimmer loading={loading} dummyData={{ user: userTemplate }}>
+ *   <UserCard user={user} />
+ * </Shimmer>
+ * ```
+ *
+ * ### List mode (`dummyLength`)
+ *
+ * Combined with `dummyData`, clones the first child N times with
+ * template props merged in:
+ *
+ * ```tsx
+ * <Shimmer
+ *   loading={loading}
+ *   dummyLength={5}
+ *   dummyData={{ fruit: { name: 'xxxxx', price: '$0.00' } }}
+ * >
+ *   <FruitCard fruit={undefined as any} />
+ * </Shimmer>
+ * ```
+ */
+declare function Shimmer({ loading, children, dummyLength, dummyData, as, stopPropagation, animation, baseColor, highlightColor, speed, borderRadius, preserveBackground, className, style, }: ShimmerProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Factory function to create a pre-configured Shimmer component.
+ * Avoids "Provider Hell" by baking config into the returned component.
+ *
+ * All config properties are optional — defaults are used for anything
+ * not specified.
+ *
+ * @example
+ * ```tsx
+ * const AppShimmer = createShimmer({
+ *   animation: 'pulse',
+ *   baseColor: '#1a1a2e',
+ *   highlightColor: '#16213e',
+ *   speed: 2,
+ * });
+ *
+ * <AppShimmer loading={isLoading}>
+ *   <MyComponent />
+ * </AppShimmer>
+ * ```
+ */
+declare function createShimmer(config?: ShimmerConfig): (props: Omit<ShimmerProps, keyof ShimmerConfig> & Partial<ShimmerConfig>) => react_jsx_runtime.JSX.Element;
+
+interface ShimmerContextValue {
+    register: (id: string, rects: ShimmerRect[]) => void;
+    unregister: (id: string) => void;
+    /** Ref object (not .current) so Reporters always read a fresh value. */
+    masterRef: RefObject<HTMLElement | null>;
+    loading: boolean;
+    config: Required<ShimmerConfig>;
+}
+declare const ShimmerContext: React.Context<ShimmerContextValue | null>;
+declare function useShimmerContext(): ShimmerContextValue | null;
+declare function useIsShimmering(): boolean;
+
+interface ShimmerSuspenseProps extends ShimmerConfig {
+    children: React__default.ReactNode;
+    /**
+     * Explicit skeleton template. Rendered hidden and traced for shimmer shape.
+     *
+     * Preferred — pass the same component with no data props:
+     * ```tsx
+     * <ShimmerSuspense template={<UserCard />}>
+     *   <UserCard />
+     * </ShimmerSuspense>
+     * ```
+     *
+     * If omitted, falls back to Option B: children are re-rendered with
+     * `useIsShimmering()=true` so they can return an empty shape themselves.
+     */
+    template?: React__default.ReactNode;
+}
+/**
+ * Suspense boundary that automatically shows a shimmer skeleton while
+ * children are suspended (e.g. useSuspenseQuery, use(promise), etc).
+ *
+ * **Option A — explicit template (preferred):**
+ * ```tsx
+ * <ShimmerSuspense template={<UserCard />}>
+ *   <UserCard />
+ * </ShimmerSuspense>
+ * ```
+ *
+ * **Option B — useIsShimmering hook (no template):**
+ * ```tsx
+ * function UserCard() {
+ *   const isShimmering = useIsShimmering();
+ *   const data = isShimmering ? null : useSuspenseQuery(...);
+ *   return <div><h3>{data?.name}</h3></div>;
+ * }
+ *
+ * <ShimmerSuspense>
+ *   <UserCard />
+ * </ShimmerSuspense>
+ * ```
+ * Components must use `useIsShimmering()` to skip data fetching in shimmer mode,
+ * otherwise they will also suspend inside the fallback (causing an empty skeleton).
+ */
+declare function ShimmerSuspense({ children, template, ...shimmerConfig }: ShimmerSuspenseProps): react_jsx_runtime.JSX.Element;
+
+export { type AnimationType, Shimmer, type ShimmerConfig, ShimmerContext, type ShimmerProps, type ShimmerRect, ShimmerSuspense, type ShimmerSuspenseProps, createShimmer, useIsShimmering, useShimmerContext };