@wwog/react 1.3.12 → 1.3.13

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.ts

@@ -1,12 +1,5 @@
-import React 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;
+import {useSyncExternalStore} from 'react'
+import {safePromiseTry} from './promise'
 
 /**
  * @zh 如果需要在变更状态时执行副作用，可以传入函数,对于异步函数，会在更改状态后执行，不会阻塞状态更新, 尽可能在外部使用useEffect处理异步副作用
@@ -15,10 +8,7 @@ export type CreateStateListener<T> = (state: T) => void;
  * @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 ExternalSideEffect<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
 }
 
 /**
@@ -50,12 +40,12 @@ export interface ExternalStateOptions<T, U = T> {
    * @en Side effect function to run after state changes
    * @zh 状态变更后运行的副作用函数
    */
-  sideEffect?: ExternalSideEffect<T>;
+  sideEffect?: ExternalSideEffect<T>
   /**
    * @en Transform functions for getting and setting state
    * @zh 用于获取和设置状态的转换函数
    */
-  transform?: Transform<T, U>;
+  transform?: Transform<T, U>
 }
 
 /**
@@ -70,31 +60,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
    */
-  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)[]
 }
 
 /**
@@ -130,117 +120,114 @@ 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 listeners: CreateStateListener<T>[] = [];
-  const { sideEffect, transform } = options;
+  const storeListeners: (() => void)[] = []
+  const {sideEffect, transform} = options
 
   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);
+          : newState) as unknown as T)
 
-    listeners.forEach((listener) => listener(state));
+    storeListeners.forEach((listener) => listener())
     if (sideEffect) {
       safePromiseTry(sideEffect, state, prevState).catch((error) => {
         console.error(
-          "Error in external state side effect, Please do it within side effects:",
-          error
-        );
-      });
+          'Error in external state side effect, Please do it within side effects:',
+          error,
+        )
+      })
     }
-  };
+  }
 
   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";
+  sideEffect?: (newState: T) => void
+  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', sideEffect, 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) => {
       // 只在客户端环境中写入存储
       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);
+      sideEffect?.(newState)
     },
     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}
+  }
+})()