@jsenv/navi 0.29.422 → 0.29.424

package/dist/dev/jsenv_navi.js

@@ -60814,6 +60814,20 @@ const readArea = slideElement => slideElement.getAttribute("data-slide-area") ||
  *   `sizing={loading ? "largest" : "frozen"}` and is measured once the real
  *   content is there. The freeze holds against what happens INSIDE the box, not
  *   against the room it is given: a window resize measures again.
+ * @param {"always"|"near"} [props.mount="always"] - when a slide's CONTENT is
+ *   rendered. The <Slide> element always is, so areas, tabs following the box
+ *   and `aria-labelledby` are the same either way. "always": every slide's,
+ *   from the start. "near": once a travel can show it — the slide on screen,
+ *   the one a travel is going to, and at rest the ones a hand dragging the box
+ *   would bring alongside (neighbours on the map, along the axes
+ *   `travelByDrag` opens, the other end of a `loop` included) — and kept from
+ *   then on. For slides that are costly to build (a grid of a few hundred
+ *   controls each): opening builds the slide shown and its neighbours rather
+ *   than all of them, and a jump to a far slide builds that one and none of
+ *   those in between, which a travel never shows. The box is then as large as
+ *   the largest slide BUILT so far (see `sizing`), so it grows as a larger one
+ *   is reached: give it a size of its own when the slides differ.
+ *   `<Slide mount>` says it for one slide — a heavy one among light ones.
  */
 const SlideContainer = ({
   layout = "row",
@@ -60829,6 +60843,7 @@ const SlideContainer = ({
   travelByScroll = "x",
   duration = "300ms",
   sizing = "largest",
+  mount = "always",
   children,
   ...rest
 }) => {
@@ -60948,6 +60963,15 @@ const SlideContainer = ({
   // Undefined at mount on purpose: the first area held outside is news like any
   // other, and it is walked to rather than opened on.
   const areaAskedSeenRef = useRef(undefined);
+  // An area held outside that this container has not answered yet: the effect
+  // reading currentFromCaller walks to it, after the render that brings it.
+  const requestIsNews = () => currentFromCaller !== undefined && currentFromCaller !== areaAskedSeenRef.current;
+  // The slide about to be on screen, as far as a render can tell: the area
+  // asked from outside while it is news — the picture is walked there before
+  // it is painted, the first request included — and the container's own answer
+  // otherwise. What a slide waiting for a travel reads to have its content in
+  // the very render that shows it (see Slide's `mount`).
+  const areaShownNext = requestIsNews() ? currentFromCaller : current;
   // Where the container stands, said where the caller holds it.
   //
   // Whether a slide is a place one came from is the STATE's own business (see
@@ -61002,6 +61026,22 @@ const SlideContainer = ({
   // state: nothing on screen depends on it, and a travel must read what the
   // one before it wrote, not what the last render saw.
   const cameFromRef = useRef({});
+  // The slides a travel has come near while their content was not rendered
+  // (mount="near", see renderNear): only ever grows, and only for a slide that
+  // was waiting — a container whose slides all render never re-renders for it.
+  const [nearAreas, setNearAreas] = useState([]);
+  // Nothing names the slide on screen (no area held outside, no default): it
+  // is the first one in the DOM, which the first render cannot read yet. The
+  // first Slide to render is that one, so it claims it — the slide on screen
+  // then has its content from the first commit (a size frozen at mount, a
+  // focus landing in it) rather than one render late.
+  const openingClaimRef = useRef(null);
+  const claimOpening = area => {
+    if (openingClaimRef.current === null) {
+      openingClaimRef.current = area;
+    }
+    return openingClaimRef.current === area;
+  };
 
   // The controller has caught up with the slide the container went to on its
   // own (commit="rest"): there are no longer two answers to give, so the
@@ -61142,6 +61182,44 @@ const SlideContainer = ({
     }
   };
 
+  // The slides a hand dragging the box from this area would bring alongside:
+  // the map's neighbours on the axes it drags, read the way the drag reads them
+  // (areaTowards knows the holes and a loop's two ends).
+  const areasAlongside = area => {
+    const alongside = [];
+    if (dragAxes?.includes("x")) {
+      alongside.push(areaTowards(-1, 0, area), areaTowards(1, 0, area));
+    }
+    if (dragAxes?.includes("y")) {
+      alongside.push(areaTowards(0, -1, area), areaTowards(0, 1, area));
+    }
+    return alongside;
+  };
+
+  // mount="near": the content of a slide is asked for before a travel shows
+  // it. The neighbours are asked for AT REST, never when a travel sets off: the
+  // travel shows the slide it goes to and nothing past it, and a slide built in
+  // the render that starts it is a frame the travel waits for. At rest nothing
+  // moves, and a hand landing next is still answered after the build.
+  const renderNear = (area, {
+    alongside
+  }) => {
+    // Asked on every render: a container with nothing waiting stops here.
+    if (!trackRef.current?.querySelector(":scope > [data-slide-unrendered]")) {
+      return;
+    }
+    const unrendered = readMap().slideElements.filter(slideElement => slideElement.hasAttribute("data-slide-unrendered")).map(readArea);
+    const near = alongside ? [area, ...areasAlongside(area)] : [area];
+    const toRender = near.filter(nearArea => unrendered.includes(nearArea));
+    if (!toRender.length) {
+      return;
+    }
+    setNearAreas(previous => {
+      const added = toRender.filter(nearArea => !previous.includes(nearArea));
+      return added.length ? [...previous, ...added] : previous;
+    });
+  };
+
   // The travel is over: the stage is struck and every slide goes back where the
   // map says it is. Nothing is seen moving for it — the slide on screen sits at
   // the same place whatever the arrangement (its own offset and the track's are
@@ -61190,6 +61268,9 @@ const SlideContainer = ({
     const offset = `${-x * 100}% ${-y * 100}%`;
     offsetRef.current = offset;
     track.style.setProperty("--slide-container-offset", offset);
+    renderNear(currentArea, {
+      alongside: true
+    });
     // Arrived, so the change can be told (commit="rest"): the picture is at
     // rest and whatever the caller does with it — write the URL, ask a server —
     // costs the gesture nothing anymore.
@@ -61467,6 +61548,15 @@ const SlideContainer = ({
     if (!stageRef.current) {
       drawnAreaRef.current = currentArea;
     }
+    // What a travel can show next (mount="near"), around where the picture
+    // SETTLES: a request from outside is walked to by an effect running after
+    // this one, in the same commit, and the slides around a picture about to be
+    // walked away from would be built for nothing. The neighbours only at
+    // rest, see renderNear.
+    const settlingArea = requestIsNews() && reachableTowards(currentArea, currentFromCaller) || currentArea;
+    renderNear(settlingArea, {
+      alongside: !stageRef.current
+    });
     // Said last, and after data-current has been written: what a travel would do
     // is read off the map from the slide that is now current, and off the locks
     // that slide is wearing in this very commit.
@@ -61704,12 +61794,9 @@ const SlideContainer = ({
   // request later), and what nothing has answered yet must still be answered
   // once it can be.
   useLayoutEffect(() => {
-    if (currentFromCaller === undefined) {
-      return;
-    }
-    if (currentFromCaller === areaAskedSeenRef.current) {
-      // Not news: either nothing moved, or this container is reading back what
-      // it wrote itself.
+    if (!requestIsNews()) {
+      // Not news: nothing held outside, nothing moved, or this container
+      // reading back what it wrote itself.
       return;
     }
     // The slide asked for is not rendered yet — no slides at all, or one whose
@@ -62539,6 +62626,11 @@ const SlideContainer = ({
         if (!past) {
           return false;
         }
+        // Two slides from the one at rest, so possibly never rendered: asked
+        // for now, and built before the frame that brings it in is painted.
+        renderNear(past, {
+          alongside: false
+        });
         const currentElement = slideElements.find(slideElement => slideElement.hasAttribute("data-current")) || slideElements[0];
         const basePlace = stageRef.current?.placeByArea.get(reached) || placeOf.get(reached) || {
           x: 0,
@@ -62997,6 +63089,12 @@ const SlideContainer = ({
             done,
             valueByArea,
             settleFocus,
+            // What a slide reads to know whether its content is rendered yet
+            // (see Slide's `mount`).
+            mount,
+            areaShownNext,
+            nearAreas,
+            claimOpening: areaShownNext === undefined ? claimOpening : null,
             // The box itself, for what is written INSIDE it to read the same
             // facts what is written outside reads by id (useSlideContainer):
             // a way out is a way out on either side of the box.
@@ -63053,9 +63151,12 @@ const warnOnNonStringArea = area => {
  *   try to leave.
  * @param {boolean} [props.preventNavNext] - hold them from going right or down.
  * @param {boolean} [props.preventNavPrevious] - …left or up.
+ * @param {"always"|"near"} [props.mount] - when this slide's content is
+ *   rendered; the container's `mount` when not said (see there).
  */
 const Slide = ({
   area,
+  mount,
   required,
   preventNav,
   preventNavNext = preventNav,
@@ -63068,6 +63169,17 @@ const Slide = ({
   {
     warnOnNonStringArea(slideArea);
   }
+  // Asked by every slide, whatever its own mode: the claim goes to the first
+  // slide to RENDER, and a slide that skipped asking would hand it to the one
+  // after it.
+  const opening = container?.claimOpening?.(slideArea);
+  // Kept once rendered (mount="near"): going back builds nothing again, and a
+  // slide being left keeps its content for as long as it is still in the frame.
+  const renderedRef = useRef(false);
+  if (!renderedRef.current && (!container || (mount ?? container.mount) !== "near" || opening || slideArea === container.areaShownNext || container.nearAreas.includes(slideArea))) {
+    renderedRef.current = true;
+  }
+  const rendered = renderedRef.current;
   const answered = Boolean(container?.answeredAreas.includes(slideArea));
   const holdsUntilAnswered = Boolean(required) && !answered;
   const nextIsLocked = Boolean(preventNavNext) || holdsUntilAnswered;
@@ -63117,13 +63229,17 @@ const Slide = ({
         "data-slide-area": slideArea,
         "data-prevent-nav-next": nextIsLocked ? "" : undefined,
         "data-prevent-nav-previous": preventNavPrevious ? "" : undefined
+        // What the container reads to know a slide is waiting for a travel
+        // to come near (see renderNear).
+        ,
+        "data-slide-unrendered": rendered ? undefined : ""
         // A surface one interacts with says what state it is in, the way every
         // other surface does — a dialog carries the very same set.
         // :focus-within is the one a slide is really about: it is what tells
         // the slide holding the keyboard from the ones waiting.
         ,
         pseudoClasses: SLIDE_PSEUDO_CLASSES,
-        children: children
+        children: rendered ? children : null
       })
     })
   });
@@ -75640,9 +75756,12 @@ const readRoomAround = ({
 // too — and an item not drawn is taken to weigh what the drawn items at that
 // edge of the window weigh. Items of one kind come together (the one-line
 // items of the past, the cards ahead), and an item misjudged is weighed again
-// once it is drawn (see "after slide"): weighing it at the average of all
-// items would draw the cards next to one-line items at the one-line size, and
-// a few dozen of them.
+// once it is drawn (see "after slide"): a window that came up short is
+// extended on the next frame, from what it measured. Weighing an item not drawn
+// at the average of all items, or at the smallest an item can be so that the
+// window never comes up short, walks into the cards at the one-line size,
+// several at a time — the latter measured in wematch: no blank spared, 50–65 ms
+// tasks while reading down through the cards.
 const EDGE_SAMPLE_ITEM_COUNT = 8;
 const createItemSizeReader = (items, start, end, itemSize) => {
   const sizeByIndex = new Map();
@@ -78127,11 +78246,18 @@ const ListResolved = /*#__PURE__*/createComponentResolver([ListFirstResolver, Li
  *   source for is a page (see `<List.Items pageSize>`), whatever either says,
  *   so the first picture costs no second request.
  * @param {number} [props.virtualItemSize]
- *   The size of one item along the scroll axis, in px, when every item has the
- *   same: what the fillers are sized with and what a scroll position is
- *   estimated from. Left out, the list measures its items — once when it
- *   mounts, again when a popup around it opens, and after each commit while
- *   items are held off screen. Given, it never measures.
+ *   The room an item not drawn is held at, in px along the scroll axis: what
+ *   the fillers hold for each item outside the render window, what a scroll
+ *   position inside them is read with, and the least an item on its way takes
+ *   (see `renderSkeleton`). Left out, it is the average of the items measured
+ *   so far — once when the list mounts, again when a popup around it opens,
+ *   and after each commit while items are held off screen. Given, it is the
+ *   worst case: the size every item has, or, in a list whose items differ, the
+ *   smallest an item can be (a thread of one-line items and cards: the
+ *   one-line size) — an item guessed too small builds one more, an item
+ *   guessed too big leaves a blank (see docs/scroll.md, "What the list knows,
+ *   and what it guesses"). The items drawn are measured either way: the render
+ *   window is sized on them.
  * @param {"self"|"parent"|"document"|Element|{current: Element}} [props.scroller="self"]
  *   Which box scrolls — and with it, which box the render window follows and
  *   which box a scroll position is read from (`onScrolledChange`). `"self"`