stimeo-ui 0.3.0 → 0.5.0

package/dist/controllers/step_indicator_controller.js

@@ -1,5 +1,40 @@
 import { Controller } from '@hotwired/stimulus';
 
+// src/controllers/step_indicator_controller.ts
+
+// src/utils/microtask_coalescer.ts
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  /** @param run - the single reconciliation pass, invoked at most once per batch. */
+  constructor(run) {
+    this.#run = run;
+  }
+  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
+  activate() {
+    this.#active = true;
+  }
+  /** Closes the window and drops any pending pass; call from `disconnect()`. */
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
+  schedule() {
+    if (!this.#active || this.#queued) return;
+    this.#queued = true;
+    const generation = this.#generation;
+    queueMicrotask(() => {
+      if (generation !== this.#generation || !this.#queued || !this.#active) return;
+      this.#queued = false;
+      this.#run();
+    });
+  }
+};
+
 // src/controllers/step_indicator_controller.ts
 var StepIndicatorController = class extends Controller {
   static targets = ["step"];
@@ -8,26 +43,65 @@ var StepIndicatorController = class extends Controller {
   };
   static actions = ["setCurrent"];
   static events = ["change"];
+  /**
+   * Whether the target callbacks may render. Stimulus reports the authored steps
+   * as connected before `connect()` and the remaining ones as disconnected after
+   * `disconnect()`, so this keeps a connect at one render pass, not one per step.
+   */
+  /**
+   * Collapses a batch of step callbacks — and a morph that swaps `current` with
+   * them — into one repaint. Replacing a list of N steps delivers N callbacks, and
+   * each one would otherwise rewrite every step's state.
+   */
+  #repaint = new MicrotaskCoalescer(() => this.#render());
   /** Renders the initial state from the `current` value. */
   connect() {
+    this.#repaint.activate();
     this.#render();
   }
+  /** Closes the window in which a queued repaint may still run. */
+  disconnect() {
+    this.#repaint.cancel();
+  }
+  /** Syncs a step appended or replaced at runtime (the consumer owns the list). */
+  stepTargetConnected() {
+    this.#repaint.schedule();
+  }
+  /** Re-derives the remaining steps when one is removed at runtime. */
+  stepTargetDisconnected() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `current` at runtime. */
+  currentValueChanged() {
+    this.#repaint.schedule();
+  }
   /**
    * 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.
+   * and dispatches `change`. Out-of-range indices are clamped to the step set,
+   * and both sides of the no-op test are clamped, so moving onto the step an
+   * out-of-range `current` already renders is not reported as a change.
    */
   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;
+    const moved = clamped !== this.#clamp(this.currentValue);
     this.currentValue = clamped;
+    if (!moved) return;
     this.#render();
     this.dispatch("change", {
       detail: { current: clamped, total: this.stepTargets.length }
     });
   }
-  /** Applies `data-state`, `aria-current`, and the progress ratio custom property. */
+  /**
+   * Applies `data-state`, `aria-current`, and the progress ratio custom property.
+   *
+   * A pure function of the step set and `current`, so running it again writes the
+   * same values — which is what lets the action path paint synchronously (the event
+   * goes out after the DOM is updated) while a coalesced pass may still follow.
+   *
+   * @stimeoRenderRoot
+   */
   #render() {
     const total = this.stepTargets.length;
     const current = this.#clamp(this.currentValue);
@@ -40,12 +114,17 @@ var StepIndicatorController = class extends Controller {
       }
     });
     const ratio = total > 1 ? current / (total - 1) : 0;
-    this.element.style.setProperty("--stimeo-step-indicator-ratio", String(ratio));
+    this.element.style.setProperty("--stimeo--step-indicator-ratio", String(ratio));
   }
-  /** Constrains an index to `[0, total-1]` (or `0` when there are no steps). */
+  /**
+   * Constrains an index to `[0, total-1]` (or `0` when there are no steps). A
+   * non-finite index falls back to the first step: `current` is read from markup,
+   * so an unparsable attribute arrives as `NaN` and would otherwise propagate
+   * into every state hook.
+   */
   #clamp(index) {
     const last = this.stepTargets.length - 1;
-    if (last < 0) return 0;
+    if (last < 0 || !Number.isFinite(index)) return 0;
     return Math.min(last, Math.max(0, Math.trunc(index)));
   }
 };

package/dist/controllers/step_indicator_controller.js.map

@@ -1 +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"]}
+{"version":3,"sources":["../../src/utils/microtask_coalescer.ts","../../src/controllers/step_indicator_controller.ts"],"names":[],"mappings":"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","file":"step_indicator_controller.js","sourcesContent":["/**\n * Collapses many Stimulus lifecycle callbacks from one DOM mutation into a\n * single pass.\n *\n * Stimulus fires `<name>TargetConnected` / `Disconnected` once per element and\n * `<name>ValueChanged` once per changed attribute. Replacing a list of N options\n * or morphing several render Values therefore delivers N callbacks — but the\n * useful unit of work is \"reconcile against the resulting declarative input\",\n * once, after the batch has settled. Every controller with reconcilable targets\n * or render Values needs the same shape: a `queued` flag plus `queueMicrotask`.\n *\n * **A microtask is the right horizon, and the reason is specific.** Stimulus\n * drives these callbacks from a `MutationObserver`, whose own callback already\n * runs as a microtask with the whole batch in hand; scheduling one more lands\n * after the last sibling callback of that batch and still before paint or any\n * event handler. A timer would be later than it needs to be, and reconciling\n * synchronously would run once per element against a half-applied DOM.\n *\n * **The two guards are not the same guard.** Scheduling is refused before the\n * controller connects, and running is refused after it disconnects:\n *\n * - **Before `connect()`** — Stimulus delivers initial target and Value callbacks\n *   ahead of `connect()`. Reconciling there would compute output against a\n *   controller whose own state has not been initialised, and `connect()` is\n *   about to do a full pass anyway.\n * - **After `disconnect()`** — Stimulus fires a callback for **every** target\n *   during teardown, and a microtask queued just before it would otherwise run\n *   against a detached tree. {@link MicrotaskCoalescer.cancel} exists for the\n *   teardown path to drop the pending pass outright.\n *\n * Both guards are part of one contract here rather than something each consumer\n * has to remember separately.\n *\n * Scope is the scheduling only. *What* to reconcile — keep the surviving active\n * option, fall back to the next / previous / first visible one, rebuild derived\n * chips or hidden fields — stays in the controller, because no two consumers\n * answer it the same way.\n *\n * This file's own doc block is dropped from `dist`, but every member comment is\n * inlined into each consumer entry (`tsup` builds with `splitting: false`), so\n * rationale belongs here and only the contract belongs on the members.\n *\n * @example\n * ```ts\n * readonly #reconcile = new MicrotaskCoalescer(() => this.#reconcileOptions());\n *\n * connect()    { this.#reconcile.activate(); }\n * disconnect() { this.#reconcile.cancel(); }\n *\n * optionTargetConnected()    { this.#reconcile.schedule(); }\n * optionTargetDisconnected() { this.#reconcile.schedule(); }\n * ```\n */\nexport class MicrotaskCoalescer {\n  readonly #run: () => void;\n  #queued = false;\n  #active = false;\n  #generation = 0;\n\n  /** @param run - the single reconciliation pass, invoked at most once per batch. */\n  constructor(run: () => void) {\n    this.#run = run;\n  }\n\n  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */\n  activate(): void {\n    this.#active = true;\n  }\n\n  /** Closes the window and drops any pending pass; call from `disconnect()`. */\n  cancel(): void {\n    this.#active = false;\n    this.#queued = false;\n    this.#generation += 1;\n  }\n\n  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */\n  schedule(): void {\n    if (!this.#active || this.#queued) return;\n    this.#queued = true;\n    const generation = this.#generation;\n    queueMicrotask(() => {\n      // A cancelled callback must not consume a pass queued after reconnect.\n      if (generation !== this.#generation || !this.#queued || !this.#active) return;\n      this.#queued = false;\n      this.#run();\n    });\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { MicrotaskCoalescer } from \"../utils/microtask_coalescer\";\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 * - Re-derives every step when the step set changes at runtime.\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  /**\n   * Whether the target callbacks may render. Stimulus reports the authored steps\n   * as connected before `connect()` and the remaining ones as disconnected after\n   * `disconnect()`, so this keeps a connect at one render pass, not one per step.\n   */\n  /**\n   * Collapses a batch of step callbacks — and a morph that swaps `current` with\n   * them — into one repaint. Replacing a list of N steps delivers N callbacks, and\n   * each one would otherwise rewrite every step's state.\n   */\n  readonly #repaint = new MicrotaskCoalescer(() => this.#render());\n\n  /** Renders the initial state from the `current` value. */\n  override connect(): void {\n    this.#repaint.activate();\n    this.#render();\n  }\n\n  /** Closes the window in which a queued repaint may still run. */\n  override disconnect(): void {\n    this.#repaint.cancel();\n  }\n\n  /** Syncs a step appended or replaced at runtime (the consumer owns the list). */\n  stepTargetConnected(): void {\n    this.#repaint.schedule();\n  }\n\n  /** Re-derives the remaining steps when one is removed at runtime. */\n  stepTargetDisconnected(): void {\n    this.#repaint.schedule();\n  }\n\n  /** Repaints when application code (or a Turbo morph) changes `current` at runtime. */\n  currentValueChanged(): void {\n    this.#repaint.schedule();\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   * and both sides of the no-op test are clamped, so moving onto the step an\n   * out-of-range `current` already renders is not reported as a change.\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    const moved = clamped !== this.#clamp(this.currentValue);\n    // Normalise even when the display does not move: an out-of-range `current` left\n    // in the markup would otherwise be re-clamped against a later step set and land\n    // somewhere the consumer never asked for. Writing it here is the consumer-driven\n    // path, the only one that owns the Value.\n    this.currentValue = clamped;\n    if (!moved) return;\n    this.#render();\n    this.dispatch(\"change\", {\n      detail: { current: clamped, total: this.stepTargets.length },\n    });\n  }\n\n  /**\n   * Applies `data-state`, `aria-current`, and the progress ratio custom property.\n   *\n   * A pure function of the step set and `current`, so running it again writes the\n   * same values — which is what lets the action path paint synchronously (the event\n   * goes out after the DOM is updated) while a coalesced pass may still follow.\n   *\n   * @stimeoRenderRoot\n   */\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  /**\n   * Constrains an index to `[0, total-1]` (or `0` when there are no steps). A\n   * non-finite index falls back to the first step: `current` is read from markup,\n   * so an unparsable attribute arrives as `NaN` and would otherwise propagate\n   * into every state hook.\n   */\n  #clamp(index: number): number {\n    const last = this.stepTargets.length - 1;\n    if (last < 0 || !Number.isFinite(index)) return 0;\n    return Math.min(last, Math.max(0, Math.trunc(index)));\n  }\n}\n"]}

package/dist/controllers/stepper_controller.js

@@ -68,6 +68,8 @@ var StepperController = class extends Controller {
    * `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).
+   *
+   * @stimeoRenderRoot
    */
   #render(current) {
     this.stepTargets.forEach((step, index) => {

package/dist/controllers/stepper_controller.js.map

@@ -1 +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 * - Runtime changes to the `index` Value re-derive every step's state.\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  #isConnected = false;\n\n  /** Normalizes an out-of-range initial `index` and renders the initial state. */\n  override connect(): void {\n    this.#isConnected = true;\n    this.#normalizeAndRender();\n  }\n\n  override disconnect(): void {\n    this.#isConnected = false;\n  }\n\n  /** Re-renders when Turbo Morph or application code changes `index` at runtime. */\n  indexValueChanged(): void {\n    if (!this.#isConnected) return;\n    this.#normalizeAndRender();\n  }\n\n  /** Advances to the next step (ignored at the last step). */\n  next(): void {\n    this.#moveTo(this.#clampIndex(this.indexValue) + 1);\n  }\n\n  /** Returns to the previous step (ignored at the first step). */\n  prev(): void {\n    this.#moveTo(this.#clampIndex(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) || !Number.isInteger(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 (!Number.isFinite(target) || !Number.isInteger(target)) return;\n    if (target < 0 || target >= total) return;\n    const current = this.#clampIndex(this.indexValue);\n    if (target === current) return;\n    if (this.linearValue && target > current + 1) return;\n\n    const previous = current;\n    this.indexValue = target;\n    this.#render(target);\n    this.dispatch(\"change\", {\n      detail: { index: target, previous, step: this.stepTargets[target] },\n    });\n  }\n\n  /** Normalizes the public Value and reflects it without dispatching an action event. */\n  #normalizeAndRender(): void {\n    const normalized = this.#clampIndex(this.indexValue);\n    if (!Object.is(normalized, this.indexValue)) this.indexValue = normalized;\n    this.#render(normalized);\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(current: number): void {\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 || !Number.isFinite(index)) return 0;\n    return Math.min(last, Math.max(0, Math.trunc(index)));\n  }\n}\n"]}
+{"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 * - Runtime changes to the `index` Value re-derive every step's state.\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  #isConnected = false;\n\n  /** Normalizes an out-of-range initial `index` and renders the initial state. */\n  override connect(): void {\n    this.#isConnected = true;\n    this.#normalizeAndRender();\n  }\n\n  override disconnect(): void {\n    this.#isConnected = false;\n  }\n\n  /** Re-renders when Turbo Morph or application code changes `index` at runtime. */\n  indexValueChanged(): void {\n    if (!this.#isConnected) return;\n    this.#normalizeAndRender();\n  }\n\n  /** Advances to the next step (ignored at the last step). */\n  next(): void {\n    this.#moveTo(this.#clampIndex(this.indexValue) + 1);\n  }\n\n  /** Returns to the previous step (ignored at the first step). */\n  prev(): void {\n    this.#moveTo(this.#clampIndex(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) || !Number.isInteger(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 (!Number.isFinite(target) || !Number.isInteger(target)) return;\n    if (target < 0 || target >= total) return;\n    const current = this.#clampIndex(this.indexValue);\n    if (target === current) return;\n    if (this.linearValue && target > current + 1) return;\n\n    const previous = current;\n    this.indexValue = target;\n    this.#render(target);\n    this.dispatch(\"change\", {\n      detail: { index: target, previous, step: this.stepTargets[target] },\n    });\n  }\n\n  /** Normalizes the public Value and reflects it without dispatching an action event. */\n  #normalizeAndRender(): void {\n    const normalized = this.#clampIndex(this.indexValue);\n    if (!Object.is(normalized, this.indexValue)) this.indexValue = normalized;\n    this.#render(normalized);\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   * @stimeoRenderRoot\n   */\n  #render(current: number): void {\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 || !Number.isFinite(index)) 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

@@ -9,7 +9,8 @@ import { Controller } from '@hotwired/stimulus';
  *
  * 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">
+ *        data-stimeo--stick-to-bottom-threshold-value="80"
+ *        data-stimeo--stick-to-bottom-pin-on-connect-value="true" style="overflow:auto">
  *     <ul data-stimeo--stick-to-bottom-target="content"><!-- Turbo Stream appends --></ul>
  *   </div>
  *
@@ -19,6 +20,14 @@ import { Controller } from '@hotwired/stimulus';
  * Scrolling recomputes pinned and reflects `data-pinned`, emitting `pin` on change; the
  * `scrollToBottom` action jumps back down (a "new messages" button).
  *
+ * A container renders at `scrollTop` 0 — unpinned — so out of the box it flags the first
+ * append rather than following it. `pinOnConnect` opts into the other starting point:
+ * `connect()` jumps to the bottom and reads the state back from where it landed. It runs
+ * on every connect, so a container inserted or re-rendered later (a Turbo Stream, a panel
+ * built on open) starts at the bottom too — which a once-per-document page event cannot
+ * do. It is off by default, so a restored reading position (a Turbo cache restore, a user
+ * who had scrolled up) is never yanked to the bottom unless the consumer asks for it.
+ *
  * @remarks
  * The `MutationObserver` watches `childList` only (not `subtree`), so it follows
  * direct appends to `content` (or the element). Appends made deeper inside a nested
@@ -44,6 +53,10 @@ declare class StickToBottomController extends Controller<HTMLElement> {
             type: StringConstructor;
             default: string;
         };
+        pinOnConnect: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
     };
     static actions: readonly ["scrollToBottom"];
     static events: readonly ["pin", "new"];
@@ -51,9 +64,20 @@ declare class StickToBottomController extends Controller<HTMLElement> {
     readonly hasContentTarget: boolean;
     thresholdValue: number;
     behaviorValue: string;
+    pinOnConnectValue: boolean;
     connect(): void;
     disconnect(): void;
-    /** Jumps to the bottom and re-pins (wired to a "new messages" button). */
+    /**
+     * Jumps to the bottom and re-pins (wired to a "new messages" button).
+     *
+     * The has-new flag clears on request — the user has acknowledged the arrival — while
+     * pinned is read back from where the scroll landed: a jump that arrives by the time
+     * this returns pins immediately, an animated one settles from its own scroll events,
+     * and a jump the engine cannot honor leaves the container unpinned, so the next append
+     * flags it again instead of being swallowed by a pinned state that does not hold.
+     *
+     * Which of those happens is not this method's to decide — see {@link behaviorValue}.
+     */
     scrollToBottom(): void;
 }
 

package/dist/controllers/stick_to_bottom_controller.js

@@ -17,14 +17,18 @@ var StickToBottomController = class extends Controller {
   static targets = ["content"];
   static values = {
     threshold: { type: Number, default: 80 },
-    behavior: { type: String, default: "auto" }
+    behavior: { type: String, default: "auto" },
+    pinOnConnect: { type: Boolean, default: false }
   };
   static actions = ["scrollToBottom"];
   static events = ["pin", "new"];
   #observer = null;
+  /** Watches for the box a deferred `pinOnConnect` jump is still waiting on. */
+  #layout = null;
   #pinned = false;
   #onScroll = () => this.#updatePinned();
   connect() {
+    if (this.pinOnConnectValue && this.#measurable()) this.#scrollToBottom("instant");
     this.#pinned = this.#isPinned();
     this.#reflectPinned();
     this.element.addEventListener("scroll", this.#onScroll, { passive: true });
@@ -32,21 +36,29 @@ var StickToBottomController = class extends Controller {
       this.#observer = new MutationObserver((mutations) => this.#onMutations(mutations));
       this.#observer.observe(this.#watched(), { childList: true });
     }
+    if (this.pinOnConnectValue && !this.#measurable()) this.#pinWhenLaidOut();
   }
   disconnect() {
     this.element.removeEventListener("scroll", this.#onScroll);
     this.#observer?.disconnect();
     this.#observer = null;
+    this.#stopWaitingForLayout();
   }
-  /** Jumps to the bottom and re-pins (wired to a "new messages" button). */
+  /**
+   * Jumps to the bottom and re-pins (wired to a "new messages" button).
+   *
+   * The has-new flag clears on request — the user has acknowledged the arrival — while
+   * pinned is read back from where the scroll landed: a jump that arrives by the time
+   * this returns pins immediately, an animated one settles from its own scroll events,
+   * and a jump the engine cannot honor leaves the container unpinned, so the next append
+   * flags it again instead of being swallowed by a pinned state that does not hold.
+   *
+   * Which of those happens is not this method's to decide — see {@link behaviorValue}.
+   */
   scrollToBottom() {
     this.#scrollToBottom();
     this.element.removeAttribute("data-has-new");
-    if (!this.#pinned) {
-      this.#pinned = true;
-      this.element.setAttribute("data-pinned", "true");
-      this.dispatch("pin", { detail: { pinned: true } });
-    }
+    this.#updatePinned();
   }
   /** Follows appended children while pinned; otherwise flags new content. */
   #onMutations(mutations) {
@@ -81,10 +93,43 @@ var StickToBottomController = class extends Controller {
     const el = this.element;
     return el.scrollHeight - el.clientHeight - el.scrollTop <= this.thresholdValue;
   }
-  #scrollToBottom() {
+  /**
+   * Whether the container has a box to scroll and to measure. One that is not rendered
+   * (inside a closed panel) reports every metric as 0, which reads as "already at the
+   * bottom" — a position describing no layout the user will ever see.
+   */
+  #measurable() {
+    return this.element.clientHeight > 0;
+  }
+  /**
+   * Holds the `pinOnConnect` jump until the container is laid out, then runs it and
+   * re-reads the state — otherwise the panel opens at the top still claiming the bottom.
+   */
+  #pinWhenLaidOut() {
+    if (typeof ResizeObserver === "undefined") return;
+    this.#layout = new ResizeObserver(() => {
+      if (!this.#measurable()) return;
+      this.#stopWaitingForLayout();
+      this.#scrollToBottom("instant");
+      this.#updatePinned();
+    });
+    this.#layout.observe(this.element);
+  }
+  /** Releases the layout watch, whether or not the deferred jump ever ran. */
+  #stopWaitingForLayout() {
+    this.#layout?.disconnect();
+    this.#layout = null;
+  }
+  /**
+   * Scrolls to the bottom, clamped by the engine to the maximum scroll offset — which is
+   * 0 for a container tall enough to hold its whole content, so the jump moves nothing
+   * there. `behavior` defaults to the configured follow behavior; pass `"instant"` for a
+   * jump that must not animate.
+   */
+  #scrollToBottom(behavior = this.#behavior()) {
     const top = this.element.scrollHeight;
     if (typeof this.element.scrollTo === "function") {
-      this.element.scrollTo({ top, behavior: this.#behavior() });
+      this.element.scrollTo({ top, behavior });
     } else {
       this.element.scrollTop = top;
     }
@@ -93,7 +138,12 @@ var StickToBottomController = class extends Controller {
   #watched() {
     return this.hasContentTarget ? this.contentTarget : this.element;
   }
-  /** Forces reduced-motion jumps while preserving the configured normal behavior. */
+  /**
+   * The behavior a follow-scroll runs with. `"auto"` is **not** a request to arrive at
+   * once: it hands the decision to the element's computed `scroll-behavior`, so a
+   * consumer stylesheet saying `smooth` animates these scrolls too. Only `"instant"`
+   * overrides that CSS, which is why reduced motion and the `pinOnConnect` jump name it.
+   */
   #behavior() {
     if (prefersReducedMotion()) return "instant";
     return this.behaviorValue === "smooth" ? "smooth" : "auto";

package/dist/controllers/stick_to_bottom_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/reduced_motion.ts","../../src/controllers/stick_to_bottom_controller.ts"],"names":[],"mappings":"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","file":"stick_to_bottom_controller.js","sourcesContent":["/**\n * Shared `prefers-reduced-motion` lookup for the motion-aware controllers\n * (count-up, highlight, overflow-indicator, scroll-visibility, stick-to-bottom,\n * transition).\n *\n * This one-liner keeps the media query string and the environment guard\n * single-sourced across them. The preference is intentionally re-read on every\n * call — the controllers check it at each animation/scroll start (WCAG 2.2\n * **2.3.3**), so flipping the OS setting takes effect immediately without any\n * listener or cache bookkeeping here.\n */\n\n/**\n * Whether the user currently requests reduced motion.\n *\n * @returns `true` when `(prefers-reduced-motion: reduce)` matches; `false`\n * otherwise, including environments without `window.matchMedia` (treated as\n * \"no preference\").\n */\nexport function prefersReducedMotion(): boolean {\n  return (\n    typeof window.matchMedia === \"function\" &&\n    window.matchMedia(\"(prefers-reduced-motion: reduce)\").matches\n  );\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { prefersReducedMotion } from \"../utils/reduced_motion\";\n\n/** Counts the element nodes in an added-node list (text nodes are ignored). */\nconst countElements = (nodes: NodeList): number => {\n  let n = 0;\n  for (const node of nodes) if (node.nodeType === Node.ELEMENT_NODE) n += 1;\n  return n;\n};\n\n/**\n * Headless **stick-to-bottom**: auto-follows new content to the bottom of a scroll\n * container (a chat log, a live console) — but only while the user is already near the\n * bottom; if they have scrolled up to read, it holds position and flags that new content\n * arrived instead (no APG pattern; honors WCAG 2.3.3 via `prefers-reduced-motion` and\n * never steals focus).\n *\n * Markup contract (identifier: `stimeo--stick-to-bottom`):\n *   <div data-controller=\"stimeo--stick-to-bottom\"\n *        data-stimeo--stick-to-bottom-threshold-value=\"80\" style=\"overflow:auto\">\n *     <ul data-stimeo--stick-to-bottom-target=\"content\"><!-- Turbo Stream appends --></ul>\n *   </div>\n *\n * The container is \"pinned\" while its distance from the bottom is within `threshold`. A\n * `MutationObserver` on `content` (or the element) reacts to appended children: while\n * pinned it scrolls to the bottom; while unpinned it sets `data-has-new` and emits `new`.\n * Scrolling recomputes pinned and reflects `data-pinned`, emitting `pin` on change; the\n * `scrollToBottom` action jumps back down (a \"new messages\" button).\n *\n * @remarks\n * The `MutationObserver` watches `childList` only (not `subtree`), so it follows\n * direct appends to `content` (or the element). Appends made deeper inside a nested\n * wrapper are not detected — keep messages as direct children, or call the public\n * `scrollToBottom` action after such inserts.\n *\n * Behavior only — it does not add content (Turbo Stream / the consumer does) and is the\n * minimal follow primitive, not a full chat UI (no virtualization / message input). State\n * is derived from the scroll position each pass (no module-scope state), so `connect()`\n * re-syncs after a Turbo Stream insert; reduced motion forces an instant jump\n * independently of consumer CSS; auto-scroll never moves focus; the observer and the\n * passive scroll listener are released on `disconnect()` (Turbo navigation included).\n */\nexport class StickToBottomController extends Controller<HTMLElement> {\n  static override targets = [\"content\"];\n  static override values = {\n    threshold: { type: Number, default: 80 },\n    behavior: { type: String, default: \"auto\" },\n  };\n  static actions = [\"scrollToBottom\"] as const;\n  static events = [\"pin\", \"new\"] as const;\n\n  declare readonly contentTarget: HTMLElement;\n  declare readonly hasContentTarget: boolean;\n\n  declare thresholdValue: number;\n  declare behaviorValue: string;\n\n  #observer: MutationObserver | null = null;\n  #pinned = false;\n\n  readonly #onScroll = (): void => this.#updatePinned();\n\n  override connect(): void {\n    this.#pinned = this.#isPinned();\n    // Re-sync the hooks from the current geometry — a Turbo cache restore may bring back a\n    // stale data-pinned / data-has-new that disagrees with the current scroll position.\n    this.#reflectPinned();\n\n    this.element.addEventListener(\"scroll\", this.#onScroll, { passive: true });\n    if (typeof MutationObserver !== \"undefined\") {\n      this.#observer = new MutationObserver((mutations) => this.#onMutations(mutations));\n      this.#observer.observe(this.#watched(), { childList: true });\n    }\n  }\n\n  override disconnect(): void {\n    this.element.removeEventListener(\"scroll\", this.#onScroll);\n    this.#observer?.disconnect();\n    this.#observer = null;\n  }\n\n  /** Jumps to the bottom and re-pins (wired to a \"new messages\" button). */\n  scrollToBottom(): void {\n    this.#scrollToBottom();\n    this.element.removeAttribute(\"data-has-new\");\n    if (!this.#pinned) {\n      this.#pinned = true;\n      this.element.setAttribute(\"data-pinned\", \"true\");\n      this.dispatch(\"pin\", { detail: { pinned: true } });\n    }\n  }\n\n  /** Follows appended children while pinned; otherwise flags new content. */\n  #onMutations(mutations: MutationRecord[]): void {\n    let added = 0;\n    for (const mutation of mutations) added += countElements(mutation.addedNodes);\n    if (added === 0) return;\n\n    if (this.#pinned) {\n      this.#scrollToBottom();\n    } else {\n      this.element.setAttribute(\"data-has-new\", \"true\");\n      this.dispatch(\"new\", { detail: { count: added } });\n    }\n  }\n\n  /** Recomputes pinned from the scroll position and reflects it on a transition. */\n  #updatePinned(): void {\n    const pinned = this.#isPinned();\n    if (pinned === this.#pinned) return;\n    this.#pinned = pinned;\n    this.#reflectPinned();\n    this.dispatch(\"pin\", { detail: { pinned } });\n  }\n\n  /** Mirrors the current `#pinned` onto the state hooks (clearing has-new once pinned). */\n  #reflectPinned(): void {\n    if (this.#pinned) {\n      this.element.setAttribute(\"data-pinned\", \"true\");\n      this.element.removeAttribute(\"data-has-new\"); // caught up with the bottom\n    } else {\n      this.element.removeAttribute(\"data-pinned\");\n    }\n  }\n\n  #isPinned(): boolean {\n    const el = this.element;\n    return el.scrollHeight - el.clientHeight - el.scrollTop <= this.thresholdValue;\n  }\n\n  #scrollToBottom(): void {\n    const top = this.element.scrollHeight;\n    if (typeof this.element.scrollTo === \"function\") {\n      this.element.scrollTo({ top, behavior: this.#behavior() });\n    } else {\n      this.element.scrollTop = top;\n    }\n  }\n\n  /** The append-watched element: the `content` target, or the container itself. */\n  #watched(): HTMLElement {\n    return this.hasContentTarget ? this.contentTarget : this.element;\n  }\n\n  /** Forces reduced-motion jumps while preserving the configured normal behavior. */\n  #behavior(): ScrollBehavior {\n    if (prefersReducedMotion()) return \"instant\";\n    return this.behaviorValue === \"smooth\" ? \"smooth\" : \"auto\";\n  }\n}\n"]}
+{"version":3,"sources":["../../src/utils/reduced_motion.ts","../../src/controllers/stick_to_bottom_controller.ts"],"names":[],"mappings":"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","file":"stick_to_bottom_controller.js","sourcesContent":["/**\n * Shared `prefers-reduced-motion` lookup for the motion-aware controllers\n * (count-up, highlight, overflow-indicator, scroll-visibility, stick-to-bottom,\n * transition).\n *\n * This one-liner keeps the media query string and the environment guard\n * single-sourced across them. The preference is intentionally re-read on every\n * call — the controllers check it at each animation/scroll start (WCAG 2.2\n * **2.3.3**), so flipping the OS setting takes effect immediately without any\n * listener or cache bookkeeping here.\n */\n\n/**\n * Whether the user currently requests reduced motion.\n *\n * @returns `true` when `(prefers-reduced-motion: reduce)` matches; `false`\n * otherwise, including environments without `window.matchMedia` (treated as\n * \"no preference\").\n */\nexport function prefersReducedMotion(): boolean {\n  return (\n    typeof window.matchMedia === \"function\" &&\n    window.matchMedia(\"(prefers-reduced-motion: reduce)\").matches\n  );\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { prefersReducedMotion } from \"../utils/reduced_motion\";\n\n/** Counts the element nodes in an added-node list (text nodes are ignored). */\nconst countElements = (nodes: NodeList): number => {\n  let n = 0;\n  for (const node of nodes) if (node.nodeType === Node.ELEMENT_NODE) n += 1;\n  return n;\n};\n\n/**\n * Headless **stick-to-bottom**: auto-follows new content to the bottom of a scroll\n * container (a chat log, a live console) — but only while the user is already near the\n * bottom; if they have scrolled up to read, it holds position and flags that new content\n * arrived instead (no APG pattern; honors WCAG 2.3.3 via `prefers-reduced-motion` and\n * never steals focus).\n *\n * Markup contract (identifier: `stimeo--stick-to-bottom`):\n *   <div data-controller=\"stimeo--stick-to-bottom\"\n *        data-stimeo--stick-to-bottom-threshold-value=\"80\"\n *        data-stimeo--stick-to-bottom-pin-on-connect-value=\"true\" style=\"overflow:auto\">\n *     <ul data-stimeo--stick-to-bottom-target=\"content\"><!-- Turbo Stream appends --></ul>\n *   </div>\n *\n * The container is \"pinned\" while its distance from the bottom is within `threshold`. A\n * `MutationObserver` on `content` (or the element) reacts to appended children: while\n * pinned it scrolls to the bottom; while unpinned it sets `data-has-new` and emits `new`.\n * Scrolling recomputes pinned and reflects `data-pinned`, emitting `pin` on change; the\n * `scrollToBottom` action jumps back down (a \"new messages\" button).\n *\n * A container renders at `scrollTop` 0 — unpinned — so out of the box it flags the first\n * append rather than following it. `pinOnConnect` opts into the other starting point:\n * `connect()` jumps to the bottom and reads the state back from where it landed. It runs\n * on every connect, so a container inserted or re-rendered later (a Turbo Stream, a panel\n * built on open) starts at the bottom too — which a once-per-document page event cannot\n * do. It is off by default, so a restored reading position (a Turbo cache restore, a user\n * who had scrolled up) is never yanked to the bottom unless the consumer asks for it.\n *\n * @remarks\n * The `MutationObserver` watches `childList` only (not `subtree`), so it follows\n * direct appends to `content` (or the element). Appends made deeper inside a nested\n * wrapper are not detected — keep messages as direct children, or call the public\n * `scrollToBottom` action after such inserts.\n *\n * Behavior only — it does not add content (Turbo Stream / the consumer does) and is the\n * minimal follow primitive, not a full chat UI (no virtualization / message input). State\n * is derived from the scroll position each pass (no module-scope state), so `connect()`\n * re-syncs after a Turbo Stream insert; reduced motion forces an instant jump\n * independently of consumer CSS; auto-scroll never moves focus; the observer and the\n * passive scroll listener are released on `disconnect()` (Turbo navigation included).\n */\nexport class StickToBottomController extends Controller<HTMLElement> {\n  static override targets = [\"content\"];\n  static override values = {\n    threshold: { type: Number, default: 80 },\n    behavior: { type: String, default: \"auto\" },\n    pinOnConnect: { type: Boolean, default: false },\n  };\n  static actions = [\"scrollToBottom\"] as const;\n  static events = [\"pin\", \"new\"] as const;\n\n  declare readonly contentTarget: HTMLElement;\n  declare readonly hasContentTarget: boolean;\n\n  declare thresholdValue: number;\n  declare behaviorValue: string;\n  declare pinOnConnectValue: boolean;\n\n  #observer: MutationObserver | null = null;\n  /** Watches for the box a deferred `pinOnConnect` jump is still waiting on. */\n  #layout: ResizeObserver | null = null;\n  #pinned = false;\n\n  readonly #onScroll = (): void => this.#updatePinned();\n\n  override connect(): void {\n    // Instant whatever `behavior` says, overriding a consumer's `scroll-behavior: smooth`:\n    // an animated jump emits scroll events on the way down, each recomputing pinned from a\n    // position still far from the bottom, so the container would unpin (and re-pin)\n    // mid-flight before it ever settles.\n    if (this.pinOnConnectValue && this.#measurable()) this.#scrollToBottom(\"instant\");\n    // Read the state back from where the container actually is, asked for a jump or not: a\n    // request the engine does not honor must leave it unpinned, so the next append is\n    // flagged rather than swallowed. This also drops a stale data-pinned / data-has-new a\n    // Turbo cache restore brought back.\n    this.#pinned = this.#isPinned();\n    this.#reflectPinned();\n\n    this.element.addEventListener(\"scroll\", this.#onScroll, { passive: true });\n    if (typeof MutationObserver !== \"undefined\") {\n      this.#observer = new MutationObserver((mutations) => this.#onMutations(mutations));\n      this.#observer.observe(this.#watched(), { childList: true });\n    }\n    if (this.pinOnConnectValue && !this.#measurable()) this.#pinWhenLaidOut();\n  }\n\n  override disconnect(): void {\n    this.element.removeEventListener(\"scroll\", this.#onScroll);\n    this.#observer?.disconnect();\n    this.#observer = null;\n    this.#stopWaitingForLayout();\n  }\n\n  /**\n   * Jumps to the bottom and re-pins (wired to a \"new messages\" button).\n   *\n   * The has-new flag clears on request — the user has acknowledged the arrival — while\n   * pinned is read back from where the scroll landed: a jump that arrives by the time\n   * this returns pins immediately, an animated one settles from its own scroll events,\n   * and a jump the engine cannot honor leaves the container unpinned, so the next append\n   * flags it again instead of being swallowed by a pinned state that does not hold.\n   *\n   * Which of those happens is not this method's to decide — see {@link behaviorValue}.\n   */\n  scrollToBottom(): void {\n    this.#scrollToBottom();\n    this.element.removeAttribute(\"data-has-new\");\n    this.#updatePinned();\n  }\n\n  /** Follows appended children while pinned; otherwise flags new content. */\n  #onMutations(mutations: MutationRecord[]): void {\n    let added = 0;\n    for (const mutation of mutations) added += countElements(mutation.addedNodes);\n    if (added === 0) return;\n\n    if (this.#pinned) {\n      this.#scrollToBottom();\n    } else {\n      this.element.setAttribute(\"data-has-new\", \"true\");\n      this.dispatch(\"new\", { detail: { count: added } });\n    }\n  }\n\n  /** Recomputes pinned from the scroll position and reflects it on a transition. */\n  #updatePinned(): void {\n    const pinned = this.#isPinned();\n    if (pinned === this.#pinned) return;\n    this.#pinned = pinned;\n    this.#reflectPinned();\n    this.dispatch(\"pin\", { detail: { pinned } });\n  }\n\n  /** Mirrors the current `#pinned` onto the state hooks (clearing has-new once pinned). */\n  #reflectPinned(): void {\n    if (this.#pinned) {\n      this.element.setAttribute(\"data-pinned\", \"true\");\n      this.element.removeAttribute(\"data-has-new\"); // caught up with the bottom\n    } else {\n      this.element.removeAttribute(\"data-pinned\");\n    }\n  }\n\n  #isPinned(): boolean {\n    const el = this.element;\n    return el.scrollHeight - el.clientHeight - el.scrollTop <= this.thresholdValue;\n  }\n\n  /**\n   * Whether the container has a box to scroll and to measure. One that is not rendered\n   * (inside a closed panel) reports every metric as 0, which reads as \"already at the\n   * bottom\" — a position describing no layout the user will ever see.\n   */\n  #measurable(): boolean {\n    return this.element.clientHeight > 0;\n  }\n\n  /**\n   * Holds the `pinOnConnect` jump until the container is laid out, then runs it and\n   * re-reads the state — otherwise the panel opens at the top still claiming the bottom.\n   */\n  #pinWhenLaidOut(): void {\n    if (typeof ResizeObserver === \"undefined\") return;\n    this.#layout = new ResizeObserver(() => {\n      if (!this.#measurable()) return;\n      this.#stopWaitingForLayout();\n      this.#scrollToBottom(\"instant\");\n      this.#updatePinned();\n    });\n    this.#layout.observe(this.element);\n  }\n\n  /** Releases the layout watch, whether or not the deferred jump ever ran. */\n  #stopWaitingForLayout(): void {\n    this.#layout?.disconnect();\n    this.#layout = null;\n  }\n\n  /**\n   * Scrolls to the bottom, clamped by the engine to the maximum scroll offset — which is\n   * 0 for a container tall enough to hold its whole content, so the jump moves nothing\n   * there. `behavior` defaults to the configured follow behavior; pass `\"instant\"` for a\n   * jump that must not animate.\n   */\n  #scrollToBottom(behavior: ScrollBehavior = this.#behavior()): void {\n    const top = this.element.scrollHeight;\n    if (typeof this.element.scrollTo === \"function\") {\n      this.element.scrollTo({ top, behavior });\n    } else {\n      this.element.scrollTop = top;\n    }\n  }\n\n  /** The append-watched element: the `content` target, or the container itself. */\n  #watched(): HTMLElement {\n    return this.hasContentTarget ? this.contentTarget : this.element;\n  }\n\n  /**\n   * The behavior a follow-scroll runs with. `\"auto\"` is **not** a request to arrive at\n   * once: it hands the decision to the element's computed `scroll-behavior`, so a\n   * consumer stylesheet saying `smooth` animates these scrolls too. Only `\"instant\"`\n   * overrides that CSS, which is why reduced motion and the `pinOnConnect` jump name it.\n   */\n  #behavior(): ScrollBehavior {\n    if (prefersReducedMotion()) return \"instant\";\n    return this.behaviorValue === \"smooth\" ? \"smooth\" : \"auto\";\n  }\n}\n"]}

package/dist/controllers/switch_controller.d.ts

@@ -4,7 +4,7 @@ import { Controller } from '@hotwired/stimulus';
  * Headless, accessible switch (toggle) behavior.
  *
  * Markup contract (identifier: `stimeo--switch`):
- *   <button data-controller="stimeo--switch"
+ *   <button type="button" data-controller="stimeo--switch"
  *           data-action="stimeo--switch#toggle keydown->stimeo--switch#onKeydown"
  *           role="switch" aria-checked="false">…</button>
  *
@@ -14,9 +14,11 @@ import { Controller } from '@hotwired/stimulus';
  * @remarks
  * Behavior only — the consumer owns all styling (typically keyed off the
  * `[aria-checked="true"]` attribute). On a native `<button>` host, the browser
- * already synthesizes a click for Space/Enter, so {@link onKeydown} deliberately
- * does nothing there (to avoid a double toggle) and only drives non-button hosts
- * such as `<div role="switch" tabindex="0">`.
+ * already synthesizes a click for Space/Enter, so {@link onKeydown} leaves the
+ * initial key to the browser and suppresses repeated keydowns. Non-button hosts
+ * such as `<div role="switch" tabindex="0">` are driven directly. Other native
+ * interactive hosts stand down because their checked/navigation semantics would
+ * conflict with `aria-checked` as this controller's sole source of truth.
  *
  * Behavior provided:
  * - Click (or Space/Enter) toggles `aria-checked` between `"true"` and `"false"`.
@@ -29,13 +31,15 @@ declare class SwitchController extends Controller<HTMLElement> {
     static events: readonly ["changed"];
     /** Ensures the switch exposes a role and is keyboard-reachable. */
     connect(): void;
+    /** Releases the explicit click guard and retained-element attribute observer. */
+    disconnect(): void;
     /** Toggles the checked state. Bound via `data-action` (click). */
     toggle(): void;
     /**
-     * Activates the switch on Space/Enter for non-native hosts and prevents the
-     * default Space scroll. Bound via `data-action` (keydown). Native `<button>`
-     * hosts are skipped because the browser already turns Space/Enter into a click,
-     * which would otherwise toggle the switch twice.
+     * Activates the switch on Space/Enter for non-native hosts and suppresses key
+     * repeat. Bound via `data-action` (keydown). A native `<button type="button">`
+     * owns the initial key-to-click synthesis; repeated keydowns are canceled before
+     * the browser can synthesize additional clicks.
      */
     onKeydown(event: KeyboardEvent): void;
 }