@shopware/helpers 1.7.1 → 1.7.2

package/README.md

@@ -2,9 +2,9 @@
 
 Welcome to `@shopware/helpers` package.
 
-For getting started documentation visit [https://frontends.shopware.com/](https://frontends.shopware.com/)
+For getting started documentation visit [https://developer.shopware.com/frontends/](https://developer.shopware.com/frontends/)
 
-Documentation specific for this package: [helpers](https://frontends.shopware.com/packages/helpers.html)
+Documentation specific for this package: [helpers](https://developer.shopware.com/frontends/packages/helpers.html)
 
 ## Reusable classes
 
@@ -49,11 +49,11 @@ const optimizedUrl = getBackgroundImageUrl(
 
 ### 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 |
+| 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`
 
@@ -85,11 +85,11 @@ const srcset = generateCdnSrcSet(
 
 ### 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 |
+| 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.
 
@@ -102,20 +102,20 @@ Builds an optimized CDN image URL with size parameters based on rendered element
 ```ts
 import { buildCdnImageUrl } from "@shopware/helpers";
 
-const url = buildCdnImageUrl(
-  "https://cdn.shopware.store/.../image.jpg",
-  { width: 724, height: 760 },
-);
+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 |
+| 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.
 
@@ -125,13 +125,8 @@ Returns an empty string if `src` is falsy. Returns the original `src` if URL par
 
 Full changelog for stable version is available [here](https://github.com/shopware/frontends/blob/main/packages/helpers/CHANGELOG.md)
 
-### Latest changes: 1.7.1
+### Latest changes: 1.7.2
 
 ### Patch Changes
 
-- [#2372](https://github.com/shopware/frontends/pull/2372) [`22fc8a7`](https://github.com/shopware/frontends/commit/22fc8a7301f6a7d2612d907ab73555978b651c00) Thanks [@patzick](https://github.com/patzick)! - Improve technical URL resolution for SSR and CSR page rendering.
-
-  This adds helpers to detect and normalize technical Shopware paths and updates
-  `useNavigationSearch` to resolve `/navigation/*`, `/detail/*`, and
-  `/landingPage/*` routes more reliably, including fallback behavior when no SEO
-  mapping row is returned.
+- [#2594](https://github.com/shopware/frontends/pull/2594) [`f16c5a0`](https://github.com/shopware/frontends/commit/f16c5a0785d6187b73c3edcf37feab7c90bd7988) Thanks [@patzick](https://github.com/patzick)! - Add helpers for resolving canonical SEO paths and detecting technical Shopware URLs.

package/dist/index.d.mts

@@ -538,7 +538,19 @@ type RouteInfoFromPathInfo = {
 };
 declare function normalizePath(path: string): string;
 declare function isTechnicalPath(path: string): boolean;
+/**
+ * Check whether an absolute or relative URL points to a technical Shopware
+ * route. Query parameters and fragments are ignored.
+ */
+declare function isTechnicalUrl(url: string, baseUrl?: string): boolean;
 declare function getRouteFromPathInfo(path: string): RouteInfoFromPathInfo | null;
+/**
+ * Get the canonical path for a mapped technical Shopware URL.
+ *
+ * Returns `null` for SEO URLs, synthetic technical fallbacks without an SEO
+ * mapping, and invalid mappings that would redirect to another technical URL.
+ */
+declare function getCanonicalPathForTechnicalPath(path: string, seoUrl?: object | null): string | null;
 
 /**
  * Get translated property from the given object.
@@ -769,5 +781,5 @@ declare function canUseQuoteActions<T extends {
     };
 }>(quote: T): boolean;
 
-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, getRouteFromPathInfo, getShippingMethodDeliveryTime, getShippingMethodIcon, getSmallestThumbnailUrl, getSrcSetForMedia, getTranslatedProperty, helpersCssClasses, isCategory, isLandingPage, isMaintenanceMode, isProduct, isProductOnSale, isProductTopSeller, isTechnicalPath, normalizePath, relativeUrlSlash, urlIsAbsolute };
+export { buildCdnImageUrl, buildUrlPrefix, canUseQuoteActions, downloadFile, encodeUrlPath, generateCdnSrcSet, getBackgroundImageUrl, getBiggestThumbnailUrl, getCanonicalPathForTechnicalPath, 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, getRouteFromPathInfo, getShippingMethodDeliveryTime, getShippingMethodIcon, getSmallestThumbnailUrl, getSrcSetForMedia, getTranslatedProperty, helpersCssClasses, isCategory, isLandingPage, isMaintenanceMode, isProduct, isProductOnSale, isProductTopSeller, isTechnicalPath, isTechnicalUrl, normalizePath, relativeUrlSlash, urlIsAbsolute };
 export type { BackgroundImageOptions, HelpersCssClasses, LayoutConfiguration, RouteInfoFromPathInfo, RouteNameFromPathInfo, TierPrice, UiMediaGalleryItem, UiMediaGalleryItemUrl, UiProductOption, UiProductProperty, UiProductReview, UrlRouteOutput };

package/dist/index.d.ts

@@ -538,7 +538,19 @@ type RouteInfoFromPathInfo = {
 };
 declare function normalizePath(path: string): string;
 declare function isTechnicalPath(path: string): boolean;
+/**
+ * Check whether an absolute or relative URL points to a technical Shopware
+ * route. Query parameters and fragments are ignored.
+ */
+declare function isTechnicalUrl(url: string, baseUrl?: string): boolean;
 declare function getRouteFromPathInfo(path: string): RouteInfoFromPathInfo | null;
+/**
+ * Get the canonical path for a mapped technical Shopware URL.
+ *
+ * Returns `null` for SEO URLs, synthetic technical fallbacks without an SEO
+ * mapping, and invalid mappings that would redirect to another technical URL.
+ */
+declare function getCanonicalPathForTechnicalPath(path: string, seoUrl?: object | null): string | null;
 
 /**
  * Get translated property from the given object.
@@ -769,5 +781,5 @@ declare function canUseQuoteActions<T extends {
     };
 }>(quote: T): boolean;
 
-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, getRouteFromPathInfo, getShippingMethodDeliveryTime, getShippingMethodIcon, getSmallestThumbnailUrl, getSrcSetForMedia, getTranslatedProperty, helpersCssClasses, isCategory, isLandingPage, isMaintenanceMode, isProduct, isProductOnSale, isProductTopSeller, isTechnicalPath, normalizePath, relativeUrlSlash, urlIsAbsolute };
+export { buildCdnImageUrl, buildUrlPrefix, canUseQuoteActions, downloadFile, encodeUrlPath, generateCdnSrcSet, getBackgroundImageUrl, getBiggestThumbnailUrl, getCanonicalPathForTechnicalPath, 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, getRouteFromPathInfo, getShippingMethodDeliveryTime, getShippingMethodIcon, getSmallestThumbnailUrl, getSrcSetForMedia, getTranslatedProperty, helpersCssClasses, isCategory, isLandingPage, isMaintenanceMode, isProduct, isProductOnSale, isProductTopSeller, isTechnicalPath, isTechnicalUrl, normalizePath, relativeUrlSlash, urlIsAbsolute };
 export type { BackgroundImageOptions, HelpersCssClasses, LayoutConfiguration, RouteInfoFromPathInfo, RouteNameFromPathInfo, TierPrice, UiMediaGalleryItem, UiMediaGalleryItemUrl, UiProductOption, UiProductProperty, UiProductReview, UrlRouteOutput };

package/dist/index.mjs

@@ -366,6 +366,13 @@ function isTechnicalPath(path) {
     (prefix) => normalizedPath.startsWith(prefix)
   );
 }
+function isTechnicalUrl(url, baseUrl = "http://localhost") {
+  try {
+    return isTechnicalPath(new URL(url, baseUrl).pathname);
+  } catch {
+    return false;
+  }
+}
 function getRouteFromPathInfo(path) {
   const normalizedPath = normalizePath(path);
   for (const [prefix, routeName] of Object.entries(TECHNICAL_ROUTE_MAP)) {
@@ -379,6 +386,15 @@ function getRouteFromPathInfo(path) {
   }
   return null;
 }
+function getCanonicalPathForTechnicalPath(path, seoUrl) {
+  if (!isTechnicalPath(path) || !seoUrl || !("seoPathInfo" in seoUrl) || typeof seoUrl.seoPathInfo !== "string") {
+    return null;
+  }
+  const seoPathInfo = seoUrl.seoPathInfo.replace(/^\/+/, "");
+  const canonicalPath = seoPathInfo ? normalizePath(`/${seoPathInfo}`) : "/";
+  if (isTechnicalPath(canonicalPath)) return null;
+  return canonicalPath;
+}
 
 const getFilter = (code, aggregation) => {
   return {
@@ -564,4 +580,4 @@ function canUseQuoteActions(quote) {
   return ["replied"].includes(quote.stateMachineState?.technicalName ?? "");
 }
 
-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, getRouteFromPathInfo, getShippingMethodDeliveryTime, getShippingMethodIcon, getSmallestThumbnailUrl, getSrcSetForMedia, getTranslatedProperty, helpersCssClasses, isCategory, isLandingPage, isMaintenanceMode, isProduct, isProductOnSale, isProductTopSeller, isTechnicalPath, normalizePath, relativeUrlSlash, urlIsAbsolute };
+export { buildCdnImageUrl, buildUrlPrefix, canUseQuoteActions, downloadFile, encodeUrlPath, generateCdnSrcSet, getBackgroundImageUrl, getBiggestThumbnailUrl, getCanonicalPathForTechnicalPath, 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, getRouteFromPathInfo, getShippingMethodDeliveryTime, getShippingMethodIcon, getSmallestThumbnailUrl, getSrcSetForMedia, getTranslatedProperty, helpersCssClasses, isCategory, isLandingPage, isMaintenanceMode, isProduct, isProductOnSale, isProductTopSeller, isTechnicalPath, isTechnicalUrl, normalizePath, relativeUrlSlash, urlIsAbsolute };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shopware/helpers",
-  "version": "1.7.1",
+  "version": "1.7.2",
   "description": "Shopware helpers for accessing API data",
   "author": "Shopware",
   "type": "module",
@@ -8,7 +8,7 @@
     "type": "git",
     "url": "git+https://github.com/shopware/frontends.git"
   },
-  "homepage": "https://frontends.shopware.com/packages/helpers.html",
+  "homepage": "https://developer.shopware.com/frontends/packages/helpers.html",
   "keywords": [
     "shopware",
     "api",
@@ -32,20 +32,19 @@
     }
   },
   "devDependencies": {
-    "@biomejs/biome": "1.8.3",
     "@typescript/native-preview": "7.0.0-dev.20260205.1",
-    "@vitest/coverage-v8": "4.1.5",
-    "happy-dom": "20.9.0",
-    "unbuild": "2.0.0",
-    "vitest": "4.1.5",
+    "@vitest/coverage-v8": "4.1.10",
+    "happy-dom": "20.10.6",
+    "unbuild": "3.6.1",
+    "vitest": "4.1.10",
     "tsconfig": "0.0.0"
   },
   "scripts": {
     "build": "unbuild && pnpm build:types",
     "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",
+    "lint": "oxlint . && oxfmt --check .",
+    "lint:fix": "oxlint --fix . && oxfmt --write . && pnpm run typecheck",
     "typecheck": "tsgo --noEmit",
     "test": "vitest run",
     "test:watch": "vitest"