xertica-ui 2.1.0 → 2.1.2

package/CHANGELOG.md

@@ -1,302 +1,324 @@
-# Changelog
-
-All notable changes to `xertica-ui` will be documented in this file.
-
-Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
-Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
----
-
-## [2.1.0] — 2026-05-13
-
-### Added
-
-- **`components/blocks/card-patterns/`** — novo domínio `blocks/` com 6 componentes de alto nível compostos exclusivamente de primitivos `ui/`:
-  - **`FeatureCard`** — ícone com fundo colorido, título, badge opcional, descrição e botão de ação. Suporta 10 tokens de cor (`primary`, `chart-1..5`, `success`, `info`, `warning`, `destructive`). Replica o padrão de cards da Home page.
-  - **`ActivityCard`** — feed de atividades recentes com avatar, descrição de ação, timestamp e badge por tipo (`create`, `update`, `delete`, `comment`, `deploy`).
-  - **`ProfileCard`** — card de usuário/membro com avatar, badge de status (`online`, `offline`, `away`, `busy`), linha de stats e ações primária/secundária.
-  - **`ProjectCard`** — status de projeto com badge, barra de progresso (usa `Progress` com variant semântica por status), stack de avatares de membros e data limite.
-  - **`QuickActionCard`** — tile de ação rápida com ícone em caixa colorida, badge e botão full-width.
-  - **`NotificationCard`** — lista de notificações com indicador de não-lido, badge de tipo, "Marcar todas como lidas" e "Ver todas".
-- **Exportação do domínio `blocks/`** — todos os componentes disponíveis via `import { ... } from 'xertica-ui'` e via `components/blocks/index.ts`.
-- **Subpath público `xertica-ui/blocks`** — `FeatureCard`, `ActivityCard`, `ProfileCard`, `ProjectCard`, `QuickActionCard` e `NotificationCard` agora podem ser importados diretamente de `xertica-ui/blocks`.
-- **Subpath público `xertica-ui/pages`** — `LoginPage`, `HomePage`, `TemplatePage`, `ForgotPasswordPage`, `ResetPasswordPage`, `VerifyEmailPage` e seus contents agora são publicados com entrypoint dedicado.
-- **Documentação** — criado `docs/components/card-patterns.md` com props, exemplos e layout de dashboard completo para todos os 6 block components.
-
-### Changed
-
-- **Calendar — dropdown caption styling** — quando `captionLayout="dropdown"` ou variações, os seletores de mês/ano agora têm visual de input (borda, fundo `bg-background`, focus ring `ring-primary`, `rounded-[var(--radius)]`, padding compacto fixo `px-2.5 py-1`). O `caption_label` em modo dropdown passa a usar `h-full w-full` com layout flexível.
-- **Calendar — prop `size` removida** — o tamanho e o arredondamento do trigger ("Pick a date") são responsabilidade do elemento trigger, não do `Calendar`. A story `InPopover` demonstra o padrão correto com `triggerSizeClasses` aplicado diretamente ao `<Button>` com `rounded-[var(--radius)]` para alinhar com o token do `Input`.
-- **Card stories** — enriquecidas com 3 novas variações: `WithAction` (uso de `CardAction` no header), `TeamMember` (grid de member cards com avatar e status), `SettingsCard` (lista de settings com `Separator` e `Badge`). Background `bg-muted` adicionado via decorator global da stories file para contraste com o fundo dos cards.
-- **Storybook — docs stories** — adicionado `render: (args) => <Component {...args} />` no nível do `meta` em todos os 60 arquivos de stories em `components/ui/`. Resolve o problema onde stories com apenas `args` (sem `render` explícito) mostravam a mesma variação repetida na aba Docs por dependerem do `projectAnnotations.render` implícito do framework React.
-- **Storybook — `preview.tsx`** — `min-h-screen` passou a ser condicional a `layout: 'fullscreen'`, resolvendo a altura excessiva dos exemplos na aba Docs.
-- **Template npm** — `templates/package.json` atualizado para `2.1.0` e dependência `xertica-ui` para `^2.1.0`.
-- **Template version badge** — o template passa a exibir um indicador visual discreto da versão do pacote `xertica-ui` usada pelo projeto.
-- **Documentação** — atualizados `calendar.md` (props `captionLayout`/`buttonVariant`, nota sobre `size` no trigger), `card.md` (`CardAction` na anatomia, exemplos WithAction/Stats/TeamMember/Settings), `chart.md` (nova seção Stacked Bar Chart), `architecture.md` (domínio `blocks/` com árvore de arquivos).
-
-### Fixed
-
-- **Chart — stacked bar radius** — em `DashboardBarChart` com `stacked`, apenas a série no topo de cada `stackId` recebe `radius={[4,4,0,0]}`; as demais recebem `radius={[0,0,0,0]}`. Elimina a borda arredondada no topo das barras intermediárias e inferiores da pilha.
-- **`FeatureCard` — badge overflow** — alterado de `flex items-center` para `flex flex-wrap` no container título+badge, garantindo que o badge quebre para a linha seguinte em vez de vazar fora do card quando o título ocupa toda a largura disponível.
-
----
-
-## [2.0.6] — 2026-05-13
-
-### Added
-
-- **Contrato de independência dos componentes** — documentado que `xertica-ui/style.css` é a única importação global obrigatória e que componentes públicos devem funcionar isoladamente sempre que possível.
-- **`useOptionalLayout`** — nova API compatível para componentes reutilizáveis consumirem o layout com fallback seguro, mantendo `useLayout` como hook estrito para apps que querem falhar cedo.
-- **Smoke tests de API pública** — adicionada validação de import/render dos subpaths públicos (`ui`, `brand`, `layout`, `assistant`, `media` e `hooks`).
-- **Exports públicos de Maps** — `useMapLayers`, `GOOGLE_MAPS_ID` e `GOOGLE_MAPS_LIBRARIES` agora são expostos pelo subpath `xertica-ui/ui`.
-
-### Changed
-
-- **`XerticaProvider` completo** — passa a compor providers de theme, brand colors, language, layout, assistant, API keys, Google Maps, tooltip e toaster como wrapper de conveniência para apps consumidores.
-- **Componentes com contexto de layout** — `Header`, `Sidebar`, páginas e componentes de mídia foram ajustados para renderizar com fallback interno quando importados sem provider.
-- **Arquitetura FSD/FDA** — tipos compartilhados do assistant foram movidos para camada neutra, evitando dependência runtime de `components/shared` para implementação de feature.
-- **Documentação LLM e componentes** — README, docs de provider/mapa, `llms.txt`, `llms-compact.txt` e `docs/llms.md` foram alinhados ao contrato de independência e aos subpaths consumíveis.
-- **Storybook Docs de UI** — páginas MDX dos componentes de UI agora renderizam as variações reais das stories, evitando repetição do mesmo exemplo nos blocos de variação.
-- **Storybook Maps** — stories de mapa usam um frame responsivo mais largo para melhorar a visualização na aba Docs.
-
-### Fixed
-
-- **Guards de browser/SSR** — providers e componentes browser-only agora protegem acessos a `window`, `document`, `localStorage`, `navigator` e scripts externos.
-- **Google Maps sem configuração** — componentes relacionados a Maps renderizam estados de configuração/erro sem quebrar a aplicação consumidora.
-
----
-
-## [2.0.5] — 2026-05-12
-
-### Added
-
-- **`llms-compact.txt`** — novo arquivo de referência compacto para LLMs, sintetizando todos os componentes em formato reduzido ideal para contextos de tokens limitados.
-- **`docs/decision-tree.md`** — guia de árvore de decisão para agentes de IA selecionarem o componente correto com base nos requisitos da UI.
-- **`templates/CLAUDE.md`** — `CLAUDE.md` agora é scaffolded automaticamente em projetos criados via `npx xertica-ui@latest init`, fornecendo contexto arquitetural (FSD/FDA, subpath imports, tokens semânticos) para Claude Code e outros assistentes de IA.
-- **Storybook stories** — adicionadas stories interativas para Accordion, AlertDialog, Button, Checkbox, Dialog, Input, Switch, Tabs, HomePage e TemplatePage.
-- **`components/pages/home-page/home-page.mdx`** e **`template-page.mdx`** — novas entradas de documentação MDX para as page components.
-
-### Changed
-
-- **`guidelines/Guidelines.md`** — reescrita completa do guia de arquitetura FSD/FDA: maior detalhamento de responsabilidades por camada, convenções de import e fluxo de adição de novas rotas.
-- **`components.json`** — atualização completa do registro de componentes, cobrindo todos os 97 componentes com metadados de subpath, props e variantes.
-- **`llms.txt`** — seção de subpath imports e mapeamento de camadas FSD/FDA atualizados.
-- **`vite.config.ts`** — ajustes no build multi-entry para garantir correta emissão dos arquivos CJS/ESM.
-
-### Fixed
-
-- **`npx xertica-ui init` usa versão em cache** — documentado que o npx armazena pacotes em cache localmente sem TTL curto. Sempre use `npx xertica-ui@latest init` para garantir a versão mais recente. O `templates/CLAUDE.md` scaffolded no projeto gerado inclui essa orientação.
-
----
-
-## [2.0.3] — 2026-05-11
-
-### Added
-
-- **CLI `update` — atualização de projeto** — novo modo no comando `update` permite atualizar os arquivos do projeto (app shell, shared, features, pages) para qualquer versão publicada do `xertica-ui`, com seleção granular de quais partes atualizar e confirmação antes de sobrescrever.
-
----
-
-## [2.0.2] — 2026-05-11
-
-### Fixed
-
-- **CLI rewritten for FSD/FDA structure** — `npx xertica-ui@latest init` agora copia corretamente a estrutura Feature-Sliced Design:
-  - Removida cópia de `src/app/routes.tsx` (arquivo não existe mais após refatoração)
-  - Adicionada cópia de `src/app/components/AppLayout.tsx`
-  - Adicionada cópia completa de `src/shared/` (`auth.ts`, `navigation.ts`, `types/auth.ts`)
-  - Adicionada cópia de `src/features/auth|home|template` conforme seleções do usuário
-  - Cópia de pages corrigida de `src/app/pages/` → `src/pages/`
-  - `AuthGuard.tsx` agora gerado dinamicamente com imports e rotas apenas das páginas selecionadas
-- **`generateDemoResponse` exportado via `xertica-ui/assistant`** — estava ausente do barrel causando `SyntaxError: does not provide an export named 'generateDemoResponse'`
-- **Build corrigido: UMD → CJS** — múltiplos entry points não são suportados com formato UMD no Vite; migrado para CJS (todos os `*.umd.js` → `*.cjs.js` no `package.json` exports)
-
----
-
-## [2.0.0] — 2026-05-11
-
-### Added
-
-- **Subpath exports** — The package now exposes 6 granular entry points alongside the full root barrel:
-  - `xertica-ui/ui` — all UI primitives (Button, Card, Input, Table, Dialog, etc.)
-  - `xertica-ui/layout` — Sidebar and Header
-  - `xertica-ui/brand` — XerticaProvider, XerticaLogo, XerticaXLogo, XerticaOrbe, ThemeToggle, LanguageSelector
-  - `xertica-ui/assistant` — XerticaAssistant, MarkdownMessage, CodeBlock, FormattedDocument, ModernChatInput
-  - `xertica-ui/media` — VideoPlayer, AudioPlayer, FloatingMediaWrapper
-  - `xertica-ui/hooks` — useLayout, useTheme, useLanguage, useBrandColors, useAssistente, useApiKey
-  - Root `from 'xertica-ui'` remains fully supported for backward compatibility.
-- **`ImageWithFallback` added to `xertica-ui/ui`** — previously only in the root barrel; now accessible via the `/ui` subpath.
-- **Multi-entry Vite build** — `vite.config.ts` now uses `lib.entry` as an object (7 entry points). Output filenames follow `[entryName].[format].js` pattern.
-- **CLI template — FSD/FDA architecture** — The scaffolded template was restructured to follow Feature-Sliced Design + Feature-Driven Architecture:
-  - `src/app/` — BrowserRouter, XerticaProvider, AuthGuard (auth state + route definitions), AppLayout (Sidebar + children shell)
-  - `src/shared/` — `config/navigation.ts` (route registry), `lib/auth.ts` (localStorage helpers), `types/auth.ts` (User interface)
-  - `src/features/auth/ui/` — LoginContent, ForgotPasswordContent, VerifyEmailContent, ResetPasswordContent; with shared `AuthPageShell` and `SocialLoginButtons` DRY extractions
-  - `src/features/home/ui/` — HomeContent
-  - `src/features/template/ui/` — TemplateContent, FormTemplate
-  - `src/pages/` — thin page wrappers (LoginPage, HomePage, TemplatePage, ForgotPasswordPage, VerifyEmailPage, ResetPasswordPage)
-- **`templates/guidelines/Guidelines.md`** — new architecture guide documenting FSD/FDA layers, layer responsibilities, and "Adding New Routes" step-by-step.
-
-### Changed
-
-- **Template imports** — All template source files updated to use subpath imports (`xertica-ui/ui`, `xertica-ui/brand`, `xertica-ui/layout`, `xertica-ui/assistant`, `xertica-ui/hooks`) instead of the root barrel.
-- **`FormTemplate.tsx` rewritten** — Removed dependency on `@hookform/resolvers/zod`, `react-hook-form`, and `zod` (packages not included in the CLI template's `package.json`). Now uses plain React `useState` + inline validation with only `xertica-ui/ui` primitives.
-- **`tsconfig.build.json`** — `include` array updated to cover all new barrel source directories (`components/**/*`, `contexts/**/*`, `hooks/**/*`).
-- **Documentation** (`llms.txt`, `llms-full.txt`) — Added subpath import reference table and FSD/FDA layer mapping.
-
-### Fixed
-
-- **Stale compiled artifacts** — Removed `App.js`, `App.d.ts`, `main.js`, `main.d.ts` from `templates/src/app/` that were being resolved by Vite's extension priority (`.js` before `.tsx`), causing `Failed to fetch dynamically imported module` errors after the FSD restructure.
-
----
-
-## [1.10.0] — 2026-05-08
-
-### Added
-
-- **Semantic Variants** — Added `success`, `info`, and `warning` variants to components that lacked them:
-  - **Button** — now supports 9 variants: `default`, `secondary`, `outline`, `ghost`, `destructive`, `link`, `success`, `info`, `warning`.
-  - **Progress** — new `variant` prop (`default`, `success`, `info`, `warning`, `destructive`) colors both the track and the indicator.
-  - **NotificationBadge** — added `secondary`, `outline`, `success`, `info`, `warning`; standardized `default` to primary color for consistency with Badge and Button.
-  - **TimelineDot** — added `info` and `outline` variants; replaced hardcoded `rgb()` values with semantic CSS tokens (`bg-success`, `bg-warning`).
-- **DialogBody** — new sub-component for the Dialog. When used, `DialogHeader` and `DialogFooter` stay pinned while `DialogBody` scrolls independently. Exported from `xertica-ui`.
-- **Dialog height management** — `DialogContent` now has `max-h-[calc(100dvh-2rem)] overflow-hidden`. The close button (×) is pinned and never scrolls with content. `size="full"` fills the full viewport height.
-- **Header `breadcrumbSlot`** — new prop accepting any `ReactNode` rendered immediately after the breadcrumb/title area (badges, buttons, status chips, etc.).
-- **Sidebar default variant groups** — `variant="default"` now renders `navigationGroups` with labeled group headers. Each `RouteConfig` supports a `children` field (sub-routes shown in a contextual `DropdownMenu` via a `ChevronRight` button at the end of the item).
-
-### Fixed
-
-- **Search double clear icon** — `type="search"` caused browsers to inject a native clear button on top of the custom × icon. Changed to `type="text"`.
-- **CSS `@source` path** — CLI template `src/styles/index.css` had `../node_modules/xertica-ui` (one level short); corrected to `../../node_modules/xertica-ui/components`.
-- **`theme-map.css` incomplete** — `--color-success`, `--color-info`, `--color-warning` and their `foreground` variants were missing, preventing `bg-success`, `text-info`, etc. from being generated in the compiled library CSS.
-
-### Changed
-
-- **Storybook argTypes** — Multiple components had controls missing from the Storybook panel: Badge (`success`/`info`/`warning` options), Select (`size`), Avatar (`size`), Rating (`readonly` casing), Timeline (`dotVariant`), Dialog (`size` available in all stories). All corrected.
-- **LLM documentation** (`llms-full.txt`) — Updated Badge, Button, Dialog, Header, NotificationBadge, Progress, Search, Sidebar, and Timeline sections to reflect current APIs.
-
----
-
-## [1.9.0] — 2026-05-05
-
-### Added
-- **Standardized Form Sizing System** — Implemented a unified `size` prop (`sm`, `md`, `lg`) across all form-related components for perfect visual alignment in grid layouts:
-  - **Text Components** — `Input`, `SelectTrigger`, `Textarea`, `Search`, and `InputOTPSlot` now share consistent height/padding/font-size tokens.
-  - **Toggle Components** — `Checkbox`, `RadioGroupItem`, and `Switch` now feature dynamic sizing for both containers and internal indicators (check icon, dot, thumb).
-  - **Labels** — `Label` component now supports `size` to match the text size of the associated input.
-  - **Reference Guide** — Added `docs/form-sizing.md` as a comprehensive guide for the standardized sizing scale.
-- **Assistant Individual Controls** — Added granular control props to `XerticaAssistant` to toggle specific features independently:
-  - `showHistory`, `showFavorites`, `allowAudioInput`, `allowFileUpload`, `allowDocCreation`, `allowPodcastGen`, `allowResearchGen`.
-- **Header Breadcrumb Navigation** — Standardized `Header` to use breadcrumbs as the default navigation pattern:
-  - Added support for `react-router-dom` links in breadcrumbs to prevent page reloads.
-  - Configurable hierarchy levels and labels directly via props.
-
-### Changed
-- **Form Component Architecture** — Migrated form elements from legacy tokens to standardized design system tokens (`bg-background`, `border-border`) for better theme consistency.
-- **Documentation & Storybook** — Updated all 9 affected form components with new "Sizes" sections in Storybook (Stories + MDX) and enriched LLM-facing markdown documentation.
-- **Unit Testing** — Updated test suites for `Checkbox`, `RadioGroup`, `Switch`, `InputOTP`, `Label`, `Search`, `Select`, and `Textarea` to verify sizing variant classes.
-
-### Fixed
-- **Search Component** — Removed obsolete `loading` prop which was causing TypeScript errors and was redundant with the current design system patterns.
-- **SelectTrigger Sizing** — Standardized `md` height to `h-10` (40px) to match the rest of the form system.
-
----
-
-## [1.8.0] — 2026-04-27
-
-### Added
-- **VideoPlayer UI Enhancements** — Added gradient overlay on controls for improved contrast against video content:
-  - Gradient: `from-black/60 via-black/30 to-transparent` with `pt-12` spacing
-  - White progress bar with `bg-white/30` track, `bg-white` fill, and `rounded-r-sm` on filled portion
-  - White icons with `drop-shadow-md` for visibility
-  - Buttons use `text-white hover:text-white hover:bg-black/50` for proper hover states
-- **Slider Visual Fixes** — Improved progress bar alignment:
-  - Added left margin `ml-2` to track for thumb alignment
-  - Added `rounded-r-sm` to Range for filled portion
-  - Adjusted track/margins for proper visual alignment at full value
-
-### Changed
-- **Documentation** — Updated component counts across all docs:
-  - `llms.txt`: 75 → 97 components
-  - `llms-full.txt`: Added statistics table
-  - `docs/llms.md`: Added statistics section
-  - `Introduction.mdx`: Added "97 Components" badge
-- **components.json** — 75 → 89 components (added missing Media, Assistant, Pages, and Map components)
-
-### Fixed
-- **Slider Progress Bar** — Fixed visual gap where thumb doesn't align with filled bar at end position by adjusting track margins
-
----
-
-## [1.7.0] — 2026-04-23
-
-### Fixed
-- **CLI CSS Theme Import** — Corrected `@theme` → `@theme inline` in both the library's `index.css` and the generated template `src/styles/index.css`. Plain `@theme {}` was causing Tailwind v4 to resolve color tokens statically at build time using the library's defaults, preventing consumer `tokens.css` overrides from propagating into utility classes (`bg-destructive`, `bg-primary`, alert colors, etc.).
-- **Dark Mode `--primary`** — Added missing `--primary: var(--xertica-primary)` in the dark mode block of `tokens.css` (library, template, and generator). Components using `bg-primary` were not picking up the dark mode brand color.
-- **Dark Mode Chart Tokens** — Generator (`bin/generate-tokens.ts`) now includes `--chart-1` through `--chart-5` in the dark mode section for all generated `tokens.css` files.
-
-### Added
-- **CLI `update` command** — `npx xertica-ui@latest update` prompts the user to select a new color theme and overwrites `src/styles/xertica/tokens.css` with the newly generated tokens, preserving all other project files.
-- **Template `@theme inline` mapping** — Generated `src/styles/index.css` now includes a complete `@theme inline {}` block mapping all tokens (sidebar, charts, gradients, brand, radii) to CSS variable aliases, ensuring full theme coverage for consumer projects.
-- **Documentation** — `docs/getting-started.md` updated with CLI `update` command reference and a new "CSS Setup (Critical)" section explaining the `@theme inline` requirement.
-
----
-
-## [1.6.0] — 2026-04-20
-
-### Added
-- **`docs/llms.md`** — Master LLM/AI-agent entrypoint index with full component catalog, token quick reference, and reading order guide.
-- **`docs/layout.md`** — Complete `LayoutContext` and `useLayout()` API reference.
-- **`docs/components/route-map.md`** — New documentation for `RouteMap` component.
-- **`docs/components/use-mobile.md`** — New documentation for `useMobile` / `useIsMobile` hooks.
-- **`Header`** — New props: `user` (profile with avatar, name, email, and dropdown menu items), `actions` (custom icon action buttons), `showSettings` / `onSettingsClick`, `showLogout` / `onLogoutClick`. Fixed render order: Language → Theme → Actions → Settings → User → Logout.
-- **`Sidebar`** — New `width` prop (`expandedWidth: number`) for configuring the expanded sidebar pixel width. Width is now read and stored via `LayoutContext.sidebarWidth`.
-
-### Changed
-- **Documentation** — All 61 component docs, 5 pattern docs, and 6 root docs fully rewritten in English with standardized structure (Overview, When to Use, Anatomy, Props table, Examples, AI Rules, Related Components).
-- **JSDoc** — All Portuguese JSDoc comments in `components/ui/` translated to English and enriched with accurate `@ai-rules`.
-- **`README.md`** — Complete rewrite in English, restructured for npm page quality (quick start, install guide, component catalog, token reference, AI agent entrypoint, troubleshooting).
-- **`package.json`** — Version bumped to `1.6.0`. Description translated to English.
-
-### Fixed
-- **`docs/components/page-header.md`** — Was documenting a wrong API (`title/description/actions`). Now correctly documents the real API: `breadcrumbs[]`, `showLanguageSelector`, `rightContent`, `PageHeaderHeading`, `PageHeaderDescription`.
-- **`docs/components/stepper.md`** — Was documenting a `steps[]` array prop. Now correctly documents the composable `<Stepper currentStep> + <Step step label>` API (1-indexed).
-- **`docs/components/empty.md`** — Was documenting single-prop component. Now correctly documents the composable sub-component pattern: `Empty > EmptyIcon > EmptyTitle > EmptyDescription > EmptyAction`.
-- **`docs/components/stats-card.md`** — `trend` was documented as a string. Now correctly documented as `{ value: number; label?: string }`.
-- **`docs/components/chart.md`** — Was documenting raw Recharts usage. Now correctly documents the `ChartContainer + ChartConfig + var(--color-*)` pattern.
-
----
-
-## [1.5.2] — 2026-04-15
-
-### Fixed
-- Resolved regression where modal components (Dialog/AlertDialog) failed to render in projects initialized via the CLI.
-- Implemented robust CSS integration using Tailwind v4 theme mappings.
-- Ensured Radix UI portals correctly inherit theme variables.
-
----
-
-## [1.5.1] — 2026-04-14
-
-### Changed
-- Sidebar: Added `assistente` variant with fixed areas, searchable navigation, and grouped navigation structures.
-- Template page updated to demonstrate the assistant sidebar variant.
-
----
-
-## [1.5.0] — 2026-04-13
-
-### Added
-- `Sidebar` — `width` / `expandedWidth` prop for configurable expanded sidebar width.
-- `LayoutContext` — `sidebarWidth` and `setSidebarWidth` for global sidebar width management.
-- `Header` — User profile section with avatar, dropdown menu, settings button, and logout button.
-- `StatsCard` — KPI metric card component.
-- `Timeline` — Chronological event list with dot variants.
-- `TreeView` — Hierarchical tree navigation.
-- `Rating` — Star-based rating input.
-- `FileUpload` — Drag-and-drop file input.
-- `Search` — Pre-built search input with icon and clear button.
-- `NotificationBadge` — Dot/count badge overlay.
-- `RouteMap` — Google Maps route display and direction calculation.
-- `Stepper` — Multi-step progress indicator.
-- `Map` — Advanced Google Maps integration with markers, circles, polygons, and layers.
-- `XerticaAssistant` — Embedded Gemini AI assistant panel.
+# Changelog
+
+All notable changes to `xertica-ui` will be documented in this file.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [2.1.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.