@planetaexo/design-system 0.54.0 → 0.54.1

package/dist/index.d.cts

@@ -2428,18 +2428,52 @@ interface PictureProps extends React.ImgHTMLAttributes<HTMLImageElement> {
      * AVIF, art-direction, etc. Render order = priority.
      */
     extraSources?: React.ReactNode;
+    /**
+     * Disable lazy loading. Use for LCP (hero, first card above the fold)
+     * so the browser starts the request immediately instead of waiting for
+     * the IntersectionObserver to fire.
+     * @default false
+     */
+    eager?: boolean;
+    /**
+     * How far before the image enters the viewport to start loading.
+     * Matches WP-Rocket's "Load images on visible viewport" — anything
+     * within `rootMargin` triggers the swap. @default "200px"
+     */
+    rootMargin?: string;
 }
 /**
- * `<img>` with a transparent WebP `<source>` wrapper.
+ * `<img>` with a transparent WebP `<source>` wrapper AND
+ * IntersectionObserver-based lazy load (WP-Rocket style).
+ *
+ * Behavior:
+ *   - SSR / first paint: the `<img>` renders a 1×1 transparent placeholder
+ *     in `src`; the real URL lives in `data-src`. The `<source srcset>` is
+ *     only emitted once the image enters the viewport — so no network
+ *     request fires for off-screen images, period.
+ *   - On mount: an `IntersectionObserver` watches with
+ *     `rootMargin: 200px` (configurable). When the placeholder gets within
+ *     200px of the viewport, state flips and the component re-renders
+ *     with the real `src` (+ WebP `<source>` if eligible). The browser
+ *     decodes asynchronously thanks to `decoding="async"`.
+ *   - Pass `eager` to skip the observer entirely — required for LCP
+ *     images (hero, above-the-fold cards). Eager renders the real URL
+ *     synchronously.
  *
- * Drop-in replacement for `<img>`. For sources that aren't WebP-eligible
- * (SVG, GIF, base64), the `<picture>` wrapper is skipped and we render
- * the plain `<img>` — saves a useless `<picture>` element in the markup.
+ * Why not just `loading="lazy"`?
+ *   Native `loading="lazy"` is honored by modern browsers but the
+ *   threshold isn't tunable (Chromium loads at ~3 viewports out, Firefox
+ *   at the next page). WP-Rocket's appeal is the predictable, small
+ *   `rootMargin` — 200px feels much more "just in time", saves more
+ *   bandwidth on long pages, and tests cleanly via DevTools network throttling.
  *
- * Intentionally lightweight: no probing, no fetch, no preload. The
- * browser's native `<picture>` resolver does the right thing for free.
+ * SSR safety:
+ *   Marked `"use client"` because of the observer. The first render
+ *   (server + client hydration) emits the placeholder; the swap happens
+ *   one effect tick later. Hydration mismatch is impossible because both
+ *   sides start from `visible = eager`.
  */
-declare function Picture({ src, extraSources, ...imgProps }: PictureProps): react_jsx_runtime.JSX.Element;
+declare function Picture({ src, extraSources, eager, rootMargin, decoding, loading, ...imgProps }: PictureProps): react_jsx_runtime.JSX.Element;
 
 /**
  * WebP-fallback helpers for components that render content-image URLs.

package/dist/index.d.ts

@@ -2428,18 +2428,52 @@ interface PictureProps extends React.ImgHTMLAttributes<HTMLImageElement> {
      * AVIF, art-direction, etc. Render order = priority.
      */
     extraSources?: React.ReactNode;
+    /**
+     * Disable lazy loading. Use for LCP (hero, first card above the fold)
+     * so the browser starts the request immediately instead of waiting for
+     * the IntersectionObserver to fire.
+     * @default false
+     */
+    eager?: boolean;
+    /**
+     * How far before the image enters the viewport to start loading.
+     * Matches WP-Rocket's "Load images on visible viewport" — anything
+     * within `rootMargin` triggers the swap. @default "200px"
+     */
+    rootMargin?: string;
 }
 /**
- * `<img>` with a transparent WebP `<source>` wrapper.
+ * `<img>` with a transparent WebP `<source>` wrapper AND
+ * IntersectionObserver-based lazy load (WP-Rocket style).
+ *
+ * Behavior:
+ *   - SSR / first paint: the `<img>` renders a 1×1 transparent placeholder
+ *     in `src`; the real URL lives in `data-src`. The `<source srcset>` is
+ *     only emitted once the image enters the viewport — so no network
+ *     request fires for off-screen images, period.
+ *   - On mount: an `IntersectionObserver` watches with
+ *     `rootMargin: 200px` (configurable). When the placeholder gets within
+ *     200px of the viewport, state flips and the component re-renders
+ *     with the real `src` (+ WebP `<source>` if eligible). The browser
+ *     decodes asynchronously thanks to `decoding="async"`.
+ *   - Pass `eager` to skip the observer entirely — required for LCP
+ *     images (hero, above-the-fold cards). Eager renders the real URL
+ *     synchronously.
  *
- * Drop-in replacement for `<img>`. For sources that aren't WebP-eligible
- * (SVG, GIF, base64), the `<picture>` wrapper is skipped and we render
- * the plain `<img>` — saves a useless `<picture>` element in the markup.
+ * Why not just `loading="lazy"`?
+ *   Native `loading="lazy"` is honored by modern browsers but the
+ *   threshold isn't tunable (Chromium loads at ~3 viewports out, Firefox
+ *   at the next page). WP-Rocket's appeal is the predictable, small
+ *   `rootMargin` — 200px feels much more "just in time", saves more
+ *   bandwidth on long pages, and tests cleanly via DevTools network throttling.
  *
- * Intentionally lightweight: no probing, no fetch, no preload. The
- * browser's native `<picture>` resolver does the right thing for free.
+ * SSR safety:
+ *   Marked `"use client"` because of the observer. The first render
+ *   (server + client hydration) emits the placeholder; the swap happens
+ *   one effect tick later. Hydration mismatch is impossible because both
+ *   sides start from `visible = eager`.
  */
-declare function Picture({ src, extraSources, ...imgProps }: PictureProps): react_jsx_runtime.JSX.Element;
+declare function Picture({ src, extraSources, eager, rootMargin, decoding, loading, ...imgProps }: PictureProps): react_jsx_runtime.JSX.Element;
 
 /**
  * WebP-fallback helpers for components that render content-image URLs.