@awes-io/ui 2.143.0 → 2.144.0

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

@@ -47,10 +47,7 @@ The `AwList` component renders an ordered list with optional items array or cust
 ### With Item Classes
 
 ```markup
-<AwList 
-    :items="items" 
-    item-class="custom-item-class"
-/>
+<AwList :items="items" item-class="italic" />
 ```
 
 ## API
@@ -73,6 +70,73 @@ The `AwList` component renders an ordered list with optional items array or cust
 
 No events are emitted by this component.
 
+## Component Behavior
+
+### List Rendering Modes
+
+The component supports two rendering modes:
+
+1. **Items Array Mode**: When `items` prop is provided, items are automatically rendered as `<li>` elements
+2. **Default Slot Mode**: When using default slot, you provide `<li>` elements directly
+
+### Items Array Rendering
+
+- Each item in the `items` array is rendered as a list item (`<li>`)
+- Items can be primitives (strings, numbers) or objects
+- Each item gets a key based on its index
+- The `itemClass` prop is applied to each `<li>` element
+- By default, items are rendered as their string representation
+
+### Item Slot Template
+
+When using the `item` slot with the `items` array:
+- **Slot props provided:**
+  - `item` - The current item from the array
+  - `index` - The zero-based index of the item
+- **Use case:** Custom rendering for each item while maintaining automatic list generation
+- **Example:** Displaying object properties, adding icons, conditional rendering
+
+### Default Slot Override
+
+When using the default slot:
+- Completely replaces the automatic item rendering
+- You must provide `<li>` elements yourself
+- The `items` and `itemClass` props are ignored
+- **Use case:** Full control over list structure, nested lists, custom markup
+
+### Item Classes
+
+The `itemClass` prop accepts:
+- **String:** Single class name or space-separated classes (e.g., `"italic"`, `"text-sm font-bold"`)
+- **Array:** Array of class names (e.g., `["italic", "text-sm"]`)
+- **Object:** Class object (Vue class binding syntax, e.g., `{ italic: true, bold: isImportant }`)
+- Applied to each `<li>` when using `items` array
+- Ignored when using default slot
+- Useful for applying Tailwind utility classes to all list items
+
+### Structure
+
+**With items array:**
+```
+<ol class="aw-list">
+  <li :class="itemClass">
+    <slot name="item" :item="item" :index="index">
+      {{ item }}
+    </slot>
+  </li>
+  ...
+</ol>
+```
+
+**With default slot:**
+```
+<ol class="aw-list">
+  <slot>
+    <!-- Your custom <li> elements -->
+  </slot>
+</ol>
+```
+
 ## Related Components
 
 - `AwCard` - Card component that may contain lists

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

@@ -27,7 +27,7 @@ The `AwProgress` component displays an animated progress bar with customizable c
 ### With Custom Color
 
 ```markup
-<AwProgress :progress="50" color="success-500" />
+<AwProgress :progress="50" color="success" />
 ```
 
 ### With Initial Value from URL
@@ -45,7 +45,7 @@ The `AwProgress` component displays an animated progress bar with customizable c
 |------|-------------|------|----------|---------|
 | progress | Progress value (0-100) | `Number` | `false` | `0` |
 | prevValueParam | URL query parameter name for initial value | `String` | `false` | `'prev_progress'` |
-| color | Progress bar color | `String` | `false` | `'accent'` |
+| color | Progress bar color - see [Built-in Colors](/reference/colors) | `String` | `false` | `'accent'` |
 
 ### Slots
 
@@ -55,6 +55,55 @@ No slots are available for this component.
 
 No events are emitted by this component.
 
+## Component Behavior
+
+### Progress Value
+
+- Progress value is automatically clamped between 0 and 100
+- Values below 0 are treated as 0
+- Values above 100 are treated as 100
+- The progress ratio is calculated as `value / 100` with 4 decimal precision
+
+### Animation
+
+The component uses anime.js for smooth progress animations:
+- **Duration:** 1000ms (1 second)
+- **Easing:** easeOutCirc - Creates a smooth deceleration effect
+- **Trigger:** Automatically animates when `progress` prop changes
+- **Initial animation:** Runs on component mount
+
+### Initial Value from URL
+
+The component can read an initial progress value from URL query parameters:
+- **Parameter name:** Configurable via `prevValueParam` prop (default: `prev_progress`)
+- **Use case:** Preserving progress state across page navigation
+- **Example:** URL `/page?prev_progress=30` will start at 30% and animate to the `progress` prop value
+
+### Color System
+
+- Uses CSS custom property `--color` for the progress bar fill
+- Color is converted using the `toColor` utility function
+- Supports all semantic colors (accent, success, info, warning, error)
+- Supports mono scale and custom colors
+- Default color is `accent`
+
+### CSS Variables
+
+The component sets two CSS custom properties:
+- `--progress` - The progress ratio (0.0000 to 1.0000)
+- `--color` - The progress bar fill color
+
+### Structure
+
+```
+<div class="aw-progress" :style="{
+  --progress: progressRatio,
+  --color: fgColor
+}"></div>
+```
+
+The actual progress bar styling is handled by CSS using these custom properties.
+
 ## Related Components
 
 - `AwButton` - Button component that may show loading/progress
@@ -66,5 +115,5 @@ No events are emitted by this component.
 - Progress value is clamped between 0 and 100
 - Animation duration is 1000ms with easeOutCirc easing
 - Initial value can be read from URL query parameters
-- Color supports theme color names (e.g., 'accent', 'success-500')
+- Color supports theme color names (e.g., 'accent', 'success')
 

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

@@ -93,6 +93,79 @@ All standard HTML radio attributes are supported via `$attrs` (e.g., `disabled`,
 |------|---------|-------------|
 | change | `value` | Emitted when radio is selected |
 
+## Component Behavior
+
+### Radio Group Logic
+
+- Radio buttons work as a group when they share the same `v-model` binding
+- Only one radio in a group can be selected at a time
+- When a radio is selected, its `value` is emitted via the `change` event
+- The `checked` prop (v-model binding) is compared to each radio's `value` to determine selection
+- Selection is determined by strict equality: `checked === value`
+
+### Value Types
+
+The component supports three value types:
+- **String:** Most common, e.g., `value="option1"`
+- **Number:** For numeric choices, e.g., `:value="1"` (use `:value` binding)
+- **Boolean:** For yes/no choices, e.g., `:value="true"` (use `:value` binding)
+
+**Important:** When using number or boolean values, use the `:value` binding syntax (v-bind) instead of plain `value` attribute.
+
+### Model Binding
+
+- Uses `v-model` with custom model definition
+- Model prop: `checked` - The currently selected value
+- Model event: `change` - Emitted when selection changes
+- Usage: `v-model="selectedValue"`
+
+### Label Rendering
+
+- Label is optional but recommended for accessibility
+- If `label` prop is provided, renders a `<label>` element linked to the radio input
+- Label slot receives: `{ label, value, isChecked }`
+- Clicking the label toggles the radio (native browser behavior)
+
+### Error Handling
+
+The component extends the ErrorMixin:
+- Supports `error` prop for error messages
+- Shows error tooltip on hover when error is present
+- Automatically clears error on selection change
+- Error state adds visual styling via `has-error` class
+
+### Field Attributes
+
+Extends FieldMixin for consistent field behavior:
+- Supports standard HTML radio attributes via `$attrs`
+- Common attributes: `disabled`, `required`, `name`
+- Auto-generates unique ID if not provided
+- Links label to input via `for`/`id` attributes
+
+### Accessibility
+
+- Proper label-input association via `id` and `for` attributes
+- Error messages linked via `aria-describedby`
+- Supports all native radio button keyboard navigation
+- Disabled state properly communicated to screen readers
+
+### Structure
+
+```
+<div class="aw-switch-field is-radio" :class="{ 'has-error': hasError }">
+  <input
+    type="radio"
+    class="aw-switch-field__element"
+    :id="id"
+    :value="value"
+    :checked="isChecked"
+  />
+  <label class="aw-switch-field__label" :for="id">
+    <slot name="label">{{ label }}</slot>
+  </label>
+</div>
+```
+
 ## Related Components
 
 - `AwCheckbox` - Checkbox component

package/docs/components/atoms/aw-select-native.md

@@ -89,6 +89,134 @@ The `AwSelectNative` component is a styled wrapper around the native HTML select
 |------|---------|-------------|
 | input | `value` | Emitted when selection changes |
 
+## Component Behavior
+
+### Option Handling
+
+The component supports two types of options:
+
+#### String Arrays
+```javascript
+options: ['Option 1', 'Option 2', 'Option 3']
+```
+- Simple string arrays where each string is both the label and value
+- Ideal for basic dropdowns with simple text options
+
+#### Object Arrays
+```javascript
+options: [
+  { id: 1, name: 'Option 1' },
+  { id: 2, name: 'Option 2' }
+]
+```
+- Requires `optionLabel` prop to specify which property to display
+- Requires `trackBy` prop to specify which property to use as value
+- Supports nested properties using dot notation (e.g., `'user.name'`)
+
+### Option Label and TrackBy
+
+Both `optionLabel` and `trackBy` props accept:
+
+**String (property path):**
+```markup
+<AwSelectNative
+  :options="users"
+  option-label="name"
+  track-by="id"
+/>
+```
+
+**Function:**
+```markup
+<AwSelectNative
+  :options="users"
+  :option-label="user => `${user.firstName} ${user.lastName}`"
+  :track-by="user => user.id"
+/>
+```
+
+**Nested properties:**
+```markup
+<AwSelectNative
+  :options="items"
+  option-label="user.profile.name"
+  track-by="user.id"
+/>
+```
+
+### Disabled Options
+
+The `optionDisabled` prop accepts a function that determines if an option should be disabled:
+
+```javascript
+optionDisabled(option) {
+  return !option.available || option.stock === 0
+}
+```
+
+Disabled options appear in the dropdown but cannot be selected.
+
+### Label Behavior
+
+- Label appears as floating label inside the select field
+- When option is selected, label moves to top position (filled state)
+- Required indicator (`*`) shown when field has `required` attribute
+- Label slot provides full customization
+
+### Prefix and Postfix
+
+- **Prefix:** Displayed before the select dropdown (e.g., "https://")
+- **Postfix:** Displayed after the select dropdown (e.g., ".com")
+- Both support text or custom slot content
+- Useful for adding context or units to the selection
+
+### Size Variants
+
+- **sm:** Smaller padding (p-2) - compact dropdowns
+- **md:** Medium padding (p-3) - default, standard size
+
+### Error Handling
+
+Extends ErrorMixin for error management:
+- Shows error tooltip on hover when error is present
+- Error state adds visual styling via `has-error` class
+- Error automatically clears when selection changes
+- Error message displayed via tooltip
+
+### Field States
+
+The component applies CSS classes based on state:
+- `is-filled` - When a valid option is selected
+- `has-label` - When label prop is provided
+- `has-error` - When error is present
+- `is-disabled` - When disabled attribute is set
+- `has-prefix` - When prefix is provided
+- `has-postfix` - When postfix is provided
+
+### Native Select Element
+
+- Uses native HTML `<select>` element for better mobile support
+- Inherits all standard HTML select attributes via `$attrs`
+- Native mobile picker UI on iOS and Android
+- Better accessibility with native keyboard navigation
+- No custom dropdown UI to maintain
+
+### Structure
+
+```
+<div class="aw-text-field is-select">
+  <div class="aw-text-field__prefix">Prefix</div>
+  <div class="relative">
+    <select class="aw-text-field__element">
+      <option>...</option>
+    </select>
+    <label class="aw-text-field__label">Label</label>
+    <div class="aw-text-field__caret">▼</div>
+  </div>
+  <div class="aw-text-field__postfix">Postfix</div>
+</div>
+```
+
 ## Related Components
 
 - `AwSelect` - Advanced select component with search and custom options

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

@@ -21,23 +21,31 @@ The `AwSlider` component provides a horizontal scrollable container with drag su
 ### Basic Example
 
 ```markup
-<AwSlider>
-    <div class="flex gap-4">
-        <div>Item 1</div>
-        <div>Item 2</div>
-        <div>Item 3</div>
-    </div>
+<AwSlider :gap="4">
+    <div>Item 1</div>
+    <div>Item 2</div>
+    <div>Item 3</div>
 </AwSlider>
 ```
 
 ### Custom Tag
 
 ```markup
-<AwSlider tag="section">
+<AwSlider tag="section" :gap="3">
     <div>Scrollable content</div>
 </AwSlider>
 ```
 
+### With Gap Spacing
+
+```markup
+<AwSlider :gap="6">
+    <AwCard v-for="n in 5" :key="n" class="flex-shrink-0">
+        Card {{ n }}
+    </AwCard>
+</AwSlider>
+```
+
 ## API
 
 ### Props
@@ -45,6 +53,7 @@ The `AwSlider` component provides a horizontal scrollable container with drag su
 | Name | Description | Type | Required | Default |
 |------|-------------|------|----------|---------|
 | tag | HTML tag for container | `String` | `false` | `'div'` |
+| gap | Gap between items (1-8) | `Number` | `false` | `0` |
 
 ### Slots
 
@@ -64,6 +73,104 @@ The `AwSlider` component provides a horizontal scrollable container with drag su
 |------|-----------|-------------|
 | scrollTo | `element` | Scrolls to the specified child element |
 
+## Component Behavior
+
+### Scrolling Mechanism
+
+The component provides multiple ways to scroll:
+- **Mouse drag:** Click and drag horizontally to scroll
+- **Touch drag:** Touch and swipe horizontally on mobile devices
+- **Native scroll:** Use scrollbar or trackpad/mouse wheel
+- **Programmatic:** Use the `scrollTo(element)` method
+
+### Drag Detection
+
+The component intelligently distinguishes between clicks and drags:
+- **Click threshold (time):** 300ms - Movement within this time may be treated as click
+- **Click threshold (distance):** 5px - Movement less than this may be treated as click
+- **Drag detection:** If movement exceeds either threshold, it's treated as a drag
+- **Click prevention:** During drag operations, click events are prevented to avoid unintended actions
+
+### Shadow Indicators
+
+Visual feedback for scrollable content:
+- **Left shadow:** Appears when content can be scrolled to the left (opacity: 0 when at start)
+- **Right shadow:** Appears when content can be scrolled to the right (opacity: 0 when at end)
+- **Responsive:** Shadows automatically update as user scrolls or content changes
+- **Overscroll handling:** Shadows properly handle browser overscroll behavior
+
+### Resize Handling
+
+The component automatically adapts to size changes:
+- **Window resize listener:** Listens to window resize events
+- **Debounced update:** Waits 300ms after resize before recalculating dimensions
+- **Dimension recalculation:** Updates scroll width, container width, and scroll position
+- **Resize event:** Emits `resized` event after recalculation completes
+- **Border correction:** Ensures scroll position stays within valid bounds after resize
+
+### Programmatic Scrolling
+
+Use the `scrollTo` method to scroll to specific child elements:
+
+```javascript
+// Scroll to a specific element
+this.$refs.slider.scrollTo(this.$refs.targetElement)
+```
+
+**How it works:**
+- Calculates the cumulative width of all child elements before the target
+- Includes margins and borders in width calculation
+- Scrolls to position the target element at the start of the visible area
+- Respects scroll boundaries (won't scroll beyond max scroll position)
+
+### Dimension Calculation
+
+The component calculates child element dimensions including:
+- **scrollWidth:** Full content width including overflow
+- **margins:** Left and right margins
+- **borders:** Left and right borders
+- Uses `getComputedStyle` for accurate measurements
+
+### Mouse Move State
+
+- **movedByMouse flag:** Tracks whether scrolling is currently controlled by mouse/touch
+- **Event listeners:** Dynamically adds/removes mousemove and mouseup listeners
+- **Performance:** Only active during drag operations to minimize overhead
+- **Clean up:** Properly removes listeners on component destroy
+
+### Touch Support
+
+- **Touch events:** Fully supports touch gestures on mobile devices
+- **pageX detection:** Automatically detects touch coordinates from touch events
+- **Native mobile scroll:** Works seamlessly with native mobile scrolling behavior
+
+### Gap Spacing
+
+The component includes a built-in `gap` prop for spacing between items:
+- **Supported values:** 1, 2, 3, 4, 5, 6, 8 (maps to Tailwind gap classes)
+- **Default:** 0 (no gap)
+- **Usage:** `:gap="4"` applies `gap-4` class to the scroller
+- Eliminates need for wrapper flex containers with gap classes
+
+### Content Requirements
+
+For proper functionality:
+- Items should have `flex-shrink-0` class to prevent shrinking
+- Total content width should exceed container width to enable scrolling
+- Use the `gap` prop for spacing between items instead of manual flex wrappers
+
+### Structure
+
+```
+<div class="aw-slider">
+  <span class="aw-slider__scroller">
+    <slot /> <!-- Your scrollable content -->
+  </span>
+  <span class="aw-slider__shadow aw-slider__shadow_left" />
+  <span class="aw-slider__shadow aw-slider__shadow_right" />
+</div>
+```
+
 ## Related Components
 
 - `AwFlow` - Flow layout component

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

@@ -98,6 +98,83 @@ All props from `AwCheckbox` are also supported.
 |------|---------|-------------|
 | change | `value` | Emitted when switch state changes |
 
+## Component Behavior
+
+### Toggle Interaction
+
+The component supports two methods of toggling:
+
+**Click to toggle:**
+- Single click/tap anywhere on the switch toggles the state
+- Works on the toggle circle, background, or label
+
+**Drag to toggle:**
+- Click/touch and drag horizontally to switch states
+- Drag threshold is 5 pixels to prevent accidental toggles
+- Visual feedback shows state change during drag
+- Works with both mouse and touch events
+
+### Drag Detection
+
+The component intelligently distinguishes between clicks and drags:
+- **Threshold:** 5 pixels of horizontal movement
+- **Click:** Movement less than threshold triggers immediate toggle
+- **Drag:** Movement exceeds threshold, switch follows drag direction
+- **Right drag (unchecked → checked):** Turns switch on when dragging right
+- **Left drag (checked → unchecked):** Turns switch off when dragging left
+
+### Icon Display
+
+Icons are displayed based on size and props:
+- **sm size:** Icons are never shown (too small)
+- **md size:** Icons shown at 12px, can be placed outside or inside toggle circle
+- **lg size:** Icons shown at 22px, can be placed outside or inside toggle circle
+
+**Icon placement:**
+- `iconPlaceIn={false}` (default): Icons appear outside the toggle circle (active on left, inactive on right)
+- `iconPlaceIn={true}`: Single icon appears inside the moving toggle circle
+
+**Icon props:**
+- `icon`: Icon shown when switch is active/on
+- `offIcon`: Icon shown when switch is inactive/off (defaults to `icon` value if not specified)
+- `hideIcon`: Completely hides all icons regardless of size
+
+For a complete list of available icons, see [Built-in Icons](/reference/icons).
+
+### Color System
+
+Background colors adapt to switch state:
+- **Active (checked):** Uses `activeColor` prop (default: `'success'`)
+- **Inactive (unchecked):** Uses `inactiveColor` prop (default: transparent/gray)
+- Colors accept any valid color from the AwesCode UI color system
+- Common active colors: `success`, `info`, `warning`, `error`, `accent`
+
+For a complete list of available colors, see [Built-in Colors](/reference/colors).
+
+### State Management
+
+Extends `AwCheckbox` for state handling:
+- Supports `v-model` for two-way binding
+- `checked` prop accepts Boolean, Array, or Number
+- `value` prop specifies the value emitted when checked
+- Internal state tracks both checkbox state and drag position
+- Watch updates internal state when external `checked` prop changes
+
+### Event Listeners
+
+The component dynamically manages event listeners:
+- **Mouse/touch down:** Initiates drag detection, adds move/up listeners
+- **Mouse/touch move:** Tracks drag position, updates visual state
+- **Mouse/touch up:** Completes toggle action, removes listeners
+- **Cleanup:** All listeners properly removed on component destroy
+
+### Touch Support
+
+Full touch gesture support for mobile devices:
+- Touch events (touchstart, touchmove, touchend) handled separately from mouse
+- Uses `screenX` for accurate position tracking across devices
+- Prevents unwanted interactions during drag operations
+
 ## Related Components
 
 - `AwCheckbox` - Checkbox component (extended by switcher)