stimeo-ui 0.3.0 → 0.4.0

data/dist/controllers/network_status_controller.js

@@ -2,6 +2,23 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/network_status_controller.ts
 
+// src/utils/announce.ts
+function announce(message, options = {}) {
+  const text = message.trim();
+  if (text.length === 0) return;
+  window.dispatchEvent(
+    new CustomEvent("stimeo--announcer:announce", {
+      detail: { message: text, assertive: options.assertive === true }
+    })
+  );
+}
+function fillTemplate(template, values) {
+  return template.replace(/\{([a-zA-Z][a-zA-Z0-9]*)\}/g, (match, name) => {
+    const replacement = values[name];
+    return replacement === void 0 ? match : String(replacement);
+  });
+}
+
 // src/utils/safe_timeout.ts
 var TimerRegistry = class {
   /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
@@ -59,20 +76,17 @@ var SafeTimeout = class extends TimerRegistry {
 var NetworkStatusController = class extends Controller {
   static targets = ["offline", "online"];
   static values = {
+    announceText: { type: String, default: "" },
+    announceOnlineText: { type: String, default: "" },
     onlineAutoHide: { type: Number, default: 0 }
   };
   static events = ["change"];
   #timers = new SafeTimeout();
   /** Last known connectivity; guards against duplicate-state re-announcements. */
   #online = true;
-  /** Banner text captured from the markup so transitions can re-write it. */
-  #offlineMessage = "";
-  #onlineMessage = "";
   #handleOnline = () => this.#update(true);
   #handleOffline = () => this.#update(false);
   connect() {
-    this.#offlineMessage = this.hasOfflineTarget ? (this.offlineTarget.textContent ?? "").trim() : "";
-    this.#onlineMessage = this.hasOnlineTarget ? (this.onlineTarget.textContent ?? "").trim() : "";
     if (this.hasOfflineTarget) this.offlineTarget.hidden = true;
     if (this.hasOnlineTarget) this.onlineTarget.hidden = true;
     this.#online = navigator.onLine;
@@ -86,7 +100,12 @@ var NetworkStatusController = class extends Controller {
     window.removeEventListener("offline", this.#handleOffline);
     this.#timers.clearAll();
   }
-  /** Applies a connectivity transition, guarded against duplicate states. */
+  /**
+   * Applies a connectivity transition, guarded against duplicate states.
+   *
+   * The event goes out last, so a listener reading `data-state` or a banner's
+   * visibility sees the state the transition landed on rather than the previous one.
+   */
   #update(online) {
     if (online === this.#online) return;
     this.#online = online;
@@ -96,6 +115,9 @@ var NetworkStatusController = class extends Controller {
     } else {
       this.#showOffline();
     }
+    announce(fillTemplate(online ? this.announceOnlineTextValue : this.announceTextValue, {}), {
+      assertive: !online
+    });
     this.dispatch("change", { detail: { online } });
   }
   /** Shows the offline banner and hides the recovery banner. */
@@ -103,7 +125,6 @@ var NetworkStatusController = class extends Controller {
     this.#timers.clearAll();
     if (this.hasOnlineTarget) this.onlineTarget.hidden = true;
     if (this.hasOfflineTarget) {
-      this.offlineTarget.textContent = this.#offlineMessage;
       this.offlineTarget.hidden = false;
     }
   }
@@ -111,7 +132,6 @@ var NetworkStatusController = class extends Controller {
   #showOnline() {
     if (this.hasOfflineTarget) this.offlineTarget.hidden = true;
     if (!this.hasOnlineTarget) return;
-    this.onlineTarget.textContent = this.#onlineMessage;
     this.onlineTarget.hidden = false;
     if (this.onlineAutoHideValue > 0) {
       this.#timers.set(() => {

data/dist/controllers/overflow_menu_controller.js

@@ -2,6 +2,35 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/overflow_menu_controller.ts
 
+// src/utils/before_cache_reset.ts
+var BeforeCacheReset = class _BeforeCacheReset {
+  /** Every subscribed instance, iterated by the one shared document listener. */
+  static #subscribers = /* @__PURE__ */ new Set();
+  /** The shared listener; installed while at least one instance is subscribed. */
+  static #onBeforeCache = () => {
+    for (const subscriber of _BeforeCacheReset.#subscribers) subscriber.#rewind();
+  };
+  #rewind;
+  /** @param rewind - the pass that returns this controller's state to its initial form. */
+  constructor(rewind) {
+    this.#rewind = rewind;
+  }
+  /** Subscribes to `turbo:before-cache`; call from `connect()`. Idempotent. */
+  activate() {
+    const first = _BeforeCacheReset.#subscribers.size === 0;
+    _BeforeCacheReset.#subscribers.add(this);
+    if (first) {
+      document.addEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+    }
+  }
+  /** Unsubscribes; call from `disconnect()`. Safe when never subscribed. */
+  deactivate() {
+    _BeforeCacheReset.#subscribers.delete(this);
+    if (_BeforeCacheReset.#subscribers.size > 0) return;
+    document.removeEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+  }
+};
+
 // src/utils/focus_candidate.ts
 function inheritsFieldsetDisabled(control) {
   let fieldset = control.closest("fieldset[disabled]");
@@ -183,17 +212,15 @@ var OverflowMenuController = class extends Controller {
   #lastHidden = null;
   /** The `tabindex` this instance lends the root for the focus fallback. */
   #tabindex = new TabindexLoan();
-  /** Hands Turbo a pristine snapshot: the cache is written after this event. */
-  #onBeforeCache = () => {
-    this.#restoreAll();
-  };
+  /** Hands Turbo a pristine snapshot of the bar, with every item back in place. */
+  #beforeCache = new BeforeCacheReset(() => this.#restoreAll());
   connect() {
     if (!this.hasItemsTarget || !this.hasMoreTarget) return;
     const trigger = this.#trigger();
     if (trigger !== null && this.#isBareTrigger(trigger)) {
       trigger.textContent = this.moreLabelValue;
     }
-    document.addEventListener("turbo:before-cache", this.#onBeforeCache);
+    this.#beforeCache.activate();
     this.#layout.observe(this.element);
     this.#layout.observeViewport();
     this.update();
@@ -201,7 +228,7 @@ var OverflowMenuController = class extends Controller {
   disconnect() {
     this.#layout.disconnect();
     this.#timers.clearAll();
-    document.removeEventListener("turbo:before-cache", this.#onBeforeCache);
+    this.#beforeCache.deactivate();
     this.#restoreAll();
     this.#lastHidden = null;
   }

data/dist/controllers/progress_controller.js

@@ -2,6 +2,23 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/progress_controller.ts
 
+// src/utils/announce.ts
+function announce(message, options = {}) {
+  const text = message.trim();
+  if (text.length === 0) return;
+  window.dispatchEvent(
+    new CustomEvent("stimeo--announcer:announce", {
+      detail: { message: text, assertive: options.assertive === true }
+    })
+  );
+}
+function fillTemplate(template, values) {
+  return template.replace(/\{([a-zA-Z][a-zA-Z0-9]*)\}/g, (match, name) => {
+    const replacement = values[name];
+    return replacement === void 0 ? match : String(replacement);
+  });
+}
+
 // src/utils/coerce.ts
 function toFiniteNumber(raw) {
   if (raw === null || raw === void 0 || raw === "") return null;
@@ -9,7 +26,57 @@ function toFiniteNumber(raw) {
   return Number.isFinite(value) ? value : null;
 }
 
+// src/utils/microtask_coalescer.ts
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  /** @param run - the single reconciliation pass, invoked at most once per batch. */
+  constructor(run) {
+    this.#run = run;
+  }
+  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
+  activate() {
+    this.#active = true;
+  }
+  /** Closes the window and drops any pending pass; call from `disconnect()`. */
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
+  schedule() {
+    if (!this.#active || this.#queued) return;
+    this.#queued = true;
+    const generation = this.#generation;
+    queueMicrotask(() => {
+      if (generation !== this.#generation || !this.#queued || !this.#active) return;
+      this.#queued = false;
+      this.#run();
+    });
+  }
+};
+
+// src/utils/range.ts
+function rangeFraction(value, min, max) {
+  const span = max - min;
+  if (!(span > 0)) return 0;
+  const clamped = Math.min(max, Math.max(min, value));
+  let fraction;
+  if (Number.isFinite(span)) {
+    fraction = (clamped - min) / span;
+  } else {
+    const scale = Math.max(Math.abs(min), Math.abs(max));
+    fraction = (clamped / scale - min / scale) / (max / scale - min / scale);
+  }
+  if (!Number.isFinite(fraction)) return 0;
+  return Math.min(1, Math.max(0, fraction));
+}
+
 // src/controllers/progress_controller.ts
+var OWNED_VALUE_TEXT = "data-stimeo--progress-owns-valuetext";
 var ProgressController = class extends Controller {
   static targets = ["bar"];
   static values = {
@@ -17,13 +84,27 @@ var ProgressController = class extends Controller {
     min: { type: Number, default: 0 },
     max: { type: Number, default: 100 },
     indeterminate: { type: Boolean, default: false },
-    valueText: { type: String, default: "" }
+    valueText: { type: String, default: "" },
+    announceText: { type: String, default: "" }
   };
   static actions = ["setValue"];
   static events = ["change", "complete"];
+  /**
+   * Collapses a morph that swaps several render inputs at once into one repaint.
+   * A single update usually rewrites the whole set, and each Value would otherwise
+   * repaint on its own.
+   */
+  #repaint = new MicrotaskCoalescer(() => {
+    this.#render();
+  });
   connect() {
+    this.#repaint.activate();
     this.#render();
   }
+  /** Closes the window in which a queued repaint may still run. */
+  disconnect() {
+    this.#repaint.cancel();
+  }
   /**
    * Updates the progress value from an action param (`amount`) or a
    * `detail.value` CustomEvent, normalizes it into range, syncs ARIA, and
@@ -39,11 +120,30 @@ var ProgressController = class extends Controller {
     this.dispatch("change", { detail: { value, ratio: this.#ratio } });
     if (value >= this.maxValue) {
       this.dispatch("complete", { detail: { value } });
+      announce(
+        fillTemplate(this.announceTextValue, { value, percent: Math.round(this.#ratio * 100) })
+      );
     }
   }
-  /** Re-render when the indeterminate flag is toggled via its data attribute. */
+  /** Repaints when application code (or a Turbo morph) changes `indeterminate` at runtime. */
   indeterminateValueChanged() {
-    this.#render();
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `value` at runtime. */
+  valueValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `min` at runtime. */
+  minValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `max` at runtime. */
+  maxValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `valueText` at runtime. */
+  valueTextValueChanged() {
+    this.#repaint.schedule();
   }
   /** Clamps `raw` into the configured `[min, max]` range. */
   #clamp(raw) {
@@ -51,9 +151,7 @@ var ProgressController = class extends Controller {
   }
   /** Current fraction of the range in `[0, 1]`; `0` when the range is empty. */
   get #ratio() {
-    const span = this.maxValue - this.minValue;
-    if (span <= 0) return 0;
-    return (this.#clamp(this.valueValue) - this.minValue) / span;
+    return rangeFraction(this.valueValue, this.minValue, this.maxValue);
   }
   /** Reflects value/range/indeterminate onto ARIA, `data-state`, and the ratio. */
   #render() {
@@ -61,7 +159,7 @@ var ProgressController = class extends Controller {
     this.element.setAttribute("aria-valuemax", String(this.maxValue));
     if (this.indeterminateValue) {
       this.element.removeAttribute("aria-valuenow");
-      this.element.removeAttribute("aria-valuetext");
+      this.#clearOwnValueText();
       this.element.style.removeProperty("--stimeo-progress-ratio");
       this.element.setAttribute("data-state", "indeterminate");
       return;
@@ -75,16 +173,25 @@ var ProgressController = class extends Controller {
   /**
    * Sets `aria-valuetext` from the consumer-provided template, substituting
    * `{value}` and `{percent}`. Left to the consumer so the human-readable text
-   * stays i18n-neutral in the library; cleared when no template is given.
+   * stays i18n-neutral in the library. With no template the attribute belongs to
+   * the consumer, so only a text this controller wrote is taken back
+   * ({@link OWNED_VALUE_TEXT}).
    */
   #applyValueText(value) {
     if (this.valueTextValue.length === 0) {
-      this.element.removeAttribute("aria-valuetext");
+      this.#clearOwnValueText();
       return;
     }
     const percent = Math.round(this.#ratio * 100);
     const text = this.valueTextValue.replaceAll("{value}", String(value)).replaceAll("{percent}", String(percent));
     this.element.setAttribute("aria-valuetext", text);
+    this.element.setAttribute(OWNED_VALUE_TEXT, "");
+  }
+  /** Removes `aria-valuetext` only when this controller is the one that wrote it. */
+  #clearOwnValueText() {
+    if (!this.element.hasAttribute(OWNED_VALUE_TEXT)) return;
+    this.element.removeAttribute("aria-valuetext");
+    this.element.removeAttribute(OWNED_VALUE_TEXT);
   }
 };
 

data/dist/controllers/range_slider_controller.js

@@ -18,6 +18,55 @@ function isReservedArrowChord(event, allow = []) {
   return event.altKey && !allow.includes("alt") || event.ctrlKey && !allow.includes("ctrl") || event.metaKey && !allow.includes("meta") || event.shiftKey && !allow.includes("shift");
 }
 
+// src/utils/microtask_coalescer.ts
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  /** @param run - the single reconciliation pass, invoked at most once per batch. */
+  constructor(run) {
+    this.#run = run;
+  }
+  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
+  activate() {
+    this.#active = true;
+  }
+  /** Closes the window and drops any pending pass; call from `disconnect()`. */
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
+  schedule() {
+    if (!this.#active || this.#queued) return;
+    this.#queued = true;
+    const generation = this.#generation;
+    queueMicrotask(() => {
+      if (generation !== this.#generation || !this.#queued || !this.#active) return;
+      this.#queued = false;
+      this.#run();
+    });
+  }
+};
+
+// src/utils/range.ts
+function rangeFraction(value, min, max) {
+  const span = max - min;
+  if (!(span > 0)) return 0;
+  const clamped = Math.min(max, Math.max(min, value));
+  let fraction;
+  if (Number.isFinite(span)) {
+    fraction = (clamped - min) / span;
+  } else {
+    const scale = Math.max(Math.abs(min), Math.abs(max));
+    fraction = (clamped / scale - min / scale) / (max / scale - min / scale);
+  }
+  if (!Number.isFinite(fraction)) return 0;
+  return Math.min(1, Math.max(0, fraction));
+}
+
 // src/controllers/range_slider_controller.ts
 var START_PROPERTY = "--stimeo-range-start";
 var END_PROPERTY = "--stimeo-range-end";
@@ -40,16 +89,33 @@ var RangeSliderController = class extends Controller {
     return this.logicalTrackValue && isRtl(this.element);
   }
   /** Normalizes the initial pair (clamped, snapped, ordered) and renders. */
+  /**
+   * Collapses a morph that swaps render inputs into one repaint, and refuses the
+   * pass Stimulus delivers before `connect()`.
+   */
+  #repaint = new MicrotaskCoalescer(() => {
+    this.#render(this.startValue, this.endValue);
+  });
   connect() {
+    this.#repaint.activate();
     const lo = Math.min(this.startValue, this.endValue);
     const hi = Math.max(this.startValue, this.endValue);
     this.#commit(lo, hi, false);
   }
   /** Cancels any active pointer drag so document listeners never leak. */
   disconnect() {
+    this.#repaint.cancel();
     this.#dragAbort?.abort();
     this.#dragAbort = null;
   }
+  /** Repaints when application code (or a Turbo morph) changes `min` at runtime. */
+  minValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `max` at runtime. */
+  maxValueChanged() {
+    this.#repaint.schedule();
+  }
   /** Keyboard stepping for whichever thumb is focused (the action's element). */
   onKeydown(event) {
     if (isReservedArrowChord(event)) return;
@@ -165,14 +231,13 @@ var RangeSliderController = class extends Controller {
       this.endThumbTarget.setAttribute("aria-valuemax", String(this.maxValue));
       this.endThumbTarget.setAttribute("aria-valuenow", String(end));
     }
-    const span = this.maxValue - this.minValue;
     this.element.style.setProperty(
       START_PROPERTY,
-      String(span > 0 ? (start - this.minValue) / span : 0)
+      String(rangeFraction(start, this.minValue, this.maxValue))
     );
     this.element.style.setProperty(
       END_PROPERTY,
-      String(span > 0 ? (end - this.minValue) / span : 0)
+      String(rangeFraction(end, this.minValue, this.maxValue))
     );
   }
   /** Clamps `raw` to `[min, max]` and snaps it to the nearest step from `min`. */

data/dist/controllers/rating_controller.js

@@ -13,6 +13,39 @@ function isReservedArrowChord(event, allow = []) {
   return event.altKey && !allow.includes("alt") || event.ctrlKey && !allow.includes("ctrl") || event.metaKey && !allow.includes("meta") || event.shiftKey && !allow.includes("shift");
 }
 
+// src/utils/microtask_coalescer.ts
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  /** @param run - the single reconciliation pass, invoked at most once per batch. */
+  constructor(run) {
+    this.#run = run;
+  }
+  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
+  activate() {
+    this.#active = true;
+  }
+  /** Closes the window and drops any pending pass; call from `disconnect()`. */
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
+  schedule() {
+    if (!this.#active || this.#queued) return;
+    this.#queued = true;
+    const generation = this.#generation;
+    queueMicrotask(() => {
+      if (generation !== this.#generation || !this.#queued || !this.#active) return;
+      this.#queued = false;
+      this.#run();
+    });
+  }
+};
+
 // src/utils/roving_tabindex.ts
 var RovingTabindex = class {
   /** Returns the current ordered item elements; called on every operation. */
@@ -59,13 +92,33 @@ var RatingController = class extends Controller {
   static events = ["change"];
   #roving = new RovingTabindex(() => this.symbolTargets);
   /** Reflects the initial value, or switches to the non-interactive readonly view. */
+  /**
+   * Collapses a morph that swaps render inputs into one repaint, and refuses the
+   * pass Stimulus delivers before `connect()`.
+   */
+  #repaint = new MicrotaskCoalescer(() => {
+    if (this.readonlyValue) {
+      this.#applyReadonly();
+      return;
+    }
+    this.#apply(this.#clamp(this.valueValue), { focus: false });
+  });
   connect() {
+    this.#repaint.activate();
     if (this.readonlyValue) {
       this.#applyReadonly();
       return;
     }
     this.#apply(this.#clamp(this.valueValue), { focus: false });
   }
+  /** Closes the window in which a queued repaint may still run. */
+  disconnect() {
+    this.#repaint.cancel();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `value` at runtime. */
+  valueValueChanged() {
+    this.#repaint.schedule();
+  }
   /** Selects (or clears) the clicked symbol. Bound via `data-action` (click). */
   select(event) {
     if (this.readonlyValue) return;