@vibehooks/react 0.0.1

package/dist/useServerSentEvent.d.ts

@@ -0,0 +1,57 @@
+//#region src/useServerSentEvent.d.ts
+interface UseServerSentEventOptions {
+  /**
+   * Whether the connection should be established.
+   * Usefull to lazily connect.
+   */
+  enabled?: boolean;
+  /**
+   * Called when an error occurs.
+   */
+  onError?: (event: Event) => void;
+  /**
+   * Called on every incoming message event.
+   */
+  onMessage?: (event: MessageEvent<string>) => void;
+  /**
+   * Called then the connection is opened.
+   */
+  onOpen?: (event: Event) => void;
+  /**
+   * Whether credentials (cookies) should be sent.
+   */
+  withCredentials?: boolean;
+}
+interface UseServerSentEventReturn {
+  /**
+   * Manually closes the connection.
+   */
+  close: () => void;
+  /**
+   * Current connection state.
+   */
+  readyState: SSEReadyState | null;
+}
+type SSEReadyState = 0 | 1 | 2;
+/**
+ * 0 = CONNECTING
+ * 1 = OPEN
+ * 2 = CLOSED
+ */
+/**
+ * `useServerSideEvent` provides unopinionated access to Server-Sent Event (SSE) via the EventSource Web API.
+ * It manages the EventSource lifecycle but delegates data handling to consumer callbacks.
+ *
+ * @example
+ * ```tsx
+ * useServerSideEvent('/api/events', {
+ *   onMessage: (e) => {
+ *     const data = JSON.parse(e.data);
+ *     console.log(data);
+ *   }
+ * });
+ * ```
+ */
+declare function useServerSentEvent(url: string, options?: UseServerSentEventOptions): UseServerSentEventReturn;
+//#endregion
+export { useServerSentEvent };

package/dist/useServerSentEvent.js

@@ -0,0 +1,78 @@
+import * as React from "react";
+
+//#region src/useServerSentEvent.ts
+/**
+* 0 = CONNECTING
+* 1 = OPEN
+* 2 = CLOSED
+*/
+/**
+* `useServerSideEvent` provides unopinionated access to Server-Sent Event (SSE) via the EventSource Web API.
+* It manages the EventSource lifecycle but delegates data handling to consumer callbacks.
+*
+* @example
+* ```tsx
+* useServerSideEvent('/api/events', {
+*   onMessage: (e) => {
+*     const data = JSON.parse(e.data);
+*     console.log(data);
+*   }
+* });
+* ```
+*/
+function useServerSentEvent(url, options = {}) {
+	const { enabled = true, onError, onMessage, onOpen, withCredentials = false } = options;
+	const sourceRef = React.useRef(null);
+	const [readyState, setReadyState] = React.useState(null);
+	const onMessageRef = React.useRef(onMessage);
+	const onOpenRef = React.useRef(onOpen);
+	const onErrorRef = React.useRef(onError);
+	const isSupported = typeof window !== "undefined" && typeof EventSource !== "undefined";
+	const close = React.useCallback(() => {
+		sourceRef.current?.close();
+		sourceRef.current = null;
+		setReadyState(null);
+	}, []);
+	React.useEffect(() => {
+		onMessageRef.current = onMessage;
+		onOpenRef.current = onOpen;
+		onErrorRef.current = onError;
+	}, [
+		onMessageRef,
+		onOpenRef,
+		onErrorRef
+	]);
+	React.useEffect(() => {
+		if (!isSupported || !enabled) return;
+		const source = new EventSource(url, { withCredentials });
+		sourceRef.current = source;
+		source.onopen = (event) => {
+			setReadyState(source.readyState);
+			onOpenRef.current?.(event);
+		};
+		source.onmessage = (event) => {
+			setReadyState(source.readyState);
+			onMessageRef.current?.(event);
+		};
+		source.onerror = (event) => {
+			setReadyState(source.readyState);
+			onErrorRef.current?.(event);
+		};
+		return () => {
+			source.close();
+			sourceRef.current = null;
+		};
+	}, [
+		url,
+		enabled,
+		withCredentials,
+		isSupported
+	]);
+	return {
+		close,
+		readyState
+	};
+}
+
+//#endregion
+export { useServerSentEvent };

package/dist/useShoppingCart.d.ts

@@ -0,0 +1,54 @@
+//#region src/useShoppingCart.d.ts
+interface UseShoppingCartOptions<T extends object> {
+  getItemDiscount?: (item: T) => number;
+  getItemKey: (item: T) => string | number;
+  getItemPrice: (item: T) => number;
+  getItemQuantity: (item: T) => number;
+  getItemTax?: (item: T) => number;
+}
+interface ShoppingCartItemDetail {
+  discount: number;
+  key: string | number;
+  quantity: number;
+  subtotal: number;
+  tax: number;
+  total: number;
+  unitPrice: number;
+}
+interface UseShoppingCartReturn<T extends object> {
+  addItem: (item: T) => void;
+  clear: () => void;
+  getDetails: () => ShoppingCartItemDetail[];
+  getItemCount: () => number;
+  getSubtotal: () => number;
+  getTotal: () => number;
+  getTotalDiscount: () => number;
+  getTotalQuantity: () => number;
+  getTotalTax: () => number;
+  items: T[];
+  removeItem: (id: number | string) => void;
+  updateItem: (id: number | string, patch: Partial<T>) => void;
+}
+/**
+ * `useShoppingCart` is a fully unopinionated React hook for managing shopping cart state.
+ * The hook does not assume any data structure; instead, it relies on user-provided extractor functions to derive semantic meaning (identity, price, quantity, taxes, discounts).
+ * This design allows the hook to adapt to any domain model while still providing a complete and ergonomic shopping cart API.
+ *
+ * @example
+ * ```tsx
+ * const cart = useShoppingCart<Product>({
+ *   getItemKey: p => p.id,
+ *   getItemPrice: p => p.price,
+ *   getItemQuantity: p => p.quantity,
+ *   getItemTax: p => p.tax ?? 0,
+ *   getItemDiscount: p => p.discount ?? 0,
+ * });
+ *
+ * cart.addItem(product);
+ * cart.getTotal();
+ * cart.getDetails();
+ * ```
+ */
+declare function useShoppingCart<T extends object>(options: UseShoppingCartOptions<T>): UseShoppingCartReturn<T>;
+//#endregion
+export { useShoppingCart };

package/dist/useShoppingCart.js

@@ -0,0 +1,122 @@
+import * as React from "react";
+
+//#region src/useShoppingCart.ts
+/**
+* `useShoppingCart` is a fully unopinionated React hook for managing shopping cart state.
+* The hook does not assume any data structure; instead, it relies on user-provided extractor functions to derive semantic meaning (identity, price, quantity, taxes, discounts).
+* This design allows the hook to adapt to any domain model while still providing a complete and ergonomic shopping cart API.
+*
+* @example
+* ```tsx
+* const cart = useShoppingCart<Product>({
+*   getItemKey: p => p.id,
+*   getItemPrice: p => p.price,
+*   getItemQuantity: p => p.quantity,
+*   getItemTax: p => p.tax ?? 0,
+*   getItemDiscount: p => p.discount ?? 0,
+* });
+*
+* cart.addItem(product);
+* cart.getTotal();
+* cart.getDetails();
+* ```
+*/
+function useShoppingCart(options) {
+	const { getItemDiscount, getItemKey, getItemPrice, getItemQuantity, getItemTax } = options;
+	const [items, setItems] = React.useState([]);
+	const addItem = React.useCallback((item) => {
+		setItems((prevItems) => [...prevItems, item]);
+	}, []);
+	const removeItem = React.useCallback((key) => {
+		setItems((prevItems) => prevItems.filter((item) => getItemKey(item) !== key));
+	}, [getItemKey]);
+	const updateItem = React.useCallback((key, patch) => {
+		setItems((prev) => prev.map((item) => getItemKey(item) === key ? {
+			...item,
+			...patch
+		} : item));
+	}, [getItemKey]);
+	const clear = React.useCallback(() => {
+		setItems([]);
+	}, []);
+	const getItemCount = React.useCallback(() => items.length, [items]);
+	const getTotalQuantity = React.useCallback(() => items.reduce((acc, item) => acc + getItemQuantity(item), 0), [items, getItemQuantity]);
+	const getSubtotal = React.useCallback(() => items.reduce((acc, item) => acc + getItemPrice(item) * getItemQuantity(item), 0), [
+		items,
+		getItemPrice,
+		getItemQuantity
+	]);
+	const getTotalTax = React.useCallback(() => getItemTax ? items.reduce((acc, item) => acc + getItemTax(item) * getItemQuantity(item), 0) : 0, [
+		items,
+		getItemTax,
+		getItemQuantity
+	]);
+	const getTotalDiscount = React.useCallback(() => getItemDiscount ? items.reduce((acc, item) => acc + getItemDiscount(item) * getItemQuantity(item), 0) : 0, [
+		items,
+		getItemDiscount,
+		getItemQuantity
+	]);
+	const getTotal = React.useCallback(() => getSubtotal() + getTotalTax() + getTotalDiscount(), [
+		getSubtotal,
+		getTotalTax,
+		getTotalDiscount
+	]);
+	return {
+		addItem,
+		clear,
+		getDetails: React.useCallback(() => {
+			const map = /* @__PURE__ */ new Map();
+			for (const item of items) {
+				const key = getItemKey(item);
+				const quantity = getItemQuantity(item);
+				const unitPrice = getItemPrice(item);
+				const tax = getItemTax ? getItemTax(item) : 0;
+				const discount = getItemDiscount ? getItemDiscount(item) : 0;
+				const existing = map.get(key);
+				if (!existing) {
+					const subtotal = quantity * unitPrice;
+					const taxTotal = tax * quantity;
+					const discountTotal = discount * quantity;
+					map.set(key, {
+						discount: discountTotal,
+						key,
+						quantity,
+						subtotal,
+						tax: taxTotal,
+						total: subtotal + taxTotal - discountTotal,
+						unitPrice
+					});
+				} else {
+					existing.quantity += quantity;
+					const subtTotalIncrement = quantity * unitPrice;
+					const taxIncrement = tax * quantity;
+					const discountIncrement = discount * quantity;
+					existing.subtotal += subtTotalIncrement;
+					existing.tax += taxIncrement;
+					existing.discount += discountIncrement;
+					existing.total += subtTotalIncrement + taxIncrement - discountIncrement;
+				}
+			}
+			return Array.from(map.values());
+		}, [
+			items,
+			getItemKey,
+			getItemPrice,
+			getItemQuantity,
+			getItemTax,
+			getItemDiscount
+		]),
+		getItemCount,
+		getSubtotal,
+		getTotal,
+		getTotalDiscount,
+		getTotalQuantity,
+		getTotalTax,
+		items,
+		removeItem,
+		updateItem
+	};
+}
+
+//#endregion
+export { useShoppingCart };

package/dist/useSmartVideo.d.ts

@@ -0,0 +1,35 @@
+import * as React from "react";
+
+//#region src/useSmartVideo.d.ts
+interface SmartVideoOptions {
+  /**
+   * Auto-play when video becomes visible.
+   */
+  autoPlay?: boolean;
+  /**
+   * Pause video when it leaves the viewport.
+   */
+  pauseOnExit?: boolean;
+  /**
+   * Reset video to time 0 when it leaves the viewport.
+   */
+  resetOnExit?: boolean;
+  /**
+   * Percentage of visibility required to start playing.
+   * (0.0 - 1.0)
+   * Default: 0.5
+   */
+  threshold?: number;
+}
+interface SmartVideoReturn {
+  isPlaying: boolean;
+  isVisible: boolean;
+  pause: () => void;
+  play: () => Promise<void>;
+  reset: () => void;
+  stop: () => void;
+  videoRef: React.RefObject<HTMLVideoElement | null>;
+}
+declare function useSmartVideo(options?: SmartVideoOptions): SmartVideoReturn;
+//#endregion
+export { useSmartVideo };

package/dist/useSmartVideo.js

@@ -0,0 +1,76 @@
+import { useIntersectionObserver } from "./useIntersectionObserver.js";
+import * as React from "react";
+
+//#region src/useSmartVideo.ts
+function useSmartVideo(options = {}) {
+	const { autoPlay, pauseOnExit, resetOnExit, threshold } = options;
+	const videoRef = React.useRef(null);
+	const { isVisible } = useIntersectionObserver({ threshold: threshold ?? .5 }, videoRef);
+	const [isPlaying, setIsPlaying] = React.useState(false);
+	React.useEffect(() => {
+		const video = videoRef.current;
+		if (!video) return;
+		const canPlay = canAutoPlay(video);
+		if (isVisible) {
+			if (autoPlay && canPlay && video.paused) video.play().catch(() => {});
+		} else {
+			if (pauseOnExit && !video.paused) video.pause();
+			if (resetOnExit) video.currentTime = 0;
+		}
+	}, [
+		isVisible,
+		autoPlay,
+		pauseOnExit,
+		resetOnExit
+	]);
+	React.useEffect(() => {
+		const video = videoRef.current;
+		if (!video) return;
+		const onPlay = () => setIsPlaying(true);
+		const onPause = () => setIsPlaying(false);
+		video.addEventListener("play", onPlay);
+		video.addEventListener("pause", onPause);
+		return () => {
+			video.removeEventListener("play", onPlay);
+			video.removeEventListener("pause", onPause);
+		};
+	}, []);
+	const play = React.useCallback(async () => {
+		if (!videoRef.current) return;
+		await safePlay(videoRef.current);
+	}, []);
+	const pause = React.useCallback(() => {
+		videoRef.current?.pause();
+	}, []);
+	const stop = React.useCallback(() => {
+		const video = videoRef.current;
+		if (!video) return;
+		video.pause();
+		video.currentTime = 0;
+	}, []);
+	return {
+		isPlaying,
+		isVisible,
+		pause,
+		play,
+		reset: React.useCallback(() => {
+			if (videoRef.current) videoRef.current.currentTime = 0;
+		}, []),
+		stop,
+		videoRef
+	};
+}
+async function safePlay(video) {
+	try {
+		await video.play();
+		return true;
+	} catch {
+		return false;
+	}
+}
+function canAutoPlay(video) {
+	return video.muted && video.playsInline;
+}
+
+//#endregion
+export { useSmartVideo };

package/dist/useSpeech.d.ts

@@ -0,0 +1,74 @@
+//#region src/useSpeech.d.ts
+interface SpeechRecognition extends EventTarget {
+  abort(): void;
+  continuous: boolean;
+  interimResults: boolean;
+  lang: string;
+  onend: ((this: SpeechRecognition, ev: Event) => unknown) | null;
+  onerror: ((this: SpeechRecognition, ev: SpeechRecognitionErrorEvent) => unknown) | null;
+  onresult: ((this: SpeechRecognition, ev: SpeechRecognitionEvent) => unknown) | null;
+  start(): void;
+  stop(): void;
+}
+interface SpeechRecognitionEvent extends Event {
+  readonly resultIndex: number;
+  readonly results: SpeechRecognitionResultList;
+}
+interface SpeechRecognitionResultList {
+  [index: number]: SpeechRecognitionResult;
+  item(index: number): SpeechRecognitionResult;
+  readonly length: number;
+}
+interface SpeechRecognitionResult {
+  [index: number]: SpeechRecognitionAlternative;
+  readonly isFinal: boolean;
+  item(index: number): SpeechRecognitionAlternative;
+  readonly length: number;
+}
+interface SpeechRecognitionAlternative {
+  readonly confidence: number;
+  readonly transcript: string;
+}
+interface SpeechRecognitionErrorEvent extends Event {
+  readonly error: string;
+  readonly message?: string;
+}
+interface SpeechRecognitionConstructor {
+  new (): SpeechRecognition;
+}
+declare global {
+  interface Window {
+    SpeechRecognition?: SpeechRecognitionConstructor;
+    webkitSpeechRecognition?: SpeechRecognitionConstructor;
+  }
+}
+type SpeechStatus = 'idle' | 'listening' | 'stopped' | 'unsupported' | 'error';
+interface UseSpeechOptions {
+  continuous?: boolean;
+  interimResults?: boolean;
+  lang?: string;
+}
+interface UseSpeechReturn {
+  error: Error | null;
+  finalTranscript: string;
+  interimTranscript: string;
+  reset: () => void;
+  start: () => void;
+  status: SpeechStatus;
+  stop: () => void;
+  transcript: string;
+}
+/**
+ * `useSpeech` is a React hook that provides unopinionated access to the Speech API.
+ *
+ * @example
+ * ```tsx
+ * const speech = useSpeech({ lang: 'en-US' });
+ * speech.start();
+ * ```
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Web_Speech_API
+ *
+ */
+declare function useSpeech(options?: UseSpeechOptions): UseSpeechReturn;
+//#endregion
+export { useSpeech };

package/dist/useSpeech.js

@@ -0,0 +1,156 @@
+import * as React from "react";
+
+//#region src/useSpeech.ts
+function isChrome() {
+	if (typeof navigator === "undefined") return false;
+	const ua = navigator.userAgent;
+	const isChromium = ua.includes("Chrome");
+	const isEdge = ua.includes("Edg");
+	const isBrave = typeof navigator.brave === "object";
+	return isChromium && !isEdge && !isBrave;
+}
+/**
+* `useSpeech` is a React hook that provides unopinionated access to the Speech API.
+*
+* @example
+* ```tsx
+* const speech = useSpeech({ lang: 'en-US' });
+* speech.start();
+* ```
+* @see https://developer.mozilla.org/en-US/docs/Web/API/Web_Speech_API
+*
+*/
+function useSpeech(options = {}) {
+	const isClient = typeof window !== "undefined";
+	const isChromeBrowser = React.useMemo(() => isChrome(), []);
+	const recognitionRef = React.useRef(null);
+	const isManuallyStoppedRef = React.useRef(false);
+	const shouldRestartRef = React.useRef(false);
+	const nextStatusRef = React.useRef(null);
+	const [status, setStatus] = React.useState("idle");
+	const [error, setError] = React.useState(null);
+	const [finalTranscript, setFinalTranscript] = React.useState("");
+	const [interimTranscript, setInterimTranscript] = React.useState("");
+	const initializeRecognition = React.useCallback(() => {
+		if (!isClient) return;
+		if (!isChromeBrowser) {
+			setStatus("unsupported");
+			return;
+		}
+		const SpeechRecognitionCtor = window.SpeechRecognition ?? window.webkitSpeechRecognition;
+		if (!SpeechRecognitionCtor) {
+			setStatus("unsupported");
+			return;
+		}
+		const recognition = new SpeechRecognitionCtor();
+		recognition.lang = options.lang ?? "en-US";
+		recognition.continuous = options.continuous ?? true;
+		recognition.interimResults = options.interimResults ?? true;
+		recognition.onresult = (event) => {
+			let interim = "";
+			let final = "";
+			for (let i = event.resultIndex; i < event.results.length; i++) {
+				const result = event.results[i];
+				const text = result?.[0]?.transcript ?? "";
+				if (result?.isFinal) final += text + " ";
+				else interim += text;
+			}
+			if (interim) setInterimTranscript(interim);
+			if (final) {
+				setFinalTranscript((prev) => prev + final);
+				setInterimTranscript("");
+			}
+		};
+		recognition.onerror = (event) => {
+			if (isManuallyStoppedRef.current) return;
+			if (event.error === "no-speech") {
+				console.warn("No se detectó voz.");
+				shouldRestartRef.current = true;
+				return;
+			}
+			if (event.error === "aborted") return;
+			setError(new Error(event.error));
+			setStatus("error");
+		};
+		recognition.onend = () => {
+			if (isManuallyStoppedRef.current) {
+				isManuallyStoppedRef.current = false;
+				setStatus(nextStatusRef.current ?? "stopped");
+				return;
+			}
+			if (status === "error") return;
+			if (shouldRestartRef.current) {
+				try {
+					recognition.start();
+					setStatus("listening");
+				} catch (err) {
+					console.error("Error al reiniciar reconocimiento:", err);
+					setError(err instanceof Error ? err : /* @__PURE__ */ new Error("Failed to restart"));
+					setStatus("error");
+					shouldRestartRef.current = false;
+				}
+				return;
+			}
+			setStatus("stopped");
+		};
+		recognitionRef.current = recognition;
+	}, [
+		isClient,
+		options.lang,
+		options.continuous,
+		options.interimResults
+	]);
+	const start = React.useCallback(() => {
+		if (!recognitionRef.current) initializeRecognition();
+		const recognition = recognitionRef.current;
+		if (!recognition) return;
+		try {
+			isManuallyStoppedRef.current = false;
+			shouldRestartRef.current = true;
+			recognition.start();
+			setStatus("listening");
+			setError(null);
+		} catch (err) {
+			console.error("Error al iniciar reconocimiento:", err);
+			setError(err instanceof Error ? err : /* @__PURE__ */ new Error("Failed to start"));
+			setStatus("error");
+		}
+	}, [initializeRecognition]);
+	const stop = React.useCallback(() => {
+		isManuallyStoppedRef.current = true;
+		shouldRestartRef.current = false;
+		if (recognitionRef.current) recognitionRef.current.stop();
+	}, []);
+	const reset = React.useCallback(() => {
+		nextStatusRef.current = "idle";
+		stop();
+		setFinalTranscript("");
+		setInterimTranscript("");
+		setError(null);
+	}, [stop]);
+	const transcript = React.useMemo(() => `${finalTranscript}${interimTranscript}`.trim(), [finalTranscript, interimTranscript]);
+	React.useEffect(() => {
+		initializeRecognition();
+		return () => {
+			isManuallyStoppedRef.current = true;
+			shouldRestartRef.current = false;
+			if (recognitionRef.current) {
+				recognitionRef.current.stop();
+				recognitionRef.current = null;
+			}
+		};
+	}, [initializeRecognition]);
+	return {
+		error,
+		finalTranscript: finalTranscript.trim(),
+		interimTranscript,
+		reset,
+		start,
+		status,
+		stop,
+		transcript
+	};
+}
+
+//#endregion
+export { useSpeech };