@awes-io/ui 2.142.3 → 2.144.0

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

@@ -0,0 +1,300 @@
+---
+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>
+```
+
+### 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
+<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

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

@@ -0,0 +1,194 @@
+---
+metaTitle: Page component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwPage /> general container for internal pages in AwesCode UI.
+title: Page
+---
+
+# AwPage
+
+**Category:** Page | **Import:** Dynamic
+
+The `AwPage` component is a top-level page container that provides a structured layout with header, breadcrumbs, title, subnavigation, content area, and optional bottom bar. It's the primary component for building pages in the application.
+
+## Overview
+
+`AwPage` provides a complete page structure with:
+- Page header with title and breadcrumb navigation
+- Optional subnavigation tabs
+- Flexible content container (default, small, full)
+- Fullscreen mode support
+- Mobile-responsive layout with sticky header
+- Bottom bar for mobile devices
+- Aside content area support
+- Integration with Vuex store for navigation state
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwPage title="Page Title">
+    <p>Page content goes here</p>
+</AwPage>
+```
+
+### With Breadcrumb
+
+```markup
+<AwPage 
+    title="Page Title"
+    :breadcrumb="{ href: '/overview', title: 'Overview' }"
+>
+    <p>Page content</p>
+</AwPage>
+```
+
+### With Subnavigation
+
+```markup
+<AwPage 
+    title="Page Title"
+    :subnav="[
+        { href: '/page/tab1', title: 'Tab 1' },
+        { href: '/page/tab2', title: 'Tab 2' }
+    ]"
+>
+    <p>Page content</p>
+</AwPage>
+```
+
+### With Buttons Slot
+
+```markup
+<AwPage title="Page Title">
+    <template #buttons>
+        <AwButton icon="plus" cta>Create</AwButton>
+        <AwButton>Settings</AwButton>
+    </template>
+    
+    <p>Page content</p>
+</AwPage>
+```
+
+### With Custom Container
+
+```markup
+<AwPage title="Page Title" container="small">
+    <p>Content in small container</p>
+</AwPage>
+
+<AwPage title="Page Title" container="full">
+    <p>Content in full-width container</p>
+</AwPage>
+```
+
+### With Aside Content
+
+```markup
+<AwPage title="Page Title">
+    <template #default>
+        <p>Main content</p>
+    </template>
+    
+    <template #aside>
+        <AwCard title="Sidebar">Sidebar content</AwCard>
+    </template>
+</AwPage>
+```
+
+### Fullscreen Mode
+
+```markup
+<AwPage title="Page Title" :fullscreen="isFullscreen">
+    <p>Fullscreen content</p>
+</AwPage>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| title | Main headline on the page | `String` | `false` | `''` |
+| metaTitle | Meta title for SEO (uses `title` if not provided) | `String` | `false` | `''` |
+| titleTag | HTML tag for title element | `String` | `false` | `'h1'` |
+| breadcrumb | Breadcrumb object with `href` and `title` | `Object` | `false` | `null` |
+| subnav | Subnavigation items array | `Array` | `false` | `[]` |
+| fullscreen | Enable fullscreen mode | `Boolean` | `false` | `false` |
+| container | Container size: `'default'`, `'small'`, or `'full'` | `String` | `false` | `'default'` |
+| headerContainer | Container size for header (overrides `container`) | `String` | `false` | `null` |
+| hideBottomBar | Hide mobile bottom bar | `Boolean` | `false` | `null` (auto) |
+| buttonsBreakpoint | Breakpoint for button visibility | `String` | `false` | `'lg'` |
+| breadcrumbMenu | Show menu toggle in breadcrumb area | `Boolean` | `false` | `undefined` |
+
+**Breadcrumb Object:**
+```javascript
+{
+  href: '/path',  // Required
+  title: 'Back'   // Optional
+}
+```
+
+**Subnav Items:**
+```javascript
+[
+  { href: '/path', title: 'Tab Title' },
+  // ... more items
+]
+```
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Main page content | - | - |
+| aside | Sidebar content (enables aside layout) | - | - |
+| heading | Custom header (replaces default) | `{ titleTag, title, breadcrumb }` | Default header |
+| title | Custom title content | `{ title, titleShowable, hideTitle }` | Default title |
+| buttons | Header buttons area | - | - |
+| subnav | Custom subnavigation | `{ subnav }` | Default `AwTabNav` component |
+| headline-breadcrumb | Custom breadcrumb button | - | Default back button |
+| after-breadcrumb | Content after breadcrumb | - | - |
+| mobile-title | Mobile title display | `{ title }` | Title text |
+| bottom-bar | Custom bottom bar | - | Default `AwBottomBar` component |
+
+### Events
+
+| Name | Payload | Description |
+|------|---------|-------------|
+| update:fullscreen | `Boolean` | Emitted when fullscreen state changes |
+
+### Config Options
+
+The component uses default configuration from `@AwConfig`. You can override these defaults in your project's `awes.config.js`:
+
+```javascript
+export default {
+  AwPage: {
+    titleTag: 'h1'  // Default HTML tag for title
+  }
+}
+```
+
+## Related Components
+
+- `AwPageHeader` - Internal header component
+- `AwTabNav` - Tab navigation component (used for subnav)
+- `AwBottomBar` - Bottom bar component for mobile
+- `AwButton` - Button component for header actions
+
+## Notes
+
+- **Import Method:** Dynamic - Component is loaded on-demand as a page component
+- Breadcrumb automatically uses `backRoute` from Vuex store if available
+- On mobile, breadcrumb area shows menu toggle if no breadcrumb is provided
+- Header becomes sticky on mobile when scrolling
+- Fullscreen mode uses native Fullscreen API with fallback
+- Bottom bar is automatically hidden if breadcrumb is present
+- Container classes: `container` (default), `container-small`, `container-fluid` (full)
+- Component provides `teleportButtonsTo` context for button teleporting
+- Uses `page` mixin for scroll watching and header stickiness
+- Integrates with `$screen` for responsive behavior