<!--
Author: Simon-Pierre Boucher
Contact: contact@spboucher.ai
-->

# Patterns — Building React Components

## Contents
- Props API: variant unions and discriminated props
- Composition: compound components
- State placement: the decision table
- Controlled vs uncontrolled inputs
- Custom hooks
- Measured memoization
- Gotchas

## Props API: variant unions and discriminated props

```tsx
type ButtonProps = {
  variant?: 'primary' | 'danger' | 'ghost';   // one axis, one prop
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;                          // true independent boolean is fine
  onClick: () => void;
  children: React.ReactNode;
};

export function Button({ variant = 'primary', size = 'md', ...rest }: ButtonProps) { /* … */ }
```

Discriminated union when props only make sense together:

```tsx
type AlertProps =
  | { kind: 'info'; message: string }
  | { kind: 'error'; message: string; retry: () => void }; // retry exists only for errors
```

## Composition: compound components

```tsx
export function Card({ children }: { children: React.ReactNode }) {
  return <section className="card">{children}</section>;
}
Card.Header = function CardHeader({ children }: { children: React.ReactNode }) {
  return <header className="card-header">{children}</header>;
};
Card.Body = function CardBody({ children }: { children: React.ReactNode }) {
  return <div className="card-body">{children}</div>;
};

// Usage — caller controls content, Card controls chrome:
<Card>
  <Card.Header><h2>Invoices</h2></Card.Header>
  <Card.Body><InvoiceTable rows={rows} /></Card.Body>
</Card>
```

Escape hatch: if slots must be validated/reordered, accept named element props
(`header={<h2>…</h2>}`) — still elements, not strings-plus-config.

## State placement: the decision table

| The value is… | Home | Tool |
|---|---|---|
| Fetched from an API | Query cache | TanStack Query / SWR |
| Shareable via link (filters, tab, page) | URL | `useSearchParams` |
| Form input mid-edit | Local component | `useState` / form library |
| Theme, auth, locale (rarely changes, read widely) | Context | `createContext` |
| Everything else | Lowest component that uses it | `useState` |

## Controlled vs uncontrolled inputs

```tsx
// Controlled — other UI reacts per keystroke
const [query, setQuery] = useState('');
<input value={query} onChange={(e) => setQuery(e.target.value)} />
<Results filter={query} />

// Uncontrolled — value only needed on submit
<form onSubmit={(e) => {
  e.preventDefault();
  const data = new FormData(e.currentTarget);
  save(data.get('email'));
}}>
  <input name="email" defaultValue={user.email} />
</form>
```

## Custom hooks

```tsx
// Reusable logic = hook. Name starts with `use`, returns plain values.
function useDebouncedValue<T>(value: T, delayMs = 300) {
  const [debounced, setDebounced] = useState(value);
  useEffect(() => {
    const id = setTimeout(() => setDebounced(value), delayMs);
    return () => clearTimeout(id);
  }, [value, delayMs]);
  return debounced;
}

const debouncedQuery = useDebouncedValue(query); // any component, same behavior
```

## Measured memoization

```tsx
// 1. Measure first: React DevTools Profiler → record → find components
//    re-rendering with unchanged props AND non-trivial render cost.
// 2. Then, and only then:
const Row = React.memo(function Row({ item }: { item: Item }) { /* … */ });
// Parent must keep prop identities stable for memo to work:
const onSelect = useCallback((id: string) => setSelected(id), []);
// Comment the reason so the next reader knows it's load-bearing:
// memo: 5k rows re-rendered on every keystroke before this (Profiler 2026-08).
```

## Gotchas

- **`useEffect` for derivation** is the top React bug source — if the effect only
  calls `setState` from other state/props, delete it and compute during render.
- **Index as `key`** breaks reordering/deletion — use a stable id; index is
  acceptable only for static, never-reordered lists.
- **Object/array literals in JSX props** (`style={{…}}`, `options={[…]}`) defeat
  `React.memo` children — hoist or memoize them only where memo is in play.
- **Context triggers re-render of every consumer** on any value change — split
  contexts (state vs dispatch) or keep fast-changing values out of context.
- **`useCallback` without a memoized child** is pure overhead — it saves nothing.
- **Stale closure in intervals/subscriptions**: include deps or use a ref;
  an empty dep array freezes captured state at mount time.
- **`'use client'` at the page root** opts the whole tree out of server
  rendering — place it at the interactive leaf component instead.