@planetaexo/design-system 0.54.0 → 0.55.0

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.
@@ -3040,6 +3074,15 @@ declare function TripPage({ title, tagline, destination, duration, images, video
 interface Category2Trip extends TripCardProps {
     /** Marca a trip como featured — sobe para o topo do grid principal. */
     featured?: boolean;
+    /**
+     * Per-group filter membership — `{ groupId: [optionId, …] }`, where the ids
+     * match the `filterGroups` option ids. A trip is kept when, for every active
+     * filter group, its ids intersect the selected option(s). Groups that no trip
+     * carries data for stay display-only (selecting them doesn't filter).
+     */
+    filterTags?: Record<string, string[]>;
+    /** Numeric price driving the price sort (the display string stays in `price`). */
+    priceValue?: number;
 }
 interface Category2BlogPost {
     title: string;
@@ -3071,8 +3114,12 @@ interface CategoryPage2Props {
         label: string;
         href?: string;
     }>;
-    /** Pass true (or a links array) to render the transparent SiteHeader over the hero. */
-    siteHeader?: boolean | SiteHeaderLink[];
+    /**
+     * Render the overlay SiteHeader inside the hero. Pass `true` for the default
+     * header, a `SiteHeaderLink[]` for custom links, or a full
+     * {@link TripSiteHeaderConfig} to wire languages + onLanguageChange.
+     */
+    siteHeader?: boolean | SiteHeaderLink[] | TripSiteHeaderConfig;
     popularTours?: Category2Trip[];
     popularToursTitle?: string;
     popularToursEyebrow?: string;

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.
@@ -3040,6 +3074,15 @@ declare function TripPage({ title, tagline, destination, duration, images, video
 interface Category2Trip extends TripCardProps {
     /** Marca a trip como featured — sobe para o topo do grid principal. */
     featured?: boolean;
+    /**
+     * Per-group filter membership — `{ groupId: [optionId, …] }`, where the ids
+     * match the `filterGroups` option ids. A trip is kept when, for every active
+     * filter group, its ids intersect the selected option(s). Groups that no trip
+     * carries data for stay display-only (selecting them doesn't filter).
+     */
+    filterTags?: Record<string, string[]>;
+    /** Numeric price driving the price sort (the display string stays in `price`). */
+    priceValue?: number;
 }
 interface Category2BlogPost {
     title: string;
@@ -3071,8 +3114,12 @@ interface CategoryPage2Props {
         label: string;
         href?: string;
     }>;
-    /** Pass true (or a links array) to render the transparent SiteHeader over the hero. */
-    siteHeader?: boolean | SiteHeaderLink[];
+    /**
+     * Render the overlay SiteHeader inside the hero. Pass `true` for the default
+     * header, a `SiteHeaderLink[]` for custom links, or a full
+     * {@link TripSiteHeaderConfig} to wire languages + onLanguageChange.
+     */
+    siteHeader?: boolean | SiteHeaderLink[] | TripSiteHeaderConfig;
     popularTours?: Category2Trip[];
     popularToursTitle?: string;
     popularToursEyebrow?: string;