shimmer-trace 1.1.0

package/dist/index.mjs

@@ -0,0 +1,590 @@
+import React2, { createContext, useContext, useId, useMemo, useRef, useState, useCallback, createElement, useLayoutEffect } from 'react';
+import { jsx, jsxs } from 'react/jsx-runtime';
+
+// src/Shimmer.tsx
+
+// src/types.ts
+var DEFAULTS = {
+  animation: "wave",
+  baseColor: "#e0e0e0",
+  highlightColor: "#f5f5f5",
+  speed: 1.5,
+  borderRadius: "",
+  preserveBackground: true
+};
+var ShimmerContext = createContext(null);
+function useShimmerContext() {
+  return useContext(ShimmerContext);
+}
+var IsShimmeringContext = createContext(false);
+function useIsShimmering() {
+  return useContext(IsShimmeringContext);
+}
+function getBlockStyles(animation, baseColor, highlightColor, speed, rect) {
+  const base = {
+    position: "absolute",
+    top: rect.y,
+    left: rect.x,
+    width: rect.width,
+    height: rect.height,
+    borderRadius: rect.borderRadius,
+    overflow: "hidden"
+  };
+  switch (animation) {
+    case "wave":
+    case "shine":
+      return { ...base, background: baseColor };
+    case "pulse":
+      return {
+        ...base,
+        background: baseColor,
+        animation: `shimmer-pulse ${speed}s ease-in-out infinite`
+      };
+    case "glow":
+      return {
+        ...base,
+        background: baseColor,
+        animation: `shimmer-glow ${speed}s ease-in-out infinite`
+      };
+    case "gradient":
+      return {
+        ...base,
+        backgroundImage: `linear-gradient(90deg, ${baseColor}, ${highlightColor}, ${baseColor})`,
+        backgroundSize: "200% 100%",
+        animation: `shimmer-gradient ${speed * 1.5}s ease-in-out infinite`
+      };
+  }
+}
+var SweepLayer = ({ rect, highlightColor, speed, containerWidth, variant }) => {
+  const isShine = variant === "shine";
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      style: {
+        position: "absolute",
+        top: 0,
+        left: -rect.x,
+        width: containerWidth > 0 ? containerWidth : "100vw",
+        height: "100%",
+        background: isShine ? `linear-gradient(115deg, transparent 30%, ${highlightColor} 50%, transparent 70%)` : `linear-gradient(90deg, transparent 0%, ${highlightColor} 50%, transparent 100%)`,
+        animation: `${isShine ? "shimmer-shine" : "shimmer-wave"} ${speed}s ease-in-out infinite`
+      }
+    }
+  );
+};
+var ShimmerOverlay = ({
+  rects,
+  animation,
+  baseColor,
+  highlightColor,
+  speed
+}) => {
+  const overlayRef = React2.useRef(null);
+  const [containerWidth, setContainerWidth] = React2.useState(0);
+  React2.useLayoutEffect(() => {
+    if (!overlayRef.current?.parentElement) return;
+    setContainerWidth(overlayRef.current.parentElement.offsetWidth);
+  }, [rects]);
+  if (rects.length === 0) return null;
+  const isSweep = animation === "wave" || animation === "shine";
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      ref: overlayRef,
+      role: "status",
+      "aria-busy": "true",
+      "aria-label": "Loading content",
+      "data-shimmer-ignore": "true",
+      style: {
+        position: "absolute",
+        top: 0,
+        left: 0,
+        width: "100%",
+        height: "100%",
+        zIndex: 1,
+        pointerEvents: "none",
+        visibility: "visible"
+      },
+      children: rects.map((rect, i) => /* @__PURE__ */ jsx(
+        "div",
+        {
+          style: getBlockStyles(animation, baseColor, highlightColor, speed, rect),
+          children: isSweep && /* @__PURE__ */ jsx(
+            SweepLayer,
+            {
+              rect,
+              highlightColor,
+              speed,
+              containerWidth,
+              variant: animation
+            }
+          )
+        },
+        i
+      ))
+    }
+  );
+};
+
+// src/utils.ts
+var counter = 0;
+function generateShimmerKey(prefix = "shimmer") {
+  return `${prefix}-clone-${++counter}`;
+}
+var FALLBACK_DIMENSIONS = {
+  INPUT: { width: 200, height: 36 },
+  BUTTON: { width: 120, height: 36 },
+  TEXTAREA: { width: 300, height: 80 },
+  SELECT: { width: 200, height: 36 },
+  IMG: { width: 100, height: 100 },
+  H1: { width: 300, height: 36 },
+  H2: { width: 260, height: 30 },
+  H3: { width: 220, height: 26 },
+  H4: { width: 200, height: 22 },
+  H5: { width: 180, height: 20 },
+  H6: { width: 160, height: 18 },
+  P: { width: 250, height: 16 },
+  SPAN: { width: 100, height: 16 }
+};
+
+// src/useTrace.ts
+var TRACEABLE_TAGS = /* @__PURE__ */ new Set([
+  // Text
+  "H1",
+  "H2",
+  "H3",
+  "H4",
+  "H5",
+  "H6",
+  "P",
+  "SPAN",
+  "A",
+  "LI",
+  "LABEL",
+  "TD",
+  "TH",
+  "BLOCKQUOTE",
+  "CODE",
+  "PRE",
+  // Media
+  "IMG",
+  "VIDEO",
+  "SVG",
+  "CANVAS",
+  "PICTURE",
+  // Form
+  "INPUT",
+  "TEXTAREA",
+  "SELECT",
+  "BUTTON",
+  // Misc
+  "HR"
+]);
+function isTraceable(el) {
+  if (el.hasAttribute("data-shimmer-ignore")) return false;
+  if (el.hasAttribute("data-shimmer")) return true;
+  if (TRACEABLE_TAGS.has(el.tagName)) return true;
+  if (el.children.length === 0) {
+    const rect = el.getBoundingClientRect();
+    return rect.width > 0 && rect.height > 0;
+  }
+  return false;
+}
+function collectTraceableElements(root) {
+  const result = [];
+  function walk(el) {
+    if (el.hasAttribute("data-shimmer-ignore")) return;
+    if (el.hasAttribute("data-shimmer-reporter")) return;
+    if (isTraceable(el)) {
+      result.push(el);
+      return;
+    }
+    for (let i = 0; i < el.children.length; i++) {
+      walk(el.children[i]);
+    }
+  }
+  for (let i = 0; i < root.children.length; i++) {
+    walk(root.children[i]);
+  }
+  return result;
+}
+function measureElement(el, containerRect, globalBorderRadius) {
+  const elRect = el.getBoundingClientRect();
+  if (elRect.width === 0 && elRect.height === 0 && elRect.left === 0 && elRect.top === 0) {
+    return null;
+  }
+  const computedStyle = window.getComputedStyle(el);
+  let borderRadius = globalBorderRadius || computedStyle.borderRadius;
+  const isZero = !borderRadius || borderRadius === "none" || borderRadius.split(" ").every((v) => v === "0" || v === "0px" || v === "0%");
+  if (isZero) {
+    borderRadius = "4px";
+  }
+  let width = elRect.width;
+  let height = elRect.height;
+  if (width === 0 || height === 0) {
+    const fallback = FALLBACK_DIMENSIONS[el.tagName];
+    if (fallback) {
+      width = width || fallback.width;
+      height = height || fallback.height;
+    }
+  }
+  return {
+    x: elRect.left - containerRect.left,
+    y: elRect.top - containerRect.top,
+    width,
+    height,
+    borderRadius
+  };
+}
+function performTrace(container, globalBorderRadius, anchorRef) {
+  const anchor = anchorRef?.current ?? container;
+  const anchorRect = anchor.getBoundingClientRect();
+  const elements = collectTraceableElements(container);
+  return elements.map((el) => measureElement(el, anchorRect, globalBorderRadius)).filter((r) => r !== null && r.width > 0 && r.height > 0);
+}
+function useTrace(containerRef, loading, globalBorderRadius, anchorRef) {
+  const [rects, setRects] = useState([]);
+  const trace = useCallback(() => {
+    if (!containerRef.current) return;
+    const traced = performTrace(containerRef.current, globalBorderRadius, anchorRef);
+    setRects(traced);
+  }, [containerRef, globalBorderRadius, anchorRef]);
+  useLayoutEffect(() => {
+    if (!loading || !containerRef.current) {
+      setRects([]);
+      return;
+    }
+    trace();
+    const observer = new ResizeObserver(() => {
+      trace();
+    });
+    observer.observe(containerRef.current);
+    return () => observer.disconnect();
+  }, [loading, trace]);
+  return rects;
+}
+
+// src/styles.ts
+var SHIMMER_STYLES_ID = "shimmer-trace-styles";
+var CSS = `
+@keyframes shimmer-wave {
+  0% { transform: translateX(-100%); }
+  100% { transform: translateX(100%); }
+}
+
+@keyframes shimmer-pulse {
+  0%, 100% { opacity: 0.4; }
+  50% { opacity: 1; }
+}
+
+@keyframes shimmer-shine {
+  0% { transform: translateX(-150%) skewX(-20deg); }
+  100% { transform: translateX(150%) skewX(-20deg); }
+}
+
+@keyframes shimmer-glow {
+  0%, 100% { filter: brightness(1); }
+  50% { filter: brightness(1.35); }
+}
+
+@keyframes shimmer-gradient {
+  0% { background-position: 0% 50%; }
+  50% { background-position: 100% 50%; }
+  100% { background-position: 0% 50%; }
+}
+
+/* preserveBackground mode: hide text + media but keep container styles */
+[data-shimmer-master][data-shimmer-preserve-bg="true"] :is(h1,h2,h3,h4,h5,h6,p,span,a,li,label,td,th,blockquote,code,pre,strong,em,small) {
+  color: transparent !important;
+  text-shadow: none !important;
+}
+[data-shimmer-master][data-shimmer-preserve-bg="true"] :is(img,video,svg,canvas,picture) {
+  opacity: 0 !important;
+}
+[data-shimmer-master][data-shimmer-preserve-bg="true"] :is(input,textarea,select,button) {
+  color: transparent !important;
+  opacity: 0 !important;
+}
+[data-shimmer-master][data-shimmer-preserve-bg="true"] {
+  pointer-events: none !important;
+  user-select: none !important;
+}
+`;
+function injectStyles() {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(SHIMMER_STYLES_ID)) return;
+  const style = document.createElement("style");
+  style.id = SHIMMER_STYLES_ID;
+  style.textContent = CSS;
+  document.head.appendChild(style);
+}
+function Shimmer({
+  loading = false,
+  children,
+  dummyLength,
+  dummyData,
+  as,
+  stopPropagation = false,
+  animation,
+  baseColor,
+  highlightColor,
+  speed,
+  borderRadius,
+  preserveBackground,
+  className,
+  style
+}) {
+  const parentContext = useShimmerContext();
+  const isMaster = !parentContext || stopPropagation;
+  const id = useId();
+  const config = useMemo(
+    () => ({
+      animation: animation ?? parentContext?.config.animation ?? DEFAULTS.animation,
+      baseColor: baseColor ?? parentContext?.config.baseColor ?? DEFAULTS.baseColor,
+      highlightColor: highlightColor ?? parentContext?.config.highlightColor ?? DEFAULTS.highlightColor,
+      speed: speed ?? parentContext?.config.speed ?? DEFAULTS.speed,
+      borderRadius: borderRadius ?? parentContext?.config.borderRadius ?? DEFAULTS.borderRadius,
+      preserveBackground: preserveBackground ?? parentContext?.config.preserveBackground ?? DEFAULTS.preserveBackground
+    }),
+    [
+      animation,
+      baseColor,
+      highlightColor,
+      speed,
+      borderRadius,
+      preserveBackground,
+      parentContext?.config
+    ]
+  );
+  if (isMaster) {
+    return /* @__PURE__ */ jsx(
+      MasterShimmer,
+      {
+        id,
+        loading,
+        config,
+        dummyLength,
+        dummyData,
+        as,
+        className,
+        style,
+        children
+      }
+    );
+  }
+  return /* @__PURE__ */ jsx(
+    ReporterShimmer,
+    {
+      id,
+      parentContext,
+      config,
+      dummyLength,
+      dummyData,
+      as,
+      children
+    }
+  );
+}
+function MasterShimmer({
+  id,
+  loading,
+  config,
+  children,
+  dummyLength,
+  dummyData,
+  as,
+  className,
+  style
+}) {
+  const containerRef = useRef(null);
+  const [reporterRects, setReporterRects] = useState({});
+  const register = useCallback((rid, rects) => {
+    setReporterRects((prev) => ({ ...prev, [rid]: rects }));
+  }, []);
+  const unregister = useCallback((rid) => {
+    setReporterRects((prev) => {
+      const next = { ...prev };
+      delete next[rid];
+      return next;
+    });
+  }, []);
+  React2.useEffect(() => {
+    injectStyles();
+  }, []);
+  const tracedRects = useTrace(
+    containerRef,
+    loading,
+    config.borderRadius || void 0
+  );
+  const allRects = useMemo(() => {
+    const reported = Object.values(reporterRects).flat();
+    return [...tracedRects, ...reported];
+  }, [tracedRects, reporterRects]);
+  const renderedChildren = useSkeletonChildren({
+    loading,
+    children,
+    dummyLength,
+    dummyData,
+    as,
+    id
+  });
+  const contextValue = useMemo(
+    () => ({
+      register,
+      unregister,
+      masterRef: containerRef,
+      loading,
+      config
+    }),
+    [register, unregister, loading, config]
+  );
+  return /* @__PURE__ */ jsx(ShimmerContext.Provider, { value: contextValue, children: /* @__PURE__ */ jsxs(
+    "div",
+    {
+      ref: containerRef,
+      className,
+      style: {
+        position: "relative",
+        visibility: loading && !config.preserveBackground ? "hidden" : void 0,
+        ...style
+      },
+      "aria-hidden": loading || void 0,
+      "data-shimmer-master": true,
+      "data-shimmer-preserve-bg": loading && config.preserveBackground ? "true" : void 0,
+      children: [
+        renderedChildren,
+        loading && /* @__PURE__ */ jsx(
+          ShimmerOverlay,
+          {
+            rects: allRects,
+            animation: config.animation,
+            baseColor: config.baseColor,
+            highlightColor: config.highlightColor,
+            speed: config.speed
+          }
+        )
+      ]
+    }
+  ) });
+}
+function ReporterShimmer({
+  id,
+  parentContext,
+  config,
+  children,
+  dummyLength,
+  dummyData,
+  as
+}) {
+  const containerRef = useRef(null);
+  const tracedRects = useTrace(
+    containerRef,
+    parentContext.loading,
+    config.borderRadius || void 0,
+    parentContext.masterRef
+  );
+  React2.useLayoutEffect(() => {
+    if (!parentContext.loading || tracedRects.length === 0) {
+      parentContext.unregister(id);
+      return;
+    }
+    parentContext.register(id, tracedRects);
+    return () => {
+      parentContext.unregister(id);
+    };
+  }, [tracedRects, parentContext, id]);
+  const renderedChildren = useSkeletonChildren({
+    loading: parentContext.loading,
+    children,
+    dummyLength,
+    dummyData,
+    as,
+    id
+  });
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      ref: containerRef,
+      "data-shimmer-reporter": true,
+      style: { display: "contents" },
+      children: renderedChildren
+    }
+  );
+}
+function useSkeletonChildren({
+  loading,
+  children,
+  dummyLength,
+  dummyData,
+  as,
+  id
+}) {
+  if (!loading) return children;
+  if (as) {
+    const count = dummyLength && dummyLength > 0 ? dummyLength : 1;
+    const Component = as;
+    return Array.from({ length: count }, (_, i) => /* @__PURE__ */ createElement(
+      Component,
+      {
+        ...dummyData || {},
+        key: generateShimmerKey(`${id}-as-${i}`)
+      }
+    ));
+  }
+  const childArray = React2.Children.toArray(children);
+  const templated = childArray.map((c, i) => {
+    if (!React2.isValidElement(c)) return c;
+    const key = generateShimmerKey(`${id}-tpl-${i}`);
+    const props = dummyData ? { ...dummyData, key } : { key };
+    return React2.cloneElement(c, props);
+  });
+  if (dummyLength && dummyLength > 0) {
+    const first = templated.find((c) => React2.isValidElement(c));
+    if (!first) return null;
+    return Array.from(
+      { length: dummyLength },
+      (_, i) => React2.cloneElement(first, {
+        key: generateShimmerKey(`${id}-clone-${i}`)
+      })
+    );
+  }
+  return templated;
+}
+function createShimmer(config = {}) {
+  const mergedConfig = {
+    animation: config.animation ?? DEFAULTS.animation,
+    baseColor: config.baseColor ?? DEFAULTS.baseColor,
+    highlightColor: config.highlightColor ?? DEFAULTS.highlightColor,
+    speed: config.speed ?? DEFAULTS.speed,
+    borderRadius: config.borderRadius ?? DEFAULTS.borderRadius,
+    preserveBackground: config.preserveBackground ?? DEFAULTS.preserveBackground
+  };
+  function ConfiguredShimmer(props) {
+    return /* @__PURE__ */ jsx(
+      Shimmer,
+      {
+        ...mergedConfig,
+        ...props
+      }
+    );
+  }
+  return ConfiguredShimmer;
+}
+function ShimmerSuspense({
+  children,
+  template,
+  ...shimmerConfig
+}) {
+  const skeletonContent = template !== void 0 ? template : /* @__PURE__ */ jsx(IsShimmeringContext.Provider, { value: true, children });
+  return /* @__PURE__ */ jsx(
+    React2.Suspense,
+    {
+      fallback: /* @__PURE__ */ jsx(Shimmer, { loading: true, ...shimmerConfig, children: skeletonContent }),
+      children
+    }
+  );
+}
+
+export { Shimmer, ShimmerContext, ShimmerSuspense, createShimmer, useIsShimmering, useShimmerContext };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map