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

package/dist/esm/components/menu/hooks/useBrowserEdgeScroll.js

@@ -0,0 +1,163 @@
+import { useState, useLayoutEffect, useCallback, useRef, useEffect } from 'react';
+import debounce from 'lodash.debounce';
+/**
+ * useBrowserEdgeScroll hook
+ *
+ * This hook will calculate if an element's top or bottom edge bleed over the viewport edge
+ * and will provide a max height value for the element to allow it to scroll instead of bleed over
+ *
+ * @param elementRef - reference to the DOM element that is the menu
+ * @param elementPosition - the position of the menu
+ * @param elementAlign - the alignment of the menu
+ * @param disable - disable the hook from running
+ * @returns AdjustedElementStyle - returns the new updated style for scrolling the menu
+ */
+export const useBrowserEdgeScroll = (elementRef, elementPosition = 'bottom', elementAlign, disable) => {
+    const [heightStyle, setHeightStyle] = useState({});
+    const [isScrolling, setIsScrolling] = useState(false);
+    // Use a ref to store the initial dimensions of the menu
+    const menuRectSizeRef = useRef(null);
+    const updateMenuStyle = useCallback(() => {
+        if (disable || !elementRef.current || elementPosition === 'static')
+            return;
+        if (elementRef.current) {
+            if (!menuRectSizeRef.current) {
+                menuRectSizeRef.current = elementRef.current.getBoundingClientRect();
+            }
+            const newMaxHeight = calculateNewMaxHeight(elementPosition, elementAlign, elementRef, menuRectSizeRef.current, window.innerHeight);
+            if (newMaxHeight !== null) {
+                setIsScrolling(true);
+                setHeightStyle({ maxHeight: newMaxHeight });
+            }
+            else {
+                setIsScrolling(false);
+                setHeightStyle({});
+            }
+        }
+    }, [
+        disable,
+        elementRef,
+        elementAlign,
+        elementPosition
+    ]);
+    const updateMenuStyleDebounced = debounce(updateMenuStyle, 10);
+    useLayoutEffect(() => {
+        if (disable || !elementRef.current || elementPosition === 'static')
+            return;
+        /**
+         * Resize observer is setup to watch for changes in the element's size or position
+         *
+         * If a resize is detected, the element's style will be updated to allow for scrolling if necessary
+         */
+        const observer = new ResizeObserver(updateMenuStyleDebounced);
+        observer.observe(elementRef.current);
+        window.addEventListener('resize', updateMenuStyleDebounced);
+        if (elementRef.current) {
+            updateMenuStyle();
+        }
+        return () => {
+            observer.disconnect();
+            window.removeEventListener('resize', updateMenuStyleDebounced);
+            menuRectSizeRef.current = null;
+        };
+        // Passing a ref in shouldn't make things work, but in this scenario
+        // it's the only way to get the menu to update when it's ref becomes available
+        // this is used for when the menu initializes, the ref may not be available so this
+        // is allowing the menu to wait before initializing the menu style without a setTimeout
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [elementRef.current, elementPosition, updateMenuStyle]);
+    const updateOnImageLoad = () => {
+        var _a;
+        const elementRect = (_a = elementRef.current) === null || _a === void 0 ? void 0 : _a.getBoundingClientRect();
+        if (elementRect) {
+            menuRectSizeRef.current = elementRect;
+            updateMenuStyleDebounced();
+        }
+    };
+    /**
+     * Listen for image additions to the element and update the menu style when they load
+     */
+    useEffect(() => {
+        var _a;
+        const images = (_a = elementRef.current) === null || _a === void 0 ? void 0 : _a.querySelectorAll('img');
+        if (images) {
+            images.forEach((img) => {
+                img.addEventListener('load', updateOnImageLoad);
+            });
+        }
+        return () => {
+            if (images) {
+                images.forEach((img) => {
+                    img.removeEventListener('load', updateOnImageLoad);
+                });
+            }
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [elementRef.current, updateMenuStyleDebounced]);
+    return { isScrolling, styles: heightStyle };
+};
+/**
+ * Calculates the new max height of the menu based on the menu alignment and the viewport height
+ *
+ * @param elementPosition - the alignment of the menu
+ * @param elementAlign - the alignment of the menu
+ * @param elementRef - reference to the DOM element that is the menu
+ * @param menuRect - the bounding client rect of the menu
+ * @param viewportHeight - the height of the viewport
+ * @returns {string} - the new max height of the menu
+ */
+const calculateNewMaxHeight = (elementPosition, elementAlign, elementRef, menuRect, viewportHeight) => {
+    const scrollBuffer = 35;
+    const scrollThreshold = 20;
+    switch (elementPosition) {
+        case 'bottom':
+            return calculateBottomAlignment(menuRect, viewportHeight, scrollBuffer, scrollThreshold);
+        case 'top':
+            return calculateTopAlignment(menuRect, elementRef, scrollBuffer, scrollThreshold);
+        case 'left':
+        case 'right':
+            return calculateSideAlignment(elementAlign, menuRect, viewportHeight, scrollThreshold, scrollBuffer);
+        case 'ignore':
+            return checkElementIsScrolling(elementRef);
+        default:
+            return null;
+    }
+};
+const calculateBottomAlignment = (menuRect, viewportHeight, scrollBuffer, scrollThreshold) => {
+    // Evaluate from the bottom of the viewport to the top of the menu
+    if (menuRect.bottom > viewportHeight - scrollThreshold) {
+        const calculatedHeight = Math.max(0, viewportHeight - menuRect.top - scrollBuffer);
+        return `${Math.floor(calculatedHeight)}px`;
+    }
+    return null;
+};
+const calculateTopAlignment = (menuRect, elementRef, scrollBuffer, scrollThreshold) => {
+    var _a;
+    const currentRect = (_a = elementRef.current) === null || _a === void 0 ? void 0 : _a.getBoundingClientRect();
+    // Evaluate distance from the top of the viewport to the bottom of the menu
+    if (currentRect && currentRect.top <= scrollThreshold) {
+        const calculatedHeight = Math.max(0, currentRect.bottom - scrollThreshold);
+        return `${Math.floor(calculatedHeight)}px`;
+    }
+    return null;
+};
+const calculateSideAlignment = (elementAlign, menuRect, viewportHeight, scrollThreshold, scrollBuffer) => {
+    // Evaluate distance from the top of the viewport to the bottom of the menu
+    if (elementAlign === 'end' && menuRect.top < scrollThreshold) {
+        const calculatedHeight = Math.max(0, menuRect.bottom - scrollBuffer);
+        return `${Math.floor(calculatedHeight)}px`;
+    }
+    // Evaluate from the bottom of the viewport to the top of the menu
+    if (elementAlign === 'start' && menuRect.bottom > viewportHeight - scrollThreshold) {
+        const calculatedHeight = Math.max(0, viewportHeight - menuRect.top - scrollBuffer);
+        return `${Math.floor(calculatedHeight)}px`;
+    }
+    return null;
+};
+const checkElementIsScrolling = (elementRef) => {
+    const el = elementRef.current;
+    if (el && el.scrollTop > 0) {
+        return 'scrolling';
+    }
+    return null;
+};

package/dist/esm/components/menu/hooks/useMenuScroll.js

@@ -0,0 +1,124 @@
+import { useState, useCallback, useEffect, useLayoutEffect } from 'react';
+const SCREEN_OFFSET = 16;
+const DEFAULT_SCROLL_STATE = {
+    isScrolling: false,
+    maxHeight: undefined
+};
+/**
+ * useMenuScroll hook
+ *
+ * Detects when a menu cannot fit on screen in either its preferred or flipped position,
+ * and constrains its height to enable internal scrolling.
+ *
+ * Behavior by position:
+ * - **top/bottom**: If the menu doesn't fit in the preferred direction AND doesn't fit
+ *   in the opposite direction (flip), it reverts to the original position and constrains
+ *   the height to the space between the trigger edge and the viewport edge.
+ * - **left/right**: Only checks vertical overflow. If the menu is taller than the viewport,
+ *   it constrains the height to the available vertical space.
+ *
+ * Uses `scrollHeight` on the list element to determine the natural (unconstrained) content
+ * height. This value remains stable even when `maxHeight` is applied, preventing feedback
+ * loops with external positioning hooks that use ResizeObserver.
+ *
+ * Uses `useLayoutEffect` for the initial calculation so that `maxHeight` is applied
+ * synchronously before the browser paints. This prevents visible flicker when the menu
+ * opens in a constrained space, because the positioning hook (useTriggerPosition) will
+ * see the already-constrained height on its first measurement via requestAnimationFrame.
+ *
+ * @param triggerRef - Reference to the trigger element that opens the menu
+ * @param listRef - Reference to the ul element inside the menu (the scrollable container)
+ * @param position - The preferred menu position relative to the trigger
+ * @param menuOffset - The gap between the trigger and the menu in pixels
+ * @param isOpen - Whether the menu is currently open
+ * @param disable - Whether to disable the hook entirely
+ * @returns An object with `maxHeight` (inline style value) and `isScrolling` (class toggle)
+ */
+export const useMenuScroll = (triggerRef, listRef, position, menuOffset, isOpen, disable) => {
+    const [scrollState, setScrollState] = useState(DEFAULT_SCROLL_STATE);
+    const calculateScroll = useCallback(() => {
+        // Reset scroll constraints when the menu closes or refs aren't available.
+        if (!isOpen || disable || !(triggerRef === null || triggerRef === void 0 ? void 0 : triggerRef.current) || !listRef.current) {
+            setScrollState((prev) => {
+                if (prev.maxHeight === undefined && !prev.isScrolling)
+                    return prev;
+                return DEFAULT_SCROLL_STATE;
+            });
+            return;
+        }
+        const triggerRect = triggerRef.current.getBoundingClientRect();
+        const naturalHeight = listRef.current.scrollHeight;
+        const viewportHeight = window.innerHeight;
+        let maxHeight;
+        let isScrolling = false;
+        switch (position) {
+            case 'bottom': {
+                const availableBelow = viewportHeight - triggerRect.bottom - menuOffset - SCREEN_OFFSET;
+                const availableAbove = triggerRect.top - menuOffset - SCREEN_OFFSET;
+                if (naturalHeight > availableBelow && naturalHeight > availableAbove) {
+                    isScrolling = true;
+                    maxHeight = availableBelow;
+                }
+                break;
+            }
+            case 'top': {
+                const availableAbove = triggerRect.top - menuOffset - SCREEN_OFFSET;
+                const availableBelow = viewportHeight - triggerRect.bottom - menuOffset - SCREEN_OFFSET;
+                if (naturalHeight > availableAbove && naturalHeight > availableBelow) {
+                    isScrolling = true;
+                    maxHeight = availableAbove;
+                }
+                break;
+            }
+            case 'left':
+            case 'right': {
+                const availableVertical = viewportHeight - 2 * SCREEN_OFFSET;
+                if (naturalHeight > availableVertical) {
+                    isScrolling = true;
+                    maxHeight = availableVertical;
+                }
+                break;
+            }
+        }
+        /**
+         * Floor the maxHeight and subtract 1px to avoid sub-pixel rounding that can
+         * cause the element being positioned to flip between flipped/unflipped states.
+         */
+        const safeMaxHeight = maxHeight !== undefined ? Math.floor(maxHeight) - 1 : undefined;
+        setScrollState((prev) => {
+            if (prev.maxHeight === safeMaxHeight && prev.isScrolling === isScrolling)
+                return prev;
+            return { isScrolling, maxHeight: safeMaxHeight };
+        });
+    }, [isOpen, disable, triggerRef, listRef, position, menuOffset]);
+    /**
+     * Calculate synchronously before paint to prevent flicker.
+     * This ensures maxHeight is applied to the DOM before useTriggerPosition's
+     * requestAnimationFrame fires, so it measures the constrained height on its first pass.
+     */
+    useLayoutEffect(() => {
+        if (isOpen && !disable) {
+            calculateScroll();
+        }
+    }, [isOpen, disable, calculateScroll]);
+    /**
+     * Respond to window resize and content size changes (e.g. images loading,
+     * lazy content, dynamically added items).
+     */
+    useEffect(() => {
+        if (!isOpen || disable)
+            return;
+        window.addEventListener('resize', calculateScroll);
+        const listElement = listRef.current;
+        let resizeObserver;
+        if (listElement) {
+            resizeObserver = new ResizeObserver(calculateScroll);
+            resizeObserver.observe(listElement);
+        }
+        return () => {
+            window.removeEventListener('resize', calculateScroll);
+            resizeObserver === null || resizeObserver === void 0 ? void 0 : resizeObserver.disconnect();
+        };
+    }, [isOpen, disable, calculateScroll, listRef]);
+    return scrollState;
+};

package/dist/esm/components/menu/hooks/useSubMenuElementPosition.js

@@ -0,0 +1,64 @@
+import { useState, useEffect } from 'react';
+import { findClosestMenuParent, calculateLeftPosition, calculateTopPosition } from '../MrlMenu/utilities';
+/**
+ * Calculates the position of the sub menu element
+ *
+ * @param triggerRef - The trigger element ref
+ * @param menuRef - The menu element ref
+ * @param isSubMenu - Is the menu a sub menu
+ * @param isOpen - Is the element visible
+ * @param originalMenuRect - The menu element rect
+ * @param disable - Should the menu be disabled
+ * @returns The sub menu position
+ */
+export const useSubMenuElementPosition = (triggerRef, menuRef, isSubMenu, isOpen, originalMenuRect, disable) => {
+    const [subMenuPosition, setSubMenuPosition] = useState({
+        left: 'calc(100% - 5px)',
+        top: ''
+    });
+    const [menuRect, setMenuRect] = useState(null);
+    useEffect(() => {
+        if (!disable && isOpen && menuRef.current && !originalMenuRect) {
+            setMenuRect(menuRef.current.getBoundingClientRect());
+        }
+    }, [
+        disable,
+        isOpen,
+        menuRef,
+        originalMenuRect
+    ]);
+    useEffect(() => {
+        if (disable ||
+            !(triggerRef === null || triggerRef === void 0 ? void 0 : triggerRef.current) ||
+            !menuRef.current ||
+            !isSubMenu ||
+            !isOpen ||
+            !menuRect ||
+            !isSubMenu)
+            return;
+        const parentMenu = findClosestMenuParent(triggerRef.current);
+        const triggerRect = triggerRef.current.getBoundingClientRect();
+        if (!(parentMenu === null || parentMenu === void 0 ? void 0 : parentMenu.parentElement))
+            return;
+        const parentMenuRect = parentMenu.getBoundingClientRect();
+        const menuHeight = menuRef.current.getBoundingClientRect().height;
+        const overlapsRight = window.innerWidth < menuRect.right;
+        const overlapsLeft = triggerRect.left - menuRect.width < menuRect.width;
+        const newLeft = calculateLeftPosition(overlapsRight, overlapsLeft, menuRect, triggerRef);
+        let newTop = calculateTopPosition(overlapsRight, overlapsLeft, triggerRef, menuRect, parentMenu, triggerRect);
+        // if the submenu height is smaller than the menu height, we want to top align the submenu so it doesn't go off
+        // of the top of the screen
+        if (menuHeight > parentMenuRect.height) {
+            newTop = `0px`;
+        }
+        setSubMenuPosition({ left: newLeft, top: newTop });
+    }, [
+        disable,
+        triggerRef,
+        menuRef,
+        menuRect,
+        isSubMenu,
+        isOpen
+    ]);
+    return subMenuPosition;
+};

package/dist/esm/components/menu/index.js

@@ -0,0 +1,6 @@
+export * from './MrlMenu';
+export * from './MrlMenuItem';
+export * from './MrlMenuItemLink';
+export * from './MrlMenuGroup';
+export * from './constants';
+export * from './utilities';

package/dist/esm/components/menu/utilities/flip-position.js

@@ -0,0 +1,19 @@
+/**
+ * Flips the given position to its opposite.
+ *
+ * @param pos - The position to flip. Can be 'left', 'right', 'top', or 'bottom'.
+ * @returns The flipped position. Will be 'right' for 'left', 'left' for 'right', 'bottom' for 'top', and 'top' for 'bottom'.
+ */
+export const flipPosition = (pos) => {
+    switch (pos) {
+        case 'left':
+            return 'right';
+        case 'right':
+            return 'left';
+        case 'top':
+            return 'bottom';
+        case 'bottom':
+            return 'top';
+    }
+    return pos;
+};

package/dist/esm/components/menu/utilities/get-scrollable-parent.js

@@ -0,0 +1,20 @@
+/**
+ * Returns the closest scrollable parent of the provided element.
+ *
+ * @param element - The element to start from
+ * @returns The closest scrollable ancestor or the document's scrolling element
+ */
+export function getScrollableParent(element) {
+    if (!element)
+        return window;
+    let current = element;
+    while (current && current !== document.body) {
+        const overflowY = window.getComputedStyle(current).overflowY;
+        const isScrollable = ['auto', 'scroll', 'overlay'].includes(overflowY);
+        if (isScrollable && current.scrollHeight > current.clientHeight) {
+            return current;
+        }
+        current = current.parentElement;
+    }
+    return window;
+}

package/dist/esm/components/menu/utilities/index.js

@@ -0,0 +1,2 @@
+export * from './flip-position';
+export * from './get-scrollable-parent';