@shopware/helpers 1.6.0 → 1.7.0

package/README.md

@@ -30,31 +30,107 @@ export default defineConfig({
 });
 ```
 
+## `getBackgroundImageUrl` helper
+
+The `getBackgroundImageUrl` function generates optimized CSS `url()` values for CMS background images. It extracts the raw URL, calculates the appropriate dimensions based on the media metadata, and applies image transformation parameters.
+
+### Usage
+
+```ts
+import { getBackgroundImageUrl } from "@shopware/helpers";
+
+const optimizedUrl = getBackgroundImageUrl(
+  "url(https://cdn.shopware.store/.../image.jpg)",
+  cmsBlockOrSection, // object with backgroundMedia.metaData.width/height
+  { format: "webp", quality: 85 }, // optional
+);
+// => 'url("https://cdn.shopware.store/.../image.jpg?width=1000&fit=crop,smart&format=webp&quality=85")'
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | `string` | CSS `url()` string containing the background image URL |
+| `element` | `{ backgroundMedia?: { metaData?: { width?: number; height?: number } } }` | CMS section or block object with media metadata |
+| `options` | `BackgroundImageOptions` (optional) | Format and quality settings |
+
+### `BackgroundImageOptions`
+
+```ts
+type BackgroundImageOptions = {
+  format?: string; // "webp" | "avif" | "jpg" | "png"
+  quality?: number; // 0-100
+};
+```
+
+When `format` or `quality` are provided, they are appended as query parameters to the image URL. If omitted, only the dimension and fit parameters are applied.
+
+## `generateCdnSrcSet` helper
+
+Generates an HTML `srcset` string using CDN width-based resizing. Useful as a fallback when media has no pre-generated thumbnails — the CDN handles on-the-fly resizing via query parameters.
+
+### Usage
+
+```ts
+import { generateCdnSrcSet } from "@shopware/helpers";
+
+const srcset = generateCdnSrcSet(
+  "https://cdn.shopware.store/.../image.jpg",
+  [400, 800, 1200, 1600], // optional, these are the defaults
+  { format: "webp", quality: 85 }, // optional
+);
+// => "https://cdn.shopware.store/.../image.jpg?width=400&fit=crop,smart&format=webp&quality=85 400w, ...800w, ...1200w, ...1600w"
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `src` | `string \| undefined` | Base image URL |
+| `widths` | `number[]` (optional) | Array of widths to generate (default: `[400, 800, 1200, 1600]`) |
+| `options` | `{ format?: string; quality?: number }` (optional) | Format and quality settings |
+
+Returns `undefined` if `src` is falsy or URL parsing fails.
+
+## `buildCdnImageUrl` helper
+
+Builds an optimized CDN image URL with size parameters based on rendered element dimensions. Adds `width` or `height` (whichever is larger) rounded up to the nearest 100px, plus `fit=crop,smart`.
+
+### Usage
+
+```ts
+import { buildCdnImageUrl } from "@shopware/helpers";
+
+const url = buildCdnImageUrl(
+  "https://cdn.shopware.store/.../image.jpg",
+  { width: 724, height: 760 },
+);
+// => "https://cdn.shopware.store/.../image.jpg?height=800&fit=crop,smart"
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `src` | `string \| undefined` | Base image URL |
+| `dimensions` | `{ width: number; height: number }` | Rendered element dimensions in pixels |
+| `options` | `{ format?: string; quality?: number }` (optional) | Format and quality settings |
+
+Returns an empty string if `src` is falsy. Returns the original `src` if URL parsing fails.
+
 <!-- AUTO GENERATED CHANGELOG -->
 
 ## Changelog
 
 Full changelog for stable version is available [here](https://github.com/shopware/frontends/blob/main/packages/helpers/CHANGELOG.md)
 
-### Latest changes: 1.6.0
+### Latest changes: 1.7.0
 
 ### Minor Changes
 
-- [#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
+- [#2287](https://github.com/shopware/frontends/pull/2287) [`c9bde38`](https://github.com/shopware/frontends/commit/c9bde38d497d5c6c2fbd97700a362eb44ce8881f) Thanks [@mkucmus](https://github.com/mkucmus)! - Add generateCdnSrcSet and buildCdnImageUrl helpers for synthetic responsive image srcset generation via CDN query params
 
 ### 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
+- [#2320](https://github.com/shopware/frontends/pull/2320) [`a871c7b`](https://github.com/shopware/frontends/commit/a871c7b6256b75c2e40d93fc0354ba1971420062) Thanks [@mdanilowicz](https://github.com/mdanilowicz)! - Improve getSmallestThumbnailUrl - add media.url fallback when thumbnails are missing or empty

package/dist/index.d.mts

@@ -397,6 +397,10 @@ type LayoutConfiguration = {
  */
 declare function getCmsLayoutConfiguration<T extends CmsBlock | CmsSection | CmsSlot>(content: T): LayoutConfiguration;
 
+type BackgroundImageOptions = {
+    format?: string;
+    quality?: number;
+};
 declare function getBackgroundImageUrl<T extends {
     backgroundMedia?: {
         metaData?: {
@@ -404,7 +408,7 @@ declare function getBackgroundImageUrl<T extends {
             height?: number;
         };
     };
-}>(url: string, element: T): string;
+}>(url: string, element: T, options?: BackgroundImageOptions): string;
 
 type UrlRoute = {
     path?: string;
@@ -616,7 +620,7 @@ declare function getMedia<T extends {
 }>(lineItem: T): ProductMedia[];
 
 /**
- * Returns the smallest thumbnail url from the media object
+ * Returns the smallest thumbnail url from the media object or the media.url if no thumbnails are available
  *
  * @param media image object
  *
@@ -628,6 +632,7 @@ declare function getSmallestThumbnailUrl<T extends {
         width: number;
         url: string;
     }>;
+    url?: string;
 }>(media?: T): string | undefined;
 
 /**
@@ -640,6 +645,41 @@ declare function getSmallestThumbnailUrl<T extends {
  * @category Media
  */
 declare function encodeUrlPath(urlString: string): string;
+/**
+ * Generates a srcset string using CDN width-based resizing.
+ * Useful as a fallback when media has no pre-generated thumbnails.
+ *
+ * @param src - Base image URL
+ * @param widths - Array of widths to generate (default: [400, 800, 1200, 1600])
+ * @param options - Optional format and quality params
+ * @returns srcset string or undefined if src is invalid
+ *
+ * @public
+ * @category Media
+ */
+declare function generateCdnSrcSet(src: string | undefined, widths?: number[], options?: {
+    format?: string;
+    quality?: number;
+}): string | undefined;
+/**
+ * Builds an optimized CDN image URL with size parameters.
+ * Adds width or height (whichever is larger, width if equal)
+ * rounded up to the nearest 100px.
+ *
+ * @param src - Base image URL
+ * @param dimensions - Rendered element dimensions (width and height)
+ * @returns Optimized image URL string
+ *
+ * @public
+ * @category Media
+ */
+declare function buildCdnImageUrl(src: string | undefined, dimensions: {
+    width: number;
+    height: number;
+}, options?: {
+    format?: string;
+    quality?: number;
+}): string;
 /**
  * Returns the srcset attribute for the image, for available breakpoints
  *
@@ -715,4 +755,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, 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 };
+export { type BackgroundImageOptions, type HelpersCssClasses, type LayoutConfiguration, type TierPrice, type UiMediaGalleryItem, type UiMediaGalleryItemUrl, type UiProductOption, type UiProductProperty, type UiProductReview, type UrlRouteOutput, buildCdnImageUrl, buildUrlPrefix, canUseQuoteActions, downloadFile, encodeUrlPath, generateCdnSrcSet, 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

@@ -397,6 +397,10 @@ type LayoutConfiguration = {
  */
 declare function getCmsLayoutConfiguration<T extends CmsBlock | CmsSection | CmsSlot>(content: T): LayoutConfiguration;
 
+type BackgroundImageOptions = {
+    format?: string;
+    quality?: number;
+};
 declare function getBackgroundImageUrl<T extends {
     backgroundMedia?: {
         metaData?: {
@@ -404,7 +408,7 @@ declare function getBackgroundImageUrl<T extends {
             height?: number;
         };
     };
-}>(url: string, element: T): string;
+}>(url: string, element: T, options?: BackgroundImageOptions): string;
 
 type UrlRoute = {
     path?: string;
@@ -616,7 +620,7 @@ declare function getMedia<T extends {
 }>(lineItem: T): ProductMedia[];
 
 /**
- * Returns the smallest thumbnail url from the media object
+ * Returns the smallest thumbnail url from the media object or the media.url if no thumbnails are available
  *
  * @param media image object
  *
@@ -628,6 +632,7 @@ declare function getSmallestThumbnailUrl<T extends {
         width: number;
         url: string;
     }>;
+    url?: string;
 }>(media?: T): string | undefined;
 
 /**
@@ -640,6 +645,41 @@ declare function getSmallestThumbnailUrl<T extends {
  * @category Media
  */
 declare function encodeUrlPath(urlString: string): string;
+/**
+ * Generates a srcset string using CDN width-based resizing.
+ * Useful as a fallback when media has no pre-generated thumbnails.
+ *
+ * @param src - Base image URL
+ * @param widths - Array of widths to generate (default: [400, 800, 1200, 1600])
+ * @param options - Optional format and quality params
+ * @returns srcset string or undefined if src is invalid
+ *
+ * @public
+ * @category Media
+ */
+declare function generateCdnSrcSet(src: string | undefined, widths?: number[], options?: {
+    format?: string;
+    quality?: number;
+}): string | undefined;
+/**
+ * Builds an optimized CDN image URL with size parameters.
+ * Adds width or height (whichever is larger, width if equal)
+ * rounded up to the nearest 100px.
+ *
+ * @param src - Base image URL
+ * @param dimensions - Rendered element dimensions (width and height)
+ * @returns Optimized image URL string
+ *
+ * @public
+ * @category Media
+ */
+declare function buildCdnImageUrl(src: string | undefined, dimensions: {
+    width: number;
+    height: number;
+}, options?: {
+    format?: string;
+    quality?: number;
+}): string;
 /**
  * Returns the srcset attribute for the image, for available breakpoints
  *
@@ -715,4 +755,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, 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 };
+export { type BackgroundImageOptions, type HelpersCssClasses, type LayoutConfiguration, type TierPrice, type UiMediaGalleryItem, type UiMediaGalleryItemUrl, type UiProductOption, type UiProductProperty, type UiProductReview, type UrlRouteOutput, buildCdnImageUrl, buildUrlPrefix, canUseQuoteActions, downloadFile, encodeUrlPath, generateCdnSrcSet, 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

@@ -260,12 +260,18 @@ const getUrlFromBackgroundImage = (url) => {
   const match = url.match(regex);
   return !match ? url : match[1];
 };
-function getBackgroundImageUrl(url, element) {
+function getBackgroundImageUrl(url, element, options) {
   const backgroundImage = getUrlFromBackgroundImage(url);
   const width = element.backgroundMedia?.metaData?.width ?? 0;
   const height = element.backgroundMedia?.metaData?.height ?? 0;
   const biggestParam = width > height ? `width=${roundUp(width > 1920 ? 1900 : width)}` : `height=${roundUp(height > 1920 ? 1900 : height)}`;
-  const srcPath = `${backgroundImage}?${biggestParam}&fit=crop,smart`;
+  let srcPath = `${backgroundImage}?${biggestParam}&fit=crop,smart`;
+  if (options?.format) {
+    srcPath += `&format=${options.format}`;
+  }
+  if (options?.quality) {
+    srcPath += `&quality=${options.quality}`;
+  }
   return `url("${srcPath}")`;
 }
 
@@ -428,6 +434,9 @@ function getMedia(lineItem) {
 
 function getSmallestThumbnailUrl(media) {
   if (!media || !media?.thumbnails?.length) {
+    if (media?.url) {
+      return media.url;
+    }
     return;
   }
   const lowest = media.thumbnails.reduce((previous, current) => {
@@ -445,6 +454,51 @@ function encodeUrlPath(urlString) {
     return urlString;
   }
 }
+function generateCdnSrcSet(src, widths = [400, 800, 1200, 1600], options) {
+  if (!src) return void 0;
+  try {
+    return widths.map((w) => {
+      const url = new URL(encodeUrlPath(src));
+      url.searchParams.set("width", String(w));
+      url.searchParams.set("fit", "crop,smart");
+      if (options?.format) {
+        url.searchParams.set("format", options.format);
+      }
+      if (options?.quality) {
+        url.searchParams.set("quality", String(options.quality));
+      }
+      return `${url.toString()} ${w}w`;
+    }).join(", ");
+  } catch {
+    return void 0;
+  }
+}
+function buildCdnImageUrl(src, dimensions, options) {
+  if (!src) return "";
+  try {
+    const url = new URL(encodeUrlPath(src));
+    const DEFAULT_SIZE = 10;
+    const w = dimensions.width ? Math.ceil(dimensions.width / 100) * 100 : DEFAULT_SIZE;
+    const h = dimensions.height ? Math.ceil(dimensions.height / 100) * 100 : DEFAULT_SIZE;
+    if (w > DEFAULT_SIZE || h > DEFAULT_SIZE) {
+      if (dimensions.width >= dimensions.height) {
+        url.searchParams.set("width", String(w));
+      } else {
+        url.searchParams.set("height", String(h));
+      }
+      url.searchParams.set("fit", "crop,smart");
+    }
+    if (options?.format) {
+      url.searchParams.set("format", options.format);
+    }
+    if (options?.quality) {
+      url.searchParams.set("quality", String(options.quality));
+    }
+    return url.toString();
+  } catch {
+    return src;
+  }
+}
 function getSrcSetForMedia(media) {
   if (!media?.thumbnails?.length) {
     return;
@@ -482,4 +536,4 @@ function canUseQuoteActions(quote) {
   return ["replied"].includes(quote.stateMachineState?.technicalName ?? "");
 }
 
-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 };
+export { buildCdnImageUrl, buildUrlPrefix, canUseQuoteActions, downloadFile, encodeUrlPath, generateCdnSrcSet, 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.6.0",
+  "version": "1.7.0",
   "description": "Shopware helpers for accessing API data",
   "author": "Shopware",
   "type": "module",
@@ -33,19 +33,20 @@
   },
   "devDependencies": {
     "@biomejs/biome": "1.8.3",
-    "@vitest/coverage-v8": "3.2.4",
-    "happy-dom": "20.0.10",
+    "@typescript/native-preview": "7.0.0-dev.20260111.1",
+    "@vitest/coverage-v8": "4.0.18",
+    "happy-dom": "20.8.9",
     "unbuild": "2.0.0",
-    "vitest": "3.2.4",
+    "vitest": "4.0.18",
     "tsconfig": "0.0.0"
   },
   "scripts": {
     "build": "unbuild && pnpm build:types",
-    "build:types": "tsc ./src/*.ts --declaration --allowJs --emitDeclarationOnly --outDir ./temp --skipLibCheck",
+    "build:types": "tsgo ./src/*.ts --ignoreConfig --declaration --allowJs --emitDeclarationOnly --outDir ./temp --skipLibCheck",
     "dev": "unbuild --stub",
     "lint": "biome check .",
     "lint:fix": "biome check . --write && pnpm run typecheck",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsgo --noEmit",
     "test": "vitest run",
     "test:watch": "vitest"
   }