@webmcpui/core 0.2.0 → 0.3.0

package/README.md

@@ -1,11 +1,19 @@
 # @webmcpui/core
 
-Framework-agnostic, WebMCP-native custom elements. Phase 1 ships form
-primitives — shared behavior (form association, validation, WebMCP exposure,
-theming) lives in a `WmcpFormControl` base class; each element is a thin
-subclass that supplies its control and specifics.
+Framework-agnostic, WebMCP-native custom elements. Every `<wmcp-*>` element is a
+proper, accessible HTML control first and, when you opt in, also registers an
+imperative [WebMCP](https://webmcpui.com/docs/webmcp) tool an agent can call.
 
-Shipped so far: `<wmcp-input>`, `<wmcp-textarea>`, `<wmcp-select>`, `<wmcp-checkbox>`.
+**Two families of primitives:**
+
+- **Form controls** expose a _value_ an agent can set — `<wmcp-input>`,
+  `<wmcp-textarea>`, `<wmcp-select>`, `<wmcp-checkbox>`, `<wmcp-radio>` /
+  `<wmcp-radio-group>`. Shared behavior (form association via `ElementInternals`,
+  Standard Schema validation, a11y, theming) lives in a `WmcpFormControl` base.
+- **Interaction primitives** expose an _action_ an agent can trigger —
+  `<wmcp-button>`, `<wmcp-dialog>`, `<wmcp-menu>`, `<wmcp-tabs>`,
+  `<wmcp-popover>` — or, for `<wmcp-toast>`, a _reading_ an agent can perceive.
+  They share a `WmcpAction` / `WmcpExposable` base.
 
 One source of truth (vanilla custom elements built with [Lit](https://lit.dev)),
 two distribution channels: an ESM package for build tools, and a single-file
@@ -21,11 +29,12 @@ pnpm add @webmcpui/core @webmcpui/tokens
 import { defineComponents } from '@webmcpui/core';
 import '@webmcpui/tokens/css'; // the theme tokens (CSS custom properties)
 
-defineComponents(); // registers <wmcp-input> (and future <wmcp-*> elements)
+defineComponents(); // registers every <wmcp-*> element
 ```
 
 ```html
 <wmcp-input label="Email" name="email" type="email"></wmcp-input>
+<wmcp-button variant="primary">Save</wmcp-button>
 ```
 
 Importing the package does **not** register elements — you call
@@ -45,7 +54,7 @@ For Webflow / WordPress / hand-written HTML — one tag, elements auto-register:
 
 See `examples/plain-html.html` for a working local version.
 
-## Standard Schema validation
+## Standard Schema validation (form controls)
 
 Bring any [Standard Schema](https://standardschema.dev) validator — Zod,
 Valibot, ArkType — set it as the `schema` property. No bespoke schema language.
@@ -59,51 +68,64 @@ input.schema = z.string().email('Enter a valid email');
 
 Validation runs on input and during native form validation; failures set
 `aria-invalid`, render an error message in a live region, and propagate to the
-containing `<form>` via ElementInternals.
-
-> **Note:** Standard Schema validates values but does not emit JSON Schema, so
-> the WebMCP tool's parameter schema is derived from the input `type`, not from
-> the validator. Richer tool schemas are a future enhancement.
+containing `<form>` via `ElementInternals`.
 
 ## WebMCP exposure
 
-Opt in with `expose`. The element registers an imperative WebMCP tool
-(`navigator.modelContext.registerTool`) on connect and unregisters on
-disconnect. It is feature-detected — a complete no-op when no agent/host is
-present (the common case today), so the input is always a good form control
-first.
+Opt in with `expose`. The element registers an imperative WebMCP tool on connect
+and unregisters on disconnect. It is feature-detected — preferring
+`document.modelContext` (canonical as of the Chrome 149+ origin trial) and
+falling back to the deprecated `navigator.modelContext` — and a complete no-op
+when no host is present, so the element is always a good control first.
 
 ```html
+<!-- form control → a "fill" tool that sets a value -->
 <wmcp-input label="Email" name="email" expose></wmcp-input>
-<!-- registers a "fill_email" tool an agent can call -->
+
+<!-- interaction primitive → an "action" tool the agent can trigger -->
+<wmcp-button tool-name="book_appointment" expose>Book</wmcp-button>
+
+<!-- a menu → a parameterized action (the agent picks which item) -->
+<wmcp-menu name="row_action" label="Actions" expose>
+  <option value="edit">Edit</option>
+  <option value="delete">Delete</option>
+</wmcp-menu>
 ```
 
+Consequential steps stay a deliberate human action: an agent can _set_ a value
+or _open_ a dialog, but submitting/confirming is the person's to make.
+
 ## Testing without a real agent
 
-No mainstream agent calls WebMCP yet, so `@webmcpui/core/testing` ships a fake
-host to exercise exposure end to end (and seeds the future inspector):
+No mainstream agent calls WebMCP broadly yet, so `@webmcpui/core/testing` ships a
+fake host to exercise exposure end to end:
 
 ```ts
 import { installFakeAgent } from '@webmcpui/core/testing';
 
 const agent = installFakeAgent();
-// ... connect a <wmcp-input expose> ...
+// ... connect a <wmcp-input expose> / <wmcp-button expose> ...
 await agent.call('fill_email', { value: 'agent@webmcpui.com' });
+await agent.call('click_button');
 agent.restore();
 ```
 
+## Documentation
+
+Full docs, live demos for every element, and `llms.txt` at
+**[webmcpui.com](https://webmcpui.com)**.
+
 ## Build & test
 
 ```bash
 pnpm build        # tsup → dist/ (ESM + IIFE + d.ts)
 pnpm typecheck    # tsc --noEmit
-pnpm test         # @web/test-runner in real Chromium (form association,
-                  # validation a11y, WebMCP exposure)
+pnpm test         # @web/test-runner in real Chromium
 pnpm test:smoke   # node smoke check against the built dist
 ```
 
 Tests run in a genuine browser via the Playwright launcher — form-associated
-custom elements and ElementInternals don't work under jsdom. First run needs
+custom elements and `ElementInternals` don't work under jsdom. First run needs
 the browser binary:
 
 ```bash

package/dist/index.d.ts

@@ -693,7 +693,7 @@ type WmcpPopoverTrigger = 'click' | 'hover';
  * Not auto-registered — call `defineComponents()` (or load the CDN bundle).
  */
 declare class WmcpPopover extends WmcpAction {
-    static readonly tagName = "wmcp-popover";
+    static readonly tagName: string;
     static styles: CSSResultGroup;
     /** Whether the panel is open (reflected). */
     open: boolean;
@@ -786,13 +786,164 @@ declare class WmcpToast extends WmcpExposable {
     render(): TemplateResult;
 }
 
+/**
+ * `<wmcp-switch>` — a form-associated, agent-operable toggle.
+ *
+ * A boolean control like `<wmcp-checkbox>`, but presented as a switch
+ * (`role="switch"`) — on/off rather than checked/unchecked. Its state is the
+ * boolean `checked`; `value` is the string submitted to the form *when on*.
+ * (checkbox and switch are two boolean controls now — a shared
+ * `WmcpBooleanControl` base is a future extraction.)
+ *
+ * Not auto-registered — call `defineComponents()` (or load the CDN bundle).
+ */
+declare class WmcpSwitch extends WmcpFormControl {
+    static readonly tagName = "wmcp-switch";
+    static styles: CSSResultGroup;
+    /** Whether the switch is on. */
+    checked: boolean;
+    private defaultChecked;
+    constructor();
+    protected get controlNoun(): string;
+    connectedCallback(): void;
+    protected getFormValue(): string | File | FormData | null;
+    protected get validationValue(): unknown;
+    protected get isEmpty(): boolean;
+    protected get requiredMessageDefault(): string;
+    protected toolInputSchema(): JSONSchema;
+    protected applyAgentValue(args: Record<string, unknown>): Promise<void>;
+    protected stateDescription(): string;
+    formResetCallback(): void;
+    private onToggle;
+    protected renderControl(): TemplateResult;
+    render(): TemplateResult;
+}
+
+/** Visual variants `<wmcp-badge>` supports (shadcn-aligned). */
+type WmcpBadgeVariant = 'primary' | 'secondary' | 'destructive' | 'outline';
+/**
+ * `<wmcp-badge>` — a small status/label pill. Purely presentational: it exposes
+ * no WebMCP tool (an agent reads its text from the accessibility tree), so it
+ * extends `LitElement` directly rather than an exposure base.
+ *
+ * Not auto-registered — call `defineComponents()` (or load the CDN bundle).
+ */
+declare class WmcpBadge extends LitElement {
+    static readonly tagName = "wmcp-badge";
+    static styles: CSSResultGroup;
+    /** Visual variant. */
+    variant: WmcpBadgeVariant;
+    render(): TemplateResult;
+}
+
+/**
+ * `<wmcp-separator>` — a thin rule dividing content. Presentational; exposes no
+ * WebMCP tool. `role="separator"` (decorative unless it separates focusable
+ * groups). Set `orientation="vertical"` for a vertical divider.
+ *
+ * Not auto-registered — call `defineComponents()` (or load the CDN bundle).
+ */
+declare class WmcpSeparator extends LitElement {
+    static readonly tagName = "wmcp-separator";
+    static styles: CSSResultGroup;
+    /** Divider direction. */
+    orientation: 'horizontal' | 'vertical';
+    connectedCallback(): void;
+}
+
+/**
+ * `<wmcp-tooltip>` — a hover/focus tooltip. A thin preset of
+ * {@link WmcpPopover}: the same anchored-panel machinery, defaulted to
+ * `trigger="hover"` (so it gets `role="tooltip"` + `aria-describedby` and opens
+ * on hover/focus). Put the trigger in the `trigger` slot and the text in the
+ * default slot.
+ *
+ * ```html
+ * <wmcp-tooltip>
+ *   <button slot="trigger" aria-label="Copy">⧉</button>
+ *   Copy to clipboard
+ * </wmcp-tooltip>
+ * ```
+ *
+ * Not auto-registered — call `defineComponents()` (or load the CDN bundle).
+ */
+declare class WmcpTooltip extends WmcpPopover {
+    static readonly tagName = "wmcp-tooltip";
+    constructor();
+    protected get defaultNameSuffix(): string;
+}
+
+/** Severity variants `<wmcp-alert>` supports. */
+type WmcpAlertVariant = 'info' | 'success' | 'warning' | 'error';
+/**
+ * `<wmcp-alert>` — an inline callout for a persistent message. Presentational
+ * (no WebMCP tool; an agent reads it from the a11y tree). Gets `role="alert"`
+ * for `error`/`warning`, `role="status"` otherwise. Optional `title`; the
+ * message is the default slot.
+ *
+ * Not auto-registered — call `defineComponents()` (or load the CDN bundle).
+ */
+declare class WmcpAlert extends LitElement {
+    static readonly tagName = "wmcp-alert";
+    static styles: CSSResultGroup;
+    /** Severity. */
+    variant: WmcpAlertVariant;
+    /** Optional bold heading above the message. */
+    title: string;
+    connectedCallback(): void;
+    render(): TemplateResult;
+}
+
+/**
+ * `<wmcp-progress>` — a determinate or indeterminate progress bar.
+ * Presentational (no WebMCP tool). `role="progressbar"` with `aria-valuenow` /
+ * `aria-valuemax` wired from `value` / `max`; omit `value` (or set
+ * `indeterminate`) for an animated indeterminate bar.
+ *
+ * Not auto-registered — call `defineComponents()` (or load the CDN bundle).
+ */
+declare class WmcpProgress extends LitElement {
+    static readonly tagName = "wmcp-progress";
+    static styles: CSSResultGroup;
+    /** Current value; leave unset for indeterminate. */
+    value?: number;
+    /** Maximum value. */
+    max: number;
+    /** Force the indeterminate (animated) state. */
+    indeterminate: boolean;
+    private get isIndeterminate();
+    updated(): void;
+    render(): TemplateResult;
+}
+
+/**
+ * `<wmcp-avatar>` — a user/entity avatar. Presentational (no WebMCP tool).
+ * Shows the `src` image; if it's missing or fails to load, falls back to the
+ * `fallback` text (e.g. initials). `alt` provides the accessible name.
+ *
+ * Not auto-registered — call `defineComponents()` (or load the CDN bundle).
+ */
+declare class WmcpAvatar extends LitElement {
+    static readonly tagName = "wmcp-avatar";
+    static styles: CSSResultGroup;
+    /** Image URL. */
+    src: string;
+    /** Accessible name for the image. */
+    alt: string;
+    /** Text shown when there's no image (e.g. initials). */
+    fallback: string;
+    private failed;
+    willUpdate(changed: Map<string, unknown>): void;
+    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, 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 };
+export { JSONSchema, StandardSchemaV1, type ValidationOutcome, WebMCPToolResult, WmcpAction, WmcpAlert, type WmcpAlertVariant, WmcpAvatar, WmcpBadge, type WmcpBadgeVariant, WmcpButton, type WmcpButtonSize, type WmcpButtonType, type WmcpButtonVariant, WmcpCheckbox, WmcpDialog, WmcpExposable, WmcpFormControl, WmcpInput, type WmcpInputType, WmcpMenu, type WmcpMenuItem, WmcpPopover, type WmcpPopoverPlacement, type WmcpPopoverTrigger, WmcpProgress, WmcpRadio, WmcpRadioGroup, type WmcpRadioOption, WmcpSelect, type WmcpSelectItem, type WmcpSelectOption, type WmcpSelectOptionGroup, WmcpSeparator, WmcpSwitch, type WmcpTabInfo, WmcpTabs, WmcpTextarea, WmcpToast, type WmcpToastOptions, type WmcpToastVariant, WmcpTooltip, defineComponents, isStandardSchema, textFieldStyles, validateStandard };
 
 declare global {
   interface HTMLElementTagNameMap {
@@ -808,5 +959,12 @@ declare global {
     'wmcp-tabs': import('./index.js').WmcpTabs;
     'wmcp-popover': import('./index.js').WmcpPopover;
     'wmcp-toast': import('./index.js').WmcpToast;
+    'wmcp-switch': import('./index.js').WmcpSwitch;
+    'wmcp-badge': import('./index.js').WmcpBadge;
+    'wmcp-separator': import('./index.js').WmcpSeparator;
+    'wmcp-tooltip': import('./index.js').WmcpTooltip;
+    'wmcp-alert': import('./index.js').WmcpAlert;
+    'wmcp-progress': import('./index.js').WmcpProgress;
+    'wmcp-avatar': import('./index.js').WmcpAvatar;
   }
 }