Beginner

// app/zakat/page.tsx
// => File location defines route: /zakat
// => No 'use client' directive = Server Component (default)
// => Server Components execute on server only
// => Never send component code to browser

export default async function ZakatPage() {
  // => Function name can be anything (Next.js only cares about default export)
  // => async keyword is ALLOWED in Server Components
  // => Cannot use async in Client Components
  // => Enables await for data fetching

  const nisabRate = 85;
  // => nisabRate is 85 (type: number)
  // => Represents grams of gold for Zakat threshold
  // => Variable declared with const (immutable)

  const goldPrice = 950000;
  // => goldPrice is 950000 (type: number)
  // => Indonesian Rupiah (IDR) per gram
  // => Current market price for calculation

  const nisabValue = nisabRate * goldPrice;
  // => Multiplication operation: 85 * 950000
  // => nisabValue is 80750000 (type: number)
  // => This is the Zakat threshold in IDR
  // => Below this amount, no Zakat required

  // => All calculations happen on SERVER
  // => Client receives ONLY the final HTML
  // => No client-side computation needed
  // => Zero JavaScript sent for this component

  return (
    <div>
      {/* => JSX syntax compiled to HTML on server */}
      {/* => Browser receives plain HTML, not JSX */}

      <h1>Zakat Calculator</h1>
      {/* => Static heading element */}
      {/* => No interactivity needed = perfect for Server Component */}

      <p>Gold Nisab: {nisabRate} grams</p>
      {/* => Variable interpolation with {} */}
      {/* => nisabRate value inserted: 85 */}
      {/* => Output HTML: "Gold Nisab: 85 grams" */}

      <p>Current Price: IDR {goldPrice.toLocaleString()}</p>
      {/* => toLocaleString() formats number with commas */}
      {/* => 950000 becomes "950,000" */}
      {/* => Method executes on SERVER before HTML sent */}
      {/* => Output HTML: "Current Price: IDR 950,000" */}

      <p>Nisab Value: IDR {nisabValue.toLocaleString()}</p>
      {/* => nisabValue (80750000) formatted */}
      {/* => Output HTML: "Nisab Value: IDR 80,750,000" */}
      {/* => Threshold clearly displayed for users */}
    </div>
  );
  // => Return JSX element (React component pattern)
  // => Entire component output rendered to HTML string
  // => HTML sent to client in response
  // => Zero client-side JavaScript for this component
  // => Fast page load, SEO-friendly, no hydration
}

// app/posts/page.tsx
// => File location defines route: /posts
// => Server Component (no 'use client')
// => Can use async/await for data fetching
// => Fetching happens during server render

export default async function PostsPage() {
  // => async function declaration
  // => Allows await keyword inside function body
  // => Server Components ONLY (Client Components cannot be async)

  const res = await fetch('https://jsonplaceholder.typicode.com/posts', {
    // => fetch() is standard Web API
    // => Next.js extends it with caching features
    // => First argument: URL string
    // => Second argument: options object

    next: { revalidate: 3600 }
    // => next object contains Next.js-specific options
    // => revalidate: cache duration in seconds
    // => 3600 seconds = 1 hour
    // => After 1 hour, Next.js refetches data
    // => Uses stale-while-revalidate pattern
  });
  // => await pauses execution until fetch completes
  // => res is Response object (type: Response)
  // => Contains status, headers, body
  // => Body not yet parsed (still stream)

  const posts = await res.json();
  // => await pauses until JSON parsing completes
  // => res.json() parses response body as JSON
  // => posts is array of post objects (type: any[])
  // => Structure: [{id: 1, title: "...", body: "...", userId: 1}, ...]
  // => Example: posts[0].title is "sunt aut facere repellat provident occaecati"

  return (
    <div>
      {/* => Container div element */}

      <h2>Blog Posts</h2>
      {/* => Heading level 2 */}
      {/* => Static text, no dynamic content */}

      <ul>
        {/* => Unordered list element */}
        {/* => Will contain list of posts */}

        {posts.slice(0, 5).map((post: any) => (
          // => posts.slice(0, 5) creates array of first 5 posts
          // => slice() doesn't mutate original array
          // => Returns new array with indices 0-4
          // => map() iterates over each post
          // => post parameter represents current post object
          // => Type annotation 'any' for flexibility (or use proper Post type)
          // => Returns array of JSX elements (React children)

          <li key={post.id}>
            {/* => List item element */}
            {/* => key prop REQUIRED for array children */}
            {/* => post.id is unique identifier (type: number) */}
            {/* => React uses keys for efficient reconciliation */}
            {/* => Example: key={1}, key={2}, key={3}, etc. */}

            <strong>{post.title}</strong>
            {/* => Bold text element */}
            {/* => post.title is post title string */}
            {/* => Example output: "sunt aut facere repellat provident occaecati" */}
            {/* => Wrapped in {} for JavaScript expression */}

            <p>{post.body.slice(0, 100)}...</p>
            {/* => Paragraph element */}
            {/* => post.body is post content (type: string) */}
            {/* => slice(0, 100) gets first 100 characters */}
            {/* => "..." appended for truncation indicator */}
            {/* => Example: "quia et suscipit\nsuscipit recusandae consequuntur..." */}
          </li>
        ))}
        {/* => Closing map() iteration */}
        {/* => Produces 5 <li> elements total */}
      </ul>
    </div>
  );
  // => Component return statement
  // => Data fetching completes BEFORE return
  // => Client receives fully rendered HTML with post data
  // => No loading states needed (server waits for data)
  // => SEO-friendly (search engines see full content)
}

// app/counter/page.tsx
// => File location defines route: /counter
// => NO 'use client' directive = Server Component (default)
// => Server Components CAN import and render Client Components
// => This creates boundary between server and client

import CounterButton from './CounterButton';
// => Relative import from same directory
// => CounterButton is Client Component (has 'use client')
// => Next.js handles code-splitting automatically

export default function CounterPage() {
  // => Regular function (not async)
  // => Server Component rendering static wrapper

  return (
    <div>
      {/* => Container div */}

      <h1>Donation Counter</h1>
      {/* => Static heading */}
      {/* => Rendered on server */}
      {/* => Sent as HTML to client */}
      {/* => No JavaScript needed for heading */}

      <CounterButton />
      {/* => Client Component usage */}
      {/* => This is the SERVER/CLIENT BOUNDARY */}
      {/* => Everything inside CounterButton runs on client */}
      {/* => Server passes initial props (none here) */}
      {/* => Client receives component code and hydrates */}
    </div>
  );
  // => Component returns JSX
  // => Heading rendered on server
  // => CounterButton placeholder sent
  // => Client JavaScript hydrates CounterButton
}

// app/counter/CounterButton.tsx
// => Separate file for Client Component
// => Must have 'use client' directive at top

'use client';
// => CRITICAL: This directive REQUIRED for Client Components
// => Tells Next.js to bundle this for client
// => Enables React hooks (useState, useEffect, etc.)
// => Enables event handlers (onClick, onChange, etc.)
// => Enables browser APIs (window, document, localStorage)
// => Without this: "You're importing a component that needs useState" error

import { useState } from 'react';
// => Import useState hook from React
// => Only works in Client Components
// => Cannot use in Server Components
// => Manages component state on client

export default function CounterButton() {
  // => Client Component function
  // => Runs in browser, not on server
  // => Can use all React hooks

  const [count, setCount] = useState(0);
  // => useState creates state variable
  // => count is current value (starts at 0)
  // => setCount is updater function
  // => State persists across re-renders
  // => Initial value: count is 0 (type: number)

  const handleClick = () => {
    // => Event handler function
    // => Arrow function for concise syntax
    // => Called when button clicked

    setCount(count + 1);
    // => Updates count to count + 1
    // => If count is 0, becomes 1
    // => If count is 5, becomes 6
    // => Triggers component re-render
    // => New count value reflected in UI
  };
  // => handleClick is function (type: () => void)

  return (
    <div>
      {/* => Container div */}

      <p>Donations: {count}</p>
      {/* => Paragraph with dynamic count */}
      {/* => Initial render: "Donations: 0" */}
      {/* => After 1 click: "Donations: 1" */}
      {/* => After 2 clicks: "Donations: 2" */}
      {/* => count variable interpolated with {} */}
      {/* => Updates when state changes */}

      <button onClick={handleClick}>
        {/* => Button element with click handler */}
        {/* => onClick prop attaches event listener */}
        {/* => handleClick function called on click */}
        {/* => onClick ONLY works in Client Components */}
        {/* => Server Components cannot handle events */}
        Donate
        {/* => Button text */}
      </button>
    </div>
  );
  // => Component returns JSX
  // => Runs in browser on every state update
  // => Re-renders when count changes
  // => React efficiently updates only changed parts
}

// app/page.tsx
// => File location: app/page.tsx
// => Creates route: "/" (root/homepage)
// => Special filename: MUST be "page.tsx" or "page.js"
// => Other filenames (like "home.tsx") NOT publicly accessible
// => Only page.tsx files create routes

export default function HomePage() {
  // => Component name can be anything (HomePage, Page, etc.)
  // => Next.js only cares about default export
  // => This renders at domain.com/

  return (
    <div>
      {/* => Root page content */}

      <h1>Welcome to Islamic Finance Platform</h1>
      {/* => Page heading */}
      {/* => Visible at homepage */}

      <p>Learn about Sharia-compliant financial products.</p>
      {/* => Descriptive text */}
      {/* => Explains platform purpose */}
    </div>
  );
  // => Returns homepage UI
  // => Accessible at: domain.com/
  // => Example: localhost:3000/
}

// app/about/page.tsx
// => File location: app/about/page.tsx
// => Folder name: "about"
// => File name: "page.tsx" (special)
// => Creates route: "/about"
// => Pattern: folder name becomes route path
// => Accessible at domain.com/about

export default function AboutPage() {
  // => About page component
  // => Renders when user navigates to /about

  return (
    <div>
      {/* => About page content */}

      <h1>About Us</h1>
      {/* => About page heading */}

      <p>We provide Sharia-compliant financial education.</p>
      {/* => About page description */}
    </div>
  );
  // => Returns about page UI
  // => Accessible at: domain.com/about
  // => Example: localhost:3000/about
}

// app/products/murabaha/page.tsx
// => File location: app/products/murabaha/page.tsx
// => Nested folder structure: products/murabaha
// => Each folder becomes path segment
// => Creates route: "/products/murabaha"
// => Pattern: folder/subfolder structure maps to URL path
// => Accessible at domain.com/products/murabaha

export default function MurabahaPage() {
  // => Murabaha product page component
  // => Nested route example

  return (
    <div>
      {/* => Product page content */}

      <h1>Murabaha Financing</h1>
      {/* => Product heading */}

      <p>Cost-plus financing for asset purchases.</p>
      {/* => Product description */}
      {/* => Explains Murabaha concept */}
    </div>
  );
  // => Returns product page UI
  // => Accessible at: domain.com/products/murabaha
  // => Example: localhost:3000/products/murabaha
  // => Folder structure = URL structure
  // => app/products/murabaha/page.tsx → /products/murabaha
}

// app/layout.tsx
// => File location: app/layout.tsx
// => Special filename: MUST be "layout.tsx" or "layout.js"
// => Root layout: wraps ALL pages in entire application
// => REQUIRED file - every Next.js app MUST have this
// => Cannot be deleted or renamed
// => Runs on every page

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
  // => Type annotation for children prop
  // => React.ReactNode accepts any valid React child
  // => Includes: JSX elements, strings, numbers, arrays, fragments, null
}) {
  // => children parameter receives page content automatically
  // => Next.js passes current page as children
  // => Different page = different children
  // => Layout component wraps children

  return (
    <html lang="en">
      {/* => Opening <html> tag */}
      {/* => REQUIRED in root layout */}
      {/* => Only root layout can have <html> */}
      {/* => lang="en" sets document language */}

      <body>
        {/* => Opening <body> tag */}
        {/* => REQUIRED in root layout */}
        {/* => Only root layout can have <body> */}
        {/* => All page content goes inside body */}

        <header>
          {/* => Header section */}
          {/* => Visible on ALL pages */}
          {/* => Stays mounted during navigation */}
          {/* => Does NOT re-render on page change */}

          <nav>Islamic Finance Platform</nav>
          {/* => Navigation text */}
          {/* => Could contain links (see Example 6) */}
          {/* => Persists across routes */}
        </header>

        <main>
          {/* => Main content area */}
          {/* => Semantic HTML5 element */}

          {children}
          {/* => Children prop renders here */}
          {/* => For /: renders HomePage content */}
          {/* => For /about: renders AboutPage content */}
          {/* => For /products/murabaha: renders MurabahaPage content */}
          {/* => THIS is what changes on navigation */}
          {/* => Header and footer stay the same */}
        </main>

        <footer>© 2026 Islamic Finance</footer>
        {/* => Footer section */}
        {/* => Visible on ALL pages */}
        {/* => Stays mounted during navigation */}
        {/* => Copyright notice */}
      </body>
    </html>
  );
  // => Component return
  // => Layout persists across all pages
  // => Only children slot changes on navigation
  // => Prevents header/footer re-render
  // => Improves performance
  // => Maintains scroll position in nav/footer
}

// app/products/layout.tsx
// => File location: app/products/layout.tsx
// => Nested layout: only wraps /products/* routes
// => Does NOT wrap other routes (/, /about, etc.)
// => Inherits from root layout (wrapped by root)
// => Layout nesting: RootLayout > ProductsLayout > Page

export default function ProductsLayout({
  children,
}: {
  children: React.ReactNode;
  // => Type annotation for children
  // => Same as root layout
}) {
  // => children receives product page content
  // => For /products/murabaha: receives MurabahaPage
  // => For /products/ijarah: receives IjarahPage

  return (
    <div>
      {/* => Container div */}
      {/* => NOT <html> or <body> (only root layout has those) */}

      <aside>
        {/* => Sidebar element */}
        {/* => Semantic HTML5 element for side content */}
        {/* => Visible on ALL /products/* pages */}
        {/* => Does NOT appear on /, /about, etc. */}

        <h3>Products</h3>
        {/* => Sidebar heading */}

        <ul>
          {/* => Product list */}
          {/* => Could be links (see Example 6) */}

          <li>Murabaha</li>
          {/* => Product 1 */}

          <li>Ijarah</li>
          {/* => Product 2 */}

          <li>Musharakah</li>
          {/* => Product 3 */}
        </ul>
      </aside>

      <div>
        {/* => Main content area */}

        {children}
        {/* => Product page content renders here */}
        {/* => For /products/murabaha: MurabahaPage content */}
        {/* => Sidebar stays, only THIS changes */}
      </div>
    </div>
  );
  // => Component return
  // => Nesting structure: RootLayout wraps this layout
  // => This layout wraps product pages
  // => Full nesting: <html><body><header/><main><aside/><div>PAGE</div></main><footer/></body></html>
  // => Sidebar persists when navigating between products
  // => Only page content (children) re-renders
}

// app/page.tsx
// => File location: app/page.tsx (homepage)
// => Using Link component for navigation

import Link from 'next/link';
// => Import Link from 'next/link' package
// => NOT from 'react-router' (different framework)
// => Next.js has its own routing system
// => Link component is built-in

export default function HomePage() {
  // => Homepage component

  return (
    <div>
      {/* => Page container */}

      <h1>Islamic Finance Courses</h1>
      {/* => Page heading */}

      <nav>
        {/* => Navigation section */}
        {/* => Semantic HTML5 element */}

        <Link href="/courses/zakat">
          {/* => Link component (NOT <a> tag) */}
          {/* => href prop specifies destination */}
          {/* => Must start with / for internal routes */}
          {/* => Route: /courses/zakat */}
          {/* => Prefetching: Link automatically prefetches on hover */}
          {/* => When user hovers, Next.js loads /courses/zakat in background */}
          {/* => Click becomes INSTANT (already loaded) */}
          {/* => Client-side navigation (no full page reload) */}

          Zakat Calculation
          {/* => Link text */}
          {/* => What user sees and clicks */}
        </Link>
        {/* => Link renders as <a> tag in HTML */}
        {/* => But behaves differently (client-side routing) */}

        <Link href="/courses/murabaha">
          {/* => Second link */}
          {/* => Same behavior: prefetch on hover */}
          {/* => Instant navigation on click */}

          Murabaha Basics
          {/* => Link text */}
        </Link>
        {/* => Multiple links on same page work fine */}
        {/* => Each prefetches independently */}

        <Link href="/about">
          {/* => Third link */}
          {/* => Route: /about */}

          About Us
        </Link>
      </nav>

      <a href="https://example.com" target="_blank" rel="noopener noreferrer">
        {/* => Regular <a> tag for EXTERNAL links */}
        {/* => Use Link for internal routes only */}
        {/* => <a> for external URLs */}
        {/* => href="https://..." (absolute URL) */}
        {/* => target="_blank" opens in new tab */}
        {/* => rel="noopener noreferrer" security attributes */}
        {/* => noopener: prevents new window from accessing window.opener */}
        {/* => noreferrer: prevents passing referrer information */}
        {/* => NO prefetching for external links */}

        External Resource
        {/* => Link text for external site */}
      </a>
      {/* => External link opens in new tab */}
      {/* => Full page navigation to external site */}
    </div>
  );
  // => Component return
  // => Link components enable fast, client-side navigation
  // => Prefetching makes clicks feel instant
  // => Application state preserved (no full reload)
}

// app/products/[id]/page.tsx
// => File location: app/products/[id]/page.tsx
// => [id] folder name with BRACKETS = dynamic route segment
// => Folder name MUST have brackets: [paramName]
// => paramName can be anything: [id], [slug], [productId], etc.
// => Matches ANY URL like /products/ANYTHING
// => Examples:
// =>   /products/1 → params.id is "1"
// =>   /products/murabaha → params.id is "murabaha"
// =>   /products/abc123 → params.id is "abc123"
// => Does NOT match /products (no ID segment)

type PageProps = {
  params: { id: string };
  // => TypeScript type for props
  // => params object has id property
  // => id matches folder name [id]
  // => Always string type (URL segments are strings)
};
// => PageProps is type definition (not runtime value)
// => Provides type safety for params

export default function ProductPage({ params }: PageProps) {
  // => Component receives props object
  // => Destructures params from props
  // => params passed automatically by Next.js
  // => No need to parse URL manually
  // => Next.js extracts [id] from URL path

  // => For URL /products/murabaha:
  // =>   params is { id: "murabaha" }
  // =>   params.id is "murabaha" (type: string)

  // => For URL /products/123:
  // =>   params is { id: "123" }
  // =>   params.id is "123" (type: string, NOT number)
  // =>   Need parseInt() if expecting number

  return (
    <div>
      {/* => Product page container */}

      <h1>Product: {params.id}</h1>
      {/* => Dynamic heading with product ID */}
      {/* => For /products/murabaha: "Product: murabaha" */}
      {/* => For /products/ijarah: "Product: ijarah" */}
      {/* => params.id value interpolated */}

      <p>Viewing details for product {params.id}</p>
      {/* => Paragraph using same params.id */}
      {/* => Can use params.id multiple times */}
      {/* => Could fetch product data using this ID */}
    </div>
  );
  // => Component returns JSX
  // => Different params.id for each URL
  // => Single component handles infinite products
}

// app/blog/[year]/[month]/[slug]/page.tsx
// => File location: app/blog/[year]/[month]/[slug]/page.tsx
// => THREE dynamic segments in path
// => [year] folder contains [month] folder contains [slug] folder
// => Nested dynamic routes
// => Matches /blog/YEAR/MONTH/SLUG
// => Example: /blog/2026/01/zakat-guide
// =>   year is "2026"
// =>   month is "01"
// =>   slug is "zakat-guide"

type BlogPageProps = {
  params: {
    year: string;
    // => First dynamic segment [year]
    // => Always string type
    // => Example: "2026", "2025", etc.

    month: string;
    // => Second dynamic segment [month]
    // => Always string type
    // => Example: "01", "12", etc.
    // => Note: "01" not 1 (string, not number)

    slug: string;
    // => Third dynamic segment [slug]
    // => Always string type
    // => Example: "zakat-guide", "murabaha-basics"
  };
};
// => Type defines all three params
// => Each matches folder name in brackets

export default function BlogPostPage({ params }: BlogPageProps) {
  // => Component receives all three params
  // => For URL /blog/2026/01/zakat-guide:
  // =>   params.year is "2026"
  // =>   params.month is "01"
  // =>   params.slug is "zakat-guide"

  return (
    <div>
      {/* => Blog post container */}

      <h1>Blog Post: {params.slug}</h1>
      {/* => Dynamic heading with post slug */}
      {/* => For /blog/2026/01/zakat-guide: "Blog Post: zakat-guide" */}
      {/* => slug typically used as URL-friendly identifier */}

      <time>
        {/* => Time element for semantic date */}

        {params.month}/{params.year}
        {/* => Date formatted as month/year */}
        {/* => For /blog/2026/01/zakat-guide: "01/2026" */}
        {/* => String concatenation: "01" + "/" + "2026" */}
        {/* => Could parse to Date for better formatting */}
      </time>
    </div>
  );
  // => Component returns JSX
  // => Three dynamic params from URL
  // => Single component handles infinite blog posts
  // => Could fetch post using year, month, slug combination
}

// app/donate/page.tsx
// => File location: app/donate/page.tsx
// => Server Component (default, no 'use client')
// => Can define and use Server Actions inline
// => No API routes needed for form handling

async function handleDonation(formData: FormData) {
  // => Server Action: async function handling form submission
  // => Parameter: FormData object (browser API for form data)
  // => FormData passed automatically by Next.js when form submits

  'use server';
  // => CRITICAL directive: marks function as Server Action
  // => Must be first statement in function (before any code)
  // => Without this: function would try to run on client (error)
  // => With this: Next.js creates server endpoint automatically
  // => Function body runs on server, never sent to browser

  const name = formData.get('name') as string;
  // => Extract 'name' field from form
  // => formData.get() returns FormDataEntryValue (string | File | null)
  // => 'as string' type assertion (we know it's string from input type="text")
  // => For form: <input name="name" value="Ahmad" />
  // =>   name is "Ahmad"
  // => Field name must match input's name attribute

  const amount = formData.get('amount') as string;
  // => Extract 'amount' field from form
  // => For form: <input name="amount" value="100000" />
  // =>   amount is "100000" (string, not number!)
  // => input type="number" still returns string from FormData
  // => Need parseInt() or Number() for math operations

  console.log(`Donation from ${name}: IDR ${amount}`);
  // => Log to SERVER console (not browser console)
  // => For name="Ahmad", amount="100000":
  // =>   Server output: "Donation from Ahmad: IDR 100000"
  // => Useful for debugging
  // => Production: replace with proper logging

  // await db.donations.create({ name, amount: parseInt(amount) });
  // => Example database operation (commented out)
  // => Server Actions can access database directly
  // => No need for separate API route
  // => Could use Prisma, Drizzle, or any database library
  // => parseInt(amount) converts "100000" to 100000 (number)
}
// => Server Action ends
// => Next.js generates server endpoint for this function
// => Endpoint URL generated automatically (not visible in code)
// => Form submission POSTs to this endpoint

export default function DonatePage() {
  // => Page component
  // => Server Component (renders on server)

  return (
    <div>
      {/* => Page container */}

      <h1>Make a Donation</h1>
      {/* => Page heading */}

      <form action={handleDonation}>
        {/* => Form element with Server Action */}
        {/* => action prop accepts Server Action function */}
        {/* => Traditional HTML: action="/api/donate" (URL string) */}
        {/* => Next.js: action={handleDonation} (function reference) */}
        {/* => On submit: Next.js POSTs form data to server endpoint */}
        {/* => handleDonation executes on server */}
        {/* => Progressive enhancement: works WITHOUT client JavaScript */}
        {/* => If JS disabled: traditional form POST */}
        {/* => If JS enabled: enhanced with client-side handling */}

        <label>
          {/* => Label for name input */}

          Name:
          {/* => Label text */}

          <input type="text" name="name" required />
          {/* => Text input for donor name */}
          {/* => type="text": single-line text input */}
          {/* => name="name": CRITICAL - FormData key */}
          {/* =>   formData.get('name') retrieves this value */}
          {/* =>   Must match string in Server Action */}
          {/* => required: HTML5 validation (must fill before submit) */}
          {/* => Browser blocks submit if empty */}
        </label>

        <label>
          {/* => Label for amount input */}

          Amount (IDR):
          {/* => Label text with currency indicator */}

          <input type="number" name="amount" required />
          {/* => Number input for donation amount */}
          {/* => type="number": numeric input with spinner controls */}
          {/* =>   Browser shows up/down arrows */}
          {/* =>   Mobile keyboard shows numeric layout */}
          {/* => name="amount": FormData key for amount */}
          {/* => required: must fill before submit */}
          {/* => Note: FormData.get('amount') returns STRING "100000" not number */}
        </label>

        <button type="submit">Donate</button>
        {/* => Submit button */}
        {/* => type="submit": triggers form submission */}
        {/* => Click executes handleDonation on server */}
        {/* => Works without JavaScript (native form submission) */}
        {/* => With JavaScript: enhanced with loading states */}
      </form>
      {/* => Form ends */}
      {/* => Submission flow: */}
      {/* =>   1. User fills name="Ahmad", amount="100000" */}
      {/* =>   2. Clicks submit button */}
      {/* =>   3. Browser creates FormData with { name: "Ahmad", amount: "100000" } */}
      {/* =>   4. Next.js POSTs to server endpoint */}
      {/* =>   5. handleDonation runs on server */}
      {/* =>   6. Server logs donation */}
      {/* =>   7. Page refreshes (default behavior) */}
    </div>
  );
  // => Component returns form UI
  // => Server Action enables backend logic without API routes
  // => Progressive enhancement: works with or without JavaScript
}

// app/zakat/calculate/page.tsx
// => File location: app/zakat/calculate/page.tsx
// => Server Component with validated Server Action
// => Shows server-side validation pattern

type ActionResult = {
  success: boolean;
  // => Boolean flag indicating validation success
  // => true: calculation succeeded
  // => false: validation failed

  message?: string;
  // => Optional error/success message
  // => ?: means property may be undefined
  // => Present for both success and error cases
  // => Example: "Zakat calculated successfully" or "Invalid input"

  zakatAmount?: number;
  // => Optional calculated zakat amount
  // => Only present when success is true
  // => Undefined when validation fails
  // => Example: 2500000 (IDR 2.5 million)
};
// => Type defines contract for Server Action return value
// => Enables type-safe result handling in Client Components
// => All Server Action results should be serializable (JSON-compatible)

async function calculateZakat(formData: FormData): Promise<ActionResult> {
  // => Server Action with return type annotation
  // => Promise<ActionResult>: async function returning ActionResult
  // => FormData parameter receives form data

  'use server';
  // => Server Action directive
  // => Function executes on server only
  // => Can return values to client (serialized as JSON)

  const wealthStr = formData.get('wealth') as string;
  // => Extract wealth input from form
  // => formData.get() returns string | File | null
  // => 'as string' assertion (we know it's string from type="number")
  // => For input value "100000000":
  // =>   wealthStr is "100000000" (string, not number)

  const wealth = parseInt(wealthStr);
  // => Convert string to integer
  // => parseInt("100000000") returns 100000000 (number)
  // => parseInt("abc") returns NaN (Not a Number)
  // => parseInt("") returns NaN
  // => Need to validate for NaN

  if (isNaN(wealth)) {
    // => Check if parsing failed
    // => isNaN(100000000) is false (valid number)
    // => isNaN(NaN) is true (invalid input)
    // => Catches: empty string, non-numeric text, null

    return {
      success: false,
      // => Validation failed

      message: 'Please enter a valid number',
      // => User-friendly error message
      // => Client can display this to user
    };
    // => Return early: stops execution
    // => Result sent back to client
  }

  if (wealth < 0) {
    // => Validate non-negative
    // => -100000 would fail this check
    // => 0 passes (acceptable, no zakat due)

    return {
      success: false,
      message: 'Wealth cannot be negative',
      // => Business logic validation
      // => Negative wealth doesn't make sense
    };
    // => Early return on validation failure
  }

  const nisab = 85 * 950000;
  // => Calculate nisab threshold
  // => Nisab: minimum wealth requiring zakat
  // => 85 grams gold (standard nisab measure)
  // => 950000: gold price per gram in IDR
  // => 85 * 950000 = 80,750,000 IDR
  // => nisab is 80750000 (constant for this example)

  if (wealth < nisab) {
    // => Check if wealth meets minimum threshold
    // => wealth=50000000 < nisab=80750000: below threshold
    // => wealth=100000000 > nisab=80750000: above threshold, zakat due

    return {
      success: false,
      message: `Wealth below nisab threshold (IDR ${nisab.toLocaleString()})`,
      // => Template string with formatted nisab
      // => nisab.toLocaleString() formats 80750000 as "80,750,000"
      // => Message: "Wealth below nisab threshold (IDR 80,750,000)"
      // => Informative: tells user the threshold
    };
    // => Not an error, but no zakat due
    // => Still returns success: false
  }

  const zakatAmount = wealth * 0.025;
  // => Calculate 2.5% zakat (Islamic standard rate)
  // => For wealth=100000000:
  // =>   zakatAmount = 100000000 * 0.025
  // =>   zakatAmount = 2500000 (2.5 million IDR)
  // => 0.025 = 2.5/100 = 2.5%

  return {
    success: true,
    // => Validation passed, calculation succeeded

    message: 'Zakat calculated successfully',
    // => Success message

    zakatAmount,
    // => Shorthand for zakatAmount: zakatAmount
    // => Includes calculated amount in result
    // => Client can display this to user
    // => Example: 2500000
  };
  // => Success result with zakat amount
  // => Client receives: { success: true, message: "...", zakatAmount: 2500000 }
}
// => Server Action ends
// => Demonstrates complete validation workflow:
// =>   1. Extract and parse input
// =>   2. Validate format (NaN check)
// =>   3. Validate business rules (negative, nisab)
// =>   4. Perform calculation
// =>   5. Return structured result

export default function ZakatCalculatorPage() {
  // => Page component
  // => This is basic version (no result display)

  return (
    <div>
      {/* => Page container */}

      <h1>Zakat Calculator</h1>
      {/* => Page heading */}

      <form action={calculateZakat}>
        {/* => Form calling validated Server Action */}
        {/* => calculateZakat executes on server */}
        {/* => Return value available via useFormState (intermediate example) */}

        <label>
          {/* => Label for wealth input */}

          Total Wealth (IDR):
          {/* => Label text with currency */}

          <input type="number" name="wealth" required />
          {/* => Number input for wealth */}
          {/* => name="wealth": matches formData.get('wealth') */}
          {/* => required: client-side validation (first line of defense) */}
          {/* => Server-side validation ALSO required (security) */}
          {/* => Client validation can be bypassed (curl, disabled JS) */}
        </label>

        <button type="submit">Calculate</button>
        {/* => Submit button triggers Server Action */}
        {/* => Server validates and calculates */}
        {/* => Result returned to client */}
      </form>

      {/* => Result display would use useFormState hook */}
      {/* => See intermediate examples for full implementation */}
      {/* => useFormState returns [state, formAction] */}
      {/* => state contains ActionResult */}
      {/* => Can conditionally render: */}
      {/* =>   {state.success && <p>Zakat: IDR {state.zakatAmount}</p>} */}
      {/* =>   {!state.success && <p>Error: {state.message}</p>} */}
    </div>
  );
  // => Component returns calculator UI
  // => Demonstrates server-side validation importance
  // => NEVER trust client-side validation alone
}

// app/actions.ts
// => File location: app/actions.ts (root of app directory)
// => Separate file for reusable Server Actions
// => Multiple pages can import and use these actions
// => Centralized location for data mutations

'use server';
// => File-level 'use server' directive
// => When at TOP of file (before imports):
// =>   ALL exported functions are Server Actions
// =>   No need to repeat 'use server' in each function
// => Alternative: per-function 'use server' inside function body
// => File-level: cleaner for files with only Server Actions

import { revalidatePath } from 'next/cache';
// => Import revalidation utility from Next.js
// => revalidatePath: invalidates cache for specific route
// => Forces Next.js to re-fetch data on next request
// => Essential after data mutations (create, update, delete)

export async function addPost(formData: FormData) {
  // => Exported Server Action
  // => 'export' makes it importable in other files
  // => 'async' because database operations are asynchronous
  // => No need for 'use server' here (covered by file-level directive)

  const title = formData.get('title') as string;
  // => Extract title from form
  // => For input: <input name="title" value="New Post" />
  // =>   title is "New Post"

  const content = formData.get('content') as string;
  // => Extract content from form
  // => For textarea: <textarea name="content">Post content...</textarea>
  // =>   content is "Post content..."

  // await db.posts.create({ title, content });
  // => Database mutation (commented for example)
  // => In production: use Prisma, Drizzle, or other ORM
  // => Example with Prisma:
  // =>   await prisma.post.create({
  // =>     data: { title, content, published: true }
  // =>   });
  // => Creates new post record in database
  // => Returns created post object

  console.log(`Created post: ${title}`);
  // => Server-side logging
  // => For title="New Post":
  // =>   Server console: "Created post: New Post"
  // => Confirms mutation executed
  // => Production: use structured logging (Winston, Pino)

  revalidatePath('/posts');
  // => CRITICAL: Invalidate cache for /posts route
  // => Why needed: Next.js caches page renders for performance
  // => After adding post, cache shows OLD data (missing new post)
  // => revalidatePath('/posts'):
  // =>   1. Marks /posts cache as stale
  // =>   2. Next request to /posts triggers re-render
  // =>   3. Fresh data fetched from database
  // =>   4. New post appears in list
  // => Without this: users see stale data until cache expires
  // => Argument must be exact path string: '/posts', '/blog', etc.
}
// => Server Action ends
// => Can be imported and used in any Server Component
// => Enables code reuse across multiple forms

// app/posts/new/page.tsx
// => File location: app/posts/new/page.tsx
// => Page for creating new posts
// => Route: /posts/new

import { addPost } from '@/app/actions';
// => Import Server Action from centralized file
// => '@/app' is alias for app directory (configured in tsconfig.json)
// => Full path: /app/actions.ts
// => Can import in multiple pages/components

export default function NewPostPage() {
  // => Page component for post creation

  return (
    <div>
      {/* => Page container */}

      <h1>Create Post</h1>
      {/* => Page heading */}

      <form action={addPost}>
        {/* => Form using imported Server Action */}
        {/* => addPost defined in separate file */}
        {/* => Same behavior as inline Server Action */}
        {/* => Benefit: reusable across multiple components */}

        <label>
          {/* => Title label */}

          Title:
          {/* => Label text */}

          <input type="text" name="title" required />
          {/* => Title input */}
          {/* => name="title": matches formData.get('title') */}
          {/* => required: client-side validation */}
        </label>

        <label>
          {/* => Content label */}

          Content:
          {/* => Label text */}

          <textarea name="content" required />
          {/* => Multi-line text input for content */}
          {/* => name="content": matches formData.get('content') */}
          {/* => required: must fill before submit */}
        </label>

        <button type="submit">Publish</button>
        {/* => Submit button */}
        {/* => Triggers addPost Server Action */}
        {/* => Flow: */}
        {/* =>   1. User fills form */}
        {/* =>   2. Clicks Publish */}
        {/* =>   3. addPost executes on server */}
        {/* =>   4. Post saved to database */}
        {/* =>   5. /posts cache invalidated */}
        {/* =>   6. User redirected (could use redirect() from next/navigation) */}
      </form>
      {/* => Form ends */}
    </div>
  );
  // => Component returns form UI
  // => Uses imported Server Action for reusability
  // => Could have multiple forms using same action
}

// app/dashboard/page.tsx
// => File location: app/dashboard/page.tsx
// => Server Component with parallel data fetching
// => Demonstrates performance optimization with Promise.all

async function getUser() {
  // => Async function simulating user API call
  // => In production: fetch('https://api.example.com/user')

  await new Promise(resolve => setTimeout(resolve, 1000));
  // => Simulate network delay
  // => new Promise(...) creates pending promise
  // => setTimeout(resolve, 1000) resolves after 1000ms (1 second)
  // => await pauses execution for 1 second
  // => Mimics real API latency

  return { name: 'Ahmad', email: 'ahmad@example.com' };
  // => Return user object
  // => Structure: { name: string, email: string }
  // => In production: await (await fetch(...)).json()
}
// => Function completes in ~1 second

async function getDonations() {
  // => Async function simulating donations API call

  await new Promise(resolve => setTimeout(resolve, 1000));
  // => 1 second simulated delay

  return [
    { id: 1, amount: 100000 },
    { id: 2, amount: 250000 },
  ];
  // => Return donation array
  // => Each item: { id: number, amount: number }
  // => Example: 100000 = IDR 100,000
}
// => Function completes in ~1 second

async function getStats() {
  // => Async function simulating statistics API call

  await new Promise(resolve => setTimeout(resolve, 1000));
  // => 1 second simulated delay

  return { totalDonations: 350000, donorCount: 2 };
  // => Return stats object
  // => totalDonations: sum of all donations
  // => donorCount: number of unique donors
  // => Could be aggregated from database query
}
// => Function completes in ~1 second

export default async function DashboardPage() {
  // => Page component (async Server Component)
  // => 'async' keyword enables await in component body
  // => Can fetch data directly without useEffect

  const [user, donations, stats] = await Promise.all([
    getUser(),
    getDonations(),
    getStats(),
  ]);
  // => PARALLEL data fetching with Promise.all
  // => Promise.all([...]) accepts array of promises
  // => Executes ALL promises SIMULTANEOUSLY
  // => Waits for ALL to complete
  // => Returns array of results (same order as input)
  // => Timing:
  // =>   T=0ms: All three fetch functions start
  // =>   T=1000ms: All three complete (parallel execution)
  // =>   Total time: ~1 second
  // => Array destructuring: [user, donations, stats]
  // =>   user = result from getUser() = { name: 'Ahmad', email: '...' }
  // =>   donations = result from getDonations() = [{ id: 1, ... }, ...]
  // =>   stats = result from getStats() = { totalDonations: 350000, ... }
  // => SEQUENTIAL alternative (BAD):
  // =>   const user = await getUser();       // Wait 1s
  // =>   const donations = await getDonations();  // Wait 1s
  // =>   const stats = await getStats();     // Wait 1s
  // =>   Total: 3 seconds (3x slower!)
  // => Promise.all is CRITICAL for performance

  return (
    <div>
      {/* => Dashboard container */}

      <h1>Dashboard for {user.name}</h1>
      {/* => Dynamic heading with user name */}
      {/* => user.name is "Ahmad" */}
      {/* => Output: "Dashboard for Ahmad" */}

      <div>
        {/* => Statistics section */}

        <h2>Statistics</h2>
        {/* => Section heading */}

        <p>Total: IDR {stats.totalDonations.toLocaleString()}</p>
        {/* => Total donations formatted */}
        {/* => stats.totalDonations is 350000 */}
        {/* => toLocaleString() formats as "350,000" */}
        {/* => Output: "Total: IDR 350,000" */}

        <p>Donors: {stats.donorCount}</p>
        {/* => Donor count */}
        {/* => stats.donorCount is 2 */}
        {/* => Output: "Donors: 2" */}
      </div>

      <div>
        {/* => Donations section */}

        <h2>Recent Donations</h2>
        {/* => Section heading */}

        <ul>
          {/* => Unordered list */}

          {donations.map(donation => (
            <li key={donation.id}>
              {/* => List item for each donation */}
              {/* => key={donation.id}: React key for list items */}
              {/* => Required for efficient re-rendering */}
              {/* => Must be unique (id is unique) */}

              IDR {donation.amount.toLocaleString()}
              {/* => Formatted donation amount */}
              {/* => For donation { id: 1, amount: 100000 }: */}
              {/* =>   Output: "IDR 100,000" */}
              {/* => For donation { id: 2, amount: 250000 }: */}
              {/* =>   Output: "IDR 250,000" */}
            </li>
          ))}
          {/* => map() iterates donations array */}
          {/* => Creates <li> for each donation */}
          {/* => donations has 2 items = 2 <li> elements */}
        </ul>
      </div>
    </div>
  );
  // => Component returns dashboard UI
  // => All data fetched in parallel (fast)
  // => Total page load: ~1 second (not 3 seconds)
  // => Promise.all enables efficient data loading
}

// app/components/Header.tsx
// => File location: app/components/Header.tsx
// => Server Component that fetches user data

async function getUser() {
  // => Shared async function for fetching user
  // => Used by multiple components

  console.log('Fetching user data...');
  // => Server console log
  // => Used to verify deduplication behavior
  // => Without dedupe: logs multiple times
  // => With dedupe: logs only ONCE despite multiple calls

  const res = await fetch('https://api.example.com/user');
  // => HTTP GET request to user API
  // => fetch() returns Response object
  // => await pauses until response received

  return res.json();
  // => Parse JSON response body
  // => Returns: { name: "Fatima", role: "admin" }
  // => Async operation: await needed when calling
}
// => Function can be called multiple times in same render
// => Next.js AUTOMATICALLY deduplicates identical requests

export async function Header() {
  // => Header component (async Server Component)
  // => 'async' enables await inside component

  const user = await getUser();
  // => FIRST call to getUser() in this render pass
  // => Next.js executes actual network request
  // => Result cached for this render pass
  // => user is { name: "Fatima", role: "admin" }

  return (
    <header>
      {/* => Header element */}

      <span>Welcome, {user.name}</span>
      {/* => Greeting with user name */}
      {/* => user.name is "Fatima" */}
      {/* => Output: "Welcome, Fatima" */}
    </header>
  );
  // => Component returns header UI
  // => Used user data from getUser()
}

// app/components/Sidebar.tsx
// => File location: app/components/Sidebar.tsx
// => Different component, SAME fetch function

export async function Sidebar() {
  // => Sidebar component (async Server Component)

  const user = await getUser();
  // => SECOND call to getUser() in same render pass
  // => Next.js detects DUPLICATE request
  // => Request deduplication:
  // =>   1. Checks if identical fetch already in progress/completed
  // =>   2. Reuses cached result from Header's call
  // =>   3. NO second network request made
  // =>   4. Returns same user object instantly
  // => user is { name: "Fatima", role: "admin" } (cached)
  // => Timing:
  // =>   Header's getUser(): 100ms network request
  // =>   Sidebar's getUser(): 0ms (cached, instant)
  // => console.log only appears ONCE in server console

  return (
    <aside>
      {/* => Sidebar element */}

      <p>Role: {user.role}</p>
      {/* => User role display */}
      {/* => user.role is "admin" */}
      {/* => Output: "Role: admin" */}
    </aside>
  );
  // => Component returns sidebar UI
  // => Used SAME user data (deduped)
}

// app/page.tsx
// => File location: app/page.tsx (homepage)
// => Parent component rendering both Header and Sidebar

import { Header } from './components/Header';
// => Import Header component
// => Relative path: ./components/Header.tsx

import { Sidebar } from './components/Sidebar';
// => Import Sidebar component

export default function HomePage() {
  // => Homepage component (Server Component)

  return (
    <div>
      {/* => Page container */}

      <Header />
      {/* => Render Header component */}
      {/* => Triggers getUser() call */}
      {/* => Makes network request to API */}
      {/* => Response cached for this render pass */}

      <Sidebar />
      {/* => Render Sidebar component */}
      {/* => Triggers getUser() call */}
      {/* => Next.js detects duplicate fetch */}
      {/* => REUSES cached response (no network request) */}
      {/* => Instant return of user data */}

      {/* => Total network requests: 1 (not 2) */}
      {/* => Server console shows "Fetching user data..." only ONCE */}
      {/* => Deduplication happens automatically (no code needed) */}
      {/* => Works with: fetch(), database queries (with caching), etc. */}
    </div>
  );
  // => Component returns page UI
  // => Both components get user data efficiently
  // => Request deduplication critical for performance:
  // =>   - Prevents redundant network requests
  // =>   - Reduces server load
  // =>   - Faster page rendering
  // =>   - Enables composition without performance penalty
}

// app/posts/loading.tsx
// => File location: app/posts/loading.tsx
// => Special file: automatic loading UI for /posts route
// => File name MUST be exactly "loading.tsx" (Next.js convention)
// => Paired with app/posts/page.tsx (shows while page loads)
// => Next.js automatically wraps page in <Suspense fallback={<Loading />}>

export default function Loading() {
  // => Loading component (regular React component)
  // => No 'use client' needed (works as Server or Client Component)
  // => Rendered IMMEDIATELY when user navigates to /posts
  // => Shows while PostsPage fetches data
  // => Replaced with actual page when data ready

  return (
    <div>
      {/* => Loading UI container */}

      <h2>Loading Posts...</h2>
      {/* => Loading message */}
      {/* => User sees this INSTANTLY (no wait) */}
      {/* => Improves perceived performance */}

      <div className="skeleton">
        {/* => Skeleton UI container */}
        {/* => Skeleton: placeholder mimicking final UI structure */}
        {/* => Shows approximate layout while loading */}
        {/* => className would need CSS: */}
        {/* =>   .skeleton { animation: pulse 2s infinite; } */}

        <div className="skeleton-line" />
        {/* => Skeleton line 1 (placeholder for first post) */}
        {/* => CSS could show gray animated bar */}

        <div className="skeleton-line" />
        {/* => Skeleton line 2 (placeholder for second post) */}

        <div className="skeleton-line" />
        {/* => Skeleton line 3 (placeholder for third post) */}
      </div>
      {/* => Skeleton mimics final post list structure */}
      {/* => User sees approximate UI immediately */}
    </div>
  );
  // => Component returns loading UI
  // => Next.js shows this during page data fetch
  // => When page ready: React replaces this with PostsPage
  // => Smooth transition: loading UI → actual content
}

// app/posts/page.tsx
// => File location: app/posts/page.tsx
// => Page component for /posts route
// => Paired with loading.tsx (loading UI while this loads)

export default async function PostsPage() {
  // => Page component (async Server Component)
  // => Fetches data before rendering

  await new Promise(resolve => setTimeout(resolve, 2000));
  // => Simulate slow network request
  // => 2000ms = 2 seconds delay
  // => In production: await fetch('https://api.example.com/posts')
  // => During this 2 second wait:
  // =>   - loading.tsx shows to user
  // =>   - User sees "Loading Posts..." and skeleton
  // =>   - NOT a blank screen (good UX)

  const posts = [
    { id: 1, title: 'Zakat Guide' },
    { id: 2, title: 'Murabaha Basics' },
  ];
  // => Post data (normally from API or database)
  // => Each post: { id: number, title: string }

  return (
    <div>
      {/* => Posts page container */}

      <h2>Posts</h2>
      {/* => Page heading */}

      <ul>
        {/* => Post list */}

        {posts.map(post => (
          <li key={post.id}>{post.title}</li>
          // => List item for each post
          // => key={post.id}: React key for list rendering
          // => Output for post 1: "Zakat Guide"
          // => Output for post 2: "Murabaha Basics"
        ))}
      </ul>
    </div>
  );
  // => Component returns posts UI
  // => Renders AFTER 2 second delay
  // => React replaces loading.tsx with this content
  // => User flow:
  // =>   T=0s: Navigate to /posts
  // =>   T=0s: loading.tsx shows immediately
  // =>   T=2s: PostsPage replaces loading.tsx
  // =>   T=2s: User sees actual posts
}

// app/dashboard/page.tsx
// => File location: app/dashboard/page.tsx
// => Demonstrates manual Suspense for granular loading

import { Suspense } from 'react';
// => Import Suspense component from React
// => Suspense: React feature for showing fallback while async content loads
// => Built into React (not Next.js specific)
// => Enables partial page rendering (some content fast, some slow)

async function DonationList() {
  // => Async Server Component (fetches data)
  // => Slow component: takes 2 seconds to render

  await new Promise(resolve => setTimeout(resolve, 2000));
  // => Simulate 2 second API delay
  // => In production: await fetch('/api/donations')
  // => Component SUSPENDS during this wait
  // => Suspense boundary shows fallback while waiting

  const donations = [
    { id: 1, amount: 100000 },
    { id: 2, amount: 250000 },
  ];
  // => Donation data (normally from API)
  // => Format: { id: number, amount: number }

  return (
    <ul>
      {/* => Donation list */}

      {donations.map(d => (
        <li key={d.id}>IDR {d.amount.toLocaleString()}</li>
        // => List item for each donation
        // => d.amount.toLocaleString() formats number with commas
        // => For d.amount=100000: "IDR 100,000"
        // => For d.amount=250000: "IDR 250,000"
      ))}
    </ul>
  );
  // => Component returns list after 2 second delay
}

function QuickStats() {
  // => Synchronous component (no data fetch)
  // => Fast component: renders IMMEDIATELY (no await)
  // => No async, no data loading

  return (
    <div>
      {/* => Stats container */}

      <h2>Quick Stats</h2>
      {/* => Section heading */}

      <p>Last updated: Now</p>
      {/* => Timestamp */}
      {/* => Static text (no API call needed) */}
      {/* => Renders instantly */}
    </div>
  );
  // => Component returns static content immediately
  // => Renders in <1ms (no network request)
}

export default function DashboardPage() {
  // => Dashboard page component

  return (
    <div>
      {/* => Dashboard container */}

      <h1>Dashboard</h1>
      {/* => Page heading */}
      {/* => Renders immediately (static content) */}

      <QuickStats />
      {/* => Fast component renders IMMEDIATELY */}
      {/* => Shows "Quick Stats" and timestamp instantly */}
      {/* => User sees this at T=0s (no wait) */}

      <Suspense fallback={<p>Loading donations...</p>}>
        {/* => Suspense boundary (React component) */}
        {/* => Wraps slow component (DonationList) */}
        {/* => fallback prop: UI to show while children load */}
        {/* => fallback renders immediately at T=0s */}
        {/* => Shows: "Loading donations..." */}

        <DonationList />
        {/* => Slow component inside Suspense */}
        {/* => Suspends for 2 seconds (await in DonationList) */}
        {/* => While suspended: fallback shows */}
        {/* => When ready: fallback replaced with DonationList */}
        {/* => Transition at T=2s: "Loading donations..." → actual list */}
      </Suspense>
      {/* => Suspense enables partial page rendering: */}
      {/* =>   - Fast content (heading, QuickStats) shows immediately */}
      {/* =>   - Slow content (DonationList) shows fallback, then actual data */}
      {/* =>   - Better UX than waiting for entire page */}
    </div>
  );
  // => Component returns dashboard UI
  // => Rendering timeline:
  // =>   T=0s: Dashboard heading + QuickStats visible + "Loading donations..."
  // =>   T=2s: "Loading donations..." → actual donation list
  // => Without Suspense: entire page waits 2 seconds (blank screen)
  // => With Suspense: fast content shows immediately (better UX)
}

// app/posts/error.tsx
// => File location: app/posts/error.tsx
// => Special file: error boundary for /posts route
// => File name MUST be exactly "error.tsx" (Next.js convention)
// => Catches errors from app/posts/page.tsx

'use client';
// => REQUIRED: Error boundaries MUST be Client Components
// => Why: error boundaries use React lifecycle methods (componentDidCatch)
// => React lifecycle only works in Client Components
// => Server Components cannot catch runtime errors
// => onClick event handler also requires Client Component

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  // => error parameter: Error object from thrown error
  // => Error type: standard JavaScript Error
  // => { digest?: string }: extends Error with optional digest property
  // => digest: unique error identifier (for logging/tracking)
  // => Example: error.digest = "abc123def456"
  // => Useful for correlating errors in logs

  reset: () => void;
  // => reset parameter: function to retry rendering
  // => Signature: () => void (no parameters, no return value)
  // => Calling reset():
  // =>   1. Re-renders error boundary
  // =>   2. Tries to render page again
  // =>   3. Might succeed if error was transient
}) {
  // => Error component receives error and reset props
  // => error.message: "Failed to fetch posts"
  // => error.digest: "xyz789" (unique ID)

  return (
    <div>
      {/* => Error UI container */}

      <h2>Something went wrong!</h2>
      {/* => User-friendly error heading */}
      {/* => Don't expose technical details in production */}
      {/* => Generic message improves security */}

      <p>{error.message}</p>
      {/* => Display error message */}
      {/* => error.message from thrown Error */}
      {/* => For: throw new Error('Failed to fetch posts') */}
      {/* =>   Output: "Failed to fetch posts" */}
      {/* => Production: sanitize message (don't leak sensitive info) */}

      <button onClick={reset}>
        {/* => Retry button */}
        {/* => onClick handler (requires 'use client') */}
        {/* => Click calls reset() function */}
        {/* => reset() provided by Next.js automatically */}

        Try Again
        {/* => Button text */}
      </button>
      {/* => Click behavior: */}
      {/* =>   1. reset() called */}
      {/* =>   2. Error boundary cleared */}
      {/* =>   3. PostsPage re-rendered */}
      {/* =>   4. If error transient (network glitch): might succeed */}
      {/* =>   5. If error persistent: error.tsx shows again */}
    </div>
  );
  // => Component returns error UI
  // => Replaces page content when error occurs
  // => Provides recovery mechanism (reset button)
}

// app/posts/page.tsx
// => File location: app/posts/page.tsx
// => Page that might throw error
// => Paired with error.tsx (catches errors from this page)

export default async function PostsPage() {
  // => Page component (async Server Component)

  const shouldFail = Math.random() > 0.5;
  // => Random boolean (50% chance true, 50% false)
  // => Math.random() returns 0.0 to 0.999...
  // => > 0.5: true for 0.5-0.999 (50% of range)
  // => Simulates unreliable API (sometimes fails)

  if (shouldFail) {
    // => 50% chance this executes

    throw new Error('Failed to fetch posts');
    // => Throw Error object with message
    // => Error propagates up component tree
    // => Caught by nearest error boundary (error.tsx)
    // => error.tsx receives this Error object
    // => error.message will be "Failed to fetch posts"
    // => Page rendering stops here
  }
  // => If shouldFail is true: error.tsx shows
  // => If shouldFail is false: continue to return statement

  return (
    <div>
      {/* => Success UI (only shows if no error) */}

      <h2>Posts</h2>
      {/* => Page heading */}

      <p>Success! Posts loaded.</p>
      {/* => Success message */}
      {/* => Only visible when shouldFail is false */}
    </div>
  );
  // => Component returns success UI
  // => Only renders if error not thrown
  // => Testing error boundary:
  // =>   - Refresh page multiple times
  // =>   - 50% see success UI
  // =>   - 50% see error UI with "Try Again" button
  // =>   - Click "Try Again": re-renders, new 50/50 chance
}