@baklavue/mcp 1.0.0

package/dist/docs/composables/sticky.md

@@ -0,0 +1,91 @@
+# useSticky
+
+A composable to detect when a sticky element is "stuck" at the top of the viewport. Uses scroll position and `getBoundingClientRect`. The target should have `position: sticky` and `top: 0` (or similar).
+
+## Basic Usage
+
+```vue
+<template>
+  <header
+    ref="header"
+    class="sticky top-0 transition-shadow"
+    :class="{ 'shadow-md': isSticky }"
+  >
+    Header
+  </header>
+</template>
+
+<script setup>
+import { ref } from "vue";
+import { useSticky } from "@baklavue/composables";
+
+const header = ref<HTMLElement | null>(null);
+const { isSticky } = useSticky(header);
+</script>
+```
+
+## With Custom Scroll Container
+
+```vue
+<template>
+  <div ref="scrollContainer" class="overflow-auto h-64">
+    <div ref="stickyHeader" class="sticky top-0">Sticky header</div>
+    <div>Content</div>
+  </div>
+</template>
+
+<script setup>
+import { ref } from "vue";
+import { useSticky } from "@baklavue/composables";
+
+const stickyHeader = ref<HTMLElement | null>(null);
+const scrollContainer = ref<HTMLElement | null>(null);
+const { isSticky } = useSticky(stickyHeader, {
+  scrollTarget: scrollContainer,
+});
+</script>
+```
+
+## Options
+
+```vue
+<script setup>
+import { useSticky } from "@baklavue/composables";
+
+const header = ref<HTMLElement | null>(null);
+const { isSticky } = useSticky(header, {
+  threshold: 0,
+  scrollTarget: undefined,
+});
+</script>
+```
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `threshold` | `number` | `0` | Pixels. `isSticky` is true when element top is at or above this |
+| `scrollTarget` | `Ref<Element \| null \| undefined>` | `undefined` | Scroll container. Default: window |
+
+## API
+
+### Parameters
+
+- `target` — `Ref<Element | null | undefined>` — Ref to the sticky element
+- `options` — Optional `UseStickyOptions`
+
+### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `isSticky` | `Ref<boolean>` | `true` when element is stuck |
+
+## TypeScript Support
+
+```typescript
+import {
+  useSticky,
+  type UseStickyOptions,
+} from "@baklavue/composables";
+
+const header = ref<HTMLElement | null>(null);
+const { isSticky } = useSticky(header, { threshold: 0 });
+```

package/dist/docs/composables/storage.md

@@ -0,0 +1,193 @@
+# useLocalStorage / useSessionStorage
+
+Reactive sync with `localStorage` and `sessionStorage`. Persist user preferences like theme, table page size, or form drafts across sessions (localStorage) or within the current tab (sessionStorage).
+
+## useLocalStorage
+
+Persists across browser sessions. Use for theme, page size, sidebar state, etc.
+
+```vue
+<template>
+  <BvSelect v-model="pageSize" :options="pageSizeOptions" />
+</template>
+
+<script setup>
+import { BvSelect } from "@baklavue/ui";
+import { useLocalStorage } from "@baklavue/composables";
+
+const pageSize = useLocalStorage("table-page-size", 10);
+const pageSizeOptions = [
+  { value: 10, text: "10" },
+  { value: 25, text: "25" },
+  { value: 50, text: "50" },
+];
+</script>
+```
+
+## useSessionStorage
+
+Persists only for the current tab/session. Use for form drafts, temporary filters, etc.
+
+```vue
+<script setup>
+import { useSessionStorage } from "@baklavue/composables";
+
+const draft = useSessionStorage("form-draft", null);
+</script>
+```
+
+## With useBaklavaTheme
+
+```vue
+<script setup>
+import { useBaklavaTheme, useLocalStorage } from "@baklavue/composables";
+
+const themePreset = useLocalStorage("theme-preset", "vue");
+const { applyTheme } = useBaklavaTheme();
+
+watch(themePreset, (preset) => applyTheme({ preset }), { immediate: true });
+</script>
+```
+
+## With usePagination
+
+```vue
+<script setup>
+import { usePagination, useLocalStorage } from "@baklavue/composables";
+
+const savedPageSize = useLocalStorage("pagination-page-size", 10);
+const { currentPage, pageSize, totalItems, slice } = usePagination({
+  pageSize: savedPageSize.value,
+});
+
+watch(pageSize, (size) => (savedPageSize.value = size));
+</script>
+```
+
+## Options
+
+`useLocalStorage` and `useSessionStorage` accept an optional third parameter.
+
+```typescript
+interface UseStorageOptions<T> {
+  /** Merge default with stored value when both are objects. Default: false */
+  mergeDefaults?: boolean | ((storageValue: T, defaults: T) => T);
+  /** Listen to storage events for cross-tab sync. Default: true for localStorage, false for sessionStorage */
+  listenToStorageChanges?: boolean;
+  /** Custom serializer. Default: JSON */
+  serializer?: { read: (raw: string) => T; write: (value: T) => string };
+  /** Error callback. Default: silent */
+  onError?: (error: unknown) => void;
+}
+```
+
+### mergeDefaults
+
+When you add new properties to your default object, existing stored values won't have them. Enable `mergeDefaults: true` for a shallow merge:
+
+```vue
+<script setup>
+import { useLocalStorage } from "@baklavue/composables";
+
+// If storage has { theme: "vue" } but default adds compact, merged result includes both
+const prefs = useLocalStorage("prefs", { theme: "vue", compact: false }, {
+  mergeDefaults: true,
+});
+</script>
+```
+
+Or pass a custom merge function for deep merge:
+
+```typescript
+import { useLocalStorage } from "@baklavue/composables";
+
+const prefs = useLocalStorage("prefs", defaultPrefs, {
+  mergeDefaults: (stored, defaults) => ({ ...defaults, ...stored }),
+});
+```
+
+### listenToStorageChanges
+
+Changes in other tabs update the ref automatically. Enabled by default for `useLocalStorage`; disabled for `useSessionStorage` (sessionStorage is tab-scoped).
+
+### Custom serializer
+
+Store `Map`, `Set`, `Date`, or custom formats:
+
+```typescript
+import { useLocalStorage } from "@baklavue/composables";
+
+const count = useLocalStorage("count", 0, {
+  serializer: {
+    read: (v) => parseFloat(v) || 0,
+    write: (v) => String(v),
+  },
+});
+
+const lastVisit = useLocalStorage("last-visit", new Date(), {
+  serializer: {
+    read: (v) => new Date(v),
+    write: (v) => v.toISOString(),
+  },
+});
+```
+
+### onError
+
+Handle quota exceeded or parse errors:
+
+```typescript
+const prefs = useLocalStorage("prefs", {}, {
+  onError: (e) => console.error("Storage error:", e),
+});
+```
+
+## API
+
+### useLocalStorage
+
+```typescript
+useLocalStorage<T>(key: string, defaultValue: T): Ref<T>
+useLocalStorage<T>(key: string, defaultValue: T, options: UseStorageOptions<T>): Ref<T>
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `key` | `string` | Storage key |
+| `defaultValue` | `T` | Default when key is missing or on SSR |
+| `options` | `UseStorageOptions<T>` | Optional: mergeDefaults, listenToStorageChanges, serializer, onError |
+
+### useSessionStorage
+
+```typescript
+useSessionStorage<T>(key: string, defaultValue: T): Ref<T>
+useSessionStorage<T>(key: string, defaultValue: T, options: UseStorageOptions<T>): Ref<T>
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `key` | `string` | Storage key |
+| `defaultValue` | `T` | Default when key is missing or on SSR |
+| `options` | `UseStorageOptions<T>` | Optional: mergeDefaults, listenToStorageChanges, serializer, onError |
+
+### Notes
+
+- Values are JSON-serialized by default. Primitives, objects, and arrays are supported.
+- On SSR, returns `defaultValue` (storage is not available).
+- Changes to the ref are written to storage (with `{ deep: true }` for objects).
+- Cross-tab sync is enabled for `useLocalStorage` by default.
+
+## TypeScript Support
+
+```typescript
+import { useLocalStorage, useSessionStorage, type UseStorageOptions } from "@baklavue/composables";
+
+const pageSize = useLocalStorage<number>("page-size", 10);
+const prefs = useLocalStorage("prefs", { theme: "vue", compact: false });
+const draft = useSessionStorage<string | null>("draft", null);
+
+// With options
+const prefsWithMerge = useLocalStorage("prefs", { theme: "vue", compact: false }, {
+  mergeDefaults: true,
+});
+```

package/dist/docs/composables/theme.md

@@ -0,0 +1,252 @@
+# useBaklavaTheme
+
+A composable for overwriting Baklava design system tokens. Use the Vue preset, pass your own preset object, or override specific colors, border radius, size/spacing, typography, and z-index.
+
+## Basic Usage
+
+### Vue Preset
+
+Apply Vue.js brand colors (Mint #41B883, Police Blue #34495E) to Baklava components:
+
+```vue
+<script setup>
+import { useBaklavaTheme } from "@baklavue/composables";
+
+useBaklavaTheme().applyTheme({ preset: "vue" });
+</script>
+
+<template>
+  <BvButton variant="primary">Primary Button</BvButton>
+</template>
+```
+
+### Custom Preset
+
+Pass your own preset object mapping CSS variable names to values:
+
+```vue
+<script setup>
+import { useBaklavaTheme } from "@baklavue/composables";
+
+useBaklavaTheme().applyTheme({
+  preset: {
+    "--bl-color-primary": "#ea4c89",
+    "--bl-color-primary-highlight": "#d6427a",
+    "--bl-color-primary-contrast": "#fce8ee",
+  },
+});
+</script>
+```
+
+### Custom Colors
+
+Override specific Baklava color tokens:
+
+```vue
+<script setup>
+import { useBaklavaTheme } from "@baklavue/composables";
+
+useBaklavaTheme().applyTheme({
+  colors: {
+    primary: "#41B883",
+    primaryHighlight: "#3aa876",
+    primaryContrast: "#e7f9ef",
+  },
+});
+</script>
+```
+
+### Border Radius
+
+Override border radius tokens:
+
+```vue
+<script setup>
+import { useBaklavaTheme } from "@baklavue/composables";
+
+useBaklavaTheme().applyTheme({
+  borderRadius: {
+    s: "0.5rem",
+    m: "0.75rem",
+    l: "1rem",
+  },
+});
+</script>
+```
+
+### Size & Spacing
+
+Override size and spacing tokens:
+
+```vue
+<script setup>
+import { useBaklavaTheme } from "@baklavue/composables";
+
+useBaklavaTheme().applyTheme({
+  size: {
+    s: "0.875rem",
+    m: "1rem",
+    l: "1.25rem",
+  },
+});
+</script>
+```
+
+### Typography
+
+Override typography tokens:
+
+```vue
+<script setup>
+import { useBaklavaTheme } from "@baklavue/composables";
+
+useBaklavaTheme().applyTheme({
+  typography: {
+    fontFamily: "'Inter', sans-serif",
+    fontSize: { s: "0.75rem", m: "0.875rem", l: "1rem" },
+  },
+});
+</script>
+```
+
+### With VitePress or App Setup
+
+Call `applyTheme` when your app mounts (e.g. in `main.ts` or VitePress `enhanceApp`):
+
+```ts
+import { createApp } from "vue";
+import App from "./App.vue";
+import { useBaklavaTheme } from "@baklavue/composables";
+
+const app = createApp(App);
+useBaklavaTheme().applyTheme({ preset: "vue" });
+app.mount("#app");
+```
+
+## API
+
+### applyTheme
+
+Applies theme overrides by injecting CSS variables into the document.
+
+```typescript
+applyTheme(options?: ApplyThemeOptions): void
+```
+
+### ApplyThemeOptions
+
+```typescript
+interface ApplyThemeOptions {
+  preset?: "vue" | "default" | BaklavaThemePresetRecord;
+  colors?: Partial<BaklavaThemeColors>;
+  borderRadius?: Partial<BaklavaThemeBorderRadius>;
+  size?: Partial<BaklavaThemeSize>;
+  typography?: Partial<BaklavaThemeTypography>;
+  zIndex?: Partial<BaklavaThemeZIndex>;
+}
+
+// Custom preset: map of CSS variable names to values
+type BaklavaThemePresetRecord = Record<string, string>;
+```
+
+### BaklavaThemeColors
+
+Custom color keys map to Baklava's `--bl-color-*` CSS variables:
+
+| Key                                                    | Baklava Variable               |
+| ------------------------------------------------------ | ------------------------------ |
+| `primary`                                              | `--bl-color-primary`           |
+| `primaryHighlight`                                     | `--bl-color-primary-highlight` |
+| `primaryContrast`                                      | `--bl-color-primary-contrast`  |
+| `success`, `successHighlight`, `successContrast`       | `--bl-color-success-*`         |
+| `danger`, `warning`, `info`                            | `--bl-color-{semantic}-*`      |
+| `neutralDarkest`, `neutralDarker`, `neutralDark`, etc. | `--bl-color-neutral-*`         |
+
+### BaklavaThemeBorderRadius
+
+| Key      | Baklava Variable            |
+| -------- | --------------------------- |
+| `xs`     | `--bl-border-radius-xs`     |
+| `s`      | `--bl-border-radius-s`      |
+| `m`      | `--bl-border-radius-m`      |
+| `l`      | `--bl-border-radius-l`      |
+| `pill`   | `--bl-border-radius-pill`   |
+| `circle` | `--bl-border-radius-circle` |
+
+### BaklavaThemeSize
+
+| Key         | Baklava Variable                        |
+| ----------- | --------------------------------------- |
+| `4xs`–`6xl` | `--bl-size-4xs` through `--bl-size-6xl` |
+
+### BaklavaThemeTypography
+
+| Key          | Baklava Variable         |
+| ------------ | ------------------------ |
+| `fontFamily` | `--bl-font-family`       |
+| `fontSize`   | `--bl-font-size-{key}`   |
+| `fontWeight` | `--bl-font-weight-{key}` |
+
+### BaklavaThemeZIndex
+
+| Key            | Baklava Variable          |
+| -------------- | ------------------------- |
+| `deep`         | `--bl-index-deep`         |
+| `base`         | `--bl-index-base`         |
+| `popover`      | `--bl-index-popover`      |
+| `tooltip`      | `--bl-index-tooltip`      |
+| `sticky`       | `--bl-index-sticky`       |
+| `overlay`      | `--bl-index-overlay`      |
+| `dialog`       | `--bl-index-dialog`       |
+| `notification` | `--bl-index-notification` |
+
+## Vue Preset Colors
+
+The `vue` preset applies:
+
+- **Primary**: #41B883 (Vue Mint)
+- **Primary Highlight**: #3aa876 (darker mint)
+- **Primary Contrast**: #e7f9ef (light mint background)
+- **Success**: Same as primary (Vue green)
+- **Neutral Darker**: #34495E (Police Blue)
+- **Neutral Darkest**: #2c3e50
+
+## Design Tokens Reference
+
+For a full reference of all Baklava design tokens with live preview examples, see [Design Tokens](/guide/design-tokens).
+
+## TypeScript Support
+
+```typescript
+import {
+  useBaklavaTheme,
+  type ApplyThemeOptions,
+  type BaklavaThemeBorderRadius,
+  type BaklavaThemeColors,
+  type BaklavaThemePreset,
+  type BaklavaThemePresetRecord,
+  type BaklavaThemeSize,
+  type BaklavaThemeTypography,
+  type BaklavaThemeZIndex,
+} from "@baklavue/composables";
+
+const { applyTheme } = useBaklavaTheme();
+
+// Built-in preset
+applyTheme({ preset: "vue" });
+
+// Custom preset
+applyTheme({
+  preset: {
+    "--bl-color-primary": "#ea4c89",
+    "--bl-color-primary-highlight": "#d6427a",
+  },
+});
+
+// Full customization
+applyTheme({
+  colors: { primary: "#41B883" },
+  borderRadius: { m: "0.5rem" },
+  size: { m: "1rem" },
+});
+```

package/dist/docs/composables/themePreset.md

@@ -0,0 +1,62 @@
+# useThemePreset
+
+A composable to persist and apply Baklava theme preset across sessions. Combines `useBaklavaTheme` and `useLocalStorage`. Re-applies theme when preset changes.
+
+## Basic Usage
+
+```vue
+<template>
+  <BvSelect v-model="preset" :options="presetOptions" />
+</template>
+
+<script setup>
+import { BvSelect } from "@baklavue/ui";
+import { useThemePreset } from "@baklavue/composables";
+
+const { preset, setPreset, applyTheme } = useThemePreset();
+
+const presetOptions = [
+  { value: "vue", text: "Vue" },
+  { value: "default", text: "Default" },
+];
+</script>
+```
+
+## Options
+
+```vue
+<script setup>
+import { useThemePreset } from "@baklavue/composables";
+
+const { preset, setPreset, applyTheme } = useThemePreset({
+  storageKey: "theme-preset",
+  defaultPreset: "vue",
+});
+</script>
+```
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `storageKey` | `string` | `"theme-preset"` | localStorage key |
+| `defaultPreset` | `"vue" \| "default"` | `"vue"` | Default when no stored value exists |
+
+## API
+
+### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `preset` | `Ref<BaklavaThemePreset>` | Current preset (persisted) |
+| `setPreset` | `(value: BaklavaThemePreset) => void` | Set preset and re-apply |
+| `applyTheme` | `() => void` | Manually re-apply current preset |
+
+## TypeScript Support
+
+```typescript
+import {
+  useThemePreset,
+  type UseThemePresetOptions,
+} from "@baklavue/composables";
+
+const { preset, setPreset } = useThemePreset({ defaultPreset: "default" });
+```

package/dist/docs/composables/throttle.md

@@ -0,0 +1,76 @@
+# useThrottleFn / useThrottledRef
+
+Throttle function execution or ref value. Useful for scroll, resize, and mousemove handlers.
+
+## Basic Usage
+
+### useThrottleFn
+
+Returns a throttled version of a function. The function is called at most once per specified interval.
+
+```vue
+<script setup>
+import { onMounted, onUnmounted } from "vue";
+import { useThrottleFn } from "@baklavue/composables";
+
+const throttledScroll = useThrottleFn(() => {
+  updateScrollPosition();
+}, 100);
+
+onMounted(() => {
+  window.addEventListener("scroll", throttledScroll);
+});
+
+onUnmounted(() => {
+  window.removeEventListener("scroll", throttledScroll);
+});
+</script>
+```
+
+### useThrottledRef
+
+Returns a ref that updates at most once per specified interval.
+
+```vue
+<script setup>
+import { ref, onMounted } from "vue";
+import { useThrottledRef } from "@baklavue/composables";
+
+const scrollY = ref(0);
+const throttledScrollY = useThrottledRef(scrollY, 100);
+
+onMounted(() => {
+  window.addEventListener("scroll", () => {
+    scrollY.value = window.scrollY;
+  });
+});
+</script>
+```
+
+## API
+
+### useThrottleFn
+
+```typescript
+useThrottleFn<T>(
+  fn: T,
+  delay?: number,
+  options?: { leading?: boolean; trailing?: boolean }
+): (...args: Parameters<T>) => void
+```
+
+- `fn` — Function to throttle
+- `delay` — Minimum interval in milliseconds. Default: 200
+- `options.leading` — Call on leading edge. Default: true
+- `options.trailing` — Call on trailing edge. Default: true
+- Returns a throttled function
+
+### useThrottledRef
+
+```typescript
+useThrottledRef<T>(value: Ref<T>, delay?: number): Ref<T>
+```
+
+- `value` — Ref to throttle
+- `delay` — Minimum interval in milliseconds. Default: 200
+- Returns a ref with throttled value