@velkymx/vibeui 0.8.0 → 0.8.2

package/docs/components/core/alert.md

@@ -0,0 +1,72 @@
+# 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) |
+| `dismissable` | `Boolean` | `false` | Shows close button when true |
+| `message` | `String` | Required | Alert message text |
+| `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` | Alert content (overrides `message` prop) |
+
+## 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"
+    dismissable
+    v-model="showAlert"
+    message="This alert can be dismissed"
+  />
+</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.
+
+## 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`

package/docs/components/core/badge.md

@@ -0,0 +1,81 @@
+# VibeBadge
+
+Small count and labeling component with Bootstrap 5.3 styling.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `Variant` | `'primary'` | Background color variant |
+| `subtle` | `Boolean` | `false` | Renders badge with subtle background and emphasis text |
+| `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 |
+|------|-------------|
+| `default` | Badge content |
+
+## Usage
+
+### Basic Badge
+
+```vue
+<template>
+  <VibeButton variant="primary">
+    Notifications <VibeBadge variant="secondary">4</VibeBadge>
+  </VibeButton>
+</template>
+```
+
+### Pill Badges
+
+```vue
+<template>
+  <div>
+    <VibeBadge variant="primary" pill>Primary</VibeBadge>
+    <VibeBadge variant="success" pill>Success</VibeBadge>
+    <VibeBadge variant="danger" pill>Danger</VibeBadge>
+  </div>
+</template>
+```
+
+### Link Badges
+
+```vue
+<template>
+  <VibeBadge tag="a" href="#" variant="primary">Link Badge</VibeBadge>
+</template>
+```
+
+### All Variants
+
+```vue
+<template>
+  <div>
+    <VibeBadge variant="primary">Primary</VibeBadge>
+    <VibeBadge variant="secondary">Secondary</VibeBadge>
+    <VibeBadge variant="success">Success</VibeBadge>
+    <VibeBadge variant="danger">Danger</VibeBadge>
+    <VibeBadge variant="warning">Warning</VibeBadge>
+    <VibeBadge variant="info">Info</VibeBadge>
+    <VibeBadge variant="light">Light</VibeBadge>
+    <VibeBadge variant="dark">Dark</VibeBadge>
+  </div>
+</template>
+```
+
+## Bootstrap CSS Classes
+
+- `.badge`
+- `.bg-{variant}`
+- `.bg-{variant}-subtle` (when `subtle` is true)
+- `.text-{variant}-emphasis` (when `subtle` is true)
+- `.rounded-pill` (when `pill` is true)

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

@@ -0,0 +1,105 @@
+# VibeButtonGroup
+
+Group buttons together in a single line or vertically.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `size` | `Size` | `undefined` | Size for all buttons in group: `'sm'` or `'lg'` |
+| `vertical` | `Boolean` | `false` | Stack buttons 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 |
+|------|-------------|
+| `default` | Button group content (typically VibeButton components) |
+
+## Usage
+
+### Basic Button Group
+
+```vue
+<template>
+  <VibeButtonGroup>
+    <VibeButton variant="primary">Left</VibeButton>
+    <VibeButton variant="primary">Middle</VibeButton>
+    <VibeButton variant="primary">Right</VibeButton>
+  </VibeButtonGroup>
+</template>
+```
+
+### Button Toolbar
+
+```vue
+<template>
+  <div>
+    <VibeButtonGroup aria-label="First group">
+      <VibeButton variant="secondary">1</VibeButton>
+      <VibeButton variant="secondary">2</VibeButton>
+      <VibeButton variant="secondary">3</VibeButton>
+    </VibeButtonGroup>
+
+    <VibeButtonGroup aria-label="Second group">
+      <VibeButton variant="secondary">4</VibeButton>
+      <VibeButton variant="secondary">5</VibeButton>
+    </VibeButtonGroup>
+  </div>
+</template>
+```
+
+### Vertical Button Group
+
+```vue
+<template>
+  <VibeButtonGroup vertical>
+    <VibeButton variant="primary">Button 1</VibeButton>
+    <VibeButton variant="primary">Button 2</VibeButton>
+    <VibeButton variant="primary">Button 3</VibeButton>
+  </VibeButtonGroup>
+</template>
+```
+
+### Sized Button Groups
+
+```vue
+<template>
+  <div>
+    <VibeButtonGroup size="sm">
+      <VibeButton variant="primary">Small</VibeButton>
+      <VibeButton variant="primary">Group</VibeButton>
+    </VibeButtonGroup>
+
+    <VibeButtonGroup size="lg">
+      <VibeButton variant="primary">Large</VibeButton>
+      <VibeButton variant="primary">Group</VibeButton>
+    </VibeButtonGroup>
+  </div>
+</template>
+```
+
+### Mixed Button Types
+
+```vue
+<template>
+  <VibeButtonGroup>
+    <VibeButton variant="danger">Delete</VibeButton>
+    <VibeButton variant="warning" outline>Archive</VibeButton>
+    <VibeButton variant="success">Save</VibeButton>
+  </VibeButtonGroup>
+</template>
+```
+
+## Bootstrap CSS Classes
+
+- `.btn-group`
+- `.btn-group-vertical`
+- `.btn-group-{size}`

package/docs/components/core/button.md

@@ -0,0 +1,127 @@
+# VibeButton
+
+Button component with variants, sizes, and support for links and router-links.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `Variant` | `'primary'` | Button color variant |
+| `size` | `Size` | `undefined` | Button size: `'sm'` or `'lg'` |
+| `outline` | `Boolean` | `false` | Use outline style instead of solid |
+| `disabled` | `Boolean` | `false` | Disable the button |
+| `type` | `ButtonType` | `'button'` | Button type: `'button'`, `'submit'`, or `'reset'` |
+| `href` | `String` | `undefined` | Renders as anchor tag with href |
+| `to` | `String\|Object` | `undefined` | Renders as router-link with to prop |
+| `active` | `Boolean` | `false` | Apply active state styling |
+| `focusRing` | `Boolean` | `false` | Enable the Bootstrap 5.3 focus-ring helper |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `click` | `Event` | Emitted when button is clicked (unless disabled) |
+| `component-error` | `Object` | Emitted when an error occurs |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Button content |
+
+## Usage
+
+### Basic Buttons
+
+```vue
+<template>
+  <div>
+    <VibeButton variant="primary">Primary</VibeButton>
+    <VibeButton variant="secondary">Secondary</VibeButton>
+    <VibeButton variant="success">Success</VibeButton>
+  </div>
+</template>
+```
+
+### Outline Buttons
+
+```vue
+<template>
+  <div>
+    <VibeButton variant="primary" outline>Outline Primary</VibeButton>
+    <VibeButton variant="danger" outline>Outline Danger</VibeButton>
+  </div>
+</template>
+```
+
+### Button Sizes
+
+```vue
+<template>
+  <div>
+    <VibeButton variant="primary" size="sm">Small</VibeButton>
+    <VibeButton variant="primary">Normal</VibeButton>
+    <VibeButton variant="primary" size="lg">Large</VibeButton>
+  </div>
+</template>
+```
+
+### Disabled State
+
+```vue
+<template>
+  <VibeButton variant="primary" disabled>Disabled Button</VibeButton>
+</template>
+```
+
+### Link Buttons
+
+```vue
+<template>
+  <div>
+    <!-- Anchor link -->
+    <VibeButton variant="primary" href="https://example.com">
+      External Link
+    </VibeButton>
+
+    <!-- Router link (requires Vue Router) -->
+    <VibeButton variant="secondary" :to="{ name: 'home' }">
+      Home
+    </VibeButton>
+  </div>
+</template>
+```
+
+### Form Submit
+
+```vue
+<template>
+  <form @submit.prevent="handleSubmit">
+    <VibeButton type="submit" variant="success">Submit Form</VibeButton>
+  </form>
+</template>
+```
+
+### With Click Handler
+
+```vue
+<script setup>
+const handleClick = () => {
+  console.log('Button clicked!')
+}
+</script>
+
+<template>
+  <VibeButton variant="primary" @click="handleClick">
+    Click Me
+  </VibeButton>
+</template>
+```
+
+## Bootstrap CSS Classes
+
+- `.btn`
+- `.btn-{variant}` or `.btn-outline-{variant}`
+- `.btn-{size}`
+- `.active`
+- `.focus-ring`

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

@@ -0,0 +1,82 @@
+# VibeCloseButton
+
+Generic close button for dismissing content like modals and alerts.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `disabled` | `Boolean` | `false` | Disable the close button |
+| `white` | `Boolean` | `false` | Use white variant for dark backgrounds |
+| `ariaLabel` | `String` | `'Close'` | Accessible label for screen readers |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `click` | `Event` | Emitted when button is clicked (unless disabled) |
+| `component-error` | `Object` | Emitted when an error occurs |
+
+## Usage
+
+### Basic Close Button
+
+```vue
+<template>
+  <VibeCloseButton @click="handleClose" />
+</template>
+
+<script setup>
+const handleClose = () => {
+  console.log('Closed!')
+}
+</script>
+```
+
+### White Variant
+
+```vue
+<template>
+  <div class="bg-dark p-3">
+    <VibeCloseButton white />
+  </div>
+</template>
+```
+
+### Custom Aria Label
+
+```vue
+<template>
+  <VibeCloseButton aria-label="Dismiss notification" />
+</template>
+```
+
+### Disabled State
+
+```vue
+<template>
+  <VibeCloseButton disabled />
+</template>
+```
+
+### In Alert Context
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const showAlert = ref(true)
+</script>
+
+<template>
+  <div v-if="showAlert" class="alert alert-warning d-flex justify-content-between">
+    <span>Warning message</span>
+    <VibeCloseButton @click="showAlert = false" />
+  </div>
+</template>
+```
+
+## Bootstrap CSS Classes
+
+- `.btn-close`
+- `.btn-close-white`

package/docs/components/core/link.md

@@ -0,0 +1,36 @@
+# 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>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `Variant` | `undefined` | Link color variant (`primary`, `success`, etc.) |
+| `underline` | `Boolean \| '0' \| '1' \| '2' \| '3'` | `true` | Underline behavior. `'0'` removes 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) |
+
+## Bootstrap 5.3 Utilities
+This component maps directly to the following Bootstrap classes:
+- `.link-{variant}`
+- `.link-underline-0`
+- `.link-underline-{variant}`
+- `.link-underline-opacity-{value}`
+- `.link-offset-{value}`
+- `.link-opacity-{value}`
+- `.focus-ring`

package/docs/components/core/placeholder.md

@@ -0,0 +1,135 @@
+# VibePlaceholder
+
+Placeholder loading component with optional animations.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `Variant` | `undefined` | Background color variant |
+| `size` | `Size` | `undefined` | Placeholder size: `'sm'` or `'lg'` |
+| `animation` | `PlaceholderAnimation` | `undefined` | Animation type: `'glow'` or `'wave'` |
+| `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 |
+|------|-------------|
+| `default` | Placeholder content (typically empty) |
+
+## Usage
+
+### Basic Placeholder
+
+```vue
+<template>
+  <VibePlaceholder width="75" />
+</template>
+```
+
+### Placeholder Card
+
+```vue
+<template>
+  <VibeCard>
+    <template #title>
+      <VibePlaceholder width="100" />
+    </template>
+    <template #body>
+      <VibePlaceholder width="100" />
+      <VibePlaceholder width="100" />
+      <VibePlaceholder width="75" />
+    </template>
+  </VibeCard>
+</template>
+```
+
+### With Glow Animation
+
+```vue
+<template>
+  <div>
+    <VibePlaceholder animation="glow" width="100" />
+    <VibePlaceholder animation="glow" width="75" />
+  </div>
+</template>
+```
+
+### With Wave Animation
+
+```vue
+<template>
+  <div>
+    <VibePlaceholder animation="wave" width="100" />
+    <VibePlaceholder animation="wave" width="90" />
+    <VibePlaceholder animation="wave" width="80" />
+  </div>
+</template>
+```
+
+### Colored Placeholders
+
+```vue
+<template>
+  <div>
+    <VibePlaceholder variant="primary" width="100" />
+    <VibePlaceholder variant="success" width="75" />
+    <VibePlaceholder variant="danger" width="50" />
+  </div>
+</template>
+```
+
+### Sizes
+
+```vue
+<template>
+  <div>
+    <VibePlaceholder size="lg" width="100" />
+    <VibePlaceholder width="100" />
+    <VibePlaceholder size="sm" width="100" />
+  </div>
+</template>
+```
+
+### Loading State Example
+
+```vue
+<script setup>
+import { ref, onMounted } from 'vue'
+
+const loading = ref(true)
+const data = ref(null)
+
+onMounted(async () => {
+  // Simulate API call
+  await new Promise(resolve => setTimeout(resolve, 2000))
+  data.value = { title: 'Article Title', content: 'Article content...' }
+  loading.value = false
+})
+</script>
+
+<template>
+  <VibeCard v-if="loading">
+    <template #body>
+      <VibePlaceholder animation="glow" width="100" />
+      <VibePlaceholder animation="glow" width="100" />
+      <VibePlaceholder animation="glow" width="75" />
+    </template>
+  </VibeCard>
+  <VibeCard v-else :title="data.title" :body="data.content" />
+</template>
+```
+
+## Bootstrap CSS Classes
+
+- `.placeholder`
+- `.bg-{variant}`
+- `.placeholder-{size}`
+- `.placeholder-{animation}`