nocturna-ui 0.0.3 → 0.0.5

package/README.md

@@ -2,69 +2,136 @@
 
 > **Primitivos góticos e brutalistas forjados para a web que não teme a escuridão.**
 
-A **Nocturna UI** é uma biblioteca de componentes React focada em interfaces de alto contraste, tipografia serifada e estética minimalista/gótica. Na v0.0.2, expandimos nosso arsenal com componentes complexos e foco total em acessibilidade.
+A **Nocturna UI** é uma biblioteca de componentes React focada em interfaces de alto contraste, tipografia serifada e estética minimalista.
 
-[Showcase (DEMO)](https://gothd.github.io/nocturna-ui/) | [NPM](https://www.npmjs.com/package/nocturna-ui) | [UNPKG](https://unpkg.com/nocturna-ui/)
+Na **v0.0.5**, introduzimos o sistema de **Aliases**, permitindo importações mais limpas (ex: `Button` ao invés de `VoidButton`), e melhoramos a cobertura de testes.
+
+[![NPM Version](https://img.shields.io/npm/v/nocturna-ui?color=000000&label=npm&style=flat-square)](https://www.npmjs.com/package/nocturna-ui)
+[![Tests](https://github.com/gothd/nocturna-ui/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/gothd/nocturna-ui/actions)
+[![Coverage](https://img.shields.io/codecov/c/github/gothd/nocturna-ui?style=flat-square&color=white)](https://codecov.io/gh/gothd/nocturna-ui)
 
 ---
 
-## 🕸️ Componentes Disponíveis
+## 🔮 Documentação Completa
+
+Para ver os componentes em ação, tabelas de propriedades interativas e exemplos avançados, visite nosso Grimório Digital:
+
+### [👉 Acessar Documentação (Playground)](https://gothd.github.io/nocturna-ui/)
+
+---
 
-| Primitivo             | Descrição                                                     |
-| :-------------------- | :------------------------------------------------------------ |
-| **VoidButton**        | Botão brutalista com suporte a tamanhos sm/md/lg.             |
-| **CryptModal**        | Modal com portal e trava de foco para acessibilidade.         |
-| **RitualSelect**      | Select customizado com suporte total a navegação via teclado. |
-| **GrimoireAccordion** | Acordeão com animação de altura dinâmica via Framer Motion.   |
-| **SoulTabs**          | Sistema de abas para organização de conteúdos densos.         |
-| **VeinInput**         | Input de texto com estados de erro e animação de pulso.       |
-| **HexCheckbox**       | Checkbox temático com animação de escala.                     |
-| **AbyssSeparator**    | Divisor de seção com suporte a labels e sigilos.              |
-| **SigilBadge**        | Emblemas para status e tags em versões Solid ou Outline.      |
-| **NocturnaCard**      | Container clássico com sombras rígidas (hard shadows).        |
+## 🌑 Instalação
 
-## 🌑 Requisitos de Instalação (Peer Dependencies)
+```bash
+npm install nocturna-ui
+```
 
-Para evitar conflitos de instâncias do React (como o erro de `useState` nulo), a **Nocturna UI** utiliza `peerDependencies`. Certifique-se de que seu projeto possua:
+### Dependências
 
-- **React** (^18.0.0)
-- **React-DOM** (^18.0.0)
-- **Framer Motion** (^11.0.0)
+A biblioteca requer React e Framer Motion.
 
 ```bash
 npm install react react-dom framer-motion
 ```
 
-## 📜 Uso via CDN (UMD)
+---
+
+## 🩸 Setup Inicial
+
+Para que os componentes funcionem corretamente, você deve importar o CSS global e envolver sua aplicação no `OmenToastProvider` (mesmo que não use notificações imediatamente, ele configura contextos globais).
+
+```tsx
+// No seu arquivo raiz (main.tsx ou App.tsx)
+import { OmenToastProvider } from "nocturna-ui";
+import "nocturna-ui/style.css"; // ⚠️ Importação vital dos estilos
+
+export default function App({ children }) {
+  return <OmenToastProvider>{children}</OmenToastProvider>;
+}
+```
+
+---
+
+## 🕸️ Uso Básico (Aliases)
 
-Para utilizar a biblioteca diretamente no navegador, a ordem dos scripts é fundamental para que as globais sejam injetadas corretamente:
+Você não precisa mais decorar nomes místicos como `VoidButton` ou `CryptModal`. Utilize os Aliases funcionais:
+
+```tsx
+import { Button, Card, Badge, useToast } from "nocturna-ui";
+
+export const Ritual = () => {
+  const { toast } = useToast();
+
+  return (
+    <Card title="Invocação">
+      <div className="flex gap-4 mb-4">
+        <Badge variant="blood">Status: Pendente</Badge>
+      </div>
+
+      <Button
+        variant="void"
+        onClick={() => toast({ title: "Pacto Realizado", type: "success" })}
+      >
+        Confirmar
+      </Button>
+    </Card>
+  );
+};
+```
+
+### Tabela de Aliases
+
+| Alias      | Componente Original | Função               |
+| ---------- | ------------------- | -------------------- |
+| `Button`   | `VoidButton`        | Ações principais     |
+| `Input`    | `VeinInput`         | Entrada de dados     |
+| `Select`   | `RitualSelect`      | Seleção acessível    |
+| `Modal`    | `CryptModal`        | Diálogos e alertas   |
+| `Toast`    | `OmenToast`         | Notificações         |
+| `Menu`     | `AltarMenu`         | Dropdowns            |
+| `Tabs`     | `SoulTabs`          | Navegação em abas    |
+| `Card`     | `NocturnaCard`      | Container estrutural |
+| `Skeleton` | `SpectreSkeleton`   | Estados de loading   |
+
+_Consulte a [documentação completa](https://gothd.github.io/nocturna-ui/) para a lista total de props e variantes._
+
+---
+
+## 📜 Uso via CDN (Vanilla JS)
+
+A biblioteca injeta uma ponte global `window.NocturnaUI` para uso sem bundlers.
 
 ```html
 <script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
 <script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
-
 <script src="https://unpkg.com/framer-motion@11/dist/framer-motion.js"></script>
 
-<script src="https://unpkg.com/nocturna-ui@0.0.3/dist/index.umd.js"></script>
-```
+<script src="https://unpkg.com/nocturna-ui@0.0.5/dist/index.umd.js"></script>
+<link
+  rel="stylesheet"
+  href="https://unpkg.com/nocturna-ui@0.0.5/dist/style.css"
+/>
 
-## 🩸 Instalação e Uso
+<div id="root"></div>
 
-```bash
-npm install nocturna-ui
-```
+<script>
+  const { ToastProvider, Button } = window.NocturnaUI;
 
-```tsx
-import "nocturna-ui/dist/style.css";
-import { VoidButton, CryptModal } from "nocturna-ui";
-
-export const Ritual = () => (
-  <VoidButton variant="blood" size="lg">
-    Iniciar Invocação
-  </VoidButton>
-);
+  // Renderização manual necessária em Vanilla JS
+  const root = ReactDOM.createRoot(document.getElementById("root"));
+  root.render(React.createElement(ToastProvider));
+</script>
 ```
 
+_Veja o [exemplo de uso completo pela CDN, com o ToastProvider](./examples/cdn/index.html)._
+
 ---
 
-Desenvolvido com 🖤 por **gothd**. ☕️
+## 🧪 Desenvolvimento
+
+```bash
+npm test               # Roda testes unitários
+npm run test:coverage  # Relatório de cobertura
+```
+
+Desenvolvido com 🖤 por **gothd**.

package/dist/components/Accordion.d.ts

@@ -1,12 +1,33 @@
 import { default as React } from 'react';
-interface GrimoireAccordionItem {
+export interface GrimoireAccordionItem {
     id: string;
     title: string;
     content: React.ReactNode;
 }
 interface GrimoireAccordionProps extends React.HTMLAttributes<HTMLDivElement> {
-    items: GrimoireAccordionItem[];
+    /**
+     * Lista de seções do acordeão.
+     * Define o ID, título e conteúdo de cada painel.
+     */
+    items: Array<{
+        /** Identificador único para controle de estado */
+        id: string;
+        /** Texto do cabeçalho (sempre uppercase/serif) */
+        title: string;
+        /** Conteúdo a ser revelado (ReactNode) */
+        content: React.ReactNode;
+    }>;
+    /**
+     * Define a estética visual.
+     * - `void`: Monocromático (Borda Branca).
+     * - `blood`: Tons de vermelho sangue (Borda Vermelha).
+     * @default "void"
+     */
     variant?: "void" | "blood";
 }
+/**
+ * Componente de Acordeão com animações de altura (Framer Motion) e estética brutalista.
+ * Possui bordas sobrepostas para criar um efeito de lista contínua.
+ */
 export declare const GrimoireAccordion: ({ items, variant, className, ...props }: GrimoireAccordionProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/Badge.d.ts

@@ -1,9 +1,34 @@
 import { default as React } from 'react';
 interface SigilBadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /**
+     * O conteúdo do emblema (geralmente texto curto ou ícone).
+     */
     children: React.ReactNode;
+    /**
+     * Define o tema de cores.
+     * - `void`: Padrão monocromático (Preto/Branco).
+     * - `blood`: Tema agressivo (Vermelho/Preto) para erros ou destaques críticos.
+     * @default "void"
+     */
     variant?: "void" | "blood";
+    /**
+     * Dimensões e escala de fonte do badge.
+     * - `sm`: Para contextos densos ou listas.
+     * - `md`: Tamanho padrão para labels independentes.
+     * @default "md"
+     */
     size?: "sm" | "md";
+    /**
+     * Estilo de preenchimento.
+     * - `outline`: Borda colorida com fundo transparente/preto.
+     * - `solid`: Fundo preenchido com a cor da variante.
+     * @default "outline"
+     */
     styleType?: "outline" | "solid";
 }
-export declare const SigilBadge: ({ children, variant, size, styleType, className, ...props }: SigilBadgeProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Componente de Badge (Emblema) para status, tags ou categorias.
+ * Utiliza tipografia serifada e uppercase para reforçar a estética gótica/brutalista.
+ */
+export declare const SigilBadge: React.ForwardRefExoticComponent<SigilBadgeProps & React.RefAttributes<HTMLSpanElement>>;
 export {};

package/dist/components/Button.d.ts

@@ -1,7 +1,21 @@
 import { default as React } from 'react';
 interface VoidButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    /**
+     * Define o estilo visual do botão.
+     * - `void`: Estilo padrão preto e branco.
+     * - `blood`: Estilo vermelho escuro para ações perigosas ou destaque.
+     * @default "void"
+     */
     variant?: "void" | "blood";
+    /**
+     * Controla o tamanho e o padding do botão.
+     * @default "md"
+     */
     size?: "sm" | "md" | "lg";
 }
-export declare const VoidButton: ({ variant, size, className, ...props }: VoidButtonProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * O botão primário da Nocturna UI.
+ * Utiliza sombras rígidas e transições brutas.
+ */
+export declare const VoidButton: React.ForwardRefExoticComponent<VoidButtonProps & React.RefAttributes<HTMLButtonElement>>;
 export {};

package/dist/components/Card.d.ts

@@ -1,8 +1,38 @@
 import { default as React } from 'react';
 interface NocturnaCardProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Define o tema visual do card.
+     * - `void`: Borda branca e sombra branca no hover.
+     * - `blood`: Borda vermelha escura e sombra avermelhada no hover.
+     * @default "void"
+     */
     variant?: "void" | "blood";
-    title: string;
+    /**
+     * Título principal do card. Renderizado em uppercase e fonte serifada.
+     * Se omitido, o cabeçalho não será renderizado.
+     */
+    title?: string;
+    /**
+     * Texto de apoio renderizado logo abaixo do título em fonte sans-serif.
+     */
     description?: string;
+    /**
+     * Controla a tag HTML usada para o título (acessibilidade).
+     * Permite ajustar a hierarquia semântica sem mudar o estilo visual.
+     * @default "h3"
+     */
+    headingLevel?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+    /**
+     * Polimorfismo: Define qual elemento HTML raiz será renderizado.
+     * Útil para semântica (ex: transformar em `section`, `article` ou `li`).
+     * @default "div"
+     */
+    as?: React.ElementType;
 }
-export declare const NocturnaCard: ({ title, description, variant, className, children, ...props }: NocturnaCardProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Container fundamental da Nocturna UI.
+ * Possui comportamento de Flex Column para garantir que o conteúdo ocupe a altura disponível,
+ * além de sombras rígidas (hard shadows) interativas no hover.
+ */
+export declare const NocturnaCard: React.ForwardRefExoticComponent<NocturnaCardProps & React.RefAttributes<HTMLDivElement>>;
 export {};

package/dist/components/Checkbox.d.ts

@@ -1,7 +1,22 @@
 import { default as React } from 'react';
 interface HexCheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "type"> {
+    /**
+     * Texto opcional exibido ao lado do checkbox.
+     * Renderizado com tipografia sans-serif e uppercase.
+     */
     label?: string;
+    /**
+     * Define o tema visual do componente.
+     * - `void`: Padrão monocromático (Borda Branca / Check Preto).
+     * - `blood`: Tema vermelho escuro (Borda Vermelha / Check Branco).
+     * @default "void"
+     */
     variant?: "void" | "blood";
 }
-export declare const HexCheckbox: ({ label, variant, checked, className, ...props }: HexCheckboxProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Checkbox customizado com estética brutalista.
+ * Mantém acessibilidade total escondendo o input nativo (`sr-only`)
+ * mas preservando a navegabilidade via teclado e leitores de tela.
+ */
+export declare const HexCheckbox: React.ForwardRefExoticComponent<HexCheckboxProps & React.RefAttributes<HTMLInputElement>>;
 export {};

package/dist/components/Input.d.ts

@@ -1,10 +1,37 @@
 import { default as React } from 'react';
 interface VeinInputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size"> {
+    /**
+     * Define o tema visual do input.
+     * - `void`: Padrão monocromático (Borda Branca).
+     * - `blood`: Tema vermelho escuro (Borda Vermelha e Texto Vermelho).
+     * @default "void"
+     */
     variant?: "void" | "blood";
+    /**
+     * Dimensões do input (altura e padding).
+     * - `sm`: Compacto para formulários densos.
+     * - `md`: Tamanho padrão para legibilidade.
+     * @default "md"
+     */
     size?: "sm" | "md";
+    /**
+     * Texto do rótulo exibido acima do campo.
+     * Automaticamente vinculado ao input via `htmlFor` e `id`.
+     */
     label?: string;
+    /**
+     * Mensagem de erro.
+     * Se fornecido:
+     * 1. Altera a cor da borda para vermelho.
+     * 2. Exibe a mensagem abaixo do input.
+     * 3. Adiciona `aria-invalid="true"` e vincula a mensagem via `aria-describedby` para leitores de tela.
+     */
     error?: string;
-    inputSize?: React.InputHTMLAttributes<HTMLInputElement>["size"];
 }
-export declare const VeinInput: ({ variant, size, label, error, className, inputSize, ...props }: VeinInputProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Campo de entrada de texto com estética brutalista.
+ * Prioriza acessibilidade automática (vínculo label-input e tratamento de erros ARIA).
+ * O foco gera uma sombra rígida (hard shadow) característica da Nocturna UI.
+ */
+export declare const VeinInput: React.ForwardRefExoticComponent<VeinInputProps & React.RefAttributes<HTMLInputElement>>;
 export {};

package/dist/components/Menu.d.ts

@@ -0,0 +1,50 @@
+import { default as React } from 'react';
+export interface AltarMenuItem {
+    /** Identificador único do item. */
+    id: string;
+    /** Texto do item. */
+    label: string;
+    /** Ícone opcional à esquerda. */
+    icon?: React.ReactNode;
+    /** Ação ao clicar. */
+    onClick: () => void;
+    /** Indica ação destrutiva (vermelho). */
+    danger?: boolean;
+    /** Desabilita o item. */
+    disabled?: boolean;
+}
+interface AltarMenuProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Lista de itens do menu. */
+    items: Array<{
+        /** Identificador único do item. */
+        id: string;
+        /** Texto do item. */
+        label: string;
+        /** Ícone opcional à esquerda. */
+        icon?: React.ReactNode;
+        /** Ação ao clicar. */
+        onClick: () => void;
+        /** Indica ação destrutiva (vermelho). */
+        danger?: boolean;
+        /** Desabilita o item. */
+        disabled?: boolean;
+    }>;
+    /** Tema visual: 'void' (Padrão) ou 'blood' (Crítico). */
+    variant?: "void" | "blood";
+    /** Elemento gatilho opcional. Se omitido, usa ícone padrão. */
+    trigger?: React.ReactNode;
+    /** Alinhamento do dropdown. */
+    align?: "left" | "right";
+}
+/**
+ * Menu Dropdown acessível.
+ *
+ * **Comportamento de Teclado:**
+ * - `Enter` / `Espaço`: Abre o menu (se focado no gatilho) ou ativa item.
+ * - `Setas (Cima/Baixo)`: Navega entre os itens e previne scroll da página.
+ * - `Home` / `End`: Vai para o primeiro ou último item.
+ * - `Esc`: Fecha o menu e retorna foco ao gatilho.
+ * - `Tab`: Fecha o menu e segue fluxo natural da página.
+ */
+export declare const AltarMenu: React.ForwardRefExoticComponent<AltarMenuProps & React.RefAttributes<HTMLButtonElement>>;
+export {};

package/dist/components/Modal.d.ts

@@ -1,11 +1,45 @@
 import { default as React } from 'react';
 interface CryptModalProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Controla a visibilidade do modal.
+     * O componente é renderizado via React Portal no `document.body`.
+     */
     isOpen: boolean;
+    /**
+     * Função chamada quando o modal solicita fechamento.
+     * Disparada por: tecla ESC, clique no overlay ou clique no botão 'X'.
+     */
     onClose: () => void;
-    title: string;
+    /**
+     * Título principal do modal.
+     * Se fornecido, renderiza um `h2` padrão e configura `aria-labelledby`.
+     * Se omitido, você deve fornecer seu próprio cabeçalho dentro de `children` para acessibilidade visual.
+     */
+    title?: string;
+    /**
+     * Descrição opcional abaixo do título.
+     * Usada automaticamente para o atributo `aria-describedby`.
+     */
     description?: string;
+    /**
+     * Conteúdo interno do modal.
+     */
     children?: React.ReactNode;
+    /**
+     * Define o tema visual.
+     * - `void`: Monocromático (Borda Branca).
+     * - `blood`: Tema de alerta/erro (Borda Vermelha).
+     * @default "void"
+     */
     variant?: "void" | "blood";
 }
-export declare const CryptModal: ({ isOpen, onClose, title, description, children, variant, className, ...props }: CryptModalProps) => React.ReactPortal | null;
+/**
+ * Modal acessível com estética brutalista (Crypt).
+ *
+ * **Features Automáticas:**
+ * - **Focus Trap:** Mantém o foco do teclado preso dentro do modal.
+ * - **Scroll Lock:** Impede a rolagem da página de fundo.
+ * - **Close on ESC:** Fecha ao pressionar Escape.
+ */
+export declare const CryptModal: React.ForwardRefExoticComponent<CryptModalProps & React.RefAttributes<HTMLDivElement>>;
 export {};

package/dist/components/Progress.d.ts

@@ -0,0 +1,57 @@
+import { default as React } from 'react';
+interface VesselProgressProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Valor atual do progresso.
+     * Utilizado apenas quando `mode="value"`.
+     * @default 0
+     */
+    value?: number;
+    /**
+     * Valor máximo da escala.
+     * @default 100
+     */
+    max?: number;
+    /**
+     * Define o tema visual da barra.
+     * - `void`: Padrão monocromático (Branco).
+     * - `blood`: Tema de perigo/erro (Vermelho Escuro).
+     * @default "void"
+     */
+    variant?: "void" | "blood";
+    /**
+     * Rótulo exibido acima da barra.
+     * Renderizado em uppercase e fonte serifada.
+     */
+    label?: string;
+    /**
+     * Se verdadeiro, exibe a porcentagem numérica no lado direito do rótulo.
+     * Funciona apenas no modo `value`.
+     * @default false
+     */
+    showValue?: boolean;
+    /**
+     * Define o comportamento da barra.
+     * - `value`: Progresso manual controlado pela prop `value`.
+     * - `timer`: Barra decrescente automática baseada na `duration`.
+     * - `indeterminate`: Animação de "loading" infinito para estados de espera.
+     * @default "value"
+     */
+    mode?: "value" | "timer" | "indeterminate";
+    /**
+     * Duração da animação em milissegundos.
+     * Utilizado apenas quando `mode="timer"`.
+     * @default 5000
+     */
+    duration?: number;
+    /**
+     * Pausa a animação do timer se verdadeiro.
+     * @default false
+     */
+    paused?: boolean;
+}
+/**
+ * Barra de progresso multifuncional com estética brutalista.
+ * Suporta exibição de valores percentuais, timers decrescentes e estados de carregamento indeterminado.
+ */
+export declare const VesselProgress: React.ForwardRefExoticComponent<VesselProgressProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/dist/components/Scroll.d.ts

@@ -0,0 +1,31 @@
+import { default as React } from 'react';
+interface AbyssScrollProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Conteúdo que será rolado.
+     * Deve exceder a altura definida em `maxHeight` para ativar a rolagem.
+     */
+    children: React.ReactNode;
+    /**
+     * Define o tema visual da barra de rolagem.
+     * - `void`: Trilho escuro com polegar (thumb) branco.
+     * - `blood`: Trilho e polegar em tons de vermelho sangue.
+     * @default "void"
+     */
+    variant?: "void" | "blood";
+    /**
+     * Altura máxima do container antes de ativar a rolagem.
+     * Aceita valores CSS válidos (ex: "400px", "50vh", 300).
+     * @default "400px"
+     */
+    maxHeight?: string | number;
+}
+/**
+ * Container de rolagem com scrollbar customizada cross-browser (Webkit & Firefox).
+ *
+ * **Features:**
+ * - Acessível via teclado (`tabindex="0"` permite foco e uso das setas).
+ * - Estilização profunda de scrollbar para manter a imersão gótica.
+ * - Suporte a conteúdo dinâmico.
+ */
+export declare const AbyssScroll: React.ForwardRefExoticComponent<AbyssScrollProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/dist/components/Select.d.ts

@@ -1,16 +1,56 @@
 import { default as React } from 'react';
-interface RitualSelectOption {
+export interface RitualSelectOption {
     value: string;
     label: string;
 }
-interface RitualSelectProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onChange"> {
-    options: RitualSelectOption[];
+interface RitualSelectProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onChange" | "value"> {
+    /**
+     * Lista de opções disponíveis para seleção.
+     */
+    options: Array<{
+        /** Valor único da opção (enviado no onChange). */
+        value: string;
+        /** Texto exibido para o usuário. */
+        label: string;
+    }>;
+    /**
+     * Valor atual selecionado (Componente Controlado).
+     * Deve corresponder ao `value` de uma das opções.
+     */
     value?: string;
+    /**
+     * Callback disparado quando uma opção é selecionada.
+     * Retorna apenas o `value` da opção (string).
+     */
     onChange?: (value: string) => void;
+    /**
+     * Texto exibido quando nenhum valor está selecionado.
+     * @default "Select..."
+     */
     placeholder?: string;
+    /**
+     * Rótulo opcional exibido acima do select.
+     */
     label?: string;
+    /**
+     * Define o tema visual.
+     * - `void`: Padrão monocromático.
+     * - `blood`: Tema avermelhado (Erro/Alerta).
+     * @default "void"
+     */
     variant?: "void" | "blood";
+    /**
+     * Altura do componente.
+     * - `sm`: Compacto (32px).
+     * - `md`: Padrão (48px).
+     * - `lg`: Expandido (64px).
+     * @default "md"
+     */
     size?: "sm" | "md" | "lg";
 }
-export declare const RitualSelect: ({ options, value, onChange, placeholder, label, variant, size, className, }: RitualSelectProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Select customizado (Combobox) com suporte a navegação por teclado e estética brutalista.
+ * Substitui o `<select>` nativo para permitir estilização profunda do dropdown.
+ */
+export declare const RitualSelect: React.ForwardRefExoticComponent<RitualSelectProps & React.RefAttributes<HTMLButtonElement>>;
 export {};

package/dist/components/Separator.d.ts

@@ -1,7 +1,28 @@
 import { default as React } from 'react';
 interface AbyssSeparatorProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Define o tema visual das linhas e do texto.
+     * - `void`: Linhas brancas (Padrão).
+     * - `blood`: Linhas vermelho-sangue (Para áreas de perigo ou destaque).
+     * @default "void"
+     */
     variant?: "void" | "blood";
+    /**
+     * Texto opcional exibido no centro do separador.
+     * As linhas se ajustam automaticamente ao redor do texto.
+     * Renderizado em uppercase e com espaçamento de letras estendido.
+     */
     label?: string;
+    /**
+     * Polimorfismo: Permite alterar o elemento HTML raiz.
+     * Útil para semântica (ex: renderizar como `li` em listas ou `hr` estilizado).
+     * @default "div"
+     */
+    as?: React.ElementType;
 }
-export declare const AbyssSeparator: ({ variant, label, className, ...props }: AbyssSeparatorProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Divisor visual com estética brutalista.
+ * Cria uma linha horizontal (ou duas, se houver rótulo) para separar seções de conteúdo.
+ */
+export declare const AbyssSeparator: React.ForwardRefExoticComponent<AbyssSeparatorProps & React.RefAttributes<HTMLDivElement>>;
 export {};