@velkymx/vibeui 0.8.0 → 0.8.2

package/docs/components/interactive/collapse.md

@@ -0,0 +1,105 @@
+# VibeCollapse
+
+Toggle visibility of content with smooth transitions.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `String` | `Auto-generated` | Unique identifier |
+| `modelValue` | `Boolean` | `false` | Control visibility (v-model) |
+| `tag` | `String` | `'div'` | HTML tag to render |
+| `horizontal` | `Boolean` | `false` | Horizontal collapse |
+| `isNav` | `Boolean` | `false` | Adds `navbar-collapse` class for use inside `VibeNavbar` |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `Boolean` | Emitted when visibility changes |
+| `show` | - | Emitted when collapse starts showing |
+| `shown` | - | Emitted when collapse is fully shown |
+| `hide` | - | Emitted when collapse starts hiding |
+| `hidden` | - | Emitted when collapse is fully hidden |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Collapsible content |
+
+## Usage
+
+### Reactive Usage (v-model)
+
+```vue
+<template>
+  <div>
+    <VibeButton variant="primary" @click="show = !show">
+      Toggle Collapse
+    </VibeButton>
+
+    <VibeCollapse v-model="show">
+      <div class="card card-body mt-2">
+        This content is controlled via Vue state with smooth animations.
+      </div>
+    </VibeCollapse>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+const show = ref(false)
+</script>
+```
+
+### Inside a Navbar
+
+When used inside a `VibeNavbar`, add `is-nav` to get the `navbar-collapse` class. `VibeNavbarToggle` will automatically synchronize with this component.
+
+```vue
+<template>
+  <VibeNavbar variant="dark" expand="lg">
+    <VibeNavbarBrand href="#">Brand</VibeNavbarBrand>
+    <VibeNavbarToggle target="navContent" />
+    <VibeCollapse id="navContent" is-nav>
+      <VibeNavbarNav :items="navItems" />
+    </VibeCollapse>
+  </VibeNavbar>
+</template>
+```
+
+### Horizontal Collapse
+
+```vue
+<template>
+  <div>
+    <VibeButton variant="primary" @click="show = !show">
+      Toggle Width
+    </VibeButton>
+
+    <div style="min-height: 120px">
+      <VibeCollapse v-model="show" horizontal>
+        <div class="card card-body" style="width: 300px">
+          This is horizontal collapse content!
+        </div>
+      </VibeCollapse>
+    </div>
+  </div>
+</template>
+```
+
+## Important Notes
+
+**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.
+
+**Instance Exposure:** You can access the underlying Bootstrap instance via template ref using the `bsInstance` property.
+
+## Bootstrap CSS Classes
+
+- `.collapse`
+- `.navbar-collapse` (when `is-nav` is set)
+- `.collapse-horizontal`
+- `.show`

package/docs/components/interactive/dropdown.md

@@ -0,0 +1,93 @@
+# VibeDropdown
+
+Data-driven toggleable contextual overlay for displaying lists of links.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `String` | `Auto-generated` | Unique identifier |
+| `text` | `String` | `'Dropdown'` | Button text |
+| `variant` | `Variant` | `'primary'` | Button color variant |
+| `size` | `Size` | `undefined` | Button size (`'sm'` or `'lg'`) |
+| `split` | `Boolean` | `false` | Split button style |
+| `direction` | `Direction` | `'down'` | Direction: `'up'`, `'down'`, `'start'`, `'end'` |
+| `menuEnd` | `Boolean` | `false` | Align menu to the right |
+| `items` | `DropdownItem[]` | Required | Array of dropdown items |
+| `autoClose` | `Boolean\|String` | `true` | Close behavior: `true`, `false`, `'inside'`, `'outside'` |
+
+### DropdownItem Interface
+
+```typescript
+interface DropdownItem {
+  text?: string
+  href?: string
+  to?: string | object
+  active?: boolean
+  disabled?: boolean
+  divider?: boolean
+  header?: boolean
+}
+```
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `item-click` | `{ item, index, event }` | Emitted when an item is clicked |
+| `show` | - | Emitted when dropdown starts showing |
+| `shown` | - | Emitted when dropdown is fully shown |
+| `hide` | - | Emitted when dropdown starts hiding |
+| `hidden` | - | Emitted when dropdown is fully hidden |
+
+## Slots
+
+| Slot | Scope | Description |
+|------|-------|-------------|
+| `button` | - | Custom button content |
+| `item` | `{ item, index }` | Custom item rendering |
+| `header` | `{ item, index }` | Custom header rendering |
+
+## Usage
+
+### Programmatic Control
+
+```vue
+<template>
+  <div>
+    <VibeButton @click="$refs.myDropdown.toggle()">External Toggle</VibeButton>
+    
+    <VibeDropdown
+      ref="myDropdown"
+      text="Dropdown Menu"
+      :items="dropdownItems"
+    />
+  </div>
+</template>
+```
+
+### Basic Dropdown
+
+```vue
+<template>
+  <VibeDropdown
+    text="Dropdown Menu"
+    :items="dropdownItems"
+  />
+</template>
+```
+
+## 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.
+
+## Bootstrap CSS Classes
+
+- `.dropdown`, `.dropup`, `.dropend`, `.dropstart`
+- `.dropdown-toggle`
+- `.dropdown-menu`
+- `.dropdown-item`

package/docs/components/interactive/modal.md

@@ -0,0 +1,148 @@
+# VibeModal
+
+Modal dialogs for lightboxes, user notifications, or custom content.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `String` | `Auto-generated` | Unique identifier for the modal |
+| `modelValue` | `Boolean` | `false` | Control visibility (v-model) |
+| `title` | `String` | `''` | Modal title |
+| `size` | `Size\|'xl'` | `undefined` | Modal size: `'sm'`, `'lg'`, `'xl'` |
+| `centered` | `Boolean` | `false` | Vertically center modal |
+| `scrollable` | `Boolean` | `false` | Scrollable modal body |
+| `fullscreen` | `Boolean\|String` | `false` | Fullscreen: `true` or breakpoint |
+| `staticBackdrop` | `Boolean` | `false` | Don't close on backdrop click |
+| `hideHeader` | `Boolean` | `false` | Hide header section |
+| `hideFooter` | `Boolean` | `false` | Hide footer section |
+| `teleport` | `Boolean\|String` | `'body'` | Destination for Vue Teleport |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `Boolean` | Emitted when modal visibility changes |
+| `show` | - | Emitted when modal starts showing |
+| `shown` | - | Emitted when modal is fully shown |
+| `hide` | - | Emitted when modal starts hiding |
+| `hidden` | - | Emitted when modal is fully hidden |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Modal body content |
+| `header` | Custom header content |
+| `footer` | Custom footer content |
+
+## Usage
+
+### Reactive Usage (v-model)
+
+```vue
+<template>
+  <div>
+    <VibeButton variant="primary" @click="showModal = true">
+      Open Modal
+    </VibeButton>
+
+    <VibeModal v-model="showModal" title="Reactive Modal">
+      <p>This modal is controlled via Vue state.</p>
+    </VibeModal>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+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
+<template>
+  <div>
+    <VibeModal title="Small Modal" size="sm">
+      Small modal content
+    </VibeModal>
+
+    <VibeModal title="Large Modal" size="lg">
+      Large modal content
+    </VibeModal>
+  </div>
+</template>
+```
+
+### Centered Modal
+
+```vue
+<template>
+  <VibeModal title="Centered Modal" centered>
+    This modal is vertically centered.
+  </VibeModal>
+</template>
+```
+
+### Custom Footer
+
+```vue
+<template>
+  <VibeModal 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>
+    </template>
+  </VibeModal>
+</template>
+```
+
+## Important Notes
+
+**Automatic Initialization:** This component automatically initializes Bootstrap's Modal functionality when it is mounted, provided that Bootstrap's JavaScript is available in your project.
+
+**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.
+
+## Mobile Optimization
+
+**Safe Areas:** In fullscreen mode, the modal header and footer automatically respect device safe areas (notches) in hybrid apps.
+
+**Hardware Back Button:** On Android devices in hybrid environments, the hardware back button will automatically close the modal if it is open.
+
+**Dynamic Height:** Fullscreen modals use `dvh` (dynamic viewport height) units to ensure they occupy the full screen height even when mobile browser bars are visible.
+
+## Bootstrap CSS Classes
+
+- `.modal`
+- `.modal-dialog`
+- `.modal-content`
+- `.modal-header`
+- `.modal-title`
+- `.modal-body`
+- `.modal-footer`
+- `.modal-{size}`
+- `.modal-dialog-centered`
+- `.modal-dialog-scrollable`
+- `.modal-fullscreen`

package/docs/components/interactive/offcanvas.md

@@ -0,0 +1,89 @@
+# VibeOffcanvas
+
+Hidden sidebar for navigation or additional content.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `String` | `Auto-generated` | Unique identifier |
+| `modelValue` | `Boolean` | `false` | Control visibility (v-model) |
+| `title` | `String` | `''` | Offcanvas title |
+| `placement` | `OffcanvasPlacement` | `'start'` | Placement: `'start'`, `'end'`, `'top'`, `'bottom'` |
+| `backdrop` | `Boolean\|String` | `true` | Backdrop: `true`, `false`, or `'static'` |
+| `scroll` | `Boolean` | `false` | Allow body scrolling |
+| `teleport` | `Boolean\|String` | `'body'` | Destination for Vue Teleport |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `Boolean` | Emitted when visibility changes |
+| `show` | - | Emitted when offcanvas starts showing |
+| `shown` | - | Emitted when offcanvas is fully shown |
+| `hide` | - | Emitted when offcanvas starts hiding |
+| `hidden` | - | Emitted when offcanvas is fully hidden |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Offcanvas body content |
+| `header` | Custom header content |
+
+## Usage
+
+### Reactive Usage (v-model)
+
+```vue
+<template>
+  <div>
+    <VibeButton variant="primary" @click="showOffcanvas = true">
+      Open Offcanvas
+    </VibeButton>
+
+    <VibeOffcanvas v-model="showOffcanvas" title="Reactive Offcanvas">
+      This offcanvas is controlled via Vue state.
+    </VibeOffcanvas>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+const showOffcanvas = ref(false)
+</script>
+```
+
+### Placement Options
+
+```vue
+<template>
+  <VibeOffcanvas title="Right Side" placement="end">
+    Content on the right
+  </VibeOffcanvas>
+</template>
+```
+
+## Important Notes
+
+**Automatic Initialization:** This component automatically initializes Bootstrap's Offcanvas functionality when it is mounted, provided that Bootstrap's JavaScript is available in your project.
+
+**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.
+
+## Mobile Optimization
+
+**Safe Areas:** When used in hybrid apps with `viewport-fit=cover`, the offcanvas header automatically adds padding to account for device notches.
+
+**Hardware Back Button:** On Android devices in hybrid environments, the hardware back button will automatically close the offcanvas if it is open.
+
+**Dynamic Height:** The offcanvas uses `dvh` (dynamic viewport height) units to ensure it occupies the full screen height even when mobile browser bars are visible.
+
+## Bootstrap CSS Classes
+
+- `.offcanvas`
+- `.offcanvas-{placement}`
+- `.offcanvas-header`
+- `.offcanvas-title`
+- `.offcanvas-body`

package/docs/components/interactive/toast.md

@@ -0,0 +1,114 @@
+# VibeToast
+
+Push notifications for lightweight alerts.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `String` | `Auto-generated` | Unique identifier |
+| `modelValue` | `Boolean` | `false` | Control visibility (v-model) |
+| `title` | `String` | `''` | Toast title |
+| `variant` | `Variant` | `undefined` | Color variant |
+| `autohide` | `Boolean` | `true` | Auto hide after delay |
+| `delay` | `Number` | `5000` | Delay in milliseconds |
+| `teleport` | `Boolean\|String` | `'body'` | Destination for Vue Teleport |
+| `placement` | `ToastPlacement` | `'top-end'` | Position of the toast |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `Boolean` | Emitted when visibility changes |
+| `show` | - | Emitted when toast starts showing |
+| `shown` | - | Emitted when toast is fully shown |
+| `hide` | - | Emitted when toast starts hiding |
+| `hidden` | - | Emitted when toast is fully hidden |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Toast body content |
+| `header` | Custom header content |
+
+## Usage
+
+### Reactive Usage (v-model)
+
+```vue
+<template>
+  <div>
+    <VibeButton @click="showToast = true">Show Toast</VibeButton>
+
+    <VibeToast v-model="showToast" title="Notification" variant="primary">
+      This toast is controlled via Vue state.
+    </VibeToast>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+const showToast = ref(false)
+</script>
+```
+
+### Placed Toasts
+
+```vue
+<template>
+  <div>
+    <VibeToast title="Success" variant="success" placement="bottom-end">
+      Operation completed successfully!
+    </VibeToast>
+
+    <VibeToast title="Center" variant="info" placement="middle-center">
+      I am in the middle of the screen
+    </VibeToast>
+  </div>
+</template>
+```
+
+### Colored Toasts
+
+```vue
+<template>
+  <div>
+    <VibeToast title="Success" variant="success">
+      Operation completed successfully!
+    </VibeToast>
+
+    <VibeToast title="Warning" variant="warning">
+      Please review your changes
+    </VibeToast>
+  </div>
+</template>
+```
+
+### Custom Delay
+
+```vue
+<template>
+  <VibeToast title="Quick Toast" :delay="2000">
+    This will auto-hide after 2 seconds
+  </VibeToast>
+</template>
+```
+
+## Important Notes
+
+**Automatic Initialization:** This component automatically initializes Bootstrap's Toast functionality when it is mounted, provided that Bootstrap's JavaScript is available in your project.
+
+**Automatic Container:** Unlike raw Bootstrap, VibeToast automatically manages its own `toast-container` and positioning based on the `placement` prop.
+
+**Teleportation:** By default, this component teleports to the `<body>` to ensure it is always visible on top of other elements.
+
+**Instance Exposure:** You can access the underlying Bootstrap instance via template ref using the `bsInstance` property.
+
+## Bootstrap CSS Classes
+
+- `.toast`
+- `.toast-header`
+- `.toast-body`
+- `.text-bg-{variant}`
+- `.toast-container`

package/docs/components/layout/col.md

@@ -0,0 +1,123 @@
+# VibeCol
+
+Column component for Bootstrap's grid system. Supports responsive sizing, offsets, ordering, and alignment.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tag` | `Tag` | `'div'` | HTML element to render |
+| `cols` | `ColSize \| Boolean` | `undefined` | Base column width (`1`-`12`, `'auto'`, or `true` for equal-width) |
+| `sm` | `ColSize \| Boolean` | `undefined` | Column width at `sm` breakpoint |
+| `md` | `ColSize \| Boolean` | `undefined` | Column width at `md` breakpoint |
+| `lg` | `ColSize \| Boolean` | `undefined` | Column width at `lg` breakpoint |
+| `xl` | `ColSize \| Boolean` | `undefined` | Column width at `xl` breakpoint |
+| `xxl` | `ColSize \| Boolean` | `undefined` | Column width at `xxl` breakpoint |
+| `offset` | `Number` | `undefined` | Base offset (`0`-`11`) |
+| `offsetSm` | `Number` | `undefined` | Offset at `sm` breakpoint |
+| `offsetMd` | `Number` | `undefined` | Offset at `md` breakpoint |
+| `offsetLg` | `Number` | `undefined` | Offset at `lg` breakpoint |
+| `offsetXl` | `Number` | `undefined` | Offset at `xl` breakpoint |
+| `offsetXxl` | `Number` | `undefined` | Offset at `xxl` breakpoint |
+| `order` | `OrderValue` | `undefined` | Base visual order |
+| `orderSm` | `OrderValue` | `undefined` | Order at `sm` breakpoint |
+| `orderMd` | `OrderValue` | `undefined` | Order at `md` breakpoint |
+| `orderLg` | `OrderValue` | `undefined` | Order at `lg` breakpoint |
+| `orderXl` | `OrderValue` | `undefined` | Order at `xl` breakpoint |
+| `orderXxl` | `OrderValue` | `undefined` | Order at `xxl` breakpoint |
+| `alignSelf` | `AlignItems` | `undefined` | Individual column vertical alignment |
+
+### Type Reference
+
+- **ColSize:** `1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 'auto'`
+- **OrderValue:** `0 | 1 | 2 | 3 | 4 | 5 | 'first' | 'last'`
+- **AlignItems:** `'start' | 'center' | 'end' | 'baseline' | 'stretch'`
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `component-error` | `Object` | Emitted when an error occurs |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Column content |
+
+## Usage
+
+### Equal-width Columns
+
+```vue
+<template>
+  <VibeRow>
+    <!-- No sizing props = equal-width (col class) -->
+    <VibeCol>1 of 3</VibeCol>
+    <VibeCol>2 of 3</VibeCol>
+    <VibeCol>3 of 3</VibeCol>
+  </VibeRow>
+</template>
+```
+
+### Specific Widths
+
+```vue
+<template>
+  <VibeRow>
+    <VibeCol :cols="8">Main content</VibeCol>
+    <VibeCol :cols="4">Sidebar</VibeCol>
+  </VibeRow>
+</template>
+```
+
+### Responsive Columns
+
+```vue
+<template>
+  <VibeRow>
+    <!-- Full width on mobile, half on medium, third on large -->
+    <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>
+</template>
+```
+
+### Auto-width Column
+
+```vue
+<template>
+  <VibeRow>
+    <VibeCol :cols="2">Fixed</VibeCol>
+    <VibeCol cols="auto">Sized to content</VibeCol>
+    <VibeCol :cols="2">Fixed</VibeCol>
+  </VibeRow>
+</template>
+```
+
+### Offsets and Ordering
+
+```vue
+<template>
+  <VibeRow>
+    <VibeCol :cols="4" :offset="4">Centered column</VibeCol>
+  </VibeRow>
+
+  <VibeRow>
+    <VibeCol :cols="6" order="last">Appears second</VibeCol>
+    <VibeCol :cols="6" order="first">Appears first</VibeCol>
+  </VibeRow>
+</template>
+```
+
+### Vertical Alignment
+
+```vue
+<template>
+  <VibeRow align-items="start" style="height: 200px;">
+    <VibeCol>Top-aligned</VibeCol>
+    <VibeCol align-self="end">Bottom-aligned</VibeCol>
+  </VibeRow>
+</template>
+```