⚛️ React Interview Questions

// A simple React component that shows how React works
import { useState } from "react";

// Component: a reusable piece of UI
function TaskCounter() {
    // State: data that changes over time
    const [tasks, setTasks] = useState([
        { id: 1, title: "Review PR #42", done: false },
        { id: 2, title: "Fix login bug", done: true },
        { id: 3, title: "Write unit tests", done: false },
    ]);

    const completedCount = tasks.filter(t => t.done).length;

    const toggleTask = (id) => {
        setTasks(prev =>
            prev.map(t => t.id === id ? { ...t, done: !t.done } : t)
        );
    };

    // JSX: HTML-like syntax inside JavaScript
    return (
        <div className="task-counter">
            <h2>Sprint Tasks ({completedCount}/{tasks.length} done)</h2>
            <ul>
                {tasks.map(task => (
                    <li key={task.id}
                        onClick={() => toggleTask(task.id)}
                        style={{ textDecoration: task.done ? "line-through" : "none" }}>
                        {task.done ? "✅" : "⬜"} {task.title}
                    </li>
                ))}
            </ul>
        </div>
    );
}

export default TaskCounter;

// Why React?
// 1. Component-based — reusable, testable pieces
// 2. Virtual DOM — efficient updates (only changed parts re-render)
// 3. Unidirectional data flow — predictable state changes
// 4. Huge ecosystem — React Router, Redux, Next.js, React Native

// ── JSX vs HTML differences ──

// 1. className instead of class
const Header = () => (
    <header className="site-header">
        <h1 className="title">Dashboard</h1>
    </header>
);

// 2. Inline styles use objects (camelCase properties)
const Badge = ({ status }) => (
    <span style={{
        backgroundColor: status === "active" ? "#22c55e" : "#ef4444",
        color: "#fff",
        padding: "4px 12px",
        borderRadius: "12px",
        fontSize: "0.85rem",
        fontWeight: 600,
    }}>
        {status}
    </span>
);

// 3. JavaScript expressions inside { }
const UserCard = ({ user }) => (
    <div className="user-card">
        <img src={user.avatar} alt={`${user.name}'s avatar`} />
        <h3>{user.name}</h3>
        <p>Joined: {new Date(user.joinDate).toLocaleDateString()}</p>
        <p>{user.posts.length} posts</p>
        {user.isVerified && <Badge status="verified" />}
    </div>
);

// 4. All tags must be self-closed
const Form = () => (
    <form>
        <input type="text" placeholder="Search..." />
        <br />
        <img src="/logo.png" alt="Logo" />
        <hr />
    </form>
);

// 5. What JSX compiles to (Babel output):
// <h1 className="title">Hello</h1>
// becomes:
// React.createElement("h1", { className: "title" }, "Hello");

// 6. htmlFor instead of for
const EmailField = () => (
    <div>
        <label htmlFor="email">Email</label>
        <input id="email" type="email" />
    </div>
);

// ── Functional Component (Modern — recommended) ──
import { useState, useEffect } from "react";

function ProductCard({ product, onAddToCart }) {
    const [quantity, setQuantity] = useState(1);
    const [inStock, setInStock] = useState(true);

    useEffect(() => {
        // Check stock when product changes
        fetch(`/api/stock/${product.id}`)
            .then(res => res.json())
            .then(data => setInStock(data.available > 0));
    }, [product.id]);

    return (
        <div className="product-card">
            <img src={product.image} alt={product.name} />
            <h3>{product.name}</h3>
            <p className="price">₹{product.price.toLocaleString()}</p>
            {inStock ? (
                <>
                    <select value={quantity} onChange={e => setQuantity(Number(e.target.value))}>
                        {[1, 2, 3, 4, 5].map(n => (
                            <option key={n} value={n}>{n}</option>
                        ))}
                    </select>
                    <button onClick={() => onAddToCart(product, quantity)}>
                        Add to Cart
                    </button>
                </>
            ) : (
                <p className="out-of-stock">Out of Stock</p>
            )}
        </div>
    );
}

// ── Class Component (Legacy — same functionality) ──
import React from "react";

class ProductCardClass extends React.Component {
    constructor(props) {
        super(props);
        this.state = { quantity: 1, inStock: true };
    }

    componentDidMount() {
        this.checkStock();
    }

    componentDidUpdate(prevProps) {
        if (prevProps.product.id !== this.props.product.id) {
            this.checkStock();
        }
    }

    checkStock() {
        fetch(`/api/stock/${this.props.product.id}`)
            .then(res => res.json())
            .then(data => this.setState({ inStock: data.available > 0 }));
    }

    render() {
        const { product, onAddToCart } = this.props;
        const { quantity, inStock } = this.state;

        return (
            <div className="product-card">
                <h3>{product.name}</h3>
                <p>₹{product.price.toLocaleString()}</p>
                {inStock && (
                    <button onClick={() => onAddToCart(product, quantity)}>
                        Add to Cart
                    </button>
                )}
            </div>
        );
    }
}

// Functional: 30 lines | Class: 40 lines — same result
// Functional components are simpler and support hooks

// ── Passing props: parent → child ──
function App() {
    const [cartItems, setCartItems] = useState([]);

    // Callback function passed as prop — child-to-parent communication
    const handleAddToCart = (product, qty) => {
        setCartItems(prev => [...prev, { ...product, qty }]);
    };

    return (
        <div className="app">
            {/* Passing data + callback as props */}
            <ProductList
                products={products}
                onAddToCart={handleAddToCart}
            />
            <CartSummary items={cartItems} />
        </div>
    );
}

// ── Receiving props (destructured) ──
function ProductList({ products, onAddToCart }) {
    return (
        <div className="product-grid">
            {products.map(product => (
                <ProductCard
                    key={product.id}
                    name={product.name}
                    price={product.price}
                    image={product.image}
                    onAdd={() => onAddToCart(product, 1)}
                />
            ))}
        </div>
    );
}

// ── Default props with destructuring defaults ──
function ProductCard({ name, price, image, onAdd, discount = 0 }) {
    const finalPrice = price - (price * discount / 100);
    return (
        <div className="product-card">
            <img src={image} alt={name} />
            <h3>{name}</h3>
            <p>₹{finalPrice.toLocaleString()}</p>
            {discount > 0 && <span className="badge">{discount}% OFF</span>}
            <button onClick={onAdd}>Add to Cart</button>
        </div>
    );
}

// ── children prop: composition pattern ──
function Card({ title, children, footer }) {
    return (
        <div className="card">
            <div className="card-header"><h3>{title}</h3></div>
            <div className="card-body">{children}</div>
            {footer && <div className="card-footer">{footer}</div>}
        </div>
    );
}

// Usage:
<Card title="User Profile" footer={<button>Save</button>}>
    <p>Name: Alice Johnson</p>
    <p>Role: Senior Developer</p>
    <p>Team: Platform Engineering</p>
</Card>

// ── useState: basic state management ──
import { useState } from "react";

function ShoppingCart() {
    // Each useState manages one piece of state
    const [items, setItems] = useState([]);
    const [coupon, setCoupon] = useState("");
    const [isCheckingOut, setIsCheckingOut] = useState(false);

    // ── Adding items (functional updater: uses prev state) ──
    const addItem = (product) => {
        setItems(prev => {
            const existing = prev.find(i => i.id === product.id);
            if (existing) {
                return prev.map(i =>
                    i.id === product.id ? { ...i, qty: i.qty + 1 } : i
                );
            }
            return [...prev, { ...product, qty: 1 }];
        });
    };

    // ── Removing items ──
    const removeItem = (id) => {
        setItems(prev => prev.filter(i => i.id !== id));
    };

    // ── Derived values (computed from state, not stored in state) ──
    const totalPrice = items.reduce((sum, i) => sum + i.price * i.qty, 0);
    const itemCount = items.reduce((sum, i) => sum + i.qty, 0);

    return (
        <div className="cart">
            <h2>Cart ({itemCount} items)</h2>
            {items.map(item => (
                <div key={item.id} className="cart-item">
                    <span>{item.name} × {item.qty}</span>
                    <span>₹{(item.price * item.qty).toLocaleString()}</span>
                    <button onClick={() => removeItem(item.id)}>Remove</button>
                </div>
            ))}
            <p className="total">Total: ₹{totalPrice.toLocaleString()}</p>
            <input
                value={coupon}
                onChange={e => setCoupon(e.target.value)}
                placeholder="Coupon code"
            />
            <button
                onClick={() => setIsCheckingOut(true)}
                disabled={items.length === 0}
            >
                Checkout
            </button>
        </div>
    );
}

// ── State vs Props summary ──
// Props: <Cart items={items} />     ← passed by parent, read-only
// State: const [items, setItems] = useState([])  ← owned, mutable

// ── WRONG: stale state with direct value ──
// setCount(count + 1); setCount(count + 1); → increments only ONCE
// ── RIGHT: functional updater ──
// setCount(prev => prev + 1); setCount(prev => prev + 1); → increments TWICE

// ── Class lifecycle vs Hook equivalents ──

// CLASS COMPONENT (legacy)
class UserProfile extends React.Component {
    state = { user: null, online: false };

    componentDidMount() {
        // Fetch user data on mount
        fetch(`/api/users/${this.props.userId}`)
            .then(res => res.json())
            .then(user => this.setState({ user }));

        // Subscribe to presence
        this.unsubscribe = presenceService.subscribe(
            this.props.userId,
            status => this.setState({ online: status })
        );
    }

    componentDidUpdate(prevProps) {
        // Re-fetch if userId changes
        if (prevProps.userId !== this.props.userId) {
            fetch(`/api/users/${this.props.userId}`)
                .then(res => res.json())
                .then(user => this.setState({ user }));
        }
    }

    componentWillUnmount() {
        // Cleanup subscription
        this.unsubscribe();
    }

    render() { /* ... */ }
}

// FUNCTIONAL COMPONENT (modern — same behavior, better organized)
import { useState, useEffect } from "react";

function UserProfile({ userId }) {
    const [user, setUser] = useState(null);
    const [online, setOnline] = useState(false);

    // Effect 1: Fetch user data (mount + update when userId changes)
    useEffect(() => {
        let cancelled = false;
        fetch(`/api/users/${userId}`)
            .then(res => res.json())
            .then(data => {
                if (!cancelled) setUser(data);
            });
        return () => { cancelled = true; }; // cleanup on re-run
    }, [userId]); // ← dependency array

    // Effect 2: Presence subscription (mount + unmount cleanup)
    useEffect(() => {
        const unsubscribe = presenceService.subscribe(userId, setOnline);
        return () => unsubscribe(); // cleanup = componentWillUnmount
    }, [userId]);

    if (!user) return <p>Loading...</p>;
    return (
        <div>
            <h2>{user.name} {online ? "🟢" : "⚫"}</h2>
            <p>{user.email}</p>
        </div>
    );
}

// Notice: related logic (fetch + cancel, subscribe + unsubscribe)
// stays TOGETHER in hooks instead of being split across 3 methods

// ── How the Virtual DOM works (conceptual) ──

// Step 1: Your component returns JSX
function Counter({ count }) {
    return (
        <div className="counter">
            <h2>Count: {count}</h2>
            <p className="label">Current value</p>
        </div>
    );
}

// Step 2: React converts JSX to a Virtual DOM object
// When count = 5, the VDOM looks like:
const vdom = {
    type: "div",
    props: { className: "counter" },
    children: [
        {
            type: "h2",
            props: {},
            children: ["Count: 5"]
        },
        {
            type: "p",
            props: { className: "label" },
            children: ["Current value"]
        }
    ]
};

// Step 3: When count changes to 6, React creates a NEW VDOM:
const newVdom = {
    type: "div",
    props: { className: "counter" },
    children: [
        {
            type: "h2",
            props: {},
            children: ["Count: 6"]  // ← Only this changed
        },
        {
            type: "p",
            props: { className: "label" },
            children: ["Current value"]  // ← Same, skip
        }
    ]
};

// Step 4: React diffs old vs new VDOM
// Result: Only ONE text node needs updating ("5" → "6")
// React patches ONLY that text node in the real DOM
// The <div>, <h2> element, and <p> are NOT touched

// ── Real benefit: batching multiple updates ──
function Dashboard() {
    const [user, setUser] = useState(null);
    const [notifications, setNotifications] = useState([]);
    const [theme, setTheme] = useState("light");

    const handleLogin = async (credentials) => {
        const userData = await login(credentials);
        // React 18 batches ALL these into ONE re-render + ONE DOM update
        setUser(userData);
        setNotifications(userData.notifications);
        setTheme(userData.preferredTheme);
        // Without VDOM: 3 separate DOM updates
        // With VDOM: 1 diffed DOM update
    };
}

// ── Controlled Component — React owns the value ──
import { useState } from "react";

function RegistrationForm() {
    const [form, setForm] = useState({
        email: "",
        password: "",
        confirmPassword: "",
    });
    const [errors, setErrors] = useState({});

    const handleChange = (e) => {
        const { name, value } = e.target;
        setForm(prev => ({ ...prev, [name]: value }));

        // Real-time validation (only possible with controlled inputs)
        if (name === "email" && value && !/\S+@\S+\.\S+/.test(value)) {
            setErrors(prev => ({ ...prev, email: "Invalid email format" }));
        } else if (name === "confirmPassword" && value !== form.password) {
            setErrors(prev => ({ ...prev, confirmPassword: "Passwords don't match" }));
        } else {
            setErrors(prev => ({ ...prev, [name]: "" }));
        }
    };

    const handleSubmit = (e) => {
        e.preventDefault();
        if (Object.values(errors).every(err => !err)) {
            console.log("Submitting:", form);
        }
    };

    return (
        <form onSubmit={handleSubmit}>
            <input
                name="email"
                value={form.email}           // ← controlled by React state
                onChange={handleChange}        // ← every keystroke updates state
                placeholder="Email"
            />
            {errors.email && <span className="error">{errors.email}</span>}

            <input
                name="password"
                type="password"
                value={form.password}
                onChange={handleChange}
            />

            <input
                name="confirmPassword"
                type="password"
                value={form.confirmPassword}
                onChange={handleChange}
            />
            {errors.confirmPassword && <span className="error">{errors.confirmPassword}</span>}

            <button type="submit">Register</button>
        </form>
    );
}

// ── Uncontrolled Component — DOM owns the value ──
import { useRef } from "react";

function SearchForm() {
    const inputRef = useRef(null);

    const handleSubmit = (e) => {
        e.preventDefault();
        const query = inputRef.current.value; // ← read from DOM directly
        console.log("Searching for:", query);
    };

    return (
        <form onSubmit={handleSubmit}>
            <input
                ref={inputRef}               // ← ref to DOM node
                defaultValue=""               // ← defaultValue, NOT value
                placeholder="Search..."
            />
            <button type="submit">Search</button>
        </form>
    );
}

// ── File input — always uncontrolled ──
function FileUpload() {
    const fileRef = useRef(null);
    const handleUpload = () => {
        const file = fileRef.current.files[0];
        console.log("File:", file.name, file.size);
    };
    return <input type="file" ref={fileRef} onChange={handleUpload} />;
}

// ── Correct: using unique, stable IDs as keys ──
function TodoList({ todos, onToggle, onDelete }) {
    return (
        <ul>
            {todos.map(todo => (
                <li key={todo.id}>  {/* ← stable unique ID from database */}
                    <input
                        type="checkbox"
                        checked={todo.done}
                        onChange={() => onToggle(todo.id)}
                    />
                    <span>{todo.text}</span>
                    <button onClick={() => onDelete(todo.id)}>Delete</button>
                </li>
            ))}
        </ul>
    );
}

// ── Wrong: using index as key with dynamic lists ──
function BrokenTodoList({ todos }) {
    return (
        <ul>
            {todos.map((todo, index) => (
                <li key={index}>  {/* ← BAD for dynamic lists! */}
                    <input type="checkbox" />
                    <span>{todo.text}</span>
                </li>
            ))}
        </ul>
    );
}
// Problem: If you delete item at index 1, item at index 2 becomes index 1.
// React thinks index 1 still exists → reuses its DOM node (with old checkbox state!)
// Result: wrong checkboxes appear checked after deletion.

// ── What happens during reconciliation ──
// Before delete: [{id:"a",text:"Buy milk"}, {id:"b",text:"Walk dog"}, {id:"c",text:"Code"}]
// Delete "Walk dog"
// After: [{id:"a",text:"Buy milk"}, {id:"c",text:"Code"}]

// WITH key={todo.id}:
// React sees: key="a" still exists → keep DOM node
//             key="b" is gone → remove DOM node
//             key="c" still exists → keep DOM node
// Result: 1 DOM removal, 0 re-renders ✅

// WITH key={index}:
// React sees: index 0 text changed? No → keep (correct)
//             index 1 text "Walk dog"→"Code" → UPDATE DOM (wrong!)
//             index 2 is gone → remove (was "Code", already moved!)
// Result: unnecessary DOM updates + potential state bugs ❌

// ── Generating keys when data has no ID ──
// Option 1: Generate ID when data is created (not during render)
const addTodo = (text) => {
    setTodos(prev => [...prev, {
        id: crypto.randomUUID(),  // ← generated ONCE, stable
        text,
        done: false,
    }]);
};

// ── React event handling basics ──
function InteractiveForm() {
    const [formData, setFormData] = useState({ name: "", email: "" });

    // Event handler — receives SyntheticEvent
    const handleChange = (e) => {
        const { name, value } = e.target;
        setFormData(prev => ({ ...prev, [name]: value }));
    };

    // Preventing default behavior
    const handleSubmit = (e) => {
        e.preventDefault(); // ← Must call explicitly. return false does NOT work.
        console.log("Form submitted:", formData);
    };

    // Passing arguments to handlers
    const handleItemClick = (itemId, e) => {
        e.stopPropagation(); // Works like vanilla JS
        console.log("Clicked item:", itemId);
    };

    return (
        <form onSubmit={handleSubmit}>
            {/* camelCase event names, function reference (not string) */}
            <input
                name="name"
                value={formData.name}
                onChange={handleChange}
                onFocus={() => console.log("Name focused")}
                onBlur={() => console.log("Name blurred")}
            />
            <input
                name="email"
                type="email"
                value={formData.email}
                onChange={handleChange}
            />
            <button type="submit">Submit</button>

            {/* Passing arguments: wrap in arrow function */}
            <ul>
                {["item-1", "item-2", "item-3"].map(id => (
                    <li key={id} onClick={(e) => handleItemClick(id, e)}>
                        {id}
                    </li>
                ))}
            </ul>
        </form>
    );
}

// ── Vanilla JS vs React comparison ──
// Vanilla JS:
// <button onclick="handleClick()">Click</button>
// document.getElementById("btn").addEventListener("click", handleClick);

// React:
// <button onClick={handleClick}>Click</button>
// React attaches ONE listener at root, delegates to correct handler

// ── Event delegation diagram ──
// Vanilla: 100 buttons = 100 event listeners in memory
// React:   100 buttons = 1 root listener + delegation lookup
//          More memory-efficient for large lists

// ── Common events ──
// onClick, onChange, onSubmit, onFocus, onBlur,
// onKeyDown, onKeyUp, onMouseEnter, onMouseLeave,
// onScroll, onDrag, onDrop, onTouchStart, onTouchEnd

// ── Pattern 1: Data fetching with cleanup ──
import { useState, useEffect } from "react";

function UserProfile({ userId }) {
    const [user, setUser] = useState(null);
    const [loading, setLoading] = useState(true);
    const [error, setError] = useState(null);

    useEffect(() => {
        let cancelled = false; // ← prevents setting state on unmounted component
        setLoading(true);
        setError(null);

        fetch(`/api/users/${userId}`)
            .then(res => {
                if (!res.ok) throw new Error(`HTTP ${res.status}`);
                return res.json();
            })
            .then(data => {
                if (!cancelled) {
                    setUser(data);
                    setLoading(false);
                }
            })
            .catch(err => {
                if (!cancelled) {
                    setError(err.message);
                    setLoading(false);
                }
            });

        return () => { cancelled = true; }; // ← cleanup: ignore stale responses
    }, [userId]); // ← re-fetches when userId changes

    if (loading) return <p>Loading...</p>;
    if (error) return <p>Error: {error}</p>;
    return <h2>{user.name}</h2>;
}

// ── Pattern 2: Event listener with cleanup ──
function WindowSize() {
    const [size, setSize] = useState({
        width: window.innerWidth,
        height: window.innerHeight,
    });

    useEffect(() => {
        const handleResize = () => {
            setSize({ width: window.innerWidth, height: window.innerHeight });
        };
        window.addEventListener("resize", handleResize);
        return () => window.removeEventListener("resize", handleResize); // cleanup!
    }, []); // ← empty array = run once on mount

    return <p>{size.width} × {size.height}</p>;
}

// ── Pattern 3: Timer with cleanup ──
function Countdown({ seconds }) {
    const [remaining, setRemaining] = useState(seconds);

    useEffect(() => {
        if (remaining <= 0) return; // no timer needed
        const timer = setInterval(() => {
            setRemaining(prev => prev - 1);
        }, 1000);
        return () => clearInterval(timer); // cleanup on unmount or re-run
    }, [remaining]);

    return <p>{remaining}s remaining</p>;
}

// ── Pattern 4: Document title (no cleanup needed) ──
function PageTitle({ title }) {
    useEffect(() => {
        document.title = title;
    }, [title]);
    return null;
}

// ── Step 1: Create Context ──
import { createContext, useContext, useState } from "react";

const ThemeContext = createContext({
    theme: "light",
    toggleTheme: () => {},
});

// ── Step 2: Provider — wraps app and provides value ──
function ThemeProvider({ children }) {
    const [theme, setTheme] = useState("light");

    const toggleTheme = () => {
        setTheme(prev => prev === "light" ? "dark" : "light");
    };

    return (
        <ThemeContext.Provider value={{ theme, toggleTheme }}>
            {children}
        </ThemeContext.Provider>
    );
}

// ── Step 3: Consume in any nested component ──
function Navbar() {
    const { theme, toggleTheme } = useContext(ThemeContext);
    return (
        <nav className={`navbar navbar-${theme}`}>
            <h1>My App</h1>
            <button onClick={toggleTheme}>
                {theme === "light" ? "🌙 Dark" : "☀️ Light"}
            </button>
        </nav>
    );
}

function Sidebar() {
    const { theme } = useContext(ThemeContext);
    return <aside className={`sidebar sidebar-${theme}`}>Sidebar</aside>;
}

// ── App: wrap with Provider ──
function App() {
    return (
        <ThemeProvider>
            <Navbar />         {/* ← accesses theme directly */}
            <main>
                <Sidebar />    {/* ← accesses theme directly */}
                <Content />    {/* ← doesn't need theme? doesn't useContext */}
            </main>
        </ThemeProvider>
    );
}
// No prop drilling! Theme is available everywhere without passing
// through App → main → Sidebar → etc.

// ── Custom hook for cleaner API ──
function useTheme() {
    const context = useContext(ThemeContext);
    if (!context) {
        throw new Error("useTheme must be used within a ThemeProvider");
    }
    return context;
}

// Usage: const { theme, toggleTheme } = useTheme();

// ── Multiple contexts (common pattern) ──
function App() {
    return (
        <AuthProvider>
            <ThemeProvider>
                <LocaleProvider>
                    <Router />
                </LocaleProvider>
            </ThemeProvider>
        </AuthProvider>
    );
}

// ── useMemo: cache expensive computation ──
import { useState, useMemo, useCallback } from "react";

function EmployeeDirectory({ employees }) {
    const [search, setSearch] = useState("");
    const [sortBy, setSortBy] = useState("name");
    const [theme, setTheme] = useState("light");

    // ✅ useMemo — recalculates ONLY when employees, search, or sortBy change
    // Changing theme does NOT re-filter/re-sort the 10,000 employee list
    const filteredEmployees = useMemo(() => {
        console.log("Filtering and sorting..."); // see when it runs
        return employees
            .filter(emp =>
                emp.name.toLowerCase().includes(search.toLowerCase()) ||
                emp.department.toLowerCase().includes(search.toLowerCase())
            )
            .sort((a, b) => a[sortBy].localeCompare(b[sortBy]));
    }, [employees, search, sortBy]);

    // ✅ useCallback — same function reference between renders
    // Prevents EmployeeCard from re-rendering when theme changes
    const handlePromote = useCallback((empId) => {
        fetch(`/api/employees/${empId}/promote`, { method: "POST" })
            .then(res => res.json())
            .then(data => console.log("Promoted:", data));
    }, []); // no dependencies — function doesn't use any reactive values

    return (
        <div className={`directory ${theme}`}>
            <input
                value={search}
                onChange={e => setSearch(e.target.value)}
                placeholder="Search employees..."
            />
            <button onClick={() => setTheme(t => t === "light" ? "dark" : "light")}>
                Toggle Theme
            </button>
            <p>{filteredEmployees.length} results</p>
            {filteredEmployees.map(emp => (
                <EmployeeCard
                    key={emp.id}
                    employee={emp}
                    onPromote={handlePromote}  // ← stable reference
                />
            ))}
        </div>
    );
}

// ── React.memo: only re-renders if props change ──
const EmployeeCard = React.memo(function EmployeeCard({ employee, onPromote }) {
    console.log("Rendering:", employee.name);
    return (
        <div className="emp-card">
            <h3>{employee.name}</h3>
            <p>{employee.department}</p>
            <button onClick={() => onPromote(employee.id)}>Promote</button>
        </div>
    );
});
// Without useCallback: onPromote is a new function every render →
//   React.memo sees "props changed" → re-renders ALL 10,000 cards
// With useCallback: onPromote is the same reference →
//   React.memo sees "props unchanged" → skips re-render ✅

// ── Summary ──
// useMemo(() => value, [deps])    → caches the VALUE
// useCallback(fn, [deps])         → caches the FUNCTION
// useCallback(fn, deps) === useMemo(() => fn, deps)

// ── Pattern 1: Ternary — if/else ──
function AuthButton({ isLoggedIn, onLogin, onLogout }) {
    return isLoggedIn
        ? <button onClick={onLogout}>Logout</button>
        : <button onClick={onLogin}>Login</button>;
}

// ── Pattern 2: && — render or nothing ──
function Notifications({ messages }) {
    return (
        <div>
            <h2>Inbox</h2>
            {messages.length > 0 && (
                <span className="badge">{messages.length} new</span>
            )}
            {/* ⚠️ WRONG: {messages.length && <Badge />}
                If length is 0, it renders "0" on screen! */}
        </div>
    );
}

// ── Pattern 3: Early return — guard clauses ──
function UserProfile({ user, loading, error }) {
    if (loading) return <Skeleton />;
    if (error) return <ErrorMessage message={error} />;
    if (!user) return <p>No user found</p>;

    // Happy path — only reached if all checks pass
    return (
        <div className="profile">
            <img src={user.avatar} alt={user.name} />
            <h2>{user.name}</h2>
            <p>{user.bio}</p>
        </div>
    );
}

// ── Pattern 4: Object map — cleaner than switch ──
function StatusIcon({ status }) {
    const icons = {
        pending:  <span className="icon">⏳ Pending</span>,
        active:   <span className="icon">✅ Active</span>,
        inactive: <span className="icon">⚫ Inactive</span>,
        banned:   <span className="icon">🚫 Banned</span>,
    };
    return icons[status] || <span className="icon">❓ Unknown</span>;
}

// ── Pattern 5: Rendering lists conditionally ──
function Dashboard({ user }) {
    return (
        <div>
            <h1>Welcome, {user.name}</h1>

            {/* Show admin panel only for admins */}
            {user.role === "admin" && <AdminPanel />}

            {/* Different content based on subscription */}
            {user.plan === "free" ? (
                <UpgradeBanner />
            ) : (
                <PremiumFeatures plan={user.plan} />
            )}

            {/* Nested conditions — use early return or extract component */}
            {user.notifications.length > 0 ? (
                <NotificationList items={user.notifications} />
            ) : (
                <p>No new notifications</p>
            )}
        </div>
    );
}

// ── HOC Pattern: withLoading ──
function withLoading(WrappedComponent) {
    // Return a new component
    return function WithLoadingComponent({ isLoading, ...rest }) {
        if (isLoading) {
            return (
                <div className="loading-wrapper">
                    <div className="spinner" />
                    <p>Loading...</p>
                </div>
            );
        }
        return <WrappedComponent {...rest} />;  // ← pass through all other props
    };
}

// Usage:
const UserListWithLoading = withLoading(UserList);
// <UserListWithLoading isLoading={true} users={users} />

// ── HOC Pattern: withAuth ──
function withAuth(WrappedComponent) {
    return function WithAuthComponent(props) {
        const { user, loading } = useAuth();

        if (loading) return <Spinner />;
        if (!user) return <Navigate to="/login" />;

        return <WrappedComponent {...props} user={user} />;
    };
}

const ProtectedDashboard = withAuth(Dashboard);
// <ProtectedDashboard /> — automatically redirects if not logged in

// ── Modern alternative: Custom Hook (preferred) ──
// Instead of HOC:
// const EnhancedComponent = withWindowSize(MyComponent);

// Use a custom hook:
function useWindowSize() {
    const [size, setSize] = useState({
        width: window.innerWidth,
        height: window.innerHeight,
    });

    useEffect(() => {
        const handleResize = () => {
            setSize({ width: window.innerWidth, height: window.innerHeight });
        };
        window.addEventListener("resize", handleResize);
        return () => window.removeEventListener("resize", handleResize);
    }, []);

    return size;
}

// Usage — no wrapper component needed:
function MyComponent() {
    const { width, height } = useWindowSize();
    return <p>Window: {width} × {height}</p>;
}

// ── HOC Composition (wrapper hell) ──
// This is why hooks are preferred:
// const Enhanced = withRouter(withAuth(withTheme(withLoading(MyComponent))));
// vs hooks:
// function MyComponent() {
//     const router = useRouter();
//     const auth = useAuth();
//     const theme = useTheme();
//     const loading = useLoading();
// }

// ── Custom Hook: useLocalStorage ──
import { useState, useEffect } from "react";

function useLocalStorage(key, initialValue) {
    // Initialize from localStorage or fallback
    const [value, setValue] = useState(() => {
        try {
            const stored = localStorage.getItem(key);
            return stored !== null ? JSON.parse(stored) : initialValue;
        } catch {
            return initialValue;
        }
    });

    // Sync to localStorage whenever value changes
    useEffect(() => {
        try {
            localStorage.setItem(key, JSON.stringify(value));
        } catch (err) {
            console.error("Failed to save to localStorage:", err);
        }
    }, [key, value]);

    return [value, setValue]; // same API as useState
}

// Usage — any component can persist state:
function Settings() {
    const [theme, setTheme] = useLocalStorage("theme", "light");
    const [fontSize, setFontSize] = useLocalStorage("fontSize", 16);
    // State survives page refresh!
    return (
        <div>
            <button onClick={() => setTheme(t => t === "light" ? "dark" : "light")}>
                Theme: {theme}
            </button>
            <input type="range" min={12} max={24}
                value={fontSize} onChange={e => setFontSize(Number(e.target.value))} />
        </div>
    );
}

// ── Custom Hook: useFetch ──
function useFetch(url) {
    const [data, setData] = useState(null);
    const [loading, setLoading] = useState(true);
    const [error, setError] = useState(null);

    useEffect(() => {
        let cancelled = false;
        setLoading(true);
        setError(null);

        fetch(url)
            .then(res => {
                if (!res.ok) throw new Error(`HTTP ${res.status}`);
                return res.json();
            })
            .then(json => { if (!cancelled) { setData(json); setLoading(false); } })
            .catch(err => { if (!cancelled) { setError(err.message); setLoading(false); } });

        return () => { cancelled = true; };
    }, [url]);

    return { data, loading, error };
}

// Usage:
function UserProfile({ userId }) {
    const { data: user, loading, error } = useFetch(`/api/users/${userId}`);
    if (loading) return <Spinner />;
    if (error) return <p>Error: {error}</p>;
    return <h2>{user.name}</h2>;
}

// ── Custom Hook: useDebounce ──
function useDebounce(value, delay = 300) {
    const [debounced, setDebounced] = useState(value);
    useEffect(() => {
        const timer = setTimeout(() => setDebounced(value), delay);
        return () => clearTimeout(timer);
    }, [value, delay]);
    return debounced;
}

// Usage:
function Search() {
    const [query, setQuery] = useState("");
    const debouncedQuery = useDebounce(query, 500);
    const { data } = useFetch(
        debouncedQuery ? `/api/search?q=${debouncedQuery}` : null
    );
    return <input value={query} onChange={e => setQuery(e.target.value)} />;
}

// ── React Router v6 Setup ──
import { BrowserRouter, Routes, Route, Link, Outlet,
         useParams, useNavigate, useSearchParams, Navigate } from "react-router-dom";

function App() {
    return (
        <BrowserRouter>
            <Routes>
                {/* Public routes */}
                <Route path="/" element={<Layout />}>
                    <Route index element={<Home />} />
                    <Route path="about" element={<About />} />
                    <Route path="products" element={<Products />} />
                    <Route path="products/:productId" element={<ProductDetail />} />

                    {/* Protected routes — nested under auth check */}
                    <Route element={<ProtectedRoute />}>
                        <Route path="dashboard" element={<Dashboard />} />
                        <Route path="settings" element={<Settings />} />
                    </Route>

                    {/* 404 catch-all */}
                    <Route path="*" element={<NotFound />} />
                </Route>
            </Routes>
        </BrowserRouter>
    );
}

// ── Layout with shared navbar ──
function Layout() {
    return (
        <div>
            <nav>
                <Link to="/">Home</Link>
                <Link to="/about">About</Link>
                <Link to="/products">Products</Link>
                <Link to="/dashboard">Dashboard</Link>
            </nav>
            <main>
                <Outlet />  {/* ← Child routes render here */}
            </main>
        </div>
    );
}

// ── URL Parameters ──
function ProductDetail() {
    const { productId } = useParams(); // reads :productId from URL
    const { data: product } = useFetch(`/api/products/${productId}`);
    return <h2>{product?.name}</h2>;
}

// ── Programmatic Navigation ──
function LoginForm() {
    const navigate = useNavigate();

    const handleLogin = async (credentials) => {
        await login(credentials);
        navigate("/dashboard", { replace: true }); // replace: can't go back to login
    };
    return <form onSubmit={handleLogin}>...</form>;
}

// ── Protected Route Pattern ──
function ProtectedRoute() {
    const { user, loading } = useAuth();
    if (loading) return <Spinner />;
    if (!user) return <Navigate to="/login" replace />;
    return <Outlet />;  // render child routes if authenticated
}

// ── Search Params ──
function Products() {
    const [searchParams, setSearchParams] = useSearchParams();
    const page = Number(searchParams.get("page")) || 1;
    const category = searchParams.get("category") || "all";

    return (
        <div>
            <button onClick={() => setSearchParams({ page: page + 1, category })}>
                Next Page
            </button>
            {/* URL becomes /products?page=2&category=all */}
        </div>
    );
}

// ── Use Case 1: DOM access — focus management ──
import { useRef, useEffect, useState } from "react";

function SearchBar() {
    const inputRef = useRef(null);

    useEffect(() => {
        inputRef.current.focus(); // auto-focus on mount
    }, []);

    const handleClear = () => {
        inputRef.current.value = "";
        inputRef.current.focus(); // re-focus after clearing
    };

    return (
        <div>
            <input ref={inputRef} placeholder="Search..." />
            <button onClick={handleClear}>Clear</button>
        </div>
    );
}

// ── Use Case 2: Mutable value — timer ID ──
function Stopwatch() {
    const [seconds, setSeconds] = useState(0);
    const [running, setRunning] = useState(false);
    const intervalRef = useRef(null); // ← timer ID, no re-render needed

    const start = () => {
        if (running) return;
        setRunning(true);
        intervalRef.current = setInterval(() => {
            setSeconds(prev => prev + 1);
        }, 1000);
    };

    const stop = () => {
        clearInterval(intervalRef.current);
        setRunning(false);
    };

    const reset = () => {
        clearInterval(intervalRef.current);
        setRunning(false);
        setSeconds(0);
    };

    // Cleanup on unmount
    useEffect(() => {
        return () => clearInterval(intervalRef.current);
    }, []);

    return (
        <div>
            <h2>{seconds}s</h2>
            <button onClick={start}>Start</button>
            <button onClick={stop}>Stop</button>
            <button onClick={reset}>Reset</button>
        </div>
    );
}

// ── Use Case 3: Previous value ──
function usePrevious(value) {
    const ref = useRef();
    useEffect(() => {
        ref.current = value;
    }, [value]);
    return ref.current; // returns value from PREVIOUS render
}

function PriceDisplay({ price }) {
    const prevPrice = usePrevious(price);
    const trend = price > prevPrice ? "📈" : price < prevPrice ? "📉" : "➡️";
    return <p>{trend} ₹{price}</p>;
}

// ── Use Case 4: Counting renders (without causing more renders) ──
function DebugComponent() {
    const renderCount = useRef(0);
    renderCount.current += 1; // mutate ref = no re-render

    console.log(`Rendered ${renderCount.current} times`);
    // If you used useState here, incrementing would cause
    // another render → increment → render → INFINITE LOOP
}

// ── Pattern: Multi-field form with validation ──
import { useState } from "react";

function ContactForm() {
    const [form, setForm] = useState({
        name: "", email: "", message: "",
    });
    const [errors, setErrors] = useState({});
    const [touched, setTouched] = useState({});
    const [submitting, setSubmitting] = useState(false);

    // Single handler for all fields (computed property name)
    const handleChange = (e) => {
        const { name, value } = e.target;
        setForm(prev => ({ ...prev, [name]: value }));
        // Re-validate on change after field was touched
        if (touched[name]) {
            setErrors(prev => ({ ...prev, [name]: validate(name, value) }));
        }
    };

    // Mark field as touched on blur, validate
    const handleBlur = (e) => {
        const { name, value } = e.target;
        setTouched(prev => ({ ...prev, [name]: true }));
        setErrors(prev => ({ ...prev, [name]: validate(name, value) }));
    };

    // Field-level validation
    const validate = (name, value) => {
        switch (name) {
            case "name":
                return value.trim().length < 2 ? "Name must be at least 2 characters" : "";
            case "email":
                return !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value) ? "Invalid email address" : "";
            case "message":
                return value.trim().length < 10 ? "Message must be at least 10 characters" : "";
            default: return "";
        }
    };

    // Full form validation on submit
    const validateAll = () => {
        const newErrors = {};
        Object.keys(form).forEach(key => {
            newErrors[key] = validate(key, form[key]);
        });
        setErrors(newErrors);
        setTouched({ name: true, email: true, message: true });
        return Object.values(newErrors).every(e => !e);
    };

    const handleSubmit = async (e) => {
        e.preventDefault(); // ← prevent page reload!
        if (!validateAll()) return;

        setSubmitting(true);
        try {
            await fetch("/api/contact", {
                method: "POST",
                headers: { "Content-Type": "application/json" },
                body: JSON.stringify(form),
            });
            alert("Message sent!");
            setForm({ name: "", email: "", message: "" });
            setTouched({});
        } catch (err) {
            setErrors({ submit: "Failed to send. Please try again." });
        } finally {
            setSubmitting(false);
        }
    };

    return (
        <form onSubmit={handleSubmit} noValidate>
            <div>
                <label htmlFor="name">Name</label>
                <input id="name" name="name"
                    value={form.name} onChange={handleChange} onBlur={handleBlur}
                    className={errors.name ? "input-error" : ""} />
                {touched.name && errors.name && <span className="error">{errors.name}</span>}
            </div>

            <div>
                <label htmlFor="email">Email</label>
                <input id="email" name="email" type="email"
                    value={form.email} onChange={handleChange} onBlur={handleBlur} />
                {touched.email && errors.email && <span className="error">{errors.email}</span>}
            </div>

            <div>
                <label htmlFor="message">Message</label>
                <textarea id="message" name="message" rows={4}
                    value={form.message} onChange={handleChange} onBlur={handleBlur} />
                {touched.message && errors.message && <span className="error">{errors.message}</span>}
            </div>

            {errors.submit && <p className="error">{errors.submit}</p>}
            <button type="submit" disabled={submitting}>
                {submitting ? "Sending..." : "Send Message"}
            </button>
        </form>
    );
}

// ── useReducer: Shopping cart with complex state logic ──
import { useReducer } from "react";

// Define initial state
const initialState = {
    items: [],
    coupon: null,
    discount: 0,
    status: "idle", // idle | processing | success | error
    error: null,
};

// Reducer: pure function (state, action) → newState
function cartReducer(state, action) {
    switch (action.type) {
        case "ADD_ITEM": {
            const existing = state.items.find(i => i.id === action.payload.id);
            if (existing) {
                return {
                    ...state,
                    items: state.items.map(i =>
                        i.id === action.payload.id
                            ? { ...i, qty: i.qty + 1 }
                            : i
                    ),
                };
            }
            return { ...state, items: [...state.items, { ...action.payload, qty: 1 }] };
        }
        case "REMOVE_ITEM":
            return { ...state, items: state.items.filter(i => i.id !== action.payload) };

        case "UPDATE_QTY":
            return {
                ...state,
                items: state.items.map(i =>
                    i.id === action.payload.id
                        ? { ...i, qty: Math.max(1, action.payload.qty) }
                        : i
                ),
            };
        case "APPLY_COUPON":
            return { ...state, coupon: action.payload.code, discount: action.payload.discount };

        case "CHECKOUT_START":
            return { ...state, status: "processing", error: null };

        case "CHECKOUT_SUCCESS":
            return { ...initialState, status: "success" }; // reset cart

        case "CHECKOUT_ERROR":
            return { ...state, status: "error", error: action.payload };

        default:
            throw new Error(`Unknown action: ${action.type}`);
    }
}

// Component using useReducer
function ShoppingCart() {
    const [state, dispatch] = useReducer(cartReducer, initialState);
    const { items, coupon, discount, status, error } = state;

    const subtotal = items.reduce((sum, i) => sum + i.price * i.qty, 0);
    const total = subtotal - (subtotal * discount / 100);

    const handleCheckout = async () => {
        dispatch({ type: "CHECKOUT_START" });
        try {
            await fetch("/api/checkout", {
                method: "POST",
                body: JSON.stringify({ items, coupon }),
            });
            dispatch({ type: "CHECKOUT_SUCCESS" });
        } catch (err) {
            dispatch({ type: "CHECKOUT_ERROR", payload: err.message });
        }
    };

    return (
        <div>
            {items.map(item => (
                <div key={item.id}>
                    <span>{item.name} × {item.qty}</span>
                    <button onClick={() => dispatch({
                        type: "UPDATE_QTY",
                        payload: { id: item.id, qty: item.qty + 1 }
                    })}>+</button>
                    <button onClick={() => dispatch({
                        type: "REMOVE_ITEM", payload: item.id
                    })}>Remove</button>
                </div>
            ))}
            <p>Total: ₹{total.toLocaleString()}</p>
            {error && <p className="error">{error}</p>}
            <button onClick={handleCheckout} disabled={status === "processing"}>
                {status === "processing" ? "Processing..." : "Checkout"}
            </button>
        </div>
    );
}

// ── Comparison: same logic with useState would need 5 separate setState calls
// and multiple if/else blocks scattered across handlers.
// useReducer centralizes ALL state transitions in one place.

// ── Reconciliation heuristics in action ──

// Heuristic 1: Different types → full remount
// Before:
<div className="old"><Counter /></div>
// After:
<section className="new"><Counter /></section>
// React: div ≠ section → destroy <div> and <Counter> state →
// create new <section> and fresh <Counter>

// Same type → update in place
// Before:
<div className="old" style={{ color: "red" }} />
// After:
<div className="new" style={{ color: "blue" }} />
// React: div === div → update className and style only

// Heuristic 2: Keys for list reconciliation
// Before: [A, B, C, D]
// After:  [E, A, B, C, D]  (E inserted at top)

// WITHOUT keys (by index):
// index 0: A→E (update), index 1: B→A (update), index 2: C→B (update)...
// Result: ALL 5 elements updated ❌

// WITH keys:
// key="a" still exists → move, key="e" is new → insert
// Result: 1 insertion, 0 updates ✅

// ── Fiber tree structure (conceptual) ──
// Each fiber node contains:
const fiber = {
    type: "div",              // element type
    key: null,                // reconciliation key
    stateNode: domElement,    // actual DOM node
    child: childFiber,        // first child
    sibling: siblingFiber,    // next sibling
    return: parentFiber,      // parent
    pendingProps: {},         // new props
    memoizedProps: {},        // current props
    memoizedState: {},        // current state
    effectTag: "UPDATE",      // what to do in commit phase
    lanes: 0b0001,           // priority lanes (React 18)
};

// ── Fiber work loop (simplified) ──
function workLoop(deadline) {
    let currentFiber = nextUnitOfWork;

    while (currentFiber && deadline.timeRemaining() > 1) {
        // Process one fiber unit
        currentFiber = performUnitOfWork(currentFiber);
    }

    if (!currentFiber && pendingCommit) {
        // All work done → commit to DOM (synchronous, uninterruptible)
        commitRoot(pendingCommit);
    } else {
        // Yield to browser → resume later
        requestIdleCallback(workLoop);
    }
}

// ── Why Fiber matters for users ──
// Old stack reconciler: render 10,000 items = 200ms frozen UI
// Fiber: render in chunks → browser handles clicks between chunks
// User sees: responsive UI even during heavy renders

// ── Error Boundary (class component — required) ──
import React from "react";

class ErrorBoundary extends React.Component {
    constructor(props) {
        super(props);
        this.state = { hasError: false, error: null, errorInfo: null };
    }

    static getDerivedStateFromError(error) {
        // Update state to show fallback UI on next render
        return { hasError: true, error };
    }

    componentDidCatch(error, errorInfo) {
        // Log to error reporting service (Sentry, LogRocket, etc.)
        console.error("Error caught by boundary:", error);
        console.error("Component stack:", errorInfo.componentStack);

        // In production:
        // errorService.log({ error, componentStack: errorInfo.componentStack });
    }

    render() {
        if (this.state.hasError) {
            // Custom fallback UI
            return this.props.fallback || (
                <div className="error-fallback">
                    <h2>Something went wrong</h2>
                    <p>{this.state.error?.message}</p>
                    <button onClick={() => this.setState({ hasError: false, error: null })}>
                        Try Again
                    </button>
                </div>
            );
        }
        return this.props.children;
    }
}

// ── Usage: Strategic placement ──
function App() {
    return (
        <ErrorBoundary fallback={<h1>App crashed. Please refresh.</h1>}>
            <header>
                <Navbar />
            </header>
            <main>
                {/* Isolate sections — sidebar crash doesn't kill main content */}
                <ErrorBoundary fallback={<p>Sidebar unavailable</p>}>
                    <Sidebar />
                </ErrorBoundary>

                <ErrorBoundary fallback={<p>Failed to load content</p>}>
                    <Dashboard />
                </ErrorBoundary>
            </main>
        </ErrorBoundary>
    );
}

// ── Reusable wrapper with reset capability ──
function ErrorFallback({ error, resetError }) {
    return (
        <div role="alert" className="error-card">
            <h3>⚠️ Something went wrong</h3>
            <pre>{error.message}</pre>
            <button onClick={resetError}>Retry</button>
        </div>
    );
}

// ── Event handler errors: use try/catch (NOT caught by boundary) ──
function DeleteButton({ itemId }) {
    const [error, setError] = useState(null);

    const handleDelete = async () => {
        try {
            await fetch(`/api/items/${itemId}`, { method: "DELETE" });
        } catch (err) {
            setError(err.message); // Handle manually — boundary won't catch this
        }
    };

    return (
        <>
            <button onClick={handleDelete}>Delete</button>
            {error && <p className="error">{error}</p>}
        </>
    );
}

// ── Modal using Portal ──
import { createPortal } from "react-dom";
import { useState, useEffect } from "react";

function Modal({ isOpen, onClose, title, children }) {
    // Prevent background scrolling when modal is open
    useEffect(() => {
        if (isOpen) {
            document.body.style.overflow = "hidden";
        }
        return () => { document.body.style.overflow = ""; };
    }, [isOpen]);

    if (!isOpen) return null;

    // Render into #modal-root (a div in index.html outside #root)
    return createPortal(
        <div className="modal-overlay" onClick={onClose}>
            <div className="modal-content"
                 onClick={e => e.stopPropagation()} // prevent closing on content click
                 role="dialog"
                 aria-modal="true"
                 aria-labelledby="modal-title">
                <div className="modal-header">
                    <h2 id="modal-title">{title}</h2>
                    <button onClick={onClose} aria-label="Close">✕</button>
                </div>
                <div className="modal-body">{children}</div>
            </div>
        </div>,
        document.getElementById("modal-root") // ← renders HERE in the DOM
    );
}

// ── Usage ──
function ProductPage() {
    const [showModal, setShowModal] = useState(false);

    return (
        <div style={{ overflow: "hidden", height: "300px" }}>
            {/* This div clips overflow — but the modal escapes via portal! */}
            <h2>Product Details</h2>
            <button onClick={() => setShowModal(true)}>Quick View</button>

            <Modal isOpen={showModal} onClose={() => setShowModal(false)} title="Product Preview">
                <img src="/product.jpg" alt="Product" />
                <p>This modal renders outside the overflow:hidden container</p>
                <button onClick={() => setShowModal(false)}>Close</button>
            </Modal>
        </div>
    );
}

// index.html:
// <body>
//   <div id="root"></div>         ← React app renders here
//   <div id="modal-root"></div>   ← Portals render here
// </body>

// ── Event bubbling through React tree (not DOM tree) ──
// Even though Modal is in #modal-root in the DOM,
// a click inside Modal bubbles up to ProductPage in the REACT tree.
// This means onClick handlers on parent React components still fire!

// ── Toast Notification Portal ──
function ToastContainer({ toasts, onDismiss }) {
    return createPortal(
        <div className="toast-container" style={{
            position: "fixed", top: 16, right: 16, zIndex: 9999
        }}>
            {toasts.map(t => (
                <div key={t.id} className={`toast toast-${t.type}`}>
                    <span>{t.message}</span>
                    <button onClick={() => onDismiss(t.id)}>✕</button>
                </div>
            ))}
        </div>,
        document.body
    );
}

// ── Route-level code splitting ──
import { Suspense, lazy } from "react";
import { BrowserRouter, Routes, Route } from "react-router-dom";

// Lazy load each route — separate chunk per page
const Home = lazy(() => import("./pages/Home"));
const Dashboard = lazy(() => import("./pages/Dashboard"));
const Settings = lazy(() => import("./pages/Settings"));
const Analytics = lazy(() => import("./pages/Analytics"));

function App() {
    return (
        <BrowserRouter>
            {/* Suspense wraps lazy components — shows fallback while loading */}
            <Suspense fallback={<PageSkeleton />}>
                <Routes>
                    <Route path="/" element={<Home />} />
                    <Route path="/dashboard" element={<Dashboard />} />
                    <Route path="/settings" element={<Settings />} />
                    <Route path="/analytics" element={<Analytics />} />
                </Routes>
            </Suspense>
        </BrowserRouter>
    );
}

// ── Component-level splitting (heavy components) ──
const RichTextEditor = lazy(() => import("./components/RichTextEditor"));
const ChartWidget = lazy(() => import("./components/ChartWidget"));

function BlogPost({ post }) {
    const [editing, setEditing] = useState(false);

    return (
        <article>
            <h1>{post.title}</h1>
            <p>{post.content}</p>

            {/* Editor only loads when user clicks Edit */}
            {editing && (
                <Suspense fallback={<p>Loading editor...</p>}>
                    <RichTextEditor content={post.content} />
                </Suspense>
            )}

            {/* Chart loaded separately — doesn't block page render */}
            <Suspense fallback={<div className="chart-skeleton" />}>
                <ChartWidget data={post.analytics} />
            </Suspense>
        </article>
    );
}

// ── Named export workaround ──
// If the module uses named exports:
// export function MyChart() { ... }  // named, not default

// Create a re-export wrapper:
const MyChart = lazy(() =>
    import("./charts").then(module => ({ default: module.MyChart }))
);

// ── Preloading for better UX ──
const Settings = lazy(() => import("./pages/Settings"));

// Preload on hover (before user clicks)
function NavLink({ to, children }) {
    const handleMouseEnter = () => {
        if (to === "/settings") {
            import("./pages/Settings"); // starts loading in background
        }
    };

    return (
        <Link to={to} onMouseEnter={handleMouseEnter}>
            {children}
        </Link>
    );
}
// By the time user clicks, the chunk is already loaded → instant navigation

// ── Render Prop Pattern: Mouse Position ──
import { useState, useEffect } from "react";

// Provider component — manages state, delegates rendering
function MouseTracker({ children }) {
    const [position, setPosition] = useState({ x: 0, y: 0 });

    useEffect(() => {
        const handleMove = (e) => {
            setPosition({ x: e.clientX, y: e.clientY });
        };
        window.addEventListener("mousemove", handleMove);
        return () => window.removeEventListener("mousemove", handleMove);
    }, []);

    // Call children as a function, passing state
    return children(position);
}

// Usage — consumer decides what to render
function App() {
    return (
        <MouseTracker>
            {({ x, y }) => (
                <div>
                    <p>Mouse: {x}, {y}</p>
                    <div style={{
                        position: "absolute",
                        left: x - 10,
                        top: y - 10,
                        width: 20,
                        height: 20,
                        borderRadius: "50%",
                        background: "red",
                    }} />
                </div>
            )}
        </MouseTracker>
    );
}

// ── Same logic as Custom Hook (modern approach) ──
function useMousePosition() {
    const [position, setPosition] = useState({ x: 0, y: 0 });

    useEffect(() => {
        const handleMove = (e) => setPosition({ x: e.clientX, y: e.clientY });
        window.addEventListener("mousemove", handleMove);
        return () => window.removeEventListener("mousemove", handleMove);
    }, []);

    return position;
}

// Usage — cleaner, no wrapper component
function App() {
    const { x, y } = useMousePosition();
    return <p>Mouse: {x}, {y}</p>;
}

// ── When render props are STILL useful: Visibility detection ──
function InView({ children, threshold = 0.5 }) {
    const [isVisible, setIsVisible] = useState(false);
    const ref = useRef(null);

    useEffect(() => {
        const observer = new IntersectionObserver(
            ([entry]) => setIsVisible(entry.isIntersecting),
            { threshold }
        );
        if (ref.current) observer.observe(ref.current);
        return () => observer.disconnect();
    }, [threshold]);

    return (
        <div ref={ref}>
            {children(isVisible)}  {/* Consumer decides what to render based on visibility */}
        </div>
    );
}

// Usage:
<InView threshold={0.3}>
    {(isVisible) => isVisible ? <HeavyChart /> : <Placeholder />}
</InView>

// ── Render Prop Hell (why hooks are preferred) ──
// <MouseTracker>
//   {(mouse) => (
//     <Theme>
//       {(theme) => (
//         <Auth>
//           {(user) => (
//             <Component mouse={mouse} theme={theme} user={user} />
//           )}
//         </Auth>
//       )}
//     </Theme>
//   )}
// </MouseTracker>
// vs hooks: 3 lines, zero nesting

// ── Server Component (default in Next.js App Router) ──
// app/products/page.tsx — NO "use client" = Server Component

// Can directly query database — no API route needed!
import { db } from "@/lib/database";

async function ProductsPage() {
    // This runs on the server — SQL never reaches the browser
    const products = await db.query(`
        SELECT id, name, price, image_url
        FROM products
        WHERE active = true
        ORDER BY created_at DESC
        LIMIT 50
    `);

    return (
        <div className="product-grid">
            <h1>Products ({products.length})</h1>
            {products.map(product => (
                // Server Component renders static parts
                <div key={product.id} className="product-card">
                    <img src={product.image_url} alt={product.name} />
                    <h3>{product.name}</h3>
                    <p>₹{product.price.toLocaleString()}</p>

                    {/* Client Component handles interactivity */}
                    <AddToCartButton productId={product.id} />
                </div>
            ))}
        </div>
    );
}

export default ProductsPage;
// Zero JS sent to browser for this component! Only HTML.
// Only AddToCartButton's JS is shipped.

// ── Client Component (needs interactivity) ──
// components/AddToCartButton.tsx
"use client"; // ← This directive makes it a Client Component

import { useState } from "react";

export function AddToCartButton({ productId }) {
    const [added, setAdded] = useState(false);

    const handleAdd = async () => {
        await fetch("/api/cart", {
            method: "POST",
            body: JSON.stringify({ productId }),
        });
        setAdded(true);
    };

    return (
        <button onClick={handleAdd} disabled={added}>
            {added ? "✓ Added" : "Add to Cart"}
        </button>
    );
}
// This component's JS IS sent to the browser (for onClick, useState)

// ── Comparison: SSR vs RSC ──
// SSR Flow:
// 1. Server renders HTML (fast initial paint)
// 2. Browser downloads ALL component JS (big bundle)
// 3. React hydrates HTML (makes it interactive)
// 4. User can now interact
// → Bundle: ProductsPage JS + AddToCartButton JS

// RSC Flow:
// 1. Server runs ProductsPage, sends only HTML + serialized output
// 2. Browser downloads ONLY Client Component JS
// 3. React hydrates only Client Components
// → Bundle: AddToCartButton JS only (ProductsPage = 0 KB!)

// ── Data flow: Server → Client ──
// ✅ Server Component can render Client Component
// ✅ Server Component can pass serializable props to Client Component
// ❌ Client Component CANNOT import Server Component
// ❌ Server Component CANNOT use useState, useEffect, onClick

// ── useTransition: non-blocking search ──
import { useState, useTransition, useDeferredValue } from "react";

function SearchableList({ items }) {
    const [query, setQuery] = useState("");
    const [isPending, startTransition] = useTransition();

    // Urgent: update search input immediately (user sees typed characters)
    // Non-urgent: filter the list (can lag behind without feeling broken)
    const [filteredItems, setFilteredItems] = useState(items);

    const handleSearch = (e) => {
        const value = e.target.value;
        setQuery(value); // ← urgent: updates input instantly

        startTransition(() => {
            // ← non-urgent: React renders this in background
            const filtered = items.filter(item =>
                item.name.toLowerCase().includes(value.toLowerCase())
            );
            setFilteredItems(filtered);
        });
    };

    return (
        <div>
            <input value={query} onChange={handleSearch} placeholder="Search..." />
            {isPending && <p className="loading">Updating results...</p>}
            <ul>
                {filteredItems.map(item => (
                    <li key={item.id}>{item.name}</li>
                ))}
            </ul>
        </div>
    );
}

// ── useDeferredValue: defer expensive child renders ──
function SearchResults({ query }) {
    // deferredQuery lags behind the actual query during heavy renders
    const deferredQuery = useDeferredValue(query);
    const isStale = query !== deferredQuery;

    // ExpensiveList renders with the DEFERRED (old) value first,
    // then re-renders with the current value when ready
    return (
        <div style={{ opacity: isStale ? 0.6 : 1, transition: "opacity 0.2s" }}>
            <ExpensiveList query={deferredQuery} />
        </div>
    );
}

// ── Practical example: Tab switching ──
function TabPanel() {
    const [tab, setTab] = useState("posts");
    const [isPending, startTransition] = useTransition();

    const switchTab = (newTab) => {
        startTransition(() => {
            setTab(newTab); // Non-urgent — old tab stays visible until new one is ready
        });
    };

    return (
        <div>
            <nav>
                <button onClick={() => switchTab("posts")}
                    style={{ opacity: isPending && tab !== "posts" ? 0.7 : 1 }}>
                    Posts
                </button>
                <button onClick={() => switchTab("comments")}
                    style={{ opacity: isPending && tab !== "comments" ? 0.7 : 1 }}>
                    Comments
                </button>
                <button onClick={() => switchTab("analytics")}
                    style={{ opacity: isPending && tab !== "analytics" ? 0.7 : 1 }}>
                    Analytics {/* Heavy component — takes 200ms to render */}
                </button>
            </nav>
            {isPending && <p>Loading tab...</p>}
            {tab === "posts" && <PostsTab />}
            {tab === "comments" && <CommentsTab />}
            {tab === "analytics" && <AnalyticsTab />}
        </div>
    );
}

// ── Automatic Batching (React 18) ──
// Before React 18: updates in setTimeout were NOT batched
// After React 18: ALL updates are batched automatically
setTimeout(() => {
    setCount(c => c + 1);    // React 17: re-render #1
    setFlag(f => !f);        // React 17: re-render #2
    // React 18: ONE batched re-render for both
}, 1000);

// ── forwardRef: Pass ref to inner DOM element ──
import { forwardRef, useRef, useImperativeHandle } from "react";

// Without forwardRef, parent can't access the inner <input>
const TextInput = forwardRef(function TextInput({ label, ...props }, ref) {
    return (
        <div className="form-field">
            <label>{label}</label>
            <input ref={ref} {...props} />  {/* ref forwarded to the <input> */}
        </div>
    );
});

// Parent can now focus the input
function LoginForm() {
    const emailRef = useRef(null);

    useEffect(() => {
        emailRef.current.focus(); // focuses the <input> inside TextInput
    }, []);

    return (
        <form>
            <TextInput ref={emailRef} label="Email" type="email" />
            <TextInput label="Password" type="password" />
            <button type="submit">Login</button>
        </form>
    );
}

// ── useImperativeHandle: Expose custom API ──
const VideoPlayer = forwardRef(function VideoPlayer({ src, poster }, ref) {
    const videoRef = useRef(null);
    const [isPlaying, setIsPlaying] = useState(false);

    // Expose only specific methods — not the entire <video> DOM node
    useImperativeHandle(ref, () => ({
        play() {
            videoRef.current.play();
            setIsPlaying(true);
        },
        pause() {
            videoRef.current.pause();
            setIsPlaying(false);
        },
        seekTo(seconds) {
            videoRef.current.currentTime = seconds;
        },
        getDuration() {
            return videoRef.current.duration;
        },
        // Parent CANNOT access videoRef.current.volume,
        // videoRef.current.playbackRate, etc.
    }), []);

    return (
        <div className="video-wrapper">
            <video ref={videoRef} src={src} poster={poster} />
            <div className="controls">
                <button onClick={() => isPlaying ? ref.current?.pause() : ref.current?.play()}>
                    {isPlaying ? "⏸" : "▶"}
                </button>
            </div>
        </div>
    );
});

// Parent uses the controlled API
function CoursePage() {
    const playerRef = useRef(null);

    const skipToHighlight = () => {
        playerRef.current.seekTo(120); // jump to 2:00
        playerRef.current.play();
    };

    return (
        <div>
            <VideoPlayer ref={playerRef} src="/lesson-1.mp4" poster="/thumb.jpg" />
            <button onClick={skipToHighlight}>Skip to Key Concept</button>
            <button onClick={() => playerRef.current.pause()}>Pause</button>
        </div>
    );
}

// ── React 19: ref as a regular prop (no forwardRef needed) ──
// React 19+:
function TextInput({ label, ref, ...props }) {
    return (
        <div className="form-field">
            <label>{label}</label>
            <input ref={ref} {...props} />  {/* ref is just a prop now! */}
        </div>
    );
}
// <TextInput ref={myRef} label="Email" /> — works without forwardRef

// ── Feature-based folder structure (recommended) ──
/*
src/
├── app/                    # App shell, providers, router
│   ├── App.tsx
│   ├── providers.tsx       # Compose all providers
│   └── router.tsx          # Route declarations
├── features/               # Feature modules (self-contained)
│   ├── auth/
│   │   ├── components/     # LoginForm, SignupForm, AuthGuard
│   │   ├── hooks/          # useAuth, useSession
│   │   ├── api/            # authApi.ts (API calls)
│   │   ├── store/          # authStore.ts (Zustand slice)
│   │   ├── types/          # auth.types.ts
│   │   ├── utils/          # tokenHelpers.ts
│   │   └── index.ts        # Public API (barrel export)
│   ├── dashboard/
│   │   ├── components/
│   │   ├── hooks/
│   │   └── index.ts
│   └── checkout/
│       ├── components/
│       ├── hooks/
│       └── index.ts
├── shared/                 # Cross-feature shared code
│   ├── components/         # Button, Modal, Table, Toast
│   ├── hooks/              # useFetch, useDebounce, useLocalStorage
│   ├── utils/              # formatCurrency, dateHelpers
│   └── types/              # global types
├── lib/                    # Third-party wrappers
│   ├── axios.ts            # Configured Axios instance
│   └── queryClient.ts      # React Query client
└── assets/                 # Images, fonts, global CSS
*/

// ── Barrel export: features/auth/index.ts ──
export { LoginForm } from "./components/LoginForm";
export { useAuth } from "./hooks/useAuth";
export type { User, AuthState } from "./types/auth.types";
// Other features import: import { useAuth, LoginForm } from "@/features/auth";

// ── State management layers ──
// Layer 1: Local state (component-specific)
function CheckoutForm() {
    const [step, setStep] = useState(1);           // UI state
    const [form, setForm] = useState(initialForm);  // form data
}

// Layer 2: Shared state (Zustand — cross-component)
import { create } from "zustand";
const useCartStore = create((set) => ({
    items: [],
    addItem: (item) => set(state => ({
        items: [...state.items, item]
    })),
    total: 0,
}));

// Layer 3: Server state (React Query — API data)
function useProducts(category) {
    return useQuery({
        queryKey: ["products", category],
        queryFn: () => api.get(`/products?category=${category}`),
        staleTime: 5 * 60 * 1000, // cache for 5 min
    });
}

// Layer 4: URL state (React Router)
function ProductFilters() {
    const [searchParams, setSearchParams] = useSearchParams();
    const category = searchParams.get("category") || "all";
    const page = Number(searchParams.get("page")) || 1;
}

// ── Provider composition ──
function Providers({ children }) {
    return (
        <QueryClientProvider client={queryClient}>
            <AuthProvider>
                <ThemeProvider>
                    {children}
                </ThemeProvider>
            </AuthProvider>
        </QueryClientProvider>
    );
}

// ── Context API: Simple theme ──
const ThemeContext = createContext();
function ThemeProvider({ children }) {
    const [theme, setTheme] = useState("light");
    return (
        <ThemeContext.Provider value={{ theme, setTheme }}>
            {children}
        </ThemeContext.Provider>
    );
}
const useTheme = () => useContext(ThemeContext);
// ⚠️ Every setTheme re-renders ALL consumers

// ── Redux Toolkit: Cart with middleware ──
import { createSlice, configureStore } from "@reduxjs/toolkit";

const cartSlice = createSlice({
    name: "cart",
    initialState: { items: [], total: 0 },
    reducers: {
        addItem(state, action) {
            state.items.push(action.payload); // Immer allows "mutation"
            state.total += action.payload.price;
        },
        removeItem(state, action) {
            const idx = state.items.findIndex(i => i.id === action.payload);
            if (idx !== -1) {
                state.total -= state.items[idx].price;
                state.items.splice(idx, 1);
            }
        },
    },
});
const store = configureStore({ reducer: { cart: cartSlice.reducer } });
// Usage: dispatch(addItem({ id: 1, name: "Widget", price: 999 }));
// + DevTools, time-travel, middleware support

// ── Zustand: Minimal, no provider ──
import { create } from "zustand";

const useCartStore = create((set, get) => ({
    items: [],
    total: 0,
    addItem: (item) => set(state => ({
        items: [...state.items, item],
        total: state.total + item.price,
    })),
    removeItem: (id) => set(state => {
        const item = state.items.find(i => i.id === id);
        return {
            items: state.items.filter(i => i.id !== id),
            total: state.total - (item?.price || 0),
        };
    }),
    getItemCount: () => get().items.length,
}));

// Usage: selector-based subscription (granular re-renders!)
function CartBadge() {
    const count = useCartStore(state => state.items.length);
    // Only re-renders when items.length changes — not on total change!
    return <span className="badge">{count}</span>;
}

function CartTotal() {
    const total = useCartStore(state => state.total);
    return <p>₹{total.toLocaleString()}</p>;
}

// No Provider needed! Just import and use.

// ── Jotai: Atomic state ──
import { atom, useAtom } from "jotai";

const countAtom = atom(0);
const doubledAtom = atom((get) => get(countAtom) * 2); // derived atom

function Counter() {
    const [count, setCount] = useAtom(countAtom);
    return <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>;
}

function Display() {
    const [doubled] = useAtom(doubledAtom);
    return <p>Doubled: {doubled}</p>; // re-renders only when countAtom changes
}

// ── Comparison Table ──
// | Feature           | Context | Redux TK | Zustand | Jotai |
// |-------------------|---------|----------|---------|-------|
// | Boilerplate       | Low     | Medium   | Minimal | Low   |
// | Bundle size       | 0 KB    | ~11 KB   | ~1 KB   | ~2 KB |
// | DevTools          | ❌      | ✅       | ✅      | ✅    |
// | Selectors         | ❌      | ✅       | ✅      | ✅    |
// | Middleware        | ❌      | ✅       | ✅      | ❌    |
// | Provider needed   | ✅      | ✅       | ❌      | ❌*   |
// | Learning curve    | Low     | High     | Low     | Low   |

// ── Auth Context + Provider ──
import { createContext, useContext, useState, useEffect } from "react";

const AuthContext = createContext(null);

export function AuthProvider({ children }) {
    const [user, setUser] = useState(null);
    const [loading, setLoading] = useState(true); // check existing session

    // On mount: verify existing token/session
    useEffect(() => {
        const checkAuth = async () => {
            try {
                const res = await fetch("/api/auth/me", { credentials: "include" });
                if (res.ok) {
                    const userData = await res.json();
                    setUser(userData);
                }
            } catch {
                setUser(null);
            } finally {
                setLoading(false);
            }
        };
        checkAuth();
    }, []);

    const login = async (email, password) => {
        const res = await fetch("/api/auth/login", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ email, password }),
            credentials: "include", // sends/receives httpOnly cookies
        });
        if (!res.ok) throw new Error("Invalid credentials");
        const userData = await res.json();
        setUser(userData);
    };

    const logout = async () => {
        await fetch("/api/auth/logout", { method: "POST", credentials: "include" });
        setUser(null);
    };

    return (
        <AuthContext.Provider value={{ user, login, logout, loading }}>
            {children}
        </AuthContext.Provider>
    );
}

export const useAuth = () => useContext(AuthContext);

// ── Protected Route Component ──
import { Navigate, Outlet, useLocation } from "react-router-dom";

function ProtectedRoute({ requiredRole }) {
    const { user, loading } = useAuth();
    const location = useLocation();

    if (loading) return <LoadingSpinner />;

    if (!user) {
        // Redirect to login, saving the attempted URL
        return <Navigate to="/login" state={{ from: location }} replace />;
    }

    if (requiredRole && user.role !== requiredRole) {
        return <Navigate to="/unauthorized" replace />;
    }

    return <Outlet />; // render the child route
}

// ── Route Configuration ──
import { BrowserRouter, Routes, Route } from "react-router-dom";

function App() {
    return (
        <AuthProvider>
            <BrowserRouter>
                <Routes>
                    {/* Public routes */}
                    <Route path="/login" element={<LoginPage />} />
                    <Route path="/signup" element={<SignupPage />} />

                    {/* Protected: any authenticated user */}
                    <Route element={<ProtectedRoute />}>
                        <Route path="/dashboard" element={<Dashboard />} />
                        <Route path="/profile" element={<Profile />} />
                        <Route path="/settings" element={<Settings />} />
                    </Route>

                    {/* Protected: admin only */}
                    <Route element={<ProtectedRoute requiredRole="admin" />}>
                        <Route path="/admin" element={<AdminPanel />} />
                        <Route path="/admin/users" element={<UserManagement />} />
                    </Route>
                </Routes>
            </BrowserRouter>
        </AuthProvider>
    );
}

// ── Axios Interceptor for Token Refresh ──
import axios from "axios";

const api = axios.create({ baseURL: "/api", withCredentials: true });

api.interceptors.response.use(
    (response) => response,
    async (error) => {
        const originalRequest = error.config;
        if (error.response?.status === 401 && !originalRequest._retry) {
            originalRequest._retry = true;
            try {
                await axios.post("/api/auth/refresh", {}, { withCredentials: true });
                return api(originalRequest); // retry with new token
            } catch {
                window.location.href = "/login"; // refresh failed → force login
            }
        }
        return Promise.reject(error);
    }
);

// ── Unit Test: Button component ──
import { render, screen, fireEvent } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { Counter } from "./Counter";

describe("Counter", () => {
    test("renders initial count of 0", () => {
        render(<Counter />);
        expect(screen.getByText("Count: 0")).toBeInTheDocument();
    });

    test("increments count when button is clicked", async () => {
        const user = userEvent.setup();
        render(<Counter />);

        const button = screen.getByRole("button", { name: /increment/i });
        await user.click(button);

        expect(screen.getByText("Count: 1")).toBeInTheDocument();
    });

    test("calls onChange callback with new count", async () => {
        const handleChange = jest.fn();
        const user = userEvent.setup();
        render(<Counter onChange={handleChange} />);

        await user.click(screen.getByRole("button", { name: /increment/i }));
        expect(handleChange).toHaveBeenCalledWith(1);
    });
});

// ── Integration Test: Login form with API ──
import { rest } from "msw";
import { setupServer } from "msw/node";
import { render, screen, waitFor } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { LoginForm } from "./LoginForm";

// Mock API with MSW
const server = setupServer(
    rest.post("/api/auth/login", (req, res, ctx) => {
        const { email, password } = req.body;
        if (email === "user@test.com" && password === "pass123") {
            return res(ctx.json({ user: { name: "Test User" }, token: "abc" }));
        }
        return res(ctx.status(401), ctx.json({ error: "Invalid credentials" }));
    })
);

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

describe("LoginForm", () => {
    test("successful login redirects to dashboard", async () => {
        const user = userEvent.setup();
        const onSuccess = jest.fn();
        render(<LoginForm onSuccess={onSuccess} />);

        await user.type(screen.getByLabelText(/email/i), "user@test.com");
        await user.type(screen.getByLabelText(/password/i), "pass123");
        await user.click(screen.getByRole("button", { name: /log in/i }));

        await waitFor(() => {
            expect(onSuccess).toHaveBeenCalledWith({ name: "Test User" });
        });
    });

    test("shows error on invalid credentials", async () => {
        const user = userEvent.setup();
        render(<LoginForm onSuccess={jest.fn()} />);

        await user.type(screen.getByLabelText(/email/i), "wrong@test.com");
        await user.type(screen.getByLabelText(/password/i), "wrongpass");
        await user.click(screen.getByRole("button", { name: /log in/i }));

        expect(await screen.findByText(/invalid credentials/i)).toBeInTheDocument();
    });

    test("disables submit button while loading", async () => {
        const user = userEvent.setup();
        render(<LoginForm onSuccess={jest.fn()} />);

        await user.type(screen.getByLabelText(/email/i), "user@test.com");
        await user.type(screen.getByLabelText(/password/i), "pass123");
        await user.click(screen.getByRole("button", { name: /log in/i }));

        expect(screen.getByRole("button", { name: /logging in/i })).toBeDisabled();
    });
});

// ── Custom Hook Test ──
import { renderHook, act } from "@testing-library/react";
import { useCounter } from "./useCounter";

test("useCounter increments and decrements", () => {
    const { result } = renderHook(() => useCounter(0));

    act(() => result.current.increment());
    expect(result.current.count).toBe(1);

    act(() => result.current.decrement());
    expect(result.current.count).toBe(0);
});

// ── E2E Test (Playwright) ──
import { test, expect } from "@playwright/test";

test("user can login and see dashboard", async ({ page }) => {
    await page.goto("/login");
    await page.getByLabel("Email").fill("user@test.com");
    await page.getByLabel("Password").fill("pass123");
    await page.getByRole("button", { name: "Log In" }).click();

    await expect(page).toHaveURL("/dashboard");
    await expect(page.getByText("Welcome, Test User")).toBeVisible();
});

// ── Setup: QueryClient Provider ──
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { ReactQueryDevtools } from "@tanstack/react-query-devtools";

const queryClient = new QueryClient({
    defaultOptions: {
        queries: {
            staleTime: 5 * 60 * 1000, // 5 minutes — data is fresh for 5 min
            gcTime: 10 * 60 * 1000,   // 10 minutes — cached data lives 10 min
            retry: 2,                  // retry failed requests twice
            refetchOnWindowFocus: true, // refetch when tab regains focus
        },
    },
});

function App() {
    return (
        <QueryClientProvider client={queryClient}>
            <Router />
            <ReactQueryDevtools /> {/* DevTools panel */}
        </QueryClientProvider>
    );
}

// ── useQuery: Fetch and cache data ──
import { useQuery } from "@tanstack/react-query";

function ProductList({ category }) {
    const {
        data: products,
        isLoading,
        error,
        isFetching, // true when refetching in background
    } = useQuery({
        queryKey: ["products", category], // refetches when category changes
        queryFn: () => fetch(`/api/products?cat=${category}`).then(r => r.json()),
        staleTime: 60_000, // override: fresh for 1 minute
        placeholderData: (previousData) => previousData, // keep old data while fetching new category
    });

    if (isLoading) return <Skeleton count={6} />;
    if (error) return <ErrorMessage error={error} />;

    return (
        <div>
            {isFetching && <RefreshIndicator />} {/* subtle spinner for background refetch */}
            {products.map(p => <ProductCard key={p.id} product={p} />)}
        </div>
    );
}

// ── useMutation: Create/Update/Delete with cache invalidation ──
import { useMutation, useQueryClient } from "@tanstack/react-query";

function AddProductForm() {
    const queryClient = useQueryClient();

    const addProduct = useMutation({
        mutationFn: (newProduct) =>
            fetch("/api/products", {
                method: "POST",
                headers: { "Content-Type": "application/json" },
                body: JSON.stringify(newProduct),
            }).then(r => r.json()),

        // Optimistic update: update UI before server responds
        onMutate: async (newProduct) => {
            await queryClient.cancelQueries({ queryKey: ["products"] });
            const previous = queryClient.getQueryData(["products"]);

            queryClient.setQueryData(["products"], (old) => [
                ...old,
                { ...newProduct, id: "temp-" + Date.now() },
            ]);

            return { previous }; // context for rollback
        },

        onError: (err, newProduct, context) => {
            // Rollback on error
            queryClient.setQueryData(["products"], context.previous);
            toast.error("Failed to add product");
        },

        onSuccess: (data) => {
            toast.success(`Added: ${data.name}`);
        },

        onSettled: () => {
            // Always refetch to sync with server
            queryClient.invalidateQueries({ queryKey: ["products"] });
        },
    });

    const handleSubmit = (formData) => {
        addProduct.mutate(formData);
    };

    return (
        <form onSubmit={handleSubmit}>
            {/* form fields */}
            <button type="submit" disabled={addProduct.isPending}>
                {addProduct.isPending ? "Adding..." : "Add Product"}
            </button>
        </form>
    );
}

// ── Pagination with useQuery ──
function PaginatedProducts() {
    const [page, setPage] = useState(1);

    const { data, isPlaceholderData } = useQuery({
        queryKey: ["products", "list", page],
        queryFn: () => fetch(`/api/products?page=${page}&limit=20`).then(r => r.json()),
        placeholderData: (prev) => prev, // keep previous page data while loading next
    });

    return (
        <div style={{ opacity: isPlaceholderData ? 0.5 : 1 }}>
            {data?.products.map(p => <ProductCard key={p.id} product={p} />)}
            <button onClick={() => setPage(p => p - 1)} disabled={page === 1}>Prev</button>
            <span>Page {page}</span>
            <button onClick={() => setPage(p => p + 1)} disabled={isPlaceholderData || !data?.hasMore}>Next</button>
        </div>
    );
}

// ── Compound Component: Accessible Tabs ──
import { createContext, useContext, useState, useRef, useId } from "react";

// 1. Shared context for implicit state
const TabsContext = createContext();

// 2. Parent: manages state
function Tabs({ defaultValue, children, onChange }) {
    const [activeTab, setActiveTab] = useState(defaultValue);
    const id = useId(); // unique prefix for ARIA IDs

    const selectTab = (value) => {
        setActiveTab(value);
        onChange?.(value);
    };

    return (
        <TabsContext.Provider value={{ activeTab, selectTab, id }}>
            <div className="tabs">{children}</div>
        </TabsContext.Provider>
    );
}

// 3. TabList: container with keyboard navigation
function TabList({ children, label }) {
    const tabsRef = useRef(null);

    const handleKeyDown = (e) => {
        const tabs = tabsRef.current?.querySelectorAll('[role="tab"]');
        if (!tabs) return;
        const currentIdx = Array.from(tabs).findIndex(t => t === document.activeElement);

        let nextIdx;
        switch (e.key) {
            case "ArrowRight": nextIdx = (currentIdx + 1) % tabs.length; break;
            case "ArrowLeft": nextIdx = (currentIdx - 1 + tabs.length) % tabs.length; break;
            case "Home": nextIdx = 0; break;
            case "End": nextIdx = tabs.length - 1; break;
            default: return;
        }
        e.preventDefault();
        tabs[nextIdx].focus();
    };

    return (
        <div ref={tabsRef} role="tablist" aria-label={label} onKeyDown={handleKeyDown}>
            {children}
        </div>
    );
}

// 4. Tab: individual tab button
function Tab({ value, children }) {
    const { activeTab, selectTab, id } = useContext(TabsContext);
    const isActive = activeTab === value;

    return (
        <button
            role="tab"
            id={`${id}-tab-${value}`}
            aria-selected={isActive}
            aria-controls={`${id}-panel-${value}`}
            tabIndex={isActive ? 0 : -1}
            onClick={() => selectTab(value)}
            className={isActive ? "tab active" : "tab"}
        >
            {children}
        </button>
    );
}

// 5. TabPanel: content panel
function TabPanel({ value, children }) {
    const { activeTab, id } = useContext(TabsContext);
    if (activeTab !== value) return null;

    return (
        <div
            role="tabpanel"
            id={`${id}-panel-${value}`}
            aria-labelledby={`${id}-tab-${value}`}
            tabIndex={0}
        >
            {children}
        </div>
    );
}

// Attach sub-components to parent (dot notation)
Tabs.List = TabList;
Tabs.Tab = Tab;
Tabs.Panel = TabPanel;

// ── Usage: Flexible, accessible, composable ──
function SettingsPage() {
    return (
        <Tabs defaultValue="general" onChange={(tab) => console.log("Tab:", tab)}>
            <Tabs.List label="Settings sections">
                <Tabs.Tab value="general">⚙️ General</Tabs.Tab>
                <Tabs.Tab value="security">🔒 Security</Tabs.Tab>
                <Tabs.Tab value="billing">💳 Billing</Tabs.Tab>
            </Tabs.List>

            <Tabs.Panel value="general">
                <h2>General Settings</h2>
                <p>Name, email, language preferences...</p>
            </Tabs.Panel>

            {/* Add custom content between panels */}
            <div className="divider" />

            <Tabs.Panel value="security">
                <h2>Security Settings</h2>
                <p>Password, 2FA, sessions...</p>
            </Tabs.Panel>

            <Tabs.Panel value="billing">
                <h2>Billing</h2>
                <p>Plans, invoices, payment methods...</p>
            </Tabs.Panel>
        </Tabs>
    );
}

// ── Compare: Monolithic vs Compound ──
// ❌ Monolithic: One component, many props — inflexible
// <Tabs tabs={[{label, content, icon}]} variant="underline" onTabChange={} />

// ✅ Compound: Composable, flexible, each piece customizable
// <Tabs><Tabs.Tab><Tabs.Panel> — add markup anywhere

// ═══════════════════════════════════════════
// APP ROUTER (Next.js 13+) — Recommended
// ═══════════════════════════════════════════

// ── SSG: Static page (default behavior) ──
// app/blog/[slug]/page.tsx
import { db } from "@/lib/db";
import { notFound } from "next/navigation";

// Generate static pages at build time
export async function generateStaticParams() {
    const posts = await db.query("SELECT slug FROM posts WHERE published = true");
    return posts.map(post => ({ slug: post.slug }));
    // Generates: /blog/react-hooks, /blog/nextjs-guide, etc.
}

// This runs at BUILD TIME (SSG) — static HTML cached on CDN
export default async function BlogPost({ params }) {
    const post = await db.query("SELECT * FROM posts WHERE slug = $1", [params.slug]);
    if (!post) notFound();

    return (
        <article>
            <h1>{post.title}</h1>
            <time>{post.publishedAt}</time>
            <div dangerouslySetInnerHTML={{ __html: post.content }} />
        </article>
    );
}

// ── ISR: Static + revalidation ──
// app/products/page.tsx

// Revalidate every 60 seconds — ISR
export const revalidate = 60; // seconds

export default async function ProductsPage() {
    // First request: rendered and cached as static HTML
    // After 60s: next request triggers background regeneration
    // Stale page served instantly while fresh version builds
    const products = await fetch("https://api.store.com/products", {
        next: { revalidate: 60 }, // per-fetch revalidation
    }).then(r => r.json());

    return (
        <div className="product-grid">
            {products.map(p => <ProductCard key={p.id} product={p} />)}
        </div>
    );
}

// ── SSR: Dynamic rendering (per-request) ──
// app/dashboard/page.tsx
import { cookies } from "next/headers";

// Using cookies/headers makes the page dynamic (SSR)
export default async function Dashboard() {
    const cookieStore = cookies();
    const token = cookieStore.get("session")?.value;

    const userData = await fetch("https://api.example.com/dashboard", {
        headers: { Authorization: `Bearer ${token}` },
        cache: "no-store", // force dynamic — no caching
    }).then(r => r.json());

    return (
        <div>
            <h1>Welcome, {userData.name}</h1>
            <DashboardWidgets data={userData.widgets} />
        </div>
    );
}

// ── Streaming with Suspense ──
// app/dashboard/page.tsx
import { Suspense } from "react";

export default function DashboardPage() {
    return (
        <div>
            <h1>Dashboard</h1>
            {/* Header renders immediately */}

            <Suspense fallback={<ChartSkeleton />}>
                <RevenueChart /> {/* Streams in when data is ready */}
            </Suspense>

            <Suspense fallback={<TableSkeleton />}>
                <RecentOrders /> {/* Streams independently */}
            </Suspense>
        </div>
    );
}

// ═══════════════════════════════════════════
// PAGES ROUTER (Legacy — still widely used)
// ═══════════════════════════════════════════

// ── getStaticProps (SSG) ──
// pages/blog/[slug].tsx
export async function getStaticPaths() {
    const posts = await fetchAllPosts();
    return {
        paths: posts.map(p => ({ params: { slug: p.slug } })),
        fallback: "blocking", // SSR for unknown slugs, then cache
    };
}

export async function getStaticProps({ params }) {
    const post = await fetchPost(params.slug);
    if (!post) return { notFound: true };
    return {
        props: { post },
        revalidate: 3600, // ISR: regenerate every hour
    };
}

// ── getServerSideProps (SSR) ──
// pages/dashboard.tsx
export async function getServerSideProps({ req }) {
    const token = req.cookies.session;
    const data = await fetchDashboard(token);
    return { props: { data } };
}

// ── Comparison Table ──
// | Strategy | When Generated  | Speed     | Data Freshness | SEO | Use Case              |
// |----------|----------------|-----------|----------------|-----|-----------------------|
// | SSG      | Build time     | Fastest   | Stale          | ✅  | Blog, docs, marketing |
// | ISR      | Build + bg     | Fast      | Near-fresh     | ✅  | E-commerce, news      |
// | SSR      | Every request  | Slower    | Always fresh   | ✅  | Dashboard, personalized|
// | CSR      | In browser     | Slowest   | Client-fetched | ❌  | Admin panels, SPAs    |

// ── Problem: Unnecessary re-renders ──
function App() {
    const [count, setCount] = useState(0);
    const [theme, setTheme] = useState("light");

    return (
        <div>
            <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>
            {/* ❌ ExpensiveList re-renders when count changes — even though it only uses theme! */}
            <ExpensiveList theme={theme} items={generateItems()} />
        </div>
    );
}

// ── Fix 1: React.memo — skip re-render if props unchanged ──
const ExpensiveList = React.memo(function ExpensiveList({ theme, items }) {
    console.log("ExpensiveList rendered"); // only logs when theme or items change
    return (
        <ul className={theme}>
            {items.map(item => <li key={item.id}>{item.name}</li>)}
        </ul>
    );
});

// ⚠️ But memo alone won't help if you pass new references every render!

// ── Fix 2: useMemo + useCallback — stable references ──
function App() {
    const [count, setCount] = useState(0);
    const [theme, setTheme] = useState("light");

    // ✅ Memoize the items array — same reference if dependencies don't change
    const items = useMemo(() => generateItems(), []); // only computed once

    // ✅ Memoize the callback — same reference across renders
    const handleItemClick = useCallback((id) => {
        console.log("Clicked:", id);
    }, []);

    return (
        <div>
            <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>
            {/* Now ExpensiveList skips re-render when count changes ✅ */}
            <ExpensiveList theme={theme} items={items} onItemClick={handleItemClick} />
        </div>
    );
}

// ── Fix 3: Move state down — isolate re-renders ──
// ❌ Before: state in parent causes all children to re-render
function Page() {
    const [searchQuery, setSearchQuery] = useState(""); // ← state here re-renders everything
    return (
        <div>
            <SearchBar value={searchQuery} onChange={setSearchQuery} />
            <Navigation />      {/* re-renders unnecessarily */}
            <ExpensiveChart />   {/* re-renders unnecessarily */}
            <Footer />           {/* re-renders unnecessarily */}
        </div>
    );
}

// ✅ After: extract stateful component — only SearchSection re-renders
function Page() {
    return (
        <div>
            <SearchSection />    {/* state is inside — re-renders only this */}
            <Navigation />       {/* never re-renders from search ✅ */}
            <ExpensiveChart />   {/* never re-renders from search ✅ */}
            <Footer />           {/* never re-renders from search ✅ */}
        </div>
    );
}

function SearchSection() {
    const [searchQuery, setSearchQuery] = useState("");
    return <SearchBar value={searchQuery} onChange={setSearchQuery} />;
}

// ── Fix 4: Composition — children as props ──
function Layout({ children }) {
    const [scrollY, setScrollY] = useState(0);
    useEffect(() => {
        const onScroll = () => setScrollY(window.scrollY);
        window.addEventListener("scroll", onScroll);
        return () => window.removeEventListener("scroll", onScroll);
    }, []);

    return (
        <div>
            <Header shrink={scrollY > 100} />
            {children} {/* ← children are created by parent, NOT re-created here */}
        </div>
    );
}

// Usage:
<Layout>
    <ExpensiveContent /> {/* This does NOT re-render when scrollY changes! */}
</Layout>
// children is a prop — its reference is stable (created by Layout's parent)

// ── TanStack Virtual: Modern virtualization ──
import { useVirtualizer } from "@tanstack/react-virtual";
import { useRef } from "react";

function VirtualList({ items }) {
    const parentRef = useRef(null);

    const virtualizer = useVirtualizer({
        count: items.length,       // total items: e.g., 100,000
        getScrollElement: () => parentRef.current,
        estimateSize: () => 60,     // estimated row height in px
        overscan: 5,                // render 5 extra items above/below viewport
    });

    return (
        <div
            ref={parentRef}
            style={{ height: "600px", overflow: "auto" }}
        >
            {/* Total scrollable height — creates proper scrollbar */}
            <div style={{ height: `${virtualizer.getTotalSize()}px`, position: "relative" }}>
                {virtualizer.getVirtualItems().map(virtualRow => (
                    <div
                        key={virtualRow.key}
                        style={{
                            position: "absolute",
                            top: 0,
                            left: 0,
                            width: "100%",
                            height: `${virtualRow.size}px`,
                            transform: `translateY(${virtualRow.start}px)`,
                        }}
                    >
                        <ListItem item={items[virtualRow.index]} />
                    </div>
                ))}
            </div>
        </div>
    );
    // 100,000 items → only ~20 DOM nodes at any time!
}

// ── react-window: Simple fixed-size list ──
import { FixedSizeList } from "react-window";

function SimpleVirtualList({ items }) {
    const Row = ({ index, style }) => (
        <div style={style} className="list-row">
            <span>{items[index].name}</span>
            <span>{items[index].email}</span>
        </div>
    );

    return (
        <FixedSizeList
            height={600}          // viewport height
            width="100%"
            itemCount={items.length}  // 50,000 items
            itemSize={50}             // each row = 50px
            overscanCount={5}
        >
            {Row}
        </FixedSizeList>
    );
}

// ── Variable-size list (dynamic heights) ──
import { VariableSizeList } from "react-window";

function ChatMessages({ messages }) {
    const getItemSize = (index) => {
        // Calculate height based on message content length
        const msg = messages[index];
        return msg.text.length > 100 ? 120 : 60; // tall for long messages
    };

    const Row = ({ index, style }) => (
        <div style={style} className={`message ${messages[index].sender}`}>
            <p>{messages[index].text}</p>
            <time>{messages[index].timestamp}</time>
        </div>
    );

    return (
        <VariableSizeList
            height={500}
            width="100%"
            itemCount={messages.length}
            itemSize={getItemSize}
        >
            {Row}
        </VariableSizeList>
    );
}

// ── Infinite Scroll with IntersectionObserver ──
function InfiniteList() {
    const [items, setItems] = useState([]);
    const [page, setPage] = useState(1);
    const [hasMore, setHasMore] = useState(true);
    const loaderRef = useRef(null);

    useEffect(() => {
        const observer = new IntersectionObserver(
            ([entry]) => {
                if (entry.isIntersecting && hasMore) {
                    setPage(p => p + 1); // triggers fetch
                }
            },
            { threshold: 0.1 }
        );

        if (loaderRef.current) observer.observe(loaderRef.current);
        return () => observer.disconnect();
    }, [hasMore]);

    useEffect(() => {
        fetch(`/api/items?page=${page}&limit=20`)
            .then(r => r.json())
            .then(data => {
                setItems(prev => [...prev, ...data.items]);
                setHasMore(data.hasMore);
            });
    }, [page]);

    return (
        <div>
            {items.map(item => <ItemCard key={item.id} item={item} />)}
            {hasMore && <div ref={loaderRef} className="loader">Loading more...</div>}
        </div>
    );
}

// ── Code Splitting: Route-based (most impactful) ──
import { lazy, Suspense } from "react";
import { Routes, Route } from "react-router-dom";

// Each route loads its own chunk — only downloaded when visited
const Home = lazy(() => import("./pages/Home"));
const Dashboard = lazy(() => import("./pages/Dashboard"));
const Settings = lazy(() => import("./pages/Settings"));
const AdminPanel = lazy(() => import("./pages/AdminPanel"));

function App() {
    return (
        <Suspense fallback={<PageSkeleton />}>
            <Routes>
                <Route path="/" element={<Home />} />
                <Route path="/dashboard" element={<Dashboard />} />
                <Route path="/settings" element={<Settings />} />
                <Route path="/admin" element={<AdminPanel />} />
            </Routes>
        </Suspense>
    );
}
// Initial bundle: only shared code + Home page
// Dashboard JS downloaded only when user navigates to /dashboard

// ── Feature-based splitting: Heavy components ──
function ProductPage({ productId }) {
    const [showReviews, setShowReviews] = useState(false);

    // Reviews component has a rich text editor + charts (200KB)
    // Only load when user clicks "Show Reviews"
    const ReviewSection = lazy(() => import("./ReviewSection"));

    return (
        <div>
            <ProductDetails id={productId} />
            <button onClick={() => setShowReviews(true)}>Show Reviews</button>

            {showReviews && (
                <Suspense fallback={<ReviewsSkeleton />}>
                    <ReviewSection productId={productId} />
                </Suspense>
            )}
        </div>
    );
}

// ── Tree shaking: Import only what you need ──
// ❌ Imports entire library (300KB for moment, 70KB for lodash)
import moment from "moment";
import _ from "lodash";

// ✅ Import specific functions (tree-shakeable)
import { format, addDays } from "date-fns";    // only used functions (~3KB)
import { debounce } from "lodash-es";           // only debounce (~1KB)
// Or even better — write your own debounce (10 lines)

// ── Bundle Analysis: Find what's heavy ──
// package.json:
// "scripts": {
//   "analyze": "npx webpack-bundle-analyzer build/stats.json"
//   "build:stats": "GENERATE_SOURCEMAP=true react-scripts build"
// }
//
// Or with source-map-explorer:
// npx source-map-explorer build/static/js/*.js

// ── Dynamic imports for conditional features ──
async function exportToPDF(data) {
    // jspdf is 200KB — only loaded when user clicks "Export PDF"
    const { jsPDF } = await import("jspdf");
    const doc = new jsPDF();
    doc.text(data.title, 10, 10);
    doc.save("report.pdf");
}

// ── Barrel file optimization ──
// ❌ components/index.ts re-exports everything
// import { Button } from "@/components"; // pulls in ALL components

// ✅ Direct imports
// import { Button } from "@/components/Button"; // only Button's code

// ── Next.js automatic optimizations ──
// next.config.js
module.exports = {
    // Automatic code splitting per page
    // Automatic tree shaking
    // Automatic polyfill loading
    experimental: {
        optimizePackageImports: ["@heroicons/react", "lucide-react"],
        // ↑ Auto-rewrites barrel imports to direct imports
    },
};

// ── Native Lazy Loading ──
function ProductGrid({ products }) {
    return (
        <div className="grid">
            {products.map((product, index) => (
                <div key={product.id} className="product-card">
                    <img
                        src={product.imageUrl}
                        alt={product.name}
                        width={300}
                        height={200}
                        loading={index < 4 ? "eager" : "lazy"} // first 4 load immediately
                        decoding="async" // don't block main thread
                    />
                    <h3>{product.name}</h3>
                    <p>₹{product.price}</p>
                </div>
            ))}
        </div>
    );
}

// ── Responsive Images with <picture> ──
function HeroImage({ src, alt }) {
    return (
        <picture>
            {/* Browser picks the best format it supports */}
            <source srcSet={`${src}.avif`} type="image/avif" />
            <source srcSet={`${src}.webp`} type="image/webp" />
            <img
                src={`${src}.jpg`} // fallback
                alt={alt}
                width={1200}
                height={600}
                loading="eager" // hero image — load immediately
                fetchPriority="high" // tell browser this is important
                style={{ width: "100%", height: "auto" }}
            />
        </picture>
    );
}

// ── srcset: Serve optimal size per viewport ──
function ResponsiveImage({ src, alt }) {
    return (
        <img
            src={`${src}-800.jpg`} // default
            srcSet={`
                ${src}-400.jpg 400w,
                ${src}-800.jpg 800w,
                ${src}-1200.jpg 1200w,
                ${src}-1600.jpg 1600w
            `}
            sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw"
            alt={alt}
            loading="lazy"
            width={800}
            height={533}
        />
    );
}

// ── Next.js Image Component (automatic optimization) ──
import Image from "next/image";

function ProductCard({ product }) {
    return (
        <div className="card">
            <Image
                src={product.imageUrl}
                alt={product.name}
                width={300}
                height={200}
                placeholder="blur" // show blurred version while loading
                blurDataURL={product.blurHash} // tiny base64 blur placeholder
                sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
                quality={75} // 75% quality — good balance
                priority={false} // true for above-the-fold (LCP) images
            />
        </div>
    );
}

// ── Skeleton Screen Component ──
function Skeleton({ width, height, borderRadius = 4 }) {
    return (
        <div
            className="skeleton"
            style={{ width, height, borderRadius }}
            aria-hidden="true"
        />
    );
}

// CSS for skeleton animation:
// .skeleton {
//     background: linear-gradient(90deg, #e0e0e0 25%, #f0f0f0 50%, #e0e0e0 75%);
//     background-size: 200% 100%;
//     animation: shimmer 1.5s ease-in-out infinite;
// }
// @keyframes shimmer {
//     0% { background-position: -200% 0; }
//     100% { background-position: 200% 0; }
// }

// ── Skeleton for a Product Card ──
function ProductCardSkeleton() {
    return (
        <div className="product-card">
            <Skeleton width="100%" height={200} />          {/* image */}
            <Skeleton width="80%" height={20} />            {/* title */}
            <Skeleton width="40%" height={16} />            {/* price */}
            <Skeleton width="60%" height={36} borderRadius={18} /> {/* button */}
        </div>
    );
}

// ── Usage with loading state ──
function ProductPage() {
    const { data, isLoading } = useQuery({ queryKey: ["products"], queryFn: fetchProducts });

    if (isLoading) {
        return (
            <div className="grid">
                {Array.from({ length: 6 }).map((_, i) => (
                    <ProductCardSkeleton key={i} />
                ))}
            </div>
        );
    }

    return (
        <div className="grid">
            {data.map(product => <ProductCard key={product.id} product={product} />)}
        </div>
    );
}

// ── Progressive Image: blur → full resolution ──
function ProgressiveImage({ src, placeholder, alt, ...props }) {
    const [loaded, setLoaded] = useState(false);

    return (
        <div className="progressive-image" style={{ position: "relative" }}>
            {/* Tiny blurred placeholder (inline base64, ~200 bytes) */}
            <img
                src={placeholder}
                alt=""
                aria-hidden="true"
                style={{
                    filter: "blur(20px)",
                    opacity: loaded ? 0 : 1,
                    transition: "opacity 0.3s",
                    position: "absolute", inset: 0,
                    width: "100%", height: "100%", objectFit: "cover",
                }}
            />
            {/* Full resolution image */}
            <img
                src={src}
                alt={alt}
                loading="lazy"
                onLoad={() => setLoaded(true)}
                style={{ opacity: loaded ? 1 : 0, transition: "opacity 0.3s" }}
                {...props}
            />
        </div>
    );
}

// ── React DevTools Profiler (UI-based) ──
// 1. Install React DevTools browser extension
// 2. Open DevTools → "Profiler" tab
// 3. Click Record → interact with your app → Stop
// 4. Analyze:
//    - Flamegraph: visual tree of component renders
//    - Ranked: components sorted by render time
//    - Each bar shows: component name, render duration, why it rendered
//
// Settings to enable:
// ⚙️ → "Record why each component rendered while profiling"
// ⚙️ → "Highlight updates when components render"

// ── React Profiler API (programmatic) ──
import { Profiler } from "react";

function onRenderCallback(
    id,           // "ProductList" — the Profiler id
    phase,        // "mount" | "update" — initial or re-render
    actualDuration, // time spent rendering (ms)
    baseDuration,   // estimated time without memoization (ms)
    startTime,      // when React began rendering
    commitTime      // when React committed the update
) {
    // Log slow renders
    if (actualDuration > 16) { // > 1 frame (16ms at 60fps)
        console.warn(`Slow render: ${id} took ${actualDuration.toFixed(2)}ms (${phase})`);
    }

    // Send to analytics in production
    if (process.env.NODE_ENV === "production") {
        sendToAnalytics({
            component: id,
            phase,
            duration: actualDuration,
            timestamp: commitTime,
        });
    }
}

function App() {
    return (
        <Profiler id="ProductList" onRender={onRenderCallback}>
            <ProductList />
        </Profiler>
    );
}

// ── Nested Profilers for granular measurement ──
function Dashboard() {
    return (
        <div>
            <Profiler id="RevenueChart" onRender={onRenderCallback}>
                <RevenueChart />
            </Profiler>

            <Profiler id="OrdersTable" onRender={onRenderCallback}>
                <OrdersTable />
            </Profiler>

            <Profiler id="UserActivity" onRender={onRenderCallback}>
                <UserActivity />
            </Profiler>
        </div>
    );
}

// ── why-did-you-render (development debugging) ──
// Step 1: Install
// npm install @welldone-software/why-did-you-render --save-dev

// Step 2: Setup (src/wdyr.js — import BEFORE React)
/// <reference types="@welldone-software/why-did-you-render" />
import React from "react";

if (process.env.NODE_ENV === "development") {
    const whyDidYouRender = require("@welldone-software/why-did-you-render");
    whyDidYouRender(React, {
        trackAllPureComponents: true,  // track all React.memo components
        trackHooks: true,               // track hook changes
        logOnDifferentValues: false,     // only log UNNECESSARY re-renders
    });
}

// Step 3: Mark specific components to track
const ExpensiveList = React.memo(function ExpensiveList({ items, onItemClick }) {
    return items.map(item => (
        <div key={item.id} onClick={() => onItemClick(item.id)}>
            {item.name}
        </div>
    ));
});
ExpensiveList.whyDidYouRender = true; // ← enable tracking

// Console output when ExpensiveList re-renders unnecessarily:
// ┌──────────────────────────────────────────
// │ ExpensiveList
// │ Re-rendered because of props change:
// │   onItemClick: ƒ onClick() {} !== ƒ onClick() {}
// │   ↑ different function reference, same implementation
// │   → Fix: wrap in useCallback
// └──────────────────────────────────────────

// ── Performance measurement hooks ──
function useRenderCount(componentName) {
    const renderCount = useRef(0);
    renderCount.current += 1;

    useEffect(() => {
        console.log(`${componentName} rendered ${renderCount.current} times`);
    });
}

function useRenderTime(componentName) {
    const startTime = performance.now();

    useEffect(() => {
        const endTime = performance.now();
        const duration = endTime - startTime;
        if (duration > 16) {
            console.warn(`${componentName} render: ${duration.toFixed(2)}ms`);
        }
    });
}

// Usage:
function ProductList({ items }) {
    useRenderCount("ProductList");
    useRenderTime("ProductList");
    return items.map(item => <ProductCard key={item.id} item={item} />);
}

// ── Chrome DevTools Performance Tab ──
// 1. Open DevTools → Performance tab
// 2. Click Record → interact with your app → Stop
// 3. Look for:
//    - Long Tasks (yellow bars > 50ms): indicates slow JavaScript
//    - Layout (purple): forced reflows from reading DOM after writes
//    - Paint (green): excessive repainting
//    - "Timings" row: shows React commit phases
//
// Common findings:
// - Large component tree rendering on every keystroke
// - Layout thrashing: reading offsetHeight then setting style in a loop
// - Synchronous DOM measurements in useLayoutEffect

// ── Performance optimization workflow ──
// 1. MEASURE: Profile with React DevTools → find slow components
// 2. IDENTIFY: Use "why did this render?" to find the cause
// 3. FIX: Apply the appropriate optimization:
//    - React.memo for prop-stable components
//    - useMemo/useCallback for derived values/callbacks
//    - Move state down or use composition
//    - Virtualize long lists
//    - Code-split heavy components
// 4. VERIFY: Profile again → confirm improvement
// 5. REPEAT: Focus on the next bottleneck

// ── Monorepo Structure (Nx) ──
/*
my-org/
├── apps/
│   ├── web/                    # Main React web app (Next.js)
│   │   ├── src/
│   │   ├── project.json        # Nx project config
│   │   └── tsconfig.json
│   ├── mobile/                 # React Native app
│   │   └── src/
│   ├── admin/                  # Admin dashboard (React + Vite)
│   │   └── src/
│   └── docs/                   # Documentation site
│       └── src/
├── libs/
│   ├── ui/                     # Shared design system
│   │   ├── src/
│   │   │   ├── Button/
│   │   │   ├── Modal/
│   │   │   ├── Table/
│   │   │   └── index.ts        # barrel export
│   │   └── project.json
│   ├── api-client/             # Typed API client (shared across apps)
│   │   └── src/
│   ├── hooks/                  # Shared React hooks
│   │   └── src/
│   ├── utils/                  # Pure utility functions
│   │   └── src/
│   └── types/                  # Shared TypeScript types
│       └── src/
├── tools/                      # Custom generators, scripts
├── nx.json                     # Nx workspace config
├── tsconfig.base.json          # Shared TS config
└── package.json
*/

// ── Importing shared code (zero publishing!) ──
// apps/web/src/pages/Dashboard.tsx
import { Button, Modal, DataTable } from "@my-org/ui";
import { useAuth, usePagination } from "@my-org/hooks";
import { apiClient } from "@my-org/api-client";
import { formatCurrency, dateToRelative } from "@my-org/utils";
import type { User, Product } from "@my-org/types";

// Same imports work in apps/mobile, apps/admin — zero duplication!

// ── Nx: Affected-only testing (CI optimization) ──
// Only test projects affected by the current PR's changes
// $ npx nx affected --target=test --base=main
// If you only changed libs/ui → only tests for ui, web, admin run
// (mobile doesn't use ui → skipped)

// ── Turborepo: turbo.json task pipeline ──
// turbo.json
{
    "$schema": "https://turbo.build/schema.json",
    "pipeline": {
        "build": {
            "dependsOn": ["^build"],  // build dependencies first
            "outputs": ["dist/**", ".next/**"]
        },
        "test": {
            "dependsOn": ["build"],
            "inputs": ["src/**", "test/**"]
        },
        "lint": {},  // no dependencies — run in parallel
        "dev": {
            "cache": false,
            "persistent": true
        }
    }
}
// $ turbo run build  →  builds all projects in dependency order
//                        with remote caching (skips unchanged projects)

// ── pnpm workspace: package.json setup ──
// pnpm-workspace.yaml
// packages:
//   - "apps/*"
//   - "libs/*"

// libs/ui/package.json
{
    "name": "@my-org/ui",
    "main": "./src/index.ts",
    "types": "./src/index.ts"
}

// apps/web/package.json
{
    "name": "@my-org/web",
    "dependencies": {
        "@my-org/ui": "workspace:*",      // links to local package
        "@my-org/hooks": "workspace:*",
        "@my-org/api-client": "workspace:*"
    }
}
// pnpm install → symlinks local packages, no npm publish needed

// ── Nx Generator: Scaffold new library ──
// $ npx nx g @nx/react:library feature-flags --directory=libs/feature-flags
// Creates: libs/feature-flags/ with src/, tests, tsconfig, project.json
// Automatically updates tsconfig paths and dependency graph

// ═══════════════════════════════════════
// WEBPACK MODULE FEDERATION (React)
// ═══════════════════════════════════════

// ── Host (Shell) App: webpack.config.js ──
const { ModuleFederationPlugin } = require("webpack").container;

module.exports = {
    plugins: [
        new ModuleFederationPlugin({
            name: "shell",
            remotes: {
                // Load micro-frontends at runtime from their deployed URLs
                checkout: "checkout@https://checkout.myapp.com/remoteEntry.js",
                search: "search@https://search.myapp.com/remoteEntry.js",
                profile: "profile@https://profile.myapp.com/remoteEntry.js",
            },
            shared: {
                react: { singleton: true, requiredVersion: "^18.0.0" },
                "react-dom": { singleton: true, requiredVersion: "^18.0.0" },
                "react-router-dom": { singleton: true },
            },
        }),
    ],
};

// ── Remote (Checkout) App: webpack.config.js ──
module.exports = {
    plugins: [
        new ModuleFederationPlugin({
            name: "checkout",
            filename: "remoteEntry.js",  // entry point for consumers
            exposes: {
                // Components this micro-frontend shares
                "./CheckoutPage": "./src/pages/CheckoutPage",
                "./CartWidget": "./src/components/CartWidget",
                "./useCart": "./src/hooks/useCart",
            },
            shared: {
                react: { singleton: true },
                "react-dom": { singleton: true },
            },
        }),
    ],
};

// ── Shell App: Loading remote components ──
import React, { Suspense, lazy } from "react";
import { Routes, Route } from "react-router-dom";

// Dynamic imports from remote micro-frontends
const CheckoutPage = lazy(() => import("checkout/CheckoutPage"));
const SearchPage = lazy(() => import("search/SearchPage"));
const ProfilePage = lazy(() => import("profile/ProfilePage"));
const CartWidget = lazy(() => import("checkout/CartWidget"));

function ShellApp() {
    return (
        <div>
            <header>
                <nav>
                    <a href="/">Home</a>
                    <a href="/search">Search</a>
                    <a href="/profile">Profile</a>
                </nav>
                {/* Cart widget from checkout team — loaded from their server */}
                <Suspense fallback={<CartBadgeSkeleton />}>
                    <CartWidget />
                </Suspense>
            </header>

            <Suspense fallback={<PageSkeleton />}>
                <Routes>
                    <Route path="/" element={<HomePage />} />
                    <Route path="/search/*" element={<SearchPage />} />
                    <Route path="/checkout/*" element={<CheckoutPage />} />
                    <Route path="/profile/*" element={<ProfilePage />} />
                </Routes>
            </Suspense>
        </div>
    );
}

// ── Error boundary for resilience ──
// If checkout team deploys a broken version, only checkout breaks
// Shell, search, and profile continue working
function MicroFrontendBoundary({ name, children }) {
    return (
        <ErrorBoundary
            fallback={
                <div className="mfe-error">
                    <p>{name} is temporarily unavailable.</p>
                    <button onClick={() => window.location.reload()}>Retry</button>
                </div>
            }
        >
            <Suspense fallback={<PageSkeleton />}>
                {children}
            </Suspense>
        </ErrorBoundary>
    );
}

// ── Communication between micro-frontends ──
// Option 1: Custom Events (decoupled)
// Checkout dispatches:
window.dispatchEvent(new CustomEvent("cart:updated", {
    detail: { itemCount: 3, total: 2999 }
}));

// Shell or CartWidget listens:
useEffect(() => {
    const handler = (e) => setCartCount(e.detail.itemCount);
    window.addEventListener("cart:updated", handler);
    return () => window.removeEventListener("cart:updated", handler);
}, []);

// Option 2: Shared state via Module Federation
// Expose a shared store from one micro-frontend, consume in others

// ── Folder Structure: Atomic Design ──
/*
src/
├── components/
│   ├── atoms/
│   │   ├── Button/
│   │   │   ├── Button.tsx
│   │   │   ├── Button.styles.ts    // styled-components or CSS module
│   │   │   ├── Button.test.tsx
│   │   │   ├── Button.stories.tsx  // Storybook
│   │   │   └── index.ts           // export { Button } from "./Button"
│   │   ├── Input/
│   │   ├── Avatar/
│   │   ├── Badge/
│   │   ├── Spinner/
│   │   └── index.ts               // barrel: export * from "./Button"; ...
│   ├── molecules/
│   │   ├── SearchBar/
│   │   ├── FormField/
│   │   ├── UserCard/
│   │   └── index.ts
│   ├── organisms/
│   │   ├── Header/
│   │   ├── ProductGrid/
│   │   ├── CommentThread/
│   │   └── index.ts
│   └── templates/
│       ├── DashboardLayout/
│       ├── AuthLayout/
│       └── index.ts
├── pages/                         // Pages = templates + real data
│   ├── Dashboard/
│   ├── ProductDetail/
│   └── Settings/
*/

// ── Atom: Button (pure, reusable, no business logic) ──
interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
    variant?: "primary" | "secondary" | "ghost" | "danger";
    size?: "sm" | "md" | "lg";
    isLoading?: boolean;
    leftIcon?: React.ReactNode;
}

function Button({
    variant = "primary",
    size = "md",
    isLoading = false,
    leftIcon,
    children,
    disabled,
    ...props
}: ButtonProps) {
    return (
        <button
            className={`btn btn-${variant} btn-${size}`}
            disabled={disabled || isLoading}
            {...props}
        >
            {isLoading ? <Spinner size="sm" /> : leftIcon}
            <span>{children}</span>
        </button>
    );
}

// ── Molecule: SearchBar (atoms composed) ──
function SearchBar({ onSearch, placeholder = "Search..." }) {
    const [query, setQuery] = useState("");

    const handleSubmit = (e) => {
        e.preventDefault();
        onSearch(query);
    };

    return (
        <form className="search-bar" onSubmit={handleSubmit} role="search">
            <Input
                value={query}
                onChange={(e) => setQuery(e.target.value)}
                placeholder={placeholder}
                leftIcon={<SearchIcon />}
                aria-label="Search"
            />
            <Button type="submit" variant="primary" size="md">
                Search
            </Button>
        </form>
    );
}

// ── Organism: Header (molecules + atoms composed) ──
function Header({ user, cartCount, onSearch }) {
    return (
        <header className="site-header">
            <Logo />                                    {/* atom */}
            <Navigation items={navItems} />             {/* molecule */}
            <SearchBar onSearch={onSearch} />            {/* molecule */}
            <div className="header-actions">
                <CartButton count={cartCount} />        {/* molecule */}
                <UserMenu user={user} />                {/* molecule */}
            </div>
        </header>
    );
}

// ── Template: Page layout (structure without data) ──
function DashboardLayout({ sidebar, header, children, footer }) {
    return (
        <div className="dashboard-layout">
            <aside className="sidebar">{sidebar}</aside>
            <div className="main-content">
                <div className="header">{header}</div>
                <main className="content">{children}</main>
                <div className="footer">{footer}</div>
            </div>
        </div>
    );
}

// ── Page: Template + real data ──
function DashboardPage() {
    const { data: stats } = useQuery({ queryKey: ["stats"], queryFn: fetchStats });
    const { data: user } = useAuth();

    return (
        <DashboardLayout
            sidebar={<DashboardSidebar activeItem="overview" />}
            header={<Header user={user} cartCount={0} onSearch={handleSearch} />}
            footer={<Footer />}
        >
            <h1>Welcome, {user.name}</h1>
            <StatsGrid stats={stats} />         {/* organism */}
            <RecentActivity limit={10} />       {/* organism */}
            <QuickActions />                    {/* organism */}
        </DashboardLayout>
    );
}

// ═══════════════════════════════════════
// LAYER 1: HTTP Client (lib/httpClient.ts)
// ═══════════════════════════════════════
import axios from "axios";

const httpClient = axios.create({
    baseURL: process.env.NEXT_PUBLIC_API_URL,  // https://api.myapp.com/v1
    timeout: 10_000,
    headers: { "Content-Type": "application/json" },
    withCredentials: true,  // send cookies
});

// Request interceptor: attach auth token
httpClient.interceptors.request.use((config) => {
    const token = getAuthToken();
    if (token) config.headers.Authorization = `Bearer ${token}`;
    return config;
});

// Response interceptor: transform errors, handle 401
httpClient.interceptors.response.use(
    (res) => res.data,  // unwrap: return data directly (not { data, status, headers })
    async (error) => {
        // Standardize error shape
        const apiError = {
            status: error.response?.status || 500,
            message: error.response?.data?.message || "Something went wrong",
            code: error.response?.data?.code || "UNKNOWN_ERROR",
        };

        // Auto-refresh on 401
        if (apiError.status === 401 && !error.config._retry) {
            error.config._retry = true;
            await refreshToken();
            return httpClient(error.config);
        }

        return Promise.reject(apiError);
    }
);

export { httpClient };

// ═══════════════════════════════════════
// LAYER 2: API Services (api/productApi.ts)
// ═══════════════════════════════════════
import { httpClient } from "@/lib/httpClient";
import { transformProduct, transformProductList } from "./transformers";

export const productApi = {
    getAll: async (params?: { category?: string; page?: number }) => {
        const data = await httpClient.get("/products", { params });
        return transformProductList(data);  // snake_case → camelCase
    },

    getById: async (id: string) => {
        const data = await httpClient.get(`/products/${id}`);
        return transformProduct(data);
    },

    create: async (product: CreateProductDTO) => {
        const data = await httpClient.post("/products", product);
        return transformProduct(data);
    },

    update: async (id: string, updates: UpdateProductDTO) => {
        const data = await httpClient.patch(`/products/${id}`, updates);
        return transformProduct(data);
    },

    delete: async (id: string) => {
        await httpClient.delete(`/products/${id}`);
    },

    search: async (query: string, filters?: SearchFilters) => {
        const data = await httpClient.get("/products/search", {
            params: { q: query, ...filters },
        });
        return transformProductList(data);
    },
};

// ═══════════════════════════════════════
// LAYER 2.5: Transformers (api/transformers.ts)
// ═══════════════════════════════════════
// API returns snake_case → frontend uses camelCase
interface ApiProduct {
    id: string;
    product_name: string;
    unit_price: number;
    created_at: string;
    category_info: { cat_id: string; cat_name: string };
}

interface Product {
    id: string;
    name: string;
    price: number;
    createdAt: Date;
    category: { id: string; name: string };
}

export function transformProduct(raw: ApiProduct): Product {
    return {
        id: raw.id,
        name: raw.product_name,
        price: raw.unit_price,
        createdAt: new Date(raw.created_at),
        category: { id: raw.category_info.cat_id, name: raw.category_info.cat_name },
    };
}

// ═══════════════════════════════════════
// LAYER 3: React Query Hooks (hooks/useProducts.ts)
// ═══════════════════════════════════════
import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
import { productApi } from "@/api/productApi";

export function useProducts(category?: string) {
    return useQuery({
        queryKey: ["products", { category }],
        queryFn: () => productApi.getAll({ category }),
        staleTime: 5 * 60_000,
    });
}

export function useProduct(id: string) {
    return useQuery({
        queryKey: ["products", id],
        queryFn: () => productApi.getById(id),
        enabled: !!id,  // don't fetch if no id
    });
}

export function useCreateProduct() {
    const queryClient = useQueryClient();

    return useMutation({
        mutationFn: productApi.create,
        onSuccess: () => {
            queryClient.invalidateQueries({ queryKey: ["products"] });
        },
    });
}

// ═══════════════════════════════════════
// LAYER 4: Component (just uses hooks!)
// ═══════════════════════════════════════
function ProductList() {
    const { data: products, isLoading, error } = useProducts("electronics");
    const createProduct = useCreateProduct();
    // Component knows NOTHING about fetch, axios, endpoints, auth headers
    // Swap REST → GraphQL by changing Layer 2 only
}

// ═══════════════════════════════════════
// DESIGN TOKENS (tokens/index.ts)
// ═══════════════════════════════════════

// Semantic tokens — meaningful names, not raw values
export const tokens = {
    colors: {
        primary: { 50: "#eff6ff", 500: "#3b82f6", 600: "#2563eb", 700: "#1d4ed8" },
        neutral: { 50: "#f9fafb", 100: "#f3f4f6", 700: "#374151", 900: "#111827" },
        success: { 500: "#22c55e" },
        error: { 500: "#ef4444" },
        warning: { 500: "#f59e0b" },
    },
    spacing: { xs: "4px", sm: "8px", md: "16px", lg: "24px", xl: "32px", "2xl": "48px" },
    radii: { sm: "4px", md: "8px", lg: "12px", full: "9999px" },
    fontSizes: { xs: "12px", sm: "14px", md: "16px", lg: "18px", xl: "24px", "2xl": "32px" },
    shadows: {
        sm: "0 1px 2px rgba(0,0,0,0.05)",
        md: "0 4px 6px rgba(0,0,0,0.1)",
        lg: "0 10px 25px rgba(0,0,0,0.15)",
    },
};

// ═══════════════════════════════════════
// THEMING with CSS Custom Properties
// ═══════════════════════════════════════

// themes/light.css
// :root {
//     --color-bg: #ffffff;
//     --color-text: #111827;
//     --color-primary: #3b82f6;
//     --color-surface: #f9fafb;
//     --color-border: #e5e7eb;
//     --shadow-card: 0 1px 3px rgba(0,0,0,0.1);
// }

// themes/dark.css
// [data-theme="dark"] {
//     --color-bg: #0f172a;
//     --color-text: #f1f5f9;
//     --color-primary: #60a5fa;
//     --color-surface: #1e293b;
//     --color-border: #334155;
//     --shadow-card: 0 1px 3px rgba(0,0,0,0.4);
// }

// ── Theme Provider (React) ──
function ThemeProvider({ children }) {
    const [theme, setTheme] = useState(() =>
        window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light"
    );

    useEffect(() => {
        document.documentElement.setAttribute("data-theme", theme);
    }, [theme]);

    const toggleTheme = () => setTheme(t => t === "light" ? "dark" : "light");

    return (
        <ThemeContext.Provider value={{ theme, toggleTheme }}>
            {children}
        </ThemeContext.Provider>
    );
}

// ── Component using tokens (not hardcoded values) ──
// Button.module.css
// .button {
//     background-color: var(--color-primary);
//     color: white;
//     padding: var(--spacing-sm) var(--spacing-md);
//     border-radius: var(--radius-md);
//     font-size: var(--font-size-md);
//     box-shadow: var(--shadow-sm);
// }
// .button:hover { background-color: var(--color-primary-hover); }
// /* Dark mode automatic — CSS vars change, components don't! */

// ═══════════════════════════════════════
// MULTI-BRAND / WHITE-LABEL
// ═══════════════════════════════════════

// Each brand overrides the same CSS custom properties
// brands/brand-a.css
// :root {
//     --color-primary: #3b82f6;     /* Blue */
//     --radius-md: 12px;             /* Rounded */
//     --font-family: "Inter", sans-serif;
// }

// brands/brand-b.css
// :root {
//     --color-primary: #22c55e;     /* Green */
//     --radius-md: 2px;              /* Sharp corners */
//     --font-family: "Roboto", sans-serif;
// }

// Load brand CSS based on config:
function App({ brandId }) {
    useEffect(() => {
        const link = document.createElement("link");
        link.rel = "stylesheet";
        link.href = `/brands/${brandId}.css`;
        document.head.appendChild(link);
    }, [brandId]);

    return <AppContent />;
    // Same components, completely different look per brand!
}

// ═══════════════════════════════════════
// COMPONENT LIBRARY STRUCTURE
// ═══════════════════════════════════════
/*
design-system/
├── tokens/
│   ├── colors.ts
│   ├── spacing.ts
│   ├── typography.ts
│   └── index.ts              # all tokens exported
├── themes/
│   ├── light.css
│   ├── dark.css
│   └── ThemeProvider.tsx
├── components/
│   ├── Button/
│   │   ├── Button.tsx
│   │   ├── Button.module.css
│   │   ├── Button.test.tsx
│   │   ├── Button.stories.tsx
│   │   └── index.ts
│   ├── Input/
│   ├── Modal/
│   ├── Select/
│   └── DataTable/
├── hooks/
│   ├── useTheme.ts
│   └── useMediaQuery.ts
├── .storybook/
│   └── preview.js
├── package.json
└── CHANGELOG.md               # managed by changesets
*/

// ── Consistent Component API Contract ──
// Every component follows the same prop patterns:
interface BaseComponentProps {
    variant?: "solid" | "outline" | "ghost";
    size?: "sm" | "md" | "lg";
    colorScheme?: "primary" | "success" | "error" | "warning";
    isDisabled?: boolean;
    className?: string;    // escape hatch for custom styles
}
// <Button variant="solid" size="md" colorScheme="primary" />
// <Badge variant="outline" size="sm" colorScheme="success" />
// <Alert variant="solid" colorScheme="error" />
// Predictable API → developers don't need to check docs every time