xertica-ui 1.5.0 → 1.5.2

package/components/Sidebar.tsx

@@ -139,6 +139,19 @@ interface SidebarProps {
   navigationGroups?: RouteGroup[];
 }
 
+/**
+ * Sidebar e Navegação Principal.
+ * 
+ * @description
+ * Componente complexo que gerencia renderização em Desktop/Mobile com suporte a:
+ * - Modo Normal (Lista Simples)
+ * - Modo Assistent (Grupos, Pesquisa, Áreas Fixas)
+ * 
+ * @ai-rules
+ * 1. NUNCA tente reinventar a Sidebar com classes tailwind. SEMPRE injete este componente no `layout` da aplicação (seja `App.tsx` ou em layout do Next.js).
+ * 2. Utilize a prop apropriada `variant="assistant"` ou `variant="default"`.
+ * 3. Garanta que o callback `navigate` manipule as rotas do seu roteador local.
+ */
 export function Sidebar({
   expanded,
   onToggle,

package/components/ui/accordion.tsx

@@ -6,6 +6,16 @@ import { ChevronDownIcon } from "lucide-react";
 
 import { cn } from "./utils";
 
+/**
+ * Gerenciador de exibição oculta (collapse) vertical focada em empilhamento.
+ * 
+ * @description
+ * Baseado em Radix UI Accordion para garantir acessibilidade via teclado.
+ * 
+ * @ai-rules
+ * 1. `AccordionItem` REQUER OBRIGATORIAMENTE a prop `value`. Sem ela a lógica local quebra.
+ * 2. Em type="single", o accordion só abre um e fecha os outros. Requer prop `collapsible` para que possa fechar a si mesmo.
+ */
 function Accordion({
   ...props
 }: React.ComponentProps<typeof AccordionPrimitive.Root>) {

package/components/ui/alert-dialog.tsx

@@ -6,6 +6,16 @@ import * as AlertDialogPrimitive from "@radix-ui/react-alert-dialog";
 import { cn } from "./utils";
 import { buttonVariants } from "./button";
 
+/**
+ * Diálogo estrito de requisição de ação destrutiva.
+ * 
+ * @description
+ * Um modal que força interação (Sim/Não) bloqueando cliques fora de foco para evitar aceitação acidental.
+ * 
+ * @ai-rules
+ * 1. Diferentemente do Dialog, exige imperativamente a bifurcação nos subcomponentes `<AlertDialogCancel>` ou `<AlertDialogAction>`.
+ * 2. Empregue somente em fluxos sem volta permanente. Para Informes simples, utilize apenas o `Dialog`.
+ */
 function AlertDialog({
   ...props
 }: React.ComponentProps<typeof AlertDialogPrimitive.Root>) {

package/components/ui/alert.tsx

@@ -38,6 +38,17 @@ export interface AlertProps
   icon?: React.ReactNode;
 }
 
+/**
+ * Bloco informativo fixo para chamar a atenção do usuário no fluxo de leitura.
+ * 
+ * @description
+ * Ideal para exibir validações críticas não transientes ou alertas contextuais.
+ * Contém um ícone inerente baseado na variante (pode ser sobrescrito).
+ * 
+ * @ai-rules
+ * 1. Sempre use a estrutura completa com `AlertTitle` e `AlertDescription` para não quebrar a tipografia interna.
+ * 2. Em telas divididas ou estreitas, o Alert se adapta preenchendo 100% da largura.
+ */
 function Alert({
   className,
   variant,

package/components/ui/aspect-ratio.tsx

@@ -2,6 +2,16 @@
 
 import * as AspectRatioPrimitive from "@radix-ui/react-aspect-ratio";
 
+/**
+ * Proporcionalizador de mídia em container geométrico exato.
+ * 
+ * @description
+ * Permite setar Box `16/9` ou `1/1` responsivo à largura para prevenir Layout-Shift CLS em Imagens.
+ * 
+ * @ai-rules
+ * 1. Insira `ratio={16/9}` na raiz.
+ * 2. Force o componente filho (ex `<img>` ou `<video>`) a usar `w-full h-full object-cover`.
+ */
 function AspectRatio({
   ...props
 }: React.ComponentProps<typeof AspectRatioPrimitive.Root>) {

package/components/ui/avatar.tsx

@@ -5,6 +5,16 @@ import * as AvatarPrimitive from "@radix-ui/react-avatar";
 
 import { cn } from "./utils";
 
+/**
+ * Componente gráfico representativo de entidades e contas (Fotos de Perfil).
+ * 
+ * @description
+ * Gerencia nativamente erros 404 e timeouts de imagens com fallback textual (Iniciais).
+ * 
+ * @ai-rules
+ * 1. Em layouts complexos nunca coloque elementos HTML `<img>` para Perfil do Usuário; o Fallback interno previne UI quebras.
+ * 2. Instancie Root `<Avatar>`, `<AvatarImage>` e por fim `<AvatarFallback>` todos juntos.
+ */
 function Avatar({
   className,
   size = "md",

package/components/ui/badge.tsx

@@ -31,6 +31,16 @@ const badgeVariants = cva(
   },
 );
 
+/**
+ * Etiqueta informacional de status.
+ * 
+ * @description
+ * Indicador visual para tabelas, contadores e pequenas marcações. Não deve ser acionável.
+ * 
+ * @ai-rules
+ * 1. Evite o uso da prop genérica `className` para forçar cores, utilize as variantes adequadas.
+ * 2. Em listas densas, a variação `outline` diminui o peso visual.
+ */
 export function Badge({
   className,
   variant,

package/components/ui/breadcrumb.tsx

@@ -4,6 +4,16 @@ import { ChevronRight, MoreHorizontal } from "lucide-react";
 
 import { cn } from "./utils";
 
+/**
+ * Navegação hierárquica histórica.
+ * 
+ * @description
+ * Permite que usuários vejam exatamente a hierarquia até a página atual e voltem níveis com facilidade.
+ * 
+ * @ai-rules
+ * 1. Último nível sempre deve ser `<BreadcrumbPage>`, os do meio `<BreadcrumbLink>`.
+ * 2. Não insira `/` como string nativa, utilize o `<BreadcrumbSeparator>`.
+ */
 function Breadcrumb({ ...props }: React.ComponentProps<"nav">) {
   return <nav aria-label="breadcrumb" data-slot="breadcrumb" {...props} />;
 }

package/components/ui/button.tsx

@@ -35,14 +35,40 @@ const buttonVariants = cva(
   },
 );
 
-const Button = React.forwardRef<
-  HTMLButtonElement,
-  React.ComponentProps<"button"> &
-    VariantProps<typeof buttonVariants> & {
-      asChild?: boolean;
-      loading?: boolean;
-    }
->(({
+/**
+ * Props para o componente Button.
+ * 
+ * @interface ButtonProps
+ */
+export interface ButtonProps
+  extends React.ComponentProps<"button">,
+    VariantProps<typeof buttonVariants> {
+  /** 
+   * Se true, renderiza o componente filho substituindo a tag <button>. 
+   * Útil para injetar o estilo de botão em links (<Link href="...">).
+   */
+  asChild?: boolean;
+  /** Se true, desabilita o botão e mostra um spinner de carregamento preservando a largura. */
+  loading?: boolean;
+}
+
+/**
+ * Botão principal do Design System Xertica.
+ * 
+ * @description
+ * Componente obrigatório para todas as interações de clique que não sejam navegação nativa.
+ * 
+ * @usage
+ * ```tsx
+ * <Button variant="default" onClick={submit}>Salvar</Button>
+ * ```
+ * 
+ * @ai-rules
+ * 1. NUNCA utilize a tag `<button>` nativa.
+ * 2. Em formulários, use `type="submit"` implicitamente.
+ * 3. Se precisar parecer um link, use `variant="link"`. Se precisar agir como link com aparência de botão, use `asChild` envelopando na Tag de Navegação.
+ */
+const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(({
   className,
   variant,
   size,

package/components/ui/calendar.tsx

@@ -11,6 +11,16 @@ import {
 import { cn } from "./utils"
 import { Button, buttonVariants } from "./button"
 
+/**
+ * Componente seletor de Data montado no `react-day-picker`.
+ * 
+ * @description
+ * Renderiza um calendário complexo mensal/anual customizado para a Xertica UI.
+ * 
+ * @ai-rules
+ * 1. Frequentemente invocado dentro de menus Popover para virar um DatePicker em Formulários.
+ * 2. Controle a data via propriedade OBRIGATÓRIA `selected={Date}`.
+ */
 function Calendar({
   className,
   classNames,

package/components/ui/card.tsx

@@ -2,6 +2,17 @@ import * as React from "react";
 
 import { cn } from "./utils";
 
+/**
+ * Base estrutural para agrupamento de conteúdo (Superfícies).
+ * 
+ * @description
+ * Dá volume e delimita um assunto visualmente, controlando cor de fundo (`bg-card`),
+ * arredondamento e paddings internos.
+ * 
+ * @ai-rules
+ * 1. NUNCA crie divs cruas com `bg-white dark:bg-black rounded border shadow`. Utilize `<Card>`!
+ * 2. Componentize as descrições no interior usando a ordem semântica (`CardHeader` > `CardContent` > `CardFooter`).
+ */
 function Card({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div

package/components/ui/carousel.tsx

@@ -42,6 +42,16 @@ function useCarousel() {
   return context;
 }
 
+/**
+ * Visualizador horizonal fluido (Carrossel).
+ * 
+ * @description
+ * Baseado no embla-carousel. A manipulação do grid é via flex-basis (`basis-1/3`).
+ * 
+ * @ai-rules
+ * 1. OBRIGATORIAMENTE use as arrows providenciadas `CarouselPrevious` e `CarouselNext` se for para ter controles paralelos interativos.
+ * 2. NUNCA coloque Tabelas infinitas dentro de um Carrocel, eles servem primáriamente para Banners/Cards. Use `ScrollArea`.
+ */
 function Carousel({
   orientation = "horizontal",
   opts,

package/components/ui/chart.tsx

@@ -34,6 +34,16 @@ function useChart() {
   return context;
 }
 
+/**
+ * Invólucro master do motor Recharts focado em Theme Injecting.
+ * 
+ * @description
+ * Substitui injeção manual de temas para `recharts`. A leitura de Tailwind configs faz-se aqui.
+ * 
+ * @ai-rules
+ * 1. Nunca passe colors Hex diretamente num `<Bar dataKey="..." fill="..." />` do Recharts. Use a injeção via `fill="var(--color-meuchart)"`.
+ * 2. O wrapper é mandatório para usar os subs `ChartLegend` e `ChartTooltip`.
+ */
 function ChartContainer({
   id,
   className,

package/components/ui/checkbox.tsx

@@ -6,6 +6,25 @@ import { Check } from "lucide-react";
 
 import { cn } from "./utils";
 
+/**
+ * Componente de Checkbox nativo do Radix UI estilizado.
+ * 
+ * @description
+ * Usado para capturar marcação múltipla ou boolean única (Ex: Aceite termos).
+ * 
+ * @usage
+ * ```tsx
+ * <div className="flex items-center space-x-2">
+ *   <Checkbox id="terms" />
+ *   <label htmlFor="terms">Aceitar termos</label>
+ * </div>
+ * ```
+ * 
+ * @ai-rules
+ * 1. NUNCA utilize `<input type="checkbox">` nativo.
+ * 2. Sempre envolva ou posicione ao lado de um `<label>` real usando `id` e `htmlFor` idênticos.
+ * 3. Para formulários Zod, utilize no contexto de `<FormControl>`.
+ */
 const Checkbox = React.forwardRef<
   React.ElementRef<typeof CheckboxPrimitive.Root>,
   React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>

package/components/ui/collapsible.tsx

@@ -2,6 +2,15 @@
 
 import * as CollapsiblePrimitive from "@radix-ui/react-collapsible";
 
+/**
+ * Painel isolado que expõe e contrai um bloco de conteúdo (Collapse).
+ * 
+ * @description
+ * Ao contrário do Accordion, opera isoladamente e não controla irmãos na árvore DOm.
+ * 
+ * @ai-rules
+ * 1. Requer OBRIGATORIAMENTE que o Agent providencie no filho `CollapsibleTrigger` um `<Button>` indicativo (geralmente com ícone Chevron).
+ */
 function Collapsible({
   ...props
 }: React.ComponentProps<typeof CollapsiblePrimitive.Root>) {

package/components/ui/command.tsx

@@ -13,6 +13,16 @@ import {
   DialogTitle,
 } from "./dialog";
 
+/**
+ * Menu de comandos pesquisáveis (Cmd+K / Spotlight).
+ * 
+ * @description
+ * Baseado no cmdk. Abstrai a lógica da barra de busca que filtra grupos densos instantaneamente.
+ * 
+ * @ai-rules
+ * 1. CommandInput não leva form-states. Ele apenas filtra nativamente o `CommandList` da DOM em tempo real.
+ * 2. `CommandItem` requer obrigatoriamente a prop `value` para ser indexado e filtrável por texto quando o componente filho interno não for apenas texto bruto.
+ */
 function Command({
   className,
   ...props

package/components/ui/context-menu.tsx

@@ -6,6 +6,16 @@ import { CheckIcon, ChevronRightIcon, CircleIcon } from "lucide-react";
 
 import { cn } from "./utils";
 
+/**
+ * Menu local capturável pelo evento Direito do Mouse (Right-click).
+ * 
+ * @description
+ * Traz a responsividade do OS para dentro das aplicações pesadas (Right click para ver opções de Tabela).
+ * 
+ * @ai-rules
+ * 1. Não é ativado por cliques esquerdos típicos. Em Mobile puritanos é pouco usual sem abstração.
+ * 2. O `ContextMenuTrigger` deve cobrir visualmente o local do clique com dimensões claras na tela.
+ */
 function ContextMenu({
   ...props
 }: React.ComponentProps<typeof ContextMenuPrimitive.Root>) {

package/components/ui/dialog.tsx

@@ -7,6 +7,18 @@ import { cva, type VariantProps } from "class-variance-authority";
 
 import { cn } from "./utils";
 
+/**
+ * Componente modal (overlay) que interrompe o fluxo para interação focada do usuário.
+ * 
+ * @description
+ * Use isso para formulários de criação ("Criar Entidade"), telas de configuração 
+ * restritas ou alertas massivos de tela cheia.
+ * 
+ * @ai-rules
+ * 1. Sempre componha a ordem: `Dialog > DialogTrigger > DialogContent > (Header, Content, Footer)`.
+ * 2. O `DialogTrigger` frequentemente precisa do prop genérico `asChild` se aninhar um `<Button>`.
+ * 3. NUNCA utilize a tag HTML `<dialog>`. 
+ */
 function Dialog({
   ...props
 }: React.ComponentProps<typeof DialogPrimitive.Root>) {

package/components/ui/drawer.tsx

@@ -5,6 +5,16 @@ import { Drawer as DrawerPrimitive } from "vaul";
 
 import { cn } from "./utils";
 
+/**
+ * Painel de gaveta acessível (Mobile-first).
+ * 
+ * @description
+ * Substitui modais no dispositivo móvel subindo um painel puxável a partir do rodapé.
+ * 
+ * @ai-rules
+ * 1. Semelhante ao Dialog genérico, componha com `DrawerTrigger`, `DrawerContent`, `DrawerHeader`, `DrawerFooter`.
+ * 2. Em telas mobile corporativas, prefira o Drawer para ações detalhadas e o Sheet exclusivo para Menus Ocultos de Navbar.
+ */
 function Drawer({
   ...props
 }: React.ComponentProps<typeof DrawerPrimitive.Root>) {

package/components/ui/dropdown-menu.tsx

@@ -6,6 +6,18 @@ import { CheckIcon, ChevronRightIcon, CircleIcon } from "lucide-react";
 
 import { cn } from "./utils";
 
+/**
+ * Menu suspenso de comandos e ações locais.
+ * 
+ * @description
+ * Ao contrário do `<Select>`, o DropdownMenu não deve ser usado para preencher valores em inputs 
+ * mas sim disparar ações (Ex: Abrir Perfil, Excluir Documento, Mover).
+ * 
+ * @ai-rules
+ * 1. A composição requer a raiz `<DropdownMenu>` contendo `<DropdownMenuTrigger>` e `<DropdownMenuContent>`.
+ * 2. Itens internos são criados via `<DropdownMenuItem>`.
+ * 3. Se o Trigger abraçar um `<Button>` não-nativo, inclua OBRIGATORIAMENTE o prop genérico `asChild` no Trigger.
+ */
 function DropdownMenu({
   ...props
 }: React.ComponentProps<typeof DropdownMenuPrimitive.Root>) {

package/components/ui/empty.tsx

@@ -1,6 +1,16 @@
 import * as React from "react";
 import { cn } from "./utils";
 
+/**
+ * Componente representativo figurativo de uma Entidade sem Registro no DB.
+ * 
+ * @description
+ * Substitui caixas vazias ou SVGs puros soltos pra comunicar que a query resultou em 0 achados.
+ * 
+ * @ai-rules
+ * 1. NUNCA crie divs cruas "Nenhum valor achado". Use `<Empty> > <EmptyTitle> > <EmptyDescription>`.
+ * 2. Alinhe botões de CTA dentro de `<EmptyAction>`.
+ */
 const Empty = React.forwardRef<
   HTMLDivElement,
   React.HTMLAttributes<HTMLDivElement>

package/components/ui/file-upload.tsx

@@ -10,6 +10,17 @@ interface FileUploadProps extends Omit<React.InputHTMLAttributes<HTMLInputElemen
   showPreview?: boolean;
 }
 
+/**
+ * Componente para upload de arquivos com suporte a drag-and-drop.
+ * 
+ * @description
+ * Gerencia o estado de arquivos selecionados e fornece uma interface padronizada para upload.
+ * 
+ * @ai-rules
+ * 1. Utilize `FileUploadTrigger` para definir a área de clique/arraste.
+ * 2. Utilize `FileUploadList` para exibir a lista de arquivos selecionados automaticamente.
+ * 3. Integre com `onChange` para capturar a lista de arquivos no estado do formulário.
+ */
 const FileUpload = React.forwardRef<HTMLDivElement, FileUploadProps>(
   ({ 
     className, 

package/components/ui/form.tsx

@@ -14,6 +14,18 @@ import {
 import { cn } from "./utils";
 import { Label } from "./label";
 
+/**
+ * Provedor raiz e controller de formulários.
+ *
+ * @description
+ * Envelopa instâncias de `react-hook-form` e provê o contexto global do formário 
+ * para os componentes filhos (`FormField`, `FormControl`, `FormMessage`).
+ * 
+ * @ai-rules
+ * 1. Sempre instancie este envolucro na extremidade do `return` de um formulário.
+ * 2. O hook `useForm` (com injetor Zod) é PRÉ-REQUISITO para usar este contexto.
+ * 3. Não crie inputs stateful com `useState` se já estiver dentro desta casca.
+ */
 const Form = FormProvider;
 
 type FormFieldContextValue<

package/components/ui/hover-card.tsx

@@ -5,6 +5,15 @@ import * as HoverCardPrimitive from "@radix-ui/react-hover-card";
 
 import { cn } from "./utils";
 
+/**
+ * Overlay exibido no Hover exibindo um preview de um entidade.
+ * 
+ * @description
+ * Nativamente otimizado com timeouts e debounces para não sobrecarregar a UX se o cursor passar velozmente por cima.
+ * 
+ * @ai-rules
+ * 1. Se usado sob `<Avatar>` ou tags HTML literais `<a href>`, lembre-se do `asChild` prop no `HoverCardTrigger`.
+ */
 function HoverCard({
   ...props
 }: React.ComponentProps<typeof HoverCardPrimitive.Root>) {

package/components/ui/input-otp.tsx

@@ -6,6 +6,16 @@ import { MinusIcon } from "lucide-react";
 
 import { cn } from "./utils";
 
+/**
+ * Input formatado para códigos de uso único (OTP).
+ * 
+ * @description
+ * Divide o input em slots individuais para facilitar a digitação de códigos de verificação.
+ * 
+ * @ai-rules
+ * 1. O `maxLength` no Root deve corresponder ao número total de `InputOTPSlot`s.
+ * 2. Utilize `InputOTPGroup` para agrupar slots e `InputOTPSeparator` para divisores visuais.
+ */
 function InputOTP({
   className,
   containerClassName,

package/components/ui/input.tsx

@@ -2,10 +2,33 @@ import * as React from "react";
 
 import { cn } from "./utils";
 
-interface InputProps extends Omit<React.ComponentProps<"input">, "size"> {
+/**
+ * Props para o componente Input.
+ *
+ * @interface InputProps
+ */
+export interface InputProps extends Omit<React.ComponentProps<"input">, "size"> {
+  /** Define o tamanho vertical e padding do input. */
   size?: "sm" | "md" | "lg";
 }
 
+/**
+ * Campo de entrada de dados simples.
+ *
+ * @description
+ * Usado para capturar inputs de texto curto, senhas e números. Deve ser usado preferencialmente
+ * dentro de um `FormField` em aplicações que manipulam estado de formulário.
+ *
+ * @usage
+ * ```tsx
+ * <Input type="email" placeholder="nome@exemplo.com" />
+ * ```
+ *
+ * @ai-rules
+ * 1. NUNCA utilize a tag `<input>` nativa.
+ * 2. Em formulários grandes conecte ao `react-hook-form` via `<FormControl>`.
+ * 3. Para blocos grandes de texto multi-linha (Descrição, Biografia), use o componente `<Textarea>` adequado, nunca `<Input>`.
+ */
 const Input = React.forwardRef<HTMLInputElement, InputProps>(
   ({ className, type, size = "md", ...props }, ref) => {
     const sizeClasses = {

package/components/ui/label.tsx

@@ -5,6 +5,16 @@ import * as LabelPrimitive from "@radix-ui/react-label";
 
 import { cn } from "./utils";
 
+/**
+ * Etiqueta acessível para campos de formulário.
+ * 
+ * @description
+ * Estilização padronizada para labels, com suporte a estados de erro e desabilitado.
+ * 
+ * @ai-rules
+ * 1. Sempre associe ao input correspondente usando `htmlFor` e o `id` do input.
+ * 2. No contexto de `Form`, prefira o uso de `FormLabel`.
+ */
 function Label({
   className,
   ...props

package/components/ui/map.tsx

@@ -411,6 +411,18 @@ const MapContent = React.forwardRef<HTMLDivElement, MapProps & { apiKey: string
 );
 MapContent.displayName = "MapContent";
 
+/**
+ * Componente principal de Mapas baseado em Google Maps.
+ * 
+ * @description
+ * Suporta Advanced Markers, Círculos, Polígonos e Camadas personalizadas.
+ * Carrega automaticamente a API do Google Maps via `useGoogleMapsLoader`.
+ * 
+ * @ai-rules
+ * 1. OBRIGATÓRIO: Fornecer uma `apiKey` válida via prop ou variável de ambiente `VITE_GOOGLE_MAPS_API_KEY`.
+ * 2. Utilize a prop `markers` para renderizar pontos de interesse, suportando `richContent` para InfoWindows React.
+ * 3. Defina `height` explicitamente (default é 400px) para garantir visibilidade no layout.
+ */
 export const Map = React.forwardRef<HTMLDivElement, MapProps>(
   (props, ref) => {
     const { isLoaded, loadError } = useGoogleMapsLoader();

package/components/ui/menubar.tsx

@@ -6,6 +6,16 @@ import { CheckIcon, ChevronRightIcon, CircleIcon } from "lucide-react";
 
 import { cn } from "./utils";
 
+/**
+ * Barra de menus navegacional densa no topo (Estilo Apple / Aplicativo Win).
+ * 
+ * @description
+ * Arquitetura de dropdowns massiva idealizada para IDEs e Editores Web focados em Dados/Mídias.
+ * 
+ * @ai-rules
+ * 1. Menubar não deve substituir a navegação padrão por `<Tabs>` se não houverem dezenas de itens.
+ * 2. Em `<MenubarShortcut>`, nunca force tipografia extravagante, o silêncio visual das hotkeys já está previsto ali dentreo.
+ */
 function Menubar({
   className,
   ...props

package/components/ui/navigation-menu.tsx

@@ -5,6 +5,16 @@ import { ChevronDownIcon } from "lucide-react";
 
 import { cn } from "./utils";
 
+/**
+ * Menu de navegação complexo para headers de aplicações.
+ * 
+ * @description
+ * Suporta submenus ricos e transições suaves, ideal para navegação principal.
+ * 
+ * @ai-rules
+ * 1. Utilize `NavigationMenuTrigger` para itens com dropdown e `NavigationMenuLink` para links diretos.
+ * 2. Envolva o conteúdo do dropdown em `NavigationMenuContent`.
+ */
 function NavigationMenu({
   className,
   children,

package/components/ui/notification-badge.tsx

@@ -9,6 +9,16 @@ interface NotificationBadgeProps extends React.HTMLAttributes<HTMLDivElement> {
   variant?: "default" | "primary" | "destructive";
 }
 
+/**
+ * Indicador visual de notificações ou contagens.
+ * 
+ * @description
+ * Pequena bolha flutuante para mostrar quantidade ou um ponto de alerta.
+ * 
+ * @ai-rules
+ * 1. Use a prop `count` para números ou `dot` para apenas um indicador visual.
+ * 2. Posicione no canto superior direito do elemento pai usando classes de utilidade.
+ */
 const NotificationBadge = React.forwardRef<HTMLDivElement, NotificationBadgeProps>(
   ({ 
     className, 

package/components/ui/page-header.tsx

@@ -83,6 +83,16 @@ export interface PageHeaderProps {
 // Component
 // ============================================================================
 
+/**
+ * Componente modular padronizado de cabeçalho de telas densas.
+ * 
+ * @description
+ * Engloba títulos, subtítulos (descrições) e blocos de ações alinhados.
+ * 
+ * @ai-rules
+ * 1. Utilize SEMPRE a trinca `PageHeader > PageHeaderHeading / PageHeaderDescription`.
+ * 2. Se houver grupo de botões, use `<PageActions>` englobando-os no lado direito.
+ */
 export function PageHeader({
   breadcrumbs,
   showLanguageSelector = false,

package/components/ui/pagination.tsx

@@ -8,6 +8,16 @@ import {
 import { cn } from "./utils";
 import { Button, buttonVariants } from "./button";
 
+/**
+ * Navegação de páginas em massa.
+ * 
+ * @description
+ * Envelopa a navegação no eixo horizontal com links, elipses e controles Previous/Next.
+ * 
+ * @ai-rules
+ * 1. Componha na ordem exata: `Pagination > PaginationContent > PaginationItem > (PaginationLink | PaginationNext | PaginationPrevious)`.
+ * 2. Em Single Page Applications (SPA), modifique os `href` de `PaginationLink` para `href="#"` e reaja via `onClick` para evitar reloads de página nativos do HTML.
+ */
 function Pagination({ className, ...props }: React.ComponentProps<"nav">) {
   return (
     <nav