@jsenv/navi 0.29.236 → 0.29.298

package/dist/dev/jsenv_navi.js

@@ -6984,7 +6984,17 @@ const openCallout = (
       `append callout into ${getElementSignature(calloutContainer)}`,
     );
   }
+  let checkCalloutInsertionImpact;
+  {
+    checkCalloutInsertionImpact = startCalloutInsertionImpactCheck(
+      calloutContainer,
+      anchorElement,
+    );
+  }
   calloutContainer.appendChild(calloutElement);
+  if (checkCalloutInsertionImpact) {
+    checkCalloutInsertionImpact();
+  }
   calloutElement.showPopover();
   addTeardown(() => {
     calloutElement.remove();
@@ -7550,6 +7560,54 @@ const canContainCallout = (element) => {
   return true;
 };
 
+// A callout is a popover with no layout box of its own, so putting it in the
+// tree must move nothing. Anything that does move means an app rule counting
+// element children — :last-child, :nth-child, :only-child, :empty, > * + * —
+// took the callout for one of them and changed subject. Invisible from the
+// app, where the rule and the markup both read fine.
+// Two boxes rather than every child of the container: a callout on a list row
+// would otherwise measure the whole list on each press.
+const startCalloutInsertionImpactCheck = (calloutContainer, anchorElement) => {
+  if (!anchorElement) {
+    return null;
+  }
+  const anchorBoxBefore = anchorElement.getBoundingClientRect();
+  const containerBoxBefore = calloutContainer.getBoundingClientRect();
+  return () => {
+    const anchorBoxAfter = anchorElement.getBoundingClientRect();
+    const containerBoxAfter = calloutContainer.getBoundingClientRect();
+    let what;
+    let boxBefore;
+    let boxAfter;
+    if (!isSameBox(anchorBoxBefore, anchorBoxAfter)) {
+      what = "moved it";
+      boxBefore = anchorBoxBefore;
+      boxAfter = anchorBoxAfter;
+    } else if (!isSameBox(containerBoxBefore, containerBoxAfter)) {
+      what = `moved ${getElementSignature(calloutContainer)} around it`;
+      boxBefore = containerBoxBefore;
+      boxAfter = containerBoxAfter;
+    } else {
+      return;
+    }
+    console.warn(
+      `opening a callout on ${getElementSignature(anchorElement)} ${what}: ${formatBox(boxBefore)} -> ${formatBox(boxAfter)}.
+A callout draws nothing in the flow, but while it is open it is an element child of ${getElementSignature(calloutContainer)}: a rule counting children there (:last-child, :nth-child, :only-child, :empty, > * + *) counts it too and matches something else than what it aims at.
+Say which children the rule counts: :nth-last-child(1 of S) / :nth-child(An+B of S), where S names yours (a class, or :not([navi-out-of-flow]) — the marker navi's out-of-flow elements carry). A sibling rule takes the marker between its compounds: > *:not([navi-out-of-flow]) + *:not([navi-out-of-flow]).
+See @jsenv/navi docs/css_architecture.md.`,
+    );
+  };
+};
+const isSameBox = (a, b) => {
+  return (
+    a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height
+  );
+};
+const formatBox = ({ x, y, width, height }) => {
+  const round = (value) => Math.round(value * 100) / 100;
+  return `${round(width)}x${round(height)} at ${round(x)},${round(y)}`;
+};
+
 const escapeHtml = (string) => {
   return string
     .replace(/&/g, "&")
@@ -18950,6 +19008,20 @@ const resolveSpacingSize = (size, element, property = "padding") => {
   }
   return normalizeStyle(SIZE_MAP[size] || size, property, "js", element);
 };
+// Whether a spacing is nothing at all, answered without resolving it. A
+// viewport or container length resolves through a computed-style read, and
+// asked during a render that read forces the browser to compute the style of
+// a tree still being built, stylesheets still being adopted. Zero is a fact
+// about the number written, whatever the unit; a scale keyword is never zero.
+const isZeroSpacingSize = (size) => {
+  if (typeof size === "number") {
+    return size === 0;
+  }
+  if (typeof size !== "string") {
+    return false;
+  }
+  return parseFloat(size) === 0;
+};
 
 const COLOR_KEYWORD_MAP = {
   primary: "var(--navi-color-primary)",
@@ -20605,16 +20677,16 @@ const useComposeElementRef = (syncElement, externalRef) => {
   const cleanupRef = useRef(null);
   const elRef = useRef(null);
   const prevSyncElementRef = useRef(undefined);
-  const stableRef = useRef(null);
+  const holderRef = useRef(null);
   const externalRefRef = useRef(externalRef);
   const syncElementRef = useRef(syncElement);
   syncElementRef.current = syncElement;
-  // Detect external ref identity change between renders. The refCallback is
-  // stable across renders, so when the parent passes a new ref object (or
-  // switches from null to a ref), Preact does NOT re-fire the callback while
-  // the DOM element is unchanged. We must manually clear the old ref and
-  // populate the new one with the current element to avoid leaving the new
-  // ref's `.current` stuck at `null`.
+  // Detect external ref identity change between renders. The refCallback keeps
+  // its identity once it holds the element, so when the parent passes a new
+  // ref object (or switches from null to a ref), Preact does NOT re-fire the
+  // callback while the DOM element is unchanged. We must manually clear the
+  // old ref and populate the new one with the current element to avoid
+  // leaving the new ref's `.current` stuck at `null`.
   const prevExternalRefRef = useRef(externalRef);
   if (prevExternalRefRef.current !== externalRef) {
     const previous = prevExternalRefRef.current;
@@ -20632,12 +20704,12 @@ const useComposeElementRef = (syncElement, externalRef) => {
   }
   externalRefRef.current = externalRef;
 
-  if (!stableRef.current) {
-    // Created once, like the ref callback that calls it, and reading the sync
-    // function through a ref for that reason: the element can be replaced long
-    // after the first render — a tag that changes, a box hidden then shown —
-    // and what the new element gets must be the current render's sync, not
-    // the one the first render closed over.
+  if (!holderRef.current) {
+    // Created once, and reading the sync function through a ref for that
+    // reason: the element can be replaced long after the first render — a tag
+    // that changes, a box hidden then shown — and what the new element gets
+    // must be the current render's sync, not the one the first render closed
+    // over.
     const runSync = (el) => {
       if (cleanupRef.current) {
         cleanupRef.current();
@@ -20650,6 +20722,18 @@ const useComposeElementRef = (syncElement, externalRef) => {
         cleanupRef.current = cleanup;
       }
     };
+    holderRef.current = { runSync, refCallback: null };
+  }
+  const { runSync } = holderRef.current;
+
+  // A new callback on every render until Preact has handed it the element,
+  // the same one afterwards. Preact re-applies a ref only when its identity
+  // changes, and a diff that throws with no error boundary above skips
+  // commitRoot: its refs are dropped while its DOM stays and is adopted as
+  // mounted by the next render. A callback that never fired would then never
+  // fire, and a Box would stay raw HTML for the life of the document. Free on
+  // a healthy mount, where the first callback is the only one ever created.
+  if (!elRef.current) {
     const refCallback = (el) => {
       elRef.current = el;
       // Keep .current in sync immediately so useEffect callbacks that read
@@ -20673,9 +20757,9 @@ const useComposeElementRef = (syncElement, externalRef) => {
         prevSyncElementRef.current = undefined;
       }
     };
-    stableRef.current = { refCallback, runSync };
+    holderRef.current.refCallback = refCallback;
   }
-  const { refCallback, runSync } = stableRef.current;
+  const { refCallback } = holderRef.current;
 
   // If element already mounted, re-sync when syncElement reference changed.
   if (elRef.current && syncElement !== prevSyncElementRef.current) {
@@ -32186,6 +32270,17 @@ registerNaviCommand("--navi-send", (source, event, { requester }) => {
         return sent;
       }
       if (isRunning) {
+        // An optimistic control takes its send as done on its own word: what
+        // follows it runs at once and the run goes on detached — still
+        // watched, still able to fail, its error callout then drawn on what
+        // surrounds the closed surface it was typed in (see openCallout's
+        // anchor resolution in callout.js).
+        const sendController = (findControlHost(target) || target)
+          .__uiStateController__;
+        if (sendController?.optimistic) {
+          runAfterSend();
+          return sent;
+        }
         // The send is committing but has not finished: leaving now would take
         // the form off the screen mid-submission (a popup closing over its own
         // running action, a slide moving on before it is answered). What
@@ -36777,6 +36872,16 @@ const useControlProps = (props, {
           if (!deferredCommand) {
             return;
           }
+          if (uiStateController.optimistic) {
+            // An optimistic button takes its action as done on its own word:
+            // the command runs at once and the run goes on detached, the same
+            // release the form counterpart gives the send (see --navi-send in
+            // commands.js). Only a refused press has nothing to follow.
+            if (completion.result !== false) {
+              deferredCommand();
+            }
+            return;
+          }
           runWhenActionSucceeded(completion, deferredCommand);
         };
         return {
@@ -39989,47 +40094,35 @@ const LoadingIndicatorFluid = ({
   const [containerWidth, setContainerWidth] = useState(0);
   const [containerHeight, setContainerHeight] = useState(0);
   const [containerRadius, setContainerRadius] = useState(0);
+
+  // Sized by the observer alone, first frame included: an element gets an
+  // observation for the size it has when first observed, delivered after the
+  // frame's own layout and before its paint. Measuring here instead would
+  // force a layout in the middle of the commit, on a tree the commit is still
+  // writing to, and the frame would lay it out again. Inside the callback style
+  // and layout are clean, so the radius read there is a lookup, not a recalc.
   useLayoutEffect(() => {
     const indicatorEl = ref.current;
     if (!indicatorEl) {
       return null;
     }
-    const {
-      width,
-      height
-    } = indicatorEl.getBoundingClientRect();
-    setContainerWidth(width);
-    setContainerHeight(height);
-    if (radius === undefined || radius === "inherit") {
-      const parentEl = indicatorEl.parentElement;
-      // Prefer the inline style (always available, even before layout is computed).
-      // Fall back to computed longhands — getComputedStyle shorthand may return ""
-      // if the browser hasn't resolved the layout yet.
-      const radius = parentEl.style.borderRadius || parentEl.style.borderTopLeftRadius || getComputedStyle(parentEl).borderTopLeftRadius || "0px";
-      setContainerRadius(radius);
-    }
-    let animationFrameId = null;
-    // Create a resize observer to detect changes in the container's dimensions
-    const resizeObserver = new ResizeObserver(entries => {
-      // Use requestAnimationFrame to debounce updates
-      if (animationFrameId) {
-        cancelAnimationFrame(animationFrameId);
-      }
-      animationFrameId = requestAnimationFrame(() => {
-        const [containerEntry] = entries;
-        const {
-          width,
-          height
-        } = containerEntry.contentRect;
-        setContainerWidth(width);
-        setContainerHeight(height);
-      });
+    const resizeObserver = new ResizeObserver(([containerEntry]) => {
+      const {
+        width,
+        height
+      } = containerEntry.contentRect;
+      setContainerWidth(width);
+      setContainerHeight(height);
+      if (radius === undefined || radius === "inherit") {
+        const parentEl = indicatorEl.parentElement;
+        // The inline style says the radius as the caller wrote it; the
+        // computed longhand otherwise, the shorthand computing to "" when the
+        // four corners differ.
+        setContainerRadius(parentEl.style.borderRadius || parentEl.style.borderTopLeftRadius || getComputedStyle(parentEl).borderTopLeftRadius || "0px");
+      }
     });
     resizeObserver.observe(indicatorEl);
     return () => {
-      if (animationFrameId) {
-        cancelAnimationFrame(animationFrameId);
-      }
       resizeObserver.disconnect();
     };
   }, []);
@@ -44371,6 +44464,13 @@ const measureDrawing = ({
  * Measured rather than declared: a bar's size comes from a prop, a theme
  * variable, its own content or the device's notch, and only the used value
  * knows all four.
+ *
+ * Written once per task, after every bar has measured. The variable resizes
+ * an ancestor of the bars — the scroll container takes its padding from it —
+ * so a write landing between two measurements turns the second one into a
+ * style recalc and a layout of the whole page. Sizes are queued, and the queue
+ * lands in a microtask: still before the browser paints, so the content is
+ * never seen under a bar, and after every read of the commit that queued them.
  */
 
 // Several bars can share an edge — during a page transition the outgoing and
@@ -44384,10 +44484,14 @@ const sizeMapByArea = new Map();
 // size again — the ones for the smaller bars, and the second half of a page
 // transition.
 const writtenValueByArea = new Map();
+// Sizes said and not yet written. One queue for both callers below: a bar
+// saying its size twice before the write keeps the last word, whoever said it.
+const pendingSizeMapByArea = new Map();
+let flushMicrotaskQueued = false;
+let flushFrame = null;
 
-// A size that must land before the next paint: a render changed the bar, so
-// the room it takes is given back in that same commit and the content is never
-// painted under it.
+// A size a render produced: a prop, the children or a theme variable changed
+// the bar, and the room it takes is given back before that commit is painted.
 /**
  * @param {"top"|"bottom"|"left"|"right"} area
  * @param {Element} barElement - Which bar this size belongs to.
@@ -44395,41 +44499,47 @@ const writtenValueByArea = new Map();
  *   content.
  */
 const setFixedBarSpace = (area, barElement, size) => {
-  dropPendingSize(area, barElement);
-  storeSize(area, barElement, size);
-  writeSpace(area);
-};
-
-// A size nothing asked for, coming from a ResizeObserver. Writing the variable
-// resizes an ANCESTOR of the bars — the scroll container takes its padding
-// from it — and mutating layout from inside a resize callback is what makes
-// the browser report "ResizeObserver loop completed with undelivered
-// notifications". So the write waits for the frame that resize produced.
-// Queued here rather than deferred by each bar on its own, so the bars sharing
-// an edge resolve to a single write instead of one per bar.
+  queueSize(area, barElement, size);
+  if (flushMicrotaskQueued) {
+    return;
+  }
+  flushMicrotaskQueued = true;
+  queueMicrotask(() => {
+    flushMicrotaskQueued = false;
+    flushPendingSizes();
+  });
+};
+
+// A size nothing asked for, coming from a ResizeObserver. Mutating layout from
+// inside a resize callback is what makes the browser report "ResizeObserver
+// loop completed with undelivered notifications", so this write waits for the
+// frame that resize produced.
 /**
  * @param {"top"|"bottom"|"left"|"right"} area
  * @param {Element} barElement - Which bar this size belongs to.
  * @param {number} size - In px.
  */
 const requestFixedBarSpace = (area, barElement, size) => {
+  queueSize(area, barElement, size);
+  if (flushFrame !== null) {
+    return;
+  }
+  flushFrame = requestAnimationFrame(() => {
+    flushFrame = null;
+    flushPendingSizes();
+  });
+};
+
+const queueSize = (area, barElement, size) => {
   let pendingSizeMap = pendingSizeMapByArea.get(area);
   if (!pendingSizeMap) {
     pendingSizeMap = new Map();
     pendingSizeMapByArea.set(area, pendingSizeMap);
   }
   pendingSizeMap.set(barElement, size);
-  if (flushFrame !== null) {
-    return;
-  }
-  flushFrame = requestAnimationFrame(flushPendingSizes);
 };
 
-const pendingSizeMapByArea = new Map();
-let flushFrame = null;
-
 const flushPendingSizes = () => {
-  flushFrame = null;
   for (const [area, pendingSizeMap] of pendingSizeMapByArea) {
     for (const [barElement, size] of pendingSizeMap) {
       storeSize(area, barElement, size);
@@ -44439,20 +44549,6 @@ const flushPendingSizes = () => {
   pendingSizeMapByArea.clear();
 };
 
-// What the bar itself just said wins over what its observer had queued about
-// it: a bar unmounting gives its room back, and a size queued for it before
-// that must not put it back.
-const dropPendingSize = (area, barElement) => {
-  const pendingSizeMap = pendingSizeMapByArea.get(area);
-  if (!pendingSizeMap) {
-    return;
-  }
-  pendingSizeMap.delete(barElement);
-  if (pendingSizeMap.size === 0) {
-    pendingSizeMapByArea.delete(area);
-  }
-};
-
 const storeSize = (area, barElement, size) => {
   let sizeMap = sizeMapByArea.get(area);
   if (!sizeMap) {
@@ -48732,6 +48828,7 @@ const COMMAND_DEFAULT_PROPS_FACTORIES = {
  *   replace?: boolean,
  *   actionStandalone?: boolean,
  *   actionAbortable?: boolean,
+ *   optimistic?: boolean,
  *   [key: string]: any,
  * }>}
  * @param {boolean} [replace] Go where the press leads — an `href`, a
@@ -48775,6 +48872,12 @@ const COMMAND_DEFAULT_PROPS_FACTORIES = {
  *   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 {boolean} [optimistic] The action is taken as done on the button's own
+ *   word: no busy state, a second press queues behind the run, and its
+ *   `command` runs at once — the popup it sits in closes over the run, which
+ *   goes on behind. A failure then has no popup to be read in: `resetOnError`
+ *   puts the button back and the error callout is drawn on what surrounds the
+ *   closed popup (see docs/popup_open.md#the-popup-owns-its-open-state).
  * @param {boolean} [actionAbortable] The person waiting may give up on this
  *   button's action: closing the popup the run holds calls it off and goes
  *   through, instead of being refused. For a run whose answer may never come —
@@ -59662,7 +59765,7 @@ const useDialogProps = props => {
     bottom: false,
     left: false
   };
-  if (resolveSpacingSize(marginWithContainer) === 0) {
+  if (isZeroSpacingSize(marginWithContainer)) {
     const {
       y,
       x