smart-skeleton-loader 1.0.1 → 2.1.1

package/README.md

@@ -1,9 +1,9 @@
-# react-auto-skeleton
+# smart-skeleton-loader
 
 > **The smartest skeleton loader for React.**
 > Automatically generate perfectly matching skeletons by measuring your actual components.
 
-[![npm version](https://img.shields.io/npm/v/react-auto-skeleton.svg)](https://www.npmjs.com/package/react-auto-skeleton)
+[![npm version](https://img.shields.io/npm/v/smart-skeleton-loader.svg)](https://www.npmjs.com/package/smart-skeleton-loader)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-Donate-orange.svg?logo=buy-me-a-coffee&logoColor=white)](https://buymeacoffee.com/dashnyamkkq)
 
@@ -13,10 +13,10 @@
 
 </div>
 
-`react-auto-skeleton` eliminates the need to manually create and maintain skeleton versions of your components. It renders your actual component responsibly (hidden), measures its layout, and overlays precise skeletons for text, images, and containers.
+`smart-skeleton-loader` eliminates the need to manually create and maintain skeleton versions of your components. It renders your actual component responsibly (hidden), measures its layout, and overlays precise skeletons for text, images, and containers.
 
 > [!IMPORTANT]
-> **Enjoying this project?** If you find `react-auto-skeleton` useful, please consider [buying me a coffee](https://buymeacoffee.com/dashnyamkkq) to support further development! 💖
+> **Enjoying this project?** If you find `smart-skeleton-loader` useful, please consider [buying me a coffee](https://buymeacoffee.com/dashnyamkkq) to support further development! 💖
 
 ## ✨ Features
 
@@ -32,12 +32,12 @@
 ## 📦 Installation
 
 ```bash
-npm install react-auto-skeleton framer-motion
+npm install smart-skeleton-loader
 # or
-yarn add react-auto-skeleton framer-motion
+yarn add smart-skeleton-loader
 ```
 
-_Note: `framer-motion` is a peer dependency used for the smooth pulse animations._
+_Zero runtime dependencies — only `react` (19+) as a peer._
 
 ## 🚀 Usage
 
@@ -46,7 +46,7 @@ _Note: `framer-motion` is a peer dependency used for the smooth pulse animations
 Wrap your component in `AutoSkeleton` and control the `loading` state.
 
 ```tsx
-import { AutoSkeleton } from 'react-auto-skeleton';
+import { AutoSkeleton } from 'smart-skeleton-loader';
 
 const UserProfile = ({ loading, user }) => {
   return (
@@ -67,7 +67,7 @@ const UserProfile = ({ loading, user }) => {
 
 When fetching lists, you might start with an empty array. **How can we measure an empty array?**
 
-The solution is the **Template Pattern**: Render "dummy" items while loading. `react-auto-skeleton` will measure these dummies and create the skeleton layout.
+The solution is the **Template Pattern**: Render "dummy" items while loading. `smart-skeleton-loader` will measure these dummies and create the skeleton layout.
 
 ```tsx
 const UserList = () => {
@@ -95,7 +95,7 @@ const UserList = () => {
 
 ### 3. Container Detection (Cards)
 
-`react-auto-skeleton` intelligently distinguishes between **Content** and **Containers**.
+`smart-skeleton-loader` intelligently distinguishes between **Content** and **Containers**.
 
 - **Content** (Text, Images, Buttons) -> Renders as a **Pulsing Gray Box**.
 - **Containers** (Elements with visible `border`, `background-color`, or `box-shadow`) -> Renders as a **Static Clone** (with your exact styles) and **NO** pulse.
@@ -121,11 +121,16 @@ Customize the appearance via the `config` prop:
 
 ## 🧩 API Reference
 
-| Prop       | Type        | Default | Description                                         |
-| ---------- | ----------- | ------- | --------------------------------------------------- |
-| `loading`  | `boolean`   | `true`  | Whether to show the skeleton or the actual content. |
-| `children` | `ReactNode` | -       | The content to measure.                             |
-| `config`   | `object`    | -       | Customization options.                              |
+| Prop           | Type            | Default      | Description                                                                    |
+| -------------- | --------------- | ------------ | ------------------------------------------------------------------------------ |
+| `loading`      | `boolean`       | `true`       | Whether to show the skeleton or the actual content.                            |
+| `children`     | `ReactNode`     | -            | The content to measure.                                                        |
+| `config`       | `object`        | -            | Customization options.                                                         |
+| `loadingLabel` | `string`        | `"Loading…"` | Text announced to screen readers while loading.                                |
+| `className`    | `string`        | -            | Class name for the outer wrapper.                                              |
+| `style`        | `CSSProperties` | -            | Style for the outer wrapper, merged over `position: relative; display: block`. |
+| `delay`        | `number`        | `0`          | Wait this long (ms) before showing the skeleton, so fast loads never flash it. |
+| `minDuration`  | `number`        | `0`          | Once shown, keep the skeleton at least this long (ms).                         |
 
 ### Config Object
 
@@ -139,13 +144,18 @@ Customize the appearance via the `config` prop:
 
 1.  **Invisible Measurement**: When `loading={true}`, your children are rendered in the DOM but hidden using `opacity: 0`. This allows them to take up space and be measured by the browser.
 2.  **Smart Scan**: We use a `TreeWalker` to scan the DOM elements.
-    - If it finds text/images -> It creates a **Primitive Skeleton**.
+    - If it finds text -> It creates **one bar per rendered line** (the last bar is as short as the last line).
+    - If it finds images/inputs/buttons -> It creates a **Primitive Skeleton**.
     - If it finds a styled container -> It creates a **Container Skeleton**.
-3.  **Overlay**: We render absolute positioned `divs` (using Framer Motion) exactly over the measured elements.
-4.  **No Shift**: Because the hidden content is already holding the space, when `loading` becomes `false`, we simply fade `opacity` to 1. No jumping content!
+3.  **Overlay**: We render absolute positioned `divs` exactly over the measured elements.
+4.  **No Shift**: Because the hidden content is already holding the space, when `loading` becomes `false`, the skeleton and content crossfade. No jumping content!
 
 ## ⚠️ Notes
 
+- **Accessibility:** while `loading`, the real content is `inert` (no clicks, no Tab focus, hidden from assistive tech), the wrapper has `aria-busy`, and `loadingLabel` is announced through a `role="status"` region.
+- **Avoiding flicker:** for most data fetching use `delay={150} minDuration={400}`: loads faster than 150ms show nothing, and a skeleton that does appear stays long enough to read as intentional. The skeleton and content crossfade over 200ms.
+- **Server rendering / Next.js:** the package is marked `'use client'`, so it can be imported from Server Components. Server-rendered HTML shows one pulsing block over the reserved space until hydration, then switches to measured skeletons.
+- **Layout:** the wrapper is `display: block`, so it fills its parent like the content it replaces. For inline content pass `style={{ display: 'inline-block' }}`.
 - **Placeholders**: For images, ensure you provide a `src` (even a placeholder) or explicit `width/height` style so the image takes up space to be measured.
 - **Opacity vs Visibility**: We use `opacity: 0` to hide content. This ensures that even elements that might behave strangely with `visibility: hidden` are correctly measured.
 

package/dist/index.cjs

@@ -1,75 +1,208 @@
-'use strict';
+'use client';
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-var react = require('react');
-var framerMotion = require('framer-motion');
-var jsxRuntime = require('react/jsx-runtime');
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AutoSkeleton: () => AutoSkeleton,
+  SkeletonPrimitive: () => SkeletonPrimitive
+});
+module.exports = __toCommonJS(index_exports);
 
 // src/AutoSkeleton.tsx
+var import_react2 = require("react");
+
+// src/measure.ts
+function groupRectsIntoLines(rects, tolerance = 2) {
+  const sorted = Array.from(rects).filter((r) => r.width > 0 && r.height > 0).sort((a, b) => a.top - b.top || a.left - b.left);
+  const lines = [];
+  for (const r of sorted) {
+    const line = lines[lines.length - 1];
+    if (line && Math.abs(r.top - line.top) <= tolerance) {
+      line.left = Math.min(line.left, r.left);
+      line.right = Math.max(line.right, r.left + r.width);
+      line.bottom = Math.max(line.bottom, r.top + r.height);
+    } else {
+      lines.push({
+        top: r.top,
+        left: r.left,
+        right: r.left + r.width,
+        bottom: r.top + r.height
+      });
+    }
+  }
+  return lines.map((l) => ({
+    top: l.top,
+    left: l.left,
+    width: l.right - l.left,
+    height: l.bottom - l.top
+  }));
+}
+function getTextLineBoxes(el) {
+  if (typeof document.createRange !== "function") return [];
+  const rects = [];
+  for (const node of Array.from(el.childNodes)) {
+    if (node.nodeType !== Node.TEXT_NODE || !node.textContent?.trim()) continue;
+    const range = document.createRange();
+    range.selectNodeContents(node);
+    if (typeof range.getClientRects !== "function") return [];
+    rects.push(...Array.from(range.getClientRects()));
+  }
+  return groupRectsIntoLines(rects);
+}
+
+// src/SkeletonPrimitive.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+var PULSE_CSS = `
+@keyframes auto-skeleton-pulse {
+  0%, 100% { background-color: var(--auto-skeleton-c); }
+  50% { background-color: var(--auto-skeleton-h); }
+}
+.auto-skeleton { animation: auto-skeleton-pulse 1.5s ease-in-out infinite; }
+@media (prefers-reduced-motion: reduce) {
+  .auto-skeleton { animation: none; }
+}
+`;
 var SkeletonPrimitive = ({
   width,
   height,
   borderRadius = "4px",
   color = "var(--auto-skeleton-color, #eee)",
   highlightColor = "var(--auto-skeleton-highlight, #f5f5f5)",
+  className,
   style,
   ...props
 }) => {
-  return /* @__PURE__ */ jsxRuntime.jsx(
-    framerMotion.motion.div,
-    {
-      style: {
-        width,
-        height,
-        borderRadius,
-        backgroundColor: color,
-        ...style
-      },
-      animate: {
-        backgroundColor: [color, highlightColor, color]
-      },
-      transition: {
-        duration: 1.5,
-        repeat: Infinity,
-        ease: "easeInOut"
-      },
-      "data-testid": "skeleton",
-      ...props
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, { children: [
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("style", { href: "auto-skeleton-pulse", precedence: "default", children: PULSE_CSS }),
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      "div",
+      {
+        className: className ? `auto-skeleton ${className}` : "auto-skeleton",
+        style: {
+          width,
+          height,
+          borderRadius,
+          backgroundColor: color,
+          "--auto-skeleton-c": color,
+          "--auto-skeleton-h": highlightColor,
+          ...style
+        },
+        "data-testid": "skeleton",
+        ...props
+      }
+    )
+  ] });
+};
+
+// src/useDisplayedLoading.ts
+var import_react = require("react");
+function useDisplayedLoading(loading, { delay = 0, minDuration = 0 } = {}) {
+  const [shown, setShown] = (0, import_react.useState)(() => loading && delay <= 0);
+  const shownAt = (0, import_react.useRef)(0);
+  (0, import_react.useLayoutEffect)(() => {
+    if (shown) shownAt.current = Date.now();
+  }, [shown]);
+  (0, import_react.useLayoutEffect)(() => {
+    if (loading === shown) return;
+    const wait = loading ? delay : Math.max(0, minDuration - (Date.now() - shownAt.current));
+    if (wait <= 0) {
+      setShown(loading);
+      return;
     }
-  );
+    const timer = setTimeout(() => setShown(loading), wait);
+    return () => clearTimeout(timer);
+  }, [loading, shown, delay, minDuration]);
+  return shown;
+}
+
+// src/AutoSkeleton.tsx
+var import_jsx_runtime2 = require("react/jsx-runtime");
+var TEXT_BAR_RATIO = 0.7;
+var FADE_MS = 200;
+var VISUALLY_HIDDEN = {
+  position: "absolute",
+  width: 1,
+  height: 1,
+  padding: 0,
+  margin: -1,
+  overflow: "hidden",
+  clip: "rect(0, 0, 0, 0)",
+  whiteSpace: "nowrap",
+  border: 0
 };
 var AutoSkeleton = ({
   loading,
   children,
+  loadingLabel = "Loading\u2026",
+  className,
+  style,
+  delay = 0,
+  minDuration = 0,
   config
 }) => {
   const theme = config?.theme || "auto";
-  const containerRef = react.useRef(null);
-  const [skeletons, setSkeletons] = react.useState([]);
+  const showSkeleton = useDisplayedLoading(loading, { delay, minDuration });
+  const busy = loading || showSkeleton;
+  const [revealed, setRevealed] = (0, import_react2.useState)(!busy);
+  if (!busy && !revealed) setRevealed(true);
+  const hidden = showSkeleton || loading && !revealed;
+  const [fadingOut, setFadingOut] = (0, import_react2.useState)(false);
+  const [prevShowSkeleton, setPrevShowSkeleton] = (0, import_react2.useState)(showSkeleton);
+  if (prevShowSkeleton !== showSkeleton) {
+    setPrevShowSkeleton(showSkeleton);
+    setFadingOut(!showSkeleton);
+  }
+  (0, import_react2.useEffect)(() => {
+    if (!fadingOut) return;
+    const timer = setTimeout(() => setFadingOut(false), FADE_MS);
+    return () => clearTimeout(timer);
+  }, [fadingOut]);
+  const containerRef = (0, import_react2.useRef)(null);
+  const [skeletons, setSkeletons] = (0, import_react2.useState)([]);
+  const [measured, setMeasured] = (0, import_react2.useState)(false);
   const updateSkeletons = () => {
     if (!containerRef.current) return;
     const containerRect = containerRef.current.getBoundingClientRect();
     const newSkeletons = [];
     const getSkeletonType = (el) => {
       const tagName = el.tagName.toLowerCase();
-      const style = window.getComputedStyle(el);
+      const style2 = window.getComputedStyle(el);
       if (["img", "input", "button", "textarea", "select"].includes(tagName)) {
         return { type: "primitive" };
       }
       const hasText = Array.from(el.childNodes).some(
         (n) => n.nodeType === Node.TEXT_NODE && n.textContent?.trim()
       );
-      if (hasText) return { type: "primitive" };
-      const hasBackground = style.backgroundColor !== "rgba(0, 0, 0, 0)" && style.backgroundColor !== "transparent";
-      const hasBorder = style.borderWidth !== "0px" && style.borderStyle !== "none" && style.borderColor !== "rgba(0, 0, 0, 0)" && style.borderColor !== "transparent";
-      const hasShadow = style.boxShadow !== "none";
+      if (hasText) return { type: "primitive", text: true };
+      const hasBackground = style2.backgroundColor !== "rgba(0, 0, 0, 0)" && style2.backgroundColor !== "transparent";
+      const hasBorder = style2.borderWidth !== "0px" && style2.borderStyle !== "none" && style2.borderColor !== "rgba(0, 0, 0, 0)" && style2.borderColor !== "transparent";
+      const hasShadow = style2.boxShadow !== "none";
       if (hasBackground || hasBorder || hasShadow) {
         return {
           type: "container",
           styles: {
-            backgroundColor: style.backgroundColor,
-            border: style.border,
-            borderRadius: style.borderRadius,
-            boxShadow: style.boxShadow
+            backgroundColor: style2.backgroundColor,
+            border: style2.border,
+            borderRadius: style2.borderRadius,
+            boxShadow: style2.boxShadow
           }
         };
       }
@@ -81,8 +214,8 @@ var AutoSkeleton = ({
       {
         acceptNode: (node2) => {
           const el = node2;
-          const style = window.getComputedStyle(el);
-          if (style.display === "none") return NodeFilter.FILTER_REJECT;
+          const style2 = window.getComputedStyle(el);
+          if (style2.display === "none") return NodeFilter.FILTER_REJECT;
           if (getSkeletonType(el)) return NodeFilter.FILTER_ACCEPT;
           return NodeFilter.FILTER_SKIP;
         }
@@ -94,11 +227,26 @@ var AutoSkeleton = ({
       const el = node;
       const rect = el.getBoundingClientRect();
       const typeData = getSkeletonType(el);
-      if (typeData) {
+      const lines = typeData?.text ? getTextLineBoxes(el) : [];
+      if (lines.length > 0) {
+        for (const line of lines) {
+          const height = Math.max(4, line.height * TEXT_BAR_RATIO);
+          newSkeletons.push({
+            key: `${idx++}`,
+            type: "primitive",
+            width: line.width,
+            height,
+            top: line.top + (line.height - height) / 2 - containerRect.top,
+            left: line.left - containerRect.left,
+            borderRadius: typeof config?.borderRadius === "number" ? `${config.borderRadius}px` : config?.borderRadius ?? "4px"
+          });
+        }
+      } else if (typeData) {
         let borderRadius = config?.borderRadius || typeData.styles?.borderRadius || window.getComputedStyle(el).borderRadius;
         if (typeData.type === "primitive") {
           if (borderRadius === "0px" || !borderRadius) {
-            if (window.getComputedStyle(el).borderRadius === "50%" || rect.width === rect.height && rect.width < 50) ;
+            if (window.getComputedStyle(el).borderRadius === "50%" || rect.width === rect.height && rect.width < 50) {
+            }
             borderRadius = "4px";
             if (el.tagName.toLowerCase() === "button") borderRadius = "6px";
             if (el.tagName.toLowerCase() === "img") borderRadius = "4px";
@@ -129,8 +277,9 @@ var AutoSkeleton = ({
       });
     }
     setSkeletons(newSkeletons);
+    setMeasured(true);
   };
-  react.useEffect(() => {
+  (0, import_react2.useLayoutEffect)(() => {
     if (!containerRef.current) return;
     updateSkeletons();
     const observer = new ResizeObserver(() => {
@@ -147,7 +296,7 @@ var AutoSkeleton = ({
       observer.disconnect();
       mutationObserver.disconnect();
     };
-  }, [loading, children]);
+  }, [showSkeleton, children]);
   const getEffectiveColors = () => {
     if (config?.color || config?.highlightColor) {
       return {
@@ -170,78 +319,99 @@ var AutoSkeleton = ({
     return { color: void 0, highlightColor: void 0 };
   };
   const effectiveColors = getEffectiveColors();
-  return /* @__PURE__ */ jsxRuntime.jsxs(
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(
     "div",
     {
-      style: { position: "relative", display: "inline-block", width: "auto" },
+      className,
+      style: { position: "relative", display: "block", ...style },
       ...theme !== "auto" ? { "data-skeleton-theme": theme } : {},
+      "aria-busy": busy,
       children: [
-        /* @__PURE__ */ jsxRuntime.jsx(
+        /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { role: "status", style: VISUALLY_HIDDEN, children: busy ? loadingLabel : "" }),
+        /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
           "div",
           {
             ref: containerRef,
             style: {
-              opacity: loading ? 0 : 1,
-              transition: "opacity 0.2s ease"
-              // Smooth transition when loading finishes
+              opacity: hidden ? 0 : 1,
+              // Hide instantly (no ghost content under the bars); fade only on reveal
+              transition: hidden ? "none" : `opacity ${FADE_MS}ms ease`
             },
-            "aria-hidden": loading,
+            "aria-hidden": hidden,
+            inert: busy,
             children
           }
         ),
-        loading && /* @__PURE__ */ jsxRuntime.jsx(
+        (showSkeleton || fadingOut) && /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(
           "div",
           {
+            "data-testid": "skeleton-overlay",
             style: {
               position: "absolute",
               top: 0,
               left: 0,
               width: "100%",
               height: "100%",
-              pointerEvents: "none"
+              pointerEvents: "none",
+              opacity: showSkeleton ? 1 : 0,
+              transition: `opacity ${FADE_MS}ms ease`
             },
-            children: skeletons.map((sk) => /* @__PURE__ */ jsxRuntime.jsx(
-              "div",
-              {
-                style: { position: "absolute", top: sk.top, left: sk.left },
-                children: sk.type === "primitive" ? /* @__PURE__ */ jsxRuntime.jsx(
-                  SkeletonPrimitive,
-                  {
-                    width: sk.width,
-                    height: sk.height,
-                    borderRadius: sk.borderRadius,
-                    color: effectiveColors.color,
-                    highlightColor: effectiveColors.highlightColor
-                  }
-                ) : (
-                  /* Container Clone: Renders static style */
-                  /* @__PURE__ */ jsxRuntime.jsx(
-                    "div",
+            children: [
+              !measured && // Server render / before hydration: nothing can be measured yet, so
+              // cover the reserved space with one block instead of showing nothing
+              /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+                SkeletonPrimitive,
+                {
+                  width: "100%",
+                  height: "100%",
+                  color: effectiveColors.color,
+                  highlightColor: effectiveColors.highlightColor
+                }
+              ),
+              skeletons.map((sk) => /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+                "div",
+                {
+                  style: { position: "absolute", top: sk.top, left: sk.left },
+                  children: sk.type === "primitive" ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+                    SkeletonPrimitive,
                     {
-                      style: {
-                        width: sk.width,
-                        height: sk.height,
-                        borderRadius: sk.borderRadius,
-                        ...sk.style,
-                        // Apply captured container styles
-                        // Ensure it doesn't hide children if z-index issues arise,
-                        // but since we render in DOM order, children come later and sit on top.
-                        boxSizing: "border-box"
-                      }
+                      width: sk.width,
+                      height: sk.height,
+                      borderRadius: sk.borderRadius,
+                      color: effectiveColors.color,
+                      highlightColor: effectiveColors.highlightColor
                     }
+                  ) : (
+                    /* Container Clone: Renders static style */
+                    /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+                      "div",
+                      {
+                        style: {
+                          width: sk.width,
+                          height: sk.height,
+                          borderRadius: sk.borderRadius,
+                          ...sk.style,
+                          // Apply captured container styles
+                          // Ensure it doesn't hide children if z-index issues arise,
+                          // but since we render in DOM order, children come later and sit on top.
+                          boxSizing: "border-box"
+                        }
+                      }
+                    )
                   )
-                )
-              },
-              sk.key
-            ))
+                },
+                sk.key
+              ))
+            ]
           }
         )
       ]
     }
   );
 };
-
-exports.AutoSkeleton = AutoSkeleton;
-exports.SkeletonPrimitive = SkeletonPrimitive;
-//# sourceMappingURL=index.cjs.map
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AutoSkeleton,
+  SkeletonPrimitive
+});
 //# sourceMappingURL=index.cjs.map