@awes-io/ui 2.142.3 → 2.143.0

package/docs/components/organisms/aw-uploader.md

@@ -0,0 +1,163 @@
+---
+metaTitle: Uploader component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwUploader /> component is used to render Uploader - UI Vue component for AwesCode UI.
+title: Uploader
+---
+
+# AwUploader
+
+**Category:** Organism | **Import:** Dynamic
+
+The `AwUploader` component is a file upload component with drag-and-drop support, progress tracking, and file validation. It handles file uploads via FormData and provides upload lifecycle events.
+
+## Overview
+
+`AwUploader` provides a file upload solution with:
+- Drag and drop file upload
+- Click to select files
+- File format validation
+- File size validation
+- Upload progress tracking
+- Multiple file support
+- Cancel upload functionality
+- Error handling
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwUploader
+    url="/api/upload"
+    @start="handleStart"
+    @finish="handleFinish"
+    @error="handleError"
+/>
+```
+
+### Single File
+
+```markup
+<AwUploader
+    url="/api/upload"
+    :max="5"
+    format="['image/jpeg', 'image/png']"
+/>
+```
+
+### Multiple Files
+
+```markup
+<AwUploader
+    url="/api/upload"
+    multiple
+    :max="10"
+    format="['image/*']"
+/>
+```
+
+### Custom Format
+
+```markup
+<AwUploader
+    url="/api/upload"
+    :format="['.pdf', '.doc', '.docx']"
+    :max="20"
+/>
+```
+
+### Custom Label
+
+```markup
+<AwUploader url="/api/upload">
+    <template #label="{ isDragging }">
+        <div :class="{ 'opacity-50': isDragging }">
+            Custom upload area
+        </div>
+    </template>
+</AwUploader>
+```
+
+### Hide Progress
+
+```markup
+<AwUploader
+    url="/api/upload"
+    hide-progress
+/>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| url | API endpoint URL for file upload | `String` | `true` | - |
+| name | Form field name for file input | `String` | `false` | `'file'` |
+| format | Allowed file formats (MIME types or extensions) | `Array` | `false` | `[]` |
+| max | Maximum file size in MB | `Number` | `false` | `2` |
+| multiple | Allow multiple file selection | `Boolean` | `false` | `false` |
+| hideProgress | Hide progress bar | `Boolean` | `false` | `false` |
+
+**Format Examples:**
+```javascript
+['image/jpeg', 'image/png']  // MIME types
+['.pdf', '.doc', '.docx']     // File extensions
+['image/*']                    // Wildcard MIME types
+```
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| label | Custom upload area content | `{ isDragging }` | Default icon and text |
+| drag-over | Content shown when dragging over | `{ isDragging }` | Default file icon |
+
+### Events
+
+| Name | Payload | Description |
+|------|---------|-------------|
+| start | `{ id, file, loading, progress, cancel }` | Emitted when upload starts |
+| progress | `{ id, file, loading, progress, cancel }` | Emitted during upload progress |
+| finish | `{ id, response }` | Emitted when upload completes successfully |
+| error | `{ id, response }` | Emitted when upload fails |
+
+**Event Payload:**
+```javascript
+{
+  id: 1,                    // Unique file ID
+  file: File,               // File object
+  loading: true,            // Upload in progress
+  progress: 50,            // Upload progress (0-100)
+  cancel: Function,        // Cancel upload function
+  response: Object         // Axios response (finish/error)
+}
+```
+
+### Mixins
+
+- `errorMixin` - Provides error handling functionality
+
+## Related Components
+
+- `AwUploaderFiles` - Component for displaying uploaded files list
+- `AwButton` - Button component (used in examples)
+- `AwProgress` - Progress component (used internally)
+
+## Notes
+
+- **Import Method:** Dynamic - Component is loaded on-demand as an organism
+- Files are uploaded using FormData via Axios
+- Drag and drop works across the entire document (global listeners)
+- File validation happens before upload starts
+- Upload can be cancelled using `cancel()` function from event payload
+- Progress is tracked per file (for multiple uploads)
+- Component uses Axios cancel tokens for cancellation
+- Error messages are displayed via tooltip
+- Format validation uses file MIME type or extension
+- Size validation compares file size to `max` prop (in MB)
+- Component registers global drag listeners (one per page)
+- Dropzone overlay appears when dragging files over component

package/docs/components/organisms/aw-user-menu.md

@@ -0,0 +1,87 @@
+---
+metaTitle: UserMenu component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwUserMenu /> component is used to render UserMenu - UI Vue component for AwesCode UI.
+title: UserMenu
+---
+
+# AwUserMenu
+
+**Category:** Layout (Internal) | **Import:** Dynamic
+
+The `AwUserMenu` component is an internal layout component that displays the user menu dropdown in the header. It shows user avatar, profile link, theme toggle, and menu items.
+
+## Overview
+
+`AwUserMenu` provides a user menu solution with:
+- User avatar display
+- Profile link
+- Theme toggle (dark/light)
+- Menu items
+- Dropdown menu
+- Desktop/mobile interactions
+
+## Usage
+
+This component is typically used internally by layout components. Direct usage is not recommended unless building custom layouts.
+
+### Internal Usage
+
+```markup
+<AwUserMenu
+    :avatar="userAvatar"
+    :name="userName"
+    :info="userInfo"
+/>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| avatar | Path to user avatar image | `String` | `false` | `''` |
+| name | User name | `String` | `false` | `''` |
+| info | Additional info under user name | `String` | `false` | `''` |
+| darkTheme | Is dark mode enabled (for internal use) | `Boolean` | `false` | `false` |
+| outline | Use outline avatar style | `Boolean` | `false` | `false` |
+| caret | Show dropdown caret icon | `Boolean` | `false` | `true` |
+| vertical | Vertical menu layout | `Boolean` | `false` | `false` |
+| showUser | Show user menu button | `Boolean` | `false` | `true` |
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Menu items | - | Profile link, theme toggle, menu items |
+| user | Custom user button | - | Default avatar button |
+| user-menu | Custom menu content | - | Default dropdown menu |
+| after-profile | Content after profile section | - | - |
+
+### Events
+
+This component does not emit custom events.
+
+## Related Components
+
+- `AwAvatar` - Avatar component (used for user display)
+- `AwUserpic` - User picture component (used in menu)
+- `AwDropdown` - Dropdown component (used for menu)
+- `AwNavItem` - Navigation item component
+- `AwIcon` - Icon components
+
+## Notes
+
+- **Import Method:** Dynamic - Component is loaded on-demand as a layout component
+- Component is internal (used within layout components)
+- User data is typically retrieved from Vuex store (`awesIo` module)
+- Profile URL is managed via Vuex store
+- Theme toggle switches between dark/light modes
+- Desktop: hover to open, mouseleave to close
+- Mobile: click to open, click outside to close
+- Menu includes profile link, theme toggle, and custom menu items
+- Avatar size changes based on `outline` prop (24px vs 40px)
+- Dropdown positioning adjusts based on `vertical` prop
+- Component uses `AwDropdown` for menu display

package/docs/components/pages/aw-page-aside.md

@@ -0,0 +1,296 @@
+---
+metaTitle: PageAside component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwPageAside /> component is used to render page with aside sidebar - UI Vue component for AwesCode UI.
+title: PageAside
+---
+
+# AwPageAside
+
+**Category:** Page | **Import:** Dynamic
+
+The `AwPageAside` component is a specialized page layout wrapper that adds a persistent sidebar (aside) section to the standard `AwPage` component. It provides responsive behavior with the aside appearing as a separate column on desktop and as a card on mobile.
+
+## Overview
+
+`AwPageAside` provides a page layout with aside sidebar:
+- Responsive aside positioning (sidebar on desktop, card on mobile)
+- Sticky aside buttons at the bottom
+- Pass-through support for all `AwPage` props and slots
+- Desktop/mobile breakpoint customization
+- Optional aside line separator
+- Mobile aside can be hidden
+- Bottom bar spacing awareness
+- `isDesktop` prop in all slots for responsive content
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwPageAside title="Page with Aside">
+    <template #default>
+        <p>Main content goes here</p>
+    </template>
+
+    <template #aside>
+        <AwCard title="Sidebar">
+            <p>Sidebar content</p>
+        </AwCard>
+    </template>
+</AwPageAside>
+```
+
+### With Aside Buttons
+
+```markup
+<AwPageAside title="Edit Form">
+    <template #default>
+        <AwForm url="/api/submit">
+            <!-- form fields -->
+        </AwForm>
+    </template>
+
+    <template #aside>
+        <AwCard title="Info">
+            <p>Additional information</p>
+        </AwCard>
+    </template>
+
+    <template #aside-buttons>
+        <AwButton cta>Save</AwButton>
+        <AwButton theme="outline">Cancel</AwButton>
+    </template>
+</AwPageAside>
+```
+
+### Custom Desktop Breakpoint
+
+```markup
+<AwPageAside
+    title="Responsive Page"
+    desktop-from="xl"
+>
+    <template #default>
+        <p>Main content</p>
+    </template>
+
+    <template #aside>
+        <p>Sidebar switches to desktop mode at xl breakpoint</p>
+    </template>
+</AwPageAside>
+```
+
+### With Line Separator
+
+```markup
+<AwPageAside
+    title="Page Title"
+    modifiers="line"
+>
+    <template #default>
+        <p>Main content</p>
+    </template>
+
+    <template #aside>
+        <p>Aside with vertical line separator</p>
+    </template>
+</AwPageAside>
+```
+
+### Hide Mobile Aside
+
+```markup
+<AwPageAside
+    title="Page Title"
+    hide-mobile-aside
+>
+    <template #default>
+        <p>Main content</p>
+    </template>
+
+    <template #aside>
+        <p>This aside only appears on desktop</p>
+    </template>
+</AwPageAside>
+```
+
+### Custom Mobile Aside
+
+```markup
+<AwPageAside title="Custom Mobile">
+    <template #default>
+        <p>Main content</p>
+    </template>
+
+    <template #aside="{ isDesktop }">
+        <div v-if="isDesktop">
+            <!-- Desktop aside layout -->
+            <AwCard title="Desktop Sidebar">...</AwCard>
+        </div>
+        <div v-else>
+            <!-- Mobile aside layout -->
+            <AwAccordionFold title="More Info">...</AwAccordionFold>
+        </div>
+    </template>
+
+    <template #mobile-aside="{ isDesktop }">
+        <AwCard v-if="!isDesktop" class="custom-mobile-card">
+            <slot name="aside" />
+        </AwCard>
+    </template>
+</AwPageAside>
+```
+
+### Pass-Through AwPage Props
+
+```markup
+<AwPageAside
+    title="Page Title"
+    :breadcrumb="{ href: '/back', title: 'Back' }"
+    :subnav="tabs"
+    container="small"
+>
+    <template #buttons>
+        <AwButton>Action</AwButton>
+    </template>
+
+    <template #default>
+        <p>Main content</p>
+    </template>
+
+    <template #aside>
+        <p>Sidebar</p>
+    </template>
+</AwPageAside>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| desktopFrom | Screen breakpoint for desktop layout | `String` | `false` | `'lg'` |
+| modifiers | CSS modifier classes (e.g., `'line'` for separator) | `String` / `Object` | `false` | `''` |
+| hideMobileAside | Hide aside section on mobile | `Boolean` | `false` | `false` |
+
+**Breakpoint Options:** `'sm'`, `'md'`, `'lg'`, `'xl'`, `'2xl'`
+
+**All `AwPage` props** are also supported and passed through via `v-bind="$attrs"`:
+- `title` - Page title
+- `breadcrumb` - Breadcrumb navigation
+- `subnav` - Subnavigation tabs
+- `container` - Container size
+- `fullscreen` - Fullscreen mode
+- etc.
+
+See [AwPage documentation](./aw-page.md#props) for complete list.
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Main page content | `{ isDesktop }` | - |
+| aside | Aside sidebar content | `{ isDesktop }` | - |
+| aside-buttons | Buttons at bottom of aside (sticky) | - | - |
+| mobile-aside | Custom mobile aside wrapper | `{ isDesktop }` | AwCard wrapper |
+| bottom | Content below main content | - | - |
+
+**Pass-through slots from AwPage:**
+- `heading` - Custom page header
+- `title` - Custom title content
+- `buttons` - Header buttons
+- `subnav` - Custom subnavigation
+- `headline-breadcrumb` - Custom breadcrumb
+- `after-breadcrumb` - Content after breadcrumb
+- `mobile-title` - Mobile title display
+- `bottom-bar` - Custom bottom bar
+
+All slots receive `isDesktop` prop for responsive rendering.
+
+### Events
+
+All events from `AwPage` are passed through (e.g., `update:fullscreen`).
+
+### Data Properties
+
+| Name | Description | Type |
+|------|-------------|------|
+| hideBottomBar | Whether bottom bar is hidden (computed from AwPage) | `Boolean` |
+
+### Computed Properties
+
+| Name | Description |
+|------|-------------|
+| isDesktop | Whether current screen size is desktop (based on `desktopFrom` prop) |
+| _slots | Filtered slots object excluding self-managed slots |
+
+### Methods
+
+| Name | Parameters | Description |
+|------|------------|-------------|
+| _wathcBottomBar | - | Updates hideBottomBar state from AwPage reference |
+
+### Head
+
+Component adds `aw-page-aside-page-body` class to `<body>` element for styling.
+
+## Related Components
+
+- [AwPage](./aw-page.md) - Base page component used internally
+- [AwPageSingle](./aw-page-single.md) - Single column page layout
+- [AwCard](../atoms/aw-card.md) - Card component used for mobile aside wrapper
+- [AwButton](../molecules/aw-button.md) - Button component for aside actions
+
+## Notes
+
+- **Import Method:** Dynamic - Component is loaded on-demand as a page component
+- Component wraps `AwPage` and passes through all props via `$attrs`
+- Desktop/mobile layout switches based on `$screen[desktopFrom]` breakpoint
+- On desktop, aside appears as a fixed-width sidebar on the right
+- On mobile, aside appears as a card below main content (unless `hideMobileAside` is true)
+- Aside buttons are sticky at the bottom on both desktop and mobile
+- Bottom spacing adjusts automatically when bottom bar is present (`4rem` padding)
+- Uses CSS custom property `--page-aside-buttons-bottom` for spacing control
+- Component filters out `default`, `aside`, and `aside-buttons` slots before passing to AwPage
+- The `modifiers` prop with value `'line'` adds `.aw-page-aside__aside--line` class
+- Uses `$refs.page` to access internal AwPage component state
+- Bottom bar visibility is watched in `created` and `updated` lifecycle hooks
+- All pass-through slots maintain their scoped slot data plus `isDesktop` prop
+- Component uses `inheritAttrs: false` to control attribute inheritance
+- Body class is set via Nuxt's `head()` method for global styling
+
+## Layout Structure
+
+**Desktop Layout:**
+```
+┌─────────────────────────────────────────────┐
+│ AwPage Wrapper (Main Content)               │
+│ ┌─────────────────────────────────────────┐ │ ┌─────────────┐
+│ │ Page Header                             │ │ │   Aside     │
+│ ├─────────────────────────────────────────┤ │ │   Content   │
+│ │ Main Content                            │ │ │             │
+│ │                                         │ │ │             │
+│ │                                         │ │ │             │
+│ └─────────────────────────────────────────┘ │ ├─────────────┤
+│                                             │ │   Buttons   │
+└─────────────────────────────────────────────┘ └─────────────┘
+```
+
+**Mobile Layout:**
+```
+┌─────────────────────────────────────────────┐
+│ Page Header                                 │
+├─────────────────────────────────────────────┤
+│ Main Content                                │
+│                                             │
+│                                             │
+├─────────────────────────────────────────────┤
+│ Mobile Aside (Card)                         │
+│                                             │
+├─────────────────────────────────────────────┤
+│ Aside Buttons (Sticky)                      │
+└─────────────────────────────────────────────┘
+```