@wwog/react 1.2.6 → 1.2.8

package/dist/index.d.mts

@@ -262,15 +262,46 @@ declare const Scope: FC<ScopeProps>;
 type CxInput = string | string[] | Record<string, boolean> | undefined | null | false;
 declare function cx(...args: CxInput[]): string;
 
-interface ClassNameProps {
-    className?: {
-        base?: CxInput;
-        hover?: CxInput;
-        active?: CxInput;
-        focus?: CxInput;
-        disabled?: CxInput;
-        [key: string]: CxInput;
-    };
+interface StylesDescriptor {
+    base?: CxInput;
+    hover?: CxInput;
+    active?: CxInput;
+    focus?: CxInput;
+    disabled?: CxInput;
+    color?: CxInput;
+    size?: CxInput;
+    layer?: CxInput;
+    wrapper?: CxInput;
+    dark?: CxInput;
+    light?: CxInput;
+    sundry?: CxInput;
+    [key: string]: CxInput;
+}
+type StylesType = StylesDescriptor | string;
+interface StylesProps {
+    /**
+     * @description_en either as a simple string or a categorized object with predefined or custom keys.
+     * @description 可以是简单字符串或包含预定义或自定义键的分类对象。
+     * @example
+     * ```tsx
+     * // Simple string
+     * <Styles className="p-2 bg-red">
+     *   <button>Click</button>
+     * </Styles>
+     *
+     * // Categorized object
+     * <Styles
+     *   className={{
+     *     base: ["p-2", { "bg-red": true }],
+     *     hover: "hover:bg-blue",
+     *     color: "text-blue",
+     *   }}
+     * >
+     *   <button>Click</button>
+     * </Styles>
+     * ```
+     */
+    className?: StylesType;
     /**
      * @description 传入容器标签名.是否生成包含所有 `className` 的 `wrapper`, 默认 false, 传递 `true` 为 `div。`
      * @description_en Whether to generate a `wrapper` containing all `className`, default is false, and pass the container tag name, if `true` will be `div`.
@@ -279,30 +310,27 @@ interface ClassNameProps {
     children?: React$1.ReactNode;
 }
 /**
- * @description 用于将 `className` 分类编写的组件，内置了类似`clsx`的功能,并且去除重复的 className。
- * @description_en A component for `className` classification, built-in similar to `clsx` functionality, and removes duplicate className.
+ * @description 分类编写样式和基本的string样式，内置类似 `clsx` 对类型描述对象的值进行组合，支持去除重复类名,支持嵌套。
+ * @description_en Categorized writing styles and basic string styles, built-in similar to `clsx` to combine the values of type description objects, support removing duplicate class names, and support nesting.
  * @component
  * @example
  * ```tsx
- * <ClassName className={{ base: "p-2 bg-red", hover: ["hover:bg-blue", { "hover:text-white": true }] }}>
+ * <Styles className={{ base: "p-2 bg-red", hover: ["hover:bg-blue", { "hover:text-white": true }] }}>
  *   <button>Click me</button>
- * </ClassName>
+ * </Styles>
  * ```
  *
  * @example
  * ```tsx
- * <ClassName
- *   className={{
- *     base: ["p-2", { "bg-red": condition }],
- *     hover: { "hover:bg-blue": true },
- *   }}
+ * <Styles
+ *   className="p-2 bg-red"
  *   asWrapper="span"
  * >
  *   <button>Click me</button>
- * </ClassName>
+ * </Styles>
  * ```
  */
-declare const ClassName: FC<ClassNameProps>;
+declare const Styles: FC<StylesProps>;
 
 interface ToggleProps<T = boolean> {
     /**
@@ -466,5 +494,5 @@ declare class Counter {
  */
 declare function childrenLoop(children: React$1.ReactNode | undefined, callback: (child: React$1.ReactNode, index: number) => boolean | void): void;
 
-export { ArrayRender, ClassName, Counter, DateRender, False, If, Pipe, Scope, SizeBox, Switch, Toggle, True, When, childrenLoop, cx, formatDate, useControlled };
-export type { ArrayRenderProps, ClassNameProps, CxInput, DateRenderProps, ElseIfProps, ElseProps, FalseProps, IfProps, PipeProps, ScopeProps, SwitchCaseProps, SwitchDefaultProps, SwitchProps, ThenProps, ToggleProps, TrueProps, UseControlledOptions, WhenProps };
+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 };

package/dist/index.js

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

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "@wwog/react",
-  "version": "1.2.6",
-  "description": "",
-  "keywords": [],
+  "version": "1.2.8",
+  "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",
+    "components",
+    "library",
+    "utils",
+    "declarative ui"
+  ],
   "author": "wwog",
   "type": "module",
   "main": "dist/index.js",
@@ -18,18 +24,23 @@
     "build": "unbuild",
     "format": "biome format --write src",
     "check": "biome check --write src",
-    "test": "vitest run",
+    "test:unit": "vitest run",
     "test:types": "tsc --noEmit --skipLibCheck",
-    "all-suites": "pnpm run format && pnpm run check && pnpm run test:types && pnpm run test"
+    "all-suites": "pnpm run format && pnpm run check && pnpm run test:types && pnpm run test:unit",
+    "test:watch": "vitest"
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
     "@types/react": "^19.1.2",
     "@types/react-dom": "^19.1.2",
-    "@vitest/coverage-v8": "^3.1.1",
+    "@vitejs/plugin-react": "^4.4.1",
+    "@vitest/browser": "^3.1.3",
+    "@vitest/coverage-v8": "^3.1.3",
+    "playwright": "^1.52.0",
     "typescript": "^5.8.3",
     "unbuild": "^3.5.0",
-    "vitest": "^3.1.1"
+    "vitest": "^3.1.3",
+    "vitest-browser-react": "^0.1.1"
   },
   "peerDependencies": {
     "react": ">=16.8.0",

package/src/components/Sundry/Styles.test.tsx

@@ -0,0 +1,128 @@
+import { expect, describe, it } from "vitest";
+import { render } from "vitest-browser-react";
+import { Styles } from "./Styles";
+import React from "react";
+
+describe("Styles Component", () => {
+  it("测试传递styles的className StylesDescriptor", () => {
+    const { getByRole } = render(
+      <Styles
+        className={{
+          base: ["p-2"],
+          hover: "hover:bg-blue",
+          color: "text-blue",
+        }}
+      >
+        <button>Click</button>
+      </Styles>
+    );
+    const renderClassName = getByRole("button").elements()[0].className;
+    expect(renderClassName).toBe("p-2 hover:bg-blue text-blue");
+  });
+
+  it("测试传递styles的className string", () => {
+    const { getByRole } = render(
+      <Styles className="button_class">
+        <button>Click</button>
+      </Styles>
+    );
+    const renderClassName = getByRole("button").elements()[0].className;
+    expect(renderClassName).toBe("button_class");
+  });
+
+  it("测试嵌套的Styles组件,仅string", () => {
+    const { getByRole } = render(
+      <Styles className="outer">
+        <Styles className="inner">
+          <button>Click</button>
+        </Styles>
+      </Styles>
+    );
+    const renderClassName = getByRole("button").elements()[0].className;
+    expect(renderClassName).toBe("outer inner");
+  });
+
+  it("测试嵌套的Styles组件,含string和StylesDescriptor", () => {
+    const { getByRole } = render(
+      <Styles
+        className={{
+          base: ["p-2"],
+          hover: "hover:bg-blue",
+          color: "text-blue",
+        }}
+      >
+        <Styles className="button_class">
+          <button>Click</button>
+        </Styles>
+      </Styles>
+    );
+    const renderClassName = getByRole("button").elements()[0].className;
+    expect(renderClassName).toBe("p-2 hover:bg-blue text-blue button_class");
+  });
+
+  it("测试children本身含有样式的混入", () => {
+    const { getByRole } = render(
+      <Styles className={{ base: "wrapper" }}>
+        <Styles className="outer">
+          <button className="inner">Click</button>
+        </Styles>
+      </Styles>
+    );
+    const renderClassName = getByRole("button").elements()[0].className;
+    expect(renderClassName).toBe("wrapper outer inner");
+  });
+
+  it("测试传递属性空值", () => {
+    const { getByRole } = render(
+      <Styles className={undefined}>
+        <button>Click</button>
+      </Styles>
+    );
+    const renderClassName = getByRole("button").elements()[0].className;
+    expect(renderClassName).toBe("");
+  });
+
+  it("测试空值与有值嵌套", () => {
+    const { getByRole } = render(
+      <Styles className={undefined}>
+        <Styles className="inner">
+          <button>Click</button>
+        </Styles>
+      </Styles>
+    );
+    const renderClassName = getByRole("button").elements()[0].className;
+    expect(renderClassName).toBe("inner");
+  });
+
+  it("测试asWrapper为true", () => {
+    const { container } = render(
+      <Styles className="wrapper" asWrapper={true}>
+        <button>Click</button>
+      </Styles>
+    );
+    expect(container.querySelector("div")?.className).toBe("wrapper");
+    expect(container.querySelector("button")?.className).toBe("");
+  });
+
+  it("测试asWrapper为指定标签", () => {
+    const { container } = render(
+      <Styles className="wrapper" asWrapper="section">
+        <button>Click</button>
+      </Styles>
+    );
+    expect(container.querySelector("section")?.className).toBe("wrapper");
+    expect(container.querySelector("button")?.className).toBe("");
+  });
+
+  it("测试asWrapper与嵌套组合", () => {
+    const { container } = render(
+      <Styles className="outer" asWrapper="div">
+        <Styles className="inner">
+          <button className="btn">Click</button>
+        </Styles>
+      </Styles>
+    );
+    expect(container.querySelector("div")?.className).toBe("outer");
+    expect(container.querySelector("button")?.className).toBe("inner btn");
+  });
+});

package/src/components/Sundry/Styles.tsx

@@ -0,0 +1,131 @@
+import React, {
+  Children,
+  cloneElement,
+  FC,
+  Fragment,
+  isValidElement,
+  type HTMLElementType,
+} from "react";
+import { cx, type CxInput } from "../../utils/cx";
+
+export interface StylesDescriptor {
+  base?: CxInput;
+  hover?: CxInput;
+  active?: CxInput;
+  focus?: CxInput;
+  disabled?: CxInput;
+  color?: CxInput;
+  size?: CxInput;
+  layer?: CxInput;
+  wrapper?: CxInput;
+  dark?: CxInput;
+  light?: CxInput;
+  sundry?: CxInput;
+  [key: string]: CxInput;
+}
+
+const isStylesDescriptor = (obj: any): obj is StylesDescriptor => {
+  return typeof obj === "object" && !!obj;
+};
+
+export type StylesType = StylesDescriptor | string;
+
+export interface StylesProps {
+  /**
+   * @description_en either as a simple string or a categorized object with predefined or custom keys.
+   * @description 可以是简单字符串或包含预定义或自定义键的分类对象。
+   * @example
+   * ```tsx
+   * // Simple string
+   * <Styles className="p-2 bg-red">
+   *   <button>Click</button>
+   * </Styles>
+   *
+   * // Categorized object
+   * <Styles
+   *   className={{
+   *     base: ["p-2", { "bg-red": true }],
+   *     hover: "hover:bg-blue",
+   *     color: "text-blue",
+   *   }}
+   * >
+   *   <button>Click</button>
+   * </Styles>
+   * ```
+   */
+  className?: StylesType;
+  /**
+   * @description 传入容器标签名.是否生成包含所有 `className` 的 `wrapper`, 默认 false, 传递 `true` 为 `div。`
+   * @description_en Whether to generate a `wrapper` containing all `className`, default is false, and pass the container tag name, if `true` will be `div`.
+   */
+  asWrapper?: boolean | HTMLElementType;
+  children?: React.ReactNode;
+}
+
+/**
+ * @description 分类编写样式和基本的string样式，内置类似 `clsx` 对类型描述对象的值进行组合，支持去除重复类名,支持嵌套。
+ * @description_en Categorized writing styles and basic string styles, built-in similar to `clsx` to combine the values of type description objects, support removing duplicate class names, and support nesting.
+ * @component
+ * @example
+ * ```tsx
+ * <Styles className={{ base: "p-2 bg-red", hover: ["hover:bg-blue", { "hover:text-white": true }] }}>
+ *   <button>Click me</button>
+ * </Styles>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <Styles
+ *   className="p-2 bg-red"
+ *   asWrapper="span"
+ * >
+ *   <button>Click me</button>
+ * </Styles>
+ * ```
+ */
+export const Styles: FC<StylesProps> = ({
+  className,
+  children,
+  asWrapper = false,
+}) => {
+  if (!children) {
+    return null;
+  }
+  if (Children.count(children) > 1) {
+    console.error(
+      "<Styles>: children has more than one child. Please check your code."
+    );
+    return <Fragment>{children}</Fragment>;
+  }
+
+  if (!className) {
+    return <Fragment>{children}</Fragment>;
+  }
+
+  const generatedClassName =
+    typeof className === "string" ? className : cx(...Object.values(className));
+
+  if (asWrapper) {
+    const Tag = asWrapper === true ? "div" : asWrapper;
+    return <Tag className={generatedClassName}>{children}</Tag>;
+  }
+  if (isValidElement(children)) {
+    const typeChildren = children as any;
+    let processedChildClassName = typeChildren?.props?.className;
+
+    if (typeChildren?.type?.displayName === Styles.displayName) {
+      if (isStylesDescriptor(processedChildClassName)) {
+        processedChildClassName = cx(...Object.values(processedChildClassName));
+      }
+    }
+
+    return cloneElement(children, {
+      className: cx(generatedClassName, processedChildClassName),
+    } as any);
+  }
+  console.error(
+    "<Styles>: children is not a valid React element. Please check your code."
+  );
+  return <Fragment>{children}</Fragment>;
+};
+Styles.displayName = "W/Styles";

package/src/components/Sundry/index.ts

@@ -1,4 +1,4 @@
 export * from './SizeBox'
 export * from './Scope'
-export * from './ClassName'
+export * from './Styles'
 export * from './Toggle'

package/src/components/Sundry/ClassName.tsx

@@ -1,86 +0,0 @@
-import React, {
-  cloneElement,
-  FC,
-  Fragment,
-  isValidElement,
-  useEffect,
-  type HTMLElementType,
-} from "react";
-import { cx, type CxInput } from "../../utils/cx";
-
-export interface ClassNameProps {
-  className?: {
-    base?: CxInput;
-    hover?: CxInput;
-    active?: CxInput;
-    focus?: CxInput;
-    disabled?: CxInput;
-    [key: string]: CxInput;
-  };
-  /**
-   * @description 传入容器标签名.是否生成包含所有 `className` 的 `wrapper`, 默认 false, 传递 `true` 为 `div。`
-   * @description_en Whether to generate a `wrapper` containing all `className`, default is false, and pass the container tag name, if `true` will be `div`.
-   */
-  asWrapper?: boolean | HTMLElementType;
-  children?: React.ReactNode;
-}
-
-/**
- * @description 用于将 `className` 分类编写的组件，内置了类似`clsx`的功能,并且去除重复的 className。
- * @description_en A component for `className` classification, built-in similar to `clsx` functionality, and removes duplicate className.
- * @component
- * @example
- * ```tsx
- * <ClassName className={{ base: "p-2 bg-red", hover: ["hover:bg-blue", { "hover:text-white": true }] }}>
- *   <button>Click me</button>
- * </ClassName>
- * ```
- *
- * @example
- * ```tsx
- * <ClassName
- *   className={{
- *     base: ["p-2", { "bg-red": condition }],
- *     hover: { "hover:bg-blue": true },
- *   }}
- *   asWrapper="span"
- * >
- *   <button>Click me</button>
- * </ClassName>
- * ```
- */
-export const ClassName: FC<ClassNameProps> = (props) => {
-  const { className, children, asWrapper } = props;
-
-  useEffect(() => {
-    if (isValidElement(children) === false) {
-      console.warn(
-        "<ClassName>: children is not a valid React element. Please check your code."
-      );
-    }
-  }, [children]);
-
-  if (!children) {
-    return null;
-  }
-
-  if (!className) {
-    return <Fragment>{children}</Fragment>;
-  }
-
-  const generatedCls = cx(...Object.values(className));
-
-  if (asWrapper) {
-    const Wrapper = typeof asWrapper === "string" ? asWrapper : "div";
-    return <Wrapper className={generatedCls}>{children}</Wrapper>;
-  }
-
-  if (isValidElement(children)) {
-    return cloneElement(children, {
-      //@ts-expect-error type error
-      className: cx(children.props.className, generatedCls),
-    } as any);
-  }
-
-  return <Fragment>{children}</Fragment>;
-};