feat(Dropdown): add disableAutoFlip & disableReferenceTrackingOnScroll as Props (#1135)

* feat(Dropdown): add disableAutoFlip prop to lock placement and prevent auto-flip

* Apply suggestion from @jmundhra-eightfold

* feat(Dropdown): disable reference-tracking on scrolling via props

* Apply suggestion from @jmundhra-eightfold

* feat(Dropdown): add tests

* feat(Dropdown): add cautionary comments

* feat(Dropdown): nits

* Apply suggestion from @jmundhra-eightfold

* Apply suggestion from @jmundhra-eightfold

* Apply suggestion from @jmundhra-eightfold

* Apply suggestion from @jmundhra-eightfold

Author: jmundhra-eightfold

src/components/Dropdown/Dropdown.test.tsx

@@ -974,4 +974,34 @@ describe('Dropdown', () => {
 
     expect(referenceElement.getAttribute('aria-haspopup')).toBe('dialog');
   });
+
+  test('Should open normally with disableAutoFlip set', async () => {
+    const { container, getByTestId } = render(
+      <Dropdown {...dropdownProps} disableAutoFlip>
+        <Button data-testid="dropdown-reference" text="Dropdown menu test" />
+      </Dropdown>
+    );
+    const referenceElement = getByTestId('dropdown-reference');
+    act(() => {
+      userEvent.click(referenceElement);
+    });
+    await waitFor(() => screen.getByText('User profile 1'));
+    expect(referenceElement.getAttribute('aria-expanded')).toBe('true');
+    expect(container.querySelector('.dropdown-wrapper')).toBeTruthy();
+  });
+
+  test('Should open normally with disableReferenceTrackingOnScroll set', async () => {
+    const { container, getByTestId } = render(
+      <Dropdown {...dropdownProps} disableReferenceTrackingOnScroll>
+        <Button data-testid="dropdown-reference" text="Dropdown menu test" />
+      </Dropdown>
+    );
+    const referenceElement = getByTestId('dropdown-reference');
+    act(() => {
+      userEvent.click(referenceElement);
+    });
+    await waitFor(() => screen.getByText('User profile 1'));
+    expect(referenceElement.getAttribute('aria-expanded')).toBe('true');
+    expect(container.querySelector('.dropdown-wrapper')).toBeTruthy();
+  });
 });

src/components/Dropdown/Dropdown.tsx

@@ -82,6 +82,8 @@ export const Dropdown: FC<DropdownProps> = React.memo(
         overlayTabIndex = -1,
         overlayProps,
         toggleDropdownOnShiftTab = false,
+        disableAutoFlip = false,
+        disableReferenceTrackingOnScroll = false,
       },
       ref: React.ForwardedRef<DropdownRef>
     ) => {
@@ -105,7 +107,11 @@ export const Dropdown: FC<DropdownProps> = React.memo(
       const { x, y, strategy, update, refs, context } = useFloating({
         placement,
         strategy: positionStrategy,
-        middleware: [fOffset(offset), flip(), shift()],
+        middleware: [
+          fOffset(offset),
+          ...(disableAutoFlip ? [] : [flip()]),
+          shift(),
+        ],
       });
 
       const intervalRef: React.MutableRefObject<NodeJS.Timer> =
@@ -240,17 +246,34 @@ export const Dropdown: FC<DropdownProps> = React.memo(
         return autoUpdate(
           refs.reference.current,
           refs.floating.current,
-          update
+          update,
+          { ancestorScroll: !disableReferenceTrackingOnScroll }
         );
-      }, [refs.reference, refs.floating, update]);
+      }, [
+        disableReferenceTrackingOnScroll,
+        refs.reference,
+        refs.floating,
+        update,
+      ]);
 
       // Add a new useEffect to update position when overlay content changes
       useEffect(() => {
-        if (mergedVisible && refs.floating.current) {
-          // Update the position when the overlay content changes
-          update();
+        if (
+          disableReferenceTrackingOnScroll ||
+          !mergedVisible ||
+          !refs.floating.current
+        ) {
+          return;
         }
-      }, [overlay, mergedVisible, update, refs.floating]);
+        // Update the position when the overlay content changes
+        update();
+      }, [
+        disableReferenceTrackingOnScroll,
+        overlay,
+        mergedVisible,
+        update,
+        refs.floating,
+      ]);
 
       const dropdownClasses: string = mergeClasses([
         dropdownClassNames,

src/components/Dropdown/Dropdown.types.ts

@@ -192,6 +192,31 @@ export interface DropdownProps {
    * The props of the overlay
    */
   overlayProps?: React.HTMLAttributes<HTMLDivElement>;
+
+  /**
+   * When true, the dropdown will not auto-flip to the opposite side when the
+   * preferred placement overflows. Use to keep a fixed placement (e.g. anchored
+   * below a trigger toward a scrollable region).
+   *
+   * CAUTION - this suppresses dropdown's auto-flip if the space on
+   * the configured side is less than the dropdown-overlay height.
+   * If the side fixed doesn't have a scrollable region, then the dropdown overlay is stuck.
+   * @default false
+   */
+  disableAutoFlip?: boolean;
+
+  /**
+   * When true, the dropdown does not reposition when an ancestor of the reference
+   * or floating element scrolls, or when the overlay content changes size while
+   * open — it stays where it opened. Element resize and layout-shift tracking via
+   * autoUpdate are unaffected. Use alongside disableAutoFlip when the reference is
+   * inside a container that scrolls out from under a fixed-placement dropdown.
+   *
+   * CAUTION: this also suppresses the reposition that would otherwise run when the
+   * overlay's own rendered content changes size while open.
+   * @default false
+   */
+  disableReferenceTrackingOnScroll?: boolean;
 }
 
 export type DropdownRef = {