stimeo-ui 0.3.0 → 0.4.0

package/dist/controllers/meter_controller.d.ts

@@ -34,13 +34,18 @@ type SetValueEvent = Event & {
  * @remarks
  * Behavior only. Because state must not be conveyed by color alone (WCAG 1.4.1),
  * a consumer-provided `valueText` template feeds `aria-valuetext` so the segment
- * is also available as text. Threshold presence is read from the *attributes*
- * (an absent attribute means "no threshold"), not from a sentinel value.
+ * is also available as text; a consumer that authors `aria-valuetext` itself keeps
+ * it instead (see {@link OWNED_VALUE_TEXT}). Threshold presence is read from the
+ * *attributes* (an absent attribute means "no threshold"), not from a sentinel value.
  */
 declare class MeterController extends Controller<HTMLElement> {
     #private;
     static targets: string[];
     static values: {
+        announceText: {
+            type: StringConstructor;
+            default: string;
+        };
         value: {
             type: NumberConstructor;
             default: number;
@@ -81,13 +86,28 @@ declare class MeterController extends Controller<HTMLElement> {
     highValue: number;
     optimumValue: number;
     valueTextValue: string;
+    announceTextValue: string;
     connect(): void;
+    /** Closes the window in which a queued repaint may still run. */
+    disconnect(): void;
     /**
      * Updates the measured value from an action param (`amount`) or a
      * `detail.value` CustomEvent, syncs ARIA and `data-state`, and dispatches
      * `change` with the value, ratio, and computed segment.
      */
     setValue(event: SetValueEvent): void;
+    /** Repaints when application code (or a Turbo morph) changes `value` at runtime. */
+    valueValueChanged(): void;
+    /** Repaints when application code (or a Turbo morph) changes `min` at runtime. */
+    minValueChanged(): void;
+    /** Repaints when application code (or a Turbo morph) changes `max` at runtime. */
+    maxValueChanged(): void;
+    /** Repaints when application code (or a Turbo morph) changes `low` at runtime. */
+    lowValueChanged(): void;
+    /** Repaints when application code (or a Turbo morph) changes `high` at runtime. */
+    highValueChanged(): void;
+    /** Repaints when application code (or a Turbo morph) changes `valueText` at runtime. */
+    valueTextValueChanged(): void;
 }
 
 export { MeterController };

package/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, "");
   }
 };
 

package/dist/controllers/meter_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/coerce.ts","../../src/controllers/meter_controller.ts"],"names":[],"mappings":"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","file":"meter_controller.js","sourcesContent":["/**\n * Numeric coercion shared by the value-bearing controllers (progress, meter,\n * color-picker).\n *\n * Stimulus already coerces numeric action params to numbers, but a value can also\n * arrive as a string — via a `*:set` CustomEvent `detail`, or an action param\n * whose attribute does not look numeric. Centralizing the parse keeps `setValue`\n * tolerant of either form while rejecting anything that is not a finite number.\n */\n\n/**\n * Coerces `raw` to a finite number, or returns `null` when it is absent, empty,\n * or not parseable. Empty strings are treated as \"no value\" rather than `0`, so a\n * stray blank param cannot silently reset the value.\n */\nexport function toFiniteNumber(raw: number | string | null | undefined): number | null {\n  if (raw === null || raw === undefined || raw === \"\") return null;\n  const value = typeof raw === \"number\" ? raw : Number(raw);\n  return Number.isFinite(value) ? value : null;\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { toFiniteNumber } from \"../utils/coerce\";\n\n/**\n * Event shape `setValue` accepts: an action param `amount` or a `detail.value`.\n * Both are typed `number | string` because, while Stimulus coerces numeric action\n * params to numbers, a `meter:set` CustomEvent (or a non-numeric-looking param)\n * may carry a string; {@link MeterController.setValue} normalizes either form.\n */\ntype SetValueEvent = Event & {\n  params?: { amount?: number | string };\n  detail?: { value?: number | string };\n};\n\n/** Threshold segment a value falls into, reflected on `data-state`. */\ntype MeterState = \"low\" | \"medium\" | \"high\";\n\n/**\n * Headless meter behavior backed by the WAI-ARIA `meter` role.\n *\n * Markup contract (identifier: `stimeo--meter`):\n *   <div data-controller=\"stimeo--meter\" role=\"meter\" aria-label=\"Disk usage\"\n *        aria-valuemin=\"0\" aria-valuemax=\"100\" aria-valuenow=\"72\"\n *        data-stimeo--meter-value-value=\"72\"\n *        data-stimeo--meter-low-value=\"50\" data-stimeo--meter-high-value=\"80\">\n *     <div data-stimeo--meter-target=\"bar\"></div>\n *   </div>\n *\n * A `meter` is a *point-in-time* scalar within a known range (disk usage,\n * battery, score) — distinct from {@link ProgressController}'s task progress.\n * The controller syncs the ARIA value attributes and, when `low`/`high`\n * thresholds are present, classifies the value into a `low`/`medium`/`high`\n * segment on `data-state` so the consumer can color the bar.\n *\n * @remarks\n * Behavior only. Because state must not be conveyed by color alone (WCAG 1.4.1),\n * a consumer-provided `valueText` template feeds `aria-valuetext` so the segment\n * is also available as text. Threshold presence is read from the *attributes*\n * (an absent attribute means \"no threshold\"), not from a sentinel value.\n */\nexport class MeterController extends Controller<HTMLElement> {\n  static override targets = [\"bar\"];\n  static override values = {\n    value: { type: Number, default: 0 },\n    min: { type: Number, default: 0 },\n    max: { type: Number, default: 100 },\n    low: { type: Number, default: 0 },\n    high: { type: Number, default: 0 },\n    optimum: { type: Number, default: 0 },\n    valueText: { type: String, default: \"\" },\n  };\n  static actions = [\"setValue\"] as const;\n  static events = [\"change\"] as const;\n\n  declare readonly barTarget: HTMLElement;\n  declare readonly hasBarTarget: boolean;\n\n  declare valueValue: number;\n  declare minValue: number;\n  declare maxValue: number;\n  declare lowValue: number;\n  declare highValue: number;\n  declare optimumValue: number;\n  declare valueTextValue: string;\n\n  override connect(): void {\n    this.#render();\n  }\n\n  /**\n   * Updates the measured value from an action param (`amount`) or a\n   * `detail.value` CustomEvent, syncs ARIA and `data-state`, and dispatches\n   * `change` with the value, ratio, and computed segment.\n   */\n  setValue(event: SetValueEvent): void {\n    const next = toFiniteNumber(event.params?.amount ?? event.detail?.value);\n    if (next === null) return;\n    this.valueValue = this.#clamp(next);\n    this.#render();\n    this.dispatch(\"change\", {\n      detail: { value: this.valueValue, ratio: this.#ratio, state: this.#state },\n    });\n  }\n\n  /** Clamps `raw` into the configured `[min, max]` range. */\n  #clamp(raw: number): number {\n    return Math.min(this.maxValue, Math.max(this.minValue, raw));\n  }\n\n  /** Current fraction of the range in `[0, 1]`; `0` when the range is empty. */\n  get #ratio(): number {\n    const span = this.maxValue - this.minValue;\n    if (span <= 0) return 0;\n    return (this.#clamp(this.valueValue) - this.minValue) / span;\n  }\n\n  /** Whether a threshold attribute is present (absent = no threshold). */\n  #hasThreshold(name: \"low\" | \"high\"): boolean {\n    return this.element.hasAttribute(`data-stimeo--meter-${name}-value`);\n  }\n\n  /**\n   * Classifies the value into a `low`/`medium`/`high` segment. Values at or\n   * below `low` are `low`; at or above `high` are `high`; otherwise `medium`.\n   * With neither threshold present, everything is `medium`.\n   */\n  get #state(): MeterState {\n    const value = this.#clamp(this.valueValue);\n    if (this.#hasThreshold(\"low\") && value <= this.lowValue) return \"low\";\n    if (this.#hasThreshold(\"high\") && value >= this.highValue) return \"high\";\n    return \"medium\";\n  }\n\n  /** Reflects value/range onto ARIA, the segment onto `data-state`, and the ratio. */\n  #render(): void {\n    const value = this.#clamp(this.valueValue);\n    this.element.setAttribute(\"aria-valuemin\", String(this.minValue));\n    this.element.setAttribute(\"aria-valuemax\", String(this.maxValue));\n    this.element.setAttribute(\"aria-valuenow\", String(value));\n    this.element.style.setProperty(\"--stimeo-meter-ratio\", String(this.#ratio));\n    this.element.setAttribute(\"data-state\", this.#state);\n    this.#applyValueText(value);\n  }\n\n  /**\n   * Sets `aria-valuetext` from the consumer-provided template, substituting\n   * `{value}`, `{percent}`, and `{state}`. Kept i18n-neutral in the library;\n   * cleared when no template is given.\n   */\n  #applyValueText(value: number): void {\n    if (this.valueTextValue.length === 0) {\n      this.element.removeAttribute(\"aria-valuetext\");\n      return;\n    }\n    const percent = Math.round(this.#ratio * 100);\n    const text = this.valueTextValue\n      .replaceAll(\"{value}\", String(value))\n      .replaceAll(\"{percent}\", String(percent))\n      .replaceAll(\"{state}\", this.#state);\n    this.element.setAttribute(\"aria-valuetext\", text);\n  }\n}\n"]}
+{"version":3,"sources":["../../src/utils/announce.ts","../../src/utils/coerce.ts","../../src/utils/microtask_coalescer.ts","../../src/utils/range.ts","../../src/controllers/meter_controller.ts"],"names":[],"mappings":"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","file":"meter_controller.js","sourcesContent":["/**\n * Sends one message to the page's shared `stimeo--announcer`.\n *\n * A component that has to reach assistive tech does not carry a live region of its\n * own: a region only announces what changes *after* assistive tech already knows\n * about it, which a region that appears (or is un-hidden) with its message cannot\n * satisfy. The one region that can is the announcer sitting in the page from the\n * start, so state changes are handed to it as an event and it does the reading.\n *\n * The event goes to `window` because the announcer is usually a sibling high in the\n * document rather than an ancestor of the component dispatching it.\n *\n * Wording comes from the consumer — the library ships no English strings — so an\n * empty message is silently dropped and nothing is announced.\n *\n * @example\n * ```ts\n * announce(this.announceTextValue, { assertive: false });\n * ```\n */\nexport function announce(message: string, options: { assertive?: boolean } = {}): void {\n  const text = message.trim();\n  if (text.length === 0) return;\n  window.dispatchEvent(\n    new CustomEvent(\"stimeo--announcer:announce\", {\n      detail: { message: text, assertive: options.assertive === true },\n    }),\n  );\n}\n\n/**\n * Fills `{name}` placeholders in an announcement template from `values`.\n *\n * The same substitution the value-text templates use, so a consumer writes\n * `\"{percent}% complete\"` in one attribute and gets the same rules everywhere. A\n * placeholder with no matching entry is left as authored rather than blanked, which\n * keeps a typo visible instead of silently swallowing the word.\n */\nexport function fillTemplate(template: string, values: Record<string, string | number>): string {\n  return template.replace(/\\{([a-zA-Z][a-zA-Z0-9]*)\\}/g, (match, name: string) => {\n    const replacement = values[name];\n    return replacement === undefined ? match : String(replacement);\n  });\n}\n","/**\n * Numeric coercion shared by the value-bearing controllers (progress, meter,\n * color-picker).\n *\n * Stimulus already coerces numeric action params to numbers, but a value can also\n * arrive as a string — via a `*:set` CustomEvent `detail`, or an action param\n * whose attribute does not look numeric. Centralizing the parse keeps `setValue`\n * tolerant of either form while rejecting anything that is not a finite number.\n */\n\n/**\n * Coerces `raw` to a finite number, or returns `null` when it is absent, empty,\n * or not parseable. Empty strings are treated as \"no value\" rather than `0`, so a\n * stray blank param cannot silently reset the value.\n */\nexport function toFiniteNumber(raw: number | string | null | undefined): number | null {\n  if (raw === null || raw === undefined || raw === \"\") return null;\n  const value = typeof raw === \"number\" ? raw : Number(raw);\n  return Number.isFinite(value) ? value : null;\n}\n","/**\n * Collapses many target callbacks from one DOM mutation into a single pass.\n *\n * Stimulus fires `<name>TargetConnected` / `Disconnected` once per element, so\n * replacing a list of N options delivers N callbacks — but the useful unit of\n * work is \"reconcile against the DOM that resulted\", once, after the batch has\n * settled. Every controller that owns a reconcilable target set needs the same\n * shape: a `queued` flag plus `queueMicrotask`.\n *\n * **A microtask is the right horizon, and the reason is specific.** Stimulus\n * drives these callbacks from a `MutationObserver`, whose own callback already\n * runs as a microtask with the whole batch in hand; scheduling one more lands\n * after the last sibling callback of that batch and still before paint or any\n * event handler. A timer would be later than it needs to be, and reconciling\n * synchronously would run once per element against a half-applied DOM.\n *\n * **The two guards are not the same guard.** Scheduling is refused before the\n * controller connects, and running is refused after it disconnects:\n *\n * - **Before `connect()`** — Stimulus delivers the *initial* target callbacks\n *   ahead of `connect()`. Reconciling there would compute a fallback against a\n *   controller whose own state has not been initialised, and `connect()` is\n *   about to do a full pass anyway.\n * - **After `disconnect()`** — Stimulus fires a callback for **every** target\n *   during teardown, and a microtask queued just before it would otherwise run\n *   against a detached tree. {@link MicrotaskCoalescer.cancel} exists for the\n *   teardown path to drop the pending pass outright.\n *\n * Both guards are part of one contract here rather than something each consumer\n * has to remember separately.\n *\n * Scope is the scheduling only. *What* to reconcile — keep the surviving active\n * option, fall back to the next / previous / first visible one, rebuild derived\n * chips or hidden fields — stays in the controller, because no two consumers\n * answer it the same way.\n *\n * This file's own doc block is dropped from `dist`, but every member comment is\n * inlined into each consumer entry (`tsup` builds with `splitting: false`), so\n * rationale belongs here and only the contract belongs on the members.\n *\n * @example\n * ```ts\n * readonly #reconcile = new MicrotaskCoalescer(() => this.#reconcileOptions());\n *\n * connect()    { this.#reconcile.activate(); }\n * disconnect() { this.#reconcile.cancel(); }\n *\n * optionTargetConnected()    { this.#reconcile.schedule(); }\n * optionTargetDisconnected() { this.#reconcile.schedule(); }\n * ```\n */\nexport class MicrotaskCoalescer {\n  readonly #run: () => void;\n  #queued = false;\n  #active = false;\n  #generation = 0;\n\n  /** @param run - the single reconciliation pass, invoked at most once per batch. */\n  constructor(run: () => void) {\n    this.#run = run;\n  }\n\n  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */\n  activate(): void {\n    this.#active = true;\n  }\n\n  /** Closes the window and drops any pending pass; call from `disconnect()`. */\n  cancel(): void {\n    this.#active = false;\n    this.#queued = false;\n    this.#generation += 1;\n  }\n\n  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */\n  schedule(): void {\n    if (!this.#active || this.#queued) return;\n    this.#queued = true;\n    const generation = this.#generation;\n    queueMicrotask(() => {\n      // A cancelled callback must not consume a pass queued after reconnect.\n      if (generation !== this.#generation || !this.#queued || !this.#active) return;\n      this.#queued = false;\n      this.#run();\n    });\n  }\n}\n","/**\n * Range normalization shared by the value-bearing controllers (progress, meter,\n * slider, range-slider).\n *\n * Each of them publishes \"where the value sits inside `[min, max]`\" as a CSS\n * custom property the consumer multiplies a track by, and each has to answer the\n * same degenerate cases: empty and inverted ranges cannot express progress, and\n * malformed Number Values can produce `NaN`. Keeping the rule in one place is\n * what makes those answers identical across the four.\n */\n\n/**\n * Fraction of `[min, max]` that `value` occupies, always within `[0, 1]`.\n *\n * `value` is clamped into the range first, so a value outside it reports a full\n * or empty track rather than pushing the fraction past the ends.\n *\n * An empty, inverted, or non-numeric range yields `0`. That is a deliberate\n * floor rather than a computed result: `min === max` would produce `NaN`, and\n * `min > max` would report a full track for a value that is really out of range.\n * Non-finite results are floored for the same reason. These results reach\n * assistive tech, because the same fraction drives the percentage substituted\n * into `aria-valuetext`.\n */\nexport function rangeFraction(value: number, min: number, max: number): number {\n  const span = max - min;\n  if (!(span > 0)) return 0;\n\n  const clamped = Math.min(max, Math.max(min, value));\n  let fraction: number;\n  if (Number.isFinite(span)) {\n    fraction = (clamped - min) / span;\n  } else {\n    // Scaling preserves the ratio when two finite endpoints straddle zero so\n    // widely that their subtraction overflows to Infinity.\n    const scale = Math.max(Math.abs(min), Math.abs(max));\n    fraction = (clamped / scale - min / scale) / (max / scale - min / scale);\n  }\n\n  if (!Number.isFinite(fraction)) return 0;\n  return Math.min(1, Math.max(0, fraction));\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { announce, fillTemplate } from \"../utils/announce\";\nimport { toFiniteNumber } from \"../utils/coerce\";\nimport { MicrotaskCoalescer } from \"../utils/microtask_coalescer\";\nimport { rangeFraction } from \"../utils/range\";\n\n/**\n * Event shape `setValue` accepts: an action param `amount` or a `detail.value`.\n * Both are typed `number | string` because, while Stimulus coerces numeric action\n * params to numbers, a `meter:set` CustomEvent (or a non-numeric-looking param)\n * may carry a string; {@link MeterController.setValue} normalizes either form.\n */\ntype SetValueEvent = Event & {\n  params?: { amount?: number | string };\n  detail?: { value?: number | string };\n};\n\n/** Threshold segment a value falls into, reflected on `data-state`. */\ntype MeterState = \"low\" | \"medium\" | \"high\";\n\n/** One point-in-time reading: the clamped value with the ratio and segment it implies. */\ntype MeterReading = { value: number; ratio: number; state: MeterState };\n\n/**\n * Marks an `aria-valuetext` this controller wrote, so a render takes back only\n * its own text. `aria-valuetext` is shared: a consumer may author it instead of\n * supplying a template, and that text is what carries the threshold segment to\n * readers who cannot see the colour — clearing it would take the segment with it.\n */\nconst OWNED_VALUE_TEXT = \"data-stimeo--meter-owns-valuetext\";\n\n/**\n * Headless meter behavior backed by the WAI-ARIA `meter` role.\n *\n * Markup contract (identifier: `stimeo--meter`):\n *   <div data-controller=\"stimeo--meter\" role=\"meter\" aria-label=\"Disk usage\"\n *        aria-valuemin=\"0\" aria-valuemax=\"100\" aria-valuenow=\"72\"\n *        data-stimeo--meter-value-value=\"72\"\n *        data-stimeo--meter-low-value=\"50\" data-stimeo--meter-high-value=\"80\">\n *     <div data-stimeo--meter-target=\"bar\"></div>\n *   </div>\n *\n * A `meter` is a *point-in-time* scalar within a known range (disk usage,\n * battery, score) — distinct from {@link ProgressController}'s task progress.\n * The controller syncs the ARIA value attributes and, when `low`/`high`\n * thresholds are present, classifies the value into a `low`/`medium`/`high`\n * segment on `data-state` so the consumer can color the bar.\n *\n * @remarks\n * Behavior only. Because state must not be conveyed by color alone (WCAG 1.4.1),\n * a consumer-provided `valueText` template feeds `aria-valuetext` so the segment\n * is also available as text; a consumer that authors `aria-valuetext` itself keeps\n * it instead (see {@link OWNED_VALUE_TEXT}). Threshold presence is read from the\n * *attributes* (an absent attribute means \"no threshold\"), not from a sentinel value.\n */\nexport class MeterController extends Controller<HTMLElement> {\n  static override targets = [\"bar\"];\n  static override values = {\n    announceText: { type: String, default: \"\" },\n    value: { type: Number, default: 0 },\n    min: { type: Number, default: 0 },\n    max: { type: Number, default: 100 },\n    low: { type: Number, default: 0 },\n    high: { type: Number, default: 0 },\n    optimum: { type: Number, default: 0 },\n    valueText: { type: String, default: \"\" },\n  };\n  static actions = [\"setValue\"] as const;\n  static events = [\"change\"] as const;\n\n  declare readonly barTarget: HTMLElement;\n  declare readonly hasBarTarget: boolean;\n\n  declare valueValue: number;\n  declare minValue: number;\n  declare maxValue: number;\n  declare lowValue: number;\n  declare highValue: number;\n  declare optimumValue: number;\n  declare valueTextValue: string;\n  declare announceTextValue: string;\n\n  /**\n   * Collapses a morph that swaps several render inputs at once into one repaint.\n   * A single update usually rewrites the whole set, and each Value would otherwise\n   * repaint on its own.\n   */\n  readonly #repaint = new MicrotaskCoalescer(() => {\n    this.#render();\n  });\n\n  /** The segment last announced, so only a change is read out. */\n  #announcedState: MeterState | null = null;\n\n  override connect(): void {\n    this.#repaint.activate();\n    this.#render();\n  }\n\n  /** Closes the window in which a queued repaint may still run. */\n  override disconnect(): void {\n    this.#repaint.cancel();\n  }\n\n  /**\n   * Updates the measured value from an action param (`amount`) or a\n   * `detail.value` CustomEvent, syncs ARIA and `data-state`, and dispatches\n   * `change` with the value, ratio, and computed segment.\n   */\n  setValue(event: SetValueEvent): void {\n    const next = toFiniteNumber(event.params?.amount ?? event.detail?.value);\n    if (next === null) return;\n    this.valueValue = this.#clamp(next);\n    const reading = this.#render();\n    this.dispatch(\"change\", { detail: reading });\n    // Only the segment is news: reading every value would be unusable, and the\n    // number itself is already exposed through `aria-valuenow`.\n    if (reading.state !== this.#announcedState) {\n      this.#announcedState = reading.state;\n      announce(\n        fillTemplate(this.announceTextValue, { state: reading.state, value: reading.value }),\n      );\n    }\n  }\n\n  /** Repaints when application code (or a Turbo morph) changes `value` at runtime. */\n  valueValueChanged(): void {\n    this.#repaint.schedule();\n  }\n\n  /** Repaints when application code (or a Turbo morph) changes `min` at runtime. */\n  minValueChanged(): void {\n    this.#repaint.schedule();\n  }\n\n  /** Repaints when application code (or a Turbo morph) changes `max` at runtime. */\n  maxValueChanged(): void {\n    this.#repaint.schedule();\n  }\n\n  /** Repaints when application code (or a Turbo morph) changes `low` at runtime. */\n  lowValueChanged(): void {\n    this.#repaint.schedule();\n  }\n\n  /** Repaints when application code (or a Turbo morph) changes `high` at runtime. */\n  highValueChanged(): void {\n    this.#repaint.schedule();\n  }\n\n  /** Repaints when application code (or a Turbo morph) changes `valueText` at runtime. */\n  valueTextValueChanged(): void {\n    this.#repaint.schedule();\n  }\n\n  /** Clamps `raw` into the configured `[min, max]` range. */\n  #clamp(raw: number): number {\n    return Math.min(this.maxValue, Math.max(this.minValue, raw));\n  }\n\n  /** Whether a threshold attribute is present (absent = no threshold). */\n  #hasThreshold(name: \"low\" | \"high\"): boolean {\n    return this.element.hasAttribute(`data-stimeo--meter-${name}-value`);\n  }\n\n  /**\n   * Classifies `value` into a `low`/`medium`/`high` segment. Values at or below\n   * `low` are `low`; at or above `high` are `high`; otherwise `medium`. With\n   * neither threshold present, everything is `medium`.\n   */\n  #stateOf(value: number): MeterState {\n    if (this.#hasThreshold(\"low\") && value <= this.lowValue) return \"low\";\n    if (this.#hasThreshold(\"high\") && value >= this.highValue) return \"high\";\n    return \"medium\";\n  }\n\n  /**\n   * Reflects value/range onto ARIA, the segment onto `data-state`, and the ratio.\n   * The reading is derived once and returned, so the `change` detail reports the\n   * same numbers the DOM just received.\n   */\n  #render(): MeterReading {\n    const value = this.#clamp(this.valueValue);\n    const reading: MeterReading = {\n      value,\n      ratio: rangeFraction(value, this.minValue, this.maxValue),\n      state: this.#stateOf(value),\n    };\n    this.element.setAttribute(\"aria-valuemin\", String(this.minValue));\n    this.element.setAttribute(\"aria-valuemax\", String(this.maxValue));\n    this.element.setAttribute(\"aria-valuenow\", String(reading.value));\n    this.element.style.setProperty(\"--stimeo-meter-ratio\", String(reading.ratio));\n    this.element.setAttribute(\"data-state\", reading.state);\n    this.#applyValueText(reading);\n    return reading;\n  }\n\n  /**\n   * Sets `aria-valuetext` from the consumer-provided template, substituting\n   * `{value}`, `{percent}`, and `{state}`. Kept i18n-neutral in the library.\n   * With no template the attribute belongs to the consumer, so only a text this\n   * controller wrote is taken back ({@link OWNED_VALUE_TEXT}).\n   */\n  #applyValueText({ value, ratio, state }: MeterReading): void {\n    if (this.valueTextValue.length === 0) {\n      if (this.element.hasAttribute(OWNED_VALUE_TEXT)) {\n        this.element.removeAttribute(\"aria-valuetext\");\n        this.element.removeAttribute(OWNED_VALUE_TEXT);\n      }\n      return;\n    }\n    const percent = Math.round(ratio * 100);\n    const text = this.valueTextValue\n      .replaceAll(\"{value}\", String(value))\n      .replaceAll(\"{percent}\", String(percent))\n      .replaceAll(\"{state}\", state);\n    this.element.setAttribute(\"aria-valuetext\", text);\n    this.element.setAttribute(OWNED_VALUE_TEXT, \"\");\n  }\n}\n"]}

package/dist/controllers/network_status_controller.d.ts

@@ -23,7 +23,9 @@ import { Controller } from '@hotwired/stimulus';
  * Behavior only. `navigator.onLine` is the browser's *guess* — it does not
  * guarantee server reachability, which stays the consumer's job. To make the
  * announcement reliable across assistive tech (merely un-hiding a static banner
- * is flaky), the controller re-writes the banner's text on each transition,
+ * is flaky), the controller reveals the banner and *then* re-writes its text on
+ * each transition — a region revealed after its content changed is outside the
+ * accessibility tree while the text changes, so the write has to come second —
  * guarded so an unchanged state never re-announces. The event listeners and the
  * auto-hide timer are removed/cleared on `disconnect()` (Turbo included).
  */
@@ -31,6 +33,14 @@ declare class NetworkStatusController extends Controller<HTMLElement> {
     #private;
     static targets: string[];
     static values: {
+        announceText: {
+            type: StringConstructor;
+            default: string;
+        };
+        announceOnlineText: {
+            type: StringConstructor;
+            default: string;
+        };
         onlineAutoHide: {
             type: NumberConstructor;
             default: number;
@@ -42,6 +52,8 @@ declare class NetworkStatusController extends Controller<HTMLElement> {
     readonly hasOfflineTarget: boolean;
     readonly hasOnlineTarget: boolean;
     onlineAutoHideValue: number;
+    announceTextValue: string;
+    announceOnlineTextValue: string;
     connect(): void;
     disconnect(): void;
 }

package/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(() => {

package/dist/controllers/network_status_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/safe_timeout.ts","../../src/controllers/network_status_controller.ts"],"names":[],"mappings":"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","file":"network_status_controller.js","sourcesContent":["/**\n * Self-cleaning timer registries shared by Stimeo controllers.\n *\n * Stimulus controllers frequently schedule `setTimeout` / `setInterval` work\n * (auto-dismiss, debouncing, polling). When the element leaves the DOM — a\n * Turbo Drive navigation, a Turbo Stream replacement, or any `disconnect()` —\n * orphaned timers keep firing against a detached controller, leaking memory and\n * mutating stale state. {@link SafeTimeout} and {@link SafeInterval} track every\n * timer they create so a single {@link TimerRegistry.clearAll | clearAll()} call\n * in `disconnect()` tears them all down.\n *\n * These are intentionally low-level primitives: they own *registration and\n * cleanup only*. Higher-level policy (pause/resume, remaining-time accounting)\n * stays in the individual controllers so per-widget semantics are not flattened\n * into a lowest-common-denominator helper.\n */\n\n/**\n * Shared registry bookkeeping for the timeout/interval variants.\n *\n * Subclasses provide the scheduling primitive ({@link schedule}) and its matching\n * canceller ({@link cancel}); this base owns the set of live ids plus the\n * per-id and bulk teardown shared by both.\n */\nabstract class TimerRegistry {\n  /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */\n  protected readonly ids = new Set<number>();\n\n  /** Schedules the underlying platform timer and returns its id. */\n  protected abstract schedule(callback: () => void, delay: number): number;\n\n  /** Cancels the underlying platform timer for `id`. */\n  protected abstract cancel(id: number): void;\n\n  /**\n   * Cancels a single tracked timer.\n   *\n   * No-ops if the id is unknown (already cleared, fired, or never owned by this\n   * registry), so callers can clear defensively without guarding.\n   */\n  clear(id: number): void {\n    if (this.ids.delete(id)) {\n      this.cancel(id);\n    }\n  }\n\n  /**\n   * Cancels every tracked timer. Call this from a controller's `disconnect()`\n   * to guarantee no timer outlives the element.\n   */\n  clearAll(): void {\n    for (const id of this.ids) {\n      this.cancel(id);\n    }\n    this.ids.clear();\n  }\n\n  /** Number of timers currently tracked (pending). */\n  get size(): number {\n    return this.ids.size;\n  }\n}\n\n/**\n * `setTimeout` wrapper that auto-forgets each timer once it fires and supports\n * bulk teardown on disconnect.\n *\n * @example\n * ```ts\n * #timers = new SafeTimeout();\n *\n * connect() {\n *   this.#timers.set(() => this.dismiss(), 5000);\n * }\n *\n * disconnect() {\n *   this.#timers.clearAll();\n * }\n * ```\n */\nexport class SafeTimeout extends TimerRegistry {\n  /**\n   * Schedules `callback` after `delay` ms and returns the timer id.\n   *\n   * The id is removed from the registry automatically when the timeout fires,\n   * so {@link TimerRegistry.size | size} reflects only still-pending timers.\n   */\n  set(callback: () => void, delay: number): number {\n    const id = this.schedule(() => {\n      this.ids.delete(id);\n      callback();\n    }, delay);\n    this.ids.add(id);\n    return id;\n  }\n\n  protected schedule(callback: () => void, delay: number): number {\n    return window.setTimeout(callback, delay);\n  }\n\n  protected cancel(id: number): void {\n    window.clearTimeout(id);\n  }\n}\n\n/**\n * `setInterval` wrapper that tracks every interval for bulk teardown on\n * disconnect. Unlike {@link SafeTimeout}, intervals are retained until they are\n * explicitly cleared because they fire repeatedly.\n *\n * @example\n * ```ts\n * #intervals = new SafeInterval();\n *\n * connect() {\n *   this.#intervals.set(() => this.tick(), 1000);\n * }\n *\n * disconnect() {\n *   this.#intervals.clearAll();\n * }\n * ```\n */\nexport class SafeInterval extends TimerRegistry {\n  /** Schedules a repeating `callback` every `delay` ms and returns the timer id. */\n  set(callback: () => void, delay: number): number {\n    const id = this.schedule(callback, delay);\n    this.ids.add(id);\n    return id;\n  }\n\n  protected schedule(callback: () => void, delay: number): number {\n    return window.setInterval(callback, delay);\n  }\n\n  protected cancel(id: number): void {\n    window.clearInterval(id);\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { SafeTimeout } from \"../utils/safe_timeout\";\n\n/**\n * Headless online/offline banner behavior built on the live-region practice (no\n * dedicated APG pattern).\n *\n * Markup contract (identifier: `stimeo--network-status`):\n *   <div data-controller=\"stimeo--network-status\">\n *     <div role=\"alert\" hidden data-stimeo--network-status-target=\"offline\">\n *       You are offline.\n *     </div>\n *     <div role=\"status\" hidden data-stimeo--network-status-target=\"online\">\n *       Back online.\n *     </div>\n *   </div>\n *\n * Reads `navigator.onLine` on connect and subscribes to the `window`\n * `online`/`offline` events, toggling the matching banner. The offline banner is\n * `role=\"alert\"` (assertive) because losing connectivity is urgent; the recovery\n * banner is `role=\"status\"` (polite).\n *\n * @remarks\n * Behavior only. `navigator.onLine` is the browser's *guess* — it does not\n * guarantee server reachability, which stays the consumer's job. To make the\n * announcement reliable across assistive tech (merely un-hiding a static banner\n * is flaky), the controller re-writes the banner's text on each transition,\n * guarded so an unchanged state never re-announces. The event listeners and the\n * auto-hide timer are removed/cleared on `disconnect()` (Turbo included).\n */\nexport class NetworkStatusController extends Controller<HTMLElement> {\n  static override targets = [\"offline\", \"online\"];\n  static override values = {\n    onlineAutoHide: { type: Number, default: 0 },\n  };\n  static events = [\"change\"] as const;\n\n  declare readonly offlineTarget: HTMLElement;\n  declare readonly onlineTarget: HTMLElement;\n  declare readonly hasOfflineTarget: boolean;\n  declare readonly hasOnlineTarget: boolean;\n\n  declare onlineAutoHideValue: number;\n\n  readonly #timers = new SafeTimeout();\n\n  /** Last known connectivity; guards against duplicate-state re-announcements. */\n  #online = true;\n  /** Banner text captured from the markup so transitions can re-write it. */\n  #offlineMessage = \"\";\n  #onlineMessage = \"\";\n\n  readonly #handleOnline = (): void => this.#update(true);\n  readonly #handleOffline = (): void => this.#update(false);\n\n  override connect(): void {\n    this.#offlineMessage = this.hasOfflineTarget\n      ? (this.offlineTarget.textContent ?? \"\").trim()\n      : \"\";\n    this.#onlineMessage = this.hasOnlineTarget ? (this.onlineTarget.textContent ?? \"\").trim() : \"\";\n\n    // Normalize initial visibility so a missing `hidden` in the markup cannot\n    // strand a stale banner (e.g. an offline notice showing while online).\n    if (this.hasOfflineTarget) this.offlineTarget.hidden = true;\n    if (this.hasOnlineTarget) this.onlineTarget.hidden = true;\n\n    this.#online = navigator.onLine;\n    // On connect, surface only the offline state; do not flash a \"back online\"\n    // banner just because the page loaded while connected.\n    this.element.setAttribute(\"data-state\", this.#online ? \"online\" : \"offline\");\n    if (!this.#online) this.#showOffline();\n\n    window.addEventListener(\"online\", this.#handleOnline);\n    window.addEventListener(\"offline\", this.#handleOffline);\n  }\n\n  override disconnect(): void {\n    window.removeEventListener(\"online\", this.#handleOnline);\n    window.removeEventListener(\"offline\", this.#handleOffline);\n    this.#timers.clearAll();\n  }\n\n  /** Applies a connectivity transition, guarded against duplicate states. */\n  #update(online: boolean): void {\n    if (online === this.#online) return;\n    this.#online = online;\n    this.element.setAttribute(\"data-state\", online ? \"online\" : \"offline\");\n    if (online) {\n      this.#showOnline();\n    } else {\n      this.#showOffline();\n    }\n    this.dispatch(\"change\", { detail: { online } });\n  }\n\n  /** Shows the offline banner and hides the recovery banner. */\n  #showOffline(): void {\n    this.#timers.clearAll();\n    if (this.hasOnlineTarget) this.onlineTarget.hidden = true;\n    if (this.hasOfflineTarget) {\n      this.offlineTarget.textContent = this.#offlineMessage;\n      this.offlineTarget.hidden = false;\n    }\n  }\n\n  /** Shows the recovery banner, optionally auto-hiding it after `onlineAutoHide`. */\n  #showOnline(): void {\n    if (this.hasOfflineTarget) this.offlineTarget.hidden = true;\n    if (!this.hasOnlineTarget) return;\n    this.onlineTarget.textContent = this.#onlineMessage;\n    this.onlineTarget.hidden = false;\n    if (this.onlineAutoHideValue > 0) {\n      this.#timers.set(() => {\n        this.onlineTarget.hidden = true;\n      }, this.onlineAutoHideValue);\n    }\n  }\n}\n"]}
+{"version":3,"sources":["../../src/utils/announce.ts","../../src/utils/safe_timeout.ts","../../src/controllers/network_status_controller.ts"],"names":[],"mappings":"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","file":"network_status_controller.js","sourcesContent":["/**\n * Sends one message to the page's shared `stimeo--announcer`.\n *\n * A component that has to reach assistive tech does not carry a live region of its\n * own: a region only announces what changes *after* assistive tech already knows\n * about it, which a region that appears (or is un-hidden) with its message cannot\n * satisfy. The one region that can is the announcer sitting in the page from the\n * start, so state changes are handed to it as an event and it does the reading.\n *\n * The event goes to `window` because the announcer is usually a sibling high in the\n * document rather than an ancestor of the component dispatching it.\n *\n * Wording comes from the consumer — the library ships no English strings — so an\n * empty message is silently dropped and nothing is announced.\n *\n * @example\n * ```ts\n * announce(this.announceTextValue, { assertive: false });\n * ```\n */\nexport function announce(message: string, options: { assertive?: boolean } = {}): void {\n  const text = message.trim();\n  if (text.length === 0) return;\n  window.dispatchEvent(\n    new CustomEvent(\"stimeo--announcer:announce\", {\n      detail: { message: text, assertive: options.assertive === true },\n    }),\n  );\n}\n\n/**\n * Fills `{name}` placeholders in an announcement template from `values`.\n *\n * The same substitution the value-text templates use, so a consumer writes\n * `\"{percent}% complete\"` in one attribute and gets the same rules everywhere. A\n * placeholder with no matching entry is left as authored rather than blanked, which\n * keeps a typo visible instead of silently swallowing the word.\n */\nexport function fillTemplate(template: string, values: Record<string, string | number>): string {\n  return template.replace(/\\{([a-zA-Z][a-zA-Z0-9]*)\\}/g, (match, name: string) => {\n    const replacement = values[name];\n    return replacement === undefined ? match : String(replacement);\n  });\n}\n","/**\n * Self-cleaning timer registries shared by Stimeo controllers.\n *\n * Stimulus controllers frequently schedule `setTimeout` / `setInterval` work\n * (auto-dismiss, debouncing, polling). When the element leaves the DOM — a\n * Turbo Drive navigation, a Turbo Stream replacement, or any `disconnect()` —\n * orphaned timers keep firing against a detached controller, leaking memory and\n * mutating stale state. {@link SafeTimeout} and {@link SafeInterval} track every\n * timer they create so a single {@link TimerRegistry.clearAll | clearAll()} call\n * in `disconnect()` tears them all down.\n *\n * These are intentionally low-level primitives: they own *registration and\n * cleanup only*. Higher-level policy (pause/resume, remaining-time accounting)\n * stays in the individual controllers so per-widget semantics are not flattened\n * into a lowest-common-denominator helper.\n */\n\n/**\n * Shared registry bookkeeping for the timeout/interval variants.\n *\n * Subclasses provide the scheduling primitive ({@link schedule}) and its matching\n * canceller ({@link cancel}); this base owns the set of live ids plus the\n * per-id and bulk teardown shared by both.\n */\nabstract class TimerRegistry {\n  /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */\n  protected readonly ids = new Set<number>();\n\n  /** Schedules the underlying platform timer and returns its id. */\n  protected abstract schedule(callback: () => void, delay: number): number;\n\n  /** Cancels the underlying platform timer for `id`. */\n  protected abstract cancel(id: number): void;\n\n  /**\n   * Cancels a single tracked timer.\n   *\n   * No-ops if the id is unknown (already cleared, fired, or never owned by this\n   * registry), so callers can clear defensively without guarding.\n   */\n  clear(id: number): void {\n    if (this.ids.delete(id)) {\n      this.cancel(id);\n    }\n  }\n\n  /**\n   * Cancels every tracked timer. Call this from a controller's `disconnect()`\n   * to guarantee no timer outlives the element.\n   */\n  clearAll(): void {\n    for (const id of this.ids) {\n      this.cancel(id);\n    }\n    this.ids.clear();\n  }\n\n  /** Number of timers currently tracked (pending). */\n  get size(): number {\n    return this.ids.size;\n  }\n}\n\n/**\n * `setTimeout` wrapper that auto-forgets each timer once it fires and supports\n * bulk teardown on disconnect.\n *\n * @example\n * ```ts\n * #timers = new SafeTimeout();\n *\n * connect() {\n *   this.#timers.set(() => this.dismiss(), 5000);\n * }\n *\n * disconnect() {\n *   this.#timers.clearAll();\n * }\n * ```\n */\nexport class SafeTimeout extends TimerRegistry {\n  /**\n   * Schedules `callback` after `delay` ms and returns the timer id.\n   *\n   * The id is removed from the registry automatically when the timeout fires,\n   * so {@link TimerRegistry.size | size} reflects only still-pending timers.\n   */\n  set(callback: () => void, delay: number): number {\n    const id = this.schedule(() => {\n      this.ids.delete(id);\n      callback();\n    }, delay);\n    this.ids.add(id);\n    return id;\n  }\n\n  protected schedule(callback: () => void, delay: number): number {\n    return window.setTimeout(callback, delay);\n  }\n\n  protected cancel(id: number): void {\n    window.clearTimeout(id);\n  }\n}\n\n/**\n * `setInterval` wrapper that tracks every interval for bulk teardown on\n * disconnect. Unlike {@link SafeTimeout}, intervals are retained until they are\n * explicitly cleared because they fire repeatedly.\n *\n * @example\n * ```ts\n * #intervals = new SafeInterval();\n *\n * connect() {\n *   this.#intervals.set(() => this.tick(), 1000);\n * }\n *\n * disconnect() {\n *   this.#intervals.clearAll();\n * }\n * ```\n */\nexport class SafeInterval extends TimerRegistry {\n  /** Schedules a repeating `callback` every `delay` ms and returns the timer id. */\n  set(callback: () => void, delay: number): number {\n    const id = this.schedule(callback, delay);\n    this.ids.add(id);\n    return id;\n  }\n\n  protected schedule(callback: () => void, delay: number): number {\n    return window.setInterval(callback, delay);\n  }\n\n  protected cancel(id: number): void {\n    window.clearInterval(id);\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { announce, fillTemplate } from \"../utils/announce\";\nimport { SafeTimeout } from \"../utils/safe_timeout\";\n\n/**\n * Headless online/offline banner behavior built on the live-region practice (no\n * dedicated APG pattern).\n *\n * Markup contract (identifier: `stimeo--network-status`):\n *   <div data-controller=\"stimeo--network-status\">\n *     <div role=\"alert\" hidden data-stimeo--network-status-target=\"offline\">\n *       You are offline.\n *     </div>\n *     <div role=\"status\" hidden data-stimeo--network-status-target=\"online\">\n *       Back online.\n *     </div>\n *   </div>\n *\n * Reads `navigator.onLine` on connect and subscribes to the `window`\n * `online`/`offline` events, toggling the matching banner. The offline banner is\n * `role=\"alert\"` (assertive) because losing connectivity is urgent; the recovery\n * banner is `role=\"status\"` (polite).\n *\n * @remarks\n * Behavior only. `navigator.onLine` is the browser's *guess* — it does not\n * guarantee server reachability, which stays the consumer's job. To make the\n * announcement reliable across assistive tech (merely un-hiding a static banner\n * is flaky), the controller reveals the banner and *then* re-writes its text on\n * each transition — a region revealed after its content changed is outside the\n * accessibility tree while the text changes, so the write has to come second —\n * guarded so an unchanged state never re-announces. The event listeners and the\n * auto-hide timer are removed/cleared on `disconnect()` (Turbo included).\n */\nexport class NetworkStatusController extends Controller<HTMLElement> {\n  static override targets = [\"offline\", \"online\"];\n  static override values = {\n    announceText: { type: String, default: \"\" },\n    announceOnlineText: { type: String, default: \"\" },\n    onlineAutoHide: { type: Number, default: 0 },\n  };\n  static events = [\"change\"] as const;\n\n  declare readonly offlineTarget: HTMLElement;\n  declare readonly onlineTarget: HTMLElement;\n  declare readonly hasOfflineTarget: boolean;\n  declare readonly hasOnlineTarget: boolean;\n\n  declare onlineAutoHideValue: number;\n  declare announceTextValue: string;\n  declare announceOnlineTextValue: string;\n\n  readonly #timers = new SafeTimeout();\n\n  /** Last known connectivity; guards against duplicate-state re-announcements. */\n  #online = true;\n\n  readonly #handleOnline = (): void => this.#update(true);\n  readonly #handleOffline = (): void => this.#update(false);\n\n  override connect(): void {\n    // Normalize initial visibility so a missing `hidden` in the markup cannot\n    // strand a stale banner (e.g. an offline notice showing while online).\n    if (this.hasOfflineTarget) this.offlineTarget.hidden = true;\n    if (this.hasOnlineTarget) this.onlineTarget.hidden = true;\n\n    this.#online = navigator.onLine;\n    // On connect, surface only the offline state; do not flash a \"back online\"\n    // banner just because the page loaded while connected.\n    this.element.setAttribute(\"data-state\", this.#online ? \"online\" : \"offline\");\n    if (!this.#online) this.#showOffline();\n\n    window.addEventListener(\"online\", this.#handleOnline);\n    window.addEventListener(\"offline\", this.#handleOffline);\n  }\n\n  override disconnect(): void {\n    window.removeEventListener(\"online\", this.#handleOnline);\n    window.removeEventListener(\"offline\", this.#handleOffline);\n    this.#timers.clearAll();\n  }\n\n  /**\n   * Applies a connectivity transition, guarded against duplicate states.\n   *\n   * The event goes out last, so a listener reading `data-state` or a banner's\n   * visibility sees the state the transition landed on rather than the previous one.\n   */\n  #update(online: boolean): void {\n    if (online === this.#online) return;\n    this.#online = online;\n    this.element.setAttribute(\"data-state\", online ? \"online\" : \"offline\");\n    if (online) {\n      this.#showOnline();\n    } else {\n      this.#showOffline();\n    }\n    // The banner is the visual half; reading it out is the announcer's job, because\n    // a region that is only revealed at the moment of the change is not reliably read.\n    announce(fillTemplate(online ? this.announceOnlineTextValue : this.announceTextValue, {}), {\n      assertive: !online,\n    });\n    this.dispatch(\"change\", { detail: { online } });\n  }\n\n  /** Shows the offline banner and hides the recovery banner. */\n  #showOffline(): void {\n    this.#timers.clearAll();\n    if (this.hasOnlineTarget) this.onlineTarget.hidden = true;\n    if (this.hasOfflineTarget) {\n      // Reveal before writing: a hidden region is out of the accessibility tree,\n      // so a text change made while it is still hidden is never observed.\n      this.offlineTarget.hidden = false;\n    }\n  }\n\n  /** Shows the recovery banner, optionally auto-hiding it after `onlineAutoHide`. */\n  #showOnline(): void {\n    if (this.hasOfflineTarget) this.offlineTarget.hidden = true;\n    if (!this.hasOnlineTarget) return;\n    // Reveal before writing, same as the offline banner.\n    this.onlineTarget.hidden = false;\n    if (this.onlineAutoHideValue > 0) {\n      this.#timers.set(() => {\n        this.onlineTarget.hidden = true;\n      }, this.onlineAutoHideValue);\n    }\n  }\n}\n"]}

package/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;
   }