xertica-ui 1.5.1 → 1.5.2

package/components.json

@@ -0,0 +1,350 @@
+[
+  {
+    "name": "accordion",
+    "docPath": "docs/components/accordion.md",
+    "sourcePath": "components/ui/accordion.tsx",
+    "description": "Gerenciador de exibição oculta (collapse) vertical focada em empilhamento. Baseado em Header nativo acessível."
+  },
+  {
+    "name": "alert-dialog",
+    "docPath": "docs/components/alert-dialog.md",
+    "sourcePath": "components/ui/alert-dialog.tsx",
+    "description": "Modal interruptivo e destrutivo que requer uma ação explícita pelo usuário para ser descartado ou aprovado."
+  },
+  {
+    "name": "alert",
+    "docPath": "docs/components/alert.md",
+    "sourcePath": "components/ui/alert.tsx",
+    "description": "Blocos informativos fixos e destacados para alertar o usuário de algo importante que não deve ser descartável e exige leitura compulsória na mesma página."
+  },
+  {
+    "name": "aspect-ratio",
+    "docPath": "docs/components/aspect-ratio.md",
+    "sourcePath": "components/ui/aspect-ratio.tsx",
+    "description": "Força uma proporção delimitada (largura/altura) em um bloco de interface responsivo contendo embeds, iframes ou Imóveis fotográficos complexos."
+  },
+  {
+    "name": "assistant",
+    "docPath": "docs/components/assistant.md",
+    "sourcePath": "components/ui/assistant.tsx",
+    "description": "Interface de conversação inteligente (Chatbot) projetada para integrar IA generativa diretamente no Design System xertica-ui."
+  },
+  {
+    "name": "avatar",
+    "docPath": "docs/components/avatar.md",
+    "sourcePath": "components/ui/avatar.tsx",
+    "description": "Representação gráfica e visual de uma Entidade, Usuário ou Organização."
+  },
+  {
+    "name": "badge",
+    "docPath": "docs/components/badge.md",
+    "sourcePath": "components/ui/badge.tsx",
+    "description": "Pequenos blocos informacionais sem formato de interação para indicação textual/status rápida. Etiqueta."
+  },
+  {
+    "name": "breadcrumb",
+    "docPath": "docs/components/breadcrumb.md",
+    "sourcePath": "components/ui/breadcrumb.tsx",
+    "description": "Exibe o caminho hierárquico percorrido pelo usuário até a página atual, providenciando navegação para voltar à telas antecessoras."
+  },
+  {
+    "name": "button",
+    "docPath": "docs/components/button.md",
+    "sourcePath": "components/ui/button.tsx",
+    "description": "Botão principal para ações do usuário."
+  },
+  {
+    "name": "calendar",
+    "docPath": "docs/components/calendar.md",
+    "sourcePath": "components/ui/calendar.tsx",
+    "description": "Selecionador de dadas baseado na robusta biblioteca interativa `react-day-picker`."
+  },
+  {
+    "name": "card",
+    "docPath": "docs/components/card.md",
+    "sourcePath": "components/ui/card.tsx",
+    "description": "Base estrutural semântica para enclausurar seções. Dá volume, sombras nativas e hierarquização por bordas. O uso universal da web moderna."
+  },
+  {
+    "name": "carousel",
+    "docPath": "docs/components/carousel.md",
+    "sourcePath": "components/ui/carousel.tsx",
+    "description": "Carrossel complexo construído em cima do engine robusto temporal `embla-carousel-react`."
+  },
+  {
+    "name": "chart",
+    "docPath": "docs/components/chart.md",
+    "sourcePath": "components/ui/chart.tsx",
+    "description": "Poderosa camada semântica Xertica UI envolvendo a biblioteca analítica `recharts`. Abstrai injeções de cor de temas responsivos/dark mode para dentro dos gráficos SVG."
+  },
+  {
+    "name": "checkbox",
+    "docPath": "docs/components/checkbox.md",
+    "sourcePath": "components/ui/checkbox.tsx",
+    "description": "Componente de seleção booleana isolada ou de múltipla escolha."
+  },
+  {
+    "name": "collapsible",
+    "docPath": "docs/components/collapsible.md",
+    "sourcePath": "components/ui/collapsible.tsx",
+    "description": "Semelhante ao Accordion, porém livre de dependências de listas. Um painel isolado que expõe e contrai um bloco de conteúdo, geralmente usado isoladamente e não em empilhamentos de múltiplos irmãos (neste caso, prefira o Accordion)."
+  },
+  {
+    "name": "command",
+    "docPath": "docs/components/command.md",
+    "sourcePath": "components/ui/command.tsx",
+    "description": "Menu de busca universal, filtragem rápida e navegação de comandos estilo Spotlight (`⌘K`, Cmd+K). Escrito sobre `cmdk`."
+  },
+  {
+    "name": "context-menu",
+    "docPath": "docs/components/context-menu.md",
+    "sourcePath": "components/ui/context-menu.tsx",
+    "description": "Exibe um menu sobre a posição do ponteiro, ativado estritamente clicando com o Botão Direito do mouse ou Right-Click (evento OnContextMenu)."
+  },
+  {
+    "name": "dialog",
+    "docPath": "docs/components/dialog.md",
+    "sourcePath": "components/ui/dialog.tsx",
+    "description": "Overlay modal focado no usuário que suspende a navegação pela interface subjacente até ser resolvido."
+  },
+  {
+    "name": "drawer",
+    "docPath": "docs/components/drawer.md",
+    "sourcePath": "components/ui/drawer.tsx",
+    "description": "Painel de folha móvel baseado em arrasto (Slide/Swipe). Diferente do `Sheet` (geralmente fixado na direita/esquerda), o Drawer por padrão escala a partir de **baixo para cima** da tela e suporta toque interativo no Mobile nativamente. Usado através da lib `vaul`."
+  },
+  {
+    "name": "dropdown-menu",
+    "docPath": "docs/components/dropdown-menu.md",
+    "sourcePath": "components/ui/dropdown-menu.tsx",
+    "description": "Exibe um menu de comandos para o usuário em forma flutuante via janela modal suspensa (exibe por gatilho ao clique, não hover ativo)."
+  },
+  {
+    "name": "empty",
+    "docPath": "docs/components/empty.md",
+    "sourcePath": "components/ui/empty.tsx",
+    "description": "Componente figurativo para ilustrar \"Empty States\" - quando listas ou bancos de dados retornam vazios ou páginas que recém nasceram ainda não contem registros."
+  },
+  {
+    "name": "file-upload",
+    "docPath": "docs/components/file-upload.md",
+    "sourcePath": "components/ui/file-upload.tsx",
+    "description": "Área de arrastar e soltar (Drag and Drop) ou Input padronizado para anexação de Mídias e Arquivos Genéricos."
+  },
+  {
+    "name": "form",
+    "docPath": "docs/components/form.md",
+    "sourcePath": "components/ui/form.tsx",
+    "description": "A abstração primária para manipulação complexa de estados de inputs, integrando `react-hook-form` e `zod`."
+  },
+  {
+    "name": "hover-card",
+    "docPath": "docs/components/hover-card.md",
+    "sourcePath": "components/ui/hover-card.tsx",
+    "description": "Overlay não acionável pelo clique, mas pelo mouse-over (hover), usado para revelar previews ricos sobre links importantes."
+  },
+  {
+    "name": "input-otp",
+    "docPath": "docs/components/input-otp.md",
+    "sourcePath": "components/ui/input-otp.tsx",
+    "description": "Um preenchedor mascarado multifragmentado (One-Time Password) inspirado no input nativo do iOS. Facilita muito a confirmação de Códigos SMS (2FA)."
+  },
+  {
+    "name": "input",
+    "docPath": "docs/components/input.md",
+    "sourcePath": "components/ui/input.tsx",
+    "description": "Campos de entrada de dados simples e texto para formulários."
+  },
+  {
+    "name": "label",
+    "docPath": "docs/components/label.md",
+    "sourcePath": "components/ui/label.tsx",
+    "description": "Etiqueta semântica tipográfica base `<label>` utilizada para amarrar textos descritivos aos respectivos formulários ou botões."
+  },
+  {
+    "name": "map",
+    "docPath": "docs/components/map.md",
+    "sourcePath": "components/ui/map.tsx",
+    "description": "Sistema de geolocalização baseado na API do Google Maps, com suporte a marcadores avançados, polígonos, círculos e cálculo de rotas."
+  },
+  {
+    "name": "menubar",
+    "docPath": "docs/components/menubar.md",
+    "sourcePath": "components/ui/menubar.tsx",
+    "description": "Faixa de comando similar aos menus de desktop (Arquivos, Editar, Visualizar) encontrada no topo de sistemas operacionais Mac/Windows."
+  },
+  {
+    "name": "navigation-menu",
+    "docPath": "docs/components/navigation-menu.md",
+    "sourcePath": "components/ui/navigation-menu.tsx",
+    "description": "Mega Menu complexo, utilizado em Top-Navigations e Header de Landipages. Suporta drop-downs gigantescos ricos em Media e text flows. Similar ao header da Stripe."
+  },
+  {
+    "name": "notification-badge",
+    "docPath": "docs/components/notification-badge.md",
+    "sourcePath": "components/ui/notification-badge.tsx",
+    "description": "Semelhante à bolinha vermelha de notificações em apps móveis. Uma bolha ou balão pequeno indicando números ativos não lidos ou puramente a existência de tração (Dot)."
+  },
+  {
+    "name": "page-header",
+    "docPath": "docs/components/page-header.md",
+    "sourcePath": "components/ui/page-header.tsx",
+    "description": "Componente robusto para construção do título primário, descrição e ações de topo fixadas visualmente no começo do corpo das telas. Usado recorrentemente para manter simetria entre as *routes*."
+  },
+  {
+    "name": "pagination",
+    "docPath": "docs/components/pagination.md",
+    "sourcePath": "components/ui/pagination.tsx",
+    "description": "Navegação para distribuir volumes massivos de informações (como tabelas ou listas) dividindo itens em páginas. Baseado no novo radix pattern, usando sintaxe markup similar a acessibilidade W3C."
+  },
+  {
+    "name": "popover",
+    "docPath": "docs/components/popover.md",
+    "sourcePath": "components/ui/popover.tsx",
+    "description": "Painéis sobrepostos posicionáveis invocados após clique. Similar ao Tooltip nativo, mas com a função de injetar conteúdo rico, formulários ou actions diretas, e não some num Hover passivo."
+  },
+  {
+    "name": "progress",
+    "docPath": "docs/components/progress.md",
+    "sourcePath": "components/ui/progress.tsx",
+    "description": "Barra de progresso horizontal indicando avanço de uma tarefa com começo e fim quantificáveis ou estados de carregamento longos."
+  },
+  {
+    "name": "radio-group",
+    "docPath": "docs/components/radio-group.md",
+    "sourcePath": "components/ui/radio-group.tsx",
+    "description": "Componente que engloba opções mutuamente exclusivas e radioativas na seleção univalente."
+  },
+  {
+    "name": "rating",
+    "docPath": "docs/components/rating.md",
+    "sourcePath": "components/ui/rating.tsx",
+    "description": "Componente visual de pontuação/avaliação formatado em 5 ícones (normalmente Estrelas). Permite avaliação fracionária."
+  },
+  {
+    "name": "resizable",
+    "docPath": "docs/components/resizable.md",
+    "sourcePath": "components/ui/resizable.tsx",
+    "description": "Painéis de dimensão embutida manipuláveis criados em cima de `react-resizable-panels`."
+  },
+  {
+    "name": "scroll-area",
+    "docPath": "docs/components/scroll-area.md",
+    "sourcePath": "components/ui/scroll-area.tsx",
+    "description": "Barra de rolamento customizada (`Radix ScrollArea`) estilizada visualmente para não quebrar com temas Dark/Light nem afetar as larguras exatas do layout inter-browser como as \"scrollbars\" nativas feias do Windows fazem."
+  },
+  {
+    "name": "search",
+    "docPath": "docs/components/search.md",
+    "sourcePath": "components/ui/search.tsx",
+    "description": "Input super especializado para buscas de interface amplas (Search Bar). Frequentemente inclui icone de lupa embutido."
+  },
+  {
+    "name": "select",
+    "docPath": "docs/components/select.md",
+    "sourcePath": "components/ui/select.tsx",
+    "description": "Menu suspenso (`dropdown`) focado em seleção univalente ou polivalente de dados a partir de uma lista pré-determinada."
+  },
+  {
+    "name": "separator",
+    "docPath": "docs/components/separator.md",
+    "sourcePath": "components/ui/separator.tsx",
+    "description": "Divisor semântico temático abstrato (`<hr>`) estilizado com `bg-border`."
+  },
+  {
+    "name": "sheet",
+    "docPath": "docs/components/sheet.md",
+    "sourcePath": "components/ui/sheet.tsx",
+    "description": "Overlay que desliza para dentro da tela e captura foco integral, empurrando o resto da UI pro fundo (efeito drawer/offcanvas)."
+  },
+  {
+    "name": "sidebar",
+    "docPath": "docs/components/sidebar.md",
+    "sourcePath": "components/ui/sidebar.tsx",
+    "description": "Navegação lateral primária para aplicações ou painéis gerenciais. A Xertica UI suporta o modo padrão e um modo estendido \"assistant\"."
+  },
+  {
+    "name": "skeleton",
+    "docPath": "docs/components/skeleton.md",
+    "sourcePath": "components/ui/skeleton.tsx",
+    "description": "Placeholder provisório para dar a ilusão do layout exato antes da carga do conteúdo (efeito shimmer pulsante). Melhora psicologicamente as métricas de Perceived Wait Time."
+  },
+  {
+    "name": "slider",
+    "docPath": "docs/components/slider.md",
+    "sourcePath": "components/ui/slider.tsx",
+    "description": "Componente de input visual na forma de barra delimitadora horizontal em que o usuário manipula o \"thumb\" ou cabeça do indicador para selecionar valores quantitativos em intervalos fixos."
+  },
+  {
+    "name": "sonner",
+    "docPath": "docs/components/sonner.md",
+    "sourcePath": "components/ui/sonner.tsx",
+    "description": "Disparador de mensagens em formato \"Toast\". Uma notificação flutuante e descartável na lateral/vizinhança da tela sem intervenção do layout."
+  },
+  {
+    "name": "stats-card",
+    "docPath": "docs/components/stats-card.md",
+    "sourcePath": "components/ui/stats-card.tsx",
+    "description": "Variação específica e padronizada do `Card` projetada exclusivamente para estatísticas rápidas numericas (Indicadores Financeiros/Métricas)."
+  },
+  {
+    "name": "stepper",
+    "docPath": "docs/components/stepper.md",
+    "sourcePath": "components/ui/stepper.tsx",
+    "description": "Orientador visual de etapas para guiar usuários através de formulários extensos."
+  },
+  {
+    "name": "switch",
+    "docPath": "docs/components/switch.md",
+    "sourcePath": "components/ui/switch.tsx",
+    "description": "Controle binário visual alternador (On/Off)."
+  },
+  {
+    "name": "table",
+    "docPath": "docs/components/table.md",
+    "sourcePath": "components/ui/table.tsx",
+    "description": "Exibição robusta de dados tabulares (linx-coluna) baseada em HTML Tables mas com Tailwind CSS styling padronizado."
+  },
+  {
+    "name": "tabs",
+    "docPath": "docs/components/tabs.md",
+    "sourcePath": "components/ui/tabs.tsx",
+    "description": "Componente de navegação intra-página que fragmenta grandes visualizações limitando-se ao que o usuário escolhe."
+  },
+  {
+    "name": "textarea",
+    "docPath": "docs/components/textarea.md",
+    "sourcePath": "components/ui/textarea.tsx",
+    "description": "Campos de entrada de dados de múltiplas linhas projetados especificamente para blocos longos de texto aberto."
+  },
+  {
+    "name": "timeline",
+    "docPath": "docs/components/timeline.md",
+    "sourcePath": "components/ui/timeline.tsx",
+    "description": "Rastreador histórico vertical projetado para auditar passos completados em ordem serial, conectando-os com uma linha contínua."
+  },
+  {
+    "name": "toggle-group",
+    "docPath": "docs/components/toggle-group.md",
+    "sourcePath": "components/ui/toggle-group.tsx",
+    "description": "Agrupador de `Toggles` que garante exclusividade ou múltipla seleção compartilhando bordas (um button group moderno)."
+  },
+  {
+    "name": "toggle",
+    "docPath": "docs/components/toggle.md",
+    "sourcePath": "components/ui/toggle.tsx",
+    "description": "Um botão de dois estados usado de forma similar ao Switch, mas com a aparência primária voltada para edição de texto e ferramentas. (ex: Botão \"Negrito\", ou \"Itálico\")."
+  },
+  {
+    "name": "tooltip",
+    "docPath": "docs/components/tooltip.md",
+    "sourcePath": "components/ui/tooltip.tsx",
+    "description": "Mensagem curta suspensa via mouse-over que estende ou descreve um Ícone ou Função ambígua."
+  },
+  {
+    "name": "tree-view",
+    "docPath": "docs/components/tree-view.md",
+    "sourcePath": "components/ui/tree-view.tsx",
+    "description": "Módulo explorador de pastas indentáveis, excelente para exibir estruturas de dados complexas ou arquivos hierárquicos."
+  }
+]

package/docs/ai-usage.md

@@ -0,0 +1,18 @@
+# AI Usage Manual
+
+Este arquivo é destinado estritamente aos LLMs operando este repositório.
+
+## Extração de Conhecimento
+1. Seu conhecimento primário deve vir da leitura dos arquivos `.md` contidos em `/docs/components` e os códigos fonte `.tsx` na pasta `/components/ui/`.
+2. A leitura do código `components/ui` não tem como objetivo gerar versões alternativas derivadas dele, mas para que você, como agente, leia o **TSDoc** contido nas props de interface do componente antes de importá-lo no projeto do desenvolvedor.
+3. Não presuma que todas as props suportadas pelo HTML nativo são exportadas no spread. Algumas podem ser barradas pelo design do componente.
+
+## O Motor de Validação (`ts-morph`)
+Ao operar Xertica UI, seu trabalho não se resume a apenas "abrir e salvar arquivos".
+Parte do processo é submeter ou ser submetido à engine local que pode vetar seu código.
+Seja pró-ativo:
+- Prefira composições óbvias e validadas vistas em `/docs/patterns`.
+- Se um log reportar `<button> inserido ilegalmente`, significa que a engine pegou que você usou uma tag nativa (geralmente punido no pipeline). O substituto neste caso não é fazer wrap, mas invocar import { Button } from 'xertica-ui'.
+
+## Tratamento de SVGs e Ícones
+- Quando um design pedir "ícone", nunca gere as tags `<svg> <path>... </svg>`. Em vez disso, utilize `import { IconName } from 'lucide-react'`.

package/docs/components/accordion.md

@@ -0,0 +1,43 @@
+# Accordion
+
+## Descrição
+Gerenciador de exibição oculta (collapse) vertical focada em empilhamento. Baseado em Header nativo acessível.
+
+## Quando usar
+- Seção de Perguntas Frequentes (FAQ).
+- Listas densas de sub-configurações em Sidebars (onde só uma/varias permanecem abertas verticalmente).
+- Esconder dados menos relevantes sem navegar de página.
+
+## Variações Formais
+- `type="single"`: Permite abrir apenas uma seção por vez. Quando um abre o outro fecha. Requer `collapsible` prop para se autossuspender.
+- `type="multiple"`: Permite todos os abertos independentes simultaneamente.
+
+## Exemplo estruturado
+
+```tsx
+import {
+  Accordion,
+  AccordionContent,
+  AccordionItem,
+  AccordionTrigger,
+} from "xertica-ui"
+
+<Accordion type="single" collapsible className="w-full">
+  <AccordionItem value="item-1">
+    <AccordionTrigger>Esta biblioteca é acessível (W3C)?</AccordionTrigger>
+    <AccordionContent>
+      Sim. Baseia-se integralmente no Radix UI e ARIA roles garantindo leitores de telas afiados.
+    </AccordionContent>
+  </AccordionItem>
+  <AccordionItem value="item-2">
+    <AccordionTrigger>Como aplico os estilos personalizados?</AccordionTrigger>
+    <AccordionContent>
+      Sobrescreva o `className` no trigger ou content diretamente. As classes utilitárias são mescladas via `tailwind-merge`.
+    </AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+## Regras para IA
+- `AccordionItem` REQUER OBRIGATORIAMENTE uma string injetada em `value="xxx"`. É como o contexto rastreia quem está visível. Injetar sub-componentes complexos na Content sem passar a value do Item quebrará a interação em state-machines.
+- O Chevron animado (`ChevronDown`) já está solidificado e embutido dentro de `AccordionTrigger`. Não reimplemente um ícone de seta nativamente a não ser se pedido de variante distinta.

package/docs/components/alert-dialog.md

@@ -0,0 +1,50 @@
+# Alert Dialog
+
+## Descrição
+Modal interruptivo e destrutivo que requer uma ação explícita pelo usuário para ser descartado ou aprovado.
+
+## Quando usar
+- Ações críticas IRREVERSÍVEIS: Excluir Usuário, Apagar Base de Dados, Cancelar Assinatura.
+
+## Diferenças do Dialog comum
+Enquanto `Dialog` pode ser fechado clicando-se no fundo escuro (backdrop) ou com no `X` superior, o `<AlertDialog>` te obriga a interagir com os botões inferiores Cancelar ou Aceitar (preventing accidental dismissals).
+
+## Exemplo mínimo
+
+```tsx
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+  Button
+} from "xertica-ui"
+
+<AlertDialog>
+  <AlertDialogTrigger asChild>
+    <Button variant="destructive">Apagar Conta</Button>
+  </AlertDialogTrigger>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle>Você tem absoluta certeza?</AlertDialogTitle>
+      <AlertDialogDescription>
+        Essa ação é irreversível e excluirá permanentemente seus dados dos nossos servidores.
+      </AlertDialogDescription>
+    </AlertDialogHeader>
+    <AlertDialogFooter>
+      <AlertDialogCancel>Cancelar</AlertDialogCancel>
+      <AlertDialogAction className="bg-destructive text-destructive-foreground hover:bg-destructive/90">
+        Sim, excluir
+      </AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
+## Regras para IA
+- Em aplicações React orientadas a estado, você pode controlar externamente ligando a prop `open={isOpen}` e escutando `onOpenChange={setIsOpen}` no Root, omitindo o `Trigger` local.

package/docs/components/alert.md

@@ -0,0 +1,36 @@
+# Alert
+
+## Descrição
+Blocos informativos fixos e destacados para alertar o usuário de algo importante que não deve ser descartável e exige leitura compulsória na mesma página.
+
+## Quando usar
+- Erros de validação críticos do formulário, que bloqueiam uso inteiro.
+- Avisos do tipo (Sua versão Free expira em 3 dias).
+- Banner Empty State ou avisos sobre funcionalidade desativada.
+
+## Quando NÃO usar
+- Notificações de sucessos transientes "Cadastrado com sucesso!". Nesses casos, use **Sonner** (`toast()`).
+- Para blocos apenas de dados informativos contextuais. Dê preferência a `Card`.
+
+## Variações Formais
+- `default`
+- `destructive`
+
+## Exemplo mínimo
+
+```tsx
+import { Alert, AlertDescription, AlertTitle } from 'xertica-ui';
+import { Terminal } from 'lucide-react';
+
+<Alert>
+  <Terminal className="h-4 w-4" />
+  <AlertTitle>Fique Atento!</AlertTitle>
+  <AlertDescription>
+    Você pode adicionar componentes interativos para seus alertas futuramente.
+  </AlertDescription>
+</Alert>
+```
+
+## Regras para IA
+- Alert demanda a composição `Alert Title` e `Alert Description` para garantir espaçamento interno perfeito. O uso do ícone dentro (passado antes do `AlertTitle`) também é muito encorajado e alinha corretamente.
+- Nunca adicione background ou borders por conta própria (explicado em Guidelines) a não ser que pretenda gerar uma variante inteiramente nova temporária.

package/docs/components/aspect-ratio.md

@@ -0,0 +1,26 @@
+# Aspect Ratio
+
+## Descrição
+Força uma proporção delimitada (largura/altura) em um bloco de interface responsivo contendo embeds, iframes ou Imóveis fotográficos complexos. 
+
+## Quando usar
+- Para exibir Imagens de Capa (`16/9`), Avatares Gigescos Quadratura (`1/1`), Videos de Youtube (`16/9`).
+
+## Exemplo mínimo
+
+```tsx
+import { AspectRatio } from "xertica-ui"
+
+<div className="w-[450px]">
+  <AspectRatio ratio={16 / 9} className="bg-muted">
+    <img
+      src="/placeholder.png"
+      alt="Capa de Vídeo"
+      className="rounded-md object-cover w-full h-full"
+    />
+  </AspectRatio>
+</div>
+```
+
+## Regras para IA
+- O filho injetado que dita o conteúdo deve preencher o invólucro do `AspectRatio` com classes unificadas (ex `w-full h-full object-cover`), senão o calculo matemático de padding-bottom provido no Radix fica quebrado.

package/docs/components/assistant.md

@@ -0,0 +1,41 @@
+# Xertica Assistant
+
+## Descrição
+Interface de conversação inteligente (Chatbot) projetada para integrar IA generativa diretamente no Design System xertica-ui.
+
+## Quando usar
+- Implementação de copilotos de navegação.
+- Auxiliar de suporte ao usuário dentro da plataforma.
+- Ferramenta de análise de dados interativa (usando tabelas e gráficos injetados na resposta).
+
+## Modos de Exibição
+- `collapsed`: Apenas ícones laterais, ocupando espaço mínimo.
+- `expanded` (Padrão): Painel lateral completo que pode ser aberto/fechado.
+- `fullPage`: Ocupa 100% da viewport, ideal para páginas dedicadas de "AI Chat".
+
+## Exemplo Estruturado
+
+```tsx
+import { XerticaAssistant } from "xertica-ui"
+
+<XerticaAssistant 
+  userName="Marcos"
+  mode="expanded"
+  isExpanded={true}
+  suggestions={[
+    { id: '1', texto: 'Resuma os relatórios de hoje' },
+    { id: '2', texto: 'Quantos usuários estão ativos?' }
+  ]}
+  onSendMessage={(text) => handleAiResponse(text)}
+/>
+```
+
+## Respostas Ricas
+O assistente suporta a injeção de componentes nas mensagens via `Message` interface:
+- `chartData` e `chartConfig`: Renderiza gráficos automáticos na bolha de resposta.
+- `tableData`: Renderiza tabelas formatadas.
+- `documentContent`: Abre visualização de documento lada a lado.
+
+## Regras para IA
+- No modo `expanded`, controle o estado de abertura via `isExpanded` e `onToggle`.
+- Para simular respostas instantâneas sem backend real em protótipos, utilize a prop `demoMode={true}` e, opcionalmente, `responseGenerator`.

package/docs/components/avatar.md

@@ -0,0 +1,32 @@
+# Avatar
+
+## Descrição
+Representação gráfica e visual de uma Entidade, Usuário ou Organização.
+
+## Quando usar
+- Fotos de perfil no header da aplicação.
+- Identificação de linhas de uma Tabela de Usuários.
+- Autoria de Comentários ou Atividades.
+
+## Estrutura OBRIGATÓRIA
+- `Avatar` (Root)
+- `AvatarImage` (Tenta carregar o src fornecido, emitindo onerror se falhar).
+- `AvatarFallback` (Alternativa em texto, usualmente as Iniciais).
+
+## Exemplo mínimo
+
+```tsx
+import { Avatar, AvatarFallback, AvatarImage } from "xertica-ui"
+
+export function AvatarDemo() {
+  return (
+    <Avatar>
+      <AvatarImage src="https://github.com/shadcn.png" alt="@xertica" />
+      <AvatarFallback>XC</AvatarFallback>
+    </Avatar>
+  )
+}
+```
+
+## Regras para IA
+- Em aplicações complexas, nunca use `img` puros para avatares, porque se a imagem vier 404 da nuvem nativamente exibirá um icon quebrado péssimo. O `AvatarFallback` dita o padrão estético salva-vidas para links partidos.

package/docs/components/badge.md

@@ -0,0 +1,30 @@
+# Badge
+
+## Descrição
+Pequenos blocos informacionais sem formato de interação para indicação textual/status rápida. Etiqueta.
+
+## Quando usar
+- Informar Status em Tabela (ex: Ativo, Inativo).
+- Enumerar categorias (Tags: *Front-end*, *NodeJS*).
+- Contadores.
+
+## Quando NÃO usar
+- Ações clicáveis que levam a caminhos grandes (para interações clicáveis prefira Button sizes compactos, ou Tags filtráveis específicas se o sistema tiver design system advanced, ou simplesmente atrele role="button" ao Badge com cuidado de navegação limitante).
+
+## Variações Formais
+- `default`
+- `secondary`
+- `destructive`
+- `outline`
+
+## Exemplo mínimo
+
+```tsx
+import { Badge } from 'xertica-ui';
+
+<Badge variant="outline">Em Processamento</Badge>
+```
+
+## Regras para IA
+- Não crie variações semânticas que não existem nativamente (como `variant="success"` ou `variant="warning"`). Se você precisa de *status styles*, no Xertica UI aplique *Tailwind Override*: `<Badge className="bg-emerald-500 hover:bg-emerald-600">Ativo</Badge>`.
+- Use a variante `outline` frequentemente quando as badges forem mais neutras e numerosas em Grid Systems para diminuir o cansaço visual.