stimeo-ui 0.2.1 → 0.3.0

package/dist/controllers/toggle_group_controller.js

@@ -2,6 +2,17 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/toggle_group_controller.ts
 
+// src/utils/logical_scroll.ts
+function isRtl(element) {
+  return window.getComputedStyle(element).direction === "rtl";
+}
+
+// src/utils/arrow_step.ts
+function isReservedArrowChord(event, allow = []) {
+  if (!event.key.startsWith("Arrow")) return false;
+  return event.altKey && !allow.includes("alt") || event.ctrlKey && !allow.includes("ctrl") || event.metaKey && !allow.includes("meta") || event.shiftKey && !allow.includes("shift");
+}
+
 // src/utils/roving_tabindex.ts
 var RovingTabindex = class {
   /** Returns the current ordered item elements; called on every operation. */
@@ -60,17 +71,27 @@ var ToggleGroupController = class extends Controller {
   }
   /** Arrow/Home/End move focus only; Space/Enter toggle non-button hosts. */
   onKeydown(event) {
+    if (event.defaultPrevented) return;
+    if (isReservedArrowChord(event)) return;
     const current = this.itemTargets.indexOf(event.currentTarget);
     if (current === -1) return;
     let next = null;
+    const rtl = isRtl(this.element);
+    const horizontalStep = (key) => rtl ? key === "ArrowRight" ? -1 : 1 : key === "ArrowRight" ? 1 : -1;
     switch (event.key) {
       case "ArrowRight":
       case "ArrowDown":
-        next = rovingMove(current, this.itemTargets.length, 1);
+        next = rovingMove(
+          current,
+          this.itemTargets.length,
+          event.key === "ArrowDown" ? 1 : horizontalStep(event.key));
         break;
       case "ArrowLeft":
       case "ArrowUp":
-        next = rovingMove(current, this.itemTargets.length, -1);
+        next = rovingMove(
+          current,
+          this.itemTargets.length,
+          event.key === "ArrowUp" ? -1 : horizontalStep(event.key));
         break;
       case "Home":
         next = 0;

package/dist/controllers/toggle_group_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/roving_tabindex.ts","../../src/controllers/toggle_group_controller.ts"],"names":[],"mappings":"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","file":"toggle_group_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, rovingMove } from \"../utils/roving_tabindex\";\n\n/**\n * Headless, accessible toggle-button group behavior.\n *\n * Markup contract (identifier: `stimeo--toggle-group`):\n *   <div data-controller=\"stimeo--toggle-group\"\n *        data-stimeo--toggle-group-mode-value=\"single\"\n *        role=\"group\" aria-label=\"Text style\">\n *     <button type=\"button\" aria-pressed=\"true\" tabindex=\"0\" data-value=\"bold\"\n *             data-stimeo--toggle-group-target=\"item\"\n *             data-action=\"click->stimeo--toggle-group#toggle\n *                          keydown->stimeo--toggle-group#onKeydown\">Bold</button>\n *     <!-- more items; exactly one tabindex=0 -->\n *   </div>\n *\n * Implements the WAI-ARIA APG **Button (toggle)** pattern with **Toolbar**-style\n * roving navigation. Each item's pressed state is `aria-pressed` (the accessible\n * name never changes); the group is a single Tab stop. For strict mutually\n * exclusive selection with radio semantics, use\n * {@link RadioGroupController | Radio Group} instead.\n *\n * @remarks\n * Behavior only — the consumer styles off `[aria-pressed=\"true\"]`. Per the\n * Toolbar model the arrow keys move **focus only**; activation is Space/Enter\n * (handled natively on `<button>` hosts, which synthesize a click).\n *\n * Behavior provided:\n * - Click (or Space/Enter) toggles an item. In `single` mode pressing one item\n *   releases the others (0 or 1 pressed); `multiple` allows any number.\n * - `ArrowRight`/`ArrowDown` move focus to the next item, `ArrowLeft`/`ArrowUp`\n *   to the previous (wrapping); `Home`/`End` to the first/last.\n * - `stimeo--toggle-group:change` is dispatched on every toggle.\n */\nexport class ToggleGroupController extends Controller<HTMLElement> {\n  static override targets = [\"item\"];\n  static override values = {\n    mode: { type: String, default: \"multiple\" },\n  };\n  static actions = [\"onKeydown\", \"toggle\"] as const;\n  static events = [\"change\"] as const;\n\n  declare readonly itemTargets: HTMLElement[];\n  declare modeValue: string;\n\n  readonly #roving = new RovingTabindex(() => this.itemTargets);\n\n  /** Establishes the roving entry point (first pressed item, else the first). */\n  override connect(): void {\n    const firstPressed = this.itemTargets.findIndex((item) => this.#isPressed(item));\n    this.#roving.setActive(firstPressed === -1 ? 0 : firstPressed);\n  }\n\n  /** Toggles the activated item. Bound via `data-action` (click). */\n  toggle(event: Event): void {\n    this.#toggleIndex(this.itemTargets.indexOf(event.currentTarget as HTMLElement));\n  }\n\n  /** Arrow/Home/End move focus only; Space/Enter toggle non-button hosts. */\n  onKeydown(event: KeyboardEvent): void {\n    const current = this.itemTargets.indexOf(event.currentTarget as HTMLElement);\n    if (current === -1) return;\n\n    let next: number | null = null;\n    switch (event.key) {\n      case \"ArrowRight\":\n      case \"ArrowDown\":\n        next = rovingMove(current, this.itemTargets.length, 1, \"wrap\");\n        break;\n      case \"ArrowLeft\":\n      case \"ArrowUp\":\n        next = rovingMove(current, this.itemTargets.length, -1, \"wrap\");\n        break;\n      case \"Home\":\n        next = 0;\n        break;\n      case \"End\":\n        next = this.itemTargets.length - 1;\n        break;\n      case \" \":\n      case \"Enter\":\n        // Native <button> hosts synthesize a click that drives #toggle; handling\n        // the key here too would toggle twice. Only non-button hosts need it.\n        if (event.currentTarget instanceof HTMLButtonElement) return;\n        event.preventDefault();\n        this.#toggleIndex(current);\n        return;\n      default:\n        return;\n    }\n\n    event.preventDefault();\n    this.#roving.setActive(next, { focus: true });\n  }\n\n  /** Applies the toggle at `index` per the current mode and dispatches `change`. */\n  #toggleIndex(index: number): void {\n    const item = this.itemTargets[index];\n    if (!item) return;\n    const willPress = !this.#isPressed(item);\n    if (this.modeValue === \"single\") {\n      this.itemTargets.forEach((other, i) => {\n        this.#setPressed(other, i === index && willPress);\n      });\n    } else {\n      this.#setPressed(item, willPress);\n    }\n    this.#roving.setActive(index);\n    this.dispatch(\"change\", {\n      detail: { value: this.#itemValue(item), pressed: willPress, values: this.#pressedValues() },\n    });\n  }\n\n  /** Whether an item is currently pressed. */\n  #isPressed(item: HTMLElement): boolean {\n    return item.getAttribute(\"aria-pressed\") === \"true\";\n  }\n\n  /** Reflects the pressed state on `aria-pressed`. */\n  #setPressed(item: HTMLElement, pressed: boolean): void {\n    item.setAttribute(\"aria-pressed\", pressed ? \"true\" : \"false\");\n  }\n\n  /** The `data-value` of every currently pressed item. */\n  #pressedValues(): string[] {\n    return this.itemTargets\n      .filter((item) => this.#isPressed(item))\n      .map((item) => this.#itemValue(item));\n  }\n\n  /** An item's value (`data-value`, defaulting to empty). */\n  #itemValue(item: HTMLElement): string {\n    return item.getAttribute(\"data-value\") ?? \"\";\n  }\n}\n"]}
+{"version":3,"sources":["../../src/utils/logical_scroll.ts","../../src/utils/arrow_step.ts","../../src/utils/roving_tabindex.ts","../../src/controllers/toggle_group_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,EAAqB,OAAA,CAAQ,IAAA,GAAO,MAAA,IAAU,MAAA;AAEhD;;;AC7CO,IAAM,qBAAA,GAAN,cAAoC,UAAA,CAAwB;AAAA,EACjE,OAAgB,OAAA,GAAU,CAAC,MAAM,CAAA;AAAA,EACjC,OAAgB,MAAA,GAAS;AAAA,IACvB,IAAA,EAAM,EAAE,IAAA,EAAM,MAAA,EAAQ,SAAS,UAAA;AAAW,GAC5C;AAAA,EACA,OAAO,OAAA,GAAU,CAAC,WAAA,EAAa,QAAQ,CAAA;AAAA,EACvC,OAAO,MAAA,GAAS,CAAC,QAAQ,CAAA;AAAA,EAKhB,OAAA,GAAU,IAAI,cAAA,CAAe,MAAM,KAAK,WAAW,CAAA;AAAA;AAAA,EAGnD,OAAA,GAAgB;AACvB,IAAA,MAAM,YAAA,GAAe,KAAK,WAAA,CAAY,SAAA,CAAU,CAAC,IAAA,KAAS,IAAA,CAAK,UAAA,CAAW,IAAI,CAAC,CAAA;AAC/E,IAAA,IAAA,CAAK,OAAA,CAAQ,SAAA,CAAU,YAAA,KAAiB,EAAA,GAAK,IAAI,YAAY,CAAA;AAAA,EAC/D;AAAA;AAAA,EAGA,OAAO,KAAA,EAAoB;AACzB,IAAA,IAAA,CAAK,aAAa,IAAA,CAAK,WAAA,CAAY,OAAA,CAAQ,KAAA,CAAM,aAA4B,CAAC,CAAA;AAAA,EAChF;AAAA;AAAA,EAGA,UAAU,KAAA,EAA4B;AAGpC,IAAA,IAAI,MAAM,gBAAA,EAAkB;AAC5B,IAAA,IAAI,oBAAA,CAAqB,KAAK,CAAA,EAAG;AACjC,IAAA,MAAM,OAAA,GAAU,IAAA,CAAK,WAAA,CAAY,OAAA,CAAQ,MAAM,aAA4B,CAAA;AAC3E,IAAA,IAAI,YAAY,EAAA,EAAI;AAEpB,IAAA,IAAI,IAAA,GAAsB,IAAA;AAU1B,IAAA,MAAM,GAAA,GAAM,KAAA,CAAM,IAAA,CAAK,OAAO,CAAA;AAC9B,IAAA,MAAM,cAAA,GAAiB,CAAC,GAAA,KACtB,GAAA,GAAO,GAAA,KAAQ,eAAe,EAAA,GAAK,CAAA,GAAK,GAAA,KAAQ,YAAA,GAAe,CAAA,GAAI,EAAA;AACrE,IAAA,QAAQ,MAAM,GAAA;AAAK,MACjB,KAAK,YAAA;AAAA,MACL,KAAK,WAAA;AACH,QAAA,IAAA,GAAO,UAAA;AAAA,UACL,OAAA;AAAA,UACA,KAAK,WAAA,CAAY,MAAA;AAAA,UACjB,MAAM,GAAA,KAAQ,WAAA,GAAc,CAAA,GAAI,cAAA,CAAe,MAAM,GAAG,CAE1D,CAAA;AACA,QAAA;AAAA,MACF,KAAK,WAAA;AAAA,MACL,KAAK,SAAA;AACH,QAAA,IAAA,GAAO,UAAA;AAAA,UACL,OAAA;AAAA,UACA,KAAK,WAAA,CAAY,MAAA;AAAA,UACjB,MAAM,GAAA,KAAQ,SAAA,GAAY,EAAA,GAAK,cAAA,CAAe,MAAM,GAAG,CAEzD,CAAA;AACA,QAAA;AAAA,MACF,KAAK,MAAA;AACH,QAAA,IAAA,GAAO,CAAA;AACP,QAAA;AAAA,MACF,KAAK,KAAA;AACH,QAAA,IAAA,GAAO,IAAA,CAAK,YAAY,MAAA,GAAS,CAAA;AACjC,QAAA;AAAA,MACF,KAAK,GAAA;AAAA,MACL,KAAK,OAAA;AAGH,QAAA,IAAI,KAAA,CAAM,yBAAyB,iBAAA,EAAmB;AACtD,QAAA,KAAA,CAAM,cAAA,EAAe;AACrB,QAAA,IAAA,CAAK,aAAa,OAAO,CAAA;AACzB,QAAA;AAAA,MACF;AACE,QAAA;AAAA;AAGJ,IAAA,KAAA,CAAM,cAAA,EAAe;AACrB,IAAA,IAAA,CAAK,QAAQ,SAAA,CAAU,IAAA,EAAM,EAAE,KAAA,EAAO,MAAM,CAAA;AAAA,EAC9C;AAAA;AAAA,EAGA,aAAa,KAAA,EAAqB;AAChC,IAAA,MAAM,IAAA,GAAO,IAAA,CAAK,WAAA,CAAY,KAAK,CAAA;AACnC,IAAA,IAAI,CAAC,IAAA,EAAM;AACX,IAAA,MAAM,SAAA,GAAY,CAAC,IAAA,CAAK,UAAA,CAAW,IAAI,CAAA;AACvC,IAAA,IAAI,IAAA,CAAK,cAAc,QAAA,EAAU;AAC/B,MAAA,IAAA,CAAK,WAAA,CAAY,OAAA,CAAQ,CAAC,KAAA,EAAO,CAAA,KAAM;AACrC,QAAA,IAAA,CAAK,WAAA,CAAY,KAAA,EAAO,CAAA,KAAM,KAAA,IAAS,SAAS,CAAA;AAAA,MAClD,CAAC,CAAA;AAAA,IACH,CAAA,MAAO;AACL,MAAA,IAAA,CAAK,WAAA,CAAY,MAAM,SAAS,CAAA;AAAA,IAClC;AACA,IAAA,IAAA,CAAK,OAAA,CAAQ,UAAU,KAAK,CAAA;AAC5B,IAAA,IAAA,CAAK,SAAS,QAAA,EAAU;AAAA,MACtB,MAAA,EAAQ,EAAE,KAAA,EAAO,IAAA,CAAK,UAAA,CAAW,IAAI,CAAA,EAAG,OAAA,EAAS,SAAA,EAAW,MAAA,EAAQ,IAAA,CAAK,cAAA,EAAe;AAAE,KAC3F,CAAA;AAAA,EACH;AAAA;AAAA,EAGA,WAAW,IAAA,EAA4B;AACrC,IAAA,OAAO,IAAA,CAAK,YAAA,CAAa,cAAc,CAAA,KAAM,MAAA;AAAA,EAC/C;AAAA;AAAA,EAGA,WAAA,CAAY,MAAmB,OAAA,EAAwB;AACrD,IAAA,IAAA,CAAK,YAAA,CAAa,cAAA,EAAgB,OAAA,GAAU,MAAA,GAAS,OAAO,CAAA;AAAA,EAC9D;AAAA;AAAA,EAGA,cAAA,GAA2B;AACzB,IAAA,OAAO,KAAK,WAAA,CACT,MAAA,CAAO,CAAC,IAAA,KAAS,KAAK,UAAA,CAAW,IAAI,CAAC,CAAA,CACtC,IAAI,CAAC,IAAA,KAAS,IAAA,CAAK,UAAA,CAAW,IAAI,CAAC,CAAA;AAAA,EACxC;AAAA;AAAA,EAGA,WAAW,IAAA,EAA2B;AACpC,IAAA,OAAO,IAAA,CAAK,YAAA,CAAa,YAAY,CAAA,IAAK,EAAA;AAAA,EAC5C;AACF","file":"toggle_group_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, rovingMove } from \"../utils/roving_tabindex\";\n\n/**\n * Headless, accessible toggle-button group behavior.\n *\n * Markup contract (identifier: `stimeo--toggle-group`):\n *   <div data-controller=\"stimeo--toggle-group\"\n *        data-stimeo--toggle-group-mode-value=\"single\"\n *        role=\"group\" aria-label=\"Text style\">\n *     <button type=\"button\" aria-pressed=\"true\" tabindex=\"0\" data-value=\"bold\"\n *             data-stimeo--toggle-group-target=\"item\"\n *             data-action=\"click->stimeo--toggle-group#toggle\n *                          keydown->stimeo--toggle-group#onKeydown\">Bold</button>\n *     <!-- more items; exactly one tabindex=0 -->\n *   </div>\n *\n * Implements the WAI-ARIA APG **Button (toggle)** pattern with **Toolbar**-style\n * roving navigation. Each item's pressed state is `aria-pressed` (the accessible\n * name never changes); the group is a single Tab stop. For strict mutually\n * exclusive selection with radio semantics, use\n * {@link RadioGroupController | Radio Group} instead.\n *\n * @remarks\n * Behavior only — the consumer styles off `[aria-pressed=\"true\"]`. Per the\n * Toolbar model the arrow keys move **focus only**; activation is Space/Enter\n * (handled natively on `<button>` hosts, which synthesize a click).\n *\n * Behavior provided:\n * - Click (or Space/Enter) toggles an item. In `single` mode pressing one item\n *   releases the others (0 or 1 pressed); `multiple` allows any number.\n * - `ArrowRight`/`ArrowDown` move focus to the next item, `ArrowLeft`/`ArrowUp`\n *   to the previous (wrapping); `Home`/`End` to the first/last.\n * - `stimeo--toggle-group:change` is dispatched on every toggle.\n */\nexport class ToggleGroupController extends Controller<HTMLElement> {\n  static override targets = [\"item\"];\n  static override values = {\n    mode: { type: String, default: \"multiple\" },\n  };\n  static actions = [\"onKeydown\", \"toggle\"] as const;\n  static events = [\"change\"] as const;\n\n  declare readonly itemTargets: HTMLElement[];\n  declare modeValue: string;\n\n  readonly #roving = new RovingTabindex(() => this.itemTargets);\n\n  /** Establishes the roving entry point (first pressed item, else the first). */\n  override connect(): void {\n    const firstPressed = this.itemTargets.findIndex((item) => this.#isPressed(item));\n    this.#roving.setActive(firstPressed === -1 ? 0 : firstPressed);\n  }\n\n  /** Toggles the activated item. Bound via `data-action` (click). */\n  toggle(event: Event): void {\n    this.#toggleIndex(this.itemTargets.indexOf(event.currentTarget as HTMLElement));\n  }\n\n  /** Arrow/Home/End move focus only; Space/Enter toggle non-button hosts. */\n  onKeydown(event: KeyboardEvent): void {\n    // A descendant widget that already claimed the key must not ALSO move the roving focus —\n    // composition depends on this yield.\n    if (event.defaultPrevented) return;\n    if (isReservedArrowChord(event)) return;\n    const current = this.itemTargets.indexOf(event.currentTarget as HTMLElement);\n    if (current === -1) return;\n\n    let next: number | null = null;\n    // Logical, not physical. APG defines these as \"next / previous control\", and\n    // says a vertical arrangement swaps in Down/Up for the same meaning — so the\n    // pair is one axis's spelling of an order, and the order reverses with the\n    // writing direction. Read from the controller element: the container is what\n    // lays the items out, and a child may carry its own `dir` (an LTR input\n    // inside an RTL form is ordinary authoring).\n    // The horizontal pair reverses; Down/Up must not come along. They share a case\n    // body here, so the direction is decided per key rather than per branch —\n    // swapping the case labels would flip the vertical axis too.\n    const rtl = isRtl(this.element);\n    const horizontalStep = (key: string) =>\n      rtl ? (key === \"ArrowRight\" ? -1 : 1) : key === \"ArrowRight\" ? 1 : -1;\n    switch (event.key) {\n      case \"ArrowRight\":\n      case \"ArrowDown\":\n        next = rovingMove(\n          current,\n          this.itemTargets.length,\n          event.key === \"ArrowDown\" ? 1 : horizontalStep(event.key),\n          \"wrap\",\n        );\n        break;\n      case \"ArrowLeft\":\n      case \"ArrowUp\":\n        next = rovingMove(\n          current,\n          this.itemTargets.length,\n          event.key === \"ArrowUp\" ? -1 : horizontalStep(event.key),\n          \"wrap\",\n        );\n        break;\n      case \"Home\":\n        next = 0;\n        break;\n      case \"End\":\n        next = this.itemTargets.length - 1;\n        break;\n      case \" \":\n      case \"Enter\":\n        // Native <button> hosts synthesize a click that drives #toggle; handling\n        // the key here too would toggle twice. Only non-button hosts need it.\n        if (event.currentTarget instanceof HTMLButtonElement) return;\n        event.preventDefault();\n        this.#toggleIndex(current);\n        return;\n      default:\n        return;\n    }\n\n    event.preventDefault();\n    this.#roving.setActive(next, { focus: true });\n  }\n\n  /** Applies the toggle at `index` per the current mode and dispatches `change`. */\n  #toggleIndex(index: number): void {\n    const item = this.itemTargets[index];\n    if (!item) return;\n    const willPress = !this.#isPressed(item);\n    if (this.modeValue === \"single\") {\n      this.itemTargets.forEach((other, i) => {\n        this.#setPressed(other, i === index && willPress);\n      });\n    } else {\n      this.#setPressed(item, willPress);\n    }\n    this.#roving.setActive(index);\n    this.dispatch(\"change\", {\n      detail: { value: this.#itemValue(item), pressed: willPress, values: this.#pressedValues() },\n    });\n  }\n\n  /** Whether an item is currently pressed. */\n  #isPressed(item: HTMLElement): boolean {\n    return item.getAttribute(\"aria-pressed\") === \"true\";\n  }\n\n  /** Reflects the pressed state on `aria-pressed`. */\n  #setPressed(item: HTMLElement, pressed: boolean): void {\n    item.setAttribute(\"aria-pressed\", pressed ? \"true\" : \"false\");\n  }\n\n  /** The `data-value` of every currently pressed item. */\n  #pressedValues(): string[] {\n    return this.itemTargets\n      .filter((item) => this.#isPressed(item))\n      .map((item) => this.#itemValue(item));\n  }\n\n  /** An item's value (`data-value`, defaulting to empty). */\n  #itemValue(item: HTMLElement): string {\n    return item.getAttribute(\"data-value\") ?? \"\";\n  }\n}\n"]}

package/dist/controllers/toolbar_controller.d.ts

@@ -6,9 +6,8 @@ import { Controller } from '@hotwired/stimulus';
  * Markup contract (identifier: `stimeo--toolbar`):
  *   <div data-controller="stimeo--toolbar" role="toolbar" aria-label="Text formatting"
  *        data-stimeo--toolbar-orientation-value="horizontal">
- *     <button type="button" data-stimeo--toolbar-target="control"
- *             data-action="keydown->stimeo--toolbar#onKeydown">Bold</button>
- *     <!-- more controls; exactly one tabindex=0 -->
+ *     <button type="button" data-stimeo--toolbar-target="control">Bold</button>
+ *     <!-- more controls -->
  *   </div>
  *
  * Implements the WAI-ARIA APG **Toolbar** pattern: the group is a single Tab
@@ -19,14 +18,45 @@ import { Controller } from '@hotwired/stimulus';
  * @remarks
  * Behavior only. The roving mechanics are delegated to {@link RovingTabindex};
  * orientation and wrap policy stay here per the APG (they differ per widget).
+ * ARIA (`role="toolbar"`, the accessible name, and `aria-orientation="vertical"`
+ * when the axis is vertical) is the author's, exactly as with `role`.
  *
  * Behavior provided:
- * - Exactly one control is tabbable (`tabindex="0"`); the rest are `-1`.
+ * - Exactly one *navigable* control is tabbable (`tabindex="0"`); the rest are
+ *   `-1`. The invariant is re-established on connect, on control add/remove,
+ *   whenever `disabled` / `hidden` changes under the toolbar, and whenever an
+ *   enclosing `<fieldset>` is disabled or re-enabled — disabling the control that
+ *   held the Tab stop must never make the whole group unreachable by Tab, and
+ *   unlocking the surrounding form must bring it back.
  * - `ArrowRight`/`ArrowLeft` (horizontal) or `ArrowDown`/`ArrowUp` (vertical)
- *   move focus to the next/previous control; `Home`/`End` to the first/last.
+ *   move focus to the next/previous navigable control; `Home`/`End` to the
+ *   first/last. `aria-disabled="true"` controls remain in that roving order and
+ *   can be both origins and destinations; only their activation is suppressed
+ *   by the control itself or its owning behavior. Native `disabled` and `hidden`
+ *   controls are excluded.
  * - With `wrap=true` movement cycles past the ends; with `wrap=false` it stops.
- * - Returning focus from outside lands on the most recently active control,
- *   because that is the one left tabbable.
+ * - `orientation` accepts `horizontal` (default) and `vertical`; any other value
+ *   degrades to `horizontal`. There is no `both` — for two-axis navigation use
+ *   `stimeo--roving`, whose same-named Value does accept it.
+ * - Returning focus from outside lands on the most recently *active* control —
+ *   the last one moved to by key, click, or programmatic `focus()`, because that
+ *   is the one left tabbable (`focusin` keeps the Tab stop in sync).
+ *
+ * Keydown is **delegated on the container**, so controls added at runtime need
+ * no per-element `data-action` (Stimulus binds those asynchronously, which is
+ * unreliable for appended nodes). A `data-action="keydown->stimeo--toolbar#onKeydown"`
+ * on each control stays supported; it does not double-move, because the second
+ * pass sees `defaultPrevented`.
+ *
+ * Initial Tab stop: to choose it, write `tabindex` on **every** control (exactly
+ * one `0`, the rest `-1`). Natively focusable elements are `tabindex="0"`
+ * effectively when the attribute is absent, so annotating only the intended
+ * entry point makes the *first* control win instead.
+ *
+ * Known constraint: a toolbar that contains a text input competes with it for
+ * the arrow keys — the APG expects the toolbar to own them. Keep free-text
+ * fields outside the toolbar (IME composition is yielded to, but caret movement
+ * is not).
  */
 declare class ToolbarController extends Controller<HTMLElement> {
     #private;
@@ -45,14 +75,24 @@ declare class ToolbarController extends Controller<HTMLElement> {
     readonly controlTargets: HTMLElement[];
     orientationValue: string;
     wrapValue: boolean;
+    connect(): void;
+    disconnect(): void;
     /**
-     * Establishes the single tab stop: keep an existing one if it is still
-     * navigable, else the first navigable control. Disabled / hidden controls are
-     * skipped so the toolbar's lone Tab stop never lands on an unfocusable element
-     * (which would make the whole group unreachable on Tab re-entry).
+     * A control added at runtime is dropped out of the Tab sequence first — a
+     * fresh `<button>` is tabbable by default, which would make the group two Tab
+     * stops — and then the lone stop is re-established.
+     */
+    controlTargetConnected(control: HTMLElement): void;
+    /** Removing the control that held the Tab stop must not orphan the group. */
+    controlTargetDisconnected(): void;
+    /**
+     * Arrow/Home/End move focus and the single tab stop.
+     *
+     * Binding this per control with `data-action` is **optional** — the same
+     * handling runs from the container's delegated listener. It stays a declared
+     * action so per-control wiring keeps working; wiring both does not
+     * double-move, because the delegated pass then yields on `defaultPrevented`.
      */
-    connect(): void;
-    /** Arrow/Home/End move focus and the single tab stop. Bound via `data-action`. */
     onKeydown(event: KeyboardEvent): void;
 }
 

package/dist/controllers/toolbar_controller.js

@@ -2,6 +2,75 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/toolbar_controller.ts
 
+// src/utils/logical_scroll.ts
+function isRtl(element) {
+  return window.getComputedStyle(element).direction === "rtl";
+}
+
+// src/utils/arrow_step.ts
+function isReservedArrowChord(event, allow = []) {
+  if (!event.key.startsWith("Arrow")) return false;
+  return event.altKey && !allow.includes("alt") || event.ctrlKey && !allow.includes("ctrl") || event.metaKey && !allow.includes("meta") || event.shiftKey && !allow.includes("shift");
+}
+
+// src/utils/composition_tracker.ts
+var CompositionTracker = class {
+  #observedTargets = /* @__PURE__ */ new Set();
+  #activeTargets = /* @__PURE__ */ new Set();
+  #onStart;
+  #onEnd;
+  constructor(options = {}) {
+    this.#onStart = options.onStart;
+    this.#onEnd = options.onEnd;
+  }
+  /** Starts lifecycle tracking for `target`; repeated calls are idempotent. */
+  observe(target) {
+    if (this.#observedTargets.has(target)) return;
+    target.addEventListener("compositionstart", this.#handleStart);
+    target.addEventListener("compositionend", this.#handleEnd);
+    this.#observedTargets.add(target);
+  }
+  /** Stops tracking one target and clears any active composition it owned. */
+  unobserve(target) {
+    if (!this.#observedTargets.delete(target)) return;
+    target.removeEventListener("compositionstart", this.#handleStart);
+    target.removeEventListener("compositionend", this.#handleEnd);
+    this.#activeTargets.delete(target);
+  }
+  /** Releases every listener and clears state so reconnect starts cleanly. */
+  disconnect() {
+    for (const target of this.#observedTargets) {
+      target.removeEventListener("compositionstart", this.#handleStart);
+      target.removeEventListener("compositionend", this.#handleEnd);
+    }
+    this.#observedTargets.clear();
+    this.#activeTargets.clear();
+  }
+  /** True when lifecycle tracking or the current event reports composition. */
+  isComposing(event) {
+    return this.#activeTargets.size > 0 || event?.isComposing === true;
+  }
+  #handleStart = (event) => {
+    if (event.currentTarget) this.#activeTargets.add(event.currentTarget);
+    this.#onStart?.(event);
+  };
+  #handleEnd = (event) => {
+    if (event.currentTarget) this.#activeTargets.delete(event.currentTarget);
+    this.#onEnd?.(event);
+  };
+};
+
+// src/utils/focus_candidate.ts
+function inheritsFieldsetDisabled(control) {
+  let fieldset = control.closest("fieldset[disabled]");
+  while (fieldset) {
+    const legend = Array.from(fieldset.children).find((child) => child.tagName === "LEGEND");
+    if (!legend?.contains(control)) return true;
+    fieldset = fieldset.parentElement?.closest("fieldset[disabled]") ?? null;
+  }
+  return false;
+}
+
 // src/utils/roving_tabindex.ts
 var RovingTabindex = class {
   /** Returns the current ordered item elements; called on every operation. */
@@ -42,6 +111,7 @@ function rovingMove(current, length, delta, wrap) {
 }
 
 // src/controllers/toolbar_controller.ts
+var STATE_ATTRIBUTES = ["disabled", "hidden"];
 var ToolbarController = class extends Controller {
   static targets = ["control"];
   static values = {
@@ -50,61 +120,190 @@ var ToolbarController = class extends Controller {
   };
   static actions = ["onKeydown"];
   #roving = new RovingTabindex(() => this.controlTargets);
+  #composition = new CompositionTracker();
+  #observer = null;
   /**
-   * Establishes the single tab stop: keep an existing one if it is still
-   * navigable, else the first navigable control. Disabled / hidden controls are
-   * skipped so the toolbar's lone Tab stop never lands on an unfocusable element
-   * (which would make the whole group unreachable on Tab re-entry).
+   * Live between `connect()` and `disconnect()`. Stimulus reports the *initial*
+   * targets before `connect()` and re-reports them as disconnected after
+   * `disconnect()`; gating on this keeps the target callbacks from clobbering
+   * the authored Tab stop on mount and from resurrecting one after teardown.
    */
+  #connected = false;
   connect() {
-    const active = this.#roving.activeIndex;
-    const activeEl = active === -1 ? null : this.controlTargets[active];
-    if (activeEl && this.#isNavigable(activeEl)) {
-      this.#roving.setActive(active);
-      return;
+    this.#ensureTabStop();
+    this.element.addEventListener("keydown", this.#onKeydown);
+    this.element.addEventListener("focusin", this.#onFocusin);
+    this.#composition.observe(this.element);
+    if (typeof MutationObserver !== "undefined") {
+      const observer = new MutationObserver(() => this.#ensureTabStop());
+      observer.observe(this.element, {
+        subtree: true,
+        childList: true,
+        attributes: true,
+        attributeFilter: STATE_ATTRIBUTES
+      });
+      for (let fieldset = this.element.parentElement?.closest("fieldset") ?? null; fieldset; fieldset = fieldset.parentElement?.closest("fieldset") ?? null) {
+        observer.observe(fieldset, { attributes: true, attributeFilter: ["disabled"] });
+      }
+      this.#observer = observer;
     }
-    const first = this.#navigableControls[0];
-    this.#roving.setActive(first ? this.controlTargets.indexOf(first) : -1);
+    this.#connected = true;
+  }
+  disconnect() {
+    this.#connected = false;
+    this.element.removeEventListener("keydown", this.#onKeydown);
+    this.element.removeEventListener("focusin", this.#onFocusin);
+    this.#composition.disconnect();
+    this.#observer?.disconnect();
+    this.#observer = null;
   }
-  /** Arrow/Home/End move focus and the single tab stop. Bound via `data-action`. */
+  /**
+   * A control added at runtime is dropped out of the Tab sequence first — a
+   * fresh `<button>` is tabbable by default, which would make the group two Tab
+   * stops — and then the lone stop is re-established.
+   */
+  controlTargetConnected(control) {
+    if (!this.#connected) return;
+    control.tabIndex = -1;
+    this.#ensureTabStop();
+  }
+  /** Removing the control that held the Tab stop must not orphan the group. */
+  controlTargetDisconnected() {
+    if (!this.#connected) return;
+    this.#ensureTabStop();
+  }
+  /**
+   * Arrow/Home/End move focus and the single tab stop.
+   *
+   * Binding this per control with `data-action` is **optional** — the same
+   * handling runs from the container's delegated listener. It stays a declared
+   * action so per-control wiring keeps working; wiring both does not
+   * double-move, because the delegated pass then yields on `defaultPrevented`.
+   */
   onKeydown(event) {
-    const navigable = this.#navigableControls;
-    const current = navigable.indexOf(event.currentTarget);
-    if (current === -1) return;
-    const length = navigable.length;
-    const wrap = this.wrapValue ? "wrap" : "clamp";
+    this.#handleKeydown(event);
+  }
+  /** Delegated counterpart of {@link onKeydown}; bound on the container. */
+  #onKeydown = (event) => {
+    this.#handleKeydown(event);
+  };
+  /**
+   * Syncs the Tab stop to a control focused by other means (click, programmatic
+   * `focus()`) so Tab re-entry returns there. A non-navigable control is ignored:
+   * the lone Tab stop must never sit on something the user cannot operate.
+   */
+  #onFocusin = (event) => {
+    const index = this.#indexOf(event.target);
+    const control = index === -1 ? void 0 : this.controlTargets[index];
+    if (!control || !this.#isNavigable(control)) return;
+    this.#roving.setActive(index);
+  };
+  #handleKeydown(event) {
+    if (event.defaultPrevented) return;
+    if (isReservedArrowChord(event)) return;
+    if (this.#composition.isComposing(event)) return;
+    this.#ensureTabStop();
+    const from = this.#indexOf(event.target);
+    if (from === -1) return;
     const vertical = this.orientationValue === "vertical";
-    const forwardKey = vertical ? "ArrowDown" : "ArrowRight";
-    const backwardKey = vertical ? "ArrowUp" : "ArrowLeft";
-    let next;
+    const rtl = !vertical && isRtl(this.element);
+    const forwardKey = vertical ? "ArrowDown" : rtl ? "ArrowLeft" : "ArrowRight";
+    const backwardKey = vertical ? "ArrowUp" : rtl ? "ArrowRight" : "ArrowLeft";
+    let target;
     if (event.key === forwardKey) {
-      next = rovingMove(current, length, 1, wrap);
+      target = this.#nextNavigable(from, 1);
     } else if (event.key === backwardKey) {
-      next = rovingMove(current, length, -1, wrap);
+      target = this.#nextNavigable(from, -1);
     } else if (event.key === "Home") {
-      next = 0;
+      target = this.#navigableControls[0];
     } else if (event.key === "End") {
-      next = length - 1;
+      const navigable = this.#navigableControls;
+      target = navigable[navigable.length - 1];
     } else {
       return;
     }
     event.preventDefault();
-    const target = navigable[next];
     if (target) this.#roving.setActive(this.controlTargets.indexOf(target), { focus: true });
   }
-  /** Controls eligible for the roving tab stop (excludes disabled / hidden). */
+  /**
+   * Re-establishes the single Tab stop: keep the current one while it is still
+   * navigable, else hand it to the first navigable control. `-1` (no Tab stop at
+   * all) is reached only when every control is unavailable, and is recovered
+   * from as soon as one becomes navigable again. Idempotent by construction, so
+   * connect, the target callbacks, the observer, and keydown can all call it.
+   */
+  #ensureTabStop() {
+    const active = this.#roving.activeIndex;
+    const activeEl = active === -1 ? null : this.controlTargets[active];
+    if (activeEl && this.#isNavigable(activeEl)) {
+      this.#roving.setActive(active);
+      return;
+    }
+    const first = this.#navigableControls[0];
+    this.#roving.setActive(first ? this.controlTargets.indexOf(first) : -1);
+  }
+  /**
+   * First navigable control strictly in the `delta` direction from `fromIndex`,
+   * scanning the **full** control list rather than the navigable subset so a
+   * non-navigable origin is never a dead end. When the direction yields nothing
+   * the origin keeps focus; when the origin itself is not navigable the first
+   * navigable control is used instead, so an arrow key always escapes.
+   */
+  #nextNavigable(fromIndex, delta) {
+    const controls = this.controlTargets;
+    const length = controls.length;
+    const wrap = this.wrapValue ? "wrap" : "clamp";
+    let index = fromIndex;
+    for (let step = 0; step < length; step++) {
+      const next = rovingMove(index, length, delta, wrap);
+      if (next === index) break;
+      index = next;
+      const candidate = controls[index];
+      if (candidate && this.#isNavigable(candidate)) return candidate;
+    }
+    const origin = controls[fromIndex];
+    return origin && this.#isNavigable(origin) ? origin : this.#navigableControls[0];
+  }
+  /** Index in `controlTargets` of the control owning `target` (it or a descendant). */
+  #indexOf(target) {
+    const node = target;
+    if (!node) return -1;
+    return this.controlTargets.findIndex((control) => control === node || control.contains(node));
+  }
+  /** Controls eligible for the roving tab stop (excludes native disabled / hidden). */
   get #navigableControls() {
     return this.controlTargets.filter((control) => this.#isNavigable(control));
   }
   /**
-   * A control can hold the tab stop unless it is `hidden`, `aria-disabled`, or a
-   * natively `disabled` form control. CSS-only visibility cannot be detected
+   * A control can hold the tab stop unless it is `hidden` or a disabled form
+   * control. `aria-disabled` remains navigable per the APG; activation suppression
+   * belongs to the control itself or its owning behavior. Native disabledness is
+   * read from the `disabled` property, narrowed by an `in` check rather than
+   * asserted since `<a>` and `<div role="button">` are legitimate controls that
+   * are unaffected by a disabled fieldset. CSS-only visibility cannot be detected
    * headlessly and stays the consumer's responsibility.
    */
   #isNavigable(control) {
-    if (control.hasAttribute("hidden")) return false;
-    if (control.getAttribute("aria-disabled") === "true") return false;
-    return !control.disabled;
+    if (this.#isHidden(control)) return false;
+    if (!("disabled" in control)) return true;
+    if (control.disabled === true) return false;
+    return !inheritsFieldsetDisabled(control);
+  }
+  /**
+   * Whether `control`, or anything between it and the toolbar root, is `hidden`.
+   *
+   * Reading only the control's own attribute lets an invisible control hold the
+   * single Tab stop, which takes the *whole* toolbar out of the Tab sequence — an
+   * ordinary `hidden` wrapper is enough. The walk stops at the root: a toolbar
+   * inside a `hidden` region is already out of the page's Tab order.
+   */
+  #isHidden(control) {
+    let node = control;
+    while (node && node !== this.element) {
+      if (node.hasAttribute("hidden")) return true;
+      node = node.parentElement;
+    }
+    return false;
   }
 };