@velkymx/vibeui 0.8.0 → 0.8.2

package/docs/components/navigation/pagination.md

@@ -0,0 +1,146 @@
+# VibePagination
+
+Data-driven pagination component with v-model support.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `size` | `'sm' \| 'lg'` | `undefined` | Pagination size |
+| `ariaLabel` | `String` | `'Pagination'` | ARIA label for the nav element |
+| `totalPages` | `Number` | Required | Total number of pages |
+| `currentPage` | `Number` | `1` | Current active page |
+| `showPrevNext` | `Boolean` | `true` | Show previous/next buttons |
+| `prevText` | `String` | `'Previous'` | Text for previous button |
+| `nextText` | `String` | `'Next'` | Text for next button |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:currentPage` | `page: number` | Emitted when page changes (v-model) |
+| `page-click` | `page: number` | Emitted when a page is clicked |
+
+## Slots
+
+| Slot | Scope | Description |
+|------|-------|-------------|
+| `prev` | `{ disabled }` | Custom previous button |
+| `page` | `{ page, active }` | Custom page button |
+| `next` | `{ disabled }` | Custom next button |
+
+## Usage
+
+### Basic Example
+
+```vue
+<template>
+  <VibePagination
+    :total-pages="10"
+    v-model:current-page="currentPage"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const currentPage = ref(1)
+</script>
+```
+
+### Sizes
+
+```vue
+<template>
+  <!-- Small -->
+  <VibePagination :total-pages="5" size="sm" v-model:current-page="page1" />
+
+  <!-- Default -->
+  <VibePagination :total-pages="5" v-model:current-page="page2" />
+
+  <!-- Large -->
+  <VibePagination :total-pages="5" size="lg" v-model:current-page="page3" />
+</template>
+```
+
+### Without Prev/Next Buttons
+
+```vue
+<template>
+  <VibePagination
+    :total-pages="10"
+    :show-prev-next="false"
+    v-model:current-page="currentPage"
+  />
+</template>
+```
+
+### Custom Button Text
+
+```vue
+<template>
+  <VibePagination
+    :total-pages="10"
+    prev-text="← Back"
+    next-text="Forward →"
+    v-model:current-page="currentPage"
+  />
+</template>
+```
+
+### Custom Page Rendering
+
+Use scoped slots for complete customization:
+
+```vue
+<template>
+  <VibePagination :total-pages="10" v-model:current-page="currentPage">
+    <template #prev="{ disabled }">
+      <VibeIcon icon="chevron-left" />
+    </template>
+
+    <template #page="{ page, active }">
+      Page {{ page }}
+    </template>
+
+    <template #next="{ disabled }">
+      <VibeIcon icon="chevron-right" />
+    </template>
+  </VibePagination>
+</template>
+```
+
+### With Event Handling
+
+```vue
+<template>
+  <VibePagination
+    :total-pages="20"
+    v-model:current-page="currentPage"
+    @page-click="handlePageClick"
+  />
+
+  <p>Current page: {{ currentPage }}</p>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const currentPage = ref(1)
+
+const handlePageClick = (page) => {
+  console.log(`Navigated to page ${page}`)
+  // Fetch data for the new page
+}
+</script>
+```
+
+## Bootstrap CSS Classes
+
+- `.pagination`
+- `.pagination-sm`
+- `.pagination-lg`
+- `.page-item`
+- `.page-link`
+- `.active`
+- `.disabled`

package/docs/components/progress/progress.md

@@ -0,0 +1,182 @@
+# VibeProgress
+
+Data-driven progress bar component supporting single or multiple bars.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `height` | `String` | `undefined` | Custom height (e.g., `'20px'`, `'2rem'`) |
+| `bars` | `ProgressBar[]` | Required | Array of progress bars to display |
+
+### ProgressBar Interface
+
+```typescript
+interface ProgressBar {
+  value: number
+  max?: number
+  variant?: Variant
+  striped?: boolean
+  animated?: boolean
+  label?: string
+  showValue?: boolean
+}
+```
+
+## Slots
+
+| Slot | Scope | Description |
+|------|-------|-------------|
+| `label` | `{ bar, index }` | Custom label rendering for each bar |
+
+## Usage
+
+### Basic Progress
+
+```vue
+<template>
+  <VibeProgress :bars="[{ value: 25 }]" />
+</template>
+```
+
+### With Label
+
+```vue
+<template>
+  <VibeProgress :bars="[{ value: 75, showValue: true }]" />
+</template>
+```
+
+### Custom Height
+
+```vue
+<template>
+  <VibeProgress height="20px" :bars="[{ value: 50 }]" />
+</template>
+```
+
+### Colored Progress Bars
+
+```vue
+<template>
+  <div class="d-flex flex-column gap-2">
+    <VibeProgress :bars="[{ value: 25, variant: 'success' }]" />
+    <VibeProgress :bars="[{ value: 50, variant: 'info' }]" />
+    <VibeProgress :bars="[{ value: 75, variant: 'warning' }]" />
+    <VibeProgress :bars="[{ value: 100, variant: 'danger' }]" />
+  </div>
+</template>
+```
+
+### Striped and Animated
+
+```vue
+<template>
+  <div class="d-flex flex-column gap-2">
+    <!-- Striped -->
+    <VibeProgress :bars="[{ value: 60, variant: 'success', striped: true }]" />
+
+    <!-- Animated stripes -->
+    <VibeProgress :bars="[{ value: 75, variant: 'info', animated: true }]" />
+  </div>
+</template>
+```
+
+### Multiple Bars
+
+Stack multiple progress bars in a single component:
+
+```vue
+<template>
+  <VibeProgress :bars="progressBars" />
+</template>
+
+<script setup>
+const progressBars = [
+  { value: 15, variant: 'success' },
+  { value: 30, variant: 'warning' },
+  { value: 20, variant: 'danger' }
+]
+</script>
+```
+
+### Dynamic Progress
+
+```vue
+<script setup>
+import { ref, onMounted } from 'vue'
+
+const progress = ref(0)
+
+onMounted(() => {
+  const interval = setInterval(() => {
+    if (progress.value < 100) {
+      progress.value += 10
+    } else {
+      clearInterval(interval)
+    }
+  }, 500)
+})
+</script>
+
+<template>
+  <VibeProgress :bars="[{
+    value: progress,
+    variant: 'primary',
+    showValue: true
+  }]" />
+</template>
+```
+
+### Custom Label Rendering
+
+Use the `label` scoped slot for custom labels:
+
+```vue
+<template>
+  <VibeProgress :bars="progressBars">
+    <template #label="{ bar }">
+      <strong>{{ bar.value }}% Complete</strong>
+    </template>
+  </VibeProgress>
+</template>
+
+<script setup>
+const progressBars = [{ value: 75, variant: 'success' }]
+</script>
+```
+
+### Complex Example
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const tasks = ref([
+  { name: 'Design', value: 100, variant: 'success' },
+  { name: 'Development', value: 75, variant: 'primary', animated: true },
+  { name: 'Testing', value: 50, variant: 'warning', striped: true },
+  { name: 'Deployment', value: 0, variant: 'secondary' }
+])
+</script>
+
+<template>
+  <div class="d-flex flex-column gap-3">
+    <div v-for="task in tasks" :key="task.name">
+      <div class="d-flex justify-content-between mb-1">
+        <span>{{ task.name }}</span>
+        <span>{{ task.value }}%</span>
+      </div>
+      <VibeProgress :bars="[task]" />
+    </div>
+  </div>
+</template>
+```
+
+## Bootstrap CSS Classes
+
+- `.progress`
+- `.progress-bar`
+- `.bg-{variant}`
+- `.progress-bar-striped`
+- `.progress-bar-animated`

package/docs/composables/back-button.md

@@ -0,0 +1,28 @@
+# useBackButton
+
+A composable to handle the Android hardware back button in hybrid mobile environments (like Capacitor or WebView apps).
+
+## Basic Usage
+
+```javascript
+import { useBackButton } from '@velkymx/vibeui'
+
+// Automatically closes this logic when the back button is pressed
+useBackButton(() => {
+  console.log('Back button pressed!')
+  closeMyOverlay()
+})
+```
+
+## How it Works
+- It listens for the native `backbutton` event emitted by hybrid wrappers.
+- It maintains an internal stack of "closeable" actions.
+- When the back button is pressed, it executes the most recently registered action and prevents the default app-exit behavior.
+- It automatically handles cleanup when the component using it is unmounted.
+
+## Integrated Components
+The following VibeUI components have `useBackButton` integrated automatically:
+- `VibeModal`
+- `VibeOffcanvas`
+
+You don't need to manually use this composable if you are using these components; they will "just work" on Android devices.

package/docs/composables/breakpoints.md

@@ -0,0 +1,54 @@
+# useBreakpoints
+
+A composable for programmatic breakpoint detection using standard Bootstrap grid sizes.
+
+## Basic Usage
+
+```javascript
+import { useBreakpoints } from '@velkymx/vibeui'
+
+const { isMobile, isTablet, isLg, isXxl } = useBreakpoints()
+```
+
+## API
+
+| Property | Type | Description |
+|---|---|---|
+| `isXs` | `ComputedRef<boolean>` | `true` if width < 576px |
+| `isSm` | `Ref<boolean>` | `true` if width >= 576px |
+| `isMd` | `Ref<boolean>` | `true` if width >= 768px |
+| `isLg` | `Ref<boolean>` | `true` if width >= 992px |
+| `isXl` | `Ref<boolean>` | `true` if width >= 1200px |
+| `isXxl` | `Ref<boolean>` | `true` if width >= 1400px |
+| `isMobile` | `ComputedRef<boolean>` | `true` if screen is `xs` or `sm` (width < 768px) |
+| `isTablet` | `ComputedRef<boolean>` | `true` if screen is exactly `md` (768px - 991px) |
+
+## Performance
+This composable uses `window.matchMedia` listeners instead of `resize` events, making it highly performant and efficient. It automatically cleans up listeners when the component is unmounted.
+
+## Example: Adaptive Layout
+
+```vue
+<template>
+  <div>
+    <!-- Show offcanvas navigation on mobile, standard nav on desktop -->
+    <VibeOffcanvas v-if="isMobile" v-model="showSidebar">
+      <MySidebarContent />
+    </VibeOffcanvas>
+    
+    <VibeRow v-else>
+      <VibeCol cols="3">
+        <MySidebarContent />
+      </VibeCol>
+      <VibeCol cols="9">
+        <slot />
+      </VibeCol>
+    </VibeRow>
+  </div>
+</template>
+
+<script setup>
+import { useBreakpoints } from '@velkymx/vibeui'
+const { isMobile } = useBreakpoints()
+</script>
+```

package/docs/composables/color-mode.md

@@ -0,0 +1,141 @@
+# useColorMode
+
+Manages Bootstrap 5.3 color modes (`light`, `dark`, `auto`) for the entire app. Sets the `data-bs-theme` attribute on `<html>`, persists the user's preference to `localStorage`, and provides a reactive ref that components can watch.
+
+**Singleton** — every call to `useColorMode()` returns the same shared state. There is one active color mode per app.
+
+## Import
+
+```ts
+import { useColorMode } from '@velkymx/vibeui'
+```
+
+## Return Values
+
+| Name | Type | Description |
+|---|---|---|
+| `colorMode` | `Ref<ColorMode>` | Reactive current mode. Bind to template or watch for changes. |
+| `setColorMode(mode)` | `(mode: ColorMode) => void` | Set a specific mode. Persists to `localStorage` and updates `<html data-bs-theme>`. |
+| `toggleColorMode()` | `() => void` | Cycle through `light → dark → auto → light`. |
+| `initColorMode()` | `() => void` | Restore the saved preference from `localStorage`. **Call once at app startup.** Subsequent calls are no-ops. |
+| `onColorModeChange(cb)` | `(mode: ColorMode) => void` | Register a callback that fires whenever the mode changes. Useful for hybrid app status bars. |
+
+## Type
+
+```ts
+type ColorMode = 'light' | 'dark' | 'auto'
+```
+
+| Value | Behavior |
+|---|---|
+| `'light'` | Forces light theme regardless of OS setting |
+| `'dark'` | Forces dark theme regardless of OS setting |
+| `'auto'` | Follows the OS `prefers-color-scheme` media query |
+
+## Setup
+
+Call `initColorMode()` once in `main.ts` before mounting the app. This restores the user's last saved preference.
+
+```ts
+// main.ts
+import { createApp } from 'vue'
+import VibeUI, { useColorMode } from '@velkymx/vibeui'
+import 'bootstrap/dist/css/bootstrap.min.css'
+import App from './App.vue'
+
+const { initColorMode } = useColorMode()
+initColorMode()
+
+createApp(App).use(VibeUI).mount('#app')
+```
+
+## Usage
+
+### Toggle button
+
+The most common use case — a button that cycles through all three modes.
+
+```vue
+<script setup lang="ts">
+import { useColorMode } from '@velkymx/vibeui'
+
+const { colorMode, toggleColorMode } = useColorMode()
+</script>
+
+<template>
+  <VibeButton variant="secondary" @click="toggleColorMode">
+    Theme: {{ colorMode }}
+  </VibeButton>
+</template>
+```
+
+### Explicit mode switcher
+
+A select or set of buttons that lets the user pick a specific mode.
+
+```vue
+<script setup lang="ts">
+import { useColorMode } from '@velkymx/vibeui'
+import type { ColorMode } from '@velkymx/vibeui'
+
+const { colorMode, setColorMode } = useColorMode()
+
+const options: { label: string; value: ColorMode }[] = [
+  { label: 'Light', value: 'light' },
+  { label: 'Dark', value: 'dark' },
+  { label: 'System', value: 'auto' },
+]
+</script>
+
+<template>
+  <div class="btn-group">
+    <VibeButton
+      v-for="option in options"
+      :key="option.value"
+      :variant="colorMode === option.value ? 'primary' : 'outline-secondary'"
+      @click="setColorMode(option.value)"
+    >
+      {{ option.label }}
+    </VibeButton>
+  </div>
+</template>
+```
+
+### Watching for changes
+
+React to color mode changes anywhere in the app — for example, to swap a chart theme.
+
+```vue
+<script setup lang="ts">
+import { watch } from 'vue'
+import { useColorMode } from '@velkymx/vibeui'
+
+const { colorMode } = useColorMode()
+
+watch(colorMode, (mode) => {
+  console.log('Color mode changed to:', mode)
+  // e.g. update a third-party chart library's theme
+})
+</script>
+```
+
+### Scoping color mode to a single component
+
+Bootstrap's `data-bs-theme` attribute works on any element, not just `<html>`. For cases where one section of the page should always be dark regardless of the app-level setting, apply it directly in the template instead of using the composable.
+
+```vue
+<template>
+  <div data-bs-theme="dark">
+    <!-- This section is always dark -->
+    <VibeCard>Always dark card</VibeCard>
+  </div>
+</template>
+```
+## Behavior Notes
+
+- **Persistence** — the selected mode is stored in `localStorage` under the key `vibe-color-mode`. It survives page reloads.
+- **System Theme Reactivity** — when the mode is set to `'auto'`, VibeUI automatically listens for OS-level theme changes (via `matchMedia`) and updates the DOM immediately without a page reload.
+- **SSR-safe** — all `document` and `localStorage` access is guarded. The composable is safe to import in server-rendered environments; `applyColorMode` simply does nothing when `document` is undefined.
+...
+- **Invalid values** — `setColorMode` silently ignores any value that is not `'light'`, `'dark'`, or `'auto'`. No error is thrown.
+- **`initColorMode` is idempotent** — it is safe to call it multiple times (e.g. from multiple entry points). Only the first call reads `localStorage` and applies the theme. All subsequent calls are no-ops and do not overwrite changes the user made after initialization.

package/docs/forms/README.md

@@ -0,0 +1,88 @@
+# VibeUI Form Components
+
+Comprehensive form components with built-in validation support for both front-end and API-based validation.
+
+## Overview
+
+VibeUI provides a complete set of form components that seamlessly integrate with Bootstrap styling and include powerful validation capabilities out of the box.
+
+### Features
+
+- ✅ **Full Bootstrap Integration** - Uses native Bootstrap classes and styling
+- ✅ **Zero-Boilerplate IDs** - `id` props are now optional and automatically generated
+- ✅ **Form Automation** - `VibeFormGroup` automatically links its label to child inputs via ID injection
+- ✅ **Two-Way Data Binding** - v-model support on all components
+- ✅ **Built-in Validation** - Comprehensive validation system with custom validators
+- ✅ **Accessible** - Automatic ARIA attribute management and label linking
+- ✅ **TypeScript** - Fully typed components and APIs
+
+## Components
+
+### Input Components
+
+| Component | Description | Documentation |
+|-----------|-------------|---------------|
+| **VibeFormInput** | Text, email, password, number, and other input types | [Docs](./form-input.md) |
+| **VibeInputGroup** | Input group for prepending/appending text or buttons | [Docs](./input-group.md) |
+| **VibeFormTextarea** | Multi-line text input | [Docs](./form-textarea.md) |
+| **VibeFormSelect** | Single and multiple selection dropdowns | [Docs](./form-select.md) |
+| **VibeFormSpinbutton** | Number input with increment/decrement buttons | [Docs](./form-spinbutton.md) |
+| **VibeFormDatepicker** | Date, time, and datetime inputs | [Docs](./form-datepicker.md) |
+
+### Choice Components
+
+| Component | Description | Documentation |
+|-----------|-------------|---------------|
+| **VibeFormCheckbox** | Single checkboxes and checkbox groups | [Docs](./form-checkbox.md) |
+| **VibeFormRadio** | Radio button groups for exclusive selection | [Docs](./form-radio.md) |
+| **VibeFormSwitch** | Toggle switches for boolean settings | [Docs](./form-switch.md) |
+
+### Advanced Components
+
+| Component | Description | Documentation |
+|-----------|-------------|---------------|
+| **VibeFormWysiwyg** | WYSIWYG editor powered by QuillJS | [Docs](./form-wysiwyg.md) |
+| **VibeFormGroup** | Form group container for layout and automated label linking | [Docs](./form-group.md) |
+
+## Quick Start
+
+### Basic Example (Automated)
+
+VibeUI automatically handles ID generation and label linking. No `id` or `label-for` is required when using `VibeFormGroup`.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const email = ref('')
+</script>
+
+<template>
+  <VibeFormGroup label="Email Address">
+    <VibeFormInput
+      v-model="email"
+      type="email"
+      placeholder="Enter email"
+    />
+  </VibeFormGroup>
+</template>
+```
+
+## Documentation
+
+### Component Documentation
+
+- [VibeFormInput](./form-input.md) - Text inputs with validation
+- [VibeInputGroup](./input-group.md) - Prepend/append groups
+- [VibeFormSelect](./form-select.md) - Select dropdowns
+- [VibeFormTextarea](./form-textarea.md) - Multi-line text input
+- [VibeFormSpinbutton](./form-spinbutton.md) - Number input with buttons
+- [VibeFormDatepicker](./form-datepicker.md) - Date and time inputs
+- [VibeFormCheckbox](./form-checkbox.md) - Checkboxes and groups
+- [VibeFormRadio](./form-radio.md) - Radio button groups
+- [VibeFormSwitch](./form-switch.md) - Toggle switches
+- [VibeFormGroup](./form-group.md) - Form group container
+- [VibeFormWysiwyg](./form-wysiwyg.md) - WYSIWYG editor
+
+### Guides
+
+- [Validation Guide](./validation.md) - Comprehensive validation documentation

package/docs/forms/form-checkbox.md

@@ -0,0 +1,50 @@
+# VibeFormCheckbox
+
+Checkbox component for single boolean values or multiple selections.
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const agreed = ref(false)
+</script>
+
+<template>
+  <VibeFormCheckbox
+    v-model="agreed"
+    label="I agree to the terms"
+  />
+</template>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `modelValue` | `any` | `false` | The checked state (v-model) |
+| `value` | `any` | `true` | Value when checked |
+| `id` | `String` | `Auto-generated` | Unique identifier |
+| `label` | `String` | `undefined` | Label text |
+| `disabled` | `Boolean` | `false` | Disable the checkbox |
+| `required` | `Boolean` | `false` | Mark as required |
+| `inline` | `Boolean` | `false` | Display inline |
+| `indeterminate` | `Boolean` | `false` | Set indeterminate state |
+| `validationState` | `'valid' \| 'invalid' \| null` | `null` | Validation state |
+| `validationMessage` | `String` | `undefined` | Validation message |
+| `validateOn` | `'change' \| 'blur'` | `'change'` | When to validate |
+| `helpText` | `String` | `undefined` | Help text |
+| `reverse` | `Boolean` | `false` | Reverse label and input |
+
+## Important Notes
+
+**Automatic ID Generation:** This component automatically generates a unique ID if one is not provided.
+
+**Automatic ID Injection:** When used inside a `VibeFormGroup`, this component will automatically inherit the group's ID to ensure proper label association and accessibility.
+
+## Bootstrap CSS Classes
+
+- `.form-check`
+- `.form-check-input`
+- `.form-check-label`
+- `.is-valid`, `.is-invalid`