stimeo-ui 0.2.0 → 0.3.0

package/dist/controllers/scroll_visibility_controller.js

@@ -1,5 +1,39 @@
 import { Controller } from '@hotwired/stimulus';
 
+// src/controllers/scroll_visibility_controller.ts
+
+// src/utils/reduced_motion.ts
+function prefersReducedMotion() {
+  return typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+
+// src/utils/tabindex_loan.ts
+var TabindexLoan = class {
+  #value;
+  #lent = /* @__PURE__ */ new Set();
+  /**
+   * @param value - the `tabindex` to lend. `"-1"` (the default) is
+   *   programmatically focusable but not a Tab stop; `"0"` is a real Tab stop,
+   *   which a scroll region with no focusable content of its own needs.
+   */
+  constructor(value = "-1") {
+    this.#value = value;
+  }
+  /** Lends `element` the value; no-ops when it already carries a `tabindex`. */
+  lend(element) {
+    if (element.hasAttribute("tabindex")) return;
+    element.setAttribute("tabindex", this.#value);
+    this.#lent.add(element);
+  }
+  /** Takes back every loan whose value is still the one that was lent. */
+  returnAll() {
+    for (const element of this.#lent) {
+      if (element.getAttribute("tabindex") === this.#value) element.removeAttribute("tabindex");
+    }
+    this.#lent.clear();
+  }
+};
+
 // src/controllers/scroll_visibility_controller.ts
 var ScrollVisibilityController = class extends Controller {
   static targets = ["element"];
@@ -11,7 +45,7 @@ var ScrollVisibilityController = class extends Controller {
   };
   static actions = ["toTop"];
   static events = ["change"];
-  /** Pending rAF id used to coalesce scroll bursts into one measurement. */
+  /** Pending rAF id that coalesces scroll bursts into one measurement. */
   #rafId = null;
   /** Previous scroll position, for `direction` mode delta detection. */
   #lastScrollY = 0;
@@ -22,6 +56,8 @@ var ScrollVisibilityController = class extends Controller {
    * the window. Captured on connect so teardown detaches from the same source.
    */
   #scrollSource = window;
+  /** Focus targets this instance lent a `tabindex` to. */
+  #tabindex = new TabindexLoan();
   #onScroll = () => {
     if (this.#rafId !== null) return;
     this.#rafId = requestAnimationFrame(() => {
@@ -41,16 +77,17 @@ var ScrollVisibilityController = class extends Controller {
       cancelAnimationFrame(this.#rafId);
       this.#rafId = null;
     }
+    this.#tabindex.returnAll();
     this.#visible = null;
   }
   /** Scrolls the source to the top and, optionally, moves focus to a safe target. */
   toTop() {
-    const behavior = this.#prefersReducedMotion() ? "auto" : "smooth";
+    const behavior = prefersReducedMotion() ? "instant" : "smooth";
     this.#scrollSource.scrollTo({ top: 0, behavior });
     if (this.focusSelectorValue) {
       const target = document.querySelector(this.focusSelectorValue);
       if (target) {
-        if (!target.hasAttribute("tabindex")) target.setAttribute("tabindex", "-1");
+        this.#tabindex.lend(target);
         target.focus();
       }
     }
@@ -93,9 +130,6 @@ var ScrollVisibilityController = class extends Controller {
     }
     return this.#scrollSource.scrollTop;
   }
-  #prefersReducedMotion() {
-    return typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
-  }
 };
 
 export { ScrollVisibilityController };

package/dist/controllers/scroll_visibility_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/controllers/scroll_visibility_controller.ts"],"names":[],"mappings":"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","file":"scroll_visibility_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/**\n * Headless **Scroll Visibility** behavior: shows or hides an element based on\n * scroll amount or direction (back-to-top buttons, hide-on-scroll headers). No\n * dedicated APG pattern; when the element is a button it follows the Button\n * practice.\n *\n * Markup contract (identifier: `stimeo--scroll-visibility`):\n *   <div data-controller=\"stimeo--scroll-visibility\"\n *        data-stimeo--scroll-visibility-offset-value=\"400\"\n *        data-stimeo--scroll-visibility-mode-value=\"offset\">\n *     <button type=\"button\" hidden\n *             data-stimeo--scroll-visibility-target=\"element\"\n *             data-action=\"stimeo--scroll-visibility#toTop\">Back to top</button>\n *   </div>\n *\n * In `offset` mode the element is shown once the scroll source is scrolled past\n * `offset` px; in `direction` mode it is hidden while scrolling down and shown\n * while scrolling up. Visibility is reflected through the `hidden` attribute (so a\n * hidden control also leaves the focus order) and `data-state`.\n *\n * By default the **window** is the scroll source. When the page itself does not\n * scroll — e.g. a fixed-height app shell whose main column scrolls in a container\n * (`overflow: auto`) — point `root` at that container (a CSS selector) so the\n * controller observes the element's scroll instead of the (never-scrolling)\n * window. `toTop` then scrolls that same container.\n *\n * @remarks\n * Behavior only — the look and any transition are the consumer's CSS. The scroll\n * listener is `passive`, coalesced through `requestAnimationFrame`, and removed on\n * `disconnect()` (Turbo navigation included). `toTop` honors\n * `prefers-reduced-motion` by falling back to an instant jump, and can move focus\n * to a `focusSelector` target (given `tabindex=\"-1\"` if needed) to keep keyboard\n * users oriented after the scroll.\n */\nexport class ScrollVisibilityController extends Controller<HTMLElement> {\n  static override targets = [\"element\"];\n  static override values = {\n    offset: { type: Number, default: 400 },\n    mode: { type: String, default: \"offset\" },\n    focusSelector: { type: String, default: \"\" },\n    root: { type: String, default: \"\" },\n  };\n  static actions = [\"toTop\"] as const;\n  static events = [\"change\"] as const;\n\n  declare readonly elementTarget: HTMLElement;\n  declare readonly hasElementTarget: boolean;\n\n  declare offsetValue: number;\n  declare modeValue: string;\n  declare focusSelectorValue: string;\n  declare rootValue: string;\n\n  /** Pending rAF id used to coalesce scroll bursts into one measurement. */\n  #rafId: number | null = null;\n  /** Previous scroll position, for `direction` mode delta detection. */\n  #lastScrollY = 0;\n  /** Current visibility, tracked to dispatch `change` only on real transitions. */\n  #visible: boolean | null = null;\n  /**\n   * The observed scroll source: a container element when `root` resolves, else\n   * the window. Captured on connect so teardown detaches from the same source.\n   */\n  #scrollSource: HTMLElement | Window = window;\n\n  readonly #onScroll = (): void => {\n    if (this.#rafId !== null) return;\n    this.#rafId = requestAnimationFrame(() => {\n      this.#rafId = null;\n      this.#evaluate();\n    });\n  };\n\n  override connect(): void {\n    this.#scrollSource = this.#resolveScrollSource();\n    this.#lastScrollY = this.#scrollY();\n    this.#scrollSource.addEventListener(\"scroll\", this.#onScroll, { passive: true });\n    this.#evaluate();\n  }\n\n  override disconnect(): void {\n    this.#scrollSource.removeEventListener(\"scroll\", this.#onScroll);\n    if (this.#rafId !== null) {\n      cancelAnimationFrame(this.#rafId);\n      this.#rafId = null;\n    }\n    this.#visible = null;\n  }\n\n  /** Scrolls the source to the top and, optionally, moves focus to a safe target. */\n  toTop(): void {\n    const behavior: ScrollBehavior = this.#prefersReducedMotion() ? \"auto\" : \"smooth\";\n    this.#scrollSource.scrollTo({ top: 0, behavior });\n    if (this.focusSelectorValue) {\n      const target = document.querySelector<HTMLElement>(this.focusSelectorValue);\n      if (target) {\n        if (!target.hasAttribute(\"tabindex\")) target.setAttribute(\"tabindex\", \"-1\");\n        target.focus();\n      }\n    }\n  }\n\n  /** Decides the next visibility from the current scroll state and applies it. */\n  #evaluate(): void {\n    const y = this.#scrollY();\n    let nextVisible: boolean;\n    if (this.modeValue === \"direction\") {\n      // Near the very top, always reveal so a hide-on-scroll header is never\n      // stranded off-screen when the page cannot scroll up any further.\n      if (y <= this.offsetValue) {\n        nextVisible = true;\n      } else {\n        nextVisible = y < this.#lastScrollY; // scrolling up reveals, down hides\n      }\n    } else {\n      nextVisible = y > this.offsetValue;\n    }\n    this.#lastScrollY = y;\n    this.#setVisible(nextVisible);\n  }\n\n  /** Applies visibility to the target, syncing `hidden`, `data-state`, `change`. */\n  #setVisible(next: boolean): void {\n    if (next === this.#visible) return;\n    this.#visible = next;\n    if (this.hasElementTarget) this.elementTarget.hidden = !next;\n    this.element.setAttribute(\"data-state\", next ? \"visible\" : \"hidden\");\n    this.dispatch(\"change\", { detail: { visible: next } });\n  }\n\n  /** Resolves the scroll source from `root` (falling back to the window). */\n  #resolveScrollSource(): HTMLElement | Window {\n    if (this.rootValue) {\n      const root = document.querySelector<HTMLElement>(this.rootValue);\n      if (root) return root;\n    }\n    return window;\n  }\n\n  #scrollY(): number {\n    if (this.#scrollSource === window) {\n      return window.scrollY ?? window.pageYOffset ?? 0;\n    }\n    return (this.#scrollSource as HTMLElement).scrollTop;\n  }\n\n  #prefersReducedMotion(): boolean {\n    return (\n      typeof window.matchMedia === \"function\" &&\n      window.matchMedia(\"(prefers-reduced-motion: reduce)\").matches\n    );\n  }\n}\n"]}
+{"version":3,"sources":["../../src/utils/reduced_motion.ts","../../src/utils/tabindex_loan.ts","../../src/controllers/scroll_visibility_controller.ts"],"names":[],"mappings":"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","file":"scroll_visibility_controller.js","sourcesContent":["/**\n * Shared `prefers-reduced-motion` lookup for the motion-aware controllers\n * (count-up, highlight, overflow-indicator, scroll-visibility, stick-to-bottom,\n * transition).\n *\n * This one-liner keeps the media query string and the environment guard\n * single-sourced across them. The preference is intentionally re-read on every\n * call — the controllers check it at each animation/scroll start (WCAG 2.2\n * **2.3.3**), so flipping the OS setting takes effect immediately without any\n * listener or cache bookkeeping here.\n */\n\n/**\n * Whether the user currently requests reduced motion.\n *\n * @returns `true` when `(prefers-reduced-motion: reduce)` matches; `false`\n * otherwise, including environments without `window.matchMedia` (treated as\n * \"no preference\").\n */\nexport function prefersReducedMotion(): boolean {\n  return (\n    typeof window.matchMedia === \"function\" &&\n    window.matchMedia(\"(prefers-reduced-motion: reduce)\").matches\n  );\n}\n","/**\n * Shared bookkeeping for a `tabindex` a controller lends an element temporarily.\n *\n * A controller that must move focus somewhere the author never made focusable\n * (a landmark root, a scroll destination) reaches for the same trick: add a\n * `tabindex` just-in-time and hand it back once it is no longer needed. The\n * borrow is the easy half; the return is what the two conditions below are for.\n *\n * **Returning needs two conditions, not one.** Owning the borrow is not enough:\n * the attribute must also still hold the value this instance wrote. A consumer\n * that changed it afterwards — `tabindex=\"0\"` to make the root its own Tab stop\n * — owns it now, and removing it there silently discards authored markup. The\n * bookkeeping is dropped either way, since the loan is over regardless of who\n * ends up owning the value.\n *\n * **Never borrow over an existing value.** An element that already carries a\n * `tabindex` is the author's to control, so there is nothing to lend and nothing\n * to return.\n *\n * The registry is keyed by element, so a controller borrowing on a single\n * element (`this.element`) and one borrowing across a changing set of targets\n * use the same API — the single-element case is a set of one. It holds no\n * opinion about *when* to borrow or where focus goes next; that stays in the\n * controller.\n *\n * **The API is deliberately two methods.** This file's own doc block is dropped\n * from `dist`, but every member comment is inlined into **each** consumer entry\n * (`tsup` builds with `splitting: false`), so rationale belongs here, only the\n * contract belongs on the members, and every method no consumer calls is still\n * paid for once per consumer entry.\n *\n * @example\n * ```ts\n * readonly #tabindex = new TabindexLoan();\n *\n * #rescueFocus() {\n *   this.#tabindex.lend(this.element);\n *   this.element.focus();\n * }\n *\n * disconnect() {\n *   this.#tabindex.returnAll();\n * }\n * ```\n */\nexport class TabindexLoan<T extends HTMLElement = HTMLElement> {\n  readonly #value: string;\n  readonly #lent = new Set<T>();\n\n  /**\n   * @param value - the `tabindex` to lend. `\"-1\"` (the default) is\n   *   programmatically focusable but not a Tab stop; `\"0\"` is a real Tab stop,\n   *   which a scroll region with no focusable content of its own needs.\n   */\n  constructor(value: string = \"-1\") {\n    this.#value = value;\n  }\n\n  /** Lends `element` the value; no-ops when it already carries a `tabindex`. */\n  lend(element: T): void {\n    if (element.hasAttribute(\"tabindex\")) return;\n    element.setAttribute(\"tabindex\", this.#value);\n    this.#lent.add(element);\n  }\n\n  /** Takes back every loan whose value is still the one that was lent. */\n  returnAll(): void {\n    for (const element of this.#lent) {\n      if (element.getAttribute(\"tabindex\") === this.#value) element.removeAttribute(\"tabindex\");\n    }\n    this.#lent.clear();\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { prefersReducedMotion } from \"../utils/reduced_motion\";\nimport { TabindexLoan } from \"../utils/tabindex_loan\";\n\n/**\n * Headless **Scroll Visibility** behavior: shows or hides an element based on\n * scroll amount or direction (back-to-top buttons, hide-on-scroll headers). No\n * dedicated APG pattern; when the element is a button it follows the Button\n * practice.\n *\n * Markup contract (identifier: `stimeo--scroll-visibility`):\n *   <div data-controller=\"stimeo--scroll-visibility\"\n *        data-stimeo--scroll-visibility-offset-value=\"400\"\n *        data-stimeo--scroll-visibility-mode-value=\"offset\">\n *     <button type=\"button\" hidden\n *             data-stimeo--scroll-visibility-target=\"element\"\n *             data-action=\"stimeo--scroll-visibility#toTop\">Back to top</button>\n *   </div>\n *\n * In `offset` mode the element is shown once the scroll source is scrolled past\n * `offset` px; in `direction` mode it is hidden while scrolling down and shown\n * while scrolling up. Visibility is reflected through the `hidden` attribute (so a\n * hidden control also leaves the focus order) and `data-state`.\n *\n * By default the **window** is the scroll source. When the page itself does not\n * scroll — e.g. a fixed-height app shell whose main column scrolls in a container\n * (`overflow: auto`) — point `root` at that container (a CSS selector) so the\n * controller observes the element's scroll instead of the (never-scrolling)\n * window. `toTop` then scrolls that same container.\n *\n * @remarks\n * Behavior only — the look and any transition are the consumer's CSS. The scroll\n * listener is `passive`, coalesced through `requestAnimationFrame`, and removed on\n * `disconnect()` (Turbo navigation included). `toTop` honors\n * `prefers-reduced-motion` by forcing an instant jump independently of the\n * consumer's CSS `scroll-behavior`, and can move focus to a `focusSelector`\n * target (given `tabindex=\"-1\"` if needed) to keep keyboard users oriented\n * after the scroll. A live disconnect removes only a `tabindex=\"-1\"` this\n * controller instance added; authored tabindex values remain. This teardown does\n * not claim to rewrite a Turbo cache snapshot that was cloned before disconnect.\n */\nexport class ScrollVisibilityController extends Controller<HTMLElement> {\n  static override targets = [\"element\"];\n  static override values = {\n    offset: { type: Number, default: 400 },\n    mode: { type: String, default: \"offset\" },\n    focusSelector: { type: String, default: \"\" },\n    root: { type: String, default: \"\" },\n  };\n  static actions = [\"toTop\"] as const;\n  static events = [\"change\"] as const;\n\n  declare readonly elementTarget: HTMLElement;\n  declare readonly hasElementTarget: boolean;\n\n  declare offsetValue: number;\n  declare modeValue: string;\n  declare focusSelectorValue: string;\n  declare rootValue: string;\n\n  /** Pending rAF id that coalesces scroll bursts into one measurement. */\n  #rafId: number | null = null;\n  /** Previous scroll position, for `direction` mode delta detection. */\n  #lastScrollY = 0;\n  /** Current visibility, tracked to dispatch `change` only on real transitions. */\n  #visible: boolean | null = null;\n  /**\n   * The observed scroll source: a container element when `root` resolves, else\n   * the window. Captured on connect so teardown detaches from the same source.\n   */\n  #scrollSource: HTMLElement | Window = window;\n  /** Focus targets this instance lent a `tabindex` to. */\n  readonly #tabindex = new TabindexLoan();\n\n  readonly #onScroll = (): void => {\n    if (this.#rafId !== null) return;\n    this.#rafId = requestAnimationFrame(() => {\n      this.#rafId = null;\n      this.#evaluate();\n    });\n  };\n\n  override connect(): void {\n    this.#scrollSource = this.#resolveScrollSource();\n    this.#lastScrollY = this.#scrollY();\n    this.#scrollSource.addEventListener(\"scroll\", this.#onScroll, { passive: true });\n    this.#evaluate();\n  }\n\n  override disconnect(): void {\n    this.#scrollSource.removeEventListener(\"scroll\", this.#onScroll);\n    if (this.#rafId !== null) {\n      cancelAnimationFrame(this.#rafId);\n      this.#rafId = null;\n    }\n    this.#tabindex.returnAll();\n    this.#visible = null;\n  }\n\n  /** Scrolls the source to the top and, optionally, moves focus to a safe target. */\n  toTop(): void {\n    const behavior: ScrollBehavior = prefersReducedMotion() ? \"instant\" : \"smooth\";\n    this.#scrollSource.scrollTo({ top: 0, behavior });\n    if (this.focusSelectorValue) {\n      const target = document.querySelector<HTMLElement>(this.focusSelectorValue);\n      if (target) {\n        this.#tabindex.lend(target);\n        target.focus();\n      }\n    }\n  }\n\n  /** Decides the next visibility from the current scroll state and applies it. */\n  #evaluate(): void {\n    const y = this.#scrollY();\n    let nextVisible: boolean;\n    if (this.modeValue === \"direction\") {\n      // Near the very top, always reveal so a hide-on-scroll header is never\n      // stranded off-screen when the page cannot scroll up any further.\n      if (y <= this.offsetValue) {\n        nextVisible = true;\n      } else {\n        nextVisible = y < this.#lastScrollY; // scrolling up reveals, down hides\n      }\n    } else {\n      nextVisible = y > this.offsetValue;\n    }\n    this.#lastScrollY = y;\n    this.#setVisible(nextVisible);\n  }\n\n  /** Applies visibility to the target, syncing `hidden`, `data-state`, `change`. */\n  #setVisible(next: boolean): void {\n    if (next === this.#visible) return;\n    this.#visible = next;\n    if (this.hasElementTarget) this.elementTarget.hidden = !next;\n    this.element.setAttribute(\"data-state\", next ? \"visible\" : \"hidden\");\n    this.dispatch(\"change\", { detail: { visible: next } });\n  }\n\n  /** Resolves the scroll source from `root` (falling back to the window). */\n  #resolveScrollSource(): HTMLElement | Window {\n    if (this.rootValue) {\n      const root = document.querySelector<HTMLElement>(this.rootValue);\n      if (root) return root;\n    }\n    return window;\n  }\n\n  #scrollY(): number {\n    if (this.#scrollSource === window) {\n      return window.scrollY ?? window.pageYOffset ?? 0;\n    }\n    return (this.#scrollSource as HTMLElement).scrollTop;\n  }\n}\n"]}

package/dist/controllers/scrollspy_controller.d.ts

@@ -1,28 +1,59 @@
 import { Controller } from '@hotwired/stimulus';
 
 /**
- * Headless, accessible Scrollspy / Navigation catalog synchronizer.
+ * Headless, accessible **Scrollspy**: keeps a table of contents in sync with the
+ * section the reader is currently in, published as `aria-current="location"`.
+ * There is no dedicated APG widget; it follows the `aria-current`
+ * current-location practice inside a `<nav>` landmark.
  *
  * Markup contract (identifier: `stimeo--scrollspy`):
  *   <nav data-controller="stimeo--scrollspy"
  *        data-stimeo--scrollspy-offset-value="80"
+ *        data-stimeo--scrollspy-root-selector-value=".content"
  *        aria-label="Table of contents">
- *     <a href="#intro" data-stimeo--scrollspy-target="link">Intro</a>
- *     <a href="#usage" data-stimeo--scrollspy-target="link">Usage</a>
+ *     <a href="#intro" data-stimeo--scrollspy-target="link"
+ *        data-action="click->stimeo--scrollspy#scrollTo">Intro</a>
+ *     <a href="#usage" data-stimeo--scrollspy-target="link"
+ *        data-action="click->stimeo--scrollspy#scrollTo">Usage</a>
  *   </nav>
- *   <section id="intro">…</section>
- *   <section id="usage">…</section>
+ *   <div class="content">
+ *     <section id="intro">…</section>
+ *     <section id="usage">…</section>
+ *   </div>
  *
- * Implements clean active location synchronization driven by `aria-current`:
- * - Leverages native `IntersectionObserver` to track viewport visibility.
- * - Robust evaluation algorithm: among all intersecting sections, the one closest
- *   to the top offset trigger line (`boundingClientRect.top`) is prioritized as active.
- * - Toggles `aria-current="location"` dynamically on active/inactive links.
- * - Gracefully handles teardown `disconnect()` by severing observer references to prevent leaks.
+ * The active section is the one whose top edge sits closest to the **trigger
+ * line**: `offset` px below the top of the *scroll root* — the `rootSelector`
+ * container, or the viewport when that value is empty. It is not the viewport
+ * top whenever a nested container is spied on. Intersecting sections win; when
+ * none intersects (between two sections, scrolled past the last one) the
+ * closest tracked section keeps the highlight, so a table of contents never
+ * goes blank.
+ *
+ * `data-action` on the links is optional and opts into {@link scrollTo}, which
+ * scrolls the nested container instead of bouncing the whole window.
  *
  * @remarks
- * Behavior only. The controller manages state on catalog links via `aria-current`,
- * respects custom offsets, and dispatches `stimeo--scrollspy:change` events.
+ * Behavior only — how a current link looks is the consumer's CSS
+ * (`[aria-current="location"] { … }`). `connect()` reads the current location
+ * back from the DOM so a Turbo cache restore re-establishes it without a
+ * redundant `change`, and `disconnect()` severs every resource acquired here:
+ * the observers, the scroll listener, and any pending frame or queued rebuild.
+ *
+ * **What is followed automatically**, and what is not (the boundary a consumer
+ * has to know, because everything outside it needs a re-`connect()`):
+ *
+ * - `link` targets added or removed — Stimulus's target callbacks.
+ * - a `link` target's `href` / `data-href` rewritten in place — a Turbo 8 morph
+ *   keeps the element *and* its target marker, so no target callback fires;
+ *   {@link ANCHOR_ATTRIBUTES} is watched for exactly this case.
+ * - the reader's scroll position, including inside a stretch where no section
+ *   crosses an observation threshold.
+ *
+ * Not followed: a *split* lifecycle in which the nav survives while the scroll
+ * root or the sections are replaced underneath it. `rootSelector` is resolved
+ * against the whole document and re-resolved once the cached container leaves
+ * it, but section elements are looked up only while the observation set is
+ * (re)built — swap those alone and nothing tells this controller to look again.
  */
 declare class ScrollspyController extends Controller<HTMLElement> {
     #private;
@@ -40,6 +71,10 @@ declare class ScrollspyController extends Controller<HTMLElement> {
             type: StringConstructor;
             default: string;
         };
+        focusSection: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
     };
     static actions: readonly ["scrollTo"];
     static events: readonly ["change"];
@@ -47,6 +82,7 @@ declare class ScrollspyController extends Controller<HTMLElement> {
     offsetValue: number;
     rootMarginValue: string;
     rootSelectorValue: string;
+    focusSectionValue: boolean;
     connect(): void;
     disconnect(): void;
     /**
@@ -56,8 +92,21 @@ declare class ScrollspyController extends Controller<HTMLElement> {
     rootMarginValueChanged(): void;
     rootSelectorValueChanged(): void;
     /**
-     * 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(): void;
+    linkTargetDisconnected(): void;
+    /**
+     * 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: Event): void;
 }