@vibehooks/react 0.0.1

package/dist/useIntersectionObserver.d.ts

@@ -0,0 +1,45 @@
+import * as React from "react";
+
+//#region src/useIntersectionObserver.d.ts
+type IntersectionObserverOptions = IntersectionObserverInit & {
+  /**
+   * If true, the observer disconnects after the first intersection.
+   */
+  once?: boolean;
+  /**
+   * Callback that executes every time the IntersectionObserverEntry changes.
+   */
+  onChange?: (entry: IntersectionObserverEntry) => void;
+};
+interface IntersectionObserverReturn<T extends Element> {
+  /**
+   * Last IntersectionObserverEntry.
+   */
+  entry: IntersectionObserverEntry | null;
+  /**
+   * Indicates if the element is visible in the viewport.
+   */
+  isVisible: boolean;
+  /**
+   * Ref will be assigned to the element that is being observed.
+   */
+  ref: React.RefObject<T | null>;
+}
+/**
+ * `useIntersectionObserver` observers the visibility of an element using the native IntersectionObserver API.
+ * Returns a typed `ref` that must be assigned to the element you want to observe.
+ *
+ * @example
+ * ```tsx
+ * const { ref, isVisible } = useIntersectionObserver<HTMLDivElement>({
+ *  threshold: 0.5,
+ *  once: true,
+ * });
+ *
+ * return <div ref={ref}>{isVisible}</div>;
+ * ```
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API
+ */
+declare function useIntersectionObserver<T extends Element = HTMLElement>(options?: IntersectionObserverOptions, externalRef?: React.RefObject<T | null>): IntersectionObserverReturn<T>;
+//#endregion
+export { useIntersectionObserver };

package/dist/useIntersectionObserver.js

@@ -0,0 +1,70 @@
+import * as React from "react";
+
+//#region src/useIntersectionObserver.ts
+/**
+* `useIntersectionObserver` observers the visibility of an element using the native IntersectionObserver API.
+* Returns a typed `ref` that must be assigned to the element you want to observe.
+*
+* @example
+* ```tsx
+* const { ref, isVisible } = useIntersectionObserver<HTMLDivElement>({
+*  threshold: 0.5,
+*  once: true,
+* });
+*
+* return <div ref={ref}>{isVisible}</div>;
+* ```
+* @see https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API
+*/
+function useIntersectionObserver(options, externalRef) {
+	const internalRef = React.useRef(null);
+	const ref = externalRef ?? internalRef;
+	const [entry, setEntry] = React.useState(null);
+	const [isVisible, setIsVisible] = React.useState(false);
+	const callbackRef = React.useRef(options?.onChange);
+	callbackRef.current = options?.onChange;
+	const observerOptions = React.useMemo(() => {
+		return {
+			root: options?.root,
+			rootMargin: options?.rootMargin,
+			threshold: options?.threshold
+		};
+	}, [
+		options?.root,
+		options?.rootMargin,
+		options?.threshold
+	]);
+	const once = options?.once;
+	const onceRef = React.useRef(false);
+	React.useEffect(() => {
+		if (typeof window === "undefined") return;
+		const element = ref.current;
+		if (!element) return;
+		const observer = new IntersectionObserver((entries, observer$1) => {
+			const firstEntry = entries[0];
+			if (!firstEntry) return;
+			setEntry(firstEntry);
+			setIsVisible(firstEntry.isIntersecting);
+			callbackRef.current?.(firstEntry);
+			if (once && firstEntry.isIntersecting && !onceRef.current) {
+				onceRef.current = true;
+				observer$1.unobserve(element);
+				observer$1.disconnect();
+			}
+		}, observerOptions);
+		observer.observe(element);
+		return () => observer.disconnect();
+	}, [
+		observerOptions,
+		ref,
+		once
+	]);
+	return {
+		entry,
+		isVisible,
+		ref
+	};
+}
+
+//#endregion
+export { useIntersectionObserver };

package/dist/useIntervalSafe.d.ts

@@ -0,0 +1,72 @@
+//#region src/useIntervalSafe.d.ts
+interface UseIntervalOptions {
+  /**
+   * Delay in milliseconds between each interval execution.
+   * If null or undefined, the interval won't be set.
+   */
+  delay: number | null;
+  /**
+   * Maximum number of times to execute the callback.
+   * If undefined, runs indefinitely until cancelled.
+   */
+  maxExecutions?: number;
+  /**
+   * Whether the interval should start immediately on mount.
+   * @default true
+   */
+  startOnMount?: boolean;
+}
+interface UseIntervalReturn {
+  /**
+   * Cancel the running interval.
+   */
+  cancel: () => void;
+  /**
+   * Number of times the callback has been executed.
+   */
+  executionCount: number;
+  /**
+   * Whether the interval is currently active.
+   */
+  isActive: boolean;
+  /**
+   * Reset the interval (cancel and start again, resetting execution count).
+   */
+  reset: () => void;
+  /**
+   * Start or restart the interval.
+   */
+  start: () => void;
+}
+/**
+ * `useInterval` is a custom hook for managing intervals in a declarative way. It's server safe and unopinionated about when/how to trigger the interval.
+ *
+ * @example
+ * ```tsx
+ * // Auto-start interval
+ * const interval = useInterval(() => {
+ *   console.log('Executed every 1 second');
+ * }, { delay: 1000 });
+ *
+ * // Manual control with execution limit
+ * const interval = useInterval(
+ *   () => fetchData(),
+ *   {
+ *     delay: 5000,
+ *     startOnMount: false,
+ *     maxExecutions: 10
+ *   }
+ * );
+ *
+ * <button onClick={interval.start}>Start Polling</button>
+ * <button onClick={interval.cancel}>Stop</button>
+ * <span>Polled {interval.executionCount} times</span>
+ * ```
+ */
+declare function useIntervalSafe(callback: () => void, {
+  delay,
+  maxExecutions,
+  startOnMount
+}: UseIntervalOptions): UseIntervalReturn;
+//#endregion
+export { useIntervalSafe };

package/dist/useIntervalSafe.js

@@ -0,0 +1,85 @@
+import * as React from "react";
+
+//#region src/useIntervalSafe.ts
+/**
+* `useInterval` is a custom hook for managing intervals in a declarative way. It's server safe and unopinionated about when/how to trigger the interval.
+*
+* @example
+* ```tsx
+* // Auto-start interval
+* const interval = useInterval(() => {
+*   console.log('Executed every 1 second');
+* }, { delay: 1000 });
+*
+* // Manual control with execution limit
+* const interval = useInterval(
+*   () => fetchData(),
+*   {
+*     delay: 5000,
+*     startOnMount: false,
+*     maxExecutions: 10
+*   }
+* );
+*
+* <button onClick={interval.start}>Start Polling</button>
+* <button onClick={interval.cancel}>Stop</button>
+* <span>Polled {interval.executionCount} times</span>
+* ```
+*/
+function useIntervalSafe(callback, { delay, maxExecutions, startOnMount = true }) {
+	const intervalRef = React.useRef(null);
+	const callbackRef = React.useRef(callback);
+	const executionsRef = React.useRef(0);
+	const [isActive, setIsActive] = React.useState(false);
+	const [executions, setExecutions] = React.useState(0);
+	React.useEffect(() => {
+		callbackRef.current = callback;
+	}, [callback]);
+	const cancel = React.useCallback(() => {
+		if (intervalRef.current) {
+			clearInterval(intervalRef.current);
+			intervalRef.current = null;
+		}
+		setIsActive(false);
+	}, []);
+	const tick = React.useCallback(() => {
+		if (maxExecutions !== void 0 && executionsRef.current >= maxExecutions) {
+			cancel();
+			return;
+		}
+		callbackRef.current();
+		executionsRef.current += 1;
+		setExecutions(executionsRef.current);
+		if (maxExecutions !== void 0 && executionsRef.current >= maxExecutions) cancel();
+	}, [cancel, maxExecutions]);
+	const start = React.useCallback(() => {
+		if (delay == null || intervalRef.current) return;
+		executionsRef.current = 0;
+		setExecutions(0);
+		setIsActive(true);
+		intervalRef.current = setInterval(tick, delay);
+	}, [
+		delay,
+		maxExecutions,
+		tick
+	]);
+	const reset = React.useCallback(() => {
+		cancel();
+		start();
+	}, [cancel, start]);
+	React.useEffect(() => {
+		if (!startOnMount) return;
+		start();
+		return cancel;
+	}, [startOnMount]);
+	return {
+		cancel,
+		executionCount: executions,
+		isActive,
+		reset,
+		start
+	};
+}
+
+//#endregion
+export { useIntervalSafe };

package/dist/useIsClient.d.ts

@@ -0,0 +1,12 @@
+//#region src/useIsClient.d.ts
+/**
+ * `useIsClient` returns true if the code is running in the browser. Otherwise, it returns false if the code is running on the server.
+ *
+ * @example
+ * ```tsx
+ * const isClient = useIsClient();
+ * ```
+ */
+declare function useIsClient(): boolean;
+//#endregion
+export { useIsClient };

package/dist/useIsClient.js

@@ -0,0 +1,21 @@
+import * as React from "react";
+
+//#region src/useIsClient.ts
+/**
+* `useIsClient` returns true if the code is running in the browser. Otherwise, it returns false if the code is running on the server.
+*
+* @example
+* ```tsx
+* const isClient = useIsClient();
+* ```
+*/
+function useIsClient() {
+	const [isClient, setIsClient] = React.useState(false);
+	React.useEffect(() => {
+		setIsClient(true);
+	}, []);
+	return isClient;
+}
+
+//#endregion
+export { useIsClient };

package/dist/useIsDesktop.d.ts

@@ -0,0 +1,12 @@
+//#region src/useIsDesktop.d.ts
+/**
+ * `useIsDesktop` returns true if the screen size is greater than or equal to the given width.
+ *
+ * @example
+ * ```tsx
+ * const isDesktop = useIsDesktop(1000);
+ * ```
+ */
+declare function useIsDesktop(width?: number): boolean;
+//#endregion
+export { useIsDesktop };

package/dist/useIsDesktop.js

@@ -0,0 +1,23 @@
+import { useScreenSize } from "./useScreenSize.js";
+import * as React from "react";
+
+//#region src/useIsDesktop.ts
+/**
+* `useIsDesktop` returns true if the screen size is greater than or equal to the given width.
+*
+* @example
+* ```tsx
+* const isDesktop = useIsDesktop(1000);
+* ```
+*/
+function useIsDesktop(width = 0) {
+	const screenSize = useScreenSize();
+	const [isDesktop, setIsDesktop] = React.useState(false);
+	React.useEffect(() => {
+		setIsDesktop(screenSize.width >= width);
+	}, [screenSize.width, width]);
+	return isDesktop;
+}
+
+//#endregion
+export { useIsDesktop };

package/dist/useIsFirstRender.d.ts

@@ -0,0 +1,12 @@
+//#region src/useIsFirstRender.d.ts
+/**
+ * `useIsFirstRender` returns true if the component is the first render.
+ *
+ * @example
+ * ```tsx
+ * const isFirstRender = useIsFirstRender();
+ * ```
+ */
+declare function useIsFirstRender(): boolean;
+//#endregion
+export { useIsFirstRender };

package/dist/useIsFirstRender.js

@@ -0,0 +1,21 @@
+import * as React from "react";
+
+//#region src/useIsFirstRender.ts
+/**
+* `useIsFirstRender` returns true if the component is the first render.
+*
+* @example
+* ```tsx
+* const isFirstRender = useIsFirstRender();
+* ```
+*/
+function useIsFirstRender() {
+	const [isFirst, setIsFirst] = React.useState(true);
+	React.useEffect(() => {
+		setIsFirst(false);
+	}, []);
+	return isFirst;
+}
+
+//#endregion
+export { useIsFirstRender };

package/dist/useList.d.ts

@@ -0,0 +1,19 @@
+//#region src/useList.d.ts
+interface ListReturn<T> {
+  insert: (idx: number, item: T) => void;
+  items: T[];
+  push: (item: T) => void;
+  remove: (idx: number) => void;
+  update: (idx: number, item: T) => void;
+}
+/**
+ * `useList` is a custom hook that allows you to create, update, and delete items in a list.
+ *
+ * @example
+ * ```tsx
+ * const { items, insert, push, remove, update } = useList<string>(['item1', 'item2']);
+ * ```
+ */
+declare function useList<T>(defaultValue?: T[]): ListReturn<T>;
+//#endregion
+export { useList };

package/dist/useList.js

@@ -0,0 +1,44 @@
+import * as React from "react";
+
+//#region src/useList.ts
+/**
+* `useList` is a custom hook that allows you to create, update, and delete items in a list.
+*
+* @example
+* ```tsx
+* const { items, insert, push, remove, update } = useList<string>(['item1', 'item2']);
+* ```
+*/
+function useList(defaultValue = []) {
+	const [items, setItems] = React.useState(defaultValue || []);
+	return {
+		insert: React.useCallback((idx, item) => {
+			setItems((prevItems) => {
+				const copy = [...prevItems];
+				copy.splice(idx, 0, item);
+				return copy;
+			});
+		}, []),
+		items,
+		push: React.useCallback((item) => {
+			setItems((prevItems) => [...prevItems, item]);
+		}, []),
+		remove: React.useCallback((idx) => {
+			setItems((prevItems) => {
+				const copy = [...prevItems];
+				copy.splice(idx, 1);
+				return copy;
+			});
+		}, []),
+		update: React.useCallback((idx, item) => {
+			setItems((prevItems) => {
+				const copy = [...prevItems];
+				copy[idx] = item;
+				return copy;
+			});
+		}, [])
+	};
+}
+
+//#endregion
+export { useList };

package/dist/useLocalNotifications.d.ts

@@ -0,0 +1,23 @@
+//#region src/useLocalNotifications.d.ts
+interface UseLocalNotificationReturn {
+  isSupported: boolean;
+  notify: (options: UseNotificationOptions) => void;
+  permission: NotificationPermission;
+  requestPermission: () => Promise<NotificationPermission>;
+}
+interface UseNotificationOptions extends NotificationOptions {
+  title: string;
+}
+/**
+ * `useLocalNotifications` is React hook for managing local notifications in the browser.
+ *
+ * @example
+ * ```tsx
+ * const { notify, requestPermission, permission } = useNotifications();
+ * notify({ title: 'Hello', body: 'World' });
+ * ```
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Notification
+ */
+declare function useLocalNotifications(): UseLocalNotificationReturn;
+//#endregion
+export { useLocalNotifications };

package/dist/useLocalNotifications.js

@@ -0,0 +1,50 @@
+import * as React from "react";
+
+//#region src/useLocalNotifications.ts
+/**
+* `useLocalNotifications` is React hook for managing local notifications in the browser.
+*
+* @example
+* ```tsx
+* const { notify, requestPermission, permission } = useNotifications();
+* notify({ title: 'Hello', body: 'World' });
+* ```
+* @see https://developer.mozilla.org/en-US/docs/Web/API/Notification
+*/
+function useLocalNotifications() {
+	const [permission, setPermission] = React.useState(typeof window !== "undefined" && "Notification" in window ? Notification.permission : "default");
+	const isSupported = typeof window !== "undefined" && "Notification" in window;
+	const requestPermission = React.useCallback(async () => {
+		if (!isSupported) return "denied";
+		const result = await Notification.requestPermission();
+		setPermission(result);
+		return result;
+	}, [isSupported]);
+	return {
+		isSupported,
+		notify: React.useCallback(({ badge, body, data, dir, icon, lang, requireInteraction, silent, tag, title }) => {
+			if (!isSupported) return;
+			if (permission !== "granted") {
+				console.warn("Notifications are not allowed.");
+				return;
+			}
+			const options = {
+				...badge !== void 0 && { badge },
+				...body !== void 0 && { body },
+				...data !== void 0 && { data },
+				...dir !== void 0 && { dir },
+				...icon !== void 0 && { icon },
+				...lang !== void 0 && { lang },
+				...requireInteraction !== void 0 && { requireInteraction },
+				...silent !== void 0 && { silent },
+				...tag !== void 0 && { tag }
+			};
+			new Notification(title, options);
+		}, [permission, isSupported]),
+		permission,
+		requestPermission
+	};
+}
+
+//#endregion
+export { useLocalNotifications };

package/dist/useLocalStorage.d.ts

@@ -0,0 +1,45 @@
+//#region src/useLocalStorage.d.ts
+interface UseLocalStorageOptions<T> {
+  /**
+   * Fallback value returned when the key does not exist or parsing fails.
+   */
+  fallback: T;
+}
+interface UseLocalStorageReturn<T> {
+  /**
+   * Removes the key from localStorage.
+   */
+  remove(): void;
+  /**
+   * Serializes and stores a value in localStorage.
+   */
+  set(value: T): void;
+  /**
+   * Updates the stored value using a functional updater.
+   */
+  update(updater: (prev: T | null) => T): void;
+  /**
+   * The current value of the key.
+   */
+  value: T;
+}
+/**
+ * `useLocalStorage` is a React hook that provides a typed, unopinionated API for interacting with `window.localStorage`.
+ *
+ * @example
+ * ```tsx
+ * const storage = useLocalStorage<User>('user', {
+ *   fallback: null,
+ * });
+ *
+ * const saveUser = () => {
+ *   storage.set({ id: '1', name: 'Sebas' });
+ * };
+ *
+ * const user = storage.get();
+ * ```
+ * @see https://developer.mozilla.org/es/docs/Web/API/Window/localStorage
+ */
+declare function useLocalStorage<T>(key: string, options: UseLocalStorageOptions<T>): UseLocalStorageReturn<T>;
+//#endregion
+export { useLocalStorage };

package/dist/useLocalStorage.js

@@ -0,0 +1,71 @@
+import * as React from "react";
+
+//#region src/useLocalStorage.ts
+const listeners = /* @__PURE__ */ new Set();
+const cache = /* @__PURE__ */ new Map();
+function emit() {
+	listeners.forEach((listener) => listener());
+}
+function subscribe(listener) {
+	listeners.add(listener);
+	return () => {
+		listeners.delete(listener);
+	};
+}
+function readFromStorage(key, fallback) {
+	if (typeof window === "undefined") return fallback;
+	try {
+		const raw = window.localStorage.getItem(key);
+		return raw === null ? fallback : JSON.parse(raw);
+	} catch {
+		return fallback;
+	}
+}
+/**
+* `useLocalStorage` is a React hook that provides a typed, unopinionated API for interacting with `window.localStorage`.
+*
+* @example
+* ```tsx
+* const storage = useLocalStorage<User>('user', {
+*   fallback: null,
+* });
+*
+* const saveUser = () => {
+*   storage.set({ id: '1', name: 'Sebas' });
+* };
+*
+* const user = storage.get();
+* ```
+* @see https://developer.mozilla.org/es/docs/Web/API/Window/localStorage
+*/
+function useLocalStorage(key, options) {
+	const { fallback } = options;
+	const getSnapshot = React.useCallback(() => {
+		if (!cache.has(key)) cache.set(key, readFromStorage(key, fallback));
+		return cache.get(key);
+	}, [key, fallback]);
+	const value = React.useSyncExternalStore(subscribe, getSnapshot, () => fallback);
+	const set = React.useCallback((next) => {
+		if (typeof window === "undefined") return;
+		cache.set(key, next);
+		window.localStorage.setItem(key, JSON.stringify(next));
+		emit();
+	}, [key]);
+	const update = React.useCallback((updater) => {
+		set(updater(value));
+	}, [value, set]);
+	return {
+		remove: React.useCallback(() => {
+			if (typeof window === "undefined") return;
+			cache.delete(key);
+			window.localStorage.removeItem(key);
+			emit();
+		}, [key]),
+		set,
+		update,
+		value
+	};
+}
+
+//#endregion
+export { useLocalStorage };