@jsenv/dom 0.17.25 → 0.17.27

package/dist/jsenv_dom.js

@@ -7674,11 +7674,187 @@ const getPaddingSizes = (element) => {
   };
 };
 
+// A gesture on an element the browser paints in the top layer belongs to that
+// element, wherever it sits in the DOM.
+const TOP_LAYER_SELECTOR$1 = [
+  ":popover-open",
+  "dialog:modal",
+  ":fullscreen",
+].join(",");
+
+// The keys that scroll the document when nothing focusable holds them.
+const SCROLL_KEY_SET = new Set([
+  "ArrowUp",
+  "ArrowDown",
+  "ArrowLeft",
+  "ArrowRight",
+  "PageUp",
+  "PageDown",
+  "Home",
+  "End",
+  " ",
+]);
+
+/**
+ * Stops the background from scrolling by cancelling the scroll gestures that
+ * would reach it, leaving every style on the page untouched.
+ *
+ * **Why not overflow: hidden?**
+ * A scroll container that cannot scroll has no sticky offsets: browsers only
+ * apply `position: sticky` constraints to a scroller that can actually scroll.
+ * Locking the document with `overflow: hidden` therefore drops every stuck
+ * element (a sticky header, a sticky table column) back to its flow position —
+ * off screen, since the page stays visually scrolled where it was. Cancelling
+ * gestures keeps the scroller scrollable, so sticky, the scrollbar and the
+ * layout width all stay exactly as they are (no gutter to compensate).
+ *
+ * **What it does not stop**
+ * - dragging the native scrollbar: it sits outside the viewport, no backdrop
+ *   covers it and no event of ours is involved;
+ * - programmatic scroll (`scrollTo`, `scrollIntoView`, a focus moving into the
+ *   background).
+ * Both are deliberate acts on a background that is covered by a backdrop, hence
+ * the requirement: without something covering the background, lock the overflow
+ * instead (see `scroll_trap.js`).
+ *
+ * @param {HTMLElement} element - The overlay being shown. Gestures landing on
+ *   it (or on any other top layer element) are left alone.
+ * @param {Object} [options]
+ * @param {HTMLElement} [options.boundaryElement] - Only block gestures landing
+ *   inside this element. For an overlay confined to a local container: the
+ *   container must stop scrolling, the rest of the page keeps its gestures.
+ * @param {HTMLElement} [options.backdropElement] - The element covering the
+ *   background, when it is one of ours (a modal dialog covers it with its own
+ *   `::backdrop` and there is nothing to pass). It is in the top layer like the
+ *   overlay itself, yet a gesture on it aims at the background behind it.
+ * @returns {() => void} Cleanup function removing the listeners.
+ */
+
+const trapScrollGestureInside = (
+  element,
+  { boundaryElement, backdropElement } = {},
+) => {
+  const { ownerDocument } = element;
+  const lockedRegion = boundaryElement || ownerDocument.documentElement;
+
+  const isBackgroundGesture = (target, clientX, clientY) => {
+    if (!lockedRegion.contains(target)) {
+      return false;
+    }
+    if (element.contains(target)) {
+      // A modal <dialog> is the event target for the whole backdrop area too
+      // (::backdrop is not hit-testable), so being the target does not mean the
+      // pointer is on it — the rect decides, same as the backdrop-click
+      // detection in dialog.jsx.
+      if (target !== element) {
+        return false;
+      }
+      const { left, right, top, bottom } = element.getBoundingClientRect();
+      return (
+        clientX < left || clientX > right || clientY < top || clientY > bottom
+      );
+    }
+    if (backdropElement && backdropElement.contains(target)) {
+      return true;
+    }
+    let ancestorOrSelf = target;
+    while (ancestorOrSelf && ancestorOrSelf.nodeType === 1) {
+      if (ancestorOrSelf.matches(TOP_LAYER_SELECTOR$1)) {
+        return false;
+      }
+      ancestorOrSelf = ancestorOrSelf.parentNode;
+    }
+    return true;
+  };
+
+  const onWheel = (wheelEvent) => {
+    if (wheelEvent.ctrlKey) {
+      // Browser zoom, not a scroll — cancelling it would take zoom away from
+      // the page while an overlay is open.
+      return;
+    }
+    if (
+      isBackgroundGesture(
+        wheelEvent.target,
+        wheelEvent.clientX,
+        wheelEvent.clientY,
+      )
+    ) {
+      wheelEvent.preventDefault();
+    }
+  };
+  const onTouchMove = (touchMoveEvent) => {
+    const { touches } = touchMoveEvent;
+    if (touches.length !== 1) {
+      return; // pinch
+    }
+    const [touch] = touches;
+    if (
+      isBackgroundGesture(touchMoveEvent.target, touch.clientX, touch.clientY)
+    ) {
+      touchMoveEvent.preventDefault();
+    }
+  };
+  const onKeyDown = (keydownEvent) => {
+    if (!SCROLL_KEY_SET.has(keydownEvent.key)) {
+      return;
+    }
+    const { target } = keydownEvent;
+    // Anything else focused (a field, a scrollable box, a button) owns the key
+    // press; only a document with nothing focused scrolls on it.
+    if (
+      target !== ownerDocument.body &&
+      target !== ownerDocument.documentElement
+    ) {
+      return;
+    }
+    if (isBackgroundGesture(target)) {
+      keydownEvent.preventDefault();
+    }
+  };
+
+  // Capture phase: the gesture must be cancelled before whatever it landed on
+  // gets a chance to act on it. passive: false is what makes preventDefault
+  // effective at all on wheel/touchmove.
+  const listenerOptions = { capture: true, passive: false };
+  ownerDocument.addEventListener("wheel", onWheel, listenerOptions);
+  ownerDocument.addEventListener("touchmove", onTouchMove, listenerOptions);
+  ownerDocument.addEventListener("keydown", onKeyDown, listenerOptions);
+  return () => {
+    ownerDocument.removeEventListener("wheel", onWheel, listenerOptions);
+    ownerDocument.removeEventListener(
+      "touchmove",
+      onTouchMove,
+      listenerOptions,
+    );
+    ownerDocument.removeEventListener("keydown", onKeyDown, listenerOptions);
+  };
+};
+
+// "gesture": cancel the scroll gestures aimed at the background, keeping it
+// scrollable (see scroll_gesture_trap.js) — only possible when a backdrop
+// covers it.
+// "overflow": hide the overflow of every scroll container behind the overlay.
+// Set this to "overflow" to put every scroll lock on that single strategy.
+const SCROLL_LOCK_STRATEGY = "gesture";
+
 /**
  * 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.
  *
+ * **Two strategies, and why the gesture one comes first**
+ * Hiding the overflow makes the scroller unable to scroll, and a scroller that
+ * cannot scroll has no sticky offsets: every `position: sticky` element behind
+ * the overlay drops back to its flow position — off screen, since the page
+ * stays visually scrolled where it was. So whenever a backdrop covers the
+ * background (`backdrop`), the lock is done by cancelling scroll gestures
+ * (`scroll_gesture_trap.js`): nothing in the page moves, sticky included, and
+ * there is no scrollbar to compensate for. The overflow lock below is what
+ * remains when nothing covers the background — a gesture trap would then let
+ * the user scroll by dragging the scrollbar of a container they can still see
+ * and reach. `SCROLL_LOCK_STRATEGY` forces that overflow lock everywhere.
+ *
  * **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.
@@ -7700,9 +7876,23 @@ const getPaddingSizes = (element) => {
  *   inside this element (itself included). For an overlay confined to a local
  *   container rather than the viewport: the container's own scroll must stop,
  *   the rest of the page keeps scrolling as usual.
+ * @param {true|HTMLElement} [options.backdrop] - What covers the background
+ *   while the overlay is open: the backdrop element, or `true` when the browser
+ *   paints it itself (a modal dialog's `::backdrop`). Enables the gesture
+ *   strategy described above.
  * @returns {() => void} Cleanup function that restores all modified styles.
  */
-const trapScrollInside = (element, { boundaryElement } = {}) => {
+const trapScrollInside = (
+  element,
+  { boundaryElement, backdrop } = {},
+) => {
+  if (backdrop && SCROLL_LOCK_STRATEGY === "gesture") {
+    return trapScrollGestureInside(element, {
+      boundaryElement,
+      backdropElement: backdrop === true ? null : backdrop,
+    });
+  }
+
   const cleanupCallbackSet = new Set();
 
   // Collect every element to lock first (preceding scrollable siblings + all
@@ -9287,7 +9477,8 @@ const css$4 = /* css */`
        not to the gesture, and two fingers are never a drag. */
     touch-action: pinch-zoom;
   }
-  [data-drag-ignore] {
+  [data-drag-ignore],
+  [data-own-target] {
     -webkit-touch-callout: default;
     touch-action: auto;
   }
@@ -11741,7 +11932,8 @@ const css$1 = /* css */`
   [data-drag-source] {
     cursor: default;
   }
-  [data-drag-ignore] {
+  [data-drag-ignore],
+  [data-own-target] {
     cursor: auto;
   }
 
@@ -11836,6 +12028,14 @@ const css$1 = /* css */`
 // can start a drag, and they have to be true BEFORE anyone drags anything.
 import.meta.css = [css$1, "@jsenv/dom/src/interaction/drag/drag_to.js"];
 
+// What a press must not be read from at all. `data-drag-ignore` is said by
+// something whose press is its own business — a text one wants to select, a
+// control that reads the pointer itself. `data-own-target` is the same fact said
+// once for every gesture there is: an element declaring that a press landing on
+// it is aimed AT it, whatever it happens to sit inside (see also
+// DRAG_EXCLUDED_SELECTOR in drag_to_travel.js).
+const DRAG_IGNORED_SELECTOR = "[data-drag-ignore],[data-own-target]";
+
 /**
  * Starts a drag-to-reorder interaction on a list item.
  *
@@ -12335,7 +12535,7 @@ const startDragTo = (event, effects, {
 } = {}) => {
   // An area that opted out of dragging (a text one wants to select, a control that
   // owns the gesture): the press there is none of our business.
-  if (event.target.closest && event.target.closest("[data-drag-ignore]")) {
+  if (event.target.closest && event.target.closest(DRAG_IGNORED_SELECTOR)) {
     return undefined;
   }
   // A secondary button (right click and friends) is a context menu, not a grab.
@@ -12517,7 +12717,7 @@ const startDragToCarryCopy = (event, {
 }) => {
   // An area that opted out of dragging (a text one wants to select, a control
   // that owns the gesture): the press there is none of our business.
-  if (event.target.closest && event.target.closest("[data-drag-ignore]")) {
+  if (event.target.closest && event.target.closest(DRAG_IGNORED_SELECTOR)) {
     return undefined;
   }
   // A secondary button (right click and friends) is a context menu, not a grab.
@@ -13262,8 +13462,11 @@ const DRAG_RESISTANCE = 0.3;
 // from one travels, and the click it would have made is swallowed on the way
 // out. A drag SOURCE is not either: it says which way it goes and only takes
 // that (see DRAG_SOURCE_AXES_ATTRIBUTE) — but a dedicated handle is, being a
-// place whose only purpose is to be taken hold of, from the first pixel.
-const DRAG_EXCLUDED_SELECTOR = ["input", "textarea", "select", '[contenteditable=""]', '[contenteditable="true"]', "[data-drag-handle]", "[data-no-drag-travel]"].join(",");
+// place whose only purpose is to be taken hold of, from the first pixel. And so
+// is an OWN TARGET: an element saying a press landing on it is aimed at IT,
+// which is the same sentence said to every gesture at once rather than to this
+// one (see DRAG_IGNORED_SELECTOR in drag_to.js).
+const DRAG_EXCLUDED_SELECTOR = ["input", "textarea", "select", '[contenteditable=""]', '[contenteditable="true"]', "[data-drag-handle]", "[data-no-drag-travel]", "[data-own-target]"].join(",");
 
 // Which axes a box travels on, one attribute per gesture, said in the DOM by
 // whoever owns the box: it is what a box ABOVE another reads to know the

package/package.json

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