component-patterns

# Component Patterns — React/Next.js Component Design Patterns A reference for component patterns, state management strategies, and project structure that the frontend-dev agent uses during frontend development. ## Target Agent `frontend-dev` — Applies this skill's patterns directly to component design and state management. ## Component Design Patterns ### 1. Compound Components A pattern where parent and child share implicit state. **Suited for**: Tab, Accordion, Dropdown, Select, and other composite UI **Structure**: `<Select>` + `<Select.Trigger>` + `<Select.Option>` **Key Concept**: State sharing via Context, flexible composition through children ### 2. Render Props / Children as Function Delegates rendering logic externally. **Suited for**: Data fetching wrappers, mouse/scroll tracking **Structure**: `<DataLoader render={(data) => <UI data={data} />} />` **Note**: Prefer Hook pattern when it can replace this ### 3. Custom Hooks (Extraction Pattern) Extracts state logic into reusable Hooks. **Suited for**: Form management, API calls, localStorage, debounce **Naming**: `use` prefix required — `useForm`, `useDebounce`, `useAuth` ### 4. Container/Presentational Separation Separates data logic (Container) from UI presentation (Presentational). **Suited for**: Large-scale apps, when testability is needed **Container**: Data fetch, state management, event handlers **Presentational**: Renders only from props, functionally pure ### 5. Higher-Order Component (HOC) Wraps a component to add functionality. **Suited for**: Auth guards, layout wrappers, error boundaries **Naming**: `with` prefix — `withAuth`, `withLayout` **Note**: Prefer Hook/Context when they can replace this ### 6. Headless Component Provides behavior/state without UI. **Suited for**: Sharing logic independent of design system **Examples**: headless `useCombobox`, `useDialog`, `useTable` ## State Management Strategy Selection Guide | State Type | Recommended Tool | Rationale | |-----------|-----------------|-----------| | **UI Local State** | useState, useReducer | Component-internal | | **Server State** | React Query (TanStack Query) | Caching, refetch, optimistic updates | | **Global Client State** | Zustand | Concise, minimal boilerplate | | **Complex Global State** | Zustand + Immer | Immutability convenience | | **URL State** | nuqs / useSearchParams | Filters, pagination | | **Form State** | React Hook Form + Zod | Integrated validation | | **Theme/Language** | Context + Provider | Low change frequency | ### State Placement Decision Flow ``` Should this state be restorable from URL? → URL state Is it server data? → React Query Is it shared across multiple components? → Zustand Is it internal to one component? → useState Does it have complex transition logic? → useReducer ``` ## Next.js App Router Folder Structure ### Recommended Structure (Feature-Based) ``` src/ ├── app/ # Next.js App Router │ ├── (auth)/ # Auth-related route group │ │ ├── login/page.tsx │ │ └── register/page.tsx │ ├── (main)/ # Main route group │ │ ├── dashboard/page.tsx │ │ └── settings/page.tsx │ ├── api/ # API Routes │ │ └── [...]/route.ts │ ├── layout.tsx # Root layout │ └── page.tsx # Home ├── components/ │ ├── ui/ # General UI (Button, Input, Modal) │ └── features/ # Feature-specific components │ ├── auth/ │ └── dashboard/ ├── hooks/ # Custom Hooks ├── lib/ # Utilities, config │ ├── api.ts # API client │ ├── auth.ts # Auth utilities │ └── utils.ts ├── stores/ # Zustand stores ├── types/ # TypeScript types └── styles/ # Global styles ``` ## Component File Conventions | Item | Rule | |------|------| | File Name | PascalCase: `UserProfile.tsx` | | Directory | kebab-case: `user-profile/` | | Index | Re-export via `index.ts` | | Test | `UserProfile.test.tsx` in same directory | | Story | `UserProfile.stories.tsx` in same directory | | Types | Same file or separate `types.ts` | ## Performance Optimization Patterns | Pattern | When | Tool | |---------|------|------| | **Memoization** | Expensive computation, frequent re-renders | `useMemo`, `React.memo` | | **Lazy Loading** | Initial bundle size | `React.lazy`, `next/dynamic` | | **Virtualization** | 1000+ item lists | `@tanstack/react-virtual` | | **Image Optimization** | Image loading | `next/image` | | **Code Splitting** | Per-route splitting | App Router automatic | | **Optimistic Updates** | Immediate feedback | React Query `onMutate` | | **Debounce** | Search, input | `useDeferredValue` or custom hook | ## Error Handling Patterns ### Hierarchical Error Boundaries ``` RootErrorBoundary (global) └── LayoutErrorBoundary (per section) └── ComponentErrorFallback (individual) ``` ### API Error Handling | HTTP Status | Client Handling | |------------|----------------| | 401 | Auto logout + redirect | | 403 | Unauthorized UI | | 404 | Not Found page | | 422 | Per-field form error display | | 429 | Retry + wait notice | | 500 | Generic error UI + retry button | ## Accessibility (a11y) Checklist - [ ] Alt text on all images - [ ] Keyboard navigation (Tab, Enter, Escape) - [ ] ARIA labels (aria-label, role) - [ ] Color contrast 4.5:1 or above - [ ] Visible focus indicator - [ ] Screen reader testing - [ ] Semantic HTML (button, nav, main, section)