gantri-components 2.251.1 → 2.252.1

package/dist/components/picture/__test__/infer-sizes-from-width.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/picture/helpers/index.d.ts

@@ -3,3 +3,4 @@ export * from './build-cloudinary-url';
 export * from './build-srcset';
 export * from './build-placeholder';
 export * from './normalize-resolution-aware';
+export * from './infer-sizes-from-width';

package/dist/components/picture/helpers/infer-sizes-from-width.d.ts

@@ -0,0 +1,21 @@
+import { NormalizedResolutionAware } from './normalize-resolution-aware';
+/**
+ * Build a `sizes` attribute string from a normalized `width` map so
+ * `<Picture width={...} />` doesn't need a hand-written `sizes`. The
+ * browser uses `sizes` together with each `<source>`'s `srcset` to pick
+ * a single variant per DPR — without an accurate value it defaults to
+ * `100vw` and over-fetches on small containers (e.g. a 400-px desktop
+ * card pulling the 1200w variant instead of 800w).
+ *
+ *   width=400                          → "400px"
+ *   width={{ lg: 400, sm: 720 }}       → "(max-width: 720px) 720px, 400px"
+ *   width={{ lg: 400, md: 600, sm: 720 }} →
+ *     "(max-width: 720px) 720px, (max-width: 1024px) 600px, 400px"
+ *   width=undefined                    → undefined (caller should fall
+ *                                        back to the default `100vw`)
+ *
+ * When a breakpoint has no explicit width, we substitute `100vw` for
+ * that segment so the inferred string never silently invents a desktop
+ * size from a sm-only spec.
+ */
+export declare const inferSizesFromWidth: (widths: NormalizedResolutionAware<number>) => string | undefined;

package/dist/components/picture/picture.types.d.ts

@@ -29,6 +29,12 @@ export interface PictureProps extends PicturePassThroughProps {
     alt: string;
     /** Override auto-detection of how to render the asset. */
     as?: PictureAs;
+    /**
+     * Target render width in px. Drives **both** the container CSS width
+     * AND the Cloudinary srcset (DPR multipliers `1x / 2x / 3x` of this
+     * value). Use it alongside `fill` to keep the parent-driven layout
+     * while still capping the source bytes the browser fetches.
+     */
     width?: ResolutionAwareProp<number>;
     height?: ResolutionAwareProp<number>;
     /** e.g. "16:9", "1:1". Drives both CSS aspect-ratio and Cloudinary ar_ transformation. */
@@ -41,7 +47,19 @@ export interface PictureProps extends PicturePassThroughProps {
     minWidth?: ResolutionAwareProp<Property.MinWidth>;
     /** CSS min-height on the container. */
     minHeight?: ResolutionAwareProp<Property.MinHeight>;
-    /** Image fills its (position: relative) parent. Mutually exclusive with width/height. */
+    /**
+     * Image fills its (`position: relative`) parent — CSS-wise the container
+     * becomes `position: absolute; inset: 0; width/height: 100%`, so the
+     * configured `width` / `height` props are ignored for layout.
+     *
+     * `width` is still honored as a **render hint for srcset**: when set
+     * alongside `fill`, the srcset is built from DPR multipliers
+     * `[width × 1, width × 2, width × 3]` instead of the default
+     * `[320, 640, 1024, 1600, 2400]`. Pair `<Picture fill width={400} />`
+     * (with `sizes="400px"` for accuracy) on a 400-px container so the
+     * browser fetches an 800-px source on Retina instead of the 1024 it
+     * would pick from the default set.
+     */
     fill?: boolean;
     /** Native sizes attribute. Default: "100vw". Tells the browser how wide the image renders. */
     sizes?: string;