@ringcentral/spring-base 1.11.0 → 1.11.2

package/chunks/twMerge.js

@@ -7,12 +7,16 @@ import { extendTailwindMerge } from 'tailwind-merge';
 const ownerWindow = unstable_ownerWindow;
 
 const ARIA_HIDDEN = 'aria-hidden';
-const REF_COUNT_MAP = '__SUI_ARIA_HIDE_OUTSIDE_REF_COUNT_MAP__';
-const getRefCountMap = (window) => {
-    if (!window[REF_COUNT_MAP]) {
-        window[REF_COUNT_MAP] = new WeakMap();
+const TOP_LAYER_ATTR = 'data-sui-top-layer';
+const alwaysVisibleSelector = `[data-live-announcer="true"], [${TOP_LAYER_ATTR}]`;
+const ARIA_HIDDEN_REF_COUNT_MAP = '__SUI_ARIA_HIDE_OUTSIDE_REF_COUNT_MAP__';
+const INERT_REF_COUNT_MAP = '__SUI_ARIA_HIDE_OUTSIDE_INERT_REF_COUNT_MAP__';
+const getRefCountMap = (window, mechanism) => {
+    const key = mechanism === 'inert' ? INERT_REF_COUNT_MAP : ARIA_HIDDEN_REF_COUNT_MAP;
+    if (!window[key]) {
+        window[key] = new WeakMap();
     }
-    return window[REF_COUNT_MAP];
+    return window[key];
 };
 const OBSERVER_STACK = '__SUI_ARIA_HIDE_OUTSIDE_OBSERVER_STACK__';
 const getObserverStack = (window) => {
@@ -21,109 +25,316 @@ const getObserverStack = (window) => {
     }
     return window[OBSERVER_STACK];
 };
-const isHTMLOrSVGElement = (node) => {
-    return 'dataset' in node;
-};
 const isElement = (node) => {
-    return node.nodeType === Node.ELEMENT_NODE;
+    return (typeof node === 'object' &&
+        node != null &&
+        'nodeType' in node &&
+        node.nodeType === 1);
+};
+const isAlwaysVisibleNode = (node) => {
+    return (node.getAttribute('data-live-announcer') === 'true' ||
+        node.hasAttribute(TOP_LAYER_ATTR));
 };
-const ariaHideOutside = (targets, root = document.body) => {
-    const currentWindow = ownerWindow(root);
+const createAriaHideOutsideController = (targets, options = {}) => {
+    const isLegacyRoot = isElement(options);
+    const configuredRoot = isLegacyRoot
+        ? options
+        : options.root;
+    const currentWindow = ownerWindow(configuredRoot ?? targets[0]);
     if (!currentWindow) {
-        return () => { };
+        return {
+            addTarget: () => { },
+            removeTarget: () => { },
+            dispose: () => { },
+        };
     }
+    const root = configuredRoot ?? currentWindow.document.body;
+    const shouldUseInert = !isLegacyRoot &&
+        options.shouldUseInert &&
+        'inert' in currentWindow.HTMLElement.prototype;
     const visibleNodes = new Set(targets);
+    const targetNodes = new Set(targets);
+    const automaticVisibleNodes = new Set();
     const hiddenNodes = new Set();
-    const refCountMap = getRefCountMap(currentWindow);
-    const observerStack = getObserverStack(currentWindow);
-    const walker = currentWindow.document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT, {
-        acceptNode(node) {
-            if (isHTMLOrSVGElement(node) &&
-                node.dataset['liveAnnouncer'] === 'true') {
-                visibleNodes.add(node);
+    const targetPaths = new Map();
+    const getTargetPath = (target) => {
+        const path = [];
+        let node = target;
+        while (node && root.contains(node)) {
+            path.push(node);
+            if (node === root) {
+                break;
             }
-            if (visibleNodes.has(node) ||
-                (node.parentElement &&
-                    hiddenNodes.has(node.parentElement) &&
-                    node.parentElement.getAttribute('role') !== 'row')) {
-                return NodeFilter.FILTER_REJECT;
-            }
-            if (targets.some((target) => node.contains(target))) {
-                return NodeFilter.FILTER_SKIP;
-            }
-            return NodeFilter.FILTER_ACCEPT;
-        },
-    });
+            node = node.parentElement;
+        }
+        return path;
+    };
+    for (const target of targets) {
+        targetPaths.set(target, getTargetPath(target));
+    }
+    const observerStack = getObserverStack(currentWindow);
+    const getHideMechanism = (node) => shouldUseInert && node instanceof currentWindow.HTMLElement
+        ? 'inert'
+        : 'aria-hidden';
+    const getHidden = (node, mechanism) => mechanism === 'inert'
+        ? node.inert
+        : node.getAttribute(ARIA_HIDDEN) === 'true';
+    const setHidden = (node, mechanism, hidden) => {
+        if (mechanism === 'inert') {
+            node.inert = hidden;
+        }
+        else if (hidden) {
+            node.setAttribute(ARIA_HIDDEN, 'true');
+        }
+        else {
+            node.removeAttribute(ARIA_HIDDEN);
+        }
+    };
+    const restoreHiddenNode = (node) => {
+        if (!hiddenNodes.delete(node)) {
+            return;
+        }
+        const mechanism = getHideMechanism(node);
+        const refCountMap = getRefCountMap(currentWindow, mechanism);
+        const count = refCountMap.get(node);
+        if (typeof count !== 'number') {
+            return;
+        }
+        if (count === 1) {
+            setHidden(node, mechanism, false);
+            refCountMap.delete(node);
+        }
+        else {
+            refCountMap.set(node, count - 1);
+        }
+    };
     const hide = (node) => {
+        const mechanism = getHideMechanism(node);
+        const refCountMap = getRefCountMap(currentWindow, mechanism);
         const refCount = refCountMap.get(node) ?? 0;
-        if (node.getAttribute(ARIA_HIDDEN) === 'true' && refCount === 0) {
+        if (getHidden(node, mechanism) && refCount === 0) {
             return;
         }
         if (refCount === 0) {
-            node.setAttribute(ARIA_HIDDEN, 'true');
+            setHidden(node, mechanism, true);
         }
         hiddenNodes.add(node);
         refCountMap.set(node, refCount + 1);
     };
+    const addAlwaysVisibleNode = (node) => {
+        automaticVisibleNodes.add(node);
+        visibleNodes.add(node);
+    };
+    const addAlwaysVisibleNodes = (node) => {
+        if (isAlwaysVisibleNode(node)) {
+            addAlwaysVisibleNode(node);
+        }
+        for (const alwaysVisibleNode of node.querySelectorAll(alwaysVisibleSelector)) {
+            addAlwaysVisibleNode(alwaysVisibleNode);
+        }
+    };
+    const removeDisconnectedAlwaysVisibleNodes = (node) => {
+        for (const alwaysVisibleNode of automaticVisibleNodes) {
+            if (!node.contains(alwaysVisibleNode) ||
+                root.contains(alwaysVisibleNode)) {
+                continue;
+            }
+            automaticVisibleNodes.delete(alwaysVisibleNode);
+            if (!targetNodes.has(alwaysVisibleNode)) {
+                visibleNodes.delete(alwaysVisibleNode);
+            }
+        }
+    };
+    const containsNode = (nodes, node) => {
+        for (const candidate of nodes) {
+            if (candidate.contains(node)) {
+                return true;
+            }
+        }
+        return false;
+    };
+    const containsVisibleNode = (node, nodes) => {
+        for (const visibleNode of nodes) {
+            if (node.contains(visibleNode)) {
+                return true;
+            }
+        }
+        return false;
+    };
+    const isCoveredByHiddenNode = (node) => {
+        let ancestor = node.parentElement;
+        while (ancestor && root.contains(ancestor)) {
+            if (hiddenNodes.has(ancestor)) {
+                return !(ancestor === node.parentElement &&
+                    ancestor.getAttribute('role') === 'row');
+            }
+            ancestor = ancestor.parentElement;
+        }
+        return false;
+    };
+    const shouldAdoptHiddenNode = (node) => {
+        return (root.contains(node) &&
+            !hiddenNodes.has(node) &&
+            !containsNode(visibleNodes, node) &&
+            !containsVisibleNode(node, visibleNodes) &&
+            !isCoveredByHiddenNode(node));
+    };
+    const acceptNode = (node) => {
+        if (visibleNodes.has(node) ||
+            (node.parentElement &&
+                hiddenNodes.has(node.parentElement) &&
+                node.parentElement.getAttribute('role') !== 'row')) {
+            return currentWindow.NodeFilter.FILTER_REJECT;
+        }
+        if (containsVisibleNode(node, visibleNodes)) {
+            return currentWindow.NodeFilter.FILTER_SKIP;
+        }
+        return currentWindow.NodeFilter.FILTER_ACCEPT;
+    };
+    const walk = (walkRoot, includeRoot) => {
+        addAlwaysVisibleNodes(walkRoot);
+        const rootFilter = acceptNode(walkRoot);
+        if (includeRoot && rootFilter === currentWindow.NodeFilter.FILTER_ACCEPT) {
+            hide(walkRoot);
+        }
+        if (rootFilter === currentWindow.NodeFilter.FILTER_REJECT) {
+            return;
+        }
+        const walker = currentWindow.document.createTreeWalker(walkRoot, currentWindow.NodeFilter.SHOW_ELEMENT, { acceptNode });
+        let node = walker.nextNode();
+        while (node != null) {
+            hide(node);
+            node = walker.nextNode();
+        }
+    };
+    const addTarget = (target) => {
+        if (!root.contains(target)) {
+            return;
+        }
+        targetNodes.add(target);
+        visibleNodes.add(target);
+        const path = getTargetPath(target);
+        for (const node of path) {
+            restoreHiddenNode(node);
+        }
+        targetPaths.set(target, path);
+    };
+    const removeTarget = (target) => {
+        if (!targetNodes.delete(target)) {
+            return;
+        }
+        if (!automaticVisibleNodes.has(target)) {
+            visibleNodes.delete(target);
+        }
+        const targetPath = targetPaths.get(target);
+        targetPaths.delete(target);
+        const connectedAncestor = targetPath?.find((node) => root.contains(node));
+        if (!connectedAncestor) {
+            return;
+        }
+        let walkRoot = connectedAncestor;
+        while (walkRoot.parentElement &&
+            walkRoot.parentElement !== root &&
+            !containsVisibleNode(walkRoot.parentElement, visibleNodes)) {
+            walkRoot = walkRoot.parentElement;
+        }
+        walk(walkRoot, true);
+    };
     if (observerStack.length) {
         observerStack[observerStack.length - 1].disconnect();
     }
-    let node = walker.nextNode();
-    while (node != null) {
-        hide(node);
-        node = walker.nextNode();
-    }
-    const observer = new currentWindow.MutationObserver((changes) => {
+    walk(root, false);
+    const processChanges = (changes) => {
         for (const change of changes) {
-            if (change.type !== 'childList' || change.addedNodes.length === 0) {
+            if (change.type !== 'childList') {
+                continue;
+            }
+            for (const node of change.removedNodes) {
+                if (isElement(node)) {
+                    removeDisconnectedAlwaysVisibleNodes(node);
+                }
+            }
+            if (!change.target.isConnected || change.addedNodes.length === 0) {
                 continue;
             }
-            if (![...visibleNodes, ...hiddenNodes].some((node) => node.contains(change.target))) {
+            if (!containsNode(visibleNodes, change.target) &&
+                !containsNode(hiddenNodes, change.target)) {
                 for (const node of change.addedNodes) {
-                    if (isHTMLOrSVGElement(node) &&
-                        node.dataset['liveAnnouncer'] === 'true') {
-                        visibleNodes.add(node);
-                    }
-                    else if (isElement(node)) {
-                        hide(node);
+                    if (isElement(node) && root.contains(node)) {
+                        walk(node, true);
                     }
                 }
             }
         }
-    });
+    };
+    const observer = new currentWindow.MutationObserver(processChanges);
     observer.observe(root, { childList: true, subtree: true });
     const observerWrapper = {
         observe() {
             observer.observe(root, { childList: true, subtree: true });
         },
+        resume(releasedHiddenNodes, releasedAlwaysVisibleNodes) {
+            for (const node of releasedAlwaysVisibleNodes) {
+                if (root.contains(node)) {
+                    addAlwaysVisibleNode(node);
+                }
+            }
+            for (const node of releasedHiddenNodes) {
+                if (shouldAdoptHiddenNode(node)) {
+                    hide(node);
+                }
+            }
+            observerWrapper.observe();
+        },
         disconnect() {
             observer.disconnect();
         },
     };
     observerStack.push(observerWrapper);
-    return () => {
-        observer.disconnect();
-        for (const node of hiddenNodes) {
-            const count = refCountMap.get(node);
-            if (count === 1) {
-                node.removeAttribute(ARIA_HIDDEN);
-                refCountMap.delete(node);
-            }
-            else if (typeof count === 'number') {
-                refCountMap.set(node, count - 1);
-            }
+    let isCleanedUp = false;
+    const dispose = () => {
+        if (isCleanedUp) {
+            return;
         }
+        isCleanedUp = true;
+        const pendingChanges = observer.takeRecords();
+        observer.disconnect();
+        processChanges(pendingChanges);
         if (observerWrapper === observerStack[observerStack.length - 1]) {
             observerStack.pop();
-            if (observerStack.length) {
-                observerStack[observerStack.length - 1].observe();
+            const previousObserver = observerStack[observerStack.length - 1];
+            if (previousObserver?.resume) {
+                previousObserver.resume(hiddenNodes, automaticVisibleNodes);
+            }
+            else {
+                previousObserver?.observe();
             }
         }
         else {
             observerStack.splice(observerStack.indexOf(observerWrapper), 1);
         }
+        for (const node of [...hiddenNodes]) {
+            restoreHiddenNode(node);
+        }
+        targetPaths.clear();
+        targetNodes.clear();
+        automaticVisibleNodes.clear();
+    };
+    return {
+        addTarget: (target) => {
+            if (!isCleanedUp) {
+                addTarget(target);
+            }
+        },
+        removeTarget: (target) => {
+            if (!isCleanedUp) {
+                removeTarget(target);
+            }
+        },
+        dispose,
     };
 };
+const ariaHideOutside = (targets, options = {}) => createAriaHideOutsideController(targets, options).dispose;
 
 const combineProps = (baseProps, newProps, coverPropKeys) => innerCombineProps({
     baseProps,
@@ -273,4 +484,4 @@ const twMerge = extendTailwindMerge({
     },
 });
 
-export { ariaHideOutside as a, combineClasses as b, combineProps as c, getRefElement as g, isRef as i, logInDev as l, ownerWindow as o, twMerge as t };
+export { ariaHideOutside as a, combineClasses as b, combineProps as c, createAriaHideOutsideController as d, getRefElement as g, isRef as i, logInDev as l, ownerWindow as o, twMerge as t };

package/hooks.js

@@ -5,7 +5,7 @@ import { useState, useRef, useEffect, useCallback, useLayoutEffect, useMemo } fr
 import { useWindowContext, useResponsiveContext, getMatchDetail } from './contexts.js';
 import uniqueId from 'lodash/uniqueId';
 import { useButton as useButton$1 } from '@mui/base/useButton';
-import { c as combineProps, a as ariaHideOutside, g as getRefElement, l as logInDev, o as ownerWindow } from './chunks/twMerge.js';
+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';
@@ -241,18 +241,42 @@ function useButton(parameters) {
 }
 
 const useAriaHideOutside = (props = {}) => {
-    const { enable = true } = props;
-    const { externalWindow, document } = useWindowContext();
+    const { enable = true, shouldUseInert = false } = props;
+    const { document } = useWindowContext();
     const ariaHideOutsideRef = useRef(null);
-    useEffect(() => {
+    const branchNodesRef = useRef(new Set());
+    const controllerRef = useRef();
+    const setAriaHideOutsideTarget = useCallback((node, isActive) => {
+        if (isActive) {
+            branchNodesRef.current.add(node);
+            controllerRef.current?.addTarget(node);
+        }
+        else {
+            branchNodesRef.current.delete(node);
+            controllerRef.current?.removeTarget(node);
+        }
+    }, []);
+    useLayoutEffect(() => {
         if (enable && ariaHideOutsideRef.current) {
-            return ariaHideOutside([ariaHideOutsideRef.current], document?.body);
+            const controller = createAriaHideOutsideController([ariaHideOutsideRef.current, ...branchNodesRef.current], {
+                root: document?.body,
+                shouldUseInert,
+            });
+            controllerRef.current = controller;
+            return () => {
+                if (controllerRef.current === controller) {
+                    controllerRef.current = undefined;
+                }
+                controller.dispose();
+            };
         }
+        controllerRef.current = undefined;
         return undefined;
-    }, [enable, externalWindow, document?.body]);
+    }, [enable, shouldUseInert, document?.body]);
     return {
         ariaHideOutsideRef: ariaHideOutsideRef,
         ariaHideEnabled: enable,
+        setAriaHideOutsideTarget,
     };
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ringcentral/spring-base",
-  "version": "1.11.0",
+  "version": "1.11.2",
   "author": "RingCentral",
   "description": "Core utilities, hooks, and foundational functionality for Spring UI components, providing essential building blocks for React applications",
   "main": "./index.js",

package/src/hooks/useAriaHideOutside/useAriaHideOutside.d.ts

@@ -1,8 +1,10 @@
 /// <reference types="react" />
 export type UseAriaHideOutsideProps = {
     enable?: boolean;
+    shouldUseInert?: boolean;
 };
 export declare const useAriaHideOutside: (props?: UseAriaHideOutsideProps) => {
     ariaHideOutsideRef: import("react").RefObject<HTMLElement>;
     ariaHideEnabled: boolean;
+    setAriaHideOutsideTarget: (node: HTMLElement, isActive: boolean) => void;
 };

package/src/hooks/useKeyboardMoveFocus/useKeyboardMoveFocus.d.ts

@@ -10,7 +10,7 @@ export type UseKeyboardMoveFocusParams<T> = {
     endSearchDebounceTime?: number;
 } & Pick<MoveIndexInTwoDimensionalOptions, 'infinite'>;
 export declare const useKeyboardMoveFocus: <T>({ infinite, options, focusedIndexRef, onFocusedIndexChange, getOptionDisabled, getOptionSearchText, columns, endSearchDebounceTime, }: UseKeyboardMoveFocusParams<T>) => {
-    getPrevFocusableOption: (index?: number, isInfinite?: any) => number;
-    getNextFocusableOption: (index?: number, isInfinite?: any) => number;
+    getPrevFocusableOption: (index?: number, isInfinite?: boolean) => number;
+    getNextFocusableOption: (index?: number, isInfinite?: boolean) => number;
     onKeyFocusedIndexHandle: (event: React.KeyboardEvent<any>) => void;
 };

package/src/utils/ariaHideOutside.d.ts

@@ -1 +1,11 @@
-export declare const ariaHideOutside: (targets: Element[], root?: HTMLElement) => () => void;
+export type AriaHideOutsideController = {
+    addTarget: (target: Element) => void;
+    removeTarget: (target: Element) => void;
+    dispose: () => void;
+};
+export type AriaHideOutsideOptions = {
+    root?: Element;
+    shouldUseInert?: boolean;
+};
+export declare const createAriaHideOutsideController: (targets: Element[], options?: AriaHideOutsideOptions | Element) => AriaHideOutsideController;
+export declare const ariaHideOutside: (targets: Element[], options?: AriaHideOutsideOptions | Element) => () => void;

package/src/utils/index.d.ts

@@ -1,5 +1,6 @@
 export * from './a11yKeyboardCode';
-export * from './ariaHideOutside';
+export { ariaHideOutside } from './ariaHideOutside';
+export type { AriaHideOutsideOptions } from './ariaHideOutside';
 export * from './capitalize';
 export * from './checkDefaultPrevented';
 export * from './checkElementName';