@velkymx/vibeui 0.8.2 → 1.0.2

package/docs/README.md

@@ -6,12 +6,26 @@ Complete documentation for VibeUI - A modern Vue 3 UI component library built wi
 
 VibeUI is designed to be simple and lightweight, providing Vue 3 components that wrap Bootstrap 5.3 functionality with a clean, intuitive API.
 
+> **New here?** See the [Starter Template](./getting-started/starter-template.md) for a complete, copy-pasteable minimal app.
+
 ### Installation
 
 ```bash
 npm install @velkymx/vibeui bootstrap
 ```
 
+#### Optional peer dependencies
+
+Install these only if you use the components that need them:
+
+- `bootstrap-icons` — required by `VibeIcon`.
+- `quill` + `dompurify` — required by `VibeFormWysiwyg`.
+
+```bash
+npm install bootstrap-icons         # for VibeIcon
+npm install quill dompurify         # for VibeFormWysiwyg
+```
+
 ### Setup
 
 ```javascript
@@ -29,7 +43,7 @@ createApp(App).use(VibeUI).mount('#app')
 
 ### Bootstrap JavaScript
 
-**VibeUI v0.8.0+ is mobile-optimized and fully abstracts Bootstrap's JavaScript.** You do not need to manually import or initialize Bootstrap JS for VibeUI components. 
+**Do NOT import Bootstrap JS — VibeUI manages it.** VibeUI is mobile-optimized and fully abstracts Bootstrap's JavaScript. You do not need to manually import or initialize Bootstrap JS for VibeUI components; importing it yourself can cause duplicate instances and event conflicts.
 
 The library handles:
 - **Dynamic Initialization:** Components initialize their own JS logic on mount.
@@ -49,42 +63,97 @@ The library handles:
 - [VibeBadge](./components/core/badge.md)
 - [VibeButton](./components/core/button.md)
 - [VibeButtonGroup](./components/core/button-group.md)
-- [VibeLink](./components/core/link.md)
 - [VibeCloseButton](./components/core/close-button.md)
-- [VibeSpinner](./components/core/spinner.md)
+- [VibeLink](./components/core/link.md)
 - [VibePlaceholder](./components/core/placeholder.md)
+- [VibeSkeleton](./components/core/skeleton.md)
+- [VibeSpinner](./components/core/spinner.md)
 
 ### [Interactive Components](./components/interactive/)
 - [VibeAccordion](./components/interactive/accordion.md)
 - [VibeCarousel](./components/interactive/carousel.md)
 - [VibeCollapse](./components/interactive/collapse.md)
+- [VibeDatePicker](./components/interactive/date-picker.md)
+- [VibeDraggable / VibeDroppable](./components/interactive/draggable.md)
 - [VibeDropdown](./components/interactive/dropdown.md)
 - [VibeModal](./components/interactive/modal.md)
 - [VibeOffcanvas](./components/interactive/offcanvas.md)
+- [VibeResizable](./components/interactive/resizable.md)
+- [VibeSlider](./components/interactive/slider.md)
+- [VibeSortable](./components/interactive/sortable.md)
+- [VibeStepper](./components/interactive/stepper.md)
+- [VibeTabs / VibeTab](./components/interactive/tabs.md)
 - [VibeToast](./components/interactive/toast.md)
 
 ### [Advanced Components](./components/advanced/)
-- [VibeTooltip](./components/advanced/tooltip.md)
 - [VibePopover](./components/advanced/popover.md)
 - [VibeScrollspy](./components/advanced/scrollspy.md)
+- [VibeTooltip](./components/advanced/tooltip.md)
+
+### [Card](./components/card/)
+- [VibeCard](./components/card/card.md)
+
+### [Hero](./components/hero/)
+- [VibeHero](./components/hero/hero.md)
+
+### [List](./components/list/)
+- [VibeListGroup](./components/list/list-group.md)
+
+### [Navigation](./components/navigation/)
+- [VibeBreadcrumb](./components/navigation/breadcrumb.md)
+- [VibeNav](./components/navigation/nav.md)
+- [VibeNavbar](./components/navigation/navbar.md)
+- [VibePagination](./components/navigation/pagination.md)
 
 ### [Data Components](./components/data/)
 - [VibeDataTable](./components/data/datatable.md)
 
+### [Charts](./components/charts/)
+- [VibeChartBar](./components/charts/chart-bar.md)
+- [VibeChartLine](./components/charts/chart-line.md)
+- [VibeChartPie](./components/charts/chart-pie.md)
+
+### [Progress](./components/progress/)
+- [VibeProgress](./components/progress/progress.md)
+
 ### [Form Components](./forms/)
+- [VibeAutocomplete](./forms/autocomplete.md)
+- [VibeFileInput](./forms/file-input.md)
+- [VibeFormCheckbox](./forms/form-checkbox.md)
+- [VibeFormDatepicker](./forms/form-datepicker.md) (native input)
 - [VibeFormGroup](./forms/form-group.md) - Automated layout & accessibility
 - [VibeFormInput](./forms/form-input.md)
-- [VibeInputGroup](./forms/input-group.md)
+- [VibeFormRadio](./forms/form-radio.md)
 - [VibeFormSelect](./forms/form-select.md)
+- [VibeFormSpinbutton](./forms/form-spinbutton.md)
+- [VibeFormSwitch](./forms/form-switch.md)
+- [VibeFormTextarea](./forms/form-textarea.md)
 - [VibeFormWysiwyg](./forms/form-wysiwyg.md)
+- [VibeInputGroup](./forms/input-group.md)
+- [Validation rules](./forms/validation.md)
 
 ## Composables
 
 Standalone utilities that can be used independently of any component.
 
-- [useColorMode](./composables/color-mode.md) - Manage Bootstrap light/dark/auto color modes
-- `useBreakpoints` - Programmatic breakpoint detection (xs, sm, md, lg, xl, xxl)
-- `useBackButton` - Handle Android hardware back button in hybrid mobile apps
+- [useBackButton](./composables/back-button.md) - Android hardware back button handling
+- [useBreakpoints](./composables/breakpoints.md) - Programmatic breakpoint detection
+- [useColorMode](./composables/color-mode.md) - Bootstrap light/dark/auto color modes
+- [useForm](./composables/use-form.md) - Multi-field form state with validation
+- [usePosition](./composables/use-position.md) - Floating-UI based anchor positioning
+- [useToast](./composables/use-toast.md) - Global toast service
+
+## Directives
+
+- [v-vibe-tooltip](./directives/v-tooltip.md) - Inline tooltip directive
+
+## Utilities
+
+- [Position utility classes](./utilities/position.md) - Bootstrap position-* / top-* / translate-middle reference
+
+## Versioning & Stability
+
+- [Versioning & Stability Policy](./versioning.md) - SemVer commitment, what's covered by the public API, deprecation and peer-dependency policy
 
 ## Design Philosophy
 
@@ -102,21 +171,24 @@ Most interactive and form components support `v-model` for two-way state synchro
 <VibeModal v-model="show" title="Hello" />
 ```
 
-### Instance Exposure
-Advanced users can access the underlying Bootstrap instance via template refs:
+### Instance Exposure (escape hatch)
+
+The underlying Bootstrap instance is exposed as `_unsafe_bsInstance` for rare cases the props/`v-model` API doesn't cover.
+
+> **This is an escape hatch, not part of the stable API.** Calling Bootstrap lifecycle methods directly will desync VibeUI's internal state and can break the component. The `_unsafe_` prefix is intentional — prefer props and `v-model` whenever possible.
 
 ```vue
 <template>
   <VibeModal ref="myModal" />
 </template>
 
-<script setup>
+<script setup lang="ts">
 import { useTemplateRef, onMounted } from 'vue'
 const modal = useTemplateRef('myModal')
 
 onMounted(() => {
-  // Access native Bootstrap methods
-  modal.value.bsInstance.handleUpdate()
+  // Escape hatch — only when no prop/v-model covers your case
+  modal.value?._unsafe_bsInstance?.handleUpdate()
 })
 </script>
 ```

package/docs/components/advanced/popover.md

@@ -1,16 +1,24 @@
 # VibePopover
 
-Popovers for displaying rich content overlays. Requires Bootstrap JS and initialization.
+Popovers for displaying contextual content overlays. Bootstrap's popover JS is initialized automatically when the component mounts.
 
 ## Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
+| `text` | `String` | `undefined` | Popover body content (preferred) |
+| `content` | `String` | `undefined` | Alias for `text` |
 | `title` | `String` | `undefined` | Popover title |
-| `content` | `String` | Required | Popover content text |
-| `placement` | `Placement` | `'top'` | Popover position: `'top'`, `'bottom'`, `'start'`, `'end'` |
-| `trigger` | `String` | `'click'` | Trigger events (space-separated) |
-| `html` | `Boolean` | `false` | Allow HTML content |
+| `placement` | `TooltipPlacement` | `'top'` | Popover position: `'top'`, `'bottom'`, `'start'`, `'end'` |
+| `trigger` | `String` | `'click'` | Trigger events (space-separated): `'click'`, `'hover'`, `'focus'` |
+
+Provide either `text` or `content` (they are interchangeable). Content is always rendered as plain text — HTML is not supported (this is intentional, to avoid XSS).
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `component-error` | `{ message, componentName, originalError }` | Emitted if Bootstrap JS is unavailable at mount |
 
 ## Slots
 
@@ -18,6 +26,10 @@ Popovers for displaying rich content overlays. Requires Bootstrap JS and initial
 |------|-------------|
 | `default` | Element that triggers the popover |
 
+## Exposed
+
+> **Escape hatch:** `_unsafe_bsInstance` (the underlying Bootstrap `Popover` instance) is exposed via a template ref. It is **not** part of the stable API — calling `dispose()` or other lifecycle methods on it directly WILL break the component.
+
 ## Usage
 
 ### Basic Popover
@@ -26,7 +38,7 @@ Popovers for displaying rich content overlays. Requires Bootstrap JS and initial
 <template>
   <VibePopover
     title="Popover Title"
-    content="This is the popover content"
+    text="This is the popover content"
   >
     <VibeButton variant="danger">Click me</VibeButton>
   </VibePopover>
@@ -40,7 +52,7 @@ Popovers for displaying rich content overlays. Requires Bootstrap JS and initial
   <div>
     <VibePopover
       title="Top Popover"
-      content="Popover on top"
+      text="Popover on top"
       placement="top"
     >
       <VibeButton variant="secondary">Top</VibeButton>
@@ -48,7 +60,7 @@ Popovers for displaying rich content overlays. Requires Bootstrap JS and initial
 
     <VibePopover
       title="End Popover"
-      content="Popover on right"
+      text="Popover on right"
       placement="end"
     >
       <VibeButton variant="secondary">End</VibeButton>
@@ -56,7 +68,7 @@ Popovers for displaying rich content overlays. Requires Bootstrap JS and initial
 
     <VibePopover
       title="Bottom Popover"
-      content="Popover on bottom"
+      text="Popover on bottom"
       placement="bottom"
     >
       <VibeButton variant="secondary">Bottom</VibeButton>
@@ -64,7 +76,7 @@ Popovers for displaying rich content overlays. Requires Bootstrap JS and initial
 
     <VibePopover
       title="Start Popover"
-      content="Popover on left"
+      text="Popover on left"
       placement="start"
     >
       <VibeButton variant="secondary">Start</VibeButton>
@@ -79,7 +91,7 @@ Popovers for displaying rich content overlays. Requires Bootstrap JS and initial
 <template>
   <VibePopover
     title="Hover Popover"
-    content="This appears on hover"
+    text="This appears on hover"
     trigger="hover focus"
   >
     <VibeButton variant="info">Hover me</VibeButton>
@@ -87,25 +99,11 @@ Popovers for displaying rich content overlays. Requires Bootstrap JS and initial
 </template>
 ```
 
-### HTML Content
-
-```vue
-<template>
-  <VibePopover
-    title="<strong>HTML Title</strong>"
-    content="<em>HTML</em> content with <a href='#'>link</a>"
-    html
-  >
-    <VibeButton variant="warning">HTML Popover</VibeButton>
-  </VibePopover>
-</template>
-```
-
 ### No Title
 
 ```vue
 <template>
-  <VibePopover content="Just content, no title">
+  <VibePopover text="Just content, no title">
     <VibeButton variant="success">No Title</VibeButton>
   </VibePopover>
 </template>
@@ -113,37 +111,14 @@ Popovers for displaying rich content overlays. Requires Bootstrap JS and initial
 
 ## Important Notes
 
-**Automatic Initialization:** This component automatically initializes Bootstrap's Popover functionality when it is mounted, provided that Bootstrap's JavaScript is available in your project.
-
-**Touch Optimization:** On touch devices, if the trigger is set to `hover focus`, it automatically switches to `click` to ensure reliable behavior on mobile screens.
+**Automatic Initialization:** This component initializes Bootstrap's Popover for you when it mounts. Bootstrap's JS is loaded internally — do not import or initialize Bootstrap JS yourself.
 
-**Manual Initialization (Optional):** If you are not using the automatic initialization or need to initialize popovers on non-VibeUI elements:
+**Touch Optimization:** On touch devices, if the trigger is `hover focus`, it automatically switches to `click` for reliable behavior on mobile screens. Initialization is SSR-safe.
 
-```javascript
-// Initialize all popovers
-import { Popover } from 'bootstrap'
-...
-const popoverTriggerList = document.querySelectorAll('[data-bs-toggle="popover"]')
-const popoverList = [...popoverTriggerList].map(popoverTriggerEl => new Popover(popoverTriggerEl))
-```
-
-Or in Vue:
-
-```vue
-<script setup>
-import { onMounted } from 'vue'
-import { Popover } from 'bootstrap'
-
-onMounted(() => {
-  const popoverTriggerList = document.querySelectorAll('[data-bs-toggle="popover"]')
-  const popoverList = [...popoverTriggerList].map(el => new Popover(el))
-})
-</script>
-```
+**Reactive content:** Updating `text`/`content`/`title` updates the live popover without a re-init.
 
 ## Bootstrap CSS Classes
 
-- Uses Bootstrap's `data-bs-toggle="popover"` attributes
 - `.popover`
 - `.popover-arrow`
 - `.popover-header`

package/docs/components/advanced/scrollspy.md

@@ -7,16 +7,19 @@ Automatically update navigation based on scroll position.
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `target` | `String` | Required | CSS selector of navigation element to update |
-| `offset` | `Number` | `10` | Offset pixels from top when calculating position |
-| `method` | `String` | `'auto'` | Scroll method: `'auto'`, `'offset'`, or `'position'` |
+| `rootMargin` | `String` | `'0px 0px -25%'` | Intersection margin for triggering activation. Format: `'top right bottom left'` in CSS units |
+| `offset` | `Number` | `undefined` | **Deprecated.** Use `rootMargin` instead. Ignored in Bootstrap 5.2+. |
+| `method` | `String` | `'auto'` | Scroll detection method: `'auto'`, `'offset'`, or `'position'` |
 | `smoothScroll` | `Boolean` | `false` | Enable smooth scrolling |
 | `tag` | `String` | `'div'` | HTML tag to render |
+| `height` | `String` | `'100%'` | CSS height of the scrollable container. Validated as a CSS length; invalid values fall back to `'100%'` |
 
 ## Events
 
 | Event | Payload | Description |
 |-------|---------|-------------|
-| `activate` | - | Emitted when a new item is activated |
+| `activate` | `event` | Emitted when a new nav item is activated |
+| `component-error` | `{ message, componentName, originalError }` | Emitted if Bootstrap JS is unavailable |
 
 ## Slots
 
@@ -24,6 +27,12 @@ Automatically update navigation based on scroll position.
 |------|-------------|
 | `default` | Scrollable content with target sections |
 
+## Exposed Methods
+
+| Method | Description |
+|--------|-------------|
+| `refresh()` | Recalculates section positions. Call after dynamic content changes. |
+
 ## Usage
 
 ### Basic Scrollspy
@@ -35,11 +44,7 @@ Automatically update navigation based on scroll position.
       <VibeNav id="navbar-example" vertical pills :items="navItems" />
     </div>
     <div class="col-8">
-      <VibeScrollspy
-        target="#navbar-example"
-        smooth-scroll
-        style="height: 300px; overflow-y: auto"
-      >
+      <VibeScrollspy target="#navbar-example" :height="'300px'" smooth-scroll>
         <h4 id="item-1">Item 1</h4>
         <p>Content for item 1...</p>
         <h4 id="item-2">Item 2</h4>
@@ -48,17 +53,54 @@ Automatically update navigation based on scroll position.
     </div>
   </div>
 </template>
+
+<script setup>
+const navItems = [
+  { text: 'Item 1', href: '#item-1' },
+  { text: 'Item 2', href: '#item-2' }
+]
+</script>
 ```
 
-## Important Notes
+### Adjusting the Activation Margin
+
+`rootMargin` controls how early a section is activated relative to the scrollable viewport. The default `'0px 0px -25%'` activates a section when it enters the top 75% of the container.
+
+```vue
+<!-- Activate earlier — section activates when it crosses the midpoint -->
+<VibeScrollspy target="#nav" root-margin="0px 0px -50%">
+  ...
+</VibeScrollspy>
+```
+
+### Refreshing After Dynamic Content
 
-**Automatic Initialization:** This component automatically initializes Bootstrap's ScrollSpy functionality when it is mounted, provided that Bootstrap's JavaScript is available in your project.
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const scrollspy = ref(null)
+
+async function loadMore() {
+  // ... add content
+  await nextTick()
+  scrollspy.value.refresh()
+}
+</script>
+
+<template>
+  <VibeScrollspy ref="scrollspy" target="#nav">
+    ...
+  </VibeScrollspy>
+</template>
+```
+
+## Important Notes
 
-**Manual Refresh:** If you dynamically add or remove content inside the scrollspy, you may need to call the `refresh()` method on the component instance via template refs.
+**Automatic Initialization:** This component automatically initializes Bootstrap's ScrollSpy functionality when mounted, provided Bootstrap JavaScript is available.
 
-**Instance Exposure:** You can access the underlying Bootstrap instance via template ref using the `bsInstance` property.
+**`rootMargin` replaces `offset`:** Bootstrap 5.2 replaced the `offset` integer with `rootMargin` (an IntersectionObserver-compatible margin string). The `offset` prop is deprecated and logs a console warning. Use `rootMargin` for all new usage.
 
-## Bootstrap CSS Classes
+**KeepAlive support:** Positions are recalculated when the component is reactivated inside `<KeepAlive>`.
 
-- Uses Bootstrap's `data-bs-spy="scroll"` attributes
-- Targets navigation items automatically
+**Validated height:** The `height` prop is validated as a CSS length string before being applied. Invalid values silently fall back to `'100%'` (CSS injection defense).

package/docs/components/advanced/tooltip.md

@@ -1,15 +1,23 @@
 # VibeTooltip
 
-Tooltips for displaying contextual information. Requires Bootstrap JS and initialization.
+Tooltips for displaying contextual information. Bootstrap's tooltip JS is initialized automatically when the component mounts.
 
 ## Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `content` | `String` | Required | Tooltip text content |
-| `placement` | `Placement` | `'top'` | Tooltip position: `'top'`, `'bottom'`, `'start'`, `'end'` |
-| `trigger` | `String` | `'hover focus'` | Trigger events (space-separated) |
-| `html` | `Boolean` | `false` | Allow HTML content |
+| `text` | `String` | `undefined` | Tooltip text content (preferred) |
+| `content` | `String` | `undefined` | **Deprecated.** Use `text` instead |
+| `placement` | `TooltipPlacement` | `'top'` | Tooltip position: `'top'`, `'bottom'`, `'start'`, `'end'` |
+| `trigger` | `String` | `'hover focus'` | Trigger events (space-separated): `'hover'`, `'focus'`, `'click'` |
+
+Content is always rendered as plain text — HTML is not supported (this is intentional, to avoid XSS).
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `component-error` | `{ message, componentName, originalError }` | Emitted if Bootstrap JS is unavailable at mount |
 
 ## Slots
 
@@ -17,13 +25,17 @@ Tooltips for displaying contextual information. Requires Bootstrap JS and initia
 |------|-------------|
 | `default` | Element that triggers the tooltip |
 
+## Exposed
+
+> **Escape hatch:** `_unsafe_bsInstance` (the underlying Bootstrap `Tooltip` instance) is exposed via a template ref. It is **not** part of the stable API — calling `dispose()` or other lifecycle methods on it directly WILL break the component.
+
 ## Usage
 
 ### Basic Tooltip
 
 ```vue
 <template>
-  <VibeTooltip content="Tooltip text">
+  <VibeTooltip text="Tooltip text">
     <VibeButton variant="secondary">Hover me</VibeButton>
   </VibeTooltip>
 </template>
@@ -34,19 +46,19 @@ Tooltips for displaying contextual information. Requires Bootstrap JS and initia
 ```vue
 <template>
   <div>
-    <VibeTooltip content="Tooltip on top" placement="top">
+    <VibeTooltip text="Tooltip on top" placement="top">
       <VibeButton variant="secondary">Top</VibeButton>
     </VibeTooltip>
 
-    <VibeTooltip content="Tooltip on right" placement="end">
+    <VibeTooltip text="Tooltip on right" placement="end">
       <VibeButton variant="secondary">End</VibeButton>
     </VibeTooltip>
 
-    <VibeTooltip content="Tooltip on bottom" placement="bottom">
+    <VibeTooltip text="Tooltip on bottom" placement="bottom">
       <VibeButton variant="secondary">Bottom</VibeButton>
     </VibeTooltip>
 
-    <VibeTooltip content="Tooltip on left" placement="start">
+    <VibeTooltip text="Tooltip on left" placement="start">
       <VibeButton variant="secondary">Start</VibeButton>
     </VibeTooltip>
   </div>
@@ -57,55 +69,22 @@ Tooltips for displaying contextual information. Requires Bootstrap JS and initia
 
 ```vue
 <template>
-  <VibeTooltip content="Click to see tooltip" trigger="click">
+  <VibeTooltip text="Click to see tooltip" trigger="click">
     <VibeButton variant="primary">Click me</VibeButton>
   </VibeTooltip>
 </template>
 ```
 
-### HTML Content
-
-```vue
-<template>
-  <VibeTooltip content="<em>Tooltip</em> with <strong>HTML</strong>" html>
-    <VibeButton variant="info">HTML Tooltip</VibeButton>
-  </VibeTooltip>
-</template>
-```
-
 ## Important Notes
 
-**Automatic Initialization:** This component automatically initializes Bootstrap's Tooltip functionality when it is mounted, provided that Bootstrap's JavaScript is available in your project.
+**Automatic Initialization:** This component initializes Bootstrap's Tooltip for you when it mounts. Bootstrap's JS is loaded internally — do not import or initialize Bootstrap JS yourself.
 
-**Touch Optimization:** On touch devices, the tooltip automatically switches its trigger from `hover focus` to `click` to ensure reliable behavior on mobile screens.
+**Touch Optimization:** On touch devices, when the trigger is `hover focus` it automatically switches to `click` for reliable behavior on mobile screens. Initialization is SSR-safe.
 
-**Manual Initialization (Optional):** If you are not using the automatic initialization or need to initialize tooltips on non-VibeUI elements:
-
-```javascript
-// Initialize all tooltips
-import { Tooltip } from 'bootstrap'
-...
-const tooltipTriggerList = document.querySelectorAll('[data-bs-toggle="tooltip"]')
-const tooltipList = [...tooltipTriggerList].map(tooltipTriggerEl => new Tooltip(tooltipTriggerEl))
-```
-
-Or in Vue:
-
-```vue
-<script setup>
-import { onMounted } from 'vue'
-import { Tooltip } from 'bootstrap'
-
-onMounted(() => {
-  const tooltipTriggerList = document.querySelectorAll('[data-bs-toggle="tooltip"]')
-  const tooltipList = [...tooltipTriggerList].map(el => new Tooltip(el))
-})
-</script>
-```
+**Reactive content:** Updating `text` (or the deprecated `content`) updates the live tooltip without a re-init.
 
 ## Bootstrap CSS Classes
 
-- Uses Bootstrap's `data-bs-toggle="tooltip"` attributes
 - `.tooltip`
 - `.tooltip-arrow`
 - `.tooltip-inner`

package/docs/components/card/card.md

@@ -14,9 +14,12 @@ Flexible content container component for displaying headers, bodies, footers, an
 | `body` | `String` | `undefined` | Card body text |
 | `header` | `String` | `undefined` | Card header text |
 | `footer` | `String` | `undefined` | Card footer text |
+| `headerClass` | `String \| Array \| Object` | `undefined` | Extra class(es) for the `.card-header` wrapper (e.g. a variant-colored header) |
+| `bodyClass` | `String \| Array \| Object` | `undefined` | Extra class(es) for the `.card-body` wrapper |
+| `footerClass` | `String \| Array \| Object` | `undefined` | Extra class(es) for the `.card-footer` wrapper |
 | `imgSrc` | `String` | `undefined` | Image URL |
 | `imgAlt` | `String` | `''` | Image alt text |
-| `imgTop` | `Boolean` | `true` | Display image at top |
+| `imgTop` | `Boolean` | `false` | Display image at top |
 | `imgBottom` | `Boolean` | `false` | Display image at bottom |
 
 ## Slots
@@ -24,6 +27,7 @@ Flexible content container component for displaying headers, bodies, footers, an
 | Slot | Description |
 |------|-------------|
 | `default` | Additional body content |
+| `image` | A direct card child rendered **outside** `.card-body` (before the header) — for a card image with custom composition, e.g. a `card-img-top` with an absolutely-positioned overlay/badge |
 | `header` | Custom header content |
 | `title` | Custom title content |
 | `body` | Custom body content |
@@ -62,6 +66,7 @@ Flexible content container component for displaying headers, bodies, footers, an
   <VibeCard
     img-src="/path/to/image.jpg"
     img-alt="Card image"
+    img-top
     title="Card with Image"
     body="This card has an image at the top."
   />
@@ -175,6 +180,7 @@ Use the default slot with Bootstrap grid:
       <VibeCard
         img-src="/path/to/image1.jpg"
         img-alt="Card 1"
+        img-top
         title="Card 1"
         body="Card content here."
       />
@@ -183,6 +189,7 @@ Use the default slot with Bootstrap grid:
       <VibeCard
         img-src="/path/to/image2.jpg"
         img-alt="Card 2"
+        img-top
         title="Card 2"
         body="Card content here."
       />
@@ -191,6 +198,7 @@ Use the default slot with Bootstrap grid:
       <VibeCard
         img-src="/path/to/image3.jpg"
         img-alt="Card 3"
+        img-top
         title="Card 3"
         body="Card content here."
       />