stimeo-ui 0.2.1 → 0.4.0

data/dist/controllers/meter_controller.js

@@ -2,6 +2,23 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/meter_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,10 +26,61 @@ 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/meter_controller.ts
+var OWNED_VALUE_TEXT = "data-stimeo--meter-owns-valuetext";
 var MeterController = class extends Controller {
   static targets = ["bar"];
   static values = {
+    announceText: { type: String, default: "" },
     value: { type: Number, default: 0 },
     min: { type: Number, default: 0 },
     max: { type: Number, default: 100 },
@@ -23,9 +91,24 @@ var MeterController = class extends Controller {
   };
   static actions = ["setValue"];
   static events = ["change"];
+  /**
+   * 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();
+  });
+  /** The segment last announced, so only a change is read out. */
+  #announcedState = null;
   connect() {
+    this.#repaint.activate();
     this.#render();
   }
+  /** Closes the window in which a queued repaint may still run. */
+  disconnect() {
+    this.#repaint.cancel();
+  }
   /**
    * Updates the measured value from an action param (`amount`) or a
    * `detail.value` CustomEvent, syncs ARIA and `data-state`, and dispatches
@@ -35,59 +118,95 @@ var MeterController = class extends Controller {
     const next = toFiniteNumber(event.params?.amount ?? event.detail?.value);
     if (next === null) return;
     this.valueValue = this.#clamp(next);
-    this.#render();
-    this.dispatch("change", {
-      detail: { value: this.valueValue, ratio: this.#ratio, state: this.#state }
-    });
+    const reading = this.#render();
+    this.dispatch("change", { detail: reading });
+    if (reading.state !== this.#announcedState) {
+      this.#announcedState = reading.state;
+      announce(
+        fillTemplate(this.announceTextValue, { state: reading.state, value: reading.value })
+      );
+    }
+  }
+  /** 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 `low` at runtime. */
+  lowValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `high` at runtime. */
+  highValueChanged() {
+    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) {
     return Math.min(this.maxValue, Math.max(this.minValue, raw));
   }
-  /** 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;
-  }
   /** Whether a threshold attribute is present (absent = no threshold). */
   #hasThreshold(name) {
     return this.element.hasAttribute(`data-stimeo--meter-${name}-value`);
   }
   /**
-   * Classifies the value into a `low`/`medium`/`high` segment. Values at or
-   * below `low` are `low`; at or above `high` are `high`; otherwise `medium`.
-   * With neither threshold present, everything is `medium`.
+   * Classifies `value` into a `low`/`medium`/`high` segment. Values at or below
+   * `low` are `low`; at or above `high` are `high`; otherwise `medium`. With
+   * neither threshold present, everything is `medium`.
    */
-  get #state() {
-    const value = this.#clamp(this.valueValue);
+  #stateOf(value) {
     if (this.#hasThreshold("low") && value <= this.lowValue) return "low";
     if (this.#hasThreshold("high") && value >= this.highValue) return "high";
     return "medium";
   }
-  /** Reflects value/range onto ARIA, the segment onto `data-state`, and the ratio. */
+  /**
+   * Reflects value/range onto ARIA, the segment onto `data-state`, and the ratio.
+   * The reading is derived once and returned, so the `change` detail reports the
+   * same numbers the DOM just received.
+   */
   #render() {
     const value = this.#clamp(this.valueValue);
+    const reading = {
+      value,
+      ratio: rangeFraction(value, this.minValue, this.maxValue),
+      state: this.#stateOf(value)
+    };
     this.element.setAttribute("aria-valuemin", String(this.minValue));
     this.element.setAttribute("aria-valuemax", String(this.maxValue));
-    this.element.setAttribute("aria-valuenow", String(value));
-    this.element.style.setProperty("--stimeo-meter-ratio", String(this.#ratio));
-    this.element.setAttribute("data-state", this.#state);
-    this.#applyValueText(value);
+    this.element.setAttribute("aria-valuenow", String(reading.value));
+    this.element.style.setProperty("--stimeo-meter-ratio", String(reading.ratio));
+    this.element.setAttribute("data-state", reading.state);
+    this.#applyValueText(reading);
+    return reading;
   }
   /**
    * Sets `aria-valuetext` from the consumer-provided template, substituting
-   * `{value}`, `{percent}`, and `{state}`. Kept i18n-neutral in the library;
-   * cleared when no template is given.
+   * `{value}`, `{percent}`, and `{state}`. Kept 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) {
+  #applyValueText({ value, ratio, state }) {
     if (this.valueTextValue.length === 0) {
-      this.element.removeAttribute("aria-valuetext");
+      if (this.element.hasAttribute(OWNED_VALUE_TEXT)) {
+        this.element.removeAttribute("aria-valuetext");
+        this.element.removeAttribute(OWNED_VALUE_TEXT);
+      }
       return;
     }
-    const percent = Math.round(this.#ratio * 100);
-    const text = this.valueTextValue.replaceAll("{value}", String(value)).replaceAll("{percent}", String(percent)).replaceAll("{state}", this.#state);
+    const percent = Math.round(ratio * 100);
+    const text = this.valueTextValue.replaceAll("{value}", String(value)).replaceAll("{percent}", String(percent)).replaceAll("{state}", state);
     this.element.setAttribute("aria-valuetext", text);
+    this.element.setAttribute(OWNED_VALUE_TEXT, "");
   }
 };