@deneb-ui/ui 2.0.126 → 2.0.127

package/README.md

@@ -637,6 +637,12 @@ export function PromoSection() {
 
 DENEB UI commerce components natively support both **Single Fixed Prices** and **Dynamic Price Ranges**, as well as apparel clothing options (color swatches with image swapping and size chips).
 
+Fivora uses one canonical catalog contract: `ProductCard` is the commerce
+renderer, `ServiceCard` is the service/quote renderer, and `UniversalCard` is
+reserved for other generic entity listings. Keep `imageUrl` as the primary
+image and `additionalImages` as the ordered gallery; DENEB normalizes them to
+`images`/`gallery` for detail and quick-view components.
+
 Keep `price`, `compareAtPrice`, `minPrice`, `maxPrice`, and variant prices as
 JSON numbers. Keep `currency` or a currency symbol as separate text. A formatted
 `priceRange` string is display-only; numeric filters and sorting must use the
@@ -653,7 +659,8 @@ import { ProductCard } from "@deneb-ui/ui";
     price: 3500,
     compareAtPrice: 4500,
     currency: "LKR",
-    imageUrl: "/images/shirt.jpg"
+    imageUrl: "/images/shirt.jpg",
+    additionalImages: ["/images/shirt-back.jpg", "/images/shirt-detail.jpg"]
   }}
   itemPath="products[0]"
 />
@@ -673,6 +680,7 @@ import { ProductCard } from "@deneb-ui/ui";
     isPriceRange: true,
     currency: "LKR",
     imageUrl: "/images/tunic-navy.jpg",
+    additionalImages: ["/images/tunic-back.jpg", "/images/tunic-detail.jpg"],
     colors: [
       { name: "Navy Blue", hex: "#1e3a8a", imageUrl: "/images/tunic-navy.jpg" },
       { name: "Olive Green", hex: "#3f6212", imageUrl: "/images/tunic-olive.jpg" },

package/dist/EditableProductCard.d.ts

@@ -29,6 +29,7 @@ export interface ProductItem {
     productImage?: string;
     gallery?: string[];
     images?: string[];
+    additionalImages?: string[];
     badge?: string;
     tag?: string;
     rating?: number | string;

package/dist/EditableProductCard.js

@@ -9,6 +9,7 @@ const EditableImage_1 = require("./EditableImage");
 const useCart_1 = require("./cart/useCart");
 const productOptions_1 = require("./utils/productOptions");
 const PlatformProductDetail_1 = require("./PlatformProductDetail");
+const catalogMedia_1 = require("./utils/catalogMedia");
 const COLOR_HEX_MAP = {
     black: '#111827',
     white: '#ffffff',
@@ -166,14 +167,7 @@ function EditableProductCard({ itemPath, product: productProp, item: itemProp, c
     const badge = String(product?.badge || product?.tag || '');
     const hasBadgeField = Boolean(product && ('badge' in product || 'tag' in product));
     const fallbackImage = imageFallback || 'https://images.unsplash.com/photo-1542291026-7eec264c27ff?auto=format&fit=crop&w=800&q=80';
-    const rawImage = product?.imageUrl ||
-        product?.image ||
-        product?.photo ||
-        product?.thumbnail ||
-        product?.productImage ||
-        (Array.isArray(product?.gallery) && product.gallery[0]) ||
-        (Array.isArray(product?.images) && product.images[0]);
-    const baseImageUrl = String(rawImage || fallbackImage);
+    const baseImageUrl = (0, catalogMedia_1.resolveCatalogPrimaryImage)(product, fallbackImage);
     // Active image: clicked color image -> resolved variant image -> product base image
     const currentImage = colorImage || resolvedPrice.variantImage || baseImageUrl;
     const imageKey = 'image' in (product || {}) && !('imageUrl' in (product || {}) && product.imageUrl)

package/dist/EditableProductDetail.d.ts

@@ -16,6 +16,7 @@ export interface ProductDetailItem {
     image?: string;
     gallery?: string[];
     images?: string[];
+    additionalImages?: string[];
     addToSelectionLabel?: string;
     specsTitle?: string;
     specs?: Array<{

package/dist/EditableProductDetail.js

@@ -9,6 +9,7 @@ const react_1 = require("react");
 const utils_1 = require("./utils");
 const productOptions_1 = require("./utils/productOptions");
 const urls_1 = require("./utils/urls");
+const catalogMedia_1 = require("./utils/catalogMedia");
 /**
  * EditableProductDetail is an elite, fully calibrated Single Product View component
  * engineered for high-conversion commerce and 100% compliant with Fivora Visual Editing.
@@ -28,14 +29,11 @@ function EditableProductDetail({ sectionPath = 'product', product, sizes, colors
     const productRecord = (product || {});
     const productPhoto = productRecord.photo;
     const productThumbnail = productRecord.thumbnail;
-    const validImages = (0, react_1.useMemo)(() => {
-        const rawList = (product.gallery && product.gallery.length > 0)
-            ? product.gallery
-            : (product.images && product.images.length > 0)
-                ? product.images
-                : [product.featuredImage || product.imageUrl || product.image || productPhoto || productThumbnail || '/products/vanta-aero-x.jpg'];
-        return rawList.filter(Boolean);
-    }, [product.gallery, product.images, product.featuredImage, product.imageUrl, product.image, productPhoto, productThumbnail]);
+    const validImages = (0, react_1.useMemo)(() => (0, catalogMedia_1.resolveCatalogImages)({
+        ...product,
+        photo: productPhoto,
+        thumbnail: productThumbnail,
+    }, '/products/vanta-aero-x.jpg'), [product, productPhoto, productThumbnail]);
     // 2. Resolve Options (Sizes, Volumes, Weights, Counts)
     const resolved = (0, productOptions_1.resolveProductOptions)(product);
     const effectiveOptions = (0, react_1.useMemo)(() => {

package/dist/EditableServiceCard.d.ts

@@ -10,6 +10,9 @@ export interface ServiceItem {
     description?: string;
     imageUrl?: string;
     image?: string;
+    gallery?: string[];
+    images?: string[];
+    additionalImages?: string[];
     features?: unknown[];
     [key: string]: unknown;
 }

package/dist/EditableServiceCard.js

@@ -4,6 +4,7 @@ exports.EditableServiceCard = EditableServiceCard;
 const jsx_runtime_1 = require("react/jsx-runtime");
 const EditableText_1 = require("./EditableText");
 const EditableImage_1 = require("./EditableImage");
+const catalogMedia_1 = require("./utils/catalogMedia");
 /**
  * EditableServiceCard standardizes service presentation across Home and Services pages.
  * Supports service name, description, image, and repeatable features checklist.
@@ -28,7 +29,8 @@ function EditableServiceCard({ itemPath, service, imageFallback = '/placeholder.
                 ? String(rawPriceCandidate)
                 : 'LKR ' + String(rawPriceCandidate)
         : '';
-    const imageUrl = String(service?.imageUrl || service?.image || '');
+    const serviceImages = (0, catalogMedia_1.resolveCatalogImages)(service);
+    const imageUrl = serviceImages[0] || '';
     const features = Array.isArray(service?.features) ? service.features : [];
     const mergedStyle = {
         textAlign: align,

package/dist/EditableUniversalCard.d.ts

@@ -1,13 +1,15 @@
 /**
  * EditableUniversalCard — DENEB UI Framework
  *
- * Universal, multi-industry listing card for all commerce and business templates:
+ * Universal, multi-industry listing renderer for non-catalog entities. Fivora
+ * products and services should use EditableProductCard/EditableServiceCard so
+ * their backend catalog behavior is preserved:
  * - 🚗 Automotive & Equipment: Make/model, year & condition, mileage, fuel, gearbox, price
  * - 📚 Bookshops & Publishers: Cover photo, book title, author, published year, pages, price
  * - 🏋️ Gyms & Fitness: Membership tier, duration, meal plan, 24/7 access, trainer, price
- * - 🍽️ Restaurants & Menus: Dish photo, title, dietary tags, ingredients, prep time, price
+ * - 🍽️ Editorial Menus: Dish photo, title, dietary tags, ingredients, prep time, price
  * - 🏠 Real Estate & Rentals: Property image, location, beds, baths, sqft, price
- * - 💼 Services & Agencies: Service title, duration, deliverable checklist, pricing
+ * - 💼 Agency Portfolios: Offering title, duration, deliverable checklist, pricing
  *
  * Designed with strict editability architecture:
  * 1. Automatically resolves fields from `useSiteData()` via `itemPath` or explicit field paths.

package/dist/PlatformProductDetail.js

@@ -9,6 +9,7 @@ const react_1 = require("react");
 const EditableProductDetail_1 = require("./EditableProductDetail");
 const SiteDataProvider_1 = require("./SiteDataProvider");
 const utils_1 = require("./utils");
+const catalogMedia_1 = require("./utils/catalogMedia");
 const DEFAULT_QUERY_PARAM = 'id';
 const DEFAULT_DETAIL_ROUTE = '/products/detail/';
 const DEFAULT_RETRY_DELAYS = [0, 750, 2_000];
@@ -93,13 +94,7 @@ function normalizeProductForDetail(product, siteData) {
         (typeof mergedProduct.thumbnail === 'string' && mergedProduct.thumbnail) ||
         undefined;
     const price = mergedProduct.price ?? mergedProduct.cost ?? mergedProduct.amount ?? mergedProduct.productPrice;
-    const images = Array.isArray(mergedProduct.gallery)
-        ? mergedProduct.gallery
-        : Array.isArray(mergedProduct.images)
-            ? mergedProduct.images
-            : Array.isArray(mergedProduct.additionalImages)
-                ? mergedProduct.additionalImages.filter((value) => typeof value === 'string' && Boolean(value.trim()))
-                : undefined;
+    const images = (0, catalogMedia_1.resolveCatalogImages)(mergedProduct);
     const compareAtPrice = mergedProduct.compareAtPrice ?? mergedProduct.originalPrice;
     const shop = (0, SiteDataProvider_1.isRecord)(siteData.shop) ? siteData.shop : {};
     const merchant = (0, SiteDataProvider_1.isRecord)(siteData.merchant) ? siteData.merchant : {};
@@ -122,7 +117,7 @@ function normalizeProductForDetail(product, siteData) {
             ? { featuredImage: image, imageUrl: image, image }
             : {}),
         ...(price !== undefined ? { price } : {}),
-        ...(images ? { gallery: images, images } : {}),
+        ...(images.length > 0 ? { gallery: images, images } : {}),
         ...(compareAtPrice !== undefined
             ? { compareAtPrice, originalPrice: compareAtPrice }
             : {}),

package/dist/ProductQuickView.d.ts

@@ -9,6 +9,8 @@ export interface ProductQuickViewItem {
     description?: string;
     imageUrl?: string;
     gallery?: string[];
+    images?: string[];
+    additionalImages?: string[];
     inStock?: boolean;
     isAvailable?: boolean;
     rating?: number;

package/dist/ProductQuickView.js

@@ -5,6 +5,7 @@ const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = require("react");
 const utils_1 = require("./utils");
 const PlatformProductDetail_1 = require("./PlatformProductDetail");
+const catalogMedia_1 = require("./utils/catalogMedia");
 /**
  * DENEB UI — Product Quick View Modal
  *
@@ -20,7 +21,7 @@ function ProductQuickView({ product, isOpen, onClose, onAddToCart, className = '
     (0, react_1.useEffect)(() => {
         if (product) {
             setQuantity(1);
-            setSelectedImage(product.imageUrl || (product.gallery && product.gallery[0]) || '');
+            setSelectedImage((0, catalogMedia_1.resolveCatalogImages)(product)[0] || '');
         }
     }, [product]);
     // Handle ESC key to close
@@ -42,7 +43,7 @@ function ProductQuickView({ product, isOpen, onClose, onAddToCart, className = '
     if (!isOpen || !product) {
         return null;
     }
-    const images = product.gallery && product.gallery.length > 0 ? product.gallery : [product.imageUrl || ''];
+    const images = (0, catalogMedia_1.resolveCatalogImages)(product);
     const currency = product.currency || '$';
     const isAvailable = product.isAvailable !== false && product.inStock !== false;
     const handleAddToCart = () => {

package/dist/SiteDataProvider.d.ts

@@ -11,6 +11,7 @@ export declare const LEGACY_PREVIEW_READY_MESSAGE: string;
 export declare const DENEB_PREVIEW_FOCUS_MESSAGE = "DENEB_PREVIEW_FOCUS_PAGE";
 export declare const PREVIEW_FOCUS_MESSAGE = "FIVORA_PREVIEW_FOCUS_PAGE";
 export declare const LEGACY_PREVIEW_FOCUS_MESSAGE: string;
+export declare const DENEB_REFRESH_LIVE_CATALOG_EVENT = "deneb:refresh-live-catalog";
 export declare const PREVIEW_FIELD_ATTRIBUTE = "data-preview-field-path";
 export { STYLE_PATCH_MESSAGE, DENEB_STYLE_PATCH_MESSAGE } from '@deneb-ui/core';
 export type GenericRecord = Record<string, any>;

package/dist/SiteDataProvider.js

@@ -1,7 +1,7 @@
 "use strict";
 'use client';
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DUMMY_PREVIEW_SHOP_NAME = exports.DUMMY_PREVIEW_ADDRESS = exports.DUMMY_PREVIEW_EMAIL = exports.DUMMY_PREVIEW_WHATSAPP = exports.DUMMY_PREVIEW_PHONE = exports.DenebDataContext = exports.useDenebData = exports.DenebDataProvider = exports.resolveAsset = exports.withBasePath = exports.SiteDataContext = exports.DENEB_STYLE_PATCH_MESSAGE = exports.STYLE_PATCH_MESSAGE = exports.PREVIEW_FIELD_ATTRIBUTE = exports.LEGACY_PREVIEW_FOCUS_MESSAGE = exports.PREVIEW_FOCUS_MESSAGE = exports.DENEB_PREVIEW_FOCUS_MESSAGE = exports.LEGACY_PREVIEW_READY_MESSAGE = exports.PREVIEW_READY_MESSAGE = exports.DENEB_PREVIEW_READY_MESSAGE = exports.LEGACY_PREVIEW_DATA_MESSAGE = exports.PREVIEW_DATA_MESSAGE = exports.DENEB_PREVIEW_DATA_MESSAGE = void 0;
+exports.DUMMY_PREVIEW_SHOP_NAME = exports.DUMMY_PREVIEW_ADDRESS = exports.DUMMY_PREVIEW_EMAIL = exports.DUMMY_PREVIEW_WHATSAPP = exports.DUMMY_PREVIEW_PHONE = exports.DenebDataContext = exports.useDenebData = exports.DenebDataProvider = exports.resolveAsset = exports.withBasePath = exports.SiteDataContext = exports.DENEB_STYLE_PATCH_MESSAGE = exports.STYLE_PATCH_MESSAGE = exports.PREVIEW_FIELD_ATTRIBUTE = exports.DENEB_REFRESH_LIVE_CATALOG_EVENT = exports.LEGACY_PREVIEW_FOCUS_MESSAGE = exports.PREVIEW_FOCUS_MESSAGE = exports.DENEB_PREVIEW_FOCUS_MESSAGE = exports.LEGACY_PREVIEW_READY_MESSAGE = exports.PREVIEW_READY_MESSAGE = exports.DENEB_PREVIEW_READY_MESSAGE = exports.LEGACY_PREVIEW_DATA_MESSAGE = exports.PREVIEW_DATA_MESSAGE = exports.DENEB_PREVIEW_DATA_MESSAGE = void 0;
 exports.isRecord = isRecord;
 exports.isDarkColor = isDarkColor;
 exports.syncThemeToDocument = syncThemeToDocument;
@@ -43,6 +43,7 @@ const ThemeStyles_1 = require("./ThemeStyles");
 const utils_1 = require("./utils");
 Object.defineProperty(exports, "withBasePath", { enumerable: true, get: function () { return utils_1.withBasePath; } });
 Object.defineProperty(exports, "resolveAsset", { enumerable: true, get: function () { return utils_1.resolveAsset; } });
+const catalogMedia_1 = require("./utils/catalogMedia");
 exports.DENEB_PREVIEW_DATA_MESSAGE = 'DENEB_PREVIEW_SITE_DATA';
 exports.PREVIEW_DATA_MESSAGE = 'FIVORA_PREVIEW_SITE_DATA';
 const PREVIOUS_PREVIEW_PREFIX = `${['MARKET', 'PLACE'].join('')}_PREVIEW_`;
@@ -55,6 +56,7 @@ exports.LEGACY_PREVIEW_READY_MESSAGE = previousPreviewMessage('READY');
 exports.DENEB_PREVIEW_FOCUS_MESSAGE = 'DENEB_PREVIEW_FOCUS_PAGE';
 exports.PREVIEW_FOCUS_MESSAGE = 'FIVORA_PREVIEW_FOCUS_PAGE';
 exports.LEGACY_PREVIEW_FOCUS_MESSAGE = previousPreviewMessage('FOCUS_PAGE');
+exports.DENEB_REFRESH_LIVE_CATALOG_EVENT = 'deneb:refresh-live-catalog';
 exports.PREVIEW_FIELD_ATTRIBUTE = 'data-preview-field-path';
 var core_2 = require("@deneb-ui/core");
 Object.defineProperty(exports, "STYLE_PATCH_MESSAGE", { enumerable: true, get: function () { return core_2.STYLE_PATCH_MESSAGE; } });
@@ -366,6 +368,9 @@ function SiteDataProvider({ children, initialSiteData, fallbackSiteData, liveCat
                 }
                 return {
                     ...current,
+                    liveCatalogUpdatedAt: typeof live.updatedAt === 'string'
+                        ? live.updatedAt
+                        : new Date().toISOString(),
                     shop: nextShop,
                     merchant: nextMerchant,
                     reviews: nextReviews ?? current.reviews,
@@ -388,6 +393,36 @@ function SiteDataProvider({ children, initialSiteData, fallbackSiteData, liveCat
                         ...(currentContent?.store && typeof currentContent.store === 'object' && nextProducts !== undefined
                             ? { store: { ...currentContent.store, products: nextProducts } }
                             : {}),
+                        ...(currentContent?.servicesPage &&
+                            typeof currentContent.servicesPage === 'object' &&
+                            nextServices !== undefined
+                            ? {
+                                servicesPage: {
+                                    ...currentContent.servicesPage,
+                                    services: nextServices,
+                                },
+                            }
+                            : {}),
+                        ...(currentContent?.company &&
+                            typeof currentContent.company === 'object' &&
+                            nextServices !== undefined
+                            ? {
+                                company: {
+                                    ...currentContent.company,
+                                    services: nextServices,
+                                },
+                            }
+                            : {}),
+                        ...(currentContent?.business &&
+                            typeof currentContent.business === 'object' &&
+                            nextServices !== undefined
+                            ? {
+                                business: {
+                                    ...currentContent.business,
+                                    services: nextServices,
+                                },
+                            }
+                            : {}),
                         ...(currentHome || Object.keys(nextHome).length > 0
                             ? {
                                 home: {
@@ -458,9 +493,19 @@ function SiteDataProvider({ children, initialSiteData, fallbackSiteData, liveCat
                 void loadLiveCatalog();
             }
         };
+        const refreshNow = () => {
+            if (document.visibilityState !== 'visible')
+                return;
+            if (retryTimer !== null)
+                window.clearTimeout(retryTimer);
+            retryTimer = null;
+            void loadLiveCatalog();
+        };
         void loadLiveCatalog();
         window.addEventListener("focus", refreshIfStale);
         window.addEventListener("online", refreshIfStale);
+        window.addEventListener('pageshow', refreshIfStale);
+        window.addEventListener(exports.DENEB_REFRESH_LIVE_CATALOG_EVENT, refreshNow);
         document.addEventListener("visibilitychange", refreshIfStale);
         return () => {
             stopped = true;
@@ -469,6 +514,8 @@ function SiteDataProvider({ children, initialSiteData, fallbackSiteData, liveCat
                 window.clearTimeout(retryTimer);
             window.removeEventListener("focus", refreshIfStale);
             window.removeEventListener("online", refreshIfStale);
+            window.removeEventListener('pageshow', refreshIfStale);
+            window.removeEventListener(exports.DENEB_REFRESH_LIVE_CATALOG_EVENT, refreshNow);
             document.removeEventListener("visibilitychange", refreshIfStale);
         };
     }, [liveCatalogEndpoint, siteSlug, initialSiteData]);
@@ -875,7 +922,9 @@ function normalizeProductItem(p) {
         p.src ??
         p.productImage ??
         (Array.isArray(p.gallery) ? p.gallery[0] : undefined) ??
-        (Array.isArray(p.images) ? p.images[0] : undefined);
+        (Array.isArray(p.images) ? p.images[0] : undefined) ??
+        (Array.isArray(p.additionalImages) ? p.additionalImages[0] : undefined);
+    const catalogImages = (0, catalogMedia_1.resolveCatalogImages)(p);
     const badgeCandidate = p.badge ?? p.tag ?? p.label ?? p.badgeText ?? p.chip;
     const descCandidate = p.description ?? p.desc ?? p.details ?? p.shortDescription ?? p.subtitle;
     const explicitMin = p.minPrice ?? customData.minPrice;
@@ -918,6 +967,13 @@ function normalizeProductItem(p) {
                 productImage: imageCandidate,
             }
             : {}),
+        ...(catalogImages.length > 0
+            ? {
+                gallery: catalogImages,
+                images: catalogImages,
+                additionalImages: catalogImages.slice(1),
+            }
+            : {}),
         ...(badgeCandidate !== undefined
             ? {
                 badge: badgeCandidate,
@@ -943,7 +999,15 @@ function normalizeServiceItem(s) {
     const nameCandidate = s.name ?? s.title ?? s.serviceName ?? s.heading;
     const titleCandidate = s.title ?? s.name ?? s.serviceName ?? s.heading;
     const descCandidate = s.description ?? s.desc ?? s.details ?? s.shortDescription;
-    const imageCandidate = s.imageUrl ?? s.image ?? s.photo ?? s.thumbnail ?? s.picture;
+    const imageCandidate = s.imageUrl ??
+        s.image ??
+        s.photo ??
+        s.thumbnail ??
+        s.picture ??
+        (Array.isArray(s.gallery) ? s.gallery[0] : undefined) ??
+        (Array.isArray(s.images) ? s.images[0] : undefined) ??
+        (Array.isArray(s.additionalImages) ? s.additionalImages[0] : undefined);
+    const catalogImages = (0, catalogMedia_1.resolveCatalogImages)(s);
     return {
         ...customData,
         ...s,
@@ -951,6 +1015,13 @@ function normalizeServiceItem(s) {
         title: titleCandidate,
         ...(descCandidate !== undefined ? { description: descCandidate, desc: descCandidate, details: descCandidate } : {}),
         ...(imageCandidate !== undefined ? { imageUrl: imageCandidate, image: imageCandidate, photo: imageCandidate } : {}),
+        ...(catalogImages.length > 0
+            ? {
+                gallery: catalogImages,
+                images: catalogImages,
+                additionalImages: catalogImages.slice(1),
+            }
+            : {}),
     };
 }
 function useProducts(fallback = []) {
@@ -958,6 +1029,13 @@ function useProducts(fallback = []) {
     const content = isRecord(siteData?.content) ? siteData.content : null;
     if (!content)
         return fallback;
+    // Once the public catalog endpoint has answered, its top-level collection is
+    // authoritative even when it is empty. This prevents deleted products from
+    // falling back to stale products embedded in the generated site bundle.
+    if (typeof siteData.liveCatalogUpdatedAt === 'string' &&
+        Array.isArray(content.products)) {
+        return content.products.map(normalizeProductItem);
+    }
     let rawList = null;
     const candidates = [
         content.products,
@@ -990,6 +1068,12 @@ function useServices(fallback = []) {
     const content = isRecord(siteData?.content) ? siteData.content : null;
     if (!content)
         return fallback;
+    // An empty live response is meaningful: all services were removed. Do not
+    // resurrect build-time services from a nested legacy collection or fallback.
+    if (typeof siteData.liveCatalogUpdatedAt === 'string' &&
+        Array.isArray(content.services)) {
+        return content.services.map(normalizeServiceItem);
+    }
     const candidates = [
         content.services,
         content.servicesPage?.services,

package/dist/utils/catalogMedia.d.ts

@@ -0,0 +1,18 @@
+export interface CatalogMediaItem {
+    featuredImage?: unknown;
+    imageUrl?: unknown;
+    image?: unknown;
+    photo?: unknown;
+    thumbnail?: unknown;
+    productImage?: unknown;
+    gallery?: unknown;
+    images?: unknown;
+    additionalImages?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * Resolves Fivora's catalog media contract while retaining legacy template
+ * aliases. The primary image stays first and duplicate URLs are removed.
+ */
+export declare function resolveCatalogImages(item?: CatalogMediaItem | null, fallbackImage?: string): string[];
+export declare function resolveCatalogPrimaryImage(item?: CatalogMediaItem | null, fallbackImage?: string): string;

package/dist/utils/catalogMedia.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCatalogImages = resolveCatalogImages;
+exports.resolveCatalogPrimaryImage = resolveCatalogPrimaryImage;
+function appendImage(images, seen, candidate) {
+    if (typeof candidate !== 'string')
+        return;
+    const normalized = candidate.trim();
+    if (!normalized || seen.has(normalized))
+        return;
+    seen.add(normalized);
+    images.push(normalized);
+}
+function appendImageList(images, seen, candidate) {
+    if (!Array.isArray(candidate))
+        return;
+    candidate.forEach((value) => appendImage(images, seen, value));
+}
+/**
+ * Resolves Fivora's catalog media contract while retaining legacy template
+ * aliases. The primary image stays first and duplicate URLs are removed.
+ */
+function resolveCatalogImages(item, fallbackImage) {
+    const images = [];
+    const seen = new Set();
+    const source = item || {};
+    appendImage(images, seen, source.featuredImage);
+    appendImage(images, seen, source.imageUrl);
+    appendImage(images, seen, source.image);
+    appendImage(images, seen, source.photo);
+    appendImage(images, seen, source.thumbnail);
+    appendImage(images, seen, source.productImage);
+    appendImageList(images, seen, source.gallery);
+    appendImageList(images, seen, source.images);
+    appendImageList(images, seen, source.additionalImages);
+    if (images.length === 0) {
+        appendImage(images, seen, fallbackImage);
+    }
+    return images;
+}
+function resolveCatalogPrimaryImage(item, fallbackImage) {
+    return resolveCatalogImages(item, fallbackImage)[0] || '';
+}

package/dist/utils/index.d.ts

@@ -1,3 +1,4 @@
 export * from './urls';
 export * from './responsive';
 export * from './productOptions';
+export * from './catalogMedia';

package/dist/utils/index.js

@@ -17,3 +17,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./urls"), exports);
 __exportStar(require("./responsive"), exports);
 __exportStar(require("./productOptions"), exports);
+__exportStar(require("./catalogMedia"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deneb-ui/ui",
-  "version": "2.0.126",
+  "version": "2.0.127",
   "description": "Visual-first React component library for editable commerce storefronts. Built for Next.js and Fivora.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -50,7 +50,7 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@deneb-ui/core": "^2.0.126"
+    "@deneb-ui/core": "^2.0.127"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",