@baklavue/mcp 1.0.0

package/dist/docs/composables/polling.md

@@ -0,0 +1,76 @@
+# usePolling
+
+Composable for polling with fetch state. Combines `useAsyncState` with `useIntervalFn` for non-query polling scenarios (e.g. when you don't need `useQuery` caching).
+
+## Basic Usage
+
+```vue
+<script setup>
+import { usePolling } from "@baklavue/composables";
+
+const { data, isLoading, pause, resume } = usePolling(
+  () => fetch("/api/status").then((r) => r.json()),
+  { interval: 5000 }
+);
+</script>
+
+<template>
+  <div>
+    <div v-if="data">Status: {{ data.status }}</div>
+    <button @click="pause">Pause</button>
+    <button @click="resume">Resume</button>
+  </div>
+</template>
+```
+
+## Pause in Background
+
+By default, polling pauses when the tab is hidden:
+
+```vue
+<script setup>
+import { usePolling } from "@baklavue/composables";
+
+const { data } = usePolling(
+  () => fetch("/api/live").then((r) => r.json()),
+  { interval: 3000, pauseInBackground: true }
+);
+</script>
+```
+
+## API
+
+### usePolling
+
+```typescript
+usePolling<T>(fetchFn: () => Promise<T>, options): UsePollingReturn<T>
+```
+
+#### Options
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `interval` | `number` | required | Polling interval in ms |
+| `immediate` | `boolean` | `true` | Run first fetch immediately |
+| `initialData` | `T` | - | Initial data before first fetch |
+| `pauseInBackground` | `boolean` | `true` | Pause when tab is hidden |
+| `onSuccess` | `(data: T) => void` | - | Callback on success |
+| `onError` | `(error: Error) => void` | - | Callback on error |
+
+#### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `data` | `Ref<T \| undefined>` | Fetched data |
+| `error` | `Ref<Error \| null>` | Error if fetch failed |
+| `isLoading` | `Ref<boolean>` | True while fetch is in flight |
+| `pause` | `() => void` | Pause polling |
+| `resume` | `() => void` | Resume polling |
+| `isActive` | `Ref<boolean>` | True when polling is active |
+
+## usePolling vs useQuery refetchInterval
+
+| | usePolling | useQuery refetchInterval |
+| --- | --- | --- |
+| Caching | No | Yes |
+| Use case | Simple polling, non-cached data | Cached API data that needs periodic refresh |

package/dist/docs/composables/previous.md

@@ -0,0 +1,58 @@
+# usePrevious
+
+A composable that tracks the previous value of a ref. Useful for diffing, dirty detection, undo logic, or "save changes" only when different.
+
+## Basic Usage
+
+```vue
+<script setup>
+import { usePrevious } from "@baklavue/composables";
+
+const count = ref(0);
+const previousCount = usePrevious(count);
+
+watch(count, (newVal) => {
+  console.log(`Was ${previousCount.value}, now ${newVal}`);
+});
+</script>
+```
+
+## Dirty Detection
+
+```vue
+<script setup>
+import { computed } from "vue";
+import { usePrevious } from "@baklavue/composables";
+
+const formData = ref({ name: "" });
+const initial = usePrevious(formData);
+
+const isDirty = computed(() =>
+  JSON.stringify(formData.value) !== JSON.stringify(initial.value),
+);
+</script>
+```
+
+## API
+
+### Arguments
+
+| Argument | Type | Description |
+| --- | --- | --- |
+| `value` | `Ref<T>` | Ref to track |
+
+### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| (return) | `Ref<T \| undefined>` | Ref holding the previous value (undefined on first render) |
+
+## TypeScript Support
+
+```typescript
+import { usePrevious } from "@baklavue/composables";
+
+const count = ref(0);
+const previous = usePrevious(count);
+// previous: Ref<number | undefined>
+```

package/dist/docs/composables/query.md

@@ -0,0 +1,248 @@
+# useQuery
+
+Data fetching with caching, stale-while-revalidate, retries, and refetch triggers. Inspired by TanStack Query. Use for API data that benefits from caching and invalidation.
+
+## Basic Usage
+
+```vue
+<script setup>
+import { useQuery } from "@baklavue/composables";
+
+const { data, error, isFetching, isLoading, refetch } = useQuery({
+  queryKey: ["users"],
+  queryFn: () => fetch("/api/users").then((r) => r.json()),
+});
+</script>
+
+<template>
+  <div v-if="isLoading">Loading...</div>
+  <div v-else-if="error">Error: {{ error.message }}</div>
+  <div v-else-if="data">
+    <ul>
+      <li v-for="user in data" :key="user.id">{{ user.name }}</li>
+    </ul>
+  </div>
+  <button @click="refetch">Refresh</button>
+</template>
+```
+
+## Reactive Query Key
+
+Use a `computed` or getter for reactive query keys (e.g. when key depends on route params):
+
+```vue
+<script setup>
+import { useQuery } from "@baklavue/composables";
+
+const userId = ref("1");
+const { data } = useQuery({
+  queryKey: () => ["users", userId.value],
+  queryFn: ({ queryKey }) =>
+    fetch(`/api/users/${queryKey[1]}`).then((r) => r.json()),
+});
+
+// Refetches automatically when userId changes
+</script>
+```
+
+## Stale Time
+
+Set `staleTime` to avoid refetching while data is fresh:
+
+```vue
+<script setup>
+import { useQuery } from "@baklavue/composables";
+
+const { data } = useQuery({
+  queryKey: ["users"],
+  queryFn: () => fetch("/api/users").then((r) => r.json()),
+  staleTime: 60_000, // Data stays fresh for 1 minute
+});
+</script>
+```
+
+## Dependent Queries
+
+Use `enabled` to run a query only when dependencies are ready:
+
+```vue
+<script setup>
+import { useQuery } from "@baklavue/composables";
+
+const userId = ref(null);
+const { data } = useQuery({
+  queryKey: () => ["users", userId.value],
+  queryFn: ({ queryKey }) =>
+    fetch(`/api/users/${queryKey[1]}`).then((r) => r.json()),
+  enabled: () => userId.value != null,
+});
+</script>
+```
+
+## Cache Invalidation
+
+Use `useQueryClient` to invalidate or update cached data:
+
+```vue
+<script setup>
+import { useQuery, useQueryClient } from "@baklavue/composables";
+
+const queryClient = useQueryClient();
+
+// Invalidate all queries matching ["users"]
+const invalidateUsers = () => {
+  queryClient.invalidateQueries({ queryKey: ["users"] });
+};
+
+// Manually set cache data
+const setUser = (id, user) => {
+  queryClient.setQueryData(["users", id], user);
+};
+
+// Read cached data
+const cachedUser = queryClient.getQueryData(["users", 1]);
+</script>
+```
+
+## Polling (refetchInterval)
+
+Poll data at a fixed interval:
+
+```vue
+<script setup>
+import { useQuery } from "@baklavue/composables";
+
+const { data } = useQuery({
+  queryKey: ["live-status"],
+  queryFn: () => fetch("/api/status").then((r) => r.json()),
+  refetchInterval: 5000,
+  refetchIntervalInBackground: false, // Pause when tab is hidden
+});
+</script>
+```
+
+## Prefetch
+
+Preload data before navigation (e.g. on link hover):
+
+```vue
+<script setup>
+import { useQueryClient } from "@baklavue/composables";
+
+const queryClient = useQueryClient();
+
+const prefetchUser = (id) => {
+  queryClient.prefetchQuery({
+    queryKey: ["users", id],
+    queryFn: () => fetch(`/api/users/${id}`).then((r) => r.json()),
+  });
+};
+</script>
+
+<template>
+  <a href="/user/1" @mouseenter="prefetchUser(1)">User 1</a>
+</template>
+```
+
+## Refetch Triggers
+
+By default, queries refetch when the window regains focus or when the network reconnects. Disable with options:
+
+```vue
+<script setup>
+import { useQuery } from "@baklavue/composables";
+
+const { data } = useQuery({
+  queryKey: ["users"],
+  queryFn: () => fetch("/api/users").then((r) => r.json()),
+  refetchOnWindowFocus: false,
+  refetchOnReconnect: false,
+});
+</script>
+```
+
+## Retries
+
+Configure retry behavior:
+
+```vue
+<script setup>
+import { useQuery } from "@baklavue/composables";
+
+// Retry 3 times with exponential backoff (default)
+const { data } = useQuery({
+  queryKey: ["users"],
+  queryFn: () => fetch("/api/users").then((r) => r.json()),
+  retry: 3,
+});
+
+// No retries
+const { data: data2 } = useQuery({
+  queryKey: ["config"],
+  queryFn: () => fetch("/api/config").then((r) => r.json()),
+  retry: false,
+});
+</script>
+```
+
+## API
+
+### useQuery
+
+```typescript
+useQuery<T>(options: UseQueryOptions<T>): UseQueryReturn<T>
+```
+
+#### Options
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `queryKey` | `MaybeRefOrGetter<QueryKey>` | required | Unique key for caching (array of values) |
+| `queryFn` | `(context: { queryKey }) => Promise<T>` | required | Async function that fetches data |
+| `staleTime` | `number` | `0` | ms until data is stale (0 = always stale) |
+| `retry` | `number \| boolean` | `3` | Retries on error (`false` = none) |
+| `retryDelay` | `number \| (attempt, error) => number` | exponential backoff | Delay between retries in ms |
+| `enabled` | `MaybeRefOrGetter<boolean>` | `true` | If false, query won't run |
+| `refetchOnWindowFocus` | `boolean` | `true` | Refetch when window regains focus |
+| `refetchOnReconnect` | `boolean` | `true` | Refetch when network reconnects |
+| `refetchInterval` | `number` | `0` | Polling interval in ms (0 = no polling) |
+| `refetchIntervalInBackground` | `boolean` | `false` | Continue polling when tab is hidden |
+| `initialData` | `T \| (() => T)` | - | Initial data before first fetch |
+
+#### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `data` | `Ref<T \| null>` | Fetched data |
+| `error` | `Ref<Error \| null>` | Error if request failed |
+| `isFetching` | `Ref<boolean>` | True while request is in flight |
+| `isLoading` | `Ref<boolean>` | True when no data yet and fetching |
+| `isSuccess` | `Ref<boolean>` | True when data is available |
+| `isError` | `Ref<boolean>` | True when error occurred |
+| `refetch` | `() => Promise<void>` | Manual refetch |
+
+### useQueryClient
+
+```typescript
+useQueryClient(): QueryClient
+```
+
+#### QueryClient Methods
+
+| Method | Description |
+| --- | --- |
+| `invalidateQueries(options?)` | Remove matching entries from cache. `{ queryKey: ["users"] }` invalidates all keys starting with `["users"]` |
+| `getQueryData<T>(queryKey)` | Get cached data for a key |
+| `setQueryData<T>(queryKey, data)` | Manually set cache for a key |
+| `prefetchQuery(options)` | Prefetch and cache data. `{ queryKey, queryFn }` |
+
+## useQuery vs useFetch
+
+| | useQuery | useFetch |
+| --- | --- | --- |
+| Caching | Yes, by query key | No |
+| Stale / refetch | Yes | No |
+| Retries | Configurable | Configurable (opt-in) |
+| Refetch triggers | Window focus, reconnect (default on) | Window focus, reconnect, URL change (opt-in) |
+| Invalidation | Via useQueryClient | N/A |
+| Use case | Cached API data | One-off or non-cached requests |

package/dist/docs/composables/raf.md

@@ -0,0 +1,78 @@
+# useRafFn
+
+Calls a function on every requestAnimationFrame. Returns pause and resume controls. Useful for animation loops and smooth updates.
+
+## Basic Usage
+
+```vue
+<script setup>
+import { ref, onMounted } from "vue";
+import { useRafFn } from "@baklavue/composables";
+
+const position = ref(0);
+const velocity = 100;
+
+const { pause, resume } = useRafFn(({ delta }) => {
+  position.value += velocity * (delta / 1000);
+});
+
+// Pause when tab is hidden
+onMounted(() => {
+  document.addEventListener("visibilitychange", () => {
+    document.hidden ? pause() : resume();
+  });
+});
+</script>
+
+<template>
+  <div :style="{ transform: `translateX(${position}px)` }">
+    Animated content
+  </div>
+</template>
+```
+
+## With FPS Limit
+
+Limit the frame rate to reduce CPU usage:
+
+```vue
+<script setup>
+import { useRafFn } from "@baklavue/composables";
+
+const { pause, resume } = useRafFn(
+  ({ delta }) => {
+    // Update animation
+  },
+  { fpsLimit: 60 }
+);
+</script>
+```
+
+## API
+
+```typescript
+useRafFn(
+  callback: (args: RafCallbackArgs) => void,
+  options?: UseRafFnOptions
+): { pause: () => void; resume: () => void; isActive: Ref<boolean> }
+```
+
+### Callback Args
+
+- `delta` — Time elapsed since last frame in milliseconds
+- `timestamp` — High-resolution timestamp
+
+### Options
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `immediate` | `boolean` | `true` | Start the loop immediately |
+| `fpsLimit` | `number` | `undefined` | Max FPS (no limit if undefined) |
+
+### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `pause` | `() => void` | Pause the animation loop |
+| `resume` | `() => void` | Resume the animation loop |
+| `isActive` | `Ref<boolean>` | True when the loop is running |

package/dist/docs/composables/scrollLock.md

@@ -0,0 +1,46 @@
+# useScrollLock
+
+A composable for locking body scroll when modals or drawers are open. Supports stacking: multiple `lock()` calls require matching `unlock()` calls. Use with `useDisclosure` for BvDialog and BvDrawer.
+
+## Basic Usage
+
+```vue
+<template>
+  <BvButton @click="open">Open Dialog</BvButton>
+  <BvDialog v-model:open="isOpen" caption="Dialog">
+    <p>Content. Body scroll is locked when open.</p>
+  </BvDialog>
+</template>
+
+<script setup>
+import { BvButton, BvDialog } from "@baklavue/ui";
+import { useDisclosure, useScrollLock } from "@baklavue/composables";
+
+const { isOpen, open, close } = useDisclosure();
+const { lock, unlock } = useScrollLock();
+
+watch(isOpen, (opened) => {
+  if (opened) lock();
+  else unlock();
+});
+</script>
+```
+
+## API
+
+### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `isLocked` | `Ref<boolean>` | True when body scroll is locked |
+| `lock` | `() => void` | Lock body scroll |
+| `unlock` | `() => void` | Unlock body scroll |
+| `toggleLock` | `() => void` | Toggle lock state |
+
+## TypeScript Support
+
+```typescript
+import { useScrollLock } from "@baklavue/composables";
+
+const { lock, unlock } = useScrollLock();
+```