@himanshu-sorathiya/react-kit 1.0.24 → 1.0.26

package/dist/events.d.ts

@@ -2,33 +2,264 @@
 
 import { 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 = 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[];
+	/**
+	 * 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;
 }
-export type UseClickOutsideReturn = void;
+/**
+ * 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> = 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>;
+	/**
+	 * 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;
 }
-export type UseEventListenerReturn = void;
+/**
+ * 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 | 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 | 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 | 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 | RefObject<T | null> | null;
 }): UseEventListenerReturn;
@@ -37,26 +268,153 @@ 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?: RefObject<HTMLElement | null> | Window;
+	/**
+	 * The element, ref, `window`, or `document` to attach the listener to.
+	 *
+	 * @default window
+	 */
+	target?: 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 {};

package/dist/events2.js

@@ -1,67 +1,44 @@
 import { t as e } from "./useEventListener.js";
-import { useEffect as t, useLayoutEffect as n, useRef as r } from "react";
+import { useEffect as t, useRef as n } from "react";
 //#region src/events/useClickOutside/useClickOutside.ts
-var i = typeof window < "u" ? n : t;
-function a(t, n, a = {}) {
-	let { enabled: o = !0, eventType: s = ["mousedown", "touchstart"] } = a, c = r(n);
-	i(() => {
-		c.current = n;
-	}, [n]), e(s, (e) => {
-		o && (Array.isArray(t) ? t : [t]).every((t) => {
-			let n = t && "current" in t ? t.current : t;
-			return n && !n.contains(e.target);
-		}) && c.current(e);
-	}, { target: typeof document > "u" ? null : document });
+var r = globalThis.process?.env?.NODE_ENV !== "production";
+function i(t, i, a = {}) {
+	let { enabled: o = !0, eventType: s = ["mousedown", "touchstart"], capture: c = !0 } = a, l = n(!1);
+	return e(s, (e) => {
+		let n = e.target;
+		if (!(n instanceof Node)) return;
+		let a = Array.isArray(t) ? t : [t];
+		r && a.length === 0 && !l.current && (l.current = !0, console.warn("[useClickOutside] Called with an empty target array — every click will be treated as outside.")), a.every((e) => {
+			let t = e && "current" in e ? e.current : e;
+			return !t || !t.contains(n);
+		}) && i(e);
+	}, {
+		target: o && typeof document < "u" ? document : null,
+		capture: c,
+		passive: !0
+	});
 }
 //#endregion
 //#region src/events/useKey/constants.ts
-var o = [
+var a = [
 	"keydown",
 	"keyup",
 	"keypress"
-], s = typeof window < "u" ? n : t;
-function c(e, n, { enabled: i = !0, preventDefault: a = !0, stopPropagation: c = !0, eventType: l = "keydown", preventRepeat: u = !1, ignoreWhenFocusedInInputs: d = !0, ctrlKey: f = !1, shiftKey: p = !1, altKey: m = !1, metaKey: h = !1, target: g } = {}) {
-	let _ = g === void 0 ? typeof window > "u" ? null : window : g, v = r(n), y = r(i), b = r(!1);
-	s(() => {
-		v.current = n;
-	}, [n]), t(() => {
-		y.current = i;
-	}, [i]), t(() => {
-		let t = _ && "current" in _ ? _.current : _;
-		if (!t) return;
-		let n = String(e || "").toLowerCase(), r = o.includes(l) ? l : "keydown", i = u && r !== "keyup";
-		function s() {
-			b.current = !1;
-		}
-		function g(e) {
-			if (!(e instanceof KeyboardEvent)) return;
-			let t = e.key.toLowerCase();
-			(t === n || f && t === "control" || p && t === "shift" || m && t === "alt" || h && t === "meta") && (b.current = !1);
-		}
-		function x(e) {
-			if (!(e instanceof KeyboardEvent) || !y.current) return;
-			let t = e.target;
-			if (!(d && t instanceof HTMLElement && (t instanceof HTMLInputElement || t instanceof HTMLTextAreaElement || t instanceof HTMLSelectElement || t.isContentEditable)) && e.ctrlKey === f && e.shiftKey === p && e.altKey === m && e.metaKey === h && n === e.key.toLowerCase()) {
-				if (i && b.current) return;
-				b.current = !0, v.current(e), a && e.preventDefault(), c && e.stopPropagation();
-			}
-		}
-		return t.addEventListener(r, x), i && (t.addEventListener("keyup", g), window.addEventListener("blur", s)), () => {
-			t.removeEventListener(r, x), i && (t.removeEventListener("keyup", g), window.removeEventListener("blur", s));
-		};
-	}, [
-		e,
-		a,
-		c,
-		l,
-		u,
-		d,
-		f,
-		p,
-		m,
-		h,
-		_
-	]);
+], o = globalThis.process?.env?.NODE_ENV !== "production";
+function s(n, r, i = {}) {
+	let { enabled: s = !0, preventDefault: c = !0, stopPropagation: l = !0, eventType: u = "keydown", preventRepeat: d = !1, ignoreWhenFocusedInInputs: f = !0, ctrlKey: p = !1, shiftKey: m = !1, altKey: h = !1, metaKey: g = !1, capture: _ = !1, target: v } = i, y = n.toLowerCase();
+	t(() => {
+		o && y === "" && console.warn("[useKey] Called with an empty key — this listener will never match.");
+	}, [y]);
+	let b = a.includes(u) ? u : "keydown", x = d && b !== "keyup";
+	return e(b, (e) => {
+		if (!(e instanceof KeyboardEvent) || e.isComposing || e.keyCode === 229 || x && e.repeat) return;
+		let t = e.target;
+		f && t instanceof HTMLElement && (t instanceof HTMLInputElement || t instanceof HTMLTextAreaElement || t instanceof HTMLSelectElement || t.isContentEditable) || !(e.ctrlKey === p && e.shiftKey === m && e.altKey === h && e.metaKey === g) || y !== e.key.toLowerCase() || (c && e.preventDefault(), l && e.stopPropagation(), r(e));
+	}, {
+		target: s ? v ?? (typeof window > "u" ? null : window) : null,
+		capture: _
+	});
 }
 //#endregion
-export { a as n, c as t };
+export { i as n, s as t };