@awes-io/ui 2.142.3 → 2.143.0

package/docs/getting-started.md

@@ -0,0 +1,596 @@
+---
+metaTitle: Getting Started | AwesCode UI
+meta:
+  - name: description
+    content: Quick start guide for AwesCode UI component library - installation, setup, and basic usage.
+title: Getting Started
+---
+
+# Getting Started
+
+Get up and running with AwesCode UI component library in minutes.
+
+## Framework Overview
+
+The AwesCode UI framework consists of 4 integrated packages:
+
+1. **@awes-io/ui** - UI component library (this package)
+2. **@awes-io/nuxt-laravel** - Laravel backend integration
+3. **@awes-io/nuxt-auth** - Authentication with JWT and 2FA
+4. **vue-mc** - Model and collection layer for API data
+
+For complete integration guide, see [Framework Integration](./integrations.md).
+
+## Installation
+
+Install the packages via npm or yarn:
+
+```bash
+# UI components (required)
+npm install @awes-io/ui
+
+# Laravel integration (recommended)
+npm install @awes-io/nuxt-laravel
+
+# Authentication (recommended)
+npm install @awes-io/nuxt-auth
+
+# or install all at once
+npm install @awes-io/ui @awes-io/nuxt-laravel @awes-io/nuxt-auth
+```
+
+## Setup
+
+### Nuxt.js Setup
+
+Add the modules to your `nuxt.config.js`:
+
+```javascript
+export default {
+  modules: [
+    '@awes-io/nuxt-laravel',  // 1. Laravel integration
+    '@awes-io/nuxt-auth',     // 2. Authentication
+    '@awes-io/ui'             // 3. UI components
+  ],
+
+  // Required: Enable components auto-import
+  components: true,
+
+  // Required: Enable Vuex store
+  store: true,
+
+  // Environment variables
+  env: {
+    LARAVEL_URL: process.env.LARAVEL_URL || 'http://localhost:8000'
+  }
+}
+```
+
+### Configuration
+
+The framework supports two types of configuration:
+
+1. **Static Configuration** (`awes.config.js`) - For logos, colors, fonts, and i18n settings
+2. **Dynamic Component Configuration** (Plugin) - For component defaults that may change at runtime
+
+#### Quick Setup
+
+Create `awes.config.js` in your project root:
+
+```javascript
+export default {
+  logo: {
+    src: '/logo.svg',
+    alt: 'My App'
+  }
+}
+
+export const dark = {
+  logo: {
+    src: '/logo-dark.svg'
+  }
+}
+
+// Optional: Configure i18n if you need to customize language settings
+// Defaults are: locale: 'en', locales: ['en']
+export const lang = {
+  locales: ['en', 'es', 'fr'],
+  locale: 'en'
+}
+```
+
+Create `plugins/components.js` for dynamic component configuration:
+
+```javascript
+import Vue from 'vue'
+import { CONFIG_VAR } from '@AwUtils/component'
+
+export default async ({ app }) => {
+  Vue.prototype[CONFIG_VAR] = Vue.prototype[CONFIG_VAR] || {}
+
+  // Configure component defaults
+  Vue.prototype[CONFIG_VAR].AwButton = {
+    size: 'md',
+    color: 'accent',
+    theme: 'solid'
+  }
+}
+```
+
+Register the plugin in `nuxt.config.js`:
+
+```javascript
+export default {
+  plugins: ['~/plugins/components.js']
+}
+```
+
+For complete configuration options, see the [Configuration Guide](./configuration.md).
+
+## Component System
+
+Components are organized into 5 categories following atomic design:
+
+### 1. Atoms (Global)
+
+Basic building blocks automatically available everywhere:
+
+```markup
+<template>
+  <div>
+    <AwButton>Click me</AwButton>
+    <AwInput v-model="name" label="Name" />
+    <AwCheckbox v-model="agreed">I agree</AwCheckbox>
+  </div>
+</template>
+```
+
+### 2. Molecules (Global)
+
+Combinations of atoms, mostly global:
+
+```markup
+<template>
+  <div>
+    <AwSelect v-model="country" :options="countries" label="Country" />
+    <AwTextarea v-model="bio" label="Bio" rows="4" />
+    <AwAlert>This is an alert message</AwAlert>
+  </div>
+</template>
+```
+
+### 3. Organisms (Dynamic)
+
+Complex components, dynamically imported:
+
+```markup
+<template>
+  <div>
+    <AwForm url="/api/submit" @sended="onSuccess">
+      <AwInput name="title" label="Title" />
+      <AwButton type="submit">Submit</AwButton>
+    </AwForm>
+
+    <AwModal :show="showModal" @close="showModal = false">
+      <template #title>Modal Title</template>
+      <p>Modal content</p>
+    </AwModal>
+
+    <AwTable :data="items" :columns="columns" />
+  </div>
+</template>
+```
+
+### 4. Pages (Dynamic)
+
+Top-level page components:
+
+```markup
+<template>
+  <AwPage title="My Page">
+    <AwCard>
+      <p>Page content</p>
+    </AwCard>
+  </AwPage>
+</template>
+```
+
+### 5. Layouts (Dynamic)
+
+Root-level layout components:
+
+```markup
+<template>
+  <AwLayout>
+    <AwPage title="Dashboard">
+      <!-- content -->
+    </AwPage>
+  </AwLayout>
+</template>
+```
+
+## Your First Page
+
+### 1. Create a Menu Plugin
+
+Create `plugins/menu.js` to configure navigation menus:
+
+```javascript
+export default function({ store }) {
+  store.commit('awesIo/SET_MENU_ITEMS', {
+    main: [
+      { text: 'Dashboard', href: '/', icon: 'dashboard' },
+      { text: 'Users', href: '/users', icon: 'users' },
+      { text: 'Settings', href: '/settings', icon: 'settings' }
+    ],
+    user: [
+      { text: 'Profile', href: '/profile', icon: 'user' },
+      { text: 'Settings', href: '/settings', icon: 'cogs' },
+      { text: 'Logout', href: '/logout', icon: 'logout' }
+    ]
+  })
+}
+```
+
+Register the plugin in `nuxt.config.js`:
+
+```javascript
+export default {
+  plugins: [
+    '~/plugins/menu.js'
+  ]
+}
+```
+
+### 2. Create a Layout
+
+```markup
+<!-- layouts/default.vue -->
+<template>
+  <AwLayout>
+    <nuxt />
+  </AwLayout>
+</template>
+```
+
+### 3. Create a Page
+
+```markup
+<!-- pages/index.vue -->
+<template>
+  <AwPage title="Dashboard">
+    <template #buttons>
+      <AwButton href="/create" icon="plus">
+        Create New
+      </AwButton>
+    </template>
+
+    <AwGrid :cols="{ default: 1, md: 2, lg: 3 }" :gap="4">
+      <AwCard title="Total Users">
+        <div class="text-4xl font-bold">1,234</div>
+        <AwDescription>Active users</AwDescription>
+      </AwCard>
+
+      <AwCard title="Revenue">
+        <div class="text-4xl font-bold">$45,678</div>
+        <AwDescription>This month</AwDescription>
+      </AwCard>
+
+      <AwCard title="Growth">
+        <div class="text-4xl font-bold">+23%</div>
+        <AwDescription>Compared to last month</AwDescription>
+      </AwCard>
+    </AwGrid>
+  </AwPage>
+</template>
+```
+
+### 4. Create a Form Page
+
+```markup
+<!-- pages/users/create.vue -->
+<template>
+  <AwPage title="Create User">
+    <AwCard>
+      <AwForm url="/api/users" method="post" @sended="onUserCreated">
+        <AwGrid :cols="2" :gap="4">
+          <AwInput name="first_name" label="First Name" required />
+          <AwInput name="last_name" label="Last Name" required />
+        </AwGrid>
+
+        <AwInput name="email" label="Email" type="email" required />
+
+        <AwSelect
+          name="role"
+          label="Role"
+          :options="['Admin', 'Editor', 'User']"
+          required
+        />
+
+        <AwPassword name="password" label="Password" required minlength="8" />
+
+        <AwFlow justify="end" :gap="2">
+          <AwButton href="/users" color="mono">Cancel</AwButton>
+          <AwButton type="submit">Create User</AwButton>
+        </AwFlow>
+      </AwForm>
+    </AwCard>
+  </AwPage>
+</template>
+
+<script>
+export default {
+  methods: {
+    onUserCreated(response) {
+      this.$notify({ title: 'User created successfully!' })
+      this.$router.push('/users')
+    }
+  }
+}
+</script>
+```
+
+## Common Patterns
+
+### Using Forms
+
+```markup
+<AwForm url="/api/endpoint" method="post" @sended="onSuccess" @error="onError">
+  <AwInput name="field" label="Label" required />
+  <AwButton type="submit">Submit</AwButton>
+</AwForm>
+```
+
+### Data Tables
+
+```markup
+<AwTableBuilder
+  url="/api/users"
+  :columns="[
+    { name: 'name', label: 'Name', sortable: true },
+    { name: 'email', label: 'Email', sortable: true },
+    { name: 'role', label: 'Role' }
+  ]"
+/>
+```
+
+### Modals
+
+```markup
+<template>
+  <div>
+    <AwButton @click="showModal = true">Open Modal</AwButton>
+
+    <AwModal :show="showModal" @close="showModal = false">
+      <template #title>Modal Title</template>
+      <p>Modal content</p>
+      <template #buttons>
+        <AwButton @click="showModal = false">Close</AwButton>
+      </template>
+    </AwModal>
+  </div>
+</template>
+```
+
+### Notifications
+
+```markup
+<script>
+export default {
+  methods: {
+    showNotification() {
+      this.$notify({
+        message: 'Operation completed successfully!',
+        type: 'success'
+      })
+    }
+  }
+}
+</script>
+```
+
+## Navigation Setup
+
+Set up your app navigation using a menu plugin (`plugins/menu.js`):
+
+```javascript
+export default function({ store }) {
+  // Main navigation menu
+  store.commit('awesIo/SET_MENU_ITEMS', {
+    main: [
+      {
+        text: 'Dashboard',
+        href: '/',
+        icon: 'dashboard'
+      },
+      {
+        text: 'Users',
+        icon: 'users',
+        key: 'users',
+        href: '/users',
+        children: [
+          { text: 'All Users', href: '/users' },
+          { text: 'Add User', href: '/users/create' },
+          { text: 'Roles', href: '/roles' }
+        ]
+      },
+      {
+        text: 'Products',
+        href: '/products',
+        icon: 'box',
+        badge: 5
+      }
+    ],
+    user: [
+      { text: 'Profile', href: '/profile', icon: 'user' },
+      { text: 'Settings', href: '/settings', icon: 'settings' },
+      { text: 'Logout', href: '/logout', icon: 'logout' }
+    ]
+  })
+}
+```
+
+Register the plugin in `nuxt.config.js`:
+
+```javascript
+export default {
+  plugins: [
+    '~/plugins/menu.js'
+  ]
+}
+```
+
+**For sections with submenu items:** See [Mobile Subnavigation Pattern](./guides/mobile-subnavigation.md) to create mobile navigation hubs that automatically redirect desktop users to content pages.
+
+## Theming & Styling
+
+### Dark Theme
+
+The library includes automatic dark theme support:
+
+```javascript
+// Toggle dark theme
+this.$store.dispatch('awesIo/toggleTheme')
+
+// Check current theme
+const isDark = this.$store.getters['awesIo/isDarkTheme']
+```
+
+### Custom CSS
+
+Override component styles in your CSS:
+
+```css
+/* Override button colors */
+.aw-button--accent {
+  --btn-bg: #your-color;
+  --btn-text: #fff;
+}
+
+/* Customize input styles */
+.aw-text-field {
+  --input-border: #your-border-color;
+  --input-focus: #your-focus-color;
+}
+```
+
+## Responsive Design
+
+All components are mobile-first and responsive:
+
+```markup
+<!-- Responsive grid -->
+<AwGrid
+  :cols="{ default: 1, sm: 2, md: 3, lg: 4 }"
+  :gap="{ default: 2, md: 4 }"
+>
+  <!-- content -->
+</AwGrid>
+
+<!-- Responsive visibility -->
+<div v-if="$screen.lg">Desktop only</div>
+<div v-if="!$screen.lg">Mobile only</div>
+```
+
+## Plugins & Utilities
+
+The library provides several utilities:
+
+### Screen Breakpoints
+
+```javascript
+// Access screen size
+if (this.$screen.lg) {
+  // Desktop view
+}
+
+// Available breakpoints: xs, sm, md, lg, xl
+```
+
+### Router Extensions
+
+```javascript
+// Enhanced router methods
+this.$router.pushBack('/fallback-url')
+this.$router.setBack('/previous-page')
+```
+
+### Notifications
+
+```javascript
+// Show notification
+this.$notify({
+  message: 'Success!',
+  type: 'success' // success, error, warning, info
+})
+```
+
+### Config Access
+
+```javascript
+// Access config
+const logoSrc = this.$awes._config.logo.src
+```
+
+## Next Steps
+
+### Essential Guides
+
+- **[Configuration Guide](./configuration.md)** - Complete configuration reference
+- **[Framework Integration](./integrations.md)** - Complete setup with all packages
+- **[List Pages](./guides/page-patterns/list-pages.md)** - Build list pages with tables
+- **[Detail Pages](./guides/page-patterns/detail-pages.md)** - Create/edit forms
+- **[Mobile Subnavigation](./guides/mobile-subnavigation.md)** - Mobile navigation hubs with submenus
+- **[Best Practices](./guides/best-practices.md)** - Framework patterns and conventions
+
+### Component Documentation
+
+- **[Component Index](./index.md)** - Browse all available components
+- **[Forms Guide](./guides/forms-guide.md)** - Form patterns and validation
+- **[Component Cookbook](./cookbook/)** - Real-world examples
+
+### Package Documentation
+
+- **[Vue-MC Models & Collections](../../vue-mc/docs/)** - Data layer documentation
+- **[Nuxt-Auth](../../nuxt-auth/docs/)** - Authentication setup
+- **[Nuxt-Laravel](../../nuxt-laravel/docs/)** - Laravel integration
+
+### Learning Path
+
+**Beginner** (getting started):
+1. Read [Framework Integration](./integrations.md)
+2. Follow [List Pages Guide](./guides/page-patterns/list-pages.md)
+3. Follow [Detail Pages Guide](./guides/page-patterns/detail-pages.md)
+
+**Intermediate** (building features):
+1. Study [Best Practices](./guides/best-practices.md)
+2. Learn [Data Fetching Patterns](./guides/data-fetching.md)
+3. Implement [Error Handling](./guides/error-handling.md)
+
+**Advanced** (complex features):
+1. Explore [Common Patterns](./cookbook/common-patterns.md)
+2. Study [Advanced Patterns](./cookbook/advanced-patterns.md)
+3. Review [Troubleshooting Guide](./reference/troubleshooting.md)
+
+## Common Issues
+
+### Components Not Found
+
+Make sure you have:
+1. Added `@awes-io/ui` to `modules` in `nuxt.config.js`
+2. Enabled `components: true`
+3. Enabled `store: true` for Vuex
+
+### Styles Not Loading
+
+Ensure your Nuxt config includes the module before other modules that might interfere with CSS loading.
+
+### Icons Not Showing
+
+The library uses custom icon sets. Make sure your `awes.config.js` is properly configured and icon assets are available.
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/awes-io/ui/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/awes-io/ui/discussions)
+- **Documentation**: [Component Docs](index.md)