kitzo 3.0.0 → 3.1.1

package/README.md

@@ -1,44 +1,40 @@
 # Kitzo
 
-A lightweight, production-ready React micro-utility library providing essential components, hooks, and functions for modern web applications.
+Lightweight, production-ready React micro-utilities for modern web applications. Focus on simplicity, performance, and minimal footprint.
+
+[Full Documentation & Demos](https://kitzo.vercel.app)
 
 ## Installation
 
 ```bash
 npm install kitzo
+# or
+pnpm add kitzo
 ```
 
-## Core Features
-
-### React Components
-
-Essential, accessible, and performance-optimized UI components:
-
-- **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.
-
-### React Hooks
+## Features
 
-A collection of hooks to simplify common React application logic:
+### Components
+- **Toast**: Smart notification system with flexible positioning.
+- **Tooltip**: Contextual information with auto-positioning logic.
 
-- **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.
+### Hooks
+- **useCopy**: Easy clipboard management.
+- **useDebounce**: Debounc any value.
+- **useDebouncedCallback**: Debounce function calls.
+- **useLocalStorage**: State persistence via storage.
+- **useOverlay**: History-synchronized overlay management.
+- **useThrottle**: Limit execution rate.
+- **useWindowSize**: Real-time window dimensions.
 
-### Utility Functions
+### Utilities
+- **copy**: Standalone programmatic clipboard copy.
 
-- **copy**: A standalone function for programmatically interacting with the system clipboard.
-
-## 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.
+## See Also
+- [Root Repository](https://github.com/riyad-96/kitzo)
+- [Documentation](https://github.com/riyad-96/kitzo/tree/main/apps/docs)
 
 ## License
+MIT
+
 
-This project is licensed under the MIT License.

package/dist/index.d.ts

@@ -188,11 +188,27 @@ export declare function useDebouncedCallback<Args extends unknown[]>(callback: (
  */
 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;
+/**
+ * A React hook that manages UI overlays (modal, drawer, popover, etc.)
+ * and synchronizes them with the browser navigation history.
+ *
+ * @param id - A stable unique identifier for the overlay.
+ *             Required to maintain history state across navigations.
+ *             Recommendation: Use page-scoped names like 'login-page:otp-modal'.
+ *
+ * @returns {isOpen: boolean, open: () => void, close: () => void}
+     */
+ export declare function useOverlay(id: string): {
+     isOpen: boolean;
+     open: () => void;
+     close: () => void;
+ };
 
-export declare function useWindowSize(updateDelay?: number): {
-    screenWidth: number;
-    screenHeight: number;
-};
+ export declare function useThrottle<T>(value: T, delay?: number): T;
+
+ export declare function useWindowSize(updateDelay?: number): {
+     screenWidth: number;
+     screenHeight: number;
+ };
 
-export { }
+ export { }

package/dist/index.js

@@ -5,8 +5,9 @@ import { useCopy as s } from "./react/hooks/useCopy.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";
+import { useOverlay as T } from "./react/hooks/useOverlay.js";
+import { useThrottle as y } from "./react/hooks/useThrottle.js";
+import { useWindowSize as D } from "./react/hooks/useWindowSize.js";
 export {
   r as Toaster,
   p as Tooltip,
@@ -15,6 +16,7 @@ export {
   a as useDebounce,
   c as useDebouncedCallback,
   i as useLocalStorage,
-  T as useThrottle,
-  C as useWindowSize
+  T as useOverlay,
+  y as useThrottle,
+  D as useWindowSize
 };

package/dist/react/hooks/useOverlay.js

@@ -0,0 +1,43 @@
+import { useState as w, useEffect as d } from "react";
+const n = "__kitzo_overlays";
+let o = [];
+const a = /* @__PURE__ */ new Set();
+if (typeof window < "u") {
+  const e = () => {
+    o = window.history.state?.[n] || [], a.forEach((r) => r(o));
+  };
+  window.addEventListener("popstate", e), window.history.state && (o = window.history.state[n] || []);
+}
+function f(e) {
+  if (!e)
+    throw new Error(
+      `useOverlay requires a unique "id" parameter to manage history state correctly. Recommendation: Use a page-scoped name like 'login-page:my-modal'.`
+    );
+  const [c, r] = w(() => o.includes(e));
+  return d(() => {
+    const t = (s) => {
+      r(s.includes(e));
+    };
+    return a.add(t), t(o), () => {
+      a.delete(t);
+    };
+  }, [e]), {
+    isOpen: c,
+    open: () => {
+      const t = window.history.state || {}, s = t[n] || [];
+      if (!s.includes(e)) {
+        const i = [...s, e];
+        window.history.pushState(
+          { ...t, [n]: i },
+          ""
+        ), o = i, a.forEach((l) => l(o));
+      }
+    },
+    close: () => {
+      ((window.history.state || {})[n] || []).includes(e) ? window.history.back() : r(!1);
+    }
+  };
+}
+export {
+  f as useOverlay
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kitzo",
-  "version": "3.0.0",
+  "version": "3.1.1",
   "description": "A lightweight production-ready React micro-utility library providing essential components, hooks, and functions for modern web applications.",
   "type": "module",
   "files": [