@awes-io/ui 2.142.3 → 2.144.0

package/docs/components/atoms/aw-action-icon.md

@@ -0,0 +1,126 @@
+---
+metaTitle: Action Icon component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwActionIcon /> component is used to render Action Icon - UI Vue component for AwesCode UI.
+title: Action Icon
+---
+
+# Action Icon
+
+**Category:** Atom | **Import:** Global
+
+The `AwActionIcon` component displays an icon with optional text, with customizable size, color, and styling.
+
+## Overview
+
+`AwActionIcon` provides a flexible icon display component that can show an icon, image, or custom content. It supports multiple sizes, colors, and can display text alongside the icon.
+
+## Usage
+
+### Different Sizes
+
+```markup
+<AwActionIcon icon="awesio/check" size="xxs" />
+<AwActionIcon icon="awesio/check" size="xs" />
+<AwActionIcon icon="awesio/check" size="sm" />
+<AwActionIcon icon="awesio/check" size="md" />
+<AwActionIcon icon="awesio/check" size="lg" />
+```
+
+### Different Colors
+
+```markup
+<AwActionIcon icon="awesio/star" color="accent" />
+<AwActionIcon icon="awesio/star" color="success" />
+<AwActionIcon icon="awesio/star" color="warning" />
+<AwActionIcon icon="awesio/star" color="error" />
+<AwActionIcon icon="awesio/star" color="info" />
+```
+
+### With Text
+
+```markup
+<AwActionIcon icon="awesio/download" text="Download" size="sm" />
+<AwActionIcon icon="awesio/upload" text="Upload" size="md" />
+<AwActionIcon icon="awesio/mail" text="Send" size="lg" />
+```
+
+### Custom Icon Color
+
+```markup
+<AwActionIcon
+    icon="awesio/heart"
+    color="mono-100"
+    icon-color="error"
+/>
+```
+
+### Outline Style
+
+```markup
+<AwActionIcon
+    icon="awesio/check"
+    color="success"
+    modifiers="outline"
+/>
+```
+
+### With Image
+
+```markup
+<AwActionIcon
+    :image="{ src: 'url', alt: 'Alt text' }"
+    size="md"
+/>
+```
+
+### Custom Size (px)
+
+You can provide a numeric value for the `size` prop to set a custom size in pixels.
+
+```markup
+<AwActionIcon icon="awesio/settings" :size="30" />
+<AwActionIcon icon="awesio/settings" :size="50" />
+<AwActionIcon icon="awesio/settings" :size="70" />
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default | Validator |
+|------|-------------|------|----------|---------|-----------|
+| image | Image object with src and alt | `Object` | `false` | `null` | - |
+| icon | Icon name | `String` | `false` | `'arrow-animated'` | - |
+| text | Text to display alongside icon | `String` | `false` | `''` | - |
+| size | Icon size preset or custom pixels | `String` / `Number` | `false` | `'md'` | Must be one of: xxs, xs, sm, md, lg or any `Number` |
+| color | Background color | `String` | `false` | `'mono-700'` | - |
+| onColor | Text/icon color | `String` | `false` | `''` | - |
+| iconColor | Custom icon color | `String` | `false` | `''` | - |
+| modifiers | CSS modifiers (e.g., 'outline') | `String` / `Array` | `false` | `''` | - |
+| desktopFrom | Breakpoint for desktop sizing | `String` | `false` | `'lg'` | - |
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Custom content (replaces icon) | - | Icon with optional text |
+
+### Events
+
+No events are emitted by this component.
+
+## Related Components
+
+- `AwIcon` - Basic icon component
+- `AwActionCard` - Card component that may use action icons
+
+## Notes
+
+- **Import Method:** Global - Available as atom component
+- Supports animated icons (automatically detected)
+- Size adapts on mobile devices when `desktopFrom` breakpoint is not met
+- When `image` prop is provided, icon and text are not displayed
+- Text is only shown when size supports it (sm, md, lg)
+

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

@@ -0,0 +1,106 @@
+---
+metaTitle: Avatar component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwAvatar /> component is used to render Avatar - UI Vue component for AwesCode UI.
+title: Avatar
+---
+
+# Avatar
+
+**Category:** Atom | **Import:** Global
+
+The `AwAvatar` component displays a user avatar with image, initials, or placeholder icon.
+
+## Overview
+
+`AwAvatar` provides a flexible avatar component that can display a user image, initials from a name, or a placeholder icon. It automatically generates colors for initials based on the user's name and supports loading states.
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwAvatar src="/user.jpg" name="John Doe" />
+```
+
+### With Initials
+
+```markup
+<AwAvatar name="Jane Smith" :size="48" />
+```
+
+### Custom Size
+
+```markup
+<AwAvatar name="User" :size="64" />
+```
+
+### Different Types
+
+```markup
+<AwAvatar name="User" type="initials" /> <!-- Shows initials -->
+<AwAvatar name="User" type="empty" /> <!-- Empty circle -->
+<AwAvatar name="User" type="no-img" /> <!-- Placeholder icon -->
+```
+
+### Without Color
+
+```markup
+<AwAvatar name="User" :is-colored="false" />
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default | Validator |
+|------|-------------|------|----------|---------|-----------|
+| tag | HTML tag for wrapper | `String` | `false` | `'span'` | - |
+| src | Full URL to the picture | `String` | `false` | `''` | - |
+| name | User name (for initials) | `String` | `false` | `''` | - |
+| size | Size of the avatar in pixels | `Number` / `String` | `false` | `36` | Must be a number |
+| type | Display type when no image | `String` | `false` | `'initials'` | Must be: initials, empty, no-img |
+| isColored | Use colored background for initials | `Boolean` | `false` | `true` | - |
+| loading | Show loading indicator | `Boolean` | `false` | `false` | - |
+| colors | Array of color objects for initials | `Array` | `false` | From config | - |
+| square | Use square shape instead of circle | `Boolean` | `false` | `false` | - |
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Custom avatar content | `{ src, name, initials, color, onColor, imageError }` | Image or initials |
+| no-img | Custom no-image placeholder | `{ initials, color, onColor }` | Default placeholder icon |
+| loading | Custom loading indicator | `{ isLoading }` | Default loader |
+
+### Events
+
+No events are emitted by this component.
+
+### Config Options
+
+The component uses default configuration from `@AwConfig`:
+
+```javascript
+export default {
+  AwAvatar: {
+    colors: COLORS // Array of color objects
+  }
+}
+```
+
+## Related Components
+
+- `AwUserpic` - User picture component
+- `AwIslandAvatar` - Avatar in island layout
+
+## Notes
+
+- **Import Method:** Global - Available as atom component
+- Automatically extracts initials from name (first letter of first two words)
+- Colors are deterministically generated from name hash for consistency
+- Falls back to initials/placeholder when image fails to load
+- Supports loading state indicator
+- Square variant available for different design needs
+                            

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

@@ -0,0 +1,137 @@
+---
+metaTitle: Card component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwCard /> component is used to render Card - UI Vue component for AwesCode UI.
+title: Card
+---
+
+# Card
+
+**Category:** Atom | **Import:** Global
+
+The `AwCard` component is a flexible container with optional header, title, description, and content sections.
+
+## Overview
+
+`AwCard` provides a structured card container with an optional header section containing title, description, and badge. It's a fundamental building block for displaying grouped content.
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwCard>
+    <AwDescription tag="div">Card content</AwDescription>
+</AwCard>
+```
+
+### With Title
+
+```markup
+<AwCard title="Card Title">
+    <AwDescription tag="div">Card content</AwDescription>
+</AwCard>
+```
+
+### With Title and Description
+
+```markup
+<AwCard
+    title="Card Title"
+    description="Card description text"
+>
+    <AwDescription tag="div">Card content</AwDescription>
+</AwCard>
+```
+
+### With Badge
+
+```markup
+<AwCard title="Featured Card">
+    <template #badge>
+        <AwBadge text="New" color="info" />
+    </template>
+    <AwDescription tag="div">Card content</AwDescription>
+</AwCard>
+```
+
+### Custom Header
+
+```markup
+<AwCard>
+    <template #header>
+        <AwFlow class="pb-2 mb-2 border-b">
+            <AwActionIcon icon="awesio/settings" size="sm" />
+            <AwDescription>Custom header content</AwDescription>
+        </AwFlow>
+    </template>
+    <AwDescription tag="div">Card content</AwDescription>
+</AwCard>
+```
+
+### Custom Title Slot
+
+```markup
+<AwCard>
+    <template #title>
+        <AwFlow :gap="1">
+            <AwActionIcon icon="awesio/check" size="xs" color="success" />
+            <strong>Custom Title with Icon</strong>
+        </AwFlow>
+    </template>
+    <template #badge>
+        <AwBadge text="3" color="error" />
+    </template>
+    <AwDescription tag="div">Card content</AwDescription>
+</AwCard>
+```
+
+### Custom Tag
+
+```markup
+<AwCard tag="article" title="Article Title">
+    <AwDescription tag="div">Article content</AwDescription>
+</AwCard>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| tag | HTML tag for card element | `String` | `false` | `'div'` |
+| titleTag | HTML tag for title | `String` | `false` | `'h3'` |
+| title | Card title text | `String` | `false` | `''` |
+| description | Card description text | `String` | `false` | `''` |
+
+All standard HTML attributes are supported via `$attrs`.
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Main card content | - | - |
+| header | Custom header (replaces default header) | - | Default header with title/description |
+| title | Custom title content | - | Title text |
+| description | Custom description content | - | Description text |
+| badge | Badge content in header | - | - |
+
+### Events
+
+No events are emitted by this component.
+
+## Related Components
+
+- `AwActionCard` - Card with action button
+- `AwDescription` - Description component used in cards
+- `AwBadge` - Badge component for card headers
+
+## Notes
+
+- **Import Method:** Global - Available as atom component
+- Header is automatically shown when title, title slot, or badge slot is provided
+- Description uses `AwDescription` component internally
+- Header has offset styling when content is present
+- Use for grouping related content with consistent styling

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

@@ -0,0 +1,288 @@
+---
+metaTitle: Checkbox component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwCheckbox /> component is used to render Checkbox - UI Vue component for AwesCode UI.
+title: Checkbox
+---
+
+# Checkbox
+
+**Category:** Atom | **Import:** Global
+
+The `AwCheckbox` component is a styled checkbox input with label support and error handling.
+
+## Overview
+
+`AwCheckbox` provides a checkbox input with consistent styling, label support, and error states. It supports both single checkboxes and checkbox groups (when used with arrays).
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwCheckbox v-model="checked" label="Accept terms" />
+```
+
+### With Custom Value
+
+```markup
+<AwCheckbox 
+    v-model="selected" 
+    value="option1" 
+    label="Option 1" 
+/>
+```
+
+### Checkbox Group
+
+```markup
+<AwCheckbox 
+    v-model="selectedItems" 
+    value="item1" 
+    label="Item 1" 
+/>
+<AwCheckbox 
+    v-model="selectedItems" 
+    value="item2" 
+    label="Item 2" 
+/>
+```
+
+### With Error
+
+```markup
+<AwCheckbox 
+    v-model="checked" 
+    label="Required field"
+    :error="errorMessage"
+/>
+```
+
+### Partial State
+
+```markup
+<AwCheckbox 
+    v-model="selectedItems" 
+    value="item1" 
+    label="Item 1"
+    :partial="isPartial"
+/>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| value | Value emitted when checked | `String` / `Number` / `Boolean` / `Object` | `false` | `'on'` |
+| checked | Checked state (boolean, number, or array for groups) | `Array` / `Boolean` / `Number` | `false` | `false` |
+| label | Label text displayed next to checkbox | `String` | `false` | `''` |
+| partial | Show partial/indeterminate state | `Boolean` | `false` | `false` |
+
+All standard HTML checkbox attributes are supported via `$attrs` (e.g., `disabled`, `required`).
+
+Inherits props from `FieldMixin` and `ErrorMixin` for additional field and error handling functionality.
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Custom checkbox element | `{ id, checked, onChange, setError, value }` | Default checkbox input |
+| label | Custom label content | `{ label, value, isChecked }` | Label text |
+
+### Events
+
+| Name | Payload | Description |
+|------|---------|-------------|
+| change | `value` | Emitted when checkbox state changes |
+
+## Component Behavior
+
+### V-Model Implementation
+
+`AwCheckbox` uses a custom v-model configuration:
+
+```javascript
+model: {
+  prop: 'checked',
+  event: 'change'
+}
+```
+
+This means:
+- `v-model="value"` is equivalent to `:checked="value" @change="value = $event"`
+- The `checked` prop receives the current state
+- The `change` event emits the new state
+
+**Single Checkbox (Boolean):**
+```vue
+<template>
+  <AwCheckbox v-model="accepted" label="I accept" />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      accepted: false // Boolean value
+    }
+  }
+}
+</script>
+```
+
+**Checkbox Group (Array):**
+```vue
+<template>
+  <AwCheckbox v-model="selected" value="option1" label="Option 1" />
+  <AwCheckbox v-model="selected" value="option2" label="Option 2" />
+  <AwCheckbox v-model="selected" value="option3" label="Option 3" />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      selected: [] // Array of selected values
+    }
+  }
+}
+</script>
+```
+
+When `checked` is an array, the component automatically:
+- Adds `value` to the array when checked
+- Removes `value` from the array when unchecked
+- Maintains the immutability of the array (returns new arrays)
+
+### Label Usage
+
+The component provides two ways to add a label:
+
+**Via Label Prop (Recommended):**
+```markup
+<AwCheckbox v-model="checked" label="Accept terms" />
+```
+- Simple text label
+- Proper `for` attribute linking
+- Automatic styling
+
+**Via Label Slot (Advanced):**
+```markup
+<AwCheckbox v-model="checked">
+  <template #label="{ label, value, isChecked }">
+    <span :class="{ 'font-bold': isChecked }">{{ label }}</span>
+  </template>
+</AwCheckbox>
+```
+- Custom label rendering
+- Access to component state
+- Full control over styling
+
+**Note:** The default slot is for completely custom checkbox rendering, not for labels. Use the `label` prop or `label` slot for labels.
+
+### Value Handling
+
+The `value` prop determines what gets emitted when the checkbox is checked:
+
+**Default (String):**
+```markup
+<AwCheckbox v-model="checked" />
+<!-- Emits: 'on' when checked -->
+```
+
+**Custom String:**
+```markup
+<AwCheckbox v-model="items" value="item1" />
+<!-- Emits: 'item1' when checked -->
+```
+
+**Number:**
+```markup
+<AwCheckbox v-model="items" :value="42" />
+<!-- Emits: 42 when checked -->
+```
+
+**Object:**
+```markup
+<AwCheckbox v-model="items" :value="{ id: 1, name: 'Item' }" />
+<!-- Emits: the object when checked -->
+```
+
+### Partial/Indeterminate State
+
+The `partial` prop shows a partial/indeterminate state:
+```markup
+<AwCheckbox
+  v-model="selectAll"
+  :partial="someSelected && !allSelected"
+  label="Select All"
+/>
+```
+
+Common use case: "Select All" checkbox in a list:
+- `partial: false` - None or all selected (shows check or empty)
+- `partial: true` - Some selected (shows indeterminate dash)
+
+### Error Handling
+
+Inherits error management from `ErrorMixin`:
+
+```vue
+<template>
+  <AwCheckbox
+    v-model="accepted"
+    label="I accept terms"
+    :error="error"
+  />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      accepted: false,
+      error: ''
+    }
+  },
+  methods: {
+    validate() {
+      if (!this.accepted) {
+        this.error = 'You must accept the terms'
+      }
+    }
+  }
+}
+</script>
+```
+
+Features:
+- Error displayed via tooltip on hover
+- Adds `has-error` class for styling
+- Error clears automatically when state changes
+- Error text shown in tooltip
+
+### Field States
+
+CSS classes applied based on component state:
+- `is-checkbox` - Always present for checkbox type
+- `has-error` - When error is present
+- `fb-field` - When using default slot (custom rendering)
+
+## Related Components
+
+- `AwSwitcher` - Toggle switch component
+- `AwRadio` - Radio button component
+- `AwInput` - Text input component
+
+## Notes
+
+- **Import Method:** Global - Available as atom component
+- Uses v-model with `checked` prop and `change` event
+- Supports checkbox groups when `checked` is an array
+- Automatically manages array when used in groups
+- Supports partial/indeterminate state
+- Extends field and error mixins for label and error handling
+- Value can be any type (string, number, boolean, object)