@jsenv/dom 0.10.2 → 0.10.3

package/dist/jsenv_dom.js

@@ -1908,6 +1908,8 @@ const pxPropertySet = new Set([
   "paddingRight",
   "paddingBottom",
   "paddingLeft",
+  "outlineWidth",
+  "outlineOffset",
   "borderWidth",
   "borderTopWidth",
   "borderRightWidth",
@@ -6131,10 +6133,10 @@ const trapScrollInside = (element) => {
     }
     const [scrollbarWidth, scrollbarHeight] = measureScrollbar(el);
     const paddingRight = parseInt(getStyle(el, "padding-right"), 0);
-    const paddingTop = parseInt(getStyle(el, "padding-top"), 0);
+    const paddingBottom = parseInt(getStyle(el, "padding-bottom"), 0);
     const removeScrollLockStyles = setStyles(el, {
       "padding-right": `${paddingRight + scrollbarWidth}px`,
-      "padding-top": `${paddingTop + scrollbarHeight}px`,
+      "padding-bottom": `${paddingBottom + scrollbarHeight}px`,
       "overflow": "hidden",
     });
     cleanupCallbackSet.add(removeScrollLockStyles);
@@ -9575,6 +9577,10 @@ const stickyAsRelativeCoords = (
   return [leftPosition, topPosition];
 };
 
+// Minimum fraction of element width/height that must be visible on the preferred side
+// before flipping to the opposite side. Prevents flickering near the flip threshold.
+const MIN_CONTENT_VISIBILITY_RATIO = 0.6;
+
 /**
  * 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
@@ -9876,47 +9882,52 @@ const visibleRectEffect = (element, update) => {
 };
 
 /**
- * Places element adjacent to anchor using one of 9 compass positions.
+ * Places element relative to anchor with independent control of horizontal and vertical axes.
  *
- * ```
- *   top-left  |   top   | top-right
- *   ----------+---------+----------
- *     left    |  center |   right
- *   ----------+---------+----------
- *  bottom-left|  bottom |bottom-right
- * ```
+ * Horizontal axis — positionX / positionXFixed (left → right):
+ *   "to-the-left"   element.right  = anchor.left   (sits entirely to the left of anchor)
+ *   "left-aligned"  element.left   = anchor.left   (left edges aligned)
+ *   "center"        element centered horizontally over anchor  (default)
+ *   "right-aligned" element.right  = anchor.right  (right edges aligned)
+ *   "to-the-right"  element.left   = anchor.right  (sits entirely to the right of anchor)
+ *
+ * Vertical axis — positionY / positionYFixed (top → bottom):
+ *   "above"         element.bottom = anchor.top    (sits above, no overlap)
+ *   "above-overlap" element.bottom = anchor.bottom (sits above, overlapping anchor)
+ *   "center"        element centered vertically over anchor
+ *   "below-overlap" element.top    = anchor.top    (sits below, overlapping anchor)
+ *   "below"         element.top    = anchor.bottom (sits below, no overlap)  (default)
  *
- * 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)
+ * positionX / positionY attempt the requested placement and automatically flip to the
+ * logical opposite when the element does not fit in the viewport:
+ *   above ↔ below,   above-overlap ↔ below-overlap
+ *
+ * positionXFixed / positionYFixed skip the fit check entirely.
+ *
+ * The resolved X and Y are persisted as data-position-x-current / data-position-y-current
+ * on the element so subsequent calls start from the last resolved position (avoids
+ * flickering when the element is near the flip threshold). Fixed axes are not persisted.
  *
  * @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 {string} [options.positionX="center"] - Preferred X placement, with viewport fallback.
+ * @param {string} [options.positionY="below"] - Preferred Y placement, with viewport fallback.
+ * @param {string} [options.positionXFixed] - Force X placement, skipping the fit-check.
+ * @param {string} [options.positionYFixed] - Force Y placement, 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 }}
+ * @returns {{ positionX, positionY, left, top, width, height, anchorLeft, anchorTop, anchorRight, anchorBottom, spaceLeft, spaceRight, spaceAbove, spaceBelow }}
  */
 const pickPositionRelativeTo = (
   element,
   anchor,
   {
-    positionTry = "bottom",
-    position,
+    positionX = "center",
+    positionY = "below",
+    positionXFixed,
+    positionYFixed,
     alignToViewportEdgeWhenAnchorNearEdge = 0,
     minLeft = 0,
   } = {},
@@ -9944,61 +9955,151 @@ const pickPositionRelativeTo = (
   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;
+  const spaceLeft = anchorLeft;
+  const spaceRight = viewportWidth - anchorRight;
+
+  // Resolve active X and Y, and whether each is fixed (no flip fallback)
+  let activeX;
+  let activeY;
+  const xIsFixed = Boolean(positionXFixed);
+  const yIsFixed = Boolean(positionYFixed);
+  const hasStoredY = Boolean(element.getAttribute("data-position-y-current"));
+  const hasStoredX = Boolean(element.getAttribute("data-position-x-current"));
+  if (xIsFixed) {
+    activeX = positionXFixed;
+  } else {
+    const storedX = element.getAttribute("data-position-x-current");
+    activeX = storedX ?? positionX;
+  }
+  if (yIsFixed) {
+    activeY = positionYFixed;
+  } else {
+    const storedY = element.getAttribute("data-position-y-current");
+    activeY = storedY ?? positionY;
+  }
 
-  // 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";
+  // Resolve final Y
+  let finalY;
+  {
+    const oppositeY = {
+      "above": "below",
+      "below": "above",
+      "above-overlap": "below-overlap",
+      "below-overlap": "above-overlap",
+    };
+    // Compute effective space for a given Y value
+    const spaceFor = (y) => {
+      if (y === "above") {
+        return spaceAbove;
+      }
+      if (y === "above-overlap") {
+        return spaceAbove + anchorHeight;
+      }
+      if (y === "below") {
+        return spaceBelow;
+      }
+      if (y === "below-overlap") {
+        return spaceBelow + anchorHeight;
+      }
+      return Infinity; // center
+    };
+    if (yIsFixed || activeY === "center") {
+      finalY = activeY;
+    } else if (!hasStoredY) {
+      // Never positioned before — pick the best side from scratch.
+      const preferred = positionY;
+      const opposite = oppositeY[preferred];
+      const preferredFits = spaceFor(preferred) >= elementHeight;
+      const oppositeFits = spaceFor(opposite) >= elementHeight;
+      if (preferredFits) {
+        // Preferred fits completely — use it (even if opposite also fits)
+        finalY = preferred;
+      } else if (oppositeFits) {
+        // Only opposite fits completely — flip
+        finalY = opposite;
+      } else {
+        // Neither fits completely — use whichever meets the minimum ratio
+        const preferredMeetsRatio =
+          spaceFor(preferred) / elementHeight >= MIN_CONTENT_VISIBILITY_RATIO;
+        finalY = preferredMeetsRatio ? preferred : opposite;
+      }
     } else {
-      resolvedVertical = "bottom"; // opposite of top
+      // Previously positioned — stay as long as current side meets minimum ratio
+      const currentFitsEnough =
+        spaceFor(activeY) / elementHeight >= MIN_CONTENT_VISIBILITY_RATIO;
+      if (currentFitsEnough) {
+        finalY = activeY;
+      } else {
+        finalY = oppositeY[activeY];
+      }
     }
-  } else {
-    // isBottom
-    const elementFitsBelow = spaceBelow >= elementHeight;
-    if (elementFitsBelow) {
-      resolvedVertical = "bottom";
+  }
+
+  // Resolve final X
+  let finalX;
+  {
+    const oppositeX = {
+      "to-the-left": "to-the-right",
+      "to-the-right": "to-the-left",
+      "left-aligned": "right-aligned",
+      "right-aligned": "left-aligned",
+    };
+    // Compute effective space for a given X value
+    const spaceFor = (x) => {
+      if (x === "to-the-left") {
+        return spaceLeft;
+      }
+      if (x === "left-aligned") {
+        return viewportWidth - anchorLeft;
+      }
+      if (x === "right-aligned") {
+        return anchorRight;
+      }
+      if (x === "to-the-right") {
+        return spaceRight;
+      }
+      return Infinity; // center
+    };
+    if (xIsFixed || activeX === "center") {
+      finalX = activeX;
+    } else if (!hasStoredX) {
+      // Never positioned before — pick the best side from scratch.
+      const preferred = positionX;
+      const opposite = oppositeX[preferred];
+      const preferredFits = spaceFor(preferred) >= elementWidth;
+      const oppositeFits = spaceFor(opposite) >= elementWidth;
+      if (preferredFits) {
+        finalX = preferred;
+      } else if (oppositeFits) {
+        finalX = opposite;
+      } else {
+        const preferredMeetsRatio =
+          spaceFor(preferred) / elementWidth >= MIN_CONTENT_VISIBILITY_RATIO;
+        finalX = preferredMeetsRatio ? preferred : opposite;
+      }
     } else {
-      resolvedVertical = "top"; // opposite of bottom
+      // Previously positioned — stay as long as current side meets minimum ratio
+      const currentFitsEnough =
+        spaceFor(activeX) / elementWidth >= MIN_CONTENT_VISIBILITY_RATIO;
+      if (currentFitsEnough) {
+        finalX = activeX;
+      } else {
+        finalX = oppositeX[activeX];
+      }
     }
   }
 
   // Calculate horizontal position (viewport-relative)
   let elementPositionLeft;
   {
-    if (isLeft) {
+    if (finalX === "to-the-left") {
       elementPositionLeft = anchorLeft - elementWidth;
-    } else if (isRight) {
-      elementPositionLeft = anchorRight;
-    } else {
-      // centered horizontally on anchor
+    } else if (finalX === "left-aligned") {
+      elementPositionLeft = anchorLeft;
+    } else if (finalX === "center") {
+      // Complex logic handles wide anchors and viewport-edge snapping
       const anchorIsWiderThanViewport = anchorWidth > viewportWidth;
       if (anchorIsWiderThanViewport) {
         const anchorLeftIsVisible = anchorLeft >= 0;
@@ -10027,6 +10128,11 @@ const pickPositionRelativeTo = (
           }
         }
       }
+    } else if (finalX === "right-aligned") {
+      elementPositionLeft = anchorRight - elementWidth;
+    } else {
+      // "to-the-right"
+      elementPositionLeft = anchorRight;
     }
     // Constrain horizontal position to viewport boundaries
     if (elementPositionLeft < 0) {
@@ -10039,40 +10145,33 @@ const pickPositionRelativeTo = (
   // Calculate vertical position (viewport-relative)
   let elementPositionTop;
   {
-    if (resolvedVertical === "center-y") {
+    if (finalY === "above") {
+      const idealTop = anchorTop - elementHeight;
+      elementPositionTop = idealTop < 0 ? 0 : idealTop;
+    } else if (finalY === "above-overlap") {
+      const idealTop = anchorBottom - elementHeight;
+      elementPositionTop = idealTop < 0 ? 0 : idealTop;
+    } else if (finalY === "center") {
       elementPositionTop = anchorTop + anchorHeight / 2 - elementHeight / 2;
-    } else if (resolvedVertical === "bottom") {
-      const idealTop = anchorBottom;
+    } else if (finalY === "below-overlap") {
+      const idealTop = anchorTop;
       elementPositionTop =
         idealTop % 1 === 0 ? idealTop : Math.floor(idealTop) + 1;
     } else {
-      // "top"
-      const idealTop = anchorTop - elementHeight;
-      elementPositionTop = idealTop < 0 ? 0 : idealTop;
+      // "below"
+      const idealTop = anchorBottom;
+      elementPositionTop =
+        idealTop % 1 === 0 ? idealTop : Math.floor(idealTop) + 1;
     }
   }
 
-  let finalPosition;
-  {
-    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 {
-      finalPosition = "center";
-    }
+  // Persist resolved X/Y so subsequent calls start from here (avoids flickering).
+  // Fixed axes are not persisted.
+  if (!xIsFixed) {
+    element.setAttribute("data-position-x-current", finalX);
   }
-
-  // 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);
+  if (!yIsFixed) {
+    element.setAttribute("data-position-y-current", finalY);
   }
 
   // Get document scroll for final coordinate conversion
@@ -10085,7 +10184,8 @@ const pickPositionRelativeTo = (
   const anchorDocumentBottom = anchorBottom + scrollTop;
 
   return {
-    position: finalPosition,
+    positionX: finalX,
+    positionY: finalY,
     left: elementDocumentLeft,
     top: elementDocumentTop,
     width: elementWidth,
@@ -10094,21 +10194,12 @@ const pickPositionRelativeTo = (
     anchorTop: anchorDocumentTop,
     anchorRight: anchorDocumentRight,
     anchorBottom: anchorDocumentBottom,
+    spaceLeft,
+    spaceRight,
     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",
-  };
-};
 
 const [publishDebugger, subscribeDebugger] = createPubSub();
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/dom",
-  "version": "0.10.2",
+  "version": "0.10.3",
   "type": "module",
   "description": "DOM utilities for writing frontend code",
   "repository": {