stimeo-ui 0.4.0 → 0.6.0

package/dist/controllers/roving_controller.js

@@ -13,6 +13,39 @@ function isReservedArrowChord(event, allow = []) {
   return event.altKey && !allow.includes("alt") || event.ctrlKey && !allow.includes("ctrl") || event.metaKey && !allow.includes("meta") || event.shiftKey && !allow.includes("shift");
 }
 
+// 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/utils/roving_tabindex.ts
 var RovingTabindex = class {
   /** Returns the current ordered item elements; called on every operation. */
@@ -35,10 +68,12 @@ var RovingTabindex = class {
    * "nothing is currently tabbable".
    *
    * @param index - Position of the item to make tabbable.
-   * @param options - Pass `{ focus: true }` to also move DOM focus to that item.
+   * @param options - Pass `{ focus: true }` to also move DOM focus to that item,
+   *   and `items` to reuse an event-scoped collection snapshot.
    */
-  setActive(index, { focus = false } = {}) {
-    const items = this.#getItems();
+  setActive(index, options = {}) {
+    const { focus = false } = options;
+    const items = options.items ?? this.#getItems();
     items.forEach((item, i) => {
       item.tabIndex = i === index ? 0 : -1;
     });
@@ -62,16 +97,31 @@ var RovingController = class extends Controller {
   };
   static events = ["change"];
   #roving = new RovingTabindex(() => this.itemTargets);
+  #reconcile = new MicrotaskCoalescer(() => this.#ensureTabStop());
+  #connected = false;
   connect() {
-    const active = this.#roving.activeIndex;
-    this.#roving.setActive(active === -1 ? 0 : active);
+    this.#ensureTabStop();
     this.element.addEventListener("keydown", this.#onKeydown);
     this.element.addEventListener("focusin", this.#onFocusin);
+    this.#connected = true;
+    this.#reconcile.activate();
   }
   disconnect() {
+    this.#connected = false;
+    this.#reconcile.cancel();
     this.element.removeEventListener("keydown", this.#onKeydown);
     this.element.removeEventListener("focusin", this.#onFocusin);
   }
+  /** Drops a runtime-added item from the Tab sequence before batch reconciliation. */
+  itemTargetConnected(item) {
+    if (!this.#connected) return;
+    item.tabIndex = -1;
+    this.#reconcile.schedule();
+  }
+  /** Re-establishes the single Tab stop after an item leaves the target set. */
+  itemTargetDisconnected() {
+    this.#reconcile.schedule();
+  }
   /** Arrow keys move focus + the tab stop; Home/End jump to the ends. */
   #onKeydown = (event) => {
     if (event.defaultPrevented) return;
@@ -125,6 +175,11 @@ var RovingController = class extends Controller {
       this.dispatch("change", { detail: { index, item: this.itemTargets[index] } });
     }
   }
+  /** Keeps the first existing Tab stop, falling back to the first live item. */
+  #ensureTabStop() {
+    const active = this.#roving.activeIndex;
+    this.#roving.setActive(active === -1 ? 0 : active);
+  }
 };
 
 export { RovingController };

package/dist/controllers/roving_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/logical_scroll.ts","../../src/utils/arrow_step.ts","../../src/utils/roving_tabindex.ts","../../src/controllers/roving_controller.ts"],"names":[],"mappings":"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","file":"roving_controller.js","sourcesContent":["/** Normalized scroll position and maximum distance on one logical axis. */\nexport interface LogicalScrollMetrics {\n  position: number;\n  max: number;\n}\n\n/**\n * Whether horizontal scrolling on `element` follows right-to-left inline flow.\n *\n * Resolved from the **computed** `direction`, so the authoring contract is the\n * usual `dir=\"rtl\"` (or a stylesheet) on the element or any ancestor.\n *\n * Scope: horizontal writing modes. A vertical writing mode (`writing-mode:\n * vertical-rl`) also inverts the horizontal axis, which this check does not\n * model — vertical writing modes are out of scope for the scroll utilities\n * (their consumers describe axes as horizontal/vertical, not inline/block).\n */\nexport function isRtl(element: Element): boolean {\n  return window.getComputedStyle(element).direction === \"rtl\";\n}\n\n/**\n * Returns scroll distance from the logical start edge.\n *\n * CSSOM View exposes standards-mode RTL horizontal offsets as `0` at the inline\n * start (right) and increasingly negative values toward the inline end (left).\n * The normalized position is always clamped to `[0, max]`, which also absorbs\n * Safari's elastic overscroll values.\n */\nexport function logicalScrollMetrics(\n  element: HTMLElement,\n  horizontal: boolean,\n): LogicalScrollMetrics {\n  const max = Math.max(\n    0,\n    horizontal\n      ? element.scrollWidth - element.clientWidth\n      : element.scrollHeight - element.clientHeight,\n  );\n  const raw = horizontal ? element.scrollLeft : element.scrollTop;\n  const position = horizontal && isRtl(element) ? -raw : raw;\n  return { position: Math.min(max, Math.max(0, position)), max };\n}\n\n/**\n * Converts a logical start/end delta to the physical value accepted by\n * `Element.scrollBy`.\n */\nexport function physicalScrollDelta(\n  element: HTMLElement,\n  horizontal: boolean,\n  logicalDelta: number,\n): number {\n  return horizontal && isRtl(element) ? -logicalDelta : logicalDelta;\n}\n","import { isRtl } from \"./logical_scroll\";\n\n/**\n * Turns an arrow key into a **logical** step: `+1` for \"next\", `-1` for\n * \"previous\", `0` when the key names neither.\n *\n * APG defines the horizontal pair as *next / previous* and says a vertical\n * arrangement swaps in Down/Up for the same meaning — so the pair is one axis's\n * spelling of an order, and the order reverses with the writing direction. Only\n * the horizontal pair reverses. Down/Up name an axis the writing direction does\n * not mirror, and returning them unchanged is the point: many controllers fold\n * both pairs into one branch, where swapping the branches under RTL would flip\n * the vertical axis too — a bug that reads as \"the arrows work\" until someone\n * presses Down.\n *\n * **Direction is read from the element the caller passes, which should be the\n * container that lays the items out** — not the focused child. A child may carry\n * its own `dir` (an LTR input inside an RTL form is ordinary authoring), and\n * probing per handler makes two handlers disagree at the boundary between them.\n *\n * This decides direction only. Whether the axis is even active (an\n * `orientation=\"horizontal\"` widget ignoring Down/Up), how far the step lands,\n * and what wrapping does all stay with the caller.\n *\n * **It encodes the list-order convention: `ArrowDown` is *next*.** Widgets that\n * pair the arrows by *value* instead — `ArrowUp` meaning \"more\", as a rating or a\n * slider does — must not use this, or their vertical axis inverts. Reverse the\n * horizontal pair on its own there.\n *\n * @example\n * ```ts\n * const step = logicalArrowStep(event.key, this.element);\n * if (step === 0) return;\n * this.#roving.setActive(rovingMove(current, length, step, \"wrap\"), { focus: true });\n * ```\n */\nexport function logicalArrowStep(key: string, element: Element): 1 | -1 | 0 {\n  if (key === \"ArrowDown\") return 1;\n  if (key === \"ArrowUp\") return -1;\n  if (key !== \"ArrowRight\" && key !== \"ArrowLeft\") return 0;\n  const forward = isRtl(element) ? \"ArrowLeft\" : \"ArrowRight\";\n  return key === forward ? 1 : -1;\n}\n\n/**\n * Rewrites `key` so an existing LTR-shaped branch keeps working under RTL:\n * `ArrowRight` and `ArrowLeft` trade places, everything else passes through.\n *\n * The alternative — negating a delta — silently breaks handlers whose two\n * horizontal branches are **not mirror images**. A grid that clamps one edge but\n * not the other, or a segmented field guarding `index > 0` on one side and\n * `index < length - 1` on the other, ends up applying the wrong guard to the\n * wrong direction. Swapping the key leaves each branch, guards and all, exactly\n * where its author put it.\n *\n * Same rule as {@link logicalArrowStep} about which element to read: pass the\n * container that lays the items out, not the focused child.\n *\n * @example\n * ```ts\n * switch (logicalArrowKey(event.key, this.element)) {\n *   case \"ArrowLeft\": // \"previous\" — whatever direction that is on screen\n * ```\n */\nexport function logicalArrowKey(key: string, element: Element): string {\n  if (key !== \"ArrowRight\" && key !== \"ArrowLeft\") return key;\n  if (!isRtl(element)) return key;\n  return key === \"ArrowRight\" ? \"ArrowLeft\" : \"ArrowRight\";\n}\n\n/** Modifiers a widget may claim on an arrow key, named for the `allow` list. */\nexport type ArrowModifier = \"alt\" | \"ctrl\" | \"meta\" | \"shift\";\n\n/**\n * True when an arrow key arrived carrying a modifier the widget must leave to\n * the browser: return without calling `preventDefault()` and without moving any\n * state.\n *\n * A bare arrow belongs to the widget; a chorded one usually does not.\n * `Alt`/`Meta` plus a horizontal arrow is history back/forward on every desktop\n * browser, and a widget that swallows it makes the shortcut work or not\n * depending on where focus happens to sit — a coin-flip the user cannot see.\n *\n * `allow` is for the combinations APG assigns to a pattern **and the widget\n * actually implements** — today only Combobox's optional `Alt+Down`/`Alt+Up`.\n * Listing one the widget does not implement defeats the point: the chord then\n * runs the plain-arrow branch, which is exactly what this guard exists to stop.\n * Non-arrow keys return `false`, so chorded letters and\n * `Control+Home`/`Control+End` are untouched.\n *\n * @example\n * ```ts\n * if (isReservedArrowChord(event)) return;\n * ```\n */\nexport function isReservedArrowChord(\n  event: KeyboardEvent,\n  allow: readonly ArrowModifier[] = [],\n): boolean {\n  if (!event.key.startsWith(\"Arrow\")) return false;\n  return (\n    (event.altKey && !allow.includes(\"alt\")) ||\n    (event.ctrlKey && !allow.includes(\"ctrl\")) ||\n    (event.metaKey && !allow.includes(\"meta\")) ||\n    (event.shiftKey && !allow.includes(\"shift\"))\n  );\n}\n","/**\n * Low-level roving-tabindex primitive shared by composite-widget controllers.\n *\n * The APG roving-tabindex pattern keeps a composite widget a single Tab stop:\n * exactly one item is in the Tab sequence (`tabindex=\"0\"`) while the rest are\n * removed from it (`tabindex=\"-1\"`), and the arrow keys move both DOM focus and\n * that single tabbable position together. {@link RovingTabindex} owns *only* that\n * mechanical bookkeeping — \"which one item is tabbable, and move focus there\".\n *\n * It is intentionally **policy-free**. Orientation, wrapping vs. clamping,\n * selection-follows-focus, typeahead, and `Home`/`End` semantics differ per APG\n * pattern (Radio Group, Toolbar, Rating, …); folding them into one helper would\n * flatten those widgets to a lowest common denominator and lose each pattern's\n * correctness. Those decisions therefore stay in each controller, which calls\n * {@link RovingTabindex.setActive} with an index it computed itself (optionally\n * via the pure {@link rovingMove} helper).\n *\n * @remarks\n * Items are read lazily through a getter so a controller can add or remove\n * targets (Stimulus re-scans the DOM) without re-wiring this helper.\n */\nexport class RovingTabindex {\n  /** Returns the current ordered item elements; called on every operation. */\n  readonly #getItems: () => HTMLElement[];\n\n  /**\n   * @param getItems - Returns the current ordered item elements. Called on every\n   *   operation so the live target list is always used.\n   */\n  constructor(getItems: () => HTMLElement[]) {\n    this.#getItems = getItems;\n  }\n\n  /** Index of the currently tabbable item (`tabindex=\"0\"`), or `-1` if none. */\n  get activeIndex(): number {\n    return this.#getItems().findIndex((item) => item.tabIndex === 0);\n  }\n\n  /**\n   * Makes exactly the item at `index` tabbable (`tabindex=\"0\"`) and removes every\n   * other item from the Tab sequence (`tabindex=\"-1\"`). An out-of-range `index`\n   * (e.g. `-1`) leaves all items at `-1`, which a controller can use to express\n   * \"nothing is currently tabbable\".\n   *\n   * @param index - Position of the item to make tabbable.\n   * @param options - Pass `{ focus: true }` to also move DOM focus to that item.\n   */\n  setActive(index: number, { focus = false }: { focus?: boolean } = {}): void {\n    const items = this.#getItems();\n    items.forEach((item, i) => {\n      item.tabIndex = i === index ? 0 : -1;\n    });\n    if (focus) items[index]?.focus();\n  }\n}\n\n/** Edge behavior for {@link rovingMove}: cycle past the ends, or stop at them. */\nexport type RovingWrap = \"wrap\" | \"clamp\";\n\n/**\n * Pure helper that resolves the target index for a one-step directional move.\n *\n * Keyboard/orientation mapping stays in the caller: it decides that a key means\n * `delta` `+1` (next) or `-1` (previous) and whether the widget should `\"wrap\"`\n * (Radio Group, Toolbar) or `\"clamp\"` at the ends.\n *\n * @param current - The index focus is moving from.\n * @param length - Number of items in the set.\n * @param delta - `+1` to move to the next item, `-1` for the previous.\n * @param wrap - `\"wrap\"` cycles around the ends; `\"clamp\"` stops at them.\n * @returns The resolved index, or `-1` when there are no items.\n */\nexport function rovingMove(\n  current: number,\n  length: number,\n  delta: number,\n  wrap: RovingWrap,\n): number {\n  if (length === 0) return -1;\n  const next = current + delta;\n  if (wrap === \"wrap\") return (next + length) % length;\n  return Math.min(length - 1, Math.max(0, next));\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { isReservedArrowChord } from \"../utils/arrow_step\";\nimport { isRtl } from \"../utils/logical_scroll\";\nimport { RovingTabindex, type RovingWrap, rovingMove } from \"../utils/roving_tabindex\";\n\n/**\n * Headless **roving tabindex**: makes a set of `item`s a single Tab stop and\n * moves focus between them with the arrow keys — the APG roving-tabindex\n * technique, surfaced as a standalone controller. It is the policy layer over the\n * shared {@link RovingTabindex} util (counterpart to Focus Scope over `FocusTrap`),\n * giving the orientation / wrap / Home-End the util deliberately leaves out. No\n * dedicated APG pattern; it is the keyboard primitive Toolbar / Menu / Radio Group\n * and friends build on. Core (zero dependencies).\n *\n * Markup contract (identifier: `stimeo--roving`):\n *   <div data-controller=\"stimeo--roving\"\n *        data-stimeo--roving-orientation-value=\"horizontal\">\n *     <button data-stimeo--roving-target=\"item\">A</button>\n *     <button data-stimeo--roving-target=\"item\">B</button>\n *     <button data-stimeo--roving-target=\"item\">C</button>\n *   </div>\n *\n * Exactly one item is tabbable (`tabindex=\"0\"`); the arrow keys (per\n * `orientation`) move focus and that tab stop together, `Home`/`End` jump to the\n * ends (`homeEnd`), and `wrap` cycles past the ends or clamps at them. Listeners\n * are **delegated on the container** — `keydown` for movement and `focusin` to\n * sync the tab stop when focus arrives by click or programmatically — so\n * dynamically added/removed items need no per-item `data-action`. It emits\n * `change` whenever the tabbable item changes.\n *\n * @remarks\n * Behavior only: it owns `tabindex` and focus movement, nothing else. It does\n * **not** assign roles (`role=\"toolbar\"`/`\"radiogroup\"` is the author's), manage\n * selection / selection-follows-focus, typeahead, or activation (`Enter`/`Space`)\n * — those stay with the consuming pattern. `connect()` is idempotent: it keeps an\n * existing tab stop (reads it back from the DOM) and only defaults to the first\n * item when none is set, so a Turbo cache restore / morph never resets the user's\n * position. The delegated listeners are torn down on `disconnect()`.\n */\nexport class RovingController extends Controller<HTMLElement> {\n  static override targets = [\"item\"];\n  static override values = {\n    orientation: { type: String, default: \"horizontal\" },\n    wrap: { type: Boolean, default: true },\n    homeEnd: { type: Boolean, default: true },\n  };\n  static events = [\"change\"] as const;\n\n  declare readonly itemTargets: HTMLElement[];\n  declare orientationValue: string;\n  declare wrapValue: boolean;\n  declare homeEndValue: boolean;\n\n  readonly #roving = new RovingTabindex(() => this.itemTargets);\n\n  override connect(): void {\n    // Establish the single tab stop from the DOM (source of truth): keep an\n    // existing tabbable item, else default to the first. Silent — no change event\n    // for the initial mount.\n    const active = this.#roving.activeIndex;\n    this.#roving.setActive(active === -1 ? 0 : active);\n    this.element.addEventListener(\"keydown\", this.#onKeydown);\n    this.element.addEventListener(\"focusin\", this.#onFocusin);\n  }\n\n  override disconnect(): void {\n    this.element.removeEventListener(\"keydown\", this.#onKeydown);\n    this.element.removeEventListener(\"focusin\", this.#onFocusin);\n  }\n\n  /** Arrow keys move focus + the tab stop; Home/End jump to the ends. */\n  readonly #onKeydown = (event: KeyboardEvent): void => {\n    // A descendant widget that already claimed the key (e.g. a grabbed\n    // `stimeo--pointer-drag` handle consuming arrows to move an item) must not\n    // ALSO move the roving focus — composition depends on this yield.\n    if (event.defaultPrevented) return;\n    if (isReservedArrowChord(event)) return;\n    const items = this.itemTargets;\n    const current = this.#indexOf(event.target);\n    if (current === -1) return;\n\n    const length = items.length;\n    const wrap: RovingWrap = this.wrapValue ? \"wrap\" : \"clamp\";\n    const orientation = this.orientationValue;\n    const horizontal = orientation === \"horizontal\" || orientation === \"both\";\n    const vertical = orientation === \"vertical\" || orientation === \"both\";\n\n    // Logical, not physical. APG defines these as \"next / previous\n    // control\", and says a vertical arrangement swaps in Down/Up for the same\n    // meaning — so the pair is one axis's spelling of an order, and the order\n    // reverses with the writing direction. Read from the controller element: the\n    // container is what lays the items out, and a child may carry its own `dir`\n    // (an LTR input inside an RTL form is ordinary authoring).\n    // Only the horizontal pair reverses; `orientation=\"both\"` keeps Down/Up as-is.\n    const rtl = horizontal && isRtl(this.element);\n    const forwardKey = rtl ? \"ArrowLeft\" : \"ArrowRight\";\n    const backwardKey = rtl ? \"ArrowRight\" : \"ArrowLeft\";\n\n    let next: number;\n    if ((horizontal && event.key === forwardKey) || (vertical && event.key === \"ArrowDown\")) {\n      next = rovingMove(current, length, 1, wrap);\n    } else if ((horizontal && event.key === backwardKey) || (vertical && event.key === \"ArrowUp\")) {\n      next = rovingMove(current, length, -1, wrap);\n    } else if (this.homeEndValue && event.key === \"Home\") {\n      next = 0;\n    } else if (this.homeEndValue && event.key === \"End\") {\n      next = length - 1;\n    } else {\n      return;\n    }\n\n    event.preventDefault();\n    this.#activate(next, true);\n  };\n\n  /**\n   * Syncs the single tab stop to an item that received focus by other means\n   * (click, programmatic `focus()`), so returning via Tab lands on it. The\n   * keyboard path's own `focus()` re-enters here but is a no-op (index unchanged).\n   */\n  readonly #onFocusin = (event: FocusEvent): void => {\n    const index = this.#indexOf(event.target);\n    if (index !== -1) this.#activate(index, false);\n  };\n\n  /** Resolves the item index owning an event target (the item or a descendant). */\n  #indexOf(target: EventTarget | null): number {\n    const node = target as Node | null;\n    if (!node) return -1;\n    return this.itemTargets.findIndex((item) => item === node || item.contains(node));\n  }\n\n  /** Makes `index` the tab stop (optionally focusing it), emitting `change` once. */\n  #activate(index: number, focus: boolean): void {\n    const previous = this.#roving.activeIndex;\n    this.#roving.setActive(index, { focus });\n    if (index !== previous) {\n      this.dispatch(\"change\", { detail: { index, item: this.itemTargets[index] } });\n    }\n  }\n}\n"]}
+{"version":3,"sources":["../../src/utils/logical_scroll.ts","../../src/utils/arrow_step.ts","../../src/utils/microtask_coalescer.ts","../../src/utils/roving_tabindex.ts","../../src/controllers/roving_controller.ts"],"names":[],"mappings":"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","file":"roving_controller.js","sourcesContent":["/** Normalized scroll position and maximum distance on one logical axis. */\nexport interface LogicalScrollMetrics {\n  position: number;\n  max: number;\n}\n\n/**\n * Whether horizontal scrolling on `element` follows right-to-left inline flow.\n *\n * Resolved from the **computed** `direction`, so the authoring contract is the\n * usual `dir=\"rtl\"` (or a stylesheet) on the element or any ancestor.\n *\n * Scope: horizontal writing modes. A vertical writing mode (`writing-mode:\n * vertical-rl`) also inverts the horizontal axis, which this check does not\n * model — vertical writing modes are out of scope for the scroll utilities\n * (their consumers describe axes as horizontal/vertical, not inline/block).\n */\nexport function isRtl(element: Element): boolean {\n  return window.getComputedStyle(element).direction === \"rtl\";\n}\n\n/**\n * Returns scroll distance from the logical start edge.\n *\n * CSSOM View exposes standards-mode RTL horizontal offsets as `0` at the inline\n * start (right) and increasingly negative values toward the inline end (left).\n * The normalized position is always clamped to `[0, max]`, which also absorbs\n * Safari's elastic overscroll values.\n */\nexport function logicalScrollMetrics(\n  element: HTMLElement,\n  horizontal: boolean,\n): LogicalScrollMetrics {\n  const max = Math.max(\n    0,\n    horizontal\n      ? element.scrollWidth - element.clientWidth\n      : element.scrollHeight - element.clientHeight,\n  );\n  const raw = horizontal ? element.scrollLeft : element.scrollTop;\n  const position = horizontal && isRtl(element) ? -raw : raw;\n  return { position: Math.min(max, Math.max(0, position)), max };\n}\n\n/**\n * Converts a logical start/end delta to the physical value accepted by\n * `Element.scrollBy`.\n */\nexport function physicalScrollDelta(\n  element: HTMLElement,\n  horizontal: boolean,\n  logicalDelta: number,\n): number {\n  return horizontal && isRtl(element) ? -logicalDelta : logicalDelta;\n}\n","import { isRtl } from \"./logical_scroll\";\n\n/**\n * Turns an arrow key into a **logical** step: `+1` for \"next\", `-1` for\n * \"previous\", `0` when the key names neither.\n *\n * APG defines the horizontal pair as *next / previous* and says a vertical\n * arrangement swaps in Down/Up for the same meaning — so the pair is one axis's\n * spelling of an order, and the order reverses with the writing direction. Only\n * the horizontal pair reverses. Down/Up name an axis the writing direction does\n * not mirror, and returning them unchanged is the point: many controllers fold\n * both pairs into one branch, where swapping the branches under RTL would flip\n * the vertical axis too — a bug that reads as \"the arrows work\" until someone\n * presses Down.\n *\n * **Direction is read from the element the caller passes, which should be the\n * container that lays the items out** — not the focused child. A child may carry\n * its own `dir` (an LTR input inside an RTL form is ordinary authoring), and\n * probing per handler makes two handlers disagree at the boundary between them.\n *\n * This decides direction only. Whether the axis is even active (an\n * `orientation=\"horizontal\"` widget ignoring Down/Up), how far the step lands,\n * and what wrapping does all stay with the caller.\n *\n * **It encodes the list-order convention: `ArrowDown` is *next*.** Widgets that\n * pair the arrows by *value* instead — `ArrowUp` meaning \"more\", as a rating or a\n * slider does — must not use this, or their vertical axis inverts. Reverse the\n * horizontal pair on its own there.\n *\n * @example\n * ```ts\n * const step = logicalArrowStep(event.key, this.element);\n * if (step === 0) return;\n * this.#roving.setActive(rovingMove(current, length, step, \"wrap\"), { focus: true });\n * ```\n */\nexport function logicalArrowStep(key: string, element: Element): 1 | -1 | 0 {\n  if (key === \"ArrowDown\") return 1;\n  if (key === \"ArrowUp\") return -1;\n  if (key !== \"ArrowRight\" && key !== \"ArrowLeft\") return 0;\n  const forward = isRtl(element) ? \"ArrowLeft\" : \"ArrowRight\";\n  return key === forward ? 1 : -1;\n}\n\n/**\n * Rewrites `key` so an existing LTR-shaped branch keeps working under RTL:\n * `ArrowRight` and `ArrowLeft` trade places, everything else passes through.\n *\n * The alternative — negating a delta — silently breaks handlers whose two\n * horizontal branches are **not mirror images**. A grid that clamps one edge but\n * not the other, or a segmented field guarding `index > 0` on one side and\n * `index < length - 1` on the other, ends up applying the wrong guard to the\n * wrong direction. Swapping the key leaves each branch, guards and all, exactly\n * where its author put it.\n *\n * Same rule as {@link logicalArrowStep} about which element to read: pass the\n * container that lays the items out, not the focused child.\n *\n * @example\n * ```ts\n * switch (logicalArrowKey(event.key, this.element)) {\n *   case \"ArrowLeft\": // \"previous\" — whatever direction that is on screen\n * ```\n */\nexport function logicalArrowKey(key: string, element: Element): string {\n  if (key !== \"ArrowRight\" && key !== \"ArrowLeft\") return key;\n  if (!isRtl(element)) return key;\n  return key === \"ArrowRight\" ? \"ArrowLeft\" : \"ArrowRight\";\n}\n\n/** Modifiers a widget may claim on an arrow key, named for the `allow` list. */\nexport type ArrowModifier = \"alt\" | \"ctrl\" | \"meta\" | \"shift\";\n\n/**\n * True when an arrow key arrived carrying a modifier the widget must leave to\n * the browser: return without calling `preventDefault()` and without moving any\n * state.\n *\n * A bare arrow belongs to the widget; a chorded one usually does not.\n * `Alt`/`Meta` plus a horizontal arrow is history back/forward on every desktop\n * browser, and a widget that swallows it makes the shortcut work or not\n * depending on where focus happens to sit — a coin-flip the user cannot see.\n *\n * `allow` is for the combinations APG assigns to a pattern **and the widget\n * actually implements** — today only Combobox's optional `Alt+Down`/`Alt+Up`.\n * Listing one the widget does not implement defeats the point: the chord then\n * runs the plain-arrow branch, which is exactly what this guard exists to stop.\n * Non-arrow keys return `false`, so chorded letters and\n * `Control+Home`/`Control+End` are untouched.\n *\n * @example\n * ```ts\n * if (isReservedArrowChord(event)) return;\n * ```\n */\nexport function isReservedArrowChord(\n  event: KeyboardEvent,\n  allow: readonly ArrowModifier[] = [],\n): boolean {\n  if (!event.key.startsWith(\"Arrow\")) return false;\n  return (\n    (event.altKey && !allow.includes(\"alt\")) ||\n    (event.ctrlKey && !allow.includes(\"ctrl\")) ||\n    (event.metaKey && !allow.includes(\"meta\")) ||\n    (event.shiftKey && !allow.includes(\"shift\"))\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 * 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","/**\n * Low-level roving-tabindex primitive shared by composite-widget controllers.\n *\n * The APG roving-tabindex pattern keeps a composite widget a single Tab stop:\n * exactly one item is in the Tab sequence (`tabindex=\"0\"`) while the rest are\n * removed from it (`tabindex=\"-1\"`), and the arrow keys move both DOM focus and\n * that single tabbable position together. {@link RovingTabindex} owns *only* that\n * mechanical bookkeeping — \"which one item is tabbable, and move focus there\".\n *\n * It is intentionally **policy-free**. Orientation, wrapping vs. clamping,\n * selection-follows-focus, typeahead, and `Home`/`End` semantics differ per APG\n * pattern (Radio Group, Toolbar, Rating, …); folding them into one helper would\n * flatten those widgets to a lowest common denominator and lose each pattern's\n * correctness. Those decisions therefore stay in each controller, which calls\n * {@link RovingTabindex.setActive} with an index it computed itself (optionally\n * via the pure {@link rovingMove} helper).\n *\n * @remarks\n * Items are read lazily through a getter so a controller can add or remove\n * targets (Stimulus re-scans the DOM) without re-wiring this helper. A caller\n * that already captured one event-scoped snapshot may pass it to\n * {@link RovingTabindex.setActive}, avoiding a second live-target scan while\n * preserving one coherent collection for the whole operation.\n */\nexport class RovingTabindex {\n  /** Returns the current ordered item elements; called on every operation. */\n  readonly #getItems: () => HTMLElement[];\n\n  /**\n   * @param getItems - Returns the current ordered item elements. Called on every\n   *   operation so the live target list is always used.\n   */\n  constructor(getItems: () => HTMLElement[]) {\n    this.#getItems = getItems;\n  }\n\n  /** Index of the currently tabbable item (`tabindex=\"0\"`), or `-1` if none. */\n  get activeIndex(): number {\n    return this.#getItems().findIndex((item) => item.tabIndex === 0);\n  }\n\n  /**\n   * Makes exactly the item at `index` tabbable (`tabindex=\"0\"`) and removes every\n   * other item from the Tab sequence (`tabindex=\"-1\"`). An out-of-range `index`\n   * (e.g. `-1`) leaves all items at `-1`, which a controller can use to express\n   * \"nothing is currently tabbable\".\n   *\n   * @param index - Position of the item to make tabbable.\n   * @param options - Pass `{ focus: true }` to also move DOM focus to that item,\n   *   and `items` to reuse an event-scoped collection snapshot.\n   */\n  setActive(\n    index: number,\n    options: { focus?: boolean; items?: readonly HTMLElement[] } = {},\n  ): void {\n    const { focus = false } = options;\n    const items = options.items ?? this.#getItems();\n    items.forEach((item, i) => {\n      item.tabIndex = i === index ? 0 : -1;\n    });\n    if (focus) items[index]?.focus();\n  }\n}\n\n/** Edge behavior for {@link rovingMove}: cycle past the ends, or stop at them. */\nexport type RovingWrap = \"wrap\" | \"clamp\";\n\n/**\n * Pure helper that resolves the target index for a one-step directional move.\n *\n * Keyboard/orientation mapping stays in the caller: it decides that a key means\n * `delta` `+1` (next) or `-1` (previous) and whether the widget should `\"wrap\"`\n * (Radio Group, Toolbar) or `\"clamp\"` at the ends.\n *\n * @param current - The index focus is moving from.\n * @param length - Number of items in the set.\n * @param delta - `+1` to move to the next item, `-1` for the previous.\n * @param wrap - `\"wrap\"` cycles around the ends; `\"clamp\"` stops at them.\n * @returns The resolved index, or `-1` when there are no items.\n */\nexport function rovingMove(\n  current: number,\n  length: number,\n  delta: number,\n  wrap: RovingWrap,\n): number {\n  if (length === 0) return -1;\n  const next = current + delta;\n  if (wrap === \"wrap\") return (next + length) % length;\n  return Math.min(length - 1, Math.max(0, next));\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { isReservedArrowChord } from \"../utils/arrow_step\";\nimport { isRtl } from \"../utils/logical_scroll\";\nimport { MicrotaskCoalescer } from \"../utils/microtask_coalescer\";\nimport { RovingTabindex, type RovingWrap, rovingMove } from \"../utils/roving_tabindex\";\n\n/**\n * Headless **roving tabindex**: makes a set of `item`s a single Tab stop and\n * moves focus between them with the arrow keys — the APG roving-tabindex\n * technique, surfaced as a standalone controller. It is the policy layer over the\n * shared {@link RovingTabindex} util (counterpart to Focus Scope over `FocusTrap`),\n * giving the orientation / wrap / Home-End the util deliberately leaves out. No\n * dedicated APG pattern; it is the keyboard primitive Toolbar / Menu / Radio Group\n * and friends build on. Core (zero dependencies).\n *\n * Markup contract (identifier: `stimeo--roving`):\n *   <div data-controller=\"stimeo--roving\"\n *        data-stimeo--roving-orientation-value=\"horizontal\">\n *     <button data-stimeo--roving-target=\"item\">A</button>\n *     <button data-stimeo--roving-target=\"item\">B</button>\n *     <button data-stimeo--roving-target=\"item\">C</button>\n *   </div>\n *\n * Exactly one item is tabbable (`tabindex=\"0\"`); the arrow keys (per\n * `orientation`) move focus and that tab stop together, `Home`/`End` jump to the\n * ends (`homeEnd`), and `wrap` cycles past the ends or clamps at them. Listeners\n * are **delegated on the container** — `keydown` for movement and `focusin` to\n * sync the tab stop when focus arrives by click or programmatically — so\n * dynamically added/removed items need no per-item `data-action`. It emits\n * `change` whenever the tabbable item changes.\n *\n * @remarks\n * Behavior only: it owns `tabindex` and focus movement, nothing else. It does\n * **not** assign roles (`role=\"toolbar\"`/`\"radiogroup\"` is the author's), manage\n * selection / selection-follows-focus, typeahead, or activation (`Enter`/`Space`)\n * — those stay with the consuming pattern. `connect()` is idempotent: it keeps an\n * existing tab stop (reads it back from the DOM) and only defaults to the first\n * item when none is set, so a Turbo cache restore / morph never resets the user's\n * position. The delegated listeners are torn down on `disconnect()`.\n */\nexport class RovingController extends Controller<HTMLElement> {\n  static override targets = [\"item\"];\n  static override values = {\n    orientation: { type: String, default: \"horizontal\" },\n    wrap: { type: Boolean, default: true },\n    homeEnd: { type: Boolean, default: true },\n  };\n  static events = [\"change\"] as const;\n\n  declare readonly itemTargets: HTMLElement[];\n  declare orientationValue: string;\n  declare wrapValue: boolean;\n  declare homeEndValue: boolean;\n\n  readonly #roving = new RovingTabindex(() => this.itemTargets);\n  readonly #reconcile = new MicrotaskCoalescer(() => this.#ensureTabStop());\n  #connected = false;\n\n  override connect(): void {\n    // Establish the single tab stop from the DOM (source of truth): keep an\n    // existing tabbable item, else default to the first. Silent — no change event\n    // for the initial mount.\n    this.#ensureTabStop();\n    this.element.addEventListener(\"keydown\", this.#onKeydown);\n    this.element.addEventListener(\"focusin\", this.#onFocusin);\n    this.#connected = true;\n    this.#reconcile.activate();\n  }\n\n  override disconnect(): void {\n    this.#connected = false;\n    this.#reconcile.cancel();\n    this.element.removeEventListener(\"keydown\", this.#onKeydown);\n    this.element.removeEventListener(\"focusin\", this.#onFocusin);\n  }\n\n  /** Drops a runtime-added item from the Tab sequence before batch reconciliation. */\n  itemTargetConnected(item: HTMLElement): void {\n    if (!this.#connected) return;\n    item.tabIndex = -1;\n    this.#reconcile.schedule();\n  }\n\n  /** Re-establishes the single Tab stop after an item leaves the target set. */\n  itemTargetDisconnected(): void {\n    this.#reconcile.schedule();\n  }\n\n  /** Arrow keys move focus + the tab stop; Home/End jump to the ends. */\n  readonly #onKeydown = (event: KeyboardEvent): void => {\n    // A descendant widget that already claimed the key (e.g. a grabbed\n    // `stimeo--pointer-drag` handle consuming arrows to move an item) must not\n    // ALSO move the roving focus — composition depends on this yield.\n    if (event.defaultPrevented) return;\n    if (isReservedArrowChord(event)) return;\n    const items = this.itemTargets;\n    const current = this.#indexOf(event.target);\n    if (current === -1) return;\n\n    const length = items.length;\n    const wrap: RovingWrap = this.wrapValue ? \"wrap\" : \"clamp\";\n    const orientation = this.orientationValue;\n    const horizontal = orientation === \"horizontal\" || orientation === \"both\";\n    const vertical = orientation === \"vertical\" || orientation === \"both\";\n\n    // Logical, not physical. APG defines these as \"next / previous\n    // control\", and says a vertical arrangement swaps in Down/Up for the same\n    // meaning — so the pair is one axis's spelling of an order, and the order\n    // reverses with the writing direction. Read from the controller element: the\n    // container is what lays the items out, and a child may carry its own `dir`\n    // (an LTR input inside an RTL form is ordinary authoring).\n    // Only the horizontal pair reverses; `orientation=\"both\"` keeps Down/Up as-is.\n    const rtl = horizontal && isRtl(this.element);\n    const forwardKey = rtl ? \"ArrowLeft\" : \"ArrowRight\";\n    const backwardKey = rtl ? \"ArrowRight\" : \"ArrowLeft\";\n\n    let next: number;\n    if ((horizontal && event.key === forwardKey) || (vertical && event.key === \"ArrowDown\")) {\n      next = rovingMove(current, length, 1, wrap);\n    } else if ((horizontal && event.key === backwardKey) || (vertical && event.key === \"ArrowUp\")) {\n      next = rovingMove(current, length, -1, wrap);\n    } else if (this.homeEndValue && event.key === \"Home\") {\n      next = 0;\n    } else if (this.homeEndValue && event.key === \"End\") {\n      next = length - 1;\n    } else {\n      return;\n    }\n\n    event.preventDefault();\n    this.#activate(next, true);\n  };\n\n  /**\n   * Syncs the single tab stop to an item that received focus by other means\n   * (click, programmatic `focus()`), so returning via Tab lands on it. The\n   * keyboard path's own `focus()` re-enters here but is a no-op (index unchanged).\n   */\n  readonly #onFocusin = (event: FocusEvent): void => {\n    const index = this.#indexOf(event.target);\n    if (index !== -1) this.#activate(index, false);\n  };\n\n  /** Resolves the item index owning an event target (the item or a descendant). */\n  #indexOf(target: EventTarget | null): number {\n    const node = target as Node | null;\n    if (!node) return -1;\n    return this.itemTargets.findIndex((item) => item === node || item.contains(node));\n  }\n\n  /** Makes `index` the tab stop (optionally focusing it), emitting `change` once. */\n  #activate(index: number, focus: boolean): void {\n    const previous = this.#roving.activeIndex;\n    this.#roving.setActive(index, { focus });\n    if (index !== previous) {\n      this.dispatch(\"change\", { detail: { index, item: this.itemTargets[index] } });\n    }\n  }\n\n  /** Keeps the first existing Tab stop, falling back to the first live item. */\n  #ensureTabStop(): void {\n    const active = this.#roving.activeIndex;\n    this.#roving.setActive(active === -1 ? 0 : active);\n  }\n}\n"]}

package/dist/controllers/scroll_area_controller.d.ts

@@ -17,11 +17,13 @@ import { Controller } from '@hotwired/stimulus';
  * own, the viewport is made keyboard-scrollable (`tabindex="0"`, plus `role="region"`
  * when it already has an accessible name). Scroll position is published as
  * `data-scroll` (`start`/`middle`/`end`), overflow as `data-overflow`, and progress
- * as `--stimeo-scroll-progress` (0–1) so consumer CSS can draw scroll shadows.
+ * as `--stimeo--scroll-progress` (0–1) so consumer CSS can draw scroll shadows.
  *
  * @remarks
  * Behavior only. The `scroll` listener and {@link LayoutObserver} (element +
  * viewport resize) are torn down on `disconnect()` (Turbo navigation included).
+ * Runtime replacement of the viewport rebinds those resources and the content
+ * observer as one lifecycle unit.
  * `role="region"` is added only when the viewport is already named, so a scrollable
  * region never becomes an unlabeled landmark.
  */
@@ -39,6 +41,10 @@ declare class ScrollAreaController extends Controller<HTMLElement> {
     readonly hasViewportTarget: boolean;
     orientationValue: string;
     connect(): void;
+    /** Schedules a complete observer/listener rebind for a runtime viewport target. */
+    viewportTargetConnected(): void;
+    /** Schedules cleanup or replacement binding after a viewport leaves. */
+    viewportTargetDisconnected(): void;
     disconnect(): void;
 }
 

package/dist/controllers/scroll_area_controller.js

@@ -2,6 +2,43 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/scroll_area_controller.ts
 
+// src/utils/attribute_lease.ts
+var AttributeLease = class {
+  #attribute;
+  #records = /* @__PURE__ */ new Map();
+  /** @param attribute - The attribute whose temporary values this lease owns. */
+  constructor(attribute) {
+    this.#attribute = attribute;
+  }
+  /** Writes or removes the leased attribute while preserving its authored value. */
+  write(element, value) {
+    const existing = this.#records.get(element);
+    if (existing) {
+      existing.written = value;
+    } else {
+      this.#records.set(element, {
+        original: element.getAttribute(this.#attribute),
+        written: value
+      });
+    }
+    if (value === null) element.removeAttribute(this.#attribute);
+    else element.setAttribute(this.#attribute, value);
+  }
+  /** Returns one lease without overwriting a value subsequently authored by a consumer. */
+  return(element) {
+    const record = this.#records.get(element);
+    if (!record) return;
+    this.#records.delete(element);
+    if (element.getAttribute(this.#attribute) !== record.written) return;
+    if (record.original === null) element.removeAttribute(this.#attribute);
+    else element.setAttribute(this.#attribute, record.original);
+  }
+  /** Returns every outstanding lease using the same ownership check as {@link return}. */
+  returnAll() {
+    for (const element of Array.from(this.#records.keys())) this.return(element);
+  }
+};
+
 // src/utils/layout_observer.ts
 var LayoutObserver = class {
   #callback;
@@ -72,10 +109,74 @@ function logicalScrollMetrics(element, horizontal) {
   return { position: Math.min(max, Math.max(0, position)), max };
 }
 
+// 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/utils/before_cache_reset.ts
+var BeforeCacheReset = class _BeforeCacheReset {
+  /** Every subscribed instance, iterated by the one shared document listener. */
+  static #subscribers = /* @__PURE__ */ new Set();
+  /** The shared listener; installed while at least one instance is subscribed. */
+  static #onBeforeCache = () => {
+    for (const subscriber of _BeforeCacheReset.#subscribers) subscriber.#rewind();
+  };
+  #rewind;
+  /** @param rewind - the pass that returns this controller's state to its initial form. */
+  constructor(rewind) {
+    this.#rewind = rewind;
+  }
+  /** Subscribes to `turbo:before-cache`; call from `connect()`. Idempotent. */
+  activate() {
+    const first = _BeforeCacheReset.#subscribers.size === 0;
+    _BeforeCacheReset.#subscribers.add(this);
+    if (first) {
+      document.addEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+    }
+  }
+  /** Unsubscribes; call from `disconnect()`. Safe when never subscribed. */
+  deactivate() {
+    _BeforeCacheReset.#subscribers.delete(this);
+    if (_BeforeCacheReset.#subscribers.size > 0) return;
+    document.removeEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+  }
+};
+
 // src/utils/tabindex_loan.ts
 var TabindexLoan = class {
   #value;
   #lent = /* @__PURE__ */ new Set();
+  /** Returns live loans before Turbo can copy them into its page snapshot. */
+  #beforeCache = new BeforeCacheReset(() => this.returnAll());
   /**
    * @param value - the `tabindex` to lend. `"-1"` (the default) is
    *   programmatically focusable but not a Tab stop; `"0"` is a real Tab stop,
@@ -89,6 +190,7 @@ var TabindexLoan = class {
     if (element.hasAttribute("tabindex")) return;
     element.setAttribute("tabindex", this.#value);
     this.#lent.add(element);
+    this.#beforeCache.activate();
   }
   /** Takes back every loan whose value is still the one that was lent. */
   returnAll() {
@@ -96,6 +198,7 @@ var TabindexLoan = class {
       if (element.getAttribute("tabindex") === this.#value) element.removeAttribute("tabindex");
     }
     this.#lent.clear();
+    this.#beforeCache.deactivate();
   }
 };
 
@@ -117,29 +220,56 @@ var ScrollAreaController = class extends Controller {
   };
   static events = ["reach"];
   #layout = new LayoutObserver(() => this.#update());
+  /** Current element receiving scroll, resize, mutation, and keyboard-reach behavior. */
+  #viewport = null;
+  /** Guards target callbacks before connect and after disconnect. */
+  #connected = false;
+  /** Collapses target replacement callbacks into one final-DOM rebind. */
+  #rebind = new MicrotaskCoalescer(() => this.#syncViewport());
   /** Re-checks the tab stop when the viewport's focusable content comes or goes. */
   #content = null;
   /** Last edge reported via `reach`, so the event fires once per arrival. */
   #lastEdge = null;
   /** Whether this controller added `tabindex`, so teardown only removes its own. */
   #tabindex = new TabindexLoan("0");
-  /** Whether this controller added `role="region"`, for symmetric teardown. */
-  #addedRole = false;
+  /** Temporarily owns a derived `role="region"` without losing an authored replacement. */
+  #role = new AttributeLease("role");
   #onScroll = () => {
     this.#update();
   };
   connect() {
-    if (!this.hasViewportTarget) return;
-    this.viewportTarget.addEventListener("scroll", this.#onScroll, { passive: true });
-    this.#layout.observe(this.viewportTarget);
+    this.#connected = true;
+    this.#rebind.activate();
     this.#layout.observeViewport();
+    this.#syncViewport();
+  }
+  /** Schedules a complete observer/listener rebind for a runtime viewport target. */
+  viewportTargetConnected() {
+    this.#rebind.schedule();
+  }
+  /** Schedules cleanup or replacement binding after a viewport leaves. */
+  viewportTargetDisconnected() {
+    this.#rebind.schedule();
+  }
+  /** Rebinds every viewport-owned resource against the final target in this mutation batch. */
+  #syncViewport() {
+    if (!this.#connected) return;
+    const next = this.hasViewportTarget ? this.viewportTarget : null;
+    if (next === this.#viewport) {
+      this.#update();
+      return;
+    }
+    if (this.#viewport) this.#unbindViewport(this.#viewport);
+    this.#viewport = next;
+    if (!next) return;
+    next.addEventListener("scroll", this.#onScroll, { passive: true });
+    this.#layout.observe(next);
     if (typeof MutationObserver !== "undefined") {
       this.#content = new MutationObserver(() => {
-        if (!this.hasViewportTarget) return;
-        const vp = this.viewportTarget;
-        this.#syncKeyboardReach(vp, this.#syncOverflow(vp));
+        if (this.#viewport !== next) return;
+        this.#syncKeyboardReach(next, this.#syncOverflow(next));
       });
-      this.#content.observe(this.viewportTarget, {
+      this.#content.observe(next, {
         subtree: true,
         childList: true,
         attributes: true
@@ -148,24 +278,31 @@ var ScrollAreaController = class extends Controller {
     this.#update();
   }
   disconnect() {
-    if (this.hasViewportTarget) {
-      this.viewportTarget.removeEventListener("scroll", this.#onScroll);
-      this.#clearAddedAttributes(this.viewportTarget);
-    }
+    this.#connected = false;
+    this.#rebind.cancel();
+    if (this.#viewport) this.#unbindViewport(this.#viewport);
     this.#layout.disconnect();
+    this.#lastEdge = null;
+  }
+  /** Releases every resource and derived attribute owned by one former viewport. */
+  #unbindViewport(viewport) {
+    viewport.removeEventListener("scroll", this.#onScroll);
+    this.#layout.unobserve(viewport);
     this.#content?.disconnect();
     this.#content = null;
+    this.#clearAddedAttributes(viewport);
+    if (this.#viewport === viewport) this.#viewport = null;
     this.#lastEdge = null;
   }
   /** Re-measures overflow and scroll position and reflects the state hooks. */
   #update() {
-    if (!this.hasViewportTarget) return;
-    const vp = this.viewportTarget;
+    const vp = this.#viewport;
+    if (!vp) return;
     const overflowing = this.#syncOverflow(vp);
     this.#syncKeyboardReach(vp, overflowing);
     const { position, progress } = this.#measurePosition(vp);
     this.element.setAttribute("data-scroll", position);
-    this.element.style.setProperty("--stimeo-scroll-progress", String(progress));
+    this.element.style.setProperty("--stimeo--scroll-progress", String(progress));
     const edge = position === "start" ? "start" : position === "end" ? "end" : null;
     if (overflowing && edge && edge !== this.#lastEdge) {
       this.#lastEdge = edge;
@@ -174,7 +311,6 @@ var ScrollAreaController = class extends Controller {
       this.#lastEdge = null;
     }
   }
-  /** Whether the viewport can scroll on the configured axis. */
   /**
    * Measures overflow and reflects the `data-overflow` hook.
    *
@@ -219,8 +355,7 @@ var ScrollAreaController = class extends Controller {
     if (wantsTabindex) {
       this.#tabindex.lend(vp);
       if (!vp.hasAttribute("role") && this.#hasAccessibleName(vp)) {
-        vp.setAttribute("role", "region");
-        this.#addedRole = true;
+        this.#role.write(vp, "region");
       }
     } else {
       this.#clearAddedAttributes(vp);
@@ -229,10 +364,7 @@ var ScrollAreaController = class extends Controller {
   /** Removes (and resets the flags for) only the attributes this controller added. */
   #clearAddedAttributes(vp) {
     this.#tabindex.returnAll();
-    if (this.#addedRole) {
-      vp.removeAttribute("role");
-      this.#addedRole = false;
-    }
+    this.#role.return(vp);
   }
   /**
    * Whether the viewport owns something the user can Tab to *right now*.