@velkymx/vibeui 0.8.2 → 1.0.2

package/docs/components/charts/chart-bar.md

@@ -0,0 +1,129 @@
+# VibeChartBar
+
+Canvas-based bar chart with responsive sizing, interactive tooltips, stacked mode, and Bootstrap-aware color cycling.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `data` | `ChartData` | Required | Chart data: labels array + datasets array |
+| `legend` | `'top' \| 'bottom' \| 'none'` | `'bottom'` | Legend position |
+| `height` | `Number \| String` | `'auto'` | Fixed height in px or CSS string. `'auto'` uses 16:9 aspect ratio |
+| `showAxes` | `Boolean` | `true` | Render X and Y axes |
+| `showGrid` | `Boolean` | `true` | Render horizontal grid lines |
+| `stacked` | `Boolean` | `false` | Stack datasets on top of each other instead of grouping side-by-side |
+
+## Data Shape
+
+```ts
+interface ChartData {
+  labels: string[]       // X-axis category labels
+  datasets: ChartDataset[]
+}
+
+interface ChartDataset {
+  label: string          // Series name (shown in legend and tooltip)
+  data: number[]         // One value per label
+  color?: string         // CSS color string. Defaults to Bootstrap CSS variables cycling through
+                         // --bs-primary, --bs-success, --bs-danger, --bs-warning, --bs-info, ...
+}
+```
+
+Import from `@velkymx/vibeui`:
+
+```ts
+import type { ChartData } from '@velkymx/vibeui'
+```
+
+## Usage
+
+### Basic Bar Chart
+
+```vue
+<script setup>
+const data = {
+  labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
+  datasets: [
+    { label: 'Orders', data: [34, 52, 48, 61, 44] }
+  ]
+}
+</script>
+
+<template>
+  <VibeChartBar :data="data" />
+</template>
+```
+
+### Grouped Bars (Multiple Datasets)
+
+```vue
+<template>
+  <VibeChartBar :data="{
+    labels: ['Q1', 'Q2', 'Q3', 'Q4'],
+    datasets: [
+      { label: 'Product A', data: [120, 145, 132, 170] },
+      { label: 'Product B', data: [ 80,  95,  88, 105] }
+    ]
+  }" />
+</template>
+```
+
+### Stacked Bar Chart
+
+```vue
+<template>
+  <VibeChartBar :data="data" stacked />
+</template>
+```
+
+### Fixed Height, Legend at Top
+
+```vue
+<template>
+  <VibeChartBar :data="data" :height="250" legend="top" />
+</template>
+```
+
+### Custom Colors
+
+```vue
+<template>
+  <VibeChartBar :data="{
+    labels: ['A', 'B', 'C'],
+    datasets: [
+      { label: 'Wins',   data: [8, 5, 7], color: '#2ecc71' },
+      { label: 'Losses', data: [2, 5, 3], color: '#e74c3c' }
+    ]
+  }" />
+</template>
+```
+
+### Reactive Data
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const data = ref({
+  labels: ['Jan', 'Feb'],
+  datasets: [{ label: 'Sales', data: [100, 150] }]
+})
+
+function addWeek() {
+  data.value.labels.push('Mar')
+  data.value.datasets[0].data.push(130)
+}
+</script>
+
+<template>
+  <VibeChartBar :data="data" />
+  <button @click="addWeek">Add Month</button>
+</template>
+```
+
+## Notes
+
+- **No external dependency.** VibeChartBar draws directly on a `<canvas>` element — no Chart.js or other charting library required.
+- **Color cycling.** When `color` is omitted on a dataset, colors cycle through Bootstrap's CSS variables (`--bs-primary`, `--bs-success`, `--bs-danger`, ...) resolved from the container's computed styles. Colors follow your Bootstrap theme and dark mode automatically.
+- **Responsive.** The canvas resizes via `ResizeObserver` and redraws at device pixel ratio for crisp HiDPI output.
+- **Tooltips.** Hover over any bar to see the category, series name, and value.

package/docs/components/charts/chart-line.md

@@ -0,0 +1,136 @@
+# VibeChartLine
+
+Canvas-based line chart with responsive sizing, interactive tooltips, and Bootstrap-aware color cycling.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `data` | `ChartData` | Required | Chart data: labels array + datasets array |
+| `legend` | `'top' \| 'bottom' \| 'none'` | `'bottom'` | Legend position |
+| `height` | `Number \| String` | `'auto'` | Fixed height in px or CSS string. `'auto'` uses 16:9 aspect ratio |
+| `showAxes` | `Boolean` | `true` | Render X and Y axes |
+| `showGrid` | `Boolean` | `true` | Render horizontal grid lines |
+| `smooth` | `Boolean` | `false` | Render lines as bezier curves instead of straight segments |
+| `fill` | `Boolean` | `false` | Fill the area under each line |
+
+## Data Shape
+
+```ts
+interface ChartData {
+  labels: string[]       // X-axis labels
+  datasets: ChartDataset[]
+}
+
+interface ChartDataset {
+  label: string          // Series name (shown in legend and tooltip)
+  data: number[]         // One value per label
+  color?: string         // CSS color string. Defaults to Bootstrap CSS variables cycling through
+                         // --bs-primary, --bs-success, --bs-danger, --bs-warning, --bs-info, ...
+}
+```
+
+Import from `@velkymx/vibeui`:
+
+```ts
+import type { ChartData } from '@velkymx/vibeui'
+```
+
+## Usage
+
+### Basic Line Chart
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const data = ref({
+  labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'],
+  datasets: [
+    { label: 'Revenue', data: [12000, 18000, 15000, 22000, 19000, 27000] }
+  ]
+})
+</script>
+
+<template>
+  <VibeChartLine :data="data" />
+</template>
+```
+
+### Multiple Series
+
+```vue
+<template>
+  <VibeChartLine :data="{
+    labels: ['Q1', 'Q2', 'Q3', 'Q4'],
+    datasets: [
+      { label: 'Sales', data: [45, 62, 58, 75] },
+      { label: 'Costs', data: [30, 35, 32, 40] }
+    ]
+  }" />
+</template>
+```
+
+### Smooth Filled Curves
+
+```vue
+<template>
+  <VibeChartLine :data="data" smooth fill />
+</template>
+```
+
+### Fixed Height, Legend at Top
+
+```vue
+<template>
+  <VibeChartLine :data="data" :height="300" legend="top" />
+</template>
+```
+
+### Custom Colors
+
+Override per-dataset colors with any CSS color string:
+
+```vue
+<template>
+  <VibeChartLine :data="{
+    labels: ['A', 'B', 'C'],
+    datasets: [
+      { label: 'Alpha', data: [1, 3, 2], color: '#e74c3c' },
+      { label: 'Beta',  data: [2, 1, 4], color: '#3498db' }
+    ]
+  }" />
+</template>
+```
+
+### Reactive Data
+
+The chart redraws whenever `data` changes:
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const data = ref({
+  labels: ['Jan', 'Feb', 'Mar'],
+  datasets: [{ label: 'Visits', data: [100, 200, 150] }]
+})
+
+function addMonth() {
+  data.value.labels.push('Apr')
+  data.value.datasets[0].data.push(180)
+}
+</script>
+
+<template>
+  <VibeChartLine :data="data" />
+  <button @click="addMonth">Add Month</button>
+</template>
+```
+
+## Notes
+
+- **No external dependency.** VibeChartLine draws directly on a `<canvas>` element — no Chart.js or other charting library required.
+- **Color cycling.** When `color` is omitted on a dataset, colors cycle through Bootstrap's CSS variables (`--bs-primary`, `--bs-success`, `--bs-danger`, ...) resolved from the computed styles of the container. Colors automatically follow your Bootstrap theme, including dark mode.
+- **Responsive.** The canvas resizes via `ResizeObserver` on the container element and redraws at the device pixel ratio for crisp output on HiDPI screens.
+- **Tooltips.** Hover over a data point to see the label and value. The chart redraws on each tooltip state change.

package/docs/components/charts/chart-pie.md

@@ -0,0 +1,102 @@
+# VibeChartPie
+
+Canvas-based pie chart with interactive tooltips, Bootstrap-aware color cycling, and responsive sizing.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `data` | `ChartData` | Required | Chart data: labels array + single dataset |
+| `legend` | `'top' \| 'bottom' \| 'none'` | `'bottom'` | Legend position |
+| `height` | `Number \| String` | `'auto'` | Fixed height in px or CSS string. `'auto'` uses 1:1 aspect ratio |
+
+## Data Shape
+
+Pie charts use a single dataset. Each value in `data` corresponds to one slice, identified by the matching index in `labels`.
+
+```ts
+interface ChartData {
+  labels: string[]       // One label per slice
+  datasets: ChartDataset[]  // Use one dataset for pie charts
+}
+
+interface ChartDataset {
+  label: string          // Series name (used in tooltip prefix)
+  data: number[]         // One value per slice (raw values; chart computes percentages)
+  color?: string         // Not used for pie — slice colors are auto-cycled from Bootstrap
+                         // CSS variables (--bs-primary, --bs-success, --bs-danger, ...)
+}
+```
+
+Slice colors are always auto-assigned from Bootstrap CSS variables in order — individual slice color overrides via `dataset.color` are not supported on pie charts.
+
+Import from `@velkymx/vibeui`:
+
+```ts
+import type { ChartData } from '@velkymx/vibeui'
+```
+
+## Usage
+
+### Basic Pie Chart
+
+```vue
+<script setup>
+const data = {
+  labels: ['Direct', 'Organic', 'Referral', 'Social'],
+  datasets: [
+    { label: 'Traffic', data: [40, 30, 20, 10] }
+  ]
+}
+</script>
+
+<template>
+  <VibeChartPie :data="data" />
+</template>
+```
+
+### Fixed Height, Legend at Top
+
+```vue
+<template>
+  <VibeChartPie :data="data" :height="300" legend="top" />
+</template>
+```
+
+### No Legend
+
+```vue
+<template>
+  <VibeChartPie :data="data" legend="none" />
+</template>
+```
+
+### Reactive Data
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const data = ref({
+  labels: ['A', 'B', 'C'],
+  datasets: [{ label: 'Share', data: [50, 30, 20] }]
+})
+
+function refresh() {
+  data.value.datasets[0].data = [35, 45, 20]
+}
+</script>
+
+<template>
+  <VibeChartPie :data="data" />
+  <button @click="refresh">Refresh</button>
+</template>
+```
+
+## Notes
+
+- **No external dependency.** VibeChartPie draws directly on a `<canvas>` element — no Chart.js or other charting library required.
+- **Color cycling.** Slice colors cycle through Bootstrap CSS variables (`--bs-primary`, `--bs-success`, `--bs-danger`, `--bs-warning`, `--bs-info`, ...) resolved from the container's computed styles. Colors follow your Bootstrap theme and dark mode.
+- **Responsive.** Defaults to a square 1:1 aspect ratio. The canvas resizes via `ResizeObserver` and redraws at device pixel ratio for crisp HiDPI output.
+- **Tooltips.** Hover over a slice to see the label and value.
+- **Single dataset.** Pass exactly one dataset. Multiple datasets are silently ignored.

package/docs/components/core/alert.md

@@ -9,8 +9,8 @@ Alert messages with Bootstrap styling, supporting variants, dismissible function
 | `variant` | `Variant` | `'primary'` | Color variant |
 | `subtle` | `Boolean` | `false` | Renders alert with subtle background and emphasis text |
 | `modelValue` | `Boolean` | `true` | Controls visibility (v-model support) |
-| `dismissable` | `Boolean` | `false` | Shows close button when true |
-| `message` | `String` | Required | Alert message text |
+| `dismissible` | `Boolean` | `false` | Shows close button when true |
+| `message` | `String` | `''` | Alert message text. Renders alongside default slot content; optional when the slot is used. |
 | `fade` | `Boolean` | `true` | Use fade animation on dismissal |
 
 ## Events
@@ -25,7 +25,7 @@ Alert messages with Bootstrap styling, supporting variants, dismissible function
 
 | Slot | Description |
 |------|-------------|
-| `default` | Alert content (overrides `message` prop) |
+| `default` | Additional alert content, appended after the `message` prop. When `message` is empty, slot is the sole content. |
 
 ## Usage
 
@@ -48,18 +48,40 @@ const showAlert = ref(true)
 <template>
   <VibeAlert
     variant="warning"
-    dismissable
+    dismissible
     v-model="showAlert"
     message="This alert can be dismissed"
   />
 </template>
 ```
 
+### Rich Content via Default Slot
+
+Use the default slot for inline buttons, links, icons, or rich VNode content. Slot content is appended after the `message` prop text — both render. Omit `message` when the slot is the sole content.
+
+```vue
+<template>
+  <!-- message prop + slot button coexist -->
+  <VibeAlert variant="success" message="Sprint locked. Planning is frozen.">
+    <div class="mt-2">
+      <VibeButton size="sm" variant="success" @click="goToBoard">Go to Sprint Board</VibeButton>
+    </div>
+  </VibeAlert>
+
+  <!-- slot as sole content -->
+  <VibeAlert variant="warning" dismissible>
+    <strong>Sprint locked.</strong>
+    Changes are frozen until release.
+    <VibeButton size="sm" variant="primary" @click="unlock">Unlock</VibeButton>
+  </VibeAlert>
+</template>
+```
+
 ## Important Notes
 
 **Automatic Initialization:** This component automatically initializes Bootstrap's Alert functionality when it is mounted, ensuring smooth dismissal animations.
 
-**Instance Exposure:** You can access the underlying Bootstrap instance via template ref using the `bsInstance` property.
+**Dismissing:** Use `v-model` to show/dismiss the alert programmatically — there is no exposed Bootstrap instance to manage manually.
 
 ## Bootstrap CSS Classes
 

package/docs/components/core/badge.md

@@ -11,12 +11,6 @@ Small count and labeling component with Bootstrap 5.3 styling.
 | `pill` | `Boolean` | `false` | Renders badge with rounded pill shape |
 | `tag` | `String` | `'span'` | HTML tag to render: `'span'`, `'a'`, or any valid tag |
 
-## Events
-
-| Event | Payload | Description |
-|-------|---------|-------------|
-| `component-error` | `Object` | Emitted when an error occurs |
-
 ## Slots
 
 | Slot | Description |

package/docs/components/core/button-group.md

@@ -11,12 +11,6 @@ Group buttons together in a single line or vertically.
 | `role` | `String` | `'group'` | ARIA role attribute |
 | `ariaLabel` | `String` | `undefined` | ARIA label for accessibility |
 
-## Events
-
-| Event | Payload | Description |
-|-------|---------|-------------|
-| `component-error` | `Object` | Emitted when an error occurs |
-
 ## Slots
 
 | Slot | Description |

package/docs/components/core/button.md

@@ -20,7 +20,7 @@ Button component with variants, sizes, and support for links and router-links.
 
 | Event | Payload | Description |
 |-------|---------|-------------|
-| `click` | `Event` | Emitted when button is clicked (unless disabled) |
+| `click` | `MouseEvent` | Emitted when button is clicked (unless disabled) |
 | `component-error` | `Object` | Emitted when an error occurs |
 
 ## Slots

package/docs/components/core/close-button.md

@@ -14,7 +14,7 @@ Generic close button for dismissing content like modals and alerts.
 
 | Event | Payload | Description |
 |-------|---------|-------------|
-| `click` | `Event` | Emitted when button is clicked (unless disabled) |
+| `click` | `MouseEvent` | Emitted when button is clicked (unless disabled) |
 | `component-error` | `Object` | Emitted when an error occurs |
 
 ## Usage
@@ -22,15 +22,15 @@ Generic close button for dismissing content like modals and alerts.
 ### Basic Close Button
 
 ```vue
-<template>
-  <VibeCloseButton @click="handleClose" />
-</template>
-
 <script setup>
 const handleClose = () => {
   console.log('Closed!')
 }
 </script>
+
+<template>
+  <VibeCloseButton @click="handleClose" />
+</template>
 ```
 
 ### White Variant

package/docs/components/core/link.md

@@ -1,34 +1,77 @@
 # VibeLink
 
-A flexible link component that supports Bootstrap 5.3's new link and underline utilities.
-
-## Basic Usage
-
-```vue
-<VibeLink href="https://example.com">Standard Link</VibeLink>
-
-<VibeLink variant="danger" underline="0">Link without underline</VibeLink>
-```
+A flexible link component that supports Bootstrap 5.3's link color and underline utilities, plus Vue Router integration.
 
 ## Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
+| `tag` | `Tag \| 'a'` | `'a'` | HTML tag to render (ignored when `to` is set — renders a router-link) |
+| `href` | `String` | `undefined` | URL for standard links. Sanitized — see Important Notes. |
+| `to` | `String \| Object` | `undefined` | Router link destination (renders `router-link`) |
 | `variant` | `Variant` | `undefined` | Link color variant (`primary`, `success`, etc.) |
-| `underline` | `Boolean \| '0' \| '1' \| '2' \| '3'` | `true` | Underline behavior. `'0'` removes underline. |
+| `underline` | `Boolean \| '0'` | `true` | Underline behavior. `false` or `'0'` removes the underline. |
 | `underlineVariant` | `Variant` | `undefined` | Color of the underline |
 | `underlineOpacity` | `0 \| 10 \| 25 \| 50 \| 75 \| 100` | `undefined` | Opacity of the underline |
 | `offset` | `1 \| 2 \| 3` | `undefined` | Underline offset from text |
 | `opacity` | `10 \| 25 \| 50 \| 75 \| 100` | `undefined` | Link text opacity |
-| `focusRing` | `Boolean` | `false` | Enable the focus-ring helper |
-| `href` | `String` | `undefined` | URL for standard links |
-| `to` | `String \| Object` | `undefined` | Router link destination |
-| `tag` | `String` | `'a'` | HTML tag to use (if not a router-link) |
+| `focusRing` | `Boolean` | `false` | Enable the Bootstrap 5.3 focus-ring helper |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Link content |
+
+## Usage
+
+### Basic Link
+
+```vue
+<template>
+  <VibeLink href="https://example.com">Standard Link</VibeLink>
+</template>
+```
+
+### Colored Link Without Underline
+
+```vue
+<template>
+  <VibeLink variant="danger" underline="0">Link without underline</VibeLink>
+</template>
+```
+
+### Underline Styling
+
+```vue
+<template>
+  <VibeLink
+    href="https://example.com"
+    underline-variant="success"
+    :underline-opacity="50"
+    :offset="2"
+  >
+    Styled underline
+  </VibeLink>
+</template>
+```
+
+### Router Link
+
+```vue
+<template>
+  <VibeLink :to="{ name: 'home' }">Home</VibeLink>
+</template>
+```
+
+## Important Notes
+
+**`href` sanitization:** The `href` prop is sanitized. Only `https://`/`http://` URLs, absolute paths (`/path`), relative paths (`./`, `../`), and anchors (`#section`) are allowed. Dangerous values such as `javascript:`, `data:`, `vbscript:`, and protocol-relative `//host` URLs are stripped — the `href` attribute is omitted entirely. Use `to` for in-app navigation via Vue Router.
+
+## Bootstrap CSS Classes
 
-## Bootstrap 5.3 Utilities
-This component maps directly to the following Bootstrap classes:
 - `.link-{variant}`
-- `.link-underline-0`
+- `.link-underline-opacity-0` (when `underline` is `false`/`'0'`)
 - `.link-underline-{variant}`
 - `.link-underline-opacity-{value}`
 - `.link-offset-{value}`

package/docs/components/core/placeholder.md

@@ -12,12 +12,6 @@ Placeholder loading component with optional animations.
 | `width` | `String\|Number` | `undefined` | Width as percentage or CSS value |
 | `tag` | `String` | `'span'` | HTML tag to render |
 
-## Events
-
-| Event | Payload | Description |
-|-------|---------|-------------|
-| `component-error` | `Object` | Emitted when an error occurs |
-
 ## Slots
 
 | Slot | Description |

package/docs/components/core/skeleton.md

@@ -0,0 +1,40 @@
+# VibeSkeleton
+
+Loading placeholder with shimmer animation. Drop-in replacement for ad-hoc empty states while data loads.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `'text' \| 'rect' \| 'circle' \| 'card'` | `'text'` | Shape preset |
+| `width` | `String \| Number` | `undefined` | CSS dimension. Number = pixels. |
+| `height` | `String \| Number` | `undefined` | CSS dimension. Number = pixels. |
+| `lines` | `Number` | `1` | Lines rendered when `variant="text"` |
+| `animated` | `Boolean` | `true` | Shimmer animation. Respects `prefers-reduced-motion`. |
+
+## Variants
+
+- **`text`**: stack of `lines` placeholder rows. Last line is shorter (60%).
+- **`rect`**: rectangular block.
+- **`circle`**: circular block. Setting `width` auto-applies same `height` for 1:1.
+- **`card`**: rectangular preview area + 2 text lines (image-card pattern).
+
+## Accessibility
+
+Each skeleton element exposes `role="status"` and `aria-busy="true"` so assistive tech announces a loading state.
+
+## Examples
+
+```vue
+<!-- 3 placeholder lines while a paragraph loads -->
+<VibeSkeleton :lines="3" />
+
+<!-- 64px avatar placeholder -->
+<VibeSkeleton variant="circle" :width="64" />
+
+<!-- 16:9 image area then text -->
+<VibeSkeleton variant="card" />
+
+<!-- Disable shimmer for low-power UI -->
+<VibeSkeleton variant="rect" :width="200" :height="100" :animated="false" />
+```

package/docs/components/core/spinner.md

@@ -12,12 +12,6 @@ Loading spinner with border or grow animation styles.
 | `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