@baklavue/mcp 1.0.0

package/dist/docs/composables/infiniteQuery.md

@@ -0,0 +1,104 @@
+# useInfiniteQuery
+
+Composable for infinite scroll / cursor-based pagination. Fetches pages and accumulates them. Use with `useIntersectionObserver` for "load more" on scroll.
+
+## Basic Usage
+
+```vue
+<script setup>
+import { useInfiniteQuery } from "@baklavue/composables";
+
+const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useInfiniteQuery({
+  queryKey: ["items"],
+  queryFn: ({ pageParam }) =>
+    fetch(`/api/items?cursor=${pageParam ?? ""}`).then((r) => r.json()),
+  initialPageParam: null,
+  getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
+});
+</script>
+
+<template>
+  <div>
+    <div v-for="(page, i) in data" :key="i">
+      <div v-for="item in page.items" :key="item.id">{{ item.name }}</div>
+    </div>
+    <button
+      :disabled="!hasNextPage || isFetchingNextPage"
+      @click="fetchNextPage()"
+    >
+      {{ isFetchingNextPage ? "Loading..." : "Load more" }}
+    </button>
+  </div>
+</template>
+```
+
+## With Intersection Observer
+
+Load more when a sentinel element becomes visible:
+
+```vue
+<script setup>
+import { useInfiniteQuery, useIntersectionObserver } from "@baklavue/composables";
+
+const sentinel = ref(null);
+const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useInfiniteQuery({
+  queryKey: ["items"],
+  queryFn: ({ pageParam }) =>
+    fetch(`/api/items?cursor=${pageParam ?? ""}`).then((r) => r.json()),
+  initialPageParam: null,
+  getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
+});
+
+const isVisible = useIntersectionObserver(sentinel);
+watch(isVisible, (visible) => {
+  if (visible && hasNextPage.value && !isFetchingNextPage.value) {
+    fetchNextPage();
+  }
+});
+</script>
+
+<template>
+  <div>
+    <div v-for="(page, i) in data" :key="i">
+      <div v-for="item in page.items" :key="item.id">{{ item.name }}</div>
+    </div>
+    <div ref="sentinel" />
+  </div>
+</template>
+```
+
+## API
+
+### useInfiniteQuery
+
+```typescript
+useInfiniteQuery<TData, TPageParam>(options): UseInfiniteQueryReturn<TData>
+```
+
+#### Options
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `queryKey` | `MaybeRefOrGetter<QueryKey>` | Unique key for caching |
+| `queryFn` | `(context: { queryKey, pageParam }) => Promise<TData>` | Async function that fetches a page |
+| `initialPageParam` | `TPageParam` | Initial page param for first fetch |
+| `getNextPageParam` | `(lastPage: TData) => TPageParam \| undefined` | Extract next page param |
+| `getPreviousPageParam` | `(firstPage: TData) => TPageParam \| undefined` | For bidirectional infinite scroll |
+| `enabled` | `MaybeRefOrGetter<boolean>` | If false, query won't run |
+| `retry` | `number \| boolean` | Retries on error |
+| `refetchOnWindowFocus` | `boolean` | Refetch when window regains focus |
+| `refetchOnReconnect` | `boolean` | Refetch when network reconnects |
+
+#### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `data` | `Ref<TData[] \| null>` | Array of fetched pages |
+| `error` | `Ref<Error \| null>` | Error if request failed |
+| `isFetching` | `Ref<boolean>` | True while initial fetch or refetch |
+| `isFetchingNextPage` | `Ref<boolean>` | True while fetching next page |
+| `hasNextPage` | `Ref<boolean>` | True if more pages available |
+| `hasPreviousPage` | `Ref<boolean>` | True if previous pages available |
+| `fetchNextPage` | `() => Promise<void>` | Fetch the next page |
+| `fetchPreviousPage` | `() => Promise<void>` | Fetch the previous page |
+| `refetch` | `() => Promise<void>` | Refetch from first page |

package/dist/docs/composables/intersectionObserver.md

@@ -0,0 +1,64 @@
+# useIntersectionObserver
+
+Detects when a target element enters or leaves the viewport. Useful for lazy loading, scroll-triggered animations, and "in view" detection.
+
+## Basic Usage
+
+```vue
+<template>
+  <div ref="target">
+    <p v-if="isVisible">This content is visible!</p>
+  </div>
+</template>
+
+<script setup>
+import { ref } from "vue";
+import { useIntersectionObserver } from "@baklavue/composables";
+
+const target = ref(null);
+const isVisible = useIntersectionObserver(target, {
+  threshold: 0.5,
+});
+</script>
+```
+
+## Lazy Loading
+
+```vue
+<template>
+  <div ref="target">
+    <img v-if="isVisible" :src="imageSrc" alt="Lazy loaded" />
+  </div>
+</template>
+
+<script setup>
+import { ref } from "vue";
+import { useIntersectionObserver } from "@baklavue/composables";
+
+const target = ref(null);
+const isVisible = useIntersectionObserver(target, { threshold: 0 });
+const imageSrc = ref("");
+</script>
+```
+
+## API
+
+```typescript
+useIntersectionObserver(
+  target: Ref<Element | null | undefined>,
+  options?: UseIntersectionObserverOptions
+): Ref<boolean>
+```
+
+### Options
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `root` | `Element \| Document \| null` | `null` | Root element (null = viewport) |
+| `rootMargin` | `string` | `"0px"` | Margin around root |
+| `threshold` | `number \| number[]` | `0` | Visibility threshold 0-1 |
+| `immediate` | `boolean` | `true` | Start observing immediately |
+
+### Return Value
+
+Returns a `Ref<boolean>` that is `true` when the target is visible (intersecting).

package/dist/docs/composables/lazyQuery.md

@@ -0,0 +1,68 @@
+# useLazyQuery
+
+Composable for lazy/on-demand queries. Does not fetch until `execute()` is called. Wraps `useQuery` with `enabled: false` initially.
+
+## Basic Usage
+
+```vue
+<script setup>
+import { ref } from "vue";
+import { useLazyQuery } from "@baklavue/composables";
+
+const userId = ref(1);
+const { data, execute, isLoading } = useLazyQuery({
+  queryKey: () => ["user", userId.value],
+  queryFn: ({ queryKey }) =>
+    fetch(`/api/users/${queryKey[1]}`).then((r) => r.json()),
+});
+
+const handleLoad = () => execute();
+</script>
+
+<template>
+  <div>
+    <button :disabled="isLoading" @click="handleLoad">Load User</button>
+    <div v-if="data">{{ data.name }}</div>
+  </div>
+</template>
+```
+
+## Await Result
+
+`execute()` returns a promise that resolves when the fetch completes:
+
+```vue
+<script setup>
+import { useLazyQuery } from "@baklavue/composables";
+
+const { data, execute } = useLazyQuery({
+  queryKey: ["details"],
+  queryFn: () => fetch("/api/details").then((r) => r.json()),
+});
+
+const handleLoad = async () => {
+  await execute();
+  // data is now populated
+};
+</script>
+```
+
+## API
+
+### useLazyQuery
+
+```typescript
+useLazyQuery<T>(options: UseLazyQueryOptions<T>): UseLazyQueryReturn<T>
+```
+
+#### Options
+
+Same as `useQuery` except `enabled` is always `false` (query starts disabled).
+
+#### Return Value
+
+Same as `useQuery` plus:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `execute` | `() => Promise<void>` | Execute the query. First call fetches, subsequent calls refetch. |

package/dist/docs/composables/loading.md

@@ -0,0 +1,91 @@
+# useLoading
+
+A composable for generic loading state with optional delay to avoid flicker for fast operations. Use with BvSkeleton, BvSpinner, or loading overlays.
+
+## Basic Usage
+
+```vue
+<template>
+  <div>
+    <BvSkeleton v-if="isLoading" variant="rectangle" />
+    <div v-else>{{ data }}</div>
+    <BvButton @click="fetchData" :loading="isLoading">Load</BvButton>
+  </div>
+</template>
+
+<script setup>
+import { BvButton, BvSkeleton } from "@baklavue/ui";
+import { useLoading } from "@baklavue/composables";
+
+const { isLoading, showLoading, hideLoading } = useLoading();
+
+const fetchData = async () => {
+  showLoading();
+  try {
+    const res = await fetch("/api/data");
+    data.value = await res.json();
+  } finally {
+    hideLoading();
+  }
+};
+</script>
+```
+
+## With Delay
+
+```vue
+<script setup>
+import { useLoading } from "@baklavue/composables";
+
+const { isLoading, showLoading, hideLoading } = useLoading({ delay: 200 });
+
+// isLoading only becomes true after 200ms. Useful to avoid flicker for fast requests.
+const quickFetch = async () => {
+  showLoading();
+  await api.getData();
+  hideLoading();
+};
+</script>
+```
+
+## With Async Wrapper
+
+```vue
+<script setup>
+import { useLoading } from "@baklavue/composables";
+
+const { isLoading, withLoading } = useLoading();
+
+const handleSave = () =>
+  withLoading(async () => {
+    await api.save();
+  });
+</script>
+```
+
+## API
+
+### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `isLoading` | `Ref<boolean>` | True when loading |
+| `showLoading` | `() => void` | Start loading |
+| `hideLoading` | `() => void` | Stop loading |
+| `withLoading` | `(fn: () => Promise<T>) => Promise<T>` | Wraps async function with loading state |
+
+### Options
+
+```typescript
+interface UseLoadingOptions {
+  delay?: number; // ms before showing loading (default: 0)
+}
+```
+
+## TypeScript Support
+
+```typescript
+import { useLoading, type UseLoadingOptions } from "@baklavue/composables";
+
+const { isLoading, withLoading } = useLoading({ delay: 200 });
+```

package/dist/docs/composables/mutation.md

@@ -0,0 +1,83 @@
+# useMutation
+
+Composable for mutations (POST/PUT/PATCH/DELETE) with explicit trigger. Pairs with `useQuery` for cache invalidation after mutations.
+
+## Basic Usage
+
+```vue
+<script setup>
+import { useMutation, useQueryClient } from "@baklavue/composables";
+
+const queryClient = useQueryClient();
+const { mutate, mutateAsync, isPending, data } = useMutation({
+  mutationFn: (user) =>
+    fetch("/api/users", {
+      method: "POST",
+      body: JSON.stringify(user),
+      headers: { "Content-Type": "application/json" },
+    }).then((r) => r.json()),
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: ["users"] }),
+});
+
+const handleCreate = () => mutate({ name: "John", email: "john@example.com" });
+</script>
+
+<template>
+  <button :disabled="isPending" @click="handleCreate">
+    {{ isPending ? "Creating..." : "Create User" }}
+  </button>
+</template>
+```
+
+## mutateAsync
+
+Use `mutateAsync` when you need to await the result:
+
+```vue
+<script setup>
+import { useMutation } from "@baklavue/composables";
+
+const { mutateAsync } = useMutation({
+  mutationFn: (data) => fetch("/api/save", { method: "POST", body: JSON.stringify(data) }).then((r) => r.json()),
+});
+
+const handleSubmit = async () => {
+  try {
+    const result = await mutateAsync({ title: "New Post" });
+    router.push(`/posts/${result.id}`);
+  } catch (err) {
+    console.error(err);
+  }
+};
+</script>
+```
+
+## API
+
+### useMutation
+
+```typescript
+useMutation<TData, TError, TVariables>(options): UseMutationReturn<TData, TVariables>
+```
+
+#### Options
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `mutationFn` | `(variables: TVariables) => Promise<TData>` | Async function that performs the mutation |
+| `onSuccess` | `(data: TData, variables: TVariables) => void` | Callback on success |
+| `onError` | `(error: TError, variables: TVariables) => void` | Callback on error |
+| `onSettled` | `(data, error, variables) => void` | Callback when mutation settles |
+
+#### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `data` | `Ref<TData \| null>` | Fetched data on success |
+| `error` | `Ref<Error \| null>` | Error if mutation failed |
+| `isPending` | `Ref<boolean>` | True while mutation is in flight |
+| `isSuccess` | `Ref<boolean>` | True when mutation succeeded |
+| `isError` | `Ref<boolean>` | True when mutation failed |
+| `mutate` | `(variables: TVariables) => void` | Execute mutation (fire-and-forget) |
+| `mutateAsync` | `(variables: TVariables) => Promise<TData>` | Execute mutation (returns promise) |
+| `reset` | `() => void` | Reset state to initial |

package/dist/docs/composables/notification.md

@@ -0,0 +1,169 @@
+# useNotification
+
+A composable for managing notifications programmatically.
+
+## Basic Usage
+
+```vue
+<template>
+  <div>
+    <BvButton @click="showSuccess">Success</BvButton>
+    <BvButton @click="showError">Error</BvButton>
+    <BvButton @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>
+```
+
+## Methods
+
+### success
+
+Shows a success notification.
+
+```typescript
+success(options: NotificationOptions): void
+```
+
+### error
+
+Shows an error notification.
+
+```typescript
+error(options: NotificationOptions): void
+```
+
+### warning
+
+Shows a warning notification.
+
+```typescript
+warning(options: NotificationOptions): void
+```
+
+### info
+
+Shows an info notification.
+
+```typescript
+info(options: NotificationOptions): void
+```
+
+## Notification Options
+
+Uses Baklava's `NotificationProps`. Key options:
+
+```typescript
+interface NotificationOptions {
+  caption?: string; // Notification title
+  description: string; // Notification message (required)
+  duration?: number;
+  permanent?: boolean;
+  primaryAction?: { label: string; onClick: () => void };
+  secondaryAction?: { label: string; onClick: () => void };
+}
+```
+
+## Examples
+
+### With Duration
+
+```vue
+<script setup>
+import { useNotification } from "@baklavue/composables";
+
+const { success } = useNotification();
+
+const showNotification = () => {
+  success({
+    caption: "Saved",
+    description: "Your changes have been saved",
+    duration: 5, // Show for 5 seconds
+  });
+};
+</script>
+```
+
+### With Custom Message
+
+```vue
+<script setup>
+import { useNotification } from '@baklavue/composables'
+
+const { error } = useNotification()
+
+const handleError = (err: Error) => {
+  error({
+    caption: 'Error',
+    description: err.message
+  })
+}
+</script>
+```
+
+## Requirements
+
+The `useNotification` composable requires a `<Notification />` component to be present in your component tree:
+
+```vue
+<template>
+  <div>
+    <!-- Your app content -->
+    <Notification />
+  </div>
+</template>
+
+<script setup>
+import { Notification } from "@baklavue/ui";
+</script>
+```
+
+## TypeScript Support
+
+```typescript
+import { useNotification } from "@baklavue/composables";
+
+const notification = useNotification();
+
+// All methods are fully typed
+notification.success({
+  caption: "Success",
+  description: "Done!",
+});
+```

package/dist/docs/composables/pagination.md

@@ -0,0 +1,109 @@
+# usePagination
+
+Pagination state for tables and lists. Provides `currentPage`, `pageSize`, `totalItems`, derived `totalPages`, `offset`, and a `slice` helper. Use with BvPagination or BvTable.
+
+## Basic Usage
+
+```vue
+<template>
+  <BvPagination
+    v-model:current-page="currentPage"
+    :total-items="totalItems"
+    :page-size="pageSize"
+  />
+</template>
+
+<script setup>
+import { computed, ref, watch } from "vue";
+import { BvPagination } from "@baklavue/ui";
+import { usePagination } from "@baklavue/composables";
+
+const allItems = ref([/* ... */]);
+
+const {
+  currentPage,
+  pageSize,
+  totalItems,
+  totalPages,
+  setPage,
+  setPageSize,
+  setTotalItems,
+  slice,
+} = usePagination({
+  totalItems: 100,
+  pageSize: 10,
+});
+
+// Sync totalItems when data changes
+watch(allItems, (items) => setTotalItems(items.length), { immediate: true });
+
+// Get items for current page
+const pageItems = computed(() => slice(allItems.value));
+</script>
+```
+
+## With BvTable
+
+```vue
+<template>
+  <BvTable
+    :columns="columns"
+    :data="pageData"
+    :pagination="{
+      currentPage,
+      totalItems,
+      itemsPerPage: pageSize,
+    }"
+  />
+</template>
+
+<script setup>
+import { computed, ref, watch } from "vue";
+import { BvTable } from "@baklavue/ui";
+import { usePagination } from "@baklavue/composables";
+
+const allData = ref([/* ... */]);
+const { currentPage, pageSize, totalItems, slice, setTotalItems } = usePagination({
+  pageSize: 10,
+});
+
+watch(allData, (data) => setTotalItems(data.length), { immediate: true });
+
+const pageData = computed(() => slice(allData.value));
+</script>
+```
+
+## API
+
+### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `currentPage` | `Ref<number>` | Current page (1-based) |
+| `pageSize` | `Ref<number>` | Items per page |
+| `totalItems` | `Ref<number>` | Total item count |
+| `totalPages` | `ComputedRef<number>` | Total pages |
+| `offset` | `ComputedRef<number>` | Offset for current page |
+| `setPage` | `(page: number) => void` | Set current page |
+| `setPageSize` | `(size: number) => void` | Set items per page |
+| `setTotalItems` | `(total: number) => void` | Set total items |
+| `slice` | `<T>(arr: T[]) => T[]` | Slice array for current page |
+
+### Options
+
+```typescript
+interface UsePaginationOptions {
+  totalItems?: number;   // Default: 0
+  pageSize?: number;     // Default: 10
+  initialPage?: number;  // Default: 1
+}
+```
+
+## TypeScript Support
+
+```typescript
+import { usePagination, type UsePaginationOptions } from "@baklavue/composables";
+
+const options: UsePaginationOptions = { totalItems: 50, pageSize: 5 };
+const pagination = usePagination(options);
+```