stimeo-ui 0.2.0 → 0.3.0

data/dist/controllers/editable_controller.js

@@ -0,0 +1,169 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/editable_controller.ts
+
+// src/utils/composition_tracker.ts
+var CompositionTracker = class {
+  #observedTargets = /* @__PURE__ */ new Set();
+  #activeTargets = /* @__PURE__ */ new Set();
+  #onStart;
+  #onEnd;
+  constructor(options = {}) {
+    this.#onStart = options.onStart;
+    this.#onEnd = options.onEnd;
+  }
+  /** Starts lifecycle tracking for `target`; repeated calls are idempotent. */
+  observe(target) {
+    if (this.#observedTargets.has(target)) return;
+    target.addEventListener("compositionstart", this.#handleStart);
+    target.addEventListener("compositionend", this.#handleEnd);
+    this.#observedTargets.add(target);
+  }
+  /** Stops tracking one target and clears any active composition it owned. */
+  unobserve(target) {
+    if (!this.#observedTargets.delete(target)) return;
+    target.removeEventListener("compositionstart", this.#handleStart);
+    target.removeEventListener("compositionend", this.#handleEnd);
+    this.#activeTargets.delete(target);
+  }
+  /** Releases every listener and clears state so reconnect starts cleanly. */
+  disconnect() {
+    for (const target of this.#observedTargets) {
+      target.removeEventListener("compositionstart", this.#handleStart);
+      target.removeEventListener("compositionend", this.#handleEnd);
+    }
+    this.#observedTargets.clear();
+    this.#activeTargets.clear();
+  }
+  /** True when lifecycle tracking or the current event reports composition. */
+  isComposing(event) {
+    return this.#activeTargets.size > 0 || event?.isComposing === true;
+  }
+  #handleStart = (event) => {
+    if (event.currentTarget) this.#activeTargets.add(event.currentTarget);
+    this.#onStart?.(event);
+  };
+  #handleEnd = (event) => {
+    if (event.currentTarget) this.#activeTargets.delete(event.currentTarget);
+    this.#onEnd?.(event);
+  };
+};
+
+// src/controllers/editable_controller.ts
+var EditableController = class extends Controller {
+  static targets = ["display", "input"];
+  static values = {
+    submitOnBlur: { type: Boolean, default: true }
+  };
+  static actions = ["edit", "onBlur", "onDisplayKeydown", "onKeydown"];
+  static events = ["cancel", "change"];
+  /** The value captured when edit mode began, used to detect real changes. */
+  #previousValue = "";
+  /**
+   * Owns IME lifecycle state for the edit surface, so a keydown that belongs to
+   * a composition (cancel or confirm) is never treated as an edit command.
+   */
+  #composition = new CompositionTracker();
+  /** Establishes the initial display mode (display shown, input hidden). */
+  connect() {
+    if (this.hasInputTarget) this.#composition.observe(this.inputTarget);
+    this.#setMode("display");
+  }
+  /** Releases the composition listeners so nothing outlives the element. */
+  disconnect() {
+    this.#composition.disconnect();
+  }
+  /** Tracks an input added initially or after connect (e.g. a Turbo swap). */
+  inputTargetConnected(input) {
+    this.#composition.observe(input);
+  }
+  /** Removes composition listeners when the active input is replaced or removed. */
+  inputTargetDisconnected(input) {
+    this.#composition.unobserve(input);
+  }
+  /** Enters edit mode: seeds the input from the display text, focuses, selects. */
+  edit() {
+    if (this.#isEditing || !this.hasInputTarget || !this.hasDisplayTarget) return;
+    this.#previousValue = this.#currentValue;
+    this.inputTarget.value = this.#previousValue;
+    this.#setMode("editing");
+    this.inputTarget.focus();
+    this.inputTarget.select();
+  }
+  /** Adds `F2` as an editing entry point alongside the button's native activation. */
+  onDisplayKeydown(event) {
+    if (event.key === "F2") {
+      event.preventDefault();
+      this.edit();
+    }
+  }
+  /** Commits on `Enter` (or `Ctrl+Enter` when multiline) and cancels on `Escape`. */
+  onKeydown(event) {
+    if (this.#composition.isComposing(event)) return;
+    if (event.key === "Escape") {
+      if (event.defaultPrevented) return;
+      event.preventDefault();
+      this.#cancel();
+      return;
+    }
+    if (event.key === "Enter") {
+      if (event.defaultPrevented) return;
+      if (this.#isMultiline && !(event.ctrlKey || event.metaKey)) return;
+      event.preventDefault();
+      this.#save(true);
+    }
+  }
+  /** Saves on blur when `submitOnBlur` is set; otherwise keeps editing. */
+  onBlur() {
+    if (!this.#isEditing) return;
+    if (this.submitOnBlurValue) this.#save(false);
+  }
+  /**
+   * Returns to display mode, reflecting the input into the display text and
+   * dispatching `change` when the value differs from where editing began.
+   *
+   * @param restoreFocus - Move focus back to the display element (explicit
+   *   keyboard commit) rather than honoring the user's new focus target (blur).
+   */
+  #save(restoreFocus) {
+    if (!this.#isEditing) return;
+    const value = this.inputTarget.value;
+    const previous = this.#previousValue;
+    this.displayTarget.textContent = value;
+    this.#setMode("display");
+    if (restoreFocus) this.displayTarget.focus();
+    if (value !== previous) {
+      this.dispatch("change", { detail: { value, previous } });
+    }
+  }
+  /** Discards edits, returns to display mode, and dispatches `cancel`. */
+  #cancel() {
+    if (!this.#isEditing) return;
+    this.#setMode("display");
+    this.displayTarget.focus();
+    this.dispatch("cancel", { detail: {} });
+  }
+  /** Toggles the `data-mode` flag and the `hidden` state of both elements. */
+  #setMode(mode) {
+    this.element.dataset.mode = mode;
+    const editing = mode === "editing";
+    if (this.hasDisplayTarget) this.displayTarget.hidden = editing;
+    if (this.hasInputTarget) this.inputTarget.hidden = !editing;
+  }
+  /** Current display text, trimmed — the value shown when not editing. */
+  get #currentValue() {
+    return (this.displayTarget.textContent ?? "").trim();
+  }
+  /** Whether the editing control is a multi-line `<textarea>`. */
+  get #isMultiline() {
+    return this.inputTarget.tagName === "TEXTAREA";
+  }
+  /** Whether the controller is currently in edit mode. */
+  get #isEditing() {
+    return this.element.dataset.mode === "editing";
+  }
+};
+
+export { EditableController };
+//# sourceMappingURL=editable_controller.js.map
+//# sourceMappingURL=editable_controller.js.map

data/dist/controllers/file_dropzone_controller.js

@@ -0,0 +1,165 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/file_dropzone_controller.ts
+var FileDropzoneController = class extends Controller {
+  static targets = ["zone", "trigger", "input", "list", "item", "itemTemplate", "status"];
+  static values = {
+    maxSize: { type: Number, default: 0 },
+    maxFiles: { type: Number, default: 0 },
+    dragLabel: { type: String, default: "Drop files to add them" }
+  };
+  static actions = ["onChange", "onDragLeave", "onDragOver", "onDrop", "openDialog"];
+  static events = ["change", "reject"];
+  /** Selected files paired with their rendered item and any preview objectURL. */
+  #entries = [];
+  /** Wires file removal as a delegated listener on the list container. */
+  connect() {
+    if (this.hasListTarget) this.listTarget.addEventListener("click", this.#onItemClick);
+  }
+  /** Revokes any outstanding preview URLs so none leaks across navigations. */
+  disconnect() {
+    if (this.hasListTarget) this.listTarget.removeEventListener("click", this.#onItemClick);
+    for (const entry of this.#entries) {
+      if (entry.url) URL.revokeObjectURL(entry.url);
+    }
+    this.#entries.length = 0;
+  }
+  /** Opens the native file dialog. Bound via `data-action` (trigger click). */
+  openDialog() {
+    this.inputTarget.click();
+  }
+  /** Adds the files chosen through the native dialog. */
+  onChange() {
+    if (this.inputTarget.files) this.#addFiles(this.inputTarget.files);
+    this.inputTarget.value = "";
+  }
+  /** Marks the zone as a drop target and announces the affordance in words. */
+  onDragOver(event) {
+    event.preventDefault();
+    if (this.hasZoneTarget) this.zoneTarget.setAttribute("data-dragover", "");
+    this.#setStatus(this.dragLabelValue);
+  }
+  /** Clears the drag-over flag when the pointer leaves the zone. */
+  onDragLeave() {
+    if (this.hasZoneTarget) this.zoneTarget.removeAttribute("data-dragover");
+  }
+  /** Accepts dropped files, clearing the drag-over state. */
+  onDrop(event) {
+    event.preventDefault();
+    if (this.hasZoneTarget) this.zoneTarget.removeAttribute("data-dragover");
+    if (event.dataTransfer?.files) this.#addFiles(event.dataTransfer.files);
+  }
+  /**
+   * Removes the file whose remove button was clicked. Delegated on the list
+   * container rather than bound per item via `data-action`, so it works the instant
+   * an item is appended without waiting on Stimulus to wire a freshly created element.
+   */
+  #onItemClick = (event) => {
+    const button = event.target.closest("button");
+    if (!button || !this.hasListTarget || !this.listTarget.contains(button)) return;
+    const index = this.#entries.findIndex((entry) => entry.item.contains(button));
+    if (index !== -1) this.#removeAt(index);
+  };
+  /** Validates each incoming file and renders the accepted ones. */
+  #addFiles(files) {
+    let changed = false;
+    if (this.hasZoneTarget) this.zoneTarget.removeAttribute("data-stimeo--file-dropzone-invalid");
+    for (const file of Array.from(files)) {
+      const reason = this.#validate(file);
+      if (reason) {
+        if (this.hasZoneTarget) {
+          this.zoneTarget.setAttribute("data-stimeo--file-dropzone-invalid", "");
+        }
+        this.#setStatus(file.name);
+        this.dispatch("reject", { detail: { file, reason } });
+        continue;
+      }
+      this.#appendFile(file);
+      this.#setStatus(file.name);
+      changed = true;
+    }
+    if (changed) this.dispatch("change", { detail: { files: this.#files } });
+  }
+  /** Returns the rejection reason for `file`, or `null` when it is acceptable. */
+  #validate(file) {
+    const limit = this.#effectiveMaxFiles;
+    if (limit > 0 && this.#entries.length >= limit) return "count";
+    if (!this.#matchesAccept(file)) return "type";
+    if (this.maxSizeValue > 0 && file.size > this.maxSizeValue) return "size";
+    return null;
+  }
+  /** Builds one preview item (name, optional thumbnail, remove button). */
+  #appendFile(file) {
+    if (!this.hasItemTemplateTarget || !this.hasListTarget) return;
+    const fragment = this.itemTemplateTarget.content.cloneNode(true);
+    const item = fragment.querySelector('[data-stimeo--file-dropzone-target="item"]');
+    const name = fragment.querySelector('[data-file-dropzone-slot="name"]');
+    const thumb = fragment.querySelector('[data-file-dropzone-slot="thumb"]');
+    const button = fragment.querySelector("button");
+    if (!item) return;
+    if (name) name.textContent = file.name;
+    if (button) button.setAttribute("aria-label", `Remove ${file.name}`);
+    let url;
+    if (thumb && file.type.startsWith("image/")) {
+      url = URL.createObjectURL(file);
+      thumb.src = url;
+      thumb.alt = file.name;
+      thumb.hidden = false;
+    } else if (thumb) {
+      thumb.hidden = true;
+    }
+    this.listTarget.appendChild(fragment);
+    this.#entries.push({ file, item, url });
+  }
+  /** Removes entry `index`, revokes its preview, and re-homes focus. */
+  #removeAt(index) {
+    const entry = this.#entries[index];
+    if (!entry) return;
+    if (entry.url) URL.revokeObjectURL(entry.url);
+    entry.item.remove();
+    this.#entries.splice(index, 1);
+    this.#setStatus(entry.file.name);
+    this.dispatch("change", { detail: { files: this.#files } });
+    const buttons = this.#removeButtons;
+    if (buttons.length === 0) {
+      if (this.hasTriggerTarget) this.triggerTarget.focus();
+    } else {
+      (buttons[index] ?? buttons[buttons.length - 1])?.focus();
+    }
+  }
+  /** Whether `file` satisfies the input's `accept` list (empty accepts all). */
+  #matchesAccept(file) {
+    const accept = this.inputTarget.accept.trim();
+    if (accept === "") return true;
+    const name = file.name.toLowerCase();
+    const type = file.type.toLowerCase();
+    return accept.split(",").some((raw) => {
+      const token = raw.trim().toLowerCase();
+      if (token === "") return false;
+      if (token.startsWith(".")) return name.endsWith(token);
+      if (token.endsWith("/*")) return type.startsWith(token.slice(0, -1));
+      return type === token;
+    });
+  }
+  /** Updates the live region so assistive tech announces the change. */
+  #setStatus(text) {
+    if (this.hasStatusTarget) this.statusTarget.textContent = text;
+  }
+  /** Effective file cap: `maxFiles`, or 1 when the input is single-select. */
+  get #effectiveMaxFiles() {
+    if (this.maxFilesValue > 0) return this.maxFilesValue;
+    return this.inputTarget.multiple ? 0 : 1;
+  }
+  /** The remove buttons currently in the list, in order. */
+  get #removeButtons() {
+    return Array.from(this.listTarget.querySelectorAll("button"));
+  }
+  /** The accepted files in selection order. */
+  get #files() {
+    return this.#entries.map((entry) => entry.file);
+  }
+};
+
+export { FileDropzoneController };
+//# sourceMappingURL=file_dropzone_controller.js.map
+//# sourceMappingURL=file_dropzone_controller.js.map

data/dist/controllers/filter_controller.js

@@ -0,0 +1,86 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/filter_controller.ts
+var FilterController = class extends Controller {
+  static targets = ["item", "control", "group", "empty"];
+  static values = { match: { type: String, default: "all" } };
+  static actions = ["apply", "clear"];
+  static events = ["change"];
+  #onChange = () => {
+    this.apply();
+  };
+  connect() {
+    this.apply();
+    this.element.addEventListener("change", this.#onChange);
+  }
+  disconnect() {
+    this.element.removeEventListener("change", this.#onChange);
+  }
+  /** Re-derives every item's visibility from the active tokens and syncs groups/empty. */
+  apply() {
+    const active = this.#activeTokens();
+    let visibleCount = 0;
+    for (const item of this.itemTargets) {
+      const visible = this.#matches(item, active);
+      item.hidden = !visible;
+      if (visible) visibleCount += 1;
+    }
+    for (const group of this.groupTargets) {
+      group.hidden = !this.#hasVisibleItem(group);
+    }
+    for (const empty of this.emptyTargets) {
+      empty.hidden = visibleCount > 0;
+    }
+    this.dispatch("change", {
+      detail: { active, visible: visibleCount, total: this.itemTargets.length }
+    });
+  }
+  /** Turns every control off (uncheck / aria-pressed="false") and re-applies. */
+  clear() {
+    for (const control of this.controlTargets) {
+      if (control instanceof HTMLInputElement) {
+        control.checked = false;
+      } else if (control.hasAttribute("aria-pressed")) {
+        control.setAttribute("aria-pressed", "false");
+      }
+    }
+    this.apply();
+  }
+  /** The tokens of every control currently "on" (checked or aria-pressed="true"). */
+  #activeTokens() {
+    const tokens = [];
+    for (const control of this.controlTargets) {
+      if (this.#isOn(control)) tokens.push(this.#tokenOf(control));
+    }
+    return tokens.filter(Boolean);
+  }
+  /** Whether a control is in its "on" state. */
+  #isOn(control) {
+    if (control instanceof HTMLInputElement) return control.checked;
+    return control.getAttribute("aria-pressed") === "true";
+  }
+  /** A control's token: explicit `data-stimeo--filter-token`, else `data-value` / value. */
+  #tokenOf(control) {
+    const explicit = control.getAttribute("data-stimeo--filter-token") ?? control.dataset.value;
+    if (explicit) return explicit;
+    return control instanceof HTMLInputElement ? control.value : "";
+  }
+  /** Whether an item satisfies the active token set per `match` (empty active → shown). */
+  #matches(item, active) {
+    if (active.length === 0) return true;
+    const tokens = this.#tokensOf(item);
+    return this.matchValue === "any" ? active.some((token) => tokens.includes(token)) : active.every((token) => tokens.includes(token));
+  }
+  /** An item's declared tokens (`data-stimeo--filter-tokens`, space-separated). */
+  #tokensOf(item) {
+    return (item.getAttribute("data-stimeo--filter-tokens") ?? "").split(/\s+/).filter(Boolean);
+  }
+  /** Whether a group still contains at least one non-hidden item. */
+  #hasVisibleItem(group) {
+    return this.itemTargets.some((item) => !item.hidden && group.contains(item));
+  }
+};
+
+export { FilterController };
+//# sourceMappingURL=filter_controller.js.map
+//# sourceMappingURL=filter_controller.js.map

data/dist/controllers/flash_controller.js

@@ -55,6 +55,40 @@ var SafeTimeout = class extends TimerRegistry {
   }
 };
 
+// src/utils/transition_completion.ts
+function timeMs(value) {
+  const trimmed = value.trim();
+  const amount = Number.parseFloat(trimmed);
+  if (!Number.isFinite(amount)) return 0;
+  if (trimmed.endsWith("ms")) return amount;
+  if (trimmed.endsWith("s")) return amount * 1e3;
+  return 0;
+}
+function cssList(value) {
+  return value.split(",").map((item) => item.trim()).filter(Boolean);
+}
+function transitionTimings(style) {
+  const properties = cssList(style.transitionProperty);
+  const durations = cssList(style.transitionDuration).map(timeMs);
+  const delays = cssList(style.transitionDelay).map(timeMs);
+  const effectiveProperties = properties.length > 0 ? properties : Array.from({ length: Math.max(durations.length, delays.length, 1) }, () => "all");
+  const effectiveDurations = durations.length > 0 ? durations : [0];
+  const effectiveDelays = delays.length > 0 ? delays : [0];
+  return effectiveProperties.filter((property) => property !== "none").map((property, index) => ({
+    property,
+    totalMs: Math.max(
+      0,
+      (effectiveDurations[index % effectiveDurations.length] ?? 0) + (effectiveDelays[index % effectiveDelays.length] ?? 0)
+    )
+  }));
+}
+function maxTotalMs(timings) {
+  return timings.reduce((max, { totalMs }) => Math.max(max, totalMs), 0);
+}
+function maxTransitionTotalMs(style) {
+  return maxTotalMs(transitionTimings(style));
+}
+
 // src/controllers/flash_controller.ts
 var ASSERTIVE_TYPES = /* @__PURE__ */ new Set(["alert", "error"]);
 var MESSAGE_SELECTOR = '[data-stimeo--flash-target="message"]';
@@ -206,13 +240,10 @@ var FlashController = class extends Controller {
       finalize();
     }
   }
-  /** First `transition-duration` of `el` in ms (0 when none / unsupported). */
+  /** Maximum transition total (duration + delay) of `el` in ms (0 when none / unsupported). */
   #transitionMs(el) {
     if (typeof window.getComputedStyle !== "function") return 0;
-    const first = window.getComputedStyle(el).transitionDuration.split(",")[0]?.trim() ?? "";
-    const amount = Number.parseFloat(first);
-    if (Number.isNaN(amount)) return 0;
-    return first.endsWith("ms") ? amount : amount * 1e3;
+    return maxTransitionTotalMs(window.getComputedStyle(el));
   }
 };
 

data/dist/controllers/form_validation_controller.js

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

data/dist/controllers/highlight_controller.js

@@ -2,6 +2,11 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/highlight_controller.ts
 
+// src/utils/reduced_motion.ts
+function prefersReducedMotion() {
+  return typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+
 // src/utils/safe_timeout.ts
 var TimerRegistry = class {
   /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
@@ -89,7 +94,7 @@ var HighlightController = class extends Controller {
   }
   /** Flags `el` with `data-highlight` and schedules its removal (unless reduced-motion). */
   #highlight(el) {
-    if (this.#prefersReducedMotion()) return;
+    if (prefersReducedMotion()) return;
     el.setAttribute("data-highlight", "true");
     this.dispatch("start", { target: el, detail: { element: el } });
     this.#timeouts.set(() => {
@@ -97,9 +102,6 @@ var HighlightController = class extends Controller {
       this.dispatch("end", { target: el, detail: { element: el } });
     }, this.durationValue);
   }
-  #prefersReducedMotion() {
-    return typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
-  }
 };
 
 export { HighlightController };

data/dist/controllers/intersection_controller.js

@@ -3,10 +3,17 @@ 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;
   #active = false;
+  #usingPlatformDefaults = false;
   constructor(onEntries) {
     this.#onEntries = onEntries;
   }
@@ -14,10 +21,22 @@ var IntersectionWatcher = class {
   get active() {
     return this.#active;
   }
+  /** Whether the live observer discarded configured options after construction failed. */
+  get usingPlatformDefaults() {
+    return this.#usingPlatformDefaults;
+  }
   /**
    * (Re)creates the observer and observes `targets`. Returns `false` — leaving
    * the watcher inert — without `IntersectionObserver` support (very old
    * browsers; the caller's no-JS fallback stays in charge) or with no targets.
+   * If initial construction with the configured options fails, the watcher
+   * warns and retries once with the same root and platform defaults.
+   *
+   * @throws 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 +44,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;
   }
 };
 
@@ -68,6 +117,8 @@ var IntersectionController = class extends Controller {
   static events = ["enter", "exit", "change", "passed"];
   /** Shared IO plumbing (support guard, root resolution, active guard, re-arm). */
   #watcher = new IntersectionWatcher((entries) => this.#onIntersect(entries));
+  /** Threshold actually installed in the live observer (0 after option fallback). */
+  #effectiveThreshold = 0;
   /** Bumped by `refresh()`: an in-flight batch becomes stale and stops. */
   #generation = 0;
   #onIntersect(entries) {
@@ -75,21 +126,23 @@ var IntersectionController = class extends Controller {
     for (const entry of entries) {
       if (!this.#watcher.active || this.#generation !== generation) return;
       const ratio = entry.intersectionRatio;
-      const threshold = this.#clampedThreshold();
+      const threshold = this.#effectiveThreshold;
       const intersecting = threshold > 0 ? entry.isIntersecting && ratio >= threshold - RATIO_EPSILON : entry.isIntersecting;
       this.element.style.setProperty(RATIO_PROPERTY, String(ratio));
       this.dispatch("change", { detail: { intersecting, ratio } });
       this.#syncIntersecting(intersecting, ratio, entry);
-      this.#syncPassed(!intersecting && this.#isBefore(entry));
+      this.#syncPassed(!intersecting && isBeforeRootStart(entry));
     }
   }
   connect() {
     if (this.onceValue && this.element.getAttribute("data-intersecting") === "true") return;
+    this.#effectiveThreshold = this.#clampedThreshold();
     this.#watcher.start(this.element, {
       rootSelector: this.rootSelectorValue,
       rootMargin: this.rootMarginValue,
       threshold: this.#thresholds()
     });
+    if (this.#watcher.usingPlatformDefaults) this.#effectiveThreshold = 0;
   }
   disconnect() {
     this.#watcher.stop();
@@ -128,7 +181,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 +197,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));