@jsenv/navi 0.30.9 → 0.30.10

package/dist/jsenv_navi.js

@@ -8425,17 +8425,35 @@ const route = (pattern, options = {}) => {
       return `route "${cleanPattern}"`;
     },
   };
-  // Asks ahead of the arrival for what this route's actions ask without the
-  // address — a page's code, a read without params (see routeAction). An
-  // action keyed by a param waits for the arrival: a prefetch has no address
-  // (preloadState is the one that has one).
-  route.preload = () => {
+  /**
+   * Asks ahead of the arrival for what this route's actions will ask: the
+   * instances the arrival promotes to runs (see prerunAhead in route_action.js).
+   *
+   * Without params, only what asks nothing of the address: the page's code, a
+   * read without params — what a link preloads, since it has no state to read
+   * the params of. Given params, `{}` included, the address `buildUrl(params)`
+   * leads to: every route action of this route reads its params as if the
+   * route matched there (see statesAt).
+   *
+   * @param {object} [params]
+   */
+  route.preload = (params) => {
     const preloadSet = routePreloadMap.get(route);
-    if (!preloadSet) {
+    if (preloadSet) {
+      for (const preload of preloadSet) {
+        preload();
+      }
+    }
+    if (params === undefined) {
       return;
     }
-    for (const preload of preloadSet) {
-      preload();
+    const statePreloadSet = routeStatePreloadMap.get(route);
+    if (!statePreloadSet) {
+      return;
+    }
+    const values = statesAt(route, params);
+    for (const preload of statePreloadSet) {
+      preload(values);
     }
   };
   Object.preventExtensions(route);
@@ -9034,6 +9052,42 @@ const preloadState = (signal, value) => {
     }
   }
 };
+// What the states of a route will hold once the address is `route.buildUrl(params)`,
+// as the routing pass will write them (see sync_routes_with_url): a param given is
+// what its state holds there; a weak one not given is back to its default, a url
+// built for another visit never carries it (readSignalForUrlBuild); any other one
+// is carried over by that url and keeps what it holds, so it is left out.
+const statesAt = (route, params) => {
+  const values = new Map();
+  for (const connection of getRoutePrivateProperties(route).routePattern
+    .connections) {
+    const { paramName, signal } = connection;
+    if (!signal) {
+      continue;
+    }
+    if (!(paramName in params)) {
+      if (connection.weak) {
+        values.set(signal, connection.getDefaultValue());
+      }
+      continue;
+    }
+    const value = params[paramName];
+    if (value !== undefined) {
+      values.set(signal, value);
+      continue;
+    }
+    // An address silent about a persisted search param leaves it alone.
+    if (
+      connection.persists &&
+      connection.paramType === "query" &&
+      connection.history !== "push"
+    ) {
+      continue;
+    }
+    values.set(signal, connection.getDefaultValue());
+  }
+  return values;
+};
 const setupRoutes = (routes) => {
   if (setupRoutesCalled) {
     throw new Error(
@@ -9562,6 +9616,35 @@ const activeRouteActionsSignal = computed(() => {
   return active;
 });
 
+/**
+ * Calls back once every route action asking something for the page on screen
+ * has answered, none running and none about to: what is asked on behalf of
+ * another page waits for it, and never competes with the page's own reads.
+ *
+ * @param {() => void} callback
+ * @returns {() => void} cancel
+ */
+const whenPageReadsAnswered = (callback) => {
+  let cancelled = false;
+  const stop = effect(function () {
+    for (const routeAction of activeRouteActionsSignal.value) {
+      const runningState = routeAction.runningStateSignal.value;
+      // IDLE: asking, and run by an effect of the same batch that has not run yet.
+      if (runningState === RUNNING || runningState === IDLE) {
+        return;
+      }
+    }
+    this.dispose();
+    if (!cancelled) {
+      untracked(callback);
+    }
+  });
+  return () => {
+    cancelled = true;
+    stop();
+  };
+};
+
 /**
  * Whether a route action of the page on screen waits for app state to ask: its
  * route matches and its `when` says no. Params that say no are not waiting:
@@ -9642,7 +9725,9 @@ const activeRouteReadsSignal = computed(() => {
  *   come from the address is not prefetched by a link — a link's prefetch has
  *   no address. It is by the press that opens a popup bound to a state these
  *   params read: that address is the current one with the state set to the
- *   popup's value (see `prefetch` on Button).
+ *   popup's value (see `prefetch` on Button). And by `route.preload(params)`,
+ *   which names the address: what a `<RouteTravel prefetch>` asks of the pages
+ *   on each side of the one on screen.
  * @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.
@@ -9723,7 +9808,7 @@ const routeAction = (
     for (const route of routes) {
       if (paramsEffect) {
         registerRouteStatePreload(route, (values) => {
-          prefetchAsIf(action, readParams, values);
+          prefetchAsIf(action, readParams, readParamsAsked, values);
         });
       } else {
         registerRoutePreload(route, () => {
@@ -9739,15 +9824,17 @@ const routeAction = (
 };
 
 // The params as they will read once the states hold what they are about to
-// (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, readParams, values) => {
+// (see readStateAsIf), prerun only when they differ from what the action asks
+// now: params the states leave alone are the ones it already runs on — or is
+// meant not to, and a prerun would retry a FAILED one behind the screen's back.
+// An action whose route does not match asks nothing: whatever its params read,
+// the arrival runs it on them.
+const prefetchAsIf = (action, readParams, readParamsAsked, values) => {
   const params = readStateAsIf(values, readParams);
   if (!params) {
     return;
   }
-  if (compareTwoJsValues(params, untracked(readParams))) {
+  if (compareTwoJsValues(params, untracked(readParamsAsked))) {
     return;
   }
   prerunAhead(action.bindParams(params));
@@ -40652,6 +40739,7 @@ const ROW_READING = {
  *   travelByDrag?: boolean,
  *   onTravel?: (detail: {route: object, params: object|undefined, cause: string}) => void|Promise<void>,
  *   renderNeighbour?: (page: {route: object, params: object|undefined}) => import("preact").ComponentChildren,
+ *   prefetch?: boolean,
  * }>}
  * @param {Array<object|{route: object, params?: object}>} [props.routes] - a window
  *   over something longer, in order. Read from the <Route> children by default,
@@ -40675,6 +40763,12 @@ const ROW_READING = {
  *   `{ route, params }`, or the entry of `routes` as it was given, and is a column
  *   the height of the row, as the page is. Its route does not match while it stands
  *   there: what it reads is not asked for.
+ * @param {boolean} [props.prefetch=false] - whether the pages on each side of the one
+ *   on screen have their reads asked for ahead of the hand: at rest, once the page on
+ *   screen has its answers and has painted them, the next page first, each with
+ *   `route.preload(params)`. A swipe then builds a page whose answers are already
+ *   there, with no wait to show. Off by default: every page one stops on costs the
+ *   reads of two more.
  *
  * Every other prop lands on the box itself (`id`, `data-testid`, `className`, …).
  * The box has to outlive every page of its row: around those <Route>s, or around
@@ -40691,6 +40785,7 @@ const RouteTravel = ({
     routeTransition: "none"
   }),
   renderNeighbour,
+  prefetch = false,
   className,
   children,
   ...rest
@@ -40700,7 +40795,8 @@ const RouteTravel = ({
   const liveRef = useRef();
   const picturesRef = useRef();
   const windowed = Boolean(routesProp);
-  const [, render] = useReducer(count => count + 1, 0);
+  // Counts the movements ended: endMovement renders through it.
+  const [restCount, render] = useReducer(count => count + 1, 0);
   const pagesFromChildren = useMemo(() => collectRoutePages(children), [children]);
   const pagesFromProp = useMemo(() => routesProp && routesProp.map(normalizePage), [routesProp]);
   // Held while the row moves: a window recentred under a hand would move the very
@@ -41274,6 +41370,45 @@ const RouteTravel = ({
     }
   }, [currentIndex]);
 
+  // What a hand can bring is asked for at rest, the next page first: never before
+  // the page on screen has its answers and has painted them. A row in movement is
+  // not at rest; the render that ends the movement asks again. Read as pages, not as
+  // entries: the pages of <Route> children are collected again at every render.
+  const neighboursRef = useRef([null, null]);
+  const nextPage = currentIndex === -1 ? null : pages[currentIndex + 1] || null;
+  const previousPage = currentIndex === -1 ? null : pages[currentIndex - 1] || null;
+  if (!samePage(neighboursRef.current[0], nextPage) || !samePage(neighboursRef.current[1], previousPage)) {
+    neighboursRef.current = [nextPage, previousPage];
+  }
+  const neighbours = neighboursRef.current;
+  useLayoutEffect(() => {
+    if (!prefetch || movementRef.current) {
+      return undefined;
+    }
+    if (!neighbours[0] && !neighbours[1]) {
+      return undefined;
+    }
+    let cancelPaint = null;
+    const cancelWait = whenPageReadsAnswered(() => {
+      cancelPaint = afterPaint(() => {
+        if (movementRef.current) {
+          return;
+        }
+        for (const page of neighbours) {
+          if (page) {
+            page.route.preload(page.params || {});
+          }
+        }
+      });
+    });
+    return () => {
+      cancelWait();
+      if (cancelPaint) {
+        cancelPaint();
+      }
+    };
+  }, [prefetch, neighbours, restCount]);
+
   // A neighbour shows from the first frame the compositor moves the row, before
   // any scroll event: a finger landing is the last word before that.
   const paintsNeighbours = Boolean(renderNeighbour);