# 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]

---

## [3.2.0] — 2026-08-17

### Added

- **`FileUpload` ganhou uma variante compacta e texto totalmente localizável** — até então o componente só tinha um layout (dropzone vertical, ícone grande) e todo o texto visível (rótulo de upload, dicas de contagem/tamanho, mensagens de erro de tamanho/quantidade) era uma string em inglês fixa no código, o único primitivo em `components/ui/` nessa condição. Adicionada a prop `size?: 'default' | 'compact'` em `components/ui/file-upload/file-upload.tsx`, seguindo o padrão de lookup por objeto plano já usado por `Search` (sem `cva`, reservado a componentes com mais de um eixo de variante) — `compact` troca o layout vertical por um horizontal, com ícone e espaçamentos menores, para uso em formulários densos. Junto, sete novas props de texto (`uploadLabel`, `dragAndDropLabel`, `multipleFilesLabel`, `singleFileLabel`, `maxSizeLabel`, `sizeErrorLabel`, `countErrorLabel`) substituem as strings fixas, com defaults em inglês idênticos ao comportamento anterior e placeholders (`{count}`, `{size}`, `{max}`) para os valores dinâmicos; as duas últimas também foram adicionadas a `UseFileUploadProps` em `components/ui/file-upload/use-file-upload.ts` para quem usa o hook headless diretamente. Documentação sincronizada em `docs/components/file-upload.md` e `file-upload.mdx`, com novos stories (`Compact`, `CustomLabels`) e testes em `file-upload.stories.tsx`/`file-upload.test.tsx`.
- **`XerticaAssistant` ganhou suporte a respostas em streaming** — nova prop `streamResponseGenerator` (async generator) em `components/assistant/xertica-assistant/use-assistant.ts` e `xertica-assistant.tsx`, com prioridade sobre `responseGenerator`/`demoMode`, permite plugar um backend real (ex. FDM Agent Engine) que entrega a resposta token a token em vez de um bloco único. `responseGenerator` passou a receber um segundo parâmetro opcional `action?: ActionType`, compatível com callbacks existentes que o ignoram. `ActionType` agora é exportado por `components/assistant/index.ts` para quem implementa `streamResponseGenerator`.
- **Ações em mensagens do assistente** — `AssistantMessageBubble`/`types.ts` ganharam as props opcionais `onMessageAction`/`activeMessageActionId`, o helper `isEmptyAssistantPlaceholder()`, a interface `MessageAction` e o campo opcional `Message.action`, habilitando um placeholder animado de "digitando" para respostas vazias em streaming (substituindo o indicador de digitação redundante) e um botão de ação em mensagens de alerta (prefixo `🔐`/`❌`, removido do texto exibido).
- **`MarkdownMessage`**: suporte a headers `h4`, citações em bloco (`>`, incluindo agrupamento multi-linha) e texto riscado (`~~texto~~`); `*` agora também é aceito como marcador de lista (GFM).

### Fixed

- **`MarkdownMessage` corrompia código contendo `**`, `_` ou crase** (ex. `x**2`, `__init__`) porque os regexes de negrito/itálico/código inline rodavam antes da extração dos blocos ```` ``` ````. Corrigido extraindo e renderizando blocos de código como elementos `<CodeBlock>` reais logo no início do parsing, antes de qualquer outro regex; listas também passaram a resolver antes de negrito/itálico para o marcador `*` não colidir com o delimitador de itálico. Relevante porque é exatamente a forma de markdown que backends como FDM/Gemini emitem.
- **`CodeBlock` rejeitava (em tipo) linguagens suportadas pelo Prism fora de um union fechado** (`'typescript' | 'tsx' | 'css' | 'bash' | 'jsx'`). Ampliado para o tipo `CodeLanguage`, um union aberto (`... | (string & {})`), sem alterar o comportamento dos valores já usados.
- **Auto-scroll do `XerticaAssistant` parava de acompanhar respostas longas** — a checagem de "está perto do fim" era feita antes do container crescer com a nova mensagem; agora usa um listener de scroll real. Chamadas a `responseGenerator`/streaming agora são protegidas por try/catch, mostrando uma mensagem de fallback em vez de travar ou lançar uma exceção não tratada quando o gerador falha.
- **`Badge` com texto longo sempre ficava em uma única linha**, mesmo com a largura do container restringida via `className`, por causa de `whitespace-nowrap` fixo nas classes base do `cva`. Trocado por `break-words` em `components/ui/badge/badge.tsx` — badges continuam em uma linha por padrão (sem `max-w-*` não há necessidade de quebra), mas agora quebram corretamente quando a largura é restringida (ex. `className="max-w-32"`).

---

## [3.0.1] — 2026-08-06

### Fixed

- **`Sidebar`/`XerticaAssistant` exibiam dados fake ("Ariel Santos") em vez do usuário autenticado real** — `AppLayout.tsx`, `HomePage.tsx` e `TemplatePage.tsx` sobrescreviam a prop `user` (e o `XerticaAssistant` sobrescrevia `userName`) com um usuário fixo, mesmo quando `useAuth()` já expunha os dados reais da sessão. Corrigido removendo os overrides fixos nos três componentes reais, em `bin/cli.ts` (`generateHomePage()`) e nos templates espelho (`templates/src/pages/HomePage.tsx`, `templates/src/pages/AssistantPage.tsx`); `XerticaAssistant` volta a usar seu fallback traduzido (`t('assistant.defaultUserName')`) quando `userName` não é passado.
- **Bug de scroll no Storybook** — corrigido via `.storybook/preview.tsx`.
- **`HomePage`/`TemplatePage` publicados em `xertica-ui/pages` quebravam ao montar em qualquer app consumidor** — ambos chamam `useAuth()` internamente, mas `AuthContext` não era reexportado por nenhum subpath do pacote, então não havia como o consumidor renderizar `<AuthProvider>` acima deles. Corrigido adicionando `export * from '../../contexts/AuthContext'` a `components/hooks/index.ts`, tornando `AuthProvider`/`useAuth`/`AuthUser` importáveis de `xertica-ui/hooks`; adicionado teste de regressão em `public-api-smoke.test.tsx` e nota no README.
- **Scaffold gerado pelo CLI instalava uma versão major desatualizada do próprio `xertica-ui`** — `templates/package.json` fixava `"xertica-ui": "^2.7.0"` e é copiado quase verbatim (`copyPackageJson()`) para todo projeto novo, então qualquer app recém-gerado instalava a 2.x enquanto o código-fonte do template já usava APIs da 3.x. Corrigido atualizando `templates/package.json` para `"version": "3.0.1"` e `"xertica-ui": "^3.0.1"`.
- **Nav da `Sidebar` em projetos "Full system" podia apontar para uma rota nunca registrada** — `templates/src/shared/config/navigation.ts` sempre incluía `/home` e `/template` independentemente de quais páginas o usuário selecionou no prompt do CLI, gerando um item de menu morto quando uma das duas era desmarcada. Corrigido com uma nova função `generateNavigation(hasHome, hasTemplate)` em `bin/cli.ts`, que agora sobrescreve `navigation.ts` no projeto gerado com apenas as rotas efetivamente registradas em `AuthGuard`.

### Changed

- **Prop de logout do `Header` renomeada de `onLogoutClick` para `onLogout`**, para consistência com a prop de mesmo nome já usada pelo `Sidebar`. Sem uso interno de `onLogoutClick` identificado no repositório antes da mudança.

---

## [3.0.0] — 2026-07-17

### Fixed

- **Scroll da `Sidebar` aparecia com a barra nativa do navegador, "colorida" e destoante do fundo escuro** — os containers de navegação com scroll real (variante `assistant` e o acordeão de overflow no mobile) usavam `overflowY: 'auto'` puro, sem nenhum estilo de scrollbar. Corrigido aplicando as utilities nativas do Tailwind v4 `scrollbar-thin scrollbar-thumb-sidebar-border scrollbar-track-transparent`, usando o token `--sidebar-border` (que resolve para um overlay de baixa opacidade sobre o fundo da sidebar em todos os 10 temas de marca), deixando o scroll discreto em qualquer tema.
- **Botão de filtro da `Sidebar.Search` perdia contraste no hover** — herdava o `hover:text-accent-foreground` (cor escura, pensada para superfícies claras) da variante `ghost` do `Button`, por sobrescrever apenas o `hover:bg-*` e não o `hover:text-*`. Corrigido adicionando `hover:text-sidebar-foreground` explicitamente, no mesmo padrão já usado pelo botão de "mais opções".

### Changed

- **Largura padrão da `Sidebar` expandida aumentada de 256px para 320px** (`LayoutContext`), com o fallback standalone de `Sidebar.Root` (fora de um `LayoutProvider`) também atualizado de 280px para 320px para manter os dois caminhos consistentes.

---

## [2.9.9] — 2026-07-14

### Fixed

- **Isotipo da marca e a inversão de cores apareciam nas telas de auth em qualquer tema, não só no "Xertica"** — os commits que introduziram o isotipo (`31e3bb51`, `7f047240`) trocaram o `leftPanel` do `AuthPageShell` para `"isotype"` de forma incondicional nas 4 páginas de autenticação (`LoginPage`, `ForgotPasswordPage`, `ResetPasswordPage`, `VerifyEmailPage`), então o painel esquerdo sempre exibia a marca e a inversão de cores (`bg-card`/`bg-muted`) associada a ela, mesmo com qualquer outro tema de cor ativo — inclusive o `xertica-original`, o tema clássico padrão. Corrigido lendo `currentTheme` via `useBrandColors()` em cada página e só usando `leftPanel="isotype"` quando `currentTheme === 'xertica'`; para os demais temas, o painel volta a exibir a imagem de capa e o gradiente originais (recuperados do histórico do git, anteriores ao rebranding). Aplicado tanto nos componentes reais (`components/pages/*-page`) quanto nos templates espelho usados pelo CLI (`templates/src/features/auth/ui/*Content.tsx`).

---

## [2.9.8] — 2026-07-14

### Fixed

- **Projeto gerado pelo scaffold "Web page" não compilava — erros de tipo de bibliotecas de terceiros** — `tsconfig.node.json` não tinha `skipLibCheck`, então o type-check processava as definições de tipo de dependências transitivas usadas internamente pelo Vite (`d3-array`, `prismjs`, etc.), e qualquer inconsistência nelas quebrava a compilação do projeto gerado, mesmo sem nenhum erro real no código do usuário. Corrigido adicionando `"skipLibCheck": true` a `templates/tsconfig.node.json`, usado tanto pelo scaffold "Web page" quanto pelo "Full system".
- **Tela em branco no scaffold "Web page" — `Error: No QueryClient set, use QueryClientProvider to set one`** — o `App.tsx` gerado por `generateLandingAppTsx` (`bin/language-config.ts`) renderizava `<LandingPage>` direto dentro de `<XerticaProvider>`, sem `QueryClientProvider`, partindo do pressuposto de que a landing page não dependia de React Query. Só que `XerticaProvider` monta `LanguageProvider` internamente, e este chama `useQueryClient()` para invalidar queries traduzíveis na troca de idioma — sem um `QueryClientProvider` acima na árvore, o app quebra no primeiro render. Corrigido envolvendo o `App.tsx` gerado em `<QueryClientProvider client={queryClient}>` (com `queryClient = new QueryClient()`), o mesmo padrão que o scaffold "Full system" (`generateAppTsx`) já usava.
- **Scroll não funcionava no scaffold "Web page"** — o CSS da própria lib (`styles/xertica/base.css`) define `html, body { height: 100%; overflow: hidden; }`, delegando o scroll a um container interno com altura própria resolvida. Como o `#root` gerado pelo Vite não tinha altura definida, a `LandingPage` (que usa `h-full overflow-y-auto`) não tinha em relação a que altura calcular seu próprio limite de scroll. Corrigido adicionando `#root { height: 100%; }` a `templates/src/styles/index.css`.

---

## [2.9.7] — 2026-07-14

### Fixed

- **Suíte de testes com exceção não tratada bloqueando `npm publish`** — o pacote de terceiros `input-otp` agenda três `setTimeout` internos (0ms/10ms/50ms) em um `useEffect` sem função de limpeza no unmount. Ao rodar a suíte completa, o cleanup automático do Testing Library desmontava o `InputOTP` entre um teste e outro sem cancelar esses timers, que disparavam mais tarde — já fora do ambiente jsdom daquele arquivo — lançando `ReferenceError: window is not defined` como exceção não tratada. Isso fazia `vitest run` sair com erro mesmo com todos os 358 testes passando, derrubando a etapa `test:unit` do `prepublishOnly` e, com isso, qualquer tentativa de `npm publish`. Corrigido em `components/ui/input-otp/input-otp.test.tsx` usando `vi.useFakeTimers()`/`vi.useRealTimers()` ao redor de cada teste, impedindo que os timers da lib vazem para fora do ciclo de vida do teste.
- **`npm publish` alertava sobre correção automática do campo `bin`** — `"bin": "./dist/cli.js"` (string, com prefixo `./`) era normalizado pelo próprio npm no momento do publish, gerando o aviso `npm auto-corrected some errors in your package.json`. Corrigido escrevendo `bin` já na forma canônica esperada (`{ "xertica-ui": "dist/cli.js" }`), sem mudança de comportamento — apenas elimina o aviso.

---

## [2.9.6] — 2026-07-14

### Added

- **CLI `init` pergunta o tipo de projeto antes de tudo** — novo primeiro prompt `O que você deseja criar?` com duas opções: `Full system` (o fluxo completo existente, inalterado: auth, sidebar, páginas, i18n) e `Web page` (um scaffold mínimo com apenas a landing page de marketing). Escolhendo `Web page`, o fluxo se reduz a 3 prompts — idiomas (multiselect), tema (select) e instalação de dependências (confirm) — e o projeto já sai pronto, sem nenhuma outra configuração.
- **Novo scaffold mínimo para "Web page"** (`initPageProject` em `bin/cli.ts`) — gera um `App.tsx` que renderiza `LandingPage` (via novo `generateLandingAppTsx` em `bin/language-config.ts`) diretamente dentro de `XerticaProvider`, sem `Router`, `QueryClientProvider` ou `AuthProvider`. Não cria `AuthContext.tsx`, `AuthGuard.tsx`, `AppLayout.tsx`, `src/shared/` nem `src/features/` — apenas `src/app/App.tsx`, `src/pages/LandingPage.tsx`, i18n/locales e tokens de tema. Também omite `CLAUDE.md`/`guidelines/` (documentam a arquitetura FSD de auth, inexistente neste scaffold) e `.env.example` (chaves usadas só pelo assistente/mapa).
- **`src/pages/LandingPage.tsx` do scaffold "Web page" ganha conteúdo de demonstração real** — em vez de um re-export de `xertica-ui/pages`, o template (`templates/src/pages/LandingPage.tsx`) agora traz a composição completa da landing page (Hero, cards, feature rows, "how it works", compliance/stats, CTA, footer) montada localmente a partir de `xertica-ui/blocks`/`xertica-ui/brand`, igual ao padrão já usado pelos demais templates (`HomeContent.tsx` etc.) — o usuário recebe algo editável como base, não uma caixa-preta importada da lib.
- **`.xertica.json` ganha o campo `projectType: 'page' | 'system'`** — projetos escaffoldados antes desta versão não têm o campo e são tratados como `'system'` em todos os pontos que o leem, preservando compatibilidade.

### Changed

- **CLI `update` adaptado para os dois tipos de projeto** — em projetos `page`, o menu principal omite a opção `Assistant` (sem conceito de assistente nesse scaffold); as opções `Languages` e `Dark Mode` regeneram `App.tsx` via `generateLandingAppTsx` em vez de `generateAppTsx`; e `Project files` mostra uma lista reduzida de 2 itens (`App shell + landing page`, `Root config files`) em vez dos 5 itens do fluxo completo, evitando tentar atualizar `AppLayout.tsx`/`AuthGuard.tsx`/`src/shared/`/`src/features/`, que não existem nesse tipo de projeto.
- **`generateAppTsx` refatorado** — a lógica de montagem da prop `availableLanguages` foi extraída para um helper interno compartilhado (`buildAvailableLanguagesProp`), reaproveitado agora também pelo novo `generateLandingAppTsx`.

---

## [2.9.5] — 2026-07-14

### Added

- **Novo isotipo `IsotypeTwist`** (`components/brand/isotype`) — quinta marca da série "isotipos": duas formas angulares sobrepostas, seguindo o mesmo mecanismo do `IsotypeFrames` (ambas 100% opacas, interseção resolvida via `mix-blend-mode: multiply` na forma da frente, com `isolate` na raiz), com duas variantes de cor registradas em `ISOTYPE_TWIST_VARIANTS`: `'magenta-blue'` (rosa + azul) e `'blue-red'` (azul + vermelho). Substitui o `IsotypeDiagonal` no painel esquerdo do `AuthPageShell` (`leftPanel="isotype"`, usado na página de login), agora renderizado com a variante `'magenta-blue'`.
- **`SectionHeading` ganha uma barra de destaque opcional** — nova prop `accentColor` (mesma convenção `BlockColor`/`colorTokens` local dos demais blocos) renderiza uma pequena barra colorida sob o título, aproximando o padrão da referência de mockup. É opcional: sem `accentColor`, o título continua exatamente como antes.

### Changed

- **`SectionHeading` simplificado** — removidos o numeral fantasma (`index`) e o rótulo eyebrow, mantendo apenas o título (com barra de destaque e descrição opcionais), conforme a referência de mockup. As props `index`/`eyebrow` saem da API do componente; as chaves de tradução `ecosystem.eyebrow`, `useCases.eyebrow` e `methodology.eyebrow` (agora não usadas) foram removidas dos 6 arquivos `landing.json`. Aplicado às 3 seções que já usam `SectionHeading` na `LandingPage` (Ecossistema, Casos de uso, Metodologia).
- **`ServiceCardGrid`/`ServiceCard` com `icon` opcional** — o chip de ícone só renderiza quando `icon` é informado, permitindo cards sem ícone (título, descrição e checklist/bullets/CTA), conforme a referência de mockup. Aplicado à seção "Casos de uso" da `LandingPage`, que passa a renderizar os 3 cards sem ícone.

- **`AuthPageShell` (`leftPanel="isotype"`) com fundos invertidos** — o painel do isotipo na página de login passa a usar `bg-muted` (mais escuro) e o painel do formulário à direita passa a usar `bg-card` (Marfim, `#FFFEF8` no tema xertica, mais claro), invertendo a relação de claridade anterior entre os dois lados.
- **`ForgotPasswordPage`, `ResetPasswordPage` e `VerifyEmailPage` trocam a foto de fundo pelo painel de isotipo** — as 3 telas usavam `AuthPageShell` com `imageSrc`/foto de herói e um overlay de gradiente que, no tema xertica (token de gradiente plano em `#1E1E1E`), ficava com o painel esquerdo escuro. Passam a usar `leftPanel="isotype"`, a mesma solução (agora clara) já aplicada à `LoginPage`, unificando a aparência das 4 telas de autenticação. Espelhado em `templates/src/features/auth/ui/{ForgotPassword,ResetPassword,VerifyEmail}Content.tsx`.
- **`SectionHeading` perde a linha divisória superior** — removida a borda `border-t`/`pt-6` que antecedia o título (Ecossistema, Casos de uso, Metodologia na `LandingPage`); o cabeçalho agora fica sem regra visual antes do título.
- **`CTASection` volta a ter fundo escuro** — troca o `bg-card` plano por `bg-sidebar`/`border-sidebar-border` (mesma superfície escura já usada na seção de metodologia desta página) e o texto passa a `text-sidebar-foreground`/`text-sidebar-foreground/70`, sem gradiente e sem cor hardcoded. Os botões continuam com as variantes naturais (`default`/`outline`), que já contrastam corretamente sobre `bg-sidebar`.
- **Seção de compliance/stats da `LandingPage` reorganizada** — `ComplianceBadgeRow` (badges) e `StatBand` (números) agora ficam contidos em um único card (`border`, `bg-card`, `rounded-2xl`) com um divisor entre os dois grupos, em vez de flutuarem soltos direto sobre o fundo da página. `ComplianceBadgeRow` passa de um `flex flex-wrap` com gaps largos para um `grid grid-cols-2 sm:grid-cols-4`, alinhando os badges em colunas; o chip de ícone usa `bg-background` para manter contraste dentro do novo card.
- **`IsotypeFrames` restrito a duas variantes de cor** — `IsotypeFrameVariantId` passa de 6 para apenas `'blue-magenta'` e `'blue-yellow'` (azul+rosa e azul+amarelo); `'green-red'`, `'green-blue'`, `'magenta-yellow'` e `'magenta-purple'` saem do registro. Único uso afetado fora do próprio componente: a seção "Onboarding" da `LandingPage`, que usava `magenta-yellow` e passa a usar `blue-yellow`. No par `blue-yellow`, o azul é o quadro de trás (posicionado mais para cima) e o amarelo o quadro da frente (posicionado mais para baixo).

### Removed

- **Removidas as seções de depoimento e de "pilares" da `LandingPage`** — o card de citação com `StatBand` (componentes/temas/downloads) e o grid de 4 colunas com ícones (tokens de tema, componentes acessíveis, blocos prontos, CLI de scaffolding) saem da página. As chaves de tradução `testimonial`, `pillars` e `stats.components`/`stats.themes`/`stats.downloads` (agora não usadas) foram removidas dos 6 arquivos `landing.json`.

---

## [2.9.4] — 2026-07-13

### Added

- **Novo bloco `HowItWorksSteps`** (`xertica-ui/blocks` → `marketing`) — variante horizontal do `EvidenceTimeline`: mesma badge numerada/colorida (`colorTokens` local, sem linha conectora), em grid responsivo (`grid-cols-1 sm:grid-cols-2 lg:grid-cols-4`) em vez de lista vertical com fio. Substitui o `EvidenceTimeline` na seção "Metodologia" da `LandingPage` (mesmos 4 itens/cópias); o `EvidenceTimeline` continua exportado e funcional para quem preferir o layout vertical.
- **Novo bloco `TopAccentCards`** (`xertica-ui/blocks` → `marketing`) — par de cards com destaque de cor na borda superior (`border-t-4`), título, corpo e lista opcional de bullets simples, sem ícone/CTA. Segue a mesma convenção local de `BlockColor`/`colorTokens` dos demais blocos de marketing. Nova seção "framing" (propósito + problema) inserida na `LandingPage` logo após o `Hero`.

### Changed

- **`CTASection` perde o fundo em gradiente** — passa a usar um fundo plano `bg-card` com borda (`border border-border`), título em `text-foreground` e descrição em `text-muted-foreground`. Os botões `cta`/`secondaryCta` deixam de ter cor forçada (branco sobre gradiente) e usam as variantes naturais `default`/`outline`, que já contrastam corretamente sobre `bg-card`. Nenhum outro consumidor deste bloco existe fora da `LandingPage`.
- **`PillBadge` vira um pill de verdade** — `rounded-[var(--radius)]` (6px) dá lugar a `rounded-full`, alinhando o componente ao próprio nome. Único consumidor é o eyebrow do `Hero`.
- **Recolorida a seção "Metodologia" da `LandingPage`** — os 4 passos passam de azul/celeste/amarelo/coral para coral/celeste/azul/laranja (`chart-4`/`chart-2`/`chart-1`/`warning`), aproximando a sequência de cores da referência de mockup (vermelho/verde-azulado/roxo/laranja); como o tema `xertica` não tem roxo, `chart-1` (azul) substitui esse passo — é um desvio conhecido da referência.

---

## [2.9.3] — 2026-07-13

### Changed

- **Padronização das variantes de botão na landing page** — o botão de "iniciar sessão" (`MarketingNavbar`, desktop e mobile) e o `secondaryCta` do `Hero` passam a usar a variante `secondary` (preto). O `primaryCta` do `Hero` ("Começar agora") e o `cta` do `CTASection` continuam `default`/primary, reservado para as ações principais de conversão. A variante `outline` continua reservada para os cards (`ServiceCardGrid`). Mudança feita direto nos blocos, sem novas props — nenhum outro consumidor desses componentes existe fora da `LandingPage`.

---

## [2.9.2] — 2026-07-13

### Changed

- **Tema `xertica` deixa de ter gradientes** — `gradientStart`/`gradientEnd` (claro e escuro) passam a apontar todos para o mesmo Negro Xertica (`#1E1E1E`), então `--gradient-diagonal` resolve para um preenchimento sólido nesse tema. Afeta todo consumidor do token (banner do `CTASection` na `LandingPage`, `AuthPageShell`, etc.) sem exigir mudança em nenhum componente — os demais temas mantêm seus gradientes normalmente.

---

## [2.9.1] — 2026-07-13

### Changed

- **`StatBand` ganha alinhamento numérico e rótulo em estilo legenda** — o valor numérico agora usa `tabular-nums` (mesma técnica já usada no numeral fantasma do `SectionHeading`), e o rótulo passa de texto simples (`text-sm`) para o padrão de legenda já usado em `ServiceCardGrid` (`text-xs font-semibold uppercase tracking-wide`). Ritmo de grade mais generoso (`gap-y-8`→`gap-y-10`, `pl-8`→`pl-10` nos divisores).
- **Espaçamento título→texto corrido padronizado em `SectionHeading`, `FeatureRow`, `CTASection` e `EvidenceTimeline`** — na referência de Swiss Design, títulos e o texto corrido que os segue precisam de um espaço deliberado entre si. O gap `mt-3`/`mt-4` (12–16px) usado nos blocos de marketing da `LandingPage` passa para `mt-6` (24px) nos três primeiros; `EvidenceTimeline`, por ser um relacionamento secundário mais denso dentro de uma lista, recebe um ajuste proporcional menor (`mt-1`→`mt-2`).

---

## [2.9.0] — 2026-07-13

### Added

- **`xertica-ui/blocks` ganha um novo namespace `marketing`** — `Hero`, `FeatureRow`, `CTASection`, `ComplianceBadgeRow`, `EvidenceTimeline`, `LogoCloud`, `MarketingFooter`, `MarketingNavbar`, `PillBadge`, `ServiceCardGrid` e `StatBand`, compondo a nova `LandingPage` (`xertica-ui/pages`, também registrada em `/landing` no template do CLI). Todos os visuais são placeholders orientados a tokens (isotipos da marca, SVGs inline), sem dependência de imagens externas.
- **Nova marca `IsotypeDiagonal`** — quarta variação da família `isotype` (`xertica-ui/brand`), com corte diagonal fixo formando pontas triangulares nos encontros azul/verde e magenta/vermelho e na hipotenusa do amarelo, as três sobre a mesma diagonal do quadrado. `AuthPageShell` ganha a prop `leftPanel="isotype"` (painel de marca sobre `bg-sidebar`, alternativa ao par imagem+gradiente) e `gradientClassName` (override do gradiente por página); `LoginPage` e o `LoginContent` do template do CLI passam a usar `leftPanel="isotype"`, substituindo a foto de estoque (Unsplash) que usavam antes.
- **`Button` variant `outline` ganha um token de contorno dedicado** — `--outline-border` / utilitário `border-outline-stroke` — com o mesmo mecanismo opcional (`BrandColors.outlineBorderColor`) já usado por `inputBorderColor`. Os 9 temas pré-existentes ficam pixel-idênticos (fallback para `--border`); o tema `xertica` passa a usar o mesmo Negro Xertica do contorno dos inputs.

### Changed

- **`Isotype` (grid plano) e `IsotypeMini` saem de rotação** nas páginas do próprio design system (Hero da `LandingPage`, cabeçalho da `HomeContent`) — continuam exportados e totalmente funcionais, apenas comentados no ponto de uso para fácil reativação futura. Só `IsotypeDiagonal` e `IsotypeFrames` seguem em uso ativo.

### Fixed

- **`Card` `variant="white"` podia renderizar texto ilegível no dark mode** — `text-card-foreground` (tema-reativo) era aplicado incondicionalmente, então um card forçado a branco herdava a cor de texto quase-branca do tema no dark mode. Agora `variant="white"` sempre pareia com `text-neutral-900` fixo, independente do tema/modo.

---

## [2.8.0] — 2026-07-09

### Added

- **Novo tema `xertica`** — a nova identidade visual da Xertica (papel quente `#FFFEF8`, tintas vivas e o preto da marca como acento geral), somando-se aos temas já existentes em `contexts/theme-data.ts` → `colorThemes`. Botões neste tema ganham radius pill (`buttonRadius: '9999px'`), stroke em todas as variantes preenchidas (`buttonStrokeWidth`/`buttonStrokeColor(Dark)`), botão primário amarelo (`#FAF338`) com contorno e texto pretos, e botão secundário na cor preta da marca (`buttonSecondaryBg(Dark)`/`buttonSecondaryForeground(Dark)`). O amarelo é **intencionalmente restrito** ao botão `default` e ao estado ligado do `Switch` — o acento geral do tema (`--primary`, usado por links, radio buttons, foco, logo, etc.) é Negro Xertica `#1E1E1E` (Crema `#F2EDD8` no dark mode), evitado de virar amarelo sem contraste em elementos que não são botão/switch. O tema `xertica-original` (agora exibido como **"Xertica Classic"**) permanece o padrão — o `id` não foi alterado, então projetos scaffolded e chamadas `setTheme('xertica-original')` continuam funcionando sem mudanças.
- **`BrandColors` ganha campos opcionais de forma/estrutura de botão** — `backgroundLight`, `buttonRadius`, `buttonStrokeWidth`, `buttonStrokeColor`/`buttonStrokeColorDark`, `buttonSecondaryBg`/`buttonSecondaryBgDark`, `buttonSecondaryForeground`/`buttonSecondaryForegroundDark`, e `buttonPrimaryBg`/`buttonPrimaryBgDark`, `buttonPrimaryForeground`/`buttonPrimaryForegroundDark` (acento do botão `default` e do `Switch`, com fallback para `var(--primary)`/`var(--primary-foreground)`). Todos são opcionais e têm fallback idêntico ao comportamento anterior, então os 9 temas pré-existentes ficam pixel-idênticos. Removido o campo morto `radius?: string` (nunca lido por `applyColors()`).
- **`components/ui/button/button.tsx`** — as variantes preenchidas (`default`, `destructive`, `secondary`, `success`, `info`, `warning`) agora aceitam um stroke via `--button-stroke-width`/`--button-stroke-color`; a variante `default` passou a usar `--button-primary-bg`/`--button-primary-foreground` (em vez de `bg-primary`/`text-primary-foreground` direto) para permitir um acento de botão distinto do `--primary` semântico geral; a variante `secondary` passou a usar os tokens `--button-secondary-bg`/`--button-secondary-foreground` (com fallback para `--secondary`/`--secondary-foreground`) em vez do modificador de opacidade `/80`, que não funcionava sobre cores vindas de `var()`.
- **`components/ui/switch/switch.tsx`** — o estado marcado (`checked`) passou a usar `--button-primary-bg` em vez de `bg-primary`, para acompanhar o mesmo acento do botão `default`.

### Changed

- `bin/generate-tokens.ts` e os `tokens.css` estáticos (`styles/xertica/`, `templates/src/styles/xertica/`) passam a emitir `--button-stroke-width`, `--button-stroke-color`, `--button-secondary-bg`, `--button-secondary-foreground`, `--button-primary-bg`, `--button-primary-foreground`, e `--radius-button`/`--background` (light) respeitam os novos campos do tema quando definidos.
- `.storybook/preview.tsx` — toolbar "Brand Color" renomeia `xertica-original` para "Xertica Classic" e adiciona a entrada "Xertica" (`xertica`).

---

## [2.7.0] — 2026-07-07

### Added

- **`xertica-ui/blocks` ganha um novo namespace `auth`** — `AuthPageShell` (layout de imagem hero + seletor de idioma + painel de formulário centralizado), `SocialLoginButtons` (com prop `providers` configurável, default `['google', 'mtLogin', 'govBr']`, para projetos que não usam todos os provedores de login social), `usePasswordStrength` e `PasswordStrengthMeter`. Extraídos da duplicação entre `components/pages/{login,forgot-password,reset-password,verify-email}-page/*` e `templates/src/features/auth/ui/*`, que agora consomem a mesma fonte via `xertica-ui/blocks`.

### Fixed

- **Assistente de IA — clique numa sugestão inicial rolava a página e deslocava o header** — o efeito de auto-scroll de `use-assistant.ts` media `messagesEndRef.current.parentElement` (uma `<div>` sem overflow próprio) em vez do viewport real do `ScrollArea` do Radix, fazendo a checagem "está perto do fim da rolagem" ser sempre verdadeira — inclusive na primeira mensagem, na transição da tela de boas-vindas para a conversa. Sem `block: 'nearest'`, o `scrollIntoView` podia rolar a janela inteira. Corrigido para medir o `[data-radix-scroll-area-viewport]` correto e conter o scroll dentro dele.
- **`components/pages/forgot-password-page/ForgotPasswordPage.tsx` tinha texto hardcoded em português**, sem passar por `useTranslation()` como as demais páginas de auth. Convertido para `t('forgotPassword.xxx')`, com as chaves adicionadas em `locales/*/pages/forgotPassword.json` (en/es/pt-BR) na raiz.

### Changed

- **`templates/src/features/home` e `templates/src/features/template` reduzidos a placeholders mínimos** — esse conteúdo é vitrine de exemplo, feito para ser substituído pelo consumidor do `npx xertica-ui init`, não para ficar sincronizado com a lib. Removido código morto (`CrudTemplate`, `DashboardTemplate`, `FormTemplate`, `LoginTemplate`, `dashboardStore`, `mock.ts`, `useFeatureCards`) e os locales órfãos correspondentes nos 3 idiomas.
- Removidos `templates/vite.config.js`/`vite.config.d.ts` — artefatos de build obsoletos e versionados por engano desde a v2.1.0, que faziam o Vite carregar uma versão desatualizada da config (sem os aliases de desenvolvimento do monorepo) em vez do `vite.config.ts` atual.

---

## [2.6.0] — 2026-07-06

### Security

- **XSS — `MarkdownMessage.tsx` escapava HTML de forma incorreta (no-op)** — `replace(/</g, '<')` e `replace(/>/g, '>')` substituíam os caracteres por eles mesmos, não escapando nada apesar de parecer uma chamada de sanitização. Corrigido para usar entidades HTML reais (`&lt;`, `&gt;`).
- **XSS — `FormattedDocument.tsx` não escapava HTML antes de renderizar via `dangerouslySetInnerHTML`** — adicionado o mesmo escape (`&lt;`/`&gt;`) como primeira etapa da conversão de markdown.
- **XSS — `map.tsx` renderizava `iconSvg` de marcadores sem sanitização** — adicionado `dompurify` (perfil `svg`/`svgFilters`) para sanitizar o SVG mantendo a marcação válida, ao invés de injetar a string diretamente via `dangerouslySetInnerHTML`.
- **`.npmrc` com tokens de autenticação estava versionado no repositório** — removido do tracking (`git rm --cached`); o arquivo permanece no `.gitignore` para não ser versionado novamente. Rotação dos tokens expostos é uma ação separada, de responsabilidade da equipe.
- **`overrides` de `undici`/`react-router`/`esbuild` sem limite de versão** — trocado de ranges abertos (`>=`) para ranges com caret (`^0.28.1`, `^7.15.1`, `^7.28.0`), evitando que uma dependência transitiva quebre a suíte de testes ao saltar de major version silenciosamente.

### Added

- **Rota `/settings` e `SettingsPage`** — o botão de Configurações na Sidebar e o `onNavigateSettings` do `XerticaAssistant` navegavam para uma rota inexistente. Criada a feature `features/settings` (conta, preferências de tema/idioma, logout com confirmação) e registrada a rota em `generateAuthGuard()`/`AuthGuard.tsx`. A feature e a página são sempre incluídas pelo CLI (`init`/`update`), já que o botão de Configurações é renderizado incondicionalmente na Sidebar.
- **CLI `init` agora copia `.gitignore`/`.prettierrc` para o projeto gerado** — antes esses arquivos existiam apenas em `templates/` e nunca chegavam ao projeto scaffolded. `update` faz backfill apenas quando o arquivo não existe, preservando customizações.
- **`prepublishOnly` agora roda a suíte de testes unitários** (`npm run test:unit`, novo script equivalente a `vitest run --project unit`) antes do build, evitando publicar um pacote com testes quebrados.

### Changed

- Removidos comentários de raciocínio interno (rascunho/dúvidas) deixados em `bin/generate-tokens.ts`.
- `coverage/` e `.playwright-mcp/` — artefatos de teste que estavam versionados por engano — removidos do tracking e adicionados ao `.gitignore`.

---

## [2.5.3] — 2026-06-23

### Fixed

- **Sidebar — vazamento horizontal causado pelo `ScrollArea` do Radix UI** — o `@radix-ui/react-scroll-area` v1.x injeta `style={{ minWidth: "100%", display: "table" }}` no viewport interno, ignorando o `overflow: hidden` dos ancestors e causando scroll horizontal indesejado na sidebar. Substituídos os dois usos de `<ScrollArea>` no `SidebarNav` (variant `assistant` e accordion de overflow mobile) por `<div>` nativa com `style={{ overflowY: 'auto', overflowX: 'hidden' }}`. O import de `ScrollArea` foi removido do arquivo.

---

## [2.5.2] — 2026-06-23

### Fixed

- **TypeScript — erros de tipos `recharts` 3.x no `chart.tsx`** — `TooltipPayload`, `LegendPayload` e `DefaultTooltipContentProps` foram removidos do namespace raiz do recharts 3. Corrigido importando os tipos diretamente de `recharts/types/component/DefaultTooltipContent` e `recharts/types/component/DefaultLegendContent`, anotando explicitamente os parâmetros `item`, `index` e `v` nos callbacks de `payload.map` e `formatter`.

### Added

- **Sidebar — Overflow de `navigationGroups` no variant `default`** — quando a lista de grupos de navegação excede a altura disponível da sidebar, os grupos excedentes são movidos para um botão "mais opções" (`MoreVertical`). No **desktop** abre um `Popover` lateral direito com todos os grupos e itens restantes. No **mobile** expande um accordion inline (abaixo do botão, com animação Framer Motion) e a área de navegação passa a usar `ScrollArea` do design system para scroll, evitando que o conteúdo fique fora da área visível.
- **Storybook — Sidebar `WithSubitemsDesktop` e `WithSubitemsMobile`** — exemplos expandidos com 4 grupos (Principal, Comercial, Comunicação, Administração) e ~18 itens raiz com múltiplos subitens, suficientes para ultrapassar a altura da tela e demonstrar o comportamento de overflow em qualquer resolução.

---

## [2.5.1] — 2026-06-22

### Fixed

- **CLI `update → Theme` — tema atual não era pré-selecionado** — o prompt de seleção de tema sempre iniciava no índice 0 (`xertica-original`), independente do tema instalado. Corrigido lendo `themeId` do `.xertica.json` e calculando o índice inicial correspondente. O nome do tema atual é exibido antes da seleção.
- **CLI `update → Theme` — `themeId` não era persistido** — após trocar o tema, o `.xertica.json` não era atualizado com o novo `themeId`, fazendo com que execuções futuras continuassem sem memória da escolha. Corrigido com `writeXerticaConfig(targetDir, { themeId: selectedTheme.id })` após a escrita do `tokens.css`.
- **CLI `init` — `themeId` não era salvo em `.xertica.json`** — o tema escolhido durante `init` não era persistido no arquivo de configuração do projeto. Corrigido passando `themeId: response.theme` ao `writeXerticaConfig`.
- **`generate-tokens.ts` — `--sidebar-border` no dark mode estava hardcoded** — o valor `rgba(65, 61, 107, 1)` (indigo fixo) era usado para todos os temas. Corrigido usando `colors.darkBorder` para que cada tema utilize sua própria cor de borda tingida.
- **`XerticaConfig` — campo `themeId` faltando na interface** — adicionado campo opcional `themeId?: string` à interface `XerticaConfig` em `bin/cli.ts`.
- **Erros de TypeScript do `recharts` 3.x** — atualização da biblioteca quebrou os tipos de `ChartTooltipContent` e `ChartLegendContent`. Corrigido:
  - `ChartTooltipContent`: migrado de `React.ComponentProps<typeof Tooltip>` (que omite `payload`/`label` no recharts 3) para tipos explícitos usando `RechartsPrimitive.TooltipPayload` e `DefaultTooltipContentProps['formatter']`
  - `ChartLegendContent`: substituído `Pick<LegendProps, 'payload' | 'verticalAlign'>` por `{ payload?: LegendPayload[]; verticalAlign?: ... }` (recharts 3 removeu `payload` de `LegendProps`)
  - `DonutBreakdownChart`: removida prop `activeIndex` do `<Pie>` (não existe mais no recharts 3)
  - `PieMetricChart`: adicionado guard `if (midAngle == null || percent == null) return null` no callback de label
  - `chart.test.tsx`: adicionado `graphicalItemId` obrigatório ao mock de payload

### Changed

- **CLI `update → Theme`** — exibe o tema atual antes do prompt de seleção com `chalk.gray('Current theme: ...')`.

---

## [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.