kitzo 2.5.2 → 2.5.4

package/dist/index.d.ts

@@ -1,6 +1,8 @@
+import { Dispatch } from 'react';
 import { JSX } from 'react/jsx-runtime';
 import { PropsWithChildren } from 'react';
 import { ReactNode } from 'react';
+import { SetStateAction } from 'react';
 
 declare type AnimationOptions = {
     duration?: number;
@@ -13,6 +15,40 @@ declare type AnimationOptions = {
 
 declare type CopyStatus = 'standby' | 'copying' | 'copied' | 'error';
 
+declare type DebouncedFunction<Args extends unknown[]> = {
+    /**
+     * The debounced version of your callback.
+     * @param args - The arguments passed to the original callback.
+     */
+    (...args: Args): void;
+    /**
+     * Cancels any scheduled execution of the debounced callback.
+     */
+    cancel: () => void;
+    /**
+     * Immediately invokes the pending execution of the debounced callback and cancels the timer.
+     */
+    flush: () => void;
+};
+
+declare type DebounceOptions = {
+    /**
+     * If true, the callback is invoked on the leading edge of the timeout (immediately on the first call).
+     * @default false
+     */
+    leading?: boolean;
+    /**
+     * If true, the callback is invoked on the trailing edge of the timeout (after the delay has passed).
+     * @default true
+     */
+    trailing?: boolean;
+    /**
+     * The number of milliseconds to delay execution.
+     * @default 300
+     */
+    delay?: number;
+};
+
 declare type Options = ToastOptionsWithoutType;
 
 declare type PromiseToastFn = <T, E = unknown>(promise: Promise<T>, msgs: PromiseToastMsgs<T, E>, options?: PromiseToastOptions) => Promise<T>;
@@ -114,6 +150,30 @@ declare type UseCopyReturn = {
 
 export declare function useDebounce<T>(value: T, delay?: number): T;
 
+/**
+ * A hook that returns a memoized debounced function to limit the execution rate of a callback.
+ * * @template Args - The type of arguments accepted by the callback.
+ * @param callback - The function to debounce.
+ * @param options - Configuration for leading/trailing edges and delay.
+ * @returns A debounced function with `.cancel()` and `.flush()` methods.
+ */
+export declare function useDebouncedCallback<Args extends unknown[]>(callback: (...args: Args) => void, options?: DebounceOptions): DebouncedFunction<Args>;
+
+/**
+ * A custom hook that manages a stateful value in `localStorage`,
+ * with full SSR safety and cross-tab synchronization.
+ *
+ * The hook uses a two-phase approach: the server and first client render
+ * always use `initialValue` (preventing hydration mismatches), and the
+ * real localStorage value is synced in after mount.
+ *
+ * @example
+ * const [theme, setTheme] = useLocalStorage<'light' | 'dark'>('ui-theme', 'light');
+ * // Supports functional updates:
+ * setTheme(prev => prev === 'light' ? 'dark' : 'light');
+ */
+export declare function useLocalStorage<T>(key: string, initialValue: T): [T, Dispatch<SetStateAction<T>>];
+
 export declare function useThrottle<T>(value: T, delay?: number): T;
 
 export declare function useWindowSize(updateDelay?: number): {

package/dist/index.js

@@ -2,15 +2,19 @@ import { Toaster as r } from "./react/components/toast/Toaster.js";
 import { Tooltip as p } from "./react/components/tooltip/Tooltip.js";
 import { toast as m } from "./react/components/toast/service/triggerToasts.js";
 import { useCopy as s } from "./react/hooks/useCopy.js";
-import { useDebounce as i } from "./react/hooks/useDebounce.js";
-import { useThrottle as a } from "./react/hooks/useThrottle.js";
-import { useWindowSize as n } from "./react/hooks/useWindowSize.js";
+import { useDebounce as a } from "./react/hooks/useDebounce.js";
+import { useDebouncedCallback as c } from "./react/hooks/useDebouncedCallback.js";
+import { useLocalStorage as i } from "./react/hooks/useLocalStorage.js";
+import { useThrottle as T } from "./react/hooks/useThrottle.js";
+import { useWindowSize as C } from "./react/hooks/useWindowSize.js";
 export {
   r as Toaster,
   p as Tooltip,
   m as toast,
   s as useCopy,
-  i as useDebounce,
-  a as useThrottle,
-  n as useWindowSize
+  a as useDebounce,
+  c as useDebouncedCallback,
+  i as useLocalStorage,
+  T as useThrottle,
+  C as useWindowSize
 };

package/dist/react/hooks/useDebouncedCallback.js

@@ -0,0 +1,33 @@
+import { useRef as l, useEffect as g, useMemo as p } from "react";
+function b(s, m = {}) {
+  const { leading: i = !1, trailing: f = !0, delay: a = 300 } = m, t = l(s), r = l(null), e = l(null), n = l(!1);
+  g(() => {
+    t.current = s;
+  }, [s]);
+  const o = p(() => {
+    const u = (...c) => {
+      r.current = c;
+      const T = () => {
+        t.current(...c);
+      };
+      e.current && clearTimeout(e.current), i && !e.current ? (T(), n.current = !0) : n.current = !1, e.current = setTimeout(() => {
+        const d = r.current, k = f && !n.current && d;
+        e.current = null, n.current = !1, r.current = null, k && t.current(...d);
+      }, a);
+    };
+    return u.cancel = () => {
+      e.current && (clearTimeout(e.current), e.current = null), r.current = null, n.current = !1;
+    }, u.flush = () => {
+      if (e.current && r.current) {
+        const c = r.current;
+        u.cancel(), t.current(...c);
+      }
+    }, u;
+  }, [a, i, f]);
+  return g(() => () => {
+    o.cancel();
+  }, [o]), o;
+}
+export {
+  b as useDebouncedCallback
+};

package/dist/react/hooks/useLocalStorage.js

@@ -0,0 +1,33 @@
+import n from "react";
+function w(t, r) {
+  const [a, s] = n.useState(r), c = n.useCallback(() => {
+    try {
+      const e = window.localStorage.getItem(t);
+      return e ? JSON.parse(e) : r;
+    } catch (e) {
+      return console.warn(`Error reading localStorage key "${t}":`, e), r;
+    }
+  }, [t, r]), d = n.useCallback(
+    (e) => {
+      try {
+        const o = e instanceof Function ? e(a) : e;
+        s(o), typeof window < "u" && (window.localStorage.setItem(t, JSON.stringify(o)), window.dispatchEvent(new Event("local-storage-update")));
+      } catch (o) {
+        console.warn(`Error setting localStorage key "${t}":`, o);
+      }
+    },
+    [t, a]
+  );
+  return n.useEffect(() => {
+    s(c());
+    const e = (o) => {
+      o.key && o.key !== t || s(c());
+    };
+    return window.addEventListener("storage", e), window.addEventListener("local-storage-update", e), () => {
+      window.removeEventListener("storage", e), window.removeEventListener("local-storage-update", e);
+    };
+  }, [t, c]), [a, d];
+}
+export {
+  w as useLocalStorage
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kitzo",
-  "version": "2.5.2",
+  "version": "2.5.4",
   "description": "A lightweight React micro-utility.",
   "type": "module",
   "files": [