@awes-io/ui 2.142.3 → 2.143.0

package/docs/components/atoms/aw-dropdown.md

@@ -0,0 +1,128 @@
+---
+metaTitle: Dropdown component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwDropdown /> component is used to render Dropdown - UI Vue component for AwesCode UI.
+title: Dropdown
+---
+
+# Dropdown
+
+**Category:** Atom | **Import:** Global
+
+The `AwDropdown` component provides a positioned dropdown menu with mobile and desktop support.
+
+## Overview
+
+`AwDropdown` creates a dropdown menu that can be positioned relative to a target element using Popper.js. It supports both desktop (positioned) and mobile (fullscreen overlay) modes, with automatic detection based on screen size.
+
+## Usage
+
+### Basic Example
+
+```markup
+<template>
+    <div>
+        <button ref="trigger" @click="show = !show">Toggle</button>
+        <AwDropdown :target="trigger" v-model="show">
+            <div>Dropdown content</div>
+        </AwDropdown>
+    </div>
+</template>
+```
+
+### With Options
+
+```markup
+<AwDropdown 
+    :target="trigger" 
+    v-model="show"
+    :options="{ placement: 'bottom-end' }"
+>
+    <AwDropdownButton>Option 1</AwDropdownButton>
+    <AwDropdownButton>Option 2</AwDropdownButton>
+</AwDropdown>
+```
+
+### With Title and Description
+
+```markup
+<AwDropdown 
+    :target="trigger" 
+    v-model="show"
+    title="Menu Title"
+    description="Menu description"
+>
+    <div>Content</div>
+</AwDropdown>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| tag | HTML tag for dropdown container | `String` | `false` | `'div'` (from config) |
+| target | Target element reference or selector | `String` / `Element` | `false` | `''` |
+| options | Popper.js options object | `Object` | `false` | From config |
+| closeOnAction | Close when action element is clicked | `Boolean` | `false` | `true` |
+| show | Whether dropdown is visible | `Boolean` | `false` | `false` |
+| closeOutside | Close when clicking outside | `Boolean` | `false` | `true` |
+| title | Mobile dropdown title | `String` | `false` | `''` |
+| description | Mobile dropdown description | `String` | `false` | `''` |
+| titleTag | HTML tag for title | `String` | `false` | `'h3'` |
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Dropdown content | - | - |
+| heading | Custom mobile heading | `{ title, description }` | Default title/description |
+| close | Custom close button (mobile) | - | Default close button |
+
+### Events
+
+| Name | Payload | Description |
+|------|---------|-------------|
+| update:show | `boolean` | Emitted when visibility changes (for v-model) |
+
+### Methods
+
+| Name | Parameters | Description |
+|------|-----------|-------------|
+| toggle | - | Toggle dropdown visibility |
+
+### Config Options
+
+The component uses default configuration from `@AwConfig`:
+
+```javascript
+export default {
+  AwDropdown: {
+    tag: 'div',
+    baseClass: 'aw-dropdown',
+    popperOptions: {
+      placement: 'bottom-start',
+      // ... popper modifiers
+    }
+  }
+}
+```
+
+## Related Components
+
+- `AwDropdownButton` - Button for dropdown items
+- `AwContextMenu` - Context menu component
+- `AwSelect` - Select component that uses dropdowns
+
+## Notes
+
+- **Import Method:** Global - Available as atom component
+- Uses Popper.js for positioning on desktop
+- Automatically switches to mobile overlay mode on small screens
+- Prevents body scrolling when open on mobile
+- Closes automatically when clicking action elements (links, buttons) by default
+- Supports custom Popper.js options for advanced positioning
+
+                            

package/docs/components/atoms/aw-file.md

@@ -0,0 +1,73 @@
+---
+metaTitle: File component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwFile /> component is used to render File input - UI Vue component for AwesCode UI.
+title: File
+---
+
+# File
+
+**Category:** Atom | **Import:** Global
+
+The `AwFile` component is a wrapper around the native file input element that emits files as an array.
+
+## Overview
+
+`AwFile` provides a styled file input wrapper that handles file selection and emits the selected files as an array. It automatically resets the input after selection.
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwFile @input="handleFiles">
+    <AwButton>Select Files</AwButton>
+</AwFile>
+```
+
+### With Custom Styling
+
+```markup
+<AwFile 
+    accept="image/*" 
+    multiple 
+    @input="handleFiles"
+    class="custom-file-input"
+>
+    <AwButton icon="awesio/upload">Upload Images</AwButton>
+</AwFile>
+```
+
+## API
+
+### Props
+
+All standard HTML file input attributes are supported via `$attrs` (e.g., `accept`, `multiple`, `disabled`).
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Custom trigger element (button, icon, etc.) | - | - |
+
+### Events
+
+| Name | Payload | Description |
+|------|---------|-------------|
+| input | `File[]` | Emitted when files are selected, provides array of File objects |
+
+## Related Components
+
+- `AwUploader` - Full-featured file upload component
+- `AwImageUpload` - Image upload component
+- `AwButton` - Button component for triggers
+
+## Notes
+
+- **Import Method:** Global - Available as atom component
+- The native file input is hidden - use the default slot to provide a custom trigger
+- Files are emitted as an array, even for single file selection
+- Input is automatically reset after file selection
+- All standard file input attributes are passed through via `$attrs`
+

package/docs/components/atoms/aw-flow.md

@@ -0,0 +1,92 @@
+---
+metaTitle: Flow component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwFlow /> component is used to render Flow layout - UI Vue component for AwesCode UI.
+title: Flow
+---
+
+# Flow
+
+**Category:** Atom | **Import:** Global
+
+The `AwFlow` component provides a flexible flow layout system with configurable gaps and alignment.
+
+## Overview
+
+`AwFlow` creates a flow-based layout (similar to flexbox) with consistent spacing between children. It supports horizontal and vertical layouts, alignment options, and customizable gaps.
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwFlow>
+    <div>Item 1</div>
+    <div>Item 2</div>
+    <div>Item 3</div>
+</AwFlow>
+```
+
+### With Custom Gap
+
+```markup
+<AwFlow :gap="8">
+    <div>Item 1</div>
+    <div>Item 2</div>
+</AwFlow>
+```
+
+### Vertical Layout
+
+```markup
+<AwFlow vertical :gap="4">
+    <div>Item 1</div>
+    <div>Item 2</div>
+</AwFlow>
+```
+
+### With Alignment
+
+```markup
+<AwFlow justify="center" align="center" :gap="6">
+    <div>Centered Item</div>
+</AwFlow>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| tag | HTML tag to render | `String` | `false` | `'span'` |
+| gap | Gap scale (spacing multiplier) | `Number` | `false` | `4` |
+| wrapChildren | Whether to wrap each child in a container | `Boolean` | `false` | `true` |
+| justify | Horizontal alignment (center, end) | `String` | `false` | `''` |
+| align | Vertical alignment (start, center, end) | `String` | `false` | `''` |
+| vertical | Use vertical layout | `Boolean` | `false` | `false` |
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Flow children | - | - |
+
+### Events
+
+No events are emitted by this component.
+
+## Related Components
+
+- `AwGrid` - Grid layout component
+- `AwCard` - Card component that may use flow layouts
+
+## Notes
+
+- **Import Method:** Global - Available as atom component
+- Gap is a scale multiplier, not pixels
+- Empty nodes are automatically filtered out
+- When `wrapChildren` is false, children are not wrapped in containers
+- Supports responsive alignment and justification
+

package/docs/components/atoms/aw-grid.md

@@ -0,0 +1,91 @@
+---
+metaTitle: Grid component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwGrid /> component is used to render Grid layout - UI Vue component for AwesCode UI.
+title: Grid
+---
+
+# Grid
+
+**Category:** Atom | **Import:** Global
+
+The `AwGrid` component provides a CSS Grid-based layout system with configurable columns, gaps, and alignment.
+
+## Overview
+
+`AwGrid` creates a responsive grid layout using CSS Grid. It supports configurable column counts, gaps, and alignment options. Children can span multiple columns using the `span` attribute.
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwGrid :col="3" :gap="6">
+    <div>Item 1</div>
+    <div>Item 2</div>
+    <div>Item 3</div>
+</AwGrid>
+```
+
+### Responsive Columns
+
+```markup
+<AwGrid :col="{ default: 1, md: 2, lg: 3 }" :gap="4">
+    <div>Item 1</div>
+    <div>Item 2</div>
+    <div>Item 3</div>
+</AwGrid>
+```
+
+### With Column Spanning
+
+```markup
+<AwGrid :col="3" :gap="6">
+    <div span="2">Spans 2 columns</div>
+    <div>Normal</div>
+    <div>Normal</div>
+</AwGrid>
+```
+
+### With Alignment
+
+```markup
+<AwGrid :col="2" align="center" :gap="4">
+    <div>Centered Item 1</div>
+    <div>Centered Item 2</div>
+</AwGrid>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| col | Number of columns or responsive object | `Number` / `Object` | `false` | `1` |
+| gap | Gap scale or responsive object | `Number` / `Object` | `false` | `6` |
+| align | Vertical alignment (start, center, end) | `String` | `false` | `'start'` |
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Grid children | - | - |
+
+### Events
+
+No events are emitted by this component.
+
+## Related Components
+
+- `AwFlow` - Flow layout component
+- `AwCard` - Card component that may use grid layouts
+
+## Notes
+
+- **Import Method:** Global - Available as atom component
+- Gap is a scale multiplier, not pixels
+- Empty nodes are automatically filtered out
+- Children can use `span` attribute to span multiple columns
+- Supports responsive column and gap configuration via objects (e.g., `{ default: 1, md: 2, lg: 3 }`)

package/docs/components/atoms/aw-headline.md

@@ -0,0 +1,71 @@
+---
+metaTitle: Headline component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwHeadline /> component is used to render Headline - UI Vue component for AwesCode UI.
+title: Headline
+---
+
+# Headline
+
+**Category:** Atom | **Import:** Global
+
+The `AwHeadline` component is a semantic heading wrapper with consistent styling.
+
+## Overview
+
+`AwHeadline` provides a styled heading component that can render as different HTML heading tags (h1-h6). It applies consistent typography and spacing.
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwHeadline>Main Heading</AwHeadline>
+```
+
+### With Custom Tag
+
+```markup
+<AwHeadline tag="h1">Page Title</AwHeadline>
+```
+
+### Different Heading Levels
+
+```markup
+<AwHeadline tag="h1">Level 1</AwHeadline>
+<AwHeadline tag="h2">Level 2</AwHeadline>
+<AwHeadline tag="h3">Level 3</AwHeadline>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| tag | HTML heading tag (h1-h6) | `String` | `false` | `'h3'` |
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Heading text content | - | - |
+
+### Events
+
+No events are emitted by this component.
+
+## Related Components
+
+- `AwSubHeadline` - Sub-heading component
+- `AwTitle` - Title component
+- `AwPage` - Page component that uses headlines
+
+## Notes
+
+- **Import Method:** Global - Available as atom component
+- Default tag is `h3`
+- Use appropriate heading levels for semantic HTML structure
+- Commonly used for section headings and page titles
+

package/docs/components/atoms/aw-icon-system-color.md

@@ -0,0 +1,121 @@
+---
+metaTitle: IconSystemColor component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwIconSystemColor /> component renders multicolor system icons - UI Vue component for AwesCode UI.
+title: IconSystemColor
+---
+
+# AwIconSystemColor
+
+**Category:** Atom | **Import:** Global
+
+The `AwIconSystemColor` component renders multicolor system icons from the AwesCode UI icon library. These icons contain multiple colors and are typically used for illustrations and decorative purposes.
+
+## Overview
+
+`AwIconSystemColor` provides multicolor icon rendering with:
+- Predefined multicolor SVG icons
+- Automatic sizing based on icon dimensions
+- Custom width/height support
+- Inline SVG rendering for styling control
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwIconSystemColor name="success" />
+```
+
+### With Custom Size
+
+```markup
+<AwIconSystemColor
+  name="error"
+  width="48"
+  height="48"
+/>
+```
+
+### In Error States
+
+```markup
+<div class="text-center">
+  <AwIconSystemColor name="404" width="200" height="200" />
+  <h2>Page Not Found</h2>
+</div>
+```
+
+### In Success Messages
+
+```markup
+<AwCard>
+  <AwIconSystemColor name="check-circle" width="64" height="64" />
+  <p>Operation completed successfully!</p>
+</AwCard>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| name | Icon name from multicolor icon set | `String` | `true` | - |
+| width | Icon width (overrides default) | `String\|Number` | `false` | Icon's default width |
+| height | Icon height (overrides default) | `String\|Number` | `false` | Icon's default height |
+
+### Slots
+
+This component does not have slots.
+
+### Events
+
+This component does not emit events.
+
+## Available Icons
+
+The component uses icons from `@AwUtils/icons/multicolor`. Common icons include:
+- Error/warning illustrations
+- Success/completion graphics
+- 404/403 error pages
+- Feature illustrations
+- Status indicators
+
+## Differences from AwIcon
+
+| Feature | AwIconSystemColor | AwIcon |
+|---------|-------------------|--------|
+| Colors | Multicolor (preserved from design) | Monochrome (inherits text color) |
+| Use Case | Illustrations, decorative | UI elements, buttons |
+| Size Control | Width/height props | Size prop or CSS |
+| Icon Set | Multicolor system icons | Font-based or mono icons |
+
+## Styling
+
+The component renders inline SVG, allowing CSS styling:
+
+```markup
+<AwIconSystemColor
+  name="success"
+  class="mx-auto"
+  style="filter: drop-shadow(0 2px 4px rgba(0,0,0,0.1))"
+/>
+```
+
+## Related Components
+
+- `AwIconSystemMono` - Monochrome system icons
+- `AwIcon` - General-purpose icon component
+
+## Notes
+
+- **Import Method:** Global - Available as atom component
+- Icons maintain their original colors from design
+- Inline SVG allows for advanced CSS styling
+- Icon viewBox and content come from icon library
+- If icon name doesn't exist, component renders empty
+- Default size comes from icon definition
+- Use for illustrations and large decorative graphics
+- Not suitable for small UI icons (use AwIconSystemMono instead)