doc: add upgrade information for Pinia migration

NEXT-40449

.wordlist.txt

@@ -493,6 +493,7 @@ ManyToManyIdField
 ManyToOne
 ManyToOneAssociation
 ManyToOneAssociationField
+MapState
 MediaDataSelection
 MediaDataSet
 MediaFolderDataSet
@@ -1386,6 +1387,7 @@ mandatorily
 manufacturerId
 manytomanyid
 mapErrors
+mapGetters
 martinfowler
 masternode
 matchers

guides/plugins/plugins/administration/system-updates/pinia.md

@@ -0,0 +1,341 @@
+---
+nav:
+  title: Upgrading to Pinia
+  position: 261
+---
+
+# Migration from Vuex in Shopware to Pinia
+
+## Introduction
+
+With the release of Shopware 6.7, we will replace Vuex with [Pinia](https://pinia.vuejs.org/) as the state management library for the administration.
+
+## Why Pinia?
+
+Migrating to Pinia simplifies state management with an intuitive API,
+no need for mutations, better TypeScript support, and seamless integration with Vue 3 Composition API.
+It’s lightweight, modular, and offers modern features like devtools support, making it a more efficient alternative to Vuex.
+
+## Migration Guide
+
+To migrate a Vuex store to Pinia, you need to make some changes to the store definition and how you access it in components.
+
+- First register it with `Shopware.Store.register` and define the store with `state`, `getters`, and `actions` properties:
+
+**Before (Vuex):**
+
+```javascript
+export default {
+    namespaced: true,
+
+    state: {
+      // Initial state
+      ...
+    },
+    mutations: {
+      ...
+    },
+    getters: {
+       ...
+    },
+    actions: {
+       ...
+    },
+}
+```
+
+**After (Pinia):**
+
+```javascript
+const store = Shopware.Store.register('<storeName>', {
+    state: () => ({
+        // Initial state
+        ...
+    }),
+    getters: {
+       ...
+    },
+    actions: {
+       ...
+    },
+});
+export default store;
+```
+
+- You can also register the store with an `id` property in the definition object, for example:
+
+```javascript
+const store = Shopware.Store.register({
+    id: '<storeName>',
+    state: () => ({
+        // Initial state
+    }),
+    getters: {
+       // ...
+    },
+    actions: {
+       // ...
+    },
+});
+```
+
+- If you register a store that already exists, it will be overwritten. You can also unregister a store:
+
+```javascript
+Shopware.Store.unregister('<storeName>');
+```
+
+- To register a store from a component or index file, simply import the store file.
+
+**Before (Vuex)**
+
+```javascript
+import productsStore from './state/products.state';
+
+Shopware.State.registerModule('product', productsStore);
+```
+
+**After (Pinia)**
+
+```javascript
+import './state/products.state';
+```
+
+### Key Changes
+
+- **State:**
+  - In Pinia, `state` must be a function returning the initial state instead of a static object.
+
+- **Mutations:**
+  - Vuex `mutations` are no longer needed in Pinia, since you can modify state directly in actions or compute it dynamically.
+  - If a mutation only sets the state to a passed value, remove it and update the state directly in your action.
+  - If a mutation has extra business logic, convert it into an action.
+
+- **Actions:**
+   - In Pinia, actions don't receive `state` as an argument. Instead, state is accessed directly using `this.anyStateField`.
+
+        **Example:**
+   - 
+        ```javascript
+        actions: {
+            updateProductName(newName) {
+                this.productName = newName; // Directly update state
+            },
+        },
+        ```
+
+- **Getters:**
+  - There cannot be getters with the same name as a property in the state, as both are exposed at the same level in the store.
+  - Getters should be used to compute and return information based on state, without modifying it.
+  - It is not necessary to create a getter to return a state property. You can access it directly from the store instance.
+  - Avoid side effects in getters to prevent unexpected bugs. Getters should only compute and return information based on state, without modifying it.
+
+- **TypeScript:**
+  - We recommend migrating JavaScript stores to TypeScript for stricter typing, better autocompletion, and fewer errors during development.
+  - To use the correct types when calling `Shopware.Store.get`, you can infer the store's type:
+
+    ```typescript
+    const store = Shopware.Store.register({
+      id: 'myStore',
+      ...
+    });
+
+    export type StoreType = ReturnType<typeof store>;
+    ```
+
+  - Then, you can use this type to extend `PiniaRootState`:
+
+    ```typescript
+    import type { StoreType } from './store/myStore';
+    
+    declare global {
+        interface PiniaRootState {
+            myStore: StoreType;
+        }
+    }
+    ```
+
+### Composables as a Store
+
+With Pinia, you can use reactive properties inside a store and define it like a composable. Keep in mind that only variables and functions returned from the store will be tracked by Pinia in devtools.
+
+```typescript
+const store = Shopware.Store.register('<storeName>', function() {
+  const count = ref(0);
+
+  const doubled = computed(() => count.value * 2);
+
+  function increment() {
+    count.value++;
+  }
+
+  function decrement() {
+    count.value--;
+  }
+
+  return { count, doubled, increment, decrement };
+});
+```
+
+### Accessing the Store
+
+To access the store in Vuex, you would typically do:
+
+```javascript
+Shopware.State.get('<storeName>');
+```
+
+When migrating to Pinia, it changes to:
+
+```javascript
+Shopware.Store.get('<storeName>');
+```
+
+### Accessing State, Getters, Mutations, and Actions
+
+Below is a practical example of how store access and usage changes from Vuex to Pinia:
+
+**Before (Vuex):**
+
+```javascript
+// Get the store
+const store = Shopware.State.get('product');
+
+// Access the state
+const productCount = Shopware.State.get('product').products.length;
+
+// Use getters
+Shopware.State.getters['product/productCount'];
+
+// Execute mutations
+store.commit('product/setProducts', [{ id: 1, name: 'Test' }]);
+
+// Execute actions
+store.dispatch('product/fetchProducts');
+```
+
+**After (Pinia):**
+
+```javascript
+// Get the store
+const store = Shopware.Store.get('product');
+
+// Access the state directly
+const productCount = Shopware.Store.get('product').products.length;
+
+// Use getters (no 'get' prefix)
+const totalProducts = Shopware.Store.get('product').productCount;
+
+// Mutate the state directly or through an action
+Shopware.Store.get('product').products = [{ id: 1, name: 'Test' }];
+
+// Execute actions (called like methods)
+Shopware.Store.get('product').fetchProducts();
+```
+
+In Pinia, you no longer need `commit` for mutations or `dispatch` for actions.
+Instead, you can work with the state and call actions directly.
+
+### MapState
+
+**Before (Vuex)**
+
+```javascript
+const { mapState } = Shopware.Component.getComponentHelper();
+
+export default {
+  computed: {
+    ...mapState('product', ['products', 'productsCount']),
+  },
+};
+```
+
+**After (Pinia)** (using the Composition API):
+
+```javascript
+const { mapState } = Shopware.Component.getComponentHelper();
+
+export default {
+  computed: {
+    ...mapState(() => Shopware.Store.get('product'), ['products', 'productsCount']),
+  },
+};
+```
+
+Remember to pass a function returning the store to `mapState`. `Shopware.Store.get` returns the store instance directly, while `mapStore` expects the `useStore` function. Also note that [mapGetters is deprecated](https://pinia.vuejs.org/api/pinia/functions/mapGetters.html), so you should rely on `mapState`.
+
+### Testing
+
+To test your store, just import it so it's registered. You can use `$reset()` to reset the store before each test:
+
+```javascript
+import './store/my.store';
+
+describe('my store', () => {
+  const store = Shopware.Store.get('myStore');
+
+  beforeEach(() => {
+    store.$reset();
+  });
+
+  it('has initial state', () => {
+    expect(store.count).toBe(0);
+  });
+});
+```
+
+When testing components that use Pinia stores, register Pinia as a plugin and reset it before each test:
+
+```javascript
+import { createPinia, setActivePinia } from 'pinia';
+
+const pinia = createPinia();
+
+describe('my component', () => {
+  beforeEach(() => {
+    setActivePinia(pinia);
+  });
+
+  it('is a component', async () => {
+    const wrapper = mount(await wrapTestComponent('myComponent', { sync: true }), {
+      global: {
+        plugins: [pinia],
+        stubs: {
+          // ...
+        },
+      },
+    });
+
+    expect(wrapper.exists()).toBe(true);
+  });
+});
+```
+
+Take into account that Pinia actions do not return a Promise. So to check DOM changes it might be necessary to await `nextTick()`;
+
+```javascript
+
+describe('MyComponent.vue', () => {
+  let wrapper;
+  const store = Shopware.Store.get('myStore');
+
+  beforeEach(async () => {
+    wrapper = mount(await wrapTestComponent('myComponent', { sync: true }), {
+      global: {
+        plugins: [createPinia],
+      },
+    });
+  });
+
+  it('increments the counter when the button is clicked', async () => {
+    store.increment();
+
+    // Wait for state updates and DOM reactivity
+    await nextTick();
+
+    // Assert the state and the DOM
+    expect(store.counter).toBe(1); // State change
+    expect(wrapper.find('p').text()).toBe('Counter: 1'); // DOM update
+  });
+});
+```