stimeo-ui 0.1.0-alpha.1

package/dist/controllers/spinner_controller.d.ts

@@ -0,0 +1,62 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless loading-indicator behavior built on the live-region + `aria-busy`
+ * practice (no dedicated APG pattern).
+ *
+ * Markup contract (identifier: `stimeo--spinner`):
+ *   <div data-controller="stimeo--spinner"
+ *        data-stimeo--spinner-delay-value="150"
+ *        data-stimeo--spinner-min-duration-value="500"
+ *        data-action="loading:start->stimeo--spinner#start
+ *                     loading:stop->stimeo--spinner#stop">
+ *     <div role="status" aria-live="polite" hidden
+ *          data-stimeo--spinner-target="indicator">
+ *       <span data-stimeo--spinner-target="message">Loading…</span>
+ *     </div>
+ *     <div aria-busy="false" data-stimeo--spinner-target="region"></div>
+ *   </div>
+ *
+ * The indicator is a `role="status"` live region carrying *text* (never an icon
+ * alone) so screen readers announce loading; the controlled `region` mirrors the
+ * busy state via `aria-busy`. Two timers tame flicker: `delay` suppresses the
+ * spinner for fast operations, and `minDuration` keeps it visible long enough to
+ * be perceived once shown.
+ *
+ * @remarks
+ * Behavior only — the visual spinner is the consumer's, alongside the text and
+ * `aria-hidden="true"`. Both timers are owned by {@link SafeTimeout} and torn
+ * down on `disconnect()` (Turbo navigation included).
+ */
+declare class SpinnerController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        delay: {
+            type: NumberConstructor;
+            default: number;
+        };
+        minDuration: {
+            type: NumberConstructor;
+            default: number;
+        };
+    };
+    static actions: readonly ["start", "stop"];
+    static events: readonly ["hide", "show"];
+    readonly indicatorTarget: HTMLElement;
+    readonly regionTarget: HTMLElement;
+    readonly messageTarget: HTMLElement;
+    readonly hasIndicatorTarget: boolean;
+    readonly hasRegionTarget: boolean;
+    readonly hasMessageTarget: boolean;
+    delayValue: number;
+    minDurationValue: number;
+    connect(): void;
+    disconnect(): void;
+    /** Begins loading. Honors `delay` before the spinner actually appears. */
+    start(): void;
+    /** Ends loading. Honors `minDuration` so a shown spinner does not flicker. */
+    stop(): void;
+}
+
+export { SpinnerController };

package/dist/controllers/spinner_controller.js

@@ -0,0 +1,164 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/spinner_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/spinner_controller.ts
+var SpinnerController = class extends Controller {
+  static targets = ["indicator", "region", "message"];
+  static values = {
+    delay: { type: Number, default: 0 },
+    minDuration: { type: Number, default: 0 }
+  };
+  static actions = ["start", "stop"];
+  static events = ["hide", "show"];
+  #timers = new SafeTimeout();
+  /** Pending show-delay timer id, or `null` when no start is awaiting its delay. */
+  #delayTimerId = null;
+  /** Pending min-duration hide timer id, or `null` when none is scheduled. */
+  #hideTimerId = null;
+  /** Epoch ms when the spinner became visible, used to enforce `minDuration`. */
+  #shownAt = 0;
+  connect() {
+    if (!this.element.hasAttribute("data-state")) {
+      this.element.setAttribute("data-state", "idle");
+    }
+  }
+  disconnect() {
+    this.#timers.clearAll();
+    this.#delayTimerId = null;
+    this.#hideTimerId = null;
+  }
+  /** Begins loading. Honors `delay` before the spinner actually appears. */
+  start() {
+    if (this.#state === "loading") {
+      this.#setBusy(true);
+      this.#cancelHide();
+      return;
+    }
+    if (this.#state !== "idle") return;
+    this.#setBusy(true);
+    this.#cancelHide();
+    if (this.delayValue > 0) {
+      this.element.setAttribute("data-state", "pending");
+      this.#delayTimerId = this.#timers.set(() => {
+        this.#delayTimerId = null;
+        this.#show();
+      }, this.delayValue);
+    } else {
+      this.#show();
+    }
+  }
+  /** Ends loading. Honors `minDuration` so a shown spinner does not flicker. */
+  stop() {
+    const state = this.#state;
+    if (state === "pending") {
+      this.#cancelDelay();
+      this.#setBusy(false);
+      this.element.setAttribute("data-state", "idle");
+      return;
+    }
+    if (state !== "loading") return;
+    this.#setBusy(false);
+    const remaining = this.minDurationValue - (Date.now() - this.#shownAt);
+    if (remaining > 0) {
+      this.#hideTimerId = this.#timers.set(() => {
+        this.#hideTimerId = null;
+        this.#hide();
+      }, remaining);
+    } else {
+      this.#hide();
+    }
+  }
+  /** Reveals the indicator, marks the moment shown, and announces via the live region. */
+  #show() {
+    this.#shownAt = Date.now();
+    if (this.hasIndicatorTarget) this.indicatorTarget.hidden = false;
+    this.element.setAttribute("data-state", "loading");
+    this.dispatch("show", { detail: {} });
+  }
+  /** Hides the indicator and returns to the idle state. */
+  #hide() {
+    if (this.hasIndicatorTarget) this.indicatorTarget.hidden = true;
+    this.element.setAttribute("data-state", "idle");
+    this.dispatch("hide", { detail: {} });
+  }
+  /** Reflects busy state onto the controlled region (if present). */
+  #setBusy(busy) {
+    if (this.hasRegionTarget) {
+      this.regionTarget.setAttribute("aria-busy", String(busy));
+    }
+  }
+  #cancelDelay() {
+    if (this.#delayTimerId !== null) {
+      this.#timers.clear(this.#delayTimerId);
+      this.#delayTimerId = null;
+    }
+  }
+  #cancelHide() {
+    if (this.#hideTimerId !== null) {
+      this.#timers.clear(this.#hideTimerId);
+      this.#hideTimerId = null;
+    }
+  }
+  /** Current lifecycle phase as reflected on `data-state`. */
+  get #state() {
+    return this.element.getAttribute("data-state") ?? "idle";
+  }
+};
+
+export { SpinnerController };
+//# sourceMappingURL=spinner_controller.js.map
+//# sourceMappingURL=spinner_controller.js.map

package/dist/controllers/spinner_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/safe_timeout.ts","../../src/controllers/spinner_controller.ts"],"names":[],"mappings":"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","file":"spinner_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 loading-indicator behavior built on the live-region + `aria-busy`\n * practice (no dedicated APG pattern).\n *\n * Markup contract (identifier: `stimeo--spinner`):\n *   <div data-controller=\"stimeo--spinner\"\n *        data-stimeo--spinner-delay-value=\"150\"\n *        data-stimeo--spinner-min-duration-value=\"500\"\n *        data-action=\"loading:start->stimeo--spinner#start\n *                     loading:stop->stimeo--spinner#stop\">\n *     <div role=\"status\" aria-live=\"polite\" hidden\n *          data-stimeo--spinner-target=\"indicator\">\n *       <span data-stimeo--spinner-target=\"message\">Loading…</span>\n *     </div>\n *     <div aria-busy=\"false\" data-stimeo--spinner-target=\"region\"></div>\n *   </div>\n *\n * The indicator is a `role=\"status\"` live region carrying *text* (never an icon\n * alone) so screen readers announce loading; the controlled `region` mirrors the\n * busy state via `aria-busy`. Two timers tame flicker: `delay` suppresses the\n * spinner for fast operations, and `minDuration` keeps it visible long enough to\n * be perceived once shown.\n *\n * @remarks\n * Behavior only — the visual spinner is the consumer's, alongside the text and\n * `aria-hidden=\"true\"`. Both timers are owned by {@link SafeTimeout} and torn\n * down on `disconnect()` (Turbo navigation included).\n */\nexport class SpinnerController extends Controller<HTMLElement> {\n  static override targets = [\"indicator\", \"region\", \"message\"];\n  static override values = {\n    delay: { type: Number, default: 0 },\n    minDuration: { type: Number, default: 0 },\n  };\n  static actions = [\"start\", \"stop\"] as const;\n  static events = [\"hide\", \"show\"] as const;\n\n  declare readonly indicatorTarget: HTMLElement;\n  declare readonly regionTarget: HTMLElement;\n  declare readonly messageTarget: HTMLElement;\n  declare readonly hasIndicatorTarget: boolean;\n  declare readonly hasRegionTarget: boolean;\n  declare readonly hasMessageTarget: boolean;\n\n  declare delayValue: number;\n  declare minDurationValue: number;\n\n  readonly #timers = new SafeTimeout();\n\n  /** Pending show-delay timer id, or `null` when no start is awaiting its delay. */\n  #delayTimerId: number | null = null;\n  /** Pending min-duration hide timer id, or `null` when none is scheduled. */\n  #hideTimerId: number | null = null;\n  /** Epoch ms when the spinner became visible, used to enforce `minDuration`. */\n  #shownAt = 0;\n\n  override connect(): void {\n    if (!this.element.hasAttribute(\"data-state\")) {\n      this.element.setAttribute(\"data-state\", \"idle\");\n    }\n  }\n\n  override disconnect(): void {\n    this.#timers.clearAll();\n    this.#delayTimerId = null;\n    this.#hideTimerId = null;\n  }\n\n  /** Begins loading. Honors `delay` before the spinner actually appears. */\n  start(): void {\n    if (this.#state === \"loading\") {\n      // Already shown (possibly waiting out `minDuration` after a stop): a quick\n      // stop→start within that window must keep the spinner visible. Restore the\n      // busy state and cancel the pending hide instead of returning a no-op, which\n      // would let the stale hide fire and flicker the spinner away mid-load.\n      this.#setBusy(true);\n      this.#cancelHide();\n      return;\n    }\n    if (this.#state !== \"idle\") return;\n    this.#setBusy(true);\n    // A pending hide from a previous cycle is now stale.\n    this.#cancelHide();\n    if (this.delayValue > 0) {\n      this.element.setAttribute(\"data-state\", \"pending\");\n      this.#delayTimerId = this.#timers.set(() => {\n        this.#delayTimerId = null;\n        this.#show();\n      }, this.delayValue);\n    } else {\n      this.#show();\n    }\n  }\n\n  /** Ends loading. Honors `minDuration` so a shown spinner does not flicker. */\n  stop(): void {\n    const state = this.#state;\n    if (state === \"pending\") {\n      // The delay never elapsed — the spinner never appeared, so just cancel.\n      this.#cancelDelay();\n      this.#setBusy(false);\n      this.element.setAttribute(\"data-state\", \"idle\");\n      return;\n    }\n    if (state !== \"loading\") return;\n\n    this.#setBusy(false);\n    const remaining = this.minDurationValue - (Date.now() - this.#shownAt);\n    if (remaining > 0) {\n      this.#hideTimerId = this.#timers.set(() => {\n        this.#hideTimerId = null;\n        this.#hide();\n      }, remaining);\n    } else {\n      this.#hide();\n    }\n  }\n\n  /** Reveals the indicator, marks the moment shown, and announces via the live region. */\n  #show(): void {\n    this.#shownAt = Date.now();\n    if (this.hasIndicatorTarget) this.indicatorTarget.hidden = false;\n    this.element.setAttribute(\"data-state\", \"loading\");\n    this.dispatch(\"show\", { detail: {} });\n  }\n\n  /** Hides the indicator and returns to the idle state. */\n  #hide(): void {\n    if (this.hasIndicatorTarget) this.indicatorTarget.hidden = true;\n    this.element.setAttribute(\"data-state\", \"idle\");\n    this.dispatch(\"hide\", { detail: {} });\n  }\n\n  /** Reflects busy state onto the controlled region (if present). */\n  #setBusy(busy: boolean): void {\n    if (this.hasRegionTarget) {\n      this.regionTarget.setAttribute(\"aria-busy\", String(busy));\n    }\n  }\n\n  #cancelDelay(): void {\n    if (this.#delayTimerId !== null) {\n      this.#timers.clear(this.#delayTimerId);\n      this.#delayTimerId = null;\n    }\n  }\n\n  #cancelHide(): void {\n    if (this.#hideTimerId !== null) {\n      this.#timers.clear(this.#hideTimerId);\n      this.#hideTimerId = null;\n    }\n  }\n\n  /** Current lifecycle phase as reflected on `data-state`. */\n  get #state(): string {\n    return this.element.getAttribute(\"data-state\") ?? \"idle\";\n  }\n}\n"]}

package/dist/controllers/step_indicator_controller.d.ts

@@ -0,0 +1,55 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless, accessible **read-only** step-progress indicator.
+ *
+ * Markup contract (identifier: `stimeo--step-indicator`):
+ *   <ol data-controller="stimeo--step-indicator" aria-label="Checkout progress"
+ *       data-stimeo--step-indicator-current-value="1"
+ *       data-action="step:set->stimeo--step-indicator#setCurrent">
+ *     <li data-stimeo--step-indicator-target="step">Cart</li>
+ *     <li data-stimeo--step-indicator-target="step">Shipping</li>
+ *     <li data-stimeo--step-indicator-target="step">Payment</li>
+ *   </ol>
+ *
+ * There is no dedicated APG widget; the current position is expressed with
+ * `aria-current="step"`. This indicator is **read only** — it never moves focus
+ * and the steps are not operable. For an interactive wizard whose steps are
+ * `<button>`s, use {@link StepperController | Stepper}.
+ *
+ * @remarks
+ * Behavior only. Each step `<li>` gets a `data-state` (`complete`/`current`/
+ * `upcoming`) derived from the current index; the consumer draws the circles,
+ * lines, and numbers from those hooks. A `--stimeo-step-indicator-ratio`
+ * (0–1) custom property on the root expresses overall progress for CSS.
+ *
+ * Behavior provided:
+ * - Reflects `current` onto each step's `data-state` and `aria-current`.
+ * - `setCurrent` (bound to an event whose `detail.current` is the 0-based index)
+ *   updates the current step and dispatches `stimeo--step-indicator:change`.
+ */
+declare class StepIndicatorController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        current: {
+            type: NumberConstructor;
+            default: number;
+        };
+    };
+    static actions: readonly ["setCurrent"];
+    static events: readonly ["change"];
+    readonly stepTargets: HTMLElement[];
+    currentValue: number;
+    /** Renders the initial state from the `current` value. */
+    connect(): void;
+    /**
+     * Updates the current step from an external event (`detail.current`, 0-based)
+     * and dispatches `change`. Out-of-range indices are clamped to the step set.
+     */
+    setCurrent(event: CustomEvent<{
+        current?: number;
+    }>): void;
+}
+
+export { StepIndicatorController };

package/dist/controllers/step_indicator_controller.js

@@ -0,0 +1,55 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/step_indicator_controller.ts
+var StepIndicatorController = class extends Controller {
+  static targets = ["step"];
+  static values = {
+    current: { type: Number, default: 0 }
+  };
+  static actions = ["setCurrent"];
+  static events = ["change"];
+  /** Renders the initial state from the `current` value. */
+  connect() {
+    this.#render();
+  }
+  /**
+   * Updates the current step from an external event (`detail.current`, 0-based)
+   * and dispatches `change`. Out-of-range indices are clamped to the step set.
+   */
+  setCurrent(event) {
+    const next = event.detail?.current;
+    if (typeof next !== "number" || !Number.isFinite(next)) return;
+    const clamped = this.#clamp(next);
+    if (clamped === this.currentValue) return;
+    this.currentValue = clamped;
+    this.#render();
+    this.dispatch("change", {
+      detail: { current: clamped, total: this.stepTargets.length }
+    });
+  }
+  /** Applies `data-state`, `aria-current`, and the progress ratio custom property. */
+  #render() {
+    const total = this.stepTargets.length;
+    const current = this.#clamp(this.currentValue);
+    this.stepTargets.forEach((step, index) => {
+      step.dataset.state = index < current ? "complete" : index === current ? "current" : "upcoming";
+      if (index === current) {
+        step.setAttribute("aria-current", "step");
+      } else {
+        step.removeAttribute("aria-current");
+      }
+    });
+    const ratio = total > 1 ? current / (total - 1) : 0;
+    this.element.style.setProperty("--stimeo-step-indicator-ratio", String(ratio));
+  }
+  /** Constrains an index to `[0, total-1]` (or `0` when there are no steps). */
+  #clamp(index) {
+    const last = this.stepTargets.length - 1;
+    if (last < 0) return 0;
+    return Math.min(last, Math.max(0, Math.trunc(index)));
+  }
+};
+
+export { StepIndicatorController };
+//# sourceMappingURL=step_indicator_controller.js.map
+//# sourceMappingURL=step_indicator_controller.js.map

package/dist/controllers/step_indicator_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/controllers/step_indicator_controller.ts"],"names":[],"mappings":";;;AA8BO,IAAM,uBAAA,GAAN,cAAsC,UAAA,CAAwB;AAAA,EACnE,OAAgB,OAAA,GAAU,CAAC,MAAM,CAAA;AAAA,EACjC,OAAgB,MAAA,GAAS;AAAA,IACvB,OAAA,EAAS,EAAE,IAAA,EAAM,MAAA,EAAQ,SAAS,CAAA;AAAE,GACtC;AAAA,EACA,OAAO,OAAA,GAAU,CAAC,YAAY,CAAA;AAAA,EAC9B,OAAO,MAAA,GAAS,CAAC,QAAQ,CAAA;AAAA;AAAA,EAMhB,OAAA,GAAgB;AACvB,IAAA,IAAA,CAAK,OAAA,EAAQ;AAAA,EACf;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,WAAW,KAAA,EAAgD;AACzD,IAAA,MAAM,IAAA,GAAO,MAAM,MAAA,EAAQ,OAAA;AAC3B,IAAA,IAAI,OAAO,IAAA,KAAS,QAAA,IAAY,CAAC,MAAA,CAAO,QAAA,CAAS,IAAI,CAAA,EAAG;AACxD,IAAA,MAAM,OAAA,GAAU,IAAA,CAAK,MAAA,CAAO,IAAI,CAAA;AAChC,IAAA,IAAI,OAAA,KAAY,KAAK,YAAA,EAAc;AACnC,IAAA,IAAA,CAAK,YAAA,GAAe,OAAA;AACpB,IAAA,IAAA,CAAK,OAAA,EAAQ;AACb,IAAA,IAAA,CAAK,SAAS,QAAA,EAAU;AAAA,MACtB,QAAQ,EAAE,OAAA,EAAS,SAAS,KAAA,EAAO,IAAA,CAAK,YAAY,MAAA;AAAO,KAC5D,CAAA;AAAA,EACH;AAAA;AAAA,EAGA,OAAA,GAAgB;AACd,IAAA,MAAM,KAAA,GAAQ,KAAK,WAAA,CAAY,MAAA;AAC/B,IAAA,MAAM,OAAA,GAAU,IAAA,CAAK,MAAA,CAAO,IAAA,CAAK,YAAY,CAAA;AAC7C,IAAA,IAAA,CAAK,WAAA,CAAY,OAAA,CAAQ,CAAC,IAAA,EAAM,KAAA,KAAU;AACxC,MAAA,IAAA,CAAK,QAAQ,KAAA,GACX,KAAA,GAAQ,UAAU,UAAA,GAAa,KAAA,KAAU,UAAU,SAAA,GAAY,UAAA;AACjE,MAAA,IAAI,UAAU,OAAA,EAAS;AACrB,QAAA,IAAA,CAAK,YAAA,CAAa,gBAAgB,MAAM,CAAA;AAAA,MAC1C,CAAA,MAAO;AACL,QAAA,IAAA,CAAK,gBAAgB,cAAc,CAAA;AAAA,MACrC;AAAA,IACF,CAAC,CAAA;AACD,IAAA,MAAM,KAAA,GAAQ,KAAA,GAAQ,CAAA,GAAI,OAAA,IAAW,QAAQ,CAAA,CAAA,GAAK,CAAA;AAClD,IAAA,IAAA,CAAK,QAAQ,KAAA,CAAM,WAAA,CAAY,+BAAA,EAAiC,MAAA,CAAO,KAAK,CAAC,CAAA;AAAA,EAC/E;AAAA;AAAA,EAGA,OAAO,KAAA,EAAuB;AAC5B,IAAA,MAAM,IAAA,GAAO,IAAA,CAAK,WAAA,CAAY,MAAA,GAAS,CAAA;AACvC,IAAA,IAAI,IAAA,GAAO,GAAG,OAAO,CAAA;AACrB,IAAA,OAAO,IAAA,CAAK,GAAA,CAAI,IAAA,EAAM,IAAA,CAAK,GAAA,CAAI,GAAG,IAAA,CAAK,KAAA,CAAM,KAAK,CAAC,CAAC,CAAA;AAAA,EACtD;AACF","file":"step_indicator_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/**\n * Headless, accessible **read-only** step-progress indicator.\n *\n * Markup contract (identifier: `stimeo--step-indicator`):\n *   <ol data-controller=\"stimeo--step-indicator\" aria-label=\"Checkout progress\"\n *       data-stimeo--step-indicator-current-value=\"1\"\n *       data-action=\"step:set->stimeo--step-indicator#setCurrent\">\n *     <li data-stimeo--step-indicator-target=\"step\">Cart</li>\n *     <li data-stimeo--step-indicator-target=\"step\">Shipping</li>\n *     <li data-stimeo--step-indicator-target=\"step\">Payment</li>\n *   </ol>\n *\n * There is no dedicated APG widget; the current position is expressed with\n * `aria-current=\"step\"`. This indicator is **read only** — it never moves focus\n * and the steps are not operable. For an interactive wizard whose steps are\n * `<button>`s, use {@link StepperController | Stepper}.\n *\n * @remarks\n * Behavior only. Each step `<li>` gets a `data-state` (`complete`/`current`/\n * `upcoming`) derived from the current index; the consumer draws the circles,\n * lines, and numbers from those hooks. A `--stimeo-step-indicator-ratio`\n * (0–1) custom property on the root expresses overall progress for CSS.\n *\n * Behavior provided:\n * - Reflects `current` onto each step's `data-state` and `aria-current`.\n * - `setCurrent` (bound to an event whose `detail.current` is the 0-based index)\n *   updates the current step and dispatches `stimeo--step-indicator:change`.\n */\nexport class StepIndicatorController extends Controller<HTMLElement> {\n  static override targets = [\"step\"];\n  static override values = {\n    current: { type: Number, default: 0 },\n  };\n  static actions = [\"setCurrent\"] as const;\n  static events = [\"change\"] as const;\n\n  declare readonly stepTargets: HTMLElement[];\n  declare currentValue: number;\n\n  /** Renders the initial state from the `current` value. */\n  override connect(): void {\n    this.#render();\n  }\n\n  /**\n   * Updates the current step from an external event (`detail.current`, 0-based)\n   * and dispatches `change`. Out-of-range indices are clamped to the step set.\n   */\n  setCurrent(event: CustomEvent<{ current?: number }>): void {\n    const next = event.detail?.current;\n    if (typeof next !== \"number\" || !Number.isFinite(next)) return;\n    const clamped = this.#clamp(next);\n    if (clamped === this.currentValue) return;\n    this.currentValue = clamped;\n    this.#render();\n    this.dispatch(\"change\", {\n      detail: { current: clamped, total: this.stepTargets.length },\n    });\n  }\n\n  /** Applies `data-state`, `aria-current`, and the progress ratio custom property. */\n  #render(): void {\n    const total = this.stepTargets.length;\n    const current = this.#clamp(this.currentValue);\n    this.stepTargets.forEach((step, index) => {\n      step.dataset.state =\n        index < current ? \"complete\" : index === current ? \"current\" : \"upcoming\";\n      if (index === current) {\n        step.setAttribute(\"aria-current\", \"step\");\n      } else {\n        step.removeAttribute(\"aria-current\");\n      }\n    });\n    const ratio = total > 1 ? current / (total - 1) : 0;\n    this.element.style.setProperty(\"--stimeo-step-indicator-ratio\", String(ratio));\n  }\n\n  /** Constrains an index to `[0, total-1]` (or `0` when there are no steps). */\n  #clamp(index: number): number {\n    const last = this.stepTargets.length - 1;\n    if (last < 0) return 0;\n    return Math.min(last, Math.max(0, Math.trunc(index)));\n  }\n}\n"]}

package/dist/controllers/stepper_controller.d.ts

@@ -0,0 +1,66 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless, accessible stepper / wizard navigation behavior.
+ *
+ * Markup contract (identifier: `stimeo--stepper`):
+ *   <ol data-controller="stimeo--stepper" data-stimeo--stepper-index-value="0">
+ *     <li data-stimeo--stepper-target="step">
+ *       <button aria-current="step" data-stimeo--stepper-index-param="0"
+ *               data-action="click->stimeo--stepper#goto">Account</button>
+ *     </li>
+ *     <!-- more steps -->
+ *   </ol>
+ *
+ * There is no dedicated APG widget; the current step is expressed with
+ * `aria-current="step"` on the operable `<button>`. Each step `<li>` also gets a
+ * `data-state` (`complete`/`current`/`upcoming`) derived from the current index.
+ * For a read-only progress display use
+ * {@link StepIndicatorController | Step Indicator}; for panel switching use Tabs.
+ *
+ * @remarks
+ * Behavior only. The controller never traps or restores focus — each step button
+ * is in the natural Tab order. `data-state` is purely derived from `index`
+ * (completion is not persisted).
+ *
+ * Behavior provided:
+ * - `next`/`prev` move one step, ignoring moves past either end.
+ * - `goto` jumps to the step in its `index` action param.
+ * - With `linear=true`, `goto` may not skip more than one step ahead of the
+ *   current one (moving backward is always allowed).
+ * - Each move re-derives `data-state`/`aria-current` and dispatches
+ *   `stimeo--stepper:change`.
+ */
+declare class StepperController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        index: {
+            type: NumberConstructor;
+            default: number;
+        };
+        linear: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+    };
+    static actions: readonly ["goto", "next", "prev"];
+    static events: readonly ["change"];
+    readonly stepTargets: HTMLElement[];
+    indexValue: number;
+    linearValue: boolean;
+    /** Normalizes an out-of-range initial `index` and renders the initial state. */
+    connect(): void;
+    /** Advances to the next step (ignored at the last step). */
+    next(): void;
+    /** Returns to the previous step (ignored at the first step). */
+    prev(): void;
+    /** Jumps to the step carried in the action's `index` param. */
+    goto(event: {
+        params: {
+            index?: number;
+        };
+    }): void;
+}
+
+export { StepperController };

package/dist/controllers/stepper_controller.js

@@ -0,0 +1,78 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/stepper_controller.ts
+var StepperController = class extends Controller {
+  static targets = ["step"];
+  static values = {
+    index: { type: Number, default: 0 },
+    linear: { type: Boolean, default: false }
+  };
+  static actions = ["goto", "next", "prev"];
+  static events = ["change"];
+  /** Normalizes an out-of-range initial `index` and renders the initial state. */
+  connect() {
+    this.indexValue = this.#clampIndex(this.indexValue);
+    this.#render();
+  }
+  /** Advances to the next step (ignored at the last step). */
+  next() {
+    this.#moveTo(this.indexValue + 1);
+  }
+  /** Returns to the previous step (ignored at the first step). */
+  prev() {
+    this.#moveTo(this.indexValue - 1);
+  }
+  /** Jumps to the step carried in the action's `index` param. */
+  goto(event) {
+    const target = Number(event.params.index);
+    if (!Number.isFinite(target)) return;
+    this.#moveTo(target);
+  }
+  /**
+   * Moves the current step to `target` when allowed: in range, not a no-op, and
+   * — under `linear` — not skipping more than one step ahead. Re-renders and
+   * dispatches `change`.
+   */
+  #moveTo(target) {
+    const total = this.stepTargets.length;
+    if (target < 0 || target >= total) return;
+    if (target === this.indexValue) return;
+    if (this.linearValue && target > this.indexValue + 1) return;
+    const previous = this.indexValue;
+    this.indexValue = target;
+    this.#render();
+    this.dispatch("change", {
+      detail: { index: target, previous, step: this.stepTargets[target] }
+    });
+  }
+  /**
+   * Derives each step's `data-state` and the current button's `aria-current`.
+   *
+   * `aria-current="step"` is placed on the step's **first** `<button>`; the markup
+   * contract assumes one operable button per step. If a step needs multiple
+   * buttons, mark the navigational one first (or this would target the wrong one).
+   */
+  #render() {
+    const current = this.indexValue;
+    this.stepTargets.forEach((step, index) => {
+      step.dataset.state = index < current ? "complete" : index === current ? "current" : "upcoming";
+      const button = step.querySelector("button");
+      if (!button) return;
+      if (index === current) {
+        button.setAttribute("aria-current", "step");
+      } else {
+        button.removeAttribute("aria-current");
+      }
+    });
+  }
+  /** Constrains an index to `[0, total-1]` (or `0` when there are no steps). */
+  #clampIndex(index) {
+    const last = this.stepTargets.length - 1;
+    if (last < 0) return 0;
+    return Math.min(last, Math.max(0, Math.trunc(index)));
+  }
+};
+
+export { StepperController };
+//# sourceMappingURL=stepper_controller.js.map
+//# sourceMappingURL=stepper_controller.js.map

package/dist/controllers/stepper_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/controllers/stepper_controller.ts"],"names":[],"mappings":"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","file":"stepper_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/**\n * Headless, accessible stepper / wizard navigation behavior.\n *\n * Markup contract (identifier: `stimeo--stepper`):\n *   <ol data-controller=\"stimeo--stepper\" data-stimeo--stepper-index-value=\"0\">\n *     <li data-stimeo--stepper-target=\"step\">\n *       <button aria-current=\"step\" data-stimeo--stepper-index-param=\"0\"\n *               data-action=\"click->stimeo--stepper#goto\">Account</button>\n *     </li>\n *     <!-- more steps -->\n *   </ol>\n *\n * There is no dedicated APG widget; the current step is expressed with\n * `aria-current=\"step\"` on the operable `<button>`. Each step `<li>` also gets a\n * `data-state` (`complete`/`current`/`upcoming`) derived from the current index.\n * For a read-only progress display use\n * {@link StepIndicatorController | Step Indicator}; for panel switching use Tabs.\n *\n * @remarks\n * Behavior only. The controller never traps or restores focus — each step button\n * is in the natural Tab order. `data-state` is purely derived from `index`\n * (completion is not persisted).\n *\n * Behavior provided:\n * - `next`/`prev` move one step, ignoring moves past either end.\n * - `goto` jumps to the step in its `index` action param.\n * - With `linear=true`, `goto` may not skip more than one step ahead of the\n *   current one (moving backward is always allowed).\n * - Each move re-derives `data-state`/`aria-current` and dispatches\n *   `stimeo--stepper:change`.\n */\nexport class StepperController extends Controller<HTMLElement> {\n  static override targets = [\"step\"];\n  static override values = {\n    index: { type: Number, default: 0 },\n    linear: { type: Boolean, default: false },\n  };\n  static actions = [\"goto\", \"next\", \"prev\"] as const;\n  static events = [\"change\"] as const;\n\n  declare readonly stepTargets: HTMLElement[];\n  declare indexValue: number;\n  declare linearValue: boolean;\n\n  /** Normalizes an out-of-range initial `index` and renders the initial state. */\n  override connect(): void {\n    this.indexValue = this.#clampIndex(this.indexValue);\n    this.#render();\n  }\n\n  /** Advances to the next step (ignored at the last step). */\n  next(): void {\n    this.#moveTo(this.indexValue + 1);\n  }\n\n  /** Returns to the previous step (ignored at the first step). */\n  prev(): void {\n    this.#moveTo(this.indexValue - 1);\n  }\n\n  /** Jumps to the step carried in the action's `index` param. */\n  goto(event: { params: { index?: number } }): void {\n    const target = Number(event.params.index);\n    if (!Number.isFinite(target)) return;\n    this.#moveTo(target);\n  }\n\n  /**\n   * Moves the current step to `target` when allowed: in range, not a no-op, and\n   * — under `linear` — not skipping more than one step ahead. Re-renders and\n   * dispatches `change`.\n   */\n  #moveTo(target: number): void {\n    const total = this.stepTargets.length;\n    if (target < 0 || target >= total) return;\n    if (target === this.indexValue) return;\n    if (this.linearValue && target > this.indexValue + 1) return;\n\n    const previous = this.indexValue;\n    this.indexValue = target;\n    this.#render();\n    this.dispatch(\"change\", {\n      detail: { index: target, previous, step: this.stepTargets[target] },\n    });\n  }\n\n  /**\n   * Derives each step's `data-state` and the current button's `aria-current`.\n   *\n   * `aria-current=\"step\"` is placed on the step's **first** `<button>`; the markup\n   * contract assumes one operable button per step. If a step needs multiple\n   * buttons, mark the navigational one first (or this would target the wrong one).\n   */\n  #render(): void {\n    const current = this.indexValue;\n    this.stepTargets.forEach((step, index) => {\n      step.dataset.state =\n        index < current ? \"complete\" : index === current ? \"current\" : \"upcoming\";\n      const button = step.querySelector<HTMLElement>(\"button\");\n      if (!button) return;\n      if (index === current) {\n        button.setAttribute(\"aria-current\", \"step\");\n      } else {\n        button.removeAttribute(\"aria-current\");\n      }\n    });\n  }\n\n  /** Constrains an index to `[0, total-1]` (or `0` when there are no steps). */\n  #clampIndex(index: number): number {\n    const last = this.stepTargets.length - 1;\n    if (last < 0) return 0;\n    return Math.min(last, Math.max(0, Math.trunc(index)));\n  }\n}\n"]}

package/dist/controllers/stick_to_bottom_controller.d.ts

@@ -0,0 +1,61 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless **stick-to-bottom**: auto-follows new content to the bottom of a scroll
+ * container (a chat log, a live console) — but only while the user is already near the
+ * bottom; if they have scrolled up to read, it holds position and flags that new content
+ * arrived instead (no APG pattern; honors WCAG 2.3.3 via `prefers-reduced-motion` and
+ * never steals focus).
+ *
+ * Markup contract (identifier: `stimeo--stick-to-bottom`):
+ *   <div data-controller="stimeo--stick-to-bottom"
+ *        data-stimeo--stick-to-bottom-threshold-value="80" style="overflow:auto">
+ *     <ul data-stimeo--stick-to-bottom-target="content"><!-- Turbo Stream appends --></ul>
+ *   </div>
+ *
+ * The container is "pinned" while its distance from the bottom is within `threshold`. A
+ * `MutationObserver` on `content` (or the element) reacts to appended children: while
+ * pinned it scrolls to the bottom; while unpinned it sets `data-has-new` and emits `new`.
+ * Scrolling recomputes pinned and reflects `data-pinned`, emitting `pin` on change; the
+ * `scrollToBottom` action jumps back down (a "new messages" button).
+ *
+ * @remarks
+ * The `MutationObserver` watches `childList` only (not `subtree`), so it follows
+ * direct appends to `content` (or the element). Appends made deeper inside a nested
+ * wrapper are not detected — keep messages as direct children, or call the public
+ * `scrollToBottom` action after such inserts.
+ *
+ * Behavior only — it does not add content (Turbo Stream / the consumer does) and is the
+ * minimal follow primitive, not a full chat UI (no virtualization / message input). It is
+ * the lightweight member of the scroll family. State is derived from the scroll position
+ * each pass (no module-scope state), so `connect()` re-syncs after a Turbo Stream insert;
+ * `behavior` falls back to `auto` under reduced motion; auto-scroll never moves focus; the
+ * observer and the passive scroll listener are released on `disconnect()` (Turbo
+ * navigation included).
+ */
+declare class StickToBottomController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        threshold: {
+            type: NumberConstructor;
+            default: number;
+        };
+        behavior: {
+            type: StringConstructor;
+            default: string;
+        };
+    };
+    static actions: readonly ["scrollToBottom"];
+    static events: readonly ["pin", "new"];
+    readonly contentTarget: HTMLElement;
+    readonly hasContentTarget: boolean;
+    thresholdValue: number;
+    behaviorValue: string;
+    connect(): void;
+    disconnect(): void;
+    /** Jumps to the bottom and re-pins (wired to a "new messages" button). */
+    scrollToBottom(): void;
+}
+
+export { StickToBottomController };