stimeo-ui 0.15.0 → 0.17.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/listener_set.ts","../../src/utils/microtask_coalescer.ts","../../src/utils/morph_render_watcher.ts","../../src/utils/number_bounds.ts","../../src/utils/coerce.ts","../../src/utils/number_value.ts","../../src/controllers/step_indicator_controller.ts"],"names":[],"mappings":"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","file":"step_indicator_controller.js","sourcesContent":["/**\n * Owns every listener a controller attaches for one connected lifetime and\n * releases them together, so an event name is spelled once and the release\n * cannot drift from the registration.\n *\n * Detaching by hand repeats three things at the release site — the type, the\n * handler reference and the capture flag — and any one of them drifting leaves\n * a listener alive on an element the controller no longer drives. Aborting the\n * signal a registration was created with releases it whatever it was made of,\n * so the release site names nothing.\n *\n * One set per lifetime, held as a field and never rebuilt. {@link\n * ListenerSet.dispose} is the only thing that closes a generation, and it opens\n * the next one in the same step, so the lifecycle hooks can call `add` and\n * `dispose` in any order any number of times, and no `add` ever meets an\n * already aborted signal — a DOM that registers a listener on such a signal\n * would keep it forever. Rebuilding the set instead would leak:\n * `addEventListener` matches an existing registration on target, type, callback\n * and capture alone, so re-adding the same handler while the first registration\n * is live is discarded, and that live registration keeps the signal it was\n * attached with — a set built by a second `connect()` can never release what it\n * appears to own.\n *\n * Scope is the registration only. Timers, observers, leases and the order they\n * are unwound in stay with the controller, which places `dispose()` in its\n * cleanup sequence. A receiver that changes at runtime (a\n * swapped target) is rebound by calling `dispose()` and then `add()` again from\n * the rebind, not by a second set.\n *\n * The set must own every registration of a tuple it holds: a listener the same\n * target already carries for the same type, callback and capture flag keeps the\n * right to remove it, and this set's `add` for that tuple is discarded. A\n * subscription shared between instances behind a participant count, or one that\n * lives for less than the connection, keeps its own pair of calls.\n *\n * @example\n * ```ts\n * readonly #listeners = new ListenerSet();\n *\n * connect(): void {\n *   this.#listeners.add(this.element, \"submit\", this.#onNativeSubmit, { capture: true });\n *   this.#listeners.add(this.element, \"turbo:submit-start\", this.#onSubmitStart);\n *   this.#listeners.add(this.element, \"turbo:submit-end\", this.#onSubmitEnd);\n * }\n *\n * disconnect(): void {\n *   this.#listeners.dispose();\n * }\n * ```\n */\nexport class ListenerSet {\n  /** The generation every `add` joins until the next `dispose()`. */\n  #abort = new AbortController();\n\n  /**\n   * Attaches `handler` to the open generation, exactly as the caller spelled it.\n   *\n   * The set supplies the signal, so `options` carries everything else the DOM\n   * accepts — `capture` included, which has to match at release time and no\n   * longer has a second place to drift from.\n   */\n  add(\n    target: EventTarget,\n    type: string,\n    handler: EventListener,\n    options?: Omit<AddEventListenerOptions, \"signal\">,\n  ): void {\n    target.addEventListener(type, handler, { ...options, signal: this.#abort.signal });\n  }\n\n  /**\n   * Releases every listener of the open generation, synchronously, and opens the\n   * next one. Idempotent, and safe before anything has been added.\n   */\n  dispose(): void {\n    this.#abort.abort();\n    this.#abort = new AbortController();\n  }\n}\n","/**\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 * @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 { ListenerSet } from \"./listener_set\";\nimport { MicrotaskCoalescer } from \"./microtask_coalescer\";\n\n/**\n * Coalesces retained-element morphs and explicit lifecycle requests into one pass.\n *\n * Observe the controller's element after its initial state is settled. Morphs on\n * that element and bubbling morphs on its descendants share the same microtask\n * as {@link schedule}. The callback repairs derived output; the controller owns\n * any logical transition reporting. {@link disconnect} releases the listener and\n * cancels pending work, including work from an earlier connected lifetime.\n */\nexport class MorphRenderWatcher {\n  readonly #listeners = new ListenerSet();\n  readonly #pass: MicrotaskCoalescer;\n  #element: Element | null = null;\n  readonly #onMorph = (): void => this.#pass.schedule();\n\n  /** @param run - the single pass that repairs the settled controller's output. */\n  constructor(run: () => void) {\n    this.#pass = new MicrotaskCoalescer(run);\n  }\n\n  /** Opens observation; observing the same element again preserves queued work. */\n  observe(element: Element): void {\n    if (this.#element === element) return;\n    this.disconnect();\n    this.#element = element;\n    this.#pass.activate();\n    this.#listeners.add(element, \"turbo:morph-element\", this.#onMorph);\n  }\n\n  /** Requests one pass; requests outside an observed lifetime are ignored. */\n  schedule(): void {\n    this.#pass.schedule();\n  }\n\n  /** Releases observation and pending work synchronously; safe to repeat. */\n  disconnect(): void {\n    this.#listeners.dispose();\n    this.#pass.cancel();\n    this.#element = null;\n  }\n}\n","import { MAX_TIMER_DELAY_MS } from \"./timer_bounds\";\n\n/** Semantic constraints on an already decoded number, independent of the DOM. */\nexport interface NumberBounds {\n  /** Finite numbers are required, including when this field is omitted. */\n  readonly finite?: true;\n  /** Inclusive lower endpoint. */\n  readonly min?: number;\n  /** Inclusive upper endpoint. */\n  readonly max?: number;\n  /** Exclusive lower endpoint. */\n  readonly exclusiveMin?: number;\n  /** Require a number without a fractional part. */\n  readonly integer?: boolean;\n  /** Exact decoded numbers accepted by a discrete contract. */\n  readonly allowedValues?: readonly number[];\n  /** JSON-safe exceptions to finite-number checking for unbounded endpoints. */\n  readonly allowInfinity?: \"negative\" | \"positive\" | \"both\";\n}\n\n/** One constraint for each Number Value, including shorthand declarations. */\nexport type NumberValueConstraints<Values> = {\n  readonly [Key in keyof Values as Values[Key] extends\n    | NumberConstructor\n    | { type: NumberConstructor }\n    ? Key\n    : never]: NumberBounds;\n};\n\n/** Reusable semantic domains; fractional inputs remain fractional unless excluded. */\nexport const NUMBER_BOUNDS = {\n  finite: { finite: true },\n  nonNegative: { finite: true, min: 0 },\n  positive: { finite: true, exclusiveMin: 0 },\n  nonNegativeInteger: { finite: true, min: 0, integer: true },\n  positiveInteger: { finite: true, exclusiveMin: 0, integer: true },\n  lowerBound: { finite: true, allowInfinity: \"negative\" },\n  upperBound: { finite: true, allowInfinity: \"positive\" },\n  timer: { finite: true, min: 0, max: MAX_TIMER_DELAY_MS },\n  positiveTimer: { finite: true, exclusiveMin: 0, max: MAX_TIMER_DELAY_MS },\n} as const satisfies Record<string, NumberBounds>;\n\n/**\n * Checks all declared bounds without rounding, clamping, or coercing the input.\n * Infinity exceptions relax only finite checking; every other bound still applies.\n */\nexport function matchesNumberBounds(value: number, bounds: NumberBounds): boolean {\n  if (!Number.isFinite(value)) {\n    const direction = value === Infinity ? \"positive\" : value === -Infinity ? \"negative\" : null;\n    if (direction === null) return false;\n    if (bounds.allowInfinity !== \"both\" && bounds.allowInfinity !== direction) return false;\n  }\n  if (bounds.min !== undefined && value < bounds.min) return false;\n  if (bounds.max !== undefined && value > bounds.max) return false;\n  if (bounds.exclusiveMin !== undefined && value <= bounds.exclusiveMin) return false;\n  if (bounds.integer && !Number.isInteger(value)) return false;\n  if (bounds.allowedValues !== undefined && !bounds.allowedValues.includes(value)) return false;\n  return true;\n}\n\n/** Decodes a Number Value literal; action params use their own JSON decoder. */\nexport function decodeNumberValue(raw: string): number {\n  return Number(raw.replace(/_/g, \"\"));\n}\n","/**\n * Numeric coercion for controllers that accept a number through a Value, an action\n * param, or an event detail.\n *\n * Stimulus decodes action params as JSON when possible and leaves other text\n * untouched. CustomEvent detail can also supply a number or numeric string.\n * The reader accepts those two types while rejecting blank and non-finite input.\n */\n\nimport { matchesNumberBounds, type NumberBounds } from \"./number_bounds\";\n\n/**\n * Reads a finite number or nonblank numeric string; other input returns `null`.\n * Blank strings cannot silently reset a value to zero.\n */\nexport function toFiniteNumber(raw: unknown): number | null {\n  if (typeof raw !== \"number\" && typeof raw !== \"string\") return null;\n  if (typeof raw === \"string\" && raw.trim().length === 0) return null;\n  const value = Number(raw);\n  return Number.isFinite(value) ? value : null;\n}\n\n/**\n * Returns an accepted decoded Number Value or the caller's fallback unchanged.\n * The caller owns the fallback contract; this reader does not parse or write a Value.\n */\nexport function readNumber(raw: number, fallback: number, bounds: NumberBounds): number {\n  return matchesNumberBounds(raw, bounds) ? raw : fallback;\n}\n","import { readNumber } from \"./coerce\";\nimport { matchesNumberBounds, type NumberBounds } from \"./number_bounds\";\n\n/** The instance identity carried by a Number Value read. */\nexport interface NumberValueOwner {\n  readonly identifier: string;\n  readonly element: Element;\n}\n\n/** Reads current declarations at the point of use without rewriting their attributes. */\nexport class NumberValueReader {\n  /** The last rejected literal per Value; no history grows for an unchanged instance. */\n  readonly #lastRejected = new Map<string, string>();\n\n  /** Resolves the declared number using its own fallback and shared class contract. */\n  read(\n    owner: NumberValueOwner,\n    name: string,\n    raw: number,\n    fallback: number,\n    bounds: NumberBounds,\n  ): number {\n    const resolved = readNumber(raw, fallback, bounds);\n    if (matchesNumberBounds(raw, bounds)) {\n      this.#lastRejected.delete(name);\n      return resolved;\n    }\n    const attribute = `data-${owner.identifier}-${name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}-value`;\n    const literal = owner.element.getAttribute(attribute);\n    if (literal === null) {\n      this.#lastRejected.delete(name);\n      return resolved;\n    }\n    if (this.#lastRejected.get(name) !== literal) {\n      this.#lastRejected.set(name, literal);\n      console.warn(\n        `Stimeo UI: \"${owner.identifier}\" has an invalid number Value \"${name}\" declaration ${JSON.stringify(literal)}; using ${fallback}.`,\n      );\n    }\n    return resolved;\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { MorphRenderWatcher } from \"../utils/morph_render_watcher\";\nimport { NUMBER_BOUNDS, type NumberValueConstraints } from \"../utils/number_bounds\";\nimport { NumberValueReader } from \"../utils/number_value\";\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  /** Numeric read boundaries share one reader for this controller instance. */\n  readonly #numbers = new NumberValueReader();\n\n  static override targets = [\"step\"];\n  static override values = {\n    index: { type: Number, default: 0 },\n  };\n\n  static valueConstraints = {\n    index: NUMBER_BOUNDS.finite,\n  } satisfies NumberValueConstraints<typeof StepIndicatorController.values>;\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 MorphRenderWatcher(() => this.#render());\n\n  /** Renders the initial state from the `index` value. */\n  override connect(): void {\n    this.#repaint.observe(this.element);\n    this.#render();\n  }\n\n  /** Closes the window in which a queued repaint may still run. */\n  override disconnect(): void {\n    this.#repaint.disconnect();\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.#safeIndex);\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.#safeIndex);\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 a finite index to the live step range, or zero 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  /** Current `index` declaration resolved against its numeric contract. */\n  get #safeIndex(): number {\n    return this.#numbers.read(\n      this,\n      \"index\",\n      this.indexValue,\n      StepIndicatorController.values.index.default,\n      StepIndicatorController.valueConstraints.index,\n    );\n  }\n}\n"]}

package/dist/controllers/stepper_controller.d.ts

@@ -16,21 +16,42 @@ 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`).
+ *
+ * User `change` reports compare the resulting state with the last published
+ * state. A pending page write handled in the same script joins that confirmation;
+ * a browser-delivered listener may settle it first as `reconcile`. Confirming
+ * the last published state reports nothing.
  *
  * @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`.
  */
@@ -47,24 +68,37 @@ declare class StepperController extends Controller<HTMLElement> {
             default: boolean;
         };
     };
+    static valueConstraints: {
+        index: {
+            readonly finite: true;
+        };
+    };
     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 finite integer carried in the action's `index` param.
+     * Blank strings and nonnumeric JSON values do not select a step.
+     */
     goto(event: {
         params: {
-            index?: number;
+            index?: unknown;
         };
     }): void;
 }

package/dist/controllers/stepper_controller.js

@@ -1,77 +1,193 @@
 import { Controller } from '@hotwired/stimulus';
 
-// src/controllers/stepper_controller.ts
-var StepperController = class extends Controller {
+var NUMBER_BOUNDS = {
+  finite: { finite: true }};
+function matchesNumberBounds(value, bounds) {
+  if (!Number.isFinite(value)) {
+    const direction = value === Infinity ? "positive" : value === -Infinity ? "negative" : null;
+    if (direction === null) return false;
+    if (bounds.allowInfinity !== "both" && bounds.allowInfinity !== direction) return false;
+  }
+  if (bounds.min !== void 0 && value < bounds.min) return false;
+  if (bounds.max !== void 0 && value > bounds.max) return false;
+  if (bounds.exclusiveMin !== void 0 && value <= bounds.exclusiveMin) return false;
+  if (bounds.integer && !Number.isInteger(value)) return false;
+  if (bounds.allowedValues !== void 0 && !bounds.allowedValues.includes(value)) return false;
+  return true;
+}
+
+function toFiniteNumber(raw) {
+  if (typeof raw !== "number" && typeof raw !== "string") return null;
+  if (typeof raw === "string" && raw.trim().length === 0) return null;
+  const value = Number(raw);
+  return Number.isFinite(value) ? value : null;
+}
+function readNumber(raw, fallback, bounds) {
+  return matchesNumberBounds(raw, bounds) ? raw : fallback;
+}
+
+var ListenerSet = class {
+  #abort = new AbortController();
+  add(target, type, handler, options) {
+    target.addEventListener(type, handler, { ...options, signal: this.#abort.signal });
+  }
+  dispose() {
+    this.#abort.abort();
+    this.#abort = new AbortController();
+  }
+};
+
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  constructor(run) {
+    this.#run = run;
+  }
+  activate() {
+    this.#active = true;
+  }
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  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();
+    });
+  }
+};
+
+var MorphRenderWatcher = class {
+  #listeners = new ListenerSet();
+  #pass;
+  #element = null;
+  #onMorph = () => this.#pass.schedule();
+  constructor(run) {
+    this.#pass = new MicrotaskCoalescer(run);
+  }
+  observe(element) {
+    if (this.#element === element) return;
+    this.disconnect();
+    this.#element = element;
+    this.#pass.activate();
+    this.#listeners.add(element, "turbo:morph-element", this.#onMorph);
+  }
+  schedule() {
+    this.#pass.schedule();
+  }
+  disconnect() {
+    this.#listeners.dispose();
+    this.#pass.cancel();
+    this.#element = null;
+  }
+};
+
+var NumberValueReader = class {
+  #lastRejected = /* @__PURE__ */ new Map();
+  read(owner, name, raw, fallback, bounds) {
+    const resolved = readNumber(raw, fallback, bounds);
+    if (matchesNumberBounds(raw, bounds)) {
+      this.#lastRejected.delete(name);
+      return resolved;
+    }
+    const attribute = `data-${owner.identifier}-${name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}-value`;
+    const literal = owner.element.getAttribute(attribute);
+    if (literal === null) {
+      this.#lastRejected.delete(name);
+      return resolved;
+    }
+    if (this.#lastRejected.get(name) !== literal) {
+      this.#lastRejected.set(name, literal);
+      console.warn(
+        `Stimeo UI: "${owner.identifier}" has an invalid number Value "${name}" declaration ${JSON.stringify(literal)}; using ${fallback}.`
+      );
+    }
+    return resolved;
+  }
+};
+
+var StepperController = class _StepperController extends Controller {
+  #numbers = new NumberValueReader();
   static targets = ["step"];
   static values = {
     index: { type: Number, default: 0 },
     linear: { type: Boolean, default: false }
   };
+  static valueConstraints = {
+    index: NUMBER_BOUNDS.finite
+  };
   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"];
+  #repaint = new MorphRenderWatcher(() => this.#reconcileStep());
+  #shown = null;
   connect() {
-    this.#isConnected = true;
-    this.#normalizeAndRender();
+    this.#repaint.observe(this.element);
+    this.#shown = this.#currentStep;
+    this.#render();
   }
   disconnect() {
-    this.#isConnected = false;
+    this.#repaint.disconnect();
   }
-  /** Re-renders when Turbo Morph or application code changes `index` at runtime. */
   indexValueChanged() {
-    if (!this.#isConnected) return;
-    this.#normalizeAndRender();
+    this.#repaint.schedule();
+  }
+  stepTargetConnected() {
+    this.#repaint.schedule();
+  }
+  stepTargetDisconnected() {
+    this.#repaint.schedule();
   }
-  /** Advances to the next step (ignored at the last step). */
   next() {
-    this.#moveTo(this.#clampIndex(this.indexValue) + 1);
+    this.#moveTo(this.#clampIndex(this.#safeIndex) + 1);
   }
-  /** Returns to the previous step (ignored at the first step). */
   prev() {
-    this.#moveTo(this.#clampIndex(this.indexValue) - 1);
+    this.#moveTo(this.#clampIndex(this.#safeIndex) - 1);
   }
-  /** Jumps to the step carried in the action's `index` param. */
   goto(event) {
-    const target = Number(event.params.index);
-    if (!Number.isFinite(target) || !Number.isInteger(target)) return;
+    const { index } = event.params;
+    const target = toFiniteNumber(index);
+    if (target === null || !Number.isInteger(target)) return;
     this.#moveTo(target);
   }
-  /**
-   * Moves the current step to `target` when allowed: in range, not a no-op, and
-   * — under `linear` — not skipping more than one step ahead. Re-renders and
-   * dispatches `change`.
-   */
   #moveTo(target) {
     const total = this.stepTargets.length;
-    if (!Number.isFinite(target) || !Number.isInteger(target)) return;
     if (target < 0 || target >= total) return;
-    const current = this.#clampIndex(this.indexValue);
-    if (target === current) return;
+    const current = this.#clampIndex(this.#safeIndex);
+    if (target === current && target === this.#shown) return;
     if (this.linearValue && target > current + 1) return;
-    const previous = current;
+    const previous = this.#shown ?? current;
     this.indexValue = target;
-    this.#render(target);
+    this.#shown = target;
+    this.#render();
+    if (target === previous) return;
     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);
-  }
-  /**
-   * Derives each step's `data-state` and the current button's `aria-current`.
-   *
-   * `aria-current="step"` is placed on the step's **first** `<button>`; the markup
-   * contract assumes one operable button per step. If a step needs multiple
-   * buttons, mark the navigational one first (or this would target the wrong one).
-   *
-   * @stimeoRenderRoot
-   */
-  #render(current) {
+  #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] }
+    });
+  }
+  get #currentStep() {
+    return this.stepTargets.length > 0 ? this.#clampIndex(this.#safeIndex) : null;
+  }
+  #render() {
+    const current = this.#clampIndex(this.#safeIndex);
     this.stepTargets.forEach((step, index) => {
       step.dataset.state = index < current ? "complete" : index === current ? "current" : "upcoming";
       const button = step.querySelector("button");
@@ -83,14 +199,21 @@ var StepperController = class extends Controller {
       }
     });
   }
-  /** Constrains an index to `[0, total-1]` (or `0` when there are no steps). */
   #clampIndex(index) {
     const last = this.stepTargets.length - 1;
-    if (last < 0 || !Number.isFinite(index)) return 0;
+    if (last < 0) return 0;
     return Math.min(last, Math.max(0, Math.trunc(index)));
   }
+  get #safeIndex() {
+    return this.#numbers.read(
+      this,
+      "index",
+      this.indexValue,
+      _StepperController.values.index.default,
+      _StepperController.valueConstraints.index
+    );
+  }
 };
 
 export { StepperController };
-//# sourceMappingURL=stepper_controller.js.map
 //# sourceMappingURL=stepper_controller.js.map

package/dist/controllers/stepper_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/controllers/stepper_controller.ts"],"names":[],"mappings":";;;AAoCO,IAAM,iBAAA,GAAN,cAAgC,UAAA,CAAwB;AAAA,EAC7D,OAAgB,OAAA,GAAU,CAAC,MAAM,CAAA;AAAA,EACjC,OAAgB,MAAA,GAAS;AAAA,IACvB,KAAA,EAAO,EAAE,IAAA,EAAM,MAAA,EAAQ,SAAS,CAAA,EAAE;AAAA,IAClC,MAAA,EAAQ,EAAE,IAAA,EAAM,OAAA,EAAS,SAAS,KAAA;AAAM,GAC1C;AAAA,EACA,OAAO,OAAA,GAAU,CAAC,MAAA,EAAQ,QAAQ,MAAM,CAAA;AAAA,EACxC,OAAO,MAAA,GAAS,CAAC,QAAQ,CAAA;AAAA,EAMzB,YAAA,GAAe,KAAA;AAAA;AAAA,EAGN,OAAA,GAAgB;AACvB,IAAA,IAAA,CAAK,YAAA,GAAe,IAAA;AACpB,IAAA,IAAA,CAAK,mBAAA,EAAoB;AAAA,EAC3B;AAAA,EAES,UAAA,GAAmB;AAC1B,IAAA,IAAA,CAAK,YAAA,GAAe,KAAA;AAAA,EACtB;AAAA;AAAA,EAGA,iBAAA,GAA0B;AACxB,IAAA,IAAI,CAAC,KAAK,YAAA,EAAc;AACxB,IAAA,IAAA,CAAK,mBAAA,EAAoB;AAAA,EAC3B;AAAA;AAAA,EAGA,IAAA,GAAa;AACX,IAAA,IAAA,CAAK,QAAQ,IAAA,CAAK,WAAA,CAAY,IAAA,CAAK,UAAU,IAAI,CAAC,CAAA;AAAA,EACpD;AAAA;AAAA,EAGA,IAAA,GAAa;AACX,IAAA,IAAA,CAAK,QAAQ,IAAA,CAAK,WAAA,CAAY,IAAA,CAAK,UAAU,IAAI,CAAC,CAAA;AAAA,EACpD;AAAA;AAAA,EAGA,KAAK,KAAA,EAA6C;AAChD,IAAA,MAAM,MAAA,GAAS,MAAA,CAAO,KAAA,CAAM,MAAA,CAAO,KAAK,CAAA;AACxC,IAAA,IAAI,CAAC,OAAO,QAAA,CAAS,MAAM,KAAK,CAAC,MAAA,CAAO,SAAA,CAAU,MAAM,CAAA,EAAG;AAC3D,IAAA,IAAA,CAAK,QAAQ,MAAM,CAAA;AAAA,EACrB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,QAAQ,MAAA,EAAsB;AAC5B,IAAA,MAAM,KAAA,GAAQ,KAAK,WAAA,CAAY,MAAA;AAC/B,IAAA,IAAI,CAAC,OAAO,QAAA,CAAS,MAAM,KAAK,CAAC,MAAA,CAAO,SAAA,CAAU,MAAM,CAAA,EAAG;AAC3D,IAAA,IAAI,MAAA,GAAS,CAAA,IAAK,MAAA,IAAU,KAAA,EAAO;AACnC,IAAA,MAAM,OAAA,GAAU,IAAA,CAAK,WAAA,CAAY,IAAA,CAAK,UAAU,CAAA;AAChD,IAAA,IAAI,WAAW,OAAA,EAAS;AACxB,IAAA,IAAI,IAAA,CAAK,WAAA,IAAe,MAAA,GAAS,OAAA,GAAU,CAAA,EAAG;AAE9C,IAAA,MAAM,QAAA,GAAW,OAAA;AACjB,IAAA,IAAA,CAAK,UAAA,GAAa,MAAA;AAClB,IAAA,IAAA,CAAK,QAAQ,MAAM,CAAA;AACnB,IAAA,IAAA,CAAK,SAAS,QAAA,EAAU;AAAA,MACtB,MAAA,EAAQ,EAAE,KAAA,EAAO,MAAA,EAAQ,UAAU,IAAA,EAAM,IAAA,CAAK,WAAA,CAAY,MAAM,CAAA;AAAE,KACnE,CAAA;AAAA,EACH;AAAA;AAAA,EAGA,mBAAA,GAA4B;AAC1B,IAAA,MAAM,UAAA,GAAa,IAAA,CAAK,WAAA,CAAY,IAAA,CAAK,UAAU,CAAA;AACnD,IAAA,IAAI,CAAC,OAAO,EAAA,CAAG,UAAA,EAAY,KAAK,UAAU,CAAA,OAAQ,UAAA,GAAa,UAAA;AAC/D,IAAA,IAAA,CAAK,QAAQ,UAAU,CAAA;AAAA,EACzB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,QAAQ,OAAA,EAAuB;AAC7B,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,MAAM,MAAA,GAAS,IAAA,CAAK,aAAA,CAA2B,QAAQ,CAAA;AACvD,MAAA,IAAI,CAAC,MAAA,EAAQ;AACb,MAAA,IAAI,UAAU,OAAA,EAAS;AACrB,QAAA,MAAA,CAAO,YAAA,CAAa,gBAAgB,MAAM,CAAA;AAAA,MAC5C,CAAA,MAAO;AACL,QAAA,MAAA,CAAO,gBAAgB,cAAc,CAAA;AAAA,MACvC;AAAA,IACF,CAAC,CAAA;AAAA,EACH;AAAA;AAAA,EAGA,YAAY,KAAA,EAAuB;AACjC,IAAA,MAAM,IAAA,GAAO,IAAA,CAAK,WAAA,CAAY,MAAA,GAAS,CAAA;AACvC,IAAA,IAAI,OAAO,CAAA,IAAK,CAAC,OAAO,QAAA,CAAS,KAAK,GAAG,OAAO,CAAA;AAChD,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":"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/number_bounds.ts","../../src/utils/coerce.ts","../../src/utils/listener_set.ts","../../src/utils/microtask_coalescer.ts","../../src/utils/morph_render_watcher.ts","../../src/utils/number_value.ts","../../src/controllers/stepper_controller.ts"],"names":[],"mappings":"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","file":"stepper_controller.js","sourcesContent":["import { MAX_TIMER_DELAY_MS } from \"./timer_bounds\";\n\n/** Semantic constraints on an already decoded number, independent of the DOM. */\nexport interface NumberBounds {\n  /** Finite numbers are required, including when this field is omitted. */\n  readonly finite?: true;\n  /** Inclusive lower endpoint. */\n  readonly min?: number;\n  /** Inclusive upper endpoint. */\n  readonly max?: number;\n  /** Exclusive lower endpoint. */\n  readonly exclusiveMin?: number;\n  /** Require a number without a fractional part. */\n  readonly integer?: boolean;\n  /** Exact decoded numbers accepted by a discrete contract. */\n  readonly allowedValues?: readonly number[];\n  /** JSON-safe exceptions to finite-number checking for unbounded endpoints. */\n  readonly allowInfinity?: \"negative\" | \"positive\" | \"both\";\n}\n\n/** One constraint for each Number Value, including shorthand declarations. */\nexport type NumberValueConstraints<Values> = {\n  readonly [Key in keyof Values as Values[Key] extends\n    | NumberConstructor\n    | { type: NumberConstructor }\n    ? Key\n    : never]: NumberBounds;\n};\n\n/** Reusable semantic domains; fractional inputs remain fractional unless excluded. */\nexport const NUMBER_BOUNDS = {\n  finite: { finite: true },\n  nonNegative: { finite: true, min: 0 },\n  positive: { finite: true, exclusiveMin: 0 },\n  nonNegativeInteger: { finite: true, min: 0, integer: true },\n  positiveInteger: { finite: true, exclusiveMin: 0, integer: true },\n  lowerBound: { finite: true, allowInfinity: \"negative\" },\n  upperBound: { finite: true, allowInfinity: \"positive\" },\n  timer: { finite: true, min: 0, max: MAX_TIMER_DELAY_MS },\n  positiveTimer: { finite: true, exclusiveMin: 0, max: MAX_TIMER_DELAY_MS },\n} as const satisfies Record<string, NumberBounds>;\n\n/**\n * Checks all declared bounds without rounding, clamping, or coercing the input.\n * Infinity exceptions relax only finite checking; every other bound still applies.\n */\nexport function matchesNumberBounds(value: number, bounds: NumberBounds): boolean {\n  if (!Number.isFinite(value)) {\n    const direction = value === Infinity ? \"positive\" : value === -Infinity ? \"negative\" : null;\n    if (direction === null) return false;\n    if (bounds.allowInfinity !== \"both\" && bounds.allowInfinity !== direction) return false;\n  }\n  if (bounds.min !== undefined && value < bounds.min) return false;\n  if (bounds.max !== undefined && value > bounds.max) return false;\n  if (bounds.exclusiveMin !== undefined && value <= bounds.exclusiveMin) return false;\n  if (bounds.integer && !Number.isInteger(value)) return false;\n  if (bounds.allowedValues !== undefined && !bounds.allowedValues.includes(value)) return false;\n  return true;\n}\n\n/** Decodes a Number Value literal; action params use their own JSON decoder. */\nexport function decodeNumberValue(raw: string): number {\n  return Number(raw.replace(/_/g, \"\"));\n}\n","/**\n * Numeric coercion for controllers that accept a number through a Value, an action\n * param, or an event detail.\n *\n * Stimulus decodes action params as JSON when possible and leaves other text\n * untouched. CustomEvent detail can also supply a number or numeric string.\n * The reader accepts those two types while rejecting blank and non-finite input.\n */\n\nimport { matchesNumberBounds, type NumberBounds } from \"./number_bounds\";\n\n/**\n * Reads a finite number or nonblank numeric string; other input returns `null`.\n * Blank strings cannot silently reset a value to zero.\n */\nexport function toFiniteNumber(raw: unknown): number | null {\n  if (typeof raw !== \"number\" && typeof raw !== \"string\") return null;\n  if (typeof raw === \"string\" && raw.trim().length === 0) return null;\n  const value = Number(raw);\n  return Number.isFinite(value) ? value : null;\n}\n\n/**\n * Returns an accepted decoded Number Value or the caller's fallback unchanged.\n * The caller owns the fallback contract; this reader does not parse or write a Value.\n */\nexport function readNumber(raw: number, fallback: number, bounds: NumberBounds): number {\n  return matchesNumberBounds(raw, bounds) ? raw : fallback;\n}\n","/**\n * Owns every listener a controller attaches for one connected lifetime and\n * releases them together, so an event name is spelled once and the release\n * cannot drift from the registration.\n *\n * Detaching by hand repeats three things at the release site — the type, the\n * handler reference and the capture flag — and any one of them drifting leaves\n * a listener alive on an element the controller no longer drives. Aborting the\n * signal a registration was created with releases it whatever it was made of,\n * so the release site names nothing.\n *\n * One set per lifetime, held as a field and never rebuilt. {@link\n * ListenerSet.dispose} is the only thing that closes a generation, and it opens\n * the next one in the same step, so the lifecycle hooks can call `add` and\n * `dispose` in any order any number of times, and no `add` ever meets an\n * already aborted signal — a DOM that registers a listener on such a signal\n * would keep it forever. Rebuilding the set instead would leak:\n * `addEventListener` matches an existing registration on target, type, callback\n * and capture alone, so re-adding the same handler while the first registration\n * is live is discarded, and that live registration keeps the signal it was\n * attached with — a set built by a second `connect()` can never release what it\n * appears to own.\n *\n * Scope is the registration only. Timers, observers, leases and the order they\n * are unwound in stay with the controller, which places `dispose()` in its\n * cleanup sequence. A receiver that changes at runtime (a\n * swapped target) is rebound by calling `dispose()` and then `add()` again from\n * the rebind, not by a second set.\n *\n * The set must own every registration of a tuple it holds: a listener the same\n * target already carries for the same type, callback and capture flag keeps the\n * right to remove it, and this set's `add` for that tuple is discarded. A\n * subscription shared between instances behind a participant count, or one that\n * lives for less than the connection, keeps its own pair of calls.\n *\n * @example\n * ```ts\n * readonly #listeners = new ListenerSet();\n *\n * connect(): void {\n *   this.#listeners.add(this.element, \"submit\", this.#onNativeSubmit, { capture: true });\n *   this.#listeners.add(this.element, \"turbo:submit-start\", this.#onSubmitStart);\n *   this.#listeners.add(this.element, \"turbo:submit-end\", this.#onSubmitEnd);\n * }\n *\n * disconnect(): void {\n *   this.#listeners.dispose();\n * }\n * ```\n */\nexport class ListenerSet {\n  /** The generation every `add` joins until the next `dispose()`. */\n  #abort = new AbortController();\n\n  /**\n   * Attaches `handler` to the open generation, exactly as the caller spelled it.\n   *\n   * The set supplies the signal, so `options` carries everything else the DOM\n   * accepts — `capture` included, which has to match at release time and no\n   * longer has a second place to drift from.\n   */\n  add(\n    target: EventTarget,\n    type: string,\n    handler: EventListener,\n    options?: Omit<AddEventListenerOptions, \"signal\">,\n  ): void {\n    target.addEventListener(type, handler, { ...options, signal: this.#abort.signal });\n  }\n\n  /**\n   * Releases every listener of the open generation, synchronously, and opens the\n   * next one. Idempotent, and safe before anything has been added.\n   */\n  dispose(): void {\n    this.#abort.abort();\n    this.#abort = new AbortController();\n  }\n}\n","/**\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 * @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 { ListenerSet } from \"./listener_set\";\nimport { MicrotaskCoalescer } from \"./microtask_coalescer\";\n\n/**\n * Coalesces retained-element morphs and explicit lifecycle requests into one pass.\n *\n * Observe the controller's element after its initial state is settled. Morphs on\n * that element and bubbling morphs on its descendants share the same microtask\n * as {@link schedule}. The callback repairs derived output; the controller owns\n * any logical transition reporting. {@link disconnect} releases the listener and\n * cancels pending work, including work from an earlier connected lifetime.\n */\nexport class MorphRenderWatcher {\n  readonly #listeners = new ListenerSet();\n  readonly #pass: MicrotaskCoalescer;\n  #element: Element | null = null;\n  readonly #onMorph = (): void => this.#pass.schedule();\n\n  /** @param run - the single pass that repairs the settled controller's output. */\n  constructor(run: () => void) {\n    this.#pass = new MicrotaskCoalescer(run);\n  }\n\n  /** Opens observation; observing the same element again preserves queued work. */\n  observe(element: Element): void {\n    if (this.#element === element) return;\n    this.disconnect();\n    this.#element = element;\n    this.#pass.activate();\n    this.#listeners.add(element, \"turbo:morph-element\", this.#onMorph);\n  }\n\n  /** Requests one pass; requests outside an observed lifetime are ignored. */\n  schedule(): void {\n    this.#pass.schedule();\n  }\n\n  /** Releases observation and pending work synchronously; safe to repeat. */\n  disconnect(): void {\n    this.#listeners.dispose();\n    this.#pass.cancel();\n    this.#element = null;\n  }\n}\n","import { readNumber } from \"./coerce\";\nimport { matchesNumberBounds, type NumberBounds } from \"./number_bounds\";\n\n/** The instance identity carried by a Number Value read. */\nexport interface NumberValueOwner {\n  readonly identifier: string;\n  readonly element: Element;\n}\n\n/** Reads current declarations at the point of use without rewriting their attributes. */\nexport class NumberValueReader {\n  /** The last rejected literal per Value; no history grows for an unchanged instance. */\n  readonly #lastRejected = new Map<string, string>();\n\n  /** Resolves the declared number using its own fallback and shared class contract. */\n  read(\n    owner: NumberValueOwner,\n    name: string,\n    raw: number,\n    fallback: number,\n    bounds: NumberBounds,\n  ): number {\n    const resolved = readNumber(raw, fallback, bounds);\n    if (matchesNumberBounds(raw, bounds)) {\n      this.#lastRejected.delete(name);\n      return resolved;\n    }\n    const attribute = `data-${owner.identifier}-${name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}-value`;\n    const literal = owner.element.getAttribute(attribute);\n    if (literal === null) {\n      this.#lastRejected.delete(name);\n      return resolved;\n    }\n    if (this.#lastRejected.get(name) !== literal) {\n      this.#lastRejected.set(name, literal);\n      console.warn(\n        `Stimeo UI: \"${owner.identifier}\" has an invalid number Value \"${name}\" declaration ${JSON.stringify(literal)}; using ${fallback}.`,\n      );\n    }\n    return resolved;\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { toFiniteNumber } from \"../utils/coerce\";\nimport { MorphRenderWatcher } from \"../utils/morph_render_watcher\";\nimport { NUMBER_BOUNDS, type NumberValueConstraints } from \"../utils/number_bounds\";\nimport { NumberValueReader } from \"../utils/number_value\";\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 * User `change` reports compare the resulting state with the last published\n * state. A pending page write handled in the same script joins that confirmation;\n * a browser-delivered listener may settle it first as `reconcile`. Confirming\n * the last published state reports nothing.\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  /** Numeric read boundaries share one reader for this controller instance. */\n  readonly #numbers = new NumberValueReader();\n\n  static override targets = [\"step\"];\n  static override values = {\n    index: { type: Number, default: 0 },\n    linear: { type: Boolean, default: false },\n  };\n\n  static valueConstraints = {\n    index: NUMBER_BOUNDS.finite,\n  } satisfies NumberValueConstraints<typeof StepperController.values>;\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 MorphRenderWatcher(() => 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.observe(this.element);\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.disconnect();\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.#safeIndex) + 1);\n  }\n\n  /** Returns to the previous step (ignored at the first step). */\n  prev(): void {\n    this.#moveTo(this.#clampIndex(this.#safeIndex) - 1);\n  }\n\n  /**\n   * Jumps to the finite integer carried in the action's `index` param.\n   * Blank strings and nonnumeric JSON values do not select a step.\n   */\n  goto(event: { params: { index?: unknown } }): void {\n    const { index } = event.params;\n    const target = toFiniteNumber(index);\n    if (target === null || !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 (target < 0 || target >= total) return;\n    const current = this.#clampIndex(this.#safeIndex);\n    if (target === current && target === this.#shown) return;\n    if (this.linearValue && target > current + 1) return;\n\n    const previous = this.#shown ?? 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    if (target === previous) return;\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.#safeIndex) : 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.#safeIndex);\n    this.stepTargets.forEach((step, index) => {\n      step.dataset.state =\n        index < current ? \"complete\" : index === current ? \"current\" : \"upcoming\";\n      const button = step.querySelector<HTMLElement>(\"button\");\n      if (!button) return;\n      if (index === current) {\n        button.setAttribute(\"aria-current\", \"step\");\n      } else {\n        button.removeAttribute(\"aria-current\");\n      }\n    });\n  }\n\n  /** Constrains an index to `[0, total-1]` (or `0` when there are no steps). */\n  #clampIndex(index: number): number {\n    const last = this.stepTargets.length - 1;\n    if (last < 0) return 0;\n    return Math.min(last, Math.max(0, Math.trunc(index)));\n  }\n  /** Current `index` declaration resolved against its numeric contract. */\n  get #safeIndex(): number {\n    return this.#numbers.read(\n      this,\n      \"index\",\n      this.indexValue,\n      StepperController.values.index.default,\n      StepperController.valueConstraints.index,\n    );\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:
@@ -68,10 +76,17 @@ declare class StickToBottomController extends Controller<HTMLElement> {
             default: boolean;
         };
     };
+    static valueConstraints: {
+        threshold: {
+            readonly finite: true;
+            readonly min: 0;
+        };
+    };
     static actions: readonly ["scrollToBottom"];
     static events: readonly ["pin", "new"];
     readonly contentTarget: HTMLElement;
     readonly hasContentTarget: boolean;
+    readonly hasNewTargets: HTMLElement[];
     thresholdValue: number;
     behaviorValue: string;
     pinOnConnectValue: boolean;
@@ -81,6 +96,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).