Intermediate

import { useReducer } from 'react';
 
// => Define action types as discriminated union
// => Ensures type safety for all actions
type Action =
  | { type: 'increment'; payload: number }
  | { type: 'decrement'; payload: number }
  | { type: 'reset' }
  | { type: 'set'; payload: number };
 
// => State interface
interface CounterState {
  count: number;                             // => Current count value
  history: number[];                         // => Array of previous values
}
 
// => Reducer function: (state, action) => newState
// => Pure function - no side effects
function counterReducer(state: CounterState, action: Action): CounterState {
  switch (action.type) {
    case 'increment':
      // => Create new state with incremented count
      return {
        count: state.count + action.payload,
        history: [...state.history, state.count + action.payload]
        // => Spread existing history, append new count
      };
 
    case 'decrement':
      return {
        count: state.count - action.payload,
        history: [...state.history, state.count - action.payload]
      };
 
    case 'reset':
      // => Reset to initial state
      return {
        count: 0,
        history: [0]
        // => Start fresh history with 0
      };
 
    case 'set':
      // => Set to specific value
      return {
        count: action.payload,
        history: [...state.history, action.payload]
      };
 
    default:
      // => TypeScript ensures exhaustive checking
      // => All action types must be handled
      return state;
  }
}
 
function DonationCounter() {
  // => useReducer(reducer, initialState) returns [state, dispatch]
  const [state, dispatch] = useReducer(counterReducer, {
    count: 0,                                // => Initial count is 0
    history: [0]                             // => History starts with [0]
  });
  // => dispatch triggers state transition via reducer
  // => TypeScript validates action types
 
  // => Dispatch actions with type and optional payload
  const handleDonate10 = () => {
    dispatch({ type: 'increment', payload: 10 });
    // => Calls reducer with current state and action
    // => Reducer returns new state
    // => Component re-renders with updated state
  };
 
  const handleUndo = () => {
    if (state.history.length > 1) {
      // => Get previous value from history
      const previousValue = state.history[state.history.length - 2];
      dispatch({ type: 'set', payload: previousValue });
    }
  };
 
  return (
    <div>
    {/* => Container div for layout grouping */}
      <h2>Total Donations: ${state.count}</h2>
      {/* => Displays current count from state */}
 
      <div>
      {/* => Container div for layout grouping */}
        <button onClick={handleDonate10}>Donate \$10</button>
        {/* => Button "Donate \$10" - triggers onClick handler */}
        <button onClick={() => dispatch({ type: 'increment', payload: 25 })}>
        {/* => Button: triggers click handler */}
          Donate \$25
        </button>
        {/* => Inline dispatch with literal action object */}
 
        <button onClick={() => dispatch({ type: 'decrement', payload: 5 })}>
        {/* => Button: triggers click handler */}
          Refund \$5
        </button>
 
        <button onClick={handleUndo}>
        {/* => Button: triggers click handler */}
          Undo Last
        </button>
 
        <button onClick={() => dispatch({ type: 'reset' })}>
        {/* => Button: triggers click handler */}
          Reset
        </button>
      </div>
 
      <div>
      {/* => Container div for layout grouping */}
        <h3>History</h3>
        {/* => H3: "History" section heading */}
        <ul>
        {/* => Unordered list of items */}
          {state.history.map((value, index) => (
            <li key={index}>
              {/* => Using index as key (OK since history only appends) */}
              Step {index}: ${value}
            </li>
          ))}
        </ul>
      </div>
    </div>
  );
}
 
export default DonationCounter;
 

import { useState, useCallback, memo } from 'react';
 
// => Memoized child component using React.memo
// => Only re-renders when props change by reference
interface TodoItemProps {
  todo: { id: number; text: string };
  onDelete: (id: number) => void;          // => Callback prop
}
 
const TodoItem = memo(({ todo, onDelete }: TodoItemProps) => {
  console.log('TodoItem rendered:', todo.text);
  // => Logs on every render
  // => Without useCallback, logs every time parent re-renders
 
  return (
    <li>
    {/* => List item */}
      {todo.text}
      <button onClick={() => onDelete(todo.id)}>Delete</button>
      {/* => Button "onDelete(todo.id)}>Delete" - triggers onClick handler */}
    </li>
  );
});
// => React.memo wraps component
// => Shallow comparison of props prevents unnecessary renders
 
function TodoList() {
  const [todos, setTodos] = useState([
    { id: 1, text: 'Read Quran' },
    // => Initial array item object
    { id: 2, text: 'Pray Fajr' }
  ]);
  // => End of initial state array
 
  const [count, setCount] = useState(0);    // => Unrelated state
 
  // => WITHOUT useCallback (inefficient)
  // => New function created on every render
  const handleDeleteWrong = (id: number) => {
    setTodos(todos.filter(todo => todo.id !== id));
  };
  // => Even if todos don't change, function reference changes
  // => TodoItem re-renders unnecessarily
 
  // => WITH useCallback (efficient)
  // => Function reference stays same unless dependencies change
  const handleDelete = useCallback((id: number) => {
    setTodos(prevTodos => prevTodos.filter(todo => todo.id !== id));
    // => Functional update avoids dependency on todos
    // => Dependencies: [] (empty) - function never recreated
  }, []);
  // => Empty dependency array: function memoized permanently
  // => Same function reference on every render
 
  // => useCallback with dependencies
  const handleDeleteWithDep = useCallback((id: number) => {
    setTodos(todos.filter(todo => todo.id !== id));
    // => Uses todos from closure
    // => Must include todos in dependencies
  }, [todos]);
  // => Function recreated only when todos changes
  // => New reference triggers TodoItem re-render
 
  return (
    <div>
    {/* => Container div for layout grouping */}
      <h2>Todos</h2>
      {/* => H2: "Todos" section heading */}
 
      <ul>
      {/* => Unordered list of items */}
        {todos.map(todo => (
          <TodoItem
          {/* => Renders TodoItem component */}
            key={todo.id}
            todo={todo}
            {/* => todo prop: todo */}
            onDelete={handleDelete}
            {/* => Passes memoized callback */}
            {/* => Same reference on every render */}
            {/* => TodoItem doesn't re-render unless todo changes */}
          />
        ))}
      </ul>
 
      <div>
      {/* => Container div for layout grouping */}
        <p>Unrelated Counter: {count}</p>
        {/* => Paragraph with content */}
        <button onClick={() => setCount(count + 1)}>
        {/* => Button: triggers click handler */}
          Increment Counter
        </button>
        {/* => Clicking this re-renders TodoList */}
        {/* => Without useCallback, all TodoItems re-render */}
        {/* => With useCallback, TodoItems don't re-render */}
      </div>
    </div>
  );
}
 
export default TodoList;
 

import { useState, useMemo } from 'react';
 
// => Type for Murabaha contract (Islamic financing)
interface MurabahaContract {
  id: number;
  // => id: numeric value field
  principalAmount: number;                   // => Original amount
  profitRate: number;                        // => Profit rate (percentage)
  termMonths: number;                        // => Loan term in months
}
 
function MurabahaCalculator() {
  const [contracts, setContracts] = useState<MurabahaContract[]>([
    { id: 1, principalAmount: 100000, profitRate: 5, termMonths: 12 },
    // => Initial array item object
    { id: 2, principalAmount: 50000, profitRate: 4, termMonths: 24 },
    // => Initial array item object
    { id: 3, principalAmount: 200000, profitRate: 6, termMonths: 36 }
  ]);
  // => End of initial state array
 
  const [filterTerm, setFilterTerm] = useState<number>(0);
  const [count, setCount] = useState(0);    // => Unrelated state
 
  // => EXPENSIVE computation WITHOUT useMemo
  // => Recalculates on EVERY render (even when contracts unchanged)
  const totalWithoutMemo = contracts.reduce((sum, contract) => {
    console.log('Calculating without memo for contract:', contract.id);
    // => This logs even when only count changes!
 
    const totalPayment = contract.principalAmount * (1 + contract.profitRate / 100);
    return sum + totalPayment;
  }, 0);
 
  // => EXPENSIVE computation WITH useMemo
  // => Recalculates ONLY when contracts changes
  const totalWithMemo = useMemo(() => {
    console.log('Calculating WITH memo (only when contracts change)');
    // => This logs only when contracts changes
    // => Not logged when count or filterTerm changes
 
    return contracts.reduce((sum, contract) => {
      const totalPayment = contract.principalAmount * (1 + contract.profitRate / 100);
      // => Principal + profit
      return sum + totalPayment;
    }, 0);
  }, [contracts]);
  // => Dependency array: [contracts]
  // => Memoized result returned if contracts unchanged
 
  // => Filtered contracts (also expensive)
  const filteredContracts = useMemo(() => {
    console.log('Filtering contracts (memoized)');
    // => Logs only when contracts or filterTerm changes
 
    if (filterTerm === 0) return contracts;
 
    return contracts.filter(c => c.termMonths === filterTerm);
    // => Filter by term length
  }, [contracts, filterTerm]);
  // => Dependencies: contracts AND filterTerm
  // => Recomputes if either changes
 
  // => Calculate statistics from memoized result
  const averageProfit = useMemo(() => {
    if (filteredContracts.length === 0) return 0;
 
    const totalProfit = filteredContracts.reduce((sum, contract) => {
      const profit = contract.principalAmount * (contract.profitRate / 100);
      return sum + profit;
    }, 0);
 
    return totalProfit / filteredContracts.length;
    // => Average profit per contract
  }, [filteredContracts]);
  // => Depends on filtered result (also memoized)
  // => Chained memoization
 
  return (
    <div>
    {/* => Container div for layout grouping */}
      <h2>Murabaha Contract Calculator</h2>
      {/* => H2: "Murabaha Contract Calculator" section heading */}
 
      <div>
      {/* => Container div for layout grouping */}
        <label>Filter by term (months): </label>
        <select
          value={filterTerm}
          {/* => value: controlled by state (state → UI sync) */}
          onChange={(e) => setFilterTerm(Number(e.target.value))}
          {/* => onChange: fires on every keystroke/change */}
        >
          <option value={0}>All</option>
          <option value={12}>12 months</option>
          <option value={24}>24 months</option>
          <option value={36}>36 months</option>
        </select>
        {/* => Changing filter triggers filteredContracts recalculation */}
      </div>
 
      <div>
      {/* => Container div for layout grouping */}
        <h3>Statistics</h3>
        {/* => H3: "Statistics" section heading */}
        <p>Total Contracts: {filteredContracts.length}</p>
        {/* => Paragraph with content */}
        <p>Total Payment (with profit): ${totalWithMemo.toFixed(2)}</p>
        {/* => Paragraph with content */}
        <p>Average Profit per Contract: ${averageProfit.toFixed(2)}</p>
        {/* => Paragraph with content */}
      </div>
 
      <div>
      {/* => Container div for layout grouping */}
        <h3>Contracts</h3>
        {/* => H3: "Contracts" section heading */}
        <ul>
        {/* => Unordered list of items */}
          {filteredContracts.map(contract => (
            <li key={contract.id}>
            {/* => List item with unique key for React reconciliation */}
              ID: {contract.id} - Principal: ${contract.principalAmount} -
              Profit Rate: {contract.profitRate}% - Term: {contract.termMonths} months
            </li>
          ))}
        </ul>
      </div>
 
      <div>
      {/* => Container div for layout grouping */}
        <p>Unrelated Counter: {count}</p>
        {/* => Paragraph with content */}
        <button onClick={() => setCount(count + 1)}>
        {/* => Button: triggers click handler */}
          Increment Counter
        </button>
        {/* => Clicking this re-renders component */}
        {/* => Without useMemo, calculations re-run */}
        {/* => With useMemo, calculations use cached result */}
        {/* => Check console logs to see difference */}
      </div>
    </div>
  );
}
 
export default MurabahaCalculator;
 

import { useState, useRef, useEffect } from 'react';
 
function DonationFormWithFocus() {
  const [amount, setAmount] = useState<number>(0);
  const [donations, setDonations] = useState<number[]>([]);
 
  // => Ref for DOM element access
  // => useRef<HTMLInputElement>(null) creates ref for input element
  const inputRef = useRef<HTMLInputElement>(null);
  // => inputRef.current is null initially
  // => After render, React assigns DOM element to inputRef.current
 
  // => Ref for mutable value (doesn't trigger re-render)
  const renderCount = useRef<number>(0);
  // => Persists across renders, unlike let variable
  // => Changing renderCount.current doesn't trigger re-render
 
  // => Ref for interval ID (cleanup reference)
  const intervalRef = useRef<NodeJS.Timeout | null>(null);
 
  // => Effect to count renders
  useEffect(() => {
    renderCount.current += 1;                // => Increment on every render
    // => Doesn't trigger re-render (unlike setState)
    console.log('Component rendered', renderCount.current, 'times');
  });
  // => No dependency array: runs after every render
 
  // => Focus input on mount
  useEffect(() => {
    if (inputRef.current) {
      // => Type guard: check if ref assigned
      inputRef.current.focus();              // => Focus the input element
      // => Directly manipulates DOM
    }
  }, []);
  // => Empty dependency array: runs once on mount
 
  // => Handle donation submission
  const handleDonate = () => {
    if (amount > 0) {
      setDonations(prev => [...prev, amount]);
      setAmount(0);                          // => Reset amount
 
      // => Focus input after submission
      if (inputRef.current) {
        inputRef.current.focus();            // => Return focus to input
      }
    }
  };
 
  // => Start auto-increment timer
  const startAutoIncrement = () => {
    if (intervalRef.current) return;         // => Already running
 
    // => Create interval and store ID in ref
    intervalRef.current = setInterval(() => {
      setAmount(prev => prev + 10);          // => Increment by \$10 every second
    }, 1000);
    // => Store interval ID for cleanup
  };
 
  // => Stop auto-increment timer
  const stopAutoIncrement = () => {
    if (intervalRef.current) {
      clearInterval(intervalRef.current);    // => Clear interval
      intervalRef.current = null;            // => Reset ref
    }
  };
 
  // => Cleanup on unmount
  useEffect(() => {
    return () => {
      // => Cleanup function runs on unmount
      if (intervalRef.current) {
        clearInterval(intervalRef.current);  // => Clear any active interval
      }
    };
  }, []);
 
  // => Get input element properties directly
  const handleCheckInput = () => {
    if (inputRef.current) {
      console.log('Input value:', inputRef.current.value);
      console.log('Input focused:', document.activeElement === inputRef.current);
      // => Direct DOM access via ref
    }
  };
 
  return (
    <div>
    {/* => Container div for layout grouping */}
      <h2>Donation Form</h2>
      {/* => H2: "Donation Form" section heading */}
      <p>Render count: {renderCount.current}</p>
      {/* => Display render count (doesn't trigger re-render when updated) */}
 
      <div>
      {/* => Container div for layout grouping */}
        <label>Amount ($): </label>
        <input
          ref={inputRef}
          {/* => Attach ref to input element */}
          {/* => React assigns DOM node to inputRef.current */}
          type="number"
          {/* => Input type: "number" */}
          value={amount}
          {/* => value: controlled by state (state → UI sync) */}
          onChange={(e) => setAmount(Number(e.target.value))}
          {/* => onChange: fires on every keystroke/change */}
          min="0"
          {/* => min: 0 (HTML input constraint) */}
        />
      </div>
 
      <div>
      {/* => Container div for layout grouping */}
        <button onClick={handleDonate}>Donate</button>
        {/* => Button "Donate" - triggers onClick handler */}
        <button onClick={handleCheckInput}>Check Input Properties</button>
        {/* => Button "Check Input Properties" - triggers onClick handler */}
      </div>
 
      <div>
      {/* => Container div for layout grouping */}
        <button onClick={startAutoIncrement}>Start Auto-Increment (\$10/sec)</button>
        {/* => Button "Start Auto-Increment (\$10/sec)" - triggers onClick handler */}
        <button onClick={stopAutoIncrement}>Stop Auto-Increment</button>
        {/* => Interval ID stored in ref persists across renders */}
      </div>
 
      <div>
      {/* => Container div for layout grouping */}
        <h3>Donations History</h3>
        {/* => H3: "Donations History" section heading */}
        <ul>
        {/* => Unordered list of items */}
          {donations.map((donation, index) => (
            <li key={index}>${donation}</li>
            {/* => List item with unique key for React reconciliation */}
          ))}
        </ul>
        <p>Total: ${donations.reduce((sum, d) => sum + d, 0)}</p>
        {/* => Paragraph with content */}
      </div>
    </div>
  );
}
 
export default DonationFormWithFocus;
 

import { useRef, useImperativeHandle, forwardRef, useState } from 'react';
 
// => Define methods exposed via ref
interface CounterRef {
  increment: () => void;
  decrement: () => void;
  reset: () => void;
  getValue: () => number;
}
 
// => Props for counter component
interface CounterProps {
  initialValue?: number;
  // => initialValue: optional field (undefined if not provided)
}
 
// => forwardRef allows component to receive ref
// => Second parameter is the forwarded ref
const Counter = forwardRef<CounterRef, CounterProps>((props, ref) => {
  const [count, setCount] = useState(props.initialValue || 0);
 
  // => useImperativeHandle customizes ref value
  // => First parameter: forwarded ref
  // => Second parameter: function returning exposed methods
  useImperativeHandle(ref, () => ({
    // => Return object with methods to expose
    // => Parent can call these methods via ref.current
 
    increment: () => {
      setCount(prev => prev + 1);            // => Increment internal state
      // => Parent can trigger this without props
    },
 
    decrement: () => {
      setCount(prev => prev - 1);
    },
 
    reset: () => {
      setCount(props.initialValue || 0);     // => Reset to initial value
    },
 
    getValue: () => {
      return count;                          // => Return current count
      // => Parent can read state without props
    }
  }), [count, props.initialValue]);
  // => Dependencies: recreate methods when these change
  // => Ensures closures capture latest values
 
  return (
    <div style={{ padding: '16px', border: '1px solid #ccc', margin: '8px' }}>
    {/* => Container div with inline styles */}
      <h3>Counter Component</h3>
      {/* => H3: "Counter Component" section heading */}
      <p>Count: {count}</p>
      {/* => Component manages its own UI */}
      {/* => Parent controls it via ref methods */}
    </div>
  );
});
// => forwardRef wraps component
// => Enables ref forwarding
 
// => Parent component using custom ref
function DonationDashboard() {
  // => Create ref for Counter component
  const counter1Ref = useRef<CounterRef>(null);
  const counter2Ref = useRef<CounterRef>(null);
  // => Typed with CounterRef interface
 
  const [message, setMessage] = useState<string>('');
 
  // => Call child method via ref
  const handleIncrementBoth = () => {
    counter1Ref.current?.increment();        // => Optional chaining (ref might be null)
    counter2Ref.current?.increment();
    // => Directly calls child's increment method
    // => No props needed for this control
  };
 
  // => Read child state via ref
  const handleGetTotal = () => {
    const value1 = counter1Ref.current?.getValue() || 0;
    const value2 = counter2Ref.current?.getValue() || 0;
    // => Calls getValue method on both counters
    // => Returns current count from each
 
    const total = value1 + value2;
    setMessage(`Total donations: $${total}`);
    // => Display combined total
  };
 
  // => Reset all counters
  const handleResetAll = () => {
    counter1Ref.current?.reset();
    counter2Ref.current?.reset();
    setMessage('All counters reset');
  };
 
  return (
    <div>
    {/* => Container div for layout grouping */}
      <h2>Donation Dashboard</h2>
      {/* => H2: "Donation Dashboard" section heading */}
 
      <div style={{ display: 'flex', gap: '16px' }}>
      {/* => Container div with inline styles */}
        <Counter ref={counter1Ref} initialValue={0} />
        {/* => Pass ref to child component */}
        {/* => forwardRef enables this */}
 
        <Counter ref={counter2Ref} initialValue={10} />
        {/* => Counter component (self-contained) */}
      </div>
 
      <div style={{ marginTop: '16px' }}>
      {/* => Container div with inline styles */}
        <button onClick={handleIncrementBoth}>
        {/* => Button: triggers click handler */}
          Increment Both Counters
        </button>
 
        <button onClick={() => counter1Ref.current?.decrement()}>
        {/* => Button: triggers click handler */}
          Decrement Counter 1
        </button>
 
        <button onClick={handleGetTotal}>
        {/* => Button: triggers click handler */}
          Get Total
        </button>
 
        <button onClick={handleResetAll}>
        {/* => Button: triggers click handler */}
          Reset All
        </button>
      </div>
 
      {message && <p><strong>{message}</strong></p>}
      {/* => Conditional render: shows if left side is truthy */}
    </div>
  );
}
 
export default DonationDashboard;
 

import { useState, useEffect } from 'react';
 
// => Custom hook for window dimensions
// => Returns current window width and height
function useWindowSize() {
  // => State for dimensions
  const [size, setSize] = useState({
    width: window.innerWidth,                // => Initial width
    height: window.innerHeight               // => Initial height
  });
 
  useEffect(() => {
    // => Event handler for resize
    const handleResize = () => {
      setSize({
        width: window.innerWidth,            // => Updated width
        height: window.innerHeight           // => Updated height
      });
    };
 
    // => Add event listener
    window.addEventListener('resize', handleResize);
    // => Listens for window resize events
 
    // => Cleanup function
    return () => {
      window.removeEventListener('resize', handleResize);
      // => Remove listener on unmount
    };
  }, []);
  // => Empty dependency array: setup once
 
  // => Return current size
  return size;
  // => Components using this hook get reactive size
}
 
// => Custom hook for local storage state
// => Syncs state with localStorage
function useLocalStorage<T>(key: string, initialValue: T) {
  // => Generic type T for value type
  // => State initialized from localStorage or initial value
  const [value, setValue] = useState<T>(() => {
    try {
      // => Try to get from localStorage
      const item = window.localStorage.getItem(key);
      // => Returns string or null
 
      return item ? JSON.parse(item) : initialValue;
      // => Parse JSON if exists, otherwise use initial value
    } catch (error) {
      console.error('Error reading from localStorage:', error);
      return initialValue;                   // => Fallback on error
    }
  });
  // => Lazy initialization (function runs only once)
 
  // => Update localStorage when value changes
  useEffect(() => {
    try {
      window.localStorage.setItem(key, JSON.stringify(value));
      // => Stringify value and save to localStorage
    } catch (error) {
      console.error('Error writing to localStorage:', error);
    }
  }, [key, value]);
  // => Dependencies: re-run when key or value changes
 
  // => Return tuple like useState
  return [value, setValue] as const;
  // => as const prevents TypeScript from widening type
  // => Maintains tuple structure [T, (value: T) => void]
}
 
// => Component using custom hooks
function ResponsiveDonationForm() {
  // => Use window size hook
  const { width, height } = useWindowSize();
  // => Automatically updates when window resizes
 
  // => Use localStorage hook for donation amount
  const [amount, setAmount] = useLocalStorage<number>('donationAmount', 0);
  // => Persists amount across page refreshes
 
  // => Use localStorage hook for donor name
  const [name, setName] = useLocalStorage<string>('donorName', '');
 
  // => Responsive behavior based on width
  const isMobile = width < 768;              // => Mobile breakpoint
 
  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    alert(`Donation submitted: $${amount} from ${name}`);
 
    // => Clear form after submission
    setAmount(0);
    setName('');
    // => Updates both state and localStorage
  };
 
  return (
    <div style={{ padding: '20px' }}>
    {/* => Container div with inline styles */}
      <h2>Donation Form</h2>
      {/* => H2: "Donation Form" section heading */}
 
      <p>
      {/* => Paragraph with content */}
        Window size: {width} x {height}
        {/* => Displays current dimensions */}
      </p>
 
      <p>
      {/* => Paragraph with content */}
        Layout: {isMobile ? 'Mobile' : 'Desktop'}
        {/* => Responsive indicator */}
      </p>
 
      <form onSubmit={handleSubmit} style={{
      {/* => Form with submit handler */}
        display: 'flex',
        flexDirection: isMobile ? 'column' : 'row',
        // => Stack vertically on mobile, horizontally on desktop
        gap: '12px'
      }}>
        <input
          type="text"
          {/* => Input type: "text" */}
          placeholder="Your Name"
          {/* => placeholder: "Your Name" */}
          value={name}
          {/* => value: controlled by state (state → UI sync) */}
          onChange={(e) => setName(e.target.value)}
          {/* => onChange: fires on every keystroke/change */}
          style={{ padding: '8px', flex: 1 }}
        />
 
        <input
          type="number"
          {/* => Input type: "number" */}
          placeholder="Amount"
          {/* => placeholder: "Amount" */}
          value={amount}
          {/* => value: controlled by state (state → UI sync) */}
          onChange={(e) => setAmount(Number(e.target.value))}
          {/* => onChange: fires on every keystroke/change */}
          style={{ padding: '8px', flex: 1 }}
          min="0"
          {/* => min: 0 (HTML input constraint) */}
        />
 
        <button type="submit" style={{ padding: '8px 16px' }}>
        {/* => Button element */}
          Donate
        </button>
      </form>
 
      <p style={{ fontSize: '0.875rem', color: '#666' }}>
        Your form data is saved locally and persists across page refreshes.
      </p>
    </div>
  );
}
 
export default ResponsiveDonationForm;
 

import { useState, useEffect } from 'react';
 
// => Complete useLocalStorage implementation
function useLocalStorage<T>(key: string, initialValue: T) {
  // => Get stored value or initial value
  const readValue = (): T => {
    // => Check if running in browser (not SSR)
    if (typeof window === 'undefined') {
      return initialValue;                   // => Return initial value during SSR
    }
 
    try {
      const item = window.localStorage.getItem(key);
      // => getItem returns string or null
 
      return item ? JSON.parse(item) : initialValue;
      // => Parse JSON string to original type
    } catch (error) {
      console.warn(`Error reading localStorage key "${key}":`, error);
      return initialValue;                   // => Fallback on error
    }
  };
 
  // => State with lazy initialization
  const [storedValue, setStoredValue] = useState<T>(readValue);
 
  // => Update localStorage and state
  const setValue = (value: T | ((val: T) => T)) => {
    try {
      // => Allow value to be function like useState
      const valueToStore = value instanceof Function ? value(storedValue) : value;
      // => If function, call with current value
      // => Otherwise use value directly
 
      // => Update state
      setStoredValue(valueToStore);
 
      // => Update localStorage
      if (typeof window !== 'undefined') {
        window.localStorage.setItem(key, JSON.stringify(valueToStore));
        // => Stringify and save
 
        // => Dispatch custom event for cross-tab sync
        window.dispatchEvent(new Event('local-storage'));
        // => Other tabs can listen to this event
      }
    } catch (error) {
      console.warn(`Error setting localStorage key "${key}":`, error);
    }
  };
 
  // => Listen for changes from other tabs
  useEffect(() => {
    const handleStorageChange = (e: StorageEvent) => {
      // => StorageEvent fires when localStorage changes in other tabs
      if (e.key === key && e.newValue !== null) {
        // => Check if our key changed
        setStoredValue(JSON.parse(e.newValue));
        // => Update state with new value from other tab
      }
    };
 
    // => Listen to storage event
    window.addEventListener('storage', handleStorageChange);
    // => Native event for cross-tab communication
 
    // => Listen to custom event (same tab updates)
    window.addEventListener('local-storage', () => {
      setStoredValue(readValue());           // => Re-read from localStorage
    });
 
    return () => {
      window.removeEventListener('storage', handleStorageChange);
      window.removeEventListener('local-storage', () => {});
    };
  }, [key]);
  // => Dependency: key (re-setup if key changes)
 
  return [storedValue, setValue] as const;
}
 
// => Component demonstrating localStorage hook
function SadaqahTracker() {
  // => Track monthly Sadaqah (charity) goal and current amount
  const [goal, setGoal] = useLocalStorage<number>('sadaqahGoal', 100);
  const [current, setCurrent] = useLocalStorage<number>('sadaqahCurrent', 0);
  // => Both persisted to localStorage
 
  // => Derived state: progress percentage
  const progress = goal > 0 ? (current / goal) * 100 : 0;
  // => Calculate percentage (handle division by zero)
 
  // => Handle donation
  const handleDonate = (amount: number) => {
    setCurrent(prev => prev + amount);       // => Functional update
    // => Updates localStorage automatically
  };
 
  // => Reset for new month
  const handleReset = () => {
    setCurrent(0);
    // => Keeps goal, resets current donations
  };
 
  return (
    <div style={{ maxWidth: '400px', margin: '0 auto', padding: '20px' }}>
    {/* => Container div with inline styles */}
      <h2>Monthly Sadaqah Tracker</h2>
      {/* => H2: "Monthly Sadaqah Tracker" section heading */}
 
      <div style={{ marginBottom: '16px' }}>
      {/* => Container div with inline styles */}
        <label>Monthly Goal ($): </label>
        <input
          type="number"
          {/* => Input type: "number" */}
          value={goal}
          {/* => value: controlled by state (state → UI sync) */}
          onChange={(e) => setGoal(Number(e.target.value))}
          {/* => onChange: fires on every keystroke/change */}
          min="0"
          {/* => min: 0 (HTML input constraint) */}
          style={{ padding: '4px', width: '100px' }}
        />
      </div>
 
      <div style={{ marginBottom: '16px' }}>
      {/* => Container div with inline styles */}
        <p><strong>Current Donations:</strong> ${current}</p>
        {/* => Paragraph with content */}
        <p><strong>Goal:</strong> ${goal}</p>
        {/* => Paragraph with content */}
        <p><strong>Progress:</strong> {progress.toFixed(1)}%</p>
 
        {/* => Progress bar */}
        <div style={{
          width: '100%',
          height: '24px',
          backgroundColor: '#f0f0f0',
          borderRadius: '4px',
          overflow: 'hidden'
        }}>
          <div style={{
            width: `${Math.min(progress, 100)}%`,
            height: '100%',
            backgroundColor: progress >= 100 ? '#029E73' : '#0173B2',
            // => Green if goal reached, blue otherwise
            transition: 'width 0.3s ease'
          }} />
        </div>
      </div>
 
      <div style={{ display: 'flex', gap: '8px', flexWrap: 'wrap' }}>
      {/* => Container div with inline styles */}
        <button onClick={() => handleDonate(5)} style={{ padding: '8px' }}>
        {/* => Button: triggers click handler */}
          Donate \$5
        </button>
        <button onClick={() => handleDonate(10)} style={{ padding: '8px' }}>
        {/* => Button: triggers click handler */}
          Donate \$10
        </button>
        <button onClick={() => handleDonate(25)} style={{ padding: '8px' }}>
        {/* => Button: triggers click handler */}
          Donate \$25
        </button>
      </div>
 
      <div style={{ marginTop: '16px' }}>
      {/* => Container div with inline styles */}
        <button onClick={handleReset} style={{ padding: '8px' }}>
        {/* => Button: triggers click handler */}
          Reset for New Month
        </button>
      </div>
 
      <p style={{ marginTop: '16px', fontSize: '0.875rem', color: '#666' }}>
        Data persists across page refreshes and syncs across browser tabs.
        Open this page in multiple tabs and try donating!
      </p>
    </div>
  );
}
 
export default SadaqahTracker;
 

import { useState, useEffect } from 'react';
 
// => Debounce hook implementation
// => Returns debounced value that updates after delay
function useDebounce<T>(value: T, delay: number): T {
  // => Generic type T for any value type
  // => State for debounced value
  const [debouncedValue, setDebouncedValue] = useState<T>(value);
  // => Initially equals input value
 
  useEffect(() => {
    // => Set timeout to update debounced value
    const handler = setTimeout(() => {
      setDebouncedValue(value);              // => Update after delay
      // => Only runs if value stays stable for delay duration
    }, delay);
    // => handler is timeout ID for cleanup
 
    // => Cleanup function
    return () => {
      clearTimeout(handler);                 // => Clear timeout on cleanup
      // => Runs before next effect or on unmount
      // => If value changes before timeout, old timeout cleared
    };
  }, [value, delay]);
  // => Dependencies: re-run when value or delay changes
  // => New timeout set on every value change
  // => Previous timeout cleared, resetting delay
 
  return debouncedValue;
  // => Returns stable value (only updates after delay)
}
 
// => Component using debounce hook
function PrayerSearch() {
  // => Search input state (updates immediately)
  const [searchTerm, setSearchTerm] = useState<string>('');
 
  // => Debounced search term (updates after 500ms delay)
  const debouncedSearchTerm = useDebounce(searchTerm, 500);
  // => Only updates when searchTerm stable for 500ms
 
  // => State for search results
  const [results, setResults] = useState<string[]>([]);
  const [isSearching, setIsSearching] = useState<boolean>(false);
 
  // => Mock prayer database
  const prayerDatabase = [
    'Fajr (Dawn Prayer)',
    'Dhuhr (Noon Prayer)',
    'Asr (Afternoon Prayer)',
    'Maghrib (Sunset Prayer)',
    'Isha (Night Prayer)',
    'Tahajjud (Night Prayer)',
    'Duha (Forenoon Prayer)',
    'Witr (Odd Prayer)',
    'Taraweeh (Ramadan Prayer)'
  ];
 
  // => Perform search when debounced term changes
  useEffect(() => {
    // => Only search if debounced term not empty
    if (debouncedSearchTerm.trim() === '') {
      setResults([]);
      setIsSearching(false);
      return;
    }
 
    // => Simulate search start
    setIsSearching(true);
    console.log('Searching for:', debouncedSearchTerm);
    // => This logs only when typing stops for 500ms
    // => Without debounce, would log on every keystroke
 
    // => Simulate API call with timeout
    const searchTimeout = setTimeout(() => {
      // => Filter prayers matching search term
      const filtered = prayerDatabase.filter(prayer =>
        prayer.toLowerCase().includes(debouncedSearchTerm.toLowerCase())
      );
 
      setResults(filtered);
      setIsSearching(false);
      console.log('Search complete. Results:', filtered.length);
    }, 300);
    // => Simulate 300ms API latency
 
    return () => clearTimeout(searchTimeout);
    // => Cleanup if debounced term changes again
  }, [debouncedSearchTerm]);
  // => Dependency: debouncedSearchTerm (not searchTerm!)
  // => Effect only runs when debounced value changes
  // => Prevents excessive API calls while typing
 
  return (
    <div style={{ maxWidth: '500px', margin: '0 auto', padding: '20px' }}>
    {/* => Container div with inline styles */}
      <h2>Prayer Search</h2>
      {/* => H2: "Prayer Search" section heading */}
 
      <div>
      {/* => Container div for layout grouping */}
        <input
          type="text"
          {/* => Input type: "text" */}
          value={searchTerm}
          {/* => value: controlled by state (state → UI sync) */}
          onChange={(e) => setSearchTerm(e.target.value)}
          // => Updates immediately on every keystroke
          placeholder="Search prayers (e.g., 'Fajr', 'Night')..."
          {/* => placeholder: "Search prayers (e.g., 'Fajr', 'Night')..." */}
          style={{
            width: '100%',
            padding: '12px',
            fontSize: '16px',
            border: '1px solid #ccc',
            borderRadius: '4px'
          }}
        />
 
        <p style={{ fontSize: '0.875rem', color: '#666', marginTop: '8px' }}>
          {searchTerm !== debouncedSearchTerm && 'Typing...'}
          {/* => Show "Typing..." if values differ (debounce in progress) */}
 
          {searchTerm === debouncedSearchTerm && searchTerm && !isSearching && `Found ${results.length} prayers`}
          {/* => Show count when stable and not searching */}
 
          {isSearching && 'Searching...'}
          {/* => Conditional render: shows if left side is truthy */}
        </p>
      </div>
 
      <div style={{ marginTop: '16px' }}>
      {/* => Container div with inline styles */}
        {results.length > 0 ? (
        {/* => True branch: rendered when condition is true */}
          <ul style={{ listStyle: 'none', padding: 0 }}>
            {results.map((prayer, index) => (
              <li key={index} style={{
              {/* => List item with unique key for React reconciliation */}
                padding: '12px',
                backgroundColor: '#f5f5f5',
                marginBottom: '8px',
                borderRadius: '4px'
              }}>
                {prayer}
              </li>
            ))}
          </ul>
        ) : debouncedSearchTerm && !isSearching ? (
        {/* => True branch: rendered when condition is true */}
          <p>No prayers found matching "{debouncedSearchTerm}"</p>
          {/* => Paragraph with content */}
        ) : null}
      </div>
 
      <div style={{ marginTop: '16px', fontSize: '0.875rem', color: '#666' }}>
      {/* => Container div with inline styles */}
        <p><strong>Debounce Demo:</strong></p>
        {/* => Paragraph with content */}
        <p>Current input: "{searchTerm}"</p>
        {/* => Paragraph with content */}
        <p>Debounced value: "{debouncedSearchTerm}"</p>
        {/* => Paragraph with content */}
        <p>Search only happens when you stop typing for 500ms.</p>
        {/* => Paragraph: "Search only happens when you stop typing..." */}
      </div>
    </div>
  );
}
 
export default PrayerSearch;
 

import { useState, useEffect } from 'react';
 
// => Type for fetch hook return value
interface UseFetchResult<T> {
  data: T | null;                            // => Fetched data or null
  loading: boolean;                          // => Loading indicator
  error: string | null;                      // => Error message or null
}
 
// => Generic fetch hook implementation
function useFetch<T>(url: string): UseFetchResult<T> {
  // => State for data, loading, and error
  const [data, setData] = useState<T | null>(null);
  const [loading, setLoading] = useState<boolean>(true);
  const [error, setError] = useState<string | null>(null);
 
  useEffect(() => {
    // => Reset states on URL change
    setLoading(true);
    setError(null);
    setData(null);
 
    // => AbortController for request cancellation
    const controller = new AbortController();
    // => Creates signal for fetch cancellation
    const signal = controller.signal;
 
    console.log('Fetching:', url);
 
    // => Perform fetch
    fetch(url, { signal })
    // => Pass signal to enable cancellation
      .then(response => {
        // => Check HTTP status
        if (!response.ok) {
          throw new Error(`HTTP error! status: ${response.status}`);
          // => Throw for 4xx, 5xx responses
        }
        return response.json();              // => Parse JSON body
      })
      .then((jsonData: T) => {
        // => Success: update data
        setData(jsonData);
        setLoading(false);
        console.log('Fetch successful');
      })
      .catch(err => {
        // => Error handling
        if (err.name === 'AbortError') {
          // => Request was cancelled
          console.log('Fetch aborted');
        } else {
          // => Actual error
          console.error('Fetch error:', err);
          setError(err.message);
          setLoading(false);
        }
      });
 
    // => Cleanup function
    return () => {
      controller.abort();                    // => Cancel request on cleanup
      // => Runs when URL changes or component unmounts
      // => Prevents state updates on unmounted component
      console.log('Aborting fetch');
    };
  }, [url]);
  // => Dependency: url (re-fetch when URL changes)
 
  // => Return current state
  return { data, loading, error };
}
 
// => Type for user data
interface User {
  id: number;
  // => id: numeric value field
  name: string;
  // => name: text value field
  email: string;
  // => email: text value field
  phone: string;
  // => phone: text value field
}
 
// => Component using fetch hook
function UserProfile() {
  const [userId, setUserId] = useState<number>(1);
 
  // => Use fetch hook with dynamic URL
  const { data: user, loading, error } = useFetch<User>(
    `https://jsonplaceholder.typicode.com/users/${userId}`
  );
  // => Destructure with alias (data as user)
  // => Re-fetches when userId changes
 
  // => Loading state
  if (loading) {
    return (
      <div style={{ padding: '20px' }}>
      {/* => Container div with inline styles */}
        <p>Loading user data...</p>
        {/* => Show loading indicator */}
      </div>
    );
  }
 
  // => Error state
  if (error) {
    return (
      <div style={{ padding: '20px' }}>
      {/* => Container div with inline styles */}
        <p style={{ color: 'red' }}>Error: {error}</p>
        {/* => Display error message */}
 
        <button onClick={() => setUserId(userId)}>
        {/* => Button: triggers click handler */}
          Retry
        </button>
        {/* => Re-trigger fetch by setting same userId */}
      </div>
    );
  }
 
  // => Success state
  return (
    <div style={{ padding: '20px', maxWidth: '500px', margin: '0 auto' }}>
    {/* => Container div with inline styles */}
      <h2>User Profile</h2>
      {/* => H2: "User Profile" section heading */}
 
      {user && (
        <div style={{
          padding: '16px',
          backgroundColor: '#f5f5f5',
          borderRadius: '8px'
        }}>
          <p><strong>ID:</strong> {user.id}</p>
          {/* => Paragraph with content */}
          <p><strong>Name:</strong> {user.name}</p>
          {/* => Paragraph with content */}
          <p><strong>Email:</strong> {user.email}</p>
          {/* => Paragraph with content */}
          <p><strong>Phone:</strong> {user.phone}</p>
          {/* => Paragraph with content */}
        </div>
      )}
 
      <div style={{ marginTop: '16px', display: 'flex', gap: '8px' }}>
      {/* => Container div with inline styles */}
        <button
          onClick={() => setUserId(prev => Math.max(1, prev - 1))}
          {/* => onClick: fires on user click */}
          disabled={userId === 1}
          // => Disable at minimum ID
        >
          Previous User
        </button>
 
        <button
          onClick={() => setUserId(prev => Math.min(10, prev + 1))}
          {/* => onClick: fires on user click */}
          disabled={userId === 10}
          // => Disable at maximum ID
        >
          Next User
        </button>
      </div>
 
      <p style={{ marginTop: '16px', fontSize: '0.875rem', color: '#666' }}>
        Current user ID: {userId}. Click buttons to fetch different users.
        Rapid clicking demonstrates request cancellation (check console).
      </p>
    </div>
  );
}
 
export default UserProfile;
 

import { useState } from 'react';
 
// => Type for validation rules
interface ValidationRules {
  required?: boolean;
  // => required: optional field (undefined if not provided)
  minLength?: number;
  // => minLength: optional field (undefined if not provided)
  maxLength?: number;
  // => maxLength: optional field (undefined if not provided)
  pattern?: RegExp;
  // => pattern: optional field (undefined if not provided)
  custom?: (value: any) => string | undefined;
}
 
// => Type for field configuration
interface FieldConfig {
  initialValue: any;
  validation?: ValidationRules;
  // => validation: optional field (undefined if not provided)
}
 
// => Type for form configuration
interface FormConfig {
  [key: string]: FieldConfig;
}
 
// => Type for form errors
interface FormErrors {
  [key: string]: string | undefined;
}
 
// => useForm hook implementation
function useForm<T extends { [key: string]: any }>(config: FormConfig) {
  // => State for form values
  // => Stores current value for each form field
  const [values, setValues] = useState<T>(() => {
    // => Initialize from config using lazy initialization
    // => Lazy init prevents recreation on every render
    const initialValues: any = {};  // => Empty object to collect initial values
    Object.keys(config).forEach(key => {
      // => Iterate through field configurations
      // => Extract initialValue for each field
      initialValues[key] = config[key].initialValue;
      // => Set field's starting value from config
    });
    return initialValues as T;  // => Type assertion for TypeScript
  });
 
  // => State for errors
  // => Maps field name to error message
  // => Empty string or undefined means no error
  const [errors, setErrors] = useState<FormErrors>({});
  // => Example: { email: 'Invalid email format', phone: undefined }
 
  // => State for touched fields
  // => Tracks which fields user has interacted with
  // => Only show errors for touched fields (better UX)
  const [touched, setTouched] = useState<{ [key: string]: boolean }>({});
  // => Example: { email: true, phone: false } - email touched, phone not
 
  // => Validate single field against its rules
  // => Returns error message string or undefined (valid)
  // => Pure function - no side effects
  const validateField = (name: string, value: any): string | undefined => {
    const rules = config[name]?.validation;
    // => Get validation rules for this field
    // => Optional chaining (?.) handles missing config safely
    if (!rules) return undefined;  // => No rules means field is valid
 
    // => Required validation
    // => Checks if value exists (not empty, null, undefined)
    if (rules.required && !value) {
      return 'This field is required';
      // => Fails for '', null, undefined, 0, false
    }
 
    // => Min length validation
    // => Only applies to string/array values with .length property
    if (rules.minLength && value.length < rules.minLength) {
      return `Minimum length is ${rules.minLength}`;
      // => Example: minLength: 3, value: 'ab' → error
    }
 
    // => Max length validation
    // => Prevents excessive input (security + UX)
    if (rules.maxLength && value.length > rules.maxLength) {
      return `Maximum length is ${rules.maxLength}`;
      // => Example: maxLength: 50, value: 'very long...' → error
    }
 
    // => Pattern validation
    // => Tests value against regex pattern
    // => Common for email, phone, zip code, etc.
    if (rules.pattern && !rules.pattern.test(value)) {
      return 'Invalid format';
      // => Example: pattern: /^[0-9]+$/, value: 'abc' → error
    }
 
    // => Custom validation
    // => Allows domain-specific validation logic
    // => Function receives value, returns error message or undefined
    if (rules.custom) {
      return rules.custom(value);
      // => Example: (val) => val.includes('@') ? undefined : 'Must contain @'
    }
 
    return undefined;  // => All validations passed, field is valid
  };
 
  // => Handle field change (called on every keystroke/input)
  // => Updates value and re-validates if field already touched
  const handleChange = (name: string, value: any) => {
    // => Update field value immutably
    // => Functional update ensures latest state
    setValues(prev => ({
      ...prev,                      // => Keep all other field values
      [name]: value                 // => Override changed field
      // => Computed property syntax: field name determines key
    }));
 
    // => Validate only if field has been touched
    // => Avoids showing errors before user interaction (better UX)
    if (touched[name]) {
      const error = validateField(name, value);
      // => Re-validate with new value
      // => Returns error message or undefined
      setErrors(prev => ({
        ...prev,
        [name]: error               // => Update or clear error for this field
        // => If error is undefined, field becomes valid
      }));
    }
  };
 
  // => Handle field blur (when input loses focus)
  // => Marks field as touched and validates current value
  const handleBlur = (name: string) => {
    // => Mark field as touched
    // => Enables error display for this field
    setTouched(prev => ({
      ...prev,
      [name]: true                  // => Set touched flag
      // => Once touched, errors will show on change
    }));
 
    // => Validate field with current value
    // => Uses values[name] from current state
    const error = validateField(name, values[name]);
    // => Get current value from state
    // => Validate against field's rules
    setErrors(prev => ({
      ...prev,
      [name]: error                 // => Set validation result
      // => Error message or undefined (valid)
    }));
  };
 
  // => Validate all fields at once
  // => Called on form submission
  // => Returns true if entire form is valid, false otherwise
  const validateAll = (): boolean => {
    const newErrors: FormErrors = {};
    // => Collect all validation errors
    // => Will contain only fields with errors
    let isValid = true;
    // => Track overall form validity
    // => Flips to false if any field has error
 
    Object.keys(config).forEach(name => {
      // => Iterate through all configured fields
      // => Validate each field regardless of touched state
      const error = validateField(name, values[name]);
      // => Run validation for current field value
      // => Returns error message or undefined
      if (error) {
        // => Field has validation error
        newErrors[name] = error;
        // => Add error to collection
        // => Example: { email: 'Invalid email', phone: 'Required' }
        isValid = false;
        // => Mark form as invalid
        // => Even one error makes entire form invalid
      }
    });
 
    setErrors(newErrors);
    // => Update all errors at once
    // => Replaces previous error state completely
    // => Shows all validation errors simultaneously
    setTouched(
      Object.keys(config).reduce((acc, key) => ({ ...acc, [key]: true }), {})
      // => Mark all fields as touched
      // => reduce() builds object: { field1: true, field2: true, ... }
      // => Ensures all errors are visible to user
    );
 
    return isValid;
    // => Return validation result
    // => true: form submittable, false: has errors
  };
 
  // => Reset form to initial state
  // => Clears all values, errors, and touched flags
  // => Useful after successful submission or user cancellation
  const reset = () => {
    const initialValues: any = {};
    // => Recreate initial values object
    Object.keys(config).forEach(key => {
      initialValues[key] = config[key].initialValue;
      // => Extract initial value from each field config
      // => Restores form to starting state
    });
    setValues(initialValues as T);
    // => Reset values to initial state
    // => Type assertion for TypeScript safety
    setErrors({});
    // => Clear all validation errors
    // => Empty object means no errors
    setTouched({});
    // => Clear all touched flags
    // => Form appears untouched after reset
  };
 
  return {
    // => Return form management API
    // => Object destructured by component
    values,       // => Current field values
    errors,       // => Current validation errors
    touched,      // => Which fields have been interacted with
    handleChange, // => Function to update field value
    handleBlur,   // => Function called when field loses focus
    validateAll,  // => Function to validate entire form
    reset         // => Function to reset form to initial state
    // => Clean API hides internal state management complexity
  };
}
 
// => Component using form hook
// => Demonstrates useForm hook in production scenario
function DonorRegistrationForm() {
  // => Define form configuration
  // => Generic type <{...}> ensures type safety for form.values
  const form = useForm<{
    name: string;      // => Donor's full name
    email: string;     // => Donor's email address
    phone: string;     // => Donor's phone number
    amount: number;    // => Donation amount in dollars
  }>({
    // => Configuration object defines fields + validation rules
    name: {
      initialValue: '',              // => Start with empty string
      validation: {
        required: true,               // => Field is mandatory
        minLength: 3,                 // => Minimum 3 characters
        maxLength: 50                 // => Maximum 50 characters
        // => Prevents very short names ('ab') or excessively long input
      }
    },
    email: {
      initialValue: '',
      validation: {
        required: true,               // => Email is mandatory
        pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
        // => Basic email regex pattern
        // => Checks for: localpart @ domain . tld
        // => Prevents spaces, requires @ and dot
        custom: (value) => {
          // => Custom validation: block disposable emails
          // => Domain-specific business logic
          if (value.endsWith('@tempmail.com')) {
            return 'Disposable emails not allowed';
            // => Reject temporary/throwaway email services
          }
          return undefined;  // => Valid email
        }
      }
    },
    phone: {
      initialValue: '',
      validation: {
        required: true,               // => Phone is mandatory
        pattern: /^\d{10}$/,          // => Exactly 10 digits
        // => ^ = start, \d = digit, {10} = exactly 10, $ = end
        custom: (value) => {
          if (value && !/^\d{10}$/.test(value)) {
            return 'Phone must be 10 digits';
            // => Custom error message for clarity
            // => Redundant with pattern but provides better UX message
          }
          return undefined;
        }
      }
    },
    amount: {
      initialValue: 0,                // => Start at 0
      validation: {
        required: true,               // => Amount is mandatory
        custom: (value) => {
          if (value <= 0) {
            return 'Amount must be greater than 0';
            // => Business rule: no zero or negative donations
            // => Ensures meaningful contribution
          }
          return undefined;
        }
      }
    }
  });
 
  const [submitted, setSubmitted] = useState(false);
  // => Track submission state
  // => Shows success message after valid submission
 
  // => Handle form submission
  // => Validates entire form before processing
  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    // => Prevent default form submission
    // => Stops page reload, allows custom handling
 
    // => Validate all fields
    // => Returns true if all valid, false if any errors
    if (form.validateAll()) {
      // => All fields valid - process submission
      console.log('Form submitted:', form.values);
      // => In production: send to API, save to database, etc.
      setSubmitted(true);
      // => Show success message
      // => Triggers conditional render below
 
      // => Reset after 2 seconds
      // => Gives user time to see success message
      setTimeout(() => {
        form.reset();
        // => Clear form to initial state
        // => Ready for next submission
        setSubmitted(false);
        // => Hide success message
        // => Return to form view
      }, 2000);  // => 2000ms = 2 seconds
    } else {
      // => Form has validation errors
      console.log('Form has errors:', form.errors);
      // => In production: show toast notification, focus first error, etc.
      // => Errors already displayed by field-level validation
    }
  };
 
  if (submitted) {
    // => Conditional render: show success message after submission
    return (
      <div style={{ padding: '20px', textAlign: 'center' }}>
        {/* => Success message displayed for 2 seconds */}
        <h2 style={{ color: '#029E73' }}>Thank you for your donation!</h2>
        {/* => Accessible green color from palette */}
        <p>Donor: {form.values.name}</p>
        {/* => Display submitted donor name */}
        <p>Amount: ${form.values.amount}</p>
        {/* => Display submitted amount */}
        {/* => After timeout, form resets and this view disappears */}
      </div>
    );
  }
 
  return (
    <div style={{ maxWidth: '500px', margin: '0 auto', padding: '20px' }}>
      {/* => Centered container with max width for readability */}
      <h2>Donor Registration</h2>
      {/* => H2: "Donor Registration" section heading */}
 
      <form onSubmit={handleSubmit}>
        {/* => Form submission calls handleSubmit */}
        {/* => Name field */}
        <div style={{ marginBottom: '16px' }}>
          {/* => Field container with bottom spacing */}
          <label style={{ display: 'block', marginBottom: '4px' }}>
            Name *
            {/* => Asterisk indicates required field */}
          </label>
          <input
            type="text"
            {/* => Input type: "text" */}
            value={form.values.name}
            {/* => Controlled input: value from form state */}
            onChange={(e) => form.handleChange('name', e.target.value)}
            {/* => Update form value on every keystroke */}
            {/* => Extract value from event target */}
            onBlur={() => form.handleBlur('name')}
            {/* => Mark field as touched when focus lost */}
            {/* => Triggers validation */}
            style={{
              width: '100%',
              padding: '8px',
              border: form.errors.name && form.touched.name ? '2px solid red' : '1px solid #ccc',
              {/* => Red border if error exists AND field touched */}
              {/* => Gray border otherwise (normal state) */}
              borderRadius: '4px'
            }}
          />
          {form.errors.name && form.touched.name && (
            {/* => Conditional render: show error only if exists AND touched */}
            {/* => Prevents showing errors before user interaction */}
            <p style={{ color: 'red', fontSize: '0.875rem', margin: '4px 0 0' }}>
              {form.errors.name}
              {/* => Display error message from validation */}
            </p>
          )}
        </div>
 
        {/* => Email field */}
        <div style={{ marginBottom: '16px' }}>
        {/* => Container div with inline styles */}
          <label style={{ display: 'block', marginBottom: '4px' }}>
            Email *
          </label>
          <input
            type="email"
            {/* => Input type: "email" */}
            value={form.values.email}
            {/* => value: controlled by state (state → UI sync) */}
            onChange={(e) => form.handleChange('email', e.target.value)}
            {/* => onChange: fires on every keystroke/change */}
            onBlur={() => form.handleBlur('email')}
            {/* => onBlur prop: () => form.handleBlur('email') */}
            style={{
              width: '100%',
              padding: '8px',
              border: form.errors.email && form.touched.email ? '2px solid red' : '1px solid #ccc',
              borderRadius: '4px'
            }}
          />
          {form.errors.email && form.touched.email && (
            <p style={{ color: 'red', fontSize: '0.875rem', margin: '4px 0 0' }}>
              {form.errors.email}
            </p>
          )}
        </div>
 
        {/* => Phone field */}
        <div style={{ marginBottom: '16px' }}>
        {/* => Container div with inline styles */}
          <label style={{ display: 'block', marginBottom: '4px' }}>
            Phone (10 digits) *
          </label>
          <input
            type="tel"
            {/* => Input type: "tel" */}
            value={form.values.phone}
            {/* => value: controlled by state (state → UI sync) */}
            onChange={(e) => form.handleChange('phone', e.target.value)}
            {/* => onChange: fires on every keystroke/change */}
            onBlur={() => form.handleBlur('phone')}
            {/* => onBlur prop: () => form.handleBlur('phone') */}
            style={{
              width: '100%',
              padding: '8px',
              border: form.errors.phone && form.touched.phone ? '2px solid red' : '1px solid #ccc',
              borderRadius: '4px'
            }}
          />
          {form.errors.phone && form.touched.phone && (
            <p style={{ color: 'red', fontSize: '0.875rem', margin: '4px 0 0' }}>
              {form.errors.phone}
            </p>
          )}
        </div>
 
        {/* => Amount field */}
        <div style={{ marginBottom: '16px' }}>
        {/* => Container div with inline styles */}
          <label style={{ display: 'block', marginBottom: '4px' }}>
            Donation Amount ($) *
          </label>
          <input
            type="number"
            {/* => Input type: "number" */}
            value={form.values.amount}
            {/* => value: controlled by state (state → UI sync) */}
            onChange={(e) => form.handleChange('amount', Number(e.target.value))}
            {/* => onChange: fires on every keystroke/change */}
            onBlur={() => form.handleBlur('amount')}
            {/* => onBlur prop: () => form.handleBlur('amount') */}
            min="0"
            {/* => min: 0 (HTML input constraint) */}
            style={{
              width: '100%',
              padding: '8px',
              border: form.errors.amount && form.touched.amount ? '2px solid red' : '1px solid #ccc',
              borderRadius: '4px'
            }}
          />
          {form.errors.amount && form.touched.amount && (
            <p style={{ color: 'red', fontSize: '0.875rem', margin: '4px 0 0' }}>
              {form.errors.amount}
            </p>
          )}
        </div>
 
        <div style={{ display: 'flex', gap: '12px' }}>
        {/* => Container div with inline styles */}
          <button
            type="submit"
            {/* => Input type: "submit" */}
            style={{
              padding: '12px 24px',
              backgroundColor: '#0173B2',
              color: '#fff',
              border: 'none',
              borderRadius: '4px',
              cursor: 'pointer',
              flex: 1
            }}
          >
            Submit Donation
          </button>
 
          <button
            type="button"
            {/* => Input type: "button" */}
            onClick={form.reset}
            {/* => onClick: fires on user click */}
            style={{
              padding: '12px 24px',
              backgroundColor: '#ccc',
              color: '#000',
              border: 'none',
              borderRadius: '4px',
              cursor: 'pointer'
            }}
          >
            Reset
          </button>
        </div>
      </form>
    </div>
  );
}
 
export default DonorRegistrationForm;