@velkymx/vibeui 0.8.0 → 0.8.2

package/docs/components/core/spinner.md

@@ -0,0 +1,109 @@
+# VibeSpinner
+
+Loading spinner with border or grow animation styles.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `Variant` | `undefined` | Text color variant |
+| `type` | `SpinnerType` | `'border'` | Spinner type: `'border'` or `'grow'` |
+| `size` | `Size` | `undefined` | Spinner size: `'sm'` or `'lg'` |
+| `label` | `String` | `'Loading...'` | Screen reader text |
+| `tag` | `String` | `'div'` | HTML tag to render |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `component-error` | `Object` | Emitted when an error occurs |
+
+## Usage
+
+### Basic Spinner
+
+```vue
+<template>
+  <VibeSpinner />
+</template>
+```
+
+### Grow Spinner
+
+```vue
+<template>
+  <VibeSpinner type="grow" />
+</template>
+```
+
+### Colored Spinners
+
+```vue
+<template>
+  <div>
+    <VibeSpinner variant="primary" />
+    <VibeSpinner variant="success" />
+    <VibeSpinner variant="danger" />
+    <VibeSpinner variant="warning" />
+    <VibeSpinner variant="info" />
+  </div>
+</template>
+```
+
+### Small Spinners
+
+```vue
+<template>
+  <div>
+    <VibeSpinner size="sm" />
+    <VibeSpinner type="grow" size="sm" />
+  </div>
+</template>
+```
+
+### In Button
+
+```vue
+<template>
+  <VibeButton variant="primary" disabled>
+    <VibeSpinner size="sm" tag="span" />
+    Loading...
+  </VibeButton>
+</template>
+```
+
+### Custom Label
+
+```vue
+<template>
+  <VibeSpinner label="Please wait while we load your data..." />
+</template>
+```
+
+### Loading State Example
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const loading = ref(true)
+
+setTimeout(() => {
+  loading.value = false
+}, 3000)
+</script>
+
+<template>
+  <div>
+    <VibeSpinner v-if="loading" variant="primary" />
+    <div v-else>Content loaded!</div>
+  </div>
+</template>
+```
+
+## Bootstrap CSS Classes
+
+- `.spinner-border` or `.spinner-grow`
+- `.text-{variant}`
+- `.spinner-{type}-{size}`
+- `.visually-hidden` (for label)

package/docs/components/data/datatable.md

@@ -0,0 +1,416 @@
+# VibeDataTable
+
+Powerful data table component with search, sorting, and pagination - similar to DataTables.net but built for Vue 3 and Bootstrap 5.3.
+
+## Features
+
+- **Search/Filter** - Real-time search across all searchable columns
+- **Column Sorting** - Click column headers to sort (asc/desc)
+- **Pagination** - Built-in pagination with customizable page sizes
+- **Responsive** - Mobile-friendly with responsive table wrapper
+- **Bootstrap Styling** - All Bootstrap table variants (striped, bordered, hover, etc.)
+- **Custom Cell Rendering** - Slots for custom cell content
+- **Formatters** - Custom data formatters per column
+- **TypeScript** - Fully typed with comprehensive interfaces
+
+## Props
+
+### Data Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `Array<any>` | `[]` | Array of data objects to display |
+| `columns` | `DataTableColumn[]` | Required | Column definitions |
+
+### Table Styling Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `striped` | `Boolean` | `false` | Striped table rows |
+| `bordered` | `Boolean` | `false` | Bordered table |
+| `borderless` | `Boolean` | `false` | Remove all borders |
+| `hover` | `Boolean` | `false` | Hover effect on rows |
+| `small` | `Boolean` | `false` | Compact table |
+| `responsive` | `Boolean` | `true` | Responsive table wrapper |
+| `stack` | `Boolean` | `false` | Transforms table into cards on mobile screens |
+| `variant` | `String` | `undefined` | Table color variant |
+
+### Feature Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `searchable` | `Boolean` | `true` | Enable search functionality |
+| `sortable` | `Boolean` | `true` | Enable column sorting |
+| `paginated` | `Boolean` | `true` | Enable pagination |
+
+### Search Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `searchPlaceholder` | `String` | `'Search...'` | Search input placeholder |
+| `searchDebounce` | `Number` | `300` | Search debounce delay (ms) |
+
+### Pagination Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `perPage` | `Number` | `10` | Items per page |
+| `currentPage` | `Number` | `1` | Current page number |
+| `perPageOptions` | `Number[]` | `[5, 10, 25, 50, 100]` | Page size options |
+
+### Sorting Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `sortBy` | `String` | `undefined` | Initial sort column key |
+| `sortDesc` | `Boolean` | `false` | Initial sort direction (true = descending) |
+
+### Display Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `showEmpty` | `Boolean` | `true` | Show message when no data |
+| `emptyText` | `String` | `'No data available'` | Empty state message |
+| `showPerPage` | `Boolean` | `true` | Show per-page selector |
+| `showInfo` | `Boolean` | `true` | Show info text (X to Y of Z entries) |
+| `infoText` | `String` | `'Showing {start} to {end} of {total} entries'` | Info text template |
+| `filteredInfoText` | `String` | `'Showing {start} to {end} of {total} entries (filtered from {totalRows} total entries)'` | Filtered info text template |
+
+## Column Definition
+
+The `columns` prop accepts an array of `DataTableColumn` objects:
+
+```typescript
+interface DataTableColumn {
+  key: string                    // Property key in data object
+  label: string                  // Column header label
+  sortable?: boolean            // Enable/disable sorting (default: true)
+  searchable?: boolean          // Include in search (default: true)
+  formatter?: (value: any, row: any) => string | number  // Custom formatter
+  class?: string                // CSS class for td
+  headerClass?: string          // CSS class for th
+  thStyle?: Record<string, string>  // Inline styles for th
+  tdStyle?: Record<string, string>  // Inline styles for td
+}
+```
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:currentPage` | `Number` | Emitted when page changes |
+| `update:perPage` | `Number` | Emitted when per-page changes |
+| `update:sortBy` | `String` | Emitted when sort column changes |
+| `update:sortDesc` | `Boolean` | Emitted when sort direction changes |
+| `row-clicked` | `(item, index)` | Emitted when row is clicked |
+
+## Slots
+
+| Slot | Props | Description |
+|------|-------|-------------|
+| `cell({columnKey})` | `{ item, value, index }` | Custom cell rendering for specific column |
+
+## Usage
+
+### Basic DataTable
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const columns = [
+  { key: 'id', label: 'ID' },
+  { key: 'name', label: 'Name' },
+  { key: 'email', label: 'Email' },
+  { key: 'status', label: 'Status' }
+]
+
+const items = [
+  { id: 1, name: 'John Doe', email: 'john@example.com', status: 'Active' },
+  { id: 2, name: 'Jane Smith', email: 'jane@example.com', status: 'Inactive' },
+  { id: 3, name: 'Bob Johnson', email: 'bob@example.com', status: 'Active' }
+]
+</script>
+
+<template>
+  <VibeDataTable :columns="columns" :items="items" />
+</template>
+```
+
+### With Bootstrap Styling
+
+```vue
+<template>
+  <VibeDataTable
+    :columns="columns"
+    :items="items"
+    striped
+    hover
+    bordered
+  />
+</template>
+```
+
+### Custom Column Configuration
+
+```vue
+<script setup>
+const columns = [
+  {
+    key: 'id',
+    label: 'ID',
+    sortable: true,
+    searchable: false,
+    headerClass: 'bg-primary text-white'
+  },
+  {
+    key: 'name',
+    label: 'Full Name',
+    sortable: true
+  },
+  {
+    key: 'salary',
+    label: 'Salary',
+    formatter: (value) => `$${value.toLocaleString()}`,
+    tdStyle: { textAlign: 'right' }
+  },
+  {
+    key: 'status',
+    label: 'Status',
+    class: 'text-center'
+  }
+]
+</script>
+
+<template>
+  <VibeDataTable :columns="columns" :items="items" />
+</template>
+```
+
+### With Custom Cell Rendering
+
+```vue
+<script setup>
+const columns = [
+  { key: 'name', label: 'Name' },
+  { key: 'email', label: 'Email' },
+  { key: 'status', label: 'Status' },
+  { key: 'actions', label: 'Actions', sortable: false }
+]
+</script>
+
+<template>
+  <VibeDataTable :columns="columns" :items="items">
+    <!-- Custom status column -->
+    <template #cell(status)="{ value }">
+      <VibeBadge :variant="value === 'Active' ? 'success' : 'danger'">
+        {{ value }}
+      </VibeBadge>
+    </template>
+
+    <!-- Custom actions column -->
+    <template #cell(actions)="{ item }">
+      <VibeButton size="sm" variant="primary" @click="editItem(item)">
+        Edit
+      </VibeButton>
+      <VibeButton size="sm" variant="danger" @click="deleteItem(item)">
+        Delete
+      </VibeButton>
+    </template>
+  </VibeDataTable>
+</template>
+```
+
+### Controlled State (v-model)
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const currentPage = ref(1)
+const perPage = ref(25)
+const sortBy = ref('name')
+const sortDesc = ref(false)
+
+const handleRowClick = (item, index) => {
+  console.log('Clicked row:', item, index)
+}
+</script>
+
+<template>
+  <VibeDataTable
+    :columns="columns"
+    :items="items"
+    v-model:current-page="currentPage"
+    v-model:per-page="perPage"
+    v-model:sort-by="sortBy"
+    v-model:sort-desc="sortDesc"
+    @row-clicked="handleRowClick"
+  />
+</template>
+```
+
+### Disable Features
+
+```vue
+<template>
+  <!-- No search, no pagination -->
+  <VibeDataTable
+    :columns="columns"
+    :items="items"
+    :searchable="false"
+    :paginated="false"
+  />
+
+  <!-- No sorting -->
+  <VibeDataTable
+    :columns="columns"
+    :items="items"
+    :sortable="false"
+  />
+</template>
+```
+
+### Custom Page Sizes
+
+```vue
+<template>
+  <VibeDataTable
+    :columns="columns"
+    :items="items"
+    :per-page="20"
+    :per-page-options="[10, 20, 50, 100, 500]"
+  />
+</template>
+```
+
+### Large Dataset Example
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+// Generate large dataset
+const items = ref(
+  Array.from({ length: 1000 }, (_, i) => ({
+    id: i + 1,
+    name: `User ${i + 1}`,
+    email: `user${i + 1}@example.com`,
+    department: ['Sales', 'Marketing', 'Engineering', 'HR'][i % 4],
+    salary: Math.floor(Math.random() * 100000) + 50000,
+    joinDate: new Date(2020 + Math.floor(Math.random() * 5), Math.floor(Math.random() * 12), 1)
+      .toISOString()
+      .split('T')[0]
+  }))
+)
+
+const columns = [
+  { key: 'id', label: 'ID', sortable: true },
+  { key: 'name', label: 'Name', sortable: true },
+  { key: 'email', label: 'Email', sortable: true },
+  { key: 'department', label: 'Department', sortable: true },
+  {
+    key: 'salary',
+    label: 'Salary',
+    sortable: true,
+    formatter: (value) => `$${value.toLocaleString()}`
+  },
+  { key: 'joinDate', label: 'Join Date', sortable: true }
+]
+</script>
+
+<template>
+  <VibeDataTable
+    :columns="columns"
+    :items="items"
+    :per-page="25"
+    striped
+    hover
+    small
+  />
+</template>
+```
+
+### With Custom Empty State
+
+```vue
+<template>
+  <VibeDataTable
+    :columns="columns"
+    :items="[]"
+    empty-text="No users found. Try adjusting your search."
+  />
+</template>
+```
+
+## Advanced Features
+
+### Formatters
+
+Use formatters to transform data before display:
+
+```vue
+<script setup>
+const columns = [
+  {
+    key: 'price',
+    label: 'Price',
+    formatter: (value) => `$${value.toFixed(2)}`
+  },
+  {
+    key: 'date',
+    label: 'Date',
+    formatter: (value) => new Date(value).toLocaleDateString()
+  },
+  {
+    key: 'percentage',
+    label: 'Complete',
+    formatter: (value) => `${value}%`
+  }
+]
+</script>
+```
+
+### Accessing Full Row in Formatter
+
+```vue
+<script setup>
+const columns = [
+  {
+    key: 'fullName',
+    label: 'Full Name',
+    formatter: (value, row) => `${row.firstName} ${row.lastName}`
+  },
+  {
+    key: 'discount',
+    label: 'Discount',
+    formatter: (value, row) => {
+      return row.isPremium ? `${value}% (Premium)` : `${value}%`
+    }
+  }
+]
+</script>
+```
+
+## Bootstrap CSS Classes
+
+- `.table` - Base table
+- `.table-striped` - Striped rows
+- `.table-bordered` - Bordered table
+- `.table-borderless` - Borderless table
+- `.table-hover` - Hover effect
+- `.table-sm` - Compact table
+- `.table-{variant}` - Color variants
+- `.table-responsive` - Responsive wrapper
+- `.vibe-table-stack` - Mobile card view transformation
+- `.pagination` - Pagination controls
+- `.form-control` - Search input
+- `.form-select` - Per-page selector
+
+## Tips
+
+1. **Large Datasets**: For datasets with 1000+ rows, consider server-side pagination
+2. **Performance**: Use `:key` on items for better Vue reactivity
+3. **Search Debounce**: Adjust `searchDebounce` prop for performance with large datasets
+4. **Custom Styling**: Use column `class`, `headerClass`, `thStyle`, `tdStyle` for styling
+5. **Slots**: Use slots for complex cell rendering (badges, buttons, images, etc.)

package/docs/components/interactive/accordion.md

@@ -0,0 +1,92 @@
+# 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 |
+
+## 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>
+```
+
+## 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.
+
+## 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,97 @@
+# 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` | - | Emitted when slide transition starts |
+| `slid` | - | Emitted when slide transition completes |
+
+## 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 = [...]
+</script>
+```
+
+### Basic Carousel
+
+```vue
+<template>
+  <VibeCarousel :items="carouselItems" />
+</template>
+```
+
+## 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.
+
+**Instance Exposure:** You can access the underlying Bootstrap instance via template ref using the `bsInstance` property.
+
+## Bootstrap CSS Classes
+
+- `.carousel`
+- `.carousel-inner`
+- `.carousel-item`
+- `.carousel-control-prev`
+- `.carousel-control-next`
+- `.carousel-indicators`
+- `.carousel-caption`
+- `.carousel-dark`
+- `.carousel-fade`