xertica-ui 2.1.3 → 2.1.4

package/docs/doc-audit.md

@@ -0,0 +1,223 @@
+# Xertica UI — Auditoria de Documentação
+
+> **Data:** 2026-05-19  
+> **Escopo:** Verificação completa de cobertura e qualidade da documentação em `docs/`
+
+---
+
+## Resumo Executivo
+
+| 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:
+
+| 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 |
+
+**Impacto:** Agentes de IA não sabem como acessar o tema atual, idioma, cores da marca ou estado do assistente programaticamente.
+
+---
+
+## 2. Problemas de Qualidade nos Docs Existentes
+
+### 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)
+
+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
+
+### 🟡 Média Prioridade (melhoria de qualidade)
+
+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`**
+
+### 🟢 Baixa Prioridade (melhorias incrementais)
+
+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
+
+---
+
+## 6. Checklist de Ações
+
+- [ ] `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

package/docs/getting-started.md

@@ -259,3 +259,157 @@ Icons are separate — always use `lucide-react`:
 ```tsx
 import { Home, Settings, Users, LogOut } from 'lucide-react';
 ```
+
+---
+
+## Troubleshooting
+
+### Components render without styles (transparent / unstyled)
+
+**Cause**: Missing CSS import.
+
+**Fix**: Add `import 'xertica-ui/style.css'` to your entry file (`main.tsx` or `index.tsx`), **before** your own styles:
+
+```tsx
+import 'xertica-ui/style.css';
+import './styles/index.css'; // your tokens and overrides
+```
+
+---
+
+### Dark mode doesn't apply
+
+**Cause**: The `dark` class is not being toggled on `<html>`, or `@theme inline` is missing from your CSS.
+
+**Fix 1**: Use `<ThemeToggle>` from `xertica-ui/brand` — it handles the class toggle automatically.
+
+**Fix 2**: Ensure your `index.css` uses `@theme inline` (not plain `@theme`):
+
+```css
+/* ✅ Correct */
+@theme inline {
+  --color-primary: var(--primary);
+}
+
+/* ❌ Wrong — compiles tokens statically, ignoring your tokens.css overrides */
+@theme {
+  --color-primary: var(--primary);
+}
+```
+
+---
+
+### Subpath imports cause TypeScript errors
+
+**Cause**: `tsconfig.json` uses `"moduleResolution": "node"` which does not support package subpath exports.
+
+**Fix**: Update `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "bundler"
+  }
+}
+```
+
+Alternatively, use `"moduleResolution": "node16"` or `"nodenext"`.
+
+---
+
+### Toast notifications don't appear
+
+**Cause**: `<Toaster>` is not mounted, or `<XerticaProvider>` is missing.
+
+**Fix**: Wrap your app in `<XerticaProvider>` — it auto-injects `<Toaster>`. If you are not using `XerticaProvider`, add `<Toaster />` manually:
+
+```tsx
+import { Toaster } from 'xertica-ui/ui';
+
+function App() {
+  return (
+    <>
+      <YourApp />
+      <Toaster />
+    </>
+  );
+}
+```
+
+---
+
+### Dialogs / Modals don't appear
+
+**Cause**: Missing `<XerticaProvider>` (which includes `TooltipProvider` and portal context).
+
+**Fix**: Ensure `<XerticaProvider>` wraps the entire application at the root level.
+
+---
+
+### Google Maps doesn't load
+
+**Cause**: Missing or invalid `googleMapsApiKey`, or the Maps API script failed to load.
+
+**Fix**: Pass the key to `XerticaProvider`:
+
+```tsx
+<XerticaProvider googleMapsApiKey="YOUR_VALID_KEY">
+  <App />
+</XerticaProvider>
+```
+
+Or use `useApiKey()` to set it at runtime:
+
+```tsx
+const { setGoogleMapsApiKey, reloadMapsApi } = useApiKey();
+setGoogleMapsApiKey('YOUR_KEY');
+await reloadMapsApi();
+```
+
+---
+
+### `useLayout()` throws "must be used within LayoutProvider"
+
+**Cause**: The component using `useLayout()` is rendered outside `<XerticaProvider>`.
+
+**Fix**: Ensure `<XerticaProvider>` is an ancestor of all components that use `useLayout()`, `useTheme()`, or any other context hook.
+
+For components that may be used both inside and outside the provider (e.g., in Storybook), use `useOptionalLayout()` instead — it returns `null` when the context is unavailable.
+
+---
+
+### Sidebar width causes content overlap
+
+**Cause**: Content area is not reading `sidebarWidth` from `useLayout()`.
+
+**Fix**: Apply the sidebar width as a left margin or padding on the main content area:
+
+```tsx
+const { sidebarWidth } = useLayout();
+
+<main style={{ marginLeft: sidebarWidth }} className="flex-1 overflow-auto">
+  {/* content */}
+</main>
+```
+
+---
+
+### AI Assistant doesn't respond (real mode)
+
+**Cause**: Missing or invalid Gemini API key.
+
+**Fix**: Set the Gemini API key via `useApiKey()` or pass it to `XerticaProvider`:
+
+```tsx
+<XerticaProvider initialGeminiApiKey="YOUR_GEMINI_KEY">
+  <App />
+</XerticaProvider>
+```
+
+Or use the Settings pattern to let users enter their own key. See [`docs/patterns/settings.md`](./patterns/settings.md).
+
+For testing without a real API key, use `mode="demo"` on `XerticaAssistant`:
+
+```tsx
+<XerticaAssistant mode="demo" />
+```

package/docs/llms.md

@@ -3,13 +3,14 @@
 > **This is the primary entrypoint for AI agents operating on any project that uses `xertica-ui`.** Read this document first before exploring any other file.
 
 ## Statistics
-- **Total Components:** 97
+- **Total Components:** 104
 - **UI Components:** 62
-- **Assistant Components:** 5
+- **Assistant Components:** 8
 - **Brand Components:** 6
 - **Media Components:** 3
 - **Layout Components:** 2
 - **Page Templates:** 8
+- **Hooks:** 9
 
 ## What is Xertica UI?
 
@@ -154,15 +155,34 @@ Follow this order when onboarding to a project that uses `xertica-ui`:
 |---|---|---|
 | `useMobile` / `useIsMobile` | [use-mobile.md](./components/use-mobile.md) | Detects mobile viewport for conditional rendering |
 | `useLayout` | [layout.md](../layout.md) | Accesses sidebar width, state, and toggle functions |
+| `useTheme` | [hooks.md](./components/hooks.md#usetheme) | Reads and toggles the current color theme (light/dark) |
+| `useLanguage` | [hooks.md](./components/hooks.md#uselanguage) | Reads and sets the current UI language preference |
+| `useBrandColors` | [hooks.md](./components/hooks.md#usebrandcolors) | Reads and modifies brand color CSS variables |
+| `useAssistente` | [hooks.md](./components/hooks.md#useassistente) | Accesses the global AI assistant context |
+| `useApiKey` | [hooks.md](./components/hooks.md#useapikey) | Manages API keys for Xertica, Gemini, and Google Maps |
+| `useAudioPlayer` | [hooks.md](./components/hooks.md#useaudioplayer) | Headless hook for building custom audio player UIs |
+| `useLayoutShortcuts` | [hooks.md](./components/hooks.md#uselayoutshortcuts) | Registers global keyboard shortcuts (Ctrl+B = sidebar toggle) |
+
+### Page Templates
+| Component | Doc | Purpose |
+|---|---|---|
+| `LoginPage` | [pages.md](./components/pages.md#loginpage) | Complete login screen with email/password and SSO placeholders |
+| `ForgotPasswordPage` | [pages.md](./components/pages.md#forgotpasswordpage) | Password recovery form |
+| `ResetPasswordPage` | [pages.md](./components/pages.md#resetpasswordpage) | New password form for reset flow |
+| `VerifyEmailPage` | [pages.md](./components/pages.md#verifyemailpage) | Email verification confirmation screen |
+| `HomePage` | [pages.md](./components/pages.md#homepage) | Root dashboard shell (Sidebar + HomeContent + Assistant) |
+| `HomeContent` | [pages.md](./components/pages.md#homecontent) | Dashboard main content area with stats, charts, and tables |
+| `TemplatePage` | [pages.md](./components/pages.md#templatepage) | Full layout reference shell (Sidebar + TemplateContent + Assistant) |
+| `TemplateContent` | [pages.md](./components/pages.md#templatecontent) | Comprehensive component showcase for development reference |
 
 ### AI Features
 | Component | Doc | Purpose |
 |---|---|---|
 | `XerticaAssistant` | [assistant.md](./components/assistant.md) | Embedded AI chat panel & document workspace |
-| `CodeBlock` | in Storybook | Syntax-highlighted code display with copy button |
+| `CodeBlock` | [code-block.md](./components/code-block.md) | Syntax-highlighted code display with copy button |
 | `MarkdownMessage` | [markdown-message.md](./components/markdown-message.md) | Renders AI responses with Markdown formatting |
-| `ModernChatInput` | in Storybook | Enhanced AI chat input with drag-and-drop support |
-| `FormattedDocument` | in Storybook | Refined document display for AI-generated content |
+| `ModernChatInput` | [modern-chat-input.md](./components/modern-chat-input.md) | Enhanced AI chat input with action chips and voice recording |
+| `FormattedDocument` | [formatted-document.md](./components/formatted-document.md) | Collapsible Markdown renderer for AI-generated documents |
 | `AssistantChart` | [assistant-chart.md](./components/assistant-chart.md) | Specialized data visualization for AI insights |
 
 ### Brand & Theme