@shopware/helpers 1.7.2 → 1.8.0

package/README.md

@@ -125,8 +125,14 @@ 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.2
+### Latest changes: 1.8.0
+
+### Minor Changes
+
+- [#2574](https://github.com/shopware/frontends/pull/2574) [`2ddf156`](https://github.com/shopware/frontends/commit/2ddf156805b2941fe2069e78453fb3c4eb6d44ac) Thanks [@mkucmus](https://github.com/mkucmus)! - Add `getCategoryFilterAggregations()` and `getCategoryFilterPostFilter()` to request category aggregations for product listings and filter by category without reducing the aggregations. `excludeRootCategory()` drops the sales channel entry point from the category entities, and the `CATEGORY_AGGREGATION_NAME` / `CATEGORY_COUNTS_AGGREGATION_NAME` / `CATEGORY_PARENTS_AGGREGATION_NAME` constants are exported for consumers that build the aggregations themselves.
+
+  `getListingFilters` (`@beta`) merges the `categories` and `categories-counts` response aggregations into a single `categories` filter with a product count per category. This changes the shape of that filter for listings that already requested a `categories` aggregation: the entities are sorted by count (highest first) instead of keeping the response order, each entity gains a `count`, the filter no longer carries the aggregation's `apiAlias`, and `categories-counts` is no longer returned as a filter of its own.
 
 ### Patch Changes
 
-- [#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.
+- [#2598](https://github.com/shopware/frontends/pull/2598) [`204c8f4`](https://github.com/shopware/frontends/commit/204c8f45f737e724db6d00b80c5faef8ddb77cb4) Thanks [@dependabot](https://github.com/apps/dependabot)! - Fix Nuxt plugin injection typing for Nuxt 4.5 and maintenance mode error handling.

package/dist/index.d.mts

@@ -427,7 +427,7 @@ type HelpersCssClasses = (typeof helpersCssClasses)[number];
 
 declare function isMaintenanceMode<T extends {
     code?: string;
-}>(errors: [T]): boolean;
+}>(errors: T[]): boolean;
 
 /**
  * Replace text placeholder with param value
@@ -561,6 +561,61 @@ declare function getCanonicalPathForTechnicalPath(path: string, seoUrl?: object
  */
 declare function getTranslatedProperty<T>(element: T | undefined | null | never, property: keyof T): string;
 
+declare const CATEGORY_AGGREGATION_NAME = "categories";
+declare const CATEGORY_COUNTS_AGGREGATION_NAME = "categories-counts";
+declare const CATEGORY_PARENTS_AGGREGATION_NAME = "categories-parents";
+type CategoryEntityAggregation = {
+    name: string;
+    type: "entity";
+    definition: "category";
+    field: string;
+};
+type CategoryCountsAggregation = {
+    name: string;
+    type: "terms";
+    field: string;
+};
+type CategoryFilterBucket = {
+    key: string;
+    count: number;
+} & {
+    [nestedAggregationName: string]: unknown;
+};
+/**
+ * Category aggregations for a listing filter: an entity `categories` agg plus a
+ * flat `categories-counts` terms agg. Kept flat because the ES search route
+ * returns no buckets once a nested sub-agg is attached, so variants overcount.
+ *
+ * @beta
+ */
+declare function getCategoryFilterAggregations(): Array<CategoryEntityAggregation | CategoryCountsAggregation>;
+/**
+ * Category filter entities without the sales channel entry point.
+ *
+ * That root category is an ancestor of every product's category tree, so it
+ * matches the whole result set and filtering by it changes nothing. Opt in per
+ * listing by passing `sessionContext.salesChannel.navigationCategoryId`;
+ * without an id the entities are returned unchanged.
+ *
+ * @beta
+ */
+declare function excludeRootCategory<T extends {
+    id: string;
+}>(entities: T[] | undefined | null, rootCategoryId: string | undefined | null): T[];
+/**
+ * Criteria `post-filter` entry narrowing a product listing to the given
+ * category ids. Sent as a post-filter, it does not reduce the category
+ * aggregations from `getCategoryFilterAggregations`, so all category options
+ * stay visible while results are filtered (standard faceted behavior).
+ *
+ * @beta
+ */
+declare function getCategoryFilterPostFilter(categoryIds: string[]): {
+    field: string;
+    type: "equalsAny";
+    value: string;
+};
+
 type ListingFilter = {
     label: string;
     code: string;
@@ -577,6 +632,7 @@ type ListingFilter = {
         translated?: {
             name?: string;
         };
+        count?: number;
     }>;
 };
 /**
@@ -781,5 +837,5 @@ declare function canUseQuoteActions<T extends {
     };
 }>(quote: T): boolean;
 
-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 };
+export { CATEGORY_AGGREGATION_NAME, CATEGORY_COUNTS_AGGREGATION_NAME, CATEGORY_PARENTS_AGGREGATION_NAME, buildCdnImageUrl, buildUrlPrefix, canUseQuoteActions, downloadFile, encodeUrlPath, excludeRootCategory, generateCdnSrcSet, getBackgroundImageUrl, getBiggestThumbnailUrl, getCanonicalPathForTechnicalPath, getCategoryBreadcrumbs, getCategoryFilterAggregations, getCategoryFilterPostFilter, 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, CategoryFilterBucket, HelpersCssClasses, LayoutConfiguration, RouteInfoFromPathInfo, RouteNameFromPathInfo, TierPrice, UiMediaGalleryItem, UiMediaGalleryItemUrl, UiProductOption, UiProductProperty, UiProductReview, UrlRouteOutput };

package/dist/index.d.ts

@@ -427,7 +427,7 @@ type HelpersCssClasses = (typeof helpersCssClasses)[number];
 
 declare function isMaintenanceMode<T extends {
     code?: string;
-}>(errors: [T]): boolean;
+}>(errors: T[]): boolean;
 
 /**
  * Replace text placeholder with param value
@@ -561,6 +561,61 @@ declare function getCanonicalPathForTechnicalPath(path: string, seoUrl?: object
  */
 declare function getTranslatedProperty<T>(element: T | undefined | null | never, property: keyof T): string;
 
+declare const CATEGORY_AGGREGATION_NAME = "categories";
+declare const CATEGORY_COUNTS_AGGREGATION_NAME = "categories-counts";
+declare const CATEGORY_PARENTS_AGGREGATION_NAME = "categories-parents";
+type CategoryEntityAggregation = {
+    name: string;
+    type: "entity";
+    definition: "category";
+    field: string;
+};
+type CategoryCountsAggregation = {
+    name: string;
+    type: "terms";
+    field: string;
+};
+type CategoryFilterBucket = {
+    key: string;
+    count: number;
+} & {
+    [nestedAggregationName: string]: unknown;
+};
+/**
+ * Category aggregations for a listing filter: an entity `categories` agg plus a
+ * flat `categories-counts` terms agg. Kept flat because the ES search route
+ * returns no buckets once a nested sub-agg is attached, so variants overcount.
+ *
+ * @beta
+ */
+declare function getCategoryFilterAggregations(): Array<CategoryEntityAggregation | CategoryCountsAggregation>;
+/**
+ * Category filter entities without the sales channel entry point.
+ *
+ * That root category is an ancestor of every product's category tree, so it
+ * matches the whole result set and filtering by it changes nothing. Opt in per
+ * listing by passing `sessionContext.salesChannel.navigationCategoryId`;
+ * without an id the entities are returned unchanged.
+ *
+ * @beta
+ */
+declare function excludeRootCategory<T extends {
+    id: string;
+}>(entities: T[] | undefined | null, rootCategoryId: string | undefined | null): T[];
+/**
+ * Criteria `post-filter` entry narrowing a product listing to the given
+ * category ids. Sent as a post-filter, it does not reduce the category
+ * aggregations from `getCategoryFilterAggregations`, so all category options
+ * stay visible while results are filtered (standard faceted behavior).
+ *
+ * @beta
+ */
+declare function getCategoryFilterPostFilter(categoryIds: string[]): {
+    field: string;
+    type: "equalsAny";
+    value: string;
+};
+
 type ListingFilter = {
     label: string;
     code: string;
@@ -577,6 +632,7 @@ type ListingFilter = {
         translated?: {
             name?: string;
         };
+        count?: number;
     }>;
 };
 /**
@@ -781,5 +837,5 @@ declare function canUseQuoteActions<T extends {
     };
 }>(quote: T): boolean;
 
-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 };
+export { CATEGORY_AGGREGATION_NAME, CATEGORY_COUNTS_AGGREGATION_NAME, CATEGORY_PARENTS_AGGREGATION_NAME, buildCdnImageUrl, buildUrlPrefix, canUseQuoteActions, downloadFile, encodeUrlPath, excludeRootCategory, generateCdnSrcSet, getBackgroundImageUrl, getBiggestThumbnailUrl, getCanonicalPathForTechnicalPath, getCategoryBreadcrumbs, getCategoryFilterAggregations, getCategoryFilterPostFilter, 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, CategoryFilterBucket, HelpersCssClasses, LayoutConfiguration, RouteInfoFromPathInfo, RouteNameFromPathInfo, TierPrice, UiMediaGalleryItem, UiMediaGalleryItemUrl, UiProductOption, UiProductProperty, UiProductReview, UrlRouteOutput };

package/dist/index.mjs

@@ -396,6 +396,48 @@ function getCanonicalPathForTechnicalPath(path, seoUrl) {
   return canonicalPath;
 }
 
+const CATEGORY_AGGREGATION_NAME = "categories";
+const CATEGORY_COUNTS_AGGREGATION_NAME = "categories-counts";
+const CATEGORY_PARENTS_AGGREGATION_NAME = "categories-parents";
+const CATEGORY_FIELD = "categoriesRo.id";
+function getCategoryFilterAggregations() {
+  return [
+    {
+      name: CATEGORY_AGGREGATION_NAME,
+      type: "entity",
+      definition: "category",
+      field: CATEGORY_FIELD
+    },
+    {
+      name: CATEGORY_COUNTS_AGGREGATION_NAME,
+      type: "terms",
+      field: CATEGORY_FIELD
+    }
+  ];
+}
+function excludeRootCategory(entities, rootCategoryId) {
+  if (!entities) return [];
+  return entities.filter((entity) => entity.id !== rootCategoryId);
+}
+function getCategoryFilterPostFilter(categoryIds) {
+  return {
+    field: CATEGORY_FIELD,
+    type: "equalsAny",
+    value: categoryIds.join("|")
+  };
+}
+function resolveCategoryBucketCount(bucket) {
+  const parents = bucket[CATEGORY_PARENTS_AGGREGATION_NAME];
+  if (!parents?.buckets) {
+    return bucket.count;
+  }
+  let count = 0;
+  for (const parent of parents.buckets) {
+    count += parent.key ? 1 : parent.count;
+  }
+  return count;
+}
+
 const getFilter = (code, aggregation) => {
   return {
     label: getTranslatedProperty(aggregation, "name") || code,
@@ -406,6 +448,30 @@ const getFilter = (code, aggregation) => {
 function isEntitiesAggregation(aggregation) {
   return aggregation.entities !== void 0;
 }
+function getCategoryFilter(aggregation, countsAggregation) {
+  const countByCategoryId = /* @__PURE__ */ new Map();
+  for (const bucket of countsAggregation?.buckets ?? []) {
+    countByCategoryId.set(bucket.key, resolveCategoryBucketCount(bucket));
+  }
+  const entities = aggregation.entities.map((entity) => ({
+    ...entity,
+    // Count per category. Used to sort here and exposed to consumers, but on
+    // the ES search route it counts every variant, so the filter UIs shipped
+    // in this repo do not render it.
+    count: countByCategoryId.get(entity.id)
+  })).sort(
+    (a, b) => (b.count ?? 0) - (a.count ?? 0) || getTranslatedProperty(a, "name").localeCompare(
+      getTranslatedProperty(b, "name")
+    )
+  );
+  return {
+    label: CATEGORY_AGGREGATION_NAME,
+    code: CATEGORY_AGGREGATION_NAME,
+    id: CATEGORY_AGGREGATION_NAME,
+    name: CATEGORY_AGGREGATION_NAME,
+    entities
+  };
+}
 function getListingFilters(aggregations) {
   if (!aggregations) {
     return [];
@@ -416,7 +482,16 @@ function getListingFilters(aggregations) {
       for (const filterEntity of aggregation.entities) {
         transformedFilters.push(getFilter(aggregationName, filterEntity));
       }
-    } else if (!["properties", "options"].includes(aggregationName)) {
+    } else if (aggregationName === CATEGORY_AGGREGATION_NAME && isEntitiesAggregation(aggregation)) {
+      transformedFilters.push(
+        getCategoryFilter(
+          aggregation,
+          aggregations[CATEGORY_COUNTS_AGGREGATION_NAME]
+        )
+      );
+    } else if (!["properties", "options", CATEGORY_COUNTS_AGGREGATION_NAME].includes(
+      aggregationName
+    )) {
       transformedFilters.push(getFilter(aggregationName, aggregation));
     }
   }
@@ -580,4 +655,4 @@ function canUseQuoteActions(quote) {
   return ["replied"].includes(quote.stateMachineState?.technicalName ?? "");
 }
 
-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 { CATEGORY_AGGREGATION_NAME, CATEGORY_COUNTS_AGGREGATION_NAME, CATEGORY_PARENTS_AGGREGATION_NAME, buildCdnImageUrl, buildUrlPrefix, canUseQuoteActions, downloadFile, encodeUrlPath, excludeRootCategory, generateCdnSrcSet, getBackgroundImageUrl, getBiggestThumbnailUrl, getCanonicalPathForTechnicalPath, getCategoryBreadcrumbs, getCategoryFilterAggregations, getCategoryFilterPostFilter, 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.2",
+  "version": "1.8.0",
   "description": "Shopware helpers for accessing API data",
   "author": "Shopware",
   "type": "module",
@@ -34,7 +34,7 @@
   "devDependencies": {
     "@typescript/native-preview": "7.0.0-dev.20260205.1",
     "@vitest/coverage-v8": "4.1.10",
-    "happy-dom": "20.10.6",
+    "happy-dom": "20.11.1",
     "unbuild": "3.6.1",
     "vitest": "4.1.10",
     "tsconfig": "0.0.0"