/**
 * @license
 *-------------------------------------------------------------------------------------------
 * Copyright © 2026 Progress Software Corporation. All rights reserved.
 * Licensed under commercial license. See LICENSE.md in the package root for more information
 *-------------------------------------------------------------------------------------------
 */
/**
 * WebMcpProvider – Generic React Context Provider for Web MCP configuration.
 *
 * Wraps a section of the component tree so that any KendoReact component
 * (Grid, Form, Scheduler, etc.) inside it automatically registers
 * browser-native AI agent tools via `document.modelContext.registerTool()`.
 *
 * Lives in `@progress/kendo-react-common` so every component package can
 * consume the context without cross-package imports.
 *
 * @example
 * ```tsx
 * import { WebMcpProvider } from '@progress/kendo-react-common';
 *
 * <WebMcpProvider>
 *     <Grid data={dataResult} sortable webMcp={{ dataName: 'employees' }} />
 * </WebMcpProvider>
 * ```
 */
import * as React from 'react';
/** @internal Result returned by a registered Web MCP tool. */
export interface WebMcpToolResult {
    content: Array<{
        type: 'text';
        text: string;
    }>;
    isError?: boolean;
}
/** @internal Handle returned by `document.modelContext.registerTool()`. */
export interface WebMcpToolRegistration {
    unregister: () => void;
}
/** @internal The `document.modelContext` surface. */
export interface WebMcpModelContext {
    registerTool: (config: {
        name: string;
        description: string;
        inputSchema: Record<string, unknown>;
        execute: (args: Record<string, unknown>) => Promise<WebMcpToolResult>;
    }) => WebMcpToolRegistration;
}
/** Describes a single tool to register via WebMcpProvider. */
export interface McpToolOption {
    /** Short identifier used as suffix in the tool name. */
    name: string;
    /** Human-readable description shown to AI agents. */
    description: string;
    /** Internal command identifier used by the component's execution router. */
    commandType: string;
    /** Whether this tool should be registered (typically derived from component props). */
    enabled: boolean;
    /** Optional JSON Schema for the tool's input parameters. */
    inputSchema?: Record<string, unknown>;
    /** Optional custom execute function. When provided, bypasses the adapter's built-in command router. */
    execute?: (args: Record<string, unknown>) => Promise<{
        content: Array<{
            type: string;
            text: string;
        }>;
        isError?: boolean;
    }> | {
        content: Array<{
            type: string;
            text: string;
        }>;
        isError?: boolean;
    };
}
/** Configuration object for the `webMcp` prop on individual components. */
export interface WebMcpProps {
    /** Human-readable data name exposed to AI agents. Overrides the provider's `dataName`. */
    dataName?: string;
    /** Optional callback to filter or customise the tools before registration. */
    tools?: (tools: McpToolOption[]) => McpToolOption[];
}
/** Shared Web MCP configuration propagated via React Context. */
export interface WebMcpContextValue {
    /** Human-readable data name exposed to AI agents. Any language works. Optional when each component provides its own via `webMcp={{ dataName }}`. */
    dataName?: string;
    /**
     * Registration callback provided by a smart provider.
     * Components call this to announce themselves so the provider can
     * create tools on their behalf. Returns an unregister function.
     *
     * @param componentType - Identifier string, e.g. 'textbox', 'grid'.
     * @param handle        - The imperative handle exposed via forwardRef.
     * @param props         - The current React props of the component.
     * @param webMcpConfig  - Component-level webMcp config (when object), or undefined (when boolean).
     * @returns A cleanup function that removes the registration.
     */
    register?: (componentType: string, handle: unknown, propsRef: {
        current: unknown;
    }, webMcpConfig?: Record<string, unknown>) => () => void;
}
/** Props accepted by `<WebMcpProvider>`. */
export interface WebMcpProviderProps extends WebMcpContextValue {
    children: React.ReactNode;
}
/** @internal */
export declare const WebMcpContext: React.Context<WebMcpContextValue | null>;
/** Provides Web MCP configuration to all descendant KendoReact components. */
export declare const WebMcpProvider: React.FC<WebMcpProviderProps>;
/** Returns the `document.modelContext` if available, or `null`. */
export declare function getModelContext(): WebMcpModelContext | null;
/**
 * Tiny hook that components call to register themselves with a parent
 * `WebMcpProvider`. Only runs when `webMcp` is truthy — zero cost otherwise.
 *
 * The component package only needs this single call — all tool creation
 * logic lives in the provider's adapter (in `@progress/kendo-react-webmcp`).
 *
 * @param componentType - Identifier string, e.g. 'textbox', 'grid'.
 * @param handle        - Ref to the component's imperative handle.
 * @param props         - The current React props.
 * @param webMcp        - The component's `webMcp` prop. `true` for defaults, object for config.
 */
export declare function useWebMcpRegister(componentType: string, handle: React.RefObject<unknown>, props: unknown, webMcp?: boolean | WebMcpProps | Record<string, unknown>): void;