🎯 useRef Hook

import { useRef } from 'react';

function MyComponent() {
    // Create a ref
    const myRef = useRef(initialValue);
    
    // Access the current value
    console.log(myRef.current); // initialValue
    
    // Modify the current value
    myRef.current = newValue;
    
    return <div>Hello</div>;
}

// This is what useRef returns:
{
    current: yourInitialValue
}

// You can think of it like this simple object:
const ref = { current: 0 };
ref.current = 5; // You can change it
console.log(ref.current); // 5

function Counter() {
    // Regular variable - resets to 0 on every render
    let count = 0;
    
    // Ref - persists across renders
    const countRef = useRef(0);
    
    const handleClick = () => {
        count++; // This resets on next render!
        countRef.current++; // This persists!
        
        console.log('Regular:', count); // Always 1
        console.log('Ref:', countRef.current); // 1, 2, 3, 4...
    };
    
    return <button onClick={handleClick}>Click me</button>;
}

function Example() {
    // State - triggers re-render when changed
    const [count, setCount] = useState(0);
    
    // Ref - does NOT trigger re-render when changed
    const countRef = useRef(0);
    
    const handleStateClick = () => {
        setCount(count + 1); // Component re-renders
        console.log('State updated:', count); // Still shows old value!
    };
    
    const handleRefClick = () => {
        countRef.current++; // No re-render
        console.log('Ref updated:', countRef.current); // Shows new value immediately
    };
    
    return (
        <div>
            <p>State: {count}</p>
            <p>Ref: {countRef.current}</p> {/* Won't update on screen! */}
            <button onClick={handleStateClick}>Update State</button>
            <button onClick={handleRefClick}>Update Ref</button>
        </div>
    );
}

import { useRef } from 'react';

function FocusInput() {
    // Create a ref for the input element
    const inputRef = useRef<HTMLInputElement>(null);
    
    const handleFocus = () => {
        // Access the DOM element via ref.current
        inputRef.current?.focus();
    };
    
    return (
        <div>
            <input ref={inputRef} type="text" />
            <button onClick={handleFocus}>Focus Input</button>
        </div>
    );
}

function LoginForm() {
    const emailRef = useRef<HTMLInputElement>(null);
    const passwordRef = useRef<HTMLInputElement>(null);
    
    const handleSubmit = (e: React.FormEvent) => {
        e.preventDefault();
        
        // Focus first empty field
        if (!emailRef.current?.value) {
            emailRef.current?.focus();
        } else if (!passwordRef.current?.value) {
            passwordRef.current?.focus();
        }
    };
    
    // Focus email on mount
    useEffect(() => {
        emailRef.current?.focus();
    }, []);
    
    return (
        <form onSubmit={handleSubmit}>
            <input ref={emailRef} type="email" placeholder="Email" />
            <input ref={passwordRef} type="password" placeholder="Password" />
            <button type="submit">Login</button>
        </form>
    );
}

function ChatRoom() {
    const messagesEndRef = useRef<HTMLDivElement>(null);
    
    const scrollToBottom = () => {
        messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' });
    };
    
    // Scroll to bottom when new message arrives
    useEffect(() => {
        scrollToBottom();
    }, [messages]);
    
    return (
        <div className="chat-container">
            {messages.map(msg => (
                <div key={msg.id}>{msg.text}</div>
            ))}
            <div ref={messagesEndRef} /> {/* Invisible anchor */}
        </div>
    );
}

function MeasureBox() {
    const boxRef = useRef<HTMLDivElement>(null);
    const [dimensions, setDimensions] = useState({ width: 0, height: 0 });
    
    const measureBox = () => {
        if (boxRef.current) {
            const { width, height } = boxRef.current.getBoundingClientRect();
            setDimensions({ width, height });
        }
    };
    
    useEffect(() => {
        measureBox();
        window.addEventListener('resize', measureBox);
        return () => window.removeEventListener('resize', measureBox);
    }, []);
    
    return (
        <div>
            <div ref={boxRef} className="box">
                Resize the window!
            </div>
            <p>Width: {dimensions.width}px</p>
            <p>Height: {dimensions.height}px</p>
        </div>
    );
}

function VideoPlayer() {
    const videoRef = useRef<HTMLVideoElement>(null);
    const [isPlaying, setIsPlaying] = useState(false);
    
    const togglePlay = () => {
        if (videoRef.current) {
            if (isPlaying) {
                videoRef.current.pause();
            } else {
                videoRef.current.play();
            }
            setIsPlaying(!isPlaying);
        }
    };
    
    return (
        <div>
            <video ref={videoRef} src="video.mp4" />
            <button onClick={togglePlay}>
                {isPlaying ? 'Pause' : 'Play'}
            </button>
        </div>
    );
}

function ComparisonDemo() {
    const [stateCount, setStateCount] = useState(0);
    const refCount = useRef(0);
    
    console.log('Component rendered');
    
    return (
        <div>
            {/* State - displays on screen, triggers re-render */}
            <p>State Count: {stateCount}</p>
            <button onClick={() => setStateCount(stateCount + 1)}>
                Increment State (re-renders)
            </button>
            
            {/* Ref - won't update on screen, no re-render */}
            <p>Ref Count: {refCount.current}</p>
            <button onClick={() => refCount.current++}>
                Increment Ref (no re-render)
            </button>
        </div>
    );
    // Click state button: "Component rendered" logs
    // Click ref button: Nothing logs!
}

// ✅ Use state - user needs to see the count
function ClickCounter() {
    const [count, setCount] = useState(0);
    
    return (
        <div>
            <p>Clicks: {count}</p>
            <button onClick={() => setCount(count + 1)}>
                Click me
            </button>
        </div>
    );
}

// ✅ Use ref - tracking renders, not displaying to user
function RenderCounter() {
    const renderCount = useRef(0);
    
    useEffect(() => {
        renderCount.current++;
        console.log(`Rendered ${renderCount.current} times`);
    });
    
    const [name, setName] = useState('');
    
    return (
        <div>
            <input 
                value={name} 
                onChange={(e) => setName(e.target.value)} 
            />
            {/* Don't try to display ref.current in JSX! */}
        </div>
    );
}

// ✅ Use ref - timer ID doesn't affect UI
function Timer() {
    const [seconds, setSeconds] = useState(0);
    const intervalRef = useRef<number | null>(null);
    
    const startTimer = () => {
        intervalRef.current = setInterval(() => {
            setSeconds(s => s + 1);
        }, 1000);
    };
    
    const stopTimer = () => {
        if (intervalRef.current) {
            clearInterval(intervalRef.current);
        }
    };
    
    useEffect(() => {
        return () => stopTimer(); // Cleanup
    }, []);
    
    return (
        <div>
            <p>Seconds: {seconds}</p>
            <button onClick={startTimer}>Start</button>
            <button onClick={stopTimer}>Stop</button>
        </div>
    );
}

function usePrevious<T>(value: T): T | undefined {
    // React 19 requires an initial argument — pass undefined explicitly
    const ref = useRef<T | undefined>(undefined);

    useEffect(() => {
        ref.current = value;
    }, [value]);

    return ref.current;
}

// Usage
function Counter() {
    const [count, setCount] = useState(0);
    const prevCount = usePrevious(count);
    
    return (
        <div>
            <p>Current: {count}</p>
            <p>Previous: {prevCount}</p>
            <button onClick={() => setCount(count + 1)}>
                Increment
            </button>
        </div>
    );
}

// Generic syntax: useRef<Type>(initialValue)

// DOM element refs - always start with null
const inputRef = useRef<HTMLInputElement>(null);
const divRef = useRef<HTMLDivElement>(null);
const buttonRef = useRef<HTMLButtonElement>(null);

// Value refs - can start with any value
const countRef = useRef<number>(0);
const nameRef = useRef<string>('');
const dataRef = useRef<User | null>(null);

// ✅ Correct - DOM refs start as null
const inputRef = useRef<HTMLInputElement>(null);

// TypeScript knows ref.current might be null
inputRef.current?.focus(); // Use optional chaining

// ❌ Wrong - TypeScript error!
const inputRef = useRef<HTMLInputElement>();
// Error: Argument of type 'undefined' is not assignable to parameter of type 'HTMLInputElement | null'

// Simple types
const countRef = useRef<number>(0);
const nameRef = useRef<string>('John');
const isActiveRef = useRef<boolean>(false);

// Complex types
interface User {
    id: number;
    name: string;
}

const userRef = useRef<User | null>(null);
const usersRef = useRef<User[]>([]);

// Timer IDs — the browser and Node return different types.
// ReturnType<typeof setInterval> works in both environments:
const timerRef = useRef<ReturnType<typeof setInterval> | null>(null);

// WebSocket or other APIs
const socketRef = useRef<WebSocket | null>(null);

function SafeRefAccess() {
    const inputRef = useRef<HTMLInputElement>(null);
    
    const focusInput = () => {
        // ✅ Safe - won't crash if ref.current is null
        inputRef.current?.focus();
        
        // ✅ Safe - check with if statement
        if (inputRef.current) {
            inputRef.current.focus();
        }
        
        // ❌ Unsafe - could crash!
        // inputRef.current.focus(); // TypeScript error
    };
    
    return <input ref={inputRef} />;
}

// Mutable ref (default) - you can change .current
const mutableRef = useRef<number>(0);
mutableRef.current = 5; // ✅ Allowed

// Read-only ref (rare, but possible)
const readonlyRef = useRef<number>(0) as { readonly current: number };
// readonlyRef.current = 5; // ❌ TypeScript error

// Generic function that works with any ref type
function useLatest<T>(value: T) {
    const ref = useRef<T>(value);
    
    useEffect(() => {
        ref.current = value;
    }, [value]);
    
    return ref;
}

// Usage with different types
const nameLatest = useLatest('John'); // RefObject<string>
const countLatest = useLatest(42); // RefObject<number>
const userLatest = useLatest({ id: 1, name: 'Alice' }); // RefObject<User>

// Pattern 1: Union type for multiple possibilities
const elementRef = useRef<HTMLDivElement | HTMLSpanElement>(null);

// Pattern 2: Nullable ref
const optionalRef = useRef<string | null>(null);

// Pattern 3: Array of refs
const itemRefs = useRef<HTMLDivElement[]>([]);

// Pattern 4: Ref to custom component (we'll cover this later)
const customRef = useRef<CustomComponentHandle>(null);

function Stopwatch() {
    const [time, setTime] = useState(0);
    const [isRunning, setIsRunning] = useState(false);
    const intervalRef = useRef<number | null>(null);
    
    const start = () => {
        if (!isRunning) {
            setIsRunning(true);
            intervalRef.current = setInterval(() => {
                setTime(t => t + 10);
            }, 10);
        }
    };
    
    const stop = () => {
        if (intervalRef.current) {
            clearInterval(intervalRef.current);
            setIsRunning(false);
        }
    };
    
    const reset = () => {
        stop();
        setTime(0);
    };
    
    // Cleanup on unmount
    useEffect(() => {
        return () => {
            if (intervalRef.current) {
                clearInterval(intervalRef.current);
            }
        };
    }, []);
    
    return (
        <div>
            <p>Time: {(time / 1000).toFixed(2)}s</p>
            <button onClick={start}>Start</button>
            <button onClick={stop}>Stop</button>
            <button onClick={reset}>Reset</button>
        </div>
    );
}

function ValueChangeDetector({ value }: { value: number }) {
    const prevValueRef = useRef<number>(value);
    
    useEffect(() => {
        const prev = prevValueRef.current;
        
        if (prev !== value) {
            console.log(`Value changed from ${prev} to ${value}`);
        }
        
        // Update ref for next render
        prevValueRef.current = value;
    }, [value]);
    
    return <div>Current value: {value}</div>;
}

function DataFetcher() {
    const [data, setData] = useState(null);
    const [loading, setLoading] = useState(false);
    
    // Track if component is mounted to prevent setState on unmounted component
    const isMountedRef = useRef(true);
    
    useEffect(() => {
        return () => {
            isMountedRef.current = false;
        };
    }, []);
    
    const fetchData = async () => {
        setLoading(true);
        
        try {
            const response = await fetch('/api/data');
            const result = await response.json();
            
            // Only update state if still mounted
            if (isMountedRef.current) {
                setData(result);
            }
        } finally {
            if (isMountedRef.current) {
                setLoading(false);
            }
        }
    };
    
    return (
        <div>
            <button onClick={fetchData}>Fetch Data</button>
            {loading && <p>Loading...</p>}
        </div>
    );
}

function useLatestCallback<T extends (...args: any[]) => any>(callback: T) {
    const callbackRef = useRef(callback);
    
    // Update ref whenever callback changes
    useEffect(() => {
        callbackRef.current = callback;
    }, [callback]);
    
    // Return stable callback that always calls the latest version
    const stableCallback = useCallback(
        (...args: Parameters<T>) => callbackRef.current(...args),
        []
    );
    
    return stableCallback;
}

// Usage
function SearchBox({ onSearch }: { onSearch: (query: string) => void }) {
    const [query, setQuery] = useState('');
    
    // onSearch might change, but we want stable reference for useEffect
    const stableOnSearch = useLatestCallback(onSearch);
    
    useEffect(() => {
        const timer = setTimeout(() => {
            stableOnSearch(query);
        }, 500);
        
        return () => clearTimeout(timer);
    }, [query]); // Only query in deps, not onSearch!
    
    return <input value={query} onChange={(e) => setQuery(e.target.value)} />;
}

function WebSocketChat() {
    const [messages, setMessages] = useState<string[]>([]);
    const socketRef = useRef<WebSocket | null>(null);
    
    useEffect(() => {
        // Create WebSocket connection
        socketRef.current = new WebSocket('ws://localhost:8080');
        
        socketRef.current.onmessage = (event) => {
            setMessages(prev => [...prev, event.data]);
        };
        
        // Cleanup on unmount
        return () => {
            socketRef.current?.close();
        };
    }, []);
    
    const sendMessage = (message: string) => {
        socketRef.current?.send(message);
    };
    
    return (
        <div>
            {messages.map((msg, i) => (
                <p key={i}>{msg}</p>
            ))}
            <button onClick={() => sendMessage('Hello')}>
                Send Hello
            </button>
        </div>
    );
}

interface LoginFormProps {
    onSubmit: (credentials: { email: string; password: string }) => void;
}

function LoginForm({ onSubmit }: LoginFormProps) {
    const emailRef = useRef<HTMLInputElement>(null);
    const passwordRef = useRef<HTMLInputElement>(null);
    const [errors, setErrors] = useState<{ email?: string; password?: string }>({});
    
    // Focus email input when component mounts
    useEffect(() => {
        emailRef.current?.focus();
    }, []);
    
    const handleSubmit = (e: React.FormEvent) => {
        e.preventDefault();
        
        const email = emailRef.current?.value || '';
        const password = passwordRef.current?.value || '';
        
        // Validate
        const newErrors: { email?: string; password?: string } = {};
        
        if (!email.includes('@')) {
            newErrors.email = 'Invalid email';
            emailRef.current?.focus(); // Focus first error
            setErrors(newErrors);
            return;
        }
        
        if (password.length < 8) {
            newErrors.password = 'Password must be 8+ characters';
            passwordRef.current?.focus();
            setErrors(newErrors);
            return;
        }
        
        setErrors({});
        onSubmit({ email, password });
    };
    
    return (
        <form onSubmit={handleSubmit}>
            <div>
                <label htmlFor="email">Email</label>
                <input
                    id="email"
                    ref={emailRef}
                    type="email"
                    aria-invalid={!!errors.email}
                    aria-describedby={errors.email ? 'email-error' : undefined}
                />
                {errors.email && (
                    <span id="email-error" role="alert">{errors.email}</span>
                )}
            </div>
            
            <div>
                <label htmlFor="password">Password</label>
                <input
                    id="password"
                    ref={passwordRef}
                    type="password"
                    aria-invalid={!!errors.password}
                />
                {errors.password && (
                    <span role="alert">{errors.password}</span>
                )}
            </div>
            
            <button type="submit">Login</button>
        </form>
    );
}

interface Message {
    id: string;
    text: string;
    sender: string;
    timestamp: Date;
}

interface ChatMessagesProps {
    messages: Message[];
}

function ChatMessages({ messages }: ChatMessagesProps) {
    const messagesEndRef = useRef<HTMLDivElement>(null);
    const containerRef = useRef<HTMLDivElement>(null);
    const [showScrollButton, setShowScrollButton] = useState(false);
    
    // Auto-scroll to bottom when new messages arrive
    useEffect(() => {
        messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' });
    }, [messages]);
    
    // Show/hide scroll-to-bottom button based on scroll position
    useEffect(() => {
        const container = containerRef.current;
        if (!container) return;
        
        const handleScroll = () => {
            const { scrollTop, scrollHeight, clientHeight } = container;
            const isNearBottom = scrollHeight - scrollTop - clientHeight < 100;
            setShowScrollButton(!isNearBottom);
        };
        
        container.addEventListener('scroll', handleScroll);
        return () => container.removeEventListener('scroll', handleScroll);
    }, []);
    
    const scrollToBottom = () => {
        messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' });
    };
    
    return (
        <div className="chat-container">
            <div ref={containerRef} className="messages-list">
                {messages.map(msg => (
                    <div key={msg.id} className="message">
                        <strong>{msg.sender}:</strong> {msg.text}
                    </div>
                ))}
                <div ref={messagesEndRef} />
            </div>
            
            {showScrollButton && (
                <button 
                    className="scroll-to-bottom"
                    onClick={scrollToBottom}
                    aria-label="Scroll to latest messages"
                >
                    ↓ New messages
                </button>
            )}
        </div>
    );
}

function ResponsiveDropdown() {
    const triggerRef = useRef<HTMLButtonElement>(null);
    const dropdownRef = useRef<HTMLDivElement>(null);
    const [isOpen, setIsOpen] = useState(false);
    const [dropdownPosition, setDropdownPosition] = useState<'bottom' | 'top'>('bottom');
    
    useEffect(() => {
        if (!isOpen || !triggerRef.current || !dropdownRef.current) return;
        
        const triggerRect = triggerRef.current.getBoundingClientRect();
        const dropdownRect = dropdownRef.current.getBoundingClientRect();
        
        // Check if dropdown would overflow viewport
        const spaceBelow = window.innerHeight - triggerRect.bottom;
        const spaceAbove = triggerRect.top;
        
        if (spaceBelow < dropdownRect.height && spaceAbove > dropdownRect.height) {
            setDropdownPosition('top');
        } else {
            setDropdownPosition('bottom');
        }
    }, [isOpen]);
    
    return (
        <div className="dropdown-container">
            <button
                ref={triggerRef}
                onClick={() => setIsOpen(!isOpen)}
                aria-expanded={isOpen}
                aria-haspopup="true"
            >
                Open Menu
            </button>
            
            {isOpen && (
                <div
                    ref={dropdownRef}
                    className={`dropdown-menu dropdown-${dropdownPosition}`}
                    role="menu"
                >
                    <button role="menuitem">Option 1</button>
                    <button role="menuitem">Option 2</button>
                    <button role="menuitem">Option 3</button>
                </div>
            )}
        </div>
    );
}

import Chart from 'chart.js/auto'; // Example: Chart.js

interface ChartData {
    labels: string[];
    values: number[];
}

interface ChartComponentProps {
    data: ChartData;
    type: 'bar' | 'line' | 'pie';
}

function ChartComponent({ data, type }: ChartComponentProps) {
    const canvasRef = useRef<HTMLCanvasElement>(null);
    const chartRef = useRef<Chart | null>(null);
    
    useEffect(() => {
        if (!canvasRef.current) return;
        
        // Destroy previous chart instance if it exists
        if (chartRef.current) {
            chartRef.current.destroy();
        }
        
        // Create new chart
        chartRef.current = new Chart(canvasRef.current, {
            type,
            data: {
                labels: data.labels,
                datasets: [{
                    label: 'Dataset',
                    data: data.values,
                    backgroundColor: 'rgba(102, 126, 234, 0.5)',
                    borderColor: 'rgba(102, 126, 234, 1)',
                    borderWidth: 2
                }]
            },
            options: {
                responsive: true,
                maintainAspectRatio: false
            }
        });
        
        // Cleanup: destroy chart when component unmounts
        return () => {
            if (chartRef.current) {
                chartRef.current.destroy();
            }
        };
    }, [data, type]);
    
    return (
        <div style={{ height: '400px', width: '100%' }}>
            <canvas ref={canvasRef} />
        </div>
    );
}

// Custom hook to track previous value
function usePrevious<T>(value: T): T | undefined {
    // React 19: pass an explicit initial value (undefined)
    const ref = useRef<T | undefined>(undefined);

    useEffect(() => {
        ref.current = value;
    }, [value]);

    return ref.current;
}

// Usage example
function CounterWithHistory() {
    const [count, setCount] = useState(0);
    const previousCount = usePrevious(count);
    
    return (
        <div>
            <p>Current: {count}</p>
            <p>Previous: {previousCount ?? 'N/A'}</p>
            <p>
                {previousCount !== undefined && count > previousCount && '📈 Increased!'}
                {previousCount !== undefined && count < previousCount && '📉 Decreased!'}
            </p>
            <button onClick={() => setCount(count + 1)}>+</button>
            <button onClick={() => setCount(count - 1)}>-</button>
        </div>
    );
}

interface VideoPlayerProps {
    src: string;
    poster?: string;
}

function VideoPlayer({ src, poster }: VideoPlayerProps) {
    const videoRef = useRef<HTMLVideoElement>(null);
    const [isPlaying, setIsPlaying] = useState(false);
    const [currentTime, setCurrentTime] = useState(0);
    const [duration, setDuration] = useState(0);
    
    const togglePlayPause = () => {
        if (!videoRef.current) return;
        
        if (isPlaying) {
            videoRef.current.pause();
        } else {
            videoRef.current.play();
        }
        setIsPlaying(!isPlaying);
    };
    
    const handleSeek = (time: number) => {
        if (!videoRef.current) return;
        videoRef.current.currentTime = time;
        setCurrentTime(time);
    };
    
    const handleTimeUpdate = () => {
        if (!videoRef.current) return;
        setCurrentTime(videoRef.current.currentTime);
    };
    
    const handleLoadedMetadata = () => {
        if (!videoRef.current) return;
        setDuration(videoRef.current.duration);
    };
    
    const handleSkip = (seconds: number) => {
        if (!videoRef.current) return;
        const newTime = Math.max(0, Math.min(duration, currentTime + seconds));
        handleSeek(newTime);
    };
    
    return (
        <div className="video-player">
            <video
                ref={videoRef}
                src={src}
                poster={poster}
                onTimeUpdate={handleTimeUpdate}
                onLoadedMetadata={handleLoadedMetadata}
                onEnded={() => setIsPlaying(false)}
            />
            
            <div className="controls">
                <button onClick={togglePlayPause}>
                    {isPlaying ? '⏸️ Pause' : '▶️ Play'}
                </button>
                
                <button onClick={() => handleSkip(-10)}>⏪ -10s</button>
                <button onClick={() => handleSkip(10)}>⏩ +10s</button>
                
                <input
                    type="range"
                    min="0"
                    max={duration}
                    value={currentTime}
                    onChange={(e) => handleSeek(Number(e.target.value))}
                    aria-label="Seek video"
                />
                
                <span>
                    {Math.floor(currentTime)}s / {Math.floor(duration)}s
                </span>
            </div>
        </div>
    );
}

// ⚠️ React 18 and earlier: this did NOT work.
//    React reserved `ref`, so `ref` here was always undefined.
function CustomInput({ label, ref }: { label: string; ref: any }) {
    return (
        <div>
            <label>{label}</label>
            <input ref={ref} /> {/* ref never arrived */}
        </div>
    );
}

interface CustomInputProps {
    label: string;
    error?: string;
    ref?: React.Ref<HTMLInputElement>;
}

// ✅ React 19: ref is a normal prop — no forwardRef needed
function CustomInput({ label, error, ref }: CustomInputProps) {
    return (
        <div className="input-group">
            <label>{label}</label>
            <input
                ref={ref}
                className={error ? 'input-error' : ''}
                aria-invalid={!!error}
            />
            {error && <span className="error-message">{error}</span>}
        </div>
    );
}

// Usage — identical to using a built-in element
function LoginForm() {
    const emailRef = useRef<HTMLInputElement>(null);

    useEffect(() => {
        emailRef.current?.focus();
    }, []);

    return (
        <form>
            <CustomInput ref={emailRef} label="Email" />
        </form>
    );
}

import { useImperativeHandle, useRef } from 'react';

// The API we choose to expose to the parent
interface VideoPlayerHandle {
    play: () => void;
    pause: () => void;
    seek: (time: number) => void;
    getCurrentTime: () => number;
}

interface VideoPlayerProps {
    src: string;
    ref?: React.Ref<VideoPlayerHandle>;
}

// ✅ React 19: ref is a prop; useImperativeHandle shapes what it holds
function VideoPlayer({ src, ref }: VideoPlayerProps) {
    const videoRef = useRef<HTMLVideoElement>(null);

    useImperativeHandle(ref, () => ({
        play() {
            videoRef.current?.play();
        },
        pause() {
            videoRef.current?.pause();
        },
        seek(time: number) {
            if (videoRef.current) {
                videoRef.current.currentTime = time;
            }
        },
        getCurrentTime() {
            return videoRef.current?.currentTime ?? 0;
        }
    }), []);

    return <video ref={videoRef} src={src} />;
}

// Usage in parent — ref.current is the handle, not the <video>
function VideoApp() {
    const playerRef = useRef<VideoPlayerHandle>(null);

    return (
        <div>
            <VideoPlayer ref={playerRef} src="video.mp4" />

            <button onClick={() => playerRef.current?.play()}>Play</button>
            <button onClick={() => playerRef.current?.pause()}>Pause</button>
            <button onClick={() => playerRef.current?.seek(30)}>Skip to 30s</button>
        </div>
    );
}

interface FormFieldHandle {
    focus: () => void;
    getValue: () => string;
    setValue: (value: string) => void;
    validate: () => boolean;
}

interface FormFieldProps {
    label: string;
    type?: 'text' | 'email' | 'password';
    required?: boolean;
    pattern?: string;
    errorMessage?: string;
    ref?: React.Ref<FormFieldHandle>;
}

// ✅ React 19: ref as a prop + useImperativeHandle for a clean API
function FormField({
    label, type = 'text', required, pattern, errorMessage, ref
}: FormFieldProps) {
    const inputRef = useRef<HTMLInputElement>(null);
    const [error, setError] = useState('');

    useImperativeHandle(ref, () => ({
        focus() {
            inputRef.current?.focus();
        },
        getValue() {
            return inputRef.current?.value ?? '';
        },
        setValue(value: string) {
            if (inputRef.current) {
                inputRef.current.value = value;
            }
        },
        validate() {
            const value = inputRef.current?.value ?? '';

            if (required && !value) {
                setError('This field is required');
                return false;
            }

            if (pattern && !new RegExp(pattern).test(value)) {
                setError(errorMessage ?? 'Invalid format');
                return false;
            }

            setError('');
            return true;
        }
    }), [required, pattern, errorMessage]);

    return (
        <div className="form-field">
            <label>{label} {required && <span>*</span>}</label>
            <input
                ref={inputRef}
                type={type}
                aria-required={required}
                aria-invalid={!!error}
            />
            {error && <span className="error">{error}</span>}
        </div>
    );
}

// Usage
function RegistrationForm() {
    const emailRef = useRef<FormFieldHandle>(null);
    const passwordRef = useRef<FormFieldHandle>(null);
    
    const handleSubmit = (e: React.FormEvent) => {
        e.preventDefault();
        
        const emailValid = emailRef.current?.validate();
        const passwordValid = passwordRef.current?.validate();
        
        if (!emailValid) {
            emailRef.current?.focus();
            return;
        }
        
        if (!passwordValid) {
            passwordRef.current?.focus();
            return;
        }
        
        // Submit form
        const email = emailRef.current?.getValue();
        const password = passwordRef.current?.getValue();
        console.log('Submitting:', { email, password });
    };
    
    return (
        <form onSubmit={handleSubmit}>
            <FormField
                ref={emailRef}
                label="Email"
                type="email"
                required
                pattern="^[^\s@]+@[^\s@]+\.[^\s@]+$"
                errorMessage="Please enter a valid email"
            />
            
            <FormField
                ref={passwordRef}
                label="Password"
                type="password"
                required
                pattern=".{8,}"
                errorMessage="Password must be at least 8 characters"
            />
            
            <button type="submit">Register</button>
        </form>
    );
}

// ❌ Bad - reading ref during render
function BadComponent() {
    const countRef = useRef(0);
    countRef.current++; // Don't do this!
    
    return <div>Renders: {countRef.current}</div>;
}

// ✅ Good - use state for values shown to user
function GoodComponent() {
    const [count, setCount] = useState(0);
    
    useEffect(() => {
        setCount(prev => prev + 1);
    });
    
    return <div>Renders: {count}</div>;
}

// ❌ Bad - expecting ref change to update UI
function BadCounter() {
    const countRef = useRef(0);
    
    const increment = () => {
        countRef.current++; // UI won't update!
    };
    
    return (
        <div>
            <p>Count: {countRef.current}</p> {/* Stuck at 0 */}
            <button onClick={increment}>+</button>
        </div>
    );
}

// ✅ Good - use state for UI updates
function GoodCounter() {
    const [count, setCount] = useState(0);
    
    return (
        <div>
            <p>Count: {count}</p>
            <button onClick={() => setCount(count + 1)}>+</button>
        </div>
    );
}

// ❌ Bad - no cleanup, memory leak!
function BadTimer() {
    const timerRef = useRef<ReturnType<typeof setInterval> | null>(null);

    useEffect(() => {
        timerRef.current = setInterval(() => {
            console.log('tick');
        }, 1000);
        // Missing cleanup!
    }, []);

    return <div>Timer running</div>;
}

// ✅ Good - proper cleanup
function GoodTimer() {
    const timerRef = useRef<ReturnType<typeof setInterval> | null>(null);

    useEffect(() => {
        timerRef.current = setInterval(() => {
            console.log('tick');
        }, 1000);
        
        return () => {
            if (timerRef.current) {
                clearInterval(timerRef.current);
            }
        };
    }, []);
    
    return <div>Timer running</div>;
}

// ❌ Bad - might crash!
function BadFocus() {
    const inputRef = useRef<HTMLInputElement>(null);
    
    useEffect(() => {
        inputRef.current.focus(); // Might be null!
    }, []);
    
    return <input ref={inputRef} />;
}

// ✅ Good - null check
function GoodFocus() {
    const inputRef = useRef<HTMLInputElement>(null);
    
    useEffect(() => {
        inputRef.current?.focus(); // Safe with optional chaining
    }, []);
    
    return <input ref={inputRef} />;
}

// ❌ Bad - missing initial argument
function BadRef() {
    const inputRef = useRef<HTMLInputElement>(); // Type error in React 19!
    return <input ref={inputRef} />;
}

// ❌ Also bad - mutable value with no initial value
function AlsoBad() {
    const countRef = useRef<number>(); // Type error — and would be undefined
    countRef.current++; // NaN!
}

// ✅ Good - proper initialization
function GoodRefs() {
    const inputRef = useRef<HTMLInputElement>(null); // DOM refs start as null
    const countRef = useRef(0); // Mutable values have initial value
    
    return <input ref={inputRef} />;
}

// ❌ Bad - stale closure captures old value
function BadCallback({ onSave }: { onSave: (data: string) => void }) {
    const [data, setData] = useState('');
    
    useEffect(() => {
        const interval = setInterval(() => {
            onSave(data); // Always uses initial data value!
        }, 1000);
        
        return () => clearInterval(interval);
    }, []); // Empty deps = stale closure
    
    return <input value={data} onChange={e => setData(e.target.value)} />;
}

// ✅ Good - ref always has latest value
function GoodCallback({ onSave }: { onSave: (data: string) => void }) {
    const [data, setData] = useState('');
    const dataRef = useRef(data);
    
    // Keep ref in sync
    useEffect(() => {
        dataRef.current = data;
    }, [data]);
    
    useEffect(() => {
        const interval = setInterval(() => {
            onSave(dataRef.current); // Always uses latest data!
        }, 1000);
        
        return () => clearInterval(interval);
    }, [onSave]);
    
    return <input value={data} onChange={e => setData(e.target.value)} />;
}