@baklavue/mcp 1.0.0

package/dist/docs/composables/scrollToError.md

@@ -0,0 +1,291 @@
+# useScrollToError
+
+A composable for scrolling to an element with validation error. Scrolls into view, optionally applies a highlight effect, focuses the first focusable control, and announces to screen readers.
+
+## Basic Usage
+
+```vue
+<template>
+  <form @submit.prevent="handleSubmit">
+    <div data-field="tags">
+      <input v-model="tags" />
+    </div>
+    <button type="submit">Submit</button>
+  </form>
+</template>
+
+<script setup lang="ts">
+import { useScrollToError } from "@baklavue/composables";
+
+const { scrollToError } = useScrollToError();
+
+const handleSubmit = () => {
+  const err = validationError.value;
+  if (err) {
+    scrollToError(err);
+  }
+};
+</script>
+```
+
+### Direct Selector
+
+```vue
+<script setup lang="ts">
+import { useScrollToError } from "@baklavue/composables";
+
+const { scrollToError } = useScrollToError();
+
+// Scroll to element by selector
+scrollToError('[data-field="tags"]');
+</script>
+```
+
+### With Validation Error Object
+
+```vue
+<script setup lang="ts">
+import { useScrollToError } from "@baklavue/composables";
+
+const { scrollToError } = useScrollToError();
+
+// Validation error with scrollTarget
+const validationError = {
+  field: "tags",
+  message: "Please select at least one option",
+  scrollTarget: '[data-field="tags"]',
+};
+
+scrollToError(validationError);
+</script>
+```
+
+## Methods
+
+### scrollToError
+
+Scrolls to the target element and optionally applies highlight and focus.
+
+```typescript
+scrollToError(target: ScrollToErrorTarget, options?: ScrollToErrorOptions): ScrollToErrorResult
+```
+
+Returns `{ success: boolean }` indicating whether the target was found and scrolled to.
+
+## Target Types
+
+Accepted by `scrollToError`:
+
+- **CSS selector string** – e.g. `'[data-field="tags"]'`
+- **HTMLElement** – direct element reference
+- **Object with scrollTarget** – e.g. `{ scrollTarget: '[data-field="tags"]' }` for validation errors
+
+## Options
+
+### ScrollToErrorOptions
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `scrollBehavior` | `'smooth' \| 'auto' \| 'instant'` | `'smooth'` | Scroll behavior |
+| `block` | `'start' \| 'center' \| 'end' \| 'nearest'` | `'center'` | Vertical scroll position |
+| `shineClass` | `string` | `'error-shine'` | CSS class for highlight effect |
+| `shineDuration` | `number` | `2500` | Duration in ms to keep the shine class. Use `0` to disable |
+| `focus` | `boolean` | `true` | Whether to attempt focusing the first focusable element |
+| `focusDelay` | `number` | `300` | Delay in ms before focus attempt |
+| `scrollContainer` | `string \| HTMLElement \| null` | — | Scroll container for forms inside modals/drawers. When provided, scrolls this container instead of the viewport |
+| `announce` | `boolean \| string` | `true` | Screen reader announcement. `true` = default message, `string` = custom message, `false` = no announcement |
+| `scrollOffset` | `{ top?: number; left?: number }` | — | Offset in pixels for fixed headers (e.g. `{ top: 80 }`) |
+
+### UseScrollToErrorOptions (composable-level)
+
+When creating the composable, you can pass default options applied to every call:
+
+```typescript
+useScrollToError({
+  defaultOptions: {
+    scrollContainer: "[data-dialog-body]",
+    shineClass: "my-app-error",
+  },
+});
+```
+
+Call-time options override these defaults.
+
+## Examples
+
+### With Custom Options
+
+```vue
+<script setup lang="ts">
+import { useScrollToError } from "@baklavue/composables";
+
+const { scrollToError } = useScrollToError();
+
+scrollToError('[data-field="tags"]', {
+  shineClass: "my-shine",
+  shineDuration: 1500,
+  focusDelay: 500,
+});
+</script>
+```
+
+### With Default Options (for modals)
+
+```vue
+<script setup lang="ts">
+import { useScrollToError } from "@baklavue/composables";
+
+const { scrollToError } = useScrollToError({
+  defaultOptions: {
+    scrollContainer: "[data-dialog-body]",
+    announce: "Form has errors. Please fix the highlighted field.",
+  },
+});
+
+scrollToError('[data-field="tags"]');
+</script>
+```
+
+### Form in Modal with Scroll Container
+
+```vue
+<template>
+  <BvDialog v-model:open="isOpen">
+    <div data-dialog-body class="dialog-body">
+      <form @submit.prevent="handleSubmit">
+        <div data-field="email">
+          <input v-model="email" />
+        </div>
+      </form>
+    </div>
+  </BvDialog>
+</template>
+
+<script setup lang="ts">
+import { useScrollToError } from "@baklavue/composables";
+
+const { scrollToError } = useScrollToError({
+  defaultOptions: { scrollContainer: "[data-dialog-body]" },
+});
+
+const handleSubmit = () => {
+  if (hasError) {
+    scrollToError('[data-field="email"]');
+  }
+};
+</script>
+```
+
+### With Fixed Header Offset
+
+```vue
+<script setup lang="ts">
+import { useScrollToError } from "@baklavue/composables";
+
+const { scrollToError } = useScrollToError();
+
+scrollToError('[data-field="tags"]', {
+  scrollOffset: { top: 80 },
+});
+</script>
+```
+
+### Without Shine Effect
+
+```vue
+<script setup lang="ts">
+import { useScrollToError } from "@baklavue/composables";
+
+const { scrollToError } = useScrollToError();
+
+scrollToError('[data-field="tags"]', {
+  shineDuration: 0,
+});
+</script>
+```
+
+### Without Focus
+
+```vue
+<script setup lang="ts">
+import { useScrollToError } from "@baklavue/composables";
+
+const { scrollToError } = useScrollToError();
+
+scrollToError('[data-field="tags"]', {
+  focus: false,
+});
+</script>
+```
+
+### Without Screen Reader Announcement
+
+```vue
+<script setup lang="ts">
+import { useScrollToError } from "@baklavue/composables";
+
+const { scrollToError } = useScrollToError();
+
+scrollToError('[data-field="tags"]', {
+  announce: false,
+});
+</script>
+```
+
+### Using Return Value
+
+```vue
+<script setup lang="ts">
+import { useScrollToError } from "@baklavue/composables";
+
+const { scrollToError } = useScrollToError();
+
+const handleSubmit = () => {
+  const result = scrollToError('[data-field="tags"]');
+  if (!result.success) {
+    console.warn("Could not scroll to error field");
+  }
+};
+</script>
+```
+
+## CSS for Shine Effect
+
+The composable uses `error-shine` by default. Define this class in your styles for the highlight effect:
+
+```css
+.error-shine {
+  animation: error-shine 2.5s ease-in-out;
+}
+
+@keyframes error-shine {
+  0%,
+  100% {
+    box-shadow: none;
+  }
+  50% {
+    box-shadow: 0 0 0 2px var(--bl-color-danger);
+  }
+}
+```
+
+## TypeScript Support
+
+```typescript
+import {
+  useScrollToError,
+  type ScrollToErrorOptions,
+  type ScrollToErrorResult,
+  type ScrollToErrorTarget,
+  type UseScrollToErrorOptions,
+} from "@baklavue/composables";
+
+const { scrollToError } = useScrollToError();
+
+// scrollToError accepts string, HTMLElement, or { scrollTarget: string }
+const result = scrollToError('[data-field="tags"]');
+// result.success: boolean
+
+scrollToError(document.getElementById("field"));
+scrollToError({ scrollTarget: '[data-field="tags"]' });
+```

package/dist/docs/composables/scrollVisibility.md

@@ -0,0 +1,60 @@
+# useScrollVisibility
+
+A composable for scroll-based visibility. Detects when scroll position exceeds a threshold. RAF-throttled for performance. Use with BvScrollToTop or custom scroll-to-top and sticky UI.
+
+## Basic Usage
+
+```vue
+<template>
+  <div>
+    <BvButton v-if="isVisible" @click="scrollToTop">Scroll to top</BvButton>
+  </div>
+</template>
+
+<script setup>
+import { BvButton } from "@baklavue/ui";
+import { useScrollVisibility } from "@baklavue/composables";
+
+const { isVisible, scrollY, scrollToTop } = useScrollVisibility({ threshold: 300 });
+</script>
+```
+
+## Custom Threshold
+
+```vue
+<script setup>
+import { useScrollVisibility } from "@baklavue/composables";
+
+const { isVisible } = useScrollVisibility({ threshold: 500 });
+// isVisible is true when user scrolls past 500px
+</script>
+```
+
+## API
+
+### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `isVisible` | `Ref<boolean>` | True when scroll exceeds threshold |
+| `scrollY` | `Ref<number>` | Current scroll position |
+| `scrollToTop` | `() => void` | Smooth scroll to top |
+
+### Options
+
+```typescript
+interface UseScrollVisibilityOptions {
+  threshold?: number; // pixels (default: 300)
+}
+```
+
+## TypeScript Support
+
+```typescript
+import {
+  useScrollVisibility,
+  type UseScrollVisibilityOptions,
+} from "@baklavue/composables";
+
+const { isVisible, scrollToTop } = useScrollVisibility({ threshold: 400 });
+```

package/dist/docs/composables/share.md

@@ -0,0 +1,78 @@
+# useShare
+
+A composable for the Web Share API. Share text, URLs, or files via native share sheet (mobile) or fallback. Pairs with `useClipboard` when share is unavailable.
+
+## Basic Usage
+
+```vue
+<template>
+  <BvButton v-if="isSupported" @click="handleShare">Share</BvButton>
+</template>
+
+<script setup>
+import { BvButton } from "@baklavue/ui";
+import { useShare, useNotification } from "@baklavue/composables";
+
+const { share, isSupported } = useShare();
+const { success } = useNotification();
+
+const handleShare = async () => {
+  const ok = await share({ title: "Report", url: "https://example.com/report" });
+  if (ok) success({ description: "Shared!" });
+};
+</script>
+```
+
+## With Default Data
+
+```vue
+<script setup>
+import { useShare, useNotification } from "@baklavue/composables";
+
+const { success } = useNotification();
+const { share, isSupported } = useShare({
+  data: { title: "Check this out", url: window.location.href },
+  onSuccess: () => success({ description: "Shared!" }),
+});
+
+await share(); // uses default data
+</script>
+```
+
+## API
+
+### Options
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `data` | `ShareData` | Default data to share when `share()` is called without arguments |
+| `onSuccess` | `() => void` | Callback when share succeeds |
+| `onError` | `(error?: Error) => void` | Callback when share fails or is aborted |
+
+### ShareData
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `title` | `string` | Title of the shared content |
+| `text` | `string` | Text to share |
+| `url` | `string` | URL to share |
+| `files` | `File[]` | Files to share (when supported) |
+
+### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `share` | `(data?: ShareData) => Promise<boolean>` | Share data. Uses default when called without args. |
+| `isSupported` | `ComputedRef<boolean>` | Whether Web Share API is available |
+| `canShare` | `ComputedRef<boolean>` | Whether the current data can be shared |
+| `shared` | `Ref<boolean>` | True after successful share |
+| `error` | `Ref<Error \| null>` | Last error if share failed |
+
+## TypeScript Support
+
+```typescript
+import { useShare, type ShareData, type UseShareOptions } from "@baklavue/composables";
+
+const { share, isSupported } = useShare();
+await share({ title: "Report", url: "https://example.com" });
+```

package/dist/docs/composables/slug.md

@@ -0,0 +1,58 @@
+# useSlug
+
+A composable for converting a string to a URL-friendly slug. Useful for SEO-friendly URLs, filenames, and unique keys.
+
+## Basic Usage
+
+```vue
+<script setup>
+import { ref } from "vue";
+import { useSlug } from "@baklavue/composables";
+
+const title = ref("Hello World!");
+const slug = useSlug(title);
+// slug: "hello-world"
+</script>
+```
+
+## With Options
+
+```vue
+<script setup>
+import { useSlug } from "@baklavue/composables";
+
+const slug = useSlug("My Project Name", { separator: "_" });
+// slug: "my_project_name"
+</script>
+```
+
+## API
+
+### Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `separator` | `string` | `"-"` | Character to replace spaces/special chars |
+| `lowercase` | `boolean` | `true` | Lowercase the result |
+
+### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| (return) | `ComputedRef<string>` | URL-friendly slug |
+
+### Behavior
+
+- Trims whitespace
+- Normalizes Unicode (NFD) and removes diacritics
+- Replaces non-word chars with separator
+- Collapses multiple separators
+- Trims leading/trailing separators
+
+## TypeScript Support
+
+```typescript
+import { useSlug, type UseSlugOptions } from "@baklavue/composables";
+
+const slug = useSlug(titleRef, { separator: "_", lowercase: false });
+```

package/dist/docs/composables/stepper.md

@@ -0,0 +1,117 @@
+# useStepper
+
+A composable for multi-step flow state. Use with BvStepper for wizards and form flows.
+
+## Basic Usage
+
+```vue
+<template>
+  <div>
+    <BvStepper v-model:current-step="currentStep" :steps="steps" />
+    <div>
+      <BvButton v-if="!isFirst" @click="prev">Previous</BvButton>
+      <BvButton v-if="!isLast" @click="next">Next</BvButton>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { BvButton, BvStepper } from "@baklavue/ui";
+import { useStepper } from "@baklavue/composables";
+
+const {
+  currentStep,
+  steps,
+  next,
+  prev,
+  isFirst,
+  isLast,
+} = useStepper({
+  steps: [
+    { label: "Details" },
+    { label: "Review" },
+    { label: "Confirm" },
+  ],
+});
+</script>
+```
+
+## With Step Validation
+
+```vue
+<script setup>
+import { useStepper } from "@baklavue/composables";
+
+const {
+  currentStep,
+  steps,
+  next,
+  setStepError,
+} = useStepper({
+  steps: [
+    { label: "Details" },
+    { label: "Review" },
+  ],
+});
+
+const validateAndNext = () => {
+  const valid = validateCurrentStep();
+  if (!valid) {
+    setStepError(currentStep.value, true);
+  } else {
+    setStepError(currentStep.value, false);
+    next();
+  }
+};
+</script>
+```
+
+## API
+
+### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `currentStep` | `Ref<number>` | Current step index (0-based) |
+| `steps` | `Ref<StepperStep[]>` | Step configurations |
+| `next` | `() => void` | Go to next step |
+| `prev` | `() => void` | Go to previous step |
+| `goTo` | `(index: number) => void` | Go to specific step |
+| `setStepError` | `(index: number, hasError: boolean) => void` | Set error state for step |
+| `isFirst` | `ComputedRef<boolean>` | True on first step |
+| `isLast` | `ComputedRef<boolean>` | True on last step |
+| `canGoNext` | `ComputedRef<boolean>` | True if can advance |
+| `canGoPrev` | `ComputedRef<boolean>` | True if can go back |
+| `stepVariant` | `(index: number) => StepVariant` | Get variant for step (default, active, success, error) |
+| `totalSteps` | `ComputedRef<number>` | Total number of steps |
+
+### Options
+
+```typescript
+interface UseStepperOptions {
+  steps: StepperStep[];
+  initialStep?: number; // default: 0
+}
+
+interface StepperStep {
+  label: string;
+  description?: string;
+  completed?: boolean;
+  error?: boolean;
+  disabled?: boolean;
+}
+```
+
+## TypeScript Support
+
+```typescript
+import {
+  useStepper,
+  type UseStepperOptions,
+  type StepperStep,
+} from "@baklavue/composables";
+
+const { currentStep, next } = useStepper({
+  steps: [{ label: "Step 1" }, { label: "Step 2" }],
+});
+```

package/dist/docs/composables/stepperForm.md

@@ -0,0 +1,74 @@
+# useStepperForm
+
+A composable for multi-step form flows with per-step validation. Use with [useStepper](/composables/stepper) and [useZodForm](/composables/formValidation) to validate before advancing to the next step.
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { useStepper, useStepperForm } from "@baklavue/composables";
+import { useZodForm } from "@baklavue/composables";
+import { ref } from "vue";
+import { z } from "zod";
+
+const form = ref({ email: "", name: "", address: "" });
+const schema = z.object({
+  email: z.string().email(),
+  name: z.string().min(1),
+  address: z.string().min(1),
+});
+
+const stepper = useStepper({
+  steps: [{ label: "Contact" }, { label: "Address" }],
+});
+
+const formValidation = useZodForm(schema, form);
+const { nextWithValidation, hasStepError } = useStepperForm(stepper, {
+  stepFields: (i) => (i === 0 ? ["email", "name"] : ["address"]),
+});
+
+const onNext = () => nextWithValidation(formValidation.validate);
+</script>
+
+<template>
+  <BvStepper v-model:current-step="stepper.currentStep" :steps="stepper.steps" />
+  <form @submit.prevent="onNext">
+    <!-- Step 0: email, name -->
+    <template v-if="stepper.currentStep.value === 0">
+      <BvInput v-model="form.email" :invalid-text="formValidation.getError('email')" />
+      <BvInput v-model="form.name" :invalid-text="formValidation.getError('name')" />
+    </template>
+    <!-- Step 1: address -->
+    <template v-else>
+      <BvInput v-model="form.address" :invalid-text="formValidation.getError('address')" />
+    </template>
+    <BvButton type="submit">Next</BvButton>
+  </form>
+</template>
+```
+
+## API
+
+### Parameters
+
+```typescript
+useStepperForm(stepper, options?)
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `stepper` | `StepperLike` | Return value from useStepper |
+| `options` | `UseStepperFormOptions` | Optional: `{ stepFields?: (stepIndex) => string[] }` |
+
+### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `hasStepError` | `() => boolean` | Whether the current step has validation errors |
+| `nextWithValidation` | `(validate: () => Promise<FormErrors \| null>) => Promise<boolean>` | Validates, advances if valid, sets step error if invalid. Returns `true` if advanced |
+
+### stepFields
+
+When provided, `stepFields(stepIndex)` returns the field paths for that step. Validation errors are filtered to these paths to determine if the current step has errors. If omitted, any validation error marks the current step as having an error.
+
+This is useful when you have a single schema for the whole form but want to show step-specific error indicators on the stepper.