@jsenv/dom 0.6.1 → 0.7.0

package/src/interaction/scroll/wheel_through.js

@@ -1,138 +0,0 @@
-/**
- * Creates intuitive scrolling behavior when scrolling over an element that needs to stay interactive
- * (we can't use pointer-events: none). Instead of scrolling the document unexpectedly,
- * finds and scrolls the appropriate scrollable container behind the overlay.
- */
-
-import { isScrollable } from "./is_scrollable.js";
-import { getScrollContainer } from "./scroll_container.js";
-
-export const allowWheelThrough = (element, connectedElement) => {
-  const isElementOrDescendant = (possibleDescendant) => {
-    return (
-      possibleDescendant === element || element.contains(possibleDescendant)
-    );
-  };
-  const tryToScrollOne = (element, wheelEvent) => {
-    if (element === document.documentElement) {
-      // let browser handle document scrolling
-      return true;
-    }
-
-    const { deltaX, deltaY } = wheelEvent;
-    // we found what we want: a scrollable container behind the element
-    // we try to scroll it.
-    const elementCanApplyScrollDeltaX =
-      deltaX && canApplyScrollDelta(element, deltaX, "x");
-    const elementCanApplyScrollDeltaY =
-      deltaY && canApplyScrollDelta(element, deltaY, "y");
-    if (!elementCanApplyScrollDeltaX && !elementCanApplyScrollDeltaY) {
-      return false;
-    }
-    if (!isScrollable(element)) {
-      return false;
-    }
-    const belongsToElement = isElementOrDescendant(element);
-    if (belongsToElement) {
-      // let browser handle the scroll on the element itself
-      return true;
-    }
-    wheelEvent.preventDefault();
-    applyWheelScrollThrough(element, wheelEvent);
-    return true;
-  };
-
-  if (connectedElement) {
-    const onWheel = (wheelEvent) => {
-      const connectedScrollContainer = getScrollContainer(connectedElement);
-      if (connectedScrollContainer === document.documentElement) {
-        // the connected scrollable parent is the document
-        // there is nothing to do, browser native scroll will work as we want
-        return;
-      }
-
-      const elementsBehindMouse = document.elementsFromPoint(
-        wheelEvent.clientX,
-        wheelEvent.clientY,
-      );
-      for (const elementBehindMouse of elementsBehindMouse) {
-        // try to scroll element itself
-        if (tryToScrollOne(elementBehindMouse, wheelEvent)) {
-          return;
-        }
-        const belongsToElement = isElementOrDescendant(elementBehindMouse);
-        // try to scroll what is behind
-        if (!belongsToElement) {
-          break;
-        }
-      }
-      // At this stage the element has no scrollable parts
-      // we can try to scroll the connected scrollable parent
-      tryToScrollOne(connectedScrollContainer, wheelEvent);
-    };
-    element.addEventListener("wheel", onWheel);
-    return;
-  }
-
-  const onWheel = (wheelEvent) => {
-    const elementsBehindMouse = document.elementsFromPoint(
-      wheelEvent.clientX,
-      wheelEvent.clientY,
-    );
-    for (const elementBehindMouse of elementsBehindMouse) {
-      // try to scroll element itself
-      if (tryToScrollOne(elementBehindMouse, wheelEvent)) {
-        return;
-      }
-      const belongsToElement = isElementOrDescendant(elementBehindMouse);
-      if (belongsToElement) {
-        // keep searching if something in our element is scrollable
-        continue;
-      }
-      // our element is not scrollable, try to scroll the container behind the mouse
-      const scrollContainer = getScrollContainer(elementBehindMouse);
-      if (tryToScrollOne(scrollContainer, wheelEvent)) {
-        return;
-      }
-    }
-  };
-  element.addEventListener("wheel", onWheel);
-};
-
-const canApplyScrollDelta = (element, delta, axis) => {
-  const {
-    clientWidth,
-    clientHeight,
-    scrollWidth,
-    scrollHeight,
-    scrollLeft,
-    scrollTop,
-  } = element;
-
-  let size = axis === "x" ? clientWidth : clientHeight;
-  let currentScroll = axis === "x" ? scrollLeft : scrollTop;
-  let scrollEnd = axis === "x" ? scrollWidth : scrollHeight;
-
-  if (size === scrollEnd) {
-    // when scrollWidth === clientWidth, there is no scroll to apply
-    return false;
-  }
-  if (delta < 0 && currentScroll <= 0) {
-    // when scrollLeft is 0, we can't scroll to the left
-    return false;
-  }
-  if (delta > 0 && currentScroll + size >= scrollEnd) {
-    // when scrollLeft + size >= scrollWidth, we can't scroll to the right
-    return false;
-  }
-  return true;
-};
-
-const applyWheelScrollThrough = (element, wheelEvent) => {
-  wheelEvent.preventDefault();
-  element.scrollBy({
-    top: wheelEvent.deltaY,
-    left: wheelEvent.deltaX,
-    behavior: wheelEvent.deltaMode === 0 ? "auto" : "smooth", // optional tweak
-  });
-};

package/src/iterable_weak_set.js

@@ -1,66 +0,0 @@
-export const createIterableWeakSet = () => {
-  const objectWeakRefSet = new Set();
-
-  return {
-    add: (object) => {
-      const objectWeakRef = new WeakRef(object);
-      objectWeakRefSet.add(objectWeakRef);
-    },
-
-    delete: (object) => {
-      for (const weakRef of objectWeakRefSet) {
-        if (weakRef.deref() === object) {
-          objectWeakRefSet.delete(weakRef);
-          return true;
-        }
-      }
-      return false;
-    },
-
-    *[Symbol.iterator]() {
-      for (const objectWeakRef of objectWeakRefSet) {
-        const object = objectWeakRef.deref();
-        if (object === undefined) {
-          objectWeakRefSet.delete(objectWeakRef);
-          continue;
-        }
-        yield object;
-      }
-    },
-
-    has: (object) => {
-      for (const weakRef of objectWeakRefSet) {
-        const objectCandidate = weakRef.deref();
-        if (objectCandidate === undefined) {
-          objectWeakRefSet.delete(weakRef);
-          continue;
-        }
-        if (objectCandidate === object) {
-          return true;
-        }
-      }
-      return false;
-    },
-
-    clear: () => {
-      objectWeakRefSet.clear();
-    },
-
-    get size() {
-      return objectWeakRefSet.size;
-    },
-
-    getStats: () => {
-      let alive = 0;
-      let dead = 0;
-      for (const weakRef of objectWeakRefSet) {
-        if (weakRef.deref() !== undefined) {
-          alive++;
-        } else {
-          dead++;
-        }
-      }
-      return { total: objectWeakRefSet.size, alive, dead };
-    },
-  };
-};

package/src/position/dom_coords.js

@@ -1,340 +0,0 @@
-/**
- * DOM Coordinate Systems: The Missing APIs Problem
- *
- * When positioning and moving DOM elements, we commonly need coordinate information.
- * The web platform provides getBoundingClientRect() which gives viewport-relative coordinates,
- * but this creates several challenges when working with scrollable containers:
- *
- * ## The Problem
- *
- * 1. **Basic positioning**: getBoundingClientRect() works great for viewport-relative positioning
- * 2. **Document scrolling**: When document has scroll, we add document.scrollLeft/scrollTop
- * 3. **Scroll containers**: When elements are inside scrollable containers, we need coordinates
- *    relative to that container, not the document
- *
- * ## Missing Browser APIs
- *
- * The web platform lacks essential APIs for scroll container workflows:
- * - No equivalent of getBoundingClientRect() relative to scroll container
- * - No built-in way to get element coordinates in scroll container space
- * - Manual coordinate conversion is error-prone and inconsistent
- *
- * ## This Module's Solution
- *
- * This module provides the missing coordinate APIs that work seamlessly with scroll containers:
- * - **getScrollRelativeRect()**: element rect relative to scroll container (PRIMARY API)
- * - **getMouseEventScrollRelativeRect()**: Mouse coordinates in scroll container space
- * - **convertScrollRelativeRectInto()**: Convert scroll-relative rect to element positioning coordinates
- *
- * These APIs abstract away the complexity of coordinate system conversion and provide
- * a consistent interface for element positioning regardless of scroll container depth.
- *
- * ## Primary API: getScrollRelativeRect()
- *
- * This is the main API you want - element rectangle relative to scroll container:
- *
- * ```js
- * const rect = element.getBoundingClientRect(); // viewport-relative
- * const scrollRect = getScrollRelativeRect(element, scrollContainer); // scroll-relative
- * ```
- *
- * Returns: { left, top, right, bottom, width, height, scrollLeft, scrollTop, scrollContainer, ...metadata }
- *
- * The scroll values are included so you can calculate scroll-absolute coordinates yourself:
- * ```js
- * const { left, top, scrollLeft, scrollTop } = getScrollRelativeRect(element);
- * const scrollAbsoluteLeft = left + scrollLeft;
- * const scrollAbsoluteTop = top + scrollTop;
- * ```
- *
- * ## Secondary APIs:
- *
- * - **getMouseEventScrollRelativeRect()**: Get mouse coordinates as a rect in scroll container space
- * - **convertScrollRelativeRectInto()**: Convert from scroll-relative coordinates to element positioning coordinates (for setting element.style.left/top)
- *
- * ## Coordinate System Terminology:
- *
- * - **Viewport-relative**: getBoundingClientRect() coordinates - relative to browser viewport
- * - **Scroll-relative**: Coordinates relative to scroll container (ignoring current scroll position)
- * - **Scroll-absolute**: Scroll-relative + scroll position (element's position in full scrollable content)
- * - **Element coordinates**: Coordinates for positioning elements (via element.style.left/top)
- *
- * ## Legacy Coordinate System Diagrams
- *
- * X-Axis Coordinate Systems in Web Development
- *
- * Diagram showing horizontal positioning and scrollbars:
- *
- * VIEWPORT (visible part of the document)
- * ┌───────────────────────────────────────────────┐
- * │                                               │
- * │                                               │
- * │ container.offsetLeft: 20px                    │
- * │       ┼─────────────────────────────┐         │
- * │       │                             │         │
- * │       │                             │         │
- * │       │  el.offsetLeft: 100px       │         │
- * │       │         ┼─────┐             │         │
- * │       │         │     │             │         │
- * │       │         └─────┘             │         │
- * │       │                             │         │
- * │       │ ░░░███░░░░░░░░░░░░░░░░░░░░░ │         │
- * │       └─────│───────────────────────┘         │
- * │ container.scrollLeft: 50px                    │
- * │                                               │
- * │                                               │
- * │ ░░░░░░░███░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░│
- * └─────────│─────────────────────────────────────┘
- *   document.scrollLeft: 200px
- *
- *
- * Left coordinate for the element:
- *
- * Document coordinates (absolute position in full document)
- * • Result: 320px
- * • Detail: container.offsetLeft + element.offsetLeft + document.scrollLeft
- *           20                +  100              + 200               = 320px
- *
- * Viewport coordinates (getBoundingClientRect().left):
- * • Result: 120px
- * • Detail: container.offsetLeft + element.offsetLeft
- *           20                +  100              = 120px
- *
- * Scroll coordinates (position within scroll container):
- * • Result: 50px
- * • Detail: element.offsetLeft - container.scrollLeft
- *           100              - 50                 = 50px
- *
- * Scroll behavior examples:
- *
- * When document scrolls (scrollLeft: 200px → 300px):
- * • Document coordinates: 320px → 420px
- * • Viewport coordinates: 120px → 120px (unchanged)
- * • Scroll coordinates: 50px → 50px (unchanged)
- *
- * When container scrolls (scrollLeft: 50px → 100px):
- * • Document coordinates: 320px → 270px
- * • Viewport coordinates: 120px → 70px
- * • Scroll coordinates: 50px → 0px
- */
-
-import { getScrollContainer } from "../interaction/scroll/scroll_container.js";
-import { getBorderSizes } from "../size/get_border_sizes.js";
-
-const { documentElement } = document;
-
-/**
- * Get element rectangle relative to its scroll container
- *
- * @param {Element} element - The element to get coordinates for
- * @param {Element} [scrollContainer] - Optional scroll container (auto-detected if not provided)
- * @param {object} [options] - Configuration options
- * @returns {object} { left, top, right, bottom, width, height, scrollLeft, scrollTop, scrollContainer, ...metadata }
- */
-export const getScrollRelativeRect = (
-  element,
-  scrollContainer = getScrollContainer(element),
-  { useOriginalPositionEvenIfSticky = false } = {},
-) => {
-  const {
-    left: leftViewport,
-    top: topViewport,
-    width,
-    height,
-  } = element.getBoundingClientRect();
-
-  let fromFixed = false;
-  let fromStickyLeft;
-  let fromStickyTop;
-  let fromStickyLeftAttr;
-  let fromStickyTopAttr;
-  const scrollLeft = scrollContainer.scrollLeft;
-  const scrollTop = scrollContainer.scrollTop;
-  const scrollContainerIsDocument = scrollContainer === documentElement;
-  const createScrollRelativeRect = (leftScrollRelative, topScrollRelative) => {
-    const isStickyLeftOrHasStickyLeftAttr = Boolean(
-      fromStickyLeft || fromStickyLeftAttr,
-    );
-    const isStickyTopOrHasStickyTopAttr = Boolean(
-      fromStickyTop || fromStickyTopAttr,
-    );
-    return {
-      left: leftScrollRelative,
-      top: topScrollRelative,
-      right: leftScrollRelative + width,
-      bottom: topScrollRelative + height,
-
-      // metadata
-      width,
-      height,
-      scrollContainer,
-      scrollContainerIsDocument,
-      scrollLeft,
-      scrollTop,
-      fromFixed,
-      fromStickyLeft,
-      fromStickyTop,
-      fromStickyLeftAttr,
-      fromStickyTopAttr,
-      isStickyLeftOrHasStickyLeftAttr,
-      isStickyTopOrHasStickyTopAttr,
-      isSticky:
-        isStickyLeftOrHasStickyLeftAttr || isStickyTopOrHasStickyTopAttr,
-    };
-  };
-
-  sticky: {
-    const computedStyle = getComputedStyle(element);
-    sticky_position: {
-      const usePositionSticky = computedStyle.position === "sticky";
-      if (usePositionSticky) {
-        // For CSS position:sticky elements, use scrollable-relative coordinates
-        const [leftScrollRelative, topScrollRelative] =
-          viewportPosToScrollRelativePos(
-            leftViewport,
-            topViewport,
-            scrollContainer,
-          );
-        const isStickyLeft = computedStyle.left !== "auto";
-        const isStickyTop = computedStyle.top !== "auto";
-        fromStickyLeft = isStickyLeft
-          ? { value: parseFloat(computedStyle.left) || 0 }
-          : undefined;
-        fromStickyTop = isStickyTop
-          ? { value: parseFloat(computedStyle.top) || 0 }
-          : undefined;
-        return createScrollRelativeRect(leftScrollRelative, topScrollRelative);
-      }
-    }
-    sticky_attribute: {
-      const hasStickyLeftAttribute = element.hasAttribute("data-sticky-left");
-      const hasStickyTopAttribute = element.hasAttribute("data-sticky-top");
-      const useStickyAttribute =
-        hasStickyLeftAttribute || hasStickyTopAttribute;
-      if (useStickyAttribute) {
-        // Handle virtually sticky obstacles (<col> or <tr>) - elements with data-sticky attributes
-        // but not CSS position:sticky. Calculate their position based on scroll and sticky behavior
-        let [leftScrollRelative, topScrollRelative] =
-          viewportPosToScrollRelativePos(
-            leftViewport,
-            topViewport,
-            scrollContainer,
-          );
-        if (hasStickyLeftAttribute) {
-          const leftCssValue = parseFloat(computedStyle.left) || 0;
-          fromStickyLeftAttr = { value: leftCssValue };
-          if (useOriginalPositionEvenIfSticky) {
-            // For obstacles: use original position only (ignore sticky behavior)
-          } else {
-            const scrollLeft = scrollContainer.scrollLeft;
-            const stickyPosition = scrollLeft + leftCssValue;
-            const leftWithScroll = leftScrollRelative + scrollLeft;
-            if (stickyPosition > leftWithScroll) {
-              leftScrollRelative = leftCssValue; // Element is stuck
-            } else {
-              // Element in natural position
-            }
-          }
-        }
-        if (hasStickyTopAttribute) {
-          const topCssValue = parseFloat(computedStyle.top) || 0;
-          fromStickyTopAttr = { value: topCssValue };
-          if (useOriginalPositionEvenIfSticky) {
-            // For obstacles: use original position only (ignore sticky behavior)
-          } else {
-            const scrollTop = scrollContainer.scrollTop;
-            const stickyPosition = scrollTop + topCssValue;
-            const topWithScroll = topScrollRelative + scrollTop;
-            if (stickyPosition > topWithScroll) {
-              topScrollRelative = topCssValue; // Element is stuck
-            } else {
-              // Element in natural position
-            }
-          }
-        }
-        return createScrollRelativeRect(leftScrollRelative, topScrollRelative);
-      }
-    }
-  }
-
-  // For normal elements, use scrollable-relative coordinates
-  const [leftScrollRelative, topScrollRelative] =
-    viewportPosToScrollRelativePos(leftViewport, topViewport, scrollContainer);
-  return createScrollRelativeRect(leftScrollRelative, topScrollRelative);
-};
-const viewportPosToScrollRelativePos = (
-  leftViewport,
-  topViewport,
-  scrollContainer,
-) => {
-  const scrollContainerIsDocument = scrollContainer === documentElement;
-  if (scrollContainerIsDocument) {
-    return [leftViewport, topViewport];
-  }
-  const { left: scrollContainerLeftViewport, top: scrollContainerTopViewport } =
-    scrollContainer.getBoundingClientRect();
-  return [
-    leftViewport - scrollContainerLeftViewport,
-    topViewport - scrollContainerTopViewport,
-  ];
-};
-
-export const addScrollToRect = (scrollRelativeRect) => {
-  const { left, top, width, height, scrollLeft, scrollTop } =
-    scrollRelativeRect;
-  const leftWithScroll = left + scrollLeft;
-  const topWithScroll = top + scrollTop;
-  return {
-    ...scrollRelativeRect,
-    left: leftWithScroll,
-    top: topWithScroll,
-    right: leftWithScroll + width,
-    bottom: topWithScroll + height,
-  };
-};
-
-// https://github.com/w3c/csswg-drafts/issues/3329
-// Return the portion of the element that is visible for this scoll container
-export const getScrollBox = (scrollContainer) => {
-  if (scrollContainer === documentElement) {
-    const { clientWidth, clientHeight } = documentElement;
-
-    return {
-      left: 0,
-      top: 0,
-      right: clientWidth,
-      bottom: clientHeight,
-      width: clientWidth,
-      height: clientHeight,
-    };
-  }
-
-  const { clientWidth, clientHeight } = scrollContainer;
-  const scrollContainerBorderSizes = getBorderSizes(scrollContainer);
-  const left = scrollContainerBorderSizes.left;
-  const top = scrollContainerBorderSizes.top;
-  const right = left + clientWidth;
-  const bottom = top + clientHeight;
-  return {
-    left,
-    top,
-    right,
-    bottom,
-    width: clientWidth,
-    height: clientHeight,
-  };
-};
-// https://developer.mozilla.org/en-US/docs/Glossary/Scroll_container#scrollport
-export const getScrollport = (scrollBox, scrollContainer) => {
-  const { left, top, width, height } = scrollBox;
-  const leftWithScroll = left + scrollContainer.scrollLeft;
-  const topWithScroll = top + scrollContainer.scrollTop;
-  const rightWithScroll = leftWithScroll + width;
-  const bottomWithScroll = topWithScroll + height;
-  return {
-    left: leftWithScroll,
-    top: topWithScroll,
-    right: rightWithScroll,
-    bottom: bottomWithScroll,
-  };
-};

package/src/position/offset_parent.js

@@ -1,15 +0,0 @@
-export const getPositionedParent = (element) => {
-  let parent = element.parentElement;
-  while (parent && parent !== document.body) {
-    const position = window.getComputedStyle(parent).position;
-    if (
-      position === "relative" ||
-      position === "absolute" ||
-      position === "fixed"
-    ) {
-      return parent;
-    }
-    parent = parent.parentElement;
-  }
-  return document.body;
-};

package/src/position/position_fixed.js

@@ -1,15 +0,0 @@
-export const findSelfOrAncestorFixedPosition = (element) => {
-  let current = element;
-  while (true) {
-    const computedStyle = window.getComputedStyle(current);
-    if (computedStyle.position === "fixed") {
-      const { left, top } = current.getBoundingClientRect();
-      return [left, top];
-    }
-    current = current.parentElement;
-    if (!current || current === document.documentElement) {
-      break;
-    }
-  }
-  return null;
-};