stimeo-ui 0.11.0 → 0.13.0

data/dist/controllers/optimistic_controller.js

@@ -1,32 +1,115 @@
 import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/optimistic_controller.ts
-var TOGGLED_MARKER = "data-optimistic-toggled";
+
+// src/utils/detach_gate.ts
+var DetachGate = class _DetachGate {
+  /** Set while a probe is queued, waiting for a reconnect to cancel it. */
+  #pending = false;
+  /**
+   * True while a probe is queued — the last disconnect was ambiguous and no
+   * reconnect has cancelled it yet. Read it from `connect()` to tell the
+   * reconnect half of an in-page move from a first connect: a controller whose
+   * initialisation restarts a measurement (a min-duration floor, an elapsed
+   * counter) must skip it for the move, where nothing actually restarted.
+   */
+  get pending() {
+    return this.#pending;
+  }
+  /**
+   * True when the disconnect is definitely a real detach — the element left
+   * the document, or `data-controller` no longer lists the identifier. False
+   * means ambiguous (in-page move or observed-root exit), NOT "alive".
+   */
+  static isDetached(host) {
+    if (!host.element.isConnected) return true;
+    const tokens = (host.element.getAttribute("data-controller") ?? "").split(/\s+/);
+    return !tokens.includes(host.identifier);
+  }
+  /**
+   * Call from `disconnect()`: runs `teardown` synchronously on a definite
+   * detach (fast path), otherwise defers it one microtask — a reconnect
+   * ({@link cancel} from `connect()`) keeps the state, no reconnect runs it.
+   * One microtask is the whole probe window: Stimulus reconnects a moved
+   * element within the same mutation batch, before the checkpoint drains.
+   */
+  disconnected(host, teardown) {
+    if (_DetachGate.isDetached(host)) {
+      this.#pending = false;
+      teardown();
+      return;
+    }
+    this.#pending = true;
+    queueMicrotask(() => {
+      if (!this.#pending) return;
+      this.#pending = false;
+      teardown();
+    });
+  }
+  /**
+   * Disarms a pending probe. Call from `connect()` (the reconnect that proves
+   * an in-page move) and from the head of any teardown path not routed through
+   * {@link disconnected} (disabled-toggle, Escape), so an orphaned probe can
+   * never run the teardown a second time.
+   */
+  cancel() {
+    this.#pending = false;
+  }
+};
+
+// src/controllers/optimistic_controller.ts
+var HIDDEN_MARKER = "data-optimistic-toggled";
+var BUSY_MARKER = "data-optimistic-busy";
+var AUTHORED_ABSENT = "absent";
+var AUTHORED_VALUE = "value:";
+var SYNTHETIC_SUBMISSION = {};
+function submissionOf(event) {
+  const detail = event.detail;
+  return detail?.formSubmission ?? SYNTHETIC_SUBMISSION;
+}
 var OptimisticController = class extends Controller {
   static targets = ["show", "hide"];
   static events = ["commit", "rollback"];
+  /** The submission that owns the applied optimistic state, if any. */
+  #pending = null;
+  #gate = new DetachGate();
+  /** True between `connect()` and `disconnect()`, so a repeat connect rewinds nothing. */
+  #connected = false;
   connect() {
-    if (this.element.hasAttribute("data-optimistic")) this.#revert();
+    const restored = !this.#connected && !this.#gate.pending;
+    this.#gate.cancel();
+    this.#connected = true;
+    if (restored && this.element.hasAttribute("data-optimistic")) this.#revert();
     this.element.addEventListener("turbo:submit-start", this.#onSubmitStart);
     this.element.addEventListener("turbo:submit-end", this.#onSubmitEnd);
   }
   disconnect() {
+    this.#connected = false;
     this.element.removeEventListener("turbo:submit-start", this.#onSubmitStart);
     this.element.removeEventListener("turbo:submit-end", this.#onSubmitEnd);
+    this.#gate.disconnected(this, () => {
+      this.#pending = null;
+    });
   }
-  #onSubmitStart = () => {
+  #onSubmitStart = (event) => {
+    this.#pending = submissionOf(event);
+    if (this.element instanceof HTMLFormElement && !this.element.hasAttribute(BUSY_MARKER)) {
+      this.element.setAttribute(BUSY_MARKER, AUTHORED_ABSENT);
+    }
+    this.#write(this.element, "aria-busy", "true", BUSY_MARKER);
     this.element.setAttribute("data-optimistic", "true");
-    this.element.setAttribute("aria-busy", "true");
-    for (const target of this.showTargets) this.#toggleHidden(target, false);
-    for (const target of this.hideTargets) this.#toggleHidden(target, true);
+    for (const target of this.showTargets) this.#setHidden(target, false);
+    for (const target of this.hideTargets) this.#setHidden(target, true);
   };
   #onSubmitEnd = (event) => {
+    if (submissionOf(event) !== this.#pending) return;
+    this.#pending = null;
     const success = event.detail?.success === true;
-    this.element.removeAttribute("aria-busy");
     if (success) {
       this.element.removeAttribute("data-optimistic");
+      this.#restore(this.element, "aria-busy", BUSY_MARKER, "true");
       for (const target of [...this.showTargets, ...this.hideTargets]) {
-        target.removeAttribute(TOGGLED_MARKER);
+        target.removeAttribute(HIDDEN_MARKER);
       }
       this.dispatch("commit");
     } else {
@@ -34,21 +117,59 @@ var OptimisticController = class extends Controller {
       this.dispatch("rollback");
     }
   };
-  /** Sets `hidden` only when it actually changes, marker-tracking the mutation. */
-  #toggleHidden(target, hidden) {
-    if (target.hidden === hidden) return;
-    target.hidden = hidden;
-    target.setAttribute(TOGGLED_MARKER, "true");
+  /** Hides or reveals a target, recording the authored `hidden` on first write. */
+  #setHidden(target, hidden) {
+    if (target.hasAttribute("hidden") === hidden) return;
+    this.#write(target, "hidden", hidden ? "" : null, HIDDEN_MARKER);
+  }
+  /** Writes an attribute, recording what it displaced under `marker` once. */
+  #write(element, attribute, value, marker) {
+    if (!element.hasAttribute(marker)) {
+      const authored = element.getAttribute(attribute);
+      element.setAttribute(
+        marker,
+        authored === null ? AUTHORED_ABSENT : `${AUTHORED_VALUE}${authored}`
+      );
+    }
+    if (value === null) element.removeAttribute(attribute);
+    else element.setAttribute(attribute, value);
   }
-  /** Reverts exactly the mutations this controller made (marker-owned only). */
+  /**
+   * Puts back the value `marker` recorded and drops the record.
+   *
+   * `written` is what this controller last put in the attribute. Anything else
+   * there now belongs to whoever wrote it — Turbo owns `aria-busy` on a form and
+   * clears it before the terminal arrives, and a consumer may have moved a face
+   * mid-flight — so the record is dropped without touching the attribute. A
+   * marker this build did not write names no authored value, so the attribute
+   * goes back to being absent.
+   */
+  #restore(element, attribute, marker, written) {
+    const recorded = element.getAttribute(marker);
+    if (recorded === null) return;
+    element.removeAttribute(marker);
+    if (element.getAttribute(attribute) !== written) return;
+    if (recorded.startsWith(AUTHORED_VALUE)) {
+      element.setAttribute(attribute, recorded.slice(AUTHORED_VALUE.length));
+      return;
+    }
+    element.removeAttribute(attribute);
+  }
+  /**
+   * Puts back exactly the markup this controller displaced (record-owned only).
+   *
+   * A face can be registered on both sides, and the hide pass runs last, so what
+   * this controller wrote there is `hidden` — matching it against the reveal's
+   * absent value instead would read as someone else's write and leave the face
+   * hidden. Each target is therefore restored once, against the write it last
+   * received.
+   */
   #revert() {
     this.element.removeAttribute("data-optimistic");
-    this.element.removeAttribute("aria-busy");
-    for (const target of [...this.showTargets, ...this.hideTargets]) {
-      if (target.hasAttribute(TOGGLED_MARKER)) {
-        target.hidden = !target.hidden;
-        target.removeAttribute(TOGGLED_MARKER);
-      }
+    this.#restore(this.element, "aria-busy", BUSY_MARKER, "true");
+    const hidden = new Set(this.hideTargets);
+    for (const target of /* @__PURE__ */ new Set([...this.showTargets, ...this.hideTargets])) {
+      this.#restore(target, "hidden", HIDDEN_MARKER, hidden.has(target) ? "" : null);
     }
   }
 };

data/dist/controllers/pointer_drag_controller.js

@@ -255,6 +255,10 @@ var PointerDragController = class _PointerDragController extends Controller {
       return;
     }
     if (!this.#keyboard) return;
+    if (event.key === "Home" || event.key === "End") {
+      event.preventDefault();
+      return;
+    }
     const step = this.#keyboardDelta(event.key);
     if (!step) return;
     event.preventDefault();

data/dist/controllers/reading_progress_controller.js

@@ -1,12 +1,158 @@
 import { Controller } from '@hotwired/stimulus';
 
+// src/controllers/reading_progress_controller.ts
+
+// src/utils/before_cache_reset.ts
+var BeforeCacheReset = class _BeforeCacheReset {
+  /** Every subscribed instance, iterated by the one shared document listener. */
+  static #subscribers = /* @__PURE__ */ new Set();
+  /** The shared listener; installed while at least one instance is subscribed. */
+  static #onBeforeCache = () => {
+    for (const subscriber of _BeforeCacheReset.#subscribers) subscriber.#rewind();
+  };
+  #rewind;
+  /** @param rewind - the pass that returns this controller's state to its initial form. */
+  constructor(rewind) {
+    this.#rewind = rewind;
+  }
+  /** Subscribes to `turbo:before-cache`; call from `connect()`. Idempotent. */
+  activate() {
+    const first = _BeforeCacheReset.#subscribers.size === 0;
+    _BeforeCacheReset.#subscribers.add(this);
+    if (first) {
+      document.addEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+    }
+  }
+  /** Unsubscribes; call from `disconnect()`. Safe when never subscribed. */
+  deactivate() {
+    _BeforeCacheReset.#subscribers.delete(this);
+    if (_BeforeCacheReset.#subscribers.size > 0) return;
+    document.removeEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+  }
+};
+
+// 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/utils/style_property_lease.ts
+var StylePropertyLease = class {
+  #property;
+  #records = /* @__PURE__ */ new Map();
+  /** @param property - The CSS property whose temporary values this lease owns. */
+  constructor(property) {
+    this.#property = property;
+  }
+  /** Writes or removes the leased declaration while preserving its authored value. */
+  write(element, value, priority = "") {
+    const existing = this.#records.get(element);
+    if (existing) {
+      existing.writtenValue = value;
+      existing.writtenPriority = value === null ? "" : priority;
+    } else {
+      this.#records.set(element, {
+        originalValue: element.style.getPropertyValue(this.#property),
+        originalPriority: element.style.getPropertyPriority(this.#property),
+        writtenValue: value,
+        writtenPriority: value === null ? "" : priority
+      });
+    }
+    this.#reflect(element, value, priority);
+  }
+  /** Returns one lease without overwriting a later consumer declaration. */
+  return(element) {
+    const record = this.#records.get(element);
+    if (!record) return;
+    this.#records.delete(element);
+    const style = element.style;
+    const stillOwned = style.getPropertyValue(this.#property) === (record.writtenValue ?? "") && style.getPropertyPriority(this.#property) === record.writtenPriority;
+    if (stillOwned) {
+      this.#reflect(element, record.originalValue, record.originalPriority);
+    }
+  }
+  /** Returns every outstanding declaration lease. */
+  returnAll() {
+    for (const element of Array.from(this.#records.keys())) this.return(element);
+  }
+  /** Reflects only a real declaration transition. */
+  #reflect(element, value, priority) {
+    const style = element.style;
+    const nextValue = value ?? "";
+    const nextPriority = value === null ? "" : priority;
+    if (style.getPropertyValue(this.#property) === nextValue && style.getPropertyPriority(this.#property) === nextPriority) {
+      return;
+    }
+    if (value === null) style.removeProperty(this.#property);
+    else style.setProperty(this.#property, value, priority);
+  }
+};
+
 // src/controllers/reading_progress_controller.ts
 var PROGRESS_PROPERTY = "--stimeo--reading-progress";
 var ReadingProgressController = class extends Controller {
   static events = ["change", "complete"];
+  /** Owns both faces of the published property so teardown can hand them back. */
+  #lease = new StylePropertyLease(PROGRESS_PROPERTY);
+  /** The article's own box and the viewport: either changes the span. */
+  #layout = new LayoutObserver(() => this.#onScroll());
+  #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
   #frame = null;
   /** Last published progress, so `change`/`complete` fire only on movement. */
   #progress = -1;
+  /** False until the connect frame has run: `complete` needs real reading. */
+  #baselined = false;
   #onScroll = () => {
     if (this.#frame !== null) return;
     this.#frame = requestAnimationFrame(() => {
@@ -16,20 +162,45 @@ var ReadingProgressController = class extends Controller {
   };
   connect() {
     this.#progress = -1;
+    this.#baselined = false;
     window.addEventListener("scroll", this.#onScroll, { passive: true, capture: true });
-    window.addEventListener("resize", this.#onScroll, { passive: true });
+    this.#layout.observe(this.element);
+    this.#layout.observeViewport();
+    this.#beforeCache.activate();
     this.#measure();
+    this.#frame = requestAnimationFrame(() => {
+      this.#frame = null;
+      this.#measure();
+      this.#baselined = true;
+    });
   }
   disconnect() {
     window.removeEventListener("scroll", this.#onScroll, { capture: true });
-    window.removeEventListener("resize", this.#onScroll);
+    this.#layout.disconnect();
+    this.#beforeCache.deactivate();
+    this.#cancelFrame();
+    this.#lease.returnAll();
+  }
+  /**
+   * Hands both declarations back before the page is snapshotted, so a restored
+   * page starts from the authored DOM rather than from someone else's progress.
+   * The baseline goes back with them: a cancelled visit leaves this page on
+   * screen, and the next measurement has to publish afresh rather than match a
+   * value that has already been handed back.
+   */
+  #rewindForCache() {
+    this.#cancelFrame();
+    this.#lease.returnAll();
+    this.#progress = -1;
+  }
+  #cancelFrame() {
     if (this.#frame !== null) cancelAnimationFrame(this.#frame);
     this.#frame = null;
-    document.documentElement.style.removeProperty(PROGRESS_PROPERTY);
   }
   /** Computes and publishes the progress; emits on movement only. */
   #measure() {
     const rect = this.element.getBoundingClientRect();
+    if (rect.width === 0 && rect.height === 0) return;
     const span = rect.height - window.innerHeight;
     const raw = span > 0 ? -rect.top / span : rect.top <= 0 ? 1 : 0;
     const progress = Math.min(1, Math.max(0, raw));
@@ -37,10 +208,10 @@ var ReadingProgressController = class extends Controller {
     const previous = this.#progress;
     this.#progress = progress;
     const value = String(progress);
-    this.element.style.setProperty(PROGRESS_PROPERTY, value);
-    document.documentElement.style.setProperty(PROGRESS_PROPERTY, value);
+    this.#lease.write(this.element, value);
+    this.#lease.write(document.documentElement, value);
     this.dispatch("change", { detail: { progress } });
-    if (progress === 1 && previous !== -1) this.dispatch("complete");
+    if (progress === 1 && previous !== -1 && this.#baselined) this.dispatch("complete");
   }
 };
 

data/dist/controllers/scrollspy_controller.js

@@ -3,6 +3,14 @@ import { Controller } from '@hotwired/stimulus';
 // src/controllers/scrollspy_controller.ts
 
 // src/utils/intersection_watcher.ts
+function queryRoot(selector) {
+  if (!selector) return null;
+  try {
+    return document.querySelector(selector);
+  } catch {
+  }
+  return null;
+}
 var IntersectionWatcher = class {
   #onEntries;
   #observer = null;
@@ -24,7 +32,10 @@ var IntersectionWatcher = class {
    * 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.
+   * warns and retries once with the same root and platform defaults. A
+   * `rootSelector` that does not parse resolves to the viewport (see
+   * {@link IntersectionWatchOptions.rootSelector}), so a typo never fails the
+   * call.
    *
    * @throws The fallback constructor error if both construction attempts fail,
    *   or whatever the platform throws from `observe()`. The exception is passed
@@ -37,7 +48,7 @@ var IntersectionWatcher = class {
     if (typeof IntersectionObserver === "undefined") return false;
     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;
+    const root = "root" in options ? options.root ?? null : queryRoot(options.rootSelector);
     let observer = null;
     try {
       const onEntries = (entries) => {

data/dist/controllers/smart_sticky_header_controller.js

@@ -1,19 +1,32 @@
 import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/smart_sticky_header_controller.ts
+var DEFAULT_OFFSET = 80;
 var SmartStickyHeaderController = class extends Controller {
   static values = {
     containerSelector: { type: String, default: "" },
-    offset: { type: Number, default: 80 },
+    offset: { type: Number, default: DEFAULT_OFFSET },
     tolerance: { type: Number, default: 4 }
   };
   static events = ["change"];
+  #connected = false;
   #frame = null;
   /** The scroll source resolved at connect — disconnect must unbind the SAME node. */
   #scrollerEl = window;
+  /** The validated `containerSelector`, or `""` when the declaration cannot be parsed. */
+  #containerSelector = "";
   #lastY = 0;
   /** Last published state, so `change` fires only on transitions. */
   #hidden = null;
+  /**
+   * The depth that never hides. A declaration that is not a finite number reads
+   * as the default, so the comparison path never sees `NaN` — which would
+   * answer `false` to every comparison and hide the header inside the very
+   * zone the value exists to protect.
+   */
+  get #offset() {
+    return Number.isFinite(this.offsetValue) ? this.offsetValue : DEFAULT_OFFSET;
+  }
   #onScroll = () => {
     if (this.#frame !== null) return;
     this.#frame = requestAnimationFrame(() => {
@@ -26,15 +39,25 @@ var SmartStickyHeaderController = class extends Controller {
    * hold while focus *stays* inside is the `#apply` hide invariant.
    */
   #onFocusin = () => this.#apply(false);
+  /** Validates `containerSelector` once so connect never parses a selector that throws. */
+  containerSelectorValueChanged() {
+    this.#containerSelector = this.#validSelector(this.containerSelectorValue);
+  }
+  /** Re-decides when application code (or a Turbo morph) changes `offset` at runtime. */
+  offsetValueChanged() {
+    if (this.#connected) this.#measure();
+  }
   connect() {
     this.#hidden = null;
     this.#scrollerEl = this.#resolveScroller();
     this.#lastY = this.#scrollY;
     this.#scrollerEl.addEventListener("scroll", this.#onScroll, { passive: true });
     this.element.addEventListener("focusin", this.#onFocusin);
-    this.#apply(false);
+    this.#apply(false, false);
+    this.#connected = true;
   }
   disconnect() {
+    this.#connected = false;
     this.#scrollerEl.removeEventListener("scroll", this.#onScroll);
     this.element.removeEventListener("focusin", this.#onFocusin);
     if (this.#frame !== null) cancelAnimationFrame(this.#frame);
@@ -42,32 +65,51 @@ var SmartStickyHeaderController = class extends Controller {
   }
   /** Resolves the scroll source: the `containerSelector` match, else the window. */
   #resolveScroller() {
-    if (this.containerSelectorValue) {
-      const container = document.querySelector(this.containerSelectorValue);
+    if (this.#containerSelector) {
+      const container = document.querySelector(this.#containerSelector);
       if (container) return container;
     }
     return window;
   }
+  /** Returns `declared` when it parses as a selector, and `""` when it does not. */
+  #validSelector(declared) {
+    if (declared.length > 0) {
+      try {
+        this.element.matches(declared);
+        return declared;
+      } catch {
+      }
+    }
+    return "";
+  }
   get #scrollY() {
     const scroller = this.#scrollerEl;
     return scroller === window ? window.scrollY : scroller.scrollTop;
   }
   #measure() {
     const y = this.#scrollY;
+    if (y <= this.#offset) {
+      this.#lastY = y;
+      this.#apply(false);
+      return;
+    }
     const delta = y - this.#lastY;
     if (Math.abs(delta) < this.toleranceValue) return;
     this.#lastY = y;
-    if (y <= this.offsetValue) this.#apply(false);
-    else if (delta > 0) this.#apply(true);
-    else this.#apply(false);
+    this.#apply(delta > 0);
   }
-  /** Reflects the state onto the hook and emits `change` on transitions. */
-  #apply(hidden) {
+  /**
+   * Reflects the state onto the hook and emits `change` on transitions.
+   *
+   * @param notify - whether a transition announces itself. The reflection
+   *   `connect()` performs is the current state, not a change.
+   */
+  #apply(hidden, notify = true) {
     if (hidden && this.element.contains(document.activeElement)) return;
     if (hidden === this.#hidden) return;
     this.#hidden = hidden;
     this.element.setAttribute("data-header-hidden", hidden ? "true" : "false");
-    this.dispatch("change", { detail: { hidden } });
+    if (notify) this.dispatch("change", { detail: { hidden } });
   }
 };