stimeo-ui 0.1.0-alpha.1

package/dist/controllers/scrollspy_controller.js

@@ -0,0 +1,171 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/scrollspy_controller.ts
+var ScrollspyController = class extends Controller {
+  static targets = ["link"];
+  static values = {
+    offset: { type: Number, default: 0 },
+    rootMargin: { type: String, default: "" },
+    rootSelector: { type: String, default: "" }
+  };
+  static actions = ["scrollTo"];
+  static events = ["change"];
+  #observer = null;
+  #isConnected = false;
+  /** Track active/intersecting status of each section element by ID. */
+  #intersectionStates = /* @__PURE__ */ new Map();
+  /** Current active section ID, used to avoid duplicate event dispatching. */
+  #activeSectionId = "";
+  connect() {
+    this.#isConnected = true;
+    this.#initializeObserver();
+  }
+  disconnect() {
+    this.#isConnected = false;
+    if (this.#observer) {
+      this.#observer.disconnect();
+      this.#observer = null;
+    }
+    this.#intersectionStates.clear();
+    this.#activeSectionId = "";
+  }
+  /**
+   * Re-initializes the observer if the offset or rootMargin values change dynamically.
+   */
+  offsetValueChanged() {
+    if (!this.#isConnected) return;
+    this.#initializeObserver();
+  }
+  rootMarginValueChanged() {
+    if (!this.#isConnected) return;
+    this.#initializeObserver();
+  }
+  rootSelectorValueChanged() {
+    if (!this.#isConnected) return;
+    this.#initializeObserver();
+  }
+  /**
+   * Smoothly scrolls to the target element mapped by the link anchor.
+   * Prevents full window scroll jumps when tracking nested scrollable containers.
+   */
+  scrollTo(event) {
+    const link = event.currentTarget;
+    const id = this.#getAnchorId(link);
+    if (!id) return;
+    event.preventDefault();
+    const targetElement = document.getElementById(id);
+    if (!targetElement) return;
+    const rootElement = this.#getRootElement();
+    if (rootElement) {
+      const containerRect = rootElement.getBoundingClientRect();
+      const targetRect = targetElement.getBoundingClientRect();
+      const scrollPosition = rootElement.scrollTop + (targetRect.top - containerRect.top) - this.offsetValue;
+      rootElement.scrollTo({
+        top: scrollPosition,
+        behavior: "smooth"
+      });
+    } else {
+      const targetRect = targetElement.getBoundingClientRect();
+      const scrollPosition = window.scrollY + targetRect.top - this.offsetValue;
+      window.scrollTo({
+        top: scrollPosition,
+        behavior: "smooth"
+      });
+    }
+  }
+  #getRootElement() {
+    if (!this.rootSelectorValue) return null;
+    return document.querySelector(this.rootSelectorValue);
+  }
+  #initializeObserver() {
+    if (this.#observer) {
+      this.#observer.disconnect();
+      this.#observer = null;
+    }
+    this.#intersectionStates.clear();
+    this.#activeSectionId = "";
+    if (this.linkTargets.length === 0) return;
+    const margin = this.rootMarginValue || `-${this.offsetValue}px 0px -80% 0px`;
+    const rootEl = this.#getRootElement();
+    this.#observer = new IntersectionObserver(this.#onIntersection, {
+      root: rootEl,
+      rootMargin: margin,
+      threshold: [0, 0.2, 0.4, 0.6, 0.8, 1]
+      // Multiple thresholds handle large sections safely
+    });
+    for (const link of this.linkTargets) {
+      const id = this.#getAnchorId(link);
+      if (!id) continue;
+      const section = document.getElementById(id);
+      if (section) {
+        this.#observer.observe(section);
+      }
+    }
+  }
+  #onIntersection = (entries) => {
+    if (!this.#isConnected) return;
+    for (const entry of entries) {
+      const id = entry.target.id;
+      if (!id) continue;
+      this.#intersectionStates.set(id, {
+        isIntersecting: entry.isIntersecting,
+        top: entry.boundingClientRect.top
+      });
+    }
+    this.#evaluateActiveSection();
+  };
+  #evaluateActiveSection() {
+    const rootEl = this.#getRootElement();
+    const triggerLine = (rootEl ? rootEl.getBoundingClientRect().top : 0) + this.offsetValue;
+    let bestId = "";
+    let closestTop = Number.MAX_VALUE;
+    for (const [id, state] of this.#intersectionStates.entries()) {
+      if (state.isIntersecting) {
+        const distance = Math.abs(state.top - triggerLine);
+        if (distance < closestTop) {
+          closestTop = distance;
+          bestId = id;
+        }
+      }
+    }
+    if (!bestId && this.#intersectionStates.size > 0) {
+      let absoluteClosestId = "";
+      let absoluteClosestTop = Number.MAX_VALUE;
+      for (const [id, state] of this.#intersectionStates.entries()) {
+        const distance = Math.abs(state.top - triggerLine);
+        if (distance < absoluteClosestTop) {
+          absoluteClosestTop = distance;
+          absoluteClosestId = id;
+        }
+      }
+      bestId = absoluteClosestId;
+    }
+    if (bestId && bestId !== this.#activeSectionId) {
+      this.#activeSectionId = bestId;
+      this.#syncActiveStates();
+    }
+  }
+  #syncActiveStates() {
+    const activeLink = this.linkTargets.find((l) => this.#getAnchorId(l) === this.#activeSectionId);
+    for (const link of this.linkTargets) {
+      const isActive = link === activeLink;
+      if (isActive) {
+        link.setAttribute("aria-current", "location");
+      } else {
+        link.removeAttribute("aria-current");
+      }
+    }
+    if (activeLink) {
+      this.dispatch("change", { detail: { id: this.#activeSectionId, link: activeLink } });
+    }
+  }
+  #getAnchorId(link) {
+    const href = link.getAttribute("href") || link.getAttribute("data-href");
+    if (!href?.startsWith("#")) return null;
+    return href.substring(1);
+  }
+};
+
+export { ScrollspyController };
+//# sourceMappingURL=scrollspy_controller.js.map
+//# sourceMappingURL=scrollspy_controller.js.map

package/dist/controllers/scrollspy_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/controllers/scrollspy_controller.ts"],"names":[],"mappings":"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","file":"scrollspy_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\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  #observer: IntersectionObserver | null = null;\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    if (this.#observer) {\n      this.#observer.disconnect();\n      this.#observer = null;\n    }\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    if (this.#observer) {\n      this.#observer.disconnect();\n      this.#observer = null;\n    }\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    const rootEl = this.#getRootElement();\n\n    this.#observer = new IntersectionObserver(this.#onIntersection, {\n      root: rootEl,\n      rootMargin: margin,\n      threshold: [0, 0.2, 0.4, 0.6, 0.8, 1], // Multiple thresholds handle large sections safely\n    });\n\n    // Observe each target section mapped by the href anchors\n    for (const link of this.linkTargets) {\n      const id = this.#getAnchorId(link);\n      if (!id) continue;\n\n      const section = document.getElementById(id);\n      if (section) {\n        this.#observer.observe(section);\n      }\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/skeleton_controller.d.ts

@@ -0,0 +1,50 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless skeleton/placeholder manager. No dedicated APG pattern; it follows
+ * the `aria-busy` + show/hide practice.
+ *
+ * Markup contract (identifier: `stimeo--skeleton`):
+ *   <div data-controller="stimeo--skeleton" aria-busy="true"
+ *        data-stimeo--skeleton-min-duration-value="300"
+ *        data-action="content:ready->stimeo--skeleton#ready">
+ *     <div aria-hidden="true" data-stimeo--skeleton-target="placeholder"></div>
+ *     <div hidden data-stimeo--skeleton-target="content"></div>
+ *   </div>
+ *
+ * Starts in the loading state (placeholder shown, real content hidden, region
+ * `aria-busy="true"`); `ready` swaps to the content and clears busy. The
+ * placeholder is `aria-hidden` (decorative) so assistive tech never reads the
+ * skeleton. `minDuration` keeps the placeholder up long enough to avoid a flash
+ * when content arrives almost immediately.
+ *
+ * @remarks
+ * Behavior only — skeleton shapes/animation are the consumer's. The
+ * min-duration timer is owned by {@link SafeTimeout} and torn down on
+ * `disconnect()` (Turbo navigation included).
+ */
+declare class SkeletonController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        minDuration: {
+            type: NumberConstructor;
+            default: number;
+        };
+    };
+    static actions: readonly ["ready", "reset"];
+    static events: readonly ["ready"];
+    readonly placeholderTarget: HTMLElement;
+    readonly contentTarget: HTMLElement;
+    readonly hasPlaceholderTarget: boolean;
+    readonly hasContentTarget: boolean;
+    minDurationValue: number;
+    connect(): void;
+    disconnect(): void;
+    /** Swaps to the real content. Honors `minDuration` to prevent a flash. */
+    ready(): void;
+    /** Returns to the loading state (e.g. a Turbo Stream re-fetch). */
+    reset(): void;
+}
+
+export { SkeletonController };

package/dist/controllers/skeleton_controller.js

@@ -0,0 +1,125 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/skeleton_controller.ts
+
+// src/utils/safe_timeout.ts
+var TimerRegistry = class {
+  /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
+  ids = /* @__PURE__ */ new Set();
+  /**
+   * Cancels a single tracked timer.
+   *
+   * No-ops if the id is unknown (already cleared, fired, or never owned by this
+   * registry), so callers can clear defensively without guarding.
+   */
+  clear(id) {
+    if (this.ids.delete(id)) {
+      this.cancel(id);
+    }
+  }
+  /**
+   * Cancels every tracked timer. Call this from a controller's `disconnect()`
+   * to guarantee no timer outlives the element.
+   */
+  clearAll() {
+    for (const id of this.ids) {
+      this.cancel(id);
+    }
+    this.ids.clear();
+  }
+  /** Number of timers currently tracked (pending). */
+  get size() {
+    return this.ids.size;
+  }
+};
+var SafeTimeout = class extends TimerRegistry {
+  /**
+   * Schedules `callback` after `delay` ms and returns the timer id.
+   *
+   * The id is removed from the registry automatically when the timeout fires,
+   * so {@link TimerRegistry.size | size} reflects only still-pending timers.
+   */
+  set(callback, delay) {
+    const id = this.schedule(() => {
+      this.ids.delete(id);
+      callback();
+    }, delay);
+    this.ids.add(id);
+    return id;
+  }
+  schedule(callback, delay) {
+    return window.setTimeout(callback, delay);
+  }
+  cancel(id) {
+    window.clearTimeout(id);
+  }
+};
+
+// src/controllers/skeleton_controller.ts
+var SkeletonController = class extends Controller {
+  static targets = ["placeholder", "content"];
+  static values = {
+    minDuration: { type: Number, default: 0 }
+  };
+  static actions = ["ready", "reset"];
+  static events = ["ready"];
+  #timers = new SafeTimeout();
+  /** Pending min-duration reveal timer id, or `null` when none is scheduled. */
+  #revealTimerId = null;
+  /** Epoch ms when the loading state began, used to enforce `minDuration`. */
+  #loadingSince = 0;
+  connect() {
+    if (this.#state !== "ready") {
+      this.#enterLoading();
+    }
+  }
+  disconnect() {
+    this.#timers.clearAll();
+    this.#revealTimerId = null;
+  }
+  /** Swaps to the real content. Honors `minDuration` to prevent a flash. */
+  ready() {
+    if (this.#state === "ready" || this.#revealTimerId !== null) return;
+    const remaining = this.minDurationValue - (Date.now() - this.#loadingSince);
+    if (remaining > 0) {
+      this.#revealTimerId = this.#timers.set(() => {
+        this.#revealTimerId = null;
+        this.#reveal();
+      }, remaining);
+    } else {
+      this.#reveal();
+    }
+  }
+  /** Returns to the loading state (e.g. a Turbo Stream re-fetch). */
+  reset() {
+    if (this.#revealTimerId !== null) {
+      this.#timers.clear(this.#revealTimerId);
+      this.#revealTimerId = null;
+    }
+    this.#enterLoading();
+  }
+  /** Shows the placeholder, hides content, and marks the region busy. */
+  #enterLoading() {
+    this.#loadingSince = Date.now();
+    if (this.hasPlaceholderTarget) this.placeholderTarget.hidden = false;
+    if (this.hasContentTarget) this.contentTarget.hidden = true;
+    this.element.setAttribute("aria-busy", "true");
+    this.element.setAttribute("data-state", "loading");
+  }
+  /** Hides the placeholder, shows content, and clears the busy state. */
+  #reveal() {
+    if (this.hasPlaceholderTarget) this.placeholderTarget.hidden = true;
+    if (this.hasContentTarget) this.contentTarget.hidden = false;
+    this.element.setAttribute("aria-busy", "false");
+    this.element.setAttribute("data-state", "ready");
+    this.dispatch("ready", { detail: {} });
+  }
+  /** Current lifecycle phase as reflected on `data-state`. */
+  get #state() {
+    return this.element.getAttribute("data-state") ?? "loading";
+  }
+};
+
+export { SkeletonController };
+//# sourceMappingURL=skeleton_controller.js.map
+//# sourceMappingURL=skeleton_controller.js.map

package/dist/controllers/skeleton_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/safe_timeout.ts","../../src/controllers/skeleton_controller.ts"],"names":[],"mappings":"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","file":"skeleton_controller.js","sourcesContent":["/**\n * Self-cleaning timer registries shared by Stimeo controllers.\n *\n * Stimulus controllers frequently schedule `setTimeout` / `setInterval` work\n * (auto-dismiss, debouncing, polling). When the element leaves the DOM — a\n * Turbo Drive navigation, a Turbo Stream replacement, or any `disconnect()` —\n * orphaned timers keep firing against a detached controller, leaking memory and\n * mutating stale state. {@link SafeTimeout} and {@link SafeInterval} track every\n * timer they create so a single {@link TimerRegistry.clearAll | clearAll()} call\n * in `disconnect()` tears them all down.\n *\n * These are intentionally low-level primitives: they own *registration and\n * cleanup only*. Higher-level policy (pause/resume, remaining-time accounting)\n * stays in the individual controllers so per-widget semantics are not flattened\n * into a lowest-common-denominator helper.\n */\n\n/**\n * Shared registry bookkeeping for the timeout/interval variants.\n *\n * Subclasses provide the scheduling primitive ({@link schedule}) and its matching\n * canceller ({@link cancel}); this base owns the set of live ids plus the\n * per-id and bulk teardown shared by both.\n */\nabstract class TimerRegistry {\n  /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */\n  protected readonly ids = new Set<number>();\n\n  /** Schedules the underlying platform timer and returns its id. */\n  protected abstract schedule(callback: () => void, delay: number): number;\n\n  /** Cancels the underlying platform timer for `id`. */\n  protected abstract cancel(id: number): void;\n\n  /**\n   * Cancels a single tracked timer.\n   *\n   * No-ops if the id is unknown (already cleared, fired, or never owned by this\n   * registry), so callers can clear defensively without guarding.\n   */\n  clear(id: number): void {\n    if (this.ids.delete(id)) {\n      this.cancel(id);\n    }\n  }\n\n  /**\n   * Cancels every tracked timer. Call this from a controller's `disconnect()`\n   * to guarantee no timer outlives the element.\n   */\n  clearAll(): void {\n    for (const id of this.ids) {\n      this.cancel(id);\n    }\n    this.ids.clear();\n  }\n\n  /** Number of timers currently tracked (pending). */\n  get size(): number {\n    return this.ids.size;\n  }\n}\n\n/**\n * `setTimeout` wrapper that auto-forgets each timer once it fires and supports\n * bulk teardown on disconnect.\n *\n * @example\n * ```ts\n * #timers = new SafeTimeout();\n *\n * connect() {\n *   this.#timers.set(() => this.dismiss(), 5000);\n * }\n *\n * disconnect() {\n *   this.#timers.clearAll();\n * }\n * ```\n */\nexport class SafeTimeout extends TimerRegistry {\n  /**\n   * Schedules `callback` after `delay` ms and returns the timer id.\n   *\n   * The id is removed from the registry automatically when the timeout fires,\n   * so {@link TimerRegistry.size | size} reflects only still-pending timers.\n   */\n  set(callback: () => void, delay: number): number {\n    const id = this.schedule(() => {\n      this.ids.delete(id);\n      callback();\n    }, delay);\n    this.ids.add(id);\n    return id;\n  }\n\n  protected schedule(callback: () => void, delay: number): number {\n    return window.setTimeout(callback, delay);\n  }\n\n  protected cancel(id: number): void {\n    window.clearTimeout(id);\n  }\n}\n\n/**\n * `setInterval` wrapper that tracks every interval for bulk teardown on\n * disconnect. Unlike {@link SafeTimeout}, intervals are retained until they are\n * explicitly cleared because they fire repeatedly.\n *\n * @example\n * ```ts\n * #intervals = new SafeInterval();\n *\n * connect() {\n *   this.#intervals.set(() => this.tick(), 1000);\n * }\n *\n * disconnect() {\n *   this.#intervals.clearAll();\n * }\n * ```\n */\nexport class SafeInterval extends TimerRegistry {\n  /** Schedules a repeating `callback` every `delay` ms and returns the timer id. */\n  set(callback: () => void, delay: number): number {\n    const id = this.schedule(callback, delay);\n    this.ids.add(id);\n    return id;\n  }\n\n  protected schedule(callback: () => void, delay: number): number {\n    return window.setInterval(callback, delay);\n  }\n\n  protected cancel(id: number): void {\n    window.clearInterval(id);\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { SafeTimeout } from \"../utils/safe_timeout\";\n\n/**\n * Headless skeleton/placeholder manager. No dedicated APG pattern; it follows\n * the `aria-busy` + show/hide practice.\n *\n * Markup contract (identifier: `stimeo--skeleton`):\n *   <div data-controller=\"stimeo--skeleton\" aria-busy=\"true\"\n *        data-stimeo--skeleton-min-duration-value=\"300\"\n *        data-action=\"content:ready->stimeo--skeleton#ready\">\n *     <div aria-hidden=\"true\" data-stimeo--skeleton-target=\"placeholder\"></div>\n *     <div hidden data-stimeo--skeleton-target=\"content\"></div>\n *   </div>\n *\n * Starts in the loading state (placeholder shown, real content hidden, region\n * `aria-busy=\"true\"`); `ready` swaps to the content and clears busy. The\n * placeholder is `aria-hidden` (decorative) so assistive tech never reads the\n * skeleton. `minDuration` keeps the placeholder up long enough to avoid a flash\n * when content arrives almost immediately.\n *\n * @remarks\n * Behavior only — skeleton shapes/animation are the consumer's. The\n * min-duration timer is owned by {@link SafeTimeout} and torn down on\n * `disconnect()` (Turbo navigation included).\n */\nexport class SkeletonController extends Controller<HTMLElement> {\n  static override targets = [\"placeholder\", \"content\"];\n  static override values = {\n    minDuration: { type: Number, default: 0 },\n  };\n  static actions = [\"ready\", \"reset\"] as const;\n  static events = [\"ready\"] as const;\n\n  declare readonly placeholderTarget: HTMLElement;\n  declare readonly contentTarget: HTMLElement;\n  declare readonly hasPlaceholderTarget: boolean;\n  declare readonly hasContentTarget: boolean;\n\n  declare minDurationValue: number;\n\n  readonly #timers = new SafeTimeout();\n\n  /** Pending min-duration reveal timer id, or `null` when none is scheduled. */\n  #revealTimerId: number | null = null;\n  /** Epoch ms when the loading state began, used to enforce `minDuration`. */\n  #loadingSince = 0;\n\n  override connect(): void {\n    if (this.#state !== \"ready\") {\n      this.#enterLoading();\n    }\n  }\n\n  override disconnect(): void {\n    this.#timers.clearAll();\n    this.#revealTimerId = null;\n  }\n\n  /** Swaps to the real content. Honors `minDuration` to prevent a flash. */\n  ready(): void {\n    if (this.#state === \"ready\" || this.#revealTimerId !== null) return;\n    const remaining = this.minDurationValue - (Date.now() - this.#loadingSince);\n    if (remaining > 0) {\n      this.#revealTimerId = this.#timers.set(() => {\n        this.#revealTimerId = null;\n        this.#reveal();\n      }, remaining);\n    } else {\n      this.#reveal();\n    }\n  }\n\n  /** Returns to the loading state (e.g. a Turbo Stream re-fetch). */\n  reset(): void {\n    if (this.#revealTimerId !== null) {\n      this.#timers.clear(this.#revealTimerId);\n      this.#revealTimerId = null;\n    }\n    this.#enterLoading();\n  }\n\n  /** Shows the placeholder, hides content, and marks the region busy. */\n  #enterLoading(): void {\n    this.#loadingSince = Date.now();\n    if (this.hasPlaceholderTarget) this.placeholderTarget.hidden = false;\n    if (this.hasContentTarget) this.contentTarget.hidden = true;\n    this.element.setAttribute(\"aria-busy\", \"true\");\n    this.element.setAttribute(\"data-state\", \"loading\");\n  }\n\n  /** Hides the placeholder, shows content, and clears the busy state. */\n  #reveal(): void {\n    if (this.hasPlaceholderTarget) this.placeholderTarget.hidden = true;\n    if (this.hasContentTarget) this.contentTarget.hidden = false;\n    this.element.setAttribute(\"aria-busy\", \"false\");\n    this.element.setAttribute(\"data-state\", \"ready\");\n    this.dispatch(\"ready\", { detail: {} });\n  }\n\n  /** Current lifecycle phase as reflected on `data-state`. */\n  get #state(): string {\n    return this.element.getAttribute(\"data-state\") ?? \"loading\";\n  }\n}\n"]}

package/dist/controllers/slider_controller.d.ts

@@ -0,0 +1,76 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless, accessible slider (single-thumb range) behavior.
+ *
+ * Markup contract (identifier: `stimeo--slider`):
+ *   <div data-controller="stimeo--slider"
+ *        data-stimeo--slider-min-value="0"
+ *        data-stimeo--slider-max-value="100"
+ *        data-stimeo--slider-step-value="1"
+ *        data-stimeo--slider-value-value="40">
+ *     <div data-stimeo--slider-target="track"
+ *          data-action="pointerdown->stimeo--slider#onPointerDown">
+ *       <div data-stimeo--slider-target="thumb" role="slider" tabindex="0"
+ *            aria-valuemin="0" aria-valuemax="100" aria-valuenow="40"
+ *            data-action="keydown->stimeo--slider#onKeydown"></div>
+ *     </div>
+ *   </div>
+ *
+ * Implements the WAI-ARIA APG **Slider** pattern. The current value is exposed
+ * to assistive tech via `aria-valuenow`/`aria-valuemin`/`aria-valuemax` on the
+ * thumb, and to the consumer's CSS via the `--stimeo--slider-fraction` custom
+ * property (a number in `[0, 1]`) set on the controller element — the library
+ * positions nothing itself.
+ *
+ * @remarks
+ * Behavior only. The consumer owns all layout (e.g. positioning the thumb from
+ * the fraction). Only the horizontal orientation is handled in this MVP.
+ *
+ * Behavior provided:
+ * - `ArrowRight`/`ArrowUp` increase and `ArrowLeft`/`ArrowDown` decrease by one
+ *   step; `Home`/`End` jump to the min/max; `PageUp`/`PageDown` move by ten steps.
+ * - Pointer press/drag on the track sets the value from the pointer position.
+ */
+declare class SliderController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        min: {
+            type: NumberConstructor;
+            default: number;
+        };
+        max: {
+            type: NumberConstructor;
+            default: number;
+        };
+        step: {
+            type: NumberConstructor;
+            default: number;
+        };
+        value: {
+            type: NumberConstructor;
+            default: number;
+        };
+    };
+    static actions: readonly ["onKeydown", "onPointerDown"];
+    static events: readonly ["change"];
+    readonly trackTarget: HTMLElement;
+    readonly thumbTarget: HTMLElement;
+    readonly hasTrackTarget: boolean;
+    readonly hasThumbTarget: boolean;
+    minValue: number;
+    maxValue: number;
+    stepValue: number;
+    valueValue: number;
+    /** Clamps the initial value and renders the starting position. */
+    connect(): void;
+    /** Cancels any active pointer drag so document listeners never leak. */
+    disconnect(): void;
+    /** Handles keyboard stepping per the APG slider model. */
+    onKeydown(event: KeyboardEvent): void;
+    /** Begins a pointer drag: sets the value and tracks subsequent movement. */
+    onPointerDown(event: PointerEvent): void;
+}
+
+export { SliderController };

package/dist/controllers/slider_controller.js

@@ -0,0 +1,109 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/slider_controller.ts
+var FRACTION_PROPERTY = "--stimeo--slider-fraction";
+var SliderController = class extends Controller {
+  static targets = ["track", "thumb"];
+  static values = {
+    min: { type: Number, default: 0 },
+    max: { type: Number, default: 100 },
+    step: { type: Number, default: 1 },
+    value: { type: Number, default: 0 }
+  };
+  static actions = ["onKeydown", "onPointerDown"];
+  static events = ["change"];
+  /** Aborts in-progress pointer-drag listeners when the drag ends or on teardown. */
+  #dragAbort = null;
+  /** Clamps the initial value and renders the starting position. */
+  connect() {
+    this.#setValue(this.valueValue, { silent: true });
+  }
+  /** Cancels any active pointer drag so document listeners never leak. */
+  disconnect() {
+    this.#dragAbort?.abort();
+    this.#dragAbort = null;
+  }
+  /** Handles keyboard stepping per the APG slider model. */
+  onKeydown(event) {
+    const big = this.stepValue * 10;
+    let next = null;
+    switch (event.key) {
+      case "ArrowRight":
+      case "ArrowUp":
+        next = this.valueValue + this.stepValue;
+        break;
+      case "ArrowLeft":
+      case "ArrowDown":
+        next = this.valueValue - this.stepValue;
+        break;
+      case "PageUp":
+        next = this.valueValue + big;
+        break;
+      case "PageDown":
+        next = this.valueValue - big;
+        break;
+      case "Home":
+        next = this.minValue;
+        break;
+      case "End":
+        next = this.maxValue;
+        break;
+      default:
+        return;
+    }
+    event.preventDefault();
+    this.#setValue(next);
+  }
+  /** Begins a pointer drag: sets the value and tracks subsequent movement. */
+  onPointerDown(event) {
+    if (!this.hasTrackTarget) return;
+    event.preventDefault();
+    this.#updateFromClientX(event.clientX);
+    if (this.hasThumbTarget) this.thumbTarget.focus();
+    this.#dragAbort?.abort();
+    const abort = new AbortController();
+    this.#dragAbort = abort;
+    const onMove = (move) => this.#updateFromClientX(move.clientX);
+    const onUp = () => {
+      abort.abort();
+      this.#dragAbort = null;
+    };
+    document.addEventListener("pointermove", onMove, { signal: abort.signal });
+    document.addEventListener("pointerup", onUp, { signal: abort.signal });
+    document.addEventListener("pointercancel", onUp, { signal: abort.signal });
+  }
+  /** Maps a pointer X coordinate to a value using the track's geometry. */
+  #updateFromClientX(clientX) {
+    const rect = this.trackTarget.getBoundingClientRect();
+    if (rect.width === 0) return;
+    const fraction = (clientX - rect.left) / rect.width;
+    this.#setValue(this.minValue + fraction * (this.maxValue - this.minValue));
+  }
+  /**
+   * Clamps `raw` to `[min, max]`, snaps it to the nearest step, stores it, and
+   * reflects the new state on the thumb's ARIA attributes and the fraction
+   * custom property. Dispatches `change` (detail `{ value }`) on a real value
+   * change — symmetric with `range-slider` — unless `silent` (the initial
+   * connect render, which is not a user edit).
+   */
+  #setValue(raw, { silent = false } = {}) {
+    const clamped = Math.min(this.maxValue, Math.max(this.minValue, raw));
+    const stepped = this.stepValue > 0 ? Math.round((clamped - this.minValue) / this.stepValue) * this.stepValue + this.minValue : clamped;
+    const value = Math.min(this.maxValue, Math.max(this.minValue, stepped));
+    const changed = value !== this.valueValue;
+    this.valueValue = value;
+    if (this.hasThumbTarget) {
+      this.thumbTarget.setAttribute("aria-valuemin", String(this.minValue));
+      this.thumbTarget.setAttribute("aria-valuemax", String(this.maxValue));
+      this.thumbTarget.setAttribute("aria-valuenow", String(value));
+    }
+    const span = this.maxValue - this.minValue;
+    const fraction = span > 0 ? (value - this.minValue) / span : 0;
+    this.element.style.setProperty(FRACTION_PROPERTY, String(fraction));
+    if (changed && !silent) this.dispatch("change", { detail: { value } });
+  }
+};
+
+export { SliderController };
+//# sourceMappingURL=slider_controller.js.map
+//# sourceMappingURL=slider_controller.js.map

package/dist/controllers/slider_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/controllers/slider_controller.ts"],"names":[],"mappings":"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","file":"slider_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/** Name of the CSS custom property exposing the thumb position (0..1). */\nconst FRACTION_PROPERTY = \"--stimeo--slider-fraction\";\n\n/**\n * Headless, accessible slider (single-thumb range) behavior.\n *\n * Markup contract (identifier: `stimeo--slider`):\n *   <div data-controller=\"stimeo--slider\"\n *        data-stimeo--slider-min-value=\"0\"\n *        data-stimeo--slider-max-value=\"100\"\n *        data-stimeo--slider-step-value=\"1\"\n *        data-stimeo--slider-value-value=\"40\">\n *     <div data-stimeo--slider-target=\"track\"\n *          data-action=\"pointerdown->stimeo--slider#onPointerDown\">\n *       <div data-stimeo--slider-target=\"thumb\" role=\"slider\" tabindex=\"0\"\n *            aria-valuemin=\"0\" aria-valuemax=\"100\" aria-valuenow=\"40\"\n *            data-action=\"keydown->stimeo--slider#onKeydown\"></div>\n *     </div>\n *   </div>\n *\n * Implements the WAI-ARIA APG **Slider** pattern. The current value is exposed\n * to assistive tech via `aria-valuenow`/`aria-valuemin`/`aria-valuemax` on the\n * thumb, and to the consumer's CSS via the `--stimeo--slider-fraction` custom\n * property (a number in `[0, 1]`) set on the controller element — the library\n * positions nothing itself.\n *\n * @remarks\n * Behavior only. The consumer owns all layout (e.g. positioning the thumb from\n * the fraction). Only the horizontal orientation is handled in this MVP.\n *\n * Behavior provided:\n * - `ArrowRight`/`ArrowUp` increase and `ArrowLeft`/`ArrowDown` decrease by one\n *   step; `Home`/`End` jump to the min/max; `PageUp`/`PageDown` move by ten steps.\n * - Pointer press/drag on the track sets the value from the pointer position.\n */\nexport class SliderController extends Controller<HTMLElement> {\n  static override targets = [\"track\", \"thumb\"];\n  static override values = {\n    min: { type: Number, default: 0 },\n    max: { type: Number, default: 100 },\n    step: { type: Number, default: 1 },\n    value: { type: Number, default: 0 },\n  };\n  static actions = [\"onKeydown\", \"onPointerDown\"] as const;\n  static events = [\"change\"] as const;\n\n  declare readonly trackTarget: HTMLElement;\n  declare readonly thumbTarget: HTMLElement;\n  declare readonly hasTrackTarget: boolean;\n  declare readonly hasThumbTarget: boolean;\n  declare minValue: number;\n  declare maxValue: number;\n  declare stepValue: number;\n  declare valueValue: number;\n\n  /** Aborts in-progress pointer-drag listeners when the drag ends or on teardown. */\n  #dragAbort: AbortController | null = null;\n\n  /** Clamps the initial value and renders the starting position. */\n  override connect(): void {\n    this.#setValue(this.valueValue, { silent: true });\n  }\n\n  /** Cancels any active pointer drag so document listeners never leak. */\n  override disconnect(): void {\n    this.#dragAbort?.abort();\n    this.#dragAbort = null;\n  }\n\n  /** Handles keyboard stepping per the APG slider model. */\n  onKeydown(event: KeyboardEvent): void {\n    const big = this.stepValue * 10;\n    let next: number | null = null;\n    switch (event.key) {\n      case \"ArrowRight\":\n      case \"ArrowUp\":\n        next = this.valueValue + this.stepValue;\n        break;\n      case \"ArrowLeft\":\n      case \"ArrowDown\":\n        next = this.valueValue - this.stepValue;\n        break;\n      case \"PageUp\":\n        next = this.valueValue + big;\n        break;\n      case \"PageDown\":\n        next = this.valueValue - big;\n        break;\n      case \"Home\":\n        next = this.minValue;\n        break;\n      case \"End\":\n        next = this.maxValue;\n        break;\n      default:\n        return;\n    }\n    event.preventDefault();\n    this.#setValue(next);\n  }\n\n  /** Begins a pointer drag: sets the value and tracks subsequent movement. */\n  onPointerDown(event: PointerEvent): void {\n    if (!this.hasTrackTarget) return;\n    event.preventDefault();\n    this.#updateFromClientX(event.clientX);\n    if (this.hasThumbTarget) this.thumbTarget.focus();\n\n    this.#dragAbort?.abort();\n    const abort = new AbortController();\n    this.#dragAbort = abort;\n    const onMove = (move: PointerEvent): void => this.#updateFromClientX(move.clientX);\n    const onUp = (): void => {\n      abort.abort();\n      this.#dragAbort = null;\n    };\n    document.addEventListener(\"pointermove\", onMove, { signal: abort.signal });\n    document.addEventListener(\"pointerup\", onUp, { signal: abort.signal });\n    // pointercancel fires when the gesture is interrupted (OS gesture, scroll\n    // takeover, device switch); clean up the same way so no listener leaks.\n    document.addEventListener(\"pointercancel\", onUp, { signal: abort.signal });\n  }\n\n  /** Maps a pointer X coordinate to a value using the track's geometry. */\n  #updateFromClientX(clientX: number): void {\n    const rect = this.trackTarget.getBoundingClientRect();\n    if (rect.width === 0) return;\n    const fraction = (clientX - rect.left) / rect.width;\n    this.#setValue(this.minValue + fraction * (this.maxValue - this.minValue));\n  }\n\n  /**\n   * Clamps `raw` to `[min, max]`, snaps it to the nearest step, stores it, and\n   * reflects the new state on the thumb's ARIA attributes and the fraction\n   * custom property. Dispatches `change` (detail `{ value }`) on a real value\n   * change — symmetric with `range-slider` — unless `silent` (the initial\n   * connect render, which is not a user edit).\n   */\n  #setValue(raw: number, { silent = false }: { silent?: boolean } = {}): void {\n    const clamped = Math.min(this.maxValue, Math.max(this.minValue, raw));\n    const stepped =\n      this.stepValue > 0\n        ? Math.round((clamped - this.minValue) / this.stepValue) * this.stepValue + this.minValue\n        : clamped;\n    const value = Math.min(this.maxValue, Math.max(this.minValue, stepped));\n    const changed = value !== this.valueValue;\n    this.valueValue = value;\n\n    if (this.hasThumbTarget) {\n      this.thumbTarget.setAttribute(\"aria-valuemin\", String(this.minValue));\n      this.thumbTarget.setAttribute(\"aria-valuemax\", String(this.maxValue));\n      this.thumbTarget.setAttribute(\"aria-valuenow\", String(value));\n    }\n\n    const span = this.maxValue - this.minValue;\n    const fraction = span > 0 ? (value - this.minValue) / span : 0;\n    this.element.style.setProperty(FRACTION_PROPERTY, String(fraction));\n\n    if (changed && !silent) this.dispatch(\"change\", { detail: { value } });\n  }\n}\n"]}