@jsenv/navi 0.30.35 → 0.30.37

package/dist/jsenv_navi.js

@@ -29381,8 +29381,9 @@ const debug$2 = (...args) => {
  *   policy as that verb, and is a write of its own for a dependent:
  *   `{ resource: ORDER, on: ["cancel"] }`. Its `rerunOn` says which reads of
  *   this resource it reruns (`{ GET_RANGE: true }`); a read it leaves out
- *   follows `rerunOn` for its verb. A name a verb takes, or one the resource
- *   already exposes (`withParams`, `store`…), throws. A `.scopedOne()` or
+ *   follows `rerunOn` for its verb. A verb's name in any case (`post`,
+ *   `get_many`…), or one the resource already exposes (`withParams`, `store`…),
+ *   throws. A `.scopedOne()` or
  *   `.scopedMany()` takes `writes` too, `.scopedMany()` with the plural verbs.
  * @param {{ GET?: { ms?: number, max?: number }, GET_MANY?: { ms?: number, max?: number } }} [restCallbacks.keep] -
  *   how long an answer of a read is trusted, coming back to the same params
@@ -30938,12 +30939,15 @@ ${name}.many("${propertyName}") source location: ${declarationSite}`,
 
   // expose one action per write named in `writes`
   if (writes) {
+    const membersExposed = Object.keys(stateFacade).filter(
+      (key) => !VERB_KEYS.includes(key),
+    );
     for (const [writeName, write] of Object.entries(writes)) {
       assertWriteCanBeNamed(
         name,
         writeName,
         write,
-        stateFacade,
+        membersExposed,
         namedWriteVerbs,
       );
       const { verb: writeVerb, callback, rerunOn: writeRerunOn } = write;
@@ -31256,7 +31260,7 @@ const assertWriteCanBeNamed = (
   name,
   writeName,
   write,
-  stateFacade,
+  membersExposed,
   namedWriteVerbs,
 ) => {
   const where = `resource(${name}) writes.${writeName}`;
@@ -31265,9 +31269,9 @@ const assertWriteCanBeNamed = (
       `${where}: "${writeName}" is a verb's name — a write named in "writes" takes a name of its own (cancel, archive…)`,
     );
   }
-  if (Object.hasOwn(stateFacade, writeName)) {
+  if (membersExposed.includes(writeName)) {
     throw new Error(
-      `${where}: the resource already exposes "${writeName}" — pick another name`,
+      `${where}: the resource already exposes "${writeName}" — a write takes a name none of its members has: ${membersExposed.join(", ")}`,
     );
   }
   if (!write || typeof write !== "object") {
@@ -75472,18 +75476,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
@@ -75498,7 +75503,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 = {
@@ -75507,12 +75512,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
@@ -75520,11 +75540,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;
@@ -75541,6 +75567,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,
@@ -75550,7 +75581,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));
@@ -75562,21 +75593,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();
@@ -75584,79 +75616,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(" ")})`;
 };
 
 /**
@@ -77438,7 +77485,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
@@ -78531,6 +78578,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()
@@ -78761,6 +78818,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.
@@ -79212,6 +79283,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
@@ -79339,6 +79411,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".`);
   }
@@ -80172,6 +80245,7 @@ const usePopoverProps = props => {
       }
     }
   });
+  const swipeToClose = swipeToCloseSides ? createSwipeToClose(swipeToCloseSides) : null;
   Object.assign(contentProps, {
     id,
     tabIndex,
@@ -80250,6 +80324,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, {
@@ -80323,6 +80417,31 @@ 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);
+    return sides.length ? sides : null;
+  }
+  const side = dockedSideOf(positionArea);
+  if (!side) {
+    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) => {
@@ -90629,8 +90748,19 @@ const useItemStore = ({
   // was asked for, and the window keeps growing meanwhile: dropping what the
   // page did not cover empties items on screen.
   const staleRanksRef = useRef(null);
+  // A run standing for no item has no rank to mark: its count is what is from
+  // before, and no window frames anything that would ask for it again.
+  const countStaleRef = useRef(false);
+  const markHeldStale = () => {
+    staleRanksRef.current = new Set(pages.byIndex.keys());
+    countStaleRef.current = pages.count === 0;
+  };
   if (staleRanksRef.current === null) {
-    staleRanksRef.current = restored ? new Set(pages.byIndex.keys()) : new Set();
+    if (restored) {
+      markHeldStale();
+    } else {
+      staleRanksRef.current = new Set();
+    }
   }
   const takeInPage = ({
     pageItems,
@@ -90669,6 +90799,7 @@ const useItemStore = ({
       i++;
     }
     pages.count = pageCount;
+    countStaleRef.current = false;
     // Which rank holds which id, kept by the source so a list drawing
     // this collection again finds it drawn (see readComposition above).
     if (itemsAction.writeComposition) {
@@ -90704,7 +90835,7 @@ const useItemStore = ({
   const invalidationRef = useRef(invalidation);
   if (invalidationRef.current !== invalidation) {
     invalidationRef.current = invalidation;
-    staleRanksRef.current = new Set(pages.byIndex.keys());
+    markHeldStale();
   }
   // The one request in flight, with the means to call it off: a page asked for
   // a window the list has left is work the server and the browser are doing for
@@ -90902,7 +91033,8 @@ const useItemStore = ({
           rank++;
         }
       }
-      const revalidating = staleFrom !== -1;
+      const countStale = countStaleRef.current;
+      const revalidating = staleFrom !== -1 || countStale;
       // The list is held on an item nothing on screen leads to: the items it holds
       // do not contain it, so no window it could draw will ever bring it. Only
       // asking for it by name does.
@@ -90918,6 +91050,10 @@ const useItemStore = ({
         const from = typeof wanted.index === "number" ? rankOfIndex(wanted.index) - Math.floor(budget / 2) : 0;
         start = from < 0 ? 0 : from;
         end = start + budget - 1;
+      } else if (countStale) {
+        // Nothing drawn to anchor on: the first page, like the very first ask.
+        start = 0;
+        end = budget - 1;
       } else if (revalidating) {
         // The items from before that the window draws, and the missing ones
         // with them: one ask.
@@ -91119,6 +91255,7 @@ const useItemStore = ({
               staleRanksRef.current.delete(rank);
               rank++;
             }
+            countStaleRef.current = false;
             setRefreshing(false);
             return;
           }
@@ -108030,7 +108167,7 @@ const SidePanel = ({
 }) => {
   import.meta.css = [css, "@jsenv/navi/src/layout/side_panel.jsx"];
   const rest = dropPickerPopupProps(restGiven);
-  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