@jsenv/navi 0.30.35 → 0.30.36

package/dist/dev/jsenv_navi.js

@@ -25136,6 +25136,12 @@ const DOUBLE_CLICK_SLOP_ATTRIBUTE = "data-double-click-slop";
 // taps: said in the DOM at render time, for the CSS below and for the boxes above
 // to read.
 const SWIPE_AXES_ATTRIBUTE = "data-swipe";
+// A popup's `translate` is where it is placed, written inline by the placement
+// (applyNewPosition in @jsenv/dom), and an inline declaration wins over the
+// rule painting the pull: the swipe is answered with nothing following it.
+// Moving a popup by hand is pushing it away, which swipe_to_close.js does by
+// composing a transform under the placement.
+const POPUP_ELEMENT_SELECTOR = `[navi-control="popover"], [navi-control="dialog"]`;
 const LONGPRESS_ATTRIBUTE = "data-longpress";
 const DOUBLE_CLICK_ATTRIBUTE = "data-double-click";
 
@@ -25235,6 +25241,9 @@ defineInteractionDetector({
       });
     };
     if (axes) {
+      if (element.matches(POPUP_ELEMENT_SELECTOR)) {
+        warnSwipeOnPopupElement(element);
+      }
       mark(SWIPE_AXES_ATTRIBUTE, axes);
       // Read by the boxes ABOVE this one: an axis swiped here is not theirs to
       // travel (see axesLeftBy).
@@ -25515,6 +25524,13 @@ const warnOnceAboutHoldTakenByInner = (element, innerElement) => {
   );
 };
 
+const warnSwipeOnPopupElement = (element) => {
+  console.warn(
+    `interactions: a swipe declared on a popup's own element does not move it — its translate is where the popup is placed. A popup pushed away closes with closeByDrag (Popover, SidePanel; a docked Dialog sheet does it on its own); a swipe on something it holds is declared on that element.`,
+    element,
+  );
+};
+
 const startSwipe = (
   pointerDownEvent,
   {
@@ -77148,18 +77164,19 @@ const readRoom = () =>
   visualViewportHeightSignal.peek() - getVirtualKeyboardOverlayHeight();
 
 /**
- * Pushing a popup docked to an edge (a side panel, a bottom sheet) back the way
- * it came in closes it: it follows the finger while it travels, and letting go
- * either finishes the departure or brings it back to rest — whichever the
- * travel was already heading to.
+ * Pushing a popup docked to an edge (a side panel, a bottom sheet, a toast)
+ * back the way it came in closes it: it follows the finger while it travels,
+ * and letting go either finishes the departure or brings it back to rest —
+ * whichever the travel was already heading to. A popup may be given other ways
+ * out than that one: a toast is also thrown sideways.
  *
  * Reading the pointer is not done here: when a press becomes a gesture, which
  * axis it leans on, how fast it was going when it was let go, who else has a
  * claim on it (a field, a scroller with room left, a box inside the panel that
  * travels the same way) is one gesture system for the whole codebase
  * (@jsenv/dom's startDragToTravel). A panel closing is a travel of exactly one
- * box, towards the edge it is docked to and nowhere else — which is all this
- * file has to say.
+ * box, out by one of the edges it may leave by and nowhere else — which is all
+ * this file has to say.
  *
  * The release travel is driven here (Web Animations) rather than handed to the
  * exit transition the `animation` prop may install: its pace is what is left to
@@ -77174,7 +77191,7 @@ const readRoom = () =>
 // less, so the panel keeps the same speed whenever the finger let go.
 const TRAVEL_DURATION = 220;
 
-// Which way a popup docked to each side travels — read by the panel itself to
+// Which way a popup leaving by each side travels — read by the panel itself to
 // say so in the DOM, which is how a box travelling INSIDE it (a row of slides,
 // a route travel) knows that axis is already walked.
 const SWIPE_AXIS_BY_SIDE = {
@@ -77183,12 +77200,27 @@ const SWIPE_AXIS_BY_SIDE = {
   top: "y",
   bottom: "y",
 };
-// Which way the finger pushes to send the panel back where it came from, in
-// screen coordinates: positive is right/down, the same sign the gesture reports.
+// Which way the finger pushes to send the panel out by each side, in screen
+// coordinates: positive is right/down, the same sign the gesture reports.
 const CLOSE_DIRECTION_BY_SIDE = { left: -1, right: 1, top: -1, bottom: 1 };
 
 /**
- * Builds the `pointerdown` handler a popup docked to `side` answers with.
+ * The axes a popup leaving by `sides` travels on, as the gesture and the DOM
+ * say them: "x", "y" or "xy".
+ */
+const swipeAxesOf = (sides) => {
+  const hasX = sides.some((side) => SWIPE_AXIS_BY_SIDE[side] === "x");
+  const hasY = sides.some((side) => SWIPE_AXIS_BY_SIDE[side] === "y");
+  if (hasX && hasY) {
+    return "xy";
+  }
+  return hasX ? "x" : "y";
+};
+
+/**
+ * Builds the `pointerdown` handler of a popup that leaves by any of `sides`:
+ * usually the one edge it is docked to, the way it came in; a toast is also
+ * thrown sideways, and leaves the way it was thrown.
  *
  * `grip` says where the gesture may start, as a selector the pressed element is
  * matched against with `closest`. A popup that names one is held THERE and
@@ -77196,11 +77228,17 @@ const CLOSE_DIRECTION_BY_SIDE = { left: -1, right: 1, top: -1, bottom: 1 };
  * and a press on it is that content's — including gestures of its own, which
  * this file has no way of knowing about. A popup that names no grip is pushed
  * from its whole surface, which only suits one made of nothing else (a side
- * panel showing a page).
- */
-const createSwipeToClose = (side, { grip } = {}) => {
-  const axis = SWIPE_AXIS_BY_SIDE[side];
-  const closeDirection = CLOSE_DIRECTION_BY_SIDE[side];
+ * panel showing a page, a toast).
+ */
+const createSwipeToClose = (sides, { grip } = {}) => {
+  const axes = swipeAxesOf(sides);
+  // The side a push along `axis` towards `sign` leaves by, if it leaves at all.
+  const sideTowards = (axis, sign) =>
+    sides.find(
+      (side) =>
+        SWIPE_AXIS_BY_SIDE[side] === axis &&
+        CLOSE_DIRECTION_BY_SIDE[side] === sign,
+    );
 
   return (pointerDownEvent) => {
     const panelEl = pointerDownEvent.currentTarget;
@@ -77217,6 +77255,11 @@ const createSwipeToClose = (side, { grip } = {}) => {
       }
     }
 
+    // Decided when the finger picks its axis (onStart), once for the gesture.
+    let axis;
+    // How far the panel travels to be out, for each way it can go on that axis.
+    const distanceOutBySign = new Map();
+
     // How far the panel has been pulled, as the style showing it — written on
     // the panel while the finger drives it, handed to the release travel as
     // its two keyframes. The gesture reports a distance in screen coordinates,
@@ -77226,7 +77269,7 @@ const createSwipeToClose = (side, { grip } = {}) => {
     // composes under the placement instead of replacing it.
     const styleAt = (distance) => ({
       transform: translateOf(axis, distance),
-      clipPath: clipOf(side, distance),
+      clipPath: clipOf(sides, axis, distance),
     });
     const paint = (distance) => {
       Object.assign(panelEl.style, styleAt(distance));
@@ -77238,21 +77281,22 @@ const createSwipeToClose = (side, { grip } = {}) => {
     };
     // The resting value is written first and the animation only covers the way
     // to it: both end on the same number, so nothing is seen changing when the
-    // animation hands the panel back to its own style.
-    const travelTo = (from, to, onArrival) => {
+    // animation hands the panel back to its own style. `span` is the full travel
+    // on that side, which the duration is a fraction of.
+    const travelTo = (from, to, span, onArrival) => {
       const covered = from > to ? from - to : to - from;
       paint(to);
       const animation = panelEl.animate([styleAt(from), styleAt(to)], {
-        duration: (covered / sizeOf(panelEl, axis)) * TRAVEL_DURATION,
+        duration: (covered / span) * TRAVEL_DURATION,
         easing: "ease-out",
       });
       animation.finished.then(onArrival, () => {});
     };
-    const close = (event) => {
+    const close = (event, out, span) => {
       triggerNaviCommand(panelEl, "--navi-close", event);
       if (panelEl.getAttribute("aria-expanded") === "true") {
         // Refused: the panel is staying, so it goes back where it was.
-        travelTo(sizeOf(panelEl, axis) * closeDirection, 0, restore);
+        travelTo(out, 0, span, restore);
         return;
       }
       restore();
@@ -77260,79 +77304,94 @@ const createSwipeToClose = (side, { grip } = {}) => {
 
     startDragToTravel(pointerDownEvent, {
       element: panelEl,
-      axes: axis,
-      onStart: ({ sign, target }) => {
-        if (sign !== closeDirection) {
+      axes,
+      onStart: ({ axis: gestureAxis, sign, target }) => {
+        const side = sideTowards(gestureAxis, sign);
+        if (!side) {
           // Pushing the panel further in is not a travel: there is nowhere that
           // way, and reading it as one would make the panel lean at every
           // gesture that starts by going the wrong way.
           return false;
         }
-        const size = sizeOf(panelEl, axis);
+        const size = distanceOut(panelEl, side);
         if (!size) {
           return false;
         }
         // Something else with a better claim on the gesture: a scroller between
         // the finger and the panel, with room left that way.
-        if (scrollRoomTowards(target, panelEl, axis, sign)) {
+        if (scrollRoomTowards(target, panelEl, gestureAxis, sign)) {
           return false;
         }
+        axis = gestureAxis;
+        distanceOutBySign.set(sign, size);
+        const otherSide = sideTowards(gestureAxis, -sign);
+        if (otherSide) {
+          distanceOutBySign.set(-sign, distanceOut(panelEl, otherSide));
+        }
         panelEl.style.transitionProperty = "none";
-        // The way out is the only way there is anything: pulling the other way
-        // leans against a wall and comes back.
+        // Only the ways out lead anywhere: pulling towards a side the panel
+        // does not leave by leans against a wall and comes back.
         return {
           size,
-          travelBack: closeDirection > 0,
-          travelOn: closeDirection < 0,
+          travelBack: Boolean(sideTowards(gestureAxis, 1)),
+          travelOn: Boolean(sideTowards(gestureAxis, -1)),
         };
       },
       onPull: ({ pulled }) => {
         paint(pulled);
       },
-      onEnd: ({ pulled, size, travels, event }) => {
+      onEnd: ({ pulled, size, sign, travels, event }) => {
         if (travels) {
-          travelTo(pulled, size * closeDirection, () => close(event));
+          const span = distanceOutBySign.get(sign);
+          travelTo(pulled, span * sign, span, () =>
+            close(event, span * sign, span),
+          );
           return;
         }
-        travelTo(pulled, 0, restore);
+        travelTo(pulled, 0, size, restore);
       },
     });
   };
 };
 
-const sizeOf = (element, axis) => {
+// What takes the popup out of sight: its own size, plus the gap a margin keeps
+// between it and the edge it is pushed through — the room applyNewPosition
+// publishes on that side. Travelling its size alone, a popup kept off its edge
+// (a toast 12px above a bar) would stop with that much of itself still showing.
+const distanceOut = (element, side) => {
   const rect = element.getBoundingClientRect();
-  return axis === "x" ? rect.width : rect.height;
+  const size = SWIPE_AXIS_BY_SIDE[side] === "x" ? rect.width : rect.height;
+  const room = parseFloat(
+    element.style.getPropertyValue(`--container-position-room-${side}`),
+  );
+  return Number.isNaN(room) ? size : size + room;
 };
 const translateOf = (axis, distance) =>
   axis === "x"
     ? `translate(${distance}px, 0px)`
     : `translate(0px, ${distance}px)`;
 // The same cut the entry/exit animation makes (popup_css.js), at a distance the
-// finger decides instead of a transition: the edge the popup is pushed back
-// through, as popup_css.js placed it (--x-popup-cut-*-at-area — on the area's
-// edge where a band of glass lies past it, 100vmax out where the window's own
-// edge does the cutting), plus what has been pulled, so the cut holds that line
-// while the box travels under it. The three other sides are left far outside
-// the box — the pull never takes the popup past them, and cutting there would
-// only shave what it legitimately paints outside its own box. Reading the
-// policy from popup_css.js rather than the rooms keeps the release travel
-// (a Web Animation on transform AND clip-path, two clocks) from animating a
-// cut the entrance would not.
+// finger decides instead of a transition: each edge the popup may leave by on
+// the axis it travels, as popup_css.js placed it (--x-popup-cut-*-at-area — on
+// the area's edge where a band of glass lies past it, 100vmax out where the
+// window's own edge does the cutting), moved by what has been pulled towards
+// it, so the cut holds that line while the box travels under it, whichever way.
+// Every other side is left far outside the box — the pull never takes the popup
+// past them, and cutting there would only shave what it legitimately paints
+// outside its own box. Reading the policy from popup_css.js rather than the
+// rooms keeps the release travel (a Web Animation on transform AND clip-path,
+// two clocks) from animating a cut the entrance would not.
 const UNCUT = "-100vmax";
-const clipOf = (side, distance) => {
-  const pulled = distance < 0 ? -distance : distance;
-  const cut = `calc(var(--x-popup-cut-${side}-at-area, ${UNCUT}) + ${pulled}px)`;
-  if (side === "top") {
-    return `inset(${cut} ${UNCUT} ${UNCUT} ${UNCUT})`;
-  }
-  if (side === "right") {
-    return `inset(${UNCUT} ${cut} ${UNCUT} ${UNCUT})`;
-  }
-  if (side === "bottom") {
-    return `inset(${UNCUT} ${UNCUT} ${cut} ${UNCUT})`;
-  }
-  return `inset(${UNCUT} ${UNCUT} ${UNCUT} ${cut})`;
+const INSET_ORDER = ["top", "right", "bottom", "left"];
+const clipOf = (sides, axis, distance) => {
+  const insets = INSET_ORDER.map((side) => {
+    if (!sides.includes(side) || SWIPE_AXIS_BY_SIDE[side] !== axis) {
+      return UNCUT;
+    }
+    const towards = distance * CLOSE_DIRECTION_BY_SIDE[side];
+    return `calc(var(--x-popup-cut-${side}-at-area, ${UNCUT}) + ${towards}px)`;
+  });
+  return `inset(${insets.join(" ")})`;
 };
 
 /**
@@ -79122,7 +79181,7 @@ const useDialogProps = props => {
   // actually resting on an edge: anywhere else the gesture would send the
   // dialog somewhere it never came from.
   const swipeToCloseSide = isDocked && (parsedPositionArea.y === "top" || parsedPositionArea.y === "bottom") ? parsedPositionArea.y : null;
-  const onSwipePointerDown = swipeToCloseSide ? createSwipeToClose(swipeToCloseSide, {
+  const onSwipePointerDown = swipeToCloseSide ? createSwipeToClose([swipeToCloseSide], {
     grip: DOCKED_SWIPE_GRIP
   }) : null;
   // A corner sitting exactly on the container's own corner must not be
@@ -80302,6 +80361,16 @@ const css$C = /* css */`
        to filter). An entrance animation moves the popover through scale and
        transform instead, which compose under it: see popup_css.js. */
 
+    /* What a touch may do on a popover pushed sideways to close it (see
+       swipe_to_close.js): the push takes the sideways axis, the page keeps the
+       vertical scroll. A push up or down travels the way the page scrolls and
+       cannot give that axis away: the browser keeps it, and the gesture is
+       settled by keepTouchRefusable. */
+    &[data-swipe-to-close~="left"],
+    &[data-swipe-to-close~="right"] {
+      touch-action: pan-y;
+    }
+
     /* The clamped max, not --popover-maxmax-*: that one ignores what the
        placement left available, which reaches here through
        --container-position-remaining-* (see applyNewPosition) — the min()
@@ -80532,6 +80601,20 @@ const css$C = /* css */`
  *   overlap with the anchor; wrap it in `inset(...)` (e.g. `inset(top)`,
  *   `inset(top-left)`) to overlap the anchor instead (edges touching or
  *   inside it).
+ * @param {boolean|Array<"top"|"right"|"bottom"|"left">} [props.closeByDrag=false] -
+ *   Pushing the popover out of its container closes it: it follows the pointer
+ *   and, when released, finishes leaving or comes back to rest. `true` pushes
+ *   it back through the edge it is docked to, the word `positionArea` leads
+ *   with (`"bottom"`, `"bottom-start"`: pushed down; `"left-end"`: pushed
+ *   left); a centred popover rests on no edge and is not pushed (warned in
+ *   dev). A list names the sides it may leave by, and it leaves the way it was
+ *   pushed: `["bottom", "left", "right"]` for a toast pushed back down behind
+ *   the bar or thrown sideways. A popover placed against an anchor at its
+ *   opening is not pushed either way (warned in dev). It is pushed from its
+ *   whole surface, so it suits a popover holding little else: a button inside
+ *   keeps its tap, and a press that turns into a push swallows the click it
+ *   would have left. The close keeps, as a cross's does. See docs/interactions.md
+ *   for a swipe on the popover's own element, which does not move it.
  * @param {string} [props.positionAreaFixed] - Overrides `positionArea` once
  *   the popover has actually been positioned once, so a live reposition
  *   (e.g. anchor moved) doesn't jump to a different side.
@@ -80985,6 +81068,7 @@ const usePopoverProps = props => {
     positionAreaWhenAnchorIsInvalid,
     marginWithContainer = 0,
     container = "app",
+    closeByDrag = false,
     // "close"  → pointer press outside closes (a plain close = commit)
     // "cancel" → pointer press outside closes AS A CANCEL (revert)
     // "capture"→ absorb the press, stay open
@@ -81118,6 +81202,7 @@ const usePopoverProps = props => {
     return popupGroup.register(openController);
   }, [popupGroup, openController]);
   const hasBackdrop = pressOutside !== "ignore" && backdrop && !popupGroup;
+  const swipeToCloseSides = resolveSwipeToCloseSides(closeByDrag, positionArea);
   if (!popupGroup && !backdrop && pressOutside === "capture") {
     console.warn(`Popover: pressOutside="capture" needs a backdrop. Absorbing a press is what a wall does, and backdrop={false} takes it away — every press outside reaches the page, exactly as with "ignore".`);
   }
@@ -81267,6 +81352,9 @@ const usePopoverProps = props => {
     }
     const hasAnchorElement = Boolean(anchorElement);
     anchorElementRef.current = anchorElement || null;
+    if (swipeToCloseSides && hasAnchorElement) {
+      console.warn(`Popover: closeByDrag is ignored, this opening placed the popover against an anchor rather than in its container. A popover pushed away has no anchor: anchorCustomEventDetail="ignore" and no anchor prop.`, anchorElement);
+    }
     // getPositionedParent already resolves to document.documentElement for
     // the via-attribute renderer on its own (popoverEl's own `popover`
     // attribute, present from render regardless of whether it's actually
@@ -81961,6 +82049,7 @@ const usePopoverProps = props => {
       }
     }
   });
+  const swipeToClose = swipeToCloseSides ? createSwipeToClose(swipeToCloseSides) : null;
   Object.assign(contentProps, {
     id,
     tabIndex,
@@ -82039,6 +82128,26 @@ const usePopoverProps = props => {
       onKeyDown?.(e);
       onKeyDownShortcuts(e);
     },
+    ...(swipeToClose ? {
+      "data-swipe-to-close": swipeToCloseSides.join(" "),
+      // The axes it travels on when pushed out, said to the shared gesture
+      // layer before any finger lands (see side_panel.jsx, which says the
+      // same for the same reasons).
+      "data-drag-travel": swipeAxesOf(swipeToCloseSides),
+      "data-travel-by-drag": swipeAxesOf(swipeToCloseSides),
+      "onTouchMove": e => {
+        rest.onTouchMove?.(e);
+        keepTouchRefusable(e);
+      },
+      "onPointerDown": e => {
+        rest.onPointerDown?.(e);
+        // Placed against an anchor at this opening: it is not in its
+        // container to be pushed out of (warned at the opening).
+        if (!anchorElementRef.current) {
+          swipeToClose(e);
+        }
+      }
+    } : null),
     // A popup opened from inside this one is in front of it, not a peer of
     // it: the group stops here.
     "children": popupGroup ? jsx(PopupGroupContext.Provider, {
@@ -82112,6 +82221,37 @@ const resolvePositionAreaAndAnimationKind = ({
 Popover.Close = PopupClose;
 Popover.Title = PopupTitle;
 
+// The sides a popover pushed away leaves by, or null when it is not pushed.
+const resolveSwipeToCloseSides = (closeByDrag, positionArea) => {
+  if (!closeByDrag) {
+    return null;
+  }
+  if (Array.isArray(closeByDrag)) {
+    const sides = closeByDrag.filter(side => side in SWIPE_AXIS_BY_SIDE);
+    if (sides.length !== closeByDrag.length) {
+      console.warn(`Popover: closeByDrag={${JSON.stringify(closeByDrag)}} names something that is not a side; the sides are "top", "right", "bottom" and "left".`);
+    }
+    return sides.length ? sides : null;
+  }
+  const side = dockedSideOf(positionArea);
+  if (!side) {
+    {
+      console.warn(`Popover: closeByDrag with positionArea="${positionArea}" rests on no edge, so there is no way back to push it through. Dock it to one ("bottom", "top", "left", "right", or a token leading with one of them), or name the sides it leaves by: closeByDrag={["left", "right"]}.`);
+    }
+    return null;
+  }
+  return [side];
+};
+const INSET_TOKEN_RE = /^inset\(\s*([a-z-]+)\s*\)$/;
+// The edge a popover docked to its container rests on: the word its
+// positionArea leads with, "bottom-start" resting on the bottom and "left-end"
+// on the left. "center" rests on none.
+const dockedSideOf = positionArea => {
+  const token = INSET_TOKEN_RE.exec(positionArea)?.[1] ?? positionArea;
+  const side = token.split("-")[0];
+  return side in SWIPE_AXIS_BY_SIDE ? side : null;
+};
+
 // The placement needs pixels: a value only CSS could evaluate (a percentage, a
 // calc()…) would put the popover at NaN, which is the top of the page.
 const resolveMarginInPixels = (margin, name) => {
@@ -110173,7 +110313,7 @@ const SidePanel = ({
 }) => {
   import.meta.css = [css, "@jsenv/navi/src/layout/side_panel.jsx"];
   const rest = dropPickerPopupProps(restGiven, "SidePanel");
-  const onSwipePointerDown = closeByDrag ? createSwipeToClose(side) : null;
+  const onSwipePointerDown = closeByDrag ? createSwipeToClose([side]) : null;
   return jsx(Popup, {
     mode: mode
     // Spread rather than written: the collision warning between `signal` and