xertica-ui 2.1.8 → 2.1.10

package/CHANGELOG.md

@@ -1,454 +1,469 @@
-# Changelog
-
-All notable changes to `xertica-ui` will be documented in this file.
-
-Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
-Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
----
-
-## [2.1.8] — 2026-05-19
-
-### Fixed
-
-- **`templates/TemplateContent.tsx` — navegação entre páginas do template não funcionava** — o componente era uma página monolítica sem sistema de tabs roteáveis. Reestruturado completamente:
-  - Tab bar controlada por `useSearchParams` — a URL `/template?tab=dashboard` ativa a tab correta diretamente, permitindo deep-link e navegação pelo histórico do browser
-  - Botões de `HomeContent` (`/template?tab=dashboard`, `/template?tab=crud`) agora funcionam e ativam a tab correspondente ao carregar
-  - Cada tab renderiza o sub-template isolado: `DashboardTemplate`, `CrudTemplate`, `FormTemplate`, `LoginTemplate`
-  - Sub-templates renderizados fora do wrapper de padding do showcase UI — sem padding duplo
-  - Tab `ui` mantém o showcase completo de componentes (Alerts, Cards, Buttons, Forms, Dialogs, etc.)
-  - Breadcrumb corrigido de "Design System / Página de Template" para "Início / Template"
-
----
-
-## [2.1.7] — 2026-05-19
-
-### Fixed
-
-- **`templates/TemplateContent.tsx` — wrapper raiz não era SPA-router-aware** — o `paddingLeft` manual foi substituído por `<PageContent>` (wrapper compartilhado de `shared/ui/PageContent.tsx`) eliminando código duplicado e garantindo que a lógica de offset do sidebar fique em um único lugar.
-- **`templates/TemplateContent.tsx` — `renderLink` tipado como `any`** — corrigido para `Record<string, unknown>` prevenindo erros silenciosos de tipos no spread `{...props}`.
-- **`templates/TemplateContent.tsx` — imports mortos removidos** — `Menu`, `ChevronRight`, `Trash2`, `Archive`, `ArrowRightLeft`, `History`, `FileEdit`, `Filter`, `Map` estavam no import mas não eram usados (ou eram usados mas faltavam). Sincronizado imports com uso real.
-- **`templates/TemplateContent.tsx` — `<h2>` raw na página** — substituído por `<PageHeader title=... subtitle=... />` para consistência com as regras do projeto.
-- **`templates/TemplatePage.tsx` — `user` tipado como `{ email: string }` em vez de `User`** — tipo corrigido para `User | null`; `onEvaluation` migrado de `console.log` para `toast.success/info`; componente agora usa `generateDemoResponse`, `richSuggestions`, `feedbackOptions` e `userName` dinâmico.
-- **`templates/HomePage.tsx` + `templates/AssistantPage.tsx` — `user` tipado como `{ email: string }`** — tipo corrigido para `User | null` em ambas as páginas.
-- **`templates/AssistantPage.tsx` — `userName="Ariel Santos"` hardcoded** — substituído por `user?.name ?? 'Usuário'` para usar o dado real do usuário autenticado.
-
----
-
-## [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
-
-- **`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
-
-- **Headless hooks — 4 new logic-only hooks** — all logic extracted from their UI components into standalone, tree-shakeable hooks:
-  - **`useFileUpload`** — drag state, file validation (size + count), error messaging, and hidden input ref. Props: `maxFiles`, `maxSize`, `onFilesChange`, `onError`, `disabled`. Returns: `files`, `dragActive`, `errorMessage`, `inputRef`, `handleFiles`, `handleDrag`, `handleDrop`, `handleChange`, `removeFile`, `openFileDialog`.
-  - **`usePagination`** — computes the full page item list (page numbers + ellipsis markers) and exposes navigation helpers. Supports controlled (`page` prop) and uncontrolled modes. Props: `totalItems`, `pageSize`, `initialPage`, `page`, `onPageChange`, `siblingCount`. Returns: `currentPage`, `totalPages`, `startIndex`, `endIndex`, `canGoPrev`, `canGoNext`, `isFirstPage`, `isLastPage`, `items: PaginationPageItem[]`, `goTo`, `next`, `prev`, `first`, `last`.
-  - **`useStepper`** — step navigation with optional async `onBeforeNext` guard for per-step validation. Supports controlled (`step` prop) and uncontrolled modes. Props: `totalSteps`, `initialStep`, `step`, `onStepChange`, `onBeforeNext`. Returns: `currentStep`, `totalSteps`, `isFirstStep`, `isLastStep`, `canGoPrev`, `canGoNext`, `next` (async), `prev`, `goTo`, `reset`.
-  - **`useTreeView`** — expand/collapse state, single-node selection, full WAI-ARIA keyboard navigation (Arrow keys, Home, End, Space), and DOM focus management via `nodeRefs`. Supports controlled `selectedNodeId`. Returns: `expanded`, `effectiveSelectedId`, `nodeRefs`, `getNodeRef`, `toggleExpand`, `handleSelect`, `handleKeyDown`, `getVisibleNodes`.
-- **New chart types — 4 new Recharts wrappers** added to `components/ui/chart/chart.tsx`:
-  - **`RadarMetricChart`** — multi-axis radar chart with optional fill, dots, and multi-series overlay.
-  - **`PieMetricChart`** — pie chart with optional percentage labels and exploded slice support.
-  - **`RadialBarMetricChart`** — radial bar chart with stacked rings and configurable arc angle.
-  - **`GaugeChart`** — pure SVG semicircle gauge with needle, threshold color zones, and optional label. Supports `thresholds` array for dynamic color changes at value breakpoints.
-- **Chart color tokens expanded** — added `--chart-6`, `--chart-7`, `--chart-8` tokens to `styles/xertica/tokens.css`, `templates/src/styles/xertica/tokens.css`, and `bin/generate-tokens.ts`. All 8 chart tokens now use a vibrant, accessible palette.
-- **Headless hook stories** — added `HeadlessHook` story variant to `file-upload.stories.tsx`, `pagination.stories.tsx`, `stepper.stories.tsx`, and `tree-view.stories.tsx` demonstrating fully custom UIs built with each hook.
-
-### Fixed
-
-- **`GaugeChart` — filled-blob visual bug for values > 50%** — the SVG arc `largeArc` flag was set to `1` when `percent > 0.5`, causing the arc command to draw the reflex arc (> 180°) which rendered as a solid filled blob. Since the gauge is a semicircle (max 180°), `largeArc` is always `0`. Removed the conditional entirely and hardcoded `0` for both arc commands.
-- **`GaugeChart` — needle overlapping value text** — the value text at `y=cy+4` was directly behind the needle pivot circle. Fixed by expanding the SVG `viewBox` from `"0 0 200 110"` to `"0 0 200 130"` and moving the value text to `y=cy+18` (13 px below the needle base circle bottom) and the label text to `y=cy+36`.
-
-### Changed
-
-- **`FileUpload` component** — refactored to consume `useFileUpload` internally; public API unchanged.
-- **`TreeView` component** — refactored to consume `useTreeView` internally; public API unchanged.
-- **`Stepper` component** — refactored to consume `useStepper` internally; public API unchanged.
-- **Documentation** — updated `docs/components/chart.md`, `docs/components/file-upload.md`, `docs/components/pagination.md`, `docs/components/stepper.md`, and `docs/components/tree-view.md` with full hook API reference, props/return tables, controlled/uncontrolled examples, and AI Rules sections.
-
----
-
-## [2.1.2] — 2026-05-14
-
-### Fixed
-
-- **`MarkdownMessage` — suporte a tabelas GFM** — o parser regex do componente não convertia blocos de tabela Markdown (`| col | col |`) em HTML. Adicionada transformação de tabelas GFM completa (header, separador, linhas de dados) com estilos do design system (`border-border`, `hover:bg-muted/50`, `rounded-[var(--radius)]`, `overflow-x-auto`). A transformação roda antes das substituições de quebra de linha para evitar `<br/>` dentro das células.
-
-### Added
-
-- **Template — `AssistantPage`** — nova página de assistente completa: sidebar em modo `assistant` aberta por padrão (largura 320px), botão "Nova Conversa" (`variant="secondary"`), busca de conversas com filtro em tempo real, histórico de 8 conversas de exemplo em 3 grupos (Hoje / Ontem / Esta semana), modal de exclusão com `AlertDialog`, modal de renomeação com `Dialog` + `Input`, simulação de conteúdo ao selecionar conversa via `initialMessages`, botão "Voltar" em `variant` primário no `Header`.
-- **Template — `AppLayout`** — novas props `sidebarVariant?: 'default' | 'assistant'` e `sidebarProps?: Record<string, any>` para permitir que páginas customizem a sidebar sem quebrar o contrato do layout.
-
----
-
-## [2.1.1] — 2026-05-14
-
-### Fixed
-
-- **XerticaAssistant — tab bar oculta em modo chat-only** — quando `showHistory` e `showFavorites` estão ambas desativadas, a barra de abas (incluindo a aba "Chat") deixa de ser renderizada, eliminando a exibição de uma aba isolada sem alternativas de navegação.
-- **`xertica-ui/style.css` — import duplo de Roboto removido** — o `@import url(Google Fonts/Roboto)` foi removido de `styles/globals.css`. A importação da fonte passa a ser responsabilidade do app consumidor, eliminando o alerta `@import must precede all other statements` do PostCSS quando o CSS compilado era injetado após o output do Tailwind v4.
-
----
-
-## [2.1.0] — 2026-05-13
-
-### Added
-
-- **`components/blocks/card-patterns/`** — novo domínio `blocks/` com 6 componentes de alto nível compostos exclusivamente de primitivos `ui/`:
-  - **`FeatureCard`** — ícone com fundo colorido, título, badge opcional, descrição e botão de ação. Suporta 10 tokens de cor (`primary`, `chart-1..5`, `success`, `info`, `warning`, `destructive`). Replica o padrão de cards da Home page.
-  - **`ActivityCard`** — feed de atividades recentes com avatar, descrição de ação, timestamp e badge por tipo (`create`, `update`, `delete`, `comment`, `deploy`).
-  - **`ProfileCard`** — card de usuário/membro com avatar, badge de status (`online`, `offline`, `away`, `busy`), linha de stats e ações primária/secundária.
-  - **`ProjectCard`** — status de projeto com badge, barra de progresso (usa `Progress` com variant semântica por status), stack de avatares de membros e data limite.
-  - **`QuickActionCard`** — tile de ação rápida com ícone em caixa colorida, badge e botão full-width.
-  - **`NotificationCard`** — lista de notificações com indicador de não-lido, badge de tipo, "Marcar todas como lidas" e "Ver todas".
-- **Exportação do domínio `blocks/`** — todos os componentes disponíveis via `import { ... } from 'xertica-ui'` e via `components/blocks/index.ts`.
-- **Subpath público `xertica-ui/blocks`** — `FeatureCard`, `ActivityCard`, `ProfileCard`, `ProjectCard`, `QuickActionCard` e `NotificationCard` agora podem ser importados diretamente de `xertica-ui/blocks`.
-- **Subpath público `xertica-ui/pages`** — `LoginPage`, `HomePage`, `TemplatePage`, `ForgotPasswordPage`, `ResetPasswordPage`, `VerifyEmailPage` e seus contents agora são publicados com entrypoint dedicado.
-- **Documentação** — criado `docs/components/card-patterns.md` com props, exemplos e layout de dashboard completo para todos os 6 block components.
-
-### Changed
-
-- **Calendar — dropdown caption styling** — quando `captionLayout="dropdown"` ou variações, os seletores de mês/ano agora têm visual de input (borda, fundo `bg-background`, focus ring `ring-primary`, `rounded-[var(--radius)]`, padding compacto fixo `px-2.5 py-1`). O `caption_label` em modo dropdown passa a usar `h-full w-full` com layout flexível.
-- **Calendar — prop `size` removida** — o tamanho e o arredondamento do trigger ("Pick a date") são responsabilidade do elemento trigger, não do `Calendar`. A story `InPopover` demonstra o padrão correto com `triggerSizeClasses` aplicado diretamente ao `<Button>` com `rounded-[var(--radius)]` para alinhar com o token do `Input`.
-- **Card stories** — enriquecidas com 3 novas variações: `WithAction` (uso de `CardAction` no header), `TeamMember` (grid de member cards com avatar e status), `SettingsCard` (lista de settings com `Separator` e `Badge`). Background `bg-muted` adicionado via decorator global da stories file para contraste com o fundo dos cards.
-- **Storybook — docs stories** — adicionado `render: (args) => <Component {...args} />` no nível do `meta` em todos os 60 arquivos de stories em `components/ui/`. Resolve o problema onde stories com apenas `args` (sem `render` explícito) mostravam a mesma variação repetida na aba Docs por dependerem do `projectAnnotations.render` implícito do framework React.
-- **Storybook — `preview.tsx`** — `min-h-screen` passou a ser condicional a `layout: 'fullscreen'`, resolvendo a altura excessiva dos exemplos na aba Docs.
-- **Template npm** — `templates/package.json` atualizado para `2.1.0` e dependência `xertica-ui` para `^2.1.0`.
-- **Template version badge** — o template passa a exibir um indicador visual discreto da versão do pacote `xertica-ui` usada pelo projeto.
-- **Documentação** — atualizados `calendar.md` (props `captionLayout`/`buttonVariant`, nota sobre `size` no trigger), `card.md` (`CardAction` na anatomia, exemplos WithAction/Stats/TeamMember/Settings), `chart.md` (nova seção Stacked Bar Chart), `architecture.md` (domínio `blocks/` com árvore de arquivos).
-
-### Fixed
-
-- **Chart — stacked bar radius** — em `DashboardBarChart` com `stacked`, apenas a série no topo de cada `stackId` recebe `radius={[4,4,0,0]}`; as demais recebem `radius={[0,0,0,0]}`. Elimina a borda arredondada no topo das barras intermediárias e inferiores da pilha.
-- **`FeatureCard` — badge overflow** — alterado de `flex items-center` para `flex flex-wrap` no container título+badge, garantindo que o badge quebre para a linha seguinte em vez de vazar fora do card quando o título ocupa toda a largura disponível.
-
----
-
-## [2.0.6] — 2026-05-13
-
-### Added
-
-- **Contrato de independência dos componentes** — documentado que `xertica-ui/style.css` é a única importação global obrigatória e que componentes públicos devem funcionar isoladamente sempre que possível.
-- **`useOptionalLayout`** — nova API compatível para componentes reutilizáveis consumirem o layout com fallback seguro, mantendo `useLayout` como hook estrito para apps que querem falhar cedo.
-- **Smoke tests de API pública** — adicionada validação de import/render dos subpaths públicos (`ui`, `brand`, `layout`, `assistant`, `media` e `hooks`).
-- **Exports públicos de Maps** — `useMapLayers`, `GOOGLE_MAPS_ID` e `GOOGLE_MAPS_LIBRARIES` agora são expostos pelo subpath `xertica-ui/ui`.
-
-### Changed
-
-- **`XerticaProvider` completo** — passa a compor providers de theme, brand colors, language, layout, assistant, API keys, Google Maps, tooltip e toaster como wrapper de conveniência para apps consumidores.
-- **Componentes com contexto de layout** — `Header`, `Sidebar`, páginas e componentes de mídia foram ajustados para renderizar com fallback interno quando importados sem provider.
-- **Arquitetura FSD/FDA** — tipos compartilhados do assistant foram movidos para camada neutra, evitando dependência runtime de `components/shared` para implementação de feature.
-- **Documentação LLM e componentes** — README, docs de provider/mapa, `llms.txt`, `llms-compact.txt` e `docs/llms.md` foram alinhados ao contrato de independência e aos subpaths consumíveis.
-- **Storybook Docs de UI** — páginas MDX dos componentes de UI agora renderizam as variações reais das stories, evitando repetição do mesmo exemplo nos blocos de variação.
-- **Storybook Maps** — stories de mapa usam um frame responsivo mais largo para melhorar a visualização na aba Docs.
-
-### Fixed
-
-- **Guards de browser/SSR** — providers e componentes browser-only agora protegem acessos a `window`, `document`, `localStorage`, `navigator` e scripts externos.
-- **Google Maps sem configuração** — componentes relacionados a Maps renderizam estados de configuração/erro sem quebrar a aplicação consumidora.
-
----
-
-## [2.0.5] — 2026-05-12
-
-### Added
-
-- **`llms-compact.txt`** — novo arquivo de referência compacto para LLMs, sintetizando todos os componentes em formato reduzido ideal para contextos de tokens limitados.
-- **`docs/decision-tree.md`** — guia de árvore de decisão para agentes de IA selecionarem o componente correto com base nos requisitos da UI.
-- **`templates/CLAUDE.md`** — `CLAUDE.md` agora é scaffolded automaticamente em projetos criados via `npx xertica-ui@latest init`, fornecendo contexto arquitetural (FSD/FDA, subpath imports, tokens semânticos) para Claude Code e outros assistentes de IA.
-- **Storybook stories** — adicionadas stories interativas para Accordion, AlertDialog, Button, Checkbox, Dialog, Input, Switch, Tabs, HomePage e TemplatePage.
-- **`components/pages/home-page/home-page.mdx`** e **`template-page.mdx`** — novas entradas de documentação MDX para as page components.
-
-### Changed
-
-- **`guidelines/Guidelines.md`** — reescrita completa do guia de arquitetura FSD/FDA: maior detalhamento de responsabilidades por camada, convenções de import e fluxo de adição de novas rotas.
-- **`components.json`** — atualização completa do registro de componentes, cobrindo todos os 97 componentes com metadados de subpath, props e variantes.
-- **`llms.txt`** — seção de subpath imports e mapeamento de camadas FSD/FDA atualizados.
-- **`vite.config.ts`** — ajustes no build multi-entry para garantir correta emissão dos arquivos CJS/ESM.
-
-### Fixed
-
-- **`npx xertica-ui init` usa versão em cache** — documentado que o npx armazena pacotes em cache localmente sem TTL curto. Sempre use `npx xertica-ui@latest init` para garantir a versão mais recente. O `templates/CLAUDE.md` scaffolded no projeto gerado inclui essa orientação.
-
----
-
-## [2.0.3] — 2026-05-11
-
-### Added
-
-- **CLI `update` — atualização de projeto** — novo modo no comando `update` permite atualizar os arquivos do projeto (app shell, shared, features, pages) para qualquer versão publicada do `xertica-ui`, com seleção granular de quais partes atualizar e confirmação antes de sobrescrever.
-
----
-
-## [2.0.2] — 2026-05-11
-
-### Fixed
-
-- **CLI rewritten for FSD/FDA structure** — `npx xertica-ui@latest init` agora copia corretamente a estrutura Feature-Sliced Design:
-  - Removida cópia de `src/app/routes.tsx` (arquivo não existe mais após refatoração)
-  - Adicionada cópia de `src/app/components/AppLayout.tsx`
-  - Adicionada cópia completa de `src/shared/` (`auth.ts`, `navigation.ts`, `types/auth.ts`)
-  - Adicionada cópia de `src/features/auth|home|template` conforme seleções do usuário
-  - Cópia de pages corrigida de `src/app/pages/` → `src/pages/`
-  - `AuthGuard.tsx` agora gerado dinamicamente com imports e rotas apenas das páginas selecionadas
-- **`generateDemoResponse` exportado via `xertica-ui/assistant`** — estava ausente do barrel causando `SyntaxError: does not provide an export named 'generateDemoResponse'`
-- **Build corrigido: UMD → CJS** — múltiplos entry points não são suportados com formato UMD no Vite; migrado para CJS (todos os `*.umd.js` → `*.cjs.js` no `package.json` exports)
-
----
-
-## [2.0.0] — 2026-05-11
-
-### Added
-
-- **Subpath exports** — The package now exposes 6 granular entry points alongside the full root barrel:
-  - `xertica-ui/ui` — all UI primitives (Button, Card, Input, Table, Dialog, etc.)
-  - `xertica-ui/layout` — Sidebar and Header
-  - `xertica-ui/brand` — XerticaProvider, XerticaLogo, XerticaXLogo, XerticaOrbe, ThemeToggle, LanguageSelector
-  - `xertica-ui/assistant` — XerticaAssistant, MarkdownMessage, CodeBlock, FormattedDocument, ModernChatInput
-  - `xertica-ui/media` — VideoPlayer, AudioPlayer, FloatingMediaWrapper
-  - `xertica-ui/hooks` — useLayout, useTheme, useLanguage, useBrandColors, useAssistente, useApiKey
-  - Root `from 'xertica-ui'` remains fully supported for backward compatibility.
-- **`ImageWithFallback` added to `xertica-ui/ui`** — previously only in the root barrel; now accessible via the `/ui` subpath.
-- **Multi-entry Vite build** — `vite.config.ts` now uses `lib.entry` as an object (7 entry points). Output filenames follow `[entryName].[format].js` pattern.
-- **CLI template — FSD/FDA architecture** — The scaffolded template was restructured to follow Feature-Sliced Design + Feature-Driven Architecture:
-  - `src/app/` — BrowserRouter, XerticaProvider, AuthGuard (auth state + route definitions), AppLayout (Sidebar + children shell)
-  - `src/shared/` — `config/navigation.ts` (route registry), `lib/auth.ts` (localStorage helpers), `types/auth.ts` (User interface)
-  - `src/features/auth/ui/` — LoginContent, ForgotPasswordContent, VerifyEmailContent, ResetPasswordContent; with shared `AuthPageShell` and `SocialLoginButtons` DRY extractions
-  - `src/features/home/ui/` — HomeContent
-  - `src/features/template/ui/` — TemplateContent, FormTemplate
-  - `src/pages/` — thin page wrappers (LoginPage, HomePage, TemplatePage, ForgotPasswordPage, VerifyEmailPage, ResetPasswordPage)
-- **`templates/guidelines/Guidelines.md`** — new architecture guide documenting FSD/FDA layers, layer responsibilities, and "Adding New Routes" step-by-step.
-
-### Changed
-
-- **Template imports** — All template source files updated to use subpath imports (`xertica-ui/ui`, `xertica-ui/brand`, `xertica-ui/layout`, `xertica-ui/assistant`, `xertica-ui/hooks`) instead of the root barrel.
-- **`FormTemplate.tsx` rewritten** — Removed dependency on `@hookform/resolvers/zod`, `react-hook-form`, and `zod` (packages not included in the CLI template's `package.json`). Now uses plain React `useState` + inline validation with only `xertica-ui/ui` primitives.
-- **`tsconfig.build.json`** — `include` array updated to cover all new barrel source directories (`components/**/*`, `contexts/**/*`, `hooks/**/*`).
-- **Documentation** (`llms.txt`, `llms-full.txt`) — Added subpath import reference table and FSD/FDA layer mapping.
-
-### Fixed
-
-- **Stale compiled artifacts** — Removed `App.js`, `App.d.ts`, `main.js`, `main.d.ts` from `templates/src/app/` that were being resolved by Vite's extension priority (`.js` before `.tsx`), causing `Failed to fetch dynamically imported module` errors after the FSD restructure.
-
----
-
-## [1.10.0] — 2026-05-08
-
-### Added
-
-- **Semantic Variants** — Added `success`, `info`, and `warning` variants to components that lacked them:
-  - **Button** — now supports 9 variants: `default`, `secondary`, `outline`, `ghost`, `destructive`, `link`, `success`, `info`, `warning`.
-  - **Progress** — new `variant` prop (`default`, `success`, `info`, `warning`, `destructive`) colors both the track and the indicator.
-  - **NotificationBadge** — added `secondary`, `outline`, `success`, `info`, `warning`; standardized `default` to primary color for consistency with Badge and Button.
-  - **TimelineDot** — added `info` and `outline` variants; replaced hardcoded `rgb()` values with semantic CSS tokens (`bg-success`, `bg-warning`).
-- **DialogBody** — new sub-component for the Dialog. When used, `DialogHeader` and `DialogFooter` stay pinned while `DialogBody` scrolls independently. Exported from `xertica-ui`.
-- **Dialog height management** — `DialogContent` now has `max-h-[calc(100dvh-2rem)] overflow-hidden`. The close button (×) is pinned and never scrolls with content. `size="full"` fills the full viewport height.
-- **Header `breadcrumbSlot`** — new prop accepting any `ReactNode` rendered immediately after the breadcrumb/title area (badges, buttons, status chips, etc.).
-- **Sidebar default variant groups** — `variant="default"` now renders `navigationGroups` with labeled group headers. Each `RouteConfig` supports a `children` field (sub-routes shown in a contextual `DropdownMenu` via a `ChevronRight` button at the end of the item).
-
-### Fixed
-
-- **Search double clear icon** — `type="search"` caused browsers to inject a native clear button on top of the custom × icon. Changed to `type="text"`.
-- **CSS `@source` path** — CLI template `src/styles/index.css` had `../node_modules/xertica-ui` (one level short); corrected to `../../node_modules/xertica-ui/components`.
-- **`theme-map.css` incomplete** — `--color-success`, `--color-info`, `--color-warning` and their `foreground` variants were missing, preventing `bg-success`, `text-info`, etc. from being generated in the compiled library CSS.
-
-### Changed
-
-- **Storybook argTypes** — Multiple components had controls missing from the Storybook panel: Badge (`success`/`info`/`warning` options), Select (`size`), Avatar (`size`), Rating (`readonly` casing), Timeline (`dotVariant`), Dialog (`size` available in all stories). All corrected.
-- **LLM documentation** (`llms-full.txt`) — Updated Badge, Button, Dialog, Header, NotificationBadge, Progress, Search, Sidebar, and Timeline sections to reflect current APIs.
-
----
-
-## [1.9.0] — 2026-05-05
-
-### Added
-- **Standardized Form Sizing System** — Implemented a unified `size` prop (`sm`, `md`, `lg`) across all form-related components for perfect visual alignment in grid layouts:
-  - **Text Components** — `Input`, `SelectTrigger`, `Textarea`, `Search`, and `InputOTPSlot` now share consistent height/padding/font-size tokens.
-  - **Toggle Components** — `Checkbox`, `RadioGroupItem`, and `Switch` now feature dynamic sizing for both containers and internal indicators (check icon, dot, thumb).
-  - **Labels** — `Label` component now supports `size` to match the text size of the associated input.
-  - **Reference Guide** — Added `docs/form-sizing.md` as a comprehensive guide for the standardized sizing scale.
-- **Assistant Individual Controls** — Added granular control props to `XerticaAssistant` to toggle specific features independently:
-  - `showHistory`, `showFavorites`, `allowAudioInput`, `allowFileUpload`, `allowDocCreation`, `allowPodcastGen`, `allowResearchGen`.
-- **Header Breadcrumb Navigation** — Standardized `Header` to use breadcrumbs as the default navigation pattern:
-  - Added support for `react-router-dom` links in breadcrumbs to prevent page reloads.
-  - Configurable hierarchy levels and labels directly via props.
-
-### Changed
-- **Form Component Architecture** — Migrated form elements from legacy tokens to standardized design system tokens (`bg-background`, `border-border`) for better theme consistency.
-- **Documentation & Storybook** — Updated all 9 affected form components with new "Sizes" sections in Storybook (Stories + MDX) and enriched LLM-facing markdown documentation.
-- **Unit Testing** — Updated test suites for `Checkbox`, `RadioGroup`, `Switch`, `InputOTP`, `Label`, `Search`, `Select`, and `Textarea` to verify sizing variant classes.
-
-### Fixed
-- **Search Component** — Removed obsolete `loading` prop which was causing TypeScript errors and was redundant with the current design system patterns.
-- **SelectTrigger Sizing** — Standardized `md` height to `h-10` (40px) to match the rest of the form system.
-
----
-
-## [1.8.0] — 2026-04-27
-
-### Added
-- **VideoPlayer UI Enhancements** — Added gradient overlay on controls for improved contrast against video content:
-  - Gradient: `from-black/60 via-black/30 to-transparent` with `pt-12` spacing
-  - White progress bar with `bg-white/30` track, `bg-white` fill, and `rounded-r-sm` on filled portion
-  - White icons with `drop-shadow-md` for visibility
-  - Buttons use `text-white hover:text-white hover:bg-black/50` for proper hover states
-- **Slider Visual Fixes** — Improved progress bar alignment:
-  - Added left margin `ml-2` to track for thumb alignment
-  - Added `rounded-r-sm` to Range for filled portion
-  - Adjusted track/margins for proper visual alignment at full value
-
-### Changed
-- **Documentation** — Updated component counts across all docs:
-  - `llms.txt`: 75 → 97 components
-  - `llms-full.txt`: Added statistics table
-  - `docs/llms.md`: Added statistics section
-  - `Introduction.mdx`: Added "97 Components" badge
-- **components.json** — 75 → 89 components (added missing Media, Assistant, Pages, and Map components)
-
-### Fixed
-- **Slider Progress Bar** — Fixed visual gap where thumb doesn't align with filled bar at end position by adjusting track margins
-
----
-
-## [1.7.0] — 2026-04-23
-
-### Fixed
-- **CLI CSS Theme Import** — Corrected `@theme` → `@theme inline` in both the library's `index.css` and the generated template `src/styles/index.css`. Plain `@theme {}` was causing Tailwind v4 to resolve color tokens statically at build time using the library's defaults, preventing consumer `tokens.css` overrides from propagating into utility classes (`bg-destructive`, `bg-primary`, alert colors, etc.).
-- **Dark Mode `--primary`** — Added missing `--primary: var(--xertica-primary)` in the dark mode block of `tokens.css` (library, template, and generator). Components using `bg-primary` were not picking up the dark mode brand color.
-- **Dark Mode Chart Tokens** — Generator (`bin/generate-tokens.ts`) now includes `--chart-1` through `--chart-5` in the dark mode section for all generated `tokens.css` files.
-
-### Added
-- **CLI `update` command** — `npx xertica-ui@latest update` prompts the user to select a new color theme and overwrites `src/styles/xertica/tokens.css` with the newly generated tokens, preserving all other project files.
-- **Template `@theme inline` mapping** — Generated `src/styles/index.css` now includes a complete `@theme inline {}` block mapping all tokens (sidebar, charts, gradients, brand, radii) to CSS variable aliases, ensuring full theme coverage for consumer projects.
-- **Documentation** — `docs/getting-started.md` updated with CLI `update` command reference and a new "CSS Setup (Critical)" section explaining the `@theme inline` requirement.
-
----
-
-## [1.6.0] — 2026-04-20
-
-### Added
-- **`docs/llms.md`** — Master LLM/AI-agent entrypoint index with full component catalog, token quick reference, and reading order guide.
-- **`docs/layout.md`** — Complete `LayoutContext` and `useLayout()` API reference.
-- **`docs/components/route-map.md`** — New documentation for `RouteMap` component.
-- **`docs/components/use-mobile.md`** — New documentation for `useMobile` / `useIsMobile` hooks.
-- **`Header`** — New props: `user` (profile with avatar, name, email, and dropdown menu items), `actions` (custom icon action buttons), `showSettings` / `onSettingsClick`, `showLogout` / `onLogoutClick`. Fixed render order: Language → Theme → Actions → Settings → User → Logout.
-- **`Sidebar`** — New `width` prop (`expandedWidth: number`) for configuring the expanded sidebar pixel width. Width is now read and stored via `LayoutContext.sidebarWidth`.
-
-### Changed
-- **Documentation** — All 61 component docs, 5 pattern docs, and 6 root docs fully rewritten in English with standardized structure (Overview, When to Use, Anatomy, Props table, Examples, AI Rules, Related Components).
-- **JSDoc** — All Portuguese JSDoc comments in `components/ui/` translated to English and enriched with accurate `@ai-rules`.
-- **`README.md`** — Complete rewrite in English, restructured for npm page quality (quick start, install guide, component catalog, token reference, AI agent entrypoint, troubleshooting).
-- **`package.json`** — Version bumped to `1.6.0`. Description translated to English.
-
-### Fixed
-- **`docs/components/page-header.md`** — Was documenting a wrong API (`title/description/actions`). Now correctly documents the real API: `breadcrumbs[]`, `showLanguageSelector`, `rightContent`, `PageHeaderHeading`, `PageHeaderDescription`.
-- **`docs/components/stepper.md`** — Was documenting a `steps[]` array prop. Now correctly documents the composable `<Stepper currentStep> + <Step step label>` API (1-indexed).
-- **`docs/components/empty.md`** — Was documenting single-prop component. Now correctly documents the composable sub-component pattern: `Empty > EmptyIcon > EmptyTitle > EmptyDescription > EmptyAction`.
-- **`docs/components/stats-card.md`** — `trend` was documented as a string. Now correctly documented as `{ value: number; label?: string }`.
-- **`docs/components/chart.md`** — Was documenting raw Recharts usage. Now correctly documents the `ChartContainer + ChartConfig + var(--color-*)` pattern.
-
----
-
-## [1.5.2] — 2026-04-15
-
-### Fixed
-- Resolved regression where modal components (Dialog/AlertDialog) failed to render in projects initialized via the CLI.
-- Implemented robust CSS integration using Tailwind v4 theme mappings.
-- Ensured Radix UI portals correctly inherit theme variables.
-
----
-
-## [1.5.1] — 2026-04-14
-
-### Changed
-- Sidebar: Added `assistente` variant with fixed areas, searchable navigation, and grouped navigation structures.
-- Template page updated to demonstrate the assistant sidebar variant.
-
----
-
-## [1.5.0] — 2026-04-13
-
-### Added
-- `Sidebar` — `width` / `expandedWidth` prop for configurable expanded sidebar width.
-- `LayoutContext` — `sidebarWidth` and `setSidebarWidth` for global sidebar width management.
-- `Header` — User profile section with avatar, dropdown menu, settings button, and logout button.
-- `StatsCard` — KPI metric card component.
-- `Timeline` — Chronological event list with dot variants.
-- `TreeView` — Hierarchical tree navigation.
-- `Rating` — Star-based rating input.
-- `FileUpload` — Drag-and-drop file input.
-- `Search` — Pre-built search input with icon and clear button.
-- `NotificationBadge` — Dot/count badge overlay.
-- `RouteMap` — Google Maps route display and direction calculation.
-- `Stepper` — Multi-step progress indicator.
-- `Map` — Advanced Google Maps integration with markers, circles, polygons, and layers.
-- `XerticaAssistant` — Embedded Gemini AI assistant panel.
+# Changelog
+
+All notable changes to `xertica-ui` will be documented in this file.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [2.1.10] — 2026-05-20
+
+### Added
+
+- **`AuthContext` / `useAuth()`** — novo contexto de autenticação em `contexts/AuthContext.tsx`. `AuthProvider` gerencia sessão via `localStorage`, expõe `user`, `isLoading`, `login(email, password) → boolean` e `logout()`. `isLoading` previne flashes de redirect durante hidratação. O `AuthProvider` deve ser montado dentro do `<Router>` (depende de `useNavigate`).
+- **`ErrorBoundary` — três variantes pré-configuradas** em `components/shared/error-boundary.tsx`:
+  - `AppErrorBoundary` — envolve todo o `App` antes dos providers; fallback full-screen com inline styles (funciona mesmo se o Tailwind falhar)
+  - `PageErrorBoundary` — envolve `<Routes>` / `<AuthGuard>`; captura lazy-chunk failures e erros de renderização de página
+  - `SectionErrorBoundary` — envolve seções isoladas (tabelas, charts, assistente); um seção quebrada não derruba a página
+  - Props: `onError` (callback para Sentry/Datadog), `resetKeys` (auto-reset quando um valor muda, ex: `[location.pathname]`)
+- **i18n completo com `i18next` + `react-i18next`** — integração completa de internacionalização:
+  - Arquivo `i18n.ts` configurado com `pt-BR` (padrão), `en` e `es`
+  - Locale files em `locales/pt-BR.json`, `en.json`, `es.json` com namespaces: `common`, `nav`, `home`, `stats`, `team`, `assistant`, `languageSelector`
+  - `LanguageContext.setLanguage()` agora chama `i18n.changeLanguage()` — todos os `useTranslation()` re-renderizam
+  - `HomeContent.tsx` e `TemplateContent.tsx` usam `useTranslation()` para todos os textos
+  - Mock data usa `i18n.t()` (instância) para responder ao idioma ativo no `queryFn`
+- **`features/` — camada de estado separada da UI**:
+  - `features/home/data/mock.ts` — tipos + dados mock + funções `fetch*()` (swap point para API real)
+  - `features/home/hooks/` — `useDashboardStats`, `useTeamMembers`, `useFeatureCards` (TanStack React Query)
+  - `features/home/store/dashboardStore.ts` — Zustand (progress, slider, switch, activeTab)
+  - `features/assistant/data/mock.ts` — `AssistantConfig` + `fetchAssistantConfig()`
+  - `features/assistant/hooks/useAssistantConfig.ts` — React Query, staleTime 30 min
+- **`QueryClientProvider`** adicionado ao stack de providers em `App.tsx` como camada mais externa (abaixo de `AppErrorBoundary`)
+- **Lazy loading** em todas as rotas via `React.lazy()` + `<Suspense fallback={null}>` — cada página é um chunk separado
+- **`ProtectedRoute` + `GuestRoute`** como componentes de guarda de rota baseados em `useAuth()` — eliminam lógica de redirect do `AuthGuard`
+- **`components/shared/navigation.ts`** — fonte canônica de `RouteConfig`, `routes[]`, `getRouteByPath` e `isValidRoute` para o app devops (substituiu `routes.tsx` na raiz)
+
+### Changed
+
+- **`LanguageSelector` — refatorado para usar `LanguageContext` e `i18next`** — removidos `useState` local, props `initialLanguage` e `onLanguageChange`. O componente agora lê de `useLanguage()` e chama `i18n.changeLanguage()` diretamente. `aria-label` e labels dos itens são traduzidos via `useTranslation()`. **Breaking**: `initialLanguage` e `onLanguageChange` foram removidos da API pública.
+- **`LanguageContext` — conectado ao `i18next`** — `setLanguage(lang)` persiste no `localStorage` E chama `i18n.changeLanguage(lang)` em uma única operação. Type mismatch corrigido: `LanguageSelector` usava `'pt'`, contexto usava `'pt-BR'` — unificado para `'pt-BR'`.
+- **`App.tsx` — limpeza da lógica de tema duplicada** — removidos IIFE top-level e `useLayoutEffect` que manipulavam `localStorage`/`classList` para garantir light mode. O `ThemeProvider` já gerencia isso corretamente; as camadas redundantes conflitavam.
+- **`HomePage` + `TemplatePage` — sem props `user`/`onLogout`** — ambos consomem `useAuth()` diretamente; prop-drilling eliminado em toda a árvore de páginas (`HomeContent`, `TemplateContent`, `AppLayout`).
+- **`routes.tsx` deletado** — conteúdo movido para `components/shared/navigation.ts`; todos os imports atualizados.
+
+### Fixed
+
+- **`useRichTextEditor` — `wordCount`/`characterCount` agora são `useState`** — as IIFEs que calculavam os contadores a cada render foram substituídas por estado React (`useState(0)`). `handleInput` atualiza os contadores imediatamente após cada digitação; um `useEffect([value])` os sincroniza quando o valor é alterado externamente.
+- **`useRichTextEditor` — `eslint-disable` removido do effect de seleção** — o effect único de mount com `// eslint-disable-next-line` foi dividido em dois: um `useRef` que mantém `updateActiveFormats` sempre atualizado e um effect de mount-only que registra o listener `selectionchange` via ref, eliminando re-registros e o disable de lint.
+- **`useAssistant` — timers vazados corrigidos** — `responseTimerRef` e `commandTimerRef` substituem os `setTimeout` bare em `handleEnviarMensagem` e `handleExecuteSearchCommand`; um effect de cleanup no unmount cancela ambos com `clearTimeout`.
+- **`useAssistant` — hydration one-shot de `initialMessages`** — `hydratedRef` garante que `setMensagens(initialMessages)` ocorra apenas uma vez, evitando reset do histórico em re-renders.
+- **`useAssistant` — scroll condicional ≤ 120px** — o auto-scroll só aciona `scrollIntoView` quando o usuário está a menos de 120 px do fundo, preservando a posição durante leitura de histórico.
+- **`useAudioPlayer` — `eslint-disable` removido do effect de modo-switch** — `currentTimeRef` e `isPlayingRef` (latest-ref pattern) substituem referências diretas ao estado dentro do effect `[isFloating, variant]`, eliminando a necessidade do disable de lint.
+- **`useStepper` — `initialStep` inválido** — lazy initializer com `Math.min(Math.max(1, initialStep), totalSteps)` garante que o estado inicial nunca fique fora do intervalo `[1, totalSteps]`.
+- **`useTreeView` — `Space` e `Enter` separados** — `Space` expande/colapsa nós-pai e seleciona folhas; `Enter` expande/colapsa e sempre seleciona, alinhando com WAI-ARIA Tree Pattern 1.2.
+- **`sidebar.tsx` — loop de re-render corrigido** — dependência do effect de overflow revertida de `navigationItems` para `navigationItems.length` para evitar loop causado pela nova referência de array gerada pelo `useMemo` a cada mudança de rota.
+- **`useAssistant` — `setConversas(savedConversations)` em loop corrigido** — removido `useEffect` que chamava `setConversas` com `savedConversations = []` (default do destructuring), causando re-render infinito.
+
+### Changed (continued)
+
+- **`RichTextEditor` — ARIA no `contentEditable`** — adicionados `role="textbox"`, `aria-multiline`, `aria-label`, `aria-readonly` e `aria-disabled` no div editável. Removido o texto "Auto-save ativo" do rodapé.
+- **`Stepper` — ARIA de lista** — o wrapper dos steps recebe `role="list"` + `aria-label="Progresso: etapa N de M"`. Cada `<Step>` recebe `role="listitem"`, `aria-current="step"` (quando ativo) e `aria-label` composto com status.
+- **`Pagination` — prop `disabled` em `PaginationLink`** — `PaginationLink` aceita `disabled?: boolean`; aplica `pointer-events-none opacity-50`, `aria-disabled`, `tabIndex={-1}` e remove `href`. `PaginationPrevious` e `PaginationNext` repassam `disabled`.
+- **`usePagination` — algoritmo deduplicado com `Set`** — reescrito usando `Set<number>` para garantir que cada página apareça exatamente uma vez.
+- **`TreeView` — prop `ariaLabel` + roving tabindex** — `<TreeView>` aceita `ariaLabel?: string`; roving tabindex: `focusableId = effectiveSelectedId ?? data[0]?.id`.
+- **`DashboardBarChart` — `topOfStack` com `useMemo`** — IIFE extraída para `React.useMemo([stacked, chartSeries])` antes do `return`.
+- **`useAssistant` — `conversasFiltradas` com `useMemo`** e tipos fortalecidos (`handleEnviarMensagem: (arg?: string | ActionType) => Promise<void>`).
+- **`sidebar.tsx` — ARIA** — botão de toggle recebe `aria-expanded` e `aria-controls="sidebar-nav"`; `<nav>` recebe `id="sidebar-nav"` e `aria-label="Navegação principal"`. `navigationItems` memoizado com `useMemo`.
+
+---
+
+- **`useRichTextEditor` — `wordCount`/`characterCount` agora são `useState`** — as IIFEs que calculavam os contadores a cada render foram substituídas por estado React (`useState(0)`). `handleInput` atualiza os contadores imediatamente após cada digitação; um `useEffect([value])` os sincroniza quando o valor é alterado externamente.
+- **`useRichTextEditor` — `eslint-disable` removido do effect de seleção** — o effect único de mount com `// eslint-disable-next-line` foi dividido em dois: um `useRef` que mantém `updateActiveFormats` sempre atualizado e um effect de mount-only que registra o listener `selectionchange` via ref, eliminando re-registros e o disable de lint.
+- **`useAssistant` — timers vazados corrigidos** — `responseTimerRef` e `commandTimerRef` substituem os `setTimeout` bare em `handleEnviarMensagem` e `handleExecuteSearchCommand`; um effect de cleanup no unmount cancela ambos com `clearTimeout`.
+- **`useAssistant` — hydration one-shot de `initialMessages`** — `hydratedRef` garante que `setMensagens(initialMessages)` ocorra apenas uma vez, evitando reset do histórico em re-renders.
+- **`useAssistant` — scroll condicional ≤ 120px** — o auto-scroll só aciona `scrollIntoView` quando o usuário está a menos de 120 px do fundo, preservando a posição durante leitura de histórico.
+- **`useAudioPlayer` — `eslint-disable` removido do effect de modo-switch** — `currentTimeRef` e `isPlayingRef` (latest-ref pattern) substituem referências diretas ao estado dentro do effect `[isFloating, variant]`, eliminando a necessidade do disable de lint.
+- **`useStepper` — `initialStep` inválido** — lazy initializer com `Math.min(Math.max(1, initialStep), totalSteps)` garante que o estado inicial nunca fique fora do intervalo `[1, totalSteps]`.
+- **`useTreeView` — `Space` e `Enter` separados** — `Space` expande/colapsa nós-pai e seleciona folhas; `Enter` expande/colapsa e sempre seleciona, alinhando com WAI-ARIA Tree Pattern 1.2.
+
+### Changed
+
+- **`RichTextEditor` — ARIA no `contentEditable`** — adicionados `role="textbox"`, `aria-multiline`, `aria-label`, `aria-readonly` e `aria-disabled` no div editável. Removido o texto "Auto-save ativo" do rodapé (informação sem valor de UX).
+- **`Stepper` — ARIA de lista** — o wrapper dos steps recebe `role="list"` + `aria-label="Progresso: etapa N de M"`. Cada `<Step>` recebe `role="listitem"`, `aria-current="step"` (quando ativo) e `aria-label` composto com status (atual/concluída).
+- **`Pagination` — prop `disabled` em `PaginationLink`** — `PaginationLink` aceita `disabled?: boolean`; quando ativo aplica `pointer-events-none opacity-50`, `aria-disabled`, `tabIndex={-1}` e remove `href`. `PaginationPrevious` e `PaginationNext` repassam `disabled` ao link.
+- **`usePagination` — algoritmo deduplicado com `Set`** — o cálculo de `items` foi reescrito usando `Set<number>` para garantir que cada página apareça exatamente uma vez, eliminando edge cases do algoritmo anterior com `leftSibling === 2` / `rightSibling === totalPages - 1`.
+- **`TreeView` — prop `ariaLabel` + roving tabindex** — `<TreeView>` aceita `ariaLabel?: string` (padrão `"Navegação em árvore"`) aplicado ao `role="tree"`. O `tabIndex` de cada item usa roving tabindex: `focusableId = effectiveSelectedId ?? data[0]?.id` em vez de `isSelected ? 0 : -1`.
+- **`DashboardBarChart` — `topOfStack` com `useMemo`** — a IIFE que calculava o conjunto de barras do topo do stack no JSX foi extraída para `React.useMemo([stacked, chartSeries])` antes do `return`, separando lógica de render.
+- **`useAssistant` — `conversasFiltradas` com `useMemo`** — substituída computação inline por `useMemo([conversas, abaSelecionada])`.
+- **`useAssistant` — sincronização de `conversas` com `savedConversations`** — adicionado `useEffect([savedConversations])` que mantém `conversas` em sync com a prop `savedConversations`.
+- **`useAssistant` — tipos fortalecidos** — `handleEnviarMensagem` tipado como `(arg?: string | ActionType) => Promise<void>` na interface e na implementação, substituindo `string | any`.
+- **`sidebar.tsx` — ARIA e `useMemo`** — botão de toggle recebe `aria-expanded` e `aria-controls="sidebar-nav"`; o `<nav>` recebe `id="sidebar-nav"` e `aria-label="Navegação principal"`. `labelTranslations` e `navigationItems` memoizados com `useMemo`; dependência do effect de overflow atualizada de `navigationItems.length` para `navigationItems`.
+
+---
+
+## [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
+
+- **Headless hooks — 4 new logic-only hooks** — all logic extracted from their UI components into standalone, tree-shakeable hooks:
+  - **`useFileUpload`** — drag state, file validation (size + count), error messaging, and hidden input ref. Props: `maxFiles`, `maxSize`, `onFilesChange`, `onError`, `disabled`. Returns: `files`, `dragActive`, `errorMessage`, `inputRef`, `handleFiles`, `handleDrag`, `handleDrop`, `handleChange`, `removeFile`, `openFileDialog`.
+  - **`usePagination`** — computes the full page item list (page numbers + ellipsis markers) and exposes navigation helpers. Supports controlled (`page` prop) and uncontrolled modes. Props: `totalItems`, `pageSize`, `initialPage`, `page`, `onPageChange`, `siblingCount`. Returns: `currentPage`, `totalPages`, `startIndex`, `endIndex`, `canGoPrev`, `canGoNext`, `isFirstPage`, `isLastPage`, `items: PaginationPageItem[]`, `goTo`, `next`, `prev`, `first`, `last`.
+  - **`useStepper`** — step navigation with optional async `onBeforeNext` guard for per-step validation. Supports controlled (`step` prop) and uncontrolled modes. Props: `totalSteps`, `initialStep`, `step`, `onStepChange`, `onBeforeNext`. Returns: `currentStep`, `totalSteps`, `isFirstStep`, `isLastStep`, `canGoPrev`, `canGoNext`, `next` (async), `prev`, `goTo`, `reset`.
+  - **`useTreeView`** — expand/collapse state, single-node selection, full WAI-ARIA keyboard navigation (Arrow keys, Home, End, Space), and DOM focus management via `nodeRefs`. Supports controlled `selectedNodeId`. Returns: `expanded`, `effectiveSelectedId`, `nodeRefs`, `getNodeRef`, `toggleExpand`, `handleSelect`, `handleKeyDown`, `getVisibleNodes`.
+- **New chart types — 4 new Recharts wrappers** added to `components/ui/chart/chart.tsx`:
+  - **`RadarMetricChart`** — multi-axis radar chart with optional fill, dots, and multi-series overlay.
+  - **`PieMetricChart`** — pie chart with optional percentage labels and exploded slice support.
+  - **`RadialBarMetricChart`** — radial bar chart with stacked rings and configurable arc angle.
+  - **`GaugeChart`** — pure SVG semicircle gauge with needle, threshold color zones, and optional label. Supports `thresholds` array for dynamic color changes at value breakpoints.
+- **Chart color tokens expanded** — added `--chart-6`, `--chart-7`, `--chart-8` tokens to `styles/xertica/tokens.css`, `templates/src/styles/xertica/tokens.css`, and `bin/generate-tokens.ts`. All 8 chart tokens now use a vibrant, accessible palette.
+- **Headless hook stories** — added `HeadlessHook` story variant to `file-upload.stories.tsx`, `pagination.stories.tsx`, `stepper.stories.tsx`, and `tree-view.stories.tsx` demonstrating fully custom UIs built with each hook.
+
+### Fixed
+
+- **`GaugeChart` — filled-blob visual bug for values > 50%** — the SVG arc `largeArc` flag was set to `1` when `percent > 0.5`, causing the arc command to draw the reflex arc (> 180°) which rendered as a solid filled blob. Since the gauge is a semicircle (max 180°), `largeArc` is always `0`. Removed the conditional entirely and hardcoded `0` for both arc commands.
+- **`GaugeChart` — needle overlapping value text** — the value text at `y=cy+4` was directly behind the needle pivot circle. Fixed by expanding the SVG `viewBox` from `"0 0 200 110"` to `"0 0 200 130"` and moving the value text to `y=cy+18` (13 px below the needle base circle bottom) and the label text to `y=cy+36`.
+
+### Changed
+
+- **`FileUpload` component** — refactored to consume `useFileUpload` internally; public API unchanged.
+- **`TreeView` component** — refactored to consume `useTreeView` internally; public API unchanged.
+- **`Stepper` component** — refactored to consume `useStepper` internally; public API unchanged.
+- **Documentation** — updated `docs/components/chart.md`, `docs/components/file-upload.md`, `docs/components/pagination.md`, `docs/components/stepper.md`, and `docs/components/tree-view.md` with full hook API reference, props/return tables, controlled/uncontrolled examples, and AI Rules sections.
+
+---
+
+## [2.1.2] — 2026-05-14
+
+### Fixed
+
+- **`MarkdownMessage` — suporte a tabelas GFM** — o parser regex do componente não convertia blocos de tabela Markdown (`| col | col |`) em HTML. Adicionada transformação de tabelas GFM completa (header, separador, linhas de dados) com estilos do design system (`border-border`, `hover:bg-muted/50`, `rounded-[var(--radius)]`, `overflow-x-auto`). A transformação roda antes das substituições de quebra de linha para evitar `<br/>` dentro das células.
+
+### Added
+
+- **Template — `AssistantPage`** — nova página de assistente completa: sidebar em modo `assistant` aberta por padrão (largura 320px), botão "Nova Conversa" (`variant="secondary"`), busca de conversas com filtro em tempo real, histórico de 8 conversas de exemplo em 3 grupos (Hoje / Ontem / Esta semana), modal de exclusão com `AlertDialog`, modal de renomeação com `Dialog` + `Input`, simulação de conteúdo ao selecionar conversa via `initialMessages`, botão "Voltar" em `variant` primário no `Header`.
+- **Template — `AppLayout`** — novas props `sidebarVariant?: 'default' | 'assistant'` e `sidebarProps?: Record<string, any>` para permitir que páginas customizem a sidebar sem quebrar o contrato do layout.
+
+---
+
+## [2.1.1] — 2026-05-14
+
+### Fixed
+
+- **XerticaAssistant — tab bar oculta em modo chat-only** — quando `showHistory` e `showFavorites` estão ambas desativadas, a barra de abas (incluindo a aba "Chat") deixa de ser renderizada, eliminando a exibição de uma aba isolada sem alternativas de navegação.
+- **`xertica-ui/style.css` — import duplo de Roboto removido** — o `@import url(Google Fonts/Roboto)` foi removido de `styles/globals.css`. A importação da fonte passa a ser responsabilidade do app consumidor, eliminando o alerta `@import must precede all other statements` do PostCSS quando o CSS compilado era injetado após o output do Tailwind v4.
+
+---
+
+## [2.1.0] — 2026-05-13
+
+### Added
+
+- **`components/blocks/card-patterns/`** — novo domínio `blocks/` com 6 componentes de alto nível compostos exclusivamente de primitivos `ui/`:
+  - **`FeatureCard`** — ícone com fundo colorido, título, badge opcional, descrição e botão de ação. Suporta 10 tokens de cor (`primary`, `chart-1..5`, `success`, `info`, `warning`, `destructive`). Replica o padrão de cards da Home page.
+  - **`ActivityCard`** — feed de atividades recentes com avatar, descrição de ação, timestamp e badge por tipo (`create`, `update`, `delete`, `comment`, `deploy`).
+  - **`ProfileCard`** — card de usuário/membro com avatar, badge de status (`online`, `offline`, `away`, `busy`), linha de stats e ações primária/secundária.
+  - **`ProjectCard`** — status de projeto com badge, barra de progresso (usa `Progress` com variant semântica por status), stack de avatares de membros e data limite.
+  - **`QuickActionCard`** — tile de ação rápida com ícone em caixa colorida, badge e botão full-width.
+  - **`NotificationCard`** — lista de notificações com indicador de não-lido, badge de tipo, "Marcar todas como lidas" e "Ver todas".
+- **Exportação do domínio `blocks/`** — todos os componentes disponíveis via `import { ... } from 'xertica-ui'` e via `components/blocks/index.ts`.
+- **Subpath público `xertica-ui/blocks`** — `FeatureCard`, `ActivityCard`, `ProfileCard`, `ProjectCard`, `QuickActionCard` e `NotificationCard` agora podem ser importados diretamente de `xertica-ui/blocks`.
+- **Subpath público `xertica-ui/pages`** — `LoginPage`, `HomePage`, `TemplatePage`, `ForgotPasswordPage`, `ResetPasswordPage`, `VerifyEmailPage` e seus contents agora são publicados com entrypoint dedicado.
+- **Documentação** — criado `docs/components/card-patterns.md` com props, exemplos e layout de dashboard completo para todos os 6 block components.
+
+### Changed
+
+- **Calendar — dropdown caption styling** — quando `captionLayout="dropdown"` ou variações, os seletores de mês/ano agora têm visual de input (borda, fundo `bg-background`, focus ring `ring-primary`, `rounded-[var(--radius)]`, padding compacto fixo `px-2.5 py-1`). O `caption_label` em modo dropdown passa a usar `h-full w-full` com layout flexível.
+- **Calendar — prop `size` removida** — o tamanho e o arredondamento do trigger ("Pick a date") são responsabilidade do elemento trigger, não do `Calendar`. A story `InPopover` demonstra o padrão correto com `triggerSizeClasses` aplicado diretamente ao `<Button>` com `rounded-[var(--radius)]` para alinhar com o token do `Input`.
+- **Card stories** — enriquecidas com 3 novas variações: `WithAction` (uso de `CardAction` no header), `TeamMember` (grid de member cards com avatar e status), `SettingsCard` (lista de settings com `Separator` e `Badge`). Background `bg-muted` adicionado via decorator global da stories file para contraste com o fundo dos cards.
+- **Storybook — docs stories** — adicionado `render: (args) => <Component {...args} />` no nível do `meta` em todos os 60 arquivos de stories em `components/ui/`. Resolve o problema onde stories com apenas `args` (sem `render` explícito) mostravam a mesma variação repetida na aba Docs por dependerem do `projectAnnotations.render` implícito do framework React.
+- **Storybook — `preview.tsx`** — `min-h-screen` passou a ser condicional a `layout: 'fullscreen'`, resolvendo a altura excessiva dos exemplos na aba Docs.
+- **Template npm** — `templates/package.json` atualizado para `2.1.0` e dependência `xertica-ui` para `^2.1.0`.
+- **Template version badge** — o template passa a exibir um indicador visual discreto da versão do pacote `xertica-ui` usada pelo projeto.
+- **Documentação** — atualizados `calendar.md` (props `captionLayout`/`buttonVariant`, nota sobre `size` no trigger), `card.md` (`CardAction` na anatomia, exemplos WithAction/Stats/TeamMember/Settings), `chart.md` (nova seção Stacked Bar Chart), `architecture.md` (domínio `blocks/` com árvore de arquivos).
+
+### Fixed
+
+- **Chart — stacked bar radius** — em `DashboardBarChart` com `stacked`, apenas a série no topo de cada `stackId` recebe `radius={[4,4,0,0]}`; as demais recebem `radius={[0,0,0,0]}`. Elimina a borda arredondada no topo das barras intermediárias e inferiores da pilha.
+- **`FeatureCard` — badge overflow** — alterado de `flex items-center` para `flex flex-wrap` no container título+badge, garantindo que o badge quebre para a linha seguinte em vez de vazar fora do card quando o título ocupa toda a largura disponível.
+
+---
+
+## [2.0.6] — 2026-05-13
+
+### Added
+
+- **Contrato de independência dos componentes** — documentado que `xertica-ui/style.css` é a única importação global obrigatória e que componentes públicos devem funcionar isoladamente sempre que possível.
+- **`useOptionalLayout`** — nova API compatível para componentes reutilizáveis consumirem o layout com fallback seguro, mantendo `useLayout` como hook estrito para apps que querem falhar cedo.
+- **Smoke tests de API pública** — adicionada validação de import/render dos subpaths públicos (`ui`, `brand`, `layout`, `assistant`, `media` e `hooks`).
+- **Exports públicos de Maps** — `useMapLayers`, `GOOGLE_MAPS_ID` e `GOOGLE_MAPS_LIBRARIES` agora são expostos pelo subpath `xertica-ui/ui`.
+
+### Changed
+
+- **`XerticaProvider` completo** — passa a compor providers de theme, brand colors, language, layout, assistant, API keys, Google Maps, tooltip e toaster como wrapper de conveniência para apps consumidores.
+- **Componentes com contexto de layout** — `Header`, `Sidebar`, páginas e componentes de mídia foram ajustados para renderizar com fallback interno quando importados sem provider.
+- **Arquitetura FSD/FDA** — tipos compartilhados do assistant foram movidos para camada neutra, evitando dependência runtime de `components/shared` para implementação de feature.
+- **Documentação LLM e componentes** — README, docs de provider/mapa, `llms.txt`, `llms-compact.txt` e `docs/llms.md` foram alinhados ao contrato de independência e aos subpaths consumíveis.
+- **Storybook Docs de UI** — páginas MDX dos componentes de UI agora renderizam as variações reais das stories, evitando repetição do mesmo exemplo nos blocos de variação.
+- **Storybook Maps** — stories de mapa usam um frame responsivo mais largo para melhorar a visualização na aba Docs.
+
+### Fixed
+
+- **Guards de browser/SSR** — providers e componentes browser-only agora protegem acessos a `window`, `document`, `localStorage`, `navigator` e scripts externos.
+- **Google Maps sem configuração** — componentes relacionados a Maps renderizam estados de configuração/erro sem quebrar a aplicação consumidora.
+
+---
+
+## [2.0.5] — 2026-05-12
+
+### Added
+
+- **`llms-compact.txt`** — novo arquivo de referência compacto para LLMs, sintetizando todos os componentes em formato reduzido ideal para contextos de tokens limitados.
+- **`docs/decision-tree.md`** — guia de árvore de decisão para agentes de IA selecionarem o componente correto com base nos requisitos da UI.
+- **`templates/CLAUDE.md`** — `CLAUDE.md` agora é scaffolded automaticamente em projetos criados via `npx xertica-ui@latest init`, fornecendo contexto arquitetural (FSD/FDA, subpath imports, tokens semânticos) para Claude Code e outros assistentes de IA.
+- **Storybook stories** — adicionadas stories interativas para Accordion, AlertDialog, Button, Checkbox, Dialog, Input, Switch, Tabs, HomePage e TemplatePage.
+- **`components/pages/home-page/home-page.mdx`** e **`template-page.mdx`** — novas entradas de documentação MDX para as page components.
+
+### Changed
+
+- **`guidelines/Guidelines.md`** — reescrita completa do guia de arquitetura FSD/FDA: maior detalhamento de responsabilidades por camada, convenções de import e fluxo de adição de novas rotas.
+- **`components.json`** — atualização completa do registro de componentes, cobrindo todos os 97 componentes com metadados de subpath, props e variantes.
+- **`llms.txt`** — seção de subpath imports e mapeamento de camadas FSD/FDA atualizados.
+- **`vite.config.ts`** — ajustes no build multi-entry para garantir correta emissão dos arquivos CJS/ESM.
+
+### Fixed
+
+- **`npx xertica-ui init` usa versão em cache** — documentado que o npx armazena pacotes em cache localmente sem TTL curto. Sempre use `npx xertica-ui@latest init` para garantir a versão mais recente. O `templates/CLAUDE.md` scaffolded no projeto gerado inclui essa orientação.
+
+---
+
+## [2.0.3] — 2026-05-11
+
+### Added
+
+- **CLI `update` — atualização de projeto** — novo modo no comando `update` permite atualizar os arquivos do projeto (app shell, shared, features, pages) para qualquer versão publicada do `xertica-ui`, com seleção granular de quais partes atualizar e confirmação antes de sobrescrever.
+
+---
+
+## [2.0.2] — 2026-05-11
+
+### Fixed
+
+- **CLI rewritten for FSD/FDA structure** — `npx xertica-ui@latest init` agora copia corretamente a estrutura Feature-Sliced Design:
+  - Removida cópia de `src/app/routes.tsx` (arquivo não existe mais após refatoração)
+  - Adicionada cópia de `src/app/components/AppLayout.tsx`
+  - Adicionada cópia completa de `src/shared/` (`auth.ts`, `navigation.ts`, `types/auth.ts`)
+  - Adicionada cópia de `src/features/auth|home|template` conforme seleções do usuário
+  - Cópia de pages corrigida de `src/app/pages/` → `src/pages/`
+  - `AuthGuard.tsx` agora gerado dinamicamente com imports e rotas apenas das páginas selecionadas
+- **`generateDemoResponse` exportado via `xertica-ui/assistant`** — estava ausente do barrel causando `SyntaxError: does not provide an export named 'generateDemoResponse'`
+- **Build corrigido: UMD → CJS** — múltiplos entry points não são suportados com formato UMD no Vite; migrado para CJS (todos os `*.umd.js` → `*.cjs.js` no `package.json` exports)
+
+---
+
+## [2.0.0] — 2026-05-11
+
+### Added
+
+- **Subpath exports** — The package now exposes 6 granular entry points alongside the full root barrel:
+  - `xertica-ui/ui` — all UI primitives (Button, Card, Input, Table, Dialog, etc.)
+  - `xertica-ui/layout` — Sidebar and Header
+  - `xertica-ui/brand` — XerticaProvider, XerticaLogo, XerticaXLogo, XerticaOrbe, ThemeToggle, LanguageSelector
+  - `xertica-ui/assistant` — XerticaAssistant, MarkdownMessage, CodeBlock, FormattedDocument, ModernChatInput
+  - `xertica-ui/media` — VideoPlayer, AudioPlayer, FloatingMediaWrapper
+  - `xertica-ui/hooks` — useLayout, useTheme, useLanguage, useBrandColors, useAssistente, useApiKey
+  - Root `from 'xertica-ui'` remains fully supported for backward compatibility.
+- **`ImageWithFallback` added to `xertica-ui/ui`** — previously only in the root barrel; now accessible via the `/ui` subpath.
+- **Multi-entry Vite build** — `vite.config.ts` now uses `lib.entry` as an object (7 entry points). Output filenames follow `[entryName].[format].js` pattern.
+- **CLI template — FSD/FDA architecture** — The scaffolded template was restructured to follow Feature-Sliced Design + Feature-Driven Architecture:
+  - `src/app/` — BrowserRouter, XerticaProvider, AuthGuard (auth state + route definitions), AppLayout (Sidebar + children shell)
+  - `src/shared/` — `config/navigation.ts` (route registry), `lib/auth.ts` (localStorage helpers), `types/auth.ts` (User interface)
+  - `src/features/auth/ui/` — LoginContent, ForgotPasswordContent, VerifyEmailContent, ResetPasswordContent; with shared `AuthPageShell` and `SocialLoginButtons` DRY extractions
+  - `src/features/home/ui/` — HomeContent
+  - `src/features/template/ui/` — TemplateContent, FormTemplate
+  - `src/pages/` — thin page wrappers (LoginPage, HomePage, TemplatePage, ForgotPasswordPage, VerifyEmailPage, ResetPasswordPage)
+- **`templates/guidelines/Guidelines.md`** — new architecture guide documenting FSD/FDA layers, layer responsibilities, and "Adding New Routes" step-by-step.
+
+### Changed
+
+- **Template imports** — All template source files updated to use subpath imports (`xertica-ui/ui`, `xertica-ui/brand`, `xertica-ui/layout`, `xertica-ui/assistant`, `xertica-ui/hooks`) instead of the root barrel.
+- **`FormTemplate.tsx` rewritten** — Removed dependency on `@hookform/resolvers/zod`, `react-hook-form`, and `zod` (packages not included in the CLI template's `package.json`). Now uses plain React `useState` + inline validation with only `xertica-ui/ui` primitives.
+- **`tsconfig.build.json`** — `include` array updated to cover all new barrel source directories (`components/**/*`, `contexts/**/*`, `hooks/**/*`).
+- **Documentation** (`llms.txt`, `llms-full.txt`) — Added subpath import reference table and FSD/FDA layer mapping.
+
+### Fixed
+
+- **Stale compiled artifacts** — Removed `App.js`, `App.d.ts`, `main.js`, `main.d.ts` from `templates/src/app/` that were being resolved by Vite's extension priority (`.js` before `.tsx`), causing `Failed to fetch dynamically imported module` errors after the FSD restructure.
+
+---
+
+## [1.10.0] — 2026-05-08
+
+### Added
+
+- **Semantic Variants** — Added `success`, `info`, and `warning` variants to components that lacked them:
+  - **Button** — now supports 9 variants: `default`, `secondary`, `outline`, `ghost`, `destructive`, `link`, `success`, `info`, `warning`.
+  - **Progress** — new `variant` prop (`default`, `success`, `info`, `warning`, `destructive`) colors both the track and the indicator.
+  - **NotificationBadge** — added `secondary`, `outline`, `success`, `info`, `warning`; standardized `default` to primary color for consistency with Badge and Button.
+  - **TimelineDot** — added `info` and `outline` variants; replaced hardcoded `rgb()` values with semantic CSS tokens (`bg-success`, `bg-warning`).
+- **DialogBody** — new sub-component for the Dialog. When used, `DialogHeader` and `DialogFooter` stay pinned while `DialogBody` scrolls independently. Exported from `xertica-ui`.
+- **Dialog height management** — `DialogContent` now has `max-h-[calc(100dvh-2rem)] overflow-hidden`. The close button (×) is pinned and never scrolls with content. `size="full"` fills the full viewport height.
+- **Header `breadcrumbSlot`** — new prop accepting any `ReactNode` rendered immediately after the breadcrumb/title area (badges, buttons, status chips, etc.).
+- **Sidebar default variant groups** — `variant="default"` now renders `navigationGroups` with labeled group headers. Each `RouteConfig` supports a `children` field (sub-routes shown in a contextual `DropdownMenu` via a `ChevronRight` button at the end of the item).
+
+### Fixed
+
+- **Search double clear icon** — `type="search"` caused browsers to inject a native clear button on top of the custom × icon. Changed to `type="text"`.
+- **CSS `@source` path** — CLI template `src/styles/index.css` had `../node_modules/xertica-ui` (one level short); corrected to `../../node_modules/xertica-ui/components`.
+- **`theme-map.css` incomplete** — `--color-success`, `--color-info`, `--color-warning` and their `foreground` variants were missing, preventing `bg-success`, `text-info`, etc. from being generated in the compiled library CSS.
+
+### Changed
+
+- **Storybook argTypes** — Multiple components had controls missing from the Storybook panel: Badge (`success`/`info`/`warning` options), Select (`size`), Avatar (`size`), Rating (`readonly` casing), Timeline (`dotVariant`), Dialog (`size` available in all stories). All corrected.
+- **LLM documentation** (`llms-full.txt`) — Updated Badge, Button, Dialog, Header, NotificationBadge, Progress, Search, Sidebar, and Timeline sections to reflect current APIs.
+
+---
+
+## [1.9.0] — 2026-05-05
+
+### Added
+
+- **Standardized Form Sizing System** — Implemented a unified `size` prop (`sm`, `md`, `lg`) across all form-related components for perfect visual alignment in grid layouts:
+  - **Text Components** — `Input`, `SelectTrigger`, `Textarea`, `Search`, and `InputOTPSlot` now share consistent height/padding/font-size tokens.
+  - **Toggle Components** — `Checkbox`, `RadioGroupItem`, and `Switch` now feature dynamic sizing for both containers and internal indicators (check icon, dot, thumb).
+  - **Labels** — `Label` component now supports `size` to match the text size of the associated input.
+  - **Reference Guide** — Added `docs/form-sizing.md` as a comprehensive guide for the standardized sizing scale.
+- **Assistant Individual Controls** — Added granular control props to `XerticaAssistant` to toggle specific features independently:
+  - `showHistory`, `showFavorites`, `allowAudioInput`, `allowFileUpload`, `allowDocCreation`, `allowPodcastGen`, `allowResearchGen`.
+- **Header Breadcrumb Navigation** — Standardized `Header` to use breadcrumbs as the default navigation pattern:
+  - Added support for `react-router-dom` links in breadcrumbs to prevent page reloads.
+  - Configurable hierarchy levels and labels directly via props.
+
+### Changed
+
+- **Form Component Architecture** — Migrated form elements from legacy tokens to standardized design system tokens (`bg-background`, `border-border`) for better theme consistency.
+- **Documentation & Storybook** — Updated all 9 affected form components with new "Sizes" sections in Storybook (Stories + MDX) and enriched LLM-facing markdown documentation.
+- **Unit Testing** — Updated test suites for `Checkbox`, `RadioGroup`, `Switch`, `InputOTP`, `Label`, `Search`, `Select`, and `Textarea` to verify sizing variant classes.
+
+### Fixed
+
+- **Search Component** — Removed obsolete `loading` prop which was causing TypeScript errors and was redundant with the current design system patterns.
+- **SelectTrigger Sizing** — Standardized `md` height to `h-10` (40px) to match the rest of the form system.
+
+---
+
+## [1.8.0] — 2026-04-27
+
+### Added
+
+- **VideoPlayer UI Enhancements** — Added gradient overlay on controls for improved contrast against video content:
+  - Gradient: `from-black/60 via-black/30 to-transparent` with `pt-12` spacing
+  - White progress bar with `bg-white/30` track, `bg-white` fill, and `rounded-r-sm` on filled portion
+  - White icons with `drop-shadow-md` for visibility
+  - Buttons use `text-white hover:text-white hover:bg-black/50` for proper hover states
+- **Slider Visual Fixes** — Improved progress bar alignment:
+  - Added left margin `ml-2` to track for thumb alignment
+  - Added `rounded-r-sm` to Range for filled portion
+  - Adjusted track/margins for proper visual alignment at full value
+
+### Changed
+
+- **Documentation** — Updated component counts across all docs:
+  - `llms.txt`: 75 → 97 components
+  - `llms-full.txt`: Added statistics table
+  - `docs/llms.md`: Added statistics section
+  - `Introduction.mdx`: Added "97 Components" badge
+- **components.json** — 75 → 89 components (added missing Media, Assistant, Pages, and Map components)
+
+### Fixed
+
+- **Slider Progress Bar** — Fixed visual gap where thumb doesn't align with filled bar at end position by adjusting track margins
+
+---
+
+## [1.7.0] — 2026-04-23
+
+### Fixed
+
+- **CLI CSS Theme Import** — Corrected `@theme` → `@theme inline` in both the library's `index.css` and the generated template `src/styles/index.css`. Plain `@theme {}` was causing Tailwind v4 to resolve color tokens statically at build time using the library's defaults, preventing consumer `tokens.css` overrides from propagating into utility classes (`bg-destructive`, `bg-primary`, alert colors, etc.).
+- **Dark Mode `--primary`** — Added missing `--primary: var(--xertica-primary)` in the dark mode block of `tokens.css` (library, template, and generator). Components using `bg-primary` were not picking up the dark mode brand color.
+- **Dark Mode Chart Tokens** — Generator (`bin/generate-tokens.ts`) now includes `--chart-1` through `--chart-5` in the dark mode section for all generated `tokens.css` files.
+
+### Added
+
+- **CLI `update` command** — `npx xertica-ui@latest update` prompts the user to select a new color theme and overwrites `src/styles/xertica/tokens.css` with the newly generated tokens, preserving all other project files.
+- **Template `@theme inline` mapping** — Generated `src/styles/index.css` now includes a complete `@theme inline {}` block mapping all tokens (sidebar, charts, gradients, brand, radii) to CSS variable aliases, ensuring full theme coverage for consumer projects.
+- **Documentation** — `docs/getting-started.md` updated with CLI `update` command reference and a new "CSS Setup (Critical)" section explaining the `@theme inline` requirement.
+
+---
+
+## [1.6.0] — 2026-04-20
+
+### Added
+
+- **`docs/llms.md`** — Master LLM/AI-agent entrypoint index with full component catalog, token quick reference, and reading order guide.
+- **`docs/layout.md`** — Complete `LayoutContext` and `useLayout()` API reference.
+- **`docs/components/route-map.md`** — New documentation for `RouteMap` component.
+- **`docs/components/use-mobile.md`** — New documentation for `useMobile` / `useIsMobile` hooks.
+- **`Header`** — New props: `user` (profile with avatar, name, email, and dropdown menu items), `actions` (custom icon action buttons), `showSettings` / `onSettingsClick`, `showLogout` / `onLogoutClick`. Fixed render order: Language → Theme → Actions → Settings → User → Logout.
+- **`Sidebar`** — New `width` prop (`expandedWidth: number`) for configuring the expanded sidebar pixel width. Width is now read and stored via `LayoutContext.sidebarWidth`.
+
+### Changed
+
+- **Documentation** — All 61 component docs, 5 pattern docs, and 6 root docs fully rewritten in English with standardized structure (Overview, When to Use, Anatomy, Props table, Examples, AI Rules, Related Components).
+- **JSDoc** — All Portuguese JSDoc comments in `components/ui/` translated to English and enriched with accurate `@ai-rules`.
+- **`README.md`** — Complete rewrite in English, restructured for npm page quality (quick start, install guide, component catalog, token reference, AI agent entrypoint, troubleshooting).
+- **`package.json`** — Version bumped to `1.6.0`. Description translated to English.
+
+### Fixed
+
+- **`docs/components/page-header.md`** — Was documenting a wrong API (`title/description/actions`). Now correctly documents the real API: `breadcrumbs[]`, `showLanguageSelector`, `rightContent`, `PageHeaderHeading`, `PageHeaderDescription`.
+- **`docs/components/stepper.md`** — Was documenting a `steps[]` array prop. Now correctly documents the composable `<Stepper currentStep> + <Step step label>` API (1-indexed).
+- **`docs/components/empty.md`** — Was documenting single-prop component. Now correctly documents the composable sub-component pattern: `Empty > EmptyIcon > EmptyTitle > EmptyDescription > EmptyAction`.
+- **`docs/components/stats-card.md`** — `trend` was documented as a string. Now correctly documented as `{ value: number; label?: string }`.
+- **`docs/components/chart.md`** — Was documenting raw Recharts usage. Now correctly documents the `ChartContainer + ChartConfig + var(--color-*)` pattern.
+
+---
+
+## [1.5.2] — 2026-04-15
+
+### Fixed
+
+- Resolved regression where modal components (Dialog/AlertDialog) failed to render in projects initialized via the CLI.
+- Implemented robust CSS integration using Tailwind v4 theme mappings.
+- Ensured Radix UI portals correctly inherit theme variables.
+
+---
+
+## [1.5.1] — 2026-04-14
+
+### Changed
+
+- Sidebar: Added `assistente` variant with fixed areas, searchable navigation, and grouped navigation structures.
+- Template page updated to demonstrate the assistant sidebar variant.
+
+---
+
+## [1.5.0] — 2026-04-13
+
+### Added
+
+- `Sidebar` — `width` / `expandedWidth` prop for configurable expanded sidebar width.
+- `LayoutContext` — `sidebarWidth` and `setSidebarWidth` for global sidebar width management.
+- `Header` — User profile section with avatar, dropdown menu, settings button, and logout button.
+- `StatsCard` — KPI metric card component.
+- `Timeline` — Chronological event list with dot variants.
+- `TreeView` — Hierarchical tree navigation.
+- `Rating` — Star-based rating input.
+- `FileUpload` — Drag-and-drop file input.
+- `Search` — Pre-built search input with icon and clear button.
+- `NotificationBadge` — Dot/count badge overlay.
+- `RouteMap` — Google Maps route display and direction calculation.
+- `Stepper` — Multi-step progress indicator.
+- `Map` — Advanced Google Maps integration with markers, circles, polygons, and layers.
+- `XerticaAssistant` — Embedded Gemini AI assistant panel.