stimeo-ui 0.2.0 → 0.3.0

package/dist/controllers/roving_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/roving_tabindex.ts","../../src/controllers/roving_controller.ts"],"names":[],"mappings":"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","file":"roving_controller.js","sourcesContent":["/**\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 { 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    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    let next: number;\n    if ((horizontal && event.key === \"ArrowRight\") || (vertical && event.key === \"ArrowDown\")) {\n      next = rovingMove(current, length, 1, wrap);\n    } else if ((horizontal && event.key === \"ArrowLeft\") || (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/roving_tabindex.ts","../../src/controllers/roving_controller.ts"],"names":[],"mappings":";;;;;AAiBO,SAAS,MAAM,OAAA,EAA2B;AAC/C,EAAA,OAAO,MAAA,CAAO,gBAAA,CAAiB,OAAO,CAAA,CAAE,SAAA,KAAc,KAAA;AACxD;;;AC4EO,SAAS,oBAAA,CACd,KAAA,EACA,KAAA,GAAkC,EAAC,EAC1B;AACT,EAAA,IAAI,CAAC,KAAA,CAAM,GAAA,CAAI,UAAA,CAAW,OAAO,GAAG,OAAO,KAAA;AAC3C,EAAA,OACG,KAAA,CAAM,MAAA,IAAU,CAAC,KAAA,CAAM,QAAA,CAAS,KAAK,CAAA,IACrC,KAAA,CAAM,OAAA,IAAW,CAAC,KAAA,CAAM,QAAA,CAAS,MAAM,KACvC,KAAA,CAAM,OAAA,IAAW,CAAC,KAAA,CAAM,QAAA,CAAS,MAAM,CAAA,IACvC,KAAA,CAAM,QAAA,IAAY,CAAC,KAAA,CAAM,QAAA,CAAS,OAAO,CAAA;AAE9C;;;ACrFO,IAAM,iBAAN,MAAqB;AAAA;AAAA,EAEjB,SAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMT,YAAY,QAAA,EAA+B;AACzC,IAAA,IAAA,CAAK,SAAA,GAAY,QAAA;AAAA,EACnB;AAAA;AAAA,EAGA,IAAI,WAAA,GAAsB;AACxB,IAAA,OAAO,IAAA,CAAK,WAAU,CAAE,SAAA,CAAU,CAAC,IAAA,KAAS,IAAA,CAAK,aAAa,CAAC,CAAA;AAAA,EACjE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,UAAU,KAAA,EAAe,EAAE,QAAQ,KAAA,EAAM,GAAyB,EAAC,EAAS;AAC1E,IAAA,MAAM,KAAA,GAAQ,KAAK,SAAA,EAAU;AAC7B,IAAA,KAAA,CAAM,OAAA,CAAQ,CAAC,IAAA,EAAM,CAAA,KAAM;AACzB,MAAA,IAAA,CAAK,QAAA,GAAW,CAAA,KAAM,KAAA,GAAQ,CAAA,GAAI,EAAA;AAAA,IACpC,CAAC,CAAA;AACD,IAAA,IAAI,KAAA,EAAO,KAAA,CAAM,KAAK,CAAA,EAAG,KAAA,EAAM;AAAA,EACjC;AACF,CAAA;AAkBO,SAAS,UAAA,CACd,OAAA,EACA,MAAA,EACA,KAAA,EACA,IAAA,EACQ;AACR,EAAA,IAAI,MAAA,KAAW,GAAG,OAAO,EAAA;AACzB,EAAA,MAAM,OAAO,OAAA,GAAU,KAAA;AACvB,EAAA,IAAI,IAAA,KAAS,MAAA,EAAQ,OAAA,CAAQ,IAAA,GAAO,MAAA,IAAU,MAAA;AAC9C,EAAA,OAAO,IAAA,CAAK,IAAI,MAAA,GAAS,CAAA,EAAG,KAAK,GAAA,CAAI,CAAA,EAAG,IAAI,CAAC,CAAA;AAC/C;;;AC3CO,IAAM,gBAAA,GAAN,cAA+B,UAAA,CAAwB;AAAA,EAC5D,OAAgB,OAAA,GAAU,CAAC,MAAM,CAAA;AAAA,EACjC,OAAgB,MAAA,GAAS;AAAA,IACvB,WAAA,EAAa,EAAE,IAAA,EAAM,MAAA,EAAQ,SAAS,YAAA,EAAa;AAAA,IACnD,IAAA,EAAM,EAAE,IAAA,EAAM,OAAA,EAAS,SAAS,IAAA,EAAK;AAAA,IACrC,OAAA,EAAS,EAAE,IAAA,EAAM,OAAA,EAAS,SAAS,IAAA;AAAK,GAC1C;AAAA,EACA,OAAO,MAAA,GAAS,CAAC,QAAQ,CAAA;AAAA,EAOhB,OAAA,GAAU,IAAI,cAAA,CAAe,MAAM,KAAK,WAAW,CAAA;AAAA,EAEnD,OAAA,GAAgB;AAIvB,IAAA,MAAM,MAAA,GAAS,KAAK,OAAA,CAAQ,WAAA;AAC5B,IAAA,IAAA,CAAK,OAAA,CAAQ,SAAA,CAAU,MAAA,KAAW,EAAA,GAAK,IAAI,MAAM,CAAA;AACjD,IAAA,IAAA,CAAK,OAAA,CAAQ,gBAAA,CAAiB,SAAA,EAAW,IAAA,CAAK,UAAU,CAAA;AACxD,IAAA,IAAA,CAAK,OAAA,CAAQ,gBAAA,CAAiB,SAAA,EAAW,IAAA,CAAK,UAAU,CAAA;AAAA,EAC1D;AAAA,EAES,UAAA,GAAmB;AAC1B,IAAA,IAAA,CAAK,OAAA,CAAQ,mBAAA,CAAoB,SAAA,EAAW,IAAA,CAAK,UAAU,CAAA;AAC3D,IAAA,IAAA,CAAK,OAAA,CAAQ,mBAAA,CAAoB,SAAA,EAAW,IAAA,CAAK,UAAU,CAAA;AAAA,EAC7D;AAAA;AAAA,EAGS,UAAA,GAAa,CAAC,KAAA,KAA+B;AAIpD,IAAA,IAAI,MAAM,gBAAA,EAAkB;AAC5B,IAAA,IAAI,oBAAA,CAAqB,KAAK,CAAA,EAAG;AACjC,IAAA,MAAM,QAAQ,IAAA,CAAK,WAAA;AACnB,IAAA,MAAM,OAAA,GAAU,IAAA,CAAK,QAAA,CAAS,KAAA,CAAM,MAAM,CAAA;AAC1C,IAAA,IAAI,YAAY,EAAA,EAAI;AAEpB,IAAA,MAAM,SAAS,KAAA,CAAM,MAAA;AACrB,IAAA,MAAM,IAAA,GAAmB,IAAA,CAAK,SAAA,GAAY,MAAA,GAAS,OAAA;AACnD,IAAA,MAAM,cAAc,IAAA,CAAK,gBAAA;AACzB,IAAA,MAAM,UAAA,GAAa,WAAA,KAAgB,YAAA,IAAgB,WAAA,KAAgB,MAAA;AACnE,IAAA,MAAM,QAAA,GAAW,WAAA,KAAgB,UAAA,IAAc,WAAA,KAAgB,MAAA;AAS/D,IAAA,MAAM,GAAA,GAAM,UAAA,IAAc,KAAA,CAAM,IAAA,CAAK,OAAO,CAAA;AAC5C,IAAA,MAAM,UAAA,GAAa,MAAM,WAAA,GAAc,YAAA;AACvC,IAAA,MAAM,WAAA,GAAc,MAAM,YAAA,GAAe,WAAA;AAEzC,IAAA,IAAI,IAAA;AACJ,IAAA,IAAK,cAAc,KAAA,CAAM,GAAA,KAAQ,cAAgB,QAAA,IAAY,KAAA,CAAM,QAAQ,WAAA,EAAc;AACvF,MAAA,IAAA,GAAO,UAAA,CAAW,OAAA,EAAS,MAAA,EAAQ,CAAA,EAAG,IAAI,CAAA;AAAA,IAC5C,CAAA,MAAA,IAAY,cAAc,KAAA,CAAM,GAAA,KAAQ,eAAiB,QAAA,IAAY,KAAA,CAAM,QAAQ,SAAA,EAAY;AAC7F,MAAA,IAAA,GAAO,UAAA,CAAW,OAAA,EAAS,MAAA,EAAQ,EAAA,EAAI,IAAI,CAAA;AAAA,IAC7C,CAAA,MAAA,IAAW,IAAA,CAAK,YAAA,IAAgB,KAAA,CAAM,QAAQ,MAAA,EAAQ;AACpD,MAAA,IAAA,GAAO,CAAA;AAAA,IACT,CAAA,MAAA,IAAW,IAAA,CAAK,YAAA,IAAgB,KAAA,CAAM,QAAQ,KAAA,EAAO;AACnD,MAAA,IAAA,GAAO,MAAA,GAAS,CAAA;AAAA,IAClB,CAAA,MAAO;AACL,MAAA;AAAA,IACF;AAEA,IAAA,KAAA,CAAM,cAAA,EAAe;AACrB,IAAA,IAAA,CAAK,SAAA,CAAU,MAAM,IAAI,CAAA;AAAA,EAC3B,CAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOS,UAAA,GAAa,CAAC,KAAA,KAA4B;AACjD,IAAA,MAAM,KAAA,GAAQ,IAAA,CAAK,QAAA,CAAS,KAAA,CAAM,MAAM,CAAA;AACxC,IAAA,IAAI,KAAA,KAAU,EAAA,EAAI,IAAA,CAAK,SAAA,CAAU,OAAO,KAAK,CAAA;AAAA,EAC/C,CAAA;AAAA;AAAA,EAGA,SAAS,MAAA,EAAoC;AAC3C,IAAA,MAAM,IAAA,GAAO,MAAA;AACb,IAAA,IAAI,CAAC,MAAM,OAAO,EAAA;AAClB,IAAA,OAAO,IAAA,CAAK,WAAA,CAAY,SAAA,CAAU,CAAC,IAAA,KAAS,SAAS,IAAA,IAAQ,IAAA,CAAK,QAAA,CAAS,IAAI,CAAC,CAAA;AAAA,EAClF;AAAA;AAAA,EAGA,SAAA,CAAU,OAAe,KAAA,EAAsB;AAC7C,IAAA,MAAM,QAAA,GAAW,KAAK,OAAA,CAAQ,WAAA;AAC9B,IAAA,IAAA,CAAK,OAAA,CAAQ,SAAA,CAAU,KAAA,EAAO,EAAE,OAAO,CAAA;AACvC,IAAA,IAAI,UAAU,QAAA,EAAU;AACtB,MAAA,IAAA,CAAK,QAAA,CAAS,QAAA,EAAU,EAAE,MAAA,EAAQ,EAAE,KAAA,EAAO,IAAA,EAAM,IAAA,CAAK,WAAA,CAAY,KAAK,CAAA,EAAE,EAAG,CAAA;AAAA,IAC9E;AAAA,EACF;AACF","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"]}

package/dist/controllers/scroll_area_controller.js

@@ -58,6 +58,47 @@ var LayoutObserver = class {
   }
 };
 
+// src/utils/logical_scroll.ts
+function isRtl(element) {
+  return window.getComputedStyle(element).direction === "rtl";
+}
+function logicalScrollMetrics(element, horizontal) {
+  const max = Math.max(
+    0,
+    horizontal ? element.scrollWidth - element.clientWidth : element.scrollHeight - element.clientHeight
+  );
+  const raw = horizontal ? element.scrollLeft : element.scrollTop;
+  const position = horizontal && isRtl(element) ? -raw : raw;
+  return { position: Math.min(max, Math.max(0, position)), max };
+}
+
+// src/utils/tabindex_loan.ts
+var TabindexLoan = class {
+  #value;
+  #lent = /* @__PURE__ */ new Set();
+  /**
+   * @param value - the `tabindex` to lend. `"-1"` (the default) is
+   *   programmatically focusable but not a Tab stop; `"0"` is a real Tab stop,
+   *   which a scroll region with no focusable content of its own needs.
+   */
+  constructor(value = "-1") {
+    this.#value = value;
+  }
+  /** Lends `element` the value; no-ops when it already carries a `tabindex`. */
+  lend(element) {
+    if (element.hasAttribute("tabindex")) return;
+    element.setAttribute("tabindex", this.#value);
+    this.#lent.add(element);
+  }
+  /** Takes back every loan whose value is still the one that was lent. */
+  returnAll() {
+    for (const element of this.#lent) {
+      if (element.getAttribute("tabindex") === this.#value) element.removeAttribute("tabindex");
+    }
+    this.#lent.clear();
+  }
+};
+
 // src/controllers/scroll_area_controller.ts
 var FOCUSABLE_SELECTOR = [
   "a[href]",
@@ -76,10 +117,12 @@ var ScrollAreaController = class extends Controller {
   };
   static events = ["reach"];
   #layout = new LayoutObserver(() => this.#update());
+  /** 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. */
-  #addedTabindex = false;
+  #tabindex = new TabindexLoan("0");
   /** Whether this controller added `role="region"`, for symmetric teardown. */
   #addedRole = false;
   #onScroll = () => {
@@ -90,6 +133,18 @@ var ScrollAreaController = class extends Controller {
     this.viewportTarget.addEventListener("scroll", this.#onScroll, { passive: true });
     this.#layout.observe(this.viewportTarget);
     this.#layout.observeViewport();
+    if (typeof MutationObserver !== "undefined") {
+      this.#content = new MutationObserver(() => {
+        if (!this.hasViewportTarget) return;
+        const vp = this.viewportTarget;
+        this.#syncKeyboardReach(vp, this.#syncOverflow(vp));
+      });
+      this.#content.observe(this.viewportTarget, {
+        subtree: true,
+        childList: true,
+        attributes: true
+      });
+    }
     this.#update();
   }
   disconnect() {
@@ -98,14 +153,15 @@ var ScrollAreaController = class extends Controller {
       this.#clearAddedAttributes(this.viewportTarget);
     }
     this.#layout.disconnect();
+    this.#content?.disconnect();
+    this.#content = 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 overflowing = this.#measureOverflow(vp);
-    this.element.setAttribute("data-overflow", overflowing ? "true" : "false");
+    const overflowing = this.#syncOverflow(vp);
     this.#syncKeyboardReach(vp, overflowing);
     const { position, progress } = this.#measurePosition(vp);
     this.element.setAttribute("data-scroll", position);
@@ -119,6 +175,21 @@ var ScrollAreaController = class extends Controller {
     }
   }
   /** Whether the viewport can scroll on the configured axis. */
+  /**
+   * Measures overflow and reflects the `data-overflow` hook.
+   *
+   * The write is skipped when the value is unchanged. An identical `setAttribute` still
+   * queues a MutationRecord, and markup that puts the viewport target on the controller
+   * element itself would then have the content observer trigger its own next callback.
+   */
+  #syncOverflow(vp) {
+    const overflowing = this.#measureOverflow(vp);
+    const next = overflowing ? "true" : "false";
+    if (this.element.getAttribute("data-overflow") !== next) {
+      this.element.setAttribute("data-overflow", next);
+    }
+    return overflowing;
+  }
   #measureOverflow(vp) {
     const o = this.orientationValue;
     const vertical = o !== "horizontal" && vp.scrollHeight > vp.clientHeight + EDGE_EPSILON;
@@ -131,8 +202,7 @@ var ScrollAreaController = class extends Controller {
    */
   #measurePosition(vp) {
     const horizontalPrimary = this.orientationValue === "horizontal" || this.orientationValue === "both" && vp.scrollHeight <= vp.clientHeight + EDGE_EPSILON;
-    const scrollPos = horizontalPrimary ? vp.scrollLeft : vp.scrollTop;
-    const maxScroll = horizontalPrimary ? vp.scrollWidth - vp.clientWidth : vp.scrollHeight - vp.clientHeight;
+    const { position: scrollPos, max: maxScroll } = logicalScrollMetrics(vp, horizontalPrimary);
     if (maxScroll <= EDGE_EPSILON) return { position: "start", progress: 0 };
     const progress = Math.min(1, Math.max(0, scrollPos / maxScroll));
     if (scrollPos <= EDGE_EPSILON) return { position: "start", progress };
@@ -147,10 +217,7 @@ var ScrollAreaController = class extends Controller {
   #syncKeyboardReach(vp, overflowing) {
     const wantsTabindex = overflowing && !this.#hasFocusableContent(vp);
     if (wantsTabindex) {
-      if (!vp.hasAttribute("tabindex")) {
-        vp.setAttribute("tabindex", "0");
-        this.#addedTabindex = true;
-      }
+      this.#tabindex.lend(vp);
       if (!vp.hasAttribute("role") && this.#hasAccessibleName(vp)) {
         vp.setAttribute("role", "region");
         this.#addedRole = true;
@@ -161,17 +228,37 @@ var ScrollAreaController = class extends Controller {
   }
   /** Removes (and resets the flags for) only the attributes this controller added. */
   #clearAddedAttributes(vp) {
-    if (this.#addedTabindex) {
-      vp.removeAttribute("tabindex");
-      this.#addedTabindex = false;
-    }
+    this.#tabindex.returnAll();
     if (this.#addedRole) {
       vp.removeAttribute("role");
       this.#addedRole = false;
     }
   }
+  /**
+   * Whether the viewport owns something the user can Tab to *right now*.
+   *
+   * The selector alone is not enough: a `display: none` button still matches it,
+   * so a viewport whose only control is revealed on demand would never get a tab
+   * stop — leaving it unreachable by keyboard exactly while it has nothing else to
+   * offer. Only rendered candidates count.
+   */
   #hasFocusableContent(vp) {
-    return vp.querySelector(FOCUSABLE_SELECTOR) !== null;
+    return Array.from(vp.querySelectorAll(FOCUSABLE_SELECTOR)).some(
+      (el) => this.#isRendered(el)
+    );
+  }
+  /**
+   * Whether `el` is actually rendered, and so can hold focus.
+   *
+   * `checkVisibility()` answers this for every way CSS can remove a box, including
+   * a class-driven `display: none` that no attribute reveals. The `hidden` walk in
+   * front of it is not redundant: it is the one case a DOM-only environment with no
+   * layout engine has to be told about explicitly.
+   */
+  #isRendered(el) {
+    if (el.closest("[hidden]") !== null) return false;
+    const check = el.checkVisibility;
+    return typeof check === "function" ? check.call(el, { visibilityProperty: true }) : true;
   }
   #hasAccessibleName(vp) {
     return vp.hasAttribute("aria-label") || vp.hasAttribute("aria-labelledby");

package/dist/controllers/scroll_area_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/layout_observer.ts","../../src/controllers/scroll_area_controller.ts"],"names":[],"mappings":"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","file":"scroll_area_controller.js","sourcesContent":["/**\n * Unified element-size and viewport observation for Stimeo controllers.\n *\n * Layout-sensitive widgets (sliders, resizable panes, scroll spies, popovers)\n * need to react both to their *own* box changing — via {@link ResizeObserver} —\n * and to the *viewport* changing — via the `window` `resize` event. Wiring those\n * two sources by hand in every controller risks leaked listeners on\n * `disconnect()`. {@link LayoutObserver} owns both behind one callback and one\n * {@link LayoutObserver.disconnect | disconnect()} that releases everything.\n *\n * Behavior only: the helper reports *that* layout changed; it never reads or\n * writes styles. Consumers decide what to recompute.\n */\n\n/** Invoked whenever an observed element or the viewport changes size. */\nexport type LayoutCallback = () => void;\n\n/** Constructs a {@link ResizeObserver}; injectable so tests stay deterministic. */\nexport type ResizeObserverFactory = (callback: ResizeObserverCallback) => ResizeObserver;\n\n/** Options for {@link LayoutObserver}. */\nexport interface LayoutObserverOptions {\n  /**\n   * Factory for the {@link ResizeObserver} used by {@link LayoutObserver.observe}.\n   * Defaults to the global constructor; override it in tests, or to no-op in\n   * environments where `ResizeObserver` is unavailable.\n   */\n  resizeObserverFactory?: ResizeObserverFactory;\n}\n\n/**\n * Observes element resizes and/or viewport resizes through a single callback,\n * with guaranteed teardown.\n *\n * @example\n * ```ts\n * #layout = new LayoutObserver(() => this.#reposition());\n *\n * connect() {\n *   this.#layout.observe(this.panelTarget);\n *   this.#layout.observeViewport();\n * }\n *\n * disconnect() {\n *   this.#layout.disconnect();\n * }\n * ```\n */\nexport class LayoutObserver {\n  readonly #callback: LayoutCallback;\n  readonly #resizeObserverFactory: ResizeObserverFactory | null;\n  #resizeObserver: ResizeObserver | null = null;\n  #observingViewport = false;\n\n  /** Stable bound handler so add/removeEventListener target the same reference. */\n  readonly #handleViewportResize = (): void => {\n    this.#callback();\n  };\n\n  constructor(callback: LayoutCallback, options: LayoutObserverOptions = {}) {\n    this.#callback = callback;\n    this.#resizeObserverFactory =\n      options.resizeObserverFactory ??\n      (typeof ResizeObserver === \"undefined\" ? null : (cb) => new ResizeObserver(cb));\n  }\n\n  /**\n   * Starts observing an element's size. Repeated calls observe additional\n   * elements through the same shared observer. No-ops when no\n   * `ResizeObserver` implementation is available.\n   */\n  observe(element: Element): void {\n    if (!this.#resizeObserverFactory) return;\n    if (!this.#resizeObserver) {\n      this.#resizeObserver = this.#resizeObserverFactory(() => {\n        this.#callback();\n      });\n    }\n    this.#resizeObserver.observe(element);\n  }\n\n  /** Stops observing a single element while leaving any others in place. */\n  unobserve(element: Element): void {\n    this.#resizeObserver?.unobserve(element);\n  }\n\n  /** Starts observing viewport resizes. Idempotent: the listener is added once. */\n  observeViewport(): void {\n    if (this.#observingViewport) return;\n    this.#observingViewport = true;\n    window.addEventListener(\"resize\", this.#handleViewportResize);\n  }\n\n  /** Stops observing viewport resizes without affecting element observation. */\n  unobserveViewport(): void {\n    if (!this.#observingViewport) return;\n    this.#observingViewport = false;\n    window.removeEventListener(\"resize\", this.#handleViewportResize);\n  }\n\n  /**\n   * Releases every observation: disconnects the {@link ResizeObserver} and\n   * removes the viewport listener. Safe to call multiple times. Call this from a\n   * controller's `disconnect()`.\n   */\n  disconnect(): void {\n    this.#resizeObserver?.disconnect();\n    this.#resizeObserver = null;\n    this.unobserveViewport();\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { LayoutObserver } from \"../utils/layout_observer\";\n\n/** A CSS selector for natively focusable / author-focusable descendants. */\nconst FOCUSABLE_SELECTOR = [\n  \"a[href]\",\n  \"button:not([disabled])\",\n  \"input:not([disabled])\",\n  \"select:not([disabled])\",\n  \"textarea:not([disabled])\",\n  \"[tabindex]:not([tabindex='-1'])\",\n  \"[contenteditable='true']\",\n].join(\",\");\n\n/** Distance from an edge (px) treated as fully reached; absorbs sub-pixel scroll. */\nconst EDGE_EPSILON = 1;\n\n/**\n * Headless **Scroll Area** behavior: keyboard reachability and scroll-state hooks\n * for a natively scrolling region. No custom scrollbar — the native one is\n * respected; this only adds a11y and CSS state.\n *\n * Markup contract (identifier: `stimeo--scroll-area`):\n *   <div data-controller=\"stimeo--scroll-area\"\n *        data-stimeo--scroll-area-orientation-value=\"vertical\">\n *     <div data-stimeo--scroll-area-target=\"viewport\" aria-label=\"Log output\">\n *       <!-- long content -->\n *     </div>\n *   </div>\n *\n * When the content overflows and the viewport holds no focusable elements of its\n * own, the viewport is made keyboard-scrollable (`tabindex=\"0\"`, plus `role=\"region\"`\n * when it already has an accessible name). Scroll position is published as\n * `data-scroll` (`start`/`middle`/`end`), overflow as `data-overflow`, and progress\n * as `--stimeo-scroll-progress` (0–1) so consumer CSS can draw scroll shadows.\n *\n * @remarks\n * Behavior only. The `scroll` listener and {@link LayoutObserver} (element +\n * viewport resize) are torn down on `disconnect()` (Turbo navigation included).\n * `role=\"region\"` is added only when the viewport is already named, so a scrollable\n * region never becomes an unlabeled landmark.\n */\nexport class ScrollAreaController extends Controller<HTMLElement> {\n  static override targets = [\"viewport\"];\n  static override values = {\n    orientation: { type: String, default: \"vertical\" },\n  };\n  static events = [\"reach\"] as const;\n\n  declare readonly viewportTarget: HTMLElement;\n  declare readonly hasViewportTarget: boolean;\n\n  declare orientationValue: string;\n\n  readonly #layout = new LayoutObserver(() => this.#update());\n  /** Last edge reported via `reach`, so the event fires once per arrival. */\n  #lastEdge: \"start\" | \"end\" | null = null;\n  /** Whether this controller added `tabindex`, so teardown only removes its own. */\n  #addedTabindex = false;\n  /** Whether this controller added `role=\"region\"`, for symmetric teardown. */\n  #addedRole = false;\n\n  readonly #onScroll = (): void => {\n    this.#update();\n  };\n\n  override connect(): void {\n    if (!this.hasViewportTarget) return;\n    this.viewportTarget.addEventListener(\"scroll\", this.#onScroll, { passive: true });\n    this.#layout.observe(this.viewportTarget);\n    this.#layout.observeViewport();\n    this.#update();\n  }\n\n  override disconnect(): void {\n    if (this.hasViewportTarget) {\n      this.viewportTarget.removeEventListener(\"scroll\", this.#onScroll);\n      // Remove only the keyboard-reach attributes this controller added, so a\n      // Turbo cache snapshot never preserves a controller-owned tab stop /\n      // landmark (controller-added state must not outlive the controller).\n      this.#clearAddedAttributes(this.viewportTarget);\n    }\n    this.#layout.disconnect();\n    this.#lastEdge = null;\n  }\n\n  /** Re-measures overflow and scroll position and reflects the state hooks. */\n  #update(): void {\n    if (!this.hasViewportTarget) return;\n    const vp = this.viewportTarget;\n    const overflowing = this.#measureOverflow(vp);\n\n    this.element.setAttribute(\"data-overflow\", overflowing ? \"true\" : \"false\");\n    this.#syncKeyboardReach(vp, overflowing);\n\n    const { position, progress } = this.#measurePosition(vp);\n    this.element.setAttribute(\"data-scroll\", position);\n    this.element.style.setProperty(\"--stimeo-scroll-progress\", String(progress));\n\n    const edge = position === \"start\" ? \"start\" : position === \"end\" ? \"end\" : null;\n    if (overflowing && edge && edge !== this.#lastEdge) {\n      this.#lastEdge = edge;\n      this.dispatch(\"reach\", { detail: { edge } });\n    } else if (!edge) {\n      this.#lastEdge = null;\n    }\n  }\n\n  /** Whether the viewport can scroll on the configured axis. */\n  #measureOverflow(vp: HTMLElement): boolean {\n    const o = this.orientationValue;\n    const vertical = o !== \"horizontal\" && vp.scrollHeight > vp.clientHeight + EDGE_EPSILON;\n    const horizontal = o !== \"vertical\" && vp.scrollWidth > vp.clientWidth + EDGE_EPSILON;\n    return vertical || horizontal;\n  }\n\n  /**\n   * Reports the scroll position bucket and 0–1 progress on the primary axis. For\n   * `both`, the vertical axis is used when it overflows, otherwise the horizontal.\n   */\n  #measurePosition(vp: HTMLElement): {\n    position: \"start\" | \"middle\" | \"end\";\n    progress: number;\n  } {\n    const horizontalPrimary =\n      this.orientationValue === \"horizontal\" ||\n      (this.orientationValue === \"both\" && vp.scrollHeight <= vp.clientHeight + EDGE_EPSILON);\n\n    const scrollPos = horizontalPrimary ? vp.scrollLeft : vp.scrollTop;\n    const maxScroll = horizontalPrimary\n      ? vp.scrollWidth - vp.clientWidth\n      : vp.scrollHeight - vp.clientHeight;\n\n    if (maxScroll <= EDGE_EPSILON) return { position: \"start\", progress: 0 };\n\n    const progress = Math.min(1, Math.max(0, scrollPos / maxScroll));\n    if (scrollPos <= EDGE_EPSILON) return { position: \"start\", progress };\n    if (scrollPos >= maxScroll - EDGE_EPSILON) return { position: \"end\", progress };\n    return { position: \"middle\", progress };\n  }\n\n  /**\n   * Makes the viewport keyboard-scrollable when it overflows and contains no\n   * focusable elements of its own (avoiding a double tab stop). Adds `role=\"region\"`\n   * only when the viewport already carries an accessible name.\n   */\n  #syncKeyboardReach(vp: HTMLElement, overflowing: boolean): void {\n    const wantsTabindex = overflowing && !this.#hasFocusableContent(vp);\n\n    if (wantsTabindex) {\n      if (!vp.hasAttribute(\"tabindex\")) {\n        vp.setAttribute(\"tabindex\", \"0\");\n        this.#addedTabindex = true;\n      }\n      if (!vp.hasAttribute(\"role\") && this.#hasAccessibleName(vp)) {\n        vp.setAttribute(\"role\", \"region\");\n        this.#addedRole = true;\n      }\n    } else {\n      this.#clearAddedAttributes(vp);\n    }\n  }\n\n  /** Removes (and resets the flags for) only the attributes this controller added. */\n  #clearAddedAttributes(vp: HTMLElement): void {\n    if (this.#addedTabindex) {\n      vp.removeAttribute(\"tabindex\");\n      this.#addedTabindex = false;\n    }\n    if (this.#addedRole) {\n      vp.removeAttribute(\"role\");\n      this.#addedRole = false;\n    }\n  }\n\n  #hasFocusableContent(vp: HTMLElement): boolean {\n    return vp.querySelector(FOCUSABLE_SELECTOR) !== null;\n  }\n\n  #hasAccessibleName(vp: HTMLElement): boolean {\n    return vp.hasAttribute(\"aria-label\") || vp.hasAttribute(\"aria-labelledby\");\n  }\n}\n"]}
+{"version":3,"sources":["../../src/utils/layout_observer.ts","../../src/utils/logical_scroll.ts","../../src/utils/tabindex_loan.ts","../../src/controllers/scroll_area_controller.ts"],"names":[],"mappings":"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","file":"scroll_area_controller.js","sourcesContent":["/**\n * Unified element-size and viewport observation for Stimeo controllers.\n *\n * Layout-sensitive widgets (sliders, resizable panes, scroll spies, popovers)\n * need to react both to their *own* box changing — via {@link ResizeObserver} —\n * and to the *viewport* changing — via the `window` `resize` event. Wiring those\n * two sources by hand in every controller risks leaked listeners on\n * `disconnect()`. {@link LayoutObserver} owns both behind one callback and one\n * {@link LayoutObserver.disconnect | disconnect()} that releases everything.\n *\n * Behavior only: the helper reports *that* layout changed; it never reads or\n * writes styles. Consumers decide what to recompute.\n */\n\n/** Invoked whenever an observed element or the viewport changes size. */\nexport type LayoutCallback = () => void;\n\n/** Constructs a {@link ResizeObserver}; injectable so tests stay deterministic. */\nexport type ResizeObserverFactory = (callback: ResizeObserverCallback) => ResizeObserver;\n\n/** Options for {@link LayoutObserver}. */\nexport interface LayoutObserverOptions {\n  /**\n   * Factory for the {@link ResizeObserver} used by {@link LayoutObserver.observe}.\n   * Defaults to the global constructor; override it in tests, or to no-op in\n   * environments where `ResizeObserver` is unavailable.\n   */\n  resizeObserverFactory?: ResizeObserverFactory;\n}\n\n/**\n * Observes element resizes and/or viewport resizes through a single callback,\n * with guaranteed teardown.\n *\n * @example\n * ```ts\n * #layout = new LayoutObserver(() => this.#reposition());\n *\n * connect() {\n *   this.#layout.observe(this.panelTarget);\n *   this.#layout.observeViewport();\n * }\n *\n * disconnect() {\n *   this.#layout.disconnect();\n * }\n * ```\n */\nexport class LayoutObserver {\n  readonly #callback: LayoutCallback;\n  readonly #resizeObserverFactory: ResizeObserverFactory | null;\n  #resizeObserver: ResizeObserver | null = null;\n  #observingViewport = false;\n\n  /** Stable bound handler so add/removeEventListener target the same reference. */\n  readonly #handleViewportResize = (): void => {\n    this.#callback();\n  };\n\n  constructor(callback: LayoutCallback, options: LayoutObserverOptions = {}) {\n    this.#callback = callback;\n    this.#resizeObserverFactory =\n      options.resizeObserverFactory ??\n      (typeof ResizeObserver === \"undefined\" ? null : (cb) => new ResizeObserver(cb));\n  }\n\n  /**\n   * Starts observing an element's size. Repeated calls observe additional\n   * elements through the same shared observer. No-ops when no\n   * `ResizeObserver` implementation is available.\n   */\n  observe(element: Element): void {\n    if (!this.#resizeObserverFactory) return;\n    if (!this.#resizeObserver) {\n      this.#resizeObserver = this.#resizeObserverFactory(() => {\n        this.#callback();\n      });\n    }\n    this.#resizeObserver.observe(element);\n  }\n\n  /** Stops observing a single element while leaving any others in place. */\n  unobserve(element: Element): void {\n    this.#resizeObserver?.unobserve(element);\n  }\n\n  /** Starts observing viewport resizes. Idempotent: the listener is added once. */\n  observeViewport(): void {\n    if (this.#observingViewport) return;\n    this.#observingViewport = true;\n    window.addEventListener(\"resize\", this.#handleViewportResize);\n  }\n\n  /** Stops observing viewport resizes without affecting element observation. */\n  unobserveViewport(): void {\n    if (!this.#observingViewport) return;\n    this.#observingViewport = false;\n    window.removeEventListener(\"resize\", this.#handleViewportResize);\n  }\n\n  /**\n   * Releases every observation: disconnects the {@link ResizeObserver} and\n   * removes the viewport listener. Safe to call multiple times. Call this from a\n   * controller's `disconnect()`.\n   */\n  disconnect(): void {\n    this.#resizeObserver?.disconnect();\n    this.#resizeObserver = null;\n    this.unobserveViewport();\n  }\n}\n","/** 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","/**\n * Shared bookkeeping for a `tabindex` a controller lends an element temporarily.\n *\n * A controller that must move focus somewhere the author never made focusable\n * (a landmark root, a scroll destination) reaches for the same trick: add a\n * `tabindex` just-in-time and hand it back once it is no longer needed. The\n * borrow is the easy half; the return is what the two conditions below are for.\n *\n * **Returning needs two conditions, not one.** Owning the borrow is not enough:\n * the attribute must also still hold the value this instance wrote. A consumer\n * that changed it afterwards — `tabindex=\"0\"` to make the root its own Tab stop\n * — owns it now, and removing it there silently discards authored markup. The\n * bookkeeping is dropped either way, since the loan is over regardless of who\n * ends up owning the value.\n *\n * **Never borrow over an existing value.** An element that already carries a\n * `tabindex` is the author's to control, so there is nothing to lend and nothing\n * to return.\n *\n * The registry is keyed by element, so a controller borrowing on a single\n * element (`this.element`) and one borrowing across a changing set of targets\n * use the same API — the single-element case is a set of one. It holds no\n * opinion about *when* to borrow or where focus goes next; that stays in the\n * controller.\n *\n * **The API is deliberately two methods.** This file's own doc block is dropped\n * from `dist`, but every member comment is inlined into **each** consumer entry\n * (`tsup` builds with `splitting: false`), so rationale belongs here, only the\n * contract belongs on the members, and every method no consumer calls is still\n * paid for once per consumer entry.\n *\n * @example\n * ```ts\n * readonly #tabindex = new TabindexLoan();\n *\n * #rescueFocus() {\n *   this.#tabindex.lend(this.element);\n *   this.element.focus();\n * }\n *\n * disconnect() {\n *   this.#tabindex.returnAll();\n * }\n * ```\n */\nexport class TabindexLoan<T extends HTMLElement = HTMLElement> {\n  readonly #value: string;\n  readonly #lent = new Set<T>();\n\n  /**\n   * @param value - the `tabindex` to lend. `\"-1\"` (the default) is\n   *   programmatically focusable but not a Tab stop; `\"0\"` is a real Tab stop,\n   *   which a scroll region with no focusable content of its own needs.\n   */\n  constructor(value: string = \"-1\") {\n    this.#value = value;\n  }\n\n  /** Lends `element` the value; no-ops when it already carries a `tabindex`. */\n  lend(element: T): void {\n    if (element.hasAttribute(\"tabindex\")) return;\n    element.setAttribute(\"tabindex\", this.#value);\n    this.#lent.add(element);\n  }\n\n  /** Takes back every loan whose value is still the one that was lent. */\n  returnAll(): void {\n    for (const element of this.#lent) {\n      if (element.getAttribute(\"tabindex\") === this.#value) element.removeAttribute(\"tabindex\");\n    }\n    this.#lent.clear();\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { LayoutObserver } from \"../utils/layout_observer\";\nimport { logicalScrollMetrics } from \"../utils/logical_scroll\";\nimport { TabindexLoan } from \"../utils/tabindex_loan\";\n\n/** A CSS selector for natively focusable / author-focusable descendants. */\nconst FOCUSABLE_SELECTOR = [\n  \"a[href]\",\n  \"button:not([disabled])\",\n  \"input:not([disabled])\",\n  \"select:not([disabled])\",\n  \"textarea:not([disabled])\",\n  \"[tabindex]:not([tabindex='-1'])\",\n  \"[contenteditable='true']\",\n].join(\",\");\n\n/** Distance from an edge (px) treated as fully reached; absorbs sub-pixel scroll. */\nconst EDGE_EPSILON = 1;\n\n/** `Element.checkVisibility` (widely available); absent in older engines. */\ninterface VisibilityCheckable {\n  checkVisibility?: (options?: { visibilityProperty?: boolean }) => boolean;\n}\n\n/**\n * Headless **Scroll Area** behavior: keyboard reachability and scroll-state hooks\n * for a natively scrolling region. No custom scrollbar — the native one is\n * respected; this only adds a11y and CSS state.\n *\n * Markup contract (identifier: `stimeo--scroll-area`):\n *   <div data-controller=\"stimeo--scroll-area\"\n *        data-stimeo--scroll-area-orientation-value=\"vertical\">\n *     <div data-stimeo--scroll-area-target=\"viewport\" aria-label=\"Log output\">\n *       <!-- long content -->\n *     </div>\n *   </div>\n *\n * When the content overflows and the viewport holds no focusable elements of its\n * own, the viewport is made keyboard-scrollable (`tabindex=\"0\"`, plus `role=\"region\"`\n * when it already has an accessible name). Scroll position is published as\n * `data-scroll` (`start`/`middle`/`end`), overflow as `data-overflow`, and progress\n * as `--stimeo-scroll-progress` (0–1) so consumer CSS can draw scroll shadows.\n *\n * @remarks\n * Behavior only. The `scroll` listener and {@link LayoutObserver} (element +\n * viewport resize) are torn down on `disconnect()` (Turbo navigation included).\n * `role=\"region\"` is added only when the viewport is already named, so a scrollable\n * region never becomes an unlabeled landmark.\n */\nexport class ScrollAreaController extends Controller<HTMLElement> {\n  static override targets = [\"viewport\"];\n  static override values = {\n    orientation: { type: String, default: \"vertical\" },\n  };\n  static events = [\"reach\"] as const;\n\n  declare readonly viewportTarget: HTMLElement;\n  declare readonly hasViewportTarget: boolean;\n\n  declare orientationValue: string;\n\n  readonly #layout = new LayoutObserver(() => this.#update());\n  /** Re-checks the tab stop when the viewport's focusable content comes or goes. */\n  #content: MutationObserver | null = null;\n  /** Last edge reported via `reach`, so the event fires once per arrival. */\n  #lastEdge: \"start\" | \"end\" | null = null;\n  /** Whether this controller added `tabindex`, so teardown only removes its own. */\n  readonly #tabindex = new TabindexLoan(\"0\");\n  /** Whether this controller added `role=\"region\"`, for symmetric teardown. */\n  #addedRole = false;\n\n  readonly #onScroll = (): void => {\n    this.#update();\n  };\n\n  override connect(): void {\n    if (!this.hasViewportTarget) return;\n    this.viewportTarget.addEventListener(\"scroll\", this.#onScroll, { passive: true });\n    this.#layout.observe(this.viewportTarget);\n    this.#layout.observeViewport();\n    // Overflow follows the box, but focusability follows the content, and the two\n    // change independently: revealing a button inside a fixed-height viewport fires\n    // no resize and no scroll. Without this the tab stop would be stale until the\n    // next unrelated event.\n    //\n    // No `attributeFilter`: what makes a control appear is not confined to its own\n    // attributes — a state hook on an ancestor (`[data-has-new] .jump { display: block }`)\n    // flips it just as well, and that set cannot be enumerated.\n    //\n    // The overflow value is re-measured here rather than reused. A content change moves\n    // the scroll extent without touching the viewport's own box, so a fixed-height\n    // viewport fires no resize when its content shrinks — reusing a cached value would\n    // hand the tab stop to a box that does not scroll. Position and `reach` are\n    // deliberately left alone: the event contract is arrival at an edge, and a content\n    // change is not an arrival.\n    if (typeof MutationObserver !== \"undefined\") {\n      this.#content = new MutationObserver(() => {\n        if (!this.hasViewportTarget) return;\n        const vp = this.viewportTarget;\n        this.#syncKeyboardReach(vp, this.#syncOverflow(vp));\n      });\n      this.#content.observe(this.viewportTarget, {\n        subtree: true,\n        childList: true,\n        attributes: true,\n      });\n    }\n    this.#update();\n  }\n\n  override disconnect(): void {\n    if (this.hasViewportTarget) {\n      this.viewportTarget.removeEventListener(\"scroll\", this.#onScroll);\n      // Remove only the keyboard-reach attributes this controller added, so a\n      // Turbo cache snapshot never preserves a controller-owned tab stop /\n      // landmark (controller-added state must not outlive the controller).\n      this.#clearAddedAttributes(this.viewportTarget);\n    }\n    this.#layout.disconnect();\n    this.#content?.disconnect();\n    this.#content = null;\n    this.#lastEdge = null;\n  }\n\n  /** Re-measures overflow and scroll position and reflects the state hooks. */\n  #update(): void {\n    if (!this.hasViewportTarget) return;\n    const vp = this.viewportTarget;\n    const overflowing = this.#syncOverflow(vp);\n    this.#syncKeyboardReach(vp, overflowing);\n\n    const { position, progress } = this.#measurePosition(vp);\n    this.element.setAttribute(\"data-scroll\", position);\n    this.element.style.setProperty(\"--stimeo-scroll-progress\", String(progress));\n\n    const edge = position === \"start\" ? \"start\" : position === \"end\" ? \"end\" : null;\n    if (overflowing && edge && edge !== this.#lastEdge) {\n      this.#lastEdge = edge;\n      this.dispatch(\"reach\", { detail: { edge } });\n    } else if (!edge) {\n      this.#lastEdge = null;\n    }\n  }\n\n  /** Whether the viewport can scroll on the configured axis. */\n  /**\n   * Measures overflow and reflects the `data-overflow` hook.\n   *\n   * The write is skipped when the value is unchanged. An identical `setAttribute` still\n   * queues a MutationRecord, and markup that puts the viewport target on the controller\n   * element itself would then have the content observer trigger its own next callback.\n   */\n  #syncOverflow(vp: HTMLElement): boolean {\n    const overflowing = this.#measureOverflow(vp);\n    const next = overflowing ? \"true\" : \"false\";\n    if (this.element.getAttribute(\"data-overflow\") !== next) {\n      this.element.setAttribute(\"data-overflow\", next);\n    }\n    return overflowing;\n  }\n\n  #measureOverflow(vp: HTMLElement): boolean {\n    const o = this.orientationValue;\n    const vertical = o !== \"horizontal\" && vp.scrollHeight > vp.clientHeight + EDGE_EPSILON;\n    const horizontal = o !== \"vertical\" && vp.scrollWidth > vp.clientWidth + EDGE_EPSILON;\n    return vertical || horizontal;\n  }\n\n  /**\n   * Reports the scroll position bucket and 0–1 progress on the primary axis. For\n   * `both`, the vertical axis is used when it overflows, otherwise the horizontal.\n   */\n  #measurePosition(vp: HTMLElement): {\n    position: \"start\" | \"middle\" | \"end\";\n    progress: number;\n  } {\n    const horizontalPrimary =\n      this.orientationValue === \"horizontal\" ||\n      (this.orientationValue === \"both\" && vp.scrollHeight <= vp.clientHeight + EDGE_EPSILON);\n\n    const { position: scrollPos, max: maxScroll } = logicalScrollMetrics(vp, horizontalPrimary);\n\n    if (maxScroll <= EDGE_EPSILON) return { position: \"start\", progress: 0 };\n\n    const progress = Math.min(1, Math.max(0, scrollPos / maxScroll));\n    if (scrollPos <= EDGE_EPSILON) return { position: \"start\", progress };\n    if (scrollPos >= maxScroll - EDGE_EPSILON) return { position: \"end\", progress };\n    return { position: \"middle\", progress };\n  }\n\n  /**\n   * Makes the viewport keyboard-scrollable when it overflows and contains no\n   * focusable elements of its own (avoiding a double tab stop). Adds `role=\"region\"`\n   * only when the viewport already carries an accessible name.\n   */\n  #syncKeyboardReach(vp: HTMLElement, overflowing: boolean): void {\n    const wantsTabindex = overflowing && !this.#hasFocusableContent(vp);\n\n    if (wantsTabindex) {\n      this.#tabindex.lend(vp);\n      if (!vp.hasAttribute(\"role\") && this.#hasAccessibleName(vp)) {\n        vp.setAttribute(\"role\", \"region\");\n        this.#addedRole = true;\n      }\n    } else {\n      this.#clearAddedAttributes(vp);\n    }\n  }\n\n  /** Removes (and resets the flags for) only the attributes this controller added. */\n  #clearAddedAttributes(vp: HTMLElement): void {\n    this.#tabindex.returnAll();\n    if (this.#addedRole) {\n      vp.removeAttribute(\"role\");\n      this.#addedRole = false;\n    }\n  }\n\n  /**\n   * Whether the viewport owns something the user can Tab to *right now*.\n   *\n   * The selector alone is not enough: a `display: none` button still matches it,\n   * so a viewport whose only control is revealed on demand would never get a tab\n   * stop — leaving it unreachable by keyboard exactly while it has nothing else to\n   * offer. Only rendered candidates count.\n   */\n  #hasFocusableContent(vp: HTMLElement): boolean {\n    return Array.from(vp.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)).some((el) =>\n      this.#isRendered(el),\n    );\n  }\n\n  /**\n   * Whether `el` is actually rendered, and so can hold focus.\n   *\n   * `checkVisibility()` answers this for every way CSS can remove a box, including\n   * a class-driven `display: none` that no attribute reveals. The `hidden` walk in\n   * front of it is not redundant: it is the one case a DOM-only environment with no\n   * layout engine has to be told about explicitly.\n   */\n  #isRendered(el: HTMLElement): boolean {\n    if (el.closest(\"[hidden]\") !== null) return false;\n    const check = (el as HTMLElement & VisibilityCheckable).checkVisibility;\n    return typeof check === \"function\" ? check.call(el, { visibilityProperty: true }) : true;\n  }\n\n  #hasAccessibleName(vp: HTMLElement): boolean {\n    return vp.hasAttribute(\"aria-label\") || vp.hasAttribute(\"aria-labelledby\");\n  }\n}\n"]}

package/dist/controllers/scroll_restore_controller.d.ts

@@ -0,0 +1,54 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless **Scroll Restore** behavior: persists and restores the scroll
+ * position of an inner scrolling region across Turbo Drive navigations (and full
+ * reloads within the same tab session). No APG widget — a pure state-preservation
+ * utility, like {@link import("./scroll_visibility_controller").ScrollVisibilityController}
+ * and the Sticky State Observer.
+ *
+ * Markup contract (identifier: `stimeo--scroll-restore`):
+ *   <div data-controller="stimeo--scroll-restore"
+ *        data-stimeo--scroll-restore-key-value="sidebar"
+ *        style="overflow: auto">
+ *     …long content…
+ *   </div>
+ *
+ * Turbo swaps the whole `<body>` on navigation, so an inner scroll container is
+ * rebuilt with `scrollTop` reset to 0. Rather than have every app hand-write a
+ * controller for this (which contradicts a "ship the behavior" library), this
+ * persists the offset under a stable key in `sessionStorage` and restores it on
+ * `connect()`.
+ *
+ * @remarks
+ * Behavior only — it sets no ARIA/`data-*`/CSS and never moves focus (restore is
+ * a plain `scrollTop`/`scrollLeft` assignment). The `scroll` listener is internal
+ * and `passive` (no consumer `data-action` needed): each event records the live
+ * offset synchronously, and a `requestAnimationFrame` coalesces the writes to
+ * `sessionStorage`. On `disconnect()` (Turbo navigation included) it flushes the
+ * **last captured** offset rather than re-reading the element — by the time Turbo
+ * fires `disconnect` it has already detached the node, whose `scrollTop` then
+ * reads `0`, so a fresh read would clobber the saved position with `0`. Keying by
+ * `key` (falling back to the element `id`) in `sessionStorage` makes it
+ * multi-instance safe and survives full reloads — unlike a module-scope variable,
+ * which only survives Turbo Drive and assumes a single instance.
+ */
+declare class ScrollRestoreController extends Controller<HTMLElement> {
+    #private;
+    static values: {
+        key: {
+            type: StringConstructor;
+            default: string;
+        };
+        axis: {
+            type: StringConstructor;
+            default: string;
+        };
+    };
+    keyValue: string;
+    axisValue: string;
+    connect(): void;
+    disconnect(): void;
+}
+
+export { ScrollRestoreController };

package/dist/controllers/scroll_restore_controller.js

@@ -0,0 +1,93 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/scroll_restore_controller.ts
+var ScrollRestoreController = class extends Controller {
+  static values = {
+    key: { type: String, default: "" },
+    axis: { type: String, default: "vertical" }
+  };
+  /** Pending rAF id that coalesces scroll bursts into one save. */
+  #rafId = null;
+  /** Resolved storage key; empty disables persistence (no key and no id). */
+  #storageKey = "";
+  /** Last offset captured while the element was live; persisted as-is on teardown. */
+  #lastTop = 0;
+  #lastLeft = 0;
+  #onScroll = () => {
+    this.#capture();
+    if (this.#rafId !== null) return;
+    this.#rafId = requestAnimationFrame(() => {
+      this.#rafId = null;
+      this.#persist();
+    });
+  };
+  connect() {
+    this.#storageKey = this.#resolveKey();
+    if (!this.#storageKey) return;
+    this.#restore();
+    this.element.addEventListener("scroll", this.#onScroll, { passive: true });
+  }
+  disconnect() {
+    if (!this.#storageKey) return;
+    this.element.removeEventListener("scroll", this.#onScroll);
+    if (this.#rafId !== null) {
+      cancelAnimationFrame(this.#rafId);
+      this.#rafId = null;
+    }
+    this.#persist();
+  }
+  /** Records the live scroll offset for the configured axis. */
+  #capture() {
+    if (this.#tracksVertical) this.#lastTop = this.element.scrollTop;
+    if (this.#tracksHorizontal) this.#lastLeft = this.element.scrollLeft;
+  }
+  /** Persists the last captured scroll offset for the configured axis. */
+  #persist() {
+    const data = {};
+    if (this.#tracksVertical) data.top = this.#lastTop;
+    if (this.#tracksHorizontal) data.left = this.#lastLeft;
+    try {
+      sessionStorage.setItem(this.#storageKey, JSON.stringify(data));
+    } catch {
+    }
+  }
+  /** Applies the persisted scroll offset, if any, without moving focus. */
+  #restore() {
+    let raw = null;
+    try {
+      raw = sessionStorage.getItem(this.#storageKey);
+    } catch {
+      return;
+    }
+    if (raw === null) return;
+    let data;
+    try {
+      data = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    if (this.#tracksVertical && typeof data.top === "number") {
+      this.element.scrollTop = data.top;
+      this.#lastTop = data.top;
+    }
+    if (this.#tracksHorizontal && typeof data.left === "number") {
+      this.element.scrollLeft = data.left;
+      this.#lastLeft = data.left;
+    }
+  }
+  /** The `sessionStorage` key: explicit `key`, else the element `id`, else none. */
+  #resolveKey() {
+    const base = this.keyValue || this.element.id;
+    return base ? `stimeo--scroll-restore:${base}` : "";
+  }
+  get #tracksVertical() {
+    return this.axisValue !== "horizontal";
+  }
+  get #tracksHorizontal() {
+    return this.axisValue === "horizontal" || this.axisValue === "both";
+  }
+};
+
+export { ScrollRestoreController };
+//# sourceMappingURL=scroll_restore_controller.js.map
+//# sourceMappingURL=scroll_restore_controller.js.map

package/dist/controllers/scroll_restore_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/controllers/scroll_restore_controller.ts"],"names":[],"mappings":"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","file":"scroll_restore_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/** Persisted scroll position; fields are present only for the saved axis. */\ninterface StoredScroll {\n  top?: number;\n  left?: number;\n}\n\n/**\n * Headless **Scroll Restore** behavior: persists and restores the scroll\n * position of an inner scrolling region across Turbo Drive navigations (and full\n * reloads within the same tab session). No APG widget — a pure state-preservation\n * utility, like {@link import(\"./scroll_visibility_controller\").ScrollVisibilityController}\n * and the Sticky State Observer.\n *\n * Markup contract (identifier: `stimeo--scroll-restore`):\n *   <div data-controller=\"stimeo--scroll-restore\"\n *        data-stimeo--scroll-restore-key-value=\"sidebar\"\n *        style=\"overflow: auto\">\n *     …long content…\n *   </div>\n *\n * Turbo swaps the whole `<body>` on navigation, so an inner scroll container is\n * rebuilt with `scrollTop` reset to 0. Rather than have every app hand-write a\n * controller for this (which contradicts a \"ship the behavior\" library), this\n * persists the offset under a stable key in `sessionStorage` and restores it on\n * `connect()`.\n *\n * @remarks\n * Behavior only — it sets no ARIA/`data-*`/CSS and never moves focus (restore is\n * a plain `scrollTop`/`scrollLeft` assignment). The `scroll` listener is internal\n * and `passive` (no consumer `data-action` needed): each event records the live\n * offset synchronously, and a `requestAnimationFrame` coalesces the writes to\n * `sessionStorage`. On `disconnect()` (Turbo navigation included) it flushes the\n * **last captured** offset rather than re-reading the element — by the time Turbo\n * fires `disconnect` it has already detached the node, whose `scrollTop` then\n * reads `0`, so a fresh read would clobber the saved position with `0`. Keying by\n * `key` (falling back to the element `id`) in `sessionStorage` makes it\n * multi-instance safe and survives full reloads — unlike a module-scope variable,\n * which only survives Turbo Drive and assumes a single instance.\n */\nexport class ScrollRestoreController extends Controller<HTMLElement> {\n  static override values = {\n    key: { type: String, default: \"\" },\n    axis: { type: String, default: \"vertical\" },\n  };\n\n  declare keyValue: string;\n  declare axisValue: string;\n\n  /** Pending rAF id that coalesces scroll bursts into one save. */\n  #rafId: number | null = null;\n  /** Resolved storage key; empty disables persistence (no key and no id). */\n  #storageKey = \"\";\n  /** Last offset captured while the element was live; persisted as-is on teardown. */\n  #lastTop = 0;\n  #lastLeft = 0;\n\n  readonly #onScroll = (): void => {\n    // Capture synchronously while the element is still connected and measurable;\n    // the rAF only debounces the sessionStorage write, never the read.\n    this.#capture();\n    if (this.#rafId !== null) return;\n    this.#rafId = requestAnimationFrame(() => {\n      this.#rafId = null;\n      this.#persist();\n    });\n  };\n\n  override connect(): void {\n    this.#storageKey = this.#resolveKey();\n    if (!this.#storageKey) return; // No stable key → do nothing (avoid mixing pages).\n    this.#restore();\n    this.element.addEventListener(\"scroll\", this.#onScroll, { passive: true });\n  }\n\n  override disconnect(): void {\n    if (!this.#storageKey) return;\n    this.element.removeEventListener(\"scroll\", this.#onScroll);\n    if (this.#rafId !== null) {\n      cancelAnimationFrame(this.#rafId);\n      this.#rafId = null;\n    }\n    // Flush the last captured offset (a throttled burst may have left the final\n    // frame unsaved). We do NOT re-read the element here: Turbo detaches the node\n    // before disconnect, so its scrollTop is 0 and would overwrite the real value.\n    this.#persist();\n  }\n\n  /** Records the live scroll offset for the configured axis. */\n  #capture(): void {\n    if (this.#tracksVertical) this.#lastTop = this.element.scrollTop;\n    if (this.#tracksHorizontal) this.#lastLeft = this.element.scrollLeft;\n  }\n\n  /** Persists the last captured scroll offset for the configured axis. */\n  #persist(): void {\n    const data: StoredScroll = {};\n    if (this.#tracksVertical) data.top = this.#lastTop;\n    if (this.#tracksHorizontal) data.left = this.#lastLeft;\n    try {\n      sessionStorage.setItem(this.#storageKey, JSON.stringify(data));\n    } catch {\n      // sessionStorage can throw (private mode / quota); persistence is best-effort.\n    }\n  }\n\n  /** Applies the persisted scroll offset, if any, without moving focus. */\n  #restore(): void {\n    let raw: string | null = null;\n    try {\n      raw = sessionStorage.getItem(this.#storageKey);\n    } catch {\n      return;\n    }\n    if (raw === null) return;\n    let data: StoredScroll;\n    try {\n      data = JSON.parse(raw) as StoredScroll;\n    } catch {\n      return;\n    }\n    // Seed the capture cache from the restored value so an immediate teardown\n    // (before any scroll) re-persists the restored position, not 0. Guard by the\n    // configured axis so a stale field from a different axis is never applied.\n    if (this.#tracksVertical && typeof data.top === \"number\") {\n      this.element.scrollTop = data.top;\n      this.#lastTop = data.top;\n    }\n    if (this.#tracksHorizontal && typeof data.left === \"number\") {\n      this.element.scrollLeft = data.left;\n      this.#lastLeft = data.left;\n    }\n  }\n\n  /** The `sessionStorage` key: explicit `key`, else the element `id`, else none. */\n  #resolveKey(): string {\n    const base = this.keyValue || this.element.id;\n    return base ? `stimeo--scroll-restore:${base}` : \"\";\n  }\n\n  get #tracksVertical(): boolean {\n    return this.axisValue !== \"horizontal\";\n  }\n\n  get #tracksHorizontal(): boolean {\n    return this.axisValue === \"horizontal\" || this.axisValue === \"both\";\n  }\n}\n"]}

package/dist/controllers/scroll_visibility_controller.d.ts

@@ -30,9 +30,12 @@ import { Controller } from '@hotwired/stimulus';
  * Behavior only — the look and any transition are the consumer's CSS. The scroll
  * listener is `passive`, coalesced through `requestAnimationFrame`, and removed on
  * `disconnect()` (Turbo navigation included). `toTop` honors
- * `prefers-reduced-motion` by falling back to an instant jump, and can move focus
- * to a `focusSelector` target (given `tabindex="-1"` if needed) to keep keyboard
- * users oriented after the scroll.
+ * `prefers-reduced-motion` by forcing an instant jump independently of the
+ * consumer's CSS `scroll-behavior`, and can move focus to a `focusSelector`
+ * target (given `tabindex="-1"` if needed) to keep keyboard users oriented
+ * after the scroll. A live disconnect removes only a `tabindex="-1"` this
+ * controller instance added; authored tabindex values remain. This teardown does
+ * not claim to rewrite a Turbo cache snapshot that was cloned before disconnect.
  */
 declare class ScrollVisibilityController extends Controller<HTMLElement> {
     #private;