@velkymx/vibeui 0.9.0 → 1.1.0

package/docs/components/navigation/breadcrumb.md

@@ -0,0 +1,120 @@
+# VibeBreadcrumb
+
+Data-driven breadcrumb navigation to indicate the current page's location within a navigational hierarchy.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `ariaLabel` | `String` | `'breadcrumb'` | ARIA label for navigation |
+| `items` | `BreadcrumbItem[]` | Required | Array of breadcrumb items |
+
+### BreadcrumbItem Interface
+
+```typescript
+interface BreadcrumbItem {
+  text: string
+  href?: string
+  to?: string | object
+  active?: boolean
+}
+```
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `item-click` | `{ item, index, event }` | Emitted when an item is clicked (unless active) |
+
+## Slots
+
+| Slot | Scope | Description |
+|------|-------|-------------|
+| `item` | `{ item, index }` | Custom item rendering |
+
+## Usage
+
+### Basic Example
+
+```vue
+<template>
+  <VibeBreadcrumb :items="breadcrumbItems" />
+</template>
+
+<script setup>
+const breadcrumbItems = [
+  { text: 'Home', href: '/' },
+  { text: 'Library', href: '/library' },
+  { text: 'Data', active: true }
+]
+</script>
+```
+
+### With Router Links
+
+```vue
+<template>
+  <VibeBreadcrumb :items="breadcrumbItems" />
+</template>
+
+<script setup>
+const breadcrumbItems = [
+  { text: 'Home', to: { name: 'home' } },
+  { text: 'Products', to: { name: 'products' } },
+  { text: 'Details', active: true }
+]
+</script>
+```
+
+### Custom Item Rendering
+
+Use the `item` scoped slot for custom rendering:
+
+```vue
+<template>
+  <VibeBreadcrumb :items="breadcrumbItems">
+    <template #item="{ item, index }">
+      <VibeIcon v-if="item.icon" :icon="item.icon" class="me-1" />
+      {{ item.text }}
+    </template>
+  </VibeBreadcrumb>
+</template>
+
+<script setup>
+const breadcrumbItems = [
+  { text: 'Home', href: '/', icon: 'house-fill' },
+  { text: 'Library', href: '/library', icon: 'book' },
+  { text: 'Data', active: true, icon: 'file-earmark' }
+]
+</script>
+```
+
+### With Event Handling
+
+```vue
+<template>
+  <VibeBreadcrumb :items="breadcrumbItems" @item-click="handleClick" />
+</template>
+
+<script setup>
+const breadcrumbItems = [
+  { text: 'Home', href: '/' },
+  { text: 'Products', href: '/products' },
+  { text: 'Details', active: true }
+]
+
+const handleClick = ({ item, index }) => {
+  console.log(`Clicked: ${item.text} at index ${index}`)
+}
+</script>
+```
+
+## Important Notes
+
+**`href` sanitization:** Item `href` values are sanitized. Only `https?://`, root-relative (`/path`), relative (`./`, `../`), and anchor (`#anchor`) URLs are allowed. `javascript:`, `data:`, and protocol-relative (`//`) URLs are stripped — such items render as plain text instead of links. Use `to` for Vue Router navigation.
+
+## Bootstrap CSS Classes
+
+- `.breadcrumb`
+- `.breadcrumb-item`
+- `.active`

package/docs/components/navigation/nav.md

@@ -0,0 +1,151 @@
+# VibeNav
+
+Data-driven navigation tabs and pills for organizing content.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tabs` | `Boolean` | `false` | Use tabs style |
+| `pills` | `Boolean` | `false` | Use pills style |
+| `underline` | `Boolean` | `false` | Use the new Bootstrap 5.3 underline style |
+| `fill` | `Boolean` | `false` | Fill available width proportionally |
+| `justified` | `Boolean` | `false` | Fill available width equally |
+| `vertical` | `Boolean` | `false` | Stack navigation vertically |
+| `tag` | `String` | `'ul'` | HTML tag to render |
+| `items` | `NavItem[]` | Required | Array of nav items |
+
+### NavItem Interface
+
+```typescript
+interface NavItem {
+  text: string
+  href?: string
+  to?: string | object
+  /** Tab panel selector (e.g. '#panel-id') for tabs/pills mode with router-link items */
+  target?: string
+  active?: boolean
+  disabled?: boolean
+  children?: NavItem[] // Support for dropdowns
+}
+```
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `item-click` | `{ item, index, event }` | Emitted when item is clicked |
+| `show` | `event` | Emitted when a tab starts showing |
+| `shown` | `event` | Emitted when a tab is fully shown |
+| `hide` | `event` | Emitted when a tab starts hiding |
+| `hidden` | `event` | Emitted when a tab is fully hidden |
+
+## Slots
+
+| Slot | Scope | Description |
+|------|-------|-------------|
+| `item` | `{ item, index }` | Custom item rendering |
+
+## Usage
+
+### Custom item content (`#item` slot)
+
+Use the `item` slot to render richer nav links — e.g. an icon next to the label. The slot is scoped with `{ item, index }`.
+
+```vue
+<template>
+  <VibeNav :items="navItems">
+    <template #item="{ item }">
+      <VibeIcon :icon="item.icon" class="me-2" />
+      {{ item.text }}
+    </template>
+  </VibeNav>
+</template>
+
+<script setup>
+const navItems = [
+  { text: 'Home', href: '#', icon: 'house', active: true },
+  { text: 'Profile', href: '#', icon: 'person' }
+]
+</script>
+```
+
+### Interactive Tabs
+
+When using the `tabs` or `pills` props, nav links with an `href` starting with `#` will automatically act as Bootstrap tab triggers.
+
+```vue
+<template>
+  <div>
+    <VibeNav tabs :items="navItems" />
+    
+    <VibeTabContent :panes="tabPanes" class="mt-3" />
+  </div>
+</template>
+
+<script setup>
+const navItems = [
+  { text: 'Home', href: '#home', active: true },
+  { text: 'Profile', href: '#profile' }
+]
+
+const tabPanes = [
+  { id: 'home', content: 'Home content...', active: true },
+  { id: 'profile', content: 'Profile content...' }
+]
+</script>
+```
+
+### Tabs with Vue Router Links
+
+Items using `to` (router-link) also work in tabs/pills mode. Provide a `target` field pointing to the panel ID, and Bootstrap Tab events (`show`, `shown`, `hide`, `hidden`) will fire correctly:
+
+```vue
+<template>
+  <VibeNav tabs :items="navItems" @shown="onShown" />
+  <div class="tab-content mt-3">
+    <div id="overview-pane" class="tab-pane fade show active">Overview content</div>
+    <div id="settings-pane" class="tab-pane fade">Settings content</div>
+  </div>
+</template>
+
+<script setup>
+const navItems = [
+  { text: 'Overview', to: '/overview', target: '#overview-pane', active: true },
+  { text: 'Settings', to: '/settings', target: '#settings-pane' }
+]
+
+const onShown = (event) => {
+  console.log('Tab shown:', event.target)
+}
+</script>
+```
+
+Items with `to` starting with `#` are also treated as tab targets without needing an explicit `target` field.
+
+## Exposed Methods
+
+| Method | Description |
+|--------|-------------|
+| `refresh()` | Tears down and re-initializes Bootstrap Tab instances. Call after dynamically changing items if needed. |
+
+> **Escape hatch:** `_unsafe_bsInstances` (a `Map` of the underlying Bootstrap `Tab` instances) is also exposed. It is **not** part of the stable API — calling `dispose()` or other lifecycle methods on these directly WILL break the component.
+
+## Important Notes
+
+**`href` sanitization:** Item and child `href` values are sanitized. Only `https?://`, root-relative (`/path`), relative (`./`, `../`), and anchor (`#anchor`) URLs are allowed; `javascript:`, `data:`, and protocol-relative (`//`) URLs are stripped. Use `to` for Vue Router navigation.
+
+**Disabled button items:** Items without `href` or `to` (plain button items) receive the HTML `disabled` attribute when `disabled: true` is set. Link and router-link items only get the disabled visual style — the browser attribute is omitted because `<a disabled>` has no native effect.
+
+**Automatic Initialization:** When using `tabs` or `pills`, this component automatically initializes Bootstrap's Tab functionality for items that target a local panel ID via `href="#..."`, `target="#..."`, or `to="#..."`.
+
+**State Management:** For complex tab state, combine `VibeNav` with `VibeTabContent` and manage the `active` state through your data.
+
+## Bootstrap CSS Classes
+
+- `.nav`
+- `.nav-tabs`
+- `.nav-pills`
+- `.nav-underline`
+- `.nav-item`
+- `.nav-link`

package/docs/components/navigation/navbar.md

@@ -0,0 +1,114 @@
+# Navbar Components
+
+Responsive navigation header with support for branding, navigation, and collapsible content.
+
+## VibeNavbar
+
+Main navbar container. Provides reactive collapse state to child components via Vue's provide/inject.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `Variant\|'dark'\|'light'` | `'light'` | Background color: maps to `bg-{variant}` |
+| `theme` | `'dark'\|'light'` | auto | Color scheme applied via `data-bs-theme`. Defaults to `'dark'` when `variant='dark'`, `'light'` when `variant='light'`, otherwise unset |
+| `expand` | `Boolean\|String` | `'lg'` | Breakpoint for collapse: `'sm'`, `'md'`, `'lg'`, `'xl'`, or `true` for always expanded |
+| `container` | `Boolean\|String` | `true` | Container type: `true` for fluid, or `'sm'`, `'md'`, `'lg'`, `'xl'` |
+| `position` | `NavbarPosition` | `undefined` | Position: `'fixed-top'`, `'fixed-bottom'`, `'sticky-top'` |
+| `tag` | `String` | `'nav'` | HTML tag to render |
+
+## Sub-Components
+
+### VibeNavbarBrand
+Branding/logo section
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `href` | `String` | `undefined` | Link URL (renders as `<a>`) |
+| `to` | `String\|Object` | `undefined` | Router link target (renders as `<router-link>`) |
+
+### VibeNavbarToggle
+Mobile collapse toggle button.
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `target` | `String` | Required | The `id` of the `VibeCollapse` to toggle |
+| `ariaLabel` | `String` | `'Toggle navigation'` | Accessible label for the button |
+
+#### Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `component-error` | `ComponentError` | Emitted if the Bootstrap collapse toggle fails (e.g. Bootstrap JS unavailable) |
+
+### VibeNavbarNav
+Navigation links container. Supports regular links and dropdown items.
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tag` | `String` | `'ul'` | HTML tag to render |
+| `items` | `NavItem[]` | `undefined` | Array of nav items (data-driven mode) |
+
+#### Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `item-click` | `{ item, index, event }` | Emitted when a regular nav item is clicked |
+| `dropdown-item-click` | `{ item, itemIndex, child, childIndex, event }` | Emitted when a dropdown child item is clicked |
+
+## Usage
+
+### Basic Navbar
+
+```vue
+<template>
+  <VibeNavbar variant="light" expand="lg">
+    <VibeNavbarBrand href="#">Navbar</VibeNavbarBrand>
+    <VibeNavbarToggle target="navbarNav" />
+    <VibeCollapse id="navbarNav" is-nav>
+      <VibeNavbarNav :items="navItems" />
+    </VibeCollapse>
+  </VibeNavbar>
+</template>
+
+<script setup>
+const navItems = [
+  { text: 'Home', href: '#', active: true },
+  { text: 'Features', href: '#' },
+  { text: 'Pricing', href: '#' }
+]
+</script>
+```
+
+## Important Notes
+
+**`href` sanitization:** `VibeNavbarBrand` (and `VibeNavbarNav` items) sanitize `href` values. Only `https?://`, root-relative (`/path`), relative (`./`, `../`), and anchor (`#anchor`) URLs are allowed; `javascript:`, `data:`, and protocol-relative (`//`) URLs are stripped. Use `to` for Vue Router navigation.
+
+**Automatic Synchronization:** `VibeNavbarToggle` is refactored to ensure that clicking it updates both Vue's internal state and the underlying Bootstrap `Collapse` instance simultaneously.
+
+**Smooth Transitions:** `VibeCollapse` now utilizes Bootstrap's JavaScript engine by default, providing smooth sliding animations when toggled via the navbar.
+
+**State Management:** Even when using Bootstrap JS for animations, the navbar remains fully reactive. You can still control the collapse state programmatically via the `VibeCollapse` `v-model`.
+
+## Mobile & Hybrid Optimization
+
+**Safe Areas:** When using `position="fixed-top"`, `fixed-bottom"`, or `sticky-top"`, the navbar automatically adds padding to account for device safe areas (notches) in hybrid environments like Capacitor.
+
+## Bootstrap CSS Classes
+
+- `.navbar`
+- `.navbar-expand-{breakpoint}`
+- `.bg-{variant}`
+- `data-bs-theme="dark|light"`
+- `.navbar-brand`
+- `.navbar-toggler`
+- `.navbar-nav`
+- `.navbar-collapse`
+- `.nav-item`
+- `.nav-link`

package/docs/components/navigation/pagination.md

@@ -0,0 +1,163 @@
+# VibePagination
+
+Data-driven pagination component with v-model support.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `size` | `'sm' \| 'lg'` | `undefined` | Pagination size |
+| `ariaLabel` | `String` | `'Pagination'` | ARIA label for the nav element |
+| `totalPages` | `Number` | Required | Total number of pages |
+| `currentPage` | `Number` | `1` | Current active page |
+| `showPrevNext` | `Boolean` | `true` | Show previous/next buttons |
+| `prevText` | `String` | `'Previous'` | Text for previous button |
+| `nextText` | `String` | `'Next'` | Text for next button |
+| `maxVisiblePages` | `Number` | `7` | Maximum page buttons to show before collapsing to ellipsis |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:currentPage` | `page: number` | Emitted when page changes (v-model) |
+| `page-click` | `page: number` | Emitted when a page is clicked |
+| `component-error` | `ComponentError` | Emitted if an internal error occurs |
+
+## Slots
+
+| Slot | Scope | Description |
+|------|-------|-------------|
+| `prev` | `{ disabled }` | Custom previous button |
+| `page` | `{ page, active }` | Custom page button |
+| `next` | `{ disabled }` | Custom next button |
+
+## Usage
+
+### Basic Example
+
+```vue
+<template>
+  <VibePagination
+    :total-pages="10"
+    v-model:current-page="currentPage"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const currentPage = ref(1)
+</script>
+```
+
+### Sizes
+
+```vue
+<template>
+  <!-- Small -->
+  <VibePagination :total-pages="5" size="sm" v-model:current-page="page1" />
+
+  <!-- Default -->
+  <VibePagination :total-pages="5" v-model:current-page="page2" />
+
+  <!-- Large -->
+  <VibePagination :total-pages="5" size="lg" v-model:current-page="page3" />
+</template>
+```
+
+### Without Prev/Next Buttons
+
+```vue
+<template>
+  <VibePagination
+    :total-pages="10"
+    :show-prev-next="false"
+    v-model:current-page="currentPage"
+  />
+</template>
+```
+
+### Custom Button Text
+
+```vue
+<template>
+  <VibePagination
+    :total-pages="10"
+    prev-text="← Back"
+    next-text="Forward →"
+    v-model:current-page="currentPage"
+  />
+</template>
+```
+
+### Large Page Counts (Ellipsis)
+
+When `totalPages` exceeds `maxVisiblePages`, intermediate pages are replaced with ellipsis (`…`). First and last pages are always shown, and the window of visible pages tracks the current page.
+
+```vue
+<template>
+  <!-- 100 pages, only 7 buttons max — ellipsis collapses the rest -->
+  <VibePagination
+    :total-pages="100"
+    v-model:current-page="currentPage"
+    :max-visible-pages="7"
+  />
+</template>
+```
+
+### Custom Page Rendering
+
+Use scoped slots for complete customization:
+
+```vue
+<template>
+  <VibePagination :total-pages="10" v-model:current-page="currentPage">
+    <template #prev="{ disabled }">
+      <VibeIcon icon="chevron-left" />
+    </template>
+
+    <template #page="{ page, active }">
+      Page {{ page }}
+    </template>
+
+    <template #next="{ disabled }">
+      <VibeIcon icon="chevron-right" />
+    </template>
+  </VibePagination>
+</template>
+```
+
+### With Event Handling
+
+```vue
+<template>
+  <VibePagination
+    :total-pages="20"
+    v-model:current-page="currentPage"
+    @page-click="handlePageClick"
+  />
+
+  <p>Current page: {{ currentPage }}</p>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const currentPage = ref(1)
+
+const handlePageClick = (page) => {
+  console.log(`Navigated to page ${page}`)
+  // Fetch data for the new page
+}
+</script>
+```
+
+## Bootstrap CSS Classes
+
+- `.pagination`
+- `.pagination-sm`
+- `.pagination-lg`
+- `.page-item`
+- `.page-link`
+- `.active`
+- `.disabled`