@himanshu-sorathiya/react-kit 1.0.28 → 1.0.30

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 // Generated by dts-bundle-generator v9.5.1
 
 import React$1 from 'react';
-import { CSSProperties, Key, RefObject } from 'react';
+import { Key, RefObject } from 'react';
 
 /**
  * The native event that triggered a `useClickOutside` handler. Determined
@@ -417,6 +417,162 @@ export type UseKeyReturn = () => void;
  * ```
  */
 export declare function useKey(key: string, handler: (event: KeyboardEvent) => void, options?: UseKeyOptions): UseKeyReturn;
+/**
+ * Configuration for `useBatcher`.
+ *
+ * All three flush triggers (`maxSize`, `maxWait`, `quietPeriod`) are
+ * optional and independent — configure any combination, and whichever
+ * condition is met first triggers the flush. If none are configured, the
+ * batch only ever flushes when `flush()` is called manually.
+ */
+export interface BatchOptions<Item> {
+	/**
+	 * Flushes the batch immediately once it reaches this many items.
+	 * Checked on every `add()` call, before either timer-based trigger is
+	 * considered.
+	 *
+	 * Invalid input (not a positive number) is ignored — not clamped to a
+	 * fallback — with a dev-mode warning, since there's no sensible
+	 * default size to fall back to.
+	 *
+	 * @defaultValue `undefined` (no size ceiling)
+	 */
+	maxSize?: number;
+	/**
+	 * A hard ceiling, in milliseconds, on how long a batch can sit before
+	 * flushing — measured from the moment the *first* item of the current
+	 * batch was added, not the most recent one. Guarantees a maximum
+	 * latency per item regardless of how long the batch keeps growing.
+	 *
+	 * Invalid input (not a non-negative number) is ignored with a dev-mode
+	 * warning.
+	 *
+	 * @defaultValue `undefined` (no time ceiling)
+	 */
+	maxWait?: number;
+	/**
+	 * Flushes the batch once this many milliseconds pass with no further
+	 * items added — resets on every `add()` call, unlike `maxWait`. Use
+	 * this when you want to wait for activity to genuinely settle before
+	 * flushing, rather than enforcing a hard per-item latency ceiling.
+	 *
+	 * If both `maxWait` and `quietPeriod` are configured and `quietPeriod`
+	 * is not shorter than `maxWait`, `maxWait` will almost always win the
+	 * race — a dev-mode warning flags this combination.
+	 *
+	 * Invalid input (not a non-negative number) is ignored with a dev-mode
+	 * warning.
+	 *
+	 * @defaultValue `undefined` (no quiet-period trigger)
+	 */
+	quietPeriod?: number;
+	/**
+	 * Called with a snapshot of the current batch contents every time it
+	 * changes — after every `add()`, and after every flush or `cancel()`
+	 * (with an empty array). This is the mechanism for getting live,
+	 * reactive access to what's currently queued (e.g. a "3 items
+	 * queued…" indicator) without `useBatcher` itself needing to hold the
+	 * full item list in React state.
+	 *
+	 * Safe to pass a fresh inline function on every render — it's captured
+	 * in a ref and refreshed via effect, same as `onFlush`.
+	 *
+	 * @defaultValue `undefined`
+	 */
+	onItemsChange?: (items: readonly Item[]) => void;
+}
+/**
+ * The object returned by `useBatcher`.
+ */
+export interface UseBatcherReturn<Item> {
+	/**
+	 * Adds `item` to the current batch. Never rejected, never deferred to
+	 * a future call — the item is always accepted immediately. Depending
+	 * on the configured triggers, this may also cause an immediate flush
+	 * (e.g. if `maxSize` is now reached).
+	 */
+	add: (item: Item) => void;
+	/**
+	 * Immediately flushes whatever is currently batched, bypassing
+	 * `maxWait`/`quietPeriod` entirely. A no-op if the batch is empty —
+	 * `onFlush` is never called with zero items.
+	 */
+	flush: () => void;
+	/**
+	 * Discards the current batch entirely, without ever calling
+	 * `onFlush`. Clears any pending timers.
+	 */
+	cancel: () => void;
+	/**
+	 * Suspends all automatic flush triggers (`maxSize`, `maxWait`,
+	 * `quietPeriod`). Items added via `add()` while paused still
+	 * accumulate normally — pausing stops the flushing machinery, not the
+	 * accumulation. The only way to flush while paused is a manual
+	 * `flush()` call.
+	 */
+	pause: () => void;
+	/**
+	 * Resumes automatic flushing. If the batch already meets `maxSize`
+	 * (because items kept arriving while paused), flushes immediately.
+	 * Otherwise, re-arms `maxWait`/`quietPeriod` timers from scratch —
+	 * pausing does not preserve partial progress toward either deadline;
+	 * resuming starts a fresh clock for whatever's still batched.
+	 */
+	resume: () => void;
+	/** The number of items currently in the batch. */
+	size: number;
+	/** `true` whenever `size > 0`. */
+	isPending: boolean;
+	/** `true` after `pause()`, until the next `resume()`. */
+	isPaused: boolean;
+}
+/**
+ * Groups rapid, individual `add()` calls into batches, flushing the whole
+ * accumulated group to `onFlush` at once — instead of debouncing,
+ * throttling, or rate-limiting, all of which discard some calls along the
+ * way. Nothing added to a `useBatcher` is ever dropped; it's only ever
+ * grouped.
+ *
+ * A batch flushes when any configured trigger fires first: reaching
+ * `maxSize` items, `maxWait` milliseconds since the batch's first item,
+ * or `quietPeriod` milliseconds of no new items. All three are optional
+ * and can be combined freely. If none are configured, only a manual
+ * `flush()` call ever empties the batch.
+ *
+ * Unlike the debounce/throttle/rate-limit hook families, there's no
+ * separate `Callback`/`State`/`Value` wrapper — `onFlush` is a single
+ * fixed handler (captured in a ref and always current, so a fresh inline
+ * function on every render is safe), and live access to the current batch
+ * contents is available via the `onItemsChange` option instead of a
+ * dedicated hook.
+ *
+ * @example
+ * ```tsx
+ * function AnalyticsProvider({ children }: { children: React.ReactNode }) {
+ *   const { add } = useBatcher<AnalyticsEvent>(
+ *     (events) => sendAnalyticsBatch(events),
+ *     { maxSize: 20, maxWait: 5000 },
+ *   );
+ *
+ *   // `track` can be called as often as needed — events are grouped and
+ *   // sent in batches of up to 20, at least once every 5 seconds.
+ *   const track = (event: AnalyticsEvent) => add(event);
+ *
+ *   return (
+ *     <AnalyticsContext.Provider value={{ track }}>
+ *       {children}
+ *     </AnalyticsContext.Provider>
+ *   );
+ * }
+ * ```
+ *
+ * @param onFlush - Called with every item accumulated since the last
+ * flush, as a snapshot array. Safe to pass a fresh inline function on
+ * every render.
+ * @param options - See {@link BatchOptions}.
+ * @returns See {@link UseBatcherReturn}.
+ */
+export declare function useBatcher<Item>(onFlush: (items: readonly Item[]) => void, options?: BatchOptions<Item>): UseBatcherReturn<Item>;
 /**
  * Adds an optional custom equality comparator to any hook that manages a
  * value and needs to decide whether a "new" value is actually different
@@ -1966,15 +2122,6 @@ export interface FuzzyHighlighterProps {
 	caseSensitive?: boolean;
 }
 export declare function FuzzyHighlighter({ text, query, className, caseSensitive, }: FuzzyHighlighterProps): React$1.JSX.Element;
-export interface ModalLayoutProps {
-	modalId: string;
-	children: React$1.ReactNode;
-	wrapperClassName?: string;
-	wrapperStyle?: React$1.CSSProperties;
-	containerClassName?: string;
-	containerStyle?: React$1.CSSProperties;
-}
-export declare function ModalLayout({ modalId, children, wrapperClassName, wrapperStyle, containerClassName, containerStyle, }: ModalLayoutProps): import("react").ReactPortal | null;
 export type ExpansionId = string | number;
 export interface UseExpansionReturn<T> {
 	expandedIds: ExpansionId[];
@@ -1994,20 +2141,6 @@ export declare function useExpansion<T = unknown>(options?: {
 	initialExpandedIds?: ExpansionId[];
 	multiple?: boolean;
 }): UseExpansionReturn<T>;
-export interface UseModalStateReturn<TData> {
-	isOpen: boolean;
-	id: string | null;
-	data: TData | undefined;
-}
-export interface UseModalActionsReturn {
-	openModal: <T = unknown>(id: string, data?: T) => void;
-	closeModal: () => void;
-	clearModal: () => void;
-}
-export type UseModalReturn<TData> = UseModalStateReturn<TData> & UseModalActionsReturn;
-export declare function useModalState<TData = unknown>(): UseModalStateReturn<TData>;
-export declare function useModalActions(): UseModalActionsReturn;
-export declare function useModal<TData = unknown>(): UseModalReturn<TData>;
 export type PinId = string | number;
 export interface UsePinReturn<T> {
 	pinnedIds: PinId[];

package/dist/index.js

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

package/dist/performance.d.ts

@@ -2,6 +2,162 @@
 
 import { Key } from 'react';
 
+/**
+ * Configuration for `useBatcher`.
+ *
+ * All three flush triggers (`maxSize`, `maxWait`, `quietPeriod`) are
+ * optional and independent — configure any combination, and whichever
+ * condition is met first triggers the flush. If none are configured, the
+ * batch only ever flushes when `flush()` is called manually.
+ */
+export interface BatchOptions<Item> {
+	/**
+	 * Flushes the batch immediately once it reaches this many items.
+	 * Checked on every `add()` call, before either timer-based trigger is
+	 * considered.
+	 *
+	 * Invalid input (not a positive number) is ignored — not clamped to a
+	 * fallback — with a dev-mode warning, since there's no sensible
+	 * default size to fall back to.
+	 *
+	 * @defaultValue `undefined` (no size ceiling)
+	 */
+	maxSize?: number;
+	/**
+	 * A hard ceiling, in milliseconds, on how long a batch can sit before
+	 * flushing — measured from the moment the *first* item of the current
+	 * batch was added, not the most recent one. Guarantees a maximum
+	 * latency per item regardless of how long the batch keeps growing.
+	 *
+	 * Invalid input (not a non-negative number) is ignored with a dev-mode
+	 * warning.
+	 *
+	 * @defaultValue `undefined` (no time ceiling)
+	 */
+	maxWait?: number;
+	/**
+	 * Flushes the batch once this many milliseconds pass with no further
+	 * items added — resets on every `add()` call, unlike `maxWait`. Use
+	 * this when you want to wait for activity to genuinely settle before
+	 * flushing, rather than enforcing a hard per-item latency ceiling.
+	 *
+	 * If both `maxWait` and `quietPeriod` are configured and `quietPeriod`
+	 * is not shorter than `maxWait`, `maxWait` will almost always win the
+	 * race — a dev-mode warning flags this combination.
+	 *
+	 * Invalid input (not a non-negative number) is ignored with a dev-mode
+	 * warning.
+	 *
+	 * @defaultValue `undefined` (no quiet-period trigger)
+	 */
+	quietPeriod?: number;
+	/**
+	 * Called with a snapshot of the current batch contents every time it
+	 * changes — after every `add()`, and after every flush or `cancel()`
+	 * (with an empty array). This is the mechanism for getting live,
+	 * reactive access to what's currently queued (e.g. a "3 items
+	 * queued…" indicator) without `useBatcher` itself needing to hold the
+	 * full item list in React state.
+	 *
+	 * Safe to pass a fresh inline function on every render — it's captured
+	 * in a ref and refreshed via effect, same as `onFlush`.
+	 *
+	 * @defaultValue `undefined`
+	 */
+	onItemsChange?: (items: readonly Item[]) => void;
+}
+/**
+ * The object returned by `useBatcher`.
+ */
+export interface UseBatcherReturn<Item> {
+	/**
+	 * Adds `item` to the current batch. Never rejected, never deferred to
+	 * a future call — the item is always accepted immediately. Depending
+	 * on the configured triggers, this may also cause an immediate flush
+	 * (e.g. if `maxSize` is now reached).
+	 */
+	add: (item: Item) => void;
+	/**
+	 * Immediately flushes whatever is currently batched, bypassing
+	 * `maxWait`/`quietPeriod` entirely. A no-op if the batch is empty —
+	 * `onFlush` is never called with zero items.
+	 */
+	flush: () => void;
+	/**
+	 * Discards the current batch entirely, without ever calling
+	 * `onFlush`. Clears any pending timers.
+	 */
+	cancel: () => void;
+	/**
+	 * Suspends all automatic flush triggers (`maxSize`, `maxWait`,
+	 * `quietPeriod`). Items added via `add()` while paused still
+	 * accumulate normally — pausing stops the flushing machinery, not the
+	 * accumulation. The only way to flush while paused is a manual
+	 * `flush()` call.
+	 */
+	pause: () => void;
+	/**
+	 * Resumes automatic flushing. If the batch already meets `maxSize`
+	 * (because items kept arriving while paused), flushes immediately.
+	 * Otherwise, re-arms `maxWait`/`quietPeriod` timers from scratch —
+	 * pausing does not preserve partial progress toward either deadline;
+	 * resuming starts a fresh clock for whatever's still batched.
+	 */
+	resume: () => void;
+	/** The number of items currently in the batch. */
+	size: number;
+	/** `true` whenever `size > 0`. */
+	isPending: boolean;
+	/** `true` after `pause()`, until the next `resume()`. */
+	isPaused: boolean;
+}
+/**
+ * Groups rapid, individual `add()` calls into batches, flushing the whole
+ * accumulated group to `onFlush` at once — instead of debouncing,
+ * throttling, or rate-limiting, all of which discard some calls along the
+ * way. Nothing added to a `useBatcher` is ever dropped; it's only ever
+ * grouped.
+ *
+ * A batch flushes when any configured trigger fires first: reaching
+ * `maxSize` items, `maxWait` milliseconds since the batch's first item,
+ * or `quietPeriod` milliseconds of no new items. All three are optional
+ * and can be combined freely. If none are configured, only a manual
+ * `flush()` call ever empties the batch.
+ *
+ * Unlike the debounce/throttle/rate-limit hook families, there's no
+ * separate `Callback`/`State`/`Value` wrapper — `onFlush` is a single
+ * fixed handler (captured in a ref and always current, so a fresh inline
+ * function on every render is safe), and live access to the current batch
+ * contents is available via the `onItemsChange` option instead of a
+ * dedicated hook.
+ *
+ * @example
+ * ```tsx
+ * function AnalyticsProvider({ children }: { children: React.ReactNode }) {
+ *   const { add } = useBatcher<AnalyticsEvent>(
+ *     (events) => sendAnalyticsBatch(events),
+ *     { maxSize: 20, maxWait: 5000 },
+ *   );
+ *
+ *   // `track` can be called as often as needed — events are grouped and
+ *   // sent in batches of up to 20, at least once every 5 seconds.
+ *   const track = (event: AnalyticsEvent) => add(event);
+ *
+ *   return (
+ *     <AnalyticsContext.Provider value={{ track }}>
+ *       {children}
+ *     </AnalyticsContext.Provider>
+ *   );
+ * }
+ * ```
+ *
+ * @param onFlush - Called with every item accumulated since the last
+ * flush, as a snapshot array. Safe to pass a fresh inline function on
+ * every render.
+ * @param options - See {@link BatchOptions}.
+ * @returns See {@link UseBatcherReturn}.
+ */
+export declare function useBatcher<Item>(onFlush: (items: readonly Item[]) => void, options?: BatchOptions<Item>): UseBatcherReturn<Item>;
 /**
  * Adds an optional custom equality comparator to any hook that manages a
  * value and needs to decide whether a "new" value is actually different

package/dist/performance.js

@@ -1,2 +1,2 @@
-import { a as e, c as t, d as n, f as r, i, l as a, m as o, n as s, o as c, p as l, r as u, s as d, t as f, u as p } from "./performance2.js";
-export { l as useDebouncedCallback, r as useDebouncedState, n as useDebouncedValue, o as useDebouncer, a as useRateLimitedCallback, t as useRateLimitedState, d as useRateLimitedValue, p as useRateLimiter, e as useThrottledCallback, i as useThrottledState, u as useThrottledValue, c as useThrottler, s as useVirtualGrid, f as useVirtualList };
+import { a as e, c as t, d as n, f as r, h as i, i as a, l as o, m as s, n as c, o as l, p as u, r as d, s as f, t as p, u as m } from "./performance2.js";
+export { i as useBatcher, u as useDebouncedCallback, r as useDebouncedState, n as useDebouncedValue, s as useDebouncer, o as useRateLimitedCallback, t as useRateLimitedState, f as useRateLimitedValue, m as useRateLimiter, e as useThrottledCallback, a as useThrottledState, d as useThrottledValue, l as useThrottler, c as useVirtualGrid, p as useVirtualList };