@awes-io/ui 2.142.3 → 2.144.0

package/docs/components/molecules/aw-island.md

@@ -0,0 +1,506 @@
+---
+metaTitle: Island component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwIsland /> component provides a card-based container with icon, title, description, and collapsible content - UI Vue component for AwesCode UI.
+title: Island
+---
+
+# AwIsland
+
+**Category:** Molecule | **Import:** Global
+
+The `AwIsland` component is an enhanced card component that displays content with an icon, title, description, and optional collapsible content section. It's designed for feature showcases, settings panels, and informational blocks.
+
+## Overview
+
+`AwIsland` provides an island-style card with:
+- Icon with customizable color
+- Title and description
+- Collapsible/expandable content
+- Options slot for action buttons
+- Footer section
+- Custom arrow icon
+- Can be used as a link
+- Responsive design
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwIsland
+  title="Feature Title"
+  description="This is a description of the feature"
+  icon="awesio/settings"
+  icon-color="accent"
+>
+  <p>Content goes here</p>
+</AwIsland>
+```
+
+### Collapsible Content
+
+```markup
+<AwIsland
+  title="Collapsible Section"
+  description="Click to expand"
+  icon="awesio/info-circle"
+>
+  <div>
+    <p>This content can be collapsed and expanded.</p>
+    <p>Add any content here.</p>
+  </div>
+</AwIsland>
+```
+
+### Always Expanded
+
+```markup
+<AwIsland
+  title="Always Open"
+  description="This section is always visible"
+  icon="awesio/check"
+  expanded
+>
+  <p>Content is always visible.</p>
+</AwIsland>
+```
+
+### As Link
+
+```markup
+<AwIsland
+  title="Clickable Island"
+  description="Click anywhere to navigate"
+  icon="awesio/arrow-r"
+  tag="AwLink"
+  href="/settings"
+/>
+```
+
+### With Options
+
+```markup
+<AwIsland
+  title="With Actions"
+  description="Section with action buttons"
+  icon="awesio/settings"
+  expanded
+>
+  <template #options>
+    <AwButton size="sm" icon="awesio/edit" theme="icon" />
+    <AwButton size="sm" icon="awesio/delete" theme="icon" />
+  </template>
+
+  <p>Content with actions</p>
+</AwIsland>
+```
+
+**Note:** The options slot is usually used with the `expanded` prop to keep the content visible while providing action buttons.
+
+### With Custom Icon
+
+You can use the `icon` slot to replace the default icon with custom content, such as images or avatar components.
+
+**Using Custom Image:**
+
+```markup
+<AwIsland title="Custom Icon" description="Using slot for custom icon">
+  <template #icon>
+    <img src="/custom-icon.svg" class="w-6 h-6" />
+  </template>
+
+  <p>Content</p>
+</AwIsland>
+```
+
+**Using AwAvatar Component:**
+
+```markup
+<AwIsland
+  title="Personal Information"
+  description="Your personal details"
+  :model="personalModel"
+>
+  <template #icon>
+    <AwAvatar
+      :src="personalModel.$.avatar"
+      :name="personalModel.$.name"
+      :size="42"
+    />
+  </template>
+
+  <AwGrid>
+    <AwInput v-model="personalModel.name" label="Name" />
+    <AwInput v-model="personalModel.email" label="Email" />
+  </AwGrid>
+</AwIsland>
+```
+
+This pattern is commonly used for user profile sections where an avatar provides better visual representation than an icon.
+
+### With Footer
+
+```markup
+<AwIsland
+  title="With Footer"
+  description="Island with footer section"
+  icon="awesio/check"
+>
+  <p>Main content</p>
+
+  <template #footer>
+    <AwButton>Save Changes</AwButton>
+  </template>
+</AwIsland>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| title | Island title | `String` | `false` | `''` |
+| titleTag | HTML tag for title | `String` | `false` | `'h2'` |
+| description | Description text below title | `String` | `false` | `''` |
+| icon | Icon name - see [Built-in Icons](/reference/icons) | `String` | `false` | `''` |
+| iconColor | Icon color (CSS custom property name) | `String` | `false` | `'mono-400'` |
+| expanded | Always show content (not collapsible) | `Boolean` | `false` | `false` |
+| show | Initial collapsed state | `Boolean` | `false` | `false` |
+| showArrow | Force show arrow icon | `Boolean` | `false` | `false` |
+| tag | Root element tag (use 'AwLink' for links) | `String` | `false` | `'section'` |
+| model | vue-mc Model instance for save/reset functionality | `Object` | `false` | `null` |
+| disabled | Disable island interactions | `Boolean` | `false` | `false` |
+
+All AwCard props are also supported (inherited).
+
+**Model Object Requirements:**
+
+When providing a `model` prop, the object must implement:
+- `changed()` - Method that returns `true` if model has unsaved changes
+- `save()` - Method that returns a Promise to save changes
+- `reset()` - Method to reset changes to original values
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Main content | `{ isOpened, toggle }` | - |
+| icon | Custom icon | - | AwIcon with icon prop |
+| title | Custom title | `{ titleTag, isOpened, toggle }` | Title text |
+| after-title | Content after title | - | - |
+| description | Custom description | `{ isOpened, toggle }` | AwDescription with description prop |
+| options | Action buttons before arrow | `{ isOpened, toggle }` | - |
+| arrow | Custom arrow icon | `{ isOpened, toggle }` | AwIconSystemMono angle |
+| separator | Content between header and body | `{ isOpened, toggle }` | - |
+| footer | Footer section | `{ isOpened, toggle }` | - |
+
+### Events
+
+Inherits all events from AwCard.
+
+### Methods
+
+| Name | Parameters | Description |
+|------|------------|-------------|
+| toggle | - | Toggle collapsed/expanded state |
+
+## Behavior
+
+### Collapsible Mode (default)
+
+When content slot is present and `expanded` is false:
+- Arrow icon shows collapse/expand state
+- Click header to toggle content
+- Content animated with AwAccordionFold
+- isOpened state tracked internally
+
+### Expanded Mode
+
+When `expanded` prop is true:
+- Content always visible
+- No collapse animation
+- Arrow icon rotates 180° (pointing down)
+- Header not clickable for toggle
+
+**Common Pattern with Options Slot:**
+
+The `expanded` prop is commonly used together with the `options` slot to create always-visible panels with action buttons:
+
+```markup
+<AwIsland
+  title="User Settings"
+  description="Manage your preferences"
+  icon="awesio/settings"
+  expanded
+>
+  <template #options>
+    <AwButton size="sm" icon="awesio/edit" theme="icon" />
+    <AwButton size="sm" icon="awesio/delete" theme="icon" />
+  </template>
+
+  <p>Settings content here</p>
+</AwIsland>
+```
+
+This pattern ensures the content remains visible while users interact with the action buttons, avoiding the need to expand/collapse to access both content and actions.
+
+### Link Mode
+
+When `tag="AwLink"`:
+- Entire island becomes clickable link
+- Inherits all AwLink props (href, to, etc.)
+- Card reset styling applied
+
+## Model Integration
+
+### Using with vue-mc Models
+
+`AwIsland` integrates with vue-mc models to provide automatic save/reset functionality in the footer. When a model is provided and has unsaved changes, the footer automatically displays Save and Reset buttons.
+
+```javascript
+import { BaseModel } from '@awes-io/vue-mc'
+
+class SettingsModel extends BaseModel {
+    defaults() {
+        return {
+            notifications: true,
+            darkMode: false
+        }
+    }
+
+    routes() {
+        return {
+            save: '/api/settings'
+        }
+    }
+}
+
+export default {
+    data() {
+        return {
+            settingsModel: new SettingsModel()
+        }
+    }
+}
+```
+
+```markup
+<AwIsland
+  title="Settings"
+  description="Configure your preferences"
+  icon="awesio/settings"
+  :model="settingsModel"
+>
+  <AwGrid>
+    <AwCheckbox v-model="settingsModel.notifications" label="Enable notifications" />
+    <AwCheckbox v-model="settingsModel.darkMode" label="Dark mode" />
+  </AwGrid>
+</AwIsland>
+```
+
+**Automatic Behavior:**
+
+- **No Changes**: Footer shows only "Close" button
+- **Has Changes**: Footer shows "Reset" and "Save" buttons
+- **Saving**: Save button disabled during save operation
+- **Success**: Shows success notification and closes island
+- **Error**: Shows error notification and keeps island open
+
+### Custom Footer with Model
+
+You can override the default footer buttons while still using model integration:
+
+```markup
+<AwIsland
+  title="Settings"
+  :model="settingsModel"
+>
+  <AwCheckbox v-model="settingsModel.notifications" label="Notifications" />
+
+  <template #buttons>
+    <AwButton
+      v-if="settingsModel.changed()"
+      @click="settingsModel.reset()"
+      color="mono"
+    >
+      Cancel
+    </AwButton>
+    <AwButton
+      v-if="settingsModel.changed()"
+      @click="customSave"
+      :disabled="settingsModel.saving"
+    >
+      Apply Changes
+    </AwButton>
+  </template>
+</AwIsland>
+```
+
+## AwIslandBuilder
+
+### Overview
+
+`AwIslandBuilder` is a wrapper component that manages multiple `AwIsland` components with accordion behavior. Only one island can be open at a time, and it provides unsaved changes protection when switching between islands.
+
+### Basic Usage
+
+```markup
+<AwIslandBuilder>
+  <AwIsland
+    title="Personal Information"
+    description="Your personal details"
+    icon="awesio/user"
+    :model="personalModel"
+  >
+    <AwInput v-model="personalModel.name" label="Name" />
+    <AwInput v-model="personalModel.email" label="Email" />
+  </AwIsland>
+
+  <AwIsland
+    title="Account Settings"
+    description="Manage your preferences"
+    icon="awesio/settings"
+    :model="accountModel"
+  >
+    <AwCheckbox v-model="accountModel.notifications" label="Email notifications" />
+    <AwCheckbox v-model="accountModel.twoFactor" label="Two-factor authentication" />
+  </AwIsland>
+
+  <AwIsland
+    title="Privacy"
+    description="Control your privacy"
+    icon="awesio/lock"
+    :model="privacyModel"
+  >
+    <AwCheckbox v-model="privacyModel.publicProfile" label="Public profile" />
+    <AwCheckbox v-model="privacyModel.showEmail" label="Show email" />
+  </AwIsland>
+</AwIslandBuilder>
+```
+
+### AwIslandBuilder Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| confirmText | Confirmation message for unsaved changes | `String` | `false` | `'There is unsaved data...'` |
+
+All `AwGrid` props are also supported (inherited).
+
+### Accordion Behavior
+
+**Single Open Island:**
+- Only one island can be expanded at a time
+- Clicking an island header collapses the currently open island
+- Click the same header again to collapse it
+
+**Unsaved Changes Protection:**
+
+When switching islands with unsaved changes:
+1. Confirmation dialog appears
+2. User can confirm (discards changes) or cancel (stays on current island)
+3. If confirmed, model is reset and new island opens
+
+**Route Navigation Protection:**
+
+Automatically prevents navigation with unsaved changes:
+- Intercepts router navigation
+- Shows confirmation dialog
+- Resets model if user confirms
+- Cancels navigation if user declines
+
+**Window Close Protection:**
+
+Prevents accidental window close with unsaved changes:
+- Browser shows native "Leave site?" dialog
+- Uses `confirmText` prop as message (where supported)
+
+### Use Cases
+
+**Settings Pages:**
+Perfect for grouped settings with separate save contexts:
+
+```markup
+<AwIslandBuilder>
+  <AwIsland title="Profile" :model="profileModel">...</AwIsland>
+  <AwIsland title="Security" :model="securityModel">...</AwIsland>
+  <AwIsland title="Notifications" :model="notificationsModel">...</AwIsland>
+</AwIslandBuilder>
+```
+
+**Wizard Steps:**
+Multi-step forms with independent save operations:
+
+```markup
+<AwIslandBuilder>
+  <AwIsland title="Step 1: Basic Info" :model="step1Model">...</AwIsland>
+  <AwIsland title="Step 2: Details" :model="step2Model">...</AwIsland>
+  <AwIsland title="Step 3: Review" :model="step3Model">...</AwIsland>
+</AwIslandBuilder>
+```
+
+**Expandable Sections:**
+Read-only information sections (without models):
+
+```markup
+<AwIslandBuilder>
+  <AwIsland title="Documentation">
+    <p>Documentation content...</p>
+  </AwIsland>
+  <AwIsland title="Examples">
+    <p>Example code...</p>
+  </AwIsland>
+</AwIslandBuilder>
+```
+
+## Icon Colors
+
+Use CSS custom property names for icon colors:
+
+```markup
+<AwIsland
+  icon="awesio/info-circle"
+  icon-color="accent"
+/>
+
+<AwIsland
+  icon="awesio/warning"
+  icon-color="error"
+/>
+
+<AwIsland
+  icon="awesio/check"
+  icon-color="success"
+/>
+```
+
+## Related Components
+
+- `AwIslandBuilder` - Accordion wrapper for multiple islands
+- `AwCard` - Base card component
+- `AwAccordionFold` - Collapse animation (used internally)
+- `AwIcon` - Icon component
+- `AwIconSystemMono` - System icons
+- `AwAvatar` - Avatar component (can be used in icon slot)
+- `AwIslandAvatar` - Island variant with avatar
+- [vue-mc Models](/vue-mc/models) - Model integration documentation
+
+## Notes
+
+- **Import Method:** Global - Available as molecule component
+- Extends AwCard component
+- Uses AwAccordionFold for collapse animation
+- Arrow icon automatically appears when content slot is used
+- Click anywhere in header to toggle (when collapsible)
+- Icon color uses CSS custom properties (--c-{color})
+- Content toggle only works when `expanded` is false
+- Title slot provides titleTag for custom heading levels
+- Icon slot can be used with AwAvatar for user profile sections
+- Options slot appears before arrow icon
+- Footer only visible when footer slot is used
+- Model prop enables automatic save/reset functionality
+- Works seamlessly with vue-mc BaseModel instances
+- AwIslandBuilder provides accordion behavior for multiple islands
+- Builder automatically handles unsaved changes protection

package/docs/components/molecules/aw-number.md

@@ -0,0 +1,138 @@
+---
+metaTitle: Number component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwNumber /> component is used to render Number input - UI Vue component for AwesCode UI.
+title: Number
+---
+
+# AwNumber
+
+**Category:** Molecule | **Import:** Global
+
+The `AwNumber` component is a numeric input field with increment/decrement buttons, min/max validation, and step control. It extends `AwInput` with specialized number handling.
+
+## Overview
+
+`AwNumber` provides a comprehensive number input solution with:
+- Increment/decrement buttons (can be hidden)
+- Min/max value constraints
+- Step control for value changes
+- Integer-only mode
+- Automatic value clamping on blur
+- Paste validation
+- Keyboard input filtering
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwNumber v-model="quantity" />
+```
+
+### With Min and Max
+
+```markup
+<AwNumber 
+    v-model="age" 
+    :min="0" 
+    :max="120" 
+    label="Age"
+/>
+```
+
+### With Step
+
+```markup
+<AwNumber 
+    v-model="price" 
+    :step="0.1" 
+    :min="0" 
+    label="Price"
+/>
+```
+
+### Integer Only
+
+```markup
+<AwNumber 
+    v-model="count" 
+    integer 
+    :min="0" 
+    label="Count"
+/>
+```
+
+### Without Buttons
+
+```markup
+<AwNumber 
+    v-model="value" 
+    hide-buttons 
+    label="Number"
+/>
+```
+
+### Custom Postfix Slot
+
+```markup
+<AwNumber v-model="value" label="Custom">
+    <template #postfix>
+        <span class="px-4">units</span>
+    </template>
+</AwNumber>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| value | Current numeric value | `Number` / `String` | `false` | `0` |
+| min | Minimum allowed value | `Number` / `String` | `false` | `-Infinity` |
+| max | Maximum allowed value | `Number` / `String` | `false` | `Infinity` |
+| step | Step amount for increment/decrement | `Number` / `String` | `false` | `1` |
+| integer | Restrict input to integers only | `Boolean` | `false` | `false` |
+| hideButtons | Hide increment/decrement buttons | `Boolean` | `false` | `false` |
+
+All standard `AwInput` props are also supported via `$attrs` (e.g., `label`, `placeholder`, `error`, `disabled`, etc.).
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| element | Custom input element | `{ cssClass, value, errorTooltip, mergedListeners, mergedAttributes, errorText, errorId }` | Default input element |
+| postfix | Custom postfix content (replaces buttons when provided) | - | Increment/decrement buttons |
+
+### Events
+
+| Name | Payload | Description |
+|------|---------|-------------|
+| input | `Number` | Emitted when value changes |
+
+### Methods
+
+| Name | Description |
+|------|-------------|
+| add | Increment the value by step amount |
+| subtract | Decrement the value by step amount |
+
+## Related Components
+
+- `AwInput` - Base input component used internally
+- `AwButton` - Button component used for increment/decrement controls
+
+## Notes
+
+- **Import Method:** Global - Component is globally registered
+- Value is automatically clamped to min/max range on blur
+- Paste events are validated against min/max constraints
+- Keys `-`, `+`, and `e` are prevented to avoid invalid number formats
+- When `integer` is true, only numeric keys are allowed
+- Input type is set to `tel` for better mobile keyboard support
+- Uses `inputmode="numeric"` for mobile numeric keyboard
+- Buttons are automatically disabled when min/max limits are reached
+- Value is converted to number internally (empty/null values become `null`)
+