stimeo-ui 0.14.0 → 0.16.0

data/dist/controllers/countdown_controller.js

@@ -99,7 +99,12 @@ var SafeInterval = class extends TimerRegistry {
 
 // src/controllers/countdown_controller.ts
 var SECOND_MS = 1e3;
+var OWNED_STATUS = "owns-status";
 var CountdownController = class extends Controller {
+  /** The status marker, in the namespace this controller is registered under. */
+  get #ownedStatus() {
+    return `data-${this.identifier}-${OWNED_STATUS}`;
+  }
   static targets = ["days", "hours", "minutes", "seconds", "status"];
   static values = {
     deadline: { type: String, default: "" },
@@ -115,6 +120,12 @@ var CountdownController = class extends Controller {
   #intervalId = null;
   /** Collapses a morph that swaps several render inputs at once into one re-derive. */
   #resync = new MicrotaskCoalescer(() => this.#resyncToValues());
+  /**
+   * Whether `connect()` has run for this connection. Stimulus delivers Value
+   * callbacks ahead of it, while the run state is still the markup's own and not
+   * yet settled; `connect()` brings the status up to date once it is.
+   */
+  #connected = false;
   /** Epoch-ms anchor: the deadline (down) or the count-up origin (up). */
   #reference = 0;
   /** Amount (ms) captured at pause, so resume can restore the same display. */
@@ -127,28 +138,25 @@ var CountdownController = class extends Controller {
    */
   #renderedAmount = 0;
   connect() {
+    this.#connected = true;
     this.#resync.activate();
     this.#initReference();
     const amount = this.#currentAmount();
     this.#render(amount);
     this.#pausedAmount = this.#renderedAmount;
     const authored = this.element.getAttribute("data-state");
+    const settled = authored === "complete" && this.#isSettled(amount);
     if (authored === null) {
-      if (this.autostartValue && this.#isValidDeadline) {
-        this.start();
-        return;
-      }
+      if (this.autostartValue && this.#isValidDeadline) this.start();
+      else this.element.setAttribute("data-state", "paused");
+    } else if (!settled) {
       this.element.setAttribute("data-state", "paused");
-      return;
+      if (authored === "running") this.start();
     }
-    if (authored === "complete" && this.#isDown && amount <= 0) {
-      return;
-    }
-    const wasRunning = authored === "running";
-    this.element.setAttribute("data-state", "paused");
-    if (wasRunning) this.start();
+    this.#syncStatus();
   }
   disconnect() {
+    this.#connected = false;
     this.#resync.cancel();
     this.#intervals.clearAll();
     this.#intervalId = null;
@@ -161,6 +169,31 @@ var CountdownController = class extends Controller {
   directionValueChanged() {
     this.#resync.schedule();
   }
+  /**
+   * Follows a completion label swapped in place by a morph.
+   *
+   * Render only: `complete` is neither dispatched nor announced again. The status
+   * changes only after the countdown has completed, and only while it still shows
+   * the text this controller wrote there and nothing else, so text or an element
+   * the consumer put in the slot stays. A change delivered ahead of `connect()` is
+   * left to `connect()`.
+   */
+  completeLabelValueChanged() {
+    if (this.#connected) this.#syncStatus();
+  }
+  /**
+   * Keeps a status that still shows this controller's text, and nothing else, on
+   * what the run state calls for: the label in force while complete; otherwise the
+   * text is taken back, marker and all. A status holding anything else is the
+   * consumer's and is left alone, marker included.
+   *
+   * @stimeoRenderRoot
+   */
+  #syncStatus() {
+    if (!this.hasStatusTarget || !this.#ownsStatus(this.statusTarget)) return;
+    if (this.#state === "complete") this.#writeStatus(this.statusTarget, this.completeLabelValue);
+    else this.#releaseStatus(this.statusTarget);
+  }
   /**
    * Points the anchor at the current `deadline` / `direction` and repaints.
    *
@@ -168,13 +201,27 @@ var CountdownController = class extends Controller {
    * paused timer run or replay a milestone. A running one needs no restart either —
    * every tick reads the anchor, so moving it is enough. While paused the stored
    * amount follows the new reading, or resume would continue from the old deadline.
+   * A completion the new reading no longer settles (a deadline moved forward, or a
+   * count turned `up`) is handed back paused, as `connect()` hands back a restored
+   * one, so `resume()` counts again; the completion text this controller wrote goes
+   * with it, from a status slot that still shows it and nothing else.
+   *
+   * @stimeoRenderRoot
    */
   #resyncToValues() {
     this.#initReference();
-    this.#render(this.#currentAmount());
+    const amount = this.#currentAmount();
+    this.#render(amount);
+    if (this.#state === "complete" && !this.#isSettled(amount)) {
+      this.element.setAttribute("data-state", "paused");
+      this.#syncStatus();
+    }
     if (this.#state !== "running") this.#pausedAmount = this.#renderedAmount;
   }
-  /** Starts (or restarts after pause) ticking toward the deadline. */
+  /**
+   * Starts (or restarts after pause) ticking toward the deadline. Counting on from a
+   * completion takes this controller's completion text back out of the status.
+   */
   start() {
     if (this.#state === "running" || !this.#isValidDeadline) return;
     if (this.#isDown && this.#currentAmount() <= 0) {
@@ -212,10 +259,8 @@ var CountdownController = class extends Controller {
     this.#initReference();
     const amount = this.#currentAmount();
     this.#render(amount);
-    if (this.hasStatusTarget && this.statusTarget.textContent === this.completeLabelValue) {
-      this.statusTarget.textContent = "";
-    }
     this.element.setAttribute("data-state", "paused");
+    this.#syncStatus();
     if (wasRunning && this.#isValidDeadline) {
       this.#pausedAmount = 0;
       this.start();
@@ -223,9 +268,19 @@ var CountdownController = class extends Controller {
       this.#pausedAmount = this.#renderedAmount;
     }
   }
-  /** Schedules the repeating tick and marks the timer running. */
+  /**
+   * Schedules the repeating tick and marks the timer running. This is the one way
+   * into `running`, and a running timer keeps none of this controller's completion
+   * text in the status, so the status is settled here as on every other way out of
+   * `complete`: `start()` leaves a completion directly when `direction` flips to
+   * `up` and `start()` runs in the same task, ahead of the direction callback.
+   *
+   * @stimeoRuntimeOnly `interval` is the period of the one timer this call arms; the running state
+   *   it writes does not depend on a Value.
+   */
   #runInterval() {
     this.element.setAttribute("data-state", "running");
+    this.#syncStatus();
     this.#intervalId = this.#intervals.set(() => this.#tick(), this.intervalValue);
   }
   /** Cancels the repeating tick, if any. */
@@ -246,21 +301,73 @@ var CountdownController = class extends Controller {
       this.#complete();
     }
   }
-  /** Stops at zero, marks completion, announces it, and emits `complete`. */
+  /**
+   * Stops at zero, marks completion, writes the completion label, emits `complete`,
+   * and announces it.
+   *
+   * @stimeoRenderRoot
+   */
   #complete() {
     this.#teardownInterval();
     this.#render(0);
     this.element.setAttribute("data-state", "complete");
-    if (this.hasStatusTarget && this.completeLabelValue.length > 0) {
-      this.statusTarget.textContent = this.completeLabelValue;
-    }
+    this.#claimStatus();
     this.dispatch("complete", { detail: {} });
+    this.#announceCompletion();
+  }
+  /**
+   * Writes the label in force into the status slot as this controller's text. An
+   * empty label puts no text there: it claims a slot that is already empty — no
+   * text and no element — empties one that is still this controller's, and leaves
+   * any other slot, the consumer's, alone.
+   */
+  #claimStatus() {
+    if (!this.hasStatusTarget) return;
+    const status = this.statusTarget;
+    const label = this.completeLabelValue;
+    if (label === "" && !this.#isEmpty(status) && !this.#ownsStatus(status)) return;
+    this.#writeStatus(status, label);
+  }
+  /**
+   * Whether the status slot shows the text this controller wrote there and nothing
+   * else: the text matches the marker, and the slot holds no element. Writing the
+   * slot's text replaces every child node, so an element the consumer puts in the
+   * slot makes it theirs even while the text still matches. An empty marker
+   * matches the slot whenever it is empty.
+   */
+  #ownsStatus(status) {
+    return status.getAttribute(this.#ownedStatus) === status.textContent && status.firstElementChild === null;
+  }
+  /** Whether the status slot holds nothing at all: no text and no element. */
+  #isEmpty(status) {
+    return status.textContent === "" && status.firstElementChild === null;
+  }
+  /** Puts `text` into the status slot and records it as this controller's. */
+  #writeStatus(status, text) {
+    if (status.textContent !== text) status.textContent = text;
+    status.setAttribute(this.#ownedStatus, text);
+  }
+  /** Takes this controller's text out of the status slot, marker and all. */
+  #releaseStatus(status) {
+    status.textContent = "";
+    status.removeAttribute(this.#ownedStatus);
+  }
+  /**
+   * Reads the completion out through the shared announcer.
+   *
+   * @stimeoRuntimeOnly `announceText` words the one announcement a completion makes.
+   */
+  #announceCompletion() {
     announce(fillTemplate(this.announceTextValue, {}));
   }
   /** Sets the time anchor from the `deadline` value. */
   #initReference() {
     this.#reference = Date.parse(this.deadlineValue);
   }
+  /** Whether a reading of `amount` leaves nothing to count: only a countdown at zero. */
+  #isSettled(amount) {
+    return this.#isDown && amount <= 0;
+  }
   /** Remaining (down) or elapsed (up) ms, never negative. */
   #currentAmount() {
     if (!this.#isValidDeadline) return 0;
@@ -268,11 +375,7 @@ var CountdownController = class extends Controller {
     const raw = this.#isDown ? this.#reference - now : now - this.#reference;
     return Math.max(0, raw);
   }
-  /**
-   * Writes the amount into the day/hour/minute/second slots.
-   *
-   * @stimeoRenderRoot
-   */
+  /** Writes the amount into the day/hour/minute/second slots. */
   #render(amount) {
     const totalSeconds = Math.floor(amount / SECOND_MS);
     this.#renderedAmount = totalSeconds * SECOND_MS;