@baklavue/composables 1.0.0-preview.1 → 1.0.0-preview.3

package/CHANGELOG.md

@@ -1,3 +1,54 @@
+# [@baklavue/composables-v1.0.0-preview.3](https://github.com/erbilnas/baklavue/compare/@baklavue/composables-v1.0.0-preview.2...@baklavue/composables-v1.0.0-preview.3) (2026-02-12)
+
+
+### Features
+
+* add new composables ([8e5cb7e](https://github.com/erbilnas/baklavue/commit/8e5cb7eb49ed6079748d7e5e282a51042a6ee2af))
+* add new composables ([fe130be](https://github.com/erbilnas/baklavue/commit/fe130be0123821e5cae0d9330f2e6709753a40b9))
+* add query composable ([28101d0](https://github.com/erbilnas/baklavue/commit/28101d03b747a0b737f889e0310856c779699844))
+* add zod form validation composable ([839a77f](https://github.com/erbilnas/baklavue/commit/839a77f1c42077fd2bdcf3b374f53d819a5cfa6b))
+
+# [Unreleased]
+
+### Features
+
+* add useColorScheme composable - Light/dark/system color scheme with persistence
+* add useThemePreset composable - Persist Baklava theme preset across sessions
+* add useElementSize composable - Reactive element dimensions via ResizeObserver
+* add useWindowSize composable - Reactive viewport width and height
+* add useContainerScroll composable - Scroll position inside a scrollable container
+* add useSticky composable - Detect when sticky element is stuck
+* add useMutation composable - Mutations (POST/PUT/DELETE) with onSuccess, onError, onSettled
+* add refetchInterval and refetchIntervalInBackground to useQuery - Polling with optional pause when tab hidden
+* add useInfiniteQuery composable - Infinite scroll / cursor-based pagination
+* add prefetchQuery to useQueryClient - Preload data before navigation
+* add useLazyQuery composable - On-demand queries that fetch when execute() is called
+* add usePolling composable - Polling with fetch state for non-query scenarios
+* add useShare composable - Web Share API for sharing text, URLs, or files
+* add useBase64 composable - Convert Blob/File/ArrayBuffer/canvas to Base64
+* add usePrevious composable - Track previous value of a ref
+* add useToggle composable - Simple boolean toggle
+* add useDateFormat composable - Reactive locale-aware date formatting (Intl)
+* add useNumberFormat composable - Reactive locale-aware number/currency formatting (Intl)
+* add useSlug composable - Convert string to URL-friendly slug
+* add useAsyncState composable - Generic async state (loading, error, data)
+* rename csv.ts to file.ts and add useFile composable
+* add multi-format support (CSV, TSV, JSON) for parse, create, and download
+* add parseStream for chunked parsing of large CSV/TSV files
+* add preview for parsing first N rows without full load
+* add Zod schema validation option for parsed data
+* add transform hook for row-level transformation/filtering
+* add typed generics for parse, parseFile, and preview results
+* add Excel (.xlsx, .xls) support for parseFile, preview, create, and download
+* add Blob support for parseFile, preview, and parseStream (in addition to File)
+
+# [@baklavue/composables-v1.0.0-preview.2](https://github.com/erbilnas/baklavue/compare/@baklavue/composables-v1.0.0-preview.1...@baklavue/composables-v1.0.0-preview.2) (2026-02-11)
+
+
+### Features
+
+* add new composables ([49105ea](https://github.com/erbilnas/baklavue/commit/49105eaa106f1a5b888f9e3f9638ed9776b3d55b))
+
 # @baklavue/composables-v1.0.0-preview.1 (2026-02-11)
 
 

package/README.md

@@ -34,23 +34,23 @@ bun add @baklavue/composables
 
 ## 📚 Available Composables
 
-### `useCsv`
+### `useFile`
 
-A composable for CSV parsing, creating, and downloading. Uses PapaParse for RFC 4180-compliant handling of quoted fields, commas in values, and edge cases.
+A composable for file parsing, creating, and downloading. Supports CSV, TSV, and JSON formats with streaming, Zod validation, transforms, and preview. Uses PapaParse for RFC 4180-compliant CSV/TSV handling.
 
 #### Basic Usage
 
 ```vue
 <script setup lang="ts">
-import { useCsv } from "@baklavue/composables";
+import { useFile } from "@baklavue/composables";
 
-const { parse, parseFile, create, download } = useCsv();
+const { parse, parseFile, create, download } = useFile();
 
 // Parse CSV string
-const result = parse("name,age\nAlice,30\nBob,25", { header: true });
+const result = parse("name,age\nAlice,30\nBob,25", { format: "csv", header: true });
 console.log(result.data); // [{ name: "Alice", age: "30" }, ...]
 
-// Parse file (async)
+// Parse file (async), format auto-detected from filename
 const handleFileUpload = async (event: Event) => {
   const file = (event.target as HTMLInputElement).files?.[0];
   if (file) {
@@ -79,23 +79,31 @@ const exportData = () => {
 
 #### API Reference
 
-The `useCsv` composable returns an object with the following methods:
+The `useFile` composable returns an object with the following methods:
 
-##### `parse(csv: string, options?: CsvParseOptions)`
+##### `parse(content: string, options?: FileParseOptions<T>)`
 
-Parses a CSV string and returns `{ data, errors, meta }`. Synchronous.
+Parses a string (CSV, TSV, or JSON) and returns `{ data, errors, meta }`. Synchronous.
 
-##### `parseFile(file: File, options?: CsvParseOptions)`
+##### `parseFile(file: File, options?: FileParseOptions<T>)`
 
-Parses a File or Blob asynchronously. Returns `Promise<ParseResult>`.
+Parses a File asynchronously. Format auto-detected from filename when omitted.
 
-##### `create(data: CsvData, options?: CsvCreateOptions)`
+##### `parseStream(file: File, options)` 
 
-Creates a CSV string from an array of objects, array of arrays, or `{ fields, data }` object.
+Chunked parsing for large CSV/TSV files. Returns `{ abort }`. Use `step` or `chunk` callbacks.
 
-##### `download(data: CsvData, filename?: string, options?: CsvCreateOptions)`
+##### `preview(file: File, options?)`
 
-Creates a CSV string and triggers a browser download. Adds UTF-8 BOM for Excel compatibility.
+Parses only the first N rows. Returns `Promise<{ data, meta?, truncated }>`.
+
+##### `create(data: FileData, options?: FileCreateOptions)`
+
+Creates a string from an array of objects, array of arrays, or `{ fields, data }` object. Supports CSV, TSV, JSON.
+
+##### `download(data: FileData, filename?: string, options?: FileCreateOptions)`
+
+Creates a string and triggers a browser download. Adds UTF-8 BOM for CSV/TSV (Excel compatibility).
 
 #### Options
 
@@ -212,16 +220,172 @@ interface NotificationProps {
 - **Duration**: If no duration is specified, notifications will use Baklava's default duration
 - **Error Handling**: The composable includes built-in error handling and will warn if the notification element is not found
 
+### `useScrollToError`
+
+Scroll to an element with validation error. Scrolls into view, optionally applies a highlight effect, and focuses the first focusable control. Works with `input`, `select`, `textarea`, `bl-select`, `bl-input`.
+
+```ts
+const { scrollToError } = useScrollToError();
+scrollToError('[data-field="tags"]');
+scrollToError(validationError); // when error has scrollTarget
+```
+
+### `useBaklavaTheme`
+
+Overwrite Baklava design system colors and tokens. Use the Vue preset, pass a custom preset object, or override specific colors, border radius, size, typography, or z-index.
+
+```ts
+const { applyTheme } = useBaklavaTheme();
+applyTheme({ preset: 'vue' });
+applyTheme({ colors: { primary: '#41B883' } });
+```
+
+### `useDisclosure`
+
+Open/close state for Dialog, Drawer, Dropdown, Accordion, and Tooltip. Avoids repetitive `ref(false)`, `open()`, `close()`, `toggle()`.
+
+```ts
+const { isOpen, open, close, toggle } = useDisclosure(false);
+// Use with v-model:open on BvDialog, BvDrawer, BvDropdown
+```
+
+### `usePagination`
+
+Pagination state for tables and lists. Provides `currentPage`, `pageSize`, `totalItems`, `totalPages`, `offset`, `slice` helper.
+
+```ts
+const { currentPage, pageSize, totalItems, totalPages, setPage, setPageSize, slice } = usePagination({ totalItems: 100, pageSize: 10 });
+```
+
+### `useConfirmDialog`
+
+Drive BvDialog for confirm/cancel flows. Returns a promise that resolves to `true` when confirmed, `false` when cancelled.
+
+```ts
+const { confirm, isOpen, caption, description, handleConfirm, handleCancel } = useConfirmDialog();
+const ok = await confirm({ caption: "Delete?", description: "Sure?" });
+```
+
+### `useClipboard`
+
+Copy text to clipboard. Integrates well with `useNotification`.
+
+```ts
+const { copy, copied } = useClipboard();
+await copy("token");
+```
+
+### `useBreakpoints` / `useMediaQuery`
+
+Responsive breakpoints. `useBreakpoints` provides `isMobile`, `isTablet`, `isDesktop`. `useMediaQuery` for custom queries.
+
+```ts
+const { isMobile, isTablet, isDesktop } = useBreakpoints();
+const matches = useMediaQuery("(max-width: 768px)");
+```
+
+### `useLocalStorage` / `useSessionStorage`
+
+Reactive sync with `localStorage` and `sessionStorage`. Works well with `useBaklavaTheme` and `usePagination` for persisting preferences.
+
+```ts
+const pageSize = useLocalStorage("table-page-size", 10);
+const draft = useSessionStorage("form-draft", null);
+```
+
+### `useCookie`
+
+Reactive sync with `document.cookie`. Returns `{ value, get, set, remove }`. Use for auth tokens or when values must be sent to the server.
+
+```ts
+const { value: token, set, remove } = useCookie("auth-token", "", { path: "/", maxAge: 86400 });
+set("new-token");
+remove();
+```
+
+### `useDebounceFn` / `useDebouncedRef`
+
+Debounce function execution or ref value. `useDebounceFn` returns a debounced function. `useDebouncedRef` returns a ref that updates after the delay. Useful for search inputs, autocomplete.
+
+```ts
+const debouncedSearch = useDebounceFn((q: string) => fetchResults(q), 300);
+const searchQuery = ref("");
+const debouncedQuery = useDebouncedRef(searchQuery, 300);
+```
+
+### `useThrottleFn` / `useThrottledRef`
+
+Throttle function execution or ref value. Useful for scroll, resize, mousemove handlers.
+
+```ts
+const throttledHandler = useThrottleFn(() => updateScroll(), 100);
+const throttledScrollY = useThrottledRef(scrollY, 100);
+```
+
+### `useIntervalFn` / `useTimeoutFn`
+
+Pausable interval and cancellable timeout. `useIntervalFn` returns `{ pause, resume, isActive }`. `useTimeoutFn` returns `{ run, cancel, isPending }`.
+
+```ts
+const { pause, resume } = useIntervalFn(() => fetchData(), 5000);
+const { run, cancel } = useTimeoutFn(() => showToast("Saved!"), 2000);
+```
+
+### `useFetch`
+
+Reactive fetch with loading/error/data. Supports abort, timeout, and manual execute.
+
+```ts
+const { data, error, isFetching, execute } = useFetch<User>(
+  () => `https://api.example.com/users/${id.value}`,
+  { immediate: true }
+);
+```
+
+### `useIntersectionObserver`
+
+Detects when a target element enters or leaves the viewport. Useful for lazy loading, scroll-triggered animations.
+
+```ts
+const target = ref<HTMLElement | null>(null);
+const isVisible = useIntersectionObserver(target, { threshold: 0.5 });
+```
+
+### `useRafFn`
+
+Calls a function on every requestAnimationFrame. Returns `{ pause, resume, isActive }`. Useful for animation loops.
+
+```ts
+const { pause, resume } = useRafFn(({ delta }) => {
+  position.value += velocity * (delta / 1000);
+});
+```
+
 ## 🏗️ Project Structure
 
 ```
 packages/composables/
 ├── index.ts              # Main export file
-├── csv.ts                # CSV parsing, creating, and download composable
+├── file.ts               # File parsing, creating, download (CSV, TSV, JSON) composable
 ├── notification.ts       # Notification composable
+├── scrollToError.ts      # Scroll to validation error composable
+├── theme.ts              # Baklava theme composable
+├── disclosure.ts         # Open/close state composable
+├── pagination.ts         # Pagination state composable
+├── confirmDialog.ts      # Confirm dialog composable
+├── clipboard.ts          # Clipboard composable
+├── cookie.ts             # useCookie composable
+├── breakpoints.ts        # Responsive breakpoints composable
+├── storage.ts            # useLocalStorage, useSessionStorage composables
+├── debounce.ts           # useDebounceFn, useDebouncedRef
+├── throttle.ts           # useThrottleFn, useThrottledRef
+├── timer.ts              # useIntervalFn, useTimeoutFn
+├── fetch.ts              # useFetch composable
+├── intersectionObserver.ts  # useIntersectionObserver
+├── raf.ts                # useRafFn composable
 ├── package.json          # Package configuration
 ├── tsconfig.json         # TypeScript configuration
-└── README.md            # This file
+└── README.md             # This file
 ```
 
 ## 🔧 Development

package/alert.spec.ts

@@ -0,0 +1,71 @@
+import { mount } from "@vue/test-utils";
+import { defineComponent } from "vue";
+import { describe, expect, it } from "vitest";
+import { useAlert } from "./alert";
+
+function withSetup<T>(composable: () => T) {
+  let result: T;
+  const TestComponent = defineComponent({
+    setup() {
+      result = composable();
+      return () => null;
+    },
+  });
+  const wrapper = mount(TestComponent);
+  return { result: result!, wrapper };
+}
+
+describe("useAlert", () => {
+  it("returns initial state", () => {
+    const { result } = withSetup(() => useAlert());
+
+    expect(result.isVisible.value).toBe(false);
+    expect(result.variant.value).toBe("info");
+    expect(result.caption.value).toBe("");
+    expect(result.description.value).toBe("");
+    expect(result.closable.value).toBe(false);
+  });
+
+  it("show() sets isVisible and options", async () => {
+    const { result, wrapper } = withSetup(() => useAlert());
+
+    result.show({
+      variant: "success",
+      caption: "Title",
+      description: "Saved!",
+      closable: true,
+    });
+
+    await wrapper.vm.$nextTick();
+    expect(result.isVisible.value).toBe(true);
+    expect(result.variant.value).toBe("success");
+    expect(result.caption.value).toBe("Title");
+    expect(result.description.value).toBe("Saved!");
+    expect(result.closable.value).toBe(true);
+  });
+
+  it("show() uses defaults for omitted options", async () => {
+    const { result, wrapper } = withSetup(() => useAlert());
+
+    result.show();
+
+    await wrapper.vm.$nextTick();
+    expect(result.isVisible.value).toBe(true);
+    expect(result.variant.value).toBe("info");
+    expect(result.caption.value).toBe("");
+    expect(result.description.value).toBe("");
+    expect(result.closable.value).toBe(false);
+  });
+
+  it("hide() sets isVisible to false", async () => {
+    const { result, wrapper } = withSetup(() => useAlert());
+
+    result.show({ description: "Message" });
+    await wrapper.vm.$nextTick();
+    expect(result.isVisible.value).toBe(true);
+
+    result.hide();
+    await wrapper.vm.$nextTick();
+    expect(result.isVisible.value).toBe(false);
+  });
+});

package/alert.ts

@@ -0,0 +1,56 @@
+import { ref } from "vue";
+
+export type AlertVariant = "info" | "success" | "warning" | "danger";
+
+export interface UseAlertOptions {
+  variant?: AlertVariant;
+  caption?: string;
+  description?: string;
+  closable?: boolean;
+}
+
+/**
+ * Composable for programmatic show/hide of inline BvAlert.
+ * Use with v-if="isVisible" or :closed="!isVisible" on BvAlert.
+ *
+ * @example
+ * ```ts
+ * const { isVisible, variant, caption, description, show, hide } = useAlert();
+ *
+ * show({ variant: "success", description: "Saved!" });
+ * hide();
+ *
+ * <BvAlert v-if="isVisible" :variant="variant" :caption="caption" :description="description" closable @close="hide" />
+ * ```
+ *
+ * @returns Object with isVisible, variant, caption, description, closable, show, hide
+ */
+export function useAlert() {
+  const isVisible = ref(false);
+  const variant = ref<AlertVariant>("info");
+  const caption = ref("");
+  const description = ref("");
+  const closable = ref(false);
+
+  const show = (options: UseAlertOptions = {}) => {
+    variant.value = options.variant ?? "info";
+    caption.value = options.caption ?? "";
+    description.value = options.description ?? "";
+    closable.value = options.closable ?? false;
+    isVisible.value = true;
+  };
+
+  const hide = () => {
+    isVisible.value = false;
+  };
+
+  return {
+    isVisible,
+    variant,
+    caption,
+    description,
+    closable,
+    show,
+    hide,
+  };
+}

package/asyncState.spec.ts

@@ -0,0 +1,114 @@
+import { mount } from "@vue/test-utils";
+import { defineComponent } from "vue";
+import { describe, expect, it, vi } from "vitest";
+import { useAsyncState } from "./asyncState";
+
+function withSetup<T>(composable: () => T) {
+  let result: T;
+  const TestComponent = defineComponent({
+    setup() {
+      result = composable();
+      return () => null;
+    },
+  });
+  const wrapper = mount(TestComponent);
+  return { result: result!, wrapper };
+}
+
+describe("useAsyncState", () => {
+  it("returns initial state", () => {
+    const fn = vi.fn();
+    const { result } = withSetup(() => useAsyncState(fn));
+
+    expect(result.state.value).toBeUndefined();
+    expect(result.isLoading.value).toBe(false);
+    expect(result.error.value).toBeNull();
+  });
+
+  it("execute() runs async fn and updates state", async () => {
+    let resolveFn!: (value: number) => void;
+    const fn = vi.fn().mockReturnValue(
+      new Promise<number>((r) => {
+        resolveFn = r;
+      }),
+    );
+    const { result, wrapper } = withSetup(() => useAsyncState(fn));
+
+    const promise = result.execute();
+    await wrapper.vm.$nextTick();
+    expect(result.isLoading.value).toBe(true);
+
+    resolveFn(42);
+    const value = await promise;
+    await wrapper.vm.$nextTick();
+    expect(value).toBe(42);
+    expect(result.state.value).toBe(42);
+    expect(result.isLoading.value).toBe(false);
+    expect(result.error.value).toBeNull();
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("execute() sets error on rejection", async () => {
+    const err = new Error("Failed");
+    const fn = vi.fn().mockRejectedValue(err);
+    const { result, wrapper } = withSetup(() => useAsyncState(fn));
+
+    await expect(result.execute()).rejects.toThrow("Failed");
+    await wrapper.vm.$nextTick();
+    expect(result.error.value).toEqual(err);
+    expect(result.isLoading.value).toBe(false);
+  });
+
+  it("respects initialData option", () => {
+    const fn = vi.fn();
+    const { result } = withSetup(() =>
+      useAsyncState(fn, { initialData: "initial" }),
+    );
+
+    expect(result.state.value).toBe("initial");
+  });
+
+  it("calls onSuccess when fn resolves", async () => {
+    const onSuccess = vi.fn();
+    const fn = vi.fn().mockResolvedValue("data");
+    const { result } = withSetup(() =>
+      useAsyncState(fn, { onSuccess }),
+    );
+
+    await result.execute();
+    expect(onSuccess).toHaveBeenCalledWith("data");
+  });
+
+  it("calls onError when fn rejects", async () => {
+    const err = new Error("Error");
+    const onError = vi.fn();
+    const fn = vi.fn().mockRejectedValue(err);
+    const { result } = withSetup(() => useAsyncState(fn, { onError }));
+
+    await expect(result.execute()).rejects.toThrow("Error");
+    expect(onError).toHaveBeenCalledWith(err);
+  });
+
+  it("wraps non-Error thrown values in Error", async () => {
+    const fn = vi.fn().mockRejectedValue("string error");
+    const { result } = withSetup(() => useAsyncState(fn));
+
+    await expect(result.execute()).rejects.toThrow("string error");
+    expect(result.error.value).toBeInstanceOf(Error);
+    expect(result.error.value?.message).toBe("string error");
+  });
+
+  it("immediate: true executes on mount", async () => {
+    const fn = vi.fn().mockResolvedValue(1);
+    const { result, wrapper } = withSetup(() =>
+      useAsyncState(fn, { immediate: true }),
+    );
+
+    await wrapper.vm.$nextTick();
+    await new Promise((r) => setTimeout(r, 0));
+    await wrapper.vm.$nextTick();
+    expect(result.state.value).toBe(1);
+    expect(result.isLoading.value).toBe(false);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+});

package/asyncState.ts

@@ -0,0 +1,84 @@
+import { ref, shallowRef } from "vue";
+
+export interface UseAsyncStateOptions<T> {
+  /** Execute immediately on mount. Default: false */
+  immediate?: boolean;
+  /** Initial data value. Default: undefined */
+  initialData?: T;
+  /** Callback on success */
+  onSuccess?: (data: T) => void;
+  /** Callback on error */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * Composable for generic async state (loading, error, data) without fetch.
+ * Complements useFetch/useQuery for non-HTTP async (IndexedDB, Web Worker, custom logic).
+ *
+ * @example
+ * ```ts
+ * const { state, execute, isLoading, error } = useAsyncState(async () => {
+ *   const data = await readFromIndexedDB();
+ *   return data;
+ * });
+ *
+ * await execute();
+ * ```
+ *
+ * @example
+ * ```ts
+ * const { state, execute, isLoading } = useAsyncState(
+ *   () => fetchUser(userId),
+ *   { immediate: true, initialData: null }
+ * );
+ * ```
+ *
+ * @param asyncFn - Async function returning the data
+ * @param options - Optional: immediate, initialData, onSuccess, onError
+ * @returns state (data), execute, isLoading, error
+ */
+export function useAsyncState<T>(
+  asyncFn: () => Promise<T>,
+  options: UseAsyncStateOptions<T> = {},
+): {
+  state: ReturnType<typeof shallowRef<T | undefined>>;
+  execute: () => Promise<T>;
+  isLoading: ReturnType<typeof ref<boolean>>;
+  error: ReturnType<typeof ref<Error | null>>;
+} {
+  const { immediate = false, initialData, onSuccess, onError } = options;
+
+  const state = shallowRef<T | undefined>(initialData);
+  const isLoading = ref(false);
+  const error = ref<Error | null>(null);
+
+  const execute = async (): Promise<T> => {
+    isLoading.value = true;
+    error.value = null;
+
+    try {
+      const data = await asyncFn();
+      state.value = data;
+      onSuccess?.(data);
+      return data;
+    } catch (err) {
+      const e = err instanceof Error ? err : new Error(String(err));
+      error.value = e;
+      onError?.(e);
+      throw e;
+    } finally {
+      isLoading.value = false;
+    }
+  };
+
+  if (immediate) {
+    execute();
+  }
+
+  return {
+    state,
+    execute,
+    isLoading,
+    error,
+  };
+}