stimeo-ui 0.2.0 → 0.3.0

data/dist/controllers/lazy_frame_controller.js

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

data/dist/controllers/listbox_controller.js

@@ -2,6 +2,45 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/listbox_controller.ts
 
+// src/utils/arrow_step.ts
+function isReservedArrowChord(event, allow = []) {
+  if (!event.key.startsWith("Arrow")) return false;
+  return event.altKey && !allow.includes("alt") || event.ctrlKey && !allow.includes("ctrl") || event.metaKey && !allow.includes("meta") || event.shiftKey && !allow.includes("shift");
+}
+
+// src/utils/microtask_coalescer.ts
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  /** @param run - the single reconciliation pass, invoked at most once per batch. */
+  constructor(run) {
+    this.#run = run;
+  }
+  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
+  activate() {
+    this.#active = true;
+  }
+  /** Closes the window and drops any pending pass; call from `disconnect()`. */
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
+  schedule() {
+    if (!this.#active || this.#queued) return;
+    this.#queued = true;
+    const generation = this.#generation;
+    queueMicrotask(() => {
+      if (generation !== this.#generation || !this.#queued || !this.#active) return;
+      this.#queued = false;
+      this.#run();
+    });
+  }
+};
+
 // src/utils/option_scroll.ts
 function scrollOptionIntoView(list, option) {
   if (list.scrollHeight <= list.clientHeight) return;
@@ -67,27 +106,135 @@ var SafeTimeout = class extends TimerRegistry {
   }
 };
 
+// src/utils/typeahead.ts
+var TYPEAHEAD_RESET_MS = 500;
+var Typeahead = class {
+  /** Timer registry for the pending idle reset; private so `reset()` is the only exit. */
+  #timers = new SafeTimeout();
+  /** Idle window before the query resets, in milliseconds. */
+  #resetMs;
+  /** The accumulated lowercase query, empty when idle. */
+  #query = "";
+  /** Id of the pending reset timer, `0` when none is scheduled. */
+  #timerId = 0;
+  /** @param options - Overrides for the idle window. */
+  constructor({ resetMs = TYPEAHEAD_RESET_MS } = {}) {
+    this.#resetMs = resetMs;
+  }
+  /** The query a search would currently run with; empty while idle. */
+  get query() {
+    return this.#query;
+  }
+  /**
+   * Folds `key` into the query, restarts the idle window, and returns the query to
+   * search with. A repeated character collapses the query to that one character.
+   */
+  push(key) {
+    const char = key.toLowerCase();
+    const repeated = this.#query.length > 0 && [...this.#query].every((c) => c === char);
+    this.#query = repeated ? char : this.#query + char;
+    this.#timers.clear(this.#timerId);
+    this.#timerId = this.#timers.set(() => this.reset(), this.#resetMs);
+    return this.#query;
+  }
+  /** Clears the query and cancels the pending idle reset. */
+  reset() {
+    this.#query = "";
+    this.#timers.clear(this.#timerId);
+    this.#timerId = 0;
+  }
+};
+function isTypeaheadKey(event) {
+  return event.key.length === 1 && event.key !== " " && !event.ctrlKey && !event.metaKey && !event.altKey && !event.isComposing;
+}
+function typeaheadLabel(element, fallbackText) {
+  const label = element.getAttribute("aria-label")?.trim();
+  if (label) return label.toLowerCase();
+  const text = element.textContent ?? "";
+  return text.trim().toLowerCase();
+}
+function findTypeaheadMatch(items, from, query, label = (item) => typeaheadLabel(item)) {
+  if (query === "") return -1;
+  const count = items.length;
+  for (let step = 1; step <= count; step += 1) {
+    const index = ((from + step) % count + count) % count;
+    const candidate = items[index];
+    if (candidate && label(candidate).startsWith(query)) return index;
+  }
+  return -1;
+}
+
 // src/controllers/listbox_controller.ts
-var TYPEAHEAD_TIMEOUT = 500;
 var ListboxController = class extends Controller {
   static targets = ["trigger", "value", "list", "option", "field"];
   static actions = ["close", "onTriggerKeydown", "open", "select", "toggle"];
   static events = ["change"];
-  /** Index of the active option, or -1 when none is active. */
-  #activeIndex = -1;
-  /** Accumulated typeahead query, reset after {@link TYPEAHEAD_TIMEOUT} ms. */
-  #typeahead = "";
-  #typeaheadTimer = 0;
-  #timers = new SafeTimeout();
-  /** Starts closed and registers the outside-click listener. */
+  /** Stable ID of the active option; DOM targets are resolved afresh before use. */
+  #activeId = null;
+  /** Target ID order captured while an option is active, used only for removal fallback. */
+  #activeOrder = [];
+  #connected = false;
+  /** Collapses one mutation batch of target callbacks into a single pass. */
+  #reconcile = new MicrotaskCoalescer(() => this.#reconcileActive());
+  /** Accumulated typeahead query and its idle-reset timer. */
+  #typeahead = new Typeahead();
+  /** Establishes the ARIA baseline, starts closed, and listens for outside clicks. */
   connect() {
+    this.#normalizeSelection();
     this.close();
-    document.addEventListener("click", this.#onOutsideClick);
+    document.addEventListener("click", this.#onOutsideClick, true);
+    this.#connected = true;
+    this.#reconcile.activate();
+  }
+  /**
+   * Establishes an inactive baseline for a late option, re-resolves active
+   * identity, and re-applies the selection baseline.
+   */
+  optionTargetConnected(option) {
+    option.removeAttribute("data-active");
+    if (!this.#connected) return;
+    this.#normalizeSelection();
+    this.#queueOptionReconciliation();
+  }
+  /** Removes controller-owned active state and reconciles the surviving targets. */
+  optionTargetDisconnected(option) {
+    option.removeAttribute("data-active");
+    if (this.#connected) this.#queueOptionReconciliation();
+  }
+  /**
+   * Brings the authored DOM to the shape the APG requires, and derives the state
+   * that follows from the initial selection.
+   *
+   * Three things happen, and only these three — which option is chosen is the
+   * author's, and is never changed:
+   *
+   * 1. Every option gets an explicit value. An absent `aria-selected` means "not
+   *    selectable" in ARIA, so a forgotten attribute hides a selectable option
+   *    from assistive technology.
+   * 2. At most one stays `true`. The first in DOM order wins, since that is the
+   *    only deterministic reading of "which one did the author mean".
+   * 3. The trigger label and the hidden field are derived from that selection.
+   *    Without this the widget announces a choice it does not submit: the popup
+   *    says "Banana", the trigger still says "Choose…", and the form posts "".
+   *
+   * No `change` fires — nothing changed, this is the initial state being told
+   * properly. The scan is the `option` target set: a `role="option"` without the
+   * target is outside the contract and is neither counted nor written.
+   */
+  #normalizeSelection() {
+    const options = this.optionTargets;
+    const selected = options.find((option) => option.getAttribute("aria-selected") === "true");
+    for (const option of options) {
+      option.setAttribute("aria-selected", option === selected ? "true" : "false");
+    }
+    if (selected) this.#applySelection(selected);
   }
   /** Removes the document listener and clears the typeahead timer. */
   disconnect() {
-    document.removeEventListener("click", this.#onOutsideClick);
-    this.#timers.clearAll();
+    this.#connected = false;
+    this.#reconcile.cancel();
+    document.removeEventListener("click", this.#onOutsideClick, true);
+    this.#typeahead.reset();
   }
   /**
    * Toggles the list on a real mouse click. Keyboard activation of the
@@ -102,9 +249,14 @@ var ListboxController = class extends Controller {
       this.close();
     }
   }
-  /** Routes trigger keyboard interaction per the APG select-only model. */
+  /** Yields claimed keys; otherwise routes the APG select-only keyboard model. */
   onTriggerKeydown(event) {
-    const length = this.optionTargets.length;
+    if (event.defaultPrevented) return;
+    if (isReservedArrowChord(event)) return;
+    if (!this.#isClosed) this.#reconcileActive();
+    const options = this.optionTargets;
+    const length = options.length;
+    const activeIndex = this.#findActiveIndex(options);
     if (this.#isClosed) {
       switch (event.key) {
         case "Enter":
@@ -123,13 +275,11 @@ var ListboxController = class extends Controller {
     switch (event.key) {
       case "ArrowDown":
         event.preventDefault();
-        this.#setActive(this.#activeIndex < 0 ? 0 : (this.#activeIndex + 1) % length);
+        this.#setActive(activeIndex < 0 ? 0 : (activeIndex + 1) % length);
         break;
       case "ArrowUp":
         event.preventDefault();
-        this.#setActive(
-          this.#activeIndex < 0 ? length - 1 : (this.#activeIndex - 1 + length) % length
-        );
+        this.#setActive(activeIndex < 0 ? length - 1 : (activeIndex - 1 + length) % length);
         break;
       case "Home":
         event.preventDefault();
@@ -145,7 +295,7 @@ var ListboxController = class extends Controller {
         this.#commitActive();
         break;
       case "Escape":
-        if (event.defaultPrevented || event.isComposing) break;
+        if (event.isComposing) break;
         event.preventDefault();
         this.close();
         this.triggerTarget.focus();
@@ -154,9 +304,9 @@ var ListboxController = class extends Controller {
         this.close();
         break;
       default:
-        if (this.#isPrintable(event)) {
+        if (isTypeaheadKey(event)) {
           event.preventDefault();
-          this.#typeaheadTo(event.key);
+          this.#typeaheadTo(options, activeIndex, event.key);
         }
         break;
     }
@@ -164,7 +314,7 @@ var ListboxController = class extends Controller {
   /** Selects the clicked option and closes, returning focus to the trigger. */
   select(event) {
     const option = event.currentTarget.closest('[role="option"]');
-    if (!option) return;
+    if (!option || !this.optionTargets.includes(option)) return;
     this.#selectOption(option);
     this.close();
     this.triggerTarget.focus();
@@ -189,28 +339,41 @@ var ListboxController = class extends Controller {
     this.listTarget.hidden = true;
     this.triggerTarget.setAttribute("aria-expanded", "false");
     this.#setActive(-1);
-    this.#resetTypeahead();
+    this.#typeahead.reset();
   }
   /** Commits the active option (keyboard) and closes, returning focus. */
   #commitActive() {
-    const option = this.#activeIndex < 0 ? void 0 : this.optionTargets[this.#activeIndex];
+    this.#reconcileActive();
+    const options = this.optionTargets;
+    const activeIndex = this.#findActiveIndex(options);
+    const option = activeIndex < 0 ? void 0 : options[activeIndex];
     if (option) this.#selectOption(option);
     this.close();
     this.triggerTarget.focus();
   }
   /** Applies selection: `aria-selected`, trigger label, hidden field, `change`. */
   #selectOption(option) {
+    const { value, fieldChanged } = this.#applySelection(option);
+    if (fieldChanged) {
+      this.fieldTarget.dispatchEvent(new Event("change", { bubbles: true }));
+    }
+    this.dispatch("change", { detail: { value, option } });
+  }
+  /**
+   * Writes `option` into `aria-selected`, the trigger label and the hidden field.
+   * Emits nothing — {@link #normalizeSelection} reuses this at connect, where the
+   * state is being described rather than changed.
+   */
+  #applySelection(option) {
     for (const candidate of this.optionTargets) {
       candidate.setAttribute("aria-selected", candidate === option ? "true" : "false");
     }
     const label = (option.textContent ?? "").trim();
     const value = option.dataset.value ?? label;
     if (this.hasValueTarget) this.valueTarget.textContent = label;
-    if (this.hasFieldTarget && this.fieldTarget.value !== value) {
-      this.fieldTarget.value = value;
-      this.fieldTarget.dispatchEvent(new Event("change", { bubbles: true }));
-    }
-    this.dispatch("change", { detail: { value, option } });
+    const fieldChanged = this.hasFieldTarget && this.fieldTarget.value !== value;
+    if (fieldChanged) this.fieldTarget.value = value;
+    return { value, fieldChanged };
   }
   /**
    * Marks the option at `index` active via `data-active` and the trigger's
@@ -218,47 +381,88 @@ var ListboxController = class extends Controller {
    * set to empty, per the APG).
    */
   #setActive(index) {
-    this.#activeIndex = index;
-    const active = index < 0 ? null : this.optionTargets[index];
-    for (const option of this.optionTargets) {
+    const options = this.optionTargets;
+    const active = index < 0 ? null : options[index] ?? null;
+    for (const option of options) {
+      const marked = option.hasAttribute("data-active");
       if (option === active) {
-        option.setAttribute("data-active", "");
-      } else {
+        if (!marked) option.setAttribute("data-active", "");
+      } else if (marked) {
         option.removeAttribute("data-active");
       }
     }
     if (active?.id) {
+      this.#activeId = active.id;
       this.triggerTarget.setAttribute("aria-activedescendant", active.id);
     } else {
+      this.#activeId = null;
       this.triggerTarget.removeAttribute("aria-activedescendant");
     }
+    this.#activeOrder = active ? options.map((option) => option.id).filter(Boolean) : [];
     if (active && this.hasListTarget) scrollOptionIntoView(this.listTarget, active);
   }
-  /** Appends a character to the typeahead query and activates the first match. */
-  #typeaheadTo(char) {
-    this.#timers.clear(this.#typeaheadTimer);
-    this.#typeahead += char.toLowerCase();
-    this.#typeaheadTimer = this.#timers.set(() => {
-      this.#typeahead = "";
-    }, TYPEAHEAD_TIMEOUT);
-    const index = this.optionTargets.findIndex(
-      (option) => (option.textContent ?? "").trim().toLowerCase().startsWith(this.#typeahead)
-    );
-    if (index !== -1) this.#setActive(index);
+  /** Resolves active state against the current target collection. */
+  #reconcileActive() {
+    if (!this.hasTriggerTarget || this.#isClosed) {
+      if (this.hasTriggerTarget) this.#setActive(-1);
+      return;
+    }
+    const options = this.optionTargets;
+    const currentIndex = this.#findActiveIndex(options);
+    if (currentIndex >= 0) {
+      const active = options[currentIndex] ?? null;
+      const marked = options.filter((option) => option.hasAttribute("data-active"));
+      const stateMatches = this.#activeId === (active?.id || null) && marked.length === 1 && marked[0] === active && this.triggerTarget.getAttribute("aria-activedescendant") === (active?.id || null);
+      if (stateMatches) {
+        this.#activeOrder = options.map((option) => option.id).filter(Boolean);
+      } else {
+        this.#setActive(currentIndex);
+      }
+      return;
+    }
+    const activeId = this.triggerTarget.getAttribute("aria-activedescendant") ?? this.#activeId;
+    this.#setActive(activeId ? this.#findFallbackIndex(options, activeId) : -1);
+  }
+  /** Finds the live target carrying the stable ID, or the active marker for an ID-less option. */
+  #findActiveIndex(options) {
+    const activeId = (this.hasTriggerTarget ? this.triggerTarget.getAttribute("aria-activedescendant") : null) ?? this.#activeId;
+    if (activeId) return options.findIndex((option) => option.id === activeId);
+    return options.findIndex((option) => option.hasAttribute("data-active"));
   }
-  /** Clears the typeahead query and its pending reset timer. */
-  #resetTypeahead() {
-    this.#timers.clear(this.#typeaheadTimer);
-    this.#typeahead = "";
+  /** Chooses a surviving former successor, then a former predecessor. */
+  #findFallbackIndex(options, activeId) {
+    const oldIndex = this.#activeOrder.indexOf(activeId);
+    if (oldIndex < 0) return -1;
+    const indexesById = new Map(options.map((option, index) => [option.id, index]));
+    for (let index = oldIndex + 1; index < this.#activeOrder.length; index += 1) {
+      const fallback = indexesById.get(this.#activeOrder[index] ?? "");
+      if (fallback !== void 0) return fallback;
+    }
+    for (let index = oldIndex - 1; index >= 0; index -= 1) {
+      const fallback = indexesById.get(this.#activeOrder[index] ?? "");
+      if (fallback !== void 0) return fallback;
+    }
+    return -1;
   }
-  /** Closes the list when a click lands outside the controller element. */
+  /** Coalesces all target callbacks from one MutationObserver batch. */
+  #queueOptionReconciliation() {
+    this.#reconcile.schedule();
+  }
+  /**
+   * Advances the typeahead query and activates the next matching option.
+   *
+   * The search resumes just after the active option so repeating a character
+   * cycles through the options starting with it, rather than re-activating the
+   * same first match on every press.
+   */
+  #typeaheadTo(options, activeIndex, char) {
+    const index = findTypeaheadMatch(options, activeIndex, this.#typeahead.push(char));
+    if (index !== -1) this.#setActive(index);
+  }
+  /** Closes on an outside click before an inside handler can detach its target. */
   #onOutsideClick = (event) => {
     if (!this.#isClosed && !this.element.contains(event.target)) this.close();
   };
-  /** Whether `event.key` is a single printable character (no modifier chord). */
-  #isPrintable(event) {
-    return event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey;
-  }
   /** Whether the list is currently hidden. */
   get #isClosed() {
     return !this.hasListTarget || this.listTarget.hidden !== false;

data/dist/controllers/local_time_controller.js

@@ -32,8 +32,8 @@ var LocalTimeController = class extends Controller {
     return Number.isNaN(ms) ? null : new Date(ms);
   }
   /**
-   * Reads a timezone-less date-time as UTC — the documented input contract —
-   * since `Date.parse` would otherwise interpret e.g. `"2026-06-08T12:30:00"` in
+   * Reads a timezone-less date-time as UTC — the input contract of this
+   * controller — since `Date.parse` would otherwise read `"2026-06-08T12:30:00"` in
    * the *runtime's* local zone, contradicting "the server emits UTC". Values that
    * already carry `Z` or a `±hh:mm` offset (and bare `YYYY-MM-DD` dates, already
    * parsed as UTC) are returned unchanged.

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