stimeo-ui 0.14.0 → 0.16.0

package/dist/controllers/step_indicator_controller.js.map

@@ -1 +1 @@
-{"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 * `change` dispatches `{ current: number, total: number }`.\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   * 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"]}
+{"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-index-value=\"1\"\n *       data-action=\"stimeo--stepper:change->stimeo--step-indicator#setIndex\">\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 * `change` dispatches `{ index: number, previous: number, total: number }`.\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 `index` onto each step's `data-state` and `aria-current`.\n * - Re-derives every step when the step set changes at runtime.\n * - `setIndex` (bound to an event whose `detail.index` is the 0-based position)\n *   moves the indicator and dispatches `stimeo--step-indicator:change`. A\n *   {@link StepperController | Stepper} dispatches exactly that shape, so the two\n *   compose with one `data-action` and no glue.\n */\nexport class StepIndicatorController extends Controller<HTMLElement> {\n  static override targets = [\"step\"];\n  static override values = {\n    index: { type: Number, default: 0 },\n  };\n  static actions = [\"setIndex\"] as const;\n  static events = [\"change\"] as const;\n\n  declare readonly stepTargets: HTMLElement[];\n  declare indexValue: number;\n\n  /**\n   * Collapses a batch of step callbacks — and a morph that swaps `index` 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 `index` 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 `index` at runtime. */\n  indexValueChanged(): void {\n    this.#repaint.schedule();\n  }\n\n  /**\n   * Moves the indicator from an external event (`detail.index`, 0-based) and\n   * dispatches `change`. Out-of-range positions 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 `index` already renders is not reported as a change.\n   */\n  setIndex(event: CustomEvent<{ index?: number }>): void {\n    const next = event.detail?.index;\n    if (typeof next !== \"number\" || !Number.isFinite(next)) return;\n    const clamped = this.#clamp(next);\n    const previous = this.#clamp(this.indexValue);\n    const moved = clamped !== previous;\n    // Normalise even when the display does not move: an out-of-range `index` 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.indexValue = clamped;\n    if (!moved) return;\n    this.#render();\n    this.dispatch(\"change\", {\n      detail: { index: clamped, previous, 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 `index`, 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.indexValue);\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: `index` 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.d.ts

@@ -16,21 +16,37 @@ import { Controller } from '@hotwired/stimulus';
  * `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.
+ * {@link StepIndicatorController | Step Indicator}; for panel switching use
+ * {@link TabsController | Tabs}.
  *
- * `change` dispatches `{ index: number, previous: number, step: HTMLElement }`.
+ * `change` dispatches `{ index: number, previous: number, total: number, step: HTMLElement }`,
+ * and `reconcile` dispatches the same
+ * `{ index: number, previous: number, total: number, step: HTMLElement }` — `previous`
+ * is the position shown before — when a change the page made moves the position of
+ * the current step (the clamped `index`).
  *
  * @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).
+ * is in the natural Tab order. `data-state` is purely derived from `index` and the
+ * steps present (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).
- * - Runtime changes to the `index` Value re-derive every step's state.
+ * - Runtime changes to the `index` Value, and steps added or removed at runtime,
+ *   re-derive every step's state once per batch. Once connected, a batch that
+ *   moves the current position (the clamped `index`) away from the one shown
+ *   reports `stimeo--stepper:reconcile` once. A batch that leaves the position
+ *   where it was reports nothing, even when another step now stands there — a
+ *   step added before the current one, or the current step removed while
+ *   another follows it — and only redraws `data-state`/`aria-current`;
+ *   connecting reports nothing.
+ * - An `index` outside the step range, fractional, or not a number at all is
+ *   clamped for display only. The Value keeps what the page declared, so the
+ *   declared step comes back once enough steps are present; a move the user makes
+ *   is the one path that writes it.
  * - Each move re-derives `data-state`/`aria-current` and dispatches
  *   `stimeo--stepper:change`.
  */
@@ -48,23 +64,32 @@ declare class StepperController extends Controller<HTMLElement> {
         };
     };
     static actions: readonly ["goto", "next", "prev"];
-    static events: readonly ["change"];
+    static events: readonly ["change", "reconcile"];
     readonly stepTargets: HTMLElement[];
     indexValue: number;
     linearValue: boolean;
-    /** Normalizes an out-of-range initial `index` and renders the initial state. */
+    /** Renders the initial state from `index`, clamped into the step range. */
     connect(): void;
+    /** Drops a pending pass, so nothing renders or reports for a stepper that left. */
     disconnect(): void;
     /** Re-renders when Turbo Morph or application code changes `index` at runtime. */
     indexValueChanged(): void;
+    /** Re-derives every step's state for a step added at runtime. */
+    stepTargetConnected(): void;
+    /** Re-derives every step's state for a step removed at runtime. */
+    stepTargetDisconnected(): 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. */
+    /**
+     * Jumps to the step carried in the action's `index` param. A param that is empty,
+     * or that Stimulus parses into anything but a number or a string, is no index,
+     * so it jumps nowhere.
+     */
     goto(event: {
         params: {
-            index?: number;
+            index?: unknown;
         };
     }): void;
 }

package/dist/controllers/stepper_controller.js

@@ -1,5 +1,40 @@
 import { Controller } from '@hotwired/stimulus';
 
+// src/controllers/stepper_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/stepper_controller.ts
 var StepperController = class extends Controller {
   static targets = ["step"];
@@ -8,20 +43,39 @@ var StepperController = class extends Controller {
     linear: { type: Boolean, default: false }
   };
   static actions = ["goto", "next", "prev"];
-  static events = ["change"];
-  #isConnected = false;
-  /** Normalizes an out-of-range initial `index` and renders the initial state. */
+  static events = ["change", "reconcile"];
+  /**
+   * Collapses the Value and target callbacks of one mutation into one pass, and
+   * refuses the ones Stimulus delivers before `connect()`, which renders itself.
+   */
+  #repaint = new MicrotaskCoalescer(() => this.#reconcileStep());
+  /**
+   * The position shown current last, which the next move is measured from, or
+   * `null` before any step has been shown. While no step is present it keeps the
+   * last one.
+   */
+  #shown = null;
+  /** Renders the initial state from `index`, clamped into the step range. */
   connect() {
-    this.#isConnected = true;
-    this.#normalizeAndRender();
+    this.#repaint.activate();
+    this.#shown = this.#currentStep;
+    this.#render();
   }
+  /** Drops a pending pass, so nothing renders or reports for a stepper that left. */
   disconnect() {
-    this.#isConnected = false;
+    this.#repaint.cancel();
   }
   /** Re-renders when Turbo Morph or application code changes `index` at runtime. */
   indexValueChanged() {
-    if (!this.#isConnected) return;
-    this.#normalizeAndRender();
+    this.#repaint.schedule();
+  }
+  /** Re-derives every step's state for a step added at runtime. */
+  stepTargetConnected() {
+    this.#repaint.schedule();
+  }
+  /** Re-derives every step's state for a step removed at runtime. */
+  stepTargetDisconnected() {
+    this.#repaint.schedule();
   }
   /** Advances to the next step (ignored at the last step). */
   next() {
@@ -31,9 +85,16 @@ var StepperController = class extends Controller {
   prev() {
     this.#moveTo(this.#clampIndex(this.indexValue) - 1);
   }
-  /** Jumps to the step carried in the action's `index` param. */
+  /**
+   * Jumps to the step carried in the action's `index` param. A param that is empty,
+   * or that Stimulus parses into anything but a number or a string, is no index,
+   * so it jumps nowhere.
+   */
   goto(event) {
-    const target = Number(event.params.index);
+    const { index } = event.params;
+    if (index === "") return;
+    if (typeof index !== "number" && typeof index !== "string") return;
+    const target = Number(index);
     if (!Number.isFinite(target) || !Number.isInteger(target)) return;
     this.#moveTo(target);
   }
@@ -51,19 +112,39 @@ var StepperController = class extends Controller {
     if (this.linearValue && target > current + 1) return;
     const previous = current;
     this.indexValue = target;
-    this.#render(target);
+    this.#shown = target;
+    this.#render();
     this.dispatch("change", {
-      detail: { index: target, previous, step: this.stepTargets[target] }
+      detail: { index: target, previous, total, step: this.stepTargets[target] }
     });
   }
-  /** Normalizes the public Value and reflects it without dispatching an action event. */
-  #normalizeAndRender() {
-    const normalized = this.#clampIndex(this.indexValue);
-    if (!Object.is(normalized, this.indexValue)) this.indexValue = normalized;
-    this.#render(normalized);
+  /**
+   * Re-derives one settled batch of Value and target changes, and reports a
+   * current position that moved from the one shown before as `reconcile`. With no
+   * step present there is nothing to report, and the position shown last stays the
+   * one the next move is measured from.
+   */
+  #reconcileStep() {
+    const previous = this.#shown;
+    const index = this.#currentStep;
+    if (index !== null) this.#shown = index;
+    this.#render();
+    if (index === null || previous === null || index === previous) return;
+    const steps = this.stepTargets;
+    this.dispatch("reconcile", {
+      detail: { index, previous, total: steps.length, step: steps[index] }
+    });
+  }
+  /** The current position, clamped into the step range, or `null` when there is no step. */
+  get #currentStep() {
+    return this.stepTargets.length > 0 ? this.#clampIndex(this.indexValue) : null;
   }
   /**
-   * Derives each step's `data-state` and the current button's `aria-current`.
+   * Derives each step's `data-state` and the current button's `aria-current` from
+   * `index`, clamped into the step range, without dispatching an action event.
+   *
+   * The clamp decides only what is shown. This body never writes `index`, so an
+   * out-of-range declaration stays in the attribute as the page wrote it.
    *
    * `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
@@ -71,7 +152,8 @@ var StepperController = class extends Controller {
    *
    * @stimeoRenderRoot
    */
-  #render(current) {
+  #render() {
+    const current = this.#clampIndex(this.indexValue);
     this.stepTargets.forEach((step, index) => {
       step.dataset.state = index < current ? "complete" : index === current ? "current" : "upcoming";
       const button = step.querySelector("button");

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 * `change` dispatches `{ index: number, previous: number, step: HTMLElement }`.\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"]}
+{"version":3,"sources":["../../src/utils/microtask_coalescer.ts","../../src/controllers/stepper_controller.ts"],"names":[],"mappings":"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","file":"stepper_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 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\n * {@link TabsController | Tabs}.\n *\n * `change` dispatches `{ index: number, previous: number, total: number, step: HTMLElement }`,\n * and `reconcile` dispatches the same\n * `{ index: number, previous: number, total: number, step: HTMLElement }` — `previous`\n * is the position shown before — when a change the page made moves the position of\n * the current step (the clamped `index`).\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` and the\n * steps present (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, and steps added or removed at runtime,\n *   re-derive every step's state once per batch. Once connected, a batch that\n *   moves the current position (the clamped `index`) away from the one shown\n *   reports `stimeo--stepper:reconcile` once. A batch that leaves the position\n *   where it was reports nothing, even when another step now stands there — a\n *   step added before the current one, or the current step removed while\n *   another follows it — and only redraws `data-state`/`aria-current`;\n *   connecting reports nothing.\n * - An `index` outside the step range, fractional, or not a number at all is\n *   clamped for display only. The Value keeps what the page declared, so the\n *   declared step comes back once enough steps are present; a move the user makes\n *   is the one path that writes it.\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\", \"reconcile\"] as const;\n\n  declare readonly stepTargets: HTMLElement[];\n  declare indexValue: number;\n  declare linearValue: boolean;\n\n  /**\n   * Collapses the Value and target callbacks of one mutation into one pass, and\n   * refuses the ones Stimulus delivers before `connect()`, which renders itself.\n   */\n  readonly #repaint = new MicrotaskCoalescer(() => this.#reconcileStep());\n\n  /**\n   * The position shown current last, which the next move is measured from, or\n   * `null` before any step has been shown. While no step is present it keeps the\n   * last one.\n   */\n  #shown: number | null = null;\n\n  /** Renders the initial state from `index`, clamped into the step range. */\n  override connect(): void {\n    this.#repaint.activate();\n    this.#shown = this.#currentStep;\n    this.#render();\n  }\n\n  /** Drops a pending pass, so nothing renders or reports for a stepper that left. */\n  override disconnect(): void {\n    this.#repaint.cancel();\n  }\n\n  /** Re-renders when Turbo Morph or application code changes `index` at runtime. */\n  indexValueChanged(): void {\n    this.#repaint.schedule();\n  }\n\n  /** Re-derives every step's state for a step added at runtime. */\n  stepTargetConnected(): void {\n    this.#repaint.schedule();\n  }\n\n  /** Re-derives every step's state for a step removed at runtime. */\n  stepTargetDisconnected(): void {\n    this.#repaint.schedule();\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  /**\n   * Jumps to the step carried in the action's `index` param. A param that is empty,\n   * or that Stimulus parses into anything but a number or a string, is no index,\n   * so it jumps nowhere.\n   */\n  goto(event: { params: { index?: unknown } }): void {\n    const { index } = event.params;\n    if (index === \"\") return;\n    if (typeof index !== \"number\" && typeof index !== \"string\") return;\n    const target = Number(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    // Settled before the report, so the pass the Value write starts finds the step\n    // already shown, and a listener that moves on is measured from this step.\n    this.#shown = target;\n    this.#render();\n    this.dispatch(\"change\", {\n      detail: { index: target, previous, total, step: this.stepTargets[target] },\n    });\n  }\n\n  /**\n   * Re-derives one settled batch of Value and target changes, and reports a\n   * current position that moved from the one shown before as `reconcile`. With no\n   * step present there is nothing to report, and the position shown last stays the\n   * one the next move is measured from.\n   */\n  #reconcileStep(): void {\n    const previous = this.#shown;\n    const index = this.#currentStep;\n    if (index !== null) this.#shown = index;\n    this.#render();\n    if (index === null || previous === null || index === previous) return;\n    const steps = this.stepTargets;\n    this.dispatch(\"reconcile\", {\n      detail: { index, previous, total: steps.length, step: steps[index] },\n    });\n  }\n\n  /** The current position, clamped into the step range, or `null` when there is no step. */\n  get #currentStep(): number | null {\n    return this.stepTargets.length > 0 ? this.#clampIndex(this.indexValue) : null;\n  }\n\n  /**\n   * Derives each step's `data-state` and the current button's `aria-current` from\n   * `index`, clamped into the step range, without dispatching an action event.\n   *\n   * The clamp decides only what is shown. This body never writes `index`, so an\n   * out-of-range declaration stays in the attribute as the page wrote it.\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(): void {\n    const current = this.#clampIndex(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 || !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

@@ -12,6 +12,8 @@ import { Controller } from '@hotwired/stimulus';
  *        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>
+ *     <button type="button" hidden data-stimeo--stick-to-bottom-target="hasNew"
+ *             data-action="stimeo--stick-to-bottom#scrollToBottom">New messages</button>
  *   </div>
  *
  * The container is "pinned" while it has a box to measure and its distance from the
@@ -21,6 +23,12 @@ import { Controller } from '@hotwired/stimulus';
  * emitting `pin` on change; the `scrollToBottom` action jumps back down (a "new messages"
  * button). A `threshold` changed at runtime re-derives the state at once.
  *
+ * `data-has-new` says which state the container is in; the optional `hasNew` targets are
+ * the regions that belong to the flagged side — the affordance offering the jump back
+ * down. They are shown while the flag is up and hidden while it is down, written wherever
+ * the flag moves, so an authored `hidden` settles at the first reflection and a restored
+ * DOM cannot leave the region contradicting the flag.
+ *
  * A container that already overflows renders at `scrollTop` 0 — further than
  * `threshold` from the bottom, so unpinned — and flags the first append rather
  * than following it. `pinOnConnect` opts into the other starting point:
@@ -72,6 +80,7 @@ declare class StickToBottomController extends Controller<HTMLElement> {
     static events: readonly ["pin", "new"];
     readonly contentTarget: HTMLElement;
     readonly hasContentTarget: boolean;
+    readonly hasNewTargets: HTMLElement[];
     thresholdValue: number;
     behaviorValue: string;
     pinOnConnectValue: boolean;
@@ -81,6 +90,16 @@ declare class StickToBottomController extends Controller<HTMLElement> {
     contentTargetConnected(): void;
     /** Moves the append watch off a `content` target that left, back onto the container. */
     contentTargetDisconnected(): void;
+    /**
+     * Settles a has-new region that arrived at runtime on the side the flag is currently
+     * on, the way a region present at connect is settled by the connect-time normalization.
+     *
+     * Stimulus attaches targets before `connect()`, and a container that leaves the document
+     * and comes back keeps its controller, so in that window the flag still reads the
+     * arrival of the connection that ended. A region attached there is left to the
+     * connect-time normalization, which drops the flag and settles the region in one write.
+     */
+    hasNewTargetConnected(): void;
     /**
      * Re-derives pinned when the distance that counts as the bottom is changed at runtime
      * (a morph that swaps the attribute on a retained element).

package/dist/controllers/stick_to_bottom_controller.js

@@ -8,10 +8,15 @@ var LayoutObserver = class {
   #resizeObserverFactory;
   #resizeObserver = null;
   #observingViewport = false;
+  #loadContainer = null;
   /** Stable bound handler so add/removeEventListener target the same reference. */
   #handleViewportResize = () => {
     this.#callback();
   };
+  /** Stable bound handler for the capture-phase `load`; see {@link observeDescendantLoads}. */
+  #handleDescendantLoad = () => {
+    this.#callback();
+  };
   constructor(callback, options = {}) {
     this.#callback = callback;
     this.#resizeObserverFactory = options.resizeObserverFactory ?? (typeof ResizeObserver === "undefined" ? null : (cb) => new ResizeObserver(cb));
@@ -47,14 +52,35 @@ var LayoutObserver = class {
     window.removeEventListener("resize", this.#handleViewportResize);
   }
   /**
-   * Releases every observation: disconnects the {@link ResizeObserver} and
-   * removes the viewport listener. Safe to call multiple times. Call this from a
-   * controller's `disconnect()`.
+   * Starts reporting a `load` from anywhere inside `container` — an image or a
+   * frame settling changes the box it sits in, and it measures as zero high until
+   * then. `load` does not bubble, so the subscription is a capture-phase listener
+   * on the container itself and nothing the caller spells.
+   *
+   * **One container at a time.** A further call moves the observation, so a widget
+   * whose content element is swapped at runtime releases the element it let go by
+   * naming the new one — there is no second place for the release to drift from.
+   */
+  observeDescendantLoads(container) {
+    this.unobserveDescendantLoads();
+    this.#loadContainer = container;
+    container.addEventListener("load", this.#handleDescendantLoad, true);
+  }
+  /** Stops reporting descendant loads without affecting element or viewport observation. */
+  unobserveDescendantLoads() {
+    this.#loadContainer?.removeEventListener("load", this.#handleDescendantLoad, true);
+    this.#loadContainer = null;
+  }
+  /**
+   * Releases every observation: disconnects the {@link ResizeObserver} and removes
+   * the viewport and descendant-load listeners. Safe to call multiple times. Call
+   * this from a controller's `disconnect()`.
    */
   disconnect() {
     this.#resizeObserver?.disconnect();
     this.#resizeObserver = null;
     this.unobserveViewport();
+    this.unobserveDescendantLoads();
   }
 };
 
@@ -63,6 +89,47 @@ function prefersReducedMotion() {
   return typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
 }
 
+// src/utils/state_regions.ts
+var StateRegions = class {
+  #whenTrue;
+  #whenFalse;
+  #taken = /* @__PURE__ */ new WeakSet();
+  constructor(options) {
+    this.#whenTrue = options.whenTrue;
+    this.#whenFalse = options.whenFalse ?? null;
+  }
+  /** Shows the regions inside `host` that belong to `isTrue` and hides the others. */
+  reflect(host, isTrue) {
+    const shown = this.#inside(host, this.#whenTrue());
+    if (!this.#whenFalse) {
+      for (const region of shown) this.#write(region, !isTrue);
+      return;
+    }
+    const hiddenSide = this.#inside(host, this.#whenFalse());
+    if (shown.length === 0 || hiddenSide.length === 0) {
+      for (const region of shown) this.#give(region);
+      for (const region of hiddenSide) this.#give(region);
+      return;
+    }
+    for (const region of shown) this.#write(region, !isTrue);
+    for (const region of hiddenSide) this.#write(region, isTrue);
+  }
+  /** Writes `hidden` where it moves, noting which regions it takes out of view. */
+  #write(region, hidden) {
+    if (hidden) this.#taken.add(region);
+    else this.#taken.delete(region);
+    if (region.hidden !== hidden) region.hidden = hidden;
+  }
+  /** Returns a region this instance hid; one it never hid keeps what it carries. */
+  #give(region) {
+    if (this.#taken.delete(region)) region.hidden = false;
+  }
+  /** The declared regions that sit within `host`, which may be the host itself. */
+  #inside(host, regions) {
+    return regions.filter((region) => host.contains(region));
+  }
+};
+
 // src/controllers/stick_to_bottom_controller.ts
 var DEFAULT_THRESHOLD = 80;
 var countElements = (nodes) => {
@@ -71,7 +138,7 @@ var countElements = (nodes) => {
   return n;
 };
 var StickToBottomController = class extends Controller {
-  static targets = ["content"];
+  static targets = ["content", "hasNew"];
   static values = {
     threshold: { type: Number, default: DEFAULT_THRESHOLD },
     behavior: { type: String, default: "auto" },
@@ -87,11 +154,14 @@ var StickToBottomController = class extends Controller {
   #awaitingLayout = false;
   #connected = false;
   #pinned = false;
+  #hasNew = false;
+  /** Owns `hidden` on the regions declared for the has-new state. */
+  #hasNewRegion = new StateRegions({ whenTrue: () => this.hasNewTargets });
   #onScroll = () => this.#updatePinned();
   connect() {
     this.#connected = true;
     if (this.pinOnConnectValue && this.#measurable()) this.#scrollToBottom("instant");
-    this.element.removeAttribute("data-has-new");
+    this.#setHasNew(false);
     this.#pinned = this.#isPinned();
     this.#reflectPinned();
     this.element.addEventListener("scroll", this.#onScroll, { passive: true });
@@ -112,6 +182,19 @@ var StickToBottomController = class extends Controller {
   contentTargetDisconnected() {
     this.#syncWatched();
   }
+  /**
+   * Settles a has-new region that arrived at runtime on the side the flag is currently
+   * on, the way a region present at connect is settled by the connect-time normalization.
+   *
+   * Stimulus attaches targets before `connect()`, and a container that leaves the document
+   * and comes back keeps its controller, so in that window the flag still reads the
+   * arrival of the connection that ended. A region attached there is left to the
+   * connect-time normalization, which drops the flag and settles the region in one write.
+   */
+  hasNewTargetConnected() {
+    if (!this.#connected) return;
+    this.#hasNewRegion.reflect(this.element, this.#hasNew);
+  }
   /**
    * Re-derives pinned when the distance that counts as the bottom is changed at runtime
    * (a morph that swaps the attribute on a retained element).
@@ -133,7 +216,7 @@ var StickToBottomController = class extends Controller {
    */
   scrollToBottom() {
     this.#scrollToBottom();
-    this.element.removeAttribute("data-has-new");
+    this.#setHasNew(false);
     this.#updatePinned();
   }
   /** Follows appended children while pinned; otherwise flags new content. */
@@ -144,7 +227,7 @@ var StickToBottomController = class extends Controller {
     if (this.#pinned) {
       this.#scrollToBottom();
     } else {
-      this.element.setAttribute("data-has-new", "true");
+      this.#setHasNew(true);
       this.dispatch("new", { detail: { count: added } });
     }
   }
@@ -164,11 +247,24 @@ var StickToBottomController = class extends Controller {
   #reflectPinned() {
     if (this.#pinned) {
       this.element.setAttribute("data-pinned", "true");
-      this.element.removeAttribute("data-has-new");
+      this.#setHasNew(false);
     } else {
       this.element.removeAttribute("data-pinned");
     }
   }
+  /**
+   * Mirrors whether content has arrived that the container did not follow onto the state
+   * hook and onto the regions declared for that state.
+   */
+  #setHasNew(hasNew) {
+    this.#hasNew = hasNew;
+    if (hasNew) {
+      this.element.setAttribute("data-has-new", "true");
+    } else {
+      this.element.removeAttribute("data-has-new");
+    }
+    this.#hasNewRegion.reflect(this.element, hasNew);
+  }
   /** Whether the container currently sits within `threshold` of its bottom. */
   #isPinned() {
     if (!this.#measurable()) return false;