@astryxdesign/core 0.0.0-bootstrap.0 → 0.1.0-canary.08d4cf4

package/dist/hooks/useMediaQuery.d.ts

@@ -0,0 +1,16 @@
+/**
+ * SSR-safe media query hook.
+ * Returns whether the given media query matches.
+ *
+ * @param query - CSS media query string
+ * @param serverDefault - Value to return during SSR. Pass a server-side hint
+ *   (e.g. derived from User-Agent or client hints) to avoid a layout flash.
+ *
+ * @example
+ * ```
+ * const isMobile = useMediaQuery('(max-width: 768px)');
+ * const isMobile = useMediaQuery('(max-width: 768px)', defaultIsMobile);
+ * ```
+ */
+export declare function useMediaQuery(query: string, serverDefault?: boolean): boolean;
+//# sourceMappingURL=useMediaQuery.d.ts.map

package/dist/hooks/useMediaQuery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useMediaQuery.d.ts","sourceRoot":"","sources":["../../src/hooks/useMediaQuery.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,UAAQ,GAAG,OAAO,CAiB3E"}

package/dist/hooks/useMediaQuery.js

@@ -0,0 +1,45 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useMediaQuery.ts
+ * @input Uses React useSyncExternalStore, useCallback
+ * @output Exports useMediaQuery hook for responsive breakpoint detection
+ * @position Core hook; used by consumers for responsive patterns
+ *
+ * SSR-safe media query hook that subscribes to window.matchMedia changes
+ * via useSyncExternalStore — the canonical React pattern for external
+ * browser state.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts
+ */
+import { useCallback, useSyncExternalStore } from 'react';
+
+/**
+ * SSR-safe media query hook.
+ * Returns whether the given media query matches.
+ *
+ * @param query - CSS media query string
+ * @param serverDefault - Value to return during SSR. Pass a server-side hint
+ *   (e.g. derived from User-Agent or client hints) to avoid a layout flash.
+ *
+ * @example
+ * ```
+ * const isMobile = useMediaQuery('(max-width: 768px)');
+ * const isMobile = useMediaQuery('(max-width: 768px)', defaultIsMobile);
+ * ```
+ */
+export function useMediaQuery(query, serverDefault = false) {
+  const subscribe = useCallback(onStoreChange => {
+    const mql = window.matchMedia(query);
+    mql.addEventListener('change', onStoreChange);
+    return () => mql.removeEventListener('change', onStoreChange);
+  }, [query]);
+  const getSnapshot = useCallback(() => {
+    return window.matchMedia(query).matches;
+  }, [query]);
+  const getServerSnapshot = useCallback(() => serverDefault, [serverDefault]);
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}

package/dist/hooks/useMenuHover.d.ts

@@ -0,0 +1,28 @@
+interface UseMenuHoverOptions {
+    show: (options?: {
+        skipAutoFocus?: boolean;
+    }) => void;
+    hide: () => void;
+    isOpen: boolean;
+    isEnabled: boolean;
+    showDelay?: number;
+    hideDelay?: number;
+}
+interface UseMenuHoverReturn<T extends HTMLElement = HTMLElement> {
+    triggerProps: {
+        onClick: () => void;
+        onMouseEnter: () => void;
+        onMouseLeave: () => void;
+    };
+    contentProps: {
+        onMouseEnter: () => void;
+        onMouseLeave: () => void;
+        onKeyDown: (e: React.KeyboardEvent) => void;
+    };
+    menuRef: React.RefObject<T | null>;
+    focusFirst: () => void;
+    setTriggerEl: (el: HTMLElement | null) => void;
+}
+export declare function useMenuHover<T extends HTMLElement = HTMLElement>(options: UseMenuHoverOptions): UseMenuHoverReturn<T>;
+export {};
+//# sourceMappingURL=useMenuHover.d.ts.map

package/dist/hooks/useMenuHover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useMenuHover.d.ts","sourceRoot":"","sources":["../../src/hooks/useMenuHover.ts"],"names":[],"mappings":"AA4BA,UAAU,mBAAmB;IAC3B,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE;QAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAC,KAAK,IAAI,CAAC;IACpD,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,UAAU,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IAC9D,YAAY,EAAE;QACZ,OAAO,EAAE,MAAM,IAAI,CAAC;QACpB,YAAY,EAAE,MAAM,IAAI,CAAC;QACzB,YAAY,EAAE,MAAM,IAAI,CAAC;KAC1B,CAAC;IACF,YAAY,EAAE;QACZ,YAAY,EAAE,MAAM,IAAI,CAAC;QACzB,YAAY,EAAE,MAAM,IAAI,CAAC;QACzB,SAAS,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAC;KAC7C,CAAC;IACF,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACnC,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,YAAY,EAAE,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;CAChD;AAED,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,CAAC,CAAC,CAAC,CA2IvB"}

package/dist/hooks/useMenuHover.js

@@ -0,0 +1,165 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useMenuHover.ts
+ * @input Uses React hooks, useListFocus
+ * @output Exports useMenuHover hook
+ * @position Internal hook; used by nav heading components and TopNavMenu
+ *
+ * Hover as a progressive enhancement on top of standard popover behavior:
+ *
+ * 1. Default popover: click toggles, Escape closes, outside-click closes,
+ *    arrow keys navigate menu items.
+ *
+ * 2. Hover add-on:
+ *    - mouseenter activates "hover mode" and opens after delay
+ *    - While in hover mode, mouseleave closes after delay
+ *    - Any close (click, Escape, outside-click) resets hover mode
+ *    - Click-to-close additionally skips the next mouseenter
+ *
+ * Only uses mouseenter/mouseleave (not mouseover).
+ */
+import { useCallback, useEffect, useRef } from 'react';
+import { useListFocus } from "./useListFocus.js";
+import { useMediaQuery } from "./useMediaQuery.js";
+export function useMenuHover(options) {
+  const {
+    show,
+    hide,
+    isOpen,
+    isEnabled,
+    showDelay = 150,
+    hideDelay = 200
+  } = options;
+  const hasHover = useMediaQuery('(hover: hover)');
+  const showTimerRef = useRef(null);
+  const hideTimerRef = useRef(null);
+  const triggerElRef = useRef(null);
+  // Whether the menu was opened/interacted via hover (enables mouseleave-to-close)
+  const hoverModeRef = useRef(false);
+  // One-shot: skip the next mouseenter after click-to-close
+  const skipNextEnterRef = useRef(false);
+  const prevIsOpenRef = useRef(isOpen);
+
+  // When popover closes (any reason), reset hover mode
+  if (prevIsOpenRef.current && !isOpen) {
+    hoverModeRef.current = false;
+  }
+  prevIsOpenRef.current = isOpen;
+  const clearTimeouts = useCallback(() => {
+    if (showTimerRef.current) {
+      clearTimeout(showTimerRef.current);
+      showTimerRef.current = null;
+    }
+    if (hideTimerRef.current) {
+      clearTimeout(hideTimerRef.current);
+      hideTimerRef.current = null;
+    }
+  }, []);
+  const {
+    listRef: menuRef,
+    handleKeyDown: handleListKeyDown,
+    focusFirst
+  } = useListFocus({
+    onEscape: () => {
+      clearTimeouts();
+      hide();
+    }
+  });
+  useEffect(() => {
+    return () => clearTimeouts();
+  }, [clearTimeouts]);
+
+  // Click: always toggle
+  const handleClick = useCallback(() => {
+    clearTimeouts();
+    if (isOpen) {
+      skipNextEnterRef.current = true;
+      hide();
+    } else {
+      skipNextEnterRef.current = false;
+      show();
+      requestAnimationFrame(() => focusFirst());
+    }
+  }, [isOpen, clearTimeouts, show, hide, focusFirst]);
+
+  // Hover: mouseenter activates hover mode and opens
+  const handleMouseEnter = useCallback(() => {
+    if (!hasHover) {
+      return;
+    }
+    if (skipNextEnterRef.current) {
+      skipNextEnterRef.current = false;
+      return;
+    }
+    hoverModeRef.current = true;
+    clearTimeouts();
+    if (showDelay > 0) {
+      showTimerRef.current = setTimeout(() => {
+        show({
+          skipAutoFocus: true
+        });
+      }, showDelay);
+    } else {
+      show({
+        skipAutoFocus: true
+      });
+    }
+  }, [hasHover, clearTimeouts, show, showDelay]);
+
+  // Hover: mouseleave only closes if in hover mode
+  const handleMouseLeave = useCallback(() => {
+    if (!hoverModeRef.current) {
+      return;
+    }
+    clearTimeouts();
+    hideTimerRef.current = setTimeout(() => {
+      hide();
+    }, hideDelay);
+  }, [clearTimeouts, hide, hideDelay]);
+
+  // Content: mouseenter cancels pending hide
+  const handleContentMouseEnter = useCallback(() => {
+    clearTimeouts();
+  }, [clearTimeouts]);
+  const setTriggerRef = useCallback(el => {
+    triggerElRef.current = el;
+  }, []);
+  const noop = useCallback(() => {}, []);
+  const noopRef = useCallback(_el => {}, []);
+  const noopKeyDown = useCallback(_e => {}, []);
+  if (!isEnabled) {
+    return {
+      triggerProps: {
+        onClick: noop,
+        onMouseEnter: noop,
+        onMouseLeave: noop
+      },
+      contentProps: {
+        onMouseEnter: noop,
+        onMouseLeave: noop,
+        onKeyDown: noopKeyDown
+      },
+      menuRef,
+      focusFirst,
+      setTriggerEl: noopRef
+    };
+  }
+  return {
+    triggerProps: {
+      onClick: handleClick,
+      onMouseEnter: handleMouseEnter,
+      onMouseLeave: handleMouseLeave
+    },
+    contentProps: {
+      onMouseEnter: handleContentMouseEnter,
+      onMouseLeave: handleMouseLeave,
+      onKeyDown: handleListKeyDown
+    },
+    menuRef,
+    focusFirst,
+    setTriggerEl: setTriggerRef
+  };
+}

package/dist/hooks/useOverflow.d.ts

@@ -0,0 +1,58 @@
+export interface UseOverflowOptions {
+    /**
+     * Gap between items in pixels. Used in width calculations.
+     * @default 0
+     */
+    gap?: number;
+    /**
+     * Minimum number of items to always show, even if they don't fit.
+     * @default 0
+     */
+    minVisibleItems?: number;
+    /**
+     * Which end to collapse items from.
+     * @default 'end'
+     */
+    collapseFrom?: 'start' | 'end';
+    /**
+     * Which element to observe for overflow calculations.
+     * - `'observeSelf'`: uses the container's own width (default)
+     * - `'observeParent'`: observes the container's parent element for
+     *   resize and uses the parent's content width. This allows the
+     *   visible container to remain content-sized while still detecting
+     *   available space for grow-back. Siblings that don't fit alongside
+     *   the items can wrap and be clipped by the parent's overflow.
+     * @default 'observeSelf'
+     */
+    behavior?: 'observeParent' | 'observeSelf';
+}
+export interface UseOverflowReturn {
+    /** Ref to attach to the visible container element */
+    containerRef: React.RefCallback<HTMLElement>;
+    /** Ref to attach to the hidden measurement container */
+    measureRef: React.RefCallback<HTMLElement>;
+    /** Number of items that fit in the visible container */
+    visibleCount: number;
+    /** Whether any items are overflowing */
+    hasOverflow: boolean;
+}
+/**
+ * Hook for managing horizontal overflow of a list of items.
+ *
+ * Renders all items into a hidden measurement container, then calculates
+ * how many fit in the visible container's width. Uses ResizeObserver to
+ * recalculate when the container resizes.
+ *
+ * The measurement container should contain all items followed by the
+ * overflow indicator element (if any). The indicator is identified by
+ * a `data-overflow-indicator` attribute.
+ *
+ * @example
+ * ```
+ * const { containerRef, measureRef, visibleCount, hasOverflow } = useOverflow(5, {
+ *   gap: 8,
+ * });
+ * ```
+ */
+export declare function useOverflow(itemCount: number, options?: UseOverflowOptions): UseOverflowReturn;
+//# sourceMappingURL=useOverflow.d.ts.map

package/dist/hooks/useOverflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOverflow.d.ts","sourceRoot":"","sources":["../../src/hooks/useOverflow.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;IAE/B;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,eAAe,GAAG,aAAa,CAAC;CAC5C;AAED,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,YAAY,EAAE,KAAK,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IAC7C,wDAAwD;IACxD,UAAU,EAAE,KAAK,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IAC3C,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CAsInB"}

package/dist/hooks/useOverflow.js

@@ -0,0 +1,137 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useOverflow.ts
+ * @input Uses React useState, useCallback, useRef; useIsomorphicLayoutEffect
+ * @output Exports useOverflow hook for measuring and managing horizontal overflow
+ * @position Core hook; used by OverflowList and consumers for overflow patterns
+ *
+ * Measures children rendered in a hidden container to determine how many fit
+ * in the available width, without flickering. Uses ResizeObserver to react
+ * to container size changes.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts
+ */
+import { useState, useCallback, useRef } from 'react';
+import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
+import { observeResize, unobserveResize } from "../utils/sharedResizeObserver.js";
+/**
+ * Hook for managing horizontal overflow of a list of items.
+ *
+ * Renders all items into a hidden measurement container, then calculates
+ * how many fit in the visible container's width. Uses ResizeObserver to
+ * recalculate when the container resizes.
+ *
+ * The measurement container should contain all items followed by the
+ * overflow indicator element (if any). The indicator is identified by
+ * a `data-overflow-indicator` attribute.
+ *
+ * @example
+ * ```
+ * const { containerRef, measureRef, visibleCount, hasOverflow } = useOverflow(5, {
+ *   gap: 8,
+ * });
+ * ```
+ */
+export function useOverflow(itemCount, options = {}) {
+  const {
+    gap = 0,
+    minVisibleItems = 0,
+    collapseFrom = 'end',
+    behavior = 'observeSelf'
+  } = options;
+  const observeParent = behavior === 'observeParent';
+  const [visibleCount, setVisibleCount] = useState(itemCount);
+  const containerElRef = useRef(null);
+  const measureElRef = useRef(null);
+  const observedElRef = useRef(null);
+  const calculate = useCallback(() => {
+    const container = containerElRef.current;
+    const measure = measureElRef.current;
+    if (!container || !measure) {
+      return;
+    }
+    let availableWidth;
+    if (observeParent && container.parentElement) {
+      const parent = container.parentElement;
+      const parentStyle = getComputedStyle(parent);
+      availableWidth = parent.clientWidth - parseFloat(parentStyle.paddingLeft) - parseFloat(parentStyle.paddingRight);
+    } else {
+      availableWidth = container.offsetWidth;
+    }
+    const allChildren = Array.from(measure.children);
+
+    // The measurement container holds itemCount items, plus optionally
+    // an overflow indicator as the last child.
+    const hasIndicator = allChildren.length > itemCount;
+    const children = hasIndicator ? allChildren.slice(0, itemCount) : allChildren;
+    const indicatorWidth = hasIndicator ? allChildren[allChildren.length - 1].offsetWidth : 0;
+    if (children.length === 0) {
+      // eslint-disable-next-line @eslint-react/set-state-in-effect -- overflow count is derived from measured DOM widths
+      setVisibleCount(0);
+      return;
+    }
+
+    // Collect widths of all children
+    const widths = children.map(child => child.offsetWidth);
+
+    // Determine how many items fit
+    let totalWidth = 0;
+    let count = 0;
+    const orderedWidths = collapseFrom === 'end' ? widths : [...widths].reverse();
+    for (let i = 0; i < orderedWidths.length; i++) {
+      const itemWidth = orderedWidths[i];
+      const gapWidth = i > 0 ? gap : 0;
+      const candidateWidth = totalWidth + itemWidth + gapWidth;
+
+      // If this isn't the last item, we need to reserve space for the indicator
+      const isLastItem = i === orderedWidths.length - 1;
+      const reservedWidth = isLastItem ? 0 : indicatorWidth + (count > 0 || indicatorWidth > 0 ? gap : 0);
+      if (candidateWidth + reservedWidth > availableWidth && count >= minVisibleItems) {
+        break;
+      }
+      totalWidth = candidateWidth;
+      count++;
+    }
+
+    // eslint-disable-next-line @eslint-react/set-state-in-effect -- overflow count is derived from measured DOM widths
+    setVisibleCount(Math.max(Math.min(count, itemCount), minVisibleItems));
+  }, [itemCount, gap, minVisibleItems, collapseFrom, observeParent]);
+  const containerRef = useCallback(el => {
+    containerElRef.current = el;
+
+    // Clean up previous observation
+    if (observedElRef.current) {
+      unobserveResize(observedElRef.current);
+      observedElRef.current = null;
+    }
+    if (el) {
+      const target = observeParent && el.parentElement ? el.parentElement : el;
+      observeResize(target, () => {
+        calculate();
+      });
+      observedElRef.current = target;
+    }
+  }, [calculate, observeParent]);
+  const measureRef = useCallback(el => {
+    measureElRef.current = el;
+    if (el) {
+      calculate();
+    }
+  }, [calculate]);
+
+  // Recalculate when itemCount changes
+  useIsomorphicLayoutEffect(() => {
+    calculate();
+  }, [calculate]);
+  const hasOverflow = visibleCount < itemCount;
+  return {
+    containerRef,
+    measureRef,
+    visibleCount,
+    hasOverflow
+  };
+}

package/dist/hooks/useScrollLock.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Locks body scroll when `isLocked` is true.
+ *
+ * Pins the body with `position: fixed` to prevent background scrolling,
+ * which is necessary for iOS Safari where `overscroll-behavior: contain`
+ * does not prevent body scroll behind modals. Restores scroll position
+ * on unlock.
+ *
+ * @example
+ * ```
+ * useScrollLock(isOpen);
+ * ```
+ */
+export declare function useScrollLock(isLocked: boolean): void;
+//# sourceMappingURL=useScrollLock.d.ts.map

package/dist/hooks/useScrollLock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScrollLock.d.ts","sourceRoot":"","sources":["../../src/hooks/useScrollLock.ts"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CA8BrD"}

package/dist/hooks/useScrollLock.js

@@ -0,0 +1,61 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useScrollLock.ts
+ * @input Uses React useEffect
+ * @output Exports useScrollLock hook for locking body scroll
+ * @position Core hook; used by Dialog to prevent background scrolling
+ *
+ * Locks body scroll when active by pinning the body with position:fixed.
+ * This is needed because overscroll-behavior:contain doesn't work on iOS Safari.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts
+ */
+import { useEffect } from 'react';
+
+/**
+ * Locks body scroll when `isLocked` is true.
+ *
+ * Pins the body with `position: fixed` to prevent background scrolling,
+ * which is necessary for iOS Safari where `overscroll-behavior: contain`
+ * does not prevent body scroll behind modals. Restores scroll position
+ * on unlock.
+ *
+ * @example
+ * ```
+ * useScrollLock(isOpen);
+ * ```
+ */
+export function useScrollLock(isLocked) {
+  useEffect(() => {
+    if (!isLocked) {
+      return;
+    }
+    const scrollX = window.scrollX;
+    const scrollY = window.scrollY;
+    const {
+      body
+    } = document;
+    const prevOverflow = body.style.overflow;
+    const prevPosition = body.style.position;
+    const prevTop = body.style.top;
+    const prevLeft = body.style.left;
+    const prevRight = body.style.right;
+    body.style.overflow = 'hidden';
+    body.style.position = 'fixed';
+    body.style.top = `-${scrollY}px`;
+    body.style.left = '0';
+    body.style.right = '0';
+    return () => {
+      body.style.overflow = prevOverflow;
+      body.style.position = prevPosition;
+      body.style.top = prevTop;
+      body.style.left = prevLeft;
+      body.style.right = prevRight;
+      window.scrollTo(scrollX, scrollY);
+    };
+  }, [isLocked]);
+}

package/dist/hooks/useScrollOverflow.d.ts

@@ -0,0 +1,30 @@
+export interface ScrollOverflowState {
+    /** Content overflows the start (left in LTR, right in RTL) */
+    overflowStart: boolean;
+    /** Content overflows the end (right in LTR, left in RTL) */
+    overflowEnd: boolean;
+    /** Whether the container has any overflow at all */
+    hasOverflow: boolean;
+}
+/**
+ * Tracks scroll overflow state for a horizontally scrollable container.
+ *
+ * Returns a ref callback to attach to the scroll container and a state
+ * object that updates as the user scrolls or the container resizes.
+ *
+ * @example
+ * ```
+ * const { scrollRef, overflowStart, overflowEnd } = useScrollOverflow();
+ * <div ref={scrollRef} style={{ overflowX: 'auto' }}>...</div>
+ * ```
+ */
+export declare function useScrollOverflow(): {
+    /** Content overflows the start (left in LTR, right in RTL) */
+    overflowStart: boolean;
+    /** Content overflows the end (right in LTR, left in RTL) */
+    overflowEnd: boolean;
+    /** Whether the container has any overflow at all */
+    hasOverflow: boolean;
+    scrollRef: (el: HTMLElement | null) => void;
+};
+//# sourceMappingURL=useScrollOverflow.d.ts.map

package/dist/hooks/useScrollOverflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScrollOverflow.d.ts","sourceRoot":"","sources":["../../src/hooks/useScrollOverflow.ts"],"names":[],"mappings":"AAoBA,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,aAAa,EAAE,OAAO,CAAC;IACvB,4DAA4D;IAC5D,WAAW,EAAE,OAAO,CAAC;IACrB,oDAAoD;IACpD,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB;IApB/B,8DAA8D;mBAC/C,OAAO;IACtB,4DAA4D;iBAC/C,OAAO;IACpB,oDAAoD;iBACvC,OAAO;oBAmDb,WAAW,GAAG,IAAI;EA6B1B"}

package/dist/hooks/useScrollOverflow.js

@@ -0,0 +1,89 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useScrollOverflow.ts
+ * @input Uses React useRef, useState, useCallback, useEffect
+ * @output Exports useScrollOverflow hook for tracking scroll position edges
+ * @position Core hook; used by Carousel for fade-edge and button state
+ *
+ * Observes a scroll container and reports whether content overflows at the
+ * start, end, or both edges. Updates on scroll and resize.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts
+ */
+import { useState, useCallback, useEffect, useRef } from 'react';
+import { observeResize, unobserveResize } from "../utils/sharedResizeObserver.js";
+/**
+ * Tracks scroll overflow state for a horizontally scrollable container.
+ *
+ * Returns a ref callback to attach to the scroll container and a state
+ * object that updates as the user scrolls or the container resizes.
+ *
+ * @example
+ * ```
+ * const { scrollRef, overflowStart, overflowEnd } = useScrollOverflow();
+ * <div ref={scrollRef} style={{ overflowX: 'auto' }}>...</div>
+ * ```
+ */
+export function useScrollOverflow() {
+  const elRef = useRef(null);
+  const [state, setState] = useState({
+    overflowStart: false,
+    overflowEnd: false,
+    hasOverflow: false
+  });
+  const measure = useCallback(() => {
+    const el = elRef.current;
+    if (!el) {
+      return;
+    }
+    const tolerance = 1;
+    const {
+      scrollLeft,
+      scrollWidth,
+      clientWidth
+    } = el;
+    const maxScroll = scrollWidth - clientWidth;
+    const overflowStart = Math.abs(scrollLeft) > tolerance;
+    const overflowEnd = Math.abs(scrollLeft) < maxScroll - tolerance;
+    const hasOverflow = scrollWidth > clientWidth + tolerance;
+    setState(prev => {
+      if (prev.overflowStart === overflowStart && prev.overflowEnd === overflowEnd && prev.hasOverflow === hasOverflow) {
+        return prev;
+      }
+      return {
+        overflowStart,
+        overflowEnd,
+        hasOverflow
+      };
+    });
+  }, []);
+  const scrollRef = useCallback(el => {
+    if (elRef.current) {
+      unobserveResize(elRef.current);
+      elRef.current.removeEventListener('scroll', measure);
+    }
+    elRef.current = el;
+    if (el) {
+      el.addEventListener('scroll', measure, {
+        passive: true
+      });
+      observeResize(el, measure);
+    }
+  }, [measure]);
+  useEffect(() => {
+    return () => {
+      if (elRef.current) {
+        unobserveResize(elRef.current);
+        elRef.current.removeEventListener('scroll', measure);
+      }
+    };
+  }, [measure]);
+  return {
+    scrollRef,
+    ...state
+  };
+}