stimeo-ui 0.15.0 → 0.17.0

data/dist/controllers/tree_view_controller.js

@@ -1,19 +1,45 @@
 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");
 }
 
-// src/utils/focus_candidate.ts
+function writeField(field, value) {
+  if (field.value === value) return false;
+  field.value = value;
+  return true;
+}
+function commitField(target) {
+  target.dispatchEvent(new Event("change", { bubbles: true }));
+}
+
 function inheritsFieldsetDisabled(control) {
   let fieldset = control.closest("fieldset[disabled]");
   while (fieldset) {
@@ -23,15 +49,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;
@@ -48,31 +84,89 @@ function isInteractiveHost(element) {
   return false;
 }
 
-// src/utils/roving_tabindex.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;
+  constructor(run) {
+    this.#run = run;
+  }
+  activate() {
+    this.#active = true;
+  }
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  schedule() {
+    if (!this.#active || this.#queued) return;
+    this.#queued = true;
+    const generation = this.#generation;
+    queueMicrotask(() => {
+      if (generation !== this.#generation || !this.#queued || !this.#active) return;
+      this.#queued = false;
+      this.#run();
+    });
+  }
+};
+
+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();
+  }
+  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();
@@ -83,43 +177,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);
@@ -136,29 +215,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);
@@ -167,7 +235,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);
@@ -194,48 +261,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 {
-  static targets = ["item", "group"];
-  static actions = ["onClick", "onKeydown", "toggle"];
-  static events = ["select", "toggle"];
+  #moves = new MoveCounter();
+  static targets = ["item", "group", "field"];
+  static actions = ["onKeydown", "select", "toggle"];
+  static events = ["select", "toggle", "reconcile"];
   #roving = new RovingTabindex(() => this.itemTargets);
   #typeahead = new Typeahead();
-  #timers = new SafeTimeout();
+  #reconcile = new MorphRenderWatcher(() => this.#reconcileSelection());
+  #observer = null;
+  #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;
@@ -246,11 +293,6 @@ var TreeViewController = class extends Controller {
       if (this.#focused === row && row.isConnected) this.#focused = null;
     });
   };
-  /**
-   * Reconciles authored expansion state and establishes the single tab stop.
-   * 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).
-   */
   connect() {
     this.element.addEventListener("focusin", this.#onFocusIn);
     this.element.addEventListener("focusout", this.#onFocusOut);
@@ -258,76 +300,87 @@ var TreeViewController = class extends Controller {
     this.#reconcileExpansion();
     this.#normalizeSelection();
     this.#normalizeTabStop();
+    this.#mirrorField(false);
     this.#order = [...this.itemTargets];
+    this.#settled = this.#selection();
     this.#connected = true;
+    this.#reconcile.observe(this.element);
+    this.#observeItems();
+  }
+  fieldTargetConnected() {
+    this.#reconcile.schedule();
+  }
+  fieldTargetDisconnected() {
+    this.#reconcile.schedule();
   }
-  /** Detaches the focus trackers, drops the typeahead buffer and its timer. */
   disconnect() {
     this.element.removeEventListener("focusin", this.#onFocusIn);
     this.element.removeEventListener("focusout", this.#onFocusOut);
     this.#connected = false;
+    this.#reconcile.disconnect();
+    this.#observer?.disconnect();
+    this.#observer = null;
     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. 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.#normalizeSelection();
     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. `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) {
-      item.setAttribute("aria-selected", item === selected ? "true" : "false");
+      setAttributeIfChanged(item, "aria-selected", item === selected ? "true" : "false");
     }
   }
-  /**
-   * 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.
-   */
+  #mirrorField(notify) {
+    if (!this.hasFieldTarget) return;
+    const moved = writeField(this.fieldTarget, this.#selection().value);
+    if (moved && notify) commitField(this.fieldTarget);
+  }
+  #selection() {
+    const item = this.itemTargets.find((candidate) => candidate.getAttribute("aria-selected") === "true") ?? null;
+    return { item, value: item?.dataset.value ?? "" };
+  }
+  #reconcileSelection() {
+    this.#reconcileExpansion();
+    this.#normalizeSelection();
+    this.#normalizeTabStop();
+    this.#dropOwnRecords();
+    this.#mirrorField(false);
+    this.#reportMove();
+  }
+  #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 } });
+  }
+  #observeItems() {
+    const observer = new MutationObserver((records) => {
+      if (this.#concernsItems(records)) this.#reconcile.schedule();
+    });
+    observer.observe(this.element, {
+      subtree: true,
+      attributes: true,
+      attributeFilter: OBSERVED_ATTRIBUTES
+    });
+    this.#observer = observer;
+  }
+  #concernsItems(records) {
+    const items = new Set(this.itemTargets);
+    return records.some((record) => items.has(record.target));
+  }
+  #dropOwnRecords() {
+    this.#observer?.takeRecords();
+  }
   itemTargetDisconnected(item) {
     if (!this.#connected || !this.element.isConnected) return;
     const stranded = this.#focusDiedWith(item);
@@ -336,14 +389,9 @@ var TreeViewController = class extends Controller {
       const next = this.#neighborOf(item);
       if (next) this.#roving.setActive(this.itemTargets.indexOf(next), { focus: stranded });
     }
+    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));
@@ -357,12 +405,6 @@ 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;
@@ -378,15 +420,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);
@@ -418,53 +451,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 (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?.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 (!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);
@@ -478,14 +501,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;
@@ -494,7 +509,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);
@@ -502,17 +516,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;
@@ -521,34 +529,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) {
@@ -557,35 +551,30 @@ 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;
     for (const candidate of this.itemTargets) {
-      candidate.setAttribute("aria-selected", candidate === item ? "true" : "false");
+      setAttributeIfChanged(candidate, "aria-selected", candidate === item ? "true" : "false");
+    }
+    this.#dropOwnRecords();
+    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;
     }
-    this.dispatch("select", { detail: { item } });
+    const token = this.#moves.record();
+    this.#mirrorField(true);
+    if (!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)) {
@@ -593,23 +582,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;
@@ -622,13 +609,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);
@@ -640,32 +620,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.findIndex((item) => item === next));
+  }
   get #visibleItems() {
     return this.itemTargets.filter((item) => {
       let node = item;
@@ -676,23 +643,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 = "";
@@ -708,5 +667,4 @@ var TreeViewController = class extends Controller {
 };
 
 export { TreeViewController };
-//# sourceMappingURL=tree_view_controller.js.map
 //# sourceMappingURL=tree_view_controller.js.map