@jsenv/navi 0.29.433 → 0.29.435

package/dist/dev/jsenv_navi.js

@@ -11514,9 +11514,16 @@ const [publishRouteRender, observeRouteRender] = createPubSub();
  * (recallScrollerPosition). What a push means for them is what it means for
  * the document — an arrival opens at the top (see startAtTop): the page
  * arrived at has its named positions dropped before its lists render, so a
- * list recalls only on the way back. A scroller that goes while its page
- * stays — a popup closing over the same address — has nothing to come back
- * to, and says so as it leaves (forgetScrollerUnlessPageLeft).
+ * list recalls only on the way back. A scroller that outlives a navigation —
+ * its page stays under a new address, or it lives outside the page that
+ * changed — is shown under the new address too, and is carried to it (see
+ * carryScrollersOnceRendered). A scroller that goes while its page stays — a
+ * popup closing over the same address — has nothing to come back to, and says
+ * so as it leaves (forgetScrollerUnlessPageLeft).
+ *
+ * Every position is kept under the address the routing shows, which can be
+ * ahead of the browser's: a replace waiting for its state to settle has moved
+ * the page and not yet `window.location` (see readShownUrl).
  *
  * What is NOT covered, and cannot be from here: a page whose height depends on
  * something still loading. Its content is not there at the moment it is put
@@ -11545,9 +11552,20 @@ let documentOffset = null;
 // url -> (scroller name -> position). The position is whatever the scroller
 // handed in: what it can put itself back on, in its own terms.
 const scrollerPositionsByUrl = new Map();
-// The url each named scroller last spoke under: what tells a scroller leaving
-// a page that stays from one leaving with its page.
-const urlByScrollerName = new Map();
+// What each named scroller still mounted last said: its position and the url
+// it said it under. What tells a scroller leaving a page that stays from one
+// leaving with its page, and what one outliving a navigation is carried with.
+const saidByScrollerName = new Map();
+
+// The address the page is shown under, as the routing knows it (see
+// installScrollRestoration): `window.location` lags behind a replace waiting
+// for its state to settle (replaceAddressWhenSettled in either integration),
+// and a scroll keyed by it meanwhile is written for the address being left.
+// Resolved, as an address handed to navTo can be kept as it was given.
+let readRoutingAddress = () => window.location.href;
+const readShownUrl = () => {
+  return new URL(readRoutingAddress(), window.location.href).href;
+};
 
 // Read once, the first time anyone needs the positions: the document's
 // restoration is installed by the routing, and a list remembering itself may
@@ -11648,11 +11666,12 @@ const holdDocumentScroll = () => {
 };
 
 let installed = false;
-const installScrollRestoration = () => {
+const installScrollRestoration = ({ readAddress }) => {
   if (installed) {
     return;
   }
   installed = true;
+  readRoutingAddress = readAddress;
   if (!("scrollRestoration" in window.history)) {
     return;
   }
@@ -11669,14 +11688,16 @@ const installScrollRestoration = () => {
       if (suspendCount) {
         return;
       }
-      positionByUrl.set(window.location.href, documentOffset);
+      positionByUrl.set(readShownUrl(), documentOffset);
     },
     { passive: true },
   );
-  const positionOnLoad = positionByUrl.get(window.location.href);
+  const urlOnLoad = readShownUrl();
+  const positionOnLoad = positionByUrl.get(urlOnLoad);
   if (!positionOnLoad) {
-    // The first page, where the browser landed it.
-    stayInPlace(window.location.href);
+    // The first page, where the browser landed it: no scroll event says so
+    // (see stayInPlace).
+    positionByUrl.set(urlOnLoad, documentOffset);
     return;
   }
   // What a reload asks for, now that the browser has been told not to do it.
@@ -11729,7 +11750,9 @@ const restoreScrollPosition = (url) => {
 // clamp is a scroll recorded under the url already returned to.
 const restoreScrollPositionOnReturn = (url) => {
   const arrival = ++arrivalCount;
-  const position = positionByUrl.get(new URL(url, window.location.href).href);
+  const href = new URL(url, window.location.href).href;
+  carryScrollersOnceRendered(href);
+  const position = positionByUrl.get(href);
   if (!position) {
     return;
   }
@@ -11771,11 +11794,13 @@ const startAtTop = (url, { from } = {}) => {
     return;
   }
   arrivalCount++;
+  const href = new URL(url, window.location.href).href;
+  carryScrollersOnceRendered(href);
   // Written down as well as done: a document already at its top fires no
   // scroll event, and a page left without ever being scrolled would have no
   // position to come back to — the return would keep the offset of the page
   // being left.
-  positionByUrl.set(new URL(url, window.location.href).href, { x: 0, y: 0 });
+  positionByUrl.set(href, { x: 0, y: 0 });
   window.scrollTo({ top: 0, left: 0, behavior: "instant" });
 };
 const isArrival = (url, { from }) => {
@@ -11789,21 +11814,51 @@ const isArrival = (url, { from }) => {
   return true;
 };
 
-// A url the document is shown under without moving: a replace, a push that
-// keeps the page (see startAtTop), the first page loaded. No scroll event says
-// where it stands, so it is written down here, or a return to it would find
-// nothing and keep the offset of the page being left. The offset the scroll
-// events last told, not read again: a read here would lay the page out in the
-// middle of a routing, once per address a settling param writes.
+// A url the page is shown under without changing: a replace, a push that
+// keeps the page (see startAtTop). Nothing scrolls, so nothing says where the
+// document stands under it — written down here, or a return to it would find
+// nothing and keep the offset of the page being left.
 //
-// Deaf with the recording: a row of tabs replaces the url as it travels, and
-// the offset belongs to nobody until the row says where its tab lands (see
-// arriveAtScrollPosition).
+// The offset as its scroll events last told it, not read again: a read here
+// would lay the page out in the middle of a routing, once per address a
+// settling param writes. Deaf with the recording: a row of tabs replaces the
+// url as it travels, and the offset belongs to nobody until the row says where
+// its tab lands (see arriveAtScrollPosition).
 const stayInPlace = (url) => {
-  if (documentOffset === null || suspendCount) {
-    return;
+  const href = new URL(url, window.location.href).href;
+  carryScrollersOnceRendered(href);
+  if (documentOffset !== null && !suspendCount) {
+    positionByUrl.set(href, documentOffset);
   }
-  positionByUrl.set(new URL(url, window.location.href).href, documentOffset);
+};
+
+// A scroller that outlives a navigation — its page stays under the new url, or
+// it lives outside the page that changed (a sidebar list kept by every page) —
+// is shown under that url as well, and says nothing there unless it moves: a
+// return to it would find no position and open the list at its top. So it is
+// carried, with the position it last said.
+//
+// Told apart once the navigation has rendered: until then a list about to be
+// swapped out is as mounted as one that stays, and carried, its position is
+// what a list of the same name arriving would read. By then one that left has
+// said so (forgetScrollerUnlessPageLeft), and one that arrived has read its
+// own and speaks under this url. One still mounted on its way out (a page kept
+// hidden while its route transition plays) is carried, and forgets the copy as
+// it unmounts under this url.
+const carryScrollersOnceRendered = (url) => {
+  whenPageRendered(() => {
+    if (readShownUrl() !== url) {
+      // Another navigation came first: what is mounted is shown under its url,
+      // and its own carry says so.
+      return;
+    }
+    for (const [name, said] of saidByScrollerName) {
+      if (said.url === url) {
+        continue;
+      }
+      writeScrollerPosition(url, name, said.position);
+    }
+  });
 };
 
 // The same arrival, for the page's own scrollers. The document is scrolled to
@@ -11846,19 +11901,21 @@ const scrollTo = ({ x, y }) => {
 
 const rememberScrollerPosition = (name, position) => {
   loadStore();
-  const url = window.location.href;
+  writeScrollerPosition(readShownUrl(), name, position);
+};
+const writeScrollerPosition = (url, name, position) => {
   let positionByName = scrollerPositionsByUrl.get(url);
   if (!positionByName) {
     positionByName = new Map();
     scrollerPositionsByUrl.set(url, positionByName);
   }
   positionByName.set(name, position);
-  urlByScrollerName.set(name, url);
+  saidByScrollerName.set(name, { url, position });
 };
 
 const recallScrollerPosition = (name) => {
   loadStore();
-  const positionByName = scrollerPositionsByUrl.get(window.location.href);
+  const positionByName = scrollerPositionsByUrl.get(readShownUrl());
   if (!positionByName) {
     return undefined;
   }
@@ -11868,17 +11925,18 @@ const recallScrollerPosition = (name) => {
 // Said by a scroller as it unmounts. Its page is being left when the url is
 // already another one — the history is written before the page it names is
 // taken down — and then its position is kept for the way back. The url still
-// being the one it spoke under means the page stays and the scroller alone
-// goes (a popup closing, a section folding): there is no coming back to a
-// place that was not left, and a position kept would greet the next mount
+// being the one it was last kept under means the page stays and the scroller
+// alone goes (a popup closing, a section folding): there is no coming back to
+// a place that was not left, and a position kept would greet the next mount
 // under this address as a return.
 const forgetScrollerUnlessPageLeft = (name) => {
-  const url = urlByScrollerName.get(name);
-  if (url === undefined) {
+  const said = saidByScrollerName.get(name);
+  if (said === undefined) {
     return;
   }
-  urlByScrollerName.delete(name);
-  if (url !== window.location.href) {
+  saidByScrollerName.delete(name);
+  const { url } = said;
+  if (url !== readShownUrl()) {
     return;
   }
   const positionByName = scrollerPositionsByUrl.get(url);
@@ -12406,7 +12464,7 @@ const setupBrowserIntegrationViaHistory = ({
   // The browser's own scroll restoration is taken over here rather than left
   // to whoever navigates: it is a decision about the document, and the entry
   // being left must be recorded from the first pixel scrolled.
-  installScrollRestoration();
+  installScrollRestoration({ readAddress });
 
   // The document is leaving, or may be killed in the background: what the
   // entry says about it has to be what the document says (see
@@ -12880,15 +12938,12 @@ const useNavStateWithWarnings = (id, options) => {
     ownerRef.current = {};
   }
   const owner = ownerRef.current;
-  // Claimed during render so warnAboutOrphanGeneratedKeys sees every id of
-  // the commit, including the ones whose effect has not run yet. The conflict
-  // is judged in the effect: when a screen replaces another in one commit,
-  // preact renders the new children before unmounting the old ones, so at
-  // render time the id may still be held by a component about to go.
-  if (id !== undefined && !idUsageMap.has(id)) {
-    idUsageMap.set(id, { owner, stackTrace: new Error().stack });
-  }
 
+  // Claimed in the effect, never during render: only the effect has a cleanup
+  // to give the id back, and a render is not always followed by its effects.
+  // A page parked by a Suspense boundary (every hook cleanup run), rendered
+  // again and taken down before the paint, leaves a render-time claim holding
+  // the id for nobody — and the next mount reads a conflict.
   useEffect(() => {
     if (id === undefined) {
       return undefined;
@@ -12902,12 +12957,9 @@ This can cause UI state conflicts and unexpected behavior.
 Consider using unique IDs for each component instance.`,
       );
     } else {
-      // Also set when absent: preact/compat's Suspense parks a subtree by
-      // running every hook cleanup in it, and the render resuming it carries
-      // the same id.
       idUsageMap.set(id, { owner, stackTrace: new Error().stack });
     }
-    warnAboutOrphanGeneratedKeys();
+    scheduleOrphanGeneratedKeysCheck();
     return () => {
       if (idUsageMap.get(id)?.owner === owner) {
         idUsageMap.delete(id);
@@ -12923,6 +12975,20 @@ Consider using unique IDs for each component instance.`,
 // and the mount coming back to the entry generates another id: the state is
 // there, and nothing reads it. Reported when a component mounting on the entry
 // finds such a key, the moment someone expected the state back.
+//
+// Checked once every effect of the flush has claimed its id: a component
+// whose effect comes later in the same flush is not an orphan.
+let orphanGeneratedKeysCheckScheduled = false;
+const scheduleOrphanGeneratedKeysCheck = () => {
+  if (orphanGeneratedKeysCheckScheduled) {
+    return;
+  }
+  orphanGeneratedKeysCheckScheduled = true;
+  queueMicrotask(() => {
+    orphanGeneratedKeysCheckScheduled = false;
+    warnAboutOrphanGeneratedKeys();
+  });
+};
 const warnAboutOrphanGeneratedKeys = () => {
   const state = browserIntegration.getDocumentState();
   if (!state) {
@@ -33440,6 +33506,20 @@ const toHex = ([r, g, b]) =>
 // sure to be understood in, whatever getComputedStyle answered with.
 let colorContext = null;
 const parseColor = (color) => {
+  const [r, g, b, a] = drawColor(color);
+  if (a === 0 || a === 255) {
+    return [r, g, b, a / 255];
+  }
+  // The canvas keeps a pixel premultiplied by its alpha, in bytes: the
+  // channels of a translucent colour come back rounded at that alpha —
+  // rgba(12, 23, 44, 0.45) reads 11, 22, 44. Made opaque, they read whole.
+  const [rOpaque, gOpaque, bOpaque] = drawColor(
+    `color(from ${color} srgb r g b / 1)`,
+  );
+  return [rOpaque, gOpaque, bOpaque, a / 255];
+};
+
+const drawColor = (color) => {
   if (!colorContext) {
     const canvas = document.createElement("canvas");
     canvas.width = 1;
@@ -33452,8 +33532,7 @@ const parseColor = (color) => {
   colorContext.fillStyle = "transparent";
   colorContext.fillStyle = color;
   colorContext.fillRect(0, 0, 1, 1);
-  const [r, g, b, a] = colorContext.getImageData(0, 0, 1, 1).data;
-  return [r, g, b, a / 255];
+  return colorContext.getImageData(0, 0, 1, 1).data;
 };
 
 // The title belongs to the last Head to arrive, whatever order they leave in:
@@ -49662,6 +49741,15 @@ const applySpacingOnTextChildren = (children, spacing, defaultSpace) => {
   }
   return childrenWithGap;
 };
+const isSpacingWidth = spacing => {
+  if (typeof spacing === "number") {
+    return true;
+  }
+  if (typeof spacing !== "string") {
+    return false;
+  }
+  return isSizeSpacingKey(spacing) || hasCSSSizeUnit(spacing) || spacing.startsWith("var(");
+};
 const outsideTextFlowSet = new Set();
 const markAsOutsideTextFlow = jsxElement => {
   outsideTextFlowSet.add(jsxElement);
@@ -49929,7 +50017,11 @@ const TextUI = props => {
   }
   const shouldPreserveSpacing = rest.as === "pre" || rest.flex || rest.grid;
   if (shouldPreserveSpacing) {
-    boxProps.spacing = resolvedSpacing;
+    // Between flex/grid items spacing is a gap, so only a width carries over: a
+    // separator (the default space, a text, an element) or "pre" has no gap.
+    if (isSpacingWidth(spacing)) {
+      boxProps.spacing = spacing;
+    }
   } else {
     children = applySpacingOnTextChildren(children, resolvedSpacing, defaultSpace);
   }
@@ -54578,6 +54670,26 @@ const Expandable = props => {
     return stopRide;
   };
 
+  // A silent change is a state the page was already in (see openEffect): it
+  // lands at once. Not playing a reveal is not enough — the stylesheet's own
+  // transition plays it whenever the previous state's style was resolved
+  // before the render: an expandable mounted closed and measured in the same
+  // commit (a List sizing its items) before its deferred mount-time open, or
+  // one kept on screen across the page change.
+  const renderWithoutMovement = (contentContainer, render) => {
+    if (!animation || !contentContainer) {
+      flushSyncRendering(render);
+      return;
+    }
+    contentContainer.style.transitionProperty = "none";
+    flushSyncRendering(render);
+    // The new style must be resolved while transitions are off — re-enabled
+    // in the same recalc, the change would transition after all.
+    // eslint-disable-next-line no-unused-expressions
+    getComputedStyle(contentContainer).transitionProperty;
+    contentContainer.style.transitionProperty = "";
+  };
+
   // What opening LOOKS like here, and how to undo it — the one thing an
   // expandable owns that a popup does not (see open_controller.js). Reassigned
   // on every render so it always closes over the latest props.
@@ -54598,10 +54710,15 @@ const Expandable = props => {
     // reopening during a collapse — read while the DOM still says closed.
     const startRect = revealing ? contentContainer.getBoundingClientRect() : null;
     cancelSettleWatch();
-    flushSyncRendering(() => {
+    const renderOpened = () => {
       setOpened(true);
       setSettled(!revealing);
-    });
+    };
+    if (silent) {
+      renderWithoutMovement(contentContainer, renderOpened);
+    } else {
+      flushSyncRendering(renderOpened);
+    }
     if (hasAction) {
       runUnwatched(() => effectiveAction.run());
     }
@@ -54640,16 +54757,22 @@ const Expandable = props => {
       cancelSettleWatch();
       // `silent`: closed by the navigation that puts another page on screen,
       // which is its movement (see page_change.js).
-      const collapsing = animation && !closeEvent.detail.silent && Boolean(contentContainerAtClose);
+      const silentClose = Boolean(closeEvent.detail.silent);
+      const collapsing = animation && !silentClose && Boolean(contentContainerAtClose);
       if (collapsing) {
         // Now, while the content is still fully laid out — the collapsing
         // track uncovers a content frozen at that size.
         freezeContentSize();
       }
-      flushSyncRendering(() => {
+      const renderClosed = () => {
         setOpened(false);
         setSettled(!collapsing);
-      });
+      };
+      if (silentClose) {
+        renderWithoutMovement(contentContainerAtClose, renderClosed);
+      } else {
+        flushSyncRendering(renderClosed);
+      }
       if (restoreFocus) {
         restoreFocus(closeEvent);
       } else if (focusedBeforeClose && contentContainerAtClose && contentContainerAtClose.contains(focusedBeforeClose)) {
@@ -74567,6 +74690,45 @@ const LIST_STYLE_CSS_VARS = {
   backgroundColor: "--list-background-color"
 };
 const LIST_PSEUDO_CLASSES = [":hover", ":focus", ":focus-visible", ":focus-within", ":read-only", ":disabled", ":-navi-void", ":-navi-expanded"];
+// Two lists mounted at once under one `id` are one entry to the scroll memory:
+// each overwrites the other's position (see docs/scroll.md). Said the moment
+// the second one mounts, once per id — on a route transition, that is the page
+// arriving while the page being left is still mounted, hidden.
+const createSharedRememberedIdWarning = () => {
+  const mountedListsById = new Map();
+  const warnedIdSet = new Set();
+  return (listId, rememberScroll, ref) => {
+    useLayoutEffect(() => {
+      if (!rememberScroll) {
+        return undefined;
+      }
+      let mountedLists = mountedListsById.get(listId);
+      if (!mountedLists) {
+        mountedLists = new Set();
+        mountedListsById.set(listId, mountedLists);
+      }
+      const mounted = {
+        element: ref.current
+      };
+      if (mountedLists.size > 0 && !warnedIdSet.has(listId)) {
+        warnedIdSet.add(listId);
+        const [other] = mountedLists;
+        console.warn(`<List id="${listId}"> mounted while another list with this id is mounted. The position a list comes back to is kept under its id, so the two overwrite each other's: the one arriving can open where the other one was, or come back at its top. Lists are mounted together on one page, under a popup, in a bar every page keeps, and during a route transition, whose page being left stays mounted until the movement ends. Give each list an id naming it in the app (a component drawing a list on several pages takes its id from the page), or set scrollResetOnNavigation on a list with no use for coming back. See docs/scroll.md.`, {
+          list: mounted.element,
+          otherList: other.element
+        });
+      }
+      mountedLists.add(mounted);
+      return () => {
+        mountedLists.delete(mounted);
+        if (mountedLists.size === 0) {
+          mountedListsById.delete(listId);
+        }
+      };
+    }, [listId, rememberScroll]);
+  };
+};
+const useWarnSharedRememberedId = createSharedRememberedIdWarning() ;
 const useListScrollSync = ({
   ref,
   listItems,
@@ -75473,6 +75635,7 @@ const useListScrollSync = ({
       }
     };
   }, []);
+  useWarnSharedRememberedId(listId, rememberScroll, ref);
 
   // A list that gets narrower rewraps every item it holds, so everything below
   // moves and the reader loses their place — the very thing scrolling a long
@@ -79582,9 +79745,11 @@ const ListResolved = /*#__PURE__*/createComponentResolver([ListFirstResolver, Li
  *   does, and for a list that scrolls itself the page's own restoration cannot
  *   see. The position is kept under the list's `id` and the page's url, for
  *   the session (a reload comes back too); a list without an `id` of its own
- *   has nothing to be remembered by. A fresh arrival at the page opens at
- *   `defaultScrolled` either way, and so does a list the caller holds through
- *   `scrolled`.
+ *   has nothing to be remembered by, and two lists mounted at once under one
+ *   `id` — a popup over the page, the page a route transition is leaving —
+ *   overwrite each other (see docs/scroll.md). A fresh arrival at the page
+ *   opens at `defaultScrolled` either way, and so does a list the caller holds
+ *   through `scrolled`.
  * @param {boolean} [props.deselectable]
  *   A single-select list allowed to hold nothing: the selected item, pressed
  *   again, lets go. Without it the list is a radio group — a choice, once