@vibehooks/react 0.0.1

package/dist/usePreferredLanguage.d.ts

@@ -0,0 +1,55 @@
+//#region src/usePreferredLanguage.d.ts
+
+interface PreferredLanguageReturn {
+  /**
+   * Language effectively used by the application.
+   */
+  language: string;
+  /**
+   * Updates the user-selected language.
+   */
+  setUserLanguage: (lang: string) => void;
+  /**
+   * System / browser language.
+   */
+  systemLanguage: string;
+  /**
+   * User-selected language, if any.
+   */
+  userLanguage: string | null;
+}
+/**
+ * `usePreferredLanguage` is a custom React hook that resolves the effective language for the application.
+ * This hook is SSR-safe and unopinionated.
+ *
+ * @example
+ * ```tsx
+ * function LanguageSelector() {
+ *   const {
+ *     language,
+ *     userLanguage,
+ *     systemLanguage,
+ *     setUserLanguage,
+ *   } = useResolvedLanguage();
+ *
+ *   return (
+ *     <div>
+ *       <p>Resolved: {language}</p>
+ *       <p>System: {systemLanguage}</p>
+ *       <p>User: {userLanguage ?? 'system default'}</p>
+ *
+ *       <button onClick={() => setUserLanguage('en')}>
+ *         English
+ *       </button>
+ *
+ *       <button onClick={() => setUserLanguage('es-PE')}>
+ *         Español
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function usePreferredLanguage(): PreferredLanguageReturn;
+//#endregion
+export { usePreferredLanguage };

package/dist/usePreferredLanguage.js

@@ -0,0 +1,127 @@
+import * as React from "react";
+
+//#region src/usePreferredLanguage.ts
+function createSystemLanguageStore() {
+	const listeners = /* @__PURE__ */ new Set();
+	let listening = false;
+	function emit() {
+		listeners.forEach((listener) => listener());
+	}
+	function subscribe(listener) {
+		listeners.add(listener);
+		if (!listening && typeof window !== "undefined") {
+			window.addEventListener("languagechange", emit);
+			listening = true;
+		}
+		return () => {
+			listeners.delete(listener);
+			if (listeners.size === 0 && listening) {
+				window.removeEventListener("languagechange", emit);
+				listening = false;
+			}
+		};
+	}
+	function getSnapshot() {
+		if (typeof window === "undefined") return "en";
+		return window.navigator.language;
+	}
+	function getServerSnapshot() {
+		return "en";
+	}
+	return {
+		getServerSnapshot,
+		getSnapshot,
+		subscribe
+	};
+}
+const systemLanguageStore = createSystemLanguageStore();
+function createUserLanguageStore() {
+	const listeners = /* @__PURE__ */ new Set();
+	const storageKey = "preferred-language";
+	let listening = false;
+	function emit() {
+		listeners.forEach((listener) => listener());
+	}
+	function subscribe(listener) {
+		listeners.add(listener);
+		if (!listening && typeof window !== "undefined") {
+			const onStorage = (event) => {
+				if (event.key === storageKey) emit();
+			};
+			window.addEventListener("storage", onStorage);
+			listening = true;
+			return () => {
+				listeners.delete(listener);
+				if (listeners.size === 0) {
+					window.removeEventListener("storage", onStorage);
+					listening = false;
+				}
+			};
+		}
+		return () => listeners.delete(listener);
+	}
+	function getSnapshot() {
+		if (typeof window === "undefined") return "en";
+		return localStorage.getItem(storageKey) ?? "en";
+	}
+	function getServerSnapshot() {
+		return "en";
+	}
+	function setLanguage(lang) {
+		if (typeof window === "undefined") return;
+		localStorage.setItem(storageKey, lang);
+		emit();
+	}
+	return {
+		getServerSnapshot,
+		getSnapshot,
+		setLanguage,
+		subscribe
+	};
+}
+const userLanguageStore = createUserLanguageStore();
+/**
+* `usePreferredLanguage` is a custom React hook that resolves the effective language for the application.
+* This hook is SSR-safe and unopinionated.
+*
+* @example
+* ```tsx
+* function LanguageSelector() {
+*   const {
+*     language,
+*     userLanguage,
+*     systemLanguage,
+*     setUserLanguage,
+*   } = useResolvedLanguage();
+*
+*   return (
+*     <div>
+*       <p>Resolved: {language}</p>
+*       <p>System: {systemLanguage}</p>
+*       <p>User: {userLanguage ?? 'system default'}</p>
+*
+*       <button onClick={() => setUserLanguage('en')}>
+*         English
+*       </button>
+*
+*       <button onClick={() => setUserLanguage('es-PE')}>
+*         Español
+*       </button>
+*     </div>
+*   );
+* }
+* ```
+*/
+function usePreferredLanguage() {
+	const systemLanguage = React.useSyncExternalStore(systemLanguageStore.subscribe, systemLanguageStore.getSnapshot, systemLanguageStore.getServerSnapshot);
+	const userLanguage = React.useSyncExternalStore(userLanguageStore.subscribe, userLanguageStore.getSnapshot, userLanguageStore.getServerSnapshot);
+	return {
+		language: userLanguage || systemLanguage || "en",
+		setUserLanguage: userLanguageStore.setLanguage,
+		systemLanguage,
+		userLanguage: userLanguage ?? null
+	};
+}
+
+//#endregion
+export { usePreferredLanguage };

package/dist/usePreferredTheme.d.ts

@@ -0,0 +1,67 @@
+//#region src/usePreferredTheme.d.ts
+type Theme = string;
+interface PreferredThemeReturn {
+  /**
+   * Sets a user-selected theme.
+   */
+  setUserTheme: (theme: Theme | null) => void;
+  /**
+   * System / OS preferred theme.
+   */
+  systemTheme: Theme;
+  /**
+   * Theme effectively used by the application.
+   */
+  theme: Theme;
+  /**
+   * Toggles between two themes.
+   * Defaults to 'light' and 'dark'.
+   */
+  toggleTheme: (options?: {
+    dark?: Theme;
+    light?: Theme;
+  }) => void;
+  /**
+   * User-selected theme, if any.
+   */
+  userTheme: Theme | null;
+}
+/**
+ * `usePreferredTheme` resolves the effective theme for the application.
+ *
+ * @example
+ * ```tsx
+ * function ThemeSwitcher() {
+ *    const {
+ *        theme,
+ *        systemTheme,
+ *        userTheme,
+ *        toggleTheme,
+ *        setUserTheme
+ *    } = usePreferredTheme();
+ *
+ *    return (
+ *        <div>
+ *            <p>Resolved: {theme}</p>
+ *            <p>System: {systemTheme}</p>
+ *            <p>User: {userTheme ?? 'system default'}</p>
+ *
+ *            <button onClick={() => toggleTheme()}>
+ *                Toggle
+ *            </button>
+ *
+ *            <button onClick={() => setUserTheme('dark')}>
+ *                Force Dark
+ *            </button>
+ *
+ *            <button onClick={() => setUserTheme(null)}>
+ *                Reset to System
+ *            </button>
+ *        </div>
+ *    );
+ * }
+ * ```
+ */
+declare function usePreferredTheme(): PreferredThemeReturn;
+//#endregion
+export { usePreferredTheme };

package/dist/usePreferredTheme.js

@@ -0,0 +1,133 @@
+import * as React from "react";
+
+//#region src/usePreferredTheme.ts
+const listeners = /* @__PURE__ */ new Set();
+function emit() {
+	listeners.forEach((listener) => listener());
+}
+let media = null;
+let mediaListenerAttached = false;
+const systemThemeStore = {
+	getServerSnapshot() {
+		return "light";
+	},
+	getSnapshot() {
+		if (typeof window === "undefined") return "light";
+		return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+	},
+	suscribe(listener) {
+		listeners.add(listener);
+		if (typeof window !== "undefined") {
+			if (!media) media = window.matchMedia("(prefers-color-scheme: dark)");
+			if (!mediaListenerAttached) {
+				media.addEventListener("change", emit);
+				mediaListenerAttached = true;
+			}
+			return () => {
+				listeners.delete(listener);
+				if (listeners.size === 0 && media && mediaListenerAttached) {
+					media.removeEventListener("change", emit);
+					mediaListenerAttached = false;
+				}
+			};
+		}
+		return () => listeners.delete(listener);
+	}
+};
+const storageKey = "preferred-theme";
+const userThemeStore = {
+	getSeverSnapshot() {
+		return null;
+	},
+	getSnapshot() {
+		if (typeof window === "undefined") return null;
+		return localStorage.getItem(storageKey) ?? null;
+	},
+	setTheme(theme) {
+		if (typeof window === "undefined") return;
+		if (theme === null) localStorage.removeItem(storageKey);
+		else localStorage.setItem(storageKey, theme);
+		emit();
+	},
+	suscribe(listener) {
+		listeners.add(listener);
+		if (typeof window !== "undefined") {
+			const onStorage = (event) => {
+				if (event.key === storageKey) emit();
+			};
+			window.addEventListener("storage", onStorage);
+			return () => {
+				listeners.delete(listener);
+				window.removeEventListener("storage", onStorage);
+			};
+		}
+		return () => listeners.delete(listener);
+	}
+};
+function updateDOMTheme(theme) {
+	if (typeof window === "undefined") return;
+	const root = document.documentElement;
+	if (theme === "dark") root.classList.add("dark");
+	else root.classList.remove("dark");
+	root.style.colorScheme = theme;
+}
+/**
+* `usePreferredTheme` resolves the effective theme for the application.
+*
+* @example
+* ```tsx
+* function ThemeSwitcher() {
+*    const {
+*        theme,
+*        systemTheme,
+*        userTheme,
+*        toggleTheme,
+*        setUserTheme
+*    } = usePreferredTheme();
+*
+*    return (
+*        <div>
+*            <p>Resolved: {theme}</p>
+*            <p>System: {systemTheme}</p>
+*            <p>User: {userTheme ?? 'system default'}</p>
+*
+*            <button onClick={() => toggleTheme()}>
+*                Toggle
+*            </button>
+*
+*            <button onClick={() => setUserTheme('dark')}>
+*                Force Dark
+*            </button>
+*
+*            <button onClick={() => setUserTheme(null)}>
+*                Reset to System
+*            </button>
+*        </div>
+*    );
+* }
+* ```
+*/
+function usePreferredTheme() {
+	const systemTheme = React.useSyncExternalStore(systemThemeStore.suscribe, systemThemeStore.getSnapshot, systemThemeStore.getServerSnapshot);
+	const userTheme = React.useSyncExternalStore(userThemeStore.suscribe, userThemeStore.getSnapshot, userThemeStore.getSeverSnapshot);
+	const resolved = userTheme ?? systemTheme ?? "light";
+	React.useEffect(() => {
+		updateDOMTheme(resolved);
+	}, [resolved]);
+	const toggleTheme = React.useCallback((options) => {
+		const light = options?.light ?? "light";
+		const dark = options?.dark ?? "dark";
+		const next = resolved === "dark" ? light : dark;
+		userThemeStore.setTheme(next);
+	}, [resolved]);
+	return {
+		setUserTheme: userThemeStore.setTheme,
+		systemTheme,
+		theme: resolved,
+		toggleTheme,
+		userTheme: userTheme ?? null
+	};
+}
+
+//#endregion
+export { usePreferredTheme };

package/dist/usePreviousDistinct.d.ts

@@ -0,0 +1,12 @@
+//#region src/usePreviousDistinct.d.ts
+/**
+ * `usePreviousDistinct` is a React hook that returns the previous value of a state variable, but only if it is different from the current value.
+ *
+ * @example
+ * ```tsx
+ * const prevUserId = usePreviousDistinct(userId);
+ * ```
+ */
+declare function usePreviousDistinct<T>(value: T): T | undefined;
+//#endregion
+export { usePreviousDistinct };

package/dist/usePreviousDistinct.js

@@ -0,0 +1,23 @@
+import * as React from "react";
+
+//#region src/usePreviousDistinct.ts
+/**
+* `usePreviousDistinct` is a React hook that returns the previous value of a state variable, but only if it is different from the current value.
+*
+* @example
+* ```tsx
+* const prevUserId = usePreviousDistinct(userId);
+* ```
+*/
+function usePreviousDistinct(value) {
+	const prevRef = React.useRef(void 0);
+	const currentRef = React.useRef(void 0);
+	if (!Object.is(value, currentRef.current)) {
+		prevRef.current = currentRef.current;
+		currentRef.current = value;
+	}
+	return prevRef.current;
+}
+
+//#endregion
+export { usePreviousDistinct };

package/dist/useResettableState.d.ts

@@ -0,0 +1,15 @@
+import * as React from "react";
+
+//#region src/useResettableState.d.ts
+
+/**
+ * `useResettableState` is a React state hook with an explicit reset mechanism.
+ *
+ * @example
+ * ```tsx
+ * const [count, setCount, reset] = useResettableState(0);
+ * ```
+ */
+declare function useResettableState<T>(initialState: T | (() => T)): readonly [T, React.Dispatch<React.SetStateAction<T>>, () => void];
+//#endregion
+export { useResettableState };

package/dist/useResettableState.js

@@ -0,0 +1,25 @@
+import * as React from "react";
+
+//#region src/useResettableState.ts
+/**
+* `useResettableState` is a React state hook with an explicit reset mechanism.
+*
+* @example
+* ```tsx
+* const [count, setCount, reset] = useResettableState(0);
+* ```
+*/
+function useResettableState(initialState) {
+	const initialRef = React.useRef(initialState instanceof Function ? initialState() : initialState);
+	const [state, setState] = React.useState(initialState);
+	return [
+		state,
+		setState,
+		React.useCallback(() => {
+			setState(typeof initialRef.current === "function" ? initialRef.current() : initialRef.current);
+		}, [])
+	];
+}
+
+//#endregion
+export { useResettableState };

package/dist/useScreenOrientation.d.ts

@@ -0,0 +1,48 @@
+//#region src/useScreenOrientation.d.ts
+declare global {
+  interface ScreenOrientation {
+    lock(orientation: ScreenOrientationLock): Promise<void>;
+    unlock(): void;
+  }
+  type ScreenOrientationLock = 'any' | 'natural' | 'portrait' | 'landscape' | 'portrait-primary' | 'portrait-secondary' | 'landscape-primary' | 'landscape-secondary';
+}
+type OrientationType = 'portrait-primary' | 'portrait-secondary' | 'landscape-primary' | 'landscape-secondary';
+interface UseScreenOrientationReturn {
+  /**
+   * Current orientation angle in degrees.
+   */
+  angle: number | null;
+  /**
+   * Whether the Screen Orientation API is supported.
+   */
+  isSupported: boolean;
+  /**
+   * Locks the screen orientation.
+   */
+  lock: (orientation: ScreenOrientationLock) => Promise<void>;
+  /**
+   * Current orientation type (e.g. portrait-primary).
+   */
+  type: OrientationType | null;
+  /**
+   * Unlocks the screen orientation.
+   */
+  unlock: () => void;
+}
+/**
+ * `useScreenOrientation` provides unopinionated access to the Screen Orientation API.
+ * It exposes current orientation state and helpers to lock/unlock orientation without imposing UI decisiones.
+ *
+ * @example
+ * ```tsx
+ * const orientation = useScreenOrientation();
+ *
+ * if (orientation.type === 'landscape-primary') {
+ *   // adapt layout
+ * }
+ * ```
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Screen_Orientation_API
+ */
+declare function useScreenOrientation(): UseScreenOrientationReturn;
+//#endregion
+export { useScreenOrientation };

package/dist/useScreenOrientation.js

@@ -0,0 +1,51 @@
+import * as React from "react";
+
+//#region src/useScreenOrientation.ts
+/**
+* `useScreenOrientation` provides unopinionated access to the Screen Orientation API.
+* It exposes current orientation state and helpers to lock/unlock orientation without imposing UI decisiones.
+*
+* @example
+* ```tsx
+* const orientation = useScreenOrientation();
+*
+* if (orientation.type === 'landscape-primary') {
+*   // adapt layout
+* }
+* ```
+* @see https://developer.mozilla.org/en-US/docs/Web/API/Screen_Orientation_API
+*/
+function useScreenOrientation() {
+	const isSupported = typeof screen !== "undefined" && screen.orientation !== void 0;
+	const [type, setType] = React.useState(isSupported ? screen.orientation.type : null);
+	const [angle, setAngle] = React.useState(isSupported ? screen.orientation.angle : null);
+	const lock = React.useCallback(async (orientation) => {
+		if (!isSupported) return;
+		await screen.orientation.lock(orientation);
+	}, [isSupported]);
+	const unlock = React.useCallback(() => {
+		if (!isSupported) return;
+		screen.orientation.unlock();
+	}, [isSupported]);
+	React.useEffect(() => {
+		if (!isSupported) return;
+		const handleChange = () => {
+			setType(screen.orientation.type);
+			setAngle(screen.orientation.angle);
+		};
+		screen.orientation.addEventListener("change", handleChange);
+		return () => {
+			screen.orientation.removeEventListener("change", handleChange);
+		};
+	}, [isSupported]);
+	return {
+		angle,
+		isSupported,
+		lock,
+		type,
+		unlock
+	};
+}
+
+//#endregion
+export { useScreenOrientation };

package/dist/useScreenSize.d.ts

@@ -0,0 +1,16 @@
+//#region src/useScreenSize.d.ts
+interface ScreenSizeReturn {
+  height: number;
+  width: number;
+}
+/**
+ * `useScreenSize` returns the current screen size.
+ *
+ * @example
+ * ```tsx
+ * const { width, height } = useScreenSize();
+ * ```
+ */
+declare function useScreenSize(): ScreenSizeReturn;
+//#endregion
+export { useScreenSize };

package/dist/useScreenSize.js

@@ -0,0 +1,34 @@
+import * as React from "react";
+
+//#region src/useScreenSize.ts
+/**
+* `useScreenSize` returns the current screen size.
+*
+* @example
+* ```tsx
+* const { width, height } = useScreenSize();
+* ```
+*/
+function useScreenSize() {
+	const [size, setSize] = React.useState({
+		height: 0,
+		width: 0
+	});
+	React.useEffect(() => {
+		const handleResize = () => {
+			setSize({
+				height: window.innerHeight,
+				width: window.innerWidth
+			});
+		};
+		handleResize();
+		window.addEventListener("resize", handleResize);
+		return () => {
+			window.removeEventListener("resize", handleResize);
+		};
+	}, []);
+	return size;
+}
+
+//#endregion
+export { useScreenSize };

package/dist/useScreenWakeLock.d.ts

@@ -0,0 +1,37 @@
+//#region src/useScreenWakeLock.d.ts
+interface UseScreenWakeLockReturn {
+  /**
+   * Whether the wake lock is currently active.
+   */
+  isActive: boolean;
+  /**
+   * Whether the Wake Lock API is supported.
+   */
+  isSupported: boolean;
+  /**
+   * Releases the wake lock.
+   */
+  release: () => Promise<void>;
+  /**
+   * Requests a screen wake lock.
+   */
+  request: () => Promise<void>;
+}
+/**
+ * `useScreenWakeLock` provides unopinionated access to the Screen Wake Lock Web API.
+ * It allows consumers to request and release a screen wake lock without imposing lifecycle or UI behavior.
+ *
+ * @example
+ * ```tsx
+ * const wakeLock = useScreenWakeLock();
+ *
+ * useEffect(() => {
+ *   wakeLock.request();
+ *   return () => wakeLock.release();
+ * }, []);
+ * ```
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Screen_Wake_Lock_API
+ */
+declare function useScreenWakeLock(): UseScreenWakeLockReturn;
+//#endregion
+export { useScreenWakeLock };

package/dist/useScreenWakeLock.js

@@ -0,0 +1,48 @@
+import * as React from "react";
+
+//#region src/useScreenWakeLock.ts
+/**
+* `useScreenWakeLock` provides unopinionated access to the Screen Wake Lock Web API.
+* It allows consumers to request and release a screen wake lock without imposing lifecycle or UI behavior.
+*
+* @example
+* ```tsx
+* const wakeLock = useScreenWakeLock();
+*
+* useEffect(() => {
+*   wakeLock.request();
+*   return () => wakeLock.release();
+* }, []);
+* ```
+* @see https://developer.mozilla.org/en-US/docs/Web/API/Screen_Wake_Lock_API
+*/
+function useScreenWakeLock() {
+	const isSupported = typeof navigator !== "undefined" && "wakeLock" in navigator;
+	const lockRef = React.useRef(null);
+	const [isActive, setIsActive] = React.useState(false);
+	const request = React.useCallback(async () => {
+		if (!isSupported || lockRef.current) return;
+		try {
+			lockRef.current = await navigator.wakeLock.request("screen");
+			setIsActive(true);
+			lockRef.current.addEventListener("release", () => {
+				lockRef.current = null;
+				setIsActive(false);
+			});
+		} catch {}
+	}, [isSupported]);
+	return {
+		isActive,
+		isSupported,
+		release: React.useCallback(async () => {
+			if (!lockRef.current) return;
+			await lockRef.current.release();
+			lockRef.current = null;
+			setIsActive(false);
+		}, []),
+		request
+	};
+}
+
+//#endregion
+export { useScreenWakeLock };