shimmer-from-structure 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,474 @@
+# ✨ Shimmer From Structure
+
+A **React & Vue** shimmer/skeleton library that **automatically adapts to your component's runtime structure**. Unlike traditional shimmer libraries that require pre-defined skeleton structures, this library analyzes your actual component's DOM at runtime and generates a shimmer effect that perfectly matches its layout.
+
+![Shimmer From Structure Demo](./example/preview.gif)
+
+## Why This Library?
+
+Traditional shimmer libraries require you to:
+
+- Manually create skeleton components that mirror your real components
+- Maintain two versions of each component (real + skeleton)
+- Update skeletons every time your layout changes
+
+**Shimmer From Structure** eliminates all of that:
+
+- ✅ **Works with React & Vue** - Simple, framework-specific drivers
+- ✅ Automatically measures your component's structure at runtime
+- ✅ Generates shimmer effects that match actual dimensions
+- ✅ Zero maintenance - works with any layout changes
+- ✅ Works with complex nested structures
+- ✅ Supports dynamic data with `templateProps`
+- ✅ Preserves container backgrounds during loading
+- ✅ Auto-detects border-radius from your CSS
+
+## Installation
+
+```bash
+npm install shimmer-from-structure
+# or
+yarn add shimmer-from-structure
+# or
+pnpm add shimmer-from-structure
+```
+
+## 🎯 Framework Support
+
+Shimmer From Structure provides dedicated packages for **React and Vue**.
+
+### React
+
+React support is built-in to the main package for backward compatibility:
+
+```javascript
+// React projects (or @shimmer-from-structure/react)
+import { Shimmer } from 'shimmer-from-structure';
+```
+
+### Vue 3
+
+Vue support requires importing from the specific adapter:
+
+```javascript
+// Vue 3 projects
+import { Shimmer } from '@shimmer-from-structure/vue';
+```
+
+---
+
+# 📖 Basic Usage
+
+## React
+
+### Static Content
+
+For components with hardcoded/static content:
+
+```tsx
+import { Shimmer } from 'shimmer-from-structure';
+
+function UserCard() {
+  return (
+    <Shimmer loading={isLoading}>
+      <div className="card">
+        <img src="avatar.jpg" className="avatar" />
+        <h2>John Doe</h2>
+        <p>Software Engineer</p>
+      </div>
+    </Shimmer>
+  );
+}
+```
+
+## Vue
+
+### Static Content
+
+```vue
+<script setup>
+import { ref } from 'vue';
+import { Shimmer } from '@shimmer-from-structure/vue';
+
+const isLoading = ref(true);
+</script>
+
+<template>
+  <Shimmer :loading="isLoading">
+    <div class="card">
+      <img src="avatar.jpg" class="avatar" />
+      <h2>John Doe</h2>
+      <p>Software Engineer</p>
+    </div>
+  </Shimmer>
+</template>
+```
+
+---
+
+### Dynamic Content with `templateProps`
+
+For components that receive dynamic data via props, use `templateProps` to provide mock data for skeleton generation:
+
+```tsx
+import { Shimmer } from 'shimmer-from-structure';
+
+// Your component that accepts props
+const UserCard = ({ user }) => (
+  <div className="card">
+    <img src={user.avatar} className="avatar" />
+    <h2>{user.name}</h2>
+    <p>{user.role}</p>
+  </div>
+);
+
+// Template data for the skeleton
+const userTemplate = {
+  name: 'Loading...',
+  role: 'Loading role...',
+  avatar: 'placeholder.jpg',
+};
+
+function App() {
+  const [loading, setLoading] = useState(true);
+  const [user, setUser] = useState(null);
+
+  return (
+    <Shimmer loading={loading} templateProps={{ user: userTemplate }}>
+      <UserCard user={user || userTemplate} />
+    </Shimmer>
+  );
+}
+```
+
+The `templateProps` object is spread onto the first child component when loading, allowing it to render with mock data for measurement.
+
+## 🎨 API Reference
+
+### `<Shimmer>` Props
+
+| Prop                   | Type                      | Default                    | Description                                               |
+| ---------------------- | ------------------------- | -------------------------- | --------------------------------------------------------- |
+| `loading`              | `boolean`                 | `true`                     | Whether to show shimmer effect or actual content          |
+| `children`             | `React.ReactNode`         | required                   | The content to render/measure                             |
+| `shimmerColor`         | `string`                  | `'rgba(255,255,255,0.15)'` | Color of the shimmer wave                                 |
+| `backgroundColor`      | `string`                  | `'rgba(255,255,255,0.08)'` | Background color of shimmer blocks                        |
+| `duration`             | `number`                  | `1.5`                      | Animation duration in seconds                             |
+| `fallbackBorderRadius` | `number`                  | `4`                        | Border radius (px) for elements with no CSS border-radius |
+| `templateProps`        | `Record<string, unknown>` | -                          | Props to inject into first child for skeleton rendering   |
+
+### Example with All Props
+
+```tsx
+<Shimmer
+  loading={isLoading}
+  shimmerColor="rgba(255, 255, 255, 0.2)"
+  backgroundColor="rgba(255, 255, 255, 0.1)"
+  duration={2}
+  fallbackBorderRadius={8}
+  templateProps={{
+    user: userTemplate,
+    settings: settingsTemplate,
+  }}
+>
+  <MyComponent user={user} settings={settings} />
+</Shimmer>
+```
+
+## 🔧 How It Works
+
+1. **Visible Container Rendering**: When `loading={true}`, your component renders with transparent text but **visible container backgrounds**
+2. **Template Props Injection**: If `templateProps` is provided, it's spread onto the first child so dynamic components can render
+3. **DOM Measurement**: Uses `useLayoutEffect` to synchronously measure all leaf elements via `getBoundingClientRect()`
+4. **Border Radius Detection**: Automatically captures each element's computed `border-radius` from CSS
+5. **Shimmer Generation**: Creates absolutely-positioned shimmer blocks matching measured dimensions
+6. **Animation**: Applies smooth gradient animation that sweeps across each block
+
+### Key Features
+
+- **Container backgrounds visible**: Unlike `opacity: 0`, we use `color: transparent` so card backgrounds/borders show during loading
+- **Auto border-radius**: Circular avatars get circular shimmer blocks automatically
+- **Fallback radius**: Text elements (which have `border-radius: 0`) use `fallbackBorderRadius` to avoid sharp rectangles
+- **Dark-mode friendly**: Default colors use semi-transparent whites that work on any background
+
+## Examples
+
+### Dashboard with Multiple Sections
+
+Each section can have its own independent loading state:
+
+```tsx
+function Dashboard() {
+  const [loadingUser, setLoadingUser] = useState(true);
+  const [loadingStats, setLoadingStats] = useState(true);
+
+  return (
+    <>
+      {/* User profile section */}
+      <Shimmer loading={loadingUser} templateProps={{ user: userTemplate }}>
+        <UserProfile user={user} />
+      </Shimmer>
+
+      {/* Stats section - with custom colors */}
+      <Shimmer
+        loading={loadingStats}
+        templateProps={{ stats: statsTemplate }}
+        shimmerColor="rgba(20, 184, 166, 0.2)"
+      >
+        <StatsGrid stats={stats} />
+      </Shimmer>
+    </>
+  );
+}
+```
+
+### Transactions List
+
+```tsx
+<Shimmer loading={loadingTransactions} templateProps={{ transactions: transactionsTemplate }}>
+  <TransactionsList transactions={transactions} />
+</Shimmer>
+```
+
+### Team Members Grid
+
+```tsx
+<Shimmer loading={loadingTeam} templateProps={{ members: teamTemplate }}>
+  <TeamMembers members={team} />
+</Shimmer>
+```
+
+## 🔄 Using with React Suspense
+
+Shimmer works seamlessly as a Suspense fallback. When used this way, `loading` is always `true` because React automatically unmounts the fallback and replaces it with the resolved component.
+
+### Basic Suspense Pattern
+
+```tsx
+import { Suspense, lazy } from 'react';
+import { Shimmer } from 'shimmer-from-structure';
+
+const UserProfile = lazy(() => import('./UserProfile'));
+
+function App() {
+  return (
+    <Suspense
+      fallback={
+        <Shimmer loading={true} templateProps={{ user: userTemplate }}>
+          <UserProfile />
+        </Shimmer>
+      }
+    >
+      <UserProfile userId="123" />
+    </Suspense>
+  );
+}
+```
+
+### Why `loading={true}` is Always Set
+
+When using Shimmer as a Suspense fallback:
+
+1. **Suspend**: React renders the fallback → Shimmer shows with `loading={true}`
+2. **Resolve**: React **replaces** the entire fallback with the real component
+3. The Shimmer is **unmounted**, not updated — so you never need to toggle `loading`
+
+### Performance Tips for Suspense
+
+**Memoize the fallback** to prevent re-renders:
+
+```tsx
+const ShimmerFallback = React.memo(() => (
+  <Shimmer loading={true} templateProps={{ user: userTemplate }}>
+    <UserProfile />
+  </Shimmer>
+));
+
+// Usage
+<Suspense fallback={<ShimmerFallback />}>
+  <UserProfile userId="123" />
+</Suspense>;
+```
+
+**Keep templates lightweight** — the DOM is measured synchronously via `useLayoutEffect`, so avoid complex logic in your template.
+
+## Global Configuration (Context API)
+
+You can set default configuration for your entire app (or specific sections) using the context/provider pattern. This is perfect for maintaining consistent themes without repeating props.
+
+### React
+
+```tsx
+import { Shimmer, ShimmerProvider } from '@shimmer-from-structure/react';
+
+function App() {
+  return (
+    // Set global defaults
+    <ShimmerProvider
+      config={{
+        shimmerColor: 'rgba(56, 189, 248, 0.4)', // Blue shimmer
+        backgroundColor: 'rgba(56, 189, 248, 0.1)', // Blue background
+        duration: 2.5,
+        fallbackBorderRadius: 8,
+      }}
+    >
+      <Dashboard />
+    </ShimmerProvider>
+  );
+}
+```
+
+### Vue
+
+```vue
+<!-- App.vue -->
+<script setup>
+import { Shimmer, provideShimmerConfig } from '@shimmer-from-structure/vue';
+
+provideShimmerConfig({
+  shimmerColor: 'rgba(255, 0, 0, 0.1)',
+  duration: 2,
+});
+</script>
+
+<template>
+  <router-view />
+</template>
+```
+
+---
+
+Components inside the provider automatically inherit values. You can still override them locally:
+
+```tsx
+// Inherits blue theme from provider
+<Shimmer loading={true}><UserCard /></Shimmer>
+
+// Overrides provider settings
+<Shimmer loading={true} duration={0.5}><FastCard /></Shimmer>
+```
+
+### Accessing Config in Hooks
+
+If you need to access the current configuration in your own components:
+
+```tsx
+import { useShimmerConfig } from 'shimmer-from-structure';
+
+function MyComponent() {
+  const config = useShimmerConfig();
+  return <div style={{ background: config.backgroundColor }}>...</div>;
+}
+```
+
+## Best Practices
+
+### 1. Use `templateProps` for Dynamic Data
+
+When your component receives data via props, always provide `templateProps` with mock data that matches the expected structure.
+
+### 2. Match Template Structure to Real Data
+
+Ensure your template data has the same array length and property structure as real data for accurate shimmer layout.
+
+### 3. Use Individual Shimmer Components
+
+Wrap each section in its own Shimmer for independent loading states:
+
+```tsx
+// ✅ Good - independent loading
+<Shimmer loading={loadingUsers}><UserList /></Shimmer>
+<Shimmer loading={loadingPosts}><PostList /></Shimmer>
+
+// ❌ Avoid - all-or-nothing loading
+<Shimmer loading={loadingUsers || loadingPosts}>
+  <UserList />
+  <PostList />
+</Shimmer>
+```
+
+### 4. Consider Element Widths
+
+Block elements like `<h1>`, `<p>` take full container width. If you want shimmer to match text width:
+
+```css
+.title {
+  width: fit-content;
+}
+```
+
+### 5. Provide Container Dimensions
+
+For async components (like charts), ensure containers have explicit dimensions so shimmer has something to measure.
+
+## ⚡ Performance Considerations
+
+- Measurement happens only when `loading` changes to `true`
+- Uses `useLayoutEffect` for synchronous measurement (no flicker)
+- Minimal re-renders - only updates when loading state or children change
+- Lightweight DOM measurements using native browser APIs
+
+- Lightweight DOM measurements using native browser APIs
+
+## 🛠️ Development
+
+This is a monorepo managed with npm workspaces. Each package can be built independently:
+
+```bash
+# Install dependencies
+npm install
+
+# Build all packages
+npm run build
+
+# Build individual packages
+npm run build:core
+npm run build:react
+npm run build:vue
+npm run build:main
+
+# Run tests
+npm test
+```
+
+## 📝 License
+
+MIT
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 🐛 Known Limitations
+
+- **Async components**: Components that render asynchronously (like charts using `ResponsiveContainer`) may need explicit container dimensions
+- **Zero-dimension elements**: Elements with `display: none` or zero dimensions won't be captured
+- **SVG internals**: Only the outer `<svg>` element is captured, not internal paths/shapes
+
+## 🏗️ Monorepo Structure
+
+This library is organized as a monorepo with four packages:
+
+| Package                         | Description                                 | Size     |
+| ------------------------------- | ------------------------------------------- | -------- |
+| `@shimmer-from-structure/core`  | Framework-agnostic DOM utilities            | 1.44 kB  |
+| `@shimmer-from-structure/react` | React adapter                               | 12.84 kB |
+| `@shimmer-from-structure/vue`   | Vue 3 adapter                               | 3.89 kB  |
+| `shimmer-from-structure`        | Main package (React backward compatibility) | 0.93 kB  |
+
+The core package contains all DOM measurement logic, while React and Vue packages are thin wrappers that provide framework-specific APIs.
+
+## 🚧 Roadmap
+
+- [x] Dynamic data support via `templateProps`
+- [x] Auto border-radius detection
+- [x] Container background visibility
+- [x] **Vue.js adapter** ✨
+- [ ] Better async component support
+- [ ] Customizable shimmer direction (vertical, diagonal)
+- [ ] React Native support
+- [ ] Svelte adapter
+
+---
+
+Made with ❤️ for developers tired of maintaining skeleton screens

package/package.json

@@ -1,42 +1,44 @@
 {
-  "name": "shimmer-from-structure",
-  "version": "1.0.0",
-  "description": "React shimmer library that automatically adapts to your component's runtime structure",
-  "main": "index.js",
-  "types": "index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./index.d.ts",
-      "default": "./index.js"
+    "name": "shimmer-from-structure",
+    "version": "1.0.2",
+    "description": "Universal UI skeleton generator for React and Vue. Auto-adapts to your component structure with zero maintenance and pixel-perfect accuracy.",
+    "main": "index.js",
+    "types": "index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./index.d.ts",
+            "default": "./index.js"
+        },
+        "./vue": "@shimmer-from-structure/vue"
     },
-    "./vue": "@shimmer-from-structure/vue"
-  },
-  "scripts": {
-    "build": "tsc"
-  },
-  "dependencies": {
-    "@shimmer-from-structure/react": "*",
-    "@shimmer-from-structure/vue": "*"
-  },
-  "peerDependencies": {
-    "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0"
-  },
-  "peerDependenciesMeta": {
-    "react": {
-      "optional": true
+    "scripts": {
+        "build": "tsc",
+        "format": "prettier --write .",
+        "prepublishOnly": "cp ../../README.md ."
     },
-    "react-dom": {
-      "optional": true
-    }
-  },
-  "keywords": [
-    "react",
-    "vue",
-    "shimmer",
-    "skeleton",
-    "loading"
-  ],
-  "author": "Olebogeng Mbedzi",
-  "license": "MIT"
-}
+    "dependencies": {
+        "@shimmer-from-structure/react": "*",
+        "@shimmer-from-structure/vue": "*"
+    },
+    "peerDependencies": {
+        "react": "^18.0.0 || ^19.0.0",
+        "react-dom": "^18.0.0 || ^19.0.0"
+    },
+    "peerDependenciesMeta": {
+        "react": {
+            "optional": true
+        },
+        "react-dom": {
+            "optional": true
+        }
+    },
+    "keywords": [
+        "react",
+        "vue",
+        "shimmer",
+        "skeleton",
+        "loading"
+    ],
+    "author": "Olebogeng Mbedzi",
+    "license": "MIT"
+}