react-smart-loading-effects 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,336 @@
+# React Smart Loading Effects
+
+[![npm version](https://img.shields.io/npm/v/react-smart-loading-effects.svg)](https://www.npmjs.com/package/react-smart-loading-effects)
+[![bundle size](https://img.shields.io/badge/gzip-2.7%20KB-brightgreen)](https://www.npmjs.com/package/react-smart-loading-effects)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ready-blue)](https://www.npmjs.com/package/react-smart-loading-effects)
+[![license](https://img.shields.io/npm/l/react-smart-loading-effects.svg)](https://www.npmjs.com/package/react-smart-loading-effects)
+
+**The easiest way to add beautiful React skeleton loaders to your app.**
+
+`react-smart-loading-effects` is a lightweight **React skeleton loader** library with polished **shimmer animation**, zero configuration, and production-ready layouts for the UI patterns you build every day — product cards, data tables, SaaS dashboards, user profiles, notification lists, and article text.
+
+Stop hand-coding dozens of placeholder `<div>` elements. Install once, drop in `<SmartLoader />`, and ship professional **loading skeleton screens** in under 30 seconds.
+
+```bash
+npm install react-smart-loading-effects
+```
+
+**Peer dependencies:** React 18+ and React DOM 18+
+
+---
+
+## See it in action
+
+![React skeleton loader overview — card, table, dashboard, profile, list, and text shimmer loaders](https://cdn.jsdelivr.net/npm/react-smart-loading-effects@1.0.0/docs/overview-demo.gif)
+
+*Six loader types, one package. GPU-friendly shimmer, accessible defaults, ~2.7 KB gzipped.*
+
+---
+
+## Table of contents
+
+- [Why use this library?](#why-use-this-library)
+- [Key features](#key-features)
+- [Quick start](#quick-start)
+- [Loader demos](#loader-demos)
+  - [Card skeleton loader](#card-skeleton-loader)
+  - [Table skeleton loader](#table-skeleton-loader)
+  - [Dashboard skeleton loader](#dashboard-skeleton-loader)
+  - [Profile skeleton loader](#profile-skeleton-loader)
+  - [List skeleton loader](#list-skeleton-loader)
+  - [Text skeleton loader](#text-skeleton-loader)
+- [API reference](#api-reference)
+- [Framework support](#framework-support)
+- [Accessibility](#accessibility)
+- [FAQ](#faq)
+- [Local demo](#local-demo)
+- [License](#license)
+
+---
+
+## Why use this library?
+
+Most React apps need **loading placeholders** — but building them from scratch is repetitive:
+
+- Card grids need image, title, description, and button skeletons
+- Admin panels need table row and column placeholders
+- Dashboards need KPI cards, chart areas, and sidebar stubs
+- Profile pages need avatar, name, and bio lines
+- Feeds need list items with avatars and text
+- Articles need multi-line text skeletons
+
+`react-smart-loading-effects` gives you all of this with a single prop:
+
+```tsx
+<SmartLoader type="table" rows={10} columns={5} />
+```
+
+No CSS imports. No UI framework. No Tailwind dependency. Just beautiful, accessible **React loading states** out of the box.
+
+---
+
+## Key features
+
+- **6 production-ready layouts** — card, table, dashboard, profile, list, text
+- **Shimmer animation** — smooth, GPU-accelerated skeleton shimmer (disable with `animated={false}`)
+- **Zero configuration** — styles inject automatically on first render
+- **Tiny bundle** — ~2.7 KB gzipped (ESM)
+- **TypeScript** — full type exports for props and loader types
+- **Accessible** — `aria-busy`, `aria-hidden`, and `prefers-reduced-motion` support
+- **Next.js ready** — works with App Router, Pages Router, and React Server Components consumers
+- **Tree-shakeable** — ESM + CommonJS builds via tsup
+
+---
+
+## Quick start
+
+```tsx
+import { SmartLoader } from "react-smart-loading-effects";
+
+function ProductGrid({ loading }: { loading: boolean }) {
+  if (loading) {
+    return <SmartLoader type="card" />;
+  }
+  return <ProductCard />;
+}
+```
+
+Use while data is fetching:
+
+```tsx
+{isLoading ? <SmartLoader type="table" rows={8} columns={5} /> : <DataTable data={data} />}
+```
+
+---
+
+## Loader demos
+
+### Card skeleton loader
+
+Perfect for **product cards**, blog post previews, e-commerce grids, and service tiles.
+
+![React card skeleton loader with shimmer — image, title, description, and CTA placeholders](https://cdn.jsdelivr.net/npm/react-smart-loading-effects@1.0.0/docs/card-loader.gif)
+
+```tsx
+<SmartLoader type="card" />
+```
+
+Includes image placeholder (16:9), title bar, description lines, and CTA button skeleton.
+
+---
+
+### Table skeleton loader
+
+Ideal for **admin dashboards**, CRM tables, analytics grids, and any paginated data view.
+
+![React table skeleton loader with shimmer — configurable rows and columns](https://cdn.jsdelivr.net/npm/react-smart-loading-effects@1.0.0/docs/table-loader.gif)
+
+```tsx
+<SmartLoader type="table" rows={10} columns={5} />
+```
+
+Configurable `rows` and `columns` with a responsive horizontal scroll wrapper.
+
+---
+
+### Dashboard skeleton loader
+
+Built for **SaaS dashboards**, analytics pages, and internal admin tools.
+
+![React dashboard skeleton loader — KPI cards, chart placeholders, and sidebar](https://cdn.jsdelivr.net/npm/react-smart-loading-effects@1.0.0/docs/dashboard-loader.gif)
+
+```tsx
+<SmartLoader type="dashboard" />
+```
+
+Includes KPI stat cards, two chart panel placeholders, and a sidebar navigation strip.
+
+---
+
+### Profile skeleton loader
+
+Great for **user profile pages**, team directories, and account settings screens.
+
+![React profile skeleton loader — avatar, name, and bio line placeholders](https://cdn.jsdelivr.net/npm/react-smart-loading-effects@1.0.0/docs/profile-loader.gif)
+
+```tsx
+<SmartLoader type="profile" />
+```
+
+Centered layout with circular avatar, name bar, and multi-line bio placeholders.
+
+---
+
+### List skeleton loader
+
+Use for **notification feeds**, message inboxes, activity streams, and comment lists.
+
+![React list skeleton loader — avatar, title, and subtitle rows](https://cdn.jsdelivr.net/npm/react-smart-loading-effects@1.0.0/docs/list-loader.gif)
+
+```tsx
+<SmartLoader type="list" rows={6} />
+```
+
+Each row includes a circular avatar, title line, and subtitle line.
+
+---
+
+### Text skeleton loader
+
+Designed for **blog articles**, documentation pages, long-form content, and paragraph loading.
+
+![React text skeleton loader — multi-line content with natural width variation](https://cdn.jsdelivr.net/npm/react-smart-loading-effects@1.0.0/docs/text-loader.gif)
+
+```tsx
+<SmartLoader type="text" rows={8} />
+```
+
+Multiple text rows with varied widths (100%, 92%, 78%) for a natural reading feel.
+
+---
+
+### Static skeleton (no animation)
+
+Disable shimmer for static placeholders or when you handle animation yourself:
+
+```tsx
+<SmartLoader type="card" animated={false} />
+```
+
+---
+
+## API reference
+
+### `SmartLoader`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `"card" \| "table" \| "dashboard" \| "profile" \| "list" \| "text"` | — | Skeleton layout (required) |
+| `rows` | `number` | varies | Row count for table, list, and text loaders |
+| `columns` | `number` | `4` | Column count for table loader |
+| `animated` | `boolean` | `true` | Enable shimmer skeleton animation |
+| `width` | `number \| string` | `"100%"` | Container width |
+| `height` | `number \| string` | — | Container height |
+| `className` | `string` | — | Additional CSS class on loader root |
+
+### Individual loaders
+
+Import loaders directly for finer control:
+
+```tsx
+import {
+  CardLoader,
+  TableLoader,
+  DashboardLoader,
+  ProfileLoader,
+  ListLoader,
+  TextLoader,
+  Skeleton,
+} from "react-smart-loading-effects";
+
+<CardLoader animated />
+<TableLoader rows={5} columns={4} />
+<Skeleton width={200} height={20} borderRadius={8} />
+```
+
+### TypeScript
+
+```tsx
+import type { SmartLoaderProps, LoaderType, LoaderCommonProps } from "react-smart-loading-effects";
+```
+
+---
+
+## Framework support
+
+| Framework | Support |
+|-----------|---------|
+| React 18+ | Yes |
+| React 19+ | Yes |
+| Next.js (App Router) | Yes |
+| Next.js (Pages Router) | Yes |
+| Vite | Yes |
+| Create React App | Yes |
+
+No CSS file imports required — shimmer keyframes are injected automatically when `SmartLoader` mounts.
+
+### Next.js example
+
+```tsx
+"use client";
+
+import { SmartLoader } from "react-smart-loading-effects";
+
+export default function Loading() {
+  return <SmartLoader type="dashboard" />;
+}
+```
+
+---
+
+## Accessibility
+
+Built-in accessibility for screen readers and motion preferences:
+
+- Loading root uses `role="status"`, `aria-busy="true"`, and `aria-label="Loading"`
+- Decorative skeleton blocks are marked `aria-hidden="true"`
+- Shimmer animation respects **`prefers-reduced-motion: reduce`** — users who prefer less motion see static skeletons automatically
+
+---
+
+## FAQ
+
+### What is a React skeleton loader?
+
+A **skeleton loader** (or **skeleton screen**) is a placeholder UI that mimics the shape of content while data loads. Unlike spinners, skeletons reduce perceived wait time by showing users what is coming. `react-smart-loading-effects` provides pre-built skeleton layouts with shimmer animation.
+
+### How is this different from a spinner?
+
+Spinners show activity but not structure. **Skeleton loaders** preview the actual layout — card images, table rows, dashboard charts — so users feel less disoriented during loading.
+
+### Do I need to import CSS?
+
+No. Shimmer styles are injected once on first render. Zero extra setup.
+
+### Does it work with Next.js?
+
+Yes. Use `SmartLoader` in client components (`"use client"`) or in loading.tsx files. No SSR issues — styles inject on the client.
+
+### Can I disable the shimmer animation?
+
+Yes: `<SmartLoader type="card" animated={false} />`. Animation also auto-disables when the user has reduced motion enabled in their OS settings.
+
+### How big is the bundle?
+
+Approximately **2.7 KB gzipped** (ESM). No runtime dependencies beyond React.
+
+### Can I use individual loader components?
+
+Yes. Export `CardLoader`, `TableLoader`, `DashboardLoader`, `ProfileLoader`, `ListLoader`, `TextLoader`, and the base `Skeleton` primitive.
+
+---
+
+## Local demo
+
+Preview all loaders with animation controls:
+
+```bash
+npm run build
+npm run demo
+```
+
+Open [http://localhost:5174](http://localhost:5174).
+
+### Regenerate README GIFs
+
+```bash
+npm run build
+npm run demo          # keep dev server running
+npm run demo:gif      # captures docs/*.gif via Playwright
+```
+
+---
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,49 @@
+import * as react from 'react';
+import { CSSProperties } from 'react';
+
+type LoaderType = "card" | "table" | "dashboard" | "profile" | "list" | "text";
+interface SmartLoaderProps {
+    type: LoaderType;
+    rows?: number;
+    columns?: number;
+    animated?: boolean;
+    width?: number | string;
+    height?: number | string;
+    className?: string;
+}
+interface LoaderCommonProps {
+    rows?: number;
+    columns?: number;
+    animated?: boolean;
+    width?: number | string;
+    height?: number | string;
+    className?: string;
+}
+
+declare const SmartLoader: react.MemoExoticComponent<({ type, rows, columns, animated, width, height, className, }: SmartLoaderProps) => react.JSX.Element>;
+
+declare const CardLoader: react.MemoExoticComponent<({ animated, width, height, className, }: LoaderCommonProps) => react.JSX.Element>;
+
+declare const TableLoader: react.MemoExoticComponent<({ rows, columns, animated, width, height, className, }: LoaderCommonProps) => react.JSX.Element>;
+
+declare const DashboardLoader: react.MemoExoticComponent<({ animated, width, height, className, }: LoaderCommonProps) => react.JSX.Element>;
+
+declare const ProfileLoader: react.MemoExoticComponent<({ animated, width, height, className, }: LoaderCommonProps) => react.JSX.Element>;
+
+declare const ListLoader: react.MemoExoticComponent<({ rows, animated, width, height, className, }: LoaderCommonProps) => react.JSX.Element>;
+
+declare const TextLoader: react.MemoExoticComponent<({ rows, animated, width, height, className, }: LoaderCommonProps) => react.JSX.Element>;
+
+interface SkeletonProps {
+    width?: number | string;
+    height?: number | string;
+    borderRadius?: number | string;
+    animated?: boolean;
+    className?: string;
+    style?: CSSProperties;
+}
+declare const Skeleton: react.MemoExoticComponent<({ width, height, borderRadius, animated, className, style, }: SkeletonProps) => react.JSX.Element>;
+
+declare function useReducedMotion(): boolean;
+
+export { CardLoader, DashboardLoader, ListLoader, type LoaderCommonProps, type LoaderType, ProfileLoader, Skeleton, type SkeletonProps, SmartLoader, type SmartLoaderProps, TableLoader, TextLoader, useReducedMotion };

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+import * as react from 'react';
+import { CSSProperties } from 'react';
+
+type LoaderType = "card" | "table" | "dashboard" | "profile" | "list" | "text";
+interface SmartLoaderProps {
+    type: LoaderType;
+    rows?: number;
+    columns?: number;
+    animated?: boolean;
+    width?: number | string;
+    height?: number | string;
+    className?: string;
+}
+interface LoaderCommonProps {
+    rows?: number;
+    columns?: number;
+    animated?: boolean;
+    width?: number | string;
+    height?: number | string;
+    className?: string;
+}
+
+declare const SmartLoader: react.MemoExoticComponent<({ type, rows, columns, animated, width, height, className, }: SmartLoaderProps) => react.JSX.Element>;
+
+declare const CardLoader: react.MemoExoticComponent<({ animated, width, height, className, }: LoaderCommonProps) => react.JSX.Element>;
+
+declare const TableLoader: react.MemoExoticComponent<({ rows, columns, animated, width, height, className, }: LoaderCommonProps) => react.JSX.Element>;
+
+declare const DashboardLoader: react.MemoExoticComponent<({ animated, width, height, className, }: LoaderCommonProps) => react.JSX.Element>;
+
+declare const ProfileLoader: react.MemoExoticComponent<({ animated, width, height, className, }: LoaderCommonProps) => react.JSX.Element>;
+
+declare const ListLoader: react.MemoExoticComponent<({ rows, animated, width, height, className, }: LoaderCommonProps) => react.JSX.Element>;
+
+declare const TextLoader: react.MemoExoticComponent<({ rows, animated, width, height, className, }: LoaderCommonProps) => react.JSX.Element>;
+
+interface SkeletonProps {
+    width?: number | string;
+    height?: number | string;
+    borderRadius?: number | string;
+    animated?: boolean;
+    className?: string;
+    style?: CSSProperties;
+}
+declare const Skeleton: react.MemoExoticComponent<({ width, height, borderRadius, animated, className, style, }: SkeletonProps) => react.JSX.Element>;
+
+declare function useReducedMotion(): boolean;
+
+export { CardLoader, DashboardLoader, ListLoader, type LoaderCommonProps, type LoaderType, ProfileLoader, Skeleton, type SkeletonProps, SmartLoader, type SmartLoaderProps, TableLoader, TextLoader, useReducedMotion };