create-react-adam 0.2.2 → 0.4.0

package/template/src/app.css

@@ -1,19 +1,30 @@
 @import "tailwindcss";
 
+@font-face {
+  font-family: "Inter";
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: url("/fonts/InterVariable.woff2") format("woff2");
+}
+
 @theme {
-  --font-sans: "Inter", sans-serif;
+  --font-sans:
+    "Inter", system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
 
-  --color-brand-primary: #3b82f6;
-  --color-brand-primaryHover: #2563eb;
-  --color-brand-primaryActive: #1d4ed8;
+  /* Brand colors are chosen to meet WCAG AA contrast (>= 4.5:1) with white
+     text; keep that in mind when changing them. */
+  --color-brand-primary: #2563eb;
+  --color-brand-primaryHover: #1d4ed8;
+  --color-brand-primaryActive: #1e40af;
 
-  --color-brand-secondary: #8b5cf6;
-  --color-brand-secondaryHover: #7c3aed;
-  --color-brand-secondaryActive: #6d28d9;
+  --color-brand-secondary: #7c3aed;
+  --color-brand-secondaryHover: #6d28d9;
+  --color-brand-secondaryActive: #5b21b6;
 
-  --color-brand-success: #22c55e;
+  --color-brand-success: #15803d;
   --color-brand-warning: #f59e0b;
-  --color-brand-danger: #ef4444;
+  --color-brand-danger: #dc2626;
 
   --color-brand-black: #0f172a;
   --color-brand-white: #ffffff;
@@ -27,3 +38,10 @@
 
   --color-brand-disabled: #94a3b8;
 }
+
+@layer base {
+  :focus-visible {
+    outline: 2px solid var(--color-brand-primary);
+    outline-offset: 2px;
+  }
+}

package/template/src/components/Button.tsx

@@ -0,0 +1,27 @@
+import { ComponentPropsWithoutRef } from "react";
+import { ButtonVariant } from "../types/ui";
+
+interface ButtonProps extends ComponentPropsWithoutRef<"button"> {
+  variant?: ButtonVariant;
+}
+
+const variantClasses: Record<ButtonVariant, string> = {
+  primary: "bg-brand-primary hover:bg-brand-primaryHover",
+  success: "bg-brand-success hover:bg-brand-success/90",
+  danger: "bg-brand-danger hover:bg-brand-danger/90",
+};
+
+const Button = ({ variant = "primary", className, ...props }: ButtonProps) => (
+  <button
+    className={[
+      "text-brand-white rounded-lg px-4 py-2 transition-colors",
+      variantClasses[variant],
+      className,
+    ]
+      .filter(Boolean)
+      .join(" ")}
+    {...props}
+  />
+);
+
+export default Button;

package/template/src/components/PreloadLink.tsx

@@ -0,0 +1,49 @@
+import type { ComponentProps, FocusEvent, MouseEvent, TouchEvent } from "react";
+import { Link } from "wouter";
+import { preloadRoute } from "../routes";
+
+// Drop-in replacement for wouter's <Link> that preloads the target page's
+// chunk as soon as the user shows intent to navigate (hover, keyboard focus,
+// or touch). By the time the click lands, the chunk is usually in flight or
+// already cached, so navigation feels instant. See src/routes.ts for the
+// full preloading picture.
+//
+// HOW TO REMOVE: swap <PreloadLink> back to wouter's <Link> wherever it is
+// used (the props are identical), delete this file, and follow the removal
+// steps in src/routes.ts.
+
+// Mirrors wouter's <Link> props in its plain-anchor form. wouter's asChild
+// variant and `to` alias are not supported here — use wouter's <Link>
+// directly if you need those.
+type PreloadLinkProps = Omit<ComponentProps<"a">, "className" | "href"> & {
+  href: string;
+  className?: string | ((isActive: boolean) => string | undefined);
+  replace?: boolean;
+  state?: unknown;
+};
+
+const PreloadLink = (props: PreloadLinkProps) => {
+  const handleIntent = () => {
+    preloadRoute(props.href);
+  };
+
+  return (
+    <Link
+      {...props}
+      onMouseEnter={(event: MouseEvent<HTMLAnchorElement>) => {
+        handleIntent();
+        props.onMouseEnter?.(event);
+      }}
+      onFocus={(event: FocusEvent<HTMLAnchorElement>) => {
+        handleIntent();
+        props.onFocus?.(event);
+      }}
+      onTouchStart={(event: TouchEvent<HTMLAnchorElement>) => {
+        handleIntent();
+        props.onTouchStart?.(event);
+      }}
+    />
+  );
+};
+
+export default PreloadLink;

package/template/src/pages/About/index.no-utils.tsx

@@ -1,6 +1,11 @@
-import { Link } from "wouter";
+import { useEffect } from "react";
+import PreloadLink from "../../components/PreloadLink";
 
 const About = () => {
+  useEffect(() => {
+    document.title = "About | __PROJECT_NAME__";
+  }, []);
+
   return (
     <div className="bg-brand-background flex min-h-screen flex-col items-center justify-center">
       <div className="mx-auto max-w-2xl px-4 text-center">
@@ -25,12 +30,12 @@ const About = () => {
           </ul>
         </div>
 
-        <Link
+        <PreloadLink
           href="/"
           className="bg-brand-primary text-brand-white hover:bg-brand-primaryHover rounded-lg px-6 py-3 transition-colors"
         >
           Back to Home
-        </Link>
+        </PreloadLink>
       </div>
     </div>
   );

package/template/src/pages/About/index.tsx

@@ -1,4 +1,6 @@
-import { Link } from "wouter";
+import { useEffect } from "react";
+import Button from "../../components/Button";
+import PreloadLink from "../../components/PreloadLink";
 import { useReactPersist } from "../../utils/Storage";
 import { useUrlState } from "../../utils/useUrlState";
 
@@ -6,6 +8,10 @@ const About = () => {
   const [sharedCount, setSharedCount] = useReactPersist("sharedCounter", 0);
   const [urlCount, setUrlCount] = useUrlState("counter", 0);
 
+  useEffect(() => {
+    document.title = "About | __PROJECT_NAME__";
+  }, []);
+
   return (
     <div className="bg-brand-background flex min-h-screen flex-col items-center justify-center">
       <div className="mx-auto max-w-2xl px-4 text-center">
@@ -26,21 +32,23 @@ const About = () => {
               This counter is shared between Home and About pages
             </p>
             <div className="flex items-center justify-center gap-4">
-              <button
+              <Button
+                variant="danger"
+                aria-label="Decrease shared counter"
                 onClick={() => setSharedCount(sharedCount - 1)}
-                className="bg-brand-danger text-brand-white hover:bg-brand-danger/90 rounded-lg px-4 py-2 transition-colors"
               >
                 -
-              </button>
+              </Button>
               <span className="text-brand-black text-3xl font-bold">
                 {sharedCount}
               </span>
-              <button
+              <Button
+                variant="success"
+                aria-label="Increase shared counter"
                 onClick={() => setSharedCount(sharedCount + 1)}
-                className="bg-brand-success text-brand-white hover:bg-brand-success/90 rounded-lg px-4 py-2 transition-colors"
               >
                 +
-              </button>
+              </Button>
             </div>
           </div>
 
@@ -52,21 +60,23 @@ const About = () => {
               This counter syncs with URL parameters
             </p>
             <div className="flex items-center justify-center gap-4">
-              <button
+              <Button
+                variant="danger"
+                aria-label="Decrease URL counter"
                 onClick={() => setUrlCount(urlCount - 1)}
-                className="bg-brand-danger text-brand-white hover:bg-brand-danger/90 rounded-lg px-4 py-2 transition-colors"
               >
                 -
-              </button>
+              </Button>
               <span className="text-brand-black text-3xl font-bold">
                 {urlCount}
               </span>
-              <button
+              <Button
+                variant="success"
+                aria-label="Increase URL counter"
                 onClick={() => setUrlCount(urlCount + 1)}
-                className="bg-brand-success text-brand-white hover:bg-brand-success/90 rounded-lg px-4 py-2 transition-colors"
               >
                 +
-              </button>
+              </Button>
             </div>
           </div>
         </div>
@@ -83,12 +93,12 @@ const About = () => {
             <li>✨ ESLint & Prettier configured</li>
           </ul>
         </div>
-        <Link
+        <PreloadLink
           href="/"
           className="bg-brand-primary text-brand-white hover:bg-brand-primaryHover rounded-lg px-6 py-3 transition-colors"
         >
           Back to Home
-        </Link>
+        </PreloadLink>
       </div>
     </div>
   );

package/template/src/pages/Home/index.no-utils.tsx

@@ -1,6 +1,14 @@
-import { Link } from "wouter";
+import { useEffect, useState } from "react";
+import Button from "../../components/Button";
+import PreloadLink from "../../components/PreloadLink";
 
 const Home = () => {
+  const [count, setCount] = useState(0);
+
+  useEffect(() => {
+    document.title = "__PROJECT_NAME__";
+  }, []);
+
   return (
     <div className="bg-brand-background flex min-h-screen flex-col items-center justify-center">
       <div className="mx-auto max-w-2xl px-4 text-center">
@@ -11,7 +19,7 @@ const Home = () => {
           Built with React, TypeScript, Vite, Wouter, and Tailwind CSS
         </p>
 
-        <div className="mb-8">
+        <div className="mb-8 space-y-6">
           <div className="bg-brand-white rounded-lg p-6 shadow-md">
             <h2 className="text-brand-black mb-4 text-2xl font-semibold">
               Get Started
@@ -27,15 +35,43 @@ const Home = () => {
               This is a clean starting point for your React application.
             </p>
           </div>
+
+          <div className="bg-brand-white rounded-lg p-6 shadow-md">
+            <h2 className="text-brand-black mb-4 text-2xl font-semibold">
+              Counter
+            </h2>
+            <p className="text-brand-gray mb-4">
+              A simple counter using the shared Button component
+            </p>
+            <div className="flex items-center justify-center gap-4">
+              <Button
+                variant="danger"
+                aria-label="Decrease counter"
+                onClick={() => setCount(count - 1)}
+              >
+                -
+              </Button>
+              <span className="text-brand-black text-3xl font-bold">
+                {count}
+              </span>
+              <Button
+                variant="success"
+                aria-label="Increase counter"
+                onClick={() => setCount(count + 1)}
+              >
+                +
+              </Button>
+            </div>
+          </div>
         </div>
 
         <div className="flex justify-center gap-4">
-          <Link
+          <PreloadLink
             href="/about"
             className="bg-brand-primary text-brand-white hover:bg-brand-primaryHover rounded-lg px-6 py-3 transition-colors"
           >
             About Page
-          </Link>
+          </PreloadLink>
           <a
             href="https://react.dev"
             target="_blank"

package/template/src/pages/Home/index.tsx

@@ -1,4 +1,6 @@
-import { Link } from "wouter";
+import { useEffect } from "react";
+import Button from "../../components/Button";
+import PreloadLink from "../../components/PreloadLink";
 import { useReactPersist } from "../../utils/Storage";
 import { useUrlState } from "../../utils/useUrlState";
 
@@ -6,6 +8,10 @@ const Home = () => {
   const [sharedCount, setSharedCount] = useReactPersist("sharedCounter", 0);
   const [urlCount, setUrlCount] = useUrlState("counter", 0);
 
+  useEffect(() => {
+    document.title = "__PROJECT_NAME__";
+  }, []);
+
   return (
     <div className="bg-brand-background flex min-h-screen flex-col items-center justify-center">
       <div className="mx-auto max-w-2xl px-4 text-center">
@@ -25,21 +31,23 @@ const Home = () => {
               This counter is shared between Home and About pages
             </p>
             <div className="flex items-center justify-center gap-4">
-              <button
+              <Button
+                variant="danger"
+                aria-label="Decrease shared counter"
                 onClick={() => setSharedCount(sharedCount - 1)}
-                className="bg-brand-danger text-brand-white hover:bg-brand-danger/90 rounded-lg px-4 py-2 transition-colors"
               >
                 -
-              </button>
+              </Button>
               <span className="text-brand-black text-3xl font-bold">
                 {sharedCount}
               </span>
-              <button
+              <Button
+                variant="success"
+                aria-label="Increase shared counter"
                 onClick={() => setSharedCount(sharedCount + 1)}
-                className="bg-brand-success text-brand-white hover:bg-brand-success/90 rounded-lg px-4 py-2 transition-colors"
               >
                 +
-              </button>
+              </Button>
             </div>
           </div>
 
@@ -51,32 +59,34 @@ const Home = () => {
               This counter syncs with URL parameters
             </p>
             <div className="flex items-center justify-center gap-4">
-              <button
+              <Button
+                variant="danger"
+                aria-label="Decrease URL counter"
                 onClick={() => setUrlCount(urlCount - 1)}
-                className="bg-brand-danger text-brand-white hover:bg-brand-danger/90 rounded-lg px-4 py-2 transition-colors"
               >
                 -
-              </button>
+              </Button>
               <span className="text-brand-black text-3xl font-bold">
                 {urlCount}
               </span>
-              <button
+              <Button
+                variant="success"
+                aria-label="Increase URL counter"
                 onClick={() => setUrlCount(urlCount + 1)}
-                className="bg-brand-success text-brand-white hover:bg-brand-success/90 rounded-lg px-4 py-2 transition-colors"
               >
                 +
-              </button>
+              </Button>
             </div>
           </div>
         </div>
 
         <div className="flex justify-center gap-4">
-          <Link
+          <PreloadLink
             href="/about"
             className="bg-brand-primary text-brand-white hover:bg-brand-primaryHover rounded-lg px-6 py-3 transition-colors"
           >
             About Page
-          </Link>
+          </PreloadLink>
           <a
             href="https://react.dev"
             target="_blank"

package/template/src/pages/NotFound/index.tsx

@@ -1,23 +1,30 @@
-import { Link } from "wouter";
+import { useEffect } from "react";
+import PreloadLink from "../../components/PreloadLink";
 
-const NotFound = () => (
-  <div className="bg-brand-background flex min-h-screen flex-col items-center justify-center">
-    <div className="text-center">
-      <h1 className="text-brand-black text-9xl font-bold">404</h1>
-      <p className="text-brand-black mt-4 text-2xl font-semibold">
-        Page Not Found
-      </p>
-      <p className="text-brand-gray mt-2">
-        The page you're looking for doesn't exist.
-      </p>
-      <Link
-        href="/"
-        className="bg-brand-primary text-brand-white hover:bg-brand-primaryHover mt-6 inline-block rounded-lg px-6 py-3 transition-colors"
-      >
-        Go Home
-      </Link>
+const NotFound = () => {
+  useEffect(() => {
+    document.title = "Page Not Found | __PROJECT_NAME__";
+  }, []);
+
+  return (
+    <div className="bg-brand-background flex min-h-screen flex-col items-center justify-center">
+      <div className="text-center">
+        <h1 className="text-brand-black text-9xl font-bold">404</h1>
+        <p className="text-brand-black mt-4 text-2xl font-semibold">
+          Page Not Found
+        </p>
+        <p className="text-brand-gray mt-2">
+          The page you're looking for doesn't exist.
+        </p>
+        <PreloadLink
+          href="/"
+          className="bg-brand-primary text-brand-white hover:bg-brand-primaryHover mt-6 inline-block rounded-lg px-6 py-3 transition-colors"
+        >
+          Go Home
+        </PreloadLink>
+      </div>
     </div>
-  </div>
-);
+  );
+};
 
 export default NotFound;

package/template/src/routes.ts

@@ -0,0 +1,94 @@
+import type { ComponentType } from "react";
+
+// Route-level code splitting + preloading.
+//
+// This file is the single source of truth for every page's dynamic import.
+// App.tsx feeds these thunks to React.lazy() for routing, and the preload
+// helpers below fire the same thunks ahead of navigation. Because dynamic
+// imports are deduped by module, a preloaded chunk is never downloaded
+// twice — navigating just picks up the in-flight or already-cached module.
+//
+// Preloading happens in two layers:
+//   1. Intent: <PreloadLink> (src/components/PreloadLink.tsx) calls
+//      preloadRoute() on hover/focus/touch. Hover-to-click is typically
+//      200-400ms — enough for a small page chunk to arrive before the click.
+//   2. Idle backstop: preloadAllRoutesWhenIdle() (called once from App.tsx)
+//      fetches every remaining chunk after the window `load` event, one at a
+//      time during idle periods, so it never competes with first-paint
+//      resources (or your Lighthouse score).
+//
+// HOW TO REMOVE PRELOADING:
+//   1. In App.tsx: delete the preloadAllRoutesWhenIdle() effect and the
+//      useDeferredValue lines, and inline the imports back into lazy(),
+//      e.g. const Home = lazy(() => import("./pages/Home"));
+//   2. In src/pages/: replace <PreloadLink> with wouter's <Link>.
+//   3. Delete this file and src/components/PreloadLink.tsx.
+
+type PageLoader = () => Promise<{ default: ComponentType }>;
+
+export const routeImports: Record<string, PageLoader> = {
+  "/": () => import("./pages/Home"),
+  "/about": () => import("./pages/About"),
+  // Not a real link target — keyed by a pseudo-path so the idle prefetcher
+  // warms the 404 page too.
+  "/404": () => import("./pages/NotFound"),
+};
+
+// Fires a route's import ahead of navigation. Safe to call repeatedly and
+// with paths that are not in the map (external links, dynamic segments) —
+// those are a no-op.
+export function preloadRoute(path: string): void {
+  const load = routeImports[path];
+  if (!load) return;
+  load().catch(() => {
+    // Preloading is opportunistic: if it fails (offline, a deploy replaced
+    // the chunk), the real import on navigation will surface the error.
+  });
+}
+
+let hasStartedIdlePreload = false;
+
+// Fetches every route chunk after the page has fully loaded, one chunk at a
+// time during browser idle periods. Skips entirely for users on data-saver
+// or 2G connections.
+export function preloadAllRoutesWhenIdle(): void {
+  // React StrictMode runs effects twice in development — only start once.
+  if (hasStartedIdlePreload) return;
+  hasStartedIdlePreload = true;
+
+  const { connection } = navigator as Navigator & {
+    connection?: { saveData?: boolean; effectiveType?: string };
+  };
+  if (connection?.saveData === true) return;
+  if (connection?.effectiveType?.endsWith("2g") === true) return;
+
+  // Safari has no requestIdleCallback; a timeout is a close-enough stand-in.
+  const scheduleIdle = (callback: () => void): void => {
+    if (typeof window.requestIdleCallback === "function") {
+      window.requestIdleCallback(callback);
+    } else {
+      window.setTimeout(callback, 1500);
+    }
+  };
+
+  const queue = Object.values(routeImports);
+  const loadNext = async (): Promise<void> => {
+    const load = queue.shift();
+    if (!load) return;
+    try {
+      await load();
+    } catch {
+      // Ignore failures here for the same reason as preloadRoute.
+    }
+    scheduleIdle(() => void loadNext());
+  };
+
+  // Waiting for `load` keeps prefetching out of the critical path: every
+  // first-paint resource is done before the first idle callback runs.
+  const start = (): void => scheduleIdle(() => void loadNext());
+  if (document.readyState === "complete") {
+    start();
+  } else {
+    window.addEventListener("load", start, { once: true });
+  }
+}

package/template/src/types/ui.ts

@@ -0,0 +1 @@
+export type ButtonVariant = "primary" | "success" | "danger";

package/template/src/utils/classNames.ts

@@ -1,3 +1,24 @@
-export default function classNames(...classes: string[]) {
-  return classes.filter(Boolean).join(" ");
+type ClassValue = string | false | null | undefined | Record<string, boolean>;
+
+export default function classNames(...classes: ClassValue[]): string {
+  const result: string[] = [];
+
+  for (const entry of classes) {
+    if (!entry) {
+      continue;
+    }
+
+    if (typeof entry === "string") {
+      result.push(entry);
+      continue;
+    }
+
+    for (const [name, isEnabled] of Object.entries(entry)) {
+      if (isEnabled) {
+        result.push(name);
+      }
+    }
+  }
+
+  return result.join(" ");
 }

package/template/src/utils/helpers.ts

@@ -0,0 +1,22 @@
+// Browsers store setTimeout delays as a 32-bit signed integer, so any delay
+// above 2^31 - 1 ms (~24.8 days) overflows and fires immediately.
+const MAX_TIMEOUT_MS = 2_147_483_647;
+
+/**
+ * Drop-in replacement for setTimeout that clamps delays larger than the
+ * maximum 32-bit signed integer (2,147,483,647 ms / ~24.8 days) instead of
+ * letting them overflow and fire immediately.
+ */
+export function safeTimeout<TArgs extends unknown[]>(
+  callback: (...callbackArgs: TArgs) => void,
+  delay: number,
+  ...args: TArgs
+): ReturnType<typeof globalThis.setTimeout> {
+  if (delay > MAX_TIMEOUT_MS) {
+    console.error(
+      `safeTimeout: delay ${delay} exceeds the maximum of ${MAX_TIMEOUT_MS} ms (~24.8 days). Using the maximum value.`,
+    );
+    delay = MAX_TIMEOUT_MS;
+  }
+  return globalThis.setTimeout(callback, delay, ...args);
+}

package/template/src/utils/useUrlState.ts

@@ -4,16 +4,28 @@ import { useLocation, useSearch } from "wouter";
 export function useUrlState(
   key: string,
   defaultValue: number,
-): [number, (value: number) => void] {
+): [number, (value: number) => void];
+export function useUrlState(
+  key: string,
+  defaultValue: string,
+): [string, (value: string) => void];
+export function useUrlState(
+  key: string,
+  defaultValue: string | number,
+): [string, (value: string) => void] | [number, (value: number) => void] {
   const [, setLocation] = useLocation();
   const searchParams = useSearch();
 
   const params = new URLSearchParams(searchParams);
   const urlValue = params.get(key);
-  const value = urlValue ? Number.parseInt(urlValue, 10) : defaultValue;
+  const value = urlValue
+    ? typeof defaultValue === "number"
+      ? Number.parseInt(urlValue, 10)
+      : urlValue
+    : defaultValue;
 
   const setValue = useCallback(
-    (newValue: number) => {
+    (newValue: string | number) => {
       const currentParams = new URLSearchParams(globalThis.location.search);
       currentParams.set(key, newValue.toString());
       setLocation(
@@ -23,5 +35,6 @@ export function useUrlState(
     [key, setLocation],
   );
 
-  return [value, setValue];
+  // The overloads guarantee value/setValue agree with the default's type.
+  return [value, setValue] as [string, (value: string) => void];
 }