@tarsis/toolkit 0.4.7 → 0.5.0

package/dist/hooks.cjs

@@ -0,0 +1,24 @@
+'use strict';
+
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const useWindowReady = require('./useWindowReady-CESjx5iD.cjs');
+
+
+
+exports.useAnimatedText = useWindowReady.useAnimatedText;
+exports.useBowser = useWindowReady.useBowser;
+exports.useDebounce = useWindowReady.useDebounce;
+exports.useEffectEvent = useWindowReady.useEffectEvent;
+exports.useInterval = useWindowReady.useInterval;
+exports.useLiveRef = useWindowReady.useLiveRef;
+exports.useMatchMedia = useWindowReady.useMatchMedia;
+exports.useOklch = useWindowReady.useOklch;
+exports.useOutsideClick = useWindowReady.useOutsideClick;
+exports.usePreviousRender = useWindowReady.usePreviousRender;
+exports.usePreviousState = useWindowReady.usePreviousState;
+exports.useRaf = useWindowReady.useRaf;
+exports.useThrottle = useWindowReady.useThrottle;
+exports.useTimeout = useWindowReady.useTimeout;
+exports.useUniversalLayoutEffect = useWindowReady.useUniversalLayoutEffect;
+exports.useWindowReady = useWindowReady.useWindowReady;

package/dist/hooks.d.ts

@@ -0,0 +1,190 @@
+import { default as default_2 } from 'react';
+import { DependencyList } from 'react';
+import { RefObject } from 'react';
+
+export declare function useAnimatedText(text: string, delimiter?: 'letter' | 'word'): string;
+
+export declare const useBowser: () => UseBowserResult | null;
+
+declare interface UseBowserResult {
+    isMobile: boolean;
+    isDesktop: boolean;
+    isMacOS: boolean;
+    isIOS: boolean;
+    isSafari: boolean;
+    isFirefox: boolean;
+    isChrome: boolean;
+}
+
+/**
+ * Custom hook that debounces a callback function to delay its execution until after
+ * a specified wait time has elapsed since the last time it was invoked.
+ *
+ * Debouncing ensures that the callback is only executed once after a series of rapid calls,
+ * waiting for a pause in the calls before executing.
+ *
+ * @param callback - The function to debounce
+ * @param delay - The delay time (in milliseconds) to wait before executing the callback
+ * @returns A debounced version of the callback function
+ *
+ * @example
+ * ```tsx
+ * const debouncedSearch = useDebounce((query: string) => {
+ *   console.log('Searching for:', query)
+ * }, 300)
+ *
+ * return <input onChange={(e) => debouncedSearch(e.target.value)} />
+ * ```
+ */
+export declare const useDebounce: <T extends (...args: any[]) => any>(callback: T, delay: number) => T;
+
+/**
+ * A React hook that implements the useEffectEvent pattern from React RFC.
+ * This hook allows you to define an event handler that can access the latest props/state
+ * without triggering effect dependency lists when the handler changes.
+ * @see https://github.com/reactjs/rfcs/blob/useevent/text/0000-useevent.md#internal-implementation
+ * @react https://react.dev/learn/separating-events-from-effects
+ */
+export declare function useEffectEvent<TArgs extends any[], TReturn extends undefined>(callback: undefined): (...args: TArgs) => TReturn;
+
+export declare function useEffectEvent<TArgs extends any[], TReturn>(callback: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+
+export declare function useEffectEvent<TArgs extends any[], TReturn>(callback: ((...args: TArgs) => TReturn) | undefined): (...args: TArgs) => TReturn | undefined;
+
+/**
+ * Custom hook that manages an interval with automatic cleanup.
+ * Provides a reliable way to handle intervals that are properly cleaned up
+ * on component unmount or when dependencies change.
+ *
+ * @param callback - The function to execute on each interval
+ * @param delay - The delay in milliseconds (null to clear the interval)
+ * @param deps - Optional dependency array. If provided, interval restarts when deps change.
+ *               If not provided, callback updates via ref without restarting interval.
+ *
+ * @example
+ * ```tsx
+ * // Runs continuously, callback updates via ref
+ * useInterval(() => {
+ *   console.log('This runs every second')
+ * }, 1000)
+ *
+ * // Restarts interval when count changes
+ * useInterval(() => {
+ *   console.log('Count:', count)
+ * }, 1000, [count])
+ * ```
+ */
+export declare const useInterval: (callback: VoidFunction, delay?: number | null, deps?: DependencyList) => void;
+
+export declare const useLiveRef: <T>(value: T) => RefObject<T>;
+
+export declare const useMatchMedia: (query: string) => boolean | null;
+
+export declare const useOklch: () => void;
+
+/**
+ * Custom hook that detects clicks outside of a specified element and triggers a callback.
+ *
+ * Useful for implementing dropdown menus, modals, or any component that should close
+ * when the user clicks outside of it.
+ *
+ * @param ref - React ref object pointing to the element to monitor
+ * @param callback - Function to call when a click occurs outside the element
+ * @param isActive - Whether the outside click detection should be active (default: true)
+ *
+ * @example
+ * ```tsx
+ * const ref = useRef<HTMLDivElement>(null)
+ * const [isOpen, setIsOpen] = useState(false)
+ *
+ * useOutsideClick(ref, () => setIsOpen(false), isOpen)
+ *
+ * return <div ref={ref}>...</div>
+ * ```
+ */
+export declare const useOutsideClick: <T extends HTMLElement = HTMLElement>(ref: RefObject<T | null>, callback: VoidFunction, isActive?: boolean) => void;
+
+export declare const usePreviousRender: <T>(value: T) => T | undefined;
+
+export declare const usePreviousState: <T>(value: T) => T | undefined;
+
+/**
+ * Custom hook that provides a requestAnimationFrame-based callback execution.
+ * Useful for performance-critical animations and continuous updates that should
+ * be synchronized with the browser's refresh rate.
+ *
+ * The callback will be executed on the next animation frame, and can be
+ * controlled with an enabled flag for conditional execution.
+ *
+ * @param callback - The function to execute on each animation frame
+ * @param enabled - Whether the animation loop should be active (default: true)
+ * @returns A function to manually trigger the animation frame callback
+ *
+ * @example
+ * ```tsx
+ * const animate = useRaf(() => {
+ *   // Animation logic here
+ *   console.log('Animation frame')
+ * }, isAnimating)
+ *
+ * // Manually trigger
+ * animate()
+ * ```
+ */
+export declare const useRaf: (callback: VoidFunction, enabled?: boolean) => VoidFunction;
+
+/**
+ * Custom hook that throttles a callback function to limit how often it can be invoked.
+ *
+ * Throttling ensures that the callback is executed at most once per specified time interval,
+ * regardless of how many times the throttled function is called.
+ *
+ * @param callback - The function to throttle
+ * @param delay - The minimum time interval (in milliseconds) between executions
+ * @returns A throttled version of the callback function
+ *
+ * @example
+ * ```tsx
+ * const throttledClick = useThrottle(() => {
+ *   console.log('Button clicked')
+ * }, 500)
+ *
+ * return <button onClick={throttledClick}>Click me</button>
+ * ```
+ */
+export declare const useThrottle: <T extends (...args: any[]) => any>(callback: T, delay: number) => T;
+
+/**
+ * Custom hook that manages a timeout with automatic cleanup.
+ * Provides a reliable way to handle timeouts that are properly cleaned up
+ * on component unmount or when dependencies change.
+ *
+ * @param callback - The function to execute after the delay
+ * @param delay - The delay in milliseconds (null to clear the timeout)
+ * @param deps - Optional dependency array. If provided, timeout restarts when deps change.
+ *               If not provided, callback updates via ref without restarting timeout.
+ *
+ * @example
+ * ```tsx
+ * // Runs once, callback updates via ref
+ * useTimeout(() => {
+ *   console.log('This runs after 1 second')
+ * }, 1000)
+ *
+ * // Restarts timeout when count changes
+ * useTimeout(() => {
+ *   console.log('Count:', count)
+ * }, 1000, [count])
+ * ```
+ */
+export declare const useTimeout: (callback: VoidFunction, delay?: number | null, deps?: DependencyList) => void;
+
+/**
+ * Universal layout effect that uses useLayoutEffect in browser environments
+ * and falls back to useEffect in SSR environments
+ */
+export declare const useUniversalLayoutEffect: typeof default_2.useEffect;
+
+export declare const useWindowReady: () => boolean;
+
+export { }

package/dist/hooks.js

@@ -0,0 +1 @@
+export { u as useAnimatedText, a as useBowser, b as useDebounce, d as useEffectEvent, e as useInterval, f as useLiveRef, g as useMatchMedia, h as useOklch, i as useOutsideClick, k as usePreviousRender, j as usePreviousState, l as useRaf, m as useThrottle, n as useTimeout, c as useUniversalLayoutEffect, o as useWindowReady } from './useWindowReady-CIGrizO6.js';