@muraldevkit/ui-toolkit 4.61.2 → 4.61.3-dev-1W6v.1

package/dist/components/menu/MrlMenu/useMenuScroll.d.ts

@@ -0,0 +1,40 @@
+import { RefObject } from 'react';
+import { MenuPosition } from '../constants';
+interface UseMenuScrollResult {
+    /** The constrained max height for the menu list when scrolling is active */
+    maxHeight: number | undefined;
+    /** Whether the menu content exceeds available space and requires internal scrolling */
+    isScrolling: boolean;
+}
+/**
+ * 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 declare const useMenuScroll: (triggerRef: RefObject<HTMLElement> | undefined, listRef: RefObject<HTMLUListElement>, position: MenuPosition, menuOffset: number, isOpen: boolean, disable: boolean) => UseMenuScrollResult;
+export {};