@webmcpui/core 0.2.1 → 0.3.1

package/README.md

@@ -12,13 +12,23 @@ imperative [WebMCP](https://webmcpui.com/docs/webmcp) tool an agent can call.
   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.
+  `<wmcp-popover>`, `<wmcp-switch>`, `<wmcp-tooltip>` — or, for `<wmcp-toast>`, a
+  _reading_ an agent can perceive. They share a `WmcpAction` / `WmcpExposable`
+  base.
+- **Presentational primitives** are plain accessible controls (no agent surface)
+  that round out the kit — `<wmcp-badge>`, `<wmcp-separator>`, `<wmcp-alert>`,
+  `<wmcp-progress>`, `<wmcp-avatar>`.
 
 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
 CDN bundle for no-build environments (Webflow, WordPress, plain HTML).
 
+**Using React or Vue?** Typed, idiomatic wrappers ship as
+[`@webmcpui/react`](https://www.npmjs.com/package/@webmcpui/react) and
+[`@webmcpui/vue`](https://www.npmjs.com/package/@webmcpui/vue) — same elements,
+same WebMCP exposure, with framework-native props, `v-model`/state, and events.
+See the [Frameworks guide](https://webmcpui.com/docs/frameworks).
+
 ## Install (build-tool consumers)
 
 ```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;
   }
 }