stimeo-ui 0.16.0 → 0.17.0

package/dist/controllers/lazy_frame_controller.js

@@ -1,8 +1,5 @@
 import { Controller } from '@hotwired/stimulus';
 
-// src/controllers/lazy_frame_controller.ts
-
-// src/utils/declared_value.ts
 function parseDeclared(raw, parse, fallback) {
   try {
     return parse(raw);
@@ -11,7 +8,6 @@ function parseDeclared(raw, parse, fallback) {
   }
 }
 
-// src/utils/intersection_watcher.ts
 function queryRoot(selector) {
   if (!selector) return null;
   return parseDeclared(selector, (raw) => document.querySelector(raw), null);
@@ -24,30 +20,12 @@ var IntersectionWatcher = class {
   constructor(onEntries) {
     this.#onEntries = onEntries;
   }
-  /** Whether an observer is live (started, `IntersectionObserver` supported). */
   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. A
-   * `rootSelector` that does not parse resolves to the viewport (see
-   * {@link IntersectionWatchOptions.rootSelector}), so a typo never fails the
-   * call.
-   *
-   * @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();
     if (typeof IntersectionObserver === "undefined") return false;
@@ -85,14 +63,6 @@ var IntersectionWatcher = class {
       throw error;
     }
   }
-  /**
-   * Re-delivers `target`'s CURRENT intersection state: `IntersectionObserver`
-   * only reports *changes*, but `observe()` always reports the present state,
-   * so unobserve→observe turns "still intersecting" into a fresh callback.
-   *
-   * @throws Whatever `unobserve()`/`observe()` throws. The watcher is stopped
-   *   first, so it never stays live with a half-rearmed target.
-   */
   rearm(target) {
     if (!this.#observer) return;
     try {
@@ -103,7 +73,6 @@ var IntersectionWatcher = class {
       throw error;
     }
   }
-  /** Severs the observer; late queued callbacks become no-ops via the guard. */
   stop() {
     this.#active = false;
     this.#observer?.disconnect();
@@ -112,7 +81,6 @@ var IntersectionWatcher = class {
   }
 };
 
-// src/controllers/lazy_frame_controller.ts
 var LazyFrameController = class extends Controller {
   static values = {
     url: { type: String, default: "" },
@@ -120,38 +88,28 @@ var LazyFrameController = class extends Controller {
     once: { type: Boolean, default: true }
   };
   static events = ["load"];
-  /** Shared IO plumbing (support guard, active guard, teardown). */
   #watcher = new IntersectionWatcher((entries) => this.#onIntersect(entries));
   #connected = false;
   #loaded = false;
-  /**
-   * Whether the observer last saw the frame inside the observed area — `null`
-   * until it has reported. A re-entry needs a frame that was seen inside and
-   * then left, so an unknown position is never a departure.
-   */
   #inside = null;
-  /**
-   * Focus reaching the frame starts the FIRST load before it intersects (keyboard / AT).
-   * `#load` releases this listener, so focus never reaches an already-loaded frame.
-   */
   #onFocus = () => this.#load();
-  /**
-   * Follows the held URL at runtime: one that arrives arms the frame, one that is
-   * taken away disarms it, so an empty `url` holds no triggers either way.
-   *
-   * Stimulus runs value callbacks before `connect()`, so the connected guard keeps
-   * arming in one place. A frame that already loaded keeps its held URL for the next
-   * re-entry instead of fetching on the spot.
-   */
   urlValueChanged() {
     if (!this.#connected || this.#loaded) return;
     if (this.urlValue) this.#arm();
     else this.#stopObserving();
   }
-  /** Rebuilds the observer when the early-load margin changes at runtime. */
   rootMarginValueChanged() {
     if (this.#connected && this.#watcher.active) this.#observe();
   }
+  onceValueChanged() {
+    if (!this.#connected || !this.#loaded) return;
+    if (this.onceValue) {
+      this.#watcher.stop();
+    } else if (!this.#watcher.active) {
+      this.#inside = null;
+      this.#arm();
+    }
+  }
   connect() {
     this.#loaded = this.element.hasAttribute("data-lazy-loaded");
     this.#inside = null;
@@ -163,7 +121,6 @@ var LazyFrameController = class extends Controller {
     this.#connected = false;
     this.#stopObserving();
   }
-  /** Attaches the triggers that still have a job to do. */
   #arm() {
     if (!this.urlValue) return;
     if (!this.#loaded) this.element.addEventListener("focusin", this.#onFocus);
@@ -183,7 +140,6 @@ var LazyFrameController = class extends Controller {
       }
     }
   }
-  /** Applies an intersecting entry: the first one loads, a return re-fetches. */
   #enter(returning) {
     if (!this.#loaded) {
       this.#load();
@@ -192,12 +148,6 @@ var LazyFrameController = class extends Controller {
     if (this.onceValue || !returning) return;
     this.#reload();
   }
-  /**
-   * Starts the load by writing the held URL to `src`.
-   *
-   * @stimeoRuntimeOnly `url` is the address this one load fetches and `once` decides whether it
-   *   stops the watcher.
-   */
   #load() {
     if (!this.urlValue) return;
     this.#loaded = true;
@@ -207,11 +157,6 @@ var LazyFrameController = class extends Controller {
     this.element.removeEventListener("focusin", this.#onFocus);
     if (this.onceValue) this.#watcher.stop();
   }
-  /**
-   * Re-entry while `once` is off: fetch the held URL again.
-   *
-   * @stimeoRuntimeOnly `url` is the address this one re-entry reloads.
-   */
   #reload() {
     const src = this.element.getAttribute("src");
     if (this.urlValue && this.urlValue !== src) {
@@ -231,5 +176,4 @@ var LazyFrameController = class extends Controller {
 };
 
 export { LazyFrameController };
-//# sourceMappingURL=lazy_frame_controller.js.map
 //# sourceMappingURL=lazy_frame_controller.js.map

package/dist/controllers/lazy_frame_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/declared_value.ts","../../src/utils/intersection_watcher.ts","../../src/controllers/lazy_frame_controller.ts"],"names":[],"mappings":";;;;;AAuBO,SAAS,aAAA,CAAiB,GAAA,EAAa,KAAA,EAA2B,QAAA,EAAgB;AACvF,EAAA,IAAI;AACF,IAAA,OAAO,MAAM,GAAG,CAAA;AAAA,EAClB,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,QAAA;AAAA,EACT;AACF;;;ACoBA,SAAS,UAAU,QAAA,EAA8C;AAC/D,EAAA,IAAI,CAAC,UAAU,OAAO,IAAA;AACtB,EAAA,OAAO,aAAA,CAAc,UAAU,CAAC,GAAA,KAAQ,SAAS,aAAA,CAAc,GAAG,GAAG,IAAI,CAAA;AAC3E;AAiBO,IAAM,sBAAN,MAA0B;AAAA,EACtB,UAAA;AAAA,EACT,SAAA,GAAyC,IAAA;AAAA,EACzC,OAAA,GAAU,KAAA;AAAA,EACV,sBAAA,GAAyB,KAAA;AAAA,EAEzB,YAAY,SAAA,EAA2D;AACrE,IAAA,IAAA,CAAK,UAAA,GAAa,SAAA;AAAA,EACpB;AAAA;AAAA,EAGA,IAAI,MAAA,GAAkB;AACpB,IAAA,OAAO,IAAA,CAAK,OAAA;AAAA,EACd;AAAA;AAAA,EAGA,IAAI,qBAAA,GAAiC;AACnC,IAAA,OAAO,IAAA,CAAK,sBAAA;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAkBA,KAAA,CAAM,OAAA,EAAuC,OAAA,GAAoC,EAAC,EAAY;AAC5F,IAAA,IAAA,CAAK,IAAA,EAAK;AACV,IAAA,IAAI,OAAO,oBAAA,KAAyB,WAAA,EAAa,OAAO,KAAA;AACxD,IAAA,MAAM,OAAO,KAAA,CAAM,OAAA,CAAQ,OAAO,CAAA,GAAK,OAAA,GAAiC,CAAC,OAAkB,CAAA;AAC3F,IAAA,IAAI,IAAA,CAAK,MAAA,KAAW,CAAA,EAAG,OAAO,KAAA;AAE9B,IAAA,MAAM,IAAA,GAAO,UAAU,OAAA,GAAW,OAAA,CAAQ,QAAQ,IAAA,GAAQ,SAAA,CAAU,QAAQ,YAAY,CAAA;AAExF,IAAA,IAAI,QAAA,GAAwC,IAAA;AAC5C,IAAA,IAAI;AACF,MAAA,MAAM,SAAA,GAAY,CAAC,OAAA,KAA+C;AAGhE,QAAA,IAAI,KAAK,OAAA,IAAW,IAAA,CAAK,cAAc,QAAA,EAAU,IAAA,CAAK,WAAW,OAAO,CAAA;AAAA,MAC1E,CAAA;AACA,MAAA,IAAI;AACF,QAAA,QAAA,GAAW,IAAI,qBAAqB,SAAA,EAAW;AAAA,UAC7C,IAAA;AAAA,UACA,YAAY,OAAA,CAAQ,UAAA;AAAA,UACpB,WAAW,OAAA,CAAQ;AAAA,SACpB,CAAA;AAAA,MACH,SAAS,KAAA,EAAO;AACd,QAAA,OAAA,CAAQ,IAAA;AAAA,UACN,wHAAA;AAAA,UACA;AAAA,SACF;AACA,QAAA,QAAA,GAAW,IAAI,oBAAA,CAAqB,SAAA,EAAW,EAAE,MAAM,CAAA;AACvD,QAAA,IAAA,CAAK,sBAAA,GAAyB,IAAA;AAAA,MAChC;AACA,MAAA,KAAA,MAAW,MAAA,IAAU,IAAA,EAAM,QAAA,CAAS,OAAA,CAAQ,MAAM,CAAA;AAClD,MAAA,IAAA,CAAK,SAAA,GAAY,QAAA;AACjB,MAAA,IAAA,CAAK,OAAA,GAAU,IAAA;AACf,MAAA,OAAO,IAAA;AAAA,IACT,SAAS,KAAA,EAAO;AAGd,MAAA,QAAA,EAAU,UAAA,EAAW;AACrB,MAAA,IAAA,CAAK,SAAA,GAAY,IAAA;AACjB,MAAA,IAAA,CAAK,OAAA,GAAU,KAAA;AACf,MAAA,IAAA,CAAK,sBAAA,GAAyB,KAAA;AAC9B,MAAA,MAAM,KAAA;AAAA,IACR;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,MAAM,MAAA,EAAuB;AAC3B,IAAA,IAAI,CAAC,KAAK,SAAA,EAAW;AACrB,IAAA,IAAI;AACF,MAAA,IAAA,CAAK,SAAA,CAAU,UAAU,MAAM,CAAA;AAC/B,MAAA,IAAA,CAAK,SAAA,CAAU,QAAQ,MAAM,CAAA;AAAA,IAC/B,SAAS,KAAA,EAAO;AACd,MAAA,IAAA,CAAK,IAAA,EAAK;AACV,MAAA,MAAM,KAAA;AAAA,IACR;AAAA,EACF;AAAA;AAAA,EAGA,IAAA,GAAa;AACX,IAAA,IAAA,CAAK,OAAA,GAAU,KAAA;AACf,IAAA,IAAA,CAAK,WAAW,UAAA,EAAW;AAC3B,IAAA,IAAA,CAAK,SAAA,GAAY,IAAA;AACjB,IAAA,IAAA,CAAK,sBAAA,GAAyB,KAAA;AAAA,EAChC;AACF,CAAA;;;ACrIO,IAAM,mBAAA,GAAN,cAAkC,UAAA,CAAwB;AAAA,EAC/D,OAAgB,MAAA,GAAS;AAAA,IACvB,GAAA,EAAK,EAAE,IAAA,EAAM,MAAA,EAAQ,SAAS,EAAA,EAAG;AAAA,IACjC,UAAA,EAAY,EAAE,IAAA,EAAM,MAAA,EAAQ,SAAS,KAAA,EAAM;AAAA,IAC3C,IAAA,EAAM,EAAE,IAAA,EAAM,OAAA,EAAS,SAAS,IAAA;AAAK,GACvC;AAAA,EACA,OAAO,MAAA,GAAS,CAAC,MAAM,CAAA;AAAA;AAAA,EAOd,QAAA,GAAW,IAAI,mBAAA,CAAoB,CAAC,YAAY,IAAA,CAAK,YAAA,CAAa,OAAO,CAAC,CAAA;AAAA,EACnF,UAAA,GAAa,KAAA;AAAA,EACb,OAAA,GAAU,KAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMV,OAAA,GAA0B,IAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMjB,QAAA,GAAW,MAAY,IAAA,CAAK,KAAA,EAAM;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAU3C,eAAA,GAAwB;AACtB,IAAA,IAAI,CAAC,IAAA,CAAK,UAAA,IAAc,IAAA,CAAK,OAAA,EAAS;AACtC,IAAA,IAAI,IAAA,CAAK,QAAA,EAAU,IAAA,CAAK,IAAA,EAAK;AAAA,cACnB,cAAA,EAAe;AAAA,EAC3B;AAAA;AAAA,EAGA,sBAAA,GAA+B;AAC7B,IAAA,IAAI,KAAK,UAAA,IAAc,IAAA,CAAK,QAAA,CAAS,MAAA,OAAa,QAAA,EAAS;AAAA,EAC7D;AAAA,EAES,OAAA,GAAgB;AAGvB,IAAA,IAAA,CAAK,OAAA,GAAU,IAAA,CAAK,OAAA,CAAQ,YAAA,CAAa,kBAAkB,CAAA;AAC3D,IAAA,IAAA,CAAK,OAAA,GAAU,IAAA;AACf,IAAA,IAAA,CAAK,UAAA,GAAa,IAAA;AAClB,IAAA,IAAI,IAAA,CAAK,OAAA,IAAW,IAAA,CAAK,SAAA,EAAW;AACpC,IAAA,IAAA,CAAK,IAAA,EAAK;AAAA,EACZ;AAAA,EAES,UAAA,GAAmB;AAC1B,IAAA,IAAA,CAAK,UAAA,GAAa,KAAA;AAClB,IAAA,IAAA,CAAK,cAAA,EAAe;AAAA,EACtB;AAAA;AAAA,EAGA,IAAA,GAAa;AACX,IAAA,IAAI,CAAC,KAAK,QAAA,EAAU;AACpB,IAAA,IAAI,CAAC,KAAK,OAAA,EAAS,IAAA,CAAK,QAAQ,gBAAA,CAAiB,SAAA,EAAW,KAAK,QAAQ,CAAA;AACzE,IAAA,IAAA,CAAK,QAAA,EAAS;AAAA,EAChB;AAAA,EAEA,QAAA,GAAiB;AACf,IAAA,IAAA,CAAK,QAAA,CAAS,MAAM,IAAA,CAAK,OAAA,EAAS,EAAE,UAAA,EAAY,IAAA,CAAK,iBAAiB,CAAA;AAAA,EACxE;AAAA,EAEA,aAAa,OAAA,EAA4C;AACvD,IAAA,KAAA,MAAW,SAAS,OAAA,EAAS;AAC3B,MAAA,IAAI,MAAM,cAAA,EAAgB;AACxB,QAAA,MAAM,SAAA,GAAY,KAAK,OAAA,KAAY,KAAA;AACnC,QAAA,IAAA,CAAK,OAAA,GAAU,IAAA;AACf,QAAA,IAAA,CAAK,OAAO,SAAS,CAAA;AAAA,MACvB,CAAA,MAAA,IAAW,KAAK,OAAA,EAAS;AAGvB,QAAA,IAAA,CAAK,OAAA,GAAU,KAAA;AAAA,MACjB;AAAA,IACF;AAAA,EACF;AAAA;AAAA,EAGA,OAAO,SAAA,EAA0B;AAC/B,IAAA,IAAI,CAAC,KAAK,OAAA,EAAS;AACjB,MAAA,IAAA,CAAK,KAAA,EAAM;AACX,MAAA;AAAA,IACF;AACA,IAAA,IAAI,IAAA,CAAK,SAAA,IAAa,CAAC,SAAA,EAAW;AAClC,IAAA,IAAA,CAAK,OAAA,EAAQ;AAAA,EACf;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,KAAA,GAAc;AACZ,IAAA,IAAI,CAAC,KAAK,QAAA,EAAU;AACpB,IAAA,IAAA,CAAK,OAAA,GAAU,IAAA;AACf,IAAA,IAAA,CAAK,OAAA,CAAQ,YAAA,CAAa,KAAA,EAAO,IAAA,CAAK,QAAQ,CAAA;AAC9C,IAAA,IAAA,CAAK,OAAA,CAAQ,YAAA,CAAa,kBAAA,EAAoB,MAAM,CAAA;AACpD,IAAA,IAAA,CAAK,QAAA,CAAS,QAAQ,EAAE,MAAA,EAAQ,EAAE,GAAA,EAAK,IAAA,CAAK,QAAA,EAAS,EAAG,CAAA;AAExD,IAAA,IAAA,CAAK,OAAA,CAAQ,mBAAA,CAAoB,SAAA,EAAW,IAAA,CAAK,QAAQ,CAAA;AACzD,IAAA,IAAI,IAAA,CAAK,SAAA,EAAW,IAAA,CAAK,QAAA,CAAS,IAAA,EAAK;AAAA,EACzC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,OAAA,GAAgB;AACd,IAAA,MAAM,GAAA,GAAM,IAAA,CAAK,OAAA,CAAQ,YAAA,CAAa,KAAK,CAAA;AAC3C,IAAA,IAAI,IAAA,CAAK,QAAA,IAAY,IAAA,CAAK,QAAA,KAAa,GAAA,EAAK;AAG1C,MAAA,IAAA,CAAK,OAAA,CAAQ,YAAA,CAAa,KAAA,EAAO,IAAA,CAAK,QAAQ,CAAA;AAC9C,MAAA,IAAA,CAAK,QAAA,CAAS,QAAQ,EAAE,MAAA,EAAQ,EAAE,GAAA,EAAK,IAAA,CAAK,QAAA,EAAS,EAAG,CAAA;AACxD,MAAA;AAAA,IACF;AACA,IAAA,MAAM,QAAQ,IAAA,CAAK,OAAA;AAInB,IAAA,IAAI,OAAO,KAAA,CAAM,MAAA,KAAW,UAAA,EAAY;AACxC,IAAA,KAAA,CAAM,MAAA,EAAO;AACb,IAAA,IAAA,CAAK,QAAA,CAAS,QAAQ,EAAE,MAAA,EAAQ,EAAE,GAAA,EAAK,GAAA,IAAO,EAAA,EAAG,EAAG,CAAA;AAAA,EACtD;AAAA,EAEA,cAAA,GAAuB;AACrB,IAAA,IAAA,CAAK,SAAS,IAAA,EAAK;AACnB,IAAA,IAAA,CAAK,OAAA,CAAQ,mBAAA,CAAoB,SAAA,EAAW,IAAA,CAAK,QAAQ,CAAA;AAAA,EAC3D;AACF","file":"lazy_frame_controller.js","sourcesContent":["/**\n * Readers for the String Values whose text can only be checked by handing it to\n * a parser: a CSS selector, a regular-expression source, a JSON object.\n *\n * Stimulus reads each of them as an ordinary string, so the controller connects\n * and the flaw surfaces later, inside the first handler that consumes the value\n * (a `SyntaxError` from `new RegExp`, a `DOMException` from the selector engine),\n * where it takes the whole handler down on every event. Parsing here, once, in\n * the `<name>ValueChanged` callback keeps the failure local to the declaration:\n * an unreadable value falls back to its default, the element stays alive, and\n * the hot path only ever receives a value that parsed.\n *\n * Which default a broken declaration falls back to is the caller's contract, so\n * every reader takes (or returns) the fallback rather than choosing one.\n */\n\n/**\n * The result of `parse(raw)`, or `fallback` when `parse` throws.\n *\n * Any exception counts as \"does not parse\": the parsers these Values feed\n * (`RegExp`, `JSON.parse`, the selector engine) all report a malformed input by\n * throwing, and none of them throws for another reason.\n */\nexport function parseDeclared<T>(raw: string, parse: (raw: string) => T, fallback: T): T {\n  try {\n    return parse(raw);\n  } catch {\n    return fallback;\n  }\n}\n\n/** What {@link validSelector} needs of the element it probes with. */\nexport interface SelectorProbe {\n  matches(selector: string): boolean;\n}\n\n/**\n * `raw` when it is a non-empty selector the DOM accepts, otherwise `fallback`.\n *\n * `element.matches` is the probe: the engine parses the selector and throws for\n * one it cannot read. Whether the selector actually matches `element` plays no\n * part, so a selector aimed at another element still passes.\n *\n * The parameter names the one method the probe uses rather than `Element`, so\n * this module carries no DOM type and the readers below stay importable from\n * the Node-side Inspector, which checks the same declarations statically.\n */\nexport function validSelector(element: SelectorProbe, raw: string, fallback: string): string {\n  if (raw.length === 0) return fallback;\n  return parseDeclared(\n    raw,\n    (selector) => {\n      element.matches(selector);\n      return selector;\n    },\n    fallback,\n  );\n}\n\n/** How `compileRegExp` wraps a source before compiling it. */\nexport type RegExpAnchor = \"none\" | \"exact\";\n\n/**\n * `source` compiled as a `RegExp`, or `null` when it does not compile.\n *\n * `\"exact\"` wraps the source as `^(?:source)$`, so the whole input has to match\n * and an alternation inside the source cannot escape the anchors. The source is\n * compiled on its own first, because an unbalanced source can be made to parse\n * by the wrapper's own parentheses — `0)|(1` becomes `^(?:0)|(1)$` — which would\n * accept a declaration that is not a regular expression and leave half of it\n * outside the anchors. The default that replaces a broken source is the\n * caller's, so `null` is returned rather than a fallback pattern.\n */\nexport function compileRegExp(source: string, anchor: RegExpAnchor = \"none\"): RegExp | null {\n  return parseDeclared(\n    source,\n    (text) => {\n      const bare = new RegExp(text);\n      return anchor === \"exact\" ? new RegExp(`^(?:${text})$`) : bare;\n    },\n    null,\n  );\n}\n\n/**\n * The JSON object `raw` declares, or `null` when the text does not parse or\n * parses to something other than a plain object (`null`, an array, a scalar).\n * Values are returned as parsed; narrowing them is the caller's contract.\n */\nexport function parseJsonObject(raw: string): Record<string, unknown> | null {\n  const parsed = parseDeclared<unknown>(raw, (text) => JSON.parse(text), null);\n  if (parsed === null || typeof parsed !== \"object\" || Array.isArray(parsed)) return null;\n  return parsed as Record<string, unknown>;\n}\n","/**\n * Shared `IntersectionObserver` plumbing for Stimeo's scroll-triggered\n * controllers (`intersection`, `scrollspy`, `sticky-observer`, `lazy-frame`).\n *\n * It centralizes the `IntersectionObserver` support guard, root resolution from\n * a selector (degrading to the viewport rather than failing), observer\n * creation/teardown, the **active guard** (the browser may\n * flush a final queued callback batch right after `disconnect()`, and a\n * detached controller must not mutate possibly-cached DOM), and the\n * unobserve→observe **re-arm** that re-delivers the current state even when the\n * target never leaves the viewport.\n *\n * Like `RovingTabindex` and `FocusTrap`, this is a policy-free internal\n * util: what an intersection *means* (a spied link, a stuck header, a lazy\n * load) stays in each controller. The public `stimeo--intersection` controller\n * is its thin declarative face.\n */\n\nimport { parseDeclared } from \"./declared_value\";\n\n/**\n * Whether `entry`'s target sits entirely before the root's **start (top)** edge —\n * the \"scrolled past the top\" half of a non-intersecting entry, as opposed to\n * \"not reached yet\" below the root.\n *\n * A target with no layout box (`display: none`, a `hidden` ancestor, a collapsed\n * `<details>`) is reported with an **empty rect**, whose `bottom` of `0` would\n * otherwise satisfy `bottom <= rootTop` for a viewport root and read as \"passed\"\n * even though the target was never scrolled anywhere. An empty rect carries no\n * position at all, so it is deliberately never \"before the edge\"; what a caller\n * publishes for that case is its own policy (both consumers treat it as the\n * neutral \"not passed\"/\"not stuck\", and the real rect that arrives once the\n * target is laid out re-establishes the true state).\n */\nexport function isBeforeRootStart(entry: IntersectionObserverEntry): boolean {\n  const rect = entry.boundingClientRect;\n  if (rect.width === 0 && rect.height === 0) return false;\n  // rootBounds is null for a cross-origin/removed root; fall back to the\n  // viewport origin.\n  const rootTop = entry.rootBounds?.top ?? 0;\n  return rect.bottom <= rootTop;\n}\n\n/**\n * Resolves an observation root from a selector. Every reading of \"no root\" ends\n * at the same place — absent, matching nothing, or not parsing at all (a typo in\n * a data attribute) — so the observation falls back to the viewport instead of\n * leaving the caller inert with no state hooks published at all.\n */\nfunction queryRoot(selector: string | undefined): Element | null {\n  if (!selector) return null;\n  return parseDeclared(selector, (raw) => document.querySelector(raw), null);\n}\n\nexport interface IntersectionWatchOptions {\n  /**\n   * The observation root. Pass an element (or `null` for the viewport) when\n   * the caller already resolved it; omit to resolve from `rootSelector`.\n   */\n  root?: Element | null;\n  /**\n   * Selector for the observation root; empty/omitted = viewport. A selector\n   * that matches nothing or does not parse also means the viewport.\n   */\n  rootSelector?: string;\n  rootMargin?: string;\n  threshold?: number | number[];\n}\n\nexport class IntersectionWatcher {\n  readonly #onEntries: (entries: IntersectionObserverEntry[]) => void;\n  #observer: IntersectionObserver | null = null;\n  #active = false;\n  #usingPlatformDefaults = false;\n\n  constructor(onEntries: (entries: IntersectionObserverEntry[]) => void) {\n    this.#onEntries = onEntries;\n  }\n\n  /** Whether an observer is live (started, `IntersectionObserver` supported). */\n  get active(): boolean {\n    return this.#active;\n  }\n\n  /** Whether the live observer discarded configured options after construction failed. */\n  get usingPlatformDefaults(): boolean {\n    return this.#usingPlatformDefaults;\n  }\n\n  /**\n   * (Re)creates the observer and observes `targets`. Returns `false` — leaving\n   * the watcher inert — without `IntersectionObserver` support (very old\n   * browsers; the caller's no-JS fallback stays in charge) or with no targets.\n   * If initial construction with the configured options fails, the watcher\n   * warns and retries once with the same root and platform defaults. A\n   * `rootSelector` that does not parse resolves to the viewport (see\n   * {@link IntersectionWatchOptions.rootSelector}), so a typo never fails the\n   * call.\n   *\n   * @throws The fallback constructor error if both construction attempts fail,\n   *   or whatever the platform throws from `observe()`. The exception is passed\n   *   through unchanged, but the watcher rolls back first: every target observed\n   *   so far is released and `active` stays `false`, so a caller that retries\n   *   starts from a clean slate.\n   */\n  start(targets: Element | readonly Element[], options: IntersectionWatchOptions = {}): boolean {\n    this.stop();\n    if (typeof IntersectionObserver === \"undefined\") return false;\n    const list = Array.isArray(targets) ? (targets as readonly Element[]) : [targets as Element];\n    if (list.length === 0) return false;\n\n    const root = \"root\" in options ? (options.root ?? null) : queryRoot(options.rootSelector);\n\n    let observer: IntersectionObserver | null = null;\n    try {\n      const onEntries = (entries: IntersectionObserverEntry[]): void => {\n        // Identity matters across an immediate restart: the old observer can\n        // flush a queued batch after the new observer has made `active` true.\n        if (this.#active && this.#observer === observer) this.#onEntries(entries);\n      };\n      try {\n        observer = new IntersectionObserver(onEntries, {\n          root,\n          rootMargin: options.rootMargin,\n          threshold: options.threshold,\n        });\n      } catch (error) {\n        console.warn(\n          \"Stimeo UI: IntersectionObserver could not be constructed with the configured options; retrying with platform defaults.\",\n          error,\n        );\n        observer = new IntersectionObserver(onEntries, { root });\n        this.#usingPlatformDefaults = true;\n      }\n      for (const target of list) observer.observe(target);\n      this.#observer = observer;\n      this.#active = true;\n      return true;\n    } catch (error) {\n      // A constructor or partial observe failure must not leave earlier targets\n      // observed or report an active watcher. Preserve the platform exception.\n      observer?.disconnect();\n      this.#observer = null;\n      this.#active = false;\n      this.#usingPlatformDefaults = false;\n      throw error;\n    }\n  }\n\n  /**\n   * Re-delivers `target`'s CURRENT intersection state: `IntersectionObserver`\n   * only reports *changes*, but `observe()` always reports the present state,\n   * so unobserve→observe turns \"still intersecting\" into a fresh callback.\n   *\n   * @throws Whatever `unobserve()`/`observe()` throws. The watcher is stopped\n   *   first, so it never stays live with a half-rearmed target.\n   */\n  rearm(target: Element): void {\n    if (!this.#observer) return;\n    try {\n      this.#observer.unobserve(target);\n      this.#observer.observe(target);\n    } catch (error) {\n      this.stop();\n      throw error;\n    }\n  }\n\n  /** Severs the observer; late queued callbacks become no-ops via the guard. */\n  stop(): void {\n    this.#active = false;\n    this.#observer?.disconnect();\n    this.#observer = null;\n    this.#usingPlatformDefaults = false;\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { IntersectionWatcher } from \"../utils/intersection_watcher\";\n\n/**\n * Headless **lazy frame**: defers a `<turbo-frame>`'s load until it nears the viewport\n * (or focus reaches it), to keep the initial render light. Turbo's own `loading=\"lazy\"`\n * observes with no margin, so the frame loads only once it is already in view; this\n * drives an explicit `IntersectionObserver` with a configurable `rootMargin`, plus a focus fallback so keyboard /\n * assistive-tech users trigger the load too (no APG pattern).\n *\n * Markup contract (identifier: `stimeo--lazy-frame`):\n *   <turbo-frame id=\"comments\" data-controller=\"stimeo--lazy-frame\"\n *     data-stimeo--lazy-frame-url-value=\"/posts/1/comments\"\n *     data-stimeo--lazy-frame-root-margin-value=\"200px\">Loading…</turbo-frame>\n *\n * The URL is *held* in the `url` value (not on `src`) so Turbo does not load it eagerly;\n * when the frame intersects (within `rootMargin`) or focus enters it, the controller\n * writes `url` to `src` — **writing `src` is what starts the fetch** — marks\n * `data-lazy-loaded`, and emits `load`. Focus is the fallback for the *first* load only;\n * once the frame has loaded, its listener is released and further focus moves inside the\n * frame change nothing.\n *\n * With `once` (default) the controller then stops observing. With `once` off it keeps\n * watching and re-fetches on a **re-entry** — the frame has to be seen inside the\n * observed area, leave it, and come back. Where a connection first finds the frame is the\n * baseline rather than a movement, so a focus-started load and a cache restore each begin\n * the visit wherever the frame sits — in view or out of it — and re-fetch nothing until it\n * leaves and returns. A re-entry serves the held `url`: when it still matches `src`, the\n * host's own `reload()` refetches it; when it has moved on, writing the new `url` to `src`\n * is the fetch.\n *\n * `load` dispatches `{ url }` — always the URL the fetch actually started for.\n *\n * @remarks\n * Behavior only — the load itself and the frame's content are Turbo's / the server's job,\n * and the loading UI (skeleton / `aria-busy`) belongs to `stimeo--frame-loading`. The trigger\n * is idempotent (`data-lazy-loaded` guards a double load and is the truth source on a\n * Turbo cache restore: a restored frame is observed again only while `once` is off, which\n * is the mode that asked to keep re-fetching). An empty `url` arms nothing and is never\n * written to `src`. The `IntersectionObserver` and focus listener are released once loaded\n * (when `once`) and on `disconnect()` (Turbo navigation included).\n */\nexport class LazyFrameController extends Controller<HTMLElement> {\n  static override values = {\n    url: { type: String, default: \"\" },\n    rootMargin: { type: String, default: \"0px\" },\n    once: { type: Boolean, default: true },\n  };\n  static events = [\"load\"] as const;\n\n  declare urlValue: string;\n  declare rootMarginValue: string;\n  declare onceValue: boolean;\n\n  /** Shared IO plumbing (support guard, active guard, teardown). */\n  readonly #watcher = new IntersectionWatcher((entries) => this.#onIntersect(entries));\n  #connected = false;\n  #loaded = false;\n  /**\n   * Whether the observer last saw the frame inside the observed area — `null`\n   * until it has reported. A re-entry needs a frame that was seen inside and\n   * then left, so an unknown position is never a departure.\n   */\n  #inside: boolean | null = null;\n\n  /**\n   * Focus reaching the frame starts the FIRST load before it intersects (keyboard / AT).\n   * `#load` releases this listener, so focus never reaches an already-loaded frame.\n   */\n  readonly #onFocus = (): void => this.#load();\n\n  /**\n   * Follows the held URL at runtime: one that arrives arms the frame, one that is\n   * taken away disarms it, so an empty `url` holds no triggers either way.\n   *\n   * Stimulus runs value callbacks before `connect()`, so the connected guard keeps\n   * arming in one place. A frame that already loaded keeps its held URL for the next\n   * re-entry instead of fetching on the spot.\n   */\n  urlValueChanged(): void {\n    if (!this.#connected || this.#loaded) return;\n    if (this.urlValue) this.#arm();\n    else this.#stopObserving();\n  }\n\n  /** Rebuilds the observer when the early-load margin changes at runtime. */\n  rootMarginValueChanged(): void {\n    if (this.#connected && this.#watcher.active) this.#observe();\n  }\n\n  override connect(): void {\n    // `data-lazy-loaded` is the truth source across a cache restore, and `once`\n    // decides whether a restored frame still has anything to watch for.\n    this.#loaded = this.element.hasAttribute(\"data-lazy-loaded\");\n    this.#inside = null;\n    this.#connected = true;\n    if (this.#loaded && this.onceValue) return;\n    this.#arm();\n  }\n\n  override disconnect(): void {\n    this.#connected = false;\n    this.#stopObserving();\n  }\n\n  /** Attaches the triggers that still have a job to do. */\n  #arm(): void {\n    if (!this.urlValue) return;\n    if (!this.#loaded) this.element.addEventListener(\"focusin\", this.#onFocus);\n    this.#observe();\n  }\n\n  #observe(): void {\n    this.#watcher.start(this.element, { rootMargin: this.rootMarginValue });\n  }\n\n  #onIntersect(entries: IntersectionObserverEntry[]): void {\n    for (const entry of entries) {\n      if (entry.isIntersecting) {\n        const returning = this.#inside === false;\n        this.#inside = true;\n        this.#enter(returning);\n      } else if (this.#inside) {\n        // An observer reports where the frame is before it reports any movement,\n        // so only a frame already seen inside can be leaving.\n        this.#inside = false;\n      }\n    }\n  }\n\n  /** Applies an intersecting entry: the first one loads, a return re-fetches. */\n  #enter(returning: boolean): void {\n    if (!this.#loaded) {\n      this.#load();\n      return;\n    }\n    if (this.onceValue || !returning) return;\n    this.#reload();\n  }\n\n  /**\n   * Starts the load by writing the held URL to `src`.\n   *\n   * @stimeoRuntimeOnly `url` is the address this one load fetches and `once` decides whether it\n   *   stops the watcher.\n   */\n  #load(): void {\n    if (!this.urlValue) return;\n    this.#loaded = true;\n    this.element.setAttribute(\"src\", this.urlValue);\n    this.element.setAttribute(\"data-lazy-loaded\", \"true\");\n    this.dispatch(\"load\", { detail: { url: this.urlValue } });\n    // The focus fallback exists to start the first load; it has nothing left to do.\n    this.element.removeEventListener(\"focusin\", this.#onFocus);\n    if (this.onceValue) this.#watcher.stop();\n  }\n\n  /**\n   * Re-entry while `once` is off: fetch the held URL again.\n   *\n   * @stimeoRuntimeOnly `url` is the address this one re-entry reloads.\n   */\n  #reload(): void {\n    const src = this.element.getAttribute(\"src\");\n    if (this.urlValue && this.urlValue !== src) {\n      // The held URL moved on. Writing it to `src` is the fetch, the same start\n      // the first load uses, so it works on any host.\n      this.element.setAttribute(\"src\", this.urlValue);\n      this.dispatch(\"load\", { detail: { url: this.urlValue } });\n      return;\n    }\n    const frame = this.element as HTMLElement & { reload?: () => void };\n    // Refetching the URL already on `src` needs the host's own `reload()`. On a\n    // non-`<turbo-frame>` host there is none, and firing `load` would announce a\n    // fetch that never started.\n    if (typeof frame.reload !== \"function\") return;\n    frame.reload();\n    this.dispatch(\"load\", { detail: { url: src ?? \"\" } });\n  }\n\n  #stopObserving(): void {\n    this.#watcher.stop();\n    this.element.removeEventListener(\"focusin\", this.#onFocus);\n  }\n}\n"]}
+{"version":3,"sources":["../../src/utils/declared_value.ts","../../src/utils/intersection_watcher.ts","../../src/controllers/lazy_frame_controller.ts"],"names":[],"mappings":"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","file":"lazy_frame_controller.js","sourcesContent":["/**\n * Readers for the String Values whose text can only be checked by handing it to\n * a parser: a CSS selector, a regular-expression source, a JSON object.\n *\n * Stimulus reads each of them as an ordinary string, so the controller connects\n * and the flaw surfaces later, inside the first handler that consumes the value\n * (a `SyntaxError` from `new RegExp`, a `DOMException` from the selector engine),\n * where it takes the whole handler down on every event. Parsing here, once, in\n * the `<name>ValueChanged` callback keeps the failure local to the declaration:\n * an unreadable value falls back to its default, the element stays alive, and\n * the hot path only ever receives a value that parsed.\n *\n * Which default a broken declaration falls back to is the caller's contract, so\n * every reader takes (or returns) the fallback rather than choosing one.\n */\n\n/**\n * The result of `parse(raw)`, or `fallback` when `parse` throws.\n *\n * Any exception counts as \"does not parse\": the parsers these Values feed\n * (`RegExp`, `JSON.parse`, the selector engine) all report a malformed input by\n * throwing, and none of them throws for another reason.\n */\nexport function parseDeclared<T>(raw: string, parse: (raw: string) => T, fallback: T): T {\n  try {\n    return parse(raw);\n  } catch {\n    return fallback;\n  }\n}\n\n/** What {@link validSelector} needs of the element it probes with. */\nexport interface SelectorProbe {\n  matches(selector: string): boolean;\n}\n\n/**\n * `raw` when it is a non-empty selector the DOM accepts, otherwise `fallback`.\n *\n * `element.matches` is the probe: the engine parses the selector and throws for\n * one it cannot read. Whether the selector actually matches `element` plays no\n * part, so a selector aimed at another element still passes.\n *\n * The parameter names the one method the probe uses rather than `Element`, so\n * this module carries no DOM type and the readers below stay importable from\n * the Node-side Inspector, which checks the same declarations statically.\n */\nexport function validSelector(element: SelectorProbe, raw: string, fallback: string): string {\n  if (raw.length === 0) return fallback;\n  return parseDeclared(\n    raw,\n    (selector) => {\n      element.matches(selector);\n      return selector;\n    },\n    fallback,\n  );\n}\n\n/** How `compileRegExp` wraps a source before compiling it. */\nexport type RegExpAnchor = \"none\" | \"exact\";\n\n/**\n * `source` compiled as a `RegExp`, or `null` when it does not compile.\n *\n * `\"exact\"` wraps the source as `^(?:source)$`, so the whole input has to match\n * and an alternation inside the source cannot escape the anchors. The source is\n * compiled on its own first, because an unbalanced source can be made to parse\n * by the wrapper's own parentheses — `0)|(1` becomes `^(?:0)|(1)$` — which would\n * accept a declaration that is not a regular expression and leave half of it\n * outside the anchors. The default that replaces a broken source is the\n * caller's, so `null` is returned rather than a fallback pattern.\n */\nexport function compileRegExp(source: string, anchor: RegExpAnchor = \"none\"): RegExp | null {\n  return parseDeclared(\n    source,\n    (text) => {\n      const bare = new RegExp(text);\n      return anchor === \"exact\" ? new RegExp(`^(?:${text})$`) : bare;\n    },\n    null,\n  );\n}\n\n/**\n * The JSON object `raw` declares, or `null` when the text does not parse or\n * parses to something other than a plain object (`null`, an array, a scalar).\n * Values are returned as parsed; narrowing them is the caller's contract.\n */\nexport function parseJsonObject(raw: string): Record<string, unknown> | null {\n  const parsed = parseDeclared<unknown>(raw, (text) => JSON.parse(text), null);\n  if (parsed === null || typeof parsed !== \"object\" || Array.isArray(parsed)) return null;\n  return parsed as Record<string, unknown>;\n}\n","/**\n * Shared `IntersectionObserver` plumbing for Stimeo's scroll-triggered\n * controllers (`intersection`, `scrollspy`, `sticky-observer`, `lazy-frame`).\n *\n * It centralizes the `IntersectionObserver` support guard, root resolution from\n * a selector (degrading to the viewport rather than failing), observer\n * creation/teardown, the **active guard** (the browser may\n * flush a final queued callback batch right after `disconnect()`, and a\n * detached controller must not mutate possibly-cached DOM), and the\n * unobserve→observe **re-arm** that re-delivers the current state even when the\n * target never leaves the viewport.\n *\n * Like `RovingTabindex` and `FocusTrap`, this is a policy-free internal\n * util: what an intersection *means* (a spied link, a stuck header, a lazy\n * load) stays in each controller. The public `stimeo--intersection` controller\n * is its thin declarative face.\n */\n\nimport { parseDeclared } from \"./declared_value\";\n\n/**\n * Whether `entry`'s target sits entirely before the root's **start (top)** edge —\n * the \"scrolled past the top\" half of a non-intersecting entry, as opposed to\n * \"not reached yet\" below the root.\n *\n * A target with no layout box (`display: none`, a `hidden` ancestor, a collapsed\n * `<details>`) is reported with an **empty rect**, whose `bottom` of `0` would\n * otherwise satisfy `bottom <= rootTop` for a viewport root and read as \"passed\"\n * even though the target was never scrolled anywhere. An empty rect carries no\n * position at all, so it is deliberately never \"before the edge\"; what a caller\n * publishes for that case is its own policy (both consumers treat it as the\n * neutral \"not passed\"/\"not stuck\", and the real rect that arrives once the\n * target is laid out re-establishes the true state).\n */\nexport function isBeforeRootStart(entry: IntersectionObserverEntry): boolean {\n  const rect = entry.boundingClientRect;\n  if (rect.width === 0 && rect.height === 0) return false;\n  // rootBounds is null for a cross-origin/removed root; fall back to the\n  // viewport origin.\n  const rootTop = entry.rootBounds?.top ?? 0;\n  return rect.bottom <= rootTop;\n}\n\n/**\n * Resolves an observation root from a selector. Every reading of \"no root\" ends\n * at the same place — absent, matching nothing, or not parsing at all (a typo in\n * a data attribute) — so the observation falls back to the viewport instead of\n * leaving the caller inert with no state hooks published at all.\n */\nfunction queryRoot(selector: string | undefined): Element | null {\n  if (!selector) return null;\n  return parseDeclared(selector, (raw) => document.querySelector(raw), null);\n}\n\nexport interface IntersectionWatchOptions {\n  /**\n   * The observation root. Pass an element (or `null` for the viewport) when\n   * the caller already resolved it; omit to resolve from `rootSelector`.\n   */\n  root?: Element | null;\n  /**\n   * Selector for the observation root; empty/omitted = viewport. A selector\n   * that matches nothing or does not parse also means the viewport.\n   */\n  rootSelector?: string;\n  rootMargin?: string;\n  threshold?: number | number[];\n}\n\nexport class IntersectionWatcher {\n  readonly #onEntries: (entries: IntersectionObserverEntry[]) => void;\n  #observer: IntersectionObserver | null = null;\n  #active = false;\n  #usingPlatformDefaults = false;\n\n  constructor(onEntries: (entries: IntersectionObserverEntry[]) => void) {\n    this.#onEntries = onEntries;\n  }\n\n  /** Whether an observer is live (started, `IntersectionObserver` supported). */\n  get active(): boolean {\n    return this.#active;\n  }\n\n  /** Whether the live observer discarded configured options after construction failed. */\n  get usingPlatformDefaults(): boolean {\n    return this.#usingPlatformDefaults;\n  }\n\n  /**\n   * (Re)creates the observer and observes `targets`. Returns `false` — leaving\n   * the watcher inert — without `IntersectionObserver` support (very old\n   * browsers; the caller's no-JS fallback stays in charge) or with no targets.\n   * If initial construction with the configured options fails, the watcher\n   * warns and retries once with the same root and platform defaults. A\n   * `rootSelector` that does not parse resolves to the viewport (see\n   * {@link IntersectionWatchOptions.rootSelector}), so a typo never fails the\n   * call.\n   *\n   * @throws The fallback constructor error if both construction attempts fail,\n   *   or whatever the platform throws from `observe()`. The exception is passed\n   *   through unchanged, but the watcher rolls back first: every target observed\n   *   so far is released and `active` stays `false`, so a caller that retries\n   *   starts from a clean slate.\n   */\n  start(targets: Element | readonly Element[], options: IntersectionWatchOptions = {}): boolean {\n    this.stop();\n    if (typeof IntersectionObserver === \"undefined\") return false;\n    const list = Array.isArray(targets) ? (targets as readonly Element[]) : [targets as Element];\n    if (list.length === 0) return false;\n\n    const root = \"root\" in options ? (options.root ?? null) : queryRoot(options.rootSelector);\n\n    let observer: IntersectionObserver | null = null;\n    try {\n      const onEntries = (entries: IntersectionObserverEntry[]): void => {\n        // Identity matters across an immediate restart: the old observer can\n        // flush a queued batch after the new observer has made `active` true.\n        if (this.#active && this.#observer === observer) this.#onEntries(entries);\n      };\n      try {\n        observer = new IntersectionObserver(onEntries, {\n          root,\n          rootMargin: options.rootMargin,\n          threshold: options.threshold,\n        });\n      } catch (error) {\n        console.warn(\n          \"Stimeo UI: IntersectionObserver could not be constructed with the configured options; retrying with platform defaults.\",\n          error,\n        );\n        observer = new IntersectionObserver(onEntries, { root });\n        this.#usingPlatformDefaults = true;\n      }\n      for (const target of list) observer.observe(target);\n      this.#observer = observer;\n      this.#active = true;\n      return true;\n    } catch (error) {\n      // A constructor or partial observe failure must not leave earlier targets\n      // observed or report an active watcher. Preserve the platform exception.\n      observer?.disconnect();\n      this.#observer = null;\n      this.#active = false;\n      this.#usingPlatformDefaults = false;\n      throw error;\n    }\n  }\n\n  /**\n   * Re-delivers `target`'s CURRENT intersection state: `IntersectionObserver`\n   * only reports *changes*, but `observe()` always reports the present state,\n   * so unobserve→observe turns \"still intersecting\" into a fresh callback.\n   *\n   * @throws Whatever `unobserve()`/`observe()` throws. The watcher is stopped\n   *   first, so it never stays live with a half-rearmed target.\n   */\n  rearm(target: Element): void {\n    if (!this.#observer) return;\n    try {\n      this.#observer.unobserve(target);\n      this.#observer.observe(target);\n    } catch (error) {\n      this.stop();\n      throw error;\n    }\n  }\n\n  /** Severs the observer; late queued callbacks become no-ops via the guard. */\n  stop(): void {\n    this.#active = false;\n    this.#observer?.disconnect();\n    this.#observer = null;\n    this.#usingPlatformDefaults = false;\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { IntersectionWatcher } from \"../utils/intersection_watcher\";\n\n/**\n * Headless **lazy frame**: defers a `<turbo-frame>`'s load until it nears the viewport\n * (or focus reaches it), to keep the initial render light. Turbo's own `loading=\"lazy\"`\n * observes with no margin, so the frame loads only once it is already in view; this\n * drives an explicit `IntersectionObserver` with a configurable `rootMargin`, plus a focus fallback so keyboard /\n * assistive-tech users trigger the load too (no APG pattern).\n *\n * Markup contract (identifier: `stimeo--lazy-frame`):\n *   <turbo-frame id=\"comments\" data-controller=\"stimeo--lazy-frame\"\n *     data-stimeo--lazy-frame-url-value=\"/posts/1/comments\"\n *     data-stimeo--lazy-frame-root-margin-value=\"200px\">Loading…</turbo-frame>\n *\n * The URL is *held* in the `url` value (not on `src`) so Turbo does not load it eagerly;\n * when the frame intersects (within `rootMargin`) or focus enters it, the controller\n * writes `url` to `src` — **writing `src` is what starts the fetch** — marks\n * `data-lazy-loaded`, and emits `load`. Focus is the fallback for the *first* load only;\n * once the frame has loaded, its listener is released and further focus moves inside the\n * frame change nothing.\n *\n * With `once` (default) the controller then stops observing. With `once` off it keeps\n * watching and re-fetches on a **re-entry** — the frame has to be seen inside the\n * observed area, leave it, and come back. Where a connection first finds the frame is the\n * baseline rather than a movement, so a focus-started load and a cache restore each begin\n * the visit wherever the frame sits — in view or out of it — and re-fetch nothing until it\n * leaves and returns. A re-entry serves the held `url`: when it still matches `src`, the\n * host's own `reload()` refetches it; when it has moved on, writing the new `url` to `src`\n * is the fetch.\n *\n * `load` dispatches `{ url }` — always the URL the fetch actually started for.\n *\n * `once` follows a runtime change for a frame that has loaded: turned off, the frame is\n * observed again and the visit begins wherever the observer first finds it, exactly as on a\n * reconnect; turned on, observing stops. Before the first load it has nothing to change,\n * because it only decides what that load leaves behind.\n *\n * @remarks\n * Behavior only — the load itself and the frame's content are Turbo's / the server's job,\n * and the loading UI (skeleton / `aria-busy`) belongs to `stimeo--frame-loading`. The trigger\n * is idempotent (`data-lazy-loaded` guards a double load and is the truth source on a\n * Turbo cache restore: a restored frame is observed again only while `once` is off, which\n * is the mode that asked to keep re-fetching). An empty `url` arms nothing and is never\n * written to `src`. The `IntersectionObserver` and focus listener are released once loaded\n * (when `once`) and on `disconnect()` (Turbo navigation included).\n */\nexport class LazyFrameController extends Controller<HTMLElement> {\n  static override values = {\n    url: { type: String, default: \"\" },\n    rootMargin: { type: String, default: \"0px\" },\n    once: { type: Boolean, default: true },\n  };\n  static events = [\"load\"] as const;\n\n  declare urlValue: string;\n  declare rootMarginValue: string;\n  declare onceValue: boolean;\n\n  /** Shared IO plumbing (support guard, active guard, teardown). */\n  readonly #watcher = new IntersectionWatcher((entries) => this.#onIntersect(entries));\n  #connected = false;\n  #loaded = false;\n  /**\n   * Whether the observer last saw the frame inside the observed area — `null`\n   * until it has reported. A re-entry needs a frame that was seen inside and\n   * then left, so an unknown position is never a departure.\n   */\n  #inside: boolean | null = null;\n\n  /**\n   * Focus reaching the frame starts the FIRST load before it intersects (keyboard / AT).\n   * `#load` releases this listener, so focus never reaches an already-loaded frame.\n   */\n  readonly #onFocus = (): void => this.#load();\n\n  /**\n   * Follows the held URL at runtime: one that arrives arms the frame, one that is\n   * taken away disarms it, so an empty `url` holds no triggers either way.\n   *\n   * Stimulus runs value callbacks before `connect()`, so the connected guard keeps\n   * arming in one place. A frame that already loaded keeps its held URL for the next\n   * re-entry instead of fetching on the spot.\n   */\n  urlValueChanged(): void {\n    if (!this.#connected || this.#loaded) return;\n    if (this.urlValue) this.#arm();\n    else this.#stopObserving();\n  }\n\n  /** Rebuilds the observer when the early-load margin changes at runtime. */\n  rootMarginValueChanged(): void {\n    if (this.#connected && this.#watcher.active) this.#observe();\n  }\n\n  /**\n   * Follows `once` for a frame that has loaded, reaching the observer a reconnect\n   * would build: a loaded frame under `once` is left unobserved, and one that may\n   * re-fetch is observed with its baseline taken afresh, so the first report is\n   * where the frame is rather than a return to it.\n   *\n   * Stimulus can deliver this ahead of `connect()`, and `#loaded` may still hold\n   * the previous connection's answer then; the connected guard keeps a callback\n   * outside the connected window from building anything.\n   */\n  onceValueChanged(): void {\n    if (!this.#connected || !this.#loaded) return;\n    if (this.onceValue) {\n      this.#watcher.stop();\n    } else if (!this.#watcher.active) {\n      this.#inside = null;\n      this.#arm();\n    }\n  }\n\n  override connect(): void {\n    // `data-lazy-loaded` is the truth source across a cache restore, and `once`\n    // decides whether a restored frame still has anything to watch for.\n    this.#loaded = this.element.hasAttribute(\"data-lazy-loaded\");\n    this.#inside = null;\n    this.#connected = true;\n    if (this.#loaded && this.onceValue) return;\n    this.#arm();\n  }\n\n  override disconnect(): void {\n    this.#connected = false;\n    this.#stopObserving();\n  }\n\n  /** Attaches the triggers that still have a job to do. */\n  #arm(): void {\n    if (!this.urlValue) return;\n    if (!this.#loaded) this.element.addEventListener(\"focusin\", this.#onFocus);\n    this.#observe();\n  }\n\n  #observe(): void {\n    this.#watcher.start(this.element, { rootMargin: this.rootMarginValue });\n  }\n\n  #onIntersect(entries: IntersectionObserverEntry[]): void {\n    for (const entry of entries) {\n      if (entry.isIntersecting) {\n        const returning = this.#inside === false;\n        this.#inside = true;\n        this.#enter(returning);\n      } else if (this.#inside) {\n        // An observer reports where the frame is before it reports any movement,\n        // so only a frame already seen inside can be leaving.\n        this.#inside = false;\n      }\n    }\n  }\n\n  /** Applies an intersecting entry: the first one loads, a return re-fetches. */\n  #enter(returning: boolean): void {\n    if (!this.#loaded) {\n      this.#load();\n      return;\n    }\n    if (this.onceValue || !returning) return;\n    this.#reload();\n  }\n\n  /**\n   * Starts the load by writing the held URL to `src`.\n   *\n   * @stimeoRuntimeOnly `url` is the address this one load fetches and `once` decides whether it\n   *   stops the watcher.\n   */\n  #load(): void {\n    if (!this.urlValue) return;\n    this.#loaded = true;\n    this.element.setAttribute(\"src\", this.urlValue);\n    this.element.setAttribute(\"data-lazy-loaded\", \"true\");\n    this.dispatch(\"load\", { detail: { url: this.urlValue } });\n    // The focus fallback exists to start the first load; it has nothing left to do.\n    this.element.removeEventListener(\"focusin\", this.#onFocus);\n    if (this.onceValue) this.#watcher.stop();\n  }\n\n  /**\n   * Re-entry while `once` is off: fetch the held URL again.\n   *\n   * @stimeoRuntimeOnly `url` is the address this one re-entry reloads.\n   */\n  #reload(): void {\n    const src = this.element.getAttribute(\"src\");\n    if (this.urlValue && this.urlValue !== src) {\n      // The held URL moved on. Writing it to `src` is the fetch, the same start\n      // the first load uses, so it works on any host.\n      this.element.setAttribute(\"src\", this.urlValue);\n      this.dispatch(\"load\", { detail: { url: this.urlValue } });\n      return;\n    }\n    const frame = this.element as HTMLElement & { reload?: () => void };\n    // Refetching the URL already on `src` needs the host's own `reload()`. On a\n    // non-`<turbo-frame>` host there is none, and firing `load` would announce a\n    // fetch that never started.\n    if (typeof frame.reload !== \"function\") return;\n    frame.reload();\n    this.dispatch(\"load\", { detail: { url: src ?? \"\" } });\n  }\n\n  #stopObserving(): void {\n    this.#watcher.stop();\n    this.element.removeEventListener(\"focusin\", this.#onFocus);\n  }\n}\n"]}

package/dist/controllers/listbox_controller.d.ts

@@ -35,6 +35,15 @@ import { Controller } from '@hotwired/stimulus';
  * — the shape of `change`, with `option: null` and `value: ""` once nothing is
  * selected — when the page moves the selection instead.
  *
+ * User `change` reports compare the resulting state with the last published
+ * state. A pending page write handled in the same script joins that confirmation;
+ * a browser-delivered listener may settle it first as `reconcile`. Confirming
+ * the last published state reports nothing.
+ *
+ * A synchronous subscriber that confirms another state replaces reports still
+ * pending for the outer confirmation. Reading state or confirming it unchanged
+ * does not replace them. An event already being dispatched cannot be recalled.
+ *
  * @remarks
  * Behavior only. Static placement is the consumer's CSS; dynamic placement is
  * delegated to the opt-in `stimeo-ui/positioning` module. The look is keyed off
@@ -82,8 +91,10 @@ declare class ListboxController extends Controller<HTMLElement> {
     static actions: readonly ["close", "onTriggerKeydown", "open", "select", "toggle"];
     static events: readonly ["change", "reconcile"];
     readonly triggerTarget: HTMLElement;
+    readonly triggerTargets: HTMLElement[];
     readonly valueTarget: HTMLElement;
     readonly listTarget: HTMLElement;
+    readonly listTargets: HTMLElement[];
     readonly optionTargets: HTMLElement[];
     readonly fieldTarget: HTMLInputElement;
     readonly hasTriggerTarget: boolean;
@@ -106,10 +117,31 @@ declare class ListboxController extends Controller<HTMLElement> {
      * active option among the surviving targets once the batch is in.
      */
     optionTargetDisconnected(option: HTMLElement): void;
+    /** Brings a trigger inserted or replaced at runtime to the open state. */
+    triggerTargetConnected(): void;
+    /**
+     * Gives a trigger that is no longer a target back the `aria-expanded` and
+     * `aria-activedescendant` its markup carried, unless the page rewrote them after this
+     * listbox did, and brings the trigger that stays to the open state.
+     */
+    triggerTargetDisconnected(trigger: HTMLElement): void;
+    /** Brings a list inserted or replaced at runtime to the open state. */
+    listTargetConnected(): void;
+    /**
+     * Gives a list that is no longer a target back the `hidden` its markup carried, unless
+     * the page rewrote it after this listbox did, and brings the list that stays to the
+     * open state. A departing list this listbox opened, found hidden, was closed by the
+     * page; that is read before its own `hidden` comes back.
+     */
+    listTargetDisconnected(list: HTMLElement): void;
     /** Fills a form field inserted or replaced at runtime with the current selection. */
     fieldTargetConnected(): void;
+    /** Brings the field that stays to the current selection when an earlier one leaves. */
+    fieldTargetDisconnected(): void;
     /** Writes the current selection into a trigger value inserted or replaced at runtime. */
     valueTargetConnected(): void;
+    /** Brings the trigger value that stays to the current selection when an earlier one leaves. */
+    valueTargetDisconnected(): void;
     /**
      * Re-renders the empty-selection label when application code (or a Turbo morph)
      * changes `placeholder` at runtime.
@@ -128,8 +160,8 @@ declare class ListboxController extends Controller<HTMLElement> {
     toggle(event: MouseEvent): void;
     /** Yields claimed keys; otherwise routes the APG select-only keyboard model. */
     onTriggerKeydown(event: KeyboardEvent): void;
-    /** Selects the clicked option and closes, returning focus to the trigger. */
-    select(event: Event): void;
+    /** Selects an owned option and closes; element calls return focus only from inside. */
+    select(source: Event | HTMLElement): void;
     /** Opens the list and activates the selected option (else the first). */
     open(): void;
     /** Closes the list, clears the active option, and resets the typeahead buffer. */