create-ej-app 25.0.0 → 27.0.0

package/template/nextjs/src/components/data-table/types.ts

@@ -0,0 +1,76 @@
+import type { RowData, SortingState } from '@tanstack/react-table'
+import { SortOrderEnum } from './enum'
+import type { DataTableColumnDef } from './features'
+
+/** A single selectable option inside a filter dropdown. */
+interface DataTableFilterOption {
+  label: string
+  value: string | boolean
+  /** Optional icon rendered next to the option label. */
+  icon?: React.ComponentType<{ className?: string }>
+}
+
+/**
+ * Describes a filter that appears in the DataTable toolbar.
+ * Filters can either be static (pre-defined `options`) or async
+ * (fetched via a server `action` on search).
+ */
+export interface DataTableFilter {
+  /** Unique key used to store the filter's selected values. */
+  id: string
+  /** Human-readable label shown in the filter dropdown trigger. */
+  label: string
+  /** Pre-defined options for static filters. Omit for async filters. */
+  options?: DataTableFilterOption[]
+  /** Server action called to fetch options dynamically (async filters). */
+  action?: any
+  /** Custom React-Query key for async filter caching. Defaults to `id`. */
+  queryKey?: string
+}
+
+/**
+ * Props accepted by the generic `DataTable` component.
+ *
+ * Supports both client-side and server-side (manual) pagination & sorting.
+ * When `manualPagination` / `manualSorting` are enabled the parent is
+ * responsible for fetching data and passing results back via `data` & `totalCount`.
+ */
+export interface DataTableProps<TData extends RowData> {
+  /** Column definitions (TanStack Table v9, typed to DataTable features). */
+  columns: DataTableColumnDef<TData, any>[]
+  /** Row data to display. */
+  data?: TData[]
+  /** Show skeleton loading rows while data is being fetched. */
+  isLoading?: boolean
+  /** Render the search input in the toolbar. */
+  enableSearch?: boolean
+  /** Placeholder text for the search input. */
+  searchPlaceholder?: string
+  /** Initial value for the search input (e.g. restored from URL query params). */
+  initialSearch?: string
+  /** Total row count for server-side pagination info. */
+  totalCount?: number
+  /** Callback fired when pagination, sorting, search or filters change. */
+  onParamsChange?: (params: {
+    page: number
+    limit: number
+    sortBy?: string
+    sortOrder?: SortOrderEnum
+    search?: string
+    filters?: Record<string, (string | boolean)[]>
+  }) => void
+  /** Enable server-side pagination (parent controls data fetching). */
+  manualPagination?: boolean
+  /** Enable server-side sorting (parent controls data fetching). */
+  manualSorting?: boolean
+  /** Current 0-based page index (controlled). */
+  pageIndex?: number
+  /** Number of rows per page (controlled). */
+  pageSize?: number
+  /** Default sorting state applied on mount. */
+  initialSorting?: SortingState
+  /** Filter definitions rendered in the toolbar filter dropdown. */
+  filters?: DataTableFilter[]
+  /** Currently active filter selections keyed by filter id. */
+  activeFilters?: Record<string, (string | boolean)[]>
+}

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

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview Reusable Error Display Component
+ *
+ * Generic error/empty state component for displaying user-friendly
+ * error messages with optional icon and action button.
+ *
+ * **Use Cases:**
+ * - Empty search results
+ * - Data fetch failures
+ * - Access denied states
+ * - 404-like content not found
+ *
+ * @module components/error
+ */
+
+import { type LucideIcon, AlertTriangle } from 'lucide-react'
+import Link from 'next/link'
+import { FC } from 'react'
+import { Button } from '~/components/ui/button'
+
+/**
+ * Error Display Component
+ *
+ * Renders a centered error state with icon, message, and action.
+ *
+ * **Layout:**
+ * - Large icon (customizable)
+ * - Bold title
+ * - Descriptive message
+ * - Action button (customizable link)
+ *
+ * @param {Object} props - Component props
+ * @param {string} props.title - Error heading text
+ * @param {string} props.message - Descriptive error message
+ * @param {LucideIcon} [props.icon] - Custom icon (defaults to AlertTriangle)
+ * @param {Object} [props.link] - Optional action button configuration
+ * @param {string} [props.link.href] - Button link destination (defaults to '/')
+ * @param {string} [props.link.text] - Button text (defaults to 'Browse Products')
+ * @returns {JSX.Element} Centered error display
+ *
+ * @example
+ * ```tsx
+ * <ErrorDisplay
+ *   title="No Results Found"
+ *   message="Try adjusting your search or filters"
+ *   icon={Search}
+ *   link={{ href: '/search', text: 'Clear Filters' }}
+ * />
+ * ```
+ */
+export const ErrorDisplay: FC<{
+  title: string
+  message: string
+  icon?: LucideIcon
+  link?: {
+    href?: string
+    text?: string
+  }
+}> = ({ title, message, icon, link }) => {
+  const Icon = icon || AlertTriangle
+  return (
+    <div className="flex w-full flex-col items-center justify-center py-16">
+      <Icon className="text-muted-foreground/50 size-16" />
+      <h2 className="mt-4 text-xl font-semibold">{title}</h2>
+      <p className="text-muted-foreground mt-2">{message}</p>
+      <Button className="mt-4" asChild>
+        <Link href={link?.href || '/'}>{link?.text || 'Go Home'}</Link>
+      </Button>
+    </div>
+  )
+}

package/template/nextjs/src/components/loader.tsx

@@ -1,13 +1,29 @@
+/**
+ * @fileoverview Page Transition Loader Component
+ *
+ * Top progress bar shown during navigation, using the theme primary color.
+ *
+ * @module components/loader
+ */
+
 'use client'
 
 import NextTopLoader from 'nextjs-toploader'
 
 import { FC } from 'react'
 
+/**
+ * Page Loader Component
+ *
+ * Renders the NextTopLoader with preset configuration.
+ * Should be included once near the root layout.
+ *
+ * @returns {JSX.Element} Top loading bar component
+ */
 export const Loader: FC = () => {
   return (
     <NextTopLoader
-      color="#777777"
+      color="var(--primary)"
       initialPosition={0.08}
       crawlSpeed={200}
       height={3}
@@ -15,7 +31,7 @@ export const Loader: FC = () => {
       showSpinner={true}
       easing="ease"
       speed={200}
-      shadow={`0 0 10px '#777777',0 0 5px '#777777'`}
+      shadow="0 0 10px var(--primary), 0 0 5px var(--primary)"
       template='<div class="bar" role="bar"><div class="peg"></div></div> 
   <div class="spinner" role="spinner"><div class="spinner-icon"></div></div>'
       zIndex={10000}

package/template/nextjs/src/components/logo.tsx

@@ -0,0 +1,49 @@
+import Image from 'next/image'
+import { cn } from '~/lib/cn'
+import { siteConfig } from '~/lib/siteConfig'
+
+/**
+ * Brand mark, with the wordmark beside it unless `showName` is false.
+ *
+ * Two SVG files rather than one: the mark uses two colors, so `currentColor`
+ * cannot recolor it for both themes.
+ */
+export function Logo({
+  className,
+  size = 36,
+  showName = true,
+  priority = false
+}: {
+  className?: string
+  size?: number
+  showName?: boolean
+  priority?: boolean
+}) {
+  const dimensions = { width: size, height: size }
+
+  return (
+    <span className={cn('flex items-center gap-2.5', className)}>
+      <Image
+        src={siteConfig.logo}
+        alt=""
+        aria-hidden
+        {...dimensions}
+        style={dimensions}
+        className="shrink-0 dark:hidden"
+        priority={priority}
+      />
+      <Image
+        src={siteConfig.logoDark}
+        alt=""
+        aria-hidden
+        {...dimensions}
+        style={dimensions}
+        className="hidden shrink-0 dark:block"
+        priority={priority}
+      />
+      <span className={cn('font-bold tracking-tight', !showName && 'sr-only')}>
+        {siteConfig.name}
+      </span>
+    </span>
+  )
+}

package/template/nextjs/src/components/navigation-search.tsx

@@ -0,0 +1,140 @@
+'use client'
+
+import { Search } from 'lucide-react'
+import { useRouter } from 'next/navigation'
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import {
+  SidebarNavGroup,
+  SidebarNavItem,
+  SidebarNavSubItem
+} from '~/components/navigation-sidebar'
+import { Button } from '~/components/ui/button'
+import {
+  Command,
+  CommandDialog,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+  CommandSeparator
+} from '~/components/ui/command'
+
+type NavigationSearchProps = {
+  groups: SidebarNavGroup[]
+  dialogDescription: string
+  emptyMessage?: string
+  buttonLabel?: string
+  buttonClassName?: string
+}
+
+export function NavigationSearch({
+  groups,
+  dialogDescription,
+  emptyMessage = 'No results found.',
+  buttonLabel = 'Search…',
+  buttonClassName = 'text-muted-foreground relative h-9 w-36 justify-start rounded-md text-sm sm:w-64 sm:pr-12'
+}: NavigationSearchProps) {
+  const router = useRouter()
+  const [searchOpen, setSearchOpen] = useState(false)
+
+  useEffect(() => {
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'k' && (event.metaKey || event.ctrlKey)) {
+        event.preventDefault()
+        setSearchOpen(true)
+      }
+    }
+
+    document.addEventListener('keydown', onKeyDown)
+    return () => document.removeEventListener('keydown', onKeyDown)
+  }, [])
+
+  const navigate = useCallback(
+    (url: string) => {
+      setSearchOpen(false)
+      router.push(url)
+    },
+    [router]
+  )
+
+  const hasGroups = groups.length > 0
+
+  const normalizedGroups = useMemo(
+    () =>
+      groups.map(group => ({
+        label: group.label,
+        items: group.items.flatMap((item: SidebarNavItem) => {
+          if (item.items?.length) {
+            return item.items.map((subItem: SidebarNavSubItem) => ({
+              key: subItem.url,
+              label: `${item.title} › ${subItem.title}`,
+              value: `${group.label} ${item.title} ${subItem.title}`,
+              url: subItem.url,
+              icon: item.icon
+            }))
+          }
+
+          return [
+            {
+              key: item.url,
+              label: item.title,
+              value: `${group.label} ${item.title}`,
+              url: item.url,
+              icon: item.icon
+            }
+          ]
+        })
+      })),
+    [groups]
+  )
+
+  return (
+    <>
+      <Button
+        variant="outline"
+        className={buttonClassName}
+        onClick={() => setSearchOpen(true)}
+        disabled={!hasGroups}
+      >
+        <Search className="mr-2 size-4" />
+        <span>{buttonLabel}</span>
+        <kbd className="bg-muted pointer-events-none absolute top-[50%] right-1.5 hidden h-5 -translate-y-1/2 items-center gap-1 rounded border px-1.5 font-mono text-[10px] font-medium opacity-100 sm:flex">
+          <span className="text-xs">⌘</span>K
+        </kbd>
+      </Button>
+
+      <CommandDialog
+        open={searchOpen}
+        onOpenChange={setSearchOpen}
+        title="Search"
+        description={dialogDescription}
+      >
+        <Command>
+          <CommandInput placeholder="Type to search…" />
+          <CommandList>
+            <CommandEmpty>{emptyMessage}</CommandEmpty>
+
+            {normalizedGroups.map((group, groupIndex) => (
+              <div key={group.label}>
+                {groupIndex > 0 ? <CommandSeparator /> : null}
+                <CommandGroup heading={group.label}>
+                  {group.items.map(item => (
+                    <CommandItem
+                      key={item.key}
+                      value={item.value}
+                      onSelect={() => navigate(item.url)}
+                    >
+                      {item.icon ? <item.icon className="mr-2 size-4" /> : null}
+                      <span>{item.label}</span>
+                    </CommandItem>
+                  ))}
+                </CommandGroup>
+              </div>
+            ))}
+          </CommandList>
+        </Command>
+      </CommandDialog>
+    </>
+  )
+}

package/template/nextjs/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/nextjs/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>
+  )
+}