Intermediate

// app/actions.ts
// => File location: app/actions.ts (Server Actions file)
// => Place at app root for global Server Actions

'use server';
// => REQUIRED directive: marks file as Server Actions module
// => All exports in this file are Server Actions
// => Server Actions run ONLY on server (never sent to client)

type FormState = {
  // => State type for useFormState hook
  // => Hook requires consistent state shape across submissions

  message: string;
  // => Success or error message to show user
  // => Always present in response

  errors?: {
    // => Optional errors object (only present on validation failure)
    // => Question mark makes property optional
    // => undefined when no validation errors

    name?: string;
    // => Name field error message (optional)
    // => Example: "Name must be at least 2 characters"

    amount?: string;
    // => Amount field error message (optional)
    // => Example: "Minimum donation is IDR 10,000"
  };
};
// => FormState defines contract between Server Action and useFormState
// => Both prevState and return value must match this type

export async function submitDonation(
  // => Server Action function signature for useFormState
  // => Export required: makes function callable from Client Components
  // => async keyword: allows await for database/API calls

  prevState: FormState,
  // => Previous form state from last submission
  // => useFormState provides this automatically
  // => First submission: receives initial state
  // => Subsequent submissions: receives previous return value
  // => Type must match return type (FormState)

  formData: FormData
  // => Form data from form submission
  // => Automatically populated by browser on submit
  // => Contains all input values with name attributes
  // => FormData is browser API (not Next.js specific)
): Promise<FormState> {
  // => Return type: Promise<FormState>
  // => async functions always return Promise
  // => Resolved value must match FormState type

  const name = formData.get('name') as string;
  // => Extract 'name' input value from form
  // => formData.get() returns FormDataEntryValue (string | File | null)
  // => Type assertion 'as string': treat value as string
  // => For input name="name", value is "Ahmad"
  // => name is "Ahmad" (type: string)

  const amountStr = formData.get('amount') as string;
  // => Extract 'amount' input value as string
  // => Number inputs still submit as strings
  // => For input name="amount" value="100000"
  // => amountStr is "100000" (type: string, NOT number)
  // => Need parseInt() to convert to number

  const errors: FormState['errors'] = {};
  // => Initialize errors object
  // => Type: FormState['errors'] (indexed access type)
  // => Initially empty object {}
  // => Add properties only if validation fails

  if (!name || name.length < 2) {
    // => Validate name field
    // => !name: true if name is null, undefined, or empty string ""
    // => name.length < 2: true if name has less than 2 characters
    // => OR operator: true if either condition true

    errors.name = 'Name must be at least 2 characters';
    // => Add error message to errors object
    // => errors.name now exists (was optional)
    // => User sees this message below name input
  }

  const amount = parseInt(amountStr);
  // => Convert string to number
  // => parseInt("100000") returns 100000 (type: number)
  // => parseInt("abc") returns NaN (Not a Number)
  // => parseInt("") returns NaN
  // => amount is 100000 or NaN (type: number)

  if (isNaN(amount) || amount < 10000) {
    // => Validate amount field
    // => isNaN(amount): true if amount is Not a Number
    // =>   Example: user entered non-numeric text
    // => amount < 10000: true if donation too small
    // => OR operator: true if either condition true

    errors.amount = 'Minimum donation is IDR 10,000';
    // => Add error message to errors object
    // => errors.amount now exists (was optional)
  }

  if (Object.keys(errors).length > 0) {
    // => Check if any validation errors exist
    // => Object.keys(errors) returns array of property names
    // => Example: ["name", "amount"] if both fields invalid
    // => .length > 0: true if errors object has any properties
    // => Validation FAILED if true

    return {
      // => Early return with validation errors
      // => Stops function execution here
      // => Client receives error state

      message: 'Validation failed',
      // => Generic error message
      // => Specific errors in errors object

      errors,
      // => Shorthand for errors: errors
      // => Includes all validation error messages
      // => Client Component displays these below fields
    };
    // => Return type matches FormState
    // => useFormState receives this, updates state
    // => Component re-renders with error messages
  }

  await new Promise(resolve => setTimeout(resolve, 1000));
  // => Simulate database save delay
  // => Production: await prisma.donation.create(...)
  // => new Promise: creates promise that resolves after 1000ms (1 second)
  // => setTimeout: delays resolve function call
  // => await: pauses execution until promise resolves

  console.log(`Saved donation: ${name} - IDR ${amount}`);
  // => Server-side logging
  // => For name="Ahmad", amount=100000
  // => Output: "Saved donation: Ahmad - IDR 100000"
  // => Logs appear in terminal (server), NOT browser console

  return {
    // => Success response
    // => Validation passed, database save complete

    message: `Thank you ${name}! Donation of IDR ${amount.toLocaleString()} received.`,
    // => Personalized success message
    // => Template literal with interpolation
    // => amount.toLocaleString() formats number with commas
    // => 100000 becomes "100,000"
    // => Result: "Thank you Ahmad! Donation of IDR 100,000 received."
  };
  // => Return type matches FormState (no errors property)
  // => useFormState receives this, updates state
  // => Component shows success message
}

// app/donate/page.tsx
// => File location: app/donate/page.tsx
// => Route: /donate
// => Client Component (needs useFormState hook)

'use client';
// => REQUIRED directive: marks component as Client Component
// => Needed for React hooks (useFormState)
// => Without this: Error "useFormState can only be used in Client Components"

import { useFormState } from 'react-dom';
// => Import useFormState hook from react-dom (not react)
// => useFormState: manages form state with Server Actions
// => Returns [state, formAction] tuple

import { submitDonation } from '../actions';
// => Import Server Action from actions.ts
// => Relative path: ../actions (up one level, then actions.ts)
// => submitDonation can be called from Client Component

export default function DonatePage() {
  // => Page component export
  // => Default export: Next.js renders this for /donate route

  const [state, formAction] = useFormState(submitDonation, {
    // => useFormState hook manages Server Action state
    // => First argument: Server Action function (submitDonation)
    // => Second argument: initial state
    // => Returns array: [current state, wrapped action]

    message: '',
    // => Initial state message (empty string)
    // => First render: state.message is ''
    // => After submission: state.message is success/error message
  });
  // => state: current form state (type: FormState)
  // =>   Updates after each submission with Server Action return value
  // => formAction: wrapped Server Action for form action attribute
  // =>   Handles state management automatically

  return (
    <div>
      <h1>Make a Donation</h1>

      <form action={formAction}>
        {/* => form element with action prop */}
        {/* => action={formAction}: wrapped Server Action from useFormState */}
        {/* => NOT action={submitDonation} (loses state management) */}
        {/* => On submit: calls formAction with FormData */}

        <div>
          <label>
            Name:
            <input type="text" name="name" />
            {/* => name attribute REQUIRED: used in formData.get('name') */}
            {/* => User types: value included in FormData on submit */}
          </label>

          {state.errors?.name && (
            // => Conditional rendering: only show if error exists
            // => state.errors?.name: optional chaining (safe access)
            // => If state.errors undefined: short-circuits to false
            // => If state.errors.name exists: renders error message
            // => && operator: renders right side only if left side truthy

            <p style={{ color: 'red' }}>{state.errors.name}</p>
            // => Error message paragraph
            // => Inline style: red text for visibility
            // => {state.errors.name}: "Name must be at least 2 characters"
          )}
        </div>

        <div>
          <label>
            Amount (IDR):
            <input type="number" name="amount" />
            {/* => type="number": numeric keyboard on mobile */}
            {/* => name="amount": used in formData.get('amount') */}
            {/* => Value still submitted as string (need parseInt) */}
          </label>

          {state.errors?.amount && (
            // => Conditional error rendering for amount field
            // => Same pattern as name field error

            <p style={{ color: 'red' }}>{state.errors.amount}</p>
            // => Amount field error message
            // => Example: "Minimum donation is IDR 10,000"
          )}
        </div>

        <button type="submit">Donate</button>
        {/* => Submit button triggers form submission */}
        {/* => type="submit": submits form (not just button) */}
        {/* => Calls formAction with FormData */}

        {state.message && (
          // => Show success or generic error message
          // => state.message always exists (never undefined)
          // => Empty string is falsy, so nothing renders initially
          // => After submission: shows "Thank you..." or "Validation failed"

          <p>{state.message}</p>
          // => Message paragraph
          // => Success: "Thank you Ahmad! Donation of IDR 100,000 received."
          // => Error: "Validation failed"
        )}
      </form>
    </div>
  );
}
// => Full workflow:
// => 1. User fills form, clicks "Donate"
// => 2. Browser creates FormData with input values
// => 3. formAction called with FormData
// => 4. submitDonation Server Action executes on server
// => 5. Returns FormState (success or errors)
// => 6. useFormState updates state with return value
// => 7. Component re-renders with new state
// => 8. User sees errors or success message

// app/actions.ts
// => File location: app/actions.ts (Server Actions module)
// => Centralized Server Actions for application

'use server';
// => REQUIRED directive: makes all exports Server Actions
// => Server Actions execute on server only

export async function createPost(formData: FormData) {
  // => Server Action for creating blog posts
  // => Export required: callable from Client Components
  // => async keyword: allows await for database operations
  // => formData parameter: receives form data from submission

  const title = formData.get('title') as string;
  // => Extract 'title' field from FormData
  // => formData.get() returns FormDataEntryValue (string | File | null)
  // => Type assertion 'as string': treat as string
  // => For input name="title" value="Zakat Guide"
  // => title is "Zakat Guide" (type: string)

  const content = formData.get('content') as string;
  // => Extract 'content' field from FormData
  // => For textarea name="content" value="This guide explains..."
  // => content is "This guide explains..." (type: string)
  // => Textareas submit values as strings (like inputs)

  await new Promise(resolve => setTimeout(resolve, 2000));
  // => Simulate slow database operation
  // => Real code: await prisma.post.create({ data: { title, content } })
  // => new Promise: creates promise resolving after 2000ms (2 seconds)
  // => setTimeout: delays resolve call by 2 seconds
  // => await: pauses function execution until promise resolves
  // => During this time: useFormStatus pending is true

  console.log(`Created post: ${title}`);
  // => Server-side logging (appears in terminal)
  // => For title="Zakat Guide"
  // => Output: "Created post: Zakat Guide"
  // => Confirms Server Action executed successfully

  return { success: true };
  // => Return success indicator
  // => Object with success boolean property
  // => Client Component can check return value
  // => Type: { success: boolean }
}

// app/components/SubmitButton.tsx
// => File location: app/components/SubmitButton.tsx
// => Reusable submit button with loading state
// => MUST be separate component (useFormStatus requirement)

'use client';
// => REQUIRED directive: Client Component for useFormStatus hook
// => Cannot use useFormStatus in Server Component

import { useFormStatus } from 'react-dom';
// => Import useFormStatus hook from react-dom (not react)
// => Provides form submission status
// => Returns object with pending, data, method, action properties

export function SubmitButton() {
  // => Submit button component with loading state
  // => Export required: used in other components
  // => CRITICAL: Must be CHILD of form element (not same level)

  const { pending } = useFormStatus();
  // => useFormStatus hook reads form submission status
  // => pending: boolean, true during form submission
  // => Destructure pending from returned object
  // => pending is false initially
  // => pending becomes true when form submits
  // => pending becomes false when Server Action completes

  // => CRITICAL CONSTRAINT: useFormStatus ONLY works in components
  // =>   that are CHILDREN of form element
  // => If used in same component as <form>: returns default values (pending: false)
  // => Must be separate child component

  return (
    <button type="submit" disabled={pending}>
      {/* => Submit button with dynamic disabled state */}
      {/* => type="submit": submits parent form */}
      {/* => disabled={pending}: disable during submission */}
      {/* => disabled when pending=true (prevents double submission) */}
      {/* => enabled when pending=false (allows submission) */}

      {pending ? 'Creating Post...' : 'Create Post'}
      {/* => Conditional button text */}
      {/* => Ternary operator: condition ? ifTrue : ifFalse */}
      {/* => When pending=true: shows "Creating Post..." (loading state) */}
      {/* => When pending=false: shows "Create Post" (normal state) */}
      {/* => Provides visual feedback during submission */}
    </button>
  );
  // => Component returns button with dynamic content
  // => Re-renders automatically when pending changes
  // => Submission flow:
  // =>   1. User clicks → pending becomes true
  // =>   2. Button shows "Creating Post...", disables
  // =>   3. Server Action executes (2 second delay)
  // =>   4. Server Action completes → pending becomes false
  // =>   5. Button shows "Create Post", enables
}

// app/posts/new/page.tsx
// => File location: app/posts/new/page.tsx
// => Route: /posts/new
// => New post creation page

'use client';
// => REQUIRED: Client Component for importing Client Component (SubmitButton)
// => Also needed if page uses any hooks

import { createPost } from '@/app/actions';
// => Import Server Action
// => Absolute path with @/ alias (configured in tsconfig.json)
// => @/ represents project root
// => Equivalent to: import { createPost } from '../../actions';

import { SubmitButton } from '@/app/components/SubmitButton';
// => Import custom submit button component
// => Absolute path for clarity
// => Component has useFormStatus hook built-in

export default function NewPostPage() {
  // => Page component for creating new posts
  // => Default export: Next.js renders for /posts/new route

  return (
    <div>
      <h1>Create New Post</h1>
      {/* => Page heading */}

      <form action={createPost}>
        {/* => Form with Server Action */}
        {/* => action={createPost}: calls Server Action on submit */}
        {/* => createPost is Server Action function reference */}
        {/* => On submit: browser sends FormData to Server Action */}

        <label>
          Title:
          <input type="text" name="title" required />
          {/* => Title input field */}
          {/* => name="title": used in formData.get('title') */}
          {/* => required attribute: HTML5 validation (prevents empty submission) */}
          {/* => type="text": standard text input */}
        </label>

        <label>
          Content:
          <textarea name="content" required />
          {/* => Content textarea field */}
          {/* => name="content": used in formData.get('content') */}
          {/* => required: prevents empty submission */}
          {/* => textarea allows multi-line text input */}
        </label>

        <SubmitButton />
        {/* => Custom submit button component */}
        {/* => CRITICAL: SubmitButton is CHILD of form */}
        {/* => This placement allows useFormStatus to work */}
        {/* => Button automatically shows loading state during submission */}
        {/* => If we used <button> directly here without useFormStatus: */}
        {/* =>   No loading state, no disabled state during submission */}
      </form>
    </div>
  );
}
// => Complete workflow:
// => 1. User fills title and content fields
// => 2. User clicks "Create Post" button
// => 3. Form submits, sends FormData to createPost Server Action
// => 4. useFormStatus detects submission: pending becomes true
// => 5. SubmitButton shows "Creating Post...", disables
// => 6. Server Action executes (2 second delay)
// => 7. Server logs "Created post: [title]"
// => 8. Server Action returns { success: true }
// => 9. useFormStatus detects completion: pending becomes false
// => 10. SubmitButton shows "Create Post", enables again

// app/actions.ts
'use server';
// => Server Actions work with/without JavaScript

import { redirect } from 'next/navigation';
// => Server-side navigation utility

export async function loginUser(formData: FormData) {
  // => Authentication Server Action
  const email = formData.get('email') as string;
  // => Extract email from form
  const password = formData.get('password') as string;
  // => Extract password from form

  if (email === 'user@example.com' && password === 'password123') {
    // => Validate credentials (production: check database)
    // cookies().set('auth_token', 'token123');
    // => Set auth cookie (commented for demo)
    redirect('/dashboard');
    // => HTTP 303 redirect without JavaScript
    // => Client-side navigation with JavaScript
  }

  return { error: 'Invalid email or password' };
  // => Return error for invalid credentials
}

// app/login/page.tsx
import { loginUser } from '../actions';
// => Import Server Action

export default function LoginPage() {
  // => Basic login page (no JavaScript required)
  return (
    <div>
      <h1>Login</h1>

      <form action={loginUser}>
        {/* => Form works WITHOUT JavaScript (HTTP POST) */}
        {/* => Form works WITH JavaScript (fetch, no reload) */}
        <label>
          Email:
          <input type="email" name="email" required />
          {/* => HTML5 email validation */}
        </label>

        <label>
          Password:
          <input type="password" name="password" required />
          {/* => Password field masked */}
        </label>

        <button type="submit">Login</button>
        {/* => Submits via HTTP POST (no JS) or fetch (with JS) */}
      </form>
    </div>
  );
}

// app/login-enhanced/page.tsx
'use client';
// => Client Component for hooks

import { useFormState, useFormStatus } from 'react-dom';
// => React form hooks
import { loginUser } from '../actions';

function SubmitButton() {
  // => Separate component (useFormStatus requirement)
  const { pending } = useFormStatus();
  // => Form submission status
  return (
    <button type="submit" disabled={pending}>
      {/* => Disable during submission */}
      {pending ? 'Logging in...' : 'Login'}
      {/* => Dynamic button text */}
    </button>
  );
}

export default function LoginEnhancedPage() {
  // => Enhanced with JavaScript features
  const [state, formAction] = useFormState(loginUser, {});
  // => useFormState manages form state
  // => state receives Server Action return value

  return (
    <div>
      <h1>Login (Enhanced)</h1>

      <form action={formAction}>
        {/* => Use wrapped formAction for state management */}
        <label>
          Email:
          <input type="email" name="email" required />
        </label>

        <label>
          Password:
          <input type="password" name="password" required />
        </label>

        <SubmitButton />
        {/* => Shows loading state during submission */}

        {state.error && (
          // => Conditional error display (JavaScript enhancement)
          <p style={{ color: 'red' }}>{state.error}</p>
          // => Inline error message
        )}
      </form>
    </div>
  );
}
// => Progressive enhancement: basic works without JS, enhanced with JS

// app/posts/page.tsx
// => ISR (Incremental Static Regeneration) example

async function getPosts() {
  // => Fetch function with caching
  const res = await fetch('https://jsonplaceholder.typicode.com/posts', {
    // => Fetch posts from API
    next: { revalidate: 60 }
    // => Cache for 60 seconds
    // => After 60s: serve stale, regenerate in background
  });
  // => First request: fetch from API, cache result
  // => Within 60s: serve from cache (instant)
  // => After 60s: serve stale cache, fetch fresh data background
  // => Next request after regeneration: serve fresh data

  return res.json();
  // => Return parsed JSON response
}

export default async function PostsPage() {
  // => Async Server Component
  const posts = await getPosts();
  // => Fetch posts (may be cached)
  // => posts is array of Post objects

  return (
    <div>
      <h2>Blog Posts (ISR)</h2>

      <p>Last rendered: {new Date().toLocaleTimeString()}</p>
      {/* => Timestamp shows when page generated */}
      {/* => Updates every 60s after first request */}

      <ul>
        {posts.slice(0, 5).map((post: any) => (
          // => Display first 5 posts
          // => slice(0, 5) takes first 5 items from array
          <li key={post.id}>
            {/* => key prop required for list items */}
            <strong>{post.title}</strong>
            {/* => Post title in bold */}
          </li>
        ))}
      </ul>
    </div>
  );
}

// Alternative: page-level revalidate export
export const revalidate = 60;
// => Apply 60s revalidation to entire page
// => All fetch requests inherit this value
// => Simpler than setting revalidate per fetch

// app/actions.ts
'use server';
// => Server Actions module

import { revalidatePath } from 'next/cache';
// => Import cache invalidation function

export async function updatePost(postId: string, formData: FormData) {
  // => Update post Server Action
  // => First param: postId (from bind)
  // => Second param: formData (from form submission)
  const title = formData.get('title') as string;
  // => Extract title from form
  const content = formData.get('content') as string;
  // => Extract content from form

  // await db.posts.update({ where: { id: postId }, data: { title, content } });
  // => Database update (commented for demo)
  // => Production: update in database
  console.log(`Updated post ${postId}: ${title}`);
  // => Log update to server console

  revalidatePath(`/posts/${postId}`);
  // => Invalidate cache for specific post page
  // => Next request to /posts/[postId] fetches fresh data
  // => Cache cleared immediately

  revalidatePath('/posts');
  // => Invalidate posts list cache
  // => List shows updated post immediately
  // => Can invalidate multiple related paths
}

// app/posts/[id]/edit/page.tsx
'use client';
// => Client Component for form

import { updatePost } from '@/app/actions';
// => Import Server Action

export default function EditPostPage({
  params,
}: {
  params: { id: string };
  // => params from dynamic route [id]
}) {
  // => Edit page for specific post

  const updatePostWithId = updatePost.bind(null, params.id);
  // => Bind postId to first parameter
  // => updatePost expects (postId, formData)
  // => updatePostWithId now expects only formData
  // => postId is pre-filled with params.id

  return (
    <div>
      <h1>Edit Post {params.id}</h1>
      {/* => Show post ID being edited */}

      <form action={updatePostWithId}>
        {/* => Form calls bound Server Action */}
        {/* => Only formData sent (postId already bound) */}
        <label>
          Title:
          <input type="text" name="title" required />
          {/* => Title input field */}
        </label>

        <label>
          Content:
          <textarea name="content" required />
          {/* => Content textarea field */}
        </label>

        <button type="submit">Update Post</button>
        {/* => Submit triggers updatePostWithId */}
      </form>
    </div>
  );
}
// => On submit: updatePost(params.id, formData) called
// => Cache invalidated, fresh data served

// app/lib/data.ts
// => Data fetching utilities with cache tags

export async function getUser(userId: string) {
  // => Fetch user by ID
  // => userId parameter: user identifier
  const res = await fetch(`https://api.example.com/users/${userId}`, {
    // => API request for user data
    next: {
      // => Next.js fetch options
      tags: [`user-${userId}`],
      // => Cache tag for revalidation
      // => Tag format: user-{userId}
      // => Allows selective cache invalidation
    },
  });
  // => res is Response object
  return res.json();
  // => Parse and return JSON
}

export async function getUserPosts(userId: string) {
  // => Fetch posts for specific user
  const res = await fetch(`https://api.example.com/users/${userId}/posts`, {
    // => API request for user's posts
    next: {
      tags: [`user-${userId}-posts`, `posts`],
      // => Multiple cache tags
      // => First tag: user-specific posts
      // => Second tag: all posts globally
      // => Enables both granular and broad revalidation
    },
  });
  return res.json();
  // => Return posts array
}

// app/actions.ts
'use server';
// => Server Actions module

import { revalidateTag } from 'next/cache';
// => Import tag-based cache invalidation

export async function updateUserProfile(userId: string, formData: FormData) {
  // => Update user profile Server Action
  // => userId: bound parameter
  // => formData: form submission data
  const name = formData.get('name') as string;
  // => Extract name from form
  // => name is "Ahmad Updated"

  // await db.users.update({ where: { id: userId }, data: { name } });
  // => Database update (commented for demo)

  revalidateTag(`user-${userId}`);
  // => Invalidate cache for user tag
  // => Affects getUser(userId) fetch
  // => Also affects getUserPosts (shares tag)
  // => All requests with this tag refreshed

  console.log(`Revalidated cache for user ${userId}`);
  // => Server log confirmation
}

export async function createPost(userId: string, formData: FormData) {
  // => Create new post Server Action
  const title = formData.get('title') as string;
  // => Extract title from form
  const content = formData.get('content') as string;
  // => Extract content from form

  // await db.posts.create({ data: { userId, title, content } });
  // => Database insertion (commented)

  revalidateTag('posts');
  // => Invalidate all posts caches
  // => Affects ALL fetches tagged 'posts'
  // => Refreshes post lists across site

  revalidateTag(`user-${userId}-posts`);
  // => Invalidate specific user's posts cache
  // => More granular than 'posts' tag
  // => Targets specific user's post list
}

// app/users/[id]/page.tsx
// => User profile page
import { getUser, getUserPosts } from '@/app/lib/data';
// => Import tagged fetch functions

export default async function UserPage({
  params,
}: {
  params: { id: string };
  // => Dynamic route params
}) {
  // => User page component

  const [user, posts] = await Promise.all([
    // => Fetch both concurrently
    // => Promise.all runs requests in parallel
    getUser(params.id),
    // => Fetch user data
    // => Tagged: user-${id}
    getUserPosts(params.id),
    // => Fetch user's posts
    // => Tagged: user-${id}-posts, posts
  ]);
  // => user contains profile data
  // => posts contains array of posts

  return (
    <div>
      <h1>{user.name}</h1>
      {/* => Display user name */}
      <p>Posts by {user.name}:</p>

      <ul>
        {posts.map((post: any) => (
          // => Iterate over posts array
          <li key={post.id}>{post.title}</li>
          // => Display post title
          // => key prop required for list items
        ))}
      </ul>
    </div>
  );
}
// => Tag revalidation workflow:
// => 1. updateUserProfile('123') → revalidateTag('user-123')
// => 2. Next getUser('123') request fetches fresh data
// => 3. getUserPosts('123') also refreshes (shares tag)

// app/(marketing)/layout.tsx
// => File location: app/(marketing)/layout.tsx
// => Parentheses create route group: (marketing)
// => Route groups organize files WITHOUT affecting URLs
// => (marketing) folder NOT part of URL path
export default function MarketingLayout({
  // => Layout for marketing pages
  children,
  // => Child pages render in layout
}: {
  children: React.ReactNode;
  // => Type: React component or JSX
}) {
  // => Marketing layout component
  return (
    <div>
      <header style={{ background: '#0173B2', color: 'white', padding: '1rem' }}>
        {/* => Marketing header with brand colors */}
        {/* => background #0173B2: accessible blue */}
        <h1>Islamic Finance Platform</h1>
        {/* => Site branding */}
        <nav>
          <a href="/">Home</a> | <a href="/about">About</a> | <a href="/pricing">Pricing</a>
          {/* => Navigation links */}
          {/* => All routes in (marketing) group */}
        </nav>
      </header>

      <main>
        {children}
        {/* => Marketing pages (/, /about, /pricing) render here */}
        {/* => Each page wrapped by this layout */}
      </main>

      <footer style={{ background: '#f5f5f5', padding: '2rem', textAlign: 'center' }}>
        {/* => Marketing footer */}
        {/* => Light gray background */}
        <p>© 2026 Islamic Finance Platform</p>
        {/* => Copyright notice */}
      </footer>
    </div>
  );
}
// => All pages in (marketing)/ use this layout

// app/(marketing)/page.tsx
// => File: app/(marketing)/page.tsx
// => URL: "/" (route group NOT in URL)
// => (marketing) group omitted from path
export default function HomePage() {
  // => Homepage component
  return (
    <div>
      <h1>Welcome to Islamic Finance</h1>
      {/* => Page heading */}
      <p>Learn Sharia-compliant financial products.</p>
      {/* => Page description */}
    </div>
  );
}
// => Wrapped by MarketingLayout (blue header + footer)

// app/(marketing)/about/page.tsx
// => File: app/(marketing)/about/page.tsx
// => URL: "/about" (NOT "/marketing/about")
// => Route group name omitted
export default function AboutPage() {
  // => About page component
  return (
    <div>
      <h1>About Us</h1>
      <p>Providing Islamic financial education since 2026.</p>
    </div>
  );
}
// => Also wrapped by MarketingLayout

// app/(app)/layout.tsx
// => File: app/(app)/layout.tsx
// => Separate route group: (app)
// => Different layout for application pages
export default function AppLayout({
  // => Application layout (different from marketing)
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <div>
      <header style={{ background: '#029E73', color: 'white', padding: '1rem' }}>
        {/* => App header with different color */}
        {/* => background #029E73: accessible teal */}
        {/* => Visually distinct from marketing */}
        <nav>
          <a href="/dashboard">Dashboard</a> | <a href="/profile">Profile</a>
          {/* => App-specific navigation */}
        </nav>
      </header>

      {children}
      {/* => App pages render here */}
      {/* => No footer in app layout */}
    </div>
  );
}

// app/(app)/dashboard/page.tsx
// => File: app/(app)/dashboard/page.tsx
// => URL: "/dashboard" (NOT "/app/dashboard")
// => Route group omitted from URL
export default function DashboardPage() {
  // => Dashboard page component
  return (
    <div>
      <h1>Dashboard</h1>
      <p>Your donation history and stats.</p>
    </div>
  );
}
// => Wrapped by AppLayout (teal header, no footer)
// => Route groups enable multiple layouts without URL changes

// app/dashboard/layout.tsx
// => Layout receiving parallel routes as props
export default function DashboardLayout({
  children,
  analytics,                                // => @analytics parallel route
  notifications,                            // => @notifications parallel route
}: {
  children: React.ReactNode;
  analytics: React.ReactNode;               // => Parallel route slot
  notifications: React.ReactNode;           // => Parallel route slot
}) {
  return (
    <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '1rem' }}>
      {/* => Main content */}
      <div style={{ gridColumn: '1 / -1' }}>
        {children}
        {/* => app/dashboard/page.tsx content */}
      </div>

      {/* => Analytics section */}
      <div>
        <h2>Analytics</h2>
        {analytics}
        {/* => app/dashboard/@analytics/page.tsx content */}
      </div>

      {/* => Notifications section */}
      <div>
        <h2>Notifications</h2>
        {notifications}
        {/* => app/dashboard/@notifications/page.tsx content */}
      </div>
    </div>
  );
}

// app/dashboard/page.tsx
// => Main dashboard page
export default function DashboardPage() {
  return (
    <div>
      <h1>Dashboard Overview</h1>
      <p>Welcome to your dashboard.</p>
    </div>
  );
}

// app/dashboard/@analytics/page.tsx
// => Analytics parallel route (@ makes it parallel)
export default function AnalyticsPage() {
  return (
    <div>
      <p>Total Donations: IDR 1,500,000</p>
      <p>This Month: IDR 350,000</p>
    </div>
  );
}

// app/dashboard/@notifications/page.tsx
// => Notifications parallel route
export default function NotificationsPage() {
  return (
    <div>
      <p>✓ Donation processed</p>
      <p>✓ Profile updated</p>
    </div>
  );
}

// app/posts/page.tsx
// => Posts list page
import Link from 'next/link';

export default function PostsPage() {
  const posts = [
    { id: '1', title: 'Zakat Guide' },
    { id: '2', title: 'Murabaha Basics' },
  ];

  return (
    <div>
      <h1>Posts</h1>
      <ul>
        {posts.map(post => (
          <li key={post.id}>
            <Link href={`/posts/${post.id}`}>
              {/* => Link to post detail */}
              {post.title}
            </Link>
          </li>
        ))}
      </ul>
    </div>
  );
}

// app/posts/[id]/page.tsx
// => Full post detail page (direct access)
export default function PostDetailPage({
  params,
}: {
  params: { id: string };
}) {
  return (
    <div>
      <h1>Post {params.id} - Full Page</h1>
      <p>This is the full post page (direct access or refresh).</p>
      <a href="/posts">Back to Posts</a>
    </div>
  );
}

// app/posts/(.)posts/[id]/page.tsx
// => Intercepted route (.) means same level
// => Shows as modal when navigating from /posts
'use client';

import { useRouter } from 'next/navigation';

export default function PostModal({
  params,
}: {
  params: { id: string };
}) {
  const router = useRouter();

  return (
    <div
      style={{
        position: 'fixed',
        top: 0,
        left: 0,
        right: 0,
        bottom: 0,
        background: 'rgba(0,0,0,0.5)',
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'center',
      }}
      onClick={() => router.back()}
      // => Click backdrop closes modal
    >
      <div
        style={{
          background: 'white',
          padding: '2rem',
          borderRadius: '8px',
          maxWidth: '500px',
        }}
        onClick={e => e.stopPropagation()}
        // => Prevent closing when clicking modal content
      >
        <h1>Post {params.id} - Modal</h1>
        <p>This is the modal view (soft navigation).</p>
        <button onClick={() => router.back()}>Close</button>
      </div>
    </div>
  );
}

// app/lib/schemas.ts
import { z } from "zod";
// => Import Zod schema builder

// => Zod schema for donation form
export const donationSchema = z.object({
  name: z.string().min(2, "Name must be at least 2 characters").max(50, "Name must be less than 50 characters"),
  // => String validation with length constraints

  email: z.string().email("Invalid email address"),
  // => Email format validation

  amount: z
    .number()
    .min(10000, "Minimum donation is IDR 10,000")
    .max(1000000000, "Maximum donation is IDR 1,000,000,000"),
  // => Number validation with range

  category: z.enum(["zakat", "sadaqah", "infaq"], {
    errorMap: () => ({ message: "Invalid category" }),
  }),
  // => Enum validation (must be one of these values)
});

// => TypeScript type inferred from schema
export type DonationInput = z.infer<typeof donationSchema>;
// => DonationInput is { name: string; email: string; amount: number; category: "zakat" | "sadaqah" | "infaq" }

// app/actions.ts
("use server");

import { donationSchema } from "./lib/schemas";

export async function submitDonation(formData: FormData) {
  // => Extract form data
  const rawData = {
    name: formData.get("name"),
    email: formData.get("email"),
    amount: parseFloat(formData.get("amount") as string),
    category: formData.get("category"),
  };

  // => Validate with Zod schema
  const result = donationSchema.safeParse(rawData);
  // => safeParse returns { success: boolean, data?: T, error?: ZodError }

  if (!result.success) {
    // => Validation failed
    const errors = result.error.flatten().fieldErrors;
    // => errors is { name?: string[], email?: string[], ... }

    return {
      success: false,
      errors: {
        // => Convert array errors to single messages
        name: errors.name?.[0],
        email: errors.email?.[0],
        amount: errors.amount?.[0],
        category: errors.category?.[0],
      },
    };
  }

  // => Validation passed, data is type-safe
  const { name, email, amount, category } = result.data;
  // => result.data is DonationInput type

  // => Save to database
  console.log(`Donation: ${name} (${email}) - IDR ${amount} - ${category}`);

  return {
    success: true,
    message: `Thank you ${name}! Your ${category} donation of IDR ${amount.toLocaleString()} has been received.`,
  };
}

// app/posts/[id]/page.tsx
'use client';

import { useOptimistic, useTransition } from 'react';
// => Import useOptimistic and useTransition hooks

type Comment = {
  id: string;
  author: string;
  text: string;
  createdAt: Date;
};

export default function PostPage({
  initialComments,
}: {
  initialComments: Comment[];
}) {
  // => useOptimistic manages optimistic state
  const [optimisticComments, addOptimisticComment] = useOptimistic(
    initialComments,                        // => Initial state
    (state, newComment: Comment) => [...state, newComment]
    // => Reducer: how to add optimistic comment
  );

  const [isPending, startTransition] = useTransition();

  async function handleSubmit(formData: FormData) {
    const author = formData.get('author') as string;
    const text = formData.get('text') as string;

    // => Create optimistic comment (shown immediately)
    const optimisticComment: Comment = {
      id: crypto.randomUUID(),
      author,
      text,
      createdAt: new Date(),
    };

    // => Add optimistic comment to UI (instant feedback)
    startTransition(() => {
      addOptimisticComment(optimisticComment);
      // => Comment appears in list immediately
    });

    // => Submit to server (async, might fail)
    try {
      // await createComment(formData);
      // => If server succeeds, page revalidates and shows real comment
      await new Promise(resolve => setTimeout(resolve, 2000));
      console.log('Comment created');
    } catch (error) {
      // => If server fails, optimistic update reverts
      console.error('Failed to create comment');
      // => Optimistic comment disappears from list
    }
  }

  return (
    <div>
      <h1>Post with Comments</h1>

      <div>
        <h2>Comments</h2>
        <ul>
          {optimisticComments.map(comment => (
            <li key={comment.id} style={{ opacity: isPending ? 0.5 : 1 }}>
              {/* => Optimistic comments shown with reduced opacity */}
              <strong>{comment.author}</strong>: {comment.text}
              <small> - {comment.createdAt.toLocaleTimeString()}</small>
            </li>
          ))}
        </ul>
      </div>

      <form action={handleSubmit}>
        <input type="text" name="author" placeholder="Your name" required />
        <textarea name="text" placeholder="Your comment" required />
        <button type="submit" disabled={isPending}>
          {isPending ? 'Posting...' : 'Post Comment'}
        </button>
      </form>
    </div>
  );
}

// app/lib/auth.ts
import { cookies } from 'next/headers';
// => Import cookies function

export async function getCurrentUser() {
  // => Server-only function (can't run on client)
  const cookieStore = cookies();            // => Access cookies
  const authToken = cookieStore.get('auth_token');
  // => authToken is { name: 'auth_token', value: 'token123' } or undefined

  if (!authToken) {
    return null;                            // => Not authenticated
  }

  // => Verify token and get user
  // const user = await db.users.findByToken(authToken.value);
  // => Simplified: return mock user
  return {
    id: '1',
    name: 'Ahmad',
    email: 'ahmad@example.com',
  };
}

// app/actions.ts
'use server';

import { cookies } from 'next/headers';

export async function login(formData: FormData) {
  const email = formData.get('email') as string;
  const password = formData.get('password') as string;

  // => Verify credentials
  if (email === 'user@example.com' && password === 'password123') {
    // => Set auth cookie (simplified)
    cookies().set('auth_token', 'token123', {
      httpOnly: true,                       // => Not accessible via JavaScript (security)
      secure: process.env.NODE_ENV === 'production', // => HTTPS only in production
      sameSite: 'lax',                      // => CSRF protection
      maxAge: 60 * 60 * 24 * 7,            // => 7 days
    });

    return { success: true };
  }

  return { success: false, error: 'Invalid credentials' };
}

export async function logout() {
  // => Delete auth cookie
  cookies().delete('auth_token');
  // => User logged out
}

// app/dashboard/page.tsx
// => Protected page using getCurrentUser
import { getCurrentUser } from '@/app/lib/auth';
import { redirect } from 'next/navigation';

export default async function DashboardPage() {
  const user = await getCurrentUser();      // => Check authentication

  if (!user) {
    // => Not authenticated, redirect to login
    redirect('/login');
    // => Server-side redirect
  }

  return (
    <div>
      <h1>Welcome, {user.name}!</h1>
      <p>Email: {user.email}</p>
      {/* => Protected content only visible to authenticated users */}
    </div>
  );
}

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

// => Protected route patterns
const protectedRoutes = ['/dashboard', '/profile', '/settings'];

export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;

  // => Check if current route is protected
  const isProtected = protectedRoutes.some(route =>
    pathname.startsWith(route)
  );

  if (isProtected) {
    // => Check for auth token
    const authToken = request.cookies.get('auth_token');

    if (!authToken) {
      // => Not authenticated, redirect to login
      const loginUrl = new URL('/login', request.url);
      loginUrl.searchParams.set('redirect', pathname);
      // => Save intended destination for post-login redirect

      return NextResponse.redirect(loginUrl);
    }

    // => TODO: Verify token validity
    // const isValid = await verifyToken(authToken.value);
    // if (!isValid) { return NextResponse.redirect(...) }
  }

  // => Authenticated or public route
  return NextResponse.next();
}

export const config = {
  // => Run middleware on protected routes only
  matcher: ['/dashboard/:path*', '/profile/:path*', '/settings/:path*'],
};

// app/login/page.tsx
'use client';

import { useSearchParams, useRouter } from 'next/navigation';
import { login } from '../actions';

export default function LoginPage() {
  const searchParams = useSearchParams();
  const router = useRouter();
  const redirect = searchParams.get('redirect') || '/dashboard';
  // => Get redirect parameter from URL

  async function handleSubmit(formData: FormData) {
    const result = await login(formData);

    if (result.success) {
      // => Login successful, redirect to intended destination
      router.push(redirect);
    }
  }

  return (
    <div>
      <h1>Login</h1>
      <p>Redirecting to: {redirect}</p>

      <form action={handleSubmit}>
        <input type="email" name="email" required />
        <input type="password" name="password" required />
        <button type="submit">Login</button>
      </form>
    </div>
  );
}

// prisma/schema.prisma
// => Prisma schema defines database structure
// model Post {
//   id        String   @id @default(cuid())
//   title     String
//   content   String
//   published Boolean  @default(false)
//   createdAt DateTime @default(now())
// }

// app/lib/prisma.ts
import { PrismaClient } from '@prisma/client';

// => Singleton pattern for Prisma client
const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClient | undefined;
};

export const prisma =
  globalForPrisma.prisma ??
  new PrismaClient({
    log: ['query'],                         // => Log SQL queries in development
  });

if (process.env.NODE_ENV !== 'production') {
  globalForPrisma.prisma = prisma;
}
// => Prevents multiple Prisma instances in development (hot reload)

// app/posts/page.tsx
// => Server Component with Prisma query
import { prisma } from '@/app/lib/prisma';

export default async function PostsPage() {
  // => Type-safe Prisma query
  const posts = await prisma.post.findMany({
    // => posts is Post[] (TypeScript type from schema)
    where: { published: true },             // => Only published posts
    orderBy: { createdAt: 'desc' },         // => Newest first
    take: 10,                               // => Limit to 10 posts
    select: {
      // => Select specific fields
      id: true,
      title: true,
      createdAt: true,
    },
  });
  // => Query runs on server, results cached

  return (
    <div>
      <h1>Published Posts</h1>
      <ul>
        {posts.map(post => (
          <li key={post.id}>
            <strong>{post.title}</strong>
            <small> - {post.createdAt.toLocaleDateString()}</small>
          </li>
        ))}
      </ul>
    </div>
  );
}

// app/actions.ts
'use server';

import { prisma } from './lib/prisma';
import { revalidatePath } from 'next/cache';

export async function createPost(formData: FormData) {
  const title = formData.get('title') as string;
  const content = formData.get('content') as string;

  // => Create post with Prisma
  const post = await prisma.post.create({
    data: {
      title,
      content,
      published: true,
    },
  });
  // => post is Post object with all fields

  // => Revalidate posts page
  revalidatePath('/posts');

  return { success: true, postId: post.id };
}