ads-fe 0.0.1

package/skills/pinia/references/best-practices-outside-component.md

@@ -0,0 +1,115 @@
+---
+name: using-stores-outside-components
+description: Correctly using stores in navigation guards, plugins, and other non-component contexts
+---
+
+# Using Stores Outside Components
+
+Stores need the `pinia` instance, which is automatically injected in components. Outside components, you may need to provide it manually.
+
+## Single Page Applications
+
+Call stores **after** pinia is installed:
+
+```ts
+import { useUserStore } from '@/stores/user'
+import { createPinia } from 'pinia'
+import { createApp } from 'vue'
+import App from './App.vue'
+
+// ❌ Fails - pinia not created yet
+const userStore = useUserStore()
+
+const pinia = createPinia()
+const app = createApp(App)
+app.use(pinia)
+
+// ✅ Works - pinia is active
+const userStore = useUserStore()
+```
+
+## Navigation Guards
+
+**Wrong:** Call at module level
+
+```ts
+import { createRouter } from 'vue-router'
+const router = createRouter({ /* ... */ })
+
+// ❌ May fail depending on import order
+const store = useUserStore()
+
+router.beforeEach((to) => {
+  if (store.isLoggedIn) { /* ... */ }
+})
+```
+
+**Correct:** Call inside the guard
+
+```ts
+router.beforeEach((to) => {
+  // ✅ Called after pinia is installed
+  const store = useUserStore()
+
+  if (to.meta.requiresAuth && !store.isLoggedIn) {
+    return '/login'
+  }
+})
+```
+
+## SSR Applications
+
+Always pass the `pinia` instance to `useStore()`:
+
+```ts
+const pinia = createPinia()
+const app = createApp(App)
+app.use(router)
+app.use(pinia)
+
+router.beforeEach((to) => {
+  // ✅ Pass pinia instance
+  const main = useMainStore(pinia)
+
+  if (to.meta.requiresAuth && !main.isLoggedIn) {
+    return '/login'
+  }
+})
+```
+
+## serverPrefetch()
+
+Access pinia via `this.$pinia`:
+
+```ts
+export default {
+  serverPrefetch() {
+    const store = useStore(this.$pinia)
+    return store.fetchData()
+  },
+}
+```
+
+## onServerPrefetch()
+
+Works normally in `<script setup>`:
+
+```vue
+<script setup>
+const store = useStore()
+
+onServerPrefetch(async () => {
+  // ✅ Just works
+  await store.fetchData()
+})
+</script>
+```
+
+## Key Takeaway
+
+Defer `useStore()` calls to functions that run after pinia is installed, rather than calling at module scope.
+
+<!--
+Source references:
+- https://pinia.vuejs.org/core-concepts/outside-component-usage.html
+-->

package/skills/pinia/references/best-practices-testing.md

@@ -0,0 +1,212 @@
+---
+name: testing
+description: Unit testing stores and components with @pinia/testing
+---
+
+# Testing Stores
+
+## Unit Testing Stores
+
+Create a fresh pinia instance for each test:
+
+```ts
+import { setActivePinia, createPinia } from 'pinia'
+import { useCounterStore } from '../src/stores/counter'
+
+describe('Counter Store', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+  })
+
+  it('increments', () => {
+    const counter = useCounterStore()
+    expect(counter.n).toBe(0)
+    counter.increment()
+    expect(counter.n).toBe(1)
+  })
+})
+```
+
+### With Plugins
+
+```ts
+import { setActivePinia, createPinia } from 'pinia'
+import { createApp } from 'vue'
+import { somePlugin } from '../src/stores/plugin'
+
+const app = createApp({})
+
+beforeEach(() => {
+  const pinia = createPinia().use(somePlugin)
+  app.use(pinia)
+  setActivePinia(pinia)
+})
+```
+
+## Testing Components
+
+Install `@pinia/testing`:
+
+```bash
+npm i -D @pinia/testing
+```
+
+Use `createTestingPinia()`:
+
+```ts
+import { mount } from '@vue/test-utils'
+import { createTestingPinia } from '@pinia/testing'
+import { useSomeStore } from '@/stores/myStore'
+
+const wrapper = mount(Counter, {
+  global: {
+    plugins: [createTestingPinia()],
+  },
+})
+
+const store = useSomeStore()
+
+// Manipulate state directly
+store.name = 'new name'
+store.$patch({ name: 'new name' })
+
+// Actions are stubbed by default
+store.someAction()
+expect(store.someAction).toHaveBeenCalledTimes(1)
+```
+
+## Initial State
+
+Set initial state for tests:
+
+```ts
+const wrapper = mount(Counter, {
+  global: {
+    plugins: [
+      createTestingPinia({
+        initialState: {
+          counter: { n: 20 }, // Store name → initial state
+        },
+      }),
+    ],
+  },
+})
+```
+
+## Action Stubbing
+
+### Execute Real Actions
+
+```ts
+createTestingPinia({ stubActions: false })
+```
+
+### Selective Stubbing
+
+```ts
+// Only stub specific actions
+createTestingPinia({
+  stubActions: ['increment', 'reset'],
+})
+
+// Or use a function
+createTestingPinia({
+  stubActions: (actionName, store) => {
+    if (actionName.startsWith('set')) return true
+    return false
+  },
+})
+```
+
+### Mock Action Return Values
+
+```ts
+import type { Mock } from 'vitest'
+
+// After getting store
+store.someAction.mockResolvedValue('mocked value')
+```
+
+## Mocking Getters
+
+Getters are writable in tests:
+
+```ts
+const pinia = createTestingPinia()
+const counter = useCounterStore(pinia)
+
+counter.double = 3 // Override computed value
+
+// Reset to default behavior
+counter.double = undefined
+counter.double // Now computed normally
+```
+
+## Custom Spy Function
+
+If not using Jest/Vitest with globals:
+
+```ts
+import { vi } from 'vitest'
+
+createTestingPinia({
+  createSpy: vi.fn,
+})
+```
+
+With Sinon:
+
+```ts
+import sinon from 'sinon'
+
+createTestingPinia({
+  createSpy: sinon.spy,
+})
+```
+
+## Pinia Plugins in Tests
+
+Pass plugins to `createTestingPinia()`:
+
+```ts
+import { somePlugin } from '../src/stores/plugin'
+
+createTestingPinia({
+  stubActions: false,
+  plugins: [somePlugin],
+})
+```
+
+**Don't use** `testingPinia.use(MyPlugin)` - pass plugins in options.
+
+## Type-Safe Mocked Store
+
+```ts
+import type { Mock } from 'vitest'
+import type { Store, StoreDefinition } from 'pinia'
+
+function mockedStore<TStoreDef extends () => unknown>(
+  useStore: TStoreDef
+): TStoreDef extends StoreDefinition<infer Id, infer State, infer Getters, infer Actions>
+  ? Store<Id, State, Record<string, never>, {
+      [K in keyof Actions]: Actions[K] extends (...args: any[]) => any
+        ? Mock<Actions[K]>
+        : Actions[K]
+    }>
+  : ReturnType<TStoreDef> {
+  return useStore() as any
+}
+
+// Usage
+const store = mockedStore(useSomeStore)
+store.someAction.mockResolvedValue('value') // Typed!
+```
+
+## E2E Tests
+
+No special handling needed - Pinia works normally.
+
+<!--
+Source references:
+- https://pinia.vuejs.org/cookbook/testing.html
+-->

package/skills/pinia/references/core-stores.md

@@ -0,0 +1,389 @@
+---
+name: stores
+description: Defining stores, state, getters, and actions in Pinia
+---
+
+# Pinia Stores
+
+Stores are defined using `defineStore()` with a unique name. Each store has three core concepts: **state**, **getters**, and **actions**.
+
+## Defining Stores
+
+### Option Stores
+
+Similar to Vue's Options API:
+
+```ts
+import { defineStore } from 'pinia'
+
+export const useCounterStore = defineStore('counter', {
+  state: () => ({
+    count: 0,
+    name: 'Eduardo',
+  }),
+  getters: {
+    doubleCount: (state) => state.count * 2,
+  },
+  actions: {
+    increment() {
+      this.count++
+    },
+  },
+})
+```
+
+Think of `state` as `data`, `getters` as `computed`, and `actions` as `methods`.
+
+### Setup Stores (Recommended)
+
+Uses Composition API syntax - more flexible and powerful:
+
+```ts
+import { ref, computed } from 'vue'
+import { defineStore } from 'pinia'
+
+export const useCounterStore = defineStore('counter', () => {
+  const count = ref(0)
+  const name = ref('Eduardo')
+  const doubleCount = computed(() => count.value * 2)
+
+  function increment() {
+    count.value++
+  }
+
+  return { count, name, doubleCount, increment }
+})
+```
+
+In Setup Stores: `ref()` → state, `computed()` → getters, `function()` → actions.
+
+**Important:** You must return all state properties for Pinia to track them.
+
+### Using Stores
+
+```vue
+<script setup>
+import { useCounterStore } from '@/stores/counter'
+
+const store = useCounterStore()
+// Access: store.count, store.doubleCount, store.increment()
+</script>
+```
+
+### Destructuring with storeToRefs
+
+```vue
+<script setup>
+import { storeToRefs } from 'pinia'
+import { useCounterStore } from '@/stores/counter'
+
+const store = useCounterStore()
+
+// ❌ Breaks reactivity
+const { name, doubleCount } = store
+
+// ✅ Preserves reactivity for state/getters
+const { name, doubleCount } = storeToRefs(store)
+
+// ✅ Actions can be destructured directly
+const { increment } = store
+</script>
+```
+
+---
+
+## State
+
+State is defined as a function returning the initial state.
+
+### TypeScript
+
+Type inference works automatically. For complex types:
+
+```ts
+interface UserInfo {
+  name: string
+  age: number
+}
+
+export const useUserStore = defineStore('user', {
+  state: () => ({
+    userList: [] as UserInfo[],
+    user: null as UserInfo | null,
+  }),
+})
+```
+
+Or use an interface for the return type:
+
+```ts
+interface State {
+  userList: UserInfo[]
+  user: UserInfo | null
+}
+
+export const useUserStore = defineStore('user', {
+  state: (): State => ({
+    userList: [],
+    user: null,
+  }),
+})
+```
+
+### Accessing and Modifying
+
+```ts
+const store = useStore()
+store.count++
+```
+
+```vue
+<input v-model="store.count" type="number" />
+```
+
+### Mutating with $patch
+
+Apply multiple changes at once:
+
+```ts
+// Object syntax
+store.$patch({
+  count: store.count + 1,
+  name: 'DIO',
+})
+
+// Function syntax (for complex mutations)
+store.$patch((state) => {
+  state.items.push({ name: 'shoes', quantity: 1 })
+  state.hasChanged = true
+})
+```
+
+### Resetting State
+
+Option Stores have built-in `$reset()`. For Setup Stores, implement your own:
+
+```ts
+export const useCounterStore = defineStore('counter', () => {
+  const count = ref(0)
+
+  function $reset() {
+    count.value = 0
+  }
+
+  return { count, $reset }
+})
+```
+
+### Subscribing to State Changes
+
+```ts
+cartStore.$subscribe((mutation, state) => {
+  mutation.type // 'direct' | 'patch object' | 'patch function'
+  mutation.storeId // 'cart'
+  mutation.payload // patch object (only for 'patch object')
+
+  localStorage.setItem('cart', JSON.stringify(state))
+})
+
+// Options
+cartStore.$subscribe(callback, { flush: 'sync' }) // Immediate
+cartStore.$subscribe(callback, { detached: true }) // Keep after unmount
+```
+
+---
+
+## Getters
+
+Getters are computed values, equivalent to Vue's `computed()`.
+
+### Basic Getters
+
+```ts
+getters: {
+  doubleCount: (state) => state.count * 2,
+}
+```
+
+### Accessing Other Getters
+
+Use `this` with explicit return type:
+
+```ts
+getters: {
+  doubleCount: (state) => state.count * 2,
+  doublePlusOne(): number {
+    return this.doubleCount + 1
+  },
+},
+```
+
+### Getters with Arguments
+
+Return a function (note: loses caching):
+
+```ts
+getters: {
+  getUserById: (state) => {
+    return (userId: string) => state.users.find((user) => user.id === userId)
+  },
+},
+```
+
+Cache within parameterized getters:
+
+```ts
+getters: {
+  getActiveUserById(state) {
+    const activeUsers = state.users.filter((user) => user.active)
+    return (userId: string) => activeUsers.find((user) => user.id === userId)
+  },
+},
+```
+
+### Accessing Other Stores in Getters
+
+```ts
+import { useOtherStore } from './other-store'
+
+getters: {
+  combined(state) {
+    const otherStore = useOtherStore()
+    return state.localData + otherStore.data
+  },
+},
+```
+
+---
+
+## Actions
+
+Actions are methods for business logic. Unlike getters, they can be asynchronous.
+
+### Defining Actions
+
+```ts
+actions: {
+  increment() {
+    this.count++
+  },
+  randomizeCounter() {
+    this.count = Math.round(100 * Math.random())
+  },
+},
+```
+
+### Async Actions
+
+```ts
+actions: {
+  async registerUser(login: string, password: string) {
+    try {
+      this.userData = await api.post({ login, password })
+    } catch (error) {
+      return error
+    }
+  },
+},
+```
+
+### Accessing Other Stores in Actions
+
+```ts
+import { useAuthStore } from './auth-store'
+
+actions: {
+  async fetchUserPreferences() {
+    const auth = useAuthStore()
+    if (auth.isAuthenticated) {
+      this.preferences = await fetchPreferences()
+    }
+  },
+},
+```
+
+**SSR:** Call all `useStore()` before any `await`:
+
+```ts
+async orderCart() {
+  // ✅ Call stores before await
+  const user = useUserStore()
+
+  await apiOrderCart(user.token, this.items)
+  // ❌ Don't call useStore() after await in SSR
+}
+```
+
+### Subscribing to Actions
+
+```ts
+const unsubscribe = someStore.$onAction(
+  ({ name, store, args, after, onError }) => {
+    const startTime = Date.now()
+    console.log(`Start "${name}" with params [${args.join(', ')}]`)
+
+    after((result) => {
+      console.log(`Finished "${name}" after ${Date.now() - startTime}ms`)
+    })
+
+    onError((error) => {
+      console.warn(`Failed "${name}": ${error}`)
+    })
+  }
+)
+
+unsubscribe() // Cleanup
+```
+
+Keep subscription after component unmount:
+
+```ts
+someStore.$onAction(callback, true)
+```
+
+---
+
+## Options API Helpers
+
+```ts
+import { mapState, mapWritableState, mapActions } from 'pinia'
+import { useCounterStore } from '../stores/counter'
+
+export default {
+  computed: {
+    // Readonly state/getters
+    ...mapState(useCounterStore, ['count', 'doubleCount']),
+    // Writable state
+    ...mapWritableState(useCounterStore, ['count']),
+  },
+  methods: {
+    ...mapActions(useCounterStore, ['increment']),
+  },
+}
+```
+
+---
+
+## Accessing Global Providers in Setup Stores
+
+```ts
+import { inject } from 'vue'
+import { useRoute } from 'vue-router'
+import { defineStore } from 'pinia'
+
+export const useSearchFilters = defineStore('search-filters', () => {
+  const route = useRoute()
+  const appProvided = inject('appProvided')
+
+  // Don't return these - access them directly in components
+  return { /* ... */ }
+})
+```
+
+<!--
+Source references:
+- https://pinia.vuejs.org/core-concepts/
+- https://pinia.vuejs.org/core-concepts/state.html
+- https://pinia.vuejs.org/core-concepts/getters.html
+- https://pinia.vuejs.org/core-concepts/actions.html
+-->