stimeo-ui 0.3.0 → 0.5.0

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

data/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 } });
     };

data/dist/controllers/focus_controller.js

@@ -2,6 +2,35 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/focus_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/escape_layer.ts
 var EscapeLayer = class _EscapeLayer {
   static #registries = /* @__PURE__ */ new WeakMap();
@@ -135,7 +164,7 @@ var FocusTrap = class {
     }
     if (this.#flag(this.#options.isolate, true)) this.#isolateBackground();
     document.addEventListener("keydown", this.#onKeydown);
-    document.addEventListener("turbo:before-cache", this.#onBeforeCache);
+    this.#beforeCache.activate();
     const onEscape = this.#options.onEscape;
     if (onEscape) this.#escapeLayer.activate(document, { onDismiss: () => onEscape() });
     if (this.#flag(this.#options.autoFocus, true)) this.#focusInitial();
@@ -152,7 +181,7 @@ var FocusTrap = class {
     this.#activeState = false;
     this.#escapeLayer.deactivate();
     document.removeEventListener("keydown", this.#onKeydown);
-    document.removeEventListener("turbo:before-cache", this.#onBeforeCache);
+    this.#beforeCache.deactivate();
     if (this.#scrollLocked) {
       document.body.style.overflow = this.#previousBodyOverflow;
       this.#scrollLocked = false;
@@ -176,9 +205,7 @@ var FocusTrap = class {
    * untouched (restore-open designs reopen against a clean baseline), and focus
    * is left alone mid-navigation. The listener lives only while active.
    */
-  #onBeforeCache = () => {
-    this.deactivate({ restoreFocus: false });
-  };
+  #beforeCache = new BeforeCacheReset(() => this.deactivate({ restoreFocus: false }));
   /**
    * Handles `Tab` (focus trap) while active. `Escape` dismissal is owned by the
    * shared {@link EscapeLayer} resolver, so Tab trapping stays independent of

data/dist/controllers/form_validation_controller.js

@@ -2,6 +2,13 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/form_validation_controller.ts
 
+// src/utils/default_attribute.ts
+function setDefaultAttribute(element, name, value) {
+  if (element.hasAttribute(name)) return false;
+  element.setAttribute(name, value);
+  return true;
+}
+
 // src/utils/focus_trap.ts
 var FOCUSABLE = 'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
 
@@ -79,8 +86,7 @@ var FormValidationController = class _FormValidationController extends Controlle
   };
   /** Suppresses native bubbles and binds the submit / blur / input listeners. */
   connect() {
-    if (!this.element.hasAttribute("novalidate")) {
-      this.element.setAttribute("novalidate", "");
+    if (setDefaultAttribute(this.element, "novalidate", "")) {
       this.element.setAttribute(_FormValidationController.#NOVALIDATE_MARKER, "");
     }
     document.addEventListener("submit", this.#onSubmit, true);