@deque/cauldron-react 6.22.3 → 6.23.0-canary.4ddfcf41

package/lib/components/Listbox/Listbox.d.ts

@@ -6,6 +6,7 @@ interface BaseListboxProps extends PolymorphicProps<Omit<React.HTMLAttributes<HT
     navigation?: 'cycle' | 'bound';
     focusStrategy?: 'lastSelected' | 'first' | 'last';
     focusDisabledOptions?: boolean;
+    activeOption?: ListboxOption;
     onActiveChange?: (option: ListboxOption) => void;
     disabled?: boolean;
 }

package/lib/index.js

@@ -1366,7 +1366,7 @@ var removeFocusTrapFromStack = function (focusTrap) {
     var focusTrapIndex = focusTrapStack.findIndex(function (trap) { return focusTrap.targetElement === trap.targetElement; });
     focusTrapStack.splice(focusTrapIndex, 1);
 };
-function getActiveElement(target) {
+function getActiveElement$1(target) {
     var _a;
     return (((_a = target === null || target === void 0 ? void 0 : target.ownerDocument.activeElement) !== null && _a !== void 0 ? _a : document.activeElement) ||
         document.body);
@@ -1502,7 +1502,7 @@ function useFocusTrap(target, options) {
         if (!targetElement || disabled) {
             return;
         }
-        returnFocusElementRef.current = getActiveElement(targetElement);
+        returnFocusElementRef.current = getActiveElement$1(targetElement);
         focusTrap.current = createFocusTrap(targetElement, initialFocusElement);
         return function () {
             var _a;
@@ -1776,6 +1776,38 @@ function getAutoAlignment(placement) {
             return null;
     }
 }
+/**
+ * Prevents large overlays from shifting off-screen above the viewport. When an overlay
+ * would overflow past the top edge, this middleware signals that it should flip to an
+ * alternative placement to keep content visible and accessible.
+ */
+var preventTopOverflowMiddleware = {
+    name: 'preventTopOverflow',
+    fn: function (state) {
+        return tslib.__awaiter(this, void 0, void 0, function () {
+            var overflow;
+            return tslib.__generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, reactDom$1.detectOverflow(state, {
+                            rootBoundary: 'document'
+                        })];
+                    case 1:
+                        overflow = _a.sent();
+                        if ((overflow === null || overflow === void 0 ? void 0 : overflow.top) >= 0) {
+                            return [2 /*return*/, {
+                                    reset: {
+                                        // Replace the initial placement axis with 'bottom' while preserving alignment (start/end)
+                                        // Examples: 'top' -> 'bottom', 'top-start' -> 'bottom-start'
+                                        placement: (state.placement.replace(/\w+?(-(start|end))?$/i, 'bottom$1') || 'bottom')
+                                    }
+                                }];
+                        }
+                        return [2 /*return*/, {}];
+                }
+            });
+        });
+    }
+};
 var AnchoredOverlay = React.forwardRef(function (_a, refProp) {
     var _b, _c;
     var as = _a.as, _d = _a.placement, initialPlacement = _d === void 0 ? 'auto' : _d, target = _a.target, children = _a.children, style = _a.style, _e = _a.open, open = _e === void 0 ? false : _e, offset = _a.offset, focusTrap = _a.focusTrap, focusTrapOptions = _a.focusTrapOptions, onOpenChange = _a.onOpenChange, onPlacementChange = _a.onPlacementChange, onShiftChange = _a.onShiftChange, portal = _a.portal, props = tslib.__rest(_a, ["as", "placement", "target", "children", "style", "open", "offset", "focusTrap", "focusTrapOptions", "onOpenChange", "onPlacementChange", "onShiftChange", "portal"]);
@@ -1795,7 +1827,11 @@ var AnchoredOverlay = React.forwardRef(function (_a, refProp) {
                 : reactDom$1.flip({
                     fallbackAxisSideDirection: 'start'
                 }),
-            reactDom$1.shift({ crossAxis: false })
+            reactDom$1.shift({
+                crossAxis: false,
+                boundary: 'clippingAncestors'
+            }),
+            preventTopOverflowMiddleware
         ].filter(Boolean),
         elements: {
             reference: resolveElement(target)
@@ -3669,12 +3705,13 @@ var optionMatchesValue = function (option, value) {
         option.value === value;
 };
 var Listbox = React.forwardRef(function (_a, ref) {
-    var _b = _a.as, Component = _b === void 0 ? 'ul' : _b, children = _a.children, defaultValue = _a.defaultValue, value = _a.value, _c = _a.navigation, navigation = _c === void 0 ? 'bound' : _c, _d = _a.focusStrategy, focusStrategy = _d === void 0 ? 'lastSelected' : _d, _e = _a.focusDisabledOptions, focusDisabledOptions = _e === void 0 ? false : _e, _f = _a.multiselect, multiselect = _f === void 0 ? false : _f, onKeyDown = _a.onKeyDown, onFocus = _a.onFocus, onSelectionChange = _a.onSelectionChange, onActiveChange = _a.onActiveChange, _g = _a.disabled, disabled = _g === void 0 ? false : _g, props = tslib.__rest(_a, ["as", "children", "defaultValue", "value", "navigation", "focusStrategy", "focusDisabledOptions", "multiselect", "onKeyDown", "onFocus", "onSelectionChange", "onActiveChange", "disabled"]);
+    var _b = _a.as, Component = _b === void 0 ? 'ul' : _b, children = _a.children, defaultValue = _a.defaultValue, value = _a.value, _c = _a.navigation, navigation = _c === void 0 ? 'bound' : _c, _d = _a.focusStrategy, focusStrategy = _d === void 0 ? 'lastSelected' : _d, _e = _a.focusDisabledOptions, focusDisabledOptions = _e === void 0 ? false : _e, _f = _a.multiselect, multiselect = _f === void 0 ? false : _f, onKeyDown = _a.onKeyDown, onFocus = _a.onFocus, onSelectionChange = _a.onSelectionChange, controlledActiveOption = _a.activeOption, onActiveChange = _a.onActiveChange, _g = _a.disabled, disabled = _g === void 0 ? false : _g, props = tslib.__rest(_a, ["as", "children", "defaultValue", "value", "navigation", "focusStrategy", "focusDisabledOptions", "multiselect", "onKeyDown", "onFocus", "onSelectionChange", "activeOption", "onActiveChange", "disabled"]);
     var _h = tslib.__read(React.useState([]), 2), options = _h[0], setOptions = _h[1];
-    var _j = tslib.__read(React.useState(null), 2), activeOption = _j[0], setActiveOption = _j[1];
+    var _j = tslib.__read(React.useState(controlledActiveOption || null), 2), activeOption = _j[0], setActiveOption = _j[1];
     var _k = tslib.__read(React.useState([]), 2), selectedOptions = _k[0], setSelectedOptions = _k[1];
     var listboxRef = useSharedRef(ref);
     var isControlled = typeof value !== 'undefined';
+    var isActiveControlled = typeof controlledActiveOption !== 'undefined';
     React.useLayoutEffect(function () {
         if (!isControlled && selectedOptions.length > 0) {
             return;
@@ -3709,6 +3746,11 @@ var Listbox = React.forwardRef(function (_a, ref) {
             onActiveChange === null || onActiveChange === void 0 ? void 0 : onActiveChange(activeOption);
         }
     }, [activeOption]);
+    React.useEffect(function () {
+        if (isActiveControlled && controlledActiveOption !== activeOption) {
+            setActiveOption(controlledActiveOption || null);
+        }
+    }, [isActiveControlled, controlledActiveOption]);
     var handleSelect = React.useCallback(function (option) {
         var _a;
         setActiveOption(option);
@@ -4925,28 +4967,142 @@ function useActionListContext() {
     return React.useContext(ActionListContext);
 }
 
+/**
+ * Get an element's accessible name by its aria-label or text content
+ */
+function getAccessibleLabel(element) {
+    var _a;
+    return (
+    // We're explicitly ignoring that we _could_ use aria-labelledby here
+    // because of the additional complexity that is needed in order to calculate
+    // the accessible name of an aria-labelled by idref. We're reserving that behavior
+    // for future implementation if it is determined to be needed.
+    element.getAttribute('aria-label') || ((_a = element.textContent) === null || _a === void 0 ? void 0 : _a.trim()) || '');
+}
+/**
+ * Gets the active element based on the root element passed in
+ */
+function getActiveElement(root) {
+    var activeElement;
+    if (document.activeElement === root &&
+        root.hasAttribute('aria-activedescendant')) {
+        activeElement = document.getElementById(
+        // Validating attribute above with "hasAttribute"
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        root.getAttribute('aria-activedescendant'));
+    }
+    else {
+        activeElement = document.activeElement;
+    }
+    return root.contains(activeElement) ? activeElement : null;
+}
+/**
+ * A hook that provides mnemonic navigation for keyboard users.
+ *
+ * Mnemonics allow users to quickly navigate to elements by typing the first
+ * letter of the element's text content. Pressing the same letter repeatedly
+ * cycles through all matching elements.
+ */
+function useMnemonics(_a) {
+    var elementOrRef = _a.elementOrRef, matchingElementsSelector = _a.matchingElementsSelector, onMatch = _a.onMatch, _b = _a.enabled, enabled = _b === void 0 ? true : _b;
+    var containerRef = React.useRef();
+    React.useEffect(function () {
+        if (elementOrRef instanceof HTMLElement) {
+            containerRef.current = elementOrRef;
+        }
+        else if (!!elementOrRef && 'current' in elementOrRef) {
+            containerRef.current = elementOrRef === null || elementOrRef === void 0 ? void 0 : elementOrRef.current;
+        }
+    }, [elementOrRef]);
+    React.useEffect(function () {
+        if (!enabled || !containerRef.current) {
+            return;
+        }
+        var keyboardHandler = function (event) {
+            // Ignore keyboard events where a modifier key was pressed
+            var hasModifier = event.ctrlKey || event.altKey || event.metaKey;
+            if (hasModifier) {
+                return;
+            }
+            // Ignore keyboard events where a non-alphanumeric character was pressed
+            if (event.key.length !== 1 || !/[a-z\d]/i.test(event.key)) {
+                return;
+            }
+            var container = containerRef.current;
+            if (!container) {
+                return;
+            }
+            // Prevent default behavior and stop propagation for mnemonic keys
+            event.preventDefault();
+            event.stopPropagation();
+            var elements = Array.from(container.querySelectorAll(matchingElementsSelector !== null && matchingElementsSelector !== void 0 ? matchingElementsSelector : focusable__default["default"]));
+            var matchingElements = elements.filter(function (element) {
+                return getAccessibleLabel(element).toLowerCase()[0] ===
+                    event.key.toLowerCase();
+            });
+            if (!matchingElements.length) {
+                return;
+            }
+            var currentActiveElement = getActiveElement(containerRef.current);
+            var nextActiveElement = null;
+            if (currentActiveElement) {
+                nextActiveElement = matchingElements.find(function (element) {
+                    // Find the next matching element that is _after_ the current active element
+                    // within the collection of identified elements
+                    return !!(element.compareDocumentPosition(currentActiveElement) &
+                        Node.DOCUMENT_POSITION_PRECEDING);
+                });
+            }
+            if (typeof onMatch === 'function') {
+                onMatch(nextActiveElement !== null && nextActiveElement !== void 0 ? nextActiveElement : matchingElements[0]);
+            }
+        };
+        var container = containerRef.current;
+        container.addEventListener('keydown', keyboardHandler);
+        return function () { return container.removeEventListener('keydown', keyboardHandler); };
+    }, [enabled, containerRef, matchingElementsSelector, onMatch]);
+    return containerRef;
+}
+
 var ActionList = React.forwardRef(function (_a, ref) {
     var _b = _a.selectionType, selectionType = _b === void 0 ? null : _b, onAction = _a.onAction, className = _a.className, children = _a.children, props = tslib.__rest(_a, ["selectionType", "onAction", "className", "children"]);
     var actionListContext = useActionListContext();
     var activeElement = React.useRef();
+    var _c = tslib.__read(React.useState(), 2), activeOption = _c[0], setActiveOption = _c[1];
     var handleActiveChange = React.useCallback(function (value) {
         activeElement.current = value === null || value === void 0 ? void 0 : value.element;
+        setActiveOption(value);
     }, []);
     var handleAction = React.useCallback(function (key, event) {
         if (typeof onAction === 'function') {
             onAction(key, event);
         }
     }, [onAction]);
+    var containerRef = useMnemonics({
+        onMatch: function (element) {
+            setActiveOption({
+                element: element
+            });
+        },
+        matchingElementsSelector: props.role === 'menu'
+            ? '[role=menuitem],[role=menuitemcheckbox],[role=menuitemradio]'
+            : '[role=option]'
+    });
     return (
     // Note: we should be able to use listbox without passing a prop
     // value for "multiselect"
     // see: https://github.com/dequelabs/cauldron/issues/1890
     // @ts-expect-error this should be allowed
-    React__default["default"].createElement(Listbox, tslib.__assign({ ref: ref, 
+    React__default["default"].createElement(Listbox, tslib.__assign({ ref: function (element) {
+            if (ref) {
+                setRef(ref, element);
+            }
+            containerRef.current = element;
+        }, 
         /* Listbox comes with an explicit role of "listbox", but we want to either
          * use the role from props, or default to the intrinsic role */
         // eslint-disable-next-line jsx-a11y/aria-role
-        role: undefined, "aria-multiselectable": actionListContext.role === 'listbox' ? undefined : null, className: classNames__default["default"]('ActionList', className) }, props, { onActiveChange: handleActiveChange, navigation: "bound" }),
+        role: undefined, "aria-multiselectable": actionListContext.role === 'listbox' ? undefined : null, className: classNames__default["default"]('ActionList', className), activeOption: activeOption }, props, { onActiveChange: handleActiveChange, navigation: "bound" }),
         React__default["default"].createElement(ActionListProvider, { role: props.role || 'list', onAction: handleAction, selectionType: selectionType }, children)));
 });
 ActionList.displayName = 'ActionList';

package/lib/utils/useMnemonics.d.ts

@@ -0,0 +1,31 @@
+import type { RefObject } from 'react';
+import type { ElementOrRef } from '../types';
+type useMnemonicsOptions = {
+    /**
+     * The container element or ref to use for matching elements for mnemonics.
+     * If not provided, the hook will return a ref that should be attached to a container.
+     */
+    elementOrRef?: ElementOrRef<HTMLElement>;
+    /**
+     * CSS selector to match for elements, defaults to focusable descendants.
+     */
+    matchingElementsSelector?: string;
+    /**
+     * Callback fired when a matching element is found via mnemonic keyboard entry.
+     */
+    onMatch: (element: HTMLElement) => void;
+    /**
+     * Whether mnemonic navigation is enabled. Defaults to true.
+     */
+    enabled?: boolean;
+};
+type useMnemonicsResults<T extends HTMLElement> = RefObject<T>;
+/**
+ * A hook that provides mnemonic navigation for keyboard users.
+ *
+ * Mnemonics allow users to quickly navigate to elements by typing the first
+ * letter of the element's text content. Pressing the same letter repeatedly
+ * cycles through all matching elements.
+ */
+export default function useMnemonics<T extends HTMLElement>({ elementOrRef, matchingElementsSelector, onMatch, enabled }: useMnemonicsOptions): useMnemonicsResults<T>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deque/cauldron-react",
-  "version": "6.22.3",
+  "version": "6.23.0-canary.4ddfcf41",
   "license": "MPL-2.0",
   "description": "Fully accessible react components library for Deque Cauldron",
   "homepage": "https://cauldron.dequelabs.com/",