@awes-io/ui 2.142.3 → 2.144.0

package/docs/components/atoms/aw-tag.md

@@ -0,0 +1,144 @@
+---
+metaTitle: Tag component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwTag /> component is used to render Tag - UI Vue component for AwesCode UI.
+title: Tag
+---
+
+# Tag
+
+**Category:** Atom | **Import:** Global
+
+The `AwTag` component displays a styled tag/badge with optional icon and customizable colors.
+
+## Overview
+
+`AwTag` provides a small badge-like component for displaying tags, labels, or status indicators. It supports custom colors, icons, and can render as different HTML tags.
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwTag text="New" />
+```
+
+### With Icon
+
+```markup
+<AwTag text="Featured" icon="awesio/star" />
+```
+
+### With Animated Icon
+
+```markup
+<AwTag text="Pending" icon="awesio/spinner" icon-class="animate-spin" color="warning" />
+```
+
+### With Custom Colors
+
+```markup
+<AwTag text="Success" color="success" />
+<AwTag text="Warning" color="warning" />
+```
+
+### As Link
+
+```markup
+<AwTag text="Tag" tag="a" href="/tagged" />
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| tag | HTML tag to render | `String` | `false` | `'span'` |
+| color | Background color | `String` | `false` | `'mono-100'` |
+| onColor | Text/icon color | `String` | `false` | `''` |
+| text | Tag text content | `String` | `true` | - |
+| icon | Icon name | `String` | `false` | `null` |
+| iconClass | CSS classes for icon | `String` / `Array` / `Object` | `false` | `null` |
+
+### Slots
+
+No slots are available for this component.
+
+### Events
+
+No events are emitted by this component.
+
+## Component Behavior
+
+### Color System
+
+The component uses the AwesCode UI color system with automatic text color calculation:
+
+**Background color:**
+- Set via `color` prop (default: `'mono-100'`)
+- Accepts any valid color from the color system
+- Uses `toColor()` utility to convert color name to CSS variable
+
+**Text/icon color:**
+- Automatically calculated using `toOnColor()` for optimal contrast
+- Can be overridden with `onColor` prop
+- Ensures accessibility by using paired colors
+
+**Custom colors:**
+- Custom colors are detected via `isCustomColor()` utility
+- Uses special overlay color for custom color backgrounds
+- Ensures consistent appearance across themes
+
+For a complete list of available colors, see [Built-in Colors](/reference/colors).
+
+### Icon Display
+
+Icons are displayed before the text when provided:
+- Icon size is fixed at 16px
+- Icon color matches the text color (calculated from background)
+- Use `iconClass` prop to add custom CSS classes (e.g., `animate-spin` for loading states)
+
+**Common icon use cases:**
+```markup
+<!-- Status with spinning icon -->
+<AwTag text="Loading" icon="awesio/spinner" icon-class="animate-spin" />
+
+<!-- Static status icon -->
+<AwTag text="Complete" icon="awesio/check-circle" color="success" />
+```
+
+For a complete list of available icons, see [Built-in Icons](/reference/icons).
+
+### HTML Tag Rendering
+
+The component can render as any HTML element:
+- Default: `<span>` - Inline element for text flow
+- Link: `<a>` - Interactive link element
+- Other: Any valid HTML tag name
+
+**Example:**
+```markup
+<!-- As link -->
+<AwTag text="View all" tag="a" href="/tags/featured" />
+
+<!-- As div -->
+<AwTag text="Block tag" tag="div" />
+```
+
+## Related Components
+
+- `AwLabel` - Label component with similar functionality
+- `AwBadge` - Badge component
+- `AwTags` - Multiple tags component
+
+## Notes
+
+- **Import Method:** Global - Available as atom component
+- Default background color is `mono-100`
+- Text color is automatically calculated from background color if `onColor` not provided
+- Supports custom colors via theme color system
+- Icon is displayed before the text
+- Can be rendered as any HTML tag (e.g., `a` for links)
+

package/docs/components/atoms/aw-title.md

@@ -0,0 +1,70 @@
+---
+metaTitle: Title component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwTitle /> component is used to render Title - UI Vue component for AwesCode UI.
+title: Title
+---
+
+# Title
+
+**Category:** Atom | **Import:** Global
+
+The `AwTitle` component is a semantic title wrapper with consistent styling.
+
+## Overview
+
+`AwTitle` provides a styled title component that can render as different HTML heading tags (h1-h6). It applies consistent typography and spacing for page or section titles.
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwTitle>Page Title</AwTitle>
+```
+
+### With Custom Tag
+
+```markup
+<AwTitle tag="h1">Main Title</AwTitle>
+```
+
+### Different Heading Levels
+
+```markup
+<AwTitle tag="h1">Level 1 Title</AwTitle>
+<AwTitle tag="h2">Level 2 Title</AwTitle>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| tag | HTML heading tag (h1-h6) | `String` | `false` | `'h2'` |
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Title text content | - | - |
+
+### Events
+
+No events are emitted by this component.
+
+## Related Components
+
+- `AwHeadline` - Headline component
+- `AwSubHeadline` - Sub-headline component
+- `AwPage` - Page component that uses titles
+
+## Notes
+
+- **Import Method:** Global - Available as atom component
+- Default tag is `h2`
+- Use for page titles and main section headings
+- Maintains semantic HTML structure with appropriate heading levels
+

package/docs/components/atoms/aw-toggler.md

@@ -0,0 +1,90 @@
+---
+metaTitle: Toggler component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwToggler /> component is used to render Toggler - UI Vue component for AwesCode UI.
+title: Toggler
+---
+
+# Toggler
+
+**Category:** Atom | **Import:** Global | **Status:** ⚠️ Deprecated
+
+The `AwToggler` component is a collapsible content wrapper with a styled container.
+
+> **⚠️ Deprecated:** This component is deprecated and should not be used in new projects. Use `AwAccordionFold` directly instead.
+
+## Overview
+
+`AwToggler` provides a toggleable content section that can be expanded or collapsed. It wraps `AwAccordionFold` with additional styling for a content container.
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwToggler>
+    <p>Toggled content</p>
+</AwToggler>
+```
+
+### With Show Prop
+
+```markup
+<AwToggler :show="isOpen">
+    <div>Content that is open by default</div>
+</AwToggler>
+```
+
+## API
+
+### Props
+
+All props from `AwAccordionFold` are supported via `$attrs`:
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| show | Whether content is visible | `Boolean` | `false` | `false` |
+| tag | HTML tag for wrapper | `String` | `false` | `'div'` |
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Toggled content | - | - |
+
+### Events
+
+All events from `AwAccordionFold` are supported via `$listeners`.
+
+## Related Components
+
+- `AwAccordionFold` - Base accordion component
+- `AwCard` - Card component that may use togglers
+
+## Migration Guide
+
+**Instead of:**
+```markup
+<AwToggler :show="isOpen">
+    <p>Content here</p>
+</AwToggler>
+```
+
+**Use:**
+```markup
+<AwAccordionFold :show="isOpen">
+    <div class="bg-mono-800 rounded p-4 mt-3">
+        <p>Content here</p>
+    </div>
+</AwAccordionFold>
+```
+
+## Notes
+
+- **Import Method:** Global - Available as atom component
+- **Status:** Deprecated - Use `AwAccordionFold` instead
+- Wraps `AwAccordionFold` with styled content container
+- Content container has background, padding, and rounded corners
+- All props and events are passed through to `AwAccordionFold`
+- Use for collapsible sections with styled content areas

package/docs/components/layouts/aw-layout-center.md

@@ -0,0 +1,168 @@
+---
+metaTitle: LayoutCenter component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwLayoutCenter /> is a centered layout for authentication and standalone pages for AwesCode UI.
+title: LayoutCenter
+---
+
+# AwLayoutCenter
+
+**Category:** Layout | **Import:** Dynamic
+
+The `AwLayoutCenter` component is a centered layout designed for authentication pages, standalone forms, and centered content. It provides a centered frame with optional logo and background.
+
+## Overview
+
+`AwLayoutCenter` provides a centered layout with:
+- Centered content frame
+- Optional logo display
+- Background image support
+- Dark theme support
+- Footer copyright text
+- Responsive design
+
+## Usage
+
+### Nuxt Page (Recommended)
+
+For Nuxt pages, use the `layout` property in your component options:
+
+```markup
+<template>
+    <AwCard class="max-w-md mx-auto">
+        <template #title>
+            <AwHeadline>Sign In</AwHeadline>
+        </template>
+
+        <form @submit.prevent="onLogin">
+            <AwGrid>
+                <AwInput
+                    v-model="formData.email"
+                    name="email"
+                    label="Email"
+                    type="email"
+                    required
+                />
+
+                <AwPassword
+                    v-model="formData.password"
+                    name="password"
+                    label="Password"
+                    required
+                />
+
+                <AwButton type="submit" size="lg" class="w-full">
+                    Sign In
+                </AwButton>
+            </AwGrid>
+        </form>
+    </AwCard>
+</template>
+
+<script>
+export default {
+    layout: 'center',
+
+    data() {
+        return {
+            formData: {
+                email: '',
+                password: ''
+            }
+        }
+    },
+
+    methods: {
+        onLogin() {
+            // Handle login
+        }
+    }
+}
+</script>
+```
+
+### Component Usage
+
+For non-Nuxt contexts or custom layouts, use the component directly:
+
+```markup
+<AwLayoutCenter>
+    <AwCard>
+        <h1>Login</h1>
+        <AwForm url="/api/login">
+            <!-- form fields -->
+        </AwForm>
+    </AwCard>
+</AwLayoutCenter>
+```
+
+### With Custom Container
+
+```markup
+<AwLayoutCenter>
+    <template #container>
+        <div class="custom-container">
+            <slot />
+        </div>
+    </template>
+</AwLayoutCenter>
+```
+
+## API
+
+### Props
+
+This component does not have props. Logo and background are managed via Vuex store and config.
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Main content | - | - |
+| container | Custom container wrapper | - | Default centered container |
+
+### Events
+
+This component does not emit custom events.
+
+### Config Options
+
+Background and logo can be configured in `awes.config.js`:
+
+```javascript
+export default {
+  _config: {
+    default: {
+      background: {
+        src: '/path/to/background.jpg',
+        // ... other background styles
+      }
+    },
+    dark: {
+      background: {
+        src: '/path/to/dark-background.jpg'
+      }
+    }
+  }
+}
+```
+
+## Related Components
+
+- `AwLayoutProvider` - Layout provider component (used internally)
+- `AwLayout` - Default layout with sidebar
+
+## Notes
+
+- **Import Method:** Dynamic - Component is loaded on-demand as a layout
+- **For Nuxt pages:** Use `layout: 'center'` in component options instead of wrapping with `<AwLayoutCenter>`
+- The Nuxt layout system automatically wraps your page content with `AwLayoutCenter`
+- Logo is retrieved from Vuex store (`awesIo` module)
+- Background image is configured via `$awes._config`
+- Background changes based on dark theme state
+- Logo is hidden on mobile (`hidden sm:block`)
+- Footer copyright text is automatically displayed
+- Content frame is centered with max-width
+- Component uses `AwLayoutProvider` for layout structure
+- Suitable for login, registration, and standalone pages

package/docs/components/layouts/aw-layout-error.md

@@ -0,0 +1,153 @@
+---
+metaTitle: LayoutError component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwLayoutError /> is an error page layout for displaying error states (403, 404, 500) for AwesCode UI.
+title: LayoutError
+---
+
+# AwLayoutError
+
+**Category:** Layout | **Import:** Dynamic
+
+The `AwLayoutError` component is a dedicated error page layout for displaying error states such as 403 Forbidden, 404 Not Found, and 500 Server Error. It provides a clean, centered error display with custom graphics for different error types.
+
+## Overview
+
+`AwLayoutError` provides an error page layout with:
+- Custom SVG illustrations for 403 and 404 errors
+- Error status code display
+- Translated error messages
+- Close button to return to homepage
+- Back button to return to homepage
+- Dark theme support
+- Responsive design
+- No navigation or header (standalone error page)
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwLayoutError :error="error" />
+```
+
+### In Nuxt Error Page
+
+```markup
+<template>
+  <AwLayoutError :error="error" />
+</template>
+
+<script>
+export default {
+  layout: 'empty', // or no layout
+  props: {
+    error: {
+      type: Object,
+      default: null
+    }
+  }
+}
+</script>
+```
+
+### With Custom Error Object
+
+```markup
+<AwLayoutError
+  :error="{
+    statusCode: 404,
+    message: 'The page you are looking for does not exist'
+  }"
+/>
+```
+
+### Different Error Codes
+
+```markup
+<!-- 403 Forbidden -->
+<AwLayoutError :error="{ statusCode: 403 }" />
+
+<!-- 404 Not Found -->
+<AwLayoutError :error="{ statusCode: 404 }" />
+
+<!-- 500 Server Error -->
+<AwLayoutError :error="{ statusCode: 500, message: 'Internal server error' }" />
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| error | Error object with statusCode and message | `Object` | `false` | `null` |
+
+**Error Object Structure:**
+```javascript
+{
+  statusCode: 403 | 404 | 500, // Error status code
+  message: String              // Custom error message
+}
+```
+
+### Slots
+
+This component does not have slots.
+
+### Events
+
+This component does not emit custom events.
+
+## Error Types
+
+### 403 Forbidden
+
+Shows a lock/security icon and displays:
+- Translated title from `error_status_403_title`
+- Translated description from `error_status_403_description`
+- Error code message
+
+### 404 Not Found
+
+Shows a search/magnifying glass icon and displays:
+- Translated title from `error_status_404_title`
+- Translated description from `error_status_404_description`
+- Error code message
+
+### Other Errors (500, etc.)
+
+Shows generic error display:
+- Error code message
+- Custom message from error object or "Something is wrong."
+
+## Translation Keys
+
+The component uses the following translation keys:
+- `error_status__code` - "Error {code}"
+- `error_status_403_title` - Title for 403 errors
+- `error_status_403_description` - Description for 403 errors
+- `error_status_404_title` - Title for 404 errors
+- `error_status_404_description` - Description for 404 errors
+- `Back` - Back button text
+
+## Related Components
+
+- `AwLayout` - Default layout with navigation
+- `AwLayoutCenter` - Centered layout for auth pages
+- `AwButton` - Used for close and back buttons
+
+## Notes
+
+- **Import Method:** Dynamic - Component is loaded on-demand as a layout
+- Different SVG illustrations for 403 (security) and 404 (not found) errors
+- Close button in top-right corner returns to homepage (href="/")
+- Back button at bottom returns to homepage (href="/")
+- Status code defaults to 500 if not provided
+- Custom error messages can be provided via error.message
+- Uses CSS custom properties for theming (`--c-mono-900`, `--c-on-surface`)
+- Fully responsive with mobile-first design
+- Back button is full-width on mobile, auto-width on desktop
+- No sidebar or header navigation (standalone error page)
+- Suitable for Nuxt error.vue layouts