@ringcentral/spring-base 1.7.0 → 1.8.0

package/hooks.js

@@ -15,18 +15,11 @@ import throttle from 'lodash/throttle';
 import { disableBodyScroll, enableBodyScroll } from 'body-scroll-lock';
 import 'tailwind-merge';
 
-// this file template replace material-ui/core/utils method
-// when upgrade mui that will not need assign type anymore
 const useEventCallback = (func) => {
     return unstable_useEventCallback(func);
 };
 
 const defaultCheckKeys = ['Enter', ' '];
-/**
- * bind event with a11y keyboard, `space`, `enter`, only trigger when key includes in `checkKeys`
- *
- * that will auto preventDefault by default, if you don't want that, set `false` with `preventDefault`
- */
 const useA11yKeyEvent = (fn, { onlyOnFocus, preventDefault = true, checkKeys = defaultCheckKeys, } = {}) => {
     return useEventCallback((event) => {
         if (!fn || (onlyOnFocus && event.target !== event.currentTarget))
@@ -39,7 +32,6 @@ const useA11yKeyEvent = (fn, { onlyOnFocus, preventDefault = true, checkKeys = d
     });
 };
 
-// base https://github.com/mui/material-ui/blob/master/packages/mui-base/src/useButton/useButton.ts
 const isNativeButton = (el) => {
     const tag = el.tagName;
     return (tag === 'BUTTON' ||
@@ -47,11 +39,6 @@ const isNativeButton = (el) => {
             ['button', 'submit', 'reset'].includes(el?.type)) ||
         (tag === 'A' && el?.href));
 };
-/**
- * bind event with a11y keyboard, `space`. help not native button to implement `:active`
- *
- * that will auto preventDefault by default, if you don't want that, set `false` with `preventDefault`
- */
 const useActive = ({ onKeyDown, onKeyUp, onClick, disabled = false, } = {}) => {
     const [active, setActive] = useState(false);
     useEffect(() => {
@@ -77,7 +64,6 @@ const useActive = ({ onKeyDown, onKeyUp, onClick, disabled = false, } = {}) => {
         if (event.target === event.currentTarget && event.key === ' ') {
             setActive(true);
         }
-        // Keyboard accessibility for non interactive elements
         if (event.target === event.currentTarget &&
             !isNativeButton(event.target) &&
             event.key === 'Enter') {
@@ -86,13 +72,10 @@ const useActive = ({ onKeyDown, onKeyUp, onClick, disabled = false, } = {}) => {
         }
     };
     const handleKeyUp = (event) => {
-        // calling preventDefault in keyUp on a <button> will not dispatch a click event if Space is pressed
-        // https://codesandbox.io/s/button-keyup-preventdefault-dn7f0
         if (event.target === event.currentTarget) {
             setActive(false);
         }
         onKeyUp?.(event);
-        // Keyboard accessibility for non interactive elements
         if (event.target === event.currentTarget &&
             !isNativeButton(event.target) &&
             event.key === ' ' &&
@@ -106,14 +89,6 @@ const useActive = ({ onKeyDown, onKeyUp, onClick, disabled = false, } = {}) => {
     };
 };
 
-/**
- * provide a ref for only calculate `cb` once
- * prevent `useRef(getValue())`, that `getValue` calculate every re-render
- *
- * @param cb that get method of get this ref init value, only calculate once
- * @returns same as `useRef` result
- *
- */
 function useResultRef(cb) {
     const renderRef = useRef(0);
     const ref = useRef();
@@ -125,20 +100,6 @@ function useResultRef(cb) {
 }
 
 const DEFAULT_PREFIX = 'spring-id-';
-/**
- * Generates a unique ID.
- *
- * @param id - Default component id or prefix id.
- * @param prefixMode Whether enable prefix the ID with.
- * @returns unique ID
- * @example
- * useId() => 'spring-id-xxxx'
- * useId('') => 'spring-id-xxxx'
- * useId(null) => 'spring-id-xxxx'
- * useId(undefined) => 'spring-id-xxxx'
- * useId('nameId') => 'nameId'
- * useId('nameId', true) => 'nameId-xxxx'
- */
 function useId(id, prefixMode) {
     const { current: resultId } = useResultRef(() => {
         if (id) {
@@ -161,16 +122,6 @@ const visuallyHiddenStyles = `
   white-space: nowrap;
   width: 1px;
 `;
-/**
- * read announce when need read message.
- *
- * @example
- * ```ts
- *   const announce = useAnnouncer('simpleId');
- *
- *   announce(`You click "Announce" button`);
- * ```
- */
 const useAnnouncer = (id) => {
     const _id = useId(id ? `rc-announcer-${id}` : 'rc-announcer', !id);
     const ref = useRef(null);
@@ -195,7 +146,6 @@ const useAnnouncer = (id) => {
             });
         };
     }, [_id]);
-    /** announce method, call with message that want let reader speak */
     return useCallback((message) => {
         const el = ref.current;
         if (el && message) {
@@ -217,34 +167,10 @@ const useAriaHideOutside = (props = {}) => {
     }, [enable, externalWindow, document?.body]);
     return {
         ariaHideOutsideRef: ariaHideOutsideRef,
-        /**
-         * Whether the `aria-hidden` attribute is being applied to outside elements.
-         * When true, elements outside the ref are hidden from screen readers.
-         */
         ariaHideEnabled: enable,
     };
 };
 
-/**
- * get Browser `Audio` instance, and auto destroy when component be destroyed.
- *
- *
- * @param init a callback when you init that audio
- *
- * @example
- *
- * ```ts
- * const audio = useAudio((instance) => {
- *   instance.src = 'https://your.audio'
- * });
- *
- * const click = () => audio.play();
- *
- * click();
- * ```
- * @see stories {@link https://develop-rcui-int.fiji.gliprc.com/?path=/story/%F0%9F%94%A7-foundation-hooks-useaudio--simple-announcer 🔧-foundation-hooks-useaudio--simple-announcer}
- * @see {@link https://chromium-review.googlesource.com/c/chromium/src/+/2816118}
- */
 const useAudio = (init) => {
     const audioRef = useResultRef(() => {
         const audio = new Audio();
@@ -254,20 +180,12 @@ const useAudio = (init) => {
     useEffect(() => {
         return () => {
             audioRef.current.srcObject = null;
-            // just for remove ref, confirm browser GC work correctly
             audioRef.current = null;
         };
-        // eslint-disable-next-line react-hooks/exhaustive-deps
     }, []);
     return audioRef.current;
 };
 
-/**
- * get previous render value
- * @param cb that get method of target value
- * @param isDefault if set `true`, the first time will get value from `cb`
- * @returns previous value get from `cb`
- */
 function usePrevious(cb, isDefault) {
     const ref = useRef(isDefault ? cb() : undefined);
     useEffect(() => {
@@ -276,11 +194,6 @@ function usePrevious(cb, isDefault) {
     return ref.current;
 }
 
-/**
- * get value when prev listen value change
- * @param cb that method you want calculate to get value
- * @param listenCb prev compare listener value
- */
 const useChange = (cb, listenCb) => {
     const countRef = useRef(0);
     const valueRef = useRef();
@@ -292,11 +205,6 @@ const useChange = (cb, listenCb) => {
     }
     return valueRef.current;
 };
-/**
- * get value when prev deps one of array value change
- * @param cb that method you want calculate to get value
- * @param deps prev compare value array
- */
 const useDepsChange = (cb, deps) => {
     const countRef = useRef(0);
     const valueRef = useRef();
@@ -310,24 +218,16 @@ const useDepsChange = (cb, deps) => {
     return valueRef.current;
 };
 
-// base https://github.com/mui/material-ui/blob/master/packages/mui-base/src/ClickAwayListener/ClickAwayListener.tsx
 function clickedRootScrollbar(event, doc) {
     return (doc.documentElement.clientWidth < event.clientX ||
         doc.documentElement.clientHeight < event.clientY);
 }
-/**
- * @deprecated Use `ClickAwayListener` from `@mui/base` instead.
- *
- * @param onClickAway Callback fired when a "click away" event is detected.
- */
 const useClickAway = (onClickAway, props = {}) => {
     const { disableReactTree = false, isEnabled = true } = props;
     const movedRef = useRef(false);
     const activatedRef = useRef(false);
     const syntheticEventRef = useRef(false);
     const [target, setTarget] = useState();
-    // This hook is usually triggered after target appears
-    // so we need to trigger re-render component in ref callback to make sure useEffect can get target correctly
     const clickAwayRef = useEventCallback((e) => {
         setTarget(e);
     });
@@ -336,8 +236,6 @@ const useClickAway = (onClickAway, props = {}) => {
         if (!isEnabled)
             return;
         if (shouldActive) {
-            // Ensure that this component is not "activated" synchronously.
-            // https://github.com/facebook/react/issues/20074
             const timer = setTimeout(() => {
                 activatedRef.current = true;
             }, 0);
@@ -348,50 +246,32 @@ const useClickAway = (onClickAway, props = {}) => {
         }
         return undefined;
     }, [isEnabled, shouldActive]);
-    // The handler doesn't take event.defaultPrevented into account:
-    //
-    // event.preventDefault() is meant to stop default behaviors like
-    // clicking a checkbox to check it, hitting a button to submit a form,
-    // and hitting left arrow to move the cursor in a text input etc.
-    // Only special HTML elements have these default behaviors.
     const handleClickAway = useEventCallback((event) => {
-        // Given developers can stop the propagation of the synthetic event,
-        // we can only be confident with a positive value.
         const insideReactTree = syntheticEventRef.current;
         syntheticEventRef.current = false;
         const doc = unstable_ownerDocument(target);
-        // 1. IE11 support, which trigger the handleClickAway even after the unbind
-        // 2. The child might render null.
-        // 3. Behave like a blur listener.
         if (!activatedRef.current ||
             !target ||
             ('clientX' in event && clickedRootScrollbar(event, doc))) {
             return;
         }
-        // Do not act if user performed touchmove
         if (movedRef.current) {
             movedRef.current = false;
             return;
         }
         let insideDOM;
-        // If not enough, can use https://github.com/DieterHolvoet/event-propagation-path/blob/master/propagationPath.js
         if (event.composedPath) {
             insideDOM = event.composedPath().indexOf(target) > -1;
         }
         else {
             insideDOM =
-                !doc.documentElement.contains(
-                // @ts-expect-error returns `false` as intended when not dispatched from a Node
-                event.target) ||
-                    target.contains(
-                    // @ts-expect-error returns `false` as intended when not dispatched from a Node
-                    event.target);
+                !doc.documentElement.contains(event.target) ||
+                    target.contains(event.target);
         }
         if (!insideDOM && (disableReactTree || !insideReactTree)) {
             onClickAway(event);
         }
     });
-    // Keep track of mouse/touch events that bubbled up through the portal.
     const handleSynthetic = (e) => {
         syntheticEventRef.current = true;
     };
@@ -423,37 +303,13 @@ const useClickAway = (onClickAway, props = {}) => {
     };
 };
 
-/**
- * provide a debounce method for debounce method
- * @param fn method for debounce
- * @param debounceTime debounce timeout value, default is  `200`ms
- * @param options debounce setting, default is  `{trailing: true, leading: flase}`, detail see lodash
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 const useDebounce = (fn, debounceTime = 200, options) => {
     const memoFn = useEventCallback(fn);
-    // eslint-disable-next-line react-hooks/exhaustive-deps
     const debounceFn = useCallback(debounce(memoFn, debounceTime, options), []);
-    // eslint-disable-next-line react-hooks/exhaustive-deps
     useEffect(() => () => debounceFn.cancel(), []);
     return debounceFn;
 };
 
-/**
- * bind event when component mount and auto remove event when destroy.
- * can remove listener by call returned function or pass empty 'target'.
- *
- * @param target
- * listener will be removed when target is changed to null,
- * or rebinding to new element when `ref.current` change
- * @returns a method object
- * - listen() listen listener again, if that have listener, that will not listen again
- * - remove() remove listener
- * @example
- * ```ts
- * useEventListener(window, 'keyup', () => console.log('window key up'))
- * ```
- */
 function useEventListener(target, key, callback, options) {
     const { startImmediately = true, ...addEventListenerOptions } = options ?? {};
     const listener = useEventCallback(callback);
@@ -472,7 +328,6 @@ function useEventListener(target, key, callback, options) {
             bindRef.current();
         }
         return cancelRef.current;
-        // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [target]);
     return {
         listen: () => bindRef.current(),
@@ -481,27 +336,7 @@ function useEventListener(target, key, callback, options) {
 }
 
 const defaultEverTargetValue = (value) => !!value;
-/**
- * that value ever to be `you want value`
- * Return true when the value ever to be `you want value` once.
- *
- * @example
- * ```ts
- * // once that isOpen is true, that result will always be `true`
- * const isEverOpen = useEver(isOpen);
- *
- * const isEverToBe2 = useEver(count, (val) => val === 2);
- * ```
- */
-const useEver = (
-/** to be checked value */
-value, 
-/**
- * value ever to be callback, default when value to be exited.
- *
- * @default (value) => !!value
- */
-targetValue = defaultEverTargetValue) => {
+const useEver = (value, targetValue = defaultEverTargetValue) => {
     const result = useRef(false);
     if (!result.current) {
         result.current = targetValue(value);
@@ -509,8 +344,6 @@ targetValue = defaultEverTargetValue) => {
     return result.current;
 };
 
-/* eslint-disable sonarjs/no-collapsible-if */
-/* eslint-disable sonarjs/prefer-single-boolean-return */
 let hadKeyboardEvent = true;
 let hadFocusVisibleRecently = false;
 const hadFocusVisibleRecentlyTimeout = new unstable_Timeout();
@@ -529,13 +362,6 @@ const inputTypesWhitelist = {
     datetime: true,
     'datetime-local': true,
 };
-/**
- * Computes whether the given element should automatically trigger the
- * `focus-visible` class being added, i.e. whether it should always match
- * `:focus-visible` when focused.
- * @param {Element} node
- * @returns {boolean}
- */
 function focusTriggersKeyboardModality(node) {
     const { type, tagName } = node;
     if (tagName === 'INPUT' &&
@@ -551,35 +377,17 @@ function focusTriggersKeyboardModality(node) {
     }
     return false;
 }
-/**
- * Keep track of our keyboard modality state with `hadKeyboardEvent`.
- * If the most recent user interaction was via the keyboard;
- * and the key press did not include a meta, alt/option, or control key;
- * then the modality is keyboard. Otherwise, the modality is not keyboard.
- * @param {KeyboardEvent} event
- */
 function handleKeyDown(event) {
     if (event.metaKey || event.altKey || event.ctrlKey) {
         return;
     }
     hadKeyboardEvent = true;
 }
-/**
- * If at any point a user clicks with a pointing device, ensure that we change
- * the modality away from keyboard.
- * This avoids the situation where a user presses a key on an already focused
- * element, and then clicks on a different element, focusing it with a
- * pointing device, while we still think we're in keyboard modality.
- */
 function handlePointerDown() {
     hadKeyboardEvent = false;
 }
 function handleVisibilityChange() {
     if (this.visibilityState === 'hidden') {
-        // If the tab becomes active again, the browser will handle calling focus
-        // on the element (Safari actually calls it twice).
-        // If this tab change caused a blur on an element with focus-visible,
-        // re-apply the class when the user switches back to the tab.
         if (hadFocusVisibleRecently) {
             hadKeyboardEvent = true;
         }
@@ -605,13 +413,7 @@ function isFocusVisible(event) {
         return target.matches(':focus-visible');
     }
     catch (error) {
-        // Browsers not implementing :focus-visible will throw a SyntaxError.
-        // We use our own heuristic for those browsers.
-        // Rethrow might be better if it's not the expected error but do we really
-        // want to crash if focus-visible malfunctioned?
     }
-    // No need for validFocusTarget check. The user does that by attaching it to
-    // focusable events only.
     return hadKeyboardEvent || focusTriggersKeyboardModality(target);
 }
 function useIsFocusVisible() {
@@ -621,20 +423,8 @@ function useIsFocusVisible() {
         }
     }, []);
     const isFocusVisibleRef = React.useRef(false);
-    /**
-     * Should be called if a blur event is fired
-     */
     function handleBlurVisible() {
-        // checking against potential state variable does not suffice if we focus and blur synchronously.
-        // React wouldn't have time to trigger a re-render so `focusVisible` would be stale.
-        // Ideally we would adjust `isFocusVisible(event)` to look at `relatedTarget` for blur events.
-        // This doesn't work in IE11 due to https://github.com/facebook/react/issues/3751
-        // TODO: check again if React releases their internal changes to focus event handling (https://github.com/facebook/react/pull/19186).
         if (isFocusVisibleRef.current) {
-            // To detect a tab/window switch, we look for a blur event followed
-            // rapidly by a visibility change.
-            // If we don't see a visibility change within 100ms, it's probably a
-            // regular focus change.
             hadFocusVisibleRecently = true;
             hadFocusVisibleRecentlyTimeout.start(100, () => {
                 hadFocusVisibleRecently = false;
@@ -644,9 +434,6 @@ function useIsFocusVisible() {
         }
         return false;
     }
-    /**
-     * Should be called if a blur event is fired
-     */
     function handleFocusVisible(event) {
         if (isFocusVisible(event)) {
             isFocusVisibleRef.current = true;
@@ -662,11 +449,6 @@ function useIsFocusVisible() {
     };
 }
 
-/**
- * bind event with a11y keyboard, `space`, `enter`, only trigger when key includes in `checkKeys`
- *
- * that will auto preventDefault by default, if you don't want that, set `false` with `preventDefault`
- */
 const useFocusVisible = ({ onFocusVisible, onFocus, onBlur, within = false, } = {}) => {
     const { isFocusVisibleRef, onFocus: handleFocusVisible, onBlur: handleBlurVisible, ref: focusVisibleRef, } = useIsFocusVisible();
     const [focusVisible, setFocusVisible] = useState(false);
@@ -675,15 +457,6 @@ const useFocusVisible = ({ onFocusVisible, onFocus, onBlur, within = false, } =
         handleBlurVisible(event);
         if (isFocusVisibleRef.current === false) {
             setFocusVisible(false);
-            /**
-             * when focus element by press `tab`, will trigger focus event in next event loop
-             *
-             * if current target is containing related target and we don't check whether it is containing related target,
-             * `FocusVisibleWithin` will be false before `focus` trigger,
-             * then `FocusVisibleWithin` will be true after `focus` trigger
-             *
-             * And if current target is containing related target, `FocusVisibleWithin` will never be false
-             */
             if (within &&
                 !event.currentTarget.contains(event.relatedTarget)) {
                 setFocusVisibleWithin(false);
@@ -726,17 +499,12 @@ const useFocusVisible = ({ onFocusVisible, onFocus, onBlur, within = false, } =
             onBlur: handleBlur,
             onFocus: handleFocus,
         },
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         focusVisibleRef: focusVisibleRef,
         focusVisible,
         focusVisibleWithin,
     };
 };
 
-/**
- * a method for trigger force update
- * @returns force update method
- */
 function useForceUpdate() {
     const [, dispatch] = useState(Object.create(null));
     return useEventCallback(() => {
@@ -744,39 +512,9 @@ function useForceUpdate() {
     });
 }
 
-/**
- * That method will give you ability fork same value `ref object` or `method`
- * Example:
- * ```ts
- * const refA = useRef();
- * const refB = useRef();
- *
- * const ref = useForkRef(refA, refB)
- *
- * useEffect(() => {
- *   console.log(refA); // get that current div dom
- *   console.log(refB); // also get that current div dom
- * },[])
- *
- * return <div ref={ref} />
- * ```
- */
 const useForkRef = unstable_useForkRef;
 
 const globalListenerEventMap = new Map();
-/**
- * create globalListener handler for share one listener event
- *
- * @example
- * ```ts
- * const globalListener = createGlobalListener('focus', () => { console.log('focus') });
- * const globalListener2 = createGlobalListener('focus', () => { console.log('focus') });
- * globalListener.listen();
- * globalListener2.listen();
- *
- * => // that will only create an event listener on window, but every callback will get emit value when event triggered
- * ```
- */
 const createGlobalListener = (key, listener, options, { customKey = key, target: targetProp = window, } = {}) => {
     let listening = false;
     const getMapValue = () => globalListenerEventMap.get(customKey);
@@ -818,63 +556,18 @@ const createGlobalListener = (key, listener, options, { customKey = key, target:
     };
     return {
         listen: () => addListener(),
-        /**
-         * remove listener
-         */
         remove: () => removeListener(),
-        /**
-         * current listener state
-         */
         get state() {
             return {
-                /**
-                 * current listener state count
-                 */
                 get count() {
                     return getMapValue()?.listeners.size || 0;
                 },
-                /**
-                 * is that be listening
-                 */
                 listening,
             };
         },
     };
 };
 
-/**
- * bind global event, when you bind same key event,
- * that will reuse one event listener and trigger both callback once that listener be triggered.
- *
- * also you can control listener with method `listen` and `remove`
- * and get listener `state` for check listener count number and current listing state.
- *
- * config:
- * - `target`: custom binding event target, default is `window`
- * - `customKey`: custom key for determining different event group, default is same as `key`
- * - `startImmediately`: start listener immediately, default is `true`
- *
- * * `key`, `options` only work when set first time, never change after first render
- *
- * @example
- * ```ts
- * useGlobalListener('keyup', () => console.log('window key up1'))
- *
- * useGlobalListener('keyup', () => console.log('window key up2'))
- *
- * useGlobalListener('touchend', () => console.log('window key up3'), {
- *  target: someWantHostElement,
- *  customKey: 'hostTouchend',
- * })
- *
- * useGlobalListener('touchend', () => console.log('window key up3'), { passive: false }, {
- *  target: someWantHostElement,
- *  customKey: 'hostTouchend',
- * })
- *
- * => // that will only create an event listener on `window`, but every callback will get emit value when event triggered
- * ```
- */
 function useGlobalListener(key, listener, ...args) {
     const { options, config } = getListenerOverloadOption(args);
     const { customKey = key, target: targetProp = window, startImmediately = true, } = config || {};
@@ -884,7 +577,6 @@ function useGlobalListener(key, listener, ...args) {
         target: targetProp,
     }));
     if (process.env.NODE_ENV !== 'production') {
-        // eslint-disable-next-line react-hooks/rules-of-hooks
         useEffect(() => {
             if (customKey === key) {
                 if (Object.keys(options).length > 0) {
@@ -902,7 +594,6 @@ function useGlobalListener(key, listener, ...args) {
                     });
                 }
             }
-            // eslint-disable-next-line react-hooks/exhaustive-deps
         }, []);
     }
     useEffect(() => {
@@ -910,7 +601,6 @@ function useGlobalListener(key, listener, ...args) {
             globalListener.listen();
         }
         return globalListener.remove;
-        // eslint-disable-next-line react-hooks/exhaustive-deps
     }, []);
     return globalListener;
 }
@@ -936,10 +626,6 @@ function getListenerOverloadOption(args) {
     return { options, config };
 }
 
-/**
- * group hidden logic, when binding events element focus,
- * that hiddenRef will auto be `tabindex={-1}` *
- */
 const useHiddenTabindex = (target) => {
     const handleFocus = useEventCallback(() => {
         const hiddenElm = getRefElement(target);
@@ -1014,20 +700,6 @@ const useHoverDirty = ({ target, disabled = false, }) => {
     };
 };
 
-/**
- * get load state of an image by passing src or srcSet
- * - false: not load yet
- * - 'loaded': successfully loaded
- * - 'error': fail to load
- *
- * @example
- * ```ts
- * const loaded = useImgLoaded({
- *   src,
- *   srcSet,
- * });
- * ```
- */
 const useImgLoaded = ({ crossOrigin, referrerPolicy, src, srcSet, }) => {
     const [loaded, setLoaded] = useState(false);
     useEffect(() => {
@@ -1064,38 +736,7 @@ const useImgLoaded = ({ crossOrigin, referrerPolicy, src, srcSet, }) => {
     return loaded;
 };
 
-/**
- * controllable interval, provide easy way to control interval
- *
- * - cancel: cancel current interval
- * - pause: pause current interval
- * - play: play current interval
- * - getRunning: return current interval running state
- *
- *  @example
- * ```ts
- * const { cancel, play, pause } = useInterval(() => {
- *    console.log('interval be triggered');
- * }, 1000)
- *
- * // get current run times
- * useInterval((times) => {
- *    console.log('current times start from 1', times);
- * }, 2000)
- *
- * // not start interval immediately
- * useInterval((times) => {
- *    console.log('current times start from 1', times);
- * }, 2000, false)
- * ```
- */
-const useInterval = (
-/** callback with times, times start from 1 */
-callback, 
-/** what delay time of that interval */
-delay = 0, 
-/** is that start interval immediately */
-startImmediately = true) => {
+const useInterval = (callback, delay = 0, startImmediately = true) => {
     const intervalRef = useRef();
     const countRef = useRef(0);
     const getRunning = useEventCallback(() => !!intervalRef.current);
@@ -1128,31 +769,13 @@ startImmediately = true) => {
         return () => cancel();
     }, [cancel, play, startImmediately]);
     return {
-        /**
-         * cancel current interval
-         */
         cancel,
-        /**
-         * pause current interval
-         */
         pause,
-        /**
-         * play current interval
-         */
         play,
-        /**
-         * return current interval running state
-         */
         getRunning,
     };
 };
 
-/**
- * Provide user trigger `onKeyDown` only one time when hold press on key.
- * @param includeKeys that check include keys
- * @param methods trigger when first keydown or keyup
- * @returns
- */
 const useKeyDownOnce = (includeKeys, { onKeyDown, onKeyUp }) => {
     const isKeyDownMapRef = useRef({});
     const handleKeyDown = useEventCallback((e) => {
@@ -1182,13 +805,8 @@ const useKeyDownOnce = (includeKeys, { onKeyDown, onKeyUp }) => {
     };
 };
 
-/**
- * that can move index in column array
- */
 function moveIndexInTwoDimension(direction, options) {
     const { currIndex, columns, total, infinite } = options;
-    // start index never small than 0
-    // const index = Math.max(currIndex, 0);
     const lastIndex = total - 1;
     const isInOrder = infinite === 'order';
     const fillTotal = Math.ceil(total / columns) * columns;
@@ -1237,8 +855,6 @@ function moveIndexInTwoDimension(direction, options) {
     if (!infinite && resultIndex >= total) {
         return currIndex;
     }
-    // * when that bigger then sourceTotal, mean that touch end line
-    // * move to current full latest and move again.
     if (resultIndex >= total) {
         if (direction === 'ArrowRight') {
             resultIndex = fillTotal - 1;
@@ -1251,9 +867,6 @@ function moveIndexInTwoDimension(direction, options) {
     return resultIndex;
 }
 
-/**
- * use keyboard move index in two dimensional
- */
 const useKeyboardMoveFocus = ({ infinite, options = [], focusedIndexRef, onFocusedIndexChange, getOptionDisabled, getOptionSearchText, columns = 1, endSearchDebounceTime = 500, }) => {
     const total = options.length;
     const searchText = useRef('');
@@ -1280,7 +893,6 @@ const useKeyboardMoveFocus = ({ infinite, options = [], focusedIndexRef, onFocus
         let findDirection;
         if (total === 0)
             return;
-        // eslint-disable-next-line no-constant-condition
         while (true) {
             const toIndex = findDirection
                 ? findDirection === 'next'
@@ -1302,22 +914,16 @@ const useKeyboardMoveFocus = ({ infinite, options = [], focusedIndexRef, onFocus
                 }
                 break;
             }
-            // * mean that item is disabled, use same direction find next
             else {
-                // * find toIndex is same as current, mean that already find all
                 if (focusedIndexRef.current !== -1 &&
                     toIndex === Math.max(focusedIndexRef.current, 0)) {
                     break;
                 }
-                // * if no item is focused currently and toIndex is already the last item checked,
-                // * it means no item in the list is focusable
                 if (focusedIndexRef.current === -1) {
-                    // from bottom to top and the first item in the list is not focusable
                     if ((Math.abs(currIndex - toIndex) !== 1 || currIndex > toIndex) &&
                         toIndex === 0) {
                         break;
                     }
-                    // from top to bottom and the last item in the list is not focusable
                     if (Math.abs(currIndex - toIndex) === 1 &&
                         currIndex < toIndex &&
                         toIndex === total - 1) {
@@ -1325,7 +931,6 @@ const useKeyboardMoveFocus = ({ infinite, options = [], focusedIndexRef, onFocus
                     }
                 }
                 currIndex = toIndex;
-                // * if that is Hom or End, find use increase or decrease
                 if (key === 'Home') {
                     findDirection = 'next';
                 }
@@ -1335,16 +940,13 @@ const useKeyboardMoveFocus = ({ infinite, options = [], focusedIndexRef, onFocus
             }
         }
     };
-    const getPrevFocusableOption = useCallback((index = focusedIndexRef.current, 
-    /** is that infinite search */
-    isInfinite = true) => {
+    const getPrevFocusableOption = useCallback((index = focusedIndexRef.current, isInfinite = true) => {
         for (let i = index; i >= 0; i--) {
             if (!getOptionDisabled?.(options[i])) {
                 return i;
             }
         }
         if (isInfinite) {
-            // loop find
             for (let i = total - 1; i > index; i--) {
                 if (!getOptionDisabled?.(options[i])) {
                     return i;
@@ -1353,16 +955,13 @@ const useKeyboardMoveFocus = ({ infinite, options = [], focusedIndexRef, onFocus
         }
         return -1;
     }, [focusedIndexRef, getOptionDisabled, options, total]);
-    const getNextFocusableOption = useCallback((index = focusedIndexRef.current, 
-    /** is that infinite search */
-    isInfinite = true) => {
+    const getNextFocusableOption = useCallback((index = focusedIndexRef.current, isInfinite = true) => {
         for (let i = index; i < total; i++) {
             if (!getOptionDisabled?.(options[i])) {
                 return i;
             }
         }
         if (isInfinite) {
-            // loop find
             for (let i = 0; i < index; i++) {
                 if (!getOptionDisabled?.(options[i])) {
                     return i;
@@ -1372,26 +971,13 @@ const useKeyboardMoveFocus = ({ infinite, options = [], focusedIndexRef, onFocus
         return -1;
     }, [focusedIndexRef, getOptionDisabled, options, total]);
     return {
-        /**
-         * Get previous focusable option(include current index).
-         */
         getPrevFocusableOption,
-        /**
-         * Get next focusable option(include current index).
-         */
         getNextFocusableOption,
-        /**
-         * Use to handle keyboard event.
-         */
         onKeyFocusedIndexHandle,
     };
 };
 
 const MOVE_ATTR_KEY = 'data-move-focused';
-/**
- * when focus in container below element with binding `getItemProps`,
- * that will only have one element can be focusable.
- */
 const useOnlyOneFocusable = ({ focusedIndexRef, containerRef, }) => {
     const moveFocusedId = useId(MOVE_ATTR_KEY, true);
     const getIndexElm = (toIndex) => containerRef.current?.querySelector(`[${moveFocusedId}="${toIndex}"]`);
@@ -1424,28 +1010,6 @@ const useOnlyOneFocusable = ({ focusedIndexRef, containerRef, }) => {
     };
 };
 
-/**
- * Provide a utils for switch trigger touch event or mouse event between different device
- *
- * - Trigger `touch` event in `touch support` device
- *   - onTouchStart
- *   - onTouchEnd
- * - Trigger `mouse` event in `non touch support` device
- *   - onMouseDown
- *   - onMouseUp
- *
- * ### Once that is touch support device, that mouse event will never can be trigger
- * https://developer.mozilla.org/en-US/docs/Web/API/Touch_events/Supporting_both_TouchEvent_and_MouseEvent
- *
- * Event order:
- * - touchstart
- * - Zero or more touchmove events, depending on movement of the finger(s)
- * - touchend
- * - mousemove
- * - mousedown
- * - mouseup
- * - click
- */
 const useTouchMouseEvent = ({ onMouseDown: onMouseDownArg, onMouseUp: onMouseUpArg, onTouchStart: onTouchStartArg, onTouchEnd: onTouchEndArg, }, { actionRef } = {}) => {
     const stopMouseEventRef = useRef(false);
     const onTouchStart = useEventCallback((e) => {
@@ -1491,9 +1055,6 @@ const useTouchMouseEvent = ({ onMouseDown: onMouseDownArg, onMouseUp: onMouseUpA
         onMouseUp,
     };
 };
-/**
- * check is element equal or contains target element
- */
 const isElmEqualOrContain = (sourceTarget, containTarget) => {
     const elm = getRefElement(sourceTarget);
     const target = getRefElement(containTarget);
@@ -1503,28 +1064,18 @@ const isElmEqualOrContain = (sourceTarget, containTarget) => {
 const isTouchEvent = (ev) => {
     return 'touches' in ev;
 };
-/**
- * Provide longPress helper, both `click`/`tab`/`keydown` will trigger event
- *
- * - Trigger `onTap` when user action leave small than delay time.
- * - Trigger `onPress` when action time is long than delay time.
- *
- * @default UseLongPressOptions { delay = 300 }
- */
 const useLongPress = ({ onTap, onPress }, { onTouchStart: onTouchStartArg, onTouchEnd: onTouchEndArg, onMouseDown, onKeyDown, onKeyUp, onMouseUp: onMouseUpArg, } = {}, { isPreventDefault = true, delay = 300, externalWindow = window, } = {}) => {
     const isEmittedRef = useRef(false);
     const isA11yDownRef = useRef(false);
     const actionRef = useRef(null);
     const reasonRef = useRef('click');
     const emitLongPress = useDebounce((e) => {
-        // * only when have onPress set have emit
         if (onPress) {
             onPress(e, reasonRef.current);
             isEmittedRef.current = true;
         }
     }, delay);
     const end = (e, isInside) => {
-        // ! mouse up only trigger when up on element, so we host that in document
         globalMouseUpListener.remove();
         if (!isEmittedRef.current && isInside) {
             onTap?.(e, reasonRef.current);
@@ -1534,7 +1085,6 @@ const useLongPress = ({ onTap, onPress }, { onTouchStart: onTouchStartArg, onTou
         emitLongPress.cancel();
     };
     const start = (e) => {
-        // ! mouse up only trigger when up on element, so we host that in document
         globalMouseUpListener.listen();
         const isTouch = e.type === 'touchstart';
         if (isTouch) {
@@ -1544,7 +1094,6 @@ const useLongPress = ({ onTap, onPress }, { onTouchStart: onTouchStartArg, onTou
     };
     const { onMouseUp, onTouchEnd, onTouchStart, ...events } = useTouchMouseEvent({
         onTouchStart: (e) => {
-            // prevent long touch leave element focus
             if (isPreventDefault) {
                 e.preventDefault();
             }
@@ -1552,7 +1101,6 @@ const useLongPress = ({ onTap, onPress }, { onTouchStart: onTouchStartArg, onTou
             start(e);
         },
         onTouchEnd: (e, isInside) => {
-            // prevent leave element focus
             if (isPreventDefault) {
                 e.preventDefault();
             }
@@ -1567,7 +1115,6 @@ const useLongPress = ({ onTap, onPress }, { onTouchStart: onTouchStartArg, onTou
             start(e);
         },
         onMouseUp: (e, isInside) => {
-            // prevent leave element focus
             if (isPreventDefault) {
                 e.preventDefault();
             }
@@ -1575,11 +1122,9 @@ const useLongPress = ({ onTap, onPress }, { onTouchStart: onTouchStartArg, onTou
             end(e, isInside);
         },
     }, { actionRef });
-    // use event listener for make event `passive` work in safari
     useEventListener(actionRef, 'touchstart', onTouchStart, {
         passive: false,
     });
-    // use event listener for make event `passive` work in safari
     useEventListener(actionRef, 'touchend', onTouchEnd, {
         passive: false,
     });
@@ -1589,7 +1134,6 @@ const useLongPress = ({ onTap, onPress }, { onTouchStart: onTouchStartArg, onTou
     });
     const handleDeleteKeyDown = useA11yKeyEvent((e) => {
         reasonRef.current = 'keyboard';
-        // * keydown when hold will trigger many time, show when current is a11y down, not trigger again
         if (!isA11yDownRef.current) {
             emitLongPress(e);
         }
@@ -1613,20 +1157,6 @@ const useLongPress = ({ onTap, onPress }, { onTouchStart: onTouchStartArg, onTou
     };
 };
 
-/**
- * get that component mounted state `ref`
- *
- * @example
- *
- * ```ts
-    const isMountedRef = useMountState();
-
-    if (isMountedRef.current) {
-      console.log('component mounted');
-    }
- *
- * ```
- */
 const useMountState = () => {
     const isMountedRef = useRef(false);
     useEffect(() => {
@@ -1638,9 +1168,6 @@ const useMountState = () => {
     return isMountedRef;
 };
 
-/**
- * only trigger when re-render (in useLayoutEffect), not trigger on component first render
- */
 const useOnLayoutReRender = (cb, deps) => {
     const count = useRef(0);
     const method = useEventCallback(cb);
@@ -1648,17 +1175,12 @@ const useOnLayoutReRender = (cb, deps) => {
         if (count.current === 0) {
             count.current = 1;
             return () => {
-                //
             };
         }
         return method();
-        // eslint-disable-next-line react-hooks/exhaustive-deps
     }, deps);
 };
 
-/**
- * only trigger when re-render, not trigger on component first render
- */
 const useOnReRender = (cb, deps) => {
     const count = useRef(0);
     const method = useEventCallback(cb);
@@ -1666,28 +1188,13 @@ const useOnReRender = (cb, deps) => {
         if (count.current === 0) {
             count.current = 1;
             return () => {
-                //
             };
         }
         return method();
-        // eslint-disable-next-line react-hooks/exhaustive-deps
     }, deps);
 };
 
-/**
- * get resize event with auto disconnect when layout destroy.
- * bring with debounce for event not too many
- * @param ref that ref for element
- * @param callback callback when element resize
- * @param performance options that improve performance
- */
-const useResizeObserver = (
-/** target element ref */
-target, 
-/** trigger when `ResizeObserver` emit */
-callback, 
-/** performance options, `mode`, `time`, `ignoreFireWhenObserve` */
-performance = {}) => {
+const useResizeObserver = (target, callback, performance = {}) => {
     const { mode = 'debounce', time: performanceTime = 200, ignoreFireWhenObserve, options, } = performance;
     const countRef = useRef(0);
     const cb = useEventCallback((...args) => {
@@ -1725,29 +1232,14 @@ performance = {}) => {
         return () => {
             observer.disconnect();
         };
-        // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [el]);
     return observerRef.current;
 };
 
-/**
- * trigger when overflow state change
- */
-const useOverflow = (
-/** target element ref */
-target, 
-/** trigger when `ResizeObserver` emit */
-cb, 
-/**
- * performance options, `mode`, `time`, `ignoreFireWhenObserve`
- *
- * @default { mode: 'throttle' time: 200 }
- */
-performance = {
+const useOverflow = (target, cb, performance = {
     mode: 'throttle',
     time: 200,
 }) => {
-    // * not have default value for that can trigger change first time.
     const showRef = useRef();
     return useResizeObserver(target, () => {
         const element = getRefElement(target);
@@ -1757,7 +1249,6 @@ performance = {
         const show = scrollWidth > clientWidth || scrollHeight > clientHeight;
         if (showRef.current === show)
             return;
-        // only emit when state change
         showRef.current = show;
         cb(show, {
             scrollWidth,
@@ -1768,38 +1259,10 @@ performance = {
     }, performance);
 };
 
-/**
- * Returns a stateful like state with Ref, and a function to update it current value.
- * can trigger update value without re-render
- *
- * @param value init value
- * @param customUpdate you can custom you update method, or just set your `forceUpdate` to reuse same instance
- * @returns an array with [ref, update]
- *
- * @example
- * ```ts
- * const [inputRef, updateInput] = useRefState(123);
- *
- * if(needReRender){
- *   updateInput(456); // trigger re-render
- * } else {
- *   updateInput(456, false); // not trigger re-render
- * }
- * ```
- */
 const useRefState = (value, customUpdate) => {
-    // eslint-disable-next-line react-hooks/rules-of-hooks
     const forceUpdate = customUpdate ?? useForceUpdate();
     const innerValueRef = useRef(value);
-    /**
-     * update ref value, set isUpdate to `false` will not trigger re-render
-     */
-    const setInnerValue = useEventCallback((toValue, 
-    /**
-     * is re-render
-     * @default true
-     */
-    isUpdate = true) => {
+    const setInnerValue = useEventCallback((toValue, isUpdate = true) => {
         innerValueRef.current = toValue;
         if (isUpdate) {
             forceUpdate();
@@ -1808,10 +1271,6 @@ const useRefState = (value, customUpdate) => {
     return [innerValueRef, setInnerValue];
 };
 
-/**
- * get all matched breakpoints
- * @param defaultBreakpoint use defaultBreakpoint when Responsive init (will pass undefined)
- */
 const useResponsiveMatch = (defaultBreakpoint) => {
     const _breakpoint = useResponsiveContext();
     const breakpoint = _breakpoint === undefined ? defaultBreakpoint : _breakpoint;
@@ -1821,13 +1280,6 @@ const useResponsiveMatch = (defaultBreakpoint) => {
     return matchDetail.matchMap;
 };
 
-/**
- * cancelable sleep method.
- *
- * - sleep: a promise sleep
- * - cancel: cancel that sleep event
- * - getSleeping: get current sleeping state
- */
 const useSleep = () => {
     const timeoutIdRef = useRef();
     const rejectRef = useRef();
@@ -1857,36 +1309,13 @@ const useSleep = () => {
         };
     }, []);
     return {
-        /**
-         * sleep method, that will be cancelable with `cancel`,
-         * and when trigger many time that will always clear previous sleep
-         */
         sleep,
-        /**
-         * cancel current sleep timer
-         */
         cancel,
-        /**
-         * return is current is sleeping
-         */
         getSleeping: () => sleepingRef.current,
     };
 };
 
-/* eslint-disable no-await-in-loop */
-/**
- * retry times when exec callback fail
- *
- * * `retry`: that will auto add `times` end of your call back
- * * `cancel`: cancel that retry event, that only cancel inner interval promise, **if you need cancel your `cb` promise, you should handle by yourself.**
- */
-const useRetry = (
-/**
- * exec callback, when you want to end that retry, return `true` with your callback
- */
-cb, 
-/** retry options */
-options) => {
+const useRetry = (cb, options) => {
     const { sleep, cancel: cancelSleep } = useSleep();
     const isCancelRef = useRef(true);
     const complete = () => {
@@ -1895,7 +1324,6 @@ options) => {
     };
     const cancel = () => {
         if (!isCancelRef.current) {
-            // * when outside cancel
             options?.onCancel?.();
             complete();
         }
@@ -1905,7 +1333,6 @@ options) => {
         cancel();
         isCancelRef.current = false;
         options?.onStart?.();
-        // * when exec success, just return directly.
         if (await cb(...args)) {
             if (!isCancelRef.current) {
                 options?.onSuccess?.();
@@ -1937,21 +1364,11 @@ options) => {
         complete();
     };
     return {
-        /**
-         * retry method, that will be cancelable with `cancel`,
-         * and when trigger many time that will always clear previous retry
-         */
         retry,
-        /**
-         * cancel current retry
-         */
         cancel,
     };
 };
 
-/**
- * @param onTabOut Callback fired when a "tab out" event is detected.
- */
 const useTabOut = (onTabOut) => {
     const lastKeyDownIsTabRef = useRef(false);
     const handleKeyDown = (e) => {
@@ -1977,28 +1394,13 @@ const useTabOut = (onTabOut) => {
     };
 };
 
-/**
- * provide a throttle method for throttle method
- * @param fn method for throttle
- * @param throttleTime throttle timeout value, default is  `200`ms
- * @param options throttle setting, default is  `{trailing: true, leading: true}`, detail see lodash
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 const useThrottle = (fn, throttleTime = 200, options) => {
     const memoFn = useEventCallback(fn);
-    // eslint-disable-next-line react-hooks/exhaustive-deps
     const throttleFn = useCallback(throttle(memoFn, throttleTime, options), []);
-    // eslint-disable-next-line react-hooks/exhaustive-deps
     useEffect(() => () => throttleFn.cancel(), []);
     return throttleFn;
 };
 
-/**
- * Internal hook to detect if the component is running in a test runner environment
- * Used by Storybook stories to disable network requests and animations during testing
- * @returns {boolean} true if running in test runner (headless browser), false otherwise
- * @internal
- */
 const useTestRunnerDetection = () => {
     return useMemo(() => {
         return (typeof window !== 'undefined' &&
@@ -2009,10 +1411,7 @@ const useTestRunnerDetection = () => {
 function useTimeout(callback, delay) {
     const savedCallback = useRef(callback);
     savedCallback.current = callback;
-    // Set up the timeout.
     useEffect(() => {
-        // Don't schedule if no delay is specified.
-        // Note: 0 is a valid value for delay.
         if (!delay && delay !== 0) {
             return;
         }
@@ -2021,28 +1420,12 @@ function useTimeout(callback, delay) {
     }, [delay]);
 }
 
-/**
- * Check if Font Loading API is available in the current environment
- * @returns boolean indicating if document.fonts.ready is available
- */
 const isFontLoadingAPIAvailable = () => {
     return (typeof document !== 'undefined' &&
         document.fonts &&
         typeof document.fonts.ready === 'object' &&
         typeof document.fonts.ready.then === 'function');
 };
-/**
- * Hook to detect when fonts are loaded
- *
- * This hook provides graceful degradation:
- * - When Font Loading API is not available (older browsers, SSR, test environments),
- *   it assumes fonts are loaded to prevent blocking UI
- * - When disabled, it immediately returns true without listening to font events
- * - When enabled and API is available, it listens for font loading completion
- *
- * @param enabled - Whether to listen for font loading events (default: true)
- * @returns boolean indicating whether fonts are loaded
- */
 const useFontLoaded = (enabled = true) => {
     const [loaded, setLoaded] = useState(() => !enabled || !isFontLoadingAPIAvailable());
     useEffect(() => {
@@ -2062,14 +1445,6 @@ const useFontLoaded = (enabled = true) => {
     return loaded;
 };
 
-/**
- * Hook to lock body scroll while allowing scroll on target element
- * Uses body-scroll-lock library for cross-platform compatibility
- *
- * @param isLocked - Whether scroll should be locked
- * @param targetElement - Element that should remain scrollable (optional)
- * @param options - Configuration options
- */
 const useBodyScrollLock = (isLocked, targetElement, options = {}) => {
     const { disabled = false, reserveScrollBarGap = true, allowTouchMove, } = options;
     const { document } = useWindowContext();