@baklavue/mcp 1.0.0

package/dist/docs/components/notification.md

@@ -0,0 +1,179 @@
+# Notification
+
+A Vue UI kit component for Baklava's `bl-notification` web component for toast notifications. Place the Notification component once in your app (typically at root or layout level). Notifications are triggered programmatically via the `useNotification` composable from `@baklavue/composables`.
+
+## Basic Usage
+
+Place `<BvNotification />` in your app. It acts as a container for toast notifications that appear when you call `useNotification()` methods.
+
+<div class="component-demo">
+
+<NotificationBasicDemo />
+
+</div>
+
+```vue
+<template>
+  <div>
+    <BvButton @click="showSuccess">Show Success</BvButton>
+    <BvButton kind="danger" @click="showError">Show Error</BvButton>
+    <BvNotification />
+  </div>
+</template>
+
+<script setup>
+import { BvButton, BvNotification } from "@baklavue/ui";
+import { useNotification } from "@baklavue/composables";
+
+const { success, error } = useNotification();
+
+const showSuccess = () => {
+  success({
+    caption: "Success!",
+    description: "Operation completed successfully.",
+  });
+};
+
+const showError = () => {
+  error({
+    caption: "Error",
+    description: "Something went wrong.",
+  });
+};
+</script>
+```
+
+## With Composables
+
+The `useNotification` composable provides four methods: `success`, `error`, `warning`, and `info`. Each displays a notification with the corresponding kind (icon and styling).
+
+<div class="component-demo">
+
+<NotificationBasicDemo />
+
+</div>
+
+```vue
+<template>
+  <div>
+    <BvButton kind="success" @click="showSuccess">Success</BvButton>
+    <BvButton kind="danger" @click="showError">Error</BvButton>
+    <BvButton kind="neutral" @click="showWarning">Warning</BvButton>
+    <BvButton @click="showInfo">Info</BvButton>
+    <BvNotification />
+  </div>
+</template>
+
+<script setup>
+import { BvButton, BvNotification } from "@baklavue/ui";
+import { useNotification } from "@baklavue/composables";
+
+const { success, error, warning, info } = useNotification();
+
+const showSuccess = () =>
+  success({
+    caption: "Success!",
+    description: "Operation completed successfully.",
+  });
+
+const showError = () =>
+  error({
+    caption: "Error",
+    description: "Something went wrong.",
+  });
+
+const showWarning = () =>
+  warning({
+    caption: "Warning",
+    description: "Please check your input.",
+  });
+
+const showInfo = () =>
+  info({
+    caption: "Info",
+    description: "This is an informational message.",
+  });
+</script>
+```
+
+## Custom Duration
+
+Control the default duration via the `duration` prop on the component (in seconds). You can also override duration per notification when calling `success`, `error`, `warning`, or `info`.
+
+<div class="component-demo">
+
+<NotificationDurationDemo />
+
+</div>
+
+```vue
+<template>
+  <div>
+    <BvButton @click="showShort">Show 3s notification</BvButton>
+    <BvButton @click="showLong">Show 10s notification</BvButton>
+    <BvNotification :duration="5" />
+  </div>
+</template>
+
+<script setup>
+import { BvButton, BvNotification } from "@baklavue/ui";
+import { useNotification } from "@baklavue/composables";
+
+const { success } = useNotification();
+
+const showShort = () => {
+  success({
+    caption: "Short duration",
+    description: "This notification stays for 3 seconds.",
+    duration: 3,
+  });
+};
+
+const showLong = () => {
+  success({
+    caption: "Long duration",
+    description: "This notification stays for 10 seconds.",
+    duration: 10,
+  });
+};
+</script>
+```
+
+## Props
+
+| Prop          | Type      | Default | Description                                                     |
+| ------------- | --------- | ------- | --------------------------------------------------------------- |
+| `duration`    | `number`  | `7`     | Default duration of notifications in seconds                    |
+| `noAnimation` | `boolean` | `false` | Disable animations. Respects user's reduced-motion preferences. |
+
+## Types
+
+```typescript
+import type { NotificationProps } from "@baklavue/ui";
+
+// Notification component props (duration, noAnimation)
+interface NotificationProps {
+  duration?: number;
+  noAnimation?: boolean;
+}
+
+// useNotification options (caption, description) - maps to Baklava NotificationProps
+interface UseNotificationOptions {
+  caption?: string; // Notification title
+  description: string; // Notification message (required)
+  duration?: number;
+  permanent?: boolean;
+  primaryAction?: { label: string; onClick: () => void };
+  secondaryAction?: { label: string; onClick: () => void };
+}
+```
+
+## Usage Notes
+
+- **Placement**: Place `<BvNotification />` once in your app, typically at the root layout or App.vue. It renders the `bl-notification` container; notifications are added via `useNotification()`.
+
+- **useNotification requirement**: The `useNotification` composable requires a `<BvNotification />` (or `<bl-notification>`) component to be present in the DOM. If it is missing, a console warning is shown and notifications will not appear.
+
+- **Accessibility**: The component follows Baklava's accessibility guidelines. The `noAnimation` prop respects the user's reduced-motion preferences.
+
+- **Styling**: The component uses Baklava's default styling. Custom styling can be applied through CSS variables or by overriding the component styles.

package/dist/docs/components/pagination.md

@@ -0,0 +1,168 @@
+# Pagination
+
+A Vue UI kit component for Baklava's `bl-pagination` web component for page navigation. Supports v-model for two-way binding of the current page and emits change events when the user navigates.
+
+## Basic Usage
+
+Use the Pagination component with `v-model:current-page` for two-way binding. Pass `total-items` (total item count) and `page-size` (items per page).
+
+<div class="component-demo">
+
+<PaginationBasicDemo />
+
+</div>
+
+```vue
+<template>
+  <div>
+    <p>Current page: {{ currentPage }}</p>
+    <BvPagination
+      v-model:current-page="currentPage"
+      :total-items="100"
+      :page-size="10"
+      @change="handlePageChange"
+    />
+  </div>
+</template>
+
+<script setup>
+import { ref } from "vue";
+import { BvPagination } from "@baklavue/ui";
+
+const currentPage = ref(1);
+
+const handlePageChange = (event) => {
+  const detail = event.detail;
+  if (detail) {
+    console.log(
+      "Page changed:",
+      detail.selectedPage,
+      "Previous:",
+      detail.prevPage,
+      "Items per page:",
+      detail.itemsPerPage
+    );
+  }
+};
+</script>
+```
+
+## With Jumper
+
+Add a jumper input to let users jump directly to a page. Set `has-jumper` to `true` and optionally provide a `jumper-label`.
+
+<div class="component-demo">
+
+<PaginationJumperDemo />
+
+</div>
+
+```vue
+<template>
+  <BvPagination
+    v-model:current-page="currentPage"
+    :total-items="250"
+    :page-size="25"
+    :has-jumper="true"
+    jumper-label="Go to page"
+  />
+</template>
+
+<script setup>
+import { ref } from "vue";
+import { BvPagination } from "@baklavue/ui";
+
+const currentPage = ref(1);
+</script>
+```
+
+## With Items Per Page Select
+
+Add a select dropdown to let users choose how many items per page to display. Set `has-select` to `true` and provide `items-per-page-options`.
+
+<div class="component-demo">
+
+<PaginationSelectDemo />
+
+</div>
+
+```vue
+<template>
+  <BvPagination
+    v-model:current-page="currentPage"
+    :total-items="100"
+    :page-size="10"
+    :has-select="true"
+    select-label="Items per page"
+    :items-per-page-options="itemsPerPageOptions"
+  />
+</template>
+
+<script setup>
+import { ref } from "vue";
+import { BvPagination } from "@baklavue/ui";
+
+const currentPage = ref(1);
+
+const itemsPerPageOptions = [
+  { text: "10 Items", value: 10 },
+  { text: "25 Items", value: 25 },
+  { text: "50 Items", value: 50 },
+  { text: "100 Items", value: 100 },
+];
+</script>
+```
+
+## Props
+
+| Prop                   | Type                    | Default     | Description                                                    |
+| ---------------------- | ----------------------- | ----------- | -------------------------------------------------------------- |
+| `currentPage`          | `number`                | `undefined` | Current page number (1-based). Supports v-model:currentPage.  |
+| `totalItems`           | `number`                | `undefined` | Total number of items to be paginated                          |
+| `pageSize`             | `number`                | `undefined` | Number of items per page                                       |
+| `hasJumper`            | `boolean`               | `false`     | When true, adds a jumper input to jump directly to a page      |
+| `jumperLabel`          | `string`                | `undefined` | Label for the jumper input                                     |
+| `hasSelect`            | `boolean`               | `false`     | When true, adds a select to choose items per page              |
+| `selectLabel`          | `string`                | `undefined` | Label for the items-per-page select                            |
+| `itemsPerPageOptions`  | `ItemsPerPageOption[]`  | `undefined` | Options for the items-per-page select (`text`, `value`)        |
+
+## Events
+
+| Event                  | Payload | Description                                                                 |
+| ---------------------- | ------- | --------------------------------------------------------------------------- |
+| `update:currentPage`   | `number`| Emitted when the current page changes (for v-model:currentPage)              |
+| `change`               | `CustomEvent` | Emitted when the user navigates. `event.detail` has `{ selectedPage, prevPage, itemsPerPage }` |
+
+## Types
+
+```typescript
+import type { PaginationProps, ItemsPerPageOption } from "@baklavue/ui";
+
+interface ItemsPerPageOption {
+  text: string;
+  value: number;
+}
+
+interface PaginationProps {
+  currentPage?: number;
+  totalItems?: number;
+  pageSize?: number;
+  hasJumper?: boolean;
+  jumperLabel?: string;
+  hasSelect?: boolean;
+  selectLabel?: string;
+  itemsPerPageOptions?: ItemsPerPageOption[];
+}
+```
+
+## Usage Notes
+
+- **Total Items vs Total Pages**: The component uses `totalItems` (total item count), not total pages. Baklava computes the page count internally from `totalItems` and `pageSize`.
+
+- **v-model**: Use `v-model:current-page` for two-way binding of the current page number.
+
+- **Change Event**: The `change` event receives a `CustomEvent` whose `detail` contains `{ selectedPage, prevPage, itemsPerPage }`.
+
+- **Accessibility**: The component follows Baklava's accessibility guidelines for pagination controls.
+
+- **Styling**: The component uses Baklava's default styling. Custom styling can be applied through CSS variables or by overriding the component styles.

package/dist/docs/components/radio.md

@@ -0,0 +1,221 @@
+# Radio
+
+A Vue UI kit component for Baklava's `bl-radio` and `bl-radio-group` components for single-choice selections. Use the `items` prop to create a radio group. Selected value is bound via v-model.
+
+## Basic Usage
+
+<div class="component-demo">
+
+<RadioSingleDemo />
+
+</div>
+
+```vue
+<template>
+  <BvRadio v-model="selected" :items="items">
+    <template #item="{ item }">{{ item.label }}</template>
+  </BvRadio>
+</template>
+
+<script setup>
+import { ref } from "vue";
+import { BvRadio } from "@baklavue/ui";
+
+const selected = ref("option1");
+const items = [
+  { value: "option1", label: "Option 1" },
+  { value: "option2", label: "Option 2" },
+];
+</script>
+```
+
+## Multiple Options
+
+<div class="component-demo">
+
+<RadioGroupDemo />
+
+</div>
+
+```vue
+<template>
+  <BvRadio v-model="choice" :items="items">
+    <template #item="{ item }">{{ item.label }}</template>
+  </BvRadio>
+</template>
+
+<script setup>
+import { ref } from "vue";
+import { BvRadio } from "@baklavue/ui";
+
+const choice = ref("yes");
+const items = [
+  { value: "yes", label: "Yes" },
+  { value: "no", label: "No" },
+  { value: "maybe", label: "Maybe" },
+];
+</script>
+```
+
+## Disabled State
+
+Disable individual radios to prevent user interaction.
+
+<div class="component-demo">
+
+<RadioDisabledDemo />
+
+</div>
+
+```vue
+<template>
+  <BvRadio v-model="choice" :items="items">
+    <template #item="{ item }">{{ item.label }}</template>
+  </BvRadio>
+</template>
+
+<script setup>
+import { ref } from "vue";
+import { BvRadio } from "@baklavue/ui";
+
+const choice = ref("yes");
+const items = [
+  { value: "yes", label: "Yes" },
+  { value: "no", label: "No" },
+  { value: "maybe", label: "Maybe (disabled)", disabled: true },
+];
+</script>
+```
+
+## Custom Content with #item Slot
+
+Use the `#item` scoped slot to customize the label or content of each radio. The slot receives `{ item, index }`.
+
+```vue
+<template>
+  <BvRadio v-model="choice" :items="items">
+    <template #item="{ item }">
+      <span>{{ item.label }}</span>
+    </template>
+  </BvRadio>
+</template>
+
+<script setup>
+import { ref } from "vue";
+import { BvRadio } from "@baklavue/ui";
+
+const choice = ref("email");
+const items = [
+  { value: "email", label: "Email notifications" },
+  { value: "sms", label: "SMS notifications" },
+  { value: "push", label: "Push notifications" },
+];
+</script>
+```
+
+## Complete Examples
+
+### Survey Form
+
+<div class="component-demo">
+
+<RadioGroupDemo />
+
+</div>
+
+```vue
+<template>
+  <div>
+    <h3>How satisfied are you?</h3>
+    <BvRadio v-model="rating" :items="ratingItems">
+      <template #item="{ item }">{{ item.label }}</template>
+    </BvRadio>
+  </div>
+</template>
+
+<script setup>
+import { ref } from "vue";
+import { BvRadio } from "@baklavue/ui";
+
+const rating = ref("5");
+const ratingItems = [
+  { value: "5", label: "Very satisfied" },
+  { value: "4", label: "Satisfied" },
+  { value: "3", label: "Neutral" },
+  { value: "2", label: "Dissatisfied" },
+  { value: "1", label: "Very dissatisfied" },
+];
+</script>
+```
+
+## Props
+
+| Prop         | Type               | Default     | Description                                                         |
+| ------------ | ------------------ | ----------- | ------------------------------------------------------------------- |
+| `modelValue` | `string \| number` | `undefined` | Selected value (use v-model for two-way binding)                    |
+| `items`      | `RadioItem[]`      | `undefined` | Array of radio items. Each item renders as a bl-radio element       |
+| `label`      | `string`           | `undefined` | Label for the radio group (bl-radio-group label attribute)           |
+| `required`   | `boolean`          | `undefined` | Whether the radio group is required (for form validation)            |
+
+### RadioItem Interface
+
+When using the `items` prop, each item should follow the `RadioItem` interface:
+
+| Property   | Type               | Default     | Description                               |
+| ---------- | ------------------ | ----------- | ----------------------------------------- |
+| `value`    | `string \| number` | required    | The value of the radio (for v-model)      |
+| `label`    | `string`           | `undefined` | Label text displayed next to the radio    |
+| `disabled` | `boolean`          | `false`     | Whether the radio is disabled             |
+| `name`     | `string`           | `undefined` | Name attribute for the radio             |
+
+Items may include additional custom data for use in the `#item` slot.
+
+## Events
+
+| Event               | Payload               | Description                                  |
+| ------------------- | --------------------- | -------------------------------------------- |
+| `update:modelValue` | `string \| number`    | Emitted when selection changes (for v-model) |
+| `change`            | `CustomEvent`         | Emitted when the selection changes           |
+
+## Slots
+
+| Slot   | Props             | Description                                            |
+| ------ | ----------------- | ------------------------------------------------------ |
+| `item` | `{ item, index }` | Scoped slot for each radio item content                |
+
+## Types
+
+```typescript
+import type { RadioProps, RadioItem } from "@baklavue/ui";
+
+interface RadioItem {
+  value: string | number;
+  label?: string;
+  disabled?: boolean;
+  name?: string;
+  [key: string]: unknown; // Additional custom data for #item slot
+}
+
+interface RadioProps {
+  modelValue?: string | number;
+  items?: RadioItem[];
+  label?: string;
+  required?: boolean;
+}
+
+// Events
+interface RadioEmits {
+  "update:modelValue": [value: string | number];
+  change: [event: CustomEvent];
+}
+```
+
+## Usage Notes
+
+- **Items Prop**: Radios are rendered from the `items` prop. Content for each item is provided via the `#item` scoped slot or defaults to `item.label`.
+
+- **v-model Behavior**: v-model binds the selected value (string or number).
+
+- **Accessibility**: The component follows Baklava's accessibility guidelines and includes proper ARIA attributes for screen readers.
+
+- **Styling**: The component uses Baklava's default styling. Custom styling can be applied via CSS variables such as `--bl-radio-align-items` (default: center) and `--bl-radio-direction` (row|column) for layout.

package/dist/docs/components/scroll-to-top.md

@@ -0,0 +1,90 @@
+# ScrollToTop
+
+A floating button that appears when the user scrolls past a threshold. Clicking it scrolls smoothly to the top of the page.
+
+## Basic Usage
+
+<div class="component-demo">
+
+<ScrollToTopBasicDemo />
+
+</div>
+
+```vue
+<template>
+  <BvScrollToTop />
+</template>
+
+<script setup>
+import { BvScrollToTop } from "@baklavue/ui";
+</script>
+```
+
+## Position
+
+Control the fixed position of the button using the `position` prop.
+
+```vue
+<template>
+  <BvScrollToTop position="bottom-left" />
+  <BvScrollToTop position="bottom-right" />
+  <BvScrollToTop position="top-left" />
+  <BvScrollToTop position="top-right" />
+</template>
+
+<script setup>
+import { BvScrollToTop } from "@baklavue/ui";
+</script>
+```
+
+## Custom Threshold
+
+Set the scroll threshold in pixels. The button becomes visible when the user scrolls past this value.
+
+```vue
+<template>
+  <BvScrollToTop :threshold="500" />
+</template>
+
+<script setup>
+import { BvScrollToTop } from "@baklavue/ui";
+</script>
+```
+
+## Props
+
+| Prop       | Type                | Default         | Description                                                |
+| ---------- | ------------------- | --------------- | ---------------------------------------------------------- |
+| `threshold` | `number`            | `300`           | Scroll threshold in pixels before button appears           |
+| `position`  | `ScrollToTopPosition` | `"bottom-right"` | Fixed position (bottom-right, bottom-left, top-right, top-left) |
+| `label`     | `string`            | `"Scroll to top"` | Accessible label for screen readers                      |
+| `size`      | `ButtonSize`        | `"medium"`      | Button size                                                |
+| `variant`   | `ButtonVariant`     | `"primary"`     | Button variant                                             |
+
+## Events
+
+| Event   | Payload | Description                 |
+| ------- | ------- | --------------------------- |
+| `click` | -       | Emitted when button is clicked |
+
+## Types
+
+```typescript
+import type { ScrollToTopProps, ScrollToTopPosition } from "@baklavue/ui";
+
+type ScrollToTopPosition = "bottom-right" | "bottom-left" | "top-right" | "top-left";
+
+interface ScrollToTopProps {
+  threshold?: number;
+  position?: ScrollToTopPosition;
+  label?: string;
+  size?: ButtonSize;
+  variant?: ButtonVariant;
+}
+```
+
+## Usage Notes
+
+- **Accessibility**: The component includes `role="complementary"` and `aria-label` for screen readers. The `label` prop is passed to the underlying button for additional context.
+- **Window scroll**: The button listens to `window.scrollY` and scrolls the window. For scrollable containers (e.g. `overflow: auto`), consider a custom implementation.
+- **Z-index**: The button uses `z-index: 1000` to stay above most content. Override via CSS if needed.