create-ej-app 25.0.0 → 27.0.0

package/template/saas-starter/src/components/navigation-sidebar.tsx

@@ -0,0 +1,241 @@
+'use client'
+
+import { ChevronRight } from 'lucide-react'
+import Link from 'next/link'
+import { usePathname } from 'next/navigation'
+import { ComponentType, ReactNode } from 'react'
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger
+} from '~/components/ui/collapsible'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger
+} from '~/components/ui/dropdown-menu'
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarHeader,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarMenuSub,
+  SidebarMenuSubButton,
+  SidebarMenuSubItem,
+  SidebarRail,
+  useSidebar
+} from '~/components/ui/sidebar'
+
+type NavigationSidebarProps = {
+  header: ReactNode
+  groups: SidebarNavGroup[]
+}
+
+export type SidebarNavIcon = ComponentType<{ className?: string }>
+
+export type SidebarNavSubItem = {
+  title: string
+  url: string
+  exact?: boolean
+}
+
+export type SidebarNavItem = {
+  title: string
+  url: string
+  icon?: SidebarNavIcon
+  exact?: boolean
+  items?: SidebarNavSubItem[]
+}
+
+export type SidebarNavGroup = {
+  label: string
+  items: SidebarNavItem[]
+  /** When true, the group is only shown to superadmins. */
+  superadminOnly?: boolean
+}
+
+export function NavigationSidebar({ header, groups }: NavigationSidebarProps) {
+  const pathname = usePathname()
+  const { state, isMobile, setOpenMobile } = useSidebar()
+  const isCollapsed = state === 'collapsed' && !isMobile
+
+  const handleLinkClick = () => {
+    if (isMobile) {
+      setOpenMobile(false)
+    }
+  }
+
+  const allItems = groups.flatMap(g => g.items)
+
+  const isItemActive = (item: { url: string; exact?: boolean }) => {
+    if (item.exact) {
+      return pathname === item.url
+    }
+
+    if (pathname !== item.url && !pathname.startsWith(`${item.url}/`)) {
+      return false
+    }
+
+    // Yield to a more specific sibling that also matches
+    const moreSpecificExists = allItems.some(
+      other =>
+        other.url !== item.url &&
+        other.url.length > item.url.length &&
+        other.url.startsWith(item.url) &&
+        (pathname === other.url || pathname.startsWith(`${other.url}/`))
+    )
+
+    return !moreSpecificExists
+  }
+
+  const isSubItemActive = (
+    item: SidebarNavSubItem,
+    siblings: SidebarNavSubItem[]
+  ) => {
+    if (!isItemActive(item)) {
+      return false
+    }
+
+    return !siblings.some(
+      sibling =>
+        sibling.url !== item.url &&
+        isItemActive(sibling) &&
+        sibling.url.length > item.url.length
+    )
+  }
+
+  const isGroupActive = (item: SidebarNavItem) => {
+    if (isItemActive(item)) {
+      return true
+    }
+
+    return item.items?.some(subItem => isItemActive(subItem)) ?? false
+  }
+
+  return (
+    <Sidebar collapsible="icon" variant="sidebar">
+      <SidebarHeader>{header}</SidebarHeader>
+      <SidebarContent>
+        {groups.map(group => (
+          <SidebarGroup key={group.label}>
+            <SidebarGroupLabel>{group.label}</SidebarGroupLabel>
+            <SidebarGroupContent>
+              <SidebarMenu>
+                {group.items.map(item =>
+                  item.items ? (
+                    isCollapsed ? (
+                      <SidebarMenuItem key={item.title}>
+                        <DropdownMenu>
+                          <DropdownMenuTrigger asChild>
+                            <SidebarMenuButton
+                              tooltip={item.title}
+                              isActive={isGroupActive(item)}
+                            >
+                              {item.icon ? <item.icon /> : null}
+                              <span>{item.title}</span>
+                              <ChevronRight className="ml-auto transition-transform duration-200" />
+                            </SidebarMenuButton>
+                          </DropdownMenuTrigger>
+                          <DropdownMenuContent
+                            side="right"
+                            align="start"
+                            sideOffset={4}
+                          >
+                            <DropdownMenuLabel>{item.title}</DropdownMenuLabel>
+                            <DropdownMenuSeparator />
+                            {item.items.map(subItem => (
+                              <DropdownMenuItem
+                                key={subItem.url}
+                                asChild
+                                className={
+                                  isSubItemActive(subItem, item.items!)
+                                    ? 'bg-accent font-medium'
+                                    : ''
+                                }
+                              >
+                                <Link
+                                  href={subItem.url}
+                                  onClick={handleLinkClick}
+                                >
+                                  {subItem.title}
+                                </Link>
+                              </DropdownMenuItem>
+                            ))}
+                          </DropdownMenuContent>
+                        </DropdownMenu>
+                      </SidebarMenuItem>
+                    ) : (
+                      <Collapsible
+                        key={item.title}
+                        asChild
+                        defaultOpen={isGroupActive(item)}
+                        className="group/collapsible"
+                      >
+                        <SidebarMenuItem>
+                          <CollapsibleTrigger asChild>
+                            <SidebarMenuButton
+                              tooltip={item.title}
+                              isActive={isGroupActive(item)}
+                            >
+                              {item.icon ? <item.icon /> : null}
+                              <span>{item.title}</span>
+                              <ChevronRight className="ml-auto transition-transform duration-200 group-data-[state=open]/collapsible:rotate-90" />
+                            </SidebarMenuButton>
+                          </CollapsibleTrigger>
+                          <CollapsibleContent>
+                            <SidebarMenuSub>
+                              {item.items.map(subItem => (
+                                <SidebarMenuSubItem key={subItem.url}>
+                                  <SidebarMenuSubButton
+                                    asChild
+                                    isActive={isSubItemActive(
+                                      subItem,
+                                      item.items!
+                                    )}
+                                  >
+                                    <Link
+                                      href={subItem.url}
+                                      onClick={handleLinkClick}
+                                    >
+                                      <span>{subItem.title}</span>
+                                    </Link>
+                                  </SidebarMenuSubButton>
+                                </SidebarMenuSubItem>
+                              ))}
+                            </SidebarMenuSub>
+                          </CollapsibleContent>
+                        </SidebarMenuItem>
+                      </Collapsible>
+                    )
+                  ) : (
+                    <SidebarMenuItem key={item.title}>
+                      <SidebarMenuButton
+                        asChild
+                        tooltip={item.title}
+                        isActive={isItemActive(item)}
+                      >
+                        <Link href={item.url} onClick={handleLinkClick}>
+                          {item.icon ? <item.icon /> : null}
+                          <span>{item.title}</span>
+                        </Link>
+                      </SidebarMenuButton>
+                    </SidebarMenuItem>
+                  )
+                )}
+              </SidebarMenu>
+            </SidebarGroupContent>
+          </SidebarGroup>
+        ))}
+      </SidebarContent>
+      <SidebarRail />
+    </Sidebar>
+  )
+}

package/template/saas-starter/src/components/page-heading.tsx

@@ -0,0 +1,38 @@
+/**
+ * Reusable page heading component for admin panel pages.
+ * Renders a consistent icon, title and description layout at the top of each page.
+ * The `icon` prop is optional; when omitted only the text block is rendered.
+ * The `children` prop allows for additional elements (e.g. action buttons) to be placed on the right side of the heading.
+ */
+import { FC, ReactNode } from 'react'
+
+export const PageHeading = ({
+  title,
+  description,
+  icon: Icon,
+  children
+}: {
+  title: string
+  description: string
+  icon?: FC<{ className?: string }>
+  children?: ReactNode
+}) => {
+  return (
+    <div className="flex items-center justify-between gap-3">
+      <div className="flex items-center gap-3">
+        {Icon && (
+          <div className="bg-primary/10 text-primary flex h-10 w-10 shrink-0 items-center justify-center rounded-lg">
+            <Icon className="h-5 w-5" />
+          </div>
+        )}
+        <div>
+          <h1 className="text-2xl font-bold tracking-tight">{title}</h1>
+          <p className="text-muted-foreground">{description}</p>
+        </div>
+      </div>
+      {children ? (
+        <div className="flex items-center gap-2">{children}</div>
+      ) : null}
+    </div>
+  )
+}

package/template/saas-starter/src/components/react-query-provider.tsx

@@ -0,0 +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, 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] = useState(createQueryClient)
+
+  return <QueryClientProvider client={client}>{children}</QueryClientProvider>
+}

package/template/saas-starter/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/saas-starter/src/components/screen-size.tsx

@@ -0,0 +1,76 @@
+/**
+ * @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 })
+
+  useEffect(() => {
+    function updateDimensions() {
+      setDimensions({
+        width: window.innerWidth,
+        height: window.innerHeight
+      })
+    }
+
+    updateDimensions()
+    window.addEventListener('resize', updateDimensions)
+
+    return () => {
+      window.removeEventListener('resize', updateDimensions)
+    }
+  }, [])
+
+  const { width, height } = dimensions
+
+  return (
+    <div className="bg-foreground text-background fixed right-4 bottom-4 flex items-center gap-2 rounded-full p-2 text-xs font-medium">
+      <span>
+        {width.toLocaleString()} x {height.toLocaleString()}
+      </span>
+      <div className="bg-muted-foreground h-4 w-px" />
+      <span className="sm:hidden">XS</span>
+      <span className="hidden sm:inline md:hidden">SM</span>
+      <span className="hidden md:inline lg:hidden">MD</span>
+      <span className="hidden lg:inline xl:hidden">LG</span>
+      <span className="hidden xl:inline 2xl:hidden">XL</span>
+      <span className="hidden 2xl:inline">2XL</span>
+    </div>
+  )
+}

package/template/saas-starter/src/components/site-footer.tsx

@@ -0,0 +1,39 @@
+/**
+ * @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'
+
+/**
+ * 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()} {name}. All rights reserved.
+        </p>
+        <div className="flex gap-4">
+          <Link href="/terms" className="hover:text-foreground">
+            Terms
+          </Link>
+          <Link href="/privacy" className="hover:text-foreground">
+            Privacy
+          </Link>
+        </div>
+      </div>
+    </footer>
+  )
+}

package/template/saas-starter/src/components/support/create-support-ticket-dialog.tsx

@@ -0,0 +1,122 @@
+'use client'
+
+import { useAction } from 'next-safe-action/hooks'
+import { useRouter } from 'next/navigation'
+import { useState } from 'react'
+import { createSupportTicketAction } from '~/app/actions/support-tickets'
+import { Button } from '~/components/ui/button'
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger
+} from '~/components/ui/dialog'
+import { Input } from '~/components/ui/input'
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue
+} from '~/components/ui/select'
+import { Textarea } from '~/components/ui/textarea'
+import { toastActionError, toastSuccessMessage } from '~/lib/toast-message'
+import {
+  supportPriorityOptions,
+  type SupportTicketPriority
+} from './support-ticket-shared'
+
+export function CreateSupportTicketDialog({
+  children,
+  organizationId,
+  redirectBasePath
+}: {
+  children: React.ReactNode
+  /** Omit to raise an account ticket rather than an organization one. */
+  organizationId?: string
+  redirectBasePath: string
+}) {
+  const router = useRouter()
+  const [open, setOpen] = useState(false)
+  const [subject, setSubject] = useState('')
+  const [priority, setPriority] = useState<SupportTicketPriority>('medium')
+  const [message, setMessage] = useState('')
+
+  const { execute, isExecuting } = useAction(createSupportTicketAction, {
+    onSuccess: ({ data }) => {
+      toastSuccessMessage('Support ticket created')
+      setOpen(false)
+      setSubject('')
+      setMessage('')
+      if (data?.id) {
+        router.push(`${redirectBasePath}/${data.id}`)
+      } else {
+        router.refresh()
+      }
+    },
+    onError: ({ error }) => {
+      toastActionError(error, 'The support ticket was not created. Try again.')
+    }
+  })
+
+  const handleSubmit = () => {
+    execute({
+      organizationId: organizationId ?? null,
+      subject,
+      priority,
+      message
+    })
+  }
+
+  return (
+    <Dialog open={open} onOpenChange={setOpen}>
+      <DialogTrigger asChild>{children}</DialogTrigger>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>New Support Ticket</DialogTitle>
+          <DialogDescription>
+            Describe the problem, including what you expected and what happened.
+          </DialogDescription>
+        </DialogHeader>
+
+        <div className="space-y-4">
+          <Input
+            value={subject}
+            onChange={event => setSubject(event.target.value)}
+            placeholder="Subject"
+          />
+          <Select
+            value={priority}
+            onValueChange={value => setPriority(value as SupportTicketPriority)}
+          >
+            <SelectTrigger className="w-full">
+              <SelectValue placeholder="Priority" />
+            </SelectTrigger>
+            <SelectContent>
+              {supportPriorityOptions.map(option => (
+                <SelectItem key={option.value} value={option.value}>
+                  {option.label}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+          <Textarea
+            value={message}
+            onChange={event => setMessage(event.target.value)}
+            placeholder="What can we help with?"
+            className="min-h-32"
+          />
+        </div>
+
+        <DialogFooter>
+          <Button onClick={handleSubmit} disabled={isExecuting}>
+            Create ticket
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}