@shopware/cms-base-layer 3.1.0 → 4.0.0

package/README.md

@@ -192,10 +192,18 @@ Replace standard `<img>` tags with `<NuxtImg>` to enable automatic optimization:
   :src="product.cover.media.url"
   preset="productDetail"
   :width="800"
-  :alt="product.cover.media.alt"
+  :alt="getTranslatedProperty(product.cover.media, 'alt')"
 />
 ```
 
+The media `alt` text is a translatable field, so read it through `getTranslatedProperty` rather than
+`media.alt` — the latter always holds the system language value, no matter which language the current
+request asks for. The helper is not auto-imported, so add it to the component's script block:
+
+```ts
+import { getTranslatedProperty } from "@shopware/helpers";
+```
+
 ### Supported Modifiers
 
 Shopware supports the following URL parameters for image transformation:
@@ -350,7 +358,7 @@ url("https://cdn.shopware.store/.../image.jpg?width=1000&fit=crop,smart&format=w
 
 ## LCP Image Preload
 
-This layer includes a `useLcpImagePreload` composable that automatically preloads the first image found in CMS page content. This targets the [Largest Contentful Paint (LCP)](https://web.dev/lcp/) element, which is often a hero background image or the first visible image element.
+This layer includes a `useLcpImagePreload` composable that preloads the first image found in CMS page content when enabled via `lcpImagePreload: true` in your `app.config.ts` (disabled by default). This targets the [Largest Contentful Paint (LCP)](https://web.dev/lcp/) element, which is often a hero background image or the first visible image element.
 
 ### How it works
 
@@ -364,12 +372,10 @@ The first image found is injected as a `<link rel="preload" as="image" fetchprio
 
 ### Usage
 
-The composable is already called in `CmsPage.vue`. If you override `CmsPage`, you can use it in your custom component:
+The composable is already called in `CmsPage.vue`. If you override `CmsPage`, you can use it in your custom component. It is auto-imported once your app extends this layer, so it needs no import statement:
 
 ```vue
 <script setup>
-import { useLcpImagePreload } from "@shopware/cms-base-layer/composables/useLcpImagePreload";
-
 const props = defineProps<{ content: Schemas["CmsPage"] }>();
 
 useLcpImagePreload(props.content?.sections || []);
@@ -384,7 +390,7 @@ Images are optimized to prevent the browser from downloading images larger than
 
 ### Product Card Images (`SwProductCardImage`)
 
-The `productCard` preset only defines URL modifiers (format/quality/fit). `width`/`height`/`densities`/`loading` stay on the component — NuxtImg presets don't propagate these reliably:
+The `productCard` preset only defines URL modifiers (format/quality/fit). `width`/`height` and `loading` stay on the component: in `@nuxt/image` 2.1.0 a preset carries `width`/`height` only as `modifiers`, which shape the URL rather than the rendered attributes, and `loading` is not a preset field at all. `densities` is kept alongside them for consistency, though a preset would propagate it:
 
 ```ts
 // nuxt.config.ts
@@ -448,9 +454,9 @@ The list of available blocks and elements is [here](https://developer.shopware.c
 
 The procedure is:
 
-- find a component in component's [list](https://developer.shopware.com/frontends/packages/cms-base.html#available-components), using a [Vue devtools](https://devtools.vuejs.org/) or browsing the github [repository](https://github.com/shopware/frontends/tree/main/packages/cms-base-layer/app/components)
+- find a component in component's [list](https://developer.shopware.com/frontends/packages/cms-base-layer.html#available-components), using a [Vue devtools](https://devtools.vuejs.org/) or browsing the github [repository](https://github.com/shopware/frontends/tree/main/packages/cms-base-layer/app/components)
 - take its name
-- create a file with the same name and place it into `~/components` dir in your nuxt project (or wherever according your nuxt config)
+- create a file with the same name and place it under a `components` directory that your `nuxt.config.ts` registers with `global: true` — CMS components are looked up with `resolveComponent`, so an override outside a global path is never found and this layer's version keeps rendering with no error. In the starter template that directory is `app/components/cms/`; because it is registered with `pathPrefix: false`, the name comes from the filename alone and subdirectory depth under it does not matter.
 
 ✅ Thanks to this, nuxt will take the component registered in your app instead of the one registered by this nuxt layer.
 
@@ -485,31 +491,66 @@ No additional packages needed to be installed.
 
 Full changelog for stable version is available [here](https://github.com/shopware/frontends/blob/main/packages/cms-base-layer/CHANGELOG.md)
 
-### Latest changes: 3.1.0
+### Latest changes: 4.0.0
+
+### Major Changes
+
+- [#2609](https://github.com/shopware/frontends/pull/2609) [`2dc86da`](https://github.com/shopware/frontends/commit/2dc86da2532e986ebdadd06a922e68403414a0ff) Thanks [@mkucmus](https://github.com/mkucmus)! - Make the package a plain Nuxt layer.
+
+  **Breaking:** the package now declares an `exports` map, so only the layer entry point
+  is importable. Deep imports such as
+  `@shopware/cms-base-layer/app/components/SwProductCard.vue` no longer resolve. Use the
+  auto-registered global components instead, which is what extending the layer gives you.
+
+  **Breaking:** the leftover Nuxt module is gone, so `index.cjs` and the `dist` build are
+  no longer published. The module registered a component folder that moved to `app/` a
+  while ago, so it could not work any more. Consume this package with `extends`, which
+  resolves `nuxt.config.ts`:
+
+  ```ts
+  export default defineNuxtConfig({
+    extends: ["@shopware/cms-base-layer"],
+  });
+  ```
+
+  Other changes:
+
+  - Dropped the `build` and `dev` scripts and the `unbuild` dev dependency. There is
+    nothing left to bundle.
+  - Fixed `files`. It listed `helpers` and `app.config.ts`, which do not exist at the
+    package root, and shipped the dead `dist` and `index.cjs`.
+  - Deleted `components.d.ts`. It typed two components at paths that moved to
+    `app/components/public/cms/`, and no tsconfig referenced the file.
+  - Removed two vitest aliases that pointed at files which do not exist.
+  - Removed the `check-colors` script. It read `uno.config.ts` from this package, which
+    moved to `@shopware/unocss-design-tokens-layer`, so it always found zero colors. It
+    also relied on `tsx` without declaring it.
 
 ### Minor Changes
 
-- [#2503](https://github.com/shopware/frontends/pull/2503) [`1b0ccc9`](https://github.com/shopware/frontends/commit/1b0ccc95fcef89de42931155fb40119b9075d21b) Thanks [@mkucmus](https://github.com/mkucmus)! - `SwProductListingFilters` and `SwProductListingFiltersHorizontal`: honor the `listingType` prop. When set to `productSearchListing` the components drive `useProductSearchListing` instead of `useCategoryListing` and keep the active search term in the request criteria and resulting URL, so the shared filter sidebar can be reused on the product search page without resetting the query. Category listing behavior is unchanged.
+- [#2574](https://github.com/shopware/frontends/pull/2574) [`2ddf156`](https://github.com/shopware/frontends/commit/2ddf156805b2941fe2069e78453fb3c4eb6d44ac) Thanks [@mkucmus](https://github.com/mkucmus)! - `SwProductListingFilters` and `SwProductListingFiltersHorizontal` render a new `SwFilterCategories` checkbox filter when the listing response contains the category aggregations from `getCategoryFilterAggregations()`. The selection is kept in the `categories` URL param and applied as a criteria `post-filter`. Both are search listings only (`listing-type="productSearchListing"`); on any other listing the category filter is not rendered, because the selection would neither reach the URL nor the criteria. Listings without these aggregations are unaffected.
 
 ### Patch Changes
 
-- [#2593](https://github.com/shopware/frontends/pull/2593) [`760635c`](https://github.com/shopware/frontends/commit/760635cdbaf3c80ae99fbe0f42a31a8ebaa14675) Thanks [@patzick](https://github.com/patzick)! - Stop registering the `@unocss/nuxt` module from the CMS layer. UnoCSS is not a dependency of this package anymore (it lives in `@shopware/unocss-design-tokens-layer`), so registering the module made every app that doesn't install UnoCSS itself fail to build with `Could not load @unocss/nuxt. Is it installed?` - for example the blank template. Apps that want the shared UnoCSS setup keep getting it from `@shopware/unocss-design-tokens-layer` or their own `@unocss/nuxt` registration.
+- [#2645](https://github.com/shopware/frontends/pull/2645) [`7a7ce3e`](https://github.com/shopware/frontends/commit/7a7ce3e5649e7ab84f7e547ce1ebcd9413117dde) Thanks [@mkucmus](https://github.com/mkucmus)! - Ship `component-dirs.json` in the published package. `nuxt.config.ts` imports it at load time, but it was missing from `files`, so the layer failed to load when installed from the registry.
+
+- [#2660](https://github.com/shopware/frontends/pull/2660) [`8913956`](https://github.com/shopware/frontends/commit/89139563924163e57cafdd9770fe603f2dbd8cba) Thanks [@mdanilowicz](https://github.com/mdanilowicz)! - Read translatable entity fields through their `translated` object instead of the untranslated entity root, so they follow the language of the current request instead of rendering the system language. Affected components: `SwContactForm` and `SwNewsletterForm` (salutation `displayName`), `SwStockInfo` (delivery time `name`), `SwVariantConfigurator` (property group `name` — the option values below it already used `translated`), `CmsElementBuyBox` (unit `name`), `CmsElementCrossSelling` (cross selling `name`), `CmsElementProductDescriptionReviews` (category `name`), `SwProductCardImage` and `CmsElementImageGallery` (media `alt`).
 
-- [#2568](https://github.com/shopware/frontends/pull/2568) [`6315350`](https://github.com/shopware/frontends/commit/6315350add0464abef153343897d42f5808f2003) Thanks [@patzick](https://github.com/patzick)! - Add cacheable GET support for category details and product reviews while preserving the existing POST behavior when `cacheableReads` is disabled.
+  All of them now go through `getTranslatedProperty()` from `@shopware/helpers`, which falls back to the root property when `translated` is missing — so the rendered value only ever changes on storefronts whose language differs from the system language.
 
-  - `useCategorySearch.search` now calls `GET /category/{navigationId}` and sends the complete encoded Criteria in the `_criteria` query parameter when cacheable reads are enabled.
-  - `useProductReviews.loadProductReviews` now calls `GET /product/{productId}/reviews` and sends its encoded Criteria in `_criteria` when cacheable reads are enabled.
-  - The CMS product description reviews element follows the same flag and endpoint behavior when it needs to fetch reviews directly.
+- [#2606](https://github.com/shopware/frontends/pull/2606) [`1c9a604`](https://github.com/shopware/frontends/commit/1c9a604e05c0fa1b27708a5338cd5690a0ff5c67) Thanks [@mkucmus](https://github.com/mkucmus)! - Stop leaking internal types into the layer's public type surface.
 
-- [#2571](https://github.com/shopware/frontends/pull/2571) [`c64ae1c`](https://github.com/shopware/frontends/commit/c64ae1c6e2d11e33bd52df4b55177cc26b646433) Thanks [@patzick](https://github.com/patzick)! - Show the category a shopper came from in product breadcrumbs, while direct product links continue to use the default category.
+  - `index.d.ts` now only augments the app config. It no longer re-exports `@shopware/composables` and `./.nuxt/imports`.
+  - The `#imports` shim moved to a private `types/imports.d.ts`, which is not published.
+  - `app.config` exports a plain object with `satisfies AppConfigInput` instead of calling `defineAppConfig`. No runtime change.
 
-- [#2596](https://github.com/shopware/frontends/pull/2596) [`6572aa8`](https://github.com/shopware/frontends/commit/6572aa84431e1f4a34d6cf04e549037692d638a6) Thanks [@patzick](https://github.com/patzick)! - Reduce Rolldown/Vite build noise: scope Nuxt global components, keep the three.js async chunk warning intentional, avoid shipping full carbon icon JSON via UnoCSS runtime, and bump @vueuse to 14.4.0.
+  This fixes `Cannot find name 'ref'` and similar errors in the shared and node contexts when a project uses the Nuxt 4 project-references `tsconfig.json`.
 
-- [#2592](https://github.com/shopware/frontends/pull/2592) [`fcc3d71`](https://github.com/shopware/frontends/commit/fcc3d71af05c2f2d409aa63ecb562714e6bc0e69) Thanks [@patzick](https://github.com/patzick)! - Replace CMS layer `@apply` styles with plain CSS declarations to avoid Nuxt build warnings.
+- [#2601](https://github.com/shopware/frontends/pull/2601) [`e64d2f9`](https://github.com/shopware/frontends/commit/e64d2f9c13a99054d7e56e4b7ec2f1f23f9768b7) Thanks [@mdanilowicz](https://github.com/mdanilowicz)! - Typography for CMS-authored HTML is now scoped to a `cms-element-text` class and ships from the layer as `app/assets/css/rich-text.css`, with overflow guards for long strings, media, `pre` and tables. Headings and lists in your own markup that had no explicit size or `list-*` class were relying on the removed global rules and will change.
 
-- [#2568](https://github.com/shopware/frontends/pull/2568) [`6315350`](https://github.com/shopware/frontends/commit/6315350add0464abef153343897d42f5808f2003) Thanks [@patzick](https://github.com/patzick)! - Preserve CMS image aspect ratios when responsive dimensions are calculated after hydration, preventing visible image scaling as optimized sources load.
+- [#2663](https://github.com/shopware/frontends/pull/2663) [`7020545`](https://github.com/shopware/frontends/commit/70205458cb9357a068029d0aaef41898ab94b354) Thanks [@mkucmus](https://github.com/mkucmus)! - A linked CMS image always has an accessible name now. `CmsElementImage` names the link with the element's `ariaLabel`, then the media title, then a generic fallback translatable through `cms.image.linkWithoutLabel`. A decorative image skips the media title.
 
-- Updated dependencies [[`6315350`](https://github.com/shopware/frontends/commit/6315350add0464abef153343897d42f5808f2003), [`b767721`](https://github.com/shopware/frontends/commit/b767721847bf3391f9067eca7a045089fb22fce0), [`f16c5a0`](https://github.com/shopware/frontends/commit/f16c5a0785d6187b73c3edcf37feab7c90bd7988), [`978b02c`](https://github.com/shopware/frontends/commit/978b02c969ca4b16f5fc1d7a953ec4cce3d98173), [`6572aa8`](https://github.com/shopware/frontends/commit/6572aa84431e1f4a34d6cf04e549037692d638a6), [`744833b`](https://github.com/shopware/frontends/commit/744833b9d7d2f8ea1f5dfe65be3fa554dbe4a09f), [`e03c91b`](https://github.com/shopware/frontends/commit/e03c91be172374894d90b7a0111855b76719fee1), [`33facb1`](https://github.com/shopware/frontends/commit/33facb178792c8cb26b47ab984ac48c08ab4b72b), [`9137475`](https://github.com/shopware/frontends/commit/91374753cedb2034385f642e6af11314f2971caa), [`474d3fe`](https://github.com/shopware/frontends/commit/474d3fed346816135b0c7c797990b215a8b691c0), [`38379a5`](https://github.com/shopware/frontends/commit/38379a5d52ab09008774533ef417ebe2cde3f7fd)]:
-  - @shopware/composables@1.12.1
-  - @shopware/api-client@1.5.1
-  - @shopware/helpers@1.7.2
+- Updated dependencies [[`2ddf156`](https://github.com/shopware/frontends/commit/2ddf156805b2941fe2069e78453fb3c4eb6d44ac), [`204c8f4`](https://github.com/shopware/frontends/commit/204c8f45f737e724db6d00b80c5faef8ddb77cb4), [`7020545`](https://github.com/shopware/frontends/commit/70205458cb9357a068029d0aaef41898ab94b354), [`183c183`](https://github.com/shopware/frontends/commit/183c183f905486c27fa770fd0f4cd9993e86c20e), [`458494e`](https://github.com/shopware/frontends/commit/458494e8bd2be88d4fbf161636a109c8f4efc443), [`183c183`](https://github.com/shopware/frontends/commit/183c183f905486c27fa770fd0f4cd9993e86c20e), [`183c183`](https://github.com/shopware/frontends/commit/183c183f905486c27fa770fd0f4cd9993e86c20e), [`8913956`](https://github.com/shopware/frontends/commit/89139563924163e57cafdd9770fe603f2dbd8cba), [`458494e`](https://github.com/shopware/frontends/commit/458494e8bd2be88d4fbf161636a109c8f4efc443)]:
+  - @shopware/helpers@1.8.0
+  - @shopware/composables@1.13.0
+  - @shopware/api-client@1.6.0

package/app/app.config.ts

@@ -1,6 +1,6 @@
-import { defineAppConfig } from "#imports";
+import type { AppConfigInput } from "nuxt/schema";
 
-export default defineAppConfig({
+export default {
   imagePlaceholder: {
     color: "#543B95",
   },
@@ -16,4 +16,4 @@ export default defineAppConfig({
     default: "(max-width: 768px) 50vw, 25vw",
   },
   unocssRuntime: true,
-});
+} satisfies AppConfigInput;

package/app/assets/css/rich-text.css

@@ -0,0 +1,80 @@
+.cms-element-text {
+  word-break: break-word;
+
+  :where(h1, h2, h3, h4, h5, h6) {
+    margin-bottom: var(--rte-heading-mb, 10px);
+    font-weight: var(--rte-heading-weight, 600);
+  }
+
+  :where(h1) {
+    font-size: var(--rte-h1-size, 2.25rem);
+    line-height: var(--rte-h1-line, 2.5rem);
+  }
+
+  :where(h2) {
+    font-size: var(--rte-h2-size, 1.75rem);
+    line-height: var(--rte-h2-line, 2rem);
+  }
+
+  :where(h3) {
+    font-size: var(--rte-h3-size, 1.25rem);
+    line-height: var(--rte-h3-line, 1.5rem);
+  }
+
+  :where(h4, h5, h6) {
+    font-size: var(--rte-h4-size, 1.125rem);
+    line-height: var(--rte-h4-line, 1.5rem);
+  }
+
+  :where(p, blockquote, pre) {
+    margin-bottom: var(--rte-flow, 1rem);
+  }
+
+  :where(ol, ul, dl) {
+    list-style-type: disc;
+    padding-left: var(--rte-list-indent, 40px);
+    margin-top: 0;
+    margin-bottom: var(--rte-flow, 1rem);
+  }
+
+  :where(ol) {
+    list-style-type: decimal;
+  }
+
+  :where(img, iframe, video) {
+    max-width: 100%;
+  }
+
+  :where(img) {
+    height: auto;
+  }
+
+  :where(table) {
+    width: 100%;
+    margin-bottom: var(--rte-flow, 1rem);
+    border-collapse: collapse;
+  }
+
+  :where(th, td) {
+    padding: var(--rte-cell-padding, 0.5rem 0.75rem);
+    border: 1px solid var(--rte-border-color, #e5e7eb);
+  }
+
+  :where(th, thead td) {
+    text-align: left;
+    font-weight: var(--rte-heading-weight, 600);
+  }
+
+  :where(hr) {
+    margin: var(--rte-flow, 1rem) 0;
+    border-top: 1px solid var(--rte-border-color, #e5e7eb);
+  }
+
+  > :last-child {
+    margin-bottom: 0;
+  }
+
+  :where(.sw-text-editor-table__col-selector) {
+    display: none;
+  }
+}

package/app/components/SwContactForm.vue

@@ -3,6 +3,7 @@ import { ApiClientError } from "@shopware/api-client";
 import type { ApiError } from "@shopware/api-client";
 import type { CmsElementForm } from "@shopware/composables";
 import { useCmsTranslations } from "@shopware/composables";
+import { getTranslatedProperty } from "@shopware/helpers";
 import { useVuelidate } from "@vuelidate/core";
 import { email, minLength, required } from "@vuelidate/validators";
 import { defu } from "defu";
@@ -189,7 +190,7 @@ const invokeSubmit = async () => {
               :key="salutation.id"
               :value="salutation.id"
             >
-              {{ salutation.displayName }}
+              {{ getTranslatedProperty(salutation, "displayName") }}
             </option>
           </select>
         </div>

package/app/components/SwFilterChips.vue

@@ -6,6 +6,9 @@ import type { Schemas } from "#shopware";
 type FilterState = {
   manufacturer: Set<string>;
   properties: Set<string>;
+  // Optional: consumers building their own filter-state object predate this
+  // field, so a missing one must render no category chips, not throw.
+  categories?: Set<string>;
   "min-price": number | undefined;
   "max-price": number | undefined;
   rating: number | undefined;
@@ -70,13 +73,14 @@ const activeChips = computed(() => {
   }
 
   // Add manufacturer filters
-  const manufacturers = Array.from(props.filters.manufacturer);
-  for (const manufacturerId of manufacturers) {
-    const filter = props.availableFilters.find(
-      (f) => f.code === "manufacturer",
-    );
-    if (filter && "entities" in filter && filter.entities) {
-      const entity = filter.entities.find((e) => e.id === manufacturerId);
+  const manufacturerFilter = props.availableFilters.find(
+    (f) => f.code === "manufacturer",
+  );
+  if (manufacturerFilter?.entities) {
+    for (const manufacturerId of props.filters.manufacturer) {
+      const entity = manufacturerFilter.entities.find(
+        (e) => e.id === manufacturerId,
+      );
       const name = getTranslatedName(entity);
       if (name) {
         chips.push({
@@ -88,6 +92,24 @@ const activeChips = computed(() => {
     }
   }
 
+  // Add category filters
+  const categoryFilter = props.availableFilters.find(
+    (f) => f.code === "categories",
+  );
+  if (categoryFilter?.entities) {
+    for (const categoryId of props.filters.categories ?? []) {
+      const entity = categoryFilter.entities.find((e) => e.id === categoryId);
+      const name = getTranslatedName(entity);
+      if (name) {
+        chips.push({
+          label: name,
+          code: "categories",
+          value: categoryId,
+        });
+      }
+    }
+  }
+
   // Add price filters
   if (props.filters["min-price"] || props.filters["max-price"]) {
     const min = props.filters["min-price"] || 0;

package/app/components/SwNewsletterForm.vue

@@ -3,6 +3,7 @@ import { ApiClientError } from "@shopware/api-client";
 import type { ApiError } from "@shopware/api-client";
 import type { CmsElementForm } from "@shopware/composables";
 import { useCmsTranslations } from "@shopware/composables";
+import { getTranslatedProperty } from "@shopware/helpers";
 import { useVuelidate } from "@vuelidate/core";
 import type { ValidationRuleWithoutParams } from "@vuelidate/core";
 import { email, required } from "@vuelidate/validators";
@@ -247,7 +248,7 @@ const invokeSubmit = async () => {
               :key="salutation.id"
               :value="salutation.id"
             >
-              {{ salutation.displayName }}
+              {{ getTranslatedProperty(salutation, "displayName") }}
             </option>
           </select>
         </div>

package/app/components/SwProductCardImage.vue

@@ -2,6 +2,7 @@
 import {
   type UrlRouteOutput,
   getSmallestThumbnailUrl,
+  getTranslatedProperty,
   isProductOnSale,
   isProductTopSeller,
 } from "@shopware/helpers";
@@ -37,7 +38,10 @@ const coverSrcPath = computed(() => {
 });
 
 const coverAlt = computed(() => {
-  return props.product?.cover?.media?.alt || props.product?.translated?.name;
+  return (
+    getTranslatedProperty(props.product?.cover?.media, "alt") ||
+    props.product?.translated?.name
+  );
 });
 
 const isOnSale = computed(() => isProductOnSale(props.product));

package/app/components/SwProductListingFilter.vue

@@ -2,6 +2,7 @@
 import { computed } from "vue";
 import type { Component } from "vue";
 
+import SwFilterCategoriesVue from "./listing-filters/SwFilterCategories.vue";
 import SwFilterPriceVue from "./listing-filters/SwFilterPrice.vue";
 import SwFilterPropertiesVue from "./listing-filters/SwFilterProperties.vue";
 import SwFilterRatingVue from "./listing-filters/SwFilterRating.vue";
@@ -11,6 +12,7 @@ const {
   filter,
   selectedManufacturer,
   selectedProperties,
+  selectedCategories = new Set<string>(),
   selectedMinPrice,
   selectedMaxPrice,
   selectedRating,
@@ -20,6 +22,7 @@ const {
   filter: ListingFilter;
   selectedManufacturer: Set<string>;
   selectedProperties: Set<string>;
+  selectedCategories?: Set<string>;
   selectedMinPrice: number | undefined;
   selectedMaxPrice: number | undefined;
   selectedRating: number | undefined;
@@ -40,11 +43,13 @@ const transformedFilters = computed(() => ({
   "shipping-free": selectedShippingFree,
   manufacturer: [...selectedManufacturer],
   properties: [...selectedProperties],
+  categories: [...selectedCategories],
 }));
 
 const filterComponent = computed<Component | undefined>(() => {
   const componentMap: Record<string, Component> = {
     manufacturer: SwFilterPropertiesVue,
+    categories: SwFilterCategoriesVue,
     price: SwFilterPriceVue,
     rating: SwFilterRatingVue,
     "shipping-free": SwFilterShippingFreeVue,

package/app/components/SwProductListingFilters.vue

@@ -4,6 +4,7 @@ import type {
   CmsElementSidebarFilter,
 } from "@shopware/composables";
 import { useCmsTranslations } from "@shopware/composables";
+import { getCategoryFilterPostFilter } from "@shopware/helpers";
 import { defu } from "defu";
 import { computed } from "vue";
 import type { ComputedRef } from "vue";
@@ -11,6 +12,7 @@ import type { LocationQueryRaw } from "vue-router";
 
 import {
   firstQueryValue,
+  getVisibleListingFilters,
   toNumber,
   useCategoryListing,
   useProductSearchListing,
@@ -59,10 +61,17 @@ const {
 
 const sidebarSelectedFilters = useSelectedListingFilters();
 
+// Only the filters this listing can actually apply - the category filter is
+// search-only, matching the post-filter and URL gates below.
+const visibleFilters = computed(() =>
+  getVisibleListingFilters(getInitialFilters.value, { isProductSearch }),
+);
+
 const showResetFiltersButton = computed<boolean>(() => {
   if (
     sidebarSelectedFilters.manufacturer.size !== 0 ||
     sidebarSelectedFilters.properties.size !== 0 ||
+    (isProductSearch && sidebarSelectedFilters.categories.size !== 0) ||
     sidebarSelectedFilters["max-price"] ||
     sidebarSelectedFilters["min-price"] ||
     sidebarSelectedFilters.rating ||
@@ -82,6 +91,19 @@ const searchCriteriaForRequest: ComputedRef<Schemas["ProductListingCriteria"]> =
     properties: [...(sidebarSelectedFilters.properties as Set<string>)]?.join(
       "|",
     ),
+    // Category selection travels as a post-filter so the category
+    // aggregation itself is not reduced (faceted behavior). Search pages
+    // only: category pages never offer this filter, so a stale
+    // ?categories= param must not silently narrow them.
+    ...(isProductSearch && sidebarSelectedFilters.categories.size > 0
+      ? {
+          "post-filter": [
+            getCategoryFilterPostFilter([
+              ...(sidebarSelectedFilters.categories as Set<string>),
+            ]),
+          ],
+        }
+      : {}),
     "min-price": sidebarSelectedFilters["min-price"] as number,
     "max-price": sidebarSelectedFilters["max-price"] as number,
     order: getCurrentSortingOrder.value as string,
@@ -98,7 +120,11 @@ const handleFilterChange = async (event: {
   try {
     const { code, value } = event;
 
-    if (code === "manufacturer" || code === "properties") {
+    if (
+      code === "manufacturer" ||
+      code === "properties" ||
+      code === "categories"
+    ) {
       const filterSet = sidebarSelectedFilters[code];
       const stringValue = String(value);
 
@@ -137,6 +163,10 @@ const executeSearch = async () => {
 
     if (criteria.manufacturer) query.manufacturer = criteria.manufacturer;
     if (criteria.properties) query.properties = criteria.properties;
+    if (isProductSearch && sidebarSelectedFilters.categories.size > 0)
+      query.categories = [
+        ...(sidebarSelectedFilters.categories as Set<string>),
+      ].join("|");
     if (criteria["min-price"]) query["min-price"] = criteria["min-price"];
     if (criteria["max-price"]) query["max-price"] = criteria["max-price"];
     if (criteria.rating) query.rating = criteria.rating;
@@ -161,6 +191,7 @@ const executeSearch = async () => {
 const clearFilters = () => {
   (sidebarSelectedFilters.manufacturer as Set<string>).clear();
   (sidebarSelectedFilters.properties as Set<string>).clear();
+  (sidebarSelectedFilters.categories as Set<string>).clear();
   sidebarSelectedFilters["min-price"] = undefined;
   sidebarSelectedFilters["max-price"] = undefined;
   sidebarSelectedFilters.rating = undefined;
@@ -208,7 +239,11 @@ const handleRemoveFilterChip = async (chip: {
   code: string;
   value: string | number;
 }) => {
-  if (chip.code === "properties" || chip.code === "manufacturer") {
+  if (
+    chip.code === "properties" ||
+    chip.code === "manufacturer" ||
+    chip.code === "categories"
+  ) {
     const filterSet = sidebarSelectedFilters[chip.code] as Set<string>;
     filterSet.delete(String(chip.value));
   } else if (chip.code === "price") {
@@ -228,7 +263,7 @@ const handleRemoveFilterChip = async (chip: {
     <!-- Active Filter Chips -->
     <SwFilterChips
       :filters="sidebarSelectedFilters"
-      :available-filters="getInitialFilters"
+      :available-filters="visibleFilters"
       @remove="handleRemoveFilterChip"
     />
 
@@ -254,11 +289,12 @@ const handleRemoveFilterChip = async (chip: {
     <!-- Filters List -->
     <div class="self-stretch flex flex-col justify-start items-start gap-4">
       <SwProductListingFilter
-        v-for="filter in getInitialFilters"
+        v-for="filter in visibleFilters"
         :key="filter.id"
         :filter="filter"
         :selected-manufacturer="sidebarSelectedFilters.manufacturer"
         :selected-properties="sidebarSelectedFilters.properties"
+        :selected-categories="sidebarSelectedFilters.categories"
         :selected-min-price="sidebarSelectedFilters['min-price']"
         :selected-max-price="sidebarSelectedFilters['max-price']"
         :selected-rating="sidebarSelectedFilters.rating"

package/app/components/SwProductListingFiltersHorizontal.vue

@@ -4,6 +4,7 @@ import type {
   CmsElementSidebarFilter,
 } from "@shopware/composables";
 import { useCmsTranslations } from "@shopware/composables";
+import { getCategoryFilterPostFilter } from "@shopware/helpers";
 import { defu } from "defu";
 import { computed } from "vue";
 import type { ComputedRef } from "vue";
@@ -11,6 +12,7 @@ import type { LocationQueryRaw } from "vue-router";
 
 import {
   firstQueryValue,
+  getVisibleListingFilters,
   toNumber,
   useCategoryListing,
   useProductSearchListing,
@@ -58,10 +60,17 @@ const {
 
 const sidebarSelectedFilters = useSelectedListingFilters();
 
+// Only the filters this listing can actually apply - the category filter is
+// search-only, matching the post-filter and URL gates below.
+const visibleFilters = computed(() =>
+  getVisibleListingFilters(getInitialFilters.value, { isProductSearch }),
+);
+
 const showResetFiltersButton = computed<boolean>(() => {
   if (
     sidebarSelectedFilters.manufacturer.size !== 0 ||
     sidebarSelectedFilters.properties.size !== 0 ||
+    (isProductSearch && sidebarSelectedFilters.categories.size !== 0) ||
     sidebarSelectedFilters["max-price"] ||
     sidebarSelectedFilters["min-price"] ||
     sidebarSelectedFilters.rating ||
@@ -81,6 +90,19 @@ const searchCriteriaForRequest: ComputedRef<Schemas["ProductListingCriteria"]> =
     properties: [...(sidebarSelectedFilters.properties as Set<string>)]?.join(
       "|",
     ),
+    // Category selection travels as a post-filter so the category
+    // aggregation itself is not reduced (faceted behavior). Search pages
+    // only: category pages never offer this filter, so a stale
+    // ?categories= param must not silently narrow them.
+    ...(isProductSearch && sidebarSelectedFilters.categories.size > 0
+      ? {
+          "post-filter": [
+            getCategoryFilterPostFilter([
+              ...(sidebarSelectedFilters.categories as Set<string>),
+            ]),
+          ],
+        }
+      : {}),
     "min-price": sidebarSelectedFilters["min-price"] as number,
     "max-price": sidebarSelectedFilters["max-price"] as number,
     order: getCurrentSortingOrder.value as string,
@@ -97,7 +119,11 @@ const handleFilterChange = async (event: {
   try {
     const { code, value } = event;
 
-    if (code === "manufacturer" || code === "properties") {
+    if (
+      code === "manufacturer" ||
+      code === "properties" ||
+      code === "categories"
+    ) {
       const filterSet = sidebarSelectedFilters[code];
       const stringValue = String(value);
 
@@ -136,6 +162,10 @@ const executeSearch = async () => {
 
     if (criteria.manufacturer) query.manufacturer = criteria.manufacturer;
     if (criteria.properties) query.properties = criteria.properties;
+    if (isProductSearch && sidebarSelectedFilters.categories.size > 0)
+      query.categories = [
+        ...(sidebarSelectedFilters.categories as Set<string>),
+      ].join("|");
     if (criteria["min-price"]) query["min-price"] = criteria["min-price"];
     if (criteria["max-price"]) query["max-price"] = criteria["max-price"];
     if (criteria.rating) query.rating = criteria.rating;
@@ -160,6 +190,7 @@ const executeSearch = async () => {
 const clearFilters = () => {
   (sidebarSelectedFilters.manufacturer as Set<string>).clear();
   (sidebarSelectedFilters.properties as Set<string>).clear();
+  (sidebarSelectedFilters.categories as Set<string>).clear();
   sidebarSelectedFilters["min-price"] = undefined;
   sidebarSelectedFilters["max-price"] = undefined;
   sidebarSelectedFilters.rating = undefined;
@@ -208,6 +239,9 @@ const hasActiveFilter = (filter: { code: string }) => {
   if (filter.code === "manufacturer") {
     return sidebarSelectedFilters.manufacturer.size > 0;
   }
+  if (filter.code === "categories") {
+    return sidebarSelectedFilters.categories.size > 0;
+  }
   if (filter.code === "price") {
     return (
       sidebarSelectedFilters["min-price"] !== undefined ||
@@ -231,7 +265,7 @@ const hasActiveFilter = (filter: { code: string }) => {
     <div class="flex flex-wrap items-center justify-start gap-4 z-10">
       <!-- Filter dropdowns -->
       <SwFilterDropdown
-        v-for="filter in getInitialFilters"
+        v-for="filter in visibleFilters"
         :key="filter.id"
         :label="filter.label"
         :is-active="hasActiveFilter(filter)"
@@ -241,6 +275,7 @@ const hasActiveFilter = (filter: { code: string }) => {
           display-mode="dropdown"
           :selected-manufacturer="sidebarSelectedFilters.manufacturer"
           :selected-properties="sidebarSelectedFilters.properties"
+          :selected-categories="sidebarSelectedFilters.categories"
           :selected-min-price="sidebarSelectedFilters['min-price']"
           :selected-max-price="sidebarSelectedFilters['max-price']"
           :selected-rating="sidebarSelectedFilters.rating"