Cursor rule

1---
2description: Modern React + TypeScript component patterns — hooks, typed props, performance optimization, forms, and testing
3globs: **/*.tsx,**/*.ts,**/components/**/*.jsx
4alwaysApply: false
5---
6# React TypeScript Component Excellence
7 
8## Modern Component Architecture
9- **Functional Components**: Use React hooks for state and lifecycle management
10- **TypeScript Integration**: Comprehensive type safety with proper interface definitions
11- **Performance Optimization**: Implement useMemo, useCallback, and React.memo strategically
12- **Accessibility First**: Built-in ARIA support and keyboard navigation
13 
14## Component Structure Best Practices
15```typescript
16import React, { useState, useCallback, useMemo, ReactNode } from 'react'
17import { clsx } from 'clsx'
18 
19// ✅ Define comprehensive prop interfaces
20interface ButtonProps {
21  children: ReactNode
22  variant?: 'primary' | 'secondary' | 'outline' | 'ghost'
23  size?: 'sm' | 'md' | 'lg'
24  disabled?: boolean
25  loading?: boolean
26  onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void
27  type?: 'button' | 'submit' | 'reset'
28  className?: string
29  'data-testid'?: string
30}
31 
32// ✅ Modern functional component with comprehensive TypeScript
33export const Button: React.FC<ButtonProps> = ({
34  children,
35  variant = 'primary',
36  size = 'md',
37  disabled = false,
38  loading = false,
39  onClick,
40  type = 'button',
41  className,
42  'data-testid': testId,
43  ...rest
44}) => {
45  // ✅ Memoized class computation for performance
46  const buttonClasses = useMemo(() => clsx(
47    'btn',
48    `btn--${variant}`,
49    `btn--${size}`,
50    {
51      'btn--disabled': disabled,
52      'btn--loading': loading,
53    },
54    className
55  ), [variant, size, disabled, loading, className])
56 
57  // ✅ Optimized event handler
58  const handleClick = useCallback((event: React.MouseEvent<HTMLButtonElement>) => {
59    if (disabled || loading) {
60      event.preventDefault()
61      return
62    }
63    onClick?.(event)
64  }, [disabled, loading, onClick])
65 
66  return (
67    <button
68      type={type}
69      className={buttonClasses}
70      onClick={handleClick}
71      disabled={disabled || loading}
72      aria-disabled={disabled || loading}
73      aria-busy={loading}
74      data-testid={testId}
75      {...rest}
76    >
77      {loading && (
78        <span className="btn__spinner" aria-hidden="true">
79          <LoadingSpinner size="sm" />
80        </span>
81      )}
82      <span className={loading ? 'btn__content--loading' : 'btn__content'}>
83        {children}
84      </span>
85    </button>
86  )
87}
88```
89 
90## Advanced Hook Patterns
91```typescript
92import { useState, useEffect, useCallback, useRef } from 'react'
93 
94// ✅ Custom hook with comprehensive TypeScript
95interface UseApiOptions<T> {
96  immediate?: boolean
97  onSuccess?: (data: T) => void
98  onError?: (error: Error) => void
99}
100 
101interface UseApiReturn<T> {
102  data: T | null
103  loading: boolean
104  error: Error | null
105  execute: () => Promise<void>
106  reset: () => void
107}
108 
109export function useApi<T>(
110  apiCall: () => Promise<T>,
111  options: UseApiOptions<T> = {}
112): UseApiReturn<T> {
113  const { immediate = false, onSuccess, onError } = options
114  
115  const [data, setData] = useState<T | null>(null)
116  const [loading, setLoading] = useState(false)
117  const [error, setError] = useState<Error | null>(null)
118  const cancelRef = useRef<AbortController | null>(null)
119 
120  const execute = useCallback(async () => {
121    // Cancel previous request
122    if (cancelRef.current) {
123      cancelRef.current.abort()
124    }
125 
126    const controller = new AbortController()
127    cancelRef.current = controller
128 
129    try {
130      setLoading(true)
131      setError(null)
132      
133      const result = await apiCall()
134      
135      if (!controller.signal.aborted) {
136        setData(result)
137        onSuccess?.(result)
138      }
139    } catch (err) {
140      if (!controller.signal.aborted) {
141        const error = err instanceof Error ? err : new Error('Unknown error')
142        setError(error)
143        onError?.(error)
144      }
145    } finally {
146      if (!controller.signal.aborted) {
147        setLoading(false)
148      }
149    }
150  }, [apiCall, onSuccess, onError])
151 
152  const reset = useCallback(() => {
153    setData(null)
154    setError(null)
155    setLoading(false)
156    if (cancelRef.current) {
157      cancelRef.current.abort()
158    }
159  }, [])
160 
161  useEffect(() => {
162    if (immediate) {
163      execute()
164    }
165 
166    return () => {
167      if (cancelRef.current) {
168        cancelRef.current.abort()
169      }
170    }
171  }, [immediate, execute])
172 
173  return { data, loading, error, execute, reset }
174}
175```
176 
177## Form Handling Excellence
178```typescript
179import { useForm, Controller } from 'react-hook-form'
180import { zodResolver } from '@hookform/resolvers/zod'
181import { z } from 'zod'
182 
183// ✅ Comprehensive form validation schema
184const loginSchema = z.object({
185  email: z
186    .string()
187    .min(1, 'Email is required')
188    .email('Please enter a valid email address'),
189  password: z
190    .string()
191    .min(8, 'Password must be at least 8 characters')
192    .regex(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/, 
193      'Password must contain at least one uppercase letter, one lowercase letter, and one number'),
194  rememberMe: z.boolean().default(false),
195})
196 
197type LoginFormData = z.infer<typeof loginSchema>
198 
199interface LoginFormProps {
200  onSubmit: (data: LoginFormData) => Promise<void>
201  loading?: boolean
202}
203 
204export const LoginForm: React.FC<LoginFormProps> = ({ 
205  onSubmit, 
206  loading = false 
207}) => {
208  const {
209    control,
210    handleSubmit,
211    formState: { errors, isValid, isSubmitting },
212    setError,
213    reset,
214  } = useForm<LoginFormData>({
215    resolver: zodResolver(loginSchema),
216    mode: 'onChange',
217    defaultValues: {
218      email: '',
219      password: '',
220      rememberMe: false,
221    },
222  })
223 
224  const handleFormSubmit = useCallback(async (data: LoginFormData) => {
225    try {
226      await onSubmit(data)
227      reset()
228    } catch (error) {
229      // Handle server validation errors
230      if (error instanceof ValidationError) {
231        error.fieldErrors.forEach(({ field, message }) => {
232          setError(field as keyof LoginFormData, { message })
233        })
234      } else {
235        setError('root', { 
236          message: 'An unexpected error occurred. Please try again.' 
237        })
238      }
239    }
240  }, [onSubmit, reset, setError])
241 
242  return (
243    <form onSubmit={handleSubmit(handleFormSubmit)} className="login-form">
244      <div className="form-group">
245        <Controller
246          name="email"
247          control={control}
248          render={({ field, fieldState }) => (
249            <Input
250              {...field}
251              type="email"
252              label="Email Address"
253              placeholder="Enter your email"
254              error={fieldState.error?.message}
255              required
256              data-testid="email-input"
257            />
258          )}
259        />
260      </div>
261 
262      <div className="form-group">
263        <Controller
264          name="password"
265          control={control}
266          render={({ field, fieldState }) => (
267            <Input
268              {...field}
269              type="password"
270              label="Password"
271              placeholder="Enter your password"
272              error={fieldState.error?.message}
273              required
274              data-testid="password-input"
275            />
276          )}
277        />
278      </div>
279 
280      <div className="form-group">
281        <Controller
282          name="rememberMe"
283          control={control}
284          render={({ field }) => (
285            <Checkbox
286              checked={field.value}
287              onChange={field.onChange}
288              label="Remember me"
289              data-testid="remember-me-checkbox"
290            />
291          )}
292        />
293      </div>
294 
295      {errors.root && (
296        <div className="form-error" role="alert">
297          {errors.root.message}
298        </div>
299      )}
300 
301      <Button
302        type="submit"
303        variant="primary"
304        size="lg"
305        disabled={!isValid || isSubmitting || loading}
306        loading={isSubmitting || loading}
307        className="w-full"
308        data-testid="submit-button"
309      >
310        {isSubmitting || loading ? 'Signing in...' : 'Sign In'}
311      </Button>
312    </form>
313  )
314}
315```
316 
317## State Management Patterns
318```typescript
319import { createContext, useContext, useReducer, ReactNode } from 'react'
320 
321// ✅ Comprehensive state management with useReducer
322interface User {
323  id: string
324  email: string
325  name: string
326  role: 'admin' | 'user' | 'guest'
327}
328 
329interface AuthState {
330  user: User | null
331  isAuthenticated: boolean
332  loading: boolean
333  error: string | null
334}
335 
336type AuthAction =
337  | { type: 'AUTH_START' }
338  | { type: 'AUTH_SUCCESS'; payload: User }
339  | { type: 'AUTH_ERROR'; payload: string }
340  | { type: 'LOGOUT' }
341  | { type: 'CLEAR_ERROR' }
342 
343const initialState: AuthState = {
344  user: null,
345  isAuthenticated: false,
346  loading: false,
347  error: null,
348}
349 
350function authReducer(state: AuthState, action: AuthAction): AuthState {
351  switch (action.type) {
352    case 'AUTH_START':
353      return {
354        ...state,
355        loading: true,
356        error: null,
357      }
358    case 'AUTH_SUCCESS':
359      return {
360        ...state,
361        user: action.payload,
362        isAuthenticated: true,
363        loading: false,
364        error: null,
365      }
366    case 'AUTH_ERROR':
367      return {
368        ...state,
369        user: null,
370        isAuthenticated: false,
371        loading: false,
372        error: action.payload,
373      }
374    case 'LOGOUT':
375      return {
376        ...state,
377        user: null,
378        isAuthenticated: false,
379        loading: false,
380        error: null,
381      }
382    case 'CLEAR_ERROR':
383      return {
384        ...state,
385        error: null,
386      }
387    default:
388      return state
389  }
390}
391 
392interface AuthContextType extends AuthState {
393  login: (email: string, password: string) => Promise<void>
394  logout: () => void
395  clearError: () => void
396}
397 
398const AuthContext = createContext<AuthContextType | undefined>(undefined)
399 
400export const useAuth = (): AuthContextType => {
401  const context = useContext(AuthContext)
402  if (!context) {
403    throw new Error('useAuth must be used within an AuthProvider')
404  }
405  return context
406}
407 
408interface AuthProviderProps {
409  children: ReactNode
410}
411 
412export const AuthProvider: React.FC<AuthProviderProps> = ({ children }) => {
413  const [state, dispatch] = useReducer(authReducer, initialState)
414 
415  const login = useCallback(async (email: string, password: string) => {
416    dispatch({ type: 'AUTH_START' })
417    
418    try {
419      const response = await authApi.login({ email, password })
420      dispatch({ type: 'AUTH_SUCCESS', payload: response.user })
421    } catch (error) {
422      const message = error instanceof Error ? error.message : 'Login failed'
423      dispatch({ type: 'AUTH_ERROR', payload: message })
424      throw error
425    }
426  }, [])
427 
428  const logout = useCallback(() => {
429    authApi.logout()
430    dispatch({ type: 'LOGOUT' })
431  }, [])
432 
433  const clearError = useCallback(() => {
434    dispatch({ type: 'CLEAR_ERROR' })
435  }, [])
436 
437  const value = useMemo(() => ({
438    ...state,
439    login,
440    logout,
441    clearError,
442  }), [state, login, logout, clearError])
443 
444  return (
445    <AuthContext.Provider value={value}>
446      {children}
447    </AuthContext.Provider>
448  )
449}
450```
451 
452## Testing Integration
453```typescript
454import { render, screen, fireEvent, waitFor } from '@testing-library/react'
455import userEvent from '@testing-library/user-event'
456import { vi } from 'vitest'
457 
458// ✅ Comprehensive component testing
459describe('LoginForm', () => {
460  const mockOnSubmit = vi.fn()
461 
462  beforeEach(() => {
463    mockOnSubmit.mockClear()
464  })
465 
466  it('should render all form elements correctly', () => {
467    render(<LoginForm onSubmit={mockOnSubmit} />)
468 
469    expect(screen.getByTestId('email-input')).toBeInTheDocument()
470    expect(screen.getByTestId('password-input')).toBeInTheDocument()
471    expect(screen.getByTestId('remember-me-checkbox')).toBeInTheDocument()
472    expect(screen.getByTestId('submit-button')).toBeInTheDocument()
473  })
474 
475  it('should validate email format', async () => {
476    const user = userEvent.setup()
477    render(<LoginForm onSubmit={mockOnSubmit} />)
478 
479    const emailInput = screen.getByTestId('email-input')
480    await user.type(emailInput, 'invalid-email')
481    await user.tab() // Trigger blur event
482 
483    await waitFor(() => {
484      expect(screen.getByText('Please enter a valid email address')).toBeInTheDocument()
485    })
486  })
487 
488  it('should submit form with valid data', async () => {
489    const user = userEvent.setup()
490    mockOnSubmit.mockResolvedValueOnce(undefined)
491 
492    render(<LoginForm onSubmit={mockOnSubmit} />)
493 
494    await user.type(screen.getByTestId('email-input'), 'test@example.com')
495    await user.type(screen.getByTestId('password-input'), 'Password123')
496    await user.click(screen.getByTestId('submit-button'))
497 
498    await waitFor(() => {
499      expect(mockOnSubmit).toHaveBeenCalledWith({
500        email: 'test@example.com',
501        password: 'Password123',
502        rememberMe: false,
503      })
504    })
505  })
506 
507  it('should handle server errors gracefully', async () => {
508    const user = userEvent.setup()
509    mockOnSubmit.mockRejectedValueOnce(new Error('Invalid credentials'))
510 
511    render(<LoginForm onSubmit={mockOnSubmit} />)
512 
513    await user.type(screen.getByTestId('email-input'), 'test@example.com')
514    await user.type(screen.getByTestId('password-input'), 'WrongPassword')
515    await user.click(screen.getByTestId('submit-button'))
516 
517    await waitFor(() => {
518      expect(screen.getByText('An unexpected error occurred. Please try again.')).toBeInTheDocument()
519    })
520  })
521})
522```
523