@baklavue/mcp 1.0.0

package/dist/docs/composables/file.md

@@ -0,0 +1,343 @@
+# useFile
+
+A composable for file parsing, creating, and downloading. Supports CSV, TSV, JSON, and Excel (.xlsx, .xls) formats with streaming, Zod validation, transforms, and preview. Accepts `File` or `Blob` for `parseFile`, `preview`, and `parseStream`. Uses PapaParse for RFC 4180-compliant CSV/TSV and SheetJS for Excel.
+
+## Basic Usage
+
+### Parse String
+
+```vue
+<script setup lang="ts">
+import { useFile } from "@baklavue/composables";
+
+const { parse } = useFile();
+
+const result = parse("name,age\nAlice,30\nBob,25", { format: "csv", header: true });
+console.log(result.data); // [{ name: "Alice", age: "30" }, { name: "Bob", age: "25" }]
+</script>
+```
+
+### Parse File
+
+```vue
+<template>
+  <input type="file" accept=".csv,.tsv,.json,.xlsx,.xls" @change="handleFileUpload" />
+</template>
+
+<script setup lang="ts">
+import { useFile } from "@baklavue/composables";
+
+const { parseFile } = useFile();
+
+const handleFileUpload = async (event: Event) => {
+  const file = (event.target as HTMLInputElement).files?.[0];
+  if (file) {
+    const result = await parseFile(file, { header: true });
+    console.log(result.data);
+  }
+};
+</script>
+```
+
+### Create CSV
+
+```vue
+<script setup lang="ts">
+import { useFile } from "@baklavue/composables";
+
+const { create } = useFile();
+
+const csv = create([
+  { name: "Alice", age: 30 },
+  { name: "Bob", age: 25 },
+]);
+// Result: "name,age\nAlice,30\nBob,25"
+</script>
+```
+
+### Download CSV
+
+```vue
+<template>
+  <button @click="exportData">Export CSV</button>
+</template>
+
+<script setup lang="ts">
+import { useFile } from "@baklavue/composables";
+
+const { download } = useFile();
+
+const data = [
+  { name: "Alice", age: 30 },
+  { name: "Bob", age: 25 },
+];
+
+const exportData = () => {
+  download(data, "export.csv");
+};
+</script>
+```
+
+## Supported Formats
+
+| Format | Parse | Create | Notes |
+| --- | --- | --- | --- |
+| CSV | Yes | Yes | RFC 4180, PapaParse |
+| TSV | Yes | Yes | Tab-delimited, PapaParse |
+| JSON | Yes | Yes | Built-in `JSON.parse` / `JSON.stringify` |
+| Excel (.xlsx, .xls) | Yes | Yes | SheetJS; parse via `parseFile` only (binary format) |
+
+Format is auto-detected from file extension when using `parseFile` or `preview`. For `Blob` (without filename), format is inferred from `blob.type` when possible; otherwise specify `format` in options.
+
+**Limitations:** `parse()` and `parseStream` do not support Excel; use `parseFile()` instead.
+
+## Methods
+
+### parse
+
+Parses a string synchronously. Returns `{ data, errors, meta }` (and `validationError` if Zod schema fails).
+
+```typescript
+parse<T>(content: string, options?: FileParseOptions<T>): ParseResult<T> & { validationError?: z.ZodError }
+```
+
+### parseFile
+
+Parses a File or Blob asynchronously. Format auto-detected from filename (File) or `blob.type` (Blob) when omitted.
+
+```typescript
+parseFile<T>(file: File | Blob, options?: FileParseOptions<T>): Promise<ParseResult<T> & { validationError?: z.ZodError }>
+```
+
+### parseStream
+
+Chunked parsing for large CSV/TSV files. Use `step` or `chunk` callbacks. Returns `{ abort }` to stop parsing. Does not support Excel; throws if format is xlsx/xls.
+
+```typescript
+parseStream(file: File | Blob, options: {
+  format?: "csv" | "tsv";
+  step?: (result: ParseResult<unknown>, parser: Parser) => void;
+  chunk?: (result: ParseResult<unknown>, parser: Parser) => void;
+  transform?: (row: unknown) => unknown | null;
+  complete?: () => void;
+  error?: (err: Error) => void;
+  // ...header, dynamicTyping, skipEmptyLines
+}): { abort: () => void }
+```
+
+### preview
+
+Parses only the first N rows. Useful for quick inspection of large files.
+
+```typescript
+preview<T>(file: File | Blob, options?: { rows?: number; format?: FileFormat; ... }): Promise<PreviewResult<T>>
+```
+
+### create
+
+Creates a string from data. Supports CSV, TSV, JSON, and Excel (returns base64 for Excel).
+
+```typescript
+create(data: FileData, options?: FileCreateOptions): string
+```
+
+### download
+
+Creates a string and triggers a browser download. Adds UTF-8 BOM for CSV/TSV (Excel compatibility).
+
+```typescript
+download(data: FileData, filename?: string, options?: FileCreateOptions): void
+```
+
+## Options
+
+### FileParseOptions
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `format` | `'csv' \| 'tsv' \| 'json' \| 'xlsx' \| 'xls'` | `'csv'` | File format |
+| `delimiter` | `string` | auto (CSV) or `\t` (TSV) | Delimiter character |
+| `header` | `boolean` | `false` | First row is header (returns array of objects) |
+| `dynamicTyping` | `boolean` | `false` | Convert numbers and booleans to their types |
+| `skipEmptyLines` | `boolean \| "greedy"` | `false` | Skip empty lines |
+| `schema` | `z.ZodType` | — | Zod schema for validation |
+| `transform` | `(row) => row \| null` | — | Transform each row; return `null` to skip |
+
+### FileCreateOptions
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `format` | `'csv' \| 'tsv' \| 'json' \| 'xlsx' \| 'xls'` | `'csv'` | Output format |
+| `delimiter` | `string` | `","` or `"\t"` | Delimiter character |
+| `header` | `boolean` | `true` | Include header row |
+| `columns` | `string[]` | — | Column order for array of objects |
+| `escapeFormulae` | `boolean` | `false` | Escape leading `=`, `+`, `-`, `@` to prevent CSV injection |
+
+## FileData Types
+
+Accepted by `create` and `download`:
+
+- **Array of objects:** `Record<string, unknown>[]` — keys become header row
+- **Array of arrays:** `unknown[][]` — no header unless `header: true` with explicit `columns`
+- **Explicit fields + data:** `{ fields: string[]; data: unknown[][] }` — for custom column order
+
+## Examples
+
+### Multi-Format (JSON, TSV, Excel)
+
+```vue
+<script setup lang="ts">
+import { useFile } from "@baklavue/composables";
+
+const { parse, parseFile, create, download } = useFile();
+
+// Parse JSON
+const jsonResult = parse('[{"a":1},{"a":2}]', { format: "json" });
+
+// Parse TSV
+const tsvResult = parse("name\tage\nAlice\t30", { format: "tsv", header: true });
+
+// Parse Excel file (use parseFile, not parse)
+const excelResult = await parseFile(file, { format: "xlsx", header: true });
+
+// Create and download Excel
+const data = [{ name: "Alice", age: 30 }];
+download(data, "export.xlsx", { format: "xlsx" });
+</script>
+```
+
+### With Blob
+
+```vue
+<script setup lang="ts">
+import { useFile } from "@baklavue/composables";
+
+const { parseFile } = useFile();
+
+// Parse from Blob (e.g. from fetch response)
+const response = await fetch("/api/export.csv");
+const blob = await response.blob();
+const result = await parseFile(blob, { format: "csv", header: true });
+</script>
+```
+
+### With Zod Validation
+
+```vue
+<script setup lang="ts">
+import { useFile } from "@baklavue/composables";
+import { z } from "zod";
+
+const schema = z.array(z.object({ name: z.string(), age: z.number() }));
+const { parseFile } = useFile();
+
+const result = await parseFile(file, {
+  format: "csv",
+  header: true,
+  dynamicTyping: true,
+  schema,
+});
+
+if (result.validationError) {
+  console.error("Validation failed:", result.validationError);
+} else {
+  console.log(result.data); // Typed as { name: string; age: number }[]
+}
+</script>
+```
+
+### With Transform
+
+```vue
+<script setup lang="ts">
+import { useFile } from "@baklavue/composables";
+
+const { parse } = useFile();
+
+const result = parse("name,age\nAlice,30\nBob,25", {
+  format: "csv",
+  header: true,
+  dynamicTyping: true,
+  transform: (row) => {
+    const r = row as { age: number };
+    return r.age >= 18 ? { ...r, adult: true } : null;
+  },
+});
+// Only rows with age >= 18, with adult: true added
+</script>
+```
+
+### Preview First Rows
+
+```vue
+<script setup lang="ts">
+import { useFile } from "@baklavue/composables";
+
+const { preview } = useFile();
+
+const { data, truncated } = await preview(file, { rows: 10 });
+console.log("First 10 rows:", data);
+if (truncated) console.log("File has more rows");
+</script>
+```
+
+### Streaming Large Files
+
+```vue
+<script setup lang="ts">
+import { useFile } from "@baklavue/composables";
+
+const { parseStream } = useFile();
+
+const { abort } = parseStream(file, {
+  format: "csv",
+  header: true,
+  step: (result, parser) => {
+    const row = result.data?.[0];
+    if (row) processRow(row);
+  },
+  complete: () => console.log("Done"),
+});
+
+// Call abort() to stop parsing
+</script>
+```
+
+### With Formulae Escaping
+
+```vue
+<script setup lang="ts">
+import { useFile } from "@baklavue/composables";
+
+const { download } = useFile();
+
+download(
+  [{ formula: "=SUM(A1:A10)", value: 100 }],
+  "export.csv",
+  { escapeFormulae: true }
+);
+</script>
+```
+
+## TypeScript Support
+
+```typescript
+import {
+  useFile,
+  type FileData,
+  type FileParseOptions,
+  type FileCreateOptions,
+  type ParseResult,
+  type ParseError,
+  type ParseMeta,
+  type PreviewResult,
+} from "@baklavue/composables";
+
+const { parse, parseFile, create, download } = useFile();
+
+// Typed parse
+const result = parse<{ name: string; age: number }>(
+  "name,age\nAlice,30",
+  { format: "csv", header: true, dynamicTyping: true }
+);
+```

package/dist/docs/composables/focusTrap.md

@@ -0,0 +1,87 @@
+# useFocusTrap
+
+A composable for trapping focus within a container (e.g. modals, dialogs). Tab cycles to next focusable element; Shift+Tab to previous. Prevents focus from escaping.
+
+## Basic Usage
+
+```vue
+<template>
+  <BvDialog v-model:open="isOpen" caption="Dialog">
+    <div ref="dialogContentRef">
+      <p>Tab cycles within this dialog.</p>
+      <BvButton @click="close">Cancel</BvButton>
+      <BvButton variant="primary">Confirm</BvButton>
+    </div>
+  </BvDialog>
+</template>
+
+<script setup>
+import { ref, watch } from "vue";
+import { BvButton, BvDialog } from "@baklavue/ui";
+import { useFocusTrap } from "@baklavue/composables";
+
+const dialogContentRef = ref(null);
+const isOpen = ref(false);
+
+const { activate, deactivate } = useFocusTrap({
+  target: dialogContentRef,
+  active: isOpen,
+});
+
+watch(isOpen, (open) => {
+  if (open) activate();
+  else deactivate();
+});
+</script>
+```
+
+## Manual Activation
+
+```vue
+<script setup>
+import { ref } from "vue";
+import { useFocusTrap } from "@baklavue/composables";
+
+const containerRef = ref(null);
+const { activate, deactivate, focusFirst, focusLast } = useFocusTrap({
+  target: containerRef,
+  initialFocus: true,
+});
+
+onMounted(() => {
+  activate();
+});
+</script>
+```
+
+## API
+
+### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `activate` | `() => void` | Start trapping focus |
+| `deactivate` | `() => void` | Stop trapping focus |
+| `focusFirst` | `() => void` | Focus first focusable element |
+| `focusLast` | `() => void` | Focus last focusable element |
+
+### Options
+
+```typescript
+interface UseFocusTrapOptions {
+  target: Ref<HTMLElement | null>; // Container element
+  active?: Ref<boolean> | boolean; // Whether trap is active (default: true)
+  initialFocus?: boolean; // Focus first element when activated (default: true)
+}
+```
+
+## TypeScript Support
+
+```typescript
+import { useFocusTrap, type UseFocusTrapOptions } from "@baklavue/composables";
+
+const { activate } = useFocusTrap({
+  target: dialogRef,
+  active: isOpen,
+});
+```

package/dist/docs/composables/formPersistence.md

@@ -0,0 +1,69 @@
+# useFormPersistence
+
+A composable for auto-saving form data to `localStorage` or `sessionStorage`. Useful for long forms, drafts, or preventing data loss on accidental navigation.
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { useFormPersistence } from "@baklavue/composables";
+import { ref } from "vue";
+
+const form = ref({ email: "", message: "" });
+useFormPersistence("contact-draft", form);
+</script>
+```
+
+Form data is automatically saved when the user types. On page load, if a draft exists in storage, it is restored.
+
+## API
+
+### Parameters
+
+```typescript
+useFormPersistence(key, data, options?)
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `key` | `string` | Storage key |
+| `data` | `Ref<T> \| Reactive<T> \| () => T` | Form data (ref, reactive, or getter) |
+| `options` | `UseFormPersistenceOptions` | Optional: `{ storage?: 'localStorage' \| 'sessionStorage', debounce?: number }` |
+
+### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `clear` | `() => void` | Remove persisted data from storage |
+
+### Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `storage` | `'localStorage' \| 'sessionStorage'` | `'localStorage'` | Where to persist |
+| `debounce` | `number` | `300` | Debounce writes in ms. Use `0` for immediate write |
+
+## Session vs Local Storage
+
+- **localStorage**: Persists across browser sessions. Use for drafts the user might return to later.
+- **sessionStorage**: Persists only for the current tab. Use for forms that should not persist after closing.
+
+```typescript
+useFormPersistence("wizard-draft", form, {
+  storage: "sessionStorage",
+  debounce: 500,
+});
+```
+
+## Clearing Draft
+
+Call `clear()` when the form is successfully submitted:
+
+```typescript
+const { clear } = useFormPersistence("contact-draft", form);
+
+const onSubmit = async () => {
+  await api.submit(form.value);
+  clear();
+};
+```

package/dist/docs/composables/formState.md

@@ -0,0 +1,71 @@
+# useFormState
+
+A lightweight composable for form dirty and touched state without validation. Use with plain ref form data or alongside [useZodForm](/composables/formValidation) when you need state tracking without Zod.
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { useFormState } from "@baklavue/composables";
+import { ref } from "vue";
+
+const form = ref({ email: "", name: "" });
+const { isDirty, dirtyFields, touched, touchedFields, setFieldTouched, setFieldValue, reset } = useFormState(form);
+
+// Check before navigation
+const beforeUnload = () => {
+  if (isDirty.value) {
+    return "You have unsaved changes";
+  }
+};
+</script>
+```
+
+## API
+
+### Parameters
+
+```typescript
+useFormState(data, options?)
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `data` | `Ref<T> \| Reactive<T> \| () => T` | Form data (ref, reactive, or getter) |
+| `options` | `UseFormStateOptions` | Optional: `{ initialValues?: Ref \| () => T }` |
+
+### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `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 |
+| `setFieldValue` | `(path: string, value: unknown) => void` | Programmatically set a field value |
+| `reset` | `(initialValues?: unknown) => void` | Reset touched state and optionally form data |
+| `initialValues` | `Ref<unknown>` | Snapshot of initial values |
+
+## Unsaved Changes Warning
+
+```typescript
+const { isDirty } = useFormState(form);
+
+onBeforeRouteLeave((_to, _from, next) => {
+  if (isDirty.value) {
+    showConfirmDialog({
+      title: "Unsaved changes",
+      message: "Leave without saving?",
+      onConfirm: () => next(),
+      onCancel: () => next(false),
+    });
+  } else {
+    next();
+  }
+});
+```
+
+## With useZodForm
+
+`useZodForm` already provides `isDirty`, `dirtyFields`, `touched`, and `touchedFields`. Use `useFormState` when you have a form without Zod validation but still need dirty/touched tracking.