@jsenv/navi 0.29.423 → 0.29.425

package/dist/dev/jsenv_navi.js

@@ -15389,6 +15389,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
@@ -40243,7 +40246,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 +40377,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"
       ? () => {
@@ -60814,6 +60829,20 @@ const readArea = slideElement => slideElement.getAttribute("data-slide-area") ||
  *   `sizing={loading ? "largest" : "frozen"}` and is measured once the real
  *   content is there. The freeze holds against what happens INSIDE the box, not
  *   against the room it is given: a window resize measures again.
+ * @param {"always"|"near"} [props.mount="always"] - when a slide's CONTENT is
+ *   rendered. The <Slide> element always is, so areas, tabs following the box
+ *   and `aria-labelledby` are the same either way. "always": every slide's,
+ *   from the start. "near": once a travel can show it — the slide on screen,
+ *   the one a travel is going to, and at rest the ones a hand dragging the box
+ *   would bring alongside (neighbours on the map, along the axes
+ *   `travelByDrag` opens, the other end of a `loop` included) — and kept from
+ *   then on. For slides that are costly to build (a grid of a few hundred
+ *   controls each): opening builds the slide shown and its neighbours rather
+ *   than all of them, and a jump to a far slide builds that one and none of
+ *   those in between, which a travel never shows. The box is then as large as
+ *   the largest slide BUILT so far (see `sizing`), so it grows as a larger one
+ *   is reached: give it a size of its own when the slides differ.
+ *   `<Slide mount>` says it for one slide — a heavy one among light ones.
  */
 const SlideContainer = ({
   layout = "row",
@@ -60829,6 +60858,7 @@ const SlideContainer = ({
   travelByScroll = "x",
   duration = "300ms",
   sizing = "largest",
+  mount = "always",
   children,
   ...rest
 }) => {
@@ -60948,6 +60978,15 @@ const SlideContainer = ({
   // Undefined at mount on purpose: the first area held outside is news like any
   // other, and it is walked to rather than opened on.
   const areaAskedSeenRef = useRef(undefined);
+  // An area held outside that this container has not answered yet: the effect
+  // reading currentFromCaller walks to it, after the render that brings it.
+  const requestIsNews = () => currentFromCaller !== undefined && currentFromCaller !== areaAskedSeenRef.current;
+  // The slide about to be on screen, as far as a render can tell: the area
+  // asked from outside while it is news — the picture is walked there before
+  // it is painted, the first request included — and the container's own answer
+  // otherwise. What a slide waiting for a travel reads to have its content in
+  // the very render that shows it (see Slide's `mount`).
+  const areaShownNext = requestIsNews() ? currentFromCaller : current;
   // Where the container stands, said where the caller holds it.
   //
   // Whether a slide is a place one came from is the STATE's own business (see
@@ -61002,6 +61041,22 @@ const SlideContainer = ({
   // state: nothing on screen depends on it, and a travel must read what the
   // one before it wrote, not what the last render saw.
   const cameFromRef = useRef({});
+  // The slides a travel has come near while their content was not rendered
+  // (mount="near", see renderNear): only ever grows, and only for a slide that
+  // was waiting — a container whose slides all render never re-renders for it.
+  const [nearAreas, setNearAreas] = useState([]);
+  // Nothing names the slide on screen (no area held outside, no default): it
+  // is the first one in the DOM, which the first render cannot read yet. The
+  // first Slide to render is that one, so it claims it — the slide on screen
+  // then has its content from the first commit (a size frozen at mount, a
+  // focus landing in it) rather than one render late.
+  const openingClaimRef = useRef(null);
+  const claimOpening = area => {
+    if (openingClaimRef.current === null) {
+      openingClaimRef.current = area;
+    }
+    return openingClaimRef.current === area;
+  };
 
   // The controller has caught up with the slide the container went to on its
   // own (commit="rest"): there are no longer two answers to give, so the
@@ -61142,6 +61197,44 @@ const SlideContainer = ({
     }
   };
 
+  // The slides a hand dragging the box from this area would bring alongside:
+  // the map's neighbours on the axes it drags, read the way the drag reads them
+  // (areaTowards knows the holes and a loop's two ends).
+  const areasAlongside = area => {
+    const alongside = [];
+    if (dragAxes?.includes("x")) {
+      alongside.push(areaTowards(-1, 0, area), areaTowards(1, 0, area));
+    }
+    if (dragAxes?.includes("y")) {
+      alongside.push(areaTowards(0, -1, area), areaTowards(0, 1, area));
+    }
+    return alongside;
+  };
+
+  // mount="near": the content of a slide is asked for before a travel shows
+  // it. The neighbours are asked for AT REST, never when a travel sets off: the
+  // travel shows the slide it goes to and nothing past it, and a slide built in
+  // the render that starts it is a frame the travel waits for. At rest nothing
+  // moves, and a hand landing next is still answered after the build.
+  const renderNear = (area, {
+    alongside
+  }) => {
+    // Asked on every render: a container with nothing waiting stops here.
+    if (!trackRef.current?.querySelector(":scope > [data-slide-unrendered]")) {
+      return;
+    }
+    const unrendered = readMap().slideElements.filter(slideElement => slideElement.hasAttribute("data-slide-unrendered")).map(readArea);
+    const near = alongside ? [area, ...areasAlongside(area)] : [area];
+    const toRender = near.filter(nearArea => unrendered.includes(nearArea));
+    if (!toRender.length) {
+      return;
+    }
+    setNearAreas(previous => {
+      const added = toRender.filter(nearArea => !previous.includes(nearArea));
+      return added.length ? [...previous, ...added] : previous;
+    });
+  };
+
   // The travel is over: the stage is struck and every slide goes back where the
   // map says it is. Nothing is seen moving for it — the slide on screen sits at
   // the same place whatever the arrangement (its own offset and the track's are
@@ -61190,6 +61283,9 @@ const SlideContainer = ({
     const offset = `${-x * 100}% ${-y * 100}%`;
     offsetRef.current = offset;
     track.style.setProperty("--slide-container-offset", offset);
+    renderNear(currentArea, {
+      alongside: true
+    });
     // Arrived, so the change can be told (commit="rest"): the picture is at
     // rest and whatever the caller does with it — write the URL, ask a server —
     // costs the gesture nothing anymore.
@@ -61467,6 +61563,15 @@ const SlideContainer = ({
     if (!stageRef.current) {
       drawnAreaRef.current = currentArea;
     }
+    // What a travel can show next (mount="near"), around where the picture
+    // SETTLES: a request from outside is walked to by an effect running after
+    // this one, in the same commit, and the slides around a picture about to be
+    // walked away from would be built for nothing. The neighbours only at
+    // rest, see renderNear.
+    const settlingArea = requestIsNews() && reachableTowards(currentArea, currentFromCaller) || currentArea;
+    renderNear(settlingArea, {
+      alongside: !stageRef.current
+    });
     // Said last, and after data-current has been written: what a travel would do
     // is read off the map from the slide that is now current, and off the locks
     // that slide is wearing in this very commit.
@@ -61704,12 +61809,9 @@ const SlideContainer = ({
   // request later), and what nothing has answered yet must still be answered
   // once it can be.
   useLayoutEffect(() => {
-    if (currentFromCaller === undefined) {
-      return;
-    }
-    if (currentFromCaller === areaAskedSeenRef.current) {
-      // Not news: either nothing moved, or this container is reading back what
-      // it wrote itself.
+    if (!requestIsNews()) {
+      // Not news: nothing held outside, nothing moved, or this container
+      // reading back what it wrote itself.
       return;
     }
     // The slide asked for is not rendered yet — no slides at all, or one whose
@@ -62539,6 +62641,11 @@ const SlideContainer = ({
         if (!past) {
           return false;
         }
+        // Two slides from the one at rest, so possibly never rendered: asked
+        // for now, and built before the frame that brings it in is painted.
+        renderNear(past, {
+          alongside: false
+        });
         const currentElement = slideElements.find(slideElement => slideElement.hasAttribute("data-current")) || slideElements[0];
         const basePlace = stageRef.current?.placeByArea.get(reached) || placeOf.get(reached) || {
           x: 0,
@@ -62997,6 +63104,12 @@ const SlideContainer = ({
             done,
             valueByArea,
             settleFocus,
+            // What a slide reads to know whether its content is rendered yet
+            // (see Slide's `mount`).
+            mount,
+            areaShownNext,
+            nearAreas,
+            claimOpening: areaShownNext === undefined ? claimOpening : null,
             // The box itself, for what is written INSIDE it to read the same
             // facts what is written outside reads by id (useSlideContainer):
             // a way out is a way out on either side of the box.
@@ -63053,9 +63166,12 @@ const warnOnNonStringArea = area => {
  *   try to leave.
  * @param {boolean} [props.preventNavNext] - hold them from going right or down.
  * @param {boolean} [props.preventNavPrevious] - …left or up.
+ * @param {"always"|"near"} [props.mount] - when this slide's content is
+ *   rendered; the container's `mount` when not said (see there).
  */
 const Slide = ({
   area,
+  mount,
   required,
   preventNav,
   preventNavNext = preventNav,
@@ -63068,6 +63184,17 @@ const Slide = ({
   {
     warnOnNonStringArea(slideArea);
   }
+  // Asked by every slide, whatever its own mode: the claim goes to the first
+  // slide to RENDER, and a slide that skipped asking would hand it to the one
+  // after it.
+  const opening = container?.claimOpening?.(slideArea);
+  // Kept once rendered (mount="near"): going back builds nothing again, and a
+  // slide being left keeps its content for as long as it is still in the frame.
+  const renderedRef = useRef(false);
+  if (!renderedRef.current && (!container || (mount ?? container.mount) !== "near" || opening || slideArea === container.areaShownNext || container.nearAreas.includes(slideArea))) {
+    renderedRef.current = true;
+  }
+  const rendered = renderedRef.current;
   const answered = Boolean(container?.answeredAreas.includes(slideArea));
   const holdsUntilAnswered = Boolean(required) && !answered;
   const nextIsLocked = Boolean(preventNavNext) || holdsUntilAnswered;
@@ -63117,13 +63244,17 @@ const Slide = ({
         "data-slide-area": slideArea,
         "data-prevent-nav-next": nextIsLocked ? "" : undefined,
         "data-prevent-nav-previous": preventNavPrevious ? "" : undefined
+        // What the container reads to know a slide is waiting for a travel
+        // to come near (see renderNear).
+        ,
+        "data-slide-unrendered": rendered ? undefined : ""
         // A surface one interacts with says what state it is in, the way every
         // other surface does — a dialog carries the very same set.
         // :focus-within is the one a slide is really about: it is what tells
         // the slide holding the keyboard from the ones waiting.
         ,
         pseudoClasses: SLIDE_PSEUDO_CLASSES,
-        children: children
+        children: rendered ? children : null
       })
     })
   });
@@ -69250,6 +69381,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;
@@ -69477,6 +69671,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
@@ -69722,12 +69922,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);
@@ -69766,13 +69974,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
@@ -70060,6 +70267,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
@@ -70575,52 +70805,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 {
@@ -79137,7 +79321,7 @@ const PickerObjectUI = /*#__PURE__*/asPickerOwnUI(() => {
   const {
     value,
     placeholder
-  } = useContext(PickerContext);
+  } = usePickerContext();
   if (uiStateHoldsNothing(value)) {
     if (!placeholder) {
       return null;
@@ -79173,7 +79357,7 @@ const PickerArrayUI = /*#__PURE__*/asPickerOwnUI(() => {
     value,
     placeholder,
     maxLines
-  } = useContext(PickerContext);
+  } = usePickerContext();
   if (uiStateHoldsNothing(value)) {
     if (!placeholder) {
       return null;
@@ -79255,7 +79439,7 @@ const PickerColorUI = /*#__PURE__*/asPickerOwnUI(() => {
   const {
     value,
     placeholder
-  } = useContext(PickerContext);
+  } = usePickerContext();
   if (!value) {
     if (!placeholder) {
       return jsx(Color, {});
@@ -79279,7 +79463,7 @@ const PickerDateUI = /*#__PURE__*/asPickerOwnUI(props => {
   const {
     value,
     placeholder
-  } = useContext(PickerContext);
+  } = usePickerContext();
   if (!value) {
     if (!placeholder) {
       return jsx(Time, {
@@ -79311,7 +79495,7 @@ const PickerMonthUI = /*#__PURE__*/asPickerOwnUI(props => {
   const {
     value,
     placeholder
-  } = useContext(PickerContext);
+  } = usePickerContext();
   if (!value) {
     if (!placeholder) {
       return jsx(Time, {
@@ -79342,7 +79526,7 @@ const PickerWeekUI = /*#__PURE__*/asPickerOwnUI(props => {
   const {
     value,
     placeholder
-  } = useContext(PickerContext);
+  } = usePickerContext();
   if (!value) {
     if (!placeholder) {
       return jsx(Time, {
@@ -79373,7 +79557,7 @@ const PickerTimeUI = /*#__PURE__*/asPickerOwnUI(props => {
   const {
     value,
     placeholder
-  } = useContext(PickerContext);
+  } = usePickerContext();
   if (!value) {
     if (!placeholder) {
       return jsx(Time, {
@@ -79404,7 +79588,7 @@ const PickerDurationUI = /*#__PURE__*/asPickerOwnUI(props => {
   const {
     value,
     placeholder
-  } = useContext(PickerContext);
+  } = usePickerContext();
   if (!value) {
     if (!placeholder) {
       return jsx(Time, {
@@ -79434,7 +79618,7 @@ const PickerDatetimeUI = /*#__PURE__*/asPickerOwnUI(props => {
   const {
     value,
     placeholder
-  } = useContext(PickerContext);
+  } = usePickerContext();
   if (!value) {
     if (!placeholder) {
       return jsx(Time, {
@@ -79463,7 +79647,7 @@ const PickerFileUI = /*#__PURE__*/asPickerOwnUI(() => {
   const {
     value,
     placeholder
-  } = useContext(PickerContext);
+  } = usePickerContext();
   if (!value) {
     if (!placeholder) {
       return null;
@@ -79999,7 +80183,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
@@ -80097,7 +80285,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
@@ -80148,7 +80337,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)
         ,
@@ -80362,7 +80552,7 @@ const PickerClear = ({
   children,
   ...rest
 }) => {
-  const pickerContext = useContext(PickerContext);
+  const pickerContext = usePickerContext();
   if (!pickerContext) {
     warnOnClearOutsidePicker();
     return null;
@@ -80646,7 +80836,7 @@ const PickerDefaultUI = () => {
   const {
     value,
     placeholder
-  } = useContext(PickerContext);
+  } = usePickerContext();
   if (!value) {
     if (!placeholder) {
       return null;
@@ -81220,10 +81410,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