@velkymx/vibeui 0.9.0 → 1.1.0

package/docs/components/interactive/toast.md

@@ -0,0 +1,177 @@
+# VibeToast
+
+Push notifications for lightweight alerts.
+
+The recommended way to show toasts is the **`useToast()` service** with a single `<VibeToastHost />` mounted once near your app root. The `<VibeToast>` component is the lower-level primitive for when you need a toast bound directly to local component state.
+
+## Toast Service (recommended)
+
+Mount `<VibeToastHost />` once (typically in `App.vue`), then call `useToast()` anywhere to enqueue toasts. The host manages containers, positioning, and dismissal for you.
+
+```vue
+<!-- App.vue -->
+<template>
+  <RouterView />
+  <VibeToastHost />
+</template>
+```
+
+```vue
+<!-- AnyComponent.vue -->
+<template>
+  <VibeButton @click="save">Save</VibeButton>
+</template>
+
+<script setup>
+import { useToast } from '@velkymx/vibeui'
+
+const toast = useToast()
+
+function save() {
+  // ...persist...
+  toast.success('Saved successfully')
+  toast.error('Something went wrong', { title: 'Error' })
+  toast.info('Heads up', { delay: 8000 })
+}
+</script>
+```
+
+### `useToast()` API
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `show` | `(body, options?) => ToastSpec` | Enqueue a toast with explicit options |
+| `success` | `(body, options?) => ToastSpec` | Shorthand for `variant: 'success'` |
+| `error` | `(body, options?) => ToastSpec` | Shorthand for `variant: 'danger'` |
+| `warn` | `(body, options?) => ToastSpec` | Shorthand for `variant: 'warning'` |
+| `info` | `(body, options?) => ToastSpec` | Shorthand for `variant: 'info'` |
+| `dismiss` | `(id) => boolean` | Remove a toast by id; returns `true` if found |
+| `clear` | `() => void` | Remove all queued toasts |
+| `toasts` | `readonly ToastSpec[]` | Reactive readonly snapshot of the queue |
+
+`ToastShowOptions`: `{ id?, title?, variant?, placement?, autohide?, delay? }`. Passing an existing `id` updates that toast in place instead of adding a new one. The variant shorthands (`success`, `error`, `warn`, `info`) accept the same options minus `variant`.
+
+### `<VibeToastHost />` Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `defaultPlacement` | `ToastPlacement` | `'top-end'` | Placement used for toasts that don't specify one |
+
+Toasts are grouped into one fixed container per placement, so toasts with different `placement` values render in the correct corner automatically.
+
+## VibeToast Component (primitive)
+
+Use the component directly when you want a toast tied to a local `v-model`.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `String` | `Auto-generated` | Unique identifier |
+| `modelValue` | `Boolean` | `false` | Control visibility (v-model) |
+| `title` | `String` | `''` | Toast title |
+| `variant` | `Variant` | `undefined` | Color variant |
+| `autohide` | `Boolean` | `true` | Auto hide after delay |
+| `delay` | `Number` | `5000` | Delay in milliseconds |
+| `teleport` | `Boolean\|String` | `'body'` | Destination for Vue Teleport |
+| `placement` | `ToastPlacement` | `'top-end'` | Position of the toast |
+| `noContainer` | `Boolean` | `false` | Render only the `.toast` element (no Teleport/container). Used internally by `VibeToastHost` to group toasts |
+
+### Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `Boolean` | Emitted when visibility changes |
+| `show` | - | Emitted when toast starts showing |
+| `shown` | - | Emitted when toast is fully shown |
+| `hide` | - | Emitted when toast starts hiding |
+| `hidden` | - | Emitted when toast is fully hidden |
+| `component-error` | `ComponentError` | Emitted if Bootstrap JS fails to load |
+
+### Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Toast body content |
+| `header` | Custom header content |
+
+### Usage
+
+```vue
+<template>
+  <div>
+    <VibeButton @click="showToast = true">Show Toast</VibeButton>
+
+    <VibeToast v-model="showToast" title="Notification" variant="primary">
+      This toast is controlled via Vue state.
+    </VibeToast>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+const showToast = ref(false)
+</script>
+```
+
+#### Placed Toasts
+
+```vue
+<template>
+  <div>
+    <VibeToast
+      v-model="showSuccess"
+      title="Success"
+      variant="success"
+      placement="bottom-end"
+    >
+      Operation completed successfully!
+    </VibeToast>
+
+    <VibeToast v-model="showInfo" title="Center" variant="info" placement="middle-center">
+      I am in the middle of the screen
+    </VibeToast>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+const showSuccess = ref(false)
+const showInfo = ref(false)
+</script>
+```
+
+#### Custom Delay
+
+```vue
+<template>
+  <VibeToast v-model="show" title="Quick Toast" :delay="2000">
+    This will auto-hide after 2 seconds
+  </VibeToast>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+const show = ref(true)
+</script>
+```
+
+## Important Notes
+
+**Prefer the service:** Use `useToast()` + `<VibeToastHost />` for most cases. It dedupes/updates by `id`, queues multiple toasts, and handles container placement. Reach for `<VibeToast>` only when you need a toast bound to a single local boolean.
+
+**Automatic Container:** Unlike raw Bootstrap, `<VibeToast>` automatically manages its own `toast-container` and positioning based on the `placement` prop (unless `noContainer` is set).
+
+**Teleportation:** By default, the component teleports to the `<body>` so it is always visible on top of other elements.
+
+**SSR:** The toast queue is a module singleton. In SSR runtimes call `resetToastStoreForSSR()` in your per-request reset hook to avoid leaking one request's pending toasts into another's render.
+
+**Escape Hatch:** `<VibeToast>` exposes `_unsafe_bsInstance` (raw Bootstrap Toast instance) via template ref. It is **not** part of the stable API — calling `dispose()` or other lifecycle methods on it directly **will** break the component. Prefer `v-model` and the exposed `show()` / `hide()` methods.
+
+## Bootstrap CSS Classes
+
+- `.toast`
+- `.toast-header`
+- `.toast-body`
+- `.text-bg-{variant}`
+- `.toast-container`

package/docs/components/layout/col.md

@@ -0,0 +1,117 @@
+# VibeCol
+
+Column component for Bootstrap's grid system. Supports responsive sizing, offsets, ordering, and alignment.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tag` | `Tag` | `'div'` | HTML element to render |
+| `cols` | `ColSize \| Boolean` | `undefined` | Base column width (`1`-`12`, `'auto'`, or `true` for equal-width) |
+| `sm` | `ColSize \| Boolean` | `undefined` | Column width at `sm` breakpoint |
+| `md` | `ColSize \| Boolean` | `undefined` | Column width at `md` breakpoint |
+| `lg` | `ColSize \| Boolean` | `undefined` | Column width at `lg` breakpoint |
+| `xl` | `ColSize \| Boolean` | `undefined` | Column width at `xl` breakpoint |
+| `xxl` | `ColSize \| Boolean` | `undefined` | Column width at `xxl` breakpoint |
+| `offset` | `Number` | `undefined` | Base offset (`0`-`11`) |
+| `offsetSm` | `Number` | `undefined` | Offset at `sm` breakpoint |
+| `offsetMd` | `Number` | `undefined` | Offset at `md` breakpoint |
+| `offsetLg` | `Number` | `undefined` | Offset at `lg` breakpoint |
+| `offsetXl` | `Number` | `undefined` | Offset at `xl` breakpoint |
+| `offsetXxl` | `Number` | `undefined` | Offset at `xxl` breakpoint |
+| `order` | `OrderValue` | `undefined` | Base visual order |
+| `orderSm` | `OrderValue` | `undefined` | Order at `sm` breakpoint |
+| `orderMd` | `OrderValue` | `undefined` | Order at `md` breakpoint |
+| `orderLg` | `OrderValue` | `undefined` | Order at `lg` breakpoint |
+| `orderXl` | `OrderValue` | `undefined` | Order at `xl` breakpoint |
+| `orderXxl` | `OrderValue` | `undefined` | Order at `xxl` breakpoint |
+| `alignSelf` | `AlignItems` | `undefined` | Individual column vertical alignment |
+
+### Type Reference
+
+- **ColSize:** `1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 'auto'`
+- **OrderValue:** `0 | 1 | 2 | 3 | 4 | 5 | 'first' | 'last'`
+- **AlignItems:** `'start' | 'center' | 'end' | 'baseline' | 'stretch'`
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Column content |
+
+## Usage
+
+### Equal-width Columns
+
+```vue
+<template>
+  <VibeRow>
+    <!-- No sizing props = equal-width (col class) -->
+    <VibeCol>1 of 3</VibeCol>
+    <VibeCol>2 of 3</VibeCol>
+    <VibeCol>3 of 3</VibeCol>
+  </VibeRow>
+</template>
+```
+
+### Specific Widths
+
+```vue
+<template>
+  <VibeRow>
+    <VibeCol :cols="8">Main content</VibeCol>
+    <VibeCol :cols="4">Sidebar</VibeCol>
+  </VibeRow>
+</template>
+```
+
+### Responsive Columns
+
+```vue
+<template>
+  <VibeRow>
+    <!-- Full width on mobile, half on medium, third on large -->
+    <VibeCol :cols="12" :md="6" :lg="4">Responsive</VibeCol>
+    <VibeCol :cols="12" :md="6" :lg="4">Responsive</VibeCol>
+    <VibeCol :cols="12" :md="12" :lg="4">Responsive</VibeCol>
+  </VibeRow>
+</template>
+```
+
+### Auto-width Column
+
+```vue
+<template>
+  <VibeRow>
+    <VibeCol :cols="2">Fixed</VibeCol>
+    <VibeCol cols="auto">Sized to content</VibeCol>
+    <VibeCol :cols="2">Fixed</VibeCol>
+  </VibeRow>
+</template>
+```
+
+### Offsets and Ordering
+
+```vue
+<template>
+  <VibeRow>
+    <VibeCol :cols="4" :offset="4">Centered column</VibeCol>
+  </VibeRow>
+
+  <VibeRow>
+    <VibeCol :cols="6" order="last">Appears second</VibeCol>
+    <VibeCol :cols="6" order="first">Appears first</VibeCol>
+  </VibeRow>
+</template>
+```
+
+### Vertical Alignment
+
+```vue
+<template>
+  <VibeRow align-items="start" style="height: 200px;">
+    <VibeCol>Top-aligned</VibeCol>
+    <VibeCol align-self="end">Bottom-aligned</VibeCol>
+  </VibeRow>
+</template>
+```

package/docs/components/layout/container.md

@@ -0,0 +1,53 @@
+# VibeContainer
+
+Responsive container component wrapping Bootstrap's `.container`, `.container-fluid`, and `.container-{breakpoint}` classes.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `fluid` | `Boolean \| ContainerType` | `false` | `false` = `.container`, `true` = `.container-fluid`, or a breakpoint (`'sm'`, `'md'`, `'lg'`, `'xl'`, `'xxl'`) for `.container-{breakpoint}` |
+| `tag` | `Tag` | `'div'` | HTML element to render |
+
+### ContainerType
+
+`'sm' | 'md' | 'lg' | 'xl' | 'xxl'`
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Container content |
+
+## Usage
+
+### Fixed-width Container
+
+```vue
+<template>
+  <VibeContainer>
+    <p>Responsive fixed-width container</p>
+  </VibeContainer>
+</template>
+```
+
+### Fluid Container
+
+```vue
+<template>
+  <VibeContainer fluid>
+    <p>Full-width container spanning the entire viewport</p>
+  </VibeContainer>
+</template>
+```
+
+### Responsive Breakpoint Container
+
+```vue
+<template>
+  <!-- 100% wide until the md breakpoint, then fixed-width -->
+  <VibeContainer fluid="md">
+    <p>Fluid until medium breakpoint</p>
+  </VibeContainer>
+</template>
+```

package/docs/components/layout/row.md

@@ -0,0 +1,107 @@
+# VibeRow
+
+Row component for Bootstrap's grid system. Provides gutters, row columns, and alignment props.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tag` | `Tag` | `'div'` | HTML element to render |
+| `gutters` | `GutterSize` | `undefined` | Base gutter size (both axes) |
+| `guttersX` | `GutterSize` | `undefined` | Horizontal gutter size |
+| `guttersY` | `GutterSize` | `undefined` | Vertical gutter size |
+| `guttersSm` | `GutterSize` | `undefined` | Gutter size at `sm` breakpoint |
+| `guttersMd` | `GutterSize` | `undefined` | Gutter size at `md` breakpoint |
+| `guttersLg` | `GutterSize` | `undefined` | Gutter size at `lg` breakpoint |
+| `guttersXl` | `GutterSize` | `undefined` | Gutter size at `xl` breakpoint |
+| `guttersXxl` | `GutterSize` | `undefined` | Gutter size at `xxl` breakpoint |
+| `guttersXSm` | `GutterSize` | `undefined` | Horizontal gutter at `sm` breakpoint |
+| `guttersXMd` | `GutterSize` | `undefined` | Horizontal gutter at `md` breakpoint |
+| `guttersXLg` | `GutterSize` | `undefined` | Horizontal gutter at `lg` breakpoint |
+| `guttersXXl` | `GutterSize` | `undefined` | Horizontal gutter at `xl` breakpoint |
+| `guttersXXxl` | `GutterSize` | `undefined` | Horizontal gutter at `xxl` breakpoint |
+| `guttersYSm` | `GutterSize` | `undefined` | Vertical gutter at `sm` breakpoint |
+| `guttersYMd` | `GutterSize` | `undefined` | Vertical gutter at `md` breakpoint |
+| `guttersYLg` | `GutterSize` | `undefined` | Vertical gutter at `lg` breakpoint |
+| `guttersYXl` | `GutterSize` | `undefined` | Vertical gutter at `xl` breakpoint |
+| `guttersYXxl` | `GutterSize` | `undefined` | Vertical gutter at `xxl` breakpoint |
+| `rowCols` | `RowColsSize` | `undefined` | Number of columns per row |
+| `rowColsSm` | `RowColsSize` | `undefined` | Columns per row at `sm` breakpoint |
+| `rowColsMd` | `RowColsSize` | `undefined` | Columns per row at `md` breakpoint |
+| `rowColsLg` | `RowColsSize` | `undefined` | Columns per row at `lg` breakpoint |
+| `rowColsXl` | `RowColsSize` | `undefined` | Columns per row at `xl` breakpoint |
+| `rowColsXxl` | `RowColsSize` | `undefined` | Columns per row at `xxl` breakpoint |
+| `alignItems` | `AlignItems` | `undefined` | Vertical alignment of columns |
+| `justifyContent` | `JustifyContent` | `undefined` | Horizontal distribution of columns |
+
+### Type Reference
+
+- **GutterSize:** `0 | 1 | 2 | 3 | 4 | 5`
+- **RowColsSize:** `1 | 2 | 3 | 4 | 5 | 6`
+- **AlignItems:** `'start' | 'center' | 'end' | 'baseline' | 'stretch'`
+- **JustifyContent:** `'start' | 'center' | 'end' | 'around' | 'between' | 'evenly'`
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Row content (typically `VibeCol` components) |
+
+## Usage
+
+### Basic Grid
+
+```vue
+<template>
+  <VibeContainer>
+    <VibeRow>
+      <VibeCol>Column 1</VibeCol>
+      <VibeCol>Column 2</VibeCol>
+      <VibeCol>Column 3</VibeCol>
+    </VibeRow>
+  </VibeContainer>
+</template>
+```
+
+### With Gutters
+
+```vue
+<template>
+  <VibeContainer>
+    <VibeRow :gutters="3" :guttersY="4">
+      <VibeCol :cols="6">Col 1</VibeCol>
+      <VibeCol :cols="6">Col 2</VibeCol>
+      <VibeCol :cols="6">Col 3</VibeCol>
+      <VibeCol :cols="6">Col 4</VibeCol>
+    </VibeRow>
+  </VibeContainer>
+</template>
+```
+
+### Row Columns
+
+```vue
+<template>
+  <VibeContainer>
+    <!-- Automatically size each child to 1/3 width -->
+    <VibeRow :row-cols="3">
+      <VibeCol>Item 1</VibeCol>
+      <VibeCol>Item 2</VibeCol>
+      <VibeCol>Item 3</VibeCol>
+    </VibeRow>
+  </VibeContainer>
+</template>
+```
+
+### Alignment
+
+```vue
+<template>
+  <VibeContainer>
+    <VibeRow align-items="center" justify-content="between">
+      <VibeCol :cols="4">Left</VibeCol>
+      <VibeCol :cols="4">Right</VibeCol>
+    </VibeRow>
+  </VibeContainer>
+</template>
+```

package/docs/components/list/list-group.md

@@ -0,0 +1,225 @@
+# VibeListGroup
+
+Data-driven component for displaying flexible lists of content.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `flush` | `Boolean` | `false` | Remove borders and rounded corners |
+| `horizontal` | `Boolean\|String` | `false` | Horizontal layout: `true` or breakpoint (`'sm'`, `'md'`, `'lg'`, `'xl'`) |
+| `numbered` | `Boolean` | `false` | Numbered list items |
+| `tag` | `String` | `'ul'` | HTML tag: `'ul'`, `'ol'`, or `'div'` |
+| `items` | `ListGroupItem[]` | Required | Array of list group items |
+
+### ListGroupItem Interface
+
+```typescript
+interface ListGroupItem {
+  text: string
+  href?: string
+  to?: string | object
+  active?: boolean
+  disabled?: boolean
+  variant?: Variant
+}
+```
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `item-click` | `{ item, index, event }` | Emitted when an item is clicked (unless disabled) |
+
+## Slots
+
+| Slot | Scope | Description |
+|------|-------|-------------|
+| `item` | `{ item, index }` | Custom item rendering |
+
+## Usage
+
+### Basic List
+
+```vue
+<template>
+  <VibeListGroup :items="listItems" />
+</template>
+
+<script setup>
+const listItems = [
+  { text: 'An item' },
+  { text: 'A second item' },
+  { text: 'A third item' }
+]
+</script>
+```
+
+### Active and Disabled Items
+
+```vue
+<template>
+  <VibeListGroup :items="listItems" />
+</template>
+
+<script setup>
+const listItems = [
+  { text: 'An item' },
+  { text: 'A second item', active: true },
+  { text: 'A third item' },
+  { text: 'A disabled item', disabled: true }
+]
+</script>
+```
+
+### With Links
+
+```vue
+<template>
+  <VibeListGroup :items="listItems" />
+</template>
+
+<script setup>
+const listItems = [
+  { text: 'Link 1', href: '#', active: true },
+  { text: 'Link 2', href: '#' },
+  { text: 'Link 3', href: '#' }
+]
+</script>
+```
+
+### With Router Links
+
+```vue
+<template>
+  <VibeListGroup :items="listItems" />
+</template>
+
+<script setup>
+const listItems = [
+  { text: 'Home', to: { name: 'home' } },
+  { text: 'About', to: { name: 'about' } },
+  { text: 'Contact', to: { name: 'contact' } }
+]
+</script>
+```
+
+### Colored Items
+
+```vue
+<template>
+  <VibeListGroup :items="listItems" />
+</template>
+
+<script setup>
+const listItems = [
+  { text: 'Primary item', variant: 'primary' },
+  { text: 'Success item', variant: 'success' },
+  { text: 'Danger item', variant: 'danger' },
+  { text: 'Warning item', variant: 'warning' },
+  { text: 'Info item', variant: 'info' }
+]
+</script>
+```
+
+### Flush List
+
+Remove borders and rounded corners:
+
+```vue
+<template>
+  <VibeListGroup flush :items="listItems" />
+</template>
+```
+
+### Horizontal List
+
+```vue
+<template>
+  <!-- Always horizontal -->
+  <VibeListGroup horizontal :items="listItems" />
+
+  <!-- Horizontal on md and up -->
+  <VibeListGroup horizontal="md" :items="listItems" />
+</template>
+```
+
+### Numbered List
+
+```vue
+<template>
+  <VibeListGroup numbered tag="ol" :items="listItems" />
+</template>
+
+<script setup>
+const listItems = [
+  { text: 'First item' },
+  { text: 'Second item' },
+  { text: 'Third item' }
+]
+</script>
+```
+
+### Custom Item Rendering
+
+Use the `item` scoped slot for complex content:
+
+```vue
+<template>
+  <VibeListGroup :items="listItems">
+    <template #item="{ item }">
+      <div class="d-flex justify-content-between align-items-center">
+        <div>
+          <h5 class="mb-1">{{ item.text }}</h5>
+          <p class="mb-1">{{ item.description }}</p>
+        </div>
+        <VibeBadge variant="primary">{{ item.count }}</VibeBadge>
+      </div>
+    </template>
+  </VibeListGroup>
+</template>
+
+<script setup>
+const listItems = [
+  { text: 'Inbox', description: 'Unread messages', count: 14 },
+  { text: 'Starred', description: 'Important items', count: 3 },
+  { text: 'Sent', description: 'Outgoing mail', count: 25 }
+]
+</script>
+```
+
+### With Event Handling
+
+```vue
+<template>
+  <VibeListGroup :items="listItems" @item-click="handleClick" />
+</template>
+
+<script setup>
+const listItems = [
+  { text: 'Item 1' },
+  { text: 'Item 2' },
+  { text: 'Item 3' }
+]
+
+const handleClick = ({ item, index }) => {
+  console.log(`Clicked: ${item.text} at index ${index}`)
+}
+</script>
+```
+
+## Important Notes
+
+**`href` sanitization:** Each item's `href` 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 item renders without an `href` (falling back to a non-link element). Use `to` for in-app navigation via Vue Router.
+
+## Bootstrap CSS Classes
+
+- `.list-group`
+- `.list-group-flush`
+- `.list-group-horizontal`, `.list-group-horizontal-{breakpoint}`
+- `.list-group-numbered`
+- `.list-group-item`
+- `.list-group-item-{variant}`
+- `.list-group-item-action`
+- `.active`
+- `.disabled`