@boxcustodia/library 2.0.0-alpha.19 → 2.0.0-alpha.20

package/dist/src/components/date-picker/date-picker.utils.d.ts

@@ -1,9 +1,26 @@
 import { DateRange } from './date-picker.model';
 export declare const DISPLAY_DATE_FORMAT = "dd/MM/yyyy";
 export declare const formatSingleDate: (date: Date | null | undefined, placeholder: string) => string;
+/**
+ * ISO 8601 calendar date (`yyyy-MM-dd`) used as the form value — locale-agnostic,
+ * sortable, and parseable by `new Date()` / backends without a custom format.
+ * The display string keeps `DISPLAY_DATE_FORMAT`; this is the value layer.
+ */
+export declare const formatISODate: (date: Date | null | undefined) => string;
 export declare const formatRangeDate: (range: DateRange | undefined, placeholder: string) => string;
 export declare const formatMultipleDates: (dates: Date[] | undefined, placeholder: string) => string;
 export declare const formatDate: (date: Date | null) => string;
+/**
+ * Emits a native `input` event on a hidden form control so Base UI's Field
+ * re-runs validation. Base UI clears the error and re-validates only inside the
+ * control's `onChange`; assigning `value` via a React prop never fires a native
+ * event, so date changes driven from outside (calendar selection, typing into
+ * the visible input) would leave the field stuck in its invalid state.
+ *
+ * Sets the value through the prototype setter so React's value tracker detects
+ * the diff, then dispatches a bubbling `input` event React maps to `onChange`.
+ */
+export declare const emitNativeInputChange: (input: HTMLInputElement | null, value: string) => void;
 export declare const parseInputToDate: (raw: string) => Date | null;
 export type DateMaskContext = {
     lastKey: string | null;

package/dist/src/components/date-picker/use-hidden-field-value.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Drives a hidden Base UI `FieldControl` input from a derived form value.
+ *
+ * The input is left uncontrolled and updated imperatively so a native `input`
+ * event fires on every change. Base UI re-runs Field validation (and clears the
+ * error) only inside the control's `onChange` — never from a React `value` prop
+ * — so date changes coming from the calendar or the visible input must emit a
+ * real event for the invalid state to clear.
+ *
+ * Returns the ref to attach to the hidden input.
+ */
+export declare function useHiddenFieldValue(value: string): import('react').RefObject<HTMLInputElement | null>;

package/dist/src/components/index.d.ts

@@ -23,6 +23,7 @@ export * from './label';
 export * from './loader';
 export * from './menu';
 export * from './number-input';
+export * from './otp';
 export * from './pagination';
 export * from './password';
 export * from './popover';

package/dist/src/hooks/index.d.ts

@@ -1,6 +1,7 @@
 export { useControllableState } from '@radix-ui/react-use-controllable-state';
 export * from './use-array';
 export * from './use-async';
+export * from './use-boolean';
 export * from './use-click-outside';
 export * from './use-clipboard';
 export * from './use-debounce-callback';
@@ -20,8 +21,7 @@ export * from './use-object';
 export * from './use-on-mount';
 export * from './use-pagination';
 export * from './use-portal';
-export * from './use-prevent-close-window';
+export * from './use-prevent-page-close';
 export * from './use-range-pagination';
 export * from './use-selection';
 export * from './use-step';
-export * from './use-toggle';

package/dist/src/hooks/internal/index.d.ts

@@ -1,2 +1,4 @@
+export { isAppleDevice } from './is-apple-device';
 export { isBrowser } from './is-browser';
 export { useIsomorphicLayoutEffect } from './use-isomorphic-layout-effect';
+export { useLatestRef } from './use-latest-ref';

package/dist/src/hooks/internal/is-apple-device.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Lazily detects whether the current device is an Apple platform (macOS, iOS,
+ * iPadOS). Reads `navigator.userAgentData?.platform` when available, falling
+ * back to the legacy `navigator.platform`.
+ *
+ * SSR-safe: returns `false` when there is no `navigator` (e.g. on the server),
+ * so the `mod` hotkey modifier deterministically resolves to `ctrl` there.
+ *
+ * The check runs on every call (not memoized at module-eval) so it can be
+ * stubbed per-test and stays correct if the environment changes.
+ */
+export declare const isAppleDevice: () => boolean;

package/dist/src/hooks/internal/use-latest-ref.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Returns a ref whose `.current` always holds the latest value passed in.
+ *
+ * Internal building block for the handler-stable pattern: hooks that accept
+ * user callbacks should read them through a ref so listeners attached to
+ * `window`/`document`/elements never need to be re-attached when the consumer
+ * passes an inline function.
+ *
+ * Updates happen in a layout effect so the ref is current before any user
+ * effect or commit-phase work runs in the same render.
+ */
+export declare const useLatestRef: <T>(value: T) => import('react').RefObject<T>;

package/dist/src/hooks/use-array/use-array.d.ts

@@ -1,11 +1,24 @@
-export declare function useArray<T>(defaultProp: T[]): readonly [T[], {
-    readonly insertAt: (index: number, item: T) => void;
-    readonly removeAt: (index: number) => void;
-    readonly updateAt: (index: number, newItem: T) => void;
-    readonly clear: () => void;
-    readonly reset: () => void;
-    readonly push: (item: T) => void;
-    readonly set: (newList: T[]) => void;
-    readonly pop: () => void;
-    readonly update: (predicate: (item: T) => boolean, newItem: T | ((item: T) => T)) => void;
-}];
+export interface UseArrayOptions<T> {
+    /** Called after every list change. NOT called on initial mount. */
+    onChange?: (items: T[]) => void;
+}
+export interface UseArrayActions<T> {
+    push(item: T): void;
+    pop(): void;
+    insertAt(index: number, item: T): void;
+    removeAt(index: number): void;
+    updateAt(index: number, item: T): void;
+    clear(): void;
+    reset(): void;
+    set(items: T[]): void;
+    move(from: number, to: number): void;
+    swap(indexA: number, indexB: number): void;
+    filter(predicate: (item: T, index: number, array: T[]) => boolean): void;
+    sort(compareFn?: (a: T, b: T) => number): void;
+    reverse(): void;
+    replace(predicate: (item: T) => boolean, newItem: T | ((item: T) => T)): void;
+    removeWhere(predicate: (item: T) => boolean): void;
+    pushMany(items: T[]): void;
+    find(predicate: (item: T, index: number, array: T[]) => boolean): T | undefined;
+}
+export declare function useArray<T>(initialValue: T[], options?: UseArrayOptions<T>): readonly [T[], UseArrayActions<T>];

package/dist/src/hooks/use-async/use-async.d.ts

@@ -1,18 +1,21 @@
-import { DependencyList } from 'react';
-interface UseAsyncOptions<T> {
-    onError?: (error: Error) => void;
+export type AsyncStatus = "idle" | "pending" | "success" | "error";
+export interface UseAsyncOptions<T> {
+    fn: (signal: AbortSignal) => Promise<T>;
+    deps?: readonly unknown[];
+    enabled?: boolean;
+    keepPreviousData?: boolean;
     onSuccess?: (data: T) => void;
-    onFinish?: () => void;
+    onError?: (error: Error) => void;
+    onSettled?: (data: T | null, error: Error | null) => void;
 }
-interface AsyncState<T> {
-    loading: boolean;
-    error: Error | null;
+export interface UseAsyncReturn<T> {
     data: T | null;
+    error: Error | null;
+    status: AsyncStatus;
+    loading: boolean;
+    isIdle: boolean;
+    isSuccess: boolean;
+    isError: boolean;
     refetch: () => void;
 }
-interface Props<T> extends UseAsyncOptions<T> {
-    fn: () => Promise<T>;
-    dependencies?: DependencyList;
-}
-export declare function useAsync<T>({ fn, dependencies, onError, onSuccess, onFinish, }: Props<T>): AsyncState<T>;
-export {};
+export declare function useAsync<T>({ fn, deps, enabled, keepPreviousData, onSuccess, onError, onSettled, }: UseAsyncOptions<T>): UseAsyncReturn<T>;

package/dist/src/hooks/use-boolean/index.d.ts

@@ -0,0 +1 @@
+export * from './use-boolean';

package/dist/src/hooks/use-boolean/use-boolean.d.ts

@@ -0,0 +1,15 @@
+export interface UseBooleanOptions {
+    /** Called after every value change. NOT called on initial mount. */
+    onChange?: (value: boolean) => void;
+}
+export interface UseBooleanActions {
+    /** Flip the current value. */
+    toggle(): void;
+    /** Force the value to true. */
+    setTrue(): void;
+    /** Force the value to false. */
+    setFalse(): void;
+    /** Set the value explicitly. */
+    set(value: boolean): void;
+}
+export declare function useBoolean(initialValue?: boolean, options?: UseBooleanOptions): readonly [boolean, UseBooleanActions];

package/dist/src/hooks/use-boolean/use-boolean.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/hooks/use-click-outside/use-click-outside.d.ts

@@ -1 +1,23 @@
-export declare const useClickOutside: <T extends HTMLElement = HTMLElement>(callback: () => void, watch?: boolean) => import('react').RefObject<T | null>;
+import { RefObject } from 'react';
+type UseClickOutsideOptions = {
+    /** Disable the listener without unmounting the hook. Defaults to `true`. */
+    enabled?: boolean;
+    /**
+     * Which DOM events trigger the outside check. Any DOM event names work;
+     * pass `null` to fall back to the default. Defaults to `["pointerdown"]`.
+     */
+    events?: string[] | null;
+    /**
+     * Return `true` to skip the callback for a given event. Useful for portals
+     * or popovers whose DOM lives outside the wrapped ref but should still count
+     * as "inside".
+     */
+    ignore?: (event: Event) => boolean;
+    /**
+     * Extra refs that also count as "inside". An event whose target lives in
+     * any of these elements will not fire the callback.
+     */
+    additionalRefs?: RefObject<HTMLElement | null>[];
+};
+export declare const useClickOutside: <T extends HTMLElement = HTMLElement>(callback: (event: Event) => void, options?: UseClickOutsideOptions) => RefObject<T | null>;
+export {};

package/dist/src/hooks/use-debounce-callback/use-debounced-callback.d.ts

@@ -1 +1,19 @@
-export declare function useDebouncedCallback<T extends (...args: any[]) => any>(callback: T, delay: number): (...args: Parameters<T>) => void;
+export interface DebouncedControls {
+    /** Cancel the pending invocation without calling the callback. No-op if nothing is pending. */
+    cancel: () => void;
+    /** Immediately invoke the callback with the last queued arguments, clearing the timer. No-op if nothing is pending. */
+    flush: () => void;
+    /** Reactive boolean: `true` while a debounced call is scheduled, `false` otherwise. */
+    isPending: boolean;
+}
+/**
+ * Returns a debounced version of `callback` together with a controls object.
+ *
+ * The returned `debounced` function has a **stable identity** — it is only
+ * recreated when `delay` changes, never when `callback` changes. This means
+ * passing an inline arrow function is safe: it will not reset a pending timer
+ * on re-render.
+ *
+ * @returns `[debounced, { cancel, flush, isPending }]`
+ */
+export declare function useDebouncedCallback<T extends (...args: any[]) => any>(callback: T, delay: number): readonly [(...args: Parameters<T>) => void, DebouncedControls];

package/dist/src/hooks/use-debounce-value/use-debounced-value.d.ts

@@ -1 +1,10 @@
-export declare function useDebouncedValue<T>(value: T, delay: number): T;
+import { DebouncedControls } from '../use-debounce-callback/use-debounced-callback';
+/**
+ * Returns the debounced version of `value` together with a controls object.
+ *
+ * Delegates entirely to `useDebouncedCallback` — there is no duplicated timer
+ * logic in this hook.
+ *
+ * @returns `[debouncedValue, { cancel, flush, isPending }]`
+ */
+export declare function useDebouncedValue<T>(value: T, delay: number): readonly [T, DebouncedControls];

package/dist/src/hooks/use-disclosure/use-disclosure.d.ts

@@ -1,8 +1,17 @@
-export declare function useDisclosure(initialState?: boolean, callbacks?: {
-    onOpen?: () => void;
-    onClose?: () => void;
-}): readonly [boolean, {
-    readonly open: () => void;
-    readonly close: () => void;
-    readonly toggle: () => void;
-}];
+export type UseDisclosureProps = {
+    /** Initial open value (default: false). */
+    defaultOpen?: boolean;
+    /** Called once per real state transition. Not called on no-op calls. */
+    onOpenChange?: (open: boolean) => void;
+};
+export type UseDisclosureActions = {
+    /** Transitions state to true. No-op (and onOpenChange not called) if already open. */
+    open: () => void;
+    /** Transitions state to false. No-op (and onOpenChange not called) if already closed. */
+    close: () => void;
+    /** Flips the current boolean state. */
+    toggle: () => void;
+    /** Sets state to the given value. No-op (and onOpenChange not called) if value is unchanged. */
+    setOpen: (open: boolean) => void;
+};
+export declare function useDisclosure(props?: UseDisclosureProps): readonly [boolean, UseDisclosureActions];

package/dist/src/hooks/use-document-title/use-document-title.d.ts

@@ -1,5 +1,16 @@
 export interface UseDocumentTitleInput {
     /** Restore the previous `document.title` when the component unmounts. Defaults to `false`. */
     restoreOnUnmount?: boolean;
+    /**
+     * Template applied to the title. The `%s` placeholder is replaced with
+     * the (trimmed) title value. Example: `"%s | Acme"` turns `"Inbox"`
+     * into `"Inbox | Acme"`. When omitted, the title is written as-is.
+     */
+    template?: string;
+    /**
+     * When `false`, the hook does not touch `document.title`. Defaults to
+     * `true`. Useful to conditionally own the title.
+     */
+    enabled?: boolean;
 }
 export declare function useDocumentTitle(title: string, options?: UseDocumentTitleInput): void;

package/dist/src/hooks/use-event-listener/use-event-listener.d.ts

@@ -1 +1,18 @@
-export declare function useEventListener<K extends keyof HTMLElementEventMap, T extends HTMLElement = HTMLElement>(type: K, listener: (this: T, ev: HTMLElementEventMap[K]) => void, options?: boolean | AddEventListenerOptions): import('react').RefObject<T | null>;
+import { RefObject } from 'react';
+/**
+ * Subscribe to a DOM event with automatic cleanup. The `listener` is read
+ * through an internal ref (handler-stable pattern), so passing an inline
+ * function never re-attaches the underlying listener on every render.
+ *
+ * The target is explicit and selected by overload:
+ * - omit it to listen on `window` (the default);
+ * - pass a `RefObject` or the element itself for an `HTMLElement`;
+ * - pass `document` for document-level events;
+ * - pass a `MediaQueryList` for media query changes.
+ *
+ * SSR-safe: the effect no-ops when there is no DOM.
+ */
+export declare function useEventListener<K extends keyof WindowEventMap>(type: K, listener: (event: WindowEventMap[K]) => void, target?: Window | RefObject<Window | null> | null, options?: boolean | AddEventListenerOptions): void;
+export declare function useEventListener<K extends keyof DocumentEventMap>(type: K, listener: (event: DocumentEventMap[K]) => void, target: Document | RefObject<Document | null>, options?: boolean | AddEventListenerOptions): void;
+export declare function useEventListener<K extends keyof HTMLElementEventMap, T extends HTMLElement = HTMLElement>(type: K, listener: (event: HTMLElementEventMap[K]) => void, target: T | RefObject<T | null>, options?: boolean | AddEventListenerOptions): void;
+export declare function useEventListener<K extends keyof MediaQueryListEventMap>(type: K, listener: (event: MediaQueryListEventMap[K]) => void, target: MediaQueryList | RefObject<MediaQueryList | null>, options?: boolean | AddEventListenerOptions): void;

package/dist/src/hooks/use-hotkey/index.d.ts

@@ -1 +1,2 @@
-export * from './use-hotkey';
+export type { HotkeyEventName, HotkeyItem, HotkeyItemOptions, HotkeyOptions, KeyboardEventLike, Keys, } from './use-hotkey';
+export { getHotkeyHandler, useHotkey } from './use-hotkey';

package/dist/src/hooks/use-hotkey/use-hotkey.d.ts

@@ -1,9 +1,66 @@
+import { HotkeyItem, HotkeyItemOptions, KeyboardEventLike } from './utils';
+export type { HotkeyItem, HotkeyItemOptions, KeyboardEventLike };
+/** A single key string or a list of key strings sharing one handler. */
 export type Keys = string | string[];
-export type HotkeyEventName = "keydown" | "keypress" | "keyup";
-export type HotkeyOptions = {
+/** Supported listener event names. `"keypress"` is removed in v2. */
+export type HotkeyEventName = "keydown" | "keyup";
+/**
+ * Options for the single-binding `useHotkey(keys, handler, options)` form.
+ * Combines hook-level concerns (`watch`, `eventName`, `tagsToIgnore`) with the
+ * per-binding behavior (`preventDefault`, `triggerOnContentEditable`).
+ */
+export type HotkeyOptions = HotkeyItemOptions & {
+    /** Listen while `true` (default). When `false`, no handler fires. */
     watch?: boolean;
+    /** DOM event to listen for. Default `"keydown"`. */
     eventName?: HotkeyEventName;
-    preventDefault?: boolean;
-    ignoreInputFields?: boolean;
+    /**
+     * Tag names whose events are ignored. Default
+     * `["INPUT", "TEXTAREA", "SELECT"]`. Pass `[]` to ignore nothing.
+     */
+    tagsToIgnore?: string[];
 };
-export declare function useHotkey(keys: string | string[], handler: (event: KeyboardEvent) => void, options?: HotkeyOptions): import('react').RefObject<HTMLElement | null>;
+/**
+ * Bind one or more keyboard shortcuts at the `document` level.
+ *
+ * Two forms are supported:
+ *
+ * 1. Single binding — `useHotkey(keys, handler, options?)` where `keys` is a
+ *    string or string array sharing one handler.
+ * 2. Multiple bindings — `useHotkey(bindings)` where `bindings` is a list of
+ *    `[key, handler, options?]` tuples, each dispatched independently.
+ *
+ * Matching is strict: every required modifier (`shift`/`ctrl`/`alt`/`meta`)
+ * must be pressed and no other modifier may be. `mod` resolves to `meta` (⌘)
+ * on Apple platforms and `ctrl` elsewhere. Events originating in `tagsToIgnore`
+ * tags (or contentEditable regions) are suppressed unless opted out.
+ *
+ * The handler is read through a ref, so passing an inline function never
+ * re-attaches the underlying listener. SSR-safe: no DOM access on the server.
+ *
+ * @example
+ * useHotkey("mod+k", () => openPalette());
+ * useHotkey([["a", onA], ["b", onB, { preventDefault: false }]]);
+ */
+export declare function useHotkey(keys: Keys, handler: (event: KeyboardEventLike) => void, options?: HotkeyOptions): void;
+export declare function useHotkey(bindings: HotkeyItem[], options?: HotkeyOptions): void;
+/**
+ * Build an element-scoped `onKeyDown` handler. Shares the same
+ * strict-modifier and `mod` behavior as {@link useHotkey}.
+ *
+ * Two forms are supported:
+ *
+ * 1. Single binding — `getHotkeyHandler(keys, handler, options?)`.
+ * 2. Multiple bindings — `getHotkeyHandler(bindings)` where `bindings` is a
+ *    list of `[key, handler, options?]` tuples.
+ *
+ * Because it is attached to an element's `onKeyDown`, it applies NO tag
+ * suppression — it has no `tagsToIgnore` and matches regardless of the target
+ * tag (including the `<input>` it is attached to).
+ *
+ * @example
+ * <input onKeyDown={getHotkeyHandler("mod+enter", submit)} />
+ * <input onKeyDown={getHotkeyHandler([["mod+enter", submit], ["escape", cancel]])} />
+ */
+export declare function getHotkeyHandler(keys: Keys, handler: (event: KeyboardEventLike) => void, options?: HotkeyItemOptions): (event: KeyboardEventLike) => void;
+export declare function getHotkeyHandler(bindings: HotkeyItem[]): (event: KeyboardEventLike) => void;

package/dist/src/hooks/use-hotkey/utils/index.d.ts

@@ -1,3 +1,4 @@
-export * from './create-hotkey-listener';
-export * from './is-input-field';
-export * from './match-key-modifiers';
+export { shouldIgnoreEvent } from './is-input-field';
+export type { HotkeyItem, HotkeyItemOptions, KeyboardEventLike, } from './match-and-run';
+export { matchAndRun } from './match-and-run';
+export { getKeyModifiers, matchKeyModifiers } from './match-key-modifiers';

package/dist/src/hooks/use-hotkey/utils/is-input-field.d.ts

@@ -1,2 +1,12 @@
-export declare const isInputField: (element: HTMLElement) => boolean;
-export declare const shouldIgnoreEvent: (event: KeyboardEvent, ignoreInputFields: boolean) => boolean;
+import { KeyboardEventLike } from './match-and-run';
+/**
+ * Decides whether a keyboard event should be suppressed because it originated
+ * inside a form control or editable region.
+ *
+ * - Suppressed when the target's tag name is in `tagsToIgnore` (case-sensitive
+ *   uppercase tag names, e.g. `["INPUT","TEXTAREA","SELECT"]`). An empty list
+ *   suppresses nothing.
+ * - Suppressed when the target is `contentEditable`, unless
+ *   `triggerOnContentEditable` is `true`.
+ */
+export declare const shouldIgnoreEvent: (event: KeyboardEventLike, tagsToIgnore: string[], triggerOnContentEditable: boolean) => boolean;

package/dist/src/hooks/use-hotkey/utils/is-input-field.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/hooks/use-hotkey/utils/match-and-run.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Structural subset of a keyboard event used by the matching core. Both the
+ * DOM `KeyboardEvent` (used by `useHotkey`) and React's synthetic
+ * `KeyboardEvent` (used by `getHotkeyHandler`) satisfy this shape, so the core
+ * stays React-free and requires no casts at either call site.
+ */
+export type KeyboardEventLike = Pick<KeyboardEvent, "key" | "shiftKey" | "ctrlKey" | "altKey" | "metaKey"> & {
+    target: EventTarget | null;
+    preventDefault: () => void;
+};
+/**
+ * Per-binding options. Defaults: `preventDefault` true,
+ * `triggerOnContentEditable` false, `tagsToIgnore` is resolved by the caller
+ * (`useHotkey` passes its configured list; `getHotkeyHandler` passes `[]`).
+ */
+export type HotkeyItemOptions = {
+    preventDefault?: boolean;
+    triggerOnContentEditable?: boolean;
+};
+/** A single hotkey binding: `[key, handler, options?]`. */
+export type HotkeyItem = [
+    key: string,
+    handler: (event: KeyboardEventLike) => void,
+    options?: HotkeyItemOptions
+];
+/**
+ * The shared matching engine. For each binding it:
+ * 1. skips the event if the target should be ignored (tag / contentEditable);
+ * 2. parses the binding key (resolving `mod` to `meta`/`ctrl` per platform);
+ * 3. strictly matches the main key and all four modifiers;
+ * 4. calls `preventDefault` (unless opted out) then the handler.
+ *
+ * `tagsToIgnore` is a core parameter: `useHotkey` passes its configured list,
+ * while `getHotkeyHandler` passes `[]` (element-scoped, so it ignores nothing).
+ */
+export declare const matchAndRun: (event: KeyboardEventLike, items: HotkeyItem[], tagsToIgnore: string[]) => void;

package/dist/src/hooks/use-hotkey/utils/match-and-run.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/hooks/use-hotkey/utils/match-key-modifiers.d.ts

@@ -1,8 +1,22 @@
-export declare const getKeyModifiers: (key: string) => {
+import { KeyboardEventLike } from './match-and-run';
+type ParsedKey = {
     mainKey: string;
-    isShift: boolean;
-    isCtrl: boolean;
-    isAlt: boolean;
-    isMeta: boolean;
+    shift: boolean;
+    ctrl: boolean;
+    alt: boolean;
+    meta: boolean;
 };
-export declare const matchKeyModifiers: (event: KeyboardEvent, key: string) => boolean;
+/**
+ * Parses a hotkey string (e.g. `"mod+shift+k"`) into its main key and the
+ * exact set of required modifiers. `mod` resolves to `meta` on Apple platforms
+ * and `ctrl` elsewhere; the opposite modifier is then required to be absent
+ * (it stays `false` here, enforcing the strict exact-match rule).
+ */
+export declare const getKeyModifiers: (key: string) => ParsedKey;
+/**
+ * Returns `true` only when the event's main key matches AND every modifier
+ * state (shift/ctrl/alt/meta) exactly equals the parsed requirement. This is a
+ * strict match: any extra or missing modifier rejects the binding.
+ */
+export declare const matchKeyModifiers: (event: KeyboardEventLike, key: string) => boolean;
+export {};

package/dist/src/hooks/use-hotkey/utils/match-key-modifiers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/hooks/use-hover/use-hover.d.ts

@@ -1,9 +1,13 @@
 import { RefCallback } from 'react';
 export interface UseHoverInput {
-    /** Fired when the pointer enters the target element. Receives the native MouseEvent. */
-    onHoverStart?: (event: MouseEvent) => void;
-    /** Fired when the pointer leaves the target element. Receives the native MouseEvent. */
-    onHoverEnd?: (event: MouseEvent) => void;
+    /** Delay in ms before `hovered` becomes true after pointer enters. Default 0 (synchronous). */
+    openDelay?: number;
+    /** Delay in ms before `hovered` becomes false after pointer leaves. Default 0 (synchronous). */
+    closeDelay?: number;
+    /** Fired when the pointer enters the target element. Receives the native PointerEvent. */
+    onHoverStart?: (event: PointerEvent) => void;
+    /** Fired when the pointer leaves the target element. Receives the native PointerEvent. */
+    onHoverEnd?: (event: PointerEvent) => void;
 }
 export interface UseHoverReturnValue<T extends HTMLElement = HTMLElement> {
     hovered: boolean;

package/dist/src/hooks/use-is-visible/use-is-visible.d.ts

@@ -1,10 +1,34 @@
 import { RefObject } from 'react';
-interface UseIsVisibleProps extends IntersectionObserverInit {
+export interface UseIsVisibleOptions extends IntersectionObserverInit {
+    /**
+     * Called once when the element first becomes visible.
+     * Stable — safe to pass an inline arrow function without causing observer re-attachment.
+     */
     onVisible?: () => void;
+    /**
+     * When true, the IntersectionObserver disconnects after the first positive intersection.
+     * `isVisible` latches to `true` and never flips back to `false`.
+     * The observer lifecycle is torn down early; no further intersection callbacks fire.
+     */
+    triggerOnce?: boolean;
+    /**
+     * When true, once `isVisible` becomes `true` it is never reset to `false`.
+     * The observer stays connected (unlike `triggerOnce`), so `entry` may continue updating.
+     */
+    freezeOnceVisible?: boolean;
 }
-interface UseIsVisibleReturn<T> {
+export interface UseIsVisibleReturn<T extends HTMLElement> {
+    /** Attach to the DOM element you want to observe. */
     ref: RefObject<T | null>;
+    /**
+     * True when the observed element is intersecting the viewport (or root).
+     * Stays true permanently when `triggerOnce` or `freezeOnceVisible` has triggered.
+     */
     isVisible: boolean;
+    /**
+     * The latest IntersectionObserverEntry received.
+     * `null` until the first intersection event fires.
+     */
+    entry: IntersectionObserverEntry | null;
 }
-export declare function useIsVisible<T extends HTMLElement>({ onVisible, root, rootMargin, threshold, }?: UseIsVisibleProps): UseIsVisibleReturn<T>;
-export {};
+export declare function useIsVisible<T extends HTMLElement>(options?: UseIsVisibleOptions): UseIsVisibleReturn<T>;

package/dist/src/hooks/use-local-storage/use-local-storage.d.ts

@@ -1,2 +1,13 @@
-export declare function useLocalStorage<T>(key: string): [T | undefined, (value: T) => void, () => void];
-export declare function useLocalStorage<T>(key: string, initialValue: T): [T, (value: T) => void, () => void];
+export interface Serializer<T> {
+    read: (raw: string) => T;
+    write: (value: T) => string;
+}
+export interface UseLocalStorageOptions<T> {
+    serializer?: Serializer<T>;
+}
+export declare function useLocalStorage<T>(key: string): [
+    T | undefined,
+    (value: T | ((prev: T | undefined) => T)) => void,
+    () => void
+];
+export declare function useLocalStorage<T>(key: string, initialValue: T, options?: UseLocalStorageOptions<T>): [T, (value: T | ((prev: T) => T)) => void, () => void];

package/dist/src/hooks/use-media-query/use-media-query.d.ts

@@ -1 +1,10 @@
-export declare const useMediaQuery: (query: string) => boolean;
+export interface UseMediaQueryOptions {
+    /**
+     * Value returned during server render and on the first client render
+     * before `matchMedia` has been read. Use this to avoid hydration
+     * mismatches in SSR consumers that already know the breakpoint.
+     * @default false
+     */
+    defaultValue?: boolean;
+}
+export declare function useMediaQuery(query: string, options?: UseMediaQueryOptions): boolean;

package/dist/src/hooks/use-media-query/use-media-query.test.d.ts

@@ -0,0 +1 @@
+export {};