@awes-io/ui 2.142.0 → 2.143.0

package/docs/components/organisms/aw-chip-select.md

@@ -0,0 +1,164 @@
+---
+metaTitle: ChipSelect component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwChipSelect /> component is used to render ChipSelect - UI Vue component for AwesCode UI.
+title: ChipSelect
+---
+
+# AwChipSelect
+
+**Category:** Organism | **Import:** Dynamic
+
+The `AwChipSelect` component is a select dropdown that displays the selected value as a chip and shows options in a dropdown menu. It's designed for selecting from a list of chip-style options.
+
+## Overview
+
+`AwChipSelect` provides a chip-based select solution with:
+- Chip display for selected value
+- Dropdown menu with chip options
+- Loading state support
+- Readonly/disabled states
+- Keyboard navigation
+- Custom option rendering
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwChipSelect 
+    v-model="selected"
+    :options="[
+        { id: 1, text: 'Option 1', color: 'success' },
+        { id: 2, text: 'Option 2', color: 'error' },
+        { id: 3, text: 'Option 3', color: 'accent' }
+    ]"
+/>
+```
+
+### With Loading State
+
+```markup
+<AwChipSelect 
+    v-model="selected"
+    :options="options"
+    :loading="isLoading"
+/>
+```
+
+### Readonly Mode
+
+```markup
+<AwChipSelect 
+    v-model="selected"
+    :options="options"
+    readonly
+/>
+```
+
+### Without Text (Icon Only)
+
+```markup
+<AwChipSelect 
+    v-model="selected"
+    :options="options"
+    no-text
+/>
+```
+
+### Filled Style
+
+```markup
+<AwChipSelect 
+    v-model="selected"
+    :options="options"
+    filled
+/>
+```
+
+### Custom Selected Display
+
+```markup
+<AwChipSelect v-model="selected" :options="options">
+    <template #selected="{ selected }">
+        <AwChip :text="selected.text" :color="selected.color">
+            <template #right>
+                <AwBadge :text="selected.count" />
+            </template>
+        </AwChip>
+    </template>
+</AwChipSelect>
+```
+
+### Custom Option Display
+
+```markup
+<AwChipSelect v-model="selected" :options="options">
+    <template #option="{ id, text, color, select }">
+        <AwChip :text="text" :color="color" @click="select(id)">
+            Custom option
+        </AwChip>
+    </template>
+</AwChipSelect>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| value | Selected option ID | `Number` / `String` | `false` | `null` |
+| options | Array of option objects | `Array` | `true` | - |
+| readonly | Prevent selection changes | `Boolean` | `false` | `false` |
+| disabled | Disable the component | `Boolean` | `false` | `false` |
+| loading | Show loading spinner | `Boolean` | `false` | `false` |
+| noText | Hide text in selected chip | `Boolean` | `false` | `false` |
+| filled | Use filled chip style | `Boolean` | `false` | `false` |
+
+**Option Object Format:**
+```javascript
+{
+  id: 1,              // Required: unique identifier
+  text: 'Option 1',   // Optional: display text
+  color: 'success',   // Optional: chip color
+  icon: 'awesio/check',     // Optional: icon name
+  // ... other chip props
+}
+```
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| selected | Custom selected chip display | `{ selected }` | Default chip with selected option |
+| option | Custom option chip display | `{ id, text, ...props, index, select }` | Default chip with option data |
+
+### Events
+
+| Name | Payload | Description |
+|------|---------|-------------|
+| input | `Number` / `String` | Emitted when option is selected (option ID) |
+
+### Mixins
+
+- `arrowFocusMixin` - Provides keyboard navigation support
+
+## Related Components
+
+- `AwChip` - Chip component used for display
+- `AwDropdown` - Dropdown component for menu
+- `AwDropdownButton` - Dropdown button component
+
+## Notes
+
+- **Import Method:** Dynamic - Component is loaded on-demand as an organism
+- Options array must contain objects with `id` property
+- Selected option is found by matching `id` with `value`
+- When `noText` is true, text is omitted from selected chip
+- Loading state shows spinner in chip
+- Dropdown closes when component is disabled/readonly
+- Keyboard navigation: Arrow keys to navigate, Enter to select
+- Component uses `AwDropdown` with custom positioning
+- All chip props can be passed in option objects

package/docs/components/organisms/aw-chip.md

@@ -0,0 +1,126 @@
+---
+metaTitle: Chip component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwChip /> component is used to render Chip - UI Vue component for AwesCode UI.
+title: Chip
+---
+
+# AwChip
+
+**Category:** Organism | **Import:** Dynamic
+
+The `AwChip` component is a small, compact element used to display labels, tags, or status indicators. It supports icons, images, colors, and custom content slots.
+
+## Overview
+
+`AwChip` provides a flexible chip/tag component with:
+- Icon or image decoration
+- Color customization
+- Filled or outlined styles
+- Loading/rotation animation support
+- Custom slot support for flexible content
+- Functional component for optimal performance
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwChip text="Label" />
+```
+
+### With Icon
+
+```markup
+<AwChip text="Active" icon="awesio/check" color="success" />
+```
+
+### With Image
+
+```markup
+<AwChip text="User" image="/path/to/avatar.jpg" />
+```
+
+### Filled Style
+
+```markup
+<AwChip text="Tag" color="accent" filled />
+```
+
+### With Loading Animation
+
+```markup
+<AwChip text="Processing" icon="progress" :rotate="true" />
+```
+
+### Custom Content
+
+```markup
+<AwChip>
+    <template #left>
+        <AwIcon name="star" />
+    </template>
+    Custom content
+    <template #right>
+        <AwButton theme="icon" @click="remove">×</AwButton>
+    </template>
+</AwChip>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| text | Text label | `String` | `false` | `''` |
+| icon | Icon name to render in decor element | `String` | `false` | `''` |
+| color | Border, icon and close icon color | `String` | `false` | `''` |
+| image | Decor element background image URL | `String` | `false` | `''` |
+| filled | Indicates if chip has filled background | `Boolean` | `false` | `false` |
+| rotate | Toggles rotate animation (for loading icons) | `Boolean` | `false` | `false` |
+
+**Color Options:** Any valid color class (e.g., `'success'`, `'error'`, `'accent'`, `'mono'`)
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Text content | - | Text prop value |
+| left | Content on the left side of text | - | Decor element (icon/image) |
+| center | Text wrapper | - | Text span |
+| right | Content on the right side of text | - | - |
+
+### Events
+
+This component does not emit any events (functional component).
+
+### Config Options
+
+The component has internal config for icon rotation:
+
+```javascript
+{
+  progress: {
+    rotate: true  // Auto-rotate progress icons
+  }
+}
+```
+
+## Related Components
+
+- `AwIcon` - Icon component used in chip decor
+- `AwIconSystemMono` - System icon component
+- `AwBadge` - Badge component (similar use case)
+
+## Notes
+
+- **Import Method:** Dynamic - Component is loaded on-demand as an organism
+- Component is functional (stateless) for optimal performance
+- Icons are automatically detected as system icons (mono) or regular icons
+- When `image` is provided, it's used as background image for decor element
+- `filled` prop changes background color instead of border color
+- Rotation animation is useful for loading states (e.g., progress spinner)
+- Default slot content replaces `text` prop if provided
+- Color classes follow Tailwind CSS naming convention

package/docs/components/organisms/aw-code-snippet.md

@@ -0,0 +1,94 @@
+---
+metaTitle: Code Snippet component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwCodeSnippet /> component is used to render Code Snippet - UI Vue component for AwesCode UI.
+title: Code Snippet
+---
+
+# AwCodeSnippet
+
+**Category:** Organism | **Import:** Dynamic
+
+The `AwCodeSnippet` component displays syntax-highlighted code with a copy-to-clipboard button. It uses Prism.js for syntax highlighting and supports multiple programming languages.
+
+## Overview
+
+`AwCodeSnippet` provides a code display solution with:
+- Syntax highlighting via Prism.js
+- Copy-to-clipboard functionality
+- Multiple language support
+- Scrollable code blocks
+- Functional component for optimal performance
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwCodeSnippet code="const x = 1;" language="javascript" />
+```
+
+### Vue Template
+
+```markup
+<AwCodeSnippet 
+    :code="vueCode"
+    language="markup"
+/>
+```
+
+### JavaScript
+
+```markup
+<AwCodeSnippet 
+    code="function hello() { console.log('Hello'); }"
+    language="javascript"
+/>
+```
+
+### CSS
+
+```markup
+<AwCodeSnippet 
+    code=".class { color: red; }"
+    language="css"
+/>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| code | Code content to display | `String` | `false` | `''` |
+| language | Programming language for syntax highlighting | `String` | `false` | `'markup'` |
+
+**Supported Languages:**
+All Prism.js supported languages (markup, css, javascript, json, python, php, etc.)
+
+### Slots
+
+This component does not have slots (functional component).
+
+### Events
+
+This component does not emit events (functional component).
+
+## Related Components
+
+- `AwCode` - Code input component (different use case)
+- `AwButton` - Button component used for copy button
+
+## Notes
+
+- **Import Method:** Dynamic - Component is loaded on-demand as an organism
+- Component is functional (stateless) for optimal performance
+- Uses Prism.js for syntax highlighting
+- Copy button uses `clipboard-copy` library
+- Code is wrapped in `<pre><code>` elements
+- Language class is applied to code element (`language-{language}`)
+- Copy button is positioned absolutely in top-right corner
+- Component handles Prism.js errors gracefully
+- Code block is scrollable when content overflows

package/docs/components/organisms/aw-code.md

@@ -0,0 +1,132 @@
+---
+metaTitle: Code component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwCode /> component is used to render Code - UI Vue component for AwesCode UI.
+title: Code
+---
+
+# AwCode
+
+**Category:** Organism | **Import:** Dynamic
+
+The `AwCode` component is a multi-field code input component designed for entering verification codes, PINs, or other structured numeric codes. It displays multiple input fields based on a pattern and handles automatic focus management.
+
+## Overview
+
+`AwCode` provides a code input solution with:
+- Pattern-based field layout (e.g., `'XXXX-XX'`)
+- Automatic focus navigation between fields
+- Paste support for complete codes
+- Error handling and validation
+- Compact mode for smaller displays
+- Numeric input only
+- Auto-advance on input
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwCode pattern="XXXXXX" v-model="code" />
+```
+
+### With Separator
+
+```markup
+<AwCode pattern="XXXX-XX" v-model="code" />
+```
+
+### Compact Mode
+
+```markup
+<AwCode pattern="XXXXXX" v-model="code" compact />
+```
+
+### With Error
+
+```markup
+<AwCode 
+    pattern="XXXXXX" 
+    v-model="code"
+    :error="codeError"
+/>
+```
+
+### With Validation
+
+```markup
+<AwCode 
+    pattern="XXXXXX" 
+    v-model="code"
+    @change="validateCode"
+/>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| pattern | Pattern string (X = input field, - = separator) | `String` | `false` | `'XXXXXX'` |
+| compact | Enable compact mode (smaller fields) | `Boolean` | `false` | `true` |
+| className | Custom CSS class | `String` | `false` | `'aw-text-field'` |
+| value | Input value (v-model) | `String` | `false` | `''` |
+| disabled | Disable all fields | `Boolean` | `false` | `false` |
+| error | Error message to display | `String` | `false` | `''` |
+
+**Pattern Format:**
+- `X` = Input field (numeric)
+- `-` = Separator (displayed as dash, not input)
+- Example: `'XXXX-XX'` creates 4 fields, dash, 2 fields
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| error | Custom error display | - | Default error tooltip |
+
+### Events
+
+| Name | Payload | Description |
+|------|---------|-------------|
+| input | `String` | Emitted on each field input (clean value without separators) |
+| change | `String` | Emitted when all fields are filled (complete code) |
+| focus | `Event` | Emitted when component receives focus |
+| invalid | `Event` | Emitted on validation error |
+
+### Config Options
+
+The component uses default configuration from `@AwConfig`. You can override these defaults in your project's `awes.config.js`:
+
+```javascript
+export default {
+  AwCode: {
+    baseClass: 'aw-text-field',
+    pattern: 'XXXXXX',
+    compact: true
+  }
+}
+```
+
+## Related Components
+
+- `AwInput` - Single input field component
+- `AwPassword` - Password input component
+
+## Notes
+
+- **Import Method:** Dynamic - Component is loaded on-demand as an organism
+- Only numeric input is accepted (digits 0-9)
+- Separators (`-`) in pattern are displayed but not included in value
+- Automatic focus moves to next field when current field is filled
+- Paste support: paste complete code to fill all fields at once
+- Backspace moves focus to previous field
+- Arrow keys navigate between fields
+- Error is displayed as tooltip on hover
+- Uses `inputmode="numeric"` for mobile keyboard optimization
+- Value is always clean (no separators) - pattern is only for display
+- Component emits `change` only when all fields are complete
+- Uses field mixin for standard field behavior
+- Uses error mixin for error handling

package/docs/components/organisms/aw-context-menu.md

@@ -0,0 +1,117 @@
+---
+metaTitle: ContextMenu component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwContextMenu /> component is used to render ContextMenu - UI Vue component for AwesCode UI.
+title: ContextMenu
+---
+
+# AwContextMenu
+
+**Category:** Organism | **Import:** Dynamic
+
+The `AwContextMenu` component is a context menu that displays a dropdown list of menu items. It's built on top of `AwDropdown` and `AwButton`, providing a button trigger with a menu list.
+
+## Overview
+
+`AwContextMenu` provides a context menu solution with:
+- Button trigger with optional text/icon
+- Dropdown menu with list items
+- Keyboard navigation support
+- Popper.js positioning
+- Customizable button appearance
+- Vertical menu layout
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwContextMenu text="Menu">
+    <AwButton>Item 1</AwButton>
+    <AwButton>Item 2</AwButton>
+    <AwButton>Item 3</AwButton>
+</AwContextMenu>
+```
+
+### Icon Only
+
+```markup
+<AwContextMenu hide-text icon="awesio/more">
+    <AwButton>Item 1</AwButton>
+    <AwButton>Item 2</AwButton>
+</AwContextMenu>
+```
+
+### With Custom Button
+
+```markup
+<AwContextMenu 
+    text="Options"
+    color="accent"
+    button-class="custom-class"
+>
+    <AwButton>Edit</AwButton>
+    <AwButton>Delete</AwButton>
+</AwContextMenu>
+```
+
+### With Popper Options
+
+```markup
+<AwContextMenu 
+    text="Menu"
+    :options="{ placement: 'bottom-end' }"
+>
+    <AwButton>Item 1</AwButton>
+    <AwButton>Item 2</AwButton>
+</AwContextMenu>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| text | Button text label | `String` | `false` | `''` |
+| hideText | Hide button text (show icon only) | `Boolean` | `false` | `null` (auto) |
+| color | Button color | `String` | `false` | `'mono'` |
+| buttonClass | Additional CSS class for button | `String` | `false` | `''` |
+| vertical | Vertical menu layout | `Boolean` | `false` | `false` |
+| options | Popper.js options object | `Object` | `false` | `{}` |
+
+**Popper.js Options:**
+See [Popper.js documentation](https://popper.js.org/docs/v2/) for all available options.
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Menu items (should be button/link components) | - | - |
+| icon | Custom button icon | - | Default icon |
+
+### Events
+
+This component does not emit custom events (uses internal state).
+
+### Mixins
+
+- `arrowFocusMixin` - Provides keyboard navigation support
+
+## Related Components
+
+- `AwDropdown` - Dropdown component used internally
+- `AwButton` - Button component used for trigger and items
+
+## Notes
+
+- **Import Method:** Dynamic - Component is loaded on-demand as an organism
+- Menu items should be button or link components
+- Items automatically get `data-arrow-focus` attribute for keyboard navigation
+- Button text is automatically hidden if `text` is empty and `hideText` is null
+- Uses Popper.js for positioning (see Popper.js docs for options)
+- Component is render-based (uses `render` function)
+- Menu items are wrapped in `<li>` elements with `aw-cm-item` class
+- Dropdown state is managed internally
+- Keyboard navigation: Arrow keys to navigate, Enter to activate