work

Author: dmail

packages/frontend/navi/dist/jsenv_navi.js

@@ -479,7 +479,7 @@ holds; only its mechanisms change.
 | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
 | two routes, `/new` and `/:id/edit`                    | one dialog, two modes — hence the value it is opened ON ([popup_open.md](./popup_open.md#opening-it-on-something)) |
 | the draft lives in the `searchParams`                 | it lives in the dialog, and dies with it                                                                           |
-| cancelling = leaving the screen, which is thrown away | `unmountWhenClosed` (+ a `key` on the form), same effect                                                           |
+| cancelling = leaving the screen, which is thrown away | `mount="while-opened"` (+ a `key` on the form), same effect                                                        |
 | `RouteTravel` between the two screens                 | nothing: a dialog has no neighbour                                                                                 |
 | `onLoad` + `pristineKey`: the resource arrives after  | it is already in hand — the dialog is opened FROM the list                                                         |
 

packages/frontend/navi/dist/jsenv_navi.js.map

@@ -169,7 +169,7 @@ which one — so the press says it, with its own value:
 
 <Dialog
   id="radar-dialog"
-  unmountWhenClosed
+  mount="while-opened"
   onOpen={(e) => {
     editedRadarIdSignal.value = e.detail.value; // undefined = création
   }}
@@ -200,7 +200,7 @@ The order is the whole point, and it is a guarantee, not a coincidence:
 
 ```
 onOpen(openEvent)   ← the subject is decided here
-children mounted    ← unmountWhenClosed rebuilds them from scratch, on that subject
+children mounted    ← mount="while-opened" rebuilds them from scratch, on that subject
 positioned, shown
 ```
 
@@ -221,7 +221,7 @@ knowing why:
 `onnavi_command` receives the whole command string and its value, but it runs
 **after** the opening: whatever it writes lands on a popup that is already open.
 That works only as long as nothing has read the state yet — which
-`unmountWhenClosed` makes a real race rather than a theoretical one.
+`mount="while-opened"` makes a real race rather than a theoretical one.
 
 A `navi_request_open` listener added on the element is the request itself, ahead
 of the popup acting on it — but it is ordered against the popup's own handler by
@@ -609,23 +609,28 @@ A closed popup builds nothing: `children` are mounted on the first open, and
 stay mounted afterwards — a reopened popup finds its scroll position and its
 half-typed form where it left them.
 
-Two props move that line:
+"Closed" is two states, not one — never opened yet, and closed again after an
+opening — so the `mount` prop answers both at once:
 
-| prop                | effect                                                                                                                                                                   |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `mountWhenClosed`   | build `children` right away — for content something depends on before any opening (a value read off it, fields a surrounding form submits, a size measured from outside) |
-| `unmountWhenClosed` | throw `children` away once the popup has finished closing — for content whose fresh state is its initial state                                                           |
+| `mount`                       | before the first open | after a close |
+| ----------------------------- | --------------------- | ------------- |
+| `"always"`                    | mounted               | mounted       |
+| `"from-first-open"` (default) | not mounted           | mounted       |
+| `"while-opened"`              | not mounted           | not mounted   |
 
-`unmountWhenClosed` is what an uncontrolled field seeded from a `defaultValue`
+`"always"` is for content something depends on before any opening: a value read
+off it, fields a surrounding form submits, a size measured from outside.
+
+`"while-opened"` is what an uncontrolled field seeded from a `defaultValue`
 needs: without it, a popup reopened after the underlying value changed still
 shows what it showed at closing time.
 
 ```jsx
-<Dialog ref={dialogRef} unmountWhenClosed>
+<Dialog ref={dialogRef} mount="while-opened">
   <Textarea defaultValue={note.text} />
 </Dialog>
 ```
 
 The content is dropped only once the exit transition is over, so the popup never
 plays it on a blank surface; a popup reopened while it was leaving keeps the
-content that opening just asked for. `mountWhenClosed` wins if both are set.
+content that opening just asked for.

packages/frontend/navi/docs/create_and_edit.md

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.149",
+  "version": "0.29.150",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {

packages/frontend/navi/docs/popup_open.md

@@ -298,16 +298,16 @@
               </Expandable>
             </div>
             <div className="demo-box">
-              <p className="demo-caption">mountWhenClosed</p>
-              <Expandable ui="Summary" mountWhenClosed animation>
+              <p className="demo-caption">mount="always"</p>
+              <Expandable ui="Summary" mount="always" animation>
                 <div className="demo-content">
                   <MountClock />
                 </div>
               </Expandable>
             </div>
             <div className="demo-box">
-              <p className="demo-caption">unmountWhenClosed</p>
-              <Expandable ui="Summary" unmountWhenClosed animation>
+              <p className="demo-caption">mount="while-opened"</p>
+              <Expandable ui="Summary" mount="while-opened" animation>
                 <div className="demo-content">
                   <MountClock />
                 </div>
@@ -681,10 +681,10 @@
             </div>
             <div className="demo-box">
               <p className="demo-caption">
-                mountWhenClosed: the closed content sizes the height — last
+                mount="always": the closed content sizes the height — last
                 resort, the content may be expensive to render
               </p>
-              <Expandable layout="column" animation mountWhenClosed>
+              <Expandable layout="column" animation mount="always">
                 <Expandable.UI style="background: #eceff1; padding: 4px">
                   More
                 </Expandable.UI>

packages/frontend/navi/package.json

@@ -38,10 +38,9 @@
  *   events.
  *
  * Content is not built until the first expansion and stays built afterwards —
- * same policy, same prop names as popups (see popup_content_mount.js):
- * `mountWhenClosed` builds it right away, `unmountWhenClosed` throws it away
- * once the collapse settles (so a closing animation still plays on real
- * content).
+ * same policy, same `mount` prop as popups (see popup_content_mount.js):
+ * `"always"` builds it right away, `"while-opened"` throws it away once the
+ * collapse settles (so a closing animation still plays on real content).
  *
  * The animation is a REVEAL, not a resize: the expandable's own footprint
  * grows/shrinks progressively (the content's grid track interpolates
@@ -73,6 +72,7 @@ import { ActionRenderer } from "../../action/action_renderer.jsx";
 import { useAction } from "../../action/use_action.js";
 import { useActionStatus } from "../../action/use_action_status.js";
 import { Box } from "../../box/box.jsx";
+import { MOUNT_DEFAULT } from "../../layout/popup_content_mount.js";
 import { whenTransitionSettles } from "../../layout/popup_shared.js";
 import { onNaviCommand } from "../commands.js";
 import { warnSignalCollision } from "../control_value.js";
@@ -187,7 +187,7 @@ const css = /* css */ `
         grid-template-columns: 1fr;
         grid-template-rows: 1fr;
       }
-      /* mountWhenClosed: the content is built and width-frozen while closed
+      /* mount="always": the content is built and width-frozen while closed
          (see the component), so it can size the height at all times — the
          expandable then keeps one stable height and only the width reveals. */
       &[data-closed-content-sized] > .navi_expandable_content_container {
@@ -260,8 +260,7 @@ const useExpandableContext = (partName) => {
  *   layout?: "row" | "column",
  *   autoFocus?: boolean,
  *   maxContentHeight?: string | number,
- *   mountWhenClosed?: boolean,
- *   unmountWhenClosed?: boolean,
+ *   mount?: "always" | "from-first-open" | "while-opened",
  *   arrowKeyShortcuts?: boolean,
  *   openKeyShortcut?: string,
  *   closeKeyShortcut?: string,
@@ -298,13 +297,15 @@ const useExpandableContext = (partName) => {
  *   the UI part (it would otherwise be lost to the closed, inert content).
  * @param maxContentHeight - Caps the content height; taller content scrolls
  *   inside the expandable instead of growing it.
- * @param mountWhenClosed - Builds the content right away instead of on first
- *   expansion. In layout="column" it also gives the closed expandable its
- *   content's height (the content is kept laid out at its open width), so
- *   opening only reveals the width instead of changing the height too.
- * @param unmountWhenClosed - Throws the content away once the collapse
- *   settles — after the closing animation, so it still plays on real content —
- *   and rebuilds it from scratch on every expansion.
+ * @param mount - When the content is built and thrown away, same three values
+ *   as a popup's (see popup_content_mount.js). `"from-first-open"` (the
+ *   default) builds it on the first expansion and keeps it afterwards.
+ *   `"always"` builds it right away; in layout="column" it also gives the
+ *   closed expandable its content's height (the content is kept laid out at
+ *   its open width), so opening only reveals the width instead of changing the
+ *   height too. `"while-opened"` throws the content away once the collapse
+ *   settles — after the closing animation, so it still plays on real
+ *   content — and rebuilds it from scratch on every expansion.
  */
 export const Expandable = (props) => {
   import.meta.css = css;
@@ -320,8 +321,7 @@ export const Expandable = (props) => {
     layout,
     autoFocus,
     maxContentHeight,
-    mountWhenClosed,
-    unmountWhenClosed,
+    mount = MOUNT_DEFAULT,
     arrowKeyShortcuts = true,
     openKeyShortcut = "ArrowRight",
     closeKeyShortcut = "ArrowLeft",
@@ -335,7 +335,9 @@ export const Expandable = (props) => {
   const contentContainerRef = useRef();
   const contentId = useId();
   const isColumn = layout === "column";
-  const closedContentSized = Boolean(isColumn && mountWhenClosed);
+  const mountedAlways = mount === "always";
+  const mountedWhileOpened = mount === "while-opened";
+  const closedContentSized = isColumn && mountedAlways;
 
   if (signal) {
     warnSignalCollision(props, "expandable", "open");
@@ -353,14 +355,11 @@ export const Expandable = (props) => {
   const { loading: actionLoading } = useActionStatus(effectiveAction);
 
   const [contentMounted, setContentMounted] = useState(
-    () => Boolean(mountWhenClosed) || opened,
+    () => mountedAlways || opened,
   );
-  // Same exclusion as popup_content_mount.js: content that must exist while
-  // closed cannot also be thrown away on close.
-  const effectiveUnmountWhenClosed = unmountWhenClosed && !mountWhenClosed;
 
   // Fully open and no longer moving — what allows overflow to become visible
-  // (see the CSS) and what unmountWhenClosed waits for before emptying.
+  // (see the CSS) and what mount="while-opened" waits for before emptying.
   const [settled, setSettled] = useState(true);
 
   // Read before the close touches the DOM: flipping the content to inert can
@@ -435,7 +434,7 @@ export const Expandable = (props) => {
     focusedAtPointerDownRef.current = null;
     setOpened(nextOpen);
     // Flipped here, before the closing/opening commit, so effects of that very
-    // commit already see the movement as started — unmountWhenClosed must not
+    // commit already see the movement as started — mount="while-opened" must not
     // read a stale "settled" and empty the content under a closing animation.
     setSettled(!animation);
     if (signal) {
@@ -573,17 +572,17 @@ export const Expandable = (props) => {
   }, [opened]);
 
   useLayoutEffect(() => {
-    if (settled && !opened && effectiveUnmountWhenClosed) {
+    if (settled && !opened && mountedWhileOpened) {
       setContentMounted(false);
     }
-  }, [settled, opened, effectiveUnmountWhenClosed]);
+  }, [settled, opened, mountedWhileOpened]);
   useLayoutEffect(() => {
-    if (mountWhenClosed) {
+    if (mountedAlways) {
       setContentMounted(true);
     }
-  }, [mountWhenClosed]);
+  }, [mountedAlways]);
 
-  // closedContentSized (column + mountWhenClosed): the closed content sizes
+  // closedContentSized (column + mount="always"): the closed content sizes
   // the height (see the CSS), which is only right if it lies at its OPEN
   // width — at its natural closed width (a 0-wide track) it would wrap
   // against nothing and stack word by word. So while closed, its width is

packages/frontend/navi/src/control/demos/21_expandable_demo.html

@@ -1409,8 +1409,7 @@ const PickerFirstResolver = (props) => {
  *   popupTestId?: string,
  *   confirmTestId?: string,
  *   cancelTestId?: string,
- *   mountWhenClosed?: boolean,
- *   unmountWhenClosed?: boolean,
+ *   mount?: "always" | "from-first-open" | "while-opened",
  *   dialogExpand?: boolean,
  *   dialogExpandX?: boolean,
  *   dialogExpandY?: boolean,
@@ -1636,13 +1635,12 @@ const PickerFirstResolver = (props) => {
  *   Both are elements navi builds, which a test may not name by class (see
  *   docs/testid.md).
  * @param {string} [cancelTestId]
- * @param {boolean} [mountWhenClosed] The popup's own (see Popup): build the
- *   children before any opening. Left out, a picker told no value builds them
- *   right away — 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.
- * @param {boolean} [unmountWhenClosed] The popup's own: throw the children
- *   away once the popup has closed.
+ * @param {"always"|"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.
  */
 // Every picker type is resolved into one of these before it gets here (see
 // PickerTypeResolver and resolveInputProps): a native input type, or navi_js

packages/frontend/navi/src/control/expandable/expandable.jsx

@@ -15,6 +15,7 @@
  * Escape, a click outside) is no.
  */
 
+import { MOUNT_DEFAULT } from "@jsenv/navi/src/layout/popup_content_mount.js";
 import { useNextResolver } from "@jsenv/navi/src/resolver/resolver.jsx";
 import { naviI18n } from "@jsenv/navi/src/text/navi_i18n.js";
 import { triggerNaviCommand } from "../commands.js";
@@ -108,8 +109,8 @@ export const PickerConfirmResolver = (props) => {
       onConfirm={onConfirm}
       // A question holds no value to read before it is asked: the popup is
       // built on the first open, like that of a picker told its value (see
-      // mountWhenClosed in picker_custom.jsx).
-      mountWhenClosed={false}
+      // the `mount` resolution in picker_custom.jsx).
+      mount={MOUNT_DEFAULT}
       message={undefined}
       confirmLabel={undefined}
       cancelLabel={undefined}

packages/frontend/navi/src/control/picker/picker.jsx

@@ -15,6 +15,7 @@ import {
   PopupModeContext,
   useResolvedPopupMode,
 } from "@jsenv/navi/src/layout/popup_mode.jsx";
+import { MOUNT_DEFAULT } from "@jsenv/navi/src/layout/popup_content_mount.js";
 import { Popup } from "@jsenv/navi/src/layout/popup.jsx";
 import { useNextResolver } from "@jsenv/navi/src/resolver/resolver.jsx";
 import { interactionsDisputeThePress } from "../interaction/interactions.js";
@@ -609,9 +610,9 @@ const PickerCustom = (props) => {
       // 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.
-      mountWhenClosed:
-        props.mountWhenClosed ?? !isControlValueGivenByProps(props),
-      unmountWhenClosed: props.unmountWhenClosed,
+      mount:
+        props.mount ??
+        (isControlValueGivenByProps(props) ? MOUNT_DEFAULT : "always"),
       // 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
@@ -902,8 +903,7 @@ const PickerContentInsidePopup = (props) => {
       {...rest}
       // On popupProps already (see the picker's popup assembly); they mean
       // nothing to the picker element.
-      mountWhenClosed={undefined}
-      unmountWhenClosed={undefined}
+      mount={undefined}
       onFocusOut={(e) => {
         if (!isPopover || !closeOnFocusOut) {
           return;
@@ -1005,7 +1005,7 @@ const PICKER_CALLOUT_CONTENT_TOKEN = createOpenToken();
  * The content is rendered through a portal into an element this component
  * owns, handed to the callout as its message (a Node, appended as-is). It is
  * rendered whether the callout is open or not, so what the content holds
- * survives a close, the way a popup's `mountWhenClosed` keeps it. The element
+ * survives a close, the way a popup's `mount="always"` keeps it. The element
  * carries data-picker-content: the callout is appended inside the picker root,
  * and a press in there must read as inside the popup, not on the trigger.
  */