stimeo-ui 0.2.1 → 0.4.0

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

@@ -216,7 +216,7 @@ var FormValidationController = class _FormValidationController extends Controlle
   }
   /**
    * Where focus should land for an invalid control. A visible control is focused
-   * directly (status quo for native fields and radios). A validatable mirror
+   * directly — the case for native fields and radios. A validatable mirror
    * (the `hidden` attribute) cannot receive focus, so focus is delegated to the
    * visible widget: the owning field's `control` target when it is itself
    * focusable, else its first focusable descendant (e.g. a roving-tabindex

data/dist/controllers/frame_loading_controller.js

@@ -2,6 +2,145 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/frame_loading_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/detach_gate.ts
+var DetachGate = class _DetachGate {
+  /** Set while a probe is queued, waiting for a reconnect to cancel it. */
+  #pending = false;
+  /**
+   * True when the disconnect is definitely a real detach — the element left
+   * the document, or `data-controller` no longer lists the identifier. False
+   * means ambiguous (in-page move or observed-root exit), NOT "alive".
+   */
+  static isDetached(host) {
+    if (!host.element.isConnected) return true;
+    const tokens = (host.element.getAttribute("data-controller") ?? "").split(/\s+/);
+    return !tokens.includes(host.identifier);
+  }
+  /**
+   * Call from `disconnect()`: runs `teardown` synchronously on a definite
+   * detach (fast path), otherwise defers it one microtask — a reconnect
+   * ({@link cancel} from `connect()`) keeps the state, no reconnect runs it.
+   * One microtask is the whole probe window: Stimulus reconnects a moved
+   * element within the same mutation batch, before the checkpoint drains.
+   */
+  disconnected(host, teardown) {
+    if (_DetachGate.isDetached(host)) {
+      this.#pending = false;
+      teardown();
+      return;
+    }
+    this.#pending = true;
+    queueMicrotask(() => {
+      if (!this.#pending) return;
+      this.#pending = false;
+      teardown();
+    });
+  }
+  /**
+   * Disarms a pending probe. Call from `connect()` (the reconnect that proves
+   * an in-page move) and from the head of any teardown path not routed through
+   * {@link disconnected} (disabled-toggle, Escape), so an orphaned probe can
+   * never run the teardown a second time.
+   */
+  cancel() {
+    this.#pending = false;
+  }
+};
+
+// src/utils/min_duration_floor.ts
+var MinDurationFloor = class {
+  #timers;
+  /** Pending finish timer id, or `null` when nothing is held back. */
+  #timerId = null;
+  /** Epoch ms the floor is measured from. */
+  #since = 0;
+  /** @param timers - the controller's registry; the floor schedules into it. */
+  constructor(timers) {
+    this.#timers = timers;
+  }
+  /** Starts the floor: call when the state being held becomes visible. */
+  begin() {
+    this.#since = Date.now();
+  }
+  /** True while a finish is held back waiting for the floor to elapse. */
+  get pending() {
+    return this.#timerId !== null;
+  }
+  /**
+   * Runs `finish` once the floor has elapsed, immediately when it already has.
+   *
+   * A held-back finish is **replaced**, never stacked: only the most recently
+   * queued id is cancellable, so a second timer would outlive every cancel and
+   * end a state that has since restarted. Controllers that want the first signal
+   * to win guard on {@link pending} before calling.
+   */
+  schedule(minDuration, finish) {
+    this.cancel();
+    const remaining = minDuration - (Date.now() - this.#since);
+    if (remaining > 0) {
+      this.#timerId = this.#timers.set(() => {
+        this.#timerId = null;
+        finish();
+      }, remaining);
+    } else {
+      finish();
+    }
+  }
+  /** Drops a held-back finish. Safe when none is queued, or after a bulk clear. */
+  cancel() {
+    if (this.#timerId !== null) {
+      this.#timers.clear(this.#timerId);
+      this.#timerId = null;
+    }
+  }
+};
+
 // src/utils/safe_timeout.ts
 var TimerRegistry = class {
   /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
@@ -59,32 +198,32 @@ var SafeTimeout = class extends TimerRegistry {
 var FrameLoadingController = class extends Controller {
   static targets = ["content", "skeleton", "overlay"];
   static values = {
+    announceText: { type: String, default: "" },
+    announceReadyText: { type: String, default: "" },
     minDuration: { type: Number, default: 0 },
     restoreFocus: { type: Boolean, default: true }
   };
   static events = ["start", "end"];
   #timeouts = new SafeTimeout();
+  #floor = new MinDurationFloor(this.#timeouts);
+  #gate = new DetachGate();
+  #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
   #loading = false;
-  #startedAt = 0;
   #inertApplied = false;
   #previousFocus = null;
   /** The id of the retreated element, used to re-find it if the load replaced it. */
   #previousFocusId = "";
   #onStart = () => {
-    this.#timeouts.clearAll();
+    this.#floor.cancel();
     if (!this.#loading) this.#begin();
   };
   #onEnd = () => {
     if (!this.#loading) return;
-    const remaining = this.minDurationValue - (Date.now() - this.#startedAt);
-    if (remaining > 0) {
-      this.#timeouts.clearAll();
-      this.#timeouts.set(() => this.#finish(), remaining);
-    } else {
-      this.#finish();
-    }
+    this.#floor.schedule(this.minDurationValue, () => this.#finish());
   };
   connect() {
+    this.#gate.cancel();
+    this.#beforeCache.activate();
     this.element.addEventListener("turbo:before-fetch-request", this.#onStart);
     this.element.addEventListener("turbo:frame-load", this.#onEnd);
     this.element.addEventListener("turbo:fetch-request-error", this.#onEnd);
@@ -93,19 +232,40 @@ var FrameLoadingController = class extends Controller {
     this.element.removeEventListener("turbo:before-fetch-request", this.#onStart);
     this.element.removeEventListener("turbo:frame-load", this.#onEnd);
     this.element.removeEventListener("turbo:fetch-request-error", this.#onEnd);
+    this.#beforeCache.deactivate();
+    this.#gate.disconnected(this, () => this.#teardown());
+  }
+  /**
+   * Drops the held finish and the loading bookkeeping on a real detach. The markup
+   * keeps whatever it last held: the page being cached is rewound at
+   * `turbo:before-cache` instead, where the frame is still whole.
+   */
+  #teardown() {
+    this.#gate.cancel();
     this.#timeouts.clearAll();
-    if (this.#loading) {
-      this.element.removeAttribute("aria-busy");
-      this.element.removeAttribute("data-frame-loading");
-      this.#clearInert();
-    }
+    this.#floor.cancel();
     this.#loading = false;
     this.#previousFocus = null;
   }
+  /**
+   * Returns the frame to its resting hooks for the snapshot Turbo is about to
+   * take, so a page reached with the Back button does not restore a frame that is
+   * busy and inert with nothing left to finish it. State only — no `end` event and
+   * no focus move, because the load did not actually complete. The live page keeps
+   * its held finish, so a navigation that never completes still ends properly.
+   */
+  #rewindForCache() {
+    if (!this.#loading) return;
+    this.element.removeAttribute("aria-busy");
+    this.element.removeAttribute("data-frame-loading");
+    if (this.hasSkeletonTarget) this.skeletonTarget.hidden = true;
+    if (this.hasOverlayTarget) this.overlayTarget.hidden = true;
+    this.#clearInert();
+  }
   /** Enters the loading state: hooks, skeleton/overlay, inert content, focus retreat. */
   #begin() {
     this.#loading = true;
-    this.#startedAt = Date.now();
+    this.#floor.begin();
     this.element.setAttribute("aria-busy", "true");
     this.element.setAttribute("data-frame-loading", "true");
     if (this.hasSkeletonTarget) this.skeletonTarget.hidden = false;
@@ -113,6 +273,7 @@ var FrameLoadingController = class extends Controller {
     this.#applyInert();
     this.#retreatFocus();
     this.dispatch("start", { detail: {} });
+    announce(fillTemplate(this.announceTextValue, {}));
   }
   /** Leaves the loading state: restore hooks, hide skeleton/overlay, restore focus. */
   #finish() {
@@ -124,6 +285,7 @@ var FrameLoadingController = class extends Controller {
     this.#clearInert();
     this.#restoreFocus();
     this.dispatch("end", { detail: {} });
+    announce(fillTemplate(this.announceReadyTextValue, {}));
   }
   /** Marks the content inert to block double-submits while stale (if we own it). */
   #applyInert() {

data/dist/controllers/intersection_controller.js

@@ -13,6 +13,7 @@ var IntersectionWatcher = class {
   #onEntries;
   #observer = null;
   #active = false;
+  #usingPlatformDefaults = false;
   constructor(onEntries) {
     this.#onEntries = onEntries;
   }
@@ -20,15 +21,22 @@ var IntersectionWatcher = class {
   get active() {
     return this.#active;
   }
+  /** Whether the live observer discarded configured options after construction failed. */
+  get usingPlatformDefaults() {
+    return this.#usingPlatformDefaults;
+  }
   /**
    * (Re)creates the observer and observes `targets`. Returns `false` — leaving
    * the watcher inert — without `IntersectionObserver` support (very old
    * browsers; the caller's no-JS fallback stays in charge) or with no targets.
+   * If initial construction with the configured options fails, the watcher
+   * warns and retries once with the same root and platform defaults.
    *
-   * @throws Whatever the platform throws for an invalid `rootMargin`/`threshold`
-   *   or a failing `observe()`. The exception is passed through unchanged, but
-   *   the watcher rolls back first: every target observed so far is released and
-   *   `active` stays `false`, so a caller that retries starts from a clean slate.
+   * @throws The fallback constructor error if both construction attempts fail,
+   *   or whatever the platform throws from `observe()`. The exception is passed
+   *   through unchanged, but the watcher rolls back first: every target observed
+   *   so far is released and `active` stays `false`, so a caller that retries
+   *   starts from a clean slate.
    */
   start(targets, options = {}) {
     this.stop();
@@ -38,12 +46,23 @@ var IntersectionWatcher = class {
     const root = "root" in options ? options.root ?? null : options.rootSelector ? document.querySelector(options.rootSelector) : null;
     let observer = null;
     try {
-      observer = new IntersectionObserver(
-        (entries) => {
-          if (this.#active && this.#observer === observer) this.#onEntries(entries);
-        },
-        { root, rootMargin: options.rootMargin, threshold: options.threshold }
-      );
+      const onEntries = (entries) => {
+        if (this.#active && this.#observer === observer) this.#onEntries(entries);
+      };
+      try {
+        observer = new IntersectionObserver(onEntries, {
+          root,
+          rootMargin: options.rootMargin,
+          threshold: options.threshold
+        });
+      } catch (error) {
+        console.warn(
+          "Stimeo UI: IntersectionObserver could not be constructed with the configured options; retrying with platform defaults.",
+          error
+        );
+        observer = new IntersectionObserver(onEntries, { root });
+        this.#usingPlatformDefaults = true;
+      }
       for (const target of list) observer.observe(target);
       this.#observer = observer;
       this.#active = true;
@@ -52,6 +71,7 @@ var IntersectionWatcher = class {
       observer?.disconnect();
       this.#observer = null;
       this.#active = false;
+      this.#usingPlatformDefaults = false;
       throw error;
     }
   }
@@ -78,6 +98,7 @@ var IntersectionWatcher = class {
     this.#active = false;
     this.#observer?.disconnect();
     this.#observer = null;
+    this.#usingPlatformDefaults = false;
   }
 };
 
@@ -96,6 +117,8 @@ var IntersectionController = class extends Controller {
   static events = ["enter", "exit", "change", "passed"];
   /** Shared IO plumbing (support guard, root resolution, active guard, re-arm). */
   #watcher = new IntersectionWatcher((entries) => this.#onIntersect(entries));
+  /** Threshold actually installed in the live observer (0 after option fallback). */
+  #effectiveThreshold = 0;
   /** Bumped by `refresh()`: an in-flight batch becomes stale and stops. */
   #generation = 0;
   #onIntersect(entries) {
@@ -103,7 +126,7 @@ var IntersectionController = class extends Controller {
     for (const entry of entries) {
       if (!this.#watcher.active || this.#generation !== generation) return;
       const ratio = entry.intersectionRatio;
-      const threshold = this.#clampedThreshold();
+      const threshold = this.#effectiveThreshold;
       const intersecting = threshold > 0 ? entry.isIntersecting && ratio >= threshold - RATIO_EPSILON : entry.isIntersecting;
       this.element.style.setProperty(RATIO_PROPERTY, String(ratio));
       this.dispatch("change", { detail: { intersecting, ratio } });
@@ -113,11 +136,13 @@ var IntersectionController = class extends Controller {
   }
   connect() {
     if (this.onceValue && this.element.getAttribute("data-intersecting") === "true") return;
+    this.#effectiveThreshold = this.#clampedThreshold();
     this.#watcher.start(this.element, {
       rootSelector: this.rootSelectorValue,
       rootMargin: this.rootMarginValue,
       threshold: this.#thresholds()
     });
+    if (this.#watcher.usingPlatformDefaults) this.#effectiveThreshold = 0;
   }
   disconnect() {
     this.#watcher.stop();

data/dist/controllers/lazy_frame_controller.js

@@ -7,6 +7,7 @@ var IntersectionWatcher = class {
   #onEntries;
   #observer = null;
   #active = false;
+  #usingPlatformDefaults = false;
   constructor(onEntries) {
     this.#onEntries = onEntries;
   }
@@ -14,15 +15,22 @@ var IntersectionWatcher = class {
   get active() {
     return this.#active;
   }
+  /** Whether the live observer discarded configured options after construction failed. */
+  get usingPlatformDefaults() {
+    return this.#usingPlatformDefaults;
+  }
   /**
    * (Re)creates the observer and observes `targets`. Returns `false` — leaving
    * the watcher inert — without `IntersectionObserver` support (very old
    * browsers; the caller's no-JS fallback stays in charge) or with no targets.
+   * If initial construction with the configured options fails, the watcher
+   * warns and retries once with the same root and platform defaults.
    *
-   * @throws Whatever the platform throws for an invalid `rootMargin`/`threshold`
-   *   or a failing `observe()`. The exception is passed through unchanged, but
-   *   the watcher rolls back first: every target observed so far is released and
-   *   `active` stays `false`, so a caller that retries starts from a clean slate.
+   * @throws The fallback constructor error if both construction attempts fail,
+   *   or whatever the platform throws from `observe()`. The exception is passed
+   *   through unchanged, but the watcher rolls back first: every target observed
+   *   so far is released and `active` stays `false`, so a caller that retries
+   *   starts from a clean slate.
    */
   start(targets, options = {}) {
     this.stop();
@@ -32,12 +40,23 @@ var IntersectionWatcher = class {
     const root = "root" in options ? options.root ?? null : options.rootSelector ? document.querySelector(options.rootSelector) : null;
     let observer = null;
     try {
-      observer = new IntersectionObserver(
-        (entries) => {
-          if (this.#active && this.#observer === observer) this.#onEntries(entries);
-        },
-        { root, rootMargin: options.rootMargin, threshold: options.threshold }
-      );
+      const onEntries = (entries) => {
+        if (this.#active && this.#observer === observer) this.#onEntries(entries);
+      };
+      try {
+        observer = new IntersectionObserver(onEntries, {
+          root,
+          rootMargin: options.rootMargin,
+          threshold: options.threshold
+        });
+      } catch (error) {
+        console.warn(
+          "Stimeo UI: IntersectionObserver could not be constructed with the configured options; retrying with platform defaults.",
+          error
+        );
+        observer = new IntersectionObserver(onEntries, { root });
+        this.#usingPlatformDefaults = true;
+      }
       for (const target of list) observer.observe(target);
       this.#observer = observer;
       this.#active = true;
@@ -46,6 +65,7 @@ var IntersectionWatcher = class {
       observer?.disconnect();
       this.#observer = null;
       this.#active = false;
+      this.#usingPlatformDefaults = false;
       throw error;
     }
   }
@@ -72,6 +92,7 @@ var IntersectionWatcher = class {
     this.#active = false;
     this.#observer?.disconnect();
     this.#observer = null;
+    this.#usingPlatformDefaults = false;
   }
 };