@muraldevkit/ui-toolkit 4.66.0-dev-7XJy.1 → 4.66.0-dev-avUr.1

package/dist/esm/utils/setAttributes/setAttributes.js

@@ -0,0 +1,78 @@
+import cn from 'classnames';
+import { isObject } from '../isObject';
+/**
+ * Parse a string of attributes into a JSON object
+ *
+ * @param {string} attributes - the custom attributes passed to a component
+ * @returns {AttrsObject} - an object of attributes
+ */
+const parseAttributes = (attributes) => {
+    try {
+        return JSON.parse(attributes);
+    }
+    catch (error) {
+        console.error('The attrs property is not properly-formatted JSON:');
+        console.error(attributes);
+        console.error(error);
+        return error;
+    }
+};
+/**
+ * Sets up a classObject to be used by the className prop
+ *
+ * @todo - 2563 - use setClasses across components
+ * @param {string} customClasses - custom classes to apply via the attrs prop
+ * @param {ClassObject} defaultClasses - design system component classes to apply
+ * @returns {ClassObject} - with all classes
+ */
+export const setClasses = (customClasses, defaultClasses) => {
+    /**
+     * If a string is passed, we must parse it into a valid JSON object.
+     * Otherwise, we can assign the passed attributes directly to the returned object.
+     */
+    const parsedAttr = typeof customClasses === 'string' ? parseAttributes(customClasses) : customClasses;
+    if (parsedAttr && isObject(parsedAttr) && parsedAttr.class) {
+        return Object.assign({ [`${parsedAttr.class}`]: typeof parsedAttr.class !== 'undefined' && parsedAttr.class.length > 0 }, defaultClasses);
+    }
+    return defaultClasses;
+};
+/**
+ * Set an object of attributes to be used in a given component.
+ *
+ * @param {AttrsObject} attributes - The custom attributes passed to the component
+ * @param {AttrsObject} defaults - An optional object of the default attributes of a component
+ * @param {string} className - Default classes to apply to the component
+ *
+ * Use when applying attributes such as a className directly to a react component.
+ * @returns {AttrsObject} - An object of component attributes
+ */
+export const setAttributes = (attributes, defaults = {}, className) => {
+    /**
+     * If a string is passed, we must parse it into a valid JSON object.
+     * Otherwise, we can assign the passed attributes directly to the returned object.
+     */
+    const customAttributes = typeof attributes === 'string' ? parseAttributes(attributes) : attributes;
+    if (customAttributes) {
+        /**
+         * Assign the defaults and the passed attributes to a new object
+         * to ensure that one attributes object without duplicated keys
+         * can be passed to the component.
+         */
+        // Applies className instead of class when forReact is true
+        return Object.assign({}, defaults, customAttributes, {
+            className: cn(className, customAttributes.className)
+        });
+    }
+    return {};
+};
+let lastId = 0;
+/**
+ *  Generates unique identifier
+ *
+ * @param {string} prefix  - prefix for identifier
+ * @returns {string} - prefixed unique identifier
+ */
+export const getUniqueId = (prefix = 'mrl') => {
+    lastId++;
+    return `${prefix}-${lastId}`;
+};

package/dist/esm/utils/trapFocus/index.js

@@ -0,0 +1,146 @@
+const A_SELECTOR = 'a[href]:not([disabled])';
+const BUTTON_SELECTOR = 'button:not([disabled]):not([tabindex="-1"])';
+const TEXTAREA_SELECTOR = 'textarea:not([disabled])';
+const INPUT = 'input:not([type="hidden"]):not([disabled])';
+const SEARCH_INPUT = 'input[type="search"]:not([disabled])';
+const SELECT_SELECTOR = 'select:not([disabled])';
+const TAB_INDEX = '[tabindex]:not([tabindex="-1"]):not([disabled])';
+const WEB_COMPONENTS = 'mrl-icon-button:not([tabindex="-1"])';
+const TABBABLE_CONTENT_AREAS = 'div[tabindex="0"]';
+export const FOCUSABLE_ELEMENTS_SELECTOR = [
+    A_SELECTOR,
+    BUTTON_SELECTOR,
+    TEXTAREA_SELECTOR,
+    INPUT,
+    SEARCH_INPUT,
+    SELECT_SELECTOR,
+    TAB_INDEX,
+    WEB_COMPONENTS,
+    TABBABLE_CONTENT_AREAS
+].join(', ');
+/**
+ * Focus trap logic
+ * @param {HTMLElement} element - The component props.
+ * @returns {HTMLElement[]} - The focusable elements inside the element.
+ */
+export const getFocusableElementsInsideElement = (element) => {
+    const focusableElements = Array.from(element.querySelectorAll(FOCUSABLE_ELEMENTS_SELECTOR)).filter((n) => n instanceof HTMLElement);
+    // If no focusable elements are found, check if the container can be focused
+    if (focusableElements.length === 0) {
+        // Check if the element has a -1 tabindex, if it doesn't let's add it so it can be focused
+        if (!element.hasAttribute('tabindex') || element.tabIndex < 0) {
+            element.setAttribute('tabindex', '-1');
+        }
+        focusableElements.push(element);
+    }
+    return focusableElements;
+};
+/**
+ * Gets the first element with the data-autofocus="true" attribute within the container element
+ * @param {HTMLElement} containerElement - container element
+ * @returns {HTMLElement | undefined} - the first element that has autofocus="true" or undefined
+ */
+export const getElementWithAutofocus = (containerElement) => {
+    const focusableElements = getFocusableElementsInsideElement(containerElement);
+    return focusableElements.find((el) => {
+        return el.getAttribute('data-autofocus') === 'true';
+    });
+};
+/**
+ * Returns if an element is a radio element
+ * @param {Element} el - The element
+ * @returns {HTMLInputElement} Returns true if the element is a radio
+ */
+const isElementRadioButton = (el) => {
+    return el.tagName === 'INPUT' && el.type === 'radio';
+};
+/**
+ * Traps focus inside of an element
+ * Adapted from https://hidde.blog/using-javascript-to-trap-focus-in-an-element/
+ * @param {HTMLElement} element // Element to trap focus in
+ * @param {boolean} disableAutofocus // Whether to disable autofocus
+ * @returns {Function}          // Cleanup function to be run when component is
+ *                              // removed from the DOM
+ */
+export const trapFocus = (element, disableAutofocus = false) => {
+    const previouslyFocusedEl = document.activeElement;
+    const mutationObserver = new MutationObserver(() => {
+        const [firstFocusableElement] = getFocusableElementsInsideElement(element);
+        // The previously focused element was removed from the DOM
+        if (!document.activeElement) {
+            firstFocusableElement.focus();
+        }
+    });
+    const tabListener = (e) => {
+        if (e.key !== 'Tab') {
+            return;
+        }
+        const focusableElements = getFocusableElementsInsideElement(element);
+        const firstFocusableElement = focusableElements[0];
+        const lastFocusableElement = focusableElements[focusableElements.length - 1];
+        if (e.shiftKey) {
+            // If the activeElement is a radio button and shares the same 'name' attribute as the firstFocusableElement
+            if (document.activeElement &&
+                isElementRadioButton(document.activeElement) &&
+                isElementRadioButton(firstFocusableElement) &&
+                document.activeElement.name === firstFocusableElement.name) {
+                lastFocusableElement.focus();
+                e.preventDefault();
+                return;
+            }
+            // Reverse in tab order, but we're at the beginning of the list
+            if (document.activeElement === firstFocusableElement) {
+                lastFocusableElement.focus();
+                e.preventDefault();
+                return;
+            }
+        }
+        else if (document.activeElement === lastFocusableElement) {
+            // Forward in tab order, but we're at the end of the list
+            firstFocusableElement.focus();
+            e.preventDefault();
+        }
+    };
+    mutationObserver.observe(element, { childList: true, subtree: true });
+    element.addEventListener('keydown', tabListener);
+    /**
+     * In the event an element has its tabindex set after component mounting has completed, we need
+     * to allow the callstack to clear to ensure it's properly set before we can focus the first element.
+     */
+    setTimeout(() => {
+        const elementWithAutofocus = getElementWithAutofocus(element);
+        if (elementWithAutofocus) {
+            elementWithAutofocus.focus();
+            return;
+        }
+        if (!disableAutofocus) {
+            const [firstFocusableElement] = getFocusableElementsInsideElement(element);
+            firstFocusableElement === null || firstFocusableElement === void 0 ? void 0 : firstFocusableElement.focus();
+        }
+    }, 20);
+    return () => {
+        element.removeEventListener('keydown', tabListener);
+        mutationObserver.disconnect();
+        /**
+         * Restore focus to element that was in focus before the focus trap was activated
+         *
+         * Conditions to move focus:
+         * - If it is still inside the trap, or effectively "lost"
+         * - If focus has been intentionally moved outside, do nothing
+         */
+        const active = document.activeElement;
+        const focusIsInside = !!active && element.contains(active);
+        const focusIsLost = !active || active === document.body;
+        if (focusIsInside || focusIsLost) {
+            const body = document.body;
+            // get data-focus-item attribute from body
+            const focusItemId = body.dataset.focusItem;
+            const focusItemEl = focusItemId ? document.getElementById(focusItemId) : null;
+            const focusTarget = focusItemEl !== null && focusItemEl !== void 0 ? focusItemEl : previouslyFocusedEl;
+            if (focusTarget instanceof HTMLElement) {
+                focusTarget.focus();
+            }
+            delete body.dataset.focusItem;
+        }
+    };
+};

package/dist/hooks/index.d.ts

@@ -1,4 +1,5 @@
 export * from './useCoordinate';
 export * from './useBreakpoint';
 export * from './useElementDimensions';
+export * from './useHasFocusableDescendant';
 export * from './useScrollbarInfo';

package/dist/hooks/useHasFocusableDescendant/index.d.ts

@@ -0,0 +1,23 @@
+import * as React from 'react';
+/**
+ * Tracks whether the subtree of the given ref contains at least one element
+ * that participates in sequential focus navigation.
+ *
+ * Used by scrollable wrapper components (`MrlPanel`, `MrlModalContent`) to
+ * decide whether the wrapper itself needs `tabindex="0"`. Per ACT rule
+ * 0ssw9k (https://www.w3.org/WAI/standards-guidelines/act/rules/0ssw9k/) a
+ * scrollable region passes WCAG 2.1.1 Keyboard either by being focusable
+ * itself or by having a focusable descendant. When focusable descendants
+ * already exist, adding `tabindex="0"` to the wrapper produces a
+ * "meaningless tab stop" finding from manual auditors.
+ *
+ * The default return value is `true` so that, on the very first render
+ * (before the layout effect has measured the DOM), components err on the
+ * side of NOT adding a tab stop. The MutationObserver flips it to `false`
+ * synchronously inside the layout effect if the wrapper is genuinely
+ * empty of focusable descendants.
+ *
+ * @param {React.RefObject<HTMLElement | null>} ref - Ref pointing at the container whose subtree should be observed.
+ * @returns {boolean} `true` while the subtree contains at least one focusable element, `false` otherwise.
+ */
+export declare function useHasFocusableDescendant(ref: React.RefObject<HTMLElement | null>): boolean;