stimeo-ui 0.16.0 → 0.18.0

package/dist/controllers/tree_view_controller.js

@@ -1,19 +1,137 @@
 import { Controller } from '@hotwired/stimulus';
 
-// src/controllers/tree_view_controller.ts
+var FOCUS_EVENTS = /* @__PURE__ */ new Set(["blur", "focus", "focusin", "focusout"]);
+var POINTER_EVENTS = /* @__PURE__ */ new Set(["mouseenter", "mouseleave", "pointerenter", "pointerleave"]);
+function stateReasonFor(event) {
+  if (!event) return "api";
+  if (FOCUS_EVENTS.has(event.type)) return "focus";
+  if (POINTER_EVENTS.has(event.type)) return "pointer";
+  return "user";
+}
+
+function actionSource(source) {
+  if (source instanceof HTMLElement) {
+    return { event: null, host: source, origin: source, reason: "api" };
+  }
+  const event = source ?? null;
+  return {
+    event,
+    host: event?.currentTarget instanceof Element ? event.currentTarget : null,
+    origin: event?.target instanceof Element ? event.target : null,
+    reason: stateReasonFor(event)
+  };
+}
 
-// 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");
 }
+function hasModifierChord(event) {
+  return event.altKey || event.ctrlKey || event.metaKey || event.shiftKey;
+}
+
+function setAttributeIfChanged(element, name, value, beforeWrite) {
+  if (element.getAttribute(name) === value) return false;
+  beforeWrite?.();
+  if (value === null) element.removeAttribute(name);
+  else element.setAttribute(name, value);
+  return true;
+}
+
+var AuthoredMutationWatcher = class {
+  #onAuthored;
+  #claims = null;
+  #observer = null;
+  constructor(onAuthored) {
+    this.#onAuthored = onAuthored;
+  }
+  observe(root, options) {
+    this.disconnect();
+    const observer = new MutationObserver((records) => {
+      if (this.#observer !== observer) return;
+      const authored = this.#filter(records);
+      if (authored.length > 0) this.#onAuthored(authored);
+    });
+    this.#observer = observer;
+    this.#claims = { attributes: /* @__PURE__ */ new Map(), children: /* @__PURE__ */ new Map() };
+    observer.observe(root, {
+      attributes: true,
+      attributeFilter: [...options.attributes],
+      subtree: options.subtree ?? false,
+      childList: options.childList ?? false
+    });
+    if (options.ancestorAttributes) {
+      let ancestor = root.parentElement;
+      while (ancestor) {
+        observer.observe(ancestor, {
+          attributes: true,
+          attributeFilter: [...options.ancestorAttributes]
+        });
+        ancestor = ancestor.parentElement;
+      }
+    }
+  }
+  claim(target, name, value) {
+    const claims = this.#claims?.attributes;
+    let attributes = claims?.get(target);
+    if (!attributes) {
+      attributes = /* @__PURE__ */ new Map();
+      claims?.set(target, attributes);
+    }
+    const pending = attributes.get(name);
+    attributes.set(name, { value, count: (pending?.count ?? 0) + 1 });
+  }
+  claimCurrent(target, name) {
+    this.claim(target, name, target.getAttribute(name));
+  }
+  claimChildList(target, added, removed) {
+    const claims = this.#claims?.children;
+    const pending = claims?.get(target) ?? { added: /* @__PURE__ */ new Map(), removed: /* @__PURE__ */ new Map() };
+    for (const node of added) pending.added.set(node, (pending.added.get(node) ?? 0) + 1);
+    for (const node of removed) pending.removed.set(node, (pending.removed.get(node) ?? 0) + 1);
+    claims?.set(target, pending);
+  }
+  take() {
+    return this.#filter(this.#observer?.takeRecords() ?? []);
+  }
+  disconnect() {
+    this.#observer?.disconnect();
+    this.#observer = null;
+    this.#claims = null;
+  }
+  #filter(records) {
+    const authored = records.filter((record) => !this.#consume(record));
+    this.#claims?.attributes.clear();
+    this.#claims?.children.clear();
+    return authored;
+  }
+  #consume(record) {
+    if (record.type === "attributes") {
+      const target = record.target;
+      const pending2 = this.#claims?.attributes.get(target)?.get(record.attributeName);
+      if (!pending2 || pending2.count === 0 || target.getAttribute(record.attributeName) !== pending2.value) {
+        return false;
+      }
+      pending2.count -= 1;
+      return true;
+    }
+    const pending = this.#claims?.children.get(record.target);
+    if (!pending) return false;
+    const added = [...record.addedNodes];
+    const removed = [...record.removedNodes];
+    if (added.some((node) => !pending.added.get(node)) || removed.some((node) => !pending.removed.get(node))) {
+      return false;
+    }
+    for (const node of added) pending.added.set(node, (pending.added.get(node) ?? 0) - 1);
+    for (const node of removed) pending.removed.set(node, (pending.removed.get(node) ?? 0) - 1);
+    return true;
+  }
+};
 
-// src/utils/field_mirror.ts
 function writeField(field, value) {
   if (field.value === value) return false;
   field.value = value;
@@ -23,7 +141,6 @@ function commitField(target) {
   target.dispatchEvent(new Event("change", { bubbles: true }));
 }
 
-// src/utils/focus_candidate.ts
 function inheritsFieldsetDisabled(control) {
   let fieldset = control.closest("fieldset[disabled]");
   while (fieldset) {
@@ -33,15 +150,25 @@ function inheritsFieldsetDisabled(control) {
   }
   return false;
 }
+function unslotted(element) {
+  return element.assignedSlot === null && element.parentElement?.shadowRoot != null;
+}
+function flatTreeParent(element) {
+  if (unslotted(element)) return null;
+  const parent = element.assignedSlot ?? element.parentNode;
+  if (parent instanceof ShadowRoot) return parent.host;
+  return parent instanceof Element ? parent : null;
+}
 function canTakeFocus(element) {
-  if (element.closest("[hidden], [inert]")) return false;
+  for (let node = element; node; node = flatTreeParent(node)) {
+    if (unslotted(node) || node.matches("[hidden], [inert]")) return false;
+  }
   if (element instanceof HTMLInputElement && element.type === "hidden") return false;
   if (!("disabled" in element)) return true;
   if (element.disabled) return false;
   return !inheritsFieldsetDisabled(element);
 }
 
-// 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;
@@ -58,27 +185,36 @@ function isInteractiveHost(element) {
   return false;
 }
 
-// src/utils/microtask_coalescer.ts
+var ListenerSet = class {
+  #abort = new AbortController();
+  add(target, type, handler, options) {
+    target.addEventListener(type, handler, { ...options, signal: this.#abort.signal });
+  }
+  dispose() {
+    this.#abort.abort();
+    this.#abort = new AbortController();
+  }
+};
+
 var MicrotaskCoalescer = class {
   #run;
   #queued = false;
   #active = false;
   #generation = 0;
-  /** @param run - the single reconciliation pass, invoked at most once per batch. */
   constructor(run) {
     this.#run = run;
   }
-  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
   activate() {
     this.#active = true;
   }
-  /** Closes the window and drops any pending pass; call from `disconnect()`. */
   cancel() {
     this.#active = false;
     this.#queued = false;
     this.#generation += 1;
   }
-  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
+  get pending() {
+    return this.#queued;
+  }
   schedule() {
     if (!this.#active || this.#queued) return;
     this.#queued = true;
@@ -91,31 +227,53 @@ var MicrotaskCoalescer = class {
   }
 };
 
-// src/utils/roving_tabindex.ts
+var MorphRenderWatcher = class {
+  #listeners = new ListenerSet();
+  #pass;
+  #element = null;
+  #onMorph = () => this.#pass.schedule();
+  constructor(run) {
+    this.#pass = new MicrotaskCoalescer(run);
+  }
+  observe(element) {
+    if (this.#element === element) return;
+    this.disconnect();
+    this.#element = element;
+    this.#pass.activate();
+    this.#listeners.add(element, "turbo:morph-element", this.#onMorph);
+  }
+  schedule() {
+    this.#pass.schedule();
+  }
+  get pending() {
+    return this.#pass.pending;
+  }
+  disconnect() {
+    this.#listeners.dispose();
+    this.#pass.cancel();
+    this.#element = null;
+  }
+};
+
+var MoveCounter = class {
+  #sequence = 0;
+  record() {
+    this.#sequence += 1;
+    return this.#sequence;
+  }
+  isLatest(token) {
+    return token === this.#sequence;
+  }
+};
+
 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,
-   *   and `items` to reuse an event-scoped collection snapshot.
-   */
   setActive(index, options = {}) {
     const { focus = false } = options;
     const items = options.items ?? this.#getItems();
@@ -126,43 +284,28 @@ var RovingTabindex = class {
   }
 };
 
-// src/utils/safe_timeout.ts
+function targetSelector(identifier, name) {
+  return `[data-${identifier}-target~="${name}"]`;
+}
+
 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);
@@ -179,29 +322,18 @@ var SafeTimeout = class extends TimerRegistry {
   }
 };
 
-// src/utils/typeahead.ts
 var TYPEAHEAD_RESET_MS = 500;
 var Typeahead = class {
-  /** Timer registry for the pending idle reset; private so `reset()` is the only exit. */
   #timers = new SafeTimeout();
-  /** Idle window before the query resets, in milliseconds. */
   #resetMs;
-  /** The accumulated lowercase query, empty when idle. */
   #query = "";
-  /** Id of the pending reset timer, `0` when none is scheduled. */
   #timerId = 0;
-  /** @param options - Overrides for the idle window. */
   constructor({ resetMs = TYPEAHEAD_RESET_MS } = {}) {
     this.#resetMs = resetMs;
   }
-  /** The query a search would currently run with; empty while idle. */
   get query() {
     return this.#query;
   }
-  /**
-   * Folds `key` into the query, restarts the idle window, and returns the query to
-   * search with. A repeated character collapses the query to that one character.
-   */
   push(key) {
     const char = key.toLowerCase();
     const repeated = this.#query.length > 0 && [...this.#query].every((c) => c === char);
@@ -210,7 +342,6 @@ var Typeahead = class {
     this.#timerId = this.#timers.set(() => this.reset(), this.#resetMs);
     return this.#query;
   }
-  /** Clears the query and cancels the pending idle reset. */
   reset() {
     this.#query = "";
     this.#timers.clear(this.#timerId);
@@ -237,62 +368,28 @@ function findTypeaheadMatch(items, from, query, label = (item) => typeaheadLabel
   return -1;
 }
 
-// src/controllers/tree_view_controller.ts
 var OBSERVED_ATTRIBUTES = ["aria-selected", "data-value"];
-function setAttributeIfChanged(element, name, value) {
-  if (element.getAttribute(name) !== value) element.setAttribute(name, value);
-}
 var NESTED_INTERACTIVE = INTERACTIVE_HOST_SELECTOR;
 var TreeViewController = class extends Controller {
+  #moves = new MoveCounter();
+  #connectionGeneration = 0;
   static targets = ["item", "group", "field"];
-  static actions = ["onClick", "onKeydown", "toggle"];
+  static actions = ["onKeydown", "select", "toggle"];
   static events = ["select", "toggle", "reconcile"];
   #roving = new RovingTabindex(() => this.itemTargets);
   #typeahead = new Typeahead();
-  #timers = new SafeTimeout();
-  /**
-   * Collapses the item and field callbacks and observed item writes of one DOM
-   * mutation into a single selection pass; refused before `connect()` and after
-   * `disconnect()`.
-   */
-  #reconcile = new MicrotaskCoalescer(() => this.#reconcileSelection());
-  /** Watches the item attributes a page can rewrite in place; set while connected. */
-  #observer = null;
-  /** The selection last settled: on connect, by the user, or by a reported pass. */
+  #reconcile = new MorphRenderWatcher(() => this.#reconcileSelection());
+  #observer = new AuthoredMutationWatcher((records) => {
+    if (this.#concernsItems(records)) this.#reconcile.schedule();
+  });
   #settled = { item: null, value: "" };
   #connected = false;
-  /**
-   * Item targets in DOM order as of the last connect / target change. A removed
-   * item is gone from `itemTargets` by the time Stimulus reports it, so this is
-   * the only record of where in the order the gap opened.
-   */
   #order = [];
-  /** The `treeitem` that last took DOM focus inside this tree, if any. */
   #focused = null;
-  /**
-   * Records which row owns DOM focus. `focusin` bubbles, so one listener covers
-   * rows and anything nested in them; the tree needs this because a removal is
-   * only reported *after* the fact, when the browser has already reset
-   * `document.activeElement`.
-   */
   #onFocusIn = (event) => {
     const target = event.target;
     this.#focused = target?.closest('[role="treeitem"]') ?? null;
   };
-  /**
-   * Forgets the tracked row when focus genuinely leaves the tree, so a later
-   * removal of that row cannot be mistaken for "focus died with it" and pull
-   * focus back in.
-   *
-   * A *removed* focused row must not clear the record — that is exactly the case
-   * {@link TreeViewController.itemTargetDisconnected} needs it for. The two are
-   * indistinguishable while the event is dispatching: Chromium fires `focusout`
-   * for a removed row *before* the detach lands — `isConnected` still reads
-   * `true` — with `document.activeElement` already on `<body>`, exactly like a
-   * plain `blur()`. Deciding on a microtask separates them — a row that is gone
-   * by then was removed. Focus moving between two rows needs no handling:
-   * `focusin` overwrites the record right after.
-   */
   #onFocusOut = (event) => {
     const target = event.target;
     const row = target?.closest('[role="treeitem"]') ?? null;
@@ -303,15 +400,10 @@ var TreeViewController = class extends Controller {
       if (this.#focused === row && row.isConnected) this.#focused = null;
     });
   };
-  /**
-   * Reconciles authored expansion state, establishes the single tab stop, and
-   * settles the selection without reporting it. Idempotent, so a Turbo cache
-   * restore / morph re-runs it safely (re-adding the same listener reference is a
-   * no-op per the DOM spec).
-   */
+  #listeners = new ListenerSet();
   connect() {
-    this.element.addEventListener("focusin", this.#onFocusIn);
-    this.element.addEventListener("focusout", this.#onFocusOut);
+    this.#listeners.add(this.element, "focusin", this.#onFocusIn);
+    this.#listeners.add(this.element, "focusout", this.#onFocusOut);
     this.#seedFocused();
     this.#reconcileExpansion();
     this.#normalizeSelection();
@@ -320,163 +412,77 @@ var TreeViewController = class extends Controller {
     this.#order = [...this.itemTargets];
     this.#settled = this.#selection();
     this.#connected = true;
-    this.#reconcile.activate();
+    this.#reconcile.observe(this.element);
     this.#observeItems();
   }
-  /** Fills a form field inserted or replaced at runtime with the current selection. */
   fieldTargetConnected() {
     this.#reconcile.schedule();
   }
-  /**
-   * Detaches the focus trackers and the item observer, drops a queued selection
-   * pass, the typeahead buffer and its timer.
-   */
+  fieldTargetDisconnected() {
+    this.#reconcile.schedule();
+  }
   disconnect() {
-    this.element.removeEventListener("focusin", this.#onFocusIn);
-    this.element.removeEventListener("focusout", this.#onFocusOut);
+    this.#connectionGeneration += 1;
+    this.#listeners.dispose();
     this.#connected = false;
-    this.#reconcile.cancel();
-    this.#observer?.disconnect();
-    this.#observer = null;
+    this.#reconcile.disconnect();
+    this.#observer.disconnect();
     this.#typeahead.reset();
-    this.#timers.clearAll();
     this.#order = [];
     this.#focused = null;
   }
-  /**
-   * Seeds the focus record from the live document. A row can already hold focus
-   * when the controller connects (a Turbo restore, or `data-controller` added to
-   * a tree the user was already in), and the `focusin` listener alone would
-   * never learn about it.
-   */
   #seedFocused() {
-    const active = this.element.ownerDocument.activeElement;
-    this.#focused = active instanceof HTMLElement && this.element.contains(active) ? active.closest('[role="treeitem"]') : null;
-  }
-  /**
-   * Re-normalizes the tab stop when a `treeitem` is added at runtime, so an
-   * appended item carrying `tabindex="0"` cannot turn the tree into two Tab
-   * stops, and settles the selection once the batch is in. Skipped before
-   * `connect()`: Stimulus registers the initial targets first, and `connect()`
-   * owns the initial tab-stop policy.
-   */
+    this.#focused = this.element.ownerDocument.activeElement?.closest('[role="treeitem"]') ?? null;
+  }
   itemTargetConnected() {
     if (!this.#connected) return;
     this.#normalizeTabStop();
     this.#trackOrder();
     this.#reconcile.schedule();
   }
-  /**
-   * Brings authored `aria-selected` to the shape the APG requires, without
-   * changing which item the author chose.
-   *
-   * Every item gets an explicit value — an absent `aria-selected` means "not
-   * selectable" in ARIA, so a forgotten attribute hides a selectable row — and a
-   * single-select tree keeps at most one `true`, first in DOM order: an item the
-   * page inserts ahead of the selection, already selected, takes it over.
-   * `connect()` reconciles authored expansion the same way. The scan is the
-   * `item` target set: a `role="treeitem"` without the target is outside the
-   * contract and is neither counted nor written.
-   */
   #normalizeSelection() {
     const items = this.itemTargets;
     const selected = items.find((item) => item.getAttribute("aria-selected") === "true");
     for (const item of items) {
-      setAttributeIfChanged(item, "aria-selected", item === selected ? "true" : "false");
+      this.#writeSelection(item, item === selected ? "true" : "false");
     }
   }
-  /**
-   * Mirrors the selected item's `data-value` into the optional form field.
-   * Nothing selected, and an item that carries no value, both submit `""`.
-   */
   #mirrorField(notify) {
     if (!this.hasFieldTarget) return;
     const moved = writeField(this.fieldTarget, this.#selection().value);
     if (moved && notify) commitField(this.fieldTarget);
   }
-  /** The selected item target, if any, and the value its field submits. */
   #selection() {
     const item = this.itemTargets.find((candidate) => candidate.getAttribute("aria-selected") === "true") ?? null;
     return { item, value: item?.dataset.value ?? "" };
   }
-  /**
-   * The pass the page's changes run: the selection is normalized and mirrored,
-   * then reported if it moved. The report comes last, so items a subscriber
-   * rewrites are the next pass's to settle.
-   */
   #reconcileSelection() {
+    this.#reconcileExpansion();
     this.#normalizeSelection();
-    this.#dropOwnRecords();
+    this.#normalizeTabStop();
+    this.#flushMutations();
     this.#mirrorField(false);
     this.#reportMove();
   }
-  /**
-   * Reports the selection as `reconcile` when its item or value differs from the
-   * selection last settled. The settled selection is replaced before dispatching,
-   * so a move a subscriber makes is measured against what it was told.
-   */
   #reportMove() {
     const selection = this.#selection();
     if (selection.item === this.#settled.item && selection.value === this.#settled.value) return;
     this.#settled = selection;
     this.dispatch("reconcile", { detail: { item: selection.item } });
   }
-  /**
-   * Watches the items' `aria-selected` and `data-value`. The tree's own writes to
-   * them are dropped from the queue as they happen, so each record the callback
-   * receives is the page's, and only a record on one of the tree's own items
-   * schedules a pass.
-   */
   #observeItems() {
-    const observer = new MutationObserver((records) => {
-      if (this.#concernsItems(records)) this.#reconcile.schedule();
-    });
-    observer.observe(this.element, {
+    this.#observer.observe(this.element, {
       subtree: true,
-      attributes: true,
-      attributeFilter: OBSERVED_ATTRIBUTES
+      attributes: OBSERVED_ATTRIBUTES
     });
-    this.#observer = observer;
   }
-  /**
-   * Whether any record is about one of this tree's own items. A widget nested in a
-   * row writes the same attributes on its own elements, and those are no reason to
-   * reconcile the tree.
-   */
   #concernsItems(records) {
     const items = new Set(this.itemTargets);
     return records.some((record) => items.has(record.target));
   }
-  /**
-   * Drops the records the tree's own writes just queued, so the observer never
-   * takes them for the page's. A page write queued just before goes with them and
-   * owes nothing: every such write leaves every item's `aria-selected` at the value
-   * the selection gives it, and the selection is then read back from the DOM, so it
-   * already holds what the page wrote.
-   */
-  #dropOwnRecords() {
-    this.#observer?.takeRecords();
-  }
-  /**
-   * Restores the roving invariants when a `treeitem` leaves at runtime — a Turbo
-   * Stream `remove`, a morph, or plain DOM surgery. The mirror of
-   * {@link TreeViewController.itemTargetConnected}: without it, removing the row
-   * that held `tabindex="0"` leaves every survivor at `-1`, i.e. a tree with
-   * **no** Tab stop, and drops DOM focus to `<body>` when the removed subtree
-   * held it.
-   *
-   * The replacement is the nearest surviving *visible* item in the pre-removal
-   * order — the one after the gap, else the one before it — which is the row
-   * `ArrowDown` would have reached. Removing a non-active item changes nothing.
-   * When no visible item survives, a tree with zero Tab stops is the correct end
-   * state.
-   *
-   * Focus is only *restored*, never *stolen*: DOM focus moves solely when it was
-   * inside the removed subtree and the document has nowhere left to put it. The
-   * roving recovery runs here, while the pre-removal order is still on record;
-   * the selection is settled once the batch is in, and a selected item that left
-   * is reported as `reconcile` with no item.
-   */
+  #flushMutations() {
+    if (this.#concernsItems(this.#observer.take())) this.#reconcile.schedule();
+  }
   itemTargetDisconnected(item) {
     if (!this.#connected || !this.element.isConnected) return;
     const stranded = this.#focusDiedWith(item);
@@ -488,12 +494,6 @@ var TreeViewController = class extends Controller {
     this.#reconcile.schedule();
     this.#order = this.#order.filter((tracked) => tracked !== item);
   }
-  /**
-   * Folds newly connected targets into the DOM-order snapshot, keeping the slot
-   * of any item whose disconnect callback has not arrived yet — a morph that
-   * both adds and removes rows reports one batch as several callbacks, and
-   * {@link TreeViewController.#neighborOf} needs those slots.
-   */
   #trackOrder() {
     const live = this.itemTargets;
     const pending = this.#order.filter((tracked) => !live.includes(tracked));
@@ -507,15 +507,10 @@ var TreeViewController = class extends Controller {
     }
     this.#order = merged;
   }
-  /**
-   * Routes tree keyboard interaction. Because `treeitem`s nest, only the handler
-   * on the nearest item to the event target acts; the same keydown bubbling to an
-   * ancestor item's handler is ignored to avoid double moves / selections. Keys
-   * from a nested interactive control (or an IME composition) are left untouched.
-   */
   onKeydown(event) {
     if (event.defaultPrevented) return;
     if (isReservedArrowChord(event)) return;
+    if ((event.key === "Home" || event.key === "End") && hasModifierChord(event)) return;
     if (event.isComposing) return;
     const item = this.#ownerItem(event);
     if (!item) return;
@@ -528,15 +523,6 @@ var TreeViewController = class extends Controller {
         event.preventDefault();
         this.#moveBy(item, -1);
         break;
-      // Logical, not physical: APG describes these as "to the child level" and
-      // "to the parent level" — a spatial move — so they follow the writing
-      // direction, exactly as horizontal roving does. `isRtl()` is the shared
-      // detector; never introduce a second one.
-      //
-      // Direction comes from the tree, not from `item`: the tree is what lays
-      // the rows out, and a row may carry its own `dir` (an LTR path inside an
-      // RTL browser is ordinary bidi authoring). Probing the focused row instead
-      // would let one row's arrows mean the opposite of its sibling's.
       case "ArrowRight":
         event.preventDefault();
         if (isRtl(this.element)) this.#collapseOrLeave(item);
@@ -568,53 +554,43 @@ var TreeViewController = class extends Controller {
         break;
     }
   }
-  /** Selects the clicked item (nearest to the target only). */
-  onClick(event) {
-    const item = this.#ownerItem(event);
-    if (!item) return;
+  select(source) {
+    const { event, host, origin, reason } = actionSource(source);
+    const item = host?.closest(targetSelector(this.identifier, "item"));
+    if (!item || !this.itemTargets.includes(item)) return;
+    if (origin && origin.closest(`[data-controller~="${this.identifier}"]`) !== this.element)
+      return;
+    if (event && this.#ownerItem(event) !== item) return;
     const group = this.#childGroup(item);
-    if (group?.contains(event.target)) return;
-    this.#focusItem(item);
-    this.#select(item);
-  }
-  /**
-   * Expands or collapses the `treeitem` nearest to the event target. Optional:
-   * wire it on a chevron control so pointer users can reach child nodes, which
-   * otherwise only `ArrowRight` / `ArrowLeft` can do. A leaf item is a no-op.
-   *
-   * The toggled row then takes focus and the tab stop, matching what the keyboard
-   * path guarantees. Without it, a browser that focuses buttons on mousedown leaves
-   * focus on the clicked chevron: arrows would stop working until focus returns to a
-   * row, and a decorative `aria-hidden` chevron would hold focus. The synchronous
-   * `stimeo--tree-view:toggle` event is observed before this final focus hand-off.
-   */
-  toggle(event) {
-    const item = event.target.closest('[role="treeitem"]');
-    if (!item || !this.element.contains(item)) return;
-    if (!this.#childGroup(item)) return;
-    this.#setExpanded(item, !this.#isExpanded(item));
-    this.#focusItem(item);
-  }
-  /**
-   * The item a raw event belongs to, or `null` when the tree must not act: the
-   * event came from a nested `treeitem` (it bubbled to an ancestor's handler) or
-   * from an interactive control inside the item.
-   */
+    if (event && origin && group?.contains(origin)) return;
+    const moveFocus = event !== null || this.element.contains(document.activeElement);
+    this.#focusItem(item, moveFocus);
+    this.#select(item, reason);
+  }
+  toggle(source) {
+    const { event, origin, reason } = actionSource(source);
+    const item = origin?.closest(targetSelector(this.identifier, "item"));
+    if (!item || !this.itemTargets.includes(item)) return;
+    if (origin?.closest(`[data-controller~="${this.identifier}"]`) !== this.element) return;
+    const group = this.#childGroup(item);
+    if (!group) return;
+    const moveFocus = event !== null || this.element.contains(document.activeElement);
+    this.#setExpanded(item, group, !this.#isExpanded(item), reason);
+    this.#focusItem(
+      item,
+      moveFocus && (event !== null || this.element.contains(document.activeElement))
+    );
+  }
   #ownerItem(event) {
-    const item = event.currentTarget;
-    const target = event.target;
+    const { host, origin: target } = actionSource(event);
+    const item = host?.closest('[role="treeitem"]');
+    if (!item || !target) return null;
     if (target.closest('[role="treeitem"]') !== item) return null;
     const control = target.closest(NESTED_INTERACTIVE);
     if (control && item.contains(control)) return null;
-    if (isInteractiveHost(target)) return null;
+    if (target instanceof HTMLElement && isInteractiveHost(target)) return null;
     return item;
   }
-  /**
-   * The surviving visible item that inherits `removed`'s position: the next one
-   * in the pre-removal order, else the previous one. Falls back to the first
-   * visible item when `removed` is not in that order — a target that arrived and
-   * left between two callbacks — and to `undefined` when nothing visible is left.
-   */
   #neighborOf(removed) {
     const visible = this.#visibleItems;
     const index = this.#order.indexOf(removed);
@@ -628,14 +604,6 @@ var TreeViewController = class extends Controller {
     }
     return visible[0];
   }
-  /**
-   * Whether DOM focus went down with `removed`: it sat on that row (or inside
-   * it) and the document now has nowhere to put focus. A browser falls back to
-   * `<body>`; a still-referenced but detached `activeElement` is the same
-   * condition seen from the other side. Focus that landed on a real element —
-   * inside this tree or anywhere else on the page — is left alone, so a removal
-   * can never steal it.
-   */
   #focusDiedWith(removed) {
     const focused = this.#focused;
     if (!focused || focused !== removed && !removed.contains(focused)) return false;
@@ -644,7 +612,6 @@ var TreeViewController = class extends Controller {
     if (active === null || active === doc.body || active === doc.documentElement) return true;
     return !active.isConnected;
   }
-  /** Moves focus to the next (`delta=1`) or previous visible item, if any. */
   #moveBy(item, delta) {
     const visible = this.#visibleItems;
     const current = visible.indexOf(item);
@@ -652,17 +619,11 @@ var TreeViewController = class extends Controller {
     const next = visible[current + delta];
     if (next) this.#focusItem(next);
   }
-  /**
-   * Expands a collapsed parent, else steps into the first child.
-   *
-   * Bound to `ArrowRight` under LTR and `ArrowLeft` under RTL — the caller picks;
-   * this method only knows "toward the child level".
-   */
   #expandOrEnter(item) {
     const group = this.#childGroup(item);
     if (!group) return;
     if (!this.#isExpanded(item)) {
-      this.#setExpanded(item, true);
+      this.#setExpanded(item, group, true);
       return;
     }
     if (group.hidden) return;
@@ -671,34 +632,20 @@ var TreeViewController = class extends Controller {
     ).find((child) => !child.hidden);
     if (firstChild) this.#focusItem(firstChild);
   }
-  /** `ArrowLeft`: collapse an expanded parent, else step out to the parent item. */
   #collapseOrLeave(item) {
-    if (this.#childGroup(item) && this.#isExpanded(item)) {
-      this.#setExpanded(item, false);
+    const group = this.#childGroup(item);
+    if (group && this.#isExpanded(item)) {
+      this.#setExpanded(item, group, false);
       return;
     }
     const parent = this.#parentItem(item);
     if (parent) this.#focusItem(parent);
   }
-  /** Focuses the first (`0`) or last (`-1`) visible item. */
   #focusEdge(index) {
     const visible = this.#visibleItems;
     const target = index < 0 ? visible[visible.length - 1] : visible[index];
     if (target) this.#focusItem(target);
   }
-  /**
-   * Whether the item is disabled — **its own attribute or an ancestor's**.
-   *
-   * ARIA is explicit that the state carries down: "The state of being disabled
-   * applies to the current element *and all focusable descendant elements* of the
-   * element on which the `aria-disabled` attribute is applied." A tree is the only
-   * pattern here whose items nest, so it is the only place the inheritance is
-   * observable — but the rule is the shared one.
-   *
-   * The walk stops at the controller element: an `aria-disabled` on the tree root
-   * would otherwise disable every row, and a disabled *tree* is the consumer's
-   * call to make with `inert`, not something this controller infers.
-   */
   #isDisabled(item) {
     let current = item;
     while (current && current !== this.element) {
@@ -707,38 +654,31 @@ var TreeViewController = class extends Controller {
     }
     return false;
   }
-  /**
-   * Applies single selection and dispatches `select`. An `aria-disabled="true"`
-   * item stays focusable (APG keeps disabled nodes reachable) but is never
-   * activated, so consumers see no `select` for it.
-   */
-  #select(item) {
+  #select(item, reason = "user") {
     if (this.#isDisabled(item)) return;
+    const generation = this.#connectionGeneration;
     for (const candidate of this.itemTargets) {
-      setAttributeIfChanged(candidate, "aria-selected", candidate === item ? "true" : "false");
+      this.#writeSelection(candidate, candidate === item ? "true" : "false");
     }
-    this.#dropOwnRecords();
-    this.#settled = this.#selection();
+    this.#flushMutations();
+    const selection = this.#selection();
+    const changed = selection.item !== this.#settled.item || selection.value !== this.#settled.value;
+    this.#settled = selection;
+    if (!changed) {
+      this.#mirrorField(false);
+      return;
+    }
+    const token = this.#moves.record();
     this.#mirrorField(true);
-    this.dispatch("select", { detail: { item } });
+    if (generation !== this.#connectionGeneration || !this.#moves.isLatest(token)) return;
+    this.dispatch("select", { detail: { item, reason } });
   }
-  /** Updates expansion, reconciles a collapsed subtree, then synchronously dispatches `toggle`. */
-  #setExpanded(item, expanded) {
-    const group = this.#childGroup(item);
-    if (!group) return;
+  #setExpanded(item, group, expanded, reason = "user") {
     item.setAttribute("aria-expanded", String(expanded));
     group.hidden = !expanded;
     if (!expanded) this.#escapeCollapsedSubtree(item, group);
-    this.dispatch("toggle", { detail: { item, expanded } });
-  }
-  /**
-   * Reconciles focus and the roving tab stop before a synchronous `toggle` event
-   * observes a newly collapsed group. If DOM focus remains inside the group,
-   * both move to the parent. Otherwise only a stranded tab stop moves, preserving
-   * DOM focus. A native chevron click takes this path when mousedown has already
-   * focused the button. {@link TreeViewController.toggle} completes its focus
-   * hand-off after this reconciliation and event dispatch.
-   */
+    this.dispatch("toggle", { detail: { item, expanded, reason } });
+  }
   #escapeCollapsedSubtree(item, group) {
     const active = document.activeElement;
     if (active instanceof HTMLElement && group.contains(active)) {
@@ -746,23 +686,21 @@ var TreeViewController = class extends Controller {
       return;
     }
     const activeIndex = this.#roving.activeIndex;
-    const tabbable = activeIndex === -1 ? void 0 : this.itemTargets[activeIndex];
+    const tabbable = this.itemTargets[activeIndex];
     if (!tabbable || !group.contains(tabbable)) return;
     const index = this.itemTargets.indexOf(item);
     if (index !== -1) this.#roving.setActive(index);
   }
-  /** Makes `item` the single tab stop and moves DOM focus to it. */
-  #focusItem(item) {
+  #focusItem(item, focus = true) {
     const index = this.itemTargets.indexOf(item);
     if (index !== -1) {
-      this.#roving.setActive(index, { focus: true });
+      this.#roving.setActive(index, { focus });
       return;
     }
     if (!canTakeFocus(item)) return;
     item.tabIndex = -1;
     item.focus();
   }
-  /** Advances the typeahead query and focuses the next matching visible item. */
   #typeaheadTo(item, char) {
     const query = this.#typeahead.push(char);
     const visible = this.#visibleItems;
@@ -775,13 +713,6 @@ var TreeViewController = class extends Controller {
     const match = visible[index];
     if (match) this.#focusItem(match);
   }
-  /**
-   * Aligns each parent's `aria-expanded` with its child `group`'s `hidden`.
-   * `aria-expanded` wins when authored (it is what assistive tech reads); a
-   * parent without it derives one from `hidden` (establish-only-when-absent, so
-   * a restored snapshot is never clobbered). Disagreeing markup would otherwise
-   * strand the only tab stop on an invisible item.
-   */
   #reconcileExpansion() {
     for (const item of this.itemTargets) {
       const group = this.#childGroup(item);
@@ -793,32 +724,19 @@ var TreeViewController = class extends Controller {
       }
     }
   }
-  /**
-   * Leaves exactly one item tabbable. An existing, still-visible tab stop wins
-   * (the DOM is the source of truth after a Turbo restore, so the user's roving
-   * position survives); otherwise the selected item takes it (APG: a single-select
-   * tree puts initial focus on its selected node), else the first visible item.
-   */
   #normalizeTabStop() {
     const items = this.itemTargets;
     const visible = this.#visibleItems;
     const activeIndex = this.#roving.activeIndex;
-    const active = activeIndex === -1 ? void 0 : items[activeIndex];
+    const active = items[activeIndex];
     if (active && visible.includes(active)) {
       this.#roving.setActive(activeIndex);
       return;
     }
     const selected = visible.find((item) => item.getAttribute("aria-selected") === "true");
     const next = selected ?? visible[0];
-    this.#roving.setActive(next ? items.indexOf(next) : -1);
-  }
-  /**
-   * The visible items: those with no `hidden` ancestor up to the tree, and not
-   * `hidden` themselves. A hidden row is out of the move set — it can hold
-   * neither DOM focus nor the only Tab stop — and neither can anything nested
-   * under one, which is why the walk tests every ancestor rather than only the
-   * collapsed `role="group"` containers.
-   */
+    this.#roving.setActive(items.indexOf(next));
+  }
   get #visibleItems() {
     return this.itemTargets.filter((item) => {
       let node = item;
@@ -829,23 +747,15 @@ var TreeViewController = class extends Controller {
       return true;
     });
   }
-  /** The child `group` owned directly by `item`, or `null` for a leaf. */
   #childGroup(item) {
     return item.querySelector(':scope > [role="group"]');
   }
-  /** The nearest ancestor `treeitem`, or `null` at the root level. */
   #parentItem(item) {
     return item.parentElement?.closest('[role="treeitem"]') ?? null;
   }
-  /** Whether a parent item is currently expanded. */
   #isExpanded(item) {
     return item.getAttribute("aria-expanded") === "true";
   }
-  /**
-   * `item`'s name for typeahead. The fallback is the item's *own* text: a parent
-   * row's nested child group is rendered inside it, and folding a whole subtree
-   * into one name would let "readme" match the folder containing it.
-   */
   #label(item) {
     return typeaheadLabel(item, () => {
       let text = "";
@@ -858,8 +768,12 @@ var TreeViewController = class extends Controller {
       return text;
     });
   }
+  #writeSelection(target, value) {
+    setAttributeIfChanged(target, "aria-selected", value, () => {
+      this.#observer.claim(target, "aria-selected", value);
+    });
+  }
 };
 
 export { TreeViewController };
-//# sourceMappingURL=tree_view_controller.js.map
 //# sourceMappingURL=tree_view_controller.js.map