stimeo-ui 0.3.0 → 0.5.0

package/dist/controllers/empty_state_controller.d.ts

@@ -13,17 +13,21 @@ import { Controller } from '@hotwired/stimulus';
  *   </div>
  *
  * Counts `list`'s child items (all element children, or those matching
- * `itemSelector`) on connect and on every childList mutation, toggles `hidden` on
- * `list` / `empty` at the 0 ↔ 1+ boundary, and reflects `data-empty` / `data-count`
- * on the controller element. Crossing the boundary dispatches `change`.
+ * `itemSelector`) on connect and on every mutation that can change that count,
+ * toggles `hidden` on `list` / `empty` at the 0 ↔ 1+ boundary, and reflects
+ * `data-empty` / `data-count` on the controller element. Crossing the boundary
+ * dispatches `change` after the display is updated, so a listener reads the
+ * state the crossing produced.
  *
  * @remarks
  * Behavior only — the placeholder's look/copy is the consumer's. State is derived
  * from the DOM (no module-scope state), so `connect()` re-syncs after a Turbo
- * Stream insertion. The `MutationObserver` is severed on `disconnect()` (Turbo
- * navigation included). With `announce`, the `empty` target is made a polite live
- * region (only if the author hasn't already), so showing it is announced — SR
- * support for unhiding a live region varies; pair with Announcer for a guarantee.
+ * Stream insertion. Both targets are re-resolved at runtime: a `list` element
+ * swapped in re-points the observation, and a swapped-in `empty` element is
+ * re-synced — including when the replacement is inserted while the original is
+ * still in the document. The `MutationObserver` is severed on `disconnect()`
+ * (Turbo navigation included). `announceText` / `announceFilledText` are read at
+ * the crossing and handed to the page's announcer.
  *
  * Ownership note: this controller deliberately owns `hidden` on the `list` / `empty`
  * targets as its single source of truth for which one is shown, rather than only
@@ -41,9 +45,13 @@ declare class EmptyStateController extends Controller<HTMLElement> {
             type: StringConstructor;
             default: string;
         };
-        announce: {
-            type: BooleanConstructor;
-            default: boolean;
+        announceText: {
+            type: StringConstructor;
+            default: string;
+        };
+        announceFilledText: {
+            type: StringConstructor;
+            default: string;
         };
     };
     static events: readonly ["change"];
@@ -52,9 +60,26 @@ declare class EmptyStateController extends Controller<HTMLElement> {
     readonly hasListTarget: boolean;
     readonly hasEmptyTarget: boolean;
     itemSelectorValue: string;
-    announceValue: boolean;
+    announceTextValue: string;
+    announceFilledTextValue: string;
     connect(): void;
     disconnect(): void;
+    /** Follows a `list` element swapped in at runtime (Turbo Stream `replace` / morph). */
+    listTargetConnected(): void;
+    /** Releases the observation when the `list` element leaves the target set. */
+    listTargetDisconnected(): void;
+    /** Syncs an `empty` element that arrives — or is replaced — at runtime. */
+    emptyTargetConnected(): void;
+    /**
+     * Syncs the `empty` element that remains when one leaves the target set. A
+     * single-target getter resolves to the first `empty` element in document order,
+     * so a swap that inserts the replacement *before* removing the original (Turbo
+     * Stream `after` / `before` / `append` followed by `remove`) leaves the
+     * replacement untouched until the original goes — this callback is that moment.
+     */
+    emptyTargetDisconnected(): void;
+    /** Re-renders when application code (or a Turbo morph) changes `itemSelector` at runtime. */
+    itemSelectorValueChanged(): void;
 }
 
 export { EmptyStateController };

package/dist/controllers/empty_state_controller.js

@@ -1,35 +1,148 @@
 import { Controller } from '@hotwired/stimulus';
 
+// src/controllers/empty_state_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/controllers/empty_state_controller.ts
 var EmptyStateController = class extends Controller {
   static targets = ["list", "empty"];
   static values = {
     itemSelector: { type: String, default: "" },
-    announce: { type: Boolean, default: false }
+    announceText: { type: String, default: "" },
+    announceFilledText: { type: String, default: "" }
   };
   static events = ["change"];
   #observer = null;
+  /** Whether the controller is between `connect()` and `disconnect()`. */
+  #connected = false;
   /** Last applied empty state; `null` until the first sync so connect emits nothing. */
   #empty = null;
   connect() {
-    if (!this.hasListTarget) return;
-    if (this.announceValue && this.hasEmptyTarget && !this.#isLiveRegion(this.emptyTarget)) {
-      this.emptyTarget.setAttribute("role", "status");
-      this.emptyTarget.setAttribute("aria-live", "polite");
-    }
-    if (typeof MutationObserver !== "undefined") {
-      this.#observer = new MutationObserver(() => this.#apply());
-      this.#observer.observe(this.listTarget, { childList: true });
-    }
-    this.#apply();
+    this.#connected = true;
+    this.#syncObservation();
+    this.#update();
   }
   disconnect() {
+    this.#connected = false;
+    this.#stopObserving();
+  }
+  /** Follows a `list` element swapped in at runtime (Turbo Stream `replace` / morph). */
+  listTargetConnected() {
+    this.#resync();
+  }
+  /** Releases the observation when the `list` element leaves the target set. */
+  listTargetDisconnected() {
+    this.#resync();
+  }
+  /** Syncs an `empty` element that arrives — or is replaced — at runtime. */
+  emptyTargetConnected() {
+    this.#resync();
+  }
+  /**
+   * Syncs the `empty` element that remains when one leaves the target set. A
+   * single-target getter resolves to the first `empty` element in document order,
+   * so a swap that inserts the replacement *before* removing the original (Turbo
+   * Stream `after` / `before` / `append` followed by `remove`) leaves the
+   * replacement untouched until the original goes — this callback is that moment.
+   */
+  emptyTargetDisconnected() {
+    this.#resync();
+  }
+  /** Re-renders when application code (or a Turbo morph) changes `itemSelector` at runtime. */
+  itemSelectorValueChanged() {
+    this.#resync();
+  }
+  /**
+   * Re-points the observation and re-renders after a target or selector change.
+   * The `#connected` guard is load-bearing: Stimulus runs value and target
+   * callbacks for the initial markup *before* `connect()` and runs target
+   * callbacks during teardown *after* `disconnect()`, and re-observing there
+   * would outlive the controller.
+   */
+  #resync() {
+    if (!this.#connected) return;
+    this.#syncObservation();
+    this.#update();
+  }
+  /**
+   * Points the mutation observation at the current `list` target — re-resolved on
+   * every sync rather than captured at connect, so an element swapped in at
+   * runtime is observed instead of the detached original.
+   *
+   * The observation covers exactly what the count predicate reads. With no
+   * `itemSelector` the count is the child element count, which only `childList`
+   * can change. With one, the predicate reads the children themselves, so
+   * attribute and descendant mutations are watched too — and the controller's own
+   * writes are filtered back out, or toggling `hidden` would re-enter the render.
+   */
+  #syncObservation() {
+    this.#stopObserving();
+    if (!this.hasListTarget || typeof MutationObserver === "undefined") return;
+    const watchesItems = this.itemSelectorValue.length > 0;
+    this.#observer = new MutationObserver((records) => {
+      if (records.some((record) => this.#affectsCount(record))) this.#update();
+    });
+    this.#observer.observe(this.listTarget, {
+      childList: true,
+      subtree: watchesItems,
+      attributes: watchesItems
+    });
+  }
+  #stopObserving() {
     this.#observer?.disconnect();
     this.#observer = null;
   }
-  /** Recomputes the count and syncs visibility, hooks, and the change event. */
-  #apply() {
-    if (!this.hasListTarget) return;
+  /**
+   * Whether a mutation can change the item count. An attribute written on a
+   * target this controller owns is its own echo — `hidden` on `list` / `empty`,
+   * and the hooks on the controller element when the list *is* that element.
+   */
+  #affectsCount(record) {
+    if (record.type !== "attributes") return true;
+    const own = record.target === this.listTarget || this.hasEmptyTarget && record.target === this.emptyTarget;
+    return !own;
+  }
+  /**
+   * Renders the count, then reports a crossed boundary. The announcement copy is
+   * read here rather than while rendering: it is the wording of the report, not
+   * an input to what is displayed.
+   */
+  #update() {
+    const count = this.#render();
+    if (count === null) return;
+    const empty = count === 0;
+    const crossed = this.#empty !== null && empty !== this.#empty;
+    this.#empty = empty;
+    if (!crossed) return;
+    this.dispatch("change", { detail: { count, empty } });
+    announce(
+      fillTemplate(empty ? this.announceTextValue : this.announceFilledTextValue, { count })
+    );
+  }
+  /**
+   * Syncs visibility and the state hooks to the current item count, and returns
+   * it. `null` when there is no `list` target to count.
+   *
+   * @stimeoRenderRoot
+   */
+  #render() {
+    if (!this.hasListTarget) return null;
     const count = this.#count();
     const empty = count === 0;
     this.element.setAttribute("data-count", String(count));
@@ -40,10 +153,7 @@ var EmptyStateController = class extends Controller {
     }
     this.listTarget.hidden = empty;
     if (this.hasEmptyTarget) this.emptyTarget.hidden = !empty;
-    if (this.#empty !== null && empty !== this.#empty) {
-      this.dispatch("change", { detail: { count, empty } });
-    }
-    this.#empty = empty;
+    return count;
   }
   /** Item count: element children matching `itemSelector`, or all element children. */
   #count() {
@@ -55,11 +165,6 @@ var EmptyStateController = class extends Controller {
       return this.listTarget.childElementCount;
     }
   }
-  #isLiveRegion(el) {
-    if (el.hasAttribute("aria-live")) return true;
-    const role = el.getAttribute("role");
-    return role === "status" || role === "alert";
-  }
 };
 
 export { EmptyStateController };

package/dist/controllers/empty_state_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/controllers/empty_state_controller.ts"],"names":[],"mappings":";;;AAmCO,IAAM,oBAAA,GAAN,cAAmC,UAAA,CAAwB;AAAA,EAChE,OAAgB,OAAA,GAAU,CAAC,MAAA,EAAQ,OAAO,CAAA;AAAA,EAC1C,OAAgB,MAAA,GAAS;AAAA,IACvB,YAAA,EAAc,EAAE,IAAA,EAAM,MAAA,EAAQ,SAAS,EAAA,EAAG;AAAA,IAC1C,QAAA,EAAU,EAAE,IAAA,EAAM,OAAA,EAAS,SAAS,KAAA;AAAM,GAC5C;AAAA,EACA,OAAO,MAAA,GAAS,CAAC,QAAQ,CAAA;AAAA,EAUzB,SAAA,GAAqC,IAAA;AAAA;AAAA,EAErC,MAAA,GAAyB,IAAA;AAAA,EAEhB,OAAA,GAAgB;AACvB,IAAA,IAAI,CAAC,KAAK,aAAA,EAAe;AACzB,IAAA,IAAI,IAAA,CAAK,iBAAiB,IAAA,CAAK,cAAA,IAAkB,CAAC,IAAA,CAAK,aAAA,CAAc,IAAA,CAAK,WAAW,CAAA,EAAG;AACtF,MAAA,IAAA,CAAK,WAAA,CAAY,YAAA,CAAa,MAAA,EAAQ,QAAQ,CAAA;AAC9C,MAAA,IAAA,CAAK,WAAA,CAAY,YAAA,CAAa,WAAA,EAAa,QAAQ,CAAA;AAAA,IACrD;AACA,IAAA,IAAI,OAAO,qBAAqB,WAAA,EAAa;AAC3C,MAAA,IAAA,CAAK,YAAY,IAAI,gBAAA,CAAiB,MAAM,IAAA,CAAK,QAAQ,CAAA;AACzD,MAAA,IAAA,CAAK,UAAU,OAAA,CAAQ,IAAA,CAAK,YAAY,EAAE,SAAA,EAAW,MAAM,CAAA;AAAA,IAC7D;AACA,IAAA,IAAA,CAAK,MAAA,EAAO;AAAA,EACd;AAAA,EAES,UAAA,GAAmB;AAC1B,IAAA,IAAA,CAAK,WAAW,UAAA,EAAW;AAC3B,IAAA,IAAA,CAAK,SAAA,GAAY,IAAA;AAAA,EACnB;AAAA;AAAA,EAGA,MAAA,GAAe;AACb,IAAA,IAAI,CAAC,KAAK,aAAA,EAAe;AACzB,IAAA,MAAM,KAAA,GAAQ,KAAK,MAAA,EAAO;AAC1B,IAAA,MAAM,QAAQ,KAAA,KAAU,CAAA;AAExB,IAAA,IAAA,CAAK,OAAA,CAAQ,YAAA,CAAa,YAAA,EAAc,MAAA,CAAO,KAAK,CAAC,CAAA;AACrD,IAAA,IAAI,KAAA,EAAO;AACT,MAAA,IAAA,CAAK,OAAA,CAAQ,YAAA,CAAa,YAAA,EAAc,MAAM,CAAA;AAAA,IAChD,CAAA,MAAO;AACL,MAAA,IAAA,CAAK,OAAA,CAAQ,gBAAgB,YAAY,CAAA;AAAA,IAC3C;AACA,IAAA,IAAA,CAAK,WAAW,MAAA,GAAS,KAAA;AACzB,IAAA,IAAI,IAAA,CAAK,cAAA,EAAgB,IAAA,CAAK,WAAA,CAAY,SAAS,CAAC,KAAA;AAIpD,IAAA,IAAI,IAAA,CAAK,MAAA,KAAW,IAAA,IAAQ,KAAA,KAAU,KAAK,MAAA,EAAQ;AACjD,MAAA,IAAA,CAAK,QAAA,CAAS,UAAU,EAAE,MAAA,EAAQ,EAAE,KAAA,EAAO,KAAA,IAAS,CAAA;AAAA,IACtD;AACA,IAAA,IAAA,CAAK,MAAA,GAAS,KAAA;AAAA,EAChB;AAAA;AAAA,EAGA,MAAA,GAAiB;AACf,IAAA,MAAM,WAAW,IAAA,CAAK,iBAAA;AACtB,IAAA,IAAI,QAAA,CAAS,MAAA,KAAW,CAAA,EAAG,OAAO,KAAK,UAAA,CAAW,iBAAA;AAClD,IAAA,IAAI;AACF,MAAA,OAAO,KAAA,CAAM,IAAA,CAAK,IAAA,CAAK,UAAA,CAAW,QAAQ,CAAA,CAAE,MAAA,CAAO,CAAC,KAAA,KAAU,KAAA,CAAM,OAAA,CAAQ,QAAQ,CAAC,CAAA,CAAE,MAAA;AAAA,IACzF,CAAA,CAAA,MAAQ;AAEN,MAAA,OAAO,KAAK,UAAA,CAAW,iBAAA;AAAA,IACzB;AAAA,EACF;AAAA,EAEA,cAAc,EAAA,EAA0B;AACtC,IAAA,IAAI,EAAA,CAAG,YAAA,CAAa,WAAW,CAAA,EAAG,OAAO,IAAA;AACzC,IAAA,MAAM,IAAA,GAAO,EAAA,CAAG,YAAA,CAAa,MAAM,CAAA;AACnC,IAAA,OAAO,IAAA,KAAS,YAAY,IAAA,KAAS,OAAA;AAAA,EACvC;AACF","file":"empty_state_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/**\n * Headless empty-state behavior: shows an \"empty\" placeholder when a list has no\n * items and hides it once one arrives (and vice-versa), watching the list with a\n * `MutationObserver` (no dedicated APG pattern; follows the WCAG \"status messages\"\n * practice when announcing).\n *\n * Markup contract (identifier: `stimeo--empty-state`):\n *   <div data-controller=\"stimeo--empty-state\">\n *     <ul data-stimeo--empty-state-target=\"list\"><!-- Turbo Stream rows --></ul>\n *     <p data-stimeo--empty-state-target=\"empty\" hidden>No items</p>\n *   </div>\n *\n * Counts `list`'s child items (all element children, or those matching\n * `itemSelector`) on connect and on every childList mutation, toggles `hidden` on\n * `list` / `empty` at the 0 ↔ 1+ boundary, and reflects `data-empty` / `data-count`\n * on the controller element. Crossing the boundary dispatches `change`.\n *\n * @remarks\n * Behavior only — the placeholder's look/copy is the consumer's. State is derived\n * from the DOM (no module-scope state), so `connect()` re-syncs after a Turbo\n * Stream insertion. The `MutationObserver` is severed on `disconnect()` (Turbo\n * navigation included). With `announce`, the `empty` target is made a polite live\n * region (only if the author hasn't already), so showing it is announced — SR\n * support for unhiding a live region varies; pair with Announcer for a guarantee.\n *\n * Ownership note: this controller deliberately owns `hidden` on the `list` / `empty`\n * targets as its single source of truth for which one is shown, rather than only\n * emitting `data-empty` and delegating visibility to consumer CSS. The toggle is\n * unconditional (set every sync), so there is nothing to save/restore and no\n * authored `hidden` to preserve — the displayed half is always a pure function of\n * the item count. Consumers wanting CSS-driven visibility should not also set\n * `hidden` on these targets themselves.\n */\nexport class EmptyStateController extends Controller<HTMLElement> {\n  static override targets = [\"list\", \"empty\"];\n  static override values = {\n    itemSelector: { type: String, default: \"\" },\n    announce: { type: Boolean, default: false },\n  };\n  static events = [\"change\"] as const;\n\n  declare readonly listTarget: HTMLElement;\n  declare readonly emptyTarget: HTMLElement;\n  declare readonly hasListTarget: boolean;\n  declare readonly hasEmptyTarget: boolean;\n\n  declare itemSelectorValue: string;\n  declare announceValue: boolean;\n\n  #observer: MutationObserver | null = null;\n  /** Last applied empty state; `null` until the first sync so connect emits nothing. */\n  #empty: boolean | null = null;\n\n  override connect(): void {\n    if (!this.hasListTarget) return;\n    if (this.announceValue && this.hasEmptyTarget && !this.#isLiveRegion(this.emptyTarget)) {\n      this.emptyTarget.setAttribute(\"role\", \"status\");\n      this.emptyTarget.setAttribute(\"aria-live\", \"polite\");\n    }\n    if (typeof MutationObserver !== \"undefined\") {\n      this.#observer = new MutationObserver(() => this.#apply());\n      this.#observer.observe(this.listTarget, { childList: true });\n    }\n    this.#apply();\n  }\n\n  override disconnect(): void {\n    this.#observer?.disconnect();\n    this.#observer = null;\n  }\n\n  /** Recomputes the count and syncs visibility, hooks, and the change event. */\n  #apply(): void {\n    if (!this.hasListTarget) return;\n    const count = this.#count();\n    const empty = count === 0;\n\n    this.element.setAttribute(\"data-count\", String(count));\n    if (empty) {\n      this.element.setAttribute(\"data-empty\", \"true\");\n    } else {\n      this.element.removeAttribute(\"data-empty\");\n    }\n    this.listTarget.hidden = empty;\n    if (this.hasEmptyTarget) this.emptyTarget.hidden = !empty;\n\n    // Emit only when the 0 ↔ 1+ boundary is crossed (not on the initial sync, and\n    // not for count changes that stay non-empty, e.g. 2 → 3).\n    if (this.#empty !== null && empty !== this.#empty) {\n      this.dispatch(\"change\", { detail: { count, empty } });\n    }\n    this.#empty = empty;\n  }\n\n  /** Item count: element children matching `itemSelector`, or all element children. */\n  #count(): number {\n    const selector = this.itemSelectorValue;\n    if (selector.length === 0) return this.listTarget.childElementCount;\n    try {\n      return Array.from(this.listTarget.children).filter((child) => child.matches(selector)).length;\n    } catch {\n      // An invalid selector (author typo) must not crash the controller — count all.\n      return this.listTarget.childElementCount;\n    }\n  }\n\n  #isLiveRegion(el: HTMLElement): boolean {\n    if (el.hasAttribute(\"aria-live\")) return true;\n    const role = el.getAttribute(\"role\");\n    return role === \"status\" || role === \"alert\";\n  }\n}\n"]}
+{"version":3,"sources":["../../src/utils/announce.ts","../../src/controllers/empty_state_controller.ts"],"names":[],"mappings":"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","file":"empty_state_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","import { Controller } from \"@hotwired/stimulus\";\nimport { announce, fillTemplate } from \"../utils/announce\";\n\n/**\n * Headless empty-state behavior: shows an \"empty\" placeholder when a list has no\n * items and hides it once one arrives (and vice-versa), watching the list with a\n * `MutationObserver` (no dedicated APG pattern; follows the WCAG \"status messages\"\n * practice when announcing).\n *\n * Markup contract (identifier: `stimeo--empty-state`):\n *   <div data-controller=\"stimeo--empty-state\">\n *     <ul data-stimeo--empty-state-target=\"list\"><!-- Turbo Stream rows --></ul>\n *     <p data-stimeo--empty-state-target=\"empty\" hidden>No items</p>\n *   </div>\n *\n * Counts `list`'s child items (all element children, or those matching\n * `itemSelector`) on connect and on every mutation that can change that count,\n * toggles `hidden` on `list` / `empty` at the 0 ↔ 1+ boundary, and reflects\n * `data-empty` / `data-count` on the controller element. Crossing the boundary\n * dispatches `change` after the display is updated, so a listener reads the\n * state the crossing produced.\n *\n * @remarks\n * Behavior only — the placeholder's look/copy is the consumer's. State is derived\n * from the DOM (no module-scope state), so `connect()` re-syncs after a Turbo\n * Stream insertion. Both targets are re-resolved at runtime: a `list` element\n * swapped in re-points the observation, and a swapped-in `empty` element is\n * re-synced — including when the replacement is inserted while the original is\n * still in the document. The `MutationObserver` is severed on `disconnect()`\n * (Turbo navigation included). `announceText` / `announceFilledText` are read at\n * the crossing and handed to the page's announcer.\n *\n * Ownership note: this controller deliberately owns `hidden` on the `list` / `empty`\n * targets as its single source of truth for which one is shown, rather than only\n * emitting `data-empty` and delegating visibility to consumer CSS. The toggle is\n * unconditional (set every sync), so there is nothing to save/restore and no\n * authored `hidden` to preserve — the displayed half is always a pure function of\n * the item count. Consumers wanting CSS-driven visibility should not also set\n * `hidden` on these targets themselves.\n */\nexport class EmptyStateController extends Controller<HTMLElement> {\n  static override targets = [\"list\", \"empty\"];\n  static override values = {\n    itemSelector: { type: String, default: \"\" },\n    announceText: { type: String, default: \"\" },\n    announceFilledText: { type: String, default: \"\" },\n  };\n  static events = [\"change\"] as const;\n\n  declare readonly listTarget: HTMLElement;\n  declare readonly emptyTarget: HTMLElement;\n  declare readonly hasListTarget: boolean;\n  declare readonly hasEmptyTarget: boolean;\n\n  declare itemSelectorValue: string;\n  declare announceTextValue: string;\n  declare announceFilledTextValue: string;\n\n  #observer: MutationObserver | null = null;\n  /** Whether the controller is between `connect()` and `disconnect()`. */\n  #connected = false;\n  /** Last applied empty state; `null` until the first sync so connect emits nothing. */\n  #empty: boolean | null = null;\n\n  override connect(): void {\n    this.#connected = true;\n    this.#syncObservation();\n    this.#update();\n  }\n\n  override disconnect(): void {\n    this.#connected = false;\n    this.#stopObserving();\n  }\n\n  /** Follows a `list` element swapped in at runtime (Turbo Stream `replace` / morph). */\n  listTargetConnected(): void {\n    this.#resync();\n  }\n\n  /** Releases the observation when the `list` element leaves the target set. */\n  listTargetDisconnected(): void {\n    this.#resync();\n  }\n\n  /** Syncs an `empty` element that arrives — or is replaced — at runtime. */\n  emptyTargetConnected(): void {\n    this.#resync();\n  }\n\n  /**\n   * Syncs the `empty` element that remains when one leaves the target set. A\n   * single-target getter resolves to the first `empty` element in document order,\n   * so a swap that inserts the replacement *before* removing the original (Turbo\n   * Stream `after` / `before` / `append` followed by `remove`) leaves the\n   * replacement untouched until the original goes — this callback is that moment.\n   */\n  emptyTargetDisconnected(): void {\n    this.#resync();\n  }\n\n  /** Re-renders when application code (or a Turbo morph) changes `itemSelector` at runtime. */\n  itemSelectorValueChanged(): void {\n    this.#resync();\n  }\n\n  /**\n   * Re-points the observation and re-renders after a target or selector change.\n   * The `#connected` guard is load-bearing: Stimulus runs value and target\n   * callbacks for the initial markup *before* `connect()` and runs target\n   * callbacks during teardown *after* `disconnect()`, and re-observing there\n   * would outlive the controller.\n   */\n  #resync(): void {\n    if (!this.#connected) return;\n    this.#syncObservation();\n    this.#update();\n  }\n\n  /**\n   * Points the mutation observation at the current `list` target — re-resolved on\n   * every sync rather than captured at connect, so an element swapped in at\n   * runtime is observed instead of the detached original.\n   *\n   * The observation covers exactly what the count predicate reads. With no\n   * `itemSelector` the count is the child element count, which only `childList`\n   * can change. With one, the predicate reads the children themselves, so\n   * attribute and descendant mutations are watched too — and the controller's own\n   * writes are filtered back out, or toggling `hidden` would re-enter the render.\n   */\n  #syncObservation(): void {\n    this.#stopObserving();\n    if (!this.hasListTarget || typeof MutationObserver === \"undefined\") return;\n    const watchesItems = this.itemSelectorValue.length > 0;\n    this.#observer = new MutationObserver((records) => {\n      if (records.some((record) => this.#affectsCount(record))) this.#update();\n    });\n    this.#observer.observe(this.listTarget, {\n      childList: true,\n      subtree: watchesItems,\n      attributes: watchesItems,\n    });\n  }\n\n  #stopObserving(): void {\n    this.#observer?.disconnect();\n    this.#observer = null;\n  }\n\n  /**\n   * Whether a mutation can change the item count. An attribute written on a\n   * target this controller owns is its own echo — `hidden` on `list` / `empty`,\n   * and the hooks on the controller element when the list *is* that element.\n   */\n  #affectsCount(record: MutationRecord): boolean {\n    if (record.type !== \"attributes\") return true;\n    const own =\n      record.target === this.listTarget ||\n      (this.hasEmptyTarget && record.target === this.emptyTarget);\n    return !own;\n  }\n\n  /**\n   * Renders the count, then reports a crossed boundary. The announcement copy is\n   * read here rather than while rendering: it is the wording of the report, not\n   * an input to what is displayed.\n   */\n  #update(): void {\n    const count = this.#render();\n    if (count === null) return;\n    const empty = count === 0;\n    // Report only when the 0 ↔ 1+ boundary is crossed (not on the initial sync,\n    // and not for count changes that stay non-empty, e.g. 2 → 3).\n    const crossed = this.#empty !== null && empty !== this.#empty;\n    this.#empty = empty;\n    if (!crossed) return;\n\n    this.dispatch(\"change\", { detail: { count, empty } });\n    // The crossing is the news, and the page's announcer reads it: a region that\n    // only becomes live when the empty state appears is not reliably announced.\n    announce(\n      fillTemplate(empty ? this.announceTextValue : this.announceFilledTextValue, { count }),\n    );\n  }\n\n  /**\n   * Syncs visibility and the state hooks to the current item count, and returns\n   * it. `null` when there is no `list` target to count.\n   *\n   * @stimeoRenderRoot\n   */\n  #render(): number | null {\n    if (!this.hasListTarget) return null;\n    const count = this.#count();\n    const empty = count === 0;\n\n    this.element.setAttribute(\"data-count\", String(count));\n    if (empty) {\n      this.element.setAttribute(\"data-empty\", \"true\");\n    } else {\n      this.element.removeAttribute(\"data-empty\");\n    }\n    this.listTarget.hidden = empty;\n    if (this.hasEmptyTarget) this.emptyTarget.hidden = !empty;\n    return count;\n  }\n\n  /** Item count: element children matching `itemSelector`, or all element children. */\n  #count(): number {\n    const selector = this.itemSelectorValue;\n    if (selector.length === 0) return this.listTarget.childElementCount;\n    try {\n      return Array.from(this.listTarget.children).filter((child) => child.matches(selector)).length;\n    } catch {\n      // An invalid selector (author typo) must not crash the controller — count all.\n      return this.listTarget.childElementCount;\n    }\n  }\n}\n"]}

package/dist/controllers/flash_controller.d.ts

@@ -15,9 +15,9 @@ import { Controller } from '@hotwired/stimulus';
  *
  * Each message is mapped by `data-flash-type` to `role="status"` (notice) or
  * `role="alert"` (alert/error), flagged `data-flash-state="visible"`, auto-dismissed
- * after `duration` (paused while hovered/focused when `pauseOnHover`), and capped at
- * `max` simultaneous messages. A close button wired to the `dismiss` action removes
- * one manually.
+ * after `duration` (paused while hovered *or* focused when `pauseOnHover`, and
+ * resumed only once both are released), and capped at `max` simultaneous messages.
+ * A close button wired to the `dismiss` action removes one manually.
  *
  * @remarks
  * Reading is **delegated to the shared Announcer** — but only for the *initial*,
@@ -26,8 +26,14 @@ import { Controller } from '@hotwired/stimulus';
  * event. Messages inserted *later* (Turbo Stream) are announced by their own freshly
  * inserted `role`, exactly like Toast, so they are not bridged again (no double
  * announcement). Behavior only — no styling; `data-flash-state="leaving"` lets CSS
- * animate removal. Focus is never moved (WCAG 2.2 4.1.3). The observer, timers, and
- * per-message listeners are torn down on `disconnect()` (Turbo navigation included).
+ * animate removal. Focus is never moved (WCAG 2.2 4.1.3): pausing never removes a
+ * message, so the control under the pointer or holding focus stays put. The
+ * observation follows a `region` element replaced at runtime; the managed set is the
+ * current region's subtree, and a message that leaves it gives up its stacking slot,
+ * its pending auto-dismiss, and any removal already scheduled. The observer, timers,
+ * and per-message listeners are torn down on `disconnect()` (Turbo navigation
+ * included), and the managed flashes leave the page before Turbo caches it so a
+ * restored snapshot does not replay a notification the visitor already received.
  */
 declare class FlashController extends Controller<HTMLElement> {
     #private;
@@ -56,6 +62,20 @@ declare class FlashController extends Controller<HTMLElement> {
     maxValue: number;
     connect(): void;
     disconnect(): void;
+    /** Follows a `region` element swapped in — or arriving — at runtime (Turbo Stream). */
+    regionTargetConnected(): void;
+    /** Releases the observation when the `region` element leaves the target set. */
+    regionTargetDisconnected(): void;
+    /**
+     * Releases a message that left the target set (a Turbo Stream `remove`, the consumer
+     * detaching the node, or a morph that rewrote the target attribute in place): it
+     * stops occupying a `max` slot, and both its pending auto-dismiss and an already
+     * scheduled removal are cancelled. A move *within* the region keeps all of them —
+     * which is why the element must still be a message to be treated as one: ownership
+     * alone reads an in-place attribute rewrite as a move, and a node outside the target
+     * set belongs to the consumer, so nothing here may dismiss it.
+     */
+    messageTargetDisconnected(message: HTMLElement): void;
     /** Dismisses the flash whose close control fired the event. */
     dismiss(event: Event): void;
 }

package/dist/controllers/flash_controller.js

@@ -2,6 +2,35 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/flash_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/safe_timeout.ts
 var TimerRegistry = class {
   /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
@@ -103,29 +132,119 @@ var FlashController = class extends Controller {
   static events = ["show", "dismiss"];
   #timers = new SafeTimeout();
   #observer = null;
+  /** Whether the controller is between `connect()` and `disconnect()`. */
+  #connected = false;
   /** Auto-dismiss timer state keyed by message element. */
   #state = /* @__PURE__ */ new Map();
   /** Messages already processed, in insertion order, to enforce `max` and avoid double work. */
   #order = [];
-  #onEnter = (event) => this.#pause(event.currentTarget);
-  #onLeave = (event) => this.#resume(event.currentTarget);
+  /**
+   * Messages between `leaving` and their removal. {@link FlashController.#beginDismiss}
+   * releases the bookkeeping above *before* the transition wait, so for that window the
+   * element is in the DOM but in neither collection — without this set a re-scan would
+   * read it as a brand-new flash and show it a second time.
+   */
+  #leaving = /* @__PURE__ */ new Set();
+  #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
+  #onEnter = (event) => this.#pause(event.currentTarget, event.type === "focusin" ? "focus" : "hover");
+  #onLeave = (event) => this.#resume(event.currentTarget, event.type === "focusout" ? "focus" : "hover");
   connect() {
-    if (!this.hasRegionTarget) return;
+    this.#connected = true;
     for (const message of this.messageTargets) {
-      this.#process(message, true);
-    }
-    if (typeof MutationObserver !== "undefined") {
-      this.#observer = new MutationObserver((mutations) => this.#onMutations(mutations));
-      this.#observer.observe(this.regionTarget, { childList: true, subtree: true });
+      if (this.#owns(message)) this.#process(message, true);
     }
+    this.#syncObservation();
+    this.#beforeCache.activate();
   }
   disconnect() {
-    this.#observer?.disconnect();
-    this.#observer = null;
+    this.#connected = false;
+    this.#beforeCache.deactivate();
+    this.#stopObserving();
     this.#timers.clearAll();
     for (const message of this.#order) this.#unbindPause(message);
     this.#state.clear();
     this.#order.length = 0;
+    this.#leaving.clear();
+  }
+  /**
+   * Takes the managed flashes out of the page just before Turbo freezes it, so a
+   * restored snapshot carries no notification the visitor has already received: the
+   * fresh `connect()` there reads a leftover flash as a brand-new one and announces it
+   * a second time. A message that never auto-dismisses (`duration: 0`) is one of these
+   * too — that value governs the timer, not what belongs in a cached page. Removal
+   * only: `dismiss` reports a dismissal, and freezing the page is not one.
+   */
+  #rewindForCache() {
+    for (const message of [...this.#order]) {
+      message.remove();
+      this.#forget(message);
+    }
+    for (const message of this.#leaving) message.remove();
+    this.#leaving.clear();
+  }
+  /** Follows a `region` element swapped in — or arriving — at runtime (Turbo Stream). */
+  regionTargetConnected() {
+    this.#resync();
+  }
+  /** Releases the observation when the `region` element leaves the target set. */
+  regionTargetDisconnected() {
+    this.#resync();
+  }
+  /**
+   * Whether this controller owns `message`. Ownership is the current `region`'s
+   * subtree: a message target anywhere else in the controller's scope is the
+   * consumer's, and so is one in a region that has gone away. The initial scan, a
+   * re-scan after a `region` swap, and a departure from the target set all resolve
+   * ownership through this one test; the observation gets it structurally, by watching
+   * that subtree and nothing else.
+   */
+  #owns(message) {
+    return this.hasRegionTarget && this.regionTarget.contains(message);
+  }
+  /**
+   * Releases a message that left the target set (a Turbo Stream `remove`, the consumer
+   * detaching the node, or a morph that rewrote the target attribute in place): it
+   * stops occupying a `max` slot, and both its pending auto-dismiss and an already
+   * scheduled removal are cancelled. A move *within* the region keeps all of them —
+   * which is why the element must still be a message to be treated as one: ownership
+   * alone reads an in-place attribute rewrite as a move, and a node outside the target
+   * set belongs to the consumer, so nothing here may dismiss it.
+   */
+  messageTargetDisconnected(message) {
+    if (!this.#connected) return;
+    const moved = this.#owns(message) && message.matches(MESSAGE_SELECTOR);
+    if (moved) return;
+    this.#forget(message);
+    this.#leaving.delete(message);
+  }
+  /**
+   * Re-points the observation after a `region` swap and picks up the messages the
+   * new element brought with it (dynamic inserts, so their own `role` announces
+   * them). The `#connected` guard is load-bearing: Stimulus runs target callbacks
+   * for the initial markup *before* `connect()` and again during teardown *after*
+   * `disconnect()`, and re-observing there would outlive the controller.
+   */
+  #resync() {
+    if (!this.#connected) return;
+    this.#syncObservation();
+    for (const message of this.messageTargets) {
+      if (this.#owns(message)) this.#process(message, false);
+    }
+  }
+  /**
+   * Points the mutation observation at the current `region` target, re-resolved on
+   * every sync rather than captured at connect, so an element swapped in at runtime
+   * is observed instead of the detached original.
+   */
+  #syncObservation() {
+    this.#stopObserving();
+    if (!this.hasRegionTarget || typeof MutationObserver === "undefined") return;
+    this.#observer = new MutationObserver((mutations) => this.#onMutations(mutations));
+    this.#observer.observe(this.regionTarget, { childList: true, subtree: true });
+  }
+  #stopObserving() {
+    this.#observer?.disconnect();
+    this.#observer = null;
   }
   /**
    * Pause-on-hover/focus listeners, bound and unbound as a pair so the two sides
@@ -171,6 +290,7 @@ var FlashController = class extends Controller {
    */
   #process(message, bridge) {
     if (this.#state.has(message) || this.#order.includes(message)) return;
+    if (this.#leaving.has(message)) return;
     const type = message.getAttribute("data-flash-type") ?? "";
     const assertive = ASSERTIVE_TYPES.has(type);
     if (!message.hasAttribute("role")) {
@@ -203,33 +323,53 @@ var FlashController = class extends Controller {
     const existing = this.#state.get(message);
     if (existing?.id) this.#timers.clear(existing.id);
     const id = this.#timers.set(() => this.#beginDismiss(message, "timeout"), duration);
-    this.#state.set(message, { id, startedAt: Date.now(), remaining: duration });
+    this.#state.set(message, {
+      id,
+      startedAt: Date.now(),
+      remaining: duration,
+      paused: existing?.paused ?? /* @__PURE__ */ new Set()
+    });
   }
-  /** Pauses a message's auto-dismiss, banking the time left (hover/focus, WCAG 2.2.1). */
-  #pause(message) {
+  /**
+   * Pauses a message's auto-dismiss, banking the time left (hover/focus, WCAG 2.2.1).
+   * Hover and focus are independent reasons: the remaining time is banked on the
+   * first of them, and {@link FlashController.#resume} waits for the last one.
+   */
+  #pause(message, reason) {
     const timer = this.#state.get(message);
-    if (!timer || timer.id === 0) return;
+    if (!timer) return;
+    timer.paused.add(reason);
+    if (timer.id === 0) return;
     this.#timers.clear(timer.id);
-    const remaining = Math.max(0, timer.remaining - (Date.now() - timer.startedAt));
-    this.#state.set(message, { id: 0, startedAt: 0, remaining });
+    const remaining = Math.max(1, timer.remaining - (Date.now() - timer.startedAt));
+    this.#state.set(message, { id: 0, startedAt: 0, remaining, paused: timer.paused });
   }
   /** Resumes a paused message's auto-dismiss with the banked time. */
-  #resume(message) {
+  #resume(message, reason) {
     const timer = this.#state.get(message);
     if (!timer) return;
-    if (timer.id !== 0 || timer.remaining <= 0) return;
+    timer.paused.delete(reason);
+    if (timer.paused.size > 0) return;
+    if (timer.id !== 0) return;
     this.#startTimer(message, timer.remaining);
   }
-  /** Marks a message leaving, then removes it after its CSS transition and emits dismiss. */
-  #beginDismiss(message, reason) {
+  /** Releases every per-message resource: timer, stacking slot, pause listeners. */
+  #forget(message) {
     const timer = this.#state.get(message);
     if (timer?.id) this.#timers.clear(timer.id);
     this.#state.delete(message);
     const index = this.#order.indexOf(message);
     if (index !== -1) this.#order.splice(index, 1);
+    this.#unbindPause(message);
+  }
+  /** Marks a message leaving, then removes it after its CSS transition and emits dismiss. */
+  #beginDismiss(message, reason) {
+    if (!this.#state.has(message) && !this.#order.includes(message)) return;
+    this.#forget(message);
+    this.#leaving.add(message);
     message.setAttribute("data-flash-state", "leaving");
     const finalize = () => {
-      this.#unbindPause(message);
+      if (!this.#leaving.delete(message)) return;
       message.remove();
       this.dispatch("dismiss", { detail: { element: message, reason } });
     };