feat(core): enable product image pagination (#2863)

* feat(core): enable product image pagination

* feat: infinite gallery, no thumbnail

* fix: infinite scroll in thumbnail scroll

* fix: retains scroll position

* fix: infinite scroll fix

* fix: change product image to 12 per page

* fix: remove label prop

* fix: update loading animation

* fix: add accessbility

* chore: update changeset

* fix: merge steamable functions

* fix: update changeset

* fix: remove @ts-expect-errors

* fix: non-nullable assertion

Author: jorgemoya

.changeset/mighty-zebras-turn.md

@@ -0,0 +1,20 @@
+---
+"@bigcommerce/catalyst-core": minor
+---
+
+Add pagination support for the product gallery. When a product has more images than the initial page load, new images will load as batches once the user reaches the end of the existing thumbnails. Thumbnail images now will display in horizontal direction in all viewport sizes.
+
+## Migration
+
+1. Create the new server action file `core/app/[locale]/(default)/product/[slug]/_actions/get-more-images.ts` with a GraphQL query to fetch additional product images with pagination.
+
+2. Update the product page data fetching in `core/app/[locale]/(default)/product/[slug]/page-data.ts` to include `pageInfo` (with `hasNextPage` and `endCursor`) from the images query.
+
+3. Update `core/app/[locale]/(default)/product/[slug]/page.tsx` to pass the new pagination props (`pageInfo`, `productId`, `loadMoreAction`) to the `ProductDetail` component.
+
+4. The `ProductGallery` component now accepts optional props for pagination:
+   - `pageInfo?: { hasNextPage: boolean; endCursor: string | null }`
+   - `productId?: number`
+   - `loadMoreAction?: ProductGalleryLoadMoreAction`
+
+Due to the number of changes, it is recommended to use the PR as a reference for migration.

core/app/[locale]/(default)/product/[slug]/_actions/get-more-images.ts

@@ -0,0 +1,54 @@
+'use server';
+
+import { removeEdgesAndNodes } from '@bigcommerce/catalyst-client';
+
+import { getSessionCustomerAccessToken } from '~/auth';
+import { client } from '~/client';
+import { graphql } from '~/client/graphql';
+import { revalidate } from '~/client/revalidate-target';
+
+const MoreProductImagesQuery = graphql(`
+  query MoreProductImagesQuery($entityId: Int!, $first: Int!, $after: String!) {
+    site {
+      product(entityId: $entityId) {
+        images(first: $first, after: $after) {
+          pageInfo {
+            hasNextPage
+            endCursor
+          }
+          edges {
+            node {
+              altText
+              url: urlTemplate(lossy: true)
+            }
+          }
+        }
+      }
+    }
+  }
+`);
+
+export async function getMoreProductImages(
+  productId: number,
+  cursor: string,
+  limit = 12,
+): Promise<{
+  images: Array<{ src: string; alt: string }>;
+  pageInfo: { hasNextPage: boolean; endCursor: string | null };
+}> {
+  const customerAccessToken = await getSessionCustomerAccessToken();
+
+  const { data } = await client.fetch({
+    document: MoreProductImagesQuery,
+    variables: { entityId: productId, first: limit, after: cursor },
+    customerAccessToken,
+    fetchOptions: customerAccessToken ? { cache: 'no-store' } : { next: { revalidate } },
+  });
+
+  const images = removeEdgesAndNodes(data.site.product?.images ?? { edges: [] });
+
+  return {
+    images: images.map((img) => ({ src: img.url, alt: img.altText })),
+    pageInfo: data.site.product?.images.pageInfo ?? { hasNextPage: false, endCursor: null },
+  };
+}

core/app/[locale]/(default)/product/[slug]/_components/reviews.tsx

@@ -77,7 +77,10 @@ const getReviews = cache(async (productId: number, paginationArgs: object) => {
 interface Props {
   productId: number;
   searchParams: Promise<SearchParams>;
-  streamableImages: Streamable<Array<{ src: string; alt: string }>>;
+  streamableImages: Streamable<{
+    images: Array<{ src: string; alt: string }>;
+    pageInfo?: { hasNextPage: boolean; endCursor: string | null };
+  }>;
   streamableProduct: Streamable<Awaited<ReturnType<typeof getStreamableProduct>>>;
 }
 

core/app/[locale]/(default)/product/[slug]/page-data.ts

@@ -274,7 +274,12 @@ const StreamableProductQuery = graphql(
           optionValueIds: $optionValueIds
           useDefaultOptionSelections: $useDefaultOptionSelections
         ) {
-          images {
+          entityId
+          images(first: 12) {
+            pageInfo {
+              hasNextPage
+              endCursor
+            }
             edges {
               node {
                 altText

core/app/[locale]/(default)/product/[slug]/page.tsx

@@ -14,6 +14,7 @@ import { productOptionsTransformer } from '~/data-transformers/product-options-t
 import { getPreferredCurrencyCode } from '~/lib/currency';
 
 import { addToCart } from './_actions/add-to-cart';
+import { getMoreProductImages } from './_actions/get-more-images';
 import { submitReview } from './_actions/submit-review';
 import { ProductAnalyticsProvider } from './_components/product-analytics-provider';
 import { ProductSchema } from './_components/product-schema';
@@ -182,9 +183,12 @@ export default async function Product({ params, searchParams }: Props) {
         alt: image.altText,
       }));
 
-    return product.defaultImage
-      ? [{ src: product.defaultImage.url, alt: product.defaultImage.altText }, ...images]
-      : images;
+    return {
+      images: product.defaultImage
+        ? [{ src: product.defaultImage.url, alt: product.defaultImage.altText }, ...images]
+        : images,
+      pageInfo: product.images.pageInfo,
+    };
   });
 
   const streameableCtaLabel = Streamable.from(async () => {
@@ -546,6 +550,7 @@ export default async function Product({ params, searchParams }: Props) {
           emptySelectPlaceholder={t('ProductDetails.emptySelectPlaceholder')}
           fields={productOptionsTransformer(baseProduct.productOptions)}
           incrementLabel={t('ProductDetails.increaseQuantity')}
+          loadMoreImagesAction={getMoreProductImages}
           prefetch={true}
           product={{
             id: baseProduct.entityId.toString(),

core/messages/en.json

@@ -463,6 +463,8 @@
       "additionalInformation": "Additional information",
       "currentStock": "{quantity, number} in stock",
       "backorderQuantity": "{quantity, number} will be on backorder",
+      "loadingMoreImages": "Loading more images",
+      "imagesLoaded": "{count, plural, =1 {1 more image loaded} other {# more images loaded}}",
       "Submit": {
         "addToCart": "Add to cart",
         "outOfStock": "Out of stock",

core/package.json

@@ -46,10 +46,10 @@
     "clsx": "^2.1.1",
     "content-security-policy-builder": "^2.3.0",
     "deepmerge": "^4.3.1",
-    "embla-carousel": "8.5.2",
-    "embla-carousel-autoplay": "8.5.2",
-    "embla-carousel-fade": "8.5.2",
-    "embla-carousel-react": "8.5.2",
+    "embla-carousel": "9.0.0-rc01",
+    "embla-carousel-autoplay": "9.0.0-rc01",
+    "embla-carousel-fade": "9.0.0-rc01",
+    "embla-carousel-react": "9.0.0-rc01",
     "gql.tada": "^1.8.10",
     "graphql": "^16.11.0",
     "dompurify": "^3.3.1",

core/vibes/soul/primitives/carousel/index.tsx

@@ -58,13 +58,13 @@ function Carousel({
   const onSelect = React.useCallback((api: CarouselApi) => {
     if (!api) return;
 
-    setCanScrollPrev(api.canScrollPrev());
-    setCanScrollNext(api.canScrollNext());
+    setCanScrollPrev(api.canGoToPrev());
+    setCanScrollNext(api.canGoToNext());
   }, []);
 
-  const scrollPrev = useCallback(() => api?.scrollPrev(), [api]);
+  const scrollPrev = useCallback(() => api?.goToPrev(), [api]);
 
-  const scrollNext = useCallback(() => api?.scrollNext(), [api]);
+  const scrollNext = useCallback(() => api?.goToNext(), [api]);
 
   const handleKeyDown = useCallback(
     (event: React.KeyboardEvent<HTMLDivElement>) => {
@@ -89,7 +89,7 @@ function Carousel({
     if (!api) return;
 
     onSelect(api);
-    api.on('reInit', onSelect);
+    api.on('reinit', onSelect);
     api.on('select', onSelect);
 
     return () => {
@@ -225,7 +225,7 @@ function CarouselScrollbar({
       if (!api) return 0;
 
       const point = nextProgress / 100;
-      const snapList = api.scrollSnapList();
+      const snapList = api.snapList();
 
       if (snapList.length === 0) return -1;
 
@@ -241,14 +241,14 @@ function CarouselScrollbar({
   useEffect(() => {
     if (!api) return;
 
-    const snapList = api.scrollSnapList();
+    const snapList = api.snapList();
     const closestSnapIndex = findClosestSnap(progress);
     const scrollbarWidth = 100 / snapList.length;
     const scrollbarLeft = (closestSnapIndex / snapList.length) * 100;
 
     setScrollbarPosition({ width: scrollbarWidth, left: scrollbarLeft });
 
-    api.scrollTo(closestSnapIndex);
+    api.goTo(closestSnapIndex);
   }, [progress, api, findClosestSnap]);
 
   useEffect(() => {
@@ -258,17 +258,17 @@ function CarouselScrollbar({
       if (!api) return;
 
       // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      setProgress(api.scrollSnapList()[api.selectedScrollSnap()]! * 100);
+      setProgress(api.snapList()[api.selectedSnap()]! * 100);
     }
 
     api.on('select', onScroll);
     api.on('scroll', onScroll);
-    api.on('reInit', onScroll);
+    api.on('reinit', onScroll);
 
     return () => {
       api.off('select', onScroll);
       api.off('scroll', onScroll);
-      api.off('reInit', onScroll);
+      api.off('reinit', onScroll);
     };
   }, [api]);
 

core/vibes/soul/sections/product-detail/index.tsx

@@ -6,7 +6,10 @@ import { AnimatedUnderline } from '@/vibes/soul/primitives/animated-underline';
 import { Price, PriceLabel } from '@/vibes/soul/primitives/price-label';
 import * as Skeleton from '@/vibes/soul/primitives/skeleton';
 import { type Breadcrumb, Breadcrumbs } from '@/vibes/soul/sections/breadcrumbs';
-import { ProductGallery } from '@/vibes/soul/sections/product-detail/product-gallery';
+import {
+  ProductGallery,
+  ProductGalleryLoadMoreAction,
+} from '@/vibes/soul/sections/product-detail/product-gallery';
 import { ReviewForm, SubmitReviewAction } from '@/vibes/soul/sections/reviews/review-form';
 
 import {
@@ -22,7 +25,10 @@ interface ProductDetailProduct {
   id: string;
   title: string;
   href: string;
-  images: Streamable<Array<{ src: string; alt: string }>>;
+  images: Streamable<{
+    images: Array<{ src: string; alt: string }>;
+    pageInfo?: { hasNextPage: boolean; endCursor: string | null };
+  }>;
   price?: Streamable<Price | null>;
   subtitle?: string;
   badge?: string;
@@ -68,6 +74,7 @@ export interface ProductDetailProps<F extends Field> {
   reviewFormTitleLabel?: string;
   reviewFormAction: SubmitReviewAction;
   user: Streamable<{ email: string; name: string }>;
+  loadMoreImagesAction?: ProductGalleryLoadMoreAction;
 }
 
 // eslint-disable-next-line valid-jsdoc
@@ -109,6 +116,7 @@ export function ProductDetail<F extends Field>({
   reviewFormTitleLabel,
   reviewFormAction,
   user,
+  loadMoreImagesAction,
 }: ProductDetailProps<F>) {
   return (
     <section className="@container">
@@ -124,7 +132,14 @@ export function ProductDetail<F extends Field>({
               <div className="grid grid-cols-1 items-stretch gap-x-8 gap-y-8 @2xl:grid-cols-2 @5xl:gap-x-12">
                 <div className="group/product-gallery hidden @2xl:block">
                   <Stream fallback={<ProductGallerySkeleton />} value={product.images}>
-                    {(images) => <ProductGallery images={images} />}
+                    {(imagesData) => (
+                      <ProductGallery
+                        images={imagesData.images}
+                        loadMoreAction={loadMoreImagesAction}
+                        pageInfo={imagesData.pageInfo}
+                        productId={Number(product.id)}
+                      />
+                    )}
                   </Stream>
                 </div>
                 {/* Product Details */}
@@ -185,8 +200,14 @@ export function ProductDetail<F extends Field>({
                   </div>
                   <div className="group/product-gallery mb-8 @2xl:hidden">
                     <Stream fallback={<ProductGallerySkeleton />} value={product.images}>
-                      {(images) => (
-                        <ProductGallery images={images} thumbnailLabel={thumbnailLabel} />
+                      {(imagesData) => (
+                        <ProductGallery
+                          images={imagesData.images}
+                          loadMoreAction={loadMoreImagesAction}
+                          pageInfo={imagesData.pageInfo}
+                          productId={Number(product.id)}
+                          thumbnailLabel={thumbnailLabel}
+                        />
                       )}
                     </Stream>
                   </div>