sse-hooks 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,327 @@
+import React, { useEffect } from 'react';
+
+/** The useBoolean return type. */
+type UseBooleanReturn = {
+    /** The current boolean state value. */
+    value: boolean;
+    /** Function to set the boolean state directly. */
+    setValue: React.Dispatch<React.SetStateAction<boolean>>;
+    /** Function to set the boolean state to `true`. */
+    setTrue: () => void;
+    /** Function to set the boolean state to `false`. */
+    setFalse: () => void;
+    /** Function to toggle the boolean state. */
+    toggle: () => void;
+};
+/**
+ * Custom hook that handles boolean state with useful utility functions.
+ * @param {boolean} [defaultValue] - The initial value for the boolean state (default is `false`).
+ * @returns {UseBooleanReturn} An object containing the boolean state value and utility functions to manipulate the state.
+ * @throws Will throw an error if `defaultValue` is an invalid boolean value.
+ * @public
+ * @example
+ * ```tsx
+ * const { value, setTrue, setFalse, toggle } = useBoolean(true);
+ * ```
+ */
+declare function useBoolean(defaultValue?: boolean): UseBooleanReturn;
+
+/**
+ * The copied text as `string` or `null` if nothing has been copied yet.
+ */
+type CopiedValue = string | null;
+/**
+ * Function to copy text to the clipboard.
+ * @param text - The text to copy to the clipboard.
+ * @returns {Promise<boolean>} A promise that resolves to `true` if the text was copied successfully, or `false` otherwise.
+ */
+type CopyFn = (text: string) => Promise<boolean>;
+/**
+ * Custom hook that copies text to the clipboard using the [`Clipboard API`](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API).
+ * @returns {[CopiedValue, CopyFn]} An tuple containing the copied text and a function to copy text to the clipboard.
+ * @public
+ * @example
+ * ```tsx
+ * const [copiedText, copyToClipboard] = useCopyToClipboard();
+ * const textToCopy = 'Hello, world!';
+ *
+ * // Attempt to copy text to the clipboard
+ * copyToClipboard(textToCopy)
+ *   .then(success => {
+ *     if (success) {
+ *       console.log(`Text "${textToCopy}" copied to clipboard successfully.`);
+ *     } else {
+ *       console.error('Failed to copy text to clipboard.');
+ *     }
+ *   });
+ * ```
+ */
+declare function useCopyToClipboard(): [CopiedValue, CopyFn];
+
+type CountdownOptions = {
+    countStart: number;
+    intervalMs?: number;
+    isIncrement?: boolean;
+    countStop?: number;
+};
+type CountdownControllers = {
+    startCountdown: () => void;
+    stopCountdown: () => void;
+    resetCountdown: () => void;
+};
+declare function useCountdown({ countStart, countStop, intervalMs, isIncrement, }: CountdownOptions): [number, CountdownControllers];
+
+type UseCounterReturn = {
+    count: number;
+    increment: () => void;
+    decrement: () => void;
+    reset: () => void;
+    setCount: React.Dispatch<React.SetStateAction<number>>;
+};
+declare function useCounter(initialValue?: number): UseCounterReturn;
+
+type DarkModeOptions = {
+    defaultValue?: boolean;
+    localStorageKey?: string;
+    initializeWithValue?: boolean;
+};
+type DarkModeReturn = {
+    isDarkMode: boolean;
+    toggle: () => void;
+    enable: () => void;
+    disable: () => void;
+    set: (value: boolean) => void;
+};
+declare function useDarkMode(options?: DarkModeOptions): DarkModeReturn;
+
+type DebounceOptions = {
+    leading?: boolean;
+    trailing?: boolean;
+    maxWait?: number;
+};
+type ControlFunctions = {
+    cancel: () => void;
+    flush: () => void;
+    isPending: () => boolean;
+};
+type DebouncedState<T extends (...args: any) => ReturnType<T>> = ((...args: Parameters<T>) => ReturnType<T> | undefined) & ControlFunctions;
+declare function useDebounceCallback<T extends (...args: any) => ReturnType<T>>(func: T, delay?: number, options?: DebounceOptions): DebouncedState<T>;
+
+type UseDebounceValueOptions<T> = {
+    leading?: boolean;
+    trailing?: boolean;
+    maxWait?: number;
+    equalityFn?: (left: T, right: T) => boolean;
+};
+declare function useDebounceValue<T>(initialValue: T | (() => T), delay: number, options?: UseDebounceValueOptions<T>): [T, DebouncedState<(value: T) => void>];
+
+type UseDocumentTitleOptions = {
+    preserveTitleOnUnmount?: boolean;
+};
+declare function useDocumentTitle(title: string, options?: UseDocumentTitleOptions): void;
+
+declare function useEventCallback<Args extends unknown[], R>(fn: (...args: Args) => R): (...args: Args) => R;
+declare function useEventCallback<Args extends unknown[], R>(fn: ((...args: Args) => R) | undefined): ((...args: Args) => R) | undefined;
+
+declare function useEventListener<K extends keyof MediaQueryListEventMap>(eventName: K, handler: (event: MediaQueryListEventMap[K]) => void, element: React.RefObject<MediaQueryList>, options?: boolean | AddEventListenerOptions): void;
+declare function useEventListener<K extends keyof WindowEventMap>(eventName: K, handler: (event: WindowEventMap[K]) => void, element?: undefined, options?: boolean | AddEventListenerOptions): void;
+declare function useEventListener<K extends keyof HTMLElementEventMap & keyof SVGElementEventMap, T extends Element = K extends keyof HTMLElementEventMap ? HTMLDivElement : SVGElement>(eventName: K, handler: ((event: HTMLElementEventMap[K]) => void) | ((event: SVGElementEventMap[K]) => void), element: React.RefObject<T>, options?: boolean | AddEventListenerOptions): void;
+declare function useEventListener<K extends keyof DocumentEventMap>(eventName: K, handler: (event: DocumentEventMap[K]) => void, element: React.RefObject<Document>, options?: boolean | AddEventListenerOptions): void;
+
+interface UseFetchOptions extends RequestInit {
+    immediate?: boolean;
+    onSuccess?: (data: any) => void;
+    onError?: (error: Error) => void;
+}
+interface UseFetchState<T> {
+    data: T | null;
+    loading: boolean;
+    error: Error | null;
+}
+interface UseFetchReturn<T> extends UseFetchState<T> {
+    execute: (url?: string, options?: RequestInit) => Promise<T | null>;
+    abort: () => void;
+    reset: () => void;
+}
+declare function useFetch<T = any>(url?: string, options?: UseFetchOptions): UseFetchReturn<T>;
+declare function useGet<T = any>(url?: string, options?: UseFetchOptions): UseFetchReturn<T>;
+declare function usePost<T = any>(url?: string, options?: UseFetchOptions): UseFetchReturn<T>;
+declare function usePut<T = any>(url?: string, options?: UseFetchOptions): UseFetchReturn<T>;
+declare function useDelete<T = any>(url?: string, options?: UseFetchOptions): UseFetchReturn<T>;
+
+declare function useHover<T extends HTMLElement = HTMLElement>(elementRef: React.RefObject<T>): boolean;
+
+interface UseIndexedDBOptions {
+    version?: number;
+    onUpgradeNeeded?: (db: IDBDatabase, oldVersion: number, newVersion: number) => void;
+}
+interface UseIndexedDBReturn<T> {
+    data: T | null;
+    error: string | null;
+    loading: boolean;
+    setItem: (key: string, value: T) => Promise<void>;
+    getItem: (key: string) => Promise<T | null>;
+    removeItem: (key: string) => Promise<void>;
+    clear: () => Promise<void>;
+    getAllKeys: () => Promise<string[]>;
+}
+declare function useIndexedDB<T>(databaseName: string, storeName: string, options?: UseIndexedDBOptions): UseIndexedDBReturn<T>;
+
+type UseIntersectionObserverOptions = {
+    root?: Element | Document | null;
+    rootMargin?: string;
+    threshold?: number | number[];
+    freezeOnceVisible?: boolean;
+    onChange?: (isIntersecting: boolean, entry: IntersectionObserverEntry) => void;
+    initialIsIntersecting?: boolean;
+};
+type IntersectionReturn = [
+    (node?: Element | null) => void,
+    boolean,
+    IntersectionObserverEntry | undefined
+] & {
+    ref: (node?: Element | null) => void;
+    isIntersecting: boolean;
+    entry?: IntersectionObserverEntry;
+};
+declare function useIntersectionObserver({ threshold, root, rootMargin, freezeOnceVisible, initialIsIntersecting, onChange, }?: UseIntersectionObserverOptions): IntersectionReturn;
+
+declare function useInterval(callback: () => void, delay: number | null): void;
+
+declare function useIsClient(): boolean;
+
+declare function useIsMounted(): () => boolean;
+
+declare const useIsomorphicLayoutEffect: typeof useEffect;
+
+declare global {
+    interface WindowEventMap {
+        "local-storage": CustomEvent;
+    }
+}
+type UseLocalStorageOptions<T> = {
+    serializer?: (value: T) => string;
+    deserializer?: (value: string) => T;
+    initializeWithValue?: boolean;
+};
+declare function useLocalStorage<T>(key: string, initialValue: T | (() => T), options?: UseLocalStorageOptions<T>): [T, React.Dispatch<React.SetStateAction<T>>, () => void];
+
+type MapOrEntries<K, V> = Map<K, V> | [K, V][];
+type UseMapActions<K, V> = {
+    set: (key: K, value: V) => void;
+    setAll: (entries: MapOrEntries<K, V>) => void;
+    remove: (key: K) => void;
+    reset: Map<K, V>["clear"];
+};
+type UseMapReturn<K, V> = [
+    Omit<Map<K, V>, "set" | "clear" | "delete">,
+    UseMapActions<K, V>
+];
+declare function useMap<K, V>(initialState?: MapOrEntries<K, V>): UseMapReturn<K, V>;
+
+type UseMediaQueryOptions = {
+    defaultValue?: boolean;
+    initializeWithValue?: boolean;
+};
+declare function useMediaQuery(query: string, { defaultValue, initializeWithValue, }?: UseMediaQueryOptions): boolean;
+
+type Options<T, InitializeWithValue extends boolean | undefined> = {
+    deserializer?: (value: string) => T;
+    initializeWithValue: InitializeWithValue;
+};
+declare function useReadLocalStorage<T>(key: string, options: Options<T, false>): T | null | undefined;
+declare function useReadLocalStorage<T>(key: string, options?: Partial<Options<T, true>>): T | null;
+
+type Size = {
+    width: number | undefined;
+    height: number | undefined;
+};
+type UseResizeObserverOptions<T extends HTMLElement = HTMLElement> = {
+    ref: React.RefObject<T>;
+    onResize?: (size: Size) => void;
+    box?: "border-box" | "content-box" | "device-pixel-content-box";
+};
+declare function useResizeObserver<T extends HTMLElement = HTMLElement>(options: UseResizeObserverOptions<T>): Size;
+
+type UseScreenOptions<InitializeWithValue extends boolean | undefined> = {
+    initializeWithValue: InitializeWithValue;
+    debounceDelay?: number;
+};
+declare function useScreen(options: UseScreenOptions<false>): Screen | undefined;
+declare function useScreen(options?: Partial<UseScreenOptions<true>>): Screen;
+
+type UseScriptStatus = "idle" | "loading" | "ready" | "error";
+type UseScriptOptions = {
+    shouldPreventLoad?: boolean;
+    removeOnUnmount?: boolean;
+    id?: string;
+};
+declare function useScript(src: string | null, options?: UseScriptOptions): UseScriptStatus;
+
+type UseScrollLockOptions = {
+    autoLock?: boolean;
+    lockTarget?: HTMLElement | string;
+    widthReflow?: boolean;
+};
+type UseScrollLockReturn = {
+    isLocked: boolean;
+    lock: () => void;
+    unlock: () => void;
+};
+declare function useScrollLock(options?: UseScrollLockOptions): UseScrollLockReturn;
+
+declare global {
+    interface WindowEventMap {
+        "session-storage": CustomEvent;
+    }
+}
+type UseSessionStorageOptions<T> = {
+    serializer?: (value: T) => string;
+    deserializer?: (value: string) => T;
+    initializeWithValue?: boolean;
+};
+declare function useSessionStorage<T>(key: string, initialValue: T | (() => T), options?: UseSessionStorageOptions<T>): [T, React.Dispatch<React.SetStateAction<T>>, () => void];
+
+type UseStepActions = {
+    goToNextStep: () => void;
+    goToPrevStep: () => void;
+    reset: () => void;
+    canGoToNextStep: boolean;
+    canGoToPrevStep: boolean;
+    setStep: React.Dispatch<React.SetStateAction<number>>;
+};
+declare function useStep(maxStep: number): [number, UseStepActions];
+
+type TernaryDarkMode = "system" | "dark" | "light";
+type TernaryDarkModeOptions = {
+    defaultValue?: TernaryDarkMode;
+    localStorageKey?: string;
+    initializeWithValue?: boolean;
+};
+type TernaryDarkModeReturn = {
+    isDarkMode: boolean;
+    ternaryDarkMode: TernaryDarkMode;
+    setTernaryDarkMode: React.Dispatch<React.SetStateAction<TernaryDarkMode>>;
+    toggleTernaryDarkMode: () => void;
+};
+declare function useTernaryDarkMode({ defaultValue, localStorageKey, initializeWithValue, }?: TernaryDarkModeOptions): TernaryDarkModeReturn;
+
+declare function useTimeout(callback: () => void, delay: number | null): void;
+
+declare function useToggle(defaultValue?: boolean): [boolean, () => void, React.Dispatch<React.SetStateAction<boolean>>];
+
+declare function useUnmount(func: () => void): void;
+
+type WindowSize<T extends number | undefined = number | undefined> = {
+    width: T;
+    height: T;
+};
+type UseWindowSizeOptions<InitializeWithValue extends boolean | undefined> = {
+    initializeWithValue: InitializeWithValue;
+    debounceDelay?: number;
+};
+declare function useWindowSize(options: UseWindowSizeOptions<false>): WindowSize;
+declare function useWindowSize(options?: Partial<UseWindowSizeOptions<true>>): WindowSize<number>;
+
+export { useBoolean, useCopyToClipboard, useCountdown, useCounter, useDarkMode, useDebounceCallback, useDebounceValue, useDelete, useDocumentTitle, useEventCallback, useEventListener, useFetch, useGet, useHover, useIndexedDB, useIntersectionObserver, useInterval, useIsClient, useIsMounted, useIsomorphicLayoutEffect, useLocalStorage, useMap, useMediaQuery, usePost, usePut, useReadLocalStorage, useResizeObserver, useScreen, useScript, useScrollLock, useSessionStorage, useStep, useTernaryDarkMode, useTimeout, useToggle, useUnmount, useWindowSize };
+export type { DebouncedState, TernaryDarkMode, TernaryDarkModeOptions, TernaryDarkModeReturn, UseFetchOptions, UseFetchReturn, UseFetchState };