@stacksjs/defaults 0.70.229 → 0.70.231

package/resources/components/Dashboard/Commerce/CommerceCategoriesDashboard.stx

@@ -0,0 +1,300 @@
+<script client>
+import type {
+  CommerceCategoryRecord,
+  CommerceCategorySummary,
+} from '../../../../app/Actions/Dashboard/Commerce/commerce-category-records'
+import { DashboardApiError, dashboardApi } from '../../../../functions/dashboard-api'
+import { pushToast } from '../../../../functions/toasts'
+
+interface CategoryIndexResponse {
+  records: CommerceCategoryRecord[]
+  summary: CommerceCategorySummary
+}
+
+interface CategoryWritePayload {
+  name: string
+  description: string
+  slug: string
+  imageUrl: string
+  isActive: boolean
+  parentCategoryId: string
+  displayOrder: number
+}
+
+const emptySummary: CommerceCategorySummary = { total: 0, active: 0, roots: 0, children: 0 }
+const records = state<CommerceCategoryRecord[]>([])
+const summary = state<CommerceCategorySummary>({ ...emptySummary })
+const search = state('')
+const activeFilter = state('all')
+const hierarchyFilter = state('all')
+const sort = state('order')
+const page = state(1)
+const pageSize = 20
+const loading = state(true)
+const loadError = state('')
+const dialogOpen = state(false)
+const dialogMode = state<'add' | 'edit'>('add')
+const editingRecord = state<CommerceCategoryRecord | null>(null)
+const detailsRecord = state<CommerceCategoryRecord | null>(null)
+const deletingRecord = state<CommerceCategoryRecord | null>(null)
+const saving = state(false)
+const deleting = state(false)
+const validationErrors = state<Record<string, string>>({})
+
+function categoryName(id: string): string {
+  return records().find(record => record.id === id)?.name || ''
+}
+
+function filteredRecords(): CommerceCategoryRecord[] {
+  const query = search().trim().toLowerCase()
+  const selectedActive = activeFilter()
+  const selectedHierarchy = hierarchyFilter()
+  return [...records()]
+    .filter((record) => {
+      if (selectedActive === 'active' && !record.isActive)
+        return false
+      if (selectedActive === 'inactive' && record.isActive)
+        return false
+      if (selectedHierarchy === 'root' && record.parentCategoryId)
+        return false
+      if (selectedHierarchy === 'child' && !record.parentCategoryId)
+        return false
+      return !query || [record.name, record.description, record.slug, categoryName(record.parentCategoryId)]
+        .some(value => value.toLowerCase().includes(query))
+    })
+    .sort((left, right) => {
+      if (sort() === 'name')
+        return left.name.localeCompare(right.name)
+      if (sort() === 'newest')
+        return Number(right.id) - Number(left.id)
+      return left.displayOrder - right.displayOrder || left.name.localeCompare(right.name)
+    })
+}
+
+function pageCount(): number {
+  return Math.max(1, Math.ceil(filteredRecords().length / pageSize))
+}
+
+function visibleRecords(): CommerceCategoryRecord[] {
+  const selectedPage = Math.min(page(), pageCount())
+  return filteredRecords().slice((selectedPage - 1) * pageSize, selectedPage * pageSize)
+}
+
+function matchingLabel(): string {
+  const count = filteredRecords().length
+  return `${count} matching ${count === 1 ? 'category' : 'categories'}`
+}
+
+function metricCards(): Array<{ label: string, value: string, detail: string }> {
+  const current = summary()
+  return [
+    { label: 'Categories', value: String(current.total), detail: 'Persisted product categories' },
+    { label: 'Active', value: String(current.active), detail: `${current.total - current.active} inactive` },
+    { label: 'Root categories', value: String(current.roots), detail: 'Top-level navigation' },
+    { label: 'Child categories', value: String(current.children), detail: 'Nested hierarchy entries' },
+  ]
+}
+
+function exportHref(): string {
+  const rows = filteredRecords().map(record => [
+    record.name,
+    record.slug,
+    record.description,
+    record.isActive ? 'Active' : 'Inactive',
+    record.parentCategoryId ? categoryName(record.parentCategoryId) : '',
+    String(record.displayOrder),
+    record.imageUrl,
+  ])
+  const escape = (value: string): string => `"${value.replaceAll('"', '""')}"`
+  const csv = [
+    ['Name', 'Slug', 'Description', 'Status', 'Parent', 'Display order', 'Image URL'],
+    ...rows,
+  ].map(row => row.map(escape).join(',')).join('\n')
+  return `data:text/csv;charset=utf-8,${encodeURIComponent(`\uFEFF${csv}`)}`
+}
+
+effect(() => {
+  search()
+  activeFilter()
+  hierarchyFilter()
+  sort()
+  page.set(1)
+})
+
+async function loadCategories(): Promise<void> {
+  loading.set(true)
+  loadError.set('')
+  try {
+    const data = await dashboardApi<CategoryIndexResponse>('/api/dashboard/commerce/categories')
+    records.set(Array.isArray(data.records) ? data.records : [])
+    summary.set(data.summary ?? { ...emptySummary })
+    page.set(Math.min(page(), Math.max(1, Math.ceil((data.records?.length || 0) / pageSize))))
+  }
+  catch (error) {
+    loadError.set('Product categories could not be loaded.')
+    pushToast('error', 'Could not load product categories', {
+      detail: error instanceof Error ? error.message : String(error),
+    })
+  }
+  finally {
+    loading.set(false)
+  }
+}
+
+function openAdd(): void {
+  dialogMode.set('add')
+  editingRecord.set(null)
+  validationErrors.set({})
+  dialogOpen.set(true)
+}
+
+function openEdit(record: CommerceCategoryRecord): void {
+  detailsRecord.set(null)
+  dialogMode.set('edit')
+  editingRecord.set(record)
+  validationErrors.set({})
+  dialogOpen.set(true)
+}
+
+function closeDialog(): void {
+  if (saving())
+    return
+  dialogOpen.set(false)
+  editingRecord.set(null)
+  validationErrors.set({})
+}
+
+async function saveCategory(payload: CategoryWritePayload): Promise<void> {
+  const current = editingRecord()
+  const editing = dialogMode() === 'edit' && current !== null
+  saving.set(true)
+  validationErrors.set({})
+  try {
+    await dashboardApi(editing ? `/api/dashboard/commerce/categories/${current.id}` : '/api/dashboard/commerce/categories', {
+      method: editing ? 'PATCH' : 'POST',
+      body: payload,
+    })
+    dialogOpen.set(false)
+    editingRecord.set(null)
+    pushToast('success', editing ? 'Category updated' : 'Category added')
+    await loadCategories()
+  }
+  catch (error) {
+    if (error instanceof DashboardApiError)
+      validationErrors.set(error.fields ?? {})
+    pushToast('error', 'Could not save category', {
+      detail: error instanceof Error ? error.message : String(error),
+    })
+  }
+  finally {
+    saving.set(false)
+  }
+}
+
+function openDetails(record: CommerceCategoryRecord): void {
+  detailsRecord.set(record)
+}
+
+function closeDetails(): void {
+  detailsRecord.set(null)
+}
+
+function openDelete(record: CommerceCategoryRecord): void {
+  deletingRecord.set(record)
+}
+
+function closeDelete(): void {
+  if (!deleting())
+    deletingRecord.set(null)
+}
+
+async function deleteCategory(): Promise<void> {
+  const current = deletingRecord()
+  if (!current)
+    return
+  deleting.set(true)
+  try {
+    await dashboardApi(`/api/dashboard/commerce/categories/${current.id}`, { method: 'DELETE' })
+    deletingRecord.set(null)
+    detailsRecord.set(null)
+    pushToast('success', 'Category deleted', { detail: current.name })
+    await loadCategories()
+  }
+  catch (error) {
+    pushToast('error', 'Could not delete category', {
+      detail: error instanceof Error ? error.message : String(error),
+    })
+  }
+  finally {
+    deleting.set(false)
+  }
+}
+
+function previousPage(): void {
+  page.set(Math.max(1, page() - 1))
+}
+
+function nextPage(): void {
+  page.set(Math.min(pageCount(), page() + 1))
+}
+
+onMount(() => {
+  void loadCategories()
+})
+</script>
+
+<div class="space-y-6">
+  <header class="flex flex-col gap-4 sm:flex-row sm:items-start sm:justify-between">
+    <div>
+      <h1 class="font-bold text-2xl text-gray-900 dark:text-white">Product Categories</h1>
+      <p class="mt-1 text-gray-500 text-sm dark:text-neutral-400">Manage the native Category hierarchy, display order, and storefront availability.</p>
+    </div>
+    <div class="flex flex-wrap gap-2">
+      <Button variant="secondary" :loading="loading()" @click="loadCategories()"><span :if="!loading()" class="h-4 w-4 i-hugeicons-refresh"></span>Refresh</Button>
+      <Button tag="a" variant="secondary" :href="exportHref()" :download="'product-categories-' + new Date().toISOString().slice(0, 10) + '.csv'"><span class="h-4 w-4 i-hugeicons-download-04"></span>Export filtered</Button>
+      <Button @click="openAdd()"><span class="h-4 w-4 i-hugeicons-add-01"></span>Add category</Button>
+    </div>
+  </header>
+
+  <div :if="loadError()" class="p-4 text-red-700 text-sm dark:text-red-300 bg-red-50 dark:bg-red-950/30 border border-red-200 rounded-lg dark:border-red-900">{{ loadError() }}</div>
+
+  <section aria-label="Product category metrics" class="grid gap-3 grid-cols-2 lg:grid-cols-4">
+    <template :for="item in metricCards()" :key="item.label">
+      <article class="p-4 bg-white dark:bg-neutral-800 border border-gray-200 rounded-lg dark:border-neutral-700">
+        <p class="text-gray-500 text-xs dark:text-neutral-400">{{ item.label }}</p>
+        <p class="mt-2 font-semibold text-2xl text-gray-900 dark:text-white">{{ item.value }}</p>
+        <p class="mt-1 text-gray-400 text-xs dark:text-neutral-500">{{ item.detail }}</p>
+      </article>
+    </template>
+  </section>
+
+  <CommerceCategoryHierarchy :records="records()" />
+
+  <section class="space-y-3">
+    <div class="grid gap-3 grid-cols-1 sm:grid-cols-2 xl:grid-cols-5">
+      <label class="relative sm:col-span-2">
+        <span class="sr-only">Search product categories</span>
+        <span class="flex absolute inset-y-0 left-0 items-center pl-3 text-gray-400 pointer-events-none"><span class="h-4 w-4 i-hugeicons-search-01"></span></span>
+        <input x-model="search" type="search" placeholder="Search names, slugs, or descriptions" class="pl-9 pr-3 py-2 w-full text-gray-900 text-sm dark:text-white bg-white dark:bg-neutral-800 border border-gray-300 rounded-md dark:border-neutral-700" />
+      </label>
+      <label><span class="sr-only">Category availability</span><select x-model="activeFilter" class="px-3 py-2 w-full text-gray-900 text-sm dark:text-white bg-white dark:bg-neutral-800 border border-gray-300 rounded-md dark:border-neutral-700"><option value="all">Any availability</option><option value="active">Active</option><option value="inactive">Inactive</option></select></label>
+      <label><span class="sr-only">Category hierarchy</span><select x-model="hierarchyFilter" class="px-3 py-2 w-full text-gray-900 text-sm dark:text-white bg-white dark:bg-neutral-800 border border-gray-300 rounded-md dark:border-neutral-700"><option value="all">Any hierarchy</option><option value="root">Root categories</option><option value="child">Child categories</option></select></label>
+      <label><span class="sr-only">Sort product categories</span><select x-model="sort" class="px-3 py-2 w-full text-gray-900 text-sm dark:text-white bg-white dark:bg-neutral-800 border border-gray-300 rounded-md dark:border-neutral-700"><option value="order">Display order</option><option value="name">Name</option><option value="newest">Newest</option></select></label>
+    </div>
+
+    <div class="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+      <p class="text-gray-500 text-sm dark:text-neutral-400">{{ matchingLabel() }}</p>
+      <div class="flex gap-2 items-center">
+        <Button variant="secondary" size="sm" :disabled="page() <= 1" @click="previousPage()">Previous</Button>
+        <span class="text-gray-500 text-sm dark:text-neutral-400">Page {{ Math.min(page(), pageCount()) }} of {{ pageCount() }}</span>
+        <Button variant="secondary" size="sm" :disabled="page() >= pageCount()" @click="nextPage()">Next</Button>
+      </div>
+    </div>
+
+    <CommerceCategoriesTable :records="visibleRecords()" :all-records="records()" :loading="loading()" @view="openDetails" @edit="openEdit" @delete="openDelete" />
+  </section>
+</div>
+
+<CommerceCategoryDialog :open="dialogOpen()" :mode="dialogMode()" :record="editingRecord()" :records="records()" :busy="saving()" :errors="validationErrors()" @submit="saveCategory" @close="closeDialog()" />
+<CommerceCategoryDetailsDialog :open="Boolean(detailsRecord())" :record="detailsRecord()" :records="records()" @edit="openEdit" @delete="openDelete" @close="closeDetails()" />
+<CommerceCategoryDeleteDialog :open="Boolean(deletingRecord())" :record="deletingRecord()" :busy="deleting()" @confirm="deleteCategory()" @close="closeDelete()" />

package/resources/components/Dashboard/Commerce/CommerceCategoriesTable.stx

@@ -0,0 +1,43 @@
+<script client>
+import type { CommerceCategoryRecord } from '../../../../app/Actions/Dashboard/Commerce/commerce-category-records'
+
+const records = useReactiveProp('records', [] as CommerceCategoryRecord[])
+const allRecords = useReactiveProp('allRecords', [] as CommerceCategoryRecord[])
+const loading = useReactiveProp('loading', false)
+const emit = defineEmits<{
+  view: [record: CommerceCategoryRecord]
+  edit: [record: CommerceCategoryRecord]
+  delete: [record: CommerceCategoryRecord]
+}>()
+
+function parentName(record: CommerceCategoryRecord): string {
+  if (!record.parentCategoryId)
+    return 'Root category'
+  return allRecords().find(parent => parent.id === record.parentCategoryId)?.name || 'Unknown parent'
+}
+</script>
+
+<div class="overflow-hidden bg-white dark:bg-neutral-800 border border-gray-200 rounded-lg dark:border-neutral-700">
+  <div :if="loading()" class="flex items-center justify-center py-16 text-gray-500 text-sm dark:text-neutral-400"><span class="mr-2 h-4 w-4 animate-spin i-hugeicons-loading-03"></span>Loading categories</div>
+  <div :if="!loading() && records().length === 0" class="py-16 text-center">
+    <div class="mb-3 mx-auto h-8 w-8 text-gray-400 i-hugeicons-tags"></div>
+    <p class="font-medium text-gray-900 text-sm dark:text-white">No product categories found</p>
+    <p class="mt-1 text-gray-500 text-xs dark:text-neutral-400">Adjust the filters or add a native Category record.</p>
+  </div>
+  <div :if="!loading() && records().length > 0" class="overflow-x-auto">
+    <table class="min-w-full divide-gray-200 divide-y dark:divide-neutral-700">
+      <thead class="bg-gray-50 dark:bg-neutral-900/60"><tr><th class="px-4 py-3 font-semibold text-gray-500 text-left text-xs tracking-wide uppercase dark:text-neutral-400">Category</th><th class="px-4 py-3 font-semibold text-gray-500 text-left text-xs tracking-wide uppercase dark:text-neutral-400">Hierarchy</th><th class="px-4 py-3 font-semibold text-gray-500 text-left text-xs tracking-wide uppercase dark:text-neutral-400">Display order</th><th class="px-4 py-3 font-semibold text-gray-500 text-left text-xs tracking-wide uppercase dark:text-neutral-400">Availability</th><th class="px-4 py-3"><span class="sr-only">Actions</span></th></tr></thead>
+      <tbody class="divide-gray-100 divide-y dark:divide-neutral-700">
+        <template :for="record in records()" :key="record.id">
+          <tr class="hover:bg-gray-50/70 dark:hover:bg-neutral-900/40">
+            <td class="px-4 py-3"><div class="flex gap-3 items-center"><span class="flex items-center justify-center shrink-0 h-9 w-9 font-semibold text-blue-700 text-sm dark:text-blue-300 bg-blue-50 dark:bg-blue-950/40 rounded-md">{{ record.name.slice(0, 1).toUpperCase() }}</span><div class="min-w-0"><Button variant="ghost" size="xs" @click="emit('view', record)">{{ record.name }}</Button><p class="mt-1 max-w-96 text-gray-400 text-xs truncate dark:text-neutral-500">{{ record.description || record.slug }}</p></div></div></td>
+            <td class="px-4 py-3"><p class="text-gray-700 text-sm dark:text-neutral-200">{{ parentName(record) }}</p><p class="mt-1 font-mono text-gray-400 text-xs dark:text-neutral-500">{{ record.slug }}</p></td>
+            <td class="px-4 py-3 font-mono text-gray-700 text-sm dark:text-neutral-200">{{ record.displayOrder }}</td>
+            <td class="px-4 py-3"><span :class="'inline-flex px-2 py-1 font-medium text-xs rounded-full ' + (record.isActive ? 'bg-green-50 text-green-700 dark:bg-green-950/40 dark:text-green-300' : 'bg-gray-100 text-gray-600 dark:bg-neutral-700 dark:text-neutral-300')">{{ record.isActive ? 'Active' : 'Inactive' }}</span></td>
+            <td class="px-4 py-3"><div class="flex gap-1 justify-end"><Button variant="ghost" size="sm" iconOnly :ariaLabel="'View ' + record.name" @click="emit('view', record)"><span class="block h-4 w-4 text-blue-500 i-hugeicons-view"></span></Button><Button variant="ghost" size="sm" iconOnly :ariaLabel="'Edit ' + record.name" @click="emit('edit', record)"><span class="block h-4 w-4 text-blue-500 i-hugeicons-edit-02"></span></Button><Button variant="ghost" size="sm" iconOnly :ariaLabel="'Delete ' + record.name" @click="emit('delete', record)"><span class="block h-4 w-4 text-red-500 i-hugeicons-delete-02"></span></Button></div></td>
+          </tr>
+        </template>
+      </tbody>
+    </table>
+  </div>
+</div>

package/resources/components/Dashboard/Commerce/CommerceCategoryDeleteDialog.stx

@@ -0,0 +1,17 @@
+<script client>
+import type { CommerceCategoryRecord } from '../../../../app/Actions/Dashboard/Commerce/commerce-category-records'
+
+const open = useReactiveProp('open', false)
+const record = useReactiveProp('record', null as CommerceCategoryRecord | null)
+const busy = useReactiveProp('busy', false)
+const emit = defineEmits()
+</script>
+
+<div :if="open()" class="flex fixed inset-0 z-50 items-center justify-center p-4 dashboard-modal-layer">
+  <button type="button" aria-label="Close delete category dialog" class="absolute inset-0 bg-black/45" @click="emit('close')"></button>
+  <section role="dialog" aria-modal="true" aria-labelledby="category-delete-title" class="relative p-6 max-w-md w-full bg-white dark:bg-neutral-800 border border-gray-200 rounded-xl dark:border-neutral-700 shadow-xl">
+    <h2 id="category-delete-title" class="font-semibold text-gray-900 text-lg dark:text-white">Delete category</h2>
+    <p class="mt-2 text-gray-500 text-sm dark:text-neutral-400">Delete "{{ record()?.name || 'Unnamed category' }}" permanently? Linked products and child categories may prevent deletion.</p>
+    <footer class="flex gap-2 justify-end mt-6"><Button variant="secondary" :disabled="busy()" @click="emit('close')">Cancel</Button><Button variant="danger" :loading="busy()" @click="emit('confirm')">Delete category</Button></footer>
+  </section>
+</div>

package/resources/components/Dashboard/Commerce/CommerceCategoryDetailsDialog.stx

@@ -0,0 +1,54 @@
+<script client>
+import type { CommerceCategoryRecord } from '../../../../app/Actions/Dashboard/Commerce/commerce-category-records'
+
+const open = useReactiveProp('open', false)
+const record = useReactiveProp('record', null as CommerceCategoryRecord | null)
+const records = useReactiveProp('records', [] as CommerceCategoryRecord[])
+const emit = defineEmits()
+
+function parentName(): string {
+  const parentId = record()?.parentCategoryId
+  if (!parentId)
+    return 'Root category'
+  return records().find(candidate => candidate.id === parentId)?.name || 'Unknown parent'
+}
+
+function children(): CommerceCategoryRecord[] {
+  const currentId = record()?.id
+  return currentId ? records().filter(candidate => candidate.parentCategoryId === currentId) : []
+}
+
+function editRecord(): void {
+  const current = record()
+  if (!current)
+    return
+  emit('edit', current)
+  emit('close')
+}
+
+function deleteRecord(): void {
+  const current = record()
+  if (!current)
+    return
+  emit('delete', current)
+  emit('close')
+}
+</script>
+
+<div :if="open()" class="flex fixed inset-0 z-50 items-center justify-center p-4 dashboard-modal-layer">
+  <button type="button" aria-label="Close category details" class="absolute inset-0 bg-black/45" @click="emit('close')"></button>
+  <section role="dialog" aria-modal="true" aria-labelledby="category-details-title" class="relative max-w-xl w-full bg-white dark:bg-neutral-800 border border-gray-200 rounded-xl dark:border-neutral-700 shadow-xl">
+    <div class="p-6">
+      <div class="flex gap-4 items-start justify-between"><div><h2 id="category-details-title" class="font-semibold text-gray-900 text-lg dark:text-white">{{ record()?.name || 'Category' }}</h2><p class="mt-1 font-mono text-gray-400 text-sm dark:text-neutral-500">{{ record()?.slug || 'No slug' }}</p></div><span class="px-2 py-1 font-semibold text-gray-700 text-xs dark:text-neutral-200 bg-gray-100 dark:bg-neutral-700 rounded-full">{{ record()?.isActive ? 'Active' : 'Inactive' }}</span></div>
+      <p class="mt-5 text-gray-600 text-sm whitespace-pre-wrap dark:text-neutral-300">{{ record()?.description || 'No description recorded.' }}</p>
+      <dl class="grid gap-4 grid-cols-2 mt-6">
+        <div><dt class="text-gray-400 text-xs dark:text-neutral-500">Parent</dt><dd class="mt-1 text-gray-900 text-sm dark:text-white">{{ parentName() }}</dd></div>
+        <div><dt class="text-gray-400 text-xs dark:text-neutral-500">Display order</dt><dd class="mt-1 font-mono text-gray-900 text-sm dark:text-white">{{ record()?.displayOrder || 0 }}</dd></div>
+        <div><dt class="text-gray-400 text-xs dark:text-neutral-500">Direct children</dt><dd class="mt-1 text-gray-900 text-sm dark:text-white">{{ children().length }}</dd></div>
+        <div><dt class="text-gray-400 text-xs dark:text-neutral-500">Record ID</dt><dd class="mt-1 font-mono text-gray-900 text-sm dark:text-white">{{ record()?.id || 'Not recorded' }}</dd></div>
+        <div class="col-span-2"><dt class="text-gray-400 text-xs dark:text-neutral-500">Image URL</dt><dd class="mt-1 break-all text-gray-900 text-sm dark:text-white">{{ record()?.imageUrl || 'Not configured' }}</dd></div>
+      </dl>
+    </div>
+    <footer class="flex gap-2 justify-between px-6 py-4 bg-gray-50 dark:bg-neutral-900/50 border-gray-200 border-t dark:border-neutral-700"><Button variant="danger" @click="deleteRecord()">Delete</Button><div class="flex gap-2"><Button variant="secondary" @click="emit('close')">Close</Button><Button @click="editRecord()">Edit category</Button></div></footer>
+  </section>
+</div>

package/resources/components/Dashboard/Commerce/CommerceCategoryDialog.stx

@@ -0,0 +1,146 @@
+<script client>
+import type { CommerceCategoryRecord } from '../../../../app/Actions/Dashboard/Commerce/commerce-category-records'
+
+const open = useReactiveProp('open', false)
+const mode = useReactiveProp('mode', 'add')
+const record = useReactiveProp('record', null as CommerceCategoryRecord | null)
+const records = useReactiveProp('records', [] as CommerceCategoryRecord[])
+const busy = useReactiveProp('busy', false)
+const errors = useReactiveProp('errors', {} as Record<string, string>)
+const emit = defineEmits()
+const name = state('')
+const description = state('')
+const slug = state('')
+const imageUrl = state('')
+const isActive = state(true)
+const parentCategoryId = state('')
+const displayOrder = state('0')
+let hydrationKey = ''
+let slugTouched = false
+
+function slugify(value: string): string {
+  return value
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036F]/g, '')
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+effect(() => {
+  if (!open()) {
+    hydrationKey = ''
+    return
+  }
+  const current = record()
+  const key = `${mode()}:${current?.id || 'new'}`
+  if (hydrationKey === key)
+    return
+  hydrationKey = key
+  name.set(current?.name || '')
+  description.set(current?.description || '')
+  slug.set(current?.slug || '')
+  imageUrl.set(current?.imageUrl || '')
+  isActive.set(current?.isActive ?? true)
+  parentCategoryId.set(current?.parentCategoryId || '')
+  displayOrder.set(String(current?.displayOrder ?? 0))
+  slugTouched = Boolean(current?.slug)
+})
+
+effect(() => {
+  if (!open() || slugTouched)
+    return
+  slug.set(slugify(name()))
+})
+
+function markSlugTouched(): void {
+  slugTouched = true
+}
+
+function normalizeSlug(): void {
+  const normalized = slugify(slug())
+  if (normalized !== slug())
+    slug.set(normalized)
+}
+
+function forbiddenParentIds(): Set<string> {
+  const currentId = record()?.id
+  if (!currentId)
+    return new Set()
+  const forbidden = new Set([currentId])
+  let changed = true
+  while (changed) {
+    changed = false
+    for (const candidate of records()) {
+      if (candidate.parentCategoryId && forbidden.has(candidate.parentCategoryId) && !forbidden.has(candidate.id)) {
+        forbidden.add(candidate.id)
+        changed = true
+      }
+    }
+  }
+  return forbidden
+}
+
+function parentOptions(): CommerceCategoryRecord[] {
+  const forbidden = forbiddenParentIds()
+  return records()
+    .filter(candidate => !forbidden.has(candidate.id))
+    .sort((left, right) => left.name.localeCompare(right.name))
+}
+
+function valid(): boolean {
+  return Boolean(
+    name().trim()
+    && slug().trim()
+    && Number.isFinite(Number(displayOrder()))
+    && Number(displayOrder()) >= 0
+  )
+}
+
+function submit(): void {
+  if (!valid())
+    return
+  emit('submit', {
+    name: name().trim(),
+    description: description().trim(),
+    slug: slugify(slug()),
+    imageUrl: imageUrl().trim(),
+    isActive: isActive(),
+    parentCategoryId: parentCategoryId(),
+    displayOrder: Number(displayOrder()),
+  })
+}
+
+function errorMessages(): string[] {
+  return Object.entries(errors()).map(([field, message]) => {
+    const label = field.replace(/([a-z])([A-Z])/g, '$1 $2').replaceAll('_', ' ')
+    return `${label.charAt(0).toUpperCase()}${label.slice(1)}: ${message}`
+  })
+}
+</script>
+
+<div :if="open()" class="flex fixed inset-0 z-50 items-center justify-center p-4 dashboard-modal-layer">
+  <button type="button" aria-label="Close category dialog" class="absolute inset-0 bg-black/45" @click="emit('close')"></button>
+  <section role="dialog" aria-modal="true" aria-labelledby="category-dialog-title" class="overflow-y-auto relative max-h-[90dvh] max-w-2xl w-full bg-white dark:bg-neutral-800 border border-gray-200 rounded-xl dark:border-neutral-700 shadow-xl">
+    <form @submit.prevent="submit">
+      <div class="p-6">
+        <h2 id="category-dialog-title" class="font-semibold text-gray-900 text-lg dark:text-white">{{ mode() === 'edit' ? 'Edit category' : 'Add category' }}</h2>
+        <p class="mt-1 text-gray-500 text-sm dark:text-neutral-400">Store hierarchy fields declared by the Category model.</p>
+        <ul :if="errorMessages().length > 0" class="mt-5 p-3 space-y-1 text-red-700 text-sm dark:text-red-300 bg-red-50 dark:bg-red-950/30 border border-red-200 rounded-lg dark:border-red-900">
+          <template :for="message in errorMessages()" :key="message"><li>{{ message }}</li></template>
+        </ul>
+        <div class="grid gap-4 grid-cols-1 sm:grid-cols-2 mt-5">
+          <label class="block"><span class="font-medium text-gray-700 text-sm dark:text-neutral-200">Name</span><input x-model="name" type="text" maxlength="50" required class="mt-1 px-3 py-2 w-full text-gray-900 text-sm dark:text-white bg-white dark:bg-neutral-900 border border-gray-300 rounded-md dark:border-neutral-700" /></label>
+          <label class="block"><span class="font-medium text-gray-700 text-sm dark:text-neutral-200">Slug</span><input x-model="slug" type="text" required spellcheck="false" class="mt-1 px-3 py-2 w-full font-mono text-gray-900 text-sm dark:text-white bg-white dark:bg-neutral-900 border border-gray-300 rounded-md dark:border-neutral-700" @input="markSlugTouched" @blur="normalizeSlug" /></label>
+          <label class="block sm:col-span-2"><span class="font-medium text-gray-700 text-sm dark:text-neutral-200">Description</span><textarea x-model="description" rows="3" class="mt-1 px-3 py-2 w-full text-gray-900 text-sm dark:text-white bg-white dark:bg-neutral-900 border border-gray-300 rounded-md dark:border-neutral-700"></textarea></label>
+          <label class="block sm:col-span-2"><span class="font-medium text-gray-700 text-sm dark:text-neutral-200">Image URL</span><input x-model="imageUrl" type="text" placeholder="Optional persisted asset URL" class="mt-1 px-3 py-2 w-full text-gray-900 text-sm dark:text-white bg-white dark:bg-neutral-900 border border-gray-300 rounded-md dark:border-neutral-700" /><span class="block mt-1 text-gray-400 text-xs dark:text-neutral-500">Use a stored asset URL. File uploads belong to the native storage workflow.</span></label>
+          <label class="block"><span class="font-medium text-gray-700 text-sm dark:text-neutral-200">Parent category</span><select x-model="parentCategoryId" class="mt-1 px-3 py-2 w-full text-gray-900 text-sm dark:text-white bg-white dark:bg-neutral-900 border border-gray-300 rounded-md dark:border-neutral-700"><option value="">Root category</option><template :for="option in parentOptions()" :key="option.id"><option :value="option.id">{{ option.name }}</option></template></select></label>
+          <label class="block"><span class="font-medium text-gray-700 text-sm dark:text-neutral-200">Display order</span><input x-model="displayOrder" type="number" min="0" step="1" required class="mt-1 px-3 py-2 w-full text-gray-900 text-sm dark:text-white bg-white dark:bg-neutral-900 border border-gray-300 rounded-md dark:border-neutral-700" /></label>
+          <label class="flex gap-3 items-center sm:col-span-2 p-3 border border-gray-200 rounded-lg dark:border-neutral-700"><input x-model="isActive" type="checkbox" class="h-4 w-4 text-blue-600 border-gray-300 rounded" /><span><span class="block font-medium text-gray-700 text-sm dark:text-neutral-200">Active in the storefront</span><span class="block mt-0.5 text-gray-400 text-xs dark:text-neutral-500">Availability is independent from the hierarchy.</span></span></label>
+        </div>
+      </div>
+      <footer class="flex gap-2 justify-end px-6 py-4 bg-gray-50 dark:bg-neutral-900/50 border-gray-200 border-t dark:border-neutral-700"><Button variant="secondary" :disabled="busy()" @click="emit('close')">Cancel</Button><Button type="submit" :loading="busy()" :disabled="!valid()">{{ mode() === 'edit' ? 'Save category' : 'Add category' }}</Button></footer>
+    </form>
+  </section>
+</div>

package/resources/components/Dashboard/Commerce/CommerceCategoryHierarchy.stx

@@ -0,0 +1,35 @@
+<script client>
+import type { CommerceCategoryRecord } from '../../../../app/Actions/Dashboard/Commerce/commerce-category-records'
+
+const records = useReactiveProp('records', [] as CommerceCategoryRecord[])
+
+function roots(): CommerceCategoryRecord[] {
+  return records()
+    .filter(record => !record.parentCategoryId)
+    .sort((left, right) => left.displayOrder - right.displayOrder || left.name.localeCompare(right.name))
+}
+
+function childCount(id: string): number {
+  return records().filter(record => record.parentCategoryId === id).length
+}
+
+function childLabel(id: string): string {
+  const count = childCount(id)
+  return `${count} ${count === 1 ? 'child' : 'children'}`
+}
+</script>
+
+<section aria-label="Category hierarchy" class="p-4 bg-white dark:bg-neutral-800 border border-gray-200 rounded-lg dark:border-neutral-700">
+  <div class="flex gap-4 items-center justify-between">
+    <div><h2 class="font-semibold text-gray-900 text-sm dark:text-white">Root hierarchy</h2><p class="mt-1 text-gray-400 text-xs dark:text-neutral-500">Ordered by storefront display order.</p></div>
+    <span class="text-gray-500 text-xs dark:text-neutral-400">{{ roots().length }} roots</span>
+  </div>
+  <div :if="roots().length === 0" class="mt-4 text-gray-500 text-sm dark:text-neutral-400">No root categories recorded.</div>
+  <div :if="roots().length > 0" class="grid gap-2 grid-cols-1 sm:grid-cols-2 xl:grid-cols-5 mt-4">
+    <template :for="record in roots().slice(0, 10)" :key="record.id">
+      <article class="p-3 border border-gray-100 rounded-lg dark:border-neutral-700">
+        <div class="flex gap-3 items-center"><span class="flex items-center justify-center shrink-0 h-8 w-8 font-semibold text-blue-700 text-xs dark:text-blue-300 bg-blue-50 dark:bg-blue-950/40 rounded-md">{{ record.name.slice(0, 1).toUpperCase() }}</span><div class="min-w-0"><p class="font-medium text-gray-900 text-sm truncate dark:text-white">{{ record.name }}</p><p class="text-gray-400 text-xs dark:text-neutral-500">{{ childLabel(record.id) }} · order {{ record.displayOrder }}</p></div></div>
+      </article>
+    </template>
+  </div>
+</section>

package/resources/components/Dashboard/Commerce/CommerceCouponBreakdown.stx

@@ -0,0 +1,34 @@
+<script client>
+import type { CouponRecord } from '../../../../app/Actions/Dashboard/Commerce/coupon-records'
+
+const records = useReactiveProp('records', [] as CouponRecord[])
+
+function statuses(): Array<{ label: string, count: number, color: string }> {
+  return [
+    { label: 'Active', count: records().filter(record => record.status === 'Active').length, color: 'bg-emerald-500' },
+    { label: 'Scheduled', count: records().filter(record => record.status === 'Scheduled').length, color: 'bg-blue-500' },
+    { label: 'Expired', count: records().filter(record => record.status === 'Expired').length, color: 'bg-gray-400' },
+  ]
+}
+
+function width(count: number): string {
+  return `${records().length ? Math.round((count / records().length) * 100) : 0}%`
+}
+
+function discountTypes(): Array<{ label: string, count: number }> {
+  return [
+    { label: 'Percentage', count: records().filter(record => record.discountType === 'percentage').length },
+    { label: 'Fixed amount', count: records().filter(record => record.discountType === 'fixed_amount').length },
+  ]
+}
+
+function mostUsed(): CouponRecord[] {
+  return [...records()].sort((left, right) => right.usageCount - left.usageCount || left.code.localeCompare(right.code)).slice(0, 5)
+}
+</script>
+
+<section aria-label="Coupon breakdowns" class="grid gap-3 lg:grid-cols-3">
+  <article class="p-4 bg-white dark:bg-neutral-800 border border-gray-200 rounded-lg dark:border-neutral-700"><h2 class="font-semibold text-gray-900 text-sm dark:text-white">Status distribution</h2><div class="mt-4 space-y-3"><template :for="item in statuses()" :key="item.label"><div><div class="flex justify-between text-xs"><span class="text-gray-500 dark:text-neutral-400">{{ item.label }}</span><span class="font-mono text-gray-700 dark:text-neutral-200">{{ item.count }}</span></div><div class="mt-1 h-1.5 bg-gray-100 dark:bg-neutral-700 rounded-full"><div :class="'h-full rounded-full ' + item.color" :style="'width: ' + width(item.count)"></div></div></div></template></div></article>
+  <article class="p-4 bg-white dark:bg-neutral-800 border border-gray-200 rounded-lg dark:border-neutral-700"><h2 class="font-semibold text-gray-900 text-sm dark:text-white">Discount types</h2><dl class="mt-3 divide-gray-100 divide-y dark:divide-neutral-700"><template :for="item in discountTypes()" :key="item.label"><div class="flex items-center justify-between py-3"><dt class="text-gray-500 text-sm dark:text-neutral-400">{{ item.label }}</dt><dd class="font-mono text-gray-900 text-sm dark:text-white">{{ item.count }}</dd></div></template></dl></article>
+  <article class="p-4 bg-white dark:bg-neutral-800 border border-gray-200 rounded-lg dark:border-neutral-700"><h2 class="font-semibold text-gray-900 text-sm dark:text-white">Most redeemed</h2><p :if="mostUsed().length === 0" class="mt-4 text-gray-500 text-sm dark:text-neutral-400">No coupon usage recorded.</p><ol :else class="mt-3 divide-gray-100 divide-y dark:divide-neutral-700"><template :for="record in mostUsed()" :key="record.id"><li class="flex items-center justify-between py-2"><span class="font-mono text-gray-600 text-sm truncate dark:text-neutral-300">{{ record.code }}</span><span class="ml-3 font-mono text-gray-900 text-sm dark:text-white">{{ record.usageCount.toLocaleString() }}</span></li></template></ol></article>
+</section>