@baklavue/mcp 1.0.0

package/dist/docs/composables/clipboard.md

@@ -0,0 +1,108 @@
+# useClipboard
+
+A composable for copying text to the clipboard. Integrates well with `useNotification` for copy feedback.
+
+## Basic Usage
+
+```vue
+<template>
+  <BvButton @click="handleCopy">Copy token</BvButton>
+</template>
+
+<script setup>
+import { BvButton } from "@baklavue/ui";
+import { useClipboard, useNotification } from "@baklavue/composables";
+
+const { copy, copied } = useClipboard();
+const { success } = useNotification();
+
+const handleCopy = async () => {
+  const ok = await copy("secret-token-123");
+  if (ok) {
+    success({ description: "Copied to clipboard!" });
+  }
+};
+</script>
+```
+
+## With Copied State
+
+```vue
+<template>
+  <BvButton @click="copy(text)">
+    {{ copied ? "Copied!" : "Copy" }}
+  </BvButton>
+</template>
+
+<script setup>
+import { BvButton } from "@baklavue/ui";
+import { useClipboard } from "@baklavue/composables";
+
+const text = ref("https://example.com/link");
+const { copy, copied } = useClipboard();
+</script>
+```
+
+## With Options
+
+```vue
+<template>
+  <BvButton v-if="isSupported" @click="copy()">
+    {{ copied ? "Copied!" : "Copy" }}
+  </BvButton>
+  <p v-else>Clipboard not supported</p>
+</template>
+
+<script setup>
+import { BvButton } from "@baklavue/ui";
+import { useClipboard } from "@baklavue/composables";
+
+const link = ref("https://example.com/share");
+const { copy, copied, isSupported } = useClipboard({
+  source: link,
+  copiedDuring: 1500,
+  legacy: true,
+});
+</script>
+```
+
+## API
+
+### Options
+
+| Option         | Type               | Default | Description                                                                      |
+| -------------- | ------------------ | ------- | -------------------------------------------------------------------------------- |
+| `source`       | `MaybeRef<string>` | —       | Default text to copy when `copy()` is called without arguments                   |
+| `copiedDuring` | `number`           | —       | Milliseconds before `copied` resets to `false`. Omit to disable auto-reset.      |
+| `legacy`       | `boolean`          | `false` | Fallback to `document.execCommand` when Clipboard API is unavailable (e.g. HTTP) |
+
+### Return Value
+
+| Property      | Type                                  | Description                                                       |
+| ------------- | ------------------------------------- | ----------------------------------------------------------------- |
+| `copy`        | `(text?: string) => Promise<boolean>` | Copies text to clipboard. Uses `source` when called without args. |
+| `copied`      | `Ref<boolean>`                        | True after successful copy                                        |
+| `isSupported` | `ComputedRef<boolean>`                | Whether clipboard is available (native or legacy when enabled)    |
+
+### Notes
+
+- Uses `navigator.clipboard.writeText()` when available
+- Returns `false` in environments without clipboard API (e.g. non-HTTPS) unless `legacy: true`
+- `copied` resets to `false` on each `copy()` call; with `copiedDuring`, it auto-resets after the specified ms
+- When `source` is provided, `copy()` can be called without arguments
+
+## TypeScript Support
+
+```typescript
+import { useClipboard, type UseClipboardOptions } from "@baklavue/composables";
+
+const { copy, copied, isSupported } = useClipboard();
+const ok = await copy("hello");
+
+const { copy: copyFromSource } = useClipboard({
+  source: ref("default"),
+  copiedDuring: 1500,
+  legacy: true,
+});
+await copyFromSource(); // copies "default"
+```

package/dist/docs/composables/colorScheme.md

@@ -0,0 +1,110 @@
+# useColorScheme
+
+A composable for light/dark/system color scheme with persistence. Supports `prefers-color-scheme` for system preference, optional attribute on document, and localStorage persistence.
+
+## Basic Usage
+
+```vue
+<template>
+  <BvButton @click="toggleScheme">
+    {{ isDark ? "Light" : "Dark" }} mode
+  </BvButton>
+</template>
+
+<script setup>
+import { BvButton } from "@baklavue/ui";
+import { useColorScheme } from "@baklavue/composables";
+
+const { scheme, isDark, setScheme } = useColorScheme();
+
+function toggleScheme() {
+  setScheme(isDark.value ? "light" : "dark");
+}
+</script>
+```
+
+## System Preference
+
+Use `"system"` to follow the OS preference:
+
+```vue
+<script setup>
+import { useColorScheme } from "@baklavue/composables";
+
+const { scheme, setScheme } = useColorScheme();
+
+// Follow system
+setScheme("system");
+</script>
+```
+
+## Options
+
+```vue
+<script setup>
+import { useColorScheme } from "@baklavue/composables";
+
+const { scheme, isDark, setScheme } = useColorScheme({
+  storageKey: "app-color-scheme",
+  attribute: "data-theme",
+  selector: "html",
+  defaultScheme: "system",
+});
+</script>
+```
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `storageKey` | `string \| false` | `"color-scheme"` | localStorage key. Set to `false` to disable persistence |
+| `attribute` | `"data-theme" \| "class"` | `"data-theme"` | Attribute to set on `document.documentElement` |
+| `selector` | `string` | `"html"` | Selector for the element to apply the attribute |
+| `defaultScheme` | `"light" \| "dark" \| "system"` | `"system"` | Default when no stored value exists |
+
+## With `attribute: "class"`
+
+When using `attribute: "class"`, the composable adds `dark` class for dark mode and removes it for light:
+
+```vue
+<script setup>
+import { useColorScheme } from "@baklavue/composables";
+
+useColorScheme({ attribute: "class" });
+</script>
+
+<template>
+  <div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
+    Content
+  </div>
+</template>
+```
+
+## API
+
+### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `scheme` | `Ref<"light" \| "dark" \| "system">` | Current scheme choice |
+| `isDark` | `Ref<boolean>` | `true` when dark mode is active |
+| `setScheme` | `(value: ColorScheme) => void` | Set scheme and persist |
+
+### ColorScheme
+
+```typescript
+type ColorScheme = "light" | "dark" | "system";
+```
+
+## TypeScript Support
+
+```typescript
+import {
+  useColorScheme,
+  type ColorScheme,
+  type UseColorSchemeOptions,
+} from "@baklavue/composables";
+
+const { scheme, isDark, setScheme } = useColorScheme({
+  storageKey: "my-app-theme",
+  defaultScheme: "system",
+});
+```

package/dist/docs/composables/confirmDialog.md

@@ -0,0 +1,105 @@
+# useConfirmDialog
+
+A composable for driving BvDialog confirm/cancel flows. Returns a promise that resolves to `true` when the user confirms, `false` when cancelled. Often used with `useNotification` for success/error feedback.
+
+## Basic Usage
+
+```vue
+<template>
+  <BvButton @click="handleDelete">Delete</BvButton>
+
+  <BvDialog v-model:open="isOpen" :caption="caption">
+    <p>{{ description }}</p>
+    <template #footer>
+      <BvButton variant="tertiary" @click="handleCancel">Cancel</BvButton>
+      <BvButton variant="primary" @click="handleConfirm">Confirm</BvButton>
+    </template>
+  </BvDialog>
+</template>
+
+<script setup>
+import { BvButton, BvDialog } from "@baklavue/ui";
+import { useConfirmDialog, useNotification } from "@baklavue/composables";
+
+const { success } = useNotification();
+const {
+  confirm,
+  isOpen,
+  caption,
+  description,
+  handleConfirm,
+  handleCancel,
+} = useConfirmDialog();
+
+const handleDelete = async () => {
+  const ok = await confirm({
+    caption: "Delete item?",
+    description: "Are you sure? This action cannot be undone.",
+  });
+  if (ok) {
+    // Perform delete
+    success({ description: "Deleted successfully" });
+  }
+};
+</script>
+```
+
+## With Async Action
+
+```vue
+<script setup>
+import { useConfirmDialog, useNotification } from "@baklavue/composables";
+
+const { success, error } = useNotification();
+const { confirm, isOpen, caption, description, handleConfirm, handleCancel, isPending } =
+  useConfirmDialog();
+
+const handleDelete = async () => {
+  const ok = await confirm({
+    caption: "Delete item?",
+    description: "This cannot be undone.",
+  });
+  if (ok) {
+    try {
+      await api.deleteItem(id);
+      success({ description: "Deleted" });
+    } catch (e) {
+      error({ description: e.message });
+    }
+  }
+};
+</script>
+```
+
+## API
+
+### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `confirm` | `(options?) => Promise<boolean>` | Opens dialog, returns promise |
+| `isOpen` | `Ref<boolean>` | Dialog visibility |
+| `caption` | `Ref<string>` | Dialog title |
+| `description` | `Ref<string>` | Dialog body text |
+| `isPending` | `Ref<boolean>` | True while dialog is open |
+| `handleConfirm` | `() => void` | Wire to Confirm button |
+| `handleCancel` | `() => void` | Wire to Cancel button |
+| `close` | `(result: boolean) => void` | Close with result |
+
+### Options
+
+```typescript
+interface ConfirmDialogOptions {
+  caption?: string;   // Dialog title
+  description?: string; // Dialog body
+}
+```
+
+## TypeScript Support
+
+```typescript
+import { useConfirmDialog, type ConfirmDialogOptions } from "@baklavue/composables";
+
+const { confirm } = useConfirmDialog();
+const ok = await confirm({ caption: "Confirm?", description: "Sure?" });
+```

package/dist/docs/composables/containerScroll.md

@@ -0,0 +1,89 @@
+# useContainerScroll
+
+A composable for reactive scroll position inside a scrollable container. Uses scroll event with RAF throttling. Useful for virtual lists, custom scroll UIs, and horizontal scroll indicators.
+
+## Basic Usage
+
+```vue
+<template>
+  <div ref="container" class="overflow-auto h-64">
+    <div class="p-4">Content</div>
+  </div>
+  <p>Scroll: {{ scrollTop }}px, {{ scrollLeft }}px</p>
+</template>
+
+<script setup>
+import { ref } from "vue";
+import { useContainerScroll } from "@baklavue/composables";
+
+const container = ref<HTMLElement | null>(null);
+const { scrollTop, scrollLeft } = useContainerScroll(container);
+</script>
+```
+
+## Scroll Shadow Indicator
+
+```vue
+<template>
+  <div class="relative">
+    <div
+      v-show="scrollLeft > 0"
+      class="absolute left-0 top-0 h-full w-8 bg-gradient-to-r from-white to-transparent"
+    />
+    <div ref="scroll" class="overflow-x-auto">
+      <div class="flex gap-4 p-4">...</div>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { ref } from "vue";
+import { useContainerScroll } from "@baklavue/composables";
+
+const scroll = ref<HTMLElement | null>(null);
+const { scrollLeft } = useContainerScroll(scroll);
+</script>
+```
+
+## Options
+
+```vue
+<script setup>
+import { useContainerScroll } from "@baklavue/composables";
+
+const container = ref<HTMLElement | null>(null);
+const { scrollTop, scrollLeft } = useContainerScroll(container, {
+  passive: true,
+});
+</script>
+```
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `passive` | `boolean` | `true` | Use passive scroll listener |
+
+## API
+
+### Parameters
+
+- `target` — `Ref<Element | null | undefined>` — Ref to the scrollable element
+- `options` — Optional `UseContainerScrollOptions`
+
+### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `scrollTop` | `Ref<number>` | Scroll position from top |
+| `scrollLeft` | `Ref<number>` | Scroll position from left |
+
+## TypeScript Support
+
+```typescript
+import {
+  useContainerScroll,
+  type UseContainerScrollOptions,
+} from "@baklavue/composables";
+
+const container = ref<HTMLElement | null>(null);
+const { scrollTop, scrollLeft } = useContainerScroll(container);
+```

package/dist/docs/composables/cookie.md

@@ -0,0 +1,137 @@
+# useCookie
+
+Reactive sync with `document.cookie`. Persists values in a cookie. Use for auth tokens, preferences that must be sent to the server, or when you need path/domain/expiry control. Cookies are sent with every request to matching paths.
+
+Returns `{ value, get, set, remove }` for reactive and imperative cookie access.
+
+## Basic usage
+
+```vue
+<script setup>
+import { useCookie } from "@baklavue/composables";
+
+const { value: token, get, set, remove } = useCookie("auth-token", "");
+const { value: theme } = useCookie("theme", "vue", { path: "/", maxAge: 60 * 60 * 24 * 365 });
+
+// Imperative API
+set("new-token");
+const current = get();  // read from cookie
+remove();              // clear cookie
+</script>
+```
+
+## Imperative API
+
+| Method | Description |
+| --- | --- |
+| `value` | Reactive ref for `v-model` and template binding |
+| `get()` | Read current value from cookie |
+| `set(value)` | Write value to cookie |
+| `remove()` | Delete cookie and reset to defaultValue |
+
+## Cookie options
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `path` | `string` | Cookie path. Default: `'/'` |
+| `domain` | `string` | Cookie domain |
+| `maxAge` | `number` | Max age in seconds. Takes precedence over `expires` |
+| `expires` | `Date` | Expiration date |
+| `secure` | `boolean` | HTTPS only |
+| `sameSite` | `'Strict' \| 'Lax' \| 'None'` | SameSite attribute |
+
+`useCookie` also supports `mergeDefaults`, `serializer`, and `onError`.
+
+## Options
+
+```typescript
+interface UseCookieOptions<T> {
+  mergeDefaults?: boolean | ((storageValue: T, defaults: T) => T);
+  serializer?: { read: (raw: string) => T; write: (value: T) => string };
+  onError?: (error: unknown) => void;
+  path?: string;
+  domain?: string;
+  maxAge?: number;
+  expires?: Date;
+  secure?: boolean;
+  sameSite?: "Strict" | "Lax" | "None";
+}
+```
+
+### mergeDefaults
+
+When you add new properties to your default object, existing stored values won't have them. Enable `mergeDefaults: true` for a shallow merge:
+
+```typescript
+import { useCookie } from "@baklavue/composables";
+
+const { value: prefs } = useCookie("prefs", { theme: "vue", compact: false }, {
+  mergeDefaults: true,
+  path: "/",
+});
+```
+
+### Custom serializer
+
+Store `Map`, `Set`, `Date`, or custom formats:
+
+```typescript
+import { useCookie } from "@baklavue/composables";
+
+const { value: lastVisit } = useCookie("last-visit", new Date(), {
+  serializer: {
+    read: (v) => new Date(v),
+    write: (v) => v.toISOString(),
+  },
+  path: "/",
+});
+```
+
+### onError
+
+Handle parse errors:
+
+```typescript
+const { value: prefs } = useCookie("prefs", {}, {
+  onError: (e) => console.error("Cookie error:", e),
+  path: "/",
+});
+```
+
+## API
+
+```typescript
+useCookie<T>(key: string, defaultValue: T): UseCookieReturn<T>
+useCookie<T>(key: string, defaultValue: T, options: UseCookieOptions<T>): UseCookieReturn<T>
+```
+
+```typescript
+interface UseCookieReturn<T> {
+  value: Ref<T>;
+  get: () => T;
+  set: (value: T) => void;
+  remove: () => void;
+}
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `key` | `string` | Cookie name |
+| `defaultValue` | `T` | Default when cookie is missing or on SSR |
+| `options` | `UseCookieOptions<T>` | Optional: mergeDefaults, serializer, onError, path, domain, maxAge, expires, secure, sameSite |
+
+### Notes
+
+- Values are JSON-serialized by default. Primitives, objects, and arrays are supported.
+- On SSR, returns `defaultValue` (cookies are not available).
+- Changes to the ref are written to the cookie (with `{ deep: true }` for objects).
+- Cookies have a ~4KB size limit per cookie.
+
+## TypeScript Support
+
+```typescript
+import { useCookie, type UseCookieOptions, type UseCookieReturn } from "@baklavue/composables";
+
+const { value: token, set, remove } = useCookie("auth-token", "");
+const { value: theme } = useCookie("theme", "vue", { path: "/", maxAge: 31536000 });
+```

package/dist/docs/composables/debounce.md

@@ -0,0 +1,69 @@
+# useDebounceFn / useDebouncedRef
+
+Debounce function execution or ref value. Useful for search inputs, autocomplete, and form validation.
+
+## Basic Usage
+
+### useDebounceFn
+
+Returns a debounced version of a function. The function is called only after the specified delay has passed since the last invocation.
+
+```vue
+<template>
+  <BvInput v-model="searchQuery" placeholder="Search..." />
+</template>
+
+<script setup>
+import { ref, watch } from "vue";
+import { BvInput } from "@baklavue/ui";
+import { useDebounceFn } from "@baklavue/composables";
+
+const searchQuery = ref("");
+
+const debouncedSearch = useDebounceFn((query) => {
+  if (query) fetchResults(query);
+}, 300);
+
+watch(searchQuery, (q) => debouncedSearch(q));
+</script>
+```
+
+### useDebouncedRef
+
+Returns a ref that updates only after the specified delay since the last change. Useful for debounced v-model.
+
+```vue
+<script setup>
+import { ref, watch } from "vue";
+import { useDebouncedRef } from "@baklavue/composables";
+
+const searchQuery = ref("");
+const debouncedQuery = useDebouncedRef(searchQuery, 300);
+
+watch(debouncedQuery, (q) => {
+  if (q) fetchResults(q);
+});
+</script>
+```
+
+## API
+
+### useDebounceFn
+
+```typescript
+useDebounceFn<T>(fn: T, delay?: number): (...args: Parameters<T>) => void
+```
+
+- `fn` — Function to debounce
+- `delay` — Delay in milliseconds. Default: 200
+- Returns a debounced function
+
+### useDebouncedRef
+
+```typescript
+useDebouncedRef<T>(value: Ref<T>, delay?: number): Ref<T>
+```
+
+- `value` — Ref to debounce
+- `delay` — Delay in milliseconds. Default: 200
+- Returns a ref with debounced value

package/dist/docs/composables/disclosure.md

@@ -0,0 +1,69 @@
+# useDisclosure
+
+A minimal composable for open/close state used by Dialog, Drawer, Dropdown, Accordion, and Tooltip. Avoids repetitive `ref(false)`, `open()`, `close()`, `toggle()`.
+
+## Basic Usage
+
+```vue
+<template>
+  <BvButton @click="open">Open Dialog</BvButton>
+  <BvDialog v-model:open="isOpen" caption="Dialog Title">
+    <p>Content goes here.</p>
+    <template #footer>
+      <BvButton @click="close">Close</BvButton>
+    </template>
+  </BvDialog>
+</template>
+
+<script setup>
+import { BvButton, BvDialog } from "@baklavue/ui";
+import { useDisclosure } from "@baklavue/composables";
+
+const { isOpen, open, close, toggle } = useDisclosure(false);
+</script>
+```
+
+## With Toggle
+
+```vue
+<template>
+  <BvButton @click="toggle">Toggle Drawer</BvButton>
+  <BvDrawer v-model:open="isOpen" caption="Drawer">
+    <p>Drawer content.</p>
+  </BvDrawer>
+</template>
+
+<script setup>
+import { BvButton, BvDrawer } from "@baklavue/ui";
+import { useDisclosure } from "@baklavue/composables";
+
+const { isOpen, toggle } = useDisclosure(false);
+</script>
+```
+
+## API
+
+### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `isOpen` | `Ref<boolean>` | Reactive open state |
+| `open` | `() => void` | Sets isOpen to true |
+| `close` | `() => void` | Sets isOpen to false |
+| `toggle` | `() => void` | Flips isOpen |
+
+### Parameters
+
+```typescript
+useDisclosure(initialState?: boolean)
+```
+
+- `initialState` — Initial open state. Default: `false`
+
+## TypeScript Support
+
+```typescript
+import { useDisclosure } from "@baklavue/composables";
+
+const { isOpen, open, close, toggle } = useDisclosure(true);
+```