@jsenv/navi 0.30.4 → 0.30.5

package/dist/jsenv_navi.js

@@ -36505,9 +36505,23 @@ const collectRoutePages = children => {
  * Whether the next container down is a row a hand scrolls: every page has a
  * place on it from the start, and the browser moves between them (see
  * RouteTravel's `nativeScroll`). Told to one container, not to the pages it holds.
+ * False, or `{ renderNeighbour }`.
  */
 const RouteRowContext = createContext(false);
 
+/**
+ * What stands in the pane of a neighbour until its page does. A component of its
+ * own: what the application calls in there (a hook, a signal) answers to it, however
+ * many neighbours the row has at that moment.
+ */
+const RouteRowNeighbour = ({
+  renderNeighbour,
+  page
+}) => jsx("div", {
+  "data-route-row-neighbour": "",
+  children: renderNeighbour(page)
+});
+
 // A container as a row: one pane per leaf, in the order they are written. A page
 // still builds when its route first matches, since a route's actions only ask
 // while it does: before that its pane is empty. Once built it stays, with what
@@ -36520,6 +36534,9 @@ const RouteRowContext = createContext(false);
 const RouteRowContainer = ({
   children
 }) => {
+  const {
+    renderNeighbour
+  } = useContext(RouteRowContext);
   const {
     activeBranch,
     leaves
@@ -36568,16 +36585,19 @@ const RouteRowContainer = ({
       shown: true
     }, "fallback");
   }
-  return leaves.map(leaf => jsx(RouteRowPane, {
+  const shownIndex = activeBranch ? leaves.findIndex(leaf => leaf.id === activeBranch.id) : -1;
+  return leaves.map((leaf, index) => jsx(RouteRowPane, {
     branch: leaf,
     page: pageOf(leaf),
-    shown: activeBranch !== null && leaf.id === activeBranch.id
+    shown: index === shownIndex,
+    renderNeighbour: shownIndex !== -1 && (index === shownIndex - 1 || index === shownIndex + 1) ? renderNeighbour : undefined
   }, leaf.id));
 };
 const RouteRowPane = ({
   branch,
   page,
-  shown
+  shown,
+  renderNeighbour
 }) => {
   // The very vnode rendered last, while not on screen: Preact does not look into
   // it, and a page nobody can see costs nothing when the address moves.
@@ -36596,7 +36616,10 @@ const RouteRowPane = ({
     "data-route-row-pane": "",
     "data-built": contentRef.current ? "" : undefined,
     inert: !shown,
-    children: contentRef.current
+    children: contentRef.current || renderNeighbour && jsx(RouteRowNeighbour, {
+      renderNeighbour: renderNeighbour,
+      page: branchRoutePage(branch)
+    })
   });
 };
 
@@ -40412,7 +40435,9 @@ const readRowStretch = (scroller, pages, page) => {
 /**
  * @param {Element} scroller
  * @param {object} options
- * @param {() => void} options.onScroll - the row moved.
+ * @param {(move: {finger: boolean}) => void} options.onScroll - the row moved.
+ *   `finger`: a touch has come since the row last stopped, so a lift will say where
+ *   it goes (`onLeftToSnap`). Without one (a trackpad, a wheel) nothing will.
  * @param {(event: Event|null) => void} options.onLand - the row may have stopped.
  *   Read `pageAtRest` to know whether it stopped on a page. Heard more than once
  *   for one landing, so what it does must find nothing to do the second time.
@@ -40428,11 +40453,13 @@ const watchRowScroll = (
 ) => {
   let stoppedTimeout = null;
   let touching = false;
+  let touchedSinceStop = false;
   let liftedAt = null;
   const landOnSilence = () => {
     liftedAt = null;
     // A finger holding the row still: nothing has stopped.
     if (!touching) {
+      touchedSinceStop = false;
       onLand(null);
     }
   };
@@ -40441,7 +40468,7 @@ const watchRowScroll = (
     stoppedTimeout = setTimeout(landOnSilence, STOPPED_SILENCE);
   };
   const onScrollEvent = () => {
-    onScroll();
+    onScroll({ finger: touchedSinceStop });
     armSilence();
     if (!liftedAt) {
       return;
@@ -40457,6 +40484,7 @@ const watchRowScroll = (
   };
   const onTouchStart = () => {
     touching = true;
+    touchedSinceStop = true;
     liftedAt = null;
     clearTimeout(stoppedTimeout);
   };
@@ -40484,6 +40512,8 @@ const watchRowScroll = (
 
 installImportMetaCssBuild(import.meta);
 const css$16 = /* css */`.navi_route_travel {
+  flex-direction: column;
+  display: flex;
   position: relative;
 }
 
@@ -40535,6 +40565,15 @@ const css$16 = /* css */`.navi_route_travel {
     overflow: clip;
   }
 
+  & > [data-route-row-pane] > [data-route-row-neighbour] {
+    contain: layout paint;
+    visibility: visible;
+    flex-direction: column;
+    display: flex;
+    position: absolute;
+    inset: 0;
+  }
+
   & > [data-route-row-live] {
     flex-direction: column;
     grid-row: 1;
@@ -40567,6 +40606,7 @@ const SET_OFF_PULL = 16;
  *   routes?: Array<object|{route: object, params?: object}>,
  *   travelByDrag?: boolean,
  *   onTravel?: (detail: {route: object, params: object|undefined, cause: string}) => void|Promise<void>,
+ *   renderNeighbour?: (page: {route: object, params: object|undefined}) => import("preact").ComponentChildren,
  * }>}
  * @param {Array<object|{route: object, params?: object}>} [props.routes] - a window
  *   over something longer, in order. Read from the <Route> children by default,
@@ -40583,6 +40623,13 @@ const SET_OFF_PULL = 16;
  *   of the page under six entries. A tab pressed goes the way its <Link> says —
  *   `<Link replace>` for a row of tabs, so a press and a swipe towards the same
  *   neighbour write the same history.
+ * @param {(page: {route: object, params: object|undefined}) => import("preact").ComponentChildren} [props.renderNeighbour]
+ *   - what stands in the pane of a page next to the one on screen, until the hand
+ *   has pulled far enough to bring that page: its background, its skeleton, what the
+ *   list already knows. A `<Route>` page already built shows itself. Receives
+ *   `{ 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.
  *
  * 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
@@ -40598,6 +40645,7 @@ const RouteTravel = ({
     replace: true,
     routeTransition: "none"
   }),
+  renderNeighbour,
   className,
   children,
   ...rest
@@ -40658,9 +40706,7 @@ const RouteTravel = ({
       travelling: false,
       pictures: new Map(),
       resumeScrollRecording: null,
-      scrollsDocument: getScrollContainer(row.parentElement, {
-        includeHidden: true
-      }) === document.documentElement,
+      scrollsDocument: rowFollowsDocument(row),
       ...fields
     };
     movementRef.current = movement;
@@ -40996,6 +41042,30 @@ const RouteTravel = ({
       Promise.resolve().then(endMovement);
     }
   }, [currentIndex]);
+
+  // 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);
+  useLayoutEffect(() => {
+    if (!paintsNeighbours) {
+      return undefined;
+    }
+    const row = rowRef.current;
+    const onTouchStart = () => {
+      if (!movementRef.current && rowFollowsDocument(row)) {
+        row.style.setProperty("--navi-route-row-pin", `${pinOf(row)}px`);
+      }
+    };
+    row.addEventListener("touchstart", onTouchStart, {
+      passive: true
+    });
+    return () => {
+      row.removeEventListener("touchstart", onTouchStart);
+    };
+  }, [paintsNeighbours]);
+  const rowContext = useMemo(() => ({
+    renderNeighbour
+  }), [renderNeighbour]);
   const rowKind = pages.length < 2 && windowed ? "still" : travelByDrag ? "" : "code";
   return jsx("div", {
     ...rest,
@@ -41008,12 +41078,20 @@ const RouteTravel = ({
       ,
       "data-travel-by-drag": travelByDrag && rowKind !== "still" ? "x" : undefined,
       children: windowed ? jsxs(Fragment, {
-        children: [pages.map((page, index) => jsx("div", {
-          "data-route-row-pane": "",
-          style: {
-            gridColumn: index + 1
-          }
-        }, index)), jsx("div", {
+        children: [pages.map((page, index) => {
+          const holdsNeighbour = paintsNeighbours && isNeighbourPane(index, liveIndex, movementRef.current);
+          return jsx("div", {
+            "data-route-row-pane": "",
+            inert: holdsNeighbour,
+            style: {
+              gridColumn: index + 1
+            },
+            children: holdsNeighbour && jsx(RouteRowNeighbour, {
+              renderNeighbour: renderNeighbour,
+              page: page
+            })
+          }, index);
+        }), jsx("div", {
           ref: liveRef,
           "data-route-row-live": "",
           style: {
@@ -41025,13 +41103,25 @@ const RouteTravel = ({
           "data-route-row-pictures": ""
         })]
       }) : jsx(RouteRowContext.Provider, {
-        value: true,
+        value: rowContext,
         children: children
       })
     })
   });
 };
 
+// The panes on each side of the live page. Not one holding a picture of the page
+// left there: a page with no background of its own would show it through.
+const isNeighbourPane = (index, liveIndex, movement) => {
+  if (index !== liveIndex - 1 && index !== liveIndex + 1) {
+    return false;
+  }
+  return !movement || !movement.pictures.has(index);
+};
+const rowFollowsDocument = row => getScrollContainer(row.parentElement, {
+  includeHidden: true
+}) === document.documentElement;
+
 // How far down the row the reader is looking, for a page brought in: a page on
 // screen scrolls with the document, and one arriving has to start from there.
 const pinOf = row => {
@@ -56513,6 +56603,10 @@ const SLIDE_TOWARD_ATTRIBUTE = "data-slide-travel-toward";
 // one: a hand on a row the browser scrolls can carry it past several slides, and
 // what follows it goes on between the two it is standing between.
 const SLIDE_BASE_ATTRIBUTE = "data-slide-travel-base";
+// The slide the row is on its way to while the current one has not changed yet,
+// because that only happens at rest: nothing is rendered and no address is written
+// under a snap, and what says where one is should not wait for it.
+const SLIDE_HEADING_ATTRIBUTE = "data-slide-heading";
 // Every way out that would DO something right now, in the words the commands
 // use: a direction ("left", "right", "up", "down") when there is a slide that
 // way, plus "first" and "last" when one is not already standing at that end of
@@ -56547,9 +56641,16 @@ const wordsOf = (element, attribute) => {
   return value ? value.split(" ") : NO_WAYS;
 };
 
+// The slide to say one is on: for whatever tells the reader where they are, as
+// opposed to data-slide-current, which is what a travel departs from.
+const readSlideOnScreen = (element) =>
+  element.getAttribute(SLIDE_HEADING_ATTRIBUTE) ??
+  element.getAttribute(SLIDE_CURRENT_ATTRIBUTE) ??
+  undefined;
+
 const readSlideContainerState = (element) => ({
   known: true,
-  current: element.getAttribute(SLIDE_CURRENT_ATTRIBUTE) ?? undefined,
+  current: readSlideOnScreen(element),
   toward: element.getAttribute(SLIDE_TOWARD_ATTRIBUTE) ?? undefined,
   // In DOM order — which is the order of the WALK for a line, and not
   // necessarily for a map: there the order is the one the areas are written in
@@ -56587,11 +56688,14 @@ const sameSlideContainerState = (a, b) =>
  *   can: (wayOut: "left"|"right"|"up"|"down"|"first"|"last") => boolean,
  *   held: (wayOut: "left"|"right"|"up"|"down"|"first"|"last") => boolean,
  * }} where the box stands. `current` is the slide on screen — the one being
- *   travelled TO while a travel plays, because that is what one is looking at;
+ *   travelled TO while a travel plays, and the one the row is going to once a hand
+ *   has let go, because that is what one is looking at. It can come before the
+ *   slide's own signal and `onCurrentChange`, which wait for the row to rest.
  *   `toward` is the other slide in the frame while the picture is between two,
- *   and nothing at rest. `can` is "asking for it would do something", `held` is
- *   "it is there and this slide says no" — a way out is dead in both cases, and
- *   only the second is worth a word to the reader.
+ *   and nothing at rest. `can` is "asking for it would do something", from the
+ *   slide a travel would depart from, `held` is "it is there and this slide says
+ *   no" — a way out is dead in both cases, and only the second is worth a word to
+ *   the reader.
  *   `known` is false until the box has been read: no box was named and none is
  *   above, the id names nothing, or — for one commit — this mounted before the
  *   box had painted. Until then `can` answers YES, because it is the answer that
@@ -57445,7 +57549,7 @@ const Nav = ({
     }
     slideContainerElementRef.current = containerElement;
     const readContainer = () => {
-      setCurrentSlideArea(containerElement.getAttribute(SLIDE_CURRENT_ATTRIBUTE) ?? undefined);
+      setCurrentSlideArea(readSlideOnScreen(containerElement));
       paintIndicatorGeometryRef.current();
       scheduleTabScrollSyncRef.current();
     };
@@ -68444,6 +68548,20 @@ const SlideContainer = ({
   const paintCurrentArea = area => {
     containerRef.current?.setAttribute(SLIDE_CURRENT_ATTRIBUTE, area);
   };
+
+  // Where the row is going, for as long as the current slide has not changed:
+  // anything saying where one is reads this first (see readSlideOnScreen). Left to
+  // the caller to announce, a landing having more to say in the same breath.
+  const writeHeading = headingElement => {
+    const containerEl = containerRef.current;
+    const area = headingElement ? readArea(headingElement) : null;
+    // A window does not change slide, it rolls: it has nowhere to be heading.
+    if (loop || area === null || area === containerEl.getAttribute(SLIDE_CURRENT_ATTRIBUTE)) {
+      containerEl.removeAttribute(SLIDE_HEADING_ATTRIBUTE);
+      return;
+    }
+    containerEl.setAttribute(SLIDE_HEADING_ATTRIBUTE, area);
+  };
   const markAnswered = area => {
     const order = readMap().slideElements.map(readArea);
     const rank = order.indexOf(area);
@@ -68649,6 +68767,10 @@ const SlideContainer = ({
     slideElements[0];
     const currentArea = readArea(currentElement);
     paintCurrentArea(currentArea);
+    // In the commit the slide changes in, so nothing reads the slide left in between.
+    if (!handMovingRef.current) {
+      writeHeading(null);
+    }
     const realPlaceOf = area => placeOf.get(area) || {
       x: 0,
       y: 0
@@ -68681,6 +68803,8 @@ const SlideContainer = ({
     const drawnArea = stage ? stage.area : drawnAreaRef.current;
     const travelStarts = !still && durationMs > 0 && drawnArea !== undefined && drawnArea !== currentArea && slideElements.some(slideElement => readArea(slideElement) === drawnArea);
     if (travelStarts) {
+      // Asked for over a row still snapping: the travel is what one will see.
+      writeHeading(null);
       // Where the slide being left IS — the place the stage gave it if a travel
       // was already playing (a press landing mid-travel departs from where the
       // eye is, not from the map), its own place otherwise.
@@ -69447,7 +69571,9 @@ const SlideContainer = ({
   // Where a hand has the row, in the terms of --slide-travel-progress: from the
   // current slide while it stands next to it, and past that between the two it
   // stands between, as far as the hand carries it.
-  const paintNativeRow = () => {
+  const paintNativeRow = ({
+    finger
+  }) => {
     if (trackAnimationRef.current?.playState === "running") {
       return;
     }
@@ -69459,6 +69585,9 @@ const SlideContainer = ({
     }
     if (restsOn(containerEl, currentElement)) {
       if (handMovingRef.current) {
+        if (!finger) {
+          writeHeading(null);
+        }
         paintTravelProgress();
       }
       return;
@@ -69479,6 +69608,12 @@ const SlideContainer = ({
       }
       element.style.setProperty("--slide-travel-progress", forward ? -fraction : fraction);
     }
+    // Nothing will say when a trackpad's fingers leave, and a long stroke would
+    // keep the first tab lit for the whole trip: the nearest slide answers. A finger
+    // has a lift to wait for (headNativeRow), and until then the slide held stands.
+    if (!finger) {
+      writeHeading(fraction >= 0.5 && toward ? toward : base);
+    }
     paintTravelToward(toward ? readArea(toward) : null);
     // What the hand reaches ahead of the neighbours built at rest is asked for on
     // the way: an empty slide goes by otherwise.
@@ -69486,6 +69621,28 @@ const SlideContainer = ({
       alongside: true
     });
   };
+
+  // A finger has lifted and the row moves: on past the slide it stands after, or
+  // back to it. Already standing on one, it has arrived, whichever way it came.
+  const headNativeRow = movedForward => {
+    if (!handMovingRef.current || trackAnimationRef.current?.playState === "running") {
+      return;
+    }
+    const slideElements = Array.from(trackRef.current.children);
+    const currentElement = slideElements.find(slideElement => slideElement.hasAttribute("data-current"));
+    if (!currentElement) {
+      return;
+    }
+    const {
+      base,
+      toward,
+      fraction,
+      forward
+    } = readRowStretch(containerRef.current, slideElements, currentElement);
+    const goesOn = fraction > 0 && movedForward === forward;
+    writeHeading(goesOn && toward ? toward : base);
+    announceState();
+  };
   const landNativeRow = scrollEndEvent => {
     if (!handMovingRef.current) {
       return;
@@ -69500,13 +69657,15 @@ const SlideContainer = ({
       return;
     }
     handMovingRef.current = false;
-    paintTravelProgress();
     const area = readArea(landedElement);
     const currentArea = containerEl.getAttribute(SLIDE_CURRENT_ATTRIBUTE);
     if (area === currentArea) {
+      writeHeading(null);
+      paintTravelProgress();
       settleTravel();
       return;
     }
+    paintTravelProgress();
     const event = scrollEndEvent ?? new Event("scrollend");
     if (loop) {
       // A window does not change slide, it rolls: back at rest in the render the
@@ -69537,6 +69696,8 @@ const SlideContainer = ({
     }
     // Refused: the row is put back in view of the slide that stays.
     handLandedRef.current = null;
+    writeHeading(null);
+    announceState();
     const currentElement = slideElements.find(slideElement => slideElement.hasAttribute("data-current"));
     containerEl.scrollTo({
       left: currentElement.offsetLeft,
@@ -69550,11 +69711,13 @@ const SlideContainer = ({
   const nativeRowHandlersRef = useRef(null);
   nativeRowHandlersRef.current = {
     paintNativeRow,
+    headNativeRow,
     landNativeRow
   };
   useLayoutEffect(() => {
     return watchRowScroll(containerRef.current, {
-      onScroll: () => nativeRowHandlersRef.current.paintNativeRow(),
+      onScroll: move => nativeRowHandlersRef.current.paintNativeRow(move),
+      onLeftToSnap: forward => nativeRowHandlersRef.current.headNativeRow(forward),
       onLand: event => nativeRowHandlersRef.current.landNativeRow(event)
     });
   }, []);