@baklavue/mcp 1.0.0

package/dist/docs/composables/formValidation.md

@@ -0,0 +1,355 @@
+# useZodForm
+
+A composable for form validation with [Zod](https://zod.dev) schemas. Supports lazy (validate on submit, then real-time) or eager (validate on every change) validation modes. Integrates with `useScrollToError` for scrolling to the first invalid field.
+
+## Prerequisites
+
+Install Zod in your project:
+
+```bash
+bun add zod
+# or: npm install zod
+```
+
+## Basic Usage
+
+<div class="component-demo">
+
+<ZodFormValidationDemo />
+
+</div>
+
+```vue
+<template>
+  <form @submit.prevent="handleSubmit" style="max-width: 300px; display: flex; flex-direction: column; gap: 1rem;">
+    <div data-field="email">
+      <BvInput
+        v-model="form.email"
+        type="email"
+        label="Email"
+        :invalid-text="getError('email')"
+      />
+    </div>
+    <div data-field="password">
+      <BvInput
+        v-model="form.password"
+        type="password"
+        label="Password"
+        help-text="Must be at least 8 characters"
+        :invalid-text="getError('password')"
+      />
+    </div>
+    <BvButton type="submit">Submit</BvButton>
+  </form>
+</template>
+
+<script setup lang="ts">
+import { BvButton, BvInput } from "@baklavue/ui";
+import { useZodForm } from "@baklavue/composables";
+import { ref } from "vue";
+import { z } from "zod";
+
+const form = ref({
+  email: "",
+  password: "",
+});
+
+const schema = z.object({
+  email: z.string().min(1, "Email is required").email("Please enter a valid email"),
+  password: z.string().min(8, "Password must be at least 8 characters"),
+});
+
+const { validate, getError, scrollToFirstError } = useZodForm(schema, form, {
+  mode: "lazy",
+});
+
+const handleSubmit = async () => {
+  const errors = await validate();
+  if (!errors) {
+    console.log("Form submitted:", form.value);
+  } else {
+    scrollToFirstError();
+  }
+};
+</script>
+```
+
+## Validation Modes
+
+### Lazy (default)
+
+Validates only when you call `validate()`. After the first validation, errors update in real time as the user types. Best for forms where you want to avoid showing errors until the user attempts to submit.
+
+```typescript
+const { validate } = useZodForm(schema, form, { mode: "lazy" });
+
+const handleSubmit = async () => {
+  const errors = await validate();
+  if (!errors) {
+    // submit
+  }
+};
+```
+
+### Eager
+
+Validates immediately when form data changes. Errors appear as soon as the user interacts with fields. Use for shorter forms or when you want immediate feedback.
+
+```typescript
+const { validate } = useZodForm(schema, form, { mode: "eager" });
+```
+
+## API
+
+### Parameters
+
+```typescript
+useZodForm(schema, data, options?)
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `schema` | `ZodSchema \| Ref<ZodSchema> \| () => ZodSchema` | Zod schema (object, ref, or getter) |
+| `data` | `Ref<T> \| Reactive<T> \| () => T` | Form data (ref, reactive, or getter) |
+| `options` | `UseZodFormOptions` | Optional: `{ mode: 'lazy' \| 'eager', debounce?: number }` |
+
+### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `validate` | `() => Promise<FormErrors \| null>` | Runs validation. Returns errors or `null` if valid |
+| `validateField` | `(path: string) => Promise<FormErrors \| null>` | Validates only the field at path (use on blur). Falls back to full validation if schema cannot be extracted |
+| `errors` | `Ref<FormErrors>` | Reactive errors grouped by field path |
+| `isValid` | `Ref<boolean>` | Whether the form is currently valid |
+| `clearErrors` | `() => void` | Clears all errors |
+| `reset` | `(initialValues?: unknown) => void` | Clears errors, touched fields, and optionally resets form data to initial values |
+| `getError` | `(path: string) => string \| undefined` | Returns first error message for a field path |
+| `getErrors` | `(path: string) => string[]` | Returns all error messages for a field path |
+| `handleSubmit` | `(onSubmit: (data) => R \| Promise<R>) => Promise<R>` | Validates, then calls onSubmit with validated data if valid; otherwise scrolls to first error and rejects |
+| `scrollToFirstError` | `(options?: ScrollToFirstErrorOptions) => ScrollToErrorResult` | Scrolls to first invalid field (requires `data-field` on wrapper). Returns `{ success: boolean }` |
+| `setFieldValue` | `(path: string, value: unknown) => void` | Programmatically set a field value |
+| `setErrors` | `(errors: FormErrors) => void` | Set errors (e.g. from server-side validation) |
+| `setFieldError` | `(path: string, message: string) => void` | Set error for a single field |
+| `initialValues` | `Ref<unknown>` | Snapshot of initial values (used for dirty check and reset) |
+| `isDirty` | `Ref<boolean>` | Whether any field has changed from initial values |
+| `dirtyFields` | `Ref<Record<string, boolean>>` | Per-field dirty state |
+| `touched` | `Ref<boolean>` | Whether any field has been blurred |
+| `touchedFields` | `Ref<Record<string, boolean>>` | Per-field touched state |
+| `setFieldTouched` | `(path: string, value?: boolean) => void` | Mark a field as touched (e.g. on blur) |
+| `isSubmitting` | `Ref<boolean>` | `true` while `handleSubmit` callback is running |
+| `isSubmitted` | `Ref<boolean>` | `true` after first submit attempt |
+| `submitCount` | `Ref<number>` | Number of submit attempts |
+
+### UseZodFormOptions
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `mode` | `'lazy' \| 'eager'` | `'lazy'` | When to run validation |
+| `debounce` | `number` | `0` | Debounce validation in ms for eager mode. Use for large forms |
+
+## Scroll to First Error
+
+Use `scrollToFirstError()` after validation fails to scroll to the first invalid field. Wrap each form control in an element with `data-field` matching the schema path:
+
+```vue
+<template>
+  <form @submit.prevent="handleSubmit">
+    <div data-field="email">
+      <BvInput v-model="form.email" :invalid-text="getError('email')" />
+    </div>
+    <div data-field="password">
+      <BvInput v-model="form.password" :invalid-text="getError('password')" />
+    </div>
+    <BvButton type="submit">Submit</BvButton>
+  </form>
+</template>
+
+<script setup lang="ts">
+const { validate, getError, scrollToFirstError } = useZodForm(schema, form);
+
+const handleSubmit = async () => {
+  const errors = await validate();
+  if (errors) {
+    scrollToFirstError();
+  }
+};
+</script>
+```
+
+`scrollToFirstError` accepts the same options as [useScrollToError](/composables/scrollToError) (`scrollBehavior`, `block`, `shineClass`, `shineDuration`, `focus`, `focusDelay`, `scrollContainer`, `announce`, `scrollOffset`), plus `fieldSelector` to customize how field paths map to DOM selectors:
+
+```typescript
+scrollToFirstError({
+  fieldSelector: (path) => `[name="${path}"]`, // Use name attribute instead of data-field
+  scrollContainer: "[data-dialog-body]", // For forms inside modals
+  scrollOffset: { top: 80 }, // For fixed headers
+});
+```
+
+## handleSubmit
+
+Use `handleSubmit(onSubmit)` to validate and submit in one call. If validation fails, it scrolls to the first error and rejects. If valid, it calls `onSubmit` with the validated (and possibly transformed) data:
+
+```typescript
+const { handleSubmit } = useZodForm(schema, form);
+
+const onSubmit = () =>
+  handleSubmit(async (data) => {
+    await api.submit(data);
+  });
+```
+
+`handleSubmit` sets `isSubmitting` to `true` while the callback runs. Use it to disable the submit button:
+
+```typescript
+const { handleSubmit, isSubmitting } = useZodForm(schema, form);
+
+const onSubmit = () =>
+  handleSubmit(async (data) => await api.submit(data));
+
+// In template: <BvButton type="submit" :disabled="isSubmitting">Submit</BvButton>
+```
+
+For additional loading overlay, combine with [useLoading](/composables/loading):
+
+```typescript
+const { handleSubmit, isSubmitting } = useZodForm(schema, form);
+const { withLoading } = useLoading();
+
+const onSubmit = () =>
+  withLoading(() =>
+    handleSubmit(async (data) => await api.submit(data))
+  );
+```
+
+## reset
+
+Use `reset()` to clear errors and optionally reset form data. Pass initial values when using a ref:
+
+```typescript
+const { reset } = useZodForm(schema, form);
+
+// Clear errors only
+reset();
+
+// Reset to initial values (when data is a ref)
+reset({ email: "", password: "" });
+```
+
+## On-Blur Validation
+
+For field-level validation on blur, use `validateField`:
+
+```vue
+<div data-field="email">
+  <BvInput
+    v-model="form.email"
+    @blur="validateField('email')"
+    :invalid-text="getError('email')"
+  />
+</div>
+```
+
+## Debounce (Eager Mode)
+
+For large forms or expensive schemas in eager mode, add a debounce to avoid validating on every keystroke:
+
+```typescript
+const { validate } = useZodForm(schema, form, {
+  mode: "eager",
+  debounce: 300,
+});
+```
+
+## Dirty & Touched State
+
+`isDirty` and `dirtyFields` track whether the form has changed from its initial values. Useful for "unsaved changes" dialogs:
+
+```typescript
+const { isDirty } = useZodForm(schema, form);
+
+// Before navigation
+if (isDirty.value) {
+  showConfirmDialog("You have unsaved changes");
+}
+```
+
+`touched` and `touchedFields` track which fields have been blurred. Call `setFieldTouched(path)` on blur to enable "show error only after touch" UX:
+
+```vue
+<BvInput
+  v-model="form.email"
+  @blur="setFieldTouched('email')"
+  :invalid-text="touchedFields.email ? getError('email') : undefined"
+/>
+```
+
+## Server-Side Errors
+
+Use `setErrors` or `setFieldError` when the API returns validation errors:
+
+```typescript
+const { setErrors, setFieldError } = useZodForm(schema, form);
+
+try {
+  await api.submit(form.value);
+} catch (err) {
+  if (err.response?.data?.errors) {
+    // Map API errors to FormErrors shape: { "path": ZodIssue[] }
+    setErrors(mapApiErrorsToFormErrors(err.response.data.errors));
+  }
+}
+```
+
+For a single field:
+
+```typescript
+setFieldError("email", "This email is already registered");
+```
+
+## Nested Fields
+
+For nested schema paths like `address.city`, use the dot notation in `getError`:
+
+```typescript
+const schema = z.object({
+  address: z.object({
+    city: z.string().min(1, "City is required"),
+  }),
+});
+
+// In template
+getError("address.city");
+```
+
+```vue
+<div data-field="address.city">
+  <BvInput v-model="form.address.city" :invalid-text="getError('address.city')" />
+</div>
+```
+
+## TypeScript Support
+
+```typescript
+import {
+  useZodForm,
+  type FormErrors,
+  type InferFormData,
+  type ScrollToFirstErrorOptions,
+  type UseZodFormOptions,
+} from "@baklavue/composables";
+import { z } from "zod";
+
+const schema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+});
+
+type FormData = z.infer<typeof schema>;
+const form = ref<FormData>({ email: "", password: "" });
+
+const { validate, errors, isValid, getError, handleSubmit } = useZodForm(
+  schema,
+  form,
+);
+```

package/dist/docs/composables/format.md

@@ -0,0 +1,107 @@
+# useDateFormat & useNumberFormat
+
+Composables for reactive, locale-aware date and number formatting using native `Intl.DateTimeFormat` and `Intl.NumberFormat`. No external date library required.
+
+## useDateFormat
+
+### Basic Usage
+
+```vue
+<template>
+  <span>{{ formatted }}</span>
+</template>
+
+<script setup>
+import { ref } from "vue";
+import { useDateFormat } from "@baklavue/composables";
+
+const date = ref(new Date());
+const formatted = useDateFormat(date, { dateStyle: "medium" });
+// "Feb 11, 2025"
+</script>
+```
+
+### With Locale
+
+```vue
+<script setup>
+import { useDateFormat } from "@baklavue/composables";
+
+const formatted = useDateFormat(new Date(), {
+  year: "numeric",
+  month: "short",
+  day: "numeric",
+  locale: "tr-TR",
+});
+</script>
+```
+
+### API
+
+| Argument | Type | Description |
+| --- | --- | --- |
+| `date` | `MaybeRefOrGetter<Date \| string \| number \| null \| undefined>` | Date to format |
+| `options` | `UseDateFormatOptions` | Intl.DateTimeFormatOptions plus optional `locale` |
+
+Returns: `ComputedRef<string>`
+
+---
+
+## useNumberFormat
+
+### Basic Usage
+
+```vue
+<template>
+  <span>{{ formatted }}</span>
+</template>
+
+<script setup>
+import { ref } from "vue";
+import { useNumberFormat } from "@baklavue/composables";
+
+const price = ref(99.99);
+const formatted = useNumberFormat(price, { style: "currency", currency: "USD" });
+// "$99.99"
+</script>
+```
+
+### Decimal Formatting
+
+```vue
+<script setup>
+import { useNumberFormat } from "@baklavue/composables";
+
+const count = ref(1234);
+const formatted = useNumberFormat(count, {
+  style: "decimal",
+  minimumFractionDigits: 2,
+  locale: "tr-TR",
+});
+</script>
+```
+
+### API
+
+| Argument | Type | Description |
+| --- | --- | --- |
+| `value` | `MaybeRefOrGetter<number \| null \| undefined>` | Number to format |
+| `options` | `UseNumberFormatOptions` | Intl.NumberFormatOptions plus optional `locale` |
+
+Returns: `ComputedRef<string>`
+
+---
+
+## TypeScript Support
+
+```typescript
+import {
+  useDateFormat,
+  useNumberFormat,
+  type UseDateFormatOptions,
+  type UseNumberFormatOptions,
+} from "@baklavue/composables";
+
+const formatted = useDateFormat(dateRef, { dateStyle: "long" });
+const price = useNumberFormat(priceRef, { style: "currency", currency: "EUR" });
+```

package/dist/docs/composables/id.md

@@ -0,0 +1,54 @@
+# useId
+
+A composable for generating stable unique IDs for use with accessibility attributes such as `aria-describedby`, `aria-labelledby`, and form labels.
+
+## Basic Usage
+
+```vue
+<template>
+  <div>
+    <label :for="inputId">Name</label>
+    <input :id="inputId" type="text" />
+  </div>
+</template>
+
+<script setup>
+import { useId } from "@baklavue/composables";
+
+const inputId = useId();
+</script>
+```
+
+## Custom Prefix
+
+```vue
+<script setup>
+import { useId } from "@baklavue/composables";
+
+const dialogId = useId("dialog");
+// dialogId.value = "dialog-1"
+</script>
+```
+
+## API
+
+### Return Value
+
+Returns a `Ref<string>` — use `id.value` in script or `id` in template for the stable unique ID.
+
+### Parameters
+
+```typescript
+useId(prefix?: string)
+```
+
+- `prefix` — Optional prefix for the ID. Default: `"bv"`
+
+## TypeScript Support
+
+```typescript
+import { useId } from "@baklavue/composables";
+
+const id = useId();
+// id is Ref<string>
+```

package/dist/docs/composables/index.md

@@ -0,0 +1,112 @@
+# Composables
+
+BaklaVue provides Vue 3 composables to enhance your application functionality.
+
+## Available Composables
+
+### UI & Feedback
+
+- [Notification](/composables/notification) (`useNotification`) - Programmatically manage notifications
+- [Confirm Dialog](/composables/confirmDialog) (`useConfirmDialog`) - Confirm/cancel dialog flow
+- [Disclosure](/composables/disclosure) (`useDisclosure`) - Open/close state for Dialog, Drawer, Dropdown
+- [Stepper](/composables/stepper) (`useStepper`) - Multi-step wizard state for BvStepper
+- [Scroll Visibility](/composables/scrollVisibility) (`useScrollVisibility`) - Scroll-based visibility for scroll-to-top and sticky UI
+- [Scroll Lock](/composables/scrollLock) (`useScrollLock`) - Lock body scroll when modals/drawers are open
+- [Alert](/composables/alert) (`useAlert`) - Programmatic show/hide for inline BvAlert
+- [Loading](/composables/loading) (`useLoading`) - Generic loading state with optional delay
+- [Focus Trap](/composables/focusTrap) (`useFocusTrap`) - Trap focus within modals/dialogs
+- [Id](/composables/id) (`useId`) - Stable unique IDs for accessibility attributes
+
+### Forms
+
+- [Form Validation](/composables/formValidation) (`useZodForm`) - Form validation with Zod schemas
+- [Form State](/composables/formState) (`useFormState`) - Form dirty and touched state without validation
+- [Field Array](/composables/fieldArray) (`useFieldArray`) - Dynamic array fields for forms
+- [Form Persistence](/composables/formPersistence) (`useFormPersistence`) - Auto-save form data to localStorage/sessionStorage
+- [Stepper Form](/composables/stepperForm) (`useStepperForm`) - Multi-step form validation with useStepper
+- [Scroll to Error](/composables/scrollToError) (`useScrollToError`) - Scroll to element with validation error
+
+### Data & Utilities
+
+- [File](/composables/file) (`useFile`) - Parse, create, and download CSV, TSV, and JSON files
+- [Clipboard](/composables/clipboard) (`useClipboard`) - Copy text to clipboard
+- [Storage](/composables/storage) (`useLocalStorage` / `useSessionStorage`) - Reactive sync with localStorage and sessionStorage
+- [Cookie](/composables/cookie) (`useCookie`) - Reactive sync with document.cookie
+- [Share](/composables/share) (`useShare`) - Share text, URLs, or files via Web Share API
+- [Base64](/composables/base64) (`useBase64`) - Convert Blob/File/ArrayBuffer/canvas to Base64
+- [Previous](/composables/previous) (`usePrevious`) - Track previous value of a ref
+- [Toggle](/composables/toggle) (`useToggle`) - Simple boolean toggle
+- [DateFormat](/composables/format) (`useDateFormat`) - Reactive locale-aware date formatting
+- [NumberFormat](/composables/format) (`useNumberFormat`) - Reactive locale-aware number/currency formatting
+- [Slug](/composables/slug) (`useSlug`) - Convert string to URL-friendly slug
+- [Async State](/composables/asyncState) (`useAsyncState`) - Generic async state (loading, error, data)
+
+### Performance
+
+- [Debounce](/composables/debounce) (`useDebounceFn` / `useDebouncedRef`) - Debounce function or ref value
+- [Throttle](/composables/throttle) (`useThrottleFn` / `useThrottledRef`) - Throttle function or ref value
+- [Timer](/composables/timer) (`useIntervalFn` / `useTimeoutFn`) - Pausable interval and cancellable timeout
+- [Request Animation Frame](/composables/raf) (`useRafFn`) - Animation frame loop
+
+### Browser APIs
+
+- [Breakpoints](/composables/breakpoints) (`useBreakpoints`) - Responsive breakpoints (isMobile, isTablet, isDesktop)
+- [Window Size](/composables/breakpoints#use-window-size) (`useWindowSize`) - Reactive viewport width and height
+- [Intersection Observer](/composables/intersectionObserver) (`useIntersectionObserver`) - Detect element visibility in viewport
+- [Element Size](/composables/elementSize) (`useElementSize`) - Reactive element dimensions via ResizeObserver
+- [Container Scroll](/composables/containerScroll) (`useContainerScroll`) - Scroll position inside a scrollable div
+- [Sticky](/composables/sticky) (`useSticky`) - Detect when sticky element is stuck
+
+### Data Fetching
+
+- [Fetch](/composables/fetch) (`useFetch`) - Reactive fetch with loading/error/data
+- [Query](/composables/query) (`useQuery`) - Data fetching with caching, retries, and invalidation
+- [Mutation](/composables/mutation) (`useMutation`) - Mutations (POST/PUT/DELETE) with cache invalidation
+- [Infinite Query](/composables/infiniteQuery) (`useInfiniteQuery`) - Infinite scroll / cursor-based pagination
+- [Lazy Query](/composables/lazyQuery) (`useLazyQuery`) - On-demand queries that fetch when execute() is called
+- [Polling](/composables/polling) (`usePolling`) - Polling with fetch state (non-cached)
+
+### Theme & Layout
+
+- [Theme](/composables/theme) (`useBaklavaTheme`) - Overwrite Baklava colors (Vue preset or custom)
+- [Color Scheme](/composables/colorScheme) (`useColorScheme`) - Light/dark/system with persistence
+- [Theme Preset](/composables/themePreset) (`useThemePreset`) - Persist Baklava theme preset
+- [Pagination](/composables/pagination) (`usePagination`) - Pagination state for tables and lists
+
+## Usage Pattern
+
+Composables follow Vue 3 Composition API patterns:
+
+```vue
+<script setup>
+import { useNotification } from "@baklavue/composables";
+
+const { success, error, warning, info } = useNotification();
+
+// Use the composable methods
+success({
+  caption: "Success!",
+  description: "Operation completed",
+});
+</script>
+```
+
+## Importing Composables
+
+```typescript
+import { useNotification } from "@baklavue/composables";
+```
+
+## TypeScript Support
+
+All composables are fully typed:
+
+```typescript
+import type { ApplyThemeOptions } from "@baklavue/composables";
+```
+
+## Next Steps
+
+- Explore individual composable documentation
+- Check [API Reference](/api/) for detailed API
+- See [Getting Started Guide](/guide/getting-started) for setup