@ringcentral/spring-base 1.12.0 → 1.13.0

package/hooks.js

@@ -1,72 +1,98 @@
-import { unstable_useEventCallback, unstable_ownerDocument, unstable_Timeout, unstable_useForkRef } from '@mui/utils';
-export { unstable_useControlled as useControlled } from '@mui/utils';
-import * as React from 'react';
-import React__default, { useState, useRef, useEffect, useCallback, useLayoutEffect, useMemo } from 'react';
-import { useWindowContext, useResponsiveContext, getMatchDetail } from './contexts.js';
-import { b as LIVE_ANNOUNCER_ATTR, e as applyVisuallyHiddenStyles, a as announce } from './chunks/index.js';
-import uniqueId from 'lodash/uniqueId';
-import { useButton as useButton$1 } from '@mui/base/useButton';
-import { c as combineProps, d as createAriaHideOutsideController, g as getRefElement, l as logInDev, o as ownerWindow } from './chunks/twMerge.js';
-import './config.js';
-import 'lodash/omit';
-import 'lodash/pick';
-import 'lodash/isPlainObject';
-import debounce from 'lodash/debounce';
-import noop from 'lodash/noop';
-import throttle from 'lodash/throttle';
-import 'tailwind-merge';
-
-const useEventCallback = (func) => {
+import { unstable_Timeout, unstable_useControlled, unstable_useEventCallback, unstable_useForkRef } from "@mui/utils";
+import react, { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import uniqueId from "lodash/uniqueId";
+import { useButton } from "@mui/base";
+import debounce from "lodash/debounce";
+import noop from "lodash/noop";
+import throttle from "lodash/throttle";
+import { getMatchDetail, useWindowContext, useResponsiveContext } from "./contexts.js";
+import { LIVE_ANNOUNCER_ATTR, announce, applyVisuallyHiddenStyles } from "./liveAnnouncer.js";
+import { createAriaHideOutsideController, getRefElement, logInDev, ownerWindow, combineProps, ownerDocument as unstable_ownerDocument } from "./utils.js";
+
+import * as __rspack_external_react from "react";
+
+// 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', ' '];
-const useA11yKeyEvent = (fn, { onlyOnFocus, preventDefault = true, checkKeys = defaultCheckKeys, } = {}) => {
-    return useEventCallback((event) => {
-        if (!fn || (onlyOnFocus && event.target !== event.currentTarget))
-            return;
+
+
+
+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) return;
         if (checkKeys.includes(event.key)) {
-            if (preventDefault)
-                event.preventDefault();
+            if (preventDefault) event.preventDefault();
             fn(event);
         }
     });
 };
 
-const isNativeButton = (el) => {
+
+
+
+// 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' ||
-        (tag === 'INPUT' &&
-            ['button', 'submit', 'reset'].includes(el?.type)) ||
-        (tag === 'A' && el?.href));
+    return tag === 'BUTTON' || tag === 'INPUT' && [
+        'button',
+        'submit',
+        'reset'
+    ].includes(el?.type) || tag === 'A' && el?.href;
 };
-const useActive = ({ onKeyDown, onKeyUp, onMouseDown, onClick, disabled = false, } = {}) => {
+/**
+ * Bind event with a11y keyboard (`space`) to help non-native button elements implement `:active` state.
+ *
+ * Also handles mouse interactions with proper window context support.
+ */ const useActive = ({ onKeyDown, onKeyUp, onMouseDown, onClick, disabled = false } = {})=>{
     const [active, setActive] = useState(false);
     const activeTargetRef = useRef(null);
     const { document: targetDocument = document } = useWindowContext();
-    useEffect(() => {
+    useEffect(()=>{
         if (disabled) {
             setActive(false);
             activeTargetRef.current = null;
         }
-    }, [disabled]);
+    }, [
+        disabled
+    ]);
     if (disabled) {
         return {
-            activeHandlers: { onKeyDown, onKeyUp, onMouseDown, onClick },
-            active: false,
+            activeHandlers: {
+                onKeyDown,
+                onKeyUp,
+                onMouseDown,
+                onClick
+            },
+            active: false
         };
     }
-    const handleMouseDown = (event) => {
+    const handleMouseDown = (event)=>{
         onMouseDown?.(event);
         if (event.defaultPrevented) {
             return;
         }
         setActive(true);
-        targetDocument.addEventListener('mouseup', () => {
+        targetDocument.addEventListener('mouseup', ()=>{
             setActive(false);
-        }, { once: true });
+        }, {
+            once: true
+        });
     };
-    const handleKeyDown = (event) => {
+    const handleKeyDown = (event)=>{
         const isSpaceKey = event.key === ' ';
         onKeyDown?.(event);
         if (event.defaultPrevented) {
@@ -82,15 +108,16 @@ const useActive = ({ onKeyDown, onKeyUp, onMouseDown, onClick, disabled = false,
             }
             setActive(true);
         }
-        if (event.target === event.currentTarget &&
-            !isNativeButton(event.target) &&
-            event.key === 'Enter') {
+        // Keyboard accessibility for non interactive elements
+        if (event.target === event.currentTarget && !isNativeButton(event.target) && event.key === 'Enter') {
             onClick?.(event);
             event.preventDefault();
         }
     };
-    const handleKeyUp = (event) => {
+    const handleKeyUp = (event)=>{
         const isSpaceKey = event.key === ' ';
+        // 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);
         }
@@ -99,11 +126,8 @@ const useActive = ({ onKeyDown, onKeyUp, onMouseDown, onClick, disabled = false,
         if (isSpaceKey) {
             activeTargetRef.current = null;
         }
-        if (hadMatchingSpaceKeyDown &&
-            event.target === event.currentTarget &&
-            !isNativeButton(event.target) &&
-            isSpaceKey &&
-            !event.defaultPrevented) {
+        // Keyboard accessibility for non interactive elements
+        if (hadMatchingSpaceKeyDown && event.target === event.currentTarget && !isNativeButton(event.target) && isSpaceKey && !event.defaultPrevented) {
             onClick?.(event);
         }
     };
@@ -112,13 +136,27 @@ const useActive = ({ onKeyDown, onKeyUp, onMouseDown, onClick, disabled = false,
             onKeyDown: handleKeyDown,
             onKeyUp: handleKeyUp,
             onMouseDown: handleMouseDown,
-            onClick,
+            onClick
         },
-        active,
+        active
     };
 };
 
-function useResultRef(cb) {
+
+
+
+
+
+
+
+/**
+ * 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();
     if (renderRef.current === 0) {
@@ -128,9 +166,27 @@ function useResultRef(cb) {
     return ref;
 }
 
+
+
+
+
+
 const DEFAULT_PREFIX = 'spring-id-';
-function useLegacyId(id, prefixMode) {
-    const { current: resultId } = useResultRef(() => {
+/**
+ * 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 useLegacyId(id, prefixMode) {
+    const { current: resultId } = useResultRef(()=>{
         if (id) {
             if (prefixMode) {
                 return uniqueId(`${id}-`);
@@ -141,7 +197,7 @@ function useLegacyId(id, prefixMode) {
     });
     return resultId;
 }
-const reactUseId = React__default.useId;
+const reactUseId = react.useId;
 function useReactId(id, prefixMode) {
     const reactId = reactUseId();
     if (id) {
@@ -151,50 +207,71 @@ function useReactId(id, prefixMode) {
 }
 const useId = reactUseId ? useReactId : useLegacyId;
 
-const isUseAnnouncerOptions = (value) => {
+
+
+
+
+
+
+const isUseAnnouncerOptions = (value)=>{
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 };
-function useAnnouncer(idOrOptions, maybeOptions) {
+/**
+ * Instance-owned live announcer. Each hook call manages its own body region.
+ *
+ * Prefer `announce` (or `useGlobalAnnouncer` in a pop-out window) so the page
+ * shares one polite/assertive live-region pair per document. Use this hook
+ * only when you need an isolated region that must not share that pair.
+ *
+ * `id` only labels the region's DOM `id` (`rc-announcer-${id}`). The same `id`
+ * does not share or reuse one node: each hook call still owns its own region.
+ * Pass distinct ids when you set one.
+ *
+ * @param idOrOptions - Optional DOM id label, or options when no id is needed
+ * @param maybeOptions - Options when the first argument is an id
+ * @returns announce function that accepts a message string
+ *
+ * @example
+ * ```ts
+ * const announceLocal = useAnnouncer('feature-a', { politeness: 'polite' });
+ * announceLocal('Saved');
+ *
+ * // Do not call useAnnouncer inside list items or other high-cardinality trees.
+ * // Lift one instance to the page/feature boundary and pass `announce` down.
+ * ```
+ */ function useAnnouncer(idOrOptions, maybeOptions) {
     const id = typeof idOrOptions === 'string' ? idOrOptions : undefined;
-    const options = isUseAnnouncerOptions(idOrOptions)
-        ? idOrOptions
-        : maybeOptions;
+    const options = isUseAnnouncerOptions(idOrOptions) ? idOrOptions : maybeOptions;
     const politeness = options?.politeness ?? 'assertive';
+    // TODO(breaking-change): rename the generated id prefix from `rc-announcer`
+    // to `sui-announcer` in the next major cleanup.
     const _id = useId(id ? `rc-announcer-${id}` : 'rc-announcer', !id);
-    const { document: targetDocument, externalWindow, globalThis: contextGlobal, } = useWindowContext();
+    const { document: targetDocument, externalWindow, globalThis: contextGlobal } = useWindowContext();
     const win = externalWindow ?? contextGlobal;
     const ref = useRef(null);
     const lastMessageRef = useRef();
     const pendingTimerRef = useRef(null);
     const pendingRemovalRef = useRef(null);
-    const clearPendingTimer = useCallback(() => {
+    const clearPendingTimer = useCallback(()=>{
         pendingTimerRef.current?.();
         pendingTimerRef.current = null;
     }, []);
-    const clearPendingRemoval = useCallback(() => {
+    const clearPendingRemoval = useCallback(()=>{
         pendingRemovalRef.current?.();
         pendingRemovalRef.current = null;
     }, []);
-    useEffect(() => {
-        const currentDocument = targetDocument ??
-            (typeof contextGlobal.document !== 'undefined'
-                ? contextGlobal.document
-                : undefined);
+    useEffect(()=>{
+        const currentDocument = targetDocument ?? (typeof contextGlobal.document !== 'undefined' ? contextGlobal.document : undefined);
         if (!currentDocument?.body) {
             return undefined;
         }
         const currentEl = ref.current;
-        const canReuseCurrentEl = currentEl?.ownerDocument === currentDocument &&
-            currentEl.id === _id &&
-            currentDocument.body.contains(currentEl);
-        const el = canReuseCurrentEl
-            ? currentEl
-            : currentDocument.createElement('div');
+        const canReuseCurrentEl = currentEl?.ownerDocument === currentDocument && currentEl.id === _id && currentDocument.body.contains(currentEl);
+        const el = canReuseCurrentEl ? currentEl : currentDocument.createElement('div');
         if (canReuseCurrentEl) {
             clearPendingRemoval();
             el.setAttribute('aria-live', politeness);
-        }
-        else {
+        } else {
             ref.current = el;
             el.id = _id;
             el.setAttribute('aria-live', politeness);
@@ -204,9 +281,9 @@ function useAnnouncer(idOrOptions, maybeOptions) {
             applyVisuallyHiddenStyles(el);
             currentDocument.body.appendChild(el);
         }
-        return () => {
+        return ()=>{
             clearPendingTimer();
-            const timerId = win.setTimeout(() => {
+            const timerId = win.setTimeout(()=>{
                 const body = currentDocument.body;
                 if (body.contains(el)) {
                     body.removeChild(el);
@@ -218,7 +295,7 @@ function useAnnouncer(idOrOptions, maybeOptions) {
                     pendingRemovalRef.current = null;
                 }
             });
-            const cancelRemoval = () => {
+            const cancelRemoval = ()=>{
                 win.clearTimeout(timerId);
             };
             pendingRemovalRef.current = cancelRemoval;
@@ -230,12 +307,17 @@ function useAnnouncer(idOrOptions, maybeOptions) {
         contextGlobal,
         win,
         clearPendingTimer,
-        clearPendingRemoval,
+        clearPendingRemoval
     ]);
-    return useCallback((message) => {
+    /**
+   * Announce method that calls screen readers to speak the message.
+   * Uses zero-width space technique to ensure repeated messages are re-announced.
+   *
+   * The technique sets content to a zero-width space (invisible) then to the message,
+   * forcing a content change that screen readers detect as new content.
+   */ return useCallback((message)=>{
         const el = ref.current;
-        if (!el)
-            return;
+        if (!el) return;
         clearPendingTimer();
         if (!message) {
             el.textContent = '';
@@ -247,8 +329,8 @@ function useAnnouncer(idOrOptions, maybeOptions) {
             lastMessageRef.current = message;
             return;
         }
-        el.textContent = '\u200B';
-        const timerId = win.setTimeout(() => {
+        el.textContent = '\u200B'; // Zero-width space (invisible but different content)
+        const timerId = win.setTimeout(()=>{
             if (el && ref.current === el) {
                 el.textContent = message;
                 lastMessageRef.current = message;
@@ -257,67 +339,113 @@ function useAnnouncer(idOrOptions, maybeOptions) {
                 pendingTimerRef.current = null;
             }
         }, 100);
-        const cancelTimer = () => {
+        const cancelTimer = ()=>{
             win.clearTimeout(timerId);
         };
         pendingTimerRef.current = cancelTimer;
-    }, [clearPendingTimer, win]);
+    }, [
+        clearPendingTimer,
+        win
+    ]);
 }
 
-function useGlobalAnnouncer() {
+
+
+
+
+
+
+/**
+ * Window-scoped wrapper around `announce`. Fills in
+ * `useWindowContext().document` so pop-out callers do not need to pass `{ document }`.
+ * Shares one polite/assertive pair per document, not per app.
+ *
+ * Unlike `useAnnouncer`, this does not mount an isolated region per hook call.
+ *
+ * Do not `destroyAnnouncer` on unmount. The window owner should call
+ * `destroyAnnouncer(win.document)` when the pop-out window closes.
+ *
+ * @example
+ * ```ts
+ * const announce = useGlobalAnnouncer();
+ * announce('Saved', 'polite');
+ * ```
+ */ function useGlobalAnnouncer() {
     const { document: targetDocument } = useWindowContext();
-    return useCallback((message, politeness = 'assertive', timeoutOrOptions) => {
-        const timeout = typeof timeoutOrOptions === 'number'
-            ? timeoutOrOptions
-            : timeoutOrOptions?.timeout;
+    return useCallback((message, politeness = 'assertive', timeoutOrOptions)=>{
+        const timeout = typeof timeoutOrOptions === 'number' ? timeoutOrOptions : timeoutOrOptions?.timeout;
         announce(message, politeness, {
             timeout,
-            document: targetDocument,
+            document: targetDocument
         });
-    }, [targetDocument]);
+    }, [
+        targetDocument
+    ]);
 }
 
-function useButton(parameters) {
-    const muiButtonResult = useButton$1(parameters);
+
+
+
+
+
+
+/**
+ * Spring UI's useButton hook that wraps MUI Base's useButton with enhanced active state management.
+ *
+ * Uses the correct document reference from WindowContext to ensure event listeners
+ * are attached to the appropriate document.
+ *
+ * @param parameters - Same parameters as MUI Base's useButton
+ * @returns Button props with proper active state management
+ */ function useButton_useButton(parameters) {
+    const muiButtonResult = useButton(parameters);
     const { active: customActive, activeHandlers } = useActive({
-        disabled: parameters.disabled,
+        disabled: parameters.disabled
     });
     const originalGetRootProps = muiButtonResult.getRootProps;
-    const getRootProps = (externalProps) => {
+    const getRootProps = (externalProps)=>{
         const mergedProps = combineProps(externalProps, activeHandlers);
         return originalGetRootProps(mergedProps);
     };
     return {
         ...muiButtonResult,
         active: customActive,
-        getRootProps,
+        getRootProps
     };
 }
 
-const useAriaHideOutside = (props = {}) => {
+
+
+
+
+
+
+const useAriaHideOutside = (props = {})=>{
     const { enable = true, shouldUseInert = false } = props;
     const { document } = useWindowContext();
     const ariaHideOutsideRef = useRef(null);
     const branchNodesRef = useRef(new Set());
     const controllerRef = useRef();
-    const setAriaHideOutsideTarget = useCallback((node, isActive) => {
+    const setAriaHideOutsideTarget = useCallback((node, isActive)=>{
         if (isActive) {
             branchNodesRef.current.add(node);
             controllerRef.current?.addTarget(node);
-        }
-        else {
+        } else {
             branchNodesRef.current.delete(node);
             controllerRef.current?.removeTarget(node);
         }
     }, []);
-    useLayoutEffect(() => {
+    useLayoutEffect(()=>{
         if (enable && ariaHideOutsideRef.current) {
-            const controller = createAriaHideOutsideController([ariaHideOutsideRef.current, ...branchNodesRef.current], {
+            const controller = createAriaHideOutsideController([
+                ariaHideOutsideRef.current,
+                ...branchNodesRef.current
+            ], {
                 root: document?.body,
-                shouldUseInert,
+                shouldUseInert
             });
             controllerRef.current = controller;
-            return () => {
+            return ()=>{
                 if (controllerRef.current === controller) {
                     controllerRef.current = undefined;
                 }
@@ -326,38 +454,87 @@ const useAriaHideOutside = (props = {}) => {
         }
         controllerRef.current = undefined;
         return undefined;
-    }, [enable, shouldUseInert, document?.body]);
+    }, [
+        enable,
+        shouldUseInert,
+        document?.body
+    ]);
     return {
         ariaHideOutsideRef: ariaHideOutsideRef,
-        ariaHideEnabled: enable,
-        setAriaHideOutsideTarget,
+        /**
+     * Whether outside elements are made unavailable to assistive technology.
+     */ ariaHideEnabled: enable,
+        setAriaHideOutsideTarget
     };
 };
 
-const useAudio = (init) => {
-    const audioRef = useResultRef(() => {
+
+
+
+
+
+/**
+ * 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();
         init?.(audio);
         return audio;
     });
-    useEffect(() => {
+    useEffect(()=>{
         const audio = audioRef.current;
-        return () => {
+        return ()=>{
             audio.srcObject = null;
         };
+    // oxlint-disable-next-line react-hooks/exhaustive-deps
     }, []);
     return audioRef.current;
 };
 
-function usePrevious(cb, isDefault) {
+
+
+
+
+
+/**
+ * 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(() => {
+    useEffect(()=>{
         ref.current = cb();
     });
     return ref.current;
 }
 
-const useChange = (cb, listenCb) => {
+
+
+
+
+/**
+ * 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();
     const prev = usePrevious(listenCb);
@@ -368,138 +545,234 @@ const useChange = (cb, listenCb) => {
     }
     return valueRef.current;
 };
-const useDepsChange = (cb, deps) => {
+/**
+ * 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();
-    const prev = usePrevious(() => deps, true);
+    const prev = usePrevious(()=>deps, true);
     const curr = deps;
-    if (countRef.current === 0 ||
-        curr.some((dep, index) => dep !== prev[index])) {
+    if (countRef.current === 0 || curr.some((dep, index)=>dep !== prev[index])) {
         countRef.current = 1;
         valueRef.current = cb(prev, curr);
     }
     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);
+    return doc.documentElement.clientWidth < event.clientX || doc.documentElement.clientHeight < event.clientY;
 }
-const useClickAway = (onClickAway, props = {}) => {
+/**
+ * @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();
-    const clickAwayRef = useEventCallback((e) => {
+    // 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);
     });
     const shouldActive = Boolean(target);
-    useEffect(() => {
-        if (!isEnabled)
-            return;
+    useEffect(()=>{
+        if (!isEnabled) return;
         if (shouldActive) {
-            const timer = setTimeout(() => {
+            // Ensure that this component is not "activated" synchronously.
+            // https://github.com/facebook/react/issues/20074
+            const timer = setTimeout(()=>{
                 activatedRef.current = true;
             }, 0);
-            return () => {
+            return ()=>{
                 clearTimeout(timer);
                 activatedRef.current = false;
             };
         }
         return undefined;
-    }, [isEnabled, shouldActive]);
-    const handleClickAway = useEventCallback((event) => {
+    }, [
+        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);
-        if (!activatedRef.current ||
-            !target ||
-            ('clientX' in event && clickedRootScrollbar(event, doc))) {
+        // 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(event.target) ||
-                    target.contains(event.target);
+        } 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);
         }
         if (!insideDOM && (disableReactTree || !insideReactTree)) {
             onClickAway(event);
         }
     });
-    const handleSynthetic = (e) => {
+    // Keep track of mouse/touch events that bubbled up through the portal.
+    const handleSynthetic = (e)=>{
         syntheticEventRef.current = true;
     };
-    useEffect(() => {
-        if (!isEnabled)
-            return;
+    useEffect(()=>{
+        if (!isEnabled) return;
         if (target) {
             const doc = unstable_ownerDocument(target);
-            const handleTouchMove = () => {
+            const handleTouchMove = ()=>{
                 movedRef.current = true;
             };
             doc.addEventListener('touchend', handleClickAway);
             doc.addEventListener('touchmove', handleTouchMove);
             doc.addEventListener('click', handleClickAway);
-            return () => {
+            return ()=>{
                 doc.removeEventListener('touchend', handleClickAway);
                 doc.removeEventListener('touchmove', handleTouchMove);
                 doc.removeEventListener('click', handleClickAway);
             };
         }
         return undefined;
-    }, [handleClickAway, isEnabled, target]);
+    }, [
+        handleClickAway,
+        isEnabled,
+        target
+    ]);
     return {
         clickAwayRef,
         clickAwayHandler: {
             onClick: handleSynthetic,
-            onTouchEnd: handleSynthetic,
-        },
+            onTouchEnd: handleSynthetic
+        }
     };
 };
 
-const useDebounce = (fn, debounceTime = 200, options) => {
+
+
+
+
+
+
+
+
+
+
+
+
+/**
+ * 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
+ */ // oxlint-disable-next-line @typescript-eslint/no-explicit-any
+const useDebounce = (fn, debounceTime = 200, options)=>{
     const memoFn = useEventCallback(fn);
+    // oxlint-disable-next-line react-hooks/exhaustive-deps
     const debounceFn = useCallback(debounce(memoFn, debounceTime, options), []);
-    useEffect(() => () => debounceFn.cancel(), []);
+    // oxlint-disable-next-line react-hooks/exhaustive-deps
+    useEffect(()=>()=>debounceFn.cancel(), []);
     return debounceFn;
 };
 
-function useEventListener(target, key, callback, options) {
+
+
+
+
+
+
+
+
+/**
+ * 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);
     const cancelRef = useRef(noop);
     const bindRef = useRef(noop);
-    useEffect(() => {
-        if (!target)
-            return;
+    useEffect(()=>{
+        if (!target) return;
         const currentElm = getRefElement(target);
         if (!currentElm) {
             return cancelRef.current;
         }
-        bindRef.current = () => currentElm.addEventListener(key, listener, addEventListenerOptions);
-        cancelRef.current = () => currentElm.removeEventListener(key, listener, addEventListenerOptions);
+        bindRef.current = ()=>currentElm.addEventListener(key, listener, addEventListenerOptions);
+        cancelRef.current = ()=>currentElm.removeEventListener(key, listener, addEventListenerOptions);
         if (startImmediately) {
             bindRef.current();
         }
         return cancelRef.current;
-    }, [target]);
+    // oxlint-disable-next-line react-hooks/exhaustive-deps
+    }, [
+        target
+    ]);
     return {
-        listen: () => bindRef.current(),
-        remove: () => cancelRef.current(),
+        listen: ()=>bindRef.current(),
+        remove: ()=>cancelRef.current()
     };
 }
 
-const defaultEverTargetValue = (value) => !!value;
-const useEver = (value, targetValue = defaultEverTargetValue) => {
+
+
+
+
+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 result = useRef(false);
     if (!result.current) {
         result.current = targetValue(value);
@@ -507,6 +780,15 @@ const useEver = (value, targetValue = defaultEverTargetValue) => {
     return result.current;
 };
 
+
+
+
+
+
+/* oxlint-disable sonarjs/no-collapsible-if */ /* oxlint-disable sonarjs/prefer-single-boolean-return */ 
+// based on https://github.com/WICG/focus-visible/blob/v4.1.5/src/focus-visible.js
+
+
 let hadKeyboardEvent = true;
 let hadFocusVisibleRecently = false;
 const hadFocusVisibleRecentlyTimeout = new unstable_Timeout();
@@ -523,13 +805,17 @@ const inputTypesWhitelist = {
     week: true,
     time: true,
     datetime: true,
-    'datetime-local': true,
+    'datetime-local': true
 };
-function focusTriggersKeyboardModality(node) {
+/**
+ * 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' &&
-        inputTypesWhitelist[type] &&
-        !node.readOnly) {
+    if (tagName === 'INPUT' && inputTypesWhitelist[type] && !node.readOnly) {
         return true;
     }
     if (tagName === 'TEXTAREA' && !node.readOnly) {
@@ -540,31 +826,47 @@ function focusTriggersKeyboardModality(node) {
     }
     return false;
 }
-function handleKeyDown(event) {
+/**
+ * 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 useIsFocusVisible_handleKeyDown(event) {
     if (event.metaKey || event.altKey || event.ctrlKey) {
         return;
     }
     hadKeyboardEvent = true;
 }
-function handlePointerDown() {
+/**
+ * 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;
         }
     }
 }
 function prepare(doc) {
-    doc.addEventListener('keydown', handleKeyDown, true);
+    doc.addEventListener('keydown', useIsFocusVisible_handleKeyDown, true);
     doc.addEventListener('mousedown', handlePointerDown, true);
     doc.addEventListener('pointerdown', handlePointerDown, true);
     doc.addEventListener('touchstart', handlePointerDown, true);
     doc.addEventListener('visibilitychange', handleVisibilityChange, true);
 }
 function teardown(doc) {
-    doc.removeEventListener('keydown', handleKeyDown, true);
+    doc.removeEventListener('keydown', useIsFocusVisible_handleKeyDown, true);
     doc.removeEventListener('mousedown', handlePointerDown, true);
     doc.removeEventListener('pointerdown', handlePointerDown, true);
     doc.removeEventListener('touchstart', handlePointerDown, true);
@@ -574,22 +876,38 @@ function isFocusVisible(event) {
     const { target } = event;
     try {
         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?
     }
-    catch (error) {
-    }
+    // No need for validFocusTarget check. The user does that by attaching it to
+    // focusable events only.
     return hadKeyboardEvent || focusTriggersKeyboardModality(target);
 }
 function useIsFocusVisible() {
-    const ref = React.useCallback((node) => {
+    const ref = __rspack_external_react.useCallback((node)=>{
         if (node != null) {
             prepare(node.ownerDocument);
         }
     }, []);
-    const isFocusVisibleRef = React.useRef(false);
-    function handleBlurVisible() {
+    const isFocusVisibleRef = __rspack_external_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, () => {
+            hadFocusVisibleRecentlyTimeout.start(100, ()=>{
                 hadFocusVisibleRecently = false;
             });
             isFocusVisibleRef.current = false;
@@ -597,7 +915,9 @@ function useIsFocusVisible() {
         }
         return false;
     }
-    function handleFocusVisible(event) {
+    /**
+   * Should be called if a blur event is fired
+   */ function handleFocusVisible(event) {
         if (isFocusVisible(event)) {
             isFocusVisibleRef.current = true;
             return true;
@@ -608,75 +928,105 @@ function useIsFocusVisible() {
         isFocusVisibleRef,
         onFocus: handleFocusVisible,
         onBlur: handleBlurVisible,
-        ref,
+        ref
     };
 }
 
-const useFocusVisible = ({ onFocusVisible, onFocus, onBlur, within = false, } = {}) => {
-    const { isFocusVisibleRef, onFocus: handleFocusVisible, onBlur: handleBlurVisible, ref: focusVisibleRef, } = useIsFocusVisible();
+// NOTE: this hook has been removed from @mui/utils in https://github.com/mui/material-ui/pull/42467
+// TODO: update related usage in components (remove useIsFocusVisible and use isFocusVisible instead, prefer to use native :focus-visible in new components):
+// reference: https://github.com/mui/material-ui/commit/089c40ca82becca90a9e865f78b76b3816983c41#diff-cf7c814aad470aa459786651c67c4ea5df1004df21668cf3f7941a1fbd3a7ab5
+
+
+
+
+
+/**
+ * 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);
     const [focusVisibleWithin, setFocusVisibleWithin] = useState(false);
+    // Used only when `within: true` — tracks the global focus listener that
+    // detects focus leaving the container via DOM unmount (where the synthetic
+    // blur event is unreliable). Mirrors the pattern used by React Aria's
+    // useFocusWithin hook.
     const globalFocusListenerRef = useRef(null);
     const containerRef = useRef(null);
+    // Store ownerDocument from the container so the listener is registered on
+    // the correct document when rendering inside iframes or detached windows.
+    // Initialized to null to avoid referencing `document` during SSR.
     const ownerDocumentRef = useRef(null);
-    const removeGlobalFocusListener = useCallback(() => {
+    const removeGlobalFocusListener = useCallback(()=>{
         if (globalFocusListenerRef.current) {
             ownerDocumentRef.current?.removeEventListener('focus', globalFocusListenerRef.current, true);
             globalFocusListenerRef.current = null;
         }
     }, []);
-    useEffect(() => {
+    useEffect(()=>{
         return removeGlobalFocusListener;
-    }, [removeGlobalFocusListener]);
-    const handleBlur = (event) => {
+    }, [
+        removeGlobalFocusListener
+    ]);
+    const handleBlur = (event)=>{
         handleBlurVisible(event);
         if (isFocusVisibleRef.current === false) {
             setFocusVisible(false);
-            if (within &&
-                !event.currentTarget.contains(event.relatedTarget)) {
+            /**
+       * 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);
             }
         }
-        if (within &&
-            globalFocusListenerRef.current &&
-            !event.currentTarget.contains(event.relatedTarget)) {
+        // When focus leaves the container via normal interaction (Tab / click),
+        // remove the global listener — it is only needed for the unmount path.
+        if (within && globalFocusListenerRef.current && !event.currentTarget.contains(event.relatedTarget)) {
             removeGlobalFocusListener();
         }
         onBlur?.(event);
     };
-    const handleFocus = (event) => {
+    const handleFocus = (event)=>{
         let updateState;
         if (within) {
             if (event.target === event.currentTarget) {
-                updateState = () => {
+                updateState = ()=>{
                     setFocusVisibleWithin(true);
                     setFocusVisible(true);
                 };
-            }
-            else {
-                updateState = () => {
+            } else {
+                updateState = ()=>{
                     setFocusVisibleWithin(true);
                 };
             }
-        }
-        else if (event.target === event.currentTarget) {
-            updateState = () => {
+        } else if (event.target === event.currentTarget) {
+            updateState = ()=>{
                 setFocusVisible(true);
             };
-        }
-        else {
+        } else {
             return;
         }
         handleFocusVisible(event);
         if (isFocusVisibleRef.current === true) {
             updateState();
             onFocusVisible?.(event);
+            // Register a global focus listener so that if the focused descendant is
+            // removed from the DOM (making the synthetic blur unreliable), we still
+            // detect when focus moves outside and reset focusVisibleWithin correctly.
+            // Mirrors the approach in React Aria's useFocusWithin:
+            // https://github.com/adobe/react-spectrum/blob/main/packages/react-aria/src/interactions/useFocusWithin.ts
             if (within) {
                 removeGlobalFocusListener();
                 containerRef.current = event.currentTarget;
                 ownerDocumentRef.current = event.currentTarget.ownerDocument;
                 const ownerDoc = ownerDocumentRef.current;
-                const listener = (e) => {
+                const listener = (e)=>{
                     if (e.target && !containerRef.current?.contains(e.target)) {
                         setFocusVisibleWithin(false);
                         ownerDoc.removeEventListener('focus', listener, true);
@@ -686,8 +1036,7 @@ const useFocusVisible = ({ onFocusVisible, onFocus, onBlur, within = false, } =
                 globalFocusListenerRef.current = listener;
                 ownerDoc.addEventListener('focus', listener, true);
             }
-        }
-        else if (within) {
+        } else if (within) {
             setFocusVisibleWithin(false);
             removeGlobalFocusListener();
         }
@@ -696,55 +1045,97 @@ const useFocusVisible = ({ onFocusVisible, onFocus, onBlur, within = false, } =
     return {
         focusVisibleHandlers: {
             onBlur: handleBlur,
-            onFocus: handleFocus,
+            onFocus: handleFocus
         },
+        // oxlint-disable-next-line @typescript-eslint/no-explicit-any
         focusVisibleRef: focusVisibleRef,
         focusVisible,
-        focusVisibleWithin,
+        focusVisibleWithin
     };
 };
 
-function useForceUpdate() {
+
+
+
+
+
+/**
+ * a method for trigger force update
+ * @returns force update method
+ */ function useForceUpdate() {
     const [, dispatch] = useState(Object.create(null));
-    return useEventCallback(() => {
+    return useEventCallback(()=>{
         dispatch(Object.create(null));
     });
 }
 
-const useForkRef = unstable_useForkRef;
+
+
+
+
+/**
+ * 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();
-const createGlobalListener = (key, listener, options, { customKey = key, target: targetProp = window, } = {}) => {
+/**
+ * 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);
-    const addListener = () => {
-        if (listening)
-            return;
+    const getMapValue = ()=>globalListenerEventMap.get(customKey);
+    const addListener = ()=>{
+        if (listening) return;
         const savedEvent = getMapValue();
         if (!savedEvent?.exec) {
-            const exec = (e) => {
+            const exec = (e)=>{
                 const event = getMapValue();
-                event?.listeners.forEach((c) => c(e));
+                event?.listeners.forEach((c)=>c(e));
             };
             globalListenerEventMap.set(customKey, {
                 exec,
-                listeners: new Set([listener]),
+                listeners: new Set([
+                    listener
+                ])
             });
             const target = getRefElement(targetProp);
             target?.addEventListener(key, exec, options);
-        }
-        else {
+        } else {
             savedEvent.listeners.add(listener);
         }
         listening = true;
     };
-    const removeListener = () => {
-        if (!listening)
-            return;
+    const removeListener = ()=>{
+        if (!listening) return;
         listening = false;
         const _savedEvent = getMapValue();
-        if (!_savedEvent)
-            return;
+        if (!_savedEvent) return;
         const { listeners } = _savedEvent;
         listeners.delete(listener);
         if (listeners.size === 0) {
@@ -754,34 +1145,80 @@ const createGlobalListener = (key, listener, options, { customKey = key, target:
         }
     };
     return {
-        listen: () => addListener(),
-        remove: () => removeListener(),
-        get state() {
+        listen: ()=>addListener(),
+        /**
+     * remove listener
+     */ remove: ()=>removeListener(),
+        /**
+     * current listener state
+     */ get state () {
             return {
-                get count() {
+                /**
+         * current listener state count
+         */ get count () {
                     return getMapValue()?.listeners.size || 0;
                 },
-                listening,
+                /**
+         * is that be listening
+         */ listening
             };
-        },
+        }
     };
 };
 
-function useGlobalListener(key, listener, ...args) {
+
+
+
+
+
+/**
+ * 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 || {};
+    const { customKey = key, target: targetProp = window, startImmediately = true } = config || {};
     const _listener = useEventCallback(listener);
     const { current: globalListener } = useRef(createGlobalListener(key, _listener, options, {
         customKey,
-        target: targetProp,
+        target: targetProp
     }));
     if (process.env.NODE_ENV !== 'production') {
-        useEffect(() => {
+        // oxlint-disable-next-line react-hooks/rules-of-hooks
+        useEffect(()=>{
             if (customKey === key) {
                 if (Object.keys(options).length > 0) {
                     logInDev({
                         scope: 'useGlobalListener',
-                        message: 'when have set options, suggest you also bind customKey, otherwise, it may use previous listener without same options',
+                        message: 'when have set options, suggest you also bind customKey, otherwise, it may use previous listener without same options'
                     });
                 }
                 const target = getRefElement(targetProp);
@@ -789,17 +1226,19 @@ function useGlobalListener(key, listener, ...args) {
                     logInDev({
                         scope: 'useGlobalListener',
                         message: 'When you custom binding event target, you must custom key for determining different event group',
-                        level: 'error',
+                        level: 'error'
                     });
                 }
             }
+        // oxlint-disable-next-line react-hooks/exhaustive-deps
         }, []);
     }
-    useEffect(() => {
+    useEffect(()=>{
         if (startImmediately) {
             globalListener.listen();
         }
         return globalListener.remove;
+    // oxlint-disable-next-line react-hooks/exhaustive-deps
     }, []);
     return globalListener;
 }
@@ -809,30 +1248,40 @@ function getListenerOverloadOption(args) {
     if (typeof args[0] === 'boolean') {
         options = args[0];
         config = args[1];
-    }
-    else {
+    } else {
         const { startImmediately, customKey, target, ...restOptions } = {
             ...args[0],
-            ...args[1],
+            ...args[1]
         };
         options = restOptions;
         config = {
             startImmediately,
             customKey,
-            target,
+            target
         };
     }
-    return { options, config };
+    return {
+        options,
+        config
+    };
 }
 
-const useHiddenTabindex = (target) => {
-    const handleFocus = useEventCallback(() => {
+
+
+
+
+
+/**
+ * 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);
         if (hiddenElm && hiddenElm.tabIndex === 0) {
             hiddenElm.tabIndex = -1;
         }
     });
-    const handleBlur = useEventCallback(() => {
+    const handleBlur = useEventCallback(()=>{
         const hiddenElm = getRefElement(target);
         if (hiddenElm && hiddenElm.tabIndex === -1) {
             hiddenElm.tabIndex = 0;
@@ -840,86 +1289,111 @@ const useHiddenTabindex = (target) => {
     });
     return {
         onFocus: handleFocus,
-        onBlur: handleBlur,
+        onBlur: handleBlur
     };
 };
 
-const useHover = ({ onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, disabled = false, disableReactTree = true, } = {}) => {
+
+
+
+
+const useHover = ({ onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, disabled = false, disableReactTree = true } = {})=>{
     const [hover, setHover] = useState(false);
     const hoverRef = useRef(false);
-    useEffect(() => {
+    useEffect(()=>{
         if (disabled) {
             setHover(false);
-        }
-        else if (!disabled && hoverRef.current) {
+        } else if (!disabled && hoverRef.current) {
             setHover(true);
         }
-    }, [disabled]);
-    const updateHoverState = (hover, event) => {
-        if (disableReactTree &&
-            !event.currentTarget.contains(event.target)) {
+    }, [
+        disabled
+    ]);
+    const updateHoverState = (hover, event)=>{
+        if (disableReactTree && !event.currentTarget.contains(event.target)) {
             return;
         }
-        if (!disabled)
-            setHover(hover);
+        if (!disabled) setHover(hover);
         hoverRef.current = hover;
     };
-    const onMouseEnter = (event) => {
+    const onMouseEnter = (event)=>{
         handleMouseEnter?.(event);
         updateHoverState(true, event);
     };
-    const onMouseLeave = (event) => {
+    const onMouseLeave = (event)=>{
         handleMouseLeave?.(event);
         updateHoverState(false, event);
     };
     return {
-        hoverHandlers: { onMouseEnter, onMouseLeave },
-        hover,
+        hoverHandlers: {
+            onMouseEnter,
+            onMouseLeave
+        },
+        hover
     };
 };
 
-const useHoverDirty = ({ target, disabled = false, }) => {
+
+
+
+const useHoverDirty = ({ target, disabled = false })=>{
     const [hover, setHover] = useState(false);
-    useEffect(() => {
-        if (disabled || !target)
-            setHover(false);
-    }, [disabled, target]);
-    useEventListener(target, 'mouseenter', () => {
-        if (disabled)
-            return;
+    useEffect(()=>{
+        if (disabled || !target) setHover(false);
+    }, [
+        disabled,
+        target
+    ]);
+    useEventListener(target, 'mouseenter', ()=>{
+        if (disabled) return;
         setHover(true);
     });
-    useEventListener(target, 'mouseleave', () => {
-        if (disabled)
-            return;
+    useEventListener(target, 'mouseleave', ()=>{
+        if (disabled) return;
         setHover(false);
     });
     return {
-        hover,
+        hover
     };
 };
 
-const useImgLoaded = ({ crossOrigin, referrerPolicy, src, srcSet, }) => {
+
+
+
+
+
+const useIsoLayoutEffect = typeof window === 'undefined' ? useEffect : useLayoutEffect;
+/**
+ * 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(() => {
+    useIsoLayoutEffect(()=>{
         if (!src && !srcSet) {
+            setLoaded('error');
             return undefined;
         }
         setLoaded(false);
         let active = true;
-        const image = new Image();
-        image.onload = () => {
-            if (!active) {
-                return;
-            }
-            setLoaded('loaded');
-        };
-        image.onerror = () => {
-            if (!active) {
-                return;
-            }
-            setLoaded('error');
-        };
+        const image = new window.Image();
+        const updateLoaded = (status)=>()=>{
+                if (!active) {
+                    return;
+                }
+                setLoaded(status);
+            };
+        image.onload = updateLoaded('loaded');
+        image.onerror = updateLoaded('error');
         crossOrigin && (image.crossOrigin = crossOrigin);
         referrerPolicy && (image.referrerPolicy = referrerPolicy);
         if (src) {
@@ -928,71 +1402,133 @@ const useImgLoaded = ({ crossOrigin, referrerPolicy, src, srcSet, }) => {
         if (srcSet) {
             image.srcset = srcSet;
         }
-        return () => {
+        if (image.complete) {
+            setLoaded(image.naturalWidth > 0 ? 'loaded' : 'error');
+        }
+        return ()=>{
             active = false;
         };
-    }, [crossOrigin, referrerPolicy, src, srcSet]);
+    }, [
+        crossOrigin,
+        referrerPolicy,
+        src,
+        srcSet
+    ]);
     return loaded;
 };
 
-const useInterval = (callback, delay = 0, startImmediately = true) => {
+
+
+
+
+
+/**
+ * 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 intervalRef = useRef();
     const countRef = useRef(0);
-    const getRunning = useEventCallback(() => !!intervalRef.current);
-    const savedCallback = useEventCallback((times) => {
+    const getRunning = useEventCallback(()=>!!intervalRef.current);
+    const savedCallback = useEventCallback((times)=>{
         callback(times);
     });
-    const pause = useCallback(() => {
+    const pause = useCallback(()=>{
         if (intervalRef.current) {
             clearInterval(intervalRef.current);
             intervalRef.current = undefined;
         }
     }, []);
-    const cancel = useCallback(() => {
+    const cancel = useCallback(()=>{
         pause();
         countRef.current = 0;
-    }, [pause]);
-    const play = useCallback(() => {
+    }, [
+        pause
+    ]);
+    const play = useCallback(()=>{
         const isRunning = getRunning();
-        if (isRunning)
-            return;
-        intervalRef.current = setInterval(() => {
+        if (isRunning) return;
+        intervalRef.current = setInterval(()=>{
             countRef.current++;
             savedCallback(countRef.current);
         }, delay);
-    }, [delay, getRunning, savedCallback]);
-    useEffect(() => {
+    }, [
+        delay,
+        getRunning,
+        savedCallback
+    ]);
+    useEffect(()=>{
         if (startImmediately) {
             play();
         }
-        return () => cancel();
-    }, [cancel, play, startImmediately]);
-    return {
+        return ()=>cancel();
+    }, [
         cancel,
-        pause,
         play,
-        getRunning,
+        startImmediately
+    ]);
+    return {
+        /**
+     * cancel current interval
+     */ cancel,
+        /**
+     * pause current interval
+     */ pause,
+        /**
+     * play current interval
+     */ play,
+        /**
+     * return current interval running state
+     */ getRunning
     };
 };
 
-const useKeyDownOnce = (includeKeys, { onKeyDown, onKeyUp }) => {
+
+
+
+
+
+/**
+ * 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) => {
+    const handleKeyDown = useEventCallback((e)=>{
         if (includeKeys.includes(e.key)) {
             if (!isKeyDownMapRef.current[e.key]) {
                 onKeyDown?.(e);
-            }
-            else {
+            } else {
                 e.preventDefault();
                 e.stopPropagation();
             }
             isKeyDownMapRef.current[e.key] = true;
-        }
-        else {
+        } else {
             onKeyDown?.(e);
         }
     });
-    const handleKeyUp = useEventCallback((e) => {
+    const handleKeyUp = useEventCallback((e)=>{
         if (includeKeys.includes(e.key)) {
             isKeyDownMapRef.current[e.key] = false;
         }
@@ -1000,48 +1536,57 @@ const useKeyDownOnce = (includeKeys, { onKeyDown, onKeyUp }) => {
     });
     return {
         onKeyDown: handleKeyDown,
-        onKeyUp: handleKeyUp,
+        onKeyUp: handleKeyUp
     };
 };
 
-function moveIndexInTwoDimension(direction, options) {
+
+
+/**
+ * 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;
     let resultIndex;
-    switch (direction) {
-        case 'ArrowUp': {
-            const toIndex = (Math.max(currIndex, 0) - columns + fillTotal) % fillTotal;
-            resultIndex = infinite ? toIndex : Math.min(toIndex, currIndex);
-            break;
-        }
-        case 'ArrowRight': {
-            if (isInOrder) {
-                const tmp = currIndex + 1;
-                resultIndex = tmp > lastIndex ? 0 : tmp;
+    switch(direction){
+        case 'ArrowUp':
+            {
+                const toIndex = (Math.max(currIndex, 0) - columns + fillTotal) % fillTotal;
+                resultIndex = infinite ? toIndex : Math.min(toIndex, currIndex);
                 break;
             }
-            const toIndex = Math.floor(currIndex / columns) * columns + ((currIndex + 1) % columns);
-            resultIndex = infinite ? toIndex : Math.max(toIndex, currIndex);
-            break;
-        }
-        case 'ArrowDown': {
-            const toIndex = (currIndex + columns) % fillTotal;
-            resultIndex = infinite ? toIndex : Math.max(toIndex, currIndex);
-            break;
-        }
-        case 'ArrowLeft': {
-            if (isInOrder) {
-                const tmp = currIndex - 1;
-                resultIndex = tmp < 0 ? lastIndex : tmp;
+        case 'ArrowRight':
+            {
+                if (isInOrder) {
+                    const tmp = currIndex + 1;
+                    resultIndex = tmp > lastIndex ? 0 : tmp;
+                    break;
+                }
+                const toIndex = Math.floor(currIndex / columns) * columns + (currIndex + 1) % columns;
+                resultIndex = infinite ? toIndex : Math.max(toIndex, currIndex);
+                break;
+            }
+        case 'ArrowDown':
+            {
+                const toIndex = (currIndex + columns) % fillTotal;
+                resultIndex = infinite ? toIndex : Math.max(toIndex, currIndex);
+                break;
+            }
+        case 'ArrowLeft':
+            {
+                if (isInOrder) {
+                    const tmp = currIndex - 1;
+                    resultIndex = tmp < 0 ? lastIndex : tmp;
+                    break;
+                }
+                const toIndex = Math.floor(currIndex / columns) * columns + (currIndex - 1 + columns) % columns;
+                resultIndex = infinite ? toIndex : Math.min(toIndex, currIndex);
                 break;
             }
-            const toIndex = Math.floor(currIndex / columns) * columns +
-                ((currIndex - 1 + columns) % columns);
-            resultIndex = infinite ? toIndex : Math.min(toIndex, currIndex);
-            break;
-        }
         case 'Home':
             resultIndex = 0;
             break;
@@ -1054,55 +1599,56 @@ 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;
         }
         return moveIndexInTwoDimension(direction, {
             ...options,
-            currIndex: resultIndex,
+            currIndex: resultIndex
         });
     }
     return resultIndex;
 }
 
-const useKeyboardMoveFocus = ({ infinite, options = [], focusedIndexRef, onFocusedIndexChange, getOptionDisabled, getOptionSearchText, columns = 1, endSearchDebounceTime = 500, }) => {
+
+
+
+
+/**
+ * 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('');
-    const debounceEndSearch = useDebounce(() => (searchText.current = ''), endSearchDebounceTime);
-    const searchTextAndFocus = (event) => {
+    const debounceEndSearch = useDebounce(()=>searchText.current = '', endSearchDebounceTime);
+    const searchTextAndFocus = (event)=>{
         const key = event.key;
-        if (!getOptionSearchText || key.length !== 1)
-            return;
+        if (!getOptionSearchText || key.length !== 1) return;
         debounceEndSearch();
         searchText.current += key.toLowerCase();
-        const matchedIndex = options.findIndex((option) => {
+        const matchedIndex = options.findIndex((option)=>{
             const text = getOptionSearchText(option);
-            return Boolean(!getOptionDisabled?.(option) &&
-                text &&
-                text.toLowerCase().startsWith(searchText.current));
+            return Boolean(!getOptionDisabled?.(option) && text && text.toLowerCase().startsWith(searchText.current));
         });
         if (matchedIndex > -1) {
             onFocusedIndexChange(event, matchedIndex);
         }
     };
-    const onKeyFocusedIndexHandle = (event) => {
+    const onKeyFocusedIndexHandle = (event)=>{
         let currIndex = focusedIndexRef.current;
         const key = event.key;
         let findDirection;
-        if (total === 0)
-            return;
-        while (true) {
-            const toIndex = findDirection
-                ? findDirection === 'next'
-                    ? currIndex + 1
-                    : currIndex - 1
-                : moveIndexInTwoDimension(key, {
-                    currIndex,
-                    columns,
-                    total,
-                    infinite,
-                });
+        if (total === 0) return;
+        // oxlint-disable-next-line no-constant-condition
+        while(true){
+            const toIndex = findDirection ? findDirection === 'next' ? currIndex + 1 : currIndex - 1 : moveIndexInTwoDimension(key, {
+                currIndex,
+                columns,
+                total,
+                infinite
+            });
             if (toIndex === currIndex) {
                 searchTextAndFocus(event);
                 break;
@@ -1112,76 +1658,99 @@ const useKeyboardMoveFocus = ({ infinite, options = [], focusedIndexRef, onFocus
                     onFocusedIndexChange(event, toIndex);
                 }
                 break;
-            }
-            else {
-                if (focusedIndexRef.current !== -1 &&
-                    toIndex === Math.max(focusedIndexRef.current, 0)) {
+            } 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) {
-                    if ((Math.abs(currIndex - toIndex) !== 1 || currIndex > toIndex) &&
-                        toIndex === 0) {
+                    // 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;
                     }
-                    if (Math.abs(currIndex - toIndex) === 1 &&
-                        currIndex < toIndex &&
-                        toIndex === total - 1) {
+                    // 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) {
                         break;
                     }
                 }
                 currIndex = toIndex;
+                // * if that is Hom or End, find use increase or decrease
                 if (key === 'Home') {
                     findDirection = 'next';
-                }
-                else if (key === 'End') {
+                } else if (key === 'End') {
                     findDirection = 'prev';
                 }
             }
         }
     };
-    const getPrevFocusableOption = useCallback((index = focusedIndexRef.current, isInfinite = true) => {
-        for (let i = index; i >= 0; i--) {
+    const getPrevFocusableOption = useCallback((index = focusedIndexRef.current, /** is that infinite search */ isInfinite = true)=>{
+        for(let i = index; i >= 0; i--){
             if (!getOptionDisabled?.(options[i])) {
                 return i;
             }
         }
         if (isInfinite) {
-            for (let i = total - 1; i > index; i--) {
+            // loop find
+            for(let i = total - 1; i > index; i--){
                 if (!getOptionDisabled?.(options[i])) {
                     return i;
                 }
             }
         }
         return -1;
-    }, [focusedIndexRef, getOptionDisabled, options, total]);
-    const getNextFocusableOption = useCallback((index = focusedIndexRef.current, isInfinite = true) => {
-        for (let i = index; i < total; i++) {
+    }, [
+        focusedIndexRef,
+        getOptionDisabled,
+        options,
+        total
+    ]);
+    const getNextFocusableOption = useCallback((index = focusedIndexRef.current, /** is that infinite search */ isInfinite = true)=>{
+        for(let i = index; i < total; i++){
             if (!getOptionDisabled?.(options[i])) {
                 return i;
             }
         }
         if (isInfinite) {
-            for (let i = 0; i < index; i++) {
+            // loop find
+            for(let i = 0; i < index; i++){
                 if (!getOptionDisabled?.(options[i])) {
                     return i;
                 }
             }
         }
         return -1;
-    }, [focusedIndexRef, getOptionDisabled, options, total]);
+    }, [
+        focusedIndexRef,
+        getOptionDisabled,
+        options,
+        total
+    ]);
     return {
-        getPrevFocusableOption,
-        getNextFocusableOption,
-        onKeyFocusedIndexHandle,
+        /**
+     * 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';
 const MOVE_INDEX_ATTR_KEY = 'data-move-index';
-const useOnlyOneFocusable = ({ focusedIndexRef, containerRef, }) => {
+/**
+ * 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();
-    const getIndexElm = (toIndex) => containerRef.current?.querySelector(`[${MOVE_ATTR_KEY}="${moveFocusedId}"][${MOVE_INDEX_ATTR_KEY}="${toIndex}"]`);
-    const setIndexTabIndex = (toIndex) => {
+    const getIndexElm = (toIndex)=>containerRef.current?.querySelector(`[${MOVE_ATTR_KEY}="${moveFocusedId}"][${MOVE_INDEX_ATTR_KEY}="${toIndex}"]`);
+    const setIndexTabIndex = (toIndex)=>{
         const toElm = getIndexElm(toIndex);
         if (toElm) {
             const prevElm = containerRef.current?.querySelector(`[${MOVE_ATTR_KEY}="${moveFocusedId}"][tabindex="0"]`);
@@ -1189,7 +1758,7 @@ const useOnlyOneFocusable = ({ focusedIndexRef, containerRef, }) => {
             toElm.setAttribute('tabindex', '0');
         }
     };
-    const focusIndex = (toIndex) => {
+    const focusIndex = (toIndex)=>{
         const toElm = getIndexElm(toIndex);
         toElm?.focus();
     };
@@ -1197,23 +1766,53 @@ const useOnlyOneFocusable = ({ focusedIndexRef, containerRef, }) => {
         moveFocusedId,
         focusIndex,
         setIndexTabIndex,
-        getItemProps: (index, options) => {
+        getItemProps: (index, options)=>{
             return combineProps({
                 [MOVE_ATTR_KEY]: moveFocusedId,
                 [MOVE_INDEX_ATTR_KEY]: String(index),
                 tabIndex: index === focusedIndexRef.current ? 0 : -1,
-                onFocus: () => {
+                onFocus: ()=>{
                     focusedIndexRef.current = index;
                     setIndexTabIndex(index);
-                },
+                }
             }, options ?? {});
-        },
+        }
     };
 };
 
-const useTouchMouseEvent = ({ onMouseDown: onMouseDownArg, onMouseUp: onMouseUpArg, onTouchStart: onTouchStartArg, onTouchEnd: onTouchEndArg, }, { actionRef } = {}) => {
+
+
+
+
+
+
+
+
+
+/**
+ * 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) => {
+    const onTouchStart = useEventCallback((e)=>{
         stopMouseEventRef.current = true;
         onTouchStartArg?.(e);
     });
@@ -1224,7 +1823,7 @@ const useTouchMouseEvent = ({ onMouseDown: onMouseDownArg, onMouseUp: onMouseUpA
         }
         return false;
     }
-    const onTouchEnd = useEventCallback((e) => {
+    const onTouchEnd = useEventCallback((e)=>{
         let isInside;
         if (actionRef && e.touches.length < 2 && e.changedTouches.length < 2) {
             const touch = e.touches[0] || e.changedTouches[0];
@@ -1233,16 +1832,15 @@ const useTouchMouseEvent = ({ onMouseDown: onMouseDownArg, onMouseUp: onMouseUpA
         }
         onTouchEndArg?.(e, isInside);
     });
-    const onMouseDown = useEventCallback((e) => {
+    const onMouseDown = useEventCallback((e)=>{
         if (stopMouseEventRef.current) {
             return;
         }
         onMouseDownArg?.(e);
     });
-    const onMouseUp = useEventCallback((e) => {
+    const onMouseUp = useEventCallback((e)=>{
         let isInside;
-        if (stopMouseEventRef.current)
-            return;
+        if (stopMouseEventRef.current) return;
         if (actionRef) {
             const elm = e.target;
             isInside = !!elm && checkInside(elm);
@@ -1253,30 +1851,50 @@ const useTouchMouseEvent = ({ onMouseDown: onMouseDownArg, onMouseUp: onMouseUpA
         onTouchStart,
         onTouchEnd,
         onMouseDown,
-        onMouseUp,
+        onMouseUp
     };
 };
-const isElmEqualOrContain = (sourceTarget, containTarget) => {
+/**
+ * check is element equal or contains target element
+ */ const isElmEqualOrContain = (sourceTarget, containTarget)=>{
     const elm = getRefElement(sourceTarget);
     const target = getRefElement(containTarget);
     return elm && target && (target === elm || target.contains(elm));
 };
 
-const isTouchEvent = (ev) => {
+
+
+
+
+
+
+
+
+
+const isTouchEvent = (ev)=>{
     return 'touches' in ev;
 };
-const useLongPress = ({ onTap, onPress }, { onTouchStart: onTouchStartArg, onTouchEnd: onTouchEndArg, onMouseDown, onKeyDown, onKeyUp, onMouseUp: onMouseUpArg, } = {}, { isPreventDefault = true, delay = 300, externalWindow = window, } = {}) => {
+/**
+ * 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) => {
+    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) => {
+    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);
@@ -1285,7 +1903,8 @@ const useLongPress = ({ onTap, onPress }, { onTouchStart: onTouchStartArg, onTou
         isEmittedRef.current = false;
         emitLongPress.cancel();
     };
-    const start = (e) => {
+    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) {
@@ -1294,111 +1913,173 @@ const useLongPress = ({ onTap, onPress }, { onTouchStart: onTouchStartArg, onTou
         emitLongPress(e);
     };
     const { onMouseUp, onTouchEnd, onTouchStart, ...events } = useTouchMouseEvent({
-        onTouchStart: (e) => {
+        onTouchStart: (e)=>{
+            // prevent long touch leave element focus
             if (isPreventDefault) {
                 e.preventDefault();
             }
             onTouchStartArg?.(e);
             start(e);
         },
-        onTouchEnd: (e, isInside) => {
+        onTouchEnd: (e, isInside)=>{
+            // prevent leave element focus
             if (isPreventDefault) {
                 e.preventDefault();
             }
             onTouchEndArg?.(e, isInside);
             end(e, isInside);
         },
-        onMouseDown: (e) => {
+        onMouseDown: (e)=>{
             if (isPreventDefault) {
                 e.preventDefault();
             }
             onMouseDown?.(e);
             start(e);
         },
-        onMouseUp: (e, isInside) => {
+        onMouseUp: (e, isInside)=>{
+            // prevent leave element focus
             if (isPreventDefault) {
                 e.preventDefault();
             }
             onMouseUpArg?.(e);
             end(e, isInside);
-        },
-    }, { actionRef });
+        }
+    }, {
+        actionRef
+    });
+    // use event listener for make event `passive` work in safari
     useEventListener(actionRef, 'touchstart', onTouchStart, {
-        passive: false,
+        passive: false
     });
+    // use event listener for make event `passive` work in safari
     useEventListener(actionRef, 'touchend', onTouchEnd, {
-        passive: false,
+        passive: false
     });
     const globalMouseUpListener = useGlobalListener('mouseup', onMouseUp, {
         target: externalWindow,
-        startImmediately: false,
+        startImmediately: false
     });
-    const handleDeleteKeyDown = useA11yKeyEvent((e) => {
+    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);
         }
         isA11yDownRef.current = true;
-    }, { preventDefault: false });
-    const handleKeyDown = useEventCallback((e) => {
+    }, {
+        preventDefault: false
+    });
+    const handleKeyDown = useEventCallback((e)=>{
         onKeyDown?.(e);
         handleDeleteKeyDown(e);
     });
-    const handleKeyUp = useEventCallback((e) => {
+    const handleKeyUp = useEventCallback((e)=>{
         onKeyUp?.(e);
-        if (isA11yDownRef.current)
-            end(e, true);
+        if (isA11yDownRef.current) end(e, true);
         isA11yDownRef.current = false;
     });
     return {
         ref: actionRef,
         onKeyDown: handleKeyDown,
         onKeyUp: handleKeyUp,
-        ...events,
+        ...events
     };
 };
 
-const useMountState = () => {
+
+
+
+
+/**
+ * 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(() => {
+    useEffect(()=>{
         isMountedRef.current = true;
-        return () => {
+        return ()=>{
             isMountedRef.current = false;
         };
     }, []);
     return isMountedRef;
 };
 
-const useOnLayoutReRender = (cb, deps) => {
+
+
+
+
+
+/**
+ * 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);
-    useLayoutEffect(() => {
+    useLayoutEffect(()=>{
         if (count.current === 0) {
             count.current = 1;
-            return () => {
+            return ()=>{
+            //
             };
         }
         return method();
+    // oxlint-disable-next-line react-hooks/exhaustive-deps
     }, deps);
 };
 
-const useOnReRender = (cb, deps) => {
+
+
+
+
+
+/**
+ * only trigger when re-render, not trigger on component first render
+ */ const useOnReRender = (cb, deps)=>{
     const count = useRef(0);
     const method = useEventCallback(cb);
-    useEffect(() => {
+    useEffect(()=>{
         if (count.current === 0) {
             count.current = 1;
-            return () => {
+            return ()=>{
+            //
             };
         }
         return method();
+    // oxlint-disable-next-line react-hooks/exhaustive-deps
     }, deps);
 };
 
-const useResizeObserver = (target, callback, performance = {}) => {
-    const { mode = 'debounce', time: performanceTime = 200, ignoreFireWhenObserve, options, } = performance;
+
+
+
+
+
+
+
+
+
+
+
+
+/**
+ * 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 { mode = 'debounce', time: performanceTime = 200, ignoreFireWhenObserve, options } = performance;
     const countRef = useRef(0);
-    const cb = useEventCallback((...args) => {
+    const cb = useEventCallback((...args)=>{
         if (ignoreFireWhenObserve && countRef.current === 0) {
             countRef.current = 1;
             return;
@@ -1407,20 +2088,18 @@ const useResizeObserver = (target, callback, performance = {}) => {
     });
     const el = getRefElement(target);
     const currentWindow = el ? ownerWindow(el) : window;
-    const observerRef = useResultRef(() => {
+    const observerRef = useResultRef(()=>{
         let resizeCallback;
         if (mode === 'debounce') {
             resizeCallback = debounce(cb, performanceTime, options);
-        }
-        else if (mode === 'throttle') {
+        } else if (mode === 'throttle') {
             resizeCallback = throttle(cb, performanceTime, options);
-        }
-        else {
+        } else {
             resizeCallback = cb;
         }
         return new currentWindow.ResizeObserver(resizeCallback);
     });
-    useLayoutEffect(() => {
+    useLayoutEffect(()=>{
         if (!currentWindow?.ResizeObserver) {
             return;
         }
@@ -1430,110 +2109,193 @@ const useResizeObserver = (target, callback, performance = {}) => {
             throw new Error('please check element exist before bind resize observer');
         }
         observer.observe(el);
-        return () => {
+        return ()=>{
             observer.disconnect();
         };
-    }, [el]);
+    // oxlint-disable-next-line react-hooks/exhaustive-deps
+    }, [
+        el
+    ]);
     return observerRef.current;
 };
 
-const useOverflow = (target, cb, performance = {
+
+
+
+
+
+/**
+ * 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 = {
     mode: 'throttle',
-    time: 200,
-}) => {
+    time: 200
+})=>{
+    // * not have default value for that can trigger change first time.
     const showRef = useRef();
-    return useResizeObserver(target, () => {
+    return useResizeObserver(target, ()=>{
         const element = getRefElement(target);
-        if (!element)
-            return;
+        if (!element) return;
         const { scrollWidth, clientWidth, scrollHeight, clientHeight } = element;
         const show = scrollWidth > clientWidth || scrollHeight > clientHeight;
-        if (showRef.current === show)
-            return;
+        if (showRef.current === show) return;
+        // only emit when state change
         showRef.current = show;
         cb(show, {
             scrollWidth,
             clientWidth,
             scrollHeight,
-            clientHeight,
+            clientHeight
         });
     }, performance);
 };
 
-const useRefState = (value, customUpdate) => {
+
+
+
+
+
+
+/**
+ * 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)=>{
+    // oxlint-disable-next-line react-hooks/rules-of-hooks
     const forceUpdate = customUpdate ?? useForceUpdate();
     const innerValueRef = useRef(value);
-    const setInnerValue = useEventCallback((toValue, isUpdate = true) => {
+    /**
+   * update ref value, set isUpdate to `false` will not trigger re-render
+   */ const setInnerValue = useEventCallback((toValue, /**
+       * is re-render
+       * @default true
+       */ isUpdate = true)=>{
         innerValueRef.current = toValue;
         if (isUpdate) {
             forceUpdate();
         }
     });
-    return [innerValueRef, setInnerValue];
+    return [
+        innerValueRef,
+        setInnerValue
+    ];
 };
 
-const useResponsiveMatch = (defaultBreakpoint) => {
+
+
+
+/**
+ * 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;
-    if (breakpoint === undefined)
-        return {};
+    if (breakpoint === undefined) return {};
     const matchDetail = getMatchDetail(breakpoint);
     return matchDetail.matchMap;
 };
 
-const useSleep = () => {
+
+
+
+
+
+
+/**
+ * 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();
     const sleepingRef = useRef(false);
-    const clearCurrTimeout = () => {
+    const clearCurrTimeout = ()=>{
         const id = timeoutIdRef.current;
         sleepingRef.current = false;
-        if (id !== undefined)
-            clearTimeout(id);
+        if (id !== undefined) clearTimeout(id);
     };
-    const sleep = (time) => new Promise((resolve, reject) => {
-        clearCurrTimeout();
-        sleepingRef.current = true;
-        rejectRef.current = reject;
-        timeoutIdRef.current = setTimeout(() => {
-            sleepingRef.current = false;
-            resolve();
-        }, time);
-    });
-    const cancel = () => {
+    const sleep = (time)=>new Promise((resolve, reject)=>{
+            clearCurrTimeout();
+            sleepingRef.current = true;
+            rejectRef.current = reject;
+            timeoutIdRef.current = setTimeout(()=>{
+                sleepingRef.current = false;
+                resolve();
+            }, time);
+        });
+    const cancel = ()=>{
         clearCurrTimeout();
         rejectRef.current?.();
     };
-    useEffect(() => {
-        return () => {
+    useEffect(()=>{
+        return ()=>{
             clearCurrTimeout();
         };
     }, []);
     return {
-        sleep,
-        cancel,
-        getSleeping: () => sleepingRef.current,
+        /**
+     * 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
     };
 };
 
-const useRetry = (cb, options) => {
+
+
+/* oxlint-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 { sleep, cancel: cancelSleep } = useSleep();
     const isCancelRef = useRef(true);
-    const complete = () => {
+    const complete = ()=>{
         isCancelRef.current = true;
         options?.onComplete?.();
     };
-    const cancel = () => {
+    const cancel = ()=>{
         if (!isCancelRef.current) {
+            // * when outside cancel
             options?.onCancel?.();
             complete();
         }
         cancelSleep();
     };
-    const retry = async (...args) => {
+    const retry = async (...args)=>{
         cancel();
         isCancelRef.current = false;
         options?.onStart?.();
+        // * when exec success, just return directly.
         if (await cb(...args)) {
             if (!isCancelRef.current) {
                 options?.onSuccess?.();
@@ -1541,17 +2303,15 @@ const useRetry = (cb, options) => {
             }
             return;
         }
-        if (!options)
-            return;
+        if (!options) return;
         const { retryTimes, intervalTime, onSuccess } = options;
-        for (let i = 0; i < retryTimes; i++) {
+        for(let i = 0; i < retryTimes; i++){
             if (isCancelRef.current) {
                 return;
             }
             try {
                 await sleep(intervalTime);
-            }
-            catch (error) {
+            } catch (error) {
                 return;
             }
             if (await cb(...args, i)) {
@@ -1565,24 +2325,34 @@ const useRetry = (cb, options) => {
         complete();
     };
     return {
-        retry,
-        cancel,
+        /**
+     * retry method, that will be cancelable with `cancel`,
+     * and when trigger many time that will always clear previous retry
+     */ retry,
+        /**
+     * cancel current retry
+     */ cancel
     };
 };
 
-const useTabOut = (onTabOut) => {
+
+
+
+
+/**
+ * @param onTabOut Callback fired when a "tab out" event is detected.
+ */ const useTabOut = (onTabOut)=>{
     const lastKeyDownIsTabRef = useRef(false);
-    const handleKeyDown = (e) => {
+    const handleKeyDown = (e)=>{
         if (e.key === 'Tab') {
             lastKeyDownIsTabRef.current = true;
         }
     };
-    const handleKeyUp = (e) => {
+    const handleKeyUp = (e)=>{
         lastKeyDownIsTabRef.current = false;
     };
-    const handleBlur = (e) => {
-        if (!e.currentTarget.contains(e.relatedTarget) &&
-            lastKeyDownIsTabRef.current) {
+    const handleBlur = (e)=>{
+        if (!e.currentTarget.contains(e.relatedTarget) && lastKeyDownIsTabRef.current) {
             onTabOut(e);
         }
     };
@@ -1590,63 +2360,153 @@ const useTabOut = (onTabOut) => {
         tabOutHandler: {
             onKeyDown: handleKeyDown,
             onKeyUp: handleKeyUp,
-            onBlur: handleBlur,
-        },
+            onBlur: handleBlur
+        }
     };
 };
 
-const useThrottle = (fn, throttleTime = 200, options) => {
+
+
+
+
+
+
+
+/**
+ * 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
+ */ // oxlint-disable-next-line @typescript-eslint/no-explicit-any
+const useThrottle = (fn, throttleTime = 200, options)=>{
     const memoFn = useEventCallback(fn);
+    // oxlint-disable-next-line react-hooks/exhaustive-deps
     const throttleFn = useCallback(throttle(memoFn, throttleTime, options), []);
-    useEffect(() => () => throttleFn.cancel(), []);
+    // oxlint-disable-next-line react-hooks/exhaustive-deps
+    useEffect(()=>()=>throttleFn.cancel(), []);
     return throttleFn;
 };
 
-const useTestRunnerDetection = () => {
-    return useMemo(() => {
-        return (typeof window !== 'undefined' &&
-            (window.navigator?.webdriver || window.chrome?.webdriver));
+
+
+
+
+/**
+ * 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' && (window.navigator?.webdriver || window.chrome?.webdriver);
     }, []);
 };
 
+
+
 function useTimeout(callback, delay) {
     const savedCallback = useRef(callback);
     savedCallback.current = callback;
-    useEffect(() => {
+    // 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;
         }
-        const id = setTimeout(() => savedCallback.current(), delay);
-        return () => clearTimeout(id);
-    }, [delay]);
+        const id = setTimeout(()=>savedCallback.current(), delay);
+        return ()=>clearTimeout(id);
+    }, [
+        delay
+    ]);
 }
+/* export default */ var useTimeout_useTimeout = ((/* unused pure expression or super */ null && (useTimeout)));
+
 
-const isFontLoadingAPIAvailable = () => {
-    return (typeof document !== 'undefined' &&
-        document.fonts &&
-        typeof document.fonts.ready === 'object' &&
-        typeof document.fonts.ready.then === 'function');
+
+
+
+/**
+ * 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';
 };
-const useFontLoaded = (enabled = true) => {
-    const [loaded, setLoaded] = useState(() => !enabled || !isFontLoadingAPIAvailable());
-    useEffect(() => {
+/**
+ * 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(()=>{
         if (!enabled || !isFontLoadingAPIAvailable()) {
             return;
         }
         let cancelled = false;
-        document.fonts.ready.then(() => {
+        document.fonts.ready.then(()=>{
             if (!cancelled) {
                 setLoaded(true);
             }
         });
-        return () => {
+        return ()=>{
             cancelled = true;
         };
-    }, [enabled]);
+    }, [
+        enabled
+    ]);
     return loaded;
 };
 
-function createInitialState() {
+
+
+
+/**
+ * bodyScrollLock.ts
+ *
+ * Standalone scroll-lock utility with no external runtime dependencies.
+ *
+ * Features
+ * --------
+ * - Pure, caller-managed state: every function accepts an explicit `WindowState` and
+ *   `win`. There are no module-level globals — state lifetime and storage are the
+ *   caller's responsibility (see `useBodyScrollLock.ts` for the per-window storage).
+ * - Ordered lock entries: every lock call registers an entry in insertion
+ *   order. Body lock stays enabled while any entry is active, while all
+ *   entries (active or inactive) may continue to contribute bounded inner
+ *   scrolling boundaries.
+ * - iOS (touchmove-based locking):
+ *     • Active entries decide whether body scroll should currently be locked.
+ *     • All entries may contribute element boundaries or allowTouchMove-based
+ *       inner-scrolling candidates.
+ *     • Matching targets run bounded DOM-walk checks, allowing inner
+ *       scrollables to move until they hit their boundary.
+ *     • Pinch-zoom allowed — skips locking when touches.length > 1 OR when
+ *       ctrlKey is set (covers trackpad-pinch on hybrid devices where the OS
+ *       synthesises a ctrl+touchmove).
+ *     • cancelable guard — never calls preventDefault on non-cancelable events.
+ * - Non-iOS: sets `body { overflow: hidden }` and optionally reserves the
+ *   scrollbar gap to prevent layout shift.
+ *
+ * API
+ * ---
+ * lock(state, win, targetElement?, options?)   — acquire or reactivate a lock entry
+ * unlock(state, win, targetElement?, options?) — remove a lock entry
+ * pause(state, win, targetElement?, options?)  — temporarily disable an entry in place
+ * clearAllLocks(state, win)                     — internal recovery reset for one window
+ *
+ * `targetElement` should be the container element that defines the lock
+ * boundary for an element-scoped lock. It scopes the iOS touch boundary:
+ * scrollable descendants of that container may keep scrolling, while touches
+ * outside it are prevented. Without `targetElement`, the lock is anonymous and
+ * iOS treats it as a pure global body lock.
+ */ function createInitialState() {
     return {
         entries: [],
         savedBodyOverflow: '',
@@ -1656,48 +2516,47 @@ function createInitialState() {
         touchStartY: 0,
         touchStartX: 0,
         nonIOSLocked: false,
-        nonIOSReservedScrollBarGap: false,
+        nonIOSReservedScrollBarGap: false
     };
 }
 function isIOS(win) {
     const { platform, maxTouchPoints, userAgent } = win.navigator;
-    return (/iP(ad|hone|od)/.test(platform) ||
-        (platform === 'MacIntel' && maxTouchPoints > 1) ||
-        /iPad|iPhone|iPod/.test(userAgent));
+    return /iP(ad|hone|od)/.test(platform) || platform === 'MacIntel' && maxTouchPoints > 1 || /iPad|iPhone|iPod/.test(userAgent);
 }
 function isScrollableElement(el, win) {
     const { overflow, overflowX, overflowY } = win.getComputedStyle(el);
-    if (!/(auto|scroll|overlay)/.test(overflow + overflowX + overflowY))
-        return false;
-    return (el.scrollHeight > el.clientHeight + 1 || el.scrollWidth > el.clientWidth + 1);
+    if (!/(auto|scroll|overlay)/.test(overflow + overflowX + overflowY)) return false;
+    return el.scrollHeight > el.clientHeight + 1 || el.scrollWidth > el.clientWidth + 1;
 }
 function isScrollBoundaryHit(scrollable, dx, dy) {
     if (Math.abs(dy) >= Math.abs(dx)) {
-        if (dy > 0 && scrollable.scrollTop <= 0)
-            return true;
-        return (dy < 0 &&
-            scrollable.scrollTop + scrollable.clientHeight >=
-                scrollable.scrollHeight - 1);
+        if (dy > 0 && scrollable.scrollTop <= 0) return true;
+        return dy < 0 && scrollable.scrollTop + scrollable.clientHeight >= scrollable.scrollHeight - 1;
     }
-    if (dx > 0 && scrollable.scrollLeft <= 0)
-        return true;
-    return (dx < 0 &&
-        scrollable.scrollLeft + scrollable.clientWidth >= scrollable.scrollWidth - 1);
+    if (dx > 0 && scrollable.scrollLeft <= 0) return true;
+    return dx < 0 && scrollable.scrollLeft + scrollable.clientWidth >= scrollable.scrollWidth - 1;
 }
-function findNearestScrollableAncestorWithinBoundary(el, win, boundary) {
+/**
+ * Walk up the DOM from `el` to find the nearest scrollable ancestor.
+ *
+ * Always stops before `<body>` and `<html>` so body scroll is never returned.
+ * When `boundary` is provided (element lock), the walk also stops at that
+ * container element, preventing it from finding scrollable ancestors outside
+ * the active lock boundary. When `boundary` is null (anonymous lock), the walk
+ * has no element boundary of its own and may find scrollable elements higher in
+ * the tree.
+ */ function findNearestScrollableAncestorWithinBoundary(el, win, boundary) {
     const { body, documentElement } = win.document;
     let cur = el;
-    while (cur && cur !== body && cur !== documentElement) {
-        if (isScrollableElement(cur, win))
-            return cur;
-        if (cur === boundary)
-            break;
+    while(cur && cur !== body && cur !== documentElement){
+        if (isScrollableElement(cur, win)) return cur;
+        if (cur === boundary) break;
         cur = cur.parentElement;
     }
     return null;
 }
 function getActiveEntries(state) {
-    return state.entries.filter((entry) => entry.active);
+    return state.entries.filter((entry)=>entry.active);
 }
 function getBoundaryForEntry(topEntry) {
     return topEntry.kind === 'element' ? topEntry.element : null;
@@ -1716,10 +2575,9 @@ function getEntryScopedScrollable(topEntry, target, win, { allowAnonymous = fals
     return getScrollableWithinBoundary(target, win, boundary);
 }
 function getAllowTouchMoveScrollable(entry, target, win) {
-    if (entry.allowTouchMove?.(target) !== true)
-        return null;
+    if (entry.allowTouchMove?.(target) !== true) return null;
     return getEntryScopedScrollable(entry, target, win, {
-        allowAnonymous: true,
+        allowAnonymous: true
     });
 }
 function canEntryAllowInnerScroll(entry, target, win, dx, dy) {
@@ -1735,10 +2593,10 @@ function canEntryAllowInnerScroll(entry, target, win, dx, dy) {
 }
 function findEntryIndex(state, targetElement, entryKey) {
     if (entryKey) {
-        return state.entries.findIndex((entry) => entry.key === entryKey);
+        return state.entries.findIndex((entry)=>entry.key === entryKey);
     }
     if (targetElement) {
-        for (let i = state.entries.length - 1; i >= 0; i--) {
+        for(let i = state.entries.length - 1; i >= 0; i--){
             const entry = state.entries[i];
             if (entry.kind === 'element' && entry.element === targetElement) {
                 return i;
@@ -1746,7 +2604,7 @@ function findEntryIndex(state, targetElement, entryKey) {
         }
         return -1;
     }
-    for (let i = state.entries.length - 1; i >= 0; i--) {
+    for(let i = state.entries.length - 1; i >= 0; i--){
         if (state.entries[i].kind === 'anonymous') {
             return i;
         }
@@ -1770,32 +2628,26 @@ function ensureEntry(state, targetElement, options = {}) {
         element: targetElement ?? null,
         active: true,
         reserveScrollBarGap: Boolean(options.reserveScrollBarGap),
-        allowTouchMove: options.allowTouchMove,
+        allowTouchMove: options.allowTouchMove
     };
     state.entries.push(entry);
     return entry;
 }
 function shouldPreventTouchMove(e, state, win) {
-    if (e.touches.length > 1)
-        return false;
-    if (e.ctrlKey)
-        return false;
-    if (!e.cancelable)
-        return false;
+    if (e.touches.length > 1) return false;
+    if (e.ctrlKey) return false;
+    if (!e.cancelable) return false;
     const touch = e.touches[0];
-    if (!touch)
-        return false;
+    if (!touch) return false;
     const dy = touch.clientY - state.touchStartY;
     const dx = touch.clientX - state.touchStartX;
-    if (dy === 0 && dx === 0)
-        return false;
-    if (getActiveEntries(state).length === 0)
-        return false;
+    if (dy === 0 && dx === 0) return false;
+    if (getActiveEntries(state).length === 0) return false;
     const target = e.target;
     if (!(target instanceof win.Element)) {
         return true;
     }
-    for (let i = state.entries.length - 1; i >= 0; i--) {
+    for(let i = state.entries.length - 1; i >= 0; i--){
         if (canEntryAllowInnerScroll(state.entries[i], target, win, dx, dy)) {
             return false;
         }
@@ -1804,22 +2656,28 @@ function shouldPreventTouchMove(e, state, win) {
 }
 function lockIOS(state, win) {
     const doc = win.document;
-    state.docTouchStartHandler = (e) => {
+    // touchStartY/X are reset to 0 when listeners are first attached. If a touch
+    // gesture is already in progress when the lock activates, the first touchmove
+    // will compute dx/dy relative to (0,0) rather than the actual start point.
+    // There is no Web API to read current touch coordinates without an event, so
+    // this is an accepted limitation: one touchmove event may fire incorrect
+    // boundary checks until the next touchstart resets the baseline.
+    state.docTouchStartHandler = (e)=>{
         if (e.touches.length > 0) {
             state.touchStartY = e.touches[0].clientY;
             state.touchStartX = e.touches[0].clientX;
         }
     };
-    state.docTouchMoveHandler = (e) => {
+    state.docTouchMoveHandler = (e)=>{
         if (shouldPreventTouchMove(e, state, win)) {
             e.preventDefault();
         }
     };
     doc.addEventListener('touchstart', state.docTouchStartHandler, {
-        passive: true,
+        passive: true
     });
     doc.addEventListener('touchmove', state.docTouchMoveHandler, {
-        passive: false,
+        passive: false
     });
 }
 function unlockIOS(state, win) {
@@ -1850,28 +2708,30 @@ function unlockNonIOS(state, win) {
     if (state.savedBodyPaddingRight !== null) {
         if (state.savedBodyPaddingRight === '') {
             body.style.removeProperty('padding-right');
-        }
-        else {
+        } else {
             body.style.paddingRight = state.savedBodyPaddingRight;
         }
         state.savedBodyPaddingRight = null;
     }
 }
+// Non-iOS keeps body overflow locked while any entry remains active.
 function bodyLockDesired(state) {
     return getActiveEntries(state).length > 0;
 }
+// Scrollbar-gap compensation is aggregated across active entries so stacked
+// locks do not add/remove body padding while the window remains locked.
 function shouldReserveScrollBarGap(state) {
-    return state.entries.some((entry) => entry.active && entry.reserveScrollBarGap);
+    return state.entries.some((entry)=>entry.active && entry.reserveScrollBarGap);
 }
 function syncIOS(state, win) {
+    // Listeners stay attached while any entry exists so disabled entries can
+    // continue contributing inner-scroll boundaries without repeated churn.
     const desired = state.entries.length > 0;
     const attached = state.docTouchMoveHandler !== null;
-    if (desired === attached)
-        return;
+    if (desired === attached) return;
     if (desired) {
         lockIOS(state, win);
-    }
-    else {
+    } else {
         unlockIOS(state, win);
     }
 }
@@ -1879,8 +2739,7 @@ function syncNonIOS(state, win) {
     const desired = bodyLockDesired(state);
     const reserveScrollBarGap = shouldReserveScrollBarGap(state);
     if (!desired) {
-        if (!state.nonIOSLocked)
-            return;
+        if (!state.nonIOSLocked) return;
         unlockNonIOS(state, win);
         state.nonIOSLocked = false;
         state.nonIOSReservedScrollBarGap = false;
@@ -1888,23 +2747,23 @@ function syncNonIOS(state, win) {
     }
     if (!state.nonIOSLocked) {
         lockNonIOS(state, win, {
-            reserveScrollBarGap,
+            reserveScrollBarGap
         });
         state.nonIOSLocked = true;
         state.nonIOSReservedScrollBarGap = reserveScrollBarGap;
         return;
     }
-    if (reserveScrollBarGap === state.nonIOSReservedScrollBarGap)
-        return;
+    if (reserveScrollBarGap === state.nonIOSReservedScrollBarGap) return;
     unlockNonIOS(state, win);
-    lockNonIOS(state, win, { reserveScrollBarGap });
+    lockNonIOS(state, win, {
+        reserveScrollBarGap
+    });
     state.nonIOSReservedScrollBarGap = reserveScrollBarGap;
 }
 function syncScrollLock(state, win) {
     if (isIOS(win)) {
         syncIOS(state, win);
-    }
-    else {
+    } else {
         syncNonIOS(state, win);
     }
 }
@@ -1913,23 +2772,50 @@ function activateEntry(state, win, targetElement, options = {}) {
     entry.active = true;
     syncScrollLock(state, win);
 }
-function lock(state, win, targetElement, options = {}) {
+/**
+ * Acquire or re-enable a body-scroll lock entry. Calling on a paused entry
+ * re-activates it without changing its position in the stack.
+ */ function lock(state, win, targetElement, options = {}) {
     activateEntry(state, win, targetElement, options);
 }
-function unlock(state, win, targetElement, options = {}) {
+/**
+ * Release a body-scroll lock entry.
+ *
+ * When `options.entryKey` is provided, it takes precedence and removes that
+ * exact entry.
+ * `unlock()` without a target only removes the most recent anonymous entry.
+ * `unlock(targetElement)` removes the most recent matching element entry.
+ */ function unlock(state, win, targetElement, options = {}) {
     const index = findEntryIndex(state, targetElement, options.entryKey);
-    if (index < 0)
-        return;
+    if (index < 0) return;
     state.entries.splice(index, 1);
     syncScrollLock(state, win);
 }
-function pause(state, win, targetElement, options = {}) {
+/**
+ * Temporarily disable a lock entry without changing its position in the stack.
+ */ function bodyScrollLock_pause(state, win, targetElement, options = {}) {
     const index = findEntryIndex(state, targetElement, options.entryKey);
-    if (index < 0 || state.entries[index].active === false)
-        return;
+    if (index < 0 || state.entries[index].active === false) return;
     state.entries[index].active = false;
     syncScrollLock(state, win);
 }
+/**
+ * Internal recovery helper: forcibly clear all lock entries and restore the
+ * window to an unlocked state.
+ *
+ * This bypasses normal per-entry lock/pause/unlock lifecycles and is intended
+ * for testing or emergency recovery only.
+ */ function clearAllLocks(state, win) {
+    state.entries = [];
+    if (state.docTouchStartHandler || state.docTouchMoveHandler) {
+        unlockIOS(state, win);
+    }
+    if (state.nonIOSLocked || state.savedBodyOverflow !== '' || state.savedBodyPaddingRight !== null) {
+        unlockNonIOS(state, win);
+    }
+    Object.assign(state, createInitialState());
+}
+
 
 const SCROLL_LOCK_KEY = '__SUI_SCROLL_LOCK__';
 function getStoredScrollLockState(win) {
@@ -1940,66 +2826,120 @@ function setStoredScrollLockState(win, state) {
     global[SCROLL_LOCK_KEY] = state;
     return state;
 }
-function getOrCreateScrollLockState(win) {
+/**
+ * Get (or lazily create) the scroll-lock state for a given window.
+ * State is stored on the window object under a unique key so it is
+ * automatically isolated per window.
+ */ function getOrCreateScrollLockState(win) {
     const state = getStoredScrollLockState(win);
     if (!state) {
         return setStoredScrollLockState(win, createInitialState());
     }
     return state;
 }
+function deleteStoredScrollLockState(win) {
+    delete win[SCROLL_LOCK_KEY];
+}
+
+
+
+
+
 
 function applyLockState(state, win, targetElement, options, disabled) {
     lock(state, win, targetElement, options);
     if (disabled) {
-        pause(state, win, targetElement, options);
+        bodyScrollLock_pause(state, win, targetElement, options);
     }
 }
 function useResolvedElement(target) {
-    const [resolvedElement, setResolvedElement] = useState(() => (getRefElement(target) ?? null));
+    const [resolvedElement, setResolvedElement] = useState(()=>getRefElement(target) ?? null);
     const targetRef = useRef(target);
     targetRef.current = target;
-    useEffect(() => {
-        const nextResolvedElement = (getRefElement(targetRef.current) ??
-            null);
-        setResolvedElement((current) => current === nextResolvedElement ? current : nextResolvedElement);
+    // Re-evaluate after each render so a stable ref object can still refresh the
+    // resolved element when ref.current appears or changes after commit.
+    // oxlint-disable-next-line react-hooks/exhaustive-deps
+    useEffect(()=>{
+        const nextResolvedElement = getRefElement(targetRef.current) ?? null;
+        setResolvedElement((current)=>current === nextResolvedElement ? current : nextResolvedElement);
     });
     return resolvedElement;
 }
-const useBodyScrollLock = (isLocked, targetElement, options = {}) => {
+/**
+ * Lock body scroll while allowing bounded inner scrolling within an optional
+ * target container.
+ *
+ * `targetElement` may be a concrete `HTMLElement` or a React `RefObject`.
+ * When wiring this hook to a React overlay container, prefer passing a
+ * concrete element from a callback ref / state bridge so the lock updates as
+ * soon as the DOM node becomes available.
+ *
+ * @example
+ * ```tsx
+ * const [targetElement, setTargetElement] = useState<HTMLDivElement | null>(null);
+ *
+ * useBodyScrollLock(open, targetElement);
+ *
+ * return <div ref={setTargetElement}>...</div>;
+ * ```
+ *
+ * @example
+ * ```tsx
+ * const targetElement = document.querySelector<HTMLElement>('#drawer-root');
+ *
+ * useBodyScrollLock(open, targetElement);
+ * ```
+ */ const useBodyScrollLock = (isLocked, targetElement, options = {})=>{
     const { disabled = false, reserveScrollBarGap = true } = options;
     const { allowTouchMove } = options;
     const entryKeyRef = useRef(Symbol('use-body-scroll-lock-entry'));
     const resolvedElement = useResolvedElement(targetElement);
+    // globalThis is always defined including SSR; in a browser globalThis === window,
+    // so the Win cast below is safe.
     const { globalThis: global } = useWindowContext();
-    useEffect(() => {
-        if (!isLocked)
-            return;
+    // Lifetime: create one stable entry per hook instance while locked, even if
+    // the resolved element is still null. The follow-up sync effect upgrades
+    // anonymous → element in place once a concrete target becomes available.
+    useEffect(()=>{
+        if (!isLocked) return;
         const win = global;
         const state = getOrCreateScrollLockState(global);
         const entryKey = entryKeyRef.current;
         const syncOptions = {
             reserveScrollBarGap,
             allowTouchMove,
-            entryKey,
+            entryKey
         };
         applyLockState(state, win, resolvedElement, syncOptions, disabled);
-        return () => {
+        return ()=>{
+            // Read the current live state rather than the captured one so that an
+            // external clearAllLocks + delete cycle doesn't leave a dangling entry
+            // in a freshly-created state object.
             const currentState = getStoredScrollLockState(global);
             if (currentState) {
-                unlock(currentState, win, resolvedElement, { entryKey });
+                unlock(currentState, win, resolvedElement, {
+                    entryKey
+                });
             }
         };
-    }, [isLocked, global]);
-    useEffect(() => {
-        if (!isLocked)
-            return;
+    // targetElement and disabled are intentionally omitted so this entry keeps
+    // its original stack position while the sync effect below mutates it.
+    // oxlint-disable-next-line react-hooks/exhaustive-deps
+    }, [
+        isLocked,
+        global
+    ]);
+    // Sync current kind (anonymous vs element), disabled state, and gap preference
+    // onto the stable entry without changing insertion order.
+    useEffect(()=>{
+        if (!isLocked) return;
         const win = global;
         const state = getOrCreateScrollLockState(global);
         const entryKey = entryKeyRef.current;
         const syncOptions = {
             reserveScrollBarGap,
             allowTouchMove,
-            entryKey,
+            entryKey
         };
         applyLockState(state, win, resolvedElement, syncOptions, disabled);
     }, [
@@ -2008,18 +2948,95 @@ const useBodyScrollLock = (isLocked, targetElement, options = {}) => {
         isLocked,
         global,
         resolvedElement,
-        reserveScrollBarGap,
+        reserveScrollBarGap
     ]);
 };
 
-const useVirtuosoExternalWindow = () => {
+
+
+
+/**
+ * Hook to get external window props for Virtuoso component.
+ *
+ * The 'externalWindow' prop exists only in the forked version of Virtuoso.
+ * Passing 'externalWindow' to the original Virtuoso component will result in a React error.
+ *
+ * If 'externalWindow' is present in the context, it indicates that the user is using the forked version.
+ * Therefore, we only return 'externalWindow' when it exists and is not the same as the global window,
+ * ensuring compatibility with detached window scenarios.
+ *
+ * @returns Props object with externalWindow if in detached window context, undefined otherwise
+ *
+ * @example
+ * ```tsx
+ * const externalWindowProps = useVirtuosoExternalWindow();
+ *
+ * return (
+ *   <Virtuoso
+ *     {...externalWindowProps}
+ *     // other props
+ *   />
+ * );
+ * ```
+ */ const useVirtuosoExternalWindow = ()=>{
     const { externalWindow } = useWindowContext();
+    // Only return externalWindow props when window is not the same as the global window
+    // This is needed for detached window scenarios with the forked virtuoso
     if (externalWindow && externalWindow !== globalThis.window) {
         return {
-            externalWindow,
+            externalWindow
         };
     }
     return undefined;
 };
 
-export { createGlobalListener, globalListenerEventMap, isElmEqualOrContain, isTouchEvent, moveIndexInTwoDimension, teardown, useA11yKeyEvent, useActive, useAnnouncer, useAriaHideOutside, useAudio, useBodyScrollLock, useButton, useChange, useClickAway, useDebounce, useDepsChange, useEventCallback, useEventListener, useEver, useFocusVisible, useFontLoaded, useForceUpdate, useForkRef, useGlobalAnnouncer, useGlobalListener, useHiddenTabindex, useHover, useHoverDirty, useId, useImgLoaded, useInterval, useIsFocusVisible, useKeyDownOnce, useKeyboardMoveFocus, useLongPress, useMountState, useOnLayoutReRender, useOnReRender, useOnlyOneFocusable, useOverflow, usePrevious, useRefState, useResizeObserver, useResponsiveMatch, useResultRef, useRetry, useSleep, useTabOut, useTestRunnerDetection, useThrottle, useTimeout, useTouchMouseEvent, useVirtuosoExternalWindow };
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+export { createGlobalListener, globalListenerEventMap, isElmEqualOrContain, isTouchEvent, moveIndexInTwoDimension, teardown, unstable_useControlled as useControlled, useA11yKeyEvent, useActive, useAnnouncer, useAriaHideOutside, useAudio, useBodyScrollLock, useButton_useButton as useButton, useChange, useClickAway, useDebounce, useDepsChange, useEventCallback, useEventListener, useEver, useFocusVisible, useFontLoaded, useForceUpdate, useForkRef, useGlobalAnnouncer, useGlobalListener, useHiddenTabindex, useHover, useHoverDirty, useId, useImgLoaded, useInterval, useIsFocusVisible, useKeyDownOnce, useKeyboardMoveFocus, useLongPress, useMountState, useOnLayoutReRender, useOnReRender, useOnlyOneFocusable, useOverflow, usePrevious, useRefState, useResizeObserver, useResponsiveMatch, useResultRef, useRetry, useSleep, useTabOut, useTestRunnerDetection, useThrottle, useTimeout, useTouchMouseEvent, useVirtuosoExternalWindow };