Allow to customize initial Popover placement

Author: acelaya

src/components/feedback/Popover.tsx

@@ -41,6 +41,7 @@ function usePopoverPositioning(
   popoverOpen: boolean,
   asNativePopover: boolean,
   alignToRight: boolean,
+  placement: 'above' | 'below',
 ) {
   const adjustPopoverPositioning = useCallback(() => {
     const popoverEl = popoverRef.current!;
@@ -71,11 +72,15 @@ function usePopoverPositioning(
     const { height: popoverHeight, width: popoverWidth } =
       popoverEl.getBoundingClientRect();
 
-    // The popover should render above only if there's not enough space below to
-    // fit it and there's more absolute space above than below
+    // The popover should render in indicated placement unless there's not
+    // enough space to fit it there, but there is in the opposite one.
     const shouldBeAbove =
-      anchorElDistanceToBottom < popoverHeight &&
-      anchorElDistanceToTop > anchorElDistanceToBottom;
+      (placement === 'above' &&
+        (anchorElDistanceToTop > popoverHeight ||
+          anchorElDistanceToBottom < anchorElDistanceToTop)) ||
+      (placement === 'below' &&
+        anchorElDistanceToBottom < popoverHeight &&
+        anchorElDistanceToTop > anchorElDistanceToBottom);
 
     if (!asNativePopover) {
       // Set styles for non-popover mode
@@ -126,7 +131,7 @@ function usePopoverPositioning(
         : `calc(${absBodyTop + anchorElDistanceToTop + anchorElHeight}px + ${POPOVER_ANCHOR_EL_GAP})`,
       left: `${Math.max(POPOVER_VIEWPORT_HORIZONTAL_GAP, left)}px`,
     });
-  }, [asNativePopover, anchorElementRef, popoverRef, alignToRight]);
+  }, [asNativePopover, anchorElementRef, popoverRef, alignToRight, placement]);
 
   useLayoutEffect(() => {
     if (!popoverOpen) {
@@ -250,6 +255,16 @@ export type PopoverProps = {
    */
   align?: 'right' | 'left';
 
+  /**
+   * Where to position the popover if there's available space: above the anchor
+   * or below it.
+   * Defaults to 'below'.
+   *
+   * If there's no space to display the popover in selected placement, an
+   * alternative placement will be used to keep it inside the viewport.
+   */
+  placement?: 'above' | 'below';
+
   /**
    * Determines if focus should be restored when the popover is closed.
    * Defaults to true.
@@ -330,6 +345,7 @@ export default function Popover({
   open,
   onClose,
   align = 'left',
+  placement = 'below',
   classes,
   variant = 'panel',
   onScroll,
@@ -345,6 +361,7 @@ export default function Popover({
     open,
     asNativePopover,
     align === 'right',
+    placement,
   );
   useOnClose(popoverRef, anchorElementRef, onClose, open, asNativePopover);
   useRestoreFocusOnClose({

src/components/feedback/test/Popover-test.js

@@ -188,17 +188,33 @@ describe('Popover', () => {
       asNativePopover: false,
       shouldBeAbove: true,
     },
-  ].forEach(({ containerPaddingTop, asNativePopover, shouldBeAbove }) => {
-    it('positions popover above or below based on available space', () => {
-      const wrapper = createComponent(
-        { asNativePopover },
-        { paddingTop: containerPaddingTop },
-      );
-      togglePopover(wrapper);
 
-      assert.equal(popoverAppearedAbove(wrapper), shouldBeAbove);
-    });
-  });
+    // placement: 'above'
+    {
+      containerPaddingTop: 1000,
+      asNativePopover: true,
+      shouldBeAbove: true,
+      placement: 'above',
+    },
+    {
+      containerPaddingTop: 0,
+      asNativePopover: true,
+      shouldBeAbove: false,
+      placement: 'above',
+    },
+  ].forEach(
+    ({ containerPaddingTop, asNativePopover, shouldBeAbove, placement }) => {
+      it('positions popover above or below based on available space and placement', () => {
+        const wrapper = createComponent(
+          { asNativePopover, placement },
+          { paddingTop: containerPaddingTop },
+        );
+        togglePopover(wrapper);
+
+        assert.equal(popoverAppearedAbove(wrapper), shouldBeAbove);
+      });
+    },
+  );
 
   [true, false].forEach(asNativePopover => {
     it('repositions popover if it is resized after being open', async () => {

src/pattern-library/components/patterns/feedback/PopoverPage.tsx

@@ -174,6 +174,25 @@ export default function PopoverPage() {
               </Library.InfoItem>
             </Library.Info>
           </Library.SectionL3>
+          <Library.SectionL3 title="placement">
+            <Library.Info>
+              <Library.InfoItem label="description">
+                Whether the <code>Popover</code> should show above or below the
+                anchor element.
+              </Library.InfoItem>
+              <Library.InfoItem label="type">
+                <code>{"'above' | 'below'"}</code>
+              </Library.InfoItem>
+              <Library.InfoItem label="default">
+                <code>{"'below'"}</code>
+              </Library.InfoItem>
+            </Library.Info>
+            <Library.Demo
+              title="Popover placement"
+              exampleFile="popover-placement"
+              withSource
+            />
+          </Library.SectionL3>
           <Library.SectionL3 title="restoreFocusOnClose">
             <Library.Info>
               <Library.InfoItem label="description">

src/pattern-library/examples/popover-placement.tsx

@@ -0,0 +1,44 @@
+import { useRef, useState } from 'preact/hooks';
+
+import { Popover } from '../../components/feedback';
+import { Button } from '../../components/input';
+
+function ButtonWithPopover({ placement }: { placement: 'above' | 'below' }) {
+  const [open, setOpen] = useState(false);
+  const buttonRef = useRef<HTMLButtonElement | null>(null);
+
+  return (
+    <div>
+      <Button
+        variant="primary"
+        elementRef={buttonRef}
+        onClick={() => setOpen(prev => !prev)}
+      >
+        {open ? 'Close' : 'Open'} {placement}
+      </Button>
+      <Popover
+        open={open}
+        onClose={() => setOpen(false)}
+        anchorElementRef={buttonRef}
+        placement={placement}
+      >
+        <div className="p-2 flex flex-col gap-y-2 w-64">
+          <p>This popover is displayed {placement} the button.</p>
+          <p>
+            It will be displayed in the opposite direction if there is no room
+            for it {placement}.
+          </p>
+        </div>
+      </Popover>
+    </div>
+  );
+}
+
+export default function App() {
+  return (
+    <div className="relative flex justify-center gap-x-3">
+      <ButtonWithPopover placement="above" />
+      <ButtonWithPopover placement="below" />
+    </div>
+  );
+}