@jsenv/navi 0.30.26 → 0.30.28

package/dist/dev/jsenv_navi.js

@@ -2,7 +2,7 @@
  * AI reading this file: read ../docs/AI_INSTRUCTIONS.md for context on
  * using @jsenv/navi as intended.
  */
-import { installImportMetaCssBuild, coarsePointerSignal, windowHeightSignal, windowWidthSignal, visualViewportHeightSignal, visualViewportWidthSignal, getAppHeight, getAppWidth, smallTouchScreenSignal } from "./jsenv_navi_side_effects.js";
+import { installImportMetaCssBuild, coarsePointerSignal, windowHeightSignal, windowWidthSignal, visualViewportHeightSignal, visualViewportWidthSignal, getAppHeight, getAppWidth, smallTouchScreenSignal, getSafeAreaInsets } from "./jsenv_navi_side_effects.js";
 import { createPubSub, createIterableWeakSet, elementIsFocusable, getScrollContainer, dispatchInternalCustomEvent, dispatchCustomEvent, createEventGroupLogger, findEvent, mergeOneStyle, findFocusable, getElementSignature, chainEvent, isTouchDrivenEvent, getKeyboardEventDefaultAction, isPressDrivenClick, getVisuallyVisibleInfo, getFirstVisuallyVisibleAncestor, createValueEffect, findFocusDelegateTarget, scrollIntoViewThroughScrollables, allowWheelThrough, dispatchPublicCustomEvent, resolveCSSColor, getScrollContainerSet, ELEMENT_SIZE_CHANGE, findSelfOrAncestorFixedPosition, visibleRectEffect, pickPositionRelativeTo, getBorderSizes, getPaddingSizes, applyNewPosition, measureLongestVisualLineWidth, keepTouchRefusable, waitForTap, waitForPressHeld, suppressClickAfterGesture, startDragToTravel, dragSourceThatStoodDown, markDragSource, refuseDragTo, startDragTo, installPanZoom, createInternalCustomEvent, activeElementSignal, normalizeStyle, getPositionedParent, normalizeStyles, createGroupTransitionController, getBorderRadius, preventIntermediateScrollbar, createOpacityTransition, trapScrollInside, scrollIntoViewScoped, isPressDisputedByDrag, closestOpenableAncestor, isAncestorOpen, isDisplayedDespiteClosedAncestor, observeAncestorOpenState, getAncestorOpenType, findBefore, findAfter, resolveCSSSize, hasCSSSizeUnit, releaseWheelGesture, getScrollIntoViewScopedOffsets, wheelGestureIsTakenFrom, claimWheelGesture, initFocusGroup, stringifyStyle as stringifyStyle$1, isScrollable, resolveOklchLightness, contrastColor, scrollRoomTowards, overflowGoesToViewport, getVirtualKeyboardOverlayHeight, subscribeVisualViewportResizeSettled, subscribeVirtualKeyboardGeometryChange, parsePositionArea, snapToPixel, trapFocusInside, onAncestorReopen, canScroll, measureWidestChildRow, performTabNavigation, dragAfterIntent, stickyAsRelativeCoords, createDragToMoveGestureController, getDropTargetInfo, setStyles, useActiveElement, setVirtualKeyboardOverlaysContent } from "@jsenv/dom";
 export { chainEvent, clickIsSuppressed, contrastColor, createDragGestureController, dragAfterIntent, findEvent, markDragSource, startDragTo } from "@jsenv/dom";
 import { signal, computed, effect, untracked, batch, useComputed, useSignal } from "@preact/signals";
@@ -810,6 +810,91 @@ const stringifyForDisplay = (
   return String(value);
 };
 
+/*
+ * Who asks for an action instance right now, and what a run called off for
+ * want of askers owes to whoever comes next.
+ *
+ * Instances are shared by params: two route actions reading the same thing
+ * with the same params, or a route action and a component reading it with
+ * `run: true`, ask ONE instance. So a binding whose params turn falsy (its
+ * route left) does not own the run in flight: it calls it off only when
+ * nothing else asks for that instance at that moment. What asks is an asker:
+ * a binding of actionRunEffect while its params are truthy, a mounted
+ * `useAsyncData` reader with `run: true`. Each says which instance it asks for
+ * when the question is put, rather than registering one: a reader of a
+ * binding follows the binding's target the moment it moves, not at its next
+ * render.
+ *
+ * Calling a run off is a guess about who is coming: a reader mounting after
+ * it (the page arriving), or suspended before its first commit, finds an
+ * instance nobody will run again. So the instance is marked, and a `run: true`
+ * reader finding it marked asks again, as an arriving binding does when its
+ * run() finds the instance aborted. An abort decided by anyone else (abort(),
+ * a give-up on a busy popup) carries no mark: aborting does not undo, and the
+ * reader leaves it be.
+ */
+
+const askerSet = createIterableWeakSet("action_asker");
+
+/**
+ * `readAskedInstance()` returns what is asked for now: an instance, a binding
+ * (its current target is what counts), or null. The asker is held weakly:
+ * whoever adds it keeps it, and removes it once it asks for nothing for good.
+ */
+const addActionAsker = (readAskedInstance) => {
+  const asker = { readAskedInstance };
+  askerSet.add(asker);
+  return asker;
+};
+const removeActionAsker = (asker) => {
+  askerSet.delete(asker);
+};
+
+const calledOffWeakSet = new WeakSet();
+
+/**
+ * Aborts the instance's run unless an asker asks for it, and marks a run
+ * called off that way (see isCalledOffForWantOfAskers).
+ */
+const callOffUnlessAsked = (action, reason) => {
+  const instance = resolveInstance(action);
+  for (const asker of askerSet) {
+    if (resolveInstance(asker.readAskedInstance()) === instance) {
+      return;
+    }
+  }
+  if (!instance.abort(reason)) {
+    return;
+  }
+  // A callback that ignores its abort signal completes all the same.
+  if (instance.runningStateSignal.peek() !== ABORTED) {
+    return;
+  }
+  calledOffWeakSet.add(instance);
+  // The mark is for this abort only: once the instance moves, an abort that
+  // comes later is somebody else's.
+  const unsubscribe = instance.runningStateSignal.subscribe((state) => {
+    if (state !== ABORTED) {
+      calledOffWeakSet.delete(instance);
+      unsubscribe();
+    }
+  });
+};
+
+const isCalledOffForWantOfAskers = (action) => {
+  return calledOffWeakSet.has(resolveInstance(action));
+};
+
+// A binding counts as the instance it targets now. Read as it stands, never
+// through getCurrentAction(), which would flush a debounced binding.
+const resolveInstance = (action) => {
+  let instance = action;
+  while (instance && instance.isProxy) {
+    instance = getActionPrivateProperties(instance).currentAction;
+  }
+  return instance;
+};
+
 const SYMBOL_OBJECT_SIGNAL = Symbol.for("navi_object_signal");
 
 /*
@@ -5324,6 +5409,8 @@ const writeActionState = (write) => {
   }
 };
 
+const askerByBindingWeakMap = new WeakMap();
+
 /**
  * Reactively runs an action whenever the params derived from signals change.
  *
@@ -5420,8 +5507,9 @@ const actionRunEffect = (
       if (actionTargetPrevious && actionTarget) {
         // params changed
         if (!asking) {
-          // falsy params, don't run
-          actionTargetPrevious.abort("abortOnFalsyParams");
+          // falsy params, don't run; the instance is shared by params, and
+          // something else may still ask for it (see action_askers.js)
+          callOffUnlessAsked(actionTargetPrevious, "abortOnFalsyParams");
           return;
         }
         if (!askingBefore) {
@@ -5447,6 +5535,11 @@ const actionRunEffect = (
     },
     ...options,
   });
+  // Held by the binding, as long as it lives: askers are held weakly.
+  askerByBindingWeakMap.set(
+    actionRunnedByThisEffect,
+    addActionAsker(() => (asking ? actionRunnedByThisEffect : null)),
+  );
   if (asking) {
     runUnwatched(() =>
       actionRunnedByThisEffect.run({ reason: "initial truthy params" }),
@@ -10319,8 +10412,10 @@ const ROUTE_ACTION_BINDING_OPTIONS = new Set([
 /**
  * Binds an action to a route: it runs when the route matches, with the params
  * the effect reads off the address, runs again on a `reload()`, and is aborted
- * when the route is left. Its data, its wait and its failure are read by the
- * page through `useAsyncData`.
+ * when the route is left, unless something else still asks for the same read
+ * with the same params: another route action, a mounted `useAsyncData` with
+ * `run: true`. Its data, its wait and its failure are read by the page through
+ * `useAsyncData`.
  *
  * A page's CODE is declared the same way — the import is one more thing the
  * address asks for, started with the data rather than after it:
@@ -33107,6 +33202,11 @@ const useForceRender = () => {
  *   failure a prerun left (a `prerun: true` head start, a press that preran
  *   it): nothing on screen asked for that run, so this asks again, once.
  *
+ *   While mounted, it asks for that instance as a route action does: a route
+ *   action reading the same thing with the same params does not call the run
+ *   off under it when its route is left. A run called off that way before
+ *   this component was there to ask is asked again.
+ *
  *   Prefer a `routeAction` wherever the parameter is one the address holds (a
  *   path param, a search param bound to a `stateSignal`), popup included: it is
  *   asked for when the address changes, with everything else that address
@@ -33256,6 +33356,20 @@ const useActionAsyncData = (action, {
   }
   useOnLoad(action, onLoad);
   usePoll(action, poll);
+  const routePage = useContext(RoutePageContext);
+
+  // `run: true` asks for the instance as long as this reader is mounted: a
+  // binding sharing it whose route is left does not call the run off under it
+  // (see action_askers.js). Asked through the binding itself, whose target
+  // moves before this renders again.
+  const askedRef = useRef(null);
+  askedRef.current = run ? action : null;
+  useLayoutEffect(() => {
+    const asker = addActionAsker(() => askedRef.current);
+    return () => {
+      removeActionAsker(asker);
+    };
+  }, []);
 
   // The instance the binding points at, remembered from one render to the
   // next: a binding that comes back to params whose instance failed — a search
@@ -33268,6 +33382,11 @@ const useActionAsyncData = (action, {
   const instanceRef = useRef(instance);
   const backOnFailure = instanceRef.current !== instance && action.runningStateSignal.peek() === FAILED;
   instanceRef.current = instance;
+  // A run called off because nothing asked for it any more, before this reader
+  // was there to ask (mounting after, or suspended before its first commit):
+  // nobody else will run it again. Not from a page the address has left, whose
+  // own route action is what called it off.
+  const calledOffBeforeThisReader = isCalledOffForWantOfAskers(action) && !(routePage && !routePage.isShown());
   // `run: true` — this component owns the request, so it is what starts it, and
   // it starts it from the render rather than from an effect: a component that
   // suspends has no effects, so a run written in one would be waiting for
@@ -33275,7 +33394,7 @@ const useActionAsyncData = (action, {
   // no-op — which is what makes starting it while rendering sound. From there
   // the wait is the ordinary one: suspended into <Loading>, or drawn by the
   // component under `loading: true`, exactly as for data someone else ran.
-  if (run && action.paramsSignal.peek() !== undefined && (runIsOwed(action) || backOnFailure)) {
+  if (run && action.paramsSignal.peek() !== undefined && (runIsOwed(action) || backOnFailure || calledOffBeforeThisReader)) {
     // Nothing waits on this run: the failure is held by the action, and this
     // hook is what reads it back.
     runUnwatched(() => action.run({
@@ -33298,7 +33417,6 @@ const useActionAsyncData = (action, {
   // has already processed the settlement and the detached DOM is discarded.
   const runningState = action.runningStateSignal.peek();
   const [, setTick] = useState(0);
-  const routePage = useContext(RoutePageContext);
   // What this render read of the action, for the subscriptions below to tell
   // a change that came between the render and them from none at all.
   const readRef = useRef(null);
@@ -33403,6 +33521,16 @@ const useActionAsyncData = (action, {
   if (runningState === COMPLETED) {
     return [action.dataSignal.peek(), false, undefined];
   }
+  // Called off (abort(), a route left with nothing else asking for it): nothing
+  // is on its way until something runs it again. What it held stays drawn and
+  // no wait is claimed. A delegated wait holding nothing has nothing to draw,
+  // and suspends below until the next run.
+  if (runningState === ABORTED) {
+    const dataHeld = action.dataSignal.peek();
+    if (dataHeld !== undefined || loadingEffect === "use") {
+      return [dataHeld, false, undefined];
+    }
+  }
   if (runningState === FAILED) {
     if (prerun) {
       // Neither shown nor reported from a head start: the failure is the
@@ -33478,8 +33606,7 @@ const useActionAsyncData = (action, {
 
   // `loading: true` says the component draws its own wait, so this hook never
   // suspends: running, or holding params nobody has started yet — a debounced
-  // binding that just retargeted, an aborted run, a run this very render is
-  // about to issue. Either way what is on screen is not the current answer,
+  // binding that just retargeted, a run this very render is about to issue. Either way what is on screen is not the current answer,
   // which is what `loading` says. Suspending would not draw a spinner: it swaps
   // the subtree for the boundary, and everything under it remounts — a dialog
   // open inside it is then closed, by a hook the caller told to stay out of it.
@@ -33487,7 +33614,8 @@ const useActionAsyncData = (action, {
     return [action.dataSignal.peek(), true, undefined];
   }
 
-  // IDLE or RUNNING with loadingEffect: "delegate" — suspend
+  // IDLE, RUNNING, or called off holding nothing, with loadingEffect:
+  // "delegate" — suspend
   const reason = runningState === RUNNING ? "loading" : "idle";
   loadingRef.current = {
     reason,
@@ -33506,6 +33634,13 @@ const useActionAsyncData = (action, {
           actionPendingPromiseWeakMap.delete(action);
           unsubscribe();
           resolve();
+        } else if (reason === "loading" && state === ABORTED) {
+          // The run waited on was called off: drawn again, this reader asks
+          // for it again when nothing else will (calledOffBeforeThisReader),
+          // draws what the instance held, or waits for the next run as idle.
+          actionPendingPromiseWeakMap.delete(action);
+          unsubscribe();
+          resolve();
         }
       });
     });
@@ -61120,6 +61255,7 @@ const measureDrawing = ({
  * never seen under a bar, and after every read of the commit that queued them.
  */
 
+
 // Several bars can share an edge — during a page transition the outgoing and
 // the incoming one are both mounted. They are all pinned to that same edge, so
 // they overlap: the room to give back is the largest of them, not their sum,
@@ -61137,6 +61273,12 @@ const pendingSizeMapByArea = new Map();
 let flushMicrotaskQueued = false;
 let flushFrame = null;
 
+// The safe area moves with these writes and no resize comes with them: what is
+// placed in it (a Popover with container="safe-area") is told here.
+const [publishFixedBarSpaceChange, subscribeFixedBarSpaceChange] =
+  createPubSub();
+const onFixedBarSpaceChange = subscribeFixedBarSpaceChange;
+
 // A size a render produced: a prop, the children or a theme variable changed
 // the bar, and the room it takes is given back before that commit is painted.
 /**
@@ -61187,13 +61329,19 @@ const queueSize = (area, barElement, size) => {
 };
 
 const flushPendingSizes = () => {
+  let written = false;
   for (const [area, pendingSizeMap] of pendingSizeMapByArea) {
     for (const [barElement, size] of pendingSizeMap) {
       storeSize(area, barElement, size);
     }
-    writeSpace(area);
+    if (writeSpace(area)) {
+      written = true;
+    }
   }
   pendingSizeMapByArea.clear();
+  if (written) {
+    publishFixedBarSpaceChange();
+  }
 };
 
 const storeSize = (area, barElement, size) => {
@@ -61220,18 +61368,20 @@ const writeSpace = (area) => {
   const property = `--navi-fixed-bar-space-${area}`;
   const { style } = document.documentElement;
   if (sizeMap.size === 0) {
-    if (writtenValueByArea.has(area)) {
-      writtenValueByArea.delete(area);
-      style.removeProperty(property);
+    if (!writtenValueByArea.has(area)) {
+      return false;
     }
-    return;
+    writtenValueByArea.delete(area);
+    style.removeProperty(property);
+    return true;
   }
   const value = `${largestSize}px`;
   if (writtenValueByArea.get(area) === value) {
-    return;
+    return false;
   }
   writtenValueByArea.set(area, value);
   style.setProperty(property, value);
+  return true;
 };
 
 installImportMetaCssBuild(import.meta);
@@ -76143,8 +76293,9 @@ const needsPopupFromMount = (props) => {
  * (measured by wematch, 2026-09-06: no panel at all for 120ms, then a panel
  * with its head missing, then the head arriving from below). So the cut is
  * taken only where it hides something the screen would otherwise show — the
- * band of glass beside an app narrowed with --navi-app-max-width — and is a
- * constant everywhere else: at layer="top" the viewport's own edge cuts the
+ * band of glass beside an app narrowed with --navi-app-max-width, the fixed
+ * bars beside a popover placed in the safe area — and is a constant
+ * everywhere else: at layer="top" the viewport's own edge cuts the
  * travel on the compositor for free, and at layer="local" the clip wrapper
  * (a static ancestor, overflow: hidden) does. Where a band exists the cut
  * still animates and still can drift under load; the full answer there is a
@@ -76276,22 +76427,34 @@ const popupCss = /* css */ `
        0 for a 0 band and 100vmax for any other, a step written without a
        branch. See this file's top comment for why an animated cut has to be
        that rare. */
+    --x-popup-area-inset-top: var(--navi-app-inset-top, 0px);
+    --x-popup-area-inset-right: var(--navi-app-inset-right, 0px);
+    --x-popup-area-inset-bottom: var(--navi-app-inset-bottom, 0px);
+    --x-popup-area-inset-left: var(--navi-app-inset-left, 0px);
     --x-popup-cut-top-at-area: calc(
       -1 * var(--container-position-room-top, 100vmax) - 100vmax +
-        min(100vmax, var(--navi-app-inset-top, 0px) * 1000000)
+        min(100vmax, var(--x-popup-area-inset-top) * 1000000)
     );
     --x-popup-cut-right-at-area: calc(
       -1 * var(--container-position-room-right, 100vmax) - 100vmax +
-        min(100vmax, var(--navi-app-inset-right, 0px) * 1000000)
+        min(100vmax, var(--x-popup-area-inset-right) * 1000000)
     );
     --x-popup-cut-bottom-at-area: calc(
       -1 * var(--container-position-room-bottom, 100vmax) - 100vmax +
-        min(100vmax, var(--navi-app-inset-bottom, 0px) * 1000000)
+        min(100vmax, var(--x-popup-area-inset-bottom) * 1000000)
     );
     --x-popup-cut-left-at-area: calc(
       -1 * var(--container-position-room-left, 100vmax) - 100vmax +
-        min(100vmax, var(--navi-app-inset-left, 0px) * 1000000)
+        min(100vmax, var(--x-popup-area-inset-left) * 1000000)
     );
+    /* Placed in the safe area (Popover's container="safe-area"): past its edge
+       lie the fixed bars, and a popup sliding in comes out from behind them. */
+    &[data-container="safe-area"] {
+      --x-popup-area-inset-top: var(--navi-safe-area-inset-top);
+      --x-popup-area-inset-right: var(--navi-safe-area-inset-right);
+      --x-popup-area-inset-bottom: var(--navi-safe-area-inset-bottom);
+      --x-popup-area-inset-left: var(--navi-safe-area-inset-left);
+    }
     /* The translate property is deliberately absent from this list — it
        carries where the popup stands, and applyNewPosition (visible_rect.js)
        owns it and drives its own transition through the Web Animations API
@@ -80183,6 +80346,14 @@ const css$C = /* css */`
  *   (`"3appw"`) or a container length (`"3cqw"`).
  * @param {string|number} [props.marginWithAnchor=0] - Extra spacing kept
  *   between the popover and the edges of its anchor, written the same way.
+ * @param {"app"|"safe-area"} [props.container="app"] - The rectangle a
+ *   `layer="top"` popover is placed in: docked against with no anchor,
+ *   flipped and clamped within with one. `"app"`: the app's own screen, its
+ *   fixed bars included — the popover covers them. `"safe-area"`: that screen
+ *   less the bars and the device's own bands (`--navi-safe-area-inset-*`), for
+ *   something docked over the page that must leave the bars uncovered, a
+ *   toast. Followed live as a bar comes or goes. Still in the top layer, so
+ *   above what the page holds. See docs/safe_area.md.
  * @param {boolean} [props.backdrop=true] - Whether anything is laid between
  *   the popover and the page at all — asked before what an outside press does
  *   and before how the backdrop is painted. `false` leaves the page
@@ -80614,6 +80785,7 @@ const usePopoverProps = props => {
     // "center" default.
     positionAreaWhenAnchorIsInvalid,
     marginWithContainer = 0,
+    container = "app",
     // "close"  → pointer press outside closes (a plain close = commit)
     // "cancel" → pointer press outside closes AS A CANCEL (revert)
     // "capture"→ absorb the press, stay open
@@ -80705,6 +80877,10 @@ const usePopoverProps = props => {
     })
   }) : null;
   const isTopLayer = layer === "top";
+  if (!isTopLayer && container !== "app") {
+    console.warn(`Popover: container="${container}" is for layer="top". A layer="local" popover is placed in its positioned ancestor; put that ancestor where it should be.`);
+  }
+  const placesInSafeArea = isTopLayer && container === "safe-area";
   const ref = props.ref;
   const backdropRef = useRef();
   // Disarms a still-pending backdrop hide from a previous close (see
@@ -80756,14 +80932,15 @@ const usePopoverProps = props => {
     positionAreaFixed,
     positionAreaWhenAnchorIsInvalid,
     marginWithAnchor,
-    marginWithContainer
+    marginWithContainer,
+    placesInSafeArea
   };
   const repositionRef = useRef(null);
   useEffect(() => {
     repositionRef.current?.(new CustomEvent("position_props_change", {
       detail: {}
     }));
-  }, [positionArea, positionAreaFixed, positionAreaWhenAnchorIsInvalid, marginWithAnchor, marginWithContainer]);
+  }, [positionArea, positionAreaFixed, positionAreaWhenAnchorIsInvalid, marginWithAnchor, marginWithContainer, placesInSafeArea]);
   // The freeze is taken where the value changes, not only at open time: a
   // popover showing skeletons first says sizing="auto" until its content is
   // there, and would otherwise be held at the size of the waiting state.
@@ -81022,8 +81199,11 @@ const usePopoverProps = props => {
         positionAreaFixed,
         positionAreaWhenAnchorIsInvalid,
         marginWithAnchor,
-        marginWithContainer
+        marginWithContainer,
+        placesInSafeArea
       } = positionPropsRef.current;
+      // undefined keeps the app's own screen (setPlacementViewportInsets).
+      const viewportInsets = placesInSafeArea ? getSafeAreaInsets() : undefined;
       let position;
       if (hasAnchorElement) {
         const {
@@ -81062,6 +81242,7 @@ const usePopoverProps = props => {
           // renderer, same as omitting `container` entirely would resolve
           // to on its own.
           container: positionedAncestor,
+          viewportInsets,
           minLeft,
           event: positionEvent
         };
@@ -81108,6 +81289,7 @@ const usePopoverProps = props => {
         const pickOptions = {
           positionArea,
           container: positionedAncestor,
+          viewportInsets,
           marginWithContainer: resolveMarginInPixels(marginWithContainer, "marginWithContainer"),
           event: positionEvent
         };
@@ -81229,6 +81411,20 @@ const usePopoverProps = props => {
     // while open (e.g. an expand/collapse toggle inside it) — not just when
     // the anchor itself moves/resizes/re-anchors.
     rectEffect.observeSize(popoverEl);
+    // A bar mounting or leaving moves the safe area and leaves the viewport as
+    // it was, so rectEffect.check() would find nothing changed: placed
+    // directly. "resize", so the popover glides to its new place.
+    if (isTopLayer) {
+      addCleanup(onFixedBarSpaceChange(() => {
+        if (!positionPropsRef.current.placesInSafeArea) {
+          return;
+        }
+        if (deferPlacementWhileCovered(popoverEl)) {
+          return;
+        }
+        placeUnlessAnchorOutOfView(new CustomEvent("resize"));
+      }));
+    }
     // Whatever its own backdrop: a modal dialog above leaves all of the page
     // inert, a popover without a wall included. layer="local" is left out, its
     // ceiling answers to its container.
@@ -81570,6 +81766,7 @@ const usePopoverProps = props => {
     id,
     tabIndex,
     "data-layer": layer,
+    "data-container": placesInSafeArea ? "safe-area" : undefined,
     "data-expand-x": expand || expandX ? "" : undefined,
     "data-expand-y": expand || expandY ? "" : undefined,
     "navi-animation": isAutoAnimation ? undefined : animation,