@jsenv/dom 0.1.0

package/src/position/visible_rect.js

@@ -0,0 +1,482 @@
+import { getScrollContainer } from "../interaction/scroll/scroll_container.js";
+import { createPubSub } from "../pub_sub.js";
+
+const DEBUG = false;
+
+// 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
+export const visibleRectEffect = (element, update) => {
+  const [teardown, addTeardown] = createPubSub();
+  const scrollContainer = getScrollContainer(element);
+  const scrollContainerIsDocument =
+    scrollContainer === document.documentElement;
+  let lastMeasuredWidth;
+  let lastMeasuredHeight;
+  const check = (reason) => {
+    if (DEBUG) {
+      console.group(`visibleRect.check("${reason}")`);
+    }
+
+    // 1. Calculate element position relative to scrollable parent
+    const { scrollLeft, scrollTop } = scrollContainer;
+    const visibleAreaLeft = scrollLeft;
+    const visibleAreaTop = scrollTop;
+
+    // Get element position relative to its scrollable parent
+    let elementAbsoluteLeft;
+    let elementAbsoluteTop;
+    if (scrollContainerIsDocument) {
+      // For document scrolling, use offsetLeft/offsetTop relative to document
+      const rect = element.getBoundingClientRect();
+      elementAbsoluteLeft = rect.left + scrollLeft;
+      elementAbsoluteTop = rect.top + scrollTop;
+    } else {
+      // For custom container, get position relative to the container
+      const elementRect = element.getBoundingClientRect();
+      const scrollContainerRect = scrollContainer.getBoundingClientRect();
+      elementAbsoluteLeft =
+        elementRect.left - scrollContainerRect.left + scrollLeft;
+      elementAbsoluteTop =
+        elementRect.top - scrollContainerRect.top + scrollTop;
+    }
+
+    const leftVisible =
+      visibleAreaLeft < elementAbsoluteLeft
+        ? elementAbsoluteLeft - visibleAreaLeft
+        : 0;
+    const topVisible =
+      visibleAreaTop < elementAbsoluteTop
+        ? elementAbsoluteTop - visibleAreaTop
+        : 0;
+    // Convert to overlay coordinates (adjust for custom scrollable container)
+    let overlayLeft = leftVisible;
+    let overlayTop = topVisible;
+    if (!scrollContainerIsDocument) {
+      const { left: scrollableLeft, top: scrollableTop } =
+        scrollContainer.getBoundingClientRect();
+      overlayLeft += scrollableLeft;
+      overlayTop += scrollableTop;
+    }
+
+    // 2. Calculate element visible width/height
+    const { width, height } = element.getBoundingClientRect();
+    lastMeasuredWidth = width;
+    lastMeasuredHeight = height;
+    const visibleAreaWidth = scrollContainer.clientWidth;
+    const visibleAreaHeight = scrollContainer.clientHeight;
+    const visibleAreaRight = visibleAreaLeft + visibleAreaWidth;
+    const visibleAreaBottom = visibleAreaTop + visibleAreaHeight;
+    // 2.1 Calculate visible width
+    let widthVisible;
+    {
+      const maxVisibleWidth = visibleAreaWidth - leftVisible;
+      const elementAbsoluteRight = elementAbsoluteLeft + width;
+      const elementLeftIsVisible = elementAbsoluteLeft >= visibleAreaLeft;
+      const elementRightIsVisible = elementAbsoluteRight <= visibleAreaRight;
+      if (elementLeftIsVisible && elementRightIsVisible) {
+        // Element fully visible horizontally
+        widthVisible = width;
+      } else if (elementLeftIsVisible && !elementRightIsVisible) {
+        // Element left is visible, right is cut off
+        widthVisible = visibleAreaRight - elementAbsoluteLeft;
+      } else if (!elementLeftIsVisible && elementRightIsVisible) {
+        // Element left is cut off, right is visible
+        widthVisible = elementAbsoluteRight - visibleAreaLeft;
+      } else {
+        // Element spans beyond both sides, show only visible area portion
+        widthVisible = maxVisibleWidth;
+      }
+    }
+    // 2.2 Calculate visible height
+    let heightVisible;
+    {
+      const maxVisibleHeight = visibleAreaHeight - topVisible;
+      const elementAbsoluteBottom = elementAbsoluteTop + height;
+      const elementTopIsVisible = elementAbsoluteTop >= visibleAreaTop;
+      const elementBottomIsVisible = elementAbsoluteBottom <= visibleAreaBottom;
+      if (elementTopIsVisible && elementBottomIsVisible) {
+        // Element fully visible vertically
+        heightVisible = height;
+      } else if (elementTopIsVisible && !elementBottomIsVisible) {
+        // Element top is visible, bottom is cut off
+        heightVisible = visibleAreaBottom - elementAbsoluteTop;
+      } else if (!elementTopIsVisible && elementBottomIsVisible) {
+        // Element top is cut off, bottom is visible
+        heightVisible = elementAbsoluteBottom - visibleAreaTop;
+      } else {
+        // Element spans beyond both sides, show only visible area portion
+        heightVisible = maxVisibleHeight;
+      }
+    }
+
+    // Calculate visibility ratios
+    const scrollVisibilityRatio =
+      (widthVisible * heightVisible) / (width * height);
+    // Calculate visibility ratio relative to document viewport
+    let documentVisibilityRatio;
+    if (scrollContainerIsDocument) {
+      documentVisibilityRatio = scrollVisibilityRatio;
+    } else {
+      // For custom containers, calculate visibility relative to document viewport
+      const elementRect = element.getBoundingClientRect();
+      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);
+    }
+
+    const visibleRect = {
+      left: overlayLeft,
+      top: overlayTop,
+      right: overlayLeft + widthVisible,
+      bottom: overlayTop + heightVisible,
+      width: widthVisible,
+      height: heightVisible,
+      visibilityRatio: documentVisibilityRatio,
+      scrollVisibilityRatio,
+    };
+
+    if (DEBUG) {
+      console.log(`update(${JSON.stringify(visibleRect, null, "  ")})`);
+      console.groupEnd();
+    }
+    update(visibleRect, {
+      width,
+      height,
+    });
+  };
+
+  check("initialization");
+
+  const [publishBeforeAutoCheck, onBeforeAutoCheck] = createPubSub();
+  auto_check: {
+    const autoCheck = (reason) => {
+      const beforeCheckResults = publishBeforeAutoCheck(reason);
+      check(reason);
+      for (const beforeCheckResult of beforeCheckResults) {
+        if (typeof beforeCheckResult === "function") {
+          beforeCheckResult();
+        }
+      }
+    };
+    // let rafId = null;
+    // const scheduleCheck = (reason) => {
+    //   cancelAnimationFrame(rafId);
+    //   rafId = requestAnimationFrame(() => {
+    //     autoCheck(reason);
+    //   });
+    // };
+    // addTeardown(() => {
+    //   cancelAnimationFrame(rafId);
+    // });
+
+    on_scroll: {
+      // 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");
+      };
+      document.addEventListener("scroll", onDocumentScroll, {
+        passive: true,
+      });
+      addTeardown(() => {
+        document.removeEventListener("scroll", onDocumentScroll, {
+          passive: true,
+        });
+      });
+      if (!scrollContainerIsDocument) {
+        const onScroll = () => {
+          autoCheck("scrollable_parent_scroll");
+        };
+        scrollContainer.addEventListener("scroll", onScroll, {
+          passive: true,
+        });
+        addTeardown(() => {
+          scrollContainer.removeEventListener("scroll", onScroll, {
+            passive: true,
+          });
+        });
+      }
+    }
+    on_window_resize: {
+      const onWindowResize = () => {
+        autoCheck("window_size_change");
+      };
+      window.addEventListener("resize", onWindowResize);
+      addTeardown(() => {
+        window.removeEventListener("resize", onWindowResize);
+      });
+    }
+    on_element_resize: {
+      let handlingResize = true;
+      const resizeObserver = new ResizeObserver(() => {
+        if (handlingResize) {
+          return;
+        }
+        // we use directly the result of getBoundingClientRect() instead of the resizeEntry.contentRect or resizeEntry.borderBoxSize
+        // so that:
+        // - We can compare the dimensions measure in the last check and the current one
+        // - We don't have to check element boz-sizing to know what to compare
+        // - resizeEntry.borderBoxSize browser support is not that great
+        const { width, height } = element.getBoundingClientRect();
+        const widthDiff = Math.abs(width - lastMeasuredWidth);
+        const heightDiff = Math.abs(height - lastMeasuredHeight);
+        if (widthDiff === 0 && heightDiff === 0) {
+          return;
+        }
+        handlingResize = true;
+        autoCheck(`element_size_change (${width}x${height})`);
+        handlingResize = false;
+      });
+      resizeObserver.observe(element);
+      // Temporarily disconnect ResizeObserver to prevent feedback loops eventually caused by update function
+      onBeforeAutoCheck(() => {
+        resizeObserver.unobserve(element);
+        return () => {
+          // This triggers a new call to the resive observer that will be ignored thanks to
+          // the widthDiff/heightDiff early return
+          resizeObserver.observe(element);
+        };
+      });
+      addTeardown(() => {
+        resizeObserver.disconnect();
+      });
+    }
+    on_intersection_change: {
+      const documentIntersectionObserver = new IntersectionObserver(
+        () => {
+          autoCheck("element_intersection_with_document_change");
+        },
+        {
+          root: null,
+          rootMargin: "0px",
+          threshold: [0, 0.1, 0.9, 1],
+        },
+      );
+      documentIntersectionObserver.observe(element);
+      addTeardown(() => {
+        documentIntersectionObserver.disconnect();
+      });
+      if (!scrollContainerIsDocument) {
+        const scrollIntersectionObserver = new IntersectionObserver(
+          () => {
+            autoCheck("element_intersection_with_scroll_change");
+          },
+          {
+            root: scrollContainer,
+            rootMargin: "0px",
+            threshold: [0, 0, 1, 0.9, 1],
+          },
+        );
+        scrollIntersectionObserver.observe(element);
+        addTeardown(() => {
+          scrollIntersectionObserver.disconnect();
+        });
+      }
+    }
+    on_window_touchmove: {
+      const onWindowTouchMove = () => {
+        autoCheck("window_touchmove");
+      };
+      window.addEventListener("touchmove", onWindowTouchMove, {
+        passive: true,
+      });
+      addTeardown(() => {
+        window.removeEventListener("touchmove", onWindowTouchMove, {
+          passive: true,
+        });
+      });
+    }
+  }
+
+  return {
+    check,
+    onBeforeAutoCheck,
+    disconnect: () => {
+      teardown();
+    },
+  };
+};
+
+export const pickPositionRelativeTo = (
+  element,
+  target,
+  { alignToViewportEdgeWhenTargetNearEdge = 0, forcePosition } = {},
+) => {
+  if (
+    import.meta.dev &&
+    getScrollContainer(element) !== document.documentElement
+  ) {
+    // The idea behind this warning is that pickPositionRelativeTo is meant to position a tooltip/dropdown etc
+    // And for this use case the element to position should be document-relative
+    // (position: absolute with first scrollable parent being the document)
+    // Because this is how you achieve the best results:
+    // 1. The element naturally follow document scroll
+    // Which gives the best experience when user scrolls the page or the container
+    // 2. The element can take more visible size in case target is within a scrollable container
+    // or uses overflow: hidden somewhere in its ancestor chain
+    console.warn(
+      "pickPositionRelativeTo should be used only for document-relative element",
+    );
+  }
+
+  const viewportWidth = document.documentElement.clientWidth;
+  const viewportHeight = document.documentElement.clientHeight;
+  // Get viewport-relative positions
+  const elementRect = element.getBoundingClientRect();
+  const targetRect = target.getBoundingClientRect();
+  const {
+    left: elementLeft,
+    right: elementRight,
+    top: elementTop,
+    bottom: elementBottom,
+  } = elementRect;
+  const {
+    left: targetLeft,
+    right: targetRight,
+    top: targetTop,
+    bottom: targetBottom,
+  } = targetRect;
+  const elementWidth = elementRight - elementLeft;
+  const elementHeight = elementBottom - elementTop;
+  const targetWidth = targetRight - targetLeft;
+
+  // 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;
+      }
+    } 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 = 0; // Left edge of viewport
+        }
+      }
+    }
+    // Constrain horizontal position to viewport boundaries
+    if (elementPositionLeft < 0) {
+      elementPositionLeft = 0;
+    } else if (elementPositionLeft + elementWidth > viewportWidth) {
+      elementPositionLeft = viewportWidth - elementWidth;
+    }
+  }
+
+  // Calculate vertical position (viewport-relative)
+  let position;
+  const spaceAboveTarget = targetTop;
+  const spaceBelowTarget = viewportHeight - targetBottom;
+  determine_position: {
+    if (forcePosition) {
+      position = forcePosition;
+      break determine_position;
+    }
+    const preferredPosition = element.getAttribute("data-position");
+    const minContentVisibilityRatio = 0.6; // 60% minimum visibility to keep position
+    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;
+    }
+    const hasMoreSpaceBelow = spaceBelowTarget >= spaceAboveTarget;
+    position = hasMoreSpaceBelow ? "below" : "above";
+  }
+
+  let elementPositionTop;
+  {
+    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;
+    } else {
+      // Calculate top position when placing above target
+      const idealTopWhenAbove = targetTop - elementHeight;
+      const minimumTopInViewport = 0;
+      elementPositionTop =
+        idealTopWhenAbove < minimumTopInViewport
+          ? minimumTopInViewport
+          : idealTopWhenAbove;
+    }
+  }
+
+  // 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;
+
+  return {
+    position,
+    left: elementDocumentLeft,
+    top: elementDocumentTop,
+    width: elementWidth,
+    height: elementHeight,
+    targetLeft: targetDocumentLeft,
+    targetTop: targetDocumentTop,
+    targetRight: targetDocumentRight,
+    targetBottom: targetDocumentBottom,
+    spaceAboveTarget,
+    spaceBelowTarget,
+  };
+};

package/src/pub_sub.js

@@ -0,0 +1,28 @@
+export const createPubSub = () => {
+  const callbackSet = new Set();
+
+  const publish = (...args) => {
+    const results = [];
+    for (const callback of callbackSet) {
+      const result = callback(...args);
+      results.push(result);
+    }
+    return results;
+  };
+
+  const subscribe = (callback) => {
+    if (typeof callback !== "function") {
+      throw new TypeError("callback must be a function");
+    }
+    callbackSet.add(callback);
+    return () => {
+      callbackSet.delete(callback);
+    };
+  };
+
+  const clear = () => {
+    callbackSet.clear();
+  };
+
+  return [publish, subscribe, clear];
+};

package/src/size/can_take_size.js

@@ -0,0 +1,11 @@
+export const canTakeSize = (element) => {
+  const computedStyle = window.getComputedStyle(element);
+
+  if (computedStyle.display === "none") {
+    return false;
+  }
+  if (computedStyle.position === "absolute") {
+    return false;
+  }
+  return true;
+};

package/src/size/details_content_full_height.js

@@ -0,0 +1,63 @@
+import { addAttributeEffect } from "../attr/add_attribute_effect.js";
+import { getHeight } from "./get_height.js";
+
+export const ensureDetailsContentFullHeight = (details) => {
+  const updateHeight = () => {
+    if (!details.open) {
+      return;
+    }
+    let summary = details.querySelector("summary");
+    const summaryNextSiblingSet = new Set();
+    {
+      let child = summary;
+      let nextElementSibling;
+      while ((nextElementSibling = child.nextElementSibling)) {
+        nextElementSibling.style.height = "auto";
+        summaryNextSiblingSet.add(nextElementSibling);
+        child = nextElementSibling;
+      }
+    }
+
+    const detailsHeight = getHeight(details);
+    let summaryHeight = getHeight(summary);
+    let heightBefore = summaryHeight;
+    for (const nextElementSibling of summaryNextSiblingSet) {
+      const contentHeight = detailsHeight - heightBefore;
+      nextElementSibling.style.height = `${contentHeight}px`;
+    }
+  };
+
+  updateHeight();
+
+  const cleanupCallbackSet = new Set();
+  update_on_size_change: {
+    const resizeObserver = new ResizeObserver(() => {
+      requestAnimationFrame(() => {
+        updateHeight();
+      });
+    });
+    resizeObserver.observe(details);
+    cleanupCallbackSet.add(() => {
+      resizeObserver.disconnect();
+    });
+  }
+  update_on_toggle: {
+    const ontoggle = () => {
+      updateHeight();
+    };
+    details.addEventListener("toggle", ontoggle);
+    cleanupCallbackSet.add(() => {
+      details.removeEventListener("toggle", ontoggle);
+    });
+  }
+  return () => {
+    for (const cleanupCallback of cleanupCallbackSet) {
+      cleanupCallback();
+    }
+    cleanupCallbackSet.clear();
+  };
+};
+
+addAttributeEffect("data-details-content-full-height", (details) => {
+  return ensureDetailsContentFullHeight(details);
+});