create-handover 0.1.1

package/template/app/globals.css

@@ -0,0 +1,118 @@
+@import "tailwindcss";
+
+:root {
+  --bg-900: #0f1724;
+  --bg-800: #17283b;
+  --surface-100: #f8fafc;
+  --surface-200: #eef2f6;
+  --surface-300: #dce3ec;
+  --text-900: #0f172a;
+  --text-700: #334155;
+  --text-500: #64748b;
+  --brand-500: #0d9488;
+  --brand-600: #0f766e;
+  --danger-500: #dc2626;
+  --danger-600: #b91c1c;
+  --success-600: #15803d;
+  --warning-600: #b45309;
+  --surface-card-bg: #ffffff;
+  --radius-lg: 0.75rem;
+  --radius-xl: 1rem;
+  --shadow-soft: 0 10px 30px rgba(15, 23, 42, 0.06);
+  --background: var(--surface-100);
+  --foreground: var(--text-900);
+
+  /* Spacing Scale (4px base unit) */
+  --spacing-1: 0.25rem;   /* 4px */
+  --spacing-2: 0.5rem;    /* 8px */
+  --spacing-3: 0.75rem;   /* 12px */
+  --spacing-4: 1rem;      /* 16px */
+  --spacing-5: 1.25rem;   /* 20px */
+  --spacing-6: 1.5rem;    /* 24px */
+  --spacing-8: 2rem;      /* 32px */
+  --spacing-10: 2.5rem;   /* 40px */
+  --spacing-12: 3rem;     /* 48px */
+  --spacing-16: 4rem;     /* 64px */
+  --spacing-20: 5rem;     /* 80px */
+  --spacing-24: 6rem;     /* 96px */
+
+  /* Semantic Spacing */
+  --spacing-inline: var(--spacing-2);      /* 8px - Between inline elements */
+  --spacing-stack: var(--spacing-4);       /* 16px - Between stacked elements */
+  --spacing-card: var(--spacing-6);        /* 24px - Card/component padding */
+  --spacing-card-compact: var(--spacing-4); /* 16px - Compact card padding */
+  --spacing-section: var(--spacing-8);     /* 32px - Between major sections */
+  --spacing-page-x: var(--spacing-4);      /* 16px - Page horizontal padding */
+  --spacing-page-y: var(--spacing-8);      /* 32px - Page vertical padding */
+}
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --font-sans: var(--font-geist-sans);
+  --font-mono: var(--font-geist-mono);
+}
+
+body {
+  background: var(--background);
+  color: var(--foreground);
+  font-family: var(--font-geist-sans), "Segoe UI", sans-serif;
+}
+
+/* Global focus-visible styles for accessibility */
+button:focus-visible,
+a:focus-visible,
+input:focus-visible,
+select:focus-visible,
+textarea:focus-visible,
+[role="tab"]:focus-visible,
+[role="button"]:focus-visible,
+[tabindex]:not([tabindex="-1"]):focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 3px rgba(13, 148, 136, 0.25);
+}
+
+/* Ensure focus-visible is only shown on keyboard navigation */
+*:focus:not(:focus-visible) {
+  outline: none;
+  box-shadow: none;
+}
+
+.surface-card {
+  background: var(--surface-card-bg);
+  border: 1px solid var(--surface-300);
+  border-radius: var(--radius-xl);
+  box-shadow: var(--shadow-soft);
+}
+
+.admin-shell {
+  background:
+    radial-gradient(1200px 400px at 10% -10%, rgba(13, 148, 136, 0.14), transparent 60%),
+    radial-gradient(900px 300px at 90% 0%, rgba(23, 40, 59, 0.16), transparent 55%),
+    var(--surface-100);
+}
+
+.section-label {
+  font-size: 0.72rem;
+  font-weight: 600;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--text-500);
+}
+
+.focus-ring {
+  /* Legacy class - now handled by global focus-visible styles */
+  /* Kept for backwards compatibility */
+}
+
+.error-banner {
+  border: 1px solid rgba(220, 38, 38, 0.3);
+  background: rgba(220, 38, 38, 0.08);
+  color: #991b1b;
+}
+
+@media (max-width: 768px) {
+  .surface-card {
+    border-radius: var(--radius-lg);
+  }
+}

package/template/app/layout.tsx

@@ -0,0 +1,36 @@
+import { Geist, Geist_Mono } from "next/font/google";
+import "./globals.css";
+import { HandoverProvider } from "@/components/HandoverProvider";
+
+const geistSans = Geist({
+  variable: "--font-geist-sans",
+  subsets: ["latin"],
+});
+
+const geistMono = Geist_Mono({
+  variable: "--font-geist-mono",
+  subsets: ["latin"],
+});
+
+export const metadata = {
+  title: "Client Admin | Handover Template",
+  description: "Client-facing content admin powered by Handover.",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="en">
+      <body
+        className={`${geistSans.variable} ${geistMono.variable} antialiased`}
+      >
+        <HandoverProvider>
+          {children}
+        </HandoverProvider>
+      </body>
+    </html>
+  );
+}

package/template/app/page.tsx

@@ -0,0 +1,78 @@
+import Link from "next/link";
+import { branding } from "@/lib/branding";
+
+/**
+ * Homepage - currently static, but when CMS content is integrated:
+ * 
+ * IMPORTANT: Add ISR (Incremental Static Regeneration) to keep content fresh
+ * while maintaining performance benefits of static generation.
+ * 
+ * Example implementation when fetching from Handover SDK:
+ * ```typescript
+ * export const revalidate = 60; // Revalidate every 60 seconds
+ * 
+ * export default async function Home() {
+ *   const sdk = createHandoverSDK();
+ *   const content = await sdk.getPageContent('home');
+ *   // ... render CMS content
+ * }
+ * ```
+ * 
+ * The revalidate value balances freshness vs. build load:
+ * - High traffic sites: 300-3600 (5min-1hr)
+ * - Medium traffic: 60-300 (1-5min)
+ * - Low traffic or frequent updates: 30-60 (30sec-1min)
+ */
+export default function Home() {
+  return (
+    <div className="min-h-screen admin-shell px-4 py-6 sm:px-8 sm:py-10">
+      <main className="mx-auto max-w-5xl space-y-8 sm:space-y-10">
+        <section className="surface-card p-6 sm:p-10">
+          <p className="section-label">{branding.siteName}</p>
+          <h1 className="mt-3 text-2xl sm:text-4xl font-semibold tracking-tight text-slate-900 max-w-2xl">
+            {branding.heroTagline}
+          </h1>
+          <p className="mt-4 text-sm sm:text-base text-slate-600 max-w-2xl">
+            This starter ships with a secure embedded admin that lets authorized clients edit text and media without exposing your platform internals.
+          </p>
+          <div className="mt-8 flex flex-col sm:flex-row gap-3">
+            <Link
+              className="focus-ring inline-flex h-11 items-center justify-center rounded-lg bg-teal-700 px-5 text-sm font-medium text-white hover:bg-teal-800"
+              href="/admin/login"
+            >
+              Open Admin
+            </Link>
+            <a
+              className="focus-ring inline-flex h-11 items-center justify-center rounded-lg border border-slate-300 bg-white px-5 text-sm font-medium text-slate-700 hover:bg-slate-50"
+              href={`mailto:${branding.supportEmail}`}
+            >
+              Contact Support
+            </a>
+          </div>
+        </section>
+
+        <section className="grid grid-cols-1 md:grid-cols-3 gap-4 sm:gap-5">
+          <article className="surface-card p-5">
+            <p className="section-label">Secure by design</p>
+            <p className="mt-2 text-sm text-slate-700">Upload limits and password checks are enforced on the platform API, not in browser-only logic.</p>
+          </article>
+          <article className="surface-card p-5">
+            <p className="section-label">Client ready</p>
+            <p className="mt-2 text-sm text-slate-700">Branding labels and support contact details can be changed via environment variables.</p>
+          </article>
+          <article className="surface-card p-5">
+            <p className="section-label">Operational control</p>
+            <p className="mt-2 text-sm text-slate-700">When the project is locked in your platform dashboard, this site displays the suspension state automatically.</p>
+          </article>
+        </section>
+
+        <section className="surface-card p-5 sm:p-6">
+          <p className="section-label">Next step</p>
+          <p className="mt-2 text-sm text-slate-700">
+            Configure <code>NEXT_PUBLIC_HANDOVER_API_URL</code> and <code>NEXT_PUBLIC_HANDOVER_API_KEY</code>, then share <code>/admin/login</code> with your client.
+          </p>
+        </section>
+      </main>
+    </div>
+  );
+}

package/template/components/HandoverProvider.tsx

@@ -0,0 +1,128 @@
+"use client";
+
+import { createContext, useContext, useEffect, useState, ReactNode } from "react";
+import { Handover, HandoverError } from "@/lib/handover";
+import { ShieldAlert, CreditCard } from "lucide-react";
+
+// Initialize SDK instance
+const handover = new Handover({
+    apiKey: process.env.NEXT_PUBLIC_HANDOVER_API_KEY || "",
+    url: process.env.NEXT_PUBLIC_HANDOVER_API_URL || "",
+});
+
+interface HandoverContextType {
+    handover: Handover;
+    text: Record<string, unknown>;
+    images: Array<{ _id: string; url: string; altText?: string; mimeType: string }>;
+    isLoading: boolean;
+    loadError: string | null;
+    refresh: () => Promise<void>;
+}
+
+const HandoverContext = createContext<HandoverContextType | null>(null);
+
+export function useHandover() {
+    const context = useContext(HandoverContext);
+    if (!context) {
+        throw new Error("useHandover must be used within a HandoverProvider");
+    }
+    return context;
+}
+
+export function HandoverProvider({ children }: { children: ReactNode }) {
+    const [text, setText] = useState<Record<string, unknown>>({});
+    const [images, setImages] = useState<Array<{ _id: string; url: string; altText?: string; mimeType: string }>>([]);
+    const [isLocked, setIsLocked] = useState(false);
+    const [isLoading, setIsLoading] = useState(true);
+    const [loadError, setLoadError] = useState<string | null>(null);
+
+    const fetchContent = async () => {
+        // If no API key is set, we can't do anything (or handled gracefully)
+        if (!process.env.NEXT_PUBLIC_HANDOVER_API_KEY) {
+            setLoadError("Missing NEXT_PUBLIC_HANDOVER_API_KEY");
+            setIsLoading(false);
+            return;
+        }
+
+        if (!process.env.NEXT_PUBLIC_HANDOVER_API_URL) {
+            setLoadError("Missing NEXT_PUBLIC_HANDOVER_API_URL");
+            setIsLoading(false);
+            return;
+        }
+
+        try {
+            const data = await handover.getContent();
+            // Data is now { text, images }
+            setText(data.text || {});
+            setImages(data.images || []);
+            setLoadError(null);
+        } catch (error: unknown) {
+            if (error instanceof HandoverError && error.code === "HANDOVER_LOCKED") {
+                setIsLocked(true);
+            } else if (error instanceof HandoverError && error.code === "INVALID_API_KEY") {
+                setLoadError("The configured API key is invalid for this project.");
+            } else {
+                setLoadError("Failed to load content from Handover. Check API URL and connectivity.");
+            }
+        } finally {
+            setIsLoading(false);
+        }
+    };
+
+    useEffect(() => {
+        fetchContent();
+    }, []);
+
+    if (loadError && !isLocked) {
+        return (
+            <div className="min-h-screen admin-shell flex items-center justify-center p-4">
+                <div className="surface-card w-full max-w-lg p-6 sm:p-8 space-y-4 text-left">
+                    <div className="section-label">Configuration issue</div>
+                    <h1 className="text-xl sm:text-2xl font-semibold text-slate-900">Template is not fully configured</h1>
+                    <p className="text-sm sm:text-base text-slate-600 break-words">{loadError}</p>
+                    <p className="text-xs sm:text-sm text-slate-500">
+                        Add the required environment variables and reload this app:
+                    </p>
+                    <ul className="text-xs sm:text-sm text-slate-700 list-disc pl-5 space-y-1">
+                        <li><code>NEXT_PUBLIC_HANDOVER_API_URL</code></li>
+                        <li><code>NEXT_PUBLIC_HANDOVER_API_KEY</code></li>
+                    </ul>
+                </div>
+            </div>
+        );
+    }
+
+    if (isLocked) {
+        return (
+            <div className="min-h-screen flex items-center justify-center bg-gray-50 text-gray-900 p-4">
+                <div className="max-w-md w-full bg-white shadow-xl rounded-xl p-8 text-center space-y-6 border border-gray-100">
+                    <div className="bg-red-50 w-16 h-16 rounded-full flex items-center justify-center mx-auto mb-4">
+                        <ShieldAlert className="w-8 h-8 text-red-500" />
+                    </div>
+
+                    <div className="space-y-2">
+                        <h1 className="text-2xl font-bold tracking-tight text-gray-900">
+                            Service Suspended
+                        </h1>
+                        <p className="text-gray-500">
+                            This website is temporarily unavailable due to a billing issue or administrative lock.
+                        </p>
+                    </div>
+
+                    <div className="pt-4 border-t border-gray-100">
+                        <div className="flex items-center justify-center gap-2 text-sm text-gray-400">
+                            <CreditCard className="w-4 h-4" />
+                            <span>Payment Required (402)</span>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        );
+    }
+
+    return (
+        <HandoverContext.Provider value={{ handover, text, images, isLoading, loadError, refresh: fetchContent }}>
+            {children}
+        </HandoverContext.Provider>
+    );
+}

package/template/components/Modal.tsx

@@ -0,0 +1,75 @@
+"use client";
+
+import { X } from "lucide-react";
+import { useEffect, useState } from "react";
+import { createPortal } from "react-dom";
+
+interface ModalProps {
+    isOpen: boolean;
+    onClose: () => void;
+    title: string;
+    children: React.ReactNode;
+    footer?: React.ReactNode;
+}
+
+export function Modal({ isOpen, onClose, title, children, footer }: ModalProps) {
+    const [isAnimating, setIsAnimating] = useState(false);
+    const [shouldRender, setShouldRender] = useState(false);
+
+    useEffect(() => {
+        if (isOpen) {
+            setShouldRender(true);
+            document.body.style.overflow = "hidden";
+            // Trigger animation after render
+            requestAnimationFrame(() => {
+                setIsAnimating(true);
+            });
+        } else {
+            setIsAnimating(false);
+            // Wait for exit animation to complete
+            const timeout = setTimeout(() => {
+                setShouldRender(false);
+            }, 200);
+            document.body.style.overflow = "unset";
+            return () => clearTimeout(timeout);
+        }
+        return () => {
+            document.body.style.overflow = "unset";
+        };
+    }, [isOpen]);
+
+    if (!shouldRender) return null;
+
+    return createPortal(
+        <div 
+            className={`fixed inset-0 z-50 flex items-center justify-center p-4 bg-black/50 backdrop-blur-sm transition-opacity duration-200 ${
+                isAnimating ? 'opacity-100' : 'opacity-0'
+            }`}
+            onClick={onClose}
+        >
+            <div 
+                className={`bg-white rounded-xl shadow-xl w-full max-w-md overflow-hidden transition-all duration-200 ${
+                    isAnimating ? 'opacity-100 scale-100 translate-y-0' : 'opacity-0 scale-95 translate-y-4'
+                }`}
+                onClick={(e) => e.stopPropagation()}
+            >
+                <div className="flex items-center justify-between p-4 border-b border-gray-100">
+                    <h3 className="font-semibold text-gray-900">{title}</h3>
+                    <button
+                        onClick={onClose}
+                        className="focus-ring text-gray-400 hover:text-gray-500 transition-colors rounded-md p-1"
+                    >
+                        <X className="w-5 h-5" />
+                    </button>
+                </div>
+                <div className="p-4">{children}</div>
+                {footer && (
+                    <div className="bg-gray-50 px-4 py-3 border-t border-gray-100 flex justify-end gap-2">
+                        {footer}
+                    </div>
+                )}
+            </div>
+        </div>,
+        document.body
+    );
+}

package/template/eslint.config.mjs

@@ -0,0 +1,18 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  // Override default ignores of eslint-config-next.
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+  ]),
+]);
+
+export default eslintConfig;

package/template/lib/branding.ts

@@ -0,0 +1,12 @@
+export const branding = {
+  siteName: process.env.NEXT_PUBLIC_SITE_NAME || "Client Site",
+  adminTitle: process.env.NEXT_PUBLIC_ADMIN_TITLE || "Client Admin",
+  supportEmail: process.env.NEXT_PUBLIC_SUPPORT_EMAIL || "support@example.com",
+  heroTagline:
+    process.env.NEXT_PUBLIC_BRAND_TAGLINE ||
+    "Keep your website content fresh with a secure, lightweight admin experience.",
+};
+
+export function getBrandInitial(): string {
+  return branding.siteName.trim().charAt(0).toUpperCase() || "C";
+}