@aceshooting/lyra-ui 1.2.0 → 2.0.0

package/dist/components/tool-result-view/registry.js

@@ -0,0 +1,84 @@
+/**
+ * A type-keyed dispatch registry for tool-result renderers -- a tiny plugin
+ * system so a host app can teach `<lyra-tool-result-view>` how to draw the
+ * result of e.g. a `get_weather` or `run_query` tool call without this
+ * library knowing anything about either. Dispatch is a two-step lookup
+ * (elipa-inspired): an exact match on the tool's name first, falling back to
+ * a facade/shape-based `matches(payload)` scan when no name matches --
+ * useful when several tool names share one result shape (e.g. every
+ * "*_search" tool returning `{ results: [...] }`) or when the caller doesn't
+ * reliably know the tool name at all.
+ */
+/** The module-level registry every `<lyra-tool-result-view>` dispatches against by default (see its `registry` prop to opt a given instance into a different one instead). */
+const defaultRegistry = new Map();
+/**
+ * Resolved-`load()` cache, keyed by *definition object identity* rather than
+ * by tool name. Keying by name would let two different registries that
+ * happen to reuse the same tool-name string (a default-registry entry and an
+ * unrelated custom-registry entry, say) silently share one cached module --
+ * identity keying makes that impossible while still giving every distinct
+ * definition the "call `load()` at most once" behavior a repeatedly-dispatched
+ * lazy renderer needs.
+ */
+let loadCache = new WeakMap();
+/** Registers (or overwrites) the renderer for `name` in the default registry. */
+export function registerToolRenderer(name, def) {
+    defaultRegistry.set(name, def);
+}
+/** The module-level default registry `registerToolRenderer()` writes to and `<lyra-tool-result-view>` reads from when no `registry` prop is set. */
+export function getDefaultToolRendererRegistry() {
+    return defaultRegistry;
+}
+/**
+ * Finds the renderer definition for `toolName`/`payload` in `registry`
+ * (the default registry when omitted), in dispatch order:
+ *   1. An exact `toolName` key match.
+ *   2. Failing that, the first entry (in registration order -- a `Map`
+ *      already iterates that way) whose `matches(payload)` returns `true`.
+ *   3. `undefined` -- the caller falls back to `<lyra-json-viewer>`.
+ */
+export function findToolRenderer(toolName, payload, registry = defaultRegistry) {
+    const exact = registry.get(toolName);
+    if (exact)
+        return exact;
+    for (const def of registry.values()) {
+        if (def.matches?.(payload))
+            return def;
+    }
+    return undefined;
+}
+function isModuleWrapper(mod) {
+    return 'default' in mod && typeof mod.default === 'object' && mod.default !== null;
+}
+/**
+ * Resolves `def` to a definition guaranteed to carry a real `render` --
+ * awaiting and unwrapping `def.load()` (caching the result so a lazy
+ * definition's `load()` runs at most once no matter how many times it's
+ * dispatched to) when `def.load` is present, or returning `def` as-is
+ * otherwise. A rejected `load()` is *not* cached -- the definition stays
+ * registered, so a later resolution attempt (e.g. after a transient network
+ * failure) gets a fresh `load()` call rather than being stuck replaying one
+ * failed promise forever.
+ */
+export function loadToolRenderer(def) {
+    if (!def.load)
+        return Promise.resolve(def);
+    const cached = loadCache.get(def);
+    if (cached)
+        return cached;
+    const promise = def.load().then((mod) => (isModuleWrapper(mod) ? mod.default : mod));
+    loadCache.set(def, promise);
+    promise.catch(() => loadCache.delete(def));
+    return promise;
+}
+/**
+ * Test-only utility: empties the default registry and its `load()` cache so
+ * one test's `registerToolRenderer()` calls can't leak into the next. Mirrors
+ * the fact that this module (like `toaster.ts`'s per-placement region map) is
+ * deliberately singleton, module-level state -- there is no per-instance
+ * registry to construct fresh in a test's own `fixture()` call instead.
+ */
+export function clearToolRenderers() {
+    defaultRegistry.clear();
+    loadCache = new WeakMap();
+}

package/dist/components/tool-result-view/tool-result-view.d.ts

@@ -0,0 +1,55 @@
+import { type TemplateResult, type PropertyValues } from 'lit';
+import { LyraElement } from '../../internal/lyra-element.js';
+import { type ToolRendererRegistry } from './registry.js';
+import '../skeleton/skeleton.js';
+import '../json-viewer/json-viewer.js';
+/**
+ * `<lyra-tool-result-view>` — renders a tool call's result via whichever
+ * custom renderer a host app has registered for it (see `registerToolRenderer()`
+ * in `registry.ts`), falling back to `<lyra-json-viewer>` whenever no
+ * renderer matches, a renderer's optional `load()` rejects, or its `render()`
+ * throws. This component owns none of the actual visual weight of a
+ * populated tool result — that's entirely whatever the registered renderer
+ * returns; this is just the dispatch + fallback + loading-state shell.
+ *
+ * Dispatch runs against `registry` when set, otherwise against the
+ * module-level default registry `registerToolRenderer()` writes to — see
+ * `findToolRenderer()`'s two-step (exact name, then shape-based `matches()`)
+ * lookup order for the full rule.
+ *
+ * `fallback` only implements `"json"` today (an unconditional
+ * `<lyra-json-viewer>`) but is still accepted/reflected as an attribute so a
+ * consumer's markup that already sets `fallback="…"` for some future value
+ * doesn't need to change again once more fallback kinds land.
+ *
+ * @customElement lyra-tool-result-view
+ * @event lyra-render-error - `detail: { toolName, error }` — fired immediately
+ * before falling back to `<lyra-json-viewer>`, whether because no renderer
+ * matched, a renderer's `load()` rejected, or its `render()` threw.
+ * @csspart base - The root wrapper around the resolved renderer's output (or the loading/fallback view).
+ */
+export declare class LyraToolResultView extends LyraElement {
+    static styles: import("lit").CSSResultGroup[];
+    /** Custom registry to dispatch against instead of the module-level default one (see `registry.ts`). */
+    registry?: ToolRendererRegistry;
+    /** The tool's name — the primary dispatch key (see `findToolRenderer()`). */
+    toolName: string;
+    /** The tool call's result payload, handed to the matched renderer's `render()` (and to `matches()` for shape-based dispatch, and to the `<lyra-json-viewer>` fallback). */
+    result: unknown;
+    /** The tool call's original arguments, if available — handed to the matched renderer's `render()` alongside `result`. */
+    args: unknown;
+    /** Forward-compatible fallback-kind selector — see the class doc; only `"json"` is implemented today. */
+    fallback: string;
+    private renderState;
+    private generation;
+    protected willUpdate(changed: PropertyValues): void;
+    private resolve;
+    private renderWith;
+    private fail;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lyra-tool-result-view': LyraToolResultView;
+    }
+}

package/dist/components/tool-result-view/tool-result-view.js

@@ -0,0 +1,138 @@
+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 } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import { LyraElement } from '../../internal/lyra-element.js';
+import { defineElement } from '../../internal/prefix.js';
+import { findToolRenderer, getDefaultToolRendererRegistry, loadToolRenderer, } from './registry.js';
+import { styles } from './tool-result-view.styles.js';
+import '../skeleton/skeleton.js';
+import '../json-viewer/json-viewer.js';
+const FALLBACK_STATE = { kind: 'fallback' };
+/**
+ * `<lyra-tool-result-view>` — renders a tool call's result via whichever
+ * custom renderer a host app has registered for it (see `registerToolRenderer()`
+ * in `registry.ts`), falling back to `<lyra-json-viewer>` whenever no
+ * renderer matches, a renderer's optional `load()` rejects, or its `render()`
+ * throws. This component owns none of the actual visual weight of a
+ * populated tool result — that's entirely whatever the registered renderer
+ * returns; this is just the dispatch + fallback + loading-state shell.
+ *
+ * Dispatch runs against `registry` when set, otherwise against the
+ * module-level default registry `registerToolRenderer()` writes to — see
+ * `findToolRenderer()`'s two-step (exact name, then shape-based `matches()`)
+ * lookup order for the full rule.
+ *
+ * `fallback` only implements `"json"` today (an unconditional
+ * `<lyra-json-viewer>`) but is still accepted/reflected as an attribute so a
+ * consumer's markup that already sets `fallback="…"` for some future value
+ * doesn't need to change again once more fallback kinds land.
+ *
+ * @customElement lyra-tool-result-view
+ * @event lyra-render-error - `detail: { toolName, error }` — fired immediately
+ * before falling back to `<lyra-json-viewer>`, whether because no renderer
+ * matched, a renderer's `load()` rejected, or its `render()` threw.
+ * @csspart base - The root wrapper around the resolved renderer's output (or the loading/fallback view).
+ */
+export class LyraToolResultView extends LyraElement {
+    constructor() {
+        super(...arguments);
+        /** The tool's name — the primary dispatch key (see `findToolRenderer()`). */
+        this.toolName = '';
+        /** Forward-compatible fallback-kind selector — see the class doc; only `"json"` is implemented today. */
+        this.fallback = 'json';
+        this.renderState = FALLBACK_STATE;
+        // Bumped on every resolve() call so a stale in-flight load() (superseded by
+        // a newer toolName/result/args/registry before it settles) can detect it's
+        // no longer current and skip writing its result over a more recent one.
+        this.generation = 0;
+    }
+    static { this.styles = [LyraElement.styles, styles]; }
+    willUpdate(changed) {
+        if (!this.hasUpdated ||
+            changed.has('toolName') ||
+            changed.has('result') ||
+            changed.has('args') ||
+            changed.has('registry')) {
+            void this.resolve();
+        }
+    }
+    async resolve() {
+        const generation = ++this.generation;
+        const registry = this.registry ?? getDefaultToolRendererRegistry();
+        const def = findToolRenderer(this.toolName, this.result, registry);
+        if (!def) {
+            this.fail(new Error(`<lyra-tool-result-view>: no renderer registered for tool "${this.toolName}"`));
+            return;
+        }
+        if (def.load) {
+            this.renderState = { kind: 'loading' };
+            let resolved;
+            try {
+                resolved = await loadToolRenderer(def);
+            }
+            catch (error) {
+                if (generation !== this.generation)
+                    return;
+                this.fail(error);
+                return;
+            }
+            if (generation !== this.generation)
+                return;
+            this.renderWith(resolved);
+            return;
+        }
+        this.renderWith(def);
+    }
+    renderWith(def) {
+        if (!def.render) {
+            this.fail(new Error(`<lyra-tool-result-view>: renderer for tool "${this.toolName}" has no render()`));
+            return;
+        }
+        try {
+            this.renderState = { kind: 'rendered', template: def.render(this.result, this.args) };
+        }
+        catch (error) {
+            this.fail(error);
+        }
+    }
+    fail(error) {
+        this.emit('lyra-render-error', { toolName: this.toolName, error });
+        this.renderState = FALLBACK_STATE;
+    }
+    render() {
+        const state = this.renderState;
+        return html `
+      <div part="base">
+        ${state.kind === 'loading'
+            ? html `<lyra-skeleton variant="rect" height="4rem"></lyra-skeleton>`
+            : state.kind === 'rendered'
+                ? state.template
+                : html `<lyra-json-viewer .data=${this.result}></lyra-json-viewer>`}
+      </div>
+    `;
+    }
+}
+__decorate([
+    property({ attribute: false })
+], LyraToolResultView.prototype, "registry", void 0);
+__decorate([
+    property({ attribute: 'tool-name' })
+], LyraToolResultView.prototype, "toolName", void 0);
+__decorate([
+    property({ attribute: false })
+], LyraToolResultView.prototype, "result", void 0);
+__decorate([
+    property({ attribute: false })
+], LyraToolResultView.prototype, "args", void 0);
+__decorate([
+    property({ reflect: true })
+], LyraToolResultView.prototype, "fallback", void 0);
+__decorate([
+    state()
+], LyraToolResultView.prototype, "renderState", void 0);
+defineElement('tool-result-view', LyraToolResultView);

package/dist/components/tool-result-view/tool-result-view.styles.d.ts

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

package/dist/components/tool-result-view/tool-result-view.styles.js

@@ -0,0 +1,13 @@
+import { css } from 'lit';
+// Deliberately minimal -- most visual weight comes from whatever the
+// registered renderer's own template contributes; this wrapper only needs to
+// not collapse to a zero-height inline box while a renderer/skeleton/
+// json-viewer child lays itself out.
+export const styles = css `
+  :host {
+    display: block;
+  }
+  [part='base'] {
+    display: block;
+  }
+`;

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

@@ -0,0 +1,151 @@
+import { type TemplateResult, type PropertyValues } from 'lit';
+import { LyraElement } from '../../internal/lyra-element.js';
+import '../checkbox/checkbox.js';
+import '../switch/switch.js';
+/** One selectable agent tool. `category` groups the row; tools with no
+ *  `category` (or an empty one) fall into the trailing "Other" bucket. */
+export interface ToolSelectDialogTool {
+    id: string;
+    name: string;
+    description?: string;
+    category?: string;
+    /** Literal icon hint (e.g. an emoji), rendered next to `name` -- same
+     *  "opaque string, not a registry lookup" convention as `<lyra-tool-call-chip>`'s `icon`. */
+    icon?: string;
+    /** Individually gates this tool regardless of `useDefaults`/`selected` -- e.g. a tool that
+     *  requires admin approval before it can ever be enabled. */
+    disabled?: boolean;
+    /** Supporting text shown under a `disabled` row (e.g. "requires admin approval"). Ignored when `disabled` is falsy. */
+    disabledReason?: string;
+}
+/** Predicate deciding whether `tool` matches a (already-trimmed, already-lowercased) `query`.
+ *  Mirrors `<lyra-combobox>`'s `OptionFilter` convention -- override `filter` to replace the
+ *  built-in case-insensitive name/description substring match entirely. */
+export type ToolSelectFilter = (tool: ToolSelectDialogTool, query: string) => boolean;
+export interface ToolSelectionChangeDetail {
+    selected: string[];
+    useDefaults: boolean;
+}
+/**
+ * Reason the dialog was dismissed, forwarded as the `lyra-close` event detail
+ * -- mirrors `<lyra-dialog>`'s own `DialogCloseReason` shape. `'escape'`/
+ * `'backdrop'` come from the dialog's own built-in dismiss triggers; any
+ * other string is whatever a caller passes to `close()` directly (e.g. a
+ * consumer's own footer Done button).
+ */
+export type ToolSelectDialogCloseReason = 'escape' | 'backdrop' | 'api' | string;
+/**
+ * `<lyra-tool-select-dialog>` — a category-grouped, filterable, searchable
+ * tool-enablement dialog for picking which agent tools are available in a
+ * conversation.
+ *
+ * This is its own standalone overlay implementation (`role="dialog"`,
+ * focus-trapped, Escape/backdrop-dismissible, scroll-locking) rather than
+ * nesting a `<lyra-dialog>` in its shadow template — see `<lyra-dialog>`'s
+ * own header comment for why a new overlay component in this library
+ * duplicates that pattern locally instead of composing the previous one.
+ *
+ * `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 visible tool count next to a category heading.
+ * @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.
+ * @csspart footer - The wrapper around the `footer` slot.
+ */
+export declare class LyraToolSelectDialog extends LyraElement {
+    static styles: import("lit").CSSResultGroup[];
+    /** Whether the dialog is open. Set this (or call `close()`) — there is no separate `show()`/`hide()` pair. */
+    open: boolean;
+    /** The full set of tools a consumer offers, across all categories. */
+    tools: ToolSelectDialogTool[];
+    /** The currently-enabled tool ids. */
+    selected: string[];
+    /** 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. */
+    useDefaults: boolean;
+    /** The dialog's visible heading and accessible name. */
+    label: string;
+    searchPlaceholder: string;
+    /** Overrides the built-in case-insensitive name/description substring match. */
+    filter: ToolSelectFilter | null;
+    private query;
+    private hasFooterSlot;
+    private releaseScrollLock?;
+    private lastTrigger?;
+    private readonly titleId;
+    private readonly categoryIds;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private onFooterSlotChange;
+    /**
+     * 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?: ToolSelectDialogCloseReason): void;
+    private onBackdropClick;
+    private onDocKeyDown;
+    private getFocusableElements;
+    private getActiveElement;
+    private emitChange;
+    private onSearchInput;
+    private onDefaultsToggle;
+    private onToolToggle;
+    private categoryId;
+    /** 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. */
+    private get groups();
+    private renderTool;
+    private renderCategory;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lyra-tool-select-dialog': LyraToolSelectDialog;
+    }
+}