stimeo-ui 0.2.0 → 0.3.0

package/dist/controllers/scrollspy_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,60 +38,140 @@ 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;
   }
 };
 
+// src/utils/reduced_motion.ts
+function prefersReducedMotion() {
+  return typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+
 // src/controllers/scrollspy_controller.ts
+var ANCHOR_ATTRIBUTES = ["href", "data-href"];
 var ScrollspyController = class extends Controller {
   static targets = ["link"];
   static values = {
     offset: { type: Number, default: 0 },
     rootMargin: { type: String, default: "" },
-    rootSelector: { type: String, default: "" }
+    rootSelector: { type: String, default: "" },
+    focusSection: { type: Boolean, default: false }
   };
   static actions = ["scrollTo"];
   static events = ["change"];
+  /**
+   * The one offset shared by observation, active-section selection, and
+   * scrolling. Stimulus parses a malformed Number Value as `NaN`; degrading it
+   * to the declared default keeps every path aligned instead of only repairing
+   * the observer margin while selection and scrolling still receive `NaN`.
+   */
+  get #offset() {
+    return Number.isFinite(this.offsetValue) ? this.offsetValue : 0;
+  }
   /** Shared IO plumbing (support guard, active guard, teardown). */
   #watcher = new IntersectionWatcher((entries) => this.#onIntersection(entries));
   #isConnected = false;
-  /** Track active/intersecting status of each section element by ID. */
+  /**
+   * Sections currently tracked, by id. Only the *latest reported* intersection
+   * flag is stored — never a coordinate. Positions are re-measured when the
+   * active section is evaluated, so a section observed several batches ago is
+   * never compared against a trigger line computed now.
+   */
   #intersectionStates = /* @__PURE__ */ new Map();
-  /** Current active section ID, used to avoid duplicate event dispatching. */
+  /** Current active section ID; comparing it suppresses duplicate `change` events. */
   #activeSectionId = "";
+  /**
+   * Scroll root resolved when the observer was (re)built; `null` = viewport.
+   * Cached so a click and every intersection batch reuse the element the
+   * observer is actually watching instead of re-querying the document.
+   */
+  #rootElement = null;
+  /**
+   * The source the `scroll` listener is currently attached to — the resolved
+   * root, or the window while the viewport is spied. `null` means "nothing
+   * attached", so teardown always detaches from the source it attached to
+   * rather than from whatever the selector resolves to now.
+   */
+  #scrollSource = null;
+  /** Pending re-evaluation frame; coalesces a scroll burst into one measurement. */
+  #frame = null;
+  /** Watches the link targets' anchor attributes for an in-place morph rewrite. */
+  #anchorObserver = null;
+  /** True while a coalesced observation rebuild is queued; see {@link #scheduleResync}. */
+  #resyncQueued = false;
   connect() {
     this.#isConnected = true;
+    this.#observeAnchorAttributes();
     this.#initializeObserver();
   }
   disconnect() {
     this.#isConnected = false;
+    this.#resyncQueued = false;
     this.#watcher.stop();
+    this.#anchorObserver?.disconnect();
+    this.#anchorObserver = null;
+    this.#detachScrollListener();
+    if (this.#frame !== null) {
+      cancelAnimationFrame(this.#frame);
+      this.#frame = null;
+    }
     this.#intersectionStates.clear();
     this.#activeSectionId = "";
+    this.#rootElement = null;
   }
   /**
    * Re-initializes the observer if the offset or rootMargin values change dynamically.
@@ -96,8 +189,81 @@ var ScrollspyController = class extends Controller {
     this.#initializeObserver();
   }
   /**
-   * Smoothly scrolls to the target element mapped by the link anchor.
-   * Prevents full window scroll jumps when tracking nested scrollable containers.
+   * Re-syncs the observation set when a Turbo Stream/morph swaps the table of
+   * contents. Stimulus fires these before `connect()` for the links already in
+   * the markup, hence the guard: the initial observer is built exactly once, by
+   * `connect()`.
+   */
+  linkTargetConnected() {
+    if (this.#isConnected) this.#scheduleResync();
+  }
+  linkTargetDisconnected() {
+    if (this.#isConnected) this.#scheduleResync();
+  }
+  /**
+   * Queues **one** observation rebuild for the current mutation batch.
+   *
+   * A single Turbo morph can append one link, drop another, and rewrite a
+   * third's `href`, and those arrive through two independent channels —
+   * Stimulus's target callbacks and {@link #anchorObserver}. Each channel just
+   * raises the flag and queues a drain; the first drain to run does the work and
+   * clears it, so every later drain in the same batch finds nothing to do and
+   * the set is rebuilt once instead of three times. `disconnect()` clears the
+   * same flag, which is how a queued rebuild is dropped rather than run against
+   * a detached controller.
+   */
+  #scheduleResync() {
+    this.#resyncQueued = true;
+    queueMicrotask(this.#drainResync);
+  }
+  #drainResync = () => {
+    if (!this.#resyncQueued) return;
+    this.#resyncQueued = false;
+    this.#initializeObserver();
+  };
+  /**
+   * Watches the link targets' anchor attributes so an in-place rewrite re-syncs.
+   *
+   * A Turbo 8 morph keeps the element **and** its `data-*-target` marker and
+   * only rewrites attributes, so Stimulus fires no target callback: without
+   * this, a link re-pointed from `#intro` to `#faq` would keep the controller
+   * observing `#intro` for the rest of the page's life. The filter is exactly
+   * {@link ANCHOR_ATTRIBUTES}; guarding on `MutationObserver` keeps the
+   * controller usable where the API is absent, matching `IntersectionWatcher`'s
+   * own support guard.
+   */
+  #observeAnchorAttributes() {
+    if (typeof MutationObserver !== "undefined") {
+      this.#anchorObserver = new MutationObserver(this.#onAnchorMutation);
+      this.#anchorObserver.observe(this.element, {
+        subtree: true,
+        attributes: true,
+        attributeFilter: ANCHOR_ATTRIBUTES
+      });
+    }
+  }
+  /**
+   * Rebuilds only for a rewrite on a *current* link target. The observer is
+   * scoped to this controller's element, but that subtree also holds links the
+   * author never marked as targets (a "back to top" anchor, a nested nav), and
+   * those anchor nothing here.
+   */
+  #onAnchorMutation = (records) => {
+    const links = this.linkTargets;
+    for (const record of records) {
+      if (!links.includes(record.target)) continue;
+      this.#scheduleResync();
+      return;
+    }
+  };
+  /**
+   * Scrolls to the section the clicked link anchors, honoring `offset` and any
+   * nested scroll container (a plain fragment jump would scroll the window).
+   *
+   * Honors `prefers-reduced-motion` (WCAG 2.2 **2.3.3**) by forcing an instant
+   * jump independently of the consumer's CSS `scroll-behavior`. With
+   * `focusSection` enabled it also moves the sequential focus starting point
+   * into the destination; the URL fragment is deliberately not touched.
    */
   scrollTo(event) {
     const link = event.currentTarget;
@@ -106,109 +272,238 @@ var ScrollspyController = class extends Controller {
     event.preventDefault();
     const targetElement = document.getElementById(id);
     if (!targetElement) return;
-    const rootElement = this.#getRootElement();
+    const behavior = prefersReducedMotion() ? "instant" : "smooth";
+    const rootElement = this.#scrollRoot();
+    const targetRect = targetElement.getBoundingClientRect();
+    const offset = this.#offset;
     if (rootElement) {
       const containerRect = rootElement.getBoundingClientRect();
-      const targetRect = targetElement.getBoundingClientRect();
-      const scrollPosition = rootElement.scrollTop + (targetRect.top - containerRect.top) - this.offsetValue;
-      rootElement.scrollTo({
-        top: scrollPosition,
-        behavior: "smooth"
-      });
+      const scrollPosition = rootElement.scrollTop + (targetRect.top - containerRect.top) - offset;
+      rootElement.scrollTo({ top: scrollPosition, behavior });
     } else {
-      const targetRect = targetElement.getBoundingClientRect();
-      const scrollPosition = window.scrollY + targetRect.top - this.offsetValue;
-      window.scrollTo({
-        top: scrollPosition,
-        behavior: "smooth"
-      });
+      const scrollPosition = window.scrollY + targetRect.top - offset;
+      window.scrollTo({ top: scrollPosition, behavior });
     }
+    if (this.focusSectionValue) this.#focusSection(targetElement);
   }
-  #getRootElement() {
+  /**
+   * Moves the sequential focus starting point into the section `scrollTo` just
+   * jumped to, so the next Tab continues *inside* the destination instead of
+   * resuming in the table of contents (`preventDefault()` alone would leave the
+   * starting point on the link). Opt-in through `focusSection`, because moving
+   * focus is a decision only the consuming page can make.
+   *
+   * `tabindex="-1"` is established only when the section is not already
+   * focusable and is never removed, so an author-owned tabindex is left alone.
+   * `preventScroll` keeps the focus call from cancelling the smooth scroll
+   * started just above.
+   */
+  #focusSection(section) {
+    if (!section.hasAttribute("tabindex")) section.setAttribute("tabindex", "-1");
+    section.focus({ preventScroll: true });
+  }
+  /**
+   * The cached scroll root, re-resolved when the cached element has left the
+   * document (a Turbo morph replaced the container) so `scrollTo` never
+   * scrolls a detached node.
+   */
+  #scrollRoot() {
+    if (this.#rootElement && !this.#rootElement.isConnected) {
+      this.#rootElement = this.#queryRootElement();
+    }
+    return this.#rootElement;
+  }
+  /**
+   * Resolves `rootSelector` to a scrollable element.
+   *
+   * @returns The container, or `null` meaning "spy the viewport" when the value
+   * is empty, matches nothing, matches a non-HTML element (an SVG node is not a
+   * scroll container), or is not a valid selector — a typo in a data attribute
+   * must degrade to viewport spying, not leave the controller inert.
+   */
+  #queryRootElement() {
     if (!this.rootSelectorValue) return null;
-    return document.querySelector(this.rootSelectorValue);
+    try {
+      const root = document.querySelector(this.rootSelectorValue);
+      return root instanceof HTMLElement ? root : null;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Re-evaluates once per frame while the reader scrolls.
+   *
+   * `IntersectionObserver` reports **threshold crossings**, not positions, so a
+   * reader moving inside one long section — or across a gap wider than the
+   * observation band — produces no batch at all and the highlight would stay
+   * frozen at whatever the last crossing decided. That would make the current
+   * location depend on the *route* to a position instead of the position: a
+   * stepwise scroll crosses thresholds an instant jump to the same offset never
+   * does. Listening to the scroll source closes the gap, and because both paths
+   * end in {@link #evaluateActiveSection} — which measures section rects and the
+   * root's top edge at that instant — they converge on the same answer.
+   */
+  #onScroll = () => {
+    if (this.#frame !== null) return;
+    this.#frame = requestAnimationFrame(() => {
+      this.#frame = null;
+      this.#evaluateActiveSection();
+    });
+  };
+  /**
+   * Points the `scroll` listener at whatever the reader actually scrolls: the
+   * resolved root, or the window when the viewport is spied.
+   *
+   * The detach is unconditional, so rebuilding the observation set (a Value
+   * change, a morph) **moves** the listener rather than stacking a second one on
+   * a container the reader has stopped scrolling.
+   */
+  #syncScrollListener() {
+    this.#detachScrollListener();
+    this.#scrollSource = this.#rootElement ?? window;
+    this.#scrollSource.addEventListener("scroll", this.#onScroll, { passive: true });
+  }
+  #detachScrollListener() {
+    this.#scrollSource?.removeEventListener("scroll", this.#onScroll);
+    this.#scrollSource = null;
   }
   #initializeObserver() {
     this.#watcher.stop();
     this.#intersectionStates.clear();
-    this.#activeSectionId = "";
+    this.#activeSectionId = this.#activeSectionId || this.#activeIdFromDom();
+    this.#rootElement = this.#queryRootElement();
+    this.#syncScrollListener();
     if (this.linkTargets.length === 0) return;
-    const margin = this.rootMarginValue || `-${this.offsetValue}px 0px -80% 0px`;
+    const margin = this.rootMarginValue || `${-this.#offset}px 0px -80% 0px`;
     const sections = [];
     for (const link of this.linkTargets) {
       const id = this.#getAnchorId(link);
       if (!id) continue;
       const section = document.getElementById(id);
-      if (section) sections.push(section);
+      if (section && !sections.includes(section)) sections.push(section);
     }
     this.#watcher.start(sections, {
-      root: this.#getRootElement(),
+      root: this.#rootElement,
       rootMargin: margin,
       threshold: [0, 0.2, 0.4, 0.6, 0.8, 1]
       // Multiple thresholds handle large sections safely
     });
+    this.#syncActiveStates(false);
   }
   #onIntersection = (entries) => {
-    if (!this.#isConnected) return;
+    const isDetached = !this.#isConnected;
+    if (isDetached) return;
     for (const entry of entries) {
-      const id = entry.target.id;
-      if (!id) continue;
-      this.#intersectionStates.set(id, {
-        isIntersecting: entry.isIntersecting,
-        top: entry.boundingClientRect.top
+      const sectionId = entry.target.id;
+      if (!sectionId) continue;
+      this.#intersectionStates.set(sectionId, {
+        element: entry.target,
+        isIntersecting: entry.isIntersecting
       });
     }
     this.#evaluateActiveSection();
   };
+  /**
+   * Picks the section closest to the trigger line and publishes it.
+   *
+   * Every coordinate is read **now**: the section rects *and* the root's top
+   * edge share one measurement instant. Comparing an entry's recorded
+   * `boundingClientRect.top` (captured whenever that section last crossed a
+   * threshold) against a freshly computed trigger line mixes two moments in
+   * time, which would make the result depend on how the reader arrived at a
+   * position — a smooth scroll and an instant jump to the same offset disagree.
+   */
   #evaluateActiveSection() {
-    const rootEl = this.#getRootElement();
-    const triggerLine = (rootEl ? rootEl.getBoundingClientRect().top : 0) + this.offsetValue;
-    let bestId = "";
-    let closestTop = Number.MAX_VALUE;
-    for (const [id, state] of this.#intersectionStates.entries()) {
-      if (state.isIntersecting) {
-        const distance = Math.abs(state.top - triggerLine);
-        if (distance < closestTop) {
-          closestTop = distance;
-          bestId = id;
-        }
+    const rootEl = this.#scrollRoot();
+    const triggerLine = (rootEl ? rootEl.getBoundingClientRect().top : 0) + this.#offset;
+    let intersectingId = "";
+    let intersectingDistance = Number.POSITIVE_INFINITY;
+    let trackedId = "";
+    let trackedDistance = Number.POSITIVE_INFINITY;
+    for (const [id, state] of this.#intersectionStates) {
+      const rect = state.element.getBoundingClientRect();
+      if (rect.width === 0 && rect.height === 0) continue;
+      const distance = Math.abs(rect.top - triggerLine);
+      if (distance < trackedDistance) {
+        trackedDistance = distance;
+        trackedId = id;
       }
-    }
-    if (!bestId && this.#intersectionStates.size > 0) {
-      let absoluteClosestId = "";
-      let absoluteClosestTop = Number.MAX_VALUE;
-      for (const [id, state] of this.#intersectionStates.entries()) {
-        const distance = Math.abs(state.top - triggerLine);
-        if (distance < absoluteClosestTop) {
-          absoluteClosestTop = distance;
-          absoluteClosestId = id;
-        }
+      if (state.isIntersecting && distance < intersectingDistance) {
+        intersectingDistance = distance;
+        intersectingId = id;
       }
-      bestId = absoluteClosestId;
     }
+    const bestId = intersectingId || trackedId;
     if (bestId && bestId !== this.#activeSectionId) {
       this.#activeSectionId = bestId;
-      this.#syncActiveStates();
+      this.#syncActiveStates(true);
     }
   }
-  #syncActiveStates() {
-    const activeLink = this.linkTargets.find((l) => this.#getAnchorId(l) === this.#activeSectionId);
+  /**
+   * Writes `aria-current` across the current link set, optionally announcing.
+   *
+   * The two halves are separate because they answer different questions.
+   * *Attributes* must be idempotently re-established whenever the link set
+   * changes, even though the reader has not moved — otherwise a link that
+   * appears (or is re-anchored) while its section is already current never gets
+   * marked. *The `change` event* announces that the reader moved, so it fires
+   * only from the evaluation path; re-publishing over a new link set is not
+   * news, and dispatching there would make a rebuild look like navigation.
+   *
+   * @param announce Whether this sync represents a change of current section.
+   */
+  #syncActiveStates(announce) {
+    const activeLinks = this.linkTargets.filter(
+      (link) => this.#getAnchorId(link) === this.#activeSectionId
+    );
     for (const link of this.linkTargets) {
-      const isActive = link === activeLink;
-      if (isActive) {
+      if (activeLinks.includes(link)) {
         link.setAttribute("aria-current", "location");
-      } else {
+      } else if (link.getAttribute("aria-current") === "location") {
         link.removeAttribute("aria-current");
       }
     }
-    if (activeLink) {
-      this.dispatch("change", { detail: { id: this.#activeSectionId, link: activeLink } });
+    if (!announce) return;
+    const primaryLink = activeLinks[0];
+    if (primaryLink) {
+      this.dispatch("change", { detail: { id: this.#activeSectionId, link: primaryLink } });
     }
   }
+  /**
+   * The current location already encoded in the DOM, i.e. the section anchored
+   * by the first link carrying this controller's `aria-current="location"`.
+   * Empty when no link claims it (a genuinely fresh render).
+   */
+  #activeIdFromDom() {
+    for (const link of this.linkTargets) {
+      if (link.getAttribute("aria-current") !== "location") continue;
+      const id = this.#getAnchorId(link);
+      if (id) return id;
+    }
+    return "";
+  }
+  /**
+   * The section id a link anchors, resolved in a fixed order:
+   *
+   * 1. `href`, when it is a non-empty same-document fragment — the contract.
+   * 2. otherwise `data-href`'s fragment — the fallback for a link whose `href`
+   *    must stay a real URL (a server-rendered permalink) or that is not an
+   *    `<a>` at all.
+   * 3. otherwise `null`: the link anchors nothing here and is not observed.
+   *
+   * Step 2 is reached whenever `href` yields nothing usable — absent, `"#"`, or
+   * a real URL — which is the whole point of the fallback: `href="/guide/usage"`
+   * with `data-href="#usage"` is a permalink that also spies, and picking the
+   * first *present* attribute instead of the first *usable* one would silently
+   * exclude exactly that markup. When both are valid fragments `href` wins.
+   */
   #getAnchorId(link) {
-    const href = link.getAttribute("href") || link.getAttribute("data-href");
-    if (!href?.startsWith("#")) return null;
-    return href.substring(1);
+    return this.#fragmentId(link.getAttribute("href")) ?? this.#fragmentId(link.getAttribute("data-href"));
+  }
+  /** The id in a `#fragment` value; `null` for absent, empty, or non-fragment. */
+  #fragmentId(value) {
+    if (!value?.startsWith("#")) return null;
+    return value.substring(1) || null;
   }
 };