@vibehooks/react 0.0.1

package/dist/useNetworkInformation.d.ts

@@ -0,0 +1,138 @@
+//#region src/useNetworkInformation.d.ts
+interface NetworkInformation extends EventTarget {
+  /**
+   * Estimated effective bandwidth of the user's connection, in megabits per second (Mb/s).
+   *
+   * This value is a browser-provided heuristic based on recently observed network performance.
+   * It does NOT represent the user's contracted bandwidth nor a speed-test result.
+   *
+   * ### Practical interpretation (approximate)
+   * - < 1 Mb/s   → very slow connection (avoid heavy assets)
+   * - 1 – 3 Mb/s → slow connection
+   * - 3 – 10 Mb/s → moderate connection
+   * - > 10 Mb/s  → fast connection
+   *
+   * ### Recommended usage
+   * - Adapt image quality and media bitrates.
+   * - Reduce prefetching and background requests on low values.
+   *
+   * ### Notes
+   * - The value may fluctuate over time.
+   * - Not available in all browsers.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/downlink
+   */
+  readonly downlink?: number | undefined;
+  /**
+   * Maximum theoretical bandwidth of the underlying network link, in megabits per second (Mb/s).
+   *
+   * This represents the estimated capacity of the physical or logical connection
+   * (e.g., Wi-Fi, Ethernet), not the observed throughput.
+   *
+   * ### Typical values
+   * - Cellular networks → low to moderate
+   * - Wi-Fi / Ethernet → high or Infinity
+   *
+   * ### Recommended usage
+   * - Decide whether large downloads are feasible.
+   * - Compare against `downlink` to detect congestion.
+   *
+   * ### Notes
+   * - Often undefined or `Infinity`.
+   * - Not consistently implemented across browsers.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/downlinkMax
+   */
+  readonly downlinkMax?: number | undefined;
+  readonly effectiveType?: 'slow-2g' | '2g' | '3g' | '4g' | undefined;
+  /**
+   * Estimated round-trip time (RTT), in milliseconds (ms).
+   *
+   * RTT measures the time it takes for a network request to travel from the client
+   * to the server and back.
+   *
+   * ### Practical interpretation (approximate)
+   * - < 50 ms   → excellent latency
+   * - 50 – 150 ms → acceptable
+   * - 150 – 300 ms → noticeable latency
+   * - > 300 ms → high latency (degraded real-time UX)
+   *
+   * ### Recommended usage
+   * - Tune request timeouts.
+   * - Decide between polling vs real-time transports.
+   * - Disable latency-sensitive features on high RTT.
+   *
+   * ### Notes
+   * - Values are estimates, not precise measurements.
+   * - RTT may vary significantly on mobile networks.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/rtt
+   */
+  readonly rtt?: number | undefined;
+  /**
+   * Indicates whether the user has enabled a reduced data usage mode (Data Saver).
+   *
+   * This is an explicit user preference, not a performance metric.
+   * When `true`, the user is signaling intent to minimize network usage.
+   *
+   * ### Recommended behavior when enabled
+   * - Serve lower-resolution images.
+   * - Disable autoplay media.
+   * - Avoid aggressive prefetching.
+   * - Reduce background network activity.
+   *
+   * ### Priority rule
+   * `saveData === true` SHOULD override optimistic decisions based on
+   * `downlink` or `downlinkMax`.
+   *
+   * ### Notes
+   * - Availability depends on browser and OS.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/saveData
+   */
+  readonly saveData?: boolean | undefined;
+  readonly type?: 'bluetooth' | 'cellular' | 'ethernet' | 'node' | 'wifi' | 'wimax' | 'other' | 'unknown' | undefined;
+}
+declare global {
+  interface Navigator {
+    connection: NetworkInformation;
+    mozConnection: NetworkInformation;
+    webkitConnection: NetworkInformation;
+  }
+}
+interface NetworkInformationSnapshot {
+  downlink?: NetworkInformation['downlink'];
+  downlinkMax?: NetworkInformation['downlinkMax'];
+  effectiveType?: NetworkInformation['effectiveType'];
+  rtt?: NetworkInformation['rtt'];
+  saveData?: NetworkInformation['saveData'];
+  type?: NetworkInformation['type'];
+}
+interface UseNetworkInformationReturn extends NetworkInformationSnapshot {
+  supported: boolean;
+}
+/**
+ * `useNetworkInformation` returns live network information using the Network Information API.
+ * The hook automatically updates when the underlying connection changes.
+ *
+ * @example
+ * ```tsx
+ * const network = useNetworkInformation();
+ *
+ * if (!network.supported) {
+ *   return <span>Network API not supported</span>;
+ * }
+ *
+ * return (
+ *   <div>
+ *     <p>Type: {network.type}</p>
+ *     <p>Effective type: {network.effectiveType}</p>
+ *     <p>Downlink: {network.downlink} Mb/s</p>
+ *   </div>
+ * );
+ * ```
+ * @see https://developer.mozilla.org/es/docs/Web/API/Network_Information_API
+ */
+declare function useNetworkInformation(): UseNetworkInformationReturn;
+//#endregion
+export { useNetworkInformation };

package/dist/useNetworkInformation.js

@@ -0,0 +1,76 @@
+import * as React from "react";
+
+//#region src/useNetworkInformation.ts
+const listeners = /* @__PURE__ */ new Set();
+let listening = false;
+function getConnection() {
+	if (typeof navigator === "undefined") return null;
+	return navigator.connection ?? navigator.mozConnection ?? navigator.webkitConnection ?? null;
+}
+let lastSnapshot = null;
+function getSnapshot() {
+	const connection = getConnection();
+	if (!connection) return null;
+	const nextSnapshot = {
+		downlink: connection.downlink,
+		downlinkMax: connection.downlinkMax,
+		effectiveType: connection.effectiveType,
+		rtt: connection.rtt,
+		saveData: connection.saveData,
+		type: connection.type
+	};
+	if (lastSnapshot && lastSnapshot.downlink === nextSnapshot.downlink && lastSnapshot.downlinkMax === nextSnapshot.downlinkMax && lastSnapshot.effectiveType === nextSnapshot.effectiveType && lastSnapshot.rtt === nextSnapshot.rtt && lastSnapshot.saveData === nextSnapshot.saveData && lastSnapshot.type === nextSnapshot.type) return lastSnapshot;
+	lastSnapshot = nextSnapshot;
+	return nextSnapshot;
+}
+function emit() {
+	listeners.forEach((listener) => listener());
+}
+function subscribe(listener) {
+	listeners.add(listener);
+	const connection = getConnection();
+	if (!listening && connection) {
+		connection.addEventListener("change", emit);
+		listening = true;
+	}
+	return () => {
+		listeners.delete(listener);
+		if (listeners.size === 0 && connection && listening) {
+			connection.removeEventListener("change", emit);
+			listening = false;
+		}
+	};
+}
+/**
+* `useNetworkInformation` returns live network information using the Network Information API.
+* The hook automatically updates when the underlying connection changes.
+*
+* @example
+* ```tsx
+* const network = useNetworkInformation();
+*
+* if (!network.supported) {
+*   return <span>Network API not supported</span>;
+* }
+*
+* return (
+*   <div>
+*     <p>Type: {network.type}</p>
+*     <p>Effective type: {network.effectiveType}</p>
+*     <p>Downlink: {network.downlink} Mb/s</p>
+*   </div>
+* );
+* ```
+* @see https://developer.mozilla.org/es/docs/Web/API/Network_Information_API
+*/
+function useNetworkInformation() {
+	const snapshot = React.useSyncExternalStore(subscribe, getSnapshot, () => null);
+	if (!snapshot) return { supported: false };
+	return {
+		supported: true,
+		...snapshot
+	};
+}
+
+//#endregion
+export { useNetworkInformation };

package/dist/useOnline.d.ts

@@ -0,0 +1,17 @@
+//#region src/useOnline.d.ts
+interface UseOnlineReturn {
+  /**
+   * Whether the browser is considered online.
+   * Note: `true` does not guarantee internet access.
+   */
+  online: boolean;
+}
+/**
+ * `useOnline` is an unopinionated hook that exposes the browser's online status based on the Navigator.onLine API.
+ * It automatically stays in sync with `online` and `offline` events.
+ *
+ * @see https://developer.mozilla.org/es/docs/Web/API/Navigator/onLine
+ */
+declare function useOnline(): UseOnlineReturn;
+//#endregion
+export { useOnline };

package/dist/useOnline.js

@@ -0,0 +1,29 @@
+import * as React from "react";
+
+//#region src/useOnline.ts
+function suscribe(callback) {
+	window.addEventListener("online", callback);
+	window.addEventListener("offline", callback);
+	return () => {
+		window.removeEventListener("online", callback);
+		window.removeEventListener("offline", callback);
+	};
+}
+function getSnapshot() {
+	return navigator.onLine;
+}
+function getServerSnapshot() {
+	return true;
+}
+/**
+* `useOnline` is an unopinionated hook that exposes the browser's online status based on the Navigator.onLine API.
+* It automatically stays in sync with `online` and `offline` events.
+*
+* @see https://developer.mozilla.org/es/docs/Web/API/Navigator/onLine
+*/
+function useOnline() {
+	return { online: React.useSyncExternalStore(suscribe, getSnapshot, getServerSnapshot) };
+}
+
+//#endregion
+export { useOnline };

package/dist/usePageVisibility.d.ts

@@ -0,0 +1,32 @@
+//#region src/usePageVisibility.d.ts
+interface PageVisibilityReturn {
+  /**
+   * Whether the document is currently visible.
+   */
+  isVisible: boolean;
+  /**
+   * Current visibility state of the document.
+   */
+  visibilityState: DocumentVisibilityState;
+}
+/**
+ * `usePageVisibility` is a React hook that exposes the current visibility
+ * state of the document using the Page Visibility API.
+ *
+ * @example
+ * ```tsx
+ * function PollingController() {
+ *   const { isVisible } = usePageVisibility();
+ *
+ *   React.useEffect(() => {
+ *     if (!isVisible) pausePolling();
+ *     else resumePolling();
+ *   }, [isVisible]);
+ *
+ *   return null;s
+ * }
+ * ```
+ */
+declare function usePageVisibility(): PageVisibilityReturn;
+//#endregion
+export { usePageVisibility };

package/dist/usePageVisibility.js

@@ -0,0 +1,65 @@
+import * as React from "react";
+
+//#region src/usePageVisibility.ts
+function visibilityStore() {
+	const listeners = /* @__PURE__ */ new Set();
+	let listening = false;
+	function emit() {
+		listeners.forEach((listener) => listener());
+	}
+	function subscribe(listener) {
+		listeners.add(listener);
+		if (!listening && typeof document !== "undefined") {
+			document.addEventListener("visibilitychange", emit);
+			listening = true;
+		}
+		return () => {
+			listeners.delete(listener);
+			if (listeners.size === 0 && listening && typeof document !== "undefined") {
+				document.removeEventListener("visibilitychange", emit);
+				listening = false;
+			}
+		};
+	}
+	function getSnapshot() {
+		if (typeof document === "undefined") return "visible";
+		return document.visibilityState;
+	}
+	function getServerSnapshot() {
+		return "visible";
+	}
+	return {
+		getServerSnapshot,
+		getSnapshot,
+		subscribe
+	};
+}
+const pageVisibilityStore = visibilityStore();
+/**
+* `usePageVisibility` is a React hook that exposes the current visibility
+* state of the document using the Page Visibility API.
+*
+* @example
+* ```tsx
+* function PollingController() {
+*   const { isVisible } = usePageVisibility();
+*
+*   React.useEffect(() => {
+*     if (!isVisible) pausePolling();
+*     else resumePolling();
+*   }, [isVisible]);
+*
+*   return null;s
+* }
+* ```
+*/
+function usePageVisibility() {
+	const visibilityState = React.useSyncExternalStore(pageVisibilityStore.subscribe, pageVisibilityStore.getSnapshot, pageVisibilityStore.getServerSnapshot);
+	return {
+		isVisible: visibilityState === "visible",
+		visibilityState
+	};
+}
+
+//#endregion
+export { usePageVisibility };

package/dist/usePermissions.d.ts

@@ -0,0 +1,28 @@
+//#region src/usePermissions.d.ts
+type PermissionState = 'granted' | 'denied' | 'prompt';
+type PermissionsSnapshot = Partial<Record<PermissionName, PermissionState>>;
+interface UsePermissionReturn {
+  isSupported: boolean;
+  permissions: PermissionsSnapshot;
+}
+/**
+ * `usePermissions` is a React hook unopinionated to observe in real-time the permission status of browser using the Permissions API.
+ * This hook does not manage permissions, it only observes them.
+ *
+ * @example
+ * ```tsx
+ * const { permissions, isSupported } = usePermissions([
+ *   'camera',
+ *   'microphone',
+ *   'geolocation'
+ * ]);
+ *
+ * if (permissions.camera === 'denied') {
+ *   // Show a message to the user
+ * }
+ * ```
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API
+ */
+declare function usePermissions<T extends readonly PermissionName[]>(permissionNames: T): UsePermissionReturn;
+//#endregion
+export { usePermissions };

package/dist/usePermissions.js

@@ -0,0 +1,70 @@
+import * as React from "react";
+
+//#region src/usePermissions.ts
+/**
+* `usePermissions` is a React hook unopinionated to observe in real-time the permission status of browser using the Permissions API.
+* This hook does not manage permissions, it only observes them.
+*
+* @example
+* ```tsx
+* const { permissions, isSupported } = usePermissions([
+*   'camera',
+*   'microphone',
+*   'geolocation'
+* ]);
+*
+* if (permissions.camera === 'denied') {
+*   // Show a message to the user
+* }
+* ```
+* @see https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API
+*/
+function usePermissions(permissionNames) {
+	const isSupported = typeof window !== "undefined" && typeof navigator !== "undefined" && "permissions" in navigator;
+	const [permissions, setPermissions] = React.useState({});
+	const statusRef = React.useRef({});
+	React.useEffect(() => {
+		if (!isSupported) return;
+		let cancelled = false;
+		const cleanups = [];
+		const setupPermission = async (name) => {
+			try {
+				const status = await navigator.permissions.query({ name });
+				if (cancelled) return;
+				statusRef.current[name] = status;
+				setPermissions((prev) => {
+					if (prev[name] === status.state) return prev;
+					return {
+						...prev,
+						[name]: status.state
+					};
+				});
+				const handleChange = () => {
+					setPermissions((prev) => {
+						if (prev[name] === status.state) return prev;
+						return {
+							...prev,
+							[name]: status.state
+						};
+					});
+				};
+				status.addEventListener("change", handleChange);
+				cleanups.push(() => {
+					status.removeEventListener("change", handleChange);
+				});
+			} catch {}
+		};
+		for (const name of permissionNames) setupPermission(name);
+		return () => {
+			cancelled = true;
+			cleanups.forEach((fn) => fn());
+		};
+	}, [isSupported, permissionNames]);
+	return {
+		isSupported,
+		permissions
+	};
+}
+
+//#endregion
+export { usePermissions };

package/dist/usePictureInPicture.d.ts

@@ -0,0 +1,47 @@
+import * as React from "react";
+
+//#region src/usePictureInPicture.d.ts
+interface UsePictureInPictureReturn {
+  /**
+   * Requests Picture-in-Picture for the attached video element.
+   */
+  enter: () => Promise<void>;
+  /**
+   * Exits Picture-in-Picture mode if active.
+   */
+  exit: () => Promise<void>;
+  /**
+   * Whether the video is currently in Picture-in-Picture mode.
+   */
+  isActive: boolean;
+  /**
+   * Whether Picture-in-Picture is supported by the browser.
+   */
+  isSupported: boolean;
+  /**
+   * Ref to the HTMLVideoElement.
+   */
+  videoRef: React.RefObject<HTMLVideoElement | null>;
+}
+/**
+ * `usePictureInPicture` provides unopinionated access to the Picture-in-Picture Web API for HTMLVideoElement.
+ * It manages PiP lifecycle and state but leaves UI and UX decisions to the consumer.
+ *
+ * @example
+ * ```tsx
+ * const pip = usePictureInPicture();
+ *
+ * return (
+ *   <>
+ *     <video ref={pip.videoRef} src="/video.mp4" controls />
+ *     <button onClick={pip.enter} disabled={!pip.isSupported}>
+ *       PiP
+ *     </button>
+ *   </>
+ * );
+ * ```
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Picture-in-Picture_API
+ */
+declare function usePictureInPicture(): UsePictureInPictureReturn;
+//#endregion
+export { usePictureInPicture };

package/dist/usePictureInPicture.js

@@ -0,0 +1,60 @@
+import * as React from "react";
+
+//#region src/usePictureInPicture.ts
+/**
+* `usePictureInPicture` provides unopinionated access to the Picture-in-Picture Web API for HTMLVideoElement.
+* It manages PiP lifecycle and state but leaves UI and UX decisions to the consumer.
+*
+* @example
+* ```tsx
+* const pip = usePictureInPicture();
+*
+* return (
+*   <>
+*     <video ref={pip.videoRef} src="/video.mp4" controls />
+*     <button onClick={pip.enter} disabled={!pip.isSupported}>
+*       PiP
+*     </button>
+*   </>
+* );
+* ```
+* @see https://developer.mozilla.org/en-US/docs/Web/API/Picture-in-Picture_API
+*/
+function usePictureInPicture() {
+	const videoRef = React.useRef(null);
+	const [isActive, setIsActive] = React.useState(false);
+	const isSupported = typeof document !== "undefined" && "pictureInPictureEnabled" in document;
+	const enter = React.useCallback(async () => {
+		if (!isSupported) return;
+		const video = videoRef.current;
+		if (!video) return;
+		if (document.pictureInPictureElement) return;
+		await video.requestPictureInPicture();
+	}, [isSupported]);
+	const exit = React.useCallback(async () => {
+		if (!isSupported) return;
+		if (!document.pictureInPictureElement) return;
+		await document.exitPictureInPicture();
+	}, [isSupported]);
+	React.useEffect(() => {
+		if (!isSupported) return;
+		const onEnter = () => setIsActive(true);
+		const onExit = () => setIsActive(false);
+		document.addEventListener("enterpictureinpicture", onEnter);
+		document.addEventListener("leavepictureinpicture", onExit);
+		return () => {
+			document.removeEventListener("enterpictureinpicture", onEnter);
+			document.removeEventListener("leavepictureinpicture", onExit);
+		};
+	}, [isSupported]);
+	return {
+		enter,
+		exit,
+		isActive,
+		isSupported,
+		videoRef
+	};
+}
+
+//#endregion
+export { usePictureInPicture };

package/dist/usePopover.d.ts

@@ -0,0 +1,54 @@
+import * as React from "react";
+
+//#region src/usePopover.d.ts
+interface UsePopoverReturn<TAnchor extends HTMLElement, TPopover extends HTMLElement> {
+  /**
+   * Ref for the anchor (trigger) element.
+   */
+  anchorRef: React.RefObject<TAnchor | null>;
+  /**
+   * Closes the popover.
+   */
+  close: () => void;
+  /**
+   * Whether the popover is open.
+   */
+  isOpen: boolean;
+  /**
+   * Opens the popover.
+   */
+  open: () => void;
+  /**
+   * Ref for the popover element.
+   */
+  popoverRef: React.RefObject<TPopover | null>;
+  /**
+   * Toggles the popover.
+   */
+  toggle: () => void;
+}
+/**
+ * `usePopover` is React hook that manages the open/close state and lifecycle of a popover anchored to a trigger element.
+ *
+ * @example
+ * ```tsx
+ *  const popover = usePopover();
+ *
+ * return (
+ *   <>
+ *     <button ref={popover.anchorRef} onClick={popover.toggle}>
+ *       Open
+ *     </button>
+ *
+ *     {popover.isOpen && (
+ *       <div ref={popover.popoverRef}>
+ *         Content
+ *       </div>
+ *     )}
+ *   </>
+ * );
+ * ```
+ */
+declare function usePopover<TAnchor extends HTMLElement = HTMLElement, TPopover extends HTMLElement = HTMLElement>(): UsePopoverReturn<TAnchor, TPopover>;
+//#endregion
+export { usePopover };

package/dist/usePopover.js

@@ -0,0 +1,67 @@
+import * as React from "react";
+
+//#region src/usePopover.ts
+/**
+* `usePopover` is React hook that manages the open/close state and lifecycle of a popover anchored to a trigger element.
+*
+* @example
+* ```tsx
+*  const popover = usePopover();
+*
+* return (
+*   <>
+*     <button ref={popover.anchorRef} onClick={popover.toggle}>
+*       Open
+*     </button>
+*
+*     {popover.isOpen && (
+*       <div ref={popover.popoverRef}>
+*         Content
+*       </div>
+*     )}
+*   </>
+* );
+* ```
+*/
+function usePopover() {
+	const [isOpen, setIsOpen] = React.useState(false);
+	const anchorRef = React.useRef(null);
+	const popoverRef = React.useRef(null);
+	const open = React.useCallback(() => {
+		setIsOpen(true);
+	}, []);
+	const close = React.useCallback(() => {
+		setIsOpen(false);
+	}, []);
+	const toggle = React.useCallback(() => {
+		setIsOpen((isOpen$1) => !isOpen$1);
+	}, []);
+	React.useEffect(() => {
+		if (!isOpen) return;
+		const onClickOutside = (event) => {
+			const target = event.target;
+			if (popoverRef.current?.contains(target) || anchorRef.current?.contains(target)) return;
+			close();
+		};
+		const onKeyDown = (event) => {
+			if (event.key === "Escape") close();
+		};
+		document.addEventListener("mousedown", onClickOutside);
+		document.addEventListener("keydown", onKeyDown);
+		return () => {
+			document.removeEventListener("mousedown", onClickOutside);
+			document.removeEventListener("keydown", onKeyDown);
+		};
+	}, [isOpen, close]);
+	return {
+		anchorRef,
+		close,
+		isOpen,
+		open,
+		popoverRef,
+		toggle
+	};
+}
+
+//#endregion
+export { usePopover };