@shopware/cms-base-layer 3.0.1 → 4.0.0

package/README.md

@@ -5,7 +5,7 @@
 [![](https://img.shields.io/github/issues/shopware/frontends/cms-base?label=cms-base%20issues&logo=github)](https://github.com/shopware/frontends/issues?q=is%3Aopen+is%3Aissue+label%3Acms-base)
 [![](https://img.shields.io/github/license/shopware/frontends?color=blue)](#)
 
-Nuxt [layer](https://nuxt.com/docs/getting-started/layers) that provides an implementation of all CMS components in Shopware [based on utility-classes](https://frontends.shopware.com/framework/styling.html).
+Nuxt [layer](https://nuxt.com/docs/getting-started/layers) that provides an implementation of all CMS components in Shopware [based on utility-classes](https://developer.shopware.com/frontends/concepts/styling.html).
 
 It is useful for projects that want to use the CMS components while keeping CMS functionality separate from the styling system and design tokens.
 
@@ -90,7 +90,7 @@ Since all CMS components are registered in your Nuxt application, you can now st
 
 > `@shopware/cms-base-layer` no longer owns the default UnoCSS theme. If you want the shared Shopware Frontends design tokens and UnoCSS defaults, extend `@shopware/unocss-design-tokens-layer` as shown above.
 
-See a [short guide](https://frontends.shopware.com/getting-started/cms/content-pages.html#use-the-cms-base-package) on how to use `cms-base-layer` in your Nuxt project.
+See a [short guide](https://developer.shopware.com/frontends/guides/cms/content-pages.html#use-the-cms-base-package) on how to use `cms-base-layer` in your Nuxt project.
 
 ## Styling and Design Tokens
 
@@ -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
@@ -442,15 +448,15 @@ export default defineAppConfig({
 
 ## 📘 Available components
 
-The list of available blocks and elements is [here](https://frontends.shopware.com/packages/cms-base-layer.html#available-components).
+The list of available blocks and elements is [here](https://developer.shopware.com/frontends/packages/cms-base-layer.html#available-components).
 
 ## 🔄 Overwriting components
 
 The procedure is:
 
-- find a component in component's [list](https://frontends.shopware.com/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.
 
@@ -475,7 +481,7 @@ No additional packages needed to be installed.
 
 ## Links
 
-- [📘 Documentation](https://frontends.shopware.com)
+- [📘 Documentation](https://developer.shopware.com/frontends)
 
 - [👥 Community](https://discord.com/channels/1308047705309708348/1405501315160739951) (`#composable-frontend`)
 
@@ -485,9 +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.0.1
+### 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
+
+- [#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
 
-- Updated dependencies [[`8be060d`](https://github.com/shopware/frontends/commit/8be060de825ca799f98a8f045a5e7fea61f5d1a2), [`5678fb0`](https://github.com/shopware/frontends/commit/5678fb008cbd86eaddd061e004de89e6f45bb7ec), [`22611e5`](https://github.com/shopware/frontends/commit/22611e542b8f42a4f34dce5186f628f9a17f457b)]:
-  - @shopware/composables@1.12.0
+- [#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`).
+
+  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.
+
+- [#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.
+
+  - `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.
+
+  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`.
+
+- [#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.
+
+- [#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 [[`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/SwProductCard.vue

@@ -17,6 +17,7 @@ import {
   useAddToCart,
   useCartErrorParamsResolver,
   useCartNotification,
+  useNavigationContext,
   useNotifications,
   useProductWishlist,
   useUrlResolver,
@@ -144,10 +145,25 @@ const productManufacturer = computed(() =>
   getProductManufacturerName(product.value),
 );
 
-const { getUrlPrefix } = useUrlResolver();
-const productLink = computed(() =>
-  buildUrlPrefix(getProductRoute(product.value), getUrlPrefix()),
+const { foreignKey: currentNavigationId, routeName } = useNavigationContext();
+const referrerCategoryId = computed(() =>
+  isProductListing && routeName.value === "frontend.navigation.page"
+    ? currentNavigationId.value
+    : undefined,
 );
+const { getUrlPrefix } = useUrlResolver();
+const productLink = computed(() => {
+  const productRoute = getProductRoute(product.value);
+  const productRouteWithReferrer = {
+    ...productRoute,
+    state: {
+      ...productRoute.state,
+      referrerCategoryId: referrerCategoryId.value,
+    },
+  };
+
+  return buildUrlPrefix(productRouteWithReferrer, getUrlPrefix());
+});
 </script>
 
 <template>

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,