@mohasinac/react 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,366 @@
+import { RefObject } 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)');
+ * ```
+ */
+declare function useMediaQuery(query: string): boolean;
+
+/**
+ * useBreakpoint Hook
+ *
+ * Convenience hook for detecting common Tailwind breakpoints.
+ * Returns boolean flags and the current breakpoint name.
+ *
+ * Breakpoints (Tailwind defaults):
+ * - Mobile: < 768px
+ * - Tablet: 768px - 1023px
+ * - Desktop: >= 1024px
+ *
+ * @returns Object with breakpoint detection flags
+ *
+ * @example
+ * ```tsx
+ * const { isMobile, isTablet, isDesktop, breakpoint } = useBreakpoint();
+ *
+ * if (isMobile) {
+ *   return <MobileView />;
+ * }
+ * return <DesktopView />;
+ * ```
+ */
+declare function useBreakpoint(): {
+    isMobile: boolean;
+    isTablet: boolean;
+    isDesktop: boolean;
+    breakpoint: "mobile" | "tablet" | "desktop";
+};
+
+/**
+ * Configuration options for useClickOutside hook
+ */
+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>[];
+}
+/**
+ * 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,
+ * });
+ * ```
+ */
+declare function useClickOutside<T extends HTMLElement = HTMLElement>(ref: RefObject<T | null>, callback: (event: MouseEvent | TouchEvent) => void, options?: UseClickOutsideOptions): void;
+
+/**
+ * Key combination modifiers
+ */
+interface KeyModifiers {
+    ctrl?: boolean;
+    shift?: boolean;
+    alt?: boolean;
+    meta?: boolean;
+}
+/**
+ * Configuration options for useKeyPress hook
+ */
+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);
+ * ```
+ */
+declare function useKeyPress(key: string | string[], callback: (event: KeyboardEvent) => void, options?: UseKeyPressOptions): void;
+
+/**
+ * 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>
+ * );
+ * ```
+ */
+declare function useLongPress(callback: () => void, ms?: number): {
+    onMouseDown: () => void;
+    onMouseUp: () => void;
+    onMouseLeave: () => void;
+    onTouchStart: () => void;
+    onTouchEnd: () => void;
+};
+
+/**
+ * Gesture types supported
+ */
+type GestureType = "tap" | "doubletap" | "pinch" | "rotate";
+/**
+ * Configuration options for useGesture hook
+ */
+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>;
+ * ```
+ */
+declare function useGesture<T extends HTMLElement = HTMLElement>(ref: RefObject<T | null>, options?: UseGestureOptions): void;
+
+/**
+ * Swipe direction types
+ */
+type SwipeDirection = "left" | "right" | "up" | "down";
+/**
+ * Configuration options for useSwipe hook
+ */
+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>;
+ * ```
+ */
+declare function useSwipe<T extends HTMLElement = HTMLElement>(ref: RefObject<T | null>, options?: UseSwipeOptions): void;
+
+interface UsePullToRefreshOptions {
+    /** Distance in px the user must pull before onRefresh triggers (default: 80) */
+    threshold?: number;
+}
+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>
+ * );
+ * ```
+ */
+declare function usePullToRefresh(onRefresh: () => Promise<void>, options?: UsePullToRefreshOptions): UsePullToRefreshReturn;
+
+/**
+ * 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)
+ */
+interface CountdownRemaining {
+    days: number;
+    hours: number;
+    minutes: number;
+    seconds: number;
+}
+/**
+ * @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>;
+ * ```
+ */
+declare function useCountdown(endDate: Date | string | undefined): CountdownRemaining | null;
+
+interface UseCameraOptions {
+    facingMode?: "user" | "environment";
+    video?: boolean | MediaTrackConstraints;
+    audio?: boolean;
+}
+interface UseCameraReturn {
+    isSupported: boolean;
+    isActive: boolean;
+    isCapturing: boolean;
+    stream: MediaStream | null;
+    error: string | null;
+    videoRef: React.RefObject<HTMLVideoElement | null>;
+    startCamera: (options?: UseCameraOptions) => Promise<void>;
+    stopCamera: () => void;
+    takePhoto: () => Blob | null;
+    startRecording: () => void;
+    stopRecording: () => Promise<Blob>;
+    switchCamera: () => Promise<void>;
+}
+/**
+ * useCamera
+ *
+ * Provides access to the device camera via the MediaDevices API.
+ * Zero domain imports. Safe to use in any Tier 1 / Tier 2 component.
+ *
+ * Lifecycle:
+ * - Call `startCamera()` to open the stream and wire `videoRef` to a <video> element.
+ * - `stopCamera()` releases hardware tracks (turns off the camera indicator light).
+ * - `takePhoto()` captures the current frame as image/webp.
+ * - `startRecording()` / `stopRecording()` use MediaRecorder (video/webm output).
+ * - `useEffect` cleanup calls `stopCamera()` automatically on unmount.
+ */
+declare function useCamera(): UseCameraReturn;
+
+export { type CountdownRemaining, type GestureType, type KeyModifiers, type SwipeDirection, type UseCameraOptions, type UseCameraReturn, type UseClickOutsideOptions, type UseGestureOptions, type UseKeyPressOptions, type UsePullToRefreshOptions, type UsePullToRefreshReturn, type UseSwipeOptions, useBreakpoint, useCamera, useClickOutside, useCountdown, useGesture, useKeyPress, useLongPress, useMediaQuery, usePullToRefresh, useSwipe };