autoworkflow 3.1.5 → 3.5.0

package/.claude/skills/state-pinia.md

@@ -0,0 +1,431 @@
+# Pinia Skill
+
+## Setup
+\`\`\`typescript
+// main.ts
+import { createApp } from 'vue';
+import { createPinia } from 'pinia';
+import App from './App.vue';
+
+const app = createApp(App);
+const pinia = createPinia();
+
+app.use(pinia);
+app.mount('#app');
+\`\`\`
+
+## Setup Stores (Composition API - Recommended)
+\`\`\`typescript
+// stores/user.ts
+import { defineStore } from 'pinia';
+import { ref, computed } from 'vue';
+
+interface User {
+  id: string;
+  email: string;
+  name: string;
+}
+
+export const useUserStore = defineStore('user', () => {
+  // State (refs)
+  const user = ref<User | null>(null);
+  const loading = ref(false);
+  const error = ref<string | null>(null);
+
+  // Getters (computed)
+  const isLoggedIn = computed(() => !!user.value);
+  const userName = computed(() => user.value?.name ?? 'Guest');
+
+  // Actions (functions)
+  async function login(email: string, password: string) {
+    loading.value = true;
+    error.value = null;
+
+    try {
+      const response = await fetch('/api/auth/login', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ email, password }),
+      });
+
+      if (!response.ok) throw new Error('Login failed');
+
+      user.value = await response.json();
+    } catch (e) {
+      error.value = (e as Error).message;
+      throw e;
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  async function logout() {
+    await fetch('/api/auth/logout', { method: 'POST' });
+    user.value = null;
+  }
+
+  function updateProfile(data: Partial<User>) {
+    if (user.value) {
+      user.value = { ...user.value, ...data };
+    }
+  }
+
+  // Return everything that should be exposed
+  return {
+    // State
+    user,
+    loading,
+    error,
+    // Getters
+    isLoggedIn,
+    userName,
+    // Actions
+    login,
+    logout,
+    updateProfile,
+  };
+});
+\`\`\`
+
+## Options Stores (Options API)
+\`\`\`typescript
+// stores/cart.ts
+import { defineStore } from 'pinia';
+
+interface CartItem {
+  id: string;
+  name: string;
+  price: number;
+  quantity: number;
+}
+
+export const useCartStore = defineStore('cart', {
+  // State
+  state: () => ({
+    items: [] as CartItem[],
+    coupon: null as string | null,
+  }),
+
+  // Getters
+  getters: {
+    totalItems: (state) => state.items.reduce((sum, item) => sum + item.quantity, 0),
+
+    totalPrice: (state) =>
+      state.items.reduce((sum, item) => sum + item.price * item.quantity, 0),
+
+    // Getter using other getters
+    formattedTotal(): string {
+      return \`$\${this.totalPrice.toFixed(2)}\`;
+    },
+
+    // Getter with parameters
+    getItemById: (state) => (id: string) =>
+      state.items.find((item) => item.id === id),
+  },
+
+  // Actions
+  actions: {
+    addItem(item: Omit<CartItem, 'quantity'>) {
+      const existing = this.items.find((i) => i.id === item.id);
+      if (existing) {
+        existing.quantity++;
+      } else {
+        this.items.push({ ...item, quantity: 1 });
+      }
+    },
+
+    removeItem(id: string) {
+      const index = this.items.findIndex((item) => item.id === id);
+      if (index !== -1) {
+        this.items.splice(index, 1);
+      }
+    },
+
+    updateQuantity(id: string, quantity: number) {
+      const item = this.items.find((i) => i.id === id);
+      if (item) {
+        item.quantity = Math.max(0, quantity);
+        if (item.quantity === 0) {
+          this.removeItem(id);
+        }
+      }
+    },
+
+    clearCart() {
+      this.items = [];
+      this.coupon = null;
+    },
+
+    // Async action
+    async applyCoupon(code: string) {
+      const response = await fetch(\`/api/coupons/\${code}\`);
+      if (response.ok) {
+        this.coupon = code;
+      }
+    },
+  },
+});
+\`\`\`
+
+## Usage in Components
+\`\`\`vue
+<script setup lang="ts">
+import { useUserStore } from '@/stores/user';
+import { useCartStore } from '@/stores/cart';
+import { storeToRefs } from 'pinia';
+
+// Setup store usage
+const userStore = useUserStore();
+const cartStore = useCartStore();
+
+// Destructure reactive state (use storeToRefs to keep reactivity)
+const { user, loading, isLoggedIn } = storeToRefs(userStore);
+
+// Actions can be destructured directly
+const { login, logout } = userStore;
+
+// Getters
+const { totalItems, formattedTotal } = storeToRefs(cartStore);
+
+// Direct access
+const handleLogin = async () => {
+  await userStore.login(email.value, password.value);
+};
+
+// Watch store changes
+watch(
+  () => userStore.user,
+  (newUser) => {
+    console.log('User changed:', newUser);
+  }
+);
+</script>
+
+<template>
+  <div>
+    <div v-if="loading">Loading...</div>
+    <div v-else-if="isLoggedIn">
+      Welcome, {{ user?.name }}
+      <button @click="logout">Logout</button>
+    </div>
+    <div v-else>
+      <button @click="handleLogin">Login</button>
+    </div>
+
+    <div>Cart: {{ totalItems }} items ({{ formattedTotal }})</div>
+  </div>
+</template>
+\`\`\`
+
+## Store Composition (Using Other Stores)
+\`\`\`typescript
+// stores/checkout.ts
+import { defineStore } from 'pinia';
+import { useUserStore } from './user';
+import { useCartStore } from './cart';
+
+export const useCheckoutStore = defineStore('checkout', () => {
+  const userStore = useUserStore();
+  const cartStore = useCartStore();
+
+  const canCheckout = computed(() =>
+    userStore.isLoggedIn && cartStore.totalItems > 0
+  );
+
+  async function processCheckout() {
+    if (!canCheckout.value) {
+      throw new Error('Cannot checkout');
+    }
+
+    const order = {
+      userId: userStore.user!.id,
+      items: cartStore.items,
+      total: cartStore.totalPrice,
+    };
+
+    const response = await fetch('/api/orders', {
+      method: 'POST',
+      body: JSON.stringify(order),
+    });
+
+    if (response.ok) {
+      cartStore.clearCart();
+      return response.json();
+    }
+
+    throw new Error('Checkout failed');
+  }
+
+  return { canCheckout, processCheckout };
+});
+\`\`\`
+
+## Plugins
+
+### Persistence Plugin
+\`\`\`typescript
+// plugins/piniaPersistedState.ts
+import { createPinia } from 'pinia';
+import piniaPluginPersistedstate from 'pinia-plugin-persistedstate';
+
+const pinia = createPinia();
+pinia.use(piniaPluginPersistedstate);
+
+// In store
+export const useUserStore = defineStore('user', () => {
+  const user = ref<User | null>(null);
+  // ...
+  return { user };
+}, {
+  persist: true, // Persist entire store
+
+  // Or with options
+  persist: {
+    key: 'user-store',
+    storage: sessionStorage, // Default: localStorage
+    paths: ['user'], // Only persist specific paths
+  },
+});
+\`\`\`
+
+### Custom Plugin
+\`\`\`typescript
+// plugins/logger.ts
+import { PiniaPluginContext } from 'pinia';
+
+export function loggerPlugin({ store }: PiniaPluginContext) {
+  store.$subscribe((mutation, state) => {
+    console.log(\`[\${mutation.storeId}] \${mutation.type}\`, state);
+  });
+
+  store.$onAction(({ name, store, args, after, onError }) => {
+    console.log(\`Action "\${name}" started on \${store.$id}\`);
+
+    after((result) => {
+      console.log(\`Action "\${name}" finished. Result:\`, result);
+    });
+
+    onError((error) => {
+      console.error(\`Action "\${name}" failed:\`, error);
+    });
+  });
+}
+
+// Register plugin
+pinia.use(loggerPlugin);
+\`\`\`
+
+## Reset Store
+\`\`\`typescript
+// Setup store - manual reset
+export const useUserStore = defineStore('user', () => {
+  const initialState = {
+    user: null as User | null,
+    loading: false,
+    error: null as string | null,
+  };
+
+  const user = ref(initialState.user);
+  const loading = ref(initialState.loading);
+  const error = ref(initialState.error);
+
+  function $reset() {
+    user.value = initialState.user;
+    loading.value = initialState.loading;
+    error.value = initialState.error;
+  }
+
+  return { user, loading, error, $reset };
+});
+
+// Options store - $reset is automatic
+const cartStore = useCartStore();
+cartStore.$reset(); // Resets to initial state
+\`\`\`
+
+## Testing
+\`\`\`typescript
+import { setActivePinia, createPinia } from 'pinia';
+import { useUserStore } from '@/stores/user';
+
+describe('User Store', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia());
+  });
+
+  it('should login user', async () => {
+    const store = useUserStore();
+
+    expect(store.isLoggedIn).toBe(false);
+
+    // Mock fetch
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({ id: '1', name: 'John', email: 'john@example.com' }),
+    });
+
+    await store.login('john@example.com', 'password');
+
+    expect(store.isLoggedIn).toBe(true);
+    expect(store.user?.name).toBe('John');
+  });
+
+  it('should handle login error', async () => {
+    const store = useUserStore();
+
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: false,
+    });
+
+    await expect(store.login('test@example.com', 'wrong')).rejects.toThrow();
+    expect(store.error).toBe('Login failed');
+  });
+});
+\`\`\`
+
+## Outside Components
+\`\`\`typescript
+// router/guards.ts
+import { useUserStore } from '@/stores/user';
+import type { Router } from 'vue-router';
+
+export function setupGuards(router: Router) {
+  router.beforeEach((to) => {
+    // Must be called after pinia is installed
+    const userStore = useUserStore();
+
+    if (to.meta.requiresAuth && !userStore.isLoggedIn) {
+      return { name: 'login', query: { redirect: to.fullPath } };
+    }
+  });
+}
+
+// api/client.ts
+import { useUserStore } from '@/stores/user';
+
+export async function apiClient(url: string, options?: RequestInit) {
+  const userStore = useUserStore();
+
+  return fetch(url, {
+    ...options,
+    headers: {
+      ...options?.headers,
+      Authorization: userStore.user ? \`Bearer \${userStore.token}\` : '',
+    },
+  });
+}
+\`\`\`
+
+## ❌ DON'T
+- Destructure state directly (loses reactivity)
+- Mutate state outside actions
+- Create stores inside components
+- Forget to use storeToRefs for reactive destructuring
+
+## ✅ DO
+- Use Setup Stores for better TypeScript support
+- Use storeToRefs when destructuring state/getters
+- Use store composition for related stores
+- Use persistence plugin for localStorage sync
+- Reset stores in tests with setActivePinia
+- Define $reset manually for Setup Stores