react-ez-skeleton 1.0.0

package/README.md

@@ -0,0 +1,211 @@
+# react-ez-skeleton
+
+**Simple. Accessible. Zero-config React skeletons.**
+
+`react-ez-skeleton` is a lightweight React skeleton loader library focused on excellent developer experience (DX). It works out of the box, is SSR-safe, respects accessibility and motion preferences, and is easy to theme using CSS variables.
+
+No CSS imports. No heavy dependencies. No surprises.
+
+## Why react-ez-skeleton?
+
+- **Zero configuration**: works immediately
+- **SSR & hydration safe**: Next.js, Remix, etc.
+- **Accessible by default**: `aria-hidden`
+- **Reduced-motion friendly**: respects `prefers-reduced-motion`
+- **Themeable**: via CSS variables
+- **Test-friendly**: `dataTestId` -> `data-testid`
+- **Tiny API**: no lock-in
+
+## Installation
+
+```bash
+npm install react-ez-skeleton
+```
+
+or
+
+```bash
+yarn add react-ez-skeleton
+```
+
+## Quick Start
+
+```tsx
+import { Skeleton } from "react-ez-skeleton";
+
+export function CardLoading() {
+  return <Skeleton width={200} height={20} />;
+}
+```
+
+That’s it.
+
+- No CSS imports
+- No providers
+- No setup
+
+## Components
+
+### `Skeleton`
+
+The base building block.
+
+```tsx
+<Skeleton width={120} height={16} />
+<Skeleton width="100%" height={24} radius={8} />
+```
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `width` | `number \| string` | `"100%"` | Width (px, %, etc.) |
+| `height` | `number \| string` | `16` | Height |
+| `radius` | `number \| string` | `4` | Border radius |
+| `animate` | `boolean` | `true` | Enable shimmer animation |
+| `respectReducedMotion` | `boolean` | `true` | Respects OS motion settings |
+| `ariaHidden` | `boolean` | `true` | Decorative by default |
+| `injectStyles` | `boolean` | `true` | Auto-inject required styles |
+| `dataTestId` | `string` | `—` | Adds `data-testid` |
+| `className` | `string` | `—` | Custom class |
+| `style` | `React.CSSProperties` | `—` | Inline styles |
+
+### `SkeletonText`
+
+Perfect for paragraphs and content blocks.
+
+```tsx
+<SkeletonText lines={3} />
+```
+
+Advanced usage:
+
+```tsx
+<SkeletonText
+  lines={4}
+  randomizeLineWidths
+  randomizeMin={60}
+  randomizeMax={95}
+  dataTestId="post-skeleton"
+/>
+```
+
+#### Props (in addition to `SkeletonProps`)
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `lines` | `number` | `3` |
+| `lineHeight` | `number \| string` | `16` |
+| `gap` | `number \| string` | `8` |
+| `lineWidths` | `(number \| string)[]` | `—` |
+| `randomizeLineWidths` | `boolean` | `false` |
+| `randomizeMin` | `number` | `60` |
+| `randomizeMax` | `number` | `100` |
+| `randomizeSeed` | `number` | `—` |
+
+Seeded randomness means deterministic layouts (nice for SSR and tests).
+
+### `SkeletonCircle`
+
+Ideal for avatars and icons.
+
+```tsx
+<SkeletonCircle size={40} />
+```
+
+## Theming (DX Highlight)
+
+No theme providers. No props explosion.
+
+Just CSS variables:
+
+```css
+:root {
+  --ez-skeleton-color-start: #2a2a2a;
+  --ez-skeleton-color-middle: #3a3a3a;
+  --ez-skeleton-color-end: #2a2a2a;
+}
+```
+
+Works automatically across your app.
+Perfect for dark mode and design systems.
+
+## Accessibility & Motion
+
+- Skeletons are decorative by default
+- Automatically hidden from screen readers
+- Honors `prefers-reduced-motion`
+
+```tsx
+<Skeleton animate={false} />
+```
+
+## Testing Support
+
+```tsx
+<Skeleton dataTestId="profile-loading" />
+
+expect(screen.getByTestId("profile-loading")).toBeInTheDocument();
+```
+
+`SkeletonText` automatically appends line indexes:
+
+- `profile-loading-0`
+- `profile-loading-1`
+
+## SSR & Framework Support
+
+Fully safe for:
+
+- Next.js (App Router & Pages)
+- Remix
+- Vite SSR
+- Astro
+- CRA
+
+Style injection is:
+
+- Singleton-based
+- Guarded
+- Client-only
+- No hydration mismatches
+
+## Opt-out Style Injection
+
+If you want full control:
+
+```tsx
+<Skeleton injectStyles={false} />
+```
+
+Then provide your own CSS:
+
+```css
+@keyframes react-ez-skeleton-pulse {
+  from {
+    background-position: 100% 50%;
+  }
+  to {
+    background-position: 0 50%;
+  }
+}
+```
+
+## Bundle Philosophy
+
+- No runtime dependencies
+- Tree-shakable
+- Side-effect safe
+- Dual ESM + CJS builds
+- TypeScript first
+
+## Contributing
+
+PRs and issues are welcome.
+Please keep changes DX-focused and minimal.
+
+## License
+
+MIT © Md. Shafiul Alam
+
+Final note: `react-ez-skeleton` is designed for developers who care about correctness, accessibility, and simplicity — without sacrificing control.

package/dist/index.cjs

@@ -0,0 +1,165 @@
+"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);
+
+// src/index.tsx
+var index_exports = {};
+__export(index_exports, {
+  Skeleton: () => Skeleton,
+  SkeletonCircle: () => SkeletonCircle,
+  SkeletonText: () => SkeletonText,
+  default: () => index_default,
+  injectSkeletonStyles: () => injectSkeletonStyles
+});
+module.exports = __toCommonJS(index_exports);
+var import_jsx_runtime = require("react/jsx-runtime");
+var stylesInjected = false;
+var toCssSize = (value) => {
+  if (value === void 0) return void 0;
+  if (typeof value === "number") return `${value}px`;
+  return value;
+};
+var Skeleton = ({
+  width = "100%",
+  height = 16,
+  radius = 4,
+  className = "",
+  style,
+  animate = true,
+  respectReducedMotion = true,
+  ariaHidden = true,
+  injectStyles = true,
+  dataTestId
+}) => {
+  if (injectStyles) injectSkeletonStyles();
+  const prefersReducedMotion = respectReducedMotion && typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  const inlineStyle = {
+    display: "inline-block",
+    background: "linear-gradient(90deg, var(--ez-skeleton-color-start, #f2f2f2) 25%, var(--ez-skeleton-color-middle, #e6e6e6) 37%, var(--ez-skeleton-color-end, #f2f2f2) 63%)",
+    backgroundSize: "400% 100%",
+    animation: animate && !prefersReducedMotion ? "var(--ez-skeleton-animation, react-ez-skeleton-pulse 1.4s ease-in-out infinite)" : "none",
+    borderRadius: toCssSize(radius),
+    width: toCssSize(width),
+    height: toCssSize(height),
+    ...style
+  };
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    "span",
+    {
+      className,
+      style: inlineStyle,
+      "aria-hidden": ariaHidden,
+      "data-testid": dataTestId
+    }
+  );
+};
+var injectSkeletonStyles = () => {
+  if (stylesInjected) return;
+  if (typeof document === "undefined") return;
+  const id = "react-ez-skeleton-keyframes";
+  if (document.getElementById(id)) {
+    stylesInjected = true;
+    return;
+  }
+  const style = document.createElement("style");
+  style.id = id;
+  style.innerHTML = `:root{--ez-skeleton-color-start:#f2f2f2;--ez-skeleton-color-middle:#e6e6e6;--ez-skeleton-color-end:#f2f2f2;--ez-skeleton-animation:react-ez-skeleton-pulse 1.4s ease-in-out infinite;}@media (prefers-reduced-motion: reduce){:root{--ez-skeleton-animation:none;}}@keyframes react-ez-skeleton-pulse{0%{background-position:100% 50%;}100%{background-position:0 50%;}}`;
+  document.head.appendChild(style);
+  stylesInjected = true;
+};
+var SkeletonText = ({
+  lines = 3,
+  lineHeight = 16,
+  gap = 8,
+  width = "100%",
+  radius = 4,
+  className = "",
+  style,
+  lineWidths,
+  randomizeLineWidths = false,
+  randomizeMin = 60,
+  randomizeMax = 100,
+  randomizeSeed,
+  animate,
+  respectReducedMotion,
+  ariaHidden,
+  injectStyles,
+  dataTestId
+}) => {
+  const clamp = (n, min2, max2) => Math.min(max2, Math.max(min2, n));
+  const createRng = (seed) => {
+    let s = seed >>> 0;
+    return () => {
+      s = 1664525 * s + 1013904223 >>> 0;
+      return s / 4294967296;
+    };
+  };
+  const rng = randomizeLineWidths ? createRng(randomizeSeed != null ? randomizeSeed : lines) : null;
+  const min = clamp(randomizeMin, 0, 100);
+  const max = clamp(randomizeMax, min, 100);
+  const getLineWidth = (index) => {
+    if (lineWidths && lineWidths[index] !== void 0) return lineWidths[index];
+    if (randomizeLineWidths && rng) {
+      const p = min + (max - min) * rng();
+      return `${Math.round(p)}%`;
+    }
+    if (index === lines - 1) return width;
+    return "100%";
+  };
+  const items = Array.from({ length: lines });
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className, style, children: items.map((_, index) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    Skeleton,
+    {
+      width: getLineWidth(index),
+      height: lineHeight,
+      radius,
+      animate,
+      respectReducedMotion,
+      ariaHidden,
+      injectStyles,
+      dataTestId: dataTestId ? `${dataTestId}-${index}` : void 0,
+      style: { marginBottom: index === lines - 1 ? 0 : toCssSize(gap) }
+    },
+    index
+  )) });
+};
+var SkeletonCircle = ({ size = 40, className = "", style, animate, respectReducedMotion, ariaHidden, injectStyles, dataTestId }) => {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    Skeleton,
+    {
+      width: size,
+      height: size,
+      radius: "50%",
+      className,
+      style,
+      animate,
+      respectReducedMotion,
+      ariaHidden,
+      injectStyles,
+      dataTestId
+    }
+  );
+};
+var index_default = Skeleton;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Skeleton,
+  SkeletonCircle,
+  SkeletonText,
+  injectSkeletonStyles
+});

package/dist/index.d.cts

@@ -0,0 +1,31 @@
+import * as React from 'react';
+
+type SkeletonProps = {
+    width?: number | string;
+    height?: number | string;
+    radius?: number | string;
+    className?: string;
+    style?: React.CSSProperties;
+    animate?: boolean;
+    respectReducedMotion?: boolean;
+    ariaHidden?: boolean;
+    injectStyles?: boolean;
+    dataTestId?: string;
+};
+declare const Skeleton: React.FC<SkeletonProps>;
+declare const injectSkeletonStyles: () => void;
+declare const SkeletonText: React.FC<Omit<SkeletonProps, "height"> & {
+    lines?: number;
+    lineHeight?: number | string;
+    gap?: number | string;
+    lineWidths?: Array<number | string>;
+    randomizeLineWidths?: boolean;
+    randomizeMin?: number;
+    randomizeMax?: number;
+    randomizeSeed?: number;
+}>;
+declare const SkeletonCircle: React.FC<Omit<SkeletonProps, "radius" | "height" | "width"> & {
+    size?: number | string;
+}>;
+
+export { Skeleton, SkeletonCircle, type SkeletonProps, SkeletonText, Skeleton as default, injectSkeletonStyles };

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import * as React from 'react';
+
+type SkeletonProps = {
+    width?: number | string;
+    height?: number | string;
+    radius?: number | string;
+    className?: string;
+    style?: React.CSSProperties;
+    animate?: boolean;
+    respectReducedMotion?: boolean;
+    ariaHidden?: boolean;
+    injectStyles?: boolean;
+    dataTestId?: string;
+};
+declare const Skeleton: React.FC<SkeletonProps>;
+declare const injectSkeletonStyles: () => void;
+declare const SkeletonText: React.FC<Omit<SkeletonProps, "height"> & {
+    lines?: number;
+    lineHeight?: number | string;
+    gap?: number | string;
+    lineWidths?: Array<number | string>;
+    randomizeLineWidths?: boolean;
+    randomizeMin?: number;
+    randomizeMax?: number;
+    randomizeSeed?: number;
+}>;
+declare const SkeletonCircle: React.FC<Omit<SkeletonProps, "radius" | "height" | "width"> & {
+    size?: number | string;
+}>;
+
+export { Skeleton, SkeletonCircle, type SkeletonProps, SkeletonText, Skeleton as default, injectSkeletonStyles };

package/dist/index.js

@@ -0,0 +1,137 @@
+// src/index.tsx
+import { jsx } from "react/jsx-runtime";
+var stylesInjected = false;
+var toCssSize = (value) => {
+  if (value === void 0) return void 0;
+  if (typeof value === "number") return `${value}px`;
+  return value;
+};
+var Skeleton = ({
+  width = "100%",
+  height = 16,
+  radius = 4,
+  className = "",
+  style,
+  animate = true,
+  respectReducedMotion = true,
+  ariaHidden = true,
+  injectStyles = true,
+  dataTestId
+}) => {
+  if (injectStyles) injectSkeletonStyles();
+  const prefersReducedMotion = respectReducedMotion && typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  const inlineStyle = {
+    display: "inline-block",
+    background: "linear-gradient(90deg, var(--ez-skeleton-color-start, #f2f2f2) 25%, var(--ez-skeleton-color-middle, #e6e6e6) 37%, var(--ez-skeleton-color-end, #f2f2f2) 63%)",
+    backgroundSize: "400% 100%",
+    animation: animate && !prefersReducedMotion ? "var(--ez-skeleton-animation, react-ez-skeleton-pulse 1.4s ease-in-out infinite)" : "none",
+    borderRadius: toCssSize(radius),
+    width: toCssSize(width),
+    height: toCssSize(height),
+    ...style
+  };
+  return /* @__PURE__ */ jsx(
+    "span",
+    {
+      className,
+      style: inlineStyle,
+      "aria-hidden": ariaHidden,
+      "data-testid": dataTestId
+    }
+  );
+};
+var injectSkeletonStyles = () => {
+  if (stylesInjected) return;
+  if (typeof document === "undefined") return;
+  const id = "react-ez-skeleton-keyframes";
+  if (document.getElementById(id)) {
+    stylesInjected = true;
+    return;
+  }
+  const style = document.createElement("style");
+  style.id = id;
+  style.innerHTML = `:root{--ez-skeleton-color-start:#f2f2f2;--ez-skeleton-color-middle:#e6e6e6;--ez-skeleton-color-end:#f2f2f2;--ez-skeleton-animation:react-ez-skeleton-pulse 1.4s ease-in-out infinite;}@media (prefers-reduced-motion: reduce){:root{--ez-skeleton-animation:none;}}@keyframes react-ez-skeleton-pulse{0%{background-position:100% 50%;}100%{background-position:0 50%;}}`;
+  document.head.appendChild(style);
+  stylesInjected = true;
+};
+var SkeletonText = ({
+  lines = 3,
+  lineHeight = 16,
+  gap = 8,
+  width = "100%",
+  radius = 4,
+  className = "",
+  style,
+  lineWidths,
+  randomizeLineWidths = false,
+  randomizeMin = 60,
+  randomizeMax = 100,
+  randomizeSeed,
+  animate,
+  respectReducedMotion,
+  ariaHidden,
+  injectStyles,
+  dataTestId
+}) => {
+  const clamp = (n, min2, max2) => Math.min(max2, Math.max(min2, n));
+  const createRng = (seed) => {
+    let s = seed >>> 0;
+    return () => {
+      s = 1664525 * s + 1013904223 >>> 0;
+      return s / 4294967296;
+    };
+  };
+  const rng = randomizeLineWidths ? createRng(randomizeSeed != null ? randomizeSeed : lines) : null;
+  const min = clamp(randomizeMin, 0, 100);
+  const max = clamp(randomizeMax, min, 100);
+  const getLineWidth = (index) => {
+    if (lineWidths && lineWidths[index] !== void 0) return lineWidths[index];
+    if (randomizeLineWidths && rng) {
+      const p = min + (max - min) * rng();
+      return `${Math.round(p)}%`;
+    }
+    if (index === lines - 1) return width;
+    return "100%";
+  };
+  const items = Array.from({ length: lines });
+  return /* @__PURE__ */ jsx("div", { className, style, children: items.map((_, index) => /* @__PURE__ */ jsx(
+    Skeleton,
+    {
+      width: getLineWidth(index),
+      height: lineHeight,
+      radius,
+      animate,
+      respectReducedMotion,
+      ariaHidden,
+      injectStyles,
+      dataTestId: dataTestId ? `${dataTestId}-${index}` : void 0,
+      style: { marginBottom: index === lines - 1 ? 0 : toCssSize(gap) }
+    },
+    index
+  )) });
+};
+var SkeletonCircle = ({ size = 40, className = "", style, animate, respectReducedMotion, ariaHidden, injectStyles, dataTestId }) => {
+  return /* @__PURE__ */ jsx(
+    Skeleton,
+    {
+      width: size,
+      height: size,
+      radius: "50%",
+      className,
+      style,
+      animate,
+      respectReducedMotion,
+      ariaHidden,
+      injectStyles,
+      dataTestId
+    }
+  );
+};
+var index_default = Skeleton;
+export {
+  Skeleton,
+  SkeletonCircle,
+  SkeletonText,
+  index_default as default,
+  injectSkeletonStyles
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "react-ez-skeleton",
+  "version": "1.0.0",
+  "description": "react-ez-skeleton provides simple, flexible skeleton components for React applications, enabling fast setup and smooth loading states without unnecessary complexity.",
+  "license": "MIT",
+  "author": "Md. Shafiul Alam",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup src/index.tsx --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.tsx --format esm --dts --watch",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "peerDependencies": {
+    "react": "^17.0.0 || ^18.0.0",
+    "react-dom": "^17.0.0 || ^18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}