feat(cms-base): enable overriding the internal components (#1501)

.changeset/quick-cycles-add.md

@@ -0,0 +1,12 @@
+---
+"@shopware-pwa/cms-base": minor
+---
+
+Ability to overwrite internal components
+
+For example:
+
+`SwSharedPrice.vue` is used for multiple times to display a price. Create a component with the same name to make `cms-base` start using your component internally.
+
+---
+⚠️ Internal components aren't part of public API so the related changes won't be published in the changelog. Try to overwrite and track the changes on your responsibility.

apps/docs/src/getting-started/cms/customize-components.md

@@ -27,7 +27,7 @@ In order to customize a component, you need to override it. The process is the s
 - Blocks
 - Elements
 
-To do so, you need to create a file with the same name as the component in the `components/cms` directory.
+To do so, you need to create a file with the same name as the component in the `components` directory or wherever according to the project's configuration.
 
 ```json
 demo-store/
@@ -38,6 +38,12 @@ demo-store/
 
 Now the CMS module will automatically resolve that file based on the name and you can start writing your component.
 
+## Internal components
+
+❗**Internal components are not a part of public API. Once overwritten you need to track the changes on your own.**
+
+There is also a possibility to override the internal components, shared between public blocks and elements, the ones starting with `Sw` prefix, like [SwSlider.vue](https://github.com/shopware/frontends/blob/main/packages/cms-base/components/SwSlider.vue) or [SwProductCard.vue](https://github.com/shopware/frontends/blob/main/packages/cms-base/components/SwProductCard.vue). 
+
 ### Additional Example
 
 <PageRef page="overwriting-cms.html" title="Overwrite CMS blocks in Nuxt 3 APP" sub="Example how to overwrite the product card" />

apps/docs/src/getting-started/cms/overwriting-cms.md

@@ -11,10 +11,10 @@ head:
       content: "https://frontends-og-image.vercel.app/Overwrite%20CMS.png"
 ---
 
-# Overwrite CMS blocks in Nuxt 3 APP
+# Overwrite CMS blocks in Nuxt 3 APP (Nuxt Layer way)
 
 To override CMS blocks in the Nuxt 3 app, create a `.vue` file with the cms block name in the components directory.
-Because of auto importing, CMS component import will be overwritten by the new file path.
+Because of auto importing, CMS component import will be overwritten by the new file with the same name.
 
 More about auto imports can be found [here](https://nuxt.com/docs/guide/concepts/auto-imports)
 
@@ -27,7 +27,8 @@ If we want to create our own product listing **component** in **demo-store** the
 `templates/vue-demo-store/components/cms/block/CmsBlockProductListing.vue`
 
 :::tip HINT 💡
-You can only override components that start with Cms. For example, you cannot override SwProductCard (this is an internal component). If you want to have your own SwProductCard, you need to overwrite the Cms component that is using the SwProductCard and then replace it with your e.g. CustomProductCard.
+
+❗**Internal components are not a part of public API. Once overwritten you need to track the changes on your own.**
 :::
 
 ### Resolving folder structure
@@ -42,6 +43,10 @@ You can repeat folder structure in name like:
 
 These are the same components resolving as **CmsName**. 💡
 
+### Internal components
+
+As example: some components use `SwSharedPrice.vue` to show prices with corresponding currency for products in many places like product card, product details page and so on. In order to change the way how the price is displayed consistently - create a one component with a name `SwSharedPrice.vue` and that's it. The new component will be used everywhere where is "imported" (autoimported actually).
+
 ### Generic CMS components
 
 Generic components are responsible for resolving each CMS element

packages/cms-base/README.md

@@ -70,11 +70,6 @@ export default defineNuxtConfig({
 
 <!-- /automd -->
 
-### ⚠️ `<RouterLink/>` components used
-
-Some components use `RouterLink` component internally, available in [Vue Router](https://github.com/vuejs/router).
-In order to parse CMS components correctly and avoid missing component warning, it's **highly recommended** to have **Vue Router installed** or **Nuxt router enabled** in your application.
-
 ## Basic usage
 
 Since all CMS components are registered in your Nuxt application, you can now start using them in your template (no imports needed):
@@ -92,6 +87,32 @@ Since all CMS components are registered in your Nuxt application, you can now st
 
 See a [short guide](https://frontends.shopware.com/getting-started/cms/content-pages.html#use-the-cms-base-package) how to use `cms-base` package in your project based on Nuxt v3.
 
+## 📘 Available components
+
+ The list of available blocks and elements is [here](https://frontends.shopware.com/packages/cms-base.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/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)
+
+✅ Thanks to this, nuxt will take the component registered in your app instead of the one registered by this nuxt layer.
+
+### Internal components
+
+❗**Internal components are not a part of public API. Once overwritten you need to track the changes on your own.**
+
+There is also a possibility to override the internal components, shared between public blocks and elements, the ones starting with `Sw` prefix, like [SwSlider.vue](https://github.com/shopware/frontends/blob/main/packages/cms-base/components/SwSlider.vue) or [SwProductCard.vue](https://github.com/shopware/frontends/blob/main/packages/cms-base/components/SwProductCard.vue). 
+
+An example: some components use `SwSharedPrice.vue` to show prices with corresponding currency for products in many places like product card, product details page and so on. In order to change the way how the price is displayed consistently - create a one component with a name `SwSharedPrice.vue` and that's it. The new component will be used everywhere where is "imported" (autoimported actually).
+
+### ⚠️ `<RouterLink/>` components used
+
+Some components use `RouterLink` component internally, available in [Vue Router](https://github.com/vuejs/router).
+In order to parse CMS components correctly and avoid missing component warning, it's **highly recommended** to have **Vue Router installed** or **Nuxt router enabled** in your application.
+
 ## TypeScript support
 
 All components are fully typed with TypeScript.

packages/cms-base/components/SwCategoryNavigation.vue

@@ -1,6 +1,5 @@
 <script setup lang="ts">
 import type { Schemas } from "#shopware";
-import SwCategoryNavigationLink from "./SwCategoryNavigationLink.vue";
 
 const props = withDefaults(
   defineProps<{

packages/cms-base/components/SwListingProductPrice.vue

@@ -4,7 +4,6 @@ import {
   useCmsTranslations,
 } from "@shopware-pwa/composables-next";
 import type { Schemas } from "#shopware";
-import SwSharedPrice from "./SwSharedPrice.vue";
 import { toRefs } from "vue";
 import { defu } from "defu";
 

packages/cms-base/components/SwProductCard.vue

@@ -11,7 +11,6 @@ import {
 } from "@shopware-pwa/helpers-next";
 import { toRefs, computed, ref, useTemplateRef } from "vue";
 import { defu } from "defu";
-import SwListingProductPrice from "./SwListingProductPrice.vue";
 import {
   useAddToCart,
   useNotifications,

packages/cms-base/components/SwProductListingFilters.vue

@@ -2,7 +2,6 @@
 import { computed, provide, reactive, ref, useTemplateRef } from "vue";
 import type { ComputedRef, UnwrapNestedRefs } from "vue";
 import { defu } from "defu";
-import SwProductListingFilter from "./SwProductListingFilter.vue";
 import type {
   CmsElementProductListing,
   CmsElementSidebarFilter,

packages/cms-base/components/SwProductPrice.vue

@@ -1,7 +1,6 @@
 <script setup lang="ts">
 import type { Schemas } from "#shopware";
 import { useCmsTranslations } from "@shopware-pwa/composables-next";
-import SwSharedPrice from "./SwSharedPrice.vue";
 import { useProductPrice, usePrice } from "#imports";
 import { toRefs } from "vue";
 import { defu } from "defu";

packages/cms-base/components/SwProductUnits.vue

@@ -1,7 +1,6 @@
 <script setup lang="ts">
 import type { Schemas } from "#shopware";
 import { useCmsTranslations } from "@shopware-pwa/composables-next";
-import SwSharedPrice from "./SwSharedPrice.vue";
 import { computed } from "vue";
 import { defu } from "defu";
 

packages/cms-base/components/public/cms/element/CmsElementBuyBox.vue

@@ -10,9 +10,6 @@ import {
 } from "#imports";
 import { computed } from "vue";
 import { defu } from "defu";
-import SwProductAddToCart from "../../../SwProductAddToCart.vue";
-import SwVariantConfigurator from "../../../SwVariantConfigurator.vue";
-import SwSharedPrice from "../../../SwSharedPrice.vue";
 
 const props = defineProps<{
   content: CmsElementBuyBox;

packages/cms-base/components/public/cms/element/CmsElementCategoryNavigation.vue

@@ -1,7 +1,6 @@
 <script setup lang="ts">
 import type { Ref } from "vue";
 import { defu } from "defu";
-import SwCategoryNavigation from "../../../SwCategoryNavigation.vue";
 import { useCmsTranslations } from "@shopware-pwa/composables-next";
 import { getTranslatedProperty } from "@shopware-pwa/helpers-next";
 import { useCategory, useNavigation } from "#imports";

packages/cms-base/components/public/cms/element/CmsElementCrossSelling.vue

@@ -4,8 +4,6 @@ import type {
   SliderElementConfig,
 } from "@shopware-pwa/composables-next";
 import { useCmsElementConfig } from "#imports";
-import SwProductCard from "../../../SwProductCard.vue";
-import SwSlider from "../../../SwSlider.vue";
 import { ref, computed, useTemplateRef } from "vue";
 import { useElementSize } from "@vueuse/core";
 

packages/cms-base/components/public/cms/element/CmsElementImageGallery.vue

@@ -2,7 +2,6 @@
 import type { CmsElementImageGallery } from "@shopware-pwa/composables-next";
 import { useCmsElementConfig } from "#imports";
 import { isSpatial } from "../../../../helpers/media/isSpatial";
-import SwSlider from "../../../SwSlider.vue";
 import { computed, onMounted, ref, useTemplateRef } from "vue";
 
 const props = withDefaults(

packages/cms-base/components/public/cms/element/CmsElementImageSlider.vue

@@ -3,7 +3,6 @@ import type {
   CmsElementImageSlider,
   CmsElementImage,
 } from "@shopware-pwa/composables-next";
-import SwSlider from "../../../SwSlider.vue";
 import { computed } from "vue";
 
 const props = defineProps<{

packages/cms-base/components/public/cms/element/CmsElementProductBox.vue

@@ -1,6 +1,5 @@
 <script setup lang="ts">
 import type { CmsElementProductBox } from "@shopware-pwa/composables-next";
-import SwProductCard from "../../../SwProductCard.vue";
 import { computed } from "vue";
 
 const props = defineProps<{

packages/cms-base/components/public/cms/element/CmsElementProductDescriptionReviews.vue

@@ -6,7 +6,6 @@ import {
   getProductName,
 } from "@shopware-pwa/helpers-next";
 import { useCmsTranslations } from "@shopware-pwa/composables-next";
-import SwProductReviews from "../../../SwProductReviews.vue";
 import { computed, ref } from "vue";
 import { defu } from "defu";
 import { useProduct } from "#imports";

packages/cms-base/components/public/cms/element/CmsElementProductListing.vue

@@ -1,8 +1,6 @@
 <script setup lang="ts">
 import type { CmsElementProductListing } from "@shopware-pwa/composables-next";
 import { useCmsTranslations } from "@shopware-pwa/composables-next";
-import SwProductCard from "../../../SwProductCard.vue";
-import SwPagination from "../../../SwPagination.vue";
 import { useCategoryListing } from "#imports";
 import { computed, ref, watch, useTemplateRef } from "vue";
 import { defu } from "defu";

packages/cms-base/components/public/cms/element/CmsElementProductSlider.vue

@@ -6,8 +6,6 @@ import type {
 import { useCmsElementConfig } from "#imports";
 import { ref, computed, onMounted, useTemplateRef } from "vue";
 import type { ComputedRef } from "vue";
-import SwProductCard from "../../../SwProductCard.vue";
-import SwSlider from "../../../SwSlider.vue";
 
 const props = defineProps<{
   content: CmsElementProductSlider;

packages/cms-base/components/public/cms/element/CmsElementSidebarFilter.vue

@@ -1,6 +1,5 @@
 <script setup lang="ts">
 import type { CmsElementSidebarFilter } from "@shopware-pwa/composables-next";
-import SwProductListingFilters from "../../../SwProductListingFilters.vue";
 
 defineProps<{
   content: CmsElementSidebarFilter;

packages/cms-base/nuxt.config.ts

@@ -7,6 +7,12 @@ export default defineNuxtConfig({
       pathPrefix: false,
       // global: true,
     },
+    {
+      path: "./components/",
+      pattern: "Sw*",
+      extensions: [".vue"],
+      global: false,
+    },
   ],
   build: {
     transpile: ["@shopware-pwa/cms-base"],