@awes-io/ui 2.142.3 → 2.144.0

package/docs/components/layouts/aw-layout-provider.md

@@ -0,0 +1,238 @@
+---
+metaTitle: LayoutProvider component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwLayoutProvider /> is a layout provider that manages navigation menus and provides context for all layouts in AwesCode UI.
+title: LayoutProvider
+---
+
+# AwLayoutProvider
+
+**Category:** Layout | **Import:** Dynamic
+
+The `AwLayoutProvider` component is the base layout provider that manages navigation menus from Vuex store and provides layout context to child components. It serves as the foundation for all other layout components.
+
+## Overview
+
+`AwLayoutProvider` provides layout management with:
+- Menu management from Vuex store (mainMenu, secondaryMenu, userMenu, tertiaryMenu)
+- Active menu item detection based on current route
+- Menu transformation with permissions checking
+- Provides layout context via Vue provide/inject
+- Offline notification display
+- Translation support for menu items
+- Route-based active item highlighting
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwLayoutProvider>
+  <div>Your layout content</div>
+</AwLayoutProvider>
+```
+
+### Used by Other Layouts
+
+```markup
+<!-- AwLayout uses AwLayoutProvider internally -->
+<template>
+  <AwLayoutProvider class="aw-layout">
+    <AwLayoutMenu v-if="$screen.lg" />
+    <AwHeaderNotification />
+    <slot />
+  </AwLayoutProvider>
+</template>
+```
+
+### Accessing Layout Context
+
+```markup
+<script>
+export default {
+  inject: ['layoutProvider'],
+
+  computed: {
+    mainMenu() {
+      return this.layoutProvider.mainMenu
+    },
+
+    activeMenuItem() {
+      return this.layoutProvider.activeMenuItem
+    }
+  }
+}
+</script>
+```
+
+## API
+
+### Props
+
+This component does not have props. All menu data comes from Vuex store.
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Layout content | - | - |
+
+### Events
+
+This component does not emit custom events.
+
+### Provided Context
+
+The component provides a `layoutProvider` object via Vue's provide/inject API:
+
+```javascript
+{
+  mainMenu: Array,         // Transformed main menu items
+  secondaryMenu: Array,    // Transformed secondary menu items
+  userMenu: Array,         // Transformed user menu items
+  tertiaryMenu: Array,     // Transformed tertiary menu items
+  activeMenu: Object,      // Currently active top-level menu item
+  activeMenuItem: Object   // Currently active menu item (including nested)
+}
+```
+
+### Menu Item Structure
+
+Menu items are transformed from Vuex store with this structure:
+
+```javascript
+{
+  text: String,            // Translated menu item text
+  subtitle: String,        // Translated subtitle (optional)
+  description: String,     // Translated description (optional)
+  href: String,            // Link URL
+  icon: String,            // Icon name
+  iconBg: String,          // Icon background color
+  iconActive: String,      // Active icon name
+  class: String,           // Custom CSS class
+  expanded: Boolean,       // Expanded state
+  target: String,          // Link target (_blank, etc.)
+  rel: String,             // Link rel attribute
+  listeners: Object,       // Event listeners
+  abstract: Boolean,       // Abstract menu item (no link)
+  key: String,             // Unique key
+  badge: String/Number,    // Badge value
+  switcher: Boolean,       // Switcher toggle
+  back: Boolean,           // Back button
+  isDivide: Boolean,       // Divider
+  arrow: Boolean,          // Show arrow
+  hideText: Boolean,       // Hide text
+  children: Array          // Child menu items
+}
+```
+
+## Vuex Store Integration
+
+The component reads menu data from the `awesIo` Vuex module:
+
+```javascript
+// In your Vuex store or via API
+this.$store.dispatch('awesIo/setMainMenu', [
+  {
+    text: 'Dashboard',
+    href: '/dashboard',
+    icon: 'dashboard'
+  },
+  {
+    text: 'Users',
+    icon: 'users',
+    toggler: true,
+    children: [
+      { text: 'All Users', href: '/users' },
+      { text: 'Add User', href: '/users/create' }
+    ]
+  }
+])
+```
+
+## Menu Transformation Features
+
+### Permission Checking
+
+Menu items with `show` function are filtered based on permissions:
+
+```javascript
+{
+  text: 'Admin',
+  href: '/admin',
+  show: ($can) => $can('access', 'admin')
+}
+```
+
+### Translation
+
+Menu items are automatically translated unless `translate: false`:
+
+```javascript
+{
+  text: 'Users',         // Will be translated via this.$t('Users')
+  translate: true        // Default
+}
+
+{
+  text: 'Custom Name',
+  translate: false       // Won't be translated
+}
+```
+
+### Dynamic Hrefs
+
+Hrefs can be functions receiving store state and getters:
+
+```javascript
+{
+  text: 'Profile',
+  href: (state, getters) => `/users/${state.user.id}`
+}
+```
+
+### Auto-Generated Hrefs
+
+Parent items without href automatically use first child's href:
+
+```javascript
+{
+  text: 'Settings',
+  toggler: true,
+  children: [
+    { text: 'Profile', href: '/settings/profile' },  // Parent will use this href
+    { text: 'Security', href: '/settings/security' }
+  ]
+}
+```
+
+## Active Item Detection
+
+The provider automatically detects active menu items based on current route:
+
+- Compares route path with menu item hrefs
+- Handles nested menu items
+- Updates on route changes
+- Sets `activeMenu` (top-level) and `activeMenuItem` (any level)
+
+## Related Components
+
+- `AwLayout` - Uses AwLayoutProvider internally
+- `AwLayoutCenter` - Uses AwLayoutProvider internally
+- `AwLayoutMenu` - Consumes layout context
+- `AwOfflineNotify` - Displayed by provider
+
+## Notes
+
+- **Import Method:** Dynamic - Component is loaded on-demand as a layout
+- All other layouts use this component as their base
+- Provides menu context to all child components via provide/inject
+- Automatically watches Vuex store for menu changes
+- Handles permission-based menu filtering via `$can` (CASL integration)
+- Menu items are deeply transformed (including nested children)
+- Active item detection uses path prefix matching
+- Offline notification is always displayed (shows when offline)
+- Menu transformation happens on every store update
+- Supports 4 menu types: main, secondary, user, tertiary
+- Used internally by AwLayout and AwLayoutCenter

package/docs/components/layouts/aw-layout.md

@@ -0,0 +1,88 @@
+---
+metaTitle: Layout component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwLayout /> is a layout with left sidebar navigation for AwesCode UI.
+title: Layout
+---
+
+# AwLayout
+
+**Category:** Layout | **Import:** Dynamic
+
+The `AwLayout` component is the default layout with left sidebar navigation. It provides the main application layout structure with navigation menu, header notifications, and content area.
+
+## Overview
+
+`AwLayout` provides the default application layout with:
+- Left sidebar navigation (desktop)
+- Header notifications
+- Content area
+- Responsive design
+- Menu integration with Vuex store
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwLayout>
+    <AwPage>
+        <h1>Page Content</h1>
+    </AwPage>
+</AwLayout>
+```
+
+### With Custom Slots
+
+```markup
+<AwLayout>
+    <template #before-header>
+        <AwBanner>Custom banner</AwBanner>
+    </template>
+    
+    <template #navbar>
+        <CustomNavbar />
+    </template>
+    
+    <AwPage>
+        <h1>Page Content</h1>
+    </AwPage>
+</AwLayout>
+```
+
+## API
+
+### Props
+
+This component does not have props. Menu is managed via Vuex store (`awesIo` module).
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Main content area | - | - |
+| before-header | Content before header | - | - |
+| navbar | Custom navbar content | - | Default navbar |
+
+### Events
+
+This component does not emit custom events.
+
+## Related Components
+
+- `AwLayoutProvider` - Layout provider component (used internally)
+- `AwLayoutMenu` - Sidebar menu component
+- `AwHeaderNotification` - Header notification component
+- `AwPage` - Page component (typically used in default slot)
+
+## Notes
+
+- **Import Method:** Dynamic - Component is loaded on-demand as a layout
+- Menu is managed via Vuex store (`awesIo` module)
+- Sidebar navigation only shows on desktop (`$screen.lg`)
+- Mobile menu is commented out in current implementation
+- Component uses `AwLayoutProvider` for layout structure
+- Header notifications are automatically displayed
+- All slots are proxied to layout menu component
+- Component provides responsive layout structure

package/docs/components/molecules/aw-action-button.md

@@ -0,0 +1,138 @@
+---
+metaTitle: Action Button component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwActionButton /> component is used to render Action Button - UI Vue component for AwesCode UI.
+title: Action Button
+---
+
+# Action Button
+
+**Category:** Molecule | **Import:** Global
+
+The `AwActionButton` component is a button-like component with icon, text, and optional descriptions, designed for action cards and lists.
+
+## Overview
+
+`AwActionButton` provides a styled action button with a leading icon, main text, optional description and subdescription, and a trailing icon. It extends link functionality and is commonly used in action cards.
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwActionButton text="Action" icon="arrow-animated" />
+```
+
+### With Descriptions
+
+```markup
+<AwActionButton
+    text="Create Project"
+    description="Start a new project"
+    subdescription="Free plan"
+    icon="awesio/plus"
+/>
+```
+
+### With Custom Icon Colors
+
+```markup
+<AwActionButton
+    text="Action"
+    icon="awesio/check"
+    icon-color="success"
+/>
+```
+
+### As Links
+
+```markup
+<!-- External link -->
+<AwActionButton
+    text="External Link"
+    icon="awesio/external"
+    href="https://example.com"
+    target="_blank"
+/>
+
+<!-- Internal link (uses router automatically) -->
+<AwActionButton
+    text="Internal Link"
+    icon="awesio/link"
+    href="/components"
+/>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| icon | Leading icon name | `String` | `false` | `''` |
+| iconColor | Leading icon background color | `String` | `false` | `'green'` |
+| iconOnColor | Leading icon text color | `String` | `false` | `null` |
+| iconSize | Leading icon size | `String` | `false` | `'md'` |
+| text | Button text | `String` | `false` | `''` |
+| description | Description text below main text | `String` | `false` | `''` |
+| subdescription | Subdescription text | `String` | `false` | `''` |
+| iconRight | Trailing icon name | `String` | `false` | `'arrow-animated'` |
+| modifiers | CSS modifiers (e.g., 'outline', 'narrow') | `String` / `Array` | `false` | `''` |
+| href | Link URL (for both internal and external links) | `String` | `false` | `undefined` |
+| target | Link target (e.g., `_blank` for external links) | `String` | `false` | `undefined` |
+
+**Link Behavior:**
+- Uses `href` prop for all links (both internal and external)
+- Internal links (starting with `/`) automatically use Vue Router
+- External links work with standard `<a>` tag behavior
+- No need to use `to` prop - the link mixin handles routing automatically
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Custom text content | `{ text }` | Text prop value |
+| icon-wrapper | Custom icon wrapper | - | Default icon wrapper |
+
+### Events
+
+All link-related events are supported (e.g., `click`).
+
+## Related Components
+
+- `AwActionCard` - Card component that uses action buttons
+- `AwActionIcon` - Icon component used in action buttons
+- `AwButton` - Standard button component
+
+## Component Behavior
+
+### Link Functionality
+
+The component extends the link mixin, providing intelligent link handling:
+
+- **Internal Navigation:** Links starting with `/` automatically use Vue Router for SPA navigation
+- **External Links:** Full URLs (starting with `http://` or `https://`) render as standard `<a>` tags
+- **Prop Usage:** Only use `href` prop - avoid using `to` prop as the link mixin handles routing
+- **Target Control:** Use `target="_blank"` for external links to open in new tabs
+
+### Icon Customization
+
+- **Leading Icon:** Customize with `icon`, `iconColor`, `iconOnColor`, and `iconSize` props
+- **Trailing Icon:** Defaults to `arrow-animated`, can be customized with `iconRight` prop
+- **Animated Icons:** Automatically detected and styled (e.g., `arrow-animated`)
+
+### Visual Modifiers
+
+Available modifiers for different styles:
+- `outline` - Outlined button style
+- `narrow` - Reduced padding for compact layouts
+- Multiple modifiers can be combined using an array: `:modifiers="['outline', 'narrow']"`
+
+## Notes
+
+- **Import Method:** Global - Available as molecule component
+- Commonly used within `AwActionCard` components
+- Description and subdescription provide context for actions
+- Default icon color is `green` with customizable background and text colors
+

package/docs/components/molecules/aw-alert.md

@@ -0,0 +1,191 @@
+---
+metaTitle: Alert component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwAlert /> component is used to render Alert - UI Vue component for AwesCode UI.
+title: Alert
+---
+
+# Alert
+
+**Category:** Molecule | **Import:** Global
+
+The `AwAlert` component displays alert messages with icon, title, description, and optional action buttons.
+
+## Overview
+
+`AwAlert` provides a styled alert component for displaying informational, warning, or error messages. It supports custom colors, icons, and action buttons.
+
+## Usage
+
+**Important:** AwAlert components should be placed inside components with "surface" backgrounds (e.g., `AwCard`, `AwModal`, `AwIsland`) for proper visual presentation.
+
+### Basic Example
+
+```markup
+<AwCard>
+    <AwAlert
+        title="Basic Alert"
+        description="This is a basic alert message."
+    />
+</AwCard>
+```
+
+### With Icons and Semantic Colors
+
+```markup
+<AwCard>
+    <AwAlert
+        title="Success"
+        description="Operation completed successfully."
+        icon="awesio/check-circle"
+        color="success"
+    />
+
+    <AwAlert
+        title="Warning"
+        description="Please review this carefully."
+        icon="awesio/warning"
+        color="warning"
+    />
+
+    <AwAlert
+        title="Error"
+        description="Something went wrong."
+        icon="awesio/close-circle"
+        color="error"
+    />
+</AwCard>
+```
+
+### With Custom Icon Color
+
+```markup
+<AwCard>
+    <AwAlert
+        title="Custom Icon Color"
+        description="Alert with custom icon color."
+        icon="awesio/star"
+        icon-color="warning"
+    />
+</AwCard>
+```
+
+### With Action Buttons
+
+```markup
+<AwCard>
+    <AwAlert
+        title="Confirm Action"
+        description="Are you sure you want to proceed?"
+        icon="awesio/question-circle"
+        color="warning"
+    >
+        <AwButton size="sm" color="success">Confirm</AwButton>
+        <AwButton size="sm" color="mono-600">Cancel</AwButton>
+    </AwAlert>
+</AwCard>
+```
+
+### With Custom Colors
+
+```markup
+<AwCard>
+    <AwAlert
+        title="Blue Theme"
+        description="Alert with blue color."
+        icon="awesio/star"
+        color="blue"
+    />
+
+    <AwAlert
+        title="Magenta Theme for Icon"
+        description="Alert with magenta icon color."
+        icon="awesio/question-circle"
+        icon-color="on-magenta"
+    />
+</AwCard>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| icon | Icon name | `String` | `false` | `''` |
+| config | Alert background color and icon | `String` | `false` | `'default'` |
+| color | Alert background color | `String` | `false` | `''` |
+| onColor | Alert icon and text color | `String` | `false` | `''` |
+| iconColor | Icon color | `String` | `false` | `''` |
+| title | Alert title text | `String` | `false` | `''` |
+| description | Alert description text | `String` | `false` | `''` |
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Action buttons | - | - |
+| icon | Custom icon content | - | Default icon |
+| title | Custom title content | - | Title text |
+| description | Custom description content | - | Description text |
+| close | Close icon or button | - | - |
+
+### Events
+
+No events are emitted by this component.
+
+## Component Behavior
+
+### Color System
+
+The alert component supports both semantic and custom colors:
+
+**Semantic Colors:**
+- `info` - Informational messages (blue theme)
+- `success` - Successful operations (green theme)
+- `warning` - Cautionary messages (yellow/orange theme)
+- `error` - Error messages (red theme)
+- `notify` - Notification alerts (notification theme)
+- `accent` - Primary brand color
+
+**Custom Colors:**
+Any named color from the design system can be used:
+- `blue`, `purple`, `magenta`, `red`, `green`, etc.
+- Named colors display with light/pastel backgrounds
+- Use `icon-color` with `on-{color}` for vibrant icon colors on custom backgrounds
+
+### Icon Colors
+
+The `iconColor` prop accepts:
+- **Semantic colors**: `success`, `warning`, `error`, `info`, `accent` (use without `on-` prefix)
+- **Named colors with OnColor variants**: `on-magenta`, `on-purple`, `on-blue`, etc. (use `on-` prefix for vibrant colors on light backgrounds)
+
+**Important:** Semantic colors should be used directly without the `on-` prefix (e.g., `icon-color="accent"`), while named colors require the `on-` prefix to get vibrant colors on light backgrounds (e.g., `icon-color="on-magenta"`).
+
+### Layout Requirements
+
+- **Surface background required**: Alerts must be placed inside components with white/surface backgrounds
+  - Compatible containers: `AwCard`, `AwModal`, `AwIsland`, or any component with surface color
+  - The surface background provides proper contrast for alert colors
+- Multiple alerts can be stacked within a single container using `AwGrid`
+- Action buttons render in a separate section below title/description
+
+## Related Components
+
+- `AwCard` - Required container for alerts
+- `AwIcon` - Icon component used within alerts
+- `AwButton` - Button component for alert actions
+- `AwBadge` - Alternative for status indicators
+
+## Notes
+
+- **Import Method:** Global - Available as molecule component
+- **Container Required:** Always wrap alerts in `AwCard` for proper styling
+- Default color is `'default'` (neutral gray theme)
+- Title and description are both optional but at least one should be provided
+- Icon appears before the title when provided
+- Action buttons use the default slot and appear below content
+- Supports both semantic colors (info, success, warning, error) and custom named colors
+- Use `icon-color` to customize icon independently from alert background
+