@jsenv/navi 0.29.502 → 0.29.503

package/dist/jsenv_navi.js

@@ -36863,6 +36863,14 @@ const collectBranches = (children, path = "") => {
       const paramsMatching = routeParams ? route.matchesParams(routeParams) : true;
       if (!matchingBranch && matching && paramsMatching) {
         matchingBranch = branch;
+        if (!routeParams) {
+          // The params are part of the page this branch shows: /games/a and
+          // /games/b are two pages on one branch, and the container renders
+          // between them so the second is announced like any other (see
+          // publishRouteRender) — a movement between the two waits on it.
+          // eslint-disable-next-line no-unused-expressions
+          route.paramsSignal.value;
+        }
       }
     }
   };
@@ -36927,6 +36935,59 @@ const RouteUI = ({
   return element;
 };
 
+/*
+ * What ONE navigation asks of a route transition, worn by the element being
+ * pressed: `<Link routeTransition>`, `<Button routeTransition>`, or the
+ * attribute by hand on any anchor. A type travels as its name — all most
+ * presses have to say — and anything more (a way round, a pace) as the same
+ * object navTo() takes, written as JSON.
+ *
+ * Apart from route_transition.jsx, which plays the request: the press handlers
+ * and the --navi-nav-to command read it too, and importing the transition
+ * machinery there would pull it into an application that defines no
+ * transition.
+ */
+
+const ROUTE_TRANSITION_REQUEST_ATTRIBUTE = "data-navi-route-transition-request";
+
+// The attributes to spread on the element. Nothing when nothing is asked, so
+// that the attribute written by hand on the same element is left standing.
+const writeRouteTransitionRequest = (routeTransition) => {
+  if (routeTransition === undefined || routeTransition === null) {
+    return null;
+  }
+  return {
+    [ROUTE_TRANSITION_REQUEST_ATTRIBUTE]:
+      typeof routeTransition === "string"
+        ? routeTransition
+        : JSON.stringify(routeTransition),
+  };
+};
+
+// The request as navTo() takes it — a type name or the object — and undefined
+// when the element asks nothing.
+const readRouteTransitionRequest = (element) => {
+  const asked = element.getAttribute(ROUTE_TRANSITION_REQUEST_ATTRIBUTE);
+  if (asked === null) {
+    return undefined;
+  }
+  const value = asked.trim();
+  if (value === "") {
+    return undefined;
+  }
+  if (value[0] !== "{") {
+    return value;
+  }
+  try {
+    return JSON.parse(value);
+  } catch {
+    console.warn(
+      `${ROUTE_TRANSITION_REQUEST_ATTRIBUTE} is neither a type name nor JSON: ${value}`,
+    );
+    return undefined;
+  }
+};
+
 /**
  * Where a route movement is heading, said before its first picture is taken.
  *
@@ -38338,10 +38399,6 @@ const TRANSITION_COVERED_ATTRIBUTE = "data-navi-route-transition-covered";
 // right for a page that IS the whole viewport.
 const TRANSITION_AREA_ATTRIBUTE = "data-navi-route-transition-area";
 const TRANSITION_TARGET_ATTRIBUTE = "data-navi-route-transition-target";
-// What ONE navigation asks for, over whatever the relations say: worn by the
-// link being pressed (see <Link routeTransition>), or handed to navTo(). It answers
-// for that navigation and for no other — the next one is back to the relations.
-const TRANSITION_REQUEST_ATTRIBUTE = "data-navi-route-transition-request";
 // What a history entry remembers of the crossing that created it, in the
 // entry's own state: `{ from, type, direction, duration }` (see recordCrossing).
 const CROSSING_STATE_KEY = "jsenv_route_transition";
@@ -38882,13 +38939,32 @@ const defineRouteTransition = (from, to, transition) => {
  * "before" the other — so give it a movement that does not need one:
  * `"cross-fade"`, or a custom type whose CSS is keyed on the type alone.
  *
- * @param {string|{type?: string, duration?: number|string}} transition - same
- *   forms as defineRouteTransition's. `"none"` (or removing the default) puts
- *   the silence back.
+ * Unless the history says it: `{ type: "slide-x", direction: "history" }` is
+ * the grammar of a navigation stack, where every link goes one level deeper
+ * and every back one level up. A push plays forward, a traversal retraces its
+ * crossing or, with none remembered, plays back when it lands lower in the
+ * history and forward when it lands higher, and a replace — the same level —
+ * plays nothing. It plays only when the page changes: a push that opens a
+ * layer over the page keeps the page. The relations written still answer
+ * first, and a page written from anywhere then answers for its way out only
+ * on a back — a link out of it is a push like any other (see findRelation).
+ *
+ * @param {string|{type?: string, duration?: number|string, direction?: "history"}} transition -
+ *   same forms as defineRouteTransition's. `"none"` (or removing the default)
+ *   puts the silence back.
  * @returns {() => void} remove this default.
  */
 const defineRouteDefaultTransition = transition => {
-  const value = normalizeTransition(transition);
+  const {
+    direction
+  } = typeof transition === "object" && transition !== null ? transition : {};
+  if (direction !== undefined && direction !== "history") {
+    throw new TypeError(`defineRouteDefaultTransition takes direction: "history" or no direction, not ${JSON.stringify(direction)}: a default is about pages no relation orders, and "history" is the one thing that orders them — the depth of the entries the navigation goes between.`);
+  }
+  const value = {
+    ...normalizeTransition(transition),
+    readsHistory: direction === "history"
+  };
   defaultTransition = value;
   installRouteTransitionCss();
   return () => {
@@ -38941,29 +39017,8 @@ const readNavigationRequest = ({
     return normalizeRequest(routeTransition);
   }
   if (element && element.getAttribute) {
-    const asked = element.getAttribute(TRANSITION_REQUEST_ATTRIBUTE);
-    if (asked === null) {
-      return null;
-    }
-    const value = asked.trim();
-    if (value === "") {
-      return null;
-    }
-    // A type is a name, and a name is all most links have to say. Anything
-    // more — a way round, a pace — is the same object the API takes
-    // everywhere else, written as JSON so that it travels on an attribute
-    // (and so that a plain <a> can say it too).
-    if (value[0] === "{") {
-      let parsed;
-      try {
-        parsed = JSON.parse(value);
-      } catch {
-        console.warn(`${TRANSITION_REQUEST_ATTRIBUTE} is neither a type name nor JSON: ${value}`);
-        return null;
-      }
-      return normalizeRequest(parsed);
-    }
-    return normalizeRequest(value);
+    const asked = readRouteTransitionRequest(element);
+    return asked === undefined ? null : normalizeRequest(asked);
   }
   return null;
 };
@@ -39049,6 +39104,31 @@ const crossingRecordedOn = state => {
   }
   return crossing;
 };
+
+/**
+ * Which way the history says a navigation goes, for a default that reads it
+ * (see defineRouteDefaultTransition): a push is one level deeper, a traversal
+ * goes where the depth of the entry it lands on puts it — back when that is
+ * not known, as in readTraversalReplay —, and anything else (a replace) stays
+ * on its level: null.
+ */
+const readHistoryDirection = (navigationType, {
+  state,
+  fromState
+}) => {
+  if (navigationType === "push") {
+    return "forward";
+  }
+  if (navigationType !== "traverse") {
+    return null;
+  }
+  const depthIn = navDepthOf(state);
+  const depthOut = navDepthOf(fromState);
+  if (depthIn !== undefined && depthOut !== undefined && depthIn > depthOut) {
+    return "forward";
+  }
+  return "back";
+};
 const navDepthOf = state => {
   if (state && typeof state[NAV_DEPTH_STATE_KEY] === "number") {
     return state[NAV_DEPTH_STATE_KEY];
@@ -39232,6 +39312,10 @@ let navigationAnimated = false;
 // "push", "replace", "traverse", … — a push is the one navigation that creates
 // the entry a crossing is recorded on.
 let navigationType = null;
+// Which way the history says this navigation goes — "forward", "back", or null
+// for a replace — when the default reads it (see readHistoryDirection), and
+// undefined when nothing does.
+let navigationHistoryDirection;
 // What was decided for the navigation now landing — a movement, or "none" —
 // which is what its entry remembers (see recordCrossing). Null while nothing
 // has been decided, and for a navigation nothing was said about.
@@ -39249,14 +39333,19 @@ observeBeforeRouting(details => {
   navigationType = details.navigationType;
   navigationUrl = details.url;
   navigationFromUrl = documentUrlSignal.peek();
-  // A traversal has no element and no call to ask anything: what it asks is
-  // the crossing it retraces — reversed for a back, as it was for a forward.
   // Read before the document state moves, so the state peeked is the entry
   // being left.
+  const fromState = documentStateSignal.peek();
+  // A traversal has no element and no call to ask anything: what it asks is
+  // the crossing it retraces — reversed for a back, as it was for a forward.
   navigationRequest = navigationType === "traverse" ? readTraversalReplay(details, {
     fromUrl: navigationFromUrl,
-    fromState: documentStateSignal.peek()
+    fromState
   }) : readNavigationRequest(details);
+  navigationHistoryDirection = defaultTransition && defaultTransition.readsHistory ? readHistoryDirection(navigationType, {
+    state: details.state,
+    fromState
+  }) : undefined;
   if (relations.length === 0 && !defaultTransition && !navigationRequest) {
     return;
   }
@@ -39274,17 +39363,24 @@ observeAfterRouting(() => {
   const url = navigationUrl;
   const fromUrl = navigationFromUrl;
   const type = navigationType;
+  const historyDirection = navigationHistoryDirection;
   // Read here and dropped here: a request answers for the navigation it was
   // made on, and the next one is back to the relations.
   navigationRequest = null;
   navigationUrl = null;
   navigationFromUrl = null;
   navigationType = null;
-  if (!navigationAnimated && (request || defaultTransition)) {
+  navigationHistoryDirection = undefined;
+  // A default reading the history plays between two pages a level apart: not
+  // on a replace, and not on a navigation that keeps the page — a push
+  // opening a layer over it moves the layer, not the page (see
+  // page_change.js).
+  const base = defaultTransition && (!defaultTransition.readsHistory || historyDirection !== null && isRenderingPageChange()) ? defaultTransition : null;
+  if (!navigationAnimated && (request || base)) {
     const {
       type,
       duration
-    } = resolveTransition(request, defaultTransition);
+    } = resolveTransition(request, base);
     if (type === "none") {
       navigationDecision = {
         type: "none"
@@ -39297,11 +39393,12 @@ observeAfterRouting(() => {
         // A default has no direction: nothing says which of two arbitrary
         // pages is before the other, and the attribute is then worn empty —
         // present for whoever keys on "one of ours is playing", silent on the
-        // way. A request is the other case: a navigation IS a way round, so a
-        // press that names the movement means forward unless it says
-        // otherwise — and a movement of navi's is written on the direction,
-        // so left empty it would play nothing at all.
-        direction: request && request.direction !== undefined ? request.direction : request && request.typeSaid ? "forward" : "",
+        // way — unless it reads the history. A request is the other case: a
+        // navigation IS a way round, so a press that names the movement means
+        // forward unless it says otherwise — and a movement of navi's is
+        // written on the direction, so left empty it would play nothing at
+        // all.
+        direction: request && request.direction !== undefined ? request.direction : request && request.typeSaid ? "forward" : base && base.readsHistory ? historyDirection : "",
         type,
         duration
       });
@@ -39417,6 +39514,12 @@ const findRelation = (fromPage, toPage) => {
       };
     }
   }
+  // Leaving such a page plays back because leaving it is assumed to be
+  // closing it. With the default reading the history, that is known instead:
+  // a link out of it is a push, one level deeper, and the default answers.
+  if (navigationHistoryDirection !== undefined && navigationHistoryDirection !== "back") {
+    return null;
+  }
   for (const relation of relations) {
     if (relation.from) {
       continue;
@@ -40330,7 +40433,11 @@ const RouteTravel = ({
   // a travel is between two of them, and by the time anything renders the first
   // one is already gone. Written after each render (below), so a subscriber
   // reading it — they all run before Preact flushes — reads the one being left.
-  const currentIndexRef = useRef(currentIndex);
+  // The page and not its place in the row: a row given again around the page
+  // on screen (a window over a list, read anew around it) puts that page at
+  // another index without anything having moved.
+  const currentPage = currentIndex === -1 ? null : pages[currentIndex];
+  const currentPageRef = useRef(currentPage);
 
   // Where a page is asked for, whoever asks: a page is a route AND the params
   // that say which of its tabs, and a caller told only the route would send the
@@ -40526,11 +40633,13 @@ const RouteTravel = ({
       if (index === -1) {
         return;
       }
-      if (index === currentIndexRef.current) {
-        // Where the row already was — the first reading of all, and any move
-        // this box has already taken note of (a render writes it too). What it
-        // was still waiting for is here nonetheless, so the wait is called off.
-        if (samePage(pageAskedForRef.current, pages[index])) {
+      const page = pages[index];
+      if (samePage(page, currentPageRef.current)) {
+        // Where the row already was — the first reading of all, a row given
+        // again around the page on screen, and any move this box has already
+        // taken note of (a render writes it too). What it was still waiting
+        // for is here nonetheless, so the wait is called off.
+        if (samePage(pageAskedForRef.current, page)) {
           pageAskedForRef.current = null;
         }
         return;
@@ -40539,13 +40648,12 @@ const RouteTravel = ({
       // between two of them is a page change the path does not show (see
       // page_change.js).
       notePageChange();
-      const page = pages[index];
       // A page this box asked for itself — a travel's own navigation, or one
       // it had given up waiting on: what arrives here is the answer to a
       // question already answered, not somebody going somewhere.
       if (samePage(pageAskedForRef.current, page)) {
         pageAskedForRef.current = null;
-        currentIndexRef.current = index;
+        currentPageRef.current = page;
         return;
       }
       // Somewhere else arrived first: whatever this box was still waiting for
@@ -40557,15 +40665,15 @@ const RouteTravel = ({
       // flight is the answer, aimed somewhere else. Starting a second one on
       // top would leave this one's pictures to be dropped mid-slide.
       if (travelRef.current) {
-        currentIndexRef.current = index;
+        currentPageRef.current = page;
         retargetTravel(travelRef.current, page);
         return;
       }
-      const fromIndex = currentIndexRef.current;
-      currentIndexRef.current = index;
-      if (fromIndex === -1 || fromIndex === index) {
-        // Arriving from outside this row (or not moving at all): there is no
-        // pair of pages to show, so there is nothing to travel between.
+      const fromIndex = pageIndexOf(pages, currentPageRef.current);
+      currentPageRef.current = page;
+      if (fromIndex === -1) {
+        // Arriving from outside this row: there is no pair of pages to show,
+        // so there is nothing to travel between.
         return;
       }
       beginTravel({
@@ -40600,8 +40708,8 @@ const RouteTravel = ({
   // What the next announcement will compare itself against: written after the
   // render that shows it, so it is always the page one is looking at.
   useLayoutEffect(() => {
-    currentIndexRef.current = currentIndex;
-  }, [currentIndex]);
+    currentPageRef.current = currentPage;
+  }, [currentPage]);
 
   // Let go of far enough: the movement carries on from under the finger, at its
   // own pace, to the end.
@@ -43563,13 +43671,15 @@ const navToCommand = (source, event, { argument }) => {
   return {
     target,
     // Which way there is worn by the source, as a link wears it (see
-    // link_replace.js, link_return.js, link_open.js):
+    // link_replace.js, link_return.js, link_open.js,
+    // route_transition_request.js):
     // `<Button command="--navi-nav-to:/done" replace>`.
     implementation: () =>
       navTo(argument, {
         replace: linkAsksForReplace(source),
         asReturn: linkAsksForReturn(source),
         open: linkAsksToOpen(source),
+        routeTransition: readRouteTransitionRequest(source),
       }),
   };
 };
@@ -56466,10 +56576,8 @@ const LinkPlain = props => {
 
   // What this link asks of a route transition, worn as an attribute so that
   // the navigation reads it off the element being pressed (see
-  // route_transition.jsx, which owns the name and does the reading). A type is
-  // a name; anything more travels as JSON, which is also how a plain <a>
-  // writes it by hand.
-  const routeTransitionRequest = routeTransition === undefined || routeTransition === null ? undefined : typeof routeTransition === "string" ? routeTransition : JSON.stringify(routeTransition);
+  // route_transition_request.js, which owns the name and does the reading).
+  const routeTransitionRequest = writeRouteTransitionRequest(routeTransition);
 
   // Which way this link goes to the place it aims at, worn as an attribute so
   // that whoever answers the press reads it off the anchor (see
@@ -56560,7 +56668,7 @@ const LinkPlain = props => {
     open: undefined,
     document: undefined,
     prefetch: undefined,
-    "data-navi-route-transition-request": routeTransitionRequest,
+    ...routeTransitionRequest,
     ...(pressableDuringRouteTransition ? {
       [PRESSABLE_ATTRIBUTE]: ""
     } : null),
@@ -61270,6 +61378,7 @@ const ButtonUI = props => {
     asReturn,
     open,
     document: isDocument,
+    routeTransition,
     pressableDuringRouteTransition,
     prefetch = true,
     // visual
@@ -61327,6 +61436,11 @@ const ButtonUI = props => {
     [LINK_DOCUMENT_ATTRIBUTE]: ""
   } : null;
 
+  // What this press asks of a route transition (see
+  // route_transition_request.js): read off the anchor by the navigation, off
+  // the source by --navi-nav-to.
+  const routeTransitionRequest = writeRouteTransitionRequest(routeTransition);
+
   // Worn as an attribute too, and read at the document by whoever catches the
   // press a movement would have swallowed (see transition_press.js).
   const pressableRequest = pressableDuringRouteTransition ? {
@@ -61383,6 +61497,8 @@ const ButtonUI = props => {
     ...openRequest,
     document: undefined,
     ...documentRequest,
+    routeTransition: undefined,
+    ...routeTransitionRequest,
     pressableDuringRouteTransition: undefined,
     ...pressableRequest,
     prefetch: undefined
@@ -62039,6 +62155,7 @@ const COMMAND_DEFAULT_PROPS_FACTORIES = {
  *   replace?: boolean,
  *   asReturn?: boolean,
  *   open?: string | { id: string, type?: "push" | "replace" },
+ *   routeTransition?: string | { type?: string, duration?: number | string, direction?: "forward" | "back" },
  *   document?: boolean,
  *   actionStandalone?: boolean,
  *   actionAbortable?: boolean,
@@ -62087,6 +62204,11 @@ const COMMAND_DEFAULT_PROPS_FACTORIES = {
  * @param {string|{id: string, type?: "push"|"replace"}} [open] Lands with one
  *   of the destination's popups open, named the way its `navState` names it:
  *   what `<Link open>` says, for a press drawn as a button.
+ * @param {string|{type?: string, duration?: number|string, direction?: "forward"|"back"}} [routeTransition]
+ *   What the press asks of a route transition, for that one navigation — a
+ *   type name, or an object to also say the pace or which way it plays, over
+ *   what the pair's relation says: what `<Link routeTransition>` says, read
+ *   off an `href`, a `route` or a `--navi-nav-to` command.
  * @param {boolean} [document] The `href` is ANOTHER DOCUMENT of this origin —
  *   an admin panel, a status page, anything built as its own entry point — so
  *   the press is left to the browser and loads that page, instead of being