@velkymx/vibeui 0.8.1 → 0.8.2

package/docs/README.md

@@ -0,0 +1,153 @@
+# 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.
+
+### Installation
+
+```bash
+npm install @velkymx/vibeui bootstrap
+```
+
+### 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
+
+**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. 
+
+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)
+- [VibeLink](./components/core/link.md)
+- [VibeCloseButton](./components/core/close-button.md)
+- [VibeSpinner](./components/core/spinner.md)
+- [VibePlaceholder](./components/core/placeholder.md)
+
+### [Interactive Components](./components/interactive/)
+- [VibeAccordion](./components/interactive/accordion.md)
+- [VibeCarousel](./components/interactive/carousel.md)
+- [VibeCollapse](./components/interactive/collapse.md)
+- [VibeDropdown](./components/interactive/dropdown.md)
+- [VibeModal](./components/interactive/modal.md)
+- [VibeOffcanvas](./components/interactive/offcanvas.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)
+
+### [Data Components](./components/data/)
+- [VibeDataTable](./components/data/datatable.md)
+
+### [Form Components](./forms/)
+- [VibeFormGroup](./forms/form-group.md) - Automated layout & accessibility
+- [VibeFormInput](./forms/form-input.md)
+- [VibeInputGroup](./forms/input-group.md)
+- [VibeFormSelect](./forms/form-select.md)
+- [VibeFormWysiwyg](./forms/form-wysiwyg.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
+
+## 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
+Advanced users can access the underlying Bootstrap instance via template refs:
+
+```vue
+<template>
+  <VibeModal ref="myModal" />
+</template>
+
+<script setup>
+import { useTemplateRef, onMounted } from 'vue'
+const modal = useTemplateRef('myModal')
+
+onMounted(() => {
+  // Access native Bootstrap methods
+  modal.value.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,150 @@
+# VibePopover
+
+Popovers for displaying rich content overlays. Requires Bootstrap JS and initialization.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `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 |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Element that triggers the popover |
+
+## Usage
+
+### Basic Popover
+
+```vue
+<template>
+  <VibePopover
+    title="Popover Title"
+    content="This is the popover content"
+  >
+    <VibeButton variant="danger">Click me</VibeButton>
+  </VibePopover>
+</template>
+```
+
+### Placement Options
+
+```vue
+<template>
+  <div>
+    <VibePopover
+      title="Top Popover"
+      content="Popover on top"
+      placement="top"
+    >
+      <VibeButton variant="secondary">Top</VibeButton>
+    </VibePopover>
+
+    <VibePopover
+      title="End Popover"
+      content="Popover on right"
+      placement="end"
+    >
+      <VibeButton variant="secondary">End</VibeButton>
+    </VibePopover>
+
+    <VibePopover
+      title="Bottom Popover"
+      content="Popover on bottom"
+      placement="bottom"
+    >
+      <VibeButton variant="secondary">Bottom</VibeButton>
+    </VibePopover>
+
+    <VibePopover
+      title="Start Popover"
+      content="Popover on left"
+      placement="start"
+    >
+      <VibeButton variant="secondary">Start</VibeButton>
+    </VibePopover>
+  </div>
+</template>
+```
+
+### Hover Trigger
+
+```vue
+<template>
+  <VibePopover
+    title="Hover Popover"
+    content="This appears on hover"
+    trigger="hover focus"
+  >
+    <VibeButton variant="info">Hover me</VibeButton>
+  </VibePopover>
+</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">
+    <VibeButton variant="success">No Title</VibeButton>
+  </VibePopover>
+</template>
+```
+
+## 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.
+
+**Manual Initialization (Optional):** If you are not using the automatic initialization or need to initialize popovers on non-VibeUI elements:
+
+```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>
+```
+
+## Bootstrap CSS Classes
+
+- Uses Bootstrap's `data-bs-toggle="popover"` attributes
+- `.popover`
+- `.popover-arrow`
+- `.popover-header`
+- `.popover-body`

package/docs/components/advanced/scrollspy.md

@@ -0,0 +1,64 @@
+# VibeScrollspy
+
+Automatically update navigation based on scroll position.
+
+## Props
+
+| 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'` |
+| `smoothScroll` | `Boolean` | `false` | Enable smooth scrolling |
+| `tag` | `String` | `'div'` | HTML tag to render |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `activate` | - | Emitted when a new item is activated |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Scrollable content with target sections |
+
+## 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"
+        smooth-scroll
+        style="height: 300px; overflow-y: auto"
+      >
+        <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>
+```
+
+## Important Notes
+
+**Automatic Initialization:** This component automatically initializes Bootstrap's ScrollSpy functionality when it is mounted, provided that Bootstrap's JavaScript is available in your project.
+
+**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.
+
+**Instance Exposure:** You can access the underlying Bootstrap instance via template ref using the `bsInstance` property.
+
+## Bootstrap CSS Classes
+
+- Uses Bootstrap's `data-bs-spy="scroll"` attributes
+- Targets navigation items automatically

package/docs/components/advanced/tooltip.md

@@ -0,0 +1,111 @@
+# VibeTooltip
+
+Tooltips for displaying contextual information. Requires Bootstrap JS and initialization.
+
+## 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 |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Element that triggers the tooltip |
+
+## Usage
+
+### Basic Tooltip
+
+```vue
+<template>
+  <VibeTooltip content="Tooltip text">
+    <VibeButton variant="secondary">Hover me</VibeButton>
+  </VibeTooltip>
+</template>
+```
+
+### Placement Options
+
+```vue
+<template>
+  <div>
+    <VibeTooltip content="Tooltip on top" placement="top">
+      <VibeButton variant="secondary">Top</VibeButton>
+    </VibeTooltip>
+
+    <VibeTooltip content="Tooltip on right" placement="end">
+      <VibeButton variant="secondary">End</VibeButton>
+    </VibeTooltip>
+
+    <VibeTooltip content="Tooltip on bottom" placement="bottom">
+      <VibeButton variant="secondary">Bottom</VibeButton>
+    </VibeTooltip>
+
+    <VibeTooltip content="Tooltip on left" placement="start">
+      <VibeButton variant="secondary">Start</VibeButton>
+    </VibeTooltip>
+  </div>
+</template>
+```
+
+### Custom Trigger
+
+```vue
+<template>
+  <VibeTooltip content="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.
+
+**Touch Optimization:** On touch devices, the tooltip automatically switches its trigger from `hover focus` to `click` to ensure reliable behavior on mobile screens.
+
+**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>
+```
+
+## Bootstrap CSS Classes
+
+- Uses Bootstrap's `data-bs-toggle="tooltip"` attributes
+- `.tooltip`
+- `.tooltip-arrow`
+- `.tooltip-inner`

package/docs/components/card/card.md

@@ -0,0 +1,215 @@
+# VibeCard
+
+Flexible content container component for displaying headers, bodies, footers, and images.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `Variant` | `undefined` | Background color variant |
+| `border` | `Variant` | `undefined` | Border color variant |
+| `textVariant` | `Variant` | `undefined` | Text color variant |
+| `tag` | `String` | `'div'` | HTML tag to render |
+| `title` | `String` | `undefined` | Card title |
+| `body` | `String` | `undefined` | Card body text |
+| `header` | `String` | `undefined` | Card header text |
+| `footer` | `String` | `undefined` | Card footer text |
+| `imgSrc` | `String` | `undefined` | Image URL |
+| `imgAlt` | `String` | `''` | Image alt text |
+| `imgTop` | `Boolean` | `true` | Display image at top |
+| `imgBottom` | `Boolean` | `false` | Display image at bottom |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Additional body content |
+| `header` | Custom header content |
+| `title` | Custom title content |
+| `body` | Custom body content |
+| `footer` | Custom footer content |
+
+## Usage
+
+### Basic Card
+
+```vue
+<template>
+  <VibeCard
+    title="Card Title"
+    body="This is the card body text. Quick and easy!"
+  />
+</template>
+```
+
+### Card with Header and Footer
+
+```vue
+<template>
+  <VibeCard
+    header="Featured"
+    title="Special title treatment"
+    body="With supporting text below as a natural lead-in."
+    footer="2 days ago"
+  />
+</template>
+```
+
+### Card with Image
+
+```vue
+<template>
+  <VibeCard
+    img-src="/path/to/image.jpg"
+    img-alt="Card image"
+    title="Card with Image"
+    body="This card has an image at the top."
+  />
+</template>
+```
+
+### Colored Cards
+
+```vue
+<template>
+  <div>
+    <VibeCard
+      variant="primary"
+      text-variant="white"
+      title="Primary Card"
+      body="Card with primary background."
+    />
+
+    <VibeCard
+      variant="success"
+      text-variant="white"
+      title="Success Card"
+      body="Card with success background."
+    />
+  </div>
+</template>
+```
+
+### Border Variants
+
+```vue
+<template>
+  <div>
+    <VibeCard
+      border="primary"
+      title="Primary Border"
+      body="Card with primary border."
+    />
+
+    <VibeCard
+      border="danger"
+      title="Danger Border"
+      body="Card with danger border."
+    />
+  </div>
+</template>
+```
+
+### Custom Content with Slots
+
+Use named slots for complex content:
+
+```vue
+<template>
+  <VibeCard>
+    <template #header>
+      <strong>Featured</strong>
+    </template>
+
+    <template #title>
+      Special Title Treatment
+    </template>
+
+    <template #body>
+      <p>With supporting text below as a natural lead-in.</p>
+    </template>
+
+    <!-- Additional body content via default slot -->
+    <VibeButton variant="primary">Go somewhere</VibeButton>
+
+    <template #footer>
+      <small class="text-muted">Last updated 3 mins ago</small>
+    </template>
+  </VibeCard>
+</template>
+```
+
+### Horizontal Card
+
+Use the default slot with Bootstrap grid:
+
+```vue
+<template>
+  <VibeCard>
+    <div class="row g-0">
+      <div class="col-md-4">
+        <img src="/path/to/image.jpg" alt="..." class="card-img">
+      </div>
+      <div class="col-md-8">
+        <div class="card-body">
+          <h5 class="card-title">Horizontal Card</h5>
+          <p class="card-text">
+            This is a wider card with supporting text.
+          </p>
+          <p class="card-text">
+            <small class="text-muted">Last updated 3 mins ago</small>
+          </p>
+        </div>
+      </div>
+    </div>
+  </VibeCard>
+</template>
+```
+
+### Card Grid
+
+```vue
+<template>
+  <div class="row row-cols-1 row-cols-md-3 g-4">
+    <div class="col">
+      <VibeCard
+        img-src="/path/to/image1.jpg"
+        img-alt="Card 1"
+        title="Card 1"
+        body="Card content here."
+      />
+    </div>
+    <div class="col">
+      <VibeCard
+        img-src="/path/to/image2.jpg"
+        img-alt="Card 2"
+        title="Card 2"
+        body="Card content here."
+      />
+    </div>
+    <div class="col">
+      <VibeCard
+        img-src="/path/to/image3.jpg"
+        img-alt="Card 3"
+        title="Card 3"
+        body="Card content here."
+      />
+    </div>
+  </div>
+</template>
+```
+
+## Bootstrap CSS Classes
+
+- `.card`
+- `.card-header`
+- `.card-body`
+- `.card-footer`
+- `.card-img-top`
+- `.card-img-bottom`
+- `.card-img`
+- `.card-title`
+- `.card-text`
+- `.bg-{variant}`
+- `.border-{variant}`
+- `.text-{variant}`