create-ej-app 25.0.0 → 27.0.0

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

@@ -0,0 +1,254 @@
+'use client'
+
+import { File, FileText, Loader2, Music, Upload, Video, X } from 'lucide-react'
+import Image from 'next/image'
+import { useRef, useState } from 'react'
+import { generateUploadUrlAction } from '~/app/actions/uploads'
+import { Button } from '~/components/ui/button'
+import { cn } from '~/lib/cn'
+import {
+  MAX_FILE_SIZE_BYTES,
+  MAX_FILE_SIZE_MB,
+  R2_UPLOAD_EXTENSION_BY_MIME_TYPE,
+  type R2UploadMimeType
+} from '~/lib/constants'
+import { toastErrorMessage, toastIfActionFailed } from '~/lib/toast-message'
+
+function isAllowedMimeType(type: string): type is R2UploadMimeType {
+  return type in R2_UPLOAD_EXTENSION_BY_MIME_TYPE
+}
+
+function readFileAsDataUrl(file: File): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader()
+    reader.onload = () => {
+      if (typeof reader.result === 'string') {
+        resolve(reader.result)
+        return
+      }
+      reject(new Error('Failed to read file'))
+    }
+    reader.onerror = () => {
+      reject(reader.error ?? new Error('Failed to read file'))
+    }
+    reader.readAsDataURL(file)
+  })
+}
+
+// Discriminated union so the preview renderer knows exactly what to show
+// without guessing from a raw URL string.
+type PreviewState =
+  | { kind: 'image'; url: string }
+  | { kind: 'file'; name: string; mimeType: string }
+  | null
+
+function getInitialPreview(currentUrl?: string | null): PreviewState {
+  if (!currentUrl) return null
+  // base64 data URLs and image paths/URLs both render as images
+  return { kind: 'image', url: currentUrl }
+}
+
+function FileTypeIcon({ mimeType }: { mimeType: string }) {
+  if (mimeType.startsWith('video/'))
+    return <Video className="text-muted-foreground h-8 w-8" />
+  if (mimeType.startsWith('audio/'))
+    return <Music className="text-muted-foreground h-8 w-8" />
+  if (mimeType === 'application/pdf' || mimeType.includes('text'))
+    return <FileText className="text-muted-foreground h-8 w-8" />
+  return <File className="text-muted-foreground h-8 w-8" />
+}
+
+type Props = {
+  /** MIME type filter passed to the file input, e.g. `"image/*"` or `"image/*,application/pdf"`. */
+  accept: string
+  /** Organization that owns the upload; the server checks you manage it. */
+  organizationId: string
+  /**
+   * Called with the R2 object key (prod) or base64 data URL (dev mode) once
+   * the upload finishes. Called with `null` when the user clears the value.
+   */
+  onClientUploadFinish: (key: string | null) => void
+  /**
+   * Pre-resolved URL for the current value. Pass the output of
+   * `resolveImageUrl` from the parent server component so the preview renders
+   * correctly for existing R2 keys.
+   */
+  currentUrl?: string | null
+  className?: string
+  /** Passed to next/image `sizes`. It should match the rendered widget width. */
+  sizes?: string
+}
+
+export function FileUpload({
+  accept,
+  organizationId,
+  onClientUploadFinish,
+  currentUrl,
+  className,
+  sizes = '128px'
+}: Props) {
+  const inputRef = useRef<HTMLInputElement>(null)
+  const [preview, setPreview] = useState<PreviewState>(
+    getInitialPreview(currentUrl)
+  )
+  const [isUploading, setIsUploading] = useState(false)
+
+  const handleFile = async (file: File) => {
+    if (file.size > MAX_FILE_SIZE_BYTES) {
+      toastErrorMessage(`Choose a file under ${MAX_FILE_SIZE_MB} MB.`)
+      return
+    }
+
+    if (!isAllowedMimeType(file.type)) {
+      toastErrorMessage('Choose a JPEG, PNG, WebP, or GIF image.')
+      return
+    }
+
+    setIsUploading(true)
+
+    // Set the preview from the file type without a network round trip.
+    if (file.type.startsWith('image/')) {
+      setPreview({ kind: 'image', url: URL.createObjectURL(file) })
+    } else {
+      setPreview({ kind: 'file', name: file.name, mimeType: file.type })
+    }
+
+    const result = await generateUploadUrlAction({
+      filename: file.name,
+      mimeType: file.type,
+      size: file.size,
+      organizationId
+    })
+
+    if (toastIfActionFailed(result)) {
+      setPreview(getInitialPreview(currentUrl))
+      setIsUploading(false)
+      return
+    }
+    if (!result?.data) {
+      toastErrorMessage('The upload could not start. Try again.')
+      setPreview(getInitialPreview(currentUrl))
+      setIsUploading(false)
+      return
+    }
+
+    const { data } = result
+
+    try {
+      if (data.mode === 'r2') {
+        const res = await fetch(data.uploadUrl, {
+          method: 'PUT',
+          body: file,
+          headers: { 'Content-Type': file.type }
+        })
+        if (!res.ok) throw new Error(`R2 upload failed: ${res.status}`)
+        onClientUploadFinish(data.key)
+      } else {
+        // Development mode has no R2 credentials, so store base64 data directly.
+        // Await the read so isUploading stays true until onClientUploadFinish runs.
+        const base64 = await readFileAsDataUrl(file)
+        if (file.type.startsWith('image/')) {
+          setPreview({ kind: 'image', url: base64 })
+        }
+        onClientUploadFinish(base64)
+      }
+    } catch {
+      toastErrorMessage(
+        data.mode === 'r2'
+          ? 'The upload failed. Check your connection and try again.'
+          : 'The file could not be read. Choose it again.'
+      )
+      setPreview(getInitialPreview(currentUrl))
+    } finally {
+      setIsUploading(false)
+    }
+  }
+
+  const handleClear = (e: React.MouseEvent) => {
+    e.stopPropagation()
+    setPreview(null)
+    onClientUploadFinish(null)
+    if (inputRef.current) inputRef.current.value = ''
+  }
+
+  return (
+    <div className={cn('relative', className)}>
+      <input
+        ref={inputRef}
+        type="file"
+        accept={accept}
+        className="hidden"
+        onChange={e => {
+          const file = e.target.files?.[0]
+          if (file) handleFile(file)
+          e.target.value = ''
+        }}
+      />
+
+      <button
+        type="button"
+        onClick={() => !isUploading && inputRef.current?.click()}
+        disabled={isUploading}
+        className={cn(
+          'border-border bg-muted/30 hover:bg-muted/50 relative flex aspect-square w-full cursor-pointer items-center justify-center overflow-hidden rounded-lg border-2 border-dashed transition-colors',
+          isUploading && 'cursor-not-allowed'
+        )}
+      >
+        {preview?.kind === 'image' && (
+          <Image
+            src={preview.url}
+            alt="Upload preview"
+            fill
+            sizes={sizes}
+            className="object-contain"
+            unoptimized={
+              preview.url.startsWith('data:') || preview.url.startsWith('blob:')
+            }
+          />
+        )}
+
+        {preview?.kind === 'file' && (
+          <div className="flex flex-col items-center gap-2 px-4">
+            <FileTypeIcon mimeType={preview.mimeType} />
+            <span className="text-muted-foreground max-w-full truncate text-xs">
+              {preview.name}
+            </span>
+          </div>
+        )}
+
+        {!preview && (
+          <div className="flex flex-col items-center gap-2">
+            <div className="bg-muted rounded-md p-2">
+              <Upload className="text-muted-foreground h-5 w-5" />
+            </div>
+            <span className="text-muted-foreground text-xs font-medium">
+              Click to upload
+            </span>
+            <span className="text-muted-foreground/60 text-[11px]">
+              Max {MAX_FILE_SIZE_MB} MB
+            </span>
+          </div>
+        )}
+
+        {isUploading && (
+          <div className="bg-background/70 absolute inset-0 flex items-center justify-center backdrop-blur-sm">
+            <Loader2 className="text-primary h-6 w-6 animate-spin" />
+          </div>
+        )}
+      </button>
+
+      {preview && !isUploading && (
+        <Button
+          type="button"
+          variant="destructive"
+          size="icon"
+          className="absolute -top-2 -right-2 h-6 w-6 rounded-full shadow-sm"
+          onClick={handleClear}
+          aria-label="Remove file"
+        >
+          <X className="h-3 w-3" />
+        </Button>
+      )}
+    </div>
+  )
+}

package/template/saas-starter/src/components/loader.tsx

@@ -0,0 +1,41 @@
+/**
+ * @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="var(--primary)"
+      initialPosition={0.08}
+      crawlSpeed={200}
+      height={3}
+      crawl={true}
+      showSpinner={true}
+      easing="ease"
+      speed={200}
+      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}
+      showAtBottom={false}
+    />
+  )
+}

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