create-ej-app 26.0.0 → 27.0.0

package/template/nextjs/src/components/react-query-provider.tsx

@@ -1,12 +1,51 @@
+/**
+ * @fileoverview React Query Provider Component
+ *
+ * Wraps the application with TanStack Query's QueryClientProvider.
+ * Enables data fetching, caching, and server state management.
+ *
+ * **Features Enabled:**
+ * - Automatic background refetching
+ * - Request deduplication
+ * - Cache management
+ * - Optimistic updates
+ * - useSafeActionQuery/useSafeActionMutation hooks
+ *
+ * @module components/react-query-provider
+ * @see https://tanstack.com/query/latest
+ */
+
 'use client'
 
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
-import { FC, ReactNode } from 'react'
+import { FC, ReactNode, useState } from 'react'
+
+/** Default: treat list/admin data as fresh for 30s so focus does not re-hit every action. */
+const DEFAULT_STALE_TIME_MS = 30_000
+
+function createQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: DEFAULT_STALE_TIME_MS
+      }
+    }
+  })
+}
 
+/**
+ * React Query Provider Component
+ *
+ * Creates one QueryClient for the provider lifetime and wraps children.
+ * Place near the root of the client tree.
+ *
+ * Global `staleTime` is 30s. Live surfaces should pass `staleTime: 0`;
+ * heavy dashboards and static options can pass a longer value.
+ */
 export const ReactQueryProvider: FC<{
   children?: ReactNode
 }> = ({ children }) => {
-  const client = new QueryClient({})
+  const [client] = useState(createQueryClient)
 
   return <QueryClientProvider client={client}>{children}</QueryClientProvider>
 }

package/template/nextjs/src/components/route-error.tsx

@@ -0,0 +1,55 @@
+'use client'
+
+import { AlertTriangle } from 'lucide-react'
+import Link from 'next/link'
+import { Button } from '~/components/ui/button'
+
+/**
+ * Shared UI for App Router error boundaries (`error.tsx`, `global-error.tsx`).
+ * Keeps recovery actions and support reference copy consistent.
+ */
+export function RouteError({
+  error,
+  onRetry,
+  homeHref = '/',
+  homeLabel = 'Go Home'
+}: {
+  error: Error & { digest?: string }
+  onRetry: () => void
+  homeHref?: string
+  homeLabel?: string
+}) {
+  return (
+    <main className="bg-background text-foreground flex min-h-screen flex-col">
+      <section className="flex min-h-[60vh] flex-col items-center justify-center px-4 py-16">
+        <div className="max-w-md text-center">
+          <AlertTriangle
+            className="text-muted-foreground/50 mx-auto size-16"
+            aria-hidden
+          />
+          <h1 className="mt-4 text-2xl font-semibold tracking-tight">
+            This Page Failed to Load
+          </h1>
+          <p className="text-muted-foreground mt-3 text-base">
+            Refresh the page or go home and try again. If it keeps happening,
+            contact support
+            {error.digest ? ' with the reference below' : ''}.
+          </p>
+          {error.digest ? (
+            <p className="text-muted-foreground mt-4 font-mono text-xs break-all">
+              Reference: {error.digest}
+            </p>
+          ) : null}
+          <div className="mt-8 flex flex-wrap items-center justify-center gap-3">
+            <Button type="button" onClick={onRetry}>
+              Try Again
+            </Button>
+            <Button type="button" variant="outline" asChild>
+              <Link href={homeHref}>{homeLabel}</Link>
+            </Button>
+          </div>
+        </div>
+      </section>
+    </main>
+  )
+}

package/template/nextjs/src/components/screen-size.tsx

@@ -1,7 +1,43 @@
+/**
+ * @fileoverview Screen Size Indicator (Development Tool)
+ *
+ * Displays current viewport dimensions and Tailwind breakpoint.
+ * Useful during development for responsive design debugging.
+ *
+ * **Displayed Info:**
+ * - Viewport width x height in pixels
+ * - Current Tailwind breakpoint (XS, SM, MD, LG, XL, 2XL)
+ *
+ * **Positioning:**
+ * - Fixed to bottom-right corner
+ * - Always visible overlay
+ *
+ * Render this component conditionally.
+ * only in development environment.
+ *
+ * @module components/screen-size
+ */
+
 'use client'
 
 import { FC, useEffect, useState } from 'react'
 
+/**
+ * Screen Size Indicator Component
+ *
+ * Fixed position badge showing viewport dimensions and breakpoint.
+ * Updates on window resize.
+ *
+ * **Breakpoint Display:**
+ * - XS: < 640px (default, no sm: prefix)
+ * - SM: 640px - 767px
+ * - MD: 768px - 1023px
+ * - LG: 1024px - 1279px
+ * - XL: 1280px - 1535px
+ * - 2XL: ≥ 1536px
+ *
+ * @returns {JSX.Element} Fixed position size indicator
+ */
 export const ScreenSize: FC = () => {
   const [dimensions, setDimensions] = useState({ width: 0, height: 0 })
 

package/template/nextjs/src/components/site-footer.tsx

@@ -1,13 +1,29 @@
+/**
+ * @fileoverview Site Footer Component
+ *
+ * Global footer displayed on all pages.
+ * Contains copyright notice and links to legal pages.
+ *
+ * @module components/site-footer
+ */
+
 import Link from 'next/link'
-import { siteConfig } from '~/lib/siteConfig'
 
-export const SiteFooter = () => {
+/**
+ * Site Footer Component
+ *
+ * Displays copyright and legal navigation links.
+ *
+ * @param {Object} props - Component props
+ * @param {string} props.name - Company name for copyright
+ * @returns {JSX.Element} Footer element with copyright and links
+ */
+export const SiteFooter = ({ name }: { name: string }) => {
   return (
     <footer className="border-t">
       <div className="text-muted-foreground container flex flex-col items-center justify-between gap-4 py-6 text-sm sm:flex-row">
         <p>
-          &copy; {new Date().getUTCFullYear()} {siteConfig.name}. All rights
-          reserved.
+          &copy; {new Date().getUTCFullYear()} {name}. All rights reserved.
         </p>
         <div className="flex gap-4">
           <Link href="/terms" className="hover:text-foreground">

package/template/nextjs/src/components/theme-provider.tsx

@@ -1,8 +1,30 @@
+/**
+ * @fileoverview Theme provider for light/dark mode and theme hotkeys.
+ *
+ * Wraps the application with Next Themes provider and manages theme switching.
+ * Includes a hotkey component (D key) to toggle the theme.
+ *
+ * **Features:**
+ * - System-aware default theme preference
+ * - Light/dark/system theme options
+ * - Keyboard shortcut (D key) for theme toggle
+ * - No theme transitions on page load
+ *
+ * @module components/theme-provider
+ */
+
 'use client'
 
 import { ThemeProvider as NextThemesProvider, useTheme } from 'next-themes'
 import { FC, useEffect } from 'react'
 
+/**
+ * Determines if the target element is a text input field.
+ * Used to avoid triggering theme hotkey when typing in inputs.
+ *
+ * @param target - DOM event target to check
+ * @returns true if target is a contenteditable, input, textarea, or select element
+ */
 function isTypingTarget(target: EventTarget | null) {
   if (!(target instanceof HTMLElement)) {
     return false
@@ -16,10 +38,27 @@ function isTypingTarget(target: EventTarget | null) {
   )
 }
 
+/**
+ * Theme Hotkey Component
+ *
+ * Listens for the 'D' key and toggles between light and dark themes.
+ * Ignores hotkey when user is typing in an input field.
+ *
+ * **Behavior:**
+ * - Press 'D' anywhere to toggle light ↔ dark
+ * - No effect if typing in input, textarea, or contenteditable element
+ * - Requires modifier keys (Ctrl, Cmd, Alt) to NOT be pressed
+ *
+ * @returns {null} Does not render any elements
+ */
 function ThemeHotkey() {
   const { resolvedTheme, setTheme } = useTheme()
 
   useEffect(() => {
+    /**
+     * Handles keyboard down events for theme toggle.
+     * Checks conditions and prevents default if hotkey is triggered.
+     */
     function onKeyDown(event: KeyboardEvent) {
       if (event.defaultPrevented || event.repeat) {
         return
@@ -50,6 +89,15 @@ function ThemeHotkey() {
   return null
 }
 
+/**
+ * Theme Provider Component
+ *
+ * Wraps application with Next Themes provider and mounts theme hotkey.
+ *
+ * @param {Object} props - Component props
+ * @param {React.ReactNode} props.children - Child components to wrap
+ * @returns {JSX.Element} Provider wrapping children with theme support
+ */
 export const ThemeProvider: FC<{
   children: React.ReactNode
 }> = ({ children }) => {

package/template/nextjs/src/components/theme-toggle.tsx

@@ -1,22 +1,75 @@
+/**
+ * @fileoverview Theme Toggle Button Component
+ *
+ * Cycles through light, dark, and system themes.
+ * Uses next-themes for theme state management.
+ *
+ * **Theme Cycle:**
+ * light → dark → system → light…
+ *
+ * **Icons:**
+ * - Sun: Light mode
+ * - Moon: Dark mode
+ * - Monitor: System preference
+ *
+ * **Hydration:**
+ * - Waits for client mount before rendering icons
+ * - Prevents hydration mismatch
+ *
+ * @module components/theme-toggle
+ */
+
 'use client'
 
-import { Moon, Sun } from 'lucide-react'
+import { Monitor, Moon, Sun } from 'lucide-react'
 import { useTheme } from 'next-themes'
-import { FC } from 'react'
+import { FC, useSyncExternalStore } from 'react'
 import { Button } from './ui/button'
 
+const emptySubscribe = () => () => {}
+
+/**
+ * Theme Toggle Button
+ *
+ * Ghost button that cycles through available themes.
+ * Shows appropriate icon for current theme state.
+ *
+ * **Behavior:**
+ * - Click cycles: light → dark → system → light
+ * - Shows nothing until mounted (prevents hydration issues)
+ *
+ * @returns {JSX.Element} Icon button for theme switching
+ */
 export const ThemeToggle: FC = () => {
   const { theme, setTheme } = useTheme()
+  // Client-only: server snapshot is false so SSR and the first client paint match.
+  const mounted = useSyncExternalStore(
+    emptySubscribe,
+    () => true,
+    () => false
+  )
+
+  const cycleTheme = () => {
+    const themes = ['light', 'dark', 'system']
+    const currentIndex = themes.indexOf(theme || 'system')
+    const nextIndex = (currentIndex + 1) % themes.length
+    setTheme(themes[nextIndex]!)
+  }
 
   return (
     <Button
       variant="ghost"
       size="icon"
+      onClick={cycleTheme}
       aria-label="Toggle theme"
-      onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}
     >
-      <Sun className="hidden h-5 w-5 dark:inline" />
-      <Moon className="inline h-5 w-5 dark:hidden" />
+      {!mounted ? null : (
+        <>
+          {theme === 'light' && <Sun className="size-4" />}
+          {theme === 'dark' && <Moon className="size-4" />}
+          {theme === 'system' && <Monitor className="size-4" />}
+        </>
+      )}
     </Button>
   )
 }

package/template/nextjs/src/components/ui/alert-dialog.tsx

@@ -0,0 +1,199 @@
+'use client'
+
+import { AlertDialog as AlertDialogPrimitive } from 'radix-ui'
+import * as React from 'react'
+
+import { Button } from '~/components/ui/button'
+import { cn } from '~/lib/cn'
+
+function AlertDialog({
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Root>) {
+  return <AlertDialogPrimitive.Root data-slot="alert-dialog" {...props} />
+}
+
+function AlertDialogTrigger({
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Trigger>) {
+  return (
+    <AlertDialogPrimitive.Trigger data-slot="alert-dialog-trigger" {...props} />
+  )
+}
+
+function AlertDialogPortal({
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Portal>) {
+  return (
+    <AlertDialogPrimitive.Portal data-slot="alert-dialog-portal" {...props} />
+  )
+}
+
+function AlertDialogOverlay({
+  className,
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Overlay>) {
+  return (
+    <AlertDialogPrimitive.Overlay
+      data-slot="alert-dialog-overlay"
+      className={cn(
+        'data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0 fixed inset-0 z-50 bg-black/10 duration-100 supports-backdrop-filter:backdrop-blur-xs',
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AlertDialogContent({
+  className,
+  size = 'default',
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Content> & {
+  size?: 'default' | 'sm'
+}) {
+  return (
+    <AlertDialogPortal>
+      <AlertDialogOverlay />
+      <AlertDialogPrimitive.Content
+        data-slot="alert-dialog-content"
+        data-size={size}
+        className={cn(
+          'group/alert-dialog-content bg-popover text-popover-foreground ring-foreground/10 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95 fixed top-1/2 left-1/2 z-50 grid w-full -translate-x-1/2 -translate-y-1/2 gap-6 rounded-xl p-6 ring-1 duration-100 outline-none data-[size=default]:max-w-xs data-[size=sm]:max-w-xs data-[size=default]:sm:max-w-lg',
+          className
+        )}
+        {...props}
+      />
+    </AlertDialogPortal>
+  )
+}
+
+function AlertDialogHeader({
+  className,
+  ...props
+}: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="alert-dialog-header"
+      className={cn(
+        'grid grid-rows-[auto_1fr] place-items-center gap-1.5 text-center has-data-[slot=alert-dialog-media]:grid-rows-[auto_auto_1fr] has-data-[slot=alert-dialog-media]:gap-x-6 sm:group-data-[size=default]/alert-dialog-content:place-items-start sm:group-data-[size=default]/alert-dialog-content:text-left sm:group-data-[size=default]/alert-dialog-content:has-data-[slot=alert-dialog-media]:grid-rows-[auto_1fr]',
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AlertDialogFooter({
+  className,
+  ...props
+}: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="alert-dialog-footer"
+      className={cn(
+        'flex flex-col-reverse gap-2 group-data-[size=sm]/alert-dialog-content:grid group-data-[size=sm]/alert-dialog-content:grid-cols-2 sm:flex-row sm:justify-end',
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AlertDialogMedia({
+  className,
+  ...props
+}: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="alert-dialog-media"
+      className={cn(
+        "bg-muted mb-2 inline-flex size-16 items-center justify-center rounded-md sm:group-data-[size=default]/alert-dialog-content:row-span-2 *:[svg:not([class*='size-'])]:size-8",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AlertDialogTitle({
+  className,
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Title>) {
+  return (
+    <AlertDialogPrimitive.Title
+      data-slot="alert-dialog-title"
+      className={cn(
+        'font-heading text-lg font-medium sm:group-data-[size=default]/alert-dialog-content:group-has-data-[slot=alert-dialog-media]/alert-dialog-content:col-start-2',
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AlertDialogDescription({
+  className,
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Description>) {
+  return (
+    <AlertDialogPrimitive.Description
+      data-slot="alert-dialog-description"
+      className={cn(
+        'text-muted-foreground *:[a]:hover:text-foreground text-sm text-balance md:text-pretty *:[a]:underline *:[a]:underline-offset-3',
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AlertDialogAction({
+  className,
+  variant = 'default',
+  size = 'default',
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Action> &
+  Pick<React.ComponentProps<typeof Button>, 'variant' | 'size'>) {
+  return (
+    <Button variant={variant} size={size} asChild>
+      <AlertDialogPrimitive.Action
+        data-slot="alert-dialog-action"
+        className={cn(className)}
+        {...props}
+      />
+    </Button>
+  )
+}
+
+function AlertDialogCancel({
+  className,
+  variant = 'outline',
+  size = 'default',
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Cancel> &
+  Pick<React.ComponentProps<typeof Button>, 'variant' | 'size'>) {
+  return (
+    <Button variant={variant} size={size} asChild>
+      <AlertDialogPrimitive.Cancel
+        data-slot="alert-dialog-cancel"
+        className={cn(className)}
+        {...props}
+      />
+    </Button>
+  )
+}
+
+export {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogMedia,
+  AlertDialogOverlay,
+  AlertDialogPortal,
+  AlertDialogTitle,
+  AlertDialogTrigger
+}

package/template/nextjs/src/components/ui/avatar.tsx

@@ -0,0 +1,112 @@
+'use client'
+
+import { Avatar as AvatarPrimitive } from 'radix-ui'
+import * as React from 'react'
+
+import { cn } from '~/lib/cn'
+
+function Avatar({
+  className,
+  size = 'default',
+  ...props
+}: React.ComponentProps<typeof AvatarPrimitive.Root> & {
+  size?: 'default' | 'sm' | 'lg'
+}) {
+  return (
+    <AvatarPrimitive.Root
+      data-slot="avatar"
+      data-size={size}
+      className={cn(
+        'group/avatar after:border-border relative flex size-8 shrink-0 rounded-full select-none after:absolute after:inset-0 after:rounded-full after:border after:mix-blend-darken data-[size=lg]:size-10 data-[size=sm]:size-6 dark:after:mix-blend-lighten',
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AvatarImage({
+  className,
+  ...props
+}: React.ComponentProps<typeof AvatarPrimitive.Image>) {
+  return (
+    <AvatarPrimitive.Image
+      data-slot="avatar-image"
+      className={cn(
+        'aspect-square size-full rounded-full object-cover',
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AvatarFallback({
+  className,
+  ...props
+}: React.ComponentProps<typeof AvatarPrimitive.Fallback>) {
+  return (
+    <AvatarPrimitive.Fallback
+      data-slot="avatar-fallback"
+      className={cn(
+        'bg-muted text-muted-foreground flex size-full items-center justify-center rounded-full text-sm group-data-[size=sm]/avatar:text-xs',
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AvatarBadge({ className, ...props }: React.ComponentProps<'span'>) {
+  return (
+    <span
+      data-slot="avatar-badge"
+      className={cn(
+        'bg-primary text-primary-foreground ring-background absolute right-0 bottom-0 z-10 inline-flex items-center justify-center rounded-full bg-blend-color ring-2 select-none',
+        'group-data-[size=sm]/avatar:size-2 group-data-[size=sm]/avatar:[&>svg]:hidden',
+        'group-data-[size=default]/avatar:size-2.5 group-data-[size=default]/avatar:[&>svg]:size-2',
+        'group-data-[size=lg]/avatar:size-3 group-data-[size=lg]/avatar:[&>svg]:size-2',
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AvatarGroup({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="avatar-group"
+      className={cn(
+        'group/avatar-group *:data-[slot=avatar]:ring-background flex -space-x-2 *:data-[slot=avatar]:ring-2',
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AvatarGroupCount({
+  className,
+  ...props
+}: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="avatar-group-count"
+      className={cn(
+        'bg-muted text-muted-foreground ring-background relative flex size-8 shrink-0 items-center justify-center rounded-full text-sm ring-2 group-has-data-[size=lg]/avatar-group:size-10 group-has-data-[size=sm]/avatar-group:size-6 [&>svg]:size-4 group-has-data-[size=lg]/avatar-group:[&>svg]:size-5 group-has-data-[size=sm]/avatar-group:[&>svg]:size-3',
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  Avatar,
+  AvatarBadge,
+  AvatarFallback,
+  AvatarGroup,
+  AvatarGroupCount,
+  AvatarImage
+}