@mwakidenis/logx-react 0.0.0-stage → 0.1.0

package/dist/hooks/index.d.ts

@@ -0,0 +1,316 @@
+import { DebouncedValueOptions, AsyncState } from '../types/index.js';
+export { useLocalStorage, useSessionStorage } from './storage/index.js';
+
+/**
+ * A boolean toggle hook.
+ *
+ * Returns the current boolean value and a stable set of actions to mutate it.
+ * All callbacks are stable (no unnecessary re-renders of consumers).
+ *
+ * @param initialValue - Initial boolean value (defaults to false)
+ */
+declare function useToggle(initialValue?: boolean): [
+    boolean,
+    {
+        toggle: () => void;
+        set: (next?: boolean) => void;
+        setTrue: () => void;
+        setFalse: () => void;
+    }
+];
+
+/**
+ * A boolean state hook with explicit setTrue/setFalse/toggle actions.
+ *
+ * Alias of useToggle with a more descriptive name. Provides stable callbacks.
+ *
+ * @param initialValue - Initial boolean value (defaults to false)
+ */
+declare function useBoolean(initialValue?: boolean): [
+    boolean,
+    {
+        setTrue: () => void;
+        setFalse: () => void;
+        toggle: () => void;
+        set: (next?: boolean) => void;
+    }
+];
+
+/**
+ * A numeric counter hook.
+ *
+ * @param initialValue - Starting value (defaults to 0)
+ */
+declare function useCounter(initialValue?: number): {
+    count: number;
+    increment: (step?: number) => void;
+    decrement: (step?: number) => void;
+    reset: () => void;
+    set: (value: number) => void;
+};
+
+/**
+ * Returns the previous value of a tracked value.
+ *
+ * On first render returns undefined (there is no previous value yet).
+ * The returned ref updates after each render so the value is always the
+ * value from the previous committed render.
+ *
+ * @param value - The value to track
+ */
+declare function usePrevious<T>(value: T): T | undefined;
+
+/**
+ * Returns a ref whose `.current` always holds the latest value without
+ * triggering re-renders. Useful for accessing the most recent value inside
+ * timers, callbacks or event listeners without stale closures.
+ *
+ * @param value - The value to track
+ */
+declare function useLatest<T>(value: T): {
+    current: T;
+};
+
+/**
+ * Returns whether the component is mounted.
+ *
+ * The value starts false (SSR-safe) and becomes true after mount. It returns
+ * to false on unmount. Use sparingly; prefer event-driven logic where possible.
+ *
+ * NOTE: Reading this during render can cause a flash of unmounted content on
+ * the client. Prefer using it inside effects or event handlers.
+ */
+declare function useMounted(): boolean;
+
+/**
+ * Array state with immutable helpers.
+ *
+ * Several helpers delegate to @mwakidenis/logx array utilities (unique,
+ * compact, first, last, take, drop, shuffle, partition, difference,
+ * intersection, union, flatten). React-specific state management is kept in
+ * this hook; LOGX provides the pure array transformations.
+ *
+ * @param initialValue - Initial array (defaults to [])
+ */
+declare function useArray<T>(initialValue?: T[]): {
+    array: T[];
+    set: (value: T[] | ((prev: T[]) => T[])) => void;
+    push: (...items: T[]) => void;
+    unshift: (...items: T[]) => void;
+    remove: (index: number) => void;
+    removeBy: (predicate: (value: T, index: number) => unknown) => void;
+    update: (index: number, value: T) => void;
+    clear: () => void;
+    reset: () => void;
+    unique: () => void;
+    compact: () => void;
+    shuffle: () => void;
+    first: () => T | undefined;
+    last: () => T | undefined;
+    take: (count: number) => T[];
+    drop: (count: number) => T[];
+    difference: (...others: T[][]) => T[];
+    intersection: (...others: T[][]) => T[];
+    union: (...others: T[][]) => T[];
+    partition: (predicate: (value: T, index: number) => unknown) => [T[], T[]];
+    flatten: () => unknown[];
+};
+
+/**
+ * Object state with immutable helpers.
+ *
+ * Several helpers delegate to @mwakidenis/logx object utilities (get, set,
+ * pick, omit, merge, keys, values, entries, clone, deepClone, mapValues).
+ * React-specific state management is kept in this hook; LOGX provides the pure
+ * object transformations.
+ *
+ * @param initialValue - Initial object (defaults to {})
+ */
+declare function useObject<T extends Record<string, unknown>>(initialValue?: T): {
+    object: T;
+    set: (value: T | ((prev: T) => T)) => void;
+    setKey: (key: string, value: unknown) => void;
+    removeKey: (key: string) => void;
+    clear: () => void;
+    reset: () => void;
+    pick: (keys: readonly string[]) => Partial<T>;
+    omit: (keys: readonly string[]) => Partial<T>;
+    merge: (sources: Partial<T>[]) => T;
+    get: (path: string | Array<string | number>) => unknown;
+    keys: () => string[];
+    values: () => unknown[];
+    entries: () => [string, unknown][];
+    clone: () => T;
+    deepClone: () => T;
+    mapValues: <U>(iteratee: (value: unknown, key: string) => U) => Record<string, U>;
+};
+
+/**
+ * Debounce a value.
+ *
+ * Returns the value after it has stopped changing for `delay` milliseconds.
+ * Uses reference equality to detect changes; for objects/arrays pass a new
+ * reference only when you want a debounce to restart.
+ *
+ * LOGX provides function debouncing (@mwakidenis/logx/function). This hook
+ * implements value debouncing (a React-specific behaviour) on top of timers;
+ * it does not map to an existing LOGX function.
+ *
+ * @param value - The value to debounce
+ * @param options - delay (ms, default 300) and leading (default false)
+ */
+declare function useDebouncedValue<T>(value: T, options?: DebouncedValueOptions): T;
+
+/**
+ * Debounce a callback using LOGX's `debounce` (@mwakidenis/logx/function).
+ *
+ * LOGX debounce is trailing-edge only: the function is invoked after `delay`
+ * milliseconds of inactivity. It exposes `cancel`, `flush` and `pending`.
+ *
+ * The latest callback reference is captured internally so the debounced
+ * function never holds a stale closure, even if `callback` changes every render.
+ *
+ * @param callback - Function to debounce
+ * @param delay - Delay in milliseconds
+ */
+declare function useDebouncedCallback<F extends (...args: unknown[]) => unknown>(callback: F, delay: number): {
+    (...args: Parameters<F>): void;
+    cancel: () => void;
+    flush: () => void;
+    pending: () => boolean;
+};
+
+/**
+ * Throttle a callback using LOGX's `throttle` (@mwakidenis/logx/function).
+ *
+ * LOGX throttle invokes on the leading edge and flushes the trailing edge at
+ * the end of the wait period. It exposes `cancel`, `flush` and `pending`.
+ *
+ * @param callback - Function to throttle
+ * @param wait - Wait period in milliseconds
+ */
+declare function useThrottle<F extends (...args: unknown[]) => unknown>(callback: F, wait: number): {
+    (...args: Parameters<F>): void;
+    cancel: () => void;
+    flush: () => void;
+    pending: () => boolean;
+};
+
+/**
+ * Track whether a media query matches.
+ *
+ * SSR-safe: returns `false` on the server and before mount, then reflects the
+ * real match status after mount. Listens for `change` events and cleans up on
+ * unmount.
+ *
+ * @param query - A CSS media query string
+ */
+declare function useMediaQuery(query: string): boolean;
+
+/**
+ * Track the window size (innerWidth / innerHeight).
+ *
+ * SSR-safe: returns { width: 0, height: 0 } on the server and first client
+ * render, then updates on resize. Cleans up the listener on unmount.
+ */
+declare function useWindowSize(): {
+    width: number;
+    height: number;
+};
+
+/**
+ * Fire a handler when a click occurs outside a ref'd element.
+ *
+ * Uses useLatest internally so the handler is always current without
+ * re-subscribing the document listeners every render.
+ *
+ * @param ref - A ref to the element to ignore clicks for
+ * @param handler - Callback fired on outside click
+ */
+declare function useClickOutside(ref: {
+    current: HTMLElement | null | undefined;
+}, handler: (event: MouseEvent | TouchEvent) => void): void;
+
+/**
+ * Attach an event listener with automatic cleanup on unmount.
+ *
+ * Supports window, document, element, or Document/Window targets. The listener
+ * is captured via a ref so it stays current without re-attaching.
+ *
+ * @param target - EventTarget (window, document, element) or null/undefined
+ * @param type - Event type
+ * @param listener - Event listener
+ * @param options - AddEventListenerOptions or capture boolean
+ */
+declare function useEventListener(target: EventTarget | null | undefined, type: string, listener: EventListener, options?: boolean | AddEventListenerOptions): void;
+
+/**
+ * Copy text to the clipboard.
+ *
+ * Uses the Clipboard API when available, with a textarea fallback for older
+ * browsers. Never throws; returns false on failure.
+ */
+declare function useClipboard(): {
+    copy: (text: string) => Promise<boolean>;
+    isSupported: boolean;
+};
+
+/**
+ * Track online/offline status.
+ *
+ * SSR-safe: assumes `true` on the server, then reads `navigator.onLine` after
+ * mount and listens for `online`/`offline` events.
+ */
+declare function useOnlineStatus(): boolean;
+
+/**
+ * A controllable timeout hook.
+ *
+ * Provides start/stop/reset and clears the timer on unmount. The callback is
+ * captured via useLatest so it never goes stale. `active` reflects whether a
+ * timeout is currently scheduled.
+ *
+ * @param callback - Function to invoke after the delay
+ * @param delay - Delay in milliseconds, or null to disable
+ */
+declare function useTimeout(callback: () => void, delay: number | null): {
+    start: () => void;
+    stop: () => void;
+    reset: () => void;
+    active: boolean;
+};
+
+/**
+ * A controllable interval hook.
+ *
+ * Provides start/stop and clears the interval on unmount. The callback is
+ * captured via useLatest so it never goes stale. `active` reflects whether an
+ * interval is currently scheduled.
+ *
+ * @param callback - Function to invoke every `delay` milliseconds
+ * @param delay - Delay in milliseconds, or null to disable
+ */
+declare function useInterval(callback: () => void, delay: number | null): {
+    start: () => void;
+    stop: () => void;
+    active: boolean;
+};
+
+/**
+ * Manage an asynchronous operation with loading, success and error states.
+ *
+ * Supports cancellation via AbortController, race-condition protection (only
+ * the latest invocation updates state), and manual execute / reset.
+ *
+ * @param asyncFn - Function returning a Promise
+ * @param immediate - Whether to invoke immediately on mount (default true)
+ */
+declare function useAsync<T>(asyncFn: () => Promise<T>, immediate?: boolean): AsyncState<T> & {
+    execute: () => Promise<void>;
+    setData: (data: T) => void;
+    setError: (error: Error) => void;
+    reset: () => void;
+    cancel: () => void;
+};
+
+export { useArray, useAsync, useBoolean, useClickOutside, useClipboard, useCounter, useDebouncedCallback, useDebouncedValue, useEventListener, useInterval, useLatest, useMediaQuery, useMounted, useObject, useOnlineStatus, usePrevious, useThrottle, useTimeout, useToggle, useWindowSize };