desktop-team-doc 0.1.0

package/content/tools/skills/frontend-develop/references/performance-optimization.md

@@ -0,0 +1,678 @@
+# Performance Optimization Guidelines
+
+This document provides comprehensive guidelines for optimizing React component performance, including proper use of hooks (`useMemo`, `useCallback`, `useEffect`), re-render optimization, and CSS performance considerations.
+
+## Core Principles
+
+### Avoid Premature Optimization
+
+**Rule**: Optimize only when there's a measurable performance problem.
+
+**Process**:
+1. Measure performance first (React DevTools Profiler)
+2. Identify bottlenecks
+3. Apply targeted optimizations
+4. Measure again to verify improvement
+
+## useMemo Usage
+
+### When to Use useMemo
+
+Use `useMemo` when:
+1. **Expensive computations**: Calculations that are computationally expensive
+2. **Reference equality**: When you need to maintain reference equality for dependencies
+3. **Preventing child re-renders**: When passing objects/arrays to memoized children
+
+### When NOT to Use useMemo
+
+**Avoid** `useMemo` for:
+- Simple calculations (addition, string concatenation)
+- Primitive values (strings, numbers, booleans)
+- Every computation (overhead can outweigh benefits)
+
+**Bad**:
+```typescript
+function Component({ count }: { count: number }) {
+  // Unnecessary: simple addition is fast
+  const doubled = useMemo(() => count * 2, [count]);
+  return <div>{doubled}</div>;
+}
+```
+
+**Good**:
+```typescript
+interface ComponentProps {
+  count: number;
+}
+
+function Component({ count }: ComponentProps) {
+  // Simple calculation, no memoization needed
+  const doubled = count * 2;
+  return <div>{doubled}</div>;
+}
+```
+
+### useMemo Best Practices
+
+**Example 1: Expensive Computation**
+```typescript
+interface DataTableProps {
+  data: DataItem[];
+  filters: FilterConfig;
+}
+
+function DataTable({ data, filters }: DataTableProps) {
+  // Expensive: filtering and sorting large dataset
+  const filteredData = useMemo(() => {
+    return data
+      .filter(item => matchesFilters(item, filters))
+      .sort((a, b) => a.date - b.date);
+  }, [data, filters]);
+
+  return <Table data={filteredData} />;
+}
+```
+
+**Example 2: Reference Equality for Dependencies**
+```typescript
+interface ComponentProps {
+  items: Item[];
+}
+
+function Component({ items }: ComponentProps) {
+  // Maintain reference equality to prevent unnecessary re-renders
+  const itemMap = useMemo(() => {
+    return new Map(items.map(item => [item.id, item]));
+  }, [items]);
+
+  return <ChildComponent itemMap={itemMap} />;
+}
+```
+
+**Example 3: Preventing Child Re-renders**
+```typescript
+interface ParentProps {
+  data: Data[];
+}
+
+const MemoizedChild = React.memo(ChildComponent);
+
+function Parent({ data }: ParentProps) {
+  // Memoize object to prevent Child re-renders
+  const config = useMemo(() => ({
+    columns: data[0]?.columns || [],
+    sortable: true,
+  }), [data]);
+
+  return <MemoizedChild config={config} />;
+}
+```
+
+## useCallback Usage
+
+### When to Use useCallback
+
+Use `useCallback` when:
+1. **Memoized children**: Passing functions to `React.memo` components
+2. **Hook dependencies**: Functions used in `useEffect`, `useMemo`, or other hooks
+3. **Expensive function creation**: Functions that are expensive to create
+
+### When NOT to Use useCallback
+
+**Avoid** `useCallback` for:
+- Functions passed to native DOM elements
+- Functions that change on every render anyway
+- Simple inline functions
+
+**Bad**:
+```typescript
+function Component({ onClick }: { onClick: () => void }) {
+  // Unnecessary: onClick is already stable
+  const handleClick = useCallback(() => {
+    onClick();
+  }, [onClick]);
+
+  return <button onClick={handleClick}>Click</button>;
+}
+```
+
+**Good**:
+```typescript
+interface ComponentProps {
+  onClick: () => void;
+}
+
+function Component({ onClick }: ComponentProps) {
+  // Direct pass-through is fine
+  return <button onClick={onClick}>Click</button>;
+}
+```
+
+### useCallback Best Practices
+
+**Example 1: Memoized Child Component**
+```typescript
+interface ParentProps {
+  items: Item[];
+}
+
+const MemoizedChild = React.memo(ChildComponent);
+
+function Parent({ items }: ParentProps) {
+  // Memoize callback to prevent Child re-renders
+  const handleItemClick = useCallback((id: string) => {
+    console.log('Item clicked:', id);
+  }, []);
+
+  return <MemoizedChild items={items} onItemClick={handleItemClick} />;
+}
+```
+
+**Example 2: Hook Dependencies**
+```typescript
+interface ComponentProps {
+  userId: string;
+}
+
+function Component({ userId }: ComponentProps) {
+  // Memoize function used in useEffect
+  const fetchUser = useCallback(async () => {
+    const response = await fetch(`/api/users/${userId}`);
+    return response.json();
+  }, [userId]);
+
+  useEffect(() => {
+    fetchUser().then(setUser);
+  }, [fetchUser]);
+
+  return <div>{/* ... */}</div>;
+}
+```
+
+**Example 3: Event Handler with Dependencies**
+```typescript
+interface ComponentProps {
+  items: Item[];
+  onUpdate: (item: Item) => void;
+}
+
+function Component({ items, onUpdate }: ComponentProps) {
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+
+  // Memoize handler that depends on state
+  const handleSelect = useCallback((id: string) => {
+    setSelectedId(id);
+    const item = items.find(i => i.id === id);
+    if (item) {
+      onUpdate(item);
+    }
+  }, [items, onUpdate]);
+
+  return <ItemList items={items} onSelect={handleSelect} />;
+}
+```
+
+## useEffect Best Practices
+
+### Dependency Array Rules
+
+**Rule**: Always specify complete dependency arrays.
+
+**Bad**:
+```typescript
+useEffect(() => {
+  fetchData(userId, filters);
+}, [userId]); // Missing filters dependency
+```
+
+**Good**:
+```typescript
+useEffect(() => {
+  fetchData(userId, filters);
+}, [userId, filters]); // Complete dependency array
+```
+
+### Avoiding Unnecessary Effects
+
+**Rule**: Don't use `useEffect` for derived state.
+
+**Bad**:
+```typescript
+function Component({ items }: { items: Item[] }) {
+  const [filteredItems, setFilteredItems] = useState<Item[]>([]);
+
+  useEffect(() => {
+    setFilteredItems(items.filter(item => item.active));
+  }, [items]);
+
+  return <ItemList items={filteredItems} />;
+}
+```
+
+**Good**:
+```typescript
+function Component({ items }: { items: Item[] }) {
+  // Compute directly, no effect needed
+  const filteredItems = items.filter(item => item.active);
+
+  return <ItemList items={filteredItems} />;
+}
+```
+
+### Effect Cleanup
+
+**Rule**: Always clean up subscriptions, timers, and event listeners.
+
+**Example**:
+```typescript
+function Component({ userId }: { userId: string }) {
+  useEffect(() => {
+    const controller = new AbortController();
+
+    fetch(`/api/users/${userId}`, {
+      signal: controller.signal,
+    })
+      .then(res => res.json())
+      .then(setUser)
+      .catch(err => {
+        if (err.name !== 'AbortError') {
+          console.error(err);
+        }
+      });
+
+    // Cleanup: abort request on unmount or userId change
+    return () => {
+      controller.abort();
+    };
+  }, [userId]);
+
+  return <div>{/* ... */}</div>;
+}
+```
+
+### Effect Optimization Patterns
+
+**Pattern 1: Debounced Effects**
+```typescript
+interface SearchInputProps {
+  onSearch: (query: string) => void;
+}
+
+function SearchInput({ onSearch }: SearchInputProps) {
+  const [query, setQuery] = useState('');
+
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      onSearch(query);
+    }, 300);
+
+    return () => clearTimeout(timer);
+  }, [query, onSearch]);
+
+  return <input value={query} onChange={e => setQuery(e.target.value)} />;
+}
+```
+
+**Pattern 2: Conditional Effects**
+```typescript
+interface ComponentProps {
+  enabled: boolean;
+  userId: string;
+}
+
+function Component({ enabled, userId }: ComponentProps) {
+  useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+
+    // Effect logic only runs when enabled is true
+    const subscription = subscribe(userId);
+    return () => subscription.unsubscribe();
+  }, [enabled, userId]);
+
+  return <div>{/* ... */}</div>;
+}
+```
+
+## Re-render Optimization
+
+### Identifying Re-render Issues
+
+**Tools**:
+- React DevTools Profiler
+- `why-did-you-render` library
+- Console logs with `useEffect`
+
+### Common Causes of Unnecessary Re-renders
+
+1. **New object/array references**: Creating new objects/arrays in render
+2. **Inline functions**: Creating functions in render
+3. **State updates**: Updating state that doesn't affect render
+4. **Parent re-renders**: Parent component re-rendering causes child re-renders
+
+### Optimization Strategies
+
+#### Strategy 1: React.memo
+
+**Rule**: Use `React.memo` for expensive components that receive stable props.
+
+**Example**:
+```typescript
+interface ItemProps {
+  id: string;
+  name: string;
+  onClick: (id: string) => void;
+}
+
+const Item = React.memo(function Item({ id, name, onClick }: ItemProps) {
+  return (
+    <div onClick={() => onClick(id)}>
+      {name}
+    </div>
+  );
+});
+
+function ItemList({ items, onItemClick }: Props) {
+  return (
+    <div>
+      {items.map(item => (
+        <Item
+          key={item.id}
+          id={item.id}
+          name={item.name}
+          onClick={onItemClick}
+        />
+      ))}
+    </div>
+  );
+}
+```
+
+#### Strategy 2: Memoize Props
+
+**Rule**: Memoize objects/arrays passed to memoized children.
+
+**Example**:
+```typescript
+interface ParentProps {
+  data: Data[];
+}
+
+const MemoizedChild = React.memo(ChildComponent);
+
+function Parent({ data }: ParentProps) {
+  // Memoize config object
+  const config = useMemo(() => ({
+    columns: data[0]?.columns || [],
+    sortable: true,
+  }), [data]);
+
+  // Memoize callback
+  const handleChange = useCallback((value: string) => {
+    console.log(value);
+  }, []);
+
+  return <MemoizedChild config={config} onChange={handleChange} />;
+}
+```
+
+#### Strategy 3: Split Components
+
+**Rule**: Split components to isolate re-renders.
+
+**Example**:
+```typescript
+// Bad: Entire component re-renders when count changes
+function Component({ items, count }: Props) {
+  return (
+    <div>
+      <ExpensiveList items={items} />
+      <Counter count={count} />
+    </div>
+  );
+}
+
+// Good: Split to isolate re-renders
+function Component({ items, count }: Props) {
+  return (
+    <div>
+      <ItemsList items={items} />
+      <Counter count={count} />
+    </div>
+  );
+}
+
+interface ItemsListProps {
+  items: Item[];
+}
+
+const ItemsList = React.memo(function ItemsList({ items }: ItemsListProps) {
+  return <ExpensiveList items={items} />;
+});
+```
+
+#### Strategy 4: State Colocation
+
+**Rule**: Keep state as close to where it's used as possible.
+
+**Example**:
+```typescript
+// Bad: State in parent causes all children to re-render
+function Parent() {
+  const [count, setCount] = useState(0);
+  return (
+    <div>
+      <ExpensiveChild1 />
+      <ExpensiveChild2 />
+      <Counter count={count} onIncrement={() => setCount(c => c + 1)} />
+    </div>
+  );
+}
+
+// Good: State colocated with component that uses it
+function Parent() {
+  return (
+    <div>
+      <ExpensiveChild1 />
+      <ExpensiveChild2 />
+      <Counter />
+    </div>
+  );
+}
+
+function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
+}
+```
+
+## CSS Performance Optimization
+
+### Browser Rendering Optimization
+
+**Rule**: Optimize CSS to minimize layout thrashing and repaints.
+
+#### Avoid Layout Thrashing
+
+**Bad**:
+```typescript
+// Forces layout recalculation
+function Component() {
+  const [width, setWidth] = useState(0);
+
+  useEffect(() => {
+    const element = ref.current;
+    if (element) {
+      const newWidth = element.offsetWidth; // Read: forces layout
+      setWidth(newWidth);
+      element.style.width = `${newWidth * 2}px`; // Write: forces layout
+    }
+  }, []);
+
+  return <div ref={ref}>Content</div>;
+}
+```
+
+**Good**:
+```typescript
+// Batch reads and writes
+function Component() {
+  const [width, setWidth] = useState(0);
+
+  useEffect(() => {
+    const element = ref.current;
+    if (element) {
+      // Batch all reads first
+      const newWidth = element.offsetWidth;
+      
+      // Then batch all writes
+      requestAnimationFrame(() => {
+        element.style.width = `${newWidth * 2}px`;
+        setWidth(newWidth);
+      });
+    }
+  }, []);
+
+  return <div ref={ref}>Content</div>;
+}
+```
+
+#### Use CSS Transforms Instead of Position Changes
+
+**Rule**: Prefer `transform` over `top`/`left` for animations.
+
+**Bad**:
+```css
+.animated {
+  position: absolute;
+  top: 0;
+  left: 0;
+  transition: top 0.3s, left 0.3s;
+}
+```
+
+**Good**:
+```css
+.animated {
+  position: absolute;
+  top: 0;
+  left: 0;
+  transform: translate(0, 0);
+  transition: transform 0.3s;
+}
+```
+
+#### Avoid Expensive CSS Properties
+
+**Rule**: Avoid properties that trigger layout recalculation.
+
+**Expensive Properties** (trigger layout):
+- `width`, `height`
+- `top`, `left`, `right`, `bottom`
+- `margin`, `padding`
+- `border-width`
+
+**Cheap Properties** (only trigger paint/composite):
+- `transform`
+- `opacity`
+- `filter`
+- `will-change`
+
+#### Use will-change Sparingly
+
+**Rule**: Use `will-change` only for elements that will animate.
+
+**Example**:
+```css
+.animated-element {
+  will-change: transform;
+  transition: transform 0.3s;
+}
+
+/* Remove will-change after animation */
+.animated-element.animation-complete {
+  will-change: auto;
+}
+```
+
+### TailwindCSS Performance
+
+**Rule**: Use Tailwind utilities efficiently.
+
+**Best Practices**:
+- Use utility classes instead of custom CSS when possible
+- Avoid deeply nested selectors
+- Use `twMerge` to merge conflicting classes efficiently
+
+**Example**:
+```typescript
+import { twMerge } from 'tailwind-merge';
+
+function Component({ className, variant }: Props) {
+  return (
+    <div
+      className={twMerge(
+        'p-4 rounded-lg',
+        variant === 'primary' && 'bg-blue-500 text-white',
+        variant === 'secondary' && 'bg-gray-200 text-gray-800',
+        className
+      )}
+    >
+      Content
+    </div>
+  );
+}
+```
+
+## Performance Measurement
+
+### React DevTools Profiler
+
+**Usage**:
+1. Open React DevTools
+2. Go to Profiler tab
+3. Click Record
+4. Interact with application
+5. Stop recording
+6. Analyze flamegraph and ranked chart
+
+### Performance Metrics
+
+**Key Metrics**:
+- **Render time**: Time spent rendering component
+- **Commit time**: Time spent committing changes to DOM
+- **Re-render frequency**: How often component re-renders
+
+### Optimization Checklist
+
+When optimizing performance:
+
+- [ ] Measured performance with React DevTools Profiler
+- [ ] Identified specific bottlenecks
+- [ ] Applied targeted optimizations
+- [ ] Verified improvements with measurements
+- [ ] `useMemo` used only for expensive computations
+- [ ] `useCallback` used only for memoized children or hook dependencies
+- [ ] `useEffect` dependencies complete and correct
+- [ ] Unnecessary re-renders eliminated
+- [ ] CSS optimized to avoid layout thrashing
+- [ ] Transform/opacity used for animations instead of position changes
+
+## Summary Checklist
+
+When optimizing performance, ensure:
+
+- [ ] Performance measured before optimization
+- [ ] `useMemo` used only when necessary (expensive computations)
+- [ ] `useCallback` used only when necessary (memoized children, hook deps)
+- [ ] `useEffect` dependencies complete
+- [ ] Re-renders optimized (React.memo, state colocation)
+- [ ] CSS optimized (avoid layout thrashing, use transforms)
+- [ ] Improvements verified with measurements
+
+## References
+
+- [React Performance Optimization](https://react.dev/learn/render-and-commit)
+- [Web.dev Performance](https://web.dev/performance/)
+- Project Coding Standards: `desktop-team-documentation/instructions/coding-conventions/frontend.md`