@velkymx/vibeui 0.8.2 → 1.0.2

package/docs/components/data/datatable.md

@@ -19,8 +19,22 @@ Powerful data table component with search, sorting, and pagination - similar to
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `items` | `Array<any>` | `[]` | Array of data objects to display |
-| `columns` | `DataTableColumn[]` | Required | Column definitions |
+| `items` | `T[]` | `[]` | Array of data objects to display |
+| `columns` | `DataTableColumn<T>[]` | Required | Column definitions |
+| `rowKey` | `String` | `'id'` | Property name used as the unique key for each row. **Recommended** — set it to a unique field in your data (e.g. `'id'`, `'uuid'`) so Vue tracks rows correctly across sorting, filtering, and pagination. Falls back to a positional key (with a DEV warning) when missing. |
+
+> **Typing tip**: `DataTableColumn` is generic over your row type. For full slot-prop / formatter typing, annotate the column array:
+>
+> ```ts
+> import type { DataTableColumn } from '@velkymx/vibeui'
+> interface User { id: number; name: string; active: boolean }
+> const columns: DataTableColumn<User>[] = [
+>   { key: 'name', label: 'Name' },              // key narrowed to keyof User
+>   { key: 'active', label: 'Active', formatter: v => v ? 'Yes' : 'No' }
+> ]
+> ```
+>
+> Without the annotation, `T` defaults to `Record<string, unknown>` and slot props arrive as `unknown`.
 
 ### Table Styling Props
 
@@ -89,11 +103,13 @@ interface DataTableColumn {
   formatter?: (value: any, row: any) => string | number  // Custom formatter
   class?: string                // CSS class for td
   headerClass?: string          // CSS class for th
-  thStyle?: Record<string, string>  // Inline styles for th
-  tdStyle?: Record<string, string>  // Inline styles for td
+  thStyle?: Record<string, string>  // Inline styles for th (sanitized — see note)
+  tdStyle?: Record<string, string>  // Inline styles for td (sanitized — see note)
 }
 ```
 
+> **`thStyle` / `tdStyle` are sanitized.** Both objects are filtered against a safe CSS-property allowlist before being applied, as a defense against CSS injection (data exfiltration / UI spoofing) when column config comes from an API or untrusted source. Properties outside the allowlist are dropped.
+
 ## Events
 
 | Event | Payload | Description |
@@ -102,7 +118,7 @@ interface DataTableColumn {
 | `update:perPage` | `Number` | Emitted when per-page changes |
 | `update:sortBy` | `String` | Emitted when sort column changes |
 | `update:sortDesc` | `Boolean` | Emitted when sort direction changes |
-| `row-clicked` | `(item, index)` | Emitted when row is clicked |
+| `row-clicked` | `(item, globalIndex)` | Emitted when a row is clicked. `globalIndex` is the index within the full filtered/sorted dataset, not the current page. Only emitted when a `@row-clicked` listener is attached (rows show a pointer cursor in that case). |
 
 ## Slots
 
@@ -133,10 +149,12 @@ const items = [
 </script>
 
 <template>
-  <VibeDataTable :columns="columns" :items="items" />
+  <VibeDataTable :columns="columns" :items="items" row-key="id" />
 </template>
 ```
 
+> Always pass `row-key` pointing at a unique field (here `id`) so Vue keys rows stably across sorting, filtering, and pagination.
+
 ### With Bootstrap Styling
 
 ```vue
@@ -232,8 +250,8 @@ const perPage = ref(25)
 const sortBy = ref('name')
 const sortDesc = ref(false)
 
-const handleRowClick = (item, index) => {
-  console.log('Clicked row:', item, index)
+const handleRowClick = (item, globalIndex) => {
+  console.log('Clicked row:', item, globalIndex)
 }
 </script>
 
@@ -241,6 +259,7 @@ const handleRowClick = (item, index) => {
   <VibeDataTable
     :columns="columns"
     :items="items"
+    row-key="id"
     v-model:current-page="currentPage"
     v-model:per-page="perPage"
     v-model:sort-by="sortBy"
@@ -410,7 +429,7 @@ const columns = [
 ## Tips
 
 1. **Large Datasets**: For datasets with 1000+ rows, consider server-side pagination
-2. **Performance**: Use `:key` on items for better Vue reactivity
+2. **Stable keys**: Set the `row-key` prop to a unique field in your data for correct behavior during sorting/filtering and best reactivity
 3. **Search Debounce**: Adjust `searchDebounce` prop for performance with large datasets
-4. **Custom Styling**: Use column `class`, `headerClass`, `thStyle`, `tdStyle` for styling
+4. **Custom Styling**: Use column `class`, `headerClass`, `thStyle`, `tdStyle` for styling (style objects are sanitized to a safe property allowlist)
 5. **Slots**: Use slots for complex cell rendering (badges, buttons, images, etc.)

package/docs/components/hero/hero.md

@@ -0,0 +1,64 @@
+# VibeHero
+
+A hero / banner section. Renders a `<section>` with consistent padding, an inner container, and content alignment — covering the Bootstrap 5.3 hero patterns (centered, two-column, dark, bordered) plus full-bleed background image / gradient heroes.
+
+```vue
+<VibeHero variant="dark" text-variant="light">
+  <h1 class="display-4 fw-bold">Build faster with VibeUI</h1>
+  <p class="lead">A modern Vue 3 component library for Bootstrap 5.3.</p>
+  <VibeButton variant="primary" size="lg">Get started</VibeButton>
+</VibeHero>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `Variant` | `undefined` | Background color → `bg-{variant}` (same vocabulary as `VibeCard`) |
+| `textVariant` | `Variant` | `undefined` | Text color → `text-{variant}` |
+| `border` | `Variant` | `undefined` | Adds `border border-{variant} rounded-3` (the bordered-hero pattern) |
+| `align` | `'start' \| 'center' \| 'end'` | `'center'` | Content alignment → `text-{align}` |
+| `fluid` | `Boolean \| ContainerType` | `false` | Inner container width (same vocabulary as `VibeContainer`) |
+| `minHeight` | `String` | `undefined` | Sanitized via `safeLength`; when set, content is vertically centered |
+| `bgImage` | `String` | `undefined` | Full-bleed background image URL; sanitized via `safeHref` (blocks `javascript:`/`data:`), rendered `cover`/`center` |
+| `overlay` | `Boolean \| String` | `false` | Darkening layer over `bgImage` for legibility — `true` for a default dark scrim, or a CSS color (sanitized via `safeColor`) |
+| `gradient` | `String` | `undefined` | CSS gradient background (e.g. `linear-gradient(135deg, #667eea, #764ba2)`); validated to `*-gradient(...)` only — no `url()`/`expression()` |
+| `tag` | `Tag` | `'section'` | Root element tag |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Hero content. You supply the inner layout (a centered column, or a `VibeRow`/`VibeCol` split). |
+
+## Examples
+
+**Centered (Bootstrap "centered hero")**
+
+```vue
+<VibeHero>
+  <VibeCol :lg="7" class="mx-auto">
+    <h1 class="display-3 fw-bold">Photo Gallery</h1>
+    <p class="lead">Curated photography from around the world.</p>
+  </VibeCol>
+</VibeHero>
+```
+
+**Two-column with gradient**
+
+```vue
+<VibeHero gradient="linear-gradient(135deg, #667eea 0%, #764ba2 100%)" align="start" class="text-white">
+  <VibeRow class="align-items-center">
+    <VibeCol :lg="6"><h1 class="display-3 fw-bold">Headline</h1></VibeCol>
+    <VibeCol :lg="6"><img src="/demo.png" class="img-fluid rounded-4 shadow-lg"></VibeCol>
+  </VibeRow>
+</VibeHero>
+```
+
+**Full-bleed image with overlay**
+
+```vue
+<VibeHero bg-image="/banner.jpg" overlay min-height="400px" class="text-white">
+  <h1 class="display-3 fw-bold">Welcome</h1>
+</VibeHero>
+```

package/docs/components/interactive/accordion.md

@@ -31,6 +31,7 @@ interface AccordionItem {
 | `shown` | `id` | Emitted when an item is fully shown |
 | `hide` | `id` | Emitted when an item starts hiding |
 | `hidden` | `id` | Emitted when an item is fully hidden |
+| `component-error` | `ComponentError` | Emitted if Bootstrap JS fails to load |
 
 ## Slots
 
@@ -75,12 +76,40 @@ Items stay open when another item is opened:
 </template>
 ```
 
+### Custom Title and Content (Slots)
+
+Both the `title` and `content` slots receive `{ item, index }` so you can render rich markup while still driving the accordion from the `items` array:
+
+```vue
+<template>
+  <VibeAccordion :items="accordionItems">
+    <template #title="{ item }">
+      <strong>{{ item.title }}</strong>
+    </template>
+    <template #content="{ item }">
+      <div v-html="item.content" />
+    </template>
+  </VibeAccordion>
+</template>
+
+<script setup>
+const accordionItems = [
+  { id: 'one', title: 'Item #1', content: '<p>Rich <em>HTML</em> body.</p>', show: true },
+  { id: 'two', title: 'Item #2', content: '<p>Second body.</p>' }
+]
+</script>
+```
+
 ## Important Notes
 
 **Automatic Initialization:** This component automatically initializes Bootstrap's Collapse functionality for each item when it is mounted, provided that Bootstrap's JavaScript is available in your project.
 
 **Reactivity:** The `show` property in the `AccordionItem` objects is watched. Changing it in your parent state will trigger the corresponding Bootstrap transition.
 
+**Item ids:** Each `item.id` (and the accordion `id`) must contain only alphanumeric characters, hyphens, and underscores — Bootstrap's internal `querySelector` breaks on CSS-special characters. In dev mode an unsafe id logs a console warning.
+
+**Escape Hatch:** The exposed `_unsafe_bsInstances` template ref is a `Map` of the underlying Bootstrap Collapse instances keyed by item id. It is **not** part of the stable API — calling `dispose()` or other lifecycle methods on them directly **will** break the component. To re-sync after manual DOM changes, call the exposed `refresh()` method instead.
+
 ## Bootstrap CSS Classes
 
 - `.accordion`

package/docs/components/interactive/carousel.md

@@ -38,8 +38,9 @@ interface CarouselItem {
 | Event | Payload | Description |
 |-------|---------|-------------|
 | `update:modelValue` | `Number` | Emitted when the active slide changes |
-| `slide` | - | Emitted when slide transition starts |
-| `slid` | - | Emitted when slide transition completes |
+| `slide` | `Event` | Emitted when slide transition starts (Bootstrap `slide.bs.carousel`) |
+| `slid` | `Event` | Emitted when slide transition completes (Bootstrap `slid.bs.carousel`) |
+| `component-error` | `ComponentError` | Emitted if Bootstrap JS fails to load |
 
 ## Slots
 
@@ -66,7 +67,10 @@ interface CarouselItem {
 <script setup>
 import { ref } from 'vue'
 const currentSlide = ref(0)
-const carouselItems = [...]
+const carouselItems = [
+  { src: '/img/slide-1.jpg', caption: 'First slide', captionText: 'Intro copy' },
+  { src: '/img/slide-2.jpg', caption: 'Second slide' }
+]
 </script>
 ```
 
@@ -76,13 +80,24 @@ const carouselItems = [...]
 <template>
   <VibeCarousel :items="carouselItems" />
 </template>
+
+<script setup>
+const carouselItems = [
+  { src: '/img/slide-1.jpg', alt: 'A scenic view' },
+  { src: '/img/slide-2.jpg', alt: 'A city street' }
+]
+</script>
 ```
 
 ## Important Notes
 
 **Automatic Initialization:** This component automatically initializes Bootstrap's Carousel functionality when it is mounted, provided that Bootstrap's JavaScript is available in your project.
 
-**Instance Exposure:** You can access the underlying Bootstrap instance via template ref using the `bsInstance` property.
+**`item.src` is required:** Every slide is an image slide — each item must provide a `src`. Captions and alt text are optional (an accessible fallback `alt` is generated from `alt` → `caption` → `captionText` → `"Carousel slide N"`).
+
+**Empty items:** An empty `items` array is handled gracefully — the carousel simply renders no slides.
+
+**Escape Hatch:** The exposed `_unsafe_bsInstance` template ref gives raw access to the underlying Bootstrap Carousel instance. It is **not** part of the stable API — calling `dispose()` or other lifecycle methods on it directly **will** break the component. To re-initialize after manual changes, call the exposed `refresh()` method instead.
 
 ## Bootstrap CSS Classes
 

package/docs/components/interactive/collapse.md

@@ -21,6 +21,7 @@ Toggle visibility of content with smooth transitions.
 | `shown` | - | Emitted when collapse is fully shown |
 | `hide` | - | Emitted when collapse starts hiding |
 | `hidden` | - | Emitted when collapse is fully hidden |
+| `component-error` | `ComponentError` | Emitted if Bootstrap JS fails to load |
 
 ## Slots
 
@@ -93,9 +94,9 @@ When used inside a `VibeNavbar`, add `is-nav` to get the `navbar-collapse` class
 
 **Automatic Initialization:** This component automatically initializes Bootstrap's Collapse functionality when it is mounted, ensuring that smooth sliding transitions are used.
 
-**State Synchronization:** Refactored to ensure that clicking a toggle (like `VibeNavbarToggle`) updates both Vue's internal state and Bootstrap's JavaScript instance simultaneously.
+**State Synchronization:** Clicking a toggle (like `VibeNavbarToggle`) updates both Vue's `v-model` state and Bootstrap's JavaScript instance simultaneously, so the two never drift out of sync.
 
-**Instance Exposure:** You can access the underlying Bootstrap instance via template ref using the `bsInstance` property.
+**Pre-init fallback:** Before Bootstrap JS finishes loading, an open collapse (`v-model` true) still renders visible via the `.show` class; once Bootstrap is ready it takes ownership of the class.
 
 ## Bootstrap CSS Classes
 

package/docs/components/interactive/date-picker.md

@@ -0,0 +1,78 @@
+# VibeDatePicker
+
+Calendar-popover datepicker with single + range mode. Distinct from `VibeFormDatepicker`, which is a thin wrapper around `<input type="date">`.
+
+Values are ISO `YYYY-MM-DD` strings.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `modelValue` | `String \| null \| [String\|null, String\|null]` | `null` | ISO date(s) (v-model) |
+| `range` | `Boolean` | `false` | Range selection mode |
+| `min` | `String` | `undefined` | ISO lower bound |
+| `max` | `String` | `undefined` | ISO upper bound |
+| `disabledDates` | `String[]` | `[]` | Specific ISO dates to disable |
+| `format` | `(iso) => string` | `undefined` | Display formatter for input value |
+| `placeholder` | `String` | `'Select date'` | |
+| `weekStart` | `Number` | `0` | 0 = Sunday, 1 = Monday |
+| `id` | `String` | auto | |
+| `label` | `String` | `undefined` | |
+| `disabled` | `Boolean` | `false` | |
+
+### Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `String \| [String\|null, String\|null]` | Selection committed |
+| `open` | — | Popover opened |
+| `close` | — | Popover closed |
+
+### Exposed methods
+
+- `open()` — programmatically open the popover.
+- `close()` — programmatically close.
+
+## Single mode
+
+```vue
+<script setup>
+import { ref } from 'vue'
+const date = ref(null)
+</script>
+
+<template>
+  <VibeDatePicker v-model="date" label="Due date" />
+</template>
+```
+
+## Range mode
+
+```vue
+<VibeDatePicker
+  v-model="range"
+  range
+  :min="'2026-01-01'"
+  :max="'2026-12-31'"
+  :format="iso => iso.split('-').reverse().join('/')"
+/>
+```
+
+The first click sets `[start, null]`. The second click adds the end date and closes the popover; if the second pick is earlier than the first, the range is auto-swapped to stay ordered.
+
+## Disabling dates
+
+```vue
+<VibeDatePicker
+  v-model="date"
+  :disabled-dates="['2026-04-29', '2026-04-30']"
+/>
+```
+
+## Important Notes
+
+**Zero-padded ISO bounds:** `min`, `max`, and every entry in `disabledDates` must be zero-padded `YYYY-MM-DD` (e.g. `2026-04-05`, not `2026-4-5`). Comparisons are lexical string comparisons, so an unpadded value compares incorrectly. In dev mode, a non-conforming `min`/`max` logs a console warning.
+
+**Read-only input:** The text input is read-only; dates are chosen through the calendar popover, which closes on outside click or `Escape`.
+
+**Keyboard navigation:** The grid supports arrow keys (day), `PageUp`/`PageDown` (month), `Home`/`End` (week), and `Enter`/`Space` to select.

package/docs/components/interactive/draggable.md

@@ -0,0 +1,91 @@
+# VibeDraggable / VibeDroppable
+
+Generic drag-and-drop primitives for kanban boards, builders, palette UIs. Communicates payloads through a shared module-level store, so payloads can be typed objects or non-serializable values (refs, functions) — no DataTransfer string round-trip.
+
+## VibeDraggable Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `payload` | `unknown` | `undefined` | Data passed to the matching droppable on drop |
+| `group` | `String` | `'default'` | Tag used to match against droppable groups |
+| `disabled` | `Boolean` | `false` | Disable dragging |
+| `tag` | `String` | `'div'` | Element to render |
+
+### Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `dragstart` | `{ payload, group, event }` | Emitted on dragstart |
+| `dragend` | `{ payload, group, event }` | Emitted on dragend, regardless of drop success |
+
+### Slots
+
+Default slot scope: `{ isDragging }`.
+
+## VibeDroppable Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `group` | `String` | `'default'` | Group accepted unless `acceptGroups` overrides |
+| `acceptGroups` | `String[]` | `undefined` | Whitelist of groups that may drop here |
+| `disabled` | `Boolean` | `false` | Reject all drops |
+| `tag` | `String` | `'div'` | Element to render |
+
+### Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `drop` | `{ payload, group, event }` | Successful drop, only emitted when group matches |
+| `dragenter` | `DragEvent` | |
+| `dragleave` | `DragEvent` | |
+
+### Slots
+
+Default slot scope: `{ isOver }`.
+
+## Examples
+
+### Kanban column move
+
+```vue
+<script setup>
+import { ref } from 'vue'
+const todo = ref([{ id: 1, title: 'Wireframes' }])
+const done = ref([])
+
+function moveCard(card, from, to) {
+  from.value = from.value.filter(c => c.id !== card.id)
+  to.value.push(card)
+}
+</script>
+
+<template>
+  <div class="d-flex gap-3">
+    <VibeDroppable group="cards" @drop="({ payload }) => moveCard(payload, todo, done)">
+      <template #default="{ isOver }">
+        <div :class="['col bg-light p-3', isOver ? 'border-primary' : '']">
+          <h5>To do</h5>
+          <VibeDraggable v-for="card in todo" :key="card.id" :payload="card" group="cards">
+            <div class="card mb-2 p-2">{{ card.title }}</div>
+          </VibeDraggable>
+        </div>
+      </template>
+    </VibeDroppable>
+
+    <VibeDroppable group="cards" @drop="({ payload }) => moveCard(payload, done, todo)">
+      <h5>Done</h5>
+      <VibeDraggable v-for="card in done" :key="card.id" :payload="card" group="cards">
+        <div class="card mb-2 p-2">{{ card.title }}</div>
+      </VibeDraggable>
+    </VibeDroppable>
+  </div>
+</template>
+```
+
+### Multi-source whitelist
+
+```vue
+<VibeDroppable :accept-groups="['todo', 'done']" group="trash">
+  <div class="trash-zone">Drop to delete</div>
+</VibeDroppable>
+```

package/docs/components/interactive/dropdown.md

@@ -39,6 +39,7 @@ interface DropdownItem {
 | `shown` | - | Emitted when dropdown is fully shown |
 | `hide` | - | Emitted when dropdown starts hiding |
 | `hidden` | - | Emitted when dropdown is fully hidden |
+| `component-error` | `ComponentError` | Emitted if Bootstrap JS fails to load |
 
 ## Slots
 
@@ -50,40 +51,75 @@ interface DropdownItem {
 
 ## Usage
 
-### Programmatic Control
+### Basic Dropdown
 
 ```vue
 <template>
-  <div>
-    <VibeButton @click="$refs.myDropdown.toggle()">External Toggle</VibeButton>
-    
-    <VibeDropdown
-      ref="myDropdown"
-      text="Dropdown Menu"
-      :items="dropdownItems"
-    />
-  </div>
+  <VibeDropdown text="Dropdown Menu" :items="dropdownItems" @item-click="onItemClick" />
 </template>
+
+<script setup>
+const dropdownItems = [
+  { header: true, text: 'Actions' },
+  { text: 'Edit', href: '#edit' },
+  { text: 'Duplicate', href: '#duplicate' },
+  { divider: true },
+  { text: 'Delete', href: '#delete', active: false }
+]
+
+function onItemClick({ item, index }) {
+  console.log('clicked', item.text, 'at', index)
+}
+</script>
 ```
 
-### Basic Dropdown
+### Custom Item Rendering (Slots)
+
+The `item` and `header` slots receive `{ item, index }` so you can render rich markup while still driving the menu from the `items` array:
 
 ```vue
 <template>
-  <VibeDropdown
-    text="Dropdown Menu"
-    :items="dropdownItems"
-  />
+  <VibeDropdown text="Menu" :items="dropdownItems">
+    <template #item="{ item }">
+      <i :class="item.icon" class="me-2" />{{ item.text }}
+    </template>
+  </VibeDropdown>
 </template>
+
+<script setup>
+const dropdownItems = [
+  { text: 'Profile', href: '#', icon: 'bi bi-person' },
+  { text: 'Settings', href: '#', icon: 'bi bi-gear' }
+]
+</script>
+```
+
+### Programmatic Control
+
+```vue
+<template>
+  <div>
+    <VibeButton @click="myDropdown.toggle()">External Toggle</VibeButton>
+
+    <VibeDropdown ref="myDropdown" text="Dropdown Menu" :items="dropdownItems" />
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+const myDropdown = ref(null)
+const dropdownItems = [
+  { text: 'Edit', href: '#edit' },
+  { text: 'Delete', href: '#delete' }
+]
+</script>
 ```
 
 ## Important Notes
 
 **Automatic Initialization:** This component automatically initializes Bootstrap's Dropdown functionality when it is mounted, provided that Bootstrap's JavaScript is available in your project.
 
-**Programmatic Methods:** You can call `show()`, `hide()`, and `toggle()` on the component instance via template refs.
-
-**Instance Exposure:** You can access the underlying Bootstrap instance via template ref using the `bsInstance` property.
+**Programmatic Methods:** The component exposes `show()`, `hide()`, and `toggle()` via template refs for programmatic control.
 
 ## Bootstrap CSS Classes
 

package/docs/components/interactive/modal.md

@@ -27,6 +27,7 @@ Modal dialogs for lightboxes, user notifications, or custom content.
 | `shown` | - | Emitted when modal is fully shown |
 | `hide` | - | Emitted when modal starts hiding |
 | `hidden` | - | Emitted when modal is fully hidden |
+| `component-error` | `ComponentError` | Emitted if Bootstrap JS fails to load |
 
 ## Slots
 
@@ -59,23 +60,6 @@ const showModal = ref(false)
 </script>
 ```
 
-### Basic Modal (Data Attributes)
-
-```vue
-<template>
-  <div>
-    <!-- You can still use standard Bootstrap data attributes -->
-    <VibeButton variant="primary" data-bs-toggle="modal" data-bs-target="#exampleModal">
-      Launch Modal
-    </VibeButton>
-
-    <VibeModal id="exampleModal" title="Modal Title">
-      <p>Modal body text goes here.</p>
-    </VibeModal>
-  </div>
-</template>
-```
-
 ### Sized Modals
 
 ```vue
@@ -106,15 +90,24 @@ const showModal = ref(false)
 
 ```vue
 <template>
-  <VibeModal title="Custom Footer">
+  <VibeModal v-model="showModal" title="Custom Footer">
     <p>Modal with custom footer buttons.</p>
 
     <template #footer>
       <VibeButton variant="secondary" @click="showModal = false">Close</VibeButton>
-      <VibeButton variant="primary">Save changes</VibeButton>
+      <VibeButton variant="primary" @click="save">Save changes</VibeButton>
     </template>
   </VibeModal>
 </template>
+
+<script setup>
+import { ref } from 'vue'
+const showModal = ref(true)
+function save() {
+  // persist changes...
+  showModal.value = false
+}
+</script>
 ```
 
 ## Important Notes
@@ -123,7 +116,9 @@ const showModal = ref(false)
 
 **Teleportation:** By default, this component teleports its DOM elements to the `<body>` to avoid stacking context issues. You can customize this with the `teleport` prop.
 
-**Instance Exposure:** You can access the underlying Bootstrap instance via template ref using the `bsInstance` property.
+**Focus Return (WCAG 2.4.3):** When the modal closes, focus is automatically returned to the element that opened it, including for programmatically opened modals.
+
+**Escape Hatch:** The exposed `_unsafe_bsInstance` template ref gives raw access to the underlying Bootstrap Modal instance. It is **not** part of the stable API — calling `dispose()` or other lifecycle methods on it directly **will** break the component. Prefer `v-model` and the exposed `show()` / `hide()` methods.
 
 ## Mobile Optimization
 

package/docs/components/interactive/offcanvas.md

@@ -23,6 +23,7 @@ Hidden sidebar for navigation or additional content.
 | `shown` | - | Emitted when offcanvas is fully shown |
 | `hide` | - | Emitted when offcanvas starts hiding |
 | `hidden` | - | Emitted when offcanvas is fully hidden |
+| `component-error` | `ComponentError` | Emitted if Bootstrap JS fails to load |
 
 ## Slots
 
@@ -70,7 +71,9 @@ const showOffcanvas = ref(false)
 
 **Teleportation:** By default, this component teleports its DOM elements to the `<body>` to avoid stacking context issues. You can customize this with the `teleport` prop.
 
-**Instance Exposure:** You can access the underlying Bootstrap instance via template ref using the `bsInstance` property.
+**Focus Return (WCAG 2.4.3):** When the offcanvas closes, focus is automatically returned to the element that opened it, including for programmatically opened panels.
+
+**Escape Hatch:** The exposed `_unsafe_bsInstance` template ref gives raw access to the underlying Bootstrap Offcanvas instance. It is **not** part of the stable API — calling `dispose()` or other lifecycle methods on it directly **will** break the component. Prefer `v-model` and the exposed `show()` / `hide()` methods.
 
 ## Mobile Optimization