@himanshu-sorathiya/react-kit 1.0.25 → 1.0.27

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[];
+	/**
+	 * 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> = 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>;
+	/**
+	 * 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 | 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,43 +816,295 @@ export interface UseSortReturn<T> {
 	getSortIndex: (id: string) => number | undefined;
 }
 export declare function useSort<T>(data?: T[], initialSorts?: SortState): UseSortReturn<T>;
+/**
+ * Defines how a value of type `T` is converted to and from the string
+ * format that `localStorage`/`sessionStorage` can actually store — the Web
+ * Storage API only ever stores strings.
+ *
+ * Implement this to store types the default JSON-based serializer can't
+ * round-trip faithfully, e.g. `Map`, `Set`, `Date`, or `bigint` — see
+ * `mapSerializer`, `setSerializer`, `dateSerializer`, and
+ * `bigIntSerializer` in `serializers.ts` for ready-made ones.
+ *
+ * @typeParam T - The in-memory value type this serializer handles.
+ */
 export interface StorageSerializer<T> {
+	/** Converts an in-memory value into the string that gets stored. */
 	serialize: (value: T) => string;
+	/**
+	 * Converts a stored string back into an in-memory value.
+	 *
+	 * @throws If the raw string can't be converted back into `T`. The hook
+	 * catches this, falls back to `initialValue`, and reports the error —
+	 * see `onError` on {@link BaseStorageOptions}.
+	 */
 	deserialize: (raw: string) => T;
 }
+/**
+ * Options shared by `useLocalStorage` and `useSessionStorage`.
+ *
+ * @typeParam T - The type of value being stored.
+ */
 export interface BaseStorageOptions<T> {
+	/**
+	 * Custom (de)serializer for values that don't round-trip through
+	 * `JSON.stringify`/`JSON.parse` cleanly.
+	 *
+	 * @defaultValue `defaultSerializer` (plain `JSON.stringify`/`JSON.parse`)
+	 */
 	serializer?: StorageSerializer<T>;
+	/**
+	 * Whether to synchronously read the existing stored value on mount.
+	 *
+	 * - `true` (default): `value` reflects storage from the very first
+	 *   render it's allowed to (see the SSR note below).
+	 * - `false`: `value` starts as `undefined` and only reflects storage
+	 *   once `isHydrated` becomes `true`, one render after mount. Use this
+	 *   if you'd rather render a loading/skeleton state than briefly show a
+	 *   value that might change right after.
+	 *
+	 * Either way, on the server — and during the client's hydration render
+	 * — `value` is always `initialValue`. This option only affects timing
+	 * on the client, after that point.
+	 *
+	 * @defaultValue `true`
+	 */
 	initializeWithValue?: boolean;
+	/**
+	 * Whether other instances of this hook watching the *same key* in the
+	 * *same tab* stay in sync with each other. Implemented via a
+	 * `CustomEvent` dispatched on `window` — the browser's native `storage`
+	 * event never fires in the tab that made the change, so without this,
+	 * two components reading the same key in one tab would drift apart.
+	 *
+	 * @defaultValue `true`
+	 */
 	sameInstanceSync?: boolean;
+	/**
+	 * Called whenever the hook hits an unexpected condition: a failed
+	 * read, a failed write, a failed cross-instance deserialize, or an
+	 * attempt to change the storage key at runtime. Fires in every
+	 * environment, including production — use this for telemetry/error
+	 * reporting.
+	 *
+	 * This is *not* a replacement for the dev-only `console.warn` the hook
+	 * also emits for the same conditions (visible when
+	 * `process.env.NODE_ENV !== "production"`) — both fire independently.
+	 */
+	onError?: (error: Error) => void;
 }
+/**
+ * Payload carried by the same-tab `CustomEvent` used for
+ * {@link BaseStorageOptions.sameInstanceSync}. Internal — not part of the
+ * public hook API, but exported so `useStorageEngine.ts` can import it.
+ */
 export interface StorageCustomEventDetail {
+	/** The new serialized value, or `null` if the key was removed. */
 	value: string | null;
+	/**
+	 * A per-hook-instance identifier, used so an instance can recognize —
+	 * and ignore — the event it just dispatched itself.
+	 */
 	instanceId: symbol;
 }
-export interface UseLocalStorageOptions<T> extends BaseStorageOptions<T> {
-	crossInstanceSync?: boolean;
-}
-export interface UseLocalStorageReturn<T> {
+/**
+ * The shape returned by {@link useStorageEngine} — and, re-exported, by
+ * both `useLocalStorage` and `useSessionStorage`.
+ *
+ * @typeParam T - The type of value being stored.
+ */
+interface UseStorageEngineReturn<T> {
+	/**
+	 * The current value.
+	 *
+	 * - `undefined` if nothing is stored yet and no `initialValue` was
+	 *   given, or — when `initializeWithValue: false` — before hydration
+	 *   completes.
+	 * - On the server, and during the client's hydration render, this is
+	 *   always `initialValue`: real storage can only be read client-side,
+	 *   and reading it any earlier would produce a hydration mismatch.
+	 */
 	value: T | undefined;
+	/**
+	 * Writes a new value to storage. Accepts either the value directly, or
+	 * an updater function that receives the current value and returns the
+	 * next one — the same convention as `useState`'s setter.
+	 *
+	 * A no-op if storage isn't available (SSR, or storage access blocked).
+	 */
 	setValue: (valueOrUpdater: T | ((prev: T | undefined) => T)) => void;
+	/**
+	 * Removes the key from storage entirely and resets `value` back to
+	 * whatever `initialValue` was passed to the hook.
+	 *
+	 * A no-op if storage isn't available (SSR, or storage access blocked).
+	 */
 	removeValue: () => void;
+	/**
+	 * `true` once the client has mounted and the hook has settled on its
+	 * real (non-server-snapshot) value. Useful for showing a loading state
+	 * instead of a value that might change the instant hydration finishes.
+	 */
 	isHydrated: boolean;
+	/**
+	 * The most recent error the hook encountered — a failed read, write,
+	 * or cross-instance sync, or an attempted key change — or `null` if
+	 * nothing has gone wrong (or an error was cleared by a subsequent
+	 * successful write/remove). See `onError` on {@link BaseStorageOptions}
+	 * for an imperative alternative to reading this reactively.
+	 */
 	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;
+/**
+ * Options accepted by `useLocalStorage`.
+ *
+ * @typeParam T - The type of value being stored.
+ */
+export interface UseLocalStorageOptions<T> extends BaseStorageOptions<T> {
+	/**
+	 * Whether this hook instance should sync with the same key changing in
+	 * *other tabs/windows* on the same origin, via the browser's native
+	 * `storage` event. Has no `sessionStorage` equivalent — sessionStorage
+	 * isn't shared across tabs, so there's nothing to sync in that case.
+	 *
+	 * @defaultValue `true`
+	 */
+	crossInstanceSync?: boolean;
 }
-export declare function useSessionStorage<T = unknown>(key: string, initialValue?: T, options?: UseSessionStorageOptions<T>): UseSessionStorageReturn<T>;
+/**
+ * Reads and writes a `localStorage` key, kept in sync with React state.
+ *
+ * - Persists across page reloads and browser restarts (unlike
+ *   `useSessionStorage`).
+ * - Stays in sync with every component in the current tab watching the
+ *   same key — see {@link UseLocalStorageOptions.sameInstanceSync} — and
+ *   with other tabs/windows on the same origin — see
+ *   {@link UseLocalStorageOptions.crossInstanceSync}.
+ * - Safe under SSR: on the server, and during the client's hydration
+ *   render, `value` is always `initialValue`. The real stored value is
+ *   only read client-side, immediately after hydration.
+ *
+ * @typeParam T - The type of value being stored. Defaults to `unknown` if
+ * omitted — pass an explicit type argument for anything beyond ad-hoc use.
+ * @param key - The `localStorage` key to read and write. Changing this on
+ * a later render isn't supported; the hook warns (dev console + `onError`)
+ * and keeps using the original key if you do.
+ * @param initialValue - Used when nothing is stored yet, as the value
+ * shown before hydration completes, and as what `removeValue` resets to.
+ * @param options - See {@link UseLocalStorageOptions}.
+ * @returns `{ value, setValue, removeValue, isHydrated, error }`.
+ *
+ * @example
+ * Basic usage:
+ * ```tsx
+ * const { value: theme, setValue: setTheme } = useLocalStorage<"light" | "dark">("theme", "light");
+ *
+ * <button onClick={() => setTheme(prev => (prev === "light" ? "dark" : "light"))}>
+ *   Toggle theme
+ * </button>
+ * ```
+ *
+ * @example
+ * With a custom serializer and error reporting:
+ * ```tsx
+ * const { value, setValue, error } = useLocalStorage("lastSeen", new Date(), {
+ *   serializer: dateSerializer,
+ *   onError: (err) => reportToErrorTracker(err),
+ * });
+ * ```
+ */
+export declare function useLocalStorage<T = unknown>(key: string, initialValue?: T, options?: UseLocalStorageOptions<T>): UseStorageEngineReturn<T>;
+/**
+ * Options accepted by `useSessionStorage`. Identical to
+ * `BaseStorageOptions` — unlike `UseLocalStorageOptions`, there's no
+ * `crossInstanceSync` option here, since sessionStorage isn't shared
+ * across tabs in the first place.
+ *
+ * @typeParam T - The type of value being stored.
+ */
+export type UseSessionStorageOptions<T> = BaseStorageOptions<T>;
+/**
+ * Reads and writes a `sessionStorage` key, kept in sync with React state.
+ *
+ * - Scoped to the current tab: cleared when the tab closes, and not
+ *   shared with other tabs (unlike `useLocalStorage`).
+ * - Stays in sync with every component in the current tab watching the
+ *   same key — see {@link UseSessionStorageOptions.sameInstanceSync}.
+ * - Safe under SSR: on the server, and during the client's hydration
+ *   render, `value` is always `initialValue`. The real stored value is
+ *   only read client-side, immediately after hydration.
+ *
+ * @typeParam T - The type of value being stored. Defaults to `unknown` if
+ * omitted — pass an explicit type argument for anything beyond ad-hoc use.
+ * @param key - The `sessionStorage` key to read and write. Changing this
+ * on a later render isn't supported; the hook warns (dev console +
+ * `onError`) and keeps using the original key if you do.
+ * @param initialValue - Used when nothing is stored yet, as the value
+ * shown before hydration completes, and as what `removeValue` resets to.
+ * @param options - See {@link UseSessionStorageOptions}.
+ * @returns `{ value, setValue, removeValue, isHydrated, error }`.
+ *
+ * @example
+ * ```tsx
+ * const { value: draft, setValue: setDraft } = useSessionStorage("draft-comment", "");
+ *
+ * <textarea value={draft ?? ""} onChange={(e) => setDraft(e.target.value)} />
+ * ```
+ */
+export declare function useSessionStorage<T = unknown>(key: string, initialValue?: T, options?: UseSessionStorageOptions<T>): UseStorageEngineReturn<T>;
+/**
+ * The default serializer used when no `serializer` option is passed to
+ * `useLocalStorage`/`useSessionStorage`. Plain `JSON.stringify`/
+ * `JSON.parse` — works for any JSON-safe value (objects, arrays, strings,
+ * numbers, booleans, `null`), but not `Map`, `Set`, `Date`, `bigint`, or
+ * `undefined` (see the other serializers below for those).
+ */
 export declare const defaultSerializer: StorageSerializer<unknown>;
+/**
+ * Serializer for `Map` values. `JSON.stringify` can't handle `Map`
+ * directly, so this round-trips it via an array of `[key, value]` entries.
+ *
+ * @typeParam K - The map's key type.
+ * @typeParam V - The map's value type.
+ *
+ * @example
+ * ```ts
+ * useLocalStorage("tags", new Map<string, number>(), {
+ *   serializer: mapSerializer<string, number>(),
+ * });
+ * ```
+ */
 export declare function mapSerializer<K, V>(): StorageSerializer<Map<K, V>>;
+/**
+ * Serializer for `Set` values, round-tripped via a plain array.
+ *
+ * @typeParam V - The set's value type.
+ *
+ * @example
+ * ```ts
+ * useLocalStorage("selectedIds", new Set<string>(), {
+ *   serializer: setSerializer<string>(),
+ * });
+ * ```
+ */
 export declare function setSerializer<V>(): StorageSerializer<Set<V>>;
+/**
+ * Serializer for `Date` values, stored as an ISO 8601 string
+ * (`Date.prototype.toISOString`).
+ *
+ * @throws During `deserialize`, if the stored string isn't a valid date —
+ * caught by the hook, which falls back to `initialValue` and reports the
+ * error via `onError`/the dev console warning.
+ */
 export declare const dateSerializer: StorageSerializer<Date>;
+/**
+ * Serializer for `bigint` values. `JSON.stringify` throws on `bigint`
+ * values, so this stores them as a plain decimal string instead.
+ *
+ * @throws During `deserialize`, if the stored string can't be converted to
+ * a `bigint` — caught by the hook, which falls back to `initialValue` and
+ * reports the error via `onError`/the dev console warning.
+ */
 export declare const bigIntSerializer: StorageSerializer<bigint>;
 export interface FuzzyHighlighterProps {
 	text: string;
@@ -590,4 +1200,9 @@ export declare function useVisibility<T = unknown>(options?: {
 	initialVisibleIds?: VisibilityId[];
 }): UseVisibilityReturn<T>;
 
+export {
+	UseStorageEngineReturn as UseLocalStorageReturn,
+	UseStorageEngineReturn as UseSessionStorageReturn,
+};
+
 export {};