@velkymx/vibeui 0.9.0 → 1.1.0

package/docs/components/card/card.md

@@ -0,0 +1,223 @@
+# VibeCard
+
+Flexible content container component for displaying headers, bodies, footers, and images.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `Variant` | `undefined` | Background color variant |
+| `border` | `Variant` | `undefined` | Border color variant |
+| `textVariant` | `Variant` | `undefined` | Text color variant |
+| `tag` | `String` | `'div'` | HTML tag to render |
+| `title` | `String` | `undefined` | Card title |
+| `body` | `String` | `undefined` | Card body text |
+| `header` | `String` | `undefined` | Card header text |
+| `footer` | `String` | `undefined` | Card footer text |
+| `headerClass` | `String \| Array \| Object` | `undefined` | Extra class(es) for the `.card-header` wrapper (e.g. a variant-colored header) |
+| `bodyClass` | `String \| Array \| Object` | `undefined` | Extra class(es) for the `.card-body` wrapper |
+| `footerClass` | `String \| Array \| Object` | `undefined` | Extra class(es) for the `.card-footer` wrapper |
+| `imgSrc` | `String` | `undefined` | Image URL |
+| `imgAlt` | `String` | `''` | Image alt text |
+| `imgTop` | `Boolean` | `false` | Display image at top |
+| `imgBottom` | `Boolean` | `false` | Display image at bottom |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Additional body content |
+| `image` | A direct card child rendered **outside** `.card-body` (before the header) — for a card image with custom composition, e.g. a `card-img-top` with an absolutely-positioned overlay/badge |
+| `header` | Custom header content |
+| `title` | Custom title content |
+| `body` | Custom body content |
+| `footer` | Custom footer content |
+
+## Usage
+
+### Basic Card
+
+```vue
+<template>
+  <VibeCard
+    title="Card Title"
+    body="This is the card body text. Quick and easy!"
+  />
+</template>
+```
+
+### Card with Header and Footer
+
+```vue
+<template>
+  <VibeCard
+    header="Featured"
+    title="Special title treatment"
+    body="With supporting text below as a natural lead-in."
+    footer="2 days ago"
+  />
+</template>
+```
+
+### Card with Image
+
+```vue
+<template>
+  <VibeCard
+    img-src="/path/to/image.jpg"
+    img-alt="Card image"
+    img-top
+    title="Card with Image"
+    body="This card has an image at the top."
+  />
+</template>
+```
+
+### Colored Cards
+
+```vue
+<template>
+  <div>
+    <VibeCard
+      variant="primary"
+      text-variant="white"
+      title="Primary Card"
+      body="Card with primary background."
+    />
+
+    <VibeCard
+      variant="success"
+      text-variant="white"
+      title="Success Card"
+      body="Card with success background."
+    />
+  </div>
+</template>
+```
+
+### Border Variants
+
+```vue
+<template>
+  <div>
+    <VibeCard
+      border="primary"
+      title="Primary Border"
+      body="Card with primary border."
+    />
+
+    <VibeCard
+      border="danger"
+      title="Danger Border"
+      body="Card with danger border."
+    />
+  </div>
+</template>
+```
+
+### Custom Content with Slots
+
+Use named slots for complex content:
+
+```vue
+<template>
+  <VibeCard>
+    <template #header>
+      <strong>Featured</strong>
+    </template>
+
+    <template #title>
+      Special Title Treatment
+    </template>
+
+    <template #body>
+      <p>With supporting text below as a natural lead-in.</p>
+    </template>
+
+    <!-- Additional body content via default slot -->
+    <VibeButton variant="primary">Go somewhere</VibeButton>
+
+    <template #footer>
+      <small class="text-muted">Last updated 3 mins ago</small>
+    </template>
+  </VibeCard>
+</template>
+```
+
+### Horizontal Card
+
+Use the default slot with Bootstrap grid:
+
+```vue
+<template>
+  <VibeCard>
+    <div class="row g-0">
+      <div class="col-md-4">
+        <img src="/path/to/image.jpg" alt="..." class="card-img">
+      </div>
+      <div class="col-md-8">
+        <div class="card-body">
+          <h5 class="card-title">Horizontal Card</h5>
+          <p class="card-text">
+            This is a wider card with supporting text.
+          </p>
+          <p class="card-text">
+            <small class="text-muted">Last updated 3 mins ago</small>
+          </p>
+        </div>
+      </div>
+    </div>
+  </VibeCard>
+</template>
+```
+
+### Card Grid
+
+```vue
+<template>
+  <div class="row row-cols-1 row-cols-md-3 g-4">
+    <div class="col">
+      <VibeCard
+        img-src="/path/to/image1.jpg"
+        img-alt="Card 1"
+        img-top
+        title="Card 1"
+        body="Card content here."
+      />
+    </div>
+    <div class="col">
+      <VibeCard
+        img-src="/path/to/image2.jpg"
+        img-alt="Card 2"
+        img-top
+        title="Card 2"
+        body="Card content here."
+      />
+    </div>
+    <div class="col">
+      <VibeCard
+        img-src="/path/to/image3.jpg"
+        img-alt="Card 3"
+        img-top
+        title="Card 3"
+        body="Card content here."
+      />
+    </div>
+  </div>
+</template>
+```
+
+## Bootstrap CSS Classes
+
+- `.card`
+- `.card-header`
+- `.card-body`
+- `.card-footer`
+- `.card-img-top`
+- `.card-img-bottom`
+- `.card-img`
+- `.card-title`
+- `.card-text`
+- `.bg-{variant}`
+- `.border-{variant}`
+- `.text-{variant}`

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

@@ -0,0 +1,94 @@
+# VibeAlert
+
+Alert messages with Bootstrap styling, supporting variants, dismissible functionality, and v-model binding.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `Variant` | `'primary'` | Color variant |
+| `subtle` | `Boolean` | `false` | Renders alert with subtle background and emphasis text |
+| `modelValue` | `Boolean` | `true` | Controls visibility (v-model support) |
+| `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
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `Boolean` | Emitted when alert is dismissed |
+| `close` | - | Emitted when dismissal starts |
+| `closed` | - | Emitted when dismissal completes |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Additional alert content, appended after the `message` prop. When `message` is empty, slot is the sole content. |
+
+## Usage
+
+### Basic Alert
+
+```vue
+<template>
+  <VibeAlert variant="success" message="Operation completed successfully!" />
+</template>
+```
+
+### Dismissible Alert with v-model
+
+```vue
+<script setup>
+import { ref } from 'vue'
+const showAlert = ref(true)
+</script>
+
+<template>
+  <VibeAlert
+    variant="warning"
+    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.
+
+**Dismissing:** Use `v-model` to show/dismiss the alert programmatically — there is no exposed Bootstrap instance to manage manually.
+
+## Bootstrap CSS Classes
+
+- `.alert`
+- `.alert-{variant}`
+- `.bg-{variant}-subtle` (when `subtle` is true)
+- `.text-{variant}-emphasis` (when `subtle` is true)
+- `.border-{variant}-subtle` (when `subtle` is true)
+- `.alert-dismissible`
+- `.fade`, `.show`