react-streaming-skeletons 0.1.0

package/README.md

@@ -0,0 +1,248 @@
+# react-streaming-skeletons
+
+Zero-layout-shift skeleton components for React Suspense streaming and Next.js App Router.
+
+## The Problem
+
+When you stream Server Components with `<Suspense>`, a mismatched fallback causes the page to **jump** when content loads — hurting your Core Web Vitals CLS score.
+
+```tsx
+// Before — causes layout shift
+<Suspense fallback={<div className="h-4 bg-gray-200" />}>  {/* 16px */}
+  <UserProfile />                                            {/* 340px */}
+</Suspense>
+```
+
+This library gives you primitives to build dimension-matched skeletons, plus a **dev-mode warning** when your skeleton and real content heights diverge.
+
+## Installation
+
+```bash
+npm install react-streaming-skeletons
+```
+
+React 18+ and react-dom 18+ are required as peer dependencies.
+
+## Quick Start
+
+```tsx
+import { Bone, SkeletonBoundary, defineSkeleton } from 'react-streaming-skeletons'
+
+// 1. Define a skeleton co-located with your real component
+export function UserCard({ user }) {
+  return (
+    <div className="flex gap-3 p-4">
+      <img src={user.avatar} className="w-10 h-10 rounded-full" />
+      <div>
+        <h2>{user.name}</h2>
+        <p>{user.bio}</p>
+      </div>
+    </div>
+  )
+}
+
+export const UserCardSkeleton = defineSkeleton(UserCard, () => (
+  <div className="flex gap-3 p-4">
+    <Bone circle width={40} height={40} />
+    <div>
+      <Bone width={120} height={20} />
+      <Bone width={200} height={16} style={{ marginTop: 6 }} />
+    </div>
+  </div>
+))
+
+// 2. Use SkeletonBoundary instead of raw Suspense
+export default function Page() {
+  return (
+    <SkeletonBoundary fallback={<UserCardSkeleton />}>
+      <UserCard />
+    </SkeletonBoundary>
+  )
+}
+```
+
+## Next.js App Router
+
+`SkeletonBoundary` works directly in Server Component pages. Your async Server Component is passed as `children` — it retains its server nature.
+
+```tsx
+// app/dashboard/page.tsx  (Server Component)
+import { SkeletonBoundary } from 'react-streaming-skeletons'
+import { StatsCard, StatsCardSkeleton } from '@/components/StatsCard'
+
+export default function DashboardPage() {
+  return (
+    <main>
+      <h1>Dashboard</h1>
+
+      <SkeletonBoundary fallback={<StatsCardSkeleton />}>
+        <StatsCard />  {/* async Server Component — fetches from DB */}
+      </SkeletonBoundary>
+    </main>
+  )
+}
+```
+
+```tsx
+// components/StatsCard.tsx  (async Server Component)
+async function StatsCard() {
+  const stats = await fetchStats()   // streamed from server
+  return <div>{stats.revenue}</div>
+}
+```
+
+## API
+
+### `<Bone>`
+
+The core animated skeleton element.
+
+```tsx
+<Bone
+  width={200}       // number (px) or string ("60%", "10rem"). Default: "100%"
+  height={20}       // number (px) or string. Default: "1em"
+  circle            // renders as a circle (border-radius: 50%)
+  rounded           // renders as a pill (border-radius: 9999px)
+  count={3}         // renders N stacked bones
+  inline            // display: inline-block instead of block
+  className="..."   // forwarded to the element
+  style={{}}        // merged into inline styles
+/>
+```
+
+**Examples**
+
+```tsx
+// Avatar placeholder
+<Bone circle width={48} height={48} />
+
+// Text line
+<Bone width="70%" height={16} />
+
+// Paragraph (3 lines)
+<Bone count={3} height={14} />
+
+// Badge
+<Bone rounded width={80} height={24} />
+```
+
+---
+
+### `<SkeletonBoundary>`
+
+A `<Suspense>` wrapper that shows `fallback` while children stream in.
+
+```tsx
+<SkeletonBoundary
+  fallback={<MySkeleton />}
+  clsThreshold={0.1}           // dev-only: warn when height shifts > 10%. Default: 0.1
+>
+  <AsyncServerComponent />
+</SkeletonBoundary>
+```
+
+In **development mode**, `SkeletonBoundary` wraps its content in a `<div>` and uses `ResizeObserver` to detect when the resolved content height differs from the skeleton height by more than `clsThreshold`. A `console.warn` is printed with the exact pixel values so you can fix the mismatch. The wrapper div is **not rendered in production**.
+
+---
+
+### `<SkeletonProvider>`
+
+Set a global theme for all `<Bone>` elements in the tree.
+
+```tsx
+<SkeletonProvider
+  theme={{
+    color: '#e2e8f0',           // base bone colour. Default: "#e2e8f0"
+    highlight: '#f8fafc',       // shimmer highlight colour. Default: "#f8fafc"
+    borderRadius: 4,            // default radius (px or string). Default: 4
+    duration: 1.5,              // shimmer animation duration in seconds. Default: 1.5
+    animationDirection: 'ltr',  // "ltr" | "rtl". Default: "ltr"
+    enableAnimation: true,      // set false to disable shimmer (e.g. prefers-reduced-motion). Default: true
+  }}
+>
+  <App />
+</SkeletonProvider>
+```
+
+Theming is implemented with CSS custom properties (`--rss-color`, `--rss-highlight`, `--rss-duration`) so it has zero runtime overhead and respects nested overrides.
+
+---
+
+### `defineSkeleton(Component, renderFn)`
+
+Links a skeleton to its real component so they stay co-located in the same file.
+
+```tsx
+export const UserCardSkeleton = defineSkeleton(UserCard, () => (
+  <div>
+    <Bone circle width={40} height={40} />
+    <Bone width="60%" height={20} />
+  </div>
+))
+```
+
+The returned component gets a `displayName` of `"<ComponentName>Skeleton"`, which makes it easy to identify in React DevTools.
+
+---
+
+### `useSkeletonTheme()`
+
+Read the current theme values in a custom skeleton component.
+
+```tsx
+import { useSkeletonTheme } from 'react-streaming-skeletons'
+
+function CustomBone() {
+  const { color, duration } = useSkeletonTheme()
+  // ...
+}
+```
+
+## Dark Mode
+
+Wrap `SkeletonProvider` inside your theme toggle to switch bone colours:
+
+```tsx
+<SkeletonProvider
+  theme={{
+    color: isDark ? '#374151' : '#e5e7eb',
+    highlight: isDark ? '#4b5563' : '#f9fafb',
+  }}
+>
+  {children}
+</SkeletonProvider>
+```
+
+## Accessibility
+
+All `<Bone>` elements render with `aria-hidden="true"` so they are invisible to screen readers. Users who prefer reduced motion should disable the shimmer animation:
+
+```tsx
+const prefersReduced =
+  typeof window !== 'undefined' &&
+  window.matchMedia('(prefers-reduced-motion: reduce)').matches
+
+<SkeletonProvider theme={{ enableAnimation: !prefersReduced }}>
+  <App />
+</SkeletonProvider>
+```
+
+## How the CLS Warning Works
+
+In development, every `<SkeletonBoundary>` observes its container with `ResizeObserver`. The first measured height is treated as the skeleton height. When Suspense resolves and the container resizes, the new height is compared against the baseline. If the shift exceeds `clsThreshold` (default 10%), you'll see:
+
+```
+[react-streaming-skeletons] CLS risk detected!
+  Skeleton height : 32px
+  Content height  : 280px
+  Shift           : 775% (threshold: 10%)
+  Fix: match your <Bone height={...}> values to the resolved content dimensions.
+```
+
+## Bundle Size
+
+~3 KB gzipped. Zero runtime dependencies.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,54 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { CSSProperties, ReactNode, ComponentType, ReactElement, FC } from 'react';
+
+interface SkeletonTheme {
+    color: string;
+    highlight: string;
+    borderRadius: number | string;
+    duration: number;
+    animationDirection: 'ltr' | 'rtl';
+    enableAnimation: boolean;
+}
+interface BoneProps {
+    width?: number | string;
+    height?: number | string;
+    circle?: boolean;
+    rounded?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    count?: number;
+    inline?: boolean;
+}
+interface SkeletonProviderProps {
+    theme?: Partial<SkeletonTheme>;
+    children: ReactNode;
+}
+interface SkeletonBoundaryProps {
+    fallback: ReactNode;
+    children: ReactNode;
+    /** Fraction (0–1) of height change that triggers a dev-mode CLS warning. Default: 0.1 */
+    clsThreshold?: number;
+}
+
+declare function Bone({ width, height, circle, rounded, className, style, count, inline, }: BoneProps): react_jsx_runtime.JSX.Element;
+
+declare function SkeletonBoundary({ fallback, children, clsThreshold, }: SkeletonBoundaryProps): react_jsx_runtime.JSX.Element;
+
+declare const defaultTheme: SkeletonTheme;
+declare function useSkeletonTheme(): SkeletonTheme;
+declare function SkeletonProvider({ theme, children }: SkeletonProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Co-locate a skeleton with its real component so the two stay in sync.
+ *
+ * @example
+ * export const UserCardSkeleton = defineSkeleton(UserCard, () => (
+ *   <div>
+ *     <Bone circle width={40} height={40} />
+ *     <Bone width="60%" height={20} />
+ *   </div>
+ * ))
+ */
+declare function defineSkeleton<P>(Component: ComponentType<P>, render: () => ReactElement): FC;
+
+export { Bone, type BoneProps, SkeletonBoundary, type SkeletonBoundaryProps, SkeletonProvider, type SkeletonProviderProps, type SkeletonTheme, defaultTheme, defineSkeleton, useSkeletonTheme };

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { CSSProperties, ReactNode, ComponentType, ReactElement, FC } from 'react';
+
+interface SkeletonTheme {
+    color: string;
+    highlight: string;
+    borderRadius: number | string;
+    duration: number;
+    animationDirection: 'ltr' | 'rtl';
+    enableAnimation: boolean;
+}
+interface BoneProps {
+    width?: number | string;
+    height?: number | string;
+    circle?: boolean;
+    rounded?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    count?: number;
+    inline?: boolean;
+}
+interface SkeletonProviderProps {
+    theme?: Partial<SkeletonTheme>;
+    children: ReactNode;
+}
+interface SkeletonBoundaryProps {
+    fallback: ReactNode;
+    children: ReactNode;
+    /** Fraction (0–1) of height change that triggers a dev-mode CLS warning. Default: 0.1 */
+    clsThreshold?: number;
+}
+
+declare function Bone({ width, height, circle, rounded, className, style, count, inline, }: BoneProps): react_jsx_runtime.JSX.Element;
+
+declare function SkeletonBoundary({ fallback, children, clsThreshold, }: SkeletonBoundaryProps): react_jsx_runtime.JSX.Element;
+
+declare const defaultTheme: SkeletonTheme;
+declare function useSkeletonTheme(): SkeletonTheme;
+declare function SkeletonProvider({ theme, children }: SkeletonProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Co-locate a skeleton with its real component so the two stay in sync.
+ *
+ * @example
+ * export const UserCardSkeleton = defineSkeleton(UserCard, () => (
+ *   <div>
+ *     <Bone circle width={40} height={40} />
+ *     <Bone width="60%" height={20} />
+ *   </div>
+ * ))
+ */
+declare function defineSkeleton<P>(Component: ComponentType<P>, render: () => ReactElement): FC;
+
+export { Bone, type BoneProps, SkeletonBoundary, type SkeletonBoundaryProps, SkeletonProvider, type SkeletonProviderProps, type SkeletonTheme, defaultTheme, defineSkeleton, useSkeletonTheme };

package/dist/index.js

@@ -0,0 +1,184 @@
+"use client";
+'use strict';
+
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/components/Bone.tsx
+
+// src/utils/injectStyles.ts
+var CSS_ID = "rss-styles";
+var SHIMMER_CSS = `
+@keyframes rss-shimmer-ltr {
+  0%   { background-position: -200px 0; }
+  100% { background-position: calc(200px + 100%) 0; }
+}
+@keyframes rss-shimmer-rtl {
+  0%   { background-position: calc(200px + 100%) 0; }
+  100% { background-position: -200px 0; }
+}
+[data-rss-bone] {
+  display: inline-block;
+  line-height: 1;
+  background: linear-gradient(
+    90deg,
+    var(--rss-color, #e2e8f0) 25%,
+    var(--rss-highlight, #f8fafc) 50%,
+    var(--rss-color, #e2e8f0) 75%
+  );
+  background-size: 200px 100%;
+  animation: rss-shimmer-ltr var(--rss-duration, 1.5s) infinite linear;
+}
+[data-rss-direction="rtl"] [data-rss-bone] {
+  animation-name: rss-shimmer-rtl;
+}
+[data-rss-no-animation] [data-rss-bone] {
+  animation: none;
+  background: var(--rss-color, #e2e8f0);
+}
+`;
+function ensureStylesInjected() {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(CSS_ID)) return;
+  const style = document.createElement("style");
+  style.id = CSS_ID;
+  style.textContent = SHIMMER_CSS;
+  document.head.appendChild(style);
+}
+function Bone({
+  width,
+  height,
+  circle = false,
+  rounded = false,
+  className,
+  style,
+  count = 1,
+  inline = false
+}) {
+  react.useEffect(() => {
+    ensureStylesInjected();
+  }, []);
+  const borderRadius = circle ? "50%" : rounded ? "9999px" : void 0;
+  const baseStyle = {
+    width: width != null ? width : "100%",
+    height: height != null ? height : "1em",
+    borderRadius,
+    display: inline ? "inline-block" : "block",
+    ...style
+  };
+  if (count <= 1) {
+    return /* @__PURE__ */ jsxRuntime.jsx(
+      "span",
+      {
+        "data-rss-bone": "",
+        className,
+        style: baseStyle,
+        "aria-hidden": "true"
+      }
+    );
+  }
+  return /* @__PURE__ */ jsxRuntime.jsx(react.Fragment, { children: Array.from({ length: count }, (_, i) => /* @__PURE__ */ jsxRuntime.jsx(
+    "span",
+    {
+      "data-rss-bone": "",
+      className,
+      style: {
+        ...baseStyle,
+        marginBottom: i < count - 1 ? "0.5em" : void 0
+      },
+      "aria-hidden": "true"
+    },
+    i
+  )) });
+}
+var isDev = process.env.NODE_ENV === "development";
+function useCLSDetection(enabled, threshold) {
+  const containerRef = react.useRef(null);
+  const firstHeightRef = react.useRef(0);
+  const warnedRef = react.useRef(false);
+  react.useEffect(() => {
+    if (!enabled || !containerRef.current) return;
+    const el = containerRef.current;
+    firstHeightRef.current = el.getBoundingClientRect().height;
+    const observer = new ResizeObserver(() => {
+      if (warnedRef.current) return;
+      const current = el.getBoundingClientRect().height;
+      const baseline = firstHeightRef.current;
+      if (baseline === 0 || current === baseline) return;
+      const diff = Math.abs(current - baseline) / baseline;
+      if (diff > threshold) {
+        warnedRef.current = true;
+        console.warn(
+          `[react-streaming-skeletons] CLS risk detected!
+  Skeleton height : ${Math.round(baseline)}px
+  Content height  : ${Math.round(current)}px
+  Shift           : ${Math.round(diff * 100)}% (threshold: ${Math.round(threshold * 100)}%)
+  Fix: match your <Bone height={...}> values to the resolved content dimensions.`
+        );
+      }
+    });
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [enabled, threshold]);
+  return containerRef;
+}
+function SkeletonBoundary({
+  fallback,
+  children,
+  clsThreshold = 0.1
+}) {
+  const containerRef = useCLSDetection(isDev, clsThreshold);
+  if (isDev) {
+    return /* @__PURE__ */ jsxRuntime.jsx("div", { ref: containerRef, "data-rss-boundary": "", children: /* @__PURE__ */ jsxRuntime.jsx(react.Suspense, { fallback, children }) });
+  }
+  return /* @__PURE__ */ jsxRuntime.jsx(react.Suspense, { fallback, children });
+}
+var defaultTheme = {
+  color: "#e2e8f0",
+  highlight: "#f8fafc",
+  borderRadius: 4,
+  duration: 1.5,
+  animationDirection: "ltr",
+  enableAnimation: true
+};
+var SkeletonContext = react.createContext(defaultTheme);
+function useSkeletonTheme() {
+  return react.useContext(SkeletonContext);
+}
+function SkeletonProvider({ theme, children }) {
+  const merged = { ...defaultTheme, ...theme };
+  return /* @__PURE__ */ jsxRuntime.jsx(SkeletonContext.Provider, { value: merged, children: /* @__PURE__ */ jsxRuntime.jsx(
+    "div",
+    {
+      "data-rss-provider": "",
+      "data-rss-direction": merged.animationDirection,
+      ...!merged.enableAnimation ? { "data-rss-no-animation": "" } : {},
+      style: {
+        "--rss-color": merged.color,
+        "--rss-highlight": merged.highlight,
+        "--rss-duration": `${merged.duration}s`
+      },
+      children
+    }
+  ) });
+}
+
+// src/utils/defineSkeleton.ts
+function defineSkeleton(Component, render) {
+  var _a, _b;
+  const displayName = (_b = (_a = Component.displayName) != null ? _a : Component.name) != null ? _b : "Component";
+  function SkeletonComponent() {
+    return render();
+  }
+  SkeletonComponent.displayName = `${displayName}Skeleton`;
+  return SkeletonComponent;
+}
+
+exports.Bone = Bone;
+exports.SkeletonBoundary = SkeletonBoundary;
+exports.SkeletonProvider = SkeletonProvider;
+exports.defaultTheme = defaultTheme;
+exports.defineSkeleton = defineSkeleton;
+exports.useSkeletonTheme = useSkeletonTheme;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils/injectStyles.ts","../src/components/Bone.tsx","../src/components/SkeletonBoundary.tsx","../src/components/SkeletonProvider.tsx","../src/utils/defineSkeleton.ts"],"names":["useEffect","jsx","Fragment","useRef","Suspense","createContext","useContext"],"mappings":"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","file":"index.js","sourcesContent":["const CSS_ID = 'rss-styles'\n\nconst SHIMMER_CSS = `\n@keyframes rss-shimmer-ltr {\n  0%   { background-position: -200px 0; }\n  100% { background-position: calc(200px + 100%) 0; }\n}\n@keyframes rss-shimmer-rtl {\n  0%   { background-position: calc(200px + 100%) 0; }\n  100% { background-position: -200px 0; }\n}\n[data-rss-bone] {\n  display: inline-block;\n  line-height: 1;\n  background: linear-gradient(\n    90deg,\n    var(--rss-color, #e2e8f0) 25%,\n    var(--rss-highlight, #f8fafc) 50%,\n    var(--rss-color, #e2e8f0) 75%\n  );\n  background-size: 200px 100%;\n  animation: rss-shimmer-ltr var(--rss-duration, 1.5s) infinite linear;\n}\n[data-rss-direction=\"rtl\"] [data-rss-bone] {\n  animation-name: rss-shimmer-rtl;\n}\n[data-rss-no-animation] [data-rss-bone] {\n  animation: none;\n  background: var(--rss-color, #e2e8f0);\n}\n`\n\nexport function ensureStylesInjected(): void {\n  if (typeof document === 'undefined') return\n  if (document.getElementById(CSS_ID)) return\n\n  const style = document.createElement('style')\n  style.id = CSS_ID\n  style.textContent = SHIMMER_CSS\n  document.head.appendChild(style)\n}\n","'use client'\n\nimport React, { useEffect, Fragment } from 'react'\nimport { ensureStylesInjected } from '../utils/injectStyles'\nimport type { BoneProps } from '../types'\n\nexport function Bone({\n  width,\n  height,\n  circle = false,\n  rounded = false,\n  className,\n  style,\n  count = 1,\n  inline = false,\n}: BoneProps) {\n  useEffect(() => {\n    ensureStylesInjected()\n  }, [])\n\n  const borderRadius: string | undefined =\n    circle ? '50%' : rounded ? '9999px' : undefined\n\n  const baseStyle: React.CSSProperties = {\n    width: width ?? '100%',\n    height: height ?? '1em',\n    borderRadius,\n    display: inline ? 'inline-block' : 'block',\n    ...style,\n  }\n\n  if (count <= 1) {\n    return (\n      <span\n        data-rss-bone=\"\"\n        className={className}\n        style={baseStyle}\n        aria-hidden=\"true\"\n      />\n    )\n  }\n\n  return (\n    <Fragment>\n      {Array.from({ length: count }, (_, i) => (\n        <span\n          key={i}\n          data-rss-bone=\"\"\n          className={className}\n          style={{\n            ...baseStyle,\n            marginBottom: i < count - 1 ? '0.5em' : undefined,\n          }}\n          aria-hidden=\"true\"\n        />\n      ))}\n    </Fragment>\n  )\n}\n","'use client'\n\nimport React, { Suspense, useRef, useEffect } from 'react'\nimport type { SkeletonBoundaryProps } from '../types'\n\nconst isDev = process.env.NODE_ENV === 'development'\n\nfunction useCLSDetection(enabled: boolean, threshold: number) {\n  const containerRef = useRef<HTMLDivElement>(null)\n  const firstHeightRef = useRef(0)\n  const warnedRef = useRef(false)\n\n  useEffect(() => {\n    if (!enabled || !containerRef.current) return\n\n    const el = containerRef.current\n    firstHeightRef.current = el.getBoundingClientRect().height\n\n    const observer = new ResizeObserver(() => {\n      if (warnedRef.current) return\n\n      const current = el.getBoundingClientRect().height\n      const baseline = firstHeightRef.current\n\n      if (baseline === 0 || current === baseline) return\n\n      const diff = Math.abs(current - baseline) / baseline\n      if (diff > threshold) {\n        warnedRef.current = true\n        console.warn(\n          `[react-streaming-skeletons] CLS risk detected!\\n` +\n            `  Skeleton height : ${Math.round(baseline)}px\\n` +\n            `  Content height  : ${Math.round(current)}px\\n` +\n            `  Shift           : ${Math.round(diff * 100)}% (threshold: ${Math.round(threshold * 100)}%)\\n` +\n            `  Fix: match your <Bone height={...}> values to the resolved content dimensions.`,\n        )\n      }\n    })\n\n    observer.observe(el)\n    return () => observer.disconnect()\n  }, [enabled, threshold])\n\n  return containerRef\n}\n\nexport function SkeletonBoundary({\n  fallback,\n  children,\n  clsThreshold = 0.1,\n}: SkeletonBoundaryProps) {\n  const containerRef = useCLSDetection(isDev, clsThreshold)\n\n  if (isDev) {\n    return (\n      <div ref={containerRef} data-rss-boundary=\"\">\n        <Suspense fallback={fallback}>{children}</Suspense>\n      </div>\n    )\n  }\n\n  return <Suspense fallback={fallback}>{children}</Suspense>\n}\n","'use client'\n\nimport React, { createContext, useContext } from 'react'\nimport type { SkeletonTheme, SkeletonProviderProps } from '../types'\n\nexport const defaultTheme: SkeletonTheme = {\n  color: '#e2e8f0',\n  highlight: '#f8fafc',\n  borderRadius: 4,\n  duration: 1.5,\n  animationDirection: 'ltr',\n  enableAnimation: true,\n}\n\nconst SkeletonContext = createContext<SkeletonTheme>(defaultTheme)\n\nexport function useSkeletonTheme(): SkeletonTheme {\n  return useContext(SkeletonContext)\n}\n\nexport function SkeletonProvider({ theme, children }: SkeletonProviderProps) {\n  const merged: SkeletonTheme = { ...defaultTheme, ...theme }\n\n  return (\n    <SkeletonContext.Provider value={merged}>\n      <div\n        data-rss-provider=\"\"\n        data-rss-direction={merged.animationDirection}\n        {...(!merged.enableAnimation ? { 'data-rss-no-animation': '' } : {})}\n        style={\n          {\n            '--rss-color': merged.color,\n            '--rss-highlight': merged.highlight,\n            '--rss-duration': `${merged.duration}s`,\n          } as React.CSSProperties\n        }\n      >\n        {children}\n      </div>\n    </SkeletonContext.Provider>\n  )\n}\n","import type { ComponentType, FC, ReactElement } from 'react'\n\n/**\n * Co-locate a skeleton with its real component so the two stay in sync.\n *\n * @example\n * export const UserCardSkeleton = defineSkeleton(UserCard, () => (\n *   <div>\n *     <Bone circle width={40} height={40} />\n *     <Bone width=\"60%\" height={20} />\n *   </div>\n * ))\n */\nexport function defineSkeleton<P>(\n  Component: ComponentType<P>,\n  render: () => ReactElement,\n): FC {\n  const displayName = Component.displayName ?? Component.name ?? 'Component'\n\n  function SkeletonComponent() {\n    return render()\n  }\n\n  SkeletonComponent.displayName = `${displayName}Skeleton`\n  return SkeletonComponent\n}\n"]}

package/dist/index.mjs

@@ -0,0 +1,177 @@
+"use client";
+import { createContext, useEffect, Fragment, Suspense, useContext, useRef } from 'react';
+import { jsx } from 'react/jsx-runtime';
+
+// src/components/Bone.tsx
+
+// src/utils/injectStyles.ts
+var CSS_ID = "rss-styles";
+var SHIMMER_CSS = `
+@keyframes rss-shimmer-ltr {
+  0%   { background-position: -200px 0; }
+  100% { background-position: calc(200px + 100%) 0; }
+}
+@keyframes rss-shimmer-rtl {
+  0%   { background-position: calc(200px + 100%) 0; }
+  100% { background-position: -200px 0; }
+}
+[data-rss-bone] {
+  display: inline-block;
+  line-height: 1;
+  background: linear-gradient(
+    90deg,
+    var(--rss-color, #e2e8f0) 25%,
+    var(--rss-highlight, #f8fafc) 50%,
+    var(--rss-color, #e2e8f0) 75%
+  );
+  background-size: 200px 100%;
+  animation: rss-shimmer-ltr var(--rss-duration, 1.5s) infinite linear;
+}
+[data-rss-direction="rtl"] [data-rss-bone] {
+  animation-name: rss-shimmer-rtl;
+}
+[data-rss-no-animation] [data-rss-bone] {
+  animation: none;
+  background: var(--rss-color, #e2e8f0);
+}
+`;
+function ensureStylesInjected() {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(CSS_ID)) return;
+  const style = document.createElement("style");
+  style.id = CSS_ID;
+  style.textContent = SHIMMER_CSS;
+  document.head.appendChild(style);
+}
+function Bone({
+  width,
+  height,
+  circle = false,
+  rounded = false,
+  className,
+  style,
+  count = 1,
+  inline = false
+}) {
+  useEffect(() => {
+    ensureStylesInjected();
+  }, []);
+  const borderRadius = circle ? "50%" : rounded ? "9999px" : void 0;
+  const baseStyle = {
+    width: width != null ? width : "100%",
+    height: height != null ? height : "1em",
+    borderRadius,
+    display: inline ? "inline-block" : "block",
+    ...style
+  };
+  if (count <= 1) {
+    return /* @__PURE__ */ jsx(
+      "span",
+      {
+        "data-rss-bone": "",
+        className,
+        style: baseStyle,
+        "aria-hidden": "true"
+      }
+    );
+  }
+  return /* @__PURE__ */ jsx(Fragment, { children: Array.from({ length: count }, (_, i) => /* @__PURE__ */ jsx(
+    "span",
+    {
+      "data-rss-bone": "",
+      className,
+      style: {
+        ...baseStyle,
+        marginBottom: i < count - 1 ? "0.5em" : void 0
+      },
+      "aria-hidden": "true"
+    },
+    i
+  )) });
+}
+var isDev = process.env.NODE_ENV === "development";
+function useCLSDetection(enabled, threshold) {
+  const containerRef = useRef(null);
+  const firstHeightRef = useRef(0);
+  const warnedRef = useRef(false);
+  useEffect(() => {
+    if (!enabled || !containerRef.current) return;
+    const el = containerRef.current;
+    firstHeightRef.current = el.getBoundingClientRect().height;
+    const observer = new ResizeObserver(() => {
+      if (warnedRef.current) return;
+      const current = el.getBoundingClientRect().height;
+      const baseline = firstHeightRef.current;
+      if (baseline === 0 || current === baseline) return;
+      const diff = Math.abs(current - baseline) / baseline;
+      if (diff > threshold) {
+        warnedRef.current = true;
+        console.warn(
+          `[react-streaming-skeletons] CLS risk detected!
+  Skeleton height : ${Math.round(baseline)}px
+  Content height  : ${Math.round(current)}px
+  Shift           : ${Math.round(diff * 100)}% (threshold: ${Math.round(threshold * 100)}%)
+  Fix: match your <Bone height={...}> values to the resolved content dimensions.`
+        );
+      }
+    });
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [enabled, threshold]);
+  return containerRef;
+}
+function SkeletonBoundary({
+  fallback,
+  children,
+  clsThreshold = 0.1
+}) {
+  const containerRef = useCLSDetection(isDev, clsThreshold);
+  if (isDev) {
+    return /* @__PURE__ */ jsx("div", { ref: containerRef, "data-rss-boundary": "", children: /* @__PURE__ */ jsx(Suspense, { fallback, children }) });
+  }
+  return /* @__PURE__ */ jsx(Suspense, { fallback, children });
+}
+var defaultTheme = {
+  color: "#e2e8f0",
+  highlight: "#f8fafc",
+  borderRadius: 4,
+  duration: 1.5,
+  animationDirection: "ltr",
+  enableAnimation: true
+};
+var SkeletonContext = createContext(defaultTheme);
+function useSkeletonTheme() {
+  return useContext(SkeletonContext);
+}
+function SkeletonProvider({ theme, children }) {
+  const merged = { ...defaultTheme, ...theme };
+  return /* @__PURE__ */ jsx(SkeletonContext.Provider, { value: merged, children: /* @__PURE__ */ jsx(
+    "div",
+    {
+      "data-rss-provider": "",
+      "data-rss-direction": merged.animationDirection,
+      ...!merged.enableAnimation ? { "data-rss-no-animation": "" } : {},
+      style: {
+        "--rss-color": merged.color,
+        "--rss-highlight": merged.highlight,
+        "--rss-duration": `${merged.duration}s`
+      },
+      children
+    }
+  ) });
+}
+
+// src/utils/defineSkeleton.ts
+function defineSkeleton(Component, render) {
+  var _a, _b;
+  const displayName = (_b = (_a = Component.displayName) != null ? _a : Component.name) != null ? _b : "Component";
+  function SkeletonComponent() {
+    return render();
+  }
+  SkeletonComponent.displayName = `${displayName}Skeleton`;
+  return SkeletonComponent;
+}
+
+export { Bone, SkeletonBoundary, SkeletonProvider, defaultTheme, defineSkeleton, useSkeletonTheme };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils/injectStyles.ts","../src/components/Bone.tsx","../src/components/SkeletonBoundary.tsx","../src/components/SkeletonProvider.tsx","../src/utils/defineSkeleton.ts"],"names":["useEffect","jsx"],"mappings":"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","file":"index.mjs","sourcesContent":["const CSS_ID = 'rss-styles'\n\nconst SHIMMER_CSS = `\n@keyframes rss-shimmer-ltr {\n  0%   { background-position: -200px 0; }\n  100% { background-position: calc(200px + 100%) 0; }\n}\n@keyframes rss-shimmer-rtl {\n  0%   { background-position: calc(200px + 100%) 0; }\n  100% { background-position: -200px 0; }\n}\n[data-rss-bone] {\n  display: inline-block;\n  line-height: 1;\n  background: linear-gradient(\n    90deg,\n    var(--rss-color, #e2e8f0) 25%,\n    var(--rss-highlight, #f8fafc) 50%,\n    var(--rss-color, #e2e8f0) 75%\n  );\n  background-size: 200px 100%;\n  animation: rss-shimmer-ltr var(--rss-duration, 1.5s) infinite linear;\n}\n[data-rss-direction=\"rtl\"] [data-rss-bone] {\n  animation-name: rss-shimmer-rtl;\n}\n[data-rss-no-animation] [data-rss-bone] {\n  animation: none;\n  background: var(--rss-color, #e2e8f0);\n}\n`\n\nexport function ensureStylesInjected(): void {\n  if (typeof document === 'undefined') return\n  if (document.getElementById(CSS_ID)) return\n\n  const style = document.createElement('style')\n  style.id = CSS_ID\n  style.textContent = SHIMMER_CSS\n  document.head.appendChild(style)\n}\n","'use client'\n\nimport React, { useEffect, Fragment } from 'react'\nimport { ensureStylesInjected } from '../utils/injectStyles'\nimport type { BoneProps } from '../types'\n\nexport function Bone({\n  width,\n  height,\n  circle = false,\n  rounded = false,\n  className,\n  style,\n  count = 1,\n  inline = false,\n}: BoneProps) {\n  useEffect(() => {\n    ensureStylesInjected()\n  }, [])\n\n  const borderRadius: string | undefined =\n    circle ? '50%' : rounded ? '9999px' : undefined\n\n  const baseStyle: React.CSSProperties = {\n    width: width ?? '100%',\n    height: height ?? '1em',\n    borderRadius,\n    display: inline ? 'inline-block' : 'block',\n    ...style,\n  }\n\n  if (count <= 1) {\n    return (\n      <span\n        data-rss-bone=\"\"\n        className={className}\n        style={baseStyle}\n        aria-hidden=\"true\"\n      />\n    )\n  }\n\n  return (\n    <Fragment>\n      {Array.from({ length: count }, (_, i) => (\n        <span\n          key={i}\n          data-rss-bone=\"\"\n          className={className}\n          style={{\n            ...baseStyle,\n            marginBottom: i < count - 1 ? '0.5em' : undefined,\n          }}\n          aria-hidden=\"true\"\n        />\n      ))}\n    </Fragment>\n  )\n}\n","'use client'\n\nimport React, { Suspense, useRef, useEffect } from 'react'\nimport type { SkeletonBoundaryProps } from '../types'\n\nconst isDev = process.env.NODE_ENV === 'development'\n\nfunction useCLSDetection(enabled: boolean, threshold: number) {\n  const containerRef = useRef<HTMLDivElement>(null)\n  const firstHeightRef = useRef(0)\n  const warnedRef = useRef(false)\n\n  useEffect(() => {\n    if (!enabled || !containerRef.current) return\n\n    const el = containerRef.current\n    firstHeightRef.current = el.getBoundingClientRect().height\n\n    const observer = new ResizeObserver(() => {\n      if (warnedRef.current) return\n\n      const current = el.getBoundingClientRect().height\n      const baseline = firstHeightRef.current\n\n      if (baseline === 0 || current === baseline) return\n\n      const diff = Math.abs(current - baseline) / baseline\n      if (diff > threshold) {\n        warnedRef.current = true\n        console.warn(\n          `[react-streaming-skeletons] CLS risk detected!\\n` +\n            `  Skeleton height : ${Math.round(baseline)}px\\n` +\n            `  Content height  : ${Math.round(current)}px\\n` +\n            `  Shift           : ${Math.round(diff * 100)}% (threshold: ${Math.round(threshold * 100)}%)\\n` +\n            `  Fix: match your <Bone height={...}> values to the resolved content dimensions.`,\n        )\n      }\n    })\n\n    observer.observe(el)\n    return () => observer.disconnect()\n  }, [enabled, threshold])\n\n  return containerRef\n}\n\nexport function SkeletonBoundary({\n  fallback,\n  children,\n  clsThreshold = 0.1,\n}: SkeletonBoundaryProps) {\n  const containerRef = useCLSDetection(isDev, clsThreshold)\n\n  if (isDev) {\n    return (\n      <div ref={containerRef} data-rss-boundary=\"\">\n        <Suspense fallback={fallback}>{children}</Suspense>\n      </div>\n    )\n  }\n\n  return <Suspense fallback={fallback}>{children}</Suspense>\n}\n","'use client'\n\nimport React, { createContext, useContext } from 'react'\nimport type { SkeletonTheme, SkeletonProviderProps } from '../types'\n\nexport const defaultTheme: SkeletonTheme = {\n  color: '#e2e8f0',\n  highlight: '#f8fafc',\n  borderRadius: 4,\n  duration: 1.5,\n  animationDirection: 'ltr',\n  enableAnimation: true,\n}\n\nconst SkeletonContext = createContext<SkeletonTheme>(defaultTheme)\n\nexport function useSkeletonTheme(): SkeletonTheme {\n  return useContext(SkeletonContext)\n}\n\nexport function SkeletonProvider({ theme, children }: SkeletonProviderProps) {\n  const merged: SkeletonTheme = { ...defaultTheme, ...theme }\n\n  return (\n    <SkeletonContext.Provider value={merged}>\n      <div\n        data-rss-provider=\"\"\n        data-rss-direction={merged.animationDirection}\n        {...(!merged.enableAnimation ? { 'data-rss-no-animation': '' } : {})}\n        style={\n          {\n            '--rss-color': merged.color,\n            '--rss-highlight': merged.highlight,\n            '--rss-duration': `${merged.duration}s`,\n          } as React.CSSProperties\n        }\n      >\n        {children}\n      </div>\n    </SkeletonContext.Provider>\n  )\n}\n","import type { ComponentType, FC, ReactElement } from 'react'\n\n/**\n * Co-locate a skeleton with its real component so the two stay in sync.\n *\n * @example\n * export const UserCardSkeleton = defineSkeleton(UserCard, () => (\n *   <div>\n *     <Bone circle width={40} height={40} />\n *     <Bone width=\"60%\" height={20} />\n *   </div>\n * ))\n */\nexport function defineSkeleton<P>(\n  Component: ComponentType<P>,\n  render: () => ReactElement,\n): FC {\n  const displayName = Component.displayName ?? Component.name ?? 'Component'\n\n  function SkeletonComponent() {\n    return render()\n  }\n\n  SkeletonComponent.displayName = `${displayName}Skeleton`\n  return SkeletonComponent\n}\n"]}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "react-streaming-skeletons",
+  "version": "0.1.0",
+  "description": "Zero-layout-shift skeleton components for React Suspense streaming and Next.js App Router",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "jest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.4.2",
+    "@testing-library/react": "^15.0.0",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^25.9.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "ts-jest": "^29.2.0",
+    "tsup": "^8.1.0",
+    "typescript": "^5.4.5"
+  },
+  "keywords": [
+    "react",
+    "skeleton",
+    "loading",
+    "streaming",
+    "suspense",
+    "nextjs",
+    "app-router",
+    "cls",
+    "layout-shift",
+    "server-components"
+  ],
+  "author": "Mehulbirare",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Mehulbirare/react-streaming-skeletons"
+  }
+}