git:20260202.b236384 to git:20260316.53fded1

+ > **Quick Guide:** Tiered components (Primitives -> Components -> Patterns -> Templates). React 19: pass `ref` as a prop directly (no `forwardRef` needed). Expose `className` prop for styling flexibility. Use `useActionState` for forms, `useOptimistic` for instant feedback, `use()` for conditional promise/context reading. Ref callbacks can return cleanup functions.

+ **(You MUST call `useFormStatus` from a child component inside `<form>`, NOT in the component that renders the form)**

+

+ **Auto-detection:** React 19, components, hooks, use(), useActionState, useFormStatus, useOptimistic, Actions, ref as prop, ref cleanup, forwardRef migration, component variants, error boundary

+ - Building React components with type-safe props

+ - Migrating from forwardRef to React 19 ref-as-prop

+ - Handling form submissions with React 19 Actions API

+ - Creating custom hooks for reusable logic

+ - Implementing error boundaries with retry

+ - Static content without interactivity

+ **Key patterns covered:**

+ - Component architecture tiers and variant props

+ - React 19 ref as prop (replaces forwardRef)

+ - React 19 hooks: `use()`, `useActionState`, `useFormStatus`, `useOptimistic`

+ - Ref callback cleanup functions

+ - Error boundaries with retry and custom fallbacks

+ - Custom hooks (pagination, debounce, localStorage)

+ - Event handler naming conventions

+ React components follow a tiered architecture from low-level primitives to high-level templates. Components should be composable, type-safe, and expose necessary customization points (`className`, refs). Use variant abstractions only when components have multiple variant dimensions to avoid over-engineering. React is styling-agnostic -- apply styles via the `className` prop.

+ **React 19 Changes:** `forwardRef` is deprecated -- pass `ref` as a regular prop directly. New hooks (`use()`, `useActionState`, `useFormStatus`, `useOptimistic`) simplify data fetching and form handling with the Actions API. Ref callbacks can return cleanup functions, eliminating the need for separate `useEffect` cleanup.

+ Components are organized in a tiered hierarchy:

+ // React 19: ref as a regular prop, no forwardRef needed

+ variant?: "default" | "ghost" | "link";

+ size?: "default" | "large" | "icon";

+ export function Button({ variant = "default", size = "default", className, ref, ...props }: ButtonProps) {

+ return <button className={className} data-variant={variant} data-size={size} ref={ref} {...props} />;

+ **Why good:** ref as regular prop eliminates forwardRef boilerplate, className enables external styling, data-attributes enable CSS selectors for variants

+ See [examples/core.md](examples/core.md) for complete component examples with good/bad comparisons.

+ Components with 2+ visual dimensions (variant, size) should expose type-safe variant props via TypeScript unions. Use `data-*` attributes so any styling solution can target them.

+ export function Alert({ variant = "info", className, ref, ...props }: AlertProps) {

+ return <div ref={ref} className={className} data-variant={variant} {...props} />;

+ **When not to use:** Components with a single visual style -- skip variant abstraction.

+ See [examples/core.md](examples/core.md) for variant props with good/bad examples.

+ ### Pattern 3: Event Handler Naming

+ - `handle` prefix for internal handlers: `handleSubmit`, `handleNameChange`

+ - `on` prefix for callback props: `onClick`, `onSubmit`

+ const handleSubmit = (e: FormEvent<HTMLFormElement>) => {

+ e.preventDefault();

+ };

+ const handleNameChange = (e: ChangeEvent<HTMLInputElement>) => {

+ setName(e.target.value);

+ };

+ See [examples/core.md](examples/core.md) for full event handler examples.

+ ### Pattern 4: Custom Hooks

+ - `useLocalStorage` - Type-safe localStorage persistence with SSR safety

+ See [examples/hooks.md](examples/hooks.md) for complete implementations.

+ ### Pattern 5: Error Boundaries with Retry

+ Error boundaries catch render errors and provide retry capability. Place them around feature sections, not just the root.

+ // Key interface -- accepts custom fallback and error callback

+ **Limitation:** Error boundaries do not catch event handler errors, async errors, or SSR errors -- use try/catch for those.

+ See [examples/error-boundaries.md](examples/error-boundaries.md) for full implementation.

+ ### Pattern 6: useActionState for Form Submissions

+ Use `useActionState` for form submissions with automatic pending state and error handling. Replaces manual `useState` for loading/error.

+ await saveProfile({ name: formData.get("name") as string });

+ return null;

+ } catch {

+ return "Failed to save profile";

+ **Why good:** hook manages pending and error state automatically, form action works with progressive enhancement, no manual useState for loading/error

+ See [examples/react-19-hooks.md](examples/react-19-hooks.md) for extended examples with success state.

+

+ ### Pattern 7: useFormStatus for Submit Buttons

+ `useFormStatus` reads parent form's pending state without prop drilling. **Must** be called from a child component inside the `<form>`.

+ **Gotcha:** Calling `useFormStatus` in the component that renders `<form>` returns `pending: false` always -- it must be a descendant component.

+ See [examples/react-19-hooks.md](examples/react-19-hooks.md) for reusable submit button patterns.

+ ### Pattern 8: useOptimistic for Instant UI Feedback

+ Show immediate UI updates while async operations complete. State automatically reverts if the request fails.

+ import { useOptimistic, startTransition } from "react";

+ const [optimisticItems, addOptimistic] = useOptimistic(

+ items,

+ (state, update: Item) => [...state, { ...update, pending: true }],

+ );

+ // In handler:

+ addOptimistic(newItem);

+ startTransition(async () => {

+ await saveItem(newItem);

+ });

+ See [examples/react-19-hooks.md](examples/react-19-hooks.md) for todo list and chat examples.

+ ### Pattern 9: use() Hook for Promises and Context

+ `use()` reads promises and context conditionally in render -- unlike `useContext`, it can be called after early returns.

+ const comments = use(commentsPromise); // Suspends until resolved

+ return <ul>{comments.map((c) => <li key={c.id}>{c.text}</li>)}</ul>;

+ // Wrap in Suspense boundary

+ <Suspense fallback={<p>Loading...</p>}>

+ <Comments commentsPromise={fetchComments()} />

+ </Suspense>

+ **Gotcha:** `use()` cannot be called in try-catch blocks -- use Error Boundaries for rejected promise handling.

+ See [examples/react-19-hooks.md](examples/react-19-hooks.md) for conditional context reading.

+ ### Pattern 10: Ref Callback Cleanup Functions

+ React 19 ref callbacks can return cleanup functions, replacing the need for separate `useEffect` cleanup.

+ return (

+ <video

+ ref={(video) => {

+ if (!video) return;

+ video.play();

+ return () => {

+ video.pause();

+ video.currentTime = 0;

+ };

+ }}

+ src={src}

+ />

+ );

+ **Why good:** cleanup runs automatically on unmount, no separate useEffect needed, simpler than useRef + useEffect combination

+ **Note:** With ref cleanup functions, TypeScript rejects non-null/undefined return values from ref callbacks. The callback is no longer called with `null` on unmount -- the cleanup function handles that.

+

+ See [examples/react-19-hooks.md](examples/react-19-hooks.md) for IntersectionObserver cleanup example.

+

+ **Detailed Resources:**

+ - [examples/core.md](examples/core.md) - Component architecture, variants, event handlers

+ - [examples/hooks.md](examples/hooks.md) - usePagination, useDebounce, useLocalStorage

+ - [examples/react-19-hooks.md](examples/react-19-hooks.md) - useActionState, useFormStatus, useOptimistic, use(), ref cleanup

+ - [examples/error-boundaries.md](examples/error-boundaries.md) - Error boundary implementation and recovery

+ - [reference.md](reference.md) - Decision frameworks, anti-patterns, checklists

+ ---

+ <red_flags>

+ ## RED FLAGS

+ **High Priority Issues:**

+ - Using `forwardRef` in React 19 -- deprecated, pass `ref` as a regular prop

+ - Calling `useFormStatus` in the component that renders `<form>` -- will always return `pending: false`

+ - Using `useState` for form loading/error when `useActionState` exists -- unnecessary boilerplate

+ - Not exposing `className` prop on reusable components -- prevents external styling

+ - Calling `use()` inside try-catch blocks -- use Error Boundaries instead

+ **Medium Priority Issues:**

+ - Adding variant abstractions for components without multiple variant dimensions

+ - Using `useCallback` on every handler regardless of child memoization (premature optimization)

+ - Wrapping ref callbacks in `useCallback` when the React Compiler handles memoization automatically

+ - Generic event handler names (`click`, `change`) instead of descriptive names (`handleNameChange`)

+

+ **Gotchas & Edge Cases:**

+

+ - Ref cleanup functions: TypeScript rejects non-null/undefined returns from ref callbacks -- use the cleanup pattern explicitly

+ - `useOptimistic` state reverts automatically on failure -- no manual rollback needed

+ - `use()` can be called conditionally (after early returns), unlike `useContext`

+ - Error boundaries do not catch event handler errors, async errors, or SSR errors

+ - `useCallback` without memoized children adds overhead without benefit

+ - SSR requires `typeof window !== "undefined"` before accessing browser APIs

+

+ </red_flags>

+

+ **(You MUST call `useFormStatus` from a child component inside `<form>`, NOT in the component that renders the form)**

+

+ **Failure to follow these rules will break component composition, form state management, and styling flexibility.**