@velkymx/vibeui 0.9.0 → 1.0.2

package/docs/components/interactive/accordion.md

@@ -0,0 +1,121 @@
+# VibeAccordion
+
+Collapsible accordion component for organizing content in a data-driven way.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `String` | `Auto-generated` | Unique identifier for the accordion |
+| `flush` | `Boolean` | `false` | Remove borders and rounded corners |
+| `items` | `AccordionItem[]` | Required | Array of accordion items |
+| `alwaysOpen` | `Boolean` | `false` | Don't collapse other items when one is opened |
+
+### AccordionItem Interface
+
+```typescript
+interface AccordionItem {
+  id: string
+  title: string
+  content: string
+  show?: boolean
+}
+```
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `item-click` | `{ item, index }` | Emitted when an accordion item is clicked |
+| `show` | `id` | Emitted when an item starts showing |
+| `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
+
+| Slot | Scope | Description |
+|------|-------|-------------|
+| `title` | `{ item, index }` | Custom title rendering |
+| `content` | `{ item, index }` | Custom content rendering |
+
+## Usage
+
+### Basic Example
+
+```vue
+<template>
+  <VibeAccordion :items="accordionItems" />
+</template>
+
+<script setup>
+const accordionItems = [
+  {
+    id: 'collapseOne',
+    title: 'Accordion Item #1',
+    content: 'This is the first item\'s content.',
+    show: true
+  },
+  {
+    id: 'collapseTwo',
+    title: 'Accordion Item #2',
+    content: 'This is the second item\'s content.'
+  }
+]
+</script>
+```
+
+### Always Open
+
+Items stay open when another item is opened:
+
+```vue
+<template>
+  <VibeAccordion always-open :items="accordionItems" />
+</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`
+- `.accordion-flush`
+- `.accordion-item`
+- `.accordion-header`
+- `.accordion-button`
+- `.accordion-collapse`
+- `.accordion-body`

package/docs/components/interactive/carousel.md

@@ -0,0 +1,112 @@
+# VibeCarousel
+
+Data-driven slideshow component for cycling through images or content.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `String` | `Auto-generated` | Unique identifier |
+| `modelValue` | `Number` | `0` | Active slide index (v-model) |
+| `controls` | `Boolean` | `true` | Show prev/next controls |
+| `indicators` | `Boolean` | `true` | Show slide indicators |
+| `ride` | `Boolean\|String` | `false` | Auto-play: `false`, `true`, or `'carousel'` |
+| `interval` | `Number\|Boolean` | `5000` | Slide interval in ms (`false` to disable) |
+| `keyboard` | `Boolean` | `true` | Keyboard navigation |
+| `pause` | `String\|Boolean` | `'hover'` | Pause on hover (`'hover'` or `false`) |
+| `wrap` | `Boolean` | `true` | Continuous cycling |
+| `touch` | `Boolean` | `true` | Touch swipe support |
+| `dark` | `Boolean` | `false` | Dark variant indicators/controls |
+| `fade` | `Boolean` | `false` | Fade transition instead of slide |
+| `items` | `CarouselItem[]` | Required | Array of carousel items |
+
+### CarouselItem Interface
+
+```typescript
+interface CarouselItem {
+  src: string
+  alt?: string
+  caption?: string
+  captionText?: string
+  active?: boolean
+  interval?: number
+}
+```
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `Number` | Emitted when the active slide changes |
+| `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
+
+| Slot | Scope | Description |
+|------|-------|-------------|
+| `caption` | `{ item, index }` | Custom caption rendering |
+
+## Usage
+
+### Reactive Usage (v-model)
+
+```vue
+<template>
+  <div>
+    <VibeCarousel v-model="currentSlide" :items="carouselItems" />
+    
+    <div class="mt-3">
+      <VibeButton @click="currentSlide = 0">Go to Slide 1</VibeButton>
+      <VibeButton @click="currentSlide = 1">Go to Slide 2</VibeButton>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+const currentSlide = ref(0)
+const carouselItems = [
+  { src: '/img/slide-1.jpg', caption: 'First slide', captionText: 'Intro copy' },
+  { src: '/img/slide-2.jpg', caption: 'Second slide' }
+]
+</script>
+```
+
+### Basic Carousel
+
+```vue
+<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.
+
+**`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
+
+- `.carousel`
+- `.carousel-inner`
+- `.carousel-item`
+- `.carousel-control-prev`
+- `.carousel-control-next`
+- `.carousel-indicators`
+- `.carousel-caption`
+- `.carousel-dark`
+- `.carousel-fade`

package/docs/components/interactive/collapse.md

@@ -0,0 +1,106 @@
+# 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 |
+| `component-error` | `ComponentError` | Emitted if Bootstrap JS fails to load |
+
+## 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:** 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.
+
+**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
+
+- `.collapse`
+- `.navbar-collapse` (when `is-nav` is set)
+- `.collapse-horizontal`
+- `.show`

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

@@ -0,0 +1,129 @@
+# 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 |
+| `component-error` | `ComponentError` | Emitted if Bootstrap JS fails to load |
+
+## Slots
+
+| Slot | Scope | Description |
+|------|-------|-------------|
+| `button` | - | Custom button content |
+| `item` | `{ item, index }` | Custom item rendering |
+| `header` | `{ item, index }` | Custom header rendering |
+
+## Usage
+
+### Basic Dropdown
+
+```vue
+<template>
+  <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>
+```
+
+### 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="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:** The component exposes `show()`, `hide()`, and `toggle()` via template refs for programmatic control.
+
+## Bootstrap CSS Classes
+
+- `.dropdown`, `.dropup`, `.dropend`, `.dropstart`
+- `.dropdown-toggle`
+- `.dropdown-menu`
+- `.dropdown-item`