@vibehooks/react 0.0.1

package/dist/useAutoScroll.js

@@ -0,0 +1,122 @@
+import * as React from "react";
+
+//#region src/useAutoScroll.ts
+/**
+* `useAutoScroll` is a custom hook for automatically scrolling to the bottom of a container element.
+* It keeps the scroll at the bottom of the container while new content is generated, but only if the user is near the bottom. If the user scrolls up to read previous content, auto-scrolling is automatically disabled so as not to interrupt their reading.
+*
+* @example
+* ```tsx
+* function ChatInterface() {
+*   const { ref, isAtBottom, scrollToBottom } = useAutoScroll({
+*     threshold: 50,
+*     behavior: 'smooth'
+*   });
+*
+*   return (
+*     <div>
+*       <div ref={ref} className="chat-container">
+*         {messages.map(msg => (
+*           <Message key={msg.id} content={msg.content} />
+*         ))}
+*       </div>
+*       {!isAtBottom && (
+*         <button onClick={scrollToBottom}>
+*           Ir al final ↓
+*         </button>
+*       )}
+*     </div>
+*   );
+* }
+* ```
+*/
+function useAutoScroll(options) {
+	const { behavior = "auto", enabled: initialEnabled = true, threshold = 100 } = options || {};
+	const containerRef = React.useRef(null);
+	const [isAtBottom, setIsAtBottom] = React.useState(true);
+	const [autoScrollEnabled, setAutoScrollEnabled] = React.useState(initialEnabled);
+	const isScrollingProgrammatically = React.useRef(false);
+	const checkIfABottom = React.useCallback(() => {
+		const container = containerRef.current;
+		if (!container) return false;
+		const { clientHeight, scrollHeight, scrollTop } = container;
+		return scrollHeight - scrollTop - clientHeight <= threshold;
+	}, [threshold]);
+	const scrollToBottom = React.useCallback((forceSmooth) => {
+		const container = containerRef.current;
+		if (!container) return;
+		isScrollingProgrammatically.current = true;
+		container.scrollTo({
+			behavior: forceSmooth !== void 0 ? forceSmooth ? "smooth" : "auto" : behavior,
+			top: container.scrollHeight
+		});
+		setTimeout(() => {
+			isScrollingProgrammatically.current = false;
+		}, 100);
+	}, [behavior]);
+	const enableAutoScroll = React.useCallback(() => {
+		setAutoScrollEnabled(true);
+		scrollToBottom();
+	}, [scrollToBottom]);
+	const disableAutoScroll = React.useCallback(() => {
+		setAutoScrollEnabled(false);
+	}, []);
+	const handleScroll = React.useCallback(() => {
+		if (isScrollingProgrammatically.current) return;
+		const atBottom = checkIfABottom();
+		setIsAtBottom(atBottom);
+		if (!atBottom && autoScrollEnabled) setAutoScrollEnabled(false);
+		else if (atBottom && !autoScrollEnabled) setAutoScrollEnabled(true);
+	}, [checkIfABottom, autoScrollEnabled]);
+	React.useEffect(() => {
+		const container = containerRef.current;
+		if (!container) return;
+		const observer = new MutationObserver(() => {
+			if (autoScrollEnabled && isAtBottom) scrollToBottom(false);
+		});
+		observer.observe(container, {
+			characterData: true,
+			childList: true,
+			subtree: true
+		});
+		return () => observer.disconnect();
+	}, [
+		autoScrollEnabled,
+		isAtBottom,
+		scrollToBottom
+	]);
+	React.useEffect(() => {
+		const container = containerRef.current;
+		if (!container) return;
+		container.addEventListener("scroll", handleScroll, { passive: true });
+		return () => container.removeEventListener("scroll", handleScroll);
+	}, []);
+	React.useEffect(() => {
+		const container = containerRef.current;
+		if (!container) return;
+		const initialCheck = () => {
+			setIsAtBottom(checkIfABottom());
+		};
+		initialCheck();
+		const images = container.querySelectorAll("img");
+		images.forEach((img) => {
+			img.addEventListener("load", initialCheck);
+		});
+		return () => {
+			images.forEach((img) => {
+				img.removeEventListener("load", initialCheck);
+			});
+		};
+	}, [checkIfABottom]);
+	return {
+		autoScrollEnabled,
+		disableAutoScroll,
+		enableAutoScroll,
+		isAtBottom,
+		ref: containerRef,
+		scrollToBottom
+	};
+}
+
+//#endregion
+export { useAutoScroll };

package/dist/useBarcode.d.ts

@@ -0,0 +1,77 @@
+import * as React from "react";
+
+//#region src/useBarcode.d.ts
+declare global {
+  interface BarcodeDetectorOptions {
+    formats?: string[];
+  }
+  interface DetectorBarcode {
+    boundingBox?: DOMRectReadOnly;
+    format: string;
+    rawValue: string;
+  }
+  class BarcodeDetector {
+    constructor(options?: BarcodeDetectorOptions);
+    static getSupportedFormats(): string[];
+    detect(image: HTMLVideoElement | HTMLImageElement | HTMLCanvasElement): Promise<DetectorBarcode[]>;
+  }
+}
+interface UseBarcodeReturn {
+  /**
+   * Raw value of the barcode.
+   */
+  current: DetectorBarcode | null;
+  /**
+   * A function to start the scanning process.
+   */
+  start: () => Promise<void>;
+  /**
+   * A function to stop the scanning process.
+   */
+  stop: () => void;
+  /**
+   * Whether the browser supports BarcodeDetector API.
+   */
+  supported: boolean;
+}
+interface UseBarcodeOptions {
+  /**
+   * Optional element to scan: video, image or canvas.
+   */
+  elementRef?: React.RefObject<HTMLVideoElement | HTMLImageElement | HTMLCanvasElement | null>;
+  /**
+   * Optional formats to detect (default includes most common formats).
+   */
+  formats?: string[];
+  /**
+   * Optional callback to be called when a barcode is detected.
+   */
+  onDetect?: (barcode: DetectorBarcode) => void;
+}
+/**
+ * `useBarcode` is a hook to detect barcodes using the browser's BarcodeDetector API.
+ * Automatically handles camera permissions, stream cleanup, and updates the last detected barcode.
+ *
+ * @example
+ * ```tsx
+ * const videoRef = useRef<HTMLVideoElement>(null);
+ * const { rawValue, supported } = useBarcode({ elementRef: videoRef });
+ *
+ * if (!supported) return <p>Barcode detection not supported</p>;
+ *
+ * return (
+ *   <div>
+ *     <video ref={videoRef} autoPlay />
+ *     {rawValue && <p>Last barcode: {rawValue.rawValue}</p>}
+ *   </div>
+ * );
+ * ```
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Barcode_Detection_API
+ */
+declare function useBarcode({
+  elementRef,
+  formats,
+  onDetect
+}?: UseBarcodeOptions): UseBarcodeReturn;
+//#endregion
+export { useBarcode };

package/dist/useBarcode.js

@@ -0,0 +1,140 @@
+import * as React from "react";
+
+//#region src/useBarcode.ts
+/**
+* `useBarcode` is a hook to detect barcodes using the browser's BarcodeDetector API.
+* Automatically handles camera permissions, stream cleanup, and updates the last detected barcode.
+*
+* @example
+* ```tsx
+* const videoRef = useRef<HTMLVideoElement>(null);
+* const { rawValue, supported } = useBarcode({ elementRef: videoRef });
+*
+* if (!supported) return <p>Barcode detection not supported</p>;
+*
+* return (
+*   <div>
+*     <video ref={videoRef} autoPlay />
+*     {rawValue && <p>Last barcode: {rawValue.rawValue}</p>}
+*   </div>
+* );
+* ```
+* @see https://developer.mozilla.org/en-US/docs/Web/API/Barcode_Detection_API
+*/
+function useBarcode({ elementRef, formats = [
+	"aztec",
+	"code_128",
+	"code_39",
+	"code_93",
+	"codabar",
+	"data_matrix",
+	"ean_13",
+	"ean_8",
+	"itf",
+	"pdf417",
+	"qr_code",
+	"upc_a",
+	"upc_e",
+	"unknown"
+], onDetect } = {}) {
+	const [current, setCurrent] = React.useState(null);
+	const [supported, setSupported] = React.useState(false);
+	const lastEmittedRef = React.useRef(null);
+	const animationRef = React.useRef(null);
+	const streamRef = React.useRef(null);
+	const detectorRef = React.useRef(null);
+	const runningRef = React.useRef(false);
+	React.useEffect(() => {
+		if (typeof window === "undefined" || !("BarcodeDetector" in window)) {
+			setSupported(false);
+			return;
+		}
+		setSupported(true);
+		detectorRef.current = new BarcodeDetector({ formats });
+	}, [formats]);
+	const emitDetected = React.useCallback((barcode) => {
+		const key = `${barcode.format}-${barcode.rawValue}`;
+		if (lastEmittedRef.current === key) return;
+		lastEmittedRef.current = key;
+		setCurrent(barcode);
+		onDetect?.(barcode);
+	}, [onDetect]);
+	const scanOnce = React.useCallback(async (el) => {
+		if (!detectorRef.current) return;
+		try {
+			const barcodes = await detectorRef.current.detect(el);
+			if (barcodes.length > 0 && barcodes[0]) emitDetected(barcodes[0]);
+			else {
+				lastEmittedRef.current = null;
+				setCurrent(null);
+			}
+		} catch (error) {
+			console.warn("useBarcode: barcode detection failed.", error);
+		}
+	}, [emitDetected]);
+	const scanLoop = React.useCallback(async (video) => {
+		if (!runningRef.current) return;
+		if (video.videoWidth === 0) {
+			animationRef.current = requestAnimationFrame(() => scanLoop(video));
+			return;
+		}
+		await scanOnce(video);
+		animationRef.current = requestAnimationFrame(() => scanLoop(video));
+	}, [scanOnce]);
+	const start = React.useCallback(async () => {
+		if (!supported) return;
+		if (!elementRef?.current) return;
+		if (runningRef.current) return;
+		const el = elementRef.current;
+		runningRef.current = true;
+		if (el instanceof HTMLVideoElement) {
+			try {
+				streamRef.current = await navigator.mediaDevices.getUserMedia({ video: { facingMode: "environment" } });
+				el.srcObject = streamRef.current;
+				el.setAttribute("playsinline", "true");
+				await el.play();
+				scanLoop(el);
+			} catch (error) {
+				runningRef.current = false;
+				console.warn("useBarcode: camera access denied or unavailable.", error);
+			}
+			return;
+		}
+		if (el instanceof HTMLImageElement || el instanceof HTMLCanvasElement) {
+			await scanOnce(el);
+			runningRef.current = false;
+			return;
+		}
+		runningRef.current = false;
+	}, [
+		elementRef,
+		scanLoop,
+		scanOnce,
+		supported
+	]);
+	const stop = React.useCallback(() => {
+		runningRef.current = false;
+		if (animationRef.current !== null) {
+			cancelAnimationFrame(animationRef.current);
+			animationRef.current = null;
+		}
+		if (streamRef.current) {
+			streamRef.current.getTracks().forEach((track) => track.stop());
+			streamRef.current = null;
+		}
+		lastEmittedRef.current = null;
+		setCurrent(null);
+	}, []);
+	React.useEffect(() => {
+		return () => stop();
+	}, []);
+	return {
+		current,
+		start,
+		stop,
+		supported
+	};
+}
+
+//#endregion
+export { useBarcode };

package/dist/useBatteryStatus.d.ts

@@ -0,0 +1,53 @@
+//#region src/useBatteryStatus.d.ts
+interface UseBatteryStatus {
+  /** Indicates whether the device is currently charging. */
+  charging: boolean | null;
+  /** Time in seconds until the battery is fully charged. `Infinity` means the battery is already full or charging is not applicable. */
+  chargingTime: number | null;
+  /** Time in seconds until the battery is completely discharged. `Infinity` means the system cannot determine the remaining time. */
+  dischargingTime: number | null;
+  /** Battery level represented as a value between 0.0 and 1.0 */
+  level: number | null;
+}
+interface UseBatteryStatusReturn {
+  /** Raw battery information. Values are `null` until the Battery Manager is resolved. */
+  battery: UseBatteryStatus;
+  /** Indicates whether the Battery Status API is supported in the current runtime environment. */
+  isSupported: boolean;
+}
+declare global {
+  interface BatteryManager extends EventTarget {
+    addEventListener(type: 'chargingchange' | 'levelchange' | 'chargingtimechange' | 'dischargingtimechange', listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+    readonly charging: boolean;
+    readonly chargingTime: number;
+    readonly dischargingTime: number;
+    readonly level: number;
+    removeEventListener(type: 'chargingchange' | 'levelchange' | 'chargingtimechange' | 'dischargingtimechange', listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+  }
+  interface Navigator {
+    getBattery(): Promise<BatteryManager>;
+  }
+}
+/**
+ * `useBatteryStatus`is a hook that provides information about the system's battery charge level and lets you be notified by events that are sent when the battery level or charging status changes.
+ * This hook uses the native 'Battery Status API and it is not available in Web Workers and it is available only in secure contexts (HTTPS).
+ *
+ * @example
+ * ```tsx
+ * const { isSupported, battery } = useBatteryStatus();
+ *
+ * if (!isSupported) {
+ *   return <span>Battery API not supported</span>;
+ * }
+ * return (
+ *  <div>
+ *   <p>Charging: {battery.charging ? 'Yes' : 'No'}</p>
+ *   <p>Level: {battery.level}</p>
+ *  </div>
+);
+ * ```
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Battery_Status_API
+ */
+declare function useBatteryStatus(): UseBatteryStatusReturn;
+//#endregion
+export { useBatteryStatus };

package/dist/useBatteryStatus.js

@@ -0,0 +1,67 @@
+import * as React from "react";
+
+//#region src/useBatteryStatus.ts
+/**
+* `useBatteryStatus`is a hook that provides information about the system's battery charge level and lets you be notified by events that are sent when the battery level or charging status changes.
+* This hook uses the native 'Battery Status API and it is not available in Web Workers and it is available only in secure contexts (HTTPS).
+*
+* @example
+* ```tsx
+* const { isSupported, battery } = useBatteryStatus();
+*
+* if (!isSupported) {
+*   return <span>Battery API not supported</span>;
+* }
+* return (
+*  <div>
+*   <p>Charging: {battery.charging ? 'Yes' : 'No'}</p>
+*   <p>Level: {battery.level}</p>
+*  </div>
+);
+* ```
+* @see https://developer.mozilla.org/en-US/docs/Web/API/Battery_Status_API
+*/
+function useBatteryStatus() {
+	const isSupported = typeof navigator !== "undefined" && typeof navigator.getBattery === "function";
+	const [battery, setBattery] = React.useState({
+		charging: null,
+		chargingTime: null,
+		dischargingTime: null,
+		level: null
+	});
+	React.useEffect(() => {
+		if (!isSupported) return;
+		let batteryManager = null;
+		const updateBatteryState = () => {
+			if (!batteryManager) return;
+			setBattery({
+				charging: batteryManager.charging,
+				chargingTime: batteryManager.chargingTime,
+				dischargingTime: batteryManager.dischargingTime,
+				level: batteryManager.level
+			});
+		};
+		navigator.getBattery().then((bm) => {
+			batteryManager = bm;
+			updateBatteryState();
+			bm.addEventListener("chargingchange", updateBatteryState);
+			bm.addEventListener("levelchange", updateBatteryState);
+			bm.addEventListener("chargingtimechange", updateBatteryState);
+			bm.addEventListener("dischargingtimechange", updateBatteryState);
+		});
+		return () => {
+			if (!batteryManager) return;
+			batteryManager.removeEventListener("chargingchange", updateBatteryState);
+			batteryManager.removeEventListener("levelchange", updateBatteryState);
+			batteryManager.removeEventListener("chargingtimechange", updateBatteryState);
+			batteryManager.removeEventListener("dischargingtimechange", updateBatteryState);
+		};
+	}, [isSupported]);
+	return {
+		battery,
+		isSupported
+	};
+}
+
+//#endregion
+export { useBatteryStatus };

package/dist/useBodyScrollFreeze.d.ts

@@ -0,0 +1,36 @@
+//#region src/useBodyScrollFreeze.d.ts
+type ScrollAxis = 'x' | 'y' | 'both';
+interface BodyScrollFreezeOptions {
+  /**
+   * Axis to freeze.
+   * - 'x'    → horizontal scroll
+   * - 'y'    → vertical scroll
+   * - 'both' → horizontal and vertical scroll
+   *
+   * @default 'y'
+   */
+  axis?: ScrollAxis;
+}
+interface BodyScrollFreezeReturn {
+  freeze: (options?: BodyScrollFreezeOptions) => void;
+  unfreeze: () => void;
+}
+/**
+ * `useBodyScrollFreeze` is an unopinionated React hook that provides an imperative API to disable body scrolling on one or both axes.
+ * The hook captures the original `overflowX` and `overflowY` values and restores them exactly when the component is unmounted.
+ *
+ * The hook does not automatically lock scrolling; consumers decide
+ * when and how to apply it.
+ *
+ * @example
+ * ```tsx
+ * const { freeze } = useBodyScrollFreeze();
+ *
+ * freeze(); // freezes vertical scroll (default)
+ * freeze({ axis: 'both' });
+ * freeze({ axis: 'x' });
+ * ```
+ */
+declare function useBodyScrollFreeze(): BodyScrollFreezeReturn;
+//#endregion
+export { useBodyScrollFreeze };

package/dist/useBodyScrollFreeze.js

@@ -0,0 +1,74 @@
+import * as React from "react";
+
+//#region src/useBodyScrollFreeze.ts
+/**
+* `useBodyScrollFreeze` is an unopinionated React hook that provides an imperative API to disable body scrolling on one or both axes.
+* The hook captures the original `overflowX` and `overflowY` values and restores them exactly when the component is unmounted.
+*
+* The hook does not automatically lock scrolling; consumers decide
+* when and how to apply it.
+*
+* @example
+* ```tsx
+* const { freeze } = useBodyScrollFreeze();
+*
+* freeze(); // freezes vertical scroll (default)
+* freeze({ axis: 'both' });
+* freeze({ axis: 'x' });
+* ```
+*/
+function useBodyScrollFreeze() {
+	const originalStyles = React.useRef(null);
+	const freeze = React.useCallback((options) => {
+		if (typeof window === "undefined") return;
+		const axis = options?.axis ?? "y";
+		const body = document.body;
+		if (!originalStyles.current) originalStyles.current = {
+			overflowX: body.style.overflowX,
+			overflowY: body.style.overflowY,
+			position: body.style.position,
+			scrollY: window.scrollY,
+			top: body.style.top,
+			width: body.style.width
+		};
+		body.style.position = "fixed";
+		body.style.top = `-${originalStyles.current.scrollY}px`;
+		body.style.width = "100%";
+		if (axis === "x" || axis === "both") body.style.overflowX = "hidden";
+		if (axis === "y" || axis === "both") body.style.overflowY = "hidden";
+	}, []);
+	const unfreeze = React.useCallback(() => {
+		if (typeof window === "undefined") return;
+		if (!originalStyles.current) return;
+		const body = document.body;
+		const { overflowX, overflowY, position, scrollY, top, width } = originalStyles.current;
+		body.style.position = position;
+		body.style.top = top;
+		body.style.width = width;
+		body.style.overflowX = overflowX;
+		body.style.overflowY = overflowY;
+		window.scrollTo(0, scrollY);
+		originalStyles.current = null;
+	}, []);
+	React.useEffect(() => {
+		return () => {
+			if (typeof window === "undefined") return;
+			if (!originalStyles.current) return;
+			const body = document.body;
+			const { overflowX, overflowY, position, scrollY, top, width } = originalStyles.current;
+			body.style.position = position;
+			body.style.top = top;
+			body.style.width = width;
+			body.style.overflowX = overflowX;
+			body.style.overflowY = overflowY;
+			window.scrollTo(0, scrollY);
+		};
+	}, []);
+	return {
+		freeze,
+		unfreeze
+	};
+}
+
+//#endregion
+export { useBodyScrollFreeze };

package/dist/useCameraCapture.d.ts

@@ -0,0 +1,76 @@
+import * as React from "react";
+
+//#region src/useCameraCapture.d.ts
+type CameraCaptureFormat = 'image/jpeg' | 'image/png';
+interface CameraCaptureOutput {
+  /**
+   * Image quality (0.0 - 1.0)
+   * Only applies to lossy formats (JPEG).
+   */
+  quality?: number;
+  /**
+   * MIME type of the captured image.
+   */
+  type: CameraCaptureFormat;
+}
+interface UseCameraCaptureOptions {
+  format?: CameraCaptureOutput;
+  /**
+   * Optional callback executed after a photo is captured.
+   * Provides both the base64 data URL and the Blob representation.
+   */
+  onCapture?: (dataUrl: string, blob: Blob) => void;
+  /**
+   * Desired output width for the captured image.
+   * The height is automatically calculated to preserve the aspect ratio.
+   *
+   * @default 320
+   */
+  width?: number;
+}
+interface UseCameraCaptureReturn {
+  /**
+   * Ref to the offscreen HTMLCanvasElement used for frame capture.
+   */
+  canvasRef: React.RefObject<HTMLCanvasElement | null>;
+  /**
+   * Captures the current video frame and renders it to the canvas.
+   */
+  capture: () => string | null;
+  /**
+   * Ref to the HTMLImageElement where the captured photo can be rendered.
+   */
+  imageRef: React.RefObject<HTMLImageElement | null>;
+  /**
+   * Requests camera permissions and starts the video stream.
+   * Can be safely called again if the user initially denied access.
+   */
+  requestPermission: () => Promise<boolean>;
+  /**
+   * Stops all active media tracks and releases the camera.
+   */
+  stop: () => void;
+  /**
+   * Indicates whether camera permissions has been granted.
+   */
+  usePermission: () => boolean;
+  /**
+   * Indicates whether the video stream is currently active.
+   */
+  useStreaming: () => boolean;
+  /**
+   * Ref to the HTMLVideoElement that renders the live camera stream.
+   */
+  videoRef: React.RefObject<HTMLVideoElement | null>;
+}
+/**
+ * Unopinionated, SSR-safe React hook for capturing still photos from the user's camera using getUserMedia and Canvas.
+ *
+ * @example
+ * ```tsx
+ * const { videoRef, requestPermission, capture } = useCameraCapture();
+ * ```
+ */
+declare function useCameraCapture(options?: UseCameraCaptureOptions): UseCameraCaptureReturn;
+//#endregion
+export { useCameraCapture };