@velkymx/vibeui 0.9.0 → 1.1.0

package/docs/components/core/badge.md

@@ -0,0 +1,75 @@
+# 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 |
+
+## 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,99 @@
+# 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 |
+
+## 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,145 @@
+# 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 |
+
+## Accessibility
+
+**Disabled contrast (WCAG 1.4.3):** The disabled state overrides Bootstrap's default `opacity: 0.65` fade with full-opacity body tokens (`--bs-body-color` / `--bs-tertiary-bg`), keeping label contrast ≥ 4.5:1 in both light and dark mode.
+
+**Icon-only buttons (WCAG 4.1.2):** A button whose slot contains only an icon (no visible text) must have an `aria-label` or `aria-labelledby` attribute so screen readers can announce its purpose. In development mode, VibeButton logs a `console.warn` when this is missing.
+
+```vue
+<!-- correct -->
+<VibeButton aria-label="Delete item">
+  <i class="bi bi-trash" aria-hidden="true" />
+</VibeButton>
+
+<!-- incorrect — no accessible name -->
+<VibeButton>
+  <i class="bi bi-trash" />
+</VibeButton>
+```
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `click` | `MouseEvent` | Emitted when button is clicked (unless disabled) |
+| `component-error` | `ComponentError` | 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` | `MouseEvent` | Emitted when button is clicked (unless disabled) |
+| `component-error` | `ComponentError` | Emitted when an error occurs |
+
+## Usage
+
+### Basic Close Button
+
+```vue
+<script setup>
+const handleClose = () => {
+  console.log('Closed!')
+}
+</script>
+
+<template>
+  <VibeCloseButton @click="handleClose" />
+</template>
+```
+
+### 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,79 @@
+# 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'` | `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 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
+
+- `.link-{variant}`
+- `.link-underline-opacity-0` (when `underline` is `false`/`'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,129 @@
+# 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 |
+
+## 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}`

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" />
+```