stimeo-ui 0.14.0 → 0.16.0

package/dist/controllers/carousel_controller.js

@@ -90,12 +90,91 @@ var BeforeCacheReset = class _BeforeCacheReset {
   }
 };
 
+// src/utils/detach_gate.ts
+var DetachGate = class _DetachGate {
+  /** Set while a probe is queued, waiting for a reconnect to cancel it. */
+  #pending = false;
+  /**
+   * True while a probe is queued — the last disconnect was ambiguous and no
+   * reconnect has cancelled it yet. Read it from `connect()` to tell the
+   * reconnect half of an in-page move from a first connect: a controller whose
+   * initialisation restarts a measurement (a min-duration floor, an elapsed
+   * counter) must skip it for the move, where nothing actually restarted.
+   */
+  get pending() {
+    return this.#pending;
+  }
+  /**
+   * True when the disconnect is definitely a real detach — the element left
+   * the document, or `data-controller` no longer lists the identifier. False
+   * means ambiguous (in-page move or observed-root exit), NOT "alive".
+   */
+  static isDetached(host) {
+    if (!host.element.isConnected) return true;
+    const tokens = (host.element.getAttribute("data-controller") ?? "").split(/\s+/);
+    return !tokens.includes(host.identifier);
+  }
+  /**
+   * Call from `disconnect()`: runs `teardown` synchronously on a definite
+   * detach (fast path), otherwise defers it one microtask — a reconnect
+   * ({@link cancel} from `connect()`) keeps the state, no reconnect runs it.
+   * One microtask is the whole probe window: Stimulus reconnects a moved
+   * element within the same mutation batch, before the checkpoint drains.
+   */
+  disconnected(host, teardown) {
+    if (_DetachGate.isDetached(host)) {
+      this.#pending = false;
+      teardown();
+      return;
+    }
+    this.#pending = true;
+    queueMicrotask(() => {
+      if (!this.#pending) return;
+      this.#pending = false;
+      teardown();
+    });
+  }
+  /**
+   * Disarms a pending probe. Call from `connect()` (the reconnect that proves
+   * an in-page move) and from the head of any teardown path not routed through
+   * {@link disconnected} (disabled-toggle, Escape), so an orphaned probe can
+   * never run the teardown a second time.
+   */
+  cancel() {
+    this.#pending = false;
+  }
+};
+
 // src/utils/event_owner.ts
 function ownerIndex(candidates, node) {
   if (!(node instanceof Node)) return -1;
   return candidates.findIndex((candidate) => candidate.contains(node));
 }
 
+// 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/microtask_coalescer.ts
 var MicrotaskCoalescer = class {
   #run;
@@ -219,11 +298,61 @@ var SafeInterval = 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/controllers/carousel_controller.ts
 var DEFAULT_INTERVAL = 5e3;
 var OBSERVED_ATTRIBUTES = ["aria-selected", "data-state", "hidden"];
 var CarouselController = class extends Controller {
-  static targets = ["slide", "viewport", "prev", "next", "picker", "playToggle"];
+  static targets = [
+    "slide",
+    "viewport",
+    "prev",
+    "next",
+    "picker",
+    "playToggle",
+    "onLabel",
+    "offLabel"
+  ];
   static values = {
     autoplay: { type: Boolean, default: false },
     interval: { type: Number, default: DEFAULT_INTERVAL },
@@ -248,7 +377,16 @@ var CarouselController = class extends Controller {
   #ariaLive = new AttributeLease("aria-live");
   /** Pairs with {@link CarouselController.#ariaLive}: only the changed slide is read. */
   #ariaAtomic = new AttributeLease("aria-atomic");
+  /** The label pair a play toggle may carry, one half per rotation state. */
+  #labels = new StateRegions({
+    whenTrue: () => this.onLabelTargets,
+    whenFalse: () => this.offLabelTargets
+  });
   #beforeCache = new BeforeCacheReset(() => this.#returnLeases());
+  /** Tells an in-page move, which keeps the rotation, from a real detach. */
+  #gate = new DetachGate();
+  /** The next pointer movement, listened for while a pointer suspension waits on it. */
+  #pointer = new ListenerSet();
   /**
    * Events an authored action binding already took. The delegated listener runs
    * later — it sits on the controller element, above every control — so it can
@@ -268,12 +406,17 @@ var CarouselController = class extends Controller {
   #activeSlide = null;
   /** Slide count at the last resolved state, so a changed total is reportable. */
   #total = 0;
-  /** Pointer rests on the carousel: a suspension that lifts on `mouseleave`. */
+  /**
+   * Pointer rests on the carousel: a suspension that lifts on `mouseleave`, or on the
+   * pointer movement that confirms a suspension a move or a connect left unconfirmed.
+   */
   #pointerPaused = false;
   /** Focus is inside the carousel: a suspension that lifts when it leaves. */
   #focusPaused = false;
   /** The tab is in the background: a suspension that lifts when it returns. */
   #hiddenPaused = false;
+  /** Reduced motion holds back the intent declared at connect, until a press or a new one. */
+  #motionHold = false;
   /** Id of the live autoplay interval, or null when stopped. */
   #timerId = null;
   /** Delay the live interval was armed with, so an `interval` change re-arms it. */
@@ -289,17 +432,24 @@ var CarouselController = class extends Controller {
    * Renders the initial slide, wires the delegated listeners, and starts autoplay
    * when requested.
    *
-   * Every suspension is re-derived from the environment rather than carried, so an
-   * in-page move — which Stimulus delivers to the *same* controller instance as
-   * `disconnect()` then `connect()` — cannot strand the carousel in a suspension
-   * whose lifting event will never arrive. The attribute observer starts after the
-   * first render so the controller's own opening writes are not fed back to it.
+   * Focus, the tab's visibility and the reduced-motion hold are read afresh. The
+   * pointer is not something the document can answer yet: no `mouseleave` reaches a
+   * node that moved, and `:hover` can answer from before the move until the pointer
+   * moves again. So an in-page move — which Stimulus delivers to the *same* controller
+   * instance as `disconnect()` then `connect()` — keeps the pointer suspension it had,
+   * `:hover` reading true adds one, and either waits for the next pointer movement to
+   * be confirmed or lifted. A rotation the move carried is still running, so the edges
+   * are judged against it. The attribute observer starts after the first render so the
+   * controller's own opening writes are not fed back to it.
    */
   connect() {
-    this.#pointerPaused = this.element.matches(":hover");
+    const moved = this.#gate.pending;
+    this.#gate.cancel();
+    this.#pointerPaused = moved && this.#pointerPaused || this.element.matches(":hover");
+    if (this.#pointerPaused) this.#awaitPointer();
     this.#focusPaused = this.element.contains(document.activeElement);
     this.#hiddenPaused = document.visibilityState === "hidden";
-    if (this.autoplayValue && prefersReducedMotion()) this.autoplayValue = false;
+    this.#motionHold = prefersReducedMotion();
     this.#index = this.#resolveIndex();
     this.#render({ focus: false });
     this.#total = this.slideTargets.length;
@@ -321,9 +471,15 @@ var CarouselController = class extends Controller {
       attributeFilter: OBSERVED_ATTRIBUTES
     });
   }
-  /** Releases every listener and observer, returns the leased ARIA, drops the suspensions. */
+  /**
+   * Releases every listener and observer, returns the leased ARIA, drops the focus
+   * and tab suspensions. The rotation goes through the detach gate: a reconnect in
+   * the same batch — an in-page move — keeps it, and the pointer suspension with it;
+   * anything else ends it.
+   */
   disconnect() {
     this.#connected = false;
+    this.#pointer.dispose();
     this.element.removeEventListener("click", this.#onClick);
     this.element.removeEventListener("keydown", this.#onKeydown);
     this.element.removeEventListener("focusin", this.#onFocusin);
@@ -334,14 +490,12 @@ var CarouselController = class extends Controller {
     this.#observer?.disconnect();
     this.#observer = null;
     this.#reconcileTargets.cancel();
-    this.#intervals.clearAll();
-    this.#timerId = null;
-    this.#pointerPaused = false;
     this.#focusPaused = false;
     this.#hiddenPaused = false;
     this.#activeSlide = null;
     this.#returnLeases();
     this.#beforeCache.deactivate();
+    this.#gate.disconnected(this, () => this.#endRun());
   }
   /**
    * Re-establishes the single selected picker when one is added after connect.
@@ -368,19 +522,46 @@ var CarouselController = class extends Controller {
   slideTargetDisconnected() {
     this.#reconcileTargets.schedule();
   }
-  /** Follows a rotation intent the page changed at runtime. */
-  autoplayValueChanged() {
+  /**
+   * Publishes the rotation state on a toggle that joins a connected carousel.
+   *
+   * A toggle the markup already carries connects ahead of `connect()`, where the
+   * suspensions and the reduced-motion hold are not settled yet; the opening pass
+   * covers it.
+   */
+  playToggleTargetConnected() {
     if (this.#connected) this.#syncTimer();
   }
+  /**
+   * Publishes the rotation state on a label half that joins a connected toggle.
+   *
+   * A half arriving changes the toggle's subtree, not its attributes, so the
+   * attribute observer never sees it; where the arrival completes a pair that was
+   * standing alone, this is what makes that pair whole and reflectable.
+   */
+  onLabelTargetConnected() {
+    if (this.#connected) this.#syncTimer();
+  }
+  /** Publishes the rotation state on a label half that joins a connected toggle. */
+  offLabelTargetConnected() {
+    if (this.#connected) this.#syncTimer();
+  }
+  /** Follows a rotation intent the page changed at runtime, lifting the reduced-motion hold. */
+  autoplayValueChanged() {
+    if (!this.#connected) return;
+    this.#motionHold = false;
+    this.#syncTimer();
+  }
   /** Re-arms the live interval at the new delay without reporting a state change. */
   intervalValueChanged() {
     if (this.#connected) this.#syncTimer();
   }
-  /** Re-publishes the step controls and re-evaluates the non-looping end. */
+  /**
+   * Re-publishes the step controls and re-evaluates the non-looping end through the
+   * reconcile pass, which reports a move only when the position changed.
+   */
   loopValueChanged() {
-    if (!this.#connected) return;
-    this.#render({ focus: false });
-    this.#syncTimer();
+    this.#reconcileTargets.schedule();
   }
   /** Advances to the next slide. Delegated; `data-action` wiring is optional. */
   next(event) {
@@ -402,11 +583,11 @@ var CarouselController = class extends Controller {
     if (index !== -1) this.#select(index, { focus: false });
   }
   /**
-   * Flips the rotation intent on the user's explicit request.
+   * Flips the rotation intent the toggle shows, on the user's explicit request.
    *
-   * The intent is written back to the `autoplay` Value, which is where every other
-   * path reads it from. A carousel with nothing to advance to has no intent to
-   * flip: the toggle is marked `aria-disabled` and does nothing.
+   * The result is written to the `autoplay` Value, which is where every other path
+   * reads it from. A carousel with nothing to advance to has no intent to flip: the
+   * toggle is marked `aria-disabled` and does nothing.
    */
   togglePlay(event) {
     if (event?.defaultPrevented) return;
@@ -422,7 +603,7 @@ var CarouselController = class extends Controller {
   pause(event) {
     this.#markHandled(event);
     if (isFocusEvent(event)) this.#focusPaused = true;
-    else this.#pointerPaused = true;
+    else this.#setPointerPaused(true);
     this.#syncTimer();
   }
   /**
@@ -437,7 +618,7 @@ var CarouselController = class extends Controller {
       if (this.#focusStaysInside(event)) return;
       this.#focusPaused = false;
     } else {
-      this.#pointerPaused = false;
+      this.#setPointerPaused(false);
     }
     this.#syncTimer();
   }
@@ -479,14 +660,36 @@ var CarouselController = class extends Controller {
   });
   /** Pointer entry suspends the rotation. */
   #onMouseenter = (event) => this.#delegate(event, () => {
-    this.#pointerPaused = true;
+    this.#setPointerPaused(true);
     this.#syncTimer();
   });
   /** Pointer exit lifts the suspension. */
   #onMouseleave = (event) => this.#delegate(event, () => {
-    this.#pointerPaused = false;
+    this.#setPointerPaused(false);
     this.#syncTimer();
   });
+  /**
+   * Reads `:hover` once the pointer has moved, when the answer is current, and lifts
+   * the pointer suspension if the pointer is not over the carousel. Listens once.
+   */
+  #onPointerMove = () => {
+    this.#pointer.dispose();
+    if (this.element.matches(":hover")) return;
+    this.#pointerPaused = false;
+    this.#syncTimer();
+  };
+  /** Leaves the pointer suspension to be confirmed or lifted on the next pointer movement. */
+  #awaitPointer() {
+    this.#pointer.add(document, "pointermove", this.#onPointerMove, {
+      capture: true,
+      passive: true
+    });
+  }
+  /** Records the pointer suspension; a newer answer ends any wait on the next movement. */
+  #setPointerPaused(paused) {
+    this.#pointer.dispose();
+    this.#pointerPaused = paused;
+  }
   /**
    * Schedules one reconciliation when a state attribute is rewritten in place —
    * the only shape of change no target callback reports.
@@ -523,10 +726,12 @@ var CarouselController = class extends Controller {
     const next = event.relatedTarget;
     return next instanceof Node && this.element.contains(next);
   }
-  /** Flips the rotation intent, unless there is nothing to rotate to. */
+  /** Flips the rotation intent unless there is nothing to rotate to; lifts the motion hold. */
   #togglePlay() {
     if (!this.#canAutoplay()) return;
-    this.autoplayValue = !this.autoplayValue;
+    const next = !this.#intent;
+    this.#motionHold = false;
+    this.autoplayValue = next;
     this.#syncTimer();
   }
   /** Applies the APG picker key map: arrows, Home, and End all move focus only. */
@@ -585,8 +790,7 @@ var CarouselController = class extends Controller {
   /**
    * Changes the active slide, updates state hooks, and emits `change` — but only
    * when the index actually changes, so a `next`/`prev` clamped at the end (or an
-   * autoplay tick at a non-looping boundary) re-renders without a spurious event
-   * (matching the "emit on real change" policy of flash/masonry/bulk-select).
+   * autoplay tick at a non-looping boundary) re-renders without a spurious event.
    */
   #select(index, { focus }) {
     const target = this.#clampToSlides(index);
@@ -673,6 +877,10 @@ var CarouselController = class extends Controller {
       this.dispatch("reconcile", { detail: { index: this.#index, total: this.#total } });
     }
   }
+  /** The rotation intent in effect: `autoplay`, unless reduced motion holds it back. */
+  get #intent() {
+    return this.autoplayValue && !this.#motionHold;
+  }
   /** Whether autoplay has anywhere left to advance to. */
   #canAutoplay() {
     const total = this.slideTargets.length;
@@ -688,15 +896,18 @@ var CarouselController = class extends Controller {
    * Drives the autoplay interval toward the desired state and publishes it.
    *
    * Rotation runs when the intent is on, nothing suspends it, and a slide is left
-   * to advance to. A carousel that has run out normalizes the intent to `false`, so
-   * `aria-pressed` never claims a rotation that cannot happen. Crossing the
-   * run/stop boundary emits `play`/`pause`; re-arming at a new `interval` is the
-   * same state and stays silent.
+   * to advance to. The toggle shows the intent only while a slide is left, so
+   * `aria-pressed` never claims a rotation that cannot happen. This body reads
+   * `autoplay` and never writes it, so the declared intent returns once a slide
+   * lies ahead again. Crossing the run/stop boundary emits `play`/`pause`;
+   * re-arming at a new `interval` is the same state and stays silent.
+   *
+   * @stimeoRenderRoot
    */
   #syncTimer() {
     const canAutoplay = this.#canAutoplay();
-    if (this.autoplayValue && !canAutoplay) this.autoplayValue = false;
-    const shouldRun = this.autoplayValue && canAutoplay && !this.#pointerPaused && !this.#focusPaused && !this.#hiddenPaused;
+    const pressed = this.#intent && canAutoplay;
+    const shouldRun = pressed && !this.#pointerPaused && !this.#focusPaused && !this.#hiddenPaused;
     const wasRunning = this.#timerId !== null;
     const interval = this.#interval;
     if (this.#timerId !== null && (!shouldRun || interval !== this.#timerInterval)) {
@@ -713,14 +924,28 @@ var CarouselController = class extends Controller {
       else this.dispatch("pause");
     }
     for (const toggle of this.playToggleTargets) {
-      toggle.setAttribute("aria-pressed", this.autoplayValue ? "true" : "false");
+      toggle.setAttribute("aria-pressed", pressed ? "true" : "false");
       this.#ariaDisabled.write(toggle, canAutoplay ? null : "true");
+      this.#labels.reflect(toggle, pressed);
     }
     if (this.hasViewportTarget) {
       this.#ariaLive.write(this.viewportTarget, shouldRun ? "off" : "polite");
       this.#ariaAtomic.write(this.viewportTarget, "false");
     }
   }
+  /**
+   * Ends the rotation once the controller has really left. A carousel still in
+   * the document hears the end — `pause`, and `data-state="paused"` — so no `play`
+   * it reported is left without one; a detached tree keeps the markup it had.
+   */
+  #endRun() {
+    const wasRunning = this.#timerId !== null;
+    this.#intervals.clearAll();
+    this.#timerId = null;
+    if (!wasRunning || !this.element.isConnected) return;
+    setAttributeIfChanged(this.element, "data-state", "paused");
+    this.dispatch("pause");
+  }
   /** Hands every leased attribute back to the value the consumer authored. */
   #returnLeases() {
     this.#ariaDisabled.returnAll();