xertica-ui 2.1.9 → 2.1.11

package/CHANGELOG.md

@@ -7,10 +7,102 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
-## [2.1.9] — 2026-05-20
+## [Unreleased]
+
+### Added
+
+- **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 JSON files for the selected languages into `src/locales/` (no orphan locales)
+  - Generates `src/i18n.ts` with imports/resources 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 JSONs, 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`).
+
+### 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.
+
+---
+
+## [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`.
@@ -275,6 +367,7 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [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).
@@ -287,11 +380,13 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   - 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.
 
@@ -300,6 +395,7 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [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
@@ -311,6 +407,7 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   - 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
@@ -319,6 +416,7 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - **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
 
 ---
@@ -326,11 +424,13 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [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.
@@ -340,6 +440,7 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [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.
@@ -348,12 +449,14 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - **`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`.
@@ -365,6 +468,7 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [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.
@@ -374,6 +478,7 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [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.
 
@@ -382,6 +487,7 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [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.

package/README.md

@@ -2,7 +2,7 @@
 
 > **Enterprise-grade React design system** built on Tailwind CSS v4, Radix UI, and Lucide Icons — with a robust AI-first documentation layer for precise LLM-driven composition and autonomous agent interaction.
 
-[![npm version](https://img.shields.io/badge/npm-2.1.4-blue)](https://www.npmjs.com/package/xertica-ui)
+[![npm version](https://img.shields.io/badge/npm-2.1.11-blue)](https://www.npmjs.com/package/xertica-ui)
 [![license](https://img.shields.io/badge/license-proprietary-red)](./LICENSE)
 
 ---
@@ -11,12 +11,12 @@
 
 Xertica UI is specifically designed to be consumed by AI Agents (LLMs, code assistants, autonomous agents). We provide dedicated entry points for AI context:
 
-| File | Purpose |
-|---|---|
-| [`llms.txt`](./llms.txt) | Standard index for AI crawlers and context-aware agents. |
+| File                                     | Purpose                                                                                     |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------- |
+| [`llms.txt`](./llms.txt)                 | Standard index for AI crawlers and context-aware agents.                                    |
 | [`llms-compact.txt`](./llms-compact.txt) | **Compact documentation** of all components in a single file for LLMs with limited context. |
-| [`llms-full.txt`](./llms-full.txt) | **Complete documentation** of all components in a single file for LLMs with large-context. |
-| `docs/llms.md` | Master index for agents to navigate the documentation folder. |
+| [`llms-full.txt`](./llms-full.txt)       | **Complete documentation** of all components in a single file for LLMs with large-context.  |
+| `docs/llms.md`                           | Master index for agents to navigate the documentation folder.                               |
 
 ---
 
@@ -30,7 +30,39 @@ cd my-app
 npm run dev
 ```
 
-The CLI scaffolds a complete Vite + React + TypeScript project with Portuguese UI localization and English AI-ready documentation.
+During `init`, the CLI walks you through:
+
+| Prompt | Choices |
+|---|---|
+| Pages to include | Login, Home, Template (multi-select) |
+| **Languages to support** | Português (BR), English, Español — select **1, 2, or 3** |
+| Default color theme | Xertica, Slate, Blue, Violet, Rose, Emerald, … |
+| Install dependencies automatically | yes / no |
+
+The CLI generates a tailored project with:
+
+- Only the locale JSON files for the languages you picked (no orphan files)
+- `src/i18n.ts` with imports + `resources` for exactly those languages
+- `src/app/App.tsx` with the `availableLanguages` prop on `<XerticaProvider>` (omitted when all 3 defaults are selected)
+- A persisted selection in `src/locales/.languages.json` so the `update` command can preserve it
+
+### Monolingual mode (transparent)
+
+If you select only one language, the project becomes **monolingual** — the `<LanguageSelector>` automatically renders `null` (there is nothing to switch to). A header comment in the generated `App.tsx` documents this behavior. To force the selector visible anyway, pass `<LanguageSelector showWhenMonolingual />`.
+
+### Updating languages later
+
+```bash
+npx xertica-ui update      # then choose "Languages"
+```
+
+The flow shows your current selection, lets you toggle languages, and on confirmation:
+- copies any newly-added locale JSON from `node_modules/xertica-ui/templates/src/locales/`
+- removes JSONs of unselected languages
+- regenerates `src/i18n.ts` and `src/app/App.tsx`
+- updates `src/locales/.languages.json`
+
+The `update` → **Project files** flow also reads `.languages.json` and preserves your selection — overwrites of `App.tsx` and `i18n.ts` won't reset your languages to defaults.
 
 > **Note:** Always use `@latest` with npx. Without it, npx may execute a locally cached older version instead of fetching the latest from the registry.
 
@@ -64,7 +96,7 @@ export function Example() {
 }
 ```
 
-**3. Optionally wrap your app** with `XerticaProvider` when you want coordinated theme, layout, assistant, maps, tooltip, API-key, and toast services:
+**3. Optionally wrap your app** with `XerticaProvider` when you want coordinated theme, layout, assistant, maps, tooltip, API-key, language, and toast services:
 
 ```tsx
 import { XerticaProvider } from 'xertica-ui/brand';
@@ -78,6 +110,26 @@ function App() {
 }
 ```
 
+**Configuring languages at runtime** — `<XerticaProvider>` accepts `availableLanguages` to override the default set. When only one language is configured, the `LanguageSelector` auto-hides:
+
+```tsx
+import { XerticaProvider, DEFAULT_LANGUAGES } from 'xertica-ui';
+import fr from './locales/fr.json';
+
+// Monolingual English (no language picker)
+<XerticaProvider availableLanguages={[{ code: 'en', label: 'English' }]}>
+
+// Defaults + a custom locale (bundle auto-registered with i18next)
+<XerticaProvider
+  availableLanguages={[
+    ...DEFAULT_LANGUAGES,
+    { code: 'fr', label: 'Français', shortLabel: 'FR', resources: fr },
+  ]}
+>
+```
+
+See [`docs/i18n.md`](./docs/i18n.md) for the full `LanguageDefinition` and `registerLanguageResource` API.
+
 ---
 
 ## 📂 Subpath Imports (FSD/FDA)
@@ -85,15 +137,15 @@ function App() {
 Xertica UI v2 exposes **granular subpath entries** — import only what your layer needs without loading the entire library:
 
 ```tsx
-import { Button, Card, Input }       from 'xertica-ui/ui';        // shared/ui — primitives
-import { QuickActionCard }           from 'xertica-ui/blocks';    // composed blocks
-import { Sidebar, Header }           from 'xertica-ui/layout';    // layout shell
-import { XerticaProvider }           from 'xertica-ui/brand';     // app-level — providers & brand
-import { XerticaAssistant }          from 'xertica-ui/assistant'; // feature — AI assistant
-import { VideoPlayer, AudioPlayer }  from 'xertica-ui/media';     // feature — media players
+import { Button, Card, Input } from 'xertica-ui/ui'; // shared/ui — primitives
+import { QuickActionCard } from 'xertica-ui/blocks'; // composed blocks
+import { Sidebar, Header } from 'xertica-ui/layout'; // layout shell
+import { XerticaProvider } from 'xertica-ui/brand'; // app-level — providers & brand
+import { XerticaAssistant } from 'xertica-ui/assistant'; // feature — AI assistant
+import { VideoPlayer, AudioPlayer } from 'xertica-ui/media'; // feature — media players
 import { useLayout, useOptionalLayout, useTheme } from 'xertica-ui/hooks'; // shared/lib — hooks & contexts
-import { TemplatePage }              from 'xertica-ui/pages';     // optional page templates
-import 'xertica-ui/style.css';                                     // styles — import once at root
+import { TemplatePage } from 'xertica-ui/pages'; // optional page templates
+import 'xertica-ui/style.css'; // styles — import once at root
 ```
 
 The root `from 'xertica-ui'` barrel remains available for full backward compatibility.
@@ -115,6 +167,7 @@ Components with unavoidable external configuration, such as Google Maps, should
 Xertica UI features an autonomous layout system managed by `LayoutContext`.
 
 ### Mandatory Page Structure
+
 Every page **must** use the `<PageHeader>` component for its title and primary actions. Never use raw `h1` or `div` for headers.
 
 ```tsx
@@ -127,16 +180,16 @@ export function MyPage() {
         <PageHeaderHeading>Dashboard</PageHeaderHeading>
         <Button>Action</Button>
       </PageHeader>
-      <div className="p-6">
-        {/* Page Content */}
-      </div>
+      <div className="p-6">{/* Page Content */}</div>
     </>
   );
 }
 ```
 
 ### `useLayout()` Hook
+
 Access the sidebar state, width, and toggle functions anywhere in the component tree:
+
 ```tsx
 import { useLayout } from 'xertica-ui/hooks';
 
@@ -167,59 +220,97 @@ src/
     types/          ← auth.ts (User interface)
   features/
     auth/ui/        ← LoginContent, ForgotPasswordContent, VerifyEmailContent, ResetPasswordContent
-    home/ui/        ← HomeContent
+    home/
+      data/mock.ts  ← typed fetch + factory functions like getMockRichSuggestions()
+      hooks/        ← useFeatureCards() — language-aware queryKey
+      ui/           ← HomeContent
     template/ui/    ← TemplateContent, FormTemplate
-  pages/            ← thin wrappers: LoginPage, HomePage, TemplatePage, …
+    assistant/      ← AssistantConfig + useAssistantConfig() (always installed, AppLayout depends on it)
+  pages/            ← thin wrappers: LoginPage, HomePage, TemplatePage, AssistantPage, …
   styles/           ← index.css, xertica/tokens.css
+  i18n.ts           ← generated by CLI — imports/resources for selected languages only
+  locales/
+    pt-BR.json
+    en.json         ← only files for the languages you selected
+    es.json
+    .languages.json ← persisted selection (read by `npx xertica-ui update`)
 ```
 
-Each feature only imports from `shared/` or its own domain. Pages only compose features. See `templates/guidelines/Guidelines.md` for the full architecture guide.
+Each feature only imports from `shared/` or its own domain. Pages only compose features. Server-state hooks (e.g. `useFeatureCards`) include the active **language** in their `queryKey` so locale switching invalidates and refetches automatically. See `templates/guidelines/Guidelines.md` for the full architecture guide.
 
 ---
 
 ## 🧩 Component Catalog (100+ Components)
 
 ### Layout & Navigation
+
 `Header` · `Sidebar` · `PageHeader` · `Breadcrumb` · `NavigationMenu` · `Tabs` · `Pagination` · `Accordion` · `Collapsible`
 
 ### Core Surfaces
+
 `Card` · `Separator` · `ScrollArea` · `AspectRatio` · `Resizable` · `Skeleton` · `Empty`
 
 ### Forms & Inputs
+
 `Form` · `Input` · `Textarea` · `RichTextEditor` · `Label` · `Checkbox` · `RadioGroup` · `Switch` · `Select` · `Slider` · `Calendar` · `InputOTP` · `FileUpload` · `Search`
 
 ### Actions & Data
+
 `Button` · `Toggle` · `ToggleGroup` · `Rating` · `Table` · `Badge` · `Avatar` · `Progress` · `StatsCard` · `Timeline` · `Stepper` · `TreeView` · `NotificationBadge` · `Chart`
 
 ### Overlays & Feedback
+
 `Dialog` · `AlertDialog` · `Sheet` · `Drawer` · `Popover` · `HoverCard` · `Tooltip` · `Alert` · `Sonner (Toast)` · `Command`
 
-### Composed Blocks
-`FeatureCard` · `ActivityCard` · `ProfileCard` · `ProjectCard` · `QuickActionCard` · `NotificationCard`
+### Composed Blocks (with matching skeleton variants)
+
+| Card | Skeleton |
+|---|---|
+| `FeatureCard` | `FeatureCardSkeleton` |
+| `ActivityCard` | `ActivityCardSkeleton` |
+| `ProfileCard` | `ProfileCardSkeleton` |
+| `ProjectCard` | `ProjectCardSkeleton` |
+| `QuickActionCard` | `QuickActionCardSkeleton` |
+| `NotificationCard` | `NotificationCardSkeleton` |
+| `StatsCard` (in `xertica-ui/ui`) | `StatsCardSkeleton` |
+
+Each skeleton mirrors its card's visual layout with pulsing placeholders for loading states:
+
+```tsx
+{isLoading
+  ? <ActivityCardSkeleton rows={5} />
+  : <ActivityCard items={items} />}
+```
 
 ---
 
 ## 🌟 Specialized Modules
 
 ### 🤖 AI Assistant
-Integrated AI chat panel with workspace support.
-- `XerticaAssistant` · `MarkdownMessage` · `CodeBlock` · `AssistantChart`
+
+Integrated AI chat panel with workspace support. Use `demoMode={true}` for mock responses without an API key; pass `demoMode={false}` and a `geminiApiKey` (via `<XerticaProvider apiKey="...">`) for real Gemini integration.
+
+- `XerticaAssistant` · `MarkdownMessage` · `CodeBlock` · `AssistantChart` · `ModernChatInput` · `FormattedDocument`
 
 ### 🗺️ Maps & Geolocation
+
 First-class Google Maps integration.
+
 - `Map` · `RouteMap` · `SimpleMap` · `GoogleMapsLoader`
 
 ### 🎙️ Media
+
 - `AudioPlayer` · `VideoPlayer` · `FloatingMediaWrapper`
 
 ### 📄 Pages
-- `LoginPage` · `HomePage` · `TemplatePage` · `ForgotPasswordPage` · `ResetPasswordPage` · `VerifyEmailPage`
+
+- `LoginPage` · `HomePage` · `TemplatePage` · `AssistantPage` · `ForgotPasswordPage` · `ResetPasswordPage` · `VerifyEmailPage`
 
 ### 🧱 Blocks
-High-level dashboard and product patterns exported from `xertica-ui/blocks`.
-- `FeatureCard` · `ActivityCard` · `ProfileCard` · `ProjectCard` · `QuickActionCard` · `NotificationCard`
 
-The CLI template now includes a small fixed version badge so generated projects can visually identify which `xertica-ui` package version they are using.
+High-level dashboard and product patterns exported from `xertica-ui/blocks` (also re-exported from the root barrel). Every card ships with a matching `*Skeleton` loading-state companion — see the table in **Composed Blocks** above.
+
+The CLI template includes a small fixed version badge so generated projects can visually identify which `xertica-ui` package version they are using.
 
 ---
 
@@ -248,38 +339,44 @@ Border:         border-border
 
 ## 🌍 Localization
 
-- **UI Components**: Fully localized in **Portuguese (pt-BR)** for end-users.
+Xertica UI is fully internationalized via **`i18next`** + **`react-i18next`**.
+
+- **UI Components**: Translated out-of-the-box in **Portuguese (pt-BR)**, **English**, and **Español**. Every component uses `useTranslation()` — no hardcoded strings.
+- **Runtime extensibility**: Add custom locales (e.g. `fr`, `ja`, `de`) at runtime via `<XerticaProvider availableLanguages={[...]}>` — no source-file edits required.
+- **Monolingual mode**: Configure a single language to make the `LanguageSelector` auto-hide.
+- **Language-aware React Query**: Hooks include the active language in their `queryKey` so mock/API responses translated via `i18n.t()` refetch automatically when the user switches language. No page reload required.
 - **Documentation/Code**: Strictly maintained in **English** for AI Agent compatibility and global developer standard.
 
+See [`docs/i18n.md`](./docs/i18n.md) for setup, runtime configuration, and adding custom locales.
+
 ---
 
 ## 💻 Tech Stack
 
-| Technology | Version |
-|---|---|
-| React | 18.3 |
-| TypeScript | 5.7 |
-| Tailwind CSS | 4.0 |
-| Vite | 6.0 |
-| Radix UI | Latest |
-| Lucide React | 0.469+ |
-| Vitest | 4.1 |
+| Technology   | Version |
+| ------------ | ------- |
+| React        | 18.3    |
+| TypeScript   | 5.7     |
+| Tailwind CSS | 4.0     |
+| Vite         | 6.0     |
+| Radix UI     | Latest  |
+| Lucide React | 0.469+  |
+| Vitest       | 4.1     |
 
 ---
 
 ## 📜 Scripts
 
-| Command | Description |
-|---|---|
-| `npm run dev` | Start development server |
-| `npm run build` | Production bundle |
-| `npm run storybook` | Launch component library documentation |
-| `npm run test` | Run unit tests via Vitest |
-| `npm run type-check` | TypeScript validation |
+| Command              | Description                            |
+| -------------------- | -------------------------------------- |
+| `npm run dev`        | Start development server               |
+| `npm run build`      | Production bundle                      |
+| `npm run storybook`  | Launch component library documentation |
+| `npm run test`       | Run unit tests via Vitest              |
+| `npm run type-check` | TypeScript validation                  |
 
 ---
 
 ## ⚖️ License
 
 Proprietary — Xertica.ai Team.
-

package/assets/xertica-logo.svg

@@ -1,38 +1,38 @@
-<svg
-  fill="none"
-  preserveAspectRatio="xMidYMid meet"
-  viewBox="0 0 1543 289"
-  xmlns="http://www.w3.org/2000/svg"
->
-  <g id="Xertica.ai">
-    <path d="M1352.82 239.808V285.425H1304.73V239.808H1352.82Z" fill="#00BEFF" />
-    <path d="M814.8 284.848H766.711V77.4971H814.8V284.848Z" fill="#00BEFF" />
-    <path d="M1543 284.438H1514.2V160.28H1543V284.438Z" fill="#00BEFF" />
-    <path 
-      clip-rule="evenodd"
-      d="M1432.83 157.796C1446.98 157.796 1459.14 162.515 1468.58 170.709V160.28H1497.38V284.438H1468.58V274.01C1459.14 282.451 1446.98 286.921 1432.83 286.921C1395.1 286.921 1368.29 260.352 1368.29 222.359C1368.29 184.616 1395.1 157.796 1432.83 157.796ZM1432.83 183.778C1410.79 183.778 1396.27 199.061 1396.27 222.359C1396.27 245.658 1410.79 260.94 1432.83 260.94C1454.63 260.94 1468.9 245.658 1468.9 222.359C1468.9 199.06 1454.63 183.778 1432.83 183.778Z"
-      fill="#00BEFF"
-      fill-rule="evenodd"
-    />
-    <path d="M947.87 73.3516C1002.88 73.3516 1044.42 107.647 1053.57 159.234H1004.68C997.221 132.988 976.34 117.308 947.87 117.308C911.387 117.308 887.337 142.612 887.337 181.176C887.337 219.739 911.387 245.036 947.87 245.036C976.34 245.036 997.221 229.356 1004.68 203.109H1053.57C1044.47 254.701 1003.26 289 947.87 289C884.853 289 840.078 244.626 840.078 181.176C840.078 118.142 884.854 73.3516 947.87 73.3516Z" fill="#00BEFF" />
-    <path d="M88.4971 39.8242L157.353 142.191L83.5371 251.524L60.9277 284.854H0L96.3154 142.191L5.37695 7H66.3047L88.4971 39.8242Z" fill="#00BEFF" />
-    <path d="M254.314 284.855H193.387L151.914 223.71L182.548 178.551L254.314 284.855Z" fill="#00BEFF" />
-    <path 
-      clip-rule="evenodd"
-      d="M1179.14 73.3477C1202.77 73.3477 1223.08 81.2286 1238.84 94.9121V77.4971H1286.94V284.847H1238.84V267.431C1223.09 281.528 1202.77 288.992 1179.14 288.992C1116.12 288.992 1071.35 244.622 1071.35 181.172C1071.35 118.139 1116.12 73.3478 1179.14 73.3477ZM1179.14 117.308C1142.66 117.308 1118.61 142.604 1118.61 181.172C1118.61 219.739 1142.66 245.035 1179.14 245.035C1215.21 245.035 1238.84 219.739 1238.84 181.172C1238.84 142.605 1215.21 117.308 1179.14 117.308Z"
-      fill="#00BEFF"
-      fill-rule="evenodd"
-    />
-    <path d="M1543 145.383H1514.2V118.067H1543V145.383Z" fill="#00BEFF" />
-    <path d="M672.466 77.501H736.31V121.457H672.466V211.448C672.466 230.939 682.415 240.891 702.313 240.891H736.309V284.852H698.999C649.246 284.851 625.203 259.968 625.203 211.449V7H672.466V77.501Z" fill="#00BEFF" />
-    <path d="M814.8 52.6172H766.711V7H814.8V52.6172Z" fill="#00BEFF" />
-    <path 
-      clip-rule="evenodd"
-      d="M354.069 73.3516C417.086 73.3517 461.864 118.143 461.864 181.176C461.864 187.396 461.031 193.615 460.204 199.422H295.197C301.829 228.864 323.392 246.696 354.069 246.696C372.724 246.696 389.309 241.721 399.675 226.376H452.742C441.132 265.774 400.501 288.996 354.069 288.996C291.053 288.996 246.274 244.626 246.273 181.176C246.273 118.142 291.053 73.3516 354.069 73.3516ZM354.068 115.65C325.044 115.65 303.902 131.826 296.44 158.78H410.863C403.819 131.826 382.672 115.65 354.068 115.65Z"
-      fill="#00BEFF"
-      fill-rule="evenodd"
-    />
-    <path d="M596.957 121.453H562.962C543.064 121.453 533.114 131.409 533.114 150.899V284.847H485.852V150.899C485.852 102.38 509.894 77.4972 559.647 77.4971H596.957V121.453Z" fill="#00BEFF" />
-    <path d="M182.552 98.6992L151.922 53.3906L188.014 0H248.941L182.552 98.6992Z" fill="#00BEFF" />
-  </g>
+<svg
+  fill="none"
+  preserveAspectRatio="xMidYMid meet"
+  viewBox="0 0 1543 289"
+  xmlns="http://www.w3.org/2000/svg"
+>
+  <g id="Xertica.ai">
+    <path d="M1352.82 239.808V285.425H1304.73V239.808H1352.82Z" fill="#00BEFF" />
+    <path d="M814.8 284.848H766.711V77.4971H814.8V284.848Z" fill="#00BEFF" />
+    <path d="M1543 284.438H1514.2V160.28H1543V284.438Z" fill="#00BEFF" />
+    <path 
+      clip-rule="evenodd"
+      d="M1432.83 157.796C1446.98 157.796 1459.14 162.515 1468.58 170.709V160.28H1497.38V284.438H1468.58V274.01C1459.14 282.451 1446.98 286.921 1432.83 286.921C1395.1 286.921 1368.29 260.352 1368.29 222.359C1368.29 184.616 1395.1 157.796 1432.83 157.796ZM1432.83 183.778C1410.79 183.778 1396.27 199.061 1396.27 222.359C1396.27 245.658 1410.79 260.94 1432.83 260.94C1454.63 260.94 1468.9 245.658 1468.9 222.359C1468.9 199.06 1454.63 183.778 1432.83 183.778Z"
+      fill="#00BEFF"
+      fill-rule="evenodd"
+    />
+    <path d="M947.87 73.3516C1002.88 73.3516 1044.42 107.647 1053.57 159.234H1004.68C997.221 132.988 976.34 117.308 947.87 117.308C911.387 117.308 887.337 142.612 887.337 181.176C887.337 219.739 911.387 245.036 947.87 245.036C976.34 245.036 997.221 229.356 1004.68 203.109H1053.57C1044.47 254.701 1003.26 289 947.87 289C884.853 289 840.078 244.626 840.078 181.176C840.078 118.142 884.854 73.3516 947.87 73.3516Z" fill="#00BEFF" />
+    <path d="M88.4971 39.8242L157.353 142.191L83.5371 251.524L60.9277 284.854H0L96.3154 142.191L5.37695 7H66.3047L88.4971 39.8242Z" fill="#00BEFF" />
+    <path d="M254.314 284.855H193.387L151.914 223.71L182.548 178.551L254.314 284.855Z" fill="#00BEFF" />
+    <path 
+      clip-rule="evenodd"
+      d="M1179.14 73.3477C1202.77 73.3477 1223.08 81.2286 1238.84 94.9121V77.4971H1286.94V284.847H1238.84V267.431C1223.09 281.528 1202.77 288.992 1179.14 288.992C1116.12 288.992 1071.35 244.622 1071.35 181.172C1071.35 118.139 1116.12 73.3478 1179.14 73.3477ZM1179.14 117.308C1142.66 117.308 1118.61 142.604 1118.61 181.172C1118.61 219.739 1142.66 245.035 1179.14 245.035C1215.21 245.035 1238.84 219.739 1238.84 181.172C1238.84 142.605 1215.21 117.308 1179.14 117.308Z"
+      fill="#00BEFF"
+      fill-rule="evenodd"
+    />
+    <path d="M1543 145.383H1514.2V118.067H1543V145.383Z" fill="#00BEFF" />
+    <path d="M672.466 77.501H736.31V121.457H672.466V211.448C672.466 230.939 682.415 240.891 702.313 240.891H736.309V284.852H698.999C649.246 284.851 625.203 259.968 625.203 211.449V7H672.466V77.501Z" fill="#00BEFF" />
+    <path d="M814.8 52.6172H766.711V7H814.8V52.6172Z" fill="#00BEFF" />
+    <path 
+      clip-rule="evenodd"
+      d="M354.069 73.3516C417.086 73.3517 461.864 118.143 461.864 181.176C461.864 187.396 461.031 193.615 460.204 199.422H295.197C301.829 228.864 323.392 246.696 354.069 246.696C372.724 246.696 389.309 241.721 399.675 226.376H452.742C441.132 265.774 400.501 288.996 354.069 288.996C291.053 288.996 246.274 244.626 246.273 181.176C246.273 118.142 291.053 73.3516 354.069 73.3516ZM354.068 115.65C325.044 115.65 303.902 131.826 296.44 158.78H410.863C403.819 131.826 382.672 115.65 354.068 115.65Z"
+      fill="#00BEFF"
+      fill-rule="evenodd"
+    />
+    <path d="M596.957 121.453H562.962C543.064 121.453 533.114 131.409 533.114 150.899V284.847H485.852V150.899C485.852 102.38 509.894 77.4972 559.647 77.4971H596.957V121.453Z" fill="#00BEFF" />
+    <path d="M182.552 98.6992L151.922 53.3906L188.014 0H248.941L182.552 98.6992Z" fill="#00BEFF" />
+  </g>
 </svg>