xertica-ui 2.5.2 → 2.6.0

package/docs/components/stats-card.md

@@ -1,138 +1,138 @@
-# StatsCard
-
-## Overview
-
-A pre-built KPI (Key Performance Indicator) card for dashboard overview pages. Renders a metric title, a large value, an optional trend indicator with automatic up/down/neutral icon, and an optional icon.
-
-Built on top of `<Card>`. Use it for dashboard stat widgets where a consistent metric display is needed.
-
----
-
-## When to Use
-
-- Dashboard overview pages to show summary metrics (revenue, users, conversion)
-- KPI widgets that need to show value + trend direction
-
-## When NOT to Use
-
-- For arbitrary content — use `<Card>` directly.
-- When you need to heavily customize layout — compose from `<Card>` primitives instead.
-
----
-
-## Props
-
-| Prop          | Type                                | Required | Description                                                                                               |
-| ------------- | ----------------------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
-| `title`       | `string`                            | **Yes**  | Metric label (short)                                                                                      |
-| `value`       | `string \| number`                  | **Yes**  | The displayed metric value                                                                                |
-| `description` | `string`                            | No       | Additional supplementary text below the value                                                             |
-| `trend`       | `{ value: number; label?: string }` | No       | Trend object. `value` is a number (positive = up, negative = down). `label` overrides `description` text. |
-| `icon`        | `ReactNode`                         | No       | Icon from `lucide-react`                                                                                  |
-| `iconColor`   | `string`                            | No       | Tailwind class for the icon text/foreground color (defaults to `text-muted-foreground`)                   |
-| `iconBg`      | `string`                            | No       | Tailwind class for the icon background color (defaults to `bg-muted`)                                     |
-| `className`   | `string`                            | No       | Additional CSS classes |
-
-### trend
-
-The `trend` prop controls the automatic trend icon and color:
-
-- `trend.value > 0` → shows `TrendingUp` icon in green
-- `trend.value < 0` → shows `TrendingDown` icon in red (destructive)
-- `trend.value === 0` → shows `Minus` icon in muted
-
-The numeric value is displayed as an absolute percentage: `Math.abs(trend.value)%`.
-
----
-
-## Examples
-
-### Basic KPI Card
-
-```tsx
-import { StatsCard } from 'xertica-ui/ui';
-import { DollarSign } from 'lucide-react';
-
-<StatsCard
-  title="Total Revenue"
-  value="$45,231.89"
-  trend={{ value: 20.1, label: 'from last month' }}
-  icon={<DollarSign className="size-5" />}
-/>;
-```
-
-### Custom Icon Colors
-
-```tsx
-import { StatsCard } from 'xertica-ui/ui';
-import { Users } from 'lucide-react';
-
-<StatsCard
-  title="Active Users"
-  value="2,350"
-  trend={{ value: 8.2, label: 'new this week' }}
-  icon={<Users className="size-5" />}
-  iconBg="bg-primary/10"
-  iconColor="text-primary"
-/>;
-```
-
-### Negative Trend
-
-```tsx
-<StatsCard
-  title="Churn Rate"
-  value="3.2%"
-  trend={{ value: -0.8, label: 'vs last quarter' }}
-  icon={<TrendingDown className="size-5" />}
-/>
-```
-
-### Stats Grid (4 columns)
-
-```tsx
-<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
-  <StatsCard
-    title="Revenue"
-    value="$45,231"
-    trend={{ value: 20.1, label: 'from last month' }}
-    icon={<DollarSign className="size-5" />}
-  />
-  <StatsCard
-    title="Active Users"
-    value="2,350"
-    trend={{ value: 8.2, label: 'new this week' }}
-    icon={<Users className="size-5" />}
-  />
-  <StatsCard
-    title="Conversion"
-    value="3.6%"
-    trend={{ value: -0.4, label: 'vs last month' }}
-    icon={<Activity className="size-5" />}
-  />
-  <StatsCard
-    title="Avg. Ticket"
-    value="$89.40"
-    description="All time average"
-    icon={<ShoppingCart className="size-5" />}
-  />
-</div>
-```
-
----
-
-## AI Rules
-
-- `trend.value` is a **numeric percentage** (e.g., `20.1` for +20.1%) — the component displays `Math.abs(value)%` automatically.
-- Do NOT pre-format the trend value as a string — pass the raw number.
-- `value` IS pre-formatted as a display string: `"$45,231"`, `"3.6%"`, `"2,350"`.
-- Icons render inside a rounded background. By default, background is `bg-muted` and color is `text-muted-foreground`, but they can be customized using `iconBg` and `iconColor` props. Use `size-5` for the icon.
-- Always use in a 4-column responsive grid for dashboard overviews.
-- `trend.label` takes precedence over `description` for below-value text.
-
----
-
-## Related Components
-
-- [`Card`](./card.md) — The underlying primitive
-- [Dashboard Pattern](../patterns/dashboard.md) — Standard usage context
+# StatsCard
+
+## Overview
+
+A pre-built KPI (Key Performance Indicator) card for dashboard overview pages. Renders a metric title, a large value, an optional trend indicator with automatic up/down/neutral icon, and an optional icon.
+
+Built on top of `<Card>`. Use it for dashboard stat widgets where a consistent metric display is needed.
+
+---
+
+## When to Use
+
+- Dashboard overview pages to show summary metrics (revenue, users, conversion)
+- KPI widgets that need to show value + trend direction
+
+## When NOT to Use
+
+- For arbitrary content — use `<Card>` directly.
+- When you need to heavily customize layout — compose from `<Card>` primitives instead.
+
+---
+
+## Props
+
+| Prop          | Type                                | Required | Description                                                                                               |
+| ------------- | ----------------------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
+| `title`       | `string`                            | **Yes**  | Metric label (short)                                                                                      |
+| `value`       | `string \| number`                  | **Yes**  | The displayed metric value                                                                                |
+| `description` | `string`                            | No       | Additional supplementary text below the value                                                             |
+| `trend`       | `{ value: number; label?: string }` | No       | Trend object. `value` is a number (positive = up, negative = down). `label` overrides `description` text. |
+| `icon`        | `ReactNode`                         | No       | Icon from `lucide-react`                                                                                  |
+| `iconColor`   | `string`                            | No       | Tailwind class for the icon text/foreground color (defaults to `text-muted-foreground`)                   |
+| `iconBg`      | `string`                            | No       | Tailwind class for the icon background color (defaults to `bg-muted`)                                     |
+| `className`   | `string`                            | No       | Additional CSS classes |
+
+### trend
+
+The `trend` prop controls the automatic trend icon and color:
+
+- `trend.value > 0` → shows `TrendingUp` icon in green
+- `trend.value < 0` → shows `TrendingDown` icon in red (destructive)
+- `trend.value === 0` → shows `Minus` icon in muted
+
+The numeric value is displayed as an absolute percentage: `Math.abs(trend.value)%`.
+
+---
+
+## Examples
+
+### Basic KPI Card
+
+```tsx
+import { StatsCard } from 'xertica-ui/ui';
+import { DollarSign } from 'lucide-react';
+
+<StatsCard
+  title="Total Revenue"
+  value="$45,231.89"
+  trend={{ value: 20.1, label: 'from last month' }}
+  icon={<DollarSign className="size-5" />}
+/>;
+```
+
+### Custom Icon Colors
+
+```tsx
+import { StatsCard } from 'xertica-ui/ui';
+import { Users } from 'lucide-react';
+
+<StatsCard
+  title="Active Users"
+  value="2,350"
+  trend={{ value: 8.2, label: 'new this week' }}
+  icon={<Users className="size-5" />}
+  iconBg="bg-primary/10"
+  iconColor="text-primary"
+/>;
+```
+
+### Negative Trend
+
+```tsx
+<StatsCard
+  title="Churn Rate"
+  value="3.2%"
+  trend={{ value: -0.8, label: 'vs last quarter' }}
+  icon={<TrendingDown className="size-5" />}
+/>
+```
+
+### Stats Grid (4 columns)
+
+```tsx
+<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
+  <StatsCard
+    title="Revenue"
+    value="$45,231"
+    trend={{ value: 20.1, label: 'from last month' }}
+    icon={<DollarSign className="size-5" />}
+  />
+  <StatsCard
+    title="Active Users"
+    value="2,350"
+    trend={{ value: 8.2, label: 'new this week' }}
+    icon={<Users className="size-5" />}
+  />
+  <StatsCard
+    title="Conversion"
+    value="3.6%"
+    trend={{ value: -0.4, label: 'vs last month' }}
+    icon={<Activity className="size-5" />}
+  />
+  <StatsCard
+    title="Avg. Ticket"
+    value="$89.40"
+    description="All time average"
+    icon={<ShoppingCart className="size-5" />}
+  />
+</div>
+```
+
+---
+
+## AI Rules
+
+- `trend.value` is a **numeric percentage** (e.g., `20.1` for +20.1%) — the component displays `Math.abs(value)%` automatically.
+- Do NOT pre-format the trend value as a string — pass the raw number.
+- `value` IS pre-formatted as a display string: `"$45,231"`, `"3.6%"`, `"2,350"`.
+- Icons render inside a rounded background. By default, background is `bg-muted` and color is `text-muted-foreground`, but they can be customized using `iconBg` and `iconColor` props. Use `size-5` for the icon.
+- Always use in a 4-column responsive grid for dashboard overviews.
+- `trend.label` takes precedence over `description` for below-value text.
+
+---
+
+## Related Components
+
+- [`Card`](./card.md) — The underlying primitive
+- [Dashboard Pattern](../patterns/dashboard.md) — Standard usage context

package/docs/components/toggle.md

@@ -56,6 +56,18 @@ const [bold, setBold] = useState(false);
 
 ---
 
+## AI Rules
+
+> [!IMPORTANT]
+>
+> - **Icon-only toggles require `aria-label`** — never render a `<Toggle>` with only an icon and no accessible name.
+> - **Do not use `<Toggle>` for immediate actions** — use `<Button>`; `<Toggle>` is for persistent on/off state.
+> - **Do not use `<Toggle>` for settings** — use `<Switch>` or `<Checkbox>` for clearer on/off semantics.
+> - **For mutually exclusive sets, use `<ToggleGroup>`** instead of managing multiple `<Toggle>` states manually.
+> - **Never use a raw `<button>`** to emulate a pressable state — always use `<Toggle>`.
+
+---
+
 ## Related Components
 
 - [`ToggleGroup`](./toggle-group.md) — Multiple related toggles with exclusion

package/docs/doc-audit.md

@@ -1,244 +1,50 @@
 # Xertica UI — Auditoria de Documentação
 
-> **Status (2026-05-21):** ⚠️ **SUPERSEDED** — este relatório data de 2026-05-19 e a maioria dos itens TODO foi resolvida nas auditorias posteriores. Itens marcados ❌ ou listados como "Sem Doc" nas tabelas abaixo **podem já estar concluídos**.
->
-> Antes de seguir qualquer recomendação aqui, verifique se a documentação correspondente já existe em `docs/components/`. A inventário real abaixo foi atualizado para refletir o estado em 2026-05-21:
->
-> | Categoria                                       | Total                 | Com Doc                                    | Sem Doc |
-> | ----------------------------------------------- | --------------------- | ------------------------------------------ | ------- |
-> | Componentes UI (`components/ui/`)               | 65                    | 65                                         | 0       |
-> | Componentes Assistant (`components/assistant/`) | 5                     | 5                                          | 0       |
-> | Componentes Brand (`components/brand/`)         | 7                     | 7                                          | 0       |
-> | Componentes Layout (`components/layout/`)       | 2                     | 2                                          | 0       |
-> | Componentes Media (`components/media/`)         | 3                     | 3                                          | 0       |
-> | Componentes Blocks (`components/blocks/`)       | 6 cards + 6 skeletons | card-patterns.md (cobre cards + skeletons) | 0       |
-> | Páginas (`components/pages/`)                   | 8                     | pages.md (cobertura agregada)              | 0       |
-> | Hooks/Contextos                                 | 9 hooks               | hooks.md (cobertura agregada)              | 0       |
-> | Utilitários (`components/figma/`)               | 1                     | image-with-fallback.md                     | 0       |
->
-> **Lacunas ainda em aberto (verificar antes de fechar):**
->
-> - Storybook `.mdx` para os 6 card skeletons (existe `.md`, mas não `.mdx`)
-> - `lib/query-client.ts` — singleton não documentado externamente (intencionalmente interno)
->
-> **Última auditoria completa:** ver mensagem do agente em 2026-05-21 que cobriu i18n flexibilidade, skeletons, queryKey language-aware, e correções em `hooks.md`, `branding.md`, `card-patterns.md`, `language-selector.md`, `architecture.md`, `getting-started.md`, `state-management.md`, `components.json`.
-
----
-
-## Resumo Executivo (histórico, possivelmente desatualizado)
-
-| Categoria                                       | Total no Código | Com Doc               | Sem Doc |
-| ----------------------------------------------- | --------------- | --------------------- | ------- |
-| Componentes UI (`components/ui/`)               | 65              | 65                    | 0       |
-| Componentes Assistant (`components/assistant/`) | 5               | 2                     | **3**   |
-| Componentes Brand (`components/brand/`)         | 7               | 6                     | **1**   |
-| Componentes Layout (`components/layout/`)       | 2               | 2                     | 0       |
-| Componentes Media (`components/media/`)         | 3               | 3                     | 0       |
-| Componentes Blocks (`components/blocks/`)       | 6 cards         | 1 doc (card-patterns) | 0       |
-| Páginas (`components/pages/`)                   | 8               | 0                     | **8**   |
-| Hooks/Contextos (`components/hooks/`)           | 6 hooks         | 1 (use-mobile)        | **5**   |
-| Utilitários (`components/figma/`)               | 1               | 0                     | **1**   |
-
----
-
-## 1. Componentes SEM Documentação
-
-### 1.1 Componentes Assistant — Sem doc própria
-
-O [`docs/llms.md`](./llms.md) menciona estes três como _"in Storybook"_, mas não há arquivo `.md` em `docs/components/`:
-
-| Componente          | Arquivo                                    | Importação             | Status     |
-| ------------------- | ------------------------------------------ | ---------------------- | ---------- |
-| `CodeBlock`         | `components/assistant/code-block/`         | `xertica-ui/assistant` | ❌ Sem doc |
-| `ModernChatInput`   | `components/assistant/modern-chat-input/`  | `xertica-ui/assistant` | ❌ Sem doc |
-| `FormattedDocument` | `components/assistant/formatted-document/` | `xertica-ui/assistant` | ❌ Sem doc |
-
-**Impacto:** Agentes de IA não conseguem usar esses componentes corretamente sem prop tables e exemplos.
-
----
-
-### 1.2 Componente Brand — Sem doc
-
-| Componente | Arquivo                      | Status                                      |
-| ---------- | ---------------------------- | ------------------------------------------- |
-| `Branding` | `components/brand/branding/` | ❌ Sem doc (apenas `.mdx` e `.stories.tsx`) |
-
----
-
-### 1.3 Hook `useMapLayers` — Sem doc
-
-O hook [`useMapLayers`](../components/ui/map-layers/map-layers.tsx) é exportado publicamente via `xertica-ui/ui` mas não tem documentação em `docs/components/`. Está relacionado ao sistema de mapas mas não aparece no catálogo do [`docs/llms.md`](./llms.md).
-
----
-
-### 1.4 Utilitário `ImageWithFallback` — Sem doc
-
-| Componente          | Arquivo                                  | Status     |
-| ------------------- | ---------------------------------------- | ---------- |
-| `ImageWithFallback` | `components/figma/ImageWithFallback.tsx` | ❌ Sem doc |
-
-Exportado publicamente via `xertica-ui` mas sem documentação.
-
----
-
-### 1.5 Páginas — Completamente sem documentação
-
-Nenhuma das 8 páginas-template tem documentação em `docs/`:
-
-| Página               | Arquivo                                  |
-| -------------------- | ---------------------------------------- |
-| `LoginPage`          | `components/pages/login-page/`           |
-| `ForgotPasswordPage` | `components/pages/forgot-password-page/` |
-| `ResetPasswordPage`  | `components/pages/reset-password-page/`  |
-| `VerifyEmailPage`    | `components/pages/verify-email-page/`    |
-| `HomePage`           | `components/pages/home-page/`            |
-| `HomeContent`        | `components/pages/home-content/`         |
-| `TemplatePage`       | `components/pages/template-page/`        |
-| `TemplateContent`    | `components/pages/template-content/`     |
-
-**Impacto:** Desenvolvedores e agentes de IA não sabem que essas páginas existem, quais props aceitam, ou como customizá-las. O [`docs/llms.md`](./llms.md) menciona "8 Page Templates" nas estatísticas mas não lista nenhuma delas no catálogo.
-
----
-
-### 1.6 Hooks/Contextos — Sem documentação
-
-O subpath `xertica-ui/hooks` exporta 6 hooks mas apenas `useMobile` tem doc:
+> **Status (2026-06-25):** ✅ **ATUAL** — esta auditoria substitui integralmente o relatório histórico de 2026-05-19. O conteúdo abaixo reflete o estado verificado da documentação contra o código-fonte.
 
-| Hook                        | Contexto             | Status                                                                          |
-| --------------------------- | -------------------- | ------------------------------------------------------------------------------- |
-| `useLayout`                 | `LayoutContext`      | ✅ Documentado em [`docs/layout.md`](./layout.md)                               |
-| `useMobile` / `useIsMobile` | `use-mobile`         | ✅ Documentado em [`docs/components/use-mobile.md`](./components/use-mobile.md) |
-| `useTheme`                  | `ThemeContext`       | ❌ Sem doc                                                                      |
-| `useLanguage`               | `LanguageContext`    | ❌ Sem doc                                                                      |
-| `useBrandColors`            | `BrandColorsContext` | ❌ Sem doc                                                                      |
-| `useAssistente`             | `AssistenteContext`  | ❌ Sem doc                                                                      |
-| `useApiKey`                 | `ApiKeyContext`      | ❌ Sem doc                                                                      |
+## Resumo Executivo
 
-**Impacto:** Agentes de IA não sabem como acessar o tema atual, idioma, cores da marca ou estado do assistente programaticamente.
+A documentação está **completa e em bom estado**. Todos os componentes públicos, hooks, contextos e páginas-template possuem cobertura em `docs/`. Nenhum arquivo de documentação está truncado ou contém seções vazias.
 
----
+| Categoria                        | Total no Código | Com Doc | Sem Doc |
+| -------------------------------- | --------------- | ------- | ------- |
+| Componentes UI (`components/ui/`)        | 60      | 60      | 0       |
+| Componentes Assistant (`components/assistant/`) | 5 | 5    | 0       |
+| Componentes Brand (`components/brand/`)  | 6\*     | 6       | 0       |
+| Componentes Layout (`components/layout/`)| 2       | 2       | 0       |
+| Componentes Media (`components/media/`)  | 3       | 3       | 0       |
+| Componentes Blocks (`components/blocks/`)| 12 (6 cards + 6 skeletons) | `card-patterns.md` (cobertura agregada) | 0 |
+| Páginas (`components/pages/`)            | 8       | `pages.md` (cobertura agregada) | 0 |
+| Hooks/Contextos                          | 10      | `hooks.md` + `use-mobile.md` + `layout.md` | 0 |
+| Utilitários (`components/figma/`)        | 1       | `image-with-fallback.md` | 0 |
 
-## 2. Problemas de Qualidade nos Docs Existentes
+\* `components/brand/branding/` existe apenas como showcase de Storybook (`.stories.tsx` + `.mdx`), não é um export público.
 
-### 2.1 `docs/architecture.md` — Título incorreto
-
-O arquivo [`docs/architecture.md`](./architecture.md) tem como título `# Xertica UI — Documentation Audit Report` (linha 1), mas deveria ser `# Xertica UI — Architecture`. Isso confunde agentes de IA que buscam documentação de arquitetura.
-
----
-
-### 2.2 `docs/components/assistant-chart.md` — Doc muito rasa
-
-O doc do [`AssistantChart`](./components/assistant-chart.md) tem apenas 47 linhas e contém uma regra problemática:
-
-> _"Data Format: Ensure your data objects contain keys that match the `dataKey` set in the internal implementation (currently `month`, `desktop`, and `mobile`)."_
-
-Isso sugere que o componente só aceita dados com essas chaves específicas, o que é enganoso. Faltam:
-
-- Explicação de como usar `dataKey` customizado
-- Exemplos com dados reais de negócio
-- Seção "When to Use / When NOT to Use"
-
----
-
-### 2.3 `docs/llms.md` — Estatísticas desatualizadas e catálogo incompleto
-
-- **Linha 6:** `Total Components: 97` — o número real é maior (inclui páginas, hooks adicionais, `useMapLayers`, etc.)
-- **Seção AI Features:** `CodeBlock`, `ModernChatInput`, `FormattedDocument` listados como _"in Storybook"_ sem link de doc — isso instrui agentes a não usá-los quando na verdade são componentes públicos
-- **Seção Pages:** não existe no catálogo — as 8 páginas-template são invisíveis para agentes de IA
-- **Seção Hooks:** `useTheme`, `useLanguage`, `useBrandColors`, `useAssistente`, `useApiKey` não estão listados
-
----
-
-### 2.4 `docs/components/floating-media-wrapper.md` — Doc incompleta
-
-O arquivo tem apenas 64 linhas e está truncado — a seção "Related Components" (linha 60) não tem conteúdo.
-
----
-
-### 2.5 `docs/components/xertica-provider.md` — Seção "AI Rules" incompleta
-
-O arquivo tem 65 linhas e a seção `## AI Rules` (linha 60) está vazia/truncada.
-
----
-
-## 3. Padrões (Patterns) Faltando
-
-Os 5 padrões existentes cobrem casos básicos, mas faltam padrões para fluxos muito comuns:
-
-| Padrão Faltando              | Descrição                                                                        |
-| ---------------------------- | -------------------------------------------------------------------------------- |
-| **Wizard / Multi-step Form** | Formulário com `Stepper` + validação por etapa + `useStepper`                    |
-| **Detail Page**              | Página de detalhe de registro com `PageHeader` + back button + seções com `Card` |
-| **Settings Page**            | Página de configurações com `Tabs` + seções de formulário + `Switch`             |
-| **Empty + Loading States**   | Padrão completo de `Skeleton` → `Empty` → dados com `Table`                      |
-| **File Upload Form**         | Formulário com `FileUpload` integrado ao `react-hook-form`                       |
-
----
-
-## 4. Docs Gerais — Pontos de Melhoria
-
-### 4.1 `docs/getting-started.md` — Falta seção de troubleshooting
-
-Não há seção de problemas comuns (ex: componentes sem estilo = CSS não importado, erros de TypeScript com subpath imports, etc.).
-
-### 4.2 `docs/installation.md` — Falta menção ao `moduleResolution`
-
-O arquivo [`docs/architecture.md`](./architecture.md) menciona que TypeScript precisa de `"moduleResolution": "bundler"` para subpath exports, mas [`docs/installation.md`](./installation.md) não menciona isso — é um erro de configuração muito comum.
-
-### 4.3 `docs/ai-usage.md` — Falta regra sobre páginas-template
-
-Não há instrução para agentes de IA sobre quando usar as páginas-template (`LoginPage`, `TemplatePage`, etc.) vs. compor do zero.
-
----
-
-## 5. Priorização das Lacunas
-
-### 🔴 Alta Prioridade (impacto direto em agentes de IA e desenvolvedores)
+> Notas de contagem:
+>
+> - `components/ui/` contém 64 diretórios, dos quais 60 são componentes documentados. Os 4 restantes são módulos internos de configuração/re-export: `map-config`, `map-layers` (hook `useMapLayers`, documentado em `map-layers.md`), `map.exports`, e `google-maps-loader` (documentado em `google-maps-loader.md`).
+> - `AssistantChart` reside em `components/ui/assistant-chart/` e é contado como componente UI; aparece de forma cruzada na seção "AI Features" do catálogo de `llms.md`.
 
-1. **Criar `docs/components/code-block.md`** — componente usado internamente e externamente
-2. **Criar `docs/components/modern-chat-input.md`** — componente de input do assistente
-3. **Criar `docs/components/formatted-document.md`** — componente de documento do assistente
-4. **Criar `docs/components/pages.md`** (ou docs individuais) — 8 páginas-template completamente invisíveis
-5. **Criar `docs/components/hooks.md`** — documentar `useTheme`, `useLanguage`, `useBrandColors`, `useAssistente`, `useApiKey`
-6. **Atualizar `docs/llms.md`** — corrigir estatísticas, adicionar páginas e hooks ao catálogo, adicionar links para docs dos componentes assistant
+## Verificações de Qualidade (2026-06-25)
 
-### 🟡 Média Prioridade (melhoria de qualidade)
+| Item                                                              | Resultado |
+| ---------------------------------------------------------------- | --------- |
+| `docs/architecture.md` — título H1 correto (`# Xertica UI — Architecture`) | ✅ OK |
+| `docs/installation.md` — menciona `moduleResolution: "bundler"`  | ✅ OK |
+| `docs/getting-started.md` — possui seção de Troubleshooting       | ✅ OK |
+| `docs/llms.md` — estatísticas reconciliadas com subtotais         | ✅ Corrigido |
+| Seções truncadas / vazias em `docs/components/`                    | ✅ Nenhuma encontrada |
+| Marcadores TODO / WIP / placeholder reais                         | ✅ Nenhum encontrado |
 
-7. **Corrigir título de `docs/architecture.md`**
-8. **Expandir `docs/components/assistant-chart.md`** — remover restrição enganosa de dataKey
-9. **Completar `docs/components/floating-media-wrapper.md`** — seção "Related Components"
-10. **Completar `docs/components/xertica-provider.md`** — seção "AI Rules"
-11. **Criar `docs/components/map-layers.md`** — documentar `useMapLayers`
-12. **Adicionar `"moduleResolution": "bundler"` em `docs/installation.md`**
+## Padrões (`docs/patterns/`)
 
-### 🟢 Baixa Prioridade (melhorias incrementais)
+Cobertura atual: `analytics`, `crud`, `dashboard`, `detail-page`, `form`, `login`, `settings`, `wizard` (8 padrões). Os fluxos comuns identificados em auditorias anteriores (wizard/multi-step, detail page, settings page) já estão documentados.
 
-13. **Criar padrão `docs/patterns/wizard.md`** — multi-step form com Stepper
-14. **Criar padrão `docs/patterns/detail-page.md`** — página de detalhe
-15. **Criar padrão `docs/patterns/settings.md`** — página de configurações
-16. **Adicionar seção de troubleshooting em `docs/getting-started.md`**
-17. **Criar `docs/components/image-with-fallback.md`** — utilitário de imagem
-18. **Criar `docs/components/branding.md`** — componente de branding
+## Pontos de Atenção Menores
 
----
+- **Convenção de seção "AI Rules":** padronizada em todos os docs de componentes. Verificar novos docs para garantir uso de "AI Rules" (e não variações como "AI Best Practices").
+- **`lib/query-client.ts`:** singleton intencionalmente interno; não exposto na API pública e não documentado externamente por design.
 
-## 6. Checklist de Ações
+## Histórico
 
-- [ ] `docs/components/code-block.md` — criar
-- [ ] `docs/components/modern-chat-input.md` — criar
-- [ ] `docs/components/formatted-document.md` — criar
-- [ ] `docs/components/pages.md` — criar (ou 8 docs individuais)
-- [ ] `docs/components/hooks.md` — criar (useTheme, useLanguage, useBrandColors, useAssistente, useApiKey)
-- [ ] `docs/llms.md` — atualizar estatísticas + adicionar páginas + hooks + links dos assistant components
-- [ ] `docs/architecture.md` — corrigir título (linha 1)
-- [ ] `docs/components/assistant-chart.md` — expandir e corrigir regra de dataKey
-- [ ] `docs/components/floating-media-wrapper.md` — completar seção "Related Components"
-- [ ] `docs/components/xertica-provider.md` — completar seção "AI Rules"
-- [ ] `docs/components/map-layers.md` — criar
-- [ ] `docs/installation.md` — adicionar requisito de `moduleResolution`
-- [ ] `docs/patterns/wizard.md` — criar
-- [ ] `docs/patterns/detail-page.md` — criar
-- [ ] `docs/patterns/settings.md` — criar
-- [ ] `docs/getting-started.md` — adicionar seção de troubleshooting
-- [ ] `docs/components/image-with-fallback.md` — criar
-- [ ] `docs/components/branding.md` — criar
+O relatório original (2026-05-19) listava lacunas em componentes Assistant, páginas-template, hooks e utilitários. Todas foram resolvidas em auditorias subsequentes (2026-05-21 em diante). Aquele conteúdo foi removido deste arquivo por estar desatualizado e contradizer o estado real verificado.

package/docs/i18n.md

@@ -99,20 +99,40 @@ const es = bundleLang(
 const savedLanguage =
   typeof window !== 'undefined' ? (localStorage.getItem('xertica_language') ?? 'pt-BR') : 'pt-BR';
 
-i18n.use(initReactI18next).init({
-  resources: {
-    'pt-BR': { translation: ptBR },
-    en: { translation: en },
-    es: { translation: es },
-  },
-  lng: savedLanguage,
-  fallbackLng: 'pt-BR',
-  interpolation: { escapeValue: false }, // React escapes already
-});
+// Guard against the i18next singleton being initialized twice: node_modules/i18next
+// is a single instance shared (hoisted) between this app and xertica-ui itself, and
+// `i18n.init()` fully replaces the resource store rather than merging. Whichever
+// side calls `.init()` last would otherwise silently wipe the other's resources.
+const defaultResourcesByLang: Record<string, Record<string, unknown>> = {
+  'pt-BR': ptBR,
+  en,
+  es,
+};
+
+if (!i18n.isInitialized) {
+  i18n.use(initReactI18next).init({
+    resources: {
+      'pt-BR': { translation: ptBR },
+      en: { translation: en },
+      es: { translation: es },
+    },
+    lng: savedLanguage,
+    fallbackLng: 'pt-BR',
+    interpolation: { escapeValue: false }, // React escapes already
+  });
+} else {
+  // Already initialized by the other side — merge in without overwriting
+  // keys that have already been registered.
+  for (const [lang, resources] of Object.entries(defaultResourcesByLang)) {
+    i18n.addResourceBundle(lang, 'translation', resources, true, false);
+  }
+}
 
 export default i18n;
 ```
 
+> This guard is generated automatically by `npx xertica-ui@latest init` / `update` — you don't need to hand-write it unless you're authoring `src/i18n.ts` from scratch.
+
 ### 4. Initialize before rendering
 
 ```ts
@@ -478,3 +498,4 @@ const {
 - **The set of available languages is runtime-configurable** — pass `availableLanguages` to `<XerticaProvider>` to add, remove, or restrict to a single locale. Never modify `DEFAULT_LANGUAGES` directly
 - **The `LanguageSelector` auto-hides when `isMonolingual` is true** — do not conditionally render it yourself; pass it `showWhenMonolingual` if you want it visible
 - **`Language` is typed as `string`** (not a strict union) to support runtime-added locales. Use `LanguageDefinition['code']` from `useLanguage().availableLanguages` for autocomplete
+- **i18next is a shared singleton** between this app and xertica-ui — `node_modules/i18next` is hoisted to a single instance, and `i18n.init()` fully replaces the resource store rather than merging. `src/i18n.ts` (and the library's own bootstrap) guard `.init()` with `i18n.isInitialized` and fall back to `addResourceBundle(..., true, false)` on the second call, so neither side wipes the other's resources and an app-customized key always wins over the design system's default