@shopware/helpers 1.5.0 → 1.6.0

package/README.md

@@ -36,8 +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.5.0
+### Latest changes: 1.6.0
 
 ### Minor Changes
 
-- [#1910](https://github.com/shopware/frontends/pull/1910) [`c8fa438`](https://github.com/shopware/frontends/commit/c8fa438b38de6dbc43a2895f2d1906907447c384) Thanks [@mdanilowicz](https://github.com/mdanilowicz)! - Add helper for getting payment and shipping method icon
+- [#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`
+
+- [#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
  *
@@ -632,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, getPaymentMethodIcon, getProductCalculatedListingPrice, getProductFreeShipping, getProductFromPrice, getProductName, getProductRatingAverage, getProductReviews, getProductRoute, getProductTierPrices, getProductUrl, getShippingMethodDeliveryTime, getShippingMethodIcon, 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
  *
@@ -632,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, getPaymentMethodIcon, getProductCalculatedListingPrice, getProductFreeShipping, getProductFromPrice, getProductName, getProductRatingAverage, getProductReviews, getProductRoute, getProductTierPrices, getProductUrl, getShippingMethodDeliveryTime, getShippingMethodIcon, 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

@@ -91,6 +91,10 @@ function getProductFromPrice(product) {
   return void 0;
 }
 
+function getProductManufacturerName(product) {
+  return product.manufacturer?.translated?.name || "";
+}
+
 function getProductRoute(product) {
   return {
     path: getProductUrl(product),
@@ -101,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":
@@ -308,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":
@@ -418,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(", ");
 }
 
@@ -455,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, getPaymentMethodIcon, getProductCalculatedListingPrice, getProductFreeShipping, getProductFromPrice, getProductName, getProductRatingAverage, getProductReviews, getProductRoute, getProductTierPrices, getProductUrl, getShippingMethodDeliveryTime, getShippingMethodIcon, 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.5.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": "3.2.3",
-    "happy-dom": "18.0.1",
+    "@vitest/coverage-v8": "3.2.4",
+    "happy-dom": "20.0.10",
     "unbuild": "2.0.0",
-    "vitest": "3.2.3",
+    "vitest": "3.2.4",
     "tsconfig": "0.0.0"
   },
   "scripts": {