@himanshu-sorathiya/react-kit 1.0.24 → 1.0.26

package/dist/index.d.ts

@@ -3,33 +3,264 @@
 import React$1 from 'react';
 import { CSSProperties, Key, RefObject } from 'react';
 
+/**
+ * The native event that triggered a `useClickOutside` handler. Determined
+ * by whichever `eventType` was configured — `MouseEvent` for
+ * `click`/`mousedown`/`mouseup`, `TouchEvent` for `touchstart`/`touchend`,
+ * `PointerEvent` for `pointerdown`/`pointerup`.
+ */
 export type ClickOutsideEvent = MouseEvent | TouchEvent | PointerEvent | Event;
-export type ClickOutsideTarget = HTMLElement | null;
+/**
+ * A single element to check clicks against, or `null` if it isn't mounted
+ * yet.
+ */
+export type ClickOutsideTarget = Element | null;
+/**
+ * A way of referring to a single {@link ClickOutsideTarget}: a React ref
+ * that will (eventually) point at the element, the element itself, or
+ * `null`.
+ *
+ * A ref whose `current` is `null` — for example, because the element hasn't
+ * mounted yet — is treated as "outside" for that entry rather than blocking
+ * detection. See `useClickOutside`'s docs for details.
+ */
 export type ClickOutsideTargetRef = React$1.RefObject<ClickOutsideTarget> | ClickOutsideTarget;
+/**
+ * Native events `useClickOutside` can listen for. Defaults to `mousedown`
+ * and `touchstart`, which fire before `click`/`mouseup` — this avoids
+ * misfiring when a user starts a drag or text selection inside the target
+ * and releases outside it.
+ */
+export type ClickOutsideEventName = "mousedown" | "mouseup" | "click" | "touchstart" | "touchend" | "pointerdown" | "pointerup";
+/**
+ * Options accepted by `useClickOutside`.
+ */
 export interface UseClickOutsideOptions {
+	/**
+	 * Whether the listener is active. Setting this to `false` fully detaches
+	 * the underlying listener rather than just skipping the check on each
+	 * click, so there's no runtime cost while disabled.
+	 *
+	 * @default true
+	 */
 	enabled?: boolean;
-	eventType?: string | string[];
-}
-export type UseClickOutsideReturn = void;
+	/**
+	 * The event(s) that count as a "click." See {@link ClickOutsideEventName}
+	 * for why `mousedown`/`touchstart` are the default.
+	 *
+	 * @default ["mousedown", "touchstart"]
+	 */
+	eventType?: ClickOutsideEventName | ClickOutsideEventName[];
+	/**
+	 * Whether the listener is registered in the capture phase.
+	 *
+	 * Defaults to `true` so this keeps working even if some element between
+	 * the click and `document` calls `event.stopPropagation()` — a common
+	 * cause of "click outside stopped working" bugs in bubble-phase
+	 * listeners.
+	 *
+	 * @default true
+	 */
+	capture?: boolean;
+}
+/**
+ * A function that detaches the listener registered by `useClickOutside`
+ * immediately, without waiting for the component to unmount.
+ *
+ * Safe to call more than once. Note that this does not permanently disable
+ * the hook: if `target`, `eventType`, `enabled`, or `capture` change
+ * afterwards, a new listener may be attached again on the next render.
+ */
+export type UseClickOutsideReturn = () => void;
+/**
+ * Calls `handler` when a click (or the configured event type) happens
+ * outside of `target`.
+ *
+ * `target` may be a single element/ref, or an array of them — the handler
+ * only fires when the click is outside *every* target in the array. An
+ * unmounted target (a ref whose `current` is `null`) is treated as
+ * "outside" for its own entry rather than blocking detection for the
+ * others, so it's safe to pass refs that haven't attached yet.
+ *
+ * @param target The element(s) to detect clicks outside of. Accepts a ref, a direct
+ * element, `null`, or an array mixing any of those.
+ * @param handler Called with the native event when a click outside is detected. Doesn't
+ * need to be memoized.
+ * @param options See {@link UseClickOutsideOptions}.
+ * @returns A function that detaches the listener on demand.
+ *
+ * @example
+ * ```tsx
+ * const modalRef = useRef<HTMLDivElement>(null);
+ * useClickOutside(modalRef, () => setOpen(false));
+ * ```
+ *
+ * @example
+ * Checking outside multiple elements at once — for example, a dropdown that
+ * shouldn't close when its own trigger button is clicked:
+ * ```tsx
+ * const triggerRef = useRef<HTMLButtonElement>(null);
+ * const panelRef = useRef<HTMLDivElement>(null);
+ * useClickOutside([triggerRef, panelRef], () => setOpen(false));
+ * ```
+ */
 export declare function useClickOutside(target: ClickOutsideTargetRef | ClickOutsideTargetRef[], handler: (event: ClickOutsideEvent) => void, options?: UseClickOutsideOptions): UseClickOutsideReturn;
+/**
+ * Any valid DOM event target — the broadest type a listener can be attached
+ * to. Used as the generic constraint for {@link UseEventListenerOptions} and
+ * {@link TargetRef}.
+ */
 export type TargetType = EventTarget;
+/**
+ * A way of referring to a listener target: a React ref that will
+ * (eventually) point at the target, the target itself, or `null`.
+ *
+ * Passing `null` — or a ref whose `current` is `null` — means no listener is
+ * attached.
+ */
 export type TargetRef<T extends TargetType> = React$1.RefObject<T | null> | T | null;
+/**
+ * Options accepted by `useEventListener`, extending the native
+ * `AddEventListenerOptions` (`capture`, `passive`, `once`) with a `target`
+ * to attach to.
+ */
 export interface UseEventListenerOptions<T extends TargetType> extends AddEventListenerOptions {
+	/**
+	 * The element, ref, `window`, or `document` to attach the listener to.
+	 *
+	 * - Omitted → defaults to `window` (or does nothing during SSR, where
+	 *   `window` doesn't exist).
+	 * - `null`, or a ref whose `current` is `null` → no listener is attached.
+	 */
 	target?: TargetRef<T>;
-}
-export type UseEventListenerReturn = void;
+	/**
+	 * An `AbortSignal` to detach the listener(s) from outside the hook.
+	 *
+	 * This is combined with the hook's own internal cleanup — aborting this
+	 * signal detaches the listener(s) immediately, the same as calling the
+	 * function the hook returns.
+	 */
+	signal?: AbortSignal;
+}
+/**
+ * A function that detaches the listener(s) registered by `useEventListener`
+ * immediately, without waiting for the component to unmount.
+ *
+ * Safe to call more than once — it's a no-op after the first call. Note
+ * that this does not permanently disable the hook: if its dependencies
+ * (event name(s), target, `capture`, `passive`, `once`, or `signal`) change
+ * afterwards, a new listener may be attached again on the next render.
+ */
+export type UseEventListenerReturn = () => void;
+/**
+ * Listens for one or more events on `window` — the default target when none
+ * is specified.
+ *
+ * @param eventName A single event name, or an array of event names, to listen for.
+ * @param handler Called with the native event whenever it fires. Doesn't need to be
+ * memoized — the latest `handler` is always used, and changing it does not
+ * re-attach the listener.
+ * @param options Optional. `target` may be omitted (defaults to `window`), or set
+ * explicitly to `window` or `null` (to disable).
+ * @returns A function that detaches the listener(s) on demand.
+ *
+ * @example
+ * ```tsx
+ * useEventListener("resize", () => {
+ *   console.log(window.innerWidth);
+ * });
+ * ```
+ */
 export declare function useEventListener<K extends keyof WindowEventMap>(eventName: K | K[], handler: (event: WindowEventMap[K]) => void, options?: UseEventListenerOptions<Window> & {
 	target?: Window | null | undefined;
 }): UseEventListenerReturn;
+/**
+ * Listens for one or more events on `document`. `target` is required to
+ * distinguish this overload from the `window` one.
+ *
+ * @param eventName A single event name, or an array of event names, to listen for.
+ * @param handler Called with the native event whenever it fires. Doesn't need to be
+ * memoized — the latest `handler` is always used, and changing it does not
+ * re-attach the listener.
+ * @param options `target` must be `document`, a ref pointing at `document`, or `null`
+ * (to disable).
+ * @returns A function that detaches the listener(s) on demand.
+ *
+ * @example
+ * ```tsx
+ * useEventListener("visibilitychange", () => {
+ *   console.log(document.visibilityState);
+ * }, { target: document });
+ * ```
+ */
 export declare function useEventListener<K extends keyof DocumentEventMap>(eventName: K | K[], handler: (event: DocumentEventMap[K]) => void, options: UseEventListenerOptions<Document> & {
 	target: Document | React$1.RefObject<Document | null> | null;
 }): UseEventListenerReturn;
+/**
+ * Listens for one or more events on an `HTMLElement`, via a ref or the
+ * element itself.
+ *
+ * @param eventName A single event name, or an array of event names, to listen for.
+ * @param handler Called with the native event whenever it fires. Doesn't need to be
+ * memoized — the latest `handler` is always used, and changing it does not
+ * re-attach the listener.
+ * @param options `target` must be the element, a ref to it, or `null` (to disable —
+ * for example while the ref hasn't attached to a DOM node yet).
+ * @returns A function that detaches the listener(s) on demand.
+ *
+ * @example
+ * ```tsx
+ * const buttonRef = useRef<HTMLButtonElement>(null);
+ * useEventListener("click", () => {
+ *   console.log("clicked");
+ * }, { target: buttonRef });
+ * ```
+ */
 export declare function useEventListener<K extends keyof HTMLElementEventMap, T extends HTMLElement = HTMLElement>(eventName: K | K[], handler: (event: HTMLElementEventMap[K]) => void, options: UseEventListenerOptions<T> & {
 	target: T | React$1.RefObject<T | null> | null;
 }): UseEventListenerReturn;
+/**
+ * Listens for one or more events on an `SVGElement`, via a ref or the
+ * element itself.
+ *
+ * @param eventName A single event name, or an array of event names, to listen for.
+ * @param handler Called with the native event whenever it fires. Doesn't need to be
+ * memoized — the latest `handler` is always used, and changing it does not
+ * re-attach the listener.
+ * @param options `target` must be the element, a ref to it, or `null` (to disable).
+ * @returns A function that detaches the listener(s) on demand.
+ *
+ * @example
+ * ```tsx
+ * const circleRef = useRef<SVGCircleElement>(null);
+ * useEventListener("click", () => {
+ *   console.log("circle clicked");
+ * }, { target: circleRef });
+ * ```
+ */
 export declare function useEventListener<K extends keyof SVGElementEventMap, T extends SVGElement = SVGElement>(eventName: K | K[], handler: (event: SVGElementEventMap[K]) => void, options: UseEventListenerOptions<T> & {
 	target: T | React$1.RefObject<T | null> | null;
 }): UseEventListenerReturn;
+/**
+ * Listens for one or more events on any other `EventTarget` — a custom
+ * event emitter, `ShadowRoot`, `MessagePort`, and so on. Since there's no
+ * matching `*EventMap` for arbitrary targets, events are typed as the
+ * generic `Event`.
+ *
+ * @param eventName A single event name, or an array of event names, to listen for.
+ * @param handler Called with the native event whenever it fires. Doesn't need to be
+ * memoized — the latest `handler` is always used, and changing it does not
+ * re-attach the listener.
+ * @param options `target` must be the target, a ref to it, or `null` (to disable).
+ * @returns A function that detaches the listener(s) on demand.
+ *
+ * @example
+ * ```tsx
+ * useEventListener("message", (event) => {
+ *   console.log(event);
+ * }, { target: myMessagePort });
+ * ```
+ */
 export declare function useEventListener<K extends string, T extends TargetType = TargetType>(eventName: K | K[], handler: (event: Event) => void, options: UseEventListenerOptions<T> & {
 	target: T | React$1.RefObject<T | null> | null;
 }): UseEventListenerReturn;
@@ -38,27 +269,154 @@ declare const validKeyEventTypes: readonly [
 	"keyup",
 	"keypress"
 ];
+/**
+ * The keyboard event types `useKey` can listen for. See
+ * {@link validKeyEventTypes}.
+ */
 export type KeyEventType = (typeof validKeyEventTypes)[number];
-export interface BaseKeyOptions {
+/**
+ * Options shared by both variants of {@link UseKeyOptions}.
+ */
+export interface UseKeyBaseOptions {
+	/**
+	 * Whether the listener is active. Setting this to `false` fully detaches
+	 * the underlying listener rather than just skipping the check on each
+	 * keystroke, so there's no runtime cost while disabled.
+	 *
+	 * @default true
+	 */
 	enabled?: boolean;
-	target?: React$1.RefObject<HTMLElement | null> | Window;
+	/**
+	 * The element, ref, `window`, or `document` to attach the listener to.
+	 *
+	 * @default window
+	 */
+	target?: React$1.RefObject<HTMLElement | null> | HTMLElement | Window | Document | null;
+	/**
+	 * Whether to call `event.preventDefault()` when `key` matches. Applied
+	 * before `handler` is called, so it still takes effect even if `handler`
+	 * throws.
+	 *
+	 * @default true
+	 */
 	preventDefault?: boolean;
+	/**
+	 * Whether to call `event.stopPropagation()` when `key` matches. Applied
+	 * before `handler` is called, so it still takes effect even if `handler`
+	 * throws.
+	 *
+	 * @default true
+	 */
 	stopPropagation?: boolean;
+	/**
+	 * Whether the listener is registered in the capture phase.
+	 *
+	 * Unlike `useClickOutside`, this defaults to `false`. Flip it to `true`
+	 * if a descendant element calling `event.stopPropagation()` is
+	 * preventing this shortcut from firing.
+	 *
+	 * @default false
+	 */
+	capture?: boolean;
+	/**
+	 * Whether to ignore the keystroke while focus is inside an `<input>`,
+	 * `<textarea>`, `<select>`, or any `contenteditable` element — so a
+	 * shortcut like a bare `"s"` doesn't fire while someone is just typing.
+	 *
+	 * @default true
+	 */
 	ignoreWhenFocusedInInputs?: boolean;
+	/**
+	 * Whether the Ctrl key must be held for a match.
+	 * @default false
+	 */
 	ctrlKey?: boolean;
+	/**
+	 * Whether the Shift key must be held for a match.
+	 * @default false
+	 */
 	shiftKey?: boolean;
+	/**
+	 * Whether the Alt key (Option, on Mac) must be held for a match.
+	 * @default false
+	 */
 	altKey?: boolean;
+	/**
+	 * Whether the Meta key (Cmd on Mac, the Windows key elsewhere) must be
+	 * held for a match.
+	 * @default false
+	 */
 	metaKey?: boolean;
 }
-export type KeyOptions = BaseKeyOptions & ({
-	eventType?: "keydown" | "keypress";
+/**
+ * Options accepted by `useKey`.
+ *
+ * `preventRepeat` is only valid together with `eventType: "keydown"` or
+ * `"keypress"` — TypeScript rejects it on `"keyup"`, since a keyup event is
+ * never marked as auto-repeating.
+ */
+export type UseKeyOptions = UseKeyBaseOptions & ({
+	/**
+	 * Which keyboard event to listen for.
+	 * @default "keydown"
+	 */
+	eventType?: Extract<KeyEventType, "keydown" | "keypress">;
+	/**
+	 * If `true`, ignores auto-repeated events fired while the key is
+	 * held down (based on the native `KeyboardEvent.repeat` flag), so
+	 * `handler` only fires once per physical press rather than
+	 * repeatedly while it's held.
+	 *
+	 * @default false
+	 */
 	preventRepeat?: boolean;
 } | {
-	eventType: "keyup";
+	eventType: Extract<KeyEventType, "keyup">;
 	preventRepeat?: never;
 });
-export type UseKeyReturn = void;
-export declare function useKey(key: string, handler: (e: KeyboardEvent) => void, { enabled, preventDefault, stopPropagation, eventType, preventRepeat, ignoreWhenFocusedInInputs, ctrlKey, shiftKey, altKey, metaKey, target, }?: KeyOptions): UseKeyReturn;
+/**
+ * A function that detaches the listener registered by `useKey` immediately,
+ * without waiting for the component to unmount.
+ *
+ * Safe to call more than once. Note that this does not permanently disable
+ * the hook: if `eventType`, `enabled`, `target`, or `capture` change
+ * afterwards, a new listener may be attached again on the next render.
+ * Changing `key` — or any of the modifier-matching options — does *not*
+ * cause a re-attach; those are picked up fresh on the next keystroke
+ * without the underlying listener ever being torn down.
+ */
+export type UseKeyReturn = () => void;
+/**
+ * Calls `handler` when `key` is pressed (or released, depending on
+ * `eventType`), optionally matching an exact combination of modifier keys.
+ *
+ * Ignores keystrokes that occur during IME composition (for example, while
+ * typing pinyin or romaji before a CJK character is confirmed), so
+ * shortcuts don't misfire or interfere with the IME's own confirmation key
+ * — often Enter. By default, also ignores keystrokes while focus is inside
+ * a text input, textarea, select, or contenteditable element — see
+ * `ignoreWhenFocusedInInputs` in {@link UseKeyOptions}.
+ *
+ * @param key The key to match, compared case-insensitively against
+ * `KeyboardEvent.key` (e.g. `"Escape"`, `"a"`, `"Enter"`).
+ * @param handler Called with the native event when a match is found. Doesn't need to be
+ * memoized.
+ * @param options See {@link UseKeyOptions}.
+ * @returns A function that detaches the listener on demand.
+ *
+ * @example
+ * ```tsx
+ * useKey("Escape", () => setOpen(false));
+ * ```
+ *
+ * @example
+ * Matching a modifier combination — all four modifier flags are matched
+ * exactly, so this only fires for Ctrl+K alone, not Ctrl+Shift+K:
+ * ```tsx
+ * useKey("k", () => openCommandPalette(), { ctrlKey: true });
+ * ```
+ */
+export declare function useKey(key: string, handler: (event: KeyboardEvent) => void, options?: UseKeyOptions): UseKeyReturn;
 export interface DebounceOptions {
 	maxWait?: number;
 	leading?: boolean;
@@ -458,6 +816,44 @@ export interface UseSortReturn<T> {
 	getSortIndex: (id: string) => number | undefined;
 }
 export declare function useSort<T>(data?: T[], initialSorts?: SortState): UseSortReturn<T>;
+export interface StorageSerializer<T> {
+	serialize: (value: T) => string;
+	deserialize: (raw: string) => T;
+}
+export interface BaseStorageOptions<T> {
+	serializer?: StorageSerializer<T>;
+	initializeWithValue?: boolean;
+	sameInstanceSync?: boolean;
+}
+export interface StorageCustomEventDetail {
+	value: string | null;
+	instanceId: symbol;
+}
+export interface UseLocalStorageOptions<T> extends BaseStorageOptions<T> {
+	crossInstanceSync?: boolean;
+}
+export interface UseLocalStorageReturn<T> {
+	value: T | undefined;
+	setValue: (valueOrUpdater: T | ((prev: T | undefined) => T)) => void;
+	removeValue: () => void;
+	isHydrated: boolean;
+	error: Error | null;
+}
+export declare function useLocalStorage<T = unknown>(key: string, initialValue?: T, options?: UseLocalStorageOptions<T>): UseLocalStorageReturn<T>;
+export type UseSessionStorageOptions<T> = BaseStorageOptions<T>;
+export interface UseSessionStorageReturn<T> {
+	value: T | undefined;
+	setValue: (valueOrUpdater: T | ((prev: T | undefined) => T)) => void;
+	removeValue: () => void;
+	isHydrated: boolean;
+	error: Error | null;
+}
+export declare function useSessionStorage<T = unknown>(key: string, initialValue?: T, options?: UseSessionStorageOptions<T>): UseSessionStorageReturn<T>;
+export declare const defaultSerializer: StorageSerializer<unknown>;
+export declare function mapSerializer<K, V>(): StorageSerializer<Map<K, V>>;
+export declare function setSerializer<V>(): StorageSerializer<Set<V>>;
+export declare const dateSerializer: StorageSerializer<Date>;
+export declare const bigIntSerializer: StorageSerializer<bigint>;
 export interface FuzzyHighlighterProps {
 	text: string;
 	query: string;

package/dist/index.js

@@ -2,5 +2,6 @@ import { t as e } from "./useEventListener.js";
 import { n as t, t as n } from "./events2.js";
 import { a as r, c as i, d as a, f as o, i as s, l as c, n as l, o as u, r as d, s as f, t as p, u as m } from "./performance2.js";
 import { a as h, c as g, i as _, n as v, o as y, r as b, s as x, t as S } from "./state2.js";
-import { a as C, c as w, i as T, n as E, o as D, r as O, s as k, t as A } from "./ui2.js";
-export { w as FuzzyHighlighter, T as ModalLayout, t as useClickOutside, o as useDebounce, a as useDebouncedCallback, m as useDebouncedState, c as useDebouncedValue, e as useEventListener, O as useExpansion, g as useFilter, x as useFuzzySearch, y as useGrouping, n as useKey, C as useModal, D as useModalActions, k as useModalState, h as useMultipleSelection, _ as useOrder, b as usePagination, E as usePin, i as useRateLimit, f as useRateLimitedCallback, v as useSingleSelection, S as useSort, u as useThrottle, r as useThrottledCallback, s as useThrottledState, d as useThrottledValue, l as useVirtualGrid, p as useVirtualList, A as useVisibility };
+import { a as C, i as w, n as T, o as E, r as D, s as O, t as k } from "./storage2.js";
+import { a as A, c as j, i as M, n as N, o as P, r as F, s as I, t as L } from "./ui2.js";
+export { j as FuzzyHighlighter, M as ModalLayout, D as bigIntSerializer, w as dateSerializer, C as defaultSerializer, E as mapSerializer, O as setSerializer, t as useClickOutside, o as useDebounce, a as useDebouncedCallback, m as useDebouncedState, c as useDebouncedValue, e as useEventListener, F as useExpansion, g as useFilter, x as useFuzzySearch, y as useGrouping, n as useKey, T as useLocalStorage, A as useModal, P as useModalActions, I as useModalState, h as useMultipleSelection, _ as useOrder, b as usePagination, N as usePin, i as useRateLimit, f as useRateLimitedCallback, k as useSessionStorage, v as useSingleSelection, S as useSort, u as useThrottle, r as useThrottledCallback, s as useThrottledState, d as useThrottledValue, l as useVirtualGrid, p as useVirtualList, L as useVisibility };

package/dist/storage.d.ts

@@ -0,0 +1,42 @@
+// Generated by dts-bundle-generator v9.5.1
+
+export interface StorageSerializer<T> {
+	serialize: (value: T) => string;
+	deserialize: (raw: string) => T;
+}
+export interface BaseStorageOptions<T> {
+	serializer?: StorageSerializer<T>;
+	initializeWithValue?: boolean;
+	sameInstanceSync?: boolean;
+}
+export interface StorageCustomEventDetail {
+	value: string | null;
+	instanceId: symbol;
+}
+export interface UseLocalStorageOptions<T> extends BaseStorageOptions<T> {
+	crossInstanceSync?: boolean;
+}
+export interface UseLocalStorageReturn<T> {
+	value: T | undefined;
+	setValue: (valueOrUpdater: T | ((prev: T | undefined) => T)) => void;
+	removeValue: () => void;
+	isHydrated: boolean;
+	error: Error | null;
+}
+export declare function useLocalStorage<T = unknown>(key: string, initialValue?: T, options?: UseLocalStorageOptions<T>): UseLocalStorageReturn<T>;
+export type UseSessionStorageOptions<T> = BaseStorageOptions<T>;
+export interface UseSessionStorageReturn<T> {
+	value: T | undefined;
+	setValue: (valueOrUpdater: T | ((prev: T | undefined) => T)) => void;
+	removeValue: () => void;
+	isHydrated: boolean;
+	error: Error | null;
+}
+export declare function useSessionStorage<T = unknown>(key: string, initialValue?: T, options?: UseSessionStorageOptions<T>): UseSessionStorageReturn<T>;
+export declare const defaultSerializer: StorageSerializer<unknown>;
+export declare function mapSerializer<K, V>(): StorageSerializer<Map<K, V>>;
+export declare function setSerializer<V>(): StorageSerializer<Set<V>>;
+export declare const dateSerializer: StorageSerializer<Date>;
+export declare const bigIntSerializer: StorageSerializer<bigint>;
+
+export {};

package/dist/storage.js

@@ -0,0 +1,2 @@
+import { a as e, i as t, n, o as r, r as i, s as a, t as o } from "./storage2.js";
+export { i as bigIntSerializer, t as dateSerializer, e as defaultSerializer, r as mapSerializer, a as setSerializer, n as useLocalStorage, o as useSessionStorage };