@wwog/react 1.3.8 → 1.3.9

package/README.md

@@ -477,6 +477,96 @@ Development notes: Internally implemented via `mediaQuery`, it does not listen t
 
 > Internal functions used by some components, which can also be used if needed
 
+#### `ruleChecker` (v1.3.9+)
+
+A type-safe data validation utility that provides comprehensive validation rules for different data types with full TypeScript support.
+
+```tsx
+import { ruleChecker } from "@wwog/react";
+
+// Define your data and validation rules
+const userData = {
+  username: 'john',
+  email: 'john@example.com',
+  age: 25,
+  hobbies: ['reading', 'coding']
+};
+
+const validationRules = {
+  username: { required: true, min: 3, max: 20 },
+  email: { required: true, email: true },
+  age: { required: true, min: 18, max: 120 },
+  hobbies: { min: 1, max: 5, unique: true }
+};
+
+// Validate the data
+const result = ruleChecker(userData, validationRules);
+
+if (result.valid) {
+  console.log('Data is valid:', result.data);
+} else {
+  console.log('Validation errors:', result.errors);
+  console.log('Field-specific errors:', result.fieldErrors);
+}
+```
+
+**Features:**
+- **Type-safe**: Full TypeScript support with automatic type inference
+- **Multiple data types**: Support for strings, numbers, booleans, and arrays
+- **Comprehensive rules**: Built-in validation for length, range, format, uniqueness, etc.
+- **Custom validators**: Support for custom validation functions
+- **Dependency validation**: Validate fields based on other field values
+- **Array element validation**: Validate individual elements within arrays
+- **Multiple rule support**: Apply multiple validation rules to a single field
+- **Detailed error reporting**: Get both general errors and field-specific errors
+
+**Available Rules:**
+- **Common rules**: `required`, `message`, `validator`, `dependsOn`
+- **String rules**: `min`, `max`, `len`, `regex`, `email`, `url`, `phone`
+- **Number rules**: `min`, `max`
+- **Array rules**: `min`, `max`, `len`, `unique`, `elementRule`
+- **Boolean rules**: Basic validation with custom validators
+
+**Complex Example:**
+```tsx
+const registrationData = {
+  username: 'user123',
+  email: 'user@example.com',
+  password: 'SecurePass123',
+  confirmPassword: 'SecurePass123',
+  age: 25,
+  tags: ['developer', 'typescript'],
+  terms: true
+};
+
+const rules = {
+  username: { required: true, min: 3, max: 20, regex: /^[a-zA-Z0-9_]+$/ },
+  email: { required: true, email: true },
+  password: [
+    { required: true, min: 8 },
+    { regex: /[A-Z]/, message: 'Password must contain uppercase letter' },
+    { regex: /[0-9]/, message: 'Password must contain number' }
+  ],
+  confirmPassword: {
+    required: true,
+    validator: (value, data) => value === data.password || 'Passwords do not match'
+  },
+  age: { required: true, min: 18, max: 120 },
+  tags: {
+    min: 1,
+    max: 10,
+    unique: true,
+    elementRule: { min: 2, max: 20 } // Each tag must be 2-20 characters
+  },
+  terms: {
+    required: true,
+    validator: (value) => value === true || 'You must accept the terms'
+  }
+};
+
+const result = ruleChecker(registrationData, rules);
+```
+
 #### `createExternalState` (v1.2.9+, useGetter added in v1.2.13)
 
 > v1.2.21: Refactor the API to move sideeffects into options and enhance support for the transform interface

package/dist/index.d.mts

@@ -716,8 +716,58 @@ type BreakpointName = (typeof breakpoints)[number];
 type BreakpointDesc = Partial<Record<BreakpointName, number>>;
 type Responsive<T> = T | Partial<Record<BreakpointName, T>>;
 
+type BaseRule<TAll, TValue> = {
+    required?: boolean;
+    message?: string;
+    validator?: (value: TValue, data: Partial<TAll>) => boolean | string;
+    dependsOn?: (data: Partial<TAll>) => boolean | string;
+};
+type LengthRuleProps = {
+    min?: number;
+    max?: number;
+    len?: number;
+};
+type NumberRangeProps = {
+    min?: number;
+    max?: number;
+};
+type StringSpecificProps = {
+    regex?: RegExp;
+    email?: boolean;
+    url?: boolean;
+    phone?: boolean;
+};
+type ArraySpecificProps = {
+    unique?: boolean;
+};
+type NumberRule<TAll> = BaseRule<TAll, number> & NumberRangeProps;
+type StringRule<TAll> = BaseRule<TAll, string> & LengthRuleProps & StringSpecificProps;
+type BooleanRule<TAll> = BaseRule<TAll, boolean>;
+type ArrayRule<TAll, U> = BaseRule<TAll, U[]> & LengthRuleProps & ArraySpecificProps & {
+    elementRule?: FieldRule<U, TAll>;
+};
+type FieldRule<TValue, TAll> = TValue extends string ? StringRule<TAll> : TValue extends number ? NumberRule<TAll> : TValue extends boolean ? BooleanRule<TAll> : TValue extends (infer U)[] ? ArrayRule<TAll, U> : BaseRule<TAll, TValue>;
+type RuleDescription<T extends Record<string, unknown>> = {
+    [K in keyof T]?: FieldRule<T[K], T> | FieldRule<T[K], T>[];
+};
+type IsRequired<R> = R extends {
+    required: true;
+} ? true : false;
+type ApplyRules<T extends Record<string, unknown>, R extends RuleDescription<T>> = {
+    [K in keyof T]: IsRequired<R[K]> extends true ? T[K] : T[K] | undefined;
+};
+type FieldErrors<T> = Partial<Record<keyof T, string[]>>;
+declare function ruleChecker<T extends Record<string, unknown>, R extends RuleDescription<T>>(data: Partial<T>, rules: R): {
+    valid: true;
+    data: ApplyRules<T, R>;
+} | {
+    valid: false;
+    errors: string[];
+    fieldErrors: FieldErrors<T>;
+};
+
 declare function getCurrentBreakpoint(breakpointDesc: BreakpointDesc, width: number): BreakpointName;
 declare function useScreen(breakpointDesc?: BreakpointDesc): "base" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
 
-export { ArrayRender, Counter, DateRender, DefBreakpointDesc, False, If, Observer, Pipe, Scope, SizeBox, Styles, Switch, Toggle, True, When, breakpoints, childrenLoop, createExternalState, createStorageState, cx, formatDate, getCurrentBreakpoint, safePromiseTry, useControlled, useScreen };
-export type { ArrayRenderProps, BreakpointDesc, BreakpointName, CreateStateListener, CxInput, DateRenderProps, ElseIfProps, ElseProps, ExternalSideEffect, ExternalState, ExternalStateOptions, ExternalWithKernel, FalseProps, IfProps, ObserverProps, PipeProps, Responsive, ScopeProps, StorageStateOptions, StylesDescriptor, StylesProps, StylesType, SwitchCaseProps, SwitchDefaultProps, SwitchProps, ThenProps, ToggleProps, Transform, TrueProps, UseControlledOptions, WhenProps };
+export { ArrayRender, Counter, DateRender, DefBreakpointDesc, False, If, Observer, Pipe, Scope, SizeBox, Styles, Switch, Toggle, True, When, breakpoints, childrenLoop, createExternalState, createStorageState, cx, formatDate, getCurrentBreakpoint, ruleChecker, safePromiseTry, useControlled, useScreen };
+export type { ApplyRules, ArrayRenderProps, ArrayRule, ArraySpecificProps, BaseRule, BooleanRule, BreakpointDesc, BreakpointName, CreateStateListener, CxInput, DateRenderProps, ElseIfProps, ElseProps, ExternalSideEffect, ExternalState, ExternalStateOptions, ExternalWithKernel, FalseProps, FieldRule, IfProps, LengthRuleProps, NumberRangeProps, NumberRule, ObserverProps, PipeProps, Responsive, RuleDescription, ScopeProps, StorageStateOptions, StringRule, StringSpecificProps, StylesDescriptor, StylesProps, StylesType, SwitchCaseProps, SwitchDefaultProps, SwitchProps, ThenProps, ToggleProps, Transform, TrueProps, UseControlledOptions, WhenProps };

package/dist/index.js

@@ -1 +1 @@
-import s,{useMemo as g,Fragment as S,Children as L,isValidElement as H,cloneElement as V,useEffect as w,useState as O,useRef as k,useCallback as Z}from"react";function Y(e,n){if(e===void 0)return;let t=0;if(Array.isArray(e)){for(const r of e)if(n(r,t++)===!1)break}else n(e,t)}const z=(e,n)=>e===n,v=e=>s.createElement(s.Fragment,null,e.children);v.displayName="Switch_Case";const N=e=>s.createElement(s.Fragment,null,e.children);N.displayName="Switch_Default";const y=e=>{const{value:n,compare:t=z,children:r,strict:l=!1}=e,o=new Set;let a=null,u=null,d=!1;return Y(r,(i,c)=>{if(!s.isValidElement(i))throw new Error(`Switch Children only accepts valid React elements at index ${c}`);const f=i.type;if(f.displayName===v.displayName){const m=i.props;if(o.has(m.value))throw new Error(`Switch found duplicate Case value at index ${c}: ${JSON.stringify(m.value)}${l?" (detected in strict mode)":""}`);if(o.add(m.value),!a&&t(n,m.value)&&(a=m.children,l===!1))return!1}else if(f.displayName===N.displayName){if(d)throw new Error(`Switch can only have one Default child at index ${c}`);if(d=!0,u=i.props.children,!l&&a)return!1}else throw new Error(`Switch Children only accepts 'Case' or 'Default' elements, found: ${String(f.displayName||f.name||f)} at index ${c}`)}),s.createElement(s.Fragment,null,a??u)};y.displayName="Switch",y.Case=v,y.Default=N,y.createTyped=function(){return{Switch:y,Case:v,Default:N}};const b=e=>s.createElement(s.Fragment,null,e.children),M=({children:e})=>s.createElement(s.Fragment,null,e),x=e=>s.createElement(s.Fragment,null,e.children);b.displayName="If_Then",M.displayName="If_Else",x.displayName="If_ElseIf";const p=({condition:e,children:n})=>{let t=null,r=null;const l=[];if(s.Children.forEach(n,o=>{if(!s.isValidElement(o))throw new Error("If component only accepts valid React elements");const a=o.type;if(a.displayName===b.displayName){if(t)throw new Error("If component can only have one Then child");t=o}else if(a.displayName===x.displayName)l.push(o);else if(a.displayName===M.displayName){if(r)throw new Error("If component can only have one Else child");r=o}else throw new Error(`If component only accepts 'Then', 'ElseIf', or 'Else' elements as children, found: ${String(a.displayName||a.name||a)}`)}),e)return t?s.createElement(s.Fragment,null,t.props.children):null;for(const o of l)if(o.props.condition)return s.createElement(s.Fragment,null,o.props.children);return r?s.createElement(s.Fragment,null,r.props.children):null};p.displayName="If",p.Then=b,p.ElseIf=x,p.Else=M,p.createTyped=function(){return{If:p,Then:b,ElseIf:x,Else:M}};const U=({condition:e,children:n})=>e?s.createElement(s.Fragment,null,n):null,G=({condition:e,children:n})=>e===!1?s.createElement(s.Fragment,null,n):null,q=({all:e,any:n,none:t,children:r,fallback:l})=>g(()=>(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])?s.createElement(s.Fragment,null,r):s.createElement(s.Fragment,null,l||null),K=({data:e,transform:n,render:t,fallback:r})=>{const l=g(()=>n.reduce((o,a)=>a(o),e),[e,n]);return l==null?s.createElement(s.Fragment,null,r||null):s.createElement(s.Fragment,null,t(l))},Q=e=>{const{children:n,h:t,w:r,size:l,height:o,width:a,className:u}=e;return s.createElement("div",{style:{width:l||r||a,height:l||t||o,flexShrink:0},className:u},n)},X=({let:e,props:n,children:t,fallback:r})=>{const l=g(()=>typeof e=="function"?e(n):e,[e,n]);return!t||!Object.keys(l).length?s.createElement(s.Fragment,null,r||null):s.createElement(s.Fragment,null,t(l))};function F(...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(r=>n.add(r));else if(typeof t=="object")for(const[r,l]of Object.entries(t))l&&n.add(r)}return Array.from(n).join(" ")}const ee=e=>typeof e=="object"&&!!e,C=({className:e,children:n,asWrapper:t=!1})=>{if(!n)return null;if(!e)return s.createElement(S,null,n);const r=typeof e=="string"?e:F(...Object.values(e));if(t)return s.createElement(t===!0?"div":t,{className:r},n);if(L.count(n)>1)return console.error("<Styles>: children has more than one child. Please check your code."),s.createElement(S,null,n);if(H(n)){const l=n;let o=l?.props?.className;return l?.type?.displayName===C.displayName&&ee(o)&&(o=F(...Object.values(o))),V(n,{className:F(r,o)})}return console.error("<Styles>: children is not a valid React element. Please check your code."),s.createElement(S,null,n)};C.displayName="W/Styles";const te=e=>{const{index:n=0,options:t,next:r,render:l}=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,a]=O(n),u=()=>{a(d=>t.length?r?r(d,t):(d+1)%t.length:d)};return l(t[o],u)},ne=({onIntersect:e,threshold:n=.1,root:t=null,rootMargin:r="0px",triggerOnce:l=!1,disabled:o=!1,children:a,className:u,style:d})=>{const i=k(null),c=k(null),f=k(!1);return w(()=>{if(o||!i.current)return;if(!window.IntersectionObserver){console.warn("IntersectionObserver is not supported in this browser");return}const m=i.current,h=I=>{I.forEach(D=>{l&&f.current||(e(D,c.current),l&&(f.current=!0,c.current?.unobserve(m)))})};return c.current=new IntersectionObserver(h,{root:t,rootMargin:r,threshold:n}),c.current.observe(m),()=>{c.current&&c.current.disconnect()}},[e,n,t,r,l,o]),w(()=>{l||(f.current=!1)},[l]),s.createElement("div",{ref:i,className:u,style:d},a)};function re(e){const{items:n,renderItem:t,filter:r,renderEmpty:l,sort:o}=e;if(!n)return console.error("ArrayRender: items is null"),null;if(n.length===0)return l?l():null;if(o){let a=[...n];return r&&(a=a.filter(r)),a=a.sort(o),a.length===0?l?l():null:s.createElement(S,null,a.map((u,d)=>t(u,d)))}return s.createElement(S,null,n.map((a,u)=>r&&!r(a)?null:t(a,u)))}function le({source:e,format:n,children:t}){const r=g(()=>{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]),l=g(()=>r?n?n(r):r.toLocaleString():null,[r,n]);return!l||!t?null:s.createElement(s.Fragment,null,t(l))}const oe="onChange",ae="value";function se(e){const{defaultValue:n,onBeforeChange:t,trigger:r=oe,valuePropName:l=ae,props:o}=e,a=Object.prototype.hasOwnProperty.call(o,l),[u,d]=O(n),i=a?o[l]:u,c=g(()=>o[r],[o,r]),f=Z(m=>{const h=typeof m=="function"?m(i):m;t&&t(h,i)===!1||(a||d(h),c&&c(h))},[a,t,i,c]);return[i,f]}function ie(e,...n){try{const t=e(...n);return t instanceof Promise?t:Promise.resolve(t)}catch(t){return Promise.reject(t)}}const j=typeof Promise.try=="function"?Promise.try.bind(Promise):ie;function J(e,n={}){let t=typeof e=="function"?e():e;const r=[],{sideEffect:l,transform:o}=n,a=()=>{const i=t;return o?.get?o.get(i):i},u=i=>{const c=t,f=o?.get?o.get(c):c;t=o?.set?o.set(typeof i=="function"?i(f):i):typeof i=="function"?i(f):i,r.forEach(m=>m(t)),l&&j(l,t,c).catch(m=>{console.error("Error in external state side effect, Please do it within side effects:",m)})},d=()=>{const[i,c]=s.useState(t);return s.useEffect(()=>(r.push(c),()=>{const f=r.indexOf(c);f>-1&&r.splice(f,1)}),[]),[o?.get?o.get(i):i,u]};return{get:a,set:u,use:d,useGetter:()=>{const[i]=d();return i},__listeners:r}}function ce(e,n,t){const{storageType:r="local",sideEffect:l,transform:o}=t??{},a=r==="local"?localStorage:sessionStorage;let u=n;const d=a.getItem(e);if(d)try{u=JSON.parse(d)}catch(i){console.warn(`Failed to parse ${r}Storage value for key "${e}", using initial state:`,i),u=n}return J(u,{sideEffect:i=>{a.setItem(e,JSON.stringify(i)),l?.(i)},transform:o})}function ue(e,n){const t=n||new Date,r=t.getFullYear(),l=t.getMonth()+1,o=t.getDate(),a=t.getHours(),u=t.getMinutes(),d=t.getSeconds(),i=t.getMilliseconds(),c=t.getDay(),f=["Sun","Mon","Tue","Wed","Thu","Fri","Sat"],m=["Sunday","Monday","Tuesday","Wednesday","Thursday","Friday","Saturday"],h=["Jan","Feb","Mar","Apr","May","Jun","Jul","Aug","Sep","Oct","Nov","Dec"],I=["January","February","March","April","May","June","July","August","September","October","November","December"],D=m[c],A=f[c],P=l-1,B=I[P],R=h[P],_={YY:r.toString().slice(2),YYYY:r.toString(),M:l.toString(),MM:l.toString().padStart(2,"0"),MMM:R,MMMM:B,D:o.toString(),DD:o.toString().padStart(2,"0"),d:c.toString(),dd:A,ddd:A,dddd:D,H:a.toString(),HH:a.toString().padStart(2,"0"),h:(a%12).toString(),hh:(a%12).toString().padStart(2,"0"),m:u.toString(),mm:u.toString().padStart(2,"0"),s:d.toString(),ss:d.toString().padStart(2,"0"),SSS:i.toString().padStart(3,"0"),Z:"+08:00",ZZ:"+0800",A:a<12?"AM":"PM",a:a<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,$=>_[$])}class de{count=0;next(){return this.count++}}const E=["base","xs","sm","md","lg","xl","2xl","3xl"],W={xs:475,sm:640,md:768,lg:1024,xl:1280,"2xl":1536,"3xl":1920},fe=[...E].reverse();function T(e,n){for(const t of fe){const r=e[t];if(r!==void 0&&!Number.isNaN(r)&&n>=r)return t}return"base"}function me(e=W){const[n,t]=O(T(e,window.innerWidth));return w(()=>{let r=[],l=[];const o=()=>{l.forEach(c=>c()),r=[],l=[];const a=T(e,window.innerWidth);t(a);const u=E.indexOf(a),d=E[u+1];if(d&&e[d]!==void 0){const c=e[d];if(Number.isNaN(c))throw new Error(`Invalid breakpoint value for ${d}: ${e[d]}`);{const f=window.matchMedia(`(min-width: ${c}px)`);r.push(f);const m=()=>o();f.addEventListener("change",m),l.push(()=>f.removeEventListener("change",m))}}const i=E[u-1];if(i&&e[i]!==void 0){const c=e[i];if(Number.isNaN(c))throw new Error(`Invalid breakpoint value for ${i}: ${e[i]}`);{const f=window.matchMedia(`(max-width: ${c-1}px)`);r.push(f);const m=()=>o();f.addEventListener("change",m),l.push(()=>f.removeEventListener("change",m))}}};return o(),()=>{l.forEach(a=>a())}},[e]),n}export{re as ArrayRender,de as Counter,le as DateRender,W as DefBreakpointDesc,G as False,p as If,ne as Observer,K as Pipe,X as Scope,Q as SizeBox,C as Styles,y as Switch,te as Toggle,U as True,q as When,E as breakpoints,Y as childrenLoop,J as createExternalState,ce as createStorageState,F as cx,ue as formatDate,T as getCurrentBreakpoint,j as safePromiseTry,se as useControlled,me as useScreen};
+import u,{useMemo as S,Fragment as F,Children as Z,isValidElement as q,cloneElement as U,useEffect as b,useState as I,useRef as O,useCallback as G}from"react";function R(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 K=(e,n)=>e===n,N=e=>u.createElement(u.Fragment,null,e.children);N.displayName="Switch_Case";const D=e=>u.createElement(u.Fragment,null,e.children);D.displayName="Switch_Default";const w=e=>{const{value:n,compare:t=K,children:l,strict:r=!1}=e,o=new Set;let a=null,i=null,f=!1;return R(l,(s,c)=>{if(!u.isValidElement(s))throw new Error(`Switch Children only accepts valid React elements at index ${c}`);const d=s.type;if(d.displayName===N.displayName){const m=s.props;if(o.has(m.value))throw new Error(`Switch found duplicate Case value at index ${c}: ${JSON.stringify(m.value)}${r?" (detected in strict mode)":""}`);if(o.add(m.value),!a&&t(n,m.value)&&(a=m.children,r===!1))return!1}else if(d.displayName===D.displayName){if(f)throw new Error(`Switch can only have one Default child at index ${c}`);if(f=!0,i=s.props.children,!r&&a)return!1}else throw new Error(`Switch Children only accepts 'Case' or 'Default' elements, found: ${String(d.displayName||d.name||d)} at index ${c}`)}),u.createElement(u.Fragment,null,a??i)};w.displayName="Switch",w.Case=N,w.Default=D,w.createTyped=function(){return{Switch:w,Case:N,Default:D}};const A=e=>u.createElement(u.Fragment,null,e.children),x=({children:e})=>u.createElement(u.Fragment,null,e),M=e=>u.createElement(u.Fragment,null,e.children);A.displayName="If_Then",x.displayName="If_Else",M.displayName="If_ElseIf";const E=({condition:e,children:n})=>{let t=null,l=null;const r=[];if(u.Children.forEach(n,o=>{if(!u.isValidElement(o))throw new Error("If component only accepts valid React elements");const a=o.type;if(a.displayName===A.displayName){if(t)throw new Error("If component can only have one Then child");t=o}else if(a.displayName===M.displayName)r.push(o);else if(a.displayName===x.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(a.displayName||a.name||a)}`)}),e)return t?u.createElement(u.Fragment,null,t.props.children):null;for(const o of r)if(o.props.condition)return u.createElement(u.Fragment,null,o.props.children);return l?u.createElement(u.Fragment,null,l.props.children):null};E.displayName="If",E.Then=A,E.ElseIf=M,E.Else=x,E.createTyped=function(){return{If:E,Then:A,ElseIf:M,Else:x}};const Q=({condition:e,children:n})=>e?u.createElement(u.Fragment,null,n):null,X=({condition:e,children:n})=>e===!1?u.createElement(u.Fragment,null,n):null,ee=({all:e,any:n,none:t,children:l,fallback:r})=>S(()=>(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])?u.createElement(u.Fragment,null,l):u.createElement(u.Fragment,null,r||null),te=({data:e,transform:n,render:t,fallback:l})=>{const r=S(()=>n.reduce((o,a)=>a(o),e),[e,n]);return r==null?u.createElement(u.Fragment,null,l||null):u.createElement(u.Fragment,null,t(r))},ne=e=>{const{children:n,h:t,w:l,size:r,height:o,width:a,className:i}=e;return u.createElement("div",{style:{width:r||l||a,height:r||t||o,flexShrink:0},className:i},n)},re=({let:e,props:n,children:t,fallback:l})=>{const r=S(()=>typeof e=="function"?e(n):e,[e,n]);return!t||!Object.keys(r).length?u.createElement(u.Fragment,null,l||null):u.createElement(u.Fragment,null,t(r))};function C(...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,r]of Object.entries(t))r&&n.add(l)}return Array.from(n).join(" ")}const le=e=>typeof e=="object"&&!!e,T=({className:e,children:n,asWrapper:t=!1})=>{if(!n)return null;if(!e)return u.createElement(F,null,n);const l=typeof e=="string"?e:C(...Object.values(e));if(t)return u.createElement(t===!0?"div":t,{className:l},n);if(Z.count(n)>1)return console.error("<Styles>: children has more than one child. Please check your code."),u.createElement(F,null,n);if(q(n)){const r=n;let o=r?.props?.className;return r?.type?.displayName===T.displayName&&le(o)&&(o=C(...Object.values(o))),U(n,{className:C(l,o)})}return console.error("<Styles>: children is not a valid React element. Please check your code."),u.createElement(F,null,n)};T.displayName="W/Styles";const oe=e=>{const{index:n=0,options:t,next:l,render:r}=e;b(()=>{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,a]=I(n),i=()=>{a(f=>t.length?l?l(f,t):(f+1)%t.length:f)};return r(t[o],i)},ae=({onIntersect:e,threshold:n=.1,root:t=null,rootMargin:l="0px",triggerOnce:r=!1,disabled:o=!1,children:a,className:i,style:f})=>{const s=O(null),c=O(null),d=O(!1);return b(()=>{if(o||!s.current)return;if(!window.IntersectionObserver){console.warn("IntersectionObserver is not supported in this browser");return}const m=s.current,g=y=>{y.forEach($=>{r&&d.current||(e($,c.current),r&&(d.current=!0,c.current?.unobserve(m)))})};return c.current=new IntersectionObserver(g,{root:t,rootMargin:l,threshold:n}),c.current.observe(m),()=>{c.current&&c.current.disconnect()}},[e,n,t,l,r,o]),b(()=>{r||(d.current=!1)},[r]),u.createElement("div",{ref:s,className:i,style:f},a)};function se(e){const{items:n,renderItem:t,filter:l,renderEmpty:r,sort:o}=e;if(!n)return console.error("ArrayRender: items is null"),null;if(n.length===0)return r?r():null;if(o){let a=[...n];return l&&(a=a.filter(l)),a=a.sort(o),a.length===0?r?r():null:u.createElement(F,null,a.map((i,f)=>t(i,f)))}return u.createElement(F,null,n.map((a,i)=>l&&!l(a)?null:t(a,i)))}function ue({source:e,format:n,children:t}){const l=S(()=>{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]),r=S(()=>l?n?n(l):l.toLocaleString():null,[l,n]);return!r||!t?null:u.createElement(u.Fragment,null,t(r))}const ie="onChange",ce="value";function fe(e){const{defaultValue:n,onBeforeChange:t,trigger:l=ie,valuePropName:r=ce,props:o}=e,a=Object.prototype.hasOwnProperty.call(o,r),[i,f]=I(n),s=a?o[r]:i,c=S(()=>o[l],[o,l]),d=G(m=>{const g=typeof m=="function"?m(s):m;t&&t(g,s)===!1||(a||f(g),c&&c(g))},[a,t,s,c]);return[s,d]}function de(e,...n){try{const t=e(...n);return t instanceof Promise?t:Promise.resolve(t)}catch(t){return Promise.reject(t)}}const J=typeof Promise.try=="function"?Promise.try.bind(Promise):de;function W(e,n={}){let t=typeof e=="function"?e():e;const l=[],{sideEffect:r,transform:o}=n,a=()=>{const s=t;return o?.get?o.get(s):s},i=s=>{const c=t,d=o?.get?o.get(c):c;t=o?.set?o.set(typeof s=="function"?s(d):s):typeof s=="function"?s(d):s,l.forEach(m=>m(t)),r&&J(r,t,c).catch(m=>{console.error("Error in external state side effect, Please do it within side effects:",m)})},f=()=>{const[s,c]=u.useState(t);return u.useEffect(()=>(l.push(c),()=>{const d=l.indexOf(c);d>-1&&l.splice(d,1)}),[]),[o?.get?o.get(s):s,i]};return{get:a,set:i,use:f,useGetter:()=>{const[s]=f();return s},__listeners:l}}function me(e,n,t){const{storageType:l="local",sideEffect:r,transform:o}=t??{},a=l==="local"?localStorage:sessionStorage;let i=n;const f=a.getItem(e);if(f)try{i=JSON.parse(f)}catch(s){console.warn(`Failed to parse ${l}Storage value for key "${e}", using initial state:`,s),i=n}return W(i,{sideEffect:s=>{a.setItem(e,JSON.stringify(s)),r?.(s)},transform:o})}function he(e,n){const t=n||new Date,l=t.getFullYear(),r=t.getMonth()+1,o=t.getDate(),a=t.getHours(),i=t.getMinutes(),f=t.getSeconds(),s=t.getMilliseconds(),c=t.getDay(),d=["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"],y=["January","February","March","April","May","June","July","August","September","October","November","December"],$=m[c],Y=d[c],j=r-1,_=y[j],H=g[j],z={YY:l.toString().slice(2),YYYY:l.toString(),M:r.toString(),MM:r.toString().padStart(2,"0"),MMM:H,MMMM:_,D:o.toString(),DD:o.toString().padStart(2,"0"),d:c.toString(),dd:Y,ddd:Y,dddd:$,H:a.toString(),HH:a.toString().padStart(2,"0"),h:(a%12).toString(),hh:(a%12).toString().padStart(2,"0"),m:i.toString(),mm:i.toString().padStart(2,"0"),s:f.toString(),ss:f.toString().padStart(2,"0"),SSS:s.toString().padStart(3,"0"),Z:"+08:00",ZZ:"+0800",A:a<12?"AM":"PM",a:a<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,V=>z[V])}class pe{count=0;next(){return this.count++}}const v=["base","xs","sm","md","lg","xl","2xl","3xl"],L={xs:475,sm:640,md:768,lg:1024,xl:1280,"2xl":1536,"3xl":1920};function h(e,n,t){t&&(e[n]||(e[n]=[]),e[n].push(t))}function ge(e){return e==null?!1:typeof e=="string"?e.trim().length>0:Array.isArray(e)?e.length>0:!0}function ye(e){return e!=null}function p(e,n){return`${String(e)} ${n}`}const k={email:/^[^\s@]+@[^\s@]+\.[^\s@]+$/,url:/^(https?:\/\/)?([\w.-]+)\.([a-z]{2,6})([/\w .-]*)*\/?$/,phone:/^1[3-9]\d{9}$/};function B(e,n,t,l,r){const o=ge(n),a=ye(n);if(t.required&&!o){h(r,e,t.message??p(e,"\u4E3A\u5FC5\u586B\u9879"));return}if(!(!a&&!t.required)){if(t.dependsOn){const i=t.dependsOn(l);i===!1?h(r,e,t.message??p(e,"\u4F9D\u8D56\u6761\u4EF6\u672A\u6EE1\u8DB3")):typeof i=="string"&&h(r,e,i)}if(typeof n=="string"){const i=t,{len:f,min:s,max:c,regex:d,email:m,url:g,phone:y}=i;typeof f=="number"&&n.length!==f&&h(r,e,t.message??p(e,`\u957F\u5EA6\u5FC5\u987B\u4E3A ${f}`)),typeof s=="number"&&n.length<s&&h(r,e,t.message??p(e,`\u957F\u5EA6\u4E0D\u80FD\u5C11\u4E8E ${s}`)),typeof c=="number"&&n.length>c&&h(r,e,t.message??p(e,`\u957F\u5EA6\u4E0D\u80FD\u8D85\u8FC7 ${c}`)),d&&!d.test(n)&&h(r,e,t.message??p(e,"\u683C\u5F0F\u4E0D\u6B63\u786E")),m&&!k.email.test(n)&&h(r,e,t.message??p(e,"\u4E0D\u662F\u6709\u6548\u7684\u90AE\u7BB1")),g&&!k.url.test(n)&&h(r,e,t.message??p(e,"\u4E0D\u662F\u6709\u6548\u7684URL")),y&&!k.phone.test(n)&&h(r,e,t.message??p(e,"\u4E0D\u662F\u6709\u6548\u7684\u624B\u673A\u53F7"))}if(typeof n=="number"){const i=t,{min:f,max:s}=i;typeof f=="number"&&n<f&&h(r,e,t.message??p(e,`\u4E0D\u80FD\u5C0F\u4E8E ${f}`)),typeof s=="number"&&n>s&&h(r,e,t.message??p(e,`\u4E0D\u80FD\u5927\u4E8E ${s}`))}if(Array.isArray(n)){const i=t,{len:f,min:s,max:c,unique:d,elementRule:m}=i;typeof f=="number"&&n.length!==f&&h(r,e,t.message??p(e,`\u957F\u5EA6\u5FC5\u987B\u4E3A ${f}`)),typeof s=="number"&&n.length<s&&h(r,e,t.message??p(e,`\u957F\u5EA6\u4E0D\u80FD\u5C0F\u4E8E ${s}`)),typeof c=="number"&&n.length>c&&h(r,e,t.message??p(e,`\u957F\u5EA6\u4E0D\u80FD\u5927\u4E8E ${c}`)),d&&new Set(n).size!==n.length&&h(r,e,t.message??p(e,"\u5143\u7D20\u5FC5\u987B\u552F\u4E00")),m&&n.forEach((g,y)=>{B(`${String(e)}[${y}]`,g,m,l,r)})}if(t.validator){const i=t.validator?.(n,l);i===!1?h(r,e,t.message??p(e,"\u6821\u9A8C\u672A\u901A\u8FC7")):typeof i=="string"&&h(r,e,i)}}}function Ee(e,n){const t={};for(const r in n){const o=r,a=n[o];if(!a)continue;const i=e[o];if(Array.isArray(a))for(const f of a)B(o,i,f,e,t);else B(o,i,a,e,t)}const l=Object.values(t).reduce((r,o)=>(o&&r.push(...o),r),[]);return l.length>0?{valid:!1,errors:l,fieldErrors:t}:{valid:!0,data:e}}const Se=[...v].reverse();function P(e,n){for(const t of Se){const l=e[t];if(l!==void 0&&!Number.isNaN(l)&&n>=l)return t}return"base"}function we(e=L){const[n,t]=I(P(e,window.innerWidth));return b(()=>{let l=[],r=[];const o=()=>{r.forEach(c=>c()),l=[],r=[];const a=P(e,window.innerWidth);t(a);const i=v.indexOf(a),f=v[i+1];if(f&&e[f]!==void 0){const c=e[f];if(Number.isNaN(c))throw new Error(`Invalid breakpoint value for ${f}: ${e[f]}`);{const d=window.matchMedia(`(min-width: ${c}px)`);l.push(d);const m=()=>o();d.addEventListener("change",m),r.push(()=>d.removeEventListener("change",m))}}const s=v[i-1];if(s&&e[s]!==void 0){const c=e[s];if(Number.isNaN(c))throw new Error(`Invalid breakpoint value for ${s}: ${e[s]}`);{const d=window.matchMedia(`(max-width: ${c-1}px)`);l.push(d);const m=()=>o();d.addEventListener("change",m),r.push(()=>d.removeEventListener("change",m))}}};return o(),()=>{r.forEach(a=>a())}},[e]),n}export{se as ArrayRender,pe as Counter,ue as DateRender,L as DefBreakpointDesc,X as False,E as If,ae as Observer,te as Pipe,re as Scope,ne as SizeBox,T as Styles,w as Switch,oe as Toggle,Q as True,ee as When,v as breakpoints,R as childrenLoop,W as createExternalState,me as createStorageState,C as cx,he as formatDate,P as getCurrentBreakpoint,Ee as ruleChecker,J as safePromiseTry,fe as useControlled,we as useScreen};

package/package.json

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

package/src/utils/index.ts

@@ -3,4 +3,5 @@ export * from "./cx";
 export * from "./reactUtils";
 export * from "./sundry";
 export * from "./promise";
-export * from "./constants";
+export * from "./constants";
+export * from "./ruleChecker";

package/src/utils/ruleChecker.test.ts

@@ -0,0 +1,662 @@
+import { describe, expect, it } from 'vitest';
+import { ruleChecker } from './ruleChecker';
+import type { RuleDescription } from './ruleChecker';
+
+describe('ruleChecker', () => {
+  // ==== 基础功能测试 ====
+  describe('基础功能', () => {
+    it('应该通过空规则验证', () => {
+      const result = ruleChecker({}, {});
+      expect(result.valid).toBe(true);
+      if (result.valid) {
+        expect(result.data).toEqual({});
+      }
+    });
+
+    it('应该验证 required 规则 - 成功', () => {
+      const data = { name: 'John' };
+      const rules: RuleDescription<typeof data> = {
+        name: { required: true },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(true);
+      if (result.valid) {
+        expect(result.data.name).toBe('John');
+      }
+    });
+
+    it('应该验证 required 规则 - 失败', () => {
+      const data = { name: '' };
+      const rules: RuleDescription<typeof data> = {
+        name: { required: true },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.errors).toContain('name 为必填项');
+        expect(result.fieldErrors.name).toContain('name 为必填项');
+      }
+    });
+
+    it('应该使用自定义错误消息', () => {
+      const data = { email: '' };
+      const rules: RuleDescription<typeof data> = {
+        email: { required: true, message: '邮箱不能为空' },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.errors).toContain('邮箱不能为空');
+      }
+    });
+
+    it('应该处理 null 和 undefined 值', () => {
+      type DataType = { name: string | null; age?: number };
+      const data: Partial<DataType> = { name: null, age: undefined };
+      const rules: RuleDescription<DataType> = {
+        name: { required: true },
+        age: { required: false },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.fieldErrors.name).toContain('name 为必填项');
+        expect(result.fieldErrors.age).toBeUndefined();
+      }
+    });
+
+    it('应该验证自定义 validator - 返回 boolean', () => {
+      const data = { password: '123' };
+      const rules: RuleDescription<typeof data> = {
+        password: {
+          validator: (value) => value.length >= 6,
+          message: '密码至少6位',
+        },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.errors).toContain('密码至少6位');
+      }
+    });
+
+    it('应该验证自定义 validator - 返回 string', () => {
+      const data = { username: 'admin' };
+      const rules: RuleDescription<typeof data> = {
+        username: {
+          validator: (value) =>
+            value === 'admin' ? '用户名不能是admin' : true,
+        },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.errors).toContain('用户名不能是admin');
+      }
+    });
+  });
+
+  // ==== 字符串规则测试 ====
+  describe('字符串规则', () => {
+    it('应该验证字符串长度 len', () => {
+      const data = { code: '123' };
+      const rules: RuleDescription<typeof data> = {
+        code: { len: 4 },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.errors).toContain('code 长度必须为 4');
+      }
+    });
+
+    it('应该验证字符串最小长度 min', () => {
+      const data = { username: 'ab' };
+      const rules: RuleDescription<typeof data> = {
+        username: { min: 3 },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.errors).toContain('username 长度不能少于 3');
+      }
+    });
+
+    it('应该验证字符串最大长度 max', () => {
+      const data = { comment: 'a'.repeat(101) };
+      const rules: RuleDescription<typeof data> = {
+        comment: { max: 100 },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.errors).toContain('comment 长度不能超过 100');
+      }
+    });
+
+    it('应该验证正则表达式', () => {
+      const data = { phone: '123456' };
+      const rules: RuleDescription<typeof data> = {
+        phone: { regex: /^\d{11}$/ },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.errors).toContain('phone 格式不正确');
+      }
+    });
+
+    it('应该验证邮箱格式', () => {
+      const data = { email: 'invalid-email' };
+      const rules: RuleDescription<typeof data> = {
+        email: { email: true },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.errors).toContain('email 不是有效的邮箱');
+      }
+    });
+
+    it('应该通过有效的邮箱验证', () => {
+      const data = { email: 'test@example.com' };
+      const rules: RuleDescription<typeof data> = {
+        email: { email: true },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(true);
+    });
+
+    it('应该验证URL格式', () => {
+      const data = { website: 'invalid-url' };
+      const rules: RuleDescription<typeof data> = {
+        website: { url: true },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.errors).toContain('website 不是有效的URL');
+      }
+    });
+
+    it('应该通过有效的URL验证', () => {
+      const data = { website: 'https://example.com' };
+      const rules: RuleDescription<typeof data> = {
+        website: { url: true },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(true);
+    });
+
+    it('应该验证手机号格式', () => {
+      const data = { mobile: '123456789' };
+      const rules: RuleDescription<typeof data> = {
+        mobile: { phone: true },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.errors).toContain('mobile 不是有效的手机号');
+      }
+    });
+
+    it('应该通过有效的手机号验证', () => {
+      const data = { mobile: '13812345678' };
+      const rules: RuleDescription<typeof data> = {
+        mobile: { phone: true },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(true);
+    });
+  });
+
+  // ==== 数字规则测试 ====
+  describe('数字规则', () => {
+    it('应该验证数字最小值', () => {
+      const data = { age: 5 };
+      const rules: RuleDescription<typeof data> = {
+        age: { min: 18 },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.errors).toContain('age 不能小于 18');
+      }
+    });
+
+    it('应该验证数字最大值', () => {
+      const data = { score: 105 };
+      const rules: RuleDescription<typeof data> = {
+        score: { max: 100 },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.errors).toContain('score 不能大于 100');
+      }
+    });
+
+    it('应该通过数字范围验证', () => {
+      const data = { percentage: 85 };
+      const rules: RuleDescription<typeof data> = {
+        percentage: { min: 0, max: 100 },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(true);
+    });
+  });
+
+  // ==== 数组规则测试 ====
+  describe('数组规则', () => {
+    it('应该验证数组长度 len', () => {
+      const data = { items: [1, 2, 3] };
+      const rules: RuleDescription<typeof data> = {
+        items: { len: 5 },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.errors).toContain('items 长度必须为 5');
+      }
+    });
+
+    it('应该验证数组最小长度', () => {
+      const data = { tags: ['one'] };
+      const rules: RuleDescription<typeof data> = {
+        tags: { min: 2 },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.errors).toContain('tags 长度不能小于 2');
+      }
+    });
+
+    it('应该验证数组最大长度', () => {
+      const data = { categories: [1, 2, 3, 4, 5, 6] };
+      const rules: RuleDescription<typeof data> = {
+        categories: { max: 5 },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.errors).toContain('categories 长度不能大于 5');
+      }
+    });
+
+    it('应该验证数组元素唯一性', () => {
+      const data = { ids: [1, 2, 2, 3] };
+      const rules: RuleDescription<typeof data> = {
+        ids: { unique: true },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.errors).toContain('ids 元素必须唯一');
+      }
+    });
+
+    it('应该通过数组元素唯一性验证', () => {
+      const data = { ids: [1, 2, 3, 4] };
+      const rules: RuleDescription<typeof data> = {
+        ids: { unique: true },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(true);
+    });
+
+    it('应该验证数组元素规则', () => {
+      const data = { emails: ['valid@email.com', 'invalid-email'] };
+      const rules: RuleDescription<typeof data> = {
+        emails: {
+          elementRule: { email: true },
+        },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        // 检查错误信息包含了数组元素索引的错误
+        expect(result.errors.some((error) => error.includes('emails[1]'))).toBe(
+          true
+        );
+      }
+    });
+  });
+
+  // ==== 依赖验证测试 ====
+  describe('依赖验证', () => {
+    it('应该验证 dependsOn - 返回 boolean', () => {
+      const data = { type: 'premium', discount: 0.9 };
+      const rules: RuleDescription<typeof data> = {
+        discount: {
+          dependsOn: (data) => data.type === 'basic', // 当类型不是basic时会失败
+          message: '只有基础用户才能设置折扣',
+        },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.errors).toContain('只有基础用户才能设置折扣');
+      }
+    });
+
+    it('应该验证 dependsOn - 返回 string', () => {
+      const data = { age: 16, hasLicense: true };
+      const rules: RuleDescription<typeof data> = {
+        hasLicense: {
+          dependsOn: (data) =>
+            (data.age || 0) < 18 ? '未成年人不能有驾驶证' : true,
+        },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.errors).toContain('未成年人不能有驾驶证');
+      }
+    });
+
+    it('应该通过 dependsOn 验证', () => {
+      const data = { type: 'basic', discount: undefined };
+      const rules: RuleDescription<typeof data> = {
+        discount: {
+          dependsOn: (data) => data.type === 'premium',
+        },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(true);
+    });
+  });
+
+  // ==== 复杂场景测试 ====
+  describe('复杂场景', () => {
+    it('应该处理多个规则数组', () => {
+      const data = { password: '123' };
+      const rules: RuleDescription<typeof data> = {
+        password: [
+          { required: true },
+          { min: 6, message: '密码至少6位' },
+          { regex: /[A-Z]/, message: '密码必须包含大写字母' },
+        ],
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.errors).toContain('密码至少6位');
+        expect(result.errors).toContain('密码必须包含大写字母');
+      }
+    });
+
+    it('应该收集多个字段的错误', () => {
+      const data = { name: '', email: 'invalid', age: 5 };
+      const rules: RuleDescription<typeof data> = {
+        name: { required: true },
+        email: { email: true },
+        age: { min: 18 },
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.errors).toHaveLength(3);
+        expect(result.fieldErrors.name).toContain('name 为必填项');
+        expect(result.fieldErrors.email).toContain('email 不是有效的邮箱');
+        expect(result.fieldErrors.age).toContain('age 不能小于 18');
+      }
+    });
+
+    it('应该处理复杂的用户注册场景', () => {
+      const data = {
+        username: 'ab',
+        email: 'test@example.com',
+        password: '123',
+        confirmPassword: '456',
+        age: 25,
+        hobbies: ['reading'],
+        terms: false,
+      };
+
+      const rules: RuleDescription<typeof data> = {
+        username: { required: true, min: 3, max: 20 },
+        email: { required: true, email: true },
+        password: [
+          { required: true },
+          { min: 6 },
+          { regex: /[A-Z]/, message: '密码必须包含大写字母' },
+        ],
+        confirmPassword: {
+          required: true,
+          validator: (value, data) =>
+            value === data.password || '两次密码不一致',
+        },
+        age: { required: true, min: 18, max: 120 },
+        hobbies: { min: 2, max: 5 },
+        terms: {
+          required: true,
+          validator: (value) => value === true || '必须同意用户协议',
+        },
+      };
+
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.fieldErrors.username).toContain(
+          'username 长度不能少于 3'
+        );
+        expect(result.fieldErrors.password).toContain(
+          'password 长度不能少于 6'
+        );
+        expect(result.fieldErrors.confirmPassword).toContain('两次密码不一致');
+        expect(result.fieldErrors.hobbies).toContain('hobbies 长度不能小于 2');
+        expect(result.fieldErrors.terms).toContain('必须同意用户协议');
+      }
+    });
+
+    it('应该在所有验证通过时返回正确的数据', () => {
+      const data = {
+        name: 'John Doe',
+        email: 'john@example.com',
+        age: 30,
+      };
+
+      const rules: RuleDescription<typeof data> = {
+        name: { required: true, min: 2 },
+        email: { required: true, email: true },
+        age: { required: true, min: 18, max: 120 },
+      };
+
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(true);
+      if (result.valid) {
+        expect(result.data).toEqual(data);
+      }
+    });
+  });
+
+  // ==== 类型安全测试 ====
+  describe('类型安全验证', () => {
+    it('数字字段应该只支持数字相关规则', () => {
+      const data = { age: 25 };
+
+      // 这些应该是有效的数字规则
+      const validRules: RuleDescription<typeof data> = {
+        age: { min: 0, max: 120, required: true },
+      };
+
+      const result = ruleChecker(data, validRules);
+      expect(result.valid).toBe(true);
+
+      // 注意：TypeScript 会阻止以下无效的数字规则
+      // age: { email: true }, // ❌ 编译错误
+      // age: { regex: /test/ }, // ❌ 编译错误
+      // age: { len: 10 }, // ❌ 编译错误
+    });
+
+    it('字符串字段应该支持长度和格式规则', () => {
+      const data = { email: 'test@example.com', name: 'John' };
+
+      const rules: RuleDescription<typeof data> = {
+        email: {
+          required: true,
+          email: true,
+          min: 5,
+          max: 100,
+        },
+        name: {
+          required: true,
+          min: 2,
+          max: 50,
+          regex: /^[a-zA-Z]+$/,
+        },
+      };
+
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(true);
+    });
+
+    it('数组字段应该支持长度和唯一性规则', () => {
+      const data = { tags: ['react', 'typescript'], ids: [1, 2, 3] };
+
+      const rules: RuleDescription<typeof data> = {
+        tags: {
+          min: 1,
+          max: 5,
+          unique: true,
+          elementRule: { min: 2, max: 20 }, // 元素是字符串
+        },
+        ids: {
+          len: 3,
+          unique: true,
+          elementRule: { min: 1, max: 1000 }, // 元素是数字
+        },
+      };
+
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(true);
+    });
+
+    it('布尔字段应该只支持基础规则', () => {
+      const data = { isActive: false, hasPermission: false };
+
+      const rules: RuleDescription<typeof data> = {
+        isActive: {
+          required: true,
+          validator: (value) => value === true || '必须激活账户',
+        },
+        hasPermission: {
+          required: true,
+        },
+      };
+
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.errors).toContain('必须激活账户');
+      }
+    });
+
+    it('应该正确处理混合类型的复杂对象', () => {
+      const data = {
+        id: 123,
+        name: 'Product Name',
+        price: 99.99,
+        tags: ['electronics', 'mobile'],
+        isActive: true,
+        description: 'A great product',
+      };
+
+      const rules: RuleDescription<typeof data> = {
+        id: { required: true, min: 1 }, // 数字规则
+        name: { required: true, min: 3, max: 50 }, // 字符串长度规则
+        price: { required: true, min: 0, max: 10000 }, // 数字范围规则
+        tags: { min: 1, max: 10, unique: true }, // 数组规则
+        isActive: { required: true }, // 布尔基础规则
+        description: { min: 10, max: 500, regex: /^[a-zA-Z\s]+$/ }, // 字符串格式规则
+      };
+
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(true);
+    });
+  });
+
+  // ==== 边缘情况测试 ====
+  describe('边缘情况', () => {
+    it('应该正确处理空字符串的各种验证', () => {
+      const data = { text: '' };
+      const rules: RuleDescription<typeof data> = {
+        text: { min: 1 }, // 空字符串长度为0，应该失败
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+    });
+
+    it('应该正确处理空数组的各种验证', () => {
+      const data = { items: [] as string[] };
+      const rules: RuleDescription<typeof data> = {
+        items: { min: 1 }, // 空数组长度为0，应该失败
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+    });
+
+    it('应该正确处理数字 0 的验证', () => {
+      const data = { count: 0 };
+      const rules: RuleDescription<typeof data> = {
+        count: { required: true, min: 0 }, // 0 是有效值，应该通过
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(true);
+    });
+
+    it('应该正确处理 false 值的验证', () => {
+      const data = { isEnabled: false };
+      const rules: RuleDescription<typeof data> = {
+        isEnabled: { required: true }, // false 是有效值，应该通过
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(true);
+    });
+
+    it('应该正确处理只有空格的字符串', () => {
+      const data = { text: '   ' };
+      const rules: RuleDescription<typeof data> = {
+        text: { required: true }, // 只有空格被视为空值，应该失败
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+    });
+
+    it('应该处理非常长的字符串', () => {
+      const longText = 'a'.repeat(1000);
+      const data = { content: longText };
+      const rules: RuleDescription<typeof data> = {
+        content: { max: 500 }, // 超过最大长度，应该失败
+      };
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.errors).toContain('content 长度不能超过 500');
+      }
+    });
+
+    it('应该处理复杂的嵌套数组元素验证', () => {
+      const data = {
+        users: [
+          { name: 'Alice', email: 'alice@test.com' },
+          { name: 'B', email: 'invalid-email' }, // 名字太短，邮箱无效
+        ],
+      };
+
+      // 注意：这个例子展示了当前系统的限制
+      // 对于复杂嵌套对象，需要扩展 elementRule 支持
+      const rules: RuleDescription<typeof data> = {
+        users: {
+          min: 1,
+          max: 10,
+          // elementRule 目前不支持对象验证
+        },
+      };
+
+      const result = ruleChecker(data, rules);
+      expect(result.valid).toBe(true); // 基本数组规则通过
+    });
+  });
+});

package/src/utils/ruleChecker.ts

@@ -0,0 +1,340 @@
+// ==== 基础规则类型 ====
+export type BaseRule<TAll, TValue> = {
+  required?: boolean;
+  message?: string;
+  validator?: (value: TValue, data: Partial<TAll>) => boolean | string;
+  dependsOn?: (data: Partial<TAll>) => boolean | string; // 支持依赖校验
+};
+
+// ==== 长度相关规则（字符串和数组共用） ====
+export type LengthRuleProps = {
+  min?: number;
+  max?: number;
+  len?: number;
+};
+
+// ==== 数字范围规则 ====
+export type NumberRangeProps = {
+  min?: number;
+  max?: number;
+};
+
+// ==== 字符串特有规则 ====
+export type StringSpecificProps = {
+  regex?: RegExp;
+  email?: boolean;
+  url?: boolean;
+  phone?: boolean;
+};
+
+// ==== 数组特有规则 ====
+export type ArraySpecificProps = {
+  unique?: boolean;
+};
+
+// ==== 各类型规则 ====
+export type NumberRule<TAll> = BaseRule<TAll, number> & NumberRangeProps;
+
+export type StringRule<TAll> = BaseRule<TAll, string> &
+  LengthRuleProps &
+  StringSpecificProps;
+
+export type BooleanRule<TAll> = BaseRule<TAll, boolean>;
+
+export type ArrayRule<TAll, U> = BaseRule<TAll, U[]> &
+  LengthRuleProps &
+  ArraySpecificProps & {
+    elementRule?: FieldRule<U, TAll>; // 元素级规则
+  };
+
+// ==== 泛型推导：字段类型 → 规则类型 ====
+export type FieldRule<TValue, TAll> = TValue extends string
+  ? StringRule<TAll>
+  : TValue extends number
+    ? NumberRule<TAll>
+    : TValue extends boolean
+      ? BooleanRule<TAll>
+      : TValue extends (infer U)[]
+        ? ArrayRule<TAll, U>
+        : BaseRule<TAll, TValue>;
+
+// ==== 描述对象 ====
+export type RuleDescription<T extends Record<string, unknown>> = {
+  [K in keyof T]?: FieldRule<T[K], T> | FieldRule<T[K], T>[];
+};
+
+// ==== Required 判断 ====
+type IsRequired<R> = R extends { required: true } ? true : false;
+
+export type ApplyRules<
+  T extends Record<string, unknown>,
+  R extends RuleDescription<T>,
+> = {
+  [K in keyof T]: IsRequired<R[K]> extends true ? T[K] : T[K] | undefined;
+};
+
+// ==== 错误收集 ====
+type FieldErrors<T> = Partial<Record<keyof T, string[]>>;
+
+function pushError<T extends Record<string, unknown>>(
+  fieldErrors: FieldErrors<T>,
+  field: keyof T,
+  msg: string
+) {
+  if (!msg) return;
+  if (!fieldErrors[field]) fieldErrors[field] = [];
+  (fieldErrors[field] as string[]).push(msg);
+}
+
+function isPresent(value: unknown): boolean {
+  if (value === null || value === undefined) return false;
+  if (typeof value === 'string') return value.trim().length > 0;
+  if (Array.isArray(value)) return value.length > 0;
+  return true;
+}
+
+function isValueProvided(value: unknown): boolean {
+  return value !== null && value !== undefined;
+}
+
+function defaultMsg(field: string | number | symbol, reason: string) {
+  return `${String(field)} ${reason}`;
+}
+
+// ==== 内置校验器 ====
+const builtins = {
+  email: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+  url: /^(https?:\/\/)?([\w.-]+)\.([a-z]{2,6})([/\w .-]*)*\/?$/,
+  phone: /^1[3-9]\d{9}$/, // 中国手机号
+};
+
+// ==== 单字段校验 ====
+function validateRule<T extends Record<string, unknown>, V>(
+  key: keyof T,
+  value: V,
+  rule: FieldRule<V, T>,
+  data: Partial<T>,
+  fieldErrors: FieldErrors<T>
+) {
+  const present = isPresent(value);
+  const valueProvided = isValueProvided(value);
+
+  // required
+  if (rule.required && !present) {
+    pushError(fieldErrors, key, rule.message ?? defaultMsg(key, '为必填项'));
+    return;
+  }
+  // 如果值没有提供且不是必填，跳过验证
+  if (!valueProvided && !rule.required) return;
+
+  // dependsOn
+  if (rule.dependsOn) {
+    const res = rule.dependsOn(data);
+    if (res === false)
+      pushError(
+        fieldErrors,
+        key,
+        rule.message ?? defaultMsg(key, '依赖条件未满足')
+      );
+    else if (typeof res === 'string') pushError(fieldErrors, key, res);
+  }
+
+  // string 相关校验
+  if (typeof value === 'string') {
+    const stringRule = rule as StringRule<T>;
+    const { len, min, max, regex, email, url, phone } = stringRule;
+
+    if (typeof len === 'number' && value.length !== len) {
+      pushError(
+        fieldErrors,
+        key,
+        rule.message ?? defaultMsg(key, `长度必须为 ${len}`)
+      );
+    }
+    if (typeof min === 'number' && value.length < min) {
+      pushError(
+        fieldErrors,
+        key,
+        rule.message ?? defaultMsg(key, `长度不能少于 ${min}`)
+      );
+    }
+    if (typeof max === 'number' && value.length > max) {
+      pushError(
+        fieldErrors,
+        key,
+        rule.message ?? defaultMsg(key, `长度不能超过 ${max}`)
+      );
+    }
+    if (regex && !regex.test(value)) {
+      pushError(
+        fieldErrors,
+        key,
+        rule.message ?? defaultMsg(key, '格式不正确')
+      );
+    }
+    if (email && !builtins.email.test(value)) {
+      pushError(
+        fieldErrors,
+        key,
+        rule.message ?? defaultMsg(key, '不是有效的邮箱')
+      );
+    }
+    if (url && !builtins.url.test(value)) {
+      pushError(
+        fieldErrors,
+        key,
+        rule.message ?? defaultMsg(key, '不是有效的URL')
+      );
+    }
+    if (phone && !builtins.phone.test(value)) {
+      pushError(
+        fieldErrors,
+        key,
+        rule.message ?? defaultMsg(key, '不是有效的手机号')
+      );
+    }
+  }
+
+  // number 相关校验
+  if (typeof value === 'number') {
+    const numberRule = rule as NumberRule<T>;
+    const { min, max } = numberRule;
+    if (typeof min === 'number' && value < min) {
+      pushError(
+        fieldErrors,
+        key,
+        rule.message ?? defaultMsg(key, `不能小于 ${min}`)
+      );
+    }
+    if (typeof max === 'number' && value > max) {
+      pushError(
+        fieldErrors,
+        key,
+        rule.message ?? defaultMsg(key, `不能大于 ${max}`)
+      );
+    }
+  }
+
+  // array 相关校验
+  if (Array.isArray(value)) {
+    const arrayRule = rule as ArrayRule<T, unknown>;
+    const { len, min, max, unique, elementRule } = arrayRule;
+
+    if (typeof len === 'number' && value.length !== len) {
+      pushError(
+        fieldErrors,
+        key,
+        rule.message ?? defaultMsg(key, `长度必须为 ${len}`)
+      );
+    }
+    if (typeof min === 'number' && value.length < min) {
+      pushError(
+        fieldErrors,
+        key,
+        rule.message ?? defaultMsg(key, `长度不能小于 ${min}`)
+      );
+    }
+    if (typeof max === 'number' && value.length > max) {
+      pushError(
+        fieldErrors,
+        key,
+        rule.message ?? defaultMsg(key, `长度不能大于 ${max}`)
+      );
+    }
+    if (unique && new Set(value).size !== value.length) {
+      pushError(
+        fieldErrors,
+        key,
+        rule.message ?? defaultMsg(key, '元素必须唯一')
+      );
+    }
+    if (elementRule) {
+      (value as unknown[]).forEach((v, i) => {
+        validateRule(
+          `${String(key)}[${i}]` as keyof T,
+          v as unknown,
+          elementRule as FieldRule<unknown, T>,
+          data,
+          fieldErrors
+        );
+      });
+    }
+  }
+
+  // 自定义 validator
+  if (rule.validator) {
+    const res = (
+      rule.validator as
+        | ((value: unknown, data: Partial<T>) => boolean | string)
+        | undefined
+    )?.(value as unknown, data);
+    if (res === false)
+      pushError(
+        fieldErrors,
+        key,
+        rule.message ?? defaultMsg(key, '校验未通过')
+      );
+    else if (typeof res === 'string') pushError(fieldErrors, key, res);
+  }
+}
+
+// ==== 主函数 ====
+export function ruleChecker<
+  T extends Record<string, unknown>,
+  R extends RuleDescription<T>,
+>(
+  data: Partial<T>,
+  rules: R
+):
+  | { valid: true; data: ApplyRules<T, R> }
+  | { valid: false; errors: string[]; fieldErrors: FieldErrors<T> } {
+  const fieldErrors: FieldErrors<T> = {};
+
+  for (const k in rules) {
+    const key = k as keyof T;
+    const ruleOrRules = rules[key] as
+      | FieldRule<T[typeof key] | undefined, T>
+      | FieldRule<T[typeof key] | undefined, T>[]
+      | undefined;
+    if (!ruleOrRules) continue;
+
+    const value = data[key] as T[typeof key] | undefined;
+
+    // 支持单个规则或规则数组
+    if (Array.isArray(ruleOrRules)) {
+      // 处理规则数组
+      for (const rule of ruleOrRules) {
+        validateRule<T, T[typeof key] | undefined>(
+          key,
+          value,
+          rule,
+          data,
+          fieldErrors
+        );
+      }
+    } else {
+      // 处理单个规则
+      validateRule<T, T[typeof key] | undefined>(
+        key,
+        value,
+        ruleOrRules,
+        data,
+        fieldErrors
+      );
+    }
+  }
+
+  // 聚合错误时，避免 [] 被推断为 never[] 导致的类型问题
+  const errors: string[] = (
+    Object.values(fieldErrors) as Array<string[] | undefined>
+  ).reduce<string[]>((acc, v) => {
+    if (v) acc.push(...v);
+    return acc;
+  }, []);
+
+  if (errors.length > 0) {
+    return { valid: false, errors, fieldErrors };
+  }
+
+  return { valid: true, data: data as ApplyRules<T, R> };
+}