taro-uno-ui 0.9.0 → 1.0.0

package/src/hooks/useAsync.ts

@@ -1,65 +1,64 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 
 export interface UseAsyncOptions<T> {
-    immediate?: boolean;
-    deps?: unknown[];
-    onSuccess?: (data: T) => void;
-    onError?: (error: Error) => void;
-    keepPreviousData?: boolean;
+  immediate?: boolean;
+  deps?: unknown[];
+  onSuccess?: (data: T) => void;
+  onError?: (error: Error) => void;
+  keepPreviousData?: boolean;
 }
 
 export interface UseAsyncResult<T> {
-    data: T | undefined;
-    error: Error | undefined;
-    loading: boolean;
-    execute: () => Promise<T | undefined>;
-    cancel: () => void;
-    setData: (updater: T | ((prev: T | undefined) => T)) => void;
+  data: T | undefined;
+  error: Error | undefined;
+  loading: boolean;
+  execute: () => Promise<T | undefined>;
+  cancel: () => void;
+  setData: (updater: T | ((prev: T | undefined) => T)) => void;
 }
 
 export function useAsync<T>(fn: () => Promise<T>, options: UseAsyncOptions<T> = {}): UseAsyncResult<T> {
-    const { immediate = false, deps = [], onSuccess, onError, keepPreviousData = true } = options;
-    const [data, setDataState] = useState<T | undefined>(undefined);
-    const [error, setError] = useState<Error | undefined>(undefined);
-    const [loading, setLoading] = useState<boolean>(false);
-    const abortRef = useRef<AbortController | null>(null);
+  const { immediate = false, deps = [], onSuccess, onError, keepPreviousData = true } = options;
+  const [data, setDataState] = useState<T | undefined>(undefined);
+  const [error, setError] = useState<Error | undefined>(undefined);
+  const [loading, setLoading] = useState<boolean>(false);
+  const abortRef = useRef<AbortController | null>(null);
 
-    const execute = useCallback(async () => {
-        if (!keepPreviousData) setDataState(undefined);
-        setLoading(true);
-        setError(undefined);
-        abortRef.current?.abort();
-        abortRef.current = new AbortController();
+  const execute = useCallback(async () => {
+    if (!keepPreviousData) setDataState(undefined);
+    setLoading(true);
+    setError(undefined);
+    abortRef.current?.abort();
+    abortRef.current = new AbortController();
 
-        try {
-            const result = await fn();
-            setDataState(prev => (typeof result === 'undefined' ? prev : result));
-            onSuccess?.(result);
-            setLoading(false);
-            return result;
-        } catch (e) {
-            const err = e as Error;
-            setError(err);
-            onError?.(err);
-            setLoading(false);
-            return undefined;
-        }
-    }, [fn, onSuccess, onError, keepPreviousData]);
+    try {
+      const result = await fn();
+      setDataState((prev) => (typeof result === 'undefined' ? prev : result));
+      onSuccess?.(result);
+      setLoading(false);
+      return result;
+    } catch (e) {
+      const err = e as Error;
+      setError(err);
+      onError?.(err);
+      setLoading(false);
+      return undefined;
+    }
+  }, [fn, onSuccess, onError, keepPreviousData]);
 
-    useEffect(() => {
-        if (immediate) execute();
-         
-    }, [immediate, execute, ...deps]);
+  useEffect(() => {
+    if (immediate) execute();
+  }, [immediate, execute, ...deps]);
 
-    const cancel = useCallback(() => {
-        abortRef.current?.abort();
-    }, []);
+  const cancel = useCallback(() => {
+    abortRef.current?.abort();
+  }, []);
 
-    const setData = useCallback((updater: T | ((prev: T | undefined) => T)) => {
-        setDataState(prev => (typeof updater === 'function' ? (updater as (p: T | undefined) => T)(prev) : updater));
-    }, []);
+  const setData = useCallback((updater: T | ((prev: T | undefined) => T)) => {
+    setDataState((prev) => (typeof updater === 'function' ? (updater as (p: T | undefined) => T)(prev) : updater));
+  }, []);
 
-    return { data, error, loading, execute, cancel, setData };
+  return { data, error, loading, execute, cancel, setData };
 }
 
 export default useAsync;

package/src/hooks/useClickOutside.ts

@@ -0,0 +1,52 @@
+/**
+ * useClickOutside Hook
+ * Detect clicks outside of a specific element
+ *
+ * @example
+ * ```typescript
+ * const ref = useClickOutside<HTMLDivElement>(() => {
+ *   console.log('Clicked outside!');
+ *   setIsOpen(false);
+ * });
+ *
+ * return <div ref={ref}>Content</div>;
+ * ```
+ */
+
+import { useEffect, useRef, RefObject } from 'react';
+
+/**
+ * Hook for detecting clicks outside an element
+ */
+export function useClickOutside<T extends HTMLElement = HTMLElement>(
+  handler: (event: MouseEvent | TouchEvent) => void,
+  enabled: boolean = true,
+): RefObject<T | null> {
+  const ref = useRef<T | null>(null);
+
+  useEffect(() => {
+    if (!enabled) return;
+
+    const handleClickOutside = (event: MouseEvent | TouchEvent) => {
+      const element = ref.current;
+      const target = event.target as Node;
+
+      // Check if click is outside the element
+      if (element && !element.contains(target)) {
+        handler(event);
+      }
+    };
+
+    // Add event listeners
+    document.addEventListener('mousedown', handleClickOutside);
+    document.addEventListener('touchstart', handleClickOutside);
+
+    // Cleanup
+    return () => {
+      document.removeEventListener('mousedown', handleClickOutside);
+      document.removeEventListener('touchstart', handleClickOutside);
+    };
+  }, [handler, enabled]);
+
+  return ref;
+}

package/src/hooks/useCounter.ts

@@ -0,0 +1,87 @@
+/**
+ * useCounter Hook
+ * Manage counter state with increment, decrement, and reset
+ *
+ * @example
+ * ```typescript
+ * const { count, increment, decrement, reset, set } = useCounter(0, { min: 0, max: 100 });
+ * increment(); // 1
+ * increment(5); // 6
+ * decrement(3); // 3
+ * ```
+ */
+
+import { useState, useCallback } from 'react';
+
+export interface UseCounterOptions {
+  /** Minimum allowed value */
+  min?: number;
+  /** Maximum allowed value */
+  max?: number;
+  /** Step size for increment/decrement */
+  step?: number;
+}
+
+export interface UseCounterReturn {
+  /** Current count value */
+  count: number;
+  /** Increment count */
+  increment: (step?: number) => void;
+  /** Decrement count */
+  decrement: (step?: number) => void;
+  /** Reset to initial value */
+  reset: () => void;
+  /** Set to specific value */
+  set: (value: number) => void;
+}
+
+/**
+ * Hook for managing counter state with constraints
+ */
+export function useCounter(initialValue: number = 0, options: UseCounterOptions = {}): UseCounterReturn {
+  const { min, max, step: defaultStep = 1 } = options;
+  const [count, setCount] = useState(initialValue);
+
+  const clamp = useCallback(
+    (value: number): number => {
+      let result = value;
+      if (min !== undefined && result < min) result = min;
+      if (max !== undefined && result > max) result = max;
+      return result;
+    },
+    [min, max],
+  );
+
+  const increment = useCallback(
+    (step: number = defaultStep) => {
+      setCount((c) => clamp(c + step));
+    },
+    [defaultStep, clamp],
+  );
+
+  const decrement = useCallback(
+    (step: number = defaultStep) => {
+      setCount((c) => clamp(c - step));
+    },
+    [defaultStep, clamp],
+  );
+
+  const reset = useCallback(() => {
+    setCount(initialValue);
+  }, [initialValue]);
+
+  const set = useCallback(
+    (value: number) => {
+      setCount(clamp(value));
+    },
+    [clamp],
+  );
+
+  return {
+    count,
+    increment,
+    decrement,
+    reset,
+    set,
+  };
+}

package/src/hooks/useDebounce.ts

@@ -0,0 +1,150 @@
+/**
+ * useDebounce & useThrottle Hooks
+ * Delay value updates or limit function call frequency
+ *
+ * @example
+ * ```typescript
+ * // Debounce - delays until user stops typing
+ * const debouncedSearch = useDebounce(searchTerm, 500);
+ *
+ * // Throttle - limits calls to once per interval
+ * const throttledScroll = useThrottle(scrollY, 100);
+ * ```
+ */
+
+import { useState, useEffect, useRef, useCallback } from 'react';
+
+/**
+ * Hook for debouncing a value
+ * Updates only after the value stops changing for the specified delay
+ */
+export function useDebounce<T>(value: T, delay: number = 500): T {
+  const [debouncedValue, setDebouncedValue] = useState<T>(value);
+
+  useEffect(() => {
+    // Set timeout to update debounced value
+    const timer = setTimeout(() => {
+      setDebouncedValue(value);
+    }, delay);
+
+    // Clear timeout if value changes before delay elapses
+    return () => {
+      clearTimeout(timer);
+    };
+  }, [value, delay]);
+
+  return debouncedValue;
+}
+
+/**
+ * Hook for throttling a value
+ * Updates at most once per interval
+ */
+export function useThrottle<T>(value: T, interval: number = 500): T {
+  const [throttledValue, setThrottledValue] = useState<T>(value);
+  const lastUpdated = useRef<number>(Date.now());
+
+  useEffect(() => {
+    const now = Date.now();
+    const timeSinceLastUpdate = now - lastUpdated.current;
+
+    if (timeSinceLastUpdate >= interval) {
+      // Enough time has passed, update immediately
+      setThrottledValue(value);
+      lastUpdated.current = now;
+      return () => {};
+    } else {
+      // Schedule update for remaining time
+      const timer = setTimeout(() => {
+        setThrottledValue(value);
+        lastUpdated.current = Date.now();
+      }, interval - timeSinceLastUpdate);
+
+      return () => {
+        clearTimeout(timer);
+      };
+    }
+  }, [value, interval]);
+
+  return throttledValue;
+}
+
+/**
+ * Hook for debouncing a callback function
+ */
+export function useDebouncedCallback<T extends (...args: any[]) => any>(
+  callback: T,
+  delay: number = 500,
+): (...args: Parameters<T>) => void {
+  const timeoutRef = useRef<NodeJS.Timeout | null>(null);
+
+  const debouncedCallback = useCallback(
+    (...args: Parameters<T>) => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+      }
+
+      timeoutRef.current = setTimeout(() => {
+        callback(...args);
+      }, delay);
+    },
+    [callback, delay],
+  );
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+      }
+    };
+  }, []);
+
+  return debouncedCallback;
+}
+
+/**
+ * Hook for throttling a callback function
+ */
+export function useThrottledCallback<T extends (...args: any[]) => any>(
+  callback: T,
+  interval: number = 500,
+): (...args: Parameters<T>) => void {
+  const lastRan = useRef<number>(Date.now());
+  const timeoutRef = useRef<NodeJS.Timeout | null>(null);
+
+  const throttledCallback = useCallback(
+    (...args: Parameters<T>) => {
+      const now = Date.now();
+      const timeSinceLastRun = now - lastRan.current;
+
+      if (timeSinceLastRun >= interval) {
+        // Enough time has passed, call immediately
+        callback(...args);
+        lastRan.current = now;
+      } else {
+        // Schedule for later
+        if (timeoutRef.current) {
+          clearTimeout(timeoutRef.current);
+        }
+
+        timeoutRef.current = setTimeout(() => {
+          callback(...args);
+          lastRan.current = Date.now();
+        }, interval - timeSinceLastRun);
+      }
+    },
+    [callback, interval],
+  );
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+      }
+    };
+  }, []);
+
+  return throttledCallback;
+}

package/src/hooks/useDeepCompareEffect.ts

@@ -0,0 +1,88 @@
+/**
+ * useDeepCompareEffect Hook
+ * Effect hook with deep comparison of dependencies
+ *
+ * @example
+ * ```typescript
+ * const [user, setUser] = useState({ name: 'John', age: 30 });
+ *
+ * useDeepCompareEffect(() => {
+ *   console.log('User changed:', user);
+ *   // This effect will only run when the actual content of user changes, not on every render
+ * }, [user]);
+ * ```
+ */
+
+import { useEffect, useRef } from 'react';
+
+/**
+ * Deep comparison function
+ */
+function isEqual(a: any, b: any): boolean {
+  // Handle primitive values
+  if (a === b) return true;
+
+  // Handle null and undefined
+  if (a == null || b == null) return a === b;
+
+  // Handle objects and arrays
+  if (typeof a === 'object' && typeof b === 'object') {
+    // Check if they are the same type
+    if (a.constructor !== b.constructor) return false;
+
+    // Handle arrays
+    if (Array.isArray(a)) {
+      if (a.length !== b.length) return false;
+      for (let i = 0; i < a.length; i++) {
+        if (!isEqual(a[i], b[i])) return false;
+      }
+      return true;
+    }
+
+    // Handle objects
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+
+    if (keysA.length !== keysB.length) return false;
+
+    for (const key of keysA) {
+      if (!keysB.includes(key) || !isEqual(a[key], b[key])) return false;
+    }
+
+    return true;
+  }
+
+  // All other cases
+  return false;
+}
+
+/**
+ * Hook for deep comparison effect
+ */
+export function useDeepCompareEffect(callback: React.EffectCallback, dependencies: any[]): void {
+  // Create a ref to store the previous dependencies
+  const previousDependencies = useRef<any[]>([]);
+
+  // Check if dependencies have changed using deep comparison
+  if (!isEqual(dependencies, previousDependencies.current)) {
+    // Update the ref with current dependencies
+    previousDependencies.current = dependencies;
+  }
+
+  // Use the ref as the dependency array for useEffect
+  useEffect(callback, [callback, previousDependencies.current]);
+}
+
+/**
+ * Hook for deep comparison layout effect
+ */
+export function useDeepCompareLayoutEffect(callback: React.EffectCallback, dependencies: any[]): void {
+  const previousDependencies = useRef<any[]>([]);
+
+  if (!isEqual(dependencies, previousDependencies.current)) {
+    previousDependencies.current = dependencies;
+  }
+
+  // @ts-ignore
+  useEffect(callback, [callback, previousDependencies.current]);
+}

package/src/hooks/useEventListener.ts

@@ -0,0 +1,77 @@
+/**
+ * useEventListener Hook
+ * Simplified event listener management with automatic cleanup
+ *
+ * @example
+ * ```typescript
+ * const handleResize = (event: Event) => {
+ *   console.log('Window resized:', window.innerWidth, window.innerHeight);
+ * };
+ *
+ * useEventListener('resize', handleResize, window);
+ * ```
+ */
+
+import { useEffect, useRef } from 'react';
+
+/**
+ * Hook for simplified event listener management
+ */
+export function useEventListener<K extends keyof WindowEventMap>(
+  eventName: K,
+  handler: (event: WindowEventMap[K]) => void,
+  element?: Window,
+  options?: boolean | AddEventListenerOptions,
+): void;
+
+export function useEventListener<K extends keyof DocumentEventMap>(
+  eventName: K,
+  handler: (event: DocumentEventMap[K]) => void,
+  element?: Document,
+  options?: boolean | AddEventListenerOptions,
+): void;
+
+export function useEventListener<K extends keyof HTMLElementEventMap, T extends HTMLElement>(
+  eventName: K,
+  handler: (event: HTMLElementEventMap[K]) => void,
+  element?: T,
+  options?: boolean | AddEventListenerOptions,
+): void;
+
+export function useEventListener<K extends string, T extends HTMLElement | Document | Window = Window>(
+  eventName: K,
+  handler: (event: Event) => void,
+  element?: T,
+  options?: boolean | AddEventListenerOptions,
+): void {
+  // Create a ref to store the event handler
+  const savedHandler = useRef<(event: Event) => void>(null);
+
+  // Update the ref when the handler changes
+  useEffect(() => {
+    savedHandler.current = handler;
+  }, [handler]);
+
+  useEffect(() => {
+    // Default to window if no element is provided
+    const targetElement = element || window;
+
+    // Check if targetElement supports addEventListener
+    if (!targetElement || !targetElement.addEventListener) {
+      return;
+    }
+
+    // Create event listener that calls the ref's current value
+    const eventListener = (event: Event) => {
+      savedHandler.current?.(event);
+    };
+
+    // Add event listener
+    targetElement.addEventListener(eventName, eventListener, options);
+
+    // Clean up event listener on unmount or when dependencies change
+    return () => {
+      targetElement.removeEventListener(eventName, eventListener, options);
+    };
+  }, [eventName, element, options]);
+}

package/src/hooks/useMediaQuery.ts

@@ -0,0 +1,75 @@
+/**
+ * useMediaQuery Hook
+ * Track media query matches for responsive design
+ *
+ * @example
+ * ```typescript
+ * const isMobile = useMediaQuery('(max-width: 768px)');
+ * const isDark = useMediaQuery('(prefers-color-scheme: dark)');
+ * ```
+ */
+
+import { useState, useEffect } from 'react';
+
+/**
+ * Hook for tracking media query matches
+ */
+export function useMediaQuery(query: string): boolean {
+  // Initialize with false for SSR
+  const [matches, setMatches] = useState(false);
+
+  useEffect(() => {
+    // Check if window is defined (client-side)
+    if (typeof window === 'undefined' || !window.matchMedia) {
+      return () => {};
+    }
+
+    const mediaQuery = window.matchMedia(query);
+
+    // Set initial value
+    setMatches(mediaQuery.matches);
+
+    // Create event listener
+    const handler = (event: MediaQueryListEvent) => {
+      setMatches(event.matches);
+    };
+
+    // Modern browsers
+    if (mediaQuery.addEventListener) {
+      mediaQuery.addEventListener('change', handler);
+      return () => mediaQuery.removeEventListener('change', handler);
+    }
+    // Legacy browsers
+    else if (mediaQuery.addListener) {
+      mediaQuery.addListener(handler);
+      return () => mediaQuery.removeListener(handler);
+    }
+
+    return () => {};
+  }, [query]);
+
+  return matches;
+}
+
+/**
+ * Predefined breakpoint hooks
+ */
+export function useIsMobile(): boolean {
+  return useMediaQuery('(max-width: 768px)');
+}
+
+export function useIsTablet(): boolean {
+  return useMediaQuery('(min-width: 769px) and (max-width: 1024px)');
+}
+
+export function useIsDesktop(): boolean {
+  return useMediaQuery('(min-width: 1025px)');
+}
+
+export function usePrefersDarkMode(): boolean {
+  return useMediaQuery('(prefers-color-scheme: dark)');
+}
+
+export function usePrefersReducedMotion(): boolean {
+  return useMediaQuery('(prefers-reduced-motion: reduce)');
+}