@awes-io/ui 2.142.3 → 2.144.0

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

@@ -0,0 +1,296 @@
+---
+metaTitle: PageAside component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwPageAside /> component is used to render page with aside sidebar - UI Vue component for AwesCode UI.
+title: PageAside
+---
+
+# AwPageAside
+
+**Category:** Page | **Import:** Dynamic
+
+The `AwPageAside` component is a specialized page layout wrapper that adds a persistent sidebar (aside) section to the standard `AwPage` component. It provides responsive behavior with the aside appearing as a separate column on desktop and as a card on mobile.
+
+## Overview
+
+`AwPageAside` provides a page layout with aside sidebar:
+- Responsive aside positioning (sidebar on desktop, card on mobile)
+- Sticky aside buttons at the bottom
+- Pass-through support for all `AwPage` props and slots
+- Desktop/mobile breakpoint customization
+- Optional aside line separator
+- Mobile aside can be hidden
+- Bottom bar spacing awareness
+- `isDesktop` prop in all slots for responsive content
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwPageAside title="Page with Aside">
+    <template #default>
+        <p>Main content goes here</p>
+    </template>
+
+    <template #aside>
+        <AwCard title="Sidebar">
+            <p>Sidebar content</p>
+        </AwCard>
+    </template>
+</AwPageAside>
+```
+
+### With Aside Buttons
+
+```markup
+<AwPageAside title="Edit Form">
+    <template #default>
+        <AwForm url="/api/submit">
+            <!-- form fields -->
+        </AwForm>
+    </template>
+
+    <template #aside>
+        <AwCard title="Info">
+            <p>Additional information</p>
+        </AwCard>
+    </template>
+
+    <template #aside-buttons>
+        <AwButton cta>Save</AwButton>
+        <AwButton theme="outline">Cancel</AwButton>
+    </template>
+</AwPageAside>
+```
+
+### Custom Desktop Breakpoint
+
+```markup
+<AwPageAside
+    title="Responsive Page"
+    desktop-from="xl"
+>
+    <template #default>
+        <p>Main content</p>
+    </template>
+
+    <template #aside>
+        <p>Sidebar switches to desktop mode at xl breakpoint</p>
+    </template>
+</AwPageAside>
+```
+
+### With Line Separator
+
+```markup
+<AwPageAside
+    title="Page Title"
+    modifiers="line"
+>
+    <template #default>
+        <p>Main content</p>
+    </template>
+
+    <template #aside>
+        <p>Aside with vertical line separator</p>
+    </template>
+</AwPageAside>
+```
+
+### Hide Mobile Aside
+
+```markup
+<AwPageAside
+    title="Page Title"
+    hide-mobile-aside
+>
+    <template #default>
+        <p>Main content</p>
+    </template>
+
+    <template #aside>
+        <p>This aside only appears on desktop</p>
+    </template>
+</AwPageAside>
+```
+
+### Custom Mobile Aside
+
+```markup
+<AwPageAside title="Custom Mobile">
+    <template #default>
+        <p>Main content</p>
+    </template>
+
+    <template #aside="{ isDesktop }">
+        <div v-if="isDesktop">
+            <!-- Desktop aside layout -->
+            <AwCard title="Desktop Sidebar">...</AwCard>
+        </div>
+        <div v-else>
+            <!-- Mobile aside layout -->
+            <AwAccordionFold title="More Info">...</AwAccordionFold>
+        </div>
+    </template>
+
+    <template #mobile-aside="{ isDesktop }">
+        <AwCard v-if="!isDesktop" class="custom-mobile-card">
+            <slot name="aside" />
+        </AwCard>
+    </template>
+</AwPageAside>
+```
+
+### Pass-Through AwPage Props
+
+```markup
+<AwPageAside
+    title="Page Title"
+    :breadcrumb="{ href: '/back', title: 'Back' }"
+    :subnav="tabs"
+    container="small"
+>
+    <template #buttons>
+        <AwButton>Action</AwButton>
+    </template>
+
+    <template #default>
+        <p>Main content</p>
+    </template>
+
+    <template #aside>
+        <p>Sidebar</p>
+    </template>
+</AwPageAside>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| desktopFrom | Screen breakpoint for desktop layout | `String` | `false` | `'lg'` |
+| modifiers | CSS modifier classes (e.g., `'line'` for separator) | `String` / `Object` | `false` | `''` |
+| hideMobileAside | Hide aside section on mobile | `Boolean` | `false` | `false` |
+
+**Breakpoint Options:** `'sm'`, `'md'`, `'lg'`, `'xl'`, `'2xl'`
+
+**All `AwPage` props** are also supported and passed through via `v-bind="$attrs"`:
+- `title` - Page title
+- `breadcrumb` - Breadcrumb navigation
+- `subnav` - Subnavigation tabs
+- `container` - Container size
+- `fullscreen` - Fullscreen mode
+- etc.
+
+See [AwPage documentation](./aw-page.md#props) for complete list.
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Main page content | `{ isDesktop }` | - |
+| aside | Aside sidebar content | `{ isDesktop }` | - |
+| aside-buttons | Buttons at bottom of aside (sticky) | - | - |
+| mobile-aside | Custom mobile aside wrapper | `{ isDesktop }` | AwCard wrapper |
+| bottom | Content below main content | - | - |
+
+**Pass-through slots from AwPage:**
+- `heading` - Custom page header
+- `title` - Custom title content
+- `buttons` - Header buttons
+- `subnav` - Custom subnavigation
+- `headline-breadcrumb` - Custom breadcrumb
+- `after-breadcrumb` - Content after breadcrumb
+- `mobile-title` - Mobile title display
+- `bottom-bar` - Custom bottom bar
+
+All slots receive `isDesktop` prop for responsive rendering.
+
+### Events
+
+All events from `AwPage` are passed through (e.g., `update:fullscreen`).
+
+### Data Properties
+
+| Name | Description | Type |
+|------|-------------|------|
+| hideBottomBar | Whether bottom bar is hidden (computed from AwPage) | `Boolean` |
+
+### Computed Properties
+
+| Name | Description |
+|------|-------------|
+| isDesktop | Whether current screen size is desktop (based on `desktopFrom` prop) |
+| _slots | Filtered slots object excluding self-managed slots |
+
+### Methods
+
+| Name | Parameters | Description |
+|------|------------|-------------|
+| _wathcBottomBar | - | Updates hideBottomBar state from AwPage reference |
+
+### Head
+
+Component adds `aw-page-aside-page-body` class to `<body>` element for styling.
+
+## Related Components
+
+- [AwPage](./aw-page.md) - Base page component used internally
+- [AwPageSingle](./aw-page-single.md) - Single column page layout
+- [AwCard](../atoms/aw-card.md) - Card component used for mobile aside wrapper
+- [AwButton](../molecules/aw-button.md) - Button component for aside actions
+
+## Notes
+
+- **Import Method:** Dynamic - Component is loaded on-demand as a page component
+- Component wraps `AwPage` and passes through all props via `$attrs`
+- Desktop/mobile layout switches based on `$screen[desktopFrom]` breakpoint
+- On desktop, aside appears as a fixed-width sidebar on the right
+- On mobile, aside appears as a card below main content (unless `hideMobileAside` is true)
+- Aside buttons are sticky at the bottom on both desktop and mobile
+- Bottom spacing adjusts automatically when bottom bar is present (`4rem` padding)
+- Uses CSS custom property `--page-aside-buttons-bottom` for spacing control
+- Component filters out `default`, `aside`, and `aside-buttons` slots before passing to AwPage
+- The `modifiers` prop with value `'line'` adds `.aw-page-aside__aside--line` class
+- Uses `$refs.page` to access internal AwPage component state
+- Bottom bar visibility is watched in `created` and `updated` lifecycle hooks
+- All pass-through slots maintain their scoped slot data plus `isDesktop` prop
+- Component uses `inheritAttrs: false` to control attribute inheritance
+- Body class is set via Nuxt's `head()` method for global styling
+
+## Layout Structure
+
+**Desktop Layout:**
+```
+┌─────────────────────────────────────────────┐
+│ AwPage Wrapper (Main Content)               │
+│ ┌─────────────────────────────────────────┐ │ ┌─────────────┐
+│ │ Page Header                             │ │ │   Aside     │
+│ ├─────────────────────────────────────────┤ │ │   Content   │
+│ │ Main Content                            │ │ │             │
+│ │                                         │ │ │             │
+│ │                                         │ │ │             │
+│ └─────────────────────────────────────────┘ │ ├─────────────┤
+│                                             │ │   Buttons   │
+└─────────────────────────────────────────────┘ └─────────────┘
+```
+
+**Mobile Layout:**
+```
+┌─────────────────────────────────────────────┐
+│ Page Header                                 │
+├─────────────────────────────────────────────┤
+│ Main Content                                │
+│                                             │
+│                                             │
+├─────────────────────────────────────────────┤
+│ Mobile Aside (Card)                         │
+│                                             │
+├─────────────────────────────────────────────┤
+│ Aside Buttons (Sticky)                      │
+└─────────────────────────────────────────────┘
+```

package/docs/components/pages/aw-page-menu-buttons.md

@@ -0,0 +1,172 @@
+---
+metaTitle: PageMenuButtons component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwPageMenuButtons /> component renders page action buttons with responsive behavior - UI Vue component for AwesCode UI.
+title: PageMenuButtons
+---
+
+# AwPageMenuButtons
+
+**Category:** Page | **Import:** Dynamic
+
+The `AwPageMenuButtons` component displays page action buttons with responsive behavior. On desktop, buttons are shown expanded; on mobile, CTA buttons become fixed floating buttons and others go into a context menu dropdown.
+
+## Overview
+
+`AwPageMenuButtons` provides responsive page actions with:
+- Desktop: Full buttons displayed expanded
+- Mobile: CTA buttons as fixed floating buttons, others in dropdown
+- Context menu for non-CTA buttons
+- Download button handling with loading states
+- Teleport/portal support for fixed buttons
+- Scroll-based expand/collapse animation
+- Conditional visibility support
+- Tooltip support
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwPageMenuButtons
+  :items="[
+    { text: 'Save', cta: true, href: '/save' },
+    { text: 'Edit', href: '/edit', icon: 'edit' },
+    { text: 'Delete', href: '/delete', icon: 'trash' }
+  ]"
+/>
+```
+
+### With Download Button
+
+```markup
+<AwPageMenuButtons
+  :items="[
+    { text: 'Download PDF', download: 'pdf', href: '/api/download', icon: 'download', cta: true }
+  ]"
+/>
+```
+
+### With Conditional Visibility
+
+```markup
+<AwPageMenuButtons
+  :items="[
+    { text: 'Edit', cta: true, href: '/edit', show: (vm) => vm.$can('edit', 'post') },
+    { text: 'Delete', href: '/delete', show: false }
+  ]"
+/>
+```
+
+### Custom Breakpoint
+
+```markup
+<AwPageMenuButtons
+  :items="buttons"
+  breakpoint="xl"
+  teleport-fixed-to=".custom-container"
+/>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| items | Array of button configurations | `Array` | `false` | `[]` |
+| breakpoint | Screen breakpoint for expanded/collapsed state | `String` | `false` | `'lg'` |
+| teleportFixedTo | Target selector for fixed buttons teleport | `String` | `false` | `'body'` |
+| expandOffset | Max scroll distance for expanded fixed buttons (px) | `Number` | `false` | `150` |
+| showContextMenuTextFrom | Breakpoint to show context menu text | `String` | `false` | `'lg'` |
+| iconVertical | Vertical icon orientation in context menu | `Boolean` | `false` | `false` |
+
+### Button Item Structure
+
+Each item in the `items` array can have these properties:
+
+```javascript
+{
+  text: String,            // Button text
+  icon: String,            // Icon name
+  href: String,            // Link URL
+  cta: Boolean,            // Call-to-action (primary button, shows as fixed on mobile)
+  download: String,        // File type for download ('pdf', 'csv', etc.)
+  tooltip: String,         // Tooltip text
+  show: Boolean|Function,  // Visibility (can be function receiving component instance)
+  listeners: Object,       // Custom event listeners
+  // ... any other AwButton props
+}
+```
+
+### Slots
+
+This component does not have slots.
+
+### Events
+
+This component does not emit custom events.
+
+### Injected Context
+
+The component injects optional `teleportButtonsTo` from parent for teleport target.
+
+## Responsive Behavior
+
+### Desktop (breakpoint+)
+
+- All buttons displayed as full `AwButton` components
+- CTA buttons and regular buttons shown in expanded state
+- Context menu shows non-CTA buttons in dropdown
+
+### Mobile (< breakpoint)
+
+- CTA buttons teleported as fixed floating buttons at bottom
+- Non-CTA buttons only in context menu dropdown
+- Fixed buttons collapse based on scroll position
+
+## Download Handling
+
+Buttons with `download` property automatically:
+- Prevent default click behavior
+- Show loading state during download
+- Use `downloadFile` utility for file downloads
+- Require `$axios` instance
+
+Example:
+```markup
+{
+  text: 'Export',
+  download: 'xlsx',
+  href: '/api/export',
+  cta: true
+}
+```
+
+## Scroll Behavior
+
+Fixed buttons expand/collapse based on scroll position:
+- `expandOffset > 0`: Buttons expand when scroll < offset
+- `expandOffset === -1`: Buttons never expand (always collapsed)
+- `expandOffset === 150` (default): Expand in top 150px
+
+Button text visibility is controlled by scroll position on mobile.
+
+## Related Components
+
+- `AwPage` - Main page component
+- `AwPageSingle` - Often used with page menu buttons
+- `AwButton` - Button component used for rendering
+- `AwContextMenu` - Dropdown menu for non-CTA buttons
+
+## Notes
+
+- **Import Method:** Dynamic - Component is loaded on-demand as page component
+- Uses Teleport (vue2-teleport) for fixed buttons
+- Fixed buttons set CSS variable `--page-fixed-buttons-height` on body
+- CTA buttons transformed to icon buttons on mobile (size lg, theme solid)
+- Context menu positioned at bottom-end with 8px offset
+- Visibility functions receive component instance for conditional logic
+- Download functionality requires axios integration
+- Tooltip directive support for all buttons

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

@@ -0,0 +1,198 @@
+---
+metaTitle: PageModal component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwPageModal /> component renders a modal page overlay with multiple themes - UI Vue component for AwesCode UI.
+title: PageModal
+---
+
+# AwPageModal
+
+**Category:** Page | **Import:** Dynamic
+
+The `AwPageModal` component provides a modal/dialog page overlay with multiple display themes: default (centered modal), fullscreen, and aside (side panel). It includes header, content area, and optional button footer.
+
+## Overview
+
+`AwPageModal` provides modal page display with:
+- Three themes: default, fullscreen, aside
+- Header with title, breadcrumb, and close button
+- Scrollable content area
+- Optional button footer
+- Body scroll locking
+- Click-outside-to-close support
+- Back button integration
+- Responsive design
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwPageModal title="Edit User">
+  <AwForm url="/api/users/1">
+    <AwInput name="name" label="Name" />
+    <AwInput name="email" label="Email" />
+  </AwForm>
+</AwPageModal>
+```
+
+### Fullscreen Theme
+
+```markup
+<AwPageModal
+  title="Document Editor"
+  theme="fullscreen"
+  container="small"
+>
+  <AwMarkdownEditor v-model="content" />
+</AwPageModal>
+```
+
+### Aside Theme (Side Panel)
+
+```markup
+<AwPageModal
+  title="Filters"
+  theme="aside"
+  @close="$router.back()"
+>
+  <AwForm>
+    <AwSelect name="category" label="Category" />
+    <AwSelect name="status" label="Status" />
+  </AwForm>
+</AwPageModal>
+```
+
+### With Breadcrumb and Buttons
+
+```markup
+<AwPageModal
+  title="Order Details"
+  :breadcrumb="{ href: '/orders', title: 'Orders' }"
+>
+  <template #default="{ closeModal }">
+    <OrderDetails :order="order" />
+  </template>
+
+  <template #buttons>
+    <AwButton @click="saveOrder">Save</AwButton>
+    <AwButton color="mono" @click="$router.back()">Cancel</AwButton>
+  </template>
+</AwPageModal>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| title | Modal title | `String` | `false` | `''` |
+| breadcrumb | Breadcrumb object with href | `Object` | `false` | `null` |
+| theme | Modal theme | `String` | `false` | `'default'` |
+| container | Content container size (fullscreen only) | `String` | `false` | `null` |
+
+**Theme Validator:** `'default'`, `'fullscreen'`, `'aside'`
+
+**Container Options (fullscreen only):**
+- `'small'` - Narrower content area
+- `'full'` - Full-width content area
+- `null` - Default width
+
+**Breadcrumb Structure:**
+```javascript
+{
+  href: String,  // Back link URL
+  title: String  // Back button title (for aria-label)
+}
+```
+
+Also inherits all props from `AwPage` component.
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Modal content | `{ closeModal }` | - |
+| headline-title | Custom title rendering | `{ title }` | Title text |
+| headline-after-title | Content after title | - | - |
+| buttons | Button footer area | - | - |
+
+### Events
+
+| Name | Payload | Description |
+|------|---------|-------------|
+| close | - | Emitted when modal should close |
+
+**Note:** If no `close` listener is provided, the component automatically calls `$router.back()` on close.
+
+## Themes
+
+### Default Theme
+
+Centered modal overlay with backdrop:
+- Centered on screen
+- Click backdrop to close
+- Medium-sized dialog
+- Suitable for forms and small content
+
+### Fullscreen Theme
+
+Full-screen modal:
+- Covers entire viewport
+- No backdrop
+- Container size options
+- Suitable for editors and large content
+
+### Aside Theme
+
+Side panel that slides in from right:
+- Appears on right side
+- Backdrop with click-to-close
+- Narrower than default
+- Suitable for filters and sidebars
+
+## Close Behavior
+
+The modal can be closed by:
+1. Click close button (×) in header
+2. Click breadcrumb back arrow
+3. Click outside modal (backdrop) - only in default/aside themes
+4. Custom close handler via `@close` event
+
+If no `close` event handler is provided, `$router.back()` is called automatically.
+
+## Body Scroll Lock
+
+The component automatically:
+- Disables body scrolling when mounted
+- Re-enables body scrolling when destroyed
+- Reserves scrollbar gap to prevent layout shift
+
+## Accessibility
+
+- `role="dialog"` on modal container
+- `role="document"` on dialog content
+- Close button has `aria-label` and `title`
+- Breadcrumb link has `aria-label`
+- Tabindex management for focus
+
+## Related Components
+
+- `AwPage` - Base page component
+- `AwModal` - Standard modal component
+- `AwPageSingle` - Single page layout
+
+## Notes
+
+- **Import Method:** Dynamic - Component is loaded on-demand as page component
+- Uses body-scroll-lock library to prevent background scrolling
+- Inherits props from AwPage component (title, breadcrumb, container)
+- Container prop only affects fullscreen theme
+- Default theme shows centered modal dialog
+- Aside theme slides in from right side
+- Fullscreen theme uses AwIconSystemMono for icons
+- Close button always visible in top-right
+- Breadcrumb back arrow only shows if breadcrumb.href is provided
+- Button footer (buttons slot) adds padding to content area