@muraldevkit/ui-toolkit 4.65.3-dev-IWCo.1 → 4.66.0-dev-avUr.1

package/dist/esm/hooks/useBreakpoint/index.js

@@ -0,0 +1,61 @@
+/* eslint-disable sort-keys */
+import { useState, useRef, useLayoutEffect } from 'react';
+import { FrameDebounce } from '../../utils/frameDebounce';
+const gridBreakpoints = {
+    xs: 0,
+    sm: 600,
+    md: 834,
+    lg: 1024,
+    xl: 1280,
+    xxl: 1440
+};
+/**
+ * Gets a breakpoint based on the width
+ *
+ * @param width - The width to determine the breakpoint
+ * @returns {keyof Breakpoints} - the current breakpoint
+ */
+function getBreakpoint(width) {
+    let currentBreakpoint = 'xs';
+    for (const breakpoint in gridBreakpoints) {
+        if (width >= gridBreakpoints[breakpoint]) {
+            currentBreakpoint = breakpoint;
+        }
+    }
+    return currentBreakpoint;
+}
+/**
+ * React Hook to return the current breakpoint
+ *
+ * @returns {keyof Breakpoints} - the current breakpoint
+ */
+export const useBreakpoint = () => {
+    const initialBreakpoint = getBreakpoint(window.innerWidth);
+    const [currentBreakpoint, setCurrentBreakpoint] = useState(initialBreakpoint);
+    //create a single ref for us to store a FrameDebounce.
+    const resizeObserverRef = useRef();
+    if (!resizeObserverRef.current) {
+        resizeObserverRef.current = {
+            instance: new FrameDebounce()
+        };
+    }
+    useLayoutEffect(() => {
+        // setup event listeners
+        const handleResize = () => {
+            var _a;
+            (_a = resizeObserverRef === null || resizeObserverRef === void 0 ? void 0 : resizeObserverRef.current) === null || _a === void 0 ? void 0 : _a.instance.debounce(() => {
+                const breakpoint = getBreakpoint(window.innerWidth);
+                setCurrentBreakpoint(breakpoint);
+            });
+        };
+        window.addEventListener('resize', handleResize);
+        // clean it up
+        return () => {
+            var _a;
+            window.removeEventListener('resize', handleResize);
+            (_a = resizeObserverRef === null || resizeObserverRef === void 0 ? void 0 : resizeObserverRef.current) === null || _a === void 0 ? void 0 : _a.instance.cancel();
+        };
+    }, []);
+    return currentBreakpoint;
+};
+export default useBreakpoint;

package/dist/esm/hooks/useBreakpoint/useBreakpointDemo.js

@@ -0,0 +1,12 @@
+import * as React from 'react';
+import { useBreakpoint } from './index';
+import { MrlText } from '../../components';
+/**
+ * Demo for useBreakpoint hook
+ *
+ * @returns JSX.Element
+ */
+export const UseBreakpointDemo = () => {
+    const breakpoint = useBreakpoint();
+    return React.createElement(MrlText, null, `Current active breakpoint: ${breakpoint}`);
+};

package/dist/esm/hooks/useClickOutside/index.js

@@ -0,0 +1,42 @@
+import { useEffect } from 'react';
+/**
+ * Hook to detect clicks outside of a given DOM element, with an optional exclusion for selectors.
+ *
+ * @param menuRef - Reference to the DOM element to detect outside clicks for.
+ * @param triggerRef - Reference to the DOM element that caused this menu to be shown.
+ * @param eventType - Event type to listen for.
+ * @param onOutsideClick - Function to call when a click is detected outside the menuRef element.
+ * @param disabled - If the hook should be disabled.
+ * @param excludeSelectors - Optional array of CSS selectors to exclude from the outside click detection.
+ */
+export const useClickOutside = (menuRef, triggerRef, eventType = 'mousedown', onOutsideClick, disabled = false, excludeSelectors) => {
+    useEffect(() => {
+        const handleClickOutside = (event) => {
+            var _a;
+            const menuElement = menuRef === null || menuRef === void 0 ? void 0 : menuRef.current;
+            const triggerElement = triggerRef === null || triggerRef === void 0 ? void 0 : triggerRef.current;
+            const target = event.target;
+            const isClickMenu = menuElement && menuElement.contains(target);
+            const isClickTrigger = triggerElement && triggerElement.contains(target);
+            /**
+             * Check if the event target is within any of the excluded selectors from
+             * the whitelist. If it is, do not call the onOutsideClick function.
+             */
+            const isExcluded = (_a = excludeSelectors === null || excludeSelectors === void 0 ? void 0 : excludeSelectors.some((selector) => { var _a; return (_a = event.target) === null || _a === void 0 ? void 0 : _a.closest(selector); })) !== null && _a !== void 0 ? _a : false;
+            if (!disabled && !isClickMenu && !isClickTrigger && !isExcluded) {
+                onOutsideClick();
+            }
+        };
+        document.body.addEventListener(eventType, handleClickOutside);
+        return () => {
+            document.body.removeEventListener(eventType, handleClickOutside);
+        };
+    }, [
+        menuRef,
+        triggerRef,
+        onOutsideClick,
+        disabled,
+        eventType,
+        excludeSelectors
+    ]);
+};

package/dist/esm/hooks/useCoordinate/index.js

@@ -0,0 +1,114 @@
+import { useLayoutEffect, useRef, useState, useMemo, useCallback } from 'react';
+import { FrameDebounce } from '../../utils/frameDebounce';
+/**
+ * get coordinates of an element relative to window and listen for changes.
+ *
+ * @param element element of type T
+ * @param disabledScrollTracking boolean to disable scroll tracking.
+ * @param openState boolean to track if the element's open state changed.
+ * @returns coordinate object of element.
+ */
+export const useCoordinate = function useCoordinate(element, disabledScrollTracking = false, openState) {
+    const [coordinate, setCoordinate] = useState({
+        bottom: 0,
+        height: 0,
+        left: 0,
+        right: 0,
+        top: 0,
+        width: 0,
+        x: 0,
+        y: 0
+    });
+    //create a single ref for us to store a FrameDebounce.
+    const intersectionObserverRef = useRef();
+    const [scrollContainer, setScrollContainer] = useState(null);
+    //getBoundingClientRect() causes a reflow plus other perf issues.
+    // its actually cheaper for the browser to fire intersection observers as we need.
+    const observer = useMemo(() => {
+        return new IntersectionObserver((entries) => {
+            for (const entry of entries) {
+                // The `entry.boundingClientRect` is where all the dimensions are stored
+                const bounds = entry.boundingClientRect.toJSON();
+                const offsetBounds = Object.assign(Object.assign({}, bounds), { left: bounds.left + window.scrollX, top: bounds.top + window.scrollY });
+                setCoordinate(offsetBounds);
+            }
+            // Disconnect the observer to stop from running in the background
+            observer.disconnect();
+        });
+    }, []);
+    const observeElementAndUpdateCoordinates = useCallback(() => {
+        var _a;
+        if (!element) {
+            return;
+        }
+        (_a = intersectionObserverRef === null || intersectionObserverRef === void 0 ? void 0 : intersectionObserverRef.current) === null || _a === void 0 ? void 0 : _a.instance.debounce(() => {
+            observer.observe(element);
+        });
+    }, [element, observer]);
+    useLayoutEffect(() => {
+        if (!element) {
+            return;
+        }
+        /**
+         * This block of code detects if the element is within a scrolling container so we can provide more exact calculations
+         * in the event that the element's position needs to be recalculated relative to the container's new scroll position.
+         *
+         * If we detect that the element is within a scrolling container, we store a reference to the scrollable element. That way
+         * we can assign event listeners to the scroll element so that we can recalculate the elements position based on the
+         * scroll value.
+         */
+        if (!disabledScrollTracking) {
+            let elementParent = element.parentElement;
+            while (elementParent && scrollContainer === null) {
+                const style = window.getComputedStyle(elementParent);
+                const overflowY = style.getPropertyValue('overflow-y');
+                if (overflowY === 'auto' || overflowY === 'scroll') {
+                    setScrollContainer(elementParent);
+                    break;
+                }
+                if (elementParent.tagName === 'BODY') {
+                    break;
+                }
+                elementParent = elementParent.parentElement;
+            }
+        }
+        // observe real quick to setup initial state.
+        observer.observe(element);
+        if (!intersectionObserverRef.current) {
+            intersectionObserverRef.current = {
+                instance: new FrameDebounce()
+            };
+        }
+        window.addEventListener('resize', observeElementAndUpdateCoordinates);
+        if (scrollContainer)
+            scrollContainer.addEventListener('scroll', observeElementAndUpdateCoordinates);
+        return () => {
+            var _a;
+            (_a = intersectionObserverRef === null || intersectionObserverRef === void 0 ? void 0 : intersectionObserverRef.current) === null || _a === void 0 ? void 0 : _a.instance.cancel();
+            window.removeEventListener('resize', observeElementAndUpdateCoordinates);
+            if (scrollContainer)
+                scrollContainer.removeEventListener('scroll', observeElementAndUpdateCoordinates);
+        };
+    }, [
+        element,
+        observer,
+        scrollContainer,
+        disabledScrollTracking,
+        openState,
+        observeElementAndUpdateCoordinates
+    ]);
+    // This effect is responsible for observing the scroll container for changes in size.
+    useLayoutEffect(() => {
+        if (!scrollContainer) {
+            return;
+        }
+        const resizeObserver = new ResizeObserver(() => {
+            observeElementAndUpdateCoordinates();
+        });
+        resizeObserver.observe(scrollContainer);
+        return () => {
+            resizeObserver.disconnect();
+        };
+    }, [element, observeElementAndUpdateCoordinates, scrollContainer]);
+    return coordinate;
+};

package/dist/esm/hooks/useElementDimensions/index.js

@@ -0,0 +1,42 @@
+import * as React from 'react';
+/**
+ * Calculates the dimensions of an element using the ResizeObserver API.
+ *
+ * @template T - The type of the element or HTMLElement.
+ * @param ref - The ref object that references the element.
+ * @returns {ElementDimensions} - The dimensions of the element.
+ */
+export function useElementDimensions(ref) {
+    const [dimensions, setDimensions] = React.useState(() => ({
+        height: null,
+        width: null
+    }));
+    React.useEffect(() => {
+        if (!ref.current)
+            return;
+        const expectedWidths = new WeakMap();
+        const expectedHeights = new WeakMap();
+        const observer = new ResizeObserver((entries) => {
+            requestAnimationFrame(() => {
+                for (const entry of entries) {
+                    const expectedWidth = expectedWidths.get(entry.target);
+                    const expectedHeight = expectedHeights.get(entry.target);
+                    if (entry.borderBoxSize[0].inlineSize === expectedWidth &&
+                        entry.borderBoxSize[0].blockSize === expectedHeight)
+                        continue;
+                    expectedWidths.set(entry.target, entry.borderBoxSize[0].inlineSize);
+                    expectedHeights.set(entry.target, entry.borderBoxSize[0].blockSize);
+                    setDimensions({
+                        height: entry.borderBoxSize[0].blockSize,
+                        width: entry.borderBoxSize[0].inlineSize
+                    });
+                }
+            });
+        });
+        observer.observe(ref.current);
+        return () => observer.disconnect();
+        // ref won't trigger a re-render, so it's safe to exclude it from the dependencies array
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    return dimensions;
+}

package/dist/esm/hooks/useHasFocusableDescendant/index.js

@@ -0,0 +1,47 @@
+import * as React from 'react';
+import { FOCUSABLE_ELEMENTS_SELECTOR } from '../../utils/trapFocus';
+/**
+ * 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 function useHasFocusableDescendant(ref) {
+    const [hasFocusableDescendant, setHasFocusableDescendant] = React.useState(true);
+    React.useLayoutEffect(() => {
+        const element = ref.current;
+        if (!element)
+            return;
+        const measure = () => {
+            const next = element.querySelector(FOCUSABLE_ELEMENTS_SELECTOR) !== null;
+            setHasFocusableDescendant((prev) => (prev === next ? prev : next));
+        };
+        measure();
+        const observer = new MutationObserver(measure);
+        observer.observe(element, {
+            attributeFilter: ['aria-disabled', 'disabled', 'hidden', 'tabindex', 'type'],
+            attributes: true,
+            childList: true,
+            subtree: true
+        });
+        return () => {
+            observer.disconnect();
+        };
+    }, [ref]);
+    return hasFocusableDescendant;
+}

package/dist/esm/hooks/useScrollbarInfo/index.js

@@ -0,0 +1,46 @@
+import * as React from 'react';
+/**
+ * Custom hook that provides information about the presence and dimensions of vertical and horizontal scrollbars
+ * in a scrollable container.
+ *
+ * @returns {UseScrollbarInfoReturn} Returns the scrollbar information and a ref to attach to the scrollable container
+ */
+export function useScrollbarInfo() {
+    const [scrollbarInfo, setScrollbarInfo] = React.useState({
+        hasHorizontalScrollbar: false,
+        hasVerticalScrollbar: false,
+        horizontalScrollbarHeight: 0,
+        verticalScrollbarWidth: 0
+    });
+    const scrollableContainerRef = React.useRef(null);
+    React.useLayoutEffect(() => {
+        if (!scrollableContainerRef.current)
+            return;
+        const observer = new ResizeObserver(([entry]) => {
+            if (!entry)
+                return;
+            const target = entry.target;
+            // Detects if scrollbars exist (works for both classic and overlay scrollbars)
+            // Vertical scrollbar exists when content height exceeds visible height
+            const hasVerticalScrollbar = target.scrollHeight > target.clientHeight;
+            // Horizontal scrollbar exists when content width exceeds visible width
+            const hasHorizontalScrollbar = target.scrollWidth > target.clientWidth;
+            // Gets dimensions only for classic scrollbars that take up layout space
+            // Vertical scrollbar width: difference between offsetWidth and clientWidth
+            const verticalScrollbarWidth = target.offsetWidth - target.clientWidth;
+            // Horizontal scrollbar height: difference between offsetHeight and clientHeight
+            const horizontalScrollbarHeight = target.offsetHeight - target.clientHeight;
+            setScrollbarInfo({
+                hasHorizontalScrollbar,
+                hasVerticalScrollbar,
+                horizontalScrollbarHeight,
+                verticalScrollbarWidth
+            });
+        });
+        observer.observe(scrollableContainerRef.current);
+        return () => {
+            observer.disconnect();
+        };
+    }, []);
+    return Object.assign(Object.assign({}, scrollbarInfo), { scrollableContainerRef });
+}

package/dist/esm/hooks/useTriggerPosition/constants.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/hooks/useTriggerPosition/index.js

@@ -0,0 +1,128 @@
+import { useMemo, useState, useEffect, useCallback, useLayoutEffect } from 'react';
+import { getPosition } from './utilities';
+import debounce from 'lodash.debounce';
+/**
+ * useTriggerPosition hook.
+ *
+ * Calculates the position of a menu element based on the alignment settings relative to a trigger element.
+ *
+ * @param triggerRef - Reference to the DOM element that triggers the menu.
+ * @param elementRef - Reference to the DOM element that is the menu.
+ * @param menuAlign - The alignment configuration of the menu.
+ * @param isElementVisible - Tells the hook if the element is visible. If false, the hook will not calculate the position.
+ * @param menuOffset - The offset of the menu from the trigger element.
+ * @param disable - Whether to disable the hook.
+ * @param disableFlipping - Whether to disable flipping logic when the menu overflows the screen.
+ * @returns {Position} The calculated position of the menu element.
+ */
+export const useTriggerPosition = (triggerRef, elementRef, menuAlign, isElementVisible = true, menuOffset = 10, disable = false, disableFlipping = false) => {
+    const offset = menuOffset;
+    // Holds the current calculated position of the menu
+    const [menuPosition, setMenuPosition] = useState({ flipped: false, left: 0, top: 0 });
+    // Memoize alignment so it only recalculates when specific props change
+    const alignment = useMemo(() => ({
+        align: menuAlign.align,
+        customPosition: menuAlign.customPosition,
+        position: menuAlign.position
+    }), [menuAlign.align, menuAlign.position, menuAlign.customPosition]);
+    /**
+     * Calculates and updates the menu position relative to the trigger.
+     * Uses requestAnimationFrame to ensure layout is stable before measuring.
+     */
+    const updatePosition = useCallback(() => {
+        if (!elementRef.current || !isElementVisible)
+            return;
+        requestAnimationFrame(() => {
+            var _a, _b;
+            const triggerRect = (_a = triggerRef === null || triggerRef === void 0 ? void 0 : triggerRef.current) === null || _a === void 0 ? void 0 : _a.getBoundingClientRect();
+            const elementRect = (_b = elementRef.current) === null || _b === void 0 ? void 0 : _b.getBoundingClientRect();
+            // Don't update if the element is not visible/rendered
+            if (!elementRect || elementRect.height === 0 || elementRect.width === 0)
+                return;
+            const newPosition = getPosition(alignment, offset, elementRect, triggerRect, disableFlipping);
+            // Only update state if the position has changed
+            setMenuPosition((prevPosition) => {
+                if (prevPosition.left !== newPosition.left || prevPosition.top !== newPosition.top) {
+                    return newPosition;
+                }
+                return prevPosition;
+            });
+        });
+    }, [alignment, elementRef, isElementVisible, offset, triggerRef, disableFlipping]);
+    /**
+     * Debounced version of the updatePosition function used for scroll and resize events.
+     * 5ms debounce gives a balance between performance and responsiveness.
+     */
+    const debouncedUpdatePosition = useMemo(() => debounce(updatePosition, 5), [updatePosition]);
+    useEffect(() => {
+        if (disable)
+            return;
+        const currentElement = elementRef.current;
+        /**
+         * We need to debounce the resize observer to prevent "resize loops"
+         * There are instances where the ResizeObserver will trigger a resize event
+         * before the browser has painted, which causes a loop of resize events
+         * and can throw errors or performance issues.
+         *
+         * The observers are purposefully using a different debounce than the event listeners.
+         * Observers need to be more aggressively debounced to prevent loops,
+         * while event listeners (resize/scroll) should update positioning more responsively.
+         */
+        const resizeObserver = new ResizeObserver(debounce(updatePosition));
+        const mutationObserver = new MutationObserver(debounce(updatePosition));
+        // Observe changes in size and style/className
+        if (currentElement) {
+            resizeObserver.observe(currentElement);
+            mutationObserver.observe(currentElement, {
+                attributeFilter: ['style', 'class'],
+                attributes: true
+            });
+        }
+        // Add listeners on open to respond to browser resizing and scrolling
+        if (isElementVisible) {
+            updatePosition();
+            window.addEventListener('resize', debouncedUpdatePosition);
+            window.addEventListener('scroll', debouncedUpdatePosition);
+        }
+        // Cleanup observers and listeners on unmount or re-render
+        return () => {
+            if (currentElement) {
+                resizeObserver.unobserve(currentElement);
+                mutationObserver.disconnect();
+            }
+            window.removeEventListener('resize', debouncedUpdatePosition);
+            window.removeEventListener('scroll', debouncedUpdatePosition);
+        };
+    }, [
+        disable,
+        triggerRef,
+        elementRef,
+        alignment,
+        offset,
+        isElementVisible,
+        updatePosition,
+        debouncedUpdatePosition
+    ]);
+    /**
+     * This effect handles an edge case where the menu is rendered,
+     * but its size is not immediately available in the first frame.
+     * A short timeout ensures we recalculate the position once layout stabilizes.
+     */
+    useEffect(() => {
+        if (!disable && isElementVisible) {
+            const timeoutId = setTimeout(updatePosition, 10);
+            return () => clearTimeout(timeoutId);
+        }
+    }, [isElementVisible, disable, updatePosition]);
+    /**
+     * useLayoutEffect ensures the position is recalculated during the layout phase,
+     * just after DOM mutations but before the browser paints.
+     */
+    useLayoutEffect(() => {
+        if (!disable && isElementVisible && elementRef.current && (triggerRef === null || triggerRef === void 0 ? void 0 : triggerRef.current)) {
+            updatePosition();
+            requestAnimationFrame(updatePosition);
+        }
+    }, [isElementVisible, updatePosition, disable, elementRef, triggerRef]);
+    return menuPosition;
+};