@allem-sdk/hooks 0.1.1 → 0.1.3

package/README.md

@@ -3,6 +3,7 @@
 </p>
 
 <p align="center">
+  <a href="https://www.npmjs.com/package/@allem-sdk/hooks"><img src="https://img.shields.io/npm/v/@allem-sdk/hooks.svg" alt="npm version" /></a>
   <a href="https://github.com/kingofmit/allem-sdk/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License" /></a>
   <img src="https://img.shields.io/badge/react-19-61dafb" alt="React 19" />
   <img src="https://img.shields.io/badge/typescript-strict-blue" alt="TypeScript" />
@@ -24,6 +25,7 @@ npm install @allem-sdk/hooks
 | Hook | Description |
 |------|-------------|
 | `useDebounce` | Debounce a value by a given delay |
+| `useThrottle` | Throttle a value, updating at most once per delay |
 | `useLocalStorage` | Persist state in localStorage with SSR safety |
 | `useMediaQuery` | Reactive CSS media query matching |
 | `useClickOutside` | Detect clicks outside a ref element |
@@ -31,6 +33,10 @@ npm install @allem-sdk/hooks
 | `useCopyToClipboard` | Copy text to clipboard with status |
 | `useIntersectionObserver` | Observe element visibility via IntersectionObserver |
 | `useWindowSize` | Reactive window dimensions |
+| `useFetch` | Data fetching with loading/error states and refetch |
+| `usePrevious` | Track the previous value of a variable |
+| `useKeyPress` | Detect if a specific key is pressed |
+| `useOnlineStatus` | Reactive browser online/offline status |
 
 ## Usage
 
@@ -62,6 +68,37 @@ function Dropdown() {
 }
 ```
 
+## More Examples
+
+```tsx
+import { useFetch, useThrottle, useKeyPress, useOnlineStatus, usePrevious } from "@allem-sdk/hooks";
+
+function UserList() {
+  const { data, error, isLoading, refetch } = useFetch<User[]>("/api/users");
+  const isOnline = useOnlineStatus();
+  const isEscPressed = useKeyPress("Escape");
+
+  if (!isOnline) return <p>You are offline</p>;
+  if (isLoading) return <p>Loading...</p>;
+  return <ul>{data?.map((u) => <li key={u.id}>{u.name}</li>)}</ul>;
+}
+
+function ScrollTracker() {
+  const [scroll, setScroll] = useState(0);
+  const throttledScroll = useThrottle(scroll, 100);
+  const prevScroll = usePrevious(throttledScroll);
+  const direction = prevScroll !== undefined && throttledScroll > prevScroll ? "down" : "up";
+
+  useEffect(() => {
+    const handler = () => setScroll(window.scrollY);
+    window.addEventListener("scroll", handler);
+    return () => window.removeEventListener("scroll", handler);
+  }, []);
+
+  return <p>Scrolling {direction}</p>;
+}
+```
+
 ## Part of [Allem SDK](https://github.com/kingofmit/allem-sdk)
 
 This package can be used standalone or as part of the full SDK. Install `allem-sdk` to get all packages in one install.

package/dist/index.d.mts

@@ -28,4 +28,66 @@ interface WindowSize {
 }
 declare function useWindowSize(): WindowSize;
 
-export { useClickOutside, useCopyToClipboard, useDebounce, useIntersectionObserver, useLocalStorage, useMediaQuery, useToggle, useWindowSize };
+interface UseFetchState<T> {
+    data: T | null;
+    error: Error | null;
+    isLoading: boolean;
+}
+interface UseFetchReturn<T> extends UseFetchState<T> {
+    refetch: () => void;
+}
+/**
+ * Simple data fetching hook with loading/error states and refetch.
+ *
+ * @example
+ * ```tsx
+ * const { data, error, isLoading, refetch } = useFetch<User[]>("/api/users");
+ * ```
+ */
+declare function useFetch<T = unknown>(url: string | null, options?: RequestInit): UseFetchReturn<T>;
+
+/**
+ * Throttles a value, updating at most once per `delay` ms.
+ *
+ * @example
+ * ```tsx
+ * const throttledScroll = useThrottle(scrollPosition, 100);
+ * ```
+ */
+declare function useThrottle<T>(value: T, delay: number): T;
+
+/**
+ * Returns the previous value of a variable.
+ *
+ * @example
+ * ```tsx
+ * const prevCount = usePrevious(count);
+ * // On first render: undefined
+ * // After count changes: previous count value
+ * ```
+ */
+declare function usePrevious<T>(value: T): T | undefined;
+
+/**
+ * Detects whether a specific key is currently pressed.
+ *
+ * @example
+ * ```tsx
+ * const isEscPressed = useKeyPress("Escape");
+ * const isEnterPressed = useKeyPress("Enter");
+ * ```
+ */
+declare function useKeyPress(targetKey: string): boolean;
+
+/**
+ * Tracks the browser's online/offline status reactively.
+ *
+ * @example
+ * ```tsx
+ * const isOnline = useOnlineStatus();
+ * // true when connected, false when offline
+ * ```
+ */
+declare function useOnlineStatus(): boolean;
+
+export { useClickOutside, useCopyToClipboard, useDebounce, useFetch, useIntersectionObserver, useKeyPress, useLocalStorage, useMediaQuery, useOnlineStatus, usePrevious, useThrottle, useToggle, useWindowSize };

package/dist/index.d.ts

@@ -28,4 +28,66 @@ interface WindowSize {
 }
 declare function useWindowSize(): WindowSize;
 
-export { useClickOutside, useCopyToClipboard, useDebounce, useIntersectionObserver, useLocalStorage, useMediaQuery, useToggle, useWindowSize };
+interface UseFetchState<T> {
+    data: T | null;
+    error: Error | null;
+    isLoading: boolean;
+}
+interface UseFetchReturn<T> extends UseFetchState<T> {
+    refetch: () => void;
+}
+/**
+ * Simple data fetching hook with loading/error states and refetch.
+ *
+ * @example
+ * ```tsx
+ * const { data, error, isLoading, refetch } = useFetch<User[]>("/api/users");
+ * ```
+ */
+declare function useFetch<T = unknown>(url: string | null, options?: RequestInit): UseFetchReturn<T>;
+
+/**
+ * Throttles a value, updating at most once per `delay` ms.
+ *
+ * @example
+ * ```tsx
+ * const throttledScroll = useThrottle(scrollPosition, 100);
+ * ```
+ */
+declare function useThrottle<T>(value: T, delay: number): T;
+
+/**
+ * Returns the previous value of a variable.
+ *
+ * @example
+ * ```tsx
+ * const prevCount = usePrevious(count);
+ * // On first render: undefined
+ * // After count changes: previous count value
+ * ```
+ */
+declare function usePrevious<T>(value: T): T | undefined;
+
+/**
+ * Detects whether a specific key is currently pressed.
+ *
+ * @example
+ * ```tsx
+ * const isEscPressed = useKeyPress("Escape");
+ * const isEnterPressed = useKeyPress("Enter");
+ * ```
+ */
+declare function useKeyPress(targetKey: string): boolean;
+
+/**
+ * Tracks the browser's online/offline status reactively.
+ *
+ * @example
+ * ```tsx
+ * const isOnline = useOnlineStatus();
+ * // true when connected, false when offline
+ * ```
+ */
+declare function useOnlineStatus(): boolean;
+
+export { useClickOutside, useCopyToClipboard, useDebounce, useFetch, useIntersectionObserver, useKeyPress, useLocalStorage, useMediaQuery, useOnlineStatus, usePrevious, useThrottle, useToggle, useWindowSize };

package/dist/index.js

@@ -24,9 +24,14 @@ __export(index_exports, {
   useClickOutside: () => useClickOutside,
   useCopyToClipboard: () => useCopyToClipboard,
   useDebounce: () => useDebounce,
+  useFetch: () => useFetch,
   useIntersectionObserver: () => useIntersectionObserver,
+  useKeyPress: () => useKeyPress,
   useLocalStorage: () => useLocalStorage,
   useMediaQuery: () => useMediaQuery,
+  useOnlineStatus: () => useOnlineStatus,
+  usePrevious: () => usePrevious,
+  useThrottle: () => useThrottle,
   useToggle: () => useToggle,
   useWindowSize: () => useWindowSize
 });
@@ -162,14 +167,125 @@ function useWindowSize() {
   }, []);
   return size;
 }
+
+// src/hooks/useFetch.ts
+var import_react9 = require("react");
+function useFetch(url, options) {
+  const [state, setState] = (0, import_react9.useState)({
+    data: null,
+    error: null,
+    isLoading: !!url
+  });
+  const optionsRef = (0, import_react9.useRef)(options);
+  optionsRef.current = options;
+  const fetchData = (0, import_react9.useCallback)(async () => {
+    if (!url) return;
+    setState((prev) => ({ ...prev, isLoading: true, error: null }));
+    try {
+      const res = await fetch(url, optionsRef.current);
+      if (!res.ok) throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+      const data = await res.json();
+      setState({ data, error: null, isLoading: false });
+    } catch (err) {
+      setState({ data: null, error: err, isLoading: false });
+    }
+  }, [url]);
+  (0, import_react9.useEffect)(() => {
+    fetchData();
+  }, [fetchData]);
+  return { ...state, refetch: fetchData };
+}
+
+// src/hooks/useThrottle.ts
+var import_react10 = require("react");
+function useThrottle(value, delay) {
+  const [throttled, setThrottled] = (0, import_react10.useState)(value);
+  const lastUpdated = (0, import_react10.useRef)(Date.now());
+  const timeoutRef = (0, import_react10.useRef)(void 0);
+  (0, import_react10.useEffect)(() => {
+    const now = Date.now();
+    const elapsed = now - lastUpdated.current;
+    if (elapsed >= delay) {
+      setThrottled(value);
+      lastUpdated.current = now;
+    } else {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = setTimeout(() => {
+        setThrottled(value);
+        lastUpdated.current = Date.now();
+      }, delay - elapsed);
+    }
+    return () => clearTimeout(timeoutRef.current);
+  }, [value, delay]);
+  return throttled;
+}
+
+// src/hooks/usePrevious.ts
+var import_react11 = require("react");
+function usePrevious(value) {
+  const ref = (0, import_react11.useRef)(void 0);
+  (0, import_react11.useEffect)(() => {
+    ref.current = value;
+  }, [value]);
+  return ref.current;
+}
+
+// src/hooks/useKeyPress.ts
+var import_react12 = require("react");
+function useKeyPress(targetKey) {
+  const [isPressed, setIsPressed] = (0, import_react12.useState)(false);
+  (0, import_react12.useEffect)(() => {
+    if (typeof window === "undefined") return;
+    const handleDown = (e) => {
+      if (e.key === targetKey) setIsPressed(true);
+    };
+    const handleUp = (e) => {
+      if (e.key === targetKey) setIsPressed(false);
+    };
+    window.addEventListener("keydown", handleDown);
+    window.addEventListener("keyup", handleUp);
+    return () => {
+      window.removeEventListener("keydown", handleDown);
+      window.removeEventListener("keyup", handleUp);
+    };
+  }, [targetKey]);
+  return isPressed;
+}
+
+// src/hooks/useOnlineStatus.ts
+var import_react13 = require("react");
+function subscribe(callback) {
+  if (typeof window === "undefined") return () => {
+  };
+  window.addEventListener("online", callback);
+  window.addEventListener("offline", callback);
+  return () => {
+    window.removeEventListener("online", callback);
+    window.removeEventListener("offline", callback);
+  };
+}
+function getSnapshot() {
+  return typeof navigator !== "undefined" ? navigator.onLine : true;
+}
+function getServerSnapshot() {
+  return true;
+}
+function useOnlineStatus() {
+  return (0, import_react13.useSyncExternalStore)(subscribe, getSnapshot, getServerSnapshot);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   useClickOutside,
   useCopyToClipboard,
   useDebounce,
+  useFetch,
   useIntersectionObserver,
+  useKeyPress,
   useLocalStorage,
   useMediaQuery,
+  useOnlineStatus,
+  usePrevious,
+  useThrottle,
   useToggle,
   useWindowSize
 });

package/dist/index.mjs

@@ -130,13 +130,124 @@ function useWindowSize() {
   }, []);
   return size;
 }
+
+// src/hooks/useFetch.ts
+import { useState as useState8, useEffect as useEffect6, useCallback as useCallback4, useRef } from "react";
+function useFetch(url, options) {
+  const [state, setState] = useState8({
+    data: null,
+    error: null,
+    isLoading: !!url
+  });
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const fetchData = useCallback4(async () => {
+    if (!url) return;
+    setState((prev) => ({ ...prev, isLoading: true, error: null }));
+    try {
+      const res = await fetch(url, optionsRef.current);
+      if (!res.ok) throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+      const data = await res.json();
+      setState({ data, error: null, isLoading: false });
+    } catch (err) {
+      setState({ data: null, error: err, isLoading: false });
+    }
+  }, [url]);
+  useEffect6(() => {
+    fetchData();
+  }, [fetchData]);
+  return { ...state, refetch: fetchData };
+}
+
+// src/hooks/useThrottle.ts
+import { useState as useState9, useEffect as useEffect7, useRef as useRef2 } from "react";
+function useThrottle(value, delay) {
+  const [throttled, setThrottled] = useState9(value);
+  const lastUpdated = useRef2(Date.now());
+  const timeoutRef = useRef2(void 0);
+  useEffect7(() => {
+    const now = Date.now();
+    const elapsed = now - lastUpdated.current;
+    if (elapsed >= delay) {
+      setThrottled(value);
+      lastUpdated.current = now;
+    } else {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = setTimeout(() => {
+        setThrottled(value);
+        lastUpdated.current = Date.now();
+      }, delay - elapsed);
+    }
+    return () => clearTimeout(timeoutRef.current);
+  }, [value, delay]);
+  return throttled;
+}
+
+// src/hooks/usePrevious.ts
+import { useRef as useRef3, useEffect as useEffect8 } from "react";
+function usePrevious(value) {
+  const ref = useRef3(void 0);
+  useEffect8(() => {
+    ref.current = value;
+  }, [value]);
+  return ref.current;
+}
+
+// src/hooks/useKeyPress.ts
+import { useState as useState10, useEffect as useEffect9 } from "react";
+function useKeyPress(targetKey) {
+  const [isPressed, setIsPressed] = useState10(false);
+  useEffect9(() => {
+    if (typeof window === "undefined") return;
+    const handleDown = (e) => {
+      if (e.key === targetKey) setIsPressed(true);
+    };
+    const handleUp = (e) => {
+      if (e.key === targetKey) setIsPressed(false);
+    };
+    window.addEventListener("keydown", handleDown);
+    window.addEventListener("keyup", handleUp);
+    return () => {
+      window.removeEventListener("keydown", handleDown);
+      window.removeEventListener("keyup", handleUp);
+    };
+  }, [targetKey]);
+  return isPressed;
+}
+
+// src/hooks/useOnlineStatus.ts
+import { useSyncExternalStore } from "react";
+function subscribe(callback) {
+  if (typeof window === "undefined") return () => {
+  };
+  window.addEventListener("online", callback);
+  window.addEventListener("offline", callback);
+  return () => {
+    window.removeEventListener("online", callback);
+    window.removeEventListener("offline", callback);
+  };
+}
+function getSnapshot() {
+  return typeof navigator !== "undefined" ? navigator.onLine : true;
+}
+function getServerSnapshot() {
+  return true;
+}
+function useOnlineStatus() {
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
 export {
   useClickOutside,
   useCopyToClipboard,
   useDebounce,
+  useFetch,
   useIntersectionObserver,
+  useKeyPress,
   useLocalStorage,
   useMediaQuery,
+  useOnlineStatus,
+  usePrevious,
+  useThrottle,
   useToggle,
   useWindowSize
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@allem-sdk/hooks",
-  "version": "0.1.1",
-  "description": "A collection of essential React hooks for modern applications",
+  "version": "0.1.3",
+  "description": "8 essential React hooks: useDebounce, useLocalStorage, useMediaQuery, useClickOutside, useToggle, useCopyToClipboard, useIntersectionObserver, useWindowSize. SSR-safe, TypeScript strict.",
   "license": "MIT",
   "author": "Ahmed Allem",
   "main": "./dist/index.js",
@@ -39,10 +39,18 @@
   "keywords": [
     "allem-sdk",
     "react",
-    "hooks",
+    "react-hooks",
     "useDebounce",
+    "useLocalStorage",
     "useMediaQuery",
-    "useLocalStorage"
+    "useClickOutside",
+    "useToggle",
+    "useCopyToClipboard",
+    "useIntersectionObserver",
+    "useWindowSize",
+    "ssr",
+    "typescript",
+    "nextjs"
   ],
   "publishConfig": {
     "access": "public"