@jsenv/navi 0.29.9 → 0.29.11

package/dist/jsenv_navi.js

@@ -1663,6 +1663,11 @@ const generateSignalId = () => {
  * @param {"string" | "number" | "boolean" | "object"} [options.type="string"] - Type for localStorage serialization/deserialization
  * @param {number} [options.step] - For number type: step size for precision. Values will be rounded to nearest multiple of step.
  * @param {Array} [options.oneOf] - Array of valid values for validation. Signal will be marked invalid if value is not in this array
+ * @param {boolean} [options.weak=false] - The param qualifies one visit, not the screen: it is written into a
+ *   url only when explicitly named (`routeParams={{ edit: id }}`), never inherited from the signal's current
+ *   value, and it goes back to the default value when the route stops matching. Use it for params like an
+ *   "edit this one" id, where every other link to the screen must lead to the plain screen.
+ *   Incompatible with `persists` (throws).
  * @param {boolean} [options.debug=false] - Enable debug logging for this signal's operations
  * @returns {import("@preact/signals").Signal} A signal that can be synchronized with a source signal and/or persisted in localStorage. The signal includes a `validity` property for validation state.
  *
@@ -1735,8 +1740,15 @@ const stateSignal = (defaultValue, options = {}) => {
     default: staticFallback,
     ignoreArrayOrder,
     autoFix,
+    weak = false,
   } = options;
 
+  if (weak && persists) {
+    throw new TypeError(
+      `stateSignal "${id}": weak and persists are contradictory — a weak param qualifies one visit, it cannot be restored from a previous session.`,
+    );
+  }
+
   // Check if defaultValue is a signal (dynamic default) or static value
   const isDynamicDefault =
     defaultValue &&
@@ -2099,6 +2111,23 @@ setBaseUrl(
     : window.location.origin,
 );
 
+/**
+ * The single place where "this param was not provided, take the signal value"
+ * happens while building a url. A weak param qualifies one visit, not the
+ * screen: it enters a url only when the caller names it (or when it is already
+ * in the url being preserved), so here it always reads as absent.
+ * Not reading the signal also keeps the built url from depending on it.
+ */
+const readSignalForUrlBuild = (connection) => {
+  if (!connection || !connection.signal) {
+    return undefined;
+  }
+  if (connection.weak) {
+    return undefined;
+  }
+  return connection.signal.value;
+};
+
 /**
  * Creates a custom route pattern matcher
  */
@@ -2173,7 +2202,7 @@ const createRoutePattern = (pattern, { searchParams = {} } = {}) => {
         // Parameter was explicitly provided - always respect explicit parameters
         continue;
       }
-      const signalValue = connection.signal.value;
+      const signalValue = readSignalForUrlBuild(connection);
       if (signalValue !== undefined) {
         // Parameter was not provided, check signal value
         resolvedParams[paramName] = signalValue;
@@ -2186,7 +2215,7 @@ const createRoutePattern = (pattern, { searchParams = {} } = {}) => {
         // Parameter was explicitly provided - always respect explicit parameters
         continue;
       }
-      const signalValue = connection.signal.value;
+      const signalValue = readSignalForUrlBuild(connection);
       if (signalValue !== undefined) {
         // Parameter was not provided, check signal value
         resolvedParams[paramName] = signalValue;
@@ -2229,7 +2258,7 @@ const createRoutePattern = (pattern, { searchParams = {} } = {}) => {
           continue;
         }
 
-        const ancestorSignalValue = ancestorConnection.signal.value;
+        const ancestorSignalValue = readSignalForUrlBuild(ancestorConnection);
         if (
           ancestorSignalValue !== undefined &&
           ancestorSignalValue !== ancestorConnection.getDefaultValue()
@@ -2307,7 +2336,7 @@ const createRoutePattern = (pattern, { searchParams = {} } = {}) => {
           if (childParam in resolvedParams) {
             continue;
           }
-          const childSignalValue = childConnection.signal.value;
+          const childSignalValue = readSignalForUrlBuild(childConnection);
           // Only include if not already resolved and is non-default
           if (
             childSignalValue !== undefined &&
@@ -2349,7 +2378,7 @@ const createRoutePattern = (pattern, { searchParams = {} } = {}) => {
         }
       } else {
         // Parameter not provided but signal has a value
-        const signalValue = connection.signal.value;
+        const signalValue = readSignalForUrlBuild(connection);
         if (connection.isCustomValue(signalValue)) {
           // Only include custom values
           filtered[paramName] = signalValue;
@@ -2368,7 +2397,7 @@ const createRoutePattern = (pattern, { searchParams = {} } = {}) => {
         }
       } else {
         // Parameter not provided but signal has a value
-        const signalValue = connection.signal.value;
+        const signalValue = readSignalForUrlBuild(connection);
         if (connection.isCustomValue(signalValue)) {
           // Only include custom values
           filtered[paramName] = signalValue;
@@ -2385,7 +2414,7 @@ const createRoutePattern = (pattern, { searchParams = {} } = {}) => {
   const canReachLiteralValue = (literalValue, params, literalPosition) => {
     // Check parent's own parameters (signals and user params)
     const parentCanProvide = connections.some((conn) => {
-      const signalValue = conn.signal.value;
+      const signalValue = readSignalForUrlBuild(conn);
       const userValue = params[conn.paramName];
       const effectiveValue = userValue !== undefined ? userValue : signalValue;
       return (
@@ -2414,7 +2443,7 @@ const createRoutePattern = (pattern, { searchParams = {} } = {}) => {
       return false;
     }
     return connsAtPosition.some((conn) => {
-      const signalValue = conn.signal.value;
+      const signalValue = readSignalForUrlBuild(conn);
       return signalValue === literalValue && conn.isCustomValue(signalValue);
     });
   };
@@ -2469,7 +2498,7 @@ const createRoutePattern = (pattern, { searchParams = {} } = {}) => {
               pathConnectionMap.get(paramName) ||
               queryConnectionMap.get(paramName);
             if (parentConnection) {
-              parentParamValue = parentConnection.signal.value;
+              parentParamValue = readSignalForUrlBuild(parentConnection);
             }
           }
 
@@ -2554,7 +2583,7 @@ const createRoutePattern = (pattern, { searchParams = {} } = {}) => {
       paramValue = item.userValue;
     } else {
       paramName = item.paramName;
-      paramValue = item.signal.value;
+      paramValue = readSignalForUrlBuild(item);
       // Only include custom parent signal values (not using defaults)
       if (paramValue === undefined || !item.isCustomValue(paramValue)) {
         return { isCompatible: true, shouldInclude: false };
@@ -2661,7 +2690,7 @@ const createRoutePattern = (pattern, { searchParams = {} } = {}) => {
         if (!siblingConnection) {
           continue;
         }
-        const siblingSignalValue = siblingConnection.signal.value;
+        const siblingSignalValue = readSignalForUrlBuild(siblingConnection);
         if (siblingSignalValue === undefined) {
           continue;
         }
@@ -2705,7 +2734,7 @@ const createRoutePattern = (pattern, { searchParams = {} } = {}) => {
         const explicitValue = params[paramName];
         const connection =
           pathConnectionMap.get(paramName) || queryConnectionMap.get(paramName);
-        const signalValue = connection ? connection.signal.value : undefined;
+        const signalValue = readSignalForUrlBuild(connection);
 
         // Check if the parameter has the required value
         if (
@@ -2759,7 +2788,7 @@ const createRoutePattern = (pattern, { searchParams = {} } = {}) => {
           hasActiveParams = true;
         }
       } else {
-        const signalValue = connection.signal.value;
+        const signalValue = readSignalForUrlBuild(connection);
         if (signalValue !== undefined) {
           // No explicit override - use signal value
           childParams[paramName] = signalValue;
@@ -2976,7 +3005,7 @@ const createRoutePattern = (pattern, { searchParams = {} } = {}) => {
         }
         // If explicitly undefined, don't include it (which means don't use child route)
       } else {
-        const signalValue = connection.signal.value;
+        const signalValue = readSignalForUrlBuild(connection);
         if (
           signalValue !== undefined &&
           connection.isCustomValue(signalValue)
@@ -3016,7 +3045,7 @@ const createRoutePattern = (pattern, { searchParams = {} } = {}) => {
           continue; // Already have this parameter
         }
 
-        const signalValue = connection.signal.value;
+        const signalValue = readSignalForUrlBuild(connection);
         // Only include custom signal values (not using defaults)
         if (
           signalValue !== undefined &&
@@ -3198,7 +3227,7 @@ const createRoutePattern = (pattern, { searchParams = {} } = {}) => {
           paramName,
           connection,
         ] of childPatternObj.pathConnectionMap) {
-          const signalValue = connection.signal.value;
+          const signalValue = readSignalForUrlBuild(connection);
           if (
             signalValue !== undefined &&
             connection.isCustomValue(signalValue)
@@ -3220,7 +3249,7 @@ const createRoutePattern = (pattern, { searchParams = {} } = {}) => {
           paramName,
           connection,
         ] of childPatternObj.queryConnectionMap) {
-          const signalValue = connection.signal.value;
+          const signalValue = readSignalForUrlBuild(connection);
           if (
             signalValue !== undefined &&
             connection.isCustomValue(signalValue)
@@ -3840,7 +3869,7 @@ const createRoutePattern = (pattern, { searchParams = {} } = {}) => {
       );
       for (const conn of targetAncestor.connections) {
         console.debug(
-          `[${pattern}] tryDirectOptimization: Target connection ${conn.paramName}: value=${conn.signal.value}, isCustom=${conn.isCustomValue(conn.signal.value)}`,
+          `[${pattern}] tryDirectOptimization: Target connection ${conn.paramName}: value=${readSignalForUrlBuild(conn)}, isCustom=${conn.isCustomValue(readSignalForUrlBuild(conn))}`,
         );
       }
     }
@@ -3857,7 +3886,7 @@ const createRoutePattern = (pattern, { searchParams = {} } = {}) => {
       }
 
       // Only include if not already processed and has custom value (not default)
-      const signalValue = connection.signal.value;
+      const signalValue = readSignalForUrlBuild(connection);
       if (signalValue !== undefined) {
         // Don't include path parameters that correspond to literal segments we're optimizing away
         const targetParam = targetParams.find((p) => p.name === paramName);
@@ -3903,7 +3932,7 @@ const createRoutePattern = (pattern, { searchParams = {} } = {}) => {
         }
 
         // Only inherit custom values (not defaults) that we don't already have
-        const signalValue = connection.signal.value;
+        const signalValue = readSignalForUrlBuild(connection);
         if (
           signalValue !== undefined &&
           connection.isCustomValue(signalValue)
@@ -3989,7 +4018,7 @@ const createRoutePattern = (pattern, { searchParams = {} } = {}) => {
         }
 
         // Only inherit if we don't have this param and parent has custom value (not default)
-        const parentSignalValue = parentConnection.signal.value;
+        const parentSignalValue = readSignalForUrlBuild(parentConnection);
         if (
           parentSignalValue !== undefined &&
           parentConnection.isCustomValue(parentSignalValue)
@@ -4075,7 +4104,36 @@ const createRoutePattern = (pattern, { searchParams = {} } = {}) => {
   // search params are updated. When buildMostPreciseUrl performs an ancestor
   // optimisation (e.g. "/map/isochrone/compare" → "/map/isochrone") it is trusted
   // as-is because the built pathname will differ from the route's own base pathname.
+  // Weak params are never inherited from their signal, but a url that already
+  // carries one keeps it: staying on the same screen while another param
+  // changes must not end the visit this param qualifies.
+  const carryOverWeakParams = (currentUrl, params) => {
+    let paramsWithWeak = params;
+    for (const [paramName, connection] of [
+      ...pathConnectionMap,
+      ...queryConnectionMap,
+    ]) {
+      if (!connection.weak || paramName in paramsWithWeak) {
+        continue;
+      }
+      const currentValue = connection.signal.peek();
+      if (currentValue === undefined) {
+        continue;
+      }
+      const currentParams = applyOn(currentUrl);
+      if (!currentParams || currentParams[paramName] === undefined) {
+        continue;
+      }
+      if (paramsWithWeak === params) {
+        paramsWithWeak = { ...params };
+      }
+      paramsWithWeak[paramName] = currentParams[paramName];
+    }
+    return paramsWithWeak;
+  };
+
   const buildUrlPreservingPath = (currentUrl, params = {}) => {
+    params = carryOverWeakParams(currentUrl, params);
     const relativeBuiltUrl = buildMostPreciseUrl(params);
     if (!currentUrl) {
       return resolveRouteUrl(relativeBuiltUrl);
@@ -4332,7 +4390,7 @@ const parsePattern = (pattern, { pathConnectionMap, queryConnectionMap }) => {
         if (
           connection &&
           connection.signal &&
-          connection.signal.value === undefined &&
+          readSignalForUrlBuild(connection) === undefined &&
           !hasDefault
         ) {
           isOptional = true;
@@ -5516,7 +5574,10 @@ const route = (pattern, { searchParams } = {}) => {
       });
     };
     route.matchesParams = (providedParams) => {
-      const currentParams = route.params;
+      // paramsSignal (not route.params) so a component calling this during render
+      // subscribes to param changes: a navigation from /games/me/a to /games/me/b
+      // leaves matchingSignal untouched, only the params change.
+      const currentParams = route.paramsSignal.value;
       const resolvedParams = routePattern.resolveParams({
         ...currentParams,
         ...providedParams,
@@ -5883,6 +5944,22 @@ This prevents cross-test pollution and ensures clean state.`,
                 }
               }
 
+              // A weak param qualifies one visit: leaving the route ends it,
+              // whatever the family and whatever the default. Coming back by a
+              // url that does not carry the param comes back to a blank screen.
+              if (connection.weak) {
+                if (!parameterExtractedByMatchingRoute) {
+                  const defaultValue = connection.getDefaultValue();
+                  if (debug) {
+                    console.debug(
+                      `[route] weak param ${paramName}: route no longer matching, back to ${defaultValue}`,
+                    );
+                  }
+                  paramSignal.value = defaultValue;
+                }
+                continue;
+              }
+
               // Only reset signal if:
               // 1. We're navigating within the same route family (not to completely unrelated routes)
               // 2. AND no matching route extracts this parameter from URL
@@ -9665,7 +9742,7 @@ const setupNetworkMonitoring = () => {
 };
 setupNetworkMonitoring();
 
-installImportMetaCssBuild(import.meta);const css$X = /* css */`
+installImportMetaCssBuild(import.meta);const css$Y = /* css */`
   .navi_loading_indicator_fluid_container {
     position: relative;
     display: flex;
@@ -9697,7 +9774,7 @@ const LoadingIndicatorFluid = ({
   visuallyHidden,
   ...rest
 }) => {
-  import.meta.css = [css$X, "@jsenv/navi/src/graphic/loading/loading_indicator_fluid.jsx"];
+  import.meta.css = [css$Y, "@jsenv/navi/src/graphic/loading/loading_indicator_fluid.jsx"];
   const ref = useRef(null);
   // The container dimensions can be deduced from the ref itself as the indicator is absolute inset 0
   const [containerWidth, setContainerWidth] = useState(0);
@@ -9902,7 +9979,7 @@ const LoadingRectangleSvg = ({
   });
 };
 
-installImportMetaCssBuild(import.meta);const css$W = /* css */`
+installImportMetaCssBuild(import.meta);const css$X = /* css */`
   .navi_loading_outline_wrapper {
     position: absolute;
     /* Controls place the outline slightly outside their box, right on top of
@@ -9939,7 +10016,7 @@ installImportMetaCssBuild(import.meta);const css$W = /* css */`
   }
 `;
 const LoadingOutline = props => {
-  import.meta.css = [css$W, "@jsenv/navi/src/graphic/loading/loading_outline.jsx"];
+  import.meta.css = [css$X, "@jsenv/navi/src/graphic/loading/loading_outline.jsx"];
   if (props.containerRef) {
     const container = props.containerRef.current;
     if (!container) {
@@ -10264,7 +10341,7 @@ const selectByTextStrings = (element, range, startText, endText) => {
 };
 
 installImportMetaCssBuild(import.meta);// https://jsfiddle.net/v5xzJ/4/
-const css$V = /* css */`
+const css$W = /* css */`
   @layer navi {
     .navi_text {
       &[data-skeleton] {
@@ -10770,7 +10847,7 @@ const TextShrinkWrap = props => {
   });
 };
 const TextUI = props => {
-  import.meta.css = [css$V, "@jsenv/navi/src/text/text.jsx"];
+  import.meta.css = [css$W, "@jsenv/navi/src/text/text.jsx"];
   let {
     ref,
     spacing,
@@ -13484,7 +13561,7 @@ installImportMetaCssBuild(import.meta);/**
  * - Arrow automatically shows when pointing at a valid anchor element
  * - Centers in viewport when no anchor element provided or anchor is too big
  */
-const css$U = /* css */`
+const css$V = /* css */`
   @layer navi {
     .navi_callout {
       /* A callout is parented to what it explains, so it inherits from it — and
@@ -13704,7 +13781,7 @@ const openCallout = (message, {
   skipFocus = false,
   debug = () => {}
 } = {}) => {
-  import.meta.css = [css$U, "@jsenv/navi/src/control/rules/callout/callout.js"];
+  import.meta.css = [css$V, "@jsenv/navi/src/control/rules/callout/callout.js"];
   if (debug === true) {
     debug = (e, ...args) => console.debug(`"${e.type}" -> `, ...args);
   }
@@ -22782,7 +22859,7 @@ const getAssociatedLabels = element => {
   return [];
 };
 
-installImportMetaCssBuild(import.meta);const css$T = /* css */`
+installImportMetaCssBuild(import.meta);const css$U = /* css */`
   @layer navi {
     .navi_button {
       --button-border-radius: var(--navi-control-border-radius);
@@ -23175,7 +23252,7 @@ installImportMetaCssBuild(import.meta);const css$T = /* css */`
   }
 `;
 const ButtonUI = props => {
-  import.meta.css = [css$T, "@jsenv/navi/src/control/input/button_ui.jsx"];
+  import.meta.css = [css$U, "@jsenv/navi/src/control/input/button_ui.jsx"];
   const {
     ref,
     // href/link
@@ -25303,7 +25380,7 @@ installImportMetaCssBuild(import.meta);/**
  * reaches the real container.
  */
 let openLocalDialogCount = 0;
-const css$S = /* css */`
+const css$T = /* css */`
   @layer navi {
     .navi_dialog {
       /* Min gap between the dialog and the edges of its container. Written
@@ -25713,7 +25790,7 @@ const css$S = /* css */`
  * @param {import("ignore:preact").ComponentChildren} props.children
  */
 const Dialog = props => {
-  import.meta.css = [css$S, "@jsenv/navi/src/layout/dialog.jsx"];
+  import.meta.css = [css$T, "@jsenv/navi/src/layout/dialog.jsx"];
   if (props.openController) {
     return jsx(ControlledDialog, {
       ...props
@@ -26531,7 +26608,7 @@ installImportMetaCssBuild(import.meta);/**
  * and applied.
  */
 let openLocalPopoverCount = 0;
-const css$R = /* css */`
+const css$S = /* css */`
   @layer navi {
     .navi_popover {
       /* soft: user-configurable preferred max-height. Kept as a *default*
@@ -26901,7 +26978,7 @@ const css$R = /* css */`
  * @param {import("ignore:preact").ComponentChildren} props.children
  */
 const Popover = props => {
-  import.meta.css = [css$R, "@jsenv/navi/src/layout/popover.jsx"];
+  import.meta.css = [css$S, "@jsenv/navi/src/layout/popover.jsx"];
   if (props.openController) {
     return jsx(ControlledPopover, {
       ...props
@@ -27865,7 +27942,7 @@ installImportMetaCssBuild(import.meta);/**
  * event, and a caller replacing the body entirely then has one protocol to
  * follow — `--navi-confirm` for yes, anything that closes for no.
  */
-const css$Q = /* css */`
+const css$R = /* css */`
   /* The width lives on the body rather than on the popup, so that custom
      content (which replaces this body entirely) sizes itself instead of
      inheriting a ceiling meant for a sentence-long question. */
@@ -28002,7 +28079,7 @@ const ConfirmPopup = ({
   onAnswer,
   onClosed
 }) => {
-  import.meta.css = [css$Q, "@jsenv/navi/src/action/confirm_popup.jsx"];
+  import.meta.css = [css$R, "@jsenv/navi/src/action/confirm_popup.jsx"];
   const {
     mode,
     confirmLabel,
@@ -28086,7 +28163,7 @@ const defaultBody = (message, {
   });
 };
 
-installImportMetaCssBuild(import.meta);const css$P = /* css */`
+installImportMetaCssBuild(import.meta);const css$Q = /* css */`
   .action_error {
     margin-top: 0;
     margin-bottom: 20px;
@@ -28111,7 +28188,7 @@ const ActionRenderer = ({
   children,
   disabled
 }) => {
-  import.meta.css = [css$P, "@jsenv/navi/src/action/action_renderer.jsx"];
+  import.meta.css = [css$Q, "@jsenv/navi/src/action/action_renderer.jsx"];
   if (action === undefined) {
     throw new Error("ActionRenderer requires an action to render, but none was provided.");
   }
@@ -31360,6 +31437,15 @@ const useActionAsyncData = (action, {
     return [staleData, true, undefined];
   }
 
+  // An action without params has nothing to run and no one to start it: this is
+  // where a route action lands when its params getter returns false. It is not a
+  // load in progress, so there is nothing to wait for — suspending here would
+  // throw a promise that never settles, and the whole <Loading> subtree would
+  // stay hidden for good, silently.
+  if (runningState !== RUNNING && action.paramsSignal.peek() === undefined) {
+    return [action.dataSignal.peek(), false, undefined];
+  }
+
   // IDLE or RUNNING with loadingEffect: "delegate" — suspend
   const reason = runningState === RUNNING ? "loading" : "idle";
   loadingRef.current = {
@@ -33534,11 +33620,12 @@ const collectBranches = children => {
         type: "container",
         node: child
       };
+      const guardMatching = route ? route.matchingSignal.value : false;
       if (!matchingBranch) {
         if (matchingChild) {
           // Real leaf match inside — always select this container
           matchingBranch = branch;
-        } else if (route && route.matchingSignal.value) {
+        } else if (guardMatching) {
           // No leaf match but an explicit route guard matches — select this
           // container so it can render its own fallback inside its layout
           matchingBranch = branch;
@@ -33556,7 +33643,12 @@ const collectBranches = children => {
         type: "leaf",
         node: child
       };
-      if (!matchingBranch && route.matchingSignal.value && (!routeParams || route.matchesParams(routeParams))) {
+      // every signal is read even once a match is found: reading is what
+      // subscribes the container to it, and a branch that is skipped today is
+      // the one that must wake the container up tomorrow
+      const matching = route.matchingSignal.value;
+      const paramsMatching = routeParams ? route.matchesParams(routeParams) : true;
+      if (!matchingBranch && matching && paramsMatching) {
         matchingBranch = branch;
       }
     }
@@ -35142,7 +35234,7 @@ const PhoneSvg = () => {
 };
 
 installImportMetaCssBuild(import.meta);// # TextAnchor — how it works
-const css$O = /* css */`
+const css$P = /* css */`
   .navi_text_anchor {
     vertical-align: baseline;
     user-select: none;
@@ -35177,7 +35269,7 @@ const TextAnchor = ({
   textSize,
   lineLayout
 }) => {
-  import.meta.css = [css$O, "@jsenv/navi/src/text/text_anchor.jsx"];
+  import.meta.css = [css$P, "@jsenv/navi/src/text/text_anchor.jsx"];
   const anchorRef = useRef();
 
   // Plain useLayoutEffect would also fire while an ancestor dialog/popover
@@ -35292,7 +35384,7 @@ const computeTopOffset = ({
 };
 const charTopCanvas = document.createElement("canvas");
 
-installImportMetaCssBuild(import.meta);const css$N = /* css */`
+installImportMetaCssBuild(import.meta);const css$O = /* css */`
   @layer navi {
     /* Ensure data attributes from box.jsx can win to update display */
     .navi_icon {
@@ -35450,7 +35542,7 @@ const Icon = ({
   fillLine,
   ...props
 }) => {
-  import.meta.css = [css$N, "@jsenv/navi/src/text/icon.jsx"];
+  import.meta.css = [css$O, "@jsenv/navi/src/text/icon.jsx"];
   const innerChildren = href ? jsx("svg", {
     width: "100%",
     height: "100%",
@@ -35603,7 +35695,7 @@ const useDimColorWhen = (elementRef, shouldDim) => {
   });
 };
 
-installImportMetaCssBuild(import.meta);const css$M = /* css */`
+installImportMetaCssBuild(import.meta);const css$N = /* css */`
   @layer navi {
     .navi_link {
       --link-border-radius: unset;
@@ -36042,7 +36134,7 @@ Object.assign(PSEUDO_CLASSES, {
  * @param {boolean} [props.readOnly]
  */
 const Link = props => {
-  import.meta.css = [css$M, "@jsenv/navi/src/nav/link/link.jsx"];
+  import.meta.css = [css$N, "@jsenv/navi/src/nav/link/link.jsx"];
   if (props.route) {
     return jsx(LinkWithRoute, {
       ...props
@@ -36277,7 +36369,7 @@ installImportMetaCssBuild(import.meta);/**
  * TabList component with support for horizontal and vertical layouts
  * https://dribbble.com/search/tabs
  */
-const css$L = /* css */`
+const css$M = /* css */`
   @layer navi {
     .navi_nav {
       --nav-border: none;
@@ -36452,7 +36544,7 @@ const Nav = ({
   // "before" or "after": which side the panel sits on, turning the nav into folder tabs
   ...props
 }) => {
-  import.meta.css = [css$L, "@jsenv/navi/src/nav/link/nav.jsx"];
+  import.meta.css = [css$M, "@jsenv/navi/src/nav/link/nav.jsx"];
   children = toChildArray(children);
   return jsx(Box, {
     as: "nav",
@@ -36844,7 +36936,7 @@ installImportMetaCssBuild(import.meta);/**
  * Border width participates in layout (it is added to the tab and page
  * padding): a thick border grows the binder rather than eating into the text.
  */
-const css$K = /* css */`
+const css$L = /* css */`
   @layer navi {
     .navi_binder {
       --binder-border-width: var(--navi-control-border-width);
@@ -37157,7 +37249,7 @@ const Binder = ({
   pagePadding,
   ...props
 }) => {
-  import.meta.css = [css$K, "@jsenv/navi/src/nav/binder/binder.jsx"];
+  import.meta.css = [css$L, "@jsenv/navi/src/nav/binder/binder.jsx"];
   const items = toChildArray(children).map((child, index) => {
     const {
       value: itemValue,
@@ -37579,7 +37671,7 @@ installImportMetaCssBuild(import.meta);/**
  *    into the size; a box-shadow draws the identical line and stays out of
  *    layout.
  */
-const css$J = /* css */`
+const css$K = /* css */`
   @layer navi {
     :root {
       --navi-fixed-bar-width: 56px;
@@ -37717,7 +37809,7 @@ const FixedBar = ({
   border = true,
   ...props
 }) => {
-  import.meta.css = [css$J, "@jsenv/navi/src/layout/fixed_bar/fixed_bar.jsx"];
+  import.meta.css = [css$K, "@jsenv/navi/src/layout/fixed_bar/fixed_bar.jsx"];
   const defaultRef = useRef();
   props.ref = props.ref || defaultRef;
   // Whichever of width/height crosses the edge the bar sits on is what the
@@ -37754,6 +37846,178 @@ const FixedBar = ({
   });
 };
 
+/**
+ * Finds the element that is too wide for the page and says which one it is.
+ *
+ * A page that overflows horizontally is a bug wherever it happens, and on
+ * Chrome Android it is a catastrophic one: the layout viewport inflates to the
+ * content and `position: fixed` centering goes with it (see
+ * docs/MOBILE_LAYOUT_PITFALLS.md). The remedy there is a wrapper in
+ * `overflow-x: clip`, and it works — at the price of making the cause
+ * invisible: nothing sticks out anymore, so nothing says a fixed width, a
+ * `min-width` or an unbreakable string is still oversized. This puts the
+ * signal back, without giving up the net.
+ *
+ * What counts as "too wide" is measured against the box that clips, not
+ * against the document: with `clip` there is no scrollable overflow to read
+ * (`scrollWidth` reports none), so the rectangles of the descendants are what
+ * tells.
+ *
+ * Two things are deliberately not reported, because they cannot reach the
+ * document:
+ * - anything inside a box that clips or scrolls on its own — a wide table in
+ *   its `overflow-x: auto` container is doing exactly what it should;
+ * - anything out of flow in the viewport's own coordinates (`position: fixed`,
+ *   the top layer), which contributes nothing to the document's overflow.
+ */
+
+
+// Subpixel layout rounds rectangles up on boxes that fit exactly.
+const OVERFLOW_TOLERANCE = 1;
+
+const css$J = /* css */ `
+  [data-navi-overflow-x] {
+    outline: 2px dashed #e74c3c;
+    outline-offset: -2px;
+  }
+`;
+
+/**
+ * @param {object} [options]
+ * @param {Element} [options.root=document.body] The box the content must fit
+ *   in — the wrapper carrying `overflow-x: clip`, when there is one.
+ * @param {boolean} [options.highlight=true] Outline the culprits on screen.
+ * @param {(overflows: Array<{element: Element, overflow: number, side: "left"|"right"}>) => void} [options.onDetect]
+ *   Replaces the default console warning.
+ * @returns {() => void} Stops watching.
+ */
+const detectHorizontalOverflow = ({
+  root = document.body,
+  highlight = true,
+  onDetect = warnOverflows,
+} = {}) => {
+  let styleEl = null;
+  if (highlight) {
+    styleEl = document.createElement("style");
+    styleEl.textContent = css$J;
+    document.head.appendChild(styleEl);
+  }
+
+  let highlightedSet = new Set();
+  const detect = () => {
+    const overflows = findOverflows(root);
+    if (highlight) {
+      const nextHighlightedSet = new Set();
+      for (const { element } of overflows) {
+        element.setAttribute("data-navi-overflow-x", "");
+        nextHighlightedSet.add(element);
+      }
+      for (const element of highlightedSet) {
+        if (!nextHighlightedSet.has(element)) {
+          element.removeAttribute("data-navi-overflow-x");
+        }
+      }
+      highlightedSet = nextHighlightedSet;
+    }
+    if (overflows.length) {
+      onDetect(overflows);
+    }
+  };
+
+  // Measuring inside a resize callback is what makes the loop; wait for the
+  // frame that resize produced.
+  let frame = null;
+  const requestDetect = () => {
+    if (frame !== null) {
+      return;
+    }
+    frame = requestAnimationFrame(() => {
+      frame = null;
+      detect();
+    });
+  };
+
+  // Resize catches the window narrowing and the content growing (the root gets
+  // taller); mutations catch a wide element arriving without changing the
+  // root's size.
+  const resizeObserver = new ResizeObserver(requestDetect);
+  resizeObserver.observe(root);
+  const mutationObserver = new MutationObserver(requestDetect);
+  mutationObserver.observe(root, { subtree: true, childList: true });
+  requestDetect();
+
+  return () => {
+    resizeObserver.disconnect();
+    mutationObserver.disconnect();
+    if (frame !== null) {
+      cancelAnimationFrame(frame);
+      frame = null;
+    }
+    for (const element of highlightedSet) {
+      element.removeAttribute("data-navi-overflow-x");
+    }
+    highlightedSet.clear();
+    if (styleEl) {
+      styleEl.remove();
+    }
+  };
+};
+
+const warnOverflows = (overflows) => {
+  for (const { element, overflow, side } of overflows) {
+    console.warn(
+      `${getElementSignature(element)} overflows the page by ${Math.round(
+        overflow,
+      )}px on the ${side}. Look for a width in px, a min-width, or an unbreakable string; if it is meant to be wider than the screen, give it its own "overflow-x: auto".`,
+      element,
+    );
+  }
+};
+
+const findOverflows = (root) => {
+  const rootRect = root.getBoundingClientRect();
+  const rootStyle = getComputedStyle(root);
+  // Only the end side is watched: what sticks out there is what the document
+  // grows to hold, and what inflates the layout viewport. Past the start edge
+  // the content is simply unreachable, and that is where the offscreen
+  // patterns (a label parked at `left: -9999px`) live.
+  const side = rootStyle.direction === "rtl" ? "left" : "right";
+  const overflows = [];
+  const collect = (parentEl) => {
+    for (const el of parentEl.children) {
+      const style = getComputedStyle(el);
+      if (style.display === "none" || style.position === "fixed") {
+        continue;
+      }
+      if (el.hasAttribute("popover") || el.tagName === "DIALOG") {
+        continue;
+      }
+      const rect = el.getBoundingClientRect();
+      if (rect.width === 0 && rect.height === 0) {
+        continue;
+      }
+      const overflow =
+        side === "right"
+          ? rect.right - rootRect.right
+          : rootRect.left - rect.left;
+      if (overflow > OVERFLOW_TOLERANCE) {
+        // The outermost box that sticks out is the one to fix; its children
+        // stick out because it does.
+        overflows.push({ element: el, overflow, side });
+        continue;
+      }
+      // A box holding its own horizontal overflow cannot leak into the page,
+      // whatever it holds — a wide table in its own scroll box is right.
+      if (style.overflowX !== "visible") {
+        continue;
+      }
+      collect(el);
+    }
+  };
+  collect(root);
+  return overflows;
+};
+
 const useFocusGroup = (
   elementRef,
   {
@@ -46956,7 +47220,7 @@ const css$u = /* css */`
        around it does. Its own scroll box must then be transparent to
        layout — otherwise it would cap the list at a height of its own and
        start a second, nested scroll inside the page's. */
-    &[data-scroller="parent"] {
+    &[data-scroller] {
       max-height: none;
       overflow: visible;
 
@@ -46966,6 +47230,14 @@ const css$u = /* css */`
       }
     }
 
+    /* Scrolling with the page means sticking to the viewport, and a FixedBar
+       is in front of that viewport: without the offset a sticky label lands
+       behind the bar. The bar publishes the room it takes (see
+       fixed_bar_space.js) and it is 0px when there is no bar. */
+    &[data-scroller="document"] {
+      --x-list-group-label-top: var(--navi-fixed-bar-space-top, 0px);
+    }
+
     &[data-expand-x] {
       width: 100%;
     }
@@ -47324,7 +47596,7 @@ const css$u = /* css */`
 
     .navi_list_item_group_label {
       position: sticky;
-      top: 0;
+      top: var(--list-group-label-top, var(--x-list-group-label-top, 0px));
       z-index: 1;
       display: block;
       background-color: var(--list-group-label-background-color);
@@ -47567,7 +47839,7 @@ const ListUI = props => {
     baseClassName: "navi_list_container",
     popover: popover,
     "data-horizontal": horizontal ? "" : undefined,
-    "data-scroller": scroller === "self" ? undefined : "parent",
+    "data-scroller": getScrollerAttribute(scroller),
     "data-expand-x": expandX || expand ? "" : undefined,
     "data-expand-y": expandY || expand ? "" : undefined,
     expandX: expandX,
@@ -47826,6 +48098,7 @@ const useListScrollSync = ({
     setScrollerElResolved(current => current === scrollerElNow ? current : scrollerElNow);
   };
   useLayoutEffect(resolveScroller);
+  useStickyScrollportWarning();
 
   // The row the scroll holds onto across a change of geometry, and where it
   // sat when that change was decided. Captured at the two moments the list
@@ -48603,6 +48876,28 @@ const getScrollerViewportRect = scrollerEl => {
   }
   return scrollerEl.getBoundingClientRect();
 };
+const useStickyScrollportWarning = (ref, scroller) => {
+  useRef(false);
+  useLayoutEffect(() => {
+    {
+      return;
+    }
+  });
+};
+
+// The CSS needs to tell "the page scrolls me" from "some box around me
+// scrolls me": only the first one sticks to the viewport, where the fixed bars
+// are.
+const getScrollerAttribute = scroller => {
+  if (scroller === "self") {
+    return undefined;
+  }
+  if (scroller === "document") {
+    return "document";
+  }
+  return "parent";
+};
+
 // scroller="parent": the list virtualizes against the scroll box it lives in
 // instead of one of its own. Which box that is can only be measured, and a
 // measurement holds for the geometry it was taken on — see resolveScroller in
@@ -52047,6 +52342,10 @@ const css$p = /* css */`
        keyboard here (see navi-focus-delegate below). */
     outline-color: var(--navi-focus-outline-color);
     outline-offset: 0px;
+    /* No grey flash under a finger: what a press does is said by the chevron's
+       own background, and the browser's rectangle is drawn square over corners
+       that are round. Inherited, so the three pieces inside get it too. */
+    -webkit-tap-highlight-color: var(--navi-control-tap-highlight-color);
   }
   /* The middle holds the keyboard, and this box wears its ring: whatever is in
      there fills it, so a ring of its own would be drawn a pixel inside this
@@ -52173,7 +52472,12 @@ const css$p = /* css */`
     border-radius: 0;
     cursor: pointer;
   }
-  .navi_picker_spin > .navi_picker_spin_way_out:hover {
+  /* Said as data-hover rather than :hover: a touch browser synthesizes the
+     enter and never the leave, so a CSS :hover would stay grey under the last
+     chevron pressed until something else was touched. What tracks it (see
+     pseudo_styles.js) knows there is no hover on such a device and simply does
+     not set the attribute. */
+  .navi_picker_spin > .navi_picker_spin_way_out[data-hover] {
     background: color-mix(in srgb, currentColor 8%, transparent);
   }
   /* Nothing that way: still there, still pressable — pressing it is how one
@@ -52199,22 +52503,28 @@ const css$p = /* css */`
      of a rounded spin is rounded there too, and nowhere else — the two corners
      it does not own stay at the 0 above. Said with inherit rather than clipped
      away with overflow, which would cut the focus ring of the very button it
-     rounds. */
+     rounds.
+     Which chevron is which is asked of the chevron itself (data-way-out) rather
+     than of its place among its siblings: the loading outline is a <span> too
+     and it is written first, so :first-of-type named IT and the chevron at the
+     start went unrounded. */
   .navi_picker_spin:not([data-vertical])
-    > .navi_picker_spin_way_out:first-of-type {
+    > .navi_picker_spin_way_out[data-way-out="start"] {
     border-start-start-radius: inherit;
     border-end-start-radius: inherit;
   }
   .navi_picker_spin:not([data-vertical])
-    > .navi_picker_spin_way_out:last-of-type {
+    > .navi_picker_spin_way_out[data-way-out="end"] {
     border-start-end-radius: inherit;
     border-end-end-radius: inherit;
   }
-  .navi_picker_spin[data-vertical] > .navi_picker_spin_way_out:first-of-type {
+  .navi_picker_spin[data-vertical]
+    > .navi_picker_spin_way_out[data-way-out="start"] {
     border-start-start-radius: inherit;
     border-start-end-radius: inherit;
   }
-  .navi_picker_spin[data-vertical] > .navi_picker_spin_way_out:last-of-type {
+  .navi_picker_spin[data-vertical]
+    > .navi_picker_spin_way_out[data-way-out="end"] {
     border-end-end-radius: inherit;
     border-end-start-radius: inherit;
   }
@@ -52455,6 +52765,7 @@ const Spin = ({
   const wayOut = atStart => {
     const isNext = atStart ? startIsNext : !startIsNext;
     return jsx(WayOut, {
+      atStart: atStart,
       unavailableMessage: wayOutMessage(atStart ? startAllowed : endAllowed, isNext ? "spin.nothing_after" : "spin.nothing_before"),
       label: isNext ? nextLabel ?? naviI18n("spin.next") : previousLabel ?? naviI18n("spin.previous"),
       onPress: e => {
@@ -52632,6 +52943,7 @@ const Spin = ({
 // the container's own tabIndex, or the field's), where the arrows already mean
 // this.
 const WayOut = ({
+  atStart,
   commandFor,
   unavailableMessage,
   label,
@@ -52640,6 +52952,17 @@ const WayOut = ({
 }) => jsx(Box, {
   as: "span",
   baseClassName: "navi_picker_spin_way_out"
+  // Which end of the box it sits in, said by the chevron rather than read
+  // from its place among its siblings: that is what the corners it is
+  // rounded by are keyed on (see the CSS above).
+  ,
+
+  "data-way-out": atStart ? "start" : "end"
+  // Tracked rather than left to CSS :hover, which stays on after a tap on a
+  // touch device (see the CSS above).
+  ,
+
+  pseudoClasses: WAY_OUT_PSEUDO_CLASSES
   // Announced as a button because that is what it is to whoever cannot see
   // the chevron — and marked unavailable rather than removed when there is
   // nothing that way, so it keeps its place.
@@ -52691,6 +53014,7 @@ const WayOut = ({
   })
 });
 const PICKER_SPIN_PSEUDO_CLASSES = [":hover", ":focus-visible"];
+const WAY_OUT_PSEUDO_CLASSES = [":hover"];
 
 // A padding written on this box would sit between its border and the chevrons,
 // which are meant to reach the corners they are rounded by — so each padding
@@ -62662,5 +62986,5 @@ const UserSvg = () => jsx("svg", {
   })
 });
 
-export { ActionRenderer, ActiveKeyboardShortcuts, Address, Badge, BadgeCount, BadgeList, Binder, Box, Button, ButtonCopyToClipboard, Caption, CardLayout, CheckSvg, CheckboxGroup, CloseSvg, Code, Col, Colgroup, Color, ConstructionSvg, ControlGroup, DaySpin, Details, Dialog, Editable, ErrorBoundary, ErrorBoundaryContext, ExclamationSvg, EyeClosedSvg, EyeSvg, Field, FixedBar, Form, Group, Head, HeartSvg, HomeSvg, Icon, Image, Input, InputDuration, Interpolate, Label, Link, LinkAnchorSvg, LinkBlankTargetSvg, LinkCurrentSvg, List, ListItem, ListItemGroup, ListItems, Loading, LoadingDotsSvg, LoadingIndicator, LoadingIndicatorFluid, LoadingOutline, MessageBox, Meter, Nav, NaviDebug, NumberSpin, Paragraph, Picker, Popover, Popup, Quantity, RadioGroup, Route, RowNumberCol, RowNumberTableCell, SVGMaskOverlay, SearchSvg, SelectableInput, SelectionContext, Separator, SettingsSvg, SidePanel, Slide, SlideContainer, Spin, StarSvg, SummaryMarker, Svg, Table, TableCell, Tbody, Text, TextBox, Textarea, TextareaCharCount, Thead, Time, Title, Tr, UITransition, Unit, UserSvg, ViewportLayout, Wheel, WheelGroup, WheelItem, actionRunEffect, anyMatchingRouteSignal, applySearch, arraySignalMembership, coarsePointerSignal, compareTwoJsValues, createAction, createAvailableConstraint, createRequestCanceller, createSearch, createSelectionKeyboardShortcuts, createSlot, defineNaviConfirmPopupOptions, enableDebugActions, enableDebugOnDocumentLoading, ensureDocumentStartViewTransition, filterTableSelection, formatDatetime, formatDay, formatDayRelative, formatMonth, formatNumber, formatTime, formatTimeRelative, getNowHours, getNowHoursRoundedToStep, interpolateText, isCellSelected, isColumnSelected, isRowSelected, isToday, languagesSignal, localStorageSignal, moveArrayItemByIndex, navBack, navForward, navIntegratedVia, navTo, naviI18n, openCallout, rawUrlPart, registerGlobalConstraint, reload, rerunActions, resource, route, routeAction, setBaseUrl, setPreferredLanguage, setSupportedLanguages, setupRoutes, stateSignal, stopLoad, stringifyTableSelectionValue, swapArrayItemByIndex, syncOwnedResourceToSignals, syncResourceToSignals, updateActions, useActionStatus, useArraySignalMembership, useAsyncData, useCalloutRequestClose, useCancelPrevious, useCellGridFromRows, useConstraintValidityState, useDependenciesDiff, useDisplayedLayoutEffect, useDocumentResource, useDocumentState, useDocumentUrl, useEditionController, useFocusGroup, useInputGroup, useKeyboardShortcuts, useNavState, useOrderedColumns, usePopupMode, useRouteStatus, useRunOnMount, useSearchText, useSelectableElement, useSelectionController, useSignalSync, useSlideValue, useStateArray, useTitleLevel, useUrlSearchParam, valueInLocalStorage, windowWidthSignal };
+export { ActionRenderer, ActiveKeyboardShortcuts, Address, Badge, BadgeCount, BadgeList, Binder, Box, Button, ButtonCopyToClipboard, Caption, CardLayout, CheckSvg, CheckboxGroup, CloseSvg, Code, Col, Colgroup, Color, ConstructionSvg, ControlGroup, DaySpin, Details, Dialog, Editable, ErrorBoundary, ErrorBoundaryContext, ExclamationSvg, EyeClosedSvg, EyeSvg, Field, FixedBar, Form, Group, Head, HeartSvg, HomeSvg, Icon, Image, Input, InputDuration, Interpolate, Label, Link, LinkAnchorSvg, LinkBlankTargetSvg, LinkCurrentSvg, List, ListItem, ListItemGroup, ListItems, Loading, LoadingDotsSvg, LoadingIndicator, LoadingIndicatorFluid, LoadingOutline, MessageBox, Meter, Nav, NaviDebug, NumberSpin, Paragraph, Picker, Popover, Popup, Quantity, RadioGroup, Route, RowNumberCol, RowNumberTableCell, SVGMaskOverlay, SearchSvg, SelectableInput, SelectionContext, Separator, SettingsSvg, SidePanel, Slide, SlideContainer, Spin, StarSvg, SummaryMarker, Svg, Table, TableCell, Tbody, Text, TextBox, Textarea, TextareaCharCount, Thead, Time, Title, Tr, UITransition, Unit, UserSvg, ViewportLayout, Wheel, WheelGroup, WheelItem, actionRunEffect, anyMatchingRouteSignal, applySearch, arraySignalMembership, coarsePointerSignal, compareTwoJsValues, createAction, createAvailableConstraint, createRequestCanceller, createSearch, createSelectionKeyboardShortcuts, createSlot, defineNaviConfirmPopupOptions, detectHorizontalOverflow, enableDebugActions, enableDebugOnDocumentLoading, ensureDocumentStartViewTransition, filterTableSelection, formatDatetime, formatDay, formatDayRelative, formatMonth, formatNumber, formatTime, formatTimeRelative, getNowHours, getNowHoursRoundedToStep, interpolateText, isCellSelected, isColumnSelected, isRowSelected, isToday, languagesSignal, localStorageSignal, moveArrayItemByIndex, navBack, navForward, navIntegratedVia, navTo, naviI18n, openCallout, rawUrlPart, registerGlobalConstraint, reload, rerunActions, resource, route, routeAction, setBaseUrl, setPreferredLanguage, setSupportedLanguages, setupRoutes, stateSignal, stopLoad, stringifyTableSelectionValue, swapArrayItemByIndex, syncOwnedResourceToSignals, syncResourceToSignals, updateActions, useActionStatus, useArraySignalMembership, useAsyncData, useCalloutRequestClose, useCancelPrevious, useCellGridFromRows, useConstraintValidityState, useDependenciesDiff, useDisplayedLayoutEffect, useDocumentResource, useDocumentState, useDocumentUrl, useEditionController, useFocusGroup, useInputGroup, useKeyboardShortcuts, useNavState, useOrderedColumns, usePopupMode, useRouteStatus, useRunOnMount, useSearchText, useSelectableElement, useSelectionController, useSignalSync, useSlideValue, useStateArray, useTitleLevel, useUrlSearchParam, valueInLocalStorage, windowWidthSignal };
 //# sourceMappingURL=jsenv_navi.js.map