stimeo-ui 0.2.0 → 0.2.1

package/dist/controllers/scrollspy_controller.js

@@ -18,6 +18,11 @@ var IntersectionWatcher = class {
    * (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.
+   *
+   * @throws Whatever the platform throws for an invalid `rootMargin`/`threshold`
+   *   or a failing `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,25 +30,42 @@ 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 {
+      observer = new IntersectionObserver(
+        (entries) => {
+          if (this.#active && this.#observer === observer) this.#onEntries(entries);
+        },
+        { root, rootMargin: options.rootMargin, threshold: options.threshold }
+      );
+      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;
+      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() {

package/dist/controllers/scrollspy_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/intersection_watcher.ts","../../src/controllers/scrollspy_controller.ts"],"names":[],"mappings":"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","file":"scrollspy_controller.js","sourcesContent":["/**\n * Shared `IntersectionObserver` plumbing for Stimeo's scroll-triggered\n * controllers (`intersection`, `scrollspy`, `sticky-observer`, `lazy-frame`).\n *\n * It centralizes the `IntersectionObserver` support guard, root resolution from\n * a selector, observer creation/teardown, the **active guard** (the browser may\n * flush a final queued callback batch right after `disconnect()`, and a\n * detached controller must not mutate possibly-cached DOM), and the\n * unobserve→observe **re-arm** that re-delivers the current state even when the\n * target never leaves the viewport.\n *\n * Like {@link RovingTabindex} and `FocusTrap`, this is a policy-free internal\n * util: what an intersection *means* (a spied link, a stuck header, a lazy\n * load) stays in each controller. The public `stimeo--intersection` controller\n * is its thin declarative face.\n */\nexport interface IntersectionWatchOptions {\n  /**\n   * The observation root. Pass an element (or `null` for the viewport) when\n   * the caller already resolved it; omit to resolve from `rootSelector`.\n   */\n  root?: Element | null;\n  /** Selector for the observation root; empty/omitted = viewport. */\n  rootSelector?: string;\n  rootMargin?: string;\n  threshold?: number | number[];\n}\n\nexport class IntersectionWatcher {\n  readonly #onEntries: (entries: IntersectionObserverEntry[]) => void;\n  #observer: IntersectionObserver | null = null;\n  #active = false;\n\n  constructor(onEntries: (entries: IntersectionObserverEntry[]) => void) {\n    this.#onEntries = onEntries;\n  }\n\n  /** Whether an observer is live (started, `IntersectionObserver` supported). */\n  get active(): boolean {\n    return this.#active;\n  }\n\n  /**\n   * (Re)creates the observer and observes `targets`. Returns `false` — leaving\n   * the watcher inert — without `IntersectionObserver` support (very old\n   * browsers; the caller's no-JS fallback stays in charge) or with no targets.\n   */\n  start(targets: Element | readonly Element[], options: IntersectionWatchOptions = {}): boolean {\n    this.stop();\n    if (typeof IntersectionObserver === \"undefined\") return false;\n    const list = Array.isArray(targets) ? (targets as readonly Element[]) : [targets as Element];\n    if (list.length === 0) return false;\n\n    const root =\n      \"root\" in options\n        ? (options.root ?? null)\n        : options.rootSelector\n          ? document.querySelector(options.rootSelector)\n          : null;\n\n    this.#active = true;\n    this.#observer = new IntersectionObserver(\n      (entries) => {\n        if (this.#active) this.#onEntries(entries);\n      },\n      { root, rootMargin: options.rootMargin, threshold: options.threshold },\n    );\n    for (const target of list) this.#observer.observe(target);\n    return true;\n  }\n\n  /**\n   * Re-delivers `target`'s CURRENT intersection state: `IntersectionObserver`\n   * only reports *changes*, but `observe()` always reports the present state,\n   * so unobserve→observe turns \"still intersecting\" into a fresh callback.\n   */\n  rearm(target: Element): void {\n    if (!this.#observer) return;\n    this.#observer.unobserve(target);\n    this.#observer.observe(target);\n  }\n\n  /** Severs the observer; late queued callbacks become no-ops via the guard. */\n  stop(): void {\n    this.#active = false;\n    this.#observer?.disconnect();\n    this.#observer = null;\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { IntersectionWatcher } from \"../utils/intersection_watcher\";\n\n/**\n * Headless, accessible Scrollspy / Navigation catalog synchronizer.\n *\n * Markup contract (identifier: `stimeo--scrollspy`):\n *   <nav data-controller=\"stimeo--scrollspy\"\n *        data-stimeo--scrollspy-offset-value=\"80\"\n *        aria-label=\"Table of contents\">\n *     <a href=\"#intro\" data-stimeo--scrollspy-target=\"link\">Intro</a>\n *     <a href=\"#usage\" data-stimeo--scrollspy-target=\"link\">Usage</a>\n *   </nav>\n *   <section id=\"intro\">…</section>\n *   <section id=\"usage\">…</section>\n *\n * Implements clean active location synchronization driven by `aria-current`:\n * - Leverages native `IntersectionObserver` to track viewport visibility.\n * - Robust evaluation algorithm: among all intersecting sections, the one closest\n *   to the top offset trigger line (`boundingClientRect.top`) is prioritized as active.\n * - Toggles `aria-current=\"location\"` dynamically on active/inactive links.\n * - Gracefully handles teardown `disconnect()` by severing observer references to prevent leaks.\n *\n * @remarks\n * Behavior only. The controller manages state on catalog links via `aria-current`,\n * respects custom offsets, and dispatches `stimeo--scrollspy:change` events.\n */\nexport class ScrollspyController extends Controller<HTMLElement> {\n  static override targets = [\"link\"];\n  static override values = {\n    offset: { type: Number, default: 0 },\n    rootMargin: { type: String, default: \"\" },\n    rootSelector: { type: String, default: \"\" },\n  };\n  static actions = [\"scrollTo\"] as const;\n  static events = [\"change\"] as const;\n\n  declare readonly linkTargets: HTMLElement[];\n\n  declare offsetValue: number;\n  declare rootMarginValue: string;\n  declare rootSelectorValue: string;\n\n  /** Shared IO plumbing (support guard, active guard, teardown). */\n  readonly #watcher = new IntersectionWatcher((entries) => this.#onIntersection(entries));\n  #isConnected = false;\n\n  /** Track active/intersecting status of each section element by ID. */\n  #intersectionStates = new Map<string, { isIntersecting: boolean; top: number }>();\n\n  /** Current active section ID, used to avoid duplicate event dispatching. */\n  #activeSectionId = \"\";\n\n  override connect(): void {\n    this.#isConnected = true;\n    this.#initializeObserver();\n  }\n\n  override disconnect(): void {\n    this.#isConnected = false;\n    this.#watcher.stop();\n    this.#intersectionStates.clear();\n    this.#activeSectionId = \"\";\n  }\n\n  /**\n   * Re-initializes the observer if the offset or rootMargin values change dynamically.\n   */\n  offsetValueChanged(): void {\n    if (!this.#isConnected) return;\n    this.#initializeObserver();\n  }\n\n  rootMarginValueChanged(): void {\n    if (!this.#isConnected) return;\n    this.#initializeObserver();\n  }\n\n  rootSelectorValueChanged(): void {\n    if (!this.#isConnected) return;\n    this.#initializeObserver();\n  }\n\n  /**\n   * Smoothly scrolls to the target element mapped by the link anchor.\n   * Prevents full window scroll jumps when tracking nested scrollable containers.\n   */\n  scrollTo(event: Event): void {\n    const link = event.currentTarget as HTMLElement;\n    const id = this.#getAnchorId(link);\n    if (!id) return;\n\n    event.preventDefault();\n\n    const targetElement = document.getElementById(id);\n    if (!targetElement) return;\n\n    const rootElement = this.#getRootElement();\n    if (rootElement) {\n      const containerRect = rootElement.getBoundingClientRect();\n      const targetRect = targetElement.getBoundingClientRect();\n      const scrollPosition =\n        rootElement.scrollTop + (targetRect.top - containerRect.top) - this.offsetValue;\n\n      rootElement.scrollTo({\n        top: scrollPosition,\n        behavior: \"smooth\",\n      });\n    } else {\n      const targetRect = targetElement.getBoundingClientRect();\n      const scrollPosition = window.scrollY + targetRect.top - this.offsetValue;\n\n      window.scrollTo({\n        top: scrollPosition,\n        behavior: \"smooth\",\n      });\n    }\n  }\n\n  #getRootElement(): HTMLElement | null {\n    if (!this.rootSelectorValue) return null;\n    return document.querySelector(this.rootSelectorValue);\n  }\n\n  #initializeObserver(): void {\n    this.#watcher.stop();\n    this.#intersectionStates.clear();\n    this.#activeSectionId = \"\";\n\n    if (this.linkTargets.length === 0) return;\n\n    // Build the dynamic rootMargin string based on offset value\n    const margin = this.rootMarginValue || `-${this.offsetValue}px 0px -80% 0px`;\n\n    // Observe each target section mapped by the href anchors.\n    const sections: Element[] = [];\n    for (const link of this.linkTargets) {\n      const id = this.#getAnchorId(link);\n      if (!id) continue;\n      const section = document.getElementById(id);\n      if (section) sections.push(section);\n    }\n\n    this.#watcher.start(sections, {\n      root: this.#getRootElement(),\n      rootMargin: margin,\n      threshold: [0, 0.2, 0.4, 0.6, 0.8, 1], // Multiple thresholds handle large sections safely\n    });\n  }\n\n  readonly #onIntersection = (entries: IntersectionObserverEntry[]): void => {\n    // Ignore any callback delivered after teardown: the browser may flush a\n    // final queued batch right after `disconnect()`, and a detached controller\n    // must not mutate `aria-current` on (possibly cached) links.\n    if (!this.#isConnected) return;\n\n    for (const entry of entries) {\n      const id = entry.target.id;\n      if (!id) continue;\n\n      this.#intersectionStates.set(id, {\n        isIntersecting: entry.isIntersecting,\n        top: entry.boundingClientRect.top,\n      });\n    }\n\n    this.#evaluateActiveSection();\n  };\n\n  #evaluateActiveSection(): void {\n    // The trigger line is `offset` px below the top of the scroll root. When a\n    // nested `rootSelector` container is used it is not at the viewport top, so\n    // the line must be measured from the container's current top — comparing the\n    // viewport-based `boundingClientRect.top` against a bare `offset` would\n    // otherwise pick the section nearest the viewport top, not the container's.\n    const rootEl = this.#getRootElement();\n    const triggerLine = (rootEl ? rootEl.getBoundingClientRect().top : 0) + this.offsetValue;\n\n    let bestId = \"\";\n    let closestTop = Number.MAX_VALUE;\n\n    // Evaluate among all intersecting elements\n    for (const [id, state] of this.#intersectionStates.entries()) {\n      if (state.isIntersecting) {\n        // Evaluate the one closest to the offset trigger line\n        const distance = Math.abs(state.top - triggerLine);\n        if (distance < closestTop) {\n          closestTop = distance;\n          bestId = id;\n        }\n      }\n    }\n\n    // Fallback: when no section currently intersects (e.g. scrolled past the\n    // bottom, or between sections), pick the tracked section whose top is closest\n    // to the trigger line so something stays highlighted.\n    if (!bestId && this.#intersectionStates.size > 0) {\n      let absoluteClosestId = \"\";\n      let absoluteClosestTop = Number.MAX_VALUE;\n\n      for (const [id, state] of this.#intersectionStates.entries()) {\n        const distance = Math.abs(state.top - triggerLine);\n        if (distance < absoluteClosestTop) {\n          absoluteClosestTop = distance;\n          absoluteClosestId = id;\n        }\n      }\n      bestId = absoluteClosestId;\n    }\n\n    if (bestId && bestId !== this.#activeSectionId) {\n      this.#activeSectionId = bestId;\n      this.#syncActiveStates();\n    }\n  }\n\n  #syncActiveStates(): void {\n    const activeLink = this.linkTargets.find((l) => this.#getAnchorId(l) === this.#activeSectionId);\n\n    for (const link of this.linkTargets) {\n      const isActive = link === activeLink;\n      if (isActive) {\n        link.setAttribute(\"aria-current\", \"location\");\n      } else {\n        link.removeAttribute(\"aria-current\");\n      }\n    }\n\n    if (activeLink) {\n      this.dispatch(\"change\", { detail: { id: this.#activeSectionId, link: activeLink } });\n    }\n  }\n\n  #getAnchorId(link: HTMLElement): string | null {\n    const href = link.getAttribute(\"href\") || link.getAttribute(\"data-href\");\n    if (!href?.startsWith(\"#\")) return null;\n    return href.substring(1);\n  }\n}\n"]}
+{"version":3,"sources":["../../src/utils/intersection_watcher.ts","../../src/controllers/scrollspy_controller.ts"],"names":[],"mappings":"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","file":"scrollspy_controller.js","sourcesContent":["/**\n * Shared `IntersectionObserver` plumbing for Stimeo's scroll-triggered\n * controllers (`intersection`, `scrollspy`, `sticky-observer`, `lazy-frame`).\n *\n * It centralizes the `IntersectionObserver` support guard, root resolution from\n * a selector, observer creation/teardown, the **active guard** (the browser may\n * flush a final queued callback batch right after `disconnect()`, and a\n * detached controller must not mutate possibly-cached DOM), and the\n * unobserve→observe **re-arm** that re-delivers the current state even when the\n * target never leaves the viewport.\n *\n * Like {@link RovingTabindex} and `FocusTrap`, this is a policy-free internal\n * util: what an intersection *means* (a spied link, a stuck header, a lazy\n * load) stays in each controller. The public `stimeo--intersection` controller\n * is its thin declarative face.\n */\n/**\n * Whether `entry`'s target sits entirely before the root's **start (top)** edge —\n * the \"scrolled past the top\" half of a non-intersecting entry, as opposed to\n * \"not reached yet\" below the root.\n *\n * A target with no layout box (`display: none`, a `hidden` ancestor, a collapsed\n * `<details>`) is reported with an **empty rect**, whose `bottom` of `0` would\n * otherwise satisfy `bottom <= rootTop` for a viewport root and read as \"passed\"\n * even though the target was never scrolled anywhere. An empty rect carries no\n * position at all, so it is deliberately never \"before the edge\"; what a caller\n * publishes for that case is its own policy (both consumers treat it as the\n * neutral \"not passed\"/\"not stuck\", and the real rect that arrives once the\n * target is laid out re-establishes the true state).\n */\nexport function isBeforeRootStart(entry: IntersectionObserverEntry): boolean {\n  const rect = entry.boundingClientRect;\n  if (rect.width === 0 && rect.height === 0) return false;\n  // rootBounds is null for a cross-origin/removed root; fall back to the\n  // viewport origin.\n  const rootTop = entry.rootBounds?.top ?? 0;\n  return rect.bottom <= rootTop;\n}\n\nexport interface IntersectionWatchOptions {\n  /**\n   * The observation root. Pass an element (or `null` for the viewport) when\n   * the caller already resolved it; omit to resolve from `rootSelector`.\n   */\n  root?: Element | null;\n  /** Selector for the observation root; empty/omitted = viewport. */\n  rootSelector?: string;\n  rootMargin?: string;\n  threshold?: number | number[];\n}\n\nexport class IntersectionWatcher {\n  readonly #onEntries: (entries: IntersectionObserverEntry[]) => void;\n  #observer: IntersectionObserver | null = null;\n  #active = false;\n\n  constructor(onEntries: (entries: IntersectionObserverEntry[]) => void) {\n    this.#onEntries = onEntries;\n  }\n\n  /** Whether an observer is live (started, `IntersectionObserver` supported). */\n  get active(): boolean {\n    return this.#active;\n  }\n\n  /**\n   * (Re)creates the observer and observes `targets`. Returns `false` — leaving\n   * the watcher inert — without `IntersectionObserver` support (very old\n   * browsers; the caller's no-JS fallback stays in charge) or with no targets.\n   *\n   * @throws Whatever the platform throws for an invalid `rootMargin`/`threshold`\n   *   or a failing `observe()`. The exception is passed through unchanged, but\n   *   the watcher rolls back first: every target observed so far is released and\n   *   `active` stays `false`, so a caller that retries starts from a clean slate.\n   */\n  start(targets: Element | readonly Element[], options: IntersectionWatchOptions = {}): boolean {\n    this.stop();\n    if (typeof IntersectionObserver === \"undefined\") return false;\n    const list = Array.isArray(targets) ? (targets as readonly Element[]) : [targets as Element];\n    if (list.length === 0) return false;\n\n    const root =\n      \"root\" in options\n        ? (options.root ?? null)\n        : options.rootSelector\n          ? document.querySelector(options.rootSelector)\n          : null;\n\n    let observer: IntersectionObserver | null = null;\n    try {\n      observer = new IntersectionObserver(\n        (entries) => {\n          // Identity matters across an immediate restart: the old observer can\n          // flush a queued batch after the new observer has made `active` true.\n          if (this.#active && this.#observer === observer) this.#onEntries(entries);\n        },\n        { root, rootMargin: options.rootMargin, threshold: options.threshold },\n      );\n      for (const target of list) observer.observe(target);\n      this.#observer = observer;\n      this.#active = true;\n      return true;\n    } catch (error) {\n      // A constructor or partial observe failure must not leave earlier targets\n      // observed or report an active watcher. Preserve the platform exception.\n      observer?.disconnect();\n      this.#observer = null;\n      this.#active = false;\n      throw error;\n    }\n  }\n\n  /**\n   * Re-delivers `target`'s CURRENT intersection state: `IntersectionObserver`\n   * only reports *changes*, but `observe()` always reports the present state,\n   * so unobserve→observe turns \"still intersecting\" into a fresh callback.\n   *\n   * @throws Whatever `unobserve()`/`observe()` throws. The watcher is stopped\n   *   first, so it never stays live with a half-rearmed target.\n   */\n  rearm(target: Element): void {\n    if (!this.#observer) return;\n    try {\n      this.#observer.unobserve(target);\n      this.#observer.observe(target);\n    } catch (error) {\n      this.stop();\n      throw error;\n    }\n  }\n\n  /** Severs the observer; late queued callbacks become no-ops via the guard. */\n  stop(): void {\n    this.#active = false;\n    this.#observer?.disconnect();\n    this.#observer = null;\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { IntersectionWatcher } from \"../utils/intersection_watcher\";\n\n/**\n * Headless, accessible Scrollspy / Navigation catalog synchronizer.\n *\n * Markup contract (identifier: `stimeo--scrollspy`):\n *   <nav data-controller=\"stimeo--scrollspy\"\n *        data-stimeo--scrollspy-offset-value=\"80\"\n *        aria-label=\"Table of contents\">\n *     <a href=\"#intro\" data-stimeo--scrollspy-target=\"link\">Intro</a>\n *     <a href=\"#usage\" data-stimeo--scrollspy-target=\"link\">Usage</a>\n *   </nav>\n *   <section id=\"intro\">…</section>\n *   <section id=\"usage\">…</section>\n *\n * Implements clean active location synchronization driven by `aria-current`:\n * - Leverages native `IntersectionObserver` to track viewport visibility.\n * - Robust evaluation algorithm: among all intersecting sections, the one closest\n *   to the top offset trigger line (`boundingClientRect.top`) is prioritized as active.\n * - Toggles `aria-current=\"location\"` dynamically on active/inactive links.\n * - Gracefully handles teardown `disconnect()` by severing observer references to prevent leaks.\n *\n * @remarks\n * Behavior only. The controller manages state on catalog links via `aria-current`,\n * respects custom offsets, and dispatches `stimeo--scrollspy:change` events.\n */\nexport class ScrollspyController extends Controller<HTMLElement> {\n  static override targets = [\"link\"];\n  static override values = {\n    offset: { type: Number, default: 0 },\n    rootMargin: { type: String, default: \"\" },\n    rootSelector: { type: String, default: \"\" },\n  };\n  static actions = [\"scrollTo\"] as const;\n  static events = [\"change\"] as const;\n\n  declare readonly linkTargets: HTMLElement[];\n\n  declare offsetValue: number;\n  declare rootMarginValue: string;\n  declare rootSelectorValue: string;\n\n  /** Shared IO plumbing (support guard, active guard, teardown). */\n  readonly #watcher = new IntersectionWatcher((entries) => this.#onIntersection(entries));\n  #isConnected = false;\n\n  /** Track active/intersecting status of each section element by ID. */\n  #intersectionStates = new Map<string, { isIntersecting: boolean; top: number }>();\n\n  /** Current active section ID, used to avoid duplicate event dispatching. */\n  #activeSectionId = \"\";\n\n  override connect(): void {\n    this.#isConnected = true;\n    this.#initializeObserver();\n  }\n\n  override disconnect(): void {\n    this.#isConnected = false;\n    this.#watcher.stop();\n    this.#intersectionStates.clear();\n    this.#activeSectionId = \"\";\n  }\n\n  /**\n   * Re-initializes the observer if the offset or rootMargin values change dynamically.\n   */\n  offsetValueChanged(): void {\n    if (!this.#isConnected) return;\n    this.#initializeObserver();\n  }\n\n  rootMarginValueChanged(): void {\n    if (!this.#isConnected) return;\n    this.#initializeObserver();\n  }\n\n  rootSelectorValueChanged(): void {\n    if (!this.#isConnected) return;\n    this.#initializeObserver();\n  }\n\n  /**\n   * Smoothly scrolls to the target element mapped by the link anchor.\n   * Prevents full window scroll jumps when tracking nested scrollable containers.\n   */\n  scrollTo(event: Event): void {\n    const link = event.currentTarget as HTMLElement;\n    const id = this.#getAnchorId(link);\n    if (!id) return;\n\n    event.preventDefault();\n\n    const targetElement = document.getElementById(id);\n    if (!targetElement) return;\n\n    const rootElement = this.#getRootElement();\n    if (rootElement) {\n      const containerRect = rootElement.getBoundingClientRect();\n      const targetRect = targetElement.getBoundingClientRect();\n      const scrollPosition =\n        rootElement.scrollTop + (targetRect.top - containerRect.top) - this.offsetValue;\n\n      rootElement.scrollTo({\n        top: scrollPosition,\n        behavior: \"smooth\",\n      });\n    } else {\n      const targetRect = targetElement.getBoundingClientRect();\n      const scrollPosition = window.scrollY + targetRect.top - this.offsetValue;\n\n      window.scrollTo({\n        top: scrollPosition,\n        behavior: \"smooth\",\n      });\n    }\n  }\n\n  #getRootElement(): HTMLElement | null {\n    if (!this.rootSelectorValue) return null;\n    return document.querySelector(this.rootSelectorValue);\n  }\n\n  #initializeObserver(): void {\n    this.#watcher.stop();\n    this.#intersectionStates.clear();\n    this.#activeSectionId = \"\";\n\n    if (this.linkTargets.length === 0) return;\n\n    // Build the dynamic rootMargin string based on offset value\n    const margin = this.rootMarginValue || `-${this.offsetValue}px 0px -80% 0px`;\n\n    // Observe each target section mapped by the href anchors.\n    const sections: Element[] = [];\n    for (const link of this.linkTargets) {\n      const id = this.#getAnchorId(link);\n      if (!id) continue;\n      const section = document.getElementById(id);\n      if (section) sections.push(section);\n    }\n\n    this.#watcher.start(sections, {\n      root: this.#getRootElement(),\n      rootMargin: margin,\n      threshold: [0, 0.2, 0.4, 0.6, 0.8, 1], // Multiple thresholds handle large sections safely\n    });\n  }\n\n  readonly #onIntersection = (entries: IntersectionObserverEntry[]): void => {\n    // Ignore any callback delivered after teardown: the browser may flush a\n    // final queued batch right after `disconnect()`, and a detached controller\n    // must not mutate `aria-current` on (possibly cached) links.\n    if (!this.#isConnected) return;\n\n    for (const entry of entries) {\n      const id = entry.target.id;\n      if (!id) continue;\n\n      this.#intersectionStates.set(id, {\n        isIntersecting: entry.isIntersecting,\n        top: entry.boundingClientRect.top,\n      });\n    }\n\n    this.#evaluateActiveSection();\n  };\n\n  #evaluateActiveSection(): void {\n    // The trigger line is `offset` px below the top of the scroll root. When a\n    // nested `rootSelector` container is used it is not at the viewport top, so\n    // the line must be measured from the container's current top — comparing the\n    // viewport-based `boundingClientRect.top` against a bare `offset` would\n    // otherwise pick the section nearest the viewport top, not the container's.\n    const rootEl = this.#getRootElement();\n    const triggerLine = (rootEl ? rootEl.getBoundingClientRect().top : 0) + this.offsetValue;\n\n    let bestId = \"\";\n    let closestTop = Number.MAX_VALUE;\n\n    // Evaluate among all intersecting elements\n    for (const [id, state] of this.#intersectionStates.entries()) {\n      if (state.isIntersecting) {\n        // Evaluate the one closest to the offset trigger line\n        const distance = Math.abs(state.top - triggerLine);\n        if (distance < closestTop) {\n          closestTop = distance;\n          bestId = id;\n        }\n      }\n    }\n\n    // Fallback: when no section currently intersects (e.g. scrolled past the\n    // bottom, or between sections), pick the tracked section whose top is closest\n    // to the trigger line so something stays highlighted.\n    if (!bestId && this.#intersectionStates.size > 0) {\n      let absoluteClosestId = \"\";\n      let absoluteClosestTop = Number.MAX_VALUE;\n\n      for (const [id, state] of this.#intersectionStates.entries()) {\n        const distance = Math.abs(state.top - triggerLine);\n        if (distance < absoluteClosestTop) {\n          absoluteClosestTop = distance;\n          absoluteClosestId = id;\n        }\n      }\n      bestId = absoluteClosestId;\n    }\n\n    if (bestId && bestId !== this.#activeSectionId) {\n      this.#activeSectionId = bestId;\n      this.#syncActiveStates();\n    }\n  }\n\n  #syncActiveStates(): void {\n    const activeLink = this.linkTargets.find((l) => this.#getAnchorId(l) === this.#activeSectionId);\n\n    for (const link of this.linkTargets) {\n      const isActive = link === activeLink;\n      if (isActive) {\n        link.setAttribute(\"aria-current\", \"location\");\n      } else {\n        link.removeAttribute(\"aria-current\");\n      }\n    }\n\n    if (activeLink) {\n      this.dispatch(\"change\", { detail: { id: this.#activeSectionId, link: activeLink } });\n    }\n  }\n\n  #getAnchorId(link: HTMLElement): string | null {\n    const href = link.getAttribute(\"href\") || link.getAttribute(\"data-href\");\n    if (!href?.startsWith(\"#\")) return null;\n    return href.substring(1);\n  }\n}\n"]}

package/dist/controllers/separator_controller.d.ts

@@ -0,0 +1,54 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless **Separator** behavior (APG Separator pattern).
+ *
+ * Markup contract (identifier: `stimeo--separator`):
+ *   <!-- decorative -->
+ *   <div data-controller="stimeo--separator" role="separator"
+ *        data-stimeo--separator-orientation-value="horizontal"></div>
+ *
+ *   <!-- focusable, value-bearing -->
+ *   <div data-controller="stimeo--separator" role="separator" tabindex="0"
+ *        aria-label="Resize sidebar" aria-orientation="vertical"
+ *        aria-valuemin="0" aria-valuemax="100" aria-valuenow="50"
+ *        data-stimeo--separator-focusable-value="true"
+ *        data-action="keydown->stimeo--separator#onKeydown"></div>
+ *
+ * Most separators are static (`role="separator"` + `aria-orientation`); this
+ * controller adds those semantics and, for the optional **focusable** variant,
+ * keeps `aria-valuenow` in sync and emits arrow-key value changes. The actual
+ * pane resize/drag is out of scope — that belongs to {@link ResizableController}.
+ *
+ * @remarks
+ * Behavior only — line drawing is the consumer's CSS. Increment direction
+ * follows the slider convention: ArrowUp/ArrowRight increase, ArrowDown/ArrowLeft
+ * decrease, scoped to the relevant axis for the orientation.
+ */
+declare class SeparatorController extends Controller<HTMLElement> {
+    #private;
+    static values: {
+        orientation: {
+            type: StringConstructor;
+            default: string;
+        };
+        focusable: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        step: {
+            type: NumberConstructor;
+            default: number;
+        };
+    };
+    static actions: readonly ["onKeydown"];
+    static events: readonly ["change"];
+    orientationValue: string;
+    focusableValue: boolean;
+    stepValue: number;
+    connect(): void;
+    /** Adjusts the value on arrow / Home / End keys (focusable variant only). */
+    onKeydown(event: KeyboardEvent): void;
+}
+
+export { SeparatorController };

package/dist/controllers/separator_controller.js

@@ -0,0 +1,87 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/separator_controller.ts
+var SeparatorController = class extends Controller {
+  static values = {
+    orientation: { type: String, default: "horizontal" },
+    focusable: { type: Boolean, default: false },
+    step: { type: Number, default: 1 }
+  };
+  static actions = ["onKeydown"];
+  static events = ["change"];
+  connect() {
+    if (!this.element.hasAttribute("role")) {
+      this.element.setAttribute("role", "separator");
+    }
+    if (!this.element.hasAttribute("aria-orientation")) {
+      this.element.setAttribute("aria-orientation", this.orientationValue);
+    }
+    if (this.focusableValue) {
+      if (!this.element.hasAttribute("tabindex")) {
+        this.element.setAttribute("tabindex", "0");
+      }
+      this.#setDefault("aria-valuemin", "0");
+      this.#setDefault("aria-valuemax", "100");
+      this.#setDefault("aria-valuenow", String(this.#clamp(this.#value)));
+    }
+  }
+  /** Adjusts the value on arrow / Home / End keys (focusable variant only). */
+  onKeydown(event) {
+    if (!this.focusableValue) return;
+    const horizontal = this.element.getAttribute("aria-orientation") !== "vertical";
+    let next = null;
+    switch (event.key) {
+      case "ArrowUp":
+        if (horizontal) next = this.#value + this.stepValue;
+        break;
+      case "ArrowDown":
+        if (horizontal) next = this.#value - this.stepValue;
+        break;
+      case "ArrowRight":
+        if (!horizontal) next = this.#value + this.stepValue;
+        break;
+      case "ArrowLeft":
+        if (!horizontal) next = this.#value - this.stepValue;
+        break;
+      case "Home":
+        next = this.#min;
+        break;
+      case "End":
+        next = this.#max;
+        break;
+      default:
+        return;
+    }
+    if (next === null) return;
+    event.preventDefault();
+    const clamped = this.#clamp(next);
+    if (clamped === this.#value) return;
+    this.element.setAttribute("aria-valuenow", String(clamped));
+    this.dispatch("change", { detail: { value: clamped } });
+  }
+  get #value() {
+    return this.#numericAttr("aria-valuenow", 0);
+  }
+  get #min() {
+    return this.#numericAttr("aria-valuemin", 0);
+  }
+  get #max() {
+    return this.#numericAttr("aria-valuemax", 100);
+  }
+  #clamp(value) {
+    return Math.min(this.#max, Math.max(this.#min, value));
+  }
+  #numericAttr(name, fallback) {
+    const parsed = Number.parseFloat(this.element.getAttribute(name) ?? "");
+    return Number.isNaN(parsed) ? fallback : parsed;
+  }
+  #setDefault(name, value) {
+    if (!this.element.hasAttribute(name)) {
+      this.element.setAttribute(name, value);
+    }
+  }
+};
+
+export { SeparatorController };
+//# sourceMappingURL=separator_controller.js.map
+//# sourceMappingURL=separator_controller.js.map

package/dist/controllers/separator_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/controllers/separator_controller.ts"],"names":[],"mappings":"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","file":"separator_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/**\n * Headless **Separator** behavior (APG Separator pattern).\n *\n * Markup contract (identifier: `stimeo--separator`):\n *   <!-- decorative -->\n *   <div data-controller=\"stimeo--separator\" role=\"separator\"\n *        data-stimeo--separator-orientation-value=\"horizontal\"></div>\n *\n *   <!-- focusable, value-bearing -->\n *   <div data-controller=\"stimeo--separator\" role=\"separator\" tabindex=\"0\"\n *        aria-label=\"Resize sidebar\" aria-orientation=\"vertical\"\n *        aria-valuemin=\"0\" aria-valuemax=\"100\" aria-valuenow=\"50\"\n *        data-stimeo--separator-focusable-value=\"true\"\n *        data-action=\"keydown->stimeo--separator#onKeydown\"></div>\n *\n * Most separators are static (`role=\"separator\"` + `aria-orientation`); this\n * controller adds those semantics and, for the optional **focusable** variant,\n * keeps `aria-valuenow` in sync and emits arrow-key value changes. The actual\n * pane resize/drag is out of scope — that belongs to {@link ResizableController}.\n *\n * @remarks\n * Behavior only — line drawing is the consumer's CSS. Increment direction\n * follows the slider convention: ArrowUp/ArrowRight increase, ArrowDown/ArrowLeft\n * decrease, scoped to the relevant axis for the orientation.\n */\nexport class SeparatorController extends Controller<HTMLElement> {\n  static override values = {\n    orientation: { type: String, default: \"horizontal\" },\n    focusable: { type: Boolean, default: false },\n    step: { type: Number, default: 1 },\n  };\n  static actions = [\"onKeydown\"] as const;\n  static events = [\"change\"] as const;\n\n  declare orientationValue: string;\n  declare focusableValue: boolean;\n  declare stepValue: number;\n\n  override connect(): void {\n    if (!this.element.hasAttribute(\"role\")) {\n      this.element.setAttribute(\"role\", \"separator\");\n    }\n    if (!this.element.hasAttribute(\"aria-orientation\")) {\n      this.element.setAttribute(\"aria-orientation\", this.orientationValue);\n    }\n\n    if (this.focusableValue) {\n      if (!this.element.hasAttribute(\"tabindex\")) {\n        this.element.setAttribute(\"tabindex\", \"0\");\n      }\n      // A value-bearing separator needs a bounded range; default it if the\n      // consumer left any bound off so arrow keys have something to clamp to.\n      this.#setDefault(\"aria-valuemin\", \"0\");\n      this.#setDefault(\"aria-valuemax\", \"100\");\n      this.#setDefault(\"aria-valuenow\", String(this.#clamp(this.#value)));\n    }\n  }\n\n  /** Adjusts the value on arrow / Home / End keys (focusable variant only). */\n  onKeydown(event: KeyboardEvent): void {\n    if (!this.focusableValue) return;\n\n    // `aria-orientation` is the source of truth (connect seeds it from the\n    // orientation value when the consumer left it off), so the focusable variant\n    // that sets the attribute directly drives the axis correctly.\n    const horizontal = this.element.getAttribute(\"aria-orientation\") !== \"vertical\";\n    let next: number | null = null;\n    switch (event.key) {\n      case \"ArrowUp\":\n        if (horizontal) next = this.#value + this.stepValue;\n        break;\n      case \"ArrowDown\":\n        if (horizontal) next = this.#value - this.stepValue;\n        break;\n      case \"ArrowRight\":\n        if (!horizontal) next = this.#value + this.stepValue;\n        break;\n      case \"ArrowLeft\":\n        if (!horizontal) next = this.#value - this.stepValue;\n        break;\n      case \"Home\":\n        next = this.#min;\n        break;\n      case \"End\":\n        next = this.#max;\n        break;\n      default:\n        return;\n    }\n    if (next === null) return;\n\n    event.preventDefault();\n    const clamped = this.#clamp(next);\n    if (clamped === this.#value) return;\n\n    this.element.setAttribute(\"aria-valuenow\", String(clamped));\n    this.dispatch(\"change\", { detail: { value: clamped } });\n  }\n\n  get #value(): number {\n    return this.#numericAttr(\"aria-valuenow\", 0);\n  }\n\n  get #min(): number {\n    return this.#numericAttr(\"aria-valuemin\", 0);\n  }\n\n  get #max(): number {\n    return this.#numericAttr(\"aria-valuemax\", 100);\n  }\n\n  #clamp(value: number): number {\n    return Math.min(this.#max, Math.max(this.#min, value));\n  }\n\n  #numericAttr(name: string, fallback: number): number {\n    const parsed = Number.parseFloat(this.element.getAttribute(name) ?? \"\");\n    return Number.isNaN(parsed) ? fallback : parsed;\n  }\n\n  #setDefault(name: string, value: string): void {\n    if (!this.element.hasAttribute(name)) {\n      this.element.setAttribute(name, value);\n    }\n  }\n}\n"]}

package/dist/controllers/sidebar_controller.d.ts

@@ -0,0 +1,107 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless, accessible **responsive collapsible sidebar** behavior.
+ *
+ * Markup contract (identifier: `stimeo--sidebar`):
+ *   <div data-controller="stimeo--sidebar"
+ *        data-action="turbo:before-cache@document->stimeo--sidebar#beforeCache"
+ *        data-stimeo--sidebar-breakpoint-value="768"
+ *        data-stimeo--sidebar-key-value="main-nav">
+ *     <header>
+ *       <button data-stimeo--sidebar-target="trigger"
+ *               data-action="click->stimeo--sidebar#toggle"
+ *               aria-expanded="true" aria-controls="app-sidebar">Menu</button>
+ *     </header>
+ *     <div data-stimeo--sidebar-target="backdrop"
+ *          data-action="click->stimeo--sidebar#close" hidden></div>
+ *     <aside id="app-sidebar" data-stimeo--sidebar-target="panel"
+ *            aria-label="Main" data-mode="inline" data-state="expanded">
+ *       <nav aria-label="…">…</nav>
+ *     </aside>
+ *   </div>
+ *   <main>…</main>   <!-- a body-level sibling so it can be made inert in overlay -->
+ *
+ * No dedicated APG pattern: the base is **Disclosure** (the trigger's
+ * `aria-expanded` controls the panel's expanded state) and, *below* the
+ * `breakpoint`, it borrows the **Dialog (Modal)** focus behavior via the shared
+ * {@link FocusTrap} (the same trap used by dialog / alert-dialog / drawer).
+ *
+ * Above the breakpoint it is an **inline**, non-modal element that toggles
+ * `expanded`↔`collapsed` (a rail), persisting that preference in `localStorage`.
+ * Below it, it becomes an **overlay** off-canvas panel: opening activates the
+ * trap (focus move, `Tab` cycle, `Escape`, body scroll lock, background `inert`,
+ * focus restore); closing defers `hidden` and the trap teardown until the exit
+ * transition ends (synchronously when there is none).
+ *
+ * @remarks
+ * Behavior only — rail width, slide, and backdrop are the consumer's CSS, keyed
+ * off `data-mode` (`inline`/`overlay`) and `data-state`. `aria-expanded` is an
+ * abstract "is the panel expanded" flag, independent of the visual difference
+ * between an inline collapsed rail (still in the DOM) and an overlay closed panel
+ * (`hidden`/off-canvas). The `role="dialog"` semantics are intentionally **not**
+ * applied — the sidebar stays an `<aside>`/`<nav>` landmark and only borrows the
+ * modal *behavior* (cf. drawer's note on `<aside role="dialog">` conflicts).
+ * The collapsed preference persists across Turbo navigations and full reloads;
+ * the transient overlay-open state never persists, so "back/forward" never
+ * restores a stuck-open menu.
+ */
+declare class SidebarController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        breakpoint: {
+            type: NumberConstructor;
+            default: number;
+        };
+        key: {
+            type: StringConstructor;
+            default: string;
+        };
+        collapsed: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+    };
+    static actions: readonly ["beforeCache", "close", "open", "toggle"];
+    readonly triggerTarget: HTMLElement;
+    readonly panelTarget: HTMLElement;
+    readonly backdropTarget: HTMLElement;
+    readonly hasTriggerTarget: boolean;
+    readonly hasPanelTarget: boolean;
+    readonly hasBackdropTarget: boolean;
+    breakpointValue: number;
+    keyValue: string;
+    collapsedValue: boolean;
+    connect(): void;
+    disconnect(): void;
+    /** Adopts a panel target added by a Turbo morph after the controller connected. */
+    panelTargetConnected(panel: HTMLElement): void;
+    /** Closes and releases overlay side effects when the actively trapped panel disappears. */
+    panelTargetDisconnected(panel: HTMLElement): void;
+    /**
+     * Rebinds responsive observation when `breakpoint` changes at runtime.
+     *
+     * Stimulus calls value callbacks before `connect()`, so the connected guard
+     * prevents an eager subscription. Equivalent normalized queries retain the
+     * existing listener instead of allocating duplicate `MediaQueryList` objects.
+     */
+    breakpointValueChanged(): void;
+    /**
+     * Sanitizes overlay markup before Turbo snapshots the page.
+     *
+     * Inline state is durable and remains untouched. Overlay state is transient:
+     * pending transitions are cancelled, controller-owned open attributes are
+     * closed immediately, and modal side effects are released without moving
+     * focus during navigation.
+     */
+    beforeCache(): void;
+    /** Toggles the panel: inline flips collapsed/expanded, overlay flips open/closed. */
+    toggle(): void;
+    /** Shows the panel (inline: expand; overlay: open). */
+    open(): void;
+    /** Hides the panel (inline: collapse; overlay: close). */
+    close(): void;
+}
+
+export { SidebarController };