stimeo-ui 0.2.0 → 0.3.0

package/dist/controllers/tree_view_controller.js

@@ -0,0 +1,691 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/tree_view_controller.ts
+
+// src/utils/logical_scroll.ts
+function isRtl(element) {
+  return window.getComputedStyle(element).direction === "rtl";
+}
+
+// src/utils/arrow_step.ts
+function isReservedArrowChord(event, allow = []) {
+  if (!event.key.startsWith("Arrow")) return false;
+  return event.altKey && !allow.includes("alt") || event.ctrlKey && !allow.includes("ctrl") || event.metaKey && !allow.includes("meta") || event.shiftKey && !allow.includes("shift");
+}
+
+// src/utils/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;
+}
+function canTakeFocus(element) {
+  if (element.closest("[hidden]")) return false;
+  if (!("disabled" in element)) return true;
+  if (element.disabled) return false;
+  return !inheritsFieldsetDisabled(element);
+}
+
+// src/utils/roving_tabindex.ts
+var RovingTabindex = class {
+  /** Returns the current ordered item elements; called on every operation. */
+  #getItems;
+  /**
+   * @param getItems - Returns the current ordered item elements. Called on every
+   *   operation so the live target list is always used.
+   */
+  constructor(getItems) {
+    this.#getItems = getItems;
+  }
+  /** Index of the currently tabbable item (`tabindex="0"`), or `-1` if none. */
+  get activeIndex() {
+    return this.#getItems().findIndex((item) => item.tabIndex === 0);
+  }
+  /**
+   * Makes exactly the item at `index` tabbable (`tabindex="0"`) and removes every
+   * other item from the Tab sequence (`tabindex="-1"`). An out-of-range `index`
+   * (e.g. `-1`) leaves all items at `-1`, which a controller can use to express
+   * "nothing is currently tabbable".
+   *
+   * @param index - Position of the item to make tabbable.
+   * @param options - Pass `{ focus: true }` to also move DOM focus to that item.
+   */
+  setActive(index, { focus = false } = {}) {
+    const items = this.#getItems();
+    items.forEach((item, i) => {
+      item.tabIndex = i === index ? 0 : -1;
+    });
+    if (focus) items[index]?.focus();
+  }
+};
+
+// src/utils/safe_timeout.ts
+var TimerRegistry = class {
+  /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
+  ids = /* @__PURE__ */ new Set();
+  /**
+   * Cancels a single tracked timer.
+   *
+   * No-ops if the id is unknown (already cleared, fired, or never owned by this
+   * registry), so callers can clear defensively without guarding.
+   */
+  clear(id) {
+    if (this.ids.delete(id)) {
+      this.cancel(id);
+    }
+  }
+  /**
+   * Cancels every tracked timer. Call this from a controller's `disconnect()`
+   * to guarantee no timer outlives the element.
+   */
+  clearAll() {
+    for (const id of this.ids) {
+      this.cancel(id);
+    }
+    this.ids.clear();
+  }
+  /** Number of timers currently tracked (pending). */
+  get size() {
+    return this.ids.size;
+  }
+};
+var SafeTimeout = class extends TimerRegistry {
+  /**
+   * Schedules `callback` after `delay` ms and returns the timer id.
+   *
+   * The id is removed from the registry automatically when the timeout fires,
+   * so {@link TimerRegistry.size | size} reflects only still-pending timers.
+   */
+  set(callback, delay) {
+    const id = this.schedule(() => {
+      this.ids.delete(id);
+      callback();
+    }, delay);
+    this.ids.add(id);
+    return id;
+  }
+  schedule(callback, delay) {
+    return window.setTimeout(callback, delay);
+  }
+  cancel(id) {
+    window.clearTimeout(id);
+  }
+};
+
+// src/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);
+    this.#query = repeated ? char : this.#query + char;
+    this.#timers.clear(this.#timerId);
+    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);
+    this.#timerId = 0;
+  }
+};
+function isTypeaheadKey(event) {
+  return event.key.length === 1 && event.key !== " " && !event.ctrlKey && !event.metaKey && !event.altKey && !event.isComposing;
+}
+function typeaheadLabel(element, fallbackText) {
+  const label = element.getAttribute("aria-label")?.trim();
+  if (label) return label.toLowerCase();
+  const text = fallbackText ? fallbackText() : element.textContent ?? "";
+  return text.trim().toLowerCase();
+}
+function findTypeaheadMatch(items, from, query, label = (item) => typeaheadLabel(item)) {
+  if (query === "") return -1;
+  const count = items.length;
+  for (let step = 1; step <= count; step += 1) {
+    const index = ((from + step) % count + count) % count;
+    const candidate = items[index];
+    if (candidate && label(candidate).startsWith(query)) return index;
+  }
+  return -1;
+}
+
+// src/controllers/tree_view_controller.ts
+var NESTED_INTERACTIVE = 'input, textarea, select, button, a[href], [contenteditable]:not([contenteditable="false"])';
+var TreeViewController = class extends Controller {
+  static targets = ["item", "group"];
+  static actions = ["onClick", "onKeydown", "toggle"];
+  static events = ["select", "toggle"];
+  #roving = new RovingTabindex(() => this.itemTargets);
+  #typeahead = new Typeahead();
+  #timers = new SafeTimeout();
+  #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;
+    if (!row || row !== this.#focused) return;
+    const next = event.relatedTarget;
+    if (next instanceof Node && this.element.contains(next)) return;
+    queueMicrotask(() => {
+      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);
+    this.#seedFocused();
+    this.#reconcileExpansion();
+    this.#normalizeSelection();
+    this.#normalizeTabStop();
+    this.#order = [...this.itemTargets];
+    this.#connected = true;
+  }
+  /** 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.#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.
+   */
+  itemTargetConnected() {
+    if (!this.#connected) return;
+    this.#normalizeSelection();
+    this.#normalizeTabStop();
+    this.#trackOrder();
+  }
+  /**
+   * 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");
+    }
+  }
+  /**
+   * 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.
+   */
+  itemTargetDisconnected(item) {
+    if (!this.#connected || !this.element.isConnected) return;
+    const stranded = this.#focusDiedWith(item);
+    if (stranded) this.#focused = null;
+    if (stranded || this.#roving.activeIndex === -1) {
+      const next = this.#neighborOf(item);
+      if (next) this.#roving.setActive(this.itemTargets.indexOf(next), { focus: stranded });
+    }
+    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));
+    if (pending.length === 0) {
+      this.#order = live;
+      return;
+    }
+    const merged = [...live];
+    for (const tracked of pending) {
+      merged.splice(Math.min(this.#order.indexOf(tracked), merged.length), 0, tracked);
+    }
+    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.isComposing) return;
+    const item = this.#ownerItem(event);
+    if (!item) return;
+    switch (event.key) {
+      case "ArrowDown":
+        event.preventDefault();
+        this.#moveBy(item, 1);
+        break;
+      case "ArrowUp":
+        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);
+        else this.#expandOrEnter(item);
+        break;
+      case "ArrowLeft":
+        event.preventDefault();
+        if (isRtl(this.element)) this.#expandOrEnter(item);
+        else this.#collapseOrLeave(item);
+        break;
+      case "Home":
+        event.preventDefault();
+        this.#focusEdge(0);
+        break;
+      case "End":
+        event.preventDefault();
+        this.#focusEdge(-1);
+        break;
+      case "Enter":
+      case " ":
+        event.preventDefault();
+        this.#select(item);
+        break;
+      default:
+        if (isTypeaheadKey(event)) {
+          event.preventDefault();
+          this.#typeaheadTo(item, event.key);
+        }
+        break;
+    }
+  }
+  /** Selects the clicked item (nearest to the target only). */
+  onClick(event) {
+    const item = this.#ownerItem(event);
+    if (!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.
+   */
+  #ownerItem(event) {
+    const item = event.currentTarget;
+    const target = event.target;
+    if (target.closest('[role="treeitem"]') !== item) return null;
+    const control = target.closest(NESTED_INTERACTIVE);
+    if (control && item.contains(control)) 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);
+    for (let at = index + 1; at < this.#order.length; at += 1) {
+      const candidate = this.#order[at];
+      if (candidate && visible.includes(candidate)) return candidate;
+    }
+    for (let at = index - 1; at >= 0; at -= 1) {
+      const candidate = this.#order[at];
+      if (candidate && visible.includes(candidate)) return candidate;
+    }
+    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;
+    const doc = this.element.ownerDocument;
+    const active = doc.activeElement;
+    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);
+    if (current === -1) return;
+    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);
+      return;
+    }
+    if (group.hidden) return;
+    const firstChild = Array.from(
+      group.querySelectorAll(':scope > [role="treeitem"]')
+    ).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);
+      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) {
+      if (current.getAttribute("aria-disabled") === "true") return true;
+      current = current.parentElement;
+    }
+    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) {
+    if (this.#isDisabled(item)) return;
+    for (const candidate of this.itemTargets) {
+      candidate.setAttribute("aria-selected", candidate === item ? "true" : "false");
+    }
+    this.dispatch("select", { detail: { item } });
+  }
+  /** Updates expansion, reconciles a collapsed subtree, then synchronously dispatches `toggle`. */
+  #setExpanded(item, expanded) {
+    const group = this.#childGroup(item);
+    if (!group) return;
+    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.
+   */
+  #escapeCollapsedSubtree(item, group) {
+    const active = document.activeElement;
+    if (active instanceof HTMLElement && group.contains(active)) {
+      this.#focusItem(item);
+      return;
+    }
+    const activeIndex = this.#roving.activeIndex;
+    const tabbable = activeIndex === -1 ? void 0 : 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) {
+    const index = this.itemTargets.indexOf(item);
+    if (index !== -1) {
+      this.#roving.setActive(index, { focus: true });
+      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;
+    const index = findTypeaheadMatch(
+      visible,
+      visible.indexOf(item),
+      query,
+      (candidate) => this.#label(candidate)
+    );
+    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);
+      if (!group) continue;
+      if (item.hasAttribute("aria-expanded")) {
+        group.hidden = !this.#isExpanded(item);
+      } else {
+        item.setAttribute("aria-expanded", String(!group.hidden));
+      }
+    }
+  }
+  /**
+   * 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];
+    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.
+   */
+  get #visibleItems() {
+    return this.itemTargets.filter((item) => {
+      let node = item;
+      while (node && node !== this.element) {
+        if (node.hidden) return false;
+        node = node.parentElement;
+      }
+      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 = "";
+      for (const node of Array.from(item.childNodes)) {
+        if (node.nodeType === Node.ELEMENT_NODE && node.matches('[role="group"]')) {
+          continue;
+        }
+        text += node.textContent ?? "";
+      }
+      return text;
+    });
+  }
+};
+
+export { TreeViewController };
+//# sourceMappingURL=tree_view_controller.js.map
+//# sourceMappingURL=tree_view_controller.js.map