@reactuses/core 1.0.1

package/index.d.ts

@@ -0,0 +1,588 @@
+import * as react from 'react';
+import { useEffect, useLayoutEffect, Dispatch, SetStateAction, MutableRefObject, DependencyList, EffectCallback, RefObject, CSSProperties } from 'react';
+import * as lodash from 'lodash';
+
+declare function usePrevious<T>(state: T): T | undefined;
+
+declare function useMarkdown(filepath: string): string;
+
+declare function useLatest<T>(value: T): React.MutableRefObject<T>;
+
+declare function useFirstMountState(): boolean;
+
+declare const _default$3: typeof useEffect | typeof react.useLayoutEffect;
+
+declare const _default$2: typeof react.useEffect | typeof useLayoutEffect;
+
+interface Serializer<T> {
+    read(raw: string): T;
+    write(value: T): string;
+}
+interface UseStorageOptions<T> {
+    /**
+     * Custom data serialization
+     */
+    serializer?: Serializer<T>;
+    /**
+     * On error callback
+     *
+     * Default log error to `console.error`
+     */
+    onError?: (error: unknown) => void;
+}
+
+declare function useLocalStorage(key: string, defaults: string, options?: UseStorageOptions<string>): readonly [string | null, Dispatch<SetStateAction<string | null>>];
+declare function useLocalStorage(key: string, defaults: number, options?: UseStorageOptions<number>): readonly [number | null, Dispatch<SetStateAction<number | null>>];
+declare function useLocalStorage(key: string, defaults: boolean, options?: UseStorageOptions<boolean>): readonly [boolean | null, Dispatch<SetStateAction<boolean | null>>];
+declare function useLocalStorage<T>(key: string, defaults: T, options?: UseStorageOptions<T>): readonly [T | null, Dispatch<SetStateAction<T | null>>];
+declare function useLocalStorage<T = unknown>(key: string, defaults: null, options?: UseStorageOptions<T>): readonly [T | null, Dispatch<SetStateAction<T | null>>];
+
+declare function useSessionStorage(key: string, defaults: string, options?: UseStorageOptions<string>): readonly [string | null, Dispatch<SetStateAction<string | null>>];
+declare function useSessionStorage(key: string, defaults: number, options?: UseStorageOptions<number>): readonly [number | null, Dispatch<SetStateAction<number | null>>];
+declare function useSessionStorage(key: string, defaults: boolean, options?: UseStorageOptions<boolean>): readonly [boolean | null, Dispatch<SetStateAction<boolean | null>>];
+declare function useSessionStorage<T>(key: string, defaults: T, options?: UseStorageOptions<T>): readonly [T | null, Dispatch<SetStateAction<T | null>>];
+declare function useSessionStorage<T = unknown>(key: string, defaults: null, options?: UseStorageOptions<T>): readonly [T | null, Dispatch<SetStateAction<T | null>>];
+
+declare type Fn = (this: any, ...args: any[]) => any;
+declare type Stoppable = [boolean, Fn, Fn];
+
+declare function useEvent<T extends Fn>(fn: T): T;
+
+declare function useToggle(initialValue: boolean): [boolean, (nextValue?: any) => void];
+
+declare function useInterval(callback: () => void, delay?: number | null, options?: {
+    immediate?: boolean;
+}): void;
+
+interface UseDarkOptions<T> {
+    /**
+     * CSS Selector for the target element applying to
+     *
+     * @default 'html'
+     */
+    selector?: string;
+    /**
+     * HTML attribute applying the target element
+     *
+     * @default 'class'
+     */
+    attribute?: string;
+    /**
+     * The initial value write the target element
+     * @default 'light | dark'
+     */
+    initialValue?: T;
+    /**
+     * Key to persist the data into localStorage/sessionStorage.
+     *
+     * @default 'reactuses-color-scheme'
+     */
+    storageKey?: string;
+    /**
+     * Storage object, can be localStorage or sessionStorage
+     *
+     * @default localStorage
+     */
+    storage?: () => Storage;
+}
+declare function useDarkMode<T extends string | "light" | "dark">(options?: UseDarkOptions<T>): readonly [T | null, react.Dispatch<react.SetStateAction<T | null>>];
+
+declare function useMediaQuery(query: string, defaultState?: boolean): boolean;
+
+declare function usePreferredDark(defaultState?: boolean): boolean;
+
+declare const useIsomorphicLayoutEffect: typeof useEffect;
+
+declare function useMount(fn: () => void): void;
+
+declare function useUnmount(fn: () => void): void;
+
+interface ThrottleSettings {
+    leading?: boolean | undefined;
+    trailing?: boolean | undefined;
+}
+interface DebounceSettings {
+    leading?: boolean;
+    trailing?: boolean;
+    maxWait?: number;
+}
+
+declare function useThrottle<T>(value: T, wait?: number, options?: ThrottleSettings): T;
+
+declare function useThrottleFn<T extends (...args: any) => any>(fn: T, wait?: number, options?: ThrottleSettings): {
+    run: lodash.DebouncedFunc<(...args_0: Parameters<T>) => ReturnType<T>>;
+    cancel: () => void;
+    flush: () => ReturnType<T> | undefined;
+};
+
+declare function useDebounce<T>(value: T, wait?: number, options?: DebounceSettings): T;
+
+declare function useDebounceFn<T extends (...args: any) => any>(fn: T, wait?: number, options?: DebounceSettings): {
+    run: lodash.DebouncedFunc<(...args_0: Parameters<T>) => ReturnType<T>>;
+    cancel: () => void;
+    flush: () => ReturnType<T> | undefined;
+};
+
+declare function useRafState<S>(initialState: S | (() => S)): readonly [S, Dispatch<SetStateAction<S>>];
+
+declare function useUpdate(): () => void;
+
+interface UseTimeoutFnOptions {
+    /**
+     * Start the timer immediate after calling this function
+     *
+     * @default false
+     */
+    immediate?: boolean;
+}
+/**
+ * Wrapper for `setTimeout` with controls.
+ *
+ * @param cb
+ * @param interval
+ * @param options
+ */
+declare function useTimeoutFn(cb: (...args: unknown[]) => any, interval: number, options?: UseTimeoutFnOptions): Stoppable;
+
+declare function useTimeout(ms?: number, options?: UseTimeoutFnOptions): Stoppable;
+
+declare function useMountedState(): () => boolean;
+
+declare type TargetValue<T> = T | undefined | null;
+declare type TargetType = HTMLElement | Element | Window | Document | EventTarget;
+declare type BasicTarget<T extends TargetType = Element> = (() => TargetValue<T>) | TargetValue<T> | MutableRefObject<TargetValue<T>>;
+
+declare type Target = BasicTarget<HTMLElement | Element | Window | Document | EventTarget>;
+declare function useEventListener<K extends keyof WindowEventMap>(eventName: K, handler: (event: WindowEventMap[K]) => void, element?: Window, options?: boolean | AddEventListenerOptions): void;
+declare function useEventListener<K extends keyof DocumentEventMap>(eventName: K, handler: (event: DocumentEventMap[K]) => void, element: Document, options?: boolean | AddEventListenerOptions): void;
+declare function useEventListener<K extends keyof HTMLElementEventMap, T extends HTMLElement = HTMLDivElement>(eventName: K, handler: (event: HTMLElementEventMap[K]) => void, element: T, options?: boolean | AddEventListenerOptions): void;
+declare function useEventListener<K extends keyof ElementEventMap>(eventName: K, handler: (event: ElementEventMap[K]) => void, element: Element, options?: boolean | AddEventListenerOptions): void;
+declare function useEventListener<K = Event>(eventName: string, handler: (event: K) => void, element: EventTarget | null | undefined, options?: boolean | AddEventListenerOptions): void;
+declare function useEventListener(eventName: string, handler: (...p: any) => void, element?: Target, options?: boolean | AddEventListenerOptions): void;
+
+declare function useCounter(initialValue?: number | (() => number), max?: number | null, min?: number | null): readonly [number, (newState: number | ((prev: number) => number) | (() => number)) => void, (delta?: number) => void, (delta?: number) => void, () => void];
+
+declare type RafLoopReturns = readonly [() => void, () => void, () => boolean];
+declare function useRafFn(callback: FrameRequestCallback, initiallyActive?: boolean): RafLoopReturns;
+
+interface IDisposable {
+    dispose(): void;
+}
+interface IEvent<T, U = void> {
+    (listener: (arg1: T, arg2: U) => any): IDisposable;
+}
+declare function useEventEmitter<T, U = void>(): readonly [IEvent<T, U>, (arg1: T, arg2: U) => void, () => void];
+
+declare function useFavicon(href: string, baseUrl?: string, rel?: string): void;
+
+declare function useMutationObserver(callback: MutationCallback, target: BasicTarget, options?: MutationObserverInit): () => void;
+
+declare type DepsEqualFnType<TDeps extends DependencyList> = (prevDeps: TDeps, nextDeps: TDeps) => boolean;
+declare function useCustomCompareEffect<TDeps extends DependencyList>(effect: EffectCallback, deps: TDeps, depsEqual: DepsEqualFnType<TDeps>): void;
+
+declare function useDeepCompareEffect(effect: EffectCallback, deps: DependencyList): void;
+
+declare function useTitle(title: string): void;
+
+interface UseScriptTagOptions {
+    /**
+     * Load the script immediately
+     *
+     * @default true
+     */
+    immediate?: boolean;
+    /**
+     * Add `async` attribute to the script tag
+     *
+     * @default true
+     */
+    async?: boolean;
+    /**
+     * Script type
+     *
+     * @default 'text/javascript'
+     */
+    type?: string;
+    /**
+     * Manual controls the timing of loading and unloading
+     *
+     * @default false
+     */
+    manual?: boolean;
+    crossOrigin?: "anonymous" | "use-credentials";
+    referrerPolicy?: "no-referrer" | "no-referrer-when-downgrade" | "origin" | "origin-when-cross-origin" | "same-origin" | "strict-origin" | "strict-origin-when-cross-origin" | "unsafe-url";
+    noModule?: boolean;
+    defer?: boolean;
+    /**
+     * Add custom attribute to the script tag
+     *
+     */
+    attrs?: Record<string, string>;
+}
+declare type Status = "idle" | "loading" | "ready" | "error";
+declare function useScriptTag(src: string, onLoaded?: (el: HTMLScriptElement) => void, options?: UseScriptTagOptions): readonly [HTMLScriptElement | null, Status, (waitForScriptLoad?: boolean) => Promise<HTMLScriptElement | boolean>, () => void];
+
+declare type IState = PermissionState | "";
+declare type DescriptorNamePolyfill = "accelerometer" | "accessibility-events" | "ambient-light-sensor" | "background-sync" | "camera" | "clipboard-read" | "clipboard-write" | "gyroscope" | "magnetometer" | "microphone" | "notifications" | "payment-handler" | "persistent-storage" | "push" | "speaker";
+declare type GeneralPermissionDescriptor = PermissionDescriptor | {
+    name: DescriptorNamePolyfill;
+};
+declare function usePermission(permissionDesc: GeneralPermissionDescriptor | GeneralPermissionDescriptor["name"]): IState;
+
+interface Options$1 {
+    isPreventDefault?: boolean;
+    delay?: number;
+}
+declare function useLongPress(callback: (e: TouchEvent | MouseEvent) => void, { isPreventDefault, delay }?: Options$1): {
+    readonly onMouseDown: (e: any) => void;
+    readonly onTouchStart: (e: any) => void;
+    readonly onMouseUp: () => void;
+    readonly onMouseLeave: () => void;
+    readonly onTouchEnd: () => void;
+};
+
+declare function useObjectUrl(object: Blob | MediaSource | undefined): string | undefined;
+
+declare function useIdle(ms?: number, initialState?: boolean, events?: (keyof WindowEventMap)[]): boolean;
+
+declare const _default$1: () => {};
+
+declare type UseTextDirectionValue = "ltr" | "rtl" | "auto";
+interface UseTextDirectionOptions {
+    /**
+     * CSS Selector for the target element applying to
+     *
+     * @default 'html'
+     */
+    selector?: string;
+    /**
+     * Initial value
+     *
+     * @default 'ltr'
+     */
+    initialValue?: UseTextDirectionValue;
+}
+declare function useTextDirection(options?: UseTextDirectionOptions): readonly [UseTextDirectionValue, (value: UseTextDirectionValue) => void];
+
+interface CursorState {
+    screenX: number;
+    screenY: number;
+    clientX: number;
+    clientY: number;
+    pageX: number;
+    pageY: number;
+    elementX: number;
+    elementY: number;
+    elementH: number;
+    elementW: number;
+    elementPosX: number;
+    elementPosY: number;
+}
+declare function useMouse(target?: BasicTarget): CursorState;
+
+interface UseFpsOptions {
+    /**
+     * Calculate the FPS on every x frames.
+     * @default 10
+     */
+    every?: number;
+}
+declare const _default: (options?: UseFpsOptions | undefined) => number;
+
+declare function useGeolocation(options?: Partial<PositionOptions>): {
+    readonly coordinates: GeolocationCoordinates;
+    readonly locatedAt: number | null;
+    readonly error: GeolocationPositionError | null;
+};
+
+interface Options {
+    onExit?: () => void;
+    onEnter?: () => void;
+}
+declare function useFullscreen(target: BasicTarget, options?: Options): readonly [boolean, {
+    readonly enterFullscreen: () => void;
+    readonly exitFullscreen: () => void;
+    readonly toggleFullscreen: () => void;
+    readonly isEnabled: true;
+}];
+
+interface INetworkInformation extends EventTarget {
+    readonly downlink: number;
+    readonly downlinkMax: number;
+    readonly effectiveType: "slow-2g" | "2g" | "3g" | "4g";
+    readonly rtt: number;
+    readonly saveData: boolean;
+    readonly type: "bluetooth" | "cellular" | "ethernet" | "none" | "wifi" | "wimax" | "other" | "unknown";
+    onChange: (event: Event) => void;
+}
+interface IUseNetworkState {
+    /**
+     * @desc Whether browser connected to the network or not.
+     */
+    online: boolean | undefined;
+    /**
+     * @desc Previous value of `online` property. Helps to identify if browser
+     * just connected or lost connection.
+     */
+    previous: boolean | undefined;
+    /**
+     * @desc The {Date} object pointing to the moment when state change occurred.
+     */
+    since: Date | undefined;
+    /**
+     * @desc Effective bandwidth estimate in megabits per second, rounded to the
+     * nearest multiple of 25 kilobits per seconds.
+     */
+    downlink: INetworkInformation["downlink"] | undefined;
+    /**
+     * @desc Maximum downlink speed, in megabits per second (Mbps), for the
+     * underlying connection technology
+     */
+    downlinkMax: INetworkInformation["downlinkMax"] | undefined;
+    /**
+     * @desc Effective type of the connection meaning one of 'slow-2g', '2g', '3g', or '4g'.
+     * This value is determined using a combination of recently observed round-trip time
+     * and downlink values.
+     */
+    effectiveType: INetworkInformation["effectiveType"] | undefined;
+    /**
+     * @desc Estimated effective round-trip time of the current connection, rounded
+     * to the nearest multiple of 25 milliseconds
+     */
+    rtt: INetworkInformation["rtt"] | undefined;
+    /**
+     * @desc {true} if the user has set a reduced data usage option on the user agent.
+     */
+    saveData: INetworkInformation["saveData"] | undefined;
+    /**
+     * @desc The type of connection a device is using to communicate with the network.
+     * It will be one of the following values:
+     *  - bluetooth
+     *  - cellular
+     *  - ethernet
+     *  - none
+     *  - wifi
+     *  - wimax
+     *  - other
+     *  - unknown
+     */
+    type: INetworkInformation["type"] | undefined;
+}
+declare function useNetwork(): IUseNetworkState;
+
+declare function useOnline(): boolean | undefined;
+
+interface OrientationState {
+    angle: number;
+    type: string;
+}
+declare function useOrientation(initialState?: OrientationState): readonly [OrientationState, (type: OrientationLockType) => Promise<void> | undefined, () => void];
+
+declare function useIntersectionObserver(target: BasicTarget, callback: IntersectionObserverCallback, options?: IntersectionObserverInit): () => void;
+
+declare function usePageLeave(): boolean;
+
+declare function useDocumentVisibility(): DocumentVisibilityState;
+
+declare function useResizeObserver(target: BasicTarget, callback: ResizeObserverCallback, options?: ResizeObserverOptions): () => void;
+
+declare function useDropZone(target: BasicTarget<HTMLElement>, onDrop?: (files: File[] | null) => void): boolean;
+
+interface UseFileDialogOptions {
+    /**
+     * @default true
+     */
+    multiple?: boolean;
+    /**
+     * @default '*'
+     */
+    accept?: string;
+    /**
+     * Select the input source for the capture file.
+     * @see [HTMLInputElement Capture](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/capture)
+     */
+    capture?: string;
+}
+declare function useFileDialog(options?: UseFileDialogOptions): readonly [
+    FileList | null,
+    (localOptions?: Partial<UseFileDialogOptions>) => void,
+    () => void
+];
+
+interface UseScrollOptions {
+    /**
+     * Throttle time for scroll event, it’s disabled by default.
+     *
+     * @default 0
+     */
+    throttle?: number;
+    /**
+     * The check time when scrolling ends.
+     * This configuration will be setting to (throttle + idle) when the `throttle` is configured.
+     *
+     * @default 200
+     */
+    idle?: number;
+    /**
+     * Offset arrived states by x pixels
+     *
+     */
+    offset?: {
+        left?: number;
+        right?: number;
+        top?: number;
+        bottom?: number;
+    };
+    /**
+     * Trigger it when scrolling.
+     *
+     */
+    onScroll?: (e: Event) => void;
+    /**
+     * Trigger it when scrolling ends.
+     *
+     */
+    onStop?: (e: Event) => void;
+    /**
+     * Listener options for scroll event.
+     *
+     * @default {capture: false, passive: true}
+     */
+    eventListenerOptions?: boolean | AddEventListenerOptions;
+}
+declare function useScroll(target: BasicTarget<HTMLElement | SVGElement | Window | Document>, options?: UseScrollOptions): readonly [
+    number,
+    number,
+    boolean,
+    {
+        left: boolean;
+        right: boolean;
+        top: boolean;
+        bottom: boolean;
+    },
+    {
+        left: boolean;
+        right: boolean;
+        top: boolean;
+        bottom: boolean;
+    }
+];
+
+interface UseInfiniteScrollOptions extends UseScrollOptions {
+    /**
+     * The minimum distance between the bottom of the element and the bottom of the viewport
+     *
+     * @default 0
+     */
+    distance?: number;
+    /**
+     * The direction in which to listen the scroll.
+     *
+     * @default 'bottom'
+     */
+    direction?: "top" | "bottom" | "left" | "right";
+    /**
+     * Whether to preserve the current scroll position when loading more items.
+     *
+     * @default false
+     */
+    preserveScrollPosition?: boolean;
+}
+declare function useInfiniteScroll(target: BasicTarget<HTMLElement | SVGElement | Window | Document>, onLoadMore: (state: ReturnType<typeof useScroll>) => void | Promise<void>, options?: UseInfiniteScrollOptions): void;
+
+declare type KeyModifier = "Alt" | "AltGraph" | "CapsLock" | "Control" | "Fn" | "FnLock" | "Meta" | "NumLock" | "ScrollLock" | "Shift" | "Symbol" | "SymbolLock";
+interface UseModifierOptions {
+    /**
+     * Event names that will prompt update to modifier states
+     *
+     * @default ['mousedown', 'mouseup', 'keydown', 'keyup']
+     */
+    events?: (keyof WindowEventMap)[];
+    /**
+     * Initial value of the returned ref
+     *
+     * @default false
+     */
+    initial?: boolean;
+}
+declare function useKeyModifier(modifier: KeyModifier, options?: UseModifierOptions): boolean;
+
+declare type IHookStateInitialSetter<S> = () => S;
+declare type IHookStateInitAction<S> = S | IHookStateInitialSetter<S>;
+
+interface MousePressedOptions {
+    /**
+     * Listen to `touchstart` `touchend` events
+     *
+     * @default true
+     */
+    touch?: boolean;
+    /**
+     * Listen to `dragstart` `drop` and `dragend` events
+     *
+     * @default true
+     */
+    drag?: boolean;
+    /**
+     * Initial values
+     *
+     * @default false
+     */
+    initialValue?: IHookStateInitAction<boolean>;
+}
+declare type MouseSourceType = "mouse" | "touch" | null;
+declare function useMousePressed(target?: BasicTarget, options?: MousePressedOptions): readonly [boolean, MouseSourceType];
+
+declare function useScrollLock(target: BasicTarget<HTMLElement | SVGElement | Window | Document>, initialState?: boolean): readonly [boolean, (flag: boolean) => void];
+
+declare function useElementSize(target: BasicTarget, options?: ResizeObserverOptions): readonly [number, number];
+
+interface UseVirtualListOptions {
+    /**
+     * container default height
+     *
+     * @default 300
+     */
+    containerHeight?: number;
+    /**
+     * item height, accept a pixel value or a function that returns the height
+     */
+    itemHeight: number | ((index: number) => number);
+    /**
+     * the extra buffer items outside of the view area
+     *
+     * @default 5
+     */
+    overscan?: number;
+}
+interface UseVirtualListItem<T> {
+    data: T;
+    index: number;
+}
+interface UseVirtualListReturn<T> {
+    list: UseVirtualListItem<T>[];
+    scrollTo: (index: number) => void;
+    containerProps: {
+        ref: RefObject<any>;
+        onScroll: () => void;
+        style: Partial<CSSProperties>;
+    };
+    wrapperProps: {
+        style: {
+            width: string;
+            height: string;
+            marginTop: string;
+        };
+    };
+}
+declare function useVirtualList<T = any>(list: T[] | undefined, options: UseVirtualListOptions): UseVirtualListReturn<T>;
+
+declare type ColorScheme = "dark" | "light" | "no-preference";
+declare function usePreferredColorScheme(defaultState?: ColorScheme): ColorScheme;
+
+declare type Contrast = "more" | "less" | "custom" | "no-preference";
+declare function usePreferredContrast(defaultState?: Contrast): Contrast;
+
+declare function useActiveElement<T extends Element>(): T | null;
+
+export { useActiveElement, useCounter, useCustomCompareEffect, useDarkMode, useDebounce, useDebounceFn, useDeepCompareEffect, useDocumentVisibility, useDropZone, useElementSize, useEvent, useEventEmitter, useEventListener, useFavicon, useFileDialog, useFirstMountState, _default as useFps, useFullscreen, useGeolocation, useIdle, useInfiniteScroll, useIntersectionObserver, useInterval, useIsomorphicLayoutEffect, useKeyModifier, useLatest, useLocalStorage, useLongPress, useMarkdown, _default$1 as useMediaDevices, useMediaQuery, useMount, useMountedState, useMouse, useMousePressed, useMutationObserver, useNetwork, useObjectUrl, useOnline, useOrientation, usePageLeave, usePermission, usePreferredColorScheme, usePreferredContrast, usePreferredDark, usePrevious, useRafFn, useRafState, useResizeObserver, useScriptTag, useScroll, useScrollLock, useSessionStorage, useTextDirection, useThrottle, useThrottleFn, useTimeout, useTimeoutFn, useTitle, useToggle, useUnmount, useUpdate, _default$3 as useUpdateEffect, _default$2 as useUpdateLayoutEffect, useVirtualList };