autoworkflow 3.1.5 → 3.5.0

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

@@ -0,0 +1,340 @@
+# Zustand Skill
+
+## Basic Store
+\`\`\`typescript
+import { create } from 'zustand';
+
+interface User {
+  id: string;
+  email: string;
+  name: string;
+}
+
+interface UserStore {
+  // State
+  user: User | null;
+  loading: boolean;
+  error: string | null;
+
+  // Actions
+  setUser: (user: User) => void;
+  clearUser: () => void;
+  fetchUser: (id: string) => Promise<void>;
+}
+
+const useUserStore = create<UserStore>((set, get) => ({
+  // Initial state
+  user: null,
+  loading: false,
+  error: null,
+
+  // Sync actions
+  setUser: (user) => set({ user }),
+  clearUser: () => set({ user: null, error: null }),
+
+  // Async action
+  fetchUser: async (id) => {
+    set({ loading: true, error: null });
+    try {
+      const response = await fetch(\`/api/users/\${id}\`);
+      if (!response.ok) throw new Error('Failed to fetch user');
+      const user = await response.json();
+      set({ user, loading: false });
+    } catch (error) {
+      set({ error: (error as Error).message, loading: false });
+    }
+  },
+}));
+
+// Usage in components
+function UserProfile({ userId }: { userId: string }) {
+  const { user, loading, fetchUser } = useUserStore();
+
+  useEffect(() => {
+    fetchUser(userId);
+  }, [userId, fetchUser]);
+
+  if (loading) return <div>Loading...</div>;
+  return <div>{user?.name}</div>;
+}
+\`\`\`
+
+## Selectors (Performance Optimization)
+\`\`\`typescript
+// ❌ Bad: Re-renders on any state change
+const { user, loading, error } = useUserStore();
+
+// ✅ Good: Only re-renders when selected state changes
+const user = useUserStore((state) => state.user);
+const loading = useUserStore((state) => state.loading);
+
+// Multiple values with shallow comparison
+import { shallow } from 'zustand/shallow';
+
+const { user, loading } = useUserStore(
+  (state) => ({ user: state.user, loading: state.loading }),
+  shallow
+);
+
+// Or use useShallow hook
+import { useShallow } from 'zustand/react/shallow';
+
+const { user, loading } = useUserStore(
+  useShallow((state) => ({ user: state.user, loading: state.loading }))
+);
+
+// Derived/computed values
+const userName = useUserStore((state) => state.user?.name);
+const isLoggedIn = useUserStore((state) => !!state.user);
+\`\`\`
+
+## Slices Pattern (Multiple Stores)
+\`\`\`typescript
+import { create, StateCreator } from 'zustand';
+
+// User slice
+interface UserSlice {
+  user: User | null;
+  setUser: (user: User) => void;
+  logout: () => void;
+}
+
+const createUserSlice: StateCreator<
+  UserSlice & CartSlice,
+  [],
+  [],
+  UserSlice
+> = (set) => ({
+  user: null,
+  setUser: (user) => set({ user }),
+  logout: () => set({ user: null }),
+});
+
+// Cart slice
+interface CartSlice {
+  items: CartItem[];
+  addItem: (item: CartItem) => void;
+  removeItem: (id: string) => void;
+  clearCart: () => void;
+}
+
+const createCartSlice: StateCreator<
+  UserSlice & CartSlice,
+  [],
+  [],
+  CartSlice
+> = (set) => ({
+  items: [],
+  addItem: (item) => set((state) => ({ items: [...state.items, item] })),
+  removeItem: (id) => set((state) => ({
+    items: state.items.filter((item) => item.id !== id),
+  })),
+  clearCart: () => set({ items: [] }),
+});
+
+// Combined store
+type StoreState = UserSlice & CartSlice;
+
+const useStore = create<StoreState>()((...a) => ({
+  ...createUserSlice(...a),
+  ...createCartSlice(...a),
+}));
+
+// Usage
+const user = useStore((state) => state.user);
+const items = useStore((state) => state.items);
+\`\`\`
+
+## Middleware
+
+### Persist (localStorage/sessionStorage)
+\`\`\`typescript
+import { create } from 'zustand';
+import { persist, createJSONStorage } from 'zustand/middleware';
+
+const useUserStore = create<UserStore>()(
+  persist(
+    (set, get) => ({
+      user: null,
+      setUser: (user) => set({ user }),
+      logout: () => set({ user: null }),
+    }),
+    {
+      name: 'user-storage', // localStorage key
+      storage: createJSONStorage(() => localStorage), // default
+      // Or sessionStorage:
+      // storage: createJSONStorage(() => sessionStorage),
+
+      // Partial persistence (only persist some fields)
+      partialize: (state) => ({ user: state.user }),
+
+      // Version for migrations
+      version: 1,
+      migrate: (persistedState, version) => {
+        if (version === 0) {
+          // Migration logic
+        }
+        return persistedState as UserStore;
+      },
+
+      // Skip hydration until ready
+      skipHydration: true,
+    }
+  )
+);
+
+// Manual hydration (when skipHydration: true)
+useEffect(() => {
+  useUserStore.persist.rehydrate();
+}, []);
+
+// Clear persisted state
+useUserStore.persist.clearStorage();
+\`\`\`
+
+### DevTools
+\`\`\`typescript
+import { create } from 'zustand';
+import { devtools } from 'zustand/middleware';
+
+const useStore = create<StoreState>()(
+  devtools(
+    (set) => ({
+      // ... store
+    }),
+    {
+      name: 'MyApp Store', // Name in DevTools
+      enabled: process.env.NODE_ENV === 'development',
+    }
+  )
+);
+
+// Named actions in DevTools
+set({ user }, false, 'setUser');
+set({ user: null }, false, 'logout');
+\`\`\`
+
+### Immer (Immutable Updates)
+\`\`\`typescript
+import { create } from 'zustand';
+import { immer } from 'zustand/middleware/immer';
+
+interface TodoStore {
+  todos: Todo[];
+  addTodo: (text: string) => void;
+  toggleTodo: (id: string) => void;
+  updateTodo: (id: string, text: string) => void;
+}
+
+const useTodoStore = create<TodoStore>()(
+  immer((set) => ({
+    todos: [],
+
+    addTodo: (text) =>
+      set((state) => {
+        state.todos.push({ id: crypto.randomUUID(), text, completed: false });
+      }),
+
+    toggleTodo: (id) =>
+      set((state) => {
+        const todo = state.todos.find((t) => t.id === id);
+        if (todo) todo.completed = !todo.completed;
+      }),
+
+    updateTodo: (id, text) =>
+      set((state) => {
+        const todo = state.todos.find((t) => t.id === id);
+        if (todo) todo.text = text;
+      }),
+  }))
+);
+\`\`\`
+
+### Combining Middleware
+\`\`\`typescript
+const useStore = create<StoreState>()(
+  devtools(
+    persist(
+      immer((set) => ({
+        // ... store implementation
+      })),
+      { name: 'app-storage' }
+    ),
+    { name: 'AppStore' }
+  )
+);
+\`\`\`
+
+## Subscribing to Changes
+\`\`\`typescript
+// Subscribe outside React
+const unsubscribe = useUserStore.subscribe(
+  (state) => console.log('State changed:', state)
+);
+
+// Subscribe to specific slice
+const unsubscribe = useUserStore.subscribe(
+  (state) => state.user,
+  (user, prevUser) => {
+    console.log('User changed:', { user, prevUser });
+  }
+);
+
+// Get state outside React
+const currentUser = useUserStore.getState().user;
+
+// Set state outside React
+useUserStore.setState({ user: newUser });
+
+// With action
+useUserStore.getState().setUser(newUser);
+\`\`\`
+
+## Testing
+\`\`\`typescript
+import { act, renderHook } from '@testing-library/react';
+import { useUserStore } from './userStore';
+
+// Reset store between tests
+beforeEach(() => {
+  useUserStore.setState({ user: null, loading: false, error: null });
+});
+
+test('should set user', () => {
+  const { result } = renderHook(() => useUserStore());
+
+  act(() => {
+    result.current.setUser({ id: '1', email: 'test@example.com', name: 'Test' });
+  });
+
+  expect(result.current.user).toEqual({
+    id: '1',
+    email: 'test@example.com',
+    name: 'Test',
+  });
+});
+
+// Test with initial state
+test('should start with loading false', () => {
+  const { result } = renderHook(() =>
+    useUserStore((state) => state.loading)
+  );
+
+  expect(result.current).toBe(false);
+});
+\`\`\`
+
+## ❌ DON'T
+- Destructure entire store (causes unnecessary re-renders)
+- Put functions in state that should be actions
+- Forget to use shallow comparison for object selectors
+- Mutate state directly (use set or immer)
+
+## ✅ DO
+- Use selectors for fine-grained subscriptions
+- Use shallow for multiple values
+- Use persist middleware for local storage
+- Use devtools in development
+- Use immer for complex nested updates
+- Use slices for large stores
+- Reset store state in tests