npm - @jsenv/dom - Versions diffs - 0.9.5 → 0.10.1 - Mend

@jsenv/dom 0.9.5 → 0.10.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/dist/jsenv_dom.js +568 -188
package/package.json +2 -2

package/dist/jsenv_dom.js CHANGED Viewed

@@ -117,13 +117,16 @@ const getElementSignature = (element) => {
       return "<html>";
     }
     const elementId = element.id;
-    if (elementId) {
+    const className = element.className;
+    if (elementId && !looksLikeGeneratedId(elementId)) {
       return `${tagName}#${elementId}`;
     }
-    const className = element.className;
     if (className) {
       return `${tagName}.${className.split(" ").join(".")}`;
     }
+    if (elementId) {
+      return `${tagName}#${elementId}`;
+    }
     const parentSignature = getElementSignature(element.parentElement);
     return `${parentSignature} > ${tagName}`;
@@ -131,6 +134,13 @@ const getElementSignature = (element) => {
   return String(element);
 };
+// Generated ids from frameworks (Preact useId, React useId, etc.) look like
+// "P0-0", ":r0:", "P1-3" — short alphanumeric tokens with dashes or colons.
+// If an id matches this pattern we prefer className over it.
+const looksLikeGeneratedId = (id) => {
+  return /^[A-Z][0-9]+-[0-9]+$|^:[a-z][0-9]*:$/.test(id);
+};
 const createIterableWeakSet = () => {
   const objectWeakRefSet = new Set();
@@ -309,6 +319,7 @@ const elementIsWindow = (a) => a.window === a;
 const elementIsDocument = (a) => a.nodeType === 9;
 const elementIsDetails = ({ nodeName }) => nodeName === "DETAILS";
 const elementIsSummary = ({ nodeName }) => nodeName === "SUMMARY";
+const elementIsDialog = ({ nodeName }) => nodeName === "DIALOG";
 // should be used ONLY when an element is related to other elements that are not descendants of this element
 const getAssociatedElements = (element) => {
@@ -3849,6 +3860,16 @@ const getFocusVisibilityInfo = (node) => {
       }
       // Continue checking ancestors
     }
+    if (elementIsDialog(nodeOrAncestor) && !nodeOrAncestor.open) {
+      return { visible: false, reason: "inside closed dialog element" };
+    }
+    if (
+      nodeOrAncestor.popover !== null &&
+      nodeOrAncestor.popover !== undefined &&
+      !nodeOrAncestor.matches(":popover-open")
+    ) {
+      return { visible: false, reason: "inside closed popover element" };
+    }
     nodeOrAncestor = nodeOrAncestor.parentNode;
   }
   return { visible: true, reason: "no reason to be hidden" };
@@ -4661,7 +4682,11 @@ const getNextTablePosition = (
 const performTabNavigation = (
   event,
-  { rootElement = document.body, outsideOfElement = null } = {},
+  {
+    rootElement = document.body,
+    outsideOfElement = null,
+    debug = () => {},
+  } = {},
 ) => {
   if (!isTabEvent$1(event)) {
     return false;
@@ -4673,29 +4698,20 @@ const performTabNavigation = (
   }
   const isForward = !event.shiftKey;
   const onTargetToFocus = (targetToFocus) => {
-    console.debug(
+    debug(
       `Tab navigation: ${isForward ? "forward" : "backward"} from`,
-      activeElement,
+      getElementSignature(activeElement),
       "to",
-      targetToFocus,
+      getElementSignature(targetToFocus),
     );
     event.preventDefault();
     markFocusNav(event);
     targetToFocus.focus();
   };
-  {
-    console.debug(
-      `Tab navigation: ${isForward ? "forward" : "backward"} from,`,
-      activeElement,
-    );
-  }
   const predicate = (candidate) => {
     const canBeFocusedByTab = isFocusableByTab(candidate);
-    {
-      console.debug(`Testing`, candidate, `${canBeFocusedByTab ? "✓" : "✗"}`);
-    }
+    // debug(`Testing`, candidate, `${canBeFocusedByTab ? "✓" : "✗"}`);
     return canBeFocusedByTab;
   };
@@ -4720,7 +4736,8 @@ const performTabNavigation = (
     if (nextFocusableElement) {
       return onTargetToFocus(nextFocusableElement);
     }
-    const firstFocusableElement = findDescendant(activeElement, predicate, {
+    // Wrap around: go back to the first focusable element in root.
+    const firstFocusableElement = findDescendant(rootElement, predicate, {
       skipRoot: outsideOfElement,
     });
     if (firstFocusableElement) {
@@ -4751,7 +4768,8 @@ const performTabNavigation = (
     if (previousFocusableElement) {
       return onTargetToFocus(previousFocusableElement);
     }
-    const lastFocusableElement = findLastDescendant(activeElement, predicate, {
+    // Wrap around: go back to the last focusable element in root.
+    const lastFocusableElement = findLastDescendant(rootElement, predicate, {
       skipRoot: outsideOfElement,
     });
     if (lastFocusableElement) {
@@ -4876,7 +4894,35 @@ const preventFocusNavViaKeyboard = (keyboardEvent) => {
   return false;
 };
-const trapFocusInside = (element) => {
+/**
+ * Traps keyboard focus and mouse clicks inside `element`.
+ *
+ * Once active:
+ * - **Tab / Shift+Tab** cycle through focusable descendants of `element`,
+ *   wrapping from last → first and first → last. If no focusable element
+ *   exists, the default browser Tab action is suppressed so focus cannot
+ *   escape.
+ * - **Mouse clicks** outside `element` are only blocked when `pointerTrap`
+ *   is `true`. Backdrop clicks (on `<dialog>` elements) still propagate even
+ *   then, so the dialog can close itself.
+ *
+ * Multiple traps can be stacked. When a new trap is activated the previous
+ * one is paused; when the new trap is released the previous one resumes.
+ * Traps must be released in LIFO order (the reverse of activation order).
+ *
+ * @param {HTMLElement} element - The root element to trap focus inside.
+ * @param {object} [options]
+ * @param {boolean} [options.pointerTrap=false] - When true, mouse clicks outside `element`
+ *   are cancelled so the user cannot move focus away by clicking the backdrop.
+ *   Backdrop clicks (target is a `<dialog>` element) only receive `preventDefault`
+ *   and still propagate, allowing the dialog to react to them (e.g. close itself).
+ * @param {Function} [options.debug] - Optional debug logger passed to tab navigation.
+ * @returns {() => void} Cleanup function — call it to release the trap.
+ */
+const trapFocusInside = (
+  element,
+  { debug, pointerTrap = false } = {},
+) => {
   if (element.nodeType === 3) {
     console.warn("cannot trap focus inside a text node");
     return () => {};
@@ -4891,39 +4937,67 @@ const trapFocusInside = (element) => {
   }
   const isEventOutside = (event) => {
-    if (event.target === element) return false;
-    if (element.contains(event.target)) return false;
+    if (event.target === element) {
+      return false;
+    }
+    if (element.contains(event.target)) {
+      return false;
+    }
     return true;
   };
   const lock = () => {
-    const onmousedown = (event) => {
-      if (isEventOutside(event)) {
-        event.preventDefault();
-        event.stopImmediatePropagation();
-      }
-    };
+    const onmousedown = pointerTrap
+      ? (event) => {
+          if (!isEventOutside(event)) {
+            return;
+          }
+          event.preventDefault();
+          // Backdrop clicks (e.g. clicking a <dialog>'s ::backdrop) must still
+          // propagate so the dialog/popover can react to them (e.g. close itself).
+          // A backdrop click is detected when the target is a <dialog> element —
+          // the ::backdrop pseudo-element is not in the DOM, so the event target
+          // becomes the dialog element itself when its content area is not hit.
+          const isBackdropClick =
+            event.target.tagName === "DIALOG" ||
+            event.target.className.includes("backdrop");
+          if (!isBackdropClick) {
+            event.stopImmediatePropagation();
+          }
+        }
+      : null;
     const onkeydown = (event) => {
       if (isTabEvent(event)) {
-        performTabNavigation(event, { rootElement: element });
+        const handled = performTabNavigation(event, {
+          rootElement: element,
+          debug,
+        });
+        if (!handled) {
+          // No focusable target found — prevent the browser from moving focus outside the trap.
+          event.preventDefault();
+        }
       }
     };
-    document.addEventListener("mousedown", onmousedown, {
-      capture: true,
-      passive: false,
-    });
+    if (onmousedown) {
+      document.addEventListener("mousedown", onmousedown, {
+        capture: true,
+        passive: false,
+      });
+    }
     document.addEventListener("keydown", onkeydown, {
       capture: true,
       passive: false,
     });
     return () => {
-      document.removeEventListener("mousedown", onmousedown, {
-        capture: true,
-        passive: false,
-      });
+      if (onmousedown) {
+        document.removeEventListener("mousedown", onmousedown, {
+          capture: true,
+          passive: false,
+        });
+      }
       document.removeEventListener("keydown", onkeydown, {
         capture: true,
         passive: false,
@@ -5785,11 +5859,228 @@ const getScrollbarState = (
   return { x, y, availableWidth, availableHeight };
 };
+/**
+ * Scrolls el into view within a specific container only — does NOT scroll
+ * any ancestor beyond that container (document, popover backdrop, etc.).
+ *
+ * Why not just use scrollIntoView({ container: "nearest" })?
+ * It finds the nearest scrollable ancestor and stops there ONLY IF that
+ * ancestor has visible scrollbar, otherwise browser walks further up,
+ * potentially scrolling the document.
+ * This is exactly the wrong behavior inside a popover or fixed panel.
+ * scrollIntoViewScoped avoids this by targeting one container explicitly.
+ *
+ * Uses scrollTo() so CSS scroll-behavior:smooth on the container is respected.
+ * Respects scroll-margin-* on the element.
+ *
+ * @param {Element} el - The element to scroll into view.
+ * @param {object} options
+ * @param {Element} [options.container] - The scroll container to scroll. Defaults to getScrollContainer(el).
+ * @param {"start"|"center"|"end"|"nearest"} [options.block="nearest"] - Vertical alignment.
+ * @param {"start"|"center"|"end"|"nearest"} [options.inline="nearest"] - Horizontal alignment.
+ */
+const scrollIntoViewScoped = (
+  el,
+  {
+    container = getScrollContainer(el),
+    block = "nearest",
+    inline = "nearest",
+  } = {},
+) => {
+  if (!container) {
+    return;
+  }
+  const containerRect = container.getBoundingClientRect();
+  const elRect = el.getBoundingClientRect();
+  const style = getComputedStyle(el);
+  const scrollMarginTop = parseFloat(style.scrollMarginTop) || 0;
+  const scrollMarginBottom = parseFloat(style.scrollMarginBottom) || 0;
+  const scrollMarginLeft = parseFloat(style.scrollMarginLeft) || 0;
+  const scrollMarginRight = parseFloat(style.scrollMarginRight) || 0;
+  const currentScrollTop = container.scrollTop;
+  const currentScrollLeft = container.scrollLeft;
+  const containerHeight = containerRect.height;
+  const containerWidth = containerRect.width;
+  // Element position relative to the container's scroll origin.
+  const elTop =
+    elRect.top - containerRect.top + currentScrollTop - scrollMarginTop;
+  const elBottom = elTop + elRect.height + scrollMarginTop + scrollMarginBottom;
+  const elLeft =
+    elRect.left - containerRect.left + currentScrollLeft - scrollMarginLeft;
+  const elRight = elLeft + elRect.width + scrollMarginLeft + scrollMarginRight;
+  let newScrollTop = currentScrollTop;
+  if (block === "start") {
+    newScrollTop = elTop;
+  } else if (block === "end") {
+    newScrollTop = elBottom - containerHeight;
+  } else if (block === "center") {
+    newScrollTop = elTop + (elRect.height - containerHeight) / 2;
+  } else {
+    // nearest: scroll only if partially or fully out of view.
+    // When the element is taller than the container, only scroll if it is
+    // completely out of view — otherwise it is already as visible as possible.
+    const scrollBottom = currentScrollTop + containerHeight;
+    const elHeight = elBottom - elTop;
+    if (elHeight <= containerHeight) {
+      if (elTop < currentScrollTop) {
+        newScrollTop = elTop;
+      } else if (elBottom > scrollBottom) {
+        newScrollTop = elBottom - containerHeight;
+      }
+    } else if (elBottom < currentScrollTop) {
+      newScrollTop = elBottom - containerHeight;
+    } else if (elTop > scrollBottom) {
+      newScrollTop = elTop;
+    }
+  }
+  let newScrollLeft = currentScrollLeft;
+  if (inline === "start") {
+    newScrollLeft = elLeft;
+  } else if (inline === "end") {
+    newScrollLeft = elRight - containerWidth;
+  } else if (inline === "center") {
+    newScrollLeft = elLeft + (elRect.width - containerWidth) / 2;
+  } else {
+    // nearest: scroll only if partially or fully out of view.
+    // When the element is wider than the container, only scroll if it is
+    // completely out of view — otherwise it is already as visible as possible.
+    const scrollRight = currentScrollLeft + containerWidth;
+    const elWidth = elRight - elLeft;
+    if (elWidth <= containerWidth) {
+      if (elLeft < currentScrollLeft) {
+        newScrollLeft = elLeft;
+      } else if (elRight > scrollRight) {
+        newScrollLeft = elRight - containerWidth;
+      }
+    } else if (elRight < currentScrollLeft) {
+      newScrollLeft = elRight - containerWidth;
+    } else if (elLeft > scrollRight) {
+      newScrollLeft = elLeft;
+    }
+  }
+  container.scrollTo({
+    left: newScrollLeft,
+    top: newScrollTop,
+  });
+};
+/**
+ * DON'T USE THIS, use scroll-padding-top/bottom in CSS instead
+ * better in every aspect
+ */
+/**
+ * Scrolls el into view (using the native "nearest" block behavior) and then
+ * corrects for any sticky element that visually covers el inside its scroll
+ * container.
+ *
+ * After the native scroll, this function iterates the siblings of el (children
+ * of el's parent) and checks whether any of them uses `position: sticky` and
+ * overlaps el. The largest overlap on each side is used to nudge scrollTop:
+ * - sticky-top (top !== auto): subtract overlap so el appears below the header
+ * - sticky-bottom (bottom !== auto): add overlap so el appears above the footer
+ *
+ * If el happens to be covered on both sides at once (extremely unlikely) the
+ * correction picks whichever side was covered — the result may not be perfect
+ * but avoids an infinite correction loop.
+ *
+ * @param {Element} el - The element to scroll into view.
+ */
+const scrollIntoViewWithStickyAwareness = (
+  el,
+  { behavior, block = "nearest", inline, container } = {},
+) => {
+  el.scrollIntoView({ behavior, block, inline, container });
+  const scrollContainer = getScrollContainer(el);
+  if (!scrollContainer) {
+    return;
+  }
+  const elRect = el.getBoundingClientRect();
+  let topCover = 0;
+  let bottomCover = 0;
+  for (const sibling of el.parentNode.children) {
+    const style = getComputedStyle(sibling);
+    if (style.position !== "sticky") {
+      continue;
+    }
+    const rect = sibling.getBoundingClientRect();
+    if (style.top !== "auto") {
+      // Sticky-top: covers el from above — track the largest overlap.
+      const overlap = rect.bottom - elRect.top;
+      if (overlap > topCover) {
+        topCover = overlap;
+      }
+    } else if (style.bottom !== "auto") {
+      // Sticky-bottom: covers el from below — track the largest overlap.
+      // Only checked when top is "auto" so each element is attributed to one
+      // side only; both sides are still accumulated across all children.
+      const overlap = elRect.bottom - rect.top;
+      if (overlap > bottomCover) {
+        bottomCover = overlap;
+      }
+    }
+    if (topCover > 0 && bottomCover > 0) {
+      // Both sides already have coverage — no point checking further children.
+      break;
+    }
+  }
+  if (topCover > 0) {
+    // For block="center" the element is visually centered in the full viewport.
+    // A sticky header of height H shifts the available center upward by H/2,
+    // so we only need to correct by half the overlap to keep the element
+    // centered in the visible (uncovered) area.
+    scrollContainer.scrollTop -= block === "center" ? topCover / 2 : topCover;
+  }
+  if (bottomCover > 0) {
+    scrollContainer.scrollTop +=
+      block === "center" ? bottomCover / 2 : bottomCover;
+  }
+};
+/**
+ * Prevents scrolling on all scrollable containers that are ancestors of (or
+ * siblings preceding) `element`. Used when an overlay (popover, dialog) is
+ * open and background scroll should be disabled.
+ *
+ * **Why padding instead of scrollbar-gutter?**
+ * `scrollbar-gutter: stable` would be the modern, CSS-native way to reserve
+ * the scrollbar lane before hiding overflow so the layout doesn't shift.
+ * However it only works well when the element's design already accounts for
+ * that reserved space. On arbitrary containers we can't assume that, so we
+ * measure the actual scrollbar size and compensate with padding — a technique
+ * that works regardless of how the element is styled.
+ *
+ * **What if the element already uses scrollbar-gutter?**
+ * A non-"auto" `scrollbar-gutter` value signals that the element has its own
+ * scrollbar-gutter strategy in place. In that case we skip the padding
+ * compensation and rely on that strategy instead — adding padding on top of an
+ * already-reserved gutter would double-count the space.
+ *
+ * @param {HTMLElement} element - The overlay element being shown. Its preceding
+ *   siblings and all ancestor scroll containers will be scroll-locked.
+ * @returns {() => void} Cleanup function that restores all modified styles.
+ */
 const trapScrollInside = (element) => {
   const cleanupCallbackSet = new Set();
   const lockScroll = (el) => {
+    const scrollbarGutter = getStyle(el, "scrollbar-gutter");
+    const hasScrollbarGutterStrategy =
+      scrollbarGutter && scrollbarGutter !== "auto";
+    if (hasScrollbarGutterStrategy) {
+      // The element manages its own gutter — just hide overflow, no padding needed.
+      const removeScrollLockStyles = setStyles(el, { overflow: "hidden" });
+      cleanupCallbackSet.add(removeScrollLockStyles);
+      return;
+    }
     const [scrollbarWidth, scrollbarHeight] = measureScrollbar(el);
-    // scrollbar-gutter would work but would display an empty blank space
     const paddingRight = parseInt(getStyle(el, "padding-right"), 0);
     const paddingTop = parseInt(getStyle(el, "padding-top"), 0);
     const removeScrollLockStyles = setStyles(el, {
@@ -5797,9 +6088,7 @@ const trapScrollInside = (element) => {
       "padding-top": `${paddingTop + scrollbarHeight}px`,
       "overflow": "hidden",
     });
-    cleanupCallbackSet.add(() => {
-      removeScrollLockStyles();
-    });
+    cleanupCallbackSet.add(removeScrollLockStyles);
   };
   let previous = element.previousSibling;
   while (previous) {
@@ -9237,24 +9526,27 @@ const stickyAsRelativeCoords = (
   return [leftPosition, topPosition];
 };
-// Creates a visible rect effect that tracks how much of an element is visible within its scrollable parent
-// and within the document viewport. This is useful for implementing overlays, lazy loading, or any UI
-// that needs to react to element visibility changes.
-//
-// The function returns two visibility ratios:
-// - scrollVisibilityRatio: Visibility ratio relative to the scrollable parent (0-1)
-// - visibilityRatio: Visibility ratio relative to the document viewport (0-1)
-//
-// When scrollable parent is the document, both ratios will be the same.
-// When scrollable parent is a custom container, scrollVisibilityRatio might be 1.0 (fully visible
-// within the container) while visibilityRatio could be 0.0 (container is scrolled out of viewport).
-// A bit like https://tetherjs.dev/ but different
+/**
+ * Tracks how much of an element is visible within its scrollable parent and within the
+ * document viewport. Calls update() on initialization and whenever visibility changes
+ * (scroll, resize, intersection changes).
+ *
+ * The update callback receives a visibleRect object with:
+ * - left, top, right, bottom, width, height: the visible portion of the element,
+ *   clipped to its scroll container's bounds and expressed in overlay coordinates
+ * - visibilityRatio: fraction of the element's area that is truly visible on screen (0–1).
+ *   For document scroll containers this is the viewport-clipped fraction.
+ *   For custom containers this is the fraction clipped by both the container AND the viewport
+ *   (so an element scrolled out of its container correctly reports 0, not 1).
+ *
+ * A bit like https://tetherjs.dev/ but different
+ */
 const visibleRectEffect = (element, update) => {
   const [teardown, addTeardown] = createPubSub();
   const scrollContainer = getScrollContainer(element);
   const scrollContainerIsDocument =
     scrollContainer === document.documentElement;
-  const check = (reason) => {
+  const check = (event) => {
     // 1. Calculate element position relative to scrollable parent
     const { scrollLeft, scrollTop } = scrollContainer;
@@ -9346,27 +9638,35 @@ const visibleRectEffect = (element, update) => {
       }
     }
-    // Calculate visibility ratios
-    const scrollVisibilityRatio =
-      (widthVisible * heightVisible) / (width * height);
-    // Calculate visibility ratio relative to document viewport
-    let documentVisibilityRatio;
+    // Calculate visibilityRatio: fraction of element area truly visible on screen.
+    // For custom containers we intersect the container-clipped visible size (widthVisible x
+    // heightVisible) with the viewport bounds, so an element scrolled out of its container
+    // correctly reports 0 rather than the raw viewport intersection of its bounding rect.
+    let visibilityRatio;
     if (scrollContainerIsDocument) {
-      documentVisibilityRatio = scrollVisibilityRatio;
+      visibilityRatio = (widthVisible * heightVisible) / (width * height);
     } else {
-      // For custom containers, calculate visibility relative to document viewport
-      const elementRect = element.getBoundingClientRect();
+      // widthVisible/heightVisible are already clipped to the scroll container.
+      // Now clip their viewport-relative counterparts against the viewport.
       const viewportWidth = window.innerWidth;
       const viewportHeight = window.innerHeight;
-      // Calculate how much of the element is visible in the document viewport
-      const elementLeft = Math.max(0, elementRect.left);
-      const elementTop = Math.max(0, elementRect.top);
-      const elementRight = Math.min(viewportWidth, elementRect.right);
-      const elementBottom = Math.min(viewportHeight, elementRect.bottom);
-      const documentVisibleWidth = Math.max(0, elementRight - elementLeft);
-      const documentVisibleHeight = Math.max(0, elementBottom - elementTop);
-      documentVisibilityRatio =
-        (documentVisibleWidth * documentVisibleHeight) / (width * height);
+      // Container-clipped visible rect in viewport coordinates
+      const visibleLeft = overlayLeft;
+      const visibleTop = overlayTop;
+      const visibleRight = overlayLeft + widthVisible;
+      const visibleBottom = overlayTop + heightVisible;
+      // Intersect with viewport
+      const clippedLeft = visibleLeft < 0 ? 0 : visibleLeft;
+      const clippedTop = visibleTop < 0 ? 0 : visibleTop;
+      const clippedRight =
+        visibleRight > viewportWidth ? viewportWidth : visibleRight;
+      const clippedBottom =
+        visibleBottom > viewportHeight ? viewportHeight : visibleBottom;
+      const clippedWidth =
+        clippedRight > clippedLeft ? clippedRight - clippedLeft : 0;
+      const clippedHeight =
+        clippedBottom > clippedTop ? clippedBottom - clippedTop : 0;
+      visibilityRatio = (clippedWidth * clippedHeight) / (width * height);
     }
     const visibleRect = {
@@ -9376,22 +9676,22 @@ const visibleRectEffect = (element, update) => {
       bottom: overlayTop + heightVisible,
       width: widthVisible,
       height: heightVisible,
-      visibilityRatio: documentVisibilityRatio,
-      scrollVisibilityRatio,
+      visibilityRatio,
     };
     update(visibleRect, {
+      event,
       width,
       height,
     });
   };
-  check();
+  check(new CustomEvent("initialization"));
   const [publishBeforeAutoCheck, onBeforeAutoCheck] = createPubSub();
   {
-    const autoCheck = (reason) => {
-      const beforeCheckResults = publishBeforeAutoCheck(reason);
-      check();
+    const autoCheck = (event) => {
+      const beforeCheckResults = publishBeforeAutoCheck(event);
+      check(event);
       for (const beforeCheckResult of beforeCheckResults) {
         if (typeof beforeCheckResult === "function") {
           beforeCheckResult();
@@ -9412,8 +9712,8 @@ const visibleRectEffect = (element, update) => {
     {
       // If scrollable parent is not document, also listen to document scroll
       // to update UI position when the scrollable parent moves in viewport
-      const onDocumentScroll = () => {
-        autoCheck("document_scroll");
+      const onDocumentScroll = (e) => {
+        autoCheck(e);
       };
       document.addEventListener("scroll", onDocumentScroll, {
         passive: true,
@@ -9424,8 +9724,8 @@ const visibleRectEffect = (element, update) => {
         });
       });
       if (!scrollContainerIsDocument) {
-        const onScroll = () => {
-          autoCheck("scrollable_parent_scroll");
+        const onScroll = (e) => {
+          autoCheck(e);
         };
         scrollContainer.addEventListener("scroll", onScroll, {
           passive: true,
@@ -9438,8 +9738,8 @@ const visibleRectEffect = (element, update) => {
       }
     }
     {
-      const onWindowResize = () => {
-        autoCheck("window_size_change");
+      const onWindowResize = (e) => {
+        autoCheck(e);
       };
       window.addEventListener("resize", onWindowResize);
       addTeardown(() => {
@@ -9469,7 +9769,9 @@ const visibleRectEffect = (element, update) => {
     {
       const documentIntersectionObserver = new IntersectionObserver(
         () => {
-          autoCheck("element_intersection_with_document_change");
+          autoCheck(
+            new CustomEvent("element_intersection_with_document_change"),
+          );
         },
         {
           root: null,
@@ -9484,7 +9786,9 @@ const visibleRectEffect = (element, update) => {
       if (!scrollContainerIsDocument) {
         const scrollIntersectionObserver = new IntersectionObserver(
           () => {
-            autoCheck("element_intersection_with_scroll_change");
+            autoCheck(
+              new CustomEvent("element_intersection_with_scroll_change"),
+            );
           },
           {
             root: scrollContainer,
@@ -9499,8 +9803,8 @@ const visibleRectEffect = (element, update) => {
       }
     }
     {
-      const onWindowTouchMove = () => {
-        autoCheck("window_touchmove");
+      const onWindowTouchMove = (e) => {
+        autoCheck(e);
       };
       window.addEventListener("touchmove", onWindowTouchMove, {
         passive: true,
@@ -9522,14 +9826,50 @@ const visibleRectEffect = (element, update) => {
   };
 };
+/**
+ * Places element adjacent to anchor using one of 9 compass positions.
+ *
+ * ```
+ *   top-left  |   top   | top-right
+ *   ----------+---------+----------
+ *     left    |  center |   right
+ *   ----------+---------+----------
+ *  bottom-left|  bottom |bottom-right
+ * ```
+ *
+ * All positions except "center" place element outside the anchor:
+ *   - "top"          → element.bottom = anchor.top,    horizontally centered
+ *   - "bottom"       → element.top    = anchor.bottom, horizontally centered  (default)
+ *   - "left"         → element.right  = anchor.left,   vertically centered
+ *   - "right"        → element.left   = anchor.right,  vertically centered
+ *   - "top-left"     → element.bottom = anchor.top,    element.right = anchor.left
+ *   - "top-right"    → element.bottom = anchor.top,    element.left  = anchor.right
+ *   - "bottom-left"  → element.top    = anchor.bottom, element.right = anchor.left
+ *   - "bottom-right" → element.top    = anchor.bottom, element.left  = anchor.right
+ *   - "center"       → element centered on anchor (overlapping)
+ *
+ * @param {HTMLElement} element - The element to position (must be document-relative)
+ * @param {HTMLElement} anchor - The anchor element to position against
+ * @param {object} [options]
+ * @param {string} [options.positionTry="bottom"] - Preferred position. Mimics CSS position-try.
+ *   If it does not fit, the logical opposite is tried automatically:
+ *   top↔bottom, left↔right, top-left↔bottom-right, top-right↔bottom-left.
+ *   The element's data-position-try attribute takes precedence over this param;
+ *   the last resolved position is persisted as data-position-current to avoid flickering.
+ * @param {string} [options.position] - Force a specific position, skipping the fit-check.
+ * @param {number} [options.alignToViewportEdgeWhenAnchorNearEdge=0] - Snap to viewport left
+ *   edge when anchor is within this many px of the left edge and element is wider than anchor.
+ * @param {number} [options.minLeft=0] - Minimum left coordinate (document-relative).
+ * @returns {{ position, left, top, width, height, anchorLeft, anchorTop, anchorRight, anchorBottom, spaceAbove, spaceBelow }}
+ */
 const pickPositionRelativeTo = (
   element,
-  target,
+  anchor,
   {
-    alignToViewportEdgeWhenTargetNearEdge = 0,
+    positionTry = "bottom",
+    position,
+    alignToViewportEdgeWhenAnchorNearEdge = 0,
     minLeft = 0,
-    positionPreference,
-    forcePosition,
   } = {},
 ) => {
@@ -9537,7 +9877,7 @@ const pickPositionRelativeTo = (
   const viewportHeight = document.documentElement.clientHeight;
   // Get viewport-relative positions
   const elementRect = element.getBoundingClientRect();
-  const targetRect = target.getBoundingClientRect();
+  const anchorRect = anchor.getBoundingClientRect();
   const {
     left: elementLeft,
     right: elementRight,
@@ -9545,50 +9885,97 @@ const pickPositionRelativeTo = (
     bottom: elementBottom,
   } = elementRect;
   const {
-    left: targetLeft,
-    right: targetRight,
-    top: targetTop,
-    bottom: targetBottom,
-  } = targetRect;
+    left: anchorLeft,
+    right: anchorRight,
+    top: anchorTop,
+    bottom: anchorBottom,
+  } = anchorRect;
   const elementWidth = elementRight - elementLeft;
   const elementHeight = elementBottom - elementTop;
-  const targetWidth = targetRight - targetLeft;
+  const anchorWidth = anchorRight - anchorLeft;
+  const anchorHeight = anchorBottom - anchorTop;
+  // Determine the active position: position wins, then data-position-current (last resolved),
+  // then data-position-try attribute (user preference), then positionTry param
+  let activePosition;
+  if (position) {
+    activePosition = position;
+  } else {
+    const positionCurrentFromAttribute = element.getAttribute(
+      "data-position-current",
+    );
+    const positionTryFromAttribute = element.getAttribute("data-position-try");
+    activePosition =
+      positionCurrentFromAttribute || positionTryFromAttribute || positionTry;
+  }
+  const spaceAbove = anchorTop;
+  const spaceBelow = viewportHeight - anchorBottom;
+  // Resolve vertical axis, falling back to opposite if the tried position does not fit
+  const { isTop, isBottom, isLeft, isRight, isCenter } =
+    decomposePosition(activePosition);
+  const isCenterX = !isLeft && !isRight; // top / bottom / center
+  const isCenterY = !isTop && !isBottom; // left / right / center
+  let resolvedVertical; // "top" | "bottom" | "center-y"
+  if (isCenter || isCenterY) {
+    resolvedVertical = "center-y";
+  } else if (position) {
+    resolvedVertical = isTop ? "top" : "bottom";
+  } else if (isTop) {
+    const minContentVisibilityRatio = 0.6;
+    const fitsAbove = spaceAbove / elementHeight >= minContentVisibilityRatio;
+    if (fitsAbove) {
+      resolvedVertical = "top";
+    } else {
+      resolvedVertical = "bottom"; // opposite of top
+    }
+  } else {
+    // isBottom
+    const elementFitsBelow = spaceBelow >= elementHeight;
+    if (elementFitsBelow) {
+      resolvedVertical = "bottom";
+    } else {
+      resolvedVertical = "top"; // opposite of bottom
+    }
+  }
   // Calculate horizontal position (viewport-relative)
   let elementPositionLeft;
   {
-    // Check if target element is wider than viewport
-    const targetIsWiderThanViewport = targetWidth > viewportWidth;
-    if (targetIsWiderThanViewport) {
-      const targetLeftIsVisible = targetLeft >= 0;
-      const targetRightIsVisible = targetRight <= viewportWidth;
-      if (!targetLeftIsVisible && targetRightIsVisible) {
-        // Target extends beyond left edge but right side is visible
-        const viewportCenter = viewportWidth / 2;
-        const distanceFromRightEdge = viewportWidth - targetRight;
-        elementPositionLeft =
-          viewportCenter - distanceFromRightEdge / 2 - elementWidth / 2;
-      } else if (targetLeftIsVisible && !targetRightIsVisible) {
-        // Target extends beyond right edge but left side is visible
-        const viewportCenter = viewportWidth / 2;
-        const distanceFromLeftEdge = -targetLeft;
-        elementPositionLeft =
-          viewportCenter - distanceFromLeftEdge / 2 - elementWidth / 2;
-      } else {
-        // Target extends beyond both edges or is fully visible (center in viewport)
-        elementPositionLeft = viewportWidth / 2 - elementWidth / 2;
-      }
+    if (isLeft) {
+      elementPositionLeft = anchorLeft - elementWidth;
+    } else if (isRight) {
+      elementPositionLeft = anchorRight;
     } else {
-      // Target fits within viewport width - center element relative to target
-      elementPositionLeft = targetLeft + targetWidth / 2 - elementWidth / 2;
-      // Special handling when element is wider than target
-      if (alignToViewportEdgeWhenTargetNearEdge) {
-        const elementIsWiderThanTarget = elementWidth > targetWidth;
-        const targetIsNearLeftEdge =
-          targetLeft < alignToViewportEdgeWhenTargetNearEdge;
-        if (elementIsWiderThanTarget && targetIsNearLeftEdge) {
-          elementPositionLeft = minLeft; // Left edge of viewport
+      // centered horizontally on anchor
+      const anchorIsWiderThanViewport = anchorWidth > viewportWidth;
+      if (anchorIsWiderThanViewport) {
+        const anchorLeftIsVisible = anchorLeft >= 0;
+        const anchorRightIsVisible = anchorRight <= viewportWidth;
+        if (!anchorLeftIsVisible && anchorRightIsVisible) {
+          const viewportCenter = viewportWidth / 2;
+          const distanceFromRightEdge = viewportWidth - anchorRight;
+          elementPositionLeft =
+            viewportCenter - distanceFromRightEdge / 2 - elementWidth / 2;
+        } else if (anchorLeftIsVisible && !anchorRightIsVisible) {
+          const viewportCenter = viewportWidth / 2;
+          const distanceFromLeftEdge = -anchorLeft;
+          elementPositionLeft =
+            viewportCenter - distanceFromLeftEdge / 2 - elementWidth / 2;
+        } else {
+          elementPositionLeft = viewportWidth / 2 - elementWidth / 2;
+        }
+      } else {
+        elementPositionLeft = anchorLeft + anchorWidth / 2 - elementWidth / 2;
+        if (alignToViewportEdgeWhenAnchorNearEdge) {
+          const elementIsWiderThanAnchor = elementWidth > anchorWidth;
+          const anchorIsNearLeftEdge =
+            anchorLeft < alignToViewportEdgeWhenAnchorNearEdge;
+          if (elementIsWiderThanAnchor && anchorIsNearLeftEdge) {
+            elementPositionLeft = minLeft;
+          }
         }
       }
     }
@@ -9601,83 +9988,76 @@ const pickPositionRelativeTo = (
   }
   // Calculate vertical position (viewport-relative)
-  let position;
-  const spaceAboveTarget = targetTop;
-  const spaceBelowTarget = viewportHeight - targetBottom;
-  determine_position: {
-    if (forcePosition) {
-      position = forcePosition;
-      break determine_position;
-    }
-    const elementPreferredPosition = element.getAttribute("data-position");
-    const minContentVisibilityRatio = 0.6; // 60% minimum visibility to keep position
-    // Check positionPreference parameter first, then element attribute
-    const preferredPosition = positionPreference || elementPreferredPosition;
-    if (preferredPosition) {
-      // Element has a preferred position - try to keep it unless we really struggle
-      const visibleRatio =
-        preferredPosition === "above"
-          ? spaceAboveTarget / elementHeight
-          : spaceBelowTarget / elementHeight;
-      const canShowMinimumContent = visibleRatio >= minContentVisibilityRatio;
-      if (canShowMinimumContent) {
-        position = preferredPosition;
-        break determine_position;
-      }
-    }
-    // No preferred position - use original logic (prefer below, fallback to above if more space)
-    const elementFitsBelow = spaceBelowTarget >= elementHeight;
-    if (elementFitsBelow) {
-      position = "below";
-      break determine_position;
+  let elementPositionTop;
+  {
+    if (resolvedVertical === "center-y") {
+      elementPositionTop = anchorTop + anchorHeight / 2 - elementHeight / 2;
+    } else if (resolvedVertical === "bottom") {
+      const idealTop = anchorBottom;
+      elementPositionTop =
+        idealTop % 1 === 0 ? idealTop : Math.floor(idealTop) + 1;
+    } else {
+      // "top"
+      const idealTop = anchorTop - elementHeight;
+      elementPositionTop = idealTop < 0 ? 0 : idealTop;
     }
-    const hasMoreSpaceBelow = spaceBelowTarget >= spaceAboveTarget;
-    position = hasMoreSpaceBelow ? "below" : "above";
   }
-  let elementPositionTop;
+  let finalPosition;
   {
-    if (position === "below") {
-      // Calculate top position when placing below target (ensure whole pixels)
-      const idealTopWhenBelow = targetBottom;
-      elementPositionTop =
-        idealTopWhenBelow % 1 === 0
-          ? idealTopWhenBelow
-          : Math.floor(idealTopWhenBelow) + 1;
+    const vertPart = resolvedVertical === "center-y" ? "" : resolvedVertical;
+    const horzPart = isCenterX ? "" : isLeft ? "left" : "right";
+    if (vertPart && horzPart) {
+      finalPosition = `${vertPart}-${horzPart}`;
+    } else if (vertPart) {
+      finalPosition = vertPart;
+    } else if (horzPart) {
+      finalPosition = horzPart;
     } else {
-      // Calculate top position when placing above target
-      const idealTopWhenAbove = targetTop - elementHeight;
-      const minimumTopInViewport = 0;
-      elementPositionTop =
-        idealTopWhenAbove < minimumTopInViewport
-          ? minimumTopInViewport
-          : idealTopWhenAbove;
+      finalPosition = "center";
     }
   }
+  // Persist the resolved position on the element so subsequent calls start from it
+  // (avoids flickering between positions when the element is near the threshold).
+  // position is not persisted — it is always explicit.
+  if (!position) {
+    element.setAttribute("data-position-current", finalPosition);
+  }
   // Get document scroll for final coordinate conversion
   const { scrollLeft, scrollTop } = document.documentElement;
   const elementDocumentLeft = elementPositionLeft + scrollLeft;
   const elementDocumentTop = elementPositionTop + scrollTop;
-  const targetDocumentLeft = targetLeft + scrollLeft;
-  const targetDocumentTop = targetTop + scrollTop;
-  const targetDocumentRight = targetRight + scrollLeft;
-  const targetDocumentBottom = targetBottom + scrollTop;
+  const anchorDocumentLeft = anchorLeft + scrollLeft;
+  const anchorDocumentTop = anchorTop + scrollTop;
+  const anchorDocumentRight = anchorRight + scrollLeft;
+  const anchorDocumentBottom = anchorBottom + scrollTop;
   return {
-    position,
+    position: finalPosition,
     left: elementDocumentLeft,
     top: elementDocumentTop,
     width: elementWidth,
     height: elementHeight,
-    targetLeft: targetDocumentLeft,
-    targetTop: targetDocumentTop,
-    targetRight: targetDocumentRight,
-    targetBottom: targetDocumentBottom,
-    spaceAboveTarget,
-    spaceBelowTarget,
+    anchorLeft: anchorDocumentLeft,
+    anchorTop: anchorDocumentTop,
+    anchorRight: anchorDocumentRight,
+    anchorBottom: anchorDocumentBottom,
+    spaceAbove,
+    spaceBelow,
+  };
+};
+// Decompose position flags
+const decomposePosition = (pos) => {
+  return {
+    isTop: pos === "top" || pos === "top-left" || pos === "top-right",
+    isBottom:
+      pos === "bottom" || pos === "bottom-left" || pos === "bottom-right",
+    isLeft: pos === "left" || pos === "top-left" || pos === "bottom-left",
+    isRight: pos === "right" || pos === "top-right" || pos === "bottom-right",
+    isCenter: pos === "center",
   };
 };
@@ -12804,4 +13184,4 @@ const useResizeStatus = (elementRef, { as = "number" } = {}) => {
   };
 };
-export { EASING, activeElementSignal, addActiveElementEffect, addAttributeEffect, allowWheelThrough, appendStyles, canInterceptKeys, captureScrollState, contrastColor, createBackgroundColorTransition, createBackgroundTransition, createBorderRadiusTransition, createBorderTransition, createDragGestureController, createDragToMoveGestureController, createGroupTransitionController, createHeightTransition, createIterableWeakSet, createOpacityTransition, createPubSub, createStyleController, createTimelineTransition, createTransition, createTranslateXTransition, createValueEffect, createWidthTransition, cubicBezier, dragAfterThreshold, elementIsFocusable, elementIsVisibleForFocus, elementIsVisuallyVisible, findAfter, findAncestor, findBefore, findDescendant, findFocusable, getAvailableHeight, getAvailableWidth, getBackground, getBackgroundColor, getBorder, getBorderRadius, getBorderSizes, getContrastRatio, getDefaultStyles, getDragCoordinates, getDropTargetInfo, getElementSignature, getFirstVisuallyVisibleAncestor, getFocusVisibilityInfo, getHeight, getHeightWithoutTransition, getInnerHeight, getInnerWidth, getLuminance, getMarginSizes, getMaxHeight, getMaxWidth, getMinHeight, getMinWidth, getOpacity, getOpacityWithoutTransition, getPaddingSizes, getPositionedParent, getPreferedColorScheme, getScrollBox, getScrollContainer, getScrollContainerSet, getScrollRelativeRect, getSelfAndAncestorScrolls, getStyle, getTranslateX, getTranslateXWithoutTransition, getTranslateY, getVisuallyVisibleInfo, getWidth, getWidthWithoutTransition, hasCSSSizeUnit, initFlexDetailsSet, initFocusGroup, initPositionSticky, isSameColor, isScrollable, measureScrollbar, mergeOneStyle, mergeTwoStyles, normalizeStyles, parseStyle, pickPositionRelativeTo, prefersDarkColors, prefersLightColors, preventFocusNav, preventFocusNavViaKeyboard, preventIntermediateScrollbar, resolveCSSColor, resolveCSSSize, resolveColorLuminance, setAttribute, setAttributes, setStyles, startDragToResizeGesture, stickyAsRelativeCoords, stringifyStyle, trapFocusInside, trapScrollInside, useActiveElement, useAvailableHeight, useAvailableWidth, useMaxHeight, useMaxWidth, useResizeStatus, visibleRectEffect };
+export { EASING, activeElementSignal, addActiveElementEffect, addAttributeEffect, allowWheelThrough, appendStyles, canInterceptKeys, captureScrollState, contrastColor, createBackgroundColorTransition, createBackgroundTransition, createBorderRadiusTransition, createBorderTransition, createDragGestureController, createDragToMoveGestureController, createGroupTransitionController, createHeightTransition, createIterableWeakSet, createOpacityTransition, createPubSub, createStyleController, createTimelineTransition, createTransition, createTranslateXTransition, createValueEffect, createWidthTransition, cubicBezier, dragAfterThreshold, elementIsFocusable, elementIsVisibleForFocus, elementIsVisuallyVisible, findAfter, findAncestor, findBefore, findDescendant, findFocusable, getAvailableHeight, getAvailableWidth, getBackground, getBackgroundColor, getBorder, getBorderRadius, getBorderSizes, getContrastRatio, getDefaultStyles, getDragCoordinates, getDropTargetInfo, getElementSignature, getFirstVisuallyVisibleAncestor, getFocusVisibilityInfo, getHeight, getHeightWithoutTransition, getInnerHeight, getInnerWidth, getLuminance, getMarginSizes, getMaxHeight, getMaxWidth, getMinHeight, getMinWidth, getOpacity, getOpacityWithoutTransition, getPaddingSizes, getPositionedParent, getPreferedColorScheme, getScrollBox, getScrollContainer, getScrollContainerSet, getScrollRelativeRect, getSelfAndAncestorScrolls, getStyle, getTranslateX, getTranslateXWithoutTransition, getTranslateY, getVisuallyVisibleInfo, getWidth, getWidthWithoutTransition, hasCSSSizeUnit, initFlexDetailsSet, initFocusGroup, initPositionSticky, isSameColor, isScrollable, measureScrollbar, mergeOneStyle, mergeTwoStyles, normalizeStyles, parseStyle, pickPositionRelativeTo, prefersDarkColors, prefersLightColors, preventFocusNav, preventFocusNavViaKeyboard, preventIntermediateScrollbar, resolveCSSColor, resolveCSSSize, resolveColorLuminance, scrollIntoViewScoped, scrollIntoViewWithStickyAwareness, setAttribute, setAttributes, setStyles, startDragToResizeGesture, stickyAsRelativeCoords, stringifyStyle, trapFocusInside, trapScrollInside, useActiveElement, useAvailableHeight, useAvailableWidth, useMaxHeight, useMaxWidth, useResizeStatus, visibleRectEffect };

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/dom",
-  "version": "0.9.5",
+  "version": "0.10.1",
   "type": "module",
   "description": "DOM utilities for writing frontend code",
   "repository": {
@@ -40,7 +40,7 @@
     "@jsenv/navi": "../navi",
     "@jsenv/snapshot": "../../tooling/snapshot",
     "@preact/signals": "2.9.0",
-    "preact": "11.0.0-beta.0"
+    "preact": "11.0.0-beta.1"
   },
   "publishConfig": {
     "access": "public"