# XerticaAssistant --- ## Overview Full-featured AI chat assistant with support for: - Chat conversations with history and favorites - Rich message rendering (Markdown, code, tables, charts, documents) - Audio/podcast generation from text - Document editing workspace - Three layout modes: `collapsed`, `expanded`, `fullPage` - Demo mode (mock AI responses without API key) The component ships in **two usage patterns**: | Pattern | When to use | | ---------------------- | ---------------------------------------------------------------------------- | | `` | Drop-in assistant panel — zero configuration needed | | `useAssistant()` | Headless hook — bring your own UI while reusing all state and business logic | > **CLI scaffold:** When running `npx xertica-ui@latest init`, the assistant is included by default. To opt out during init, answer `no` at the "Include AI Assistant?" prompt. To add or remove it later from an existing project, run `npx xertica-ui update` → **Assistant**. The CLI will copy or delete `src/features/assistant/` and `src/pages/AssistantPage.tsx`, and regenerate `AuthGuard.tsx`, `HomePage.tsx`, and `TemplatePage.tsx` accordingly. --- ## Props | Prop | Type | Default | Required | Description | | ------------------------- | ------------------------------------------------------------------------- | ------------ | ------------------------------------------- | ------------------------------------------------------------ | | `mode` | `AssistantMode` | `'expanded'` | No | Layout mode: `'collapsed'`, `'expanded'`, `'fullPage'` | | `isExpanded` | `boolean` | `true` | No | Whether panel is expanded (mode='expanded' only) | | `onToggle` | `() => void` | — | No | Callback when panel is toggled | | `defaultTab` | `'chat' \| 'historico' \| 'favoritos'` | `'chat'` | No | Initially selected tab | | `demoMode` | `boolean` | `true` | No | Enable demo mode (mock AI responses) | | `customResponses` | `MockResponse[]` | — | No | Custom mock responses for demo mode | | `onNavigateSettings` | `() => void` | — | No | Navigate to settings page | | `onNavigateFullPage` | `() => void` | — | No | Navigate to full-page view | | `userName` | `string` | `'Usuário'` | No | Display name of logged-in user | | `initialMessages` | `Message[]` | — | Pre-loaded messages to hydrate conversation | | `savedConversations` | `Conversation[]` | — | Previously saved conversations | | `suggestions` | `Suggestion[]` | — | Suggested prompts shown in empty state | | `onSendMessage` | `(message: string) => void` | — | Callback when user sends message | | `onFileAttach` | `(file: File) => void` | — | Callback when user attaches file | | `isProcessing` | `boolean` | `false` | No | Shows typing indicator | | `width` | `string` | — | No | Custom panel width (expanded mode) | | `height` | `string` | — | No | Custom panel height (fullPage mode) | | `className` | `string` | — | No | Additional CSS classes | | `mobileFloating` | `boolean` | — | No | Show as floating button on mobile | | `responseGenerator` | `(message: string) => Promise>` | — | No | Custom response generator function | | `richSuggestions` | `Suggestion[]` | — | No | Extended suggestions (shown after clicking "Mais sugestões") | | `onRichAction` | `(actionId: string, actionText: string) => void` | — | No | Callback when user clicks rich suggestion | | `onEvaluation` | `(messageId: string, type: 'like' \| 'dislike', reason?: string) => void` | — | No | Callback when user rates a message | | `feedbackOptions` | `string[]` | — | No | Negative feedback categories | | `showHistory` | `boolean` | `true` | No | Show conversation history tab and collapsed icon | | `showFavorites` | `boolean` | `true` | No | Show favorites tab and collapsed icon | | `enableAudioInput` | `boolean` | `true` | No | Enable voice recording / audio upload | | `enableFileAttachment` | `boolean` | `true` | No | Enable file attachment button | | `enableDocumentCreation` | `boolean` | `true` | No | Enable "Create document" action in chat input | | `enablePodcastGeneration` | `boolean` | `true` | No | Enable podcast generation (action chip + per-message button) | | `enableSearch` | `boolean` | `true` | No | Enable "Search" action in chat input | --- ## Types ```typescript type AssistantMode = 'collapsed' | 'expanded' | 'fullPage'; type AssistantTab = 'chat' | 'historico' | 'favoritos'; type MessageType = 'user' | 'assistant' | 'system'; type AttachmentType = 'file' | 'audio' | 'image' | 'video' | 'document' | 'podcast' | 'search'; type SearchResultType = 'document' | 'project' | 'conversation' | 'file' | 'contact'; interface Message { id: string; type: MessageType; content: string; timestamp: Date; isFavorite?: boolean; attachmentType?: AttachmentType; attachmentName?: string; documentContent?: string; documentTitle?: string; audioUrl?: string; searchResults?: SearchResult[]; chartData?: any[]; chartConfig?: any; tableData?: { caption?: string; headers: string[]; rows: (string | React.ReactNode)[][] }; evaluation?: 'like' | 'dislike'; evaluationReason?: string; } interface Conversation { id: string; title: string; lastMessage?: string; timestamp: string; isFavorite: boolean; messages: Message[]; } interface Suggestion { id: string; text: string; icon?: React.ReactNode; } interface SearchResult { id: string; type: SearchResultType; title: string; description: string; path: string; relevance: number; lastModified?: string; } ``` --- ## Layout Modes ### Expanded (default) Resizable side panel (420px default) that sits flush against the right side of the screen. ### FullPage Dedicated full-page view with centered content container (`max-w-6xl`). ### Collapsed Icon-only sidebar strip with tooltip tooltips. --- ## Mobile Behavior - Desktop: Sits flush against right side, mutually exclusive with `` - Mobile: Transitions to floating Action Button (bottom-right), expands to full-screen overlay when clicked --- ## Document Editor Mode When the assistant generates a full document, a `RichTextEditor` slides precisely from the right border overlaying the page. --- ## Examples ### Basic Integration (Demo Mode) ```tsx import { XerticaAssistant } from 'xertica-ui/assistant'; ; ``` ### With Real API ```tsx import { XerticaAssistant } from 'xertica-ui/assistant'; console.log(msg)} responseGenerator={async msg => { const response = await callGeminiAPI(apiKey, msg); return response; }} />; ``` ### FullPage Mode ```tsx ``` --- ## Demo Mode Responses The component includes built-in mock responses for common requests: - Document creation: Generates markdown documents - Search: Returns mock search results - Summary: Generates summary tables - Podcast: Generates audio attachments - Charts: Renders data charts Use `customResponses` to override defaults. --- ## Feature Flags Each assistant capability can be individually toggled via boolean props. All flags default to `true`. ### Chat Only (no extras) ```tsx ``` ### Custom Configuration ```tsx // Only document creation and file attachment ``` --- ## Headless Hook — `useAssistant()` Use the headless hook when you need full control over the assistant's UI — custom layout, custom styling, or embedding the assistant logic inside a larger component. ### Import ```tsx import { useAssistant } from 'xertica-ui/assistant'; ``` ### Hook Props The hook accepts the same props as `XerticaAssistantProps` (minus purely visual props like `width`, `height`, `className`, `mobileFloating`, `onNavigateSettings`, `onNavigateFullPage`, `userName`, and feature flags). | Prop | Type | Default | Description | | -------------------- | ------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------- | | `mode` | `AssistantMode` | `'expanded'` | Layout mode | | `isExpanded` | `boolean` | `true` | Controlled expansion state | | `onToggle` | `() => void` | — | Toggle callback | | `defaultTab` | `AssistantTab` | `'chat'` | Initially selected tab | | `demoMode` | `boolean` | `true` | Enable demo mode | | `customResponses` | `MockResponse[]` | `[]` | Custom mock responses | | `initialMessages` | `Message[]` | `[]` | Pre-loaded messages — hydrated **once** on mount (one-shot). Subsequent changes to this prop do not reset the conversation | | `savedConversations` | `Conversation[]` | `[]` | Previously saved conversations | | `suggestions` | `Suggestion[]` | — | Suggested prompts | | `onSendMessage` | `(message: string) => void` | — | Send message callback | | `isProcessing` | `boolean` | `false` | Shows typing indicator | | `responseGenerator` | `(message: string) => Promise>` | — | Custom response generator | | `richSuggestions` | `Suggestion[]` | `[]` | Extended suggestions | | `onRichAction` | `(actionId: string, actionText: string) => void` | — | Rich suggestion callback | | `onEvaluation` | `(messageId: string, type: 'like' \| 'dislike', reason?: string) => void` | — | Evaluation callback | ### Hook Return Value | Property | Type | Description | | ------------------------------ | -------------------------------------------------------------- | ------------------------------------------------------------- | | `isFullPage` | `boolean` | Whether mode is `'fullPage'` | | `isExpanded` | `boolean` | Current expansion state | | `isMobile` | `boolean` | Whether viewport is mobile | | `abaSelecionada` | `AssistantTab` | Currently selected tab | | `setAbaSelecionada` | `(tab: AssistantTab) => void` | Change selected tab | | `mensagens` | `Message[]` | Current conversation messages | | `setMensagens` | `Dispatch>` | Update messages | | `mensagem` | `string` | Current input value | | `setMensagem` | `(value: string) => void` | Update input value | | `conversas` | `Conversation[]` | All saved conversations | | `conversaAtual` | `string \| null` | ID of the active conversation | | `conversasFiltradas` | `Conversation[]` | Conversations filtered by active tab | | `copiedId` | `string \| null` | ID of the message currently showing "copied" state | | `generatingPodcastId` | `string \| null` | ID of the message generating a podcast | | `executingCommand` | `string \| null` | ID of the search command being executed | | `savedSearches` | `string[]` | IDs of saved search messages | | `editingDocument` | `{ content: string; title: string } \| null` | Document being edited | | `setEditingDocument` | `(doc \| null) => void` | Open/close document editor | | `showMoreSuggestions` | `boolean` | Whether extended suggestions are visible | | `setShowMoreSuggestions` | `(show: boolean) => void` | Toggle extended suggestions | | `evaluationState` | `EvaluationState` | State of the feedback dialog | | `setEvaluationState` | `Dispatch<...>` | Update evaluation state | | `sugestoes` | `Suggestion[]` | Resolved suggestions (prop or defaults) | | `messagesEndRef` | `RefObject` | Attach to the scroll anchor at the bottom of the message list | | `fileInputRef` | `RefObject` | Attach to the hidden file input | | `audioInputRef` | `RefObject` | Attach to the hidden audio input | | `handleToggle` | `() => void` | Toggle expansion | | `handleExpandWithTab` | `(tab: AssistantTab) => void` | Expand and switch to a specific tab | | `handleEnviarMensagem` | `(arg?: string \| ActionType) => Promise` | Send a message | | `handleToggleFavorite` | `(messageId: string) => void` | Toggle message favorite | | `handleCopyMessage` | `(content: string, messageId: string) => Promise` | Copy message to clipboard | | `handleGeneratePodcast` | `(messageId: string, content: string) => Promise` | Generate podcast from message | | `handleDownloadDocument` | `(content: string, fileName: string) => void` | Download document as `.md` | | `handleDownloadPodcast` | `(audioUrl: string, fileName: string) => void` | Download podcast as `.mp3` | | `handleEditDocument` | `(content: string, title: string) => void` | Open document editor | | `handleNovaConversa` | `() => void` | Start a new conversation | | `handleSelecionarConversa` | `(conversaId: string) => void` | Load a saved conversation | | `handleToggleFavoritaConversa` | `(conversaId: string) => void` | Toggle conversation favorite | | `handleOpenSearchResult` | `(result: SearchResult) => void` | Open a search result | | `handleExecuteSearchCommand` | `(commandId, searchTerm, results, messageId) => Promise` | Execute a search command | | `handleRichSuggestionClick` | `(suggestion: Suggestion) => void` | Handle rich suggestion click | | `handleEvaluationClick` | `(messageId: string, type: 'like' \| 'dislike') => void` | Handle message evaluation | | `openFeedbackDialog` | `(messageId: string, category: string \| null) => void` | Open dislike feedback dialog | | `handleSubmitDislike` | `() => void` | Submit dislike feedback | ### Headless Hook Example ```tsx import { useAssistant } from 'xertica-ui/assistant'; function MyMinimalAssistant() { const { mensagens, mensagem, setMensagem, handleEnviarMensagem, isExpanded, handleToggle, messagesEndRef, } = useAssistant({ demoMode: true }); return (
{/* Header */}
AI Assistant
{/* Messages */}
{mensagens.map(msg => (
{msg.content}
))}
{/* Input */}
setMensagem(e.target.value)} onKeyDown={e => e.key === 'Enter' && handleEnviarMensagem()} placeholder="Type a message..." className="flex-1 border rounded px-3 py-2 text-sm" />
); } ``` --- ## AI Rules - Use `demoMode={true}` for development without API key - Use `responseGenerator` for custom AI integration - In fullPage mode, welcome message shows "Olá, {userName}" (not "Assistente Xertica") - Tab switching (chat/historico/favoritos) hides navigation tabs in fullPage mode - Feature flags are independent and can be combined freely; all default to `true` - When `showHistory` or `showFavorites` is `false`, both the collapsed icon and expanded tab are removed - When both `showHistory` and `showFavorites` are `false`, the entire tab navigation bar is hidden (including the Chat tab) — there is no point showing a single tab with no alternatives - ALWAYS use `useAssistant()` when building a custom assistant UI — never re-implement message state or response generation manually - The `messagesEndRef` from the hook MUST be attached to a div at the bottom of the message list for auto-scroll to work - `handleEnviarMensagem()` handles both demo mode responses and `responseGenerator` — do not call `responseGenerator` directly - `handleEnviarMensagem` accepts `arg?: string | ActionType` — pass a string to send a specific message, pass an `ActionType` (`'document'`, `'podcast'`, `'search'`) to trigger an action, or pass nothing to send the current `mensagem` input value - `initialMessages` is hydrated **once** (one-shot) — passing a new array after mount does not reset the conversation. To reset, call `setMensagens([])` directly - Auto-scroll is conditional: `messagesEndRef.scrollIntoView` is only called when the user is within 120px of the bottom of the chat container — preserves scroll position during history review - **`suggestions`, `richSuggestions`, and `feedbackOptions` should come from `useAssistantConfig()` (React Query)** — never hardcode them in the page component. Use the fallback factory functions from `features/assistant/data/mock.ts` while the query loads ## Dynamic Configuration with React Query In projects using the `features/` architecture, assistant configuration (suggestions, feedback options) is fetched via `useAssistantConfig()`: ```tsx import { useAssistantConfig, getMockRichSuggestions, getMockFeedbackOptions } from '../features/assistant'; function MyPage() { const { data: assistantConfig } = useAssistantConfig(); return ( ); } ``` To connect to a real configuration API, replace `fetchAssistantConfig` in `features/assistant/data/mock.ts`: ```ts // features/assistant/data/mock.ts export async function fetchAssistantConfig(): Promise { // Replace with real endpoint: return fetch('/api/assistant/config').then(r => r.json()); } ```