work

Author: dmail

packages/frontend/navi/docs/AI_INSTRUCTIONS.md

@@ -166,8 +166,9 @@ to start when unsure which export solves a problem.
 
 - `interactions.md` — a gesture is named, not read by hand: the `interactions`
   prop, swipes and holds, the gate, `selfInteractions` for an affordance inside
-  somebody else's box, registering a detector. Read before a `pointerdown`
-  listener of your own, and before stopping propagation to keep a popup shut.
+  somebody else's box, `actionStandalone` for a run nothing above waits on,
+  registering a detector. Read before a `pointerdown` listener of your own, and
+  before stopping propagation to keep a popup shut.
 - `drag_interactions.md` — an element carried: `move`, `reorder`, `land`,
   `toss`, `leave`, `moving`, the `grab`/`release`/`refuse` moments, dressing the
   clone, and the machinery for a gesture whose product is a value. Read before

packages/frontend/navi/docs/form_changed.md

@@ -181,7 +181,9 @@ and that is deliberate: a door that carries no value of its own can still
 write into the form through what its popup does, and a read-only form must
 still shut it. An affordance that genuinely writes nowhere says that
 separately, with `whenSelfInteractionsBlocked="ignore"` — as it says whose
-press it is with `selfInteractions`. Three questions, three props (see
+press it is with `selfInteractions`, and a control whose action is meant to be
+left running says THAT separately too, with `actionStandalone`. One question
+each, one prop each (see
 [interactions.md](./interactions.md#the-third-question-whose-value-is-it)).
 
 Every control takes the prop, groups included — `<Form standalone>` is the

packages/frontend/navi/docs/interactions.md

@@ -12,6 +12,7 @@
   - [Why it is a list, and why it is required](#why-it-is-a-list-and-why-it-is-required)
   - [Where the zone blocks: does it write to the control it sits in?](#where-the-zone-blocks-does-it-write-to-the-control-it-sits-in)
   - [The third question: whose value is it?](#the-third-question-whose-value-is-it)
+  - [The fourth question: whose wait is it?](#the-fourth-question-whose-wait-is-it)
   - [On something you draw yourself](#on-something-you-draw-yourself)
   - [When the affordance should sit OUTSIDE instead](#when-the-affordance-should-sit-outside-instead)
   - [navi steps back; a plain `onClick` does not](#navi-steps-back-a-plain-onclick-does-not)
@@ -278,7 +279,7 @@ that gesture. Whose **value** an element carries is a separate question, and
 group around it, so what it holds never joins that value (see
 [form_changed.md](./form_changed.md#a-control-that-answers-for-itself)).
 
-The three come apart, which is why they are three props:
+They come apart, which is why they are separate props:
 
 | the element                                             | says                                                                        |
 | ------------------------------------------------------- | --------------------------------------------------------------------------- |
@@ -291,6 +292,39 @@ Reading `standalone` as "ignore everything around me" is the trap: `disabled`,
 because "what do I hold" and "may anything be changed here" are not the same
 question.
 
+### The fourth question: whose wait is it?
+
+A running action says two things at once. To the control: I am mid-action —
+busy, a second press refused, the error callout if it fails. To everything
+around it: nothing here moves on — the form does not submit, and the popup does
+not close (see
+[popup_open.md](./popup_open.md#the-popup-owns-its-open-state)).
+
+The second half is a promise about an answer: a send holds something neither
+committed nor given up, so the screen showing it stays. It is exactly wrong for
+a run that was started to be LEFT running — activating a service worker update,
+which lands only once the browser switches over and can be held by the page's
+own in-flight work for minutes. Waiting is not the point; the app goes on being
+used and the feedback is somewhere else entirely. `actionStandalone` says the
+wait is the control's own:
+
+```jsx
+<Button action={() => activateUpdate()} actionStandalone>
+  Activate
+</Button>
+```
+
+Everything the control does for itself stays: it renders busy, it refuses a
+second press, and it raises the error callout — which is why it keeps `action`
+rather than re-implementing the three by hand. What changes is that no ancestor
+is told: the form around it submits, and the panel it sits in closes on Escape,
+on the backdrop and on its cross.
+
+The question that picks it is what closing over the run would lose. An answer
+being sent: everything — the popup is the only place its failure can be read,
+and `actionStandalone` there is how a save fails behind a closed popup. Something
+the app watches from somewhere else: nothing — it was never being watched here.
+
 ### On something you draw yourself
 
 `selfInteractions` is a `Box` prop too, so an affordance does not have to become

packages/frontend/navi/docs/popup_open.md

@@ -41,6 +41,23 @@ A form that is sending holds an answer that is neither committed nor given up.
 Escape, the backdrop, a close button — all of them ask, and the busy control
 answers, the same way it would answer anyone else.
 
+That is the right answer for a run bounded by a request that comes back. A run
+deliberately left going is the other case — activating a service worker update,
+which lands only once the browser switches over and can take as long as the
+page's own in-flight work takes. Nothing is held there: the app stays usable
+while it settles, and a panel that waits for it is a panel that may never close
+again. The control says so, and no popup around it is told:
+
+```jsx
+<Button action={() => activateUpdate()} actionStandalone>
+  Activate
+</Button>
+```
+
+It is still busy for itself — the spinner, the second press refused, the error
+callout — which is the whole point of keeping `action` (see
+[interactions.md](./interactions.md#the-fourth-question-whose-wait-is-it)).
+
 So the question is never "should this popup be controlled?" but "what triggers
 the opening?" — and, when the answer is the application rather than a gesture,
 where that state lives:
@@ -497,6 +514,10 @@ save running on its own behind a closed popup — close from somewhere the actio
 does not hold up, e.g. an `onClick` of your own. Know what it costs: **a save
 that fails does so behind a closed popup**.
 
+Nobody wanting to close, but everybody wanting to be ABLE to, is a different
+need and has its own answer: `actionStandalone` (see the top of this page) frees
+the popup without closing it, and the error callout stays where the press was.
+
 ## Escape cancels, the other gestures keep
 
 The gestures that close a popup do not all mean the same thing, and that is on

packages/frontend/navi/src/control/control_context.js

@@ -117,6 +117,9 @@ export const CONTROL_PROP_SET = new Set([
   "resetOnAbort",
   "resetOnError",
   "optimistic",
+  // The wait this control's action creates is its own: it renders busy and
+  // refuses a second press, and nothing above it is told (see BUSY_CONSTRAINT).
+  "actionStandalone",
 
   "charGuard",
   "maxLengthGuard",

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

@@ -1593,7 +1593,14 @@ const useInteractiveProps = (
     const parentAction = useContext(ActionContext);
     const actionStatus = useActionStatus(boundAction);
     const networkPolicyReason = useNetworkPolicyReason();
-    const { disabled, required, readOnly, loading, optimistic } = props;
+    const {
+      disabled,
+      required,
+      readOnly,
+      loading,
+      optimistic,
+      actionStandalone,
+    } = props;
 
     // `whenSelfInteractionsBlocked="ignore"`: an affordance that writes nothing
     // to the control it sits in has no business inheriting that control's state
@@ -1676,6 +1683,11 @@ const useInteractiveProps = (
     // Read by BUSY_CONSTRAINT: an optimistic control stays interactive while
     // its bound action runs (a new toggle replaces the run instead of waiting).
     uiStateController.optimistic = Boolean(optimistic);
+    // Read by BUSY_CONSTRAINT: the wait belongs to this control alone. It is
+    // busy for itself — the render, the second press, the callout — and nothing
+    // above it is told, so a form still submits and a popup still closes over a
+    // run that was meant to be left going.
+    uiStateController.actionStandalone = Boolean(actionStandalone);
     // What the interaction rule last refused is only true while the control is
     // held; the state it was read from moves here (see refreshReport).
     useLayoutEffect(() => {

packages/frontend/navi/src/control/input/button.jsx

@@ -124,6 +124,7 @@ const COMMAND_DEFAULT_PROPS_FACTORIES = {
  *   selfInteractions?: string,
  *   whenSelfInteractionsBlocked?: "hide" | "refuse" | "ignore",
  *   replace?: boolean,
+ *   actionStandalone?: boolean,
  *   [key: string]: any,
  * }>}
  * @param {boolean} [replace] Go where the press leads — an `href`, a
@@ -154,6 +155,13 @@ const COMMAND_DEFAULT_PROPS_FACTORIES = {
  *   by whether it WRITES to the control it sits in: it goes (`"hide"`, the
  *   default), `"refuse"` keeps it and refuses with a callout, `"ignore"` lets
  *   it through untouched — for an affordance that never wrote to that control.
+ * @param {boolean} [actionStandalone] The wait this button's action creates is
+ *   its own: it renders busy, refuses a second press and raises the error
+ *   callout as always, and nothing above it is told — the form around it still
+ *   submits, the popup it sits in still closes. For a run started to be left
+ *   running, which the app watches from somewhere else; never for one holding
+ *   an answer the screen is the only place to read (see
+ *   docs/interactions.md#the-fourth-question-whose-wait-is-it).
  * @param {string} [contentDisplay] The display of the frame the button draws
  *   around its children. It follows the button's own by default — its display
  *   and, a display alone saying nothing about direction, the rest of its flow

packages/frontend/navi/src/control/rules/interaction/busy_constraint.js

@@ -13,6 +13,11 @@ export const BUSY_CONSTRAINT = {
   transient: true,
   // Unlike readonly/disabled, a busy element DOES block its parent from
   // submitting — the element is mid-operation and cannot safely participate.
+  // Unless it says the wait is its own (`actionStandalone`): then the refusal
+  // stays on the element and every ancestor reads it as free — the group above
+  // (see getInteractionBlockingControls) and the popup around it (see
+  // findBusyElementInside in dialog.jsx and popover.jsx, which both filter on
+  // `ignoredByParents`).
   check: (field, { intent } = {}) => {
     const isBusy = isControlBusy(field);
     if (!isBusy) {
@@ -32,7 +37,11 @@ export const BUSY_CONSTRAINT = {
     const message = isButton
       ? naviI18n("constraint.busy.button")
       : naviI18n("constraint.busy.default");
-    return { message, status: "info" };
+    return {
+      message,
+      status: "info",
+      ignoredByParents: Boolean(field.actionStandalone),
+    };
   },
 };
 CONSTRAINT_ATTRIBUTE_SET.add("data-busy");

packages/frontend/navi/src/layout/dialog.jsx

@@ -970,10 +970,19 @@ const DOCKED_SWIPE_GRIP = "[data-header],[data-swipe-grip]";
 // controls rather than reading an attribute off the dialog: a dialog carries no
 // state of its own (see this file's top comment), and `aria-busy` on the
 // controls is a render snapshot — BUSY_CONSTRAINT reads the live answer.
+// Same as Popover's own; kept in both rather than shared, since each file reads
+// on its own — what changes here changes there too.
 const findBusyElementInside = (dialogEl) => {
   for (const element of dialogEl.querySelectorAll("[navi-control-host]")) {
     const controller = element.__uiStateController__;
-    if (controller && BUSY_CONSTRAINT.check(controller)) {
+    if (!controller) {
+      continue;
+    }
+    const busyInfo = BUSY_CONSTRAINT.check(controller);
+    // `ignoredByParents`: the control says the wait is its own
+    // (`actionStandalone`), so a popup is one more ancestor it does not hold —
+    // the same reading a group makes of it (see control_interaction.js).
+    if (busyInfo && !busyInfo.ignoredByParents) {
       return element;
     }
   }

packages/frontend/navi/src/layout/popover.jsx

@@ -767,12 +767,19 @@ const PopoverCustom = (props) => {
 // controls rather than reading an attribute off the popup: a popup carries no
 // state of its own (see this file's top comment), and `aria-busy` on the
 // controls is a render snapshot — BUSY_CONSTRAINT reads the live answer.
-// Same as Dialog's own; kept in both rather than shared, since it is three
-// lines and each file reads on its own.
+// Same as Dialog's own; kept in both rather than shared, since each file reads
+// on its own — what changes here changes there too.
 const findBusyElementInside = (popupEl) => {
   for (const element of popupEl.querySelectorAll("[navi-control-host]")) {
     const controller = element.__uiStateController__;
-    if (controller && BUSY_CONSTRAINT.check(controller)) {
+    if (!controller) {
+      continue;
+    }
+    const busyInfo = BUSY_CONSTRAINT.check(controller);
+    // `ignoredByParents`: the control says the wait is its own
+    // (`actionStandalone`), so a popup is one more ancestor it does not hold —
+    // the same reading a group makes of it (see control_interaction.js).
+    if (busyInfo && !busyInfo.ignoredByParents) {
       return element;
     }
   }