@awes-io/ui 2.143.0 → 2.144.0

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

@@ -21,33 +21,69 @@ The `AwActionCard` component is a card-like container with a title, optional des
 ### Basic Example
 
 ```markup
-<AwActionCard title="Card Title" href="/path" />
+<AwActionCard
+    title="Simple Action Card"
+    description="This is a basic action card with a title and description"
+/>
 ```
 
 ### With Action Button
 
 ```markup
 <AwActionCard
-    title="Card Title"
-    :action="{ text: 'Action', color: 'accent' }"
-    @action="handleAction"
+    title="Card with Action"
+    description="Click the button to trigger an action"
+    :action="{ text: 'Click Me', color: 'mono-dark' }"
+    @action="onAction"
 />
 ```
 
-### With Slots
+### With Link
+
+```markup
+<AwActionCard
+    title="Clickable Card"
+    description="This entire card is clickable"
+    href="/components"
+/>
+```
+
+### With Content Slot
+
+```markup
+<AwActionCard
+    title="Card with Body"
+    description="This card includes additional body content"
+    :action="{ text: 'Save', color: 'accent' }"
+>
+    <AwActionCardBody title="Details">
+        <AwDescription>You can add any content inside the action card.</AwDescription>
+        <AwList>
+            <li>Item 1</li>
+            <li>Item 2</li>
+            <li>Item 3</li>
+        </AwList>
+    </AwActionCardBody>
+</AwActionCard>
+```
+
+### With Custom Slots
 
 ```markup
-<AwActionCard title="Card Title">
+<AwActionCard
+    title="Custom Card"
+    description="This card uses custom slots for before and after title"
+>
     <template #before-title>
-        <AwButton text="Before" />
+        <AwActionIcon icon="awesio/check" size="sm" />
     </template>
-    
+
     <template #after-title>
-        <AwSwitcher v-model="enabled" />
+        <AwButton text="Custom Action" color="accent" size="sm" />
     </template>
-    
+
     <AwActionCardBody>
-        <h3>Card Content</h3>
+        <AwDescription>Custom slot content with icon before title and custom button after.</AwDescription>
     </AwActionCardBody>
 </AwActionCard>
 ```

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

@@ -18,35 +18,73 @@ The `AwActionIcon` component displays an icon with optional text, with customiza
 
 ## Usage
 
-### Basic Example
+### Different Sizes
 
 ```markup
-<AwActionIcon icon="arrow-animated" />
+<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="star" text="Favorite" size="md" />
+<AwActionIcon icon="awesio/download" text="Download" size="sm" />
+<AwActionIcon icon="awesio/upload" text="Upload" size="md" />
+<AwActionIcon icon="awesio/mail" text="Send" size="lg" />
 ```
 
-### With Image
+### Custom Icon Color
 
 ```markup
-<AwActionIcon :image="{ src: '/path/to/image.png', alt: 'Icon' }" />
+<AwActionIcon
+    icon="awesio/heart"
+    color="mono-100"
+    icon-color="error"
+/>
 ```
 
-### Custom Size and Color
+### Outline Style
 
 ```markup
-<AwActionIcon 
-    icon="awesio/check" 
-    size="lg" 
-    color="accent-500" 
-    onColor="white"
+<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
@@ -56,7 +94,7 @@ The `AwActionIcon` component displays an icon with optional text, with customiza
 | 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 (xxs, xs, sm, md, lg) | `String` | `false` | `'md'` | Must be one of: xxs, xs, sm, md, lg |
+| 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` | `''` | - |

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

@@ -22,7 +22,7 @@ The `AwCard` component is a flexible container with optional header, title, desc
 
 ```markup
 <AwCard>
-    <p>Card content</p>
+    <AwDescription tag="div">Card content</AwDescription>
 </AwCard>
 ```
 
@@ -30,35 +30,60 @@ The `AwCard` component is a flexible container with optional header, title, desc
 
 ```markup
 <AwCard title="Card Title">
-    <p>Card content</p>
+    <AwDescription tag="div">Card content</AwDescription>
 </AwCard>
 ```
 
 ### With Title and Description
 
 ```markup
-<AwCard 
+<AwCard
     title="Card Title"
     description="Card description text"
 >
-    <p>Card content</p>
+    <AwDescription tag="div">Card content</AwDescription>
 </AwCard>
 ```
 
-### With Custom Header
+### 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>
-        <div>Custom header</div>
+        <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>
-        <h2>Custom Title</h2>
+        <AwFlow :gap="1">
+            <AwActionIcon icon="awesio/check" size="xs" color="success" />
+            <strong>Custom Title with Icon</strong>
+        </AwFlow>
     </template>
     <template #badge>
-        <AwBadge>New</AwBadge>
+        <AwBadge text="3" color="error" />
     </template>
-    <p>Content</p>
+    <AwDescription tag="div">Card content</AwDescription>
 </AwCard>
 ```
 
@@ -66,7 +91,7 @@ The `AwCard` component is a flexible container with optional header, title, desc
 
 ```markup
 <AwCard tag="article" title="Article Title">
-    <p>Article content</p>
+    <AwDescription tag="div">Article content</AwDescription>
 </AwCard>
 ```
 

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

@@ -78,10 +78,13 @@ The `AwCheckbox` component is a styled checkbox input with label support and err
 |------|-------------|------|----------|---------|
 | 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 |
@@ -95,6 +98,179 @@ All standard HTML checkbox attributes are supported via `$attrs` (e.g., `disable
 |------|---------|-------------|
 | 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

package/docs/components/atoms/aw-content-placeholder.md

@@ -45,13 +45,20 @@ The `AwContentPlaceholder` component displays animated placeholder content while
 ### Avatar Type
 
 ```markup
-<AwContentPlaceholder type="avatar" />
+<AwFlow :gap="2">
+    <AwContentPlaceholder type="avatar" />
+    <AwContentPlaceholder type="avatar" />
+    <AwContentPlaceholder type="avatar" />
+</AwFlow>
 ```
 
 ### Button Type
 
 ```markup
-<AwContentPlaceholder type="button" :lines="1" />
+<AwGrid :gap="2">
+    <AwContentPlaceholder type="button" :lines="2" />
+    <AwContentPlaceholder type="button" :lines="1" />
+</AwGrid>
 ```
 
 ### Multi-Column Layout
@@ -64,6 +71,30 @@ The `AwContentPlaceholder` component displays animated placeholder content while
 <AwContentPlaceholder type="text" :columns="3" :lines="6" />
 ```
 
+### Loading Simulation
+
+```markup
+<AwCard title="User Profile">
+    <AwFlow v-if="!loading" :gap="2">
+        <AwAvatar :src="data.avatar" :name="data.name" size="lg" />
+        <AwFlow vertical :gap="1">
+            <AwDescription tag="div" class="font-semibold">
+                {{ data.name }}
+            </AwDescription>
+            <AwDescription tag="div" class="text-sm">
+                {{ data.email }}
+            </AwDescription>
+        </AwFlow>
+    </AwFlow>
+    <AwFlow v-else :gap="2">
+        <AwContentPlaceholder type="avatar" />
+        <AwFlow vertical :gap="1" class="flex-1">
+            <AwContentPlaceholder type="text" :lines="2" />
+        </AwFlow>
+    </AwFlow>
+</AwCard>
+```
+
 ## API
 
 ### Props

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

@@ -18,19 +18,25 @@ The `AwDock` component is a slide-up panel that can be opened and closed with to
 
 ## Usage
 
-### Basic Example
+### Basic Example with Visible Slot
 
 ```markup
 <AwDock>
-    <div>Dock content</div>
-</AwDock>
-```
-
-### With Toggle Button
-
-```markup
-<AwDock :togglable="true">
-    <div>Content with toggle button</div>
+    <AwDescription tag="div">
+        Scrollable content
+    </AwDescription>
+
+    <template #visible>
+        <AwButton
+            color="accent"
+            size="lg"
+            icon-right="arrow-animated"
+            highlight-icon
+            class="w-full"
+        >
+            Action
+        </AwButton>
+    </template>
 </AwDock>
 ```
 
@@ -38,10 +44,8 @@ The `AwDock` component is a slide-up panel that can be opened and closed with to
 
 ```markup
 <AwDock prevent-slide="a, button">
-    <div>
-        <a href="#">Link</a>
-        <button>Button</button>
-    </div>
+    <a href="#">Link</a>
+    <button>Button</button>
 </AwDock>
 ```
 
@@ -77,8 +81,10 @@ The `AwDock` component is a slide-up panel that can be opened and closed with to
 ## Notes
 
 - **Import Method:** Global - Available as atom component
+- **Primary Use:** Mobile/tablet component - designed for smaller screens with touch interactions
 - Uses body-scroll-lock to prevent background scrolling when open
 - Supports touch and mouse drag gestures
 - Content in default slot becomes scrollable when dock is fully open
 - Use `visible` slot for content that should always be visible (e.g., action buttons)
+- **Important:** Only one AwDock component should be used per page due to fixed positioning
 

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

@@ -18,42 +18,88 @@ The `AwDropdown` component provides a positioned dropdown menu with mobile and d
 
 ## Usage
 
-### Basic Example
+### Basic Example (Recommended)
+
+The recommended way to control the dropdown is by calling the `toggle()` method via ref:
 
 ```markup
-<template>
-    <div>
-        <button ref="trigger" @click="show = !show">Toggle</button>
-        <AwDropdown :target="trigger" v-model="show">
-            <div>Dropdown content</div>
-        </AwDropdown>
-    </div>
-</template>
+<AwButton color="accent" @click="$refs.dropdown.toggle()">
+    Toggle Dropdown
+</AwButton>
+<AwDropdown ref="dropdown">
+    <AwDescription tag="div" class="p-4">
+        Dropdown content
+    </AwDescription>
+</AwDropdown>
 ```
 
-### With Options
+### With Dropdown Buttons
 
 ```markup
-<AwDropdown 
-    :target="trigger" 
-    v-model="show"
-    :options="{ placement: 'bottom-end' }"
->
-    <AwDropdownButton>Option 1</AwDropdownButton>
-    <AwDropdownButton>Option 2</AwDropdownButton>
+<AwButton color="accent" @click="$refs.dropdown.toggle()">
+    Open Menu
+</AwButton>
+<AwDropdown ref="dropdown">
+    <AwDropdownButton @click="handleAction">
+        Option 1
+    </AwDropdownButton>
+    <AwDropdownButton color="error" @click="handleAction">
+        Option 2
+    </AwDropdownButton>
+    <AwDropdownButton @click="handleAction">
+        Option 3
+    </AwDropdownButton>
+</AwDropdown>
+```
+
+### With State Sync (Alternative)
+
+If you need to track the dropdown state in your component, use `:show.sync`:
+
+```markup
+<AwButton color="accent" @click="show = !show">
+    Open Menu
+</AwButton>
+<AwDropdown :show.sync="show">
+    <AwDropdownButton @click="handleAction">
+        Option 1
+    </AwDropdownButton>
+    <AwDropdownButton @click="handleAction">
+        Option 2
+    </AwDropdownButton>
+</AwDropdown>
+```
+
+### With Target Selector
+
+```markup
+<AwButton id="trigger" color="accent" @click="show = !show">
+    Toggle
+</AwButton>
+
+<div>Some other content between dropdown and button</div>
+
+<AwDropdown target="#trigger" :show.sync="show">
+    <AwDescription tag="div" class="p-4">
+        Dropdown content
+    </AwDescription>
 </AwDropdown>
 ```
 
-### With Title and Description
+### With Title and Description (Mobile)
 
 ```markup
-<AwDropdown 
-    :target="trigger" 
-    v-model="show"
+<AwButton color="accent" @click="show = !show">
+    Open Menu
+</AwButton>
+<AwDropdown
+    :show.sync="show"
     title="Menu Title"
     description="Menu description"
 >
-    <div>Content</div>
+    <AwDescription tag="div" class="p-4">
+        Content
+    </AwDescription>
 </AwDropdown>
 ```
 
@@ -124,5 +170,9 @@ export default {
 - 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
+- **Auto-target detection:** If no `target` prop is specified, the dropdown automatically uses the previous sibling element as the trigger
+- **Recommended control method:** Use `$refs.dropdown.toggle()` for simple show/hide control. This is the preferred approach for most use cases
+- **Alternative state management:** Use `:show.sync` only when you need to track or react to the dropdown's visibility state in your component
+- **Available methods:** Call `toggle()`, `open()`, or `close()` methods directly via refs for programmatic control