@velkymx/vibeui 0.8.0 → 0.8.2

package/docs/components/layout/container.md

@@ -0,0 +1,59 @@
+# VibeContainer
+
+Responsive container component wrapping Bootstrap's `.container`, `.container-fluid`, and `.container-{breakpoint}` classes.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `fluid` | `Boolean \| ContainerType` | `false` | `false` = `.container`, `true` = `.container-fluid`, or a breakpoint (`'sm'`, `'md'`, `'lg'`, `'xl'`, `'xxl'`) for `.container-{breakpoint}` |
+| `tag` | `Tag` | `'div'` | HTML element to render |
+
+### ContainerType
+
+`'sm' | 'md' | 'lg' | 'xl' | 'xxl'`
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `component-error` | `Object` | Emitted when an error occurs |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Container content |
+
+## Usage
+
+### Fixed-width Container
+
+```vue
+<template>
+  <VibeContainer>
+    <p>Responsive fixed-width container</p>
+  </VibeContainer>
+</template>
+```
+
+### Fluid Container
+
+```vue
+<template>
+  <VibeContainer fluid>
+    <p>Full-width container spanning the entire viewport</p>
+  </VibeContainer>
+</template>
+```
+
+### Responsive Breakpoint Container
+
+```vue
+<template>
+  <!-- 100% wide until the md breakpoint, then fixed-width -->
+  <VibeContainer fluid="md">
+    <p>Fluid until medium breakpoint</p>
+  </VibeContainer>
+</template>
+```

package/docs/components/layout/row.md

@@ -0,0 +1,113 @@
+# VibeRow
+
+Row component for Bootstrap's grid system. Provides gutters, row columns, and alignment props.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tag` | `Tag` | `'div'` | HTML element to render |
+| `gutters` | `GutterSize` | `undefined` | Base gutter size (both axes) |
+| `guttersX` | `GutterSize` | `undefined` | Horizontal gutter size |
+| `guttersY` | `GutterSize` | `undefined` | Vertical gutter size |
+| `guttersSm` | `GutterSize` | `undefined` | Gutter size at `sm` breakpoint |
+| `guttersMd` | `GutterSize` | `undefined` | Gutter size at `md` breakpoint |
+| `guttersLg` | `GutterSize` | `undefined` | Gutter size at `lg` breakpoint |
+| `guttersXl` | `GutterSize` | `undefined` | Gutter size at `xl` breakpoint |
+| `guttersXxl` | `GutterSize` | `undefined` | Gutter size at `xxl` breakpoint |
+| `guttersXSm` | `GutterSize` | `undefined` | Horizontal gutter at `sm` breakpoint |
+| `guttersXMd` | `GutterSize` | `undefined` | Horizontal gutter at `md` breakpoint |
+| `guttersXLg` | `GutterSize` | `undefined` | Horizontal gutter at `lg` breakpoint |
+| `guttersXXl` | `GutterSize` | `undefined` | Horizontal gutter at `xl` breakpoint |
+| `guttersXXxl` | `GutterSize` | `undefined` | Horizontal gutter at `xxl` breakpoint |
+| `guttersYSm` | `GutterSize` | `undefined` | Vertical gutter at `sm` breakpoint |
+| `guttersYMd` | `GutterSize` | `undefined` | Vertical gutter at `md` breakpoint |
+| `guttersYLg` | `GutterSize` | `undefined` | Vertical gutter at `lg` breakpoint |
+| `guttersYXl` | `GutterSize` | `undefined` | Vertical gutter at `xl` breakpoint |
+| `guttersYXxl` | `GutterSize` | `undefined` | Vertical gutter at `xxl` breakpoint |
+| `rowCols` | `RowColsSize` | `undefined` | Number of columns per row |
+| `rowColsSm` | `RowColsSize` | `undefined` | Columns per row at `sm` breakpoint |
+| `rowColsMd` | `RowColsSize` | `undefined` | Columns per row at `md` breakpoint |
+| `rowColsLg` | `RowColsSize` | `undefined` | Columns per row at `lg` breakpoint |
+| `rowColsXl` | `RowColsSize` | `undefined` | Columns per row at `xl` breakpoint |
+| `rowColsXxl` | `RowColsSize` | `undefined` | Columns per row at `xxl` breakpoint |
+| `alignItems` | `AlignItems` | `undefined` | Vertical alignment of columns |
+| `justifyContent` | `JustifyContent` | `undefined` | Horizontal distribution of columns |
+
+### Type Reference
+
+- **GutterSize:** `0 | 1 | 2 | 3 | 4 | 5`
+- **RowColsSize:** `1 | 2 | 3 | 4 | 5 | 6`
+- **AlignItems:** `'start' | 'center' | 'end' | 'baseline' | 'stretch'`
+- **JustifyContent:** `'start' | 'center' | 'end' | 'around' | 'between' | 'evenly'`
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `component-error` | `Object` | Emitted when an error occurs |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Row content (typically `VibeCol` components) |
+
+## Usage
+
+### Basic Grid
+
+```vue
+<template>
+  <VibeContainer>
+    <VibeRow>
+      <VibeCol>Column 1</VibeCol>
+      <VibeCol>Column 2</VibeCol>
+      <VibeCol>Column 3</VibeCol>
+    </VibeRow>
+  </VibeContainer>
+</template>
+```
+
+### With Gutters
+
+```vue
+<template>
+  <VibeContainer>
+    <VibeRow :gutters="3" :guttersY="4">
+      <VibeCol :cols="6">Col 1</VibeCol>
+      <VibeCol :cols="6">Col 2</VibeCol>
+      <VibeCol :cols="6">Col 3</VibeCol>
+      <VibeCol :cols="6">Col 4</VibeCol>
+    </VibeRow>
+  </VibeContainer>
+</template>
+```
+
+### Row Columns
+
+```vue
+<template>
+  <VibeContainer>
+    <!-- Automatically size each child to 1/3 width -->
+    <VibeRow :row-cols="3">
+      <VibeCol>Item 1</VibeCol>
+      <VibeCol>Item 2</VibeCol>
+      <VibeCol>Item 3</VibeCol>
+    </VibeRow>
+  </VibeContainer>
+</template>
+```
+
+### Alignment
+
+```vue
+<template>
+  <VibeContainer>
+    <VibeRow align-items="center" justify-content="between">
+      <VibeCol :cols="4">Left</VibeCol>
+      <VibeCol :cols="4">Right</VibeCol>
+    </VibeRow>
+  </VibeContainer>
+</template>
+```

package/docs/components/list/list-group.md

@@ -0,0 +1,221 @@
+# VibeListGroup
+
+Data-driven component for displaying flexible lists of content.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `flush` | `Boolean` | `false` | Remove borders and rounded corners |
+| `horizontal` | `Boolean\|String` | `false` | Horizontal layout: `true` or breakpoint (`'sm'`, `'md'`, `'lg'`, `'xl'`) |
+| `numbered` | `Boolean` | `false` | Numbered list items |
+| `tag` | `String` | `'ul'` | HTML tag: `'ul'`, `'ol'`, or `'div'` |
+| `items` | `ListGroupItem[]` | Required | Array of list group items |
+
+### ListGroupItem Interface
+
+```typescript
+interface ListGroupItem {
+  text: string
+  href?: string
+  to?: string | object
+  active?: boolean
+  disabled?: boolean
+  variant?: Variant
+}
+```
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `item-click` | `{ item, index, event }` | Emitted when an item is clicked (unless disabled) |
+
+## Slots
+
+| Slot | Scope | Description |
+|------|-------|-------------|
+| `item` | `{ item, index }` | Custom item rendering |
+
+## Usage
+
+### Basic List
+
+```vue
+<template>
+  <VibeListGroup :items="listItems" />
+</template>
+
+<script setup>
+const listItems = [
+  { text: 'An item' },
+  { text: 'A second item' },
+  { text: 'A third item' }
+]
+</script>
+```
+
+### Active and Disabled Items
+
+```vue
+<template>
+  <VibeListGroup :items="listItems" />
+</template>
+
+<script setup>
+const listItems = [
+  { text: 'An item' },
+  { text: 'A second item', active: true },
+  { text: 'A third item' },
+  { text: 'A disabled item', disabled: true }
+]
+</script>
+```
+
+### With Links
+
+```vue
+<template>
+  <VibeListGroup :items="listItems" />
+</template>
+
+<script setup>
+const listItems = [
+  { text: 'Link 1', href: '#', active: true },
+  { text: 'Link 2', href: '#' },
+  { text: 'Link 3', href: '#' }
+]
+</script>
+```
+
+### With Router Links
+
+```vue
+<template>
+  <VibeListGroup :items="listItems" />
+</template>
+
+<script setup>
+const listItems = [
+  { text: 'Home', to: { name: 'home' } },
+  { text: 'About', to: { name: 'about' } },
+  { text: 'Contact', to: { name: 'contact' } }
+]
+</script>
+```
+
+### Colored Items
+
+```vue
+<template>
+  <VibeListGroup :items="listItems" />
+</template>
+
+<script setup>
+const listItems = [
+  { text: 'Primary item', variant: 'primary' },
+  { text: 'Success item', variant: 'success' },
+  { text: 'Danger item', variant: 'danger' },
+  { text: 'Warning item', variant: 'warning' },
+  { text: 'Info item', variant: 'info' }
+]
+</script>
+```
+
+### Flush List
+
+Remove borders and rounded corners:
+
+```vue
+<template>
+  <VibeListGroup flush :items="listItems" />
+</template>
+```
+
+### Horizontal List
+
+```vue
+<template>
+  <!-- Always horizontal -->
+  <VibeListGroup horizontal :items="listItems" />
+
+  <!-- Horizontal on md and up -->
+  <VibeListGroup horizontal="md" :items="listItems" />
+</template>
+```
+
+### Numbered List
+
+```vue
+<template>
+  <VibeListGroup numbered tag="ol" :items="listItems" />
+</template>
+
+<script setup>
+const listItems = [
+  { text: 'First item' },
+  { text: 'Second item' },
+  { text: 'Third item' }
+]
+</script>
+```
+
+### Custom Item Rendering
+
+Use the `item` scoped slot for complex content:
+
+```vue
+<template>
+  <VibeListGroup :items="listItems">
+    <template #item="{ item }">
+      <div class="d-flex justify-content-between align-items-center">
+        <div>
+          <h5 class="mb-1">{{ item.text }}</h5>
+          <p class="mb-1">{{ item.description }}</p>
+        </div>
+        <VibeBadge variant="primary">{{ item.count }}</VibeBadge>
+      </div>
+    </template>
+  </VibeListGroup>
+</template>
+
+<script setup>
+const listItems = [
+  { text: 'Inbox', description: 'Unread messages', count: 14 },
+  { text: 'Starred', description: 'Important items', count: 3 },
+  { text: 'Sent', description: 'Outgoing mail', count: 25 }
+]
+</script>
+```
+
+### With Event Handling
+
+```vue
+<template>
+  <VibeListGroup :items="listItems" @item-click="handleClick" />
+</template>
+
+<script setup>
+const listItems = [
+  { text: 'Item 1' },
+  { text: 'Item 2' },
+  { text: 'Item 3' }
+]
+
+const handleClick = ({ item, index }) => {
+  console.log(`Clicked: ${item.text} at index ${index}`)
+}
+</script>
+```
+
+## Bootstrap CSS Classes
+
+- `.list-group`
+- `.list-group-flush`
+- `.list-group-horizontal`, `.list-group-horizontal-{breakpoint}`
+- `.list-group-numbered`
+- `.list-group-item`
+- `.list-group-item-{variant}`
+- `.list-group-item-action`
+- `.active`
+- `.disabled`

package/docs/components/navigation/breadcrumb.md

@@ -0,0 +1,116 @@
+# 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>
+```
+
+## Bootstrap CSS Classes
+
+- `.breadcrumb`
+- `.breadcrumb-item`
+- `.active`

package/docs/components/navigation/nav.md

@@ -0,0 +1,88 @@
+# 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
+  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
+
+### 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>
+```
+
+## Important Notes
+
+**Automatic Initialization:** When using `tabs` or `pills`, this component automatically initializes Bootstrap's Tab functionality for any items that target a local ID (e.g., `href="#my-tab"`).
+
+**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,106 @@
+# 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 |
+
+### 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
+
+**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`