stimeo-ui 0.1.0-alpha.1

package/dist/controllers/toast_controller.js

@@ -0,0 +1,310 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/toast_controller.ts
+
+// src/utils/safe_timeout.ts
+var TimerRegistry = class {
+  /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
+  ids = /* @__PURE__ */ new Set();
+  /**
+   * Cancels a single tracked timer.
+   *
+   * No-ops if the id is unknown (already cleared, fired, or never owned by this
+   * registry), so callers can clear defensively without guarding.
+   */
+  clear(id) {
+    if (this.ids.delete(id)) {
+      this.cancel(id);
+    }
+  }
+  /**
+   * Cancels every tracked timer. Call this from a controller's `disconnect()`
+   * to guarantee no timer outlives the element.
+   */
+  clearAll() {
+    for (const id of this.ids) {
+      this.cancel(id);
+    }
+    this.ids.clear();
+  }
+  /** Number of timers currently tracked (pending). */
+  get size() {
+    return this.ids.size;
+  }
+};
+var SafeTimeout = class extends TimerRegistry {
+  /**
+   * Schedules `callback` after `delay` ms and returns the timer id.
+   *
+   * The id is removed from the registry automatically when the timeout fires,
+   * so {@link TimerRegistry.size | size} reflects only still-pending timers.
+   */
+  set(callback, delay) {
+    const id = this.schedule(() => {
+      this.ids.delete(id);
+      callback();
+    }, delay);
+    this.ids.add(id);
+    return id;
+  }
+  schedule(callback, delay) {
+    return window.setTimeout(callback, delay);
+  }
+  cancel(id) {
+    window.clearTimeout(id);
+  }
+};
+
+// src/controllers/toast_controller.ts
+var ToastController = class extends Controller {
+  static targets = ["list", "template", "item"];
+  static values = {
+    duration: { type: Number, default: 0 },
+    max: { type: Number, default: 3 }
+  };
+  static actions = ["dismiss", "onKeydown", "pause", "resume", "show"];
+  static events = ["dismiss", "show"];
+  /**
+   * Registry for every auto-dismiss and transition-finalize timer the controller
+   * schedules. {@link SafeTimeout} owns *registration and teardown only*; the
+   * pause/resume remaining-time accounting stays in `#activeTimeouts` so the
+   * per-widget WCAG 2.2.1 semantics are not flattened into the helper.
+   */
+  #timers = new SafeTimeout();
+  /**
+   * Pending one-shot `requestAnimationFrame` handles (the entering→visible flip).
+   * Tracked so {@link disconnect} can cancel any that have not fired, preventing a
+   * detached element from being mutated after it leaves the DOM (Turbo).
+   */
+  #rafHandles = /* @__PURE__ */ new Set();
+  /** Track active timeouts mapped by each toast element for safe cancellation. */
+  #activeTimeouts = /* @__PURE__ */ new Map();
+  /** Track active pause reasons (hover/focus) per toast for WCAG 2.2.1 pause/resume. */
+  #pauseReasons = /* @__PURE__ */ new Map();
+  connect() {
+    this.enforceMaxLimit();
+    for (const item of this.itemTargets) {
+      if (!this.#activeTimeouts.has(item)) {
+        this.#startTimer(item);
+      }
+    }
+  }
+  disconnect() {
+    this.#timers.clearAll();
+    for (const handle of this.#rafHandles) {
+      window.cancelAnimationFrame(handle);
+    }
+    this.#rafHandles.clear();
+    this.#activeTimeouts.clear();
+    this.#pauseReasons.clear();
+  }
+  durationValueChanged() {
+    if (this.durationValue > 0) {
+      for (const item of this.itemTargets) {
+        if (!this.#activeTimeouts.has(item)) {
+          this.#startTimer(item);
+        }
+      }
+    }
+  }
+  maxValueChanged() {
+    this.enforceMaxLimit();
+  }
+  /**
+   * Stimulus lifecycle callback triggered automatically when a new item target
+   * enters the DOM. Perfectly handles dynamic client-side injections and server-side
+   * Turbo Stream appends alike.
+   */
+  itemTargetConnected(element) {
+    this.enforceMaxLimit();
+    this.#startTimer(element);
+    element.setAttribute("data-state", "entering");
+    const handle = window.requestAnimationFrame(() => {
+      this.#rafHandles.delete(handle);
+      element.setAttribute("data-state", "visible");
+    });
+    this.#rafHandles.add(handle);
+  }
+  /** Clears any active timer when a toast is removed from the DOM. */
+  itemTargetDisconnected(element) {
+    this.#clearTimer(element);
+  }
+  /**
+   * Shows a new toast. Accepts its content from either a Stimulus action param
+   * (attribute-only trigger) or a programmatic `show` CustomEvent `detail`
+   * (remote / Turbo trigger); the action param wins when both are present.
+   *
+   *   <button data-action="click->stimeo--toast#show"
+   *           data-stimeo--toast-body-param="Saved"
+   *           data-stimeo--toast-type-param="status">Show</button>
+   *
+   *   element.dispatchEvent(new CustomEvent("show", { detail: { body, type } }))
+   *
+   * Clones the template slot, interpolates the body text, and appends to the list.
+   */
+  show(event) {
+    if (!this.hasTemplateTarget || !this.hasListTarget) return;
+    const body = this.#readField(event, "body");
+    if (!body) return;
+    const clone = this.templateTarget.content.cloneNode(true);
+    const item = clone.querySelector("[data-stimeo--toast-target='item']");
+    if (!item) return;
+    const bodySlot = item.querySelector("[data-toast-slot='body']");
+    if (bodySlot) {
+      bodySlot.textContent = body;
+    }
+    item.setAttribute("role", this.#readField(event, "type") === "alert" ? "alert" : "status");
+    this.listTarget.appendChild(item);
+    this.dispatch("show", { detail: { item } });
+  }
+  /**
+   * Reads a string field from a Stimulus action param or a CustomEvent `detail`,
+   * preferring the action param. Returns null unless a non-empty string is found,
+   * so untrusted runtime payloads cannot inject non-string values.
+   */
+  #readField(event, key) {
+    const params = event.params;
+    const fromParams = params?.[key];
+    if (typeof fromParams === "string" && fromParams.length > 0) return fromParams;
+    const detail = event.detail;
+    if (detail && typeof detail === "object" && key in detail) {
+      const value = detail[key];
+      if (typeof value === "string" && value.length > 0) return value;
+    }
+    return null;
+  }
+  /** Dismisses the toast that contained the trigger. */
+  dismiss(event) {
+    const target = event.currentTarget || event.target;
+    if (!target) return;
+    const item = target.closest("[data-stimeo--toast-target='item']");
+    if (!item) return;
+    this.#removeWithTransition(item, "user");
+  }
+  /** Dismisses the focused toast when Escape is pressed. */
+  onKeydown(event) {
+    if (event.key === "Escape") {
+      const target = event.currentTarget || event.target;
+      if (!target) return;
+      const item = target.closest("[data-stimeo--toast-target='item']");
+      if (!item) return;
+      event.preventDefault();
+      this.#removeWithTransition(item, "user");
+    }
+  }
+  /**
+   * Pauses the auto-dismiss timer on mouse entry or keyboard focus.
+   *
+   * Hover and focus are tracked as independent reasons: the timer is only
+   * snapshotted on the first active reason, and only resumed once *every*
+   * reason has been released (see {@link resume}). This keeps a toast paused
+   * while it is still hovered *or* focused, per WCAG 2.2.1.
+   */
+  pause(event) {
+    const item = this.#itemFromEvent(event);
+    if (!item || this.durationValue <= 0) return;
+    const timeout = this.#activeTimeouts.get(item);
+    if (!timeout) return;
+    const reasons = this.#pauseReasonsFor(item);
+    const wasActive = reasons.size > 0;
+    reasons.add(this.#pauseReason(event));
+    if (wasActive || timeout.id === 0) return;
+    this.#timers.clear(timeout.id);
+    const elapsed = Date.now() - timeout.startedAt;
+    const remaining = Math.max(0, timeout.remaining - elapsed);
+    this.#activeTimeouts.set(item, { id: 0, startedAt: 0, remaining });
+    item.setAttribute("data-paused", "true");
+  }
+  /** Resumes the auto-dismiss timer once both hover and focus have been released. */
+  resume(event) {
+    const item = this.#itemFromEvent(event);
+    if (!item || this.durationValue <= 0) return;
+    const reasons = this.#pauseReasonsFor(item);
+    reasons.delete(this.#pauseReason(event));
+    if (reasons.size > 0) return;
+    const timeout = this.#activeTimeouts.get(item);
+    if (!timeout || timeout.remaining <= 0) return;
+    item.removeAttribute("data-paused");
+    this.#startTimer(item, timeout.remaining);
+  }
+  /** Resolves the toast item element a pause/resume event targets. */
+  #itemFromEvent(event) {
+    const target = event.currentTarget || event.target;
+    return target?.closest("[data-stimeo--toast-target='item']") ?? null;
+  }
+  /** Classifies a pause/resume event as a hover or focus reason. */
+  #pauseReason(event) {
+    return event.type === "focusin" || event.type === "focusout" ? "focus" : "hover";
+  }
+  /** Lazily creates and returns the active pause-reason set for an item. */
+  #pauseReasonsFor(item) {
+    let reasons = this.#pauseReasons.get(item);
+    if (!reasons) {
+      reasons = /* @__PURE__ */ new Set();
+      this.#pauseReasons.set(item, reasons);
+    }
+    return reasons;
+  }
+  #startTimer(element, duration = this.durationValue) {
+    if (duration <= 0) return;
+    this.#clearTimer(element);
+    const id = this.#timers.set(() => {
+      this.#removeWithTransition(element, "timeout");
+    }, duration);
+    this.#activeTimeouts.set(element, { id, startedAt: Date.now(), remaining: duration });
+  }
+  #clearTimer(element) {
+    const timeout = this.#activeTimeouts.get(element);
+    if (timeout) {
+      if (timeout.id) this.#timers.clear(timeout.id);
+      this.#activeTimeouts.delete(element);
+    }
+    this.#pauseReasons.delete(element);
+  }
+  #removeWithTransition(element, reason) {
+    this.#clearTimer(element);
+    element.setAttribute("data-state", "leaving");
+    const finalize = () => {
+      if (element.parentNode === this.listTarget) {
+        this.listTarget.removeChild(element);
+      }
+      this.dispatch("dismiss", { detail: { item: element, reason } });
+    };
+    const transitions = window.getComputedStyle(element).transitionDuration;
+    const duration = cssTimeToMs(transitions);
+    if (duration > 0) {
+      this.#timers.set(finalize, duration);
+    } else {
+      finalize();
+    }
+  }
+  /**
+   * Removes the oldest toasts when the list exceeds `maxValue`.
+   *
+   * Public (not `#private`) as a deterministic test seam: enforcement normally
+   * runs from `itemTargetConnected`, a Stimulus callback that fires via a
+   * MutationObserver — which happy-dom does not reliably deliver — so the unit
+   * tests invoke it directly. It is therefore listed in the contract guard's
+   * NON_ACTION_ALLOWLIST (it is not a user-wired action).
+   */
+  enforceMaxLimit() {
+    const currentItems = this.itemTargets;
+    if (currentItems.length > this.maxValue) {
+      const excessCount = currentItems.length - this.maxValue;
+      for (let i = 0; i < excessCount; i++) {
+        const oldest = currentItems[i];
+        if (oldest) this.#removeWithTransition(oldest, "timeout");
+      }
+    }
+  }
+};
+function cssTimeToMs(value) {
+  const first = value.split(",")[0]?.trim() ?? "";
+  const amount = Number.parseFloat(first);
+  if (Number.isNaN(amount)) return 0;
+  return first.endsWith("ms") ? amount : amount * 1e3;
+}
+
+export { ToastController, cssTimeToMs };
+//# sourceMappingURL=toast_controller.js.map
+//# sourceMappingURL=toast_controller.js.map

package/dist/controllers/toast_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/safe_timeout.ts","../../src/controllers/toast_controller.ts"],"names":[],"mappings":"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","file":"toast_controller.js","sourcesContent":["/**\n * Self-cleaning timer registries shared by Stimeo controllers.\n *\n * Stimulus controllers frequently schedule `setTimeout` / `setInterval` work\n * (auto-dismiss, debouncing, polling). When the element leaves the DOM — a\n * Turbo Drive navigation, a Turbo Stream replacement, or any `disconnect()` —\n * orphaned timers keep firing against a detached controller, leaking memory and\n * mutating stale state. {@link SafeTimeout} and {@link SafeInterval} track every\n * timer they create so a single {@link TimerRegistry.clearAll | clearAll()} call\n * in `disconnect()` tears them all down.\n *\n * These are intentionally low-level primitives: they own *registration and\n * cleanup only*. Higher-level policy (pause/resume, remaining-time accounting)\n * stays in the individual controllers so per-widget semantics are not flattened\n * into a lowest-common-denominator helper.\n */\n\n/**\n * Shared registry bookkeeping for the timeout/interval variants.\n *\n * Subclasses provide the scheduling primitive ({@link schedule}) and its matching\n * canceller ({@link cancel}); this base owns the set of live ids plus the\n * per-id and bulk teardown shared by both.\n */\nabstract class TimerRegistry {\n  /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */\n  protected readonly ids = new Set<number>();\n\n  /** Schedules the underlying platform timer and returns its id. */\n  protected abstract schedule(callback: () => void, delay: number): number;\n\n  /** Cancels the underlying platform timer for `id`. */\n  protected abstract cancel(id: number): void;\n\n  /**\n   * Cancels a single tracked timer.\n   *\n   * No-ops if the id is unknown (already cleared, fired, or never owned by this\n   * registry), so callers can clear defensively without guarding.\n   */\n  clear(id: number): void {\n    if (this.ids.delete(id)) {\n      this.cancel(id);\n    }\n  }\n\n  /**\n   * Cancels every tracked timer. Call this from a controller's `disconnect()`\n   * to guarantee no timer outlives the element.\n   */\n  clearAll(): void {\n    for (const id of this.ids) {\n      this.cancel(id);\n    }\n    this.ids.clear();\n  }\n\n  /** Number of timers currently tracked (pending). */\n  get size(): number {\n    return this.ids.size;\n  }\n}\n\n/**\n * `setTimeout` wrapper that auto-forgets each timer once it fires and supports\n * bulk teardown on disconnect.\n *\n * @example\n * ```ts\n * #timers = new SafeTimeout();\n *\n * connect() {\n *   this.#timers.set(() => this.dismiss(), 5000);\n * }\n *\n * disconnect() {\n *   this.#timers.clearAll();\n * }\n * ```\n */\nexport class SafeTimeout extends TimerRegistry {\n  /**\n   * Schedules `callback` after `delay` ms and returns the timer id.\n   *\n   * The id is removed from the registry automatically when the timeout fires,\n   * so {@link TimerRegistry.size | size} reflects only still-pending timers.\n   */\n  set(callback: () => void, delay: number): number {\n    const id = this.schedule(() => {\n      this.ids.delete(id);\n      callback();\n    }, delay);\n    this.ids.add(id);\n    return id;\n  }\n\n  protected schedule(callback: () => void, delay: number): number {\n    return window.setTimeout(callback, delay);\n  }\n\n  protected cancel(id: number): void {\n    window.clearTimeout(id);\n  }\n}\n\n/**\n * `setInterval` wrapper that tracks every interval for bulk teardown on\n * disconnect. Unlike {@link SafeTimeout}, intervals are retained until they are\n * explicitly cleared because they fire repeatedly.\n *\n * @example\n * ```ts\n * #intervals = new SafeInterval();\n *\n * connect() {\n *   this.#intervals.set(() => this.tick(), 1000);\n * }\n *\n * disconnect() {\n *   this.#intervals.clearAll();\n * }\n * ```\n */\nexport class SafeInterval extends TimerRegistry {\n  /** Schedules a repeating `callback` every `delay` ms and returns the timer id. */\n  set(callback: () => void, delay: number): number {\n    const id = this.schedule(callback, delay);\n    this.ids.add(id);\n    return id;\n  }\n\n  protected schedule(callback: () => void, delay: number): number {\n    return window.setInterval(callback, delay);\n  }\n\n  protected cancel(id: number): void {\n    window.clearInterval(id);\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { SafeTimeout } from \"../utils/safe_timeout\";\n\n/**\n * Headless, highly accessible toast notification behavior.\n *\n * Markup contract (identifier: `stimeo--toast`):\n *   <div data-controller=\"stimeo--toast\"\n *        data-stimeo--toast-duration-value=\"5000\"\n *        data-stimeo--toast-max-value=\"3\">\n *     <!-- Attribute-only trigger: no hand-written JS required. -->\n *     <button data-action=\"click->stimeo--toast#show\"\n *             data-stimeo--toast-body-param=\"Saved\"\n *             data-stimeo--toast-type-param=\"status\">Show</button>\n *     <!-- The live region is a descendant; the controller element only needs\n *          to enclose both the trigger(s) and the list/template targets. -->\n *     <div role=\"region\" aria-label=\"Notifications\">\n *       <ol data-stimeo--toast-target=\"list\"></ol>\n *       <template data-stimeo--toast-target=\"template\">\n *         <li role=\"status\" data-stimeo--toast-target=\"item\"\n *             data-action=\"mouseenter->stimeo--toast#pause\n *                          mouseleave->stimeo--toast#resume\n *                          focusin->stimeo--toast#pause\n *                          focusout->stimeo--toast#resume\n *                          keydown->stimeo--toast#onKeydown\"\n *             tabindex=\"0\">\n *           <span data-toast-slot=\"body\"></span>\n *           <button type=\"button\" data-action=\"stimeo--toast#dismiss\">Dismiss</button>\n *         </li>\n *       </template>\n *     </div>\n *   </div>\n *\n * Implements WAI-ARIA live region status/alert announcements, limits simultaneous\n * elements, and pauses dismiss timeouts on hover or focus to comply with WCAG 2.2.1.\n *\n * @remarks\n * Behavior only. The controller handles state updates via `data-state` and lifecycle events\n * while leaving visual styling completely to the client's CSS transitions.\n */\nexport class ToastController extends Controller<HTMLElement> {\n  static override targets = [\"list\", \"template\", \"item\"];\n  static override values = {\n    duration: { type: Number, default: 0 },\n    max: { type: Number, default: 3 },\n  };\n  static actions = [\"dismiss\", \"onKeydown\", \"pause\", \"resume\", \"show\"] as const;\n  static events = [\"dismiss\", \"show\"] as const;\n\n  declare readonly listTarget: HTMLElement;\n  declare readonly templateTarget: HTMLTemplateElement;\n  declare readonly itemTargets: HTMLElement[];\n  declare readonly hasListTarget: boolean;\n  declare readonly hasTemplateTarget: boolean;\n\n  declare durationValue: number;\n  declare maxValue: number;\n\n  /**\n   * Registry for every auto-dismiss and transition-finalize timer the controller\n   * schedules. {@link SafeTimeout} owns *registration and teardown only*; the\n   * pause/resume remaining-time accounting stays in `#activeTimeouts` so the\n   * per-widget WCAG 2.2.1 semantics are not flattened into the helper.\n   */\n  #timers = new SafeTimeout();\n\n  /**\n   * Pending one-shot `requestAnimationFrame` handles (the entering→visible flip).\n   * Tracked so {@link disconnect} can cancel any that have not fired, preventing a\n   * detached element from being mutated after it leaves the DOM (Turbo).\n   */\n  #rafHandles = new Set<number>();\n\n  /** Track active timeouts mapped by each toast element for safe cancellation. */\n  #activeTimeouts = new Map<HTMLElement, { id: number; startedAt: number; remaining: number }>();\n\n  /** Track active pause reasons (hover/focus) per toast for WCAG 2.2.1 pause/resume. */\n  #pauseReasons = new Map<HTMLElement, Set<string>>();\n\n  override connect(): void {\n    this.enforceMaxLimit();\n    for (const item of this.itemTargets) {\n      if (!this.#activeTimeouts.has(item)) {\n        this.#startTimer(item);\n      }\n    }\n  }\n\n  override disconnect(): void {\n    // SafeTimeout owns every auto-dismiss + finalize timer; one call tears them\n    // all down so none fires against the detached controller.\n    this.#timers.clearAll();\n    for (const handle of this.#rafHandles) {\n      window.cancelAnimationFrame(handle);\n    }\n    this.#rafHandles.clear();\n    this.#activeTimeouts.clear();\n    this.#pauseReasons.clear();\n  }\n\n  durationValueChanged(): void {\n    if (this.durationValue > 0) {\n      for (const item of this.itemTargets) {\n        if (!this.#activeTimeouts.has(item)) {\n          this.#startTimer(item);\n        }\n      }\n    }\n  }\n\n  maxValueChanged(): void {\n    this.enforceMaxLimit();\n  }\n\n  /**\n   * Stimulus lifecycle callback triggered automatically when a new item target\n   * enters the DOM. Perfectly handles dynamic client-side injections and server-side\n   * Turbo Stream appends alike.\n   */\n  itemTargetConnected(element: HTMLElement): void {\n    this.enforceMaxLimit();\n    this.#startTimer(element);\n    element.setAttribute(\"data-state\", \"entering\");\n    const handle = window.requestAnimationFrame(() => {\n      this.#rafHandles.delete(handle);\n      element.setAttribute(\"data-state\", \"visible\");\n    });\n    this.#rafHandles.add(handle);\n  }\n\n  /** Clears any active timer when a toast is removed from the DOM. */\n  itemTargetDisconnected(element: HTMLElement): void {\n    this.#clearTimer(element);\n  }\n\n  /**\n   * Shows a new toast. Accepts its content from either a Stimulus action param\n   * (attribute-only trigger) or a programmatic `show` CustomEvent `detail`\n   * (remote / Turbo trigger); the action param wins when both are present.\n   *\n   *   <button data-action=\"click->stimeo--toast#show\"\n   *           data-stimeo--toast-body-param=\"Saved\"\n   *           data-stimeo--toast-type-param=\"status\">Show</button>\n   *\n   *   element.dispatchEvent(new CustomEvent(\"show\", { detail: { body, type } }))\n   *\n   * Clones the template slot, interpolates the body text, and appends to the list.\n   */\n  show(event: Event): void {\n    if (!this.hasTemplateTarget || !this.hasListTarget) return;\n\n    const body = this.#readField(event, \"body\");\n    if (!body) return;\n\n    const clone = this.templateTarget.content.cloneNode(true) as DocumentFragment;\n    const item = clone.querySelector(\"[data-stimeo--toast-target='item']\") as HTMLElement | null;\n    if (!item) return;\n\n    const bodySlot = item.querySelector(\"[data-toast-slot='body']\");\n    if (bodySlot) {\n      bodySlot.textContent = body;\n    }\n\n    // Validate the live-region role at runtime; untrusted params/detail could\n    // otherwise write an invalid ARIA role. Anything but \"alert\" stays polite.\n    item.setAttribute(\"role\", this.#readField(event, \"type\") === \"alert\" ? \"alert\" : \"status\");\n\n    this.listTarget.appendChild(item);\n    this.dispatch(\"show\", { detail: { item } });\n  }\n\n  /**\n   * Reads a string field from a Stimulus action param or a CustomEvent `detail`,\n   * preferring the action param. Returns null unless a non-empty string is found,\n   * so untrusted runtime payloads cannot inject non-string values.\n   */\n  #readField(event: Event, key: \"body\" | \"type\"): string | null {\n    const params = (event as { params?: Record<string, unknown> }).params;\n    const fromParams = params?.[key];\n    if (typeof fromParams === \"string\" && fromParams.length > 0) return fromParams;\n\n    const detail = (event as CustomEvent<unknown>).detail;\n    if (detail && typeof detail === \"object\" && key in detail) {\n      const value = (detail as Record<string, unknown>)[key];\n      if (typeof value === \"string\" && value.length > 0) return value;\n    }\n    return null;\n  }\n\n  /** Dismisses the toast that contained the trigger. */\n  dismiss(event: Event): void {\n    const target = (event.currentTarget || event.target) as HTMLElement | null;\n    if (!target) return;\n    const item = target.closest(\"[data-stimeo--toast-target='item']\") as HTMLElement | null;\n    if (!item) return;\n\n    this.#removeWithTransition(item, \"user\");\n  }\n\n  /** Dismisses the focused toast when Escape is pressed. */\n  onKeydown(event: KeyboardEvent): void {\n    if (event.key === \"Escape\") {\n      const target = (event.currentTarget || event.target) as HTMLElement | null;\n      if (!target) return;\n      const item = target.closest(\"[data-stimeo--toast-target='item']\") as HTMLElement | null;\n      if (!item) return;\n\n      event.preventDefault();\n      this.#removeWithTransition(item, \"user\");\n    }\n  }\n\n  /**\n   * Pauses the auto-dismiss timer on mouse entry or keyboard focus.\n   *\n   * Hover and focus are tracked as independent reasons: the timer is only\n   * snapshotted on the first active reason, and only resumed once *every*\n   * reason has been released (see {@link resume}). This keeps a toast paused\n   * while it is still hovered *or* focused, per WCAG 2.2.1.\n   */\n  pause(event: Event): void {\n    const item = this.#itemFromEvent(event);\n    if (!item || this.durationValue <= 0) return;\n\n    const timeout = this.#activeTimeouts.get(item);\n    if (!timeout) return;\n\n    const reasons = this.#pauseReasonsFor(item);\n    const wasActive = reasons.size > 0;\n    reasons.add(this.#pauseReason(event));\n\n    // Only snapshot the remaining time on the first reason; subsequent reasons\n    // must not recompute elapsed against the already-cleared timer.\n    if (wasActive || timeout.id === 0) return;\n\n    this.#timers.clear(timeout.id);\n    const elapsed = Date.now() - timeout.startedAt;\n    const remaining = Math.max(0, timeout.remaining - elapsed);\n\n    this.#activeTimeouts.set(item, { id: 0, startedAt: 0, remaining });\n    item.setAttribute(\"data-paused\", \"true\");\n  }\n\n  /** Resumes the auto-dismiss timer once both hover and focus have been released. */\n  resume(event: Event): void {\n    const item = this.#itemFromEvent(event);\n    if (!item || this.durationValue <= 0) return;\n\n    const reasons = this.#pauseReasonsFor(item);\n    reasons.delete(this.#pauseReason(event));\n    // Still paused by the other reason (e.g. mouse left but focus remains).\n    if (reasons.size > 0) return;\n\n    const timeout = this.#activeTimeouts.get(item);\n    if (!timeout || timeout.remaining <= 0) return;\n\n    item.removeAttribute(\"data-paused\");\n    this.#startTimer(item, timeout.remaining);\n  }\n\n  /** Resolves the toast item element a pause/resume event targets. */\n  #itemFromEvent(event: Event): HTMLElement | null {\n    const target = (event.currentTarget || event.target) as HTMLElement | null;\n    return target?.closest(\"[data-stimeo--toast-target='item']\") ?? null;\n  }\n\n  /** Classifies a pause/resume event as a hover or focus reason. */\n  #pauseReason(event: Event): \"focus\" | \"hover\" {\n    return event.type === \"focusin\" || event.type === \"focusout\" ? \"focus\" : \"hover\";\n  }\n\n  /** Lazily creates and returns the active pause-reason set for an item. */\n  #pauseReasonsFor(item: HTMLElement): Set<string> {\n    let reasons = this.#pauseReasons.get(item);\n    if (!reasons) {\n      reasons = new Set<string>();\n      this.#pauseReasons.set(item, reasons);\n    }\n    return reasons;\n  }\n\n  #startTimer(element: HTMLElement, duration = this.durationValue): void {\n    if (duration <= 0) return;\n\n    this.#clearTimer(element);\n    const id = this.#timers.set(() => {\n      this.#removeWithTransition(element, \"timeout\");\n    }, duration);\n\n    this.#activeTimeouts.set(element, { id, startedAt: Date.now(), remaining: duration });\n  }\n\n  #clearTimer(element: HTMLElement): void {\n    const timeout = this.#activeTimeouts.get(element);\n    if (timeout) {\n      if (timeout.id) this.#timers.clear(timeout.id);\n      this.#activeTimeouts.delete(element);\n    }\n    this.#pauseReasons.delete(element);\n  }\n\n  #removeWithTransition(element: HTMLElement, reason: \"timeout\" | \"user\"): void {\n    this.#clearTimer(element);\n    element.setAttribute(\"data-state\", \"leaving\");\n\n    const finalize = () => {\n      if (element.parentNode === this.listTarget) {\n        this.listTarget.removeChild(element);\n      }\n      this.dispatch(\"dismiss\", { detail: { item: element, reason } });\n    };\n\n    const transitions = window.getComputedStyle(element).transitionDuration;\n    const duration = cssTimeToMs(transitions);\n    if (duration > 0) {\n      this.#timers.set(finalize, duration);\n    } else {\n      finalize();\n    }\n  }\n\n  /**\n   * Removes the oldest toasts when the list exceeds `maxValue`.\n   *\n   * Public (not `#private`) as a deterministic test seam: enforcement normally\n   * runs from `itemTargetConnected`, a Stimulus callback that fires via a\n   * MutationObserver — which happy-dom does not reliably deliver — so the unit\n   * tests invoke it directly. It is therefore listed in the contract guard's\n   * NON_ACTION_ALLOWLIST (it is not a user-wired action).\n   */\n  enforceMaxLimit(): void {\n    const currentItems = this.itemTargets;\n    if (currentItems.length > this.maxValue) {\n      const excessCount = currentItems.length - this.maxValue;\n      for (let i = 0; i < excessCount; i++) {\n        const oldest = currentItems[i];\n        if (oldest) this.#removeWithTransition(oldest, \"timeout\");\n      }\n    }\n  }\n}\n\n/**\n * Converts the first value of a CSS `transition-duration` string to milliseconds.\n * Browsers normalize computed `<time>` values to seconds (e.g. `0.2s`), but parse\n * `ms` defensively so a consumer's `ms` transition is not delayed 1000x.\n *\n * Pure (no `this`); exported so it can be unit-tested directly.\n */\nexport function cssTimeToMs(value: string): number {\n  const first = value.split(\",\")[0]?.trim() ?? \"\";\n  const amount = Number.parseFloat(first);\n  if (Number.isNaN(amount)) return 0;\n  return first.endsWith(\"ms\") ? amount : amount * 1000;\n}\n"]}

package/dist/controllers/toggle_group_controller.d.ts

@@ -0,0 +1,56 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless, accessible toggle-button group behavior.
+ *
+ * Markup contract (identifier: `stimeo--toggle-group`):
+ *   <div data-controller="stimeo--toggle-group"
+ *        data-stimeo--toggle-group-mode-value="single"
+ *        role="group" aria-label="Text style">
+ *     <button type="button" aria-pressed="true" tabindex="0" data-value="bold"
+ *             data-stimeo--toggle-group-target="item"
+ *             data-action="click->stimeo--toggle-group#toggle
+ *                          keydown->stimeo--toggle-group#onKeydown">Bold</button>
+ *     <!-- more items; exactly one tabindex=0 -->
+ *   </div>
+ *
+ * Implements the WAI-ARIA APG **Button (toggle)** pattern with **Toolbar**-style
+ * roving navigation. Each item's pressed state is `aria-pressed` (the accessible
+ * name never changes); the group is a single Tab stop. For strict mutually
+ * exclusive selection with radio semantics, use
+ * {@link RadioGroupController | Radio Group} instead.
+ *
+ * @remarks
+ * Behavior only — the consumer styles off `[aria-pressed="true"]`. Per the
+ * Toolbar model the arrow keys move **focus only**; activation is Space/Enter
+ * (handled natively on `<button>` hosts, which synthesize a click).
+ *
+ * Behavior provided:
+ * - Click (or Space/Enter) toggles an item. In `single` mode pressing one item
+ *   releases the others (0 or 1 pressed); `multiple` allows any number.
+ * - `ArrowRight`/`ArrowDown` move focus to the next item, `ArrowLeft`/`ArrowUp`
+ *   to the previous (wrapping); `Home`/`End` to the first/last.
+ * - `stimeo--toggle-group:change` is dispatched on every toggle.
+ */
+declare class ToggleGroupController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        mode: {
+            type: StringConstructor;
+            default: string;
+        };
+    };
+    static actions: readonly ["onKeydown", "toggle"];
+    static events: readonly ["change"];
+    readonly itemTargets: HTMLElement[];
+    modeValue: string;
+    /** Establishes the roving entry point (first pressed item, else the first). */
+    connect(): void;
+    /** Toggles the activated item. Bound via `data-action` (click). */
+    toggle(event: Event): void;
+    /** Arrow/Home/End move focus only; Space/Enter toggle non-button hosts. */
+    onKeydown(event: KeyboardEvent): void;
+}
+
+export { ToggleGroupController };

package/dist/controllers/toggle_group_controller.js

@@ -0,0 +1,130 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/toggle_group_controller.ts
+
+// src/utils/roving_tabindex.ts
+var RovingTabindex = class {
+  /** Returns the current ordered item elements; called on every operation. */
+  #getItems;
+  /**
+   * @param getItems - Returns the current ordered item elements. Called on every
+   *   operation so the live target list is always used.
+   */
+  constructor(getItems) {
+    this.#getItems = getItems;
+  }
+  /** Index of the currently tabbable item (`tabindex="0"`), or `-1` if none. */
+  get activeIndex() {
+    return this.#getItems().findIndex((item) => item.tabIndex === 0);
+  }
+  /**
+   * Makes exactly the item at `index` tabbable (`tabindex="0"`) and removes every
+   * other item from the Tab sequence (`tabindex="-1"`). An out-of-range `index`
+   * (e.g. `-1`) leaves all items at `-1`, which a controller can use to express
+   * "nothing is currently tabbable".
+   *
+   * @param index - Position of the item to make tabbable.
+   * @param options - Pass `{ focus: true }` to also move DOM focus to that item.
+   */
+  setActive(index, { focus = false } = {}) {
+    const items = this.#getItems();
+    items.forEach((item, i) => {
+      item.tabIndex = i === index ? 0 : -1;
+    });
+    if (focus) items[index]?.focus();
+  }
+};
+function rovingMove(current, length, delta, wrap) {
+  if (length === 0) return -1;
+  const next = current + delta;
+  return (next + length) % length;
+}
+
+// src/controllers/toggle_group_controller.ts
+var ToggleGroupController = class extends Controller {
+  static targets = ["item"];
+  static values = {
+    mode: { type: String, default: "multiple" }
+  };
+  static actions = ["onKeydown", "toggle"];
+  static events = ["change"];
+  #roving = new RovingTabindex(() => this.itemTargets);
+  /** Establishes the roving entry point (first pressed item, else the first). */
+  connect() {
+    const firstPressed = this.itemTargets.findIndex((item) => this.#isPressed(item));
+    this.#roving.setActive(firstPressed === -1 ? 0 : firstPressed);
+  }
+  /** Toggles the activated item. Bound via `data-action` (click). */
+  toggle(event) {
+    this.#toggleIndex(this.itemTargets.indexOf(event.currentTarget));
+  }
+  /** Arrow/Home/End move focus only; Space/Enter toggle non-button hosts. */
+  onKeydown(event) {
+    const current = this.itemTargets.indexOf(event.currentTarget);
+    if (current === -1) return;
+    let next = null;
+    switch (event.key) {
+      case "ArrowRight":
+      case "ArrowDown":
+        next = rovingMove(current, this.itemTargets.length, 1);
+        break;
+      case "ArrowLeft":
+      case "ArrowUp":
+        next = rovingMove(current, this.itemTargets.length, -1);
+        break;
+      case "Home":
+        next = 0;
+        break;
+      case "End":
+        next = this.itemTargets.length - 1;
+        break;
+      case " ":
+      case "Enter":
+        if (event.currentTarget instanceof HTMLButtonElement) return;
+        event.preventDefault();
+        this.#toggleIndex(current);
+        return;
+      default:
+        return;
+    }
+    event.preventDefault();
+    this.#roving.setActive(next, { focus: true });
+  }
+  /** Applies the toggle at `index` per the current mode and dispatches `change`. */
+  #toggleIndex(index) {
+    const item = this.itemTargets[index];
+    if (!item) return;
+    const willPress = !this.#isPressed(item);
+    if (this.modeValue === "single") {
+      this.itemTargets.forEach((other, i) => {
+        this.#setPressed(other, i === index && willPress);
+      });
+    } else {
+      this.#setPressed(item, willPress);
+    }
+    this.#roving.setActive(index);
+    this.dispatch("change", {
+      detail: { value: this.#itemValue(item), pressed: willPress, values: this.#pressedValues() }
+    });
+  }
+  /** Whether an item is currently pressed. */
+  #isPressed(item) {
+    return item.getAttribute("aria-pressed") === "true";
+  }
+  /** Reflects the pressed state on `aria-pressed`. */
+  #setPressed(item, pressed) {
+    item.setAttribute("aria-pressed", pressed ? "true" : "false");
+  }
+  /** The `data-value` of every currently pressed item. */
+  #pressedValues() {
+    return this.itemTargets.filter((item) => this.#isPressed(item)).map((item) => this.#itemValue(item));
+  }
+  /** An item's value (`data-value`, defaulting to empty). */
+  #itemValue(item) {
+    return item.getAttribute("data-value") ?? "";
+  }
+};
+
+export { ToggleGroupController };
+//# sourceMappingURL=toggle_group_controller.js.map
+//# sourceMappingURL=toggle_group_controller.js.map

package/dist/controllers/toggle_group_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/roving_tabindex.ts","../../src/controllers/toggle_group_controller.ts"],"names":[],"mappings":";;;;;AAqBO,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;;;AC/CO,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;AACpC,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;AAC1B,IAAA,QAAQ,MAAM,GAAA;AAAK,MACjB,KAAK,YAAA;AAAA,MACL,KAAK,WAAA;AACH,QAAA,IAAA,GAAO,WAAW,OAAA,EAAS,IAAA,CAAK,WAAA,CAAY,MAAA,EAAQ,CAAS,CAAA;AAC7D,QAAA;AAAA,MACF,KAAK,WAAA;AAAA,MACL,KAAK,SAAA;AACH,QAAA,IAAA,GAAO,WAAW,OAAA,EAAS,IAAA,CAAK,WAAA,CAAY,MAAA,EAAQ,EAAU,CAAA;AAC9D,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":["/**\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"]}

package/dist/controllers/toolbar_controller.d.ts

@@ -0,0 +1,59 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless, accessible toolbar behavior.
+ *
+ * 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 -->
+ *   </div>
+ *
+ * Implements the WAI-ARIA APG **Toolbar** pattern: the group is a single Tab
+ * stop (roving tabindex) and the arrow keys move focus between controls. Each
+ * control's own function (press, toggle, open a menu) stays with that element or
+ * its own controller — the toolbar only owns navigation.
+ *
+ * @remarks
+ * Behavior only. The roving mechanics are delegated to {@link RovingTabindex};
+ * orientation and wrap policy stay here per the APG (they differ per widget).
+ *
+ * Behavior provided:
+ * - Exactly one control is tabbable (`tabindex="0"`); the rest are `-1`.
+ * - `ArrowRight`/`ArrowLeft` (horizontal) or `ArrowDown`/`ArrowUp` (vertical)
+ *   move focus to the next/previous control; `Home`/`End` to the first/last.
+ * - 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.
+ */
+declare class ToolbarController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        orientation: {
+            type: StringConstructor;
+            default: string;
+        };
+        wrap: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+    };
+    static actions: readonly ["onKeydown"];
+    readonly controlTargets: HTMLElement[];
+    orientationValue: string;
+    wrapValue: boolean;
+    /**
+     * 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).
+     */
+    connect(): void;
+    /** Arrow/Home/End move focus and the single tab stop. Bound via `data-action`. */
+    onKeydown(event: KeyboardEvent): void;
+}
+
+export { ToolbarController };