@wwog/react 1.3.0 → 1.3.2

package/README.md

@@ -313,6 +313,69 @@ function Example() {
 - `format`: Optional function to format the date, defaults to `toLocaleString()`.
 - `children`: Function to render the formatted date, receives the formatted date as an argument.
 
+#### `<Observer>` (v1.3.1+)
+
+A declarative Intersection Observer component for lazy loading, infinite scrolling, and viewport-based interactions.
+
+```tsx
+import { Observer } from "@wwog/react";
+
+function LazyImage({ src, alt }) {
+  const [isVisible, setIsVisible] = useState(false);
+
+  return (
+    <Observer
+      onIntersect={(entry) => {
+        if (entry.isIntersecting) {
+          setIsVisible(true);
+        }
+      }}
+      threshold={0.1}
+      triggerOnce
+    >
+      <div className="image-container">
+        {isVisible ? (
+          <img src={src} alt={alt} />
+        ) : (
+          <div className="placeholder">Loading...</div>
+        )}
+      </div>
+    </Observer>
+  );
+}
+
+// Infinite scrolling example
+function InfiniteList({ items, onLoadMore }) {
+  return (
+    <div>
+      {items.map((item) => (
+        <div key={item.id}>{item.content}</div>
+      ))}
+      <Observer
+        onIntersect={(entry) => {
+          if (entry.isIntersecting) {
+            onLoadMore();
+          }
+        }}
+        rootMargin="100px"
+      >
+        <div>Loading more...</div>
+      </Observer>
+    </div>
+  );
+}
+```
+
+- `onIntersect`: Callback function triggered when intersection changes, receives IntersectionObserverEntry as parameter.
+- `threshold`: Intersection threshold, can be a number (0-1) or array of numbers, defaults to 0.
+- `root`: Root element for intersection observation, defaults to viewport.
+- `rootMargin`: Root margin for expanding/shrinking the root's bounding box, defaults to "0px".
+- `triggerOnce`: Whether to trigger only once, defaults to false.
+- `disabled`: Whether to disable observation, defaults to false.
+- `children`: Child elements to observe.
+- `className`: CSS class name for the wrapper element.
+- `style`: Inline styles for the wrapper element.
+
 #### `<SizeBox>`
 
 Create a fixed-size container for layout adjustment and spacing control.
@@ -400,6 +463,10 @@ You can also use a container wrapper element:
 
 > A lightweight external state management utility that allows you to create and manage state outside the React component tree while maintaining perfect integration with components.
 
+### `createStorageState` (v1.3.2+)
+
+> Extends from createExternalState and uses storage to persist state, supports `localStorage` and `sessionStorage`
+
 ```tsx
 import { createExternalState } from "@wwog/react";
 

package/dist/index.d.mts

@@ -372,6 +372,95 @@ interface ToggleProps<T = boolean> {
  */
 declare const Toggle: <T>(props: ToggleProps<T>) => React$1.ReactNode;
 
+interface ObserverProps {
+    /**
+     * @description_en Callback function when intersection occurs.
+     * @description_zh 交叉时触发的回调函数。
+     */
+    onIntersect: (entry: IntersectionObserverEntry, observer: IntersectionObserver) => void;
+    /**
+     * @description_en Threshold(s) at which to trigger the callback. Default is 0.1.
+     * @description_zh 触发回调的阈值，默认为 0.1。
+     * @optional
+     * @default 0.1
+     */
+    threshold?: number | number[];
+    /**
+     * @description_en The root element for intersection. Default is viewport.
+     * @description_zh 交叉的根元素，默认为视口。
+     * @optional
+     * @default null
+     */
+    root?: Element | Document | null;
+    /**
+     * @description_en Margin around the root. Default is "0px".
+     * @description_zh 根元素周围的边距，默认为 "0px"。
+     * @optional
+     * @default "0px"
+     */
+    rootMargin?: string;
+    /**
+     * @description_en Whether to trigger only once. Default is false.
+     * @description_zh 是否只触发一次，默认为 false。
+     * @optional
+     * @default false
+     */
+    triggerOnce?: boolean;
+    /**
+     * @description_en Whether to disable the observer. Default is false.
+     * @description_zh 是否禁用观察者，默认为 false。
+     * @optional
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * @description_en Child elements to observe.
+     * @description_zh 要观察的子元素。
+     * @optional
+     */
+    children?: ReactNode;
+    /**
+     * @description_en CSS class name.
+     * @description_zh CSS 类名。
+     * @optional
+     */
+    className?: string;
+    /**
+     * @description_en Inline styles.
+     * @description_zh 内联样式。
+     * @optional
+     */
+    style?: React$1.CSSProperties;
+}
+/**
+ * @description_zh 交叉观察者组件，用于监听元素与视口的交叉状态，常用于懒加载和无限滚动场景。
+ * @description_en Intersection Observer component for monitoring element-viewport intersection, commonly used for lazy loading and infinite scrolling.
+ * @component
+ * @example
+ * ```tsx
+ * // 懒加载示例
+ * <Observer onIntersect={loadImage} triggerOnce>
+ *   <img data-src="image.jpg" alt="Lazy loaded" />
+ * </Observer>
+ *
+ * // 无限滚动示例
+ * <Observer onIntersect={loadMore} threshold={0.1}>
+ *   <div>滚动到这里加载更多</div>
+ * </Observer>
+ *
+ * // 自定义根元素和边距
+ * <Observer
+ *   onIntersect={handleIntersect}
+ *   root={scrollContainer}
+ *   rootMargin="100px"
+ *   threshold={[0, 0.5, 1]}
+ * >
+ *   <div>观察目标</div>
+ * </Observer>
+ * ```
+ */
+declare const Observer: React$1.FC<ObserverProps>;
+
 interface ArrayRenderProps<T> {
     items: T[];
     renderItem: (item: T, index: number) => React$1.ReactNode;
@@ -565,6 +654,12 @@ interface ExternalWithKernel<T, U = T> extends ExternalState<T, U> {
  * ```
  */
 declare function createExternalState<T, U = T>(initialState: T | (() => T), options?: ExternalStateOptions<T, U>): ExternalState<T, U>;
+interface StorageStateOptions<T, U> {
+    sideEffect?: (newState: T) => void;
+    transform?: Transform<T, U>;
+    storageType: "local" | "session";
+}
+declare function createStorageState<T, U = T>(key: string, initialState: T, options?: StorageStateOptions<T, U>): ExternalState<T, U>;
 
 /**
  * @description 性能优化，替代 React.Children.forEach, 回调可以返回 false 来中断循环
@@ -613,5 +708,5 @@ declare class Counter {
 
 declare const safePromiseTry: <T, U extends unknown[]>(callbackFn: (...args: U) => T | PromiseLike<T>, ...args: U) => Promise<Awaited<T>>;
 
-export { ArrayRender, Counter, DateRender, False, If, Pipe, Scope, SizeBox, Styles, Switch, Toggle, True, When, childrenLoop, createExternalState, cx, formatDate, safePromiseTry, useControlled };
-export type { ArrayRenderProps, CreateStateListener, CxInput, DateRenderProps, ElseIfProps, ElseProps, ExternalSideEffect, ExternalState, ExternalStateOptions, ExternalWithKernel, FalseProps, IfProps, PipeProps, ScopeProps, StylesDescriptor, StylesProps, StylesType, SwitchCaseProps, SwitchDefaultProps, SwitchProps, ThenProps, ToggleProps, Transform, TrueProps, UseControlledOptions, WhenProps };
+export { ArrayRender, Counter, DateRender, False, If, Observer, Pipe, Scope, SizeBox, Styles, Switch, Toggle, True, When, childrenLoop, createExternalState, createStorageState, cx, formatDate, safePromiseTry, useControlled };
+export type { ArrayRenderProps, CreateStateListener, CxInput, DateRenderProps, ElseIfProps, ElseProps, ExternalSideEffect, ExternalState, ExternalStateOptions, ExternalWithKernel, FalseProps, IfProps, ObserverProps, PipeProps, ScopeProps, StorageStateOptions, StylesDescriptor, StylesProps, StylesType, SwitchCaseProps, SwitchDefaultProps, SwitchProps, ThenProps, ToggleProps, Transform, TrueProps, UseControlledOptions, WhenProps };

package/dist/index.js

@@ -1 +1 @@
-import r,{useMemo as h,Children as J,Fragment as S,isValidElement as _,cloneElement as R,useEffect as W,useState as x,useCallback as H}from"react";function C(t,n){if(t===void 0)return;let e=0;if(Array.isArray(t)){for(const l of t)if(n(l,e++)===!1)break}else n(t,e)}const B=(t,n)=>t===n,E=t=>r.createElement(r.Fragment,null,t.children);E.displayName="Switch_Case";const w=t=>r.createElement(r.Fragment,null,t.children);w.displayName="Switch_Default";const y=t=>{const{value:n,compare:e=B,children:l,strict:o=!1}=t,a=new Set;let s=null,f=null,m=!1;return C(l,(i,c)=>{if(!r.isValidElement(i))throw new Error(`Switch Children only accepts valid React elements at index ${c}`);const u=i.type;if(u.displayName===E.displayName){const d=i.props;if(a.has(d.value))throw new Error(`Switch found duplicate Case value at index ${c}: ${JSON.stringify(d.value)}${o?" (detected in strict mode)":""}`);if(a.add(d.value),!s&&e(n,d.value)&&(s=d.children,o===!1))return!1}else if(u.displayName===w.displayName){if(m)throw new Error(`Switch can only have one Default child at index ${c}`);if(m=!0,f=i.props.children,!o&&s)return!1}else throw new Error(`Switch Children only accepts 'Case' or 'Default' elements, found: ${String(u.displayName||u.name||u)} at index ${c}`)}),r.createElement(r.Fragment,null,s??f)};y.displayName="Switch",y.Case=E,y.Default=w,y.createTyped=function(){return{Switch:y,Case:E,Default:w}};const N=t=>r.createElement(r.Fragment,null,t.children),v=({children:t})=>r.createElement(r.Fragment,null,t),F=t=>r.createElement(r.Fragment,null,t.children);N.displayName="If_Then",v.displayName="If_Else",F.displayName="If_ElseIf";const p=({condition:t,children:n})=>{let e=null,l=null;const o=[];if(r.Children.forEach(n,a=>{if(!r.isValidElement(a))throw new Error("If component only accepts valid React elements");const s=a.type;if(s.displayName===N.displayName){if(e)throw new Error("If component can only have one Then child");e=a}else if(s.displayName===F.displayName)o.push(a);else if(s.displayName===v.displayName){if(l)throw new Error("If component can only have one Else child");l=a}else throw new Error(`If component only accepts 'Then', 'ElseIf', or 'Else' elements as children, found: ${String(s.displayName||s.name||s)}`)}),t)return e?r.createElement(r.Fragment,null,e.props.children):null;for(const a of o)if(a.props.condition)return r.createElement(r.Fragment,null,a.props.children);return l?r.createElement(r.Fragment,null,l.props.children):null};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 V=({condition:t,children:n})=>t?r.createElement(r.Fragment,null,n):null,Z=({condition:t,children:n})=>t===!1?r.createElement(r.Fragment,null,n):null,z=({all:t,any:n,none:e,children:l,fallback:o})=>h(()=>(t&&(n||e)&&console.warn('When: Multiple condition types (all, any, none) provided; "all" takes precedence.'),!!(t&&t.length>0&&t.every(Boolean)||n&&n.length>0&&n.some(Boolean)||e&&e.length>0&&e.every(a=>!a))),[t,n,e])?r.createElement(r.Fragment,null,l):r.createElement(r.Fragment,null,o||null),L=({data:t,transform:n,render:e,fallback:l})=>{const o=h(()=>n.reduce((a,s)=>s(a),t),[t,n]);return o==null?r.createElement(r.Fragment,null,l||null):r.createElement(r.Fragment,null,e(o))},G=t=>{const{children:n,h:e,w:l,size:o,height:a,width:s,className:f}=t;return r.createElement("div",{style:{width:o||l||s,height:o||e||a,flexShrink:0},className:f},n)},U=({let:t,props:n,children:e,fallback:l})=>{const o=h(()=>typeof t=="function"?t(n):t,[t,n]);return!e||!Object.keys(o).length?r.createElement(r.Fragment,null,l||null):r.createElement(r.Fragment,null,e(o))};function M(...t){const n=new Set;for(const e of t)if(e){if(typeof e=="string")n.add(e);else if(Array.isArray(e))e.forEach(l=>n.add(l));else if(typeof e=="object")for(const[l,o]of Object.entries(e))o&&n.add(l)}return Array.from(n).join(" ")}const q=t=>typeof t=="object"&&!!t,b=({className:t,children:n,asWrapper:e=!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(!t)return r.createElement(S,null,n);const l=typeof t=="string"?t:M(...Object.values(t));if(e)return r.createElement(e===!0?"div":e,{className:l},n);if(_(n)){const o=n;let a=o?.props?.className;return o?.type?.displayName===b.displayName&&q(a)&&(a=M(...Object.values(a))),R(n,{className:M(l,a)})}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=t=>{const{index:n=0,options:e,next:l,render:o}=t;W(()=>{if(e.length<n+1)throw new Error(`Index ${n} is out of bounds for options array of length ${e.length}. Defaulting to first option.`)},[n,e]);const[a,s]=x(n),f=()=>{s(m=>e.length?l?l(m,e):(m+1)%e.length:m)};return o(e[a],f)};function Q(t){const{items:n,renderItem:e,filter:l}=t;return n?r.createElement(S,null,n.map((o,a)=>l&&!l(o)?null:e(o,a))):(console.error("ArrayRender: items is null"),null)}function X({source:t,format:n,children:e}){const l=h(()=>{if(t instanceof Date)return t;if(typeof t=="string"||typeof t=="number"){const a=new Date(t);return isNaN(a.getTime())?null:a}return null},[t]),o=h(()=>l?n?n(l):l.toLocaleString():null,[l,n]);return!o||!e?null:r.createElement(r.Fragment,null,e(o))}const $="onChange",ee="value";function te(t){const{defaultValue:n,onBeforeChange:e,trigger:l=$,valuePropName:o=ee,props:a}=t,s=Object.prototype.hasOwnProperty.call(a,o),[f,m]=x(n),i=s?a[o]:f,c=h(()=>a[l],[a,l]),u=H(d=>{const g=typeof d=="function"?d(i):d;e&&e(g,i)===!1||(s||m(g),c&&c(g))},[s,e,i,c]);return[i,u]}function ne(t,...n){try{const e=t(...n);return e instanceof Promise?e:Promise.resolve(e)}catch(e){return Promise.reject(e)}}const I=typeof Promise.try=="function"?Promise.try.bind(Promise):ne;function re(t,n={}){let e=typeof t=="function"?t():t;const l=[],{sideEffect:o,transform:a}=n,s=()=>{const i=e;return a?.get?a.get(i):i},f=i=>{const c=e,u=a?.get?a.get(c):c;e=a?.set?a.set(typeof i=="function"?i(u):i):typeof i=="function"?i(u):i,l.forEach(d=>d(e)),o&&I(o,e,c).catch(d=>{console.error("Error in external state side effect, Please do it within side effects:",d)})},m=()=>{const[i,c]=r.useState(e);return r.useEffect(()=>(l.push(c),()=>{const u=l.indexOf(c);u>-1&&l.splice(u,1)}),[]),[a?.get?a.get(i):i,f]};return{get:s,set:f,use:m,useGetter:()=>{const[i]=m();return i},__listeners:l}}function le(t,n){const e=n||new Date,l=e.getFullYear(),o=e.getMonth()+1,a=e.getDate(),s=e.getHours(),f=e.getMinutes(),m=e.getSeconds(),i=e.getMilliseconds(),c=e.getDay(),u=["Sun","Mon","Tue","Wed","Thu","Fri","Sat"],d=["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"],P=d[c],D=u[c],T=o-1,Y=A[T],k=g[T],O={YY:l.toString().slice(2),YYYY:l.toString(),M:o.toString(),MM:o.toString().padStart(2,"0"),MMM:k,MMMM:Y,D:a.toString(),DD:a.toString().padStart(2,"0"),d:c.toString(),dd:D,ddd:D,dddd:P,H:s.toString(),HH:s.toString().padStart(2,"0"),h:(s%12).toString(),hh:(s%12).toString().padStart(2,"0"),m:f.toString(),mm:f.toString().padStart(2,"0"),s:m.toString(),ss:m.toString().padStart(2,"0"),SSS:i.toString().padStart(3,"0"),Z:"+08:00",ZZ:"+0800",A:s<12?"AM":"PM",a:s<12?"am":"pm"};return t.replace(/YYYY|YY|M{1,4}|D{1,2}|d{1,4}|H{1,2}|h{1,2}|m{1,2}|s{1,2}|SSS|Z{1,2}|A|a/g,j=>O[j])}class ae{count=0;next(){return this.count++}}export{Q as ArrayRender,ae as Counter,X as DateRender,Z as False,p as If,L as Pipe,U as Scope,G as SizeBox,b as Styles,y as Switch,K as Toggle,V as True,z as When,C as childrenLoop,re as createExternalState,M as cx,le as formatDate,I as safePromiseTry,te as useControlled};
+import a,{useMemo as g,Children as W,Fragment as E,isValidElement as H,cloneElement as B,useEffect as D,useState as A,useRef as O,useCallback as V}from"react";function P(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,w=e=>a.createElement(a.Fragment,null,e.children);w.displayName="Switch_Case";const N=e=>a.createElement(a.Fragment,null,e.children);N.displayName="Switch_Default";const y=e=>{const{value:n,compare:t=Z,children:r,strict:o=!1}=e,l=new Set;let s=null,u=null,f=!1;return P(r,(c,i)=>{if(!a.isValidElement(c))throw new Error(`Switch Children only accepts valid React elements at index ${i}`);const d=c.type;if(d.displayName===w.displayName){const m=c.props;if(l.has(m.value))throw new Error(`Switch found duplicate Case value at index ${i}: ${JSON.stringify(m.value)}${o?" (detected in strict mode)":""}`);if(l.add(m.value),!s&&t(n,m.value)&&(s=m.children,o===!1))return!1}else if(d.displayName===N.displayName){if(f)throw new Error(`Switch can only have one Default child at index ${i}`);if(f=!0,u=c.props.children,!o&&s)return!1}else throw new Error(`Switch Children only accepts 'Case' or 'Default' elements, found: ${String(d.displayName||d.name||d)} at index ${i}`)}),a.createElement(a.Fragment,null,s??u)};y.displayName="Switch",y.Case=w,y.Default=N,y.createTyped=function(){return{Switch:y,Case:w,Default:N}};const v=e=>a.createElement(a.Fragment,null,e.children),b=({children:e})=>a.createElement(a.Fragment,null,e),M=e=>a.createElement(a.Fragment,null,e.children);v.displayName="If_Then",b.displayName="If_Else",M.displayName="If_ElseIf";const h=({condition:e,children:n})=>{let t=null,r=null;const o=[];if(a.Children.forEach(n,l=>{if(!a.isValidElement(l))throw new Error("If component only accepts valid React elements");const s=l.type;if(s.displayName===v.displayName){if(t)throw new Error("If component can only have one Then child");t=l}else if(s.displayName===M.displayName)o.push(l);else if(s.displayName===b.displayName){if(r)throw new Error("If component can only have one Else child");r=l}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?a.createElement(a.Fragment,null,t.props.children):null;for(const l of o)if(l.props.condition)return a.createElement(a.Fragment,null,l.props.children);return r?a.createElement(a.Fragment,null,r.props.children):null};h.displayName="If",h.Then=v,h.ElseIf=M,h.Else=b,h.createTyped=function(){return{If:h,Then:v,ElseIf:M,Else:b}};const z=({condition:e,children:n})=>e?a.createElement(a.Fragment,null,n):null,L=({condition:e,children:n})=>e===!1?a.createElement(a.Fragment,null,n):null,U=({all:e,any:n,none:t,children:r,fallback:o})=>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(l=>!l))),[e,n,t])?a.createElement(a.Fragment,null,r):a.createElement(a.Fragment,null,o||null),G=({data:e,transform:n,render:t,fallback:r})=>{const o=g(()=>n.reduce((l,s)=>s(l),e),[e,n]);return o==null?a.createElement(a.Fragment,null,r||null):a.createElement(a.Fragment,null,t(o))},$=e=>{const{children:n,h:t,w:r,size:o,height:l,width:s,className:u}=e;return a.createElement("div",{style:{width:o||r||s,height:o||t||l,flexShrink:0},className:u},n)},q=({let:e,props:n,children:t,fallback:r})=>{const o=g(()=>typeof e=="function"?e(n):e,[e,n]);return!t||!Object.keys(o).length?a.createElement(a.Fragment,null,r||null):a.createElement(a.Fragment,null,t(o))};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,o]of Object.entries(t))o&&n.add(r)}return Array.from(n).join(" ")}const K=e=>typeof e=="object"&&!!e,x=({className:e,children:n,asWrapper:t=!1})=>{if(!n)return null;if(W.count(n)>1)return console.error("<Styles>: children has more than one child. Please check your code."),a.createElement(E,null,n);if(!e)return a.createElement(E,null,n);const r=typeof e=="string"?e:F(...Object.values(e));if(t)return a.createElement(t===!0?"div":t,{className:r},n);if(H(n)){const o=n;let l=o?.props?.className;return o?.type?.displayName===x.displayName&&K(l)&&(l=F(...Object.values(l))),B(n,{className:F(r,l)})}return console.error("<Styles>: children is not a valid React element. Please check your code."),a.createElement(E,null,n)};x.displayName="W/Styles";const Q=e=>{const{index:n=0,options:t,next:r,render:o}=e;D(()=>{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[l,s]=A(n),u=()=>{s(f=>t.length?r?r(f,t):(f+1)%t.length:f)};return o(t[l],u)},X=({onIntersect:e,threshold:n=.1,root:t=null,rootMargin:r="0px",triggerOnce:o=!1,disabled:l=!1,children:s,className:u,style:f})=>{const c=O(null),i=O(null),d=O(!1);return D(()=>{if(l||!c.current)return;if(!window.IntersectionObserver){console.warn("IntersectionObserver is not supported in this browser");return}const m=c.current,p=I=>{I.forEach(S=>{if(S.isIntersecting){if(o&&d.current)return;e(S,i.current),o&&(d.current=!0,i.current?.unobserve(m))}})};return i.current=new IntersectionObserver(p,{root:t,rootMargin:r,threshold:n}),i.current.observe(m),()=>{i.current&&i.current.disconnect()}},[e,n,t,r,o,l]),D(()=>{o||(d.current=!1)},[o]),a.createElement("div",{ref:c,className:u,style:f},s)};function ee(e){const{items:n,renderItem:t,filter:r}=e;return n?a.createElement(E,null,n.map((o,l)=>r&&!r(o)?null:t(o,l))):(console.error("ArrayRender: items is null"),null)}function te({source:e,format:n,children:t}){const r=g(()=>{if(e instanceof Date)return e;if(typeof e=="string"||typeof e=="number"){const l=new Date(e);return isNaN(l.getTime())?null:l}return null},[e]),o=g(()=>r?n?n(r):r.toLocaleString():null,[r,n]);return!o||!t?null:a.createElement(a.Fragment,null,t(o))}const ne="onChange",re="value";function le(e){const{defaultValue:n,onBeforeChange:t,trigger:r=ne,valuePropName:o=re,props:l}=e,s=Object.prototype.hasOwnProperty.call(l,o),[u,f]=A(n),c=s?l[o]:u,i=g(()=>l[r],[l,r]),d=V(m=>{const p=typeof m=="function"?m(c):m;t&&t(p,c)===!1||(s||f(p),i&&i(p))},[s,t,c,i]);return[c,d]}function oe(e,...n){try{const t=e(...n);return t instanceof Promise?t:Promise.resolve(t)}catch(t){return Promise.reject(t)}}const Y=typeof Promise.try=="function"?Promise.try.bind(Promise):oe;function k(e,n={}){let t=typeof e=="function"?e():e;const r=[],{sideEffect:o,transform:l}=n,s=()=>{const c=t;return l?.get?l.get(c):c},u=c=>{const i=t,d=l?.get?l.get(i):i;t=l?.set?l.set(typeof c=="function"?c(d):c):typeof c=="function"?c(d):c,r.forEach(m=>m(t)),o&&Y(o,t,i).catch(m=>{console.error("Error in external state side effect, Please do it within side effects:",m)})},f=()=>{const[c,i]=a.useState(t);return a.useEffect(()=>(r.push(i),()=>{const d=r.indexOf(i);d>-1&&r.splice(d,1)}),[]),[l?.get?l.get(c):c,u]};return{get:s,set:u,use:f,useGetter:()=>{const[c]=f();return c},__listeners:r}}function ae(e,n,t){const{storageType:r="local",sideEffect:o,transform:l}=t??{},s=r==="local"?localStorage:sessionStorage;let u=n;const f=s.getItem(e);if(f)try{u=JSON.parse(f)}catch(c){console.warn(`Failed to parse ${r}Storage value for key "${e}", using initial state:`,c),u=n}return k(u,{sideEffect:c=>{s.setItem(e,JSON.stringify(c)),o?.(c)},transform:l})}function se(e,n){const t=n||new Date,r=t.getFullYear(),o=t.getMonth()+1,l=t.getDate(),s=t.getHours(),u=t.getMinutes(),f=t.getSeconds(),c=t.getMilliseconds(),i=t.getDay(),d=["Sun","Mon","Tue","Wed","Thu","Fri","Sat"],m=["Sunday","Monday","Tuesday","Wednesday","Thursday","Friday","Saturday"],p=["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"],S=m[i],T=d[i],C=o-1,j=I[C],J=p[C],R={YY:r.toString().slice(2),YYYY:r.toString(),M:o.toString(),MM:o.toString().padStart(2,"0"),MMM:J,MMMM:j,D:l.toString(),DD:l.toString().padStart(2,"0"),d:i.toString(),dd:T,ddd:T,dddd:S,H:s.toString(),HH:s.toString().padStart(2,"0"),h:(s%12).toString(),hh:(s%12).toString().padStart(2,"0"),m:u.toString(),mm:u.toString().padStart(2,"0"),s:f.toString(),ss:f.toString().padStart(2,"0"),SSS:c.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,_=>R[_])}class ce{count=0;next(){return this.count++}}export{ee as ArrayRender,ce as Counter,te as DateRender,L as False,h as If,X as Observer,G as Pipe,q as Scope,$ as SizeBox,x as Styles,y as Switch,Q as Toggle,z as True,U as When,P as childrenLoop,k as createExternalState,ae as createStorageState,F as cx,se as formatDate,Y as safePromiseTry,le as useControlled};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wwog/react",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "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/components/Sundry/Observer.tsx

@@ -0,0 +1,168 @@
+import React, { useEffect, useRef, type ReactNode } from "react";
+
+export interface ObserverProps {
+  /**
+   * @description_en Callback function when intersection occurs.
+   * @description_zh 交叉时触发的回调函数。
+   */
+  onIntersect: (entry: IntersectionObserverEntry, observer: IntersectionObserver) => void;
+  /**
+   * @description_en Threshold(s) at which to trigger the callback. Default is 0.1.
+   * @description_zh 触发回调的阈值，默认为 0.1。
+   * @optional
+   * @default 0.1
+   */
+  threshold?: number | number[];
+  /**
+   * @description_en The root element for intersection. Default is viewport.
+   * @description_zh 交叉的根元素，默认为视口。
+   * @optional
+   * @default null
+   */
+  root?: Element | Document | null;
+  /**
+   * @description_en Margin around the root. Default is "0px".
+   * @description_zh 根元素周围的边距，默认为 "0px"。
+   * @optional
+   * @default "0px"
+   */
+  rootMargin?: string;
+  /**
+   * @description_en Whether to trigger only once. Default is false.
+   * @description_zh 是否只触发一次，默认为 false。
+   * @optional
+   * @default false
+   */
+  triggerOnce?: boolean;
+  /**
+   * @description_en Whether to disable the observer. Default is false.
+   * @description_zh 是否禁用观察者，默认为 false。
+   * @optional
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * @description_en Child elements to observe.
+   * @description_zh 要观察的子元素。
+   * @optional
+   */
+  children?: ReactNode;
+  /**
+   * @description_en CSS class name.
+   * @description_zh CSS 类名。
+   * @optional
+   */
+  className?: string;
+  /**
+   * @description_en Inline styles.
+   * @description_zh 内联样式。
+   * @optional
+   */
+  style?: React.CSSProperties;
+}
+
+/* 
+提供声明式的观察者API封装。
+简化懒加载、无限滚动等常见场景的实现。
+支持灵活的配置选项和一次性触发。
+*/
+/**
+ * @description_zh 交叉观察者组件，用于监听元素与视口的交叉状态，常用于懒加载和无限滚动场景。
+ * @description_en Intersection Observer component for monitoring element-viewport intersection, commonly used for lazy loading and infinite scrolling.
+ * @component
+ * @example
+ * ```tsx
+ * // 懒加载示例
+ * <Observer onIntersect={loadImage} triggerOnce>
+ *   <img data-src="image.jpg" alt="Lazy loaded" />
+ * </Observer>
+ * 
+ * // 无限滚动示例
+ * <Observer onIntersect={loadMore} threshold={0.1}>
+ *   <div>滚动到这里加载更多</div>
+ * </Observer>
+ * 
+ * // 自定义根元素和边距
+ * <Observer 
+ *   onIntersect={handleIntersect}
+ *   root={scrollContainer}
+ *   rootMargin="100px"
+ *   threshold={[0, 0.5, 1]}
+ * >
+ *   <div>观察目标</div>
+ * </Observer>
+ * ```
+ */
+export const Observer: React.FC<ObserverProps> = ({
+  onIntersect,
+  threshold = 0.1,
+  root = null,
+  rootMargin = "0px",
+  triggerOnce = false,
+  disabled = false,
+  children,
+  className,
+  style,
+}) => {
+  const elementRef = useRef<HTMLDivElement>(null);
+  const observerRef = useRef<IntersectionObserver | null>(null);
+  const hasTriggeredRef = useRef(false);
+
+  useEffect(() => {
+    if (disabled || !elementRef.current) {
+      return;
+    }
+
+    // 检查浏览器支持
+    if (!window.IntersectionObserver) {
+      console.warn('IntersectionObserver is not supported in this browser');
+      return;
+    }
+
+    const element = elementRef.current;
+
+    const handleIntersect = (entries: IntersectionObserverEntry[]) => {
+      entries.forEach((entry) => {
+        if (entry.isIntersecting) {
+          if (triggerOnce && hasTriggeredRef.current) {
+            return;
+          }
+
+          onIntersect(entry, observerRef.current!);
+          
+          if (triggerOnce) {
+            hasTriggeredRef.current = true;
+            observerRef.current?.unobserve(element);
+          }
+        }
+      });
+    };
+
+    observerRef.current = new IntersectionObserver(handleIntersect, {
+      root,
+      rootMargin,
+      threshold,
+    });
+
+    observerRef.current.observe(element);
+
+    return () => {
+      if (observerRef.current) {
+        observerRef.current.disconnect();
+      }
+    };
+  }, [onIntersect, threshold, root, rootMargin, triggerOnce, disabled]);
+
+  // 重置触发状态（当 triggerOnce 从 true 变为 false 时）
+  useEffect(() => {
+    if (!triggerOnce) {
+      hasTriggeredRef.current = false;
+    }
+  }, [triggerOnce]);
+
+  return (
+    <div ref={elementRef} className={className} style={style}>
+      {children}
+    </div>
+  );
+};

package/src/components/Sundry/index.ts

@@ -2,3 +2,4 @@ export * from "./SizeBox";
 export * from "./Scope";
 export * from "./Styles";
 export * from "./Toggle";
+export * from "./Observer";

package/src/utils/createExternalState.test.tsx

@@ -1,10 +1,10 @@
-import { expect, describe, it, vi } from "vitest";
+import { expect, describe, it, vi, beforeEach } from "vitest";
 import { render } from "vitest-browser-react";
 import {
   createExternalState,
+  createStorageState,
   type ExternalWithKernel,
 } from "./createExternalState";
-import { safePromiseTry } from "./promise";
 import React from "react";
 
 describe("createExternalState", () => {
@@ -219,3 +219,172 @@ describe("createExternalState", () => {
     expect(state.get()).toBe("TEST");
   });
 });
+
+describe("createStorageState", () => {
+  beforeEach(() => {
+    // 清理localStorage和sessionStorage
+    localStorage.clear();
+    sessionStorage.clear();
+    vi.clearAllMocks();
+  });
+
+  it("测试localStorage初始状态", () => {
+    const state = createStorageState("test-key", "initial", {
+      storageType: "local",
+    });
+    expect(state.get()).toBe("initial");
+    expect(localStorage.getItem("test-key")).toBeNull();
+  });
+
+  it("测试localStorage状态持久化", () => {
+    const state = createStorageState("test-key", "initial", {
+      storageType: "local",
+    });
+    
+    state.set("updated");
+    expect(state.get()).toBe("updated");
+    expect(localStorage.getItem("test-key")).toBe('"updated"');
+  });
+
+  it("测试从localStorage恢复状态", () => {
+    // 预先设置localStorage值
+    localStorage.setItem("test-key", '"stored-value"');
+    
+    const state = createStorageState("test-key", "initial", {
+      storageType: "local",
+    });
+    
+    expect(state.get()).toBe("stored-value");
+  });
+
+  it("测试sessionStorage状态持久化", () => {
+    const state = createStorageState("test-key", "initial", {
+      storageType: "session",
+    });
+    
+    state.set("session-updated");
+    expect(state.get()).toBe("session-updated");
+    expect(sessionStorage.getItem("test-key")).toBe('"session-updated"');
+  });
+
+  it("测试从sessionStorage恢复状态", () => {
+    // 预先设置sessionStorage值
+    sessionStorage.setItem("test-key", '"session-stored"');
+    
+    const state = createStorageState("test-key", "initial", {
+      storageType: "session",
+    });
+    
+    expect(state.get()).toBe("session-stored");
+  });
+
+  it("测试复杂对象的存储和恢复", () => {
+    interface User {
+      name: string;
+      age: number;
+    }
+    
+    const initialUser: User = { name: "张三", age: 25 };
+    const state = createStorageState<User>("user-key", initialUser, {
+      storageType: "local",
+    });
+    
+    const updatedUser: User = { name: "李四", age: 30 };
+    state.set(updatedUser);
+    
+    expect(state.get()).toEqual(updatedUser);
+    expect(JSON.parse(localStorage.getItem("user-key")!)).toEqual(updatedUser);
+    
+    // 创建新实例验证恢复
+    const newState = createStorageState<User>("user-key", initialUser, {
+      storageType: "local",
+    });
+    expect(newState.get()).toEqual(updatedUser);
+  });
+
+  it("测试存储解析错误处理", () => {
+    const consoleSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    
+    // 设置无效的JSON数据
+    localStorage.setItem("test-key", "invalid-json");
+    
+    const state = createStorageState("test-key", "fallback", {
+      storageType: "local",
+    });
+    
+    expect(state.get()).toBe("fallback");
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Failed to parse localStorage value for key "test-key"'),
+      expect.any(Error)
+    );
+    
+    consoleSpy.mockRestore();
+  });
+
+  it("测试存储副作用函数", () => {
+    const mockSideEffect = vi.fn();
+    const state = createStorageState("test-key", "initial" as string, {
+      storageType: "local",
+      sideEffect: mockSideEffect,
+    });
+    
+    state.set("updated");
+    
+    expect(mockSideEffect).toHaveBeenCalledTimes(1);
+    expect(mockSideEffect).toHaveBeenCalledWith("updated");
+    expect(localStorage.getItem("test-key")).toBe('"updated"');
+  });
+
+  it("测试存储状态的transform功能", () => {
+    const state = createStorageState("test-key", "hello", {
+      storageType: "local",
+      transform: {
+        get: (str) => str.toUpperCase(),
+        set: (str) => str.toLowerCase(),
+      },
+    });
+    
+    expect(state.get()).toBe("HELLO");
+    
+    state.set("WORLD");
+    expect(state.get()).toBe("WORLD");
+    expect(localStorage.getItem("test-key")).toBe('"world"');
+  });
+
+  it("测试存储状态在React组件中的使用", async () => {
+    const state = createStorageState("component-key", "initial", {
+      storageType: "local",
+    });
+    
+    function TestComponent() {
+      const [value, setValue] = state.use();
+      return (
+        <div>
+          <span data-testid="value">{value}</span>
+          <button onClick={() => setValue("component-updated")}>Update</button>
+        </div>
+      );
+    }
+    
+    const { getByTestId, getByText } = render(<TestComponent />);
+    const valueLocator = getByTestId("value");
+    const buttonLocator = getByText("Update");
+    
+    expect(valueLocator.element().textContent).toBe("initial");
+    
+    await buttonLocator.click();
+    
+    expect(valueLocator.element().textContent).toBe("component-updated");
+    expect(state.get()).toBe("component-updated");
+    expect(localStorage.getItem("component-key")).toBe('"component-updated"');
+  });
+
+  it("测试默认storageType为local", () => {
+    const state = createStorageState("default-key", "initial");
+    
+    state.set("default-updated");
+    
+    expect(localStorage.getItem("default-key")).toBe('"default-updated"');
+    expect(sessionStorage.getItem("default-key")).toBeNull();
+  });
+});

package/src/utils/createExternalState.ts

@@ -200,3 +200,38 @@ export function createExternalState<T, U = T>(
   //@ts-expect-error ignore
   return { get, set, use, useGetter, __listeners: listeners };
 }
+
+export interface StorageStateOptions<T, U> {
+  sideEffect?: (newState: T) => void;
+  transform?: Transform<T, U>;
+  storageType: "local" | "session";
+}
+
+export function createStorageState<T, U = T>(
+  key: string,
+  initialState: T,
+  options?: StorageStateOptions<T, U>
+) {
+  const { storageType = "local", sideEffect, transform } = options ?? {};
+  const storage = storageType === "local" ? localStorage : sessionStorage;
+  let _initState: T = initialState;
+  const storedValue = storage.getItem(key);
+  if (storedValue) {
+    try {
+      _initState = JSON.parse(storedValue);
+    } catch (error) {
+      console.warn(
+        `Failed to parse ${storageType}Storage value for key "${key}", using initial state:`,
+        error
+      );
+      _initState = initialState;
+    }
+  }
+  return createExternalState(_initState, {
+    sideEffect: (newState) => {
+      storage.setItem(key, JSON.stringify(newState));
+      sideEffect?.(newState);
+    },
+    transform,
+  });
+}