@awes-io/ui 2.142.3 → 2.144.0

package/docs/guides/page-patterns/list-pages.md

@@ -0,0 +1,1242 @@
+# List Page Patterns
+
+Complete guide to building list pages with tables, search, and actions using AwPage and AwTableBuilder.
+
+## When to Use AwPage
+
+Use `AwPage` for:
+- **List pages** - Display collections of items in tables
+- **Dashboards** - Overview pages with metrics and data
+- **Index pages** - Entry points to sections with navigation
+
+**Key characteristics:**
+- Shows aside menu by default
+- Simple title prop
+- Automatic integration with menu system
+- Best for browsing and navigation
+
+## Basic List Page
+
+### Minimal Example
+
+```markup
+<template>
+    <AwPage title="Customers">
+        <AwTableBuilder
+            :collection="customers"
+            @click:row="viewCustomer"
+        >
+            <AwTableCol field="name" title="Name" />
+            <AwTableCol field="email" title="Email" />
+            <AwTableCol field="phone" title="Phone" />
+        </AwTableBuilder>
+    </AwPage>
+</template>
+
+<script>
+import Customers from '~/collections/Customers'
+
+export default {
+    middleware: 'auth',
+
+    data() {
+        return {
+            customers: new Customers([], {
+                shop_uuid: this.$route.params.shop_uuid
+            })
+        }
+    },
+
+    methods: {
+        viewCustomer(customer) {
+            this.$router.push(`/${this.$route.params.shop_uuid}/customers/${customer.id}`)
+        }
+    }
+}
+</script>
+```
+
+**What happens:**
+1. ✅ AwTableBuilder automatically calls `customers.fetch()` on mount
+2. ✅ No manual `fetch()` or `mounted()` needed
+3. ✅ Collection handles pagination automatically
+4. ✅ Loading states managed internally
+5. ✅ Row click navigates to detail page
+
+**⚠️ Important: Don't use v-if for loading**
+
+```markup
+<!-- ❌ BAD - Prevents AwTableBuilder from mounting and fetching -->
+<template>
+    <AwPage title="Customers">
+        <div v-if="loading">Loading...</div>
+        <AwTableBuilder v-else :collection="customers">
+            <!-- Never mounts if loading=true initially -->
+        </AwTableBuilder>
+    </AwPage>
+</template>
+
+<!-- ✅ GOOD - Let AwTableBuilder handle its own loading -->
+<template>
+    <AwPage title="Customers">
+        <AwTableBuilder :collection="customers">
+            <!-- Mounts immediately, shows internal loading state -->
+        </AwTableBuilder>
+    </AwPage>
+</template>
+```
+
+## Header Action Buttons
+
+**⚠️ Important: Create buttons should not be in menu items**
+
+Create actions should only appear on list pages using `AwPageMenuButtons` and in empty states. Do not add create pages to menu navigation items.
+
+### Single CTA Button
+
+For navigation to create pages, use `href` instead of `listeners`:
+
+```markup
+<template>
+    <AwPage title="Templates">
+        <template #buttons>
+            <AwPageMenuButtons
+                :items="[{
+                    text: 'Create Template',
+                    icon: 'awesio/plus',
+                    cta: true,
+                    href: '/templates/create'
+                }]"
+            />
+        </template>
+
+        <AwTableBuilder :collection="templates">
+            <!-- Table columns -->
+        </AwTableBuilder>
+    </AwPage>
+</template>
+```
+
+### Multiple Action Buttons
+
+```markup
+<template #buttons>
+    <AwPageMenuButtons
+        :items="[
+            {
+                text: 'Export',
+                icon: 'awesio/download',
+                color: 'mono',
+                listeners: { click: exportData }
+            },
+            {
+                text: 'Import',
+                icon: 'awesio/upload',
+                color: 'mono',
+                listeners: { click: importData }
+            },
+            {
+                text: 'Create',
+                icon: 'awesio/plus',
+                cta: true,
+                listeners: { click: createItem }
+            }
+        ]"
+    />
+</template>
+```
+
+**Button Configuration:**
+- `text` - Button label (required)
+- `icon` - Icon name (optional)
+- `color` - `'mono'`, `'primary'`, `'accent'` (default: 'mono')
+- `cta` - Makes button prominent with accent color (default: false)
+- `href` - Navigation URL (use for navigation, preferred over listeners)
+- `listeners` - Event handlers object `{ click: handler }` (use only for non-navigation actions)
+
+**Button Ordering:**
+- Secondary actions (Export, Import) first
+- Primary CTA (Create, Add) last
+- CTA buttons automatically styled with accent color
+
+## Search Integration
+
+### Basic Search
+
+```markup
+<template>
+    <AwPage title="Customers">
+        <!-- Search bar -->
+        <div class="flex justify-end mb-6">
+            <AwSearch class="w-full lg:w-auto" />
+        </div>
+
+        <!-- Table watches for search param changes -->
+        <AwTableBuilder
+            :collection="customers"
+            :watch-params="['search']"
+        >
+            <AwTableCol field="name" title="Name" />
+            <AwTableCol field="email" title="Email" />
+        </AwTableBuilder>
+    </AwPage>
+</template>
+```
+
+**How it works:**
+1. ✅ AwSearch updates `$route.query.search`
+2. ✅ AwTableBuilder watches `search` param via `:watch-params`
+3. ✅ Table automatically refetches when search changes
+4. ✅ Collection receives search param in API request
+
+### Search with Filters
+
+When using `AwFilterSelect` components that sync with URL parameters, use `AwFilterChosen` to display active filters:
+
+```markup
+<template>
+    <AwPage title="Users">
+        <div class="flex flex-wrap gap-4 mb-6">
+            <AwFilterSelect
+                param="is_active"
+                label="Status"
+                :options="statusOptions"
+                single
+            />
+            <AwFilterSelect
+                param="permissions"
+                label="Permissions"
+                :options="permissionOptions"
+            />
+            <AwSearch class="ml-auto" />
+        </div>
+
+        <AwFilterChosen :watch-params="['is_active', 'permissions']">
+            <template #is_active="{ value }">
+                {{ getStatusLabel(value) }}
+            </template>
+            <template #permissions="{ value }">
+                {{ getPermissionLabel(value) }}
+            </template>
+        </AwFilterChosen>
+
+        <AwTableBuilder
+            :collection="users"
+            :watch-params="['search', 'is_active', 'permissions']"
+        >
+            <AwTableCol field="first_name" title="First Name" />
+            <AwTableCol field="last_name" title="Last Name" />
+        </AwTableBuilder>
+    </AwPage>
+</template>
+
+<script>
+export default {
+    computed: {
+        statusOptions() {
+            return [
+                { id: 'true', title: 'Active' },
+                { id: 'false', title: 'Inactive' }
+            ]
+        },
+
+        permissionOptions() {
+            return [
+                { id: 'manage-profile', title: 'Manage profile' },
+                { id: 'manage-users', title: 'Manage users' }
+            ]
+        }
+    },
+
+    methods: {
+        getStatusLabel(value) {
+            if (value === true || value === 'true') return 'Active'
+            if (value === false || value === 'false') return 'Inactive'
+            return value
+        },
+
+        getPermissionLabel(value) {
+            if (!value) return value
+
+            const permissions = Array.isArray(value)
+                ? value
+                : typeof value === 'string'
+                  ? value.split(',').map((p) => p.trim())
+                  : [value]
+
+            return permissions
+                .map((perm) => {
+                    const option = this.permissionOptions.find(
+                        (opt) => opt.id === perm || String(opt.id) === String(perm)
+                    )
+                    return option ? option.title : perm
+                })
+                .join(', ')
+        }
+    }
+}
+</script>
+```
+
+**Best Practices:**
+- ✅ **Always use custom slots** in `AwFilterChosen` to display user-friendly text instead of raw parameter values
+- ✅ **Omit `'search'` from watch-params** - Search doesn't need to be displayed as a chip
+- ✅ **Place search on the right** using `ml-auto` class
+- ✅ **Handle different value types** - Values can be strings, booleans, arrays, or comma-separated strings
+
+## Button Nav Filtering
+
+For simple toggle filters (like Active/Inactive, All/Pending/Completed), use `AwButtonNav` with query parameters:
+
+### Basic Button Nav Filter
+
+```markup
+<template>
+    <AwPage title="Services">
+        <AwButtonNav :items="filterItems" class="mb-6" />
+
+        <AwTableBuilder
+            :collection="services"
+            :watch-params="['is_active']"
+        >
+            <AwTableCol field="name" title="Service" />
+            <AwTableCol field="price" title="Price" />
+        </AwTableBuilder>
+    </AwPage>
+</template>
+
+<script>
+import { BaseCollection } from '@awes-io/vue-mc'
+
+class Services extends BaseCollection {
+    routes() {
+        return {
+            fetch: '/api/services'
+        }
+    }
+}
+
+export default {
+    data() {
+        return {
+            services: new Services()
+        }
+    },
+
+    computed: {
+        filterItems() {
+            return [
+                {
+                    text: 'Active',
+                    href: { query: { is_active: null } }
+                },
+                {
+                    text: 'Inactive',
+                    href: { query: { is_active: '0' } }
+                }
+            ]
+        }
+    }
+}
+</script>
+```
+
+**How it works:**
+1. ✅ `AwButtonNav` items use `href: { query: { param: value } }` format
+2. ✅ Setting `param: null` removes the parameter from URL (shows all active items)
+3. ✅ Setting `param: '0'` adds `is_active=0` to URL (shows inactive items)
+4. ✅ `AwTableBuilder` watches `is_active` param via `:watch-params`
+5. ✅ Table automatically refetches when query parameter changes
+
+### Multiple Filter Options
+
+For filters with more than two options:
+
+```markup
+<template>
+    <AwPage title="Orders">
+        <AwButtonNav :items="statusFilters" class="mb-6" />
+
+        <AwTableBuilder
+            :collection="orders"
+            :watch-params="['status']"
+        >
+            <AwTableCol field="number" title="Order #" />
+            <AwTableCol field="total" title="Total" />
+        </AwTableBuilder>
+    </AwPage>
+</template>
+
+<script>
+export default {
+    computed: {
+        statusFilters() {
+            return [
+                {
+                    text: 'All',
+                    href: { query: { status: null } }
+                },
+                {
+                    text: 'Pending',
+                    href: { query: { status: 'pending' } }
+                },
+                {
+                    text: 'Completed',
+                    href: { query: { status: 'completed' } }
+                },
+                {
+                    text: 'Cancelled',
+                    href: { query: { status: 'cancelled' } }
+                }
+            ]
+        }
+    }
+}
+</script>
+```
+
+### Button Nav with Icons
+
+You can add icons to filter buttons:
+
+```markup
+<template>
+    <AwButtonNav :items="filterItems" class="mb-6" />
+</template>
+
+<script>
+export default {
+    computed: {
+        filterItems() {
+            return [
+                {
+                    text: 'Active',
+                    icon: 'awesio/check-circle',
+                    href: { query: { is_active: null } }
+                },
+                {
+                    text: 'Inactive',
+                    icon: 'awesio/x-circle',
+                    href: { query: { is_active: '0' } }
+                }
+            ]
+        }
+    }
+}
+</script>
+```
+
+**Best Practices:**
+- ✅ **Use for simple toggle filters** - Best for 2-4 options (Active/Inactive, All/Pending/Completed)
+- ✅ **Use `null` to remove parameters** - Setting `param: null` removes it from URL, showing unfiltered results
+- ✅ **Use `AwFilterSelect` for complex filters** - When you have many options or need multi-select, use `AwFilterSelect` instead
+- ✅ **Combine with search** - Button nav filters work well alongside `AwSearch` for combined filtering
+
+## Custom Column Rendering
+
+### Understanding the `field` Prop
+
+**⚠️ Critical Distinction:**
+
+```markup
+<!-- WITH field: cell = field value only -->
+<AwTableCol title="Name" field="name">
+    <template #default="{ cell }">
+        {{ cell }} <!-- cell is just the string value of 'name' -->
+    </template>
+</AwTableCol>
+
+<!-- WITHOUT field: cell = entire row object -->
+<AwTableCol title="Name">
+    <template #default="{ cell }">
+        {{ cell.name }} <!-- cell is the full row object -->
+        {{ cell.email }} <!-- can access other fields -->
+    </template>
+</AwTableCol>
+```
+
+### Simple Field Display
+
+```markup
+<!-- No custom template needed for simple fields -->
+<AwTableCol field="name" title="Name" />
+<AwTableCol field="email" title="Email" />
+<AwTableCol field="phone" title="Phone" />
+```
+
+### Status Badge
+
+```markup
+<AwTableCol title="Status">
+    <template #default="{ cell }">
+        <AwLabel
+            :label="cell.is_active ? 'Active' : 'Inactive'"
+            :color="cell.is_active ? 'success' : 'mono'"
+        />
+    </template>
+</AwTableCol>
+```
+
+### Date Formatting
+
+```markup
+<AwTableCol title="Created">
+    <template #default="{ cell }">
+        {{ $dayjs(cell.created_at).format('ll') }}
+    </template>
+</AwTableCol>
+```
+
+**Common date formats:**
+- `ll` - Jan 15, 2024
+- `lll` - Jan 15, 2024 10:30 AM
+- `LL` - January 15, 2024
+- `MMMM YYYY` - January 2024
+
+### Currency Formatting
+
+```markup
+<AwTableCol title="Total">
+    <template #default="{ cell }">
+        ${{ (cell.total / 100).toFixed(2) }}
+    </template>
+</AwTableCol>
+```
+
+### Combined Data
+
+```markup
+<AwTableCol title="Customer">
+    <template #default="{ cell }">
+        <div class="flex items-center gap-2">
+            <AwAvatar :src="cell.avatar" size="sm" />
+            <div>
+                <div class="font-medium">{{ cell.name }}</div>
+                <div class="text-sm text-secondary">{{ cell.email }}</div>
+            </div>
+        </div>
+    </template>
+</AwTableCol>
+```
+
+## Mobile vs Desktop Table Layouts
+
+### Reordering Columns for Mobile
+
+A common pattern is to display important information differently on mobile vs desktop. For example, an employee userpic might be in the 3rd or 4th column on desktop, but should appear in the mobile header for better visual hierarchy.
+
+**Pattern: Userpic in Mobile Header**
+
+```markup
+<template>
+    <AwPage title="Jobs">
+        <AwTableBuilder :collection="jobs">
+            <!-- Job title - shown on both desktop and mobile -->
+            <AwTableCol field="title" title="Job Title" />
+
+            <!-- Client info -->
+            <AwTableCol field="client_name" title="Client" />
+
+            <!-- Assigned employee - 3rd column on desktop, hidden on mobile -->
+            <AwTableCol title="Assigned To" hide-mobile>
+                <template #default="{ cell }">
+                    <AwUserpic
+                        :src="cell.employee?.avatar"
+                        :name="cell.employee?.name"
+                        :description="cell.employee?.role"
+                    />
+                </template>
+            </AwTableCol>
+
+            <!-- Due date -->
+            <AwTableCol title="Due Date">
+                <template #default="{ cell }">
+                    {{ $dayjs(cell.due_date).format('ll') }}
+                </template>
+            </AwTableCol>
+
+            <!-- Mobile header: Show userpic prominently -->
+            <template #mobile-header-content="{ cell }">
+                <AwUserpic
+                    :src="cell.employee?.avatar"
+                    :name="cell.employee?.name"
+                    :description="cell.employee?.role"
+                />
+            </template>
+        </AwTableBuilder>
+    </AwPage>
+</template>
+```
+
+**What happens:**
+- **Desktop:** Userpic appears in "Assigned To" column (3rd position)
+- **Mobile:** Row collapses into card layout with userpic in header
+- `hide-mobile` prop hides the desktop column on mobile to avoid duplication
+- `mobile-header-content` slot positions userpic prominently in collapsed row header
+
+**Pattern: Main Info in Mobile Header**
+
+Sometimes the most important information should be highlighted in the mobile header:
+
+```markup
+<template>
+    <AwPage title="Services">
+        <AwTableBuilder :collection="services">
+            <!-- Service name - desktop only -->
+            <AwTableCol field="name" title="Service" hide-mobile />
+
+            <!-- Price -->
+            <AwTableCol title="Price">
+                <template #default="{ cell }">
+                    ${{ (cell.price / 100).toFixed(2) }}
+                </template>
+            </AwTableCol>
+
+            <!-- Duration -->
+            <AwTableCol field="duration" title="Duration" />
+
+            <!-- Category -->
+            <AwTableCol field="category" title="Category" />
+
+            <!-- Mobile header: Show service name as headline -->
+            <template #mobile-header-content="{ cell }">
+                <AwHeadline>{{ cell.name }}</AwHeadline>
+            </template>
+        </AwTableBuilder>
+    </AwPage>
+</template>
+```
+
+**What happens:**
+- **Desktop:** Service name in first column
+- **Mobile:** Service name becomes prominent headline in collapsed row header
+- Other details (price, duration, category) shown below in mobile card layout
+- `hide-mobile` on desktop column prevents duplicate service name
+
+**Pattern: Combined User + Main Info**
+
+For complex tables, combine userpic with main information in mobile header:
+
+```markup
+<template>
+    <AwPage title="Bookings">
+        <AwTableBuilder :collection="bookings">
+            <!-- Service name - hidden on mobile -->
+            <AwTableCol field="service_name" title="Service" hide-mobile />
+
+            <!-- Date & Time -->
+            <AwTableCol title="Date & Time">
+                <template #default="{ cell }">
+                    {{ $dayjs(cell.scheduled_at).format('lll') }}
+                </template>
+            </AwTableCol>
+
+            <!-- Client - shown on desktop, hidden on mobile -->
+            <AwTableCol title="Client" hide-mobile>
+                <template #default="{ cell }">
+                    <AwUserpic
+                        :src="cell.client?.avatar"
+                        :name="cell.client?.name"
+                        :description="cell.client?.email"
+                    />
+                </template>
+            </AwTableCol>
+
+            <!-- Status -->
+            <AwTableCol title="Status">
+                <template #default="{ cell }">
+                    <AwLabel
+                        :label="cell.status"
+                        :color="getStatusColor(cell.status)"
+                    />
+                </template>
+            </AwTableCol>
+
+            <!-- Mobile header: Service + Client -->
+            <template #mobile-header-content="{ cell }">
+                <div class="space-y-2">
+                    <AwHeadline>{{ cell.service_name }}</AwHeadline>
+                    <AwUserpic
+                        :src="cell.client?.avatar"
+                        :name="cell.client?.name"
+                        :description="cell.client?.email"
+                    />
+                </div>
+            </template>
+        </AwTableBuilder>
+    </AwPage>
+</template>
+
+<script>
+export default {
+    methods: {
+        getStatusColor(status) {
+            const colors = {
+                confirmed: 'success',
+                pending: 'warning',
+                cancelled: 'error',
+                completed: 'info'
+            }
+            return colors[status] || 'mono'
+        }
+    }
+}
+</script>
+```
+
+### Best Practices for Mobile Layouts
+
+**1. Use `hide-mobile` to Prevent Duplication**
+
+```markup
+<!-- ✅ GOOD - Hide desktop column to avoid showing info twice -->
+<AwTableCol title="Employee" hide-mobile>
+    <template #default="{ cell }">
+        <AwUserpic :name="cell.employee.name" />
+    </template>
+</AwTableCol>
+
+<template #mobile-header-content="{ cell }">
+    <AwUserpic :name="cell.employee.name" />
+</template>
+
+<!-- ❌ BAD - Shows employee info twice on mobile -->
+<AwTableCol title="Employee">
+    <template #default="{ cell }">
+        <AwUserpic :name="cell.employee.name" />
+    </template>
+</AwTableCol>
+
+<template #mobile-header-content="{ cell }">
+    <AwUserpic :name="cell.employee.name" />
+</template>
+```
+
+**2. Prioritize Visual Hierarchy on Mobile**
+
+```markup
+<!-- ✅ GOOD - Most important info in mobile header -->
+<template #mobile-header-content="{ cell }">
+    <AwHeadline>{{ cell.title }}</AwHeadline>
+    <AwUserpic :name="cell.owner.name" />
+</template>
+
+<!-- ❌ BAD - Generic info that doesn't help user scan -->
+<template #mobile-header-content="{ cell }">
+    <span>{{ cell.id }}</span>
+</template>
+```
+
+**3. Use Appropriate Components**
+
+- **AwHeadline** - For main titles/names
+- **AwUserpic** - For person/employee information with avatar
+- **AwLabel** - For status badges
+- Keep mobile headers concise and scannable
+
+**4. Consider Touch Targets**
+
+```markup
+<!-- Mobile header content should support touch/tap -->
+<AwTableBuilder
+    :collection="items"
+    @click:row="viewItem"
+>
+    <template #mobile-header-content="{ cell }">
+        <AwUserpic :name="cell.name" />
+    </template>
+</AwTableBuilder>
+```
+
+## Row Actions
+
+### Click Row (Navigation)
+
+```markup
+<template>
+    <AwPage title="Customers">
+        <AwTableBuilder
+            :collection="customers"
+            @click:row="viewCustomer"
+        >
+            <AwTableCol field="name" title="Name" />
+            <AwTableCol field="email" title="Email" />
+        </AwTableBuilder>
+    </AwPage>
+</template>
+
+<script>
+export default {
+    methods: {
+        viewCustomer(customer) {
+            this.$router.push(
+                `/${this.$route.params.shop_uuid}/customers/${customer.id}`
+            )
+        }
+    }
+}
+</script>
+```
+
+### Dropdown Actions
+
+```markup
+<template>
+    <AwPage title="Templates">
+        <AwTableBuilder :collection="templates">
+            <AwTableCol field="name" title="Name" />
+            <AwTableCol field="status" title="Status" />
+
+            <!-- Dropdown slot for row actions -->
+            <template #dropdown="{ cell }">
+                <AwDropdownButton
+                    text="View"
+                    @click="viewItem(cell)"
+                />
+                <AwDropdownButton
+                    text="Edit"
+                    @click="editItem(cell)"
+                />
+                <AwDropdownButton
+                    text="Duplicate"
+                    @click="duplicateItem(cell)"
+                />
+                <AwDropdownButton
+                    text="Delete"
+                    color="error"
+                    @click="deleteItem(cell)"
+                />
+            </template>
+        </AwTableBuilder>
+    </AwPage>
+</template>
+
+<script>
+export default {
+    methods: {
+        viewItem(item) {
+            this.$router.push(`/templates/${item.id}`)
+        },
+
+        editItem(item) {
+            this.$router.push(`/templates/${item.id}/edit`)
+        },
+
+        duplicateItem(item) {
+            // Duplicate logic
+        },
+
+        async deleteItem(item) {
+            const confirmed = await this.$confirm({
+                title: 'Delete Template',
+                message: `Are you sure you want to delete "${item.name}"?`
+            })
+
+            if (!confirmed) return
+
+            try {
+                await this.$axios.delete(`/api/templates/${item.id}`)
+                this.$notify({
+                    title: 'Template deleted successfully',
+                    type: 'success'
+                })
+                this.templates.fetch() // Refetch list
+            } catch (error) {
+                this.$notify({
+                    title: 'Failed to delete template',
+                    type: 'error'
+                })
+            }
+        }
+    }
+}
+</script>
+```
+
+**⚠️ Important: Can't use both @click:row and #dropdown**
+
+```markup
+<!-- ❌ BAD - Conflict! Row click and dropdown both trigger -->
+<AwTableBuilder
+    :collection="items"
+    @click:row="viewItem"
+>
+    <template #dropdown="{ cell }">
+        <AwDropdownButton text="Edit" />
+    </template>
+</AwTableBuilder>
+
+<!-- ✅ GOOD - Choose one approach -->
+<!-- Option 1: Row click only -->
+<AwTableBuilder
+    :collection="items"
+    @click:row="viewItem"
+>
+    <!-- No dropdown -->
+</AwTableBuilder>
+
+<!-- Option 2: Dropdown only -->
+<AwTableBuilder :collection="items">
+    <template #dropdown="{ cell }">
+        <AwDropdownButton text="View" @click="viewItem(cell)" />
+        <AwDropdownButton text="Edit" @click="editItem(cell)" />
+    </template>
+</AwTableBuilder>
+```
+
+**Dropdown Action Ordering:**
+1. View (if separate from row click)
+2. Edit
+3. Other actions (Duplicate, Archive, etc.)
+4. Delete (last, in error color)
+
+## Mobile Breadcrumbs
+
+For pages in subfolders, add breadcrumbs for mobile navigation:
+
+```markup
+<template>
+    <AwPage title="Email Templates">
+        <!-- Mobile breadcrumb -->
+        <template #mobile-breadcrumbs>
+            <AwButton
+                :href="`/${$route.params.shop_uuid}/notifications`"
+                theme="text"
+                icon="arrow-left"
+                text="Notifications"
+            />
+        </template>
+
+        <!-- Page content -->
+    </AwPage>
+</template>
+```
+
+## Empty States
+
+Use the `cta-button` prop on `AwEmptyContainer` to add a create button in the empty state. The button should use the same `href` as the header button:
+
+```markup
+<template>
+    <AwPage title="Customers">
+        <template #buttons>
+            <AwPageMenuButtons
+                :items="[{
+                    text: 'Create Customer',
+                    icon: 'awesio/plus',
+                    cta: true,
+                    href: '/customers/create'
+                }]"
+            />
+        </template>
+
+        <AwTableBuilder :collection="customers">
+            <AwTableCol field="name" title="Name" />
+
+            <!-- Empty state with create button -->
+            <template #empty-container>
+                <AwEmptyContainer
+                    icon="users"
+                    title="No customers yet"
+                    description="Create your first customer to get started"
+                    :cta-button="{
+                        text: 'Create Customer',
+                        icon: 'awesio/plus',
+                        href: '/customers/create'
+                    }"
+                />
+            </template>
+        </AwTableBuilder>
+    </AwPage>
+</template>
+```
+
+**Best Practice:** Always use the same create button in both the header (`AwPageMenuButtons`) and empty state (`AwEmptyContainer` cta-button) with the same `href` for consistency.
+
+## Complete Example
+
+Full-featured list page with all patterns:
+
+```markup
+<template>
+    <AwPage title="Email Templates">
+        <!-- Mobile breadcrumbs -->
+        <template #mobile-breadcrumbs>
+            <AwButton
+                :href="`/${$route.params.shop_uuid}/notifications`"
+                theme="text"
+                icon="arrow-left"
+                text="Back to Notifications"
+            />
+        </template>
+
+        <!-- Header action buttons -->
+        <template #buttons>
+            <AwPageMenuButtons
+                :items="[
+                    {
+                        text: 'Import',
+                        icon: 'awesio/upload',
+                        color: 'mono',
+                        listeners: { click: importTemplates }
+                    },
+                    {
+                        text: 'Create Template',
+                        icon: 'awesio/plus',
+                        cta: true,
+                        href: `/${shopUuid}/templates/create`
+                    }
+                ]"
+            />
+        </template>
+
+        <!-- Search and filters -->
+        <div class="flex flex-col lg:flex-row gap-4 mb-6">
+            <AwSearch class="flex-1" />
+            <AwSelect
+                v-model="channelFilter"
+                :options="['all', 'email', 'sms', 'push']"
+                label="Channel"
+                class="w-full lg:w-48"
+            />
+        </div>
+
+        <!-- Table with data -->
+        <AwTableBuilder
+            :collection="templates"
+            :watch-params="['search']"
+            :options="{ shop_uuid: shopUuid, channel: channelFilter }"
+        >
+            <!-- Simple field columns -->
+            <AwTableCol field="name" title="Template Name" />
+
+            <!-- Custom status column -->
+            <AwTableCol title="Status">
+                <template #default="{ cell }">
+                    <AwLabel
+                        :label="cell.is_active ? 'Active' : 'Inactive'"
+                        :color="cell.is_active ? 'success' : 'mono'"
+                    />
+                </template>
+            </AwTableCol>
+
+            <!-- Channel badge -->
+            <AwTableCol title="Channel">
+                <template #default="{ cell }">
+                    <AwBadge :text="cell.channel" />
+                </template>
+            </AwTableCol>
+
+            <!-- Date column -->
+            <AwTableCol title="Last Modified">
+                <template #default="{ cell }">
+                    {{ $dayjs(cell.updated_at).format('ll') }}
+                </template>
+            </AwTableCol>
+
+            <!-- Row actions dropdown -->
+            <template #dropdown="{ cell }">
+                <AwDropdownButton
+                    text="Edit"
+                    @click="editTemplate(cell)"
+                />
+                <AwDropdownButton
+                    text="Duplicate"
+                    @click="duplicateTemplate(cell)"
+                />
+                <AwDropdownButton
+                    :text="cell.is_active ? 'Deactivate' : 'Activate'"
+                    @click="toggleActive(cell)"
+                />
+                <AwDropdownButton
+                    text="Delete"
+                    color="error"
+                    @click="deleteTemplate(cell)"
+                />
+            </template>
+
+            <!-- Empty state -->
+            <template #empty-container>
+                <AwEmptyContainer
+                    icon="awesio/mail"
+                    title="No templates yet"
+                    description="Create your first email template"
+                    :cta-button="{
+                        text: 'Create Template',
+                        icon: 'awesio/plus',
+                        href: `/${shopUuid}/templates/create`
+                    }"
+                />
+            </template>
+        </AwTableBuilder>
+    </AwPage>
+</template>
+
+<script>
+import EmailTemplates from '~/collections/EmailTemplates'
+
+export default {
+    middleware: 'auth',
+
+    data() {
+        return {
+            channelFilter: 'all',
+            templates: new EmailTemplates([], {
+                shop_uuid: this.$route.params.shop_uuid
+            })
+        }
+    },
+
+    computed: {
+        shopUuid() {
+            return this.$route.params.shop_uuid
+        }
+    },
+
+    methods: {
+        editTemplate(template) {
+            this.$router.push({
+                name: 'templates-edit',
+                params: {
+                    shop_uuid: this.shopUuid,
+                    id: template.id
+                }
+            })
+        },
+
+        async duplicateTemplate(template) {
+            try {
+                await this.$axios.post(`/api/templates/${template.id}/duplicate`)
+                this.$notify({
+                    title: 'Template duplicated successfully',
+                    type: 'success'
+                })
+                this.templates.fetch()
+            } catch (error) {
+                this.$notify({
+                    title: 'Failed to duplicate template',
+                    type: 'error'
+                })
+            }
+        },
+
+        async toggleActive(template) {
+            try {
+                await this.$axios.patch(`/api/templates/${template.id}`, {
+                    is_active: !template.is_active
+                })
+                this.$notify({
+                    title: `Template ${template.is_active ? 'deactivated' : 'activated'}`,
+                    type: 'success'
+                })
+                this.templates.fetch()
+            } catch (error) {
+                this.$notify({
+                    title: 'Failed to update template',
+                    type: 'error'
+                })
+            }
+        },
+
+        async deleteTemplate(template) {
+            const confirmed = await this.$confirm({
+                title: 'Delete Template',
+                message: `Are you sure you want to delete "${template.name}"?`
+            })
+
+            if (!confirmed) return
+
+            try {
+                await this.$axios.delete(`/api/templates/${template.id}`)
+                this.$notify({
+                    title: 'Template deleted successfully',
+                    type: 'success'
+                })
+                this.templates.fetch()
+            } catch (error) {
+                this.$notify({
+                    title: 'Failed to delete template',
+                    type: 'error'
+                })
+            }
+        },
+
+        importTemplates() {
+            // Import logic
+        }
+    }
+}
+</script>
+```
+
+## Best Practices
+
+### 1. Collection Initialization
+
+✅ **Always include shop_uuid in options:**
+```javascript
+customers: new Customers([], {
+    shop_uuid: this.$route.params.shop_uuid
+})
+```
+
+### 2. No Manual Fetching
+
+✅ **Let AwTableBuilder handle fetching:**
+```markup
+<!-- ✅ GOOD -->
+<AwTableBuilder :collection="customers" />
+
+<!-- ❌ BAD - Don't fetch manually -->
+<script>
+async mounted() {
+    await this.customers.fetch() // Unnecessary!
+}
+</script>
+```
+
+### 3. Loading States
+
+✅ **Don't wrap in v-if:**
+```markup
+<!-- ✅ GOOD - Component handles loading -->
+<AwTableBuilder :collection="customers" />
+
+<!-- ❌ BAD - Prevents mounting -->
+<AwTableBuilder v-if="!loading" :collection="customers" />
+```
+
+### 4. Date Formatting
+
+✅ **Always use $dayjs:**
+```markup
+<!-- ✅ GOOD -->
+{{ $dayjs(cell.created_at).format('ll') }}
+
+<!-- ❌ BAD - Inconsistent formatting -->
+{{ new Date(cell.created_at).toLocaleDateString() }}
+```
+
+### 5. Confirmations for Destructive Actions
+
+✅ **Always confirm deletes:**
+```javascript
+async deleteItem(item) {
+    const confirmed = await this.$confirm({
+        title: 'Delete Item',
+        message: `Are you sure you want to delete "${item.name}"?`
+    })
+
+    if (!confirmed) return
+
+    // Proceed with deletion
+}
+```
+
+## See Also
+
+- [Detail Pages](./detail-pages.md) - Create and edit pages
+- [Dashboard Pages](./dashboard-pages.md) - Metrics and overview pages
+- [AwTableBuilder](../../components/organisms/aw-table-builder.md) - Table component reference
+- [AwPage](../../components/pages/aw-page.md) - Page component reference
+- [Data Fetching Guide](../data-fetching.md) - Working with collections