@velkymx/vibeui 0.9.0 → 1.0.2

package/docs/components/progress/progress.md

@@ -0,0 +1,188 @@
+# 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'`). Validated as a CSS length; invalid values are ignored |
+| `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>
+```
+
+## Important Notes
+
+**Validated height:** The `height` prop is validated as a CSS length string before being applied (CSS injection defense). Invalid values are ignored and the default Bootstrap height is used.
+
+**Safe values:** Each bar's percentage is clamped to 0–100. A `value` of `NaN` (or a non-finite number) renders safely as 0%. A `max` of `0` or less also renders as 0%.
+
+## 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,179 @@
+# 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` and attach the system-theme listener. **Call once at app startup, before mount.** Subsequent calls are no-ops while already initialized. |
+| `clearColorMode()` | `() => void` | Reset to `auto`, remove the `localStorage` key, and **keep the system listener attached** so auto mode stays reactive to OS theme changes. |
+| `onColorModeChange(cb)` | `(cb: (mode: ColorMode) => void) => () => void` | Register a callback that fires whenever the mode changes. Returns an **unsubscribe function** — call it to remove the callback and avoid leaks. 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' : 'secondary'"
+      :outline="colorMode !== option.value"
+      @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>
+```
+
+### Subscribing outside a component
+
+`onColorModeChange` is for non-reactive sinks (a hybrid app status bar, an analytics call). It returns an unsubscribe function — call it on teardown.
+
+```vue
+<script setup lang="ts">
+import { onUnmounted } from 'vue'
+import { useColorMode } from '@velkymx/vibeui'
+
+const { onColorModeChange } = useColorMode()
+
+const off = onColorModeChange((mode) => {
+  // e.g. sync the native status bar color in a Capacitor app
+})
+
+onUnmounted(off)
+</script>
+```
+
+### Resetting to system default
+
+`clearColorMode` removes the saved preference and returns to `auto`. The OS theme listener stays attached, so the app keeps tracking system theme changes afterward.
+
+```vue
+<script setup lang="ts">
+import { useColorMode } from '@velkymx/vibeui'
+
+const { clearColorMode } = useColorMode()
+</script>
+
+<template>
+  <VibeButton variant="secondary" outline @click="clearColorMode">
+    Use system default
+  </VibeButton>
+</template>
+```
+
+### 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; applying the theme simply does nothing when `document` is undefined. On the client, `initColorMode()` is the real init path that reads storage and attaches the listener.
+- **Invalid values** — `setColorMode` silently ignores any value that is not `'light'`, `'dark'`, or `'auto'`. No error is thrown.
+- **`initColorMode` is idempotent** — while initialized, repeat calls are no-ops and do not overwrite changes the user made after init. Calling `clearColorMode()` un-initializes the singleton, so a later `initColorMode()` can re-read storage.

package/docs/composables/use-form.md

@@ -0,0 +1,78 @@
+# useForm
+
+Multi-field form composable for managing groups of related fields with reactive values, errors, and touched state. For single-field validation use `useFormValidation` instead.
+
+## Quick start
+
+```ts
+import { useForm, validators } from '@velkymx/vibeui'
+
+const { fields, errors, touched, isDirty, isValid, validate, reset, markTouched } = useForm({
+  name: '',
+  email: '',
+  age: 0
+})
+
+const submit = async () => {
+  const result = await validate({
+    name: [validators.required('Name is required')],
+    email: [validators.required(), validators.email()]
+  })
+  if (!result.valid) return
+  // submit fields...
+}
+```
+
+## Why a separate composable?
+
+`useFormValidation` returns `{ value: Ref<T>, ... }` for a single field. In TypeScript templates the nested `value` ref does not auto-unwrap deeply — to keep template type-checking clean you must destructure once at script level (`const { value: name } = useFormValidation('')`).
+
+For multi-field forms, that destructure pattern multiplied per field becomes noisy. `useForm` returns a single reactive `fields` object: properties are auto-unwrapped reactively, so `{{ fields.name }}` works directly in templates with full TypeScript inference.
+
+## Returned API
+
+| Key | Type | Description |
+|---|---|---|
+| `fields` | `T` (reactive) | Mutable field values. `fields.name = 'x'` updates state. |
+| `errors` | `Record<keyof T, string>` (reactive) | Per-field error message. Empty string = no error. |
+| `touched` | `Record<keyof T, boolean>` (reactive) | Per-field touched flag. |
+| `isDirty` | `ComputedRef<boolean>` | True if any field differs from initial. |
+| `isValid` | `ComputedRef<boolean>` | `false` until the first `validate()` or `validateField()` call; then `true` if no field has an error. |
+| `values` | `ComputedRef<T>` | Snapshot of current field values. |
+| `validate(rules)` | `(rules) => Promise<{ valid, errors }>` | Run rules; populates `errors` map. |
+| `validateField(key, rule)` | `(key, rule) => Promise<string>` | Run rules for one field. |
+| `reset()` | `() => void` | Restore initial values, clear errors/touched. |
+| `markTouched(key)` | `(key) => void` | Mark single field touched. |
+| `markAllTouched()` | `() => void` | Mark every field touched (use on submit). |
+| `setField(key, value)` | `(key, value) => void` | Programmatic field update. |
+
+## Validation rules
+
+`validate(rules)` accepts a record mapping field keys to either a `ValidatorFunction` or a `ValidationRule[]` array. Reuse the built-in validators or pass arbitrary functions.
+
+```ts
+const result = await validate({
+  email: [validators.required(), validators.email()],
+  age:   [validators.min(18, 'Must be 18+')],
+  bio:   (value) => typeof value === 'string' && value.length <= 500
+})
+```
+
+## Single-field destructure pattern
+
+If you only have one field, prefer `useFormValidation` and destructure at the call site:
+
+```ts
+import { useFormValidation } from '@velkymx/vibeui'
+
+const { value: name, validationState, validationMessage, validate } = useFormValidation('')
+```
+
+In the template, top-level refs auto-unwrap:
+
+```vue
+<input v-model="name" />
+<span v-if="validationState === 'invalid'">{{ validationMessage }}</span>
+```
+
+Avoid `const form = useFormValidation('')` followed by `{{ form.value }}` in templates — the nested ref type does not unwrap cleanly under Volar.

package/docs/composables/use-position.md

@@ -0,0 +1,68 @@
+# usePosition
+
+JS positioning helper for anchoring one element relative to another. Wraps `@floating-ui/dom` with a natural-language anchor-point API similar to jQuery UI's `.position()`.
+
+Use this when CSS position utilities (`docs/utilities/position.md`) aren't enough — typically dynamic menus, callouts, picker overlays, drag ghosts.
+
+## Quick start
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { usePosition } from '@velkymx/vibeui'
+
+const anchor = ref(null)
+const target = ref(null)
+
+const { x, y, placement, update, stop } = usePosition(target, anchor, {
+  my: 'top center',
+  at: 'bottom center',
+  offset: [0, 8],
+  collision: 'flip+shift'
+})
+</script>
+
+<template>
+  <button ref="anchor">Anchor</button>
+  <div ref="target">I float below the button.</div>
+</template>
+```
+
+The composable applies `position`, `left`, and `top` styles directly to the target element.
+
+## Anchor points
+
+Both `my` and `at` accept any of the 9 natural-language points:
+
+```
+top start    | top center    | top end
+center start | center center | center end
+bottom start | bottom center | bottom end
+```
+
+`my` is the point on the target that is being placed; `at` is the point on the anchor that the target is aligned to.
+
+## Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `my` | anchor point | `'top center'` | Point on target |
+| `at` | anchor point | `'bottom center'` | Point on anchor |
+| `offset` | `[skid, distance]` | `[0, 0]` | Tweak placement |
+| `collision` | `'flip' \| 'shift' \| 'flip+shift' \| 'none'` | `'flip+shift'` | Viewport handling |
+| `autoUpdate` | `boolean` | `true` | Reposition on scroll/resize/mutation |
+| `strategy` | `'absolute' \| 'fixed'` | `'absolute'` | CSS positioning strategy |
+
+## Returns
+
+| Key | Type | Description |
+|---|---|---|
+| `x` | `Ref<number>` | Latest left coordinate |
+| `y` | `Ref<number>` | Latest top coordinate |
+| `placement` | `Ref<Placement>` | Resolved placement (post-flip) |
+| `update()` | `() => Promise<void>` | Recompute manually |
+| `stop()` | `() => void` | Tear down `autoUpdate` listeners |
+
+## Internal use
+
+`VibeDropdown`, `VibeTooltip`, `VibePopover`, `VibeDatePicker`, and `VibeAutocomplete` currently use Bootstrap's bundled Popper or component-local positioning rather than `usePosition`.

package/docs/composables/use-toast.md

@@ -0,0 +1,91 @@
+# useToast
+
+Global toast service. Call `useToast()` from anywhere and dispatch toast messages without managing a `<VibeToast>` component instance per call site. A single `<VibeToastHost />` mounted at the root renders the queue.
+
+## Setup
+
+Mount `<VibeToastHost />` once in your app shell:
+
+```vue
+<!-- App.vue -->
+<template>
+  <RouterView />
+  <VibeToastHost />
+</template>
+```
+
+## API
+
+```ts
+import { useToast } from '@velkymx/vibeui'
+
+const toast = useToast()
+```
+
+| Method | Variant | Notes |
+|--------|---------|-------|
+| `show(body, options?)` | `options.variant` | Generic |
+| `success(body, options?)` | `success` | |
+| `error(body, options?)` | `danger` | |
+| `warn(body, options?)` | `warning` | |
+| `info(body, options?)` | `info` | |
+| `dismiss(id)` | — | Remove a specific toast. Returns `true` if found. |
+| `clear()` | — | Remove all toasts |
+| `toasts` | — | Read-only reactive list |
+
+### Options
+
+```ts
+interface ToastShowOptions {
+  id?: string             // override auto-generated id
+  title?: string
+  variant?: Variant
+  placement?: ToastPlacement   // 'top-end' (default) etc.
+  autohide?: boolean      // default true
+  delay?: number          // ms, default 5000
+}
+```
+
+Each call returns the resolved `ToastSpec`, including the assigned `id` if you didn't provide one. Use it later to `dismiss(id)`.
+
+## Examples
+
+```ts
+const toast = useToast()
+
+toast.success('Saved successfully')
+toast.error('Could not save: network error', { delay: 8000 })
+
+const sticky = toast.warn('Long-running export…', { autohide: false })
+// later
+toast.dismiss(sticky.id)
+```
+
+### Programmatic clear on route change
+
+```ts
+import { useToast } from '@velkymx/vibeui'
+import { useRouter } from 'vue-router'
+
+const toast = useToast()
+const router = useRouter()
+router.afterEach(() => toast.clear())
+```
+
+## Coexistence with `<VibeToast>`
+
+The component-form `<VibeToast v-model="show">` still works — useful when a toast lives logically inside a single view. `useToast` is for app-wide notifications dispatched from composables, async handlers, or non-component code.
+
+> Mixing both in the same app produces two `.toast-container`s at the same placement (one from `<VibeToastHost>`, one per standalone `<VibeToast>`), which Bootstrap stacks side-by-side rather than vertically. If that's visually unwanted, pick one form per app.
+
+## SSR
+
+The toast queue is a module-level singleton. In SSR runtimes the same store is reused across requests; call `resetToastStoreForSSR()` from your server entry's per-request reset hook to avoid leaking one request's pending toasts into another's render output.
+
+```ts
+import { resetToastStoreForSSR } from '@velkymx/vibeui'
+
+// In your server's request handler:
+resetToastStoreForSSR()
+const app = createSSRApp(/* ... */)
+```