TypeScript Types

interface CopilotChatProps {
  /** Custom instructions for the system message */
  instructions?: string;

  /** Suggestion behavior: "auto" (AI-generated), "manual" (programmatic), or static array */
  suggestions?: ChatSuggestions;

  /** Callback when generation state changes */
  onInProgress?: (inProgress: boolean) => void;

  /** Callback when user submits a message */
  onSubmitMessage?: (message: string) => void | Promise<void>;

  /** Custom stop generation handler */
  onStopGeneration?: OnStopGeneration;

  /** Custom reload/regenerate handler */
  onReloadMessages?: OnReloadMessages;

  /** Callback when message is regenerated */
  onRegenerate?: (messageId: string) => void;

  /** Callback when message is copied to clipboard */
  onCopy?: (message: string) => void;

  /** Callback for positive feedback */
  onThumbsUp?: (message: Message) => void;

  /** Callback for negative feedback */
  onThumbsDown?: (message: Message) => void;

  /** Custom markdown component renderers */
  markdownTagRenderers?: ComponentsMap;

  /** Custom icon overrides */
  icons?: CopilotChatIcons;

  /** Custom label/text overrides */
  labels?: CopilotChatLabels;

  /** Enable image upload functionality */
  imageUploadsEnabled?: boolean;

  /** File input accept attribute (default: "image/*") */
  inputFileAccept?: string;

  /** Override system message generation */
  makeSystemMessage?: SystemMessageFunction;

  /** Disable system message entirely */
  disableSystemMessage?: boolean;

  /** Custom assistant message component */
  AssistantMessage?: React.ComponentType<AssistantMessageProps>;

  /** Custom user message component */
  UserMessage?: React.ComponentType<UserMessageProps>;

  /** Custom error message component */
  ErrorMessage?: React.ComponentType<ErrorMessageProps>;

  /** Custom messages container component */
  Messages?: React.ComponentType<MessagesProps>;

  /** Custom message renderer */
  RenderMessage?: React.ComponentType<RenderMessageProps>;

  /** Custom suggestions list renderer */
  RenderSuggestionsList?: React.ComponentType<RenderSuggestionsListProps>;

  /** Custom input component */
  Input?: React.ComponentType<InputProps>;

  /** Custom image renderer */
  ImageRenderer?: React.ComponentType<ImageRendererProps>;

  /** Additional CSS class */
  className?: string;

  /** Child elements */
  children?: React.ReactNode;

  /** Hide the stop generation button */
  hideStopButton?: boolean;

  /** Event tracking hooks (requires publicApiKey in CopilotKit provider) */
  observabilityHooks?: CopilotObservabilityHooks;

  /** Custom error renderer */
  renderError?: (error: {
    message: string;
    operation?: string;
    timestamp: number;
    onDismiss: () => void;
    onRetry?: () => void;
  }) => React.ReactNode;

  /** Error handler for debugging */
  onError?: CopilotErrorHandler;
}

interface CopilotModalProps extends CopilotChatProps {
  /** Whether popup is open by default (default: false) */
  defaultOpen?: boolean;

  /** Close popup when clicking outside (default: true) */
  clickOutsideToClose?: boolean;

  /** Close popup when pressing Escape (default: true) */
  hitEscapeToClose?: boolean;

  /** Keyboard shortcut to toggle popup (default: "/") */
  shortcut?: string;

  /** Callback when open state changes */
  onSetOpen?: (open: boolean) => void;

  /** Custom window/modal component */
  Window?: React.ComponentType<WindowProps>;

  /** Custom toggle button component */
  Button?: React.ComponentType<ButtonProps>;

  /** Custom header component */
  Header?: React.ComponentType<HeaderProps>;
}

type CopilotErrorHandler = (error: Error) => void;

type SystemMessageFunction = (args: {
  instructions?: string;
}) => string;

type ChatSuggestions = "auto" | "manual" | SuggestionItem[];

interface SuggestionItem {
  /** Suggestion title/text displayed to user */
  title: string;

  /** Message to send when suggestion is clicked */
  message: string;

  /** Whether suggestion is still being generated */
  partial?: boolean;

  /** Optional CSS class */
  className?: string;
}

interface CopilotChatSuggestion {
  /** Suggestion title/text displayed to user */
  title: string;

  /** Message to send when suggestion is clicked */
  message: string;

  /** Whether suggestion is still being generated */
  partial?: boolean;

  /** Optional CSS class */
  className?: string;
}

interface UseCopilotChatSuggestionsConfiguration {
  /** Instructions for GPT to generate relevant suggestions */
  instructions: string;

  /** Minimum number of suggestions to generate (default: 1) */
  minSuggestions?: number;

  /** Maximum number of suggestions to generate (default: 3) */
  maxSuggestions?: number;

  /** Whether suggestions are available (default: "enabled") */
  available?: "enabled" | "disabled";

  /** Optional CSS class for suggestions container */
  className?: string;
}

type Message = AIMessage | UserMessage;

interface AIMessage {
  id: string;
  role: "assistant";
  content: string;
  generativeUI?: () => React.ReactNode;
  agentName?: string;
  state?: any;
  image?: ImageData;
}

interface UserMessage {
  id: string;
  role: "user";
  content: string;
  image?: ImageData;
}

interface ImageData {
  /** Image format (e.g., "png", "jpeg", "gif") */
  format: string;

  /** Base64-encoded image bytes */
  bytes: string;
}

/**
 * Note: ImageData is imported from @copilotkit/shared, not defined locally.
 * It's re-exported from @copilotkit/react-ui for convenience.
 */

interface ChatError {
  /** Error message text */
  message: string;

  /** Operation that caused the error */
  operation?: string;

  /** Error timestamp */
  timestamp: number;
}

interface AssistantMessageProps {
  /** The AI message content */
  message?: AIMessage;

  /** Whether this is the most recent message */
  isCurrentMessage?: boolean;

  /** Whether response is loading (thinking state) */
  isLoading: boolean;

  /** Whether response is actively streaming */
  isGenerating: boolean;

  /** Callback to regenerate this message */
  onRegenerate?: () => void;

  /** Callback when message is copied */
  onCopy?: (message: string) => void;

  /** Callback for positive feedback */
  onThumbsUp?: (message: Message) => void;

  /** Callback for negative feedback */
  onThumbsDown?: (message: Message) => void;

  /** Custom markdown component renderers */
  markdownTagRenderers?: ComponentsMap;

  /** Custom image renderer component */
  ImageRenderer?: React.ComponentType<ImageRendererProps>;

  /**
   * @deprecated Use message property instead
   * Note: Despite being deprecated, this property is currently REQUIRED
   */
  rawData: any;

  /** @deprecated Use message.generativeUI() instead */
  subComponent?: React.JSX.Element;
}

interface UserMessageProps {
  /** The user message content */
  message?: UserMessage;

  /** Image renderer component for displaying attachments */
  ImageRenderer: React.ComponentType<ImageRendererProps>;

  /**
   * @deprecated Use message property instead
   * Note: Despite being deprecated, this property is currently REQUIRED
   */
  rawData: any;
}

interface ErrorMessageProps {
  /** Error information */
  error: ChatError;

  /** Whether this is the most recent message */
  isCurrentMessage?: boolean;

  /** Callback to regenerate/retry */
  onRegenerate?: () => void;

  /** Callback when error is copied */
  onCopy?: (message: string) => void;
}

interface ImageRendererProps {
  /** Image data with format and encoded bytes */
  image: ImageData;

  /** Optional text content to display with image */
  content?: string;

  /** Additional CSS class */
  className?: string;
}

interface RenderMessageProps {
  /** The message to render */
  message: Message;

  /** Whether chat is currently in progress */
  inProgress: boolean;

  /** Message index in the array */
  index: number;

  /** Whether this is the most recent message */
  isCurrentMessage: boolean;

  /** Result from action execution if applicable */
  actionResult?: string;

  /** Assistant message component to use */
  AssistantMessage?: React.ComponentType<AssistantMessageProps>;

  /** User message component to use */
  UserMessage?: React.ComponentType<UserMessageProps>;

  /** Image renderer component to use */
  ImageRenderer?: React.ComponentType<ImageRendererProps>;

  /** Callback to regenerate message */
  onRegenerate?: (messageId: string) => void;

  /** Callback when message is copied */
  onCopy?: (message: string) => void;

  /** Callback for positive feedback */
  onThumbsUp?: (message: Message) => void;

  /** Callback for negative feedback */
  onThumbsDown?: (message: Message) => void;

  /** Custom markdown renderers */
  markdownTagRenderers?: ComponentsMap;
}

interface RenderSuggestionsListProps {
  /** Array of suggestion items */
  suggestions: CopilotChatSuggestion[];

  /** Click handler for suggestions */
  onSuggestionClick: (message: string) => void;
}

interface MessagesProps {
  /** Array of all messages */
  messages: Message[];

  /** Whether chat is in progress */
  inProgress: boolean;

  /** Child elements (typically suggestions) */
  children?: React.ReactNode;

  /** Current chat error if any */
  chatError?: ChatError | null;

  /** Assistant message component */
  AssistantMessage: React.ComponentType<AssistantMessageProps>;

  /** User message component */
  UserMessage: React.ComponentType<UserMessageProps>;

  /** Error message component */
  ErrorMessage?: React.ComponentType<ErrorMessageProps>;

  /** Message renderer */
  RenderMessage: React.ComponentType<RenderMessageProps>;

  /** Image renderer */
  ImageRenderer: React.ComponentType<ImageRendererProps>;

  /** Regenerate callback */
  onRegenerate?: (messageId: string) => void;

  /** Copy callback */
  onCopy?: (message: string) => void;

  /** Thumbs up callback */
  onThumbsUp?: (message: Message) => void;

  /** Thumbs down callback */
  onThumbsDown?: (message: Message) => void;

  /** Custom markdown renderers */
  markdownTagRenderers?: ComponentsMap;
}

interface InputProps {
  /** Whether chat is in progress */
  inProgress: boolean;

  /** Handler for sending messages */
  onSend: (text: string) => Promise<Message>;

  /** Whether input is visible */
  isVisible?: boolean;

  /** Stop generation handler */
  onStop?: () => void;

  /** Upload handler (file picker trigger) */
  onUpload?: () => void;

  /** Hide stop button */
  hideStopButton?: boolean;
}

interface WindowProps {
  clickOutsideToClose: boolean;
  hitEscapeToClose: boolean;
  shortcut: string;
  children?: React.ReactNode;
}

interface ButtonProps {
  // Can be extended with custom props
}

interface HeaderProps {
  // Can be extended with custom props
}

interface SuggestionsProps {
  /** Suggestion title to display */
  title: string;

  /** Message to send when clicked */
  message: string;

  /** Whether suggestion is still loading */
  partial?: boolean;

  /** Optional CSS class */
  className?: string;

  /** Click handler */
  onClick: (message: string) => void;
}

type ComponentsMap<T extends Record<string, object> = Record<string, object>> = {
  [K in keyof T]: React.FC<{ children?: React.ReactNode } & T[K]>;
};

interface CopilotChatIcons {
  /** Icon for opening the chat (popup/sidebar button) */
  openIcon?: React.ReactNode;

  /** Icon for closing the chat (popup/sidebar button) */
  closeIcon?: React.ReactNode;

  /** Icon for header close button */
  headerCloseIcon?: React.ReactNode;

  /** Icon for send message button */
  sendIcon?: React.ReactNode;

  /** Icon for activity/loading indicator */
  activityIcon?: React.ReactNode;

  /** Spinner icon for loading states */
  spinnerIcon?: React.ReactNode;

  /** Icon for stop generation button */
  stopIcon?: React.ReactNode;

  /** Icon for regenerate response button */
  regenerateIcon?: React.ReactNode;

  /** Icon for push-to-talk microphone button */
  pushToTalkIcon?: React.ReactNode;

  /** Icon for copy to clipboard button */
  copyIcon?: React.ReactNode;

  /** Icon for positive feedback button */
  thumbsUpIcon?: React.ReactNode;

  /** Icon for negative feedback button */
  thumbsDownIcon?: React.ReactNode;

  /** Icon for upload/attach file button */
  uploadIcon?: React.ReactNode;
}

interface CopilotChatLabels {
  /** Initial message(s) displayed when chat starts - string or array of strings */
  initial?: string | string[];

  /** Chat header title (default: "CopilotKit") */
  title?: string;

  /** Input field placeholder (default: "Type a message...") */
  placeholder?: string;

  /** Error message text (default: "❌ An error occurred. Please try again.") */
  error?: string;

  /** Stop button label (default: "Stop generating") */
  stopGenerating?: string;

  /** Regenerate button label (default: "Regenerate response") */
  regenerateResponse?: string;

  /** Copy button label (default: "Copy to clipboard") */
  copyToClipboard?: string;

  /** Thumbs up button label (default: "Thumbs up") */
  thumbsUp?: string;

  /** Thumbs down button label (default: "Thumbs down") */
  thumbsDown?: string;

  /** Copied confirmation text (default: "Copied!") */
  copied?: string;
}

interface CopilotKitCSSProperties extends React.CSSProperties {
  /** Primary brand color */
  "--copilot-kit-primary-color"?: string;

  /** Contrast color for primary (text on primary background) */
  "--copilot-kit-contrast-color"?: string;

  /** Background color for chat panel */
  "--copilot-kit-background-color"?: string;

  /** Background color for input field */
  "--copilot-kit-input-background-color"?: string;

  /** Secondary UI color */
  "--copilot-kit-secondary-color"?: string;

  /** Contrast color for secondary (text on secondary background) */
  "--copilot-kit-secondary-contrast-color"?: string;

  /** Color for separators and borders */
  "--copilot-kit-separator-color"?: string;

  /** Color for muted/secondary text */
  "--copilot-kit-muted-color"?: string;

  /** Error background color */
  "--copilot-kit-error-background"?: string;

  /** Error border color */
  "--copilot-kit-error-border"?: string;

  /** Error text color */
  "--copilot-kit-error-text"?: string;

  /** Small shadow for subtle elevation */
  "--copilot-kit-shadow-sm"?: string;

  /** Medium shadow for moderate elevation */
  "--copilot-kit-shadow-md"?: string;

  /** Large shadow for prominent elevation */
  "--copilot-kit-shadow-lg"?: string;

  /** Dev console background color */
  "--copilot-kit-dev-console-bg"?: string;

  /** Dev console text color */
  "--copilot-kit-dev-console-text"?: string;
}

interface CopilotObservabilityHooks {
  /** Called when user sends a message */
  onMessageSent?: (message: string) => void;

  /** Called when chat is closed/minimized */
  onChatMinimized?: () => void;

  /** Called when chat is opened/expanded */
  onChatExpanded?: () => void;

  /** Called when message is regenerated */
  onMessageRegenerated?: (messageId: string) => void;

  /** Called when message is copied to clipboard */
  onMessageCopied?: (content: string) => void;

  /** Called when user provides feedback */
  onFeedbackGiven?: (messageId: string, type: "thumbsUp" | "thumbsDown") => void;

  /** Called when generation starts */
  onChatStarted?: () => void;

  /** Called when generation stops */
  onChatStopped?: () => void;

  /** Called on errors */
  onError?: (errorEvent: CopilotErrorEvent) => void;
}

interface CopilotErrorEvent {
  /** The error object */
  error: Error;

  /** Optional context about where the error occurred */
  context?: string;
}

type OnStopGeneration = (args: OnStopGenerationArguments) => void;

interface OnStopGenerationArguments {
  /** Currently executing agent name */
  currentAgentName: string | undefined;

  /** Current message array */
  messages: Message[];

  /** Function to update messages */
  setMessages: (messages: Message[]) => void;

  /** Default stop generation function */
  stopGeneration: () => void;

  /** Restart the current agent */
  restartCurrentAgent: () => void;

  /** Stop the current agent */
  stopCurrentAgent: () => void;

  /** Run the current agent with optional hint */
  runCurrentAgent: (hint?: HintFunction) => Promise<void>;

  /** Set agent state */
  setCurrentAgentState: (state: any) => void;
}

type OnReloadMessages = (args: OnReloadMessagesArguments) => void;

interface OnReloadMessagesArguments extends OnStopGenerationArguments {
  /** ID of message to regenerate */
  messageId: string;
}

type HintFunction = () => string | Promise<string>;

interface ChatContext {
  /** All label overrides with defaults applied */
  labels: Required<CopilotChatLabels>;

  /** All icon overrides with defaults applied */
  icons: Required<CopilotChatIcons>;

  /** Whether chat is currently open (for popup/sidebar) */
  open: boolean;

  /** Function to set open state */
  setOpen: (open: boolean) => void;
}

interface CopilotKitVersion {
  /** Current installed version */
  current: string;

  /** Latest available version */
  latest: string;

  /** Update urgency level */
  severity: "low" | "medium" | "high";

  /** Optional advisory message */
  advisory: string | null;

  /** Timestamp of last version check */
  lastChecked: number;
}

/**
 * @deprecated Use RenderMessage prop instead
 * Legacy render props from earlier versions
 */
interface LegacyRenderMessageProps {
  RenderTextMessage?: React.ComponentType<any>;
  RenderActionExecutionMessage?: React.ComponentType<any>;
  RenderAgentStateMessage?: React.ComponentType<any>;
  RenderResultMessage?: React.ComponentType<any>;
  RenderImageMessage?: React.ComponentType<any>;
}

/**
 * Generic type for mapping element names to React components
 * Used for markdown renderers and other extensible component maps
 */
type ComponentsMap<T extends Record<string, object> = Record<string, object>> = {
  [K in keyof T]: React.FC<{ children?: React.ReactNode } & T[K]>;
};

/**
 * Make all properties in T required
 */
type Required<T> = {
  [P in keyof T]-?: T[P];
};

/**
 * Simple renderer interface with content property
 * Used for basic content rendering scenarios
 */
interface Renderer {
  content: string;
}

/**
 * Type for image upload data structure
 * Contains the image content type and base64-encoded bytes
 */
type ImageUpload = {
  /** MIME type of the image (e.g., "image/png", "image/jpeg") */
  contentType: string;
  /** Base64-encoded image bytes */
  bytes: string;
};

// Import UI component types from react-ui
import type {
  // Component props
  CopilotChatProps,
  CopilotModalProps,
  AssistantMessageProps,
  UserMessageProps,
  ErrorMessageProps,
  ImageRendererProps,
  RenderMessageProps,
  RenderSuggestionsListProps,
  MessagesProps,
  InputProps,
  WindowProps,
  ButtonProps,
  HeaderProps,

  // Customization
  CopilotChatIcons,
  CopilotChatLabels,
  CopilotKitCSSProperties,
  ComponentsMap,

  // Messages
  ChatError,

  // Utilities
  Renderer,
  ImageUpload,
  SuggestionsProps,

  // Suggestions
  ChatSuggestions,
  CopilotChatSuggestion,
  UseCopilotChatSuggestionsConfiguration,

  // Handlers
  OnStopGeneration, // Exported - can be used for type annotations
  OnReloadMessages, // Exported - can be used for type annotations
  // OnStopGenerationArguments, // Not exported - internal argument type
  // OnReloadMessagesArguments, // Not exported - internal argument type
  CopilotErrorHandler,

  // Observability
  CopilotObservabilityHooks,

  // Context
  ChatContext,

  // Dev console types are internal and not exported
  // CopilotKitVersion, // Not exported
} from "@copilotkit/react-ui";

// Import core domain types from shared package
import type {
  Message,
  AIMessage,
  UserMessage,
  ImageData,
  CopilotErrorEvent,
} from "@copilotkit/shared";

// Import from react-core if needed
import type {
  SuggestionItem,
  SystemMessageFunction,
  HintFunction,
} from "@copilotkit/react-core";