xertica-ui 2.1.4 → 2.1.6

package/CHANGELOG.md

@@ -7,6 +7,62 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [2.1.6] — 2026-05-19
+
+### Fixed
+
+- **`templates/HomeContent.tsx` — JSX malformado causava crash da página** — tags `</div>`, `</ScrollArea>` e `</main>` estavam faltando após refatoração para `<PageContent>`, fazendo a página Home quebrar completamente ao renderizar.
+- **`templates/DashboardTemplate.tsx` — `StatsCard.trend` com tipo errado** — `trend` recebia um `number` primitivo (`trend={20.1}`) mas o prop exige um objeto `{ value: number; label?: string }`. Corrigido para `trend={{ value: 20.1, label: 'vs mês anterior' }}` em todos os 4 cards.
+- **`templates/DashboardTemplate.tsx` — `DonutBreakdownChart` com chaves acentuadas** — o `channelConfig` usava chaves como `Orgânico` que falhavam no lookup interno do chart. Renomeadas para ASCII (`organico`, `pago`, `social`, `direto`) com labels legíveis mantidas via `label:`.
+- **`templates/DashboardTemplate.tsx` — cast de `Badge.variant` sem type safety** — `event.status as 'default' | ...` foi substituído por um mapa `EVENT_BADGE_VARIANT` com tipagem `EventStatus` explícita.
+- **`templates/SettingsContent.tsx` — imports duplicados de `xertica-ui/hooks`** — `useTheme` e `useLayout` eram importados em duas linhas separadas do mesmo módulo. Unificados em um único import.
+- **`templates/SettingsContent.tsx` — `Separator`, `Badge` e `useNavigate` importados mas nunca usados** — removidos para evitar erros de lint/build.
+- **`templates/SettingsContent.tsx` — `Switch.onCheckedChange` com tipo incompatível** — `toggleTheme` é `() => void` mas `onCheckedChange` exige `(checked: boolean) => void`. Corrigido com wrapper arrow `() => toggleTheme()`.
+
+---
+
+## [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

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.4-blue)](https://www.npmjs.com/package/xertica-ui)
+[![npm version](https://img.shields.io/badge/npm-2.1.6-blue)](https://www.npmjs.com/package/xertica-ui)
 [![license](https://img.shields.io/badge/license-proprietary-red)](./LICENSE)
 
 ---

package/assets/xertica-logo.svg

@@ -1,38 +1,38 @@
-<svg
-  fill="none"
-  preserveAspectRatio="xMidYMid meet"
-  viewBox="0 0 1543 289"
-  xmlns="http://www.w3.org/2000/svg"
->
-  <g id="Xertica.ai">
-    <path d="M1352.82 239.808V285.425H1304.73V239.808H1352.82Z" fill="#00BEFF" />
-    <path d="M814.8 284.848H766.711V77.4971H814.8V284.848Z" fill="#00BEFF" />
-    <path d="M1543 284.438H1514.2V160.28H1543V284.438Z" fill="#00BEFF" />
-    <path 
-      clip-rule="evenodd"
-      d="M1432.83 157.796C1446.98 157.796 1459.14 162.515 1468.58 170.709V160.28H1497.38V284.438H1468.58V274.01C1459.14 282.451 1446.98 286.921 1432.83 286.921C1395.1 286.921 1368.29 260.352 1368.29 222.359C1368.29 184.616 1395.1 157.796 1432.83 157.796ZM1432.83 183.778C1410.79 183.778 1396.27 199.061 1396.27 222.359C1396.27 245.658 1410.79 260.94 1432.83 260.94C1454.63 260.94 1468.9 245.658 1468.9 222.359C1468.9 199.06 1454.63 183.778 1432.83 183.778Z"
-      fill="#00BEFF"
-      fill-rule="evenodd"
-    />
-    <path d="M947.87 73.3516C1002.88 73.3516 1044.42 107.647 1053.57 159.234H1004.68C997.221 132.988 976.34 117.308 947.87 117.308C911.387 117.308 887.337 142.612 887.337 181.176C887.337 219.739 911.387 245.036 947.87 245.036C976.34 245.036 997.221 229.356 1004.68 203.109H1053.57C1044.47 254.701 1003.26 289 947.87 289C884.853 289 840.078 244.626 840.078 181.176C840.078 118.142 884.854 73.3516 947.87 73.3516Z" fill="#00BEFF" />
-    <path d="M88.4971 39.8242L157.353 142.191L83.5371 251.524L60.9277 284.854H0L96.3154 142.191L5.37695 7H66.3047L88.4971 39.8242Z" fill="#00BEFF" />
-    <path d="M254.314 284.855H193.387L151.914 223.71L182.548 178.551L254.314 284.855Z" fill="#00BEFF" />
-    <path 
-      clip-rule="evenodd"
-      d="M1179.14 73.3477C1202.77 73.3477 1223.08 81.2286 1238.84 94.9121V77.4971H1286.94V284.847H1238.84V267.431C1223.09 281.528 1202.77 288.992 1179.14 288.992C1116.12 288.992 1071.35 244.622 1071.35 181.172C1071.35 118.139 1116.12 73.3478 1179.14 73.3477ZM1179.14 117.308C1142.66 117.308 1118.61 142.604 1118.61 181.172C1118.61 219.739 1142.66 245.035 1179.14 245.035C1215.21 245.035 1238.84 219.739 1238.84 181.172C1238.84 142.605 1215.21 117.308 1179.14 117.308Z"
-      fill="#00BEFF"
-      fill-rule="evenodd"
-    />
-    <path d="M1543 145.383H1514.2V118.067H1543V145.383Z" fill="#00BEFF" />
-    <path d="M672.466 77.501H736.31V121.457H672.466V211.448C672.466 230.939 682.415 240.891 702.313 240.891H736.309V284.852H698.999C649.246 284.851 625.203 259.968 625.203 211.449V7H672.466V77.501Z" fill="#00BEFF" />
-    <path d="M814.8 52.6172H766.711V7H814.8V52.6172Z" fill="#00BEFF" />
-    <path 
-      clip-rule="evenodd"
-      d="M354.069 73.3516C417.086 73.3517 461.864 118.143 461.864 181.176C461.864 187.396 461.031 193.615 460.204 199.422H295.197C301.829 228.864 323.392 246.696 354.069 246.696C372.724 246.696 389.309 241.721 399.675 226.376H452.742C441.132 265.774 400.501 288.996 354.069 288.996C291.053 288.996 246.274 244.626 246.273 181.176C246.273 118.142 291.053 73.3516 354.069 73.3516ZM354.068 115.65C325.044 115.65 303.902 131.826 296.44 158.78H410.863C403.819 131.826 382.672 115.65 354.068 115.65Z"
-      fill="#00BEFF"
-      fill-rule="evenodd"
-    />
-    <path d="M596.957 121.453H562.962C543.064 121.453 533.114 131.409 533.114 150.899V284.847H485.852V150.899C485.852 102.38 509.894 77.4972 559.647 77.4971H596.957V121.453Z" fill="#00BEFF" />
-    <path d="M182.552 98.6992L151.922 53.3906L188.014 0H248.941L182.552 98.6992Z" fill="#00BEFF" />
-  </g>
+<svg
+  fill="none"
+  preserveAspectRatio="xMidYMid meet"
+  viewBox="0 0 1543 289"
+  xmlns="http://www.w3.org/2000/svg"
+>
+  <g id="Xertica.ai">
+    <path d="M1352.82 239.808V285.425H1304.73V239.808H1352.82Z" fill="#00BEFF" />
+    <path d="M814.8 284.848H766.711V77.4971H814.8V284.848Z" fill="#00BEFF" />
+    <path d="M1543 284.438H1514.2V160.28H1543V284.438Z" fill="#00BEFF" />
+    <path 
+      clip-rule="evenodd"
+      d="M1432.83 157.796C1446.98 157.796 1459.14 162.515 1468.58 170.709V160.28H1497.38V284.438H1468.58V274.01C1459.14 282.451 1446.98 286.921 1432.83 286.921C1395.1 286.921 1368.29 260.352 1368.29 222.359C1368.29 184.616 1395.1 157.796 1432.83 157.796ZM1432.83 183.778C1410.79 183.778 1396.27 199.061 1396.27 222.359C1396.27 245.658 1410.79 260.94 1432.83 260.94C1454.63 260.94 1468.9 245.658 1468.9 222.359C1468.9 199.06 1454.63 183.778 1432.83 183.778Z"
+      fill="#00BEFF"
+      fill-rule="evenodd"
+    />
+    <path d="M947.87 73.3516C1002.88 73.3516 1044.42 107.647 1053.57 159.234H1004.68C997.221 132.988 976.34 117.308 947.87 117.308C911.387 117.308 887.337 142.612 887.337 181.176C887.337 219.739 911.387 245.036 947.87 245.036C976.34 245.036 997.221 229.356 1004.68 203.109H1053.57C1044.47 254.701 1003.26 289 947.87 289C884.853 289 840.078 244.626 840.078 181.176C840.078 118.142 884.854 73.3516 947.87 73.3516Z" fill="#00BEFF" />
+    <path d="M88.4971 39.8242L157.353 142.191L83.5371 251.524L60.9277 284.854H0L96.3154 142.191L5.37695 7H66.3047L88.4971 39.8242Z" fill="#00BEFF" />
+    <path d="M254.314 284.855H193.387L151.914 223.71L182.548 178.551L254.314 284.855Z" fill="#00BEFF" />
+    <path 
+      clip-rule="evenodd"
+      d="M1179.14 73.3477C1202.77 73.3477 1223.08 81.2286 1238.84 94.9121V77.4971H1286.94V284.847H1238.84V267.431C1223.09 281.528 1202.77 288.992 1179.14 288.992C1116.12 288.992 1071.35 244.622 1071.35 181.172C1071.35 118.139 1116.12 73.3478 1179.14 73.3477ZM1179.14 117.308C1142.66 117.308 1118.61 142.604 1118.61 181.172C1118.61 219.739 1142.66 245.035 1179.14 245.035C1215.21 245.035 1238.84 219.739 1238.84 181.172C1238.84 142.605 1215.21 117.308 1179.14 117.308Z"
+      fill="#00BEFF"
+      fill-rule="evenodd"
+    />
+    <path d="M1543 145.383H1514.2V118.067H1543V145.383Z" fill="#00BEFF" />
+    <path d="M672.466 77.501H736.31V121.457H672.466V211.448C672.466 230.939 682.415 240.891 702.313 240.891H736.309V284.852H698.999C649.246 284.851 625.203 259.968 625.203 211.449V7H672.466V77.501Z" fill="#00BEFF" />
+    <path d="M814.8 52.6172H766.711V7H814.8V52.6172Z" fill="#00BEFF" />
+    <path 
+      clip-rule="evenodd"
+      d="M354.069 73.3516C417.086 73.3517 461.864 118.143 461.864 181.176C461.864 187.396 461.031 193.615 460.204 199.422H295.197C301.829 228.864 323.392 246.696 354.069 246.696C372.724 246.696 389.309 241.721 399.675 226.376H452.742C441.132 265.774 400.501 288.996 354.069 288.996C291.053 288.996 246.274 244.626 246.273 181.176C246.273 118.142 291.053 73.3516 354.069 73.3516ZM354.068 115.65C325.044 115.65 303.902 131.826 296.44 158.78H410.863C403.819 131.826 382.672 115.65 354.068 115.65Z"
+      fill="#00BEFF"
+      fill-rule="evenodd"
+    />
+    <path d="M596.957 121.453H562.962C543.064 121.453 533.114 131.409 533.114 150.899V284.847H485.852V150.899C485.852 102.38 509.894 77.4972 559.647 77.4971H596.957V121.453Z" fill="#00BEFF" />
+    <path d="M182.552 98.6992L151.922 53.3906L188.014 0H248.941L182.552 98.6992Z" fill="#00BEFF" />
+  </g>
 </svg>

package/assets/xertica-x-logo.svg

@@ -1,21 +1,21 @@
-<svg
-  fill="none"
-  preserveAspectRatio="xMidYMid meet"
-  viewBox="0 0 258 282"
-  xmlns="http://www.w3.org/2000/svg"
->
-  <g id="Xertica X">
-    <path 
-      d="M67.2666 0.0361328L89.7793 33.3447L159.63 137.228L84.7471 248.178L61.8115 282H0L97.7109 137.228L5.45508 0.0361328H67.2666Z" 
-      fill="#00BEFF" 
-    />
-    <path 
-      d="M258 282H196.185L154.114 219.951L185.192 174.123L258 282Z" 
-      fill="#00BEFF" 
-    />
-    <path 
-      d="M252.696 0.186523L185.042 100.142L154.106 54.0693L190.884 0L252.696 0.186523Z" 
-      fill="#00BEFF" 
-    />
-  </g>
+<svg
+  fill="none"
+  preserveAspectRatio="xMidYMid meet"
+  viewBox="0 0 258 282"
+  xmlns="http://www.w3.org/2000/svg"
+>
+  <g id="Xertica X">
+    <path 
+      d="M67.2666 0.0361328L89.7793 33.3447L159.63 137.228L84.7471 248.178L61.8115 282H0L97.7109 137.228L5.45508 0.0361328H67.2666Z" 
+      fill="#00BEFF" 
+    />
+    <path 
+      d="M258 282H196.185L154.114 219.951L185.192 174.123L258 282Z" 
+      fill="#00BEFF" 
+    />
+    <path 
+      d="M252.696 0.186523L185.042 100.142L154.106 54.0693L190.884 0L252.696 0.186523Z" 
+      fill="#00BEFF" 
+    />
+  </g>
 </svg>

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.6');
 
 program
     .command('init')

package/components/assistant/index.ts

@@ -1,6 +1,6 @@
-export * from './xertica-assistant';
-export { CodeBlock } from './code-block';
-export { MarkdownMessage } from './markdown-message';
-export { ModernChatInput } from './modern-chat-input';
-export { FormattedDocument } from './formatted-document';
-export { generateDemoResponse } from '../../utils/demo-responses';
+export * from './xertica-assistant';
+export { CodeBlock } from './code-block';
+export { MarkdownMessage } from './markdown-message';
+export { ModernChatInput } from './modern-chat-input';
+export { FormattedDocument } from './formatted-document';
+export { generateDemoResponse } from '../../utils/demo-responses';

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,
+    };
+}