@vibehooks/react 0.0.1

package/dist/useSummarizer.d.ts

@@ -0,0 +1,92 @@
+//#region src/useSummarizer.d.ts
+type SummarizerAvailability = 'available' | 'unavailable' | 'downloadable';
+type SummarizerType = 'tldr' | 'key-points' | 'headline' | 'paragraph';
+type SummarizerFormat = 'plain-text' | 'markdown';
+type SummarizerLength = 'short' | 'medium' | 'long';
+interface SummarizerCreateOptions {
+  format?: SummarizerFormat;
+  inputLanguage?: string;
+  length?: SummarizerLength;
+  outputLanguage?: string;
+  signal?: AbortSignal;
+  type?: SummarizerType;
+}
+interface BrowserSummarizer {
+  destroy(): void;
+  summarize(text: string, options?: {
+    signal?: AbortSignal;
+  }): Promise<string>;
+}
+interface SummarizerStatic {
+  availability(options?: SummarizerCreateOptions): Promise<SummarizerAvailability>;
+  create(options?: SummarizerCreateOptions): Promise<BrowserSummarizer>;
+}
+declare global {
+  interface Window {
+    Summarizer: SummarizerStatic;
+  }
+}
+interface UseSummarizerReturn {
+  /**
+   * Cancels any pending create or summarize operation.
+   */
+  cancel(): void;
+  /**
+   * Checks whether the browser AI model can satisfy the given options.
+   */
+  checkAvailability(options?: SummarizerCreateOptions): Promise<SummarizerAvailability>;
+  /**
+   * Creates a Summarizer instance with the given options.
+   * Requires recent user interaction to be triggered.
+   */
+  create(options?: SummarizerCreateOptions): Promise<void>;
+  /**
+   * Destroys the active Summarizer instance.
+   */
+  destroy(): void;
+  /**
+   * Checks if the provided error is an AbortError.
+   */
+  isAbortError(error: unknown): boolean;
+  /**
+   * Indicates whether the Summarizer API exists in the current environment.
+   */
+  isSupported: boolean;
+  /**
+   * Runs a sumamrization request using the active Summarizer instance.
+   */
+  summarize(text: string): Promise<string>;
+}
+/**
+ * `useSummarizer` is React hook that provides low-level access to the browser Summarizer API.
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   isSupported,
+ *   checkAvailability,
+ *   create,
+ *   summarize,
+ *   destroy,
+ * } = useSummarizer();
+ *
+ * const run = async () => {
+ *   const availability = await checkAvailability({
+ *     type: 'tldr',
+ *     format: 'markdown',
+ *   });
+ *
+ *   if (availability !== 'available') return;
+ *
+ *   await create({ type: 'tldr' });
+ *   const summary = await summarize(longText);
+ *
+ *   console.log(summary);
+ *   destroy();
+ * };
+ * ```
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Summarizer_API
+ */
+declare function useSummarizer(): UseSummarizerReturn;
+//#endregion
+export { useSummarizer };

package/dist/useSummarizer.js

@@ -0,0 +1,83 @@
+import * as React from "react";
+
+//#region src/useSummarizer.ts
+function isAbortError(error) {
+	return error instanceof DOMException && error.name === "AbortError";
+}
+/**
+* `useSummarizer` is React hook that provides low-level access to the browser Summarizer API.
+*
+* @example
+* ```tsx
+* const {
+*   isSupported,
+*   checkAvailability,
+*   create,
+*   summarize,
+*   destroy,
+* } = useSummarizer();
+*
+* const run = async () => {
+*   const availability = await checkAvailability({
+*     type: 'tldr',
+*     format: 'markdown',
+*   });
+*
+*   if (availability !== 'available') return;
+*
+*   await create({ type: 'tldr' });
+*   const summary = await summarize(longText);
+*
+*   console.log(summary);
+*   destroy();
+* };
+* ```
+* @see https://developer.mozilla.org/en-US/docs/Web/API/Summarizer_API
+*/
+function useSummarizer() {
+	const summarizerRef = React.useRef(null);
+	const abortRef = React.useRef(null);
+	const isSupported = typeof window !== "undefined" && typeof window.Summarizer !== "undefined";
+	const checkAvailability = React.useCallback(async (options) => {
+		if (!isSupported) return "unavailable";
+		return window.Summarizer.availability(options);
+	}, [isSupported]);
+	const create = React.useCallback(async (options) => {
+		if (!isSupported) throw new Error("Summarizer API not supported.");
+		abortRef.current?.abort();
+		abortRef.current = new AbortController();
+		summarizerRef.current = await window.Summarizer.create({ ...options });
+	}, [isSupported]);
+	const summarize = React.useCallback(async (text) => {
+		if (!summarizerRef.current) throw new Error("Summarizer instance not created.");
+		if (!abortRef.current) abortRef.current = new AbortController();
+		try {
+			return await summarizerRef.current.summarize(text, { signal: abortRef.current.signal });
+		} catch (err) {
+			if (isAbortError(err)) return Promise.reject(err);
+			throw err;
+		}
+	}, []);
+	const cancel = React.useCallback(() => {
+		if (abortRef.current) {
+			abortRef.current?.abort();
+			abortRef.current = null;
+		}
+	}, []);
+	return {
+		cancel,
+		checkAvailability,
+		create,
+		destroy: React.useCallback(() => {
+			summarizerRef.current?.destroy();
+			summarizerRef.current = null;
+			cancel();
+		}, [cancel]),
+		isAbortError,
+		isSupported,
+		summarize
+	};
+}
+
+//#endregion
+export { useSummarizer };

package/dist/useTaskQueue.d.ts

@@ -0,0 +1,25 @@
+//#region src/useTaskQueue.d.ts
+interface Task<T = unknown> {
+  id: string;
+  run: () => Promise<T>;
+}
+interface UseTaskQueueReturn<T = unknown> {
+  enqueue: (task: Task<T>) => void;
+  queue: Task<T>[];
+  running: boolean;
+}
+/**
+ * `useTaskQueue` is a React hook that manages a queue of async tasks with concurrency control.
+ *
+ * @example
+ * ```tsx
+ * const { enqueue, running, queue } = useTaskQueue();
+ *
+ * React.useEffect(() => {
+ *   enqueue({ id: 'task1', run: async () => console.log('Task 1') });
+ * }, []);
+ * ```
+ */
+declare function useTaskQueue<T = unknown>(): UseTaskQueueReturn<T>;
+//#endregion
+export { useTaskQueue };

package/dist/useTaskQueue.js

@@ -0,0 +1,51 @@
+import * as React from "react";
+
+//#region src/useTaskQueue.ts
+/**
+* `useTaskQueue` is a React hook that manages a queue of async tasks with concurrency control.
+*
+* @example
+* ```tsx
+* const { enqueue, running, queue } = useTaskQueue();
+*
+* React.useEffect(() => {
+*   enqueue({ id: 'task1', run: async () => console.log('Task 1') });
+* }, []);
+* ```
+*/
+function useTaskQueue() {
+	const [queue, setQueue] = React.useState([]);
+	const [running, setRunning] = React.useState(false);
+	const isProcessingRef = React.useRef(false);
+	React.useEffect(() => {
+		if (queue.length === 0) {
+			setRunning(false);
+			return;
+		}
+		if (isProcessingRef.current) return;
+		isProcessingRef.current = true;
+		const task = queue[0];
+		setRunning(true);
+		const run = async () => {
+			try {
+				await task?.run();
+			} catch (error) {
+				console.error(error);
+			} finally {
+				isProcessingRef.current = false;
+				setQueue((prev) => prev.slice(1));
+			}
+		};
+		run();
+	}, [queue]);
+	return {
+		enqueue: React.useCallback((task) => {
+			setQueue((prev) => [...prev, task]);
+		}, []),
+		queue,
+		running
+	};
+}
+
+//#endregion
+export { useTaskQueue };

package/dist/useThrottledCallback.d.ts

@@ -0,0 +1,32 @@
+//#region src/useThrottledCallback.d.ts
+interface UseThrottledCallbackOptions {
+  /**
+   * Minimum time in milliseconds between callback executions.
+   */
+  delay: number;
+}
+type ThrottledCallbackReturn<TArgs extends readonly unknown[]> = (...args: TArgs) => void;
+/**
+ * `useThrottledCallback` is a React hook that returns a throttled version of a callback.
+ * The throttled callback will execute at most once every `delay` milliseconds, regardless of how many times it is invoked.
+ *
+ * @example
+ * ```tsx
+ * * const onScroll = useThrottledCallback(
+ *   (y: number) => {
+ *     console.log(y);
+ *   },
+ *   { delay: 200 }
+ * );
+ *
+ * React.useEffect(() => {
+ *   const handler = () => onScroll(window.scrollY);
+ *   window.addEventListener('scroll', handler);
+ *
+ *   return () => window.removeEventListener('scroll', handler);
+ * }, [onScroll]);
+ * ```
+ */
+declare function useThrottledCallback<TArgs extends readonly unknown[]>(callback: (...args: TArgs) => void, options: UseThrottledCallbackOptions): ThrottledCallbackReturn<TArgs>;
+//#endregion
+export { useThrottledCallback };

package/dist/useThrottledCallback.js

@@ -0,0 +1,42 @@
+import * as React from "react";
+
+//#region src/useThrottledCallback.ts
+/**
+* `useThrottledCallback` is a React hook that returns a throttled version of a callback.
+* The throttled callback will execute at most once every `delay` milliseconds, regardless of how many times it is invoked.
+*
+* @example
+* ```tsx
+* * const onScroll = useThrottledCallback(
+*   (y: number) => {
+*     console.log(y);
+*   },
+*   { delay: 200 }
+* );
+*
+* React.useEffect(() => {
+*   const handler = () => onScroll(window.scrollY);
+*   window.addEventListener('scroll', handler);
+*
+*   return () => window.removeEventListener('scroll', handler);
+* }, [onScroll]);
+* ```
+*/
+function useThrottledCallback(callback, options) {
+	const { delay } = options;
+	const lastCallRef = React.useRef(0);
+	const callbackRef = React.useRef(callback);
+	React.useEffect(() => {
+		callbackRef.current = callback;
+	}, [callback]);
+	return React.useCallback((...args) => {
+		const now = Date.now();
+		if (now - lastCallRef.current >= delay) {
+			lastCallRef.current = now;
+			callbackRef.current(...args);
+		}
+	}, [delay]);
+}
+
+//#endregion
+export { useThrottledCallback };

package/dist/useTimeout.d.ts

@@ -0,0 +1,58 @@
+//#region src/useTimeout.d.ts
+interface UseTimeoutOptions {
+  /**
+   * Delay in milliseconds before the callback is executed.
+   * If null or undefined, the timeout won't be set.
+   */
+  delay: number | null;
+  /**
+   * Whether the timeout should start immediately on mount.
+   * @default true
+   */
+  startOnMount?: boolean;
+}
+interface UseTimeoutReturn {
+  /**
+   * Cancel the pending timeout.
+   */
+  cancel: () => void;
+  /**
+   * Whether the timeout is currently active.
+   */
+  isActive: boolean;
+  /**
+   * Reset the timeout (cancel and start again).
+   */
+  reset: () => void;
+  /**
+   * Start or restart the timeout.
+   */
+  start: () => void;
+}
+/**
+ * `useTimeout` is a custom hook for managing timeouts in a declarative way. It's sever-safe and unopinionated about when/how to trigger the timeout.
+ *
+ * @example
+ * ```tsx
+ * // Auto-start timeout
+ * const timeout = useTimeout(() => {
+ *   console.log('Executed after 2 seconds');
+ * }, { delay: 2000 });
+ *
+ * // Manual control
+ * const timeout = useTimeout(() => {
+ *   showNotification('Session expired');
+ * }, { delay: 5000, startOnMount: false });
+ *
+ * // Start manually
+ * <button onClick={timeout.start}>Start Timer</button>
+ * <button onClick={timeout.cancel}>Cancel</button>
+ * <button onClick={timeout.reset}>Reset</button>
+ * ```
+ */
+declare function useTimeout(callback: () => void, {
+  delay,
+  startOnMount
+}: UseTimeoutOptions): UseTimeoutReturn;
+//#endregion
+export { useTimeout };

package/dist/useTimeout.js

@@ -0,0 +1,70 @@
+import * as React from "react";
+
+//#region src/useTimeout.ts
+/**
+* `useTimeout` is a custom hook for managing timeouts in a declarative way. It's sever-safe and unopinionated about when/how to trigger the timeout.
+*
+* @example
+* ```tsx
+* // Auto-start timeout
+* const timeout = useTimeout(() => {
+*   console.log('Executed after 2 seconds');
+* }, { delay: 2000 });
+*
+* // Manual control
+* const timeout = useTimeout(() => {
+*   showNotification('Session expired');
+* }, { delay: 5000, startOnMount: false });
+*
+* // Start manually
+* <button onClick={timeout.start}>Start Timer</button>
+* <button onClick={timeout.cancel}>Cancel</button>
+* <button onClick={timeout.reset}>Reset</button>
+* ```
+*/
+function useTimeout(callback, { delay, startOnMount = true }) {
+	const timeoutRef = React.useRef(null);
+	const callbackRef = React.useRef(callback);
+	const [isActive, setIsActive] = React.useState(false);
+	React.useEffect(() => {
+		callbackRef.current = callback;
+	}, [callback]);
+	const cancel = React.useCallback(() => {
+		if (timeoutRef.current !== null) {
+			clearTimeout(timeoutRef.current);
+			timeoutRef.current = null;
+			setIsActive(false);
+		}
+	}, []);
+	const start = React.useCallback(() => {
+		cancel();
+		if (delay === null || delay === void 0) return;
+		setIsActive(true);
+		timeoutRef.current = setTimeout(() => {
+			callbackRef.current();
+			timeoutRef.current = null;
+			setIsActive(false);
+		}, delay);
+	}, [delay, cancel]);
+	const reset = React.useCallback(() => {
+		cancel();
+		start();
+	}, [cancel, start]);
+	React.useEffect(() => {
+		if (startOnMount) start();
+		return cancel;
+	}, [
+		startOnMount,
+		start,
+		cancel
+	]);
+	return {
+		cancel,
+		isActive,
+		reset,
+		start
+	};
+}
+
+//#endregion
+export { useTimeout };

package/dist/useToggle.d.ts

@@ -0,0 +1,30 @@
+//#region src/useToggle.d.ts
+interface ToggleOptions {
+  /**
+   * Default value for the toggle.
+   */
+  defaultValue?: boolean;
+}
+interface ToggleReturn {
+  /**
+   * Handles the toggle.
+   */
+  handleToggle: () => void;
+  /**
+   * Current status of the toggle.
+   */
+  status: boolean;
+}
+/**
+ * `useToggle` returns a toggle state and a function to toggle the state.
+ *
+ * @example
+ * ```tsx
+ * const { status, handleToggle } = useToggle({ defaultValue: false });
+ * ```
+ */
+declare function useToggle({
+  defaultValue
+}: ToggleOptions): ToggleReturn;
+//#endregion
+export { useToggle };

package/dist/useToggle.js

@@ -0,0 +1,23 @@
+import * as React from "react";
+
+//#region src/useToggle.ts
+/**
+* `useToggle` returns a toggle state and a function to toggle the state.
+*
+* @example
+* ```tsx
+* const { status, handleToggle } = useToggle({ defaultValue: false });
+* ```
+*/
+function useToggle({ defaultValue = false }) {
+	const [status, setStatus] = React.useState(defaultValue);
+	return {
+		handleToggle: React.useCallback(() => {
+			return setStatus((prev) => !prev);
+		}, []),
+		status
+	};
+}
+
+//#endregion
+export { useToggle };

package/dist/useTraceUpdates.d.ts

@@ -0,0 +1,22 @@
+//#region src/useTraceUpdates.d.ts
+/**
+ * `useTraceUpdates` is a React hook that logs all updates to the component tree.
+ * It is useful for debugging with React DevTools.
+ * It is only recommended for development purposes.
+ *
+ * @example
+ * ```tsx
+ * // Trace state changes
+ * function Counter() {
+ *   const [count, setCount] = React.useState(0);
+ *   const [step, setStep] = React.useState(1);
+ *
+ *   useTraceUpdates({ count }, 'Counter.count');
+ *
+ *   return <button onClick={() => setCount(c => c + step)} />;
+ * }
+ * ```
+ */
+declare function useTraceUpdates(value: Record<string, unknown>, name?: string): void;
+//#endregion
+export { useTraceUpdates };

package/dist/useTraceUpdates.js

@@ -0,0 +1,38 @@
+import * as React from "react";
+
+//#region src/useTraceUpdates.ts
+/**
+* `useTraceUpdates` is a React hook that logs all updates to the component tree.
+* It is useful for debugging with React DevTools.
+* It is only recommended for development purposes.
+*
+* @example
+* ```tsx
+* // Trace state changes
+* function Counter() {
+*   const [count, setCount] = React.useState(0);
+*   const [step, setStep] = React.useState(1);
+*
+*   useTraceUpdates({ count }, 'Counter.count');
+*
+*   return <button onClick={() => setCount(c => c + step)} />;
+* }
+* ```
+*/
+function useTraceUpdates(value, name) {
+	const prev = React.useRef(null);
+	React.useEffect(() => {
+		if (prev.current) {
+			const changes = {};
+			for (const key in value) if (prev.current[key] !== value[key]) changes[key] = {
+				from: prev.current[key],
+				to: value[key]
+			};
+			if (Object.keys(changes).length > 0) console.log(`[useTraceUpdates] ${name ?? "Component"} changes:`, changes);
+		}
+		prev.current = value;
+	}, [value, name]);
+}
+
+//#endregion
+export { useTraceUpdates };

package/dist/useTranslator.d.ts

@@ -0,0 +1,110 @@
+//#region src/useTranslator.d.ts
+interface TranslatorConfig {
+  sourceLanguage?: BCP47LanguageTag;
+  targetLanguage: BCP47LanguageTag;
+}
+type TranslatorAvailability = 'available' | 'unavailable' | 'downloadable';
+interface Translator {
+  destroy(): void;
+  readonly inputQuota: number;
+  measureInputUsage(text: string): Promise<number>;
+  readonly sourceLanguage: BCP47LanguageTag;
+  readonly targetLanguage: BCP47LanguageTag;
+  translate(text: string): Promise<string>;
+  translateStreaming(text: string): ReadableStream<string>;
+}
+interface TranslatorConstructor {
+  availability(config: TranslatorConfig): Promise<TranslatorAvailability>;
+  create(config: TranslatorConfig): Promise<Translator>;
+}
+declare global {
+  interface Window {
+    Translator?: TranslatorConstructor;
+  }
+}
+/**
+ * BCP 47 language tag.
+ * Examples: "en", "en-US", "es", "es-PE", "fr", "pt-BR"
+ */
+type BCP47LanguageTag = string;
+interface TranslatorTranslateOptions {
+  /**
+   * Optional callback triggered after checking
+   * whether the language pair is supported.
+   */
+  onLanguageSupportCheck?: (supported: boolean) => void;
+  /**
+   * Source language (BCP 47).
+   * If undefined, the browser may attempt auto-detection (if supported).
+   */
+  sourceLanguage: BCP47LanguageTag;
+  /**
+   * Target language (BCP 47).
+   */
+  targetLanguage: BCP47LanguageTag;
+}
+interface UseTranslatorReturn {
+  /**
+   * Manually checks if the language pair is supported.
+   */
+  checkLanguageSupport: () => Promise<boolean>;
+  /**
+   * Last error produced by the hook.
+   */
+  error: Error | null;
+  /**
+   * Whether the configured language pair is supported.
+   * Null until checked.
+   */
+  isLanguagePairSupported: boolean | null;
+  /**
+   * Whether the Translator API is available in the current browser.
+   */
+  isSupported: boolean;
+  /**
+   * Indicates whether a translation is in progress.
+   */
+  isTranslating: boolean;
+  /**
+   * Translates a given text using the configured languages.
+   */
+  translate: (text: string) => Promise<string>;
+  /**
+   * Last translation result.
+   */
+  translation: string | null;
+}
+/**
+ * `useTranslator` is a React custom hook that provides a simple way to translate text using Translator API in Chrome to translate text with AI models provided in the browser.
+ *
+ * @example
+ * ```tsx
+ * const {
+ *        isSupported,
+ *        translate,
+ *        checkLanguageSupport,
+ *        isLanguagePairSupported,
+ *        isTranslating,
+ *        translation,
+ *        error,
+ *    } = useTranslator({
+ *        sourceLanguage: "es",
+ *        targetLanguage: "en-US",
+ *        onLanguageSupportCheck: (supported) => {
+ *            console.log("Language pair supported:", supported);
+ *        },
+ *    });
+ *
+ *    React.useEffect(() => {
+ *    checkLanguageSupport();
+ *    }, [checkLanguageSupport]);
+ *
+ *    const handleTranslate = async () => {
+ *    await translate("Hola mundo");
+ *    };
+ * ```
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Translator
+ */
+declare function useTranslator(options: TranslatorTranslateOptions): UseTranslatorReturn;
+//#endregion
+export { useTranslator };