@wwog/react 1.3.12 → 1.3.14

package/src/hooks/useScreen.ts

@@ -1,99 +1,88 @@
-import { useEffect, useState } from "react";
-import {
-  breakpoints,
-  DefBreakpointDesc,
-  type BreakpointDesc,
-  type BreakpointName,
-} from "../utils";
+import {useEffect, useMemo, useRef, useState} from 'react'
+import {type BreakpointDesc, type BreakpointName, DefBreakpointDesc, breakpoints} from '../utils'
 
-const reverseBreakpoints = [...breakpoints].reverse();
+const reverseBreakpoints = [...breakpoints].reverse()
+
+const isBrowser = typeof window !== 'undefined'
 
 export function getCurrentBreakpoint(
   breakpointDesc: BreakpointDesc,
-  width: number
+  width: number,
 ): BreakpointName {
   for (const bp of reverseBreakpoints) {
-    const bpValue = breakpointDesc[bp];
+    const bpValue = breakpointDesc[bp]
     if (bpValue !== undefined && !Number.isNaN(bpValue) && width >= bpValue) {
-      return bp;
+      return bp
     }
   }
-  return "base";
+  return 'base'
 }
 
 export function useScreen(breakpointDesc: BreakpointDesc = DefBreakpointDesc) {
+  // 用 JSON 序列化稳定化对象引用，避免调用方每次传字面量对象导致 effect 无限重跑
+  const stableKey = useMemo(() => JSON.stringify(breakpointDesc), [breakpointDesc])
+  const descRef = useRef(breakpointDesc)
+  descRef.current = breakpointDesc
+
   const [currentBreakpoint, setCurrentBreakpoint] = useState<BreakpointName>(
-    getCurrentBreakpoint(breakpointDesc, window.innerWidth)
-  );
+    // lazy initializer：SSR 环境下 window 不存在，fallback 到 "base"
+    () => (isBrowser ? getCurrentBreakpoint(breakpointDesc, window.innerWidth) : 'base'),
+  )
 
   useEffect(() => {
-    let mediaQueries: MediaQueryList[] = [];
-    let listeners: (() => void)[] = [];
+    if (!isBrowser) return
+
+    let mediaQueries: MediaQueryList[] = []
+    let listeners: (() => void)[] = []
 
     const updateMediaQueries = () => {
-      // 清理旧的监听器
-      listeners.forEach((removeListener) => removeListener());
-      mediaQueries = [];
-      listeners = [];
+      listeners.forEach((removeListener) => removeListener())
+      mediaQueries = []
+      listeners = []
 
-      // 计算当前断点
-      const currentBp = getCurrentBreakpoint(breakpointDesc, window.innerWidth);
-      setCurrentBreakpoint(currentBp);
+      const desc = descRef.current
+      const currentBp = getCurrentBreakpoint(desc, window.innerWidth)
+      setCurrentBreakpoint(currentBp)
 
-      // 找到当前断点的索引
-      const currentIndex = breakpoints.indexOf(currentBp);
+      const currentIndex = breakpoints.indexOf(currentBp)
 
-      // 监听下一个断点（min-width）
-      const nextBp = breakpoints[currentIndex + 1];
-      if (nextBp && breakpointDesc[nextBp] !== undefined) {
-        const nextMinWidth = breakpointDesc[nextBp];
+      const nextBp = breakpoints[currentIndex + 1]
+      if (nextBp && desc[nextBp] !== undefined) {
+        const nextMinWidth = desc[nextBp]
         if (!Number.isNaN(nextMinWidth)) {
-          const mediaQuery = window.matchMedia(
-            `(min-width: ${nextMinWidth}px)`
-          );
-          mediaQueries.push(mediaQuery);
-          const handleMediaChange = () => updateMediaQueries();
-          mediaQuery.addEventListener("change", handleMediaChange);
-          listeners.push(() =>
-            mediaQuery.removeEventListener("change", handleMediaChange)
-          );
+          const mediaQuery = window.matchMedia(`(min-width: ${nextMinWidth}px)`)
+          mediaQueries.push(mediaQuery)
+          const handleMediaChange = () => updateMediaQueries()
+          mediaQuery.addEventListener('change', handleMediaChange)
+          listeners.push(() => mediaQuery.removeEventListener('change', handleMediaChange))
         } else {
-          throw new Error(
-            `Invalid breakpoint value for ${nextBp}: ${breakpointDesc[nextBp]}`
-          );
+          throw new Error(`Invalid breakpoint value for ${nextBp}: ${desc[nextBp]}`)
         }
       }
 
-      // 监听上一个断点（max-width）
-      const prevBp = breakpoints[currentIndex - 1];
-      if (prevBp && breakpointDesc[prevBp] !== undefined) {
-        const prevMinWidth = breakpointDesc[prevBp];
+      const prevBp = breakpoints[currentIndex - 1]
+      if (prevBp && desc[prevBp] !== undefined) {
+        const prevMinWidth = desc[prevBp]
         if (!Number.isNaN(prevMinWidth)) {
-          const mediaQuery = window.matchMedia(
-            `(max-width: ${prevMinWidth - 1}px)`
-          );
-          mediaQueries.push(mediaQuery);
-          const handleMediaChange = () => updateMediaQueries();
-          mediaQuery.addEventListener("change", handleMediaChange);
-          listeners.push(() =>
-            mediaQuery.removeEventListener("change", handleMediaChange)
-          );
+          const mediaQuery = window.matchMedia(`(max-width: ${prevMinWidth - 1}px)`)
+          mediaQueries.push(mediaQuery)
+          const handleMediaChange = () => updateMediaQueries()
+          mediaQuery.addEventListener('change', handleMediaChange)
+          listeners.push(() => mediaQuery.removeEventListener('change', handleMediaChange))
         } else {
-          throw new Error(
-            `Invalid breakpoint value for ${prevBp}: ${breakpointDesc[prevBp]}`
-          );
+          throw new Error(`Invalid breakpoint value for ${prevBp}: ${desc[prevBp]}`)
         }
       }
-    };
+    }
 
-    // 初次执行
-    updateMediaQueries();
+    updateMediaQueries()
 
-    // 清理函数
     return () => {
-      listeners.forEach((removeListener) => removeListener());
-    };
-  }, [breakpointDesc]);
+      listeners.forEach((removeListener) => removeListener())
+    }
+    // stableKey 作为稳定化的依赖，替代直接依赖 breakpointDesc 对象引用
+    // biome-ignore lint/correctness/useExhaustiveDependencies: stableKey is the stable proxy for breakpointDesc object identity
+  }, [stableKey])
 
-  return currentBreakpoint;
+  return currentBreakpoint
 }

package/src/index.ts

@@ -1,7 +1,7 @@
-export * from "./components/ProcessControl";
-export * from "./components/Sundry";
-export * from "./components/Struct";
+export * from './components/ProcessControl'
+export * from './components/Sundry'
+export * from './components/Struct'
 
-export * from "./hooks";
+export * from './hooks'
 
-export * from "./utils";
+export * from './utils'

package/src/utils/constants.ts

@@ -1,13 +1,4 @@
-export const breakpoints = [
-  "base",
-  "xs",
-  "sm",
-  "md",
-  "lg",
-  "xl",
-  "2xl",
-  "3xl",
-] as const;
+export const breakpoints = ['base', 'xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const
 
 export const DefBreakpointDesc: BreakpointDesc = {
   xs: 475,
@@ -15,11 +6,11 @@ export const DefBreakpointDesc: BreakpointDesc = {
   md: 768,
   lg: 1024,
   xl: 1280,
-  "2xl": 1536,
-  "3xl": 1920,
-};
-export type BreakpointName = (typeof breakpoints)[number];
+  '2xl': 1536,
+  '3xl': 1920,
+}
+export type BreakpointName = (typeof breakpoints)[number]
 
-export type BreakpointDesc = Partial<Record<BreakpointName, number>>;
+export type BreakpointDesc = Partial<Record<BreakpointName, number>>
 
-export type Responsive<T> = T | Partial<Record<BreakpointName, T>>;
+export type Responsive<T> = T | Partial<Record<BreakpointName, T>>

package/src/utils/createExternalState.test.tsx

@@ -120,30 +120,49 @@ describe("createExternalState", () => {
     expect(state.__listeners.length).toBe(0);
   });
 
-  it("测试副作用函数", () => {
-    const mockSideEffect = vi.fn((...args) => void 0);
+  it("测试 onSet 每次 set 都会触发", () => {
+    const mockOnSet = vi.fn((...args) => void 0);
     const initialState: string = "initial";
     const state = createExternalState(initialState, {
-      sideEffect: mockSideEffect,
+      onSet: mockOnSet,
     });
     state.set("updated");
-    expect(mockSideEffect).toHaveBeenCalledTimes(1);
-    expect(mockSideEffect).toHaveBeenCalledWith("updated", initialState);
+    expect(mockOnSet).toHaveBeenCalledTimes(1);
+    expect(mockOnSet).toHaveBeenCalledWith("updated", initialState);
+    state.set("updated");
+    expect(mockOnSet).toHaveBeenCalledTimes(2);
+    expect(mockOnSet).toHaveBeenCalledWith("updated", "updated");
+    state.set("updated2");
+    expect(mockOnSet).toHaveBeenCalledTimes(3);
+    expect(mockOnSet).toHaveBeenCalledWith("updated2", "updated");
+  });
+
+  it("测试 onChange 仅在值变化时触发", () => {
+    const mockOnChange = vi.fn((...args) => void 0);
+    const initialState: string = "initial";
+    const state = createExternalState(initialState, {
+      onChange: mockOnChange,
+    });
+    state.set("updated");
+    expect(mockOnChange).toHaveBeenCalledTimes(1);
+    expect(mockOnChange).toHaveBeenCalledWith("updated", initialState);
+    state.set("updated");
+    expect(mockOnChange).toHaveBeenCalledTimes(1);
     state.set("updated2");
-    expect(mockSideEffect).toHaveBeenCalledTimes(2);
-    expect(mockSideEffect).toHaveBeenCalledWith("updated2", "updated");
+    expect(mockOnChange).toHaveBeenCalledTimes(2);
+    expect(mockOnChange).toHaveBeenCalledWith("updated2", "updated");
   });
 
-  it("测试异步副作用函数", async () => {
-    const mockAsyncSideEffect = vi.fn().mockResolvedValue(undefined);
+  it("测试异步 onSet 回调", async () => {
+    const mockAsyncOnSet = vi.fn().mockResolvedValue(undefined);
     const initialState: string = "initial";
     const state = createExternalState(initialState, {
-      sideEffect: mockAsyncSideEffect,
+      onSet: mockAsyncOnSet,
     });
 
     state.set("updated");
-    expect(mockAsyncSideEffect).toHaveBeenCalledTimes(1);
-    expect(mockAsyncSideEffect).toHaveBeenCalledWith("updated", initialState);
+    expect(mockAsyncOnSet).toHaveBeenCalledTimes(1);
+    expect(mockAsyncOnSet).toHaveBeenCalledWith("updated", initialState);
   });
 
   it("测试复杂数据类型", async () => {
@@ -321,17 +340,17 @@ describe("createStorageState", () => {
     consoleSpy.mockRestore();
   });
 
-  it("测试存储副作用函数", () => {
-    const mockSideEffect = vi.fn();
+  it("测试存储 onSet 回调", () => {
+    const mockOnSet = vi.fn();
     const state = createStorageState("test-key", "initial" as string, {
       storageType: "local",
-      sideEffect: mockSideEffect,
+      onSet: mockOnSet,
     });
     
     state.set("updated");
     
-    expect(mockSideEffect).toHaveBeenCalledTimes(1);
-    expect(mockSideEffect).toHaveBeenCalledWith("updated");
+    expect(mockOnSet).toHaveBeenCalledTimes(1);
+    expect(mockOnSet).toHaveBeenCalledWith("updated", "initial");
     expect(localStorage.getItem("test-key")).toBe('"updated"');
   });
 

package/src/utils/createExternalState.ts

@@ -1,24 +1,14 @@
-import React from "react";
-import { safePromiseTry } from "./promise";
+import {useSyncExternalStore} from 'react'
+import {safePromiseTry} from './promise'
 
 /**
- * @en Callback function type for state change listeners
- * @zh 状态变更监听器的回调函数类型
- * @template T The type of the state / 状态的类型
- */
-export type CreateStateListener<T> = (state: T) => void;
-
-/**
- * @zh 如果需要在变更状态时执行副作用，可以传入函数,对于异步函数，会在更改状态后执行，不会阻塞状态更新, 尽可能在外部使用useEffect处理异步副作用
- * @en If you need to perform side effects when changing the state, you can pass a function. For asynchronous functions, it will be executed after the state changes without blocking the state update, so it's best to use useEffect for handling asynchronous side effects.
+ * @zh 状态回调函数。对于异步函数，会在状态更新后执行，不会阻塞状态更新，尽可能在外部使用 useEffect 处理异步副作用。
+ * @en State callback function. Async callbacks run after the state update without blocking it; prefer useEffect for async side effects.
  * @template T The type of the state / 状态的类型
  * @param newState The new state value / 新的状态值
  * @param prevState The previous state value / 之前的状态值
  */
-export type ExternalSideEffect<T> = (
-  newState: T,
-  prevState: T
-) => any | Promise<any>;
+export type ExternalStateCallback<T> = (newState: T, prevState: T) => any | Promise<any>
 
 /**
  * @en Transform functions for getting and setting state
@@ -31,12 +21,12 @@ export interface Transform<T, U = T> {
    * @en Transform function for getting state
    * @zh 获取状态时的转换函数
    */
-  get?: (state: T) => U;
+  get?: (state: T) => U
   /**
    * @en Transform function for setting state
    * @zh 设置状态时的转换函数
    */
-  set?: (value: U) => T;
+  set?: (value: U) => T
 }
 
 /**
@@ -47,15 +37,20 @@ export interface Transform<T, U = T> {
  */
 export interface ExternalStateOptions<T, U = T> {
   /**
-   * @en Side effect function to run after state changes
-   * @zh 状态变更后运行的副作用函数
+   * @en Callback invoked on every `set` call, even when the value is unchanged
+   * @zh 每次调用 `set` 后触发，即使值未发生变化
    */
-  sideEffect?: ExternalSideEffect<T>;
+  onSet?: ExternalStateCallback<T>
+  /**
+   * @en Callback invoked only when the stored value actually changes
+   * @zh 仅在内部存储值发生变化时触发
+   */
+  onChange?: ExternalStateCallback<T>
   /**
    * @en Transform functions for getting and setting state
    * @zh 用于获取和设置状态的转换函数
    */
-  transform?: Transform<T, U>;
+  transform?: Transform<T, U>
 }
 
 /**
@@ -70,31 +65,31 @@ export interface ExternalState<T, U = T> {
    * @zh 获取当前状态值
    * @returns The current state value (transformed if transform.get is provided) / 当前状态值（如果提供了 transform.get 则进行转换）
    */
-  get: () => U;
+  get: () => U
 
   /**
    * @en Set a new state value
    * @zh 设置新的状态值
    * @param newState The new state value or a function that returns it / 新的状态值或返回新状态的函数
    */
-  set: (newState: U | ((prevState: U) => U)) => void;
+  set: (newState: U | ((prevState: U) => U)) => void
 
   /**
    * @en React Hook for using external state in components
    * @zh 在组件中使用外部状态的 React Hook
-   * @returns Array containing current钣金龙8国际唯一官网 current state and update function, similar to useState / 包含当前状态和更新函数的数组，类似于 useState
+   * @returns Array containing current state and update function, similar to useState / 包含当前状态和更新函数的数组，类似于 useState
    */
-  use: () => [U, (newState: U | ((prevState: U) => U)) => void];
+  use: () => [U, (newState: U | ((prevState: U) => U)) => void]
 
   /**
    * @zh use的变体，只获取value.
    * @en A variant of use that only gets the value.
    */
-  useGetter: () => U;
+  useGetter: () => U
 }
 
 export interface ExternalWithKernel<T, U = T> extends ExternalState<T, U> {
-  __listeners: CreateStateListener<T>[];
+  __listeners: (() => void)[]
 }
 
 /**
@@ -103,7 +98,7 @@ export interface ExternalWithKernel<T, U = T> extends ExternalState<T, U> {
  * ```tsx
  * // Create an app-level theme state with options
  * const themeState = createExternalState('light', {
- *   sideEffect: (newState, prevState) => console.log(`Theme changed from ${prevState} to ${newState}`),
+ *   onChange: (newState, prevState) => console.log(`Theme changed from ${prevState} to ${newState}`),
  *   transform: {
  *     get: (state) => state.toUpperCase(),
  *     set: (value) => value.toLowerCase()
@@ -130,117 +125,120 @@ export interface ExternalWithKernel<T, U = T> extends ExternalState<T, U> {
  */
 export function createExternalState<T, U = T>(
   initialState: T | (() => T),
-  options: ExternalStateOptions<T, U> = {}
+  options: ExternalStateOptions<T, U> = {},
 ): ExternalState<T, U> {
-  let state: T =
-    typeof initialState === "function"
-      ? (initialState as () => T)()
-      : initialState;
+  let state: T = typeof initialState === 'function' ? (initialState as () => T)() : initialState
+
+  const storeListeners: (() => void)[] = []
+  const {onSet, onChange, transform} = options
 
-  const listeners: CreateStateListener<T>[] = [];
-  const { sideEffect, transform } = options;
+  const runCallback = (callback: ExternalStateCallback<T> | undefined, newState: T, prevState: T) => {
+    if (!callback) return
+    safePromiseTry(callback, newState, prevState).catch((error) => {
+      console.error('Error in external state callback, Please do it within side effects:', error)
+    })
+  }
 
   const get = () => {
-    const currentState = state;
-    return transform?.get
-      ? transform.get(currentState)
-      : (currentState as unknown as U);
-  };
+    const currentState = state
+    return transform?.get ? transform.get(currentState) : (currentState as unknown as U)
+  }
 
   const set = (newState: U | ((prevState: U) => U)) => {
-    const prevState = state;
+    const prevState = state
     const transformedPrevState = transform?.get
       ? transform.get(prevState)
-      : (prevState as unknown as U);
+      : (prevState as unknown as U)
     state = transform?.set
       ? transform.set(
-          typeof newState === "function"
+          typeof newState === 'function'
             ? (newState as (prev: U) => U)(transformedPrevState)
-            : newState
+            : newState,
         )
-      : ((typeof newState === "function"
+      : ((typeof newState === 'function'
           ? (newState as (prev: U) => U)(transformedPrevState)
-          : newState) as unknown as T);
-
-    listeners.forEach((listener) => listener(state));
-    if (sideEffect) {
-      safePromiseTry(sideEffect, state, prevState).catch((error) => {
-        console.error(
-          "Error in external state side effect, Please do it within side effects:",
-          error
-        );
-      });
+          : newState) as unknown as T)
+
+    storeListeners.forEach((listener) => listener())
+
+    runCallback(onSet, state, prevState)
+    if (!Object.is(state, prevState)) {
+      runCallback(onChange, state, prevState)
     }
-  };
+  }
 
   const use = () => {
-    const [localState, setLocalState] = React.useState<T>(state);
-
-    React.useEffect(() => {
-      listeners.push(setLocalState);
-      return () => {
-        const index = listeners.indexOf(setLocalState);
-        if (index > -1) {
-          listeners.splice(index, 1);
+    const localState = useSyncExternalStore(
+      (onStoreChange) => {
+        storeListeners.push(onStoreChange)
+        return () => {
+          const index = storeListeners.indexOf(onStoreChange)
+          if (index > -1) {
+            storeListeners.splice(index, 1)
+          }
         }
-      };
-    }, []);
-
-    return [
-      transform?.get ? transform.get(localState) : (localState as unknown as U),
-      set,
-    ] as [U, (newState: U | ((prevState: U) => U)) => void];
-  };
+      },
+      () => state,
+      () => state,
+    )
+
+    return [transform?.get ? transform.get(localState) : (localState as unknown as U), set] as [
+      U,
+      (newState: U | ((prevState: U) => U)) => void,
+    ]
+  }
 
   const useGetter = () => {
-    const [value] = use();
-    return value;
-  };
+    const [value] = use()
+    return value
+  }
 
   //@ts-expect-error ignore
-  return { get, set, use, useGetter, __listeners: listeners };
+  return {get, set, use, useGetter, __listeners: storeListeners}
 }
 
 export interface StorageStateOptions<T, U> {
-  sideEffect?: (newState: T) => void;
-  transform?: Transform<T, U>;
-  storageType: "local" | "session";
+  onSet?: ExternalStateCallback<T>
+  onChange?: ExternalStateCallback<T>
+  transform?: Transform<T, U>
+  storageType: 'local' | 'session'
 }
 
 export function createStorageState<T, U = T>(
   key: string,
   initialState: T,
-  options?: StorageStateOptions<T, U>
+  options?: StorageStateOptions<T, U>,
 ) {
-  const { storageType = "local", sideEffect, transform } = options ?? {};
-  let _initState: T = initialState;
-  
+  const {storageType = 'local', onSet, onChange, transform} = options ?? {}
+  let _initState: T = initialState
+
   // 只在客户端环境中读取存储
   if (typeof window !== 'undefined') {
-    const storage = storageType === "local" ? localStorage : sessionStorage;
-    const storedValue = storage.getItem(key);
+    const storage = storageType === 'local' ? localStorage : sessionStorage
+    const storedValue = storage.getItem(key)
     if (storedValue) {
       try {
-        _initState = JSON.parse(storedValue);
+        _initState = JSON.parse(storedValue)
       } catch (error) {
         console.warn(
           `Failed to parse ${storageType}Storage value for key "${key}", using initial state:`,
-          error
-        );
-        _initState = initialState;
+          error,
+        )
+        _initState = initialState
       }
     }
   }
-  
+
   return createExternalState(_initState, {
-    sideEffect: (newState) => {
+    onSet: (newState, prevState) => {
       // 只在客户端环境中写入存储
       if (typeof window !== 'undefined') {
-        const storage = storageType === "local" ? localStorage : sessionStorage;
-        storage.setItem(key, JSON.stringify(newState));
+        const storage = storageType === 'local' ? localStorage : sessionStorage
+        storage.setItem(key, JSON.stringify(newState))
       }
-      sideEffect?.(newState);
+      onSet?.(newState, prevState)
     },
+    onChange,
     transform,
-  });
+  })
 }

package/src/utils/index.ts

@@ -1,7 +1,7 @@
-export * from "./createExternalState";
-export * from "./cx";
-export * from "./reactUtils";
-export * from "./sundry";
-export * from "./promise";
-export * from "./constants";
-export * from "./ruleChecker";
+export * from './createExternalState'
+export * from './cx'
+export * from './reactUtils'
+export * from './sundry'
+export * from './promise'
+export * from './constants'
+export * from './ruleChecker'

package/src/utils/promise.ts

@@ -16,37 +16,37 @@ function promiseTry<T, U extends unknown[]>(
   ...args: U
 ): Promise<Awaited<T>> {
   try {
-    const result = callbackFn(...args); // Call the callback function
+    const result = callbackFn(...args) // Call the callback function
     // Check if the result is a PromiseLike (Promise)
     if (result instanceof Promise) {
-      return result; // If it's a promise, return it directly
+      return result // If it's a promise, return it directly
     }
     // If the result is not a promise, resolve it with Promise.resolve
-    return Promise.resolve(result as Awaited<T>);
+    return Promise.resolve(result as Awaited<T>)
   } catch (error) {
     // If the callback throws an error, reject the promise
-    return Promise.reject(error);
+    return Promise.reject(error)
   }
 }
 
 export const safePromiseTry = (() => {
-  if (typeof Promise.try === "function") {
-    return Promise.try.bind(Promise);
+  if (typeof Promise.try === 'function') {
+    return Promise.try.bind(Promise)
   }
-  return promiseTry;
-})();
+  return promiseTry
+})()
 
 export const safePromiseWithResolvers = (() => {
-  if (typeof Promise.withResolvers === "function") {
-    return Promise.withResolvers.bind(Promise);
+  if (typeof Promise.withResolvers === 'function') {
+    return Promise.withResolvers.bind(Promise)
   }
   return <T>() => {
-    let resolve!: (value: T) => void;
-    let reject!: (reason?: any) => void;
+    let resolve!: (value: T) => void
+    let reject!: (reason?: any) => void
     const promise = new Promise((res, rej) => {
-      resolve = res;
-      reject = rej;
-    });
-    return { promise, resolve, reject };
-  };
-})();
+      resolve = res
+      reject = rej
+    })
+    return {promise, resolve, reject}
+  }
+})()