fix: sort images based on role order (#73)

* fix: sort images based on role order

* fix: pass imageRoleOrder

---------

Co-authored-by: Dylan Depass <[email protected]>

Author: maxakuru

src/content/queries/cs-product.js

@@ -11,7 +11,12 @@
  */
 
 import { forceImagesHTTPS } from '../../utils/http.js';
-import { gql, parseRating, parseSpecialToDate } from '../../utils/product.js';
+import {
+  gql,
+  parseRating,
+  parseSpecialToDate,
+  sortImagesByRole,
+} from '../../utils/product.js';
 
 function extractMinMaxPrice(data) {
   let minPrice = data.priceRange?.minimum ?? data.price;
@@ -32,6 +37,11 @@ function extractMinMaxPrice(data) {
  */
 export const adapter = (config, productData) => {
   const { minPrice, maxPrice } = extractMinMaxPrice(productData);
+  const images = sortImagesByRole(
+    forceImagesHTTPS(productData.images)
+    ?? [],
+    config.imageRoleOrder,
+  );
 
   /** @type {Product} */
   const product = {
@@ -70,7 +80,7 @@ export const adapter = (config, productData) => {
         },
       };
     }),
-    images: forceImagesHTTPS(productData.images) ?? [],
+    images,
     attributes: productData.attributes ?? [],
     attributeMap: Object.fromEntries((productData.attributes ?? [])
       .map(({ name, value }) => [name, value])),
@@ -170,6 +180,7 @@ export default ({ sku, imageRoles = [], linkTypes = [] }) => gql`{
       images(roles: [${imageRoles.map((s) => `"${s}"`).join(',')}]) { 
         url
         label
+        roles
       }
       links(linkTypes: [${linkTypes.map((s) => `"${s}"`).join(',')}]) {
         product {

src/content/queries/cs-variants.js

@@ -11,7 +11,12 @@
  */
 
 import { forceImagesHTTPS } from '../../utils/http.js';
-import { gql, parseRating, parseSpecialToDate } from '../../utils/product.js';
+import {
+  gql,
+  parseRating,
+  parseSpecialToDate,
+  sortImagesByRole,
+} from '../../utils/product.js';
 
 /**
  * @param {Config} config
@@ -22,14 +27,16 @@ export const adapter = (config, variants) => variants.map(({ selections, product
   const minPrice = product.priceRange?.minimum ?? product.price;
   const maxPrice = product.priceRange?.maximum ?? product.price;
 
+  const images = sortImagesByRole(forceImagesHTTPS(product.images) ?? [], config.imageRoleOrder);
+
   /** @type {Variant} */
   const variant = {
     name: product.name,
     sku: product.sku,
     description: product.description,
     url: product.url,
     inStock: product.inStock,
-    images: forceImagesHTTPS(product.images) ?? [],
+    images,
     attributes: product.attributes ?? [],
     attributeMap: Object.fromEntries((product.attributes ?? [])
       .map(({ name, value }) => [name, value])),
@@ -91,6 +98,7 @@ export default ({ sku, imageRoles = [] }) => gql`
         images(roles: [${imageRoles.map((s) => `"${s}"`).join(',')}]) {
           url
           label
+          roles
         }
         ... on SimpleProductView {
           description

src/schemas/Config.js

@@ -44,6 +44,10 @@ const ConfigEntry = {
     offerVariantURLTemplate: { type: 'string' },
     liveSearchEnabled: { type: 'boolean' },
     attributeOverrides: AttributeOverrides,
+    imageRoleOrder: {
+      type: 'array',
+      items: { type: 'string' },
+    },
     imageParams: {
       type: 'object',
       properties: {},

src/templates/html/HTMLTemplate.js

@@ -268,7 +268,7 @@ ${HTMLTemplate.indent(this.renderProductItems(opt.items), 2)}`).join('\n')}
     }
 
     // append image params
-    const { url: purl, label } = image;
+    const { url: purl, label, roles = [] } = image;
     const params = new URLSearchParams(this.ctx.config.imageParams);
     let url;
 
@@ -283,6 +283,7 @@ ${HTMLTemplate.indent(this.renderProductItems(opt.items), 2)}`).join('\n')}
     return {
       url: url.toString(),
       label,
+      roles,
     };
   }
 

src/types.d.ts

@@ -67,6 +67,13 @@ declare global {
      */
     imageRoles?: string[];
 
+    /**
+     * Order for images to appear in markup
+     * If not provided, images will not be sorted
+     * If image role doesn't exist in the order, it will be appended to the end
+     */
+    imageRoleOrder?: string[];
+
     /**
      * Attributes to override using a different attribute name
      */
@@ -140,6 +147,7 @@ declare global {
     sku?: string;
     matchedPatterns: string[];
     imageRoles?: string[];
+    imageRoleOrder?: string[];
     linkTypes?: string[];
     host: string;
     params: Record<string, string>;
@@ -258,6 +266,7 @@ declare global {
   interface Image {
     url: string;
     label: string;
+    roles: string[];
   }
 
   interface Price {

src/utils/product.js

@@ -154,3 +154,25 @@ export function parseRating(product) {
   }
   return undefined;
 }
+
+/**
+ * @param {Product['images']} images images with roles
+ * @param {string[]} [order] preference order
+ * @returns {Product['images']}
+ */
+export function sortImagesByRole(images, order) {
+  if (!order?.length) {
+    return images;
+  }
+
+  const sorted = [];
+  let remaining = images;
+  order.forEach((role) => {
+    const found = remaining.filter((img) => img.roles.includes(role));
+    if (found.length) {
+      sorted.push(...found);
+      remaining = remaining.filter((img) => !found.includes(img));
+    }
+  });
+  return sorted.concat(remaining);
+}

test/utils/product.test.js

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { strict as assert } from 'node:assert';
+import { sortImagesByRole } from '../../src/utils/product.js';
+
+describe('product utils', () => {
+  describe('sortImagesByRole()', () => {
+    it('should sort images by role', () => {
+      /** @type {Product['images']} */
+      const images = [{
+        url: 'https://example.com/image4.jpg',
+        label: 'four',
+        roles: ['teriary'],
+      }, {
+        url: 'https://example.com/image1.jpg',
+        label: 'one',
+        roles: ['thumbnail'],
+      }, {
+        url: 'https://example.com/image2.jpg',
+        label: 'two',
+        roles: ['primary'],
+      }, {
+        url: 'https://example.com/image3.jpg',
+        label: 'three',
+        roles: ['thumbnail', 'secondary'],
+      }];
+
+      const sortedImages = sortImagesByRole(images, ['thumbnail', 'primary']);
+      assert.deepStrictEqual(sortedImages, [{
+        url: 'https://example.com/image1.jpg',
+        label: 'one',
+        roles: ['thumbnail'],
+      }, {
+        url: 'https://example.com/image3.jpg',
+        label: 'three',
+        roles: ['thumbnail', 'secondary'],
+      }, {
+        url: 'https://example.com/image2.jpg',
+        label: 'two',
+        roles: ['primary'],
+      }, {
+        url: 'https://example.com/image4.jpg',
+        label: 'four',
+        roles: ['teriary'],
+      }]);
+    });
+  });
+});