react-webmcp 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import React from 'react';
+import React$1 from 'react';
 
 /**
  * WebMCP type definitions for the W3C navigator.modelContext API.
@@ -36,7 +36,13 @@ interface JSONSchema {
     items?: JSONSchemaProperty;
 }
 interface ToolAnnotations {
-    /** Indicates the tool only reads data and does not modify state (browser-native). */
+    /**
+     * Indicates the tool only reads data and does not modify state.
+     *
+     * Per the spec's formalized `registerTool()` algorithm, this value is
+     * extracted from annotations and stored as a top-level field on the
+     * internal tool definition struct (`read-only hint`, initially false).
+     */
     readOnlyHint?: boolean;
     /**
      * Indicates the tool performs a destructive/irreversible operation.
@@ -138,6 +144,7 @@ interface ModelContextTesting {
         name: string;
         description: string;
         inputSchema: string;
+        readOnlyHint?: boolean;
     }>;
     /**
      * Execute a tool by name.
@@ -270,7 +277,7 @@ declare function useWebMCPContext(config: {
  */
 declare function useToolEvent(event: "toolactivated" | "toolcancel", callback: (toolName: string) => void, toolNameFilter?: string): void;
 
-interface WebMCPFormProps extends Omit<React.FormHTMLAttributes<HTMLFormElement>, "onSubmit"> {
+interface WebMCPFormProps extends Omit<React$1.FormHTMLAttributes<HTMLFormElement>, "onSubmit"> {
     /** The tool name exposed to AI agents. Maps to the `toolname` HTML attribute. */
     toolName: string;
     /** Description of what this tool does. Maps to `tooldescription`. */
@@ -286,7 +293,7 @@ interface WebMCPFormProps extends Omit<React.FormHTMLAttributes<HTMLFormElement>
     onToolActivated?: (toolName: string) => void;
     /** Called when a tool cancel event fires for this form's tool. */
     onToolCancel?: (toolName: string) => void;
-    children: React.ReactNode;
+    children: React$1.ReactNode;
 }
 /**
  * A React wrapper for the WebMCP declarative API.
@@ -314,7 +321,7 @@ interface WebMCPFormProps extends Omit<React.FormHTMLAttributes<HTMLFormElement>
  */
 declare function WebMCPForm({ toolName, toolDescription, toolAutoSubmit, onSubmit, onToolActivated, onToolCancel, children, ...rest }: WebMCPFormProps): react_jsx_runtime.JSX.Element;
 
-interface WebMCPInputProps extends React.InputHTMLAttributes<HTMLInputElement> {
+interface WebMCPInputProps extends React$1.InputHTMLAttributes<HTMLInputElement> {
     /** Maps to the `toolparamtitle` attribute (overrides the JSON Schema property key). */
     toolParamTitle?: string;
     /** Maps to the `toolparamdescription` attribute (describes this parameter to agents). */
@@ -337,14 +344,14 @@ interface WebMCPInputProps extends React.InputHTMLAttributes<HTMLInputElement> {
  * />
  * ```
  */
-declare const WebMCPInput: React.ForwardRefExoticComponent<WebMCPInputProps & React.RefAttributes<HTMLInputElement>>;
+declare const WebMCPInput: React$1.ForwardRefExoticComponent<WebMCPInputProps & React$1.RefAttributes<HTMLInputElement>>;
 
-interface WebMCPSelectProps extends React.SelectHTMLAttributes<HTMLSelectElement> {
+interface WebMCPSelectProps extends React$1.SelectHTMLAttributes<HTMLSelectElement> {
     /** Maps to the `toolparamtitle` attribute (overrides the JSON Schema property key). */
     toolParamTitle?: string;
     /** Maps to the `toolparamdescription` attribute (describes this parameter to agents). */
     toolParamDescription?: string;
-    children: React.ReactNode;
+    children: React$1.ReactNode;
 }
 /**
  * A `<select>` element enhanced with WebMCP declarative attributes.
@@ -364,9 +371,9 @@ interface WebMCPSelectProps extends React.SelectHTMLAttributes<HTMLSelectElement
  * </WebMCPSelect>
  * ```
  */
-declare const WebMCPSelect: React.ForwardRefExoticComponent<WebMCPSelectProps & React.RefAttributes<HTMLSelectElement>>;
+declare const WebMCPSelect: React$1.ForwardRefExoticComponent<WebMCPSelectProps & React$1.RefAttributes<HTMLSelectElement>>;
 
-interface WebMCPTextareaProps extends React.TextareaHTMLAttributes<HTMLTextAreaElement> {
+interface WebMCPTextareaProps extends React$1.TextareaHTMLAttributes<HTMLTextAreaElement> {
     /** Maps to the `toolparamtitle` attribute (overrides the JSON Schema property key). */
     toolParamTitle?: string;
     /** Maps to the `toolparamdescription` attribute (describes this parameter to agents). */
@@ -386,7 +393,7 @@ interface WebMCPTextareaProps extends React.TextareaHTMLAttributes<HTMLTextAreaE
  * />
  * ```
  */
-declare const WebMCPTextarea: React.ForwardRefExoticComponent<WebMCPTextareaProps & React.RefAttributes<HTMLTextAreaElement>>;
+declare const WebMCPTextarea: React$1.ForwardRefExoticComponent<WebMCPTextareaProps & React$1.RefAttributes<HTMLTextAreaElement>>;
 
 interface WebMCPContextValue {
     /** Whether navigator.modelContext is available in this browser. */
@@ -412,7 +419,7 @@ interface WebMCPContextValue {
  * ```
  */
 declare function WebMCPProvider({ children }: {
-    children: React.ReactNode;
+    children: React$1.ReactNode;
 }): react_jsx_runtime.JSX.Element;
 /**
  * Returns the current WebMCP availability status.
@@ -445,4 +452,284 @@ declare function isWebMCPAvailable(): boolean;
  */
 declare function isWebMCPTestingAvailable(): boolean;
 
-export { type JSONSchema, type JSONSchemaProperty, type ModelContext, type ModelContextTesting, type ToolActivatedEvent, type ToolAnnotations, type ToolCancelEvent, type ToolContent, type ToolContentJSON, type ToolContentText, type UseWebMCPToolConfig, type WebMCPContextConfig, WebMCPForm, type WebMCPFormProps, type WebMCPFormSubmitEvent, WebMCPInput, type WebMCPInputProps, WebMCPProvider, WebMCPSelect, type WebMCPSelectProps, WebMCPTextarea, type WebMCPTextareaProps, type WebMCPToolDefinition, getModelContext, isWebMCPAvailable, isWebMCPTestingAvailable, useToolEvent, useWebMCPContext, useWebMCPStatus, useWebMCPTool };
+/**
+ * Type definitions for the WebMCP adapter layer.
+ *
+ * These types support the runtime schema collector engine that enables
+ * third-party UI component libraries (e.g. Material UI) to work with
+ * the WebMCP tool registration API.
+ */
+/**
+ * Describes a single field (tool parameter) collected from React children,
+ * the `fields` prop, or via `useRegisterField`.
+ *
+ * @example
+ * ```ts
+ * const field: FieldDefinition = {
+ *   name: "email",
+ *   type: "email",
+ *   required: true,
+ *   description: "Recipient's email address",
+ * };
+ * ```
+ */
+interface FieldDefinition {
+    /** Field name — must be unique within a tool. */
+    name: string;
+    /** HTML input type (e.g. "text", "email", "number"). Defaults to "string". */
+    type?: string;
+    /** Whether the field is required. */
+    required?: boolean;
+    /** Human-readable title for agents. */
+    title?: string;
+    /** Human-readable description for agents. */
+    description?: string;
+    /** Minimum numeric value (maps to JSON Schema `minimum`). */
+    min?: number;
+    /** Maximum numeric value (maps to JSON Schema `maximum`). */
+    max?: number;
+    /** Minimum string length (maps to JSON Schema `minLength`). */
+    minLength?: number;
+    /** Maximum string length (maps to JSON Schema `maxLength`). */
+    maxLength?: number;
+    /** Regex pattern for string validation (maps to JSON Schema `pattern`). */
+    pattern?: string;
+    /** Allowed values — mapped to JSON Schema `enum`. */
+    enumValues?: (string | number | boolean)[];
+    /** Labelled options — mapped to JSON Schema `oneOf`. */
+    oneOf?: {
+        value: string | number | boolean;
+        label: string;
+    }[];
+}
+
+/**
+ * Props for the `WebMCP.Tool` component.
+ */
+interface WebMCPToolProps {
+    /** Unique tool name exposed to AI agents. */
+    name: string;
+    /** Human-readable description of what this tool does. */
+    description: string;
+    /** Handler called when an AI agent invokes this tool. */
+    onExecute: (input: Record<string, unknown>) => unknown | Promise<unknown>;
+    /** Optional field overrides / enrichment keyed by field name. */
+    fields?: Record<string, Partial<FieldDefinition>>;
+    /** When true, schema validation issues throw instead of warn. */
+    strict?: boolean;
+    /** If true, the tool auto-submits when filled by an agent. */
+    autoSubmit?: boolean;
+    /** Optional metadata hints for agents. */
+    annotations?: ToolAnnotations;
+    /** Called when a `toolactivated` event fires for this tool. */
+    onToolActivated?: (toolName: string) => void;
+    /** Called when a `toolcancel` event fires for this tool. */
+    onToolCancel?: (toolName: string) => void;
+    children: React$1.ReactNode;
+}
+/**
+ * Framework-agnostic tool wrapper that collects a JSON Schema from its
+ * React children and registers it as a WebMCP tool.
+ *
+ * Fields are auto-detected from child components (e.g. `<Input name="email" />`),
+ * enriched via the `fields` prop, and can be overridden by descendant
+ * components using `useRegisterField`.
+ *
+ * @example
+ * ```tsx
+ * <WebMCPTool
+ *   name="send_email"
+ *   description="Send an email to a user"
+ *   onExecute={async ({ email, priority }) => {
+ *     await sendEmail(email, priority);
+ *     return { content: [{ type: "text", text: "Sent!" }] };
+ *   }}
+ *   fields={{ email: { description: "Recipient's email" } }}
+ * >
+ *   <FormControl>
+ *     <Input name="email" type="email" required />
+ *   </FormControl>
+ * </WebMCPTool>
+ * ```
+ */
+declare function WebMCPTool({ name, description, onExecute, fields: fieldsProp, strict, autoSubmit, annotations, onToolActivated, onToolCancel, children, }: WebMCPToolProps): react_jsx_runtime.JSX.Element;
+declare namespace WebMCPTool {
+    var displayName: string;
+}
+
+/**
+ * Props for the `WebMCP.Field` component.
+ */
+interface WebMCPFieldProps extends Omit<FieldDefinition, "name"> {
+    /** Field name — must be unique within the parent `WebMCP.Tool`. */
+    name: string;
+    children: React$1.ReactNode;
+}
+/**
+ * Zero-UI wrapper that registers a field with the nearest `WebMCP.Tool`.
+ *
+ * Use this as an escape hatch for custom components that cannot be
+ * auto-detected by the children traversal engine. Enum values are
+ * automatically detected from children that have a `value` prop
+ * (e.g. `<MenuItem value="low">Low</MenuItem>`).
+ *
+ * Renders a React Fragment — no extra DOM elements are introduced.
+ *
+ * @example
+ * ```tsx
+ * <WebMCP.Field name="priority" description="Email priority">
+ *   <Select>
+ *     <MenuItem value="low">Low</MenuItem>
+ *     <MenuItem value="high">High</MenuItem>
+ *   </Select>
+ * </WebMCP.Field>
+ * ```
+ */
+declare function WebMCPField({ children, name, ...rest }: WebMCPFieldProps): react_jsx_runtime.JSX.Element;
+declare namespace WebMCPField {
+    var displayName: string;
+}
+
+/**
+ * Register a field definition with the nearest `WebMCP.Tool` ancestor.
+ *
+ * Uses `useEffect` (SSR-safe) so registration only happens on the client.
+ * The field is automatically unregistered on unmount. Re-registration
+ * only occurs when the field definition changes (compared by fingerprint).
+ *
+ * If no `WebMCP.Tool` ancestor exists, a dev-mode warning is logged.
+ *
+ * @example
+ * ```tsx
+ * function MyField() {
+ *   useRegisterField({ name: "email", type: "email", required: true });
+ *   return <input name="email" type="email" required />;
+ * }
+ * ```
+ */
+declare function useRegisterField(field: FieldDefinition): void;
+
+interface UseSchemaCollectorOptions {
+    /** React children to traverse for auto-detected fields. */
+    children: React.ReactNode;
+    /** Optional field overrides keyed by field name. */
+    fields?: Record<string, Partial<FieldDefinition>>;
+    /** When true, validation issues throw instead of warn. */
+    strict?: boolean;
+}
+/**
+ * Core engine hook that collects field definitions from three sources,
+ * merges them, validates in dev, and builds a deterministic JSON Schema.
+ *
+ * **Sources** (lowest to highest priority):
+ * 1. Children traversal (auto-detected from React tree)
+ * 2. `fields` prop (enrichment / override)
+ * 3. Context-registered fields (via `useRegisterField`)
+ *
+ * @example
+ * ```tsx
+ * const { schema, registerField, unregisterField } = useSchemaCollector({
+ *   children,
+ *   fields: { email: { description: "Recipient" } },
+ * });
+ * ```
+ */
+declare function useSchemaCollector({ children, fields: fieldsProp, strict, }: UseSchemaCollectorOptions): {
+    schema: JSONSchema;
+    registerField: (field: FieldDefinition) => void;
+    unregisterField: (name: string) => void;
+};
+
+/**
+ * Recursively extract option values from React children.
+ *
+ * Detects elements that have a `value` prop (e.g. `<MenuItem value="low">Low</MenuItem>`)
+ * and collects `{ value, label }` pairs. The label is derived from string children
+ * or falls back to `String(value)`.
+ *
+ * @example
+ * ```tsx
+ * const options = extractOptions(
+ *   <>
+ *     <MenuItem value="low">Low</MenuItem>
+ *     <MenuItem value="high">High</MenuItem>
+ *   </>
+ * );
+ * // [{ value: "low", label: "Low" }, { value: "high", label: "High" }]
+ * ```
+ */
+declare function extractOptions(children: React$1.ReactNode): {
+    value: string | number | boolean;
+    label: string;
+}[];
+/**
+ * Recursively extract field definitions from a React children tree.
+ *
+ * Walks the tree using `React.Children.toArray` (safe, pure traversal).
+ * Detects field names from `props.name`, `props.inputProps.name`, or
+ * `props.slotProps.input.name`. When a named element is found, it builds
+ * a `FieldDefinition` from its props and auto-detects enum values from
+ * its children. Elements without a name are recursed into.
+ *
+ * @example
+ * ```tsx
+ * const fields = extractFields(
+ *   <>
+ *     <Input name="email" type="email" required />
+ *     <Select name="priority">
+ *       <MenuItem value="low">Low</MenuItem>
+ *       <MenuItem value="high">High</MenuItem>
+ *     </Select>
+ *   </>
+ * );
+ * ```
+ */
+declare function extractFields(children: React$1.ReactNode): FieldDefinition[];
+
+/**
+ * Build a deterministic JSON Schema from an array of field definitions.
+ *
+ * Property names are sorted alphabetically and the `required` array is
+ * also sorted, ensuring identical output regardless of field insertion
+ * order.
+ *
+ * @example
+ * ```ts
+ * const schema = buildInputSchema([
+ *   { name: "email", type: "email", required: true },
+ *   { name: "age", type: "number", min: 0, max: 120 },
+ * ]);
+ * ```
+ */
+declare function buildInputSchema(fields: FieldDefinition[]): JSONSchema;
+
+/**
+ * Validate an array of field definitions for common schema issues.
+ *
+ * In production this is a no-op. In development it checks for:
+ * - Duplicate field names
+ * - `pattern` used on non-string types
+ * - `min`/`max` used on non-number types
+ * - `minLength`/`maxLength` used on non-string types
+ * - Enum values whose types don't match the declared field type
+ *
+ * By default warnings are logged via `console.warn` with the
+ * `[react-webmcp]` prefix. When `strict` is `true`, an `Error` is
+ * thrown instead.
+ *
+ * @example
+ * ```ts
+ * validateSchema(fields); // warns in dev
+ * validateSchema(fields, { strict: true }); // throws in dev
+ * ```
+ */
+declare function validateSchema(fields: FieldDefinition[], options?: {
+    strict?: boolean;
+}): void;
+
+declare const WebMCP: {
+    readonly Tool: typeof WebMCPTool;
+    readonly Field: typeof WebMCPField;
+};
+
+export { type FieldDefinition, type JSONSchema, type JSONSchemaProperty, type ModelContext, type ModelContextTesting, type ToolActivatedEvent, type ToolAnnotations, type ToolCancelEvent, type ToolContent, type ToolContentJSON, type ToolContentText, type UseWebMCPToolConfig, WebMCP, type WebMCPContextConfig, WebMCPField, type WebMCPFieldProps, WebMCPForm, type WebMCPFormProps, type WebMCPFormSubmitEvent, WebMCPInput, type WebMCPInputProps, WebMCPProvider, WebMCPSelect, type WebMCPSelectProps, WebMCPTextarea, type WebMCPTextareaProps, WebMCPTool, type WebMCPToolDefinition, type WebMCPToolProps, buildInputSchema, extractFields, extractOptions, getModelContext, isWebMCPAvailable, isWebMCPTestingAvailable, useRegisterField, useSchemaCollector, useToolEvent, useWebMCPContext, useWebMCPStatus, useWebMCPTool, validateSchema };