@jsenv/dom 0.17.18 → 0.17.20

package/dist/jsenv_dom.js

@@ -261,11 +261,22 @@ const chainEvent = (customEvent, parentEvent) => {
   if (!parentEvent) {
     return customEvent;
   }
-  if (!customEvent.detail) {
-    console.warn(
-      `Event "${customEvent.type}" has no detail object. Cannot chain to parent event "${parentEvent.type}".`,
-    );
-    return customEvent;
+  if (!customEvent.detail || typeof customEvent.detail !== "object") {
+    // A native event has nowhere to hang the chain: `Event` has no detail at
+    // all and `UIEvent` (so `InputEvent` too) exposes it as a readonly number.
+    // Give it an own detail object, shadowing the prototype getter, so a
+    // synthetic event dispatched on behalf of a gesture can still say what
+    // caused it.
+    if (nativeDetailHasMeaning(customEvent)) {
+      console.warn(
+        `Chaining "${customEvent.type}" to "${parentEvent.type}" replaces its native detail (${customEvent.detail}), which carries the click count on this event type. Chain a custom event instead, or read the click count before chaining.`,
+      );
+    }
+    Object.defineProperty(customEvent, "detail", {
+      value: {},
+      configurable: true,
+      enumerable: true,
+    });
   }
   // Always build eventChain from the first wrapping so callers can rely on it
   // being present whenever `parentEvent` is set.
@@ -309,6 +320,24 @@ const findEvent = (event, predicate) => {
   return undefined;
 };
 
+// `detail` is a click count on the pointer events that define one, and 0
+// everywhere else (`input`, `focus`, `wheel`…). Overwriting it there loses the
+// only way to tell a real click from a keyboard/programmatic one (detail === 0),
+// so those events must not be chained.
+const EVENT_TYPES_WITH_MEANINGFUL_DETAIL = new Set([
+  "click",
+  "auxclick",
+  "dblclick",
+  "mousedown",
+  "mouseup",
+]);
+const nativeDetailHasMeaning = (event) => {
+  if (EVENT_TYPES_WITH_MEANINGFUL_DETAIL.has(event.type)) {
+    return true;
+  }
+  return typeof event.detail === "number" && event.detail !== 0;
+};
+
 const resolveEventPredicate = (predicate) => {
   if (typeof predicate === "string") {
     return (e) => e.type === predicate;
@@ -8244,7 +8273,12 @@ const createDragGestureController = (options = {}) => {
       // metadata about interaction sources
       grabEvent: event,
       dragEvent: null,
-      releaseEvent: null
+      releaseEvent: null,
+      // The gesture ended without the hand ever letting go: the browser took
+      // the touch to scroll with, another gesture took the pointer. Whoever
+      // reads it must not commit anything — a release that was not asked for
+      // says nothing about where things belong.
+      cancelled: false
     };
     definePropertyAsReadOnly(gestureInfo, "name");
     definePropertyAsReadOnly(gestureInfo, "direction");
@@ -8556,9 +8590,13 @@ const createDragGestureController = (options = {}) => {
     };
     const release = ({
       event = new CustomEvent("programmatic"),
+      cancelled = event.type === "pointercancel",
       releaseX = gestureInfo.dragX,
       releaseY = gestureInfo.dragY
     } = {}) => {
+      // Written before the last drag is reported, so the callbacks reading the
+      // end of the gesture all see the same one.
+      gestureInfo.cancelled = cancelled;
       drag(releaseX, releaseY, {
         event,
         isRelease: true
@@ -8613,10 +8651,13 @@ const createDragGestureController = (options = {}) => {
         event: dragEvent
       });
     };
-    const releaseViaPointer = mouseupEvent => {
-      const [mouseReleaseX, mouseReleaseY] = mouseEventCoords(mouseupEvent);
+    const releaseViaPointer = (pointerEvent, {
+      cancelled
+    } = {}) => {
+      const [mouseReleaseX, mouseReleaseY] = mouseEventCoords(pointerEvent);
       dragGesture.release({
-        event: mouseupEvent,
+        event: pointerEvent,
+        cancelled,
         releaseX: mouseReleaseX,
         releaseY: mouseReleaseY
       });
@@ -8713,7 +8754,8 @@ const createDragGestureController = (options = {}) => {
     const cleanup = initializer({
       onMove: dragViaPointer,
       onRelease: releaseViaPointer,
-      gestureInfo: dragGesture.gestureInfo
+      gestureInfo: dragGesture.gestureInfo,
+      dragGesture
     });
     dragGesture.addReleaseCallback(() => {
       cleanup();
@@ -8725,7 +8767,8 @@ const createDragGestureController = (options = {}) => {
       return initDragByPointer(grabEvent, options, ({
         onMove,
         onRelease,
-        gestureInfo
+        gestureInfo,
+        dragGesture
       }) => {
         // Captured on something that will still be there at the end of the
         // gesture: the browser releases the capture when its element leaves the
@@ -8733,7 +8776,21 @@ const createDragGestureController = (options = {}) => {
         // finger would lose the pointer at its first move. Callers whose target
         // is stable have nothing to say and keep it.
         const target = options?.pointerCaptureElement || grabEvent.target;
-        target.setPointerCapture(grabEvent.pointerId);
+        // The capture is ONE per pointer for the whole document: taking it is
+        // taking it away from whoever had it, who is then told the exact same
+        // thing it is told when its own gesture ends. So it is taken when this
+        // gesture is established and not a moment earlier — for most callers
+        // that is the grab itself (the intent was settled before, by a handle
+        // or a long press), and for a caller that is still deciding what the
+        // press means, it is whenever it says so (see capturePointer).
+        let captured = false;
+        dragGesture.capturePointer = () => {
+          captured = true;
+          target.setPointerCapture(grabEvent.pointerId);
+        };
+        if (!options?.pointerCaptureDeferred) {
+          dragGesture.capturePointer();
+        }
         /*
          * A touchmove left alone is the browser deciding the touch belongs to
          * it: it takes it to scroll with, and a touch it has taken is a pointer
@@ -8767,7 +8824,7 @@ const createDragGestureController = (options = {}) => {
         grabTarget.addEventListener("touchmove", preventTouchScroll, {
           passive: false
         });
-        // Only OUR capture ending means this gesture is over:
+        // Only OUR capture ending is this gesture's business:
         // lostpointercapture bubbles, so a descendant giving up its own capture
         // walks straight into this listener. That is not a rare shape — it is
         // exactly what happens when a gesture hands over to another one (a
@@ -8775,16 +8832,37 @@ const createDragGestureController = (options = {}) => {
         // the pressed element, while the real one is being held on a container
         // above it), and taken as our own it kills the new gesture one
         // millisecond after it started.
+        //
+        // And when it IS ours, it is a loss, never an end: the ends a gesture
+        // has are the pointer going up and the pointer being cancelled, both
+        // listened for below. A capture that goes while the pointer is still
+        // down was taken — by another gesture, or by the element it was held
+        // on leaving the document — and what was being carried must go back
+        // rather than land wherever the hand happened to be.
         const onCaptureLost = pointerEvent => {
-          if (pointerEvent.target !== target) {
+          if (!captured || pointerEvent.target !== target) {
             return;
           }
-          onRelease(pointerEvent);
+          onRelease(pointerEvent, {
+            cancelled: true
+          });
         };
         target.addEventListener("lostpointercapture", onCaptureLost);
         target.addEventListener("pointercancel", onRelease);
-        target.addEventListener("pointermove", onMove);
         target.addEventListener("pointerup", onRelease);
+        // Read from the window rather than from the element while the pointer
+        // is not this gesture's: without a capture a move is delivered to
+        // whatever is under the pointer, and a hand that has left the element
+        // is exactly the hand this gesture is trying to make sense of. The
+        // capture phase reaches the window before anything else, captured or
+        // not, so there is one place to read whichever way the gesture ends up.
+        const onPointerMove = pointerEvent => {
+          if (pointerEvent.pointerId !== grabEvent.pointerId) {
+            return;
+          }
+          onMove(pointerEvent);
+        };
+        window.addEventListener("pointermove", onPointerMove, true);
         // The end of the pointer is also listened for on the window, because
         // the end is the one event a gesture cannot afford to miss and the
         // element it is captured on is not always on its way: a pointer can
@@ -8814,15 +8892,17 @@ const createDragGestureController = (options = {}) => {
           grabTarget.removeEventListener("touchmove", preventTouchScroll);
           target.removeEventListener("lostpointercapture", onCaptureLost);
           target.removeEventListener("pointercancel", onRelease);
-          target.removeEventListener("pointermove", onMove);
+          window.removeEventListener("pointermove", onPointerMove, true);
           target.removeEventListener("pointerup", onRelease);
           window.removeEventListener("pointerup", onPointerEnd, true);
           window.removeEventListener("pointercancel", onPointerEnd, true);
-          // Asked for only while there is something to give back: a pointer
-          // that is up no longer exists, the browser has already dropped the
+          // Only what this gesture took, and only while there is something to
+          // give back: a capture on that element may be someone else's (two
+          // gestures reading the same press hold the same node), and a pointer
+          // that is up no longer exists — the browser has already dropped the
           // capture with it, and asking again throws ("No active pointer with
-          // the given id is found") — on the most ordinary release there is.
-          if (target.hasPointerCapture(grabEvent.pointerId)) {
+          // the given id is found") on the most ordinary release there is.
+          if (captured && target.hasPointerCapture(grabEvent.pointerId)) {
             target.releasePointerCapture(grabEvent.pointerId);
           }
         };
@@ -9066,12 +9146,16 @@ const css$4 = /* css */`
     /* A source taken by long press must let the scroll through until the grab —
        which is exactly what the long press is there to tell apart. Zoom has
        nothing to do with the gesture and nobody should lose it by resting a
-       finger on a word. */
+       finger on a word.
+
+       Vertical, because that is the way the page and the lists in it go: a
+       source dragged along one axis is surrounded by something scrolling along
+       that same axis (a row of a list runs the way the list scrolls), and a
+       source dragged both ways sits on the usual vertical page. */
     touch-action: pan-y pinch-zoom;
   }
   [data-drag-source="x"] {
-    /* The axis is the one thing the caller has to say, being the only one who
-       knows which way what surrounds the source scrolls. */
+    /* …and the sideways one, for the same reason read the other way. */
     touch-action: pan-x pinch-zoom;
   }
   [data-drag-on-contact] [data-drag-source],
@@ -9107,23 +9191,36 @@ import.meta.css = [css$4, "@jsenv/dom/src/interaction/drag/drag_after_intent.js"
  *
  * On the element and not on the window, so the rest of the page keeps its
  * touches on the compositor's fast path.
+ *
+ * Exported because a drag does not always begin on a drag source: a copy caught
+ * on its way home is pressed through the pictures of a view transition, and the
+ * touch lands on the document root (see letCopyBeCaught in drag_to.js). Same
+ * rule, other element — and it has to be the same function, or the listener put
+ * down is not the one taken back off.
  */
 const keepTouchRefusable = () => {
   // Being registered IS the whole of it — see above.
 };
 
 /**
- * Says an element is something a drag can start from.
+ * Says an element is something a drag can start from, and which way that drag
+ * goes.
+ *
+ * The axes are written in the DOM rather than kept here because they are what
+ * someone ELSE reads: a box above this one that travels under the same finger
+ * (a row of slides, a sheet pushed down to close it) has to know which axes are
+ * already spoken for before it answers the press — the same thing a travel says
+ * about itself with `data-travel-by-drag`. It is also what leaves the browser
+ * the pan it may still do until the grab (see the stylesheet above).
  *
  * @param {Element} element
- * @param {string} [axes]
- *   Which way the SURROUNDINGS scroll, so the other axis is left to them until
- *   the grab: `"x"` for a source inside something travelling sideways, anything
- *   else for the usual vertical page.
+ * @param {"x"|"y"|"xy"} [axes="xy"]
+ *   Which way the drag walks. A list reordered along its own line says `"y"`;
+ *   something carried across a board, or thrown, goes both ways.
  * @returns {function} Takes the mark back off.
  */
-const markDragSource = (element, axes) => {
-  element.setAttribute("data-drag-source", axes === "x" ? "x" : "");
+const markDragSource = (element, axes = "xy") => {
+  element.setAttribute("data-drag-source", axes);
   element.addEventListener("touchmove", keepTouchRefusable, {
     passive: false
   });
@@ -9223,7 +9320,13 @@ const dragAfterDistance = (grabEvent, dragGestureInitializer, threshold) => {
     }
   });
   const significantDragGesture = significantDragGestureController.grabViaPointer(grabEvent, {
-    element: grabEvent.target
+    element: grabEvent.target,
+    // This one owns nothing: it measures a distance to find out whether there
+    // is a gesture at all, and it is over the moment there is. Taking the
+    // pointer for that would take it from whoever is already holding this same
+    // element for a gesture of their own — and giving it back at the threshold
+    // would tell them theirs is over.
+    pointerCaptureDeferred: true
   });
 };
 const dragAfterLongPress = (grabEvent, dragGestureInitializer, {
@@ -11512,6 +11615,18 @@ const css$1 = /* css */`
     pointer-events: auto;
   }
 
+  /* …and a FINGER reaching for it does not land on it: the pictures of the
+     transition cover the page, so as far as the browser is concerned the touch
+     began on the document root. What a touch may do is decided there and at that
+     moment, so the root says it for as long as the copy can be caught — the pan
+     is ours (nothing should scroll while something is landing), zoom stays the
+     reader's. Half of a pair: without the non-passive listener put down at the
+     same moment (see letCopyBeCaught) every touchmove arrives already
+     non-cancelable and refusing it does nothing. */
+  [data-drag-catchable] {
+    touch-action: pinch-zoom;
+  }
+
   /* Ce qui a été lancé: il continue dans la direction du geste jusqu'à sortir de
      l'écran, et revient par le même chemin si la réponse refuse. */
   [navi-drag-clone-wrapper][data-tossed] {
@@ -12152,6 +12267,12 @@ const resolveDropMeaning = ({
   tossDistance = TOSS_DISTANCE_TO_COMMIT,
   tossSpeed = TOSS_SPEED_TO_COMMIT
 }) => {
+  if (gestureInfo.cancelled) {
+    // Nobody let go of anything: the gesture was taken away mid-air (the
+    // pointer cancelled, another gesture taking it). Where the thing happened
+    // to be at that moment is not a place it was put.
+    return "cancel";
+  }
   if (canToss) {
     const {
       xDelta,
@@ -12451,7 +12572,15 @@ const startDragToCarryCopy = (event, {
       return dragGesture;
     }, {
       threshold,
-      longPress,
+      // A copy caught on its way home is not an ambiguous press: the hand
+      // reached for something moving, and the press was already matched
+      // against the copy's own box before it got here. The wait a finger is
+      // asked for elsewhere tells a scroll from a drag, and there is no scroll
+      // to tell it from — the copy covers that spot from the top layer. Asked
+      // for anyway it cannot even be answered: the wait is about as long as the
+      // journey, so the thing is home before the proof is done, while a mouse
+      // takes it in five pixels.
+      longPress: cloneWrapperCaught ? false : longPress,
       longPressDelay,
       longPressSlop,
       onPressStart,
@@ -12641,6 +12770,17 @@ const letCopyBeCaught = (cloneWrapper, carryAgain) => {
   // gesture holds what it grabbed rather than whatever was behind.
   cloneWrapper.setAttribute("data-catchable", "");
   document.addEventListener("pointerdown", onPointerDown, true);
+  // The touch half of the same reach, said on the root because that is where a
+  // finger pressing through the pictures lands (see the stylesheet). Both go
+  // down before the copy sets off, since what a touch may do is settled when it
+  // begins: put down later, the press is still read, the carry still starts, and
+  // the browser cancels the pointer one move afterwards — a copy that cannot be
+  // caught with a finger and can with a mouse.
+  const root = document.documentElement;
+  root.setAttribute("data-drag-catchable", "");
+  root.addEventListener("touchmove", keepTouchRefusable, {
+    passive: false
+  });
   return {
     settled: async () => {
       // A hand that lets go and presses again while the copy is still there is
@@ -12652,6 +12792,8 @@ const letCopyBeCaught = (cloneWrapper, carryAgain) => {
       }
       cloneWrapper.removeAttribute("data-catchable");
       document.removeEventListener("pointerdown", onPointerDown, true);
+      root.removeAttribute("data-drag-catchable");
+      root.removeEventListener("touchmove", keepTouchRefusable);
       return caught;
     }
   };
@@ -12943,10 +13085,13 @@ const DRAG_FLICK_DISTANCE = 8;
 // way. Let go and it comes back — a wall one can lean on, never walk through.
 const DRAG_RESISTANCE = 0.3;
 
-// What a drag must not start on: something that reads the pointer itself. A
-// button or a link is not in the list — dragging from one travels, and the
-// click it would have made is swallowed on the way out.
-const DRAG_EXCLUDED_SELECTOR = ["input", "textarea", "select", '[contenteditable=""]', '[contenteditable="true"]', "[data-no-drag-travel]"].join(",");
+// What a drag must not start on: something that reads the pointer itself, whole,
+// with no axis left to share. A button or a link is not in the list — dragging
+// 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(",");
 
 // 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
@@ -12954,6 +13099,12 @@ const DRAG_EXCLUDED_SELECTOR = ["input", "textarea", "select", '[contenteditable
 // from the outside.
 const DRAG_AXES_ATTRIBUTE = "data-travel-by-drag";
 const WHEEL_AXES_ATTRIBUTE = "data-travel-by-wheel";
+// The same thing said by something that is PICKED UP rather than travelled: a
+// row taken out of a list, a card carried across a board (see markDragSource).
+// It holds the pointer from the press exactly as a nested travel does, so it is
+// read exactly as one — a list reordered along its own line takes the axis it
+// runs on and leaves the other to whoever is above.
+const DRAG_SOURCE_AXES_ATTRIBUTE = "data-drag-source";
 
 // A surface the browser paints in the top layer: it is still a DOM descendant
 // of whatever it was written in, and it is nowhere near it on screen — it
@@ -13169,10 +13320,12 @@ const startDragToTravel = (pointerDownEvent, {
   if (!target.closest || target.closest(DRAG_EXCLUDED_SELECTOR)) {
     return null;
   }
-  // A box between the finger and this one that travels the same way: the
-  // gesture is its, and this one is left with the axes it does not walk — none
-  // at all, most of the time, and then there is no gesture here to read.
-  const axesLeft = axesLeftBy(axes, target, element, DRAG_AXES_ATTRIBUTE);
+  // A box between the finger and this one that travels the same way, and then
+  // anything between them that is picked up and carried the same way: the
+  // gesture is theirs, and this one is left with the axes none of them walks —
+  // none at all, most of the time, and then there is no gesture here to read.
+  const axesLeftByTravels = axesLeftBy(axes, target, element, DRAG_AXES_ATTRIBUTE);
+  const axesLeft = axesLeftByTravels && axesLeftBy(axesLeftByTravels, target, element, DRAG_SOURCE_AXES_ATTRIBUTE);
   if (!axesLeft) {
     return null;
   }
@@ -13339,6 +13492,9 @@ const startDragToTravel = (pointerDownEvent, {
           pulled: started.slack || 0
         };
         document.documentElement.setAttribute(WALKING_ATTRIBUTE, axis);
+        // The travel exists: from here the pointer is this box's, and it is
+        // followed wherever it goes.
+        dragGesture.capturePointer();
       }
       const {
         axis
@@ -13410,9 +13566,12 @@ const startDragToTravel = (pointerDownEvent, {
       const towardsSomething = pulled > 0 ? travel.travelBack : travel.travelOn;
       const velocity = axis === "x" ? gestureInfo.velocityX : gestureInfo.velocityY;
       // A gesture taken away rather than let go of (the browser scrolling
-      // something else, a call coming in) said nothing: things go back.
+      // something else, a call coming in, another gesture taking the pointer)
+      // said nothing: things go back.
       const releaseEvent = gestureInfo.releaseEvent || gestureInfo.dragEvent;
-      const cancelled = releaseEvent?.type === "pointercancel";
+      const {
+        cancelled
+      } = gestureInfo;
       onEnd({
         axis,
         pulled,
@@ -13443,7 +13602,15 @@ const startDragToTravel = (pointerDownEvent, {
       // gesture may take that away (a page that travels navigates, and the
       // router unmounts the page being left), and a capture whose element
       // leaves the document is a capture the browser drops.
-      pointerCaptureElement: element
+      pointerCaptureElement: element,
+      // A travel is established in two steps, and the pointer is only owned
+      // after the second: the distance below says the press is not a click, and
+      // the first move says which axis it leans on — which this box may not
+      // walk, or the caller may refuse. Taken at the first step, the capture
+      // would be taken away from whoever else is reading the same press for
+      // gestures that give themselves up one event later. It is claimed once
+      // the travel exists, in onDrag below.
+      pointerCaptureDeferred: true
     });
     return dragGesture;
   };

package/package.json

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