stimeo-ui 0.15.0 → 0.16.0

package/dist/controllers/intersection_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/declared_value.ts","../../src/utils/intersection_watcher.ts","../../src/controllers/intersection_controller.ts"],"names":[],"mappings":"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","file":"intersection_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, isBeforeRootStart } from \"../utils/intersection_watcher\";\n\n/** Name of the CSS custom property exposing the visible ratio (0..1). */\nconst RATIO_PROPERTY = \"--stimeo--intersection-ratio\";\n\n/**\n * Tolerance for the visibility test. Real observers can report a ratio a hair\n * below the configured threshold at that threshold's own crossing callback\n * (fractional device pixels / zoom), most visibly at threshold 1 where \"fully\n * visible\" may arrive as 0.99x — a strict `>=` would then never see it.\n */\nconst RATIO_EPSILON = 0.01;\n\n/**\n * Headless **intersection primitive**: a thin declarative wrapper over\n * {@link IntersectionObserver} that turns viewport visibility into events and\n * state hooks. It is the scroll-triggered building block for\n * scroll-driven behavior — loading more on approach, \"animate when visible\"\n * (compose it with `stimeo--count-up`), progress and sticky-header work — so a\n * consumer does not write its own observer. No APG widget — a pure\n * state-detection utility. Core (zero dependencies).\n *\n * Markup contract (identifier: `stimeo--intersection`):\n *   <div data-controller=\"stimeo--intersection\"\n *        data-stimeo--intersection-root-margin-value=\"200px\"\n *        data-action=\"stimeo--intersection:enter->feed#loadNextPage\"></div>\n *\n * The controller observes its own element. `enter` fires when the element\n * becomes visible (intersection ratio reaches `threshold`; detail `{ ratio }`),\n * `exit` when it leaves (detail `{ ratio, position }`, where `position` is the\n * edge it left across — `\"before\"` = upward past the root's start edge,\n * `\"after\"` = downward, still ahead), `change` on every observed update\n * (detail `{ intersecting, ratio }` — set `ratioSteps` for fine-grained ratio\n * reporting), and `passed` when the element fully crosses the root's start edge\n * in either direction (detail `{ passed }` — the sticky/progress line). The\n * visibility is mirrored as `data-intersecting`/`data-passed` and the ratio as\n * the `--stimeo--intersection-ratio` custom property for consumer CSS.\n *\n * @remarks\n * Behavior only — what visibility *means* (load a page, start an animation,\n * pin a header) belongs to the consumer via `data-action`/CSS. `connect()` is\n * idempotent: the previous state is read back from `data-intersecting`/\n * `data-passed`, so a Turbo cache restore does not re-fire `enter` for an\n * element that was already visible (and with `once`, an element whose enter\n * already fired is not observed again). `threshold` is re-read when Turbo morphs\n * the attribute in place, and a `rootSelector` that does not parse observes the\n * viewport rather than leaving the element unobserved. Without\n * `IntersectionObserver` (very old browsers) the controller stays inert —\n * consumers keep whatever no-JS fallback their markup provides. The observer is\n * disconnected on `disconnect()` (Turbo navigation included).\n */\nexport class IntersectionController extends Controller<HTMLElement> {\n  static override values = {\n    threshold: { type: Number, default: 0 },\n    ratioSteps: { type: Number, default: 0 },\n    rootMargin: { type: String, default: \"0px\" },\n    rootSelector: { type: String, default: \"\" },\n    once: { type: Boolean, default: false },\n  };\n  static actions = [\"refresh\"] as const;\n  static events = [\"enter\", \"exit\", \"change\", \"passed\"] as const;\n\n  declare thresholdValue: number;\n  declare ratioStepsValue: number;\n  declare rootMarginValue: string;\n  declare rootSelectorValue: string;\n  declare onceValue: boolean;\n\n  /** Shared IO plumbing (support guard, root resolution, active guard, re-arm). */\n  readonly #watcher = new IntersectionWatcher((entries) => this.#onIntersect(entries));\n  /** Threshold actually installed in the live observer (0 after option fallback). */\n  #effectiveThreshold = 0;\n  /** Bumped by `refresh()`: an in-flight batch becomes stale and stops. */\n  #generation = 0;\n\n  #onIntersect(entries: IntersectionObserverEntry[]): void {\n    // A single callback can batch several transitions for the same target\n    // (delivery lagging behind a fast scroll), so process every entry in\n    // order — collapsing to the last one alone would drop an enter→exit pair\n    // and, under `once`, lose the one-shot enter entirely. If a handler calls\n    // `refresh()` mid-batch (enter → append content → re-arm), the remaining\n    // entries describe a state `refresh` just reset — replaying them would\n    // re-fire `enter` for the same visibility episode — so the generation\n    // bump abandons them and the re-observation delivers the fresh state\n    // (`once` stopping the watcher mid-batch is caught by the active check).\n    const generation = this.#generation;\n    for (const entry of entries) {\n      if (!this.#watcher.active || this.#generation !== generation) return;\n\n      const ratio = entry.intersectionRatio;\n      // `isIntersecting` is geometric (\"any overlap\"), so a non-zero `threshold`\n      // (\"counts as visible at ≥N%\") must be applied to the ratio ourselves —\n      // against the same 0..1-clamped value the observer was configured with, or\n      // a `threshold` above 1 would make `intersecting` unreachable while the\n      // observer still fires at ratio 1. The epsilon absorbs subpixel rounding\n      // (see RATIO_EPSILON); keeping the geometric `isIntersecting` conjunct\n      // stops it from underflowing a tiny threshold into \"always visible\".\n      // A constructor fallback omits the configured threshold, so the observer\n      // can only notify at its effective default line (0). Applying the authored\n      // line here would wait for a callback that the fallback observer never\n      // schedules after an initially intersecting entry.\n      const threshold = this.#effectiveThreshold;\n      const intersecting =\n        threshold > 0\n          ? entry.isIntersecting && ratio >= threshold - RATIO_EPSILON\n          : entry.isIntersecting;\n\n      this.element.style.setProperty(RATIO_PROPERTY, String(ratio));\n      this.dispatch(\"change\", { detail: { intersecting, ratio } });\n      this.#syncIntersecting(intersecting, ratio, entry);\n      this.#syncPassed(!intersecting && isBeforeRootStart(entry));\n    }\n  }\n\n  override connect(): void {\n    // A cache restore may bring back an element whose one-shot enter already\n    // fired; honor it instead of re-observing (mirrors `data-lazy-loaded`).\n    if (this.onceValue && this.element.getAttribute(\"data-intersecting\") === \"true\") return;\n    this.#observe();\n  }\n\n  override disconnect(): void {\n    this.#watcher.stop();\n  }\n\n  /**\n   * Re-reads the visibility line and rebuilds the observer. Turbo 8 morphing\n   * rewrites the attribute in place without a reconnect, and the line is what\n   * the intersection callback compares every ratio against, so a value frozen at\n   * connect time would decide `data-intersecting` wrongly for the rest of the\n   * page's life. Nothing to rebuild before the first `connect()`; after a spent\n   * one-shot the watcher is deliberately stopped, and re-observing would deliver\n   * the current state and fire `enter` a second time.\n   */\n  thresholdValueChanged(): void {\n    if (this.#watcher.active) this.#observe();\n  }\n\n  /** (Re)installs the observer from the current Values. */\n  #observe(): void {\n    this.#effectiveThreshold = this.#clampedThreshold();\n    this.#watcher.start(this.element, {\n      rootSelector: this.rootSelectorValue,\n      rootMargin: this.rootMarginValue,\n      threshold: this.#thresholds(),\n    });\n    if (this.#watcher.usingPlatformDefaults) this.#effectiveThreshold = 0;\n  }\n\n  /**\n   * Re-delivers the current intersection state as a fresh transition. Bound via\n   * `data-action` (e.g. `my-feed:appended@window->stimeo--intersection#refresh`).\n   *\n   * `IntersectionObserver` only reports state *changes*, so a sentinel that\n   * stays visible while content is appended below it never fires `enter` again\n   * and a hand-rolled infinite scroll stalls. `observe()` always delivers the\n   * current state, and clearing the recorded `data-intersecting`/`data-passed`\n   * makes that delivery count as a transition — a still-visible sentinel\n   * re-fires `enter`. No-op once the observer is gone (`once` fired, no\n   * `IntersectionObserver` support, or after `disconnect()`).\n   */\n  refresh(): void {\n    if (!this.#watcher.active) return;\n    this.#generation += 1;\n    this.element.removeAttribute(\"data-intersecting\");\n    this.element.removeAttribute(\"data-passed\");\n    this.#watcher.rearm(this.element);\n  }\n\n  /**\n   * Reflects the visibility onto `data-intersecting` and fires `enter`/`exit`\n   * on transitions. The previous state is the DOM attribute (source of truth),\n   * so the observer's initial callback fires `enter` for an element that starts\n   * visible but stays silent after a cache restore that already recorded it.\n   * An initial not-visible state is established silently (no `exit`).\n   */\n  #syncIntersecting(intersecting: boolean, ratio: number, entry: IntersectionObserverEntry): void {\n    const previous = this.element.getAttribute(\"data-intersecting\");\n    this.element.setAttribute(\"data-intersecting\", intersecting ? \"true\" : \"false\");\n\n    if (intersecting && previous !== \"true\") {\n      // One-shot mode: the shot is spent at this transition, so stop observing\n      // before the event. A handler that re-arms (the `enter` -> append ->\n      // `refresh()` reflex) then finds an inactive watcher and leaves the hooks\n      // in their final state — `data-intersecting=\"true\"` marks it for reconnects.\n      if (this.onceValue) this.#watcher.stop();\n      this.dispatch(\"enter\", { detail: { ratio } });\n    } else if (!intersecting && previous === \"true\") {\n      this.dispatch(\"exit\", {\n        detail: { ratio, position: this.#leftViaStartEdge(entry) ? \"before\" : \"after\" },\n      });\n    }\n  }\n\n  /**\n   * Which edge the element left across, for the `exit` detail. A non-zero\n   * `threshold` withdraws visibility while the element still overlaps the root,\n   * so the leaving rect can straddle the start edge — the direction is the\n   * element's own top against that edge, not whether it has cleared the root\n   * entirely (that is what `passed` reports). An element with no layout box\n   * (`display: none`, a collapsed `<details>`) is reported with an empty rect\n   * that carries no position at all, so it is deliberately neither direction\n   * and takes the \"still ahead\" reading.\n   */\n  #leftViaStartEdge(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    return rect.top < (entry.rootBounds?.top ?? 0);\n  }\n\n  /**\n   * Reflects the \"scrolled past\" state onto `data-passed` and fires `passed` on\n   * transitions — the line sticky headers and reading progress key off. Like\n   * `enter`, an initial `passed=true` (page restored mid-scroll) fires; the\n   * initial `false` is established silently.\n   */\n  #syncPassed(passed: boolean): void {\n    const previous = this.element.getAttribute(\"data-passed\");\n    this.element.setAttribute(\"data-passed\", passed ? \"true\" : \"false\");\n    const changed = previous === null ? passed : (previous === \"true\") !== passed;\n    if (changed) this.dispatch(\"passed\", { detail: { passed } });\n  }\n\n  /** The configured `threshold`, clamped to the 0..1 the observer accepts. */\n  #clampedThreshold(): number {\n    return Math.min(1, Math.max(0, this.thresholdValue));\n  }\n\n  /**\n   * Observer thresholds: the `threshold` line itself, plus `ratioSteps` evenly\n   * spaced steps when fine-grained `change` ratios are wanted (progress bars).\n   *\n   * 0 is always observed. An observer notifies only at the lines it was given,\n   * so a non-zero `threshold` on its own delivers its last callback while the\n   * element is still partly visible: the element leaving for good would never be\n   * reported, freezing the ratio and `data-passed` mid-departure.\n   */\n  #thresholds(): number[] {\n    const thresholds = new Set<number>([0, this.#clampedThreshold()]);\n    if (this.ratioStepsValue > 0) {\n      // i counts up to ratioSteps, so i/ratioSteps is inherently 0..1.\n      for (let i = 0; i <= this.ratioStepsValue; i += 1) {\n        thresholds.add(i / this.ratioStepsValue);\n      }\n    }\n    return [...thresholds].sort((a, b) => a - b);\n  }\n}\n"]}
+{"version":3,"sources":["../../src/utils/declared_value.ts","../../src/utils/intersection_watcher.ts","../../src/controllers/intersection_controller.ts"],"names":[],"mappings":"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","file":"intersection_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, isBeforeRootStart } from \"../utils/intersection_watcher\";\n\n/** Name of the CSS custom property exposing the visible ratio (0..1). */\nconst RATIO_PROPERTY = \"--stimeo--intersection-ratio\";\n\n/**\n * Tolerance for the visibility test. Real observers can report a ratio a hair\n * below the configured threshold at that threshold's own crossing callback\n * (fractional device pixels / zoom), most visibly at threshold 1 where \"fully\n * visible\" may arrive as 0.99x — a strict `>=` would then never see it.\n */\nconst RATIO_EPSILON = 0.01;\n\n/**\n * Headless **intersection primitive**: a thin declarative wrapper over\n * {@link IntersectionObserver} that turns viewport visibility into events and\n * state hooks. It is the scroll-triggered building block for\n * scroll-driven behavior — loading more on approach, \"animate when visible\"\n * (compose it with `stimeo--count-up`), progress and sticky-header work — so a\n * consumer does not write its own observer. No APG widget — a pure\n * state-detection utility. Core (zero dependencies).\n *\n * Markup contract (identifier: `stimeo--intersection`):\n *   <div data-controller=\"stimeo--intersection\"\n *        data-stimeo--intersection-root-margin-value=\"200px\"\n *        data-action=\"stimeo--intersection:enter->feed#loadNextPage\"></div>\n *\n * The controller observes its own element. `enter` fires when the element\n * becomes visible (intersection ratio reaches `threshold`; detail `{ ratio }`),\n * `exit` when it leaves (detail `{ ratio, position }`, where `position` is the\n * edge it left across — `\"before\"` = upward past the root's start edge,\n * `\"after\"` = downward, still ahead), `change` on every observed update\n * (detail `{ intersecting, ratio }` — set `ratioSteps` for fine-grained ratio\n * reporting), and `passed` when the element fully crosses the root's start edge\n * in either direction (detail `{ passed }` — the sticky/progress line). The\n * visibility is mirrored as `data-intersecting`/`data-passed` and the ratio as\n * the `--stimeo--intersection-ratio` custom property for consumer CSS.\n *\n * @remarks\n * Behavior only — what visibility *means* (load a page, start an animation,\n * pin a header) belongs to the consumer via `data-action`/CSS. `connect()` is\n * idempotent: the previous state is read back from `data-intersecting`/\n * `data-passed`, so a Turbo cache restore does not re-fire `enter` for an\n * element that was already visible (and with `once`, an element whose enter\n * already fired is not observed again). `threshold` is re-read when Turbo morphs\n * the attribute in place, and a `rootSelector` that does not parse observes the\n * viewport rather than leaving the element unobserved. Without\n * `IntersectionObserver` (very old browsers) the controller stays inert —\n * consumers keep whatever no-JS fallback their markup provides. The observer is\n * disconnected on `disconnect()` (Turbo navigation included).\n */\nexport class IntersectionController extends Controller<HTMLElement> {\n  static override values = {\n    threshold: { type: Number, default: 0 },\n    ratioSteps: { type: Number, default: 0 },\n    rootMargin: { type: String, default: \"0px\" },\n    rootSelector: { type: String, default: \"\" },\n    once: { type: Boolean, default: false },\n  };\n  static actions = [\"refresh\"] as const;\n  static events = [\"enter\", \"exit\", \"change\", \"passed\"] as const;\n\n  declare thresholdValue: number;\n  declare ratioStepsValue: number;\n  declare rootMarginValue: string;\n  declare rootSelectorValue: string;\n  declare onceValue: boolean;\n\n  /** Shared IO plumbing (support guard, root resolution, active guard, re-arm). */\n  readonly #watcher = new IntersectionWatcher((entries) => this.#onIntersect(entries));\n  /** Threshold actually installed in the live observer (0 after option fallback). */\n  #effectiveThreshold = 0;\n  /** Bumped by `refresh()`: an in-flight batch becomes stale and stops. */\n  #generation = 0;\n\n  #onIntersect(entries: IntersectionObserverEntry[]): void {\n    // A single callback can batch several transitions for the same target\n    // (delivery lagging behind a fast scroll), so process every entry in\n    // order — collapsing to the last one alone would drop an enter→exit pair\n    // and, under `once`, lose the one-shot enter entirely. If a handler calls\n    // `refresh()` mid-batch (enter → append content → re-arm), the remaining\n    // entries describe a state `refresh` just reset — replaying them would\n    // re-fire `enter` for the same visibility episode — so the generation\n    // bump abandons them and the re-observation delivers the fresh state\n    // (`once` stopping the watcher mid-batch is caught by the active check).\n    const generation = this.#generation;\n    for (const entry of entries) {\n      if (!this.#watcher.active || this.#generation !== generation) return;\n\n      const ratio = entry.intersectionRatio;\n      // `isIntersecting` is geometric (\"any overlap\"), so a non-zero `threshold`\n      // (\"counts as visible at ≥N%\") must be applied to the ratio ourselves —\n      // against the same 0..1-clamped value the observer was configured with, or\n      // a `threshold` above 1 would make `intersecting` unreachable while the\n      // observer still fires at ratio 1. The epsilon absorbs subpixel rounding\n      // (see RATIO_EPSILON); keeping the geometric `isIntersecting` conjunct\n      // stops it from underflowing a tiny threshold into \"always visible\".\n      // A constructor fallback omits the configured threshold, so the observer\n      // can only notify at its effective default line (0). Applying the authored\n      // line here would wait for a callback that the fallback observer never\n      // schedules after an initially intersecting entry.\n      const threshold = this.#effectiveThreshold;\n      const intersecting =\n        threshold > 0\n          ? entry.isIntersecting && ratio >= threshold - RATIO_EPSILON\n          : entry.isIntersecting;\n\n      this.element.style.setProperty(RATIO_PROPERTY, String(ratio));\n      this.dispatch(\"change\", { detail: { intersecting, ratio } });\n      this.#syncIntersecting(intersecting, ratio, entry);\n      this.#syncPassed(!intersecting && isBeforeRootStart(entry));\n    }\n  }\n\n  override connect(): void {\n    // A cache restore may bring back an element whose one-shot enter already\n    // fired; honor it instead of re-observing (mirrors `data-lazy-loaded`).\n    if (this.onceValue && this.element.getAttribute(\"data-intersecting\") === \"true\") return;\n    this.#observe();\n  }\n\n  override disconnect(): void {\n    this.#watcher.stop();\n  }\n\n  /**\n   * Re-reads the visibility line and rebuilds the observer. Turbo 8 morphing\n   * rewrites the attribute in place without a reconnect, and the line is what\n   * the intersection callback compares every ratio against, so a value frozen at\n   * connect time would decide `data-intersecting` wrongly for the rest of the\n   * page's life. Nothing to rebuild before the first `connect()`; after a spent\n   * one-shot the watcher is deliberately stopped, and re-observing would deliver\n   * the current state and fire `enter` a second time.\n   */\n  thresholdValueChanged(): void {\n    if (this.#watcher.active) this.#observe();\n  }\n\n  /** (Re)installs the observer from the current Values. */\n  #observe(): void {\n    this.#effectiveThreshold = this.#clampedThreshold();\n    this.#watcher.start(this.element, {\n      rootSelector: this.rootSelectorValue,\n      rootMargin: this.rootMarginValue,\n      threshold: this.#thresholds(),\n    });\n    if (this.#watcher.usingPlatformDefaults) this.#effectiveThreshold = 0;\n  }\n\n  /**\n   * Re-delivers the current intersection state as a fresh transition. Bound via\n   * `data-action` (e.g. `my-feed:appended@window->stimeo--intersection#refresh`).\n   *\n   * `IntersectionObserver` only reports state *changes*, so a sentinel that\n   * stays visible while content is appended below it never fires `enter` again\n   * and a hand-rolled infinite scroll stalls. `observe()` always delivers the\n   * current state, and clearing the recorded `data-intersecting`/`data-passed`\n   * makes that delivery count as a transition — a still-visible sentinel\n   * re-fires `enter`. No-op once the observer is gone (`once` fired, no\n   * `IntersectionObserver` support, or after `disconnect()`).\n   */\n  refresh(): void {\n    if (!this.#watcher.active) return;\n    this.#generation += 1;\n    this.element.removeAttribute(\"data-intersecting\");\n    this.element.removeAttribute(\"data-passed\");\n    this.#watcher.rearm(this.element);\n  }\n\n  /**\n   * Reflects the visibility onto `data-intersecting` and fires `enter`/`exit`\n   * on transitions. The previous state is the DOM attribute (source of truth),\n   * so the observer's initial callback fires `enter` for an element that starts\n   * visible but stays silent after a cache restore that already recorded it.\n   * An initial not-visible state is established silently (no `exit`).\n   *\n   * @stimeoRuntimeOnly `once` decides whether this enter spends the watcher's one shot; the hook it\n   *   writes follows the entry.\n   */\n  #syncIntersecting(intersecting: boolean, ratio: number, entry: IntersectionObserverEntry): void {\n    const previous = this.element.getAttribute(\"data-intersecting\");\n    this.element.setAttribute(\"data-intersecting\", intersecting ? \"true\" : \"false\");\n\n    if (intersecting && previous !== \"true\") {\n      // One-shot mode: the shot is spent at this transition, so stop observing\n      // before the event. A handler that re-arms (the `enter` -> append ->\n      // `refresh()` reflex) then finds an inactive watcher and leaves the hooks\n      // in their final state — `data-intersecting=\"true\"` marks it for reconnects.\n      if (this.onceValue) this.#watcher.stop();\n      this.dispatch(\"enter\", { detail: { ratio } });\n    } else if (!intersecting && previous === \"true\") {\n      this.dispatch(\"exit\", {\n        detail: { ratio, position: this.#leftViaStartEdge(entry) ? \"before\" : \"after\" },\n      });\n    }\n  }\n\n  /**\n   * Which edge the element left across, for the `exit` detail. A non-zero\n   * `threshold` withdraws visibility while the element still overlaps the root,\n   * so the leaving rect can straddle the start edge — the direction is the\n   * element's own top against that edge, not whether it has cleared the root\n   * entirely (that is what `passed` reports). An element with no layout box\n   * (`display: none`, a collapsed `<details>`) is reported with an empty rect\n   * that carries no position at all, so it is deliberately neither direction\n   * and takes the \"still ahead\" reading.\n   */\n  #leftViaStartEdge(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    return rect.top < (entry.rootBounds?.top ?? 0);\n  }\n\n  /**\n   * Reflects the \"scrolled past\" state onto `data-passed` and fires `passed` on\n   * transitions — the line sticky headers and reading progress key off. Like\n   * `enter`, an initial `passed=true` (page restored mid-scroll) fires; the\n   * initial `false` is established silently.\n   */\n  #syncPassed(passed: boolean): void {\n    const previous = this.element.getAttribute(\"data-passed\");\n    this.element.setAttribute(\"data-passed\", passed ? \"true\" : \"false\");\n    const changed = previous === null ? passed : (previous === \"true\") !== passed;\n    if (changed) this.dispatch(\"passed\", { detail: { passed } });\n  }\n\n  /** The configured `threshold`, clamped to the 0..1 the observer accepts. */\n  #clampedThreshold(): number {\n    return Math.min(1, Math.max(0, this.thresholdValue));\n  }\n\n  /**\n   * Observer thresholds: the `threshold` line itself, plus `ratioSteps` evenly\n   * spaced steps when fine-grained `change` ratios are wanted (progress bars).\n   *\n   * 0 is always observed. An observer notifies only at the lines it was given,\n   * so a non-zero `threshold` on its own delivers its last callback while the\n   * element is still partly visible: the element leaving for good would never be\n   * reported, freezing the ratio and `data-passed` mid-departure.\n   */\n  #thresholds(): number[] {\n    const thresholds = new Set<number>([0, this.#clampedThreshold()]);\n    if (this.ratioStepsValue > 0) {\n      // i counts up to ratioSteps, so i/ratioSteps is inherently 0..1.\n      for (let i = 0; i <= this.ratioStepsValue; i += 1) {\n        thresholds.add(i / this.ratioStepsValue);\n      }\n    }\n    return [...thresholds].sort((a, b) => a - b);\n  }\n}\n"]}

package/dist/controllers/lazy_frame_controller.js

@@ -192,7 +192,12 @@ var LazyFrameController = class extends Controller {
     if (this.onceValue || !returning) return;
     this.#reload();
   }
-  /** Starts the load by writing the held URL to `src`. */
+  /**
+   * 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;
@@ -202,7 +207,11 @@ 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. */
+  /**
+   * 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) {

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":"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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 * @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  /** Starts the load by writing the held URL to `src`. */\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  /** Re-entry while `once` is off: fetch the held URL again. */\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 * @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"]}

package/dist/controllers/listbox_controller.d.ts

@@ -28,9 +28,12 @@ import { Controller } from '@hotwired/stimulus';
  * (Select-Only Combobox) form. Focus stays on the trigger; the active option is
  * tracked with `aria-activedescendant` rather than by moving DOM focus. For a
  * text-filtered popup use {@link ComboboxController | Combobox}; for multiple
- * selection use Multi-Select.
+ * selection use {@link MultiSelectController | Multi-Select}.
  *
- * `change` dispatches `{ value: string, option: HTMLElement }`.
+ * `change` dispatches `{ value: string, option: HTMLElement }` when the user
+ * selects. `reconcile` dispatches `{ value: string, option: HTMLElement | null }`
+ * — the shape of `change`, with `option: null` and `value: ""` once nothing is
+ * selected — when the page moves the selection instead.
  *
  * @remarks
  * Behavior only. Static placement is the consumer's CSS; dynamic placement is
@@ -50,14 +53,34 @@ import { Controller } from '@hotwired/stimulus';
  *   Making the field a validatable mirror (`<input type="text" hidden required>`
  *   instead of `type="hidden"`) lets `stimeo--form-validation` enforce native
  *   constraints on the committed value with no extra JavaScript.
+ * - With nothing selected the trigger value shows `placeholder` when it is set,
+ *   else the text it held before the controller first wrote into it; it keeps no
+ *   text of an option that is not selected. A value the page rewrote, or added an
+ *   element to, after the controller wrote into it is the page's instead, and stays
+ *   exactly as the page left it until the next selection.
+ * - A selection the page moves — the selected option removed or dropped from the
+ *   targets, a morph or a script writing an option's `aria-selected` or the
+ *   selected option's `data-value`, a selected option that arrives ahead of the
+ *   selection — updates the label and the field silently and dispatches
+ *   `stimeo--listbox:reconcile`: once per batch, and only when the selected
+ *   option or its value differs from the selection last settled (on connect, by
+ *   the user, or by the previous `reconcile`). Connecting reports nothing. While
+ *   connected a `MutationObserver` watches the options' `aria-selected` and
+ *   `data-value`; `disconnect()` releases it.
  * - `Enter`/`Space` select and close; `Escape` and outside click / `Tab` close;
  *   closing via select/Escape returns focus to the trigger.
  */
 declare class ListboxController extends Controller<HTMLElement> {
     #private;
     static targets: string[];
+    static values: {
+        placeholder: {
+            type: StringConstructor;
+            default: string;
+        };
+    };
     static actions: readonly ["close", "onTriggerKeydown", "open", "select", "toggle"];
-    static events: readonly ["change"];
+    static events: readonly ["change", "reconcile"];
     readonly triggerTarget: HTMLElement;
     readonly valueTarget: HTMLElement;
     readonly listTarget: HTMLElement;
@@ -67,16 +90,35 @@ declare class ListboxController extends Controller<HTMLElement> {
     readonly hasValueTarget: boolean;
     readonly hasListTarget: boolean;
     readonly hasFieldTarget: boolean;
-    /** Establishes the ARIA baseline, starts closed, and listens for outside clicks. */
+    placeholderValue: string;
+    /**
+     * Establishes the ARIA baseline, settles the selection without reporting it,
+     * starts closed, and listens for outside clicks.
+     */
     connect(): void;
     /**
-     * Establishes an inactive baseline for a late option, re-resolves active
-     * identity, and re-applies the selection baseline.
+     * Establishes an inactive baseline for a late option, then re-applies the
+     * selection baseline and re-resolves active identity once the batch is in.
      */
     optionTargetConnected(option: HTMLElement): void;
-    /** Removes controller-owned active state and reconciles the surviving targets. */
+    /**
+     * Removes controller-owned active state, then settles the selection and the
+     * active option among the surviving targets once the batch is in.
+     */
     optionTargetDisconnected(option: HTMLElement): void;
-    /** Removes the document listener and clears the typeahead timer. */
+    /** Fills a form field inserted or replaced at runtime with the current selection. */
+    fieldTargetConnected(): void;
+    /** Writes the current selection into a trigger value inserted or replaced at runtime. */
+    valueTargetConnected(): void;
+    /**
+     * Re-renders the empty-selection label when application code (or a Turbo morph)
+     * changes `placeholder` at runtime.
+     */
+    placeholderValueChanged(): void;
+    /**
+     * Releases the outside-click listener and the option observer, drops a queued
+     * pass, and clears the typeahead timer.
+     */
     disconnect(): void;
     /**
      * Toggles the list on a real mouse click. Keyboard activation of the