@awes-io/ui 2.142.0 → 2.143.0

package/docs/integrations.md

@@ -0,0 +1,870 @@
+# Package Integration Guide
+
+Complete guide to integrating all AwesCode UI packages together for a full-stack Nuxt.js + Laravel application.
+
+## Framework Architecture
+
+The AwesCode UI framework consists of four interconnected packages that work together:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Nuxt.js Application                      │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  @awes-io/ui (Components & Pages)                           │
+│  - AwPage, AwTableBuilder, AwForm                           │
+│  - Global components (atoms, molecules)                      │
+│  - Page layouts and navigation                               │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  @awes-io/nuxt-auth (Authentication)                        │
+│  - $auth object and user state                              │
+│  - Login, register, 2FA, OAuth                               │
+│  - Route protection middleware                               │
+│  - JWT token management                                      │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  @awes-io/nuxt-laravel (Backend Integration)                │
+│  - API proxy configuration                                   │
+│  - Axios setup and base URL                                  │
+│  - Build process (Nuxt → Laravel public)                     │
+│  - Version plugin                                            │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  @awes-io/vue-mc (Models & Collections)                     │
+│  - BaseModel for single resources                           │
+│  - BaseCollection for lists                                  │
+│  - Automatic API communication                               │
+│  - Validation and error handling                             │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+                    ┌─────────────────┐
+                    │  Laravel Backend │
+                    │  (API endpoints) │
+                    └─────────────────┘
+```
+
+## Data Flow
+
+**Typical request flow:**
+
+1. User interacts with **UI component** (AwTableBuilder, AwForm)
+2. Component uses **vue-mc Model/Collection** for data operations
+3. Model/Collection makes request via **$axios** (configured by nuxt-laravel)
+4. **nuxt-auth** adds JWT token to request headers
+5. **nuxt-laravel proxy** forwards request to Laravel backend
+6. Laravel processes request and returns response
+7. Model/Collection updates and notifies UI component
+8. Component re-renders with new data
+
+## Package Overview
+
+### 1. UI Components (@awes-io/ui)
+
+**Purpose**: Pre-built Vue components for building application interfaces
+
+**Key Features**:
+- 102+ components organized by atomic design
+- Page components (AwPage, AwPageSingle)
+- Form components with validation
+- Table builder with auto-fetching
+- Layout system with navigation
+
+**Documentation**: [./index.md](./index.md)
+
+### 2. Vue-MC (@awes-io/vue-mc)
+
+**Purpose**: Model-Collection layer for API data management
+
+**Key Features**:
+- BaseModel for single resources
+- BaseCollection for lists with pagination
+- Automatic API communication
+- Built-in validation
+- Lifecycle hooks
+
+**Documentation**: [../../vue-mc/docs/](../../vue-mc/docs/)
+
+### 3. Nuxt-Auth (@awes-io/nuxt-auth)
+
+**Purpose**: Complete authentication solution
+
+**Key Features**:
+- JWT authentication with Laravel backend
+- Two-factor authentication (2FA)
+- Social login (OAuth)
+- Email verification
+- Password reset
+- Route protection middleware
+
+**Documentation**: [../../nuxt-auth/docs/](../../nuxt-auth/docs/)
+
+### 4. Nuxt-Laravel (@awes-io/nuxt-laravel)
+
+**Purpose**: Integration layer between Nuxt.js and Laravel
+
+**Key Features**:
+- API proxy for development and production
+- Automatic axios configuration
+- Build process (Nuxt → Laravel public)
+- Version plugin for tracking deployments
+
+**Documentation**: [../../nuxt-laravel/docs/](../../nuxt-laravel/docs/)
+
+## Complete Setup Example
+
+### 1. Installation
+
+```bash
+# Install all packages
+yarn add @awes-io/ui @awes-io/vue-mc @awes-io/nuxt-auth @awes-io/nuxt-laravel
+
+# Install peer dependencies
+yarn add @nuxtjs/axios dayjs
+```
+
+### 2. Project Structure
+
+```
+project-root/
+├── app/                        # Laravel application
+├── resources/
+│   └── nuxt/                   # Nuxt source code
+│       ├── assets/
+│       ├── components/
+│       ├── layouts/
+│       ├── pages/
+│       ├── models/             # Vue-MC models
+│       ├── collections/        # Vue-MC collections
+│       └── plugins/
+├── storage/app/nuxt/           # Nuxt build output
+├── public/                     # Laravel public (serves SPA)
+├── nuxt.config.js              # Nuxt configuration
+├── package.json                # NPM dependencies
+└── composer.json               # Composer dependencies
+```
+
+### 3. Environment Variables
+
+**`.env`** (Laravel root):
+
+```bash
+# Laravel backend URL
+LARAVEL_URL=http://localhost:8000
+
+# Frontend URL (for CORS)
+FRONTEND_URL=http://localhost:3000
+
+# Direct API URL (production, skip proxy)
+NON_PROXY_URL=https://api.example.com
+
+# Application info (for version plugin)
+APP_NAME=MyApplication
+APP_VERSION=v1.0.0
+APP_VERSION_DATE=2024-01-15T10:00:00Z
+
+# Laravel settings
+APP_URL=http://localhost:8000
+SESSION_DRIVER=cookie
+SESSION_DOMAIN=localhost
+SANCTUM_STATEFUL_DOMAINS=localhost:3000
+```
+
+### 4. Nuxt Configuration
+
+**`nuxt.config.js`**:
+
+```javascript
+export default {
+    // SPA mode
+    mode: 'spa',
+
+    // Nuxt source directory
+    srcDir: 'resources/nuxt',
+
+    // Modules (ORDER MATTERS!)
+    modules: [
+        // 1. Laravel integration (includes axios)
+        '@awes-io/nuxt-laravel',
+
+        // 2. Authentication
+        '@awes-io/nuxt-auth',
+
+        // 3. UI components
+        '@awes-io/ui'
+    ],
+
+    // Module options
+    awesIo: {
+        nuxtLaravel: {
+            generateDir: 'storage/app/nuxt',
+            versionPlugin: {
+                name: process.env.APP_NAME,
+                version: process.env.APP_VERSION,
+                date: process.env.APP_VERSION_DATE
+            }
+        },
+        nuxtAuth: {
+            register: true,           // Enable registration
+            socialLogin: true,        // Enable OAuth
+            twoFactor: true,         // Enable 2FA
+            emailVerification: true  // Enable email verification
+        }
+    },
+
+    // Environment variables available in app
+    env: {
+        laravelUrl: process.env.LARAVEL_URL || 'http://localhost:8000',
+        frontendUrl: process.env.FRONTEND_URL || 'http://localhost:3000'
+    },
+
+    // Build configuration
+    build: {
+        extractCSS: true,
+        optimizeCSS: true,
+        transpile: ['@awes-io/ui', '@awes-io/vue-mc']
+    }
+}
+```
+
+### 5. Package Scripts
+
+**`package.json`**:
+
+```json
+{
+    "scripts": {
+        "dev": "LARAVEL_URL=http://localhost:8000 nuxt",
+        "build": "LARAVEL_URL=http://localhost:8000 nuxt build",
+        "generate": "LARAVEL_URL=http://localhost:8000 nuxt generate",
+        "start": "LARAVEL_URL=http://localhost:8000 nuxt start"
+    }
+}
+```
+
+### 6. Laravel Configuration
+
+**`config/cors.php`**:
+
+```php
+return [
+    'paths' => ['api/*', 'broadcasting/*', 'sanctum/csrf-cookie'],
+    'allowed_methods' => ['*'],
+    'allowed_origins' => [env('FRONTEND_URL', 'http://localhost:3000')],
+    'allowed_origins_patterns' => [],
+    'allowed_headers' => ['*'],
+    'exposed_headers' => [],
+    'max_age' => 0,
+    'supports_credentials' => true,
+];
+```
+
+**`routes/web.php`** (serve Nuxt SPA):
+
+```php
+// Serve Nuxt SPA for all routes (except API)
+Route::fallback(function () {
+    return file_get_contents(public_path('index.html'));
+});
+```
+
+## Integration Patterns
+
+### Pattern 1: Authenticated API Call with Vue-MC
+
+**Create a Model** (`resources/nuxt/models/User.js`):
+
+```javascript
+import { BaseModel } from '@awes-io/vue-mc'
+
+export default class User extends BaseModel {
+    defaults() {
+        return {
+            id: null,
+            name: '',
+            email: '',
+            role: 'user',
+            created_at: null
+        }
+    }
+
+    routes() {
+        return {
+            fetch: '/api/users/{id}',
+            save: '/api/users',
+            update: '/api/users/{id}',
+            delete: '/api/users/{id}'
+        }
+    }
+
+    validation() {
+        return {
+            name: 'required|string|min:2',
+            email: 'required|email'
+        }
+    }
+}
+```
+
+**Create a Collection** (`resources/nuxt/collections/Users.js`):
+
+```javascript
+import { BaseCollection } from '@awes-io/vue-mc'
+import User from '~/models/User'
+
+export default class Users extends BaseCollection {
+    model() {
+        return User
+    }
+
+    routes() {
+        return {
+            fetch: '/api/users'
+        }
+    }
+}
+```
+
+**Use in Protected Page** (`resources/nuxt/pages/users/index.vue`):
+
+```markup
+<template>
+    <AwPage title="Users">
+        <!-- Header actions (create button) -->
+        <template #header-actions>
+            <AwButton
+                href="/users/create"
+                text="Create User"
+                icon="plus"
+            />
+        </template>
+
+        <!-- Table with automatic fetching -->
+        <AwTableBuilder
+            :collection="users"
+            :options="{ shop_uuid: $auth.user.shop_uuid }"
+        >
+            <AwTableCol field="name" label="Name" />
+            <AwTableCol field="email" label="Email" />
+            <AwTableCol field="role" label="Role" />
+            <AwTableCol label="Created">
+                <template #default="{ data }">
+                    {{ $dayjs(data.created_at).format('ll') }}
+                </template>
+            </AwTableCol>
+
+            <!-- Row actions dropdown -->
+            <template #dropdown="{ cell }">
+                <AwDropdownButton>
+                    <AwButton
+                        :href="`/users/${cell.id}`"
+                        theme="text"
+                        text="View"
+                    />
+                    <AwButton
+                        :href="`/users/${data.id}/edit`"
+                        theme="text"
+                        text="Edit"
+                    />
+                    <AwButton
+                        @click="deleteUser(data)"
+                        theme="text"
+                        color="error"
+                        text="Delete"
+                    />
+                </AwDropdownButton>
+            </template>
+        </AwTableBuilder>
+    </AwPage>
+</template>
+
+<script>
+import Users from '~/collections/Users'
+
+export default {
+    // Require authentication
+    middleware: 'auth',
+
+    data() {
+        return {
+            users: new Users()
+        }
+    },
+
+    methods: {
+        async deleteUser(user) {
+            const isConfirmed = await this.$confirm({
+                title: 'Delete User',
+                message: `Are you sure you want to delete ${user.name}?`
+            })
+
+            if (!isConfirmed) return
+
+            try {
+                await this.$axios.delete(`/api/users/${user.id}`)
+                this.$notify({
+                    message: 'User deleted successfully',
+                    type: 'success'
+                })
+                // Refetch collection
+                this.users.fetch()
+            } catch (error) {
+                this.$notify({
+                    message: 'Failed to delete user',
+                    type: 'error'
+                })
+            }
+        }
+    }
+}
+</script>
+```
+
+**What Happens**:
+1. ✅ **nuxt-auth** middleware checks authentication
+2. ✅ **AwTableBuilder** creates Users collection with shop_uuid
+3. ✅ Collection automatically fetches from `/api/users`
+4. ✅ **nuxt-laravel** proxies request to Laravel backend
+5. ✅ **nuxt-auth** adds JWT token to request
+6. ✅ Laravel returns paginated user data
+7. ✅ Table displays data with automatic pagination
+
+### Pattern 2: Create/Edit Page with Form Validation
+
+**Create/Edit Page** (`resources/nuxt/pages/users/_id.vue`):
+
+```markup
+<template>
+    <AwPageSingle
+        :title="isNew ? 'Create User' : 'Edit User'"
+        hide-menu
+    >
+        <!-- Save button in header -->
+        <template #buttons>
+            <AwButton
+                @click="save"
+                :loading="model.saving"
+                text="Save"
+                icon="check"
+            />
+        </template>
+
+        <!-- Form with validation -->
+        <AwCard>
+            <AwGrid>
+                <AwInput
+                    v-model="model.name"
+                    label="Name"
+                    :error="model.errors.name"
+                    required
+                />
+
+                <AwInput
+                    v-model="model.email"
+                    label="Email"
+                    type="email"
+                    :error="model.errors.email"
+                    required
+                />
+
+                <AwSelect
+                    v-model="model.role"
+                    label="Role"
+                    :options="['user', 'admin', 'manager']"
+                    :error="model.errors.role"
+                />
+
+                <AwPassword
+                    v-if="isNew"
+                    v-model="model.password"
+                    label="Password"
+                    :error="model.errors.password"
+                    required
+                />
+            </AwGrid>
+        </AwCard>
+    </AwPageSingle>
+</template>
+
+<script>
+import User from '~/models/User'
+
+export default {
+    middleware: 'auth',
+
+    data() {
+        return {
+            model: new User({ id: this.$route.params.id })
+        }
+    },
+
+    computed: {
+        isNew() {
+            return this.model.isNew()
+        }
+    },
+
+    async mounted() {
+        if (!this.isNew) {
+            try {
+                await this.model.fetch()
+            } catch (error) {
+                // Redirect on 404
+                this.$notify({
+                    message: 'User not found',
+                    type: 'error'
+                })
+                this.$router.push('/users')
+            }
+        }
+    },
+
+    methods: {
+        async save() {
+            try {
+                await this.model.save()
+
+                // Check for validation errors
+                if (Object.keys(this.model.errors).length > 0) {
+                    this.$notify({
+                        message: 'Please fix validation errors',
+                        type: 'error'
+                    })
+                    return
+                }
+
+                this.$notify({
+                    message: `User ${this.isNew ? 'created' : 'updated'} successfully`,
+                    type: 'success'
+                })
+
+                this.$router.push('/users')
+            } catch (error) {
+                this.$notify({
+                    message: 'Failed to save user',
+                    type: 'error'
+                })
+            }
+        }
+    }
+}
+</script>
+```
+
+**What Happens**:
+1. ✅ Page loads model with ID from route
+2. ✅ If existing user, model.fetch() retrieves data
+3. ✅ Form fields bound to model properties
+4. ✅ On save, model.save() sends POST/PUT request
+5. ✅ Laravel validates and returns errors (422 status)
+6. ✅ Model populates `errors` object
+7. ✅ Error messages display next to fields
+8. ✅ On success, redirect to list page
+
+### Pattern 3: Real-Time Data with Broadcasting
+
+**Setup** (requires Laravel Broadcasting):
+
+```javascript
+// nuxt.config.js
+export default {
+    modules: [
+        '@awes-io/nuxt-laravel',
+        '@awes-io/nuxt-auth',
+        '@awes-io/ui',
+        '@nuxtjs/socket.io' // Add socket.io
+    ],
+
+    io: {
+        sockets: [{
+            url: process.env.LARAVEL_URL,
+            default: true
+        }]
+    }
+}
+```
+
+**Component with Real-Time Updates**:
+
+```markup
+<template>
+    <AwPage title="Notifications">
+        <div v-for="notification in notifications" :key="notification.id">
+            <AwAlert :type="notification.type">
+                {{ notification.message }}
+            </AwAlert>
+        </div>
+    </AwPage>
+</template>
+
+<script>
+export default {
+    middleware: 'auth',
+
+    data() {
+        return {
+            notifications: []
+        }
+    },
+
+    mounted() {
+        // Subscribe to private channel
+        this.$socket.private(`user.${this.$auth.user.id}`)
+            .listen('NotificationSent', (notification) => {
+                this.notifications.unshift(notification)
+                this.$notify({
+                    message: notification.message,
+                    type: notification.type
+                })
+            })
+    }
+}
+</script>
+```
+
+### Pattern 4: Permission-Based UI Rendering
+
+```markup
+<template>
+    <AwPage title="Dashboard">
+        <!-- Admin-only section -->
+        <AwCard v-if="$auth.user.role === 'admin'">
+            <h2>Admin Statistics</h2>
+            <!-- Admin content -->
+        </AwCard>
+
+        <!-- Manager and above -->
+        <AwCard v-if="canManage">
+            <h2>Team Management</h2>
+            <!-- Management content -->
+        </AwCard>
+
+        <!-- Everyone sees this -->
+        <AwCard>
+            <h2>Your Activity</h2>
+            <!-- User activity -->
+        </AwCard>
+    </AwPage>
+</template>
+
+<script>
+export default {
+    middleware: 'auth',
+
+    computed: {
+        canManage() {
+            return ['admin', 'manager'].includes(this.$auth.user.role)
+        }
+    }
+}
+</script>
+```
+
+## Common Integration Issues
+
+### Issue 1: API Requests Not Proxied
+
+**Symptom**: CORS errors or 404 on API calls
+
+**Solution**: Check environment variables
+
+```bash
+# Verify LARAVEL_URL is set
+echo $LARAVEL_URL
+
+# Check proxy configuration in network tab
+# Should see requests to /api/* being proxied
+```
+
+**Fix**:
+```bash
+# Set in package.json scripts
+"dev": "LARAVEL_URL=http://localhost:8000 nuxt"
+```
+
+### Issue 2: Authentication Not Persisting
+
+**Symptom**: User logged out on page refresh
+
+**Solution**: Check Laravel session/CORS config
+
+```php
+// config/cors.php
+'supports_credentials' => true,
+
+// config/session.php
+'domain' => env('SESSION_DOMAIN', null), // Set to null for localhost
+```
+
+### Issue 3: Models Not Receiving Auth Token
+
+**Symptom**: 401 errors on authenticated requests
+
+**Solution**: Ensure module order in nuxt.config.js
+
+```javascript
+modules: [
+    '@awes-io/nuxt-laravel',  // FIRST (configures axios)
+    '@awes-io/nuxt-auth',     // SECOND (adds token interceptor)
+    '@awes-io/ui'             // THIRD (uses axios)
+]
+```
+
+### Issue 4: Build Files Not Copied to Public
+
+**Symptom**: `public/_nuxt/` empty after generate
+
+**Solution**: Check generateDir matches Laravel structure
+
+```javascript
+// nuxt.config.js
+awesIo: {
+    nuxtLaravel: {
+        generateDir: 'storage/app/nuxt'  // Must match Laravel structure
+    }
+}
+```
+
+### Issue 5: Components Not Rendering
+
+**Symptom**: `<AwButton>` renders as empty
+
+**Solution**: Ensure UI module is loaded
+
+```javascript
+// nuxt.config.js
+modules: [
+    '@awes-io/ui'  // Registers global components
+]
+```
+
+## Development Workflow
+
+### 1. Start Development Servers
+
+```bash
+# Terminal 1: Laravel backend
+php artisan serve
+# Listening on http://localhost:8000
+
+# Terminal 2: Nuxt frontend
+yarn dev
+# Listening on http://localhost:3000
+```
+
+### 2. Hot Reload
+
+- Frontend changes: Automatic hot reload
+- Backend changes: Restart Laravel server if needed
+
+### 3. Database Migrations
+
+```bash
+# Run migrations
+php artisan migrate
+
+# Seed data
+php artisan db:seed
+```
+
+## Production Deployment
+
+### 1. Build Frontend
+
+```bash
+# Generate static files
+yarn generate
+
+# Output: storage/app/nuxt/ → public/_nuxt/
+```
+
+### 2. Configure Environment
+
+```bash
+# .env (production)
+APP_ENV=production
+LARAVEL_URL=https://api.example.com
+NON_PROXY_URL=https://api.example.com
+FRONTEND_URL=https://example.com
+```
+
+### 3. Deploy Laravel
+
+```bash
+# Standard Laravel deployment
+composer install --optimize-autoloader --no-dev
+php artisan config:cache
+php artisan route:cache
+php artisan view:cache
+```
+
+### 4. Serve Application
+
+Laravel serves the Nuxt SPA via `public/index.html` with all routes handled by the SPA router.
+
+## Testing Integration
+
+### Component Testing
+
+```javascript
+// components/__tests__/UserList.spec.js
+import { mount } from '@vue/test-utils'
+import UserList from '~/components/UserList'
+import Users from '~/collections/Users'
+
+describe('UserList', () => {
+    it('displays users from collection', async () => {
+        const users = new Users([
+            { id: 1, name: 'Alice' },
+            { id: 2, name: 'Bob' }
+        ])
+
+        const wrapper = mount(UserList, {
+            data: () => ({ users })
+        })
+
+        expect(wrapper.text()).toContain('Alice')
+        expect(wrapper.text()).toContain('Bob')
+    })
+})
+```
+
+### E2E Testing
+
+```javascript
+// tests/e2e/auth.spec.js
+describe('Authentication', () => {
+    it('can login and access protected page', () => {
+        cy.visit('/login')
+        cy.get('[name=email]').type('user@example.com')
+        cy.get('[name=password]').type('password')
+        cy.get('button[type=submit]').click()
+
+        cy.url().should('include', '/dashboard')
+        cy.contains('Welcome back')
+    })
+})
+```
+
+## Next Steps
+
+- **Build Pages**: See [Page Pattern Guides](./guides/page-patterns/)
+- **Best Practices**: See [Best Practices Guide](./guides/best-practices.md)
+- **Forms**: See [Forms Guide](./guides/forms-guide.md)
+- **Components**: Browse [Component Documentation](./components/)
+
+## External Resources
+
+- [Nuxt.js Documentation](https://nuxtjs.org/)
+- [Laravel Documentation](https://laravel.com/docs)
+- [Vue.js Guide](https://vuejs.org/guide/)
+- [Axios Documentation](https://axios-http.com/docs/)