@rovela-ai/sdk 0.19.4 → 0.19.6

package/templates/store-template/app/admin/(dashboard)/categories/page.tsx

@@ -0,0 +1,223 @@
+'use client'
+
+/**
+ * Admin Categories Page
+ *
+ * Category management with tree display.
+ * Uses SDK admin useAdminCategories hook.
+ */
+
+import { useState, useEffect } from 'react'
+import Link from 'next/link'
+import { Plus, Pencil, Trash2, FolderOpen, ChevronRight, ChevronDown } from 'lucide-react'
+import { AdminPageHeader, useAdminCategories, DeleteConfirmDialog, type CategoryTreeItem, adminToast } from '@rovela-ai/sdk/admin'
+import { AdminEmptyState } from '@rovela-ai/sdk/admin/components'
+
+export default function AdminCategoriesPage() {
+  const { categoryTree, isLoading, error, deleteCategory } = useAdminCategories()
+  const [expandedIds, setExpandedIds] = useState<Set<string>>(new Set())
+  const [deletingId, setDeletingId] = useState<string | null>(null)
+
+  // Auto-expand every parent on first load so newly-created subcategories are
+  // visible without the merchant hunting for the chevron. Only seeds once
+  // (prev.size === 0 guard) so manual collapse state survives subsequent
+  // tree updates.
+  // Pattern C — populate state from async-loaded data.
+  useEffect(() => {
+    if (categoryTree.length === 0) return
+    const ids = new Set<string>()
+    const walk = (nodes: CategoryTreeItem[]) => nodes.forEach(n => {
+      if (n.children.length > 0) {
+        ids.add(n.id)
+        walk(n.children)
+      }
+    })
+    walk(categoryTree)
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    setExpandedIds(prev => (prev.size === 0 ? ids : prev))
+  }, [categoryTree])
+
+  // Delete confirmation state
+  const [deleteTarget, setDeleteTarget] = useState<{ id: string; name: string } | null>(null)
+  const [deleteError, setDeleteError] = useState<string | null>(null)
+
+  const toggleExpand = (id: string) => {
+    setExpandedIds(prev => {
+      const next = new Set(prev)
+      if (next.has(id)) {
+        next.delete(id)
+      } else {
+        next.add(id)
+      }
+      return next
+    })
+  }
+
+  const handleDeleteClick = (id: string, name: string) => {
+    setDeleteTarget({ id, name })
+    setDeleteError(null)
+  }
+
+  const handleDeleteConfirm = async () => {
+    if (!deleteTarget) return
+
+    setDeletingId(deleteTarget.id)
+    const success = await deleteCategory(deleteTarget.id)
+    setDeletingId(null)
+
+    if (success) {
+      setDeleteTarget(null)
+      adminToast.success('Category deleted')
+    } else {
+      setDeleteError('Failed to delete category. It may have products assigned to it.')
+    }
+  }
+
+  const handleDeleteCancel = () => {
+    if (!deletingId) {
+      setDeleteTarget(null)
+      setDeleteError(null)
+    }
+  }
+
+  const renderCategory = (category: CategoryTreeItem, depth: number = 0) => {
+    const hasChildren = category.children.length > 0
+    const isExpanded = expandedIds.has(category.id)
+    const isDeleting = deletingId === category.id
+
+    return (
+      <div key={category.id}>
+        <div
+          className={`flex items-center gap-3 border-b border-border px-4 py-3 hover:bg-accent/50 transition-colors ${isDeleting ? 'opacity-50' : ''}`}
+          style={{ paddingLeft: `${16 + depth * 24}px` }}
+        >
+          {/* Expand/collapse toggle */}
+          <button
+            type="button"
+            onClick={() => toggleExpand(category.id)}
+            className={`p-1 rounded hover:bg-accent ${!hasChildren ? 'invisible' : ''}`}
+            disabled={!hasChildren}
+          >
+            {isExpanded ? (
+              <ChevronDown className="h-4 w-4 text-muted-foreground" />
+            ) : (
+              <ChevronRight className="h-4 w-4 text-muted-foreground" />
+            )}
+          </button>
+
+          {/* Category icon */}
+          <FolderOpen className="h-5 w-5 text-muted-foreground flex-shrink-0" />
+
+          {/* Category info */}
+          <div className="flex-1 min-w-0">
+            <div className="flex items-center gap-2">
+              <span className="font-medium text-foreground truncate">{category.name}</span>
+              {hasChildren && (
+                <span
+                  className="text-xs text-muted-foreground tabular-nums"
+                  aria-label={`${category.children.length} subcategor${category.children.length === 1 ? 'y' : 'ies'}`}
+                >
+                  {category.children.length}
+                </span>
+              )}
+            </div>
+            <div className="text-sm text-muted-foreground truncate">/{category.slug}</div>
+          </div>
+
+          {/* Actions */}
+          <div className="flex items-center gap-2">
+            <Link
+              href={`/admin/categories/${category.id}`}
+              className="p-2 rounded-md hover:bg-accent text-muted-foreground hover:text-foreground transition-colors"
+            >
+              <Pencil className="h-4 w-4" />
+            </Link>
+            <button
+              type="button"
+              onClick={() => handleDeleteClick(category.id, category.name)}
+              disabled={isDeleting}
+              className="p-2 rounded-md hover:bg-destructive/10 text-muted-foreground hover:text-destructive transition-colors disabled:opacity-50"
+            >
+              <Trash2 className="h-4 w-4" />
+            </button>
+          </div>
+        </div>
+
+        {/* Children */}
+        {hasChildren && isExpanded && (
+          <div>
+            {category.children.map(child => renderCategory(child, depth + 1))}
+          </div>
+        )}
+      </div>
+    )
+  }
+
+  return (
+    <div className="space-y-6">
+      <AdminPageHeader
+        title="Categories"
+        subtitle="Organize your catalog into collections your customers browse."
+        actions={
+          <Link href="/admin/categories/new" className="admin-btn admin-btn-primary">
+            <Plus className="h-4 w-4" />
+            Add category
+          </Link>
+        }
+      />
+
+      {/* Error state */}
+      {error && (
+        <div className="rounded-md bg-destructive/10 px-4 py-3 text-sm text-destructive">
+          {error}
+        </div>
+      )}
+
+      {/* Loading state */}
+      {isLoading && (
+        <div className="flex items-center justify-center py-12">
+          <span className="admin-spinner admin-spinner-lg" />
+        </div>
+      )}
+
+      {/* Empty state */}
+      {!isLoading && !error && categoryTree.length === 0 && (
+        <div className="rounded-lg border border-border bg-card">
+          <AdminEmptyState
+            icon={<FolderOpen />}
+            title="No categories yet"
+            description="Get started by creating your first category."
+            action={
+              <Link
+                href="/admin/categories/new"
+                className="admin-btn admin-btn-primary"
+              >
+                <Plus className="h-4 w-4" />
+                Add category
+              </Link>
+            }
+          />
+        </div>
+      )}
+
+      {/* Category tree */}
+      {!isLoading && !error && categoryTree.length > 0 && (
+        <div className="rounded-lg border border-border bg-card overflow-hidden">
+          {categoryTree.map(category => renderCategory(category, 0))}
+        </div>
+      )}
+
+      {/* Delete Confirmation Dialog */}
+      <DeleteConfirmDialog
+        isOpen={!!deleteTarget}
+        title="Delete Category"
+        itemName={deleteTarget?.name || ''}
+        itemType="category"
+        isDeleting={!!deletingId}
+        error={deleteError}
+        onConfirm={handleDeleteConfirm}
+        onCancel={handleDeleteCancel}
+      />
+    </div>
+  )
+}

package/templates/store-template/app/admin/(dashboard)/customers/[id]/page.tsx

@@ -0,0 +1,26 @@
+'use client'
+
+/**
+ * Admin Customer Detail Page
+ *
+ * View and manage a single customer using the SDK CustomerDetails
+ * component, which renders the page header itself (back + eyebrow +
+ * name + verification badge) — LEDGER page architecture.
+ */
+
+import { useParams, useRouter } from 'next/navigation'
+import { CustomerDetails } from '@rovela-ai/sdk/admin'
+
+export default function CustomerDetailPage() {
+  const params = useParams()
+  const id = params.id as string
+  const router = useRouter()
+
+  return (
+    <CustomerDetails
+      customerId={id}
+      onBack={() => router.push('/admin/customers')}
+      onDelete={() => router.push('/admin/customers')}
+    />
+  )
+}

package/templates/store-template/app/admin/(dashboard)/customers/page.tsx

@@ -0,0 +1,33 @@
+'use client'
+
+/**
+ * Admin Customers Page
+ *
+ * Customer management view using SDK CustomerTable component.
+ * Displays ALL registered customers, not just those who ordered.
+ */
+
+import { useRouter } from 'next/navigation'
+import { AdminPageHeader, CustomerTable } from '@rovela-ai/sdk/admin'
+
+export default function AdminCustomersPage() {
+  const router = useRouter()
+
+  const handleCustomerClick = (customerId: string) => {
+    router.push(`/admin/customers/${customerId}`)
+  }
+
+  return (
+    <div className="space-y-6">
+      <AdminPageHeader
+        title="Customers"
+        subtitle="Everyone with an account or an order in your store."
+      />
+
+      <CustomerTable
+        pageSize={20}
+        onCustomerClick={handleCustomerClick}
+      />
+    </div>
+  )
+}

package/templates/store-template/app/admin/(dashboard)/discounts/page.tsx

@@ -0,0 +1,16 @@
+'use client'
+
+/**
+ * Admin Discounts Page
+ *
+ * The NATIVE discounts engine — discount codes and automatic promotions
+ * created and applied inside the store's own checkout. The DiscountsManager
+ * renders the page header itself (LEDGER page architecture): this wrapper
+ * stays a bare mount so the title and CTAs exist exactly once.
+ */
+
+import { DiscountsManager } from '@rovela-ai/sdk/admin'
+
+export default function AdminDiscountsPage() {
+  return <DiscountsManager />
+}

package/templates/store-template/app/admin/(dashboard)/emails/page.tsx

@@ -0,0 +1,16 @@
+'use client'
+
+/**
+ * Admin Emails Page
+ *
+ * Every transactional email the store sends, on one shared brand theme.
+ * The EmailsManager renders the page header itself (LEDGER page
+ * architecture): this wrapper stays a bare mount so the title and CTAs
+ * exist exactly once.
+ */
+
+import { EmailsManager } from '@rovela-ai/sdk/admin'
+
+export default function AdminEmailsPage() {
+  return <EmailsManager />
+}

package/templates/store-template/app/admin/(dashboard)/files/page.tsx

@@ -0,0 +1,16 @@
+'use client'
+
+/**
+ * Admin Files Page
+ *
+ * The store's media library — every image and video under the store's R2
+ * prefix. Same live storage the Rovela platform's Assets Library lists.
+ * The FilesManager renders the page header itself (LEDGER page
+ * architecture): this wrapper stays a bare mount.
+ */
+
+import { FilesManager } from '@rovela-ai/sdk/admin'
+
+export default function AdminFilesPage() {
+  return <FilesManager />
+}

package/templates/store-template/app/admin/(dashboard)/layout.tsx

@@ -0,0 +1,44 @@
+/**
+ * Admin Layout
+ *
+ * Protected admin area with sidebar navigation.
+ *
+ * Server-side gate: the layout is an async Server Component
+ * that calls `getCurrentAdmin()` and 307-redirects unauthenticated users to
+ * `/admin/login` BEFORE any HTML reaches the client. Eliminates the flash
+ * of admin chrome that previously appeared during the ~200–400ms session
+ * fetch window for unauthenticated visitors.
+ *
+ * Layered defense:
+ *   - Server Component layout (this file): the primary gate. Stops cold
+ *     loads of `/admin/*` from rendering any chrome for unauth visitors.
+ *   - AdminGuard (client component, kept inside): catches mid-session
+ *     expirations after the page is already rendered (e.g., JWT TTL
+ *     elapses while the user is idle on /admin/products).
+ *   - requireAdmin on every API route: the actual security boundary.
+ *
+ * AdminLayout is a client component (uses `rovela-admin-theme` chrome and
+ * the AdminNav with hooks) so it stays client-rendered — but it now only
+ * renders for authenticated users.
+ */
+
+import { redirect } from 'next/navigation'
+import { AdminGuard, AdminLayout } from '@rovela-ai/sdk/admin'
+import { getCurrentAdmin } from '@rovela-ai/sdk/admin/server'
+
+export default async function AdminRootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  const session = await getCurrentAdmin()
+  if (!session) {
+    redirect('/admin/login')
+  }
+
+  return (
+    <AdminLayout>
+      <AdminGuard redirectTo="/admin/login">{children}</AdminGuard>
+    </AdminLayout>
+  )
+}

package/templates/store-template/app/admin/(dashboard)/loading.tsx

@@ -0,0 +1,88 @@
+/**
+ * Admin Dashboard Loading State
+ *
+ * Shows skeleton UI during page transitions within the admin dashboard.
+ * Matches the dashboard layout structure for smooth visual continuity.
+ */
+
+export default function AdminLoading() {
+  return (
+    <div className="space-y-8">
+      {/* Welcome Header Skeleton */}
+      <div className="flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
+        <div>
+          <div className="admin-skeleton h-8 w-64 rounded" />
+          <div className="admin-skeleton h-4 w-40 mt-2 rounded" />
+        </div>
+        <div className="flex gap-2">
+          <div className="admin-skeleton h-10 w-28 rounded-lg" />
+          <div className="admin-skeleton h-10 w-28 rounded-lg" />
+          <div className="admin-skeleton h-10 w-10 rounded-lg" />
+        </div>
+      </div>
+
+      {/* Stats Cards Skeleton */}
+      <section>
+        <div className="admin-skeleton h-4 w-20 mb-4 rounded" />
+        <div className="admin-stats-grid">
+          {[...Array(4)].map((_, i) => (
+            <div key={i} className="admin-card p-6">
+              <div className="admin-skeleton h-4 w-24 rounded" />
+              <div className="admin-skeleton h-9 w-32 mt-2 rounded" />
+              <div className="admin-skeleton h-3 w-20 mt-4 rounded" />
+            </div>
+          ))}
+        </div>
+      </section>
+
+      {/* Charts Skeleton */}
+      <section className="grid grid-cols-1 gap-6 xl:grid-cols-3">
+        <div className="xl:col-span-2 admin-card p-6">
+          <div className="admin-skeleton h-5 w-32 mb-4 rounded" />
+          <div className="admin-skeleton h-64 rounded" />
+        </div>
+        <div className="admin-card p-6">
+          <div className="admin-skeleton h-5 w-28 mb-4 rounded" />
+          <div className="admin-skeleton h-64 rounded" />
+        </div>
+      </section>
+
+      {/* Activity Section Skeleton */}
+      <section>
+        <div className="admin-skeleton h-4 w-16 mb-4 rounded" />
+        <div className="grid grid-cols-1 gap-6 lg:grid-cols-2">
+          <div className="admin-card p-6">
+            <div className="admin-skeleton h-5 w-28 mb-4 rounded" />
+            <div className="space-y-3">
+              {[...Array(5)].map((_, i) => (
+                <div key={i} className="flex items-center gap-3">
+                  <div className="admin-skeleton h-10 w-10 rounded" />
+                  <div className="flex-1">
+                    <div className="admin-skeleton h-4 w-32 rounded" />
+                    <div className="admin-skeleton h-3 w-24 mt-1 rounded" />
+                  </div>
+                  <div className="admin-skeleton h-6 w-16 rounded" />
+                </div>
+              ))}
+            </div>
+          </div>
+          <div className="admin-card p-6">
+            <div className="admin-skeleton h-5 w-24 mb-4 rounded" />
+            <div className="space-y-3">
+              {[...Array(5)].map((_, i) => (
+                <div key={i} className="flex items-center gap-3">
+                  <div className="admin-skeleton h-10 w-10 rounded" />
+                  <div className="flex-1">
+                    <div className="admin-skeleton h-4 w-28 rounded" />
+                    <div className="admin-skeleton h-3 w-20 mt-1 rounded" />
+                  </div>
+                  <div className="admin-skeleton h-6 w-12 rounded" />
+                </div>
+              ))}
+            </div>
+          </div>
+        </div>
+      </section>
+    </div>
+  )
+}

package/templates/store-template/app/admin/(dashboard)/locations/page.tsx

@@ -0,0 +1,16 @@
+'use client'
+
+/**
+ * Admin Locations Page
+ *
+ * Physical shops (a standalone entity, Shopify's Locations model). Pickup
+ * enabled locations appear at checkout as "Pick up in store". The
+ * LocationsManager renders the page header itself (LEDGER page
+ * architecture): this wrapper stays a bare mount.
+ */
+
+import { LocationsManager } from '@rovela-ai/sdk/admin'
+
+export default function AdminLocationsPage() {
+  return <LocationsManager />
+}

package/templates/store-template/app/admin/(dashboard)/orders/[id]/page.tsx

@@ -0,0 +1,66 @@
+'use client'
+
+/**
+ * Admin Order Detail Page
+ *
+ * View and manage individual order details.
+ * Uses SDK admin OrderDetails and RefundDialog components.
+ */
+
+import { useState, useCallback } from 'react'
+import { useParams, useRouter } from 'next/navigation'
+import { OrderDetails, RefundDialog } from '@rovela-ai/sdk/admin'
+
+export default function AdminOrderDetailPage() {
+  const params = useParams()
+  const id = params.id as string
+  const router = useRouter()
+
+  // Refund dialog state
+  const [showRefundDialog, setShowRefundDialog] = useState(false)
+  const [refundOrderData, setRefundOrderData] = useState<{
+    orderId: string
+    orderTotal: string | number
+    orderCurrency?: string | null
+  } | null>(null)
+
+  // Handle refund button click from OrderDetails
+  const handleRefund = useCallback(
+    (orderId: string, orderTotal: string | number, orderCurrency?: string | null) => {
+      setRefundOrderData({ orderId, orderTotal, orderCurrency })
+      setShowRefundDialog(true)
+    },
+    []
+  )
+
+  // Handle refund success - refresh the page to show updated status
+  const handleRefundSuccess = useCallback(() => {
+    // Force a refresh by navigating to the same page
+    router.refresh()
+  }, [router])
+
+  return (
+    <div className="space-y-6">
+      <OrderDetails
+        orderId={id}
+        onBack={() => router.push('/admin/orders')}
+        onRefund={handleRefund}
+      />
+
+      {/* Refund Dialog */}
+      {refundOrderData && (
+        <RefundDialog
+          orderId={refundOrderData.orderId}
+          orderTotal={refundOrderData.orderTotal}
+          currency={refundOrderData.orderCurrency}
+          isOpen={showRefundDialog}
+          onClose={() => {
+            setShowRefundDialog(false)
+            setRefundOrderData(null)
+          }}
+          onSuccess={handleRefundSuccess}
+        />
+      )}
+    </div>
+  )
+}

package/templates/store-template/app/admin/(dashboard)/orders/page.tsx

@@ -0,0 +1,26 @@
+'use client'
+
+/**
+ * Admin Orders Page
+ *
+ * Order management with table and filters.
+ * Uses SDK admin OrderTable component.
+ */
+
+import { useRouter } from 'next/navigation'
+import { AdminPageHeader, OrderTable } from '@rovela-ai/sdk/admin'
+
+export default function AdminOrdersPage() {
+  const router = useRouter()
+
+  return (
+    <div className="space-y-6">
+      <AdminPageHeader
+        title="Orders"
+        subtitle="Track, fulfill and refund your customers' orders."
+      />
+
+      <OrderTable onOrderClick={(id) => router.push(`/admin/orders/${id}`)} />
+    </div>
+  )
+}