@cmtlyt/lingshu-toolkit 0.2.0 → 0.3.0

package/dist/607.js

@@ -0,0 +1,311 @@
+import { dataHandler, logger, $dt, throwError, $t, throwType } from "./707.js";
+function withResolvers() {
+    return 'function' == typeof Promise.withResolvers ? Promise.withResolvers() : (()=>{
+        const resolver = {
+            promise: null,
+            resolve: null,
+            reject: null
+        };
+        resolver.promise = new Promise((resolve, reject)=>{
+            resolver.resolve = resolve;
+            resolver.reject = reject;
+        });
+        return resolver;
+    })();
+}
+const noop = ()=>void 0;
+const identity = (_v)=>_v;
+function getType(_v) {
+    return Object.prototype.toString.call(_v).slice(8, -1).toLowerCase();
+}
+function getNextValueHandler(from, to, valueFormatter) {
+    const type = getType(from);
+    const context = {
+        progress: 0,
+        valueFormatter
+    };
+    const baseNextValue = (_from, _to)=>{
+        const { valueFormatter: formatter, progress } = context;
+        if ('number' !== getType(_from)) return _from;
+        return formatter(_from + (_to - _from) * progress);
+    };
+    const arrayHandler = (_from, _to)=>{
+        const result = Array.from(_from, (item, idx)=>{
+            if (Array.isArray(item)) return arrayHandler(item, _to[idx]);
+            if ('object' === getType(item)) return objectHandler(item, _to[idx]);
+            return baseNextValue(item, _to[idx]);
+        });
+        return result;
+    };
+    const objectHandler = (_from, _to)=>{
+        const result = {};
+        const keys = Reflect.ownKeys(_from);
+        for(let i = 0; i < keys.length; i++){
+            const key = keys[i];
+            const fromValue = _from[key];
+            const toValue = _to[key];
+            if (Array.isArray(_from[key])) result[key] = arrayHandler(fromValue, toValue);
+            else if ('object' === getType(fromValue)) result[key] = objectHandler(fromValue, toValue);
+            else result[key] = baseNextValue(fromValue, toValue);
+        }
+        return result;
+    };
+    let nextValueHandler = baseNextValue;
+    if ('array' === type) nextValueHandler = arrayHandler;
+    else if ('object' === type) nextValueHandler = objectHandler;
+    return (progress)=>{
+        context.progress = progress;
+        return nextValueHandler(from, to);
+    };
+}
+function matchValid(from, to, valueParser) {
+    const fromType = getType(from);
+    const toType = getType(to);
+    if (fromType !== toType) throwType('animation/stepAnimation', 'from and to must be the same type');
+    if ('array' === fromType) {
+        if (from.length !== to.length) throwType('animation/stepAnimation', 'from and to must be the same length');
+        const result = [
+            Array.from({
+                length: from.length
+            }),
+            Array.from({
+                length: to.length
+            })
+        ];
+        for(let i = 0; i < from.length; i++){
+            const [fromItem, toItem] = matchValid(from[i], to[i], valueParser);
+            result[0][i] = fromItem;
+            result[1][i] = toItem;
+        }
+        return result;
+    }
+    if ('object' === fromType) {
+        const toKeys = Reflect.ownKeys(to);
+        const fromKeys = new Set(Reflect.ownKeys(from));
+        const result = [
+            {},
+            {}
+        ];
+        for(let i = 0; i < toKeys.length; i++){
+            const key = toKeys[i];
+            if (!fromKeys.has(key)) throwType('animation/stepAnimation', `from does not have this key: ${String(key)}`);
+            const [fromItem, toItem] = matchValid(from[key], to[key], valueParser);
+            result[0][key] = fromItem;
+            result[1][key] = toItem;
+        }
+        return result;
+    }
+    if ('number' !== fromType) return [
+        valueParser(from),
+        valueParser(to)
+    ];
+    return [
+        from,
+        to
+    ];
+}
+function createNextTick(resolvers, rcSignal) {
+    const nextTick = (()=>{
+        if ('function' == typeof globalThis.requestAnimationFrame) return globalThis.requestAnimationFrame;
+        return (callback)=>setTimeout(callback, 16);
+    })();
+    return (callback)=>{
+        if (rcSignal.stopSignal) return true;
+        nextTick(()=>tryRun(callback, resolvers, (error)=>{
+                rcSignal.stop();
+                resolvers.reject(error);
+            }));
+        return false;
+    };
+}
+async function tryRun(callback, resolvers, customErrorHandler) {
+    return new Promise((resolve, reject)=>{
+        const result = callback();
+        if (result && 'function' == typeof result.then) return result.then(resolve, reject);
+        resolve();
+    }).catch(customErrorHandler || resolvers.reject);
+}
+function createRunningControllerSignal(startFn, options) {
+    const { onStart, onStop, onClear } = options;
+    const resolvers = withResolvers();
+    const ctrl = {
+        stopSignal: true,
+        resolvers,
+        stop: ()=>{
+            ctrl.stopSignal = true;
+            onStop();
+        },
+        start: ()=>{
+            ctrl.stopSignal = false;
+            onStart();
+            startFn();
+        },
+        clear: ()=>{
+            ctrl.stopSignal = true;
+            onClear();
+            resolvers.resolve(true);
+        }
+    };
+    return ctrl;
+}
+function* stepAnimation(from, to, step, options = {}) {
+    if (!Number.isInteger(step) || step <= 0) throwError('stepAnimation', 'step must be a positive integer', RangeError);
+    const { parser: valueParser = identity, formatter: valueFormatter = identity } = options;
+    const [validFrom, validTo] = matchValid(from, to, valueParser);
+    const getNextValue = getNextValueHandler(validFrom, validTo, valueFormatter);
+    for(let i = 0; i <= step; i++){
+        const value = getNextValue(i / step);
+        yield value;
+    }
+}
+const validInfo = $dt({
+    autoStart: $t.boolean(true),
+    easing: $t["function"](()=>identity),
+    onStart: $t["function"](()=>noop),
+    onStop: $t["function"](()=>noop),
+    onClear: $t["function"](()=>noop),
+    onUpdate: $t["function"](()=>noop),
+    onComplete: $t["function"](()=>noop),
+    formatter: $t["function"](()=>identity),
+    parser: $t["function"](()=>identity)
+});
+function animation(from, to, duration, options = {}) {
+    if (duration <= 0 || !Number.isInteger(duration)) throwError('animation', 'duration must be a positive integer', RangeError);
+    const validOptions = dataHandler(options, validInfo, {
+        unwrap: true
+    });
+    const [validFrom, validTo] = matchValid(from, to, validOptions.parser);
+    const { autoStart, easing, onComplete, onUpdate, formatter: valueFormatter } = validOptions;
+    const getNextValue = getNextValueHandler(validFrom, validTo, valueFormatter);
+    let startTime = 0;
+    let hasStarted = false;
+    const rcSignal = createRunningControllerSignal(()=>{
+        const now = performance.now();
+        startTime += now;
+        const stopFlag = nextTick(tick);
+        if (stopFlag) {
+            startTime -= performance.now();
+            return;
+        }
+        if (!hasStarted) {
+            onUpdate(getNextValue(0));
+            hasStarted = true;
+        }
+    }, validOptions);
+    const { resolvers } = rcSignal;
+    const nextTick = createNextTick(resolvers, rcSignal);
+    const tick = ()=>{
+        const elapsed = performance.now() - startTime;
+        const progress = easing(Math.min(elapsed / duration, 1));
+        const value = getNextValue(progress);
+        onUpdate(value);
+        if (elapsed < duration) {
+            const stopFlag = nextTick(tick);
+            if (stopFlag) startTime = -elapsed;
+        } else {
+            onComplete();
+            resolvers.resolve(false);
+        }
+    };
+    if (false !== autoStart) rcSignal.start();
+    return {
+        promise: resolvers.promise,
+        stop: rcSignal.stop,
+        start: rcSignal.start,
+        clear: rcSignal.clear
+    };
+}
+function getEmpty(_v) {
+    return Array.isArray(_v) ? [] : {};
+}
+function valueCheck(_v) {
+    return Array.isArray(_v) || 'object' == typeof _v;
+}
+function conditionMerge(...input) {
+    const conditionItems = (input.length > 1 ? input : input[0]).map((item)=>{
+        let result = null;
+        if (Array.isArray(item)) {
+            const [condition, value, fullback] = item;
+            result = {
+                condition,
+                value,
+                fullback
+            };
+        } else if (Object.getOwnPropertyDescriptor(item, 'condition')) result = item;
+        else throwType('conditionMerge', 'input must be an ConditionItem');
+        const validValue = valueCheck(result.value);
+        const validFullback = void 0 === result.fullback || valueCheck(result.fullback);
+        if (!(validValue && validFullback)) throwType('conditionMerge', 'value and fullback must be an array or object');
+        return result;
+    });
+    const result = getEmpty(conditionItems[0].value);
+    const mergeFn = Array.isArray(result) ? (a1, a2)=>Reflect.apply(Array.prototype.splice.bind(a1, a1.length, 0), null, a2) : Object.assign;
+    for(let i = 0, item = conditionItems[i]; i < conditionItems.length; item = conditionItems[++i])mergeFn(result, item.condition ? item.value : item.fullback || getEmpty(item.value));
+    return result;
+}
+const create_storage_handler_validInfo = $dt({
+    storageKey: 'validString',
+    storageType: $t["enum"]([
+        'local',
+        'session',
+        'memory'
+    ], 'local'),
+    autoSaveInterval: $t.number(0)
+});
+const memoryStorage = {
+    data: {},
+    getItem (key) {
+        return this.data[key];
+    },
+    setItem (key, value) {
+        this.data[key] = value;
+    },
+    removeItem (key) {
+        delete this.data[key];
+    }
+};
+function getStorage(storageType) {
+    try {
+        if ('memory' === storageType) return memoryStorage;
+        return 'local' === storageType ? localStorage : sessionStorage;
+    } catch  {
+        logger.warn('createStorage', 'Failed to access localStorage or sessionStorage, using memoryStorage instead.');
+        return memoryStorage;
+    }
+}
+const CLEAR_FLAG = Symbol('cleared');
+function createStorageHandler(storageKey, initialData, options = {}) {
+    const { storageKey: validStorageKey, storageType, autoSaveInterval } = dataHandler({
+        storageKey,
+        ...options
+    }, create_storage_handler_validInfo, {
+        unwrap: true
+    });
+    const storage = getStorage(storageType);
+    const storageData = storage.getItem(validStorageKey);
+    const context = {
+        data: storageData ? JSON.parse(storageData) : initialData || {}
+    };
+    return {
+        get (key) {
+            if (context.data === CLEAR_FLAG) throwError('createStorageHandler', 'Storage has been cleared.');
+            if (null == key) return context.data;
+            return context.data[key];
+        },
+        set (value, key) {
+            if (context.data === CLEAR_FLAG) throwError('createStorageHandler', 'Storage has been cleared.');
+            if (null == key) context.data = value;
+            else context.data[key] = value;
+            if (autoSaveInterval > 0) setTimeout(()=>{
+                storage.setItem(validStorageKey, JSON.stringify(context.data));
+            }, autoSaveInterval);
+            else storage.setItem(validStorageKey, JSON.stringify(context.data));
+        },
+        clear () {
+            context.data = CLEAR_FLAG;
+            storage.removeItem(validStorageKey);
+        }
+    };
+}
+Symbol('__PACK__');
+export { animation, conditionMerge, createStorageHandler, stepAnimation, withResolvers };

package/dist/707.js

@@ -34,7 +34,12 @@ const $t = {
     object: typeHandler('object'),
     array: typeHandler('array'),
     function: typeHandler('function'),
-    symbol: typeHandler('symbol')
+    symbol: typeHandler('symbol'),
+    enum: (list, fullback)=>{
+        if (!Array.isArray(list)) throwType('$t.enum', 'list must be an array');
+        const set = new Set(list);
+        return typeHandler('enum', (_v)=>set.has(_v))(fullback);
+    }
 };
 function defineTransform(dataInfo) {
     const verifyInfo = {};

package/dist/react/index.d.ts

@@ -1,3 +1,10 @@
+export * from './use-boolean';
 export * from './use-controllable-value';
 export * from './use-counter';
+export * from './use-force-update';
+export * from './use-mount';
+export * from './use-ref-state';
+export * from './use-storage';
+export * from './use-title';
+export * from './use-toggle';
 export * from './use-valid-data';

package/dist/react/index.js

@@ -1,5 +1,42 @@
-import { useEffect, useEffectEvent, useMemo, useRef, useState } from "react";
-import { dataHandler, logger, $dt, $t } from "../707.js";
+import { useEffect, useEffectEvent, useMemo, useReducer, useRef, useState } from "react";
+import { dataHandler, logger, $dt, $t, throwType } from "../707.js";
+import { createStorageHandler } from "../607.js";
+function useToggle(defualtValue = false, reverseValue) {
+    const [state, setState] = useState(defualtValue);
+    const toggleRef = useRef([
+        defualtValue,
+        void 0 === reverseValue ? !defualtValue : reverseValue
+    ]);
+    const actions = useMemo(()=>{
+        const [left, right] = toggleRef.current;
+        return {
+            set: (value)=>{
+                if (value !== left && value !== right) throwType('useToggle', 'value is not left or right');
+                setState(value);
+            },
+            setLeft: ()=>setState(left),
+            setRight: ()=>setState(right),
+            toggle: ()=>setState((prev)=>prev === left ? right : left)
+        };
+    }, []);
+    return [
+        state,
+        actions
+    ];
+}
+function useBoolean(defaultValue = false) {
+    const [state, { toggle, set }] = useToggle(!!defaultValue);
+    const actions = useMemo(()=>({
+            toggle,
+            setTrue: ()=>set(true),
+            setFalse: ()=>set(false),
+            set: (value)=>set(!!value)
+        }), []);
+    return [
+        state,
+        actions
+    ];
+}
 function useValidData(data, verifyInfo, options) {
     const verifyInfoRef = useRef(verifyInfo);
     const optionsRef = useRef(options);
@@ -84,5 +121,87 @@ function useCounter(initialValue = 0, options = {}) {
         actions
     ];
 }
+function useForceUpdate() {
+    const [, forceUpdate] = useReducer((prev)=>(prev + 1) % 10, 0);
+    return forceUpdate;
+}
+function useMount(callback) {
+    const callbackRef = useRef(callback);
+    useEffect(()=>{
+        dataHandler({
+            fn: callbackRef.current
+        }, {
+            fn: $t["function"]()
+        }, {
+            strict: true
+        });
+        callbackRef.current();
+    }, []);
+}
+function clone(_v) {
+    return structuredClone(_v);
+}
+function useRefState(initialState) {
+    const stateRef = useRef(initialState);
+    const forceUpdate = useForceUpdate();
+    const ctrl = useMemo(()=>{
+        const origin = clone(stateRef.current);
+        const updateHandler = (update = true)=>void (update && forceUpdate());
+        const patchState = (updater, update = true)=>{
+            updater(stateRef.current);
+            updateHandler(update);
+        };
+        const setState = (state, update = true)=>{
+            stateRef.current = state;
+            updateHandler(update);
+        };
+        return {
+            patchState,
+            forceUpdate,
+            getState: ()=>stateRef.current,
+            setState,
+            reset: (update = true)=>setState(clone(origin), update)
+        };
+    }, [
+        forceUpdate
+    ]);
+    return [
+        stateRef.current,
+        ctrl
+    ];
+}
+function useStorage(storageKey, options, initialData) {
+    const optionsRef = useRef({
+        initialData,
+        options
+    });
+    return useMemo(()=>{
+        const { initialData: _initialData, options: _options } = optionsRef.current;
+        return createStorageHandler(storageKey, _initialData || {}, _options);
+    }, [
+        storageKey
+    ]);
+}
+function setTitle(title) {
+    if (!title) return;
+    document.title = title;
+}
+const use_title_validInfo = $dt({
+    restoreOnUnmount: $t.boolean(true)
+});
+function useTitle(title, options = {}) {
+    const { restoreOnUnmount } = useValidData(options, use_title_validInfo);
+    useEffect(()=>{
+        const originalTitle = document.title;
+        setTitle(title);
+        return ()=>{
+            if (restoreOnUnmount) setTitle(originalTitle);
+        };
+    }, [
+        title,
+        restoreOnUnmount
+    ]);
+    return setTitle;
+}
 export { $dt, $t, defineTransform } from "../707.js";
-export { useControllableValue, useCounter, useValidData };
+export { useBoolean, useControllableValue, useCounter, useForceUpdate, useMount, useRefState, useStorage, useTitle, useToggle, useValidData };

package/dist/react/use-force-update/index.d.ts

@@ -0,0 +1 @@
+export declare function useForceUpdate(): import("react").ActionDispatch<[]>;

package/dist/react/use-force-update/index.js

@@ -0,0 +1,6 @@
+import { useReducer } from "react";
+function useForceUpdate() {
+    const [, forceUpdate] = useReducer((prev)=>(prev + 1) % 10, 0);
+    return forceUpdate;
+}
+export { useForceUpdate };

package/dist/react/use-force-update/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/react/use-ref-state/index.d.ts

@@ -0,0 +1,8 @@
+export interface UseRefStateCtrl<T> {
+    patchState: (updater: (draft: T) => void, update?: boolean) => void;
+    forceUpdate: () => void;
+    getState: () => T;
+    setState: (state: T, update?: boolean) => void;
+    reset: (update?: boolean) => void;
+}
+export declare function useRefState<T>(initialState: T): readonly [T, UseRefStateCtrl<T>];

package/dist/react/use-ref-state/index.js

@@ -0,0 +1,35 @@
+import { useMemo, useRef } from "react";
+import { useForceUpdate } from "../use-force-update/index.js";
+function clone(_v) {
+    return structuredClone(_v);
+}
+function useRefState(initialState) {
+    const stateRef = useRef(initialState);
+    const forceUpdate = useForceUpdate();
+    const ctrl = useMemo(()=>{
+        const origin = clone(stateRef.current);
+        const updateHandler = (update = true)=>void (update && forceUpdate());
+        const patchState = (updater, update = true)=>{
+            updater(stateRef.current);
+            updateHandler(update);
+        };
+        const setState = (state, update = true)=>{
+            stateRef.current = state;
+            updateHandler(update);
+        };
+        return {
+            patchState,
+            forceUpdate,
+            getState: ()=>stateRef.current,
+            setState,
+            reset: (update = true)=>setState(clone(origin), update)
+        };
+    }, [
+        forceUpdate
+    ]);
+    return [
+        stateRef.current,
+        ctrl
+    ];
+}
+export { useRefState };

package/dist/react/use-ref-state/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/react/use-storage/index.d.ts

@@ -0,0 +1,2 @@
+import { type CreateStorageOptions } from '../../shared/create-storage-handler';
+export declare function useStorage<T extends Record<string, any>>(storageKey: string, options?: Partial<CreateStorageOptions>, initialData?: T): import("../../shared/create-storage-handler").StorageHandler<T>;

package/dist/react/use-storage/index.js

@@ -0,0 +1,15 @@
+import { useMemo, useRef } from "react";
+import { createStorageHandler } from "../../shared/create-storage-handler/index.js";
+function useStorage(storageKey, options, initialData) {
+    const optionsRef = useRef({
+        initialData,
+        options
+    });
+    return useMemo(()=>{
+        const { initialData: _initialData, options: _options } = optionsRef.current;
+        return createStorageHandler(storageKey, _initialData || {}, _options);
+    }, [
+        storageKey
+    ]);
+}
+export { useStorage };

package/dist/react/use-storage/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/react/use-valid-data/index.d.ts

@@ -1,8 +1,8 @@
 import type { DataHandlerOptions, Handler } from '../../shared/data-handler/types';
 export * from '../../shared/data-handler/tools';
-export declare function useValidData<T extends Record<PropertyKey, any>, O extends DataHandlerOptions<T> = DataHandlerOptions<T> & {
+export declare function useValidData<T extends Record<PropertyKey, any>, H extends Handler<T> = Handler<T>, O extends DataHandlerOptions<T> = DataHandlerOptions<T> & {
     unwrap: true;
-}>(data: T, verifyInfo: Handler<T>, options?: O): O["unwrap"] extends true ? T & O["defaultValue"] : {
-    result: T & O["defaultValue"];
+}>(data: T, verifyInfo: H, options?: O): O["unwrap"] extends true ? import("../../shared").Printify<import("../../shared/data-handler").Transform2Type<H> extends infer T_1 ? T_1 extends import("../../shared/data-handler").Transform2Type<H> ? T_1 extends (...args: any[]) => any ? T & O["defaultValue"] : T & O["defaultValue"] & { [K in keyof T_1]: import("../../shared").Equal<T_1[K], any> extends true ? Required<T & O["defaultValue"]>[K] : T_1[K]; } : never : never> : {
+    result: import("../../shared").Printify<import("../../shared/data-handler").Transform2Type<H> extends infer T_2 ? T_2 extends import("../../shared/data-handler").Transform2Type<H> ? T_2 extends (...args: any[]) => any ? T & O["defaultValue"] : T & O["defaultValue"] & { [K_1 in keyof T_2]: import("../../shared").Equal<T_2[K_1], any> extends true ? Required<T & O["defaultValue"]>[K_1] : T_2[K_1]; } : never : never>;
     errors: string[];
 };

package/dist/shared/animation/__test__/animation-pause-resume.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/animation/__test__/animation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/animation/__test__/step-animation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/animation/__test__/utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/animation/index.d.ts

@@ -0,0 +1,3 @@
+import type { AnimationBaseOptions, AnimationOptions, AnimationResult } from './types';
+export declare function stepAnimation<T>(from: T, to: T, step: number, options?: AnimationBaseOptions): Generator<T, void, unknown>;
+export declare function animation<T>(from: T, to: T, duration: number, options?: AnimationOptions): AnimationResult;

package/dist/shared/animation/index.js

@@ -0,0 +1,71 @@
+import { $dt, $t, dataHandler } from "../data-handler/index.js";
+import { throwError } from "../throw-error/index.js";
+import { createNextTick, createRunningControllerSignal, getNextValueHandler, identity, matchValid, noop } from "./utils.js";
+function* stepAnimation(from, to, step, options = {}) {
+    if (!Number.isInteger(step) || step <= 0) throwError('stepAnimation', 'step must be a positive integer', RangeError);
+    const { parser: valueParser = identity, formatter: valueFormatter = identity } = options;
+    const [validFrom, validTo] = matchValid(from, to, valueParser);
+    const getNextValue = getNextValueHandler(validFrom, validTo, valueFormatter);
+    for(let i = 0; i <= step; i++){
+        const value = getNextValue(i / step);
+        yield value;
+    }
+}
+const validInfo = $dt({
+    autoStart: $t.boolean(true),
+    easing: $t["function"](()=>identity),
+    onStart: $t["function"](()=>noop),
+    onStop: $t["function"](()=>noop),
+    onClear: $t["function"](()=>noop),
+    onUpdate: $t["function"](()=>noop),
+    onComplete: $t["function"](()=>noop),
+    formatter: $t["function"](()=>identity),
+    parser: $t["function"](()=>identity)
+});
+function animation(from, to, duration, options = {}) {
+    if (duration <= 0 || !Number.isInteger(duration)) throwError('animation', 'duration must be a positive integer', RangeError);
+    const validOptions = dataHandler(options, validInfo, {
+        unwrap: true
+    });
+    const [validFrom, validTo] = matchValid(from, to, validOptions.parser);
+    const { autoStart, easing, onComplete, onUpdate, formatter: valueFormatter } = validOptions;
+    const getNextValue = getNextValueHandler(validFrom, validTo, valueFormatter);
+    let startTime = 0;
+    let hasStarted = false;
+    const rcSignal = createRunningControllerSignal(()=>{
+        const now = performance.now();
+        startTime += now;
+        const stopFlag = nextTick(tick);
+        if (stopFlag) {
+            startTime -= performance.now();
+            return;
+        }
+        if (!hasStarted) {
+            onUpdate(getNextValue(0));
+            hasStarted = true;
+        }
+    }, validOptions);
+    const { resolvers } = rcSignal;
+    const nextTick = createNextTick(resolvers, rcSignal);
+    const tick = ()=>{
+        const elapsed = performance.now() - startTime;
+        const progress = easing(Math.min(elapsed / duration, 1));
+        const value = getNextValue(progress);
+        onUpdate(value);
+        if (elapsed < duration) {
+            const stopFlag = nextTick(tick);
+            if (stopFlag) startTime = -elapsed;
+        } else {
+            onComplete();
+            resolvers.resolve(false);
+        }
+    };
+    if (false !== autoStart) rcSignal.start();
+    return {
+        promise: resolvers.promise,
+        stop: rcSignal.stop,
+        start: rcSignal.start,
+        clear: rcSignal.clear
+    };
+}
+export { animation, stepAnimation };

package/dist/shared/animation/types.d.ts

@@ -0,0 +1,22 @@
+export type Formatter = (value: number) => any;
+export interface AnimationBaseOptions {
+    parser?: (value: any) => number;
+    formatter?: Formatter;
+}
+export interface AnimationOptions extends AnimationBaseOptions {
+    autoStart?: boolean;
+    easing?: (time: number) => number;
+    onStart?: () => void;
+    onStop?: () => void;
+    onClear?: () => void;
+    onUpdate?: (value: any) => void;
+    onComplete?: () => void;
+}
+export interface AnimationCtrl {
+    stop: () => void;
+    start: () => void;
+    clear: () => void;
+}
+export type AnimationResult = AnimationCtrl & {
+    promise: Promise<boolean>;
+};

package/dist/shared/animation/utils.d.ts

@@ -0,0 +1,16 @@
+import { type Resolver } from '../with-resolvers';
+import type { AnimationOptions, Formatter } from './types';
+export declare const noop: () => undefined;
+export declare const identity: <T>(_v: T) => T;
+export declare function getNextValueHandler(from: any, to: any, valueFormatter: Formatter): (progress: number) => any;
+export declare function matchValid(from: any, to: any, valueParser: (value: any) => number): number[] | unknown[][] | [Record<PropertyKey, any>, Record<PropertyKey, any>];
+export declare function createNextTick(resolvers: Resolver<any>, rcSignal: RCSignal): (callback: (...args: any[]) => void) => boolean;
+export declare function tryRun(callback: () => any, resolvers: Resolver<any>, customErrorHandler?: (err: any) => void): Promise<void>;
+export declare function createRunningControllerSignal(startFn: () => void, options: Required<AnimationOptions>): {
+    stopSignal: boolean;
+    resolvers: Resolver<boolean>;
+    stop: () => void;
+    start: () => void;
+    clear: () => void;
+};
+export type RCSignal = Omit<ReturnType<typeof createRunningControllerSignal>, 'resolvers'>;

package/dist/shared/animation/utils.js

@@ -0,0 +1,138 @@
+import { throwType } from "../throw-error/index.js";
+import { withResolvers } from "../with-resolvers/index.js";
+const noop = ()=>void 0;
+const identity = (_v)=>_v;
+function getType(_v) {
+    return Object.prototype.toString.call(_v).slice(8, -1).toLowerCase();
+}
+function getNextValueHandler(from, to, valueFormatter) {
+    const type = getType(from);
+    const context = {
+        progress: 0,
+        valueFormatter
+    };
+    const baseNextValue = (_from, _to)=>{
+        const { valueFormatter: formatter, progress } = context;
+        if ('number' !== getType(_from)) return _from;
+        return formatter(_from + (_to - _from) * progress);
+    };
+    const arrayHandler = (_from, _to)=>{
+        const result = Array.from(_from, (item, idx)=>{
+            if (Array.isArray(item)) return arrayHandler(item, _to[idx]);
+            if ('object' === getType(item)) return objectHandler(item, _to[idx]);
+            return baseNextValue(item, _to[idx]);
+        });
+        return result;
+    };
+    const objectHandler = (_from, _to)=>{
+        const result = {};
+        const keys = Reflect.ownKeys(_from);
+        for(let i = 0; i < keys.length; i++){
+            const key = keys[i];
+            const fromValue = _from[key];
+            const toValue = _to[key];
+            if (Array.isArray(_from[key])) result[key] = arrayHandler(fromValue, toValue);
+            else if ('object' === getType(fromValue)) result[key] = objectHandler(fromValue, toValue);
+            else result[key] = baseNextValue(fromValue, toValue);
+        }
+        return result;
+    };
+    let nextValueHandler = baseNextValue;
+    if ('array' === type) nextValueHandler = arrayHandler;
+    else if ('object' === type) nextValueHandler = objectHandler;
+    return (progress)=>{
+        context.progress = progress;
+        return nextValueHandler(from, to);
+    };
+}
+function matchValid(from, to, valueParser) {
+    const fromType = getType(from);
+    const toType = getType(to);
+    if (fromType !== toType) throwType('animation/stepAnimation', 'from and to must be the same type');
+    if ('array' === fromType) {
+        if (from.length !== to.length) throwType('animation/stepAnimation', 'from and to must be the same length');
+        const result = [
+            Array.from({
+                length: from.length
+            }),
+            Array.from({
+                length: to.length
+            })
+        ];
+        for(let i = 0; i < from.length; i++){
+            const [fromItem, toItem] = matchValid(from[i], to[i], valueParser);
+            result[0][i] = fromItem;
+            result[1][i] = toItem;
+        }
+        return result;
+    }
+    if ('object' === fromType) {
+        const toKeys = Reflect.ownKeys(to);
+        const fromKeys = new Set(Reflect.ownKeys(from));
+        const result = [
+            {},
+            {}
+        ];
+        for(let i = 0; i < toKeys.length; i++){
+            const key = toKeys[i];
+            if (!fromKeys.has(key)) throwType('animation/stepAnimation', `from does not have this key: ${String(key)}`);
+            const [fromItem, toItem] = matchValid(from[key], to[key], valueParser);
+            result[0][key] = fromItem;
+            result[1][key] = toItem;
+        }
+        return result;
+    }
+    if ('number' !== fromType) return [
+        valueParser(from),
+        valueParser(to)
+    ];
+    return [
+        from,
+        to
+    ];
+}
+function createNextTick(resolvers, rcSignal) {
+    const nextTick = (()=>{
+        if ('function' == typeof globalThis.requestAnimationFrame) return globalThis.requestAnimationFrame;
+        return (callback)=>setTimeout(callback, 16);
+    })();
+    return (callback)=>{
+        if (rcSignal.stopSignal) return true;
+        nextTick(()=>tryRun(callback, resolvers, (error)=>{
+                rcSignal.stop();
+                resolvers.reject(error);
+            }));
+        return false;
+    };
+}
+async function tryRun(callback, resolvers, customErrorHandler) {
+    return new Promise((resolve, reject)=>{
+        const result = callback();
+        if (result && 'function' == typeof result.then) return result.then(resolve, reject);
+        resolve();
+    }).catch(customErrorHandler || resolvers.reject);
+}
+function createRunningControllerSignal(startFn, options) {
+    const { onStart, onStop, onClear } = options;
+    const resolvers = withResolvers();
+    const ctrl = {
+        stopSignal: true,
+        resolvers,
+        stop: ()=>{
+            ctrl.stopSignal = true;
+            onStop();
+        },
+        start: ()=>{
+            ctrl.stopSignal = false;
+            onStart();
+            startFn();
+        },
+        clear: ()=>{
+            ctrl.stopSignal = true;
+            onClear();
+            resolvers.resolve(true);
+        }
+    };
+    return ctrl;
+}
+export { createNextTick, createRunningControllerSignal, getNextValueHandler, identity, matchValid, noop, tryRun };

package/dist/shared/condition-merge/index.d.ts

@@ -1,4 +1,4 @@
-import type { IsPrimitive, UnionToIntersection } from '../types';
+import type { IsPrimitive, Printify, UnionToIntersection } from '../types';
 type AssertValue = Record<PropertyKey, any> | any[];
 type ConditionArrayItem = [boolean, AssertValue, AssertValue?];
 type ConditionObjItem = {
@@ -25,11 +25,7 @@ type MergedResult<T extends ConditionItem[]> = T extends [
     ...infer Last extends [ConditionItem, ...ConditionItem[]]
 ] ? ParseConditionValue<First> & MergedResult<Last> : ParseConditionValue<T[0]>;
 type CMInput = ConditionItem[];
-type Printify<T> = T extends any[] ? T : [T] extends [never] ? T : {
-    [K in keyof T]: T[K];
-};
 type FormatResult<T extends any[]> = T[0] & Record<PropertyKey, any>;
 export declare function conditionMerge<T extends CMInput>(...input: T): FormatResult<MergedResult<T>>;
 export declare function conditionMerge<T extends CMInput>(input: T): FormatResult<MergedResult<T>>;
 export {};
-t {};

package/dist/shared/create-storage-handler/index.browser.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/create-storage-handler/index.d.ts

@@ -0,0 +1,10 @@
+export interface CreateStorageOptions {
+    storageType: 'local' | 'session' | 'memory';
+    autoSaveInterval: number;
+}
+export interface StorageHandler<T extends Record<string, any>> {
+    get: <K extends keyof T | (string & {})>(key?: K) => string extends K ? T : T[K & keyof T];
+    set: <K extends keyof T | (string & {})>(value: string extends K ? T : T[K & keyof T], key?: K) => void;
+    clear: () => void;
+}
+export declare function createStorageHandler<T extends Record<string, any>>(storageKey: string, initialData?: T, options?: Partial<CreateStorageOptions>): StorageHandler<T>;

package/dist/shared/create-storage-handler/index.js

@@ -0,0 +1,68 @@
+import { $dt, $t, dataHandler } from "../data-handler/index.js";
+import { logger } from "../logger/index.js";
+import { throwError } from "../throw-error/index.js";
+const validInfo = $dt({
+    storageKey: 'validString',
+    storageType: $t["enum"]([
+        'local',
+        'session',
+        'memory'
+    ], 'local'),
+    autoSaveInterval: $t.number(0)
+});
+const memoryStorage = {
+    data: {},
+    getItem (key) {
+        return this.data[key];
+    },
+    setItem (key, value) {
+        this.data[key] = value;
+    },
+    removeItem (key) {
+        delete this.data[key];
+    }
+};
+function getStorage(storageType) {
+    try {
+        if ('memory' === storageType) return memoryStorage;
+        return 'local' === storageType ? localStorage : sessionStorage;
+    } catch  {
+        logger.warn('createStorage', 'Failed to access localStorage or sessionStorage, using memoryStorage instead.');
+        return memoryStorage;
+    }
+}
+const CLEAR_FLAG = Symbol('cleared');
+function createStorageHandler(storageKey, initialData, options = {}) {
+    const { storageKey: validStorageKey, storageType, autoSaveInterval } = dataHandler({
+        storageKey,
+        ...options
+    }, validInfo, {
+        unwrap: true
+    });
+    const storage = getStorage(storageType);
+    const storageData = storage.getItem(validStorageKey);
+    const context = {
+        data: storageData ? JSON.parse(storageData) : initialData || {}
+    };
+    return {
+        get (key) {
+            if (context.data === CLEAR_FLAG) throwError('createStorageHandler', 'Storage has been cleared.');
+            if (null == key) return context.data;
+            return context.data[key];
+        },
+        set (value, key) {
+            if (context.data === CLEAR_FLAG) throwError('createStorageHandler', 'Storage has been cleared.');
+            if (null == key) context.data = value;
+            else context.data[key] = value;
+            if (autoSaveInterval > 0) setTimeout(()=>{
+                storage.setItem(validStorageKey, JSON.stringify(context.data));
+            }, autoSaveInterval);
+            else storage.setItem(validStorageKey, JSON.stringify(context.data));
+        },
+        clear () {
+            context.data = CLEAR_FLAG;
+            storage.removeItem(validStorageKey);
+        }
+    };
+}
+export { createStorageHandler };

package/dist/shared/create-storage-handler/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/data-handler/index.d.ts

@@ -1,6 +1,11 @@
+import type { Equal, Printify } from '../types';
+import type { Transform2Type } from './tools';
 import type { DataHandlerOptions, Handler } from './types';
-export declare function dataHandler<M extends Record<PropertyKey, any>, O extends DataHandlerOptions<M> = DataHandlerOptions<M>>(data: M & Partial<O['defaultValue']>, handler: Handler<M>, options?: O): O['unwrap'] extends true ? M & O['defaultValue'] : {
-    result: M & O['defaultValue'];
+type MergeResult<BaseResult extends Record<PropertyKey, any>, HandlerResult extends Handler<any>> = Printify<HandlerResult extends (...args: any[]) => any ? BaseResult : BaseResult & {
+    [K in keyof HandlerResult]: Equal<HandlerResult[K], any> extends true ? Required<BaseResult>[K] : HandlerResult[K];
+}>;
+export declare function dataHandler<M extends Record<PropertyKey, any>, H extends Handler<M> = Handler<M>, O extends DataHandlerOptions<M> = DataHandlerOptions<M>>(data: M & Partial<O['defaultValue']>, handler: H, options?: O): O['unwrap'] extends true ? MergeResult<M & O['defaultValue'], Transform2Type<H>> : {
+    result: MergeResult<M & O['defaultValue'], Transform2Type<H>>;
     errors: string[];
 };
 export * from './tools';

package/dist/shared/data-handler/tools.d.ts

@@ -1,18 +1,42 @@
 import type { Handler } from './types';
 type TypeHandler = NonNullable<Exclude<Handler<any>, (...args: any[]) => any>[string]>;
-type Fullback = ((_v: any) => any) | (any & {});
+type TypeHandlerParams = Parameters<TypeHandler> extends [any, ...infer Rest] ? Rest : never;
+type ParseType<T extends string> = T extends keyof TypeMap ? TypeMap[T] : any;
+type TypeHandlerInfo<T extends string> = (value: ParseType<T>, ...args: TypeHandlerParams) => ReturnType<TypeHandler>;
+interface TypeMap {
+    notNullable: any & {};
+    string: string;
+    validString: string;
+    number: number;
+    validNumber: number;
+    boolean: boolean;
+    object: Record<PropertyKey, any>;
+    array: any[];
+    function: (...args: any[]) => any;
+    symbol: symbol;
+    enum: any & {};
+}
 export declare const $t: {
-    notNullable: (fullback?: Fullback) => TypeHandler;
-    string: (fullback?: Fullback) => TypeHandler;
-    validString: (fullback?: Fullback) => TypeHandler;
-    number: (fullback?: Fullback) => TypeHandler;
-    validNumber: (fullback?: Fullback) => TypeHandler;
-    boolean: (fullback?: Fullback) => TypeHandler;
-    object: (fullback?: Fullback) => TypeHandler;
-    array: (fullback?: Fullback) => TypeHandler;
-    function: (fullback?: Fullback) => TypeHandler;
-    symbol: (fullback?: Fullback) => TypeHandler;
+    notNullable: (fullback?: any) => TypeHandlerInfo<"notNullable">;
+    string: (fullback?: string | ((_v: any) => string) | undefined) => TypeHandlerInfo<"string">;
+    validString: (fullback?: string | ((_v: any) => string) | undefined) => TypeHandlerInfo<"validString">;
+    number: (fullback?: number | ((_v: any) => number) | undefined) => TypeHandlerInfo<"number">;
+    validNumber: (fullback?: number | ((_v: any) => number) | undefined) => TypeHandlerInfo<"validNumber">;
+    boolean: (fullback?: boolean | ((_v: any) => boolean) | undefined) => TypeHandlerInfo<"boolean">;
+    object: (fullback?: Record<PropertyKey, any> | ((_v: any) => Record<PropertyKey, any>) | undefined) => TypeHandlerInfo<"object">;
+    array: (fullback?: any[] | ((_v: any) => any[]) | undefined) => TypeHandlerInfo<"array">;
+    function: (fullback?: ((_v: any) => (...args: any[]) => any) | undefined) => TypeHandlerInfo<"function">;
+    symbol: (fullback?: symbol | ((_v: any) => symbol) | undefined) => TypeHandlerInfo<"symbol">;
+    enum: <T>(list: T[], fullback?: T) => TypeHandlerInfo<"enum">;
 };
-export declare function defineTransform<T extends Record<PropertyKey, any>>(dataInfo: Partial<Record<keyof T, keyof typeof $t | TypeHandler>>): Record<PropertyKey, (value: any, action: import("./types").Actions, option: any) => false | (any & {})>;
+type TransformMap = typeof $t;
+type TransformKey = Exclude<keyof TransformMap, 'enum'>;
+type DataTransformResult<D extends Record<PropertyKey, TransformKey | TypeHandler | undefined>> = {
+    [K in keyof D]: D[K] extends TransformKey ? TransformMap[D[K]] : D[K];
+};
+export type Transform2Type<R extends DataTransformResult<any>> = {
+    [K in keyof R]: R[K] extends TypeHandlerInfo<infer T> ? ParseType<T> & {} : any & {};
+};
+export declare function defineTransform<T extends Record<PropertyKey, any>, D extends Partial<Record<keyof T, TransformKey | TypeHandler>> = Partial<Record<keyof T, TransformKey | TypeHandler>>>(dataInfo: D): DataTransformResult<D>;
 export declare const $dt: typeof defineTransform;
 export {};

package/dist/shared/data-handler/tools.js

@@ -1,4 +1,5 @@
 import { logger } from "../logger/index.js";
+import { throwType } from "../throw-error/index.js";
 function getType(_v) {
     return Object.prototype.toString.call(_v).slice(8, -1).toLowerCase();
 }
@@ -21,7 +22,12 @@ const $t = {
     object: typeHandler('object'),
     array: typeHandler('array'),
     function: typeHandler('function'),
-    symbol: typeHandler('symbol')
+    symbol: typeHandler('symbol'),
+    enum: (list, fullback)=>{
+        if (!Array.isArray(list)) throwType('$t.enum', 'list must be an array');
+        const set = new Set(list);
+        return typeHandler('enum', (_v)=>set.has(_v))(fullback);
+    }
 };
 function defineTransform(dataInfo) {
     const verifyInfo = {};

package/dist/shared/data-handler/types.d.ts

@@ -8,8 +8,8 @@ export interface Actions {
     transform: <T>(value: T) => T;
 }
 export type Handler<M extends Record<PropertyKey, any>> = Partial<{
-    [K in keyof M]: (value: M[K], action: Actions, option: M) => false | (any & {});
-}> | (<K extends keyof M>(value: M[K], key: K, action: Actions, option: M) => false | (any & {}));
+    [K in keyof M]: (value: any, action: Actions, option: M) => false | (any & {});
+}> | (<K extends keyof M>(value: any, key: K, action: Actions, option: M) => false | (any & {}));
 export interface ActionContext {
     errors: string[];
     transforms: [PropertyKey, any][];

package/dist/shared/index.d.ts

@@ -1,2 +1,7 @@
+export * from './animation';
+export * from './condition-merge';
+export * from './create-storage-handler';
 export * from './data-handler';
 export * from './throw-error';
+export * from './types';
+export * from './with-resolvers';

package/dist/shared/index.js

@@ -1 +1,2 @@
 export { $dt, $t, dataHandler, defineTransform, throwError, throwType } from "../707.js";
+export { animation, conditionMerge, createStorageHandler, stepAnimation, withResolvers } from "../607.js";

package/dist/shared/types/base.d.ts

@@ -3,3 +3,6 @@ export type NonUnion<T> = Equal<[T] extends [never] ? never : T[], T extends any
 export type UnionToIntersection<U> = [U] extends [never] ? never : (U extends any ? (_v: U) => void : never) extends (_v: infer I) => void ? I : never;
 export type IsPrimitive<T> = T extends number | string | boolean | symbol | bigint | null | undefined ? true : false;
 export type IsBasicType<T> = T extends number | string | boolean | symbol | bigint ? true : false;
+export type Printify<T> = T extends any[] ? T : [T] extends [never] ? T : {
+    [K in keyof T]: T[K];
+};

package/dist/shared/with-resolvers/index.d.ts

@@ -0,0 +1,6 @@
+export type Resolver<T> = {
+    promise: Promise<T>;
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (reason?: any) => void;
+};
+export declare function withResolvers<T>(): Resolver<T>;

package/dist/shared/with-resolvers/index.js

@@ -0,0 +1,15 @@
+function withResolvers() {
+    return 'function' == typeof Promise.withResolvers ? Promise.withResolvers() : (()=>{
+        const resolver = {
+            promise: null,
+            resolve: null,
+            reject: null
+        };
+        resolver.promise = new Promise((resolve, reject)=>{
+            resolver.resolve = resolve;
+            resolver.reject = reject;
+        });
+        return resolver;
+    })();
+}
+export { withResolvers };

package/dist/shared/with-resolvers/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/utils.d.ts

@@ -0,0 +1,13 @@
+import { Component, type PropsWithChildren } from 'react';
+export declare class ErrorBoundary extends Component<PropsWithChildren<{
+    onError: () => void;
+}>> {
+    state: {
+        hasError: boolean;
+    };
+    static getDerivedStateFromError(): {
+        hasError: boolean;
+    };
+    componentDidCatch(): void;
+    render(): import("react").ReactNode;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cmtlyt/lingshu-toolkit",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "main": "./dist/shared.js",
   "module": "./dist/shared.js",
@@ -52,10 +52,12 @@
     "@vitest/browser-playwright": "4.0.18",
     "@vitest/coverage-v8": "4.0.18",
     "@vitest/ui": "4.0.18",
+    "cross-env": "^10.1.0",
     "esno": "^4.8.0",
     "husky": "^9.1.7",
     "jsdom": "^27.4.0",
     "lint-staged": "^16.2.7",
+    "playwright": "^1.58.1",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "rspress": "^1.47.1",
@@ -115,9 +117,9 @@
     "dev:registry": "pnpm dlx serve src/public -p 3000",
     "preview:docs": "rspress preview",
     "format": "biome format --write",
-    "test": "vitest --config=vitest.browser.config.ts --coverage.enabled --ui",
-    "test:ci": "vitest run --config=vitest.browser.config.ts",
-    "test:lib:ci": "vitest run",
+    "test": "vitest --config=vitest.project.config.ts --coverage.enabled --ui",
+    "test:ci": "cross-env gen_file_disabled=true vitest run --config=vitest.project.config.ts",
+    "test:lib:ci": "cross-env gen_file_disabled=true vitest run",
     "test:lib": "vitest --coverage.enabled --ui",
     "script:gen-file": "esno scripts/gen-file.ts"
   }