@jsenv/navi 0.29.457 → 0.29.459

package/dist/dev/jsenv_navi.js

@@ -11310,27 +11310,29 @@ const updateDocumentState = (value) => {
  * `state`:
  * - `undefined` — a neutral navigation: a link click, a `replaceUrl` writing a
  *   search param. A **replace** stays on the entry the document is already on,
- *   so what that entry holds stays with it. A **push** opens a NEW entry, and
- *   what was written for the one being left — an open dialog, an expanded
- *   picker (see `useNavState`) — describes that entry alone: carried forward it
- *   would reopen on the next screen, and on the one after that, until something
- *   mounting the same id opens out of nowhere.
+ *   so what that entry holds stays with it. A **push** opens a NEW entry. One
+ *   arriving at another page (`isArrival`, see scroll_restoration.js) starts
+ *   empty: what was written for the entry being left — an open dialog, an
+ *   expanded picker (see `useNavState`) — describes that entry alone, and
+ *   carried forward it would reopen on the next screen, and on the one after
+ *   that, until something mounting the same id opens out of nowhere. A push
+ *   that keeps the page (a layer bound to a search param, opened over it)
+ *   carries the state: whatever holds it is still mounted under the new
+ *   address, and an empty entry would close it there — an expanded row
+ *   collapsing under the layer, expanding again when the back takes it away.
  * - `null` — an explicit reset.
  * - an object — built by the caller (`enter()`/`leave()` copy the current state
  *   themselves), taken as given.
  *
- * `sharedState` always wins: it describes the document, not the entry.
- *
- * The push/replace split is the Navigation API's own rule for a `navigate()`
- * carrying no state — which is why via_navigation.js gets it from the browser
- * and via_history.js has to spell it out to say the same thing.
+ * `currentState` is what the entry being left holds. `sharedState` always
+ * wins: it describes the document, not the entry.
  */
 const resolveEffectiveDocumentState = (
   state,
-  { navigationType, currentState, sharedState },
+  { navigationType, isArrival, currentState, sharedState },
 ) => {
   if (state === undefined) {
-    if (navigationType === "push") {
+    if (navigationType === "push" && isArrival) {
       return sharedState;
     }
     return { ...(currentState || {}), ...sharedState };
@@ -11874,6 +11876,8 @@ const startAtTop = (url, { from } = {}) => {
   positionByUrl.set(href, { x: 0, y: 0 });
   window.scrollTo({ top: 0, left: 0, behavior: "instant" });
 };
+// Also what decides whether a push carries the state of the page it keeps
+// (see resolveEffectiveDocumentState).
 const isArrival = (url, { from }) => {
   if (
     from !== undefined &&
@@ -12309,7 +12313,8 @@ const setupBrowserIntegrationViaHistory = ({
 
   const applyRoutingTask = (url, options) => {
     // Read before the history is written: the url the reader is being taken
-    // away from, which is what decides where a push lands (see startAtTop).
+    // away from, which is what decides where a push lands (see startAtTop) and
+    // whether it carries the state (see resolveEffectiveDocumentState).
     const urlLeft = readAddress();
     const {
       reason,
@@ -12329,6 +12334,7 @@ const setupBrowserIntegrationViaHistory = ({
       markUrlAsVisited(url);
       const effectiveState = resolveEffectiveDocumentState(state, {
         navigationType,
+        isArrival: isArrival(url, { from: urlLeft }),
         currentState: getDocumentState(),
         sharedState: {
           jsenv_visited_urls: Array.from(visitedUrlSet),
@@ -39484,6 +39490,14 @@ const activeRouteReadsSignal = computed(() => {
  *   params read: that address is the current one with the state set to the
  *   popup's value (see `prefetch` on Button).
  * @param {object} [options]
+ * @param {() => any} [options.when] - a condition on app state the action
+ *   asks under, read off signals like the params: falsy, it runs nothing.
+ *   Unlike a params function it leaves the action asking nothing of the
+ *   address, so a link to the route still prefetches an action without
+ *   params when the condition holds at that moment — a page's code only some
+ *   readers may download (`() => meIsAdminSignal.value`). A condition reading
+ *   the address belongs in the params: a link reads `when` as it is, not as
+ *   the address it leads to will make it.
  * @param {boolean} [options.prefetch=true] - `false` keeps the action from
  *   being prerun ahead of what asks for it, when the read is not worth a
  *   hover or a press that may not end in an opening.
@@ -39492,7 +39506,7 @@ const routeAction = (
   routeOrRoutes,
   action,
   paramsEffect,
-  { prefetch = true, ...options } = {},
+  { when, prefetch = true, ...options } = {},
 ) => {
   if (typeof action === "function") {
     action = createAction(action);
@@ -39502,7 +39516,12 @@ const routeAction = (
     routes.length === 1
       ? routes[0].matchingSignal
       : anyMatchingRouteSignal(routes);
-  const readParams = paramsEffect || (() => true);
+  const readParams = () => {
+    if (when && !when()) {
+      return null;
+    }
+    return paramsEffect ? paramsEffect() : true;
+  };
   const readParamsAsked = () => {
     const matching = routeMatchingSignal.value;
     const params = readParams();
@@ -39538,10 +39557,13 @@ const routeAction = (
     for (const route of routes) {
       if (paramsEffect) {
         registerRouteStatePreload(route, (values) => {
-          prefetchAsIf(action, paramsEffect, values);
+          prefetchAsIf(action, readParams, values);
         });
       } else {
         registerRoutePreload(route, () => {
+          if (!untracked(readParams)) {
+            return;
+          }
           prerunAhead(action.bindParams(true));
         });
       }
@@ -39554,12 +39576,12 @@ const routeAction = (
 // (see readStateAsIf), prerun only when that changes them: params the state
 // leaves alone are the ones the action already runs on — or is meant not to,
 // and a prerun would retry a FAILED one behind the screen's back.
-const prefetchAsIf = (action, paramsEffect, values) => {
-  const params = readStateAsIf(values, paramsEffect);
+const prefetchAsIf = (action, readParams, values) => {
+  const params = readStateAsIf(values, readParams);
   if (!params) {
     return;
   }
-  if (compareTwoJsValues(params, untracked(paramsEffect))) {
+  if (compareTwoJsValues(params, untracked(readParams))) {
     return;
   }
   prerunAhead(action.bindParams(params));