@wwog/react 1.1.7 → 1.2.0

package/README.md

@@ -141,11 +141,38 @@ function Example({ isActive }) {
 - `<True condition={...}>`：当 condition 为 true 时渲染子内容。
 - `<False condition={...}>`：当 condition 为 false 时渲染子内容。
 
+#### `<Toggle>`
+
+声明式切换组件，在预定义选项中切换值，并通过指定属性传递给子组件，支持自定义切换逻辑。
+
+```tsx
+import { Toggle } from "@wwog/react";
+
+interface ThemeChildProps {
+  theme: string;
+  toggleTheme: () => void;
+}
+const ThemeChild: React.FC<ThemeChildProps> = ({ theme, toggleTheme }) => (
+  <div onClick={toggleTheme}>当前主题: {theme}</div>
+);
+
+<Toggle source="light" options={["light", "dark"]} target="theme" toggleTarget="toggleTheme">
+  <ThemeChild />
+</Toggle>
+```
+
+- `source`：初始切换值。
+- `options`：可切换的值数组。
+- `target`：传递切换值给子节点的属性名，默认 value。
+- `toggleTarget`：传递切换函数给子节点的属性名，默认 toggle。
+- `next`：自定义切换逻辑函数。
+- `children`：渲染内容。
+
 ### 通用组件
 
 #### `<ArrayRender>`
 
-高效渲染数组数据的工具组件，支持过滤和自定义渲染。
+内部仅单次循环。高效渲染数组数据的工具组件，支持过滤和自定义渲染。
 
 ```tsx
 import { ArrayRender } from "@wwog/react";
@@ -181,8 +208,8 @@ function Example({ users }) {
     <Pipe
       data={users}
       transform={[
-        (data) => data.filter(user => user.active),
-        (data) => data.map(user => user.name)
+        (data) => data.filter((user) => user.active),
+        (data) => data.map((user) => user.name),
       ]}
       render={(names) => <div>{names.join(", ")}</div>}
       fallback={<div>No Data</div>}
@@ -210,15 +237,23 @@ import { Scope } from "@wwog/react";
 function Example() {
   return (
     <Scope let={{ count: 1, text: "Hello" }}>
-      {({ count, text }) => <div>{text} {count}</div>}
+      {({ count, text }) => (
+        <div>
+          {text} {count}
+        </div>
+      )}
     </Scope>
   );
 }
 
 // 支持函数式 let
-<Scope let={(props) => ({ total: props.items.length })} props={{ items: [1, 2] }} fallback={<div>Empty</div>}>
+<Scope
+  let={(props) => ({ total: props.items.length })}
+  props={{ items: [1, 2] }}
+  fallback={<div>Empty</div>}
+>
   {({ total }) => <div>Total: {total}</div>}
-</Scope>
+</Scope>;
 ```
 
 - `let`：对象或函数，定义作用域变量。
@@ -230,6 +265,8 @@ function Example() {
 
 创建固定尺寸的容器，用于布局调整和间距控制。
 
+> v1.1.8: Fixed SizeBox not working in 'flex' layouts, add classname props
+
 ```tsx
 import { SizeBox } from "@wwog/react";
 
@@ -261,9 +298,6 @@ function Layout() {
 - Once：确保内容仅渲染一次，适合初始化。
 - Each：增强列表渲染，支持过滤和排序。
 
-
 ## License
 
 MIT
-
-

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import React, { ReactNode, FC } from 'react';
+import React$1, { ReactNode, FC, Dispatch } from 'react';
 
 interface SwitchProps<T> {
     value: T;
@@ -7,7 +7,7 @@ interface SwitchProps<T> {
      * @description_en optional compare function, default to () => a === b
      **/
     compare?: (a: T, b: T) => boolean;
-    children?: React.ReactNode;
+    children?: React$1.ReactNode;
     /**
      * @description 是否严格模式，默认 false.建议跟随开发环境变化,严格模式下,会循环所有节点来提供更多的错误提示
      * @description_en strict mode, default to false. It is recommended to follow the development environment changes. In strict mode, all nodes will be looped to provide more error prompts
@@ -22,58 +22,58 @@ interface SwitchProps<T> {
 }
 interface SwitchCaseProps<T> {
     value: T;
-    children?: React.ReactNode;
+    children?: React$1.ReactNode;
 }
 interface SwitchDefaultProps {
-    children?: React.ReactNode;
+    children?: React$1.ReactNode;
 }
 /**
  * @description Switch 组件用于根据传入的 value 渲染不同的子组件
  * @description_en The Switch component is used to render different child components based on the passed value
  */
 declare const Switch: {
-    <T>(props: SwitchProps<T>): React.ReactElement | null;
+    <T>(props: SwitchProps<T>): React$1.ReactElement | null;
     displayName: string;
     Case: {
-        <T>(props: SwitchCaseProps<T>): React.ReactElement;
+        <T>(props: SwitchCaseProps<T>): React$1.ReactElement;
         displayName: string;
     };
     Default: {
-        (props: SwitchDefaultProps): React.ReactElement;
+        (props: SwitchDefaultProps): React$1.ReactElement;
         displayName: string;
     };
     createTyped<T>(): {
-        Switch: (props: SwitchProps<T>) => React.ReactElement | null;
-        Case: (props: SwitchCaseProps<T>) => React.ReactElement;
-        Default: (props: SwitchDefaultProps) => React.ReactElement;
+        Switch: (props: SwitchProps<T>) => React$1.ReactElement | null;
+        Case: (props: SwitchCaseProps<T>) => React$1.ReactElement;
+        Default: (props: SwitchDefaultProps) => React$1.ReactElement;
     };
 };
 
 interface IfProps {
     condition: boolean;
-    children?: React.ReactNode;
+    children?: React$1.ReactNode;
 }
 interface ThenProps {
-    children?: React.ReactNode;
+    children?: React$1.ReactNode;
 }
 interface ElseProps {
-    children?: React.ReactNode;
+    children?: React$1.ReactNode;
 }
 interface ElseIfProps {
     condition: boolean;
-    children?: React.ReactNode;
+    children?: React$1.ReactNode;
 }
 declare const If: {
-    ({ condition, children, }: IfProps): React.ReactElement | null;
+    ({ condition, children, }: IfProps): React$1.ReactElement | null;
     displayName: string;
-    Then: React.FC<ThenProps>;
-    ElseIf: React.FC<ElseIfProps>;
-    Else: React.FC<ElseProps>;
+    Then: React$1.FC<ThenProps>;
+    ElseIf: React$1.FC<ElseIfProps>;
+    Else: React$1.FC<ElseProps>;
     createTyped(): {
-        If: (props: IfProps) => React.ReactElement | null;
-        Then: (props: ThenProps) => React.ReactElement;
-        ElseIf: (props: ElseIfProps) => React.ReactElement;
-        Else: (props: ElseProps) => React.ReactElement;
+        If: (props: IfProps) => React$1.ReactElement | null;
+        Then: (props: ThenProps) => React$1.ReactElement;
+        ElseIf: (props: ElseIfProps) => React$1.ReactElement;
+        Else: (props: ElseProps) => React$1.ReactElement;
     };
 };
 interface TrueProps {
@@ -190,6 +190,75 @@ interface PipeProps {
  */
 declare const Pipe: FC<PipeProps>;
 
+interface ToggleProps<T = boolean> {
+    /**
+     * @description_en The initial value to toggle.
+     * @description_zh 初始切换值。
+     */
+    source: T;
+    /**
+     * @description_en Array of values to toggle between.
+     * @description_zh 可切换的值数组。
+     */
+    options: T[];
+    /**
+     * @description_en The prop name to pass the toggled value to children.
+     * @description_zh 将切换后的值传递给子节点的属性名。
+     * @default 'value'
+     */
+    target?: string;
+    /**
+     * @description_en The prop name to pass the toggle function to children.
+     * @description_zh 将切换函数传递给子节点的属性名。
+     * @default 'toggle'
+     */
+    toggleTarget?: string;
+    /**
+     * @description_en Function to determine the next value in the toggle sequence.
+     * @description_zh 确定切换序列中下一个值的函数。
+     * @optional
+     */
+    next?: (current: T, options: T[]) => T;
+    /**
+     * @description_en Content to render, receiving the toggled value and toggle function via the target and toggleTarget props.
+     * @description_zh 渲染的内容，通过 target 和 toggleTarget 属性接收切换后的值和切换函数。
+     */
+    children: ReactNode;
+}
+/**
+ * @description_zh 一个声明式组件，用于在预定义选项中切换值并通过指定属性传递给子组件，支持自定义切换逻辑。
+ * @description_en A declarative component for toggling between predefined values and passing them to children via specified props, supporting custom toggle logic.
+ * @component
+ * @example
+ * ```tsx
+ * interface ThemeChildProps {
+ *   theme: string;
+ *   toggleTheme: () => void;
+ * }
+ * const ThemeChild: FC<ThemeChildProps> = ({ theme, toggleTheme }) => (
+ *   <div onClick={toggleTheme}>当前主题: {theme}</div>
+ * );
+ *
+ * <Toggle source="light" options={["light", "dark"]} target="theme" toggleTarget="toggleTheme">
+ *   <ThemeChild />
+ * </Toggle>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <Toggle
+ *   source={1}
+ *   options={[1, 2, 3]}
+ *   target="value"
+ *   toggleTarget="toggleValue"
+ *   next={(current, options) => options[(options.indexOf(current) + 1) % options.length]}
+ * >
+ *   <ValueChild />
+ * </Toggle>
+ * ```
+ */
+declare const Toggle: <T>(props: ToggleProps<T>) => (string | number | bigint | React$1.ReactElement<unknown, string | React$1.JSXElementConstructor<any>> | Iterable<React$1.ReactNode> | Promise<string | number | bigint | boolean | React$1.ReactPortal | React$1.ReactElement<unknown, string | React$1.JSXElementConstructor<any>> | Iterable<React$1.ReactNode> | null | undefined>)[] | null | undefined;
+
 interface SizeBoxProps {
     size?: number | string;
     height?: number | string;
@@ -197,6 +266,7 @@ interface SizeBoxProps {
     h?: number | string;
     w?: number | string;
     children?: ReactNode;
+    className?: string;
 }
 /**
  * @description SizeBox 组件用于设置一个固定大小的盒子
@@ -205,7 +275,7 @@ declare const SizeBox: FC<SizeBoxProps>;
 
 interface ArrayRenderProps<T> {
     items: T[];
-    renderItem: (item: T, index: number) => React.ReactNode;
+    renderItem: (item: T, index: number) => React$1.ReactNode;
     filter?: (item: T) => boolean;
 }
 declare function ArrayRender<T>(props: ArrayRenderProps<T>): ReactNode;
@@ -269,7 +339,34 @@ declare const Scope: FC<ScopeProps>;
  * @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.ReactNode | undefined, callback: (child: React.ReactNode, index: number) => boolean | void): void;
+declare function childrenLoop(children: React$1.ReactNode | undefined, callback: (child: React$1.ReactNode, index: number) => boolean | void): void;
+
+interface UseControlledOptions<T> {
+    /**
+     * @description - 非受控模式下的默认值,会被受控模式下的值覆盖
+     * @description_en - Default value in uncontrolled mode, will be overridden by the value in controlled mode
+     */
+    defaultValue: T;
+    /**
+     * @description - 值变更前的回调函数，可用于拦截或修改新值
+     * @description_en - Callback function before the value changes, can be used to intercept or modify the new value
+     */
+    onBeforeChange?: (newValue: T, currentValue: T) => boolean | void;
+    /**
+     * @description - 当值发生变化时触发的回调函数名
+     * @description_en - Callback function name triggered when the value changes
+     * @default - onChange
+     */
+    trigger?: string;
+    /**
+     * @description - 值的属性名
+     * @description_en - Property name of the value
+     * @default - value
+     */
+    valuePropName?: string;
+    props: Record<string, any>;
+}
+declare function useControlled<T>(options: UseControlledOptions<T>): [T, Dispatch<React.SetStateAction<T>>];
 
-export { ArrayRender, False, If, Pipe, Scope, SizeBox, Switch, True, When, childrenLoop };
-export type { ArrayRenderProps, ElseIfProps, ElseProps, FalseProps, IfProps, PipeProps, ScopeProps, SwitchCaseProps, SwitchDefaultProps, SwitchProps, ThenProps, TrueProps, WhenProps };
+export { ArrayRender, False, If, Pipe, Scope, SizeBox, Switch, Toggle, True, When, childrenLoop, useControlled };
+export type { ArrayRenderProps, ElseIfProps, ElseProps, FalseProps, IfProps, PipeProps, ScopeProps, SwitchCaseProps, SwitchDefaultProps, SwitchProps, ThenProps, ToggleProps, TrueProps, UseControlledOptions, WhenProps };

package/dist/index.js

@@ -1 +1 @@
-import n,{useMemo as g,Fragment as S}from"react";function v(e,l){if(e===void 0)return;let t=0;if(Array.isArray(e)){for(const a of e)if(l(a,t++)===!1)break}else l(e,t)}const I=(e,l)=>e===l,f=e=>n.createElement(n.Fragment,null,e.children);f.displayName="Switch_Case";const p=e=>n.createElement(n.Fragment,null,e.children);p.displayName="Switch_Default";const s=e=>{const{value:l,compare:t=I,children:a,strict:r=!1}=e,i=new Set;let c=null,N=null,F=!1;return v(a,(u,h)=>{if(!n.isValidElement(u))throw new Error(`Switch Children only accepts valid React elements at index ${h}`);const d=u.type;if(d.displayName===f.displayName){const m=u.props;if(i.has(m.value))throw new Error(`Switch found duplicate Case value at index ${h}: ${JSON.stringify(m.value)}${r?" (detected in strict mode)":""}`);if(i.add(m.value),!c&&t(l,m.value)&&(c=m.children,r===!1))return!1}else if(d.displayName===p.displayName){if(F)throw new Error(`Switch can only have one Default child at index ${h}`);if(F=!0,N=u.props.children,!r&&c)return!1}else throw new Error(`Switch Children only accepts 'Case' or 'Default' elements, found: ${String(d.displayName||d.name||d)} at index ${h}`)}),n.createElement(n.Fragment,null,c??N)};s.displayName="Switch",s.Case=f,s.Default=p,s.createTyped=function(){return{Switch:s,Case:f,Default:p}};const y=e=>n.createElement(n.Fragment,null,e.children),E=({children:e})=>n.createElement(n.Fragment,null,e),w=e=>n.createElement(n.Fragment,null,e.children);y.displayName="If_Then",E.displayName="If_Else",w.displayName="If_ElseIf";const o=({condition:e,children:l})=>{let t=null,a=null;const r=[];if(n.Children.forEach(l,i=>{if(!n.isValidElement(i))throw new Error("If component only accepts valid React elements");const c=i.type;if(c.displayName===y.displayName){if(t)throw new Error("If component can only have one Then child");t=i}else if(c.displayName===w.displayName)r.push(i);else if(c.displayName===E.displayName){if(a)throw new Error("If component can only have one Else child");a=i}else throw new Error(`If component only accepts 'Then', 'ElseIf', or 'Else' elements as children, found: ${String(c.displayName||c.name||c)}`)}),e)return t?n.createElement(n.Fragment,null,t.props.children):null;for(const i of r)if(i.props.condition)return n.createElement(n.Fragment,null,i.props.children);return a?n.createElement(n.Fragment,null,a.props.children):null};o.displayName="If",o.Then=y,o.ElseIf=w,o.Else=E,o.createTyped=function(){return{If:o,Then:y,ElseIf:w,Else:E}};const C=({condition:e,children:l})=>e?n.createElement(n.Fragment,null,l):null,T=({condition:e,children:l})=>e===!1?n.createElement(n.Fragment,null,l):null,k=({all:e,any:l,none:t,children:a,fallback:r})=>g(()=>(e&&(l||t)&&console.warn('When: Multiple condition types (all, any, none) provided; "all" takes precedence.'),!!(e&&e.length>0&&e.every(Boolean)||l&&l.length>0&&l.some(Boolean)||t&&t.length>0&&t.every(i=>!i))),[e,l,t])?n.createElement(n.Fragment,null,a):n.createElement(n.Fragment,null,r||null),x=({data:e,transform:l,render:t,fallback:a})=>{const r=g(()=>l.reduce((i,c)=>c(i),e),[e,l]);return r==null?n.createElement(n.Fragment,null,a||null):n.createElement(n.Fragment,null,t(r))},$=e=>{const{children:l,h:t,w:a,size:r,height:i,width:c}=e;return n.createElement("div",{style:{width:r||a||c,height:r||t||i}},l)};function b(e){const{items:l,renderItem:t,filter:a}=e;return l?n.createElement(S,null,l.map((r,i)=>a&&!a(r)?null:t(r,i))):(console.error("ArrayRender: items is null"),null)}const D=({let:e,props:l,children:t,fallback:a})=>{const r=g(()=>typeof e=="function"?e(l):e,[e,l]);return!t||!Object.keys(r).length?n.createElement(n.Fragment,null,a||null):n.createElement(n.Fragment,null,t(r))};export{b as ArrayRender,T as False,o as If,x as Pipe,D as Scope,$ as SizeBox,s as Switch,C as True,k as When,v as childrenLoop};
+import n,{useMemo as y,useState as S,Fragment as I,useCallback as T}from"react";function C(e,t){if(e===void 0)return;let l=0;if(Array.isArray(e)){for(const a of e)if(t(a,l++)===!1)break}else t(e,l)}const x=(e,t)=>e===t,g=e=>n.createElement(n.Fragment,null,e.children);g.displayName="Switch_Case";const E=e=>n.createElement(n.Fragment,null,e.children);E.displayName="Switch_Default";const p=e=>{const{value:t,compare:l=x,children:a,strict:o=!1}=e,r=new Set;let c=null,m=null,f=!1;return C(a,(s,d)=>{if(!n.isValidElement(s))throw new Error(`Switch Children only accepts valid React elements at index ${d}`);const i=s.type;if(i.displayName===g.displayName){const u=s.props;if(r.has(u.value))throw new Error(`Switch found duplicate Case value at index ${d}: ${JSON.stringify(u.value)}${o?" (detected in strict mode)":""}`);if(r.add(u.value),!c&&l(t,u.value)&&(c=u.children,o===!1))return!1}else if(i.displayName===E.displayName){if(f)throw new Error(`Switch can only have one Default child at index ${d}`);if(f=!0,m=s.props.children,!o&&c)return!1}else throw new Error(`Switch Children only accepts 'Case' or 'Default' elements, found: ${String(i.displayName||i.name||i)} at index ${d}`)}),n.createElement(n.Fragment,null,c??m)};p.displayName="Switch",p.Case=g,p.Default=E,p.createTyped=function(){return{Switch:p,Case:g,Default:E}};const w=e=>n.createElement(n.Fragment,null,e.children),N=({children:e})=>n.createElement(n.Fragment,null,e),v=e=>n.createElement(n.Fragment,null,e.children);w.displayName="If_Then",N.displayName="If_Else",v.displayName="If_ElseIf";const h=({condition:e,children:t})=>{let l=null,a=null;const o=[];if(n.Children.forEach(t,r=>{if(!n.isValidElement(r))throw new Error("If component only accepts valid React elements");const c=r.type;if(c.displayName===w.displayName){if(l)throw new Error("If component can only have one Then child");l=r}else if(c.displayName===v.displayName)o.push(r);else if(c.displayName===N.displayName){if(a)throw new Error("If component can only have one Else child");a=r}else throw new Error(`If component only accepts 'Then', 'ElseIf', or 'Else' elements as children, found: ${String(c.displayName||c.name||c)}`)}),e)return l?n.createElement(n.Fragment,null,l.props.children):null;for(const r of o)if(r.props.condition)return n.createElement(n.Fragment,null,r.props.children);return a?n.createElement(n.Fragment,null,a.props.children):null};h.displayName="If",h.Then=w,h.ElseIf=v,h.Else=N,h.createTyped=function(){return{If:h,Then:w,ElseIf:v,Else:N}};const k=({condition:e,children:t})=>e?n.createElement(n.Fragment,null,t):null,b=({condition:e,children:t})=>e===!1?n.createElement(n.Fragment,null,t):null,$=({all:e,any:t,none:l,children:a,fallback:o})=>y(()=>(e&&(t||l)&&console.warn('When: Multiple condition types (all, any, none) provided; "all" takes precedence.'),!!(e&&e.length>0&&e.every(Boolean)||t&&t.length>0&&t.some(Boolean)||l&&l.length>0&&l.every(r=>!r))),[e,t,l])?n.createElement(n.Fragment,null,a):n.createElement(n.Fragment,null,o||null),D=({data:e,transform:t,render:l,fallback:a})=>{const o=y(()=>t.reduce((r,c)=>c(r),e),[e,t]);return o==null?n.createElement(n.Fragment,null,a||null):n.createElement(n.Fragment,null,l(o))},O=e=>{const{source:t,options:l,target:a="value",toggleTarget:o="toggle",next:r,children:c}=e,m=y(()=>l.includes(t)?t:l[0],[t,l]),[f,s]=S(m),d=()=>{s(i=>l.length?r?r(i,l):l[(l.indexOf(i)+1)%l.length]||l[0]:i)};return n.Children.map(c,i=>n.isValidElement(i)?n.cloneElement(i,{[a]:f,[o]:d}):i)},_=e=>{const{children:t,h:l,w:a,size:o,height:r,width:c,className:m}=e;return n.createElement("div",{style:{width:o||a||c,height:o||l||r,flexShrink:0},className:m},t)};function A(e){const{items:t,renderItem:l,filter:a}=e;return t?n.createElement(I,null,t.map((o,r)=>a&&!a(o)?null:l(o,r))):(console.error("ArrayRender: items is null"),null)}const B=({let:e,props:t,children:l,fallback:a})=>{const o=y(()=>typeof e=="function"?e(t):e,[e,t]);return!l||!Object.keys(o).length?n.createElement(n.Fragment,null,a||null):n.createElement(n.Fragment,null,l(o))},R="onChange",V="value";function P(e){const{defaultValue:t,onBeforeChange:l,trigger:a=R,valuePropName:o=V,props:r}=e,c=Object.prototype.hasOwnProperty.call(r,o),[m,f]=S(t),s=c?r[o]:m,d=y(()=>r[a],[r,a]),i=T(u=>{const F=typeof u=="function"?u(s):u;l&&l(F,s)===!1||(c||f(F),d&&d(F))},[c,l,a,s,d]);return[s,i]}export{A as ArrayRender,b as False,h as If,D as Pipe,B as Scope,_ as SizeBox,p as Switch,O as Toggle,k as True,$ as When,C as childrenLoop,P as useControlled};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wwog/react",
-  "version": "1.1.7",
+  "version": "1.2.0",
   "description": "",
   "keywords": [],
   "author": "wwog",
@@ -19,8 +19,7 @@
     "format": "biome format --write src",
     "check": "biome check --apply src",
     "test": "pnpm check && pnpm test:types && vitest run --coverage",
-    "test:types": "tsc --noEmit --skipLibCheck",
-    "preinstall": "npx only-allow pnpm"
+    "test:types": "tsc --noEmit --skipLibCheck"
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",

package/src/Common/SizeBox.tsx

@@ -7,16 +7,22 @@ interface SizeBoxProps {
   h?: number | string;
   w?: number | string;
   children?: ReactNode;
+  className?: string;
 }
 /**
  * @description SizeBox 组件用于设置一个固定大小的盒子
  */
 export const SizeBox: FC<SizeBoxProps> = (props) => {
-  const { children, h, w, size, height, width } = props;
+  const { children, h, w, size, height, width, className } = props;
 
   const widthValue = size || w || width;
   const heightValue = size || h || height;
   return (
-    <div style={{ width: widthValue, height: heightValue }}>{children}</div>
+    <div
+      style={{ width: widthValue, height: heightValue, flexShrink: 0 }}
+      className={className}
+    >
+      {children}
+    </div>
   );
 };

package/src/ProcessControl/Toggle.tsx

@@ -0,0 +1,105 @@
+import React, { ReactNode, useState, useMemo } from "react";
+
+export interface ToggleProps<T = boolean> {
+  /**
+   * @description_en The initial value to toggle.
+   * @description_zh 初始切换值。
+   */
+  source: T;
+  /**
+   * @description_en Array of values to toggle between.
+   * @description_zh 可切换的值数组。
+   */
+  options: T[];
+  /**
+   * @description_en The prop name to pass the toggled value to children.
+   * @description_zh 将切换后的值传递给子节点的属性名。
+   * @default 'value'
+   */
+  target?: string;
+  /**
+   * @description_en The prop name to pass the toggle function to children.
+   * @description_zh 将切换函数传递给子节点的属性名。
+   * @default 'toggle'
+   */
+  toggleTarget?: string;
+  /**
+   * @description_en Function to determine the next value in the toggle sequence.
+   * @description_zh 确定切换序列中下一个值的函数。
+   * @optional
+   */
+  next?: (current: T, options: T[]) => T;
+  /**
+   * @description_en Content to render, receiving the toggled value and toggle function via the target and toggleTarget props.
+   * @description_zh 渲染的内容，通过 target 和 toggleTarget 属性接收切换后的值和切换函数。
+   */
+  children: ReactNode;
+}
+
+/**
+ * @description_zh 一个声明式组件，用于在预定义选项中切换值并通过指定属性传递给子组件，支持自定义切换逻辑。
+ * @description_en A declarative component for toggling between predefined values and passing them to children via specified props, supporting custom toggle logic.
+ * @component
+ * @example
+ * ```tsx
+ * interface ThemeChildProps {
+ *   theme: string;
+ *   toggleTheme: () => void;
+ * }
+ * const ThemeChild: FC<ThemeChildProps> = ({ theme, toggleTheme }) => (
+ *   <div onClick={toggleTheme}>当前主题: {theme}</div>
+ * );
+ *
+ * <Toggle source="light" options={["light", "dark"]} target="theme" toggleTarget="toggleTheme">
+ *   <ThemeChild />
+ * </Toggle>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <Toggle
+ *   source={1}
+ *   options={[1, 2, 3]}
+ *   target="value"
+ *   toggleTarget="toggleValue"
+ *   next={(current, options) => options[(options.indexOf(current) + 1) % options.length]}
+ * >
+ *   <ValueChild />
+ * </Toggle>
+ * ```
+ */
+export const Toggle = <T,>(props: ToggleProps<T>) => {
+  const {
+    source,
+    options,
+    target = "value",
+    toggleTarget = "toggle",
+    next,
+    children,
+  } = props;
+  const defaultValue = useMemo(() => {
+    return options.includes(source) ? source : options[0];
+  }, [source, options]);
+
+  const [currentValue, setCurrentValue] = useState<T>(defaultValue);
+
+  const toggle = () => {
+    setCurrentValue((prev) => {
+      if (!options.length) return prev;
+      const nextValue = next
+        ? next(prev, options)
+        : options[(options.indexOf(prev) + 1) % options.length] || options[0];
+      return nextValue;
+    });
+  };
+
+  return React.Children.map(children, (child) => {
+    if (React.isValidElement(child)) {
+      return React.cloneElement(child, {
+        [target]: currentValue,
+        [toggleTarget]: toggle,
+      } as { [key: string]: any });
+    }
+    return child;
+  });
+};

package/src/ProcessControl/index.ts

@@ -1,4 +1,5 @@
 export * from "./Switch";
 export * from "./If";
 export * from "./When";
-export * from "./Pipe";
+export * from "./Pipe";
+export * from "./Toggle";

package/src/hooks/index.ts

@@ -0,0 +1 @@
+export * from "./useControlled";

package/src/hooks/useControlled.ts

@@ -0,0 +1,73 @@
+import { useCallback, useMemo, useState, type Dispatch } from "react";
+
+const DEFAULT_TRIGGER = "onChange";
+const DEFAULT_VALUE_PROP_NAME = "value";
+
+export interface UseControlledOptions<T> {
+  /**
+   * @description - 非受控模式下的默认值,会被受控模式下的值覆盖
+   * @description_en - Default value in uncontrolled mode, will be overridden by the value in controlled mode
+   */
+  defaultValue: T;
+  /**
+   * @description - 值变更前的回调函数，可用于拦截或修改新值
+   * @description_en - Callback function before the value changes, can be used to intercept or modify the new value
+   */
+  onBeforeChange?: (newValue: T, currentValue: T) => boolean | void;
+  /**
+   * @description - 当值发生变化时触发的回调函数名
+   * @description_en - Callback function name triggered when the value changes
+   * @default - onChange
+   */
+  trigger?: string;
+  /**
+   * @description - 值的属性名
+   * @description_en - Property name of the value
+   * @default - value
+   */
+  valuePropName?: string;
+  props: Record<string, any>;
+}
+
+export function useControlled<T>(
+  options: UseControlledOptions<T>
+): [T, Dispatch<React.SetStateAction<T>>] {
+  const {
+    defaultValue,
+    onBeforeChange,
+    trigger = DEFAULT_TRIGGER,
+    valuePropName = DEFAULT_VALUE_PROP_NAME,
+    props,
+  } = options;
+  const isControlled = Object.prototype.hasOwnProperty.call(
+    props,
+    valuePropName
+  );
+  const [internalValue, setInternalValue] = useState<T>(defaultValue);
+  const value = isControlled ? props[valuePropName] : internalValue;
+  const onChange = useMemo(() => props[trigger], [props, trigger]);
+
+  const setValue = useCallback<Dispatch<React.SetStateAction<T>>>(
+    (newValue) => {
+      const resolvedValue =
+        typeof newValue === "function"
+          ? (newValue as (prev: T) => T)(value)
+          : newValue;
+      if (onBeforeChange) {
+        const shouldProceed = onBeforeChange(resolvedValue, value);
+        if (shouldProceed === false) {
+          return;
+        }
+      }
+      if (!isControlled) {
+        setInternalValue(resolvedValue);
+      }
+      if (onChange) {
+        onChange(resolvedValue);
+      }
+    },
+    [isControlled, onBeforeChange, trigger, value, onChange]
+  );
+
+  return [value, setValue];
+}

package/src/index.ts

@@ -1,3 +1,4 @@
 export * from "./ProcessControl";
 export * from "./Common";
 export * from "./utils";
+export * from "./hooks";