docs: enhance tip

sheinsight · Sep 4, 2024 · fa3d3ad · fa3d3ad
1 parent 924cd57
commit fa3d3ad
Show file tree

Hide file tree

Showing 116 changed files with 266 additions and 224 deletions.
diff --git a/docs/docs/en/docs/features/element-target.md b/docs/docs/en/docs/features/element-target.md
@@ -55,7 +55,9 @@ This Hook has been used in many core functionalities of `@shined/react-use`, suc
 ### ElementTarget Types {#element-target-types}
 
 :::tip Tip
+
 The "🚥" prefix indicates it can be a Getter function, especially useful in SSR. The "⚛️" prefix indicates it can be a `Ref` containing it.
+
 :::
 
 - 🚥 ⚛️ **window/document**: The global window or document object.

diff --git a/docs/docs/en/docs/features/ref-getter.md b/docs/docs/en/docs/features/ref-getter.md
@@ -19,9 +19,11 @@ A Ref Getter is a function specially designed to access the current value of a R
 It's important to note that **components will not re-render when the Ref value changes**, so please do not use the Ref Getter for UI rendering. If you need to trigger re-renders based on changes, it's recommended to use `useState` or `useReducer`.
 
 :::tip Tip
+
 Choosing to use Ref and its Getter is fundamentally a performance trade-off, allowing developers to effectively manage state while avoiding unnecessary re-renders. However, it is critical to use this pattern cautiously, as overuse or misuse can lead to complexity or unintended behaviors in React applications.
 
 This delicate balance ensures that your application retains its performance while still being able to respond to dynamic demands without sacrificing React's principles of reactivity.
+
 :::
 
 ## useGetterRef {#use-getter-ref}

diff --git a/docs/docs/en/docs/usage-guide.mdx b/docs/docs/en/docs/usage-guide.mdx
@@ -4,8 +4,10 @@
 
 Below are some common usage guidelines to help you better utilize `@shined/react-use`.
 
-:::tip Note
+:::tip TIP
+
 The following includes only a part of the common scenarios, following best practices. Please choose according to the specific situation.
+
 :::
 
 ## Replace useState \{#replace-use-state}

diff --git a/docs/docs/zh-cn/docs/usage-guide.mdx b/docs/docs/zh-cn/docs/usage-guide.mdx
@@ -5,7 +5,9 @@
 以下是一些常见场景的使用指引，以帮助你更好地使用 `@shined/react-use`。
 
 :::tip 提示
+
 以下仅包含部分常见场景的使用指引，遵循最佳实践，具体使用请根据实际情况选择。
+
 :::
 
 ## 替换 useState \{#replace-use-state}

diff --git a/docs/src/components/index.ts b/docs/src/components/index.ts
@@ -11,7 +11,6 @@ export * from './react-use-icon'
 export * from './select'
 export * from './since'
 export * from './source'
-export * from './tip'
 export * from './zone'
 
 export * from '../utils'
diff --git a/docs/src/components/tip.tsx b/docs/src/components/tip.tsx
diff --git a/packages/react-use/src/use-async-effect/index.mdx b/packages/react-use/src/use-async-effect/index.mdx
@@ -10,10 +10,12 @@ import { HooksType } from '@/components'
 
 A React Hook similar to [React.useEffect](https://react.dev/reference/react/useEffect), but supports **cancellable** **asynchronous** functions.
 
-:::warning Warning
+:::note Note
+
 It should not return a cleanup function, as it is `async` and cannot synchronously return a cleanup function to be executed as expected.
 
 If you need to clean up something, please use `isCancelled()` within `UseAsyncEffectCallback` to check the status of the Effect.
+
 :::
 
 ## Scenes \{#scenes}

diff --git a/packages/react-use/src/use-async-effect/index.zh-cn.mdx b/packages/react-use/src/use-async-effect/index.zh-cn.mdx
@@ -10,10 +10,12 @@ import { HooksType } from '@/components'
 
 一个类似于 [React.useEffect](https://react.dev/reference/react/useEffect) 的 React Hook，但支持**可取消**的**异步**函数。
 
-:::warning 注意
+:::note 注意
+
 它不应该返回一个清理函数，因为它是 `async` 的，无法同步返回清理函数并按预期进行清理。
 
 如果你需要清理一些东西，请在 `UseAsyncEffectCallback` 中使用 `isCancelled()` 来检查 Effect 的状态。
+
 :::
 
 ## 场景 Scenes \{#scenes}

diff --git a/packages/react-use/src/use-async-update-effect/index.mdx b/packages/react-use/src/use-async-update-effect/index.mdx
@@ -11,10 +11,12 @@ import { HooksType } from '@/components'
 
 A React Hook which is like [useAsyncEffect](/reference/use-async-effect) but **ignore the execution at first mount**.
 
-:::note
+:::note Note
+
 It should not return a cleanup function as it's `async` which cannot cleanup as expected.
 
 If you need to cleanup something, use `isCancelled` in `UseAsyncEffectCallback` instead to check effect status.
+
 :::
 
 ## Demo

diff --git a/packages/react-use/src/use-async-update-effect/index.zh-cn.mdx b/packages/react-use/src/use-async-update-effect/index.zh-cn.mdx
@@ -11,10 +11,12 @@ import { HooksType } from '@/components'
 
 一个 React 钩子，与 [useAsyncEffect](/reference/use-async-effect) 类似，但是 **在首次挂载时忽略执行**。
 
-:::note
+:::note 注意
+
 由于是 `async` 的，它不应该返回一个清理函数，因为无法按预期进行清理。
 
 如果你需要清理一些内容，使用 `UseAsyncEffectCallback` 中的 `isCancelled` 来检查 Effect 的状态。
+
 :::
 
 ## 演示 \{#demo}

diff --git a/packages/react-use/src/use-boolean/index.mdx b/packages/react-use/src/use-boolean/index.mdx
@@ -13,7 +13,9 @@ import { HooksType, Since } from '@/components'
 A React Hook for managing `boolean` state.
 
 :::tip Tip
+
 If you need to manage the alternating states of multiple values (such as toggling between multiple languages, themes, etc.), it is recommended to use [useCircularList](/reference/use-circular-list).
+
 :::
 
 ## Scenes \{#scenes}

diff --git a/packages/react-use/src/use-boolean/index.zh-cn.mdx b/packages/react-use/src/use-boolean/index.zh-cn.mdx
@@ -12,8 +12,10 @@ import { HooksType, Since } from '@/components'
 
 一个用于帮助管理 `boolean` 状态的 React Hook。
 
-:::tip 小提示
+:::tip 提示
+
 如果你需要管理多个值的循环交替状态（如切换多语言、多主题等），建议使用 [useCircularList](/reference/use-circular-list)。
+
 :::
 
 ## 场景 Scenes \{#scenes}

diff --git a/packages/react-use/src/use-circular-list/index.mdx b/packages/react-use/src/use-circular-list/index.mdx
@@ -10,7 +10,7 @@ import { HooksType } from '@/components'
 
 A React Hook that helps to create a circular list that can cycle through the list.
 
-:::tip
+:::tip Tip
 
 If you need to manage a state that toggle between two stable values, consider utilizing [useToggle](/reference/use-toggle) as an alternative.
 

diff --git a/packages/react-use/src/use-click-outside/index.mdx b/packages/react-use/src/use-click-outside/index.mdx
@@ -34,9 +34,9 @@ useClickOutside(elementTarget, callback, options)
 
 ### ElementTarget
 
-import { Tip } from '@/components'
+`ElementTarget` is a union type that represents various kinds of elements that can be targeted.
 
-<Tip type="target" />
+See [ElementTarget](/docs/fearetus/element-target) or [ElementTarget Types](/docs/fearetus/element-target#element-target-types) for more details.
 
 ### Callback
 

diff --git a/packages/react-use/src/use-click-outside/index.zh-cn.mdx b/packages/react-use/src/use-click-outside/index.zh-cn.mdx
@@ -34,9 +34,9 @@ useClickOutside(elementTarget, callback, options)
 
 ### 元素目标 ElementTarget \{#element-target}
 
-import { Tip } from '@/components'
+`ElementTarget` 是一个联合类型，代表可以被定位的各种元素。
 
-<Tip type="target" />
+更多详情，请参见 [ElementTarget](/docs/fearetus/element-target) 或 [ElementTarget 类型](/docs/fearetus/element-target#element-target-types)。
 
 ### 回调函数 Callback \{#callback}
 

diff --git a/packages/react-use/src/use-countdown/index.mdx b/packages/react-use/src/use-countdown/index.mdx
@@ -75,9 +75,9 @@ export type UseCountdownOptions<Controls extends boolean = false> = {
 
 ### Returns
 
-import { Tip } from '@/components'
+Retuerns contain [Pausable](/docs/react-use/pausable) instance that can be paused, resumed.
 
-<Tip type="pausable" />
+See [Pausable](/docs/react-use/pausable) for more details.
 
 ```tsx
 export type UseCountdownReturns<Controls extends boolean> = Controls extends true ? { ms: number } & Pausable : number

diff --git a/packages/react-use/src/use-countdown/index.zh-cn.mdx b/packages/react-use/src/use-countdown/index.zh-cn.mdx
@@ -75,9 +75,9 @@ export type UseCountdownOptions<Controls extends boolean = false> = {
 
 ### 返回值 \{#returns}
 
-import { Tip } from '@/components'
+返回值中包含可暂停、恢复的 [Pausable](/docs/features/pausable) 实例。
 
-<Tip type="pausable" />
+更多详情，请参见 [Pausable](/docs/features/pausable)。
 
 ```tsx
 export type UseCountdownReturns<Controls extends boolean> = Controls extends true ? { ms: number } & Pausable : number

diff --git a/packages/react-use/src/use-css-var/index.mdx b/packages/react-use/src/use-css-var/index.mdx
@@ -59,9 +59,9 @@ export type UseCssVarOptions = {
 
 ### ElementTarget
 
-import { Tip } from '@/components'
+`ElementTarget` is a union type that represents various kinds of elements that can be targeted.
 
-<Tip type="target" />
+See [ElementTarget](/docs/fearetus/element-target) or [ElementTarget Types](/docs/fearetus/element-target#element-target-types) for more details.
 
 `() => document.documentElement` by defaults.
 

diff --git a/packages/react-use/src/use-css-var/index.zh-cn.mdx b/packages/react-use/src/use-css-var/index.zh-cn.mdx
@@ -59,9 +59,9 @@ export type UseCssVarOptions = {
 
 ### 元素目标 ElementTarget \{#element-target}
 
-import { Tip } from '@/components'
+`ElementTarget` 是一个联合类型，代表可以被定位的各种元素。
 
-<Tip type="target" />
+更多详情，请参见 [ElementTarget](/docs/fearetus/element-target) 或 [ElementTarget 类型](/docs/fearetus/element-target#element-target-types)。
 
 `() => document.documentElement` by defaults.
 

diff --git a/packages/react-use/src/use-date-format/index.mdx b/packages/react-use/src/use-date-format/index.mdx
@@ -10,8 +10,10 @@ import { HooksType } from '@/components'
 
 A dependency-free React Hook to format date using symbols, similar to the `format` function found in libraries such as [dayjs](https://day.js.org/docs/en/display/format), [momentjs](https://momentjs.com/docs/#/displaying/format/), or [date-fns](https://date-fns.org/docs/format).
 
-:::tip
+:::tip Tip
+
 By default, the formatting behavior aligns with that of `dayjs`, `momentjs`, and `date-fns@^1`. You can set `unicodeSymbols` option to `true` to use [Unicde Standard Date Symbols](https://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table), which is similar to `date-fns@^2` and subsequent versions.
+
 :::
 
 ## Demo

diff --git a/packages/react-use/src/use-date-format/index.zh-cn.mdx b/packages/react-use/src/use-date-format/index.zh-cn.mdx
@@ -10,8 +10,10 @@ import { HooksType } from '@/components'
 
 一个无依赖的 React Hook，用于使用符号格式化日期，类似于诸如 [dayjs](https://day.js.org/docs/en/display/format)、[momentjs](https://momentjs.com/docs/#/displaying/format/) 或 [date-fns](https://date-fns.org/docs/format) 等库中的 `format` 函数。
 
-:::tip
+:::tip 提示
+
 默认情况下，格式化行为与 `dayjs`、`momentjs` 和 `date-fns@^1` 一致。您可以将 `unicodeSymbols` 选项设置为 `true` 以使用 [Unicode 标准日期符号](https://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table)，这类似于 `date-fns@^2` 及以后版本。
+
 :::
 
 ## 演示 \{#demo}

diff --git a/packages/react-use/src/use-draggable/index.mdx b/packages/react-use/src/use-draggable/index.mdx
@@ -36,9 +36,9 @@ const draggable = useDraggable(elementTarget, options)
 
 ### ElementTarget
 
-import { Tip } from '@/components'
+`ElementTarget` is a union type that represents various kinds of elements that can be targeted.
 
-<Tip type="target" />
+See [ElementTarget](/docs/fearetus/element-target) or [ElementTarget Types](/docs/fearetus/element-target#element-target-types) for more details.
 
 ### Options
 

diff --git a/packages/react-use/src/use-draggable/index.zh-cn.mdx b/packages/react-use/src/use-draggable/index.zh-cn.mdx
@@ -36,9 +36,9 @@ const draggable = useDraggable(elementTarget, options)
 
 ### 元素目标 ElementTarget \{#element-target}
 
-import { Tip } from '@/components'
+`ElementTarget` 是一个联合类型，代表可以被定位的各种元素。
 
-<Tip type="target" />
+更多详情，请参见 [ElementTarget](/docs/fearetus/element-target) 或 [ElementTarget 类型](/docs/fearetus/element-target#element-target-types)。
 
 ### 选项 Options \{#options}
 

diff --git a/packages/react-use/src/use-drop-zone/index.mdx b/packages/react-use/src/use-drop-zone/index.mdx
@@ -36,9 +36,9 @@ const { isOverDropZone, files } = useDropZone(elementTarget, options)
 
 ### ElementTarget
 
-import { Tip } from '@/components'
+`ElementTarget` is a union type that represents various kinds of elements that can be targeted.
 
-<Tip type="target" />
+See [ElementTarget](/docs/fearetus/element-target) or [ElementTarget Types](/docs/fearetus/element-target#element-target-types) for more details.
 
 ### Options
 

diff --git a/packages/react-use/src/use-drop-zone/index.zh-cn.mdx b/packages/react-use/src/use-drop-zone/index.zh-cn.mdx
@@ -36,9 +36,9 @@ const { isOverDropZone, files } = useDropZone(elementTarget, options)
 
 ### 元素目标 ElementTarget \{#element-target}
 
-import { Tip } from '@/components'
+`ElementTarget` 是一个联合类型，代表可以被定位的各种元素。
 
-<Tip type="target" />
+更多详情，请参见 [ElementTarget](/docs/fearetus/element-target) 或 [ElementTarget 类型](/docs/fearetus/element-target#element-target-types)。
 
 ### 选项 Options \{#options}
 

diff --git a/packages/react-use/src/use-element-bounding/index.mdx b/packages/react-use/src/use-element-bounding/index.mdx
@@ -36,9 +36,9 @@ const { update, ...bounding } = useElementBounding(elementTarget, options)
 
 ### ElementTarget
 
-import { Tip } from '@/components'
+`ElementTarget` is a union type that represents various kinds of elements that can be targeted.
 
-<Tip type="target" />
+See [ElementTarget](/docs/fearetus/element-target) or [ElementTarget Types](/docs/fearetus/element-target#element-target-types) for more details.
 
 ### Options
 

diff --git a/packages/react-use/src/use-element-bounding/index.zh-cn.mdx b/packages/react-use/src/use-element-bounding/index.zh-cn.mdx
@@ -36,9 +36,9 @@ const { update, ...bounding } = useElementBounding(elementTarget, options)
 
 ### 元素目标 ElementTarget \{#element-target}
 
-import { Tip } from '@/components'
+`ElementTarget` 是一个联合类型，代表可以被定位的各种元素。
 
-<Tip type="target" />
+更多详情，请参见 [ElementTarget](/docs/fearetus/element-target) 或 [ElementTarget 类型](/docs/fearetus/element-target#element-target-types)。
 
 ### 选项 Options \{#options}
 

diff --git a/packages/react-use/src/use-element-by-point/index.mdx b/packages/react-use/src/use-element-by-point/index.mdx
@@ -60,9 +60,9 @@ export type UseElementByPointOptions<M extends boolean = false> = Position & {
 
 ### Returns
 
-import { Tip } from '@/components'
+Retuerns contain [Pausable](/docs/features/pausable) instance that can be paused, resumed.
 
-<Tip type="pausable" />
+See [Pausable](/docs/features/pausable) for more details.
 
 ```tsx
 export type UseElementByPointReturns<E extends Element | null | Element[]> = Pausable & {

diff --git a/packages/react-use/src/use-element-by-point/index.zh-cn.mdx b/packages/react-use/src/use-element-by-point/index.zh-cn.mdx
@@ -60,9 +60,9 @@ export type UseElementByPointOptions<M extends boolean = false> = Position & {
 
 ### 返回值 \{#returns}
 
-import { Tip } from '@/components'
+返回值中包含可暂停、恢复的 [Pausable](/docs/features/pausable) 实例。
 
-<Tip type="pausable" />
+更多详情，请参见 [Pausable](/docs/features/pausable)。
 
 ```tsx
 export type UseElementByPointReturns<E extends Element | null | Element[]> = Pausable & {

diff --git a/packages/react-use/src/use-element-size/index.mdx b/packages/react-use/src/use-element-size/index.mdx
@@ -36,9 +36,9 @@ const { width, height, ...useResizeObserverReturns } = useElementSize(elementTar
 
 ### ElementTarget
 
-import { Tip } from '@/components'
+`ElementTarget` is a union type that represents various kinds of elements that can be targeted.
 
-<Tip type="target" />
+See [ElementTarget](/docs/fearetus/element-target) or [ElementTarget Types](/docs/fearetus/element-target#element-target-types) for more details.
 
 ### DefaultValue
 

diff --git a/packages/react-use/src/use-element-size/index.zh-cn.mdx b/packages/react-use/src/use-element-size/index.zh-cn.mdx
@@ -36,9 +36,9 @@ const { width, height, ...useResizeObserverReturns } = useElementSize(elementTar
 
 ### 元素目标 ElementTarget \{#element-target}
 
-import { Tip } from '@/components'
+`ElementTarget` 是一个联合类型，代表可以被定位的各种元素。
 
-<Tip type="target" />
+更多详情，请参见 [ElementTarget](/docs/fearetus/element-target) 或 [ElementTarget 类型](/docs/fearetus/element-target#element-target-types)。
 
 ### 默认值 DefaultValue \{#default-value}
 

diff --git a/packages/react-use/src/use-element-visibility/index.mdx b/packages/react-use/src/use-element-visibility/index.mdx
@@ -36,9 +36,9 @@ const visibility = useElementVisibility(elementTarget, options)
 
 ### ElementTarget
 
-import { Tip } from '@/components'
+`ElementTarget` is a union type that represents various kinds of elements that can be targeted.
 
-<Tip type="target" />
+See [ElementTarget](/docs/fearetus/element-target) or [ElementTarget Types](/docs/fearetus/element-target#element-target-types) for more details.
 
 ### Options
 

diff --git a/packages/react-use/src/use-element-visibility/index.zh-cn.mdx b/packages/react-use/src/use-element-visibility/index.zh-cn.mdx
@@ -36,9 +36,9 @@ const visibility = useElementVisibility(elementTarget, options)
 
 ### 元素目标 ElementTarget \{#element-target}
 
-import { Tip } from '@/components'
+`ElementTarget` 是一个联合类型，代表可以被定位的各种元素。
 
-<Tip type="target" />
+更多详情，请参见 [ElementTarget](/docs/fearetus/element-target) 或 [ElementTarget 类型](/docs/fearetus/element-target#element-target-types)。
 
 ### 选项 Options \{#options}