@awes-io/ui 2.142.3 → 2.144.0

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

@@ -0,0 +1,235 @@
+---
+metaTitle: Icon component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwIcon /> component is used to render Icon - UI Vue component for AwesCode UI.
+title: Icon
+---
+
+# Icon
+
+**Category:** Atom | **Import:** Global
+
+The `AwIcon` component renders SVG icons from the icon system, supporting custom icons, system icons, and animated icons.
+
+## Overview
+
+`AwIcon` is a functional component that renders icons from multiple sources:
+- Custom SVG icons (via SVG sprite)
+- System icons (mono and color variants)
+- Animated icons
+
+It automatically detects the icon type and renders the appropriate component.
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwIcon name="star" />
+```
+
+### Custom Size
+
+```markup
+<AwIcon name="star" size="24" />
+<AwIcon name="star" :size="32" />
+```
+
+### With Color
+
+```markup
+<AwIcon name="star" color="accent" />
+```
+
+### System Icons
+
+```markup
+<AwIcon name="awesio/arrow" />
+<AwIcon name="awesiocolor/check" />
+```
+
+### Animated Icons
+
+```markup
+<AwIcon name="arrow-animated" />
+```
+
+### With Rotation
+
+```markup
+<AwIcon name="awesio/arrow::180" />
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| name | Icon name (required) - see [Built-in Icons](/reference/icons) | `String` | `true` | - |
+| size | Icon size (pixels or number) | `String` / `Number` | `false` | `null` |
+| color | Icon fill color - see [Built-in Colors](/reference/colors) | `String` | `false` | `''` |
+| viewBox | Custom SVG viewBox | `String` | `false` | `null` |
+| className | Additional CSS class | `String` | `false` | - |
+
+### Slots
+
+No slots are available for this component.
+
+### Events
+
+No events are emitted by this component.
+
+## Icon Types
+
+`AwIcon` automatically detects the icon type based on the `name` prop and renders the appropriate component internally. The detection follows this priority order:
+
+1. **Animated Icons** - Checked first by exact name match
+2. **System Icons** - Detected by prefix (`awesio/` or `awesiocolor/`)
+3. **Custom Icons** - Fallback to SVG sprite system
+
+### Custom Icons
+Custom SVG icons loaded via SVG sprite system. These are icons you add to your project's SVG sprite:
+```markup
+<AwIcon name="custom-icon-name" />
+```
+
+**How it works:**
+- Component renders `SvgIcon` which looks up the icon in the SVG sprite
+- Icons are loaded from your project's sprite system
+- Use for project-specific icons not in the built-in sets
+
+### System Mono Icons
+Built-in monochrome system icons from `@AwUtils/icons/mono`. Single-color SVG paths that inherit text color:
+```markup
+<AwIcon name="awesio/arrow" />
+<AwIcon name="awesio/check" />
+<AwIcon name="awesio/settings" />
+```
+
+**How it works:**
+- Component detects `awesio/` prefix and renders `AwIconSystemMono`
+- Icon name is extracted (e.g., `arrow` from `awesio/arrow`)
+- Supports rotation using `::` syntax: `awesio/arrow::180`
+- Icons inherit current text color via CSS
+- All icons are 24x24 viewBox by default
+
+**Available Mono Icons:**
+`angle`, `angle-r`, `arrow`, `arrow-r`, `ban`, `check`, `check-circle`, `circle`, `close`, `close-circle`, `delete`, `download`, `drag`, `edit`, `empty-box`, `external`, `eye`, `eye-no`, `filter`, `file-csv`, `file-excel`, `file-image`, `file-pdf`, `file-word`, `image`, `info-circle`, `light`, `lock`, `mail`, `menu`, `menu-dots`, `more`, `more-v`, `phone`, `plus`, `plus-circle`, `plus-fill-square`, `profile`, `save`, `search`, `settings`, `triangle`, `undo`, `upload`, `user`, `warning`
+
+### System Color Icons
+Built-in multicolor system icons from `@AwUtils/icons/multicolor`. Icons with multiple colors for illustrations and decorative purposes:
+```markup
+<AwIcon name="awesiocolor/loader" />
+<AwIcon name="awesiocolor/spinner" />
+```
+
+**How it works:**
+- Component detects `awesiocolor/` prefix and renders `AwIconSystemColor`
+- Icon name is extracted (e.g., `loader` from `awesiocolor/loader`)
+- Icons have predefined dimensions and colors
+- Best for loading states and animated indicators
+
+**Available Color Icons:**
+`loader`, `spinner`
+
+**Note:** Color icons have predefined dimensions. Use `width` and `height` props on `AwIconSystemColor` to override if needed. Color icons are best for loading states and animated indicators.
+
+### Animated Icons
+Special animated icons from `@AwUtils/icons/animated`. Icons with CSS animations:
+```markup
+<AwIcon name="arrow-animated" />
+```
+
+**How it works:**
+- Component checks for exact name match in animated icons first
+- Renders inline SVG with animation classes
+- Animations are defined via CSS classes in the icon content
+- Use for loading states and interactive feedback
+
+**Available Animated Icons:**
+`arrow-animated`
+
+## Related Components
+
+- `AwIconSystemMono` - System mono icon component
+- `AwIconSystemColor` - System color icon component
+- `AwButton` - Button component that uses icons
+
+## Icon Detection Logic
+
+The component uses the following detection logic (in order):
+
+1. **Animated Icons**: Checks if name exists in `ANIMATED_ICONS` object
+   - If found: Renders inline SVG with animation classes
+   - Example: `arrow-animated` → renders animated SVG
+
+2. **System Icons**: Checks if name matches pattern `/^awesio(color)?\/.+/`
+   - If `awesiocolor/` prefix: Renders `AwIconSystemColor` with extracted name
+   - If `awesio/` prefix: Renders `AwIconSystemMono` with extracted name and optional rotation
+   - Example: `awesio/arrow::180` → extracts `arrow` and `180` for rotation
+
+3. **Custom Icons**: Falls back to `SvgIcon` component
+   - Looks up icon in SVG sprite system
+   - Example: `custom-icon` → searches sprite for matching icon
+
+## Examples
+
+### Mono Icons with Rotation
+```markup
+<AwIcon name="awesio/arrow" />
+<AwIcon name="awesio/arrow::90" />
+<AwIcon name="awesio/arrow::180" />
+<AwIcon name="awesio/arrow::270" />
+```
+
+### Color Icons for Loading States
+```markup
+<div v-if="loading">
+    <AwIcon name="awesiocolor/loader" />
+    <p>Loading...</p>
+</div>
+```
+
+### Animated Loading States
+```markup
+<AwIcon name="arrow-animated" size="32" />
+```
+
+### Different Icon Types Together
+```markup
+<div class="flex gap-4">
+    <!-- Mono icon -->
+    <AwIcon name="awesio/check" color="success" />
+    
+    <!-- Color icon -->
+    <AwIcon name="awesiocolor/loader" />
+    
+    <!-- Animated icon -->
+    <AwIcon name="arrow-animated" />
+    
+    <!-- Custom icon -->
+    <AwIcon name="custom-logo" />
+</div>
+```
+
+## Viewing All Available Icons
+
+To see all available built-in icons, visit the Icons page in the example project at `/icons`. The page displays:
+- All mono icons with `awesio/` prefix
+- All color icons with `awesiocolor/` prefix  
+- All animated icons
+- Search functionality to find icons by name
+
+## Notes
+
+- **Import Method:** Global - Available as atom component
+- Functional component for optimal performance
+- Automatically detects icon type from name pattern
+- Size defaults to text size (1em) if not specified
+- Supports rotation for mono system icons using `::` syntax (e.g., `awesio/arrow::180`)
+- Animated icons are automatically detected and rendered with CSS animations
+- Color prop sets fill color via CSS custom properties (works with mono icons)
+- Mono icons inherit text color when color prop is not provided
+- Color icons have fixed colors defined in the icon data

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

@@ -0,0 +1,123 @@
+---
+metaTitle: Info component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwInfo /> component is used to render Info - UI Vue component for AwesCode UI.
+title: Info
+---
+
+# Info
+
+**Category:** Atom | **Import:** Global
+
+The `AwInfo` component displays information with an optional label and help tooltip.
+
+## Overview
+
+`AwInfo` provides a structured way to display information with a label and optional help icon. It's useful for displaying read-only data in forms or detail views.
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwInfo label="Email" text="user@example.com" />
+```
+
+### With Help Tooltip
+
+```markup
+<AwInfo 
+    label="Status" 
+    text="Active"
+    help="Current account status"
+/>
+```
+
+### With Custom Content
+
+```markup
+<AwInfo label="Details">
+    <div>Custom content here</div>
+</AwInfo>
+```
+
+### Required Field
+
+```markup
+<AwInfo label="Name" text="John Doe" required />
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| label | Subtitle/label for the element | `String` | `false` | `''` |
+| help | Tooltip text with help icon | `String` | `false` | `''` |
+| text | Text content (string or number) | `String` / `Number` | `false` | `''` |
+| required | Show required indicator | `Boolean` | `false` | `false` |
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Custom content (replaces text) | - | Text prop value or '—' |
+| icon | Custom help icon | - | Default info-circle icon |
+
+### Events
+
+No events are emitted by this component.
+
+## Related Components
+
+- `AwDescription` - Description component
+- `AwLabel` - Label component
+- `AwInput` - Input component
+
+## Component Behavior
+
+### Label Display
+- Label is rendered only when `label` prop is provided
+- Label uses `AwDescription` component with `<span>` tag
+- When `required` is true, label receives `aw-info__label--required` class for styling
+
+### Help Tooltip
+- Help icon appears only when `help` prop is provided
+- Tooltip is positioned to the right of the label
+- Tooltip uses Vue tooltip directive with `:right.prepend` modifiers
+- Default help icon is `info-circle` from AwIconSystemMono
+- Help icon can be customized using the `icon` slot
+
+### Content Display
+- Default slot takes precedence over `text` prop
+- When default slot has content, `text` prop is ignored
+- When no slot content and no `text` prop, displays '—' (em dash)
+- Slot detection uses `notEmptyNode` utility to filter empty nodes
+- Text content is rendered in a `<div>` wrapper
+
+### Structure
+```
+<div class="aw-info">
+  <div class="aw-info__label" [class.aw-info__label--required]>
+    <AwDescription tag="span">{{ label }}</AwDescription>
+    <slot name="icon">
+      <span v-tooltip>
+        <AwIconSystemMono name="info-circle" />
+      </span>
+    </slot>
+  </div>
+  <slot /> or <div>{{ text || '—' }}</div>
+</div>
+```
+
+## Notes
+
+- **Import Method:** Global - Available as atom component
+- Shows '—' (em dash) when text is empty and no slot content
+- Help icon appears when `help` prop is provided
+- Default help icon is `info-circle` from system icons
+- Use for displaying read-only information in forms or detail views
+- Component checks for non-empty slot nodes using `$scopedSlots` API
+- Supports both string and number values for `text` prop

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

@@ -0,0 +1,212 @@
+---
+metaTitle: Input component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwInput /> component is used to render Input - UI Vue component for AwesCode UI.
+title: Input
+---
+
+# Input
+
+**Category:** Atom | **Import:** Global
+
+The `AwInput` component is a styled text input field with label, error handling, and optional prefix/postfix slots.
+
+## Overview
+
+`AwInput` provides a comprehensive text input component with consistent styling, label support, error states, and flexible slot-based customization. It extends the text field mixin for common input functionality.
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwInput v-model="value" placeholder="Enter text" />
+```
+
+### With Label
+
+```markup
+<AwInput v-model="email" label="Email" placeholder="your@email.com" />
+```
+
+### With Prefix and Postfix
+
+```markup
+<AwInput 
+    v-model="url" 
+    label="Website"
+    prefix="https://"
+    postfix=".com"
+/>
+```
+
+### With Icon
+
+```markup
+<AwInput v-model="search" label="Search">
+    <template #icon>
+        <AwIcon name="awesio/search" class="mx-3" />
+    </template>
+</AwInput>
+```
+
+### With Error
+
+```markup
+<AwInput 
+    v-model="value" 
+    label="Required Field"
+    :error="errorMessage"
+/>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default | Validator |
+|------|-------------|------|----------|---------|-----------|
+| type | Input type (text, email, number, etc.) | `String` | `false` | `'text'` | Must not be checkbox, radio, date, tel, color |
+| prefix | Prefix text or slot content | `String` | `false` | `''` | - |
+| postfix | Postfix text or slot content | `String` | `false` | `''` | - |
+| size | Input size (sm, md) | `String` | `false` | `'md'` | Must be one of configured sizes |
+| theme | CSS theme modifiers | `String` | `false` | `''` | - |
+
+All standard HTML input attributes are also supported via `$attrs`.
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Custom input element | `{ cssClass, value, errorTooltip, mergedListeners, mergedAttributes, errorText, errorId }` | Default input element |
+| prefix | Custom prefix content | - | Prefix text |
+| postfix | Custom postfix content | - | Postfix text |
+| icon | Icon slot | - | - |
+| label | Custom label content | `{ cssClass }` | Label text |
+
+### Events
+
+All standard input events are supported (e.g., `input`, `focus`, `blur`, `change`).
+
+### Config Options
+
+The component uses default configuration from `@AwConfig`:
+
+```javascript
+export default {
+  AwInput: {
+    baseClass: 'aw-text-field',
+    sizes: ['sm', 'md']
+  }
+}
+```
+
+## Component Behavior
+
+### Input Type Validation
+- Invalid types (checkbox, radio, date, tel, color) trigger console errors
+- Invalid type suggestions:
+  - `checkbox` → Use `<AwCheckbox />` or `<AwSwitcher />`
+  - `radio` → Use `<AwRadio />`
+  - `date/datetime/time/month/week` → Use `<AwDate />`
+  - `tel` → Use `<AwTel />`
+- Type validation runs via prop validator
+- **Preferred alternatives for number/money:**
+  - For number inputs → Use `<AwNumber />` (preferred over `type="number"`)
+  - For money/currency inputs → Use `<AwMoney />` (preferred over `type="number"` with prefix/postfix)
+
+### Label Behavior
+- Label appears only when `label` prop or `label` slot is provided
+- Label is rendered inside the input wrapper (floating label pattern)
+- Required indicator shown when `isRequired` is true (from TextFieldMixin)
+- Label receives `aw-text-field__label--required` class when required
+
+### Prefix and Postfix
+- Prefix/postfix can be text (via props) or custom content (via slots)
+- When using text props, wrapper receives `px-4` padding
+- Prefix appears before the input, postfix after
+- CSS classes: `aw-text-field__prefix`, `aw-text-field__postfix`
+- Wrapper adds `has-prefix` or `has-postfix` classes for styling
+
+### Icon Slot
+- Icon slot renders inside the input wrapper
+- When icon slot has content, wrapper adds `has-icon` class
+- Icon positioned with `aw-text-field__icon` class
+- Recommended to add `mx-3` class to icons for proper spacing
+
+### Size and Padding
+- Two sizes: `md` (default) and `sm`
+- Size affects input padding:
+  - `md` → `p-3` (12px padding)
+  - `sm` → `p-2` (8px padding)
+- Size validation checks against configured sizes in `_config.sizes`
+
+### Error Handling
+- Error state managed by TextFieldMixin
+- Error tooltip shows on input with `v-tooltip.show.prepend`
+- Input receives `data-error` attribute when error exists
+- Input uses `aria-describedby` for error accessibility
+- Error text and ID provided via scoped slot bindings
+
+### Theme Modifiers
+- `theme` prop accepts comma-separated modifiers
+- Each modifier adds `aw-text-field--{modifier}` class
+- Example: `theme="compact,bordered"` → `aw-text-field--compact aw-text-field--bordered`
+
+### Structure
+```
+<label class="aw-text-field is-{type} [has-icon] [has-prefix] [has-postfix]">
+  <div class="aw-text-field__prefix [px-4]">
+    <slot name="prefix">{{ prefix }}</slot>
+  </div>
+
+  <div class="relative w-full">
+    <slot name="element" v-bind="{ cssClass, value, errorTooltip, ... }">
+      <input
+        class="aw-text-field__element [p-3|p-2]"
+        :value="inputValue"
+        :aria-describedby="errorId"
+        :data-error="errorText"
+        v-tooltip.show.prepend="errorTooltip"
+      />
+    </slot>
+
+    <div class="aw-text-field__label [aw-text-field__label--required]">
+      <slot name="label">{{ label }}</slot>
+    </div>
+
+    <span class="aw-text-field__icon">
+      <slot name="icon" />
+    </span>
+  </div>
+
+  <div class="aw-text-field__postfix [px-4]">
+    <slot name="postfix">{{ postfix }}</slot>
+  </div>
+</label>
+```
+
+## Related Components
+
+- `AwTextarea` - Multi-line text input
+- `AwPassword` - Password input
+- `AwSelect` - Select dropdown
+- `AwDate` - Date input
+- `AwTel` - Telephone input
+- `AwNumber` - Number input with formatting
+- `AwMoney` - Money/currency input with formatting
+
+## Notes
+
+- **Import Method:** Global - Available as atom component
+- Extends `TextFieldMixin` for common field functionality (value, error, label, validation)
+- Supports error states with tooltip display
+- Invalid input types (checkbox, radio, date, tel, color) will show console errors
+- Use appropriate specialized components for specific input types
+- Size affects padding: `md` uses `p-3`, `sm` uses `p-2`
+- Base CSS class: `aw-text-field` (from config)
+- Wrapper is a `<label>` element for better accessibility
+- Input element uses `mergedAttributes` (combines type, skipAttr, $attrs, and id)
+- All standard HTML input attributes supported via `$attrs` (inheritAttrs enabled)
+- All standard input events supported via `mergedListeners`

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

@@ -0,0 +1,136 @@
+---
+metaTitle: Label component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwLabel /> component is used to render Label - UI Vue component for AwesCode UI.
+title: Label
+---
+
+# Label
+
+**Category:** Atom | **Import:** Global
+
+The `AwLabel` component displays a styled label with optional icons and customizable colors.
+
+## Overview
+
+`AwLabel` provides a badge-like label component that can display text with optional leading and trailing icons. It supports custom colors and is commonly used for tags, categories, and status indicators.
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwLabel label="New" />
+```
+
+### With Icons
+
+```markup
+<AwLabel label="Featured" icon="awesio/star" />
+<AwLabel label="Verified" icon="awesio/check" icon-second="awesio/close" />
+```
+
+### With Colors
+
+```markup
+<AwLabel label="Success" color="success" />
+<AwLabel label="Warning" color="warning" />
+```
+
+### Boolean Icon
+
+```markup
+<AwLabel label="Active" :icon="true" />
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| label | Label text | `String` | `true` | - |
+| color | Background color - see [Built-in Colors](/reference/colors) | `String` | `false` | `''` |
+| onColor | Text/icon color - see [Built-in Colors](/reference/colors) | `String` | `false` | `''` |
+| icon | Leading icon (boolean for default, string for custom) - see [Built-in Icons](/reference/icons) | `Boolean` / `String` | `false` | `null` |
+| iconSecond | Trailing icon name - see [Built-in Icons](/reference/icons) | `String` | `false` | `null` |
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Custom label content (replaces label prop) | - | Label text |
+
+### Events
+
+No events are emitted by this component.
+
+## Component Behavior
+
+### Icon Handling
+- **Boolean icon:** When `icon` is `true`, displays `awesio/circle` icon
+- **String icon:** When `icon` is a string, displays that icon name
+- **Null/false icon:** When `icon` is `null` or `false`, no icon displayed
+- Icons are automatically rendered using `AwIcon` component with size 16
+- Icons have `aria-hidden="true"` for accessibility
+
+### Icon Type Detection
+- Component checks if icon exists in mono icon set
+- System icons (mono) are detected automatically
+- Non-system icons handled via AwIcon component
+
+### Color System
+- **Default colors (no color/onColor specified):**
+  - Background: `var(--c-mono-900)`
+  - Text/icon: `var(--c-mono-400)`
+- **With color prop:**
+  - Background: Uses `toColor(color)` utility
+  - Text/icon: Auto-calculated using `toOnColor(color)` for contrast
+- **With onColor prop:**
+  - Overrides automatic text/icon color
+  - Uses `toColor(onColor)` utility
+
+### Available Colors
+- **Semantic colors:** `success`, `warning`, `error`, `info`, `accent`, `notify`
+- **Mono scale:** `mono-0` through `mono-900` (in increments of 50/100)
+- **Named colors:** `red`, `peach`, `yellow`, `magenta`, `purple`, `light-blue`, `blue`, `green`, `lime`, `grey`, `light-grey`, `black`, `forest`, `brown`
+- All colors automatically get proper contrast text/icon colors via `toOnColor` utility
+
+### Style Variables
+Component uses CSS custom properties:
+- `--aw-label-bg` - Background color
+- `--aw-label-on-color` - Text and icon color
+
+### Rendering
+- Component only renders if `label` prop is provided
+- Default slot replaces label text but label prop is still required
+- Icons positioned via flexbox: leading icon → text → trailing icon
+
+### Structure
+```
+<div class="aw-label" :style="{ --aw-label-bg, --aw-label-on-color }">
+  <AwIcon v-if="_icon" :name="_icon" size="16" />
+  <slot>{{ label }}</slot>
+  <AwIcon v-if="iconSecond" :name="iconSecond" size="16" />
+</div>
+```
+
+## Related Components
+
+- `AwTag` - Tag component
+- `AwBadge` - Badge component
+- `AwIcon` - Icon component
+
+## Notes
+
+- **Import Method:** Global - Available as atom component
+- When `icon` is `true`, displays default circle icon (`awesio/circle`)
+- When `icon` is a string, displays that icon
+- System icons are automatically detected from mono icon set
+- Default colors are mono-900 background with mono-400 text if no colors specified
+- Use `onColor` to override text color when using custom background color
+- Label prop is required even when using default slot
+- Icons are always size 16 and have aria-hidden attribute
+- Color utilities (`toColor`, `toOnColor`) handle color name to CSS variable conversion
+