ai-playbook 1.0.0

package/roles/software-developer/frontend/state-management/best-practices.md

@@ -0,0 +1,344 @@
+# State Management: Best Practices
+
+Effective state management is crucial for building scalable, maintainable frontend applications. This guide covers how to minimize state, place it correctly, and manage async operations.
+
+## Minimize State
+
+The less state you have, the fewer bugs you'll have. Before adding something as state, ask: "Does this need to change over time?"
+
+**What should NOT be state:**
+
+```javascript
+// BAD: Derived values as state
+function User({ firstName, lastName }) {
+  const [fullName, setFullName] = useState('');
+  
+  useEffect(() => {
+    setFullName(`${firstName} ${lastName}`);
+  }, [firstName, lastName]);
+  
+  return <div>{fullName}</div>;
+}
+
+// GOOD: Derive directly
+function User({ firstName, lastName }) {
+  const fullName = `${firstName} ${lastName}`;
+  return <div>{fullName}</div>;
+}
+
+// BAD: Stable values as state
+function Form() {
+  const [submitUrl, setSubmitUrl] = useState('/api/users');
+  // submitUrl never changes!
+  
+  return <form action={submitUrl}>{...}</form>;
+}
+
+// GOOD: Use constant
+const SUBMIT_URL = '/api/users';
+
+function Form() {
+  return <form action={SUBMIT_URL}>{...}</form>;
+}
+```
+
+**What SHOULD be state:**
+
+Values that:
+- Change over time (user input, server data, UI state)
+- Multiple parts of the component depend on
+- Affect component behavior or rendering
+
+```javascript
+// GOOD: Essential UI state
+function SearchableList({ items }) {
+  const [searchTerm, setSearchTerm] = useState('');
+  const [sortBy, setSortBy] = useState('name');
+  
+  const filtered = items.filter(item => 
+    item.name.includes(searchTerm)
+  );
+  const sorted = filtered.sort((a, b) => 
+    a[sortBy].localeCompare(b[sortBy])
+  );
+  
+  return (
+    <>
+      <input 
+        value={searchTerm}
+        onChange={(e) => setSearchTerm(e.target.value)}
+        placeholder="Search..."
+      />
+      <select value={sortBy} onChange={(e) => setSortBy(e.target.value)}>
+        <option value="name">Name</option>
+        <option value="date">Date</option>
+      </select>
+      <ul>
+        {sorted.map(item => <li key={item.id}>{item.name}</li>)}
+      </ul>
+    </>
+  );
+}
+```
+
+## State Placement
+
+State belongs at the lowest level that needs it. Consider four categories:
+
+**Local state:** Component manages its own UI state.
+
+```javascript
+function Accordion({ items }) {
+  const [expanded, setExpanded] = useState(null);
+  
+  return items.map(item => (
+    <div key={item.id}>
+      <button onClick={() => setExpanded(expanded === item.id ? null : item.id)}>
+        {item.title}
+      </button>
+      {expanded === item.id && <div>{item.content}</div>}
+    </div>
+  ));
+}
+```
+
+**Shared state:** Multiple components at the same level need data.
+
+```javascript
+function Dashboard() {
+  const [selectedUser, setSelectedUser] = useState(null);
+  
+  return (
+    <>
+      <UserList onSelect={setSelectedUser} />
+      {selectedUser && <UserDetail user={selectedUser} />}
+    </>
+  );
+}
+```
+
+**Server state:** Data from API. Treat differently from UI state.
+
+```javascript
+function UserData({ userId }) {
+  const [data, setData] = useState(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState(null);
+  
+  useEffect(() => {
+    fetchUser(userId)
+      .then(data => {
+        setData(data);
+        setIsLoading(false);
+      })
+      .catch(err => {
+        setError(err);
+        setIsLoading(false);
+      });
+  }, [userId]);
+  
+  return <div>...</div>;
+}
+```
+
+**Derived state:** Computed from other state. Don't store it.
+
+```javascript
+function ShoppingCart({ items }) {
+  const [quantities, setQuantities] = useState({});
+  
+  // BAD: Store total as state
+  const [total, setTotal] = useState(0);
+  
+  // GOOD: Calculate when needed
+  const total = items.reduce((sum, item) => 
+    sum + (item.price * (quantities[item.id] || 0)), 0
+  );
+  
+  return <div>Total: ${total.toFixed(2)}</div>;
+}
+```
+
+## Immutability
+
+Never mutate state directly. Always create new objects and arrays.
+
+```javascript
+// BAD: Mutation
+function addTodo(text) {
+  todos.push({ id: Date.now(), text });
+  setTodos(todos);
+}
+
+// GOOD: Create new array
+function addTodo(text) {
+  setTodos([...todos, { id: Date.now(), text }]);
+}
+
+// BAD: Mutating nested object
+function updateUser(userId, changes) {
+  user.profile.name = changes.name;
+  setUser(user);
+}
+
+// GOOD: Create new object with spread
+function updateUser(userId, changes) {
+  setUser({
+    ...user,
+    profile: { ...user.profile, ...changes }
+  });
+}
+
+// For complex updates, use a library like immer:
+function updateNestedData(changes) {
+  setData(produce(data, draft => {
+    draft.deeply.nested.value = changes.value;
+  }));
+}
+```
+
+## Data Flow
+
+Maintain unidirectional data flow: parent → child via props, child → parent via callbacks.
+
+```javascript
+// GOOD: Unidirectional flow
+function Parent() {
+  const [count, setCount] = useState(0);
+  
+  return <Child count={count} onIncrement={() => setCount(count + 1)} />;
+}
+
+function Child({ count, onIncrement }) {
+  return (
+    <>
+      <div>Count: {count}</div>
+      <button onClick={onIncrement}>Increment</button>
+    </>
+  );
+}
+
+// BAD: Bidirectional (child modifies parent's state directly)
+// This breaks the dependency chain and makes debugging hard
+```
+
+## State Management Patterns
+
+**useReducer for complex state:**
+
+```javascript
+const initialState = { items: [], loading: false, error: null };
+
+function reducer(state, action) {
+  switch (action.type) {
+    case 'FETCH_START':
+      return { ...state, loading: true };
+    case 'FETCH_SUCCESS':
+      return { items: action.payload, loading: false, error: null };
+    case 'FETCH_ERROR':
+      return { ...state, loading: false, error: action.payload };
+    default:
+      return state;
+  }
+}
+
+function Component() {
+  const [state, dispatch] = useReducer(reducer, initialState);
+  
+  useEffect(() => {
+    dispatch({ type: 'FETCH_START' });
+    fetchItems()
+      .then(data => dispatch({ type: 'FETCH_SUCCESS', payload: data }))
+      .catch(err => dispatch({ type: 'FETCH_ERROR', payload: err }));
+  }, []);
+  
+  return <div>...</div>;
+}
+```
+
+**Context for shared state:**
+
+```javascript
+const ThemeContext = createContext();
+
+function ThemeProvider({ children }) {
+  const [theme, setTheme] = useState('light');
+  
+  const toggle = () => setTheme(theme === 'light' ? 'dark' : 'light');
+  
+  return (
+    <ThemeContext.Provider value={{ theme, toggle }}>
+      {children}
+    </ThemeContext.Provider>
+  );
+}
+
+function useTheme() {
+  const context = useContext(ThemeContext);
+  if (!context) throw new Error('useTheme must be used in ThemeProvider');
+  return context;
+}
+
+function Component() {
+  const { theme, toggle } = useTheme();
+  return <button onClick={toggle}>Theme: {theme}</button>;
+}
+```
+
+## Async State
+
+Handle async operations with three explicit states: loading, success, error.
+
+```javascript
+function useAsync(asyncFn, immediate = true) {
+  const [state, dispatch] = useReducer(
+    (state, action) => ({ ...state, ...action }),
+    { status: 'idle', data: null, error: null }
+  );
+  
+  const execute = useCallback(async () => {
+    dispatch({ status: 'pending' });
+    try {
+      const data = await asyncFn();
+      dispatch({ status: 'success', data });
+    } catch (error) {
+      dispatch({ status: 'error', error });
+    }
+  }, [asyncFn]);
+  
+  useEffect(() => {
+    if (immediate) execute();
+  }, [execute, immediate]);
+  
+  return { ...state, execute };
+}
+
+// Usage
+function Component() {
+  const { status, data, error } = useAsync(() => fetchUser(123));
+  
+  if (status === 'pending') return <div>Loading...</div>;
+  if (status === 'error') return <div>Error: {error.message}</div>;
+  if (status === 'success') return <div>{data.name}</div>;
+}
+```
+
+## State Management Best Practices Checklist
+
+- [ ] State is minimized (no derived values)
+- [ ] Each state variable has clear ownership
+- [ ] No prop drilling beyond 2-3 levels
+- [ ] Async operations use loading/error/success pattern
+- [ ] State mutations always create new objects
+- [ ] Data flow is unidirectional (parent → child → parent)
+- [ ] Complex state logic extracted to useReducer
+- [ ] Shared state uses Context or state management library
+- [ ] Server state separate from UI state
+- [ ] useEffect dependencies are correct
+
+## Related Guidance
+
+- `/components` — component design for state placement  
+- `/code-quality` — naming conventions for state  
+- `/testing` — testing state changes  
+- `/logging-observability` — tracking state changes

package/roles/software-developer/frontend/testing/README.md

@@ -0,0 +1,114 @@
+# Testing
+
+Senior frontend developers test thoroughly: unit, integration, and e2e. Always test after changes.
+
+## Testing Pyramid
+
+```
+         E2E (few, full app flow)
+       /                        \
+    Integration (component + API)
+   /                              \
+Unit (function, component in isolation)
+```
+
+Test more at bottom, fewer at top.
+
+## Unit Tests
+
+### What to Test
+- Pure functions (utilities, formatters, validators)
+- Component rendering with different props
+- State updates and side effects
+- Event handlers and callbacks
+- Logic branches (happy path + edge cases)
+
+### What NOT to Test
+- Framework internals (React's rendering)
+- Third-party library behavior
+- Implementation details (prefer testing behavior)
+
+### Test Structure
+```
+describe('MyComponent', () => {
+  it('renders with required props', () => { ... })
+  it('calls onClick when clicked', () => { ... })
+  it('handles error state', () => { ... })
+})
+```
+
+### Tools
+- Jest (testing framework)
+- React Testing Library (component testing)
+- Vitest (modern Jest alternative)
+
+## Integration Tests
+
+### What to Test
+- Components working together
+- Component + state management
+- Component + API (mock API)
+- User workflows (form submission, navigation)
+
+### Approach
+- Mount multiple components
+- Mock API responses
+- Simulate user interactions
+- Assert final state/DOM
+
+### Tools
+- React Testing Library (recommended)
+- Cypress (browser-based)
+- Playwright (full browser testing)
+
+## E2E Tests
+
+### What to Test
+- Full user journeys
+- Real backend (or staging)
+- Navigation, data persistence
+- Error handling in real conditions
+
+### Characteristics
+- Slow, expensive
+- Real-world conditions
+- Test critical paths only
+- Run less frequently
+
+### Tools
+- Cypress
+- Playwright
+- Selenium (older)
+
+## Test Coverage Guidelines
+
+- **Aim for 80%+ line coverage**
+- Don't chase 100% (diminishing returns)
+- Focus on behavior, not coverage numbers
+- Mission-critical paths: 100% coverage
+- Utilities and helpers: 80%+ coverage
+
+## Testing Anti-Patterns
+
+- Testing implementation details
+- Over-mocking (mocking too much loses integration value)
+- Flaky tests (timing-dependent)
+- Tests that depend on test order
+- Not testing error cases
+- Insufficient assertions (test passes but doesn't verify)
+
+## Testing Checklist
+
+After every change:
+- [ ] Unit tests pass
+- [ ] Integration tests pass
+- [ ] Coverage maintained/improved
+- [ ] No test regressions
+- [ ] Edge cases covered
+- [ ] Error paths tested
+
+## Related Guidance
+
+- `/code-quality` — test formatting and style
+- `/debugging` — debug failing tests
+- `/logging-observability` — logging in tests