feat: accept an explicit vertical popover offset

src/popover/animations/ios.enter.ts

@@ -8,6 +8,8 @@ const POPOVER_IOS_BODY_PADDING = 5;
 
 /**
  * iOS Popover Enter Animation
+ * `opts.verticalOffset` overrides the non-replacing surface offset in CSS pixels.
+ * Omit it to use the theme's default body margin.
  */
 // TODO(FW-2832): types
 export const iosEnterAnimation = (baseEl: HTMLElement, opts: any = {}): Animation => {
@@ -102,6 +104,7 @@ export const iosEnterAnimation = (baseEl: HTMLElement, opts: any = {}): Animatio
     results.referenceCoordinates,
     referenceSizeEl?.getBoundingClientRect(),
     isReplace,
+    opts.verticalOffset,
   );
   // A replacing surface grows inward from the button's edge, not its center.
   const preferredLeft =

src/popover/utils.spec.ts

@@ -3,6 +3,27 @@ import { describe, expect, it } from 'vitest';
 import { calculateWindowAdjustment, getIndexOfItem, getNextItem, getPopoverPosition, getPrevItem } from './utils.js';
 
 describe('popover utilities', () => {
+  it.each([undefined, 0, 3, -2])('uses verticalOffset=%s without fixing the caller to the default margin', (offset) => {
+    const position = calculateWindowAdjustment(
+      'right',
+      120,
+      100,
+      5,
+      440,
+      636,
+      200,
+      52,
+      8,
+      'right',
+      'center',
+      undefined,
+      undefined,
+      false,
+      offset,
+    );
+    expect(position.top).toBe(120 + (offset ?? 8));
+  });
+
   it('navigates only relative to ion-item elements', () => {
     const items = [document.createElement('ion-item'), document.createElement('ion-item')] as HTMLIonItemElement[];
 

src/popover/utils.ts

@@ -612,11 +612,12 @@ export const calculateWindowAdjustment = (
   triggerCoordinates?: ReferenceCoordinates,
   eventElementRect?: DOMRect,
   isReplace: boolean = false,
+  verticalOffset: number = POPOVER_IOS_BODY_MARGIN,
 ): PopoverStyles => {
   const triggerTop = triggerCoordinates ? triggerCoordinates.top + triggerCoordinates.height : bodyHeight / 2 - contentHeight / 2;
   const triggerHeight = triggerCoordinates ? triggerCoordinates.height : 0;
   let left = coordLeft;
-  let top = !isReplace ? coordTop + POPOVER_IOS_BODY_MARGIN : coordTop - triggerHeight;
+  let top = !isReplace ? coordTop + verticalOffset : coordTop - triggerHeight;
   let bottom;
   let originX = contentOriginX;
   let originY = contentOriginY;