xertica-ui 2.2.1 → 2.4.0

package/components/assistant/xertica-assistant/xertica-assistant.tsx

@@ -1,613 +1,611 @@
-import React from 'react';
-import { useAssistant } from './use-assistant';
-import { motion, AnimatePresence } from 'framer-motion';
-import { useTranslation } from 'react-i18next';
-import { ScrollArea } from '../../ui/scroll-area';
-import { ModernChatInput } from '../modern-chat-input';
-import { XerticaOrbe } from '../../brand/xertica-orbe';
-import { Button } from '../../ui/button';
-import { cn } from '../../shared/utils';
-
-// Sub-components
-import {
-  AssistantCollapsedView,
-  AssistantHeader,
-  AssistantTabBar,
-  AssistantWelcomeScreen,
-  AssistantMessageBubble,
-  AssistantTypingIndicator,
-  AssistantConversationList,
-  AssistantFeedbackDialog,
-  AssistantDocumentEditor,
-} from './parts';
-import type { EvaluationState } from './parts';
-
-// ============================================================================
-// TypeScript Interfaces & Types — imported from shared types.ts and re-exported
-// for backward compatibility with consumers that import from xertica-assistant.
-// ============================================================================
-import type {
-  MessageType,
-  AttachmentType,
-  SearchResultType,
-  AssistantMode,
-  AssistantTab,
-  SearchResult,
-  SearchSource,
-  SearchCommand,
-  Message,
-  Conversation,
-  Suggestion,
-  MockResponse,
-} from './types';
-
-export type {
-  MessageType,
-  AttachmentType,
-  SearchResultType,
-  AssistantMode,
-  AssistantTab,
-  SearchResult,
-  SearchSource,
-  SearchCommand,
-  Message,
-  Conversation,
-  Suggestion,
-  MockResponse,
-};
-
-// ============================================================================
-// Component Props
-// ============================================================================
-
-export interface XerticaAssistantProps {
-  /**
-   * Layout mode for the assistant panel
-   * @default 'expanded'
-   */
-  mode?: AssistantMode;
-
-  /**
-   * Whether the panel is expanded (only applies when `mode='expanded'`)
-   * @default true
-   */
-  isExpanded?: boolean;
-
-  /**
-   * Callback fired when the assistant panel is expanded or collapsed
-   */
-  onToggle?: () => void;
-
-  /**
-   * Initially selected tab
-   * @default 'chat'
-   */
-  defaultTab?: AssistantTab;
-
-  /**
-   * Enables demo mode — generates mock AI responses without a real API key
-   */
-  demoMode?: boolean;
-
-  /**
-   * Custom mock responses to use in demo mode
-   */
-  customResponses?: MockResponse[];
-
-  /**
-   * Callback fired when the user navigates to the settings page
-   */
-  onNavigateSettings?: () => void;
-
-  /**
-   * Callback fired when the user navigates to the full-page assistant view
-   */
-  onNavigateFullPage?: () => void;
-
-  /**
-   * Display name of the logged-in user
-   * @default 'User'
-   */
-  userName?: string;
-
-  /**
-   * Pre-loaded messages to hydrate an existing conversation
-   */
-  initialMessages?: Message[];
-
-  /**
-   * Previously saved conversations shown in the history panel
-   */
-  savedConversations?: Conversation[];
-
-  /**
-   * Suggested prompts shown to the user in the empty state
-   */
-  suggestions?: Suggestion[];
-
-  /**
-   * Subtitle shown below the user's name in the empty state.
-   * @default 'Como posso ajudar?'
-   */
-  welcomeMessage?: string;
-
-  /**
-   * Callback fired when the user sends a message
-   */
-  onSendMessage?: (message: string) => void;
-
-  /**
-   * Callback fired when the user attaches a file
-   */
-  onFileAttach?: (file: File) => void;
-
-  /**
-   * If true, shows a typing indicator while waiting for an AI response
-   */
-  isProcessing?: boolean;
-
-  /**
-   * Custom panel width (only applies when `mode='expanded'`)
-   */
-  width?: string;
-
-  /**
-   * Custom panel height (only applies when `mode='fullPage'`)
-   */
-  height?: string;
-
-  /**
-   * Additional CSS classes for the root container
-   */
-  className?: string;
-  mobileFloating?: boolean;
-  /**
-   * Custom response generator function — overrides demo mode defaults
-   * @param message The user's input message
-   * @returns A promise or direct value resolving to either a markdown string or a partial `Message` object
-   */
-  responseGenerator?: (
-    message: string
-  ) => Promise<string | Partial<Message>> | string | Partial<Message>;
-  /**
-   * Extended suggestions shown when the user clicks "More suggestions"
-   */
-  richSuggestions?: Suggestion[];
-  /**
-   * Callback fired when the user clicks a rich suggestion item
-   */
-  onRichAction?: (actionId: string, actionText: string) => void;
-  /**
-   * Callback fired when the user rates a message (thumbs up/down)
-   */
-  onEvaluation?: (messageId: string, type: 'like' | 'dislike', reason?: string) => void;
-  /**
-   * Negative feedback categories shown in the dislike dropdown
-   */
-  feedbackOptions?: string[];
-
-  // ============================================================================
-  // Feature Flags — Controls individual assistant capabilities
-  // ============================================================================
-
-  /**
-   * Whether to show the conversation history tab and collapsed icon.
-   * @default true
-   */
-  showHistory?: boolean;
-
-  /**
-   * Whether to show the favorites tab and collapsed icon.
-   * @default true
-   */
-  showFavorites?: boolean;
-
-  /**
-   * Whether to enable audio input (voice recording / audio upload) in the chat.
-   * @default true
-   */
-  enableAudioInput?: boolean;
-
-  /**
-   * Whether to enable file attachment in the chat input.
-   * @default true
-   */
-  enableFileAttachment?: boolean;
-
-  /**
-   * Whether to enable the "Create document" action in the chat input.
-   * @default true
-   */
-  enableDocumentCreation?: boolean;
-
-  /**
-   * Whether to enable podcast generation (action chip + per-message button).
-   * @default true
-   */
-  enablePodcastGeneration?: boolean;
-
-  /**
-   * Whether to enable the "Search" action in the chat input.
-   * @default true
-   */
-  enableSearch?: boolean;
-}
-
-// ============================================================================
-// Main Component
-// ============================================================================
-
-/**
- * XerticaAssistant - Full-featured AI assistant with chat, history, and favorites.
- *
- * Supports three layout modes:
- * - `collapsed`: Icon-only sidebar strip
- * - `expanded`: Expandable side panel (default)
- * - `fullPage`: Dedicated full-page view
- *
- * @example
- * ```tsx
- * // Expanded mode (default)
- * <XerticaAssistant
- *   mode="expanded"
- *   userName="Jane Smith"
- *   onSendMessage={(msg) => console.log(msg)}
- * />
- *
- * // Full-page mode
- * <XerticaAssistant
- *   mode="fullPage"
- *   height="100vh"
- * />
- *
- * // Collapsed mode (icon strip only)
- * <XerticaAssistant
- *   mode="expanded"
- *   isExpanded={false}
- *   onToggle={() => setExpanded(!expanded)}
- * />
- * ```
- */
-/**
- * AI Chat Assistant component (Smart Chat Interface).
- *
- * @description
- * Full-featured chat interface with support for history, favorites, attachments,
- * and rich component rendering (tables, charts, documents, podcasts).
- * Supports three layout modes: `'collapsed'`, `'expanded'`, and `'fullPage'`.
- *
- * @ai-rules
- * 1. In `mode="expanded"` (default), the component acts as a resizable side panel.
- * 2. Use `onSendMessage` to capture user input and `responseGenerator` to provide AI responses in demo mode.
- * 3. Supports automatic Markdown rendering and syntax-highlighted code blocks.
- */
-export function XerticaAssistant({
-  mode = 'expanded',
-  isExpanded: controlledIsExpanded,
-  onToggle,
-  defaultTab = 'chat',
-  demoMode = true,
-  onNavigateSettings,
-  onNavigateFullPage,
-  userName,
-  initialMessages = [],
-  savedConversations = [],
-  suggestions: propSuggestions,
-  onSendMessage,
-  onFileAttach,
-  isProcessing = false,
-  width,
-  height,
-  className = '',
-  mobileFloating = false,
-  customResponses = [],
-  responseGenerator,
-  richSuggestions = [],
-  welcomeMessage,
-  onRichAction,
-  onEvaluation,
-  feedbackOptions,
-  // Feature flags — all default to true for backward compatibility
-  showHistory = true,
-  showFavorites = true,
-  enableAudioInput = true,
-  enableFileAttachment = true,
-  enableDocumentCreation = true,
-  enablePodcastGeneration = true,
-  enableSearch = true,
-}: XerticaAssistantProps) {
-  const { t } = useTranslation();
-  // Apply i18n defaults when the caller does not provide values
-  const resolvedUserName = userName ?? t('assistant.defaultUserName');
-  const resolvedWelcomeMessage = welcomeMessage ?? t('assistant.defaultWelcomeMessage');
-  // ============================================================================
-  // State & Logic — delegated to useAssistant hook
-  // ============================================================================
-
-  const {
-    isFullPage,
-    isExpanded,
-    isMobile,
-    abaSelecionada,
-    setAbaSelecionada,
-    mensagens,
-    mensagem,
-    setMensagem,
-    conversaAtual,
-    conversasFiltradas,
-    copiedId,
-    generatingPodcastId,
-    executingCommand,
-    savedSearches,
-    editingDocument,
-    setEditingDocument,
-    showMoreSuggestions,
-    setShowMoreSuggestions,
-    evaluationState,
-    setEvaluationState,
-    sugestoes,
-    messagesEndRef,
-    fileInputRef,
-    audioInputRef,
-    handleToggle,
-    handleExpandWithTab,
-    handleEnviarMensagem,
-    handleToggleFavorite,
-    handleCopyMessage,
-    handleGeneratePodcast,
-    handleDownloadDocument,
-    handleDownloadPodcast,
-    handleEditDocument,
-    handleNovaConversa,
-    handleSelecionarConversa,
-    handleToggleFavoritaConversa,
-    handleOpenSearchResult,
-    handleExecuteSearchCommand,
-    handleRichSuggestionClick,
-    handleEvaluationClick,
-    openFeedbackDialog,
-    handleSubmitDislike,
-  } = useAssistant({
-    mode,
-    isExpanded: controlledIsExpanded,
-    onToggle,
-    defaultTab,
-    demoMode,
-    customResponses,
-    initialMessages,
-    savedConversations,
-    suggestions: propSuggestions,
-    onSendMessage,
-    isProcessing,
-    responseGenerator,
-    richSuggestions,
-    onRichAction,
-    onEvaluation,
-  });
-
-  // ============================================================================
-  // Render
-  // ============================================================================
-
-  const containerWidth =
-    width ??
-    (isFullPage ? '100%' : isExpanded ? '420px' : '80px'); // Compacto quando fechado - apenas ícones
-  const containerHeight = height ?? 'h-full';
-
-  // Mobile floating button — shown when collapsed on mobile
-  if (isMobile && !isExpanded) {
-    return (
-      <Button
-        onClick={handleToggle}
-        className={cn(
-          'fixed bottom-4 right-4 h-14 rounded-full shadow-lg pl-3 pr-5 gap-3 bg-white text-zinc-900 hover:bg-zinc-50 border border-zinc-200 z-50 transition-all duration-300',
-          className
-        )}
-      >
-        <XerticaOrbe size={32} />
-        <span className="font-semibold text-base tracking-wide">{t('assistant.title')}</span>
-      </Button>
-    );
-  }
-
-  return (
-    <>
-      {/* Hidden File Inputs */}
-      <input
-        ref={fileInputRef}
-        type="file"
-        accept=".pdf,.doc,.docx,.txt,.md"
-        className="hidden"
-        onChange={e => {
-          const file = e.target.files?.[0];
-          if (file && onFileAttach) {
-            onFileAttach(file);
-          }
-        }}
-        aria-label={t('assistant.uploadDocument')}
-      />
-      <input
-        ref={audioInputRef}
-        type="file"
-        accept="audio/*"
-        className="hidden"
-        onChange={e => {
-          const file = e.target.files?.[0];
-          if (file && onFileAttach) {
-            onFileAttach(file);
-          }
-        }}
-        aria-label={t('assistant.uploadAudio')}
-      />
-
-      {/* Main Assistant Container */}
-      <div
-        className={cn(
-          `${containerHeight} flex flex-col bg-background relative`,
-          !isFullPage && 'border-l border-border shadow-sm',
-          isMobile && isExpanded && 'fixed inset-0 z-[100] h-[100dvh] w-full border-l-0 shadow-2xl',
-          className
-        )}
-        style={
-          !(isMobile && isExpanded)
-            ? {
-                width: isFullPage ? '100%' : containerWidth,
-              }
-            : undefined
-        }
-      >
-        {/* Document Editor Overlay */}
-        {editingDocument && !isFullPage && (
-          <AssistantDocumentEditor
-            document={editingDocument}
-            isMobile={isMobile}
-            containerWidth={containerWidth}
-            onClose={() => setEditingDocument(null)}
-            onChange={doc => setEditingDocument(doc)}
-          />
-        )}
-
-        {/* Header — only visible when not in fullPage mode */}
-        {!isFullPage && (
-          <AssistantHeader
-            isExpanded={isExpanded}
-            onToggle={handleToggle}
-            onNavigateFullPage={onNavigateFullPage}
-          />
-        )}
-
-        {/* Collapsed State — Icons Only */}
-        {!isExpanded && !isFullPage && (
-          <AssistantCollapsedView
-            showHistory={showHistory}
-            showFavorites={showFavorites}
-            onToggle={handleToggle}
-            onExpandWithTab={handleExpandWithTab}
-          />
-        )}
-
-        {/* Expanded State — Full Content */}
-        <AnimatePresence>
-          {(isExpanded || isFullPage) && (
-            <motion.div
-              initial={isFullPage ? false : { opacity: 0, x: 50 }}
-              animate={{ opacity: 1, x: 0 }}
-              exit={isFullPage ? undefined : { opacity: 0, x: 50 }}
-              transition={{ duration: 0.2 }}
-              className="flex-1 flex flex-col overflow-hidden"
-            >
-              {/* Navigation Tabs — hidden in fullPage mode and when no secondary tabs are enabled */}
-              {!isFullPage && (showHistory || showFavorites) && (
-                <AssistantTabBar
-                  activeTab={abaSelecionada}
-                  showHistory={showHistory}
-                  showFavorites={showFavorites}
-                  onTabChange={setAbaSelecionada}
-                />
-              )}
-
-              {/* Content Area */}
-              <div className="flex-1 overflow-hidden flex flex-col">
-                {/* Chat Tab */}
-                {abaSelecionada === 'chat' && (
-                  <div
-                    className={`flex-1 flex flex-col min-h-0 ${isFullPage ? 'mx-auto w-full max-w-6xl' : ''}`}
-                  >
-                    {mensagens.length === 0 ? (
-                      <AssistantWelcomeScreen
-                        userName={resolvedUserName}
-                        welcomeMessage={resolvedWelcomeMessage}
-                        suggestions={sugestoes}
-                        richSuggestions={richSuggestions}
-                        showMoreSuggestions={showMoreSuggestions}
-                        onSetShowMoreSuggestions={setShowMoreSuggestions}
-                        onSendSuggestion={handleEnviarMensagem}
-                        onRichSuggestionClick={handleRichSuggestionClick}
-                      />
-                    ) : (
-                      <ScrollArea className="flex-1 min-h-0 overflow-x-hidden [&_[data-radix-scroll-area-viewport]>div]:!block">
-                        <div className="space-y-4 px-4 py-4 max-w-6xl mx-auto !block !w-full">
-                          {mensagens.map(msg => (
-                            <AssistantMessageBubble
-                              key={msg.id}
-                              msg={msg}
-                              copiedId={copiedId}
-                              generatingPodcastId={generatingPodcastId}
-                              executingCommand={executingCommand}
-                              savedSearches={savedSearches}
-                              enablePodcastGeneration={enablePodcastGeneration}
-                              feedbackOptions={feedbackOptions}
-                              onCopyMessage={handleCopyMessage}
-                              onToggleFavorite={handleToggleFavorite}
-                              onGeneratePodcast={handleGeneratePodcast}
-                              onDownloadDocument={handleDownloadDocument}
-                              onDownloadPodcast={handleDownloadPodcast}
-                              onEditDocument={handleEditDocument}
-                              onOpenSearchResult={handleOpenSearchResult}
-                              onExecuteSearchCommand={handleExecuteSearchCommand}
-                              onEvaluationClick={handleEvaluationClick}
-                              onOpenFeedbackDialog={openFeedbackDialog}
-                            />
-                          ))}
-
-                          {/* Typing Indicator */}
-                          {isProcessing && <AssistantTypingIndicator />}
-
-                          <div ref={messagesEndRef} />
-                        </div>
-                      </ScrollArea>
-                    )}
-                  </div>
-                )}
-
-                {/* History / Favorites Tab */}
-                {((abaSelecionada === 'historico' && showHistory) ||
-                  (abaSelecionada === 'favoritos' && showFavorites)) && (
-                  <AssistantConversationList
-                    conversations={conversasFiltradas}
-                    currentConversationId={conversaAtual}
-                    activeTab={abaSelecionada}
-                    isFullPage={isFullPage}
-                    onNewConversation={handleNovaConversa}
-                    onSelectConversation={handleSelecionarConversa}
-                    onToggleFavorite={handleToggleFavoritaConversa}
-                  />
-                )}
-              </div>
-
-              {/* Modern Input Area — only visible in chat mode */}
-              {abaSelecionada === 'chat' && (
-                <ModernChatInput
-                  value={mensagem}
-                  onChange={setMensagem}
-                  onSubmit={handleEnviarMensagem}
-                  onFileUpload={
-                    enableFileAttachment ? () => fileInputRef.current?.click() : undefined
-                  }
-                  onAudioUpload={
-                    enableAudioInput ? () => audioInputRef.current?.click() : undefined
-                  }
-                  disabled={isProcessing}
-                  isFullPage={isFullPage}
-                  enableAudioInput={enableAudioInput}
-                  enableFileAttachment={enableFileAttachment}
-                  enableDocumentCreation={enableDocumentCreation}
-                  enablePodcastGeneration={enablePodcastGeneration}
-                  enableSearch={enableSearch}
-                />
-              )}
-            </motion.div>
-          )}
-        </AnimatePresence>
-      </div>
-
-      {/* Feedback Dialog */}
-      <AssistantFeedbackDialog
-        state={evaluationState}
-        onReasonChange={reason => setEvaluationState(prev => ({ ...prev, reason }))}
-        onClose={() => setEvaluationState(prev => ({ ...prev, isOpen: false }))}
-        onSubmit={handleSubmitDislike}
-      />
-    </>
-  );
-}
+import React from 'react';
+import { useAssistant } from './use-assistant';
+import { motion, AnimatePresence } from 'framer-motion';
+import { useTranslation } from 'react-i18next';
+import { ScrollArea } from '../../ui/scroll-area';
+import { ModernChatInput } from '../modern-chat-input';
+import { XerticaOrbe } from '../../brand/xertica-orbe';
+import { Button } from '../../ui/button';
+import { cn } from '../../shared/utils';
+
+// Sub-components
+import {
+  AssistantCollapsedView,
+  AssistantHeader,
+  AssistantTabBar,
+  AssistantWelcomeScreen,
+  AssistantMessageBubble,
+  AssistantTypingIndicator,
+  AssistantConversationList,
+  AssistantFeedbackDialog,
+  AssistantDocumentEditor,
+} from './parts';
+import type { EvaluationState } from './parts';
+
+// ============================================================================
+// TypeScript Interfaces & Types — imported from shared types.ts and re-exported
+// for backward compatibility with consumers that import from xertica-assistant.
+// ============================================================================
+import type {
+  MessageType,
+  AttachmentType,
+  SearchResultType,
+  AssistantMode,
+  AssistantTab,
+  SearchResult,
+  SearchSource,
+  SearchCommand,
+  Message,
+  Conversation,
+  Suggestion,
+  MockResponse,
+} from './types';
+
+export type {
+  MessageType,
+  AttachmentType,
+  SearchResultType,
+  AssistantMode,
+  AssistantTab,
+  SearchResult,
+  SearchSource,
+  SearchCommand,
+  Message,
+  Conversation,
+  Suggestion,
+  MockResponse,
+};
+
+// ============================================================================
+// Component Props
+// ============================================================================
+
+export interface XerticaAssistantProps {
+  /**
+   * Layout mode for the assistant panel
+   * @default 'expanded'
+   */
+  mode?: AssistantMode;
+
+  /**
+   * Whether the panel is expanded (only applies when `mode='expanded'`)
+   * @default true
+   */
+  isExpanded?: boolean;
+
+  /**
+   * Callback fired when the assistant panel is expanded or collapsed
+   */
+  onToggle?: () => void;
+
+  /**
+   * Initially selected tab
+   * @default 'chat'
+   */
+  defaultTab?: AssistantTab;
+
+  /**
+   * Enables demo mode — generates mock AI responses without a real API key
+   */
+  demoMode?: boolean;
+
+  /**
+   * Custom mock responses to use in demo mode
+   */
+  customResponses?: MockResponse[];
+
+  /**
+   * Callback fired when the user navigates to the settings page
+   */
+  onNavigateSettings?: () => void;
+
+  /**
+   * Callback fired when the user navigates to the full-page assistant view
+   */
+  onNavigateFullPage?: () => void;
+
+  /**
+   * Display name of the logged-in user
+   * @default 'User'
+   */
+  userName?: string;
+
+  /**
+   * Pre-loaded messages to hydrate an existing conversation
+   */
+  initialMessages?: Message[];
+
+  /**
+   * Previously saved conversations shown in the history panel
+   */
+  savedConversations?: Conversation[];
+
+  /**
+   * Suggested prompts shown to the user in the empty state
+   */
+  suggestions?: Suggestion[];
+
+  /**
+   * Subtitle shown below the user's name in the empty state.
+   * @default 'Como posso ajudar?'
+   */
+  welcomeMessage?: string;
+
+  /**
+   * Callback fired when the user sends a message
+   */
+  onSendMessage?: (message: string) => void;
+
+  /**
+   * Callback fired when the user attaches a file
+   */
+  onFileAttach?: (file: File) => void;
+
+  /**
+   * If true, shows a typing indicator while waiting for an AI response
+   */
+  isProcessing?: boolean;
+
+  /**
+   * Custom panel width (only applies when `mode='expanded'`)
+   */
+  width?: string;
+
+  /**
+   * Custom panel height (only applies when `mode='fullPage'`)
+   */
+  height?: string;
+
+  /**
+   * Additional CSS classes for the root container
+   */
+  className?: string;
+  mobileFloating?: boolean;
+  /**
+   * Custom response generator function — overrides demo mode defaults
+   * @param message The user's input message
+   * @returns A promise or direct value resolving to either a markdown string or a partial `Message` object
+   */
+  responseGenerator?: (
+    message: string
+  ) => Promise<string | Partial<Message>> | string | Partial<Message>;
+  /**
+   * Extended suggestions shown when the user clicks "More suggestions"
+   */
+  richSuggestions?: Suggestion[];
+  /**
+   * Callback fired when the user clicks a rich suggestion item
+   */
+  onRichAction?: (actionId: string, actionText: string) => void;
+  /**
+   * Callback fired when the user rates a message (thumbs up/down)
+   */
+  onEvaluation?: (messageId: string, type: 'like' | 'dislike', reason?: string) => void;
+  /**
+   * Negative feedback categories shown in the dislike dropdown
+   */
+  feedbackOptions?: string[];
+
+  // ============================================================================
+  // Feature Flags — Controls individual assistant capabilities
+  // ============================================================================
+
+  /**
+   * Whether to show the conversation history tab and collapsed icon.
+   * @default true
+   */
+  showHistory?: boolean;
+
+  /**
+   * Whether to show the favorites tab and collapsed icon.
+   * @default true
+   */
+  showFavorites?: boolean;
+
+  /**
+   * Whether to enable audio input (voice recording / audio upload) in the chat.
+   * @default true
+   */
+  enableAudioInput?: boolean;
+
+  /**
+   * Whether to enable file attachment in the chat input.
+   * @default true
+   */
+  enableFileAttachment?: boolean;
+
+  /**
+   * Whether to enable the "Create document" action in the chat input.
+   * @default true
+   */
+  enableDocumentCreation?: boolean;
+
+  /**
+   * Whether to enable podcast generation (action chip + per-message button).
+   * @default true
+   */
+  enablePodcastGeneration?: boolean;
+
+  /**
+   * Whether to enable the "Search" action in the chat input.
+   * @default true
+   */
+  enableSearch?: boolean;
+}
+
+// ============================================================================
+// Main Component
+// ============================================================================
+
+/**
+ * XerticaAssistant - Full-featured AI assistant with chat, history, and favorites.
+ *
+ * Supports three layout modes:
+ * - `collapsed`: Icon-only sidebar strip
+ * - `expanded`: Expandable side panel (default)
+ * - `fullPage`: Dedicated full-page view
+ *
+ * @example
+ * ```tsx
+ * // Expanded mode (default)
+ * <XerticaAssistant
+ *   mode="expanded"
+ *   userName="Jane Smith"
+ *   onSendMessage={(msg) => console.log(msg)}
+ * />
+ *
+ * // Full-page mode
+ * <XerticaAssistant
+ *   mode="fullPage"
+ *   height="100vh"
+ * />
+ *
+ * // Collapsed mode (icon strip only)
+ * <XerticaAssistant
+ *   mode="expanded"
+ *   isExpanded={false}
+ *   onToggle={() => setExpanded(!expanded)}
+ * />
+ * ```
+ */
+/**
+ * AI Chat Assistant component (Smart Chat Interface).
+ *
+ * @description
+ * Full-featured chat interface with support for history, favorites, attachments,
+ * and rich component rendering (tables, charts, documents, podcasts).
+ * Supports three layout modes: `'collapsed'`, `'expanded'`, and `'fullPage'`.
+ *
+ * @ai-rules
+ * 1. In `mode="expanded"` (default), the component acts as a resizable side panel.
+ * 2. Use `onSendMessage` to capture user input and `responseGenerator` to provide AI responses in demo mode.
+ * 3. Supports automatic Markdown rendering and syntax-highlighted code blocks.
+ */
+export function XerticaAssistant({
+  mode = 'expanded',
+  isExpanded: controlledIsExpanded,
+  onToggle,
+  defaultTab = 'chat',
+  demoMode = true,
+  onNavigateSettings,
+  onNavigateFullPage,
+  userName,
+  initialMessages = [],
+  savedConversations = [],
+  suggestions: propSuggestions,
+  onSendMessage,
+  onFileAttach,
+  isProcessing = false,
+  width,
+  height,
+  className = '',
+  mobileFloating = false,
+  customResponses = [],
+  responseGenerator,
+  richSuggestions = [],
+  welcomeMessage,
+  onRichAction,
+  onEvaluation,
+  feedbackOptions,
+  // Feature flags — all default to true for backward compatibility
+  showHistory = true,
+  showFavorites = true,
+  enableAudioInput = true,
+  enableFileAttachment = true,
+  enableDocumentCreation = true,
+  enablePodcastGeneration = true,
+  enableSearch = true,
+}: XerticaAssistantProps) {
+  const { t } = useTranslation();
+  // Apply i18n defaults when the caller does not provide values
+  const resolvedUserName = userName ?? t('assistant.defaultUserName');
+  const resolvedWelcomeMessage = welcomeMessage ?? t('assistant.defaultWelcomeMessage');
+  // ============================================================================
+  // State & Logic — delegated to useAssistant hook
+  // ============================================================================
+
+  const {
+    isFullPage,
+    isExpanded,
+    isMobile,
+    abaSelecionada,
+    setAbaSelecionada,
+    mensagens,
+    mensagem,
+    setMensagem,
+    conversaAtual,
+    conversasFiltradas,
+    copiedId,
+    generatingPodcastId,
+    executingCommand,
+    savedSearches,
+    editingDocument,
+    setEditingDocument,
+    showMoreSuggestions,
+    setShowMoreSuggestions,
+    evaluationState,
+    setEvaluationState,
+    sugestoes,
+    messagesEndRef,
+    fileInputRef,
+    audioInputRef,
+    handleToggle,
+    handleExpandWithTab,
+    handleEnviarMensagem,
+    handleToggleFavorite,
+    handleCopyMessage,
+    handleGeneratePodcast,
+    handleDownloadDocument,
+    handleDownloadPodcast,
+    handleEditDocument,
+    handleNovaConversa,
+    handleSelecionarConversa,
+    handleToggleFavoritaConversa,
+    handleOpenSearchResult,
+    handleExecuteSearchCommand,
+    handleRichSuggestionClick,
+    handleEvaluationClick,
+    openFeedbackDialog,
+    handleSubmitDislike,
+  } = useAssistant({
+    mode,
+    isExpanded: controlledIsExpanded,
+    onToggle,
+    defaultTab,
+    demoMode,
+    customResponses,
+    initialMessages,
+    savedConversations,
+    suggestions: propSuggestions,
+    onSendMessage,
+    isProcessing,
+    responseGenerator,
+    richSuggestions,
+    onRichAction,
+    onEvaluation,
+  });
+
+  // ============================================================================
+  // Render
+  // ============================================================================
+
+  const containerWidth = width ?? (isFullPage ? '100%' : isExpanded ? '420px' : '80px'); // Compacto quando fechado - apenas ícones
+  const containerHeight = height ?? 'h-full';
+
+  // Mobile floating button — shown when collapsed on mobile
+  if (isMobile && !isExpanded) {
+    return (
+      <Button
+        onClick={handleToggle}
+        className={cn(
+          'fixed bottom-4 right-4 h-14 rounded-full shadow-lg pl-3 pr-5 gap-3 bg-white text-zinc-900 hover:bg-zinc-50 border border-zinc-200 z-50 transition-all duration-300',
+          className
+        )}
+      >
+        <XerticaOrbe size={32} />
+        <span className="font-semibold text-base tracking-wide">{t('assistant.title')}</span>
+      </Button>
+    );
+  }
+
+  return (
+    <>
+      {/* Hidden File Inputs */}
+      <input
+        ref={fileInputRef}
+        type="file"
+        accept=".pdf,.doc,.docx,.txt,.md"
+        className="hidden"
+        onChange={e => {
+          const file = e.target.files?.[0];
+          if (file && onFileAttach) {
+            onFileAttach(file);
+          }
+        }}
+        aria-label={t('assistant.uploadDocument')}
+      />
+      <input
+        ref={audioInputRef}
+        type="file"
+        accept="audio/*"
+        className="hidden"
+        onChange={e => {
+          const file = e.target.files?.[0];
+          if (file && onFileAttach) {
+            onFileAttach(file);
+          }
+        }}
+        aria-label={t('assistant.uploadAudio')}
+      />
+
+      {/* Main Assistant Container */}
+      <div
+        className={cn(
+          `${containerHeight} flex flex-col bg-background relative`,
+          !isFullPage && 'border-l border-border shadow-sm',
+          isMobile && isExpanded && 'fixed inset-0 z-[100] h-[100dvh] w-full border-l-0 shadow-2xl',
+          className
+        )}
+        style={
+          !(isMobile && isExpanded)
+            ? {
+                width: isFullPage ? '100%' : containerWidth,
+              }
+            : undefined
+        }
+      >
+        {/* Document Editor Overlay */}
+        {editingDocument && !isFullPage && (
+          <AssistantDocumentEditor
+            document={editingDocument}
+            isMobile={isMobile}
+            containerWidth={containerWidth}
+            onClose={() => setEditingDocument(null)}
+            onChange={doc => setEditingDocument(doc)}
+          />
+        )}
+
+        {/* Header — only visible when not in fullPage mode */}
+        {!isFullPage && (
+          <AssistantHeader
+            isExpanded={isExpanded}
+            onToggle={handleToggle}
+            onNavigateFullPage={onNavigateFullPage}
+          />
+        )}
+
+        {/* Collapsed State — Icons Only */}
+        {!isExpanded && !isFullPage && (
+          <AssistantCollapsedView
+            showHistory={showHistory}
+            showFavorites={showFavorites}
+            onToggle={handleToggle}
+            onExpandWithTab={handleExpandWithTab}
+          />
+        )}
+
+        {/* Expanded State — Full Content */}
+        <AnimatePresence>
+          {(isExpanded || isFullPage) && (
+            <motion.div
+              initial={isFullPage ? false : { opacity: 0, x: 50 }}
+              animate={{ opacity: 1, x: 0 }}
+              exit={isFullPage ? undefined : { opacity: 0, x: 50 }}
+              transition={{ duration: 0.2 }}
+              className="flex-1 flex flex-col overflow-hidden"
+            >
+              {/* Navigation Tabs — hidden in fullPage mode and when no secondary tabs are enabled */}
+              {!isFullPage && (showHistory || showFavorites) && (
+                <AssistantTabBar
+                  activeTab={abaSelecionada}
+                  showHistory={showHistory}
+                  showFavorites={showFavorites}
+                  onTabChange={setAbaSelecionada}
+                />
+              )}
+
+              {/* Content Area */}
+              <div className="flex-1 overflow-hidden flex flex-col">
+                {/* Chat Tab */}
+                {abaSelecionada === 'chat' && (
+                  <div
+                    className={`flex-1 flex flex-col min-h-0 ${isFullPage ? 'mx-auto w-full max-w-6xl' : ''}`}
+                  >
+                    {mensagens.length === 0 ? (
+                      <AssistantWelcomeScreen
+                        userName={resolvedUserName}
+                        welcomeMessage={resolvedWelcomeMessage}
+                        suggestions={sugestoes}
+                        richSuggestions={richSuggestions}
+                        showMoreSuggestions={showMoreSuggestions}
+                        onSetShowMoreSuggestions={setShowMoreSuggestions}
+                        onSendSuggestion={handleEnviarMensagem}
+                        onRichSuggestionClick={handleRichSuggestionClick}
+                      />
+                    ) : (
+                      <ScrollArea className="flex-1 min-h-0 overflow-x-hidden [&_[data-radix-scroll-area-viewport]>div]:!block">
+                        <div className="space-y-4 px-4 py-4 max-w-6xl mx-auto !block !w-full">
+                          {mensagens.map(msg => (
+                            <AssistantMessageBubble
+                              key={msg.id}
+                              msg={msg}
+                              copiedId={copiedId}
+                              generatingPodcastId={generatingPodcastId}
+                              executingCommand={executingCommand}
+                              savedSearches={savedSearches}
+                              enablePodcastGeneration={enablePodcastGeneration}
+                              feedbackOptions={feedbackOptions}
+                              onCopyMessage={handleCopyMessage}
+                              onToggleFavorite={handleToggleFavorite}
+                              onGeneratePodcast={handleGeneratePodcast}
+                              onDownloadDocument={handleDownloadDocument}
+                              onDownloadPodcast={handleDownloadPodcast}
+                              onEditDocument={handleEditDocument}
+                              onOpenSearchResult={handleOpenSearchResult}
+                              onExecuteSearchCommand={handleExecuteSearchCommand}
+                              onEvaluationClick={handleEvaluationClick}
+                              onOpenFeedbackDialog={openFeedbackDialog}
+                            />
+                          ))}
+
+                          {/* Typing Indicator */}
+                          {isProcessing && <AssistantTypingIndicator />}
+
+                          <div ref={messagesEndRef} />
+                        </div>
+                      </ScrollArea>
+                    )}
+                  </div>
+                )}
+
+                {/* History / Favorites Tab */}
+                {((abaSelecionada === 'historico' && showHistory) ||
+                  (abaSelecionada === 'favoritos' && showFavorites)) && (
+                  <AssistantConversationList
+                    conversations={conversasFiltradas}
+                    currentConversationId={conversaAtual}
+                    activeTab={abaSelecionada}
+                    isFullPage={isFullPage}
+                    onNewConversation={handleNovaConversa}
+                    onSelectConversation={handleSelecionarConversa}
+                    onToggleFavorite={handleToggleFavoritaConversa}
+                  />
+                )}
+              </div>
+
+              {/* Modern Input Area — only visible in chat mode */}
+              {abaSelecionada === 'chat' && (
+                <ModernChatInput
+                  value={mensagem}
+                  onChange={setMensagem}
+                  onSubmit={handleEnviarMensagem}
+                  onFileUpload={
+                    enableFileAttachment ? () => fileInputRef.current?.click() : undefined
+                  }
+                  onAudioUpload={
+                    enableAudioInput ? () => audioInputRef.current?.click() : undefined
+                  }
+                  disabled={isProcessing}
+                  isFullPage={isFullPage}
+                  enableAudioInput={enableAudioInput}
+                  enableFileAttachment={enableFileAttachment}
+                  enableDocumentCreation={enableDocumentCreation}
+                  enablePodcastGeneration={enablePodcastGeneration}
+                  enableSearch={enableSearch}
+                />
+              )}
+            </motion.div>
+          )}
+        </AnimatePresence>
+      </div>
+
+      {/* Feedback Dialog */}
+      <AssistantFeedbackDialog
+        state={evaluationState}
+        onReasonChange={reason => setEvaluationState(prev => ({ ...prev, reason }))}
+        onClose={() => setEvaluationState(prev => ({ ...prev, isOpen: false }))}
+        onSubmit={handleSubmitDislike}
+      />
+    </>
+  );
+}