New Image component

.changeset/five-chefs-heal.md

@@ -0,0 +1,5 @@
+---
+'@shopify/hydrogen-react': patch
+---
+
+Adds an all-new responsive Image component

packages/hydrogen-react/src/Image.doc.ts

@@ -12,7 +12,7 @@ const data: ReferenceEntityTemplateSchema = {
     },
   ],
   description:
-    "The `Image` component renders an image for the Storefront API's\n[Image object](https://shopify.dev/api/storefront/reference/common-objects/image) by using the `data` prop. You can [customize this component](https://shopify.dev/api/hydrogen/components#customizing-hydrogen-components) using passthrough props.\n\nAn image's width and height are determined using the following priority list:\n1. The width and height values for the `loaderOptions` prop\n2. The width and height values for bare props\n3. The width and height values for the `data` prop\n\nIf only one of `width` or `height` are defined, then the other will attempt to be calculated based on the image's aspect ratio,\nprovided that both `data.width` and `data.height` are available. If `data.width` and `data.height` aren't available, then the aspect ratio cannot be determined and the missing value will remain as `null`",
+    "The `Image` component renders an image for the Storefront API's\n[Image object](https://shopify.dev/api/storefront/reference/common-objects/image) by using the `data` prop. You can [customize this component](https://shopify.dev/api/hydrogen/components#customizing-hydrogen-components) using passthrough props.\n\nImages default to being responsive automativally (`width: 100%, height: auto`), and expect an `aspectRatio` prop, which ensures your image doesn't create any layout shift. For fixed-size images, you can set `width` to an exact value, and a `srcSet` with 1x, 2x, and 3x DPI variants will automatically be generated for you.",
   type: 'component',
   defaultExample: {
     description: 'I am the default example',

packages/hydrogen-react/src/Image.example.jsx

@@ -1,4 +1,16 @@
-import {Image} from '@shopify/hydrogen-react';
+import {Image, IMAGE_FRAGMENT} from '@shopify/hydrogen-react';
+
+// An example query that includes the image fragment
+const IMAGE_QUERY = `#graphql
+  ${IMAGE_FRAGMENT}
+  query {
+    product {
+      featuredImage {
+        ...Image
+      }
+    }
+  }
+`;
 
 export default function ProductImage({product}) {
   const image = product.featuredImage;
@@ -7,5 +19,11 @@ export default function ProductImage({product}) {
     return null;
   }
 
-  return <Image data={image} />;
+  return (
+    <Image
+      data={image}
+      sizes="(min-width: 45em) 50vw, 100vw"
+      aspectRatio="4/5"
+    />
+  );
 }

packages/hydrogen-react/src/Image.example.tsx

@@ -1,12 +1,31 @@
-import {Image} from '@shopify/hydrogen-react';
+import React from 'react';
+import {Image, IMAGE_FRAGMENT} from '@shopify/hydrogen-react';
 import type {Product} from '@shopify/hydrogen-react/storefront-api-types';
 
+// An example query that includes the image fragment
+const IMAGE_QUERY = `#graphql
+  ${IMAGE_FRAGMENT}
+  query {
+    product {
+      featuredImage {
+        ...Image
+      }
+    }
+  }
+`;
+
 export default function ProductImage({product}: {product: Product}) {
   const image = product.featuredImage;
 
   if (!image) {
     return null;
   }
 
-  return <Image data={image} />;
+  return (
+    <Image
+      data={image}
+      sizes="(min-width: 45em) 50vw, 100vw"
+      aspectRatio="4/5"
+    />
+  );
 }

packages/hydrogen-react/src/Image.stories.tsx

@@ -1,45 +1,82 @@
 import * as React from 'react';
 import type {Story} from '@ladle/react';
-import {Image, type ShopifyImageProps} from './Image.js';
-import {IMG_SRC_SET_SIZES} from './image-size.js';
+import {Image, ShopifyLoaderOptions, LoaderParams} from './Image.js';
+import type {PartialDeep} from 'type-fest';
+import type {Image as ImageType} from './storefront-api-types.js';
+
+type Crop = 'center' | 'top' | 'bottom' | 'left' | 'right';
+
+type ImageConfig = {
+  intervals: number;
+  startingWidth: number;
+  incrementSize: number;
+  placeholderWidth: number;
+};
+
+type HtmlImageProps = React.ImgHTMLAttributes<HTMLImageElement>;
 
 const Template: Story<{
-  'data.url': ShopifyImageProps['data']['url'];
-  'data.width': ShopifyImageProps['data']['width'];
-  'data.height': ShopifyImageProps['data']['height'];
-  width: ShopifyImageProps['width'];
-  height: ShopifyImageProps['height'];
-  widths: ShopifyImageProps['widths'];
-  loaderOptions: ShopifyImageProps['loaderOptions'];
+  as?: 'img' | 'source';
+  data?: PartialDeep<ImageType, {recurseIntoArrays: true}>;
+  loader?: (params: LoaderParams) => string;
+  src: string;
+  width?: string | number;
+  height?: string | number;
+  crop?: Crop;
+  sizes?: string;
+  aspectRatio?: string;
+  config?: ImageConfig;
+  alt?: string;
+  loading?: 'lazy' | 'eager';
+  loaderOptions?: ShopifyLoaderOptions;
+  widths?: (HtmlImageProps['width'] | ImageType['width'])[];
 }> = (props) => {
-  const finalProps: ShopifyImageProps = {
-    data: {
-      url: props['data.url'],
-      width: props['data.width'],
-      height: props['data.height'],
-      id: 'testing',
-    },
-    width: props.width,
-    height: props.height,
-    widths: props.widths,
-    loaderOptions: props.loaderOptions,
-  };
-  return <Image {...finalProps} />;
+  return (
+    <>
+      {/* Standard Usage */}
+      <Image
+        {...props}
+        width="100%"
+        loading="eager"
+        aspectRatio="1/1"
+        sizes="100vw"
+      />
+      {/*  */}
+      <Image
+        {...props}
+        src="https://cdn.shopify.com/s/files/1/0551/4566/0472/products/Main.jpg"
+        width="100%"
+        aspectRatio="1/1"
+        sizes="100vw"
+      />
+      <Image {...props} sizes="50vw" width="50vw" />
+      <Image {...props} aspectRatio="4/3" width="50vw" sizes="50vw" />
+      <Image {...props} width="30vw" sizes="30vw" />
+      <Image {...props} width={100} height={200} />
+      <Image {...props} width="5rem" />
+      <Image {...props} widths={[100, 200, 300]} />
+      <Image
+        {...props}
+        loaderOptions={{
+          crop: 'center',
+        }}
+        widths={[200, 300]}
+      />
+      <Image
+        sizes="100vw"
+        src="https://cdn.shopify.com/s/files/1/0551/4566/0472/products/Main.jpg"
+        widths={[100, 200, 300]}
+      />
+    </>
+  );
 };
 
 export const Default = Template.bind({});
 Default.args = {
-  'data.url':
-    'https://cdn.shopify.com/s/files/1/0551/4566/0472/products/Main.jpg',
-  'data.width': 100,
-  'data.height': 100,
-  width: 500,
-  height: 500,
-  widths: IMG_SRC_SET_SIZES,
-  loaderOptions: {
-    crop: 'center',
-    scale: 2,
-    width: 500,
-    height: 500,
+  data: {
+    url: 'https://cdn.shopify.com/s/files/1/0551/4566/0472/products/Main.jpg',
+    altText: 'alt text',
+    width: 3908,
+    height: 3908,
   },
 };