Suspense #

// ANTI-PATTERN: Manual loading state in every component
func Dashboard() *Element {
    user, setUser := useState(nil)
    orders, setOrders := useState(nil)
    stats, setStats := useState(nil)
    userLoading, setUserLoading := useState(true)
    ordersLoading, setOrdersLoading := useState(true)
    statsLoading, setStatsLoading := useState(true)

    useEffect(func() {
        fetchUser().then(func(data any) {
            setUser(data)
            setUserLoading(false)
        })
        fetchOrders().then(func(data any) {
            setOrders(data)
            setOrdersLoading(false)
        })
        fetchStats().then(func(data any) {
            setStats(data)
            setStatsLoading(false)
        })
    })

    return renderFragment(
        renderConditional(userLoading, renderUserSkeleton(), renderUserProfile(user)),
        renderConditional(ordersLoading, renderOrdersSkeleton(), renderRecentOrders(orders)),
        renderConditional(statsLoading, renderStatsSkeleton(), renderStatsCards(stats)),
    )
}

// Problems:
// → Loading state boilerplate in every component
// → Inconsistent — every developer can implement it differently
// → Hard to coordinate content appearance order
// → Data-fetching components and loading UI are mixed

// CORRECT: The Suspense boundary manages loading state
func Dashboard() *Element {
    return renderFragment(
        renderSuspense(renderUserSkeleton(), func() *Element {
            return renderUserProfile() // Fetches its own data
        }),
        renderSuspense(renderOrdersSkeleton(), func() *Element {
            return renderRecentOrders() // Fetches its own data
        }),
        renderSuspense(renderStatsSkeleton(), func() *Element {
            return renderStatsCards() // Fetches its own data
        }),
    )
}

// Advantages:
// → Every section loads independently
// → Components focus on rendering, not loading management
// → Loading states consistent and centralized

// React.lazy — Suspense for code splitting
// (React is a framework API — this shows the equivalent lazy-loading logic)
var HeavyChart = lazyLoad(func() *Element { return loadComponent("HeavyChart") })
var DataTable = lazyLoad(func() *Element { return loadComponent("DataTable") })
var RichEditor = lazyLoad(func() *Element { return loadComponent("RichEditor") })

func ReportPage() *Element {
    return renderFragment(
        renderReportHeader(), // Not lazy — loads immediately

        renderSuspense(renderChartSkeleton(300), func() *Element {
            return renderHeavyChart(reportData)
        }),

        renderSuspense(renderTableSkeleton(10), func() *Element {
            return renderDataTable()
        }),
    )
}

// The framework automatically:
// 1. Starts downloading HeavyChart.chunk.js
// 2. Shows <ChartSkeleton /> during the download
// 3. When the download finishes, replaces the skeleton with the real component
// 4. No if (loading) at all in the parent component

// Suspense with data fetching (React 18 + React Query)
// (React is a framework API — this shows the equivalent suspense logic)
func UserProfile(userId string) *Element {
    // No loading state — the component suspends automatically
    user := useSuspenseQuery("user", userId, func() any { return fetchUser(userId) })

    // This code only executes when the user is available
    return renderFragment(
        renderImage(user.Avatar, user.Name),
        renderHeading(user.Name),
        renderParagraph(user.Email),
    )
}

// The parent doesn't need to know about UserProfile's loading state
func ProfilePage(userId string) *Element {
    return renderSuspense(renderProfileSkeleton(), func() *Element {
        return renderUserProfile(userId)
    })
}

// ANTI-PATTERN: One boundary for everything → fast content waits for slow content
func Dashboard() *Element {
    return renderSuspense(renderFullPageSkeleton(), func() *Element {
        return renderFragment(
            renderUserProfile(),   // ready in 200ms
            renderRecentOrders(),  // ready in 800ms
            renderHeavyAnalytics(),// ready in 3000ms!
        )
    })
}
// UserProfile and RecentOrders must wait for HeavyAnalytics (3 seconds!)
// The whole page is a skeleton until HeavyAnalytics finishes

// CORRECT: Per-section boundaries → each part appears as soon as it's ready
func Dashboard() *Element {
    return renderFragment(
        // Content that's almost always fast — shared boundary above
        renderSuspense(renderHeaderSkeleton(), func() *Element { return renderDashboardHeader() }),

        // Content with independent speeds — separate boundaries
        renderSuspense(renderUserSkeleton(), func() *Element { return renderUserProfile() }),
        renderSuspense(renderOrdersSkeleton(), func() *Element { return renderRecentOrders() }),

        // Heavy content — its own boundary at the bottom
        renderSuspense(renderAnalyticsSkeleton(), func() *Element { return renderHeavyAnalytics() }),
    )
}
// UserProfile appears at 200ms, RecentOrders at 800ms, HeavyAnalytics at 3000ms
// Users can already see and interact with some content much earlier

// Suspense and Error Boundaries
// (React is a framework API — this shows the equivalent error-handling logic)
// Component for showing errors with a retry option
func ErrorFallback(error Error, resetErrorBoundary func()) *Element {
    return renderFragment(
        renderParagraph("Failed to load data: "+error.Message),
        renderButton("Try Again", resetErrorBoundary),
    )
}

// ErrorBoundary + Suspense combination for one section
func OrdersSection() *Element {
    return renderErrorBoundary(
        func() *Element { return renderErrorFallback(error, resetErrorBoundary) },
        renderSuspense(renderOrdersSkeleton(), func() *Element { return renderRecentOrders() }),
    )
}

// Correct order: ErrorBoundary outside Suspense
// If the ErrorBoundary is inside Suspense:
// → Errors from RecentOrders won't be caught by the ErrorBoundary
//   because Suspense intercepts them first

// useTransition — Suspense for navigation
// (React is a framework API — this shows the equivalent transition logic)
func ProductFilter() *Element {
    category, setCategory := useState("all")
    isPending, startTransition := useTransition()

    handleCategoryChange := func(newCategory string) {
        startTransition(func() {
            // This state update is marked as "non-urgent"
            // React keeps showing the old content until the update finishes
            // without showing skeletons/fallbacks
            setCategory(newCategory)
        })
    }

    return renderFragment(
        renderCategoryButtons(
            category,
            handleCategoryChange,
            isPending, // show a light loading indicator on the button
                       // without replacing the entire content with a skeleton
        ),
        renderConditional(isPending, renderLoadingBar(), nil), // Thin progress bar
        renderSuspense(renderProductSkeleton(), func() *Element {
            return renderProductList(category)
        }),
    )
}

// Go backend — Streaming HTML with placeholders + injection
package main

import (
    "fmt"
    "net/http"
    "time"
)

func dashboardHandler(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "text/html; charset=utf-8")
    w.Header().Set("X-Content-Type-Options", "nosniff")
    // Transfer-Encoding: chunked happens automatically when using a Flusher

    flusher, ok := w.(http.Flusher)
    if !ok {
        http.Error(w, "Streaming not supported", http.StatusInternalServerError)
        return
    }

    // === STEP 1: Send the page shell immediately ===
    fmt.Fprint(w, `<!DOCTYPE html>
<html>
<head>
  <title>Dashboard</title>
  <link rel="stylesheet" href="/app.css">
</head>
<body>
  <nav>Dashboard Nav</nav>
  <main>
    <h1>Dashboard</h1>

    <!-- Placeholder for products — shows immediately as a skeleton -->
    <div id="products-container">
      <div class="skeleton skeleton-list"></div>
    </div>

    <!-- Placeholder for recommendations -->
    <div id="reco-container">
      <div class="skeleton skeleton-grid"></div>
    </div>
  </main>
  <footer>Footer</footer>
  <script src="/app.js"></script>
`)
    flusher.Flush()  // Send immediately to the browser

    // === STEP 2: Fetch products data (simulated 200ms) ===
    time.Sleep(200 * time.Millisecond)
    products := fetchProducts()  // actual DB query

    // Inject content into the placeholder via a script
    fmt.Fprintf(w, `<script>
document.getElementById('products-container').innerHTML = %q;
</script>`, renderProductsHTML(products))
    flusher.Flush()

    // === STEP 3: Fetch recommendations (simulated 1.5s) ===
    time.Sleep(1300 * time.Millisecond)  // total 1.5s
    recommendations := fetchRecommendations()

    fmt.Fprintf(w, `<script>
document.getElementById('reco-container').innerHTML = %q;
</script>`, renderRecoHTML(recommendations))
    flusher.Flush()

    // Close the connection
    fmt.Fprint(w, `</body></html>`)
}

// React Server Components + Suspense (Next.js App Router)
// (React is a framework API — this shows the equivalent logic in Go)
// Server Component — fetches data directly in the component
func UserProfile(userId string) *Element {
    user := dbFindUserByID(userId)  // queries the DB directly on the server
    return renderFragment(
        renderImage(user.Avatar, user.Name),
        renderHeading(user.Name),
    )
}

func RecentOrders(userId string) *Element {
    orders := dbFindOrdersByUser(userId)  // can be slower
    return renderOrdersList(orders)
}

func Analytics() *Element {
    stats := fetchExternalAnalytics()  // can be very slow
    return renderStatsCards(stats)
}

// The page is a server component composing the components above
func DashboardPage(params Params) *Element {
    return renderFragment(
        // UserProfile renders on the server, streamed to the client when ready
        renderSuspense(renderProfileSkeleton(), func() *Element {
            return renderUserProfile(params.ID)
        }),

        renderSuspense(renderOrdersSkeleton(), func() *Element {
            return renderRecentOrders(params.ID)
        }),

        // Analytics can be slow — place it below with a separate boundary
        renderSuspense(renderAnalyticsSkeleton(), func() *Element {
            return renderAnalytics()
        }),
    )
}

// Next.js / React automatically:
// 1. Renders the page shell immediately
// 2. Streams each section when its data is ready on the server
// 3. The browser receives and displays content progressively
// → No client-to-API request waterfalls
// → TTFB stays low because the shell is sent immediately

// ANTI-PATTERN: Generic spinners aren't informative
renderSuspense(renderDiv("Loading..."), func() *Element { return renderProductList() })
// Users don't know what structure will appear
// Severe layout shifts when content appears (high CLS)

// CORRECT: Skeletons resembling the real content
func ProductListSkeleton() *Element {
    return renderDivClass("product-grid",
        renderCards(8, func(i int) *Element {
            return renderDivClass("product-card-skeleton",
                renderSkeleton("skeleton-image", 200),
                renderSkeletonText("80%"),
                renderSkeletonText("60%"),
                renderSkeletonText("40%"),
            )
        }),
    )
}

renderSuspense(renderProductListSkeleton(), func() *Element { return renderProductList() })
// Advantages:
// → Users know there will be 8 product cards
// → No layout shifts when content appears (low CLS)
// → Feels "loading", not "broken"

// ✗ Anti-pattern: one global boundary
func App() *Element {
    return renderSuspense(renderFullPageSpinner(), func() *Element {
        return renderRouter(
            renderRoute("/", renderHome()),
            renderRoute("/dashboard", renderDashboard()),
        )
    })
}
// If one small component in Dashboard suspends → the entire app becomes a spinner!

// ✓ Solution: Suspense boundaries at the right levels
func App() *Element {
    return renderRouter(
        renderRoute("/", func() *Element {
            return renderSuspense(renderHomeSkeleton(), func() *Element { return renderHome() })
        }),
        renderRoute("/dashboard", func() *Element {
            return renderSuspense(renderDashboardSkeleton(), func() *Element { return renderDashboard() })
        }),
    )
}

// ✗ Anti-pattern: Suspense without an Error Boundary
renderSuspense(renderSkeleton(), func() *Element {
    return renderDataComponent() // If the fetch fails → the error isn't caught!
})
// Errors from DataComponent propagate up and crash

// ✓ Solution: Always pair with an Error Boundary
renderErrorBoundary(
    func() *Element { return renderErrorFallback() },
    renderSuspense(renderSkeleton(), func() *Element { return renderDataComponent() }),
)

// ✗ Anti-pattern: fallbacks with wrong dimensions
renderSuspense(renderDivStyle("height: 50px", "Loading..."), func() *Element {
    return renderProductList() // ProductList is actually 800px tall
})
// When content appears: layout shifts from 50px to 800px = high CLS!

// ✓ Solution: Skeletons with dimensions close to the real content
renderSuspense(renderProductListSkeleton(), func() *Element { return renderProductList() }) // ~800px, 8 cards