@flikk/ui 1.0.0-beta.3 → 1.0.0-beta.30

package/dist/hooks/index.d.ts

@@ -13,3 +13,5 @@ export { useIsClient } from "./useIsClient";
 export { useClickOutside } from "./useClickOutside";
 export { useScaleBackground } from "./useScaleBackground";
 export type { UseScaleBackgroundOptions } from "./useScaleBackground";
+export { useMediaQuery } from "./useMediaQuery";
+export { useDarkMode } from './useDarkMode';

package/dist/hooks/useClickOutside.d.ts

@@ -1,7 +1,13 @@
 import { RefObject } from 'react';
 /**
- * Custom hook that handles clicks outside of the specified element
- * @param ref The reference to the element to detect clicks outside of
- * @param handler The callback function to execute when a click outside is detected
+ * Overload 1 — legacy API: useClickOutside(ref, handler)
+ * Preserves backward compatibility with existing callers.
  */
-export declare const useClickOutside: <T extends HTMLElement | null>(ref: RefObject<T>, handler: (event: MouseEvent | TouchEvent) => void) => void;
+export declare function useClickOutside<T extends HTMLElement | null>(ref: RefObject<T>, handler: (event: MouseEvent | TouchEvent) => void): void;
+/**
+ * Overload 2 — new API: useClickOutside(callback, isActive?, additionalRefs?)
+ * Returns a ref to attach to the primary element.
+ * Accepts an optional array of additional refs whose contents count as "inside"
+ * (useful for trigger+content patterns).
+ */
+export declare function useClickOutside(callback: () => void, isActive?: boolean, additionalRefs?: RefObject<HTMLElement | null>[]): RefObject<HTMLElement | null>;

package/dist/hooks/useClickOutside.js

@@ -1,28 +1,49 @@
-import { useRef, useEffect } from 'react';
+"use client";
+import { useRef, useCallback, useEffect } from 'react';
 
-/**
- * Custom hook that handles clicks outside of the specified element
- * @param ref The reference to the element to detect clicks outside of
- * @param handler The callback function to execute when a click outside is detected
- */
-const useClickOutside = (ref, handler) => {
-    const handlerRef = useRef(handler);
-    handlerRef.current = handler;
-    useEffect(() => {
-        const listener = (event) => {
-            const el = ref.current;
-            if (!el || el.contains(event.target)) {
+// Implementation
+function useClickOutside(refOrCallback, handlerOrIsActive, additionalRefs) {
+    const internalRef = useRef(null);
+    const legacyHandlerRef = useRef(null);
+    // Keep legacy handler ref current
+    if (typeof refOrCallback !== 'function' && typeof handlerOrIsActive === 'function') {
+        legacyHandlerRef.current = handlerOrIsActive;
+    }
+    const isLegacy = typeof refOrCallback !== 'function';
+    const isActive = isLegacy
+        ? true
+        : typeof handlerOrIsActive === 'boolean'
+            ? handlerOrIsActive
+            : true;
+    const handleClickOutside = useCallback((event) => {
+        var _a;
+        const target = event.target;
+        if (isLegacy) {
+            const legacyRef = refOrCallback;
+            const el = legacyRef.current;
+            if (!el || el.contains(target))
+                return;
+            (_a = legacyHandlerRef.current) === null || _a === void 0 ? void 0 : _a.call(legacyHandlerRef, event);
+        }
+        else {
+            if (internalRef.current && internalRef.current.contains(target))
                 return;
-            }
-            handlerRef.current(event);
-        };
-        document.addEventListener('mousedown', listener);
-        document.addEventListener('touchstart', listener);
-        return () => {
-            document.removeEventListener('mousedown', listener);
-            document.removeEventListener('touchstart', listener);
-        };
-    }, [ref]);
-};
+            if (additionalRefs === null || additionalRefs === void 0 ? void 0 : additionalRefs.some(r => { var _a; return (_a = r.current) === null || _a === void 0 ? void 0 : _a.contains(target); }))
+                return;
+            refOrCallback();
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [isLegacy, additionalRefs]);
+    useEffect(() => {
+        if (!isActive)
+            return;
+        document.addEventListener('mousedown', handleClickOutside);
+        return () => document.removeEventListener('mousedown', handleClickOutside);
+    }, [handleClickOutside, isActive]);
+    if (isLegacy) {
+        return;
+    }
+    return internalRef;
+}
 
 export { useClickOutside };

package/dist/hooks/useDarkMode.d.ts

@@ -0,0 +1 @@
+export declare function useDarkMode(): boolean;

package/dist/hooks/useDarkMode.js

@@ -0,0 +1,43 @@
+"use client";
+import { useState, useEffect } from 'react';
+
+const _subscribers = new Set();
+let _observer = null;
+function _getIsDark() {
+    if (typeof document === 'undefined')
+        return false;
+    return (document.documentElement.classList.contains('dark') ||
+        document.body.classList.contains('dark') ||
+        document.querySelector('.dark') !== null);
+}
+function _ensureObserver() {
+    if (_observer || typeof document === 'undefined')
+        return;
+    _getIsDark();
+    _observer = new MutationObserver(() => {
+        _getIsDark();
+        _subscribers.forEach((fn) => fn());
+    });
+    _observer.observe(document.documentElement, {
+        attributes: true,
+        attributeFilter: ['class'],
+    });
+    _observer.observe(document.body, {
+        attributes: true,
+        attributeFilter: ['class'],
+    });
+}
+function useDarkMode() {
+    const [, rerender] = useState(0);
+    useEffect(() => {
+        _ensureObserver();
+        const notify = () => rerender((n) => n + 1);
+        _subscribers.add(notify);
+        return () => {
+            _subscribers.delete(notify);
+        };
+    }, []);
+    return typeof document === 'undefined' ? false : _getIsDark();
+}
+
+export { useDarkMode };

package/dist/hooks/useFocusTrap.js

@@ -1,3 +1,4 @@
+"use client";
 import { useRef, useEffect } from 'react';
 
 const FOCUSABLE_SELECTOR = [

package/dist/hooks/useFormStateMachine.d.ts

@@ -1,5 +1,5 @@
 import { StateMachineConfig, StateIdentifier } from "../utils/stateMachine";
-export interface UseFormStateMachineOptions<TData = any> {
+export interface UseFormStateMachineOptions<TData = unknown> {
     /** Initial form data */
     initialData?: TData;
     /** Callback when state changes */

package/dist/hooks/useIsClient.js

@@ -1,3 +1,4 @@
+"use client";
 import { useState, useEffect } from 'react';
 
 /**

package/dist/hooks/useMediaQuery.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Hook to detect if a media query matches.
+ * Returns false during SSR and on first render (safe default).
+ */
+export declare const useMediaQuery: (query: string) => boolean;

package/dist/hooks/useMediaQuery.js

@@ -0,0 +1,22 @@
+"use client";
+import { useState, useEffect } from 'react';
+
+/**
+ * Hook to detect if a media query matches.
+ * Returns false during SSR and on first render (safe default).
+ */
+const useMediaQuery = (query) => {
+    const [matches, setMatches] = useState(false);
+    useEffect(() => {
+        if (typeof window === "undefined")
+            return;
+        const mql = window.matchMedia(query);
+        setMatches(mql.matches);
+        const handler = (e) => setMatches(e.matches);
+        mql.addEventListener("change", handler);
+        return () => mql.removeEventListener("change", handler);
+    }, [query]);
+    return matches;
+};
+
+export { useMediaQuery };

package/dist/hooks/useNetworkStatus.d.ts

@@ -1,7 +1,3 @@
-/**
- * useNetworkStatus Hook
- * Detects online/offline status and network quality
- */
 /**
  * Network status return type
  */

package/dist/hooks/useNetworkStatus.js

@@ -1,9 +1,6 @@
+"use client";
 import { useState, useCallback, useRef, useEffect } from 'react';
 
-/**
- * useNetworkStatus Hook
- * Detects online/offline status and network quality
- */
 /**
  * Get the Network Information API connection object
  */
@@ -32,7 +29,7 @@ const getConnection = () => {
  * }
  */
 const useNetworkStatus = () => {
-    const [isOnline, setIsOnline] = useState(() => typeof navigator !== "undefined" ? navigator.onLine : true);
+    const [isOnline, setIsOnline] = useState(typeof navigator !== "undefined" ? navigator.onLine : true);
     const [wasOffline, setWasOffline] = useState(false);
     const [networkInfo, setNetworkInfo] = useState({});
     const updateNetworkInfo = useCallback(() => {

package/dist/hooks/useOverlay.d.ts

@@ -1,3 +1,5 @@
+export declare function lockScroll(): void;
+export declare function unlockScroll(): void;
 export interface UseOverlayOptions {
     /** Whether the overlay is currently open */
     isOpen: boolean;

package/dist/hooks/useOverlay.js

@@ -1,5 +1,40 @@
+"use client";
 import { useCallback, useEffect } from 'react';
 
+// ── Scroll-lock manager (ref-counted) ──────────────────────────────────
+// Supports nested overlays: only the first lock measures the scrollbar
+// and compensates; subsequent locks just bump the counter.
+let lockCount = 0;
+let savedOverflow = '';
+let savedPaddingRight = '';
+function lockScroll() {
+    if (typeof window === 'undefined')
+        return;
+    lockCount++;
+    if (lockCount === 1) {
+        const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;
+        // Save originals before mutating
+        savedOverflow = document.body.style.overflow;
+        savedPaddingRight = document.body.style.paddingRight;
+        // Expose width as CSS variable so fixed-position elements can compensate
+        // e.g.  position: fixed; padding-right: var(--scrollbar-width, 0px);
+        document.documentElement.style.setProperty('--scrollbar-width', `${scrollbarWidth}px`);
+        if (scrollbarWidth > 0) {
+            document.body.style.paddingRight = `${scrollbarWidth}px`;
+        }
+        document.body.style.overflow = 'hidden';
+    }
+}
+function unlockScroll() {
+    if (typeof window === 'undefined')
+        return;
+    lockCount = Math.max(0, lockCount - 1);
+    if (lockCount === 0) {
+        document.body.style.overflow = savedOverflow;
+        document.body.style.paddingRight = savedPaddingRight;
+        document.documentElement.style.removeProperty('--scrollbar-width');
+    }
+}
 /**
  * Shared hook for overlay behavior (escape key, scroll lock, click handling)
  *
@@ -49,15 +84,15 @@ const useOverlay = ({ isOpen, onClose, closeOnEsc = true, closeOnOverlayClick =
         if (isOpen) {
             // Add Escape key listener
             document.addEventListener('keydown', handleEscKey);
-            // Lock body scroll to prevent background scrolling
+            // Lock body scroll (ref-counted so nested overlays work)
             if (enableScrollLock) {
-                document.body.style.overflow = 'hidden';
+                lockScroll();
             }
             // Cleanup on unmount or when overlay closes
             return () => {
                 document.removeEventListener('keydown', handleEscKey);
                 if (enableScrollLock) {
-                    document.body.style.overflow = 'unset';
+                    unlockScroll();
                 }
             };
         }
@@ -68,4 +103,4 @@ const useOverlay = ({ isOpen, onClose, closeOnEsc = true, closeOnOverlayClick =
     };
 };
 
-export { useOverlay };
+export { lockScroll, unlockScroll, useOverlay };

package/dist/hooks/useScaleBackground.js

@@ -1,6 +1,8 @@
-import { useRef, useLayoutEffect, useEffect } from 'react';
+"use client";
+import { useRef, useEffect, useLayoutEffect } from 'react';
 import { animate } from 'motion/react';
 
+const useIsomorphicLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;
 const WRAPPER_SELECTOR = "[data-flik-drawer-wrapper]";
 /**
  * useScaleBackground
@@ -22,7 +24,9 @@ function useScaleBackground({ isOpen, scale = 0.94, borderRadius = 24, position
     const controlsRef = useRef(null);
     // Track current animation progress so rapid toggling picks up where it left off
     const progressRef = useRef(0);
-    useLayoutEffect(() => {
+    useIsomorphicLayoutEffect(() => {
+        if (typeof window === 'undefined')
+            return;
         // Skip if no scaling needed
         if (scale >= 1)
             return;

package/dist/hooks/useSelectPortal.d.ts

@@ -6,6 +6,16 @@ export interface UseSimpleDropdownOptions {
     offset?: number;
     estimatedWidth?: number;
     autoWidth?: boolean;
+    onClose?: () => void;
+    stickyTracking?: boolean;
+    /**
+     * Clamp the dropdown horizontally so it never overflows the viewport edges.
+     * Runs even when `stickyTracking` is on, because horizontal position is
+     * independent of vertical scroll and so cannot fight the scroll-follow
+     * behavior. Vertical clamping remains gated on `!stickyTracking`.
+     * @default true
+     */
+    clampToViewport?: boolean;
 }
 export interface SimpleDropdownReturn {
     position: {
@@ -24,5 +34,5 @@ export interface SimpleDropdownReturn {
  * Uses position: fixed with pure viewport coordinates to properly follow scroll
  * Fixes critical issues: dropdown not following scroll & multiple dropdowns not working
  */
-export declare const useSimpleDropdown: ({ triggerRef, isOpen, placement, offset, estimatedWidth, autoWidth, }: UseSimpleDropdownOptions) => SimpleDropdownReturn;
-export declare const useSelectPortal: ({ triggerRef, isOpen, placement, offset, estimatedWidth, autoWidth, }: UseSimpleDropdownOptions) => SimpleDropdownReturn;
+export declare const useSimpleDropdown: ({ triggerRef, isOpen, placement, offset, estimatedWidth, autoWidth, onClose, stickyTracking, clampToViewport, }: UseSimpleDropdownOptions) => SimpleDropdownReturn;
+export declare const useSelectPortal: ({ triggerRef, isOpen, placement, offset, estimatedWidth, autoWidth, onClose, stickyTracking, clampToViewport, }: UseSimpleDropdownOptions) => SimpleDropdownReturn;

package/dist/hooks/useSelectPortal.js

@@ -1,19 +1,13 @@
-import { useRef, useState, useCallback, useLayoutEffect, useMemo } from 'react';
+"use client";
+import { useRef, useState, useCallback, useLayoutEffect, useEffect } from 'react';
 
-// Simple debounce utility
-const debounce = (func, wait) => {
-    let timeout;
-    return () => {
-        clearTimeout(timeout);
-        timeout = setTimeout(func, wait);
-    };
-};
+const useIsomorphicLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;
 /**
  * Fixed dropdown positioning hook
  * Uses position: fixed with pure viewport coordinates to properly follow scroll
  * Fixes critical issues: dropdown not following scroll & multiple dropdowns not working
  */
-const useSimpleDropdown = ({ triggerRef, isOpen, placement = "bottom-start", offset = 4, estimatedWidth, autoWidth = false, }) => {
+const useSimpleDropdown = ({ triggerRef, isOpen, placement = "bottom-start", offset = 4, estimatedWidth, autoWidth = false, onClose, stickyTracking = false, clampToViewport = true, }) => {
     const contentRef = useRef(null);
     const [position, setPosition] = useState({ top: -9999, left: -9999, width: 0 });
     const [cssVariables, setCssVariables] = useState({});
@@ -22,6 +16,7 @@ const useSimpleDropdown = ({ triggerRef, isOpen, placement = "bottom-start", off
     const [isReady, setIsReady] = useState(false);
     const isInitialRenderRef = useRef(true);
     const rafIdRef = useRef(null);
+    const frozenPlacementRef = useRef(placement);
     // Enhanced measurement system - use actual DOM measurements when available
     const measureDropdownHeight = useCallback(() => {
         if (contentRef.current) {
@@ -130,6 +125,7 @@ const useSimpleDropdown = ({ triggerRef, isOpen, placement = "bottom-start", off
         }
         setActualPlacement(finalPlacement);
         setIsFlipped(needsFlip);
+        frozenPlacementRef.current = finalPlacement;
         // Calculate position based on final placement
         let top = 0;
         let left = 0;
@@ -174,51 +170,63 @@ const useSimpleDropdown = ({ triggerRef, isOpen, placement = "bottom-start", off
                 left = rect.right + offset;
             }
         }
-        // Collision detection - handle both horizontal and vertical overflow
-        // Horizontal bounds checking
-        const rightEdge = left + dropdownWidth;
-        const overflow = rightEdge - (viewportWidth - margin);
-        if (overflow > 0) {
-            // Shift left just enough to fit
-            const shiftedLeft = left - overflow;
-            if (shiftedLeft >= margin) {
-                left = shiftedLeft;
+        // Collision detection. Horizontal clamping runs whenever `clampToViewport`
+        // is on (default) — even with stickyTracking — because horizontal position
+        // is independent of vertical scroll and so cannot fight scroll-follow.
+        // Vertical clamping stays gated on `!stickyTracking` so the dropdown can
+        // follow the trigger past the top/bottom viewport edges during scroll.
+        if (clampToViewport) {
+            // Horizontal bounds checking
+            const rightEdge = left + dropdownWidth;
+            const overflow = rightEdge - (viewportWidth - margin);
+            if (overflow > 0) {
+                // Shift left just enough to fit
+                const shiftedLeft = left - overflow;
+                left = shiftedLeft >= margin ? shiftedLeft : margin;
             }
-            else {
-                // Clamp to viewport margin
+            // Handle left edge overflow
+            if (left < margin) {
                 left = margin;
             }
         }
-        // Handle left edge overflow
-        if (left < margin) {
-            left = margin;
-        }
-        // Vertical bounds checking
-        const bottomEdge = top + dropdownHeight;
-        const verticalOverflow = bottomEdge - (viewportHeight - margin);
-        if (verticalOverflow > 0) {
-            // Shift up just enough to fit
-            const shiftedTop = top - verticalOverflow;
-            if (shiftedTop >= margin) {
-                top = shiftedTop;
+        {
+            // Vertical clamp runs on every calculatePosition — initial open, resize,
+            // and the non-sticky scroll path. The sticky scroll-follow path
+            // (updatePositionInDOM) stays unclamped so the popover tracks the trigger
+            // past the top/bottom edges during scroll. Clamping here means a sticky
+            // popover still OPENS fully on-screen even in a short viewport.
+            const bottomEdge = top + dropdownHeight;
+            const verticalOverflow = bottomEdge - (viewportHeight - margin);
+            if (verticalOverflow > 0) {
+                // Shift up just enough to fit
+                const shiftedTop = top - verticalOverflow;
+                if (shiftedTop >= margin) {
+                    top = shiftedTop;
+                }
+                else {
+                    // Clamp to viewport margin
+                    top = margin;
+                }
             }
-            else {
-                // Clamp to viewport margin
+            // Handle top edge overflow
+            if (top < margin) {
                 top = margin;
             }
         }
-        // Handle top edge overflow
-        if (top < margin) {
-            top = margin;
-        }
         setPosition({ top, left, width: dropdownWidth });
-        // Calculate available space based on placement direction
+        // Calculate available space (drives the scrollable max-height var).
+        // Sticky overlays (Popover/Dropdown) clamp their open position to the
+        // viewport, so they can occupy the full usable viewport height regardless
+        // of which side of the trigger they sit on — size against that, not just
+        // the cramped space below. Non-sticky dropdowns (Select) keep per-side
+        // space so they never grow over their trigger.
+        const usableViewportHeight = viewportHeight - margin * 2 - offset;
         let availableSpace = 0;
         if (finalPlacement.startsWith("top")) {
-            availableSpace = spaceAbove - offset;
+            availableSpace = stickyTracking ? usableViewportHeight : spaceAbove - offset;
         }
         else if (finalPlacement.startsWith("bottom")) {
-            availableSpace = spaceBelow - offset;
+            availableSpace = stickyTracking ? usableViewportHeight : spaceBelow - offset;
         }
         else if (finalPlacement.startsWith("left")) {
             availableSpace = spaceLeft - offset;
@@ -242,9 +250,71 @@ const useSimpleDropdown = ({ triggerRef, isOpen, placement = "bottom-start", off
         }
         setCssVariables(cssVars);
         // Mark initial render as complete after first calculation
-    }, [measureDropdownHeight, measureDropdownWidth, offset, placement, triggerRef]);
+    }, [measureDropdownHeight, measureDropdownWidth, offset, placement, triggerRef, stickyTracking, clampToViewport]);
+    // Direct DOM mutation for stickyTracking — bypasses React state for zero-lag scroll tracking
+    const updatePositionInDOM = useCallback(() => {
+        if (!triggerRef.current || !contentRef.current)
+            return;
+        const rect = triggerRef.current.getBoundingClientRect();
+        const frozen = frozenPlacementRef.current;
+        const dropdownHeight = measureDropdownHeight();
+        const dropdownWidth = measureDropdownWidth();
+        let top = 0;
+        let left = 0;
+        if (frozen.startsWith("top") || frozen.startsWith("bottom")) {
+            if (frozen.includes("start")) {
+                left = rect.left;
+            }
+            else if (frozen.includes("end")) {
+                left = rect.right - dropdownWidth;
+            }
+            else {
+                left = rect.left + (rect.width / 2) - (dropdownWidth / 2);
+            }
+            if (frozen.startsWith("top")) {
+                top = rect.top - dropdownHeight - offset;
+            }
+            else {
+                top = rect.bottom + offset;
+            }
+        }
+        else if (frozen.startsWith("left") || frozen.startsWith("right")) {
+            if (frozen.includes("start")) {
+                top = rect.top;
+            }
+            else if (frozen.includes("end")) {
+                top = rect.bottom - dropdownHeight;
+            }
+            else {
+                top = rect.top + (rect.height / 2) - (dropdownHeight / 2);
+            }
+            if (frozen.startsWith("left")) {
+                left = rect.left - dropdownWidth - offset;
+            }
+            else {
+                left = rect.right + offset;
+            }
+        }
+        // Keep horizontal clamping consistent with calculatePosition so the popover
+        // doesn't re-overflow the right edge when scroll-tracking recomputes position.
+        if (clampToViewport) {
+            const margin = 16;
+            const viewportWidth = window.innerWidth;
+            const overflow = left + dropdownWidth - (viewportWidth - margin);
+            if (overflow > 0) {
+                const shiftedLeft = left - overflow;
+                left = shiftedLeft >= margin ? shiftedLeft : margin;
+            }
+            if (left < margin)
+                left = margin;
+        }
+        contentRef.current.style.top = `${top}px`;
+        contentRef.current.style.left = `${left}px`;
+    }, [triggerRef, measureDropdownHeight, measureDropdownWidth, offset, clampToViewport]);
     // Reset initial render flag when dropdown opens
-    useLayoutEffect(() => {
+    useIsomorphicLayoutEffect(() => {
+        if (typeof window === 'undefined')
+            return;
         if (!isOpen) {
             if (rafIdRef.current !== null) {
                 cancelAnimationFrame(rafIdRef.current);
@@ -275,27 +345,72 @@ const useSimpleDropdown = ({ triggerRef, isOpen, placement = "bottom-start", off
         };
     }, [isOpen, calculatePosition]);
     // Initial position calculation
-    useLayoutEffect(() => {
+    useIsomorphicLayoutEffect(() => {
+        if (typeof window === 'undefined')
+            return;
         if (!isOpen)
             return;
         calculatePosition();
     }, [isOpen, calculatePosition]);
-    // Debounced position updates for better performance
-    const debouncedCalculatePosition = useMemo(() => debounce(calculatePosition, 16), // ~60fps
-    [calculatePosition]);
-    // Update position on scroll and resize - debounced for performance
-    useLayoutEffect(() => {
+    // rAF-synced scroll handler: skips internal scrolls, detects off-screen trigger
+    const scrollRafRef = useRef(null);
+    const handleScroll = useCallback((e) => {
+        // Skip if scroll originated inside the popover content
+        if (contentRef.current && contentRef.current.contains(e.target)) {
+            return;
+        }
+        // Close if trigger has scrolled off-screen (skip for stickyTracking)
+        if (!stickyTracking && triggerRef.current) {
+            const rect = triggerRef.current.getBoundingClientRect();
+            const isOffScreen = rect.bottom < 0 || rect.top > window.innerHeight
+                || rect.right < 0 || rect.left > window.innerWidth;
+            if (isOffScreen && onClose) {
+                onClose();
+                return;
+            }
+        }
+        if (stickyTracking) {
+            // Direct DOM mutation — zero-lag tracking, bypasses React state entirely
+            updatePositionInDOM();
+        }
+        else {
+            if (scrollRafRef.current)
+                cancelAnimationFrame(scrollRafRef.current);
+            scrollRafRef.current = requestAnimationFrame(() => {
+                scrollRafRef.current = null;
+                calculatePosition();
+            });
+        }
+    }, [calculatePosition, onClose, triggerRef, stickyTracking, updatePositionInDOM]);
+    const handleResize = useCallback(() => {
+        if (scrollRafRef.current)
+            cancelAnimationFrame(scrollRafRef.current);
+        scrollRafRef.current = requestAnimationFrame(() => {
+            scrollRafRef.current = null;
+            calculatePosition();
+        });
+    }, [calculatePosition]);
+    // Update position on scroll and resize - rAF-synced for smooth tracking
+    useIsomorphicLayoutEffect(() => {
+        if (typeof window === 'undefined')
+            return;
         if (!isOpen)
             return;
-        window.addEventListener("scroll", debouncedCalculatePosition, { passive: true, capture: true });
-        window.addEventListener("resize", debouncedCalculatePosition, { passive: true });
+        window.addEventListener("scroll", handleScroll, { passive: true, capture: true });
+        window.addEventListener("resize", handleResize, { passive: true });
         return () => {
-            window.removeEventListener("scroll", debouncedCalculatePosition, true);
-            window.removeEventListener("resize", debouncedCalculatePosition);
+            window.removeEventListener("scroll", handleScroll, true);
+            window.removeEventListener("resize", handleResize);
+            if (scrollRafRef.current) {
+                cancelAnimationFrame(scrollRafRef.current);
+                scrollRafRef.current = null;
+            }
         };
-    }, [isOpen, debouncedCalculatePosition]);
+    }, [isOpen, handleScroll, handleResize]);
     // Recalculate when dropdown content resizes (e.g. search filtering)
-    useLayoutEffect(() => {
+    useIsomorphicLayoutEffect(() => {
+        if (typeof window === 'undefined')
+            return;
         if (!isOpen)
             return;
         if (!contentRef.current)
@@ -303,6 +418,10 @@ const useSimpleDropdown = ({ triggerRef, isOpen, placement = "bottom-start", off
         if (typeof ResizeObserver === "undefined")
             return;
         const observer = new ResizeObserver(() => {
+            // Content resize (incl. the initial settle right after open) goes through
+            // calculatePosition so the popover re-fits and stays vertically clamped to
+            // the viewport. Only the scroll path uses the unclamped updatePositionInDOM
+            // follow — otherwise the resize-on-open would immediately undo the clamp.
             calculatePosition();
         });
         observer.observe(contentRef.current);