stimeo-ui 0.15.0 → 0.16.0

data/dist/controllers/frame_loading_controller.js

@@ -262,6 +262,10 @@ var FrameLoadingController = class extends Controller {
     this.#floor.cancel();
     if (!this.#loading) this.#begin();
   };
+  /**
+   * @stimeoRuntimeOnly `minDuration` holds the loading state at least this long for the one load
+   *   that ended.
+   */
   #onEnd = () => {
     if (!this.#loading) return;
     this.#floor.schedule(this.minDurationValue, () => this.#finish());
@@ -363,7 +367,12 @@ var FrameLoadingController = class extends Controller {
     this.#revealedOverlay = this.overlayTarget;
     this.overlayTarget.hidden = false;
   }
-  /** Enters the loading state: hooks, skeleton/overlay, inert content, focus retreat. */
+  /**
+   * Enters the loading state: hooks, skeleton/overlay, inert content, focus retreat.
+   *
+   * @stimeoRuntimeOnly `announceText` words the one announcement of this load and `restoreFocus`
+   *   decides whether focus leaves the frame it covers.
+   */
   #begin() {
     this.#loading = true;
     this.#floor.begin();
@@ -376,7 +385,12 @@ var FrameLoadingController = class extends Controller {
     this.dispatch("start", { detail: {} });
     announce(fillTemplate(this.announceTextValue, {}));
   }
-  /** Leaves the loading state: restore hooks, hide skeleton/overlay, restore focus. */
+  /**
+   * Leaves the loading state: restore hooks, hide skeleton/overlay, restore focus.
+   *
+   * @stimeoRuntimeOnly `announceReadyText` words the one announcement of this finished load and
+   *   `restoreFocus` decides whether focus goes back.
+   */
   #finish() {
     this.#loading = false;
     this.#rewindHooks();

data/dist/controllers/highlight_controller.js

@@ -103,7 +103,20 @@ function prefersReducedMotion() {
   return typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
 }
 
+// src/utils/transient_hooks.ts
+var TransientHooks = class {
+  #attributes;
+  constructor(options) {
+    this.#attributes = options.attributes;
+  }
+  /** Drops the declared hooks from `element`; what it carries besides stays. */
+  reset(element) {
+    for (const attribute of this.#attributes) element.removeAttribute(attribute);
+  }
+};
+
 // src/controllers/highlight_controller.ts
+var TRANSIENT = new TransientHooks({ attributes: ["data-highlight"] });
 var hookOwners = /* @__PURE__ */ new WeakMap();
 var HighlightController = class extends Controller {
   static values = {
@@ -137,7 +150,7 @@ var HighlightController = class extends Controller {
   /** Drops a hook that arrived with the DOM, along with this connection's claim on it. */
   #clearArrivedHook(el) {
     if (hookOwners.get(el) === this) hookOwners.delete(el);
-    el.removeAttribute("data-highlight");
+    TRANSIENT.reset(el);
   }
   /** Highlights every element child added by a childList mutation. */
   #onMutations(mutations) {
@@ -147,7 +160,11 @@ var HighlightController = class extends Controller {
       }
     }
   }
-  /** Flags `el` with `data-highlight` and schedules its removal (unless reduced-motion). */
+  /**
+   * Flags `el` with `data-highlight` and schedules its removal (unless reduced-motion).
+   *
+   * @stimeoRuntimeOnly `duration` is the length of the one emphasis this call arms.
+   */
   #highlight(el) {
     if (prefersReducedMotion()) return;
     this.#releasePending(el);

data/dist/controllers/hover_card_controller.js

@@ -164,6 +164,16 @@ function isScrollable(element) {
   return /auto|scroll|overlay/.test(style.overflow + style.overflowX + style.overflowY);
 }
 
+// src/utils/state_reason.ts
+var FOCUS_EVENTS = /* @__PURE__ */ new Set(["blur", "focus", "focusin", "focusout"]);
+var POINTER_EVENTS = /* @__PURE__ */ new Set(["mouseenter", "mouseleave", "pointerenter", "pointerleave"]);
+function stateReasonFor(event) {
+  if (!event) return "api";
+  if (FOCUS_EVENTS.has(event.type)) return "focus";
+  if (POINTER_EVENTS.has(event.type)) return "pointer";
+  return "user";
+}
+
 // src/controllers/hover_card_controller.ts
 var HoverCardController = class extends Controller {
   static targets = ["trigger", "card"];
@@ -173,6 +183,7 @@ var HoverCardController = class extends Controller {
     closeOnScroll: { type: Boolean, default: false }
   };
   static actions = ["close", "open"];
+  static events = ["close", "open"];
   /** Pending open/close timers, with their IDs reset on every lifecycle boundary. */
   #timers = new SafeTimeout();
   /** Escape-stack membership while open; the shared resolver dismisses via it. */
@@ -181,14 +192,18 @@ var HoverCardController = class extends Controller {
   #pendingClose = null;
   /** Cleanup for the dismiss-on-scroll listeners while open, or `null`. */
   #stopScrollDismiss = null;
+  /** Whether state moves are reported: set once `connect()` settled the baseline. */
+  #reporting = false;
   /** Starts closed and discards any stale pending state from a prior connection. */
   connect() {
     this.#cancelOpen();
     this.#cancelClose();
-    this.#conceal();
+    this.#conceal("api");
+    this.#reporting = true;
   }
   /** Clears timers, the Escape-stack membership, and scroll listeners so nothing outlives the element. */
   disconnect() {
+    this.#reporting = false;
     this.#cancelOpen();
     this.#cancelClose();
     this.#escapeLayer.deactivate();
@@ -196,16 +211,17 @@ var HoverCardController = class extends Controller {
     this.#stopScrollDismiss = null;
   }
   /** Opens the card, after `openDelay` ms (or immediately at 0). Cancels a pending close. */
-  open() {
+  open(event) {
+    const reason = stateReasonFor(event);
     this.#cancelClose();
     if (this.#isOpen || this.#pendingOpen !== null) return;
     if (this.openDelayValue <= 0) {
-      this.#reveal();
+      this.#reveal(reason);
       return;
     }
     this.#pendingOpen = this.#timers.set(() => {
       this.#pendingOpen = null;
-      this.#reveal();
+      this.#reveal(reason);
     }, this.openDelayValue);
   }
   /**
@@ -214,28 +230,37 @@ var HoverCardController = class extends Controller {
    * (e.g. a link in the card) and, if so, aborts the close — covering keyboard
    * traversal that the pointer-only hoverable bridge cannot.
    */
-  close() {
+  close(event) {
+    const reason = stateReasonFor(event);
     this.#cancelOpen();
     if (!this.#isOpen || this.#pendingClose !== null) return;
     this.#pendingClose = this.#timers.set(() => {
       this.#pendingClose = null;
       if (this.element.contains(document.activeElement)) return;
-      this.#conceal();
+      this.#conceal(reason);
     }, this.closeDelayValue);
   }
-  /** Reveals the card, reflects state, and joins the Escape stack / scroll watcher. */
-  #reveal() {
+  /**
+   * Reveals the card, reflects state, reports a move, and joins the Escape stack.
+   *
+   * @stimeoRuntimeOnly `closeOnScroll` decides whether this reveal wires the scroll dismissal; what
+   *   is shown does not depend on it.
+   */
+  #reveal(reason) {
     if (!this.hasCardTarget) return;
+    const was = this.#isOpen;
     this.cardTarget.hidden = false;
     this.cardTarget.setAttribute("data-state", "open");
     if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", "true");
-    this.#escapeLayer.activate(document, { onDismiss: () => this.#dismiss() });
+    if (!was && this.#reporting) this.dispatch("open", { detail: { reason }, cancelable: false });
+    this.#escapeLayer.activate(document, { onDismiss: () => this.#dismiss("escape") });
     if (this.closeOnScrollValue && !this.#stopScrollDismiss) {
-      this.#stopScrollDismiss = observeScrollDismiss(this.element, () => this.#dismiss());
+      this.#stopScrollDismiss = observeScrollDismiss(this.element, () => this.#dismiss("scroll"));
     }
   }
-  /** Hides the card, reflects state, and leaves the Escape stack / scroll watcher. */
-  #conceal() {
+  /** Hides the card, reflects state, reports a move, and leaves the Escape stack. */
+  #conceal(reason) {
+    const was = this.#isOpen;
     this.#escapeLayer.deactivate();
     this.#stopScrollDismiss?.();
     this.#stopScrollDismiss = null;
@@ -244,12 +269,13 @@ var HoverCardController = class extends Controller {
       this.cardTarget.setAttribute("data-state", "closed");
     }
     if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", "false");
+    if (was && this.#reporting) this.dispatch("close", { detail: { reason }, cancelable: false });
   }
   /** Cancels pending timers and conceals immediately (shared Escape path). */
-  #dismiss() {
+  #dismiss(reason) {
     this.#cancelOpen();
     this.#cancelClose();
-    this.#conceal();
+    this.#conceal(reason);
   }
   /** Cancels any pending open timer. */
   #cancelOpen() {

data/dist/controllers/idle_controller.js

@@ -55,6 +55,47 @@ var SafeTimeout = class extends TimerRegistry {
   }
 };
 
+// src/utils/state_regions.ts
+var StateRegions = class {
+  #whenTrue;
+  #whenFalse;
+  #taken = /* @__PURE__ */ new WeakSet();
+  constructor(options) {
+    this.#whenTrue = options.whenTrue;
+    this.#whenFalse = options.whenFalse ?? null;
+  }
+  /** Shows the regions inside `host` that belong to `isTrue` and hides the others. */
+  reflect(host, isTrue) {
+    const shown = this.#inside(host, this.#whenTrue());
+    if (!this.#whenFalse) {
+      for (const region of shown) this.#write(region, !isTrue);
+      return;
+    }
+    const hiddenSide = this.#inside(host, this.#whenFalse());
+    if (shown.length === 0 || hiddenSide.length === 0) {
+      for (const region of shown) this.#give(region);
+      for (const region of hiddenSide) this.#give(region);
+      return;
+    }
+    for (const region of shown) this.#write(region, !isTrue);
+    for (const region of hiddenSide) this.#write(region, isTrue);
+  }
+  /** Writes `hidden` where it moves, noting which regions it takes out of view. */
+  #write(region, hidden) {
+    if (hidden) this.#taken.add(region);
+    else this.#taken.delete(region);
+    if (region.hidden !== hidden) region.hidden = hidden;
+  }
+  /** Returns a region this instance hid; one it never hid keeps what it carries. */
+  #give(region) {
+    if (this.#taken.delete(region)) region.hidden = false;
+  }
+  /** The declared regions that sit within `host`, which may be the host itself. */
+  #inside(host, regions) {
+    return regions.filter((region) => host.contains(region));
+  }
+};
+
 // src/utils/string_list.ts
 function parseStringList(raw, fallback = []) {
   const text = raw.trim();
@@ -87,7 +128,12 @@ var IdleController = class extends Controller {
     // runs, so one malformed attribute would stop the detector connecting.
     events: { type: String, default: "" }
   };
+  static targets = ["prompt", "idle"];
   static events = ["prompt", "idle", "active"];
+  /** The regions of the warning window, revealed alongside `data-prompt`. */
+  #promptRegions = new StateRegions({ whenTrue: () => this.promptTargets });
+  /** The regions of the elapsed timeout, revealed alongside `data-idle`. */
+  #idleRegions = new StateRegions({ whenTrue: () => this.idleTargets });
   #timeouts = new SafeTimeout();
   #idle = false;
   #prompted = false;
@@ -104,7 +150,7 @@ var IdleController = class extends Controller {
     if (this.#idle || this.#prompted) {
       this.#idle = false;
       this.#prompted = false;
-      this.element.removeAttribute("data-idle");
+      this.#reflect();
       this.dispatch("active", { detail: {} });
       this.#arm();
     }
@@ -115,7 +161,7 @@ var IdleController = class extends Controller {
   connect() {
     this.#idle = false;
     this.#prompted = false;
-    this.element.removeAttribute("data-idle");
+    this.#reflect();
     this.#boundEvents = parseStringList(this.eventsValue, DEFAULT_ACTIVITY_EVENTS);
     for (const type of this.#boundEvents) {
       document.addEventListener(type, this.#onActivity, { passive: true, capture: true });
@@ -131,7 +177,11 @@ var IdleController = class extends Controller {
     document.removeEventListener("visibilitychange", this.#onVisibility);
     this.#timeouts.clearAll();
   }
-  /** Schedules the prompt and idle checks from the current activity baseline. */
+  /**
+   * Schedules the prompt and idle checks from the current activity baseline.
+   *
+   * @stimeoRuntimeOnly `timeout` and `promptBefore` time the checks this call arms.
+   */
   #arm() {
     this.#timeouts.clearAll();
     this.#lastActivity = Date.now();
@@ -145,6 +195,9 @@ var IdleController = class extends Controller {
    * Idle-timer callback: go idle only if there has genuinely been no activity for
    * `timeout`; otherwise reschedule for the remaining time. This lets activity events
    * stay O(1) (a timestamp write) while the deadline still tracks the last activity.
+   *
+   * @stimeoRuntimeOnly `timeout` sets the deadline this one check compares against; the phase it
+   *   shows follows the elapsed time.
    */
   #checkIdle() {
     const remaining = this.timeoutValue - (Date.now() - this.#lastActivity);
@@ -154,19 +207,51 @@ var IdleController = class extends Controller {
     }
     this.#idle = true;
     this.#prompted = false;
-    this.element.setAttribute("data-idle", "true");
+    this.#reflect();
     this.dispatch("idle", { detail: {} });
   }
-  /** Prompt-timer callback: warn at `promptBefore` before the idle deadline. */
+  /**
+   * Prompt-timer callback: warn at `promptBefore` before the idle deadline. A window
+   * narrowed while the cycle runs can push the warning onto the deadline or past it,
+   * and the phase it belongs to is the one before idle, so a lapsed cycle keeps the
+   * phase it reached. The next window opens with the cycle that activity arms.
+   *
+   * @stimeoRuntimeOnly `timeout` and `promptBefore` set the deadlines this one check compares
+   *   against; the phase it shows follows the elapsed time.
+   */
   #checkPrompt() {
+    if (this.#idle) return;
     const remaining = this.timeoutValue - this.promptBeforeValue - (Date.now() - this.#lastActivity);
     if (remaining > 0) {
       this.#timeouts.set(() => this.#checkPrompt(), remaining);
       return;
     }
     this.#prompted = true;
+    this.#reflect();
     this.dispatch("prompt", { detail: { remaining: this.promptBeforeValue } });
   }
+  /** Applies the current phase to a warning region inserted or replaced at runtime. */
+  promptTargetConnected() {
+    this.#promptRegions.reflect(this.element, this.#prompted);
+  }
+  /** Applies the current phase to an idle region inserted or replaced at runtime. */
+  idleTargetConnected() {
+    this.#idleRegions.reflect(this.element, this.#idle);
+  }
+  /**
+   * Writes the phase to the element and to the declared regions. Both hooks and both
+   * regions are a pure function of the two flags, so every place that moves a flag ends
+   * here and the markup can never disagree with the phase the detector is in.
+   */
+  #reflect() {
+    const { element } = this;
+    if (this.#prompted) element.setAttribute("data-prompt", "true");
+    else element.removeAttribute("data-prompt");
+    if (this.#idle) element.setAttribute("data-idle", "true");
+    else element.removeAttribute("data-idle");
+    this.#promptRegions.reflect(element, this.#prompted);
+    this.#idleRegions.reflect(element, this.#idle);
+  }
 };
 
 export { IdleController };

data/dist/controllers/input_mask_controller.js

@@ -3,11 +3,19 @@ import { Controller } from '@hotwired/stimulus';
 // src/controllers/input_mask_controller.ts
 
 // src/utils/composition_tracker.ts
+var COMPOSITION_INPUT_TYPES = /* @__PURE__ */ new Set([
+  "insertCompositionText",
+  "insertFromComposition",
+  "deleteCompositionText",
+  "deleteByComposition"
+]);
 var CompositionTracker = class {
   #observedTargets = /* @__PURE__ */ new Set();
   #activeTargets = /* @__PURE__ */ new Set();
   #onStart;
   #onEnd;
+  /** The field whose confirming `input` is still owed, while the window is open. */
+  #confirmedTarget = null;
   constructor(options = {}) {
     this.#onStart = options.onStart;
     this.#onEnd = options.onEnd;
@@ -17,6 +25,7 @@ var CompositionTracker = class {
     if (this.#observedTargets.has(target)) return;
     target.addEventListener("compositionstart", this.#handleStart);
     target.addEventListener("compositionend", this.#handleEnd);
+    target.addEventListener("keydown", this.#handleKeydown);
     this.#observedTargets.add(target);
   }
   /** Stops tracking one target and clears any active composition it owned. */
@@ -24,29 +33,52 @@ var CompositionTracker = class {
     if (!this.#observedTargets.delete(target)) return;
     target.removeEventListener("compositionstart", this.#handleStart);
     target.removeEventListener("compositionend", this.#handleEnd);
+    target.removeEventListener("keydown", this.#handleKeydown);
     this.#activeTargets.delete(target);
+    if (this.#confirmedTarget === target) this.#confirmedTarget = null;
   }
   /** Releases every listener and clears state so reconnect starts cleanly. */
   disconnect() {
     for (const target of this.#observedTargets) {
       target.removeEventListener("compositionstart", this.#handleStart);
       target.removeEventListener("compositionend", this.#handleEnd);
+      target.removeEventListener("keydown", this.#handleKeydown);
     }
     this.#observedTargets.clear();
     this.#activeTargets.clear();
+    this.#confirmedTarget = null;
   }
   /** True when lifecycle tracking or the current event reports composition. */
   isComposing(event) {
     return this.#activeTargets.size > 0 || event?.isComposing === true;
   }
+  /**
+   * Whether `event` is the `input` echoing the composition just confirmed.
+   *
+   * Asking closes the window either way, so one confirmation is folded at most
+   * once and a consumer asks once per `input`.
+   */
+  consumesConfirmedInput(event) {
+    const confirmed = this.#confirmedTarget;
+    this.#confirmedTarget = null;
+    if (confirmed === null || confirmed !== event.target) return false;
+    const inputType = event.inputType;
+    return !inputType || COMPOSITION_INPUT_TYPES.has(inputType);
+  }
   #handleStart = (event) => {
+    this.#confirmedTarget = null;
     if (event.currentTarget) this.#activeTargets.add(event.currentTarget);
     this.#onStart?.(event);
   };
   #handleEnd = (event) => {
     if (event.currentTarget) this.#activeTargets.delete(event.currentTarget);
+    this.#confirmedTarget = event.target;
     this.#onEnd?.(event);
   };
+  /** A key on an observed field opens an edit of its own, so no echo is owed. */
+  #handleKeydown = () => {
+    this.#confirmedTarget = null;
+  };
 };
 
 // src/utils/declared_value.ts
@@ -99,7 +131,7 @@ var DEFAULT_TOKENS = {
   a: "[A-Za-z]",
   "*": "[A-Za-z0-9]"
 };
-var UNMASK_ATTR = "data-stimeo--input-mask-unmask";
+var UNMASK_ATTR = "unmask";
 function acceptedForm(regex, char) {
   if (regex.test(char)) return char;
   const half = halfWidthChar(char);
@@ -176,6 +208,10 @@ function tokenCharOffset(tokenFlags, n) {
   return -1;
 }
 var InputMaskController = class extends Controller {
+  /** The attribute above, in the namespace this controller is registered under. */
+  get #unmaskAttribute() {
+    return `data-${this.identifier}-${UNMASK_ATTR}`;
+  }
   static values = {
     pattern: { type: String, default: "" },
     tokens: { type: String, default: "" },
@@ -188,8 +224,23 @@ var InputMaskController = class extends Controller {
   #started = false;
   /** Validated token map; the hot path never parses the `tokens` declaration. */
   #tokens = compileTokens("");
-  /** Holds mid-composition input so the IME's uncommitted text is never rewritten. */
-  #composition = new CompositionTracker({ onEnd: () => this.#reformat("edit") });
+  /** The field's text when the running composition began. */
+  #textBeforeComposition = "";
+  /**
+   * Holds mid-composition input so the IME's uncommitted text is never rewritten,
+   * and formats the confirmed text once when the composition ends. A composition
+   * that ends on the text it began with committed nothing, so a re-format then is
+   * the page's: the mask changed while it ran.
+   */
+  #composition = new CompositionTracker({
+    onStart: () => {
+      this.#textBeforeComposition = this.element.value;
+    },
+    onEnd: () => {
+      const committedNothing = this.element.value === this.#textBeforeComposition;
+      this.#reformat(committedNothing ? "reconcile" : "edit");
+    }
+  });
   /** Re-parses the declaration and re-formats under the tokens it now selects. */
   tokensValueChanged() {
     this.#tokens = compileTokens(this.tokensValue);
@@ -225,8 +276,11 @@ var InputMaskController = class extends Controller {
   /**
    * Core reformat: mask the current value, restore the caret, sync the sink and
    * the state hooks, and report a moved value under the event `cause` selects.
+   *
+   * @stimeoRenderRoot
    */
   #reformat(cause, deletion = null) {
+    if (this.#composition.isComposing()) return;
     const input = this.element;
     const raw = input.value;
     if (this.patternValue === "") {
@@ -311,8 +365,8 @@ var InputMaskController = class extends Controller {
    *    `id` (`data-stimeo--input-mask-unmask="zip"`).
    * 2. **Nearest container** — otherwise, walking up from the input, the first
    *    *value-less* sink in the closest ancestor. Wrapped input+sink pairs each
-   *    find their own sink, and the single form-level sink keeps working
-   *    unchanged. A sink claimed by another input's id is never matched here.
+   *    find their own sink, and a single form-level sink is found the same
+   *    way. A sink claimed by another input's id is never matched here.
    *
    * Both steps only ever consider the associated form's own controls, so a sink
    * belonging to a different form (or to none) is never written, while one the
@@ -324,10 +378,10 @@ var InputMaskController = class extends Controller {
     const candidates = this.#sinkCandidates();
     const id = this.element.id;
     if (id.length > 0) {
-      const paired = candidates.find((sink) => sink.getAttribute(UNMASK_ATTR) === id);
+      const paired = candidates.find((sink) => sink.getAttribute(this.#unmaskAttribute) === id);
       if (paired) return paired;
     }
-    const free = candidates.filter((sink) => sink.getAttribute(UNMASK_ATTR) === "");
+    const free = candidates.filter((sink) => sink.getAttribute(this.#unmaskAttribute) === "");
     for (let node = this.element.parentElement; node !== null; node = node.parentElement) {
       const ancestor = node;
       const sink = free.find((candidate) => ancestor.contains(candidate));
@@ -344,10 +398,12 @@ var InputMaskController = class extends Controller {
   #sinkCandidates() {
     const form = this.element.form;
     if (form === null) {
-      return Array.from(document.querySelectorAll(`input[${UNMASK_ATTR}]`));
+      return Array.from(
+        document.querySelectorAll(`input[${this.#unmaskAttribute}]`)
+      );
     }
     return Array.from(form.elements).filter(
-      (element) => element instanceof HTMLInputElement && element.hasAttribute(UNMASK_ATTR)
+      (element) => element instanceof HTMLInputElement && element.hasAttribute(this.#unmaskAttribute)
     );
   }
   /** Sets a boolean `data-*` flag to `"true"` when `on`, else removes it. */

data/dist/controllers/intersection_controller.js

@@ -204,6 +204,9 @@ var IntersectionController = class extends Controller {
    * so the observer's initial callback fires `enter` for an element that starts
    * visible but stays silent after a cache restore that already recorded it.
    * An initial not-visible state is established silently (no `exit`).
+   *
+   * @stimeoRuntimeOnly `once` decides whether this enter spends the watcher's one shot; the hook it
+   *   writes follows the entry.
    */
   #syncIntersecting(intersecting, ratio, entry) {
     const previous = this.element.getAttribute("data-intersecting");

data/dist/controllers/lazy_frame_controller.js

@@ -192,7 +192,12 @@ var LazyFrameController = class extends Controller {
     if (this.onceValue || !returning) return;
     this.#reload();
   }
-  /** Starts the load by writing the held URL to `src`. */
+  /**
+   * Starts the load by writing the held URL to `src`.
+   *
+   * @stimeoRuntimeOnly `url` is the address this one load fetches and `once` decides whether it
+   *   stops the watcher.
+   */
   #load() {
     if (!this.urlValue) return;
     this.#loaded = true;
@@ -202,7 +207,11 @@ var LazyFrameController = class extends Controller {
     this.element.removeEventListener("focusin", this.#onFocus);
     if (this.onceValue) this.#watcher.stop();
   }
-  /** Re-entry while `once` is off: fetch the held URL again. */
+  /**
+   * Re-entry while `once` is off: fetch the held URL again.
+   *
+   * @stimeoRuntimeOnly `url` is the address this one re-entry reloads.
+   */
   #reload() {
     const src = this.element.getAttribute("src");
     if (this.urlValue && this.urlValue !== src) {