stimeo-ui 0.9.0 → 0.11.0

package/dist/controllers/password_reveal_controller.js

@@ -2,6 +2,35 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/password_reveal_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). */
@@ -56,6 +85,7 @@ var SafeTimeout = class extends TimerRegistry {
 };
 
 // src/controllers/password_reveal_controller.ts
+var MAX_DELAY = 2 ** 31 - 1;
 var PasswordRevealController = class extends Controller {
   static targets = ["input", "toggle"];
   static values = {
@@ -65,11 +95,54 @@ var PasswordRevealController = class extends Controller {
   static events = ["toggle"];
   /** Auto re-mask timer; torn down on disconnect. */
   #timers = new SafeTimeout();
+  /**
+   * Whether this controller is between `connect()` and `disconnect()`.
+   *
+   * Target callbacks outlive the controller: Stimulus stops the target observer
+   * after `disconnect()`, so a field leaving after teardown still reaches
+   * {@link PasswordRevealController.inputTargetDisconnected}. Arming from there
+   * would put a timer back that nothing will clear. The element staying in the
+   * document does not answer this — unloading the controller leaves it there.
+   */
+  #connected = false;
+  /** Masks the field before Turbo copies the page into its snapshot. */
+  #beforeCache = new BeforeCacheReset(() => this.#rewindToMasked());
   connect() {
-    this.#reflect(this.#isVisible);
+    this.#connected = true;
+    const visible = this.#isVisible;
+    this.#reflect(visible);
+    this.#beforeCache.activate();
+    this.#arm(visible);
   }
   disconnect() {
+    this.#connected = false;
     this.#timers.clearAll();
+    this.#beforeCache.deactivate();
+  }
+  /** Re-derives the hooks and the re-mask for a field swapped in after connect. */
+  inputTargetConnected() {
+    const visible = this.#connected && this.#isVisible;
+    this.#reflect(visible);
+    this.#arm(visible);
+  }
+  /**
+   * Re-derives from whatever field is left rather than assuming none is. A swap
+   * delivers this callback next to the arrival in either order, so a revealed
+   * replacement that answered "masked" here would be described as hidden while
+   * showing the password, and would carry no re-mask.
+   *
+   * Teardown is the one case with nothing to derive: target callbacks run after
+   * `disconnect()`, so the field is still revealed and re-arming from it would
+   * outlive the controller. A detached root is the signal to stand down.
+   */
+  inputTargetDisconnected() {
+    const visible = this.#connected && this.element.isConnected && this.#isVisible;
+    this.#reflect(visible);
+    this.#arm(visible);
+  }
+  /** Re-derives the pressed state for a button swapped in after connect. */
+  toggleTargetConnected() {
+    this.#reflect(this.#isVisible);
   }
   /** Toggles the input between masked and revealed. Bound via `data-action`. */
   toggle() {
@@ -98,11 +171,37 @@ var PasswordRevealController = class extends Controller {
     }
     this.#reflect(visible);
     this.dispatch("toggle", { detail: { visible } });
+    this.#arm(visible);
+  }
+  /** Schedules the auto re-mask for a revealed field, replacing any pending one. */
+  #arm(visible) {
     this.#timers.clearAll();
-    if (visible && this.autoHideValue > 0) {
-      this.#timers.set(() => this.#setVisible(false), this.autoHideValue);
+    const delay = this.#autoHideDelay;
+    if (visible && delay > 0) {
+      this.#timers.set(() => this.#setVisible(false), delay);
     }
   }
+  /**
+   * The auto re-mask delay, held to what `setTimeout` can carry. Past that limit
+   * a delay folds to zero, turning "keep it showing" into "hide it at once" —
+   * the opposite of what the declaration asked for. A value that is no delay at
+   * all stays out of the positive range {@link PasswordRevealController.#arm}
+   * requires, so it schedules nothing.
+   */
+  get #autoHideDelay() {
+    return Math.min(this.autoHideValue, MAX_DELAY);
+  }
+  /**
+   * Returns the field to masked before Turbo copies the page. Silent and
+   * focus-free: the page is about to be frozen, so there is no one to tell and
+   * nowhere for focus to go.
+   */
+  #rewindToMasked() {
+    this.#timers.clearAll();
+    if (!this.hasInputTarget) return;
+    this.inputTarget.type = "password";
+    this.#reflect(false);
+  }
   /** Reflects the visible state onto `aria-pressed` and `data-state`. */
   #reflect(visible) {
     if (this.hasToggleTarget) {

package/dist/controllers/password_reveal_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/safe_timeout.ts","../../src/controllers/password_reveal_controller.ts"],"names":[],"mappings":"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","file":"password_reveal_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 password show/hide (unmask) toggle behavior.\n *\n * Markup contract (identifier: `stimeo--password-reveal`):\n *   <div data-controller=\"stimeo--password-reveal\">\n *     <input type=\"password\" aria-label=\"Password\"\n *            data-stimeo--password-reveal-target=\"input\">\n *     <button type=\"button\" aria-pressed=\"false\" aria-label=\"Show password\"\n *             data-stimeo--password-reveal-target=\"toggle\"\n *             data-action=\"stimeo--password-reveal#toggle\"></button>\n *   </div>\n *\n * No dedicated APG pattern; this follows the toggle **Button** practice. The\n * accessible name stays state-independent (\"Show password\") while the pressed\n * state is conveyed by `aria-pressed`.\n *\n * `toggle` dispatches `{ visible: boolean }`.\n *\n * @remarks\n * Behavior only — icon rendering is the consumer's, keyed off `aria-pressed` /\n * `data-state` (`hidden` / `visible`). Flipping `input.type` can drop focus and\n * the caret, so when (and only when) the input was the focused element its focus\n * and selection are restored afterward; when the toggle button holds focus\n * (keyboard use) focus is left on the button. An optional `autoHide` re-masks\n * after a delay, and that timer is torn down on disconnect (Turbo).\n */\nexport class PasswordRevealController extends Controller<HTMLElement> {\n  static override targets = [\"input\", \"toggle\"];\n  static override values = {\n    autoHide: { type: Number, default: 0 },\n  };\n  static actions = [\"toggle\"] as const;\n  static events = [\"toggle\"] as const;\n\n  declare readonly inputTarget: HTMLInputElement;\n  declare readonly toggleTarget: HTMLElement;\n  declare readonly hasInputTarget: boolean;\n  declare readonly hasToggleTarget: boolean;\n\n  declare autoHideValue: number;\n\n  /** Auto re-mask timer; torn down on disconnect. */\n  #timers = new SafeTimeout();\n\n  override connect(): void {\n    this.#reflect(this.#isVisible);\n  }\n\n  override disconnect(): void {\n    this.#timers.clearAll();\n  }\n\n  /** Toggles the input between masked and revealed. Bound via `data-action`. */\n  toggle(): void {\n    this.#setVisible(!this.#isVisible);\n  }\n\n  /** Whether the input is currently revealed (`type=\"text\"`). */\n  get #isVisible(): boolean {\n    return this.hasInputTarget && this.inputTarget.type === \"text\";\n  }\n\n  /** Switches the masked/revealed state, preserving focus and caret. */\n  #setVisible(visible: boolean): void {\n    if (!this.hasInputTarget) return;\n    const input = this.inputTarget;\n\n    // Only the input's *own* focus is restored across the type change; if the\n    // toggle button (keyboard) holds focus, it is left untouched.\n    const restoreInputFocus = document.activeElement === input;\n    const selectionStart = input.selectionStart;\n    const selectionEnd = input.selectionEnd;\n\n    input.type = visible ? \"text\" : \"password\";\n\n    if (restoreInputFocus) {\n      input.focus();\n      // `selectionStart` / `selectionEnd` are `number | null` (null for input\n      // types that don't expose a selection); only restore when both are present.\n      if (selectionStart !== null && selectionEnd !== null) {\n        try {\n          input.setSelectionRange(selectionStart, selectionEnd);\n        } catch {\n          // Some input types reject selection access; focus alone is enough.\n        }\n      }\n    }\n\n    this.#reflect(visible);\n    this.dispatch(\"toggle\", { detail: { visible } });\n\n    this.#timers.clearAll();\n    if (visible && this.autoHideValue > 0) {\n      this.#timers.set(() => this.#setVisible(false), this.autoHideValue);\n    }\n  }\n\n  /** Reflects the visible state onto `aria-pressed` and `data-state`. */\n  #reflect(visible: boolean): void {\n    if (this.hasToggleTarget) {\n      this.toggleTarget.setAttribute(\"aria-pressed\", visible ? \"true\" : \"false\");\n    }\n    this.element.setAttribute(\"data-state\", visible ? \"visible\" : \"hidden\");\n  }\n}\n"]}
+{"version":3,"sources":["../../src/utils/before_cache_reset.ts","../../src/utils/safe_timeout.ts","../../src/controllers/password_reveal_controller.ts"],"names":[],"mappings":";;;;;AA2CO,IAAM,gBAAA,GAAN,MAAM,iBAAA,CAAiB;AAAA;AAAA,EAE5B,OAAgB,YAAA,mBAAe,IAAI,GAAA,EAAsB;AAAA;AAAA,EAGzD,OAAgB,iBAAiB,MAAY;AAC3C,IAAA,KAAA,MAAW,UAAA,IAAc,iBAAA,CAAiB,YAAA,EAAc,UAAA,CAAW,OAAA,EAAQ;AAAA,EAC7E,CAAA;AAAA,EAES,OAAA;AAAA;AAAA,EAGT,YAAY,MAAA,EAAoB;AAC9B,IAAA,IAAA,CAAK,OAAA,GAAU,MAAA;AAAA,EACjB;AAAA;AAAA,EAGA,QAAA,GAAiB;AACf,IAAA,MAAM,KAAA,GAAQ,iBAAA,CAAiB,YAAA,CAAa,IAAA,KAAS,CAAA;AACrD,IAAA,iBAAA,CAAiB,YAAA,CAAa,IAAI,IAAI,CAAA;AACtC,IAAA,IAAI,KAAA,EAAO;AACT,MAAA,QAAA,CAAS,gBAAA,CAAiB,oBAAA,EAAsB,iBAAA,CAAiB,cAAc,CAAA;AAAA,IACjF;AAAA,EACF;AAAA;AAAA,EAGA,UAAA,GAAmB;AACjB,IAAA,iBAAA,CAAiB,YAAA,CAAa,OAAO,IAAI,CAAA;AACzC,IAAA,IAAI,iBAAA,CAAiB,YAAA,CAAa,IAAA,GAAO,CAAA,EAAG;AAC5C,IAAA,QAAA,CAAS,mBAAA,CAAoB,oBAAA,EAAsB,iBAAA,CAAiB,cAAc,CAAA;AAAA,EACpF;AACF,CAAA;;;AClDA,IAAe,gBAAf,MAA6B;AAAA;AAAA,EAER,GAAA,uBAAU,GAAA,EAAY;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAczC,MAAM,EAAA,EAAkB;AACtB,IAAA,IAAI,IAAA,CAAK,GAAA,CAAI,MAAA,CAAO,EAAE,CAAA,EAAG;AACvB,MAAA,IAAA,CAAK,OAAO,EAAE,CAAA;AAAA,IAChB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,QAAA,GAAiB;AACf,IAAA,KAAA,MAAW,EAAA,IAAM,KAAK,GAAA,EAAK;AACzB,MAAA,IAAA,CAAK,OAAO,EAAE,CAAA;AAAA,IAChB;AACA,IAAA,IAAA,CAAK,IAAI,KAAA,EAAM;AAAA,EACjB;AAAA;AAAA,EAGA,IAAI,IAAA,GAAe;AACjB,IAAA,OAAO,KAAK,GAAA,CAAI,IAAA;AAAA,EAClB;AACF,CAAA;AAmBO,IAAM,WAAA,GAAN,cAA0B,aAAA,CAAc;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAO7C,GAAA,CAAI,UAAsB,KAAA,EAAuB;AAC/C,IAAA,MAAM,EAAA,GAAK,IAAA,CAAK,QAAA,CAAS,MAAM;AAC7B,MAAA,IAAA,CAAK,GAAA,CAAI,OAAO,EAAE,CAAA;AAClB,MAAA,QAAA,EAAS;AAAA,IACX,GAAG,KAAK,CAAA;AACR,IAAA,IAAA,CAAK,GAAA,CAAI,IAAI,EAAE,CAAA;AACf,IAAA,OAAO,EAAA;AAAA,EACT;AAAA,EAEU,QAAA,CAAS,UAAsB,KAAA,EAAuB;AAC9D,IAAA,OAAO,MAAA,CAAO,UAAA,CAAW,QAAA,EAAU,KAAK,CAAA;AAAA,EAC1C;AAAA,EAEU,OAAO,EAAA,EAAkB;AACjC,IAAA,MAAA,CAAO,aAAa,EAAE,CAAA;AAAA,EACxB;AACF,CAAA;;;AClGA,IAAM,SAAA,GAAY,KAAK,EAAA,GAAK,CAAA;AAsCrB,IAAM,wBAAA,GAAN,cAAuC,UAAA,CAAwB;AAAA,EACpE,OAAgB,OAAA,GAAU,CAAC,OAAA,EAAS,QAAQ,CAAA;AAAA,EAC5C,OAAgB,MAAA,GAAS;AAAA,IACvB,QAAA,EAAU,EAAE,IAAA,EAAM,MAAA,EAAQ,SAAS,CAAA;AAAE,GACvC;AAAA,EACA,OAAO,OAAA,GAAU,CAAC,QAAQ,CAAA;AAAA,EAC1B,OAAO,MAAA,GAAS,CAAC,QAAQ,CAAA;AAAA;AAAA,EAUzB,OAAA,GAAU,IAAI,WAAA,EAAY;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAW1B,UAAA,GAAa,KAAA;AAAA;AAAA,EAGJ,eAAe,IAAI,gBAAA,CAAiB,MAAM,IAAA,CAAK,iBAAiB,CAAA;AAAA,EAEhE,OAAA,GAAgB;AACvB,IAAA,IAAA,CAAK,UAAA,GAAa,IAAA;AAClB,IAAA,MAAM,UAAU,IAAA,CAAK,UAAA;AACrB,IAAA,IAAA,CAAK,SAAS,OAAO,CAAA;AACrB,IAAA,IAAA,CAAK,aAAa,QAAA,EAAS;AAG3B,IAAA,IAAA,CAAK,KAAK,OAAO,CAAA;AAAA,EACnB;AAAA,EAES,UAAA,GAAmB;AAC1B,IAAA,IAAA,CAAK,UAAA,GAAa,KAAA;AAClB,IAAA,IAAA,CAAK,QAAQ,QAAA,EAAS;AACtB,IAAA,IAAA,CAAK,aAAa,UAAA,EAAW;AAAA,EAC/B;AAAA;AAAA,EAGA,oBAAA,GAA6B;AAC3B,IAAA,MAAM,OAAA,GAAU,IAAA,CAAK,UAAA,IAAc,IAAA,CAAK,UAAA;AACxC,IAAA,IAAA,CAAK,SAAS,OAAO,CAAA;AACrB,IAAA,IAAA,CAAK,KAAK,OAAO,CAAA;AAAA,EACnB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYA,uBAAA,GAAgC;AAC9B,IAAA,MAAM,UAAU,IAAA,CAAK,UAAA,IAAc,IAAA,CAAK,OAAA,CAAQ,eAAe,IAAA,CAAK,UAAA;AACpE,IAAA,IAAA,CAAK,SAAS,OAAO,CAAA;AACrB,IAAA,IAAA,CAAK,KAAK,OAAO,CAAA;AAAA,EACnB;AAAA;AAAA,EAGA,qBAAA,GAA8B;AAC5B,IAAA,IAAA,CAAK,QAAA,CAAS,KAAK,UAAU,CAAA;AAAA,EAC/B;AAAA;AAAA,EAGA,MAAA,GAAe;AACb,IAAA,IAAA,CAAK,WAAA,CAAY,CAAC,IAAA,CAAK,UAAU,CAAA;AAAA,EACnC;AAAA;AAAA,EAGA,IAAI,UAAA,GAAsB;AACxB,IAAA,OAAO,IAAA,CAAK,cAAA,IAAkB,IAAA,CAAK,WAAA,CAAY,IAAA,KAAS,MAAA;AAAA,EAC1D;AAAA;AAAA,EAGA,YAAY,OAAA,EAAwB;AAClC,IAAA,IAAI,CAAC,KAAK,cAAA,EAAgB;AAC1B,IAAA,MAAM,QAAQ,IAAA,CAAK,WAAA;AAInB,IAAA,MAAM,iBAAA,GAAoB,SAAS,aAAA,KAAkB,KAAA;AACrD,IAAA,MAAM,iBAAiB,KAAA,CAAM,cAAA;AAC7B,IAAA,MAAM,eAAe,KAAA,CAAM,YAAA;AAE3B,IAAA,KAAA,CAAM,IAAA,GAAO,UAAU,MAAA,GAAS,UAAA;AAEhC,IAAA,IAAI,iBAAA,EAAmB;AACrB,MAAA,KAAA,CAAM,KAAA,EAAM;AAGZ,MAAA,IAAI,cAAA,KAAmB,IAAA,IAAQ,YAAA,KAAiB,IAAA,EAAM;AACpD,QAAA,IAAI;AACF,UAAA,KAAA,CAAM,iBAAA,CAAkB,gBAAgB,YAAY,CAAA;AAAA,QACtD,CAAA,CAAA,MAAQ;AAAA,QAER;AAAA,MACF;AAAA,IACF;AAEA,IAAA,IAAA,CAAK,SAAS,OAAO,CAAA;AACrB,IAAA,IAAA,CAAK,SAAS,QAAA,EAAU,EAAE,QAAQ,EAAE,OAAA,IAAW,CAAA;AAC/C,IAAA,IAAA,CAAK,KAAK,OAAO,CAAA;AAAA,EACnB;AAAA;AAAA,EAGA,KAAK,OAAA,EAAwB;AAC3B,IAAA,IAAA,CAAK,QAAQ,QAAA,EAAS;AACtB,IAAA,MAAM,QAAQ,IAAA,CAAK,cAAA;AACnB,IAAA,IAAI,OAAA,IAAW,QAAQ,CAAA,EAAG;AACxB,MAAA,IAAA,CAAK,QAAQ,GAAA,CAAI,MAAM,KAAK,WAAA,CAAY,KAAK,GAAG,KAAK,CAAA;AAAA,IACvD;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,IAAI,cAAA,GAAyB;AAC3B,IAAA,OAAO,IAAA,CAAK,GAAA,CAAI,IAAA,CAAK,aAAA,EAAe,SAAS,CAAA;AAAA,EAC/C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,eAAA,GAAwB;AACtB,IAAA,IAAA,CAAK,QAAQ,QAAA,EAAS;AACtB,IAAA,IAAI,CAAC,KAAK,cAAA,EAAgB;AAC1B,IAAA,IAAA,CAAK,YAAY,IAAA,GAAO,UAAA;AACxB,IAAA,IAAA,CAAK,SAAS,KAAK,CAAA;AAAA,EACrB;AAAA;AAAA,EAGA,SAAS,OAAA,EAAwB;AAC/B,IAAA,IAAI,KAAK,eAAA,EAAiB;AACxB,MAAA,IAAA,CAAK,YAAA,CAAa,YAAA,CAAa,cAAA,EAAgB,OAAA,GAAU,SAAS,OAAO,CAAA;AAAA,IAC3E;AACA,IAAA,IAAA,CAAK,OAAA,CAAQ,YAAA,CAAa,YAAA,EAAc,OAAA,GAAU,YAAY,QAAQ,CAAA;AAAA,EACxE;AACF","file":"password_reveal_controller.js","sourcesContent":["/**\n * Runs a controller's \"return to the initial state\" pass just before Turbo\n * caches the page.\n *\n * **`disconnect()` cannot do this job, for two independent reasons.** Turbo\n * queues the clone from this event rather than taking it here, and the body swap\n * that runs the controller's `disconnect()` is queued separately — so which of\n * the two lands first is not something a controller can rely on, and a rewind\n * written in `disconnect()` may reach only the DOM being thrown away. In the\n * other direction, `disconnect()` also fires on an in-page move (Stimulus tears\n * down and reconnects the same element), where rewinding would wipe a\n * legitimately in-progress interaction — a spinner mid-load would vanish. One\n * timing is unreliable, the other is too eager; `turbo:before-cache` is the only\n * point that is exactly \"the page is about to be frozen\".\n *\n * Scope is the subscription only: registering on `activate()`, unregistering on\n * `deactivate()`, and one shared document listener no matter how many instances\n * are live. *What* to return to its initial state — which `data-state`, which\n * `hidden`, which `aria-busy` — stays in the controller, because no two\n * consumers answer it the same way.\n *\n * **Rewind state, not appearance.** The pass writes attributes the controller\n * itself owns; the visual result of those attributes is the consumer's CSS, and\n * a library that reached for style or class names would be guessing at markup\n * it does not own.\n *\n * Both entry points are idempotent, so the lifecycle hooks can call them\n * unconditionally: a second `activate()` does not double-subscribe and does not\n * make the callback run twice, and `deactivate()` on an instance that never\n * subscribed is a no-op.\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 #beforeCache = new BeforeCacheReset(() => this.#rewind());\n *\n * connect()    { this.#beforeCache.activate(); }\n * disconnect() { this.#beforeCache.deactivate(); }\n * ```\n */\nexport class BeforeCacheReset {\n  /** Every subscribed instance, iterated by the one shared document listener. */\n  static readonly #subscribers = new Set<BeforeCacheReset>();\n\n  /** The shared listener; installed while at least one instance is subscribed. */\n  static readonly #onBeforeCache = (): void => {\n    for (const subscriber of BeforeCacheReset.#subscribers) subscriber.#rewind();\n  };\n\n  readonly #rewind: () => void;\n\n  /** @param rewind - the pass that returns this controller's state to its initial form. */\n  constructor(rewind: () => void) {\n    this.#rewind = rewind;\n  }\n\n  /** Subscribes to `turbo:before-cache`; call from `connect()`. Idempotent. */\n  activate(): void {\n    const first = BeforeCacheReset.#subscribers.size === 0;\n    BeforeCacheReset.#subscribers.add(this);\n    if (first) {\n      document.addEventListener(\"turbo:before-cache\", BeforeCacheReset.#onBeforeCache);\n    }\n  }\n\n  /** Unsubscribes; call from `disconnect()`. Safe when never subscribed. */\n  deactivate(): void {\n    BeforeCacheReset.#subscribers.delete(this);\n    if (BeforeCacheReset.#subscribers.size > 0) return;\n    document.removeEventListener(\"turbo:before-cache\", BeforeCacheReset.#onBeforeCache);\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 { BeforeCacheReset } from \"../utils/before_cache_reset\";\nimport { SafeTimeout } from \"../utils/safe_timeout\";\n\n/** The longest delay `setTimeout` can hold; past it a delay folds to zero. */\nconst MAX_DELAY = 2 ** 31 - 1;\n\n/**\n * Headless password show/hide (unmask) toggle behavior.\n *\n * Markup contract (identifier: `stimeo--password-reveal`):\n *   <div data-controller=\"stimeo--password-reveal\">\n *     <input type=\"password\" aria-label=\"Password\"\n *            data-stimeo--password-reveal-target=\"input\">\n *     <button type=\"button\" aria-pressed=\"false\" aria-label=\"Show password\"\n *             data-stimeo--password-reveal-target=\"toggle\"\n *             data-action=\"stimeo--password-reveal#toggle\"></button>\n *   </div>\n *\n * No dedicated APG pattern; this follows the toggle **Button** practice. The\n * accessible name stays state-independent (\"Show password\") while the pressed\n * state is conveyed by `aria-pressed`.\n *\n * `toggle` dispatches `{ visible: boolean }`.\n *\n * @remarks\n * Behavior only — icon rendering is the consumer's, keyed off `aria-pressed` /\n * `data-state` (`hidden` / `visible`). Flipping `input.type` can drop focus and\n * the caret, so when (and only when) the input was the focused element its focus\n * and selection are restored afterward; when the toggle button holds focus\n * (keyboard use) focus is left on the button.\n *\n * The hooks are derived from the input's `type`, so they are re-derived whenever\n * a target enters or leaves — a field or button swapped in by a Turbo Stream\n * describes the state it actually has rather than the one the server rendered.\n *\n * An optional `autoHide` re-masks after a delay. The delay is armed on connect as\n * well, so a controller that reconnects onto an already revealed field still owes\n * the re-mask it promised; a value that is not a delay `setTimeout` can hold falls\n * back rather than inverting into an immediate one. Revealing is never carried\n * into a Turbo snapshot: the field is masked again before the page is cached, so\n * returning to it does not put a credential back on screen.\n */\nexport class PasswordRevealController extends Controller<HTMLElement> {\n  static override targets = [\"input\", \"toggle\"];\n  static override values = {\n    autoHide: { type: Number, default: 0 },\n  };\n  static actions = [\"toggle\"] as const;\n  static events = [\"toggle\"] as const;\n\n  declare readonly inputTarget: HTMLInputElement;\n  declare readonly toggleTarget: HTMLElement;\n  declare readonly hasInputTarget: boolean;\n  declare readonly hasToggleTarget: boolean;\n\n  declare autoHideValue: number;\n\n  /** Auto re-mask timer; torn down on disconnect. */\n  #timers = new SafeTimeout();\n\n  /**\n   * Whether this controller is between `connect()` and `disconnect()`.\n   *\n   * Target callbacks outlive the controller: Stimulus stops the target observer\n   * after `disconnect()`, so a field leaving after teardown still reaches\n   * {@link PasswordRevealController.inputTargetDisconnected}. Arming from there\n   * would put a timer back that nothing will clear. The element staying in the\n   * document does not answer this — unloading the controller leaves it there.\n   */\n  #connected = false;\n\n  /** Masks the field before Turbo copies the page into its snapshot. */\n  readonly #beforeCache = new BeforeCacheReset(() => this.#rewindToMasked());\n\n  override connect(): void {\n    this.#connected = true;\n    const visible = this.#isVisible;\n    this.#reflect(visible);\n    this.#beforeCache.activate();\n    // Reconnecting onto an already revealed field inherits the promise the\n    // declaration made: without re-arming, the re-mask would never arrive.\n    this.#arm(visible);\n  }\n\n  override disconnect(): void {\n    this.#connected = false;\n    this.#timers.clearAll();\n    this.#beforeCache.deactivate();\n  }\n\n  /** Re-derives the hooks and the re-mask for a field swapped in after connect. */\n  inputTargetConnected(): void {\n    const visible = this.#connected && this.#isVisible;\n    this.#reflect(visible);\n    this.#arm(visible);\n  }\n\n  /**\n   * Re-derives from whatever field is left rather than assuming none is. A swap\n   * delivers this callback next to the arrival in either order, so a revealed\n   * replacement that answered \"masked\" here would be described as hidden while\n   * showing the password, and would carry no re-mask.\n   *\n   * Teardown is the one case with nothing to derive: target callbacks run after\n   * `disconnect()`, so the field is still revealed and re-arming from it would\n   * outlive the controller. A detached root is the signal to stand down.\n   */\n  inputTargetDisconnected(): void {\n    const visible = this.#connected && this.element.isConnected && this.#isVisible;\n    this.#reflect(visible);\n    this.#arm(visible);\n  }\n\n  /** Re-derives the pressed state for a button swapped in after connect. */\n  toggleTargetConnected(): void {\n    this.#reflect(this.#isVisible);\n  }\n\n  /** Toggles the input between masked and revealed. Bound via `data-action`. */\n  toggle(): void {\n    this.#setVisible(!this.#isVisible);\n  }\n\n  /** Whether the input is currently revealed (`type=\"text\"`). */\n  get #isVisible(): boolean {\n    return this.hasInputTarget && this.inputTarget.type === \"text\";\n  }\n\n  /** Switches the masked/revealed state, preserving focus and caret. */\n  #setVisible(visible: boolean): void {\n    if (!this.hasInputTarget) return;\n    const input = this.inputTarget;\n\n    // Only the input's *own* focus is restored across the type change; if the\n    // toggle button (keyboard) holds focus, it is left untouched.\n    const restoreInputFocus = document.activeElement === input;\n    const selectionStart = input.selectionStart;\n    const selectionEnd = input.selectionEnd;\n\n    input.type = visible ? \"text\" : \"password\";\n\n    if (restoreInputFocus) {\n      input.focus();\n      // `selectionStart` / `selectionEnd` are `number | null` (null for input\n      // types that don't expose a selection); only restore when both are present.\n      if (selectionStart !== null && selectionEnd !== null) {\n        try {\n          input.setSelectionRange(selectionStart, selectionEnd);\n        } catch {\n          // Some input types reject selection access; focus alone is enough.\n        }\n      }\n    }\n\n    this.#reflect(visible);\n    this.dispatch(\"toggle\", { detail: { visible } });\n    this.#arm(visible);\n  }\n\n  /** Schedules the auto re-mask for a revealed field, replacing any pending one. */\n  #arm(visible: boolean): void {\n    this.#timers.clearAll();\n    const delay = this.#autoHideDelay;\n    if (visible && delay > 0) {\n      this.#timers.set(() => this.#setVisible(false), delay);\n    }\n  }\n\n  /**\n   * The auto re-mask delay, held to what `setTimeout` can carry. Past that limit\n   * a delay folds to zero, turning \"keep it showing\" into \"hide it at once\" —\n   * the opposite of what the declaration asked for. A value that is no delay at\n   * all stays out of the positive range {@link PasswordRevealController.#arm}\n   * requires, so it schedules nothing.\n   */\n  get #autoHideDelay(): number {\n    return Math.min(this.autoHideValue, MAX_DELAY);\n  }\n\n  /**\n   * Returns the field to masked before Turbo copies the page. Silent and\n   * focus-free: the page is about to be frozen, so there is no one to tell and\n   * nowhere for focus to go.\n   */\n  #rewindToMasked(): void {\n    this.#timers.clearAll();\n    if (!this.hasInputTarget) return;\n    this.inputTarget.type = \"password\";\n    this.#reflect(false);\n  }\n\n  /** Reflects the visible state onto `aria-pressed` and `data-state`. */\n  #reflect(visible: boolean): void {\n    if (this.hasToggleTarget) {\n      this.toggleTarget.setAttribute(\"aria-pressed\", visible ? \"true\" : \"false\");\n    }\n    this.element.setAttribute(\"data-state\", visible ? \"visible\" : \"hidden\");\n  }\n}\n"]}

package/dist/controllers/password_strength_controller.d.ts

@@ -1,17 +1,32 @@
 import { Controller } from '@hotwired/stimulus';
 
+/**
+ * Event shape {@link PasswordStrengthController.setScore} accepts: an action param
+ * `score` or a `detail.score`. Both are typed `number | string` because, while
+ * Stimulus coerces numeric action params to numbers, a `CustomEvent` (or a
+ * non-numeric-looking param) may carry a string.
+ */
+type SetScoreEvent = Event & {
+    params?: {
+        score?: number | string;
+    };
+    detail?: {
+        score?: number | string;
+    };
+};
 /**
  * Headless password-strength behavior: scores the field with a lightweight
- * zero-dependency heuristic and drives a meter plus an `aria-live` label. No
+ * zero-dependency heuristic and drives a meter plus a visible level readout. No
  * dedicated APG pattern; the meter display follows {@link MeterController}.
  *
  * Markup contract (identifier: `stimeo--password-strength`):
- *   <div data-controller="stimeo--password-strength">
+ *   <div data-controller="stimeo--password-strength"
+ *        data-stimeo--password-strength-announce-text-value="Password strength: {level}">
  *     <input type="password" data-stimeo--password-strength-target="input"
  *            data-action="input->stimeo--password-strength#evaluate" aria-describedby="pw">
  *     <div data-stimeo--password-strength-target="meter" role="meter"
- *          aria-valuemin="0" aria-valuemax="4"></div>
- *     <span id="pw" data-stimeo--password-strength-target="label" aria-live="polite"></span>
+ *          aria-label="Password strength" aria-valuemin="0" aria-valuemax="4"></div>
+ *     <span id="pw" data-stimeo--password-strength-target="label"></span>
  *   </div>
  *
  * On each input the controller scores the password (length milestones + character
@@ -20,22 +35,30 @@ import { Controller } from '@hotwired/stimulus';
  * `--stimeo--password-strength`, and (when `minScore` is set) `data-below-min`,
  * and writes the level label into the label target.
  *
- * `change` dispatches `{ score, level, max, meetsMin }`.
+ * `change` and `reconcile` dispatch `{ score, level, max, meetsMin }`.
  *
  * @remarks
  * Behavior only — the meter/bar look is the consumer's, keyed off the data hooks.
  * `data-strength` is one of the fixed {@link STRENGTH_BANDS} (not the localizable
  * `levels` text), so consumers can style by it regardless of locale; the visible
- * label receives the matching `levels` entry. Non-text state (meter ARIA,
- * `data-strength`/`data-below-min`, the custom property, and the `change` event)
- * updates **immediately** on every keystroke so styling and consumers stay
- * responsive, while the label — in an `aria-live="polite"` region — is written on
- * a short debounce so a screen reader is not flooded mid-typing. The score is a
- * pure function of the input value (no module-scope state), so `connect()`
- * re-evaluates idempotently after a Turbo cache restore; the debounce timer is
- * owned by {@link SafeTimeout} and torn down on `disconnect()` (Turbo included).
- * The estimator is intentionally not a dictionary/zxcvbn-grade one (kept
- * zero-dep); swap a stronger one in on the consumer side if needed.
+ * label receives the matching `levels` entry. Every visible and non-text output
+ * updates on the keystroke that caused it, so the readout never trails the meter.
+ *
+ * Assistive notification is opt-in and i18n-neutral: `announceText` accepts
+ * `{level}`, `{score}`, `{max}` and `{band}`, and one settled message is handed to
+ * the page's shared `stimeo--announcer` after a short debounce. Only a level the
+ * reader has not already heard is sent, so typing inside one level stays quiet.
+ * The label target is plain visible output and is not itself a live region.
+ *
+ * The score is a pure function of the field value (no module-scope state), so
+ * `connect()` re-evaluates idempotently; the initial reflection never dispatches
+ * or announces. Runtime Value and target changes repaint on a microtask and
+ * dispatch `reconcile` only when the public derived state actually moves. Because
+ * the field value is not part of a Turbo snapshot, everything derived from it is
+ * rewound on `turbo:before-cache` — silently, since `connect()` derives it again
+ * after a restore. The estimator is intentionally not a dictionary/zxcvbn-grade
+ * one (kept zero-dep); a consumer that needs a stronger one computes the score
+ * itself and hands it over through {@link setScore}.
  */
 declare class PasswordStrengthController extends Controller<HTMLElement> {
     #private;
@@ -49,9 +72,13 @@ declare class PasswordStrengthController extends Controller<HTMLElement> {
             type: StringConstructor;
             default: string;
         };
+        announceText: {
+            type: StringConstructor;
+            default: string;
+        };
     };
-    static actions: readonly ["evaluate"];
-    static events: readonly ["change"];
+    static actions: readonly ["evaluate", "setScore"];
+    static events: readonly ["change", "reconcile"];
     readonly inputTarget: HTMLInputElement;
     readonly meterTarget: HTMLElement;
     readonly labelTarget: HTMLElement;
@@ -60,10 +87,37 @@ declare class PasswordStrengthController extends Controller<HTMLElement> {
     readonly hasLabelTarget: boolean;
     minScoreValue: number;
     levelsValue: string;
+    announceTextValue: string;
+    /** Reflects the current DOM state and opens the reconciliation window. */
     connect(): void;
+    /** Releases the reconciliation window, the cache subscription and the debounce. */
     disconnect(): void;
     /** Re-evaluates strength from the input. Bound via `data-action` (`input`). */
     evaluate(): void;
+    /**
+     * Adopts a score computed outside the built-in heuristic, clamped into the
+     * declared scale. An unreadable value leaves the current score standing, and
+     * the next `evaluate` hands scoring back to the heuristic.
+     */
+    setScore(event: SetScoreEvent): void;
+    /** Re-reads the scale when application code or a Turbo morph changes `levels`. */
+    levelsValueChanged(): void;
+    /** Repaints when application code or a Turbo morph changes `minScore`. */
+    minScoreValueChanged(): void;
+    /** Repaints when application code or a Turbo morph changes `announceText`. */
+    announceTextValueChanged(): void;
+    /** Scores the field added or replaced at runtime. */
+    inputTargetConnected(): void;
+    /** Falls back to the pristine state after the scored field is removed. */
+    inputTargetDisconnected(): void;
+    /** Syncs a meter added or replaced at runtime, which carries no value yet. */
+    meterTargetConnected(): void;
+    /** Repaints the remaining output after a meter is removed. */
+    meterTargetDisconnected(): void;
+    /** Fills a readout added or replaced at runtime. */
+    labelTargetConnected(): void;
+    /** Repaints the remaining output after a readout is removed. */
+    labelTargetDisconnected(): void;
 }
 
 export { PasswordStrengthController };