@jsenv/navi 0.29.364 → 0.29.366

package/dist/dev/jsenv_navi.js

@@ -28872,6 +28872,8 @@ const visitedUrlsSignal = browserIntegration.visitedUrlsSignal;
 browserIntegration.handleActionTask;
 
 const idUsageMap = new Map();
+// Keys found in the entry with nobody to claim them, already reported.
+const orphanKeysReported = new Set();
 const useNavStateWithWarnings = (id, options) => {
   const idRef = useRef(undefined);
   if (idRef.current !== id) {
@@ -28895,6 +28897,15 @@ Consider using unique IDs for each component instance.`,
   }
 
   useEffect(() => {
+    // Registered here as well as in the render above: preact/compat's
+    // Suspense parks a subtree by running every hook cleanup in it, and the
+    // render resuming it carries the same id.
+    if (!idUsageMap.has(id)) {
+      idUsageMap.set(id, {
+        stackTrace: new Error().stack,
+      });
+    }
+    warnAboutOrphanGeneratedKeys();
     return () => {
       idUsageMap.delete(id);
     };
@@ -28903,6 +28914,31 @@ Consider using unique IDs for each component instance.`,
   return useNavStateBasic(id, options);
 };
 
+// A generated id (preact's useId()) names one mount. State written under one
+// outlives that mount in the history entry — a page left with a popup open —
+// 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.
+const warnAboutOrphanGeneratedKeys = () => {
+  const state = browserIntegration.getDocumentState();
+  if (!state) {
+    return;
+  }
+  for (const key of Object.keys(state)) {
+    if (
+      !isLikelyPreactGeneratedId(key) ||
+      idUsageMap.has(key) ||
+      orphanKeysReported.has(key)
+    ) {
+      continue;
+    }
+    orphanKeysReported.add(key);
+    console.warn(
+      `useNavState: this history entry holds "${key}", written by a component whose id was generated (preact's useId()) and that is not mounted anymore — a Picker without an id, a popup with navState and no id. A generated id names one mount, so nothing will read that state again: a popup open when this screen was left comes back closed. Give the component a stable id if it was meant to be found as it was.`,
+    );
+  }
+};
+
 const NO_OP = () => {};
 const NO_ID_GIVEN = [undefined, NO_OP, NO_OP];
 // What the computed below answers for a key the document state does not hold:
@@ -60567,6 +60603,13 @@ const clipOf = (side, distance) => {
  * (TARGET_WAIT_MS), on the half-strength frame where the anchor is still
  * readable, and lifts the moment it is there.
  *
+ * A closing may land where no opening took off: a dialog opened the plain way
+ * (`animation={{ open, close: "lifting" }}` in dialog.jsx), closing into a box the close
+ * itself brings — the state `onClose` writes renders the place the lifted node
+ * belongs to. So the box a closing comes back to is read once the change is
+ * made, inside the transition, and when the caller named it (`liftAnchor`) it
+ * is waited for (LANDING_WAIT_MS): the new picture is taken once it is there.
+ *
  * One name serves the whole movement, because only one of the two boxes is on
  * screen at a time: it names the anchor while the popup is closed, and the
  * lifted node while it is open.
@@ -60609,6 +60652,12 @@ const ARRIVING_ATTRIBUTE = "data-navi-popup-lift-arriving";
 // stands, without a movement, so a target that never comes cannot keep it
 // unpainted.
 const TARGET_WAIT_MS = 1000;
+// How long a closing waits for the box it comes back to, when that box is
+// brought by the close (see this file's top comment). The page is frozen on
+// the picture of the open popup meanwhile, so the wait is short: what it
+// covers is a render, not a fetch. Past it the popup's picture plays out on
+// its own.
+const LANDING_WAIT_MS = 300;
 // The popup's own animation duration, published on the root because the
 // ::view-transition tree hangs off it and inherits from nowhere else.
 const DURATION_PROPERTY = "--navi-popup-lift-duration";
@@ -60649,14 +60698,16 @@ let releaseScrollHold = null;
  * a view transition morphing the anchor's box into the lifted node's, or back.
  *
  * `opened` says which way: the box being left is the anchor when the popup is
- * opening and the lifted node when it is closing. `lift` is Dialog's own prop
- * of that name.
+ * opening and the lifted node when it is closing. `resolveAnchor` is read on
+ * the spot for an opening, and once the change is made for a closing;
+ * `waitForAnchor` has a closing wait for it when it is not there yet. `lift`
+ * is Dialog's own prop of that name.
  */
 const liftPopupFromAnchor = (
   popupEl,
-  anchorElement,
+  resolveAnchor,
   applyChange,
-  { opened, lift },
+  { opened, lift, waitForAnchor },
 ) => {
   const startViewTransition = ensureDocumentStartViewTransition();
   // A movement still wearing the name would make the name two elements wide,
@@ -60664,7 +60715,7 @@ const liftPopupFromAnchor = (
   // document.
   releaseLiftInProgress?.();
 
-  const elementLeaving = opened ? anchorElement : resolveLiftTarget(popupEl);
+  const elementLeaving = opened ? resolveAnchor() : resolveLiftTarget(popupEl);
   // Read before the first write: the read brings the style up to date, and a
   // write before it would make it bring it up to date once more.
   const duration = getComputedStyle(popupEl)
@@ -60688,12 +60739,14 @@ const liftPopupFromAnchor = (
 
   let giveBackNameArriving = null;
   let stopWaitingForTarget = null;
+  let stopWaitingForAnchor = null;
   const release = () => {
     if (releaseLiftInProgress !== release) {
       return;
     }
     releaseLiftInProgress = null;
     stopWaitingForTarget?.();
+    stopWaitingForAnchor?.();
     boxAnimationInProgress?.cancel();
     boxAnimationInProgress = null;
     releaseScrollHold?.();
@@ -60719,13 +60772,18 @@ const liftPopupFromAnchor = (
     const boxLeaving = room ? elementLeaving.getBoundingClientRect() : null;
     let boxArriving = null;
     let cornersArriving = null;
-    const viewTransition = startViewTransition(() => {
+    const viewTransition = startViewTransition(async () => {
       // The name is the arriving box's from here on: worn by both, it is worn
       // by neither. Written rather than removed, so a name the element also
       // has from a stylesheet cannot resurface for the length of the movement.
       elementLeaving.style.setProperty(NAME_PROPERTY, "none");
       change();
-      const elementArriving = resolveElementArriving();
+      const elementArriving = await resolveElementArriving();
+      // Replaced while waiting for its landing: the movement replacing it
+      // holds the name now.
+      if (releaseLiftInProgress !== release) {
+        return;
+      }
       if (elementArriving) {
         giveBackNameArriving = wearLiftName(elementArriving);
         cornersArriving = readCorners(elementArriving);
@@ -60750,12 +60808,33 @@ const liftPopupFromAnchor = (
   };
 
   if (!opened) {
-    startMovement(applyChange, () =>
+    startMovement(applyChange, () => {
+      const anchorElement = resolveAnchor();
+      if (anchorElement?.isConnected) {
+        return anchorElement;
+      }
       // Gone from the document while the popup was open (the row it stood in
       // was removed): nothing to arrive at, and the browser plays the popup's
       // picture out on its own.
-      anchorElement.isConnected ? anchorElement : null,
-    );
+      if (!waitForAnchor) {
+        return null;
+      }
+      return new Promise((resolve) => {
+        stopWaitingForAnchor = whenAnchorAppears(resolveAnchor, (element) => {
+          stopWaitingForAnchor = null;
+          // Not when stopped by a movement replacing this one.
+          if (
+            !element &&
+            releaseLiftInProgress === release
+          ) {
+            console.warn(
+              `[navi] Dialog's "liftAnchor" named nothing on screen within ${LANDING_WAIT_MS}ms of the close, so the dialog closes without landing. The element it names is where the box comes back to: in the document at the close, or rendered by what the close changes (onClose).`,
+            );
+          }
+          resolve(element);
+        });
+      });
+    });
     return;
   }
 
@@ -60915,6 +60994,40 @@ const whenLiftTargetAppears = (popupEl, callback) => {
   return stop;
 };
 
+// Calls `callback` with the anchor once `resolveAnchor` finds it in the
+// document, or with null past LANDING_WAIT_MS — or when stopped, since the
+// transition's update is waiting on it. Returns how to stop.
+const whenAnchorAppears = (resolveAnchor, callback) => {
+  const observer = new MutationObserver(() => {
+    const anchorElement = resolveAnchor();
+    if (anchorElement?.isConnected) {
+      stop(anchorElement);
+    }
+  });
+  observer.observe(document.documentElement, {
+    childList: true,
+    subtree: true,
+    attributes: true,
+    attributeFilter: ["id"],
+  });
+  const timeout = setTimeout(() => {
+    stop(null);
+  }, LANDING_WAIT_MS);
+  let stopped = false;
+  const stop = (anchorElement = null) => {
+    if (stopped) {
+      return;
+    }
+    stopped = true;
+    observer.disconnect();
+    clearTimeout(timeout);
+    callback(anchorElement);
+  };
+  return () => {
+    stop(null);
+  };
+};
+
 const ignore = () => {};
 
 // The room the fixed bars leave, in viewport coordinates; null without bars.
@@ -61580,6 +61693,18 @@ const css$E = /* css */`
     opacity: 0;
   }
 
+  /* A closing lift is the dialog leaving as a picture: whatever exit its
+     opening animation arms (animation={{ open, close: "lifting" }}, see
+     popup_css.js) would
+     keep it rendered into the picture of the state it closes into. */
+  :root[data-navi-popup-lift="closing"] {
+    .navi_dialog,
+    .navi_dialog::backdrop,
+    .navi_dialog_backdrop {
+      transition: none;
+    }
+  }
+
   /* While a dialog is lifting out of the element that opened it
      (popup_lift.js). The page around IS taken as a picture, the browser's own
      default, and on purpose: the wall and what the dialog holds around the
@@ -61822,7 +61947,7 @@ const css$E = /* css */`
  *   scroll while open (its backdrop only covers the scrollport, so scrolling
  *   there would reveal uncovered content); this prop extends the lock to the
  *   whole page. Defaults to `true` for a dialog docked by `dockedOnSmallTouchScreen`.
- * @param {boolean|"auto"|"fading"|"scaling"|"sliding"|"lifting"|`slide-from-${string}`} [props.animation]
+ * @param {boolean|"auto"|"fading"|"scaling"|"sliding"|"lifting"|`slide-from-${string}`|{open: boolean|"auto"|"fading"|"scaling"|"sliding"|`slide-from-${string}`, close: "lifting"}} [props.animation]
  *   - `true`/`"auto"` resolves to `"scaling"` for a centered `positionArea`,
  *   or a concrete `"slide-from-*"` direction otherwise. Any other explicit
  *   value is used as-is. `"lifting"` is the odd one out: every other kind
@@ -61841,6 +61966,15 @@ const css$E = /* css */`
  *   being what the movement leaves rather than a context to keep readable;
  *   `backdropVariant="discrete"` asks for the light wash back. See
  *   `popup_lift.js`.
+ *   - `{ open, close: "lifting" }`: the close alone lifts. The dialog opens
+ *   with `open` (any value above but `"lifting"`), and its `data-lift` node
+ *   travels into `liftAnchor` on close — for a dialog that did not come out
+ *   of what it lands in (a banner opens a full-screen reveal, closing it puts
+ *   the crest in its place on the plate that replaces the banner). The box it
+ *   lands in may be rendered by the close itself: `liftAnchor` is read once
+ *   `onClose` has run, and waited for a moment when it is not there yet.
+ *   `"lifting"` is the only `close` that differs from the opening: every
+ *   other kind closes by playing its opening backwards.
  * @param {"box"|"scene"} [props.lift="box"] - Under `animation="lifting"`,
  *   what the anchor and what it becomes are to each other, which decides
  *   how their pictures sit in the box moving between them. `"box"`: one
@@ -61865,14 +61999,15 @@ const css$E = /* css */`
  *   `document.getElementById` when the dialog opens — see popover.jsx's own
  *   `anchor` doc for why (mainly `defaultOpen`).
  * @param {Element|{current: Element}|string} [props.liftAnchor] - Under
- *   `animation="lifting"`, where the closing brings the box back to, when that
- *   is no longer where it came from: a popup one walks through (a row of cards
- *   shown one at a time) has something else in front by the time it closes,
- *   and the box would otherwise fly back to the card the press opened on. Same
- *   grammar as `anchor` (element, ref or id), resolved at the close, so
- *   whatever names the card currently in front — an id built from the signal
- *   the walk is bound to, a ref moved with it — is read then and not at the
- *   opening. Left out, the box comes back to the anchor it came out of.
+ *   `animation="lifting"` or `animation={{ open, close: "lifting" }}`, where the closing
+ *   brings the box back to, when that is not where it came from: a popup one
+ *   walks through (a row of cards shown one at a time) has something else in
+ *   front by the time it closes, and the box would otherwise fly back to the
+ *   card the press opened on. Same grammar as `anchor` (element, ref or id),
+ *   resolved once the close is made — after `onClose` — so whatever names the
+ *   card currently in front, or the box the close itself renders, is read
+ *   then and not at the opening. Left out, the box comes back to the anchor
+ *   it came out of.
  * @param {boolean} [props.sizeFromAnchor=false] - Whether the dialog takes the
  *   anchor's width/height as a min-width/min-height floor
  *   (`--anchor-width`/`--anchor-height`). Off by default: unlike a popover,
@@ -62360,7 +62495,18 @@ const useDialogProps = props => {
     flushEdges.left = expandX || x === "left" || x === "inset-left";
     flushEdges.right = expandX || x === "right" || x === "inset-right";
   }
-  const isAutoAnimation = animation === true || animation === "auto";
+
+  // `{ open, close }` says each way on its own; a single value says both.
+  const {
+    open: openAnimation,
+    close: closeAnimation = openAnimation
+  } = animation !== null && typeof animation === "object" ? animation : {
+    open: animation
+  };
+  if (closeAnimation !== openAnimation && closeAnimation !== "lifting") {
+    console.warn(`[navi] Dialog animation={{ close: ${JSON.stringify(closeAnimation)} }}: "lifting" is the only close that differs from the opening; every other kind closes by playing the opening backwards.`);
+  }
+  const isAutoAnimation = openAnimation === true || openAnimation === "auto";
   // The dialog and the anchor are one box, and what plays between them is the
   // browser's own morph (popup_lift.js) — nothing this dialog does to its own
   // box. So it arms no CSS transition of its own, which is not merely useless
@@ -62368,11 +62514,12 @@ const useDialogProps = props => {
   // with allow-discrete, and a dialog kept rendered for the length of its exit
   // is exactly what the picture taken of the state it closes into must not
   // show.
-  const lifting = animation === "lifting";
+  const lifting = openAnimation === "lifting";
+  const liftsOnClose = closeAnimation === "lifting";
   // Dialog never has a real anchor to POSITION against (see this file's top
   // comment), so this is always the "no anchor" path — the same one Popover's
   // own custom renderer falls into when it has no real anchor either.
-  const resolvedAnimationKind = isAutoAnimation ? resolveAutoAnimationKind(undefined, parsedPositionArea) : animation;
+  const resolvedAnimationKind = isAutoAnimation ? resolveAutoAnimationKind(undefined, parsedPositionArea) : openAnimation;
   // Not gated on isAutoAnimation — an explicit animation="sliding" needs a
   // concrete direction just as much as an auto-resolved one does (same as
   // Popover's own "sliding"/"expanding" resolution step in openEffect).
@@ -62421,13 +62568,11 @@ const useDialogProps = props => {
   // is in front NOW, which only the caller knows. Resolved at the close for
   // that reason: the element it names changes while the popup is open, so
   // anything read at the opening would be the walk's starting point again.
+  // Silent when it names nothing: the close may be what renders it, and
+  // popup_lift.js asks again until it is there (and warns past that).
   const resolveLiftAnchorElement = () => {
     if (typeof liftAnchor === "string") {
-      const liftAnchorElementById = document.getElementById(liftAnchor);
-      if (!liftAnchorElementById) {
-        console.warn(`Dialog: liftAnchor="${liftAnchor}" did not match any element`);
-      }
-      return liftAnchorElementById;
+      return document.getElementById(liftAnchor);
     }
     // A ref is unwrapped even when it holds nothing, the same way `anchor` is:
     // the ref object itself has no box to come back to.
@@ -62439,7 +62584,7 @@ const useDialogProps = props => {
   // provided the change happens between its two pictures, which is what
   // handing it to the controller buys (see popup_lift.js and
   // open_controller.js's own transitionChange).
-  openController.transitionChange = lifting ? (applyChange, {
+  openController.transitionChange = liftsOnClose ? (applyChange, {
     opened,
     event
   }) => {
@@ -62447,29 +62592,29 @@ const useDialogProps = props => {
     // A mount-time opening was never seen closed (see openEffect's own
     // `silent`): there is no box it comes from, because nothing was shown
     // before it.
-    if (!dialogEl || opened && event.detail.silent) {
+    if (!dialogEl || opened && (!lifting || event.detail.silent)) {
       applyChange();
       return;
     }
-    let anchorElement;
-    if (opened) {
-      anchorElement = resolveAnchorElement(event);
-    } else if (liftAnchor) {
-      anchorElement = resolveLiftAnchorElement();
-    } else {
-      anchorElement = anchorElementRef.current;
+    if (!opened) {
+      // Read once the close is made (popup_lift.js): the box it lands in
+      // may be one the close itself renders.
+      liftPopupFromAnchor(dialogEl, liftAnchor ? resolveLiftAnchorElement : () => anchorElementRef.current, applyChange, {
+        opened,
+        lift,
+        waitForAnchor: Boolean(liftAnchor)
+      });
+      return;
     }
+    const anchorElement = resolveAnchorElement(event);
     if (!anchorElement) {
-      if (opened) {
+      {
         console.warn(`[navi] Dialog has animation="lifting" and no anchor to lift out of, so it simply appears. The anchor is whatever opened it — a <Button command="--navi-open">, the "source" given to triggerNaviCommand — or the "anchor" prop.`);
       }
-      if (!opened && liftAnchor) {
-        console.warn(`[navi] Dialog has animation="lifting" and a "liftAnchor" naming nothing on screen, so it simply closes. The element it names is where the box comes back to, and it has to be in the document at the close.`);
-      }
       applyChange();
       return;
     }
-    liftPopupFromAnchor(dialogEl, anchorElement, applyChange, {
+    liftPopupFromAnchor(dialogEl, () => anchorElement, applyChange, {
       opened,
       lift
     });
@@ -65284,8 +65429,8 @@ const PickerCustom = props => {
   // before computing popupId below, so two Pickers without an explicit id never collide.
   // Captured before the fallback chain below overwrites props.id — needed to
   // know whether the id actually came from the caller (stable) or from
-  // useId()/ControlIdContext (not guaranteed stable across a reload), see
-  // pickerNavType below.
+  // useId()/ControlIdContext (a generated id names one mount: a reload, or a
+  // return to this page, generates another), see pickerNavType below.
   const hasExplicitId = Boolean(props.id);
   const idDefault = useId();
   const controlId = useContext(ControlIdContext);
@@ -65362,10 +65507,12 @@ const PickerCustom = props => {
     // pushes a history entry so the back button closes it. Every other case
     // (popover mode, or a dialog whose id was auto-generated via useId()/
     // ControlIdContext) replaces the current history state instead — a
-    // generated id isn't stable across a reload, so pushing it would either
-    // silently drop the entry or, worse, collide with a different
-    // component's own generated id (see useNavState's own fallback for the
-    // same concern, applied here proactively for the id we control).
+    // generated id names one mount, so pushing it would either leave an entry
+    // nothing reads or, worse, collide with a different component's own
+    // generated id (see useNavState's own fallback for the same concern,
+    // applied here proactively for the id we control). What a generated id
+    // costs either way: the state is written, and the mount coming back to
+    // the page (or a reload) finds it under a key it does not have.
     const pickerNavType = mode === "dialog" && hasExplicitId ? "push" : "replace";
     const [expanded, enterExpanded, leaveExpanded] = useNavState(popupId, {
       type: pickerNavType,
@@ -65904,6 +66051,7 @@ const PickerContentInsidePopup = props => {
     popupWidthFitContent,
     animation,
     lift,
+    liftAnchor,
     animationDuration,
     // mode="callout": what the callout says about what it holds, and paints
     // in its border and icon — "none" for a plain tooltip (see the callout
@@ -66000,6 +66148,7 @@ const PickerContentInsidePopup = props => {
       dockedOnSmallTouchScreen: isPopover ? undefined : dockedOnSmallTouchScreen,
       sizeFromAnchor: isPopover ? undefined : dialogSizeFromAnchor,
       lift: isPopover ? undefined : lift,
+      liftAnchor: isPopover ? undefined : liftAnchor,
       children: jsx(PopupModeContext.Provider, {
         value: mode,
         children: children
@@ -75471,8 +75620,9 @@ const PickerFirstResolver = props => {
  *   children?: import("ignore:preact").ComponentChildren,
  *   mode?: "popover" | "dialog" | "callout",
  *   openOn?: "press" | "longpress" | "contextmenu" | string | string[],
- *   animation?: boolean | "auto" | "fading" | "scaling" | "sliding" | "lifting" | `slide-from-${string}`,
+ *   animation?: boolean | "auto" | "fading" | "scaling" | "sliding" | "lifting" | `slide-from-${string}` | { open: boolean | "auto" | "fading" | "scaling" | "sliding" | `slide-from-${string}`, close: "lifting" },
  *   lift?: "box" | "scene",
+ *   liftAnchor?: Element | { current: Element } | string,
  *   animationDuration?: string,
  *   calloutStatus?: "info" | "warning" | "error" | "success" | "none",
  *   calloutIcon?: boolean,
@@ -75631,6 +75781,12 @@ const PickerFirstResolver = props => {
  *   content failed to load, its value could not be resolved…). Shown as a
  *   callout on the trigger, open or closed — the caller has nothing to place.
  *   Dismissing it discards that error; a new `error` value raises another one.
+ * @param {string} [id] What the popup's open state is kept under in the
+ *   history entry: a screen left and come back to finds the picker open, and
+ *   in dialog mode the opening is an entry of its own, closed by the back
+ *   button before the screen is left. Left out, the key is a generated id,
+ *   which names one mount: the state survives neither leaving the screen nor a
+ *   reload. A picker whose popup leads somewhere (a link inside it) has one.
  * @param {"popover"|"dialog"|"callout"} [mode] Which popup the children open
  *   in. Left out, a popover on a large screen and a dialog on a narrow one.
  *   `"callout"` shows them in the picker's own callout — the speech bubble its
@@ -75843,6 +75999,11 @@ const PickerFirstResolver = props => {
  *   that opens precisely to get bigger. It brings an opaque, blurred backdrop
  *   with it (`--navi-backdrop-lift-*`); `backdropVariant="discrete"` asks for
  *   the light wash back.
+ * @param {Element|{current: Element}|string} [liftAnchor] Dialog mode,
+ *   Dialog's own: where a lifting close lands when that is not the trigger
+ *   (`animation="lifting"`, or `animation={{ open, close: "lifting" }}` for a
+ *   popup that opens the plain way and only lands on close),
+ *   read once the close is made (after `onClose`).
  * @param {"box"|"scene"} [lift="box"] Dialog's own, under `animation="lifting"`:
  *   `"box"` for a card that extends (its top stays, the box uncovers the rest),
  *   `"scene"` for a thumbnail that is a band cut from the middle of the bigger