Frontend Development Guide for Next.js #

// components/ui/Card.tsx

// Define the shape of props(parameters) that this component accepts
interface CardProps {
  title: string                  // Required: The card's title
  children: React.ReactNode      // Required: The content inside the card
  className?: string            // Optional: Additional CSS classes
}

// Card component that renders a styled container with a title and content
export function Card({ 
  title,
  children,
  className = ''  // Default to empty string if no className provided
}: CardProps) {
  return (
    // Main container with base styles and optional custom classes
    <div className={`
      rounded-lg    /* Rounded corners */
      shadow-md    /* Subtle shadow for depth */
      p-4         /* Padding on all sides */
      ${className} /* Custom classes passed as prop */
    `}>
      {/* Title section with consistent styling */}
      <h2 className="text-xl font-bold mb-2">{title}</h2>
      
      {/* Content section that renders the children */}
      <div>{children}</div>
    </div>
  )
}

// app/posts/page.tsx

import { Suspense } from 'react'
import { PostList } from '@/components/features/PostList'
import { LoadingSpinner } from '@/components/ui/LoadingSpinner'

// Posts page component - demonstrates Next.js 13+ app directory structure
export default function PostsPage() {
  return (
    // Container with responsive padding and max-width
    <div className="
      container    /* Set max-width and center content */
      mx-auto     /* Center horizontally */
      px-4        /* Horizontal padding */
      py-8        /* Vertical padding */
    ">
      {/* Page title with consistent styling */}
      <h1 className="
        text-3xl    /* Large text size */
        font-bold   /* Bold weight */
        mb-6        /* Bottom margin */
      ">
        Posts
      </h1>

      {/* 
        Suspense boundary for loading state
        - Shows LoadingSpinner while PostList is loading
        - Part of React's concurrent features
      */}
      <Suspense fallback={<LoadingSpinner />}>
        <PostList />
      </Suspense>
    </div>
  )
}

// contexts/ThemeContext.tsx

import { createContext, useContext, useState } from 'react'

// Define the shape of our context state and methods
interface ThemeContextType {
  theme: 'light' | 'dark'      // Current theme
  toggleTheme: () => void      // Function to switch themes
}

// Create the context with undefined as initial value
// We use undefined initially so TypeScript can warn us if we forget the Provider
const ThemeContext = createContext<ThemeContextType | undefined>(undefined)

// Provider component that wraps our app and makes theme available to any child component
export function ThemeProvider({ 
  children 
}: { 
  children: React.ReactNode   // Components that will have access to the theme
}) {
  // Manage the theme state
  const [theme, setTheme] = useState<'light' | 'dark'>('light')

  // Function to toggle between light and dark themes
  const toggleTheme = () => setTheme(prev => prev === 'light' ? 'dark' : 'light')
  
  // Provide the theme context to children
  return (
    <ThemeContext.Provider 
      value={{
        theme,      // Current theme state
        toggleTheme // Function to change theme
      }}
    >
      {children}
    </ThemeContext.Provider>
  )
}

// Custom hook to use the theme context
export function useTheme() {
  // Get the context value
  const context = useContext(ThemeContext)
  
  // Throw an error if used outside of provider
  if (context === undefined) {
    throw new Error('useTheme must be used within a ThemeProvider')
  }
  
  return context
}

/* Usage example:
function MyComponent() {
  const { theme, toggleTheme } = useTheme()
  return (
    <button onClick={toggleTheme}>
      Current theme: {theme}
    </button>
  )
}
*/

// hooks/useForm.ts

import { useState, ChangeEvent, FormEvent } from 'react'

// Define the options that our hook accepts
interface UseFormOptions<T> {
  initialValues: T                                    // Initial form values
  onSubmit: (values: T) => Promise<void>             // Submit handler
  validate?: (values: T) => Partial<Record<keyof T, string>>  // Optional validation
}

// Custom hook for form handling with TypeScript generics
export function useForm<T extends Record<string, any>>({
  initialValues,
  onSubmit,
  validate
}: UseFormOptions<T>) {
  // State management
  const [values, setValues] = useState<T>(initialValues)          // Form values
  const [errors, setErrors] = useState<Partial<Record<keyof T, string>>>({})  // Validation errors
  const [submitting, setSubmitting] = useState(false)             // Submit state

  // Handle input changes
  const handleChange = (e: ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => {
    const { name, value } = e.target
    setValues(prev => ({
      ...prev,
      [name]: value
    }))
  }

  // Handle form submission
  const handleSubmit = async (e: FormEvent) => {
    e.preventDefault()
    
    // Validate if validation function is provided
    if (validate) {
      const validationErrors = validate(values)
      if (Object.keys(validationErrors).length > 0) {
        setErrors(validationErrors)
        return
      }
    }

    // Submit the form
    setSubmitting(true)
    try {
      await onSubmit(values)
    } finally {
      setSubmitting(false)
    }
  }

  return { 
    values,       // Current form values
    errors,       // Validation errors
    submitting,   // Whether form is submitting
    handleChange, // Input change handler
    handleSubmit  // Form submit handler
  }
}

/* Usage example:
const form = useForm({
  initialValues: { email: '', password: '' },
  validate: (values) => {
    const errors: Record<string, string> = {}
    if (!values.email) errors.email = 'Required'
    if (!values.password) errors.password = 'Required'
    return errors
  },
  onSubmit: async (values) => {
    await submitToAPI(values)
  }
})
*/