feat(hooks): refactor useControllableValue with useLatestCallback and shallowEqual

- Replace `useLatestRef` with `useLatestCallback` for better callback handling
- Use `shallowEqual` from `fast-equals` to compare state changes
- Rename internal functions `getValue` to `getState` and `getDefaultValue` to `getDefaultState`
- Update type definitions and improve equality checks in state updates
- Add `fast-equals` as a dependency in package.json and lockfile

Author: nuintun

packages/examples/app/js/hooks/useControllableValue.ts

@@ -3,9 +3,10 @@
  */
 
 import useIsMounted from './useIsMounted';
-import useLatestRef from './useLatestRef';
+import { shallowEqual } from 'fast-equals';
 import { isFunction } from '/js/utils/utils';
-import React, { useCallback, useEffect, useState } from 'react';
+import React, { useEffect, useState } from 'react';
+import useLatestCallback from './useLatestCallback';
 
 export interface Props {
   [prop: string]: any;
@@ -54,22 +55,22 @@ function isControlled<V>(props: Props, options: Options<V>): boolean {
 }
 
 /**
- * @function getValue
+ * @function getState
  * @param props 组件 Props
  * @param options 配置选项
  */
-function getValue<V>(props: Props, options: Options<V>): V {
+function getState<V>(props: Props, options: Options<V>): V {
   const valuePropName = getValuePropName(options);
 
   return props[valuePropName];
 }
 
 /**
- * @function getDefaultValue
+ * @function getDefaultState
  * @param props 组件 Props
  * @param options 配置选项
  */
-function getDefaultValue<V>(props: Props, options: Options<V>): V {
+function getDefaultState<V>(props: Props, options: Options<V>): V {
   const defaultValuePropName = getDefaultValuePropName(options);
 
   return props[defaultValuePropName];
@@ -106,49 +107,43 @@ export default function useControllableValue<V = undefined>(
   options: Options<V> = {}
 ): [value: V | undefined, setValue: SetValueAction<V | undefined>] {
   const isMounted = useIsMounted();
-  const propsRef = useLatestRef(props);
-  const optionsRef = useLatestRef(options);
 
-  const [value = options.defaultValue, setState] = useState<V | undefined>(() => {
+  const [currentState = options.defaultValue, setState] = useState<V | undefined>(() => {
     if (isControlled(props, options)) {
-      return getValue(props, options);
+      return getState(props, options);
     }
 
-    return getDefaultValue(props, options);
+    return getDefaultState(props, options);
   });
 
-  const valueRef = useLatestRef(value);
-
-  const setValue = useCallback((value: React.SetStateAction<V | undefined>, ...args: any[]): void => {
+  const setValue = useLatestCallback((value: React.SetStateAction<V | undefined>, ...args: unknown[]): void => {
     if (isMounted()) {
-      const { current: prevState } = valueRef;
-      const state = isFunction(value) ? value(prevState) : value;
+      const state = currentState ?? options.defaultValue;
+      const nextState = isFunction(value) ? value(state) : value;
 
-      if (state !== prevState) {
-        const { current: props } = propsRef;
+      if (!shallowEqual(nextState, state)) {
         const { trigger = 'onChange' } = props;
-        const { current: options } = optionsRef;
 
         if (!isControlled(props, options)) {
-          setState(state);
+          setState(nextState);
         }
 
         if (isFunction(props[trigger])) {
-          props[trigger](state, ...args);
+          props[trigger](nextState, ...args);
         }
       }
     }
-  }, []);
+  });
 
   useEffect(() => {
     if (isControlled(props, options)) {
-      const nextValue = getValue(props, options);
+      const nextState = getState(props, options);
 
-      if (nextValue !== value) {
-        setState(nextValue);
+      if (!shallowEqual(nextState, currentState)) {
+        setState(nextState);
       }
     }
   });
 
-  return [value, setValue];
+  return [currentState, setValue];
 }

packages/examples/app/js/hooks/useLatestCallback.ts

@@ -0,0 +1,28 @@
+/**
+ * @module useLatestCallback
+ */
+
+import { useRef } from 'react';
+import useLatestRef from './useLatestRef';
+
+export interface Callback {
+  (this: unknown, ...args: any[]): any;
+}
+
+/**
+ * @function useLatestCallback
+ * @description [hook] 持久化可获取最新上下文的回调函数
+ * @param callback 待处理的回调函数
+ */
+export default function useLatestCallback<C extends Callback>(callback: C): C {
+  const callbackRef = useLatestRef(callback);
+  const latestCallbackRef = useRef<C | null>(null);
+
+  if (latestCallbackRef.current == null) {
+    latestCallbackRef.current = function (this, ...args) {
+      return callbackRef.current.apply(this, args);
+    } as C;
+  }
+
+  return latestCallbackRef.current;
+}

packages/examples/app/js/hooks/useLatestRef.ts

@@ -6,22 +6,29 @@ import React, { useMemo, useRef } from 'react';
 
 /**
  * @function useLatestRef
- * @description 生成自更新 useRef 对象
+ * @description [hook] 生成自更新 useRef 对象
+ * @param value 引用值
  */
-export default function useLatestRef<T = undefined>(): React.RefObject<T | undefined>;
+export default function useLatestRef<T>(value: T): React.RefObject<T>;
 /**
  * @function useLatestRef
- * @description 生成自更新 useRef 对象
+ * @description [hook] 生成自更新 useRef 对象
  * @param value 引用值
  */
-export default function useLatestRef<T>(value: T): React.RefObject<T>;
+export default function useLatestRef<T>(value: T | null): React.RefObject<T | null>;
+/**
+ * @function useLatestRef
+ * @description [hook] 生成自更新 useRef 对象
+ * @param value 引用值
+ */
+export default function useLatestRef<T>(value: T | undefined): React.RefObject<T | undefined>;
 /**
  * @function useLatestRef
- * @description 生成自更新 useRef 对象
+ * @description [hook] 生成自更新 useRef 对象
  * @param value 引用值
  */
-export default function useLatestRef<T = undefined>(value?: T): React.RefObject<T | undefined> {
-  const valueRef = useRef(value);
+export default function useLatestRef<T>(value: T | null | undefined): React.RefObject<T | null | undefined> {
+  const valueRef = useRef<T | null | undefined>(value);
 
   // https://github.com/alibaba/hooks/issues/728
   valueRef.current = useMemo(() => value, [value]);

packages/examples/package.json

@@ -28,6 +28,7 @@
     "chardet": "^2.1.0",
     "classnames": "^2.5.1",
     "copy-to-clipboard": "^3.3.3",
+    "fast-equals": "^5.3.2",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "react-error-boundary": "^6.0.0"