stimeo-ui 0.2.0 → 0.2.1

package/dist/controllers/highlight_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/safe_timeout.ts","../../src/controllers/highlight_controller.ts"],"names":[],"mappings":"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","file":"highlight_controller.js","sourcesContent":["/**\n * Self-cleaning timer registries shared by Stimeo controllers.\n *\n * Stimulus controllers frequently schedule `setTimeout` / `setInterval` work\n * (auto-dismiss, debouncing, polling). When the element leaves the DOM — a\n * Turbo Drive navigation, a Turbo Stream replacement, or any `disconnect()` —\n * orphaned timers keep firing against a detached controller, leaking memory and\n * mutating stale state. {@link SafeTimeout} and {@link SafeInterval} track every\n * timer they create so a single {@link TimerRegistry.clearAll | clearAll()} call\n * in `disconnect()` tears them all down.\n *\n * These are intentionally low-level primitives: they own *registration and\n * cleanup only*. Higher-level policy (pause/resume, remaining-time accounting)\n * stays in the individual controllers so per-widget semantics are not flattened\n * into a lowest-common-denominator helper.\n */\n\n/**\n * Shared registry bookkeeping for the timeout/interval variants.\n *\n * Subclasses provide the scheduling primitive ({@link schedule}) and its matching\n * canceller ({@link cancel}); this base owns the set of live ids plus the\n * per-id and bulk teardown shared by both.\n */\nabstract class TimerRegistry {\n  /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */\n  protected readonly ids = new Set<number>();\n\n  /** Schedules the underlying platform timer and returns its id. */\n  protected abstract schedule(callback: () => void, delay: number): number;\n\n  /** Cancels the underlying platform timer for `id`. */\n  protected abstract cancel(id: number): void;\n\n  /**\n   * Cancels a single tracked timer.\n   *\n   * No-ops if the id is unknown (already cleared, fired, or never owned by this\n   * registry), so callers can clear defensively without guarding.\n   */\n  clear(id: number): void {\n    if (this.ids.delete(id)) {\n      this.cancel(id);\n    }\n  }\n\n  /**\n   * Cancels every tracked timer. Call this from a controller's `disconnect()`\n   * to guarantee no timer outlives the element.\n   */\n  clearAll(): void {\n    for (const id of this.ids) {\n      this.cancel(id);\n    }\n    this.ids.clear();\n  }\n\n  /** Number of timers currently tracked (pending). */\n  get size(): number {\n    return this.ids.size;\n  }\n}\n\n/**\n * `setTimeout` wrapper that auto-forgets each timer once it fires and supports\n * bulk teardown on disconnect.\n *\n * @example\n * ```ts\n * #timers = new SafeTimeout();\n *\n * connect() {\n *   this.#timers.set(() => this.dismiss(), 5000);\n * }\n *\n * disconnect() {\n *   this.#timers.clearAll();\n * }\n * ```\n */\nexport class SafeTimeout extends TimerRegistry {\n  /**\n   * Schedules `callback` after `delay` ms and returns the timer id.\n   *\n   * The id is removed from the registry automatically when the timeout fires,\n   * so {@link TimerRegistry.size | size} reflects only still-pending timers.\n   */\n  set(callback: () => void, delay: number): number {\n    const id = this.schedule(() => {\n      this.ids.delete(id);\n      callback();\n    }, delay);\n    this.ids.add(id);\n    return id;\n  }\n\n  protected schedule(callback: () => void, delay: number): number {\n    return window.setTimeout(callback, delay);\n  }\n\n  protected cancel(id: number): void {\n    window.clearTimeout(id);\n  }\n}\n\n/**\n * `setInterval` wrapper that tracks every interval for bulk teardown on\n * disconnect. Unlike {@link SafeTimeout}, intervals are retained until they are\n * explicitly cleared because they fire repeatedly.\n *\n * @example\n * ```ts\n * #intervals = new SafeInterval();\n *\n * connect() {\n *   this.#intervals.set(() => this.tick(), 1000);\n * }\n *\n * disconnect() {\n *   this.#intervals.clearAll();\n * }\n * ```\n */\nexport class SafeInterval extends TimerRegistry {\n  /** Schedules a repeating `callback` every `delay` ms and returns the timer id. */\n  set(callback: () => void, delay: number): number {\n    const id = this.schedule(callback, delay);\n    this.ids.add(id);\n    return id;\n  }\n\n  protected schedule(callback: () => void, delay: number): number {\n    return window.setInterval(callback, delay);\n  }\n\n  protected cancel(id: number): void {\n    window.clearInterval(id);\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { SafeTimeout } from \"../utils/safe_timeout\";\n\n/**\n * Headless \"highlight on insert\" behavior: briefly flags a freshly inserted element\n * with `data-highlight` so CSS can flash / fade it in, then removes the flag after\n * `duration` ms (no dedicated APG pattern; a purely visual emphasis that honors the\n * WCAG \"animation from interactions\" practice via `prefers-reduced-motion`).\n *\n * Markup contract (identifier: `stimeo--highlight`):\n *   <!-- self-highlight: put it on the inserted row itself -->\n *   <li data-controller=\"stimeo--highlight\">New item</li>\n *\n *   <!-- container mode: watch for added children and highlight each -->\n *   <ul data-controller=\"stimeo--highlight\" data-stimeo--highlight-observe-value=\"true\"></ul>\n *\n * In the default (self) mode the controller element is highlighted once on\n * `connect()`. With `observe`, a `MutationObserver` instead highlights every element\n * child added to the container (e.g. Turbo Stream appends). Each highlight sets\n * `data-highlight=\"true\"`, dispatches `start`, and after `duration` removes it and\n * dispatches `end` — both carry `detail.element`.\n *\n * @remarks\n * Behavior only — it ships no color or animation, just the hook (pair with CSS, and\n * with Announcer / Flash for non-visual notice). Under `prefers-reduced-motion: reduce`\n * the emphasis is suppressed entirely (the element simply appears), so no hook or\n * event is emitted. The self hook is added on `connect()` and removed before its\n * `duration` elapses, so it does not linger into a `turbo:before-cache` snapshot; the\n * observer and pending timers are torn down on `disconnect()` (Turbo navigation\n * included).\n */\nexport class HighlightController extends Controller<HTMLElement> {\n  static override values = {\n    duration: { type: Number, default: 1500 },\n    observe: { type: Boolean, default: false },\n  };\n  static events = [\"start\", \"end\"] as const;\n\n  declare durationValue: number;\n  declare observeValue: boolean;\n\n  readonly #timeouts = new SafeTimeout();\n  #observer: MutationObserver | null = null;\n\n  override connect(): void {\n    if (this.observeValue) {\n      if (typeof MutationObserver !== \"undefined\") {\n        this.#observer = new MutationObserver((mutations) => this.#onMutations(mutations));\n        this.#observer.observe(this.element, { childList: true });\n      }\n      return;\n    }\n    this.#highlight(this.element);\n  }\n\n  override disconnect(): void {\n    this.#observer?.disconnect();\n    this.#observer = null;\n    this.#timeouts.clearAll();\n  }\n\n  /** Highlights every element child added by a childList mutation. */\n  #onMutations(mutations: MutationRecord[]): void {\n    for (const mutation of mutations) {\n      for (const node of mutation.addedNodes) {\n        if (node instanceof HTMLElement) this.#highlight(node);\n      }\n    }\n  }\n\n  /** Flags `el` with `data-highlight` and schedules its removal (unless reduced-motion). */\n  #highlight(el: HTMLElement): void {\n    // Reduced motion: suppress the emphasis so the element just appears — no hook,\n    // no timer, no events, nothing to transition.\n    if (this.#prefersReducedMotion()) return;\n\n    el.setAttribute(\"data-highlight\", \"true\");\n    this.dispatch(\"start\", { target: el, detail: { element: el } });\n    this.#timeouts.set(() => {\n      el.removeAttribute(\"data-highlight\");\n      this.dispatch(\"end\", { target: el, detail: { element: el } });\n    }, this.durationValue);\n  }\n\n  #prefersReducedMotion(): boolean {\n    return (\n      typeof window.matchMedia === \"function\" &&\n      window.matchMedia(\"(prefers-reduced-motion: reduce)\").matches\n    );\n  }\n}\n"]}
+{"version":3,"sources":["../../src/utils/reduced_motion.ts","../../src/utils/safe_timeout.ts","../../src/controllers/highlight_controller.ts"],"names":[],"mappings":"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","file":"highlight_controller.js","sourcesContent":["/**\n * Shared `prefers-reduced-motion` lookup for the motion-aware controllers\n * (count-up, highlight, overflow-indicator, scroll-visibility, stick-to-bottom,\n * transition).\n *\n * Each of those controllers used to duplicate the same guarded `matchMedia`\n * read; this one-liner keeps the media query string and the environment guard\n * single-sourced. The preference is intentionally re-read on every call — the\n * controllers check it at each animation/scroll start (WCAG 2.2 **2.3.3**), so\n * flipping the OS setting takes effect immediately without any listener or\n * cache bookkeeping here.\n */\n\n/**\n * Whether the user currently requests reduced motion.\n *\n * @returns `true` when `(prefers-reduced-motion: reduce)` matches; `false`\n * otherwise, including environments without `window.matchMedia` (treated as\n * \"no preference\").\n */\nexport function prefersReducedMotion(): boolean {\n  return (\n    typeof window.matchMedia === \"function\" &&\n    window.matchMedia(\"(prefers-reduced-motion: reduce)\").matches\n  );\n}\n","/**\n * Self-cleaning timer registries shared by Stimeo controllers.\n *\n * Stimulus controllers frequently schedule `setTimeout` / `setInterval` work\n * (auto-dismiss, debouncing, polling). When the element leaves the DOM — a\n * Turbo Drive navigation, a Turbo Stream replacement, or any `disconnect()` —\n * orphaned timers keep firing against a detached controller, leaking memory and\n * mutating stale state. {@link SafeTimeout} and {@link SafeInterval} track every\n * timer they create so a single {@link TimerRegistry.clearAll | clearAll()} call\n * in `disconnect()` tears them all down.\n *\n * These are intentionally low-level primitives: they own *registration and\n * cleanup only*. Higher-level policy (pause/resume, remaining-time accounting)\n * stays in the individual controllers so per-widget semantics are not flattened\n * into a lowest-common-denominator helper.\n */\n\n/**\n * Shared registry bookkeeping for the timeout/interval variants.\n *\n * Subclasses provide the scheduling primitive ({@link schedule}) and its matching\n * canceller ({@link cancel}); this base owns the set of live ids plus the\n * per-id and bulk teardown shared by both.\n */\nabstract class TimerRegistry {\n  /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */\n  protected readonly ids = new Set<number>();\n\n  /** Schedules the underlying platform timer and returns its id. */\n  protected abstract schedule(callback: () => void, delay: number): number;\n\n  /** Cancels the underlying platform timer for `id`. */\n  protected abstract cancel(id: number): void;\n\n  /**\n   * Cancels a single tracked timer.\n   *\n   * No-ops if the id is unknown (already cleared, fired, or never owned by this\n   * registry), so callers can clear defensively without guarding.\n   */\n  clear(id: number): void {\n    if (this.ids.delete(id)) {\n      this.cancel(id);\n    }\n  }\n\n  /**\n   * Cancels every tracked timer. Call this from a controller's `disconnect()`\n   * to guarantee no timer outlives the element.\n   */\n  clearAll(): void {\n    for (const id of this.ids) {\n      this.cancel(id);\n    }\n    this.ids.clear();\n  }\n\n  /** Number of timers currently tracked (pending). */\n  get size(): number {\n    return this.ids.size;\n  }\n}\n\n/**\n * `setTimeout` wrapper that auto-forgets each timer once it fires and supports\n * bulk teardown on disconnect.\n *\n * @example\n * ```ts\n * #timers = new SafeTimeout();\n *\n * connect() {\n *   this.#timers.set(() => this.dismiss(), 5000);\n * }\n *\n * disconnect() {\n *   this.#timers.clearAll();\n * }\n * ```\n */\nexport class SafeTimeout extends TimerRegistry {\n  /**\n   * Schedules `callback` after `delay` ms and returns the timer id.\n   *\n   * The id is removed from the registry automatically when the timeout fires,\n   * so {@link TimerRegistry.size | size} reflects only still-pending timers.\n   */\n  set(callback: () => void, delay: number): number {\n    const id = this.schedule(() => {\n      this.ids.delete(id);\n      callback();\n    }, delay);\n    this.ids.add(id);\n    return id;\n  }\n\n  protected schedule(callback: () => void, delay: number): number {\n    return window.setTimeout(callback, delay);\n  }\n\n  protected cancel(id: number): void {\n    window.clearTimeout(id);\n  }\n}\n\n/**\n * `setInterval` wrapper that tracks every interval for bulk teardown on\n * disconnect. Unlike {@link SafeTimeout}, intervals are retained until they are\n * explicitly cleared because they fire repeatedly.\n *\n * @example\n * ```ts\n * #intervals = new SafeInterval();\n *\n * connect() {\n *   this.#intervals.set(() => this.tick(), 1000);\n * }\n *\n * disconnect() {\n *   this.#intervals.clearAll();\n * }\n * ```\n */\nexport class SafeInterval extends TimerRegistry {\n  /** Schedules a repeating `callback` every `delay` ms and returns the timer id. */\n  set(callback: () => void, delay: number): number {\n    const id = this.schedule(callback, delay);\n    this.ids.add(id);\n    return id;\n  }\n\n  protected schedule(callback: () => void, delay: number): number {\n    return window.setInterval(callback, delay);\n  }\n\n  protected cancel(id: number): void {\n    window.clearInterval(id);\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { prefersReducedMotion } from \"../utils/reduced_motion\";\nimport { SafeTimeout } from \"../utils/safe_timeout\";\n\n/**\n * Headless \"highlight on insert\" behavior: briefly flags a freshly inserted element\n * with `data-highlight` so CSS can flash / fade it in, then removes the flag after\n * `duration` ms (no dedicated APG pattern; a purely visual emphasis that honors the\n * WCAG \"animation from interactions\" practice via `prefers-reduced-motion`).\n *\n * Markup contract (identifier: `stimeo--highlight`):\n *   <!-- self-highlight: put it on the inserted row itself -->\n *   <li data-controller=\"stimeo--highlight\">New item</li>\n *\n *   <!-- container mode: watch for added children and highlight each -->\n *   <ul data-controller=\"stimeo--highlight\" data-stimeo--highlight-observe-value=\"true\"></ul>\n *\n * In the default (self) mode the controller element is highlighted once on\n * `connect()`. With `observe`, a `MutationObserver` instead highlights every element\n * child added to the container (e.g. Turbo Stream appends). Each highlight sets\n * `data-highlight=\"true\"`, dispatches `start`, and after `duration` removes it and\n * dispatches `end` — both carry `detail.element`.\n *\n * @remarks\n * Behavior only — it ships no color or animation, just the hook (pair with CSS, and\n * with Announcer / Flash for non-visual notice). Under `prefers-reduced-motion: reduce`\n * the emphasis is suppressed entirely (the element simply appears), so no hook or\n * event is emitted. The self hook is added on `connect()` and removed before its\n * `duration` elapses, so it does not linger into a `turbo:before-cache` snapshot; the\n * observer and pending timers are torn down on `disconnect()` (Turbo navigation\n * included).\n */\nexport class HighlightController extends Controller<HTMLElement> {\n  static override values = {\n    duration: { type: Number, default: 1500 },\n    observe: { type: Boolean, default: false },\n  };\n  static events = [\"start\", \"end\"] as const;\n\n  declare durationValue: number;\n  declare observeValue: boolean;\n\n  readonly #timeouts = new SafeTimeout();\n  #observer: MutationObserver | null = null;\n\n  override connect(): void {\n    if (this.observeValue) {\n      if (typeof MutationObserver !== \"undefined\") {\n        this.#observer = new MutationObserver((mutations) => this.#onMutations(mutations));\n        this.#observer.observe(this.element, { childList: true });\n      }\n      return;\n    }\n    this.#highlight(this.element);\n  }\n\n  override disconnect(): void {\n    this.#observer?.disconnect();\n    this.#observer = null;\n    this.#timeouts.clearAll();\n  }\n\n  /** Highlights every element child added by a childList mutation. */\n  #onMutations(mutations: MutationRecord[]): void {\n    for (const mutation of mutations) {\n      for (const node of mutation.addedNodes) {\n        if (node instanceof HTMLElement) this.#highlight(node);\n      }\n    }\n  }\n\n  /** Flags `el` with `data-highlight` and schedules its removal (unless reduced-motion). */\n  #highlight(el: HTMLElement): void {\n    // Reduced motion: suppress the emphasis so the element just appears — no hook,\n    // no timer, no events, nothing to transition.\n    if (prefersReducedMotion()) return;\n\n    el.setAttribute(\"data-highlight\", \"true\");\n    this.dispatch(\"start\", { target: el, detail: { element: el } });\n    this.#timeouts.set(() => {\n      el.removeAttribute(\"data-highlight\");\n      this.dispatch(\"end\", { target: el, detail: { element: el } });\n    }, this.durationValue);\n  }\n}\n"]}

package/dist/controllers/intersection_controller.js

@@ -3,6 +3,12 @@ import { Controller } from '@hotwired/stimulus';
 // src/controllers/intersection_controller.ts
 
 // src/utils/intersection_watcher.ts
+function isBeforeRootStart(entry) {
+  const rect = entry.boundingClientRect;
+  if (rect.width === 0 && rect.height === 0) return false;
+  const rootTop = entry.rootBounds?.top ?? 0;
+  return rect.bottom <= rootTop;
+}
 var IntersectionWatcher = class {
   #onEntries;
   #observer = null;
@@ -18,6 +24,11 @@ var IntersectionWatcher = class {
    * (Re)creates the observer and observes `targets`. Returns `false` — leaving
    * the watcher inert — without `IntersectionObserver` support (very old
    * browsers; the caller's no-JS fallback stays in charge) or with no targets.
+   *
+   * @throws Whatever the platform throws for an invalid `rootMargin`/`threshold`
+   *   or a failing `observe()`. The exception is passed through unchanged, but
+   *   the watcher rolls back first: every target observed so far is released and
+   *   `active` stays `false`, so a caller that retries starts from a clean slate.
    */
   start(targets, options = {}) {
     this.stop();
@@ -25,25 +36,42 @@ var IntersectionWatcher = class {
     const list = Array.isArray(targets) ? targets : [targets];
     if (list.length === 0) return false;
     const root = "root" in options ? options.root ?? null : options.rootSelector ? document.querySelector(options.rootSelector) : null;
-    this.#active = true;
-    this.#observer = new IntersectionObserver(
-      (entries) => {
-        if (this.#active) this.#onEntries(entries);
-      },
-      { root, rootMargin: options.rootMargin, threshold: options.threshold }
-    );
-    for (const target of list) this.#observer.observe(target);
-    return true;
+    let observer = null;
+    try {
+      observer = new IntersectionObserver(
+        (entries) => {
+          if (this.#active && this.#observer === observer) this.#onEntries(entries);
+        },
+        { root, rootMargin: options.rootMargin, threshold: options.threshold }
+      );
+      for (const target of list) observer.observe(target);
+      this.#observer = observer;
+      this.#active = true;
+      return true;
+    } catch (error) {
+      observer?.disconnect();
+      this.#observer = null;
+      this.#active = false;
+      throw error;
+    }
   }
   /**
    * Re-delivers `target`'s CURRENT intersection state: `IntersectionObserver`
    * only reports *changes*, but `observe()` always reports the present state,
    * so unobserve→observe turns "still intersecting" into a fresh callback.
+   *
+   * @throws Whatever `unobserve()`/`observe()` throws. The watcher is stopped
+   *   first, so it never stays live with a half-rearmed target.
    */
   rearm(target) {
     if (!this.#observer) return;
-    this.#observer.unobserve(target);
-    this.#observer.observe(target);
+    try {
+      this.#observer.unobserve(target);
+      this.#observer.observe(target);
+    } catch (error) {
+      this.stop();
+      throw error;
+    }
   }
   /** Severs the observer; late queued callbacks become no-ops via the guard. */
   stop() {
@@ -80,7 +108,7 @@ var IntersectionController = class extends Controller {
       this.element.style.setProperty(RATIO_PROPERTY, String(ratio));
       this.dispatch("change", { detail: { intersecting, ratio } });
       this.#syncIntersecting(intersecting, ratio, entry);
-      this.#syncPassed(!intersecting && this.#isBefore(entry));
+      this.#syncPassed(!intersecting && isBeforeRootStart(entry));
     }
   }
   connect() {
@@ -128,7 +156,7 @@ var IntersectionController = class extends Controller {
       if (this.onceValue) this.#watcher.stop();
     } else if (!intersecting && previous === "true") {
       this.dispatch("exit", {
-        detail: { ratio, position: this.#isBefore(entry) ? "before" : "after" }
+        detail: { ratio, position: isBeforeRootStart(entry) ? "before" : "after" }
       });
     }
   }
@@ -144,11 +172,6 @@ var IntersectionController = class extends Controller {
     const changed = previous === null ? passed : previous === "true" !== passed;
     if (changed) this.dispatch("passed", { detail: { passed } });
   }
-  /** True when the element sits entirely before the root's start (top) edge. */
-  #isBefore(entry) {
-    const rootTop = entry.rootBounds?.top ?? 0;
-    return entry.boundingClientRect.bottom <= rootTop;
-  }
   /** The configured `threshold`, clamped to the 0..1 the observer accepts. */
   #clampedThreshold() {
     return Math.min(1, Math.max(0, this.thresholdValue));

package/dist/controllers/intersection_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/intersection_watcher.ts","../../src/controllers/intersection_controller.ts"],"names":[],"mappings":"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","file":"intersection_controller.js","sourcesContent":["/**\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, observer 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 {@link 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 */\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  /** Selector for the observation root; empty/omitted = viewport. */\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\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  /**\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   */\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 =\n      \"root\" in options\n        ? (options.root ?? null)\n        : options.rootSelector\n          ? document.querySelector(options.rootSelector)\n          : null;\n\n    this.#active = true;\n    this.#observer = new IntersectionObserver(\n      (entries) => {\n        if (this.#active) this.#onEntries(entries);\n      },\n      { root, rootMargin: options.rootMargin, threshold: options.threshold },\n    );\n    for (const target of list) this.#observer.observe(target);\n    return true;\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  rearm(target: Element): void {\n    if (!this.#observer) return;\n    this.#observer.unobserve(target);\n    this.#observer.observe(target);\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  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { IntersectionWatcher } 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 that infinite-scroll,\n * reading-progress, count-up (\"animate when visible\") and smart sticky headers\n * compose from, without each writing 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`), `exit` when it\n * leaves (detail carries `position`: `\"before\"` = scrolled past the root's\n * start edge, `\"after\"` = 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). Without `IntersectionObserver` (very\n * old browsers) the controller stays inert — consumers keep whatever no-JS\n * fallback their markup provides. The observer is disconnected on\n * `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  /** 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      const threshold = this.#clampedThreshold();\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 && this.#isBefore(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.#watcher.start(this.element, {\n      rootSelector: this.rootSelectorValue,\n      rootMargin: this.rootMarginValue,\n      threshold: this.#thresholds(),\n    });\n  }\n\n  override disconnect(): void {\n    this.#watcher.stop();\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      this.dispatch(\"enter\", { detail: { ratio } });\n      // One-shot mode: the enter fired; stop observing and leave the hooks in\n      // their final state (`data-intersecting=\"true\"` marks it for reconnects).\n      if (this.onceValue) this.#watcher.stop();\n    } else if (!intersecting && previous === \"true\") {\n      this.dispatch(\"exit\", {\n        detail: { ratio, position: this.#isBefore(entry) ? \"before\" : \"after\" },\n      });\n    }\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  /** True when the element sits entirely before the root's start (top) edge. */\n  #isBefore(entry: IntersectionObserverEntry): boolean {\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 entry.boundingClientRect.bottom <= rootTop;\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  #thresholds(): number[] {\n    const thresholds = new Set<number>([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/intersection_watcher.ts","../../src/controllers/intersection_controller.ts"],"names":[],"mappings":"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","file":"intersection_controller.js","sourcesContent":["/**\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, observer 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 {@link 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/**\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\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  /** Selector for the observation root; empty/omitted = viewport. */\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\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  /**\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   *\n   * @throws Whatever the platform throws for an invalid `rootMargin`/`threshold`\n   *   or a failing `observe()`. The exception is passed through unchanged, but\n   *   the watcher rolls back first: every target observed so far is released and\n   *   `active` stays `false`, so a caller that retries 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 =\n      \"root\" in options\n        ? (options.root ?? null)\n        : options.rootSelector\n          ? document.querySelector(options.rootSelector)\n          : null;\n\n    let observer: IntersectionObserver | null = null;\n    try {\n      observer = new IntersectionObserver(\n        (entries) => {\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        { root, rootMargin: options.rootMargin, threshold: options.threshold },\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      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  }\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 that infinite-scroll,\n * reading-progress, count-up (\"animate when visible\") and smart sticky headers\n * compose from, without each writing 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`), `exit` when it\n * leaves (detail carries `position`: `\"before\"` = scrolled past the root's\n * start edge, `\"after\"` = 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). Without `IntersectionObserver` (very\n * old browsers) the controller stays inert — consumers keep whatever no-JS\n * fallback their markup provides. The observer is disconnected on\n * `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  /** 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      const threshold = this.#clampedThreshold();\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.#watcher.start(this.element, {\n      rootSelector: this.rootSelectorValue,\n      rootMargin: this.rootMarginValue,\n      threshold: this.#thresholds(),\n    });\n  }\n\n  override disconnect(): void {\n    this.#watcher.stop();\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      this.dispatch(\"enter\", { detail: { ratio } });\n      // One-shot mode: the enter fired; stop observing and leave the hooks in\n      // their final state (`data-intersecting=\"true\"` marks it for reconnects).\n      if (this.onceValue) this.#watcher.stop();\n    } else if (!intersecting && previous === \"true\") {\n      this.dispatch(\"exit\", {\n        detail: { ratio, position: isBeforeRootStart(entry) ? \"before\" : \"after\" },\n      });\n    }\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  #thresholds(): number[] {\n    const thresholds = new Set<number>([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

@@ -18,6 +18,11 @@ var IntersectionWatcher = class {
    * (Re)creates the observer and observes `targets`. Returns `false` — leaving
    * the watcher inert — without `IntersectionObserver` support (very old
    * browsers; the caller's no-JS fallback stays in charge) or with no targets.
+   *
+   * @throws Whatever the platform throws for an invalid `rootMargin`/`threshold`
+   *   or a failing `observe()`. The exception is passed through unchanged, but
+   *   the watcher rolls back first: every target observed so far is released and
+   *   `active` stays `false`, so a caller that retries starts from a clean slate.
    */
   start(targets, options = {}) {
     this.stop();
@@ -25,25 +30,42 @@ var IntersectionWatcher = class {
     const list = Array.isArray(targets) ? targets : [targets];
     if (list.length === 0) return false;
     const root = "root" in options ? options.root ?? null : options.rootSelector ? document.querySelector(options.rootSelector) : null;
-    this.#active = true;
-    this.#observer = new IntersectionObserver(
-      (entries) => {
-        if (this.#active) this.#onEntries(entries);
-      },
-      { root, rootMargin: options.rootMargin, threshold: options.threshold }
-    );
-    for (const target of list) this.#observer.observe(target);
-    return true;
+    let observer = null;
+    try {
+      observer = new IntersectionObserver(
+        (entries) => {
+          if (this.#active && this.#observer === observer) this.#onEntries(entries);
+        },
+        { root, rootMargin: options.rootMargin, threshold: options.threshold }
+      );
+      for (const target of list) observer.observe(target);
+      this.#observer = observer;
+      this.#active = true;
+      return true;
+    } catch (error) {
+      observer?.disconnect();
+      this.#observer = null;
+      this.#active = false;
+      throw error;
+    }
   }
   /**
    * Re-delivers `target`'s CURRENT intersection state: `IntersectionObserver`
    * only reports *changes*, but `observe()` always reports the present state,
    * so unobserve→observe turns "still intersecting" into a fresh callback.
+   *
+   * @throws Whatever `unobserve()`/`observe()` throws. The watcher is stopped
+   *   first, so it never stays live with a half-rearmed target.
    */
   rearm(target) {
     if (!this.#observer) return;
-    this.#observer.unobserve(target);
-    this.#observer.observe(target);
+    try {
+      this.#observer.unobserve(target);
+      this.#observer.observe(target);
+    } catch (error) {
+      this.stop();
+      throw error;
+    }
   }
   /** Severs the observer; late queued callbacks become no-ops via the guard. */
   stop() {

package/dist/controllers/lazy_frame_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/intersection_watcher.ts","../../src/controllers/lazy_frame_controller.ts"],"names":[],"mappings":"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","file":"lazy_frame_controller.js","sourcesContent":["/**\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, observer 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 {@link 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 */\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  /** Selector for the observation root; empty/omitted = viewport. */\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\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  /**\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   */\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 =\n      \"root\" in options\n        ? (options.root ?? null)\n        : options.rootSelector\n          ? document.querySelector(options.rootSelector)\n          : null;\n\n    this.#active = true;\n    this.#observer = new IntersectionObserver(\n      (entries) => {\n        if (this.#active) this.#onEntries(entries);\n      },\n      { root, rootMargin: options.rootMargin, threshold: options.threshold },\n    );\n    for (const target of list) this.#observer.observe(target);\n    return true;\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  rearm(target: Element): void {\n    if (!this.#observer) return;\n    this.#observer.unobserve(target);\n    this.#observer.observe(target);\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  }\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 * fires on *render*, not on viewport entry, so this drives an explicit `IntersectionObserver`\n * with a configurable `rootMargin` for early loading, 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` — which starts the Turbo load — marks `data-lazy-loaded`, and\n * emits `load`. With `once` (default) it then stops observing; otherwise re-entry asks\n * Turbo to `reload()` the frame.\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 Frame Loading State. The trigger\n * is idempotent (`data-lazy-loaded` guards a double load and is honored on a Turbo cache\n * restore — a frame that already loaded is not observed again). The `IntersectionObserver`\n * and focus listener are released once loaded (when `once`) and on `disconnect()` (Turbo\n * 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  #loaded = false;\n\n  /** Focus reaching the frame triggers the load before it intersects (keyboard / AT). */\n  readonly #onFocus = (): void => this.#trigger();\n\n  override connect(): void {\n    // A cache restore may bring back an already-loaded frame; respect it, do not reload.\n    if (this.element.hasAttribute(\"data-lazy-loaded\")) {\n      this.#loaded = true;\n      return;\n    }\n    if (!this.urlValue) return;\n\n    this.element.addEventListener(\"focusin\", this.#onFocus);\n    this.#watcher.start(this.element, { rootMargin: this.rootMarginValue });\n  }\n\n  override disconnect(): void {\n    this.#stopObserving();\n  }\n\n  #onIntersect(entries: IntersectionObserverEntry[]): void {\n    for (const entry of entries) {\n      if (entry.isIntersecting) {\n        this.#trigger();\n        return;\n      }\n    }\n  }\n\n  #trigger(): void {\n    if (!this.#loaded) this.#load();\n    else if (!this.onceValue) this.#reload();\n  }\n\n  /** Starts the load by writing the held URL to `src`. */\n  #load(): void {\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    if (this.onceValue) this.#stopObserving();\n  }\n\n  /** Re-entry while `once` is off: ask Turbo to reload the frame's current `src`. */\n  #reload(): void {\n    const frame = this.element as HTMLElement & { reload?: () => void };\n    // Only signal `load` when a reload actually happens. On a non-`<turbo-frame>`\n    // host (no `reload()`), firing it would announce a load that never occurred.\n    if (typeof frame.reload !== \"function\") return;\n    frame.reload();\n    this.dispatch(\"load\", { detail: { url: this.urlValue } });\n  }\n\n  #stopObserving(): void {\n    this.#watcher.stop();\n    this.element.removeEventListener(\"focusin\", this.#onFocus);\n  }\n}\n"]}
+{"version":3,"sources":["../../src/utils/intersection_watcher.ts","../../src/controllers/lazy_frame_controller.ts"],"names":[],"mappings":"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","file":"lazy_frame_controller.js","sourcesContent":["/**\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, observer 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 {@link 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/**\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\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  /** Selector for the observation root; empty/omitted = viewport. */\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\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  /**\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   *\n   * @throws Whatever the platform throws for an invalid `rootMargin`/`threshold`\n   *   or a failing `observe()`. The exception is passed through unchanged, but\n   *   the watcher rolls back first: every target observed so far is released and\n   *   `active` stays `false`, so a caller that retries 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 =\n      \"root\" in options\n        ? (options.root ?? null)\n        : options.rootSelector\n          ? document.querySelector(options.rootSelector)\n          : null;\n\n    let observer: IntersectionObserver | null = null;\n    try {\n      observer = new IntersectionObserver(\n        (entries) => {\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        { root, rootMargin: options.rootMargin, threshold: options.threshold },\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      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  }\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 * fires on *render*, not on viewport entry, so this drives an explicit `IntersectionObserver`\n * with a configurable `rootMargin` for early loading, 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` — which starts the Turbo load — marks `data-lazy-loaded`, and\n * emits `load`. With `once` (default) it then stops observing; otherwise re-entry asks\n * Turbo to `reload()` the frame.\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 Frame Loading State. The trigger\n * is idempotent (`data-lazy-loaded` guards a double load and is honored on a Turbo cache\n * restore — a frame that already loaded is not observed again). The `IntersectionObserver`\n * and focus listener are released once loaded (when `once`) and on `disconnect()` (Turbo\n * 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  #loaded = false;\n\n  /** Focus reaching the frame triggers the load before it intersects (keyboard / AT). */\n  readonly #onFocus = (): void => this.#trigger();\n\n  override connect(): void {\n    // A cache restore may bring back an already-loaded frame; respect it, do not reload.\n    if (this.element.hasAttribute(\"data-lazy-loaded\")) {\n      this.#loaded = true;\n      return;\n    }\n    if (!this.urlValue) return;\n\n    this.element.addEventListener(\"focusin\", this.#onFocus);\n    this.#watcher.start(this.element, { rootMargin: this.rootMarginValue });\n  }\n\n  override disconnect(): void {\n    this.#stopObserving();\n  }\n\n  #onIntersect(entries: IntersectionObserverEntry[]): void {\n    for (const entry of entries) {\n      if (entry.isIntersecting) {\n        this.#trigger();\n        return;\n      }\n    }\n  }\n\n  #trigger(): void {\n    if (!this.#loaded) this.#load();\n    else if (!this.onceValue) this.#reload();\n  }\n\n  /** Starts the load by writing the held URL to `src`. */\n  #load(): void {\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    if (this.onceValue) this.#stopObserving();\n  }\n\n  /** Re-entry while `once` is off: ask Turbo to reload the frame's current `src`. */\n  #reload(): void {\n    const frame = this.element as HTMLElement & { reload?: () => void };\n    // Only signal `load` when a reload actually happens. On a non-`<turbo-frame>`\n    // host (no `reload()`), firing it would announce a load that never occurred.\n    if (typeof frame.reload !== \"function\") return;\n    frame.reload();\n    this.dispatch(\"load\", { detail: { url: this.urlValue } });\n  }\n\n  #stopObserving(): void {\n    this.#watcher.stop();\n    this.element.removeEventListener(\"focusin\", this.#onFocus);\n  }\n}\n"]}

package/dist/controllers/masonry_controller.d.ts

@@ -0,0 +1,54 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless **Masonry** layout helper: assigns each item to the shortest column so
+ * variable-height cards pack without vertical gaps. There is no APG widget — this
+ * is a layout-only utility that emits state hooks, never visual structure.
+ *
+ * Markup contract (identifier: `stimeo--masonry`):
+ *   <div data-controller="stimeo--masonry"
+ *        data-stimeo--masonry-min-column-width-value="240"
+ *        data-stimeo--masonry-gap-value="16">
+ *     <div data-stimeo--masonry-target="item">…</div>
+ *     <div data-stimeo--masonry-target="item">…</div>
+ *   </div>
+ *
+ * The column count is derived responsively from the container width and
+ * `minColumnWidth`; each item is then placed into whichever column is currently
+ * shortest (measured from item heights). The count is published on the controller
+ * element as the `--stimeo-masonry-columns` custom property and each item gets a
+ * `data-column` index, so the consumer's CSS owns the actual placement.
+ *
+ * @remarks
+ * Behavior only. **DOM order is never changed** — reading order and focus order
+ * stay the source markup order (WCAG 1.3.2). The visual packing is purely the
+ * column assignment a consumer reads from `data-column`; this controller writes no
+ * positioning styles. Re-layout runs on connect, on resize ({@link LayoutObserver}),
+ * and on item add/remove ({@link MutationObserver}); both observers are released on
+ * `disconnect()` (Turbo navigation included). Use only for independent cards whose
+ * visual order carries no meaning.
+ */
+declare class MasonryController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        minColumnWidth: {
+            type: NumberConstructor;
+            default: number;
+        };
+        gap: {
+            type: NumberConstructor;
+            default: number;
+        };
+    };
+    static events: readonly ["layout"];
+    readonly itemTargets: HTMLElement[];
+    minColumnWidthValue: number;
+    gapValue: number;
+    /** Observes size/content changes and performs the first layout pass. */
+    connect(): void;
+    /** Releases both observers and the load listener so nothing fires after detach. */
+    disconnect(): void;
+}
+
+export { MasonryController };

package/dist/controllers/masonry_controller.js

@@ -0,0 +1,142 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/masonry_controller.ts
+
+// src/utils/layout_observer.ts
+var LayoutObserver = class {
+  #callback;
+  #resizeObserverFactory;
+  #resizeObserver = null;
+  #observingViewport = false;
+  /** Stable bound handler so add/removeEventListener target the same reference. */
+  #handleViewportResize = () => {
+    this.#callback();
+  };
+  constructor(callback, options = {}) {
+    this.#callback = callback;
+    this.#resizeObserverFactory = options.resizeObserverFactory ?? (typeof ResizeObserver === "undefined" ? null : (cb) => new ResizeObserver(cb));
+  }
+  /**
+   * Starts observing an element's size. Repeated calls observe additional
+   * elements through the same shared observer. No-ops when no
+   * `ResizeObserver` implementation is available.
+   */
+  observe(element) {
+    if (!this.#resizeObserverFactory) return;
+    if (!this.#resizeObserver) {
+      this.#resizeObserver = this.#resizeObserverFactory(() => {
+        this.#callback();
+      });
+    }
+    this.#resizeObserver.observe(element);
+  }
+  /** Stops observing a single element while leaving any others in place. */
+  unobserve(element) {
+    this.#resizeObserver?.unobserve(element);
+  }
+  /** Starts observing viewport resizes. Idempotent: the listener is added once. */
+  observeViewport() {
+    if (this.#observingViewport) return;
+    this.#observingViewport = true;
+    window.addEventListener("resize", this.#handleViewportResize);
+  }
+  /** Stops observing viewport resizes without affecting element observation. */
+  unobserveViewport() {
+    if (!this.#observingViewport) return;
+    this.#observingViewport = false;
+    window.removeEventListener("resize", this.#handleViewportResize);
+  }
+  /**
+   * Releases every observation: disconnects the {@link ResizeObserver} and
+   * removes the viewport listener. Safe to call multiple times. Call this from a
+   * controller's `disconnect()`.
+   */
+  disconnect() {
+    this.#resizeObserver?.disconnect();
+    this.#resizeObserver = null;
+    this.unobserveViewport();
+  }
+};
+
+// src/controllers/masonry_controller.ts
+var COLUMNS_PROPERTY = "--stimeo-masonry-columns";
+var MasonryController = class extends Controller {
+  static targets = ["item"];
+  static values = {
+    minColumnWidth: { type: Number, default: 240 },
+    gap: { type: Number, default: 16 }
+  };
+  static events = ["layout"];
+  #layout = new LayoutObserver(() => this.#relayout());
+  #mutationObserver = null;
+  /** Last published column count, so `layout` fires only on real changes. */
+  #lastColumns = 0;
+  /**
+   * Re-pack when a descendant resource finishes loading. Images/iframes report a
+   * height of 0 until loaded, which would skew the shortest-column packing if the
+   * first pass ran before they settled; `load` does not bubble, so this is bound in
+   * the capture phase to catch every descendant.
+   */
+  #onLoad = () => this.#relayout();
+  /** Observes size/content changes and performs the first layout pass. */
+  connect() {
+    this.#layout.observe(this.element);
+    this.#layout.observeViewport();
+    if (typeof MutationObserver !== "undefined") {
+      this.#mutationObserver = new MutationObserver(() => this.#relayout());
+      this.#mutationObserver.observe(this.element, { childList: true, subtree: true });
+    }
+    this.element.addEventListener("load", this.#onLoad, true);
+    this.#relayout();
+  }
+  /** Releases both observers and the load listener so nothing fires after detach. */
+  disconnect() {
+    this.#layout.disconnect();
+    this.#mutationObserver?.disconnect();
+    this.#mutationObserver = null;
+    this.element.removeEventListener("load", this.#onLoad, true);
+    this.#lastColumns = 0;
+  }
+  /**
+   * Recomputes the column count and assigns every item to the shortest column.
+   * Runs automatically on connect, on resize, on item add/remove, and when a
+   * descendant resource loads (private — there is no public action; the observers
+   * and the capture-phase `load` listener drive it). Items are walked in DOM
+   * order; each lands in the column with the least accumulated height, which
+   * keeps the packing balanced without reordering the DOM.
+   */
+  #relayout() {
+    const items = this.itemTargets;
+    const columns = this.#columnCount();
+    const heights = new Array(columns).fill(0);
+    for (const item of items) {
+      let shortest = 0;
+      for (let col = 1; col < columns; col++) {
+        if ((heights[col] ?? 0) < (heights[shortest] ?? 0)) shortest = col;
+      }
+      item.setAttribute("data-column", String(shortest));
+      heights[shortest] = (heights[shortest] ?? 0) + item.getBoundingClientRect().height + this.gapValue;
+    }
+    this.element.style.setProperty(COLUMNS_PROPERTY, String(columns));
+    if (columns !== this.#lastColumns) {
+      this.#lastColumns = columns;
+      this.dispatch("layout", { detail: { columns } });
+    }
+  }
+  /**
+   * Derives how many columns fit: `floor((width + gap) / (minColumnWidth + gap))`,
+   * never fewer than one. When the width is unmeasurable (detached, or a layout
+   * engine that reports `0`), it falls back to a single column so every item still
+   * gets a valid `data-column`.
+   */
+  #columnCount() {
+    const width = this.element.getBoundingClientRect().width;
+    const denominator = this.minColumnWidthValue + this.gapValue;
+    if (width <= 0 || denominator <= 0) return 1;
+    return Math.max(1, Math.floor((width + this.gapValue) / denominator));
+  }
+};
+
+export { MasonryController };
+//# sourceMappingURL=masonry_controller.js.map
+//# sourceMappingURL=masonry_controller.js.map

package/dist/controllers/masonry_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/layout_observer.ts","../../src/controllers/masonry_controller.ts"],"names":[],"mappings":"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","file":"masonry_controller.js","sourcesContent":["/**\n * Unified element-size and viewport observation for Stimeo controllers.\n *\n * Layout-sensitive widgets (sliders, resizable panes, scroll spies, popovers)\n * need to react both to their *own* box changing — via {@link ResizeObserver} —\n * and to the *viewport* changing — via the `window` `resize` event. Wiring those\n * two sources by hand in every controller risks leaked listeners on\n * `disconnect()`. {@link LayoutObserver} owns both behind one callback and one\n * {@link LayoutObserver.disconnect | disconnect()} that releases everything.\n *\n * Behavior only: the helper reports *that* layout changed; it never reads or\n * writes styles. Consumers decide what to recompute.\n */\n\n/** Invoked whenever an observed element or the viewport changes size. */\nexport type LayoutCallback = () => void;\n\n/** Constructs a {@link ResizeObserver}; injectable so tests stay deterministic. */\nexport type ResizeObserverFactory = (callback: ResizeObserverCallback) => ResizeObserver;\n\n/** Options for {@link LayoutObserver}. */\nexport interface LayoutObserverOptions {\n  /**\n   * Factory for the {@link ResizeObserver} used by {@link LayoutObserver.observe}.\n   * Defaults to the global constructor; override it in tests, or to no-op in\n   * environments where `ResizeObserver` is unavailable.\n   */\n  resizeObserverFactory?: ResizeObserverFactory;\n}\n\n/**\n * Observes element resizes and/or viewport resizes through a single callback,\n * with guaranteed teardown.\n *\n * @example\n * ```ts\n * #layout = new LayoutObserver(() => this.#reposition());\n *\n * connect() {\n *   this.#layout.observe(this.panelTarget);\n *   this.#layout.observeViewport();\n * }\n *\n * disconnect() {\n *   this.#layout.disconnect();\n * }\n * ```\n */\nexport class LayoutObserver {\n  readonly #callback: LayoutCallback;\n  readonly #resizeObserverFactory: ResizeObserverFactory | null;\n  #resizeObserver: ResizeObserver | null = null;\n  #observingViewport = false;\n\n  /** Stable bound handler so add/removeEventListener target the same reference. */\n  readonly #handleViewportResize = (): void => {\n    this.#callback();\n  };\n\n  constructor(callback: LayoutCallback, options: LayoutObserverOptions = {}) {\n    this.#callback = callback;\n    this.#resizeObserverFactory =\n      options.resizeObserverFactory ??\n      (typeof ResizeObserver === \"undefined\" ? null : (cb) => new ResizeObserver(cb));\n  }\n\n  /**\n   * Starts observing an element's size. Repeated calls observe additional\n   * elements through the same shared observer. No-ops when no\n   * `ResizeObserver` implementation is available.\n   */\n  observe(element: Element): void {\n    if (!this.#resizeObserverFactory) return;\n    if (!this.#resizeObserver) {\n      this.#resizeObserver = this.#resizeObserverFactory(() => {\n        this.#callback();\n      });\n    }\n    this.#resizeObserver.observe(element);\n  }\n\n  /** Stops observing a single element while leaving any others in place. */\n  unobserve(element: Element): void {\n    this.#resizeObserver?.unobserve(element);\n  }\n\n  /** Starts observing viewport resizes. Idempotent: the listener is added once. */\n  observeViewport(): void {\n    if (this.#observingViewport) return;\n    this.#observingViewport = true;\n    window.addEventListener(\"resize\", this.#handleViewportResize);\n  }\n\n  /** Stops observing viewport resizes without affecting element observation. */\n  unobserveViewport(): void {\n    if (!this.#observingViewport) return;\n    this.#observingViewport = false;\n    window.removeEventListener(\"resize\", this.#handleViewportResize);\n  }\n\n  /**\n   * Releases every observation: disconnects the {@link ResizeObserver} and\n   * removes the viewport listener. Safe to call multiple times. Call this from a\n   * controller's `disconnect()`.\n   */\n  disconnect(): void {\n    this.#resizeObserver?.disconnect();\n    this.#resizeObserver = null;\n    this.unobserveViewport();\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { LayoutObserver } from \"../utils/layout_observer\";\n\n/** CSS custom property exposing the current column count to consumer CSS. */\nconst COLUMNS_PROPERTY = \"--stimeo-masonry-columns\";\n\n/**\n * Headless **Masonry** layout helper: assigns each item to the shortest column so\n * variable-height cards pack without vertical gaps. There is no APG widget — this\n * is a layout-only utility that emits state hooks, never visual structure.\n *\n * Markup contract (identifier: `stimeo--masonry`):\n *   <div data-controller=\"stimeo--masonry\"\n *        data-stimeo--masonry-min-column-width-value=\"240\"\n *        data-stimeo--masonry-gap-value=\"16\">\n *     <div data-stimeo--masonry-target=\"item\">…</div>\n *     <div data-stimeo--masonry-target=\"item\">…</div>\n *   </div>\n *\n * The column count is derived responsively from the container width and\n * `minColumnWidth`; each item is then placed into whichever column is currently\n * shortest (measured from item heights). The count is published on the controller\n * element as the `--stimeo-masonry-columns` custom property and each item gets a\n * `data-column` index, so the consumer's CSS owns the actual placement.\n *\n * @remarks\n * Behavior only. **DOM order is never changed** — reading order and focus order\n * stay the source markup order (WCAG 1.3.2). The visual packing is purely the\n * column assignment a consumer reads from `data-column`; this controller writes no\n * positioning styles. Re-layout runs on connect, on resize ({@link LayoutObserver}),\n * and on item add/remove ({@link MutationObserver}); both observers are released on\n * `disconnect()` (Turbo navigation included). Use only for independent cards whose\n * visual order carries no meaning.\n */\nexport class MasonryController extends Controller<HTMLElement> {\n  static override targets = [\"item\"];\n  static override values = {\n    minColumnWidth: { type: Number, default: 240 },\n    gap: { type: Number, default: 16 },\n  };\n  static events = [\"layout\"] as const;\n\n  declare readonly itemTargets: HTMLElement[];\n  declare minColumnWidthValue: number;\n  declare gapValue: number;\n\n  readonly #layout = new LayoutObserver(() => this.#relayout());\n  #mutationObserver: MutationObserver | null = null;\n  /** Last published column count, so `layout` fires only on real changes. */\n  #lastColumns = 0;\n\n  /**\n   * Re-pack when a descendant resource finishes loading. Images/iframes report a\n   * height of 0 until loaded, which would skew the shortest-column packing if the\n   * first pass ran before they settled; `load` does not bubble, so this is bound in\n   * the capture phase to catch every descendant.\n   */\n  readonly #onLoad = (): void => this.#relayout();\n\n  /** Observes size/content changes and performs the first layout pass. */\n  override connect(): void {\n    this.#layout.observe(this.element);\n    this.#layout.observeViewport();\n\n    if (typeof MutationObserver !== \"undefined\") {\n      this.#mutationObserver = new MutationObserver(() => this.#relayout());\n      this.#mutationObserver.observe(this.element, { childList: true, subtree: true });\n    }\n    this.element.addEventListener(\"load\", this.#onLoad, true);\n    this.#relayout();\n  }\n\n  /** Releases both observers and the load listener so nothing fires after detach. */\n  override disconnect(): void {\n    this.#layout.disconnect();\n    this.#mutationObserver?.disconnect();\n    this.#mutationObserver = null;\n    this.element.removeEventListener(\"load\", this.#onLoad, true);\n    this.#lastColumns = 0;\n  }\n\n  /**\n   * Recomputes the column count and assigns every item to the shortest column.\n   * Runs automatically on connect, on resize, on item add/remove, and when a\n   * descendant resource loads (private — there is no public action; the observers\n   * and the capture-phase `load` listener drive it). Items are walked in DOM\n   * order; each lands in the column with the least accumulated height, which\n   * keeps the packing balanced without reordering the DOM.\n   */\n  #relayout(): void {\n    const items = this.itemTargets;\n    const columns = this.#columnCount();\n\n    const heights = new Array<number>(columns).fill(0);\n    for (const item of items) {\n      let shortest = 0;\n      for (let col = 1; col < columns; col++) {\n        if ((heights[col] ?? 0) < (heights[shortest] ?? 0)) shortest = col;\n      }\n      item.setAttribute(\"data-column\", String(shortest));\n      heights[shortest] =\n        (heights[shortest] ?? 0) + item.getBoundingClientRect().height + this.gapValue;\n    }\n\n    this.element.style.setProperty(COLUMNS_PROPERTY, String(columns));\n\n    if (columns !== this.#lastColumns) {\n      this.#lastColumns = columns;\n      this.dispatch(\"layout\", { detail: { columns } });\n    }\n  }\n\n  /**\n   * Derives how many columns fit: `floor((width + gap) / (minColumnWidth + gap))`,\n   * never fewer than one. When the width is unmeasurable (detached, or a layout\n   * engine that reports `0`), it falls back to a single column so every item still\n   * gets a valid `data-column`.\n   */\n  #columnCount(): number {\n    const width = this.element.getBoundingClientRect().width;\n    const denominator = this.minColumnWidthValue + this.gapValue;\n    if (width <= 0 || denominator <= 0) return 1;\n    return Math.max(1, Math.floor((width + this.gapValue) / denominator));\n  }\n}\n"]}