@restnfeel/agentc-starter-kit/src/lib/chatbot/types/components.ts

한국어 기업용 CMS 모듈 - Task Master AI와 함께 빠르게 웹사이트를 구현할 수 있는 재사용 가능한 컴포넌트 시스템

/**
 * @fileoverview Component props type definitions for the RAG chatbot system
 * @module types/components
 */

import type { ReactNode } from "react";
import type { ChatbotError, ConversationMessage, Document } from "./index";

/**
 * Base props for all chatbot components
 */
export interface BaseChatbotProps {
  /** CSS class name for custom styling */
  className?: string;
  /** Whether the component is disabled */
  disabled?: boolean;
  /** Loading state */
  loading?: boolean;
  /** Error handler callback */
  onError?: (error: ChatbotError) => void;
}

/**
 * Props for the ChatbotProvider component
 */
export interface ChatbotProviderProps {
  /** Child components */
  children: ReactNode;
  /** Chatbot configuration */
  config?: {
    /** Vector store configuration */
    vectorStore?: {
      type: "supabase" | "qdrant" | "pinecone";
      url: string;
      apiKey: string;
      collection?: string;
    };
    /** LLM configuration */
    llm?: {
      provider: "openai" | "anthropic" | "google" | "mistral";
      apiKey: string;
      model: string;
      temperature?: number;
      maxTokens?: number;
    };
    /** Storage configuration */
    storage?: {
      type: "supabase" | "local";
      url?: string;
      apiKey?: string;
      bucket?: string;
    };
  };
  /** Auto-initialize on mount */
  autoInitialize?: boolean;
  /** Error boundary fallback */
  fallback?: ReactNode;
}

/**
 * Props for chat widget components
 */
export interface ChatWidgetProps extends BaseChatbotProps {
  /** Widget title */
  title?: string;
  /** Placeholder text for input */
  placeholder?: string;
  /** Welcome message */
  welcomeMessage?: string;
  /** Whether to show suggested questions */
  showSuggestedQuestions?: boolean;
  /** Whether to show conversation history */
  showHistory?: boolean;
  /** Maximum height of the widget */
  maxHeight?: string;
  /** Theme variant */
  variant?: "default" | "compact" | "minimal";
  /** Message sent callback */
  onMessageSent?: (message: string) => void;
  /** Response received callback */
  onResponseReceived?: (message: ConversationMessage) => void;
  /** Conversation started callback */
  onConversationStart?: (conversationId: string) => void;
  /** Conversation ended callback */
  onConversationEnd?: (conversationId: string) => void;
}

/**
 * Props for floating chat button
 */
export interface FloatingChatButtonProps extends BaseChatbotProps {
  /** Button position */
  position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
  /** Button size */
  size?: "sm" | "md" | "lg";
  /** Custom icon component */
  icon?: ReactNode;
  /** Button label for accessibility */
  label?: string;
  /** Whether the chat is open */
  isOpen?: boolean;
  /** Open/close handler */
  onToggle?: (isOpen: boolean) => void;
  /** Animation style */
  animation?: "bounce" | "fade" | "slide" | "none";
}

/**
 * Props for knowledge management components
 */
export interface KnowledgeManagementProps extends BaseChatbotProps {
  /** Whether to show upload interface */
  showUpload?: boolean;
  /** Whether to show document list */
  showDocuments?: boolean;
  /** Whether to show search interface */
  showSearch?: boolean;
  /** Maximum file size in bytes */
  maxFileSize?: number;
  /** Accepted file types */
  acceptedFileTypes?: string[];
  /** Document uploaded callback */
  onDocumentUploaded?: (document: Document) => void;
  /** Document deleted callback */
  onDocumentDeleted?: (documentId: string) => void;
  /** Document updated callback */
  onDocumentUpdated?: (document: Document) => void;
}

/**
 * Props for document uploader component
 */
export interface DocumentUploaderProps extends BaseChatbotProps {
  /** Whether to accept multiple files */
  multiple?: boolean;
  /** Maximum file size in bytes */
  maxFileSize?: number;
  /** Maximum number of files */
  maxFiles?: number;
  /** Accepted file types */
  accept?: string;
  /** Upload area height */
  height?: string;
  /** Show progress for uploads */
  showProgress?: boolean;
  /** Upload started callback */
  onUploadStart?: (files: File[]) => void;
  /** Upload progress callback */
  onUploadProgress?: (progress: number, file: File) => void;
  /** Upload completed callback */
  onUploadComplete?: (documents: Document[]) => void;
  /** Upload failed callback */
  onUploadError?: (error: Error, file: File) => void;
}

/**
 * Props for RAG manager component
 */
export interface RAGManagerProps extends BaseChatbotProps {
  /** Whether to show vector store status */
  showVectorStoreStatus?: boolean;
  /** Whether to show LLM configuration */
  showLLMConfig?: boolean;
  /** Whether to show storage status */
  showStorageStatus?: boolean;
  /** Whether to show system health */
  showSystemHealth?: boolean;
  /** Refresh interval for status updates in milliseconds */
  refreshInterval?: number;
  /** Configuration updated callback */
  onConfigUpdated?: (config: any) => void;
  /** System health changed callback */
  onHealthChanged?: (health: any) => void;
}

/**
 * Props for suggested questions component
 */
export interface SuggestedQuestionsProps extends BaseChatbotProps {
  /** List of suggested questions */
  questions?: string[];
  /** Maximum number of questions to show */
  maxQuestions?: number;
  /** Whether to show as buttons or list */
  variant?: "buttons" | "list" | "chips";
  /** Question clicked callback */
  onQuestionClick?: (question: string) => void;
  /** Whether to shuffle questions on each render */
  shuffle?: boolean;
  /** Category filter */
  category?: string;
}

/**
 * Props for theme configuration
 */
export interface ThemeProps {
  /** Theme name */
  theme?: "light" | "dark" | "auto" | "custom";
  /** Custom theme colors */
  colors?: {
    primary?: string;
    secondary?: string;
    background?: string;
    surface?: string;
    text?: string;
    textSecondary?: string;
    border?: string;
    error?: string;
    success?: string;
    warning?: string;
  };
  /** Custom fonts */
  fonts?: {
    primary?: string;
    mono?: string;
  };
  /** Border radius values */
  borderRadius?: {
    sm?: string;
    md?: string;
    lg?: string;
  };
  /** Shadow values */
  shadows?: {
    sm?: string;
    md?: string;
    lg?: string;
  };
}

/**
 * Props for internationalization
 */
export interface I18nProps {
  /** Current language code */
  language?: string;
  /** Available languages */
  languages?: Array<{
    code: string;
    name: string;
    flag?: string;
  }>;
  /** Custom translations */
  translations?: Record<string, Record<string, string>>;
  /** Language changed callback */
  onLanguageChange?: (language: string) => void;
  /** Text direction */
  direction?: "ltr" | "rtl";
}