@webmcpui/core 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gary Pfaff (Pfaff Digital)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# @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.
+
+Shipped so far: `<wmcp-input>`, `<wmcp-textarea>`, `<wmcp-select>`, `<wmcp-checkbox>`.
+
+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).
+
+## Install (build-tool consumers)
+
+```bash
+pnpm add @webmcpui/core @webmcpui/tokens
+```
+
+```ts
+import { defineComponents } from '@webmcpui/core';
+import '@webmcpui/tokens/css'; // the theme tokens (CSS custom properties)
+
+defineComponents(); // registers <wmcp-input> (and future <wmcp-*> elements)
+```
+
+```html
+<wmcp-input label="Email" name="email" type="email"></wmcp-input>
+```
+
+Importing the package does **not** register elements — you call
+`defineComponents()` so you control timing. (The CDN bundle below registers
+automatically.)
+
+## No build? Drop a script tag
+
+For Webflow / WordPress / hand-written HTML — one tag, elements auto-register:
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@webmcpui/tokens/dist/css/tokens.css" />
+<script src="https://cdn.jsdelivr.net/npm/@webmcpui/core/dist/webmcpui.global.js"></script>
+
+<wmcp-input label="Email" name="email" type="email"></wmcp-input>
+```
+
+See `examples/plain-html.html` for a working local version.
+
+## Standard Schema validation
+
+Bring any [Standard Schema](https://standardschema.dev) validator — Zod,
+Valibot, ArkType — set it as the `schema` property. No bespoke schema language.
+
+```ts
+import { z } from 'zod';
+
+const input = document.querySelector('wmcp-input')!;
+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.
+
+## 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.
+
+```html
+<wmcp-input label="Email" name="email" expose></wmcp-input>
+<!-- registers a "fill_email" tool an agent can call -->
+```
+
+## 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):
+
+```ts
+import { installFakeAgent } from '@webmcpui/core/testing';
+
+const agent = installFakeAgent();
+// ... connect a <wmcp-input expose> ...
+await agent.call('fill_email', { value: 'agent@webmcpui.com' });
+agent.restore();
+```
+
+## 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: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
+the browser binary:
+
+```bash
+pnpm exec playwright install chromium
+```

package/dist/chunk-ADS4GRIL.js

@@ -0,0 +1,14 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+
+export {
+  __decorateClass
+};

package/dist/index.d.ts

@@ -0,0 +1,378 @@
+import * as lit from 'lit';
+import { LitElement, CSSResultGroup, TemplateResult, nothing } from 'lit';
+import { J as JSONSchema } from './webmcp-DEspBoqq.js';
+export { T as ToolDisposer, W as WebMCPToolDefinition, a as WebMCPToolResult, b as WebMCPToolResultContent, e as exposeTool, i as isWebMCPAvailable } from './webmcp-DEspBoqq.js';
+
+/**
+ * Minimal Standard Schema v1 types + a validation helper.
+ *
+ * We deliberately depend only on the interop spec (https://standardschema.dev),
+ * never on a specific validator. Devs bring Zod, Valibot, ArkType — anything
+ * that implements `~standard`. This is the Skillet-avoidance decision: no
+ * bespoke schema language, zero learning curve.
+ */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+    interface Props<Input = unknown, Output = Input> {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+        readonly types?: Types<Input, Output>;
+    }
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    interface SuccessResult<Output> {
+        readonly value: Output;
+        readonly issues?: undefined;
+    }
+    interface FailureResult {
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    interface Issue {
+        readonly message: string;
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment>;
+    }
+    interface PathSegment {
+        readonly key: PropertyKey;
+    }
+    interface Types<Input = unknown, Output = Input> {
+        readonly input: Input;
+        readonly output: Output;
+    }
+}
+interface ValidationOutcome<Output> {
+    /** True when the value passed validation. */
+    readonly valid: boolean;
+    /** The (possibly transformed) output value when valid. */
+    readonly value?: Output;
+    /** Flat list of human-readable messages when invalid. */
+    readonly errors: readonly string[];
+}
+/**
+ * Run a Standard Schema validator and normalize the result into a flat outcome
+ * the components can consume. Awaits async validators transparently.
+ */
+declare function validateStandard<Output>(schema: StandardSchemaV1<unknown, Output>, value: unknown): Promise<ValidationOutcome<Output>>;
+/** Duck-type check that an unknown value is a Standard Schema. */
+declare function isStandardSchema(value: unknown): value is StandardSchemaV1;
+
+/**
+ * Base class for form-associated, agent-operable controls.
+ *
+ * Owns everything shared across the form primitives:
+ * - native `<form>` participation via ElementInternals (`formAssociated`)
+ * - Standard Schema validation + a11y error wiring
+ * - imperative WebMCP exposure (feature-detected, no-op when absent)
+ * - label / control / message layout and the shared themed appearance
+ *
+ * Subclasses implement {@link renderControl} (the actual `<input>` /
+ * `<textarea>` / …) and may override {@link controlNoun} and
+ * {@link toolInputSchema}. Abstract — not registered on its own.
+ */
+/**
+ * Text-field box appearance for the `.control` element. Used by input,
+ * textarea, and select — the controls that render as a bordered field.
+ */
+declare const textFieldStyles: lit.CSSResult;
+declare abstract class WmcpFormControl extends LitElement {
+    static formAssociated: boolean;
+    static styles: CSSResultGroup;
+    /** Visible label text. */
+    label: string;
+    /** Form control name (used for submission and the default tool name). */
+    name: string;
+    /** Current value (reflected to the form). */
+    value: string;
+    placeholder: string;
+    required: boolean;
+    disabled: boolean;
+    /** Helper text shown below the control when there is no error. */
+    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.
+     */
+    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>`). */
+    protected get control(): HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement | null;
+    /** Id to point the control's `aria-describedby` at, if any. */
+    protected get describedBy(): string | undefined;
+    connectedCallback(): void;
+    /**
+     * The value contributed to the containing form. Defaults to the string
+     * `value`; controls with a conditional contribution (e.g. an unchecked
+     * checkbox) override this and may return `null` to contribute nothing.
+     */
+    protected getFormValue(): string | File | FormData | null;
+    /** Push the current form value into ElementInternals. */
+    protected syncFormValue(): void;
+    /**
+     * The value passed to the schema validator. Defaults to the string `value`;
+     * boolean controls (checkbox) override to validate their checked state.
+     */
+    protected get validationValue(): unknown;
+    /**
+     * Whether the control counts as empty for the `required` constraint.
+     * Defaults to an empty string value; boolean controls (checkbox) override.
+     */
+    protected get isEmpty(): boolean;
+    /** Default message for the `required` constraint when none is provided. */
+    protected get requiredMessageDefault(): string;
+    disconnectedCallback(): void;
+    updated(changed: Map<string, unknown>): void;
+    /** The resolved WebMCP tool name. */
+    get resolvedToolName(): string;
+    protected registerTool(): void;
+    /**
+     * Apply the agent's tool arguments to component state. Defaults to treating
+     * `args.value` as the new string value; controls with a different shape
+     * (e.g. checkbox's `args.checked`) override this.
+     */
+    protected applyAgentValue(args: Record<string, unknown>): Promise<void>;
+    /** Human-readable current state, used in the tool's result message. */
+    protected stateDescription(): string;
+    /** JSON Schema for the WebMCP tool's args. Defaults to a single string. */
+    protected toolInputSchema(): JSONSchema;
+    /** Apply a value as if a user typed it: update, validate, announce. */
+    setValueFromAgent(value: string): Promise<void>;
+    protected onInput(event: Event): Promise<void>;
+    /** Compute validity: the `required` constraint first, then the schema. */
+    private computeValidity;
+    /**
+     * Validate and reflect the result to the form via ElementInternals.
+     *
+     * @param show When true (default, on interaction) the error is also made
+     *   visible. When false (on connect/reset) validity is set for
+     *   `form.checkValidity()` but the message stays hidden until the form is
+     *   actually reported (native-style — the `invalid` event reveals it).
+     */
+    validate(show?: boolean): Promise<boolean>;
+    /** Reveal the validation message when the form reports validity (submit). */
+    private readonly onInvalid;
+    /** Called by the form when it resets. */
+    formResetCallback(): void;
+    /** Subclasses render their control element here (id/class "control"). */
+    protected abstract renderControl(): TemplateResult;
+    protected renderMessage(): TemplateResult<1> | typeof nothing;
+    render(): TemplateResult<1>;
+}
+
+type WmcpInputType = 'text' | 'email' | 'password' | 'number' | 'tel' | 'url' | 'search' | 'date';
+/**
+ * `<wmcp-input>` — a form-associated, agent-operable single-line text input.
+ *
+ * Behavior (form association, validation, WebMCP exposure, theming) comes from
+ * {@link WmcpFormControl}; this adds the `type` attribute and the `<input>`.
+ *
+ * Not auto-registered — call `defineComponents()` (or load the CDN bundle).
+ */
+declare class WmcpInput extends WmcpFormControl {
+    static readonly tagName = "wmcp-input";
+    static styles: lit.CSSResultGroup[];
+    /** HTML input type. */
+    type: WmcpInputType;
+    protected get controlNoun(): string;
+    protected toolInputSchema(): JSONSchema;
+    protected renderControl(): lit.TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'wmcp-input': WmcpInput;
+    }
+}
+
+/**
+ * `<wmcp-textarea>` — a form-associated, agent-operable multi-line text input.
+ *
+ * Behavior comes from {@link WmcpFormControl}; this adds the `rows` attribute
+ * and the `<textarea>`. It shares the input token surface (`--input-*`) and
+ * adds `--textarea-min-height`.
+ *
+ * Not auto-registered — call `defineComponents()` (or load the CDN bundle).
+ */
+declare class WmcpTextarea extends WmcpFormControl {
+    static readonly tagName = "wmcp-textarea";
+    static styles: lit.CSSResultGroup[];
+    /** Initial visible number of text lines. */
+    rows: number;
+    protected get controlNoun(): string;
+    protected renderControl(): lit.TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'wmcp-textarea': WmcpTextarea;
+    }
+}
+
+interface WmcpSelectOption {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+interface WmcpSelectOptionGroup {
+    label: string;
+    options: WmcpSelectOption[];
+}
+type WmcpSelectItem = WmcpSelectOption | WmcpSelectOptionGroup;
+/**
+ * `<wmcp-select>` — a form-associated, agent-operable single-select dropdown.
+ *
+ * Wraps a native `<select>` (correct keyboard nav, screen-reader behavior, and
+ * mobile pickers for free). Options come from declarative `<option>` /
+ * `<optgroup>` children (HTML-native, works with no build) or from the
+ * `options` property (for JS / framework callers).
+ *
+ * The value is a single string, so form association and WebMCP fill behavior
+ * come from {@link WmcpFormControl}; this adds the option model and a tool
+ * schema whose `value` is an `enum` of the valid option values.
+ *
+ * Not auto-registered — call `defineComponents()` (or load the CDN bundle).
+ */
+declare class WmcpSelect extends WmcpFormControl {
+    static readonly tagName = "wmcp-select";
+    static styles: lit.CSSResultGroup[];
+    /**
+     * Options as data. When non-empty, takes precedence over declarative
+     * `<option>` children. Set as a property, not an attribute.
+     */
+    options: WmcpSelectItem[];
+    /** The normalized option model actually rendered (property or declarative). */
+    private resolvedOptions;
+    private optionObserver?;
+    protected get controlNoun(): string;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    willUpdate(changed: Map<string, unknown>): void;
+    updated(changed: Map<string, unknown>): void;
+    private syncOptions;
+    private readDeclarativeOptions;
+    /** All selectable options, flattened across groups. */
+    flatOptions(): WmcpSelectOption[];
+    protected toolInputSchema(): JSONSchema;
+    private renderOption;
+    protected renderControl(): lit.TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'wmcp-select': WmcpSelect;
+    }
+}
+
+/**
+ * `<wmcp-checkbox>` — a form-associated, agent-operable boolean checkbox.
+ *
+ * The first non-string control. Its primary state is the boolean `checked`;
+ * `value` is the string submitted to the form *when checked* (native default
+ * `"on"`). This is why {@link WmcpFormControl} exposes hooks: checkbox overrides
+ * `getFormValue` (conditional), `validationValue` (the boolean),
+ * `applyAgentValue` / `toolInputSchema` (a `checked` boolean), and
+ * `formResetCallback` (restore the initial checked state).
+ *
+ * Not auto-registered — call `defineComponents()` (or load the CDN bundle).
+ */
+declare class WmcpCheckbox extends WmcpFormControl {
+    static readonly tagName = "wmcp-checkbox";
+    static styles: lit.CSSResultGroup[];
+    /** Whether the box is checked. */
+    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(): lit.TemplateResult<1>;
+    render(): lit.TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'wmcp-checkbox': WmcpCheckbox;
+    }
+}
+
+interface WmcpRadioOption {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+/**
+ * `<wmcp-radio>` — a data member of a `<wmcp-radio-group>`.
+ *
+ * Like `<option>` is to `<select>`: it carries `value` / `label` / `disabled`
+ * and renders nothing itself. The group reads these and renders the actual
+ * radio inputs. Registered so it hides itself when used declaratively.
+ */
+declare class WmcpRadio extends HTMLElement {
+    static readonly tagName = "wmcp-radio";
+    get value(): string;
+    get label(): string;
+    get disabled(): boolean;
+    connectedCallback(): void;
+}
+/**
+ * `<wmcp-radio-group>` — a form-associated, agent-operable single-choice group.
+ *
+ * The group is the form participant (owns name, value, validation, exposure);
+ * `<wmcp-radio>` children are data. The group renders the native radio inputs
+ * in its own shadow DOM under one internal name, so native single-selection,
+ * roving tabindex, and arrow-key navigation all work. Options come from
+ * declarative `<wmcp-radio>` children or the `options` property.
+ *
+ * Not auto-registered — call `defineComponents()` (or load the CDN bundle).
+ */
+declare class WmcpRadioGroup extends WmcpFormControl {
+    static readonly tagName = "wmcp-radio-group";
+    static styles: lit.CSSResultGroup[];
+    /** Options as data. When non-empty, takes precedence over `<wmcp-radio>`. */
+    options: WmcpRadioOption[];
+    private resolvedOptions;
+    private optionObserver?;
+    /** Internal name shared by the rendered inputs (groups them natively). */
+    private readonly groupName;
+    protected get controlNoun(): string;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    willUpdate(changed: Map<string, unknown>): void;
+    updated(changed: Map<string, unknown>): void;
+    private syncOptions;
+    private readDeclarativeOptions;
+    protected toolInputSchema(): JSONSchema;
+    private onSelect;
+    protected renderControl(): lit.TemplateResult<1>;
+    render(): lit.TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'wmcp-radio': WmcpRadio;
+        'wmcp-radio-group': WmcpRadioGroup;
+    }
+}
+
+/**
+ * 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 };