@awes-io/ui 2.142.0 → 2.143.0

package/docs/reference/plugins.md

@@ -0,0 +1,970 @@
+# Plugins & Utilities Reference
+
+Complete reference for all AwesCode UI plugins and utility methods available in your application.
+
+## Overview
+
+AwesCode UI provides several plugins that extend Nuxt with custom functionality:
+
+| Plugin | Purpose | Available As |
+|--------|---------|--------------|
+| **core** | Notifications, config access | `$notify`, `$confirm`, `$awes` |
+| **screen** | Responsive breakpoints | `$screen` |
+| **dayjs** | Date formatting | `$dayjs` |
+| **router** | Router extensions | `router.pushBack`, `router.setBack` |
+| **dark-theme** | Theme management | `$store.commit('awesIo/SET_DARK_THEME')`, `$store.getters['awesIo/isDarkTheme']` |
+| **permissions** | CASL permissions | `$can`, `$cannot` |
+
+All plugins are automatically registered by the `@awes-io/ui` Nuxt module.
+
+## $notify
+
+Display toast notifications to users.
+
+### Basic Usage
+
+```javascript
+// Success notification
+this.$notify({
+    title: 'Customer saved successfully',
+    type: 'success'
+})
+
+// Error notification
+this.$notify({
+    title: 'Failed to load data',
+    type: 'error'
+})
+
+// Warning notification
+this.$notify({
+    title: 'Data may be outdated',
+    type: 'warning'
+})
+
+// Info notification
+this.$notify({
+    title: 'Processing request...',
+    type: 'info'
+})
+```
+
+### Notification Types
+
+```javascript
+// Success (green)
+this.$notify({
+    title: 'Operation completed',
+    type: 'success'
+})
+
+// Error (red)
+this.$notify({
+    title: 'Something went wrong',
+    type: 'error'
+})
+
+// Warning (yellow/orange)
+this.$notify({
+    title: 'Please review your input',
+    type: 'warning'
+})
+
+// Info (blue)
+this.$notify({
+    title: 'Your session will expire in 5 minutes',
+    type: 'info'
+})
+```
+
+### With Duration
+
+```javascript
+// Auto-dismiss after 5 seconds (default)
+this.$notify({
+    title: 'Auto-dismiss notification'
+})
+
+// Auto-dismiss after 10 seconds
+this.$notify({
+    title: 'Longer notification',
+    timeout: 10000
+})
+
+// Never auto-dismiss (requires manual close)
+this.$notify({
+    title: 'Important: Please read carefully',
+    timeout: 0
+})
+```
+
+### With Title
+
+```javascript
+this.$notify({
+    title: 'Success',
+    text: 'Customer profile updated successfully',
+    type: 'success'
+})
+
+this.$notify({
+    title: 'Error',
+    text: 'Unable to connect to server',
+    type: 'error'
+})
+```
+
+### Common Patterns
+
+```javascript
+// After successful save
+async save() {
+    try {
+        await this.customer.save()
+
+        this.$notify({
+            title: 'Customer saved successfully',
+            type: 'success'
+        })
+
+        this.$router.push('/customers')
+    } catch (error) {
+        this.$notify({
+            title: 'Failed to save customer',
+            type: 'error'
+        })
+    }
+}
+
+// After successful delete
+async delete() {
+    await this.$axios.delete(`/api/customers/${id}`)
+
+    this.$notify({
+        title: 'Customer deleted',
+        type: 'success'
+    })
+}
+
+// Network error
+catch (error) {
+    if (!error.response) {
+        this.$notify({
+            title: 'Network error. Please check your connection.',
+            type: 'error'
+        })
+    }
+}
+
+// Bulk action
+this.$notify({
+    title: `${count} customers updated`,
+    type: 'success'
+})
+```
+
+## $confirm
+
+Show confirmation dialogs for destructive actions.
+
+### Basic Usage
+
+```javascript
+const confirmed = await this.$confirm({
+    title: 'Delete Customer',
+    message: 'Are you sure you want to delete this customer?'
+})
+
+if (confirmed) {
+    // User clicked "Confirm"
+    await this.deleteCustomer()
+} else {
+    // User clicked "Cancel" or closed dialog
+}
+```
+
+### With Custom Button Text
+
+```javascript
+const confirmed = await this.$confirm({
+    title: 'Permanent Delete',
+    message: 'This will permanently delete all data. This action cannot be undone.',
+    confirmText: 'Yes, Delete Everything',
+    cancelText: 'No, Keep It'
+})
+```
+
+### Delete Pattern
+
+```javascript
+async deleteCustomer(customer) {
+    const confirmed = await this.$confirm({
+        title: 'Delete Customer',
+        message: `Are you sure you want to delete ${customer.name}?`
+    })
+
+    if (!confirmed) {
+        return
+    }
+
+    try {
+        await this.$axios.delete(`/api/customers/${customer.id}`)
+
+        this.$notify({
+            title: 'Customer deleted',
+            type: 'success'
+        })
+
+        await this.customers.fetch()
+    } catch (error) {
+        this.$notify({
+            title: 'Failed to delete customer',
+            type: 'error'
+        })
+    }
+}
+```
+
+### Discard Changes Pattern
+
+```javascript
+async leave() {
+    if (this.hasUnsavedChanges) {
+        const confirmed = await this.$confirm({
+            title: 'Unsaved Changes',
+            message: 'You have unsaved changes. Are you sure you want to leave?',
+            confirmText: 'Leave',
+            cancelText: 'Stay'
+        })
+
+        if (!confirmed) {
+            return
+        }
+    }
+
+    this.$router.push('/customers')
+}
+```
+
+### With Navigation Guard
+
+```javascript
+export default {
+    beforeRouteLeave(to, from, next) {
+        if (this.hasUnsavedChanges) {
+            this.$confirm({
+                title: 'Unsaved Changes',
+                message: 'Are you sure you want to leave?'
+            }).then(confirmed => {
+                if (confirmed) {
+                    next()
+                } else {
+                    next(false)
+                }
+            })
+        } else {
+            next()
+        }
+    }
+}
+```
+
+## $screen
+
+Reactive responsive breakpoints.
+
+### Breakpoint Values
+
+```javascript
+// Breakpoints (following Tailwind defaults)
+$screen.sm   // >= 640px
+$screen.md   // >= 768px
+$screen.lg   // >= 1024px
+$screen.xl   // >= 1280px
+$screen.xxl  // >= 1536px
+```
+
+### Usage in Templates
+
+```markup
+<template>
+    <div>
+        <!-- Mobile only -->
+        <div v-if="!$screen.md">
+            Mobile menu
+        </div>
+
+        <!-- Desktop only -->
+        <div v-if="$screen.md">
+            Desktop menu
+        </div>
+
+        <!-- Responsive columns -->
+        <AwGrid :col="$screen.md ? 2 : 1">
+            <div>Column 1</div>
+            <div>Column 2</div>
+        </AwGrid>
+
+        <!-- Conditional component -->
+        <AwTable v-if="$screen.lg" :collection="items" />
+        <AwCard v-else v-for="item in items" :key="item.id">
+            {{ item.name }}
+        </AwCard>
+    </div>
+</template>
+```
+
+### Usage in Methods
+
+```javascript
+export default {
+    methods: {
+        openSidebar() {
+            // On mobile, open as modal
+            if (!this.$screen.md) {
+                this.showMobileMenu = true
+            }
+        },
+
+        getTableColumns() {
+            // Fewer columns on mobile
+            if (this.$screen.sm) {
+                return ['name', 'email', 'phone', 'created_at']
+            }
+            return ['name', 'email']
+        }
+    }
+}
+```
+
+### Usage in Computed
+
+```javascript
+export default {
+    computed: {
+        isMobile() {
+            return !this.$screen.md
+        },
+
+        columns() {
+            if (this.$screen.xl) {
+                return 4
+            }
+            if (this.$screen.lg) {
+                return 3
+            }
+            if (this.$screen.md) {
+                return 2
+            }
+            return 1
+        }
+    }
+}
+```
+
+### Reactive Updates
+
+`$screen` is reactive - components automatically update when breakpoints change:
+
+```markup
+<template>
+    <div>
+        <!-- Automatically updates on resize -->
+        <p>Current breakpoint: {{ currentBreakpoint }}</p>
+    </div>
+</template>
+
+<script>
+export default {
+    computed: {
+        currentBreakpoint() {
+            if (this.$screen.xxl) return 'xxl'
+            if (this.$screen.xl) return 'xl'
+            if (this.$screen.lg) return 'lg'
+            if (this.$screen.md) return 'md'
+            if (this.$screen.sm) return 'sm'
+            return 'xs'
+        }
+    }
+}
+</script>
+```
+
+## $dayjs
+
+Date formatting and manipulation using Day.js library.
+
+**⚠️ CRITICAL: Always use `$dayjs`, never use native `Date` constructor**
+
+The framework uses Day.js for all date operations. Using native JavaScript `Date` constructor can cause timezone issues, inconsistent formatting, and compatibility problems. Always use `$dayjs` (in templates) or `this.$dayjs` (in methods) instead of `new Date()`.
+
+```javascript
+// ❌ BAD - Never use native Date
+const date = new Date(value)
+date.toLocaleDateString('en-US', { month: 'short', day: 'numeric', year: 'numeric' })
+
+// ✅ GOOD - Always use $dayjs
+this.$dayjs(value).format('MMM D, YYYY')
+```
+
+### IMPORTANT: Template vs Method Usage
+
+```markup
+<template>
+    <!-- ✅ GOOD: In templates, use $dayjs WITHOUT this -->
+    {{ $dayjs(date).format('ll') }}
+</template>
+
+<script>
+export default {
+    methods: {
+        formatDate(date) {
+            // ✅ GOOD: In methods, use this.$dayjs WITH this
+            return this.$dayjs(date).format('ll')
+        }
+    }
+}
+</script>
+```
+
+### Common Date Formats
+
+```javascript
+const date = '2024-01-15'
+
+// Short date: Jan 15, 2024
+this.$dayjs(date).format('ll')
+
+// Long date: January 15, 2024
+this.$dayjs(date).format('LL')
+
+// Short date + time: Jan 15, 2024 2:30 PM
+this.$dayjs(date).format('lll')
+
+// Long date + time: January 15, 2024 2:30 PM
+this.$dayjs(date).format('LLL')
+
+// Full: Monday, January 15, 2024 2:30 PM
+this.$dayjs(date).format('LLLL')
+
+// Month and year: January 2024
+this.$dayjs(date).format('MMMM YYYY')
+
+// ISO format: 2024-01-15T14:30:00Z
+this.$dayjs(date).toISOString()
+
+// Relative time: 2 hours ago
+this.$dayjs(date).fromNow()
+```
+
+### Template Usage
+
+```markup
+<template>
+    <div>
+        <!-- Short date -->
+        <p>{{ $dayjs(customer.created_at).format('ll') }}</p>
+
+        <!-- Month and year -->
+        <p>{{ $dayjs(order.date).format('MMMM YYYY') }}</p>
+
+        <!-- Relative time -->
+        <p>Updated {{ $dayjs(item.updated_at).fromNow() }}</p>
+
+        <!-- Custom format -->
+        <p>{{ $dayjs(event.date).format('MMM D, YYYY [at] h:mm A') }}</p>
+    </div>
+</template>
+```
+
+### Common Patterns
+
+```javascript
+// Display created date
+computed: {
+    createdDate() {
+        return this.$dayjs(this.customer.created_at).format('ll')
+    }
+}
+
+// Display relative time
+computed: {
+    lastUpdated() {
+        return this.$dayjs(this.item.updated_at).fromNow()
+    }
+}
+
+// Filter by date range
+methods: {
+    filterByMonth(month, year) {
+        const start = this.$dayjs(`${year}-${month}-01`).startOf('month')
+        const end = this.$dayjs(`${year}-${month}-01`).endOf('month')
+
+        return this.items.filter(item => {
+            const date = this.$dayjs(item.date)
+            return date.isAfter(start) && date.isBefore(end)
+        })
+    }
+}
+
+// Sort by date
+methods: {
+    sortByDate() {
+        return this.items.sort((a, b) => {
+            return this.$dayjs(a.date).diff(this.$dayjs(b.date))
+        })
+    }
+}
+```
+
+### Date Manipulation
+
+```javascript
+// Add time
+this.$dayjs().add(7, 'day')       // 7 days from now
+this.$dayjs().add(1, 'month')     // 1 month from now
+this.$dayjs().add(2, 'year')      // 2 years from now
+
+// Subtract time
+this.$dayjs().subtract(3, 'day')  // 3 days ago
+this.$dayjs().subtract(1, 'week') // 1 week ago
+
+// Start/end of period
+this.$dayjs().startOf('month')    // First day of month
+this.$dayjs().endOf('month')      // Last day of month
+this.$dayjs().startOf('week')     // Start of week (Sunday)
+
+// Comparison
+const date1 = this.$dayjs('2024-01-15')
+const date2 = this.$dayjs('2024-02-20')
+
+date1.isBefore(date2)  // true
+date1.isAfter(date2)   // false
+date1.isSame(date2)    // false
+
+// Difference
+date2.diff(date1, 'day')    // 36 days
+date2.diff(date1, 'month')  // 1 month
+```
+
+## router.pushBack / router.setBack
+
+Navigate back to a specific route.
+
+### Basic Usage
+
+```javascript
+// Set where "back" should go
+this.$router.setBack('/customers')
+
+// Navigate back
+this.$router.pushBack()
+```
+
+### Common Pattern
+
+```javascript
+// On list page - set back route
+mounted() {
+    this.$router.setBack('/customers')
+}
+
+// On detail page - go back
+methods: {
+    cancel() {
+        this.$router.pushBack()
+    }
+}
+```
+
+### With Fallback
+
+```javascript
+// Go back, or fallback to /dashboard
+this.$router.pushBack('/dashboard')
+```
+
+### Complete Example
+
+```markup
+<!-- List Page -->
+<script>
+export default {
+    mounted() {
+        // Set back route for detail pages
+        this.$router.setBack(`/shops/${this.$route.params.shop_uuid}/customers`)
+    },
+
+    methods: {
+        viewCustomer(customer) {
+            this.$router.push(`/shops/${this.$route.params.shop_uuid}/customers/${customer.id}`)
+        }
+    }
+}
+</script>
+
+<!-- Detail Page -->
+<script>
+export default {
+    methods: {
+        async save() {
+            await this.customer.save()
+
+            this.$notify({
+                title: 'Customer saved',
+                type: 'success'
+            })
+
+            // Go back to list
+            this.$router.pushBack(`/shops/${this.$route.params.shop_uuid}/customers`)
+        },
+
+        cancel() {
+            // Go back without saving
+            this.$router.pushBack(`/shops/${this.$route.params.shop_uuid}/customers`)
+        }
+    }
+}
+</script>
+```
+
+## $awes
+
+Access AwesCode UI configuration and utilities.
+
+### Configuration Access
+
+```javascript
+// Get component config
+const buttonConfig = this.$awes.config.AwButton
+
+// Get global config
+const apiUrl = this.$awes.config.apiUrl
+```
+
+### Usage
+
+```javascript
+export default {
+    computed: {
+        defaultButtonSize() {
+            return this.$awes.config.AwButton?.size || 'md'
+        }
+    }
+}
+```
+
+## $can / $cannot (CASL Permissions)
+
+Check user permissions (if CASL is configured).
+
+### Basic Usage
+
+```markup
+<template>
+    <div>
+        <!-- Show button only if user can create -->
+        <AwButton v-if="$can('create', 'Customer')">
+            Add Customer
+        </AwButton>
+
+        <!-- Show button only if user can edit -->
+        <AwButton v-if="$can('update', customer)">
+            Edit
+        </AwButton>
+
+        <!-- Show button only if user can delete -->
+        <AwButton v-if="$can('delete', customer)">
+            Delete
+        </AwButton>
+
+        <!-- Inverse check -->
+        <p v-if="$cannot('view', 'Reports')">
+            You don't have access to reports
+        </p>
+    </div>
+</template>
+```
+
+### In Methods
+
+```javascript
+export default {
+    methods: {
+        async deleteCustomer(customer) {
+            // Check permission
+            if (!this.$can('delete', customer)) {
+                this.$notify({
+                    title: 'You do not have permission to delete this customer',
+                    type: 'error'
+                })
+                return
+            }
+
+            // Proceed with delete
+            await this.$axios.delete(`/api/customers/${customer.id}`)
+        }
+    }
+}
+```
+
+## Dark Theme Management
+
+Toggle between light and dark themes using Vuex store.
+
+### Basic Usage
+
+```markup
+<template>
+    <AwButton @click="toggleTheme">
+        Toggle Theme
+    </AwButton>
+</template>
+
+<script>
+export default {
+    methods: {
+        toggleTheme() {
+            const currentTheme = this.$store.getters['awesIo/isDarkTheme']
+            this.$store.commit('awesIo/SET_DARK_THEME', !currentTheme)
+        }
+    }
+}
+</script>
+```
+
+### Using v-model with Switcher
+
+```markup
+<template>
+    <AwSwitcher v-model="isDarkTheme" size="lg" />
+</template>
+
+<script>
+export default {
+    computed: {
+        isDarkTheme: {
+            get() {
+                return this.$store.getters['awesIo/isDarkTheme']
+            },
+            set(val) {
+                this.$store.commit('awesIo/SET_DARK_THEME', val)
+            }
+        }
+    }
+}
+</script>
+```
+
+### With Icon Button
+
+```markup
+<template>
+    <AwButton @click="toggleTheme">
+        <AwIcon :name="isDarkTheme ? 'sun' : 'moon'" />
+        {{ isDarkTheme ? 'Light Mode' : 'Dark Mode' }}
+    </AwButton>
+</template>
+
+<script>
+export default {
+    computed: {
+        isDarkTheme() {
+            return this.$store.getters['awesIo/isDarkTheme']
+        }
+    },
+
+    methods: {
+        toggleTheme() {
+            this.$store.commit('awesIo/SET_DARK_THEME', !this.isDarkTheme)
+        }
+    }
+}
+</script>
+```
+
+## Complete Examples
+
+### Form with Full Error Handling
+
+```markup
+<template>
+    <AwPageSingle
+        hide-menu
+        :title="customer.isNew() ? 'New Customer' : 'Edit Customer'"
+    >
+        <AwCard title="Customer Information">
+            <AwInput
+                v-model="customer.name"
+                :error="customer.errors.name"
+                label="Name"
+            />
+
+            <AwInput
+                v-model="customer.email"
+                :error="customer.errors.email"
+                label="Email"
+                type="email"
+            />
+
+            <AwDate
+                v-model="customer.birthday"
+                :error="customer.errors.birthday"
+                label="Birthday"
+            />
+
+            <!-- Display formatted date -->
+            <p v-if="customer.birthday">
+                Birthday: {{ $dayjs(customer.birthday).format('LL') }}
+            </p>
+        </AwCard>
+
+        <template #buttons>
+            <AwButton
+                :loading="saving"
+                color="accent"
+                @click="save"
+            >
+                Save
+            </AwButton>
+
+            <AwButton @click="cancel">
+                Cancel
+            </AwButton>
+        </template>
+    </AwPageSingle>
+</template>
+
+<script>
+import Customer from '~/models/Customer'
+
+export default {
+    data() {
+        return {
+            customer: new Customer(
+                {},
+                null,
+                { shop_uuid: this.$route.params.shop_uuid }
+            ),
+            saving: false
+        }
+    },
+
+    methods: {
+        async save() {
+            this.saving = true
+
+            try {
+                await this.customer.save()
+
+                if (Object.keys(this.customer.errors).length > 0) {
+                    this.$notify({
+                        title: 'Please fix validation errors',
+                        type: 'error'
+                    })
+                    return
+                }
+
+                this.$notify({
+                    title: 'Customer saved successfully',
+                    type: 'success'
+                })
+
+                this.$router.pushBack(`/shops/${this.$route.params.shop_uuid}/customers`)
+            } catch (error) {
+                this.$notify({
+                    title: 'Failed to save customer',
+                    type: 'error'
+                })
+            } finally {
+                this.saving = false
+            }
+        },
+
+        cancel() {
+            this.$router.pushBack(`/shops/${this.$route.params.shop_uuid}/customers`)
+        }
+    }
+}
+</script>
+```
+
+### Responsive Table
+
+```markup
+<template>
+    <AwPage title="Customers">
+        <template #buttons>
+            <AwButton
+                v-if="$can('create', 'Customer')"
+                :href="`/shops/${$route.params.shop_uuid}/customers/new`"
+                color="accent"
+            >
+                Add Customer
+            </AwButton>
+        </template>
+
+        <!-- Desktop table -->
+        <AwTableBuilder
+            v-if="$screen.md"
+            :collection="customers"
+            @click:row="viewCustomer"
+        >
+            <AwTableCol field="name" title="Name" />
+            <AwTableCol field="email" title="Email" />
+            <AwTableCol field="phone" title="Phone" />
+            <AwTableCol field="created_at" title="Created">
+                <template #default="{ cell }">
+                    {{ $dayjs(cell).format('ll') }}
+                </template>
+            </AwTableCol>
+        </AwTableBuilder>
+
+        <!-- Mobile cards -->
+        <div v-else>
+            <AwCard
+                v-for="customer in customers.models"
+                :key="customer.id"
+                class="mb-4"
+                @click="viewCustomer(customer)"
+            >
+                <h3>{{ customer.name }}</h3>
+                <p>{{ customer.email }}</p>
+                <p class="text-sm text-gray-500">
+                    Created {{ $dayjs(customer.created_at).fromNow() }}
+                </p>
+            </AwCard>
+        </div>
+    </AwPage>
+</template>
+
+<script>
+import Customers from '~/collections/Customers'
+
+export default {
+    data() {
+        return {
+            customers: new Customers([], {
+                shop_uuid: this.$route.params.shop_uuid
+            })
+        }
+    },
+
+    mounted() {
+        this.$router.setBack(`/shops/${this.$route.params.shop_uuid}/customers`)
+    },
+
+    methods: {
+        viewCustomer(customer) {
+            this.$router.push(`/shops/${this.$route.params.shop_uuid}/customers/${customer.id}`)
+        }
+    }
+}
+</script>
+```
+
+## See Also
+
+- [Error Handling Guide](../guides/error-handling.md) - Using $notify and $confirm
+- [Data Fetching Guide](../guides/data-fetching.md) - Using date formatting in templates
+- [Best Practices Guide](../guides/best-practices.md) - Plugin usage patterns