stimeo-ui 0.9.0 → 0.10.0

data/dist/controllers/password_strength_controller.js

@@ -2,6 +2,92 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/password_strength_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/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/coerce.ts
+function toFiniteNumber(raw) {
+  if (raw === null || raw === void 0 || raw === "") return null;
+  const value = typeof raw === "number" ? raw : Number(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/safe_timeout.ts
 var TimerRegistry = class {
   /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
@@ -75,6 +161,7 @@ var DEFAULT_LEVELS = ["weak", "fair", "good", "strong"];
 var LENGTH_MILESTONES = [8, 12, 16];
 var MAX_POINTS = LENGTH_MILESTONES.length + (CLASS_PATTERNS.length - 1);
 var STRENGTH_BANDS = ["weak", "fair", "good", "strong"];
+var MIN_LEVELS = 2;
 var PasswordStrengthController = class _PasswordStrengthController extends Controller {
   static targets = ["input", "meter", "label"];
   static values = {
@@ -82,50 +169,143 @@ var PasswordStrengthController = class _PasswordStrengthController extends Contr
     // A JSON list read through `parseStringList` rather than Stimulus's `Array`
     // type: that reader throws out of the value observer before any callback
     // runs, so one malformed attribute would stop the meter connecting.
-    levels: { type: String, default: "" }
+    levels: { type: String, default: "" },
+    announceText: { type: String, default: "" }
   };
-  static actions = ["evaluate"];
-  static events = ["change"];
-  /** Delay (ms) before the polite live-region label is written, to throttle SR flooding. */
+  static actions = ["evaluate", "setScore"];
+  static events = ["change", "reconcile"];
+  /** Delay (ms) before one settled level is sent to the shared announcer. */
   static #announceDelay = 200;
   #timers = new SafeTimeout();
+  #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
+  #repaint = new MicrotaskCoalescer(() => this.#reconcile());
+  #levels = [...DEFAULT_LEVELS];
   #announceId = null;
+  #announcedLevel = null;
+  #externalScore = null;
+  #lastDetail = null;
+  /** Reflects the current DOM state and opens the reconciliation window. */
   connect() {
-    this.#update({ announce: false });
+    this.#repaint.activate();
+    this.#beforeCache.activate();
+    this.#lastDetail = this.#detail(this.#render());
   }
+  /** Releases the reconciliation window, the cache subscription and the debounce. */
   disconnect() {
-    this.#timers.clearAll();
-    this.#announceId = null;
+    this.#repaint.cancel();
+    this.#beforeCache.deactivate();
+    this.#cancelAnnouncement();
+    this.#announcedLevel = null;
+    this.#externalScore = null;
+    this.#lastDetail = null;
   }
   /** Re-evaluates strength from the input. Bound via `data-action` (`input`). */
   evaluate() {
-    this.#update();
+    this.#externalScore = null;
+    this.#commit();
   }
   /**
-   * Recomputes the strength. The meter ARIA, data hooks, the custom property and
-   * the `change` event apply immediately; the live-region label text is debounced
-   * unless `announce` is `false` (the initial render).
+   * 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.
    */
-  #update(options = {}) {
-    const password = this.hasInputTarget ? this.inputTarget.value : "";
-    const labels = parseStringList(this.levelsValue, DEFAULT_LEVELS);
-    const max = labels.length;
-    const score = this.#score(password, max);
-    const label = score > 0 ? labels[score - 1] ?? "" : "";
+  setScore(event) {
+    const next = toFiniteNumber(event.params?.score ?? event.detail?.score);
+    if (next === null) return;
+    this.#externalScore = next;
+    this.#commit();
+  }
+  /** Re-reads the scale when application code or a Turbo morph changes `levels`. */
+  levelsValueChanged() {
+    this.#levels = this.#readLevels();
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code or a Turbo morph changes `minScore`. */
+  minScoreValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code or a Turbo morph changes `announceText`. */
+  announceTextValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Scores the field added or replaced at runtime. */
+  inputTargetConnected() {
+    this.#repaint.schedule();
+  }
+  /** Falls back to the pristine state after the scored field is removed. */
+  inputTargetDisconnected() {
+    this.#repaint.schedule();
+  }
+  /** Syncs a meter added or replaced at runtime, which carries no value yet. */
+  meterTargetConnected() {
+    this.#repaint.schedule();
+  }
+  /** Repaints the remaining output after a meter is removed. */
+  meterTargetDisconnected() {
+    this.#repaint.schedule();
+  }
+  /** Fills a readout added or replaced at runtime. */
+  labelTargetConnected() {
+    this.#repaint.schedule();
+  }
+  /** Repaints the remaining output after a readout is removed. */
+  labelTargetDisconnected() {
+    this.#repaint.schedule();
+  }
+  /** Reflects one confirmed scoring pass and offers its level to the reader. */
+  #commit() {
+    const reading = this.#render();
+    this.#lastDetail = this.#detail(reading);
+    this.dispatch("change", { detail: this.#lastDetail });
+    this.#scheduleAnnouncement(reading);
+  }
+  /** Repaints one mutation batch and reports a changed controller-derived state. */
+  #reconcile() {
+    const previous = this.#lastDetail;
+    const owed = this.#announceId !== null;
+    this.#cancelAnnouncement();
+    const reading = this.#render();
+    const detail = this.#detail(reading);
+    this.#lastDetail = detail;
+    if (reading.score === 0) this.#announcedLevel = null;
+    if (owed) this.#scheduleAnnouncement(reading);
+    if (previous && this.#detailsDiffer(previous, detail)) {
+      this.dispatch("reconcile", { detail });
+    }
+  }
+  /**
+   * Synchronizes the meter ARIA, the root state hooks, the fill custom property
+   * and the visible level readout.
+   *
+   * @stimeoRenderRoot
+   */
+  #render() {
+    const max = this.#levels.length;
+    const score = this.#currentScore(max);
+    const level = this.#levels[score - 1] ?? "";
+    const meetsMin = score > 0 && score >= this.#minScore;
+    const band = this.#band(score, max);
     this.#reflectMeter(score, max);
-    this.#reflectRoot(score, max);
-    if (options.announce === false) {
-      this.#writeLabel(label);
-      return;
+    this.#reflectRoot(score, max, band, meetsMin);
+    this.#writeLabel(level);
+    return { score, level, max, meetsMin, band };
+  }
+  /**
+   * The declared minimum, or the Value's default (`0`, an inert gate) when the
+   * declaration cannot be read as a number. Every comparison against an unread
+   * number answers false, which would fail even the strongest password instead
+   * of leaving the gate off, so the unreadable declaration is confined to its
+   * own Value the way an unreadable scale is.
+   */
+  get #minScore() {
+    return Number.isFinite(this.minScoreValue) ? this.minScoreValue : 0;
+  }
+  /** The externally supplied score when one stands, else the heuristic's. */
+  #currentScore(max) {
+    if (this.#externalScore !== null) {
+      return Math.min(max, Math.max(0, Math.round(this.#externalScore)));
     }
-    this.dispatch("change", {
-      detail: { score, level: label, max, meetsMin: score > 0 && score >= this.minScoreValue }
-    });
-    if (this.#announceId !== null) this.#timers.clear(this.#announceId);
-    this.#announceId = this.#timers.set(() => {
-      this.#writeLabel(label);
-      this.#announceId = null;
-    }, _PasswordStrengthController.#announceDelay);
+    return this.#score(this.hasInputTarget ? this.inputTarget.value : "", max);
   }
   /** Syncs the meter target's ARIA value attributes (`0..levels.length`). */
   #reflectMeter(score, max) {
@@ -139,25 +319,27 @@ var PasswordStrengthController = class _PasswordStrengthController extends Contr
    * empty), the `data-below-min` hook when the score is under `minScore`, and the
    * `0–1` fill the consumer's CSS turns into the bar width.
    */
-  #reflectRoot(score, max) {
-    const band = this.#band(score, max);
+  #reflectRoot(score, max, band, meetsMin) {
     this.#toggle("data-strength", band, band.length > 0);
-    this.#toggle("data-below-min", "true", score > 0 && score < this.minScoreValue);
-    const ratio = max > 0 ? score / max : 0;
-    this.element.style.setProperty("--stimeo--password-strength", String(ratio));
+    this.#toggle("data-below-min", "true", score > 0 && !meetsMin);
+    this.element.style.setProperty("--stimeo--password-strength", String(score / max));
   }
-  #writeLabel(label) {
-    if (this.hasLabelTarget) this.labelTarget.textContent = label;
+  /** Writes the visible readout only when its text actually changed. */
+  #writeLabel(text) {
+    if (!this.hasLabelTarget || this.labelTarget.textContent === text) return;
+    this.labelTarget.textContent = text;
   }
   /**
    * Locale-independent styling band (one of {@link STRENGTH_BANDS}) for `score`
-   * out of `max`. Empty input → `""`. Quantizes the `score/max` ratio into the
-   * four fixed bands, so a non-default level count still maps onto a stable hook.
+   * out of `max`. Empty input → `""`. Maps the position within the declared scale
+   * onto the position within the fixed bands, so both ends stay anchored on any
+   * level count: the weakest score is always `weak` and the strongest `strong`,
+   * and only the middle collapses when the scales differ in size.
    */
   #band(score, max) {
-    if (score <= 0 || max <= 0) return "";
-    const index = Math.ceil(score / max * STRENGTH_BANDS.length) - 1;
-    return STRENGTH_BANDS[Math.min(STRENGTH_BANDS.length - 1, Math.max(0, index))] ?? "";
+    if (score <= 0) return "";
+    const index = Math.round((score - 1) / (max - 1) * (STRENGTH_BANDS.length - 1));
+    return STRENGTH_BANDS[index] ?? STRENGTH_BANDS[0];
   }
   /** Sets `name` to `value` when `on`, else removes it (value/presence data hook). */
   #toggle(name, value, on) {
@@ -167,6 +349,11 @@ var PasswordStrengthController = class _PasswordStrengthController extends Contr
       this.element.removeAttribute(name);
     }
   }
+  /** The declared level labels, or the defaults when the scale cannot order. */
+  #readLevels() {
+    const declared = parseStringList(this.levelsValue, DEFAULT_LEVELS);
+    return declared.length >= MIN_LEVELS ? declared : [...DEFAULT_LEVELS];
+  }
   /**
    * Lightweight zero-dependency strength heuristic returning an integer in
    * `[0, max]` (`max` = number of levels). Empty input is `0` (no level); any
@@ -176,7 +363,7 @@ var PasswordStrengthController = class _PasswordStrengthController extends Contr
    * alone cannot mask trivial repetition.
    */
   #score(password, max) {
-    if (password.length === 0 || max === 0) return 0;
+    if (password.length === 0) return 0;
     let points = 0;
     for (const milestone of LENGTH_MILESTONES) {
       if (password.length >= milestone) points += 1;
@@ -186,6 +373,64 @@ var PasswordStrengthController = class _PasswordStrengthController extends Contr
     const bucketed = Math.round(points / MAX_POINTS * max);
     return Math.min(max, Math.max(1, bucketed));
   }
+  /** Debounces one i18n-neutral message for a level transition into the announcer. */
+  #scheduleAnnouncement(reading) {
+    this.#cancelAnnouncement();
+    if (reading.score === 0) {
+      this.#announcedLevel = null;
+      return;
+    }
+    if (reading.level === this.#announcedLevel) return;
+    const message = fillTemplate(this.announceTextValue, {
+      level: reading.level,
+      score: reading.score,
+      max: reading.max,
+      band: reading.band
+    });
+    if (message.trim().length === 0) return;
+    this.#announceId = this.#timers.set(() => {
+      this.#announcedLevel = reading.level;
+      announce(message);
+      this.#announceId = null;
+    }, _PasswordStrengthController.#announceDelay);
+  }
+  /** Cancels the one outstanding message without touching visible output. */
+  #cancelAnnouncement() {
+    if (this.#announceId !== null) this.#timers.clear(this.#announceId);
+    this.#announceId = null;
+  }
+  /**
+   * Returns every output derived from the field value to its pristine form.
+   *
+   * The value itself is not carried in a Turbo snapshot, so a band, a fill or a
+   * readout left behind would describe a password the restored page no longer
+   * holds. The pass is silent: `connect()` derives the state again from whatever
+   * the restored field contains.
+   */
+  #rewindForCache() {
+    this.#cancelAnnouncement();
+    this.#announcedLevel = null;
+    this.#externalScore = null;
+    this.#lastDetail = null;
+    this.#reflectMeter(0, this.#levels.length);
+    this.#toggle("data-strength", "", false);
+    this.#toggle("data-below-min", "true", false);
+    this.element.style.removeProperty("--stimeo--password-strength");
+    this.#writeLabel("");
+  }
+  /** Selects the public event state from the richer internal reading. */
+  #detail(reading) {
+    return {
+      score: reading.score,
+      level: reading.level,
+      max: reading.max,
+      meetsMin: reading.meetsMin
+    };
+  }
+  /** Compares exactly the state carried by `change` and `reconcile`. */
+  #detailsDiffer(left, right) {
+    return left.score !== right.score || left.level !== right.level || left.max !== right.max || left.meetsMin !== right.meetsMin;
+  }
 };
 
 export { PasswordStrengthController };

data/dist/controllers/resizable_controller.js

@@ -251,7 +251,7 @@ var ResizableController = class extends Controller {
       this.#dispatchChange();
     }
   }
-  /** Double-click or Enter to collapse the primary pane, or put it back. */
+  /** Collapses the primary pane to its minimum, or returns it to the last position. */
   toggle() {
     const { min, max } = this.#range;
     if (this.#position > min) {

data/dist/controllers/scroll_restore_controller.js

@@ -1,6 +1,17 @@
 import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/scroll_restore_controller.ts
+function parseStored(raw) {
+  if (raw === null) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function storedOffset(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
 var ScrollRestoreController = class extends Controller {
   static values = {
     key: { type: String, default: "" },
@@ -13,6 +24,26 @@ var ScrollRestoreController = class extends Controller {
   /** Last offset captured while the element was live; persisted as-is on teardown. */
   #lastTop = 0;
   #lastLeft = 0;
+  /**
+   * The offsets this controller's own restore produced, awaiting the `scroll`
+   * the engine fires for them. A restore the layout cannot reach yet lands short,
+   * so treating that echo as the reader's position would cut the saved offset
+   * down to whatever the unfinished layout allowed.
+   */
+  #echoTop = null;
+  #echoLeft = null;
+  /** Offsets stored for an axis that is not tracked, carried through saves. */
+  #carried = {};
+  /**
+   * Whether each axis holds an offset worth saving — one this namespace restored
+   * or the reader moved. A save writes only the axes that are marked, so an
+   * offset taken under a different key or axis is never re-published as if the
+   * reader had left it there.
+   */
+  #capturedTop = false;
+  #capturedLeft = false;
+  /** Whether the controller is connected; Value callbacks outside that window do not resync. */
+  #connected = false;
   #onScroll = () => {
     this.#capture();
     if (this.#rafId !== null) return;
@@ -22,58 +53,127 @@ var ScrollRestoreController = class extends Controller {
     });
   };
   connect() {
+    this.#connected = true;
     this.#storageKey = this.#resolveKey();
-    if (!this.#storageKey) return;
-    this.#restore();
     this.element.addEventListener("scroll", this.#onScroll, { passive: true });
+    if (this.#storageKey) this.#restore();
   }
   disconnect() {
-    if (!this.#storageKey) return;
+    this.#connected = false;
     this.element.removeEventListener("scroll", this.#onScroll);
+    this.#cancelFrame();
+    this.#persist();
+  }
+  /** Re-derives the namespace when application code or a Turbo morph moves `key`. */
+  keyValueChanged() {
+    this.#resync();
+  }
+  /** Re-derives the tracked axes when application code or a Turbo morph moves `axis`. */
+  axisValueChanged() {
+    this.#resync();
+  }
+  /** Rebuilds the persistence state around the Values as they now read. */
+  #resync() {
+    if (!this.#connected) return;
+    this.#cancelFrame();
+    this.#storageKey = this.#resolveKey();
+    this.#echoTop = null;
+    this.#echoLeft = null;
+    this.#carried = {};
+    this.#capturedTop = false;
+    this.#capturedLeft = false;
+    if (this.#storageKey) this.#restore();
+  }
+  /** Drops the pending coalesced save, if one is queued. */
+  #cancelFrame() {
     if (this.#rafId !== null) {
       cancelAnimationFrame(this.#rafId);
       this.#rafId = null;
     }
-    this.#persist();
   }
-  /** Records the live scroll offset for the configured axis. */
+  /**
+   * Records the live scroll offset for the configured axis.
+   *
+   * An axis holds its echo until that axis actually moves. A scroll event names
+   * no axis, so consuming both on the first one to arrive would leave the other
+   * unguarded: on `both`, moving one axis would take the clamped reading of the
+   * untouched axis as the reader's own position and save it, cutting the stored
+   * offset down to whatever the layout could reach at restore time.
+   */
   #capture() {
-    if (this.#tracksVertical) this.#lastTop = this.element.scrollTop;
-    if (this.#tracksHorizontal) this.#lastLeft = this.element.scrollLeft;
+    if (this.#tracksVertical) {
+      const top = this.element.scrollTop;
+      if (top !== this.#echoTop) {
+        this.#echoTop = null;
+        this.#lastTop = top;
+        this.#capturedTop = true;
+      }
+    }
+    if (this.#tracksHorizontal) {
+      const left = this.element.scrollLeft;
+      if (left !== this.#echoLeft) {
+        this.#echoLeft = null;
+        this.#lastLeft = left;
+        this.#capturedLeft = true;
+      }
+    }
   }
-  /** Persists the last captured scroll offset for the configured axis. */
+  /**
+   * Writes the marked axes, carrying through any offset held for an untracked one.
+   * Without a key, or with neither axis marked, it writes nothing.
+   */
   #persist() {
-    const data = {};
-    if (this.#tracksVertical) data.top = this.#lastTop;
-    if (this.#tracksHorizontal) data.left = this.#lastLeft;
+    if (!this.#storageKey || !(this.#capturedTop || this.#capturedLeft)) return;
+    const data = { ...this.#carried };
+    if (this.#tracksVertical && this.#capturedTop) data.top = this.#lastTop;
+    if (this.#tracksHorizontal && this.#capturedLeft) data.left = this.#lastLeft;
     try {
-      sessionStorage.setItem(this.#storageKey, JSON.stringify(data));
+      window.sessionStorage.setItem(this.#storageKey, JSON.stringify(data));
     } catch {
     }
   }
   /** Applies the persisted scroll offset, if any, without moving focus. */
   #restore() {
-    let raw = null;
-    try {
-      raw = sessionStorage.getItem(this.#storageKey);
-    } catch {
-      return;
-    }
-    if (raw === null) return;
-    let data;
+    let raw;
     try {
-      data = JSON.parse(raw);
+      raw = window.sessionStorage.getItem(this.#storageKey);
     } catch {
       return;
     }
-    if (this.#tracksVertical && typeof data.top === "number") {
-      this.element.scrollTop = data.top;
-      this.#lastTop = data.top;
+    const data = parseStored(raw);
+    if (data === null) return;
+    this.#echoTop = null;
+    this.#echoLeft = null;
+    const top = storedOffset(data.top);
+    const left = storedOffset(data.left);
+    const options = { behavior: "instant" };
+    let requested = false;
+    if (this.#tracksVertical) {
+      if (top !== null) {
+        options.top = top;
+        this.#lastTop = top;
+        this.#capturedTop = true;
+        requested = true;
+      }
+    } else if (data.top !== void 0) {
+      this.#carried.top = data.top;
     }
-    if (this.#tracksHorizontal && typeof data.left === "number") {
-      this.element.scrollLeft = data.left;
-      this.#lastLeft = data.left;
+    if (this.#tracksHorizontal) {
+      if (left !== null) {
+        options.left = left;
+        this.#lastLeft = left;
+        this.#capturedLeft = true;
+        requested = true;
+      }
+    } else if (data.left !== void 0) {
+      this.#carried.left = data.left;
     }
+    if (!requested) return;
+    const beforeTop = this.element.scrollTop;
+    const beforeLeft = this.element.scrollLeft;
+    this.element.scrollTo(options);
+    if (this.element.scrollTop !== beforeTop) this.#echoTop = this.element.scrollTop;
+    if (this.element.scrollLeft !== beforeLeft) this.#echoLeft = this.element.scrollLeft;
   }
   /** The `sessionStorage` key: explicit `key`, else the element `id`, else none. */
   #resolveKey() {