create-zerotal 1.0.0

package/templates/react/resources/js/Components/Card.tsx

@@ -0,0 +1,40 @@
+import type { ComponentProps } from "react";
+import { cn } from "../lib/cn";
+
+/**
+ * The app's surface primitive — a hairline border with a faint inner highlight
+ * (see the `surface` utility in resources/css/app.css) instead of a drop shadow.
+ *
+ * Pass `interactive` for cards that are links or buttons: it adds a hover lift
+ * and a border tint so the affordance is obvious without a shadow.
+ */
+export function Card({
+  className,
+  interactive = false,
+  ...rest
+}: ComponentProps<"div"> & { interactive?: boolean }) {
+  return (
+    <div
+      className={cn(
+        "surface rounded-xl",
+        interactive &&
+          "transition-[transform,border-color,box-shadow] duration-200 hover:-translate-y-0.5 hover:border-primary/40",
+        className,
+      )}
+      {...rest}
+    />
+  );
+}
+
+/** Small square glyph holder used at the top of a feature card. */
+export function CardIcon({ className, ...rest }: ComponentProps<"div">) {
+  return (
+    <div
+      className={cn(
+        "grid size-10 place-items-center rounded-lg border border-border bg-accent text-accent-foreground",
+        className,
+      )}
+      {...rest}
+    />
+  );
+}

package/templates/react/resources/js/Components/Code.tsx

@@ -0,0 +1,33 @@
+import type { ComponentProps } from "react";
+import { cn } from "../lib/cn";
+
+/** Inline code chip — for file paths, package names and commands used in prose. */
+export function Code({ className, ...rest }: ComponentProps<"code">) {
+  return (
+    <code
+      className={cn(
+        "rounded-md border border-border bg-muted px-1.5 py-0.5 font-mono text-[0.85em] text-foreground",
+        className,
+      )}
+      {...rest}
+    />
+  );
+}
+
+/** A terminal-styled block for a command the reader is meant to run. */
+export function Command({ children, className, ...rest }: ComponentProps<"div">) {
+  return (
+    <div
+      className={cn(
+        "flex items-center gap-3 rounded-lg border border-border bg-muted px-3.5 py-2.5 font-mono text-sm",
+        className,
+      )}
+      {...rest}
+    >
+      <span aria-hidden="true" className="text-primary select-none">
+        $
+      </span>
+      <span className="overflow-x-auto text-foreground">{children}</span>
+    </div>
+  );
+}

package/templates/react/resources/js/Components/Field.tsx

@@ -0,0 +1,125 @@
+import { useId, type ComponentProps, type ReactNode } from "react";
+import { cn } from "../lib/cn";
+
+/**
+ * Labelled form controls with error and hint text wired up.
+ *
+ * The point of these is the accessibility plumbing you would otherwise retype on
+ * every form: the label is bound to the control by id, the error and hint are
+ * announced via `aria-describedby`, and a failed field is marked `aria-invalid`
+ * rather than only turning red. Pass `error={errors.email}` straight from
+ * Inertia's shared `errors` prop.
+ */
+
+interface FieldProps {
+  label: string;
+  error?: string | undefined;
+  hint?: string | undefined;
+}
+
+const CONTROL =
+  "w-full rounded-lg border bg-card px-3 py-2 text-sm text-foreground shadow-sm " +
+  "transition-colors placeholder:text-muted-foreground focus:outline-none " +
+  "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring";
+
+function Shell({
+  label,
+  error,
+  hint,
+  controlId,
+  errorId,
+  hintId,
+  children,
+}: FieldProps & {
+  controlId: string;
+  errorId: string;
+  hintId: string;
+  children: ReactNode;
+}) {
+  return (
+    <div className="space-y-1.5">
+      <label htmlFor={controlId} className="block text-sm font-medium text-foreground">
+        {label}
+      </label>
+
+      {children}
+
+      {error ? (
+        <p id={errorId} role="alert" className="text-sm text-destructive">
+          {error}
+        </p>
+      ) : hint ? (
+        <p id={hintId} className="text-sm text-muted-foreground">
+          {hint}
+        </p>
+      ) : null}
+    </div>
+  );
+}
+
+export function TextField({
+  label,
+  error,
+  hint,
+  className,
+  ...rest
+}: FieldProps & ComponentProps<"input">) {
+  const id = useId();
+  const controlId = rest.id ?? `${id}-control`;
+
+  return (
+    <Shell
+      label={label}
+      error={error}
+      hint={hint}
+      controlId={controlId}
+      errorId={`${id}-error`}
+      hintId={`${id}-hint`}
+    >
+      <input
+        {...rest}
+        id={controlId}
+        aria-invalid={error ? true : undefined}
+        aria-describedby={error ? `${id}-error` : hint ? `${id}-hint` : undefined}
+        className={cn(CONTROL, error ? "border-destructive" : "border-input", className)}
+      />
+    </Shell>
+  );
+}
+
+export function TextAreaField({
+  label,
+  error,
+  hint,
+  className,
+  rows = 5,
+  ...rest
+}: FieldProps & ComponentProps<"textarea">) {
+  const id = useId();
+  const controlId = rest.id ?? `${id}-control`;
+
+  return (
+    <Shell
+      label={label}
+      error={error}
+      hint={hint}
+      controlId={controlId}
+      errorId={`${id}-error`}
+      hintId={`${id}-hint`}
+    >
+      <textarea
+        {...rest}
+        id={controlId}
+        rows={rows}
+        aria-invalid={error ? true : undefined}
+        aria-describedby={error ? `${id}-error` : hint ? `${id}-hint` : undefined}
+        className={cn(
+          CONTROL,
+          "resize-y",
+          error ? "border-destructive" : "border-input",
+          className,
+        )}
+      />
+    </Shell>
+  );
+}

package/templates/react/resources/js/Components/FlashToasts.tsx

@@ -0,0 +1,79 @@
+import { useEffect, useState } from "react";
+import { usePage } from "@inertiajs/react";
+import { cn } from "../lib/cn";
+import { CheckIcon, CloseIcon } from "./Icons";
+import type { SharedProps } from "../types";
+
+/**
+ * Auto-dismissing toasts driven by the shared `flash` prop.
+ *
+ * A route calls `http.flash("success", "…")` before redirecting; the flash
+ * survives exactly one request, `@zerotal/inertia` merges it into every page's
+ * props, and this component turns it into a toast. Rendered once in AppLayout,
+ * so no page has to think about it.
+ */
+
+interface Toast {
+  id: number;
+  kind: "success" | "error";
+  message: string;
+}
+
+const TONE: Record<Toast["kind"], string> = {
+  success: "border-success/40 text-success",
+  error: "border-destructive/40 text-destructive",
+};
+
+export default function FlashToasts() {
+  const { flash } = usePage<SharedProps>().props;
+  const [toasts, setToasts] = useState<Toast[]>([]);
+
+  useEffect(() => {
+    const next: Toast[] = [];
+    if (flash?.success) next.push({ id: Date.now(), kind: "success", message: flash.success });
+    if (flash?.error) next.push({ id: Date.now() + 1, kind: "error", message: flash.error });
+    if (next.length === 0) return;
+
+    setToasts((prev) => [...prev, ...next]);
+    const timer = setTimeout(() => {
+      setToasts((prev) => prev.filter((t) => !next.some((n) => n.id === t.id)));
+    }, 5000);
+    return () => clearTimeout(timer);
+  }, [flash?.success, flash?.error]);
+
+  if (toasts.length === 0) return null;
+
+  return (
+    <div
+      aria-live="polite"
+      className="pointer-events-none fixed inset-x-4 bottom-4 z-50 flex flex-col items-end gap-2 sm:inset-x-auto sm:right-6"
+    >
+      {toasts.map((toast) => (
+        <div
+          key={toast.id}
+          className={cn(
+            "pointer-events-auto flex w-full max-w-sm items-start gap-3 rounded-xl border bg-card p-3.5 shadow-lg",
+            TONE[toast.kind],
+          )}
+        >
+          <span className="mt-0.5 shrink-0">
+            {toast.kind === "success" ? (
+              <CheckIcon className="size-4.5" />
+            ) : (
+              <CloseIcon className="size-4.5" />
+            )}
+          </span>
+          <p className="flex-1 text-sm text-card-foreground">{toast.message}</p>
+          <button
+            type="button"
+            aria-label="Dismiss"
+            onClick={() => setToasts((prev) => prev.filter((t) => t.id !== toast.id))}
+            className="shrink-0 rounded text-muted-foreground transition-colors hover:text-foreground"
+          >
+            <CloseIcon className="size-4" />
+          </button>
+        </div>
+      ))}
+    </div>
+  );
+}

package/templates/react/resources/js/Components/Icons.tsx

@@ -0,0 +1,149 @@
+import type { SVGProps } from "react";
+
+/**
+ * The handful of icons this starter needs, inlined.
+ *
+ * They are plain `stroke="currentColor"` SVGs, so they inherit text colour and
+ * follow the theme with no extra wiring — and no icon package to install. Reach
+ * for a real icon set once you outgrow these.
+ */
+
+type IconProps = SVGProps<SVGSVGElement>;
+
+function Svg({ children, ...props }: IconProps) {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      {...props}
+    >
+      {children}
+    </svg>
+  );
+}
+
+export function SunIcon(props: IconProps) {
+  return (
+    <Svg {...props}>
+      <circle cx="12" cy="12" r="4" />
+      <path d="M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4" />
+    </Svg>
+  );
+}
+
+export function MoonIcon(props: IconProps) {
+  return (
+    <Svg {...props}>
+      <path d="M21 12.8A9 9 0 1 1 11.2 3 7 7 0 0 0 21 12.8z" />
+    </Svg>
+  );
+}
+
+export function MenuIcon(props: IconProps) {
+  return (
+    <Svg {...props}>
+      <path d="M4 7h16M4 12h16M4 17h16" />
+    </Svg>
+  );
+}
+
+export function CloseIcon(props: IconProps) {
+  return (
+    <Svg {...props}>
+      <path d="M18 6 6 18M6 6l12 12" />
+    </Svg>
+  );
+}
+
+export function ArrowRightIcon(props: IconProps) {
+  return (
+    <Svg {...props}>
+      <path d="M5 12h14M13 6l6 6-6 6" />
+    </Svg>
+  );
+}
+
+export function CheckIcon(props: IconProps) {
+  return (
+    <Svg {...props}>
+      <path d="m20 6-11 11-5-5" />
+    </Svg>
+  );
+}
+
+export function FolderIcon(props: IconProps) {
+  return (
+    <Svg {...props}>
+      <path d="M3 7a2 2 0 0 1 2-2h3.9a2 2 0 0 1 1.6.8l1 1.2H19a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z" />
+    </Svg>
+  );
+}
+
+export function LayersIcon(props: IconProps) {
+  return (
+    <Svg {...props}>
+      <path d="m12 3 9 5-9 5-9-5 9-5z" />
+      <path d="m3 12 9 5 9-5" />
+      <path d="m3 16.5 9 5 9-5" />
+    </Svg>
+  );
+}
+
+export function ShieldIcon(props: IconProps) {
+  return (
+    <Svg {...props}>
+      <path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z" />
+      <path d="m9 12 2 2 4-4" />
+    </Svg>
+  );
+}
+
+export function DatabaseIcon(props: IconProps) {
+  return (
+    <Svg {...props}>
+      <path d="M3 6c0-1.7 4-3 9-3s9 1.3 9 3-4 3-9 3-9-1.3-9-3z" />
+      <path d="M3 6v6c0 1.7 4 3 9 3s9-1.3 9-3V6" />
+      <path d="M3 12v6c0 1.7 4 3 9 3s9-1.3 9-3v-6" />
+    </Svg>
+  );
+}
+
+export function ClockIcon(props: IconProps) {
+  return (
+    <Svg {...props}>
+      <circle cx="12" cy="12" r="9" />
+      <path d="M12 7v5.2l3.2 2" />
+    </Svg>
+  );
+}
+
+export function BoltIcon(props: IconProps) {
+  return (
+    <Svg {...props}>
+      <path d="m13 2-9 12h7l-1 8 9-12h-7l1-8z" />
+    </Svg>
+  );
+}
+
+export function TerminalIcon(props: IconProps) {
+  return (
+    <Svg {...props}>
+      <path d="m5 8 4 4-4 4M12 16h7" />
+      <rect x="2" y="3" width="20" height="18" rx="2.5" />
+    </Svg>
+  );
+}
+
+export function MailIcon(props: IconProps) {
+  return (
+    <Svg {...props}>
+      <rect x="2.5" y="5" width="19" height="14" rx="2.5" />
+      <path d="m3 7 8.1 5.4a1.6 1.6 0 0 0 1.8 0L21 7" />
+    </Svg>
+  );
+}

package/templates/react/resources/js/Components/ThemeToggle.tsx

@@ -0,0 +1,47 @@
+import { useCallback, useState } from "react";
+import { MoonIcon, SunIcon } from "./Icons";
+
+/**
+ * Light/dark switch.
+ *
+ * The class on `<html>` is the single source of truth — every colour in the app
+ * is a CSS custom property that `.dark` redefines, so flipping the class
+ * re-themes the page with no re-render and no `dark:` variants scattered through
+ * the components. The choice is persisted under the same storage key the
+ * no-flash script in resources/app.html reads on boot.
+ */
+
+const STORAGE_KEY = "zerotal-theme";
+
+function isDark(): boolean {
+  return typeof document !== "undefined" && document.documentElement.classList.contains("dark");
+}
+
+export default function ThemeToggle() {
+  const [dark, setDark] = useState(isDark);
+
+  const toggle = useCallback(() => {
+    const next = !isDark();
+    document.documentElement.classList.toggle("dark", next);
+    try {
+      localStorage.setItem(STORAGE_KEY, next ? "dark" : "light");
+    } catch {
+      // Storage can be unavailable (private mode). The class is still applied,
+      // the choice just won't survive a reload.
+    }
+    setDark(next);
+  }, []);
+
+  return (
+    <button
+      type="button"
+      onClick={toggle}
+      aria-pressed={dark}
+      aria-label={dark ? "Switch to light theme" : "Switch to dark theme"}
+      title={dark ? "Switch to light theme" : "Switch to dark theme"}
+      className="grid size-9 place-items-center rounded-lg border border-border bg-card text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+    >
+      {dark ? <MoonIcon className="size-4.5" /> : <SunIcon className="size-4.5" />}
+    </button>
+  );
+}

package/templates/react/resources/js/Layouts/AppLayout.tsx

@@ -0,0 +1,163 @@
+import { useEffect, useState, type ReactNode } from "react";
+import { Link, usePage } from "@inertiajs/react";
+import FlashToasts from "../Components/FlashToasts";
+import ThemeToggle from "../Components/ThemeToggle";
+import { CloseIcon, MenuIcon } from "../Components/Icons";
+import { APP_NAME, DOCS_URL } from "../lib/site";
+import { cn } from "../lib/cn";
+
+/**
+ * Shared application shell — decorative backdrop, sticky header with
+ * active-aware navigation, and a footer.
+ *
+ * Use it as an Inertia persistent layout so the header survives client-side
+ * navigations and only the page body re-renders:
+ *
+ *   Page.layout = (page) => <AppLayout>{page}</AppLayout>;
+ *
+ * Header, content and footer all share the same `max-w-5xl px-6` container, so
+ * the nav and the page body line up at every breakpoint. Pages that want a
+ * narrower measure wrap their own content rather than changing this one.
+ */
+
+const NAV = [
+  { href: "/", label: "Home" },
+  { href: "/about", label: "About" },
+  { href: "/contact", label: "Contact" },
+];
+
+const CONTAINER = "mx-auto w-full max-w-5xl px-6";
+
+function isActive(url: string, href: string): boolean {
+  return href === "/" ? url === "/" : url.startsWith(href);
+}
+
+export default function AppLayout({ children }: { children: ReactNode }) {
+  const { url } = usePage();
+  const [menuOpen, setMenuOpen] = useState(false);
+
+  // Close the mobile menu once a visit lands, otherwise it stays open on top of
+  // the page the user just navigated to.
+  useEffect(() => setMenuOpen(false), [url]);
+
+  const navLink = (href: string) =>
+    cn(
+      "rounded-lg px-3 py-2 text-sm font-medium transition-colors",
+      isActive(url, href)
+        ? "bg-accent text-accent-foreground"
+        : "text-muted-foreground hover:bg-muted hover:text-foreground",
+    );
+
+  const navItems = NAV.map((item) => (
+    <Link
+      key={item.href}
+      href={item.href}
+      aria-current={isActive(url, item.href) ? "page" : undefined}
+      className={navLink(item.href)}
+    >
+      {item.label}
+    </Link>
+  ));
+
+  return (
+    <div className="relative flex min-h-dvh flex-col">
+      {/* Decorative only: the grid and the glow. Fixed, inert, and behind everything. */}
+      <div aria-hidden="true" className="pointer-events-none fixed inset-0 -z-10 overflow-hidden">
+        <div className="absolute inset-0 bg-grid" />
+        <div className="absolute inset-x-0 top-0 h-136 bg-aurora" />
+      </div>
+
+      <a
+        href="#main"
+        className="sr-only focus:not-sr-only focus:absolute focus:top-3 focus:left-3 focus:z-50 focus:rounded-lg focus:border focus:border-border focus:bg-card focus:px-4 focus:py-2 focus:text-sm focus:font-medium"
+      >
+        Skip to content
+      </a>
+
+      <header className="sticky top-0 z-40 border-b border-border bg-background/75 backdrop-blur-md">
+        <div className={cn(CONTAINER, "flex h-16 items-center justify-between gap-4")}>
+          <Link
+            href="/"
+            className="flex min-w-0 items-center gap-2.5 font-semibold tracking-tight"
+            aria-label={`${APP_NAME} home`}
+          >
+            <img src="/zt.svg" alt="" className="size-8 shrink-0 rounded-lg" />
+            <span className="truncate">{APP_NAME}</span>
+          </Link>
+
+          <nav aria-label="Main" className="hidden items-center gap-1 sm:flex">
+            {navItems}
+          </nav>
+
+          <div className="flex items-center gap-2">
+            <a
+              href={DOCS_URL}
+              target="_blank"
+              rel="noreferrer"
+              className="hidden rounded-lg px-3 py-2 text-sm font-medium text-muted-foreground transition-colors hover:bg-muted hover:text-foreground sm:block"
+            >
+              Docs
+            </a>
+            <ThemeToggle />
+            <button
+              type="button"
+              onClick={() => setMenuOpen((open) => !open)}
+              aria-expanded={menuOpen}
+              aria-controls="mobile-nav"
+              aria-label={menuOpen ? "Close menu" : "Open menu"}
+              className="grid size-9 place-items-center rounded-lg border border-border bg-card text-muted-foreground transition-colors hover:bg-muted hover:text-foreground sm:hidden"
+            >
+              {menuOpen ? <CloseIcon className="size-4.5" /> : <MenuIcon className="size-4.5" />}
+            </button>
+          </div>
+        </div>
+
+        {menuOpen ? (
+          <nav
+            id="mobile-nav"
+            aria-label="Main"
+            className={cn(CONTAINER, "flex flex-col gap-1 border-t border-border py-3 sm:hidden")}
+          >
+            {navItems}
+            <a
+              href={DOCS_URL}
+              target="_blank"
+              rel="noreferrer"
+              className="rounded-lg px-3 py-2 text-sm font-medium text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+            >
+              Docs
+            </a>
+          </nav>
+        ) : null}
+      </header>
+
+      <main id="main" className={cn(CONTAINER, "flex-1 py-14 sm:py-20")}>
+        {children}
+      </main>
+
+      <footer className="border-t border-border">
+        <div
+          className={cn(
+            CONTAINER,
+            "flex flex-col items-center justify-between gap-3 py-8 text-sm text-muted-foreground sm:flex-row",
+          )}
+        >
+          <p>
+            Built with <span className="font-medium text-foreground">Zerotal</span> — the Bun-native
+            TypeScript framework.
+          </p>
+          <a
+            href={DOCS_URL}
+            target="_blank"
+            rel="noreferrer"
+            className="font-medium transition-colors hover:text-foreground"
+          >
+            Documentation
+          </a>
+        </div>
+      </footer>
+
+      <FlashToasts />
+    </div>
+  );
+}

package/templates/react/resources/js/app.tsx

@@ -0,0 +1,29 @@
+import { createInertiaApp, type ResolvedComponent } from "@inertiajs/react";
+import { createRoot } from "react-dom/client";
+import { pages } from "./pages.generated.ts";
+import "../css/app.css";
+
+createInertiaApp({
+  // Suffix every `<Head title="…" />` with the app name, so a page only has to
+  // name itself. Pages that set no title fall back to the app name alone.
+  title: (title) => (title ? `${title} — {{name}}` : "{{name}}"),
+
+  // Map a component name (e.g. "Users/Index") to its lazily-loaded module.
+  // `pages` is generated from the configured pages dir by `inertia:build`.
+  resolve: async (name): Promise<ResolvedComponent> => {
+    const page = pages[name];
+    if (!page) throw new Error(`Inertia page not found: "${name}"`);
+    return (await page()).default as ResolvedComponent;
+  },
+
+  // The top-of-page loading bar shown during slow visits. `--primary` is read off
+  // the document so the bar follows the theme instead of hardcoding a colour.
+  progress: {
+    color: getComputedStyle(document.documentElement).getPropertyValue("--primary").trim(),
+    delay: 200,
+  },
+
+  setup({ el, App, props }) {
+    createRoot(el).render(<App {...props} />);
+  },
+});

package/templates/react/resources/js/env.d.ts

@@ -0,0 +1,13 @@
+// Ambient declarations for non-code assets imported from TypeScript and bundled
+// by `bun zt serve` (see the `assets` block in config/app.ts). These let
+// side-effect imports like `import "../css/app.css"` type-check.
+declare module "*.css";
+declare module "*.scss";
+declare module "*.svg";
+declare module "*.png";
+declare module "*.jpg";
+declare module "*.jpeg";
+declare module "*.gif";
+declare module "*.webp";
+declare module "*.woff";
+declare module "*.woff2";

package/templates/react/resources/js/lib/cn.ts

@@ -0,0 +1,13 @@
+/**
+ * Join class names, dropping anything falsy.
+ *
+ * Deliberately tiny — this is the only thing the components here need from a
+ * class utility, and it keeps the starter free of a runtime dependency. Swap in
+ * `clsx` + `tailwind-merge` if you start composing conflicting utilities.
+ *
+ * @example
+ * cn("px-3 py-2", isActive && "bg-accent", className)
+ */
+export function cn(...parts: Array<string | false | null | undefined>): string {
+  return parts.filter(Boolean).join(" ");
+}