@vvi/react-hooks 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# 更新日志 📔
+
+## v1.0.0 (2026-7-4)
+
+- 构建该项目

package/LICENSE

@@ -0,0 +1,16 @@
+# MIT License
+    
+Copyright ©️ <2026> <MrMudBean>
+
+Permission to use, copy, modify, and/or distribute this software for any  
+purpose with or without fee is hereby granted, provided that the above  
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES  
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF  
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR  
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES  
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN  
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF  
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ 

package/README.md

@@ -0,0 +1,33 @@
+# react-hooks
+
+[![version](<https://img.shields.io/npm/v/@vvi/react-hooks.svg?logo=npm&logoColor=rgb(0,0,0)&label=版本号&labelColor=rgb(73,73,228)&color=rgb(0,0,0)>)](https://www.npmjs.com/package/@vvi/react-hooks) [![issues 提交](<https://img.shields.io/badge/issues-提交-rgb(255,0,63)?logo=github>)](https://github.com/MrMudBean/react-hooks/issues)
+  
+业务无关的 hooks 。
+
+## 安装
+
+```bash
+npm install --save @vvi/react-hooks
+
+# pnpm
+pnpm add --save @vvi/react-hooks
+
+# yarn
+yarn add --save @vvi/react-hooks
+```
+
+## 使用
+
+提供了几个简单的与业务无关的用于把玩的 react hooks ：
+
+- **`useTimeId`** ：一个 `useRef` 数值，可用于储存 `setTimeout`、`setInterval` 的返回值，自动在卸载时调用 `clearTimeout(id.current)`
+- **`useInputIsComposing`** ： 储存了当前绑定了 ref 的输入框是否完成了输入的 `usrRef` 数据。可在桌面端设备上中文输入判定是否完成输入选择
+- **`useAnimationFrame`** ：一个 `useRef` 数据，数据储存了 `requestAnimationFrame`
+- **`useRipples`** ：一个 `useRef` 数据。储存了 [Ripples](https://www.npmjs.com/package/@vvi/ripple) 实例
+- **`useLazyRipples`** ：一个 `useRef` 数据，储存了 [Ripple](https://www.npmjs.com/package/@vvi/ripple) 实例
+
+## 状态
+
+此软件包是 `MrMudBean` 生态系统的一部分。
+它使用严格的 TypeScript 编写，并通过 Rollup 构建进行验证。
+虽然单元测试较少，但 API 稳定，并在生产环境中大量使用。

package/cjs/index.js

@@ -0,0 +1,15 @@
+'use strict';
+
+var useAnimationFrame = require('./useAnimationFrame.js');
+var useRipples = require('./use-ripples.js');
+var useLazyRipple = require('./use-lazy-ripple.js');
+var useInputIsComposing = require('./useInputIsComposing.js');
+var useTimeId = require('./useTimeId.js');
+
+
+
+exports.useAnimationFrame = useAnimationFrame.useAnimationFrame;
+exports.useRipples = useRipples.useRipples;
+exports.useLazyRipples = useLazyRipple.useLazyRipples;
+exports.useInputIsComposing = useInputIsComposing.useInputIsComposing;
+exports.useTimeId = useTimeId.useTimeId;

package/cjs/use-lazy-ripple.js

@@ -0,0 +1,67 @@
+'use client';
+'use strict';
+
+var is = require('@vvi/is');
+var react = require('react');
+
+/**
+ * ## 懒加载使用涟漪 hook
+ * @param canvas
+ * @param option
+ */
+function useLazyRipples(canvas, option) {
+    /**  react dom  */
+    const ripples = react.useRef(null);
+    /**  当前是否被卸载  */
+    const isUnmounted = react.useRef(true);
+    /**  是否已加载  */
+    const isLoaded = react.useRef(false);
+    // 加载状态
+    const [isLoading, setIsLoading] = react.useState(false);
+    // 错误状态
+    const [error, setError] = react.useState(null);
+    // 参数
+    const optionRef = react.useRef(option);
+    /**  卸载  */
+    function unmounted() {
+        isUnmounted.current = true;
+        setTimeout(() => {
+            // 当前是被卸载状态
+            if (isUnmounted.current) {
+                ripples.current?.destroy();
+            }
+        }, 0);
+    }
+    // 更新 option，防止加载 option 为旧数据
+    react.useEffect(() => {
+        optionRef.current = option;
+    }, [option]);
+    react.useEffect(() => {
+        isUnmounted.current = false;
+        /**  非空检验（这里一般都是有值的，除非故障）  */
+        if (is.isNull(canvas.current) || isLoaded.current) {
+            return unmounted;
+        }
+        // 设置加载状态
+        setIsLoading(true);
+        isLoaded.current = true;
+        import('@vvi/ripple')
+            .then(module => {
+            if (is.isNull(canvas.current) || isUnmounted.current) {
+                return;
+            }
+            ripples.current = new module.Ripples(canvas.current, optionRef.current);
+            return;
+        })
+            .catch(err => {
+            setError(err);
+        })
+            .finally(() => {
+            setIsLoading(false);
+        });
+        return unmounted;
+    }, []);
+    return { ripples, isLoading, error };
+}
+
+exports.useLazyRipples = useLazyRipples;

package/cjs/use-ripples.js

@@ -0,0 +1,66 @@
+'use client';
+'use strict';
+
+var is = require('@vvi/is');
+var ripple = require('@vvi/ripple');
+var react = require('react');
+
+/**
+ * @module @vvi/react-hooks/index
+ * @file use-ripples.ts
+ * @description   ripple 的主要核心逻辑
+ * @author MrMudBean <Mr.MudBean@outlook.com>
+ * @copyright 2026 ©️ MrMudBean
+ * @since 2025-06-20 01:37
+ * @version 2.0.0-alpha.0
+ * @lastModified 2026-07-07 09:14
+ */
+/**
+ * ## 使用绘制 ripples 上一层
+ * @param canvas `usrRef` 包裹的 `HTMLCanvasElement`，用于绘制图像
+ * @param option  初始化的
+ * @see  [useRipples](https://lmssee.com/custom-hooks/use-ripples)
+ * @see  [JQuery ripple](https://github.com/sirxemic/jquery.ripples)
+ * @example
+ * 下面是在 <BackgroundRipple> 中使用
+ * ```ts
+ * import { useRipples } from '@vvi/react-hooks';
+ *
+ *  export function BackgroundRipple(props: BackgroundRipplesProps) {
+ *
+ *   // canvas 元素
+ *  const canvas = useRef<HTMLCanvasElement>(null);
+ *
+ *  // 使用 ripples
+ *  const ripplesRef = useRipples(canvas, props);
+ *
+ *  return (<>
+ *     <canvas ref={canvas}></canvas>
+ *     {props.children}
+ *  </>);
+ *  }
+ * ```
+ */
+function useRipples(canvas, option) {
+    /**  react dom  */
+    const ripples = react.useRef(null);
+    // 初始化数据
+    react.useEffect(() => {
+        /**  非空检验（这里一般都是有值的，除非故障）  */
+        if (is.isNull(canvas.current))
+            return;
+        try {
+            ripples.current = new ripple.Ripples(canvas.current, option);
+        }
+        catch (error) {
+        }
+        return () => ripples.current?.destroy();
+    }, []);
+    return ripples;
+}
+
+Object.defineProperty(exports, "Ripples", {
+  enumerable: true,
+  get: function () { return ripple.Ripples; }
+});
+exports.useRipples = useRipples;

package/cjs/useAnimationFrame.js

@@ -0,0 +1,137 @@
+'use client';
+'use strict';
+
+var is = require('@vvi/is');
+var react = require('react');
+
+/**
+ * @module @vvi/react-hooks/useAnimationFrame
+ * @file useAnimationFrame.ts
+ * @description 使用 animationFrame
+ * @author MrMudBean <Mr.MudBean@outlook.com>
+ * @copyright 2026 ©️ MrMudBean
+ * @since 2025-01-07 11:23
+ * @version 2.0.0-alpha.0
+ * @lastModified 2026-07-06 17:16
+ */
+/**
+ * # 该钩子在组件卸载时会自动调用 `window.cancelAnimationFrame` 清理传入的回调方法
+ *
+ * 默认是传入即启动调用方法
+ * @description 创建一个会自己关闭（组建卸载时）的 animationFrame。当然，可以通过返回值手动终止
+ * @param callback  使用回调函数。回调函数有两个参数，除了默认的时间，还有另一个用于暂停后的记时时间。如果没有主动暂停，两者时间总是趋近于相等的（可能有其他延迟造成时间差越来越大）。如果没有暂停需求，使用第一个默认时间就可以了。
+ * @param [option=false] 使用第二参数，可指定是否立即执行及是否仅执行一次
+ * @returns  返回值包含执行状态
+ * @see   [useAnimationFrame](https://npm.lmssee.com/react-hooks/use-animation-frame)
+ * @example
+ * ```ts
+ *  import { useAnimationFrame } from '@vvi/react-hooks';
+ *  ...
+ *
+ *  export function Home () {
+ *  // 如果没有主动暂停的需要，直接使用默认的 time 最好。如果中间有使用暂停。那么 time 值是不连贯的，而 runTime 是连贯的
+ *  const result = useAnimationFrame((time ,runTime) => {
+ *     ... //
+ *  });
+ *
+ * return <>
+ *
+ *    <button onclick={() => result.cancel()}>暂停</button>
+ *    <button onclick={() => result.render()}>恢复</button>
+ *   </>
+ * }
+ *  ...
+ * ```
+ * 当然，可使用第二参数执行立即执行还是仅执行一次（作用不大，不与赘述）
+ */
+function useAnimationFrame(callback, option = false) {
+    if (is.isBoolean(option)) {
+        option = {
+            immediately: option,
+            once: false,
+        };
+    }
+    else if (is.isPlainObject(option)) {
+        option = {
+            once: is.isBoolean(option.once) ? option.once : false,
+            immediately: is.isBoolean(option.immediately) ? option.immediately : false,
+        };
+    }
+    else {
+        option = {
+            immediately: false,
+            once: false,
+        };
+    }
+    /**    */
+    const animationFrame = react.useRef({
+        id: 0,
+        immediately: option.immediately ?? true,
+        once: option.once ?? false,
+        noun: false,
+        time: 0,
+        cancelTime: 0,
+        firstRunEffect: true,
+        isUnmounted: true,
+        result: {
+            cancel() {
+                const { id } = animationFrame.current;
+                if (id)
+                    window.cancelAnimationFrame(id);
+                animationFrame.current.result.canceled = true;
+            },
+            canceled: false,
+            render() {
+                const { current } = animationFrame;
+                const { result } = current;
+                current.cancelTime = performance.now();
+                result.cancel();
+                result.canceled = false;
+                current.id = window.requestAnimationFrame(_);
+            },
+        },
+    });
+    const { current } = animationFrame;
+    /**  转化为函数  */
+    const _ = react.useCallback((time) => {
+        const { result } = current;
+        const _time = time - current.cancelTime;
+        current.time += _time < 0 ? 16.7 : _time;
+        callback(time, current.time);
+        // 如果不是仅执行一次，进入下一次执行
+        if (!current.once)
+            result.render();
+    }, [callback]);
+    // 首次执行
+    if (current.immediately && !current.noun && current.result.canceled) {
+        current.noun = true;
+        current.result.render();
+    }
+    react.useEffect(() => {
+        /// 非仅执行一次再次这里需要执行
+        if (!current.once) {
+            if (current.firstRunEffect) {
+                current.result.render();
+                current.firstRunEffect = false; //  标记为不允许执行
+            }
+            else if (!current.firstRunEffect && !current.result.canceled) {
+                /**  非第一次执行  */
+                current.result.render();
+            }
+        }
+    }, [callback]);
+    /// 在组件退出时保证能正确的退出
+    react.useEffect(() => {
+        current.isUnmounted = false;
+        return () => {
+            current.isUnmounted = true;
+            setTimeout(() => {
+                if (current.isUnmounted)
+                    current.result.cancel();
+            }, 0);
+        };
+    }, []);
+    return current.result;
+}
+
+exports.useAnimationFrame = useAnimationFrame;

package/cjs/useInputIsComposing.js

@@ -0,0 +1,68 @@
+'use client';
+'use strict';
+
+var react = require('react');
+
+/**
+ * @module @vvi/react-hooks/useInputIsComposing
+ * @file useInputIsComposing.ts
+ * @description 使用输入框是否完成输入状态
+ * @author MrMudBean <Mr.MudBean@outlook.com>
+ * @copyright 2026 ©️ MrMudBean
+ * @since 2025-01-07 11:23
+ * @version 2.0.0-alpha.0
+ * @lastModified 2026-07-06 17:16
+ */
+/**
+ * # 导出一个使用 `useRef` 创建的 `boolean`
+ *
+ * *由于是包裹在 RefObject 之中，判断时务必使用 `isComposing.current` 进行判断*
+ * @description 用于判断当前的输入状态是否结束
+ * @param inputRef [RefObject<HTMLInputElement | HTMLTextAreaElement>] 输入框的 ref
+ * @returns  RefObject<boolean>
+ * @see   [useInputIscComposing](https://npm.lmssee.com/react-hooks/use-input-is-composing)
+ * @example
+ * ```ts
+ *  import { useInputIsComposing } from '@vvi/react-hooks';
+ *
+ *  ...
+ *  const inputRef = useRef<HTMLInputElement>(null);
+ *
+ *  const inputIsComposing = useInputIsComposing(inputRef);
+ *  ...
+ *  function enterDown(e: React.KeyboardEvent<HTMLInputElement>) {
+ *     if (e.key === 'Enter') {
+ *        if (isComposing.current) {
+ *            console.log("此时此景，按回车键说明为了从候选词中挑选");
+ *        } else {
+ *           console.log("输入完毕，敲回车是为了看一些开发者是否绑定了其他事件");
+ *        }
+ *     }
+ *  }
+ *  ...
+ *  <input type="text" onKeyDown={enterDown} ref={inputRef} />
+ *  ...
+ * ```
+ */
+function useInputIsComposing(inputRef) {
+    /** 当前输入框是否输入模式结束 */
+    const isComposing = react.useRef(false);
+    /** 监视当前编辑器输入状态 */
+    react.useEffect(() => {
+        const _i = inputRef.current; /// 当前元素
+        if (!_i)
+            return; /// 没有（不可能事件但是）获取元素直接返回
+        const handleCompositionStart = () => (isComposing.current = true); /// 键盘输入
+        const handleCompositionEnd = () => (isComposing.current = false); /// 键盘输入结束
+        // _i.focus(); /// 让该元素显示时自动聚焦
+        _i.addEventListener('compositionstart', handleCompositionStart); /// 监听键盘输入事件
+        _i.addEventListener('compositionend', handleCompositionEnd); /// 监听键盘输入结束事件
+        return () => {
+            _i.removeEventListener('compositionstart', handleCompositionStart); /// 取消监听键盘输入事件
+            _i.removeEventListener('compositionend', handleCompositionEnd); /// 取消监听键盘输入结束事件
+        };
+    }, []);
+    return isComposing;
+}
+
+exports.useInputIsComposing = useInputIsComposing;

package/cjs/useTimeId.js

@@ -0,0 +1,53 @@
+'use client';
+'use strict';
+
+var react = require('react');
+
+/**
+ * @module @vvi/react-hooks/useTimeId
+ * @file useTimeId.ts
+ * @description 使用定时器返回的时间戳
+ * @author MrMudBean <Mr.MudBean@outlook.com>
+ * @copyright 2026 ©️ MrMudBean
+ * @since 2025-01-07 11:20
+ * @version 2.0.0-alpha.0
+ * @lastModified 2026-07-06 17:13
+ */
+/**
+ * # 导出一个使用 `useRef` 创建的 `NodeJS.Timeout`
+ *
+ * 该数值在组件卸载时会自动调用 `clearTimeout` 清理
+ * @see   [useTimeId](https://npm.lmssee.com/react-hooks/use-time-id)
+ * @example
+ * ```ts
+ * import { useTimeId } from '@vvi/react-hooks';
+ *
+ * ...
+ *
+ * const timeoutId = useTimeId();
+ *
+ * useEffect(()=>{
+ *     timeoutId.current = setTimeout(()=>{
+ *         ...
+ *     } ,delay);
+ *  });
+ * ...
+ * ```
+ * 其实，正确的用法是这样的：
+ * ```ts
+ *  useEffect(()=>{
+ *    const timeId = setTimeout(()=>{
+ *        ...
+ *    }, delay) ;
+ *
+ *     return ()=> timeId && clearTimeout(timeId);
+ *  });
+ * ```
+ */
+function useTimeId() {
+    const timeId = react.useRef(undefined);
+    react.useEffect(() => () => (timeId.current && clearTimeout(timeId.current)) || undefined, []);
+    return timeId;
+}
+
+exports.useTimeId = useTimeId;

package/es/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @packageDocumentation
+ * @module @react-hooks/index
+ * @file index.ts
+ * @description _
+ * @author Mr.MudBean <Mr.MudBean@outlook.com>
+ * @license MIT
+ * @copyright 2026 ©️ Mr.MudBean
+ * @since 2026-07-06 16:13
+ * @version 0.0.0
+ * @lastModified 2026-07-06 16:18
+ */
+export { useAnimationFrame } from './useAnimationFrame';
+export { useRipples } from './use-ripples';
+export { useLazyRipples } from './use-lazy-ripple';
+export { useInputIsComposing } from './useInputIsComposing';
+export { useTimeId } from './useTimeId';

package/es/index.js

@@ -0,0 +1,5 @@
+export { useAnimationFrame } from './useAnimationFrame.js';
+export { useRipples } from './use-ripples.js';
+export { useLazyRipples } from './use-lazy-ripple.js';
+export { useInputIsComposing } from './useInputIsComposing.js';
+export { useTimeId } from './useTimeId.js';

package/es/use-lazy-ripple.d.ts

@@ -0,0 +1,13 @@
+import type { Ripples } from '@vvi/ripple';
+import type { RipplesOptions } from '@vvi/ripple';
+import type { RefObject } from 'react';
+/**
+ * ## 懒加载使用涟漪 hook
+ * @param canvas
+ * @param option
+ */
+export declare function useLazyRipples(canvas: RefObject<HTMLCanvasElement | null>, option?: RipplesOptions): {
+    ripples: RefObject<Ripples | null>;
+    isLoading: boolean;
+    error: unknown;
+};

package/es/use-lazy-ripple.js

@@ -0,0 +1,65 @@
+'use client';
+import { isNull } from '@vvi/is';
+import { useRef, useState, useEffect } from 'react';
+
+/**
+ * ## 懒加载使用涟漪 hook
+ * @param canvas
+ * @param option
+ */
+function useLazyRipples(canvas, option) {
+    /**  react dom  */
+    const ripples = useRef(null);
+    /**  当前是否被卸载  */
+    const isUnmounted = useRef(true);
+    /**  是否已加载  */
+    const isLoaded = useRef(false);
+    // 加载状态
+    const [isLoading, setIsLoading] = useState(false);
+    // 错误状态
+    const [error, setError] = useState(null);
+    // 参数
+    const optionRef = useRef(option);
+    /**  卸载  */
+    function unmounted() {
+        isUnmounted.current = true;
+        setTimeout(() => {
+            // 当前是被卸载状态
+            if (isUnmounted.current) {
+                ripples.current?.destroy();
+            }
+        }, 0);
+    }
+    // 更新 option，防止加载 option 为旧数据
+    useEffect(() => {
+        optionRef.current = option;
+    }, [option]);
+    useEffect(() => {
+        isUnmounted.current = false;
+        /**  非空检验（这里一般都是有值的，除非故障）  */
+        if (isNull(canvas.current) || isLoaded.current) {
+            return unmounted;
+        }
+        // 设置加载状态
+        setIsLoading(true);
+        isLoaded.current = true;
+        import('@vvi/ripple')
+            .then(module => {
+            if (isNull(canvas.current) || isUnmounted.current) {
+                return;
+            }
+            ripples.current = new module.Ripples(canvas.current, optionRef.current);
+            return;
+        })
+            .catch(err => {
+            setError(err);
+        })
+            .finally(() => {
+            setIsLoading(false);
+        });
+        return unmounted;
+    }, []);
+    return { ripples, isLoading, error };
+}
+
+export { useLazyRipples };

package/es/use-ripples.d.ts

@@ -0,0 +1,31 @@
+import { Ripples, type RipplesOptions } from '@vvi/ripple';
+import type { RefObject } from 'react';
+/**
+ * ## 使用绘制 ripples 上一层
+ * @param canvas `usrRef` 包裹的 `HTMLCanvasElement`，用于绘制图像
+ * @param option  初始化的
+ * @see  [useRipples](https://lmssee.com/custom-hooks/use-ripples)
+ * @see  [JQuery ripple](https://github.com/sirxemic/jquery.ripples)
+ * @example
+ * 下面是在 <BackgroundRipple> 中使用
+ * ```ts
+ * import { useRipples } from '@vvi/react-hooks';
+ *
+ *  export function BackgroundRipple(props: BackgroundRipplesProps) {
+ *
+ *   // canvas 元素
+ *  const canvas = useRef<HTMLCanvasElement>(null);
+ *
+ *  // 使用 ripples
+ *  const ripplesRef = useRipples(canvas, props);
+ *
+ *  return (<>
+ *     <canvas ref={canvas}></canvas>
+ *     {props.children}
+ *  </>);
+ *  }
+ * ```
+ */
+export declare function useRipples(canvas: RefObject<HTMLCanvasElement | null>, option?: RipplesOptions): RefObject<Ripples | null>;
+export { Ripples };
+export type { RipplesOptions };

package/es/use-ripples.js

@@ -0,0 +1,61 @@
+'use client';
+import { isNull } from '@vvi/is';
+import { Ripples } from '@vvi/ripple';
+export { Ripples } from '@vvi/ripple';
+import { useRef, useEffect } from 'react';
+
+/**
+ * @module @vvi/react-hooks/index
+ * @file use-ripples.ts
+ * @description   ripple 的主要核心逻辑
+ * @author MrMudBean <Mr.MudBean@outlook.com>
+ * @copyright 2026 ©️ MrMudBean
+ * @since 2025-06-20 01:37
+ * @version 2.0.0-alpha.0
+ * @lastModified 2026-07-07 09:14
+ */
+/**
+ * ## 使用绘制 ripples 上一层
+ * @param canvas `usrRef` 包裹的 `HTMLCanvasElement`，用于绘制图像
+ * @param option  初始化的
+ * @see  [useRipples](https://lmssee.com/custom-hooks/use-ripples)
+ * @see  [JQuery ripple](https://github.com/sirxemic/jquery.ripples)
+ * @example
+ * 下面是在 <BackgroundRipple> 中使用
+ * ```ts
+ * import { useRipples } from '@vvi/react-hooks';
+ *
+ *  export function BackgroundRipple(props: BackgroundRipplesProps) {
+ *
+ *   // canvas 元素
+ *  const canvas = useRef<HTMLCanvasElement>(null);
+ *
+ *  // 使用 ripples
+ *  const ripplesRef = useRipples(canvas, props);
+ *
+ *  return (<>
+ *     <canvas ref={canvas}></canvas>
+ *     {props.children}
+ *  </>);
+ *  }
+ * ```
+ */
+function useRipples(canvas, option) {
+    /**  react dom  */
+    const ripples = useRef(null);
+    // 初始化数据
+    useEffect(() => {
+        /**  非空检验（这里一般都是有值的，除非故障）  */
+        if (isNull(canvas.current))
+            return;
+        try {
+            ripples.current = new Ripples(canvas.current, option);
+        }
+        catch (error) {
+        }
+        return () => ripples.current?.destroy();
+    }, []);
+    return ripples;
+}
+
+export { useRipples };

package/es/useAnimationFrame.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @module @vvi/react-hooks/useAnimationFrame
+ * @file useAnimationFrame.ts
+ * @description 使用 animationFrame
+ * @author MrMudBean <Mr.MudBean@outlook.com>
+ * @copyright 2026 ©️ MrMudBean
+ * @since 2025-01-07 11:23
+ * @version 2.0.0-alpha.0
+ * @lastModified 2026-07-06 17:16
+ */
+/**  使用动画结果  */
+export interface UseAnimationFrameResult {
+    /**  取消执行动画  */
+    cancel(): void;
+    /**  当前取消的状态  */
+    canceled: boolean;
+    /**  再次执行  */
+    render(): void;
+}
+export interface UseAnimationFrame {
+    /**  当前动画的 id  */
+    id: null | number;
+    /**  执行的时间 */
+    time: number;
+    /**  暂停的时间  */
+    cancelTime: number;
+    /**  返回值  */
+    result: UseAnimationFrameResult;
+    immediately: boolean;
+    /**  是否完成了额外的首次执行  */
+    noun: boolean;
+    /**  是否仅执行一次  */
+    once: boolean;
+    /**  是否首次执行 effect  */
+    firstRunEffect: boolean;
+    /**  是否已卸载  */
+    isUnmounted: boolean;
+}
+export type AnimationFrameOption = boolean | {
+    immediately?: boolean;
+    once?: boolean;
+};
+/**
+ * # 该钩子在组件卸载时会自动调用 `window.cancelAnimationFrame` 清理传入的回调方法
+ *
+ * 默认是传入即启动调用方法
+ * @description 创建一个会自己关闭（组建卸载时）的 animationFrame。当然，可以通过返回值手动终止
+ * @param callback  使用回调函数。回调函数有两个参数，除了默认的时间，还有另一个用于暂停后的记时时间。如果没有主动暂停，两者时间总是趋近于相等的（可能有其他延迟造成时间差越来越大）。如果没有暂停需求，使用第一个默认时间就可以了。
+ * @param [option=false] 使用第二参数，可指定是否立即执行及是否仅执行一次
+ * @returns  返回值包含执行状态
+ * @see   [useAnimationFrame](https://npm.lmssee.com/react-hooks/use-animation-frame)
+ * @example
+ * ```ts
+ *  import { useAnimationFrame } from '@vvi/react-hooks';
+ *  ...
+ *
+ *  export function Home () {
+ *  // 如果没有主动暂停的需要，直接使用默认的 time 最好。如果中间有使用暂停。那么 time 值是不连贯的，而 runTime 是连贯的
+ *  const result = useAnimationFrame((time ,runTime) => {
+ *     ... //
+ *  });
+ *
+ * return <>
+ *
+ *    <button onclick={() => result.cancel()}>暂停</button>
+ *    <button onclick={() => result.render()}>恢复</button>
+ *   </>
+ * }
+ *  ...
+ * ```
+ * 当然，可使用第二参数执行立即执行还是仅执行一次（作用不大，不与赘述）
+ */
+export declare function useAnimationFrame(callback: (time: number, runtime: number) => void, option?: AnimationFrameOption): UseAnimationFrameResult;

package/es/useAnimationFrame.js

@@ -0,0 +1,135 @@
+'use client';
+import { isBoolean, isPlainObject } from '@vvi/is';
+import { useRef, useCallback, useEffect } from 'react';
+
+/**
+ * @module @vvi/react-hooks/useAnimationFrame
+ * @file useAnimationFrame.ts
+ * @description 使用 animationFrame
+ * @author MrMudBean <Mr.MudBean@outlook.com>
+ * @copyright 2026 ©️ MrMudBean
+ * @since 2025-01-07 11:23
+ * @version 2.0.0-alpha.0
+ * @lastModified 2026-07-06 17:16
+ */
+/**
+ * # 该钩子在组件卸载时会自动调用 `window.cancelAnimationFrame` 清理传入的回调方法
+ *
+ * 默认是传入即启动调用方法
+ * @description 创建一个会自己关闭（组建卸载时）的 animationFrame。当然，可以通过返回值手动终止
+ * @param callback  使用回调函数。回调函数有两个参数，除了默认的时间，还有另一个用于暂停后的记时时间。如果没有主动暂停，两者时间总是趋近于相等的（可能有其他延迟造成时间差越来越大）。如果没有暂停需求，使用第一个默认时间就可以了。
+ * @param [option=false] 使用第二参数，可指定是否立即执行及是否仅执行一次
+ * @returns  返回值包含执行状态
+ * @see   [useAnimationFrame](https://npm.lmssee.com/react-hooks/use-animation-frame)
+ * @example
+ * ```ts
+ *  import { useAnimationFrame } from '@vvi/react-hooks';
+ *  ...
+ *
+ *  export function Home () {
+ *  // 如果没有主动暂停的需要，直接使用默认的 time 最好。如果中间有使用暂停。那么 time 值是不连贯的，而 runTime 是连贯的
+ *  const result = useAnimationFrame((time ,runTime) => {
+ *     ... //
+ *  });
+ *
+ * return <>
+ *
+ *    <button onclick={() => result.cancel()}>暂停</button>
+ *    <button onclick={() => result.render()}>恢复</button>
+ *   </>
+ * }
+ *  ...
+ * ```
+ * 当然，可使用第二参数执行立即执行还是仅执行一次（作用不大，不与赘述）
+ */
+function useAnimationFrame(callback, option = false) {
+    if (isBoolean(option)) {
+        option = {
+            immediately: option,
+            once: false,
+        };
+    }
+    else if (isPlainObject(option)) {
+        option = {
+            once: isBoolean(option.once) ? option.once : false,
+            immediately: isBoolean(option.immediately) ? option.immediately : false,
+        };
+    }
+    else {
+        option = {
+            immediately: false,
+            once: false,
+        };
+    }
+    /**    */
+    const animationFrame = useRef({
+        id: 0,
+        immediately: option.immediately ?? true,
+        once: option.once ?? false,
+        noun: false,
+        time: 0,
+        cancelTime: 0,
+        firstRunEffect: true,
+        isUnmounted: true,
+        result: {
+            cancel() {
+                const { id } = animationFrame.current;
+                if (id)
+                    window.cancelAnimationFrame(id);
+                animationFrame.current.result.canceled = true;
+            },
+            canceled: false,
+            render() {
+                const { current } = animationFrame;
+                const { result } = current;
+                current.cancelTime = performance.now();
+                result.cancel();
+                result.canceled = false;
+                current.id = window.requestAnimationFrame(_);
+            },
+        },
+    });
+    const { current } = animationFrame;
+    /**  转化为函数  */
+    const _ = useCallback((time) => {
+        const { result } = current;
+        const _time = time - current.cancelTime;
+        current.time += _time < 0 ? 16.7 : _time;
+        callback(time, current.time);
+        // 如果不是仅执行一次，进入下一次执行
+        if (!current.once)
+            result.render();
+    }, [callback]);
+    // 首次执行
+    if (current.immediately && !current.noun && current.result.canceled) {
+        current.noun = true;
+        current.result.render();
+    }
+    useEffect(() => {
+        /// 非仅执行一次再次这里需要执行
+        if (!current.once) {
+            if (current.firstRunEffect) {
+                current.result.render();
+                current.firstRunEffect = false; //  标记为不允许执行
+            }
+            else if (!current.firstRunEffect && !current.result.canceled) {
+                /**  非第一次执行  */
+                current.result.render();
+            }
+        }
+    }, [callback]);
+    /// 在组件退出时保证能正确的退出
+    useEffect(() => {
+        current.isUnmounted = false;
+        return () => {
+            current.isUnmounted = true;
+            setTimeout(() => {
+                if (current.isUnmounted)
+                    current.result.cancel();
+            }, 0);
+        };
+    }, []);
+    return current.result;
+}
+
+export { useAnimationFrame };

package/es/useInputIsComposing.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @module @vvi/react-hooks/useInputIsComposing
+ * @file useInputIsComposing.ts
+ * @description 使用输入框是否完成输入状态
+ * @author MrMudBean <Mr.MudBean@outlook.com>
+ * @copyright 2026 ©️ MrMudBean
+ * @since 2025-01-07 11:23
+ * @version 2.0.0-alpha.0
+ * @lastModified 2026-07-06 17:16
+ */
+import type { RefObject } from 'react';
+/**
+ * # 导出一个使用 `useRef` 创建的 `boolean`
+ *
+ * *由于是包裹在 RefObject 之中，判断时务必使用 `isComposing.current` 进行判断*
+ * @description 用于判断当前的输入状态是否结束
+ * @param inputRef [RefObject<HTMLInputElement | HTMLTextAreaElement>] 输入框的 ref
+ * @returns  RefObject<boolean>
+ * @see   [useInputIscComposing](https://npm.lmssee.com/react-hooks/use-input-is-composing)
+ * @example
+ * ```ts
+ *  import { useInputIsComposing } from '@vvi/react-hooks';
+ *
+ *  ...
+ *  const inputRef = useRef<HTMLInputElement>(null);
+ *
+ *  const inputIsComposing = useInputIsComposing(inputRef);
+ *  ...
+ *  function enterDown(e: React.KeyboardEvent<HTMLInputElement>) {
+ *     if (e.key === 'Enter') {
+ *        if (isComposing.current) {
+ *            console.log("此时此景，按回车键说明为了从候选词中挑选");
+ *        } else {
+ *           console.log("输入完毕，敲回车是为了看一些开发者是否绑定了其他事件");
+ *        }
+ *     }
+ *  }
+ *  ...
+ *  <input type="text" onKeyDown={enterDown} ref={inputRef} />
+ *  ...
+ * ```
+ */
+export declare function useInputIsComposing(inputRef: RefObject<HTMLInputElement | HTMLTextAreaElement | null>): RefObject<boolean>;

package/es/useInputIsComposing.js

@@ -0,0 +1,66 @@
+'use client';
+import { useRef, useEffect } from 'react';
+
+/**
+ * @module @vvi/react-hooks/useInputIsComposing
+ * @file useInputIsComposing.ts
+ * @description 使用输入框是否完成输入状态
+ * @author MrMudBean <Mr.MudBean@outlook.com>
+ * @copyright 2026 ©️ MrMudBean
+ * @since 2025-01-07 11:23
+ * @version 2.0.0-alpha.0
+ * @lastModified 2026-07-06 17:16
+ */
+/**
+ * # 导出一个使用 `useRef` 创建的 `boolean`
+ *
+ * *由于是包裹在 RefObject 之中，判断时务必使用 `isComposing.current` 进行判断*
+ * @description 用于判断当前的输入状态是否结束
+ * @param inputRef [RefObject<HTMLInputElement | HTMLTextAreaElement>] 输入框的 ref
+ * @returns  RefObject<boolean>
+ * @see   [useInputIscComposing](https://npm.lmssee.com/react-hooks/use-input-is-composing)
+ * @example
+ * ```ts
+ *  import { useInputIsComposing } from '@vvi/react-hooks';
+ *
+ *  ...
+ *  const inputRef = useRef<HTMLInputElement>(null);
+ *
+ *  const inputIsComposing = useInputIsComposing(inputRef);
+ *  ...
+ *  function enterDown(e: React.KeyboardEvent<HTMLInputElement>) {
+ *     if (e.key === 'Enter') {
+ *        if (isComposing.current) {
+ *            console.log("此时此景，按回车键说明为了从候选词中挑选");
+ *        } else {
+ *           console.log("输入完毕，敲回车是为了看一些开发者是否绑定了其他事件");
+ *        }
+ *     }
+ *  }
+ *  ...
+ *  <input type="text" onKeyDown={enterDown} ref={inputRef} />
+ *  ...
+ * ```
+ */
+function useInputIsComposing(inputRef) {
+    /** 当前输入框是否输入模式结束 */
+    const isComposing = useRef(false);
+    /** 监视当前编辑器输入状态 */
+    useEffect(() => {
+        const _i = inputRef.current; /// 当前元素
+        if (!_i)
+            return; /// 没有（不可能事件但是）获取元素直接返回
+        const handleCompositionStart = () => (isComposing.current = true); /// 键盘输入
+        const handleCompositionEnd = () => (isComposing.current = false); /// 键盘输入结束
+        // _i.focus(); /// 让该元素显示时自动聚焦
+        _i.addEventListener('compositionstart', handleCompositionStart); /// 监听键盘输入事件
+        _i.addEventListener('compositionend', handleCompositionEnd); /// 监听键盘输入结束事件
+        return () => {
+            _i.removeEventListener('compositionstart', handleCompositionStart); /// 取消监听键盘输入事件
+            _i.removeEventListener('compositionend', handleCompositionEnd); /// 取消监听键盘输入结束事件
+        };
+    }, []);
+    return isComposing;
+}
+
+export { useInputIsComposing };

package/es/useTimeId.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @module @vvi/react-hooks/useTimeId
+ * @file useTimeId.ts
+ * @description 使用定时器返回的时间戳
+ * @author MrMudBean <Mr.MudBean@outlook.com>
+ * @copyright 2026 ©️ MrMudBean
+ * @since 2025-01-07 11:20
+ * @version 2.0.0-alpha.0
+ * @lastModified 2026-07-06 17:13
+ */
+/**
+ * # 导出一个使用 `useRef` 创建的 `NodeJS.Timeout`
+ *
+ * 该数值在组件卸载时会自动调用 `clearTimeout` 清理
+ * @see   [useTimeId](https://npm.lmssee.com/react-hooks/use-time-id)
+ * @example
+ * ```ts
+ * import { useTimeId } from '@vvi/react-hooks';
+ *
+ * ...
+ *
+ * const timeoutId = useTimeId();
+ *
+ * useEffect(()=>{
+ *     timeoutId.current = setTimeout(()=>{
+ *         ...
+ *     } ,delay);
+ *  });
+ * ...
+ * ```
+ * 其实，正确的用法是这样的：
+ * ```ts
+ *  useEffect(()=>{
+ *    const timeId = setTimeout(()=>{
+ *        ...
+ *    }, delay) ;
+ *
+ *     return ()=> timeId && clearTimeout(timeId);
+ *  });
+ * ```
+ */
+export declare function useTimeId(): import("react").RefObject<number | undefined>;

package/es/useTimeId.js

@@ -0,0 +1,51 @@
+'use client';
+import { useRef, useEffect } from 'react';
+
+/**
+ * @module @vvi/react-hooks/useTimeId
+ * @file useTimeId.ts
+ * @description 使用定时器返回的时间戳
+ * @author MrMudBean <Mr.MudBean@outlook.com>
+ * @copyright 2026 ©️ MrMudBean
+ * @since 2025-01-07 11:20
+ * @version 2.0.0-alpha.0
+ * @lastModified 2026-07-06 17:13
+ */
+/**
+ * # 导出一个使用 `useRef` 创建的 `NodeJS.Timeout`
+ *
+ * 该数值在组件卸载时会自动调用 `clearTimeout` 清理
+ * @see   [useTimeId](https://npm.lmssee.com/react-hooks/use-time-id)
+ * @example
+ * ```ts
+ * import { useTimeId } from '@vvi/react-hooks';
+ *
+ * ...
+ *
+ * const timeoutId = useTimeId();
+ *
+ * useEffect(()=>{
+ *     timeoutId.current = setTimeout(()=>{
+ *         ...
+ *     } ,delay);
+ *  });
+ * ...
+ * ```
+ * 其实，正确的用法是这样的：
+ * ```ts
+ *  useEffect(()=>{
+ *    const timeId = setTimeout(()=>{
+ *        ...
+ *    }, delay) ;
+ *
+ *     return ()=> timeId && clearTimeout(timeId);
+ *  });
+ * ```
+ */
+function useTimeId() {
+    const timeId = useRef(undefined);
+    useEffect(() => () => (timeId.current && clearTimeout(timeId.current)) || undefined, []);
+    return timeId;
+}
+
+export { useTimeId };

package/es/utils/dog.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @module @react-hooks/qqi
+ * @file dog.ts
+ * @description _
+ * @author Mr.MudBean <Mr.MudBean@outlook.com>
+ * @copyright 2026 ©️ Mr.MudBean
+ * @since 2026-07-06 16:04
+ * @version 0.0.0
+ * @lastModified 2026-07-06 16:05
+ */
+export declare const dog: import("@vvi/log").DevLog;

package/package.json

@@ -0,0 +1,118 @@
+{
+  "name": "@vvi/react-hooks",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "cjs/index.js",
+  "module": "es/index.js",
+  "types": "es/index.d.ts",
+  "author": {
+    "name": "泥豆君",
+    "email": "Mr.MudBean@outlook.com",
+    "url": "https://mudbean.cn"
+  },
+  "description": "React hooks of vvi",
+  "sideEffects": false,
+  "license": "MIT",
+  "files": [
+    "cjs",
+    "es",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "default": "./es/index.js",
+        "types": "./es/index.d.ts"
+      },
+      "require": {
+        "default": "./cjs/index.js",
+        "types": "./es/index.d.ts"
+      }
+    },
+    "./use-lazy-ripple": {
+      "import": {
+        "default": "./es/use-lazy-ripple.js",
+        "types": "./es/use-lazy-ripple.d.ts"
+      },
+      "require": {
+        "default": "./cjs/use-lazy-ripple.js",
+        "types": "./es/use-lazy-ripple.d.ts"
+      }
+    },
+    "./use-ripples": {
+      "import": {
+        "default": "./es/use-ripples.js",
+        "types": "./es/use-ripples.d.ts"
+      },
+      "require": {
+        "default": "./cjs/use-ripples.js",
+        "types": "./es/use-ripples.d.ts"
+      }
+    },
+    "./useAnimationFrame": {
+      "import": {
+        "default": "./es/useAnimationFrame.js",
+        "types": "./es/useAnimationFrame.d.ts"
+      },
+      "require": {
+        "default": "./cjs/useAnimationFrame.js",
+        "types": "./es/useAnimationFrame.d.ts"
+      }
+    },
+    "./useInputIsComposing": {
+      "import": {
+        "default": "./es/useInputIsComposing.js",
+        "types": "./es/useInputIsComposing.d.ts"
+      },
+      "require": {
+        "default": "./cjs/useInputIsComposing.js",
+        "types": "./es/useInputIsComposing.d.ts"
+      }
+    },
+    "./useTimeId": {
+      "import": {
+        "default": "./es/useTimeId.js",
+        "types": "./es/useTimeId.d.ts"
+      },
+      "require": {
+        "default": "./cjs/useTimeId.js",
+        "types": "./es/useTimeId.d.ts"
+      }
+    }
+  },
+  "keywords": [
+    "react-hooks",
+    "mudbean",
+    "vvi"
+  ],
+  "homepage": "https://npm.lmssee.com/react-hooks",
+  "dependencies": {
+    "@vvi/is": "^2.0.5",
+    "@vvi/ripple": "^1.0.0",
+    "@vvi/state": "^0.0.2"
+  },
+  "peerDependencies": {
+    "react": "^19.2"
+  },
+  "bugs": {
+    "url": "https://github.com/MrMudBean/react-hooks/issues",
+    "email": "Mr.MudBean@outlook.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MrMudBean/react-hooks.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "browserslist": [
+    "> 1%",
+    "last 2 versions"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}