@jsenv/navi 0.29.424 → 0.29.426

package/dist/dev/jsenv_navi.js

@@ -7,7 +7,7 @@ import { createPubSub, elementIsFocusable, createIterableWeakSet, dispatchIntern
 export { chainEvent, clickIsSuppressed, contrastColor, createDragGestureController, dragAfterIntent, findEvent, markDragSource, startDragTo } from "@jsenv/dom";
 import { signal, computed, effect, untracked, batch, useComputed, useSignal } from "@preact/signals";
 import { options, isValidElement, createContext, render, h, toChildArray, createRef, cloneElement, createElement, Fragment as Fragment$1 } from "preact";
-import { useErrorBoundary, useLayoutEffect, useContext, useMemo, useRef, useEffect, useCallback, useState, useReducer, useId } from "preact/hooks";
+import { useErrorBoundary, useLayoutEffect, useContext, useState, useMemo, useRef, useEffect, useCallback, useReducer, useId } from "preact/hooks";
 import { humanizeI18n, prefixFirstAndIndentRemainingLines, setRuntimeLangSource, formatDuration, formatMonth, formatDay, resolveTimeRangePrecision, formatDatePlaceholder, toDate, getRelativeDay, formatDayRelative, formatMonthPlaceholder, formatWeekPlaceholder, formatDatetimePlaceholder, formatDatetime, toTimeOfDay, formatTimeOfDay, formatTime, formatMinuteDuration, formatSecondDuration, formatHourDuration, formatTimeRelative, formatNumber, interpolateText, installInterpolateJsx } from "@jsenv/humanize";
 export { createI18n, formatDatetime, formatDay, formatDayRelative, formatDuration, formatHourDuration, formatMinuteDuration, formatMonth, formatNumber, formatSecondDuration, formatTime, formatTimeOfDay, formatTimeRange, formatTimeRelative, interpolateText } from "@jsenv/humanize";
 import { jsxs, jsx, Fragment } from "preact/jsx-runtime";
@@ -11240,6 +11240,179 @@ const dropGeneratedIdKeys = (state) => {
   return stateWithoutGeneratedIdKeys;
 };
 
+const FRAME_TIMEOUT_MS = 100;
+
+/**
+ * Calls back once the browser has painted what is committed now.
+ *
+ * The callbacks of the next frame run before that frame paints, so the call is
+ * made from a task queued from inside one — the same way preact schedules
+ * useEffect. Unlike an effect, nothing runs this early: preact flushes a
+ * component's pending effects as soon as that component renders again, and a
+ * re-render before the paint is exactly what a caller waiting for the paint
+ * has to survive. A frame not coming at all (a background tab) still answers,
+ * late, through the timeout.
+ *
+ * @param {() => void} callback
+ * @returns {() => void} cancel
+ */
+const afterPaint = (callback) => {
+  let called = false;
+  let timeoutId;
+  let frameId;
+  const onFrame = () => {
+    if (called) {
+      return;
+    }
+    called = true;
+    clearTimeout(timeoutId);
+    cancelAnimationFrame(frameId);
+    timeoutId = setTimeout(callback, 0);
+  };
+  timeoutId = setTimeout(onFrame, FRAME_TIMEOUT_MS);
+  frameId = requestAnimationFrame(onFrame);
+  return () => {
+    called = true;
+    clearTimeout(timeoutId);
+    cancelAnimationFrame(frameId);
+  };
+};
+
+/**
+ * Runs `fn` and commits whatever it re-renders before returning, instead of
+ * letting Preact batch it into the next microtask. Layout effects of what gets
+ * mounted run inside the call too, exactly as they would on any other commit.
+ *
+ * For the caller that has to read the DOM it just asked for — measuring an
+ * element whose content it mounts in the same breath — and cannot wait a tick
+ * to do it, because what comes after is a browser event still in flight
+ * (preventDefault, focus placement) that no longer accepts being answered late.
+ *
+ * `options.debounceRendering` is Preact's own hook for deciding *when* the
+ * render queue drains; swapping it for "right now" for the duration of the call
+ * is exactly how preact/compat implements React's flushSync. Reserve it for the
+ * case above: rendering synchronously in the middle of an event gives up the
+ * batching that makes several state changes one commit.
+ */
+const flushSyncRendering = (fn) => {
+  const debounceRenderingPrevious = options.debounceRendering;
+  options.debounceRendering = (drainRenderQueue) => {
+    drainRenderQueue();
+  };
+  try {
+    fn();
+  } finally {
+    options.debounceRendering = debounceRenderingPrevious;
+  }
+};
+
+/**
+ * The content of a `<Box mount="after-paint">`: built right after the first
+ * frame that shows the box, unless that frame would show it.
+ *
+ * The browser paints nothing until the render that builds a page has ended, and
+ * what lies below the first screen weighs in that render as much as what is on
+ * it. A box marked this way is left empty in that render, then built once the
+ * frame is painted — the page-level twin of a list's render window (see
+ * `renderBudget` in list.jsx), for a page made of sections.
+ *
+ * Which boxes lie below the screen is measured, not taken from the caller. The
+ * caller cannot know: a taller phone, a profile with nothing in its first
+ * section, and the box it marked is on screen. So each box looks where it
+ * stands in the animation callbacks of its first frame — laid out, not yet
+ * painted — and one the frame would show, or one above it, is built there:
+ * content appearing on screen is a pop-in, and content growing ABOVE what is
+ * read pushes it down. Marking too much costs a second render in that frame,
+ * never a wrong picture.
+ *
+ * The document put back where it was read is the other frame that shows it.
+ * That offset is written by navi (see scroll_restoration.js), and written into
+ * a document still missing its bottom it is clamped: the page opens higher than
+ * it was left, and the bottom arrives under a page that has already jumped. So
+ * whoever writes an arrival's offset builds first the boxes that offset shows
+ * (buildDeferredBoxesAbove), in the same task — synchronously, since what comes
+ * right after it (the offset, a route travel measuring its window) reads the
+ * layout.
+ */
+
+const deferredBoxes = new Set();
+const MountAfterPaint = ({
+  boxRef,
+  children
+}) => {
+  const [built, setBuilt] = useState(false);
+  useLayoutEffect(() => {
+    let frame;
+    let cancelAfterPaint;
+    const stopWaiting = () => {
+      deferredBoxes.delete(deferredBox);
+      cancelAnimationFrame(frame);
+      cancelAfterPaint();
+    };
+    // The first of the three that come — the offset of an arrival, the frame
+    // finding the box on screen, the paint — builds it and cancels the others.
+    const deferredBox = {
+      getElement: () => boxRef.current,
+      build: () => {
+        stopWaiting();
+        setBuilt(true);
+      }
+    };
+    deferredBoxes.add(deferredBox);
+    // Requested before afterPaint's own frame callback, so the box is looked at
+    // before that one turns the paint into a build.
+    frame = requestAnimationFrame(() => {
+      const top = readTopInWindow(boxRef.current);
+      if (top !== null && top < window.innerHeight) {
+        deferredBox.build();
+      }
+    });
+    cancelAfterPaint = afterPaint(deferredBox.build);
+    return stopWaiting;
+  }, []);
+  return built ? children : null;
+};
+
+/**
+ * Builds, now, every box still waiting whose top is above `bottom` (in the
+ * document's coordinates): what the document will show once scrolled so that
+ * `bottom` is the bottom of the screen. Boxes built push those below them
+ * further down, so the ones measured above `bottom` are all the ones that can
+ * be shown there, and a few more at worst.
+ *
+ * Renders synchronously, so it must be called outside a Preact commit: a render
+ * flushed from a layout effect runs inside the commit still walking the tree.
+ */
+const buildDeferredBoxesAbove = bottom => {
+  if (deferredBoxes.size === 0) {
+    return;
+  }
+  const toBuild = [];
+  for (const deferredBox of deferredBoxes) {
+    const top = readTopInWindow(deferredBox.getElement());
+    if (top !== null && top + window.scrollY < bottom) {
+      toBuild.push(deferredBox);
+    }
+  }
+  if (toBuild.length === 0) {
+    return;
+  }
+  flushSyncRendering(() => {
+    for (const deferredBox of toBuild) {
+      deferredBox.build();
+    }
+  });
+};
+
+// null for a box nothing draws (a closed popup, a hidden tab): no frame shows
+// it, wherever the document is.
+const readTopInWindow = element => {
+  if (!element || element.getClientRects().length === 0) {
+    return null;
+  }
+  return element.getBoundingClientRect().top;
+};
+
 /**
  * A container has put its page on screen — or as much of it as it can.
  *
@@ -11295,7 +11468,9 @@ const [publishRouteRender, observeRouteRender] = createPubSub();
  * 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
  * back, so a position beyond what has arrived is clamped as before. Only the
- * page knows when it is whole.
+ * page knows when it is whole. What navi itself leaves out of a first render
+ * is the exception — a `<Box mount="after-paint">` — and is built before the
+ * offset that shows it is written (see mount_after_paint.jsx).
  *
  * WHEN a page is arrived at is not decided here either. A document navigation
  * lands where its kind says (see via_history.js), and one scrollport can be
@@ -11444,14 +11619,18 @@ const installScrollRestoration = () => {
   // What a reload asks for, now that the browser has been told not to do it.
   // Once, and at the first render of a route: the position is only meaningful
   // once there is a page under it.
+  // Written once the commit that rendered it has ended: said from inside it,
+  // and what the offset shows may still have to be built (see scrollTo).
   const positionOnLoad = positionByUrl.get(window.location.href);
   if (positionOnLoad && (positionOnLoad.x || positionOnLoad.y)) {
     const stopListening = observeRouteRender(() => {
       stopListening();
-      if (documentHoldCount) {
-        return;
-      }
-      scrollTo(positionOnLoad);
+      queueMicrotask(() => {
+        if (documentHoldCount) {
+          return;
+        }
+        scrollTo(positionOnLoad);
+      });
     });
   }
 };
@@ -11558,14 +11737,25 @@ const forgetScrollersOnArrival = (url, { from } = {}) => {
 // last read. Where this one was read, and its top when it never was — leaving
 // the offset alone would seat the reader wherever the neighbour happened to
 // be, so here "nothing recorded" and "stay" are not the same thing.
+//
+// Called outside a Preact commit only, like scrollTo: a row of tabs measures
+// its window right after, so what the top shows is built first here rather
+// than in the frame (see mount_after_paint.jsx).
 const arriveAtScrollPosition = (url) => {
   if (restoreScrollPosition(url)) {
     return;
   }
+  buildDeferredBoxesAbove(window.innerHeight);
   startAtTop(url);
 };
 
+// What the offset shows is built first: written into a document still missing
+// a deferred box, the offset is clamped (see mount_after_paint.jsx). That build
+// is a render of its own, so this is never called from inside a commit — a
+// caller that learns the page is there from a layout effect (observeRouteRender)
+// writes once that commit has ended.
 const scrollTo = ({ x, y }) => {
+  buildDeferredBoxesAbove(y + window.innerHeight);
   window.scrollTo({ top: y, left: x, behavior: "instant" });
 };
 
@@ -15389,6 +15579,9 @@ const createOpenController = (
     // content is still waiting for a first open to be built. Called below,
     // before openEffect, so the popup measures and positions the real thing.
     mountContent: null,
+    // Set alongside mountContent: the content asked for outside any opening,
+    // by something that reads it while the popup is closed.
+    buildContent: null,
     // The caller's own `onOpen`, set by Dialog/Popover from their props on
     // every render (like openEffect). Called BEFORE mountContent, so whatever
     // it decides — which record this dialog is opening on — is already true by
@@ -30925,6 +31118,7 @@ const PSEUDO_STATE_CHILD_PROP_SET = new Set(["tabIndex", "tabindex"]);
  *   footer?: boolean,
  *   body?: boolean,
  *   sticky?: boolean,
+ *   mount?: "always" | "after-paint",
  *   children?: import("ignore:preact").ComponentChildren,
  *   [key: string]: any,
  * }>}
@@ -30973,6 +31167,16 @@ const PSEUDO_STATE_CHILD_PROP_SET = new Set(["tabIndex", "tabindex"]);
  *   (see docs/interactions.md). A plain box has no wiring of its own: it does
  *   nothing with `action` (that is a control's prop), so a click on it is
  *   declared here like any other interaction: `interactions={{ click: fn }}`.
+ * @param {"always"|"after-paint"} [mount="always"] When `children` are built.
+ *   `"after-paint"` leaves the box empty in the render that first mounts it and
+ *   builds them right after the first frame that shows the page, then keeps
+ *   them: for the sections of a page that lie below its first screen. navi
+ *   measures where the box stands before that frame, and one the frame would
+ *   show (or where the document is put back, on a return) is built before the
+ *   paint all the same. Until built, what is inside is not in the document:
+ *   no id there is found, no named control there is there to hear its own
+ *   `signal` (see docs/control_object.md). Only for content nothing reaches
+ *   before the first frame (see docs/scroll.md).
  */
 const Box = props => {
   const {
@@ -30980,6 +31184,7 @@ const Box = props => {
     children,
     separator,
     interactions,
+    mount,
     ...computeProps
   } = props;
   const parentBoxFlow = useContext(BoxFlowContext);
@@ -31057,6 +31262,12 @@ const Box = props => {
       children: innerChildren
     });
   }
+  if (mount === "after-paint") {
+    innerChildren = jsx(MountAfterPaint, {
+      boxRef: finalRef,
+      children: innerChildren
+    });
+  }
   return jsx(TagName, {
     ref: finalRef,
     className: innerClassName,
@@ -34627,6 +34838,13 @@ const OLD_BAND_TOP_PROPERTY = "--navi-transition-old-band-top";
 const OLD_BAND_RIGHT_PROPERTY = "--navi-transition-old-band-right";
 const OLD_BAND_BOTTOM_PROPERTY = "--navi-transition-old-band-bottom";
 const OLD_BAND_LEFT_PROPERTY = "--navi-transition-old-band-left";
+const VIEWPORT_TOP_PROPERTY = "--navi-transition-viewport-top";
+const VIEWPORT_LEFT_PROPERTY = "--navi-transition-viewport-left";
+// Worn by the root once the group is held at the window by our numbers alone
+// (see placeTransitionWindow): the group rule of each movement is written on
+// it. Read by rules on pseudo-elements only, so wearing it restyles nothing
+// the document inherits.
+const WINDOW_PLACED_ATTRIBUTE = "data-navi-transition-window-placed";
 const WINDOW_PROPERTIES = [
   WINDOW_TOP_PROPERTY,
   WINDOW_LEFT_PROPERTY,
@@ -34640,6 +34858,8 @@ const WINDOW_PROPERTIES = [
   OLD_BAND_RIGHT_PROPERTY,
   OLD_BAND_BOTTOM_PROPERTY,
   OLD_BAND_LEFT_PROPERTY,
+  VIEWPORT_TOP_PROPERTY,
+  VIEWPORT_LEFT_PROPERTY,
 ];
 
 // Whose numbers are currently published. The window belongs to the movement
@@ -34647,6 +34867,8 @@ const WINDOW_PROPERTIES = [
 // after another has replaced it must not wipe numbers the new one is standing
 // on.
 let windowOwner = null;
+// The element the box is captured as, for as long as the window is held.
+let windowElement = null;
 // Stops re-reading the arriving state's corner, when a movement is on.
 let unfollowArrivingState = null;
 
@@ -34702,6 +34924,10 @@ const holdTransitionWindow = (
   const right =
     rectBefore.right > rectAfter.right ? rectBefore.right : rectAfter.right;
   windowOwner = owner;
+  windowElement = element;
+  // Pictures of a movement this one took over from are placed by the browser
+  // until this one's own pictures exist.
+  document.documentElement.removeAttribute(WINDOW_PLACED_ATTRIBUTE);
   setTransitionValue(WINDOW_TOP_PROPERTY, `${top}px`);
   setTransitionValue(WINDOW_LEFT_PROPERTY, `${left}px`);
   setTransitionValue(WINDOW_WIDTH_PROPERTY, `${right - left}px`);
@@ -34726,6 +34952,33 @@ const holdTransitionWindow = (
   });
 };
 
+/**
+ * Called once the pictures exist — the view transition's `ready` — with the
+ * name the box was captured under. Where the viewport's corner stands in the
+ * space the pictures are drawn in is the browser's placement of the group
+ * minus our reading of the same element, both taken in this one instant; the
+ * group is held at the window with it from then on (see the top of the file).
+ * A browser that does not hand the group's placement back leaves the group
+ * where it places it, moved to the window by the arriving corner.
+ */
+const placeTransitionWindow = (owner, groupName) => {
+  if (owner !== windowOwner) {
+    return;
+  }
+  const { transform } = getComputedStyle(
+    document.documentElement,
+    `::view-transition-group(${groupName})`,
+  );
+  if (!transform || transform === "none") {
+    return;
+  }
+  const placement = new DOMMatrixReadOnly(transform);
+  const rect = windowElement.getBoundingClientRect();
+  setTransitionValue(VIEWPORT_TOP_PROPERTY, `${placement.m42 - rect.top}px`);
+  setTransitionValue(VIEWPORT_LEFT_PROPERTY, `${placement.m41 - rect.left}px`);
+  document.documentElement.setAttribute(WINDOW_PLACED_ATTRIBUTE, "");
+};
+
 // The live layout takes the box back. A discontinuity by construction — the
 // window stands at the held height, the box is at its own — and an invisible
 // one: the page arriving is fully in place, and the strip below it that the
@@ -34735,20 +34988,22 @@ const releaseTransitionWindow = (owner) => {
     return;
   }
   windowOwner = null;
+  windowElement = null;
   if (unfollowArrivingState) {
     unfollowArrivingState();
   }
+  document.documentElement.removeAttribute(WINDOW_PLACED_ATTRIBUTE);
   for (const property of WINDOW_PROPERTIES) {
     removeTransitionValue(property);
   }
 };
 
-// The arriving state's corner, re-read every frame — as often as the browser
-// refreshes the group's placement from the same element (see the top of the
-// file) — and with it the offset outside the box, which carries the window
-// and the corner of the state being left along. Requested, never awaited: the
-// first call runs inside the update callback, where a frame cannot come.
-// Written only when it moved: every write restyles the pictures.
+// The arriving state's corner, re-read every frame — as often as anything can
+// move the page arriving (see the top of the file) — and with it the offset
+// outside the box, which carries the window and the corner of the state being
+// left along. Requested, never awaited: the first call runs inside the update
+// callback, where a frame cannot come. Written only when it moved: every write
+// restyles the pictures.
 const followArrivingState = (element, rectAtHold, heldAt) => {
   if (unfollowArrivingState) {
     unfollowArrivingState();
@@ -35253,6 +35508,13 @@ const css$12 = /* css */`@property --navi-route-transition-leave {
     animation-name: none;
   }
 
+  &[data-navi-transition-window-placed]::view-transition-group(navi-route-transition) {
+    top: calc(var(--navi-transition-window-top) + var(--navi-transition-viewport-top));
+    left: calc(var(--navi-transition-window-left) +
+          var(--navi-transition-viewport-left));
+    transform: none;
+  }
+
   &::view-transition-old(navi-route-transition) {
     top: calc(var(--navi-transition-window-old-top) - var(--navi-transition-window-top));
     left: calc(var(--navi-transition-window-old-left) - var(--navi-transition-window-left));
@@ -36300,6 +36562,8 @@ const beginTransition = ({
   // the only place the silent misconfigurations show. They are all about the
   // same thing — a movement playing on pictures that are not the pages.
   const viewTransitionReady = () => {
+    // Read before anything below writes to the document.
+    placeTransitionWindow(transition, AREA_NAME);
     startTransitionFurniture(transition, {
       duration: transition.duration
     });
@@ -36811,6 +37075,13 @@ const css$11 = /* css */`.navi_route_travel {
     animation-duration: var(--navi-route-travel-duration, .3s);
     animation-name: none;
   }
+
+  &[data-navi-transition-window-placed]::view-transition-group(navi-route-travel) {
+    top: calc(var(--navi-transition-window-top) + var(--navi-transition-viewport-top));
+    left: calc(var(--navi-transition-window-left) +
+          var(--navi-transition-viewport-left));
+    transform: none;
+  }
 }
 
 :root[data-navi-route-travel-held] {
@@ -37189,6 +37460,10 @@ const RouteTravel = ({
       });
     });
     travel.viewTransition = viewTransition;
+    // Subscribed first, so it reads before the scrub below writes anything.
+    viewTransition.ready.then(() => {
+      placeTransitionWindow(travel, TRAVEL_NAME);
+    }, ignoreSkipped);
     if (scrub) {
       // Said only now: the release has to have something to let go of, and the
       // transition did not exist a line above.
@@ -37388,16 +37663,20 @@ const RouteTravel = ({
           // what makes the document tall enough to hold that offset again —
           // and the recording stays deaf until then, over the clamp the swap
           // back makes on the way. Its own deafness rather than the travel's:
-          // the travel ends here, and this outlives it by a render.
+          // the travel ends here, and this outlives it by a render. Written
+          // once the commit that says so has ended, as arriveAtScrollPosition
+          // asks.
           const resumeScrollRecording = suspendScrollRecording();
           const stopWatchingRender = observeRouteRender(() => {
             stopWatchingRender();
-            const {
-              route,
-              params
-            } = travel.fromPage;
-            arriveAtScrollPosition(route.buildUrl(params));
-            resumeScrollRecording();
+            queueMicrotask(() => {
+              const {
+                route,
+                params
+              } = travel.fromPage;
+              arriveAtScrollPosition(route.buildUrl(params));
+              resumeScrollRecording();
+            });
           });
         }
         releaseRendering();
@@ -40181,34 +40460,6 @@ registerNaviCommand("--navi-unselect", (source, event) => {
   };
 });
 
-/**
- * Runs `fn` and commits whatever it re-renders before returning, instead of
- * letting Preact batch it into the next microtask. Layout effects of what gets
- * mounted run inside the call too, exactly as they would on any other commit.
- *
- * For the caller that has to read the DOM it just asked for — measuring an
- * element whose content it mounts in the same breath — and cannot wait a tick
- * to do it, because what comes after is a browser event still in flight
- * (preventDefault, focus placement) that no longer accepts being answered late.
- *
- * `options.debounceRendering` is Preact's own hook for deciding *when* the
- * render queue drains; swapping it for "right now" for the duration of the call
- * is exactly how preact/compat implements React's flushSync. Reserve it for the
- * case above: rendering synchronously in the middle of an event gives up the
- * batching that makes several state changes one commit.
- */
-const flushSyncRendering = (fn) => {
-  const debounceRenderingPrevious = options.debounceRendering;
-  options.debounceRendering = (drainRenderQueue) => {
-    drainRenderQueue();
-  };
-  try {
-    fn();
-  } finally {
-    options.debounceRendering = debounceRenderingPrevious;
-  }
-};
-
 /**
  * When a popup builds what it holds, and when it throws it away.
  *
@@ -40243,7 +40494,11 @@ const flushSyncRendering = (fn) => {
  *
  * "always" is for content something else depends on before any opening: a
  * value the popup's owner reads off its own children, fields a form around it
- * collects on submit, a size measured from outside.
+ * collects on submit, a size measured from outside. When the popup's owner
+ * cannot tell at mount whether anything will depend on it, the content waits
+ * and whatever depends on it asks for it, closed, with
+ * `openController.buildContent()` (a picker's drawing reading the value its
+ * popup holds, see usePickerContext).
  *
  * "idle" is "always" minus the cost on the critical render: the page appears
  * without the content, and the browser builds it in an idle moment after
@@ -40370,6 +40625,14 @@ const usePopupContentMount = (
       }
     }
   };
+  // A plain render rather than a flush: the popup stays closed, and nothing is
+  // about to measure it.
+  openController.buildContent = () => {
+    if (contentMountedRef.current) {
+      return;
+    }
+    setContentMounted(true);
+  };
   openController.unmountContent =
     mount === "while-opened"
       ? () => {
@@ -42519,6 +42782,65 @@ const keptOrFirstDefinedChildUIState = (children, fallbackState, kept) => {
   }
   return kept;
 };
+// The same claim, for an object: a key whose control is not there cannot be
+// contradicted by it — a slide not built yet (SlideContainer mount="near"), a
+// row scrolled out, a page parked. A key of `kept` stays until a control of
+// that name, there, says otherwise; a value put ON the group replaces the
+// whole object, which is how a key is dropped on purpose.
+const keptAndNamedChildUIStates = (children, fallbackState, kept) => {
+  const groupValues =
+    kept !== null && typeof kept === "object" && !Array.isArray(kept)
+      ? { ...kept }
+      : {};
+  return Object.assign(
+    groupValues,
+    readNamedChildUIStates(children, { warnNameless: true }),
+  );
+};
+// What the named controls among `children` say, one key each. A nameless
+// GROUP is a grouping, not a value: it exists to hold its children together
+// (a WheelGroup sharing navigation, a fieldset-ish cluster) without claiming a
+// key of its own, so what its controls say is written as if they were here.
+// Naming it is what turns the same group into one key — see ControlGroup's
+// `name`. Only what its CONTROLS say: such a grouping is handed the whole
+// object around it (see distributeChildUIState below) and keeps what they do
+// not answer for, so merged whole it would carry its siblings' keys back up,
+// stale.
+const readNamedChildUIStates = (children, { warnNameless }) => {
+  const values = {};
+  for (const child of children) {
+    const { name, emptyUIState } = child;
+    // A control holding nothing writes its own empty, not a hole: the key is in
+    // the object either way, and what is read from it keeps the shape the
+    // reader was promised (see resolveEmptyUIState).
+    const uiState =
+      child.uiState === undefined && emptyUIState !== undefined
+        ? emptyUIState
+        : child.uiState;
+    if (!name) {
+      if (isNamelessGrouping(child, uiState)) {
+        Object.assign(
+          values,
+          child.keepsUnansweredKeys
+            ? readNamedChildUIStates(child.getChildControllers(), {
+                warnNameless: false,
+              })
+            : uiState,
+        );
+        continue;
+      }
+      if (warnNameless) {
+        console.warn(
+          "A group child is missing a name property, its state won't be included in the group state",
+          child,
+        );
+      }
+      continue;
+    }
+    values[name] = uiState;
+  }
+  return values;
+};
 
 // Default aggregate/distribute implementations keyed by controlType or stateType.
 // Looked up in useUIGroupStateController to fill in omitted aggregateChildStates /
@@ -42588,37 +42910,7 @@ const GROUP_DEFAULTS = {
     childControlFilter: (child) => {
       return child.controlType !== "button" && child.controlType !== "link";
     },
-    aggregateChildStates: (children) => {
-      const groupValues = {};
-      for (const child of children) {
-        const { name, emptyUIState } = child;
-        // A control holding nothing writes its own empty, not a hole: the key
-        // is in the object either way, and what is read from it keeps the shape
-        // the reader was promised (see resolveEmptyUIState).
-        const uiState =
-          child.uiState === undefined && emptyUIState !== undefined
-            ? emptyUIState
-            : child.uiState;
-        if (!name) {
-          // A nameless GROUP is a grouping, not a value: it exists to hold its
-          // children together (a WheelGroup sharing navigation, a fieldset-ish
-          // cluster) without claiming a key of its own, so what it holds is
-          // merged in as if its children had been written here. Naming it is
-          // what turns the same group into one key — see ControlGroup's `name`.
-          if (isNamelessGrouping(child, uiState)) {
-            Object.assign(groupValues, uiState);
-            continue;
-          }
-          console.warn(
-            "A group child is missing a name property, its state won't be included in the group state",
-            child,
-          );
-          continue;
-        }
-        groupValues[name] = uiState;
-      }
-      return groupValues;
-    },
+    aggregateChildStates: keptAndNamedChildUIStates,
     distributeChildUIState: (newUIState, child) => {
       const childName = child.name;
       if (
@@ -42642,7 +42934,8 @@ const GROUP_DEFAULTS = {
         return childUIState;
       }
       // Merged in on the way up (see above), so on the way down it takes the
-      // whole object and picks out its own keys — the same value it produced.
+      // whole object: its controls pick out their own keys, and it keeps the
+      // rest for those of its controls that are not there yet.
       // Only for a child with no name of its own: the same condition the
       // aggregate applies before merging. A NAMED child holding an object (a
       // `type="object"` picker, say) answers for one key, and the object it is
@@ -43130,6 +43423,11 @@ const useUIGroupStateController = (
         // a picker filling its popup, a value prop) rather than worked out from
         // its children. What it protects is read in onChange.
         stateGivenFromAbove: hasValueProp || hasDefaultValueProp,
+        // Its value carries keys none of its controls answers for (see
+        // keptAndNamedChildUIStates): a group merging it as a nameless
+        // grouping reads its controls instead of its value.
+        keepsUnansweredKeys:
+          resolvedAggregateChildStates === keptAndNamedChildUIStates,
         uiStateSignal,
         wantRequesterButtonState,
         ref,
@@ -53731,7 +54029,8 @@ const useExpandableContext = partName => {
  *   other three, intent on the UI part (pointer entering it, focus landing in
  *   it) builds the content ahead of the click; `"while-opened"` content is
  *   built by a press on it only, and thrown away if that press does not
- *   expand it.
+ *   expand it. Named controls in content not built are kept by the group
+ *   around them (docs/control_object.md, "A control that is not there").
  */
 const Expandable = props => {
   import.meta.css = [css$R, "@jsenv/navi/src/control/expandable/expandable.jsx"];
@@ -60822,12 +61121,19 @@ const readArea = slideElement => slideElement.getAttribute("data-slide-area") ||
  *   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
+ *   items 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.
+ *   A slide not built has no controls, and a group around the container keeps
+ *   their keys for them: what it was handed reaches them once built. What is
+ *   shared between slides is written through that group (its `signal`, a
+ *   `--navi-update` aimed at it), never into one control's own `signal`, which
+ *   nobody reads while that control is not built; and nothing validates a
+ *   field before its slide is built. See docs/control_object.md, "A control
+ *   that is not there".
  */
 const SlideContainer = ({
   layout = "row",
@@ -69366,6 +69672,69 @@ const toPopoverAnimation = animation => {
   return animation;
 };
 
+const PickerContext = createContext();
+
+/*
+ * The picker's context, for whatever draws its value. A picker told no value
+ * holds what the control in its popup holds, and builds that popup only when
+ * something reads it (see the mount decision in picker_custom.jsx): what the
+ * picker draws itself it knows about, a drawing given as an element is the
+ * caller's, and says so here by reading. In a layout effect, so the frame that
+ * first shows the drawing already shows the value.
+ */
+const usePickerContext = () => {
+  const context = useContext(PickerContext);
+  const requestValue = context?.requestValue;
+  useLayoutEffect(() => {
+    requestValue?.();
+  }, [requestValue]);
+  return context;
+};
+
+/*
+ * A typed picker (`type="date"`, `type="array"`, …) draws its value with a ui
+ * of navi's own, installed as the very "ui" prop a caller overrides to draw
+ * that value themselves. Marking navi's own tells the two apart afterwards:
+ * an empty value is greyed as a placeholder only when the drawing is navi's —
+ * a caller's ui may well be their way of writing "no filter", which is an
+ * answer, not a blank (see navi-placeholder in picker.jsx).
+ */
+const asPickerOwnUI = PickerUI => {
+  PickerUI.isPickerOwnUI = true;
+  return PickerUI;
+};
+const pickerUIIsNaviOwn = ui => {
+  return Boolean(ui) && typeof ui === "object" && Boolean(ui.type?.isPickerOwnUI);
+};
+
+/**
+ * What the picker holds, read from inside its `ui` — for a drawing given as
+ * an element (`ui={<MyCard game={game} />}`), which the picker cannot hand
+ * props to. `value` is the state the picker holds right now: the answer the
+ * popup just closed on, before the server has said anything, and put back if
+ * the action fails. `loading` is the run in flight; `interactive` is false
+ * while the picker is disabled, read-only or busy.
+ *
+ * @returns {{ value: any, loading: boolean, interactive: boolean } | null}
+ *   null outside a picker.
+ */
+const usePickerState = () => {
+  const context = usePickerContext();
+  if (!context) {
+    return null;
+  }
+  const {
+    value,
+    loading,
+    interactive
+  } = context;
+  return {
+    value,
+    loading,
+    interactive
+  };
+};
+
 installImportMetaCssBuild(import.meta);
 const css$B = /* css */`.navi_picker_callout_dock > [data-picker-content] {
   display: none;
@@ -69593,6 +69962,12 @@ const PickerCustom = props => {
   const idDefault = useId();
   const controlId = useContext(ControlIdContext);
   props.id = props.id || controlId || idDefault;
+  // Given no value, the picker holds what the control in its popup holds (see
+  // the `mount` decision below) — and a group around it collects that from the
+  // moment both exist.
+  const valueInPopup = !isControlValueGivenByProps(props);
+  const parentController = useContext(ParentUIStateControllerContext);
+  const answersToGroup = Boolean(parentController) && !props.standalone;
   // Same narrow-container/maxWidth-compact heuristic Popup itself uses (see
   // popup_mode.jsx's own useResolvedPopupMode) — frozen for the lifetime of an opening
   // (computed when closed, stable while open, so a screen resize mid-session
@@ -69838,12 +70213,20 @@ const PickerCustom = props => {
     const requestInteraction = options => {
       dispatchRequestInteraction(ref.current, options);
     };
+
+    // What a drawing of the caller's calls as it reads the value (see
+    // usePickerContext): the popup holding it, built while closed. Only when
+    // `mount` is left to the picker — a caller who set it has said when.
+    const requestValue = useStableCallback(() => {
+      openController.buildContent();
+    });
     const {
       onActionStart,
       children,
       uiAction: uiActionProp
     } = props;
     Object.assign(pickerProps, {
+      "requestValue": valueInPopup && props.mount === undefined ? requestValue : undefined,
       "aria-expanded": Boolean(expanded),
       "onActionStart": e => {
         onActionStart?.(e);
@@ -69882,13 +70265,12 @@ const PickerCustom = props => {
       anchor: props.anchor || props.ref,
       openController,
       // A picker whose value was never given to it reads it off the control in
-      // its popup (see useUIFacadeStateController): the trigger shows what the
-      // list inside says is selected, so that list has to exist before anyone
-      // opens anything. Told a value — even an empty one — the picker owns it
-      // and pushes it down instead, leaving the popup free to build its
-      // content only when it is first opened (see popup_content_mount.js).
-      // A caller who knows better says so with the popup's own props.
-      mount: props.mount ?? (isControlValueGivenByProps(props) ? MOUNT_DEFAULT : "always"),
+      // its popup (see useUIFacadeStateController), so that control is built as
+      // soon as something reads the value: at mount when the picker sees the
+      // reader, otherwise when a drawing of the caller's asks (requestValue
+      // above). Told a value — even an empty one — the picker pushes it down,
+      // and the popup waits for its first open (see popup_content_mount.js).
+      mount: props.mount ?? (valueInPopup && isPickerValueReadAtMount(props, answersToGroup) ? "always" : MOUNT_DEFAULT),
       // Not on pickerProps (the trigger): commands.js's own
       // resolveClosestExpandable() does `el.closest("[aria-expanded]")` to
       // find where to dispatch navi_request_open/navi_request_close — and
@@ -70176,6 +70558,29 @@ const PickerCustom = props => {
   });
 };
 
+// Whether something reads a picker's value before its popup has opened, as
+// far as the picker sees from its own props: the drawing navi renders for it
+// (its own, or the typed one PickerTypeResolver installs — `ui` is still unset
+// here), one of navi's Picker.UI.*, a component handed `value`, the clear
+// cross, a form submitting it by name, a group it answers to. A headless
+// picker draws nothing, and an element `ui` is the caller's: it reads through
+// usePickerContext, which asks for the value then.
+const isPickerValueReadAtMount = (props, answersToGroup) => {
+  if (props.name !== undefined || answersToGroup) {
+    return true;
+  }
+  if (props.variant === "headless") {
+    return false;
+  }
+  if (props.clearable) {
+    return true;
+  }
+  const {
+    ui
+  } = props;
+  return ui === undefined || typeof ui === "function" || pickerUIIsNaviOwn(ui);
+};
+
 // A hold declared on something AROUND the picker (a card opened by
 // `openOn="longpress"`, holding this one in its drawing): the finger going
 // down may be the start of that hold, so this picker opens on the click — which
@@ -70691,52 +71096,6 @@ const PickerConfirmBody = ({
   });
 };
 
-const PickerContext = createContext();
-
-/*
- * A typed picker (`type="date"`, `type="array"`, …) draws its value with a ui
- * of navi's own, installed as the very "ui" prop a caller overrides to draw
- * that value themselves. Marking navi's own tells the two apart afterwards:
- * an empty value is greyed as a placeholder only when the drawing is navi's —
- * a caller's ui may well be their way of writing "no filter", which is an
- * answer, not a blank (see navi-placeholder in picker.jsx).
- */
-const asPickerOwnUI = PickerUI => {
-  PickerUI.isPickerOwnUI = true;
-  return PickerUI;
-};
-const pickerUIIsNaviOwn = ui => {
-  return Boolean(ui) && typeof ui === "object" && Boolean(ui.type?.isPickerOwnUI);
-};
-
-/**
- * What the picker holds, read from inside its `ui` — for a drawing given as
- * an element (`ui={<MyCard game={game} />}`), which the picker cannot hand
- * props to. `value` is the state the picker holds right now: the answer the
- * popup just closed on, before the server has said anything, and put back if
- * the action fails. `loading` is the run in flight; `interactive` is false
- * while the picker is disabled, read-only or busy.
- *
- * @returns {{ value: any, loading: boolean, interactive: boolean } | null}
- *   null outside a picker.
- */
-const usePickerState = () => {
-  const context = useContext(PickerContext);
-  if (!context) {
-    return null;
-  }
-  const {
-    value,
-    loading,
-    interactive
-  } = context;
-  return {
-    value,
-    loading,
-    interactive
-  };
-};
-
 const PickerNaviMinute = props => {
   const Next = useNextResolver();
   const {
@@ -70858,44 +71217,6 @@ document.addEventListener(
   { capture: true, passive: true },
 );
 
-const FRAME_TIMEOUT_MS = 100;
-
-/**
- * Calls back once the browser has painted what is committed now.
- *
- * The callbacks of the next frame run before that frame paints, so the call is
- * made from a task queued from inside one — the same way preact schedules
- * useEffect. Unlike an effect, nothing runs this early: preact flushes a
- * component's pending effects as soon as that component renders again, and a
- * re-render before the paint is exactly what a caller waiting for the paint
- * has to survive. A frame not coming at all (a background tab) still answers,
- * late, through the timeout.
- *
- * @param {() => void} callback
- * @returns {() => void} cancel
- */
-const afterPaint = (callback) => {
-  let called = false;
-  let timeoutId;
-  let frameId;
-  const onFrame = () => {
-    if (called) {
-      return;
-    }
-    called = true;
-    clearTimeout(timeoutId);
-    cancelAnimationFrame(frameId);
-    timeoutId = setTimeout(callback, 0);
-  };
-  timeoutId = setTimeout(onFrame, FRAME_TIMEOUT_MS);
-  frameId = requestAnimationFrame(onFrame);
-  return () => {
-    called = true;
-    clearTimeout(timeoutId);
-    cancelAnimationFrame(frameId);
-  };
-};
-
 const LoadingDotsSvg = () => {
   return jsxs("svg", {
     viewBox: "0 0 200 200",
@@ -79253,7 +79574,7 @@ const PickerObjectUI = /*#__PURE__*/asPickerOwnUI(() => {
   const {
     value,
     placeholder
-  } = useContext(PickerContext);
+  } = usePickerContext();
   if (uiStateHoldsNothing(value)) {
     if (!placeholder) {
       return null;
@@ -79289,7 +79610,7 @@ const PickerArrayUI = /*#__PURE__*/asPickerOwnUI(() => {
     value,
     placeholder,
     maxLines
-  } = useContext(PickerContext);
+  } = usePickerContext();
   if (uiStateHoldsNothing(value)) {
     if (!placeholder) {
       return null;
@@ -79371,7 +79692,7 @@ const PickerColorUI = /*#__PURE__*/asPickerOwnUI(() => {
   const {
     value,
     placeholder
-  } = useContext(PickerContext);
+  } = usePickerContext();
   if (!value) {
     if (!placeholder) {
       return jsx(Color, {});
@@ -79395,7 +79716,7 @@ const PickerDateUI = /*#__PURE__*/asPickerOwnUI(props => {
   const {
     value,
     placeholder
-  } = useContext(PickerContext);
+  } = usePickerContext();
   if (!value) {
     if (!placeholder) {
       return jsx(Time, {
@@ -79427,7 +79748,7 @@ const PickerMonthUI = /*#__PURE__*/asPickerOwnUI(props => {
   const {
     value,
     placeholder
-  } = useContext(PickerContext);
+  } = usePickerContext();
   if (!value) {
     if (!placeholder) {
       return jsx(Time, {
@@ -79458,7 +79779,7 @@ const PickerWeekUI = /*#__PURE__*/asPickerOwnUI(props => {
   const {
     value,
     placeholder
-  } = useContext(PickerContext);
+  } = usePickerContext();
   if (!value) {
     if (!placeholder) {
       return jsx(Time, {
@@ -79489,7 +79810,7 @@ const PickerTimeUI = /*#__PURE__*/asPickerOwnUI(props => {
   const {
     value,
     placeholder
-  } = useContext(PickerContext);
+  } = usePickerContext();
   if (!value) {
     if (!placeholder) {
       return jsx(Time, {
@@ -79520,7 +79841,7 @@ const PickerDurationUI = /*#__PURE__*/asPickerOwnUI(props => {
   const {
     value,
     placeholder
-  } = useContext(PickerContext);
+  } = usePickerContext();
   if (!value) {
     if (!placeholder) {
       return jsx(Time, {
@@ -79550,7 +79871,7 @@ const PickerDatetimeUI = /*#__PURE__*/asPickerOwnUI(props => {
   const {
     value,
     placeholder
-  } = useContext(PickerContext);
+  } = usePickerContext();
   if (!value) {
     if (!placeholder) {
       return jsx(Time, {
@@ -79579,7 +79900,7 @@ const PickerFileUI = /*#__PURE__*/asPickerOwnUI(() => {
   const {
     value,
     placeholder
-  } = useContext(PickerContext);
+  } = usePickerContext();
   if (!value) {
     if (!placeholder) {
       return null;
@@ -80115,7 +80436,11 @@ const PickerButton = props => {
     // a piece of, waiting as a whole (see the `loadingOutline` doc).
     loadingOutline,
     // Where the outline runs, in px from the picker's box: negative is outside.
-    loadingOutlineInset = -2
+    loadingOutlineInset = -2,
+    // Builds the popup this picker's value is read from, for a drawing that
+    // reads it (see usePickerContext). Set by PickerCustom, only while that
+    // value lives in the popup.
+    requestValue
   } = props;
   // A word in a sentence is never truncated — and the clamp's overflow: hidden
   // would cut its dotted underline, which sits on the edge of the line box
@@ -80213,7 +80538,8 @@ const PickerButton = props => {
     id: inputProps.id,
     interactive,
     loading,
-    clearConfirm
+    clearConfirm,
+    requestValue
   };
   return (
     /* Read-only crosses into everything the picker is made of: what it really
@@ -80264,7 +80590,8 @@ const PickerButton = props => {
         error: undefined,
         dayLabel: undefined,
         loadingOutline: undefined,
-        loadingOutlineInset: undefined
+        loadingOutlineInset: undefined,
+        requestValue: undefined
         // This wrapper will receive keyboard event bubbling from the picker popup content
         // we re-dispatch on the input (to get escape to close for instance)
         ,
@@ -80478,7 +80805,7 @@ const PickerClear = ({
   children,
   ...rest
 }) => {
-  const pickerContext = useContext(PickerContext);
+  const pickerContext = usePickerContext();
   if (!pickerContext) {
     warnOnClearOutsidePicker();
     return null;
@@ -80762,7 +81089,7 @@ const PickerDefaultUI = () => {
   const {
     value,
     placeholder
-  } = useContext(PickerContext);
+  } = usePickerContext();
   if (!value) {
     if (!placeholder) {
       return null;
@@ -81336,10 +81663,13 @@ const PickerFirstResolver = props => {
  * @param {string} [cancelTestId]
  * @param {"always"|"idle"|"from-first-open"|"while-opened"} [mount] The popup's own
  *   (see Popup): when the children are built and thrown away. Left out, a
- *   picker told no value builds them right away (`"always"`) — it reads its
- *   value off the control they hold — and one told a value waits for the first
- *   open. A `type="confirm"` picker never builds them early: its popup is a
- *   question, there is nothing to read.
+ *   picker told no value holds what the control they hold holds, and builds
+ *   them as soon as that value is read: right away (`"always"`) when navi draws
+ *   it (no `ui`, a `Picker.UI.*`, a component `ui`), when there is a clear
+ *   cross, or when a form or group around the picker collects it; when an
+ *   element `ui` calls `usePickerState()`. Read by nothing, it waits for the
+ *   first open, like a picker told a value. A `type="confirm"` picker never
+ *   builds them early: its popup is a question, there is nothing to read.
  */
 // Every picker type is resolved into one of these before it gets here (see
 // PickerTypeResolver and resolveInputProps): a native input type, or navi_js