import { FunctionType } from '../api/types';

/**
 * PairComponent Types
 *
 * PairComponents are React components that can be "paired" with the chatbot,
 * allowing the agent to interact with UI elements while users watch in real-time.
 */
/**
 * Field information for a form field in a PairComponent
 * Extended with rich metadata for both agent guidance and UI help
 */
export interface FieldInfo {
    /** Field identifier */
    name: string;
    /** Display label */
    label: string;
    /** Data type */
    type: "string" | "number" | "boolean" | "select" | "multiselect" | "date" | "file" | "array" | "object";
    /** Whether the field is required */
    required: boolean;
    /** Options for select/multiselect fields */
    options?: {
        value: string | number;
        label: string;
    }[];
    /** Description of what this field is for (helps both agent and users) */
    description?: string;
    /** Placeholder text shown in input */
    placeholder?: string;
    /** Example valid values (helps agent pick correct format) */
    examples?: string[];
    /** Expected format hint (e.g., "camelCase", "email", "url") */
    format?: string;
    /** Contextual hint for how to fill this field */
    hint?: string;
    /** Default value */
    defaultValue?: any;
    /** Validation rules */
    validation?: {
        pattern?: string;
        patternMessage?: string;
        min?: number;
        max?: number;
        minLength?: number;
        maxLength?: number;
    };
    /** Child fields for array/object types */
    children?: FieldInfo[];
    /** Group this field belongs to (for UI organization) */
    group?: string;
}
/**
 * Extended state with context for agent guidance
 */
export interface StateWithContext {
    /** Current field values */
    values: Record<string, any>;
    /** Field schema with descriptions, examples, hints */
    schema: FieldInfo[];
    /** Names of required fields that are not yet filled */
    missing: string[];
    /** Map of field name -> validation error message */
    invalid: Record<string, string>;
    /** Map of field name -> contextual suggestion based on current state */
    suggestions: Record<string, string>;
    /** Overall form readiness */
    ready: boolean;
}
/**
 * Validation result from a PairComponent
 */
export interface ValidationResult {
    valid: boolean;
    errors: Record<string, string>;
}
/**
 * Imperative handle for controlling a PairComponent from tools
 */
export interface PairComponentControl {
    /** Get current state of all fields */
    getState: () => Record<string, any>;
    /** Set a specific field value */
    setField: (field: string, value: any) => void;
    /** Get metadata about all available fields */
    getFields: () => FieldInfo[];
    /** Submit/save the form */
    submit: () => Promise<any>;
    /** Reset the form to initial state */
    reset: () => void;
    /** Validate all fields and return validation result */
    validate: () => ValidationResult;
    /** Focus a specific field */
    focusField?: (field: string) => void;
    /** Get component-specific actions (optional) */
    getActions?: () => string[];
    /** Execute a component-specific action (optional) */
    executeAction?: (action: string, args?: Record<string, any>) => Promise<any>;
    /**
     * Get field schema with rich metadata (descriptions, examples, hints)
     * This helps the agent understand what each field expects
     */
    getFieldSchema?: () => FieldInfo[];
    /**
     * Get current state WITH context for agent guidance
     * Returns values + schema + missing fields + validation errors + suggestions
     * This is the primary method agents should use to understand form state
     */
    getStateWithContext?: () => StateWithContext;
}
/**
 * Props passed to every PairComponent
 * Note: The controlRef is passed as an actual React ref via forwardRef, not as a prop
 */
export interface PairComponentProps {
    /** Callback when component is closed */
    onClose: () => void;
    /** Callback when operation succeeds */
    onSuccess: (result: any) => void;
    /** Callback when operation fails */
    onError: (error: Error) => void;
    /** Currently active/focused field (for visual highlighting) */
    activeField?: string;
    /** Initial data to populate the form */
    initialData?: Record<string, any>;
}
/**
 * Tool context available to PairComponent tools
 */
export interface PairComponentToolContext {
    /** Get control handle for the active component */
    getControl: () => PairComponentControl | null;
    /** Get current component state */
    getState: () => Record<string, any>;
    /** Set visual focus on a field */
    setActiveField: (field: string | undefined) => void;
    /** Component name */
    componentName: string;
}
/**
 * A tool that operates on a PairComponent
 */
export interface PairComponentTool {
    /** Tool name (used in tool calls) */
    name: string;
    /** Description for the agent */
    description: string;
    /** Input fields for the tool */
    inputFields: FunctionType["inputFields"];
    /** Output fields for the tool (optional) */
    outputFields?: FunctionType["outputFields"];
    /** Whether the tool runs synchronously */
    sync?: boolean;
    /** The tool implementation */
    handler: (args: Record<string, any>, context: PairComponentToolContext) => Promise<any> | any;
}
/**
 * A PairComponent definition
 */
export interface PairComponent {
    /** Unique identifier */
    name: string;
    /** Human-readable description (shown to user and agent) */
    description: string;
    /** Keywords for intent matching (helps agent identify when to use this component) */
    keywords: string[];
    /** The React component to render (must use forwardRef to expose PairComponentControl) */
    component: React.ForwardRefExoticComponent<PairComponentProps & React.RefAttributes<PairComponentControl>>;
    /** Tools available when this component is active */
    tools: PairComponentTool[];
    /** Default props to pass to the component */
    defaultProps?: Record<string, any>;
    /** Panel size when displayed */
    panelSize?: "sm" | "md" | "lg" | "xl";
    /** Optional icon for the component */
    icon?: React.ReactNode;
}
/**
 * State of the active PairComponent
 */
export interface ActivePairComponentState {
    /** The component definition */
    component: PairComponent;
    /** Current control reference */
    controlRef: React.RefObject<PairComponentControl>;
    /** Currently focused field */
    activeField?: string;
    /** Initial data passed to the component */
    initialData?: Record<string, any>;
    /** Whether the component is currently submitting */
    isSubmitting?: boolean;
    /** Last error from the component */
    lastError?: Error;
}
/**
 * Result from tool execution
 */
export interface ToolResult {
    success: boolean;
    data?: any;
    error?: string;
}
/**
 * Base tools available for all PairComponents
 */
export declare const BASE_PAIR_COMPONENT_TOOLS: readonly ["activateComponent", "deactivateComponent", "listPairComponents", "getComponentState"];
export type BasePairComponentToolName = typeof BASE_PAIR_COMPONENT_TOOLS[number];