@awes-io/ui 2.142.3 → 2.144.0

package/docs/reference/troubleshooting.md

@@ -0,0 +1,964 @@
+# Troubleshooting Guide
+
+Solutions to common issues when working with AwesCode UI framework.
+
+## Component Issues
+
+### Component Not Rendering
+
+**Problem:** Component doesn't appear on the page.
+
+**Possible Causes:**
+
+1. **Component not registered**
+```markup
+<!-- ❌ Component not found -->
+<AwCustomComponent />
+```
+
+**Solution:** Check if component is globally registered (atoms, molecules) or needs dynamic import (organisms, pages, layouts):
+```javascript
+// For organisms, pages, layouts
+export default {
+    components: {
+        AwForm: () => import('@awes-io/ui/components/3_organisms/AwForm.vue')
+    }
+}
+```
+
+2. **Component hidden by v-if**
+```markup
+<!-- ❌ Never renders if loading=true initially -->
+<AwTableBuilder v-if="!loading" :collection="customers" />
+```
+
+**Solution:** Let component handle its own loading state:
+```markup
+<!-- ✅ Component mounts and shows internal loading -->
+<AwTableBuilder :collection="customers" />
+```
+
+3. **Wrong component path**
+```javascript
+// ❌ Old path after reorganization
+import AwButton from '@awes-io/ui/docs/aw-button.md'
+
+// ✅ Correct path
+// AwButton is globally registered, no import needed
+```
+
+### Component Props Not Working
+
+**Problem:** Props don't seem to have any effect.
+
+**Debugging Steps:**
+
+1. Check prop name spelling:
+```markup
+<!-- ❌ Wrong prop name -->
+<AwButton colour="accent">Save</AwButton>
+
+<!-- ✅ Correct prop name -->
+<AwButton color="accent">Save</AwButton>
+```
+
+2. Check prop type:
+```markup
+<!-- ❌ String instead of boolean -->
+<AwButton loading="true">Save</AwButton>
+
+<!-- ✅ Boolean -->
+<AwButton :loading="true">Save</AwButton>
+```
+
+3. Check component documentation:
+```markup
+<!-- ✅ Refer to component docs for correct props -->
+<!-- See: packages/ui/docs/components/molecules/aw-button.md -->
+```
+
+### Events Not Firing
+
+**Problem:** Component events don't trigger methods.
+
+**Common Causes:**
+
+1. **Missing v-on or @**
+```markup
+<!-- ❌ Missing @ -->
+<AwButton click="save">Save</AwButton>
+
+<!-- ✅ Correct -->
+<AwButton @click="save">Save</AwButton>
+```
+
+2. **Wrong event name**
+```markup
+<!-- ❌ Wrong event name -->
+<AwTableBuilder @row-click="viewRow">
+
+<!-- ✅ Correct event name -->
+<AwTableBuilder @click:row="viewRow">
+```
+
+3. **Event bubbling stopped**
+```markup
+<!-- ❌ Click event stopped by child -->
+<AwTableBuilder @click:row="viewRow">
+    <template #dropdown="{ cell }">
+        <AwDropdownButton>
+            <!-- This stops row click -->
+        </AwDropdownButton>
+    </template>
+</AwTableBuilder>
+
+<!-- ✅ Use dropdown slot OR click:row, not both -->
+<AwTableBuilder :collection="customers">
+    <template #dropdown="{ cell }">
+        <AwDropdownButton>
+            <AwButton @click="edit(cell)">Edit</AwButton>
+        </AwDropdownButton>
+    </template>
+</AwTableBuilder>
+```
+
+## Data Fetching Issues
+
+### AwTableBuilder Not Fetching Data
+
+**Problem:** Table shows empty, data never loads.
+
+**Cause:** Table wrapped in v-if/v-else, preventing mount:
+```markup
+<!-- ❌ BAD - Table never mounts if loading=true -->
+<template>
+    <AwPage title="Customers">
+        <div v-if="loading">Loading...</div>
+        <AwTableBuilder v-else :collection="customers">
+            <!-- Never mounts! -->
+        </AwTableBuilder>
+    </AwPage>
+</template>
+
+<script>
+export default {
+    data() {
+        return {
+            loading: true,  // Starts true
+            customers: new Customers([])
+        }
+    }
+}
+</script>
+```
+
+**Solution:** Let AwTableBuilder handle loading:
+```markup
+<!-- ✅ GOOD - Table mounts and fetches automatically -->
+<template>
+    <AwPage title="Customers">
+        <AwTableBuilder :collection="customers">
+            <!-- Mounts immediately, shows internal loading state -->
+        </AwTableBuilder>
+    </AwPage>
+</template>
+
+<script>
+export default {
+    data() {
+        return {
+            customers: new Customers([], {
+                shop_uuid: this.$route.params.shop_uuid
+            })
+        }
+    }
+    // No loading flag needed!
+}
+</script>
+```
+
+### Collection Returns Empty Array
+
+**Problem:** API request succeeds but collection.models is empty.
+
+**Debugging Steps:**
+
+1. **Check response structure**
+```javascript
+// Expected structure
+{
+    "data": [...],  // Array of items
+    "meta": {...}   // Pagination meta
+}
+
+// If your API returns different structure, configure collection
+```
+
+2. **Check collection route**
+```javascript
+// In collection file
+routes() {
+    return {
+        fetch: '/api/shops/:shop_uuid/customers'  // Must match backend route
+    }
+}
+```
+
+3. **Check collection options**
+```javascript
+// ✅ Include shop_uuid in options
+customers: new Customers([], {
+    shop_uuid: this.$route.params.shop_uuid
+})
+
+// ❌ Missing shop_uuid
+customers: new Customers([])
+```
+
+4. **Inspect network request**
+```javascript
+// Open browser DevTools → Network tab
+// Check request URL and response
+```
+
+### Model Fetch Returns 404
+
+**Problem:** Fetching model returns 404 Not Found.
+
+**Debugging Steps:**
+
+1. **Check if model is new**
+```javascript
+// ✅ Don't fetch new models
+if (!this.model.isNew()) {
+    await this.model.fetch()
+}
+
+// ❌ Fetching new model fails
+await this.model.fetch()  // 404 if no ID
+```
+
+2. **Check model route**
+```javascript
+// In model file
+routes() {
+    return {
+        fetch: '/api/shops/:shop_uuid/customers/:id'
+    }
+}
+```
+
+3. **Check model has ID**
+```javascript
+// ✅ Model has ID
+const customer = new Customer(
+    { id: this.$route.params.id },
+    null,
+    { shop_uuid: this.$route.params.shop_uuid }
+)
+
+// ❌ Model has no ID
+const customer = new Customer({}, null, {})
+```
+
+### Infinite Loading / Fetch Loop
+
+**Problem:** Component keeps fetching data repeatedly.
+
+**Cause:** Watch triggers refetch, which triggers watch again:
+```javascript
+// ❌ Creates infinite loop
+watch: {
+    collection: {
+        handler() {
+            this.collection.fetch()  // Triggers watch again
+        },
+        deep: true
+    }
+}
+```
+
+**Solution:** Watch specific properties:
+```javascript
+// ✅ Watch route params instead
+watch: {
+    '$route.query.search': {
+        handler() {
+            this.collection.fetch()
+        }
+    }
+}
+
+// ✅ Or use AwTableBuilder watch-params
+<AwTableBuilder
+    :collection="customers"
+    :watch-params="['search', 'status']"
+/>
+```
+
+## Form & Validation Issues
+
+### Validation Errors Not Showing
+
+**Problem:** Form submits with errors but errors don't display.
+
+**Debugging Steps:**
+
+1. **Check :error binding**
+```markup
+<!-- ❌ No error binding -->
+<AwInput v-model="customer.name" label="Name" />
+
+<!-- ✅ Bind error from model -->
+<AwInput
+    v-model="customer.name"
+    :error="customer.errors.name"
+    label="Name"
+/>
+```
+
+2. **Check if errors exist**
+```javascript
+async save() {
+    await this.customer.save()
+
+    // ✅ Check for errors
+    if (Object.keys(this.customer.errors).length > 0) {
+        console.log('Errors:', this.customer.errors)
+        return
+    }
+}
+```
+
+3. **Check backend response format**
+```json
+// Expected format for 422 validation errors
+{
+    "message": "The given data was invalid.",
+    "errors": {
+        "name": ["The name field is required."],
+        "email": ["The email has already been taken."]
+    }
+}
+```
+
+### Form Not Submitting
+
+**Problem:** Clicking submit button does nothing.
+
+**Debugging Steps:**
+
+1. **Check button type**
+```markup
+<!-- ❌ Missing @click -->
+<AwButton color="accent">Save</AwButton>
+
+<!-- ✅ With click handler -->
+<AwButton color="accent" @click="save">Save</AwButton>
+```
+
+2. **Check for errors in method**
+```javascript
+async save() {
+    console.log('Save called')  // Add debug log
+
+    try {
+        await this.customer.save()
+        console.log('Save successful')
+    } catch (error) {
+        console.error('Save failed:', error)
+    }
+}
+```
+
+3. **Check button not disabled**
+```markup
+<!-- May be disabled during loading -->
+<AwButton
+    :disabled="saving"
+    :loading="saving"
+    @click="save"
+>
+    Save
+</AwButton>
+```
+
+### Model Save Succeeds but Errors Remain
+
+**Problem:** save() succeeds but model.errors still has errors.
+
+**Cause:** Validation errors return 422, which vue-mc treats as "success" with errors:
+```javascript
+// ✅ Always check errors after save
+await this.customer.save()
+
+if (Object.keys(this.customer.errors).length > 0) {
+    // Has validation errors even though save() didn't throw
+    this.$notify({
+        message: 'Please fix validation errors',
+        type: 'error'
+    })
+    return
+}
+
+// Actually saved successfully
+```
+
+## Table Issues
+
+### Rows Not Reactive When Using vue-mc Models
+
+**Problem:** Table rows (for example in `AwTableBuilder`) update only for the first row or only after calling `$forceUpdate` when using `@awes-io/vue-mc` models.
+
+**Cause:** The project uses different Vue versions for `@awes-io/ui` and `@awes-io/vue-mc`, so models are created in one Vue instance and rendered in another, breaking reactivity.
+
+**Solution:** Ensure the project has a single Vue version by configuring root `resolutions`:
+
+```json
+// package.json (root of monorepo)
+"resolutions": {
+    "vue": "2.7.16",
+    "vue-template-compiler": "2.7.16",
+    "vue-server-renderer": "2.7.16"
+}
+```
+
+Remove any Vue-specific `overrides` / `resolutions` from package-level configs (for example `packages/vue-mc/package.json`), reinstall dependencies, and verify a single Vue version with `yarn why vue`.
+
+### @click:row and #dropdown Conflict
+
+**Problem:** Row click doesn't work when dropdown is present.
+
+**Cause:** Cannot use both @click:row and #dropdown slot simultaneously:
+```markup
+<!-- ❌ BAD - Both click:row and dropdown -->
+<AwTableBuilder
+    :collection="customers"
+    @click:row="viewCustomer"
+>
+    <template #dropdown="{ cell }">
+        <AwDropdownButton>
+            <!-- This prevents row click -->
+        </AwDropdownButton>
+    </template>
+</AwTableBuilder>
+```
+
+**Solution:** Use ONLY #dropdown slot:
+```markup
+<!-- ✅ GOOD - Dropdown only -->
+<AwTableBuilder :collection="customers">
+    <AwTableCol field="name" title="Name" />
+
+    <template #dropdown="{ cell }">
+        <AwDropdownButton>
+            <AwButton @click="viewCustomer(cell)">View</AwButton>
+            <AwButton @click="editCustomer(cell)">Edit</AwButton>
+            <AwButton @click="deleteCustomer(cell)">Delete</AwButton>
+        </AwDropdownButton>
+    </template>
+</AwTableBuilder>
+```
+
+### Table Column Shows [object Object]
+
+**Problem:** Table cell displays "[object Object]" instead of value.
+
+**Cause:** Field prop behavior - with field prop, cell = value only; without field, cell = entire row:
+```markup
+<!-- ❌ BAD - Trying to access object property with field prop -->
+<AwTableCol field="address" title="Address">
+    <template #default="{ cell }">
+        {{ cell.city }}  <!-- cell is just address object, not whole row -->
+    </template>
+</AwTableCol>
+```
+
+**Solution 1:** Don't use field prop:
+```markup
+<!-- ✅ GOOD - No field prop, cell = entire row -->
+<AwTableCol title="Address">
+    <template #default="{ cell }">
+        {{ cell.address.city }}
+    </template>
+</AwTableCol>
+```
+
+**Solution 2:** Use field prop correctly:
+```markup
+<!-- ✅ GOOD - Format the field value directly -->
+<AwTableCol field="address" title="Address">
+    <template #default="{ cell }">
+        {{ cell.city }}, {{ cell.state }}
+    </template>
+</AwTableCol>
+```
+
+### Table Pagination Not Working
+
+**Problem:** Pagination controls don't appear or don't work.
+
+**Debugging Steps:**
+
+1. **Check backend returns pagination meta**
+```json
+{
+    "data": [...],
+    "meta": {
+        "current_page": 1,
+        "last_page": 10,
+        "per_page": 15,
+        "total": 145
+    }
+}
+```
+
+2. **Check collection route accepts page param**
+```javascript
+// Backend should handle ?page=2
+GET /api/customers?page=2
+```
+
+3. **Check AwTableBuilder has pagination prop (if needed)**
+```markup
+<!-- Usually automatic, but can disable -->
+<AwTableBuilder
+    :collection="customers"
+    :pagination="true"
+/>
+```
+
+## Styling Issues
+
+### Styles Not Applying
+
+**Problem:** Custom styles don't apply to component.
+
+**Common Causes:**
+
+1. **CSS specificity**
+```scss
+// ❌ Not specific enough
+.aw-button {
+    background: red;
+}
+
+// ✅ More specific or use !important
+.custom-btn.aw-button {
+    background: red !important;
+}
+```
+
+2. **Scoped styles**
+```markup
+<!-- ❌ Scoped styles don't affect child components -->
+<style scoped>
+.aw-button {
+    background: red;  // Won't work
+}
+</style>
+
+<!-- ✅ Use deep selector -->
+<style scoped>
+::v-deep .aw-button {
+    background: red;
+}
+</style>
+
+<!-- ✅ Or remove scoped -->
+<style>
+.custom-page .aw-button {
+    background: red;
+}
+</style>
+```
+
+3. **Loading state preventing styles**
+```scss
+// ❌ Applies even during loading
+.custom-btn {
+    background-color: var(--c-accent) !important;
+}
+
+// ✅ Exclude loading state
+.custom-btn:not([disabled]):not(.loading) {
+    background-color: var(--c-accent) !important;
+}
+```
+
+### Dark Theme Not Working
+
+**Problem:** Dark theme colors don't apply.
+
+**Debugging Steps:**
+
+1. **Check theme plugin loaded**
+```javascript
+// In nuxt.config.js, @awes-io/ui module should be registered
+modules: [
+    '@awes-io/ui'
+]
+```
+
+2. **Use CSS custom properties**
+```scss
+// ✅ Use theme variables
+.custom-element {
+    background: var(--c-background);
+    color: var(--c-text);
+}
+
+// ❌ Hard-coded colors
+.custom-element {
+    background: #fff;
+    color: #000;
+}
+```
+
+3. **Check dark class on html**
+```javascript
+// Should add .dark class to <html> when dark theme active
+document.documentElement.classList.contains('dark')
+```
+
+## Date & Time Issues
+
+### Dates Not Formatting Correctly
+
+**Problem:** Dates show as raw strings or errors.
+
+**Solution:** Use $dayjs, not native Date:
+```markup
+<!-- ❌ BAD - Raw date string -->
+{{ customer.created_at }}
+
+<!-- ❌ BAD - Native Date -->
+{{ new Date(customer.created_at).toLocaleDateString() }}
+
+<!-- ✅ GOOD - Use $dayjs -->
+{{ $dayjs(customer.created_at).format('ll') }}
+```
+
+**Remember template vs method usage:**
+```markup
+<template>
+    <!-- ✅ Without this in templates -->
+    {{ $dayjs(date).format('ll') }}
+</template>
+
+<script>
+export default {
+    methods: {
+        formatDate(date) {
+            // ✅ With this in methods
+            return this.$dayjs(date).format('ll')
+        }
+    }
+}
+</script>
+```
+
+### Dates in Wrong Timezone
+
+**Problem:** Dates show in wrong timezone.
+
+**Solution:** Configure Day.js timezone plugin:
+```javascript
+// In plugin or component
+import dayjs from 'dayjs'
+import utc from 'dayjs/plugin/utc'
+import timezone from 'dayjs/plugin/timezone'
+
+dayjs.extend(utc)
+dayjs.extend(timezone)
+
+// Set timezone
+dayjs.tz.setDefault('America/New_York')
+
+// Use in templates
+this.$dayjs(date).tz('America/New_York').format('ll')
+```
+
+## Router Issues
+
+### Navigation Not Working
+
+**Problem:** Clicking link/button doesn't navigate.
+
+**Debugging Steps:**
+
+1. **Check href vs @click**
+```markup
+<!-- ✅ For navigation, use href -->
+<AwButton :href="`/customers/${customer.id}`">
+    View
+</AwButton>
+
+<!-- ✅ Or use @click with router.push -->
+<AwButton @click="$router.push(`/customers/${customer.id}`)">
+    View
+</AwButton>
+
+<!-- ❌ Missing navigation -->
+<AwButton>View</AwButton>
+```
+
+2. **Check route exists**
+```javascript
+// Verify route exists in pages/ directory
+pages/
+  shops/
+    _shop_uuid/
+      customers/
+        _id.vue  // Must exist
+```
+
+3. **Check route params**
+```javascript
+// ✅ Include all required params
+this.$router.push({
+    name: 'shops-shop_uuid-customers-id',
+    params: {
+        shop_uuid: this.$route.params.shop_uuid,
+        id: customer.id
+    }
+})
+```
+
+### pushBack Not Going Anywhere
+
+**Problem:** router.pushBack() doesn't navigate.
+
+**Cause:** Back route not set with setBack:
+```javascript
+// ❌ pushBack without setBack
+this.$router.pushBack()  // Does nothing
+```
+
+**Solution:** Set back route first:
+```javascript
+// ✅ On list page
+mounted() {
+    this.$router.setBack(`/shops/${this.$route.params.shop_uuid}/customers`)
+}
+
+// ✅ On detail page
+methods: {
+    cancel() {
+        // Goes to route set by setBack
+        this.$router.pushBack()
+    }
+}
+```
+
+## Performance Issues
+
+### Page Slow to Load
+
+**Problem:** Page takes long time to render.
+
+**Common Causes:**
+
+1. **Loading too much data**
+```javascript
+// ❌ Fetching all records
+customers: new Customers([])  // Could be thousands
+
+// ✅ Use pagination
+customers: new Customers([], {
+    shop_uuid: this.$route.params.shop_uuid,
+    per_page: 25
+})
+```
+
+2. **Too many watchers**
+```javascript
+// ❌ Deep watchers on large objects
+watch: {
+    customers: {
+        handler() { ... },
+        deep: true  // Expensive
+    }
+}
+
+// ✅ Watch specific properties
+watch: {
+    'customers.models.length': {
+        handler() { ... }
+    }
+}
+```
+
+3. **Inefficient computed properties**
+```javascript
+// ❌ Filters array every time
+computed: {
+    activeCustomers() {
+        return this.customers.models.filter(c => c.active)  // Runs on every change
+    }
+}
+
+// ✅ Cache or use backend filtering
+customers: new Customers([], {
+    shop_uuid: this.$route.params.shop_uuid,
+    status: 'active'  // Filter on backend
+})
+```
+
+### Table Slow to Render
+
+**Problem:** AwTableBuilder slow with many rows.
+
+**Solutions:**
+
+1. **Reduce per_page**
+```javascript
+customers: new Customers([], {
+    shop_uuid: this.$route.params.shop_uuid,
+    per_page: 15  // Fewer rows per page
+})
+```
+
+2. **Simplify cell templates**
+```markup
+<!-- ❌ Complex calculations in cell -->
+<AwTableCol field="total" title="Total">
+    <template #default="{ cell, row }">
+        {{ complexCalculation(row) }}
+    </template>
+</AwTableCol>
+
+<!-- ✅ Calculate on backend or cache -->
+<AwTableCol field="total_formatted" title="Total" />
+```
+
+3. **Use field prop when possible**
+```markup
+<!-- ✅ Fast - direct field access -->
+<AwTableCol field="name" title="Name" />
+
+<!-- ❌ Slower - custom template -->
+<AwTableCol title="Name">
+    <template #default="{ cell }">
+        {{ cell.name }}
+    </template>
+</AwTableCol>
+```
+
+## Authentication Issues
+
+### User Not Redirected to Login
+
+**Problem:** Accessing protected page doesn't redirect to login.
+
+**Debugging Steps:**
+
+1. **Check middleware**
+```javascript
+// ✅ Page has auth middleware
+export default {
+    middleware: 'auth'
+}
+```
+
+2. **Check nuxt-auth config**
+```javascript
+// In nuxt.config.js
+auth: {
+    strategies: {
+        laravelJWT: {
+            // ...
+            redirect: {
+                login: '/login',
+                logout: '/login',
+                home: '/dashboard'
+            }
+        }
+    }
+}
+```
+
+3. **Check token**
+```javascript
+// In browser console
+console.log(this.$auth.loggedIn)
+console.log(this.$auth.token)
+```
+
+### API Requests Return 401
+
+**Problem:** API requests fail with 401 Unauthorized.
+
+**Debugging Steps:**
+
+1. **Check token in request headers**
+```javascript
+// Open DevTools → Network → Select request → Headers
+// Should have: Authorization: Bearer <token>
+```
+
+2. **Check token expiration**
+```javascript
+// In browser console
+const payload = JSON.parse(atob(this.$auth.token.split('.')[1]))
+console.log('Expires:', new Date(payload.exp * 1000))
+```
+
+3. **Check nuxt-auth strategy config**
+```javascript
+auth: {
+    strategies: {
+        laravelJWT: {
+            url: process.env.LARAVEL_URL,
+            endpoints: {
+                login: { url: '/api/auth/login', method: 'post' },
+                refresh: { url: '/api/auth/refresh', method: 'post' },
+                user: { url: '/api/auth/me', method: 'get' }
+            }
+        }
+    }
+}
+```
+
+## Getting Help
+
+If you can't find a solution here:
+
+1. **Check component documentation**
+   - [Component Index](../index.md)
+   - Individual component docs in [components/](../components/)
+
+2. **Check integration guides**
+   - [Integration Guide](../integrations.md)
+   - [Best Practices](../guides/best-practices.md)
+
+3. **Enable debug mode**
+```javascript
+// In nuxt.config.js
+export default {
+    build: {
+        extend(config, { isDev }) {
+            if (isDev) {
+                config.devtool = 'source-map'
+            }
+        }
+    }
+}
+```
+
+4. **Check browser console**
+   - Look for errors or warnings
+   - Check network requests (DevTools → Network)
+   - Inspect Vue component tree (Vue DevTools)
+
+5. **Minimal reproduction**
+   - Create minimal example that reproduces issue
+   - Isolate component causing problem
+   - Test with default props
+
+## See Also
+
+- [Error Handling Guide](../guides/error-handling.md) - Handling errors properly
+- [Data Fetching Guide](../guides/data-fetching.md) - Collection and model patterns
+- [Best Practices Guide](../guides/best-practices.md) - Avoiding common issues
+- [Plugins Reference](./plugins.md) - Using framework utilities