@awes-io/ui 2.142.3 → 2.144.0

package/docs/components/organisms/aw-cropper.md

@@ -0,0 +1,151 @@
+---
+metaTitle: Cropper component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwCropper /> component is used to render Cropper - UI Vue component for AwesCode UI.
+title: Cropper
+---
+
+# AwCropper
+
+**Category:** Organism | **Import:** Dynamic
+
+The `AwCropper` component is an image cropping tool built on Croppie.js. It allows users to select and crop a portion of an image with rotation support and customizable output dimensions.
+
+## Overview
+
+`AwCropper` provides an image cropping solution with:
+- Interactive crop area selection
+- Image rotation (90° increments)
+- Customizable viewport and output dimensions
+- Circle or square crop shapes
+- Format and quality control
+- Mobile-friendly touch support
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwCropper 
+    src="/path/to/image.jpg"
+    :width="200"
+    :height="200"
+    @save="handleCrop"
+/>
+```
+
+### Square Crop
+
+```markup
+<AwCropper 
+    src="/path/to/image.jpg"
+    :width="300"
+    :height="300"
+    square
+    @save="handleCrop"
+/>
+```
+
+### Custom Output Size
+
+```markup
+<AwCropper 
+    src="/path/to/image.jpg"
+    :width="200"
+    :height="200"
+    :save-width="800"
+    :save-height="800"
+    format="jpeg"
+    :quality="0.9"
+    @save="handleCrop"
+/>
+```
+
+### Custom Buttons
+
+```markup
+<AwCropper 
+    src="/path/to/image.jpg"
+    :width="200"
+    :height="200"
+    @save="handleCrop"
+    @cancel="handleCancel"
+>
+    <template #buttons="{ rotate, save }">
+        <AwButton @click="rotate">Rotate</AwButton>
+        <AwButton @click="save" color="accent">Save</AwButton>
+        <AwButton @click="$emit('cancel')">Cancel</AwButton>
+    </template>
+</AwCropper>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| src | Source image URL | `String` | `true` | - |
+| width | Viewport width in pixels | `String` / `Number` | `false` | `200` |
+| height | Viewport height in pixels | `String` / `Number` | `false` | `200` |
+| saveWidth | Output image width in pixels | `Number` | `false` | `800` |
+| saveHeight | Output image height in pixels | `Number` | `false` | `800` |
+| padding | Padding around viewport | `String` / `Number` | `false` | `100` |
+| format | Output format: `'png'` or `'jpeg'` | `String` | `false` | `'png'` |
+| quality | Output quality (0-1, JPEG only) | `String` / `Number` | `false` | `1` |
+| square | Use square crop shape (instead of circle) | `Boolean` | `false` | `false` |
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| buttons | Custom buttons area | `{ rotate, save }` | Default rotate and save buttons |
+| upload | Upload area (not used in current implementation) | - | - |
+
+### Events
+
+| Name | Payload | Description |
+|------|---------|-------------|
+| save | `Blob` | Emitted when save is clicked, returns cropped image as Blob |
+| cancel | - | Emitted when cancel is clicked (if handled) |
+
+### Methods
+
+| Name | Parameters | Description |
+|------|------------|-------------|
+| rotate | - | Rotate image 90° counter-clockwise |
+| save | - | Trigger save (emits `save` event with Blob) |
+| refresh | - | Refresh cropper with current image |
+
+### Config Options
+
+The component uses default configuration from `@AwConfig`. You can override these defaults in your project's `awes.config.js`:
+
+```javascript
+export default {
+  AwCropper: {
+    baseClass: 'aw-cropper'
+  }
+}
+```
+
+## Related Components
+
+- `AwButton` - Button component for actions
+- `AwImageUpload` - Image upload component
+
+## Notes
+
+- **Import Method:** Dynamic - Component is loaded on-demand as an organism
+- Uses Croppie.js library for image cropping functionality
+- Viewport defines the visible crop area
+- Output dimensions (`saveWidth`/`saveHeight`) define the final image size
+- Format `'png'` supports transparency, `'jpeg'` does not
+- Quality only affects JPEG output (0-1 range)
+- Square mode creates square crop area, otherwise circle
+- Rotation is in 90° increments (counter-clockwise)
+- Pinch zoom is prevented on mobile devices
+- Component initializes Croppie on mount
+- Image orientation is automatically handled
+- Save returns a Blob that can be used with FileReader or FormData

package/docs/components/organisms/aw-date.md

@@ -0,0 +1,161 @@
+---
+metaTitle: Date component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwDate /> component is used to render Date - UI Vue component for AwesCode UI.
+title: Date
+---
+
+# AwDate
+
+**Category:** Organism | **Import:** Dynamic
+
+The `AwDate` component is a date input field with an integrated calendar dropdown. It combines an input field with a calendar picker, supporting single dates, date ranges, and editable text input.
+
+## Overview
+
+`AwDate` provides a date input solution with:
+- Text input field with calendar dropdown
+- Single date or date range selection
+- Editable input (when format allows)
+- Clear button support
+- Prefix/postfix support
+- Automatic calendar view sizing
+- Day.js integration for date formatting
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwDate v-model="selectedDate" label="Select Date" />
+```
+
+### With Format
+
+```markup
+<AwDate 
+    v-model="selectedDate"
+    format="DD.MM.YYYY"
+    label="Date"
+/>
+```
+
+### Date Range
+
+```markup
+<AwDate 
+    v-model="dateRange"
+    range
+    format="DD.MM.YYYY"
+    label="Date Range"
+/>
+```
+
+### Clearable
+
+```markup
+<AwDate 
+    v-model="selectedDate"
+    clearable
+    label="Date"
+/>
+```
+
+### Editable Input
+
+```markup
+<AwDate 
+    v-model="selectedDate"
+    format="DD.MM.YYYY"
+    editable
+    label="Date"
+/>
+```
+
+### With Prefix/Postfix
+
+```markup
+<AwDate 
+    v-model="selectedDate"
+    prefix="From:"
+    postfix="to"
+    label="Date"
+/>
+```
+
+### With Min/Max
+
+```markup
+<AwDate 
+    v-model="selectedDate"
+    :min="minDate"
+    :max="maxDate"
+    label="Date"
+/>
+```
+
+## API
+
+### Props
+
+All props from `AwCalendar` are supported, plus:
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| format | Date format string (e.g., `'DD.MM.YYYY'`) | `String` | `false` | `'ll'` |
+| clearable | Show clear button when value exists | `Boolean` | `false` | `false` |
+| editable | Allow manual text input (only for DMY formats) | `Boolean` | `false` | `false` |
+| prefix | Prefix text shown when value exists | `String` | `false` | `''` |
+| postfix | Postfix text shown when value exists | `String` | `false` | `''` |
+| label | Input label | `String` | `false` | `''` |
+
+**Calendar Props (inherited):**
+- `value`, `range`, `min`, `max`, `disabledDays`, `firstDay`, `showToday`, `parseFormat`, `outputFormat`
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| prefix | Custom prefix content | - | Prefix text |
+| postfix | Custom postfix content | - | Postfix text |
+| All calendar slots | Same as `AwCalendar` | - | - |
+
+### Events
+
+| Name | Payload | Description |
+|------|---------|-------------|
+| input | `Date` / `Object` | Emitted when date is selected |
+| focus | `Event` | Emitted when input receives focus |
+| All calendar events | - | Inherited from `AwCalendar` |
+
+### Config Options
+
+The component uses default configuration from `@AwConfig`. You can override these defaults in your project's `awes.config.js`:
+
+```javascript
+export default {
+  AwDate: {
+    format: 'll'  // Default date format
+  }
+}
+```
+
+## Related Components
+
+- `AwCalendar` - Calendar component used in dropdown
+- `AwInput` - Base input component
+- `AwDropdown` - Dropdown component for calendar
+
+## Notes
+
+- **Import Method:** Dynamic - Component is loaded on-demand as an organism
+- Input is editable only when format contains only DMY characters and separators
+- Calendar dropdown automatically adjusts number of month views based on available width
+- Range selection shows two dates separated by `' - '` in input
+- Uses field mixin for standard field behavior
+- Uses calendar mixin for date logic
+- Format string uses Day.js format tokens
+- When editable, manual input is validated and parsed using format
+- Dropdown closes automatically when date is selected (unless range mode)
+- Clear button clears the value (sets to `null`)

package/docs/components/organisms/aw-display-date.md

@@ -0,0 +1,33 @@
+---
+metaTitle: DisplayDate component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwDisplayDate /> component displays formatted dates - UI Vue component for AwesCode UI.
+title: DisplayDate
+---
+
+# AwDisplayDate
+
+**Category:** Organism | **Import:** Dynamic
+
+The `AwDisplayDate` component displays formatted date strings with support for various formats and localization.
+
+## Usage
+
+```markup
+<AwDisplayDate :date="new Date()" format="MMMM D, YYYY" />
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| date | Date to display | `Date\|String` | `true` | - |
+| format | Date format string | `String` | `false` | `'MMM D, YYYY'` |
+
+## Notes
+
+- **Import Method:** Dynamic - Component is loaded on-demand as organism
+- Uses Day.js for formatting

package/docs/components/organisms/aw-download-link.md

@@ -0,0 +1,46 @@
+---
+metaTitle: DownloadLink component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwDownloadLink /> component provides file download functionality - UI Vue component for AwesCode UI.
+title: DownloadLink
+---
+
+# AwDownloadLink
+
+**Category:** Organism | **Import:** Dynamic
+
+The `AwDownloadLink` component handles file downloads with loading states and error handling.
+
+## Usage
+
+```markup
+<AwDownloadLink
+  href="/api/download/file.pdf"
+  filename="document.pdf"
+>
+  Download PDF
+</AwDownloadLink>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| href | Download URL | `String` | `true` | - |
+| filename | Downloaded filename | `String` | `false` | - |
+
+### Events
+
+| Name | Payload | Description |
+|------|---------|-------------|
+| success | - | Download completed |
+| error | `error` | Download failed |
+
+## Notes
+
+- **Import Method:** Dynamic - Component is loaded on-demand as organism
+- Shows loading state during download
+- Uses axios for download requests

package/docs/components/organisms/aw-fetch-data.md

@@ -0,0 +1,161 @@
+---
+metaTitle: FetchData component | AwesCode UI
+meta:
+  - name: description
+    content: The <AwFetchData /> component is used to render FetchData - UI Vue component for AwesCode UI.
+title: FetchData
+---
+
+# AwFetchData
+
+**Category:** Organism | **Import:** Dynamic
+
+The `AwFetchData` component is a wrapper component that fetches data from an API endpoint and provides loading and error states. It automatically watches route parameters and refetches when they change.
+
+## Overview
+
+`AwFetchData` provides a data fetching solution with:
+- Automatic data fetching on mount
+- Loading state management
+- Error handling and display
+- Route parameter watching (auto-refetch on change)
+- Customizable loading/error displays
+- Blur effect during loading
+
+## Usage
+
+### Basic Example
+
+```markup
+<AwFetchData url="/api/users">
+    <template #default="{ data }">
+        <div v-for="user in data" :key="user.id">
+            {{ user.name }}
+        </div>
+    </template>
+</AwFetchData>
+```
+
+### With Custom Loading
+
+```markup
+<AwFetchData url="/api/users">
+    <template #default="{ data }">
+        <UserList :users="data" />
+    </template>
+    
+    <template #loading>
+        <AwContentPlaceholder type="text" :lines="6" />
+    </template>
+</AwFetchData>
+```
+
+### Loading State for Form Data
+
+```markup
+<AwFetchData url="/api/user/profile">
+    <template #default="{ data }">
+        <AwForm url="/api/user/profile" method="patch">
+            <AwInput v-model="data.name" label="Name" />
+            <AwInput v-model="data.email" label="Email" />
+            <AwButton type="submit">Save</AwButton>
+        </AwForm>
+    </template>
+    
+    <template #loading>
+        <AwContentPlaceholder type="form" :lines="4" />
+    </template>
+</AwFetchData>
+```
+
+### With Custom Error
+
+```markup
+<AwFetchData url="/api/users">
+    <template #default="{ data }">
+        <UserList :users="data" />
+    </template>
+    
+    <template #error="{ error }">
+        <AwAlert :text="error" color="error" />
+        <AwButton @click="refetch">Retry</AwButton>
+    </template>
+</AwFetchData>
+```
+
+### Manual Fetch
+
+```markup
+<AwFetchData url="/api/users" :fetch="false" ref="fetcher">
+    <template #default="{ data }">
+        <UserList :users="data" />
+    </template>
+</AwFetchData>
+
+<AwButton @click="$refs.fetcher._fetchFromWatcher()">
+    Load Data
+</AwButton>
+```
+
+### With Route Parameters
+
+```markup
+<!-- Automatically refetches when ?page= changes -->
+<AwFetchData url="/api/users">
+    <template #default="{ data }">
+        <UserList :users="data" />
+    </template>
+</AwFetchData>
+```
+
+## API
+
+### Props
+
+| Name | Description | Type | Required | Default |
+|------|-------------|------|----------|---------|
+| url | API endpoint URL | `String` | `true` | - |
+| method | HTTP method | `String` | `false` | `'GET'` |
+| tag | HTML tag for wrapper element | `String` | `false` | `'div'` |
+| fetch | Fetch data on mount | `Boolean` | `false` | `true` |
+
+### Slots
+
+| Name | Description | Props | Default Slot Content |
+|------|-------------|-------|---------------------|
+| default | Content with fetched data | `{ data }` | - |
+| loading | Custom loading display | - | Default loading chip with spinner |
+| error | Custom error display | `{ error }` | Default error message with refresh button |
+
+### Events
+
+This component does not emit custom events.
+
+### Methods
+
+| Name | Parameters | Description |
+|------|------------|-------------|
+| _fetchFromWatcher | - | Manually trigger data fetch |
+
+### Mixins
+
+- `WatchParams` - Watches route parameters and refetches when they change
+
+## Related Components
+
+- `AwChip` - Chip component used in default loading state
+- `AwButton` - Button component used in default error state
+- `AwProgress` - Progress component (can be used in loading slot)
+
+## Notes
+
+- **Import Method:** Dynamic - Component is loaded on-demand as an organism
+- Uses `$axios` for HTTP requests (must be configured)
+- Loading state only shows if request takes longer than 350ms
+- Route parameters are automatically included in request
+- Error message is extracted from `response.data.message` or shows default
+- Data is stored in `data` property and passed to default slot
+- Component uses `fetchQuery()` method from `WatchParams` mixin
+- Blur effect (3px) is applied to content during loading
+- Default slot receives `{ data }` object with fetched data
+- Error slot receives `{ error }` string with error message