chore: modify documentation & TS type

biome.json

@@ -26,6 +26,9 @@
     "enabled": true,
     "rules": {
       "recommended": true,
+      "style": {
+        "noInferrableTypes": "off"
+      },
       "correctness": {
         "useExhaustiveDependencies": {
           "level": "warn",

src/create-single-loading/index.mdx

@@ -49,13 +49,13 @@ export interface CreateSingleLoadingOptions {
   /**
    * Whether set to false on error
    *
-   * @default true
+   * @defaultValue true
    */
   resetOnError?: boolean
   /**
    * Initial loading state
    *
-   * @default false
+   * @defaultValue false
    */
   initialState?: boolean
 }
@@ -64,33 +64,49 @@ export interface CreateSingleLoadingOptions {
 ### Returns
 
 ```tsx
-export interface useAsyncFnExtendReturn<T extends AnyFunc> extends UseAsyncFnReturn<T> {
+export interface UseAsyncFnExtendReturns<T extends AnyFunc> extends UseAsyncFnReturns<T> {
   /**
    * Set the loading state
+   *
+   * @param {boolean} value - `boolean`, the loading value to set
+   * @returns {void} `void`
    */
   setLoading: (value: boolean) => void
 }
 
-export interface CreateSingleLoadingReturn {
+export interface CreateSingleLoadingReturns {
   /**
-   * Use loading state with async function via Hook in React
+   * A Hook in React to use bound async function with loading state
+   *
+   * @param {AnyFunc} asyncFn - `AnyFunc`, the async function to bind, see {@link AnyFunc}
+   * @returns {UseAsyncFnExtendReturns} see {@link UseAsyncFnExtendReturns}
    */
-  useAsyncFn: <T extends AnyFunc>(func: T) => useAsyncFnExtendReturn<T>
+  useAsyncFn: <T extends AnyFunc>(asyncFn: T) => UseAsyncFnExtendReturns<T>
   /**
-   * Use loading state via Hook in React
+   * A Hook in React to use loading state
+   *
+   * @returns {boolean} `boolean`, the loading state
    */
   useLoading(): boolean
   /**
    * Set the loading state via store in JS/TS
+   *
+   * @param {boolean} value - `boolean`, the value to set
+   * @returns {void} `void`
    */
-  set(value: boolean): void
+  set: (value: boolean) => void
   /**
    * Get the loading state via store in JS/TS
+   *
+   * @returns {boolean} `boolean`, the loading state
    */
   get(): boolean
   /**
    * Bind the loading state to the async function in JS/TS
+   *
+   * @param {AnyFunc} asyncFn - `AnyFunc`, the async function to bind, see {@link AnyFunc}
+   * @returns {AnyFunc} `AnyFunc`, same as `asyncFn` param, see {@link AnyFunc}
    */
-  bind: <T extends AnyFunc>(func: T) => T
+  bind: <T extends AnyFunc>(asyncFn: T) => T
 }
 ```

src/create-single-loading/index.ts

@@ -1,60 +1,81 @@
 import { create } from '@shined/reactive'
 import { useAsyncFn as useAsyncFnOrigin } from '../use-async-fn'
 
-import type { ReactNode } from 'react'
-import type { UseAsyncFnReturn } from '../use-async-fn'
+import type { UseAsyncFnReturns } from '../use-async-fn'
 import type { AnyFunc } from '../utils/basic'
 
-export interface UseSingleLoadingProviderProps {
-  children: ReactNode | undefined
-}
-
-export interface useAsyncFnExtendReturn<T extends AnyFunc> extends UseAsyncFnReturn<T> {
+export interface UseAsyncFnExtendReturns<T extends AnyFunc> extends UseAsyncFnReturns<T> {
   /**
    * Set the loading state
+   *
+   * @param {boolean} value - `boolean`, the loading value to set
+   * @returns {void} `void`
    */
   setLoading: (value: boolean) => void
 }
 
-export interface CreateSingleLoadingReturn {
+export interface CreateSingleLoadingReturns {
   /**
    * A Hook in React to use bound async function with loading state
+   *
+   * @param {AnyFunc} asyncFn - `AnyFunc`, the async function to bind, see {@link AnyFunc}
+   * @returns {UseAsyncFnExtendReturns} see {@link UseAsyncFnExtendReturns}
    */
-  useAsyncFn: <T extends AnyFunc>(func: T) => useAsyncFnExtendReturn<T>
+  useAsyncFn: <T extends AnyFunc>(asyncFn: T) => UseAsyncFnExtendReturns<T>
   /**
    * A Hook in React to use loading state
+   *
+   * @returns {boolean} `boolean`, the loading state
    */
   useLoading(): boolean
   /**
    * Set the loading state via store in JS/TS
+   *
+   * @param {boolean} value - `boolean`, the value to set
+   * @returns {void} `void`
    */
   set: (value: boolean) => void
   /**
    * Get the loading state via store in JS/TS
+   *
+   * @returns {boolean} `boolean`, the loading state
    */
   get(): boolean
   /**
    * Bind the loading state to the async function in JS/TS
+   *
+   * @param {AnyFunc} asyncFn - `AnyFunc`, the async function to bind, see {@link AnyFunc}
+   * @returns {AnyFunc} `AnyFunc`, same as `asyncFn` param, see {@link AnyFunc}
    */
-  bind: <T extends AnyFunc>(func: T) => T
+  bind: <T extends AnyFunc>(asyncFn: T) => T
 }
 
 export interface CreateSingleLoadingOptions {
   /**
    * Whether set to false on error
    *
-   * @default true
+   * @defaultValue true
    */
   resetOnError?: boolean
   /**
    * Initial loading state
    *
-   * @default false
+   * @defaultValue false
    */
   initialState?: boolean
 }
 
-export function createSingleLoading(options: CreateSingleLoadingOptions = {}): CreateSingleLoadingReturn {
+/**
+ * A utility that provide a way to manage single (or global) loading state via multiple Hooks or simple JS/TS functions, using [Reactive](https://sheinsight.github.io/reactive/) under the hood.
+ *
+ * You need to install `@shined/reactive` to use this utility.
+ *
+ * @param {CreateSingleLoadingOptions} options {@link CreateSingleLoadingOptions}
+ * @returns {CreateSingleLoadingReturns} `CreateSingleLoadingReturns`, single loading instance, see {@link CreateSingleLoadingReturns}
+ *
+ * @see {@link https://sheinsight.github.io/reactive/ | Reactive - Documentation}
+ */
+export function createSingleLoading(options: CreateSingleLoadingOptions = {}): CreateSingleLoadingReturns {
   const { resetOnError = true, initialState = false } = options
   const store = create({ loading: initialState })
 

src/use-active-element/index.mdx

@@ -4,7 +4,7 @@ import { HooksType } from '@/components'
 
 <HooksType category="Element" lowLevel />
 
-A React Hook that returns the currently **active element** (via `document.activeElement`).
+A React Hook that returns the currently **active element** (via `document.activeElement`), optionally traversing the shadow DOM.
 
 ## Demo
 

src/use-active-element/index.ts

@@ -6,13 +6,16 @@ export interface UseActiveElementOptions {
   /**
    * Whether to traverse the shadow DOM to find the active element
    *
-   * @default true
+   * @defaultValue false
    */
   deep?: boolean
 }
 
 /**
- * use the active element, optionally traversing the shadow DOM
+ * A React Hook that returns the currently **active element** (via `document.activeElement`), optionally traversing the shadow DOM.
+ *
+ * @param {UseActiveElementOptions} options - `UseActiveElementOptions`, options to configure the hook, see {@link UseActiveElementOptions}
+ * @returns {Element | null} `Element | null`, the currently active element, `null` if there is none, see {@link Element}
  */
 export function useActiveElement(options: UseActiveElementOptions = {}): Element | null {
   const [element, setElement] = useSafeState<Element | null>(null)
@@ -36,9 +39,11 @@ export function useActiveElement(options: UseActiveElementOptions = {}): Element
 }
 
 /**
- * find the active element, optionally traversing the shadow DOM
+ * Get the currently active element, optionally traversing the shadow DOM.
+ *
+ * @param {boolean} [deep=false] - `boolean`, Whether to traverse the shadow DOM to find the active element
  */
-function getActiveElement(deep = false): Element | null {
+function getActiveElement(deep: boolean = false): Element | null {
   let element = document.activeElement
 
   if (deep) {

src/use-adaptive-textarea/index.mdx

@@ -4,11 +4,11 @@ import { HooksType } from '@/components'
 
 <HooksType category="Element" />
 
-A React Hook that helps to create **adaptive** textarea.
+A React Hook that helps to create **adaptive** textarea that automatically adjust height based on its content.
 
 ## Demo
 
-Input and feel free to wrap the text in the textarea.
+Input in the textarea, and see the height of the textarea automatically adjust.
 
 import { App } from './demo'
 
@@ -36,41 +36,41 @@ const { ref, height, resize } = useAdaptiveTextarea(options)
 ### Options
 
 ```tsx
-export type UseAdaptiveTextareaOptions<T extends HTMLElement = HTMLElement> = {
+export interface UseAdaptiveTextareaOptions<T extends HTMLElement = HTMLElement> {
   /**
    * a list of dependencies to trigger the resize
    *
-   * @default []
+   * @defaultValue []
    */
   watch?: DependencyList
   /**
    * a list of events to trigger the resize
    *
-   * @default ['input']
+   * @defaultValue ['input']
    */
   events?: (keyof HTMLElementEventMap)[]
   /**
    * whether to automatically adjust the height of the `textarea` element
    *
-   * @default true
+   * @defaultValue true
    */
   autoHeight?: boolean
   /**
    * a target element to apply the height style
    *
-   * @default undefined
+   * @defaultValue undefined
    */
   styleTarget?: ElementTarget<T>
   /**
    * a style property to apply the height value
    *
-   * @default 'height'
+   * @defaultValue 'height'
    */
   styleProp?: 'height' | 'minHeight'
   /**
    * a callback function to be called when the height of the `textarea` element changes
    *
-   * @default undefined
+   * @defaultValue undefined
    */
   onResize?: (height: number, prevHeight: number) => void
 }
@@ -79,7 +79,7 @@ export type UseAdaptiveTextareaOptions<T extends HTMLElement = HTMLElement> = {
 ### Returns
 
 ```tsx
-export type UseAdaptiveTextareaReturn = {
+export interface UseAdaptiveTextareaReturns {
   /**
    * a React ref that should be passed to the `textarea` element
    */
@@ -90,6 +90,8 @@ export type UseAdaptiveTextareaReturn = {
   height: number
   /**
    * a function to manually resize the `textarea` element
+   *
+   * @returns {void} `void`
    */
   resize(): void
 }

src/use-adaptive-textarea/index.ts

@@ -13,42 +13,42 @@ export interface UseAdaptiveTextareaOptions<T extends HTMLElement = HTMLElement>
   /**
    * a list of dependencies to trigger the resize
    *
-   * @default []
+   * @defaultValue []
    */
   watch?: DependencyList
   /**
    * a list of events to trigger the resize
    *
-   * @default ['input']
+   * @defaultValue ['input']
    */
   events?: (keyof HTMLElementEventMap)[]
   /**
    * whether to automatically adjust the height of the `textarea` element
    *
-   * @default true
+   * @defaultValue true
    */
   autoHeight?: boolean
   /**
    * a target element to apply the height style
    *
-   * @default undefined
+   * @defaultValue undefined
    */
   styleTarget?: ElementTarget<T>
   /**
    * a style property to apply the height value
    *
-   * @default 'height'
+   * @defaultValue 'height'
    */
   styleProp?: 'height' | 'minHeight'
   /**
    * a callback function to be called when the height of the `textarea` element changes
    *
-   * @default undefined
+   * @defaultValue undefined
    */
   onResize?: (height: number, prevHeight: number) => void
 }
 
-export interface UseAdaptiveTextareaReturn {
+export interface UseAdaptiveTextareaReturns {
   /**
    * a React ref that should be passed to the `textarea` element
    */
@@ -59,18 +59,21 @@ export interface UseAdaptiveTextareaReturn {
   height: number
   /**
    * a function to manually resize the `textarea` element
+   *
+   * @returns {void} `void`
    */
   resize(): void
 }
 
 /**
- * Automatically adjust the height of a `textarea` element based on its content
+ * A React Hook that helps to create **adaptive** textarea that automatically adjust height based on its content.
  *
- * @tip set `rows={1}` attribute & `resize: none` style to the `textarea` before using this Hook
+ * @param {UseAdaptiveTextareaOptions} options - `UseAdaptiveTextareaOptions`, see {@link UseAdaptiveTextareaOptions}
+ * @returns {UseAdaptiveTextareaReturns} `UseAdaptiveTextareaReturns`, see {@link UseAdaptiveTextareaReturns}
  */
 export function useAdaptiveTextarea<T extends HTMLElement>(
   options: UseAdaptiveTextareaOptions<T> = {},
-): UseAdaptiveTextareaReturn {
+): UseAdaptiveTextareaReturns {
   const { onResize, events = ['input'], autoHeight = true, watch = [], styleTarget, styleProp = 'height' } = options
 
   const taRef = useRef<HTMLTextAreaElement>(null)

src/use-async-effect/index.mdx

@@ -6,6 +6,12 @@ import { HooksType } from '@/components'
 
 A React Hook which is like [React.useEffect](https://react.dev/reference/react/useEffect) but support **cancellable** **async** function.
 
+:::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
 
 Toggle the status several times, and you will find that all **obsolete** timers are deleted as expected, although we do not return a cleanup function in effect.