@mohasinac/appkit 2.1.3 → 2.3.0

package/src/react/hooks/useClickOutside.ts

@@ -1,87 +0,0 @@
-"use client";
-
-import { useEffect, useRef, RefObject } from "react";
-
-/**
- * Configuration options for useClickOutside hook
- */
-export interface UseClickOutsideOptions {
-  /** Whether the hook is enabled */
-  enabled?: boolean;
-  /** Event type to listen for (default: 'mousedown') */
-  eventType?: "mousedown" | "mouseup" | "click";
-  /** Refs to additional elements that should be considered "inside" */
-  additionalRefs?: RefObject<HTMLElement | null>[];
-}
-
-const EMPTY_REFS: RefObject<HTMLElement | null>[] = [];
-
-/**
- * useClickOutside Hook
- *
- * Detects clicks outside of specified element(s) and triggers a callback.
- * Commonly used for dropdowns, modals, and popovers.
- *
- * @param ref - Primary element reference
- * @param callback - Function to call when clicking outside
- * @param options - Configuration options
- *
- * @example
- * ```tsx
- * const dropdownRef = useRef<HTMLDivElement>(null);
- * const triggerRef = useRef<HTMLButtonElement>(null);
- *
- * useClickOutside(dropdownRef, () => {
- *   setIsOpen(false);
- * }, {
- *   additionalRefs: [triggerRef],
- *   enabled: isOpen,
- * });
- * ```
- */
-export function useClickOutside<T extends HTMLElement = HTMLElement>(
-  ref: RefObject<T | null>,
-  callback: (event: MouseEvent | TouchEvent) => void,
-  options: UseClickOutsideOptions = {},
-) {
-  const {
-    enabled = true,
-    eventType = "mousedown",
-    additionalRefs = EMPTY_REFS,
-  } = options;
-
-  // Store callback in a ref to avoid re-subscribing listeners on every render
-  const callbackRef = useRef(callback);
-  useEffect(() => {
-    callbackRef.current = callback;
-  }, [callback]);
-
-  useEffect(() => {
-    if (!enabled) return;
-
-    const handleClickOutside = (event: MouseEvent | TouchEvent) => {
-      // Check if click is outside the primary ref
-      if (ref.current && !ref.current.contains(event.target as Node)) {
-        // Check if click is outside all additional refs
-        const isOutsideAll = additionalRefs.every(
-          (additionalRef) =>
-            !additionalRef.current ||
-            !additionalRef.current.contains(event.target as Node),
-        );
-
-        if (isOutsideAll) {
-          callbackRef.current(event);
-        }
-      }
-    };
-
-    // Add event listeners for both mouse and touch
-    document.addEventListener(eventType, handleClickOutside);
-    document.addEventListener("touchstart", handleClickOutside);
-
-    return () => {
-      document.removeEventListener(eventType, handleClickOutside);
-      document.removeEventListener("touchstart", handleClickOutside);
-    };
-  }, [ref, enabled, eventType, additionalRefs]);
-}

package/src/react/hooks/useContainerGrid.ts

@@ -1,77 +0,0 @@
-// appkit/src/react/hooks/useContainerGrid.ts
-"use client";
-import { useRef, useState, useEffect } from "react";
-
-export interface UseContainerGridOptions {
-  /** Minimum width of each grid item in pixels */
-  minItemWidth: number;
-  /** Gap between items in pixels (default: 16) */
-  gap?: number;
-  /** Minimum column count (default: 1) */
-  minCols?: number;
-  /** Maximum column count (default: Infinity) */
-  maxCols?: number;
-}
-
-export interface UseContainerGridResult {
-  /** Attach to the grid container element */
-  containerRef: React.RefObject<HTMLElement | null>;
-  /** Current computed column count */
-  cols: number;
-}
-
-/**
- * `useContainerGrid` — compute the number of columns that fit in a container
- * using a `ResizeObserver`. Drives fluid skeleton loader card counts.
- *
- * **Formula**: `cols = clamp(minCols, floor((width + gap) / (minItemWidth + gap)), maxCols)`
- *
- * Pair with the `fluid-grid-*` CSS utilities in `tailwind.config.js` so the
- * skeleton count always matches the visible grid columns.
- *
- * @example
- * ```tsx
- * const { containerRef, cols } = useContainerGrid({ minItemWidth: 220 });
- *
- * return (
- *   <ul ref={containerRef as React.RefObject<HTMLUListElement>} className="fluid-grid-card gap-4">
- *     {isLoading
- *       ? Array.from({ length: cols * 2 }).map((_, i) => <li key={i}><Skeleton /></li>)
- *       : items.map((item) => <li key={item.id}><ProductCard product={item} /></li>)}
- *   </ul>
- * );
- * ```
- */
-export function useContainerGrid({
-  minItemWidth,
-  gap = 16,
-  minCols = 1,
-  maxCols = Infinity,
-}: UseContainerGridOptions): UseContainerGridResult {
-  const containerRef = useRef<HTMLElement>(null);
-  const [cols, setCols] = useState(minCols);
-
-  useEffect(() => {
-    const el = containerRef.current;
-    if (!el) return;
-
-    const compute = (width: number) => {
-      const raw = Math.floor((width + gap) / (minItemWidth + gap));
-      const clamped = Math.min(
-        maxCols === Infinity ? raw : maxCols,
-        Math.max(minCols, raw),
-      );
-      setCols(clamped);
-    };
-
-    const ro = new ResizeObserver(([entry]) => {
-      if (entry) compute(entry.contentRect.width);
-    });
-    ro.observe(el);
-    compute(el.getBoundingClientRect().width);
-
-    return () => ro.disconnect();
-  }, [minItemWidth, gap, minCols, maxCols]);
-
-  return { containerRef, cols };
-}

package/src/react/hooks/useCountdown.ts

@@ -1,73 +0,0 @@
-import { useState, useEffect } from "react";
-
-/**
- * useCountdown — tracks time remaining until a future date.
- *
- * Returns `null` when the target date has passed or is not provided.
- *
- * Supports:
- * - `Date` objects
- * - ISO strings / numeric timestamps
- * - Firestore Timestamp JSON shape `{ _seconds, _nanoseconds }` (serialised
- *   by Firestore's REST API — no Firestore SDK import needed)
- */
-export interface CountdownRemaining {
-  days: number;
-  hours: number;
-  minutes: number;
-  seconds: number;
-}
-
-/** Resolve any date-like value into a ms timestamp. */
-function resolveMs(endDate: unknown): number {
-  if (!endDate) return NaN;
-  if (endDate instanceof Date) return endDate.getTime();
-  // Firestore Timestamp JSON shape: { _seconds, _nanoseconds }
-  if (
-    typeof endDate === "object" &&
-    endDate !== null &&
-    "_seconds" in endDate &&
-    typeof (endDate as Record<string, unknown>)._seconds === "number"
-  ) {
-    return (endDate as { _seconds: number })._seconds * 1000;
-  }
-  // ISO string or numeric string
-  return new Date(endDate as string).getTime();
-}
-
-/**
- * @example
- * ```tsx
- * const remaining = useCountdown(auction.endsAt);
- * if (!remaining) return <span>Ended</span>;
- * return <span>{remaining.hours}h {remaining.minutes}m {remaining.seconds}s</span>;
- * ```
- */
-export function useCountdown(
-  endDate: Date | string | undefined,
-): CountdownRemaining | null {
-  const getRemaining = (): CountdownRemaining | null => {
-    if (!endDate) return null;
-    const ms = resolveMs(endDate);
-    if (Number.isNaN(ms)) return null;
-    const diff = ms - Date.now();
-    if (diff <= 0) return null;
-    return {
-      days: Math.floor(diff / (1000 * 60 * 60 * 24)),
-      hours: Math.floor((diff % (1000 * 60 * 60 * 24)) / (1000 * 60 * 60)),
-      minutes: Math.floor((diff % (1000 * 60 * 60)) / (1000 * 60)),
-      seconds: Math.floor((diff % (1000 * 60)) / 1000),
-    };
-  };
-
-  const [remaining, setRemaining] = useState<CountdownRemaining | null>(
-    getRemaining,
-  );
-
-  useEffect(() => {
-    const id = setInterval(() => setRemaining(getRemaining()), 1000);
-    return () => clearInterval(id);
-  }, [endDate]);
-
-  return remaining;
-}

package/src/react/hooks/useGesture.ts

@@ -1,255 +0,0 @@
-"use client";
-
-import { useRef, useEffect, RefObject } from "react";
-
-/**
- * Gesture types supported
- */
-export type GestureType = "tap" | "doubletap" | "pinch" | "rotate";
-
-/**
- * Configuration options for useGesture hook
- */
-export interface UseGestureOptions {
-  /** Callback for tap gesture */
-  onTap?: (x: number, y: number) => void;
-  /** Callback for double tap gesture */
-  onDoubleTap?: (x: number, y: number) => void;
-  /** Callback for pinch gesture (zoom in/out) */
-  onPinch?: (scale: number, distance: number) => void;
-  /** Callback during pinching */
-  onPinching?: (scale: number) => void;
-  /** Callback for rotation gesture */
-  onRotate?: (angle: number) => void;
-  /** Callback during rotation */
-  onRotating?: (angle: number) => void;
-  /** Maximum time between taps for double tap (ms, default: 300) */
-  doubleTapDelay?: number;
-  /** Maximum movement allowed for tap (px, default: 10) */
-  tapMovementThreshold?: number;
-  /** Prevent default behavior */
-  preventDefault?: boolean;
-}
-
-/**
- * useGesture Hook
- *
- * Detects various touch gestures including tap, double tap, pinch, and rotate.
- * Primarily designed for touch devices but also works with mouse for basic gestures.
- *
- * @param ref - Reference to the element to attach gesture handlers
- * @param options - Configuration options for gesture detection
- *
- * @example
- * ```tsx
- * const ref = useRef<HTMLDivElement>(null);
- *
- * useGesture(ref, {
- *   onTap: (x, y) => console.log('Tapped at', x, y),
- *   onDoubleTap: () => console.log('Double tapped'),
- *   onPinch: (scale) => console.log('Pinch scale', scale),
- * });
- *
- * return <div ref={ref}>Touch me!</div>;
- * ```
- */
-export function useGesture<T extends HTMLElement = HTMLElement>(
-  ref: RefObject<T | null>,
-  options: UseGestureOptions = {},
-) {
-  const {
-    onTap,
-    onDoubleTap,
-    onPinch,
-    onPinching,
-    onRotate,
-    onRotating,
-    doubleTapDelay = 300,
-    tapMovementThreshold = 10,
-    preventDefault = false,
-  } = options;
-
-  const touchStartRef = useRef<{ x: number; y: number; time: number } | null>(
-    null,
-  );
-  const lastTapRef = useRef<number>(0);
-  const initialPinchDistanceRef = useRef<number>(0);
-  const initialRotationRef = useRef<number>(0);
-
-  // Store callbacks in refs to avoid event listener churn
-  const onTapRef = useRef(onTap);
-  const onDoubleTapRef = useRef(onDoubleTap);
-  const onPinchRef = useRef(onPinch);
-  const onPinchingRef = useRef(onPinching);
-  const onRotateRef = useRef(onRotate);
-  const onRotatingRef = useRef(onRotating);
-
-  useEffect(() => {
-    onTapRef.current = onTap;
-  }, [onTap]);
-  useEffect(() => {
-    onDoubleTapRef.current = onDoubleTap;
-  }, [onDoubleTap]);
-  useEffect(() => {
-    onPinchRef.current = onPinch;
-  }, [onPinch]);
-  useEffect(() => {
-    onPinchingRef.current = onPinching;
-  }, [onPinching]);
-  useEffect(() => {
-    onRotateRef.current = onRotate;
-  }, [onRotate]);
-  useEffect(() => {
-    onRotatingRef.current = onRotating;
-  }, [onRotating]);
-
-  useEffect(() => {
-    const element = ref.current;
-    if (!element) return;
-
-    const getDistance = (touch1: Touch, touch2: Touch): number => {
-      const dx = touch1.clientX - touch2.clientX;
-      const dy = touch1.clientY - touch2.clientY;
-      return Math.sqrt(dx * dx + dy * dy);
-    };
-
-    const getAngle = (touch1: Touch, touch2: Touch): number => {
-      const dx = touch1.clientX - touch2.clientX;
-      const dy = touch1.clientY - touch2.clientY;
-      return Math.atan2(dy, dx) * (180 / Math.PI);
-    };
-
-    const handleTouchStart = (e: TouchEvent) => {
-      if (preventDefault) e.preventDefault();
-      const touch = e.touches[0];
-      touchStartRef.current = {
-        x: touch.clientX,
-        y: touch.clientY,
-        time: Date.now(),
-      };
-      if (e.touches.length === 2) {
-        initialPinchDistanceRef.current = getDistance(
-          e.touches[0],
-          e.touches[1],
-        );
-        initialRotationRef.current = getAngle(e.touches[0], e.touches[1]);
-      }
-    };
-
-    const handleTouchMove = (e: TouchEvent) => {
-      if (!touchStartRef.current) return;
-      if (
-        e.touches.length === 2 &&
-        (onPinchRef.current ||
-          onPinchingRef.current ||
-          onRotateRef.current ||
-          onRotatingRef.current)
-      ) {
-        if (preventDefault) e.preventDefault();
-        const currentDistance = getDistance(e.touches[0], e.touches[1]);
-        const currentAngle = getAngle(e.touches[0], e.touches[1]);
-        if (initialPinchDistanceRef.current > 0) {
-          onPinchingRef.current?.(
-            currentDistance / initialPinchDistanceRef.current,
-          );
-        }
-        if (initialRotationRef.current !== 0) {
-          onRotatingRef.current?.(currentAngle - initialRotationRef.current);
-        }
-      }
-    };
-
-    const handleTouchEnd = (e: TouchEvent) => {
-      if (!touchStartRef.current) return;
-      if (preventDefault) e.preventDefault();
-      const touch = e.changedTouches[0];
-      const deltaX = Math.abs(touch.clientX - touchStartRef.current.x);
-      const deltaY = Math.abs(touch.clientY - touchStartRef.current.y);
-
-      if (deltaX < tapMovementThreshold && deltaY < tapMovementThreshold) {
-        const now = Date.now();
-        const timeSinceLastTap = now - lastTapRef.current;
-        if (onDoubleTapRef.current && timeSinceLastTap < doubleTapDelay) {
-          onDoubleTapRef.current(
-            touchStartRef.current.x,
-            touchStartRef.current.y,
-          );
-          lastTapRef.current = 0;
-        } else {
-          onTapRef.current?.(touchStartRef.current.x, touchStartRef.current.y);
-          lastTapRef.current = now;
-        }
-      }
-
-      if (e.touches.length === 0 && initialPinchDistanceRef.current > 0) {
-        const currentDistance = getDistance(
-          e.changedTouches[0],
-          e.changedTouches[1] || e.changedTouches[0],
-        );
-        onPinchRef.current?.(
-          currentDistance / initialPinchDistanceRef.current,
-          currentDistance,
-        );
-        initialPinchDistanceRef.current = 0;
-      }
-
-      if (e.touches.length === 0 && initialRotationRef.current !== 0) {
-        const currentAngle = getAngle(
-          e.changedTouches[0],
-          e.changedTouches[1] || e.changedTouches[0],
-        );
-        onRotateRef.current?.(currentAngle - initialRotationRef.current);
-        initialRotationRef.current = 0;
-      }
-
-      touchStartRef.current = null;
-    };
-
-    const handleMouseDown = (e: MouseEvent) => {
-      if (preventDefault) e.preventDefault();
-      touchStartRef.current = { x: e.clientX, y: e.clientY, time: Date.now() };
-    };
-
-    const handleMouseUp = (e: MouseEvent) => {
-      if (!touchStartRef.current) return;
-      if (preventDefault) e.preventDefault();
-      const deltaX = Math.abs(e.clientX - touchStartRef.current.x);
-      const deltaY = Math.abs(e.clientY - touchStartRef.current.y);
-      if (deltaX < tapMovementThreshold && deltaY < tapMovementThreshold) {
-        const now = Date.now();
-        const timeSinceLastTap = now - lastTapRef.current;
-        if (onDoubleTapRef.current && timeSinceLastTap < doubleTapDelay) {
-          onDoubleTapRef.current(
-            touchStartRef.current.x,
-            touchStartRef.current.y,
-          );
-          lastTapRef.current = 0;
-        } else {
-          onTapRef.current?.(touchStartRef.current.x, touchStartRef.current.y);
-          lastTapRef.current = now;
-        }
-      }
-      touchStartRef.current = null;
-    };
-
-    element.addEventListener("touchstart", handleTouchStart, {
-      passive: !preventDefault,
-    });
-    element.addEventListener("touchmove", handleTouchMove, {
-      passive: !preventDefault,
-    });
-    element.addEventListener("touchend", handleTouchEnd, {
-      passive: !preventDefault,
-    });
-    element.addEventListener("mousedown", handleMouseDown);
-    element.addEventListener("mouseup", handleMouseUp);
-
-    return () => {
-      element.removeEventListener("touchstart", handleTouchStart);
-      element.removeEventListener("touchmove", handleTouchMove);
-      element.removeEventListener("touchend", handleTouchEnd);
-      element.removeEventListener("mousedown", handleMouseDown);
-      element.removeEventListener("mouseup", handleMouseUp);
-    };
-  }, [ref, doubleTapDelay, tapMovementThreshold, preventDefault]);
-}

package/src/react/hooks/useKeyPress.ts

@@ -1,113 +0,0 @@
-"use client";
-
-import { useEffect, useCallback, useRef, useMemo } from "react";
-
-/**
- * Key combination modifiers
- */
-export interface KeyModifiers {
-  ctrl?: boolean;
-  shift?: boolean;
-  alt?: boolean;
-  meta?: boolean; // Command key on Mac
-}
-
-/**
- * Configuration options for useKeyPress hook
- */
-export interface UseKeyPressOptions extends KeyModifiers {
-  /** Whether the hook is enabled */
-  enabled?: boolean;
-  /** Event type to listen for (default: 'keydown') */
-  eventType?: "keydown" | "keyup" | "keypress";
-  /** Prevent default behavior */
-  preventDefault?: boolean;
-  /** Target element (default: document) */
-  target?: HTMLElement | Document | Window;
-}
-
-/**
- * useKeyPress Hook
- *
- * Detects keyboard events with support for key combinations.
- * Useful for keyboard shortcuts and accessibility.
- *
- * @param key - Key or array of keys to listen for (e.g., 'Enter', 'Escape', ['a', 'A'])
- * @param callback - Function to call when key is pressed
- * @param options - Configuration options including modifiers
- *
- * @example
- * ```tsx
- * // Simple key press
- * useKeyPress('Escape', () => closeModal());
- *
- * // Key combination (Ctrl+S)
- * useKeyPress('s', handleSave, {
- *   ctrl: true,
- *   preventDefault: true,
- * });
- *
- * // Multiple keys
- * useKeyPress(['Enter', 'NumpadEnter'], handleSubmit);
- * ```
- */
-export function useKeyPress(
-  key: string | string[],
-  callback: (event: KeyboardEvent) => void,
-  options: UseKeyPressOptions = {},
-) {
-  const {
-    enabled = true,
-    eventType = "keydown",
-    preventDefault = false,
-    ctrl = false,
-    shift = false,
-    alt = false,
-    meta = false,
-    target = typeof document !== "undefined" ? document : null,
-  } = options;
-
-  // Memoize keys array to avoid re-creation when `key` is a string
-  const keys = useMemo(() => (Array.isArray(key) ? key : [key]), [key]);
-
-  // Store callback in a ref to keep event listener stable
-  const callbackRef = useRef(callback);
-  useEffect(() => {
-    callbackRef.current = callback;
-  }, [callback]);
-
-  const handleKeyPress = useCallback(
-    (event: KeyboardEvent) => {
-      // Check if pressed key matches any of the target keys
-      const isKeyMatch = keys.some((k) => event.key === k || event.code === k);
-
-      if (!isKeyMatch) return;
-
-      // Check modifiers
-      const modifiersMatch =
-        event.ctrlKey === ctrl &&
-        event.shiftKey === shift &&
-        event.altKey === alt &&
-        event.metaKey === meta;
-
-      if (!modifiersMatch) return;
-
-      if (preventDefault) {
-        event.preventDefault();
-      }
-
-      callbackRef.current(event);
-    },
-    [keys, ctrl, shift, alt, meta, preventDefault],
-  );
-
-  useEffect(() => {
-    if (!enabled || !target) return;
-
-    target.addEventListener(eventType, handleKeyPress as EventListener);
-
-    return () => {
-      target.removeEventListener(eventType, handleKeyPress as EventListener);
-    };
-  }, [enabled, eventType, handleKeyPress, target]);
-}

package/src/react/hooks/useLongPress.ts

@@ -1,62 +0,0 @@
-"use client";
-
-import { useRef, useCallback, useEffect } from "react";
-
-/**
- * useLongPress Hook
- *
- * Fires `callback` after the element is held for `ms` milliseconds.
- * A quick tap (pointer-up before the threshold) does NOT fire the callback.
- * Safe to use on both mouse and touch devices.
- *
- * @param callback - Function to call on long-press
- * @param ms       - Hold duration in ms before callback fires (default: 500)
- *
- * @example
- * ```tsx
- * const longPress = useLongPress(() => openContextMenu(), 500);
- *
- * return (
- *   <tr {...longPress}>…</tr>
- * );
- * ```
- */
-export function useLongPress(callback: () => void, ms = 500) {
-  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  // Keep callback ref stable — avoids re-attaching on every render
-  const callbackRef = useRef(callback);
-
-  useEffect(() => {
-    callbackRef.current = callback;
-  }, [callback]);
-
-  const start = useCallback(() => {
-    timerRef.current = setTimeout(() => {
-      callbackRef.current();
-    }, ms);
-  }, [ms]);
-
-  const cancel = useCallback(() => {
-    if (timerRef.current !== null) {
-      clearTimeout(timerRef.current);
-      timerRef.current = null;
-    }
-  }, []);
-
-  // Clean up any pending timer on unmount
-  useEffect(() => {
-    return () => {
-      if (timerRef.current !== null) {
-        clearTimeout(timerRef.current);
-      }
-    };
-  }, []);
-
-  return {
-    onMouseDown: start,
-    onMouseUp: cancel,
-    onMouseLeave: cancel,
-    onTouchStart: start,
-    onTouchEnd: cancel,
-  };
-}

package/src/react/hooks/useMediaQuery.ts

@@ -1,40 +0,0 @@
-"use client";
-
-import { useState, useEffect } from "react";
-
-/**
- * useMediaQuery Hook
- *
- * Detects if a CSS media query matches the current viewport.
- * Returns true/false based on whether the query matches.
- *
- * @param query - CSS media query string (e.g., '(min-width: 768px)')
- * @returns boolean - Whether the media query currently matches
- *
- * @example
- * ```tsx
- * const isMobile = useMediaQuery('(max-width: 767px)');
- * const isDesktop = useMediaQuery('(min-width: 1024px)');
- * ```
- */
-export function useMediaQuery(query: string): boolean {
-  const [matches, setMatches] = useState(
-    // Lazy initializer: use real value on first client render, suppressing the flash.
-    // Returns false on server (no window) — consistent with no-match default.
-    () => typeof window !== "undefined" && window.matchMedia(query).matches,
-  );
-
-  useEffect(() => {
-    if (typeof window === "undefined") return;
-
-    const media = window.matchMedia(query);
-    setMatches(media.matches);
-
-    const listener = (e: MediaQueryListEvent) => setMatches(e.matches);
-    media.addEventListener("change", listener);
-
-    return () => media.removeEventListener("change", listener);
-  }, [query]);
-
-  return matches;
-}