@siberiacancode/reactuse 0.0.111 → 0.0.113

package/dist/types/hooks/useStopwatch/useStopwatch.d.ts

@@ -0,0 +1,59 @@
+/** The use stopwatch return type */
+export interface UseStopwatchReturn {
+    /** The total count of the stopwatch */
+    count: number;
+    /** The day count of the stopwatch */
+    days: number;
+    /** The hour count of the stopwatch */
+    hours: number;
+    /** The minute count of the stopwatch */
+    minutes: number;
+    /** The over state of the stopwatch */
+    over: boolean;
+    /** The paused state of the stopwatch */
+    paused: boolean;
+    /** The second count of the stopwatch */
+    seconds: number;
+    /** The function to pause the stopwatch */
+    pause: () => void;
+    /** The function to reset the stopwatch */
+    reset: () => void;
+    /** The function to start the stopwatch */
+    start: () => void;
+    /** The function to toggle the stopwatch */
+    toggle: () => void;
+}
+/** The use stopwatch options */
+export interface UseStopwatchOptions {
+    /** The enabled state of the timer */
+    enabled?: boolean;
+}
+interface UseStopwatch {
+    (initialTime?: number, options?: UseStopwatchOptions): UseStopwatchReturn;
+    (options?: UseStopwatchOptions & {
+        initialTime?: number;
+    }): UseStopwatchReturn;
+}
+/**
+ * @name useStopwatch
+ * @description - Hook that creates a stopwatch functionality
+ * @category Time
+ *
+ * @overload
+ * @param {number} [initialTime=0] The initial time of the timer
+ * @param {boolean} [options.enabled=true] The enabled state of the timer
+ * @returns {UseStopwatchReturn} An object containing the current time and functions to interact with the timer
+ *
+ * @example
+ * const { seconds, minutes, start, pause, reset } = useStopwatch(1000, { enabled: false });
+ *
+ * @overload
+ * @param {number} [options.initialTime=0] -The initial time of the timer
+ * @param {boolean} [options.enabled=true] The enabled state of the timer
+ * @returns {UseStopwatchReturn} An object containing the current time and functions to interact with the timer
+ *
+ * @example
+ * const { seconds, minutes, start, pause, reset } = useStopwatch({ initialTime: 1000, enabled: false });
+ */
+export declare const useStopwatch: UseStopwatch;
+export {};

package/dist/types/hooks/useStorage/useStorage.d.ts

@@ -0,0 +1,40 @@
+export type UseStorageInitialValue<Value> = (() => Value) | Value;
+export interface UseStorageOptions<Value> {
+    initialValue?: UseStorageInitialValue<Value>;
+    storage?: Storage;
+    deserializer?: (value: string) => Value;
+    serializer?: (value: Value) => string;
+}
+export interface UseStorageReturn<Value> {
+    value: Value;
+    remove: () => void;
+    set: (value: Value) => void;
+}
+export declare const STORAGE_EVENT = "reactuse-storage";
+export declare const dispatchStorageEvent: (params: Partial<StorageEvent>) => boolean;
+/**
+ * @name useStorage
+ * @description - Hook that manages storage value
+ * @category Browser
+ *
+ * @overload
+ * @param {string} key The key of the storage
+ * @param {UseStorageInitialValue<Value>} [initialValue] The initial value of the storage
+ * @returns {UseStorageReturn<Value>} The value and the set function
+ *
+ * @overload
+ * @param {string} key The key of the storage
+ * @param {(value: Value) => string} [params.serializer] The serializer function
+ * @param {(value: string) => Value} [params.deserializer] The deserializer function
+ * @param {Storage} [params.storage] The storage
+ * @param {UseStorageInitialValue<Value>} [params.initialValue] The initial value of the storage
+ * @returns {UseStorageReturn<Value>} The value and the set function
+ *
+ * @example
+ * const { value, set, remove } = useStorage('key', 'value');
+ */
+export declare const useStorage: <Value>(key: string, params?: UseStorageInitialValue<Value> | UseStorageOptions<Value>) => {
+    value: Value | undefined;
+    set: (value: Value) => void;
+    remove: () => void;
+};

package/dist/types/hooks/useTextDirection/useTextDirection.d.ts

@@ -0,0 +1,41 @@
+import { HookTarget } from '../../utils/helpers';
+import { StateRef } from '../useRefState/useRefState';
+/** The use text direction value type */
+export type UseTextDirectionValue = 'auto' | 'ltr' | 'rtl';
+/** The use text direction return type */
+export interface UseTextDirectionReturn {
+    /** The current direction */
+    value: UseTextDirectionValue;
+    /*** The function to remove the direction */
+    remove: () => void;
+    /*** The function to set the direction */
+    set: (value: UseTextDirectionValue | null) => void;
+}
+export interface UseTextDirection {
+    (target: HookTarget, initialValue?: UseTextDirectionValue): UseTextDirectionReturn;
+    <Target extends Element>(initialValue?: UseTextDirectionValue, target?: never): UseTextDirectionReturn & {
+        ref: StateRef<Target>;
+    };
+}
+/**
+ * @name useTextDirection
+ * @description - Hook that can get and set the direction of the element
+ * @category Browser
+ *
+ * @overload
+ * @param {HookTarget} target The target element to observe
+ * @param {UseTextDirectionValue} [initialValue = 'ltr'] The initial direction of the element
+ * @returns {UseTextDirectionReturn} An object containing the current text direction of the element
+ *
+ * @example
+ * const { value, set, remove } = useTextDirection(ref);
+ *
+ * @overload
+ * @template Target The target element type
+ * @param {UseTextDirectionValue} [initialValue = 'ltr'] The initial direction of the element
+ * @returns { { ref: StateRef<Target> } & UseTextDirectionReturn } An object containing the current text direction of the element
+ *
+ * @example
+ * const { ref, value, set, remove } = useTextDirection();
+ */
+export declare const useTextDirection: UseTextDirection;

package/dist/types/hooks/useTextSelection/useTextSelection.d.ts

@@ -0,0 +1,25 @@
+export declare const getRangesSelection: (selection: Selection) => Range[];
+/** The use text selection return type */
+export interface UseTextSelectionReturn {
+    /** The current selection ranges */
+    ranges: Range[];
+    /** The current selection rects */
+    rects: DOMRect[];
+    /** The current selection */
+    selection: Selection | null;
+    /** The current selection text */
+    text: string;
+}
+/**
+ * @name useTextSelection
+ * @description - Hook that manages the text selection
+ * @category Sensors
+ *
+ * @browserapi document.getSelection https://developer.mozilla.org/en-US/docs/Web/API/Document/getSelection
+ *
+ * @returns {UseTextSelectionReturn} An object containing the current text selection
+ *
+ * @example
+ * const selection = useTextSelection();
+ */
+export declare const useTextSelection: () => UseTextSelectionReturn;

package/dist/types/hooks/useThrottleCallback/useThrottleCallback.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @name useThrottleCallback
+ * @description - Hook that creates a throttled callback
+ * @category Utilities
+ *
+ * @template Params The type of the params
+ * @template Return The type of the return
+ * @param {(...args: Params) => Return} callback The callback function
+ * @param {number} delay The delay in milliseconds
+ * @returns {(...args: Params) => Return} The callback with throttle
+ *
+ * @example
+ * const throttled = useThrottleCallback(() => console.log('callback'), 500);
+ */
+export declare const useThrottleCallback: <Params extends unknown[], Return>(callback: (...args: Params) => Return, delay: number) => (...args: Params) => void;

package/dist/types/hooks/useThrottleValue/useThrottleValue.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @name useThrottleValue
+ * @description - Hook that creates a throttled value
+ * @category Utilities
+ *
+ * @template Value The type of the value
+ * @param {Value} value The value to be throttled
+ * @param {number} delay The delay in milliseconds
+ * @returns {Value} The throttled value
+ *
+ * @example
+ * const throttledValue = useThrottleValue(value, 500);
+ */
+export declare const useThrottleValue: <Value>(value: Value, delay: number) => Value;

package/dist/types/hooks/useTime/useTime.d.ts

@@ -0,0 +1,24 @@
+export interface UseTimeReturn {
+    day: number;
+    hours: number;
+    meridiemHours: {
+        value: number;
+        type: string;
+    };
+    minutes: number;
+    month: number;
+    seconds: number;
+    timestamp: number;
+    year: number;
+}
+/**
+ * @name useTime
+ * @description - Hook that gives you current time in different values
+ * @category Time
+ *
+ * @returns {UseTimeReturn} An object containing the current time
+ *
+ * @example
+ * const { seconds, minutes, hours, meridiemHours, day, month, year, timestamp } = useTime();
+ */
+export declare const useTime: () => UseTimeReturn;

package/dist/types/hooks/useTimeout/useTimeout.d.ts

@@ -0,0 +1,21 @@
+/** The use timeout return type */
+interface UseTimeoutReturn {
+    /**  Timeout is ready state value */
+    ready: boolean;
+    /** Function to clear timeout */
+    clear: () => void;
+}
+/**
+ * @name useTimeout
+ * @description - Hook that executes a callback function after a specified delay
+ * @category Time
+ *
+ * @param {() => void} callback The function to be executed after the timeout
+ * @param {number} delay The delay in milliseconds before the timeout executes the callback function
+ * @returns {UseTimeoutReturn} An object with a `ready` boolean state value and a `clear` function to clear timeout
+ *
+ * @example
+ * const { clear, ready } = useTimeout(() => {}, 5000);
+ */
+export declare function useTimeout(callback: () => void, delay: number): UseTimeoutReturn;
+export {};

package/dist/types/hooks/useTimer/useTimer.d.ts

@@ -0,0 +1,84 @@
+export type PositiveInteger<Value extends number> = `${Value}` extends `-${any}` | `${any}.${any}` ? never : Value;
+export declare const getTimeFromSeconds: (timestamp: number) => {
+    seconds: number;
+    minutes: number;
+    hours: number;
+    days: number;
+};
+/** The use timer options type */
+export interface UseTimerOptions {
+    /** Whether the timer should start automatically */
+    immediately?: boolean;
+    /** The function to be executed when the timer is expired */
+    onExpire?: () => void;
+    /** The function to be executed when the timer is started */
+    onStart?: () => void;
+    /** Callback function to be executed on each tick of the timer */
+    onTick?: (seconds: number) => void;
+}
+/** The use timer return type */
+export interface UseTimerReturn {
+    /** flag to indicate if timer is active or not */
+    active: boolean;
+    /** The total count of the timer */
+    count: number;
+    /** The day count of the timer */
+    days: number;
+    /** The hour count of the timer */
+    hours: number;
+    /** The minute count of the timer */
+    minutes: number;
+    /** The second count of the timer */
+    seconds: number;
+    /** The function to clear the timer */
+    clear: () => void;
+    /** The function to decrease the timer */
+    decrease: (seconds: PositiveInteger<number>) => void;
+    /** The function to increase the timer */
+    increase: (seconds: PositiveInteger<number>) => void;
+    /** The function to pause the timer */
+    pause: () => void;
+    /** The function to restart the timer */
+    restart: (time: PositiveInteger<number>, immediately?: boolean) => void;
+    /** The function to resume the timer */
+    resume: () => void;
+    /** The function to start the timer */
+    start: () => void;
+    /** The function to toggle the timer */
+    toggle: () => void;
+}
+export interface UseTimer {
+    (): UseTimerReturn;
+    (seconds: PositiveInteger<number>, callback: () => void): UseTimerReturn;
+    (seconds: PositiveInteger<number>, options?: UseTimerOptions): UseTimerReturn;
+}
+/**
+ * @name useTimer
+ * @description - Hook that creates a timer functionality
+ * @category Time
+ *
+ * @overload
+ * @returns {UseTimerReturn} An object containing the timer properties and functions
+ *
+ * @example
+ * const { days, hours, minutes, seconds, toggle, pause, start, restart, resume, active, decrease, increase } = useTimer();
+ *
+ * @overload
+ * @param {number} seconds The seconds value that define for how long the timer will be running
+ * @param {() => void} callback The function to be executed once countdown timer is expired
+ * @returns {UseTimerReturn} An object containing the timer properties and functions
+ *
+ * @example
+ * const { days, hours, minutes, seconds, toggle, pause, start, restart, resume, active, decrease, increase } = useTimer(1000, () => console.log('ready'));
+ *
+ * @overload
+ * @param {number} seconds The seconds value that define for how long the timer will be running
+ * @param {boolean} [options.immediately=true] The flag to decide if timer should start automatically
+ * @param {() => void} [options.onExpire] The function to be executed when the timer is expired
+ * @param {(timestamp: number) => void} [options.onTick] The function to be executed on each tick of the timer
+ * @returns {UseTimerReturn} An object containing the timer properties and functions
+ *
+ * @example
+ * const { days, hours, minutes, seconds, toggle, pause, start, restart, resume, active, decrease, increase } = useTimer(1000);
+ */
+export declare const useTimer: UseTimer;

package/dist/types/hooks/useToggle/useToggle.d.ts

@@ -0,0 +1,18 @@
+import { SetStateAction } from 'react';
+/** The use toggle return type */
+export type UseToggleReturn<Value> = readonly [Value, (value?: Value) => void];
+/**
+ * @name useToggle
+ * @description - Hook that create toggle
+ * @category Utilities
+ *
+ * @template Value The type of the value
+ * @param {Value[]} [values=[false, true]] The values to toggle
+ *
+ * @example
+ * const [on, toggle] = useToggle();
+ *
+ * @example
+ * const [value, toggle] = useToggle(['light', 'dark'] as const);
+ */
+export declare const useToggle: <Value = boolean>(values?: readonly Value[]) => readonly [Value, (value?: SetStateAction<Value>) => void];

package/dist/types/hooks/useUnmount/useUnmount.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @name useUnmount
+ * @description - Hook that defines the logic when unmounting a component
+ * @category Lifecycle
+ *
+ * @param {() => void} callback The callback function to be invoked on component unmount
+ * @returns {void}
+ *
+ * @example
+ * useUnmount(() => console.log('This effect runs on component unmount'));
+ */
+export declare const useUnmount: (callback: () => void) => void;

package/dist/types/hooks/useVibrate/useVibrate.d.ts

@@ -0,0 +1,40 @@
+/** The use vibrate pattern type */
+export type UseVibratePattern = number | number[];
+/** The use vibrate return type */
+export interface UseVibrateReturn {
+    /** The support indicator */
+    supported: boolean;
+    /** The vibrating indicator */
+    vibrating: boolean;
+    /** The pause function */
+    pause: () => void;
+    /** The resume function */
+    resume: () => void;
+    /** The start function */
+    start: (interval: number) => void;
+    /** The vibrate function */
+    trigger: (pattern?: UseVibratePattern) => void;
+}
+/**
+ * @name useVibrate
+ * @description - Hook that provides vibrate api
+ * @category Browser
+ *
+ * @browserapi navigator.vibrate https://developer.mozilla.org/en-US/docs/Web/API/Navigator/vibrate
+ *
+ * @overload
+ * @param {UseVibratePattern} options.pattern The pattern for vibration
+ * @param {number} [options.interval=0] Time in milliseconds between vibrations
+ * @returns {UseVibrateReturn} An object containing support indicator, start vibration and stop vibration functions
+ *
+ * @example
+ * const { supported, active, vibrate, stop, pause, resume } = useVibrate(1000);
+ */
+export declare const useVibrate: (pattern: UseVibratePattern, interval?: number) => {
+    supported: boolean;
+    trigger: (internalPattern?: UseVibratePattern) => void;
+    stop: () => void;
+    active: boolean;
+    pause: () => void;
+    resume: (intervalInterval?: number) => void;
+};

package/dist/types/hooks/useWebSocket/useWebSocket.d.ts

@@ -0,0 +1,35 @@
+export type UseWebSocketUrl = (() => string) | string;
+export interface UseWebSocketOptions {
+    protocols?: Array<'soap' | 'wasm'>;
+    retry?: boolean | number;
+    onConnected?: (webSocket: WebSocket) => void;
+    onDisconnected?: (event: CloseEvent, webSocket: WebSocket) => void;
+    onError?: (event: Event, webSocket: WebSocket) => void;
+    onMessage?: (event: MessageEvent, webSocket: WebSocket) => void;
+}
+export type UseWebSocketStatus = 'connected' | 'connecting' | 'disconnected' | 'failed';
+export interface UseWebSocketReturn {
+    client?: WebSocket;
+    close: WebSocket['close'];
+    send: WebSocket['send'];
+    status: UseWebSocketStatus;
+    open: () => void;
+}
+/**
+ * @name useWebSocket
+ * @description - Hook that connects to a WebSocket server and handles incoming and outgoing messages
+ * @category Browser
+ *
+ * @param {UseWebSocketUrl} url The URL of the WebSocket server
+ * @param {(webSocket: WebSocket) => void} [options.onConnected] The callback function that is called when the WebSocket connection is established
+ * @param {(event: CloseEvent, webSocket: WebSocket) => void} [options.onDisconnected] The callback function that is called when the WebSocket connection is closed
+ * @param {(event: Event, webSocket: WebSocket) => void} [options.onError] The callback function that is called when an error occurs
+ * @param {(event: MessageEvent, webSocket: WebSocket) => void} [options.onMessage] The callback function that is called when a message is received
+ * @param {boolean | number} [options.retry] The number of times to retry the connection
+ * @param {Array<'soap' | 'wasm'>} [options.protocols] The list of protocols to use
+ * @returns {UseWebSocketReturn} An object with the status, close, send, open, and ws properties
+ *
+ * @example
+ * const { status, close, send, open, client } = useWebSocket('url');
+ */
+export declare const useWebSocket: (url: UseWebSocketUrl, options?: UseWebSocketOptions) => UseWebSocketReturn;

package/dist/types/hooks/useWindowEvent/useWindowEvent.d.ts

@@ -0,0 +1,16 @@
+import { UseEventListenerOptions } from '../useEventListener/useEventListener';
+/**
+ * @name useWindowEvent
+ * @description - Hook attaches an event listener to the window object for the specified event
+ * @category Browser
+ *
+ * @template Event Key of window event map.
+ * @param {Event} event The event to listen for.
+ * @param {(event: WindowEventMap[Event]) => void} listener The callback function to be executed when the event is triggered
+ * @param {UseEventListenerOptions} [options] The options for the event listener
+ * @returns {void}
+ *
+ * @example
+ * useWindowEvent('click', () => console.log('clicked'));
+ */
+export declare const useWindowEvent: <Event extends keyof WindowEventMap>(event: Event, listener: (this: Window, event: WindowEventMap[Event]) => any, options?: UseEventListenerOptions) => void;

package/dist/types/hooks/useWindowFocus/useWindowFocus.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @name useWindowFocus
+ * @description - Hook that provides the current focus state of the window
+ * @category Elements
+ *
+ * @returns {boolean} The current focus state of the window
+ *
+ * @example
+ * const focused = useWindowFocus();
+ */
+export declare const useWindowFocus: () => boolean;

package/dist/types/hooks/useWindowScroll/useWindowScroll.d.ts

@@ -0,0 +1,19 @@
+export interface ScrollPosition {
+    x: number;
+    y: number;
+}
+export declare const scrollTo: ({ x, y, behavior }: Partial<ScrollPosition & ScrollOptions>) => void;
+/**
+ * @name useWindowScroll
+ * @description - Hook that manages the window scroll position
+ * @category Browser
+ *
+ * @returns {UseWindowScrollReturn} An object containing the current window scroll position
+ *
+ * @example
+ * const { value, scrollTo } = useWindowScroll();
+ */
+export declare const useWindowScroll: () => {
+    value: ScrollPosition;
+    scrollTo: ({ x, y, behavior }: Partial<ScrollPosition & ScrollOptions>) => void;
+};

package/dist/types/hooks/useWindowSize/useWindowSize.d.ts

@@ -0,0 +1,29 @@
+/** The use window size return type */
+interface UseWindowSizeParams {
+    /** Whether to include the scrollbar in the window size calculation */
+    includeScrollbar?: boolean;
+}
+/** The use window size return type */
+export interface UseWindowSizeReturn {
+    /** The current window height */
+    height: number;
+    /** The current window width */
+    width: number;
+}
+/**
+ * @name useWindowSize
+ * @description - Hook that manages a window size
+ * @category Elements
+ *
+ * @param {number} [params.initialWidth=Number.POSITIVE_INFINITY] The initial window width
+ * @param {number} [params.initialHeight=Number.POSITIVE_INFINITY] The initial window height
+ * @returns {UseWindowSizeReturn} An object containing the current window width and height
+ *
+ * @example
+ * const { width, height } = useWindowSize();
+ */
+export declare const useWindowSize: (params?: UseWindowSizeParams) => {
+    width: number;
+    height: number;
+};
+export {};

package/dist/types/hooks/useWizard/useWizard.d.ts

@@ -0,0 +1,27 @@
+export interface WizardItem<WizardStepId> {
+    id: WizardStepId;
+    nodes?: WizardStepId[];
+}
+/**
+ * @name useWizard
+ * @description - Hook that manages a wizard
+ * @category Utilities
+ *
+ * @param {WizardItem<WizardStepId>[]} map The map of the wizard
+ * @param {WizardStepId} [initialStepId] The initial step id
+ * @returns {UseWizardReturn<WizardStepId>} An object containing the current step id and functions to interact with the wizard
+ *
+ * @example
+ * const { currentStepId, set, reset, back, history } = useWizard([
+ *  { id: 'step1', nodes: ['step2', 'step3'] },
+ *  { id: 'step2', nodes: ['step3'] },
+ *  { id: 'step3', nodes: [] },
+ * ])
+ */
+export declare const useWizard: <WizardStepId extends string>(map: WizardItem<WizardStepId>[], initialStepId?: WizardStepId) => {
+    currentStepId: WizardStepId;
+    set: (id: WizardStepId) => void;
+    reset: () => void;
+    back: () => void;
+    history: WizardStepId[];
+};