@velkymx/vibeui 0.9.0 → 1.1.0

package/docs/components/core/spinner.md

@@ -0,0 +1,103 @@
+# 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 |
+
+## 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,437 @@
+# 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` | `T[]` | `[]` | Array of data objects to display |
+| `columns` | `DataTableColumn<T>[]` | `[]` | Column definitions. Defaults to an empty array, so an unset/loading state renders an empty table rather than erroring. |
+| `rowKey` | `String` | `'id'` | Property name used as the unique key for each row. **Recommended** — set it to a unique field in your data (e.g. `'id'`, `'uuid'`) so Vue tracks rows correctly across sorting, filtering, and pagination. Falls back to a positional key (with a DEV warning) when missing. |
+
+> **Typing tip**: `DataTableColumn` is generic over your row type. For full slot-prop / formatter typing, annotate the column array:
+>
+> ```ts
+> import type { DataTableColumn } from '@velkymx/vibeui'
+> interface User { id: number; name: string; active: boolean }
+> const columns: DataTableColumn<User>[] = [
+>   { key: 'name', label: 'Name' },              // key narrowed to keyof User
+>   { key: 'active', label: 'Active', formatter: v => v ? 'Yes' : 'No' }
+> ]
+> ```
+>
+> Without the annotation, `T` defaults to `Record<string, unknown>` and slot props arrive as `unknown`.
+
+### 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 |
+| `clickable` | `Boolean` | `false` | Show a pointer cursor on rows to signal they are interactive (pair with a `@row-clicked` listener) |
+
+### 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 (sanitized — see note)
+  tdStyle?: Record<string, string>  // Inline styles for td (sanitized — see note)
+}
+```
+
+> **`thStyle` / `tdStyle` are sanitized.** Both objects are filtered against a safe CSS-property allowlist before being applied, as a defense against CSS injection (data exfiltration / UI spoofing) when column config comes from an API or untrusted source. Properties outside the allowlist are dropped.
+
+## 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, globalIndex)` | Emitted when a row is clicked. `globalIndex` is the index within the full filtered/sorted dataset, not the current page. Only emitted when a `@row-clicked` listener is attached (rows show a pointer cursor in that case). |
+| `component-error` | `ComponentError` | Emitted if an internal error occurs |
+
+## 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" row-key="id" />
+</template>
+```
+
+> Always pass `row-key` pointing at a unique field (here `id`) so Vue keys rows stably across sorting, filtering, and pagination.
+
+### 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, globalIndex) => {
+  console.log('Clicked row:', item, globalIndex)
+}
+</script>
+
+<template>
+  <VibeDataTable
+    :columns="columns"
+    :items="items"
+    row-key="id"
+    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. **Stable keys**: Set the `row-key` prop to a unique field in your data for correct behavior during sorting/filtering and best reactivity
+3. **Search Debounce**: Adjust `searchDebounce` prop for performance with large datasets
+4. **Custom Styling**: Use column `class`, `headerClass`, `thStyle`, `tdStyle` for styling (style objects are sanitized to a safe property allowlist)
+5. **Slots**: Use slots for complex cell rendering (badges, buttons, images, etc.)

package/docs/components/hero/hero.md

@@ -0,0 +1,65 @@
+# VibeHero
+
+A hero / banner section. Renders a `<section>` with consistent padding, an inner container, and content alignment — covering the Bootstrap 5.3 hero patterns (centered, two-column, dark, bordered) plus full-bleed background image / gradient heroes.
+
+```vue
+<VibeHero variant="dark" text-variant="light">
+  <h1 class="display-4 fw-bold">Build faster with VibeUI</h1>
+  <p class="lead">A modern Vue 3 component library for Bootstrap 5.3.</p>
+  <VibeButton variant="primary" size="lg">Get started</VibeButton>
+</VibeHero>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `Variant` | `undefined` | Background color → `bg-{variant}` (same vocabulary as `VibeCard`) |
+| `textVariant` | `Variant` | `undefined` | Text color → `text-{variant}` |
+| `border` | `Variant` | `undefined` | Adds `border border-{variant} rounded-3` (the bordered-hero pattern) |
+| `align` | `'start' \| 'center' \| 'end'` | `'center'` | Content alignment → `text-{align}` |
+| `fluid` | `Boolean \| ContainerType` | `false` | Inner container width (same vocabulary as `VibeContainer`) |
+| `minHeight` | `String` | `undefined` | Sanitized via `safeLength`; when set, content is vertically centered |
+| `bgImage` | `String` | `undefined` | Full-bleed background image URL; sanitized via `safeHref` (blocks `javascript:`/`data:`), rendered `cover`/`center` |
+| `overlay` | `Boolean \| String` | `false` | Darkening layer over `bgImage` for legibility — `true` for a default dark scrim, or a CSS color (sanitized via `safeColor`) |
+| `overlayOpacity` | `Number` | `0.5` | Opacity of the default dark scrim when `overlay` is `true`; clamped to `[0, 1]`. Ignored when `overlay` is a CSS color string |
+| `gradient` | `String` | `undefined` | CSS gradient background (e.g. `linear-gradient(135deg, #667eea, #764ba2)`); validated to `*-gradient(...)` only — no `url()`/`expression()` |
+| `tag` | `Tag` | `'section'` | Root element tag |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Hero content. You supply the inner layout (a centered column, or a `VibeRow`/`VibeCol` split). |
+
+## Examples
+
+**Centered (Bootstrap "centered hero")**
+
+```vue
+<VibeHero>
+  <VibeCol :lg="7" class="mx-auto">
+    <h1 class="display-3 fw-bold">Photo Gallery</h1>
+    <p class="lead">Curated photography from around the world.</p>
+  </VibeCol>
+</VibeHero>
+```
+
+**Two-column with gradient**
+
+```vue
+<VibeHero gradient="linear-gradient(135deg, #667eea 0%, #764ba2 100%)" align="start" class="text-white">
+  <VibeRow class="align-items-center">
+    <VibeCol :lg="6"><h1 class="display-3 fw-bold">Headline</h1></VibeCol>
+    <VibeCol :lg="6"><img src="/demo.png" class="img-fluid rounded-4 shadow-lg"></VibeCol>
+  </VibeRow>
+</VibeHero>
+```
+
+**Full-bleed image with overlay**
+
+```vue
+<VibeHero bg-image="/banner.jpg" overlay min-height="400px" class="text-white">
+  <h1 class="display-3 fw-bold">Welcome</h1>
+</VibeHero>
+```