xertica-ui 2.3.0 → 2.4.0

package/docs/architecture-improvements.md

@@ -1,456 +1,456 @@
-# Relatório de Melhorias Arquiteturais
-
-> **Objetivo:** Identificar oportunidades para melhorar a separação entre UI e lógica de negócio, tornando o projeto mais moderno, testável e manutenível.
->
-> **Data da análise:** Maio 2026  
-> **Escopo:** Todos os componentes, hooks e contextos do projeto
-
----
-
-## Sumário Executivo
-
-O projeto já adota boas práticas em vários pontos — o padrão **headless hook** está presente em `useRichTextEditor`, `useTreeView`, `useSidebar` e `useAssistant`. No entanto, existem **inconsistências** onde a mesma lógica é duplicada em múltiplos lugares e componentes com mais de 600 linhas misturam JSX com lógica de estado.
-
-### Severidade dos Problemas
-
-| Severidade | Quantidade | Exemplos                                                                                                                                |
-| ---------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| 🔴 Crítico | 1 ~~2~~    | ~~`ThemeToggle` bypassa `ThemeContext`~~ ✅ resolvido em v2.2.0; tipos duplicados entre contextos                                       |
-| 🟠 Alto    | 3          | `AudioPlayer` sem hook; detecção mobile duplicada 4×; `xertica-assistant.tsx` com 1573 linhas                                           |
-| 🟡 Médio   | 4          | `sidebar.tsx` com 1089 linhas; atalhos de teclado no `LayoutContext`; `BrandColorsContext` com utilitário inline; `header.tsx` sem hook |
-| 🟢 Baixo   | 3          | `SidebarTooltipContent` duplicado; `AssistantTooltipContent` inline; cookie management inline                                           |
-
----
-
-## 🔴 Problemas Críticos
-
-### C1 — `ThemeToggle` bypassa `ThemeContext` completamente ✅ RESOLVIDO (v2.2.0)
-
-**Arquivo:** [`components/brand/theme-toggle/ThemeToggle.tsx`](../components/brand/theme-toggle/ThemeToggle.tsx)
-
-**Resolução:** O `ThemeToggle` foi corrigido para usar `useTheme()` do `ThemeContext`. Adicionalmente, o bug `disableDarkMode` foi corrigido em `templates/src/app/App.tsx` e `bin/language-config.ts` — o prop estava hard-coded como `true`, tornando o `toggleTheme()` um no-op em projetos gerados pelo CLI. O `ThemeToggle` agora funciona corretamente tanto no projeto base quanto em projetos gerados.
-
-<details>
-<summary>Análise original (histórico)</summary>
-
-**Problema original:** O componente `ThemeToggle` manipulava `document.documentElement.classList` diretamente e mantinha seu próprio estado local com `useState`, ignorando completamente o `ThemeContext` e o hook `useTheme()`. Isso criava um **risco de dessincronização**: se o tema fosse alterado via `ThemeContext` (ex: por outro componente ou por `defaultTheme`), o `ThemeToggle` não refletiria a mudança.
-
-Adicionalmente, em projetos gerados pelo CLI, `XerticaProvider` era instanciado com `disableDarkMode` hard-coded, fazendo `toggleTheme()` retornar imediatamente sem efeito.
-
-</details>
-
----
-
-### C2 — Tipos duplicados entre `AssistenteContext` e `xertica-assistant.tsx`
-
-**Arquivos:**
-
-- [`contexts/AssistenteContext.tsx`](../contexts/AssistenteContext.tsx) — linhas 5–71
-- [`components/assistant/xertica-assistant/xertica-assistant.tsx`](../components/assistant/xertica-assistant/xertica-assistant.tsx) — linhas 155–230
-
-**Problema:** Os mesmos tipos são definidos em dois lugares com nomes e estruturas ligeiramente diferentes:
-
-| `AssistenteContext.tsx` | `xertica-assistant.tsx` | Diferença                            |
-| ----------------------- | ----------------------- | ------------------------------------ |
-| `Message`               | `Message`               | Campos diferentes (`role` vs `type`) |
-| `Conversa`              | `Conversation`          | Nome diferente, campos em PT vs EN   |
-| `SearchResult`          | `SearchResult`          | Duplicado idêntico                   |
-| `SearchSource`          | `SearchSource`          | Duplicado idêntico                   |
-| `SearchCommand`         | `SearchCommand`         | Duplicado idêntico                   |
-
-Isso significa que existem **dois contratos de tipo incompatíveis** para os mesmos dados, forçando conversões implícitas e tornando refatorações perigosas.
-
-**Solução:** Criar um arquivo de tipos compartilhado:
-
-```
-components/assistant/xertica-assistant/
-├── types.ts          ← NOVO: fonte única de verdade para todos os tipos
-├── use-assistant.ts  ← importa de types.ts
-├── xertica-assistant.tsx ← importa de types.ts
-contexts/
-└── AssistenteContext.tsx ← importa de types.ts (re-exporta para compatibilidade)
-```
-
-```ts
-// components/assistant/xertica-assistant/types.ts
-export interface Message { ... }
-export interface Conversation { ... }
-export interface SearchResult { ... }
-// ...
-
-// contexts/AssistenteContext.tsx
-export type { Message, Conversation, SearchResult } from '@/components/assistant/xertica-assistant/types';
-```
-
----
-
-## 🟠 Problemas de Alta Prioridade
-
-### A1 — Detecção de mobile duplicada em 4+ lugares
-
-**Problema:** A lógica `window.innerWidth < 768` está duplicada em:
-
-| Arquivo                                                                                                                 | Linha | Forma                            |
-| ----------------------------------------------------------------------------------------------------------------------- | ----- | -------------------------------- |
-| [`components/shared/use-mobile.ts`](../components/shared/use-mobile.ts)                                                 | 18    | `useIsMobile()` hook ✅          |
-| [`components/assistant/xertica-assistant/use-assistant.ts`](../components/assistant/xertica-assistant/use-assistant.ts) | ~192  | `window.innerWidth < 768` inline |
-| [`components/layout/sidebar/use-sidebar.ts`](../components/layout/sidebar/use-sidebar.ts)                               | ~46   | `window.innerWidth < 768` inline |
-| [`components/media/audio-player/AudioPlayer.tsx`](../components/media/audio-player/AudioPlayer.tsx)                     | ~113  | `window.innerWidth < 768` inline |
-| [`contexts/LayoutContext.tsx`](../contexts/LayoutContext.tsx)                                                           | ~60   | `window.innerWidth < 768` inline |
-
-O hook `useIsMobile()` **já existe** em `components/shared/use-mobile.ts` e usa `matchMedia` (mais eficiente que `resize` events), mas não está sendo usado pelos outros arquivos.
-
-**Solução:** Substituir todas as ocorrências pelo hook existente:
-
-```ts
-// ❌ ATUAL
-const [isMobileViewport, setIsMobileViewport] = useState(window.innerWidth < 768);
-useEffect(() => {
-  const handleResize = () => setIsMobileViewport(window.innerWidth < 768);
-  window.addEventListener('resize', handleResize);
-  return () => window.removeEventListener('resize', handleResize);
-}, []);
-
-// ✅ CORRETO
-import { useIsMobile } from '@/components/shared/use-mobile';
-const isMobileViewport = useIsMobile();
-```
-
-**Impacto:** Reduz código duplicado, garante breakpoint consistente (768px), usa `matchMedia` que é mais performático que `resize` events.
-
----
-
-### A2 — `AudioPlayer.tsx` (663 linhas) sem hook headless
-
-**Arquivo:** [`components/media/audio-player/AudioPlayer.tsx`](../components/media/audio-player/AudioPlayer.tsx)
-
-**Problema:** Todo o estado e lógica do player de áudio está inline no componente, misturado com JSX. Inclui:
-
-- Gerenciamento de estado (`isPlaying`, `currentTime`, `duration`, `volume`, `playbackRate`, `isFloating`)
-- `IntersectionObserver` para auto-float
-- Sincronização de áudio com `useEffect`
-- Detecção de mobile (duplicada)
-- Formatação de tempo (`formatTime`)
-- Handlers de eventos (`togglePlay`, `handleSeek`, `handleVolumeChange`, `handleSetFloating`)
-
-**Solução:** Extrair para `use-audio-player.ts`:
-
-```ts
-// components/media/audio-player/use-audio-player.ts
-export interface UseAudioPlayerProps {
-  src: string;
-  autoFloat?: boolean;
-  onEnded?: () => void;
-}
-
-export interface UseAudioPlayerReturn {
-  audioRef: React.RefObject<HTMLAudioElement>;
-  containerRef: React.RefObject<HTMLDivElement>;
-  isPlaying: boolean;
-  currentTime: number;
-  duration: number;
-  volume: number;
-  playbackRate: number;
-  isFloating: boolean;
-  isMobile: boolean;
-  togglePlay: () => void;
-  handleSeek: (value: number[]) => void;
-  handleVolumeChange: (value: number[]) => void;
-  handleSetFloating: (floating: boolean) => void;
-  setPlaybackRate: (rate: number) => void;
-  formatTime: (time: number) => string;
-}
-
-export function useAudioPlayer(props: UseAudioPlayerProps): UseAudioPlayerReturn { ... }
-```
-
-**Benefícios:**
-
-- `AudioPlayer.tsx` fica com ~200 linhas de JSX puro
-- Lógica do player pode ser testada unitariamente sem renderizar DOM
-- Permite criar variantes do player (mini, fullscreen) reusando o mesmo hook
-
----
-
-### A3 — `xertica-assistant.tsx` com 1573 linhas — decomposição necessária
-
-**Arquivo:** [`components/assistant/xertica-assistant/xertica-assistant.tsx`](../components/assistant/xertica-assistant/xertica-assistant.tsx)
-
-**Problema:** Mesmo com o `useAssistant` hook extraindo a lógica de estado, o componente ainda tem ~1000 linhas de JSX com sub-componentes definidos inline e seções de renderização muito longas.
-
-**Estrutura atual:**
-
-```
-xertica-assistant.tsx (1573 linhas)
-├── AssistantTooltipContent (componente inline, linhas 105-131)
-├── Tipos exportados (linhas 155-230) ← deveria estar em types.ts
-├── XerticaAssistantProps (linhas 246-417) ← 171 linhas de interface!
-└── XerticaAssistant (linhas 467-1572)
-    ├── Document editor overlay (linhas 598-694)
-    ├── Collapsed view (linhas 695-827)
-    ├── Chat messages list (linhas 888-1394) ← 506 linhas!
-    ├── History/Favorites tabs (linhas 1439-1511)
-    ├── Chat input area (linhas 1515-1531)
-    └── Feedback dialog (linhas 1539-1570)
-```
-
-**Solução — decomposição em sub-componentes:**
-
-```
-components/assistant/xertica-assistant/
-├── types.ts                          ← NOVO: todos os tipos
-├── use-assistant.ts                  ← existente (manter)
-├── xertica-assistant.tsx             ← orquestrador (~200 linhas)
-└── parts/
-    ├── AssistantCollapsedView.tsx    ← NOVO: view colapsada
-    ├── AssistantDocumentEditor.tsx   ← NOVO: overlay do editor
-    ├── AssistantMessageList.tsx      ← NOVO: lista de mensagens
-    ├── AssistantMessage.tsx          ← NOVO: mensagem individual
-    ├── AssistantHistoryTab.tsx       ← NOVO: aba de histórico
-    ├── AssistantFeedbackDialog.tsx   ← NOVO: dialog de feedback
-    └── AssistantTooltipContent.tsx   ← NOVO: tooltip customizado
-```
-
-**Impacto:** `xertica-assistant.tsx` passa de 1573 para ~200 linhas. Cada sub-componente é testável e manutenível independentemente.
-
----
-
-## 🟡 Problemas de Média Prioridade
-
-### M1 — `sidebar.tsx` com 1089 linhas — decomposição parcial necessária
-
-**Arquivo:** [`components/layout/sidebar/sidebar.tsx`](../components/layout/sidebar/sidebar.tsx)
-
-**Problema:** O arquivo já usa compound components (`SidebarRoot`, `SidebarHeader`, `SidebarNav`, `SidebarSearch`, `SidebarFooter`), mas todos estão no mesmo arquivo de 1089 linhas. Além disso, `SidebarTooltipContent` é definido inline (linhas 40-64) — idêntico ao `AssistantTooltipContent` em `xertica-assistant.tsx`.
-
-**Solução:**
-
-```
-components/layout/sidebar/
-├── sidebar.tsx           ← orquestrador + export público (~100 linhas)
-├── use-sidebar.ts        ← existente (manter)
-├── SidebarContext.tsx    ← NOVO: contexto interno extraído
-└── parts/
-    ├── SidebarRoot.tsx   ← NOVO
-    ├── SidebarHeader.tsx ← NOVO
-    ├── SidebarNav.tsx    ← NOVO
-    ├── SidebarSearch.tsx ← NOVO
-    └── SidebarFooter.tsx ← NOVO
-```
-
-**Oportunidade adicional:** `SidebarTooltipContent` e `AssistantTooltipContent` são idênticos — extrair para componente compartilhado:
-
-```
-components/shared/
-└── CustomTooltipContent.tsx  ← NOVO: tooltip com portal e arrow
-```
-
----
-
-### M2 — Atalhos de teclado e cookies misturados no `LayoutContext`
-
-**Arquivo:** [`contexts/LayoutContext.tsx`](../contexts/LayoutContext.tsx)
-
-**Problema:** O `LayoutContext` mistura três responsabilidades distintas:
-
-1. **Estado de layout** (sidebar expandida, assistente expandido)
-2. **Atalhos de teclado** (`Ctrl+B` para toggle sidebar, linhas 78-86)
-3. **Persistência em cookies** (funções `getCookie`/`setCookie`, linhas 25-45)
-
-**Solução — separação de responsabilidades:**
-
-```ts
-// contexts/LayoutContext.tsx — apenas estado
-export function LayoutProvider({ children }) {
-  const [sidebarExpanded, setSidebarExpanded] = usePersistentState('sidebar', true);
-  // ...
-}
-
-// hooks/use-layout-shortcuts.ts — NOVO: atalhos de teclado
-export function useLayoutShortcuts() {
-  const { toggleSidebar } = useLayout();
-  useEffect(() => {
-    const handler = (e: KeyboardEvent) => {
-      if ((e.ctrlKey || e.metaKey) && e.key === 'b') {
-        e.preventDefault();
-        toggleSidebar();
-      }
-    };
-    document.addEventListener('keydown', handler);
-    return () => document.removeEventListener('keydown', handler);
-  }, [toggleSidebar]);
-}
-
-// hooks/use-persistent-state.ts — NOVO: estado com persistência em cookie
-export function usePersistentState<T>(key: string, defaultValue: T) { ... }
-```
-
----
-
-### M3 — `BrandColorsContext` com utilitário `hexToRgb` inline
-
-**Arquivo:** [`contexts/BrandColorsContext.tsx`](../contexts/BrandColorsContext.tsx) — linhas 79-88
-
-**Problema:** A função `hexToRgb` é um utilitário puro definido dentro do componente Provider. Não pode ser testada isoladamente e não pode ser reutilizada.
-
-**Solução:**
-
-```ts
-// utils/color-utils.ts — NOVO
-export function hexToRgb(hex: string): { r: number; g: number; b: number } | null { ... }
-export function rgbToHsl(r: number, g: number, b: number): { h: number; s: number; l: number } { ... }
-export function generateColorScale(baseHex: string): Record<string, string> { ... }
-```
-
----
-
-### M4 — `header.tsx` sem hook headless
-
-**Arquivo:** [`components/layout/header/header.tsx`](../components/layout/header/header.tsx)
-
-**Problema:** O `Header` não tem lógica de estado complexa, mas tem lógica de renderização condicional para breadcrumbs, ações e menu do usuário que poderia ser extraída para melhorar a testabilidade.
-
-**Avaliação:** Prioridade baixa — o componente tem 337 linhas mas é principalmente JSX declarativo. Não há estado local significativo. A extração de um `useHeader` hook seria de valor limitado aqui.
-
-**Recomendação:** Manter como está, mas considerar extrair `HeaderUserMenu` e `HeaderBreadcrumbs` como sub-componentes separados para melhorar a legibilidade.
-
----
-
-## 🟢 Problemas de Baixa Prioridade
-
-### B1 — `SidebarTooltipContent` e `AssistantTooltipContent` são idênticos
-
-**Arquivos:**
-
-- [`components/layout/sidebar/sidebar.tsx`](../components/layout/sidebar/sidebar.tsx) — linhas 40-64
-- [`components/assistant/xertica-assistant/xertica-assistant.tsx`](../components/assistant/xertica-assistant/xertica-assistant.tsx) — linhas 105-131
-
-Ambos implementam um tooltip com `TooltipPrimitive.Portal` e `TooltipPrimitive.Arrow`. Extrair para componente compartilhado elimina duplicação.
-
----
-
-### B2 — `use-sidebar.ts` tem alturas hardcoded
-
-**Arquivo:** [`components/layout/sidebar/use-sidebar.ts`](../components/layout/sidebar/use-sidebar.ts) — linhas 57-91
-
-A função `checkOverflow` usa valores hardcoded (`40px`, `32px`) para calcular overflow de itens de navegação. Esses valores deveriam ser constantes nomeadas ou derivados do DOM.
-
-```ts
-// ❌ ATUAL
-const itemHeight = 40;
-const groupHeaderHeight = 32;
-
-// ✅ MELHOR
-const SIDEBAR_ITEM_HEIGHT_PX = 40;
-const SIDEBAR_GROUP_HEADER_HEIGHT_PX = 32;
-```
-
----
-
-### B3 — `use-assistant.ts` tem `setTimeout` para simular async ✅ RESOLVIDO
-
-**Arquivo:** [`components/assistant/xertica-assistant/use-assistant.ts`](../components/assistant/xertica-assistant/use-assistant.ts)
-
-**Resolução (v2.1.9):** Todo o dado mock foi extraído para a camada `features/*/data/mock.ts`. A estrutura implementada usa o padrão **swap point**: cada `features/<nome>/data/mock.ts` contém funções `async fetch*()` que simulam latência de rede e retornam dados tipados. Para conectar a uma API real, basta substituir o corpo dessas funções por chamadas `fetch()` ou `axios` — hooks, componentes e tipos permanecem inalterados.
-
-```ts
-// features/assistant/data/mock.ts — antes (mock)
-export async function fetchAssistantConfig(): Promise<AssistantConfig> {
-  await new Promise(resolve => setTimeout(resolve, 150)); // simula latência
-  return MOCK_ASSISTANT_CONFIG;
-}
-
-// features/assistant/data/mock.ts — depois (API real)
-export async function fetchAssistantConfig(): Promise<AssistantConfig> {
-  return fetch('/api/assistant/config').then(r => r.json());
-}
-```
-
-A configuração do assistente (suggestions, richSuggestions, feedbackOptions) é agora consumida via `useAssistantConfig()` (TanStack React Query) com `staleTime: 30min`.
-
----
-
-## Padrões Positivos — Manter e Expandir
-
-O projeto já tem excelentes exemplos do padrão headless hook que devem servir como referência:
-
-### ✅ `useRichTextEditor` — Exemplo de referência
-
-**Arquivo:** [`components/ui/rich-text-editor/use-rich-text-editor.ts`](../components/ui/rich-text-editor/use-rich-text-editor.ts)
-
-- Interface `UseRichTextEditorProps` bem definida
-- Interface `UseRichTextEditorReturn` completa com todos os retornos tipados
-- Lógica completamente separada do JSX
-- `rich-text-editor.tsx` é JSX puro consumindo o hook
-
-### ✅ `useTreeView` — Exemplo de referência para acessibilidade
-
-**Arquivo:** [`components/ui/tree-view/use-tree-view.ts`](../components/ui/tree-view/use-tree-view.ts)
-
-- WAI-ARIA keyboard navigation implementada no hook
-- Componente de UI não precisa conhecer lógica de navegação por teclado
-
-### ✅ `useAssistant` — Boa extração, mas incompleta
-
-**Arquivo:** [`components/assistant/xertica-assistant/use-assistant.ts`](../components/assistant/xertica-assistant/use-assistant.ts)
-
-- Toda a lógica de estado está no hook
-- O componente ainda tem 1000+ linhas de JSX que precisam de decomposição
-
----
-
-## Plano de Implementação Recomendado
-
-### Fase 1 — Correções Críticas (1-2 dias)
-
-| #   | Tarefa                                                        | Arquivo(s)        | Esforço |
-| --- | ------------------------------------------------------------- | ----------------- | ------- |
-| ~~1.1~~ | ~~Corrigir `ThemeToggle` para usar `useTheme()`~~ | ✅ Resolvido em v2.2.0 | — |
-| 1.2 | Criar `types.ts` compartilhado para o assistente              | `types.ts` (novo) | 1h      |
-| 1.3 | Atualizar imports em `AssistenteContext` e `use-assistant.ts` | 2 arquivos        | 30min   |
-
-### Fase 2 — Eliminação de Duplicações (2-3 dias)
-
-| #   | Tarefa                                         | Arquivo(s)     | Esforço |
-| --- | ---------------------------------------------- | -------------- | ------- |
-| 2.1 | Substituir detecção mobile por `useIsMobile()` | 4 arquivos     | 2h      |
-| 2.2 | Extrair `CustomTooltipContent` compartilhado   | 1 arquivo novo | 1h      |
-| 2.3 | Mover `hexToRgb` para `utils/color-utils.ts`   | 2 arquivos     | 30min   |
-
-### Fase 3 — Extração de Hooks (3-5 dias)
-
-| #   | Tarefa                                       | Arquivo(s)        | Esforço |
-| --- | -------------------------------------------- | ----------------- | ------- |
-| 3.1 | Criar `use-audio-player.ts`                  | 1 arquivo novo    | 4h      |
-| 3.2 | Refatorar `AudioPlayer.tsx` para usar o hook | `AudioPlayer.tsx` | 2h      |
-| 3.3 | Extrair `use-layout-shortcuts.ts`            | 1 arquivo novo    | 1h      |
-| 3.4 | Extrair `use-persistent-state.ts`            | 1 arquivo novo    | 1h      |
-
-### Fase 4 — Decomposição de Componentes Grandes (5-8 dias)
-
-| #   | Tarefa                                              | Arquivo(s)       | Esforço |
-| --- | --------------------------------------------------- | ---------------- | ------- |
-| 4.1 | Decompor `xertica-assistant.tsx` em sub-componentes | 7 arquivos novos | 1 dia   |
-| 4.2 | Decompor `sidebar.tsx` em sub-componentes           | 5 arquivos novos | 1 dia   |
-| 4.3 | Extrair `HeaderUserMenu` e `HeaderBreadcrumbs`      | 2 arquivos novos | 3h      |
-
----
-
-## Métricas de Melhoria Esperadas
-
-| Métrica                           | Atual                   | Após Fase 1-2 | Após Fase 3-4 |
-| --------------------------------- | ----------------------- | ------------- | ------------- |
-| Maior arquivo (linhas)            | 1573                    | 1573          | ~200          |
-| Duplicações de detecção mobile    | 4                       | 1             | 1             |
-| Definições de tipo duplicadas     | 2 conjuntos             | 1 conjunto    | 1 conjunto    |
-| Componentes sem hook headless     | 2 (AudioPlayer, Header) | 2             | 0-1           |
-| Risco de dessincronização de tema | Eliminado (v2.2.0)      | Eliminado     | Eliminado     |
-
----
-
-## Referências
-
-- [Padrão Headless Hook — Kent C. Dodds](https://kentcdodds.com/blog/inversion-of-control)
-- [Compound Components Pattern](https://kentcdodds.com/blog/compound-components-with-react-hooks)
-- [`docs/architecture.md`](./architecture.md) — Arquitetura atual do projeto
-- [`docs/doc-audit.md`](./doc-audit.md) — Auditoria de documentação
+# Relatório de Melhorias Arquiteturais
+
+> **Objetivo:** Identificar oportunidades para melhorar a separação entre UI e lógica de negócio, tornando o projeto mais moderno, testável e manutenível.
+>
+> **Data da análise:** Maio 2026  
+> **Escopo:** Todos os componentes, hooks e contextos do projeto
+
+---
+
+## Sumário Executivo
+
+O projeto já adota boas práticas em vários pontos — o padrão **headless hook** está presente em `useRichTextEditor`, `useTreeView`, `useSidebar` e `useAssistant`. No entanto, existem **inconsistências** onde a mesma lógica é duplicada em múltiplos lugares e componentes com mais de 600 linhas misturam JSX com lógica de estado.
+
+### Severidade dos Problemas
+
+| Severidade | Quantidade | Exemplos                                                                                                                                |
+| ---------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔴 Crítico | 1 ~~2~~    | ~~`ThemeToggle` bypassa `ThemeContext`~~ ✅ resolvido em v2.2.0; tipos duplicados entre contextos                                       |
+| 🟠 Alto    | 3          | `AudioPlayer` sem hook; detecção mobile duplicada 4×; `xertica-assistant.tsx` com 1573 linhas                                           |
+| 🟡 Médio   | 4          | `sidebar.tsx` com 1089 linhas; atalhos de teclado no `LayoutContext`; `BrandColorsContext` com utilitário inline; `header.tsx` sem hook |
+| 🟢 Baixo   | 3          | `SidebarTooltipContent` duplicado; `AssistantTooltipContent` inline; cookie management inline                                           |
+
+---
+
+## 🔴 Problemas Críticos
+
+### C1 — `ThemeToggle` bypassa `ThemeContext` completamente ✅ RESOLVIDO (v2.2.0)
+
+**Arquivo:** [`components/brand/theme-toggle/ThemeToggle.tsx`](../components/brand/theme-toggle/ThemeToggle.tsx)
+
+**Resolução:** O `ThemeToggle` foi corrigido para usar `useTheme()` do `ThemeContext`. Adicionalmente, o bug `disableDarkMode` foi corrigido em `templates/src/app/App.tsx` e `bin/language-config.ts` — o prop estava hard-coded como `true`, tornando o `toggleTheme()` um no-op em projetos gerados pelo CLI. O `ThemeToggle` agora funciona corretamente tanto no projeto base quanto em projetos gerados.
+
+<details>
+<summary>Análise original (histórico)</summary>
+
+**Problema original:** O componente `ThemeToggle` manipulava `document.documentElement.classList` diretamente e mantinha seu próprio estado local com `useState`, ignorando completamente o `ThemeContext` e o hook `useTheme()`. Isso criava um **risco de dessincronização**: se o tema fosse alterado via `ThemeContext` (ex: por outro componente ou por `defaultTheme`), o `ThemeToggle` não refletiria a mudança.
+
+Adicionalmente, em projetos gerados pelo CLI, `XerticaProvider` era instanciado com `disableDarkMode` hard-coded, fazendo `toggleTheme()` retornar imediatamente sem efeito.
+
+</details>
+
+---
+
+### C2 — Tipos duplicados entre `AssistenteContext` e `xertica-assistant.tsx`
+
+**Arquivos:**
+
+- [`contexts/AssistenteContext.tsx`](../contexts/AssistenteContext.tsx) — linhas 5–71
+- [`components/assistant/xertica-assistant/xertica-assistant.tsx`](../components/assistant/xertica-assistant/xertica-assistant.tsx) — linhas 155–230
+
+**Problema:** Os mesmos tipos são definidos em dois lugares com nomes e estruturas ligeiramente diferentes:
+
+| `AssistenteContext.tsx` | `xertica-assistant.tsx` | Diferença                            |
+| ----------------------- | ----------------------- | ------------------------------------ |
+| `Message`               | `Message`               | Campos diferentes (`role` vs `type`) |
+| `Conversa`              | `Conversation`          | Nome diferente, campos em PT vs EN   |
+| `SearchResult`          | `SearchResult`          | Duplicado idêntico                   |
+| `SearchSource`          | `SearchSource`          | Duplicado idêntico                   |
+| `SearchCommand`         | `SearchCommand`         | Duplicado idêntico                   |
+
+Isso significa que existem **dois contratos de tipo incompatíveis** para os mesmos dados, forçando conversões implícitas e tornando refatorações perigosas.
+
+**Solução:** Criar um arquivo de tipos compartilhado:
+
+```
+components/assistant/xertica-assistant/
+├── types.ts          ← NOVO: fonte única de verdade para todos os tipos
+├── use-assistant.ts  ← importa de types.ts
+├── xertica-assistant.tsx ← importa de types.ts
+contexts/
+└── AssistenteContext.tsx ← importa de types.ts (re-exporta para compatibilidade)
+```
+
+```ts
+// components/assistant/xertica-assistant/types.ts
+export interface Message { ... }
+export interface Conversation { ... }
+export interface SearchResult { ... }
+// ...
+
+// contexts/AssistenteContext.tsx
+export type { Message, Conversation, SearchResult } from '@/components/assistant/xertica-assistant/types';
+```
+
+---
+
+## 🟠 Problemas de Alta Prioridade
+
+### A1 — Detecção de mobile duplicada em 4+ lugares
+
+**Problema:** A lógica `window.innerWidth < 768` está duplicada em:
+
+| Arquivo                                                                                                                 | Linha | Forma                            |
+| ----------------------------------------------------------------------------------------------------------------------- | ----- | -------------------------------- |
+| [`components/shared/use-mobile.ts`](../components/shared/use-mobile.ts)                                                 | 18    | `useIsMobile()` hook ✅          |
+| [`components/assistant/xertica-assistant/use-assistant.ts`](../components/assistant/xertica-assistant/use-assistant.ts) | ~192  | `window.innerWidth < 768` inline |
+| [`components/layout/sidebar/use-sidebar.ts`](../components/layout/sidebar/use-sidebar.ts)                               | ~46   | `window.innerWidth < 768` inline |
+| [`components/media/audio-player/AudioPlayer.tsx`](../components/media/audio-player/AudioPlayer.tsx)                     | ~113  | `window.innerWidth < 768` inline |
+| [`contexts/LayoutContext.tsx`](../contexts/LayoutContext.tsx)                                                           | ~60   | `window.innerWidth < 768` inline |
+
+O hook `useIsMobile()` **já existe** em `components/shared/use-mobile.ts` e usa `matchMedia` (mais eficiente que `resize` events), mas não está sendo usado pelos outros arquivos.
+
+**Solução:** Substituir todas as ocorrências pelo hook existente:
+
+```ts
+// ❌ ATUAL
+const [isMobileViewport, setIsMobileViewport] = useState(window.innerWidth < 768);
+useEffect(() => {
+  const handleResize = () => setIsMobileViewport(window.innerWidth < 768);
+  window.addEventListener('resize', handleResize);
+  return () => window.removeEventListener('resize', handleResize);
+}, []);
+
+// ✅ CORRETO
+import { useIsMobile } from '@/components/shared/use-mobile';
+const isMobileViewport = useIsMobile();
+```
+
+**Impacto:** Reduz código duplicado, garante breakpoint consistente (768px), usa `matchMedia` que é mais performático que `resize` events.
+
+---
+
+### A2 — `AudioPlayer.tsx` (663 linhas) sem hook headless
+
+**Arquivo:** [`components/media/audio-player/AudioPlayer.tsx`](../components/media/audio-player/AudioPlayer.tsx)
+
+**Problema:** Todo o estado e lógica do player de áudio está inline no componente, misturado com JSX. Inclui:
+
+- Gerenciamento de estado (`isPlaying`, `currentTime`, `duration`, `volume`, `playbackRate`, `isFloating`)
+- `IntersectionObserver` para auto-float
+- Sincronização de áudio com `useEffect`
+- Detecção de mobile (duplicada)
+- Formatação de tempo (`formatTime`)
+- Handlers de eventos (`togglePlay`, `handleSeek`, `handleVolumeChange`, `handleSetFloating`)
+
+**Solução:** Extrair para `use-audio-player.ts`:
+
+```ts
+// components/media/audio-player/use-audio-player.ts
+export interface UseAudioPlayerProps {
+  src: string;
+  autoFloat?: boolean;
+  onEnded?: () => void;
+}
+
+export interface UseAudioPlayerReturn {
+  audioRef: React.RefObject<HTMLAudioElement>;
+  containerRef: React.RefObject<HTMLDivElement>;
+  isPlaying: boolean;
+  currentTime: number;
+  duration: number;
+  volume: number;
+  playbackRate: number;
+  isFloating: boolean;
+  isMobile: boolean;
+  togglePlay: () => void;
+  handleSeek: (value: number[]) => void;
+  handleVolumeChange: (value: number[]) => void;
+  handleSetFloating: (floating: boolean) => void;
+  setPlaybackRate: (rate: number) => void;
+  formatTime: (time: number) => string;
+}
+
+export function useAudioPlayer(props: UseAudioPlayerProps): UseAudioPlayerReturn { ... }
+```
+
+**Benefícios:**
+
+- `AudioPlayer.tsx` fica com ~200 linhas de JSX puro
+- Lógica do player pode ser testada unitariamente sem renderizar DOM
+- Permite criar variantes do player (mini, fullscreen) reusando o mesmo hook
+
+---
+
+### A3 — `xertica-assistant.tsx` com 1573 linhas — decomposição necessária
+
+**Arquivo:** [`components/assistant/xertica-assistant/xertica-assistant.tsx`](../components/assistant/xertica-assistant/xertica-assistant.tsx)
+
+**Problema:** Mesmo com o `useAssistant` hook extraindo a lógica de estado, o componente ainda tem ~1000 linhas de JSX com sub-componentes definidos inline e seções de renderização muito longas.
+
+**Estrutura atual:**
+
+```
+xertica-assistant.tsx (1573 linhas)
+├── AssistantTooltipContent (componente inline, linhas 105-131)
+├── Tipos exportados (linhas 155-230) ← deveria estar em types.ts
+├── XerticaAssistantProps (linhas 246-417) ← 171 linhas de interface!
+└── XerticaAssistant (linhas 467-1572)
+    ├── Document editor overlay (linhas 598-694)
+    ├── Collapsed view (linhas 695-827)
+    ├── Chat messages list (linhas 888-1394) ← 506 linhas!
+    ├── History/Favorites tabs (linhas 1439-1511)
+    ├── Chat input area (linhas 1515-1531)
+    └── Feedback dialog (linhas 1539-1570)
+```
+
+**Solução — decomposição em sub-componentes:**
+
+```
+components/assistant/xertica-assistant/
+├── types.ts                          ← NOVO: todos os tipos
+├── use-assistant.ts                  ← existente (manter)
+├── xertica-assistant.tsx             ← orquestrador (~200 linhas)
+└── parts/
+    ├── AssistantCollapsedView.tsx    ← NOVO: view colapsada
+    ├── AssistantDocumentEditor.tsx   ← NOVO: overlay do editor
+    ├── AssistantMessageList.tsx      ← NOVO: lista de mensagens
+    ├── AssistantMessage.tsx          ← NOVO: mensagem individual
+    ├── AssistantHistoryTab.tsx       ← NOVO: aba de histórico
+    ├── AssistantFeedbackDialog.tsx   ← NOVO: dialog de feedback
+    └── AssistantTooltipContent.tsx   ← NOVO: tooltip customizado
+```
+
+**Impacto:** `xertica-assistant.tsx` passa de 1573 para ~200 linhas. Cada sub-componente é testável e manutenível independentemente.
+
+---
+
+## 🟡 Problemas de Média Prioridade
+
+### M1 — `sidebar.tsx` com 1089 linhas — decomposição parcial necessária
+
+**Arquivo:** [`components/layout/sidebar/sidebar.tsx`](../components/layout/sidebar/sidebar.tsx)
+
+**Problema:** O arquivo já usa compound components (`SidebarRoot`, `SidebarHeader`, `SidebarNav`, `SidebarSearch`, `SidebarFooter`), mas todos estão no mesmo arquivo de 1089 linhas. Além disso, `SidebarTooltipContent` é definido inline (linhas 40-64) — idêntico ao `AssistantTooltipContent` em `xertica-assistant.tsx`.
+
+**Solução:**
+
+```
+components/layout/sidebar/
+├── sidebar.tsx           ← orquestrador + export público (~100 linhas)
+├── use-sidebar.ts        ← existente (manter)
+├── SidebarContext.tsx    ← NOVO: contexto interno extraído
+└── parts/
+    ├── SidebarRoot.tsx   ← NOVO
+    ├── SidebarHeader.tsx ← NOVO
+    ├── SidebarNav.tsx    ← NOVO
+    ├── SidebarSearch.tsx ← NOVO
+    └── SidebarFooter.tsx ← NOVO
+```
+
+**Oportunidade adicional:** `SidebarTooltipContent` e `AssistantTooltipContent` são idênticos — extrair para componente compartilhado:
+
+```
+components/shared/
+└── CustomTooltipContent.tsx  ← NOVO: tooltip com portal e arrow
+```
+
+---
+
+### M2 — Atalhos de teclado e cookies misturados no `LayoutContext`
+
+**Arquivo:** [`contexts/LayoutContext.tsx`](../contexts/LayoutContext.tsx)
+
+**Problema:** O `LayoutContext` mistura três responsabilidades distintas:
+
+1. **Estado de layout** (sidebar expandida, assistente expandido)
+2. **Atalhos de teclado** (`Ctrl+B` para toggle sidebar, linhas 78-86)
+3. **Persistência em cookies** (funções `getCookie`/`setCookie`, linhas 25-45)
+
+**Solução — separação de responsabilidades:**
+
+```ts
+// contexts/LayoutContext.tsx — apenas estado
+export function LayoutProvider({ children }) {
+  const [sidebarExpanded, setSidebarExpanded] = usePersistentState('sidebar', true);
+  // ...
+}
+
+// hooks/use-layout-shortcuts.ts — NOVO: atalhos de teclado
+export function useLayoutShortcuts() {
+  const { toggleSidebar } = useLayout();
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if ((e.ctrlKey || e.metaKey) && e.key === 'b') {
+        e.preventDefault();
+        toggleSidebar();
+      }
+    };
+    document.addEventListener('keydown', handler);
+    return () => document.removeEventListener('keydown', handler);
+  }, [toggleSidebar]);
+}
+
+// hooks/use-persistent-state.ts — NOVO: estado com persistência em cookie
+export function usePersistentState<T>(key: string, defaultValue: T) { ... }
+```
+
+---
+
+### M3 — `BrandColorsContext` com utilitário `hexToRgb` inline
+
+**Arquivo:** [`contexts/BrandColorsContext.tsx`](../contexts/BrandColorsContext.tsx) — linhas 79-88
+
+**Problema:** A função `hexToRgb` é um utilitário puro definido dentro do componente Provider. Não pode ser testada isoladamente e não pode ser reutilizada.
+
+**Solução:**
+
+```ts
+// utils/color-utils.ts — NOVO
+export function hexToRgb(hex: string): { r: number; g: number; b: number } | null { ... }
+export function rgbToHsl(r: number, g: number, b: number): { h: number; s: number; l: number } { ... }
+export function generateColorScale(baseHex: string): Record<string, string> { ... }
+```
+
+---
+
+### M4 — `header.tsx` sem hook headless
+
+**Arquivo:** [`components/layout/header/header.tsx`](../components/layout/header/header.tsx)
+
+**Problema:** O `Header` não tem lógica de estado complexa, mas tem lógica de renderização condicional para breadcrumbs, ações e menu do usuário que poderia ser extraída para melhorar a testabilidade.
+
+**Avaliação:** Prioridade baixa — o componente tem 337 linhas mas é principalmente JSX declarativo. Não há estado local significativo. A extração de um `useHeader` hook seria de valor limitado aqui.
+
+**Recomendação:** Manter como está, mas considerar extrair `HeaderUserMenu` e `HeaderBreadcrumbs` como sub-componentes separados para melhorar a legibilidade.
+
+---
+
+## 🟢 Problemas de Baixa Prioridade
+
+### B1 — `SidebarTooltipContent` e `AssistantTooltipContent` são idênticos
+
+**Arquivos:**
+
+- [`components/layout/sidebar/sidebar.tsx`](../components/layout/sidebar/sidebar.tsx) — linhas 40-64
+- [`components/assistant/xertica-assistant/xertica-assistant.tsx`](../components/assistant/xertica-assistant/xertica-assistant.tsx) — linhas 105-131
+
+Ambos implementam um tooltip com `TooltipPrimitive.Portal` e `TooltipPrimitive.Arrow`. Extrair para componente compartilhado elimina duplicação.
+
+---
+
+### B2 — `use-sidebar.ts` tem alturas hardcoded
+
+**Arquivo:** [`components/layout/sidebar/use-sidebar.ts`](../components/layout/sidebar/use-sidebar.ts) — linhas 57-91
+
+A função `checkOverflow` usa valores hardcoded (`40px`, `32px`) para calcular overflow de itens de navegação. Esses valores deveriam ser constantes nomeadas ou derivados do DOM.
+
+```ts
+// ❌ ATUAL
+const itemHeight = 40;
+const groupHeaderHeight = 32;
+
+// ✅ MELHOR
+const SIDEBAR_ITEM_HEIGHT_PX = 40;
+const SIDEBAR_GROUP_HEADER_HEIGHT_PX = 32;
+```
+
+---
+
+### B3 — `use-assistant.ts` tem `setTimeout` para simular async ✅ RESOLVIDO
+
+**Arquivo:** [`components/assistant/xertica-assistant/use-assistant.ts`](../components/assistant/xertica-assistant/use-assistant.ts)
+
+**Resolução (v2.1.9):** Todo o dado mock foi extraído para a camada `features/*/data/mock.ts`. A estrutura implementada usa o padrão **swap point**: cada `features/<nome>/data/mock.ts` contém funções `async fetch*()` que simulam latência de rede e retornam dados tipados. Para conectar a uma API real, basta substituir o corpo dessas funções por chamadas `fetch()` ou `axios` — hooks, componentes e tipos permanecem inalterados.
+
+```ts
+// features/assistant/data/mock.ts — antes (mock)
+export async function fetchAssistantConfig(): Promise<AssistantConfig> {
+  await new Promise(resolve => setTimeout(resolve, 150)); // simula latência
+  return MOCK_ASSISTANT_CONFIG;
+}
+
+// features/assistant/data/mock.ts — depois (API real)
+export async function fetchAssistantConfig(): Promise<AssistantConfig> {
+  return fetch('/api/assistant/config').then(r => r.json());
+}
+```
+
+A configuração do assistente (suggestions, richSuggestions, feedbackOptions) é agora consumida via `useAssistantConfig()` (TanStack React Query) com `staleTime: 30min`.
+
+---
+
+## Padrões Positivos — Manter e Expandir
+
+O projeto já tem excelentes exemplos do padrão headless hook que devem servir como referência:
+
+### ✅ `useRichTextEditor` — Exemplo de referência
+
+**Arquivo:** [`components/ui/rich-text-editor/use-rich-text-editor.ts`](../components/ui/rich-text-editor/use-rich-text-editor.ts)
+
+- Interface `UseRichTextEditorProps` bem definida
+- Interface `UseRichTextEditorReturn` completa com todos os retornos tipados
+- Lógica completamente separada do JSX
+- `rich-text-editor.tsx` é JSX puro consumindo o hook
+
+### ✅ `useTreeView` — Exemplo de referência para acessibilidade
+
+**Arquivo:** [`components/ui/tree-view/use-tree-view.ts`](../components/ui/tree-view/use-tree-view.ts)
+
+- WAI-ARIA keyboard navigation implementada no hook
+- Componente de UI não precisa conhecer lógica de navegação por teclado
+
+### ✅ `useAssistant` — Boa extração, mas incompleta
+
+**Arquivo:** [`components/assistant/xertica-assistant/use-assistant.ts`](../components/assistant/xertica-assistant/use-assistant.ts)
+
+- Toda a lógica de estado está no hook
+- O componente ainda tem 1000+ linhas de JSX que precisam de decomposição
+
+---
+
+## Plano de Implementação Recomendado
+
+### Fase 1 — Correções Críticas (1-2 dias)
+
+| #       | Tarefa                                                        | Arquivo(s)             | Esforço |
+| ------- | ------------------------------------------------------------- | ---------------------- | ------- |
+| ~~1.1~~ | ~~Corrigir `ThemeToggle` para usar `useTheme()`~~             | ✅ Resolvido em v2.2.0 | —       |
+| 1.2     | Criar `types.ts` compartilhado para o assistente              | `types.ts` (novo)      | 1h      |
+| 1.3     | Atualizar imports em `AssistenteContext` e `use-assistant.ts` | 2 arquivos             | 30min   |
+
+### Fase 2 — Eliminação de Duplicações (2-3 dias)
+
+| #   | Tarefa                                         | Arquivo(s)     | Esforço |
+| --- | ---------------------------------------------- | -------------- | ------- |
+| 2.1 | Substituir detecção mobile por `useIsMobile()` | 4 arquivos     | 2h      |
+| 2.2 | Extrair `CustomTooltipContent` compartilhado   | 1 arquivo novo | 1h      |
+| 2.3 | Mover `hexToRgb` para `utils/color-utils.ts`   | 2 arquivos     | 30min   |
+
+### Fase 3 — Extração de Hooks (3-5 dias)
+
+| #   | Tarefa                                       | Arquivo(s)        | Esforço |
+| --- | -------------------------------------------- | ----------------- | ------- |
+| 3.1 | Criar `use-audio-player.ts`                  | 1 arquivo novo    | 4h      |
+| 3.2 | Refatorar `AudioPlayer.tsx` para usar o hook | `AudioPlayer.tsx` | 2h      |
+| 3.3 | Extrair `use-layout-shortcuts.ts`            | 1 arquivo novo    | 1h      |
+| 3.4 | Extrair `use-persistent-state.ts`            | 1 arquivo novo    | 1h      |
+
+### Fase 4 — Decomposição de Componentes Grandes (5-8 dias)
+
+| #   | Tarefa                                              | Arquivo(s)       | Esforço |
+| --- | --------------------------------------------------- | ---------------- | ------- |
+| 4.1 | Decompor `xertica-assistant.tsx` em sub-componentes | 7 arquivos novos | 1 dia   |
+| 4.2 | Decompor `sidebar.tsx` em sub-componentes           | 5 arquivos novos | 1 dia   |
+| 4.3 | Extrair `HeaderUserMenu` e `HeaderBreadcrumbs`      | 2 arquivos novos | 3h      |
+
+---
+
+## Métricas de Melhoria Esperadas
+
+| Métrica                           | Atual                   | Após Fase 1-2 | Após Fase 3-4 |
+| --------------------------------- | ----------------------- | ------------- | ------------- |
+| Maior arquivo (linhas)            | 1573                    | 1573          | ~200          |
+| Duplicações de detecção mobile    | 4                       | 1             | 1             |
+| Definições de tipo duplicadas     | 2 conjuntos             | 1 conjunto    | 1 conjunto    |
+| Componentes sem hook headless     | 2 (AudioPlayer, Header) | 2             | 0-1           |
+| Risco de dessincronização de tema | Eliminado (v2.2.0)      | Eliminado     | Eliminado     |
+
+---
+
+## Referências
+
+- [Padrão Headless Hook — Kent C. Dodds](https://kentcdodds.com/blog/inversion-of-control)
+- [Compound Components Pattern](https://kentcdodds.com/blog/compound-components-with-react-hooks)
+- [`docs/architecture.md`](./architecture.md) — Arquitetura atual do projeto
+- [`docs/doc-audit.md`](./doc-audit.md) — Auditoria de documentação