xertica-ui 2.4.0 → 2.5.0

package/CHANGELOG.md

@@ -1,564 +1,621 @@
-# 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).
-
----
-
-## [Unreleased]
-
----
-
-## [2.4.0] — 2026-06-16
-
-### Added
-
-- **CLI — Ativação/Desativação de Dark Mode** — nova funcionalidade no CLI para ativar ou desativar o dark mode ao criar (`init`) ou atualizar (`update`) o projeto. A escolha do usuário é armazenada em `.xertica.json` na raiz e gera `disableDarkMode={true}` dentro do `<XerticaProvider>` em `App.tsx`. O botão `ThemeToggle` e a aba de switch de temas nas configurações ocultam-se automaticamente caso o dark mode esteja desativado.
-
-### Fixed
-
-- **Layout — Correção do scroll vertical** — ajustado o comportamento do scroll vertical para travar o viewport com `h-screen overflow-hidden` em `App.tsx` e `AuthGuard.tsx`, bem como `height: 100%; overflow: hidden` no `html, body` em `index.css` e `base.css`. Páginas de autenticação (como login, recuperação de senha, etc.) agora possuem rolagem interna (`h-full overflow-y-auto`), impedindo que o scroll global suba/desloque o cabeçalho (`Header`) e o assistente virtual.
-
----
-
-## [2.3.0] — 2026-06-15
-
-### Added
-
-- **CLI — Suporte a AI Assistant no `init`** — novo prompt `Include AI Assistant?` (confirm, default: true). Quando desativado, os arquivos `src/features/assistant/`, `src/pages/AssistantPage.tsx` e a rota `/assistente` são omitidos inteiramente. A escolha é persistida em `.xertica.json` na raiz do projeto gerado.
-- **CLI — `update` → Assistant** — nova opção no menu de update para adicionar ou remover o AI Assistant de um projeto existente. Detecta o estado atual via `.xertica.json` (com fallback por presença de arquivos). Ao adicionar: copia `features/assistant/` e `AssistantPage.tsx`. Ao remover: deleta esses arquivos. Em ambos os casos regenera `AuthGuard.tsx`, `HomePage.tsx` e `TemplatePage.tsx` para refletir o novo estado.
-- **CLI — `.xertica.json`** — novo arquivo de configuração persistido na raiz do projeto gerado. Armazena flags de features (`hasAssistant`) para que o `update` possa ler o estado atual sem inferir pelos arquivos.
-- **CLI — `cli:dev` e `cli:run`** — novos scripts em `package.json` para desenvolvimento e teste local do CLI sem publicar no npm. `cli:dev` compila em modo watch; `cli:run` executa `dist/cli.js` diretamente.
-- **CLI — Versão no banner** — `init` e `update` exibem a versão atual na linha de abertura (`v2.3.0`).
-- **Geradores de página com/sem assistente** — `generateHomePage(hasAssistant)` e `generateTemplatePage(hasAssistant)` geram versões das páginas sem dependências do assistente quando ele não está incluído, prevenindo erros de import.
-- **Design system — Token `--mobile-content-padding`** — novo token CSS em `tokens.css` (`1.25rem`) que controla o padding horizontal do conteúdo em telas mobile. Também mapeado no `theme-map.css` como `--spacing-mobile-content-padding`. A variante `@custom-variant mobile` foi adicionada em `base.css`.
-- **i18n — `assistant.page.*` nos locales da lib** — as 12 chaves da seção `assistant.page` (`today`, `yesterday`, `thisWeek`, `searchConversations`, `rename`, `delete`, `cancel`, `save`, `deleteConversationTitle`, `deleteConversationDesc`, `renameConversationTitle`, `conversationNameLabel`) foram adicionadas aos locales internos da lib (`locales/pt-BR|en|es/components/assistant.json`). Anteriormente só existiam nos locales dos templates, causando chaves brutas na `AssistantPage`.
-
-### Fixed
-
-- **Build — esbuild 0.28 + Tailwind v4 target incompatibility** — `vite.config.ts` agora define `build.target: 'esnext'` e `optimizeDeps.esbuildOptions.target: 'esnext'`, eliminando os 1205 erros `Transforming destructuring to the configured target environment is not supported yet` causados pelo esbuild 0.28 ao tentar fazer downcompile de ES2020+.
-- **CLI — Remoção do assistente não detectava estado atual** — quando `.xertica.json` não existia (projeto gerado antes desta versão), `currentlyHas` era sempre `false` mesmo com os arquivos do assistente presentes. Agora há fallback por presença de `src/features/assistant/` e `src/pages/AssistantPage.tsx`.
-- **CLI — Imports quebrados após remoção do assistente** — `HomePage.tsx` e `TemplatePage.tsx` importavam `../features/assistant` diretamente. Após remoção, esses imports ficavam quebrados. Resolvido: essas páginas agora são geradas dinamicamente pelo CLI (com/sem imports do assistente) em vez de copiadas estaticamente.
-- **i18n — Chaves `assistant.page.*` apareciam como texto bruto** — o bundle compilado da lib não incluía a seção `page` nos locales do assistente. Como a lib inicializa o i18next com seus próprios recursos antes do projeto consumidor, as chaves não eram encontradas.
-
-### Changed
-
-- **Padding mobile global** — os containers de conteúdo (`HomeContent`, `TemplateContent`) em `components/pages/` e `templates/src/features/` mudaram de `p-2` para `p-5` em mobile (equivalente a `1.25rem`, alinhado ao token `--mobile-content-padding`). Em `sm:` e `md:` o comportamento permanece inalterado (`p-4` e `p-6` respectivamente).
-- **CLI — `update` → Project files → pages** — ao atualizar páginas, `HomePage.tsx` e `TemplatePage.tsx` agora são regeneradas dinamicamente respeitando o estado atual do assistente (lido de `.xertica.json` ou inferido pela presença de `AssistantPage.tsx`), em vez de sobrescritas com a cópia estática do template.
-
----
-
-## [2.2.1] — 2026-05-21
-
-### Added
-
-- **i18n — Cobertura completa na página de Template** — `TemplateContent.tsx` e os 4 starter templates (`LoginTemplate`, `FormTemplate`, `DashboardTemplate`, `CrudTemplate`) estão 100% traduzidos (pt-BR, en, es). Anteriormente a maioria dos textos era hard-coded em PT-BR.
-- **i18n — Namespace `templates.*` completo** — novo namespace com 539 chaves cobrindo todos os textos visíveis: seções, alertas, abas, formulários, tabela de dados, configurações, botões (variantes/tamanhos), badges, dialogs, sidebar, componentes avançados (Pagination, Stepper, TreeView, RichTextEditor) e rodapé. Suporte completo para `<Trans>` com interpolação de `<code>` nas descrições técnicas.
-- **i18n — Novos namespaces de starter templates** — 4 novos arquivos de locale por idioma: `loginTemplate`, `formTemplate`, `dashboardTemplate`, `crudTemplate` (total de 12 novos JSONs × 2 mirrors = 24 arquivos).
-- **i18n — Estrutura de locales reorganizada** — os monolitos `locales/<lang>.json` foram divididos em pastas por categoria:
-  - `locales/<lang>/{common,nav,errors,languageSelector,themeToggle}.json` (transversal)
-  - `locales/<lang>/pages/{home,templates,login,resetPassword,verifyEmail,loginTemplate,formTemplate,dashboardTemplate,crudTemplate}.json`
-  - `locales/<lang>/components/{assistant,sidebar,media,projectCard,profileCard,notificationCard,activityCard,stats,team}.json`
-- **i18n — Loader via `import.meta.glob`** — `i18n.ts` (base e templates) substituiu os 57 imports estáticos por 3 chamadas `import.meta.glob('./locales/<lang>/**/*.json', { eager: true })` + função `bundleLang()`. Adicionar um novo arquivo JSON é suficiente — sem tocar no `i18n.ts`.
-- **CLI — Locale em pastas** — `syncLocaleFiles` e `generateI18nFile` em `bin/language-config.ts` atualizados para copiar/gerar a nova estrutura de pastas. Projetos legados com `<lang>.json` flat são migrados automaticamente no próximo `update`.
-- **`templates/vite.config.ts` — aliases de monorepo** — aliases automáticos detectam se o `vite.config.ts` está dentro do monorepo (`../components/index.ts` existe) e apontam `xertica-ui/*` diretamente para o source TypeScript, permitindo HMR sem rebuild da lib. Em projetos gerados pelo CLI, o check retorna `false` e `xertica-ui` resolve do `node_modules` normalmente.
-- **CLI — Language selection on `init`** — `npx xertica-ui init` now prompts for the languages the project should support (multi-select with `pt-BR`, `en`, `es`; all selected by default; minimum 1). The CLI:
-  - Copies **only** the locale folders for the selected languages into `src/locales/` (no orphan locales)
-  - Generates `src/i18n.ts` with `import.meta.glob` calls for exactly those languages
-  - Injects the `availableLanguages` prop into the generated `src/app/App.tsx`
-  - Persists the selection in `src/locales/.languages.json` (schema v1)
-- **CLI — `update` → Languages** — new option in the `update` command lets users add or remove languages later. Shows a diff (`+ es`, `- en`) before confirming. Regenerates `App.tsx`, `i18n.ts`, copies new locale folders, and prunes removed ones.
-- **CLI — Monolingual auto-detection** — when only one language is selected, the generated `App.tsx` includes a banner comment documenting that the `LanguageSelector` will auto-hide.
-- **`bin/language-config.ts`** — new module encapsulating the supported-language registry (`SUPPORTED_LANGUAGES`), code generators (`generateI18nFile`, `generateAppTsx`), and persistence helpers (`readLanguagesConfig`, `writeLanguagesConfig`, `syncLocaleFiles`).
-
-### Fixed
-
-- **Dark mode toggle no CLI** — `XerticaProvider` no `templates/src/app/App.tsx` era gerado com `disableDarkMode` hard-coded, tornando o `ThemeToggle` um no-op. Removido de `App.tsx`, do template literal do CLI em `bin/language-config.ts` e do exemplo em `templates/CLAUDE.md`.
-
-### Changed
-
-- **CLI — `update` → Project files (`app` branch)** — instead of blindly overwriting `App.tsx` and `i18n.ts` with the static template (which would erase the user's language selection), the update flow now reads the persisted selection from `src/locales/.languages.json` and regenerates these files honoring it. Projects scaffolded before this feature shipped get their selection inferred from the locale files present and the inferred config is written back.
-- **`DashboardTemplate`** — `StatsCard` deixou de chamar `useTranslation()` internamente; o sufixo de tendência (`lastMonth`) é resolvido no pai e passado como prop, reduzindo o número de subscribers i18n de 5 para 1.
-- **`TemplateContent` — dialog inputs controlados** — os `Input` do dialog "Editar Perfil" foram convertidos de `defaultValue` (uncontrolled) para `value`/`onChange` com lazy `useState`, garantindo que o valor reflita o idioma ativo no momento da montagem sem sobrescrever edições do usuário.
-- **`TemplateContent` — `treeData` movido para dentro do componente** — os labels dos nós do TreeView (`Components`, `UI`, `Button`…) agora reagem ao switch de idioma em tempo real, pois `treeData` é construído após `const { t } = useTranslation()`.
-
----
-
-## [2.1.11] — 2026-05-20
-
-### Fixed
-
-- **CLI Initialization** — Correções essenciais no comando `init`:
-  - `i18n.ts` e o diretório `locales/` agora são copiados corretamente, restaurando as traduções na aplicação gerada.
-  - `AuthContext.tsx` e dependências agora são incluídas, habilitando o hook `useAuth`.
-  - A geração do `AuthGuard.tsx` foi reconstruída de forma dinâmica para consumir corretamente o `useAuth()` e garantir integridade das rotas protegidas e abertas, suportando _lazy loading_ dinâmico das rotas de acordo com a seleção do usuário.
-  - O diretório `features/assistant/` agora é sempre copiado visto que o `AppLayout` depende nativamente da `AssistantPage`.
-- **Template Lints** — Resolução de diversos `unused-vars` (variáveis e imports órfãos) espalhados pelo `HomeContent.tsx`, `TemplateContent.tsx`, `AssistantPage.tsx` e `AuthContext.tsx`, garantindo que o `npm run check` (`tsc` + `eslint`) execute com 100% de sucesso imediatamente após a geração do projeto.
-- **`LanguageSelector` e `LanguageContext`** — Correção de bugs na seleção de idiomas e fallback:
-  - `LanguageContext.tsx` agora valida de forma robusta e intercepta valores legados como `'PT'` no `localStorage`, realizando um _fallback_ seguro para `'pt-BR'`.
-  - O componente `LanguageSelector.tsx` foi ajustado na sua composição com Radix UI: a dependência restritiva do `<SelectValue>` foi removida no trigger, evitando a sobrescrita do conteúdo. Agora o componente exibe a variante `minimal` (como `PT`, `EN`, `ES`) perfeitamente, sincronizada com o estado global de tradução.
-
----
-
-## [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.
+# 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).
+
+---
+
+## [Unreleased]
+
+---
+
+## [2.5.0] — 2026-06-22
+
+### Added
+
+- **Sidebar — Subitens inline no mobile** — em viewports mobile (< 768 px) os itens com `children` agora expandem/colapsam de forma inline (accordion) abaixo do item pai, em vez de abrir um `DropdownMenu` lateral que ficava invisível fora dos limites do container. O botão `ChevronRight` rotaciona 90° ao abrir e os filhos surgem com animação via Framer Motion. No desktop o comportamento de dropdown lateral permanece inalterado.
+
+- **Storybook — Stories de sidebar com subitens (desktop e mobile)** — adicionadas duas novas stories na documentação da `Sidebar`:
+  - `WithSubitemsDesktop` — sidebar iniciada expandida mostrando o botão `ChevronRight` nos itens com filhos e o dropdown lateral ao clicar.
+  - `WithSubitemsMobile` — simula um viewport de 375 px com header de app mobile (botão hambúrguer). Ao abrir, a sidebar cobre a tela inteira e os subitens expandem inline, permitindo inspeção e ajuste do visual mobile.
+
+- **Tema de cores — Dark mode tingido por hue** — todos os tokens de superfície do dark mode (`--background`, `--card`, `--popover`, `--muted`, `--secondary`, `--accent`, `--border`, `--input`) agora são tingidos com a hue da cor primária do tema ativo, em vez de cinza-zinc neutro para todos os temas:
+  - **primary / xertica-original**: fundo `#05050d` (azul-índigo muito sutil)
+  - **blue**: fundo `#03050f` (azul marinho profundo)
+  - **violet**: fundo `#07040f` (violeta escuro)
+  - **rose**: fundo `#0f0305` (rosa/vermelho escuro)
+  - **emerald**: fundo `#030f08` (verde escuro)
+  - **amber**: fundo `#0f0a03` (âmbar escuro)
+  - **orange**: fundo `#0f0703` (laranja escuro)
+  - **zinc / slate**: mantêm o azul-índigo sutil (alinhado com o tema default)
+
+- **`BrandColorsContext` — novos campos `darkBackground`, `darkCard`, `darkMuted`, `darkBorder`** — a interface `BrandColors` em `contexts/theme-data.ts` ganhou 4 novos campos que definem as cores de superfície específicas de cada tema no dark mode. Todos os 9 temas foram atualizados com valores correspondentes.
+
+- **`XerticaProvider` — nova prop `defaultColorTheme`** — aceita o ID de um `ColorTheme` (ex: `'blue'`, `'rose'`, `'emerald'`) para selecionar o tema de cor completo via props, sem a limitação de passar apenas um hex isolado via `primaryColor`.
+
+- **Storybook — troca de temas de cor funcional** — o toolbar `Brand Color` agora troca o tema completo (primary, sidebar, charts **e** superfícies dark) com total fidelidade. Os valores do toolbar foram migrados de hex brutos para IDs de tema (`xertica-original`, `blue`, `violet`, etc.).
+
+### Fixed
+
+- **`BrandColorsContext` — tokens de superfície dark não refletiam no Storybook** — o `applyColors()` injetava o style tag com `document.head.prepend()`, colocando-o antes de todos os outros estilos. Como os tokens de cor do `tokens.css` apareciam depois (e com seletores de maior especificidade como `:root[data-mode='dark']`), sobrescreviam os valores injetados. Corrigido com três ajustes:
+  1. `prepend` → `appendChild` para que o style injetado sempre apareça por último no `<head>` e vença na cascata de mesma especificidade.
+  2. Os tokens de primary/sidebar/charts/semantic passaram a ser aplicados via `root.style.setProperty()` (inline style no `<html>`), que tem especificidade máxima e sempre vence qualquer regra de stylesheet.
+  3. O bloco dark de superfícies usa o seletor `:root[data-mode='dark'], .dark` para igualar a especificidade do `tokens.css` e ser decidido pela ordem de aparição.
+
+- **`TemplatePage.stories.tsx` — erro ao renderizar no Storybook** — o componente `TemplatePage` usa `useAuth()` internamente, mas o decorator das stories não incluía `AuthProvider`. Ao carregar a página de documentação, o hook lançava `"useAuth must be used within <AuthProvider>"`. Corrigido adicionando `AuthProvider` dentro do `MemoryRouter` no decorator.
+
+- **Sidebar — `isMobileViewport` não consumido em `SidebarNav`** — o valor já existia no `SidebarContext` mas não era lido pelo `SidebarNav`, impedindo a bifurcação entre accordion (mobile) e dropdown (desktop).
+
+### Changed
+
+- **`BrandColorsContext.applyColors` — estratégia de injeção de CSS** — tokens de primary aplicados via inline style (máxima prioridade); tokens de superfície dark injetados via `<style>` tag no final do `<head>`.
+
+- **Storybook `preview.tsx` — toolbar `brandColor`** — os itens do toolbar passaram de hex brutos para IDs de tema; o decorator usa `defaultColorTheme` em vez de `primaryColor` no `XerticaProvider`.
+
+- **`bin/generate-tokens.ts`** — o bloco dark mode agora usa `colors.darkBackground`, `colors.darkCard`, `colors.darkMuted` e `colors.darkBorder` em vez de valores zinc hardcoded, gerando CSS correto para todos os temas.
+
+- **Três arquivos `tokens.css`** (`styles/xertica/`, `src/styles/xertica/`, `templates/src/styles/xertica/`) — atualizados com os valores dark tingidos para o tema xertica-original (azul-índigo).
+
+---
+
+## [2.4.1] — 2026-06-17
+
+### Changed
+
+- **StatsCard — Cores de ícone customizáveis** — Adicionadas as propriedades `iconColor` e `iconBg` ao `StatsCard`, permitindo customizar a cor do ícone e o fundo do ícone (que anteriormente eram fixos em `text-muted-foreground` e `bg-muted`). Documentação e histórias do Storybook foram atualizadas correspondendo a essas propriedades.
+
+---
+
+## [2.4.0] — 2026-06-16
+
+### Added
+
+- **CLI — Ativação/Desativação de Dark Mode** — nova funcionalidade no CLI para ativar ou desativar o dark mode ao criar (`init`) ou atualizar (`update`) o projeto. A escolha do usuário é armazenada em `.xertica.json` na raiz e gera `disableDarkMode={true}` dentro do `<XerticaProvider>` em `App.tsx`. O botão `ThemeToggle` e a aba de switch de temas nas configurações ocultam-se automaticamente caso o dark mode esteja desativado.
+
+### Fixed
+
+- **Layout — Correção do scroll vertical** — ajustado o comportamento do scroll vertical para travar o viewport com `h-screen overflow-hidden` em `App.tsx` e `AuthGuard.tsx`, bem como `height: 100%; overflow: hidden` no `html, body` em `index.css` e `base.css`. Páginas de autenticação (como login, recuperação de senha, etc.) agora possuem rolagem interna (`h-full overflow-y-auto`), impedindo que o scroll global suba/desloque o cabeçalho (`Header`) e o assistente virtual.
+
+---
+
+## [2.3.0] — 2026-06-15
+
+### Added
+
+- **CLI — Suporte a AI Assistant no `init`** — novo prompt `Include AI Assistant?` (confirm, default: true). Quando desativado, os arquivos `src/features/assistant/`, `src/pages/AssistantPage.tsx` e a rota `/assistente` são omitidos inteiramente. A escolha é persistida em `.xertica.json` na raiz do projeto gerado.
+- **CLI — `update` → Assistant** — nova opção no menu de update para adicionar ou remover o AI Assistant de um projeto existente. Detecta o estado atual via `.xertica.json` (com fallback por presença de arquivos). Ao adicionar: copia `features/assistant/` e `AssistantPage.tsx`. Ao remover: deleta esses arquivos. Em ambos os casos regenera `AuthGuard.tsx`, `HomePage.tsx` e `TemplatePage.tsx` para refletir o novo estado.
+- **CLI — `.xertica.json`** — novo arquivo de configuração persistido na raiz do projeto gerado. Armazena flags de features (`hasAssistant`) para que o `update` possa ler o estado atual sem inferir pelos arquivos.
+- **CLI — `cli:dev` e `cli:run`** — novos scripts em `package.json` para desenvolvimento e teste local do CLI sem publicar no npm. `cli:dev` compila em modo watch; `cli:run` executa `dist/cli.js` diretamente.
+- **CLI — Versão no banner** — `init` e `update` exibem a versão atual na linha de abertura (`v2.3.0`).
+- **Geradores de página com/sem assistente** — `generateHomePage(hasAssistant)` e `generateTemplatePage(hasAssistant)` geram versões das páginas sem dependências do assistente quando ele não está incluído, prevenindo erros de import.
+- **Design system — Token `--mobile-content-padding`** — novo token CSS em `tokens.css` (`1.25rem`) que controla o padding horizontal do conteúdo em telas mobile. Também mapeado no `theme-map.css` como `--spacing-mobile-content-padding`. A variante `@custom-variant mobile` foi adicionada em `base.css`.
+- **i18n — `assistant.page.*` nos locales da lib** — as 12 chaves da seção `assistant.page` (`today`, `yesterday`, `thisWeek`, `searchConversations`, `rename`, `delete`, `cancel`, `save`, `deleteConversationTitle`, `deleteConversationDesc`, `renameConversationTitle`, `conversationNameLabel`) foram adicionadas aos locales internos da lib (`locales/pt-BR|en|es/components/assistant.json`). Anteriormente só existiam nos locales dos templates, causando chaves brutas na `AssistantPage`.
+
+### Fixed
+
+- **Build — esbuild 0.28 + Tailwind v4 target incompatibility** — `vite.config.ts` agora define `build.target: 'esnext'` e `optimizeDeps.esbuildOptions.target: 'esnext'`, eliminando os 1205 erros `Transforming destructuring to the configured target environment is not supported yet` causados pelo esbuild 0.28 ao tentar fazer downcompile de ES2020+.
+- **CLI — Remoção do assistente não detectava estado atual** — quando `.xertica.json` não existia (projeto gerado antes desta versão), `currentlyHas` era sempre `false` mesmo com os arquivos do assistente presentes. Agora há fallback por presença de `src/features/assistant/` e `src/pages/AssistantPage.tsx`.
+- **CLI — Imports quebrados após remoção do assistente** — `HomePage.tsx` e `TemplatePage.tsx` importavam `../features/assistant` diretamente. Após remoção, esses imports ficavam quebrados. Resolvido: essas páginas agora são geradas dinamicamente pelo CLI (com/sem imports do assistente) em vez de copiadas estaticamente.
+- **i18n — Chaves `assistant.page.*` apareciam como texto bruto** — o bundle compilado da lib não incluía a seção `page` nos locales do assistente. Como a lib inicializa o i18next com seus próprios recursos antes do projeto consumidor, as chaves não eram encontradas.
+
+### Changed
+
+- **Padding mobile global** — os containers de conteúdo (`HomeContent`, `TemplateContent`) em `components/pages/` e `templates/src/features/` mudaram de `p-2` para `p-5` em mobile (equivalente a `1.25rem`, alinhado ao token `--mobile-content-padding`). Em `sm:` e `md:` o comportamento permanece inalterado (`p-4` e `p-6` respectivamente).
+- **CLI — `update` → Project files → pages** — ao atualizar páginas, `HomePage.tsx` e `TemplatePage.tsx` agora são regeneradas dinamicamente respeitando o estado atual do assistente (lido de `.xertica.json` ou inferido pela presença de `AssistantPage.tsx`), em vez de sobrescritas com a cópia estática do template.
+
+---
+
+## [2.2.1] — 2026-05-21
+
+### Added
+
+- **i18n — Cobertura completa na página de Template** — `TemplateContent.tsx` e os 4 starter templates (`LoginTemplate`, `FormTemplate`, `DashboardTemplate`, `CrudTemplate`) estão 100% traduzidos (pt-BR, en, es). Anteriormente a maioria dos textos era hard-coded em PT-BR.
+- **i18n — Namespace `templates.*` completo** — novo namespace com 539 chaves cobrindo todos os textos visíveis: seções, alertas, abas, formulários, tabela de dados, configurações, botões (variantes/tamanhos), badges, dialogs, sidebar, componentes avançados (Pagination, Stepper, TreeView, RichTextEditor) e rodapé. Suporte completo para `<Trans>` com interpolação de `<code>` nas descrições técnicas.
+- **i18n — Novos namespaces de starter templates** — 4 novos arquivos de locale por idioma: `loginTemplate`, `formTemplate`, `dashboardTemplate`, `crudTemplate` (total de 12 novos JSONs × 2 mirrors = 24 arquivos).
+- **i18n — Estrutura de locales reorganizada** — os monolitos `locales/<lang>.json` foram divididos em pastas por categoria:
+  - `locales/<lang>/{common,nav,errors,languageSelector,themeToggle}.json` (transversal)
+  - `locales/<lang>/pages/{home,templates,login,resetPassword,verifyEmail,loginTemplate,formTemplate,dashboardTemplate,crudTemplate}.json`
+  - `locales/<lang>/components/{assistant,sidebar,media,projectCard,profileCard,notificationCard,activityCard,stats,team}.json`
+- **i18n — Loader via `import.meta.glob`** — `i18n.ts` (base e templates) substituiu os 57 imports estáticos por 3 chamadas `import.meta.glob('./locales/<lang>/**/*.json', { eager: true })` + função `bundleLang()`. Adicionar um novo arquivo JSON é suficiente — sem tocar no `i18n.ts`.
+- **CLI — Locale em pastas** — `syncLocaleFiles` e `generateI18nFile` em `bin/language-config.ts` atualizados para copiar/gerar a nova estrutura de pastas. Projetos legados com `<lang>.json` flat são migrados automaticamente no próximo `update`.
+- **`templates/vite.config.ts` — aliases de monorepo** — aliases automáticos detectam se o `vite.config.ts` está dentro do monorepo (`../components/index.ts` existe) e apontam `xertica-ui/*` diretamente para o source TypeScript, permitindo HMR sem rebuild da lib. Em projetos gerados pelo CLI, o check retorna `false` e `xertica-ui` resolve do `node_modules` normalmente.
+- **CLI — Language selection on `init`** — `npx xertica-ui init` now prompts for the languages the project should support (multi-select with `pt-BR`, `en`, `es`; all selected by default; minimum 1). The CLI:
+  - Copies **only** the locale folders for the selected languages into `src/locales/` (no orphan locales)
+  - Generates `src/i18n.ts` with `import.meta.glob` calls for exactly those languages
+  - Injects the `availableLanguages` prop into the generated `src/app/App.tsx`
+  - Persists the selection in `src/locales/.languages.json` (schema v1)
+- **CLI — `update` → Languages** — new option in the `update` command lets users add or remove languages later. Shows a diff (`+ es`, `- en`) before confirming. Regenerates `App.tsx`, `i18n.ts`, copies new locale folders, and prunes removed ones.
+- **CLI — Monolingual auto-detection** — when only one language is selected, the generated `App.tsx` includes a banner comment documenting that the `LanguageSelector` will auto-hide.
+- **`bin/language-config.ts`** — new module encapsulating the supported-language registry (`SUPPORTED_LANGUAGES`), code generators (`generateI18nFile`, `generateAppTsx`), and persistence helpers (`readLanguagesConfig`, `writeLanguagesConfig`, `syncLocaleFiles`).
+
+### Fixed
+
+- **Dark mode toggle no CLI** — `XerticaProvider` no `templates/src/app/App.tsx` era gerado com `disableDarkMode` hard-coded, tornando o `ThemeToggle` um no-op. Removido de `App.tsx`, do template literal do CLI em `bin/language-config.ts` e do exemplo em `templates/CLAUDE.md`.
+
+### Changed
+
+- **CLI — `update` → Project files (`app` branch)** — instead of blindly overwriting `App.tsx` and `i18n.ts` with the static template (which would erase the user's language selection), the update flow now reads the persisted selection from `src/locales/.languages.json` and regenerates these files honoring it. Projects scaffolded before this feature shipped get their selection inferred from the locale files present and the inferred config is written back.
+- **`DashboardTemplate`** — `StatsCard` deixou de chamar `useTranslation()` internamente; o sufixo de tendência (`lastMonth`) é resolvido no pai e passado como prop, reduzindo o número de subscribers i18n de 5 para 1.
+- **`TemplateContent` — dialog inputs controlados** — os `Input` do dialog "Editar Perfil" foram convertidos de `defaultValue` (uncontrolled) para `value`/`onChange` com lazy `useState`, garantindo que o valor reflita o idioma ativo no momento da montagem sem sobrescrever edições do usuário.
+- **`TemplateContent` — `treeData` movido para dentro do componente** — os labels dos nós do TreeView (`Components`, `UI`, `Button`…) agora reagem ao switch de idioma em tempo real, pois `treeData` é construído após `const { t } = useTranslation()`.
+
+---
+
+## [2.1.11] — 2026-05-20
+
+### Fixed
+
+- **CLI Initialization** — Correções essenciais no comando `init`:
+  - `i18n.ts` e o diretório `locales/` agora são copiados corretamente, restaurando as traduções na aplicação gerada.
+  - `AuthContext.tsx` e dependências agora são incluídas, habilitando o hook `useAuth`.
+  - A geração do `AuthGuard.tsx` foi reconstruída de forma dinâmica para consumir corretamente o `useAuth()` e garantir integridade das rotas protegidas e abertas, suportando _lazy loading_ dinâmico das rotas de acordo com a seleção do usuário.
+  - O diretório `features/assistant/` agora é sempre copiado visto que o `AppLayout` depende nativamente da `AssistantPage`.
+- **Template Lints** — Resolução de diversos `unused-vars` (variáveis e imports órfãos) espalhados pelo `HomeContent.tsx`, `TemplateContent.tsx`, `AssistantPage.tsx` e `AuthContext.tsx`, garantindo que o `npm run check` (`tsc` + `eslint`) execute com 100% de sucesso imediatamente após a geração do projeto.
+- **`LanguageSelector` e `LanguageContext`** — Correção de bugs na seleção de idiomas e fallback:
+  - `LanguageContext.tsx` agora valida de forma robusta e intercepta valores legados como `'PT'` no `localStorage`, realizando um _fallback_ seguro para `'pt-BR'`.
+  - O componente `LanguageSelector.tsx` foi ajustado na sua composição com Radix UI: a dependência restritiva do `<SelectValue>` foi removida no trigger, evitando a sobrescrita do conteúdo. Agora o componente exibe a variante `minimal` (como `PT`, `EN`, `ES`) perfeitamente, sincronizada com o estado global de tradução.
+
+---
+
+## [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.