@mohasinac/appkit 2.1.3 → 2.2.0

package/dist/react/hooks/usePendingTable.js

@@ -0,0 +1,45 @@
+"use client";
+import { useMemo } from "react";
+import { usePendingFilters } from "./usePendingFilters";
+/**
+ * usePendingTable
+ *
+ * A thin wrapper around `usePendingFilters` that exposes a `pendingTable`
+ * object matching the `UrlTable` interface (`get`, `set`, `setMany`).
+ *
+ * Drop this into any listing view to replace the per-filter `useState` +
+ * `handleFilterApply` + `handleFilterClear` boilerplate.
+ *
+ * @example
+ * ```tsx
+ * const { pendingTable, filterActiveCount, onFilterApply, onFilterClear } =
+ *   usePendingTable(table, ['status', 'category', 'minPrice', 'maxPrice']);
+ *
+ * // Pass pendingTable directly to any *Filters component:
+ * filterContent={<ProductFilters table={pendingTable} showStatus />}
+ * filterActiveCount={filterActiveCount}
+ * onFilterApply={onFilterApply}
+ * onFilterClear={onFilterClear}
+ * ```
+ */
+export function usePendingTable(table, keys) {
+    const filters = usePendingFilters({ table, keys });
+    const pendingTable = useMemo(() => ({
+        get: (key) => filters.pending[key]?.[0] ?? "",
+        set: (key, value) => {
+            filters.set(key, value ? [value] : []);
+        },
+        setMany: (updates) => {
+            for (const [k, v] of Object.entries(updates)) {
+                filters.set(k, v ? [v] : []);
+            }
+        },
+    }), [filters.pending, filters.set]);
+    return {
+        pendingTable,
+        filterActiveCount: filters.appliedCount,
+        onFilterApply: filters.apply,
+        onFilterClear: filters.clear,
+        onFilterReset: filters.reset,
+    };
+}

package/dist/react/hooks/usePullToRefresh.d.ts

@@ -0,0 +1,38 @@
+import { RefObject } from "react";
+export interface UsePullToRefreshOptions {
+    /** Distance in px the user must pull before onRefresh triggers (default: 80) */
+    threshold?: number;
+}
+export interface UsePullToRefreshReturn {
+    /** Attach to the scrollable container element */
+    containerRef: RefObject<HTMLDivElement | null>;
+    /** `true` while the user is actively pulling */
+    isPulling: boolean;
+    /** Pull progress from 0 (not started) to 1 (threshold reached) */
+    progress: number;
+}
+/**
+ * usePullToRefresh Hook
+ *
+ * Attaches touch event listeners to `containerRef`.
+ * When the user overscrolls from the very top and pulls down past `threshold`,
+ * `onRefresh` is called. Progress (0–1) can be used to render a loading indicator.
+ *
+ * @param onRefresh - Async function called when pull threshold is reached
+ * @param options   - Configuration: `threshold` in px (default 80)
+ *
+ * @example
+ * ```tsx
+ * const { containerRef, isPulling, progress } = usePullToRefresh(async () => {
+ *   await refetchOrders();
+ * });
+ *
+ * return (
+ *   <div ref={containerRef} className="overflow-y-auto">
+ *     {isPulling && <PullIndicator progress={progress} />}
+ *     {…}
+ *   </div>
+ * );
+ * ```
+ */
+export declare function usePullToRefresh(onRefresh: () => Promise<void>, options?: UsePullToRefreshOptions): UsePullToRefreshReturn;

package/dist/react/hooks/usePullToRefresh.js

@@ -0,0 +1,82 @@
+"use client";
+import { useRef, useState, useCallback, useEffect } from "react";
+/**
+ * usePullToRefresh Hook
+ *
+ * Attaches touch event listeners to `containerRef`.
+ * When the user overscrolls from the very top and pulls down past `threshold`,
+ * `onRefresh` is called. Progress (0–1) can be used to render a loading indicator.
+ *
+ * @param onRefresh - Async function called when pull threshold is reached
+ * @param options   - Configuration: `threshold` in px (default 80)
+ *
+ * @example
+ * ```tsx
+ * const { containerRef, isPulling, progress } = usePullToRefresh(async () => {
+ *   await refetchOrders();
+ * });
+ *
+ * return (
+ *   <div ref={containerRef} className="overflow-y-auto">
+ *     {isPulling && <PullIndicator progress={progress} />}
+ *     {…}
+ *   </div>
+ * );
+ * ```
+ */
+export function usePullToRefresh(onRefresh, options = {}) {
+    const { threshold = 80 } = options;
+    const containerRef = useRef(null);
+    const [isPulling, setIsPulling] = useState(false);
+    const [progress, setProgress] = useState(0);
+    const startYRef = useRef(null);
+    const thresholdReachedRef = useRef(false);
+    const onRefreshRef = useRef(onRefresh);
+    useEffect(() => {
+        onRefreshRef.current = onRefresh;
+    }, [onRefresh]);
+    const handleTouchStart = useCallback((e) => {
+        const el = containerRef.current;
+        if (!el || el.scrollTop > 0)
+            return;
+        startYRef.current = e.touches[0].clientY;
+        thresholdReachedRef.current = false;
+    }, []);
+    const handleTouchMove = useCallback((e) => {
+        if (startYRef.current === null)
+            return;
+        const delta = e.touches[0].clientY - startYRef.current;
+        if (delta <= 0) {
+            setProgress(0);
+            setIsPulling(false);
+            return;
+        }
+        const prog = Math.min(delta / threshold, 1);
+        setProgress(prog);
+        setIsPulling(true);
+        thresholdReachedRef.current = prog >= 1;
+    }, [threshold]);
+    const handleTouchEnd = useCallback(async () => {
+        setIsPulling(false);
+        setProgress(0);
+        startYRef.current = null;
+        if (thresholdReachedRef.current) {
+            thresholdReachedRef.current = false;
+            await onRefreshRef.current();
+        }
+    }, []);
+    useEffect(() => {
+        const el = containerRef.current;
+        if (!el)
+            return;
+        el.addEventListener("touchstart", handleTouchStart, { passive: true });
+        el.addEventListener("touchmove", handleTouchMove, { passive: true });
+        el.addEventListener("touchend", handleTouchEnd);
+        return () => {
+            el.removeEventListener("touchstart", handleTouchStart);
+            el.removeEventListener("touchmove", handleTouchMove);
+            el.removeEventListener("touchend", handleTouchEnd);
+        };
+    }, [handleTouchStart, handleTouchMove, handleTouchEnd]);
+    return { containerRef, isPulling, progress };
+}

package/dist/react/hooks/useRealtimeEvent.d.ts

@@ -0,0 +1,53 @@
+import { type IClientRealtimeProvider } from "../../contracts/client-realtime";
+export declare const RealtimeEventType: {
+    readonly AUTH: "auth";
+    readonly PAYMENT: "payment";
+    readonly CHAT: "chat";
+    readonly BID: "bid";
+    readonly BULK: "bulk";
+};
+export type RealtimeEventType = (typeof RealtimeEventType)[keyof typeof RealtimeEventType];
+export declare const RealtimeEventStatus: {
+    readonly IDLE: "idle";
+    readonly SUBSCRIBING: "subscribing";
+    readonly PENDING: "pending";
+    readonly SUCCESS: "success";
+    readonly FAILED: "failed";
+    readonly TIMEOUT: "timeout";
+};
+export type RealtimeEventStatus = (typeof RealtimeEventStatus)[keyof typeof RealtimeEventStatus];
+export declare const RTDBPayloadStatus: {
+    readonly PENDING: "pending";
+    readonly SUCCESS: "success";
+    readonly FAILED: "failed";
+    readonly ERROR: "error";
+};
+export interface RTDBEventPayload {
+    status: (typeof RTDBPayloadStatus)[keyof typeof RTDBPayloadStatus];
+    error?: string;
+    [key: string]: unknown;
+}
+export interface RealtimeEventMessages {
+    tokenFailure?: string;
+    connectionLost?: string;
+    timedOut?: string;
+    failure?: string;
+}
+export interface UseRealtimeEventConfig<TData = undefined> {
+    type: RealtimeEventType;
+    rtdbPath: string;
+    /** Optional provider override. Falls back to the globally registered provider. */
+    realtimeProvider?: IClientRealtimeProvider;
+    timeoutMs?: number;
+    extractData?: (raw: RTDBEventPayload) => TData | null;
+    messages?: RealtimeEventMessages;
+    onLogError?: (message: string, error: unknown) => void;
+}
+export interface UseRealtimeEventReturn<TData = undefined> {
+    status: RealtimeEventStatus;
+    error: string | null;
+    data: TData | null;
+    subscribe: (eventId: string, customToken: string) => void;
+    reset: () => void;
+}
+export declare function useRealtimeEvent<TData = undefined>(config: UseRealtimeEventConfig<TData>): UseRealtimeEventReturn<TData>;

package/dist/react/hooks/useRealtimeEvent.js

@@ -0,0 +1,124 @@
+"use client";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { getClientRealtimeProvider, } from "../../contracts/client-realtime";
+export const RealtimeEventType = {
+    AUTH: "auth",
+    PAYMENT: "payment",
+    CHAT: "chat",
+    BID: "bid",
+    BULK: "bulk",
+};
+export const RealtimeEventStatus = {
+    IDLE: "idle",
+    SUBSCRIBING: "subscribing",
+    PENDING: "pending",
+    SUCCESS: "success",
+    FAILED: "failed",
+    TIMEOUT: "timeout",
+};
+export const RTDBPayloadStatus = {
+    PENDING: "pending",
+    SUCCESS: "success",
+    FAILED: "failed",
+    ERROR: "error",
+};
+const DEFAULT_TIMEOUT_MS = 3 * 60 * 1000;
+const DEFAULT_MESSAGES = {
+    tokenFailure: "Failed to initialize realtime tracking.",
+    connectionLost: "Realtime connection lost.",
+    timedOut: "Operation timed out.",
+    failure: "Operation failed.",
+};
+export function useRealtimeEvent(config) {
+    const configRef = useRef(config);
+    const [status, setStatus] = useState(RealtimeEventStatus.IDLE);
+    const [error, setError] = useState(null);
+    const [data, setData] = useState(null);
+    const unsubscribeRef = useRef(null);
+    const timeoutRef = useRef(null);
+    const eventIdRef = useRef(null);
+    const cleanup = useCallback(() => {
+        if (unsubscribeRef.current) {
+            unsubscribeRef.current();
+            unsubscribeRef.current = null;
+        }
+        if (timeoutRef.current) {
+            clearTimeout(timeoutRef.current);
+            timeoutRef.current = null;
+        }
+        const provider = configRef.current.realtimeProvider ?? getClientRealtimeProvider();
+        provider.signOut().catch(() => {
+            // no-op
+        });
+    }, []);
+    const subscribe = useCallback((eventId, customToken) => {
+        const { type, rtdbPath, realtimeProvider, timeoutMs = DEFAULT_TIMEOUT_MS, extractData, messages, onLogError, } = configRef.current;
+        const provider = realtimeProvider ?? getClientRealtimeProvider();
+        const msg = {
+            ...DEFAULT_MESSAGES,
+            ...(messages ?? {}),
+        };
+        cleanup();
+        eventIdRef.current = eventId;
+        setStatus(RealtimeEventStatus.SUBSCRIBING);
+        setError(null);
+        setData(null);
+        (async () => {
+            try {
+                await provider.signInWithToken(customToken);
+            }
+            catch (authErr) {
+                onLogError?.(`useRealtimeEvent[${type}]: custom token sign-in failed`, authErr);
+                setError(msg.tokenFailure);
+                setStatus(RealtimeEventStatus.FAILED);
+                cleanup();
+                return;
+            }
+            if (eventIdRef.current !== eventId) {
+                cleanup();
+                return;
+            }
+            setStatus(RealtimeEventStatus.PENDING);
+            unsubscribeRef.current = provider.subscribe(`${rtdbPath}/${eventId}`, (snapshot) => {
+                if (!snapshot.exists())
+                    return;
+                const raw = snapshot.val();
+                if (!raw)
+                    return;
+                if (raw.status === RTDBPayloadStatus.SUCCESS) {
+                    cleanup();
+                    if (extractData)
+                        setData(extractData(raw));
+                    setStatus(RealtimeEventStatus.SUCCESS);
+                }
+                else if (raw.status === RTDBPayloadStatus.FAILED ||
+                    raw.status === RTDBPayloadStatus.ERROR) {
+                    cleanup();
+                    setError(raw.error ?? msg.failure);
+                    setStatus(RealtimeEventStatus.FAILED);
+                }
+            }, (rtdbErr) => {
+                onLogError?.(`useRealtimeEvent[${type}]: RTDB subscription error`, rtdbErr);
+                cleanup();
+                setError(msg.connectionLost);
+                setStatus(RealtimeEventStatus.FAILED);
+            });
+            timeoutRef.current = setTimeout(() => {
+                cleanup();
+                setStatus(RealtimeEventStatus.TIMEOUT);
+                setError(msg.timedOut);
+            }, timeoutMs);
+        })();
+    }, [cleanup]);
+    const reset = useCallback(() => {
+        cleanup();
+        eventIdRef.current = null;
+        setStatus(RealtimeEventStatus.IDLE);
+        setError(null);
+        setData(null);
+    }, [cleanup]);
+    useEffect(() => () => {
+        cleanup();
+    }, [cleanup]);
+    return { status, error, data, subscribe, reset };
+}

package/dist/react/hooks/useSwipe.d.ts

@@ -0,0 +1,55 @@
+import "client-only";
+import { RefObject } from "react";
+/**
+ * Swipe direction types
+ */
+export type SwipeDirection = "left" | "right" | "up" | "down";
+/**
+ * Configuration options for useSwipe hook
+ */
+export interface UseSwipeOptions {
+    /** Minimum distance in pixels to register as a swipe (default: 50) */
+    minSwipeDistance?: number;
+    /** Maximum time in ms for a swipe gesture (default: 300) */
+    maxSwipeTime?: number;
+    /** Threshold for swipe velocity (pixels/ms, default: 0.3) */
+    velocityThreshold?: number;
+    /** Callback when swipe is detected */
+    onSwipe?: (direction: SwipeDirection, distance: number, velocity: number) => void;
+    /** Callback for specific directions */
+    onSwipeLeft?: (distance: number, velocity: number) => void;
+    onSwipeRight?: (distance: number, velocity: number) => void;
+    onSwipeUp?: (distance: number, velocity: number) => void;
+    onSwipeDown?: (distance: number, velocity: number) => void;
+    /** Callback during swipe (for dragging effect) */
+    onSwiping?: (deltaX: number, deltaY: number) => void;
+    /** Callback when swipe starts */
+    onSwipeStart?: () => void;
+    /** Callback when swipe ends (regardless of direction detected) */
+    onSwipeEnd?: () => void;
+    /** Prevent default behavior during touch */
+    preventDefault?: boolean;
+}
+/**
+ * useSwipe Hook
+ *
+ * Detects swipe gestures on touch and mouse events.
+ * Works on both mobile (touch) and desktop (mouse drag).
+ *
+ * @param ref - Reference to the element to attach swipe handlers
+ * @param options - Configuration options for swipe detection
+ *
+ * @example
+ * ```tsx
+ * const ref = useRef<HTMLDivElement>(null);
+ *
+ * useSwipe(ref, {
+ *   onSwipeLeft: () => console.log('Swiped left'),
+ *   onSwipeRight: () => console.log('Swiped right'),
+ *   minSwipeDistance: 100,
+ * });
+ *
+ * return <div ref={ref}>Swipe me!</div>;
+ * ```
+ */
+export declare function useSwipe<T extends HTMLElement = HTMLElement>(ref: RefObject<T | null>, options?: UseSwipeOptions): void;

package/dist/react/hooks/useSwipe.js

@@ -0,0 +1,165 @@
+"use client";
+import "client-only";
+import { useRef, useEffect } from "react";
+/**
+ * useSwipe Hook
+ *
+ * Detects swipe gestures on touch and mouse events.
+ * Works on both mobile (touch) and desktop (mouse drag).
+ *
+ * @param ref - Reference to the element to attach swipe handlers
+ * @param options - Configuration options for swipe detection
+ *
+ * @example
+ * ```tsx
+ * const ref = useRef<HTMLDivElement>(null);
+ *
+ * useSwipe(ref, {
+ *   onSwipeLeft: () => console.log('Swiped left'),
+ *   onSwipeRight: () => console.log('Swiped right'),
+ *   minSwipeDistance: 100,
+ * });
+ *
+ * return <div ref={ref}>Swipe me!</div>;
+ * ```
+ */
+export function useSwipe(ref, options = {}) {
+    const { minSwipeDistance = 50, maxSwipeTime = 300, velocityThreshold = 0.3, onSwipe, onSwipeLeft, onSwipeRight, onSwipeUp, onSwipeDown, onSwiping, onSwipeStart, onSwipeEnd, preventDefault = false, } = options;
+    const touchStartRef = useRef(null);
+    const isSwiping = useRef(false);
+    const onSwipeRef = useRef(onSwipe);
+    const onSwipeLeftRef = useRef(onSwipeLeft);
+    const onSwipeRightRef = useRef(onSwipeRight);
+    const onSwipeUpRef = useRef(onSwipeUp);
+    const onSwipeDownRef = useRef(onSwipeDown);
+    const onSwipingRef = useRef(onSwiping);
+    const onSwipeStartRef = useRef(onSwipeStart);
+    const onSwipeEndRef = useRef(onSwipeEnd);
+    useEffect(() => {
+        onSwipeRef.current = onSwipe;
+    }, [onSwipe]);
+    useEffect(() => {
+        onSwipeLeftRef.current = onSwipeLeft;
+    }, [onSwipeLeft]);
+    useEffect(() => {
+        onSwipeRightRef.current = onSwipeRight;
+    }, [onSwipeRight]);
+    useEffect(() => {
+        onSwipeUpRef.current = onSwipeUp;
+    }, [onSwipeUp]);
+    useEffect(() => {
+        onSwipeDownRef.current = onSwipeDown;
+    }, [onSwipeDown]);
+    useEffect(() => {
+        onSwipingRef.current = onSwiping;
+    }, [onSwiping]);
+    useEffect(() => {
+        onSwipeStartRef.current = onSwipeStart;
+    }, [onSwipeStart]);
+    useEffect(() => {
+        onSwipeEndRef.current = onSwipeEnd;
+    }, [onSwipeEnd]);
+    useEffect(() => {
+        const element = ref.current;
+        if (!element)
+            return;
+        const processSwipe = (deltaX, deltaY, deltaTime) => {
+            const absX = Math.abs(deltaX);
+            const absY = Math.abs(deltaY);
+            const distance = Math.sqrt(deltaX * deltaX + deltaY * deltaY);
+            const velocity = distance / deltaTime;
+            if (distance < minSwipeDistance ||
+                deltaTime > maxSwipeTime ||
+                velocity < velocityThreshold)
+                return;
+            let direction;
+            if (absX > absY) {
+                direction = deltaX > 0 ? "right" : "left";
+                if (direction === "left")
+                    onSwipeLeftRef.current?.(distance, velocity);
+                else
+                    onSwipeRightRef.current?.(distance, velocity);
+            }
+            else {
+                direction = deltaY > 0 ? "down" : "up";
+                if (direction === "up")
+                    onSwipeUpRef.current?.(distance, velocity);
+                else
+                    onSwipeDownRef.current?.(distance, velocity);
+            }
+            onSwipeRef.current?.(direction, distance, velocity);
+        };
+        const handleTouchStart = (e) => {
+            if (preventDefault)
+                e.preventDefault();
+            const touch = e.touches[0];
+            touchStartRef.current = {
+                x: touch.clientX,
+                y: touch.clientY,
+                time: Date.now(),
+            };
+            isSwiping.current = true;
+            onSwipeStartRef.current?.();
+        };
+        const handleTouchMove = (e) => {
+            if (!touchStartRef.current || !isSwiping.current)
+                return;
+            if (preventDefault)
+                e.preventDefault();
+            onSwipingRef.current?.(e.touches[0].clientX - touchStartRef.current.x, e.touches[0].clientY - touchStartRef.current.y);
+        };
+        const handleTouchEnd = (e) => {
+            if (!touchStartRef.current || !isSwiping.current)
+                return;
+            if (preventDefault)
+                e.preventDefault();
+            const touch = e.changedTouches[0];
+            processSwipe(touch.clientX - touchStartRef.current.x, touch.clientY - touchStartRef.current.y, Date.now() - touchStartRef.current.time);
+            touchStartRef.current = null;
+            isSwiping.current = false;
+            onSwipeEndRef.current?.();
+        };
+        const handleMouseDown = (e) => {
+            if (preventDefault)
+                e.preventDefault();
+            touchStartRef.current = { x: e.clientX, y: e.clientY, time: Date.now() };
+            isSwiping.current = true;
+            onSwipeStartRef.current?.();
+        };
+        const handleMouseMove = (e) => {
+            if (!touchStartRef.current || !isSwiping.current)
+                return;
+            onSwipingRef.current?.(e.clientX - touchStartRef.current.x, e.clientY - touchStartRef.current.y);
+        };
+        const handleMouseUp = (e) => {
+            if (!touchStartRef.current || !isSwiping.current)
+                return;
+            if (preventDefault)
+                e.preventDefault();
+            processSwipe(e.clientX - touchStartRef.current.x, e.clientY - touchStartRef.current.y, Date.now() - touchStartRef.current.time);
+            touchStartRef.current = null;
+            isSwiping.current = false;
+            onSwipeEndRef.current?.();
+        };
+        element.addEventListener("touchstart", handleTouchStart, {
+            passive: !preventDefault,
+        });
+        element.addEventListener("touchmove", handleTouchMove, {
+            passive: !preventDefault,
+        });
+        element.addEventListener("touchend", handleTouchEnd, {
+            passive: !preventDefault,
+        });
+        element.addEventListener("mousedown", handleMouseDown);
+        document.addEventListener("mousemove", handleMouseMove);
+        document.addEventListener("mouseup", handleMouseUp);
+        return () => {
+            element.removeEventListener("touchstart", handleTouchStart);
+            element.removeEventListener("touchmove", handleTouchMove);
+            element.removeEventListener("touchend", handleTouchEnd);
+            element.removeEventListener("mousedown", handleMouseDown);
+            document.removeEventListener("mousemove", handleMouseMove);
+            document.removeEventListener("mouseup", handleMouseUp);
+        };
+    }, [ref, minSwipeDistance, maxSwipeTime, velocityThreshold, preventDefault]);
+}

package/dist/react/hooks/useUnsavedChanges.d.ts

@@ -0,0 +1,44 @@
+import "client-only";
+export declare const UNSAVED_CHANGES_EVENT = "unsaved-changes:confirm";
+export interface UseUnsavedChangesOptions {
+    /** Current form values to compare against initial */
+    formValues: Record<string, string>;
+    /** Initial form values snapshot (taken when data loads) */
+    initialValues: Record<string, string> | null;
+    /** Additional dirty flag from outside the form (e.g. pending avatar upload) */
+    extraDirty?: boolean;
+    /**
+     * Called when the user attempts to navigate away with unsaved changes.
+     * Must return a Promise that resolves to `true` (continue) or `false` (stay).
+     * Defaults to `window.confirm` with a generic message.
+     */
+    confirmFn?: () => Promise<boolean>;
+    /**
+     * Message shown in the browser-native `beforeunload` dialog.
+     * Most modern browsers ignore custom messages and show their own text.
+     */
+    beforeUnloadWarning?: string;
+}
+export interface UseUnsavedChangesReturn {
+    /** Whether there are any unsaved changes (form or extra) */
+    isDirty: boolean;
+    /** Whether the form fields specifically have changed */
+    isFormDirty: boolean;
+    /** Call after a successful save to reset initial values to current */
+    markClean: () => void;
+    /** Prompt the user and return true if they confirmed leaving, false otherwise */
+    confirmLeave: () => Promise<boolean>;
+}
+/**
+ * useUnsavedChanges
+ *
+ * Tracks unsaved form changes and warns users before navigating away.
+ *
+ * - Compares `formValues` to `initialValues` to detect form dirtiness
+ * - Accepts an optional `extraDirty` flag (e.g. pending file upload)
+ * - Registers a `beforeunload` handler while dirty
+ * - Exposes `confirmLeave()` which calls the provided `confirmFn` (or falls back
+ *   to `window.confirm`) to handle navigation guards
+ * - `markClean()` resets the snapshot after a successful save
+ */
+export declare function useUnsavedChanges({ formValues, initialValues, extraDirty, confirmFn, beforeUnloadWarning, }: UseUnsavedChangesOptions): UseUnsavedChangesReturn;

package/dist/react/hooks/useUnsavedChanges.js

@@ -0,0 +1,55 @@
+"use client";
+import "client-only";
+import { useState, useEffect, useCallback, useRef } from "react";
+export const UNSAVED_CHANGES_EVENT = "unsaved-changes:confirm";
+/**
+ * useUnsavedChanges
+ *
+ * Tracks unsaved form changes and warns users before navigating away.
+ *
+ * - Compares `formValues` to `initialValues` to detect form dirtiness
+ * - Accepts an optional `extraDirty` flag (e.g. pending file upload)
+ * - Registers a `beforeunload` handler while dirty
+ * - Exposes `confirmLeave()` which calls the provided `confirmFn` (or falls back
+ *   to `window.confirm`) to handle navigation guards
+ * - `markClean()` resets the snapshot after a successful save
+ */
+export function useUnsavedChanges({ formValues, initialValues, extraDirty = false, confirmFn, beforeUnloadWarning = "You have unsaved changes. Leave?", }) {
+    const [savedSnapshot, setSavedSnapshot] = useState(initialValues);
+    const savedSnapshotRef = useRef(savedSnapshot);
+    savedSnapshotRef.current = savedSnapshot;
+    // Sync snapshot when initialValues first arrives (data load)
+    useEffect(() => {
+        if (initialValues && !savedSnapshotRef.current) {
+            setSavedSnapshot(initialValues);
+        }
+    }, [initialValues]);
+    const isFormDirty = (() => {
+        if (!savedSnapshot)
+            return false;
+        return Object.keys(formValues).some((key) => (formValues[key] ?? "") !== (savedSnapshot[key] ?? ""));
+    })();
+    const isDirty = isFormDirty || extraDirty;
+    useEffect(() => {
+        if (!isDirty)
+            return;
+        const handler = (e) => {
+            e.preventDefault();
+            e.returnValue = beforeUnloadWarning;
+            return beforeUnloadWarning;
+        };
+        window.addEventListener("beforeunload", handler);
+        return () => window.removeEventListener("beforeunload", handler);
+    }, [isDirty, beforeUnloadWarning]);
+    const markClean = useCallback(() => {
+        setSavedSnapshot({ ...formValues });
+    }, [formValues]);
+    const confirmLeave = useCallback(() => {
+        if (!isDirty)
+            return Promise.resolve(true);
+        if (confirmFn)
+            return confirmFn();
+        return Promise.resolve(window.confirm("You have unsaved changes. Leave without saving?"));
+    }, [isDirty, confirmFn]);
+    return { isDirty, isFormDirty, markClean, confirmLeave };
+}