@shopware/helpers 1.4.0 → 1.6.0

package/README.md

@@ -36,10 +36,25 @@ export default defineConfig({
 
 Full changelog for stable version is available [here](https://github.com/shopware/frontends/blob/main/packages/helpers/CHANGELOG.md)
 
-### Latest changes: 1.4.0
+### Latest changes: 1.6.0
 
 ### Minor Changes
 
-- [#1602](https://github.com/shopware/frontends/pull/1602) [`bb7d1cb`](https://github.com/shopware/frontends/commit/bb7d1cbc4204ff1d48f77416f94f550bc235e5ed) Thanks [@patzick](https://github.com/patzick)! - Switch from `@shopware-pwa/helpers-next` to `@shopware/helpers` package.
+- [#1985](https://github.com/shopware/frontends/pull/1985) [`2cbda25`](https://github.com/shopware/frontends/commit/2cbda257a1056454e12f2fba9052f83eecb6d986) Thanks [@mkucmus](https://github.com/mkucmus)! - Added methods to extract product info:
+  - `isProductOnSale`
+  - `isProductTopSeller`
+  - `getProductManufacturerName`
 
-- [#1602](https://github.com/shopware/frontends/pull/1602) [`bb7d1cb`](https://github.com/shopware/frontends/commit/bb7d1cbc4204ff1d48f77416f94f550bc235e5ed) Thanks [@patzick](https://github.com/patzick)! - Switch from `@shopware-pwa/cms-base` to `@shopware/cms-base-layer` package.
+- [#2176](https://github.com/shopware/frontends/pull/2176) [`c647baf`](https://github.com/shopware/frontends/commit/c647baf93e7174b849f5961ee5803add99d78602) Thanks [@mkucmus](https://github.com/mkucmus)! - - Add `getProductListingFromCmsPage` helper to extract product listing from CMS page structure
+  - Enable early access to listing data during SSR before component tree renders
+
+### Patch Changes
+
+- [#2030](https://github.com/shopware/frontends/pull/2030) [`22ff62e`](https://github.com/shopware/frontends/commit/22ff62e354f024599d64ea8096af57695248851c) Thanks [@mkucmus](https://github.com/mkucmus)! - Extended `ListingFilter` type to support property options and manufacturer entities:
+  - Added optional `options` property for property group options
+  - Added optional `entities` property for manufacturer entities
+  - Improved type safety by explicitly typing empty array return in `getListingFilters()`
+
+- [#2153](https://github.com/shopware/frontends/pull/2153) [`56cd178`](https://github.com/shopware/frontends/commit/56cd178e25fe2399b7170ccac3044e980621f041) Thanks [@mkucmus](https://github.com/mkucmus)! - Fix `getSrcSetForMedia` to properly encode special characters (spaces, commas, parentheses) in media URLs
+
+- [#2162](https://github.com/shopware/frontends/pull/2162) [`e1fae3e`](https://github.com/shopware/frontends/commit/e1fae3eb6430e5c8e133456fbaf7f215f80c36f6) Thanks [@mkucmus](https://github.com/mkucmus)! - Export encodeUrlPath helper function to properly handle special characters (spaces, commas) in image URLs

package/dist/index.d.mts

@@ -22,7 +22,7 @@ declare function getProductFreeShipping<T extends {
  * @category Product
  */
 declare function getMainImageUrl<T extends {
-    cover?: {
+    cover: {
         media?: {
             url: string;
         };
@@ -34,9 +34,11 @@ declare function getMainImageUrl<T extends {
         };
     }>;
 } | {
-    cover?: {
+    cover: {
         url: string;
     };
+} | {
+    cover: null;
 }>(object: T): string;
 
 /**
@@ -205,6 +207,18 @@ declare function getProductFromPrice<T extends {
     calculatedPrices?: CalculatedPrice[];
 }>(product: T): number | undefined;
 
+interface ProductWithManufacturer {
+    manufacturer?: {
+        translated?: {
+            name?: string;
+        };
+    };
+}
+/**
+ * Gets the translated name of the product manufacturer
+ */
+declare function getProductManufacturerName(product: ProductWithManufacturer): string;
+
 /**
  * Get product route information for Vue router.
  *
@@ -228,6 +242,24 @@ declare function getProductRoute<T extends {
     };
 };
 
+/**
+ * Checks if a product is on sale based on its price percentage
+ */
+declare function isProductOnSale(product: {
+    calculatedPrice: {
+        listPrice?: {
+            percentage?: number;
+        } | null;
+    };
+}): boolean;
+
+/**
+ * Checks if a product is marked as a top seller
+ */
+declare function isProductTopSeller(product: {
+    markAsTopseller?: boolean;
+}): boolean;
+
 /**
  * Get URL for category.
  * Some link {@link isLinkCategory}
@@ -418,6 +450,35 @@ declare function getCmsBreadcrumbs<T extends {
     name: string;
 }[];
 
+type CmsPageStructure = {
+    sections: Array<{
+        blocks?: Array<{
+            slots?: Array<{
+                type?: string;
+                data?: unknown;
+                [key: string]: unknown;
+            }>;
+            [key: string]: unknown;
+        }>;
+        [key: string]: unknown;
+    }>;
+    [key: string]: unknown;
+};
+/**
+ * Extracts the product listing data from a CMS page structure.
+ * Useful for SSR to get listing data early before components render.
+ *
+ * @param cmsPage - The CMS page object (Schemas["CmsPage"])
+ * @returns The product listing result or null if not found
+ *
+ * @example
+ * ```ts
+ * const listing = getProductListingFromCmsPage(cmsPage);
+ * createCategoryListingContext(listing);
+ * ```
+ */
+declare function getProductListingFromCmsPage<T = unknown>(cmsPage: CmsPageStructure): T | null;
+
 type Category = {
     apiAlias: "category";
 };
@@ -475,6 +536,18 @@ type ListingFilter = {
     code: string;
     id: string;
     name: string;
+    options?: Array<{
+        id: string;
+        translated?: {
+            name?: string;
+        };
+    }>;
+    entities?: Array<{
+        id: string;
+        translated?: {
+            name?: string;
+        };
+    }>;
 };
 /**
  * @beta
@@ -557,6 +630,16 @@ declare function getSmallestThumbnailUrl<T extends {
     }>;
 }>(media?: T): string | undefined;
 
+/**
+ * Encodes URL pathname to handle special characters (spaces, commas, etc.)
+ *
+ * @param urlString - The URL string to encode
+ * @returns The URL with encoded pathname
+ *
+ * @public
+ * @category Media
+ */
+declare function encodeUrlPath(urlString: string): string;
 /**
  * Returns the srcset attribute for the image, for available breakpoints
  *
@@ -584,6 +667,24 @@ declare function getShippingMethodDeliveryTime<T extends {
     };
 }>(shippingMethod: T): string | undefined;
 
+/**
+ * Get shipping method icon
+ */
+declare function getShippingMethodIcon<T extends {
+    media?: {
+        url: string;
+    };
+}>(shippingMethod: T): string;
+
+/**
+ * Get payment method icon
+ */
+declare function getPaymentMethodIcon<T extends {
+    media?: {
+        url: string;
+    };
+}>(paymentMethod: T): string;
+
 /**
  * Get translated language name
  *
@@ -614,4 +715,4 @@ declare function canUseQuoteActions<T extends {
     };
 }>(quote: T): boolean;
 
-export { type HelpersCssClasses, type LayoutConfiguration, type TierPrice, type UiMediaGalleryItem, type UiMediaGalleryItemUrl, type UiProductOption, type UiProductProperty, type UiProductReview, buildUrlPrefix, canUseQuoteActions, downloadFile, getBackgroundImageUrl, getBiggestThumbnailUrl, getCategoryBreadcrumbs, getCategoryImageUrl, getCategoryRoute, getCategoryUrl, getCmsBreadcrumbs, getCmsEntityObject, getCmsLayoutConfiguration, getCmsTranslate, getFormattedPrice, getLanguageName, getListingFilters, getMainImageUrl, getMedia, getProductCalculatedListingPrice, getProductFreeShipping, getProductFromPrice, getProductName, getProductRatingAverage, getProductReviews, getProductRoute, getProductTierPrices, getProductUrl, getShippingMethodDeliveryTime, getSmallestThumbnailUrl, getSrcSetForMedia, getTranslatedProperty, helpersCssClasses, isCategory, isLandingPage, isMaintenanceMode, isProduct, relativeUrlSlash, urlIsAbsolute };
+export { type HelpersCssClasses, type LayoutConfiguration, type TierPrice, type UiMediaGalleryItem, type UiMediaGalleryItemUrl, type UiProductOption, type UiProductProperty, type UiProductReview, type UrlRouteOutput, buildUrlPrefix, canUseQuoteActions, downloadFile, encodeUrlPath, getBackgroundImageUrl, getBiggestThumbnailUrl, getCategoryBreadcrumbs, getCategoryImageUrl, getCategoryRoute, getCategoryUrl, getCmsBreadcrumbs, getCmsEntityObject, getCmsLayoutConfiguration, getCmsTranslate, getFormattedPrice, getLanguageName, getListingFilters, getMainImageUrl, getMedia, getPaymentMethodIcon, getProductCalculatedListingPrice, getProductFreeShipping, getProductFromPrice, getProductListingFromCmsPage, getProductManufacturerName, getProductName, getProductRatingAverage, getProductReviews, getProductRoute, getProductTierPrices, getProductUrl, getShippingMethodDeliveryTime, getShippingMethodIcon, getSmallestThumbnailUrl, getSrcSetForMedia, getTranslatedProperty, helpersCssClasses, isCategory, isLandingPage, isMaintenanceMode, isProduct, isProductOnSale, isProductTopSeller, relativeUrlSlash, urlIsAbsolute };

package/dist/index.d.ts

@@ -22,7 +22,7 @@ declare function getProductFreeShipping<T extends {
  * @category Product
  */
 declare function getMainImageUrl<T extends {
-    cover?: {
+    cover: {
         media?: {
             url: string;
         };
@@ -34,9 +34,11 @@ declare function getMainImageUrl<T extends {
         };
     }>;
 } | {
-    cover?: {
+    cover: {
         url: string;
     };
+} | {
+    cover: null;
 }>(object: T): string;
 
 /**
@@ -205,6 +207,18 @@ declare function getProductFromPrice<T extends {
     calculatedPrices?: CalculatedPrice[];
 }>(product: T): number | undefined;
 
+interface ProductWithManufacturer {
+    manufacturer?: {
+        translated?: {
+            name?: string;
+        };
+    };
+}
+/**
+ * Gets the translated name of the product manufacturer
+ */
+declare function getProductManufacturerName(product: ProductWithManufacturer): string;
+
 /**
  * Get product route information for Vue router.
  *
@@ -228,6 +242,24 @@ declare function getProductRoute<T extends {
     };
 };
 
+/**
+ * Checks if a product is on sale based on its price percentage
+ */
+declare function isProductOnSale(product: {
+    calculatedPrice: {
+        listPrice?: {
+            percentage?: number;
+        } | null;
+    };
+}): boolean;
+
+/**
+ * Checks if a product is marked as a top seller
+ */
+declare function isProductTopSeller(product: {
+    markAsTopseller?: boolean;
+}): boolean;
+
 /**
  * Get URL for category.
  * Some link {@link isLinkCategory}
@@ -418,6 +450,35 @@ declare function getCmsBreadcrumbs<T extends {
     name: string;
 }[];
 
+type CmsPageStructure = {
+    sections: Array<{
+        blocks?: Array<{
+            slots?: Array<{
+                type?: string;
+                data?: unknown;
+                [key: string]: unknown;
+            }>;
+            [key: string]: unknown;
+        }>;
+        [key: string]: unknown;
+    }>;
+    [key: string]: unknown;
+};
+/**
+ * Extracts the product listing data from a CMS page structure.
+ * Useful for SSR to get listing data early before components render.
+ *
+ * @param cmsPage - The CMS page object (Schemas["CmsPage"])
+ * @returns The product listing result or null if not found
+ *
+ * @example
+ * ```ts
+ * const listing = getProductListingFromCmsPage(cmsPage);
+ * createCategoryListingContext(listing);
+ * ```
+ */
+declare function getProductListingFromCmsPage<T = unknown>(cmsPage: CmsPageStructure): T | null;
+
 type Category = {
     apiAlias: "category";
 };
@@ -475,6 +536,18 @@ type ListingFilter = {
     code: string;
     id: string;
     name: string;
+    options?: Array<{
+        id: string;
+        translated?: {
+            name?: string;
+        };
+    }>;
+    entities?: Array<{
+        id: string;
+        translated?: {
+            name?: string;
+        };
+    }>;
 };
 /**
  * @beta
@@ -557,6 +630,16 @@ declare function getSmallestThumbnailUrl<T extends {
     }>;
 }>(media?: T): string | undefined;
 
+/**
+ * Encodes URL pathname to handle special characters (spaces, commas, etc.)
+ *
+ * @param urlString - The URL string to encode
+ * @returns The URL with encoded pathname
+ *
+ * @public
+ * @category Media
+ */
+declare function encodeUrlPath(urlString: string): string;
 /**
  * Returns the srcset attribute for the image, for available breakpoints
  *
@@ -584,6 +667,24 @@ declare function getShippingMethodDeliveryTime<T extends {
     };
 }>(shippingMethod: T): string | undefined;
 
+/**
+ * Get shipping method icon
+ */
+declare function getShippingMethodIcon<T extends {
+    media?: {
+        url: string;
+    };
+}>(shippingMethod: T): string;
+
+/**
+ * Get payment method icon
+ */
+declare function getPaymentMethodIcon<T extends {
+    media?: {
+        url: string;
+    };
+}>(paymentMethod: T): string;
+
 /**
  * Get translated language name
  *
@@ -614,4 +715,4 @@ declare function canUseQuoteActions<T extends {
     };
 }>(quote: T): boolean;
 
-export { type HelpersCssClasses, type LayoutConfiguration, type TierPrice, type UiMediaGalleryItem, type UiMediaGalleryItemUrl, type UiProductOption, type UiProductProperty, type UiProductReview, buildUrlPrefix, canUseQuoteActions, downloadFile, getBackgroundImageUrl, getBiggestThumbnailUrl, getCategoryBreadcrumbs, getCategoryImageUrl, getCategoryRoute, getCategoryUrl, getCmsBreadcrumbs, getCmsEntityObject, getCmsLayoutConfiguration, getCmsTranslate, getFormattedPrice, getLanguageName, getListingFilters, getMainImageUrl, getMedia, getProductCalculatedListingPrice, getProductFreeShipping, getProductFromPrice, getProductName, getProductRatingAverage, getProductReviews, getProductRoute, getProductTierPrices, getProductUrl, getShippingMethodDeliveryTime, getSmallestThumbnailUrl, getSrcSetForMedia, getTranslatedProperty, helpersCssClasses, isCategory, isLandingPage, isMaintenanceMode, isProduct, relativeUrlSlash, urlIsAbsolute };
+export { type HelpersCssClasses, type LayoutConfiguration, type TierPrice, type UiMediaGalleryItem, type UiMediaGalleryItemUrl, type UiProductOption, type UiProductProperty, type UiProductReview, type UrlRouteOutput, buildUrlPrefix, canUseQuoteActions, downloadFile, encodeUrlPath, getBackgroundImageUrl, getBiggestThumbnailUrl, getCategoryBreadcrumbs, getCategoryImageUrl, getCategoryRoute, getCategoryUrl, getCmsBreadcrumbs, getCmsEntityObject, getCmsLayoutConfiguration, getCmsTranslate, getFormattedPrice, getLanguageName, getListingFilters, getMainImageUrl, getMedia, getPaymentMethodIcon, getProductCalculatedListingPrice, getProductFreeShipping, getProductFromPrice, getProductListingFromCmsPage, getProductManufacturerName, getProductName, getProductRatingAverage, getProductReviews, getProductRoute, getProductTierPrices, getProductUrl, getShippingMethodDeliveryTime, getShippingMethodIcon, getSmallestThumbnailUrl, getSrcSetForMedia, getTranslatedProperty, helpersCssClasses, isCategory, isLandingPage, isMaintenanceMode, isProduct, isProductOnSale, isProductTopSeller, relativeUrlSlash, urlIsAbsolute };

package/dist/index.mjs

@@ -3,8 +3,7 @@ function getProductFreeShipping(product) {
 }
 
 function getMainImageUrl(object) {
-  if (!object)
-    return "";
+  if (!object) return "";
   if ("cover" in object && object.cover) {
     if ("media" in object.cover) {
       return object?.cover?.media?.url || "";
@@ -58,8 +57,7 @@ function getProductTierPrices(product) {
 }
 
 function getProductUrl(product) {
-  if (!product)
-    return "/";
+  if (!product) return "/";
   const seoUrl = product.seoUrls?.[0]?.seoPathInfo;
   return seoUrl ? `/${seoUrl}` : `/detail/${product.id}`;
 }
@@ -89,8 +87,12 @@ function getProductFromPrice(product) {
   }
   const realPrice = getProductRealPrice(product);
   const displayFromPriceLabel = (product.calculatedPrices?.length ?? 0) > 0;
-  if (displayFromPriceLabel)
-    return realPrice?.unitPrice;
+  if (displayFromPriceLabel) return realPrice?.unitPrice;
+  return void 0;
+}
+
+function getProductManufacturerName(product) {
+  return product.manufacturer?.translated?.name || "";
 }
 
 function getProductRoute(product) {
@@ -103,6 +105,14 @@ function getProductRoute(product) {
   };
 }
 
+function isProductOnSale(product) {
+  return (product.calculatedPrice?.listPrice?.percentage ?? 0) > 0;
+}
+
+function isProductTopSeller(product) {
+  return !!product.markAsTopseller;
+}
+
 function getEntityPrefix(category) {
   switch (category.linkType) {
     case "category":
@@ -111,11 +121,12 @@ function getEntityPrefix(category) {
       return "detail";
     case "landing_page":
       return "landingPage";
+    default:
+      return "navigation";
   }
 }
 function getCategoryUrl(category) {
-  if (!category)
-    return "/";
+  if (!category) return "/";
   switch (category.type) {
     case void 0:
       return "/";
@@ -136,8 +147,7 @@ function getCategoryImageUrl(category) {
 function getCategoryBreadcrumbs(category, options) {
   const breadcrumbs = category?.translated?.breadcrumb || category?.breadcrumb || [];
   const startIndex = options?.startIndex || 0;
-  if (breadcrumbs.length <= startIndex)
-    return [];
+  if (breadcrumbs.length <= startIndex) return [];
   return breadcrumbs.slice(startIndex).map((element) => {
     return {
       name: element
@@ -146,8 +156,7 @@ function getCategoryBreadcrumbs(category, options) {
 }
 
 function getCategoryRoute(category) {
-  if (!category)
-    return "/";
+  if (!category) return "/";
   if (category.type === "page" || category.type === "link" && category.linkType === "category") {
     return {
       path: getCategoryUrl(category),
@@ -266,8 +275,7 @@ function urlIsAbsolute(url) {
 
 function buildUrlPrefix(url, prefix) {
   if (typeof url === "string") {
-    if (urlIsAbsolute(url))
-      return { path: url };
+    if (urlIsAbsolute(url)) return { path: url };
     const resultUrl = url[0] !== "/" ? `/${url}` : url;
     return { path: prefix ? `/${prefix}${resultUrl}` : resultUrl };
   }
@@ -290,8 +298,7 @@ function isMaintenanceMode(errors) {
 }
 
 function getCmsTranslate(key, params) {
-  if (!params)
-    return key;
+  if (!params) return key;
   let translatedText = key;
   for (const param in params) {
     const placeholder = `{${param}}`;
@@ -313,6 +320,12 @@ function getCmsBreadcrumbs(page) {
   ];
 }
 
+function getProductListingFromCmsPage(cmsPage) {
+  const slot = cmsPage.sections.flatMap((section) => section.blocks ?? []).flatMap((block) => block.slots ?? []).find((slot2) => slot2.type === "product-listing");
+  const listing = slot?.data?.listing;
+  return listing ?? null;
+}
+
 function getCmsEntityObject(response) {
   switch (response.resourceType) {
     case "frontend.detail.page":
@@ -423,12 +436,21 @@ function getSmallestThumbnailUrl(media) {
   return lowest?.url;
 }
 
+function encodeUrlPath(urlString) {
+  try {
+    const url = new URL(urlString);
+    url.pathname = url.pathname.split("/").map((segment) => encodeURIComponent(decodeURIComponent(segment))).join("/");
+    return url.toString();
+  } catch {
+    return urlString;
+  }
+}
 function getSrcSetForMedia(media) {
   if (!media?.thumbnails?.length) {
     return;
   }
   return media.thumbnails.map((thumbnail) => {
-    return thumbnail.url ? `${thumbnail.url} ${thumbnail.width}w` : void 0;
+    return thumbnail.url ? `${encodeUrlPath(thumbnail.url)} ${thumbnail.width}w` : void 0;
   }).filter((value) => !!value).join(", ");
 }
 
@@ -436,6 +458,14 @@ function getShippingMethodDeliveryTime(shippingMethod) {
   return shippingMethod.deliveryTime?.translated.name;
 }
 
+function getShippingMethodIcon(shippingMethod) {
+  return shippingMethod.media?.url ?? "";
+}
+
+function getPaymentMethodIcon(paymentMethod) {
+  return paymentMethod.media?.url ?? "";
+}
+
 function getLanguageName(language) {
   return language.translationCode?.translated.name || "";
 }
@@ -452,4 +482,4 @@ function canUseQuoteActions(quote) {
   return ["replied"].includes(quote.stateMachineState?.technicalName ?? "");
 }
 
-export { buildUrlPrefix, canUseQuoteActions, downloadFile, getBackgroundImageUrl, getBiggestThumbnailUrl, getCategoryBreadcrumbs, getCategoryImageUrl, getCategoryRoute, getCategoryUrl, getCmsBreadcrumbs, getCmsEntityObject, getCmsLayoutConfiguration, getCmsTranslate, getFormattedPrice, getLanguageName, getListingFilters, getMainImageUrl, getMedia, getProductCalculatedListingPrice, getProductFreeShipping, getProductFromPrice, getProductName, getProductRatingAverage, getProductReviews, getProductRoute, getProductTierPrices, getProductUrl, getShippingMethodDeliveryTime, getSmallestThumbnailUrl, getSrcSetForMedia, getTranslatedProperty, helpersCssClasses, isCategory, isLandingPage, isMaintenanceMode, isProduct, relativeUrlSlash, urlIsAbsolute };
+export { buildUrlPrefix, canUseQuoteActions, downloadFile, encodeUrlPath, getBackgroundImageUrl, getBiggestThumbnailUrl, getCategoryBreadcrumbs, getCategoryImageUrl, getCategoryRoute, getCategoryUrl, getCmsBreadcrumbs, getCmsEntityObject, getCmsLayoutConfiguration, getCmsTranslate, getFormattedPrice, getLanguageName, getListingFilters, getMainImageUrl, getMedia, getPaymentMethodIcon, getProductCalculatedListingPrice, getProductFreeShipping, getProductFromPrice, getProductListingFromCmsPage, getProductManufacturerName, getProductName, getProductRatingAverage, getProductReviews, getProductRoute, getProductTierPrices, getProductUrl, getShippingMethodDeliveryTime, getShippingMethodIcon, getSmallestThumbnailUrl, getSrcSetForMedia, getTranslatedProperty, helpersCssClasses, isCategory, isLandingPage, isMaintenanceMode, isProduct, isProductOnSale, isProductTopSeller, relativeUrlSlash, urlIsAbsolute };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shopware/helpers",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Shopware helpers for accessing API data",
   "author": "Shopware",
   "type": "module",
@@ -33,10 +33,10 @@
   },
   "devDependencies": {
     "@biomejs/biome": "1.8.3",
-    "@vitest/coverage-v8": "2.1.8",
-    "happy-dom": "16.6.0",
+    "@vitest/coverage-v8": "3.2.4",
+    "happy-dom": "20.0.10",
     "unbuild": "2.0.0",
-    "vitest": "2.1.8",
+    "vitest": "3.2.4",
     "tsconfig": "0.0.0"
   },
   "scripts": {