@jsenv/navi 0.29.171 → 0.29.173

package/dist/jsenv_navi.js

@@ -1489,6 +1489,11 @@ naviI18n.addAll({
     fr: "Cette action attend une modification.",
     en: "This action is waiting for a change.",
   },
+  // parallelGuard: the surface already has as many runs in flight as it allows
+  "constraint.readonly.parallel_guard": {
+    fr: "[max] action[s] déjà en cours, attendez qu'une se termine.",
+    en: "[max] action[s] already in progress, wait for one to finish.",
+  },
   "constraint.readonly.network_policy": {
     fr: "Hors ligne : ça ne peut pas partir.",
     en: "Offline: this cannot be sent.",
@@ -3301,15 +3306,23 @@ const SYMBOL_OBJECT_SIGNAL = Symbol.for("navi_object_signal");
  * resolves priorities between the four operation sets (reset > rerun > run >
  * prerun) and performs them.
  *
- * Memory design (the surprising part): nothing here keeps actions alive.
- * Child actions are held through ephemerons (createJsValueWeakMap) so a child
- * and its params are garbage-collected together, running actions live in
- * iterable *weak* sets, and property/signal mirroring uses weakEffect. Two
+ * Memory design (the surprising part): by default nothing here keeps actions
+ * alive. Child actions are held through ephemerons (createJsValueWeakMap) so a
+ * child and its params are garbage-collected together, running actions live in
+ * iterable *weak* sets, and property/signal mirroring uses weakEffect. Three
  * consequences to be aware of:
  * - an action can exist in several places only if everyone shares the same
  *   instance (the caches above are what makes lookups return it);
  * - prerun actions may have no other reference yet, so
- *   prerunProtectionRegistry pins them for a few minutes.
+ *   prerunProtectionRegistry pins them until they answer;
+ * - an answer outlives the screen that asked for it only where the question
+ *   declared `keep` (createKeptAnswerRegistry); everything else is asked again.
+ *
+ * What makes that design fragile: reading an action's signals from inside an
+ * effect subscribes that effect to them, and the root action never dies — so
+ * the effect, and everything its closure holds, never dies either. Stringifying
+ * an action for a debug message is the easy way to do it by accident, which is
+ * why toString peeks.
  *
  * A failing run rejects, and writes its error into errorSignal as well. The
  * callers that cannot take a rejection — a run started from a signal effect, a
@@ -3424,6 +3437,58 @@ const prerunProtectionRegistry = (() => {
   };
 })();
 
+/**
+ * The answers a root action keeps once the screen that asked for them is gone.
+ *
+ * An action holds its answer for exactly as long as something references it, so
+ * without this the lifetime of an answer is whatever the garbage collector
+ * decides: coming back to a screen re-asks the same question, or does not,
+ * depending on when a collection happened to run.
+ *
+ * Age is read when someone looks an answer up, never on a timer. A screen
+ * nobody is on must not talk to the network, and an answer expiring under a
+ * screen someone IS on would empty it mid-read.
+ */
+const createKeptAnswerRegistry = ({ ms, max }) => {
+  // insertion order is recency order: looking an answer up re-inserts it, so
+  // the first key is always the least recently used one
+  const answeredAtMap = new Map();
+
+  return {
+    keep: (action) => {
+      answeredAtMap.delete(action);
+      answeredAtMap.set(action, Date.now());
+      if (max === undefined) {
+        return;
+      }
+      while (answeredAtMap.size > max) {
+        const [leastRecentlyUsed] = answeredAtMap.keys();
+        answeredAtMap.delete(leastRecentlyUsed);
+      }
+    },
+
+    drop: (action) => {
+      answeredAtMap.delete(action);
+    },
+
+    touch: (action) => {
+      const answeredAt = answeredAtMap.get(action);
+      if (answeredAt === undefined) {
+        return;
+      }
+      answeredAtMap.delete(action);
+      if (ms !== undefined && Date.now() - answeredAt > ms) {
+        // reset rather than drop the instance: equal params must keep giving
+        // the same action, otherwise whoever still holds this one would be
+        // reading a different instance than whoever asks for it next.
+        action.reset({ reason: "kept answer expired" });
+        return;
+      }
+      answeredAtMap.set(action, answeredAt);
+    },
+  };
+};
+
 const formatActionSet = (actionSet, prefix = "") => {
   let message = prefix;
   for (const action of actionSet) {
@@ -3823,12 +3888,38 @@ const mergeActionParams = (currentParams, newParams) => {
 };
 
 const actionWeakMap = new WeakMap();
+/**
+ * Wraps an async callback into an action: a question, its answer, and the
+ * signals saying where that answer is.
+ *
+ * @param {Function} callback
+ * @param {object} [rootOptions]
+ * @param {{ ms?: number, max?: number }} [rootOptions.keep] - how long an
+ *   answer stays good once it has landed. Without it an answer lives exactly as
+ *   long as something references it: the screen that asked goes away, and
+ *   coming back asks the same question again at a moment nothing in the code
+ *   decides.
+ *
+ *   `ms` counts from the moment the answer landed; `max` caps how many answers
+ *   are held at once, the least recently looked-at going first. Age is read
+ *   when someone looks, never on a timer — a screen nobody is on must not talk
+ *   to the network — and an expired answer is `reset()`, so the question goes
+ *   back out through whoever asks for it next.
+ *
+ *   It is declared here rather than on each binding because the answer to "how
+ *   long is this still true?" belongs to the question: a court list is good for
+ *   the session, a count of people watching grows on its own and is worth a few
+ *   minutes, a payment status is worth nothing at all.
+ */
 const createAction = (callback, rootOptions = {}) => {
   const existing = actionWeakMap.get(callback);
   if (existing) {
     return existing;
   }
 
+  const keptAnswerRegistry = rootOptions.keep
+    ? createKeptAnswerRegistry(rootOptions.keep)
+    : null;
   let rootAction;
 
   const createActionCore = (options, { parentAction } = {}) => {
@@ -4060,6 +4151,9 @@ const createAction = (callback, rootOptions = {}) => {
       }
       const existingChildAction = childActionWeakMap.get(newParamsOrSignal);
       if (existingChildAction) {
+        if (keptAnswerRegistry) {
+          keptAnswerRegistry.touch(existingChildAction);
+        }
         return existingChildAction;
       }
       const childAction = _bindParams(
@@ -4198,7 +4292,10 @@ const createAction = (callback, rootOptions = {}) => {
         paramsSignal.value = nextParams;
         return true;
       },
-      toString: () => action.callSource,
+      // peek: an action gets stringified into debug messages built inside
+      // effects, and subscribing there would keep those effects — and everything
+      // their closures hold — alive for as long as the action itself.
+      toString: () => actionCallSourceSignal.peek(),
       meta,
       debug: (...args) => {
         if (!meta.debug && !DEBUG$2) {
@@ -4362,6 +4459,9 @@ const createAction = (callback, rootOptions = {}) => {
             onComplete?.(data, action);
             completeSideEffectCleanup = completeSideEffect?.(action);
           });
+          if (keptAnswerRegistry) {
+            keptAnswerRegistry.keep(action);
+          }
           if (DEBUG$2) {
             console.log(`"${action}": completed`);
           }
@@ -4477,6 +4577,9 @@ const createAction = (callback, rootOptions = {}) => {
         }
 
         prerunProtectionRegistry.unprotect(action);
+        if (keptAnswerRegistry) {
+          keptAnswerRegistry.drop(action);
+        }
 
         if (sideEffectCleanup) {
           sideEffectCleanup(reason);
@@ -4726,7 +4829,7 @@ const createActionProxyFromSignal = (
       );
     },
     replaceParams: null, // Will be set below
-    toString: () => actionProxy.callSource,
+    toString: () => callSourceSignal.peek(), // peek: see the action's toString
     meta: action.meta,
 
     paramsSignal: proxyParamsSignal,
@@ -7268,6 +7371,33 @@ const openCallout = (message, {
       preventScroll: true
     });
   }
+  close_on_escape_from_anywhere: {
+    // Escape closes a callout by reaching its anchor (above), which works while
+    // the anchor holds the keyboard. Some do not: a callout opened with
+    // `skipFocus` leaves the focus where it was, and a press on a blocked list
+    // row leaves it nowhere at all — the row refuses the press, focus included.
+    // The callout is then unreachable by keyboard, and "click somewhere else to
+    // make it go" is not an answer for someone not using a pointer.
+    //
+    // Only for the ones that cannot be heard otherwise, and only while they are
+    // open: a callout the anchor can hear about is left to the anchor, so
+    // Escape goes on meaning what it means where the user is.
+    if (anchorElement && anchorElement.contains(document.activeElement)) {
+      break close_on_escape_from_anywhere;
+    }
+    const onDocumentKeydown = e => {
+      if (e.key !== "Escape") {
+        return;
+      }
+      requestClose(e, "escape_key");
+      e.stopPropagation();
+      e.preventDefault();
+    };
+    document.addEventListener("keydown", onDocumentKeydown, true);
+    addTeardown(() => {
+      document.removeEventListener("keydown", onDocumentKeydown, true);
+    });
+  }
   {
     const handleCustomCloseEvent = e => {
       onRequestClose(e);
@@ -8240,7 +8370,16 @@ const createCalloutManager = (
       // Resolved as the token is added, and kept with it: a token shown later
       // (when the one covering it goes) must be drawn where it was pointing at
       // the time, and the control itself is where a token pointing nowhere goes.
-      anchorElement: anchorElement || controller.ref.current,
+      //
+      // Unless the control has somewhere better to send it, which is why it is
+      // given the event: a control drawn by something else — a list row whose
+      // selection is a visually hidden checkbox — answers for a whole box, and
+      // the sentence belongs where the press landed inside it rather than in
+      // its middle (see getCalloutAnchorElement in list_selectable.jsx).
+      anchorElement:
+        anchorElement ||
+        controller.getCalloutAnchorElement?.(event) ||
+        controller.ref.current,
     };
     tokens.set(token, tokenData);
     showToken(tokenData, event);
@@ -10102,6 +10241,15 @@ const readOnlyMessage = (field) => {
   if (reason === "network-policy") {
     return getNetworkPolicyReadOnlyMessage();
   }
+  // As many runs as the surface allows are already out (see parallel_guard.js):
+  // what stops the press is the queue, and it says how long it is.
+  if (reason === "parallel-guard") {
+    const { max } = field.parallelGuard;
+    return naviI18n("constraint.readonly.parallel_guard", {
+      max,
+      s: max > 1 ? "s" : "",
+    });
+  }
   // A send button held back by the form above it, which holds nothing new (see
   // Button's own `readOnlyWhileFormUnchanged`) — what stops the press is not the
   // button, it is the form still waiting for a change, so that is what it says.
@@ -33397,6 +33545,70 @@ document.body.addEventListener(
   { capture: true },
 );
 
+/**
+ * How many runs a surface lets happen at once.
+ *
+ * A list whose rows each carry their own action is a place to act, row by row,
+ * and nothing about it stops someone from starting a run on every row before
+ * any of them comes back: a dozen requests in flight, a dozen rows waiting, and
+ * a server asked to do a dozen things at once because a list happened to be
+ * long. The guard is what makes the surface say "not yet" instead — the rows
+ * that are not running go read-only and say what they are waiting for, and the
+ * next press is possible again the moment one of the runs comes back.
+ *
+ * It counts runs, not values — which is what separates it from
+ * `maxLengthGuard`, the one that says how many things a selection may HOLD.
+ * Both refuse a gesture; they refuse it for unrelated reasons and a surface can
+ * carry either, or both.
+ */
+const ParallelGuardContext = createContext(null);
+
+/**
+ * @param {number} max - how many runs may be in flight at once. `Infinity`
+ *   lifts the guard without taking it out of the tree.
+ */
+const useParallelGuard = (max) => {
+  const guardRef = useRef(null);
+  if (!guardRef.current) {
+    // A Set rather than a counter: a control asks about ITSELF (its own run is
+    // never what blocks it), and a start that arrives twice for one run must
+    // not be counted twice.
+    const runningSet = new Set();
+    const runningCountSignal = signal(0);
+    const guard = {
+      max,
+      runningCountSignal,
+      claim: (controller) => {
+        if (runningSet.has(controller)) {
+          return;
+        }
+        runningSet.add(controller);
+        runningCountSignal.value = runningSet.size;
+      },
+      release: (controller) => {
+        if (!runningSet.delete(controller)) {
+          return;
+        }
+        runningCountSignal.value = runningSet.size;
+      },
+      blocks: (controller) => {
+        if (guard.max === Infinity) {
+          return false;
+        }
+        if (runningSet.has(controller)) {
+          return false;
+        }
+        // Read through the signal so a control held back re-renders — and
+        // becomes pressable again — the moment one of the runs comes back.
+        return runningCountSignal.value >= guard.max;
+      },
+    };
+    guardRef.current = guard;
+  }
+  guardRef.current.max = max;
+  return guardRef.current;
+};
+
 /**
  * How a control tells the labels pointing at it what it is (disabled, readOnly,
  * required) and when it goes away.
@@ -34312,6 +34524,9 @@ const useUIStateController = (
         resetUIState: (e) => {
           controller.setUIState(controller.state, e);
         },
+        // Read by the callout manager when it has nowhere else to point.
+        getCalloutAnchorElement: (event) =>
+          resolveCalloutAnchorElement(controller.ref.current, event),
         // What the control shows becomes what is acknowledged: the outside said
         // yes to it, so it is where a rollback goes back to. Left alone for a
         // control whose value is GIVEN — the prop is already its truth — and
@@ -34535,6 +34750,44 @@ const firstDefinedChildUIState = (children) => {
   return undefined;
 };
 
+// Where a control that cannot point at itself puts what it has to say.
+//
+// A control drawn by something ELSE answers for a box bigger than itself: a
+// list row's selection is a visually hidden checkbox inside a whole pressable
+// row, so a callout anchored on the control lands in the middle of that row,
+// pointing at nothing. What the press landed on is what the sentence is about
+// — another control in the same box takes it (the button that invites, the
+// picker that opens), and the box itself takes what was aimed at the box.
+//
+// Answering null leaves the callout where it would have gone, which is also
+// what a box asks for once and for all with `data-callout-anchor="item"`.
+const resolveCalloutAnchorElement = (element, event) => {
+  if (!element || !element.closest("[navi-visually-hidden]")) {
+    return null;
+  }
+  const target = event?.target;
+  if (!target || !target.closest) {
+    return null;
+  }
+  const controlRoot = findControlRoot(element);
+  if (
+    !controlRoot ||
+    controlRoot.getAttribute("data-callout-anchor") === "item"
+  ) {
+    return null;
+  }
+  const controlHost = target.closest("[navi-control-host]");
+  if (
+    !controlHost ||
+    controlHost === element ||
+    !controlRoot.contains(controlHost) ||
+    controlHost.closest("[navi-visually-hidden]")
+  ) {
+    return null;
+  }
+  return controlHost;
+};
+
 // A run that came back with a yes settles what the control is worth — but only
 // for the control the run BELONGS to. Anything with a `command` still fires its
 // own navi_action_* events (it is given a placeholder action so they exist),
@@ -37370,6 +37623,7 @@ const useInteractiveProps = (props, {
     const controlRequired = useContext(RequiredContext);
     const controlLoadingFromAbove = useContext(LoadingContext$1);
     const parentActionRequester = useContext(ActionRequesterContext);
+    const parallelGuard = useContext(ParallelGuardContext);
     const parentAction = useContext(ActionContext);
     const actionStatus = useActionStatus(boundAction);
     const networkPolicyReason = useNetworkPolicyReason();
@@ -37407,7 +37661,12 @@ const useInteractiveProps = (props, {
     // why (see network_policy.js): a press that looks accepted and fails after
     // is what the policy exists to avoid.
     const heldByNetworkPolicy = networkPolicyReason !== null && (isWriteAction(boundAction) || Boolean(zoneStateApplies && parentAction && isWriteAction(parentAction)));
-    const readOnlyBase = readOnly || controlReadOnly || loadingBase || readOnlyFromParentMaxLengthGuard || controlInfo.readOnlyUncontrolled || heldByNetworkPolicy;
+    // Held back because the surface above already has as many runs in flight as
+    // it allows (see parallel_guard.js). Only a control that would START one:
+    // anything without an action of its own runs nothing and has nothing to
+    // wait its turn for.
+    const heldByParallelGuard = Boolean(zoneStateApplies && parallelGuard && props.action && parallelGuard.blocks(uiStateController));
+    const readOnlyBase = readOnly || controlReadOnly || loadingBase || readOnlyFromParentMaxLengthGuard || heldByParallelGuard || controlInfo.readOnlyUncontrolled || heldByNetworkPolicy;
     // An optimistic control trusts its action to succeed: the state the user
     // just set stays visible and interactive while the action runs — no
     // loading, no readonly. On failure resetOnError rolls the state back and
@@ -37452,6 +37711,13 @@ const useInteractiveProps = (props, {
     } else {
       controlHostProps["aria-readonly"] = readOnlyResolved ? "true" : "false";
     }
+    // Read by READONLY_CONSTRAINT to say how many runs are already out, and by
+    // the action handlers below, which are where a run joins and leaves the
+    // count (a labelled block away, hence through the controller).
+    uiStateController.parallelGuard = parallelGuard;
+    if (heldByParallelGuard) {
+      controlHostProps["data-readonly-reason"] = "parallel-guard";
+    }
     if (heldByNetworkPolicy) {
       // Read by READONLY_CONSTRAINT; wins over any other reason the control
       // carries — nothing leaves, whatever else was holding it.
@@ -37695,6 +37961,7 @@ const useInteractiveProps = (props, {
         // carried by every navi_action_* event of that run).
         uiStateController.pendingActionEvent = e.detail.event;
         uiStateController.actionInFlight = true;
+        uiStateController.parallelGuard?.claim(uiStateController);
         // The very instance this run uses, resolved now — while the UI state
         // still holds the value the run was made for. detail.action may be a
         // proxy following that state, and by the time anyone wants to abort
@@ -37709,6 +37976,7 @@ const useInteractiveProps = (props, {
         e.detail.addSideEffect(outcome => {
           uiStateController.actionInFlight = false;
           uiStateController.runningAction = null;
+          uiStateController.parallelGuard?.release(uiStateController);
           const queuedEvent = uiStateController.queuedActionAllowedEvent;
           if (!queuedEvent) {
             return;
@@ -56983,12 +57251,22 @@ const translateOf = (axis, distance) =>
 
 const PopupClose = ({
   label,
+  iconSize,
   ...rest
 }) => {
   return jsx(Button, {
     command: "--navi-close",
     icon: true,
     variant: "discrete"
+    // Dismissing writes nothing to whatever control the popup belongs to, so
+    // that control's read-only and disabled are not about this cross: a
+    // read-only picker still opens to be read (see readonly_constraint.js),
+    // and what is opened has to be closable. Whether closing is allowed at
+    // this instant is the popup's own question, answered by the popup — a
+    // dialog holds the close while an action inside it runs (see
+    // findBusyElementInside in dialog.jsx).
+    ,
+    whenSelfInteractionsBlocked: "ignore"
     // The cross is drawn at the control size, which is a few millimetres
     // wide; the padding is what makes it a target a thumb can hit.
     ,
@@ -56997,6 +57275,7 @@ const PopupClose = ({
     "aria-label": label === undefined ? naviI18n("button.close") : label,
     ...rest,
     children: jsx(Icon, {
+      size: iconSize,
       children: jsx(CloseSvg, {})
     })
   });
@@ -63873,6 +64152,11 @@ const ListUI = props => {
     })
   });
 };
+// How many of a list's own rows may be acting at once, when the rows are what
+// carry the action. Four rather than none: a list is a place where the same
+// gesture is available many times over, and nothing else stops a long one from
+// putting a request out for every row it draws.
+const PARALLEL_GUARD_DEFAULT = 4;
 const ListFirstResolver = props => {
   const Next = useNextResolver();
   const refDefault = useRef(null);
@@ -63884,8 +64168,13 @@ const ListFirstResolver = props => {
     virtualRef.current = createListVirtual();
   }
   props.virtual = virtualRef.current;
-  return jsx(Next, {
-    ...props
+  const parallelGuard = useParallelGuard(props.parallelGuard ?? PARALLEL_GUARD_DEFAULT);
+  return jsx(ParallelGuardContext.Provider, {
+    value: parallelGuard,
+    children: jsx(Next, {
+      ...props,
+      parallelGuard: undefined
+    })
   });
 };
 
@@ -63899,6 +64188,7 @@ const ListFirstResolver = props => {
  *   deselectable?: boolean,
  *   maxLength?: number,
  *   maxLengthGuard?: number,
+ *   parallelGuard?: number,
  *   standalone?: boolean,
  *   action?: (value: any) => void,
  *   uiAction?: (value: any) => void,
@@ -64075,6 +64365,13 @@ const ListFirstResolver = props => {
  *   taking — and `uiAction` is not called. The selected ones stay takeable
  *   back, so a selection that arrived too long can always be brought back
  *   under the limit. Implies `maxLength` for validity.
+ * @param {number} [props.parallelGuard=4]
+ *   How many runs the rows may have in flight at once, for a list whose rows
+ *   carry their own `action` (a button per row). While that many are out, every
+ *   row that is not running goes read-only and says how many it is waiting on;
+ *   the next press is possible again as soon as one comes back. `Infinity`
+ *   lifts it. Counts runs, not values — `maxLengthGuard` above is the one that
+ *   says how many things the selection may hold.
  * @param {boolean} [props.standalone]
  *   This list answers for itself: it does not register with the control group
  *   or picker around it, so its selection stays out of that value and nothing
@@ -66067,8 +66364,25 @@ const ListItemReal = props => {
     if (event.button !== 0 || isOverlaidOnRow(event)) {
       return;
     }
-    blockInteraction(event);
     pressStartedHereRef.current = true;
+    // A row that IS a control has one already able to answer this, in the same
+    // words it uses for the keyboard, and it is the one the callout would be
+    // anchored on either way — two answers would be two callouts on one anchor,
+    // toggling each other off (see `reopen` in openCallout).
+    //
+    // Asked before the press is blocked, not after: a gate handed an event
+    // already prevented reads it as "someone else took this one" and steps
+    // back without a word (see onRequestInteraction).
+    const controlHost = isControlRoot(event.currentTarget) ? findControlHost(event.currentTarget) : null;
+    if (controlHost) {
+      dispatchRequestInteraction(controlHost, {
+        event,
+        name: "press on a blocked row"
+      });
+      blockInteraction(event);
+      return;
+    }
+    blockInteraction(event);
     // One at a time, and not the one that just dismissed it (see the refs).
     if (calloutRef.current && calloutRef.current.opened) {
       return;