stimeo-ui 0.16.0 → 0.18.0

package/dist/controllers/scrollspy_controller.js

@@ -1,8 +1,27 @@
 import { Controller } from '@hotwired/stimulus';
 
-// src/controllers/scrollspy_controller.ts
+var FOCUS_EVENTS = /* @__PURE__ */ new Set(["blur", "focus", "focusin", "focusout"]);
+var POINTER_EVENTS = /* @__PURE__ */ new Set(["mouseenter", "mouseleave", "pointerenter", "pointerleave"]);
+function stateReasonFor(event) {
+  if (!event) return "api";
+  if (FOCUS_EVENTS.has(event.type)) return "focus";
+  if (POINTER_EVENTS.has(event.type)) return "pointer";
+  return "user";
+}
+
+function actionSource(source) {
+  if (source instanceof HTMLElement) {
+    return { event: null, host: source, origin: source, reason: "api" };
+  }
+  const event = source ?? null;
+  return {
+    event,
+    host: event?.currentTarget instanceof Element ? event.currentTarget : null,
+    origin: event?.target instanceof Element ? event.target : null,
+    reason: stateReasonFor(event)
+  };
+}
 
-// src/utils/declared_value.ts
 function parseDeclared(raw, parse, fallback) {
   try {
     return parse(raw);
@@ -22,14 +41,8 @@ function validSelector(element, raw, fallback) {
   );
 }
 
-// src/utils/frame_coalescer.ts
 var FrameCoalescer = class {
   #frame = null;
-  /**
-   * Runs `run` on the next frame, unless a frame is already pending — the first
-   * request of a burst wins and the rest are dropped. The pending frame is
-   * released before `run`, so `run` may request the next one.
-   */
   schedule(run) {
     if (this.#frame !== null) return;
     this.#frame = requestAnimationFrame(() => {
@@ -37,14 +50,6 @@ var FrameCoalescer = class {
       run();
     });
   }
-  /**
-   * Drops the pending frame, and reaches the platform only when there is one.
-   *
-   * There is no handle value that stands for "nothing pending":
-   * `cancelAnimationFrame` takes an `unsigned long`, so a negative placeholder
-   * arrives as a large positive number that the same allocator can hand out, and
-   * an idle cancel would then drop a frame belonging to someone else.
-   */
   cancel() {
     if (this.#frame === null) return;
     cancelAnimationFrame(this.#frame);
@@ -52,7 +57,6 @@ var FrameCoalescer = class {
   }
 };
 
-// src/utils/intersection_watcher.ts
 function queryRoot(selector) {
   if (!selector) return null;
   return parseDeclared(selector, (raw) => document.querySelector(raw), null);
@@ -65,30 +69,12 @@ var IntersectionWatcher = class {
   constructor(onEntries) {
     this.#onEntries = onEntries;
   }
-  /** Whether an observer is live (started, `IntersectionObserver` supported). */
   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. 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
-   *   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();
     if (typeof IntersectionObserver === "undefined") return false;
@@ -126,14 +112,6 @@ var IntersectionWatcher = class {
       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;
     try {
@@ -144,7 +122,6 @@ var IntersectionWatcher = class {
       throw error;
     }
   }
-  /** Severs the observer; late queued callbacks become no-ops via the guard. */
   stop() {
     this.#active = false;
     this.#observer?.disconnect();
@@ -153,12 +130,124 @@ var IntersectionWatcher = class {
   }
 };
 
-// src/utils/reduced_motion.ts
+var ListenerSet = class {
+  #abort = new AbortController();
+  add(target, type, handler, options) {
+    target.addEventListener(type, handler, { ...options, signal: this.#abort.signal });
+  }
+  dispose() {
+    this.#abort.abort();
+    this.#abort = new AbortController();
+  }
+};
+
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  constructor(run) {
+    this.#run = run;
+  }
+  activate() {
+    this.#active = true;
+  }
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  get pending() {
+    return this.#queued;
+  }
+  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();
+    });
+  }
+};
+
+var MorphRenderWatcher = class {
+  #listeners = new ListenerSet();
+  #pass;
+  #element = null;
+  #onMorph = () => this.#pass.schedule();
+  constructor(run) {
+    this.#pass = new MicrotaskCoalescer(run);
+  }
+  observe(element) {
+    if (this.#element === element) return;
+    this.disconnect();
+    this.#element = element;
+    this.#pass.activate();
+    this.#listeners.add(element, "turbo:morph-element", this.#onMorph);
+  }
+  schedule() {
+    this.#pass.schedule();
+  }
+  get pending() {
+    return this.#pass.pending;
+  }
+  disconnect() {
+    this.#listeners.dispose();
+    this.#pass.cancel();
+    this.#element = null;
+  }
+};
+
+var NUMBER_BOUNDS = {
+  finite: { finite: true }};
+function matchesNumberBounds(value, bounds) {
+  if (!Number.isFinite(value)) {
+    const direction = value === Infinity ? "positive" : value === -Infinity ? "negative" : null;
+    if (direction === null) return false;
+    if (bounds.allowInfinity !== "both" && bounds.allowInfinity !== direction) return false;
+  }
+  if (bounds.min !== void 0 && value < bounds.min) return false;
+  if (bounds.max !== void 0 && value > bounds.max) return false;
+  if (bounds.exclusiveMin !== void 0 && value <= bounds.exclusiveMin) return false;
+  if (bounds.integer && !Number.isInteger(value)) return false;
+  if (bounds.allowedValues !== void 0 && !bounds.allowedValues.includes(value)) return false;
+  return true;
+}
+
+function readNumber(raw, fallback, bounds) {
+  return matchesNumberBounds(raw, bounds) ? raw : fallback;
+}
+
+var NumberValueReader = class {
+  #lastRejected = /* @__PURE__ */ new Map();
+  read(owner, name, raw, fallback, bounds) {
+    const resolved = readNumber(raw, fallback, bounds);
+    if (matchesNumberBounds(raw, bounds)) {
+      this.#lastRejected.delete(name);
+      return resolved;
+    }
+    const attribute = `data-${owner.identifier}-${name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}-value`;
+    const literal = owner.element.getAttribute(attribute);
+    if (literal === null) {
+      this.#lastRejected.delete(name);
+      return resolved;
+    }
+    if (this.#lastRejected.get(name) !== literal) {
+      this.#lastRejected.set(name, literal);
+      console.warn(
+        `Stimeo UI: "${owner.identifier}" has an invalid number Value "${name}" declaration ${JSON.stringify(literal)}; using ${fallback}.`
+      );
+    }
+    return resolved;
+  }
+};
+
 function prefersReducedMotion() {
   return typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
 }
 
-// src/utils/scroll_source.ts
 function resolveScrollContainer(selector) {
   const match = selector ? document.querySelector(selector) : null;
   return match instanceof HTMLElement ? match : null;
@@ -167,9 +256,13 @@ function scrollOffset(source) {
   return source === window ? window.scrollY ?? window.pageYOffset ?? 0 : source.scrollTop;
 }
 
-// src/controllers/scrollspy_controller.ts
+function targetSelector(identifier, name) {
+  return `[data-${identifier}-target~="${name}"]`;
+}
+
 var ANCHOR_ATTRIBUTES = ["href", "data-href"];
-var ScrollspyController = class extends Controller {
+var ScrollspyController = class _ScrollspyController extends Controller {
+  #numbers = new NumberValueReader();
   static targets = ["link"];
   static values = {
     offset: { type: Number, default: 0 },
@@ -177,70 +270,48 @@ var ScrollspyController = class extends Controller {
     rootSelector: { type: String, default: "" },
     focusSection: { type: Boolean, default: false }
   };
+  static valueConstraints = {
+    offset: NUMBER_BOUNDS.finite
+  };
   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;
+    return this.#safeOffset;
   }
-  /** Shared IO plumbing (support guard, active guard, teardown). */
   #watcher = new IntersectionWatcher((entries) => this.#onIntersection(entries));
   #isConnected = false;
-  /**
-   * 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; 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;
-  /** Coalesces a scroll burst into one measurement per frame. */
+  #scrollListeners = new ListenerSet();
   #frames = new FrameCoalescer();
-  /** The validated `rootSelector`, or `""` when the declaration cannot be parsed. */
   #rootSelector = "";
-  /** 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;
+  #resyncInputsChanged = false;
+  #resync = new MorphRenderWatcher(() => {
+    const retainStates = !this.#resyncInputsChanged;
+    this.#resyncInputsChanged = false;
+    this.#initializeObserver(retainStates);
+    this.#evaluateActiveSection();
+  });
   connect() {
+    this.#resync.observe(this.element);
     this.#isConnected = true;
     this.#observeAnchorAttributes();
     this.#initializeObserver();
   }
   disconnect() {
     this.#isConnected = false;
-    this.#resyncQueued = false;
+    this.#resync.disconnect();
+    this.#resyncInputsChanged = false;
     this.#watcher.stop();
     this.#anchorObserver?.disconnect();
     this.#anchorObserver = null;
     this.#detachScrollListener();
     this.#frames.cancel();
-    this.#intersectionStates.clear();
     this.#activeSectionId = "";
     this.#rootElement = null;
   }
-  /**
-   * Re-initializes the observer if the offset or rootMargin values change dynamically.
-   */
   offsetValueChanged() {
     if (!this.#isConnected) return;
     this.#initializeObserver();
@@ -254,50 +325,16 @@ var ScrollspyController = class extends Controller {
     if (!this.#isConnected) return;
     this.#initializeObserver();
   }
-  /**
-   * 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);
+    this.#resyncInputsChanged = true;
+    this.#resync.schedule();
   }
-  #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
-   * `href` and `data-href`; 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);
@@ -308,12 +345,6 @@ var ScrollspyController = class extends Controller {
       });
     }
   }
-  /**
-   * 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) {
@@ -322,20 +353,16 @@ var ScrollspyController = class extends Controller {
       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;
+  scrollTo(source) {
+    const { event, host, origin } = actionSource(source);
+    const link = host?.closest(targetSelector(this.identifier, "link"));
+    if (!link || !this.linkTargets.includes(link)) return;
+    if (origin && origin.closest(`[data-controller~="${this.identifier}"]`) !== this.element)
+      return;
+    const moveFocus = event !== null || this.element.contains(document.activeElement);
     const id = this.#getAnchorId(link);
     if (!id) return;
-    event.preventDefault();
+    event?.preventDefault();
     const targetElement = document.getElementById(id);
     if (!targetElement) return;
     const behavior = prefersReducedMotion() ? "instant" : "smooth";
@@ -350,85 +377,36 @@ var ScrollspyController = class extends Controller {
       const scrollPosition = scrollOffset(window) + targetRect.top - offset;
       window.scrollTo({ top: scrollPosition, behavior });
     }
-    if (this.focusSectionValue) this.#focusSection(targetElement);
-  }
-  /**
-   * 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.
-   */
+    if (this.focusSectionValue && moveFocus) this.#focusSection(targetElement);
+  }
   #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
-   * declaration is empty, matches nothing, or matches a non-HTML element. A typo
-   * reads as empty: the declaration is validated once when it changes, so a
-   * selector that cannot be parsed degrades to viewport spying rather than
-   * leaving the controller inert.
-   */
   #queryRootElement() {
     return resolveScrollContainer(this.#rootSelector);
   }
-  /**
-   * 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 = () => this.#frames.schedule(() => 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 });
+    this.#scrollListeners.add(this.#rootElement ?? window, "scroll", this.#onScroll, {
+      passive: true
+    });
   }
   #detachScrollListener() {
-    this.#scrollSource?.removeEventListener("scroll", this.#onScroll);
-    this.#scrollSource = null;
-  }
-  /**
-   * @stimeoRuntimeOnly `rootMargin` wires the observer this call installs; the active section it
-   *   republishes is the one already recorded.
-   */
-  #initializeObserver() {
+    this.#scrollListeners.dispose();
+  }
+  #initializeObserver(retainStates = false) {
     this.#watcher.stop();
-    this.#intersectionStates.clear();
+    const previousStates = retainStates ? this.#intersectionStates : null;
+    const previousRoot = this.#rootElement;
+    this.#intersectionStates = /* @__PURE__ */ new Map();
     this.#activeSectionId = this.#activeSectionId || this.#activeIdFromDom();
     this.#rootElement = this.#queryRootElement();
     this.#syncScrollListener();
@@ -439,13 +417,18 @@ var ScrollspyController = class extends Controller {
       const id = this.#getAnchorId(link);
       if (!id) continue;
       const section = document.getElementById(id);
-      if (section && !sections.includes(section)) sections.push(section);
+      if (section && !sections.includes(section)) {
+        sections.push(section);
+        const previous = previousStates?.get(id);
+        if (previous?.element === section && previousRoot === this.#rootElement) {
+          this.#intersectionStates.set(id, previous);
+        }
+      }
     }
     this.#watcher.start(sections, {
       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);
   }
@@ -462,18 +445,6 @@ var ScrollspyController = class extends Controller {
     }
     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.
-   *
-   * @stimeoRenderRoot
-   */
   #evaluateActiveSection() {
     const rootEl = this.#scrollRoot();
     const triggerLine = (rootEl ? rootEl.getBoundingClientRect().top : 0) + this.#offset;
@@ -500,19 +471,6 @@ var ScrollspyController = class extends Controller {
       this.#syncActiveStates(true);
     }
   }
-  /**
-   * 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
@@ -530,11 +488,6 @@ var ScrollspyController = class extends Controller {
       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;
@@ -543,31 +496,23 @@ var ScrollspyController = class extends Controller {
     }
     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) {
     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;
   }
+  get #safeOffset() {
+    return this.#numbers.read(
+      this,
+      "offset",
+      this.offsetValue,
+      _ScrollspyController.values.offset.default,
+      _ScrollspyController.valueConstraints.offset
+    );
+  }
 };
 
 export { ScrollspyController };
-//# sourceMappingURL=scrollspy_controller.js.map
 //# sourceMappingURL=scrollspy_controller.js.map