@trackunit/react-components 1.21.8 → 1.21.12

package/index.cjs.js

@@ -1341,6 +1341,15 @@ const createBreakpointState = ({ width }) => {
     }), { ...defaultBreakpointState });
 };
 
+const canUseMatchMedia = () => typeof window !== "undefined" && typeof window.matchMedia === "function";
+const getViewportBreakpointState = () => {
+    if (!canUseMatchMedia())
+        return { ...defaultBreakpointState };
+    return sharedUtils.objectEntries(uiDesignTokens.themeScreenSizeAsNumber).reduce((acc, [size, minWidth]) => ({
+        ...acc,
+        [breakpointPropsMap[size]]: window.matchMedia(`(min-width: ${minWidth}px)`).matches,
+    }), { ...defaultBreakpointState });
+};
 /**
  * A custom React hook that provides real-time information about the current viewport size.
  * ! Consider using `useContainerBreakpoints` instead, and only use this when you need to actually react to the viewport size, not the container size.
@@ -1364,36 +1373,23 @@ const createBreakpointState = ({ width }) => {
  */
 const useViewportBreakpoints = (options = {}) => {
     const { skip = false } = options;
-    const [viewportSize, setViewportSize] = react.useState(() => {
-        const newViewportSize = sharedUtils.objectEntries(uiDesignTokens.themeScreenSizeAsNumber).reduce((acc, [size, minWidth]) => ({
-            ...acc,
-            [breakpointPropsMap[size]]: window.matchMedia(`(min-width: ${minWidth}px)`).matches,
-        }), { ...defaultBreakpointState });
-        return newViewportSize;
-    });
+    const [viewportSize, setViewportSize] = react.useState(getViewportBreakpointState);
     const updateViewportSize = react.useCallback(() => {
-        const newViewportSize = sharedUtils.objectEntries(uiDesignTokens.themeScreenSizeAsNumber).reduce((acc, [size, minWidth]) => ({
-            ...acc,
-            [breakpointPropsMap[size]]: window.matchMedia(`(min-width: ${minWidth}px)`).matches,
-        }), { ...defaultBreakpointState });
-        setViewportSize(newViewportSize);
+        setViewportSize(getViewportBreakpointState());
     }, []);
     const updateViewportSizeRef = react.useRef(updateViewportSize);
     react.useEffect(() => {
         updateViewportSizeRef.current = updateViewportSize;
     }, [updateViewportSize]);
     react.useEffect(() => {
-        if (skip) {
+        if (skip || !canUseMatchMedia()) {
             return;
         }
-        // Initial check
         updateViewportSizeRef.current();
-        // Set up listeners for each breakpoint
         const mediaQueryLists = sharedUtils.objectEntries(uiDesignTokens.themeScreenSizeAsNumber).map(([_, minWidth]) => window.matchMedia(`(min-width: ${minWidth}px)`));
         mediaQueryLists.forEach(mql => {
             mql.addEventListener("change", updateViewportSizeRef.current);
         });
-        // Cleanup
         return () => {
             mediaQueryLists.forEach(mql => {
                 mql.removeEventListener("change", updateViewportSizeRef.current);
@@ -9812,6 +9808,112 @@ const useModifierKey = ({ exclude = [] } = {}) => {
     return isModifierPressed;
 };
 
+const resolveRootEl = (refLike) => {
+    if (refLike && typeof refLike === "object" && "current" in refLike) {
+        return refLike.current;
+    }
+    return refLike;
+};
+/**
+ * Observes a scroll area within the given root element and toggles CSS
+ * class(es) on a target element when the scroll area overflows vertically.
+ *
+ * Behavior:
+ * - Locates elements via CSS selectors within the root.
+ * - Recomputes on resize, DOM mutations within the scroll area, scroll
+ *   events, and image load/error events.
+ * - Cleans up all observers/listeners on unmount or dependency change.
+ *
+ * Edge cases:
+ * - If either element is missing, retries via requestAnimationFrame
+ *   (up to 20 attempts) to handle deferred DOM mounting (e.g. portals).
+ * - No DOM mutations occur when `enabled` is false.
+ *
+ * @param rootRef Root element that contains both the scroll area and the target.
+ * @param options Configuration.
+ * @param options.scrollAreaSelector CSS selector to locate the scrollable element.
+ * @param options.targetSelector CSS selector to locate the element that receives the class toggle.
+ * @param options.toggleClass CSS class(es) toggled on the target when the scroll area overflows. Accepts string or string[].
+ * @param options.enabled Whether the hook is active. Defaults to true.
+ */
+const useOverflowBorder = (rootRef, { scrollAreaSelector, targetSelector, toggleClass, enabled = true }) => {
+    react.useLayoutEffect(() => {
+        if (!enabled)
+            return;
+        let cleanup;
+        let cancelled = false;
+        const classes = Array.isArray(toggleClass)
+            ? toggleClass.filter(Boolean)
+            : String(toggleClass).split(/\s+/).filter(Boolean);
+        let attempts = 0;
+        const MAX_ATTEMPTS = 20;
+        const tryInit = () => {
+            if (cancelled)
+                return;
+            const root = resolveRootEl(rootRef);
+            if (!root) {
+                if (attempts++ < MAX_ATTEMPTS)
+                    requestAnimationFrame(tryInit);
+                return;
+            }
+            const scrollAreaEl = root.querySelector(scrollAreaSelector);
+            const targetEl = root.querySelector(targetSelector);
+            if (!scrollAreaEl || !targetEl) {
+                if (attempts++ < MAX_ATTEMPTS)
+                    requestAnimationFrame(tryInit);
+                return;
+            }
+            const update = () => {
+                const hasOverflow = scrollAreaEl.scrollHeight > scrollAreaEl.clientHeight;
+                classes.forEach(cls => targetEl.classList.toggle(cls, hasOverflow));
+            };
+            update();
+            const ro = new ResizeObserver(update);
+            ro.observe(scrollAreaEl);
+            const attachImgListeners = (node) => {
+                node.querySelectorAll("img").forEach(img => {
+                    if (!img.complete) {
+                        const once = () => update();
+                        img.addEventListener("load", once, { once: true });
+                        img.addEventListener("error", once, { once: true });
+                    }
+                });
+            };
+            attachImgListeners(scrollAreaEl);
+            const mo = new MutationObserver(muts => {
+                update();
+                for (const m of muts) {
+                    m.addedNodes.forEach(n => {
+                        if (n instanceof HTMLImageElement) {
+                            if (!n.complete) {
+                                const once = () => update();
+                                n.addEventListener("load", once, { once: true });
+                                n.addEventListener("error", once, { once: true });
+                            }
+                        }
+                        else if (n instanceof HTMLElement) {
+                            attachImgListeners(n);
+                        }
+                    });
+                }
+            });
+            mo.observe(scrollAreaEl, { childList: true, subtree: true, characterData: true });
+            scrollAreaEl.addEventListener("scroll", update, { passive: true });
+            cleanup = () => {
+                ro.disconnect();
+                mo.disconnect();
+                scrollAreaEl.removeEventListener("scroll", update);
+                classes.forEach(cls => targetEl.classList.remove(cls));
+            };
+        };
+        requestAnimationFrame(tryInit);
+        return () => {
+            cancelled = true;
+            cleanup?.();
+        };
+    }, [enabled, toggleClass, scrollAreaSelector, targetSelector, rootRef]);
+};
+
 /**
  * The usePrevious hook is a useful tool for tracking the previous value of a variable in a functional component. This can be particularly handy in scenarios where it is necessary to compare the current value with the previous one, such as triggering actions or rendering based on changes.
  *
@@ -10329,6 +10431,7 @@ exports.useLocalStorageReducer = useLocalStorageReducer;
 exports.useMeasure = useMeasure;
 exports.useMergeRefs = useMergeRefs;
 exports.useModifierKey = useModifierKey;
+exports.useOverflowBorder = useOverflowBorder;
 exports.useOverflowItems = useOverflowItems;
 exports.usePopoverContext = usePopoverContext;
 exports.usePrevious = usePrevious;

package/index.esm.js

@@ -1339,6 +1339,15 @@ const createBreakpointState = ({ width }) => {
     }), { ...defaultBreakpointState });
 };
 
+const canUseMatchMedia = () => typeof window !== "undefined" && typeof window.matchMedia === "function";
+const getViewportBreakpointState = () => {
+    if (!canUseMatchMedia())
+        return { ...defaultBreakpointState };
+    return objectEntries(themeScreenSizeAsNumber).reduce((acc, [size, minWidth]) => ({
+        ...acc,
+        [breakpointPropsMap[size]]: window.matchMedia(`(min-width: ${minWidth}px)`).matches,
+    }), { ...defaultBreakpointState });
+};
 /**
  * A custom React hook that provides real-time information about the current viewport size.
  * ! Consider using `useContainerBreakpoints` instead, and only use this when you need to actually react to the viewport size, not the container size.
@@ -1362,36 +1371,23 @@ const createBreakpointState = ({ width }) => {
  */
 const useViewportBreakpoints = (options = {}) => {
     const { skip = false } = options;
-    const [viewportSize, setViewportSize] = useState(() => {
-        const newViewportSize = objectEntries(themeScreenSizeAsNumber).reduce((acc, [size, minWidth]) => ({
-            ...acc,
-            [breakpointPropsMap[size]]: window.matchMedia(`(min-width: ${minWidth}px)`).matches,
-        }), { ...defaultBreakpointState });
-        return newViewportSize;
-    });
+    const [viewportSize, setViewportSize] = useState(getViewportBreakpointState);
     const updateViewportSize = useCallback(() => {
-        const newViewportSize = objectEntries(themeScreenSizeAsNumber).reduce((acc, [size, minWidth]) => ({
-            ...acc,
-            [breakpointPropsMap[size]]: window.matchMedia(`(min-width: ${minWidth}px)`).matches,
-        }), { ...defaultBreakpointState });
-        setViewportSize(newViewportSize);
+        setViewportSize(getViewportBreakpointState());
     }, []);
     const updateViewportSizeRef = useRef(updateViewportSize);
     useEffect(() => {
         updateViewportSizeRef.current = updateViewportSize;
     }, [updateViewportSize]);
     useEffect(() => {
-        if (skip) {
+        if (skip || !canUseMatchMedia()) {
             return;
         }
-        // Initial check
         updateViewportSizeRef.current();
-        // Set up listeners for each breakpoint
         const mediaQueryLists = objectEntries(themeScreenSizeAsNumber).map(([_, minWidth]) => window.matchMedia(`(min-width: ${minWidth}px)`));
         mediaQueryLists.forEach(mql => {
             mql.addEventListener("change", updateViewportSizeRef.current);
         });
-        // Cleanup
         return () => {
             mediaQueryLists.forEach(mql => {
                 mql.removeEventListener("change", updateViewportSizeRef.current);
@@ -9810,6 +9806,112 @@ const useModifierKey = ({ exclude = [] } = {}) => {
     return isModifierPressed;
 };
 
+const resolveRootEl = (refLike) => {
+    if (refLike && typeof refLike === "object" && "current" in refLike) {
+        return refLike.current;
+    }
+    return refLike;
+};
+/**
+ * Observes a scroll area within the given root element and toggles CSS
+ * class(es) on a target element when the scroll area overflows vertically.
+ *
+ * Behavior:
+ * - Locates elements via CSS selectors within the root.
+ * - Recomputes on resize, DOM mutations within the scroll area, scroll
+ *   events, and image load/error events.
+ * - Cleans up all observers/listeners on unmount or dependency change.
+ *
+ * Edge cases:
+ * - If either element is missing, retries via requestAnimationFrame
+ *   (up to 20 attempts) to handle deferred DOM mounting (e.g. portals).
+ * - No DOM mutations occur when `enabled` is false.
+ *
+ * @param rootRef Root element that contains both the scroll area and the target.
+ * @param options Configuration.
+ * @param options.scrollAreaSelector CSS selector to locate the scrollable element.
+ * @param options.targetSelector CSS selector to locate the element that receives the class toggle.
+ * @param options.toggleClass CSS class(es) toggled on the target when the scroll area overflows. Accepts string or string[].
+ * @param options.enabled Whether the hook is active. Defaults to true.
+ */
+const useOverflowBorder = (rootRef, { scrollAreaSelector, targetSelector, toggleClass, enabled = true }) => {
+    useLayoutEffect(() => {
+        if (!enabled)
+            return;
+        let cleanup;
+        let cancelled = false;
+        const classes = Array.isArray(toggleClass)
+            ? toggleClass.filter(Boolean)
+            : String(toggleClass).split(/\s+/).filter(Boolean);
+        let attempts = 0;
+        const MAX_ATTEMPTS = 20;
+        const tryInit = () => {
+            if (cancelled)
+                return;
+            const root = resolveRootEl(rootRef);
+            if (!root) {
+                if (attempts++ < MAX_ATTEMPTS)
+                    requestAnimationFrame(tryInit);
+                return;
+            }
+            const scrollAreaEl = root.querySelector(scrollAreaSelector);
+            const targetEl = root.querySelector(targetSelector);
+            if (!scrollAreaEl || !targetEl) {
+                if (attempts++ < MAX_ATTEMPTS)
+                    requestAnimationFrame(tryInit);
+                return;
+            }
+            const update = () => {
+                const hasOverflow = scrollAreaEl.scrollHeight > scrollAreaEl.clientHeight;
+                classes.forEach(cls => targetEl.classList.toggle(cls, hasOverflow));
+            };
+            update();
+            const ro = new ResizeObserver(update);
+            ro.observe(scrollAreaEl);
+            const attachImgListeners = (node) => {
+                node.querySelectorAll("img").forEach(img => {
+                    if (!img.complete) {
+                        const once = () => update();
+                        img.addEventListener("load", once, { once: true });
+                        img.addEventListener("error", once, { once: true });
+                    }
+                });
+            };
+            attachImgListeners(scrollAreaEl);
+            const mo = new MutationObserver(muts => {
+                update();
+                for (const m of muts) {
+                    m.addedNodes.forEach(n => {
+                        if (n instanceof HTMLImageElement) {
+                            if (!n.complete) {
+                                const once = () => update();
+                                n.addEventListener("load", once, { once: true });
+                                n.addEventListener("error", once, { once: true });
+                            }
+                        }
+                        else if (n instanceof HTMLElement) {
+                            attachImgListeners(n);
+                        }
+                    });
+                }
+            });
+            mo.observe(scrollAreaEl, { childList: true, subtree: true, characterData: true });
+            scrollAreaEl.addEventListener("scroll", update, { passive: true });
+            cleanup = () => {
+                ro.disconnect();
+                mo.disconnect();
+                scrollAreaEl.removeEventListener("scroll", update);
+                classes.forEach(cls => targetEl.classList.remove(cls));
+            };
+        };
+        requestAnimationFrame(tryInit);
+        return () => {
+            cancelled = true;
+            cleanup?.();
+        };
+    }, [enabled, toggleClass, scrollAreaSelector, targetSelector, rootRef]);
+};
+
 /**
  * The usePrevious hook is a useful tool for tracking the previous value of a variable in a functional component. This can be particularly handy in scenarios where it is necessary to compare the current value with the previous one, such as triggering actions or rendering based on changes.
  *
@@ -10174,4 +10276,4 @@ const useWindowActivity = ({ onFocus, onBlur, skip = false } = { onBlur: undefin
     return useMemo(() => ({ focused }), [focused]);
 };
 
-export { ActionRenderer, Alert, Badge, Breadcrumb, BreadcrumbContainer, Button, Card, CardBody, CardFooter, CardHeader, Collapse, CompletionStatusIndicator, CopyableText, DEFAULT_SKELETON_PREFERENCE_CARD_PROPS, DetailsList, EmptyState, EmptyValue, ExternalLink, GridAreas, Heading, Highlight, HorizontalOverflowScroller, Icon, IconButton, Indicator, KPI, KPICard, KPICardSkeleton, KPISkeleton, List, ListItem, MenuDivider, MenuItem, MenuList, MoreMenu, Notice, PackageNameStoryComponent, Page, PageContent, PageHeader, PageHeaderKpiMetrics, PageHeaderSecondaryActions, PageHeaderTitle, Pagination, Polygon, Popover, PopoverContent, PopoverTitle, PopoverTrigger, Portal, PreferenceCard, PreferenceCardSkeleton, Prompt, ROLE_CARD, SectionHeader, SegmentedValueBar, Sidebar, SkeletonBlock, SkeletonLabel, SkeletonLines, Spacer, Spinner, StarButton, Tab, TabContent, TabList, Tabs, Tag, Text, ToggleGroup, Tooltip, TrendIndicator, TrendIndicators, ValueBar, ZStack, createGrid, cvaButton, cvaButtonPrefixSuffix, cvaButtonSpinner, cvaButtonSpinnerContainer, cvaClickable, cvaContainerStyles, cvaContentContainer, cvaContentWrapper, cvaDescriptionCard, cvaIconBackground, cvaIconButton, cvaImgStyles, cvaIndicator, cvaIndicatorIcon, cvaIndicatorIconBackground, cvaIndicatorLabel, cvaIndicatorPing, cvaInputContainer, cvaInteractableItem, cvaList, cvaListContainer, cvaListItem$1 as cvaListItem, cvaMenu, cvaMenuItem, cvaMenuItemLabel, cvaMenuItemPrefix, cvaMenuItemStyle, cvaMenuItemSuffix, cvaMenuList, cvaMenuListDivider, cvaMenuListItem, cvaMenuListMultiSelect, cvaPageHeader, cvaPageHeaderContainer, cvaPageHeaderHeading, cvaPreferenceCard, cvaTitleCard, cvaToggleGroup, cvaToggleGroupWithSlidingBackground, cvaToggleItem, cvaToggleItemContent, cvaToggleItemText, cvaZStackContainer, cvaZStackItem, defaultPageSize, docs, getDevicePixelRatio, getValueBarColorByValue, iconColorNames, iconPalette, noPagination, preferenceCardGrid, useBidirectionalScroll, useClickOutside, useContainerBreakpoints, useContinuousTimeout, useCopyToClipboard, useCursorUrlSync, useCustomEncoding, useDebounce, useDevicePixelRatio, useElevatedReducer, useElevatedState, useGridAreas, useHover, useInfiniteScroll, useIsFirstRender, useIsFullscreen, useIsTextTruncated, useKeyboardShortcut, useList, useListItemHeight, useLocalStorage, useLocalStorageReducer, useMeasure, useMergeRefs, useModifierKey, useOverflowItems, usePopoverContext, usePrevious, usePrompt, useRandomCSSLengths, useRelayPagination, useResize, useScrollBlock, useScrollDetection, useSelfUpdatingRef, useSessionStorage, useSessionStorageReducer, useTextSearch, useTimeout, useViewportBreakpoints, useWatch, useWindowActivity };
+export { ActionRenderer, Alert, Badge, Breadcrumb, BreadcrumbContainer, Button, Card, CardBody, CardFooter, CardHeader, Collapse, CompletionStatusIndicator, CopyableText, DEFAULT_SKELETON_PREFERENCE_CARD_PROPS, DetailsList, EmptyState, EmptyValue, ExternalLink, GridAreas, Heading, Highlight, HorizontalOverflowScroller, Icon, IconButton, Indicator, KPI, KPICard, KPICardSkeleton, KPISkeleton, List, ListItem, MenuDivider, MenuItem, MenuList, MoreMenu, Notice, PackageNameStoryComponent, Page, PageContent, PageHeader, PageHeaderKpiMetrics, PageHeaderSecondaryActions, PageHeaderTitle, Pagination, Polygon, Popover, PopoverContent, PopoverTitle, PopoverTrigger, Portal, PreferenceCard, PreferenceCardSkeleton, Prompt, ROLE_CARD, SectionHeader, SegmentedValueBar, Sidebar, SkeletonBlock, SkeletonLabel, SkeletonLines, Spacer, Spinner, StarButton, Tab, TabContent, TabList, Tabs, Tag, Text, ToggleGroup, Tooltip, TrendIndicator, TrendIndicators, ValueBar, ZStack, createGrid, cvaButton, cvaButtonPrefixSuffix, cvaButtonSpinner, cvaButtonSpinnerContainer, cvaClickable, cvaContainerStyles, cvaContentContainer, cvaContentWrapper, cvaDescriptionCard, cvaIconBackground, cvaIconButton, cvaImgStyles, cvaIndicator, cvaIndicatorIcon, cvaIndicatorIconBackground, cvaIndicatorLabel, cvaIndicatorPing, cvaInputContainer, cvaInteractableItem, cvaList, cvaListContainer, cvaListItem$1 as cvaListItem, cvaMenu, cvaMenuItem, cvaMenuItemLabel, cvaMenuItemPrefix, cvaMenuItemStyle, cvaMenuItemSuffix, cvaMenuList, cvaMenuListDivider, cvaMenuListItem, cvaMenuListMultiSelect, cvaPageHeader, cvaPageHeaderContainer, cvaPageHeaderHeading, cvaPreferenceCard, cvaTitleCard, cvaToggleGroup, cvaToggleGroupWithSlidingBackground, cvaToggleItem, cvaToggleItemContent, cvaToggleItemText, cvaZStackContainer, cvaZStackItem, defaultPageSize, docs, getDevicePixelRatio, getValueBarColorByValue, iconColorNames, iconPalette, noPagination, preferenceCardGrid, useBidirectionalScroll, useClickOutside, useContainerBreakpoints, useContinuousTimeout, useCopyToClipboard, useCursorUrlSync, useCustomEncoding, useDebounce, useDevicePixelRatio, useElevatedReducer, useElevatedState, useGridAreas, useHover, useInfiniteScroll, useIsFirstRender, useIsFullscreen, useIsTextTruncated, useKeyboardShortcut, useList, useListItemHeight, useLocalStorage, useLocalStorageReducer, useMeasure, useMergeRefs, useModifierKey, useOverflowBorder, useOverflowItems, usePopoverContext, usePrevious, usePrompt, useRandomCSSLengths, useRelayPagination, useResize, useScrollBlock, useScrollDetection, useSelfUpdatingRef, useSessionStorage, useSessionStorageReducer, useTextSearch, useTimeout, useViewportBreakpoints, useWatch, useWindowActivity };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-components",
-  "version": "1.21.8",
+  "version": "1.21.12",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -13,10 +13,10 @@
     "@floating-ui/react": "^0.26.25",
     "string-ts": "^2.0.0",
     "tailwind-merge": "^2.0.0",
-    "@trackunit/ui-design-tokens": "1.11.89",
-    "@trackunit/css-class-variance-utilities": "1.11.92",
-    "@trackunit/shared-utils": "1.13.92",
-    "@trackunit/ui-icons": "1.11.88",
+    "@trackunit/ui-design-tokens": "1.11.92",
+    "@trackunit/css-class-variance-utilities": "1.11.95",
+    "@trackunit/shared-utils": "1.13.95",
+    "@trackunit/ui-icons": "1.11.91",
     "es-toolkit": "^1.39.10",
     "@tanstack/react-virtual": "3.13.12",
     "fflate": "^0.8.2",

package/src/hooks/useOverflowBorder.d.ts

@@ -0,0 +1,33 @@
+import { type RefObject } from "react";
+type OverflowBorderOptions = {
+    readonly scrollAreaSelector: string;
+    readonly targetSelector: string;
+    readonly toggleClass: string | Array<string>;
+    readonly enabled?: boolean;
+};
+type ElementRef = HTMLElement | null;
+type ElementRefLike = ElementRef | RefObject<ElementRef>;
+/**
+ * Observes a scroll area within the given root element and toggles CSS
+ * class(es) on a target element when the scroll area overflows vertically.
+ *
+ * Behavior:
+ * - Locates elements via CSS selectors within the root.
+ * - Recomputes on resize, DOM mutations within the scroll area, scroll
+ *   events, and image load/error events.
+ * - Cleans up all observers/listeners on unmount or dependency change.
+ *
+ * Edge cases:
+ * - If either element is missing, retries via requestAnimationFrame
+ *   (up to 20 attempts) to handle deferred DOM mounting (e.g. portals).
+ * - No DOM mutations occur when `enabled` is false.
+ *
+ * @param rootRef Root element that contains both the scroll area and the target.
+ * @param options Configuration.
+ * @param options.scrollAreaSelector CSS selector to locate the scrollable element.
+ * @param options.targetSelector CSS selector to locate the element that receives the class toggle.
+ * @param options.toggleClass CSS class(es) toggled on the target when the scroll area overflows. Accepts string or string[].
+ * @param options.enabled Whether the hook is active. Defaults to true.
+ */
+export declare const useOverflowBorder: (rootRef: ElementRefLike, { scrollAreaSelector, targetSelector, toggleClass, enabled }: OverflowBorderOptions) => void;
+export {};

package/src/index.d.ts

@@ -130,6 +130,7 @@ export { useKeyboardShortcut } from "./hooks/useKeyboardShortcut/useKeyboardShor
 export * from "./hooks/useMeasure";
 export * from "./hooks/useMergeRefs";
 export * from "./hooks/useModifierKey";
+export * from "./hooks/useOverflowBorder";
 export * from "./hooks/usePrevious";
 export * from "./hooks/useRelayPagination";
 export * from "./hooks/useResize";
@@ -141,3 +142,4 @@ export * from "./hooks/useTimeout";
 export * from "./hooks/useViewportBreakpoints";
 export * from "./hooks/useWatch";
 export * from "./hooks/useWindowActivity";
+export type { CloseReason, DismissOptions, OnBeforeCloseFn, OnCloseFn, OnOpenChangeFn, OnOpenFn, UseOverlayDismissibleProps, UseOverlayDismissibleReturn, } from "./overlay-dismissible/types";

package/src/overlay-dismissible/types.d.ts

@@ -0,0 +1,52 @@
+import type { RefObject } from "react";
+/**
+ * Reasons why an overlay (Modal/Sheet) closed.
+ * - `escape-key`: User pressed the ESC key
+ * - `outside-press`: User clicked outside / on overlay
+ * - `programmatic`: The close() function was called (e.g., from a close button)
+ * - `gesture`: User swiped down to close (Sheet only; Modal-in-sheet-mode)
+ */
+export type CloseReason = "escape-key" | "outside-press" | "programmatic" | "gesture";
+/**
+ * Config for which user gestures trigger close.
+ * Shared by Modal and Sheet.
+ */
+export type DismissOptions = {
+    /** Whether ESC key closes. @default true */
+    readonly escapeKey?: boolean;
+    /** Whether overlay/outside click closes. @default true */
+    readonly outsidePress?: boolean;
+    /** Whether swipe-down gesture closes (Sheet only; Modal-in-sheet-mode). @default true */
+    readonly gesture?: boolean;
+};
+/** Callback fired when the overlay closes. */
+export type OnCloseFn = (event?: Event, reason?: CloseReason) => void;
+/** Callback fired when the overlay opens. */
+export type OnOpenFn = (event?: Event) => void;
+/** Callback fired when the overlay open state changes. */
+export type OnOpenChangeFn = (open: boolean, event?: Event, reason?: CloseReason) => void;
+/** Callback fired BEFORE the overlay closes. Return false to prevent closing. */
+export type OnBeforeCloseFn = (event?: Event, reason?: CloseReason) => boolean | Promise<boolean>;
+/** Base props shared by useModal and useSheet. */
+export type UseOverlayDismissibleProps = {
+    readonly isOpen?: boolean;
+    readonly defaultOpen?: boolean;
+    readonly onClose?: OnCloseFn;
+    readonly onOpen?: OnOpenFn;
+    readonly onOpenChange?: OnOpenChangeFn;
+    readonly onBeforeClose?: OnBeforeCloseFn;
+    /** Config for which user gestures trigger close. Defaults: all true. */
+    readonly dismiss?: DismissOptions;
+};
+/** Base return value shared by useModal and useSheet. */
+export type UseOverlayDismissibleReturn = {
+    readonly isOpen: boolean;
+    readonly open: () => void;
+    readonly close: () => void;
+    readonly toggle: () => void;
+    readonly ref: RefObject<HTMLDivElement | null>;
+};
+/** Resolves DismissOptions with defaults (all true when omitted). */
+export declare const DEFAULT_DISMISS_OPTIONS: Required<DismissOptions>;
+/** Merges caller-supplied DismissOptions with defaults, returning a fully-resolved options object. */
+export declare function resolveDismissOptions(dismiss?: DismissOptions): Required<DismissOptions>;