@wwog/react 1.1.6 → 1.1.7

package/README.md

@@ -5,6 +5,10 @@
 [![npm version](https://img.shields.io/npm/v/@wwog/react.svg)](https://www.npmjs.com/package/@wwog/react)
 [![ESM](https://img.shields.io/badge/📦-ESM%20only-brightgreen.svg)](https://nodejs.org/api/esm.html)
 
+---
+
+[English Documentation](./README_en.md)
+
 ## 安装
 
 ```bash
@@ -161,6 +165,67 @@ function UserList({ users }) {
 }
 ```
 
+#### `<Pipe>` (v1.1.7+)
+
+声明式的数据管道处理组件，适合多步骤数据转换和链式处理。
+
+> 声明式数据处理，替代嵌套函数调用。
+> 提高代码可读性，逻辑清晰。
+> 适合数据清洗、格式化等场景。
+
+```tsx
+import { Pipe } from "@wwog/react";
+
+function Example({ users }) {
+  return (
+    <Pipe
+      data={users}
+      transform={[
+        (data) => data.filter(user => user.active),
+        (data) => data.map(user => user.name)
+      ]}
+      render={(names) => <div>{names.join(", ")}</div>}
+      fallback={<div>No Data</div>}
+    />
+  );
+}
+```
+
+- `data`：初始数据。
+- `transform`：数据转换函数数组，按顺序依次处理。
+- `render`：渲染最终结果。
+- `fallback`：结果为 null/undefined 时的兜底内容。
+
+#### `<Scope>` (v1.1.7+)
+
+为子节点提供局部作用域，声明式定义临时变量，简化复杂渲染逻辑。
+
+> 避免在组件外定义临时状态或计算。
+> 声明式定义局部变量，增强代码自包含性。
+> 适合表单、计算密集型渲染等场景。
+
+```tsx
+import { Scope } from "@wwog/react";
+
+function Example() {
+  return (
+    <Scope let={{ count: 1, text: "Hello" }}>
+      {({ count, text }) => <div>{text} {count}</div>}
+    </Scope>
+  );
+}
+
+// 支持函数式 let
+<Scope let={(props) => ({ total: props.items.length })} props={{ items: [1, 2] }} fallback={<div>Empty</div>}>
+  {({ total }) => <div>Total: {total}</div>}
+</Scope>
+```
+
+- `let`：对象或函数，定义作用域变量。
+- `props`：传递给 let 函数的参数。
+- `children`：作用域变量的渲染函数。
+- `fallback`：无内容时的兜底渲染。
+
 #### `<SizeBox>`
 
 创建固定尺寸的容器，用于布局调整和间距控制。
@@ -184,6 +249,21 @@ function Layout() {
 }
 ```
 
+### Ideas
+
+> 需求不高,但有用的组件
+
+- Loop：灵活的迭代渲染，支持数组、对象和范围。
+- Try：封装异步逻辑，处理 Promise 状态。
+- Toggle：基于布尔状态切换 on 和 off 内容。
+- Pick：轻量版值选择渲染，类似枚举匹配。
+- Render：动态渲染函数，简化复杂渲染逻辑。
+- Once：确保内容仅渲染一次，适合初始化。
+- Each：增强列表渲染，支持过滤和排序。
+
+
 ## License
 
 MIT
+
+

package/dist/index.d.mts

@@ -138,6 +138,58 @@ interface WhenProps {
  */
 declare const When: FC<WhenProps>;
 
+/**
+ * Props for the `Pipe` component.
+ *
+ * @interface PipeProps
+ * @property {any} data - The initial data to process.
+ * @property {((input: any) => any)[]} transform - Array of functions to transform the data.
+ * @property {(result: any) => ReactNode} render - Function to render the transformed data.
+ * @property {ReactNode} [fallback] - Content to render if the result is null or undefined.
+ */
+interface PipeProps {
+    /**
+     * @description_en The initial data to process.
+     * @description_zh 要处理的初始数据。
+     */
+    data: any;
+    /**
+     * @description_en Array of functions to transform the data.
+     * @description_zh 转换数据的函数数组。
+     */
+    transform: ((input: any) => any)[];
+    /**
+     * @description_en Function to render the transformed data.
+     * @description_zh 渲染转换后数据的函数。
+     */
+    render: (result: any) => ReactNode;
+    /**
+     * @description_en Content to render if the result is null or undefined.
+     * @description_zh 如果结果为 null 或 undefined 时渲染的内容。
+     * @optional
+     * @default null
+     */
+    fallback?: ReactNode;
+}
+/**
+ * @description_zh 一个声明式组件，用于通过管道式处理数据并渲染，简化多步骤数据转换。
+ * @description_en A declarative component for processing data through a pipeline and rendering, simplifying multi-step data transformations.
+ * @component
+ * @example
+ * ```tsx
+ * <Pipe
+ *   data={users}
+ *   transform={[
+ *     (data) => data.filter(user => user.active),
+ *     (data) => data.map(user => user.name)
+ *   ]}
+ *   render={(names) => <div>{names.join(", ")}</div>}
+ *   fallback={<div>No Data</div>}
+ * />
+ * ```
+ */
+declare const Pipe: FC<PipeProps>;
+
 interface SizeBoxProps {
     size?: number | string;
     height?: number | string;
@@ -158,11 +210,66 @@ interface ArrayRenderProps<T> {
 }
 declare function ArrayRender<T>(props: ArrayRenderProps<T>): ReactNode;
 
+/**
+ * Props for the `Scope` component.
+ *
+ * @interface ScopeProps
+ * @property {Record<string, any> | ((props: any) => Record<string, any>)} let - An object or function defining local variables for the scope.
+ * @property {any} [props] - Optional props passed to the let function.
+ * @property {(scope: Record<string, any>) => ReactNode} [children] - Render function to access the scope variables.
+ * @property {ReactNode} [fallback] - Content to render if children or scope is empty.
+ */
+interface ScopeProps {
+    /**
+     * @description_en An object or function defining local variables for the scope.
+     * @description_zh 定义作用域局部变量的对象或函数。
+     */
+    let: Record<string, any> | ((props: any) => Record<string, any>);
+    /**
+     * @description_en Optional props passed to the let function.
+     * @description_zh 传递给 let 函数的可选属性。
+     * @optional
+     */
+    props?: any;
+    /**
+     * @description_en Render function to access the scope variables.
+     * @description_zh 访问作用域变量的渲染函数。
+     * @optional
+     */
+    children?: (scope: Record<string, any>) => ReactNode;
+    /**
+     * @description_en Content to render if children or scope is empty.
+     * @description_zh 如果 children 或 scope 为空时渲染的内容。
+     * @optional
+     * @default null
+     */
+    fallback?: ReactNode;
+}
+/**
+ * @description_zh 一个声明式组件，为子节点提供局部作用域，简化临时状态或上下文管理。
+ * @description_en A declarative component that provides a local scope for children, simplifying temporary state or context management.
+ * @component
+ * @example
+ * ```tsx
+ * <Scope let={{ count: 1, text: "Hello" }}>
+ *   {({ count, text }) => <div>{text} {count}</div>}
+ * </Scope>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <Scope let={(props) => ({ total: props.items.length })} props={{ items: [1, 2] }} fallback={<div>Empty</div>}>
+ *   {({ total }) => <div>Total: {total}</div>}
+ * </Scope>
+ * ```
+ */
+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;
 
-export { ArrayRender, False, If, SizeBox, Switch, True, When, childrenLoop };
-export type { ArrayRenderProps, ElseIfProps, ElseProps, FalseProps, IfProps, SwitchCaseProps, SwitchDefaultProps, SwitchProps, ThenProps, TrueProps, WhenProps };
+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 };

package/dist/index.js

@@ -1 +1 @@
-import n,{useMemo as F,Fragment as I}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 S=(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 c=e=>{const{value:l,compare:t=S,children:a,strict:i=!1}=e,r=new Set;let o=null,g=null,N=!1;return v(a,(h,u)=>{if(!n.isValidElement(h))throw new Error(`Switch Children only accepts valid React elements at index ${u}`);const d=h.type;if(d.displayName===f.displayName){const m=h.props;if(r.has(m.value))throw new Error(`Switch found duplicate Case value at index ${u}: ${JSON.stringify(m.value)}${i?" (detected in strict mode)":""}`);if(r.add(m.value),!o&&t(l,m.value)&&(o=m.children,i===!1))return!1}else if(d.displayName===p.displayName){if(N)throw new Error(`Switch can only have one Default child at index ${u}`);if(N=!0,g=h.props.children,!i&&o)return!1}else throw new Error(`Switch Children only accepts 'Case' or 'Default' elements, found: ${String(d.displayName||d.name||d)} at index ${u}`)}),n.createElement(n.Fragment,null,o??g)};c.displayName="Switch",c.Case=f,c.Default=p,c.createTyped=function(){return{Switch:c,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 s=({condition:e,children:l})=>{let t=null,a=null;const i=[];if(n.Children.forEach(l,r=>{if(!n.isValidElement(r))throw new Error("If component only accepts valid React elements");const o=r.type;if(o.displayName===y.displayName){if(t)throw new Error("If component can only have one Then child");t=r}else if(o.displayName===w.displayName)i.push(r);else if(o.displayName===E.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(o.displayName||o.name||o)}`)}),e)return t?n.createElement(n.Fragment,null,t.props.children):null;for(const r of i)if(r.props.condition)return n.createElement(n.Fragment,null,r.props.children);return a?n.createElement(n.Fragment,null,a.props.children):null};s.displayName="If",s.Then=y,s.ElseIf=w,s.Else=E,s.createTyped=function(){return{If:s,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,x=({all:e,any:l,none:t,children:a,fallback:i})=>F(()=>(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(r=>!r))),[e,l,t])?n.createElement(n.Fragment,null,a):n.createElement(n.Fragment,null,i||null),$=e=>{const{children:l,h:t,w:a,size:i,height:r,width:o}=e;return n.createElement("div",{style:{width:i||a||o,height:i||t||r}},l)};function D(e){const{items:l,renderItem:t,filter:a}=e;return l?n.createElement(I,null,l.map((i,r)=>a&&!a(i)?null:t(i,r))):(console.error("ArrayRender: items is null"),null)}export{D as ArrayRender,T as False,s as If,$ as SizeBox,c as Switch,C as True,x as When,v as childrenLoop};
+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};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wwog/react",
-  "version": "1.1.6",
+  "version": "1.1.7",
   "description": "",
   "keywords": [],
   "author": "wwog",

package/src/Common/Scope.tsx

@@ -0,0 +1,77 @@
+import React, { FC, ReactNode, useMemo } from "react";
+
+/**
+ * Props for the `Scope` component.
+ *
+ * @interface ScopeProps
+ * @property {Record<string, any> | ((props: any) => Record<string, any>)} let - An object or function defining local variables for the scope.
+ * @property {any} [props] - Optional props passed to the let function.
+ * @property {(scope: Record<string, any>) => ReactNode} [children] - Render function to access the scope variables.
+ * @property {ReactNode} [fallback] - Content to render if children or scope is empty.
+ */
+export interface ScopeProps {
+  /**
+   * @description_en An object or function defining local variables for the scope.
+   * @description_zh 定义作用域局部变量的对象或函数。
+   */
+  let: Record<string, any> | ((props: any) => Record<string, any>);
+  /**
+   * @description_en Optional props passed to the let function.
+   * @description_zh 传递给 let 函数的可选属性。
+   * @optional
+   */
+  props?: any;
+  /**
+   * @description_en Render function to access the scope variables.
+   * @description_zh 访问作用域变量的渲染函数。
+   * @optional
+   */
+  children?: (scope: Record<string, any>) => ReactNode;
+  /**
+   * @description_en Content to render if children or scope is empty.
+   * @description_zh 如果 children 或 scope 为空时渲染的内容。
+   * @optional
+   * @default null
+   */
+  fallback?: ReactNode;
+}
+/* 
+设计原因
+避免在组件外定义临时状态或计算。
+声明式定义局部变量，增强代码自包含性。
+适合表单、计算密集型渲染等场景。 
+*/
+/**
+ * @description_zh 一个声明式组件，为子节点提供局部作用域，简化临时状态或上下文管理。
+ * @description_en A declarative component that provides a local scope for children, simplifying temporary state or context management.
+ * @component
+ * @example
+ * ```tsx
+ * <Scope let={{ count: 1, text: "Hello" }}>
+ *   {({ count, text }) => <div>{text} {count}</div>}
+ * </Scope>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <Scope let={(props) => ({ total: props.items.length })} props={{ items: [1, 2] }} fallback={<div>Empty</div>}>
+ *   {({ total }) => <div>Total: {total}</div>}
+ * </Scope>
+ * ```
+ */
+export const Scope: FC<ScopeProps> = ({
+  let: letValue,
+  props,
+  children,
+  fallback,
+}) => {
+  const scope = useMemo(() => {
+    return typeof letValue === "function" ? letValue(props) : letValue;
+  }, [letValue, props]);
+
+  if (!children || !Object.keys(scope).length) {
+    return <>{fallback || null}</>;
+  }
+
+  return <>{children(scope)}</>;
+};

package/src/Common/index.ts

@@ -1,2 +1,3 @@
 export * from "./SizeBox";
 export * from "./ArrayRender";
+export * from "./Scope";

package/src/ProcessControl/Pipe.tsx

@@ -0,0 +1,64 @@
+import React, { FC, ReactNode, useMemo } from "react";
+
+/**
+ * Props for the `Pipe` component.
+ *
+ * @interface PipeProps
+ * @property {any} data - The initial data to process.
+ * @property {((input: any) => any)[]} transform - Array of functions to transform the data.
+ * @property {(result: any) => ReactNode} render - Function to render the transformed data.
+ * @property {ReactNode} [fallback] - Content to render if the result is null or undefined.
+ */
+export interface PipeProps {
+  /**
+   * @description_en The initial data to process.
+   * @description_zh 要处理的初始数据。
+   */
+  data: any;
+  /**
+   * @description_en Array of functions to transform the data.
+   * @description_zh 转换数据的函数数组。
+   */
+  transform: ((input: any) => any)[];
+  /**
+   * @description_en Function to render the transformed data.
+   * @description_zh 渲染转换后数据的函数。
+   */
+  render: (result: any) => ReactNode;
+  /**
+   * @description_en Content to render if the result is null or undefined.
+   * @description_zh 如果结果为 null 或 undefined 时渲染的内容。
+   * @optional
+   * @default null
+   */
+  fallback?: ReactNode;
+}
+
+/**
+ * @description_zh 一个声明式组件，用于通过管道式处理数据并渲染，简化多步骤数据转换。
+ * @description_en A declarative component for processing data through a pipeline and rendering, simplifying multi-step data transformations.
+ * @component
+ * @example
+ * ```tsx
+ * <Pipe
+ *   data={users}
+ *   transform={[
+ *     (data) => data.filter(user => user.active),
+ *     (data) => data.map(user => user.name)
+ *   ]}
+ *   render={(names) => <div>{names.join(", ")}</div>}
+ *   fallback={<div>No Data</div>}
+ * />
+ * ```
+ */
+export const Pipe: FC<PipeProps> = ({ data, transform, render, fallback }) => {
+  const result = useMemo(() => {
+    return transform.reduce((acc, fn) => fn(acc), data);
+  }, [data, transform]);
+
+  if (result == null) {
+    return <>{fallback || null}</>;
+  }
+
+  return <>{render(result)}</>;
+};

package/src/ProcessControl/index.ts

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