@decocms/apps-vtex 7.66.5 → 7.66.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/apps-vtex",
-  "version": "7.66.5",
+  "version": "7.66.6",
   "type": "module",
   "description": "Deco commerce app: VTEX integration",
   "repository": {
@@ -51,10 +51,10 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.66.5",
-    "@decocms/apps-commerce": "7.66.5",
-    "@decocms/apps-website": "7.66.5",
-    "@decocms/tanstack": "7.66.5"
+    "@decocms/blocks": "7.66.6",
+    "@decocms/apps-commerce": "7.66.6",
+    "@decocms/apps-website": "7.66.6",
+    "@decocms/tanstack": "7.66.6"
   },
   "peerDependencies": {
     "@tanstack/react-query": ">=5.0.0",

package/src/loaders/intelligentSearch/productList.ts

@@ -19,6 +19,13 @@ export interface ProductListProps {
 	 * a single in-stock variant per product).
 	 */
 	completeVariants?: boolean;
+	/**
+	 * `imageLabel`s that survive the shelf transform's 2-image cap. Storefronts
+	 * that pick the card image by name (a still/packshot asset, a colour
+	 * thumbnail) need this: those assets are registered last on the SKU, so the
+	 * positional cap drops them and the card falls back to the first photo.
+	 */
+	keepImageNames?: string[];
 }
 
 interface CollectionProps {
@@ -147,6 +154,7 @@ export default async function vtexProductListShelf(
 				baseUrl,
 				priceCurrency: "BRL",
 				shelfCompleteVariants: props.completeVariants,
+				keepImageNames: props.keepImageNames,
 			});
 		});
 

package/src/utils/__tests__/transform.test.ts

@@ -749,6 +749,7 @@ describe("toProductShelf", () => {
 				},
 			],
 			variations: [{ name: "Cor", values: ["Preto"] }],
+			...overrides,
 		}) as any;
 
 	// Campanha is a PRODUCT specification (in specificationGroups), NOT a sku.variation.
@@ -818,6 +819,69 @@ describe("toProductShelf", () => {
 			expect.arrayContaining([expect.objectContaining({ name: "RefId", value: "REF-SKU1" })]),
 		);
 	});
+
+	// A real catalog registers the packshot and the colour thumbnail LAST:
+	// measured on a live store, `secondary` sits at index 6 and `color-thumbnail`
+	// at index 7 of 8. A card that selects either BY NAME gets nothing from a
+	// positional cap and silently falls back to the first photo (the model
+	// wearing the piece).
+	const labelledImages = [
+		...Array.from({ length: 6 }, (_, i) => ({
+			imageUrl: `https://img.com/photo-${i}.jpg`,
+			imageText: `Photo ${i}`,
+			imageLabel: `product-photo-${i}`,
+		})),
+		{ imageUrl: "https://img.com/still.jpg", imageText: "Still", imageLabel: "secondary" },
+		{ imageUrl: "https://img.com/thumb.jpg", imageText: "Thumb", imageLabel: "color-thumbnail" },
+	];
+	const skuWithLabels = () => makeSku({ images: labelledImages });
+	const labelledProduct = () => makeProduct({ items: [skuWithLabels()] });
+
+	it("keeps the 2-image cap when keepImageNames is absent", () => {
+		const result = toProductShelf(labelledProduct(), skuWithLabels(), 0, options);
+		expect(result.image?.map((i) => i.name)).toEqual(["product-photo-0", "product-photo-1"]);
+	});
+
+	it("keepImageNames adds back labelled images that fall outside the cap", () => {
+		const result = toProductShelf(labelledProduct(), skuWithLabels(), 0, {
+			...options,
+			keepImageNames: ["secondary", "color-thumbnail"],
+		});
+		expect(result.image?.map((i) => i.name)).toEqual([
+			"product-photo-0",
+			"product-photo-1",
+			"secondary",
+			"color-thumbnail",
+		]);
+	});
+
+	it("keepImageNames does not duplicate a label already inside the cap", () => {
+		const result = toProductShelf(labelledProduct(), skuWithLabels(), 0, {
+			...options,
+			keepImageNames: ["product-photo-0", "secondary"],
+		});
+		expect(result.image?.map((i) => i.name)).toEqual([
+			"product-photo-0",
+			"product-photo-1",
+			"secondary",
+		]);
+	});
+
+	it("keepImageNames listing a label the SKU does not have changes nothing", () => {
+		const result = toProductShelf(labelledProduct(), skuWithLabels(), 0, {
+			...options,
+			keepImageNames: ["vira"],
+		});
+		expect(result.image?.map((i) => i.name)).toEqual(["product-photo-0", "product-photo-1"]);
+	});
+
+	it("maxImages overrides the shelf default cap", () => {
+		const result = toProductShelf(labelledProduct(), skuWithLabels(), 0, {
+			...options,
+			maxImages: 3,
+		});
+		expect(result.image).toHaveLength(3);
+	});
 });
 
 // ---------------------------------------------------------------------------
@@ -1018,12 +1082,28 @@ describe("toProduct — displayedVariantId / maxImages", () => {
 		);
 	});
 
+	it("keepImageNames rescues a labelled image from the maxImages cap", () => {
+		const capped = toProduct(product, items[0], 0, {
+			...options,
+			maxImages: 2,
+			keepImageNames: ["label3"],
+		});
+		expect(capped.image?.map((i) => i.name)).toEqual(["label0", "label1", "label3"]);
+	});
+
+	it("keepImageNames without maxImages is a no-op — every image is already there", () => {
+		const before = toProduct(product, items[0], 0, options);
+		const after = toProduct(product, items[0], 0, { ...options, keepImageNames: ["label3"] });
+		expect(JSON.stringify(after)).toBe(JSON.stringify(before));
+	});
+
 	it("every option absent is byte-for-byte the previous output", () => {
 		const before = toProduct(product, items[0], 0, options);
 		const after = toProduct(product, items[0], 0, {
 			...options,
 			displayedVariantId: undefined,
 			maxImages: undefined,
+			keepImageNames: undefined,
 			priceSpecifications: undefined,
 		});
 		expect(JSON.stringify(after)).toBe(JSON.stringify(before));

package/src/utils/transform.ts

@@ -168,9 +168,24 @@ export interface ProductOptions {
 	 * (hover) image sits at index 1 in only 5 of the 19 products that have one —
 	 * index 2 in 12 of them, index 3 in 2. A cap of 2 therefore drops the hover
 	 * image on most cards that use one. Callers that select by name should keep
-	 * the named entries instead of using this option.
+	 * the named entries through {@link keepImageNames}.
 	 */
 	maxImages?: number;
+	/**
+	 * `imageLabel`s that survive the positional cap. An image whose label is
+	 * listed here is kept even when it falls outside {@link maxImages} (and
+	 * outside the shelf transform's own default cap), in its original order.
+	 *
+	 * This is the escape hatch the `maxImages` note asks for. A storefront that
+	 * picks the card image BY NAME — a "still"/packshot asset, a colour
+	 * thumbnail — cannot use a positional cap on its own: those assets are
+	 * registered last on the SKU, so any cap drops them and the card silently
+	 * falls back to the first photo. Pass the labels the card selects and the
+	 * payload stays lean everywhere else.
+	 *
+	 * Undefined (default) preserves the current behaviour byte for byte.
+	 */
+	keepImageNames?: string[];
 	/** Property names to keep on lean variant additionalProperty. Defaults to VARIANT_PROPERTY_NAMES. */
 	variantPropertyNames?: Set<string>;
 	/** When leanVariants is true, still include image[0] on each variant entry. Default true. */
@@ -186,6 +201,28 @@ export interface ProductOptions {
 	shelfCompleteVariants?: boolean;
 }
 
+/**
+ * Apply the positional image cap, then add back the entries the caller selects
+ * by name. Order is preserved: the capped head first, then the named tail in
+ * catalog order. No cap means no work.
+ */
+const capImages = <I extends { imageLabel?: string | null }>(
+	images: I[] | null | undefined,
+	maxImages: number | undefined,
+	keepImageNames: string[] | undefined,
+): I[] | null | undefined => {
+	if (!images || typeof maxImages !== "number") return images;
+
+	const capped = images.slice(0, maxImages);
+
+	if (!keepImageNames?.length) return capped;
+
+	const keep = new Set(keepImageNames);
+	const named = images.slice(maxImages).filter((image) => keep.has(image.imageLabel ?? ""));
+
+	return named.length > 0 ? [...capped, ...named] : capped;
+};
+
 /** Returns first available sku */
 const findFirstAvailable = (items: Array<LegacySkuVTEX | SkuVTEX>) =>
 	items?.find((item) =>
@@ -495,8 +532,7 @@ export const toProduct = <P extends LegacyProductVTEX | ProductVTEX>(
 				} satisfies ProductGroup)
 			: undefined;
 
-	const cappedImages =
-		typeof options.maxImages === "number" ? images?.slice(0, options.maxImages) : images;
+	const cappedImages = capImages(images, options.maxImages, options.keepImageNames);
 	const finalImages = cappedImages?.map(({ imageUrl, imageText, imageLabel }) => {
 		const url = imagesByKey.get(getImageKey(imageUrl)) ?? imageUrl;
 		const alternateName = imageText || imageLabel || "";
@@ -659,6 +695,9 @@ const applyPriceSpecifications = (offers: Offer[], options: ProductOptions): Off
 			}))
 		: offers;
 
+/** Default positional image cap for the shelf transform (front + back). */
+const SHELF_MAX_IMAGES = 2;
+
 /** Property names commonly used by ProductCard/Shelf components */
 const SHELF_PROPERTY_NAMES = new Set([
 	"category",
@@ -674,7 +713,8 @@ const SHELF_PROPERTY_NAMES = new Set([
  * Lean product transform for shelf/card display. Same signature as toProduct().
  *
  * Differences from toProduct():
- * - Images: capped at 2 per SKU (front + back)
+ * - Images: capped at 2 per SKU (front + back), overridable via `maxImages`;
+ *   `keepImageNames` adds back labelled assets that fall outside the cap
  * - Offers: best seller only (in-stock first, then cheapest), stripped installments (keeps ListPrice, SalePrice, SRP, PIX, best no-interest)
  * - isVariantOf: single in-stock variant at level 0
  * - additionalProperty: filtered to known-used property names
@@ -690,9 +730,11 @@ export const toProductShelf = <P extends LegacyProductVTEX | ProductVTEX>(
 	const { productId, items, productReference } = product;
 	const { name, itemId: skuId } = sku;
 
-	// Images: cap at 2
+	// Images: cap at 2, keeping any label the caller selects by name
 	const rawImages = nonEmptyArray(sku.images);
-	const mappedImages = (rawImages ?? []).slice(0, 2).map(({ imageUrl, imageText, imageLabel }) => ({
+	const cappedImages =
+		capImages(rawImages, options.maxImages ?? SHELF_MAX_IMAGES, options.keepImageNames) ?? [];
+	const mappedImages = cappedImages.map(({ imageUrl, imageText, imageLabel }) => ({
 		"@type": "ImageObject" as const,
 		alternateName: imageText || imageLabel || "",
 		url: imageUrl,