stimeo-ui 0.2.0 → 0.2.1

data/dist/controllers/tree_view_controller.js

@@ -0,0 +1,275 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/tree_view_controller.ts
+
+// src/utils/roving_tabindex.ts
+var RovingTabindex = class {
+  /** Returns the current ordered item elements; called on every operation. */
+  #getItems;
+  /**
+   * @param getItems - Returns the current ordered item elements. Called on every
+   *   operation so the live target list is always used.
+   */
+  constructor(getItems) {
+    this.#getItems = getItems;
+  }
+  /** Index of the currently tabbable item (`tabindex="0"`), or `-1` if none. */
+  get activeIndex() {
+    return this.#getItems().findIndex((item) => item.tabIndex === 0);
+  }
+  /**
+   * Makes exactly the item at `index` tabbable (`tabindex="0"`) and removes every
+   * other item from the Tab sequence (`tabindex="-1"`). An out-of-range `index`
+   * (e.g. `-1`) leaves all items at `-1`, which a controller can use to express
+   * "nothing is currently tabbable".
+   *
+   * @param index - Position of the item to make tabbable.
+   * @param options - Pass `{ focus: true }` to also move DOM focus to that item.
+   */
+  setActive(index, { focus = false } = {}) {
+    const items = this.#getItems();
+    items.forEach((item, i) => {
+      item.tabIndex = i === index ? 0 : -1;
+    });
+    if (focus) items[index]?.focus();
+  }
+};
+
+// src/utils/safe_timeout.ts
+var TimerRegistry = class {
+  /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
+  ids = /* @__PURE__ */ new Set();
+  /**
+   * Cancels a single tracked timer.
+   *
+   * No-ops if the id is unknown (already cleared, fired, or never owned by this
+   * registry), so callers can clear defensively without guarding.
+   */
+  clear(id) {
+    if (this.ids.delete(id)) {
+      this.cancel(id);
+    }
+  }
+  /**
+   * Cancels every tracked timer. Call this from a controller's `disconnect()`
+   * to guarantee no timer outlives the element.
+   */
+  clearAll() {
+    for (const id of this.ids) {
+      this.cancel(id);
+    }
+    this.ids.clear();
+  }
+  /** Number of timers currently tracked (pending). */
+  get size() {
+    return this.ids.size;
+  }
+};
+var SafeTimeout = class extends TimerRegistry {
+  /**
+   * Schedules `callback` after `delay` ms and returns the timer id.
+   *
+   * The id is removed from the registry automatically when the timeout fires,
+   * so {@link TimerRegistry.size | size} reflects only still-pending timers.
+   */
+  set(callback, delay) {
+    const id = this.schedule(() => {
+      this.ids.delete(id);
+      callback();
+    }, delay);
+    this.ids.add(id);
+    return id;
+  }
+  schedule(callback, delay) {
+    return window.setTimeout(callback, delay);
+  }
+  cancel(id) {
+    window.clearTimeout(id);
+  }
+};
+
+// src/controllers/tree_view_controller.ts
+var TYPEAHEAD_TIMEOUT = 500;
+var TreeViewController = class extends Controller {
+  static targets = ["item", "group"];
+  static actions = ["onClick", "onKeydown"];
+  static events = ["select", "toggle"];
+  #roving = new RovingTabindex(() => this.itemTargets);
+  #typeahead = "";
+  #typeaheadTimer = 0;
+  #timers = new SafeTimeout();
+  /** Establishes the single tab stop (keeps an existing one, else the first). */
+  connect() {
+    const active = this.#roving.activeIndex;
+    this.#roving.setActive(active === -1 ? 0 : active);
+  }
+  /** Clears the pending typeahead-reset timer. */
+  disconnect() {
+    this.#timers.clearAll();
+  }
+  /**
+   * 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.
+   */
+  onKeydown(event) {
+    const item = event.currentTarget;
+    if (event.target.closest('[role="treeitem"]') !== item) return;
+    switch (event.key) {
+      case "ArrowDown":
+        event.preventDefault();
+        this.#moveBy(item, 1);
+        break;
+      case "ArrowUp":
+        event.preventDefault();
+        this.#moveBy(item, -1);
+        break;
+      case "ArrowRight":
+        event.preventDefault();
+        this.#expandOrEnter(item);
+        break;
+      case "ArrowLeft":
+        event.preventDefault();
+        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 (this.#isPrintable(event)) {
+          event.preventDefault();
+          this.#typeaheadTo(item, event.key);
+        }
+        break;
+    }
+  }
+  /** Selects the clicked item (nearest to the target only). */
+  onClick(event) {
+    const item = event.currentTarget;
+    if (event.target.closest('[role="treeitem"]') !== item) return;
+    this.#focusItem(item);
+    this.#select(item);
+  }
+  /** 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);
+    const next = visible[current + delta];
+    if (next) this.#focusItem(next);
+  }
+  /** `ArrowRight`: expand a collapsed parent, else step into the first child. */
+  #expandOrEnter(item) {
+    const group = this.#childGroup(item);
+    if (!group) return;
+    if (this.#isExpanded(item)) {
+      const firstChild = group.querySelector(':scope > [role="treeitem"]');
+      if (firstChild) this.#focusItem(firstChild);
+    } else {
+      this.#setExpanded(item, true);
+    }
+  }
+  /** `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);
+  }
+  /** Applies single selection and dispatches `select`. */
+  #select(item) {
+    for (const candidate of this.itemTargets) {
+      candidate.setAttribute("aria-selected", candidate === item ? "true" : "false");
+    }
+    this.dispatch("select", { detail: { item } });
+  }
+  /** Toggles `aria-expanded` + the child group's `hidden`, dispatching `toggle`. */
+  #setExpanded(item, expanded) {
+    const group = this.#childGroup(item);
+    if (!group) return;
+    item.setAttribute("aria-expanded", String(expanded));
+    group.hidden = !expanded;
+    this.dispatch("toggle", { detail: { item, expanded } });
+  }
+  /** 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 });
+  }
+  /** Advances the typeahead buffer and focuses the next matching visible item. */
+  #typeaheadTo(item, char) {
+    this.#timers.clear(this.#typeaheadTimer);
+    this.#typeahead += char.toLowerCase();
+    this.#typeaheadTimer = this.#timers.set(() => {
+      this.#typeahead = "";
+    }, TYPEAHEAD_TIMEOUT);
+    const visible = this.#visibleItems;
+    const start = visible.indexOf(item);
+    for (let offset = 1; offset <= visible.length; offset += 1) {
+      const candidate = visible[(start + offset) % visible.length];
+      if (candidate && this.#label(candidate).startsWith(this.#typeahead)) {
+        this.#focusItem(candidate);
+        return;
+      }
+    }
+  }
+  /** The visible items: those with no collapsed (`hidden`) ancestor group. */
+  get #visibleItems() {
+    return this.itemTargets.filter((item) => {
+      let node = item.parentElement;
+      while (node && node !== this.element) {
+        if (node.matches('[role="group"]') && 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 own label text (excluding any nested child group), lowercased. */
+  #label(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.trim().toLowerCase();
+  }
+  /** Whether `event.key` is a single printable character (no modifier chord). */
+  #isPrintable(event) {
+    return event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey;
+  }
+};
+
+export { TreeViewController };
+//# sourceMappingURL=tree_view_controller.js.map
+//# sourceMappingURL=tree_view_controller.js.map