@velkymx/vibeui 0.9.0 → 1.0.2

package/llms.txt

@@ -0,0 +1,782 @@
+# VibeUI
+
+A Vue 3 component library that wraps Bootstrap 5.3. Every Bootstrap component is exposed as a typed Vue component with reactive props, v-model support, automatic Bootstrap JS lifecycle management, and zero manual DOM work required.
+
+**Package:** `@velkymx/vibeui`
+**Stack:** Vue 3 (Composition API) + Bootstrap 5.3 + TypeScript + Vite
+**Current version:** 1.0.0
+
+---
+
+## Key Mental Model
+
+VibeUI is a thin but complete abstraction layer over Bootstrap. It does three things:
+
+1. **Wraps Bootstrap CSS** — components apply the correct Bootstrap classes based on Vue props.
+2. **Abstracts Bootstrap JS** — interactive components (`Modal`, `Offcanvas`, `Toast`, `Tooltip`, `Popover`, `Accordion`, `Carousel`, `Collapse`, `Dropdown`) initialize, configure, and destroy their own Bootstrap JS instances via `onMounted`/`onBeforeUnmount`. You never touch `new bootstrap.Modal(el)`.
+3. **Adds Vue reactivity** — props drive Bootstrap re-initialization, `v-model` syncs visibility state, and Bootstrap's native events are re-emitted as Vue events.
+
+---
+
+## Building With VibeUI — start here
+
+This is the whole workflow: **load → use → leverage**. Follow it and you won't fight the library. (Detailed reference sections follow; the per-component docs are linked in the Documentation Index at the end — read a component's doc before using it.)
+
+### 1. Load
+
+```bash
+npm install @velkymx/vibeui bootstrap
+```
+```ts
+import { createApp } from 'vue'
+import VibeUI from '@velkymx/vibeui'
+import 'bootstrap/dist/css/bootstrap.min.css'   // YOU import the CSS
+createApp(App).use(VibeUI).mount('#app')         // registers every component + the v-vibe-tooltip directive
+```
+
+- **Import Bootstrap CSS yourself. Never import Bootstrap JS** — VibeUI loads it internally, on demand, per component.
+- `app.use(VibeUI)` registers everything globally. Or import by name for tree-shaking **and** full template type-checking: `import { VibeButton, VibeModal } from '@velkymx/vibeui'`.
+- **Non-bundler / UMD / CDN pages:** the internal `import('bootstrap')` is a bare specifier, so add an import map or interactive components silently fail:
+  `<script type="importmap">{ "imports": { "bootstrap": "https://esm.sh/bootstrap@5.3" } }</script>`
+
+### 2. Use — props, `v-model`, `:items`, slots
+
+- **Style with props:** `variant`, `size`, `outline` (boolean). For one-offs pass `class`/`style` — they merge onto the component root.
+- **Visibility is `v-model`:** `<VibeModal v-model="open" />` (also Offcanvas / Toast / Collapse / Alert). Do not call Bootstrap `show`/`hide`.
+- **Data-driven components take arrays — never hand-write the Bootstrap markup:**
+  - `:items` → `VibeNav`, `VibeDropdown`, `VibeListGroup`, `VibeBreadcrumb`, `VibeNavbarNav`
+  - `:items` (`CarouselItem[]`, each needs `src`) → `VibeCarousel`
+  - `:options` → `VibeFormSelect`
+  - `:bars` → `VibeProgress`
+  - `:columns` + `:items` → `VibeDataTable`
+- **Custom content uses slots:** `#item` (Nav/Dropdown/ListGroup), `#header`/`#footer`/`#image` (Card), `cell(<key>)` (DataTable), default slot for body.
+- **Imperative actions use the exposed methods via a template ref:** `modal.value?.show()` / `.hide()` / `.toggle()` / `.refresh()`. Drive the component — never reach around it to Bootstrap.
+
+### 3. Leverage
+
+- **Forms:** wrap controls in `<VibeFormGroup label="…">` (auto-links label + id + a11y). Validate with `useForm` + `validators` (`required`/`email`/`minLength`/…) and bind `:validation-state` / `:validation-message` per field.
+- **Composables:** `useToast` (global toasts; mount `<VibeToastHost/>` once), `useColorMode` (light/dark/auto), `useBreakpoints` (`isMobile`/`isTablet`/…), `useForm`, `usePosition`.
+- **Layout & sections:** `VibeContainer` / `VibeRow` (`:gutters`) / `VibeCol` (`:cols`/`:md`/…/`:order`); `VibeHero` for banner/hero sections; `VibeCard` (with `headerClass`/`bodyClass`/`#image`).
+- **Copy whole patterns** from the full-page templates in `examples/` (Album, Pricing, Checkout, Sign-in, Dashboard, Sidebars, Cover, Product, Carousel, Blog).
+
+### Read the doc first
+
+A component's exact props/events/slots live in its doc page (Documentation Index, bottom). **Read it before building — do not guess props or reverse-engineer from `dist/`.** The documented API is the source of truth.
+
+### Common mistakes — do NOT do these
+
+- ❌ `variant="outline-secondary"` → ✅ `variant="secondary" outline` (outline is a boolean prop)
+- ❌ `<VibeIcon name="house" />` → ✅ `<VibeIcon icon="house" />`
+- ❌ `<VibeCarousel :slides="…" />` → ✅ `<VibeCarousel :items="…" />` (each `CarouselItem` needs `src`)
+- ❌ `<vibe-card-body>`, `<vibe-list-group-item>`, `<vibe-nav-item>`, `<vibe-dropdown-item>`, `<vibe-progress-bar>` — **none of these exist.** Use the default / `#item` slot and `:items` / `:bars`.
+- ❌ hand-written `<ul class="nav">` / `<div class="card">` → ✅ `<VibeNav :items>` / `<VibeCard>`
+- ❌ `import 'bootstrap/dist/js/…'` or `new bootstrap.Modal()` → ✅ never; use props, `v-model`, and exposed methods
+- ❌ UMD/CDN page with no `bootstrap` import map → interactive components silently fall back / fail
+- ❌ guessing a prop name → ✅ open the component's doc page first
+
+---
+
+## Project Structure
+
+```
+vibeui/
+├── src/
+│   ├── index.ts                    # Package entry point — exports everything
+│   ├── types.ts                    # All shared TypeScript types
+│   ├── components/
+│   │   ├── index.ts                # Component registration + Vue plugin
+│   │   ├── VibeAlert.vue
+│   │   ├── VibeButton.vue          # Renders as <button>, <a>, or <router-link>; variant="link"
+│   │   ├── VibeBadge.vue
+│   │   ├── VibeButtonGroup.vue
+│   │   ├── VibeCard.vue              # headerClass/bodyClass/footerClass + #image slot
+│   │   ├── VibeHero.vue              # hero/banner section (variant/bordered/bgImage/gradient)
+│   │   ├── VibeCloseButton.vue
+│   │   ├── VibeSpinner.vue
+│   │   ├── VibePlaceholder.vue
+│   │   ├── VibeSkeleton.vue        # text/rect/circle/card loading placeholder
+│   │   ├── VibeContainer.vue       # Layout
+│   │   ├── VibeRow.vue
+│   │   ├── VibeCol.vue
+│   │   ├── VibeBreadcrumb.vue      # Data-driven: accepts items[]
+│   │   ├── VibeNav.vue
+│   │   ├── VibeNavbar.vue
+│   │   ├── VibeNavbarBrand.vue
+│   │   ├── VibeNavbarToggle.vue
+│   │   ├── VibeNavbarNav.vue
+│   │   ├── VibePagination.vue      # v-model:currentPage
+│   │   ├── VibeTabContent.vue
+│   │   ├── VibeTabs.vue            # tab container w/ content switching
+│   │   ├── VibeTab.vue             # child of VibeTabs
+│   │   ├── VibeListGroup.vue       # Data-driven: accepts items[]
+│   │   ├── VibeProgress.vue        # Data-driven: accepts bars[]
+│   │   ├── VibeStepper.vue         # multi-step wizard w/ guards
+│   │   ├── VibeAccordion.vue       # Bootstrap JS — auto init/destroy
+│   │   ├── VibeCollapse.vue        # Bootstrap JS — v-model
+│   │   ├── VibeDropdown.vue        # Bootstrap JS — data-driven items[]
+│   │   ├── VibeModal.vue           # Bootstrap JS — v-model, Teleport, size xl/fullscreen
+│   │   ├── VibeOffcanvas.vue       # Bootstrap JS — v-model, Teleport to body
+│   │   ├── VibeToast.vue           # Bootstrap JS — v-model OR no-container mode for host
+│   │   ├── VibeToastHost.vue       # hosts queued toasts from useToast()
+│   │   ├── VibeCarousel.vue        # Bootstrap JS — v-model (active slide index)
+│   │   ├── VibeTooltip.vue         # Bootstrap JS — reactive re-init on prop change
+│   │   ├── VibePopover.vue         # Bootstrap JS — reactive re-init on prop change
+│   │   ├── VibeScrollspy.vue
+│   │   ├── VibeIcon.vue            # Renders Bootstrap Icons (bi-*)
+│   │   ├── VibeDataTable.vue       # Generic <T>: sortable, searchable, paginated
+│   │   ├── VibeDatePicker.vue      # calendar popover, single + range, keyboard nav
+│   │   ├── VibeAutocomplete.vue    # search-as-you-type, sync or async source
+│   │   ├── VibeFileInput.vue       # file picker w/ drag-drop, accept enforcement
+│   │   ├── VibeSlider.vue          # single + range slider, keyboard, track click
+│   │   ├── VibeResizable.vue       # corner / edge handle resizing
+│   │   ├── VibeSortable.vue        # drag-to-reorder list (single-list)
+│   │   ├── VibeDraggable.vue       # free-drag source, pairs with VibeDroppable
+│   │   ├── VibeDroppable.vue       # drop zone, group / acceptGroups matching
+│   │   ├── dndStore.ts             # shared payload store between drag/drop
+│   │   ├── VibeFormInput.vue
+│   │   ├── VibeFormSelect.vue      # typed primitive option values
+│   │   ├── VibeFormTextarea.vue
+│   │   ├── VibeFormCheckbox.vue
+│   │   ├── VibeFormRadio.vue
+│   │   ├── VibeFormSwitch.vue
+│   │   ├── VibeFormSpinbutton.vue
+│   │   ├── VibeFormDatepicker.vue  # Native <input type=date> wrapper
+│   │   ├── VibeFormGroup.vue       # Context-aware — auto-links label to child input
+│   │   ├── VibeInputGroup.vue      # prepend/append slots; pairs with noWrapper inputs
+│   │   ├── VibeLink.vue
+│   │   ├── VibeFormWysiwyg.vue     # Quill 2.x — toolbar string presets
+│   │   ├── VibeChartLine.vue       # canvas line chart, smooth/fill, Bootstrap color cycling
+│   │   ├── VibeChartBar.vue        # canvas bar chart, grouped + stacked
+│   │   └── VibeChartPie.vue        # canvas pie chart, Bootstrap color cycling
+│   ├── composables/
+│   │   ├── useId.ts                # Generates unique IDs (SSR-safe)
+│   │   ├── useColorMode.ts         # Bootstrap color mode management (singleton)
+│   │   ├── useFormValidation.ts    # Field-level validation + built-in validators
+│   │   ├── useForm.ts              # multi-field form state w/ deep-clone reset
+│   │   ├── useToast.ts             # global toast service (use w/ <VibeToastHost />)
+│   │   ├── usePosition.ts          # floating-ui anchor positioning
+│   │   ├── useBackButton.ts        # Android hardware back button
+│   │   └── useBreakpoints.ts       # programmatic breakpoint detection
+│   └── directives/
+│       └── vTooltip.ts             # v-vibe-tooltip directive
+├── tests/
+│   ├── components/                 # Component tests (Vitest + @vue/test-utils)
+│   ├── composables/                # Composable tests
+│   ├── directives/                 # Directive tests
+│   └── mocks/bootstrap.ts          # Aliased in vite.config.ts test block
+├── docs/
+│   ├── README.md                   # Docs index — start here
+│   ├── components/                 # Per-component reference docs
+│   ├── forms/                      # Form + validation docs
+│   ├── directives/                 # v-vibe-tooltip
+│   ├── utilities/position.md       # Bootstrap position-* class reference
+│   └── composables/
+│       ├── color-mode.md
+│       ├── breakpoints.md
+│       ├── back-button.md
+│       ├── use-form.md
+│       ├── use-position.md
+│       └── use-toast.md
+├── examples/                       # Standalone HTML demo pages (load ../dist + CDNs; run `npm run build` first, or `npm run examples`)
+├── smoke/                          # manual smoke test page
+│   ├── index.html                  # `npm run smoke` builds + serves on :8001
+│   └── dist/                       # gitignored; populated by `npm run smoke`
+├── vite.config.ts                  # Also contains Vitest config
+└── llms.txt                        # This file
+```
+
+---
+
+## Installation & Setup
+
+```bash
+npm install @velkymx/vibeui bootstrap
+```
+
+```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'
+
+// Restore saved light/dark/auto preference before first render
+const { initColorMode } = useColorMode()
+initColorMode()
+
+createApp(App).use(VibeUI).mount('#app')
+```
+
+Bootstrap CSS must be imported by the consumer. VibeUI does **not** bundle it.
+Bootstrap JS is handled internally via dynamic import — do **not** import `bootstrap/dist/js/bootstrap.bundle.min.js` yourself.
+
+---
+
+## Exports
+
+Everything is exported from the package root:
+
+```ts
+// Plugin (registers all components + the v-vibe-tooltip directive)
+import VibeUI from '@velkymx/vibeui'
+app.use(VibeUI)
+
+// Individual components
+import {
+  VibeButton, VibeAlert, VibeModal, VibeOffcanvas,
+  VibeCard, VibeHero,
+  VibeFileInput, VibeSkeleton, VibeDatePicker, VibeAutocomplete,
+  VibeTabs, VibeTab, VibeStepper,
+  VibeSortable, VibeDraggable, VibeDroppable,
+  VibeResizable, VibeSlider,
+  VibeToast, VibeToastHost,
+  VibeChartLine, VibeChartBar, VibeChartPie
+  /* ... */
+} from '@velkymx/vibeui'
+
+// Composables
+import {
+  useColorMode, useFormValidation, validators,
+  useId, useBreakpoints, useBackButton,
+  useForm, useToast, usePosition, resetToastStoreForSSR
+} from '@velkymx/vibeui'
+
+// Directives (also registered globally by app.use(VibeUI))
+import { vTooltip } from '@velkymx/vibeui'
+
+// Types
+import type {
+  Variant, ButtonVariant, ColorMode, Size,
+  DataTableColumn, DataTableCellSlotProps,
+  FormSelectOption, FormSelectOptionValue,
+  ToastSpec, ToastShowOptions, UseToastReturn,
+  UsePositionOptions, UsePositionReturn,
+  ChartData, ChartDataset, ChartLegendPosition
+} from '@velkymx/vibeui'
+```
+
+---
+
+## Shared Types (`src/types.ts`)
+
+These types are used across all components. Always import from `@velkymx/vibeui`.
+
+```ts
+type Variant         = 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'light' | 'dark'
+type ButtonVariant   = Variant | 'link'                             
+type Size            = 'sm' | 'lg'
+type ColorMode       = 'light' | 'dark' | 'auto'
+type ButtonType      = 'button' | 'submit' | 'reset'
+type Tag             = 'div' | 'span' | 'section' | 'article' | 'nav' | 'aside' | 'header' | 'footer' | 'main'
+type TooltipPlacement = 'top' | 'bottom' | 'start' | 'end'   // also OffcanvasPlacement, NavbarPosition, ToastPlacement exist
+type ToastPlacement  = 'top-start' | 'top-center' | 'top-end' | 'middle-...' | 'bottom-...'
+type Direction       = 'up' | 'down' | 'start' | 'end'
+type SpinnerType     = 'border' | 'grow'
+type InputType       = 'text' | 'email' | 'password' | 'number' | 'tel' | 'url' | 'search' | 'date' | 'time' | ...
+type ValidationState = 'valid' | 'invalid' | null
+
+// Data-driven component item shapes
+interface BreadcrumbItem   { text, href?, to?, active? }
+interface NavItem          { text, href?, to?, target?, active?, disabled?, children? }
+//   target?: string — tab panel selector (e.g. '#panel-id') for tabs/pills mode with router-link items
+interface DropdownItem     { text?, href?, to?, active?, disabled?, divider?, header? }
+interface ListGroupItem    { text, href?, to?, active?, disabled?, variant? }
+interface AccordionItem    { id, title, content, show? }
+interface CarouselItem     { src, alt?, caption?, captionText?, active?, interval? }
+interface ProgressBar      { value, max?, variant?, striped?, animated?, label?, showValue? }
+
+// Generic over the row type T (default Record<string, unknown>)
+interface DataTableColumn<T>      { key: keyof T & string, label, sortable?, searchable?,
+                                    formatter?: (value: T[keyof T], row: T) => string | number, ... }
+interface DataTableCellSlotProps<T> { item: T, value: T[keyof T], index: number }
+
+// Form select primitive — accepts null / undefined / boolean
+type FormSelectOptionValue = string | number | boolean | null | undefined
+interface FormSelectOption  { value: FormSelectOptionValue, text, disabled? }
+
+// charts
+interface ChartDataset      { label: string, data: number[], color?: string }
+interface ChartData         { labels: string[], datasets: ChartDataset[] }
+type ChartLegendPosition    = 'top' | 'bottom' | 'none'
+
+// stepper / toast / position
+interface StepperStep       { label, description?, disabled?, icon? }
+interface ToastSpec         { id, title?, body, variant?, placement?, autohide?, delay? }
+interface ToastShowOptions  { id?, title?, variant?, placement?, autohide?, delay? }
+interface UsePositionOptions { my?, at?, offset?, collision?, autoUpdate?, strategy? }
+```
+
+---
+
+## Layout Components
+
+### VibeContainer
+
+Wraps Bootstrap's `.container`, `.container-fluid`, and `.container-{breakpoint}`.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `fluid` | `boolean \| ContainerType` | `false` | `false` = fixed, `true` = fluid, or breakpoint string |
+| `tag` | `Tag` | `'div'` | HTML element |
+
+```vue
+<VibeContainer>Fixed width</VibeContainer>
+<VibeContainer fluid>Full width</VibeContainer>
+<VibeContainer fluid="md">Fluid until md breakpoint</VibeContainer>
+```
+
+### VibeRow
+
+Bootstrap grid row with gutters, row-columns, and alignment.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tag` | `Tag` | `'div'` | HTML element |
+| `gutters` | `GutterSize` | — | Both-axis gutter (`0`-`5`) |
+| `guttersX` / `guttersY` | `GutterSize` | — | Per-axis gutter |
+| `gutters{X\|Y}{Sm\|Md\|Lg\|Xl\|Xxl}` | `GutterSize` | — | Responsive gutters |
+| `rowCols` | `RowColsSize` | — | Columns per row (`1`-`6`) |
+| `rowCols{Sm\|Md\|Lg\|Xl\|Xxl}` | `RowColsSize` | — | Responsive row-cols |
+| `alignItems` | `AlignItems` | — | Vertical alignment |
+| `justifyContent` | `JustifyContent` | — | Horizontal distribution |
+
+Types: `GutterSize = 0-5`, `RowColsSize = 1-6`, `AlignItems = 'start' | 'center' | 'end' | 'baseline' | 'stretch'`, `JustifyContent = 'start' | 'center' | 'end' | 'around' | 'between' | 'evenly'`
+
+### VibeCol
+
+Bootstrap grid column with responsive sizing, offsets, ordering, and alignment.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tag` | `Tag` | `'div'` | HTML element |
+| `cols` | `ColSize \| boolean` | — | Base width (`1`-`12`, `'auto'`, or `true`) |
+| `sm` / `md` / `lg` / `xl` / `xxl` | `ColSize \| boolean` | — | Responsive width |
+| `offset` | `Number` | — | Base offset (`0`-`11`) |
+| `offset{Sm\|Md\|Lg\|Xl\|Xxl}` | `Number` | — | Responsive offsets |
+| `order` | `OrderValue` | — | Visual order |
+| `order{Sm\|Md\|Lg\|Xl\|Xxl}` | `OrderValue` | — | Responsive order |
+| `alignSelf` | `AlignItems` | — | Individual vertical alignment |
+
+Types: `ColSize = 1-12 | 'auto'`, `OrderValue = 0-5 | 'first' | 'last'`
+
+When no sizing props are provided, `VibeCol` defaults to equal-width (`col` class).
+
+```vue
+<VibeContainer>
+  <VibeRow :gutters="3">
+    <VibeCol :cols="12" :md="6" :lg="4">Responsive</VibeCol>
+    <VibeCol :cols="12" :md="6" :lg="4">Responsive</VibeCol>
+    <VibeCol :cols="12" :md="12" :lg="4">Responsive</VibeCol>
+  </VibeRow>
+</VibeContainer>
+```
+
+---
+
+## Core Patterns
+
+### v-model for visibility
+
+All interactive components (Modal, Offcanvas, Toast, Collapse, Alert) use `v-model` to control open/closed state:
+
+```vue
+<script setup>
+const show = ref(false)
+</script>
+
+<template>
+  <VibeButton @click="show = true">Open</VibeButton>
+  <VibeModal v-model="show" title="Hello">Content</VibeModal>
+</template>
+```
+
+### Data-driven components
+
+Components like `VibeBreadcrumb`, `VibeListGroup`, `VibeDropdown`, `VibeAccordion`, `VibeCarousel`, and `VibeProgress` accept an `items` or `bars` array prop rather than manual slot markup:
+
+```vue
+<VibeBreadcrumb :items="[
+  { text: 'Home', href: '/' },
+  { text: 'Products', href: '/products' },
+  { text: 'Details', active: true }
+]" />
+```
+
+### VibeFormGroup — automatic label linking
+
+`VibeFormGroup` uses Vue's `provide`/`inject` to share a generated ID with child inputs. This means `id` and `label-for` are optional — the group handles accessibility automatically:
+
+```vue
+<VibeFormGroup label="Email Address">
+  <VibeFormInput v-model="email" type="email" />
+  <!-- label is automatically linked to input, no id needed -->
+</VibeFormGroup>
+```
+
+### Programmatic control (template ref)
+
+Visibility is normally driven by `v-model` — prefer that. When you must trigger an action imperatively (e.g. open a modal from a non-template handler), interactive components expose **safe methods** via a template ref. Use these, not the underlying Bootstrap object:
+
+- `VibeModal` / `VibeOffcanvas` / `VibeToast` → `show()`, `hide()`
+- `VibeDropdown` → `show()`, `hide()`, `toggle()`
+- `VibeCarousel` / `VibeAccordion` / `VibeNav` / `VibeScrollspy` → `refresh()`
+
+```vue
+<template>
+  <VibeModal ref="modal" v-model="show" title="Advanced" />
+</template>
+
+<script setup>
+const modal = useTemplateRef('modal')
+modal.value?.show()   // or modal.value?.hide()
+</script>
+```
+
+Drive every component through its props, `v-model`, slots, and these exposed methods. Do not reach around the component to Bootstrap's own JS — VibeUI owns that lifecycle, and bypassing it desyncs component state.
+
+### Teleportation
+
+`VibeModal`, `VibeOffcanvas`, and `VibeToast` render via `<Teleport to="body">` by default. This prevents CSS stacking context issues. No configuration needed.
+
+### Toast service
+
+Mount `<VibeToastHost />` once at the app root, then dispatch from anywhere via the `useToast` composable. Toasts at the same placement stack inside one shared `.toast-container`.
+
+```vue
+<!-- App.vue -->
+<template>
+  <RouterView />
+  <VibeToastHost />
+</template>
+```
+
+```ts
+import { useToast } from '@velkymx/vibeui'
+const toast = useToast()
+toast.success('Saved')
+toast.error('Network error', { delay: 8000 })
+const sticky = toast.warn('Long export…', { autohide: false })
+toast.dismiss(sticky.id)
+```
+
+The component-form `<VibeToast v-model="show">` still works for app-local toasts.
+
+### Drag & drop
+
+Two layers depending on use case:
+
+- **Single-list reorder** → `<VibeSortable v-model="items">` with a scoped slot per item.
+- **Cross-list moves** (kanban, builders) → `<VibeDraggable :payload>` paired with `<VibeDroppable @drop>`. Match by `group` (default `'default'`) or `acceptGroups` whitelist. Payloads pass through a shared module store, so they can be typed objects, refs, or non-serializable values — no DataTransfer string round-trip.
+
+A document-level `dragend` / `drop` listener installed by `setActiveDrag` clears stale payloads if a drag aborts (escape, page nav, browser bug).
+
+### Calendar popover
+
+`VibeDatePicker` is a fully custom calendar (distinct from `VibeFormDatepicker` which wraps `<input type=date>`). ISO `YYYY-MM-DD` model, `range` mode emits `[start, end]`, full keyboard nav (arrows / PageUp+Down / Home+End / Enter / Escape), click-outside-to-close.
+
+```vue
+<VibeDatePicker v-model="due" :min="'2026-01-01'" :max="'2026-12-31'" />
+<VibeDatePicker v-model="window" range />
+```
+
+### Floating UI anchoring
+
+For ad-hoc anchoring when CSS position utilities aren't enough. Wraps `@floating-ui/dom` with a natural-language anchor-point API.
+
+```ts
+const { x, y, placement, update, stop } = usePosition(targetRef, anchorRef, () => ({
+  my: 'top center',
+  at: 'bottom center',
+  offset: [0, 8],
+  collision: 'flip+shift'
+}))
+```
+
+Pass options as a getter to keep `my` / `at` reactive.
+
+---
+
+## Composables
+
+### useColorMode
+
+Singleton. Sets `data-bs-theme` on `<html>`. Persists to `localStorage`.
+
+```ts
+const { colorMode, setColorMode, toggleColorMode, initColorMode } = useColorMode()
+
+// colorMode: Ref<'light' | 'dark' | 'auto'>
+// Call initColorMode() once in main.ts — subsequent calls are no-ops
+// toggleColorMode() cycles light → dark → auto → light
+```
+
+Full docs: `docs/composables/color-mode.md`
+
+### useFormValidation
+
+Per-field validation with reactive state.
+
+```ts
+const email = useFormValidation('')
+
+// email.value          — Ref<string>
+// email.validationState — Ref<'valid' | 'invalid' | null>
+// email.validationMessage — Ref<string>
+// email.isValid / email.isInvalid — computed booleans
+// email.isDirty / email.isTouched / email.isValidating — Ref<boolean>
+// await email.validate(rules)
+// email.reset()
+```
+
+### validators (built-in)
+
+```ts
+import { validators } from '@velkymx/vibeui'
+
+validators.required(message?)
+validators.email(message?)
+validators.minLength(n, message?)
+validators.maxLength(n, message?)
+validators.min(n, message?)
+validators.max(n, message?)
+validators.pattern(regex, message?)
+validators.url(message?)
+validators.async(fn: (value) => Promise<boolean | string>)
+```
+
+Validators return `true` on pass, or a string error message on failure.
+Full docs: `docs/forms/validation.md`
+
+### useId
+
+Generates a unique, SSR-safe ID string. Used internally by form components.
+
+```ts
+const id = useId('prefix') // → 'prefix-3-7'
+```
+
+### useForm
+
+Multi-field form state with reactive `fields`, `errors`, `touched` maps. `fields` is a Vue `reactive` so its properties auto-unwrap in templates.
+
+```ts
+const { fields, errors, touched, isDirty, isValid, validate, validateField, reset, markAllTouched, setField, values }
+  = useForm({ name: '', email: '', age: 0 })
+
+const result = await validate({
+  name:  [validators.required('Name is required')],
+  email: [validators.required(), validators.email()],
+  age:   [validators.min(18, 'Must be 18+')]
+})
+// result.valid: boolean
+// result.errors: Partial<Record<K, string>>
+```
+
+`isValid` is `false` until the first `validate()` or `validateField()` call; then `true` if no field has an error. Use this to guard submit buttons without showing errors on a fresh form.
+
+`reset` deep-clones the initial values back in (works for object / array fields). Dirty tracking uses structural compare (`JSON.stringify`) so non-primitive fields don't read as permanently dirty.
+
+For **single-field** validation, prefer `useFormValidation` (older API) and destructure at the call site to keep templates clean.
+
+### useToast
+
+```ts
+const { show, success, error, warn, info, dismiss, clear, toasts } = useToast()
+
+success(body, { id?, title?, placement?, autohide?, delay? })
+toasts // DeepReadonly<ToastSpec[]>
+```
+
+The store is a module singleton (per app per JS realm). For SSR, call `resetToastStoreForSSR()` from the server entry's per-request reset hook. Multi-app browser usage shares the same queue — use the component form for app-local notifications.
+
+### usePosition
+
+```ts
+const { x, y, placement, update, stop } = usePosition(target, anchor, options)
+```
+
+`options` accepts a plain object (static) **or** a getter `() => UsePositionOptions` (reactive). The getter is re-evaluated on every `update()` and is part of the watch dependency set.
+
+The composable owns `position` / `left` / `top` on the target element while alive. `stop()` (and `onBeforeUnmount`) restore the previous inline values.
+
+### useBreakpoints
+
+```ts
+const { isXs, isSm, isMd, isLg, isXl, isXxl, isMobile, isTablet } = useBreakpoints()
+```
+
+Reactive booleans driven by `window.matchMedia` against Bootstrap's standard breakpoints.
+
+### useBackButton
+
+Hooks Android's hardware back button (Capacitor / Cordova) into Vue components — `VibeModal` and `VibeOffcanvas` register their close handlers automatically.
+
+---
+
+## Directives
+
+### v-vibe-tooltip
+
+Inline tooltip directive registered globally by `app.use(VibeUI)`.
+
+```vue
+<button v-vibe-tooltip="'Save changes'">Save</button>
+<span v-vibe-tooltip="{ title: 'Open in new tab', placement: 'right', html: true }">↗</span>
+```
+
+Re-creates the underlying Bootstrap Tooltip when `placement` / `trigger` / `html` change; title-only changes use the cheap `setContent` path. Touch devices auto-swap `hover focus` → `click`.
+
+For component-form usage with rich slot content, use `<VibeTooltip>`.
+
+---
+
+## Testing
+
+Two Vitest projects share one Vite pipeline:
+- **`unit`** — `@vue/test-utils` + happy-dom, with **Bootstrap JS mocked** (`tests/mocks/bootstrap.ts`, aliased only in this project). Fast.
+- **`browser`** — real headless Chromium (Playwright provider) running the **real** Bootstrap JS + Quill — the integration paths happy-dom can't reach.
+
+```bash
+npm run test:run      # unit suite (what CI runs)
+npm run test:browser  # browser suite, real Chromium
+npm run test:all      # both projects
+npm run test:examples # Playwright: load every examples/*.html and assert it mounts (needs CDN network)
+```
+
+So unit tests never trigger real Bootstrap JS; the browser tests deliberately do.
+
+**Pattern for component tests:**
+```ts
+import { describe, it, expect } from 'vitest'
+import { mount } from '@vue/test-utils'
+import VibeButton from '../../src/components/VibeButton.vue'
+
+it('applies variant class', () => {
+  const wrapper = mount(VibeButton, { props: { variant: 'danger' } })
+  expect(wrapper.classes()).toContain('btn-danger')
+})
+```
+
+**Pattern for composable tests:**
+- Use `_resetColorMode()` (exported from `useColorMode.ts`, not from the package index) to reset singleton state between tests.
+- Use `vi.stubGlobal` + `try/finally` for environment mocking (e.g. SSR simulation).
+
+---
+
+## Build
+
+```bash
+npm run build   # outputs to dist/ as ESM + UMD + type declarations
+npm run dev     # Vite dev server for the src/App.vue playground
+```
+
+Build output:
+- `dist/vibeui.es.js` — ESM for bundlers
+- `dist/vibeui.umd.js` — UMD for CDN / script tag usage
+- `dist/vibeui.d.ts` — TypeScript declarations
+
+Vue and Bootstrap are **external** — not bundled. Consumers provide their own. `@floating-ui/dom` is a runtime dependency (used by `usePosition`).
+
+### Smoke testing
+
+```bash
+npm run smoke   # rebuilds the lib + serves smoke/ on :8001
+```
+
+`smoke/index.html` mounts every component with realistic data and a status badge for runtime errors. Bootstrap, Quill, and Vue are loaded from CDN via an importmap (Bootstrap and Quill via `esm.sh` so transitive deps like `@popperjs/core` resolve automatically).
+
+---
+
+## Adding a New Component
+
+1. Create `src/components/VibeFoo.vue`
+2. Follow the pattern: `defineProps` with typed props, `computed` for class assembly, `<component :is="tag">` if the element type is configurable
+3. Export from `src/components/index.ts` (named export + `app.component(...)` registration)
+4. Export from `src/index.ts` (re-export via `export * from './components'` covers it automatically)
+5. Add types to `src/types.ts` if new shared types are needed
+6. Add tests in `tests/components/VibeFoo.test.ts`
+7. Add docs in `docs/components/{category}/foo.md`
+
+If the component uses Bootstrap JS:
+- Dynamically import: `const { Foo } = await import('bootstrap')`
+- Initialize in `onMounted`, dispose in `onBeforeUnmount`
+- Watch functional props and call `instance.dispose()` + reinitialize on change
+- Expose safe imperative methods (`show()` / `hide()` / `refresh()`) via `defineExpose`. Follow the existing convention of also exposing the raw instance only under the `_unsafe_bsInstance` name (escape hatch — never a plain `bsInstance`)
+
+---
+
+## Canvas Charts
+
+Three chart components drawn directly on `<canvas>` — no Chart.js or other dependency.
+
+```vue
+<VibeChartLine :data="data" smooth fill legend="top" />
+<VibeChartBar  :data="data" stacked />
+<VibeChartPie  :data="data" />
+```
+
+All three share the same `ChartData` shape:
+
+```ts
+const data: ChartData = {
+  labels: ['Jan', 'Feb', 'Mar'],
+  datasets: [
+    { label: 'Revenue', data: [100, 150, 130], color: '#0d6efd' }  // color optional
+  ]
+}
+```
+
+When `color` is omitted, colors cycle through Bootstrap CSS variables (`--bs-primary`, `--bs-success`, `--bs-danger`, ...) from the component's computed style — automatically matching your Bootstrap theme and dark mode.
+
+| Prop | Line | Bar | Pie | Description |
+|------|------|-----|-----|-------------|
+| `data` | ✓ | ✓ | ✓ | `ChartData` — required |
+| `legend` | ✓ | ✓ | ✓ | `'top' \| 'bottom' \| 'none'` (default `'bottom'`) |
+| `height` | ✓ | ✓ | ✓ | Number/String px or `'auto'` (default). Line/Bar → 16:9, Pie → 1:1 |
+| `showAxes` | ✓ | ✓ | — | Show X/Y axes (default `true`) |
+| `showGrid` | ✓ | ✓ | — | Show grid lines (default `true`) |
+| `smooth` | ✓ | — | — | Bezier curves instead of straight lines |
+| `fill` | ✓ | — | — | Fill area under line |
+| `stacked` | — | ✓ | — | Stack datasets instead of grouping |
+
+All charts are responsive via `ResizeObserver`, render at device pixel ratio for crisp HiDPI output, and show hover tooltips on data points/slices/bars.
+
+---
+
+## What VibeUI Does NOT Do
+
+- Does not bundle Bootstrap CSS or JS
+- Does not require Bootstrap Icons (optional peer dep for `VibeIcon`)
+- Does not require Vue Router (optional peer dep for `href`/`to` props on `VibeButton`)
+- Does not require QuillJS (optional peer dep for `VibeFormWysiwyg`)
+- Does not provide a theme system beyond Bootstrap's `data-bs-theme` color modes
+
+## Documentation Index
+
+Per-component and per-API reference. **Read the relevant page before building with a component.**
+
+**Start here:** [docs/README.md](docs/README.md) · [Getting started / starter template](docs/getting-started/starter-template.md) · [Versioning & stability policy](docs/versioning.md)
+
+**Layout:** [VibeContainer](docs/components/layout/container.md) · [VibeRow](docs/components/layout/row.md) · [VibeCol](docs/components/layout/col.md)
+
+**Core:** [VibeAlert](docs/components/core/alert.md) · [VibeBadge](docs/components/core/badge.md) · [VibeButton](docs/components/core/button.md) · [VibeButtonGroup](docs/components/core/button-group.md) · [VibeCloseButton](docs/components/core/close-button.md) · [VibeLink](docs/components/core/link.md) · [VibePlaceholder](docs/components/core/placeholder.md) · [VibeSkeleton](docs/components/core/skeleton.md) · [VibeSpinner](docs/components/core/spinner.md)
+
+**Card / Hero / List:** [VibeCard](docs/components/card/card.md) · [VibeHero](docs/components/hero/hero.md) · [VibeListGroup](docs/components/list/list-group.md)
+
+**Navigation:** [VibeBreadcrumb](docs/components/navigation/breadcrumb.md) · [VibeNav](docs/components/navigation/nav.md) · [VibeNavbar](docs/components/navigation/navbar.md) · [VibePagination](docs/components/navigation/pagination.md)
+
+**Interactive:** [VibeAccordion](docs/components/interactive/accordion.md) · [VibeCarousel](docs/components/interactive/carousel.md) · [VibeCollapse](docs/components/interactive/collapse.md) · [VibeDatePicker](docs/components/interactive/date-picker.md) · [VibeDraggable / VibeDroppable](docs/components/interactive/draggable.md) · [VibeDropdown](docs/components/interactive/dropdown.md) · [VibeModal](docs/components/interactive/modal.md) · [VibeOffcanvas](docs/components/interactive/offcanvas.md) · [VibeResizable](docs/components/interactive/resizable.md) · [VibeSlider](docs/components/interactive/slider.md) · [VibeSortable](docs/components/interactive/sortable.md) · [VibeStepper](docs/components/interactive/stepper.md) · [VibeTabs / VibeTab](docs/components/interactive/tabs.md) · [VibeToast](docs/components/interactive/toast.md)
+
+**Advanced:** [VibePopover](docs/components/advanced/popover.md) · [VibeScrollspy](docs/components/advanced/scrollspy.md) · [VibeTooltip](docs/components/advanced/tooltip.md)
+
+**Data & Charts:** [VibeDataTable](docs/components/data/datatable.md) · [VibeChartBar](docs/components/charts/chart-bar.md) · [VibeChartLine](docs/components/charts/chart-line.md) · [VibeChartPie](docs/components/charts/chart-pie.md)
+
+**Progress:** [VibeProgress](docs/components/progress/progress.md)
+
+**Forms:** [overview](docs/forms/README.md) · [VibeAutocomplete](docs/forms/autocomplete.md) · [VibeFileInput](docs/forms/file-input.md) · [VibeFormCheckbox](docs/forms/form-checkbox.md) · [VibeFormDatepicker](docs/forms/form-datepicker.md) · [VibeFormGroup](docs/forms/form-group.md) · [VibeFormInput](docs/forms/form-input.md) · [VibeFormRadio](docs/forms/form-radio.md) · [VibeFormSelect](docs/forms/form-select.md) · [VibeFormSpinbutton](docs/forms/form-spinbutton.md) · [VibeFormSwitch](docs/forms/form-switch.md) · [VibeFormTextarea](docs/forms/form-textarea.md) · [VibeFormWysiwyg](docs/forms/form-wysiwyg.md) · [VibeInputGroup](docs/forms/input-group.md) · [Validation & useForm](docs/forms/validation.md)
+
+**Composables:** [useBackButton](docs/composables/back-button.md) · [useBreakpoints](docs/composables/breakpoints.md) · [useColorMode](docs/composables/color-mode.md) · [useForm](docs/composables/use-form.md) · [usePosition](docs/composables/use-position.md) · [useToast](docs/composables/use-toast.md)
+
+**Directives:** [v-vibe-tooltip](docs/directives/v-tooltip.md)
+
+**Utilities:** [Position utility classes](docs/utilities/position.md)