@webmcpui/core 0.1.2 → 0.2.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { LitElement, CSSResultGroup, TemplateResult, nothing, CSSResult } from 'lit';
-import { J as JSONSchema } from './webmcp-JAn7I2xj.js';
-export { T as ToolDisposer, W as WebMCPToolDefinition, a as WebMCPToolResult, b as WebMCPToolResultContent, e as exposeTool, i as isWebMCPAvailable } from './webmcp-JAn7I2xj.js';
+import { J as JSONSchema, W as WebMCPToolResult } from './webmcp-DbmbtX6x.js';
+export { T as ToolDisposer, a as WebMCPToolDefinition, b as WebMCPToolResultContent, e as exposeTool, i as isWebMCPAvailable } from './webmcp-DbmbtX6x.js';
 
 /**
  * Minimal Standard Schema v1 types + a validation helper.
@@ -61,6 +61,51 @@ declare function validateStandard<Output>(schema: StandardSchemaV1<unknown, Outp
 /** Duck-type check that an unknown value is a Standard Schema. */
 declare function isStandardSchema(value: unknown): value is StandardSchemaV1;
 
+/**
+ * Base for every element that can register itself as a WebMCP tool — both the
+ * *value* controls ({@link WmcpFormControl}) and the *action* elements
+ * ({@link WmcpAction}).
+ *
+ * It owns only the exposure *mechanism*: the `expose` / `tool-name` /
+ * `tool-description` opt-in surface, the tool's lifecycle (register on connect,
+ * dispose on disconnect, re-register when its identity changes, drop when
+ * `expose` is turned off), and the single `exposeTool` call. The spec-sensitive
+ * registration/disposal itself lives one layer down in `exposeTool`, so this is
+ * thin wiring over a single source of truth.
+ *
+ * Each subtree supplies the *policy* via four hooks — {@link resolvedToolName},
+ * {@link defaultToolDescription}, {@link toolInputSchema}, {@link executeTool} —
+ * plus {@link toolReactiveProps} when extra properties feed the tool's name or
+ * description. Abstract — not registered on its own.
+ */
+declare abstract class WmcpExposable extends LitElement {
+    /** Whether to expose this element as a WebMCP tool. */
+    expose: boolean;
+    /** Override the generated WebMCP tool name. */
+    toolName: string;
+    /** Override the generated WebMCP tool description. */
+    toolDescription: string;
+    private toolDisposer;
+    /** The resolved WebMCP tool name. */
+    abstract get resolvedToolName(): string;
+    /** Description used when `tool-description` is not set. */
+    protected abstract get defaultToolDescription(): string;
+    /** JSON Schema for the tool's args. Defaults to a no-argument tool. */
+    protected toolInputSchema(): JSONSchema;
+    /** Invoked when the agent calls the tool; returns the agent-facing result. */
+    protected abstract executeTool(args: Record<string, unknown>): WebMCPToolResult | Promise<WebMCPToolResult>;
+    /**
+     * Property changes that alter the tool's *identity* (name/description) and so
+     * require re-registration. State read live inside {@link executeTool} does
+     * not belong here. Subclasses extend this with their own naming inputs.
+     */
+    protected get toolReactiveProps(): readonly string[];
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    updated(changed: Map<string, unknown>): void;
+    protected registerTool(): void;
+}
+
 /**
  * Base class for form-associated, agent-operable controls.
  *
@@ -86,7 +131,7 @@ declare const textFieldStyles: CSSResult;
  * that supplies its control markup and tool schema. Abstract — not registered
  * on its own.
  */
-declare abstract class WmcpFormControl extends LitElement {
+declare abstract class WmcpFormControl extends WmcpExposable {
     static formAssociated: boolean;
     static styles: CSSResultGroup;
     /** Visible label text. */
@@ -102,12 +147,6 @@ declare abstract class WmcpFormControl extends LitElement {
     helperText: string;
     /** Message shown when a `required` control is empty. */
     requiredMessage: string;
-    /** Whether to expose this control as a WebMCP tool. */
-    expose: boolean;
-    /** Override the generated WebMCP tool name. */
-    toolName: string;
-    /** Override the generated WebMCP tool description. */
-    toolDescription: string;
     /**
      * Standard Schema validator (Zod, Valibot, ArkType, …). Set as a property,
      * not an attribute. Validation runs on input and on form validation.
@@ -115,7 +154,6 @@ declare abstract class WmcpFormControl extends LitElement {
     schema?: StandardSchemaV1<unknown, unknown>;
     protected error: string;
     protected readonly internals: ElementInternals;
-    private toolDisposer;
     /** Noun used in default tool names/descriptions when `name` is empty. */
     protected get controlNoun(): string;
     /** The rendered control element (`<input>` / `<textarea>` / `<select>`). */
@@ -145,9 +183,10 @@ declare abstract class WmcpFormControl extends LitElement {
     protected get requiredMessageDefault(): string;
     disconnectedCallback(): void;
     updated(changed: Map<string, unknown>): void;
-    /** The resolved WebMCP tool name. */
     get resolvedToolName(): string;
-    protected registerTool(): void;
+    protected get defaultToolDescription(): string;
+    protected get toolReactiveProps(): readonly string[];
+    protected executeTool(args: Record<string, unknown>): Promise<WebMCPToolResult>;
     /**
      * Apply the agent's tool arguments to component state. Defaults to treating
      * `args.value` as the new string value; controls with a different shape
@@ -359,13 +398,401 @@ declare class WmcpRadioGroup extends WmcpFormControl {
     render(): TemplateResult;
 }
 
+/**
+ * Base class for agent-operable *action* elements.
+ *
+ * Where {@link WmcpFormControl} exposes a *value* an agent can set, an action
+ * element exposes an *action* an agent can trigger — a click, an open, a
+ * dismissal. The WebMCP exposure mechanism (the `expose` surface, the tool
+ * lifecycle, the `exposeTool` call) lives in the shared {@link WmcpExposable}
+ * base; this layer adds the action-flavored *policy*: a verb-prefixed tool name
+ * (`click_save`, `open_booking`), an action-shaped default description, and a
+ * no-argument tool by default.
+ *
+ * A subclass supplies {@link actionVerb} and {@link executeTool}, and may
+ * override {@link actionNoun}, {@link defaultNameSuffix}, or
+ * {@link toolInputSchema} (e.g. a menu whose action takes which-item). Abstract
+ * — not registered on its own.
+ *
+ * Extracted when the second action element (dialog) landed alongside the first
+ * (button) — two data points reveal what's genuinely shared, the same rule
+ * that produced `WmcpFormControl`.
+ */
+declare abstract class WmcpAction extends WmcpExposable {
+    /** Identifier used to build the default tool name. */
+    name: string;
+    /** Accessible name and the noun used in the default tool description. */
+    label: string;
+    /** Verb that prefixes the default tool name, e.g. `click` → `click_save`. */
+    protected abstract get actionVerb(): string;
+    /** Suffix for the default tool name when `name` is empty. */
+    protected get defaultNameSuffix(): string;
+    /** Human-readable noun for the thing being acted on. */
+    protected get actionNoun(): string;
+    get resolvedToolName(): string;
+    protected get defaultToolDescription(): string;
+    protected get toolReactiveProps(): readonly string[];
+    /**
+     * Perform the action and return the agent-facing result. Called when the
+     * agent invokes the tool; subclasses implement the actual effect.
+     */
+    protected abstract executeTool(args: Record<string, unknown>): WebMCPToolResult | Promise<WebMCPToolResult>;
+}
+
+/** Visual variants `<wmcp-button>` supports (shadcn-aligned). */
+type WmcpButtonVariant = 'primary' | 'secondary' | 'destructive' | 'outline' | 'ghost';
+/** Size variants `<wmcp-button>` supports. */
+type WmcpButtonSize = 'sm' | 'md' | 'lg';
+/** Native button behaviors `<wmcp-button>` mirrors. */
+type WmcpButtonType = 'button' | 'submit' | 'reset';
+/**
+ * `<wmcp-button>` — a themeable, agent-operable button. The first Phase 2
+ * interaction primitive.
+ *
+ * Where the form controls expose a *value* an agent can set, a button exposes
+ * an *action* an agent can trigger. When a WebMCP host is present and the
+ * button opts in (`expose`), it registers a tool that activates the button
+ * exactly as a human click would — running light-DOM `click` handlers and, for
+ * `type="submit"`/`"reset"`, driving the associated form. With no agent
+ * present (the common case today) it is simply a good, accessible button.
+ *
+ * Activation has a single path: both a real click and an agent tool call route
+ * through the inner native `<button>`, so behavior, focus, and form
+ * participation are identical for human and agent. A `disabled` button can be
+ * activated by neither.
+ *
+ * Form-associated, so `type="submit"` and `type="reset"` work from inside the
+ * shadow boundary (a native submit button there would not reach the outer
+ * form). Visible content is slotted; an explicit `label` is used for the
+ * accessible name and the default tool description when set.
+ *
+ * Not auto-registered — call `defineComponents()` (or load the CDN bundle).
+ */
+declare class WmcpButton extends WmcpAction {
+    static readonly tagName = "wmcp-button";
+    static formAssociated: boolean;
+    static shadowRootOptions: ShadowRootInit;
+    static styles: CSSResultGroup;
+    /** Visual variant. */
+    variant: WmcpButtonVariant;
+    /** Size. */
+    size: WmcpButtonSize;
+    /** Native button behavior: a plain button, a form submit, or a form reset. */
+    type: WmcpButtonType;
+    /** Disables the button for both humans and agents. */
+    disabled: boolean;
+    private readonly internals;
+    /** The inner native `<button>` that owns activation, focus, and a11y. */
+    private get button();
+    protected get actionVerb(): string;
+    protected get defaultNameSuffix(): string;
+    protected get actionNoun(): string;
+    protected get defaultToolDescription(): string;
+    protected executeTool(): WebMCPToolResult;
+    /**
+     * Activate the button as if a human clicked it: routes through the inner
+     * native button so light-DOM `click` handlers fire and `type`-driven form
+     * submission/reset happens. A no-op when disabled.
+     */
+    activate(): void;
+    /**
+     * Inner-button click handler. The native click already bubbles (composed) to
+     * the host, so light-DOM listeners fire without help; this only adds the
+     * cross-shadow form behavior a native submit/reset button can't do from here.
+     */
+    private onInnerClick;
+    render(): TemplateResult;
+}
+
+/**
+ * `<wmcp-dialog>` — a modal dialog whose *action* is being opened. The second
+ * Phase 2 interaction primitive, and the one that motivated the shared
+ * {@link WmcpAction} base.
+ *
+ * It wraps the native `<dialog>` element, so it inherits the platform's focus
+ * trap, top-layer stacking, backdrop, and Escape-to-close for free. The
+ * exposed WebMCP action is **open** — the agent surfaces the dialog for the
+ * user to review; closing/confirming stays a deliberate human (or
+ * programmatic) step. That asymmetry is the consent gate: an agent can ask for
+ * attention, but the irreversible confirm is the person's to make.
+ *
+ * Drive it declaratively with the reflected `open` attribute or imperatively
+ * with {@link show} / {@link close}; either way it emits composed `open` and
+ * `close` events. With no agent present it is simply an accessible modal.
+ *
+ * Not auto-registered — call `defineComponents()` (or load the CDN bundle).
+ */
+declare class WmcpDialog extends WmcpAction {
+    static readonly tagName = "wmcp-dialog";
+    static styles: CSSResultGroup;
+    /** Whether the dialog is open (reflected, so `[open]` styling works). */
+    open: boolean;
+    /** Open as a modal (focus-trapping, with backdrop). Set false for non-modal. */
+    modal: boolean;
+    /** Keep the dialog open when the backdrop is clicked (modal "static" mode). */
+    staticBackdrop: boolean;
+    /** Last `returnValue` the dialog closed with (mirrors native `<dialog>`). */
+    returnValue: string;
+    private get dialogEl();
+    protected get actionVerb(): string;
+    protected get defaultNameSuffix(): string;
+    protected get defaultToolDescription(): string;
+    protected executeTool(): WebMCPToolResult;
+    updated(changed: Map<string, unknown>): void;
+    /** Open the dialog (modal unless `modal` is false). */
+    show(): void;
+    /** Close the dialog, optionally recording a `returnValue`. */
+    close(returnValue?: string): void;
+    /** Reconcile our `open` state with the native dialog's imperative API. */
+    private syncNativeOpen;
+    /** Native `close` fires for Escape, backdrop, or our own `close()`. */
+    private onNativeClose;
+    /**
+     * Close on a backdrop click. A click whose target is the `<dialog>` itself
+     * is the backdrop — content clicks retarget to `.panel` or its children — so
+     * this never fires on the dialog's own frame or a text drag-select.
+     */
+    private onDialogClick;
+    render(): TemplateResult;
+}
+
+/** A single selectable item in a `<wmcp-menu>`. */
+interface WmcpMenuItem {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+/**
+ * `<wmcp-menu>` — a menu-button whose exposed action is *selecting an item*.
+ * The first **parameterized** interaction primitive: where button and dialog
+ * expose no-argument actions, the menu's tool takes *which item* — an `enum`
+ * of the item values — so it pressure-tests the {@link WmcpAction} base the
+ * way `<wmcp-select>` did for `WmcpFormControl`.
+ *
+ * The popup uses the native Popover API (top layer, light-dismiss, and Escape
+ * for free); items come from declarative `<option>` children (no build) or the
+ * `items` property. Selecting an item — by human click, keyboard, or agent
+ * tool call — fires a composed `select` event (`detail: { value, label }`) and
+ * closes the menu. A menu dispatches actions; it does not hold a value.
+ *
+ * Not auto-registered — call `defineComponents()` (or load the CDN bundle).
+ */
+declare class WmcpMenu extends WmcpAction {
+    static readonly tagName = "wmcp-menu";
+    static styles: CSSResultGroup;
+    /** Trigger label. */
+    label: string;
+    /**
+     * Items as data. When non-empty, takes precedence over declarative
+     * `<option>` children. Set as a property, not an attribute.
+     */
+    items: WmcpMenuItem[];
+    /** Whether the popup is open (reflected). */
+    open: boolean;
+    /** The normalized item model actually rendered (property or declarative). */
+    private resolvedItems;
+    private itemObserver?;
+    private get menuEl();
+    private get itemButtons();
+    protected get actionVerb(): string;
+    protected get defaultNameSuffix(): string;
+    protected get actionNoun(): string;
+    protected get defaultToolDescription(): string;
+    protected get toolReactiveProps(): readonly string[];
+    protected toolInputSchema(): JSONSchema;
+    protected executeTool(args: Record<string, unknown>): WebMCPToolResult;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    willUpdate(changed: Map<string, unknown>): void;
+    private syncItems;
+    private readDeclarativeItems;
+    /** Dispatch the selection and close the menu. */
+    private selectItem;
+    private onItemClick;
+    /** Sync `open`/`aria-expanded` and move focus into the menu when it opens. */
+    private onToggle;
+    /** Roving focus among items with the arrow / Home / End keys. */
+    private onMenuKeydown;
+    render(): TemplateResult;
+}
+
+/** A single tab derived from a `[tab]` panel child of `<wmcp-tabs>`. */
+interface WmcpTabInfo {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+/**
+ * `<wmcp-tabs>` — a tab set whose exposed action is *switching the active tab*.
+ * The first **stateful** interaction primitive: where button/dialog/menu are
+ * fire-and-forget dispatchers, a tab set holds a persistent `active` selection
+ * (reflected), and the agent's tool both reads and changes it.
+ *
+ * It confirms the {@link WmcpAction} base needs no "current value" concept — a
+ * stateful action element simply owns its own state (here `active`, like the
+ * dialog owns `open`) and its `executeTool` mutates it.
+ *
+ * Panels are declarative light-DOM children carrying a `tab` attribute (and an
+ * optional `tab-label`); the tablist is derived from them. Switching — by
+ * click, arrow keys, or agent — updates `active`, reveals the matching panel,
+ * and fires a composed `change` event (`detail: { value }`).
+ *
+ * Not auto-registered — call `defineComponents()` (or load the CDN bundle).
+ */
+declare class WmcpTabs extends WmcpAction {
+    static readonly tagName = "wmcp-tabs";
+    static styles: CSSResultGroup;
+    /** The value of the active tab (reflected — this is the persistent state). */
+    active: string;
+    /** Accessible name for the tablist. */
+    label: string;
+    /** The tab model derived from the `[tab]` panel children. */
+    private tabs;
+    private panelObserver?;
+    protected get actionVerb(): string;
+    protected get defaultNameSuffix(): string;
+    protected get actionNoun(): string;
+    protected get defaultToolDescription(): string;
+    protected get toolReactiveProps(): readonly string[];
+    protected toolInputSchema(): JSONSchema;
+    protected executeTool(args: Record<string, unknown>): WebMCPToolResult;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    updated(changed: Map<string, unknown>): void;
+    /** Light-DOM children that declare a tab via the `tab` attribute. */
+    private get panelEls();
+    private syncTabs;
+    /** Fall back to the first enabled tab when `active` is unset or invalid. */
+    private ensureActive;
+    /** Reflect the active tab onto the slotted panels (roles, labels, hidden). */
+    private applyPanels;
+    /** Switch the active tab, firing `change` when it actually moves. */
+    switchTo(value: string): void;
+    private get tabButtons();
+    /** Arrow / Home / End roving with automatic activation (ARIA tabs pattern). */
+    private onKeydown;
+    render(): TemplateResult;
+}
+
+/** Where the panel sits relative to its trigger. */
+type WmcpPopoverPlacement = 'top' | 'bottom' | 'left' | 'right';
+/** How the popover is opened: clicked (interactive) or hovered (tooltip). */
+type WmcpPopoverTrigger = 'click' | 'hover';
+/**
+ * `<wmcp-popover>` — a non-modal, anchored floating panel whose exposed action
+ * is being opened. The sibling of [dialog](./dialog.ts) (modal) and
+ * [menu](./menu.ts) (action list): same native-Popover-API + CSS-anchor
+ * machinery as the menu, but the content is arbitrary.
+ *
+ * `trigger="click"` (default) gives an interactive popover — click to toggle,
+ * with light-dismiss and Escape for free. `trigger="hover"` gives a tooltip —
+ * it opens on hover/focus, closes on leave/blur, and labels its trigger via
+ * `aria-describedby`. Either way the agent can `open` it; closing stays a
+ * human/light-dismiss step, the same consent posture as the dialog.
+ *
+ * Not auto-registered — call `defineComponents()` (or load the CDN bundle).
+ */
+declare class WmcpPopover extends WmcpAction {
+    static readonly tagName = "wmcp-popover";
+    static styles: CSSResultGroup;
+    /** Whether the panel is open (reflected). */
+    open: boolean;
+    /** Trigger text, used when no `trigger` slot content is provided. */
+    label: string;
+    /** Panel placement relative to the trigger. */
+    placement: WmcpPopoverPlacement;
+    /** Open on click (interactive popover) or on hover/focus (tooltip). */
+    trigger: WmcpPopoverTrigger;
+    private get panelEl();
+    protected get actionVerb(): string;
+    protected get defaultNameSuffix(): string;
+    protected get defaultToolDescription(): string;
+    protected executeTool(): WebMCPToolResult;
+    updated(changed: Map<string, unknown>): void;
+    /** Open the popover. */
+    show(): void;
+    /** Close the popover. */
+    close(): void;
+    private syncNativeOpen;
+    /** Native toggle fires for clicks, light-dismiss, Escape, and our own calls. */
+    private onToggle;
+    private closeTimer?;
+    disconnectedCallback(): void;
+    /** Open on hover/focus of the trigger *or* the panel. */
+    private openOnHover;
+    /**
+     * Close on leave/blur — but on a short delay, so the pointer can cross the
+     * gap from the trigger to the panel (and reach interactive content inside it)
+     * without the popover vanishing. Re-entering either cancels the close.
+     */
+    private scheduleHoverClose;
+    private cancelScheduledClose;
+    render(): TemplateResult;
+}
+
+/** A toast's severity, used for styling and the agent-readable summary. */
+type WmcpToastVariant = 'info' | 'success' | 'warning' | 'error';
+/** Options accepted by {@link WmcpToast.show}. */
+interface WmcpToastOptions {
+    title?: string;
+    message: string;
+    variant?: WmcpToastVariant;
+    /** Auto-dismiss after this many ms; `0` keeps it until dismissed. */
+    duration?: number;
+}
+/**
+ * `<wmcp-toast>` — a notification region, and the one component whose agent
+ * surface is *perceiving* rather than *actuating*.
+ *
+ * Page code throws toasts the way it always has — `el.show({ message })` — and
+ * they announce to screen readers via an `aria-live` region. When `expose` is
+ * set, the very same notifications become readable by an agent through a
+ * `read_<name>` tool: the machine-readable twin of the `aria-live`
+ * announcement. An agent acting on the user's behalf often has no other way to
+ * learn an outcome ("Payment declined", an async "Export ready"), so it reads
+ * the toasts rather than posting them.
+ *
+ * Extends {@link WmcpExposable} directly — not {@link WmcpAction} — because the
+ * tool reports state instead of triggering an action.
+ *
+ * Not auto-registered — call `defineComponents()` (or load the CDN bundle).
+ */
+declare class WmcpToast extends WmcpExposable {
+    static readonly tagName = "wmcp-toast";
+    static styles: CSSResultGroup;
+    /** Identifier used for the default tool name (`read_<name>`). */
+    name: string;
+    /** Accessible name for the live region. */
+    label: string;
+    /** Corner the toasts stack in. */
+    placement: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    /** Default auto-dismiss in ms; `0` keeps toasts until dismissed. */
+    duration: number;
+    private toasts;
+    private recent;
+    private nextId;
+    private timers;
+    /** Show a toast. Returns its id (pass to {@link dismiss}). */
+    show(options: WmcpToastOptions): number;
+    /** Dismiss a toast by id. */
+    dismiss(id: number): void;
+    /** Dismiss all visible toasts. */
+    clear(): void;
+    disconnectedCallback(): void;
+    get resolvedToolName(): string;
+    protected get defaultToolDescription(): string;
+    protected get toolReactiveProps(): readonly string[];
+    protected executeTool(): WebMCPToolResult;
+    render(): TemplateResult;
+}
+
 /**
  * Register all webmcpui custom elements. Idempotent — safe to call more than
  * once and safe alongside the CDN bundle (already-defined tags are skipped).
  */
 declare function defineComponents(): void;
 
-export { JSONSchema, StandardSchemaV1, type ValidationOutcome, WmcpCheckbox, WmcpFormControl, WmcpInput, type WmcpInputType, WmcpRadio, WmcpRadioGroup, type WmcpRadioOption, WmcpSelect, type WmcpSelectItem, type WmcpSelectOption, type WmcpSelectOptionGroup, WmcpTextarea, defineComponents, isStandardSchema, textFieldStyles, validateStandard };
+export { JSONSchema, StandardSchemaV1, type ValidationOutcome, WebMCPToolResult, WmcpAction, WmcpButton, type WmcpButtonSize, type WmcpButtonType, type WmcpButtonVariant, WmcpCheckbox, WmcpDialog, WmcpExposable, WmcpFormControl, WmcpInput, type WmcpInputType, WmcpMenu, type WmcpMenuItem, WmcpPopover, type WmcpPopoverPlacement, type WmcpPopoverTrigger, WmcpRadio, WmcpRadioGroup, type WmcpRadioOption, WmcpSelect, type WmcpSelectItem, type WmcpSelectOption, type WmcpSelectOptionGroup, type WmcpTabInfo, WmcpTabs, WmcpTextarea, WmcpToast, type WmcpToastOptions, type WmcpToastVariant, defineComponents, isStandardSchema, textFieldStyles, validateStandard };
 
 declare global {
   interface HTMLElementTagNameMap {
@@ -375,5 +802,11 @@ declare global {
     'wmcp-checkbox': import('./index.js').WmcpCheckbox;
     'wmcp-radio': import('./index.js').WmcpRadio;
     'wmcp-radio-group': import('./index.js').WmcpRadioGroup;
+    'wmcp-button': import('./index.js').WmcpButton;
+    'wmcp-dialog': import('./index.js').WmcpDialog;
+    'wmcp-menu': import('./index.js').WmcpMenu;
+    'wmcp-tabs': import('./index.js').WmcpTabs;
+    'wmcp-popover': import('./index.js').WmcpPopover;
+    'wmcp-toast': import('./index.js').WmcpToast;
   }
 }