ai-flow-dev 1.0.1

package/templates/frontend/docs/pwa.template.md

@@ -0,0 +1,135 @@
+# Progressive Web App (PWA)
+
+> PWA features and offline capabilities for {{PROJECT_NAME}}
+
+---
+
+## 🎯 PWA Strategy
+
+**Service Worker:** {{SERVICE_WORKER_ENABLED}}
+**Caching Strategy:** {{CACHING_STRATEGY}}
+**Install Prompt:** {{INSTALL_PROMPT}}
+**Offline Support:** {{OFFLINE_SUPPORT}}
+
+---
+
+## 🔧 Service Worker
+
+### Registration
+
+```typescript
+// registerServiceWorker.ts
+if ('serviceWorker' in navigator) {
+  window.addEventListener('load', () => {
+    navigator.serviceWorker
+      .register('/sw.js')
+      .then((registration) => {
+        console.log('SW registered:', registration);
+      })
+      .catch((error) => {
+        console.error('SW registration failed:', error);
+      });
+  });
+}
+```
+
+### Service Worker Implementation
+
+```javascript
+// public/sw.js
+const CACHE_NAME = 'app-v1';
+const urlsToCache = [
+  '/',
+  '/index.html',
+  '/assets/app.js',
+  '/assets/app.css',
+];
+
+// Install
+self.addEventListener('install', (event) => {
+  event.waitUntil(
+    caches.open(CACHE_NAME).then((cache) => {
+      return cache.addAll(urlsToCache);
+    })
+  );
+});
+
+// Fetch (Cache-first strategy)
+self.addEventListener('fetch', (event) => {
+  event.respondWith(
+    caches.match(event.request).then((response) => {
+      return response || fetch(event.request);
+    })
+  );
+});
+```
+
+---
+
+## 📱 Web App Manifest
+
+```json
+// public/manifest.json
+{
+  "name": "{{PROJECT_NAME}}",
+  "short_name": "{{PROJECT_SHORT_NAME}}",
+  "description": "{{PROJECT_DESCRIPTION}}",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#ffffff",
+  "theme_color": "#000000",
+  "icons": [
+    {
+      "src": "/icon-192.png",
+      "sizes": "192x192",
+      "type": "image/png"
+    },
+    {
+      "src": "/icon-512.png",
+      "sizes": "512x512",
+      "type": "image/png"
+    }
+  ]
+}
+```
+
+---
+
+## 📲 Install Prompt
+
+```typescript
+// utils/installPrompt.ts
+let deferredPrompt: BeforeInstallPromptEvent | null = null;
+
+window.addEventListener('beforeinstallprompt', (e) => {
+  e.preventDefault();
+  deferredPrompt = e;
+  showInstallButton();
+});
+
+export function showInstallPrompt() {
+  if (deferredPrompt) {
+    deferredPrompt.prompt();
+    deferredPrompt.userChoice.then((choiceResult) => {
+      if (choiceResult.outcome === 'accepted') {
+        console.log('User accepted install');
+      }
+      deferredPrompt = null;
+    });
+  }
+}
+```
+
+---
+
+## 🔗 Related Documents
+
+- [Performance](performance.md) - PWA performance
+- [Operations](operations.md) - PWA deployment
+
+---
+
+**Last Updated:** {{GENERATION_DATE}}
+
+**PWA Features:** {{PWA_FEATURES}}
+

package/templates/frontend/docs/state-management.template.md

@@ -0,0 +1,394 @@
+# State Management
+
+> State management patterns and best practices for {{PROJECT_NAME}}
+
+---
+
+## 🎯 State Management Solution
+
+**Solution:** {{STATE_MANAGEMENT}}
+
+{{STATE_MANAGEMENT_DESCRIPTION}}
+
+---
+
+## 📊 State Categories
+
+### 1. Server State (Remote Data)
+
+**Managed by:** {{DATA_FETCHING}}
+
+**Characteristics:**
+- Fetched from APIs
+- Cached and synchronized
+- May be stale
+- Shared across components
+
+**Examples:**
+- User data from `/api/user`
+- Product listings
+- Blog posts
+
+**Pattern:**
+```typescript
+// Using {{DATA_FETCHING}}
+const { data, isLoading, error, refetch } = useQuery({
+  queryKey: ['users', userId],
+  queryFn: () => fetchUser(userId)
+});
+
+if (isLoading) return <Spinner />;
+if (error) return <Error message={error.message} />;
+
+return <UserProfile user={data} />;
+```
+
+---
+
+### 2. Client State (Local UI State)
+
+**Managed by:** {{STATE_MANAGEMENT}}
+
+**Characteristics:**
+- Exists only in frontend
+- Controls UI behavior
+- Not persisted to server (usually)
+
+**Examples:**
+- Modal open/closed
+- Theme (dark/light mode)
+- Current tab selected
+- Form validation errors
+
+**Pattern:**
+```typescript
+// Using {{STATE_MANAGEMENT}}
+{{CLIENT_STATE_EXAMPLE}}
+```
+
+---
+
+### 3. URL State (Query Params & Routes)
+
+**Managed by:** Router + URL
+
+**Characteristics:**
+- Persisted in URL
+- Shareable via link
+- Browser back/forward works
+
+**Examples:**
+- Search query: `?q=react`
+- Filters: `?category=tech&sort=date`
+- Pagination: `?page=3`
+- Selected item: `/posts/123`
+
+**Pattern:**
+```typescript
+// React Router
+const [searchParams, setSearchParams] = useSearchParams();
+const query = searchParams.get('q') || '';
+
+// Vue Router
+const route = useRoute();
+const query = route.query.q || '';
+```
+
+---
+
+### 4. Form State
+
+**Managed by:** {{FORM_LIBRARY}}
+
+**Characteristics:**
+- Temporary, component-scoped
+- Validation logic
+- Reset on submit
+
+**Pattern:**
+```typescript
+// Using {{FORM_LIBRARY}}
+{{FORM_STATE_EXAMPLE}}
+```
+
+---
+
+## 🏗️ State Architecture
+
+### State Location Decision Tree
+
+```
+Is data from server?
+├─ YES → Use {{DATA_FETCHING}} (server state)
+└─ NO → Is it global/shared?
+    ├─ YES → Use {{STATE_MANAGEMENT}} (global client state)
+    └─ NO → Is it URL-related?
+        ├─ YES → Use router/query params (URL state)
+        └─ NO → Use local component state
+```
+
+---
+
+## 🎨 {{STATE_MANAGEMENT}} Patterns
+
+### Store Structure
+
+```typescript
+{{STORE_STRUCTURE_EXAMPLE}}
+```
+
+### Reading State
+
+```typescript
+{{READ_STATE_EXAMPLE}}
+```
+
+### Updating State
+
+```typescript
+{{UPDATE_STATE_EXAMPLE}}
+```
+
+---
+
+## 🔄 Data Flow
+
+### Unidirectional Data Flow
+
+```
+User Action
+    ↓
+Event Handler
+    ↓
+Update State (store/API)
+    ↓
+State Change
+    ↓
+Component Re-render
+    ↓
+Updated UI
+```
+
+### Example: Todo App
+
+```typescript
+// 1. User clicks "Add Todo"
+<button onClick={() => addTodo(text)}>Add</button>
+
+// 2. Action dispatched
+const addTodo = (text: string) => {
+  // Update local state optimistically
+  setTodos([...todos, { id: Date.now(), text, done: false }]);
+
+  // Sync to server
+  api.createTodo({ text })
+    .catch(error => {
+      // Rollback on error
+      setTodos(todos);
+      showError(error);
+    });
+};
+
+// 3. State updated → Component re-renders
+```
+
+---
+
+## 🚀 Performance Optimization
+
+### 1. Avoid Over-Rendering
+
+```typescript
+// ❌ Bad - Every field change re-renders entire form
+const FormContainer = () => {
+  const [formData, setFormData] = useState({ name: '', email: '', bio: '' });
+
+  return <Form data={formData} onChange={setFormData} />;
+};
+
+// ✅ Good - Each field independent
+const FormContainer = () => {
+  return (
+    <Form>
+      <NameField />
+      <EmailField />
+      <BioField />
+    </Form>
+  );
+};
+```
+
+### 2. Selector Optimization
+
+```typescript
+// ❌ Bad - New array every render (breaks memoization)
+const activeUsers = useStore(state => state.users.filter(u => u.active));
+
+// ✅ Good - Memoized selector
+const selectActiveUsers = createSelector(
+  [(state) => state.users],
+  (users) => users.filter(u => u.active)
+);
+const activeUsers = useStore(selectActiveUsers);
+```
+
+### 3. State Normalization
+
+```typescript
+// ❌ Bad - Nested, hard to update
+const state = {
+  posts: [
+    { id: 1, title: 'Post 1', author: { id: 10, name: 'Alice' } },
+    { id: 2, title: 'Post 2', author: { id: 10, name: 'Alice' } }
+  ]
+};
+
+// ✅ Good - Normalized
+const state = {
+  posts: {
+    byId: {
+      1: { id: 1, title: 'Post 1', authorId: 10 },
+      2: { id: 2, title: 'Post 2', authorId: 10 }
+    },
+    allIds: [1, 2]
+  },
+  users: {
+    byId: {
+      10: { id: 10, name: 'Alice' }
+    }
+  }
+};
+```
+
+---
+
+## 🔐 State Persistence
+
+### Local Storage
+
+```typescript
+// Save state to localStorage
+const saveState = (key: string, state: any) => {
+  localStorage.setItem(key, JSON.stringify(state));
+};
+
+// Load state from localStorage
+const loadState = (key: string) => {
+  const saved = localStorage.getItem(key);
+  return saved ? JSON.parse(saved) : null;
+};
+
+// Initialize store with persisted state
+const useThemeStore = create(
+  persist(
+    (set) => ({
+      theme: 'light',
+      setTheme: (theme) => set({ theme })
+    }),
+    { name: 'theme-storage' }
+  )
+);
+```
+
+---
+
+## 🧪 Testing State
+
+### Unit Testing Store Logic
+
+```typescript
+describe('TodoStore', () => {
+  it('adds todo', () => {
+    const { result } = renderHook(() => useTodoStore());
+
+    act(() => {
+      result.current.addTodo('Buy milk');
+    });
+
+    expect(result.current.todos).toHaveLength(1);
+    expect(result.current.todos[0].text).toBe('Buy milk');
+  });
+});
+```
+
+### Integration Testing with Components
+
+```typescript
+test('displays todos from store', () => {
+  const todos = [
+    { id: 1, text: 'Todo 1', done: false },
+    { id: 2, text: 'Todo 2', done: true }
+  ];
+
+  // Setup store state
+  useTodoStore.setState({ todos });
+
+  render(<TodoList />);
+
+  expect(screen.getByText('Todo 1')).toBeInTheDocument();
+  expect(screen.getByText('Todo 2')).toBeInTheDocument();
+});
+```
+
+---
+
+## ⚠️ Common Pitfalls
+
+### 1. Storing Derived Data
+
+```typescript
+// ❌ Bad - Storing computed value
+const state = {
+  todos: [...],
+  completedCount: 5  // Derived from todos
+};
+
+// ✅ Good - Compute on the fly
+const state = {
+  todos: [...]
+};
+const completedCount = todos.filter(t => t.done).length;
+```
+
+### 2. Mutating State Directly
+
+```typescript
+// ❌ Bad - Direct mutation
+state.user.name = 'Alice';
+
+// ✅ Good - Immutable update
+setState({ user: { ...state.user, name: 'Alice' } });
+```
+
+### 3. Over-Using Global State
+
+```typescript
+// ❌ Bad - Everything in global store
+const globalState = {
+  modalOpen: false,  // Should be local
+  currentTab: 'home',  // Should be URL
+  formErrors: {},  // Should be form state
+};
+
+// ✅ Good - Only truly global data
+const globalState = {
+  user: { ... },
+  theme: 'dark',
+  notifications: [...]
+};
+```
+
+---
+
+## 🔗 Related Documents
+
+- [AI Instructions](../ai-instructions.md) - State management rules
+- [Component Architecture](components.md) - Component/state interaction
+- [API Integration](api-integration.md) - Server state patterns
+- [Testing Strategy](testing.md) - Testing state logic
+
+---
+
+**Last Updated:** {{GENERATION_DATE}}
+
+**Solution:** {{STATE_MANAGEMENT}}