@wwog/react 1.2.20 → 1.2.21

package/README.md

@@ -393,14 +393,19 @@ You can also use a container wrapper element:
 
 #### `createExternalState` (v1.2.9+, useGetter added in v1.2.13)
 
-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.
+> v1.2.21: Refactor the API to move sideeffects into options and enhance support for the transform interface
+> v1.2.13: add useGetter
+
+> 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}`);
+const themeState = createExternalState("light", {
+  sideEffect: (newTheme, oldTheme) => {
+    console.log(`Theme changed from ${oldTheme} to ${newTheme}`);
+  },
 });
 
 // Get or modify state from anywhere
@@ -429,15 +434,17 @@ function ReadOnlyThemeConsumer() {
 }
 ```
 
-- `createExternalState<T>(initialState, sideEffect?)`: Creates a state accessible outside components
+- `createExternalState<T>(initialState, options?)`: Creates a state accessible outside components
   - `initialState`: Initial state value
-  - `sideEffect`: Optional side effect function, called on state updates
+  - `options.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
     - `useGetter()`: React Hook that only returns the state value, useful when you only need to read the state
-
+  - `options.transform`:
+    - `get`
+    - `set`
 Use cases:
 
 - Global state management (themes, user settings, etc.)

package/dist/index.d.mts

@@ -492,49 +492,92 @@ type CreateStateListener<T> = (state: T) => void;
  * @param prevState The previous state value / 之前的状态值
  */
 type ExternalSideEffect<T> = (newState: T, prevState: T) => any | Promise<any>;
+/**
+ * @en Transform functions for getting and setting state
+ * @zh 用于获取和设置状态的转换函数
+ * @template T The type of the state / 状态的类型
+ * @template U The transformed type for getting / 获取时的转换类型
+ */
+interface Transform<T, U = T> {
+    /**
+     * @en Transform function for getting state
+     * @zh 获取状态时的转换函数
+     */
+    get?: (state: T) => U;
+    /**
+     * @en Transform function for setting state
+     * @zh 设置状态时的转换函数
+     */
+    set?: (value: U) => T;
+}
+/**
+ * @en Options for creating external state
+ * @zh 创建外部状态的选项
+ * @template T The type of the state / 状态的类型
+ * @template U The transformed type for getting / 获取时的转换类型
+ */
+interface ExternalStateOptions<T, U = T> {
+    /**
+     * @en Side effect function to run after state changes
+     * @zh 状态变更后运行的副作用函数
+     */
+    sideEffect?: ExternalSideEffect<T>;
+    /**
+     * @en Transform functions for getting and setting state
+     * @zh 用于获取和设置状态的转换函数
+     */
+    transform?: Transform<T, U>;
+}
 /**
  * @en External state management interface
  * @zh 外部状态管理接口
  * @template T The type of the state / 状态的类型
+ * @template U The transformed type for getting / 获取时的转换类型
  */
-interface ExternalState<T> {
+interface ExternalState<T, U = T> {
     /**
      * @en Get the current state value
      * @zh 获取当前状态值
-     * @returns The current state value / 当前状态值
+     * @returns The current state value (transformed if transform.get is provided) / 当前状态值（如果提供了 transform.get 则进行转换）
      */
-    get: () => T;
+    get: () => U;
     /**
      * @en Set a new state value
      * @zh 设置新的状态值
-     * @param newState The new state value / 新的状态值
+     * @param newState The new state value or a function that returns it / 新的状态值或返回新状态的函数
      */
-    set: (newState: T) => void;
+    set: (newState: U | ((prevState: U) => U)) => 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
+     * @returns Array containing current钣金龙8国际唯一官网 current state and update function, similar to useState / 包含当前状态和更新函数的数组，类似于 useState
      */
-    use: () => [T, (newState: T) => void];
+    use: () => [U, (newState: U | ((prevState: U) => U)) => void];
     /**
      * @zh use的变体，只获取value.
      * @en A variant of use that only gets the value.
      */
-    useGetter: () => T;
+    useGetter: () => U;
 }
-interface ExternalWithKernel<T> extends ExternalState<T> {
+interface ExternalWithKernel<T, U = T> extends ExternalState<T, U> {
     __listeners: CreateStateListener<T>[];
 }
 /**
  *
  * @example
  * ```tsx
- * // Create an app-level theme state
- * const themeState = createExternalState('light');
+ * // Create an app-level theme state with options
+ * const themeState = createExternalState('light', {
+ *   sideEffect: (newState, prevState) => console.log(`Theme changed from ${prevState} to ${newState}`),
+ *   transform: {
+ *     get: (state) => state.toUpperCase(),
+ *     set: (value) => value.toLowerCase()
+ *   }
+ * });
  *
  * // Get or modify state outside components
- * console.log(themeState.get()); // 'light'
- * themeState.set('dark');
+ * console.log(themeState.get()); // 'LIGHT'
+ * themeState.set((prev) => prev === 'light' ? 'dark' : 'light'); // Toggle theme
  *
  * // Use state in components
  * function ThemeConsumer() {
@@ -542,7 +585,7 @@ interface ExternalWithKernel<T> extends ExternalState<T> {
  *
  *   return (
  *     <div className={theme}>
- *       <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
+ *       <button onClick={() => setTheme((prev) => prev === 'LIGHT' ? 'DARK' : 'LIGHT')}>
  *         Toggle theme / 切换主题
  *       </button>
  *     </div>
@@ -550,7 +593,7 @@ interface ExternalWithKernel<T> extends ExternalState<T> {
  * }
  * ```
  */
-declare function createExternalState<T>(initialState: T | (() => T), sideEffect?: ExternalSideEffect<T>): ExternalState<T>;
+declare function createExternalState<T, U = T>(initialState: T | (() => T), options?: ExternalStateOptions<T, U>): ExternalState<T, U>;
 
 /**
  * @description 性能优化，替代 React.Children.forEach, 回调可以返回 false 来中断循环
@@ -600,4 +643,4 @@ declare class Counter {
 declare const safePromiseTry: <T, U extends unknown[]>(callbackFn: (...args: U) => T | PromiseLike<T>, ...args: U) => Promise<Awaited<T>>;
 
 export { ArrayRender, Clamp, Counter, DateRender, False, If, Pipe, Scope, SizeBox, Styles, Switch, Toggle, True, When, childrenLoop, createExternalState, cx, formatDate, safePromiseTry, useControlled };
-export type { ArrayRenderProps, ClampProps, CreateStateListener, CxInput, DateRenderProps, ElseIfProps, ElseProps, ExternalSideEffect, ExternalState, ExternalWithKernel, FalseProps, IfProps, PipeProps, ScopeProps, StylesDescriptor, StylesProps, StylesType, SwitchCaseProps, SwitchDefaultProps, SwitchProps, ThenProps, ToggleProps, TrueProps, UseControlledOptions, WhenProps };
+export type { ArrayRenderProps, ClampProps, CreateStateListener, CxInput, DateRenderProps, ElseIfProps, ElseProps, ExternalSideEffect, ExternalState, ExternalStateOptions, ExternalWithKernel, FalseProps, IfProps, PipeProps, ScopeProps, StylesDescriptor, StylesProps, StylesType, SwitchCaseProps, SwitchDefaultProps, SwitchProps, ThenProps, ToggleProps, Transform, TrueProps, UseControlledOptions, WhenProps };

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wwog/react",
-  "version": "1.2.20",
+  "version": "1.2.21",
   "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/utils/createExternalState.test.tsx

@@ -123,7 +123,9 @@ describe("createExternalState", () => {
   it("测试副作用函数", () => {
     const mockSideEffect = vi.fn((...args) => void 0);
     const initialState: string = "initial";
-    const state = createExternalState(initialState, mockSideEffect);
+    const state = createExternalState(initialState, {
+      sideEffect: mockSideEffect,
+    });
     state.set("updated");
     expect(mockSideEffect).toHaveBeenCalledTimes(1);
     expect(mockSideEffect).toHaveBeenCalledWith("updated", initialState);
@@ -135,7 +137,9 @@ describe("createExternalState", () => {
   it("测试异步副作用函数", async () => {
     const mockAsyncSideEffect = vi.fn().mockResolvedValue(undefined);
     const initialState: string = "initial";
-    const state = createExternalState(initialState, mockAsyncSideEffect);
+    const state = createExternalState(initialState, {
+      sideEffect: mockAsyncSideEffect,
+    });
 
     state.set("updated");
     expect(mockAsyncSideEffect).toHaveBeenCalledTimes(1);
@@ -181,4 +185,37 @@ describe("createExternalState", () => {
     expect(ageLocator.element().textContent).toBe("35");
     expect(state.get()).toEqual({ name: "王五", age: 35 });
   });
+
+  it("测试transform转换功能", async () => {
+    const state = createExternalState("hello", {
+      transform: {
+        get: (str) => str.toUpperCase(),
+        set: (str) => str.toLowerCase(),
+      },
+    });
+
+    expect(state.get()).toBe("HELLO");
+
+    state.set("WORLD");
+    expect(state.get()).toBe("WORLD");
+
+    function TestComponent() {
+      const [value, setValue] = state.use();
+      return (
+        <div>
+          <span data-testid="value">{value}</span>
+          <button data-testid="update" onClick={() => setValue("TEST")}>
+            Update
+          </button>
+        </div>
+      );
+    }
+
+    const { getByTestId } = render(<TestComponent />);
+    expect(getByTestId("value").element().textContent).toBe("WORLD");
+
+    await getByTestId("update").click();
+    expect(getByTestId("value").element().textContent).toBe("TEST");
+    expect(state.get()).toBe("TEST");
+  });
 });

package/src/utils/createExternalState.ts

@@ -20,41 +20,80 @@ export type ExternalSideEffect<T> = (
   prevState: T
 ) => any | Promise<any>;
 
+/**
+ * @en Transform functions for getting and setting state
+ * @zh 用于获取和设置状态的转换函数
+ * @template T The type of the state / 状态的类型
+ * @template U The transformed type for getting / 获取时的转换类型
+ */
+export interface Transform<T, U = T> {
+  /**
+   * @en Transform function for getting state
+   * @zh 获取状态时的转换函数
+   */
+  get?: (state: T) => U;
+  /**
+   * @en Transform function for setting state
+   * @zh 设置状态时的转换函数
+   */
+  set?: (value: U) => T;
+}
+
+/**
+ * @en Options for creating external state
+ * @zh 创建外部状态的选项
+ * @template T The type of the state / 状态的类型
+ * @template U The transformed type for getting / 获取时的转换类型
+ */
+export interface ExternalStateOptions<T, U = T> {
+  /**
+   * @en Side effect function to run after state changes
+   * @zh 状态变更后运行的副作用函数
+   */
+  sideEffect?: ExternalSideEffect<T>;
+  /**
+   * @en Transform functions for getting and setting state
+   * @zh 用于获取和设置状态的转换函数
+   */
+  transform?: Transform<T, U>;
+}
+
 /**
  * @en External state management interface
  * @zh 外部状态管理接口
  * @template T The type of the state / 状态的类型
+ * @template U The transformed type for getting / 获取时的转换类型
  */
-export interface ExternalState<T> {
+export interface ExternalState<T, U = T> {
   /**
    * @en Get the current state value
    * @zh 获取当前状态值
-   * @returns The current state value / 当前状态值
+   * @returns The current state value (transformed if transform.get is provided) / 当前状态值（如果提供了 transform.get 则进行转换）
    */
-  get: () => T;
+  get: () => U;
 
   /**
    * @en Set a new state value
    * @zh 设置新的状态值
-   * @param newState The new state value / 新的状态值
+   * @param newState The new state value or a function that returns it / 新的状态值或返回新状态的函数
    */
-  set: (newState: T) => void;
+  set: (newState: U | ((prevState: U) => U)) => 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
+   * @returns Array containing current钣金龙8国际唯一官网 current state and update function, similar to useState / 包含当前状态和更新函数的数组，类似于 useState
    */
-  use: () => [T, (newState: T) => void];
+  use: () => [U, (newState: U | ((prevState: U) => U)) => void];
 
   /**
    * @zh use的变体，只获取value.
    * @en A variant of use that only gets the value.
    */
-  useGetter: () => T;
+  useGetter: () => U;
 }
 
-export interface ExternalWithKernel<T> extends ExternalState<T> {
+export interface ExternalWithKernel<T, U = T> extends ExternalState<T, U> {
   __listeners: CreateStateListener<T>[];
 }
 
@@ -62,12 +101,18 @@ export interface ExternalWithKernel<T> extends ExternalState<T> {
  *
  * @example
  * ```tsx
- * // Create an app-level theme state
- * const themeState = createExternalState('light');
+ * // Create an app-level theme state with options
+ * const themeState = createExternalState('light', {
+ *   sideEffect: (newState, prevState) => console.log(`Theme changed from ${prevState} to ${newState}`),
+ *   transform: {
+ *     get: (state) => state.toUpperCase(),
+ *     set: (value) => value.toLowerCase()
+ *   }
+ * });
  *
  * // Get or modify state outside components
- * console.log(themeState.get()); // 'light'
- * themeState.set('dark');
+ * console.log(themeState.get()); // 'LIGHT'
+ * themeState.set((prev) => prev === 'light' ? 'dark' : 'light'); // Toggle theme
  *
  * // Use state in components
  * function ThemeConsumer() {
@@ -75,7 +120,7 @@ export interface ExternalWithKernel<T> extends ExternalState<T> {
  *
  *   return (
  *     <div className={theme}>
- *       <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
+ *       <button onClick={() => setTheme((prev) => prev === 'LIGHT' ? 'DARK' : 'LIGHT')}>
  *         Toggle theme / 切换主题
  *       </button>
  *     </div>
@@ -83,22 +128,39 @@ export interface ExternalWithKernel<T> extends ExternalState<T> {
  * }
  * ```
  */
-export function createExternalState<T>(
+export function createExternalState<T, U = T>(
   initialState: T | (() => T),
-  sideEffect?: ExternalSideEffect<T>
-): ExternalState<T> {
+  options: ExternalStateOptions<T, U> = {}
+): ExternalState<T, U> {
   let state: T =
     typeof initialState === "function"
       ? (initialState as () => T)()
       : initialState;
 
   const listeners: CreateStateListener<T>[] = [];
+  const { sideEffect, transform } = options;
 
-  const get = () => state;
+  const get = () => {
+    const currentState = state;
+    return transform?.get
+      ? transform.get(currentState)
+      : (currentState as unknown as U);
+  };
 
-  const set = (newState: T | (() => T)) => {
+  const set = (newState: U | ((prevState: U) => U)) => {
     const prevState = state;
-    state = typeof newState === "function" ? (newState as () => T)() : newState;
+    const transformedPrevState = transform?.get
+      ? transform.get(prevState)
+      : (prevState as unknown as U);
+    state = transform?.set
+      ? transform.set(
+          typeof newState === "function"
+            ? (newState as (prev: U) => U)(transformedPrevState)
+            : newState
+        )
+      : ((typeof newState === "function"
+          ? (newState as (prev: U) => U)(transformedPrevState)
+          : newState) as unknown as T);
 
     listeners.forEach((listener) => listener(state));
     if (sideEffect) {
@@ -112,7 +174,7 @@ export function createExternalState<T>(
   };
 
   const use = () => {
-    const [localState, setLocalState] = React.useState(state);
+    const [localState, setLocalState] = React.useState<T>(state);
 
     React.useEffect(() => {
       listeners.push(setLocalState);
@@ -124,7 +186,10 @@ export function createExternalState<T>(
       };
     }, []);
 
-    return [localState, set] as [T, (newState: T) => void];
+    return [
+      transform?.get ? transform.get(localState) : (localState as unknown as U),
+      set,
+    ] as [U, (newState: U | ((prevState: U) => U)) => void];
   };
 
   const useGetter = () => {