@vibehooks/react 0.0.1

package/dist/useFile.d.ts

@@ -0,0 +1,74 @@
+import * as React from "react";
+
+//#region src/useFile.d.ts
+interface UseFileOptions {
+  /**
+   * Accepted file types (input accept attribute)
+   * Example: 'image/*', '.pdf'
+   */
+  accept?: string;
+  /**
+   * Whether the file input should be disabled
+   */
+  disabled?: boolean;
+  /**
+   * Allow selecting multiple files
+   */
+  multiple?: boolean;
+}
+interface UseFileReturn {
+  /**
+   * Currently selected files.
+   */
+  files: File[];
+  /**
+   * Whether at least one file is selected.
+   */
+  hasFiles: boolean;
+  /**
+   * Props to spread into an <input type="file" /> element.
+   */
+  inputProps: React.InputHTMLAttributes<HTMLInputElement>;
+  /**
+   * Clears the selected files.
+   */
+  reset: () => void;
+  /**
+   * Manually sets files (useful for drag & drop).
+   */
+  setFiles: (files: File[] | FileList) => void;
+}
+/**
+ * `useFile` is a React hook that manages file selection and access in an unopinionated and transport-agnostic way.
+ * This hook does not upload files, validate contents, or trigger side effects.
+ *
+ * @example
+ * ```tsx
+ * const file = useFile({ accept: 'image/*', multiple: true });
+ *
+ * return (
+ *   <>
+ *     <input {...file.inputProps} />
+ *     {file.files.map((f) => (
+ *       <p key={f.name}>{f.name}</p>
+ *     ))}
+ *   </>
+ * );
+ *
+ * `Use tipically with a button to trigger the file selection`
+ * <input {...file.inputProps} />;
+ * <button onClick={() => upload(file.files)}>
+ *   Upload
+ * </button>
+ *
+ * `Use with Drag & Drop`
+ * const file = useFile({ multiple: true });
+ * const onDrop = (e: React.DragEvent) => {
+ *   e.preventDefault();
+ * file.setFiles(e.dataTransfer.files);
+ * };
+ * ```
+ */
+declare function useFile(options?: UseFileOptions): UseFileReturn;
+//#endregion
+export { useFile };

package/dist/useFile.js

@@ -0,0 +1,74 @@
+import * as React from "react";
+
+//#region src/useFile.ts
+/**
+* `useFile` is a React hook that manages file selection and access in an unopinionated and transport-agnostic way.
+* This hook does not upload files, validate contents, or trigger side effects.
+*
+* @example
+* ```tsx
+* const file = useFile({ accept: 'image/*', multiple: true });
+*
+* return (
+*   <>
+*     <input {...file.inputProps} />
+*     {file.files.map((f) => (
+*       <p key={f.name}>{f.name}</p>
+*     ))}
+*   </>
+* );
+*
+* `Use tipically with a button to trigger the file selection`
+* <input {...file.inputProps} />;
+* <button onClick={() => upload(file.files)}>
+*   Upload
+* </button>
+*
+* `Use with Drag & Drop`
+* const file = useFile({ multiple: true });
+* const onDrop = (e: React.DragEvent) => {
+*   e.preventDefault();
+* file.setFiles(e.dataTransfer.files);
+* };
+* ```
+*/
+function useFile(options = {}) {
+	const { accept, disabled, multiple = false } = options;
+	const [files, setInternalFiles] = React.useState([]);
+	const inputRef = React.useRef(null);
+	const setFiles = React.useCallback((input) => {
+		const next = Array.from(input);
+		setInternalFiles(multiple ? next : next.slice(0, 1));
+	}, [multiple]);
+	const reset = React.useCallback(() => {
+		setInternalFiles([]);
+		if (inputRef.current) inputRef.current.value = "";
+	}, []);
+	const onChange = React.useCallback((event) => {
+		if (!event.target.files) return;
+		setFiles(event.target.files);
+	}, [setFiles]);
+	const inputProps = React.useMemo(() => ({
+		accept,
+		disabled,
+		multiple,
+		onChange,
+		ref: inputRef,
+		type: "file"
+	}), [
+		accept,
+		multiple,
+		disabled,
+		onChange
+	]);
+	return {
+		files,
+		hasFiles: files.length > 0,
+		inputProps,
+		reset,
+		setFiles
+	};
+}
+
+//#endregion
+export { useFile };

package/dist/useFullScreen.d.ts

@@ -0,0 +1,20 @@
+import * as React from "react";
+
+//#region src/useFullScreen.d.ts
+interface FullScreenReturn {
+  enter: () => Promise<void>;
+  exit: () => Promise<void>;
+  isFullscreen: boolean;
+  toggle: () => Promise<void>;
+}
+/**
+ * `useFullScreen` controls the browser Fullscreen API.
+ *
+ * @example
+ * ```tsx
+ * const { isFullscreen, enter, exit, toggle } = useFullscreen<HTMLDivElement>(ref);
+ * ```
+ */
+declare function useFullscreen<T extends HTMLElement>(ref: React.RefObject<T | null>): FullScreenReturn;
+//#endregion
+export { useFullscreen };

package/dist/useFullScreen.js

@@ -0,0 +1,43 @@
+import * as React from "react";
+
+//#region src/useFullScreen.ts
+/**
+* `useFullScreen` controls the browser Fullscreen API.
+*
+* @example
+* ```tsx
+* const { isFullscreen, enter, exit, toggle } = useFullscreen<HTMLDivElement>(ref);
+* ```
+*/
+function useFullscreen(ref) {
+	const [isFullscreen, setIsFullscreen] = React.useState(false);
+	const enter = React.useCallback(async () => {
+		if (!ref.current) return;
+		if (document.fullscreenElement) return;
+		await ref.current.requestFullscreen();
+	}, []);
+	const exit = React.useCallback(async () => {
+		if (!document.fullscreenElement) return;
+		await document.exitFullscreen();
+	}, []);
+	const toggle = React.useCallback(async () => {
+		if (document.fullscreenElement) await exit();
+		else await enter();
+	}, [enter, exit]);
+	React.useEffect(() => {
+		const handleChange = () => {
+			setIsFullscreen(Boolean(document.fullscreenElement));
+		};
+		document.addEventListener("fullscreenchange", handleChange);
+		return () => document.removeEventListener("fullscreenchange", handleChange);
+	}, []);
+	return {
+		enter,
+		exit,
+		isFullscreen,
+		toggle
+	};
+}
+
+//#endregion
+export { useFullscreen };

package/dist/useGeolocation.d.ts

@@ -0,0 +1,47 @@
+//#region src/useGeolocation.d.ts
+type GeolocationPermissionState = PermissionState | 'unsupported';
+interface UseGeolocationReturn {
+  /**
+   * Clears a watcher.
+   */
+  clearWatch: (watcherId: number) => void;
+  /**
+   * Latest geolocation error.
+   */
+  error: GeolocationPositionError | null;
+  /**
+   * Requests the current position once.
+   */
+  getCurrentPosition: (options?: PositionOptions) => void;
+  /**
+   * Indicates whether the Geolocation API is supported.
+   */
+  isSupported: boolean;
+  /**
+   * Current permission state for geolocation.
+   * - 'granted'
+   * - 'denied'
+   * - 'prompt'
+   * - 'unsupported' (Permissions API not available)
+   */
+  permissionState: GeolocationPermissionState;
+  /**
+   * Latest known position.
+   */
+  position: GeolocationPosition | null;
+  /**
+   * Starts watching position changes.
+   */
+  watchPosition: (options?: PositionOptions) => number | null;
+}
+/**
+ * `useGeolocation` is a React hook to safely access the Geolocation API in an unopinionated and SSR-safe manner.
+ *
+ * @example
+ * ```tsx
+ * const { clearWatch, error, getCurrentPosition, isSupported, permissionState, position, watchPosition } = useGeolocation();
+ * ```
+ */
+declare function useGeolocation(): UseGeolocationReturn;
+//#endregion
+export { useGeolocation };

package/dist/useGeolocation.js

@@ -0,0 +1,68 @@
+import * as React from "react";
+
+//#region src/useGeolocation.ts
+/**
+* `useGeolocation` is a React hook to safely access the Geolocation API in an unopinionated and SSR-safe manner.
+*
+* @example
+* ```tsx
+* const { clearWatch, error, getCurrentPosition, isSupported, permissionState, position, watchPosition } = useGeolocation();
+* ```
+*/
+function useGeolocation() {
+	const isClient = typeof window !== "undefined" && typeof navigator !== "undefined";
+	const isSupported = isClient && "geolocation" in navigator;
+	const [position, setPosition] = React.useState(null);
+	const [error, setError] = React.useState(null);
+	const [permissionState, setPermissionState] = React.useState(isClient && "permissions" in navigator ? "prompt" : "unsupported");
+	React.useEffect(() => {
+		if (!isClient || !("permissions" in navigator) || !isSupported) return;
+		let status = null;
+		navigator.permissions.query({ name: "geolocation" }).then((permissionStatus) => {
+			status = permissionStatus;
+			setPermissionState(permissionStatus.state);
+			permissionStatus.onchange = () => {
+				setPermissionState(permissionStatus.state);
+			};
+		}).catch(() => {
+			setPermissionState("unsupported");
+		});
+		return () => {
+			if (status) status.onchange = null;
+		};
+	}, [isClient, isSupported]);
+	const getCurrentPosition = React.useCallback((options) => {
+		if (!isSupported) return;
+		navigator.geolocation.getCurrentPosition((position$1) => {
+			setPosition(position$1);
+			setError(null);
+		}, (err) => {
+			setError(err);
+			setPosition(null);
+		}, options);
+	}, [isSupported]);
+	const watchPosition = React.useCallback((options) => {
+		if (!isSupported) return null;
+		return navigator.geolocation.watchPosition((pos) => {
+			setPosition(pos);
+			setError(null);
+		}, (err) => {
+			setError(err);
+		}, options);
+	}, [isSupported]);
+	return {
+		clearWatch: React.useCallback((watcherId) => {
+			if (!isSupported) return;
+			navigator.geolocation.clearWatch(watcherId);
+		}, [isSupported]),
+		error,
+		getCurrentPosition,
+		isSupported,
+		permissionState,
+		position,
+		watchPosition
+	};
+}
+
+//#endregion
+export { useGeolocation };

package/dist/useHoverIntent.d.ts

@@ -0,0 +1,45 @@
+import * as React from "react";
+
+//#region src/useHoverIntent.d.ts
+interface UseHoverIntentOptions {
+  /**
+   * Delay (ms) before considering hover as intentional.
+   */
+  delay?: number;
+  /**
+   * Pixel movement tolerance before canceling intent.
+   */
+  tolerance?: number;
+}
+interface UseHoverIntentReturn {
+  /**
+   * Event handlers to spread on the target element.
+   */
+  handlers: {
+    onMouseEnter?: React.MouseEventHandler;
+    onMouseLeave?: React.MouseEventHandler;
+    onMouseMove?: React.MouseEventHandler;
+  };
+  /**
+   * Whether the hover is considered intentional.
+   */
+  isIntent: boolean;
+}
+/**
+ * `useHoverIntent` detects whether a mouse hover is intentional by observing pointer movement and time spent over an element.
+ * It is useful for preventing accidental hover interactions.
+ *
+ * @example
+ * ```tsx
+ * const hover = useHoverIntent({ delay: 150, tolerance: 8 });
+ *
+ * return (
+ *   <div {...hover.handlers}>
+ *     {hover.isIntent && <Tooltip />}
+ *   </div>
+ * );
+ * ```
+ */
+declare function useHoverIntent(options?: UseHoverIntentOptions): UseHoverIntentReturn;
+//#endregion
+export { useHoverIntent };

package/dist/useHoverIntent.js

@@ -0,0 +1,81 @@
+import * as React from "react";
+
+//#region src/useHoverIntent.ts
+/**
+* `useHoverIntent` detects whether a mouse hover is intentional by observing pointer movement and time spent over an element.
+* It is useful for preventing accidental hover interactions.
+*
+* @example
+* ```tsx
+* const hover = useHoverIntent({ delay: 150, tolerance: 8 });
+*
+* return (
+*   <div {...hover.handlers}>
+*     {hover.isIntent && <Tooltip />}
+*   </div>
+* );
+* ```
+*/
+function useHoverIntent(options = {}) {
+	const { delay = 100, tolerance = 6 } = options;
+	const [isIntent, setIsIntent] = React.useState(false);
+	const timeoutRef = React.useRef(null);
+	const lastPointRef = React.useRef(null);
+	const clear = React.useCallback(() => {
+		if (timeoutRef.current !== null) {
+			window.clearTimeout(timeoutRef.current);
+			timeoutRef.current = null;
+		}
+	}, []);
+	const onMouseEnter = React.useCallback((event) => {
+		lastPointRef.current = {
+			x: event.clientX,
+			y: event.clientY
+		};
+		clear();
+		timeoutRef.current = window.setTimeout(() => {
+			setIsIntent(true);
+		}, delay);
+	}, [delay, clear]);
+	const onMouseMove = React.useCallback((event) => {
+		if (!lastPointRef.current) return;
+		const dx = Math.abs(event.clientX - lastPointRef.current.x);
+		const dy = Math.abs(event.clientY - lastPointRef.current.y);
+		if (dx > tolerance || dy > tolerance) {
+			clear();
+			setIsIntent(false);
+			timeoutRef.current = window.setTimeout(() => {
+				setIsIntent(true);
+			}, delay);
+			lastPointRef.current = {
+				x: event.clientX,
+				y: event.clientY
+			};
+		}
+	}, [
+		tolerance,
+		clear,
+		delay
+	]);
+	const onMouseLeave = React.useCallback(() => {
+		clear();
+		lastPointRef.current = null;
+		setIsIntent(false);
+	}, [clear]);
+	React.useEffect(() => {
+		return () => {
+			clear();
+		};
+	}, [clear]);
+	return {
+		handlers: {
+			onMouseEnter,
+			onMouseLeave,
+			onMouseMove
+		},
+		isIntent
+	};
+}
+
+//#endregion
+export { useHoverIntent };

package/dist/useIdle.d.ts

@@ -0,0 +1,47 @@
+//#region src/useIdle.d.ts
+interface UseIdleOptions {
+  /**
+   * Events that reset the idle timer.
+   * @default ['mousemove', 'keydown', 'mousedown', 'touchstart', 'scroll']
+   */
+  events?: readonly (keyof WindowEventMap)[];
+  /**
+   * Initial idle state.
+   * Useful for SSR or background tabs.
+   * @default false
+   */
+  initialState?: boolean;
+  /**
+   * Time in milliseconds before the user is considered idle.
+   * @default 60000
+   */
+  timeout?: number;
+}
+interface UseIdleReturn {
+  /**
+   * Whether the user is currently idle.
+   */
+  isIdle: boolean;
+  /**
+   * Timestamp (ms) of the last detected user activity.
+   */
+  lastActiveAt: number;
+}
+/**
+ * `useIdle` is a React hook  to detect user inactivity.
+ * It observes user interaction events and marks the user as idle after a specified period without activity.
+ * This hook does not perform side effects (logout, pause, etc.).
+ * It only exposes idle state so the consumer can decide what to do.
+ *
+ * @example
+ * ```tsx
+ * const { isIdle } = useIdle({ timeout: 30000 });
+ *
+ * if (isIdle) {
+ *   // pause expensive work
+ * }
+ * ```
+ */
+declare function useIdle(options?: UseIdleOptions): UseIdleReturn;
+//#endregion
+export { useIdle };

package/dist/useIdle.js

@@ -0,0 +1,59 @@
+import * as React from "react";
+
+//#region src/useIdle.ts
+/**
+* `useIdle` is a React hook  to detect user inactivity.
+* It observes user interaction events and marks the user as idle after a specified period without activity.
+* This hook does not perform side effects (logout, pause, etc.).
+* It only exposes idle state so the consumer can decide what to do.
+*
+* @example
+* ```tsx
+* const { isIdle } = useIdle({ timeout: 30000 });
+*
+* if (isIdle) {
+*   // pause expensive work
+* }
+* ```
+*/
+function useIdle(options = {}) {
+	const { events = [
+		"mousemove",
+		"keydown",
+		"mousedown",
+		"touchstart",
+		"scroll"
+	], initialState = false, timeout = 6e4 } = options;
+	const isBrowser = typeof window !== "undefined";
+	const [isIdle, setIsIdle] = React.useState(initialState);
+	const lasActiveRef = React.useRef(Date.now());
+	const timeoutRef = React.useRef(null);
+	const resetTimer = React.useCallback(() => {
+		lasActiveRef.current = Date.now();
+		setIsIdle((prev) => prev ? false : prev);
+		if (timeoutRef.current !== null) window.clearTimeout(timeoutRef.current);
+		timeoutRef.current = window.setTimeout(() => {
+			setIsIdle(true);
+		}, timeout);
+	}, [timeout]);
+	React.useEffect(() => {
+		if (!isBrowser) return;
+		resetTimer();
+		for (const event of events) window.addEventListener(event, resetTimer, { passive: true });
+		return () => {
+			if (timeoutRef.current !== null) window.clearTimeout(timeoutRef.current);
+			for (const event of events) window.removeEventListener(event, resetTimer);
+		};
+	}, [
+		events,
+		isBrowser,
+		resetTimer
+	]);
+	return {
+		isIdle,
+		lastActiveAt: lasActiveRef.current
+	};
+}
+
+//#endregion
+export { useIdle };

package/dist/useIndexedDB.d.ts

@@ -0,0 +1,60 @@
+//#region src/useIndexedDB.d.ts
+interface UseIndexedDBOptions {
+  /**
+   * Database name
+   */
+  name: string;
+  /**
+   * Option upgrade callback
+   */
+  onUpgrade?: (db: IDBDatabase, oldVersion: number, newVersion: number | null) => void;
+  /**
+   * Database version
+   */
+  version: number;
+}
+interface UseIndexedDBTransactionOptions {
+  mode?: IDBTransactionMode;
+}
+interface UseIndexedDBTransactionReturn {
+  /**
+   * Closes the database connection
+   */
+  close: () => void;
+  /**
+   * Deletes the database
+   */
+  deleteDatabase: () => Promise<void>;
+  /**
+   * Opens the database connection
+   */
+  open: () => Promise<IDBDatabase>;
+  /**
+   * Runs a transaction and exposes the object store
+   */
+  withStore: <T>(storeName: string, fn: (store: IDBObjectStore) => Promise<T>, options?: UseIndexedDBTransactionOptions) => Promise<T>;
+}
+/**
+ * `useIndexedDB` is a React hook that provides unopinionated access to IndexedDB.
+ * This hook does not manage schemas, objet stores, or data shape.
+ * It only abstracts database lifecycle and transaction boilerplate.
+ *
+ * @example
+ * ```tsx
+ * const db = useIndexedDB({
+ *   name: 'app-db',
+ *   version: 1,
+ *   onUpgrade(db) {
+ *     db.createObjectStore('users', { keyPath: 'id' });
+ *   },
+ * });
+ *
+ * await db.withStore('users', async (store) => {
+ *   store.put({ id: '1', name: 'Sebas' });
+ * });
+ * ```
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API
+ */
+declare function useIndexedDB(options: UseIndexedDBOptions): UseIndexedDBTransactionReturn;
+//#endregion
+export { useIndexedDB };

package/dist/useIndexedDB.js

@@ -0,0 +1,75 @@
+import * as React from "react";
+
+//#region src/useIndexedDB.ts
+/**
+* `useIndexedDB` is a React hook that provides unopinionated access to IndexedDB.
+* This hook does not manage schemas, objet stores, or data shape.
+* It only abstracts database lifecycle and transaction boilerplate.
+*
+* @example
+* ```tsx
+* const db = useIndexedDB({
+*   name: 'app-db',
+*   version: 1,
+*   onUpgrade(db) {
+*     db.createObjectStore('users', { keyPath: 'id' });
+*   },
+* });
+*
+* await db.withStore('users', async (store) => {
+*   store.put({ id: '1', name: 'Sebas' });
+* });
+* ```
+* @see https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API
+*/
+function useIndexedDB(options) {
+	const dbRef = React.useRef(null);
+	const isSupported = typeof window !== "undefined" && typeof window.indexedDB !== "undefined";
+	const open = React.useCallback(() => {
+		if (!isSupported) return Promise.reject(/* @__PURE__ */ new Error("IndexedDB not supported."));
+		if (dbRef.current) return Promise.resolve(dbRef.current);
+		return new Promise((resolve, reject) => {
+			const request = indexedDB.open(options.name, options.version);
+			request.onupgradeneeded = (event) => {
+				options.onUpgrade?.(request.result, event.oldVersion, event.newVersion);
+			};
+			request.onsuccess = () => {
+				dbRef.current = request.result;
+				resolve(dbRef.current);
+			};
+			request.onerror = () => {
+				reject(request.error);
+			};
+		});
+	}, [isSupported, options]);
+	const withStore = React.useCallback(async (storeName, fn, options$1) => {
+		const db = await open();
+		return new Promise((resolve, reject) => {
+			const tx = db.transaction(storeName, options$1?.mode ?? "readwrite");
+			fn(tx.objectStore(storeName)).then((result) => {
+				tx.oncomplete = () => resolve(result);
+				tx.onerror = () => reject(tx.error);
+			}).catch(reject);
+		});
+	}, [open]);
+	const close = React.useCallback(() => {
+		dbRef.current?.close();
+		dbRef.current = null;
+	}, []);
+	return {
+		close,
+		deleteDatabase: React.useCallback(() => {
+			close();
+			return new Promise((resolve, reject) => {
+				const request = indexedDB.deleteDatabase(options.name);
+				request.onsuccess = () => resolve();
+				request.onerror = () => reject(request.error);
+			});
+		}, [close, options.name]),
+		open,
+		withStore
+	};
+}
+
+//#endregion
+export { useIndexedDB };