stimeo-ui 0.14.0 → 0.16.0

data/dist/controllers/form_validation_controller.js

@@ -96,13 +96,19 @@ var CONSTRAINT_MESSAGE_KEYS = [
   ["stepMismatch", "step-mismatch"],
   ["badInput", "bad-input"]
 ];
-var MESSAGE_ATTR_PREFIX = "data-stimeo--form-validation-message-";
-var MESSAGE_ATTR_GENERIC = "data-stimeo--form-validation-message";
-var DISALLOW_ATTR = "data-stimeo--form-validation-disallow";
-var DISALLOW_WHITESPACE_MESSAGE = `${MESSAGE_ATTR_PREFIX}whitespace`;
+var MESSAGE_PART = "message";
+var DISALLOW_PART = "disallow";
 var DISALLOW_WHITESPACE_DEFAULT = "Please enter a value that is not only whitespace.";
 var FORM_FIELD_INVALID_ATTR = "data-stimeo--form-field-invalid";
 var FormValidationController = class _FormValidationController extends Controller {
+  /** The generic message override, in the namespace this controller is registered under. */
+  get #messageAttribute() {
+    return `data-${this.identifier}-${MESSAGE_PART}`;
+  }
+  /** Marks the `novalidate` this controller applied, so an authored one is left alone. */
+  get #novalidateMarker() {
+    return `data-${this.identifier}-${_FormValidationController.#NOVALIDATE_PART}`;
+  }
   static outlets = ["stimeo--form-field"];
   static values = {
     validateOnBlur: { type: Boolean, default: true },
@@ -112,8 +118,8 @@ var FormValidationController = class _FormValidationController extends Controlle
   };
   static actions = ["validate"];
   static events = ["valid", "invalid"];
-  /** Marker recording that we added `novalidate`, so we only remove our own. */
-  static #NOVALIDATE_MARKER = "data-stimeo--form-validation-novalidate";
+  /** Suffix of the marker recording that we added `novalidate`, so we only remove our own. */
+  static #NOVALIDATE_PART = "novalidate";
   /** Object-backed groups already interacted with — the input revalidation gate. */
   #touchedGroups = /* @__PURE__ */ new WeakSet();
   /** String-backed fallback radio groups already interacted with. */
@@ -169,7 +175,7 @@ var FormValidationController = class _FormValidationController extends Controlle
   /** Suppresses native bubbles and binds the submit / blur / input listeners. */
   connect() {
     if (setDefaultAttribute(this.element, "novalidate", "")) {
-      this.element.setAttribute(_FormValidationController.#NOVALIDATE_MARKER, "");
+      this.element.setAttribute(this.#novalidateMarker, "");
     }
     this.#listenerDocument = this.element.ownerDocument;
     this.#listenerDocument.addEventListener("submit", this.#onSubmit, true);
@@ -189,9 +195,9 @@ var FormValidationController = class _FormValidationController extends Controlle
     }
     this.#ownedCustomErrors.clear();
     this.#touchedRadioGroups.clear();
-    if (this.element.hasAttribute(_FormValidationController.#NOVALIDATE_MARKER)) {
+    if (this.element.hasAttribute(this.#novalidateMarker)) {
       this.element.removeAttribute("novalidate");
-      this.element.removeAttribute(_FormValidationController.#NOVALIDATE_MARKER);
+      this.element.removeAttribute(this.#novalidateMarker);
     }
   }
   /**
@@ -283,10 +289,10 @@ var FormValidationController = class _FormValidationController extends Controlle
     if (control.validity.customError) return control.validationMessage;
     for (const [flag, key] of CONSTRAINT_MESSAGE_KEYS) {
       if (control.validity[flag]) {
-        return this.#authoredMessage(control, `${MESSAGE_ATTR_PREFIX}${key}`) ?? this.#authoredMessage(control, MESSAGE_ATTR_GENERIC) ?? control.validationMessage;
+        return this.#authoredMessage(control, `${this.#messageAttribute}-${key}`) ?? this.#authoredMessage(control, this.#messageAttribute) ?? control.validationMessage;
       }
     }
-    return control.validationMessage || this.#authoredMessage(control, MESSAGE_ATTR_GENERIC) || "";
+    return control.validationMessage || this.#authoredMessage(control, this.#messageAttribute) || "";
   }
   /**
    * Applies (or clears) a declarative custom constraint via `setCustomValidity`,
@@ -302,14 +308,14 @@ var FormValidationController = class _FormValidationController extends Controlle
   #syncCustomValidity(control) {
     const recorded = this.#ownedCustomErrors.get(control);
     const ownsCurrent = recorded !== void 0 && control.validationMessage === recorded;
-    const violates = control.getAttribute(DISALLOW_ATTR) === "whitespace" && control.value.length > 0 && control.value.trim() === "";
+    const violates = control.getAttribute(`data-${this.identifier}-${DISALLOW_PART}`) === "whitespace" && control.value.length > 0 && control.value.trim() === "";
     if (!violates) {
       if (ownsCurrent) control.setCustomValidity("");
       this.#ownedCustomErrors.delete(control);
       return;
     }
     if (control.validity.customError && !ownsCurrent) return;
-    const message = this.#authoredMessage(control, DISALLOW_WHITESPACE_MESSAGE) ?? this.#authoredMessage(control, MESSAGE_ATTR_GENERIC) ?? DISALLOW_WHITESPACE_DEFAULT;
+    const message = this.#authoredMessage(control, `${this.#messageAttribute}-whitespace`) ?? this.#authoredMessage(control, this.#messageAttribute) ?? DISALLOW_WHITESPACE_DEFAULT;
     if (!ownsCurrent || recorded !== message) control.setCustomValidity(message);
     this.#ownedCustomErrors.set(control, message);
   }

data/dist/controllers/frame_loading_controller.js

@@ -103,6 +103,30 @@ var DetachGate = class _DetachGate {
   }
 };
 
+// src/utils/listener_set.ts
+var ListenerSet = class {
+  /** The generation every `add` joins until the next `dispose()`. */
+  #abort = new AbortController();
+  /**
+   * Attaches `handler` to the open generation, exactly as the caller spelled it.
+   *
+   * The set supplies the signal, so `options` carries everything else the DOM
+   * accepts — `capture` included, which has to match at release time and no
+   * longer has a second place to drift from.
+   */
+  add(target, type, handler, options) {
+    target.addEventListener(type, handler, { ...options, signal: this.#abort.signal });
+  }
+  /**
+   * Releases every listener of the open generation, synchronously, and opens the
+   * next one. Idempotent, and safe before anything has been added.
+   */
+  dispose() {
+    this.#abort.abort();
+    this.#abort = new AbortController();
+  }
+};
+
 // src/utils/min_duration_floor.ts
 var MinDurationFloor = class {
   #timers;
@@ -218,6 +242,7 @@ var FrameLoadingController = class extends Controller {
   #floor = new MinDurationFloor(this.#timeouts);
   #gate = new DetachGate();
   #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
+  #listeners = new ListenerSet();
   #loading = false;
   /**
    * The optional targets this controller revealed, and the content it marked inert.
@@ -237,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());
@@ -244,14 +273,12 @@ var FrameLoadingController = class extends Controller {
   connect() {
     this.#gate.cancel();
     this.#beforeCache.activate();
-    this.element.addEventListener("turbo:before-fetch-request", this.#onStart);
-    this.element.addEventListener("turbo:frame-load", this.#onEnd);
-    this.element.addEventListener("turbo:fetch-request-error", this.#onEnd);
+    this.#listeners.add(this.element, "turbo:before-fetch-request", this.#onStart);
+    this.#listeners.add(this.element, "turbo:frame-load", this.#onEnd);
+    this.#listeners.add(this.element, "turbo:fetch-request-error", this.#onEnd);
   }
   disconnect() {
-    this.element.removeEventListener("turbo:before-fetch-request", this.#onStart);
-    this.element.removeEventListener("turbo:frame-load", this.#onEnd);
-    this.element.removeEventListener("turbo:fetch-request-error", this.#onEnd);
+    this.#listeners.dispose();
     this.#beforeCache.deactivate();
     this.#gate.disconnected(this, () => this.#teardown());
   }
@@ -340,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();
@@ -353,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

@@ -2,11 +2,6 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/highlight_controller.ts
 
-// src/utils/reduced_motion.ts
-function prefersReducedMotion() {
-  return typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
-}
-
 // src/utils/safe_timeout.ts
 var TimerRegistry = class {
   /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
@@ -60,7 +55,68 @@ var SafeTimeout = class extends TimerRegistry {
   }
 };
 
+// src/utils/keyed_timers.ts
+var KeyedTimers = class {
+  #timers = new SafeTimeout();
+  /** The pending timer of each key; an entry lives exactly as long as its timer. */
+  #pending = /* @__PURE__ */ new Map();
+  /**
+   * Arms `callback` after `delay` ms for `key`, cancelling the timer `key` had
+   * pending. The entry is dropped before the callback runs, so the callback sees
+   * the key unarmed and may arm it again for the next round.
+   */
+  set(key, callback, delay) {
+    this.clear(key);
+    const id = this.#timers.set(() => {
+      this.#pending.delete(key);
+      callback();
+    }, delay);
+    this.#pending.set(key, id);
+  }
+  /**
+   * Cancels `key`'s pending timer, if it has one.
+   *
+   * A timer id is a positive integer, so `-1` stands for "nothing pending" and
+   * the registry ignores an id it does not own — the unarmed case needs no
+   * branch of its own, and no other key's timer can be reached from here.
+   */
+  clear(key) {
+    this.#timers.clear(this.#pending.get(key) ?? -1);
+    this.#pending.delete(key);
+  }
+  /**
+   * Cancels every pending timer and forgets every key. Call this from a
+   * controller's `disconnect()` so no timer, and no entry, outlives the element.
+   */
+  clearAll() {
+    this.#timers.clearAll();
+    this.#pending.clear();
+  }
+  /** Whether `key` has a timer pending. */
+  has(key) {
+    return this.#pending.has(key);
+  }
+};
+
+// src/utils/reduced_motion.ts
+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 = {
@@ -68,14 +124,11 @@ var HighlightController = class extends Controller {
     observe: { type: Boolean, default: false }
   };
   static events = ["start", "end"];
-  #timeouts = new SafeTimeout();
   /**
-   * The removal timer this connection has outstanding for an element. Held weakly so
-   * a row that leaves the DOM is not retained, and dropped wholesale on `disconnect()`
-   * so a cleared id can never be matched against a recycled one. Which connection owns
-   * an element's hook is answered by the shared owner registry above.
+   * The removal timer this connection has outstanding for each element. Which
+   * connection owns an element's hook is answered by the shared owner registry above.
    */
-  #pending = /* @__PURE__ */ new WeakMap();
+  #removal = new KeyedTimers();
   #observer = null;
   connect() {
     this.#clearArrivedHook(this.element);
@@ -92,13 +145,12 @@ var HighlightController = class extends Controller {
   disconnect() {
     this.#observer?.disconnect();
     this.#observer = null;
-    this.#timeouts.clearAll();
-    this.#pending = /* @__PURE__ */ new WeakMap();
+    this.#removal.clearAll();
   }
   /** 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) {
@@ -108,19 +160,25 @@ 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);
     el.setAttribute("data-highlight", "true");
     this.dispatch("start", { target: el, detail: { element: el } });
-    const id = this.#timeouts.set(() => {
-      this.#pending.delete(el);
-      hookOwners.delete(el);
-      el.removeAttribute("data-highlight");
-      this.dispatch("end", { target: el, detail: { element: el } });
-    }, this.durationValue);
-    this.#pending.set(el, id);
+    this.#removal.set(
+      el,
+      () => {
+        hookOwners.delete(el);
+        el.removeAttribute("data-highlight");
+        this.dispatch("end", { target: el, detail: { element: el } });
+      },
+      this.durationValue
+    );
     hookOwners.set(el, this);
   }
   /**
@@ -133,10 +191,9 @@ var HighlightController = class extends Controller {
     if (owner !== void 0 && owner !== this) owner.#cancelPending(el);
     this.#cancelPending(el);
   }
-  /** Releases `el`'s pending removal timer, if it has one. */
+  /** Releases `el`'s pending removal timer, if it has one, and this connection's claim. */
   #cancelPending(el) {
-    this.#timeouts.clear(this.#pending.get(el) ?? -1);
-    this.#pending.delete(el);
+    this.#removal.clear(el);
     hookOwners.delete(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 };