stimeo-ui 0.11.0 → 0.12.0

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 } });
   }
 };