@awes-io/ui 2.143.0 → 2.144.0

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

@@ -33,7 +33,7 @@ The `AwIsland` component is an enhanced card component that displays content wit
   title="Feature Title"
   description="This is a description of the feature"
   icon="awesio/settings"
-  icon-color="accent-500"
+  icon-color="accent"
 >
   <p>Content goes here</p>
 </AwIsland>
@@ -86,6 +86,7 @@ The `AwIsland` component is an enhanced card component that displays content wit
   title="With Actions"
   description="Section with action buttons"
   icon="awesio/settings"
+  expanded
 >
   <template #options>
     <AwButton size="sm" icon="awesio/edit" theme="icon" />
@@ -96,8 +97,14 @@ The `AwIsland` component is an enhanced card component that displays content wit
 </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>
@@ -108,13 +115,38 @@ The `AwIsland` component is an enhanced card component that displays content wit
 </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="box"
+  icon="awesio/check"
 >
   <p>Main content</p>
 
@@ -131,17 +163,26 @@ The `AwIsland` component is an enhanced card component that displays content wit
 | Name | Description | Type | Required | Default |
 |------|-------------|------|----------|---------|
 | title | Island title | `String` | `false` | `''` |
-| titleTag | HTML tag for title | `String` | `false` | `'div'` |
+| titleTag | HTML tag for title | `String` | `false` | `'h2'` |
 | description | Description text below title | `String` | `false` | `''` |
-| icon | Icon name | `String` | `false` | `''` |
-| iconColor | Icon color (CSS custom property) | `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` | `'div'` |
+| 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 |
@@ -184,6 +225,28 @@ When `expanded` prop is true:
 - 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"`:
@@ -191,6 +254,207 @@ When `tag="AwLink"`:
 - 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:
@@ -198,27 +462,30 @@ Use CSS custom property names for icon colors:
 ```markup
 <AwIsland
   icon="awesio/info-circle"
-  icon-color="accent-500"
+  icon-color="accent"
 />
 
 <AwIsland
   icon="awesio/warning"
-  icon-color="error-500"
+  icon-color="error"
 />
 
 <AwIsland
-  icon="success"
-  icon-color="success-500"
+  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
 
@@ -230,5 +497,10 @@ Use CSS custom property names for icon colors:
 - 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/organisms/aw-filter-select.md

@@ -40,6 +40,20 @@ The `AwFilterSelect` component is a dropdown filter that syncs with URL query pa
 />
 ```
 
+**Note:** When using boolean values in filter options, they must be represented as strings:
+
+```markup
+<AwFilterSelect
+    param="is_active"
+    label="Status"
+    :options="[
+        { id: 'true', title: 'Active' },
+        { id: 'false', title: 'Inactive' }
+    ]"
+    single
+/>
+```
+
 ### Multiple Selection
 
 ```markup

package/docs/components/pages/aw-page-single.md

@@ -77,6 +77,53 @@ export default {
 </AwPageSingle>
 ```
 
+### Preview Slot Patterns
+
+We have two standard patterns for the `#preview` slot depending on the entity type:
+
+#### Human Pattern (Users, Customers)
+
+Used for people. Displays a large avatar and the person's name.
+
+```markup
+<template #preview>
+    <AwCard class="text-center">
+        <AwAvatar
+            :src="user.avatar"
+            :name="userName"
+            size="240"
+            class="mx-auto"
+        />
+        <AwHeadline class="mt-4">
+            {{ userName }}
+        </AwHeadline>
+    </AwCard>
+</template>
+```
+
+#### Item Pattern (Services, Products, Locations)
+
+Used for non-human entities with an image. Displays a large image with rounded corners.
+
+```markup
+<template #preview>
+    <AwCard style="--card-padding-x: 0.5rem; --card-padding-y: 0.5rem;">
+        <AwActionIcon
+            :size="380"
+            :image="item.image ? { src: item.image, alt: item.name } : null"
+            icon="awesio/image"
+            icon-color="mono-400"
+            color="mono-800"
+            class="w-full"
+            style="--icon-size: 48px; --radius: 0.5rem;"
+        />
+        <AwHeadline class="p-4 mt-2">
+            {{ item.name }}
+        </AwHeadline>
+    </AwCard>
+</template>
+```
+
 ### With Action Button
 
 ```markup