skeleton-ghost-loader 1.0.0

package/README.md

@@ -0,0 +1,29 @@
+# skeletonloader
+
+A **Tailwind CSS–based, structure-preserving skeleton loader for React**.
+
+`skeletonloader` automatically converts your existing JSX into skeleton placeholders **while keeping the exact layout and styling**, by reusing the same `className` (Tailwind utilities).
+
+✅ No DOM measurement  
+✅ No layout shift  
+✅ SSR / Next.js safe  
+✅ Zero config  
+✅ Tailwind-native  
+
+---
+
+## ✨ Features
+
+- 🧱 **Preserves structure** – DOM tree stays the same
+- 🎨 **Uses Tailwind classes** – width, height, radius come from `className`
+- 🌗 **Dark mode support** – works with `dark:` utilities
+- ⏸ **Disable animation** – optional pulse control
+- ⛔ **Skip skeleton** – exclude specific components
+- ⚡ **Lightweight** – no extra dependencies
+
+---
+
+## 📦 Installation
+
+```bash
+npm install skeletonloader

package/index.js

@@ -0,0 +1 @@
+export { default } from "./src";

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "skeleton-ghost-loader",
+  "version": "1.0.0",
+  "description": "Tailwind-based structure preserving skeleton loader for React",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "src"
+  ],
+  "keywords": [
+    "react",
+    "skeleton",
+    "tailwind",
+    "loader",
+    "ui"
+  ],
+  "license": "ISC",
+  "peerDependencies": {
+    "react": ">=16.8",
+    "react-dom": ">=16.8"
+  }
+}

package/src/components/Skeleton.jsx

@@ -0,0 +1,18 @@
+import React from "react";
+import { replaceWithSkeleton } from "../utils/replaceWithSkeleton";
+import Skip from "./Skip";
+
+const Skeleton = ({ loading, children, pulse = true }) => {
+  if (!loading) return children;
+
+  return (
+    <>
+      {replaceWithSkeleton(children, { pulse })}
+    </>
+  );
+};
+
+
+Skeleton.Skip = Skip;
+
+export default Skeleton;

package/src/components/SkeletonItem.jsx

@@ -0,0 +1,17 @@
+import React from "react";
+
+const SkeletonItem = ({ className = "", pulse }) => {
+  return (
+    <div
+      aria-hidden="true"
+      className={`
+        ${className}
+        bg-gray-200 dark:bg-gray-700
+        rounded
+        ${pulse ? "animate-pulse" : ""}
+      `}
+    />
+  );
+};
+
+export default SkeletonItem;

package/src/components/Skip.jsx

@@ -0,0 +1,7 @@
+const Skip = ({ children }) => {
+  return children;
+};
+
+Skip.displayName = "SkeletonSkip";
+
+export default Skip;

package/src/index.js

@@ -0,0 +1,3 @@
+import Skeleton from "./components/Skeleton";
+
+export default Skeleton;

package/src/utils/replaceWithSkeleton.js

@@ -0,0 +1,44 @@
+import React from "react";
+import SkeletonItem from "../components/SkeletonItem";
+
+export function replaceWithSkeleton(node, options) {
+  const { pulse } = options;
+
+  // Text node
+  if (typeof node === "string" || typeof node === "number") {
+    return (
+      <div
+        className={`h-4 w-full rounded bg-gray-200 dark:bg-gray-700 ${
+          pulse ? "animate-pulse" : ""
+        }`}
+      />
+    );
+  }
+
+  if (!React.isValidElement(node)) return node;
+
+  //  Skip skeleton
+  if (node.type?.displayName === "SkeletonSkip") {
+    return node.props.children;
+  }
+
+  const { className = "", children } = node.props;
+
+  // Leaf node
+  if (!children) {
+    return (
+      <SkeletonItem
+        className={className}
+        pulse={pulse}
+      />
+    );
+  }
+
+  // Container node
+  return React.cloneElement(node, {
+    className,
+    children: React.Children.map(children, (child) =>
+      replaceWithSkeleton(child, options)
+    ),
+  });
+}