@wwog/react 1.2.8 → 1.2.9

package/README.md

@@ -367,6 +367,51 @@ You can also use a container wrapper element:
 
 > Internal functions used by some components, which can also be used if needed
 
+#### `createExternalState` (v1.2.9+)
+
+A lightweight external state management utility that allows you to create and manage state outside the React component tree while maintaining perfect integration with components.
+
+```tsx
+import { createExternalState } from "@wwog/react";
+
+// Create a global theme state
+const themeState = createExternalState('light', (newTheme, oldTheme) => {
+  console.log(`Theme changed from ${oldTheme} to ${newTheme}`);
+});
+
+// Get or modify state from anywhere
+console.log(themeState.get()); // 'light'
+themeState.set('dark');
+
+// Use the state in components
+function ThemeConsumer() {
+  const [theme, setTheme] = themeState.use();
+  
+  return (
+    <div className={theme}>
+      Current theme: {theme}
+      <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
+        Toggle theme
+      </button>
+    </div>
+  );
+}
+```
+
+- `createExternalState<T>(initialState, sideEffect?)`: Creates a state accessible outside components
+  - `initialState`: Initial state value
+  - `sideEffect`: Optional side effect function, called on state updates
+  - Returns an object with methods:
+    - `get()`: Get the current state value
+    - `set(newState)`: Update the state value
+    - `use()`: React Hook, returns `[state, setState]` for using this state in components
+
+Use cases:
+- Global state management (themes, user settings, etc.)
+- Cross-component communication
+- Reactive state in services or utility classes
+- Sharing state with non-React code
+
 #### `formatDate`
 
 A relatively standard date formatting function

package/dist/index.d.mts

@@ -449,6 +449,78 @@ interface UseControlledOptions<T> {
 }
 declare function useControlled<T>(options: UseControlledOptions<T>): [T, Dispatch<React.SetStateAction<T>>];
 
+/**
+ * @en Callback function type for state change listeners
+ * @zh 状态变更监听器的回调函数类型
+ * @template T The type of the state / 状态的类型
+ */
+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.
+ * @template T The type of the state / 状态的类型
+ * @param newState The new state value / 新的状态值
+ * @param prevState The previous state value / 之前的状态值
+ */
+type ExternalSideEffect<T> = (newState: T, prevState: T) => void | Promise<void>;
+/**
+ * @en External state management interface
+ * @zh 外部状态管理接口
+ * @template T The type of the state / 状态的类型
+ */
+interface ExternalState<T> {
+    /**
+     * @en Get the current state value
+     * @zh 获取当前状态值
+     * @returns The current state value / 当前状态值
+     */
+    get: () => T;
+    /**
+     * @en Set a new state value
+     * @zh 设置新的状态值
+     * @param newState The new state value / 新的状态值
+     */
+    set: (newState: T) => void;
+    /**
+     * @en React Hook for using external state in components
+     * @zh 在组件中使用外部状态的 React Hook
+     * @returns Array containing current state and update function, similar to useState / 包含当前状态和更新函数的数组，类似于 useState
+     */
+    use: () => [T, (newState: T) => void];
+}
+/**
+ *
+ * @example
+ * ```tsx
+ * // Create an app-level theme state
+ * const themeState = createExternalState('light');
+ *
+ * // Get or modify state outside components
+ * console.log(themeState.get()); // 'light'
+ * themeState.set('dark');
+ *
+ * // Use state in components
+ * function ThemeConsumer() {
+ *   const [theme, setTheme] = themeState.use();
+ *
+ *   return (
+ *     <div className={theme}>
+ *       <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
+ *         Toggle theme / 切换主题
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function createExternalState<T>(initialState: T, sideEffect?: ExternalSideEffect<T>): ExternalState<T>;
+
+/**
+ * @description 性能优化，替代 React.Children.forEach, 回调可以返回 false 来中断循环
+ * @description_en Replace React.Children.forEach, the callback can return false to interrupt the loop
+ */
+declare function childrenLoop(children: React$1.ReactNode | undefined, callback: (child: React$1.ReactNode, index: number) => boolean | void): void;
+
 /**
  * @param schema
  * @example
@@ -488,11 +560,5 @@ declare class Counter {
     next(): number;
 }
 
-/**
- * @description 性能优化，替代 React.Children.forEach, 回调可以返回 false 来中断循环
- * @description_en Replace React.Children.forEach, the callback can return false to interrupt the loop
- */
-declare function childrenLoop(children: React$1.ReactNode | undefined, callback: (child: React$1.ReactNode, index: number) => boolean | void): void;
-
-export { ArrayRender, Counter, DateRender, False, If, Pipe, Scope, SizeBox, Styles, Switch, Toggle, True, When, childrenLoop, cx, formatDate, useControlled };
-export type { ArrayRenderProps, CxInput, DateRenderProps, ElseIfProps, ElseProps, FalseProps, IfProps, PipeProps, ScopeProps, StylesDescriptor, StylesProps, StylesType, SwitchCaseProps, SwitchDefaultProps, SwitchProps, ThenProps, ToggleProps, TrueProps, UseControlledOptions, WhenProps };
+export { ArrayRender, Counter, DateRender, False, If, Pipe, Scope, SizeBox, Styles, Switch, Toggle, True, When, childrenLoop, createExternalState, cx, formatDate, useControlled };
+export type { ArrayRenderProps, CreateStateListener, CxInput, DateRenderProps, ElseIfProps, ElseProps, ExternalSideEffect, ExternalState, FalseProps, IfProps, PipeProps, ScopeProps, StylesDescriptor, StylesProps, StylesType, SwitchCaseProps, SwitchDefaultProps, SwitchProps, ThenProps, ToggleProps, TrueProps, UseControlledOptions, WhenProps };

package/dist/index.js

@@ -1 +1 @@
-import r,{useMemo as h,Children as J,Fragment as S,isValidElement as P,cloneElement as R,useEffect as W,useState as I,useCallback as H}from"react";function T(e,n){if(e===void 0)return;let t=0;if(Array.isArray(e)){for(const l of e)if(n(l,t++)===!1)break}else n(e,t)}const _=(e,n)=>e===n,E=e=>r.createElement(r.Fragment,null,e.children);E.displayName="Switch_Case";const w=e=>r.createElement(r.Fragment,null,e.children);w.displayName="Switch_Default";const y=e=>{const{value:n,compare:t=_,children:l,strict:a=!1}=e,o=new Set;let s=null,c=null,u=!1;return T(l,(d,i)=>{if(!r.isValidElement(d))throw new Error(`Switch Children only accepts valid React elements at index ${i}`);const f=d.type;if(f.displayName===E.displayName){const m=d.props;if(o.has(m.value))throw new Error(`Switch found duplicate Case value at index ${i}: ${JSON.stringify(m.value)}${a?" (detected in strict mode)":""}`);if(o.add(m.value),!s&&t(n,m.value)&&(s=m.children,a===!1))return!1}else if(f.displayName===w.displayName){if(u)throw new Error(`Switch can only have one Default child at index ${i}`);if(u=!0,c=d.props.children,!a&&s)return!1}else throw new Error(`Switch Children only accepts 'Case' or 'Default' elements, found: ${String(f.displayName||f.name||f)} at index ${i}`)}),r.createElement(r.Fragment,null,s??c)};y.displayName="Switch",y.Case=E,y.Default=w,y.createTyped=function(){return{Switch:y,Case:E,Default:w}};const N=e=>r.createElement(r.Fragment,null,e.children),v=({children:e})=>r.createElement(r.Fragment,null,e),F=e=>r.createElement(r.Fragment,null,e.children);N.displayName="If_Then",v.displayName="If_Else",F.displayName="If_ElseIf";const p=({condition:e,children:n})=>{let t=null,l=null;const a=[];if(r.Children.forEach(n,o=>{if(!r.isValidElement(o))throw new Error("If component only accepts valid React elements");const s=o.type;if(s.displayName===N.displayName){if(t)throw new Error("If component can only have one Then child");t=o}else if(s.displayName===F.displayName)a.push(o);else if(s.displayName===v.displayName){if(l)throw new Error("If component can only have one Else child");l=o}else throw new Error(`If component only accepts 'Then', 'ElseIf', or 'Else' elements as children, found: ${String(s.displayName||s.name||s)}`)}),e)return t?r.createElement(r.Fragment,null,t.props.children):null;for(const o of a)if(o.props.condition)return r.createElement(r.Fragment,null,o.props.children);return l?r.createElement(r.Fragment,null,l.props.children):null};p.displayName="If",p.Then=N,p.ElseIf=F,p.Else=v,p.createTyped=function(){return{If:p,Then:N,ElseIf:F,Else:v}};const B=({condition:e,children:n})=>e?r.createElement(r.Fragment,null,n):null,V=({condition:e,children:n})=>e===!1?r.createElement(r.Fragment,null,n):null,Z=({all:e,any:n,none:t,children:l,fallback:a})=>h(()=>(e&&(n||t)&&console.warn('When: Multiple condition types (all, any, none) provided; "all" takes precedence.'),!!(e&&e.length>0&&e.every(Boolean)||n&&n.length>0&&n.some(Boolean)||t&&t.length>0&&t.every(o=>!o))),[e,n,t])?r.createElement(r.Fragment,null,l):r.createElement(r.Fragment,null,a||null),z=({data:e,transform:n,render:t,fallback:l})=>{const a=h(()=>n.reduce((o,s)=>s(o),e),[e,n]);return a==null?r.createElement(r.Fragment,null,l||null):r.createElement(r.Fragment,null,t(a))},L=e=>{const{children:n,h:t,w:l,size:a,height:o,width:s,className:c}=e;return r.createElement("div",{style:{width:a||l||s,height:a||t||o,flexShrink:0},className:c},n)},q=({let:e,props:n,children:t,fallback:l})=>{const a=h(()=>typeof e=="function"?e(n):e,[e,n]);return!t||!Object.keys(a).length?r.createElement(r.Fragment,null,l||null):r.createElement(r.Fragment,null,t(a))};function M(...e){const n=new Set;for(const t of e)if(t){if(typeof t=="string")n.add(t);else if(Array.isArray(t))t.forEach(l=>n.add(l));else if(typeof t=="object")for(const[l,a]of Object.entries(t))a&&n.add(l)}return Array.from(n).join(" ")}const G=e=>typeof e=="object"&&!!e,b=({className:e,children:n,asWrapper:t=!1})=>{if(!n)return null;if(J.count(n)>1)return console.error("<Styles>: children has more than one child. Please check your code."),r.createElement(S,null,n);if(!e)return r.createElement(S,null,n);const l=typeof e=="string"?e:M(...Object.values(e));if(t)return r.createElement(t===!0?"div":t,{className:l},n);if(P(n)){const a=n;let o=a?.props?.className;return a?.type?.displayName===b.displayName&&G(o)&&(o=M(...Object.values(o))),R(n,{className:M(l,o)})}return console.error("<Styles>: children is not a valid React element. Please check your code."),r.createElement(S,null,n)};b.displayName="W/Styles";const K=e=>{const{index:n=0,options:t,next:l,render:a}=e;W(()=>{if(t.length<n+1)throw new Error(`Index ${n} is out of bounds for options array of length ${t.length}. Defaulting to first option.`)},[n,t]);const[o,s]=I(n),c=()=>{s(u=>t.length?l?l(u,t):(u+1)%t.length:u)};return a(t[o],c)};function Q(e){const{items:n,renderItem:t,filter:l}=e;return n?r.createElement(S,null,n.map((a,o)=>l&&!l(a)?null:t(a,o))):(console.error("ArrayRender: items is null"),null)}function U({source:e,format:n,children:t}){const l=h(()=>{if(e instanceof Date)return e;if(typeof e=="string"||typeof e=="number"){const o=new Date(e);return isNaN(o.getTime())?null:o}return null},[e]),a=h(()=>l?n?n(l):l.toLocaleString():null,[l,n]);return!a||!t?null:r.createElement(r.Fragment,null,t(a))}const X="onChange",$="value";function ee(e){const{defaultValue:n,onBeforeChange:t,trigger:l=X,valuePropName:a=$,props:o}=e,s=Object.prototype.hasOwnProperty.call(o,a),[c,u]=I(n),d=s?o[a]:c,i=h(()=>o[l],[o,l]),f=H(m=>{const g=typeof m=="function"?m(d):m;t&&t(g,d)===!1||(s||u(g),i&&i(g))},[s,t,d,i]);return[d,f]}function te(e,n){const t=n||new Date,l=t.getFullYear(),a=t.getMonth()+1,o=t.getDate(),s=t.getHours(),c=t.getMinutes(),u=t.getSeconds(),d=t.getMilliseconds(),i=t.getDay(),f=["Sun","Mon","Tue","Wed","Thu","Fri","Sat"],m=["Sunday","Monday","Tuesday","Wednesday","Thursday","Friday","Saturday"],g=["Jan","Feb","Mar","Apr","May","Jun","Jul","Aug","Sep","Oct","Nov","Dec"],A=["January","February","March","April","May","June","July","August","September","October","November","December"],Y=m[i],D=f[i],C=a-1,x=A[C],k=g[C],O={YY:l.toString().slice(2),YYYY:l.toString(),M:a.toString(),MM:a.toString().padStart(2,"0"),MMM:k,MMMM:x,D:o.toString(),DD:o.toString().padStart(2,"0"),d:i.toString(),dd:D,ddd:D,dddd:Y,H:s.toString(),HH:s.toString().padStart(2,"0"),h:(s%12).toString(),hh:(s%12).toString().padStart(2,"0"),m:c.toString(),mm:c.toString().padStart(2,"0"),s:u.toString(),ss:u.toString().padStart(2,"0"),SSS:d.toString().padStart(3,"0"),Z:"+08:00",ZZ:"+0800",A:s<12?"AM":"PM",a:s<12?"am":"pm"};return e.replace(/YYYY|YY|M{1,4}|D{1,2}|d{1,4}|H{1,2}|h{1,2}|m{1,2}|s{1,2}|SSS|Z{1,2}|A|a/g,j=>O[j])}class ne{count=0;next(){return this.count++}}export{Q as ArrayRender,ne as Counter,U as DateRender,V as False,p as If,z as Pipe,q as Scope,L as SizeBox,b as Styles,y as Switch,K as Toggle,B as True,Z as When,T as childrenLoop,M as cx,te as formatDate,ee as useControlled};
+import r,{useMemo as h,Children as J,Fragment as S,isValidElement as P,cloneElement as R,useEffect as W,useState as I,useCallback as H}from"react";function T(e,n){if(e===void 0)return;let t=0;if(Array.isArray(e)){for(const l of e)if(n(l,t++)===!1)break}else n(e,t)}const _=(e,n)=>e===n,E=e=>r.createElement(r.Fragment,null,e.children);E.displayName="Switch_Case";const w=e=>r.createElement(r.Fragment,null,e.children);w.displayName="Switch_Default";const y=e=>{const{value:n,compare:t=_,children:l,strict:o=!1}=e,a=new Set;let s=null,c=null,i=!1;return T(l,(d,u)=>{if(!r.isValidElement(d))throw new Error(`Switch Children only accepts valid React elements at index ${u}`);const m=d.type;if(m.displayName===E.displayName){const f=d.props;if(a.has(f.value))throw new Error(`Switch found duplicate Case value at index ${u}: ${JSON.stringify(f.value)}${o?" (detected in strict mode)":""}`);if(a.add(f.value),!s&&t(n,f.value)&&(s=f.children,o===!1))return!1}else if(m.displayName===w.displayName){if(i)throw new Error(`Switch can only have one Default child at index ${u}`);if(i=!0,c=d.props.children,!o&&s)return!1}else throw new Error(`Switch Children only accepts 'Case' or 'Default' elements, found: ${String(m.displayName||m.name||m)} at index ${u}`)}),r.createElement(r.Fragment,null,s??c)};y.displayName="Switch",y.Case=E,y.Default=w,y.createTyped=function(){return{Switch:y,Case:E,Default:w}};const N=e=>r.createElement(r.Fragment,null,e.children),v=({children:e})=>r.createElement(r.Fragment,null,e),F=e=>r.createElement(r.Fragment,null,e.children);N.displayName="If_Then",v.displayName="If_Else",F.displayName="If_ElseIf";const p=({condition:e,children:n})=>{let t=null,l=null;const o=[];if(r.Children.forEach(n,a=>{if(!r.isValidElement(a))throw new Error("If component only accepts valid React elements");const s=a.type;if(s.displayName===N.displayName){if(t)throw new Error("If component can only have one Then child");t=a}else if(s.displayName===F.displayName)o.push(a);else if(s.displayName===v.displayName){if(l)throw new Error("If component can only have one Else child");l=a}else throw new Error(`If component only accepts 'Then', 'ElseIf', or 'Else' elements as children, found: ${String(s.displayName||s.name||s)}`)}),e)return t?r.createElement(r.Fragment,null,t.props.children):null;for(const a of o)if(a.props.condition)return r.createElement(r.Fragment,null,a.props.children);return l?r.createElement(r.Fragment,null,l.props.children):null};p.displayName="If",p.Then=N,p.ElseIf=F,p.Else=v,p.createTyped=function(){return{If:p,Then:N,ElseIf:F,Else:v}};const B=({condition:e,children:n})=>e?r.createElement(r.Fragment,null,n):null,V=({condition:e,children:n})=>e===!1?r.createElement(r.Fragment,null,n):null,Z=({all:e,any:n,none:t,children:l,fallback:o})=>h(()=>(e&&(n||t)&&console.warn('When: Multiple condition types (all, any, none) provided; "all" takes precedence.'),!!(e&&e.length>0&&e.every(Boolean)||n&&n.length>0&&n.some(Boolean)||t&&t.length>0&&t.every(a=>!a))),[e,n,t])?r.createElement(r.Fragment,null,l):r.createElement(r.Fragment,null,o||null),z=({data:e,transform:n,render:t,fallback:l})=>{const o=h(()=>n.reduce((a,s)=>s(a),e),[e,n]);return o==null?r.createElement(r.Fragment,null,l||null):r.createElement(r.Fragment,null,t(o))},L=e=>{const{children:n,h:t,w:l,size:o,height:a,width:s,className:c}=e;return r.createElement("div",{style:{width:o||l||s,height:o||t||a,flexShrink:0},className:c},n)},q=({let:e,props:n,children:t,fallback:l})=>{const o=h(()=>typeof e=="function"?e(n):e,[e,n]);return!t||!Object.keys(o).length?r.createElement(r.Fragment,null,l||null):r.createElement(r.Fragment,null,t(o))};function M(...e){const n=new Set;for(const t of e)if(t){if(typeof t=="string")n.add(t);else if(Array.isArray(t))t.forEach(l=>n.add(l));else if(typeof t=="object")for(const[l,o]of Object.entries(t))o&&n.add(l)}return Array.from(n).join(" ")}const G=e=>typeof e=="object"&&!!e,b=({className:e,children:n,asWrapper:t=!1})=>{if(!n)return null;if(J.count(n)>1)return console.error("<Styles>: children has more than one child. Please check your code."),r.createElement(S,null,n);if(!e)return r.createElement(S,null,n);const l=typeof e=="string"?e:M(...Object.values(e));if(t)return r.createElement(t===!0?"div":t,{className:l},n);if(P(n)){const o=n;let a=o?.props?.className;return o?.type?.displayName===b.displayName&&G(a)&&(a=M(...Object.values(a))),R(n,{className:M(l,a)})}return console.error("<Styles>: children is not a valid React element. Please check your code."),r.createElement(S,null,n)};b.displayName="W/Styles";const K=e=>{const{index:n=0,options:t,next:l,render:o}=e;W(()=>{if(t.length<n+1)throw new Error(`Index ${n} is out of bounds for options array of length ${t.length}. Defaulting to first option.`)},[n,t]);const[a,s]=I(n),c=()=>{s(i=>t.length?l?l(i,t):(i+1)%t.length:i)};return o(t[a],c)};function Q(e){const{items:n,renderItem:t,filter:l}=e;return n?r.createElement(S,null,n.map((o,a)=>l&&!l(o)?null:t(o,a))):(console.error("ArrayRender: items is null"),null)}function U({source:e,format:n,children:t}){const l=h(()=>{if(e instanceof Date)return e;if(typeof e=="string"||typeof e=="number"){const a=new Date(e);return isNaN(a.getTime())?null:a}return null},[e]),o=h(()=>l?n?n(l):l.toLocaleString():null,[l,n]);return!o||!t?null:r.createElement(r.Fragment,null,t(o))}const X="onChange",$="value";function ee(e){const{defaultValue:n,onBeforeChange:t,trigger:l=X,valuePropName:o=$,props:a}=e,s=Object.prototype.hasOwnProperty.call(a,o),[c,i]=I(n),d=s?a[o]:c,u=h(()=>a[l],[a,l]),m=H(f=>{const g=typeof f=="function"?f(d):f;t&&t(g,d)===!1||(s||i(g),u&&u(g))},[s,t,d,u]);return[d,m]}function te(e,n){let t=e;const l=[],o=()=>t,a=s=>{const c=t;t=s,n&&n(s,c),l.forEach(i=>i(t))};return{get:o,set:a,use:()=>{const[s,c]=r.useState(t);return r.useEffect(()=>(l.push(c),()=>{const i=l.indexOf(c);i>-1&&l.splice(i,1)}),[]),[s,a]}}}function ne(e,n){const t=n||new Date,l=t.getFullYear(),o=t.getMonth()+1,a=t.getDate(),s=t.getHours(),c=t.getMinutes(),i=t.getSeconds(),d=t.getMilliseconds(),u=t.getDay(),m=["Sun","Mon","Tue","Wed","Thu","Fri","Sat"],f=["Sunday","Monday","Tuesday","Wednesday","Thursday","Friday","Saturday"],g=["Jan","Feb","Mar","Apr","May","Jun","Jul","Aug","Sep","Oct","Nov","Dec"],x=["January","February","March","April","May","June","July","August","September","October","November","December"],A=f[u],D=m[u],C=o-1,Y=x[C],k=g[C],O={YY:l.toString().slice(2),YYYY:l.toString(),M:o.toString(),MM:o.toString().padStart(2,"0"),MMM:k,MMMM:Y,D:a.toString(),DD:a.toString().padStart(2,"0"),d:u.toString(),dd:D,ddd:D,dddd:A,H:s.toString(),HH:s.toString().padStart(2,"0"),h:(s%12).toString(),hh:(s%12).toString().padStart(2,"0"),m:c.toString(),mm:c.toString().padStart(2,"0"),s:i.toString(),ss:i.toString().padStart(2,"0"),SSS:d.toString().padStart(3,"0"),Z:"+08:00",ZZ:"+0800",A:s<12?"AM":"PM",a:s<12?"am":"pm"};return e.replace(/YYYY|YY|M{1,4}|D{1,2}|d{1,4}|H{1,2}|h{1,2}|m{1,2}|s{1,2}|SSS|Z{1,2}|A|a/g,j=>O[j])}class re{count=0;next(){return this.count++}}export{Q as ArrayRender,re as Counter,U as DateRender,V as False,p as If,z as Pipe,q as Scope,L as SizeBox,b as Styles,y as Switch,K as Toggle,B as True,Z as When,T as childrenLoop,te as createExternalState,M as cx,ne as formatDate,ee as useControlled};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wwog/react",
-  "version": "1.2.8",
+  "version": "1.2.9",
   "description": "A practical React component library providing declarative flow control and common UI utility components to make your React code more concise and readable.",
   "keywords": [
     "react",

package/src/index.ts

@@ -1,9 +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/sundry'
-export * from './utils/cx'
-export * from './utils/reactUtils'
+export * from "./utils";

package/src/utils/createExternalState.ts

@@ -0,0 +1,107 @@
+import React from "react";
+
+/**
+ * @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.
+ * @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) => void | Promise<void>;
+
+/**
+ * @en External state management interface
+ * @zh 外部状态管理接口
+ * @template T The type of the state / 状态的类型
+ */
+export interface ExternalState<T> {
+  /**
+   * @en Get the current state value
+   * @zh 获取当前状态值
+   * @returns The current state value / 当前状态值
+   */
+  get: () => T;
+  
+  /**
+   * @en Set a new state value
+   * @zh 设置新的状态值
+   * @param newState The new state value / 新的状态值
+   */
+  set: (newState: T) => void;
+  
+  /**
+   * @en React Hook for using external state in components
+   * @zh 在组件中使用外部状态的 React Hook
+   * @returns Array containing current state and update function, similar to useState / 包含当前状态和更新函数的数组，类似于 useState
+   */
+  use: () => [T, (newState: T) => void];
+}
+
+/**
+ * 
+ * @example
+ * ```tsx
+ * // Create an app-level theme state
+ * const themeState = createExternalState('light');
+ * 
+ * // Get or modify state outside components 
+ * console.log(themeState.get()); // 'light'
+ * themeState.set('dark');
+ * 
+ * // Use state in components
+ * function ThemeConsumer() {
+ *   const [theme, setTheme] = themeState.use();
+ *   
+ *   return (
+ *     <div className={theme}>
+ *       <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
+ *         Toggle theme / 切换主题
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function createExternalState<T>(
+  initialState: T,
+  sideEffect?: ExternalSideEffect<T>
+): ExternalState<T> {
+  let state: T = initialState;
+  const listeners: CreateStateListener<T>[] = [];
+
+  const get = () => state;
+
+  const set = (newState: T) => {
+    const prevState = state;
+    state = newState;
+    if (sideEffect) {
+      sideEffect(newState, prevState);
+    }
+    listeners.forEach((listener) => listener(state));
+  };
+
+  const use = () => {
+    const [localState, setLocalState] = React.useState(state);
+
+    React.useEffect(() => {
+      listeners.push(setLocalState);
+      return () => {
+        const index = listeners.indexOf(setLocalState);
+        if (index > -1) {
+          listeners.splice(index, 1);
+        }
+      };
+    }, []);
+
+    return [localState, set] as [T, (newState: T) => void];
+  };
+
+  return { get, set, use };
+}

package/src/utils/index.ts

@@ -0,0 +1,4 @@
+export * from "./createExternalState";
+export * from "./cx";
+export * from "./reactUtils";
+export * from "./sundry";