@decocms/apps 0.21.4 → 0.22.0

package/commerce/components/Image.tsx

@@ -1,4 +1,5 @@
 import type { ImgHTMLAttributes } from "react";
+import { forwardRef } from "react";
 
 // -------------------------------------------------------------------------
 // Known asset prefixes that get stripped to produce a relative src path
@@ -34,7 +35,7 @@ export function getImageCdnDomain(): string {
 // Fit options & optimization types
 // -------------------------------------------------------------------------
 
-export type FitOptions = "contain" | "cover";
+export type FitOptions = "contain" | "cover" | "fill";
 
 export const FACTORS = [1, 2];
 
@@ -163,92 +164,77 @@ export interface ImageProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "s
   height?: number;
   /** @description Object-fit */
   fit?: FitOptions;
-  /** @description Preload the image (adds fetchPriority="high") */
+  /**
+   * @description Web Vitals (LCP). Injects a `<link rel="preload">` tag
+   * alongside the `<img>`, sets `fetchPriority="high"` and `loading="eager"`.
+   * Use once per page for the LCP image.
+   */
   preload?: boolean;
+  /** @description Media query for responsive preloading (e.g. "(min-width: 768px)") */
+  media?: string;
 }
 
-export function Image({
-  src,
-  width,
-  height,
-  fit = "cover",
-  preload,
-  loading,
-  decoding,
-  srcSet: srcSetProp,
-  sizes,
-  ...rest
-}: ImageProps) {
-  if (!height && typeof process !== "undefined") {
-    console.warn(`Missing height. This image will NOT be optimized: ${src}`);
-  }
-
-  const srcSet = srcSetProp ?? getSrcSet(src, width, height, fit);
-
-  return (
-    <img
-      {...rest}
-      src={src}
-      srcSet={srcSet}
-      sizes={srcSet ? (sizes ?? "(max-width: 768px) 100vw, 50vw") : undefined}
-      width={width}
-      height={height}
-      loading={loading ?? (preload ? "eager" : "lazy")}
-      decoding={decoding ?? "async"}
-      fetchPriority={preload ? "high" : undefined}
-    />
-  );
-}
-
-// -------------------------------------------------------------------------
-// Picture (responsive art direction)
-// -------------------------------------------------------------------------
-
-export interface PictureSourceProps {
-  src: string;
-  width: number;
-  height?: number;
-  media: string;
-  fit?: FitOptions;
-}
-
-export interface PictureProps extends Omit<ImageProps, "sizes"> {
-  sources: PictureSourceProps[];
-}
+export const Image = forwardRef<HTMLImageElement, ImageProps>(
+  function Image(
+    {
+      src,
+      width,
+      height,
+      fit = "cover",
+      preload,
+      media,
+      loading,
+      decoding,
+      srcSet: srcSetProp,
+      sizes,
+      fetchPriority,
+      ...rest
+    },
+    ref,
+  ) {
+    if (!height && typeof process !== "undefined") {
+      console.warn(`Missing height. This image will NOT be optimized: ${src}`);
+    }
 
-export function Picture({
-  sources,
-  src,
-  width,
-  height,
-  fit = "cover",
-  preload,
-  ...rest
-}: PictureProps) {
-  return (
-    <picture>
-      {sources.map((source, i) => {
-        const srcSet = getSrcSet(source.src, source.width, source.height, source.fit ?? fit);
-        return (
-          <source
-            key={i}
-            srcSet={srcSet}
-            media={source.media}
-            width={source.width}
-            height={source.height}
+    const optimizedSrc = getOptimizedMediaUrl({
+      originalSrc: src,
+      width,
+      height,
+      fit,
+    });
+    const srcSet = srcSetProp ?? getSrcSet(src, width, height, fit);
+    const resolvedSizes = srcSet
+      ? (sizes ?? "(max-width: 768px) 100vw, 50vw")
+      : undefined;
+
+    return (
+      <>
+        {preload && (
+          <link
+            as="image"
+            rel="preload"
+            href={optimizedSrc}
+            imageSrcSet={srcSet}
+            imageSizes={resolvedSizes}
+            fetchPriority={fetchPriority ?? "high"}
+            media={media}
           />
-        );
-      })}
-      <Image
-        src={src}
-        width={width}
-        height={height}
-        fit={fit}
-        preload={preload}
-        {...rest}
-      />
-    </picture>
-  );
-}
+        )}
+        <img
+          {...rest}
+          src={optimizedSrc}
+          srcSet={srcSet}
+          sizes={resolvedSizes}
+          width={width}
+          height={height}
+          loading={loading ?? (preload ? "eager" : "lazy")}
+          decoding={decoding ?? "async"}
+          fetchPriority={preload ? "high" : fetchPriority}
+          ref={ref}
+        />
+      </>
+    );
+  },
+);
 
 export default Image;

package/commerce/components/Picture.tsx

@@ -0,0 +1,114 @@
+import {
+  createContext,
+  forwardRef,
+  useContext,
+  useMemo,
+  type ComponentPropsWithoutRef,
+  type ReactNode,
+} from "react";
+import { getOptimizedMediaUrl, getSrcSet, type FitOptions } from "./Image";
+
+// -------------------------------------------------------------------------
+// Preload context — flows from <Picture preload> to child <Source> elements
+// so each source can inject its own <link rel="preload"> with the correct
+// media query for responsive art direction.
+// -------------------------------------------------------------------------
+
+interface PreloadContextValue {
+  preload: boolean;
+}
+
+const PreloadContext = createContext<PreloadContextValue>({ preload: false });
+
+// -------------------------------------------------------------------------
+// Source — composable <source> with automatic srcSet optimization and
+// preload link injection when inside a <Picture preload>.
+// -------------------------------------------------------------------------
+
+export type SourceProps = Omit<
+  ComponentPropsWithoutRef<"source">,
+  "width" | "height"
+> & {
+  src: string;
+  /** @description Improves Web Vitals (CLS|LCP) */
+  width: number;
+  /** @description Improves Web Vitals (CLS|LCP) */
+  height?: number;
+  /** @description Improves Web Vitals (LCP). Use high for LCP image. */
+  fetchPriority?: "high" | "low" | "auto";
+  /** @description Object-fit */
+  fit?: FitOptions;
+};
+
+export const Source = forwardRef<HTMLSourceElement, SourceProps>(
+  function Source(
+    { src, width, height, fetchPriority, fit = "cover", ...rest },
+    ref,
+  ) {
+    const { preload } = useContext(PreloadContext);
+
+    const optimizedSrc = getOptimizedMediaUrl({
+      originalSrc: src,
+      width,
+      height,
+      fit,
+    });
+    const srcSet = rest.srcSet ?? getSrcSet(src, width, height, fit);
+
+    return (
+      <>
+        {preload && (
+          <link
+            as="image"
+            rel="preload"
+            href={optimizedSrc}
+            imageSrcSet={srcSet}
+            fetchPriority={fetchPriority ?? "high"}
+            media={rest.media}
+          />
+        )}
+        <source
+          {...rest}
+          srcSet={srcSet ?? optimizedSrc}
+          width={width}
+          height={height}
+          ref={ref}
+        />
+      </>
+    );
+  },
+);
+
+// -------------------------------------------------------------------------
+// Picture — composable wrapper that provides preload context to children.
+//
+// Usage:
+//   <Picture preload={isLcp}>
+//     <Source media="(max-width: 767px)" src={mobile} width={320} height={280} />
+//     <Source media="(min-width: 768px)" src={desktop} width={1280} height={280} />
+//     <Image src={desktop} width={1280} height={280} />
+//   </Picture>
+// -------------------------------------------------------------------------
+
+export type PictureProps = ComponentPropsWithoutRef<"picture"> & {
+  children: ReactNode;
+  /**
+   * @description When true, child <Source> and <Image> elements inject
+   * `<link rel="preload">` tags for their respective media queries.
+   */
+  preload?: boolean;
+};
+
+export const Picture = forwardRef<HTMLPictureElement, PictureProps>(
+  function Picture({ children, preload = false, ...props }, ref) {
+    const value = useMemo(() => ({ preload }), [preload]);
+
+    return (
+      <PreloadContext.Provider value={value}>
+        <picture {...props} ref={ref}>
+          {children}
+        </picture>
+      </PreloadContext.Provider>
+    );
+  },
+);

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@decocms/apps",
-  "version": "0.21.4",
+  "version": "0.22.0",
   "type": "module",
   "description": "Deco commerce apps for TanStack Start - Shopify, VTEX, commerce types, analytics utils",
   "exports": {
     "./commerce/types": "./commerce/types/commerce.ts",
     "./commerce/components/JsonLd": "./commerce/components/JsonLd.tsx",
     "./commerce/components/Image": "./commerce/components/Image.tsx",
+    "./commerce/components/Picture": "./commerce/components/Picture.tsx",
     "./commerce/utils/*": "./commerce/utils/*.ts",
     "./commerce/sdk/*": "./commerce/sdk/*.ts",
     "./shopify": "./shopify/index.ts",