@jackuait/blok 0.11.1 → 0.12.0

package/src/components/utils/popover/popover-desktop.ts

@@ -10,13 +10,39 @@ import type { SearchableItem } from './components/search-input';
 import { SearchInput, SearchInputEvent, scoreSearchMatch } from './components/search-input';
 import { PopoverAbstract } from './popover-abstract';
 import { CSSVariables, css as popoverCss } from './popover.const';
+import { clampNestedPopoverTop, resolveNestedPopoverSide } from './popover-nested-position';
 import { resolvePosition } from './popover-position';
+import { stripPopoverAttribute } from '../top-layer';
 import { twMerge } from '../tw';
 
 import type { PopoverParams } from '@/types/utils/popover/popover';
 import { PopoverEvent } from '@/types/utils/popover/popover-event';
 
 
+/**
+ * Last observed pointer position, tracked globally via a document-level
+ * mousemove listener. Used by `PopoverDesktop` to distinguish the
+ * synthesized post-paint mouseover (which fires at the same coordinates
+ * the pointer was already sitting at) from a genuine mouseover triggered
+ * by real pointer motion.
+ *
+ * Fields are null until the first mousemove is observed in this document.
+ */
+const pointerTracker: { x: number | null; y: number | null } = { x: null, y: null };
+
+const POINTER_TRACKER_KEY = '__blokPopoverPointerTracker__';
+
+// Install the tracker once per document; installing from multiple
+// PopoverDesktop modules is a no-op.
+if (typeof document !== 'undefined' && !(document as unknown as Record<string, unknown>)[POINTER_TRACKER_KEY]) {
+  document.addEventListener('mousemove', (event: MouseEvent) => {
+    pointerTracker.x = event.clientX;
+    pointerTracker.y = event.clientY;
+  }, { capture: true });
+  (document as unknown as Record<string, unknown>)[POINTER_TRACKER_KEY] = true;
+}
+
+
 /**
  * Desktop popover.
  * On desktop devices popover behaves like a floating element. Nested popover appears at right or left side.
@@ -52,6 +78,41 @@ export class PopoverDesktop extends PopoverAbstract {
    */
   private previouslyHoveredItem: PopoverItem | null = null;
 
+  /**
+   * Suppresses the synthesized mouseover that Chromium fires immediately
+   * after the popover enters the CSS Top Layer (via `showPopover()`).
+   * Without this guard, the layout-triggered hover would open whatever
+   * nested submenu happens to sit under the pointer the moment the parent
+   * popover appears (e.g. "Convert to" auto-expands the moment block
+   * settings opens).
+   *
+   * The synthesized hit test fires at the same screen coordinates where
+   * the pointer was sitting when the popover opened — it's a pure layout
+   * event, with no pointer motion behind it. We capture those coordinates
+   * at `show()` time; any mouseover whose clientX/Y matches is discarded
+   * as synthesized, while a mouseover at different coordinates is a
+   * genuine hover triggered by real pointer motion and passes through.
+   *
+   * Cleared after one animation frame as a safety net in case no
+   * mouseover arrives at all.
+   */
+  private suppressSyncHover = false;
+
+  /**
+   * Pointer coordinates at the moment `show()` was invoked. Any mouseover
+   * received while armed whose clientX/Y matches these coordinates is
+   * treated as a synthesized post-paint hit test and swallowed. Null when
+   * the suppressor is disarmed or no pointer motion has ever been seen.
+   */
+  private suppressSyncHoverPointer: { x: number; y: number } | null = null;
+
+  /**
+   * Handle returned by requestAnimationFrame used to arm the frame that
+   * clears `suppressSyncHover` as a safety net. Null when no frame is
+   * scheduled.
+   */
+  private suppressSyncHoverRaf: number | null = null;
+
   /**
    * Element of the page that creates 'scope' of the popover.
    * If possible, popover will not cross specified element's borders when opening.
@@ -69,6 +130,16 @@ export class PopoverDesktop extends PopoverAbstract {
    */
   private leftAlignElement: HTMLElement | undefined;
 
+  /**
+   * When true, places the popover to the left of the trigger, vertically centered.
+   */
+  private placeLeftOfAnchor = false;
+
+  /**
+   * Minimum gap (px) from viewport top/bottom when placeLeftOfAnchor is active.
+   */
+  private viewportMargin = 0;
+
   /**
    * Updates the element whose left edge is used for horizontal positioning.
    * @param element - new element to align against, or undefined to fall back to trigger
@@ -102,6 +173,11 @@ export class PopoverDesktop extends PopoverAbstract {
    */
   private promotedSeparators: HTMLElement[] = [];
 
+  /**
+   * Group separator rendered above top-level matches in search results.
+   */
+  private topLevelSeparator: HTMLElement | null = null;
+
   /**
    * Construct the instance
    * @param params - popover params
@@ -119,6 +195,14 @@ export class PopoverDesktop extends PopoverAbstract {
       this.leftAlignElement = params.leftAlignElement;
     }
 
+    if (params.placeLeftOfAnchor === true) {
+      this.placeLeftOfAnchor = true;
+    }
+
+    if (typeof params.viewportMargin === 'number') {
+      this.viewportMargin = params.viewportMargin;
+    }
+
     if (params.nestingLevel !== undefined) {
       this.nestingLevel = params.nestingLevel;
     }
@@ -269,6 +353,13 @@ export class PopoverDesktop extends PopoverAbstract {
       }
     }
 
+    // Set flag BEFORE super.show() so handleHover can suppress the
+    // synthesized mouseover Chromium fires when the element enters the
+    // CSS Top Layer. The flag is released as soon as the user moves the
+    // mouse (real pointer motion distinguishes a genuine hover from a
+    // paint-triggered hit test, which has no motion) or, as a safety net,
+    // after two animation frames if nothing arrives.
+    this.armSuppressSyncHover();
     super.show();
     this.flipper?.activate(this.flippableElements);
 
@@ -347,6 +438,8 @@ export class PopoverDesktop extends PopoverAbstract {
       scrollOffset: { x: window.scrollX, y: window.scrollY },
       offset: 8,
       leftAlignRect,
+      placeLeftOfAnchor: this.placeLeftOfAnchor,
+      viewportMargin: this.viewportMargin,
     });
   }
 
@@ -363,6 +456,10 @@ export class PopoverDesktop extends PopoverAbstract {
 
     this.previouslyHoveredItem = null;
 
+    // Tear down synthesized-hover suppression so a future show() starts
+    // from a known state.
+    this.disarmSuppressSyncHover();
+
     // Clear any externally-supplied anchor rect so the next show() falls back
     // to the trigger element unless the caller explicitly sets a new one.
     // Also clear inline position so a stale top/left from a previous open
@@ -381,6 +478,60 @@ export class PopoverDesktop extends PopoverAbstract {
     super.destroy();
   }
 
+  /**
+   * Arms the synthesized-hover suppression: records the pointer position
+   * at the moment `show()` was called and schedules a safety rAF that
+   * clears the flag even if no mouseover ever arrives. Idempotent —
+   * re-arming tears down any prior armament first.
+   */
+  private armSuppressSyncHover(): void {
+    this.disarmSuppressSyncHover();
+
+    this.suppressSyncHover = true;
+    this.suppressSyncHoverPointer = pointerTracker.x !== null && pointerTracker.y !== null
+      ? { x: pointerTracker.x, y: pointerTracker.y }
+      : null;
+
+    this.suppressSyncHoverRaf = window.requestAnimationFrame(() => {
+      this.suppressSyncHoverRaf = window.requestAnimationFrame(() => {
+        this.disarmSuppressSyncHover();
+      });
+    });
+  }
+
+  /**
+   * True when the given mouseover event looks like Chromium's post-paint
+   * synthesized hit test — i.e. its clientX/Y match the pointer position
+   * snapshot captured at `show()` time. If we have no snapshot (no
+   * mousemove has ever fired in the document) we fall back to treating
+   * every mouseover received while armed as synthesized, matching the
+   * pre-fix behavior for the very first popover opened in a fresh page.
+   * @param event - the mouseover event under consideration
+   */
+  private isLikelySynthesizedHover(event: MouseEvent): boolean {
+    if (this.suppressSyncHoverPointer === null) {
+      return true;
+    }
+
+    return event.clientX === this.suppressSyncHoverPointer.x
+      && event.clientY === this.suppressSyncHoverPointer.y;
+  }
+
+  /**
+   * Tears down the synthesized-hover suppression: clears the flag,
+   * forgets the pointer position snapshot, and cancels the safety rAF.
+   * Safe to call when nothing is armed.
+   */
+  private disarmSuppressSyncHover(): void {
+    this.suppressSyncHover = false;
+    this.suppressSyncHoverPointer = null;
+
+    if (this.suppressSyncHoverRaf !== null) {
+      window.cancelAnimationFrame(this.suppressSyncHoverRaf);
+      this.suppressSyncHoverRaf = null;
+    }
+  }
+
   /**
    * Checks if popover contains the node.
    * Overridden to check nested popover as well.
@@ -417,6 +568,22 @@ export class PopoverDesktop extends PopoverAbstract {
    * @param event - hover event data
    */
   protected handleHover(event: Event): void {
+    // Swallow the synthesized hit test Chromium fires when the element
+    // enters the CSS Top Layer. That hit test reports the same clientX/Y
+    // the pointer was sitting at when `show()` ran; a genuine hover
+    // triggered by real pointer motion reports different coordinates.
+    // A matching event is discarded; a non-matching event disarms the
+    // suppressor and passes through as normal. See `suppressSyncHover`.
+    if (this.suppressSyncHover) {
+      if (event instanceof MouseEvent && this.isLikelySynthesizedHover(event)) {
+        this.disarmSuppressSyncHover();
+
+        return;
+      }
+
+      this.disarmSuppressSyncHover();
+    }
+
     const item = this.getTargetItem(event);
 
     if (item === undefined) {
@@ -611,7 +778,7 @@ export class PopoverDesktop extends PopoverAbstract {
     actualNestedPopoverEl.style.setProperty(CSSVariables.NestingLevel, this.nestedPopover.nestingLevel.toString());
 
     // Apply nested popover positioning (moved from popover.css)
-    this.applyNestedPopoverPositioning(nestedPopoverEl);
+    this.applyNestedPopoverPositioning(nestedPopoverEl, item);
 
     /**
      * Refresh trigger item's active state after any click inside the nested popover.
@@ -634,8 +801,9 @@ export class PopoverDesktop extends PopoverAbstract {
    * Applies positioning styles to nested popover container.
    * This replaces CSS selectors like [data-blok-nested] [data-blok-popover-container]
    * @param nestedPopoverEl - the nested popover element (mount element)
+   * @param triggerItem - popover item whose children are rendered as the nested popover
    */
-  private applyNestedPopoverPositioning(nestedPopoverEl: HTMLElement): void {
+  private applyNestedPopoverPositioning(nestedPopoverEl: HTMLElement, triggerItem: PopoverItem): void {
     const nestedContainerEl = nestedPopoverEl.querySelector(`[${DATA_ATTR.popoverContainer}]`);
     if (!(nestedContainerEl instanceof HTMLElement)) {
       return;
@@ -647,19 +815,38 @@ export class PopoverDesktop extends PopoverAbstract {
 
     // Check if parent popover has openTop or openLeft state
     const _isParentOpenTop = this.nodes.popover.hasAttribute(DATA_ATTR.popoverOpenTop);
-    const isParentOpenLeft = this.nodes.popover.hasAttribute(DATA_ATTR.popoverOpenLeft);
+    const parentPrefersLeft = this.nodes.popover.hasAttribute(DATA_ATTR.popoverOpenLeft);
 
     // Apply position: absolute for nested container
     nestedContainer.style.position = 'absolute';
 
     // Get parent width - use computed width if --width resolves to 'auto'
+    const parentContainerWidth = this.nodes.popoverContainer.offsetWidth;
     const parentWidth = this.params.width === undefined || this.params.width === 'auto'
-      ? `${this.nodes.popoverContainer.offsetWidth}px`
+      ? `${parentContainerWidth}px`
       : 'var(--width)';
 
-    // Calculate --popover-left based on nesting level and parent open direction
-    // Set on the actual popover element to override its default value
-    if (isParentOpenLeft) {
+    // Decide the side based on measured space, not just the parent's flag.
+    // The flag can be truthy for very different reasons (open-left after a
+    // right-edge flip vs. placeLeftOfAnchor) — mirroring it blindly used to
+    // push the nested popover off-screen when the parent itself hugged the
+    // viewport's left edge (e.g. BlockSettings on the leftmost block).
+    const parentRect = this.nodes.popoverContainer.getBoundingClientRect();
+    const nestedMeasuredWidth = this.nestedPopover?.size.width ?? parentContainerWidth;
+    const { openLeft: openNestedLeft } = resolveNestedPopoverSide({
+      parentRect: {
+        left: parentRect.left,
+        right: parentRect.right,
+        width: parentRect.width,
+      },
+      nestedWidth: nestedMeasuredWidth,
+      viewportWidth: window.innerWidth,
+      parentPrefersLeft,
+    });
+
+    // Calculate --popover-left based on nesting level and chosen side.
+    // Set on the actual popover element to override its default value.
+    if (openNestedLeft) {
       // Position to the left
       actualPopoverEl.style.setProperty(CSSVariables.PopoverLeft, `calc(-1 * (var(--nesting-level) + 1) * ${parentWidth} + 100%)`);
     } else {
@@ -667,8 +854,27 @@ export class PopoverDesktop extends PopoverAbstract {
       actualPopoverEl.style.setProperty(CSSVariables.PopoverLeft, `calc(var(--nesting-level) * (${parentWidth} - var(--nested-popover-overlap)))`);
     }
 
-    // Center nested popover vertically on the trigger item
-    nestedContainer.style.top = 'calc(var(--trigger-item-top) - var(--popover-height) / 2 + var(--item-height) / 2)';
+    // Center nested popover vertically on the trigger item, then clamp
+    // so the submenu never overflows the viewport top or bottom.
+    const triggerItemEl = triggerItem.getElement();
+    const triggerItemRect = triggerItemEl?.getBoundingClientRect();
+    const nestedHeight = this.nestedPopover?.size.height ?? 0;
+
+    if (triggerItemRect && nestedHeight > 0) {
+      const triggerCenterY = triggerItemRect.top + triggerItemRect.height / 2;
+      const desiredTop = triggerCenterY - nestedHeight / 2;
+      const { top: clampedTop } = clampNestedPopoverTop({
+        desiredTop,
+        nestedHeight,
+        viewportHeight: window.innerHeight,
+      });
+
+      const parentRootTop = this.nodes.popover.getBoundingClientRect().top;
+
+      nestedContainer.style.top = `${clampedTop - parentRootTop}px`;
+    } else {
+      nestedContainer.style.top = 'calc(var(--trigger-item-top) - var(--popover-height) / 2 + var(--item-height) / 2)';
+    }
   }
 
 
@@ -696,6 +902,12 @@ export class PopoverDesktop extends PopoverAbstract {
     popoverClone.style.position = 'absolute';
     popoverClone.style.top = '-1000px';
 
+    // The native `popover` attribute makes the element `display:none` until
+    // `showPopover()` is called. Strip it from the measurement clone (via the
+    // centralized helper) so the container has a rendered box and
+    // offsetHeight/offsetWidth are real.
+    stripPopoverAttribute(popoverClone);
+
     popoverClone.setAttribute(DATA_ATTR.popoverOpened, 'true');
     popoverClone.querySelector(`[${DATA_ATTR.nested}]`)?.remove();
 
@@ -847,6 +1059,11 @@ export class PopoverDesktop extends PopoverAbstract {
     }
     this.promotedSeparators = [];
 
+    if (this.topLevelSeparator !== null) {
+      this.topLevelSeparator.remove();
+      this.topLevelSeparator = null;
+    }
+
     if (this.promotedItemCache !== null) {
       for (const item of this.promotedItemCache.items) {
         item.getElement()?.remove();
@@ -857,15 +1074,17 @@ export class PopoverDesktop extends PopoverAbstract {
   }
 
   /**
-   * Creates a group separator element for promoted search results.
-   * @param label - the parent chain label (e.g., "Convert to" or "Parent › Child")
+   * Creates a group separator element for search results.
+   * @param label - group label text
+   * @param kind - which data attribute to tag the separator with (top-level vs promoted group)
    */
-  private createGroupSeparator(label: string): HTMLElement {
+  private createGroupSeparator(label: string, kind: 'promoted' | 'topLevel' = 'promoted'): HTMLElement {
     const el = document.createElement('div');
+    const attr = kind === 'topLevel' ? DATA_ATTR.topLevelGroupLabel : DATA_ATTR.promotedGroupLabel;
 
-    el.setAttribute(DATA_ATTR.promotedGroupLabel, '');
+    el.setAttribute(attr, '');
     el.setAttribute('role', 'separator');
-    el.className = 'px-3 pt-2.5 pb-1 text-[11px] font-medium uppercase tracking-wide text-gray-text/50 cursor-default';
+    el.className = 'pl-2 pr-3 pt-2.5 pb-1 text-[11px] font-medium uppercase tracking-wide text-gray-text/50 cursor-default';
     el.textContent = label;
 
     return el;
@@ -1024,6 +1243,16 @@ export class PopoverDesktop extends PopoverAbstract {
     const isEmptyQuery = data.query === '';
     const allTopLevel = data.topLevelItems as unknown as PopoverItemDefault[];
 
+    if (this.nodes.contextLabel !== undefined) {
+      if (isEmptyQuery) {
+        this.nodes.contextLabel.removeAttribute(DATA_ATTR.hidden);
+        this.nodes.contextLabel.classList.remove('hidden');
+      } else {
+        this.nodes.contextLabel.setAttribute(DATA_ATTR.hidden, 'true');
+        this.nodes.contextLabel.classList.add('hidden');
+      }
+    }
+
     // Deduplicate: hide top-level items whose title matches a promoted item
     const matchingTopLevel = !isEmptyQuery && data.promotedItems.length > 0
       ? this.deduplicateAgainstPromoted(allTopLevel, data.promotedItems)
@@ -1058,12 +1287,29 @@ export class PopoverDesktop extends PopoverAbstract {
     }
     this.promotedSeparators = [];
 
+    if (this.topLevelSeparator !== null) {
+      this.topLevelSeparator.remove();
+      this.topLevelSeparator = null;
+    }
+
     if (this.promotedItemCache !== null) {
       for (const item of this.promotedItemCache.items) {
         item.getElement()?.remove();
       }
     }
 
+    // Render top-level group header when promoted groups will be rendered below
+    if (!isEmptyQuery && matchingTopLevel.length > 0 && data.promotedItems.length > 0) {
+      const label = this.messages.actions ?? 'Actions';
+      const separator = this.createGroupSeparator(label, 'topLevel');
+      const firstRankedElement = matchingTopLevel[0].getElement();
+
+      if (firstRankedElement !== null && this.nodes.items !== null) {
+        this.nodes.items.insertBefore(separator, firstRankedElement);
+        this.topLevelSeparator = separator;
+      }
+    }
+
     // Render promoted items grouped by parent chain
     if (data.promotedItems.length > 0) {
       const groups = new Map<string, Array<{ item: PopoverItemDefault; score: number }>>();

package/src/components/utils/popover/popover-inline.ts

@@ -149,7 +149,7 @@ export class PopoverInline extends PopoverDesktop {
 
     // Apply inline items container styles
     if (this.nodes.items) {
-      this.nodes.items.className = twMerge(css.items, 'flex');
+      this.nodes.items.className = twMerge(css.items, 'flex pb-0');
     }
 
     // Set inline height CSS variables
@@ -204,7 +204,8 @@ export class PopoverInline extends PopoverDesktop {
       this.nodes.popoverContainer.className = twMerge(
         css.popoverContainer,
         css.popoverContainerOpened,
-        cssInline.popoverContainer
+        cssInline.popoverContainer,
+        cssInline.popoverContainerOpened
       );
 
       // Set height based on screen

package/src/components/utils/popover/popover-nested-position.ts

@@ -0,0 +1,132 @@
+/**
+ * Input for resolving the side (left / right of the parent popover) the
+ * nested popover should open on.
+ */
+export interface NestedPopoverPositionInput {
+  /** Viewport-relative rect of the parent popover container. */
+  parentRect: { left: number; right: number; width: number };
+  /** Measured nested popover width (container offsetWidth). */
+  nestedWidth: number;
+  /** Current viewport width (window.innerWidth). */
+  viewportWidth: number;
+  /**
+   * Preferred side derived from the parent's own positioning.
+   * True when the parent already sits "open-left" (right-aligned or
+   * placed left of its anchor) — the nested popover prefers to continue
+   * extending leftward unless no room remains.
+   */
+  parentPrefersLeft: boolean;
+  /**
+   * Horizontal overlap (px) between the parent and a right-side nested
+   * popover. The nested popover can overlap the parent's trailing edge by
+   * this many pixels, which effectively grants the nested popover extra
+   * horizontal room on the right.
+   * Defaults to 4 to match the `--nested-popover-overlap` CSS variable.
+   */
+  overlap?: number;
+}
+
+export interface NestedPopoverPositionOutput {
+  /** True when the nested popover should open to the left of the parent. */
+  openLeft: boolean;
+}
+
+/**
+ * Picks the side the nested popover should open on.
+ *
+ * The rules, in order:
+ *   1. If the nested popover fits on the preferred side, keep it there.
+ *   2. Otherwise, flip to the alternate side if it fits there.
+ *   3. If neither side fits, pick the side with more available space so the
+ *      popover stays as close to on-screen as possible.
+ *
+ * The decision is based purely on measured pixel geometry — never on the
+ * parent's own positioning flag alone. That flag may mean different things
+ * in different placement modes (open-left after right-edge flip vs.
+ * placeLeftOfAnchor), and blindly mirroring it onto the nested popover
+ * pushed it off-screen when the parent itself hugged the viewport's left
+ * edge. See `src/components/utils/popover/popover-desktop.ts`.
+ */
+export function resolveNestedPopoverSide(input: NestedPopoverPositionInput): NestedPopoverPositionOutput {
+  const {
+    parentRect,
+    nestedWidth,
+    viewportWidth,
+    parentPrefersLeft,
+    overlap = 4,
+  } = input;
+
+  const spaceOnLeft = Math.max(0, parentRect.left);
+  const spaceOnRight = Math.max(0, viewportWidth - parentRect.right + overlap);
+
+  const fitsLeft = nestedWidth <= spaceOnLeft;
+  const fitsRight = nestedWidth <= spaceOnRight;
+
+  if (parentPrefersLeft) {
+    if (fitsLeft) {
+      return { openLeft: true };
+    }
+
+    if (fitsRight) {
+      return { openLeft: false };
+    }
+  } else {
+    if (fitsRight) {
+      return { openLeft: false };
+    }
+
+    if (fitsLeft) {
+      return { openLeft: true };
+    }
+  }
+
+  // Neither side fits — pick the side with more space. Break ties by
+  // keeping the default (right) side so the nested popover stays anchored
+  // next to the trigger rather than flipping for no visible benefit.
+  return { openLeft: spaceOnLeft > spaceOnRight };
+}
+
+/**
+ * Input for clamping the nested popover's vertical position.
+ * All coordinates are in viewport space.
+ */
+export interface ClampNestedPopoverTopInput {
+  /** Desired top (viewport-relative) before any clamping — usually centered on the trigger item. */
+  desiredTop: number;
+  /** Measured nested popover height. */
+  nestedHeight: number;
+  /** Current viewport height (window.innerHeight). */
+  viewportHeight: number;
+  /** Minimum gap from the viewport's top/bottom edges. Defaults to 8. */
+  margin?: number;
+}
+
+export interface ClampNestedPopoverTopOutput {
+  /** Clamped top (viewport-relative). */
+  top: number;
+}
+
+/**
+ * Clamps the nested popover's vertical position so it stays inside the
+ * viewport. When the popover is taller than the viewport minus margins,
+ * pins it to the top margin so at least its first items remain reachable.
+ *
+ * Horizontal flipping is handled separately by {@link resolveNestedPopoverSide}.
+ */
+export function clampNestedPopoverTop(input: ClampNestedPopoverTopInput): ClampNestedPopoverTopOutput {
+  const {
+    desiredTop,
+    nestedHeight,
+    viewportHeight,
+    margin = 8,
+  } = input;
+
+  const topFloor = margin;
+  const maxTop = viewportHeight - nestedHeight - margin;
+
+  if (maxTop < topFloor) {
+    return { top: topFloor };
+  }
+
+  return { top: Math.max(topFloor, Math.min(maxTop, desiredTop)) };
+}

package/src/components/utils/popover/popover-position.ts

@@ -17,6 +17,19 @@ export interface PositionInput {
   offset?: number;
   /** Element rect whose left edge overrides anchor's left for horizontal alignment */
   leftAlignRect?: DOMRect;
+  /**
+   * When true, the popover is placed to the left of the anchor (its right edge
+   * sits one offset-gap before the anchor's left edge) and is vertically centered
+   * against the anchor. Clamping to scope boundaries still applies.
+   */
+  placeLeftOfAnchor?: boolean;
+  /**
+   * Minimum distance (in pixels) between the popover and the viewport top/bottom
+   * edges. Applied only when placeLeftOfAnchor is true. Keeps the popover
+   * within the viewport — shifting up if centered placement would overflow the
+   * bottom — so it remains fully visible near the anchor. Has no effect when 0.
+   */
+  viewportMargin?: number;
 }
 
 export interface ResolvedPosition {
@@ -62,12 +75,44 @@ export function resolvePosition(input: PositionInput): ResolvedPosition {
     scrollOffset,
     offset = 8,
     leftAlignRect,
+    placeLeftOfAnchor = false,
+    viewportMargin = 0,
   } = input;
 
-  // --- Vertical ---
   const boundaryBottom = Math.min(viewportSize.height, scopeBounds.bottom);
   const boundaryTop = Math.max(0, scopeBounds.top);
+  const boundaryRight = Math.min(viewportSize.width, scopeBounds.right);
+  const boundaryLeft = Math.max(0, scopeBounds.left);
+  const scopeTopInDocCoords = scopeBounds.top + scrollOffset.y;
+
+  // Placement mode: left of anchor, vertically centered.
+  if (placeLeftOfAnchor) {
+    const anchorCenterY = (anchor.top + anchor.bottom) / 2 + scrollOffset.y;
+    const anchorTopInDocCoords = anchor.top + scrollOffset.y;
+    const rawTop = anchorCenterY - popoverSize.height / 2;
+    const scopeBottomInDocCoords = scopeBounds.bottom + scrollOffset.y;
+    const viewportTopFloor = scrollOffset.y + viewportMargin;
+    const viewportBottomCeiling = scrollOffset.y + viewportSize.height - viewportMargin;
+
+    // Popover top must never sit below the anchor top — keeps the menu visually
+    // attached to the trigger instead of dropping underneath it when the viewport
+    // margin would otherwise force the top edge down.
+    const topFloor = Math.max(scopeTopInDocCoords, Math.min(viewportTopFloor, anchorTopInDocCoords));
+    const bottomCeiling = Math.min(scopeBottomInDocCoords, viewportBottomCeiling);
+    const maxTop = bottomCeiling - popoverSize.height;
+    const anchorCeiling = Math.max(topFloor, anchorTopInDocCoords);
+    const constrainedTop = Math.min(anchorCeiling, Math.max(topFloor, rawTop));
+    const top = maxTop < topFloor
+      ? topFloor
+      : Math.min(maxTop, constrainedTop);
+
+    const rawLeft = anchor.left - offset - popoverSize.width + scrollOffset.x;
+    const left = Math.max(boundaryLeft + scrollOffset.x, rawLeft);
+
+    return { top, left, openTop: false, openLeft: true };
+  }
 
+  // --- Vertical ---
   const spaceBelow = boundaryBottom - anchor.bottom - offset;
   const spaceAbove = anchor.top - offset - boundaryTop;
 
@@ -82,15 +127,11 @@ export function resolvePosition(input: PositionInput): ResolvedPosition {
   // than the viewport-clamped boundaryTop, so the clamp is correct when the page is
   // scrolled (boundaryTop is viewport-relative; adding scrollOffset converts it to
   // document coords but discards any negative scope top that was clamped to 0).
-  const scopeTopInDocCoords = scopeBounds.top + scrollOffset.y;
   const top = rawTop < scopeTopInDocCoords
     ? scopeTopInDocCoords
     : rawTop;
 
   // --- Horizontal ---
-  const boundaryRight = Math.min(viewportSize.width, scopeBounds.right);
-  const boundaryLeft = Math.max(0, scopeBounds.left);
-
   const alignLeft = (leftAlignRect?.left ?? anchor.left) + scrollOffset.x;
   const alignRight = anchor.right + scrollOffset.x;