@carbon/ibm-products-web-components 0.22.0-rc.0 → 0.23.0-rc.0

package/es/utilities/manageFocusTrap/manageFocusTrap.js

@@ -0,0 +1,138 @@
+/**
+ * Copyright IBM Corp. 2024
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { selectorTabbable, prefix } from '@carbon/web-components/es/globals/settings';
+
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Traps focus within a set of containers, ensuring it stays within focusable elements.
+ * @param {NodeListOf<Element>} containers - The containers to trap focus within.
+ * @returns {object} An object with a `cleanup` method to remove event listeners.
+ */
+let _containers = [];
+const registerFocusableContainers = (container) => {
+    if (container) {
+        _containers.push(container);
+    }
+};
+const clearFocusableContainers = () => {
+    _containers.length = 0;
+};
+const trapFocus = (containers) => {
+    const selectorTabbable$1 = selectorTabbable.replace(`${prefix}-button`, `${prefix}-button:not([disabled]), ${prefix}-selectable-tag`);
+    if (containers && containers.length > 0) {
+        _containers = containers;
+    }
+    if (!_containers.length) {
+        return { cleanup: () => { } };
+    }
+    /**
+     * Given a container element, return the best candidate to focus.
+     * - If element itself is tabbable, return it.
+     * - Otherwise, find the first tabbable descendant.
+     */
+    const getFocusTarget = (el) => {
+        if (!el) {
+            return null;
+        }
+        if (el.tagName === 'BUTTON' || el.tabIndex >= 0) {
+            return el;
+        }
+        const inner = el.querySelector('button, [tabindex]:not([tabindex="-1"])');
+        return inner || el;
+    };
+    /**
+  
+   * Returns the "real" active element in the document, resolving through
+   * Shadow DOM and slot boundaries when necessary.
+   *
+   * In some cases `document.activeElement` may not reflect the actual
+   * tabbable node that has focus:
+   *   - If focus is inside a shadow root, `document.activeElement` is the host,
+   *     not the element inside. This utility dives into the shadowRoot to find
+   *     the inner active element.
+   *   - If focus is on a `<slot>` element, this function resolves to the first
+   *     tabbable assigned element within the slot.
+     */
+    const getRealActiveElement = () => {
+        var _a;
+        let activeElement = document.activeElement;
+        // If inside shadow DOM
+        if (activeElement &&
+            selectorTabbable$1.indexOf(activeElement.tagName.toLocaleLowerCase()) ==
+                -1 &&
+            ((_a = activeElement === null || activeElement === void 0 ? void 0 : activeElement.shadowRoot) === null || _a === void 0 ? void 0 : _a.activeElement)) {
+            activeElement = activeElement.shadowRoot.activeElement;
+        }
+        // If active element is a slot
+        if ((activeElement === null || activeElement === void 0 ? void 0 : activeElement.tagName) === 'SLOT') {
+            let assigned;
+            if (activeElement instanceof HTMLSlotElement) {
+                assigned = activeElement.assignedElements({ flatten: true });
+            }
+            const candidate = assigned === null || assigned === void 0 ? void 0 : assigned.find((node) => node.matches('button, [tabindex]:not([tabindex="-1"])'));
+            if (candidate) {
+                activeElement = candidate;
+            }
+        }
+        return activeElement;
+    };
+    //Optionally focus first element immediately
+    requestAnimationFrame(() => {
+        var _a;
+        const elements = getAllFocusableElements(_containers);
+        (_a = getFocusTarget(elements[0])) === null || _a === void 0 ? void 0 : _a.focus({ preventScroll: true });
+    });
+    function onKeyDown(e) {
+        var _a, _b;
+        if (e.key !== 'Tab') {
+            return;
+        }
+        // Flatten all focusable elements from all containers
+        const elements = getAllFocusableElements(_containers);
+        const first = elements[0];
+        const last = elements[elements.length - 1];
+        const active = getRealActiveElement();
+        if (e.shiftKey) {
+            // Shift+Tab wrap
+            if (active === first || first.contains(active)) {
+                e.preventDefault();
+                (_a = getFocusTarget(last)) === null || _a === void 0 ? void 0 : _a.focus();
+            }
+        }
+        else {
+            // Tab wrap
+            if (active === last || last.contains(active)) {
+                e.preventDefault();
+                (_b = getFocusTarget(first)) === null || _b === void 0 ? void 0 : _b.focus();
+            }
+        }
+    }
+    /**
+     * Retrieves all focusable elements within the provided containers.
+     **/
+    const getAllFocusableElements = (containers) => containers
+        .flatMap((container) => [...container.querySelectorAll(selectorTabbable$1)])
+        .filter(Boolean);
+    document.addEventListener('keydown', onKeyDown, true);
+    return {
+        cleanup: () => {
+            document.removeEventListener('keydown', onKeyDown, true);
+            _containers.length = 0;
+        },
+    };
+};
+
+export { clearFocusableContainers, registerFocusableContainers, trapFocus };
+//# sourceMappingURL=manageFocusTrap.js.map

package/es/utilities/manageFocusTrap/manageFocusTrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manageFocusTrap.js","sources":["../../../src/utilities/manageFocusTrap/manageFocusTrap.ts"],"sourcesContent":[null],"names":["selectorTabbable","selectorTabbableCarbon","carbonPrefix"],"mappings":"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"}