@awes-io/ui 2.142.0 → 2.143.0

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

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

@@ -0,0 +1,253 @@
+---
+metaTitle: PageSingle component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwPageSingle /> component renders a single entity page with header, content, and optional preview panel - UI Vue component for AwesCode UI.
+title: PageSingle
+---
+
+# AwPageSingle
+
+**Category:** Page | **Import:** Dynamic
+
+The `AwPageSingle` component provides a page layout for displaying single entities (user profile, document view, product details, etc.) with a sticky header, content area, optional preview panel, and action button support.
+
+## Overview
+
+`AwPageSingle` provides single-entity page layout with:
+- Sticky page header with breadcrumb
+- Title and description display
+- Content area with optional preview panel
+- Mobile/desktop responsive layouts
+- Fixed action button on mobile
+- Progress indicator support
+- Scroll-based sticky behavior
+- Container size options
+
+## Usage
+
+**⚠️ Essential: Always use `layout: 'empty'`**
+
+Every page using `AwPageSingle` must include `layout: 'empty'` in the component export:
+
+```javascript
+export default {
+    layout: 'empty',  // Required for AwPageSingle pages
+    // ... rest of component
+}
+```
+
+### Basic Example
+
+```markup
+<template>
+  <AwPageSingle title="John Doe" description="User Profile">
+    <AwCard>
+      <h3>Personal Information</h3>
+      <!-- user details -->
+    </AwCard>
+  </AwPageSingle>
+</template>
+
+<script>
+export default {
+  layout: 'empty'
+}
+</script>
+```
+
+### With Preview Panel
+
+```markup
+<AwPageSingle
+  title="Invoice #12345"
+  description="Draft invoice"
+  :breadcrumb="{ href: '/invoices', title: 'Invoices' }"
+>
+  <!-- Main content -->
+  <AwForm url="/api/invoices/12345">
+    <AwInput name="customer" label="Customer" />
+    <AwInput name="amount" label="Amount" />
+  </AwForm>
+
+  <!-- Preview panel -->
+  <template #preview>
+    <InvoicePreview :invoice="invoice" />
+  </template>
+</AwPageSingle>
+```
+
+### With Action Button
+
+```markup
+<AwPageSingle
+  title="Document"
+  :action="{ text: 'Save', icon: 'awesio/check', color: 'accent' }"
+  @action="saveDocument"
+>
+  <AwMarkdownEditor v-model="content" />
+</AwPageSingle>
+```
+
+### With Custom Container
+
+```markup
+<AwPageSingle
+  title="Wide Content"
+  container="full"
+>
+  <AwTable :data="items" />
+</AwPageSingle>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| title | Page title | `String` | `false` | `''` |
+| description | Description text (mobile only) | `String` | `false` | `''` |
+| headerDescription | Description in header (desktop) | `String` | `false` | `''` |
+| breadcrumb | Breadcrumb configuration | `Object` | `false` | `null` |
+| headerProgress | Progress value (0-100) | `Number` | `false` | `null` |
+| action | Action button configuration | `Object` | `false` | `null` |
+| container | Container size type | `String` | `false` | `null` |
+| desktopFrom | Breakpoint for desktop layout | `String` | `false` | `'lg'` |
+| reverse | Reverse content/preview order | `Boolean` | `false` | `false` |
+| hideMenu | Hide page menu | `Boolean` | `false` | `false` |
+
+**Breadcrumb Structure:**
+```javascript
+{
+  href: String,  // Back link URL (optional, defaults to $router.back())
+  title: String  // Back button aria-label
+}
+```
+
+**Action Button Structure:**
+```javascript
+{
+  text: String,      // Button text
+  icon: String,      // Icon name
+  color: String,     // Button color
+  before: Boolean,   // Show before menu on desktop
+  // ... any other AwButton props
+}
+```
+
+**Container Options:**
+- `'default'` - Standard container with max-width
+- `'full'` - Full-width fluid container
+- `null` - Custom preview-based layout
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Main content area | - | - |
+| preview | Preview panel (right side on desktop) | - | - |
+| breadcrumb | Custom breadcrumb content | - | Back button |
+| after-breadcrumb | Content after breadcrumb | - | - |
+| buttons | Additional buttons in header | - | - |
+| after-menu | Content after page menu | - | - |
+
+### Events
+
+| Name | Payload | Description |
+|------|---------|-------------|
+| action | - | Emitted when action button is clicked |
+
+## Layout Behavior
+
+### Desktop (lg+)
+
+- Sticky header with title and action button
+- Content and preview side-by-side (if preview slot used)
+- Action button in header (position based on `action.before`)
+- Description shown in header if `headerDescription` provided
+
+### Mobile
+
+- Title in header when scrolled (hidden at top)
+- Content and preview stacked vertically
+- Fixed floating action button at bottom
+- Description shown below header if `description` provided
+- Action button sticky at bottom
+
+## Container Types
+
+### Default Container
+
+Standard centered container with max-width:
+```markup
+<AwPageSingle container="default">
+```
+
+### Full Container
+
+Full-width fluid container:
+```markup
+<AwPageSingle container="full">
+```
+
+### Preview Container (null)
+
+Custom two-column layout with preview:
+```markup
+<AwPageSingle :container="null">
+  <div>Content</div>
+  <template #preview>Preview</template>
+</AwPageSingle>
+```
+
+## Scroll Behavior
+
+The component uses IntersectionObserver to track:
+- Header sticky state (when scrolled past top)
+- Action button sticky state on mobile
+
+Scroll marks are placed at top and bottom of content to detect visibility.
+
+## Reverse Layout
+
+Use `reverse` prop to swap content/preview order:
+```markup
+<AwPageSingle reverse>
+  <div>Main content</div>
+  <template #preview>Preview (shows on left)</template>
+</AwPageSingle>
+```
+
+## Header Progress
+
+Show progress indicator in header:
+```markup
+<AwPageSingle
+  title="Document"
+  :header-progress="75"
+>
+```
+
+Progress bar appears in header, useful for multi-step forms or loading states.
+
+## Related Components
+
+- `AwPage` - Standard page component
+- `AwPageHeader` - Page header component (used internally)
+- `AwPageModal` - Modal page component
+- `AwPageMenuButtons` - Page menu buttons
+
+## Notes
+
+- **Import Method:** Dynamic - Component is loaded on-demand as page component
+- Uses `pageMixin` for common page functionality
+- Sets body class `aw-page-single-noty` for notification positioning
+- Automatically handles responsive breakpoints
+- Preview panel only shows if preview slot is used
+- Action button placement differs between mobile/desktop
+- Back button uses `$router.back()` if no breadcrumb.href provided
+- IntersectionObserver for scroll detection
+- Supports Nuxt head() for body attributes
+- Header stickiness based on scroll position
+- Mobile action button animates based on bottom visibility