@jsenv/navi 0.29.155 → 0.29.157

package/dist/jsenv_navi.js

@@ -888,6 +888,157 @@ const isPlainObject$2 = obj => {
   return Object.getPrototypeOf(obj) === proto || Object.getPrototypeOf(obj) === null;
 };
 
+const isSignal = (value) => {
+  return getSignalType(value) !== null;
+};
+
+const BRAND_SYMBOL = Symbol.for("preact-signals");
+const getSignalType = (value) => {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+
+  if (value.brand !== BRAND_SYMBOL) {
+    return null;
+  }
+
+  if (typeof value._fn === "function") {
+    return "computed";
+  }
+
+  return "signal";
+};
+
+const MAX_ENTRIES = 5;
+
+const stringifyForDisplay = (
+  value,
+  maxDepth = 2,
+  currentDepth = 0,
+  options = {},
+) => {
+  const { asFunctionArgs = false } = options;
+  const indent = "  ".repeat(currentDepth);
+  const nextIndent = "  ".repeat(currentDepth + 1);
+
+  if (currentDepth >= maxDepth) {
+    return typeof value === "object" && value !== null
+      ? "[Object]"
+      : String(value);
+  }
+
+  if (value === null) {
+    return "null";
+  }
+  if (value === undefined) {
+    return "undefined";
+  }
+  if (typeof value === "string") {
+    return `"${value}"`;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (typeof value === "function") {
+    return `[Function ${value.name || "anonymous"}]`;
+  }
+  if (value instanceof Date) {
+    return `Date(${value.toISOString()})`;
+  }
+  if (value instanceof RegExp) {
+    return value.toString();
+  }
+
+  if (Array.isArray(value)) {
+    const openBracket = asFunctionArgs ? "(" : "[";
+    const closeBracket = asFunctionArgs ? ")" : "]";
+
+    if (value.length === 0) return `${openBracket}${closeBracket}`;
+
+    // Display arrays with only one element on a single line
+    if (value.length === 1) {
+      const item = stringifyForDisplay(
+        value[0],
+        maxDepth,
+        currentDepth + 1,
+        // Remove asFunctionArgs for nested calls
+        { ...options, asFunctionArgs: false },
+      );
+      return `${openBracket}${item}${closeBracket}`;
+    }
+
+    if (value.length > MAX_ENTRIES) {
+      const preview = value
+        .slice(0, MAX_ENTRIES)
+        .map(
+          (v) =>
+            `${nextIndent}${stringifyForDisplay(v, maxDepth, currentDepth + 1, { ...options, asFunctionArgs: false })}`,
+        );
+      return `${openBracket}\n${preview.join(",\n")},\n${nextIndent}...${value.length - MAX_ENTRIES} more\n${indent}${closeBracket}`;
+    }
+
+    const items = value.map(
+      (v) =>
+        `${nextIndent}${stringifyForDisplay(v, maxDepth, currentDepth + 1, { ...options, asFunctionArgs: false })}`,
+    );
+    return `${openBracket}\n${items.join(",\n")}\n${indent}${closeBracket}`;
+  }
+
+  if (typeof value === "object") {
+    const signalType = getSignalType(value);
+    if (signalType) {
+      const signalValue = value.peek();
+      const prefix = signalType === "computed" ? "computed" : "signal";
+      return `${prefix}(${stringifyForDisplay(signalValue, maxDepth, currentDepth, { ...options, asFunctionArgs: false })})`;
+    }
+
+    const entries = Object.entries(value);
+    if (entries.length === 0) return "{}";
+
+    // ✅ Inclure les clés avec valeurs undefined/null
+    const allEntries = [];
+    for (const [key, val] of entries) {
+      allEntries.push([key, val]);
+    }
+
+    // Ajouter les clés avec undefined (que Object.entries omet)
+    const descriptor = Object.getOwnPropertyDescriptors(value);
+    for (const [key, desc] of Object.entries(descriptor)) {
+      if (desc.value === undefined && !entries.some(([k]) => k === key)) {
+        allEntries.push([key, undefined]);
+      }
+    }
+
+    // Display objects with only one key on a single line
+    if (allEntries.length === 1) {
+      const [key, val] = allEntries[0];
+      const valueStr = stringifyForDisplay(val, maxDepth, currentDepth + 1, {
+        ...options,
+        asFunctionArgs: false,
+      });
+      return `{ ${key}: ${valueStr} }`;
+    }
+
+    if (allEntries.length > MAX_ENTRIES) {
+      const preview = allEntries
+        .slice(0, MAX_ENTRIES)
+        .map(
+          ([k, v]) =>
+            `${nextIndent}${k}: ${stringifyForDisplay(v, maxDepth, currentDepth + 1, { ...options, asFunctionArgs: false })}`,
+        );
+      return `{\n${preview.join(",\n")},\n${nextIndent}...${allEntries.length - MAX_ENTRIES} more\n${indent}}`;
+    }
+
+    const pairs = allEntries.map(
+      ([k, v]) =>
+        `${nextIndent}${k}: ${stringifyForDisplay(v, maxDepth, currentDepth + 1, { ...options, asFunctionArgs: false })}`,
+    );
+    return `{\n${pairs.join(",\n")}\n${indent}}`;
+  }
+
+  return String(value);
+};
+
 /*
  * Deep structural equality for arbitrary JS values — what `===` can't do but this
  * codebase constantly needs: memoization cache keys ({ id: 1 } equal to { id: 1 }),
@@ -898,9 +1049,9 @@ const isPlainObject$2 = obj => {
  * "wrong" for equality purposes: NaN equals NaN, Date compared by time value,
  * cycles don't loop (a set of the pairs being compared guards circular refs),
  * and same-type is required
- * before descending. Functions, and objects with nothing enumerable to compare
- * (a Set, a Map, an element, a URL), are equal by reference only — nothing in
- * them says whether two are "the same". Cheap paths run first: reference
+ * before descending. Functions, signals, and objects with nothing enumerable to
+ * compare (a Set, a Map, an element, a URL), are equal by reference only —
+ * nothing in them says whether two are "the same". Cheap paths run first: reference
  * equality, then the identity short-circuit below, then array length before
  * element-by-element.
  *
@@ -918,6 +1069,7 @@ const isPlainObject$2 = obj => {
  *   compareTwoJsValues(a, b); // true immediately, no property walk
  */
 
+
 // Marks objects with a conceptual identity that transcends reference equality —
 // see the file comment. Symbol.for keeps it one shared symbol across modules.
 const SYMBOL_IDENTITY = Symbol.for("navi_object_identity");
@@ -1060,6 +1212,15 @@ const compareTwoJsValues = (
     if (aIsDate) {
       return a.getTime() === b.getTime();
     }
+    // A signal is a source of truth, not a value: two of them holding the same
+    // thing right now say nothing about the next tick, and one may change while
+    // the other does not. Their internals (the current value, a version
+    // counter) are enumerable, so without this they would be walked and two
+    // unrelated signals would pass for one — a params signal owned by one
+    // screen would then be handed the action bound to another's.
+    if (isSignal(a) || isSignal(b)) {
+      return false;
+    }
     const aKeys = Object.keys(a);
     const bKeys = Object.keys(b);
     if (aKeys.length !== bKeys.length) {
@@ -1142,159 +1303,37 @@ const debounceSignal = (
     clearTimeout(timeoutId);
     debouncedSignal.value = latestValue;
   };
+  // Whoever reads the debounced value gets the previous one during the delay,
+  // with nothing saying a newer one is on its way. This says it.
+  debouncedSignal.settlingSignal = computed(() => {
+    return !compareTwoJsValues(signalToDebounce.value, debouncedSignal.value);
+  });
 
   return debouncedSignal;
 };
 
-const isSignal = (value) => {
-  return getSignalType(value) !== null;
-};
-
-const BRAND_SYMBOL = Symbol.for("preact-signals");
-const getSignalType = (value) => {
-  if (!value || typeof value !== "object") {
-    return null;
-  }
-
-  if (value.brand !== BRAND_SYMBOL) {
-    return null;
-  }
-
-  if (typeof value._fn === "function") {
-    return "computed";
-  }
-
-  return "signal";
-};
+const debouncedSignalCache = new WeakMap();
 
-const MAX_ENTRIES = 5;
-
-const stringifyForDisplay = (
-  value,
-  maxDepth = 2,
-  currentDepth = 0,
-  options = {},
-) => {
-  const { asFunctionArgs = false } = options;
-  const indent = "  ".repeat(currentDepth);
-  const nextIndent = "  ".repeat(currentDepth + 1);
-
-  if (currentDepth >= maxDepth) {
-    return typeof value === "object" && value !== null
-      ? "[Object]"
-      : String(value);
-  }
-
-  if (value === null) {
-    return "null";
-  }
-  if (value === undefined) {
-    return "undefined";
-  }
-  if (typeof value === "string") {
-    return `"${value}"`;
-  }
-  if (typeof value === "number" || typeof value === "boolean") {
-    return String(value);
-  }
-  if (typeof value === "function") {
-    return `[Function ${value.name || "anonymous"}]`;
-  }
-  if (value instanceof Date) {
-    return `Date(${value.toISOString()})`;
-  }
-  if (value instanceof RegExp) {
-    return value.toString();
-  }
-
-  if (Array.isArray(value)) {
-    const openBracket = asFunctionArgs ? "(" : "[";
-    const closeBracket = asFunctionArgs ? ")" : "]";
-
-    if (value.length === 0) return `${openBracket}${closeBracket}`;
-
-    // Display arrays with only one element on a single line
-    if (value.length === 1) {
-      const item = stringifyForDisplay(
-        value[0],
-        maxDepth,
-        currentDepth + 1,
-        // Remove asFunctionArgs for nested calls
-        { ...options, asFunctionArgs: false },
-      );
-      return `${openBracket}${item}${closeBracket}`;
-    }
-
-    if (value.length > MAX_ENTRIES) {
-      const preview = value
-        .slice(0, MAX_ENTRIES)
-        .map(
-          (v) =>
-            `${nextIndent}${stringifyForDisplay(v, maxDepth, currentDepth + 1, { ...options, asFunctionArgs: false })}`,
-        );
-      return `${openBracket}\n${preview.join(",\n")},\n${nextIndent}...${value.length - MAX_ENTRIES} more\n${indent}${closeBracket}`;
-    }
-
-    const items = value.map(
-      (v) =>
-        `${nextIndent}${stringifyForDisplay(v, maxDepth, currentDepth + 1, { ...options, asFunctionArgs: false })}`,
-    );
-    return `${openBracket}\n${items.join(",\n")}\n${indent}${closeBracket}`;
+/**
+ * The one debounced signal for a given source and delay.
+ *
+ * Two callers asking the same question of the same signal must wait on the same
+ * answer: a debounced signal per caller is a timer per caller, and the actions
+ * derived from them are then several instances of what is one request.
+ */
+const getDebouncedSignal = (signalToDebounce, delay) => {
+  let byDelay = debouncedSignalCache.get(signalToDebounce);
+  if (!byDelay) {
+    byDelay = new Map();
+    debouncedSignalCache.set(signalToDebounce, byDelay);
   }
-
-  if (typeof value === "object") {
-    const signalType = getSignalType(value);
-    if (signalType) {
-      const signalValue = value.peek();
-      const prefix = signalType === "computed" ? "computed" : "signal";
-      return `${prefix}(${stringifyForDisplay(signalValue, maxDepth, currentDepth, { ...options, asFunctionArgs: false })})`;
-    }
-
-    const entries = Object.entries(value);
-    if (entries.length === 0) return "{}";
-
-    // ✅ Inclure les clés avec valeurs undefined/null
-    const allEntries = [];
-    for (const [key, val] of entries) {
-      allEntries.push([key, val]);
-    }
-
-    // Ajouter les clés avec undefined (que Object.entries omet)
-    const descriptor = Object.getOwnPropertyDescriptors(value);
-    for (const [key, desc] of Object.entries(descriptor)) {
-      if (desc.value === undefined && !entries.some(([k]) => k === key)) {
-        allEntries.push([key, undefined]);
-      }
-    }
-
-    // Display objects with only one key on a single line
-    if (allEntries.length === 1) {
-      const [key, val] = allEntries[0];
-      const valueStr = stringifyForDisplay(val, maxDepth, currentDepth + 1, {
-        ...options,
-        asFunctionArgs: false,
-      });
-      return `{ ${key}: ${valueStr} }`;
-    }
-
-    if (allEntries.length > MAX_ENTRIES) {
-      const preview = allEntries
-        .slice(0, MAX_ENTRIES)
-        .map(
-          ([k, v]) =>
-            `${nextIndent}${k}: ${stringifyForDisplay(v, maxDepth, currentDepth + 1, { ...options, asFunctionArgs: false })}`,
-        );
-      return `{\n${preview.join(",\n")},\n${nextIndent}...${allEntries.length - MAX_ENTRIES} more\n${indent}}`;
-    }
-
-    const pairs = allEntries.map(
-      ([k, v]) =>
-        `${nextIndent}${k}: ${stringifyForDisplay(v, maxDepth, currentDepth + 1, { ...options, asFunctionArgs: false })}`,
-    );
-    return `{\n${pairs.join(",\n")}\n${indent}}`;
+  const existing = byDelay.get(delay);
+  if (existing) {
+    return existing;
   }
-
-  return String(value);
+  const debouncedSignal = debounceSignal(signalToDebounce, { delay });
+  byDelay.set(delay, debouncedSignal);
+  return debouncedSignal;
 };
 
 /**
@@ -3157,6 +3196,10 @@ const SYMBOL_OBJECT_SIGNAL = Symbol.for("navi_object_signal");
  * routing or lists.
  */
 
+// Params waiting to settle exist only under a debounced binding; every other
+// action answers "no" so nobody has to check whether it can be asked.
+const NOT_SETTLING_SIGNAL = signal(false);
+
 let DEBUG$2 = false;
 const enableDebugActions = () => {
   DEBUG$2 = true;
@@ -3816,12 +3859,53 @@ const createAction = (callback, rootOptions = {}) => {
         ...options,
       });
     };
+    /**
+     * The action instance for these params.
+     *
+     * @param {any} newParamsOrSignal - params, or a signal holding them (the
+     *   result then retargets itself as the signal changes), or an object whose
+     *   values may be signals.
+     * @param {object} [options]
+     * @param {number} [options.debounce] - milliseconds the params must stay
+     *   stable before the instance follows them. What it buys is a screen that
+     *   owns its params — a search box, a picker — asking one question instead
+     *   of one per keystroke, without an effect: the binding IS the delay.
+     *   Only for a signal; params that cannot change have nothing to settle.
+     *   During the delay the instance is still the previous one, holding the
+     *   previous answer — `paramsSettlingSignal` is what says a newer one is
+     *   coming, and `useAsyncData(action, { loading: true })` reads it.
+     */
     const bindParams = (newParamsOrSignal, options = {}) => {
+      const { debounce, ...optionsWithoutDebounce } = options;
+      if (debounce) {
+        if (!isSignal(newParamsOrSignal)) {
+          console.warn(
+            `bindParams({ debounce }) expects a signal, received ${typeof newParamsOrSignal}: params that cannot change have nothing to settle.`,
+          );
+        } else {
+          // The delay lives in a signal derived from theirs, one per (signal,
+          // delay): the cache below then keys on it like on any other signal,
+          // so two call sites asking the same question with the same delay get
+          // the one instance, and two different delays get two.
+          const debouncedParamsSignal = getDebouncedSignal(
+            newParamsOrSignal,
+            debounce,
+          );
+          return bindParams(debouncedParamsSignal, {
+            ...optionsWithoutDebounce,
+            syncParams: debouncedParamsSignal.flush,
+            paramsSettlingSignal: debouncedParamsSignal.settlingSignal,
+          });
+        }
+      }
       const existingChildAction = childActionWeakMap.get(newParamsOrSignal);
       if (existingChildAction) {
         return existingChildAction;
       }
-      const childAction = _bindParams(newParamsOrSignal, options);
+      const childAction = _bindParams(
+        newParamsOrSignal,
+        optionsWithoutDebounce,
+      );
       childActionWeakMap.set(newParamsOrSignal, childAction);
       if (childAction !== action) {
         // binding that added nothing resolves to the action itself; it must
@@ -3964,6 +4048,7 @@ const createAction = (callback, rootOptions = {}) => {
       },
 
       paramsSignal,
+      paramsSettlingSignal: NOT_SETTLING_SIGNAL,
       runningStateSignal,
       isPrerunSignal,
       valueSignal,
@@ -4297,6 +4382,7 @@ const createActionProxyFromSignal = (
     inheritData = true,
     onChange,
     syncParams,
+    paramsSettlingSignal = NOT_SETTLING_SIGNAL,
   } = {},
 ) => {
   const actionTargetChangeCallbackSet = new Set();
@@ -4473,6 +4559,7 @@ const createActionProxyFromSignal = (
     meta: action.meta,
 
     paramsSignal: proxyParamsSignal,
+    paramsSettlingSignal,
     isPrerunSignal: proxySignal("isPrerunSignal", "isPrerun"),
     runningStateSignal: proxySignal("runningStateSignal", "runningState"),
     errorSignal: proxySignal("errorSignal", "error"),
@@ -4629,7 +4716,9 @@ const isPlainObject = (obj) => {
  * @param {number} [options.debounce] - When set, the action is only run once the derived params
  *   have been stable for this many milliseconds. Useful to avoid firing a backend call on every
  *   keystroke: set `debounce: 500` and the request is sent only after the user stops interacting
- *   with the filters for 500 ms.
+ *   with the filters for 500 ms. During that delay the action still holds the previous answer;
+ *   `action.paramsSettlingSignal` is what says a newer one is coming, and
+ *   `useAsyncData(action, { loading: true })` reads it.
  *
  *   Example — auto-refresh a result list while the user tweaks filters:
  *   ```js
@@ -4659,7 +4748,7 @@ const actionRunEffect = (
   if (typeof action === "function") {
     action = createAction(action);
   }
-  let actionParamsSignal = computed(() => {
+  const actionParamsSignal = computed(() => {
     const params = deriveActionParamsFromSignals();
     action.debug(
       `Derived params for action "${action}": ${stringifyForDisplay(params)}`,
@@ -4677,14 +4766,8 @@ const actionRunEffect = (
     }
     return params;
   });
-  if (debounce) {
-    actionParamsSignal = debounceSignal(actionParamsSignal, {
-      delay: debounce,
-    });
-  }
-
   const actionRunnedByThisEffect = action.bindParams(actionParamsSignal, {
-    syncParams: debounce ? actionParamsSignal.flush : undefined,
+    debounce,
     onChange: (actionTarget, actionTargetPrevious, { explicitRunIntent }) => {
       if (explicitRunIntent) {
         // The caller already issued an explicit run/rerun/prerun/reset/abort —
@@ -5432,6 +5515,11 @@ const CONTROL_ATTRIBUTE_SET = new Set([
   "spellcheck",
   "autoCorrect",
   "aria-controls",
+  // The name goes where the role is: the root box has none, so an aria-label
+  // left on it names nothing at all, while the host is what the user focuses
+  // and what a screen reader announces (and what getByRole({ name }) reads).
+  "aria-label",
+  "aria-labelledby",
   "tabIndex",
   "command",
   "commandFor",
@@ -6419,6 +6507,11 @@ const css$12 = /* css */`
  * @param {Object} options - Configuration options
  * @param {HTMLElement} [options.anchorElement] - Element the callout should follow. If not provided or too big, callout will be centered in viewport
  * @param {string} [options.status=""] - Callout status: "info" | "warning" | "error" | "success"
+ * @param {string} [options.testId] - `data-testid` on the callout element. The callout is
+ *   drawn by navi, so nothing the caller renders can carry the name a test needs — same
+ *   situation as a picker's `popupTestId` (see docs/testid.md). A role is already there
+ *   for free (`status`/`alert`); reach for this when the role is not enough to tell two
+ *   callouts apart.
  * @param {Function} [options.onClose] - Callback when callout is closed
  * @param {boolean} [options.closeOnClickOutside] - Whether to close on outside clicks (defaults to true for "info" status)
  * @param {boolean} [options.icon=true] - Whether the status icon is shown beside the message.
@@ -6465,6 +6558,7 @@ const openCallout = (message, {
   // "success" - positive feedback (e.g., "Changes saved successfully")
   // "" - neutral information
   status = "",
+  testId,
   onClose,
   closeOnClickOutside = status === "info",
   closeOnFocusLeave = closeOnClickOutside,
@@ -6642,6 +6736,15 @@ const openCallout = (message, {
         calloutElement.removeAttribute("data-icon");
       }
     }
+    if (Object.hasOwn(options, "testId")) {
+      // Per message, like the cross below: a callout is a slot several things
+      // speak through, and the one speaking is what a test is looking at.
+      if (options.testId) {
+        calloutElement.setAttribute("data-testid", options.testId);
+      } else {
+        calloutElement.removeAttribute("data-testid");
+      }
+    }
     if (Object.hasOwn(options, "closeButton")) {
       // Per message rather than per callout: what replaces a message (a
       // constraint taking over a tooltip's callout) brings its own cross back.
@@ -7042,6 +7145,7 @@ const openCallout = (message, {
   }
   update(message, {
     status,
+    testId,
     icon,
     closeButton
   });
@@ -7698,7 +7802,7 @@ const generateSvgWithoutArrow = (width, height) => {
  *
  * Usage:
  *   const myToken = createOpenToken();
- *   calloutManager.addOpenToken(myToken, { message, status, anchorElement, event, skipFocus, onClose });
+ *   calloutManager.addOpenToken(myToken, { message, status, testId, anchorElement, event, skipFocus, onClose });
  *   calloutManager.removeOpenToken(myToken, event);
  *   calloutManager.requestCloseCallout(event, debugReason); // force-close all
  *   calloutManager.callout  // current open callout or null
@@ -7744,6 +7848,7 @@ const createCalloutManager = (
         const [, remainingTokenData] = tokens.entries().next().value;
         callout.update(remainingTokenData.message, {
           status: remainingTokenData.status,
+          testId: remainingTokenData.testId,
           icon: remainingTokenData.icon,
           closeButton: remainingTokenData.closeButton,
         });
@@ -7770,6 +7875,7 @@ const createCalloutManager = (
     {
       message,
       status,
+      testId,
       icon,
       closeButton,
       anchorElement,
@@ -7784,12 +7890,13 @@ const createCalloutManager = (
     }
     const calloutOptions = {
       status,
+      testId,
       icon,
       closeButton,
       closeOnClickOutside: status !== "error",
     };
 
-    tokens.set(token, { message, status, icon, closeButton, onClose });
+    tokens.set(token, { message, status, testId, icon, closeButton, onClose });
     if (callout) {
       callout.update(message, calloutOptions);
       return;
@@ -15150,8 +15257,12 @@ const createResource = (
     idKey,
     uniqueKeys,
 
+    // Reactive reads, not hooks: they subscribe the render that calls them to
+    // the store's array signal. Nothing hook-shaped inside, so a loop or a
+    // condition is fine. `useAllByIds` skips the ids the store does not hold.
     useArray: () => store.arraySignal.value,
     useById: (id) => store.select(idKey, id),
+    useAllByIds: (idArray) => store.selectAll(idArray),
 
     withParams: undefined,
     one: undefined,
@@ -17350,14 +17461,34 @@ const useActionAsyncData = (action, {
       }
       setTick(n => n + 1);
     });
+    // A debounced binding waits before it retargets, so nothing above changes
+    // while the delay runs — but what is on screen is already out of date.
+    let settlingNotificationIsInitial = true;
+    const unsubscribeFromParamsSettling = action.paramsSettlingSignal.subscribe(() => {
+      if (settlingNotificationIsInitial) {
+        settlingNotificationIsInitial = false;
+        return;
+      }
+      setTick(n => n + 1);
+    });
     return () => {
       unsubscribeFromRunningState();
       unsubscribeFromData();
+      unsubscribeFromParamsSettling();
     };
     // Bound to the action, not to the mount: params given as a plain object
     // make another action instance, and the component would otherwise stay
     // subscribed to the state of the one it no longer reads.
   }, [action]);
+
+  // The params moved and the run has not started: under a debounce the action
+  // is still the previous one, COMPLETED with the previous answer. There is no
+  // run to await yet, so nothing can be suspended on — but a component drawing
+  // its own wait can say the answer on screen is on its way out, which is the
+  // whole reason it asked for `loading`.
+  if (loadingEffect === "use" && runningState !== FAILED && action.paramsSettlingSignal.peek()) {
+    return [action.dataSignal.peek(), true, undefined];
+  }
   if (runningState === COMPLETED) {
     return [action.dataSignal.peek(), false, undefined];
   }
@@ -28081,8 +28212,10 @@ const RouteTransitionArea = ({
  * @param {object} to - same forms. Going from `from` to `to` plays forward,
  *   the reverse plays back — unless the reverse is written as a relation of
  *   its own, which then owns that way (a movement of its own, or `"none"` for
- *   a plain cut). A change between two pages no relation was written for plays
- *   nothing.
+ *   a plain cut). Written with the SAME movement it owns that way all the
+ *   same, so both crossings play forward and the pair can never say "back":
+ *   that pair is warned about. A change between two pages no relation was
+ *   written for plays nothing.
  * @param {string|{type?: string, duration?: number|string}} [transition] -
  *   what plays: a type name, or `{ type, duration }` to also say how long
  *   (`--navi-route-transition-duration` says it for everyone otherwise).
@@ -28131,6 +28264,7 @@ const defineRouteTransition = (from, to, transition) => {
     type,
     duration
   };
+  warnAboutBothWaysWritten(relation);
   relations.push(relation);
   rebuildWatcher();
   return () => {
@@ -28725,6 +28859,38 @@ const currentPageIndex$1 = pages => {
   }
   return currentIndex;
 };
+
+// Both ways of a pair written with the SAME movement. The exact way travelled
+// is searched before any reverse (see findRelation), so each way then finds
+// its own relation and BOTH play forward: the pair loses the one thing a
+// direction is for. That is not a resolution to fix — it is what makes
+// reciprocity a default — it is a definition with no reading under which it is
+// what the author meant, so it is said here, where both relations are known.
+// Narrow on purpose: a different type is the asymmetry the reverse exists for,
+// "none" is silence said out loud, and a different duration is a way out taken
+// slower.
+const warnAboutBothWaysWritten = ({
+  from,
+  to,
+  type,
+  duration
+}) => {
+  const reverse = relations.find(candidate => samePage$1(candidate.from, to) && samePage$1(candidate.to, from));
+  if (!reverse) {
+    return;
+  }
+  if (reverse.type !== type || reverse.duration !== duration) {
+    return;
+  }
+  if (type === "none") {
+    return;
+  }
+  // The one already written is named first: that is the order the application
+  // wrote them in, and the order it will find them in to fix them.
+  const written = `${describePage(reverse.from)} → ${describePage(reverse.to)}`;
+  const added = `${describePage(from)} → ${describePage(to)}`;
+  warnOnce(`both-ways-written:${written}|${added}`, `${written} and ${added} are both written with the same movement, so BOTH crossings play forward and this pair can never say "back" — the back button included. A relation written for the exact way travelled wins over being the reverse of another (see findRelation), which is what makes reciprocity the default: write the way back only to give it a DIFFERENT movement, or "none" to silence it. A single crossing that walks the map backwards says so on itself instead: <Link routeTransition={{ direction: "forward" }}>, or navTo(url, { routeTransition: { direction: "forward" } }).`);
+};
 const warnPagesBothCurrent = (pageKept, pageIgnored) => {
   const kept = describePage(pageKept);
   const ignored = describePage(pageIgnored);
@@ -58630,8 +58796,15 @@ const PickerCustomResolver = props => {
       props.variant = "icon";
     }
     // A door, never a field (see `allowNameless`): the form around it expects
-    // no value from it, and no name.
+    // no value from it, and no name. So the trigger answers to "button" — it is
+    // pressed to read something, never typed into — the same thing a confirm
+    // picker says through `picksNothing` (see picker.jsx). Said as the role
+    // here rather than through that prop: `picksNothing` also takes the right
+    // slot away, and the status icon a callout trigger draws sits in it.
     props.allowNameless = true;
+    if (props.role === undefined) {
+      props.role = "button";
+    }
     // A word in a sentence asks for a plain tooltip — no icon in the callout,
     // no status color; an icon one presses is the callout's own status icon,
     // and says "info" like the callout it opens.
@@ -59315,6 +59488,7 @@ const PickerContentInsidePopup = props => {
     children: isCallout ? jsx(PickerCalloutPopup, {
       ...popupProps,
       pickerRef: props.ref,
+      testId: popupTestId,
       status: calloutStatus,
       icon: calloutIcon,
       closeButton: calloutCloseButton,
@@ -59379,6 +59553,7 @@ const PickerCalloutPopup = ({
   anchor,
   openController,
   pickerRef,
+  testId,
   status,
   icon,
   closeButton,
@@ -59404,6 +59579,10 @@ const PickerCalloutPopup = ({
     const anchorElement = anchor === pickerRef ? undefined : anchor && "current" in anchor ? anchor.current : anchor;
     calloutManager.addOpenToken(PICKER_CALLOUT_CONTENT_TOKEN, {
       message: hostRef.current,
+      // The popup a `popupTestId` names is this callout: it is the surface the
+      // picker opens, drawn by navi, so it is the one thing the caller cannot
+      // name from its own children.
+      testId,
       // "none" is the picker's word for it; the callout's is no status at all.
       status: status === "none" ? undefined : status,
       icon,
@@ -67334,6 +67513,11 @@ const PickerButton = props => {
     // confirm resolver (see picker_confirm.jsx), which is the picker that is
     // one — a caller whose popup is a menu of actions says it for themselves.
     picksNothing,
+    // Where the caller's own role goes: onto the host, beside the name (see
+    // control_context.js) — a role and a name on two different elements name
+    // nothing at all. Left unsaid, a picker that picks nothing takes "button"
+    // (see PickerInput below).
+    role,
     readOnly,
     error
   } = props;
@@ -67388,6 +67572,21 @@ const PickerButton = props => {
   // clearing being a modification like any other.
   const interactive = !basePseudoState[":disabled"] && !basePseudoState[":read-only"] && !loading;
   usePickerErrorCallout(uiStateController, error);
+  // What the picker really is, said on the element that holds the name and
+  // takes the focus (the host input below): a picker that picks nothing is a
+  // door — its popup is a question (type="confirm") or something to read
+  // (mode="callout", which says it for itself) — and a door is pressed. So it
+  // answers to "button" rather than to the "textbox" its <input> would
+  // otherwise be, which is both what a screen reader announces and what
+  // getByRole("button", { name }) finds. A picker holding a value stays a
+  // textbox: it does hold text.
+  const hostRole = role ?? (picksNothing ? "button" : undefined);
+  // And what that button is called, when the caller wrote it as a drawing
+  // rather than as a word: a door draws no value, so what sits in its value
+  // slot IS its label — the `ui` a caller gave it, or its placeholder. Skipped
+  // the moment the caller names it themselves (aria-label/aria-labelledby),
+  // which is the only way to name a door drawn as an icon.
+  const hostLabelId = hostRole === "button" && inputProps["aria-label"] === undefined && inputProps["aria-labelledby"] === undefined && variant !== "headless" && ui !== "default" ? `${inputProps.id}_picker_label` : undefined;
   // What the picker knows about itself, for the pieces it does not place: the
   // drawings of its value (Picker.UI.*), and the affordances a caller may put
   // in their own `ui` (Picker.Clear) as much as the ones it puts in its slot.
@@ -67434,6 +67633,7 @@ const PickerButton = props => {
         basePseudoState: basePseudoState,
         styleCSSVars: PickerStyleCSSVars,
         variant: undefined,
+        role: undefined,
         rightSlotIcon: undefined,
         rightSlotIconSize: undefined,
         rightSlot: undefined,
@@ -67482,6 +67682,8 @@ const PickerButton = props => {
               color: "var(--picker-loader-color)",
               inset: -2
             }), jsx(PickerInput, {
+              role: hostRole,
+              "aria-labelledby": hostLabelId,
               tabIndex: variant === "headless" ? -1 : undefined,
               "aria-hidden": variant === "headless" ? "true" : undefined,
               ...inputProps,
@@ -67557,6 +67759,10 @@ const PickerButton = props => {
               }
             }), variant === "headless" || ui === "default" ? null : jsx(Text, {
               className: "navi_picker_value"
+              // Only when it names the trigger (see hostLabelId above).
+              ,
+
+              id: hostLabelId
               // Tells the caller's own drawing of the control from the value
               // the picker draws itself, so each is written on its own line
               // (see .navi_picker_value in the CSS above).