kitzo 2.5.4 → 3.0.0

package/README.md

@@ -1,40 +1,44 @@
 # Kitzo
 
-**Lightweight React UI components and essential hooks.**
+A lightweight, production-ready React micro-utility library providing essential components, hooks, and functions for modern web applications.
 
----
-
-### Installation
+## Installation
 
 ```bash
 npm install kitzo
 ```
 
----
+## Core Features
+
+### React Components
+
+Essential, accessible, and performance-optimized UI components:
 
-### Core Features
+- **Toast**: A flexible notification system with support for custom positions, animations, and interaction patterns.
+- **Tooltip**: A contextual information component with smart positioning and customizable delay and animations.
 
-#### Components
+### React Hooks
 
-- **Toast** — Accessible, animated notifications.
-- **Tooltip** — Smart-positioned contextual labels.
+A collection of hooks to simplify common React application logic:
 
-#### Hooks
+- **useDebounce**: Delays value updates until a specified time has passed.
+- **useDebouncedCallback**: Returns a debounced version of a callback function.
+- **useThrottle**: Limits the execution rate of a frequently changing value.
+- **useLocalStorage**: Synchronizes state with browser local storage.
+- **useWindowSize**: Provides real-time window dimensions.
+- **useCopy**: Simplifies clipboard operations within components.
 
-- **useDebounce** — Optimize performance by delaying execution.
-- **useWindowSize** — Real-time viewport dimensions.
-- **useCopy** — Simple "copy to clipboard" functionality.
-- **useThrottle** —  Limits how often a value can change within a specified time interval.
+### Utility Functions
 
----
+- **copy**: A standalone function for programmatically interacting with the system clipboard.
 
-### Documentation
+## Documentation
 
-For usage guides and live demos, visit documentation:
+For full usage guides, API references, and live demonstrations, visit the documentation site:
 [https://kitzo.vercel.app](https://kitzo.vercel.app)
 
----
+Check out the [root project](file:///home/riyad/Desktop/kitzo-monorepo/README.md) for project-wide information.
 
-### License
+## License
 
-MIT
+This project is licensed under the MIT License.

package/dist/index.d.ts

@@ -51,6 +51,13 @@ declare type DebounceOptions = {
 
 declare type Options = ToastOptionsWithoutType;
 
+declare type Options_2<T> = {
+    /** Milliseconds to debounce writes to localStorage (default: 0 — no debounce). */
+    debounceMs?: number;
+    /** Called once after the first value is read from localStorage on mount. */
+    onMount?: (value: T) => void;
+};
+
 declare type PromiseToastFn = <T, E = unknown>(promise: Promise<T>, msgs: PromiseToastMsgs<T, E>, options?: PromiseToastOptions) => Promise<T>;
 
 declare type PromiseToastMsgs<T, E = unknown> = {
@@ -167,12 +174,19 @@ export declare function useDebouncedCallback<Args extends unknown[]>(callback: (
  * always use `initialValue` (preventing hydration mismatches), and the
  * real localStorage value is synced in after mount.
  *
+ * - State is updated immediately on every `setValue` call for a responsive UI.
+ * - Writes to `localStorage` are debounced by `options.debounceMs` ms.
+ * - `options.onMount` is called exactly once with the first value read from storage.
+ *
  * @example
- * const [theme, setTheme] = useLocalStorage<'light' | 'dark'>('ui-theme', 'light');
+ * const [theme, setTheme] = useLocalStorage<'light' | 'dark'>('ui-theme', 'light', {
+ *   debounceMs: 300,
+ *   onMount: (v) => console.log('loaded from storage:', v),
+ * });
  * // 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 useLocalStorage<T>(key: string, initialValue: T, options?: Options_2<T>): [T, Dispatch<SetStateAction<T>>];
 
 export declare function useThrottle<T>(value: T, delay?: number): T;
 

package/dist/react/hooks/useLocalStorage.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kitzo",
-  "version": "2.5.4",
-  "description": "A lightweight React micro-utility.",
+  "version": "3.0.0",
+  "description": "A lightweight production-ready React micro-utility library providing essential components, hooks, and functions for modern web applications.",
   "type": "module",
   "files": [
     "dist"
@@ -44,24 +44,14 @@
     "react-dom": ">=19"
   },
   "devDependencies": {
-    "@changesets/cli": "^2.29.8",
     "@eslint/js": "^9.39.2",
     "@tailwindcss/vite": "^4.1.18",
-    "@types/node": "^25.0.6",
-    "@types/react": "^19.2.8",
-    "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react-swc": "^4.2.2",
-    "daisyui": "^5.5.14",
-    "eslint": "^9.39.2",
     "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-react-refresh": "^0.4.26",
     "globals": "^17.0.0",
-    "prettier": "^3.7.4",
-    "prettier-plugin-tailwindcss": "^0.7.2",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
-    "tailwindcss": "^4.1.18",
-    "typescript": "~5.8.2",
     "typescript-eslint": "^8.52.0",
     "vite": "^7.3.1",
     "vite-plugin-dts": "^4.5.4"
@@ -70,6 +60,7 @@
     "dev": "vite",
     "dev:host": "vite --host",
     "build": "tsc -b && vite build",
+    "type-check": "tsc --noEmit",
     "lint": "eslint .",
     "preview": "vite preview",
     "cs": "changeset"