stimeo-ui 0.4.0 → 0.6.0

package/dist/controllers/toggle_group_controller.js

@@ -8,11 +8,46 @@ function isRtl(element) {
 }
 
 // src/utils/arrow_step.ts
+function logicalArrowStep(key, element) {
+  if (key === "ArrowDown") return 1;
+  if (key === "ArrowUp") return -1;
+  if (key !== "ArrowRight" && key !== "ArrowLeft") return 0;
+  const forward = isRtl(element) ? "ArrowLeft" : "ArrowRight";
+  return key === forward ? 1 : -1;
+}
 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/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/interactive_host.ts
+var INTERACTIVE_HOST_SELECTOR = "button, input, select, textarea, label, a[href], area[href], summary, details, audio[controls], video[controls], iframe, object, embed";
+function isInteractiveHost(element) {
+  if (element.matches(INTERACTIVE_HOST_SELECTOR)) return true;
+  let current = element;
+  while (current) {
+    const raw = current.getAttribute("contenteditable");
+    if (raw !== null) {
+      const value = raw.trim().toLowerCase();
+      if (value === "false") return false;
+      if (value === "" || value === "true" || value === "plaintext-only") return true;
+    }
+    current = current.parentElement;
+  }
+  return false;
+}
+
 // src/utils/roving_tabindex.ts
 var RovingTabindex = class {
   /** Returns the current ordered item elements; called on every operation. */
@@ -35,10 +70,12 @@ var RovingTabindex = class {
    * "nothing is currently tabbable".
    *
    * @param index - Position of the item to make tabbable.
-   * @param options - Pass `{ focus: true }` to also move DOM focus to that item.
+   * @param options - Pass `{ focus: true }` to also move DOM focus to that item,
+   *   and `items` to reuse an event-scoped collection snapshot.
    */
-  setActive(index, { focus = false } = {}) {
-    const items = this.#getItems();
+  setActive(index, options = {}) {
+    const { focus = false } = options;
+    const items = options.items ?? this.#getItems();
     items.forEach((item, i) => {
       item.tabIndex = i === index ? 0 : -1;
     });
@@ -52,6 +89,16 @@ function rovingMove(current, length, delta, wrap) {
 }
 
 // src/controllers/toggle_group_controller.ts
+var ITEM_ATTRIBUTES = [
+  "aria-pressed",
+  "disabled",
+  "hidden",
+  "type",
+  "href",
+  "contenteditable",
+  "controls"
+];
+var hasModifier = (event) => event.altKey || event.ctrlKey || event.metaKey || event.shiftKey;
 var ToggleGroupController = class extends Controller {
   static targets = ["item"];
   static values = {
@@ -59,86 +106,362 @@ var ToggleGroupController = class extends Controller {
   };
   static actions = ["onKeydown", "toggle"];
   static events = ["change"];
-  #roving = new RovingTabindex(() => this.itemTargets);
-  /** Establishes the roving entry point (first pressed item, else the first). */
+  #roving = new RovingTabindex(() => this.#managedTargets);
+  #handledEvents = /* @__PURE__ */ new WeakSet();
+  #managedItems = /* @__PURE__ */ new Set();
+  #originalTabindex = /* @__PURE__ */ new Map();
+  #ownedPressed = /* @__PURE__ */ new Set();
+  #internalPressedValues = /* @__PURE__ */ new Map();
+  #observer = null;
+  #connected = false;
+  /**
+   * Normalizes state and establishes one roving entry point. A single authored
+   * `tabindex="0"` survives reconnect; otherwise the first pressed, navigable
+   * item wins, falling back to the first navigable item.
+   */
   connect() {
-    const firstPressed = this.itemTargets.findIndex((item) => this.#isPressed(item));
-    this.#roving.setActive(firstPressed === -1 ? 0 : firstPressed);
+    const currentItems = new Set(this.itemTargets);
+    for (const item of this.#managedItems) {
+      if (!currentItems.has(item)) this.#releaseItem(item);
+    }
+    const authoredStops = this.itemTargets.filter(
+      (item) => this.#isSupportedHost(item) && item.getAttribute("tabindex") === "0" && this.#isNavigable(item)
+    );
+    const preferred = authoredStops.length === 1 ? authoredStops[0] : null;
+    for (const item of this.itemTargets) this.#reconcileHost(item, false);
+    this.#normalizeSelection();
+    this.#ensureTabStop(preferred);
+    this.element.addEventListener("click", this.#onClickCapture, true);
+    this.element.addEventListener("keydown", this.#onKeydownCapture, true);
+    this.element.addEventListener("click", this.#onClick);
+    this.element.addEventListener("keydown", this.#onKeydown);
+    this.element.addEventListener("focusin", this.#onFocusin);
+    this.#connected = true;
+    this.#internalPressedValues.clear();
+    this.#observeMutations();
+  }
+  /** Releases every listener and observer while retaining DOM state for Turbo cache/reconnect. */
+  disconnect() {
+    this.#connected = false;
+    this.element.removeEventListener("click", this.#onClickCapture, true);
+    this.element.removeEventListener("keydown", this.#onKeydownCapture, true);
+    this.element.removeEventListener("click", this.#onClick);
+    this.element.removeEventListener("keydown", this.#onKeydown);
+    this.element.removeEventListener("focusin", this.#onFocusin);
+    this.#observer?.disconnect();
+    this.#observer = null;
+    this.#internalPressedValues.clear();
+  }
+  /** Drops a newly connected item from the Tab sequence before reconciling the group. */
+  itemTargetConnected(item) {
+    if (!this.#connected) return;
+    this.#reconcileHost(item, true);
+    this.#normalizeSelection();
+    this.#ensureTabStop();
   }
-  /** Toggles the activated item. Bound via `data-action` (click). */
+  /** Restores attributes owned only while an element is an item and repairs the Tab stop. */
+  itemTargetDisconnected(item) {
+    if (!this.#connected) return;
+    this.#releaseItem(item);
+    this.#normalizeSelection();
+    this.#ensureTabStop();
+  }
+  /** Reconciles the single-selection invariant when the Stimulus Value changes. */
+  modeValueChanged() {
+    if (!this.#connected) return;
+    this.#normalizeSelection();
+    this.#ensureTabStop();
+  }
+  /**
+   * Toggles the action's item. Per-item action wiring is optional because click
+   * is also delegated from the group.
+   */
   toggle(event) {
-    this.#toggleIndex(this.itemTargets.indexOf(event.currentTarget));
+    if (event.defaultPrevented) return;
+    const item = event.currentTarget;
+    if (!item || !this.itemTargets.includes(item)) return;
+    this.#handledEvents.add(event);
+    this.#toggleItem(item);
   }
-  /** Arrow/Home/End move focus only; Space/Enter toggle non-button hosts. */
+  /**
+   * Moves focus or activates the action's item. Per-item action wiring is
+   * optional because keydown is also delegated from the group.
+   */
   onKeydown(event) {
-    if (event.defaultPrevented) return;
+    const item = event.currentTarget;
+    if (!item || !this.itemTargets.includes(item)) return;
+    this.#handleKeydown(event, item);
+  }
+  /** Blocks disabled activation before per-item or consumer event handlers run. */
+  #onClickCapture = (event) => {
+    const item = this.#itemForEventTarget(event.target);
+    if (!item || !this.#isSupportedHost(item) || !this.#isActivationDisabled(item)) return;
+    event.preventDefault();
+    event.stopImmediatePropagation();
+  };
+  /** Blocks disabled keyboard activation while leaving navigation keys available. */
+  #onKeydownCapture = (event) => {
+    if (event.key !== " " && event.key !== "Enter") return;
+    const item = this.#itemForEventTarget(event.target);
+    if (!item || !this.#isSupportedHost(item) || !this.#isActivationDisabled(item)) return;
+    event.preventDefault();
+    event.stopImmediatePropagation();
+  };
+  /** Delegated click path for static and runtime-added items without actions. */
+  #onClick = (event) => {
+    if (this.#handledEvents.delete(event) || event.defaultPrevented) return;
+    const item = this.#itemForEventTarget(event.target);
+    if (item) this.#toggleItem(item);
+  };
+  /** Delegated keydown path for static and runtime-added items without actions. */
+  #onKeydown = (event) => {
+    const item = this.#itemForEventTarget(event.target);
+    if (item) this.#handleKeydown(event, item);
+  };
+  /** Keeps programmatic and pointer focus as the group's next Tab entry point. */
+  #onFocusin = (event) => {
+    const item = this.#itemForEventTarget(event.target);
+    if (!item || !this.#isNavigable(item)) return;
+    this.#setActive(item);
+  };
+  /** Applies the APG navigation and activation key map to one supported item. */
+  #handleKeydown(event, item) {
+    if (event.defaultPrevented || !this.#isSupportedHost(item)) return;
+    if (event.isComposing) 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,
-          event.key === "ArrowDown" ? 1 : horizontalStep(event.key));
-        break;
-      case "ArrowLeft":
-      case "ArrowUp":
-        next = rovingMove(
-          current,
-          this.itemTargets.length,
-          event.key === "ArrowUp" ? -1 : horizontalStep(event.key));
-        break;
-      case "Home":
-        next = 0;
-        break;
-      case "End":
-        next = this.itemTargets.length - 1;
-        break;
-      case " ":
-      case "Enter":
-        if (event.currentTarget instanceof HTMLButtonElement) return;
+    if ((event.key === "Home" || event.key === "End") && hasModifier(event)) return;
+    if (!this.#managedItems.has(item)) this.#reconcileHost(item, true);
+    this.#ensureTabStop();
+    const items = this.#managedTargets;
+    const current = items.indexOf(item);
+    if (event.key === " " || event.key === "Enter") {
+      if (this.#isActivationDisabled(item)) {
         event.preventDefault();
-        this.#toggleIndex(current);
+        event.stopImmediatePropagation();
         return;
-      default:
+      }
+      if (item instanceof HTMLButtonElement) {
+        if (event.repeat) event.preventDefault();
         return;
+      }
+      event.preventDefault();
+      if (!event.repeat) this.#toggleItem(item);
+      return;
+    }
+    const step = logicalArrowStep(event.key, this.element);
+    let destination;
+    if (step !== 0) {
+      destination = this.#nextNavigable(current, step);
+    } else if (event.key === "Home") {
+      destination = this.#navigableItems[0];
+    } else if (event.key === "End") {
+      const navigable = this.#navigableItems;
+      destination = navigable[navigable.length - 1];
+    } else {
+      return;
     }
     event.preventDefault();
-    this.#roving.setActive(next, { focus: true });
+    if (destination) this.#setActive(destination, true);
   }
-  /** Applies the toggle at `index` per the current mode and dispatches `change`. */
-  #toggleIndex(index) {
-    const item = this.itemTargets[index];
-    if (!item) return;
+  /** Applies one user toggle and dispatches the documented change detail. */
+  #toggleItem(item) {
+    if (!this.#isSupportedHost(item) || this.#isActivationDisabled(item)) return;
+    if (!this.#managedItems.has(item)) this.#reconcileHost(item, true);
     const willPress = !this.#isPressed(item);
     if (this.modeValue === "single") {
-      this.itemTargets.forEach((other, i) => {
-        this.#setPressed(other, i === index && willPress);
-      });
+      for (const other of this.#managedTargets)
+        this.#setPressed(other, other === item && willPress);
     } else {
       this.#setPressed(item, willPress);
     }
-    this.#roving.setActive(index);
+    this.#setActive(item);
     this.dispatch("change", {
       detail: { value: this.#itemValue(item), pressed: willPress, values: this.#pressedValues() }
     });
   }
+  /** Reconciles supported hosts, pressed state, and the roving invariant after a DOM mutation. */
+  #reconcile() {
+    for (const item of this.itemTargets) this.#reconcileHost(item, true);
+    this.#normalizeSelection();
+    this.#ensureTabStop();
+  }
+  /** Begins or ends ownership according to the item's current host semantics. */
+  #reconcileHost(item, dropFromTabSequence) {
+    if (!this.#isSupportedHost(item)) {
+      this.#releaseItem(item);
+      return;
+    }
+    if (!this.#managedItems.has(item)) {
+      this.#managedItems.add(item);
+      this.#originalTabindex.set(item, item.getAttribute("tabindex"));
+      if (dropFromTabSequence) item.tabIndex = -1;
+    }
+    this.#normalizePressed(item);
+  }
+  /** Restores only defaults owned because an element belonged to this group. */
+  #releaseItem(item) {
+    if (!this.#managedItems.delete(item)) return;
+    const original = this.#originalTabindex.get(item);
+    if (original === null) item.removeAttribute("tabindex");
+    else if (original !== void 0) item.setAttribute("tabindex", original);
+    this.#originalTabindex.delete(item);
+    if (this.#ownedPressed.delete(item)) item.removeAttribute("aria-pressed");
+    this.#internalPressedValues.delete(item);
+  }
+  /** Supplies a missing pressed state and normalizes invalid ARIA tokens. */
+  #normalizePressed(item) {
+    const value = item.getAttribute("aria-pressed");
+    if (value === null) {
+      this.#ownedPressed.add(item);
+      this.#internalPressedValues.set(item, "false");
+      item.setAttribute("aria-pressed", "false");
+    } else if (value !== "true" && value !== "false") {
+      item.setAttribute("aria-pressed", "false");
+    }
+  }
+  /** Makes the first DOM-ordered pressed item the sole pressed item in single mode. */
+  #normalizeSelection() {
+    for (const item of this.#managedTargets) this.#normalizePressed(item);
+    if (this.modeValue !== "single") return;
+    let found = false;
+    for (const item of this.#managedTargets) {
+      if (!this.#isPressed(item)) continue;
+      if (!found) found = true;
+      else this.#setPressed(item, false);
+    }
+  }
+  /** Keeps one navigable Tab stop, preferring current DOM state after initial connect. */
+  #ensureTabStop(initialPreference) {
+    const navigable = this.#navigableItems;
+    let active;
+    if (initialPreference !== void 0) {
+      active = initialPreference ?? void 0;
+    } else {
+      const current = this.#managedTargets.filter(
+        (item) => item.tabIndex === 0 && this.#isNavigable(item)
+      );
+      if (current.length === 1) active = current[0];
+    }
+    active ??= navigable.find((item) => this.#isPressed(item));
+    active ??= navigable[0];
+    this.#setActive(active ?? null);
+  }
+  /** Moves through the full item order until a navigable destination is found. */
+  #nextNavigable(fromIndex, delta) {
+    const items = this.#managedTargets;
+    let index = fromIndex;
+    for (let step = 0; step < items.length; step++) {
+      index = rovingMove(index, items.length, delta);
+      const candidate = items[index];
+      if (candidate && this.#isNavigable(candidate)) return candidate;
+    }
+    return void 0;
+  }
+  /** Assigns the single roving Tab stop and optionally moves DOM focus. */
+  #setActive(item, focus = false) {
+    this.#roving.setActive(this.#managedTargets.indexOf(item), { focus });
+  }
+  /** Finds this group's item containing an event target, excluding nested groups. */
+  #itemForEventTarget(target) {
+    if (!this.#ownsEventTarget(target)) return void 0;
+    const node = target;
+    return this.itemTargets.find((item) => item === node || item.contains(node));
+  }
+  /** Whether the closest Toggle Group scope around a target is this instance. */
+  #ownsEventTarget(target) {
+    return target instanceof Element && target.closest('[data-controller~="stimeo--toggle-group"]') === this.element;
+  }
+  /** Hosts whose activation model can be owned without conflicting native behavior. */
+  #isSupportedHost(item) {
+    if (item instanceof HTMLButtonElement) return item.type === "button";
+    return !isInteractiveHost(item);
+  }
+  /** Items eligible for roving focus (ARIA-disabled deliberately remains eligible). */
+  #isNavigable(item) {
+    if (!this.#isSupportedHost(item) || this.#isHidden(item)) return false;
+    if (!(item instanceof HTMLButtonElement)) return true;
+    return !item.disabled && !inheritsFieldsetDisabled(item);
+  }
+  /** Whether hidden applies on the path from an item up to the group root. */
+  #isHidden(item) {
+    let current = item;
+    while (current && current !== this.element) {
+      if (current.hasAttribute("hidden")) return true;
+      current = current.parentElement;
+    }
+    return false;
+  }
+  /** Whether ARIA, visibility, or native HTML semantics suppress activation. */
+  #isActivationDisabled(item) {
+    if (!this.#isNavigable(item)) return true;
+    let current = item;
+    while (current) {
+      if (current.getAttribute("aria-disabled") === "true") return true;
+      current = current.parentElement;
+    }
+    return false;
+  }
+  /** Releases default ownership when a Turbo morph authors `aria-pressed`. */
+  #releaseAuthoredPressed(records) {
+    for (const record of records) {
+      if (record.attributeName !== "aria-pressed") continue;
+      const item = record.target;
+      const value = item.getAttribute("aria-pressed");
+      if (value !== null && this.#internalPressedValues.get(item) !== value) {
+        this.#ownedPressed.delete(item);
+      }
+    }
+    this.#internalPressedValues.clear();
+  }
+  /** Watches target membership, retained item hosts/state, and inherited host/fieldset state. */
+  #observeMutations() {
+    const observer = new MutationObserver((records) => {
+      this.#releaseAuthoredPressed(records);
+      observer.disconnect();
+      this.#reconcile();
+      this.#observeWith(observer);
+    });
+    this.#observer = observer;
+    this.#observeWith(observer);
+  }
+  /** Registers every root and ancestor observation on one observer instance. */
+  #observeWith(observer) {
+    observer.observe(this.element, {
+      subtree: true,
+      childList: true,
+      attributes: true,
+      attributeFilter: ITEM_ATTRIBUTES
+    });
+    let ancestor = this.element.parentElement;
+    while (ancestor) {
+      observer.observe(ancestor, {
+        attributes: true,
+        attributeFilter: ["contenteditable", "disabled"]
+      });
+      ancestor = ancestor.parentElement;
+    }
+  }
+  /** Supported targets currently managed by the roving primitive. */
+  get #managedTargets() {
+    return this.itemTargets.filter((item) => this.#managedItems.has(item));
+  }
+  /** Managed items eligible for the roving Tab stop. */
+  get #navigableItems() {
+    return this.#managedTargets.filter((item) => this.#isNavigable(item));
+  }
   /** Whether an item is currently pressed. */
   #isPressed(item) {
     return item.getAttribute("aria-pressed") === "true";
   }
-  /** Reflects the pressed state on `aria-pressed`. */
+  /** Reflects pressed state while distinguishing controller writes from authored morphs. */
   #setPressed(item, pressed) {
-    item.setAttribute("aria-pressed", pressed ? "true" : "false");
+    const value = pressed ? "true" : "false";
+    this.#internalPressedValues.set(item, value);
+    item.setAttribute("aria-pressed", value);
   }
-  /** The `data-value` of every currently pressed item. */
+  /** The DOM-ordered values of every currently pressed managed item. */
   #pressedValues() {
-    return this.itemTargets.filter((item) => this.#isPressed(item)).map((item) => this.#itemValue(item));
+    return this.#managedTargets.filter((item) => this.#isPressed(item)).map((item) => this.#itemValue(item));
   }
   /** An item's value (`data-value`, defaulting to empty). */
   #itemValue(item) {