chore: add optional parent boundary clamping for popover trigger positioning

src/internal/components/chart-popover/index.tsx

@@ -34,6 +34,9 @@ export interface ChartPopoverProps extends PopoverProps {
   trackKey?: string | number;
   minVisibleBlockSize?: number;
 
+  /** Optional parent element to clamp the popover trigger position within its bounds */
+  parentRef?: React.RefObject<HTMLElement>;
+
   /** Optional container element that prevents any clicks in there from dismissing the popover */
   container: Element | null;
 
@@ -74,6 +77,7 @@ function ChartPopover(
     trackKey,
     onDismiss,
     container,
+    parentRef,
     minVisibleBlockSize,
 
     onMouseEnter,
@@ -137,6 +141,7 @@ function ChartPopover(
         trackRef={trackRef}
         getTrack={getTrack}
         trackKey={trackKey}
+        parentRef={parentRef}
         minVisibleBlockSize={minVisibleBlockSize}
         arrow={position => (
           <div className={clsx(popoverStyles.arrow, popoverStyles[`arrow-position-${position}`])}>

src/popover/__tests__/popover-container.test.tsx

@@ -42,3 +42,17 @@ test.each([null, document.createElement('div')])('accepts track element with get
   const getTrack = usePopoverPositionSpy.mock.calls[0][0].getTrack;
   expect(getTrack()).toBe(track);
 });
+
+test.each([null, document.createElement('div')])('passes parentRef=%s to usePopoverPosition', parentRef => {
+  render(
+    <PopoverContainer
+      {...defaultProps}
+      parentRef={{ current: parentRef }}
+      trackRef={{ current: document.createElement('div') }}
+    >
+      content
+    </PopoverContainer>
+  );
+
+  expect(usePopoverPositionSpy.mock.calls[0][0].parentRef?.current).toBe(parentRef);
+});

src/popover/__tests__/positions.test.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 import {
   calculatePosition,
+  clampRectStart,
   intersectRectangles,
   isCenterOutside,
   PRIORITY_MAPPING,
@@ -280,3 +281,48 @@ describe('isCenterOutside', () => {
     ).toBe(false);
   });
 });
+
+describe('clampRectStart', () => {
+  const parent = { insetInlineStart: 100, insetBlockStart: 100, inlineSize: 400, blockSize: 300 };
+
+  test('clamps insetInlineStart to parent start when track is before parent', () => {
+    const track = { insetInlineStart: 50, insetBlockStart: 200, inlineSize: 20, blockSize: 20 };
+    expect(clampRectStart(track, parent).insetInlineStart).toBe(100);
+  });
+
+  test('clamps insetBlockStart to parent start when track is above parent', () => {
+    const track = { insetInlineStart: 200, insetBlockStart: 50, inlineSize: 20, blockSize: 20 };
+    expect(clampRectStart(track, parent).insetBlockStart).toBe(100);
+  });
+
+  test('clamps insetInlineStart to parent end when track is past parent', () => {
+    const track = { insetInlineStart: 600, insetBlockStart: 200, inlineSize: 20, blockSize: 20 };
+    expect(clampRectStart(track, parent).insetInlineStart).toBe(500);
+  });
+
+  test('clamps insetBlockStart to parent end when track is below parent', () => {
+    const track = { insetInlineStart: 200, insetBlockStart: 500, inlineSize: 20, blockSize: 20 };
+    expect(clampRectStart(track, parent).insetBlockStart).toBe(400);
+  });
+
+  test('does not clamp when track is within parent bounds', () => {
+    const track = { insetInlineStart: 200, insetBlockStart: 250, inlineSize: 20, blockSize: 20 };
+    const result = clampRectStart(track, parent);
+    expect(result.insetInlineStart).toBe(200);
+    expect(result.insetBlockStart).toBe(250);
+  });
+
+  test('clamps both axes simultaneously', () => {
+    const track = { insetInlineStart: 10, insetBlockStart: 500, inlineSize: 20, blockSize: 20 };
+    const result = clampRectStart(track, parent);
+    expect(result.insetInlineStart).toBe(100);
+    expect(result.insetBlockStart).toBe(400);
+  });
+
+  test('preserves inlineSize and blockSize of the track', () => {
+    const track = { insetInlineStart: 50, insetBlockStart: 50, inlineSize: 20, blockSize: 30 };
+    const result = clampRectStart(track, parent);
+    expect(result.inlineSize).toBe(20);
+    expect(result.blockSize).toBe(30);
+  });
+});

src/popover/container.tsx

@@ -27,6 +27,8 @@ interface PopoverContainerProps {
   */
   trackKey?: string | number;
   minVisibleBlockSize?: number;
+  /** Optional parent element to clamp popover position within its bounds */
+  parentRef?: React.RefObject<HTMLElement>;
   position: PopoverProps.Position;
   zIndex?: React.CSSProperties['zIndex'];
   arrow: (position: InternalPosition | null) => React.ReactNode;
@@ -52,6 +54,7 @@ export default function PopoverContainer({
   trackRef,
   getTrack: externalGetTrack,
   trackKey,
+  parentRef,
   minVisibleBlockSize,
   arrow,
   children,
@@ -90,6 +93,7 @@ export default function PopoverContainer({
       popoverRef,
       bodyRef,
       arrowRef,
+      parentRef,
       getTrack: getTrack.current,
       contentRef,
       allowScrollToFit,

src/popover/use-popover-position.ts

@@ -13,13 +13,20 @@ import {
   scrollRectangleIntoView,
 } from '../internal/utils/scrollable-containers';
 import { BoundingBox, InternalPosition, Offset, PopoverProps, Rect } from './interfaces';
-import { calculatePosition, getDimensions, getOffsetDimensions, isCenterOutside } from './utils/positions';
+import {
+  calculatePosition,
+  clampRectStart,
+  getDimensions,
+  getOffsetDimensions,
+  isCenterOutside,
+} from './utils/positions';
 
 export default function usePopoverPosition({
   popoverRef,
   bodyRef,
   arrowRef,
   getTrack,
+  parentRef,
   contentRef,
   allowScrollToFit,
   allowVerticalOverflow,
@@ -34,6 +41,7 @@ export default function usePopoverPosition({
   arrowRef: React.RefObject<HTMLDivElement | null>;
   getTrack: () => null | HTMLElement | SVGElement;
   contentRef: React.RefObject<HTMLDivElement | null>;
+  parentRef?: React.RefObject<HTMLElement>;
   allowScrollToFit?: boolean;
   allowVerticalOverflow?: boolean;
   preferredPosition: PopoverProps.Position;
@@ -88,7 +96,7 @@ export default function usePopoverPosition({
       // Get rects representing key elements
       // Use getComputedStyle for arrowRect to avoid modifications made by transform
       const viewportRect = getViewportRect(document.defaultView!);
-      const trackRect = getLogicalBoundingClientRect(track);
+      const trackRect = getClampedTrackRect(track, parentRef?.current);
       const arrowRect = getDimensions(arrow);
       const { containingBlock, boundary } = findUpUntilMultiple({
         startElement: popover,
@@ -183,7 +191,7 @@ export default function usePopoverPosition({
         if (!track) {
           return;
         }
-        const trackRect = getLogicalBoundingClientRect(track);
+        const trackRect = getClampedTrackRect(track, parentRef?.current);
 
         const newTrackOffset = toRelativePosition(
           trackRect,
@@ -209,13 +217,14 @@ export default function usePopoverPosition({
       bodyRef,
       contentRef,
       arrowRef,
+      parentRef,
       keepPosition,
       preferredPosition,
       renderWithPortal,
       allowVerticalOverflow,
+      minVisibleBlockSize,
       allowScrollToFit,
       hideOnOverscroll,
-      minVisibleBlockSize,
     ]
   );
   return { updatePositionHandler, popoverStyle, internalPosition, positionHandlerRef, isOverscrolling };
@@ -262,3 +271,11 @@ function isBoundary(element: HTMLElement) {
   const computedStyle = getComputedStyle(element);
   return !!computedStyle.clipPath && computedStyle.clipPath !== 'none';
 }
+
+function getClampedTrackRect(track: HTMLElement | SVGElement, parentRef?: HTMLElement | null) {
+  const trackRect = getLogicalBoundingClientRect(track);
+  if (!parentRef) {
+    return trackRect;
+  }
+  return clampRectStart(trackRect, getLogicalBoundingClientRect(parentRef));
+}

src/popover/utils/positions.ts

@@ -345,6 +345,14 @@ function isTopOrBottom(internalPosition: InternalPosition) {
   return ['top', 'bottom'].includes(internalPosition.split('-')[0]);
 }
 
+export function clampRectStart(rect: Rect, bounds: BoundingBox) {
+  const parentInlineEnd = bounds.insetInlineStart + bounds.inlineSize;
+  const parentBlockEnd = bounds.insetBlockStart + bounds.blockSize;
+  rect.insetInlineStart = Math.max(bounds.insetInlineStart, Math.min(rect.insetInlineStart, parentInlineEnd));
+  rect.insetBlockStart = Math.max(bounds.insetBlockStart, Math.min(rect.insetBlockStart, parentBlockEnd));
+  return rect;
+}
+
 export function isCenterOutside(child: Rect, parent: Rect) {
   const childCenter = child.insetBlockStart + child.blockSize / 2;
   const overflowsBlockStart = childCenter < parent.insetBlockStart;