📚 Complete API Reference

// src/components/live-metrics-header.tsx (Client Component)
"use client";

import { useEffect, useState } from "react";
import { useRouter } from "dinou";

export function LiveMetricsHeader() {
  const router = useRouter();
  const [lastRefreshed, setLastRefreshed] = useState<Date>(new Date());
  const [searchFilter, setSearchFilter] = useState("");

  useEffect(() => {
    // Polls fresh server data every 30 seconds
    const interval = setInterval(() => {
      // Soft reloads server components: local searchFilter and focus are preserved!
      router.refresh();
      setLastRefreshed(new Date());
    }, 30_000);

    return () => clearInterval(interval);
  }, [router]);

  return (
    <div className="flex items-center justify-between p-4 border-b">
      <div>
        <h2 className="font-semibold text-sm">Real-Time Metrics</h2>
        <span className="text-xs text-muted-foreground">
          Last updated: {lastRefreshed.toLocaleTimeString()}
        </span>
      </div>

      {/* Local state is NOT wiped when router.refresh() runs in the background */}
      <input
        type="search"
        value={searchFilter}
        onChange={(e) => setSearchFilter(e.target.value)}
        placeholder="Filter metrics locally..."
        className="text-xs px-2 py-1 border rounded"
      />

      <button
        onClick={() => {
          router.refresh({ layout: true });
          setLastRefreshed(new Date());
        }}
        className="text-xs bg-secondary px-3 py-1.5 rounded hover:bg-secondary/80"
      >
        Refresh All (Including Layout)
      </button>
    </div>
  );
}

// src/components/cart-drawer.tsx (Client Component)
"use client";

import { useRouter } from "dinou";
import { updateQuantityAction } from "@/actions/cart";

export function CartItemRow({ item }: { item: { id: string; qty: number } }) {
  const router = useRouter();

  const handleUpdate = async (delta: number) => {
    await updateQuantityAction(item.id, item.qty + delta);

    // Surgically revalidates only the <DinouCacheSlot id="cart-counter" /> and
    // <DinouCacheSlot id="cart-totals" /> without refetching the full page
    router.refreshSlot("cart-counter", { fresh: true });
    router.refreshSlot("cart-totals", { fresh: true });
  };

  return (
    <div className="flex items-center gap-2">
      <button onClick={() => handleUpdate(-1)}>-</button>
      <span>{item.qty}</span>
      <button onClick={() => handleUpdate(1)}>+</button>
    </div>
  );
}

// src/components/dashboard-toolbar.tsx (Client Component)
"use client";

import { useState } from "react";
import { refreshSlot } from "dinou";

export function DashboardToolbar() {
  const [isRefreshing, setIsRefreshing] = useState(false);

  const handleRefreshAll = () => {
    setIsRefreshing(true);

    // "*" instructs Dinou to revalidate every mounted <DinouCacheSlot> across the page
    refreshSlot("*", { fresh: true });

    setTimeout(() => setIsRefreshing(false), 600);
  };

  return (
    <div className="flex items-center justify-between p-4 bg-card border rounded-lg">
      <h2 className="text-sm font-semibold">Analytics Overview</h2>
      <button
        onClick={handleRefreshAll}
        disabled={isRefreshing}
        className="px-3 py-1.5 text-xs bg-primary text-primary-foreground rounded-md font-medium hover:bg-primary/90 transition-colors"
      >
        {isRefreshing ? "Updating all slots..." : "Refresh All Widgets"}
      </button>
    </div>
  );
}

// src/stores/cart-store.ts (Client Action / Store)
import { refreshSlot } from "dinou";

export async function onCartItemAdded(productId: string) {
  await fetch(`/api/cart/items`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ productId, quantity: 1 }),
  });

  // Revalidate the cart summary slot and checkout totals immediately
  refreshSlot("cart-summary", { fresh: true });
  refreshSlot("checkout-totals", { fresh: true });
}

// src/components/global-spinner.tsx (Client Component)
"use client";

import { useNavigationLoading } from "dinou";

export function GlobalNavigationIndicator() {
  const isNavigating = useNavigationLoading();

  if (!isNavigating) return null;

  return (
    <div
      role="status"
      aria-live="polite"
      className="fixed bottom-4 right-4 z-50 flex items-center gap-2 px-3 py-2 bg-card border rounded-full shadow-lg text-xs font-medium text-foreground transition-all"
    >
      <div className="h-3 w-3 rounded-full border-2 border-primary border-t-transparent animate-spin" />
      <span>Loading content...</span>
    </div>
  );
}

// src/components/nav-button.tsx (Client Component)
"use client";

import { useNavigationLoading, useRouter } from "dinou";

interface NavButtonProps {
  href: string;
  children: React.ReactNode;
}

export function NavButton({ href, children }: NavButtonProps) {
  const router = useRouter();
  const isNavigating = useNavigationLoading();

  return (
    <button
      onClick={() => router.push(href)}
      disabled={isNavigating}
      className="px-4 py-2 bg-primary text-primary-foreground rounded-md text-sm font-medium disabled:opacity-50 disabled:cursor-not-allowed transition-opacity"
    >
      {isNavigating ? "Navigating..." : children}
    </button>
  );
}