@velkymx/vibeui 0.9.0 → 1.1.0

package/docs/README.md

@@ -0,0 +1,225 @@
+# VibeUI Documentation
+
+Complete documentation for VibeUI - A modern Vue 3 UI component library built with Bootstrap 5.3.
+
+## Getting Started
+
+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
+import { createApp } from 'vue'
+import App from './App.vue'
+import VibeUI, { useColorMode } from '@velkymx/vibeui'
+import 'bootstrap/dist/css/bootstrap.min.css'
+
+// Restore saved color mode preference before mounting
+const { initColorMode } = useColorMode()
+initColorMode()
+
+createApp(App).use(VibeUI).mount('#app')
+```
+
+### Bootstrap JavaScript
+
+**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.
+- **Reactive Configuration:** Re-initializes automatically when props like `placement` or `delay` change.
+- **Memory Cleanup:** Automatically disposes of Bootstrap instances on unmount.
+- **State Integrity:** Synchronizes internal Vue state with native Bootstrap events.
+
+## Components
+
+### [Layout Components](./components/layout/)
+- [VibeContainer](./components/layout/container.md)
+- [VibeRow](./components/layout/row.md)
+- [VibeCol](./components/layout/col.md)
+
+### [Core Components](./components/core/)
+- [VibeAlert](./components/core/alert.md)
+- [VibeBadge](./components/core/badge.md)
+- [VibeButton](./components/core/button.md)
+- [VibeButtonGroup](./components/core/button-group.md)
+- [VibeCloseButton](./components/core/close-button.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/)
+- [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)
+- [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.
+
+- [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
+
+1. **Full Abstraction** - No "reach-around" required; the library manages the framework engine.
+2. **Zero-Boilerplate** - Automatic IDs, Teleportation, and state syncing.
+3. **Smart Forms** - Context-aware form groups automate accessibility.
+4. **TypeScript First** - Comprehensive type definitions for all props and events.
+
+## Common Patterns
+
+### v-model Support
+Most interactive and form components support `v-model` for two-way state synchronization.
+
+```vue
+<VibeModal v-model="show" title="Hello" />
+```
+
+### 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 lang="ts">
+import { useTemplateRef, onMounted } from 'vue'
+const modal = useTemplateRef('myModal')
+
+onMounted(() => {
+  // Escape hatch — only when no prop/v-model covers your case
+  modal.value?._unsafe_bsInstance?.handleUpdate()
+})
+</script>
+```
+
+## Mobile & Hybrid App Support
+
+VibeUI is optimized for mobile-first development and hybrid environments like **Capacitor**.
+
+### Programmatic Breakpoints
+Use the `useBreakpoints` composable to adapt your UI based on the viewport size.
+
+```javascript
+import { useBreakpoints } from '@velkymx/vibeui'
+const { isMobile, isTablet, isLg } = useBreakpoints()
+```
+
+### Safe Areas
+Components like `VibeNavbar`, `VibeOffcanvas`, and `VibeModal` automatically respect device safe areas (notches) when your app is configured with `viewport-fit=cover`.
+
+### Hybrid Navigation
+Use `useBackButton` to ensure Android hardware back button events correctly close active UI layers like modals and sidebars.
+
+```javascript
+import { useBackButton } from '@velkymx/vibeui'
+// Registered automatically inside VibeModal and VibeOffcanvas
+```
+
+## Contributing
+...
+Contributions are welcome! Please visit the [GitHub repository](https://github.com/velkymx/vibeui) to report issues or submit pull requests.
+
+## License
+
+MIT License - See LICENSE file for details.

package/docs/components/advanced/popover.md

@@ -0,0 +1,125 @@
+# VibePopover
+
+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 |
+| `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` | `ComponentError` | Emitted if Bootstrap JS is unavailable at mount |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `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
+
+```vue
+<template>
+  <VibePopover
+    title="Popover Title"
+    text="This is the popover content"
+  >
+    <VibeButton variant="danger">Click me</VibeButton>
+  </VibePopover>
+</template>
+```
+
+### Placement Options
+
+```vue
+<template>
+  <div>
+    <VibePopover
+      title="Top Popover"
+      text="Popover on top"
+      placement="top"
+    >
+      <VibeButton variant="secondary">Top</VibeButton>
+    </VibePopover>
+
+    <VibePopover
+      title="End Popover"
+      text="Popover on right"
+      placement="end"
+    >
+      <VibeButton variant="secondary">End</VibeButton>
+    </VibePopover>
+
+    <VibePopover
+      title="Bottom Popover"
+      text="Popover on bottom"
+      placement="bottom"
+    >
+      <VibeButton variant="secondary">Bottom</VibeButton>
+    </VibePopover>
+
+    <VibePopover
+      title="Start Popover"
+      text="Popover on left"
+      placement="start"
+    >
+      <VibeButton variant="secondary">Start</VibeButton>
+    </VibePopover>
+  </div>
+</template>
+```
+
+### Hover Trigger
+
+```vue
+<template>
+  <VibePopover
+    title="Hover Popover"
+    text="This appears on hover"
+    trigger="hover focus"
+  >
+    <VibeButton variant="info">Hover me</VibeButton>
+  </VibePopover>
+</template>
+```
+
+### No Title
+
+```vue
+<template>
+  <VibePopover text="Just content, no title">
+    <VibeButton variant="success">No Title</VibeButton>
+  </VibePopover>
+</template>
+```
+
+## Important Notes
+
+**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.
+
+**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.
+
+**Reactive content:** Updating `text`/`content`/`title` updates the live popover without a re-init.
+
+## Bootstrap CSS Classes
+
+- `.popover`
+- `.popover-arrow`
+- `.popover-header`
+- `.popover-body`

package/docs/components/advanced/scrollspy.md

@@ -0,0 +1,106 @@
+# VibeScrollspy
+
+Automatically update navigation based on scroll position.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `target` | `String` | Required | CSS selector of navigation element to update |
+| `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'`. Note: `'offset'` is deprecated in Bootstrap 5.2+ (IntersectionObserver-based detection supersedes it); prefer `'auto'` 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` | `event` | Emitted when a new nav item is activated |
+| `component-error` | `ComponentError` | Emitted if Bootstrap JS is unavailable |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Scrollable content with target sections |
+
+## Exposed Methods
+
+| Method | Description |
+|--------|-------------|
+| `refresh()` | Recalculates section positions. Call after dynamic content changes. |
+
+## Usage
+
+### Basic Scrollspy
+
+```vue
+<template>
+  <div class="row">
+    <div class="col-4">
+      <VibeNav id="navbar-example" vertical pills :items="navItems" />
+    </div>
+    <div class="col-8">
+      <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>
+        <p>Content for item 2...</p>
+      </VibeScrollspy>
+    </div>
+  </div>
+</template>
+
+<script setup>
+const navItems = [
+  { text: 'Item 1', href: '#item-1' },
+  { text: 'Item 2', href: '#item-2' }
+]
+</script>
+```
+
+### 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
+
+```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
+
+**Automatic Initialization:** This component automatically initializes Bootstrap's ScrollSpy functionality when mounted, provided Bootstrap JavaScript is available.
+
+**`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.
+
+**KeepAlive support:** Positions are recalculated when the component is reactivated inside `<KeepAlive>`.
+
+**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

@@ -0,0 +1,90 @@
+# VibeTooltip
+
+Tooltips for displaying contextual information. Bootstrap's tooltip JS is initialized automatically when the component mounts.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `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` | `ComponentError` | Emitted if Bootstrap JS is unavailable at mount |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `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 text="Tooltip text">
+    <VibeButton variant="secondary">Hover me</VibeButton>
+  </VibeTooltip>
+</template>
+```
+
+### Placement Options
+
+```vue
+<template>
+  <div>
+    <VibeTooltip text="Tooltip on top" placement="top">
+      <VibeButton variant="secondary">Top</VibeButton>
+    </VibeTooltip>
+
+    <VibeTooltip text="Tooltip on right" placement="end">
+      <VibeButton variant="secondary">End</VibeButton>
+    </VibeTooltip>
+
+    <VibeTooltip text="Tooltip on bottom" placement="bottom">
+      <VibeButton variant="secondary">Bottom</VibeButton>
+    </VibeTooltip>
+
+    <VibeTooltip text="Tooltip on left" placement="start">
+      <VibeButton variant="secondary">Start</VibeButton>
+    </VibeTooltip>
+  </div>
+</template>
+```
+
+### Custom Trigger
+
+```vue
+<template>
+  <VibeTooltip text="Click to see tooltip" trigger="click">
+    <VibeButton variant="primary">Click me</VibeButton>
+  </VibeTooltip>
+</template>
+```
+
+## Important Notes
+
+**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, when the trigger is `hover focus` it automatically switches to `click` for reliable behavior on mobile screens. Initialization is SSR-safe.
+
+**Reactive content:** Updating `text` (or the deprecated `content`) updates the live tooltip without a re-init.
+
+## Bootstrap CSS Classes
+
+- `.tooltip`
+- `.tooltip-arrow`
+- `.tooltip-inner`