docs: zh support

Author: gaoachao

.changeset/slick-heads-send.md

@@ -2,4 +2,4 @@
 "@lynx-js/react-use": patch
 ---
 
-Introduce `useVelocity`.
+Introduce `useVelocity`: a hook that tracks touch velocity and direction with smoothing support.

README.md

@@ -25,7 +25,7 @@
     <br />
     A React-style hooks library designed specifically for <a href="https://lynxjs.org/react/">ReactLynx</a>.
     <br />
-    Bringing familiar React patterns to cross-platform applications.
+    Translations: <a href="https://github.com/lynx-community/reactlynx-use/blob/main/README.zh-CN.md">🇨🇳 汉语</a>
   </sup>
   <br />
   <br />
@@ -62,6 +62,7 @@
 - [**MainThreadScripts**](./docs/en/mts/README.md)
   - [`useMainThreadImperativeHandle`](./docs/en/mts/useMainThreadImperativeHandle.md) &mdash; main-thread version of React's [useImperativeHandle](https://react.dev/reference/react/useImperativeHandle).
   - [`useTapLock`](./docs/en/mts/useTapLock.md) &mdash; a hook for locking tap events.
+  - [`useVelocity`](./docs/en/mts/useVelocity.md) &mdash; a hook that tracks touch velocity and direction with smoothing support.
     <br/>
     <br/>
 - [**Lifecycles**](./docs/en/lifecycles/README.md)

README.zh-CN.md

@@ -1 +1,120 @@
-TODO
+<div align="center">
+  <h1>
+    <br/>
+    <br/>
+    🐈‍⬛
+    <br />
+    <br />
+    <br />
+    <br />
+    <br />
+  </h1>
+  <sup>
+    <br />
+    <br />
+    <a href="https://www.npmjs.com/package/@lynx-js/react-use">
+       <img src="https://img.shields.io/npm/v/@lynx-js/react-use.svg" alt="npm package" />
+    </a>
+    <a href="https://www.npmjs.com/package/@lynx-js/react-use">
+      <img src="https://img.shields.io/npm/dm/@lynx-js/react-use.svg" alt="npm downloads" />
+    </a>
+    <a href="./LICENSE">
+      <img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="license" />
+    </a>
+    <br />
+    <br />
+    专为 <a href="https://lynxjs.org/react/">ReactLynx</a> 设计的 React 风格 hooks 库。
+    <br />
+  </sup>
+  <br />
+  <br />
+  <br />
+  <br />
+  <pre>npm i <a href="https://www.npmjs.com/package/@lynx-js/react-use">@lynx-js/react-use</a></pre>
+  <br />
+  <br />
+  <br />
+  <br />
+  <br />
+</div>
+
+---
+
+<div align="center">
+  <h2>✨ 特性</h2>
+</div>
+
+<br/>
+
+- 🎯 **ReactLynx 兼容** &mdash; 与 ReactLynx 应用无缝集成
+- ⚛️ **React 风格 API** &mdash; 为 React 开发者提供熟悉的 hooks API
+- 🔧 **跨平台特性** &mdash; 基于 Lynx 跨平台特性精心设计
+
+<br/>
+<br/>
+
+---
+
+<div align="center">
+  <h2>📄 文档</h2>
+</div>
+
+- [**主线程脚本**](./docs/zh/mts/README.md)
+  - [`useMainThreadImperativeHandle`](./docs/zh/mts/useMainThreadImperativeHandle.md) &mdash; React [useImperativeHandle](https://react.dev/reference/react/useImperativeHandle) 的主线程版本。
+  - [`useTapLock`](./docs/zh/mts/useTapLock.md) &mdash; 用于锁定点击事件的 hook。
+  - [`useVelocity`](./docs/zh/mts/useVelocity.md) &mdash; 用于跟踪 tap 速度和方向的 hook。
+    <br/>
+    <br/>
+- [**生命周期**](./docs/zh/lifecycles/README.md)
+  - [`useEffectOnce`](./docs/zh/lifecycles/useEffectOnce.md) &mdash; 仅运行一次的 [`useEffect`](https://reactjs.org/docs/hooks-reference.html#useeffect)。
+  - [`useLifecycles`](./docs/zh/lifecycles/useLifecycles.md) &mdash; 调用 `mount` 和 `unmount` 回调。
+  - [`useMountedState`](./docs/zh/lifecycles/useMountedState.md) 和 [`useUnmountPromise`](./docs/zh/lifecycles/useUnmountPromise.md) &mdash; 跟踪组件是否已挂载。
+  - [`useUnmount`](./docs/zh/lifecycles/useUnmount.md) &mdash; 调用 `unmount` 回调。
+  - [`useUpdateEffect`](./docs/zh/lifecycles/useUpdateEffect.md) &mdash; 仅在更新时运行 `effect`。
+    <br/>
+    <br/>
+- [**副作用**](./docs/zh/side-effects/README.md)
+  - [`useDebounce`](./docs/zh/side-effects/useDebounce.md) &mdash; 对函数进行防抖处理。
+  - [`useError`](./docs/zh/side-effects/useError.md) &mdash; 错误分发器。
+  - [`useThrottle` 和 `useThrottleFn`](./docs/zh/side-effects/useThrottle.md) &mdash; 对函数进行节流处理。
+    <br/>
+    <br/>
+- [**状态**](./docs/zh/state/README.md)
+  - [`createMemo`](./docs/zh/state/createMemo.md) &mdash; memoized hooks 的工厂函数。
+  - [`useToggle` 和 `useBoolean`](./docs/zh/state/useToggle.md) &mdash; 跟踪布尔值的状态。
+  - [`useCounter` 和 `useNumber`](./docs/zh/state/useCounter.md) &mdash; 跟踪数字的状态。
+  - [`useDefault`](./docs/zh/state/useDefault.md) &mdash; 当状态为 `null` 或 `undefined` 时返回默认值。
+  - [`useLatest`](./docs/zh/state/useLatest.md) &mdash; 返回最新的 state 或 props
+  - [`useMap`](./docs/zh/state/useMap.md) &mdash; 跟踪对象的状态。
+  - [`usePrevious`](./docs/zh/state/usePrevious.md) &mdash; 返回之前的 state 或 props。
+  - [`useQueue`](./docs/zh/state/useQueue.md) &mdash; 实现简单的队列。
+  - [`useSet`](./docs/zh/state/useSet.md) &mdash; 跟踪 Set 的状态。
+  - [`useSetState`](./docs/zh/state/useSetState.md) &mdash; 创建类似 `this.setState` 工作方式的 `setState` 方法。
+
+<br />
+<br />
+
+---
+
+<div align="center">
+  <h2>🙏 致谢</h2>
+</div>
+
+<br />
+
+本库中的许多 hooks 都建立在 [**react-use**](https://github.com/streamich/react-use) 提供的优秀基础之上。我们向维护者和贡献者致以诚挚的谢意，感谢他们在 React hooks 生态系统中的杰出工作。
+
+我们还从其他优秀项目中汲取灵感：
+
+- [kripod/react-hooks](https://github.com/kripod/react-hooks)
+- [vueuse/vueuse](https://github.com/vueuse/vueuse)
+- [alibaba/hooks](https://github.com/alibaba/hooks)
+
+<br />
+<br />
+
+---
+
+<p align="center">
+  用 ❤️ 为 ReactLynx 社区打造
+</p>

docs/en/mts/README.md

@@ -1 +1,3 @@
-# Main Thread Script (MTS)
+# Main Thread Script (MTS)
+
+_"MTS Hooks"_ unleash the power of Lynx's [Main Thread Script](https://lynxjs.org/next/react/main-thread-script.html).

docs/en/mts/useVelocity.md

@@ -0,0 +1,52 @@
+# useVelocity
+
+A hook that tracks touch velocity and direction with smoothing support.
+
+## Usage
+
+```tsx
+import { useVelocity } from "@lynx-js/react-use";
+
+const Demo = () => {
+  const { getVelocity, handleTouchStartMT, handleTouchMoveMT } = useVelocity({
+    smoothingFactor: 0.2,
+    maxTimeDelta: 100,
+    RTL: false,
+  });
+
+  return (
+    <view
+      onTouchStart={handleTouchStartMT}
+      onTouchMove={handleTouchMoveMT}
+      onTouchEnd={() => {
+        const { velocity, direction } = getVelocity();
+        console.log(`Velocity: ${velocity}px/s, Direction: ${direction}`);
+      }}
+    >
+      <text>Swipe me!</text>
+    </view>
+  );
+};
+```
+
+## Type Declarations
+
+```ts
+import type { MainThread } from '@lynx-js/types';
+export type Direction = 'forward' | 'backward' | 'none';
+export interface UseVelocityOptions {
+    RTL?: boolean;
+    smoothingFactor?: number;
+    maxTimeDelta?: number;
+}
+export interface VelocityResult {
+    velocity: number;
+    direction: Direction;
+}
+export interface UseVelocityReturn {
+    getVelocity: () => VelocityResult;
+    handleTouchStartMT: (event: MainThread.TouchEvent) => void;
+    handleTouchMoveMT: (event: MainThread.TouchEvent) => void;
+}
+export default function useVelocity(options?: UseVelocityOptions): UseVelocityReturn;
+```

docs/zh/lifecycles/README.md

@@ -0,0 +1,5 @@
+# Lifecycle
+
+> **致谢：** 部分文档基于 [react-use](https://github.com/streamich/react-use/blob/master/docs/Lifecycles.md)
+
+_"Lifecycle Hooks"_ modify and extend built-in React hooks or imitate React Class component lifecycle patterns.

docs/zh/lifecycles/useEffectOnce.md

@@ -0,0 +1,31 @@
+# useEffectOnce
+
+> **致谢：** Re-export from [react-use](https://github.com/streamich/react-use)
+
+仅运行一次的 [`useEffect`](https://reactjs.org/docs/hooks-reference.html#useeffect)
+
+## 示例
+
+```tsx
+import { useEffectOnce } from "@lynx-js/react-use";
+
+const Demo = () => {
+  useEffectOnce(() => {
+    console.log("Running effect once on mount");
+
+    return () => {
+      console.log("Running clean-up of effect on unmount");
+    };
+  });
+
+  return null;
+};
+```
+
+## 类型定义
+
+```ts
+import type { EffectCallback } from "@lynx-js/react";
+
+declare const useEffectOnce: (effect: EffectCallback) => void;
+```

docs/zh/lifecycles/useLifecycles.md

@@ -0,0 +1,25 @@
+# useLifecycles
+
+> **致谢：** Re-export from [react-use](https://github.com/streamich/react-use)
+
+React 生命周期 Hook，用于在组件挂载时调用 `mount` 回调，在组件卸载时调用 `unmount` 回调
+
+## 示例
+
+```tsx
+import { useLifecycles } from "@lynx-js/react-use";
+
+const Demo = () => {
+  useLifecycles(
+    () => console.log("MOUNTED"),
+    () => console.log("UNMOUNTED")
+  );
+  return null;
+};
+```
+
+## 类型定义
+
+```ts
+declare const useLifecycles: (mount: any, unmount?: any) => void;
+```

docs/zh/lifecycles/useMountedState.md

@@ -0,0 +1,36 @@
+# useMountedState
+
+> **致谢：** Re-export from [react-use](https://github.com/streamich/react-use)
+
+> **注意！**：尽管名称中包含 `State`，但**_此 Hook 不会导致组件重新渲染_**。  
+> 此组件旨在用于避免在已卸载的组件上更新状态。
+
+生命周期 Hook，提供检查组件挂载状态的能力。  
+返回一个函数，如果组件已挂载则返回 `true`，否则返回 `false`。
+
+## 示例
+
+```tsx
+import { useEffect } from "@lynx-js/react";
+import { useMountedState } from "@lynx-js/react-use";
+
+const Demo = () => {
+  const isMounted = useMountedState();
+
+  useEffect(() => {
+    setTimeout(() => {
+      if (isMounted()) {
+        // ...
+      } else {
+        // ...
+      }
+    }, 1000);
+  });
+};
+```
+
+## 类型定义
+
+```ts
+function useMountedState(): () => boolean;
+```

docs/zh/lifecycles/useUnmount.md

@@ -0,0 +1,24 @@
+# useUnmount
+
+> **致谢：** Re-export from [react-use](https://github.com/streamich/react-use)
+
+React 生命周期 Hook，在组件即将卸载时调用一个函数。如果你需要同时使用挂载和卸载函数，请使用 `useLifecycles`。
+
+## 示例
+
+```tsx
+import { useUnmount } from "@lynx-js/react-use";
+
+const Demo = () => {
+  useUnmount(() => {
+    console.log("UNMOUNTED");
+  });
+  return null;
+};
+```
+
+## 类型定义
+
+```ts
+declare const useUnmount: (fn: () => any) => void;
+```