create-ej-app 25.0.0 → 27.0.0

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

@@ -0,0 +1,236 @@
+'use client'
+
+import { ArrowLeft, Loader2, Send } from 'lucide-react'
+import Link from 'next/link'
+import { useState } from 'react'
+import {
+  addSupportTicketMessageAction,
+  getSupportTicketDetailsAction,
+  updateSupportTicketStatusAction
+} from '~/app/actions/support-tickets'
+import { Button } from '~/components/ui/button'
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue
+} from '~/components/ui/select'
+import { Textarea } from '~/components/ui/textarea'
+import { formatDate } from '~/lib/format-date'
+import {
+  useSafeActionMutation,
+  useSafeActionQuery
+} from '~/lib/safe-action-client'
+import { toastActionError, toastSuccessMessage } from '~/lib/toast-message'
+import {
+  SupportPriorityBadge,
+  SupportStatusBadge,
+  formatSupportLabel,
+  supportStatusOptions,
+  type SupportTicketStatus
+} from './support-ticket-shared'
+
+export function SupportTicketConversation({
+  ticketId,
+  backHref,
+  mode
+}: {
+  ticketId: string
+  backHref: string
+  /** `admin` answers as the support team and can change the status. */
+  mode: 'app' | 'admin'
+}) {
+  const [message, setMessage] = useState('')
+  const { data, isLoading, refetch } = useSafeActionQuery(
+    `support-ticket-${ticketId}`,
+    getSupportTicketDetailsAction,
+    { ticketId }
+  )
+
+  const addMessage = useSafeActionMutation(addSupportTicketMessageAction, {
+    onSuccess: () => {
+      setMessage('')
+      void refetch()
+      toastSuccessMessage('Message sent')
+    },
+    onError: error =>
+      toastActionError(error, 'Your message was not sent. Try again.')
+  })
+
+  const updateStatus = useSafeActionMutation(updateSupportTicketStatusAction, {
+    onSuccess: () => {
+      void refetch()
+      toastSuccessMessage('Ticket status updated')
+    },
+    onError: error =>
+      toastActionError(error, 'The status was not changed. Try again.')
+  })
+
+  if (isLoading) {
+    return (
+      <div className="flex h-[60vh] items-center justify-center">
+        <Loader2 className="text-primary h-8 w-8 animate-spin" />
+      </div>
+    )
+  }
+
+  if (!data) return null
+
+  const customerReplyDisabled =
+    mode === 'app' && ['closed', 'resolved'].includes(data.ticket.status)
+  const replyDisabled =
+    customerReplyDisabled || addMessage.isPending || !message.trim()
+
+  return (
+    <div className="space-y-5">
+      <div className="flex flex-wrap items-start justify-between gap-3">
+        <div className="space-y-3">
+          <Button asChild variant="ghost" size="sm" className="-ml-2">
+            <Link href={backHref}>
+              <ArrowLeft className="mr-2 h-4 w-4" />
+              Back
+            </Link>
+          </Button>
+          <div>
+            <div className="text-muted-foreground font-mono text-sm">
+              {data.ticket.ticketNumber}
+            </div>
+            <h1 className="text-2xl font-bold tracking-tight">
+              {data.ticket.subject}
+            </h1>
+            <div className="mt-2 flex flex-wrap items-center gap-2">
+              <SupportStatusBadge status={data.ticket.status} />
+              <SupportPriorityBadge priority={data.ticket.priority} />
+              <span className="text-muted-foreground text-sm">
+                Created {formatDate(data.ticket.createdAt, { short: true })}
+              </span>
+            </div>
+          </div>
+        </div>
+
+        {mode === 'admin' ? (
+          <div className="min-w-52">
+            <Select
+              value={data.ticket.status}
+              onValueChange={value =>
+                updateStatus.mutate({
+                  ticketId,
+                  status: value as SupportTicketStatus
+                })
+              }
+              disabled={updateStatus.isPending}
+            >
+              <SelectTrigger className="w-full">
+                <SelectValue placeholder="Update status" />
+              </SelectTrigger>
+              <SelectContent>
+                {supportStatusOptions.map(option => (
+                  <SelectItem key={option.value} value={option.value}>
+                    {option.label}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+          </div>
+        ) : null}
+      </div>
+
+      <div className="grid gap-5 lg:grid-cols-[1fr_280px]">
+        <section className="border-border bg-card overflow-hidden rounded-lg border shadow-sm">
+          <div className="border-border bg-muted/30 border-b px-5 py-3">
+            <h2 className="font-semibold">Conversation</h2>
+          </div>
+          <div className="space-y-4 p-5">
+            {data.messages.map(item => {
+              const mine = mode === 'admin' ? item.isAdmin : !item.isAdmin
+              return (
+                <div
+                  key={item.id}
+                  className={`flex ${mine ? 'justify-end' : 'justify-start'}`}
+                >
+                  <div
+                    className={`max-w-[82%] rounded-lg border px-4 py-3 ${
+                      mine
+                        ? 'bg-primary text-primary-foreground border-primary'
+                        : 'bg-background'
+                    }`}
+                  >
+                    <div className="mb-1 text-xs opacity-75">
+                      {item.isAdmin
+                        ? 'Support Team'
+                        : item.userName || item.userEmail || 'Customer'}{' '}
+                      ·{' '}
+                      {formatDate(item.createdAt, { short: true, time: true })}
+                    </div>
+                    <p className="text-sm leading-relaxed whitespace-pre-wrap">
+                      {item.message}
+                    </p>
+                  </div>
+                </div>
+              )
+            })}
+          </div>
+          <div className="border-border bg-muted/20 space-y-3 border-t p-5">
+            <Textarea
+              value={message}
+              disabled={customerReplyDisabled || addMessage.isPending}
+              onChange={event => setMessage(event.target.value)}
+              placeholder={
+                customerReplyDisabled
+                  ? 'This ticket is resolved or closed. Open a new one to follow up.'
+                  : 'Write a reply…'
+              }
+              className="min-h-28"
+            />
+            <div className="flex justify-end">
+              <Button
+                disabled={replyDisabled}
+                onClick={() =>
+                  addMessage.mutate({
+                    ticketId,
+                    message,
+                    asSupport: mode === 'admin'
+                  })
+                }
+              >
+                <Send className="mr-2 h-4 w-4" />
+                Send message
+              </Button>
+            </div>
+          </div>
+        </section>
+
+        <aside className="border-border bg-card h-fit rounded-lg border p-5 shadow-sm">
+          <h2 className="font-semibold">Ticket Details</h2>
+          <dl className="mt-4 space-y-3 text-sm">
+            <div>
+              <dt className="text-muted-foreground">Status</dt>
+              <dd>{formatSupportLabel(data.ticket.status)}</dd>
+            </div>
+            <div>
+              <dt className="text-muted-foreground">Priority</dt>
+              <dd>{formatSupportLabel(data.ticket.priority)}</dd>
+            </div>
+            <div>
+              <dt className="text-muted-foreground">Organization</dt>
+              <dd>{data.ticket.organizationName || '-'}</dd>
+            </div>
+            <div>
+              <dt className="text-muted-foreground">Raised by</dt>
+              <dd>{data.ticket.userName || data.ticket.userEmail || '-'}</dd>
+            </div>
+            <div>
+              <dt className="text-muted-foreground">Resolved</dt>
+              <dd>
+                {data.ticket.resolvedAt
+                  ? formatDate(data.ticket.resolvedAt, { short: true })
+                  : '-'}
+              </dd>
+            </div>
+          </dl>
+        </aside>
+      </div>
+    </div>
+  )
+}

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

@@ -0,0 +1,58 @@
+import { Badge } from '~/components/ui/badge'
+
+export const supportStatusOptions = [
+  { label: 'Open', value: 'open' },
+  { label: 'In Progress', value: 'in_progress' },
+  { label: 'Waiting on Customer', value: 'waiting_customer' },
+  { label: 'Resolved', value: 'resolved' },
+  { label: 'Closed', value: 'closed' }
+] as const
+
+export const supportPriorityOptions = [
+  { label: 'Low', value: 'low' },
+  { label: 'Medium', value: 'medium' },
+  { label: 'High', value: 'high' },
+  { label: 'Urgent', value: 'urgent' }
+] as const
+
+export type SupportTicketStatus = (typeof supportStatusOptions)[number]['value']
+export type SupportTicketPriority =
+  (typeof supportPriorityOptions)[number]['value']
+
+export function formatSupportLabel(value: string | null) {
+  if (!value) return '-'
+  return value.replaceAll('_', ' ').replace(/\b\w/g, char => char.toUpperCase())
+}
+
+export function SupportStatusBadge({ status }: { status: string }) {
+  const variantMap = {
+    open: 'info',
+    in_progress: 'info',
+    waiting_customer: 'warning',
+    resolved: 'success',
+    closed: 'secondary'
+  } as const
+
+  const variant = variantMap[status as keyof typeof variantMap] ?? 'secondary'
+
+  return <Badge variant={variant}>{formatSupportLabel(status)}</Badge>
+}
+
+export function SupportPriorityBadge({
+  priority
+}: {
+  priority: string | null
+}) {
+  if (!priority) return <span className="text-muted-foreground">-</span>
+
+  const variantMap = {
+    low: 'outline',
+    medium: 'secondary',
+    high: 'warning',
+    urgent: 'destructive'
+  } as const
+
+  const variant = variantMap[priority as keyof typeof variantMap] ?? 'secondary'
+
+  return <Badge variant={variant}>{formatSupportLabel(priority)}</Badge>
+}

package/template/saas-starter/src/components/support/support-tickets-table.tsx

@@ -0,0 +1,281 @@
+'use client'
+
+import { Eye, Plus, Ticket } from 'lucide-react'
+import Link from 'next/link'
+import {
+  parseAsInteger,
+  parseAsJson,
+  parseAsString,
+  useQueryStates
+} from 'nuqs'
+import {
+  getAdminSupportTicketsAction,
+  getMyAccountSupportTicketsAction,
+  getOrganizationSupportTicketsAction,
+  getSupportTicketOrganizationsAction
+} from '~/app/actions/support-tickets'
+import { DataTable, type DataTableColumnDef } from '~/components/data-table'
+import { SortOrderEnum } from '~/components/data-table/enum'
+import { DataTableFilter } from '~/components/data-table/types'
+import { PageHeading } from '~/components/page-heading'
+import { Button } from '~/components/ui/button'
+import { formatDate } from '~/lib/format-date'
+import { useSafeActionQuery } from '~/lib/safe-action-client'
+import { CreateSupportTicketDialog } from './create-support-ticket-dialog'
+import {
+  SupportPriorityBadge,
+  SupportStatusBadge,
+  supportPriorityOptions,
+  supportStatusOptions
+} from './support-ticket-shared'
+
+type SupportTicket = {
+  id: string
+  ticketNumber: string
+  subject: string
+  status: string
+  priority: string | null
+  createdAt: Date
+  resolvedAt: Date | null
+  userId: string | null
+  userName: string | null
+  userEmail: string | null
+  organizationId: string | null
+  organizationName: string | null
+}
+
+const baseFilters: DataTableFilter[] = [
+  {
+    id: 'status',
+    label: 'Status',
+    options: supportStatusOptions.map(option => ({
+      label: option.label,
+      value: option.value
+    }))
+  },
+  {
+    id: 'priority',
+    label: 'Priority',
+    options: supportPriorityOptions.map(option => ({
+      label: option.label,
+      value: option.value
+    }))
+  }
+]
+
+// Only the platform view spans organizations, so only it filters by one.
+const adminFilters: DataTableFilter[] = [
+  ...baseFilters,
+  {
+    id: 'organizationId',
+    label: 'Organization',
+    action: getSupportTicketOrganizationsAction,
+    queryKey: 'support-ticket-organizations'
+  }
+]
+
+type SupportTicketsTableProps =
+  | { mode: 'admin' | 'account'; basePath: string; organizationId?: undefined }
+  | { mode: 'app'; basePath: string; organizationId: string }
+
+const COPY = {
+  admin: {
+    title: 'Support Tickets',
+    description: 'View, respond to, and manage customer support conversations.',
+    searchPlaceholder: 'Search by ticket #, subject, user, or organization…'
+  },
+  app: {
+    title: 'Support Tickets',
+    description:
+      'Every ticket for this organization. Owners and admins can reply to all of them.',
+    searchPlaceholder: 'Search by ticket # or subject…'
+  },
+  account: {
+    title: 'Support',
+    description:
+      "Tickets about your account. To raise one about an organization, use that organization's support page.",
+    searchPlaceholder: 'Search by ticket # or subject…'
+  }
+} as const
+
+export function SupportTicketsTable({
+  mode,
+  basePath,
+  organizationId
+}: SupportTicketsTableProps) {
+  const [queryState, setQueryState] = useQueryStates({
+    page: parseAsInteger.withDefault(1),
+    limit: parseAsInteger.withDefault(10),
+    sortBy: parseAsString,
+    sortOrder: parseAsString,
+    search: parseAsString,
+    filters: parseAsJson(v => v as Record<string, (string | boolean)[]>)
+  })
+
+  const params = {
+    page: queryState.page,
+    limit: queryState.limit,
+    sortBy: (queryState.sortBy ?? undefined) as
+      | 'ticketNumber'
+      | 'subject'
+      | 'status'
+      | 'priority'
+      | 'createdAt'
+      | 'resolvedAt'
+      | undefined,
+    sortOrder: (queryState.sortOrder ?? undefined) as SortOrderEnum | undefined,
+    search: queryState.search ?? undefined,
+    filters: queryState.filters ?? undefined
+  }
+
+  const adminQuery = useSafeActionQuery(
+    'admin-support-tickets',
+    getAdminSupportTicketsAction,
+    params,
+    { enabled: mode === 'admin' }
+  )
+  const organizationQuery = useSafeActionQuery(
+    `support-tickets-${organizationId}`,
+    getOrganizationSupportTicketsAction,
+    { ...params, organizationId: organizationId! },
+    { enabled: mode === 'app' }
+  )
+  const accountQuery = useSafeActionQuery(
+    'account-support-tickets',
+    getMyAccountSupportTicketsAction,
+    params,
+    { enabled: mode === 'account' }
+  )
+  const { data, isLoading } =
+    mode === 'admin'
+      ? adminQuery
+      : mode === 'app'
+        ? organizationQuery
+        : accountQuery
+
+  const columns: DataTableColumnDef<SupportTicket>[] = [
+    {
+      accessorKey: 'ticketNumber',
+      header: 'Ticket #',
+      enableSorting: true,
+      cell: ({ row }) => (
+        <span className="font-mono text-sm">{row.original.ticketNumber}</span>
+      )
+    },
+    {
+      accessorKey: 'subject',
+      header: mode === 'account' ? 'Subject' : 'Subject & Raised by',
+      enableSorting: true,
+      cell: ({ row }) => (
+        <div className="flex flex-col">
+          <span className="line-clamp-1 text-sm font-medium">
+            {row.original.subject}
+          </span>
+          {mode === 'account' ? null : (
+            <span className="text-muted-foreground text-xs">
+              {row.original.userName ||
+                row.original.userEmail ||
+                'Removed user'}
+            </span>
+          )}
+        </div>
+      )
+    },
+    ...(mode === 'admin'
+      ? [
+          {
+            accessorKey: 'organizationName',
+            header: 'Organization',
+            enableSorting: false,
+            cell: ({ row }: { row: { original: SupportTicket } }) =>
+              row.original.organizationId ? (
+                <span className="line-clamp-1 text-sm">
+                  {row.original.organizationName || 'Unknown'}
+                </span>
+              ) : (
+                <span className="text-muted-foreground text-sm">Account</span>
+              )
+          } satisfies DataTableColumnDef<SupportTicket>
+        ]
+      : []),
+    {
+      accessorKey: 'status',
+      header: 'Status',
+      enableSorting: true,
+      cell: ({ row }) => <SupportStatusBadge status={row.original.status} />
+    },
+    {
+      accessorKey: 'priority',
+      header: 'Priority',
+      enableSorting: true,
+      cell: ({ row }) => (
+        <SupportPriorityBadge priority={row.original.priority} />
+      )
+    },
+    {
+      accessorKey: 'createdAt',
+      header: 'Created',
+      enableSorting: true,
+      cell: ({ row }) => formatDate(row.original.createdAt, { short: true })
+    },
+    {
+      id: 'actions',
+      cell: ({ row }) => (
+        <Button asChild variant="ghost" size="icon" className="h-8 w-8">
+          <Link href={`${basePath}/${row.original.id}`}>
+            <Eye className="h-4 w-4" />
+            <span className="sr-only">View ticket</span>
+          </Link>
+        </Button>
+      )
+    }
+  ]
+
+  return (
+    <div className="space-y-6">
+      <PageHeading
+        title={COPY[mode].title}
+        description={COPY[mode].description}
+        icon={Ticket}
+      >
+        {mode === 'admin' ? null : (
+          <CreateSupportTicketDialog
+            organizationId={organizationId}
+            redirectBasePath={basePath}
+          >
+            <Button size="sm">
+              <Plus className="mr-2 h-4 w-4" />
+              New Ticket
+            </Button>
+          </CreateSupportTicketDialog>
+        )}
+      </PageHeading>
+
+      <DataTable
+        columns={columns}
+        data={data?.[0]}
+        isLoading={isLoading}
+        totalCount={data?.[1]}
+        enableSearch
+        initialSearch={params.search}
+        searchPlaceholder={COPY[mode].searchPlaceholder}
+        manualPagination
+        manualSorting
+        pageIndex={params.page - 1}
+        pageSize={params.limit}
+        filters={mode === 'admin' ? adminFilters : baseFilters}
+        activeFilters={params.filters ?? {}}
+        onParamsChange={({ page, limit, sortBy, sortOrder, search, filters }) =>
+          setQueryState({
+            page,
+            limit,
+            sortBy: sortBy ?? null,
+            sortOrder: sortOrder ?? null,
+            search: search ?? null,
+            filters: filters ?? null
+          })
+        }
+      />
+    </div>
+  )
+}

package/template/saas-starter/src/components/theme-provider.tsx

@@ -0,0 +1,115 @@
+/**
+ * @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
+  }
+
+  return (
+    target.isContentEditable ||
+    target.tagName === 'INPUT' ||
+    target.tagName === 'TEXTAREA' ||
+    target.tagName === 'SELECT'
+  )
+}
+
+/**
+ * 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
+      }
+
+      if (event.metaKey || event.ctrlKey || event.altKey) {
+        return
+      }
+
+      if (event.key.toLowerCase() !== 'd') {
+        return
+      }
+
+      if (isTypingTarget(event.target)) {
+        return
+      }
+
+      setTheme(resolvedTheme === 'dark' ? 'light' : 'dark')
+    }
+
+    window.addEventListener('keydown', onKeyDown)
+
+    return () => {
+      window.removeEventListener('keydown', onKeyDown)
+    }
+  }, [resolvedTheme, setTheme])
+
+  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 }) => {
+  return (
+    <NextThemesProvider
+      attribute="class"
+      defaultTheme="system"
+      enableSystem
+      disableTransitionOnChange
+    >
+      <ThemeHotkey />
+      {children}
+    </NextThemesProvider>
+  )
+}