@aceshooting/lyra-ui 1.2.0 → 2.1.0

package/dist/components/tool-select-dialog/tool-select-dialog.js

@@ -0,0 +1,350 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { html, nothing } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import { LyraElement } from '../../internal/lyra-element.js';
+import { activateOverlay } from '../../internal/overlay-manager.js';
+import { defineElement } from '../../internal/prefix.js';
+import { lockScroll } from '../../internal/scroll-lock.js';
+import { nextId, srOnly } from '../../internal/a11y.js';
+import { styles } from './tool-select-dialog.styles.js';
+import '../checkbox/checkbox.js';
+import '../switch/switch.js';
+const OTHER_CATEGORY = 'Other';
+/** Default `filter`: case-insensitive substring match against the tool's name and description. */
+function defaultFilter(tool, query) {
+    return tool.name.toLowerCase().includes(query) || (tool.description ?? '').toLowerCase().includes(query);
+}
+/**
+ * `<lyra-tool-select-dialog>` — a category-grouped, filterable, searchable
+ * tool-enablement dialog for picking which agent tools are available in a
+ * conversation.
+ *
+ * This renders its own dialog panel rather than nesting a `<lyra-dialog>` in
+ * its shadow template. Shared overlay infrastructure coordinates stacking,
+ * focus trapping, Escape/backdrop dismissal, and focus return with every
+ * other overlay in the same document.
+ *
+ * `useDefaults` is a single top-level switch: while `true`, every per-tool
+ * checkbox below renders disabled (still reflecting whatever `selected`
+ * holds — a consumer should populate that with its own default tool set
+ * whenever `useDefaults` is true) and a hint explains that turning the
+ * switch off is how to customize. Turning it off is the "customize"
+ * affordance — it's the only thing that both flips `useDefaults` to `false`
+ * *and* unlocks the per-tool checkboxes for editing, so there's exactly one
+ * control for that transition rather than a separate button duplicating it.
+ *
+ * There is no built-in footer/close button — like `<lyra-dialog>`, dismissal
+ * happens via Escape, a backdrop click, or a consumer's own `footer`-slotted
+ * action calling `close()`. This also means the search input is the very
+ * first focusable element in the panel with no special-casing needed, so
+ * it's what receives focus on open (see `updated()`).
+ *
+ * @customElement lyra-tool-select-dialog
+ * @slot footer - Optional action buttons (e.g. a "Done" button), rendered in a bottom row.
+ * Changes already apply live via `lyra-change`, so this is optional.
+ * @event lyra-change - The enabled-tool selection or the `useDefaults` toggle changed.
+ * `detail: { selected: string[], useDefaults: boolean }`.
+ * @event lyra-close - `detail: ToolSelectDialogCloseReason`. Fired exactly once per dismissal,
+ * via Escape, a backdrop click, or a `close()` call.
+ * @csspart backdrop - The full-viewport scrim behind the panel.
+ * @csspart panel - The dialog panel itself (`role="dialog"` while open).
+ * @csspart header - The wrapper around the title/subtitle.
+ * @csspart title - The dialog's heading.
+ * @csspart subtitle - The "N of M tools enabled" summary line.
+ * @csspart search-row - The wrapper around the search input.
+ * @csspart search-input - The filter text input.
+ * @csspart defaults-row - The wrapper around the use-defaults switch and its hint.
+ * @csspart defaults-toggle - The built-in `<lyra-switch>` bound to `useDefaults`.
+ * @csspart defaults-hint - The "turn off to customize" hint, shown only while `useDefaults` is true.
+ * @csspart body - The scrollable wrapper around the grouped tool list.
+ * @csspart empty - The "no tools" / "no matches" message.
+ * @csspart category - A single category's wrapper (`role="group"`).
+ * @csspart category-heading - A category's heading.
+ * @csspart category-count - The terse, `aria-hidden` tool count next to a category heading
+ * (the heading's accessible name gets the full sentence from an sr-only sibling instead).
+ * @csspart category-list - The `<ul>` of tool rows within a category.
+ * @csspart tool-row - A single tool's `<li>` row.
+ * @csspart tool-checkbox - A row's `<lyra-checkbox>`.
+ * @csspart tool-name - A row's name text (plus its `icon`, if set).
+ * @csspart tool-icon - A row's leading icon glyph, when `icon` is set.
+ * @csspart tool-description - A row's optional description text.
+ * @csspart tool-disabled-reason - A disabled row's `disabledReason` text, slotted inside
+ * `tool-checkbox` (alongside `tool-name`/`tool-description`) so it contributes to the
+ * checkbox's accessible name/description instead of going unannounced.
+ * @csspart footer - The wrapper around the `footer` slot.
+ */
+export class LyraToolSelectDialog extends LyraElement {
+    constructor() {
+        super(...arguments);
+        /** Whether the dialog is open. Set this (or call `close()`) — there is no separate `show()`/`hide()` pair. */
+        this.open = false;
+        /** The full set of tools a consumer offers, across all categories. */
+        this.tools = [];
+        /** The currently-enabled tool ids. */
+        this.selected = [];
+        /** Whether the conversation is using the default tool set (`true`) or a custom selection (`false`) — see the class doc for the exact interaction with `selected`/per-tool editing. */
+        this.useDefaults = false;
+        /** The dialog's visible heading and accessible name. */
+        this.label = 'Select tools';
+        this.searchPlaceholder = 'Search tools…';
+        /** Overrides the built-in case-insensitive name/description substring match. */
+        this.filter = null;
+        this.query = '';
+        this.hasFooterSlot = false;
+        this.titleId = nextId('tool-select-dialog-title');
+        // Stable per-category heading ids, keyed by category name -- generated
+        // once (not regenerated every render/keystroke) so a category's
+        // aria-labelledby target keeps the same id across re-renders.
+        this.categoryIds = new Map();
+        this.onFooterSlotChange = (e) => {
+            this.hasFooterSlot = e.target.assignedElements({ flatten: true }).length > 0;
+        };
+        this.onBackdropClick = () => {
+            this.overlay?.dismissBackdrop();
+        };
+        this.onSearchInput = (e) => {
+            this.query = e.target.value;
+        };
+        this.onDefaultsToggle = (e) => {
+            this.useDefaults = e.detail.checked;
+            this.emitChange();
+        };
+    }
+    static { this.styles = [LyraElement.styles, styles, srOnly]; }
+    willUpdate(changed) {
+        if (!this.hasUpdated) {
+            this.hasFooterSlot = Array.from(this.children).some((el) => el.getAttribute('slot') === 'footer');
+        }
+        if (changed.has('open')) {
+            if (this.open) {
+                this.releaseScrollLock ??= lockScroll(this.ownerDocument);
+                this.activateOverlay();
+            }
+            else {
+                this.releaseScrollLock?.();
+                this.releaseScrollLock = undefined;
+                this.overlay?.deactivate();
+                this.overlay = undefined;
+                // Otherwise a long-lived instance reopens still showing whatever
+                // search filter/collapsed-category state the previous session left
+                // behind, rather than the fresh, unfiltered list a reopen implies.
+                this.query = '';
+            }
+        }
+    }
+    // Runs after render (not willUpdate) so [part="panel"] and its contents
+    // have already landed in the DOM before the focus call below can rely on
+    // them -- mirrors lyra-dialog's/lyra-tool-result-dialog's identical
+    // ordering rationale.
+    updated(changed) {
+        if (changed.has('open') && this.open) {
+            this.overlay?.focusInitial();
+        }
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        if (this.hasUpdated && this.open) {
+            this.releaseScrollLock ??= lockScroll(this.ownerDocument);
+            this.activateOverlay();
+            queueMicrotask(() => this.overlay?.focusInitial());
+        }
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.releaseScrollLock?.();
+        this.releaseScrollLock = undefined;
+        this.overlay?.suspend();
+    }
+    activateOverlay() {
+        if (this.overlay?.isActive()) {
+            this.overlay.resume();
+            return;
+        }
+        this.overlay = activateOverlay({
+            host: this,
+            panel: () => this.shadowRoot?.querySelector('[part="panel"]') ?? null,
+            onEscape: () => this.close('escape'),
+            onBackdrop: () => this.close('backdrop'),
+        });
+    }
+    /**
+     * Close the dialog and return focus to whatever had it before the dialog
+     * opened. `reason` is forwarded as the `lyra-close` detail — built-in
+     * triggers pass `'escape'`/`'backdrop'`; a consumer's own close affordance
+     * (e.g. a footer Done button) should call this directly with its own
+     * reason string, so every dismissal path funnels through the same event
+     * instead of the consumer having to also toggle `open` itself.
+     */
+    close(reason = 'api') {
+        if (!this.open)
+            return;
+        this.open = false;
+        this.emit('lyra-close', reason);
+    }
+    emitChange() {
+        this.emit('lyra-change', {
+            selected: [...this.selected],
+            useDefaults: this.useDefaults,
+        });
+    }
+    onToolToggle(tool, e) {
+        const set = new Set(this.selected);
+        e.detail.checked ? set.add(tool.id) : set.delete(tool.id);
+        this.selected = [...set];
+        this.emitChange();
+    }
+    categoryId(category) {
+        let id = this.categoryIds.get(category);
+        if (!id) {
+            id = nextId('tool-select-dialog-category');
+            this.categoryIds.set(category, id);
+        }
+        return id;
+    }
+    /** Tools grouped by `category` (first-seen order), with an uncategorized
+     *  bucket always last, then filtered by the active search query -- a
+     *  category left with zero matches is dropped entirely rather than
+     *  rendered as an empty heading. */
+    get groups() {
+        const order = [];
+        const byCategory = new Map();
+        for (const tool of this.tools) {
+            const category = tool.category?.trim() || OTHER_CATEGORY;
+            let bucket = byCategory.get(category);
+            if (!bucket) {
+                bucket = [];
+                byCategory.set(category, bucket);
+                if (category !== OTHER_CATEGORY)
+                    order.push(category);
+            }
+            bucket.push(tool);
+        }
+        if (byCategory.has(OTHER_CATEGORY))
+            order.push(OTHER_CATEGORY);
+        const q = this.query.trim().toLowerCase();
+        const matches = q ? (tool) => (this.filter ?? defaultFilter)(tool, q) : () => true;
+        return order
+            .map((category) => ({ category, tools: byCategory.get(category).filter(matches) }))
+            .filter((group) => group.tools.length > 0);
+    }
+    renderTool(tool) {
+        const rowDisabled = Boolean(tool.disabled) || this.useDefaults;
+        return html `
+      <li part="tool-row" ?data-disabled=${rowDisabled}>
+        <lyra-checkbox
+          part="tool-checkbox"
+          value=${tool.id}
+          ?checked=${this.selected.includes(tool.id)}
+          ?disabled=${rowDisabled}
+          @lyra-change=${(e) => this.onToolToggle(tool, e)}
+        >
+          <span part="tool-name">
+            ${tool.icon ? html `<span part="tool-icon" aria-hidden="true">${tool.icon}</span>` : nothing}${tool.name}
+          </span>
+          ${tool.description ? html `<span part="tool-description">${tool.description}</span>` : nothing}
+          ${tool.disabled && tool.disabledReason
+            ? html `<span part="tool-disabled-reason">${tool.disabledReason}</span>`
+            : nothing}
+        </lyra-checkbox>
+      </li>
+    `;
+    }
+    renderCategory(group) {
+        const headingId = this.categoryId(group.category);
+        return html `
+      <div part="category" role="group" aria-labelledby=${headingId}>
+        <h3 part="category-heading" id=${headingId}>
+          ${group.category}<span part="category-count" aria-hidden="true">${group.tools.length}</span
+          ><span class="sr-only">${group.tools.length} tool${group.tools.length === 1 ? '' : 's'}</span>
+        </h3>
+        <ul part="category-list">
+          ${group.tools.map((tool) => this.renderTool(tool))}
+        </ul>
+      </div>
+    `;
+    }
+    render() {
+        const groups = this.groups;
+        const hasTools = this.tools.length > 0;
+        return html `
+      <div part="backdrop" @click=${this.onBackdropClick}></div>
+      <div
+        part="panel"
+        role=${this.open ? 'dialog' : nothing}
+        aria-modal=${this.open ? 'true' : nothing}
+        aria-labelledby=${this.titleId}
+        tabindex="-1"
+      >
+        <div part="header">
+          <h2 part="title" id=${this.titleId}>${this.label}</h2>
+          <p part="subtitle" ?hidden=${!hasTools}>${this.selected.length} of ${this.tools.length} tools enabled</p>
+        </div>
+        <div part="search-row">
+          <input
+            part="search-input"
+            type="search"
+            .value=${this.query}
+            placeholder=${this.searchPlaceholder}
+            aria-label=${this.searchPlaceholder}
+            @input=${this.onSearchInput}
+          />
+        </div>
+        <div part="defaults-row">
+          <lyra-switch
+            part="defaults-toggle"
+            ?checked=${this.useDefaults}
+            @lyra-change=${this.onDefaultsToggle}
+          >
+            Use default tools
+          </lyra-switch>
+          ${this.useDefaults
+            ? html `<p part="defaults-hint">Turn off to choose individual tools.</p>`
+            : nothing}
+        </div>
+        <div part="body">
+          ${groups.length === 0
+            ? html `<p part="empty">
+                ${hasTools ? html `No tools match "${this.query}".` : 'No tools available.'}
+              </p>`
+            : groups.map((group) => this.renderCategory(group))}
+        </div>
+        <div part="footer" ?hidden=${!this.hasFooterSlot}>
+          <slot name="footer" @slotchange=${this.onFooterSlotChange}></slot>
+        </div>
+      </div>
+    `;
+    }
+}
+__decorate([
+    property({ type: Boolean, reflect: true })
+], LyraToolSelectDialog.prototype, "open", void 0);
+__decorate([
+    property({ attribute: false })
+], LyraToolSelectDialog.prototype, "tools", void 0);
+__decorate([
+    property({ attribute: false })
+], LyraToolSelectDialog.prototype, "selected", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true, attribute: 'use-defaults' })
+], LyraToolSelectDialog.prototype, "useDefaults", void 0);
+__decorate([
+    property()
+], LyraToolSelectDialog.prototype, "label", void 0);
+__decorate([
+    property({ attribute: 'search-placeholder' })
+], LyraToolSelectDialog.prototype, "searchPlaceholder", void 0);
+__decorate([
+    property({ attribute: false })
+], LyraToolSelectDialog.prototype, "filter", void 0);
+__decorate([
+    state()
+], LyraToolSelectDialog.prototype, "query", void 0);
+__decorate([
+    state()
+], LyraToolSelectDialog.prototype, "hasFooterSlot", void 0);
+defineElement('tool-select-dialog', LyraToolSelectDialog);

package/dist/components/tool-select-dialog/tool-select-dialog.styles.d.ts

@@ -0,0 +1 @@
+export declare const styles: import("lit").CSSResult;

package/dist/components/tool-select-dialog/tool-select-dialog.styles.js

@@ -0,0 +1,191 @@
+import { css } from 'lit';
+export const styles = css `
+  :host {
+    /* Backdrop scrim color -- component-specific so a host can retheme it
+       without a raw literal leaking into the public API (no shared
+       --wa-*-overlay token exists in the design system to resolve through,
+       same rationale as lyra-dialog's --lyra-dialog-overlay-color and
+       lyra-tool-result-dialog's --lyra-tool-result-dialog-overlay-color). */
+    --lyra-tool-select-dialog-overlay-color: rgb(0 0 0 / 0.5);
+    display: none;
+    position: fixed;
+    inset: 0;
+    z-index: var(--lyra-overlay-stack-index, 1000);
+    align-items: center;
+    justify-content: center;
+    padding: var(--lyra-space-l);
+  }
+  :host([open]) {
+    display: flex;
+  }
+  [part='backdrop'] {
+    position: absolute;
+    inset: 0;
+    background: var(--lyra-tool-select-dialog-overlay-color);
+  }
+  [part='panel'] {
+    position: relative;
+    display: flex;
+    flex-direction: column;
+    inline-size: min(30rem, 100%);
+    block-size: min(38rem, 100%);
+    background: var(--lyra-color-surface);
+    border: 1px solid var(--lyra-color-border);
+    border-radius: var(--lyra-radius);
+    box-shadow: var(--lyra-shadow);
+    overflow: hidden;
+  }
+  [part='header'] {
+    padding: var(--lyra-space-l) var(--lyra-space-l) 0;
+  }
+  [part='title'] {
+    margin: 0;
+    font-size: 1rem;
+    font-weight: 600;
+  }
+  [part='subtitle'] {
+    margin: var(--lyra-space-xs) 0 0;
+    font-size: 0.8125rem;
+    color: var(--lyra-color-text-quiet);
+  }
+  [part='subtitle'][hidden] {
+    display: none;
+  }
+
+  [part='search-row'] {
+    padding: var(--lyra-space-m) var(--lyra-space-l) 0;
+  }
+  [part='search-input'] {
+    inline-size: 100%;
+    box-sizing: border-box;
+    padding: var(--lyra-space-s) var(--lyra-space-m);
+    border: 1px solid var(--lyra-color-border);
+    border-radius: var(--lyra-radius);
+    background: var(--lyra-color-surface);
+    color: inherit;
+    font: inherit;
+  }
+  [part='search-input']:focus-visible {
+    outline: var(--lyra-focus-ring-width) solid var(--lyra-focus-ring-color);
+    outline-offset: var(--lyra-focus-ring-offset);
+  }
+
+  [part='defaults-row'] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--lyra-space-xs);
+    padding: var(--lyra-space-m) var(--lyra-space-l);
+    border-block-end: 1px solid var(--lyra-color-border);
+  }
+  [part='defaults-hint'] {
+    margin: 0;
+    /* Lines the hint up under the switch's label text, not its track --
+       lyra-switch's own [part="base"] uses a fixed 2.25rem track
+       inline-size plus a --lyra-space-s gap before its label (both defined
+       in switch.styles.ts, not exposed as tokens), so this indent is
+       coupled to that fixed geometry rather than derived from an unrelated
+       component's token. */
+    padding-inline-start: calc(2.25rem + var(--lyra-space-s));
+    font-size: 0.75rem;
+    color: var(--lyra-color-text-quiet);
+  }
+
+  [part='body'] {
+    flex: 1 1 auto;
+    min-block-size: 0;
+    overflow: auto;
+    padding: var(--lyra-space-m) var(--lyra-space-l) var(--lyra-space-l);
+  }
+  [part='empty'] {
+    margin: 0;
+    padding: var(--lyra-space-l) 0;
+    color: var(--lyra-color-text-quiet);
+    font-size: 0.875rem;
+    text-align: center;
+  }
+
+  [part='category'] {
+    margin-block-end: var(--lyra-space-l);
+  }
+  [part='category']:last-child {
+    margin-block-end: 0;
+  }
+  [part='category-heading'] {
+    display: flex;
+    align-items: baseline;
+    gap: var(--lyra-space-xs);
+    margin: 0 0 var(--lyra-space-s);
+    font-size: 0.75rem;
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    color: var(--lyra-color-text-quiet);
+  }
+  [part='category-count'] {
+    font-weight: 400;
+    text-transform: none;
+    letter-spacing: normal;
+  }
+  [part='category-list'] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--lyra-space-s);
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  [part='tool-row'] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--lyra-space-xs);
+  }
+  [part='tool-row'][data-disabled] [part='tool-checkbox'] {
+    opacity: var(--lyra-opacity-disabled);
+  }
+  [part='tool-checkbox'] {
+    align-items: flex-start;
+  }
+  [part='tool-checkbox']::part(label) {
+    display: flex;
+    flex-direction: column;
+    gap: 0.125rem;
+  }
+  [part='tool-name'] {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--lyra-space-xs);
+    font-size: 0.875rem;
+    font-weight: 600;
+    color: var(--lyra-color-text);
+  }
+  [part='tool-icon'] {
+    line-height: 1;
+  }
+  [part='tool-description'] {
+    display: block;
+    font-size: 0.8125rem;
+    color: var(--lyra-color-text-quiet);
+  }
+  [part='tool-disabled-reason'] {
+    /* Slotted into lyra-checkbox's default slot alongside tool-name/
+       tool-description (see tool-select-dialog.ts's renderTool()), so it
+       inherits its indent for free from ::part(label)'s column layout
+       above instead of needing its own guessed padding. */
+    display: block;
+    font-size: 0.75rem;
+    color: var(--lyra-color-warning);
+  }
+
+  [part='footer'] {
+    display: flex;
+    align-items: center;
+    justify-content: flex-end;
+    gap: var(--lyra-space-s);
+    padding: var(--lyra-space-m) var(--lyra-space-l);
+    border-block-start: 1px solid var(--lyra-color-border);
+  }
+  [part='footer'][hidden] {
+    display: none;
+  }
+`;

package/dist/components/tree/tree-node.d.ts

@@ -14,8 +14,11 @@ import type { TreeItem } from './tree.js';
  *
  * @customElement lyra-tree-node
  * @event lyra-node-toggle - `detail: { id, expanded }`, fired when this node is expanded or collapsed (via `expand()`/`collapse()`, the toggle button, or ArrowRight/ArrowLeft).
- * @event lyra-node-select - `detail: { id }`, fired when this node's primary action is activated (via `select()`, clicking its label, or Enter/Space).
- * @csspart row, toggle, label, badge
+ * @event lyra-node-select - `detail: { id }`, fired when this node's primary action is activated (via `select()`, clicking anywhere in its row, or Enter/Space).
+ * @csspart row - The tree row.
+ * @csspart toggle - The expand/collapse button.
+ * @csspart label - The node label.
+ * @csspart badge - The optional node badge.
  */
 export declare class LyraTreeNode extends LyraElement {
     static styles: import("lit").CSSResultGroup[];
@@ -32,7 +35,16 @@ export declare class LyraTreeNode extends LyraElement {
     expand(): void;
     /** Collapse this node (no-op if already collapsed or a leaf). */
     collapse(): void;
-    /** Fire this item's primary "select" action (Enter/Space, or clicking the label). */
+    /**
+     * Fire this item's primary "select" action (Enter/Space, or clicking
+     * anywhere in the row). Emits *before* calling `.focus()`: `<lyra-tree>`'s
+     * `onNodeActivate` listener for `lyra-node-select` runs synchronously
+     * (native `dispatchEvent` is sync) and updates `activeId`, which pushes
+     * `tabIndex = 0` down onto this node via its own render -- calling
+     * `.focus()` after that emit, rather than before, means real DOM focus
+     * lands correctly the very first time a previously-inactive node is
+     * clicked, not one render late.
+     */
     select(): void;
     /** See `cascadeUpdateComplete` and the matching override on `<lyra-tree>`. */
     protected getUpdateComplete(): Promise<boolean>;

package/dist/components/tree/tree-node.js

@@ -8,7 +8,7 @@ import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { repeat } from 'lit/directives/repeat.js';
 import { LyraElement } from '../../internal/lyra-element.js';
-import { defineElement } from '../../internal/prefix.js';
+import { defineElement, tag } from '../../internal/prefix.js';
 import { chevronIcon } from '../../internal/icons.js';
 import { css } from 'lit';
 import { cascadeUpdateComplete } from './update-cascade.js';
@@ -89,8 +89,11 @@ const styles = css `
  *
  * @customElement lyra-tree-node
  * @event lyra-node-toggle - `detail: { id, expanded }`, fired when this node is expanded or collapsed (via `expand()`/`collapse()`, the toggle button, or ArrowRight/ArrowLeft).
- * @event lyra-node-select - `detail: { id }`, fired when this node's primary action is activated (via `select()`, clicking its label, or Enter/Space).
- * @csspart row, toggle, label, badge
+ * @event lyra-node-select - `detail: { id }`, fired when this node's primary action is activated (via `select()`, clicking anywhere in its row, or Enter/Space).
+ * @csspart row - The tree row.
+ * @csspart toggle - The expand/collapse button.
+ * @csspart label - The node label.
+ * @csspart badge - The optional node badge.
  */
 export class LyraTreeNode extends LyraElement {
     constructor() {
@@ -145,19 +148,29 @@ export class LyraTreeNode extends LyraElement {
         this.expanded = false;
         this.emit('lyra-node-toggle', { id: this.item.id, expanded: false });
     }
-    /** Fire this item's primary "select" action (Enter/Space, or clicking the label). */
+    /**
+     * Fire this item's primary "select" action (Enter/Space, or clicking
+     * anywhere in the row). Emits *before* calling `.focus()`: `<lyra-tree>`'s
+     * `onNodeActivate` listener for `lyra-node-select` runs synchronously
+     * (native `dispatchEvent` is sync) and updates `activeId`, which pushes
+     * `tabIndex = 0` down onto this node via its own render -- calling
+     * `.focus()` after that emit, rather than before, means real DOM focus
+     * lands correctly the very first time a previously-inactive node is
+     * clicked, not one render late.
+     */
     select() {
         this.emit('lyra-node-select', { id: this.item.id });
+        this.focus();
     }
     /** See `cascadeUpdateComplete` and the matching override on `<lyra-tree>`. */
     async getUpdateComplete() {
         const result = await super.getUpdateComplete();
-        await cascadeUpdateComplete(this.shadowRoot?.querySelectorAll('lyra-tree-node') ?? []);
+        await cascadeUpdateComplete([...(this.shadowRoot?.querySelectorAll(tag('tree-node')) ?? [])]);
         return result;
     }
     render() {
         return html `
-      <div part="row" style=${`--lyra-tree-depth:${this.depth}`}>
+      <div part="row" style=${`--lyra-tree-depth:${this.depth}`} @click=${() => this.select()}>
         <button
           part="toggle"
           type="button"
@@ -172,7 +185,7 @@ export class LyraTreeNode extends LyraElement {
         >
           ${this.hasChildren ? chevronIcon() : nothing}
         </button>
-        <span part="label" @click=${() => this.select()}>${this.item.label}</span>
+        <span part="label">${this.item.label}</span>
         ${this.item.badge != null ? html `<span part="badge">${this.item.badge}</span>` : nothing}
       </div>
       ${this.expanded && this.hasChildren