xertica-ui 2.1.3 → 2.1.5

package/CHANGELOG.md

@@ -7,6 +7,63 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [2.1.5] — 2026-05-19
+
+### Fixed
+
+- **`use-rich-text-editor` — `wordCount`/`characterCount` não reativos** — os contadores eram lidos via `editorRef.current` no corpo do render (sem estado reativo), ficando stale após cada keystroke. Convertidos para `useState` e atualizados dentro de `handleInput`. Um segundo `useEffect([value])` foi adicionado para atualizar os contadores quando o valor externo é sincronizado ao editor.
+- **`use-assistant-messages` — `setTimeout` da resposta AI nunca cancelado** — o timer da resposta simulada (1–2 s) não era cancelado ao desmontar o componente, causando chamadas de `setMensagens` em componente desmontado. Adicionado `responseTimerRef` + `useEffect` cleanup com `clearTimeout`.
+- **`use-assistant-messages` — `initialMessages` resetava a conversa a cada re-render** — o `useEffect` que sincronizava `initialMessages` disparava toda vez que a referência do array mudava, sobrescrevendo mensagens digitadas pelo usuário. Corrigido com `hydratedRef` (hydration one-shot).
+- **`use-assistant-messages` — auto-scroll forçado ignorava scroll do usuário** — `scrollIntoView` era chamado incondicionalmente em todo novo `mensagens`. Agora só rola se o usuário já está a menos de 120 px do final do container.
+- **`use-assistant-conversations` — `conversas` não sincronizado quando `savedConversations` muda** — o estado era inicializado uma vez no mount; atualizações externas da prop eram ignoradas. Adicionado `useEffect([savedConversations])` para re-sincronizar.
+- **`use-assistant-conversations` — `setTimeout` do comando não limpo no unmount** — `commandTimerRef` + cleanup `useEffect` adicionados para cancelar o timer ao desmontar.
+- **`use-audio-player` — `eslint-disable` mascarando deps stale no modo-switch effect** — o efeito de restauração de estado ao trocar `isFloating`/`variant` lia `currentTime` e `isPlaying` de uma closure stale. Corrigido com `currentTimeRef` e `isPlayingRef` (padrão "latest ref"), eliminando o `eslint-disable`.
+- **`use-rich-text-editor` — `eslint-disable` no `useEffect` de seleção** — o listener de `selectionchange` chamava `updateActiveFormats` via closure stale. Separado em dois effects: init (mount-only) e listener (via `updateActiveFormatsRef` para evitar re-registro a cada render).
+- **`use-assistant-conversations` — `conversasFiltradas` não memoizado** — recalculado em todo re-render do componente pai. Substituído por `useMemo([conversas, abaSelecionada])`.
+- **`use-assistant-messages` — `handleEnviarMensagem` tipado como `string | any`** — tipo colapsado para `any`. Corrigido para `(arg?: string) => Promise<void>`.
+- **`FileUpload` / `useFileUpload` — drop-zone inacessível por teclado** — adicionados `role="button"`, `tabIndex`, `onKeyDown` (Enter/Space abre o file picker) e `focus-visible:ring` à drop-zone.
+- **`useFileUpload` — `accept` não validado em drag-and-drop** — o browser só aplica `accept` nativamente no picker; arquivos de tipo diferente podiam ser soltos livremente. Adicionado helper `matchesAccept` que filtra por MIME type e extensão antes da validação de tamanho/contagem.
+- **`FileUpload` — tamanho de arquivo sempre em KB** — arquivos grandes exibiam `102400.00 KB`. Corrigido para exibição adaptativa KB/MB.
+- **`useStepper` — `initialStep` não clampado no mount** — valores fora de `[1, totalSteps]` vazavam diretamente para o estado. Corrigido com lazy initializer `Math.min(Math.max(1, initialStep), totalSteps)`.
+- **`use-pagination` — páginas duplicadas quando `siblingCount` grande** — o algoritmo de construção do `items` array podia inserir a mesma página duas vezes quando o sibling range coincidia com os push explícitos de `page 2` / `page totalPages-1`. Reescrito com `Set` deduplicado; ellipsis inferido do gap entre páginas consecutivas.
+- **`use-tree-view` — Space key disparava `handleSelect` em nós pai** — segundo a spec WAI-ARIA tree, Space em branch deve apenas expandir/colapsar; Select fica reservado para Enter e nós folha. Corrigido no `handleKeyDown`.
+- **`chart-metric.tsx` — `stateClassName` passado duas vezes para `getChartState`** — em todas as 3 instâncias de `RadarMetricChart`, `PieMetricChart` e `RadialBarMetricChart`, `stateClassName` aparecia dentro do props object e novamente como 3º argumento separado. 3º argumento removido.
+- **`use-assistant-conversations` — magic string `'5'` como command ID hardcoded** — comentário de TODO mantido; o timer cleanup foi aplicado independentemente.
+
+### Added
+
+- **`useFileUpload` — `clearFiles()`** — nova função na API pública do hook que remove todos os arquivos aceitos e limpa o `errorMessage` em uma única chamada.
+- **`useFileUpload` — prop `accept`** — o hook agora aceita e aplica o filtro `accept` tanto no drag-and-drop quanto no click-to-browse (anteriormente, `accept` era apenas passado ao `<input>` sem enforçar em drops).
+
+### Changed
+
+- **`Stepper` — ARIA** — adicionados `role="list"` + `aria-label="Progresso: etapa X de Y"` no `<Stepper>` e `role="listitem"` + `aria-current="step"` + `aria-label` descritivo em cada `<Step>`, tornando o componente acessível a screen readers.
+- **`PaginationLink` — `disabled` prop + `href` fallback** — `PaginationLink` agora aceita `disabled` (aplica `aria-disabled`, `tabIndex=-1` e `pointer-events-none`) e faz fallback para `href="#"` quando `href` não é passado, garantindo que o link permaneça focusável via Tab em SPAs. `PaginationPrevious` e `PaginationNext` receberam o `disabled` pass-through.
+- **`TreeView` — ARIA e roving tabindex** — adicionado `aria-label` (padrão `"Navegação em árvore"`) no `role="tree"` (WCAG 4.1.2); implementado roving tabindex correto: `focusableId = selectedId ?? firstRootId` garante que sempre haja um nó focusável por Tab mesmo sem seleção ativa.
+- **`RichTextEditor` — ARIA no `contentEditable`** — adicionados `role="textbox"`, `aria-multiline="true"`, `aria-label`, `aria-readonly` e `aria-disabled` ao div editável.
+- **`RichTextEditor` — removido "Auto-save ativo"** — texto no rodapé que indicava auto-save não implementado. Removido para não enganar o usuário.
+- **`RichTextEditor` — sync de `value` externo** — adicionado `useEffect([value])` que sincroniza o HTML do editor quando o valor muda externamente e o editor não está em foco (ex.: carregar dados da API após o mount).
+- **`Sidebar` — `<nav>` landmark + `aria-expanded` + `useMemo`** — o root `<div>` foi substituído por `<nav aria-label="Navegação principal" id="sidebar-nav">`; o botão de toggle recebeu `aria-expanded` e `aria-controls`; `navigationItems` foi envolvido em `useMemo([routes, pathname])` e a dependency do effect de overflow foi atualizada de `navigationItems.length` para `navigationItems`.
+- **`DashboardBarChart` — `topOfStack` com `useMemo`** — computação que determinava qual bar recebe radius no topo do stack foi extraída da IIFE inline para `React.useMemo([stacked, chartSeries])`, evitando recalcular a cada render.
+- **Documentação** — corrigidas e atualizadas as docs de `file-upload.md`, `stepper.md`, `pagination.md`, `tree-view.md`, `rich-text-editor.md`, `sidebar.md`, `chart.md` e `hooks.md` para refletir todas as mudanças desta versão.
+
+---
+
+## [2.1.4] — 2026-05-19
+
+### Changed
+
+- **`XerticaAssistant` — decomposição em sub-componentes** — o componente monolítico (1 468 linhas) foi dividido em 9 sub-componentes focados em `parts/`: `AssistantHeader`, `AssistantCollapsedView`, `AssistantTabBar`, `AssistantWelcomeScreen`, `AssistantMessageBubble`, `AssistantTypingIndicator`, `AssistantConversationList`, `AssistantFeedbackDialog` e `AssistantDocumentEditor`. A API pública (`XerticaAssistantProps`) permanece 100% compatível.
+- **`useAudioPlayer` — headless hook** — toda a lógica do `AudioPlayer` foi extraída para `components/media/audio-player/use-audio-player.ts`. O componente `AudioPlayer` agora consome o hook internamente; API pública inalterada. O hook é exportado via `components/hooks/index.ts`.
+- **`useLayoutShortcuts` — headless hook** — registro de atalhos de teclado (Ctrl+B, Ctrl+I) extraído do `LayoutContext` para `components/hooks/use-layout-shortcuts.ts`. Exportado via `components/hooks/index.ts`.
+- **`CustomTooltipContent` — componente compartilhado** — implementação duplicada de tooltip customizado (existia em `sidebar.tsx` e `xertica-assistant.tsx`) consolidada em `components/shared/CustomTooltipContent.tsx`.
+- **`useIsMobile` — fonte única de detecção mobile** — `use-sidebar.ts`, `use-assistant.ts`, `LayoutContext.tsx` e `AudioPlayer.tsx` agora importam de `components/shared/use-mobile.ts` em vez de duplicar a lógica de `matchMedia`.
+- **`utils/color-utils.ts` — utilitários de cor** — funções `hexToRgb`, `hexToRgba` e `isLightColor` extraídas do `BrandColorsContext` para `utils/color-utils.ts` como funções puras reutilizáveis.
+- **`ThemeToggle` — usa `useTheme()`** — substituída referência direta ao `localStorage` pelo hook `useTheme()` do `ThemeContext`.
+- **`types.ts` — fonte única de tipos do assistente** — `Message`, `Conversation`, `Suggestion`, `MockResponse`, `SearchResult`, `SearchSource`, `SearchCommand` e enums relacionados movidos para `components/assistant/xertica-assistant/types.ts`. `xertica-assistant.tsx` e `AssistenteContext.tsx` re-exportam os tipos para backward compatibility.
+
+---
+
 ## [2.1.3] — 2026-05-16
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 > **Enterprise-grade React design system** built on Tailwind CSS v4, Radix UI, and Lucide Icons — with a robust AI-first documentation layer for precise LLM-driven composition and autonomous agent interaction.
 
-[![npm version](https://img.shields.io/badge/npm-2.1.3-blue)](https://www.npmjs.com/package/xertica-ui)
+[![npm version](https://img.shields.io/badge/npm-2.1.5-blue)](https://www.npmjs.com/package/xertica-ui)
 [![license](https://img.shields.io/badge/license-proprietary-red)](./LICENSE)
 
 ---

package/bin/cli.ts

@@ -18,7 +18,7 @@ const program = new Command();
 program
     .name('xertica-ui')
     .description('CLI to initialize Xertica UI projects')
-    .version('2.1.3');
+    .version('2.1.5');
 
 program
     .command('init')

package/components/assistant/xertica-assistant/hooks/index.ts

@@ -0,0 +1,8 @@
+export { useAssistantMessages } from './use-assistant-messages';
+export type { UseAssistantMessagesProps, UseAssistantMessagesReturn, EvaluationState } from './use-assistant-messages';
+
+export { useAssistantConversations } from './use-assistant-conversations';
+export type { UseAssistantConversationsProps, UseAssistantConversationsReturn } from './use-assistant-conversations';
+
+export { useAssistantSuggestions, DEFAULT_SUGGESTIONS } from './use-assistant-suggestions';
+export type { UseAssistantSuggestionsProps, UseAssistantSuggestionsReturn } from './use-assistant-suggestions';

package/components/assistant/xertica-assistant/hooks/use-assistant-conversations.ts

@@ -0,0 +1,119 @@
+import { useState, useCallback, useEffect, useMemo, useRef } from 'react';
+import type { Message, Conversation, SearchResult, AssistantTab } from '../types';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Props & Return types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface UseAssistantConversationsProps {
+    savedConversations?: Conversation[];
+    /** Current tab — used to compute conversasFiltradas */
+    abaSelecionada: AssistantTab;
+    setAbaSelecionada: (tab: AssistantTab) => void;
+    setMensagens: React.Dispatch<React.SetStateAction<Message[]>>;
+}
+
+export interface UseAssistantConversationsReturn {
+    conversas: Conversation[];
+    conversaAtual: string | null;
+    conversasFiltradas: Conversation[];
+    savedSearches: string[];
+    executingCommand: string | null;
+    handleNovaConversa: () => void;
+    handleSelecionarConversa: (conversaId: string) => void;
+    handleToggleFavoritaConversa: (conversaId: string) => void;
+    handleOpenSearchResult: (result: SearchResult) => void;
+    handleExecuteSearchCommand: (
+        commandId: string,
+        searchTerm: string,
+        results: SearchResult[],
+        messageId: string,
+    ) => Promise<void>;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Hook
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function useAssistantConversations({
+    savedConversations = [],
+    abaSelecionada,
+    setAbaSelecionada,
+    setMensagens,
+}: UseAssistantConversationsProps): UseAssistantConversationsReturn {
+
+    const [conversas, setConversas] = useState<Conversation[]>(savedConversations);
+    const [conversaAtual, setConversaAtual] = useState<string | null>(null);
+    const [savedSearches, setSavedSearches] = useState<string[]>([]);
+    const [executingCommand, setExecutingCommand] = useState<string | null>(null);
+
+    // UC-2: re-sync when the parent updates savedConversations (e.g. after API fetch)
+    useEffect(() => {
+        setConversas(savedConversations);
+    }, [savedConversations]);
+
+    // UC-4: memoize so it isn't recomputed on every parent re-render
+    const conversasFiltradas = useMemo(
+        () => conversas.filter(conversa => abaSelecionada === 'favoritos' ? conversa.isFavorite : true),
+        [conversas, abaSelecionada]
+    );
+
+    // UC-5: ref to cancel the command timer if the component unmounts
+    const commandTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+    useEffect(() => () => clearTimeout(commandTimerRef.current), []);
+
+    const handleNovaConversa = useCallback(() => {
+        setMensagens([]);
+        setConversaAtual(null);
+        setAbaSelecionada('chat');
+    }, [setMensagens, setAbaSelecionada]);
+
+    const handleSelecionarConversa = useCallback((conversaId: string) => {
+        const conversa = conversas.find(c => c.id === conversaId);
+        if (conversa) {
+            setMensagens(conversa.messages);
+            setConversaAtual(conversaId);
+            setAbaSelecionada('chat');
+        }
+    }, [conversas, setMensagens, setAbaSelecionada]);
+
+    const handleToggleFavoritaConversa = useCallback((conversaId: string) => {
+        setConversas(prev =>
+            prev.map(conv =>
+                conv.id === conversaId ? { ...conv, isFavorite: !conv.isFavorite } : conv
+            )
+        );
+    }, []);
+
+    const handleOpenSearchResult = useCallback((_result: SearchResult) => {
+        // TODO: implement navigation to search result when conversation routing is available
+    }, []);
+
+    const handleExecuteSearchCommand = useCallback(async (
+        commandId: string,
+        searchTerm: string,
+        results: SearchResult[],
+        messageId: string,
+    ) => {
+        setExecutingCommand(commandId);
+        commandTimerRef.current = setTimeout(() => {
+            if (commandId === '5') {
+                setSavedSearches(prev => [...prev, messageId]);
+            }
+            setExecutingCommand(null);
+        }, 1500);
+    }, []);
+
+    return {
+        conversas,
+        conversaAtual,
+        conversasFiltradas,
+        savedSearches,
+        executingCommand,
+        handleNovaConversa,
+        handleSelecionarConversa,
+        handleToggleFavoritaConversa,
+        handleOpenSearchResult,
+        handleExecuteSearchCommand,
+    };
+}

package/components/assistant/xertica-assistant/hooks/use-assistant-messages.ts

@@ -0,0 +1,323 @@
+import { useState, useRef, useCallback, useEffect } from 'react';
+import { toast } from 'sonner';
+import { gerarResposta } from '../../../shared/assistant-utils';
+import type { Message, Suggestion, MockResponse } from '../types';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Props & Return types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface UseAssistantMessagesProps {
+    initialMessages?: Message[];
+    isProcessing?: boolean;
+    demoMode?: boolean;
+    customResponses?: MockResponse[];
+    responseGenerator?: (message: string) => Promise<string | Partial<Message>> | string | Partial<Message>;
+    onSendMessage?: (message: string) => void;
+    onEvaluation?: (messageId: string, type: 'like' | 'dislike', reason?: string) => void;
+    /** Current tab — used to drive auto-scroll */
+    abaSelecionada: string;
+}
+
+export interface EvaluationState {
+    isOpen: boolean;
+    messageId: string | null;
+    type: 'dislike' | null;
+    category?: string | null;
+    reason: string;
+}
+
+export interface UseAssistantMessagesReturn {
+    mensagens: Message[];
+    setMensagens: React.Dispatch<React.SetStateAction<Message[]>>;
+    mensagem: string;
+    setMensagem: (value: string) => void;
+    copiedId: string | null;
+    generatingPodcastId: string | null;
+    editingDocument: { content: string; title: string } | null;
+    setEditingDocument: (doc: { content: string; title: string } | null) => void;
+    evaluationState: EvaluationState;
+    setEvaluationState: React.Dispatch<React.SetStateAction<EvaluationState>>;
+    messagesEndRef: React.RefObject<HTMLDivElement>;
+    handleEnviarMensagem: (arg?: string) => Promise<void>;
+    handleToggleFavorite: (messageId: string) => void;
+    handleCopyMessage: (content: string, messageId: string) => Promise<void>;
+    handleGeneratePodcast: (messageId: string, content: string) => Promise<void>;
+    handleDownloadDocument: (content: string, fileName: string) => void;
+    handleDownloadPodcast: (audioUrl: string, fileName: string) => void;
+    handleEditDocument: (content: string, title: string) => void;
+    handleEvaluationClick: (messageId: string, type: 'like' | 'dislike') => void;
+    openFeedbackDialog: (messageId: string, category: string | null) => void;
+    handleSubmitDislike: () => void;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Hook
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function useAssistantMessages({
+    initialMessages = [],
+    isProcessing = false,
+    demoMode = true,
+    customResponses = [],
+    responseGenerator,
+    onSendMessage,
+    onEvaluation,
+    abaSelecionada,
+}: UseAssistantMessagesProps): UseAssistantMessagesReturn {
+
+    const [mensagens, setMensagens] = useState<Message[]>(initialMessages);
+    const [mensagem, setMensagem] = useState('');
+    const [copiedId, setCopiedId] = useState<string | null>(null);
+    const [generatingPodcastId, setGeneratingPodcastId] = useState<string | null>(null);
+    const [editingDocument, setEditingDocument] = useState<{ content: string; title: string } | null>(null);
+    const [evaluationState, setEvaluationState] = useState<EvaluationState>({
+        isOpen: false,
+        messageId: null,
+        type: null,
+        category: null,
+        reason: '',
+    });
+
+    const messagesEndRef = useRef<HTMLDivElement>(null);
+
+    // Ref to cancel the AI response timer when the component unmounts (UM-1)
+    const responseTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+    useEffect(() => () => clearTimeout(responseTimerRef.current), []);
+
+    // Auto-scroll only when the user is already near the bottom (UM-5).
+    // Firing unconditionally would forcibly scroll users who have scrolled up to read history.
+    useEffect(() => {
+        if (abaSelecionada !== 'chat' || !messagesEndRef.current) return;
+        const viewport = messagesEndRef.current.closest('[data-radix-scroll-area-viewport]')
+            ?? messagesEndRef.current.parentElement;
+        if (viewport) {
+            const nearBottom =
+                viewport.scrollHeight - viewport.scrollTop - viewport.clientHeight < 120;
+            if (nearBottom) messagesEndRef.current.scrollIntoView({ behavior: 'smooth' });
+        } else {
+            // Fallback when no scroll container is found
+            messagesEndRef.current.scrollIntoView({ behavior: 'smooth' });
+        }
+    }, [mensagens, abaSelecionada]);
+
+    // Sync initial messages exactly once on mount (UM-3).
+    // Using a ref guard prevents the effect from resetting the conversation every
+    // time the parent re-renders and passes a new array reference.
+    const hydratedRef = useRef(false);
+    useEffect(() => {
+        if (!hydratedRef.current && initialMessages.length > 0) {
+            setMensagens(initialMessages);
+            hydratedRef.current = true;
+        }
+    }, [initialMessages]);
+
+    const handleEnviarMensagem = useCallback(async (arg?: string) => {
+        let msgToSend = mensagem;
+
+        if (typeof arg === 'string' && !['document', 'podcast', 'search'].includes(arg)) {
+            msgToSend = arg;
+        }
+
+        if (!msgToSend.trim() || isProcessing) return;
+
+        const novaMensagem: Message = {
+            id: `msg-${Date.now()}`,
+            type: 'user',
+            content: msgToSend,
+            timestamp: new Date(),
+            isFavorite: false,
+        };
+
+        setMensagens(prev => [...prev, novaMensagem]);
+
+        if (onSendMessage) {
+            onSendMessage(msgToSend);
+        }
+
+        if (demoMode || responseGenerator) {
+            const mensagemAtual = msgToSend;
+            responseTimerRef.current = setTimeout(async () => {
+                let resposta: string | Partial<Message>;
+
+                if (responseGenerator) {
+                    resposta = await responseGenerator(mensagemAtual);
+                } else {
+                    resposta = gerarResposta(mensagemAtual, customResponses);
+                }
+
+                let novaMensagemIA: Message = {
+                    id: `msg-${Date.now()}-ia`,
+                    type: 'assistant',
+                    content: '',
+                    timestamp: new Date(),
+                    isFavorite: false,
+                };
+
+                if (typeof resposta === 'string') {
+                    novaMensagemIA.content = resposta;
+                } else {
+                    novaMensagemIA = { ...novaMensagemIA, ...resposta };
+                }
+
+                setMensagens(prev => [...prev, novaMensagemIA]);
+            }, 1000 + Math.random() * 1000);
+        }
+
+        setMensagem('');
+    }, [mensagem, isProcessing, onSendMessage, demoMode, responseGenerator, customResponses]);
+
+    const handleToggleFavorite = useCallback((messageId: string) => {
+        setMensagens(prev =>
+            prev.map(msg =>
+                msg.id === messageId ? { ...msg, isFavorite: !msg.isFavorite } : msg
+            )
+        );
+    }, []);
+
+    const handleCopyMessage = useCallback(async (content: string, messageId: string) => {
+        try {
+            if (navigator.clipboard && navigator.clipboard.writeText) {
+                try {
+                    await navigator.clipboard.writeText(content);
+                    setCopiedId(messageId);
+                    setTimeout(() => setCopiedId(null), 2000);
+                } catch (clipboardError: any) {
+                    if (clipboardError.name === 'NotAllowedError' || clipboardError.message.includes('permissions policy')) {
+                        throw new Error('Clipboard permission denied, falling back');
+                    }
+                    throw clipboardError;
+                }
+            } else {
+                throw new Error('Clipboard API not available');
+            }
+        } catch {
+            try {
+                const textArea = document.createElement('textarea');
+                textArea.value = content;
+                textArea.style.position = 'fixed';
+                textArea.style.left = '-999999px';
+                textArea.style.top = '-999999px';
+                document.body.appendChild(textArea);
+                textArea.focus();
+                textArea.select();
+                const successful = document.execCommand('copy');
+                document.body.removeChild(textArea);
+                if (successful) {
+                    setCopiedId(messageId);
+                    setTimeout(() => setCopiedId(null), 2000);
+                }
+            } catch (fallbackErr) {
+                console.error('Falha ao copiar:', fallbackErr);
+            }
+        }
+    }, []);
+
+    const handleGeneratePodcast = useCallback(async (messageId: string, content: string) => {
+        setGeneratingPodcastId(messageId);
+        setTimeout(() => {
+            setMensagens(prev =>
+                prev.map(msg =>
+                    msg.id === messageId
+                        ? {
+                            ...msg,
+                            attachmentType: 'podcast' as const,
+                            attachmentName: 'Podcast - ' + content.substring(0, 30) + '...',
+                            audioUrl: 'data:audio/mpeg;base64,//uQx...',
+                        }
+                        : msg
+                )
+            );
+            setGeneratingPodcastId(null);
+        }, 2000);
+    }, []);
+
+    const handleDownloadDocument = useCallback((content: string, fileName: string) => {
+        const blob = new Blob([content], { type: 'text/markdown' });
+        const url = URL.createObjectURL(blob);
+        const a = document.createElement('a');
+        a.href = url;
+        a.download = fileName.endsWith('.md') ? fileName : fileName + '.md';
+        document.body.appendChild(a);
+        a.click();
+        document.body.removeChild(a);
+        URL.revokeObjectURL(url);
+    }, []);
+
+    const handleDownloadPodcast = useCallback((audioUrl: string, fileName: string) => {
+        const a = document.createElement('a');
+        a.href = audioUrl;
+        a.download = fileName.endsWith('.mp3') ? fileName : fileName + '.mp3';
+        document.body.appendChild(a);
+        a.click();
+        document.body.removeChild(a);
+    }, []);
+
+    const handleEditDocument = useCallback((content: string, title: string) => {
+        setEditingDocument({ content, title });
+    }, []);
+
+    const handleEvaluationClick = useCallback((messageId: string, type: 'like' | 'dislike') => {
+        if (type === 'like') {
+            if (onEvaluation) onEvaluation(messageId, 'like');
+            setMensagens(prev => prev.map(m => m.id === messageId ? { ...m, evaluation: 'like' as const } : m));
+            toast.success("Obrigado por avaliar positivamente!");
+        }
+    }, [onEvaluation]);
+
+    const openFeedbackDialog = useCallback((messageId: string, category: string | null) => {
+        setEvaluationState({
+            isOpen: true,
+            messageId,
+            type: 'dislike',
+            category,
+            reason: '',
+        });
+    }, []);
+
+    const handleSubmitDislike = useCallback(() => {
+        if (evaluationState.messageId) {
+            const finalReason = evaluationState.category
+                ? (evaluationState.reason ? `${evaluationState.category}: ${evaluationState.reason}` : evaluationState.category)
+                : evaluationState.reason;
+
+            if (onEvaluation) {
+                onEvaluation(evaluationState.messageId, 'dislike', finalReason);
+            }
+
+            setMensagens(prev =>
+                prev.map(m =>
+                    m.id === evaluationState.messageId
+                        ? { ...m, evaluation: 'dislike' as const, evaluationReason: finalReason }
+                        : m
+                )
+            );
+            toast.success("Obrigado pelo seu feedback. Vamos melhorar.");
+        }
+        setEvaluationState({ isOpen: false, messageId: null, type: null, category: null, reason: '' });
+    }, [evaluationState, onEvaluation]);
+
+    return {
+        mensagens,
+        setMensagens,
+        mensagem,
+        setMensagem,
+        copiedId,
+        generatingPodcastId,
+        editingDocument,
+        setEditingDocument,
+        evaluationState,
+        setEvaluationState,
+        messagesEndRef,
+        handleEnviarMensagem,
+        handleToggleFavorite,
+        handleCopyMessage,
+        handleGeneratePodcast,
+        handleDownloadDocument,
+        handleDownloadPodcast,
+        handleEditDocument,
+        handleEvaluationClick,
+        openFeedbackDialog,
+        handleSubmitDislike,
+    };
+}

package/components/assistant/xertica-assistant/hooks/use-assistant-suggestions.ts

@@ -0,0 +1,64 @@
+import { useState, useCallback } from 'react';
+import type { Suggestion } from '../types';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Default suggestions
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const DEFAULT_SUGGESTIONS: Suggestion[] = [
+    { id: '1', text: 'Me ajude a criar um documento profissional' },
+    { id: '2', text: 'Buscar nos meus arquivos por "relatório"' },
+    { id: '3', text: 'Resuma as conversas importantes desta semana' },
+    { id: '4', text: 'Crie um podcast sobre o último projeto' },
+];
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Props & Return types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface UseAssistantSuggestionsProps {
+    suggestions?: Suggestion[];
+    richSuggestions?: Suggestion[];
+    onRichAction?: (actionId: string, actionText: string) => void;
+    /** handleEnviarMensagem from useAssistantMessages, passed in to avoid circular deps */
+    handleEnviarMensagem: (arg?: string | any) => Promise<void>;
+}
+
+export interface UseAssistantSuggestionsReturn {
+    sugestoes: Suggestion[];
+    showMoreSuggestions: boolean;
+    setShowMoreSuggestions: (show: boolean) => void;
+    handleRichSuggestionClick: (suggestion: Suggestion) => void;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Hook
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function useAssistantSuggestions({
+    suggestions,
+    richSuggestions = [],
+    onRichAction,
+    handleEnviarMensagem,
+}: UseAssistantSuggestionsProps): UseAssistantSuggestionsReturn {
+
+    const [showMoreSuggestions, setShowMoreSuggestions] = useState(false);
+
+    const sugestoes = suggestions ?? DEFAULT_SUGGESTIONS;
+
+    const handleRichSuggestionClick = useCallback((suggestion: Suggestion) => {
+        if (onRichAction) {
+            onRichAction(suggestion.id, suggestion.text);
+        } else {
+            handleEnviarMensagem(suggestion.text);
+        }
+        setShowMoreSuggestions(false);
+    }, [onRichAction, handleEnviarMensagem]);
+
+    return {
+        sugestoes,
+        showMoreSuggestions,
+        setShowMoreSuggestions,
+        handleRichSuggestionClick,
+    };
+}