kitzo 2.5.5 → 3.1.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](https://github.com/riyad-96/kitzo) for project-wide information.
 
-### License
+## 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,7 +1,7 @@
 {
   "name": "kitzo",
-  "version": "2.5.5",
-  "description": "A lightweight React micro-utility.",
+  "version": "3.1.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"