@mohasinac/appkit 2.1.3 → 2.3.0

package/src/react/hooks/usePendingFilters.ts

@@ -1,138 +0,0 @@
-"use client";
-
-import { useCallback, useMemo, useState } from "react";
-import type { useUrlTable } from "./useUrlTable";
-
-type UrlTable = ReturnType<typeof useUrlTable>;
-
-export interface UsePendingFiltersOptions {
-  /** The page's useUrlTable instance */
-  table: UrlTable;
-  /** URL param keys to manage (e.g. ['status', 'category', 'role']) */
-  keys: string[];
-}
-
-export interface UsePendingFiltersReturn {
-  /** Current uncommitted selections per key (string[] per key) */
-  pending: Record<string, string[]>;
-  /** Values currently in the URL (committed) per key */
-  applied: Record<string, string[]>;
-  /** true when pending differs from applied */
-  isDirty: boolean;
-  /** Total number of selected values across all pending keys */
-  pendingCount: number;
-  /** Total number of selected values in the URL (for badge display) */
-  appliedCount: number;
-  /** Update one key in pending state (does NOT write to URL) */
-  set: (key: string, values: string[]) => void;
-  /** Write all pending keys to the URL (resets page to 1) */
-  apply: () => void;
-  /** Discard pending, revert to applied (URL) state */
-  reset: () => void;
-  /** Clear all keys in both pending state and the URL */
-  clear: () => void;
-}
-
-/**
- * usePendingFilters
- *
- * Manages local (uncommitted) filter state for a FilterDrawer or any deferred
- * filter panel. Values are only written to the URL when `apply()` is called.
- *
- * Initialised from the current URL params on mount, so opening a drawer
- * pre-fills any already-applied filters.
- *
- * @example
- * ```ts
- * const table   = useUrlTable({ defaults: { pageSize: '25' } });
- * const filters = usePendingFilters({ table, keys: ['status', 'category'] });
- *
- * <FilterDrawer
- *   onApply={() => { filters.apply(); setDrawerOpen(false); }}
- *   onReset={() => filters.clear()}
- *   activeCount={filters.appliedCount}
- * >
- *   <FilterFacetSection
- *     title="Status"
- *     options={STATUS_OPTIONS}
- *     selected={filters.pending['status'] ?? []}
- *     onChange={(v) => filters.set('status', v)}
- *   />
- * </FilterDrawer>
- * ```
- */
-export function usePendingFilters({
-  table,
-  keys,
-}: UsePendingFiltersOptions): UsePendingFiltersReturn {
-  const parseValues = useCallback(
-    (key: string): string[] => {
-      const raw = table.get(key);
-      return raw ? raw.split(",").filter(Boolean) : [];
-    },
-    [table],
-  );
-
-  const [pending, setPending] = useState<Record<string, string[]>>(() =>
-    Object.fromEntries(keys.map((k) => [k, parseValues(k)])),
-  );
-
-  const applied = useMemo<Record<string, string[]>>(
-    () => Object.fromEntries(keys.map((k) => [k, parseValues(k)])),
-    [keys, parseValues],
-  );
-
-  const pendingCount = useMemo(
-    () => Object.values(pending).reduce((sum, arr) => sum + arr.length, 0),
-    [pending],
-  );
-
-  const appliedCount = useMemo(
-    () => Object.values(applied).reduce((sum, arr) => sum + arr.length, 0),
-    [applied],
-  );
-
-  const isDirty = useMemo(() => {
-    return keys.some((k) => {
-      const p = (pending[k] ?? []).slice().sort();
-      const a = (applied[k] ?? []).slice().sort();
-      return p.length !== a.length || p.some((v, i) => v !== a[i]);
-    });
-  }, [keys, pending, applied]);
-
-  const set = useCallback((key: string, values: string[]) => {
-    setPending((prev) => ({ ...prev, [key]: values }));
-  }, []);
-
-  const apply = useCallback(() => {
-    const updates: Record<string, string> = { page: "1" };
-    for (const k of keys) {
-      updates[k] = (pending[k] ?? []).join(",");
-    }
-    table.setMany(updates);
-  }, [keys, pending, table]);
-
-  const reset = useCallback(() => {
-    setPending(Object.fromEntries(keys.map((k) => [k, parseValues(k)])));
-  }, [keys, parseValues]);
-
-  const clear = useCallback(() => {
-    const empty = Object.fromEntries(keys.map((k) => [k, [] as string[]]));
-    setPending(empty);
-    const updates: Record<string, string> = { page: "1" };
-    for (const k of keys) updates[k] = "";
-    table.setMany(updates);
-  }, [keys, table]);
-
-  return {
-    pending,
-    applied,
-    isDirty,
-    pendingCount,
-    appliedCount,
-    set,
-    apply,
-    reset,
-    clear,
-  };
-}

package/src/react/hooks/usePendingTable.ts

@@ -1,84 +0,0 @@
-"use client";
-
-import { useMemo } from "react";
-import { usePendingFilters } from "./usePendingFilters";
-import type { useUrlTable } from "./useUrlTable";
-
-type UrlTable = ReturnType<typeof useUrlTable>;
-
-/**
- * Minimal UrlTable-compatible interface consumed by *Filters components.
- */
-export interface PendingTable {
-  get: (key: string) => string;
-  set: (key: string, value: string) => void;
-  setMany: (updates: Record<string, string>) => void;
-}
-
-export interface UsePendingTableReturn {
-  /** Drop-in UrlTable replacement that reads/writes to pending state */
-  pendingTable: PendingTable;
-  /** Count of applied (URL) filter values — use for the filter badge */
-  filterActiveCount: number;
-  /** Commit all pending changes to the URL (resets page to 1) */
-  onFilterApply: () => void;
-  /** Clear all filter keys from pending state and URL */
-  onFilterClear: () => void;
-  /**
-   * Revert pending state to the current URL values without clearing them.
-   * Call this when opening a filter drawer to ensure it shows the last
-   * committed state, even if the URL changed externally (e.g. a status tab).
-   */
-  onFilterReset: () => void;
-}
-
-/**
- * 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: UrlTable,
-  keys: string[],
-): UsePendingTableReturn {
-  const filters = usePendingFilters({ table, keys });
-
-  const pendingTable = useMemo<PendingTable>(
-    () => ({
-      get: (key: string): string => filters.pending[key]?.[0] ?? "",
-      set: (key: string, value: string): void => {
-        filters.set(key, value ? [value] : []);
-      },
-      setMany: (updates: Record<string, string>): void => {
-        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/src/react/hooks/usePullToRefresh.ts

@@ -1,111 +0,0 @@
-"use client";
-
-import { useRef, useState, useCallback, useEffect, 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 function usePullToRefresh(
-  onRefresh: () => Promise<void>,
-  options: UsePullToRefreshOptions = {},
-): UsePullToRefreshReturn {
-  const { threshold = 80 } = options;
-
-  const containerRef = useRef<HTMLDivElement>(null);
-  const [isPulling, setIsPulling] = useState(false);
-  const [progress, setProgress] = useState(0);
-
-  const startYRef = useRef<number | null>(null);
-  const thresholdReachedRef = useRef(false);
-  const onRefreshRef = useRef(onRefresh);
-
-  useEffect(() => {
-    onRefreshRef.current = onRefresh;
-  }, [onRefresh]);
-
-  const handleTouchStart = useCallback((e: TouchEvent) => {
-    const el = containerRef.current;
-    if (!el || el.scrollTop > 0) return;
-    startYRef.current = e.touches[0].clientY;
-    thresholdReachedRef.current = false;
-  }, []);
-
-  const handleTouchMove = useCallback(
-    (e: TouchEvent) => {
-      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/src/react/hooks/useSwipe.ts

@@ -1,240 +0,0 @@
-"use client";
-
-import { useRef, useEffect, 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 function useSwipe<T extends HTMLElement = HTMLElement>(
-  ref: RefObject<T | null>,
-  options: UseSwipeOptions = {},
-) {
-  const {
-    minSwipeDistance = 50,
-    maxSwipeTime = 300,
-    velocityThreshold = 0.3,
-    onSwipe,
-    onSwipeLeft,
-    onSwipeRight,
-    onSwipeUp,
-    onSwipeDown,
-    onSwiping,
-    onSwipeStart,
-    onSwipeEnd,
-    preventDefault = false,
-  } = options;
-
-  const touchStartRef = useRef<{ x: number; y: number; time: number } | null>(
-    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: number,
-      deltaY: number,
-      deltaTime: number,
-    ) => {
-      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: SwipeDirection;
-      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: TouchEvent) => {
-      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: TouchEvent) => {
-      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: TouchEvent) => {
-      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: MouseEvent) => {
-      if (preventDefault) e.preventDefault();
-      touchStartRef.current = { x: e.clientX, y: e.clientY, time: Date.now() };
-      isSwiping.current = true;
-      onSwipeStartRef.current?.();
-    };
-
-    const handleMouseMove = (e: MouseEvent) => {
-      if (!touchStartRef.current || !isSwiping.current) return;
-      onSwipingRef.current?.(
-        e.clientX - touchStartRef.current.x,
-        e.clientY - touchStartRef.current.y,
-      );
-    };
-
-    const handleMouseUp = (e: MouseEvent) => {
-      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/src/react/hooks/useUnsavedChanges.ts

@@ -1,104 +0,0 @@
-"use client";
-
-import { useState, useEffect, useCallback, useRef } from "react";
-
-export 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 function useUnsavedChanges({
-  formValues,
-  initialValues,
-  extraDirty = false,
-  confirmFn,
-  beforeUnloadWarning = "You have unsaved changes. Leave?",
-}: UseUnsavedChangesOptions): UseUnsavedChangesReturn {
-  const [savedSnapshot, setSavedSnapshot] = useState<Record<
-    string,
-    string
-  > | null>(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: BeforeUnloadEvent) => {
-      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((): Promise<boolean> => {
-    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 };
-}