nocturna-ui 0.0.3 → 0.0.4

package/README.md

@@ -2,42 +2,120 @@
 
 > **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/gótica. Na **v0.0.4**, expandimos nosso arsenal com componentes de feedback, navegação e um sistema robusto de notificações (Toasts) desacoplado.
 
 [Showcase (DEMO)](https://gothd.github.io/nocturna-ui/) | [NPM](https://www.npmjs.com/package/nocturna-ui) | [UNPKG](https://unpkg.com/nocturna-ui/)
 
 ---
 
-## 🕸️ Componentes Disponíveis
+## 🕸️ Arsenal de Componentes
+
+| Primitivo                  | Descrição                                                     |
+| :------------------------- | :------------------------------------------------------------ |
+| **VoidButton**             | Botão brutalista com suporte a tamanhos sm/md/lg.             |
+| **CryptModal**             | Modal com portal, trava de foco e suporte a tecla ESC.        |
+| **RitualSelect**           | Select customizado com suporte total a navegação via teclado. |
+| **AltarMenu** `Novo`       | Menu dropdown acessível para ações e navegação.               |
+| **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 labels integrados e validação visual.      |
+| **HexCheckbox**            | Checkbox temático com animação de escala e ícone custom.      |
+| **OmenToast** `Novo`       | Sistema de notificações (Toasts) via Hook ou Global.          |
+| **RuneTooltip** `Novo`     | Tooltips informativos com posicionamento automático.          |
+| **VesselProgress** `Novo`  | Barras de progresso (Valor ou Timer/Indeterminate).           |
+| **AbyssScroll** `Novo`     | Container com scrollbar customizada cross-browser.            |
+| **SpectreSkeleton** `Novo` | Placeholders de carregamento (Avatar, Card).                  |
+| **SigilBadge**             | Emblemas para status e tags em versões Solid ou Outline.      |
+| **AbyssSeparator**         | Divisor de seção com suporte a labels e sigilos.              |
+| **NocturnaCard**           | Container clássico com sombras rígidas (hard shadows).        |
 
-| 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
+
+### 1. Instale o pacote
 
-## 🌑 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:
+### 2. Dependências (Peer Dependencies)
 
-- **React** (^18.0.0)
-- **React-DOM** (^18.0.0)
-- **Framer Motion** (^11.0.0)
+Para garantir animações fluidas e evitar conflitos de versão do React, certifique-se de ter instalado:
 
 ```bash
 npm install react react-dom framer-motion
 ```
 
-## 📜 Uso via CDN (UMD)
+_(Nota: Os ícones internos utilizam Lucide React e já estão inclusos no pacote. Você não precisa instalá-lo separadamente, a menos que queira usar os mesmos ícones em sua aplicação)._
+
+### 3. Setup do Provider
+
+Para que o sistema de **Toasts** (OmenToast) funcione, você deve envolver sua aplicação com o `OmenToastProvider`:
+
+```tsx
+// src/App.tsx ou src/layout.tsx
+import { OmenToastProvider } from "nocturna-ui";
+import "nocturna-ui/dist/style.css"; // Importação vital dos estilos
+
+export default function App({ children }) {
+  return <OmenToastProvider>{children}</OmenToastProvider>;
+}
+```
+
+---
+
+## 🩸 Como Usar
+
+### Componentes Básicos
+
+```tsx
+import { VoidButton, SigilBadge } from "nocturna-ui";
+
+export const Ritual = () => (
+  <div className="flex gap-4">
+    <SigilBadge variant="blood">Status: Ativo</SigilBadge>
+    <VoidButton variant="void" onClick={() => console.log("Invocado")}>
+      Iniciar Ritual
+    </VoidButton>
+  </div>
+);
+```
+
+### Hook de Toast (React)
+
+Dentro de qualquer componente filho do Provider:
+
+```tsx
+import { useToast, VoidButton } from "nocturna-ui";
+
+export const SummonToast = () => {
+  const { toast } = useToast();
+
+  return (
+    <VoidButton
+      onClick={() =>
+        toast({
+          title: "Oferenda Aceita",
+          description: "Os dados foram salvos no grimório.",
+          type: "success",
+          variant: "void",
+        })
+      }
+    >
+      Salvar
+    </VoidButton>
+  );
+};
+```
+
+---
+
+## 📜 Uso via CDN (Vanilla JS / HTML)
 
-Para utilizar a biblioteca diretamente no navegador, a ordem dos scripts é fundamental para que as globais sejam injetadas corretamente:
+A **Nocturna UI** injeta uma ponte global (`window.NocturnaUI`) quando carregada via script tag, permitindo o uso do sistema de Toasts mesmo fora do React.
+
+**Ordem de Importação:**
 
 ```html
 <script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
@@ -45,25 +123,47 @@ Para utilizar a biblioteca diretamente no navegador, a ordem dos scripts é fund
 
 <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.4/dist/index.umd.js"></script>
+<link
+  rel="stylesheet"
+  href="https://unpkg.com/nocturna-ui@0.0.4/dist/style.css"
+/>
 ```
 
-## 🩸 Instalação e Uso
+**Inicialização e Uso:**
 
-```bash
-npm install nocturna-ui
+```html
+<div id="root"></div>
+
+<script>
+  // 1. Inicializa o Provider (Necessário para a Bridge funcionar)
+  const root = ReactDOM.createRoot(document.getElementById("root"));
+  root.render(React.createElement(window.NocturnaUI.OmenToastProvider));
+
+  // 2. Dispara Toasts via JavaScript Puro
+  function invocarMensagem() {
+    if (window.NocturnaUI && window.NocturnaUI.toaster) {
+      window.NocturnaUI.toaster.toast({
+        title: "Vanilla JS",
+        description: "O sistema de notificações funciona sem build steps.",
+        variant: "blood",
+        type: "warning",
+      });
+    }
+  }
+</script>
+
+<button onclick="invocarMensagem()">Testar Toast</button>
 ```
 
-```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>
-);
-```
+## 🛠️ Tecnologias
+
+- **TypeScript** - Tipagem estrita para rituais seguros.
+- **Tailwind CSS** - Estilização atômica encapsulada (sem conflitos de classe).
+- **Framer Motion** - Animações de entrada e saída (Accordions, Modais, Toasts).
+- **Lucide React** - Iconografia leve e consistente.
 
 ---
 

package/dist/components/Badge.d.ts

@@ -5,5 +5,5 @@ interface SigilBadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
     size?: "sm" | "md";
     styleType?: "outline" | "solid";
 }
-export declare const SigilBadge: ({ children, variant, size, styleType, className, ...props }: SigilBadgeProps) => import("react/jsx-runtime").JSX.Element;
+export declare const SigilBadge: React.ForwardRefExoticComponent<SigilBadgeProps & React.RefAttributes<HTMLSpanElement>>;
 export {};

package/dist/components/Button.d.ts

@@ -3,5 +3,5 @@ interface VoidButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>
     variant?: "void" | "blood";
     size?: "sm" | "md" | "lg";
 }
-export declare const VoidButton: ({ variant, size, className, ...props }: VoidButtonProps) => import("react/jsx-runtime").JSX.Element;
+export declare const VoidButton: React.ForwardRefExoticComponent<VoidButtonProps & React.RefAttributes<HTMLButtonElement>>;
 export {};

package/dist/components/Card.d.ts

@@ -3,6 +3,8 @@ interface NocturnaCardProps extends React.HTMLAttributes<HTMLDivElement> {
     variant?: "void" | "blood";
     title: string;
     description?: string;
+    headingLevel?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+    as?: React.ElementType;
 }
-export declare const NocturnaCard: ({ title, description, variant, className, children, ...props }: NocturnaCardProps) => import("react/jsx-runtime").JSX.Element;
+export declare const NocturnaCard: React.ForwardRefExoticComponent<NocturnaCardProps & React.RefAttributes<HTMLDivElement>>;
 export {};

package/dist/components/Checkbox.d.ts

@@ -3,5 +3,5 @@ interface HexCheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputEleme
     label?: string;
     variant?: "void" | "blood";
 }
-export declare const HexCheckbox: ({ label, variant, checked, className, ...props }: HexCheckboxProps) => import("react/jsx-runtime").JSX.Element;
+export declare const HexCheckbox: React.ForwardRefExoticComponent<HexCheckboxProps & React.RefAttributes<HTMLInputElement>>;
 export {};

package/dist/components/Input.d.ts

@@ -4,7 +4,6 @@ interface VeinInputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement
     size?: "sm" | "md";
     label?: string;
     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;
+export declare const VeinInput: React.ForwardRefExoticComponent<VeinInputProps & React.RefAttributes<HTMLInputElement>>;
 export {};

package/dist/components/Menu.d.ts

@@ -0,0 +1,17 @@
+import { default as React } from 'react';
+interface AltarMenuItem {
+    id: string;
+    label: string;
+    icon?: React.ReactNode;
+    onClick: () => void;
+    danger?: boolean;
+    disabled?: boolean;
+}
+interface AltarMenuProps extends React.HTMLAttributes<HTMLDivElement> {
+    items: AltarMenuItem[];
+    variant?: "void" | "blood";
+    trigger?: React.ReactNode;
+    align?: "left" | "right";
+}
+export declare const AltarMenu: React.ForwardRefExoticComponent<AltarMenuProps & React.RefAttributes<HTMLButtonElement>>;
+export {};

package/dist/components/Modal.d.ts

@@ -7,5 +7,5 @@ interface CryptModalProps extends React.HTMLAttributes<HTMLDivElement> {
     children?: React.ReactNode;
     variant?: "void" | "blood";
 }
-export declare const CryptModal: ({ isOpen, onClose, title, description, children, variant, className, ...props }: CryptModalProps) => React.ReactPortal | null;
+export declare const CryptModal: React.ForwardRefExoticComponent<CryptModalProps & React.RefAttributes<HTMLDivElement>>;
 export {};

package/dist/components/Progress.d.ts

@@ -0,0 +1,13 @@
+import { default as React } from 'react';
+interface VesselProgressProps extends React.HTMLAttributes<HTMLDivElement> {
+    value?: number;
+    max?: number;
+    variant?: "void" | "blood";
+    label?: string;
+    showValue?: boolean;
+    mode?: "value" | "timer" | "indeterminate";
+    duration?: number;
+    paused?: boolean;
+}
+export declare const VesselProgress: React.ForwardRefExoticComponent<VesselProgressProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/dist/components/Scroll.d.ts

@@ -0,0 +1,8 @@
+import { default as React } from 'react';
+interface AbyssScrollProps extends React.HTMLAttributes<HTMLDivElement> {
+    children: React.ReactNode;
+    variant?: "void" | "blood";
+    maxHeight?: string | number;
+}
+export declare const AbyssScroll: React.ForwardRefExoticComponent<AbyssScrollProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/dist/components/Select.d.ts

@@ -3,7 +3,7 @@ interface RitualSelectOption {
     value: string;
     label: string;
 }
-interface RitualSelectProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onChange"> {
+interface RitualSelectProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onChange" | "value"> {
     options: RitualSelectOption[];
     value?: string;
     onChange?: (value: string) => void;
@@ -12,5 +12,5 @@ interface RitualSelectProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonEl
     variant?: "void" | "blood";
     size?: "sm" | "md" | "lg";
 }
-export declare const RitualSelect: ({ options, value, onChange, placeholder, label, variant, size, className, }: RitualSelectProps) => import("react/jsx-runtime").JSX.Element;
+export declare const RitualSelect: React.ForwardRefExoticComponent<RitualSelectProps & React.RefAttributes<HTMLButtonElement>>;
 export {};

package/dist/components/Separator.d.ts

@@ -2,6 +2,7 @@ import { default as React } from 'react';
 interface AbyssSeparatorProps extends React.HTMLAttributes<HTMLDivElement> {
     variant?: "void" | "blood";
     label?: string;
+    as?: React.ElementType;
 }
-export declare const AbyssSeparator: ({ variant, label, className, ...props }: AbyssSeparatorProps) => import("react/jsx-runtime").JSX.Element;
+export declare const AbyssSeparator: React.ForwardRefExoticComponent<AbyssSeparatorProps & React.RefAttributes<HTMLDivElement>>;
 export {};

package/dist/components/Skeleton.d.ts

@@ -0,0 +1,17 @@
+import { default as React } from 'react';
+interface SpectreSkeletonProps extends React.HTMLAttributes<HTMLDivElement> {
+    variant?: "void" | "blood";
+    width?: string | number;
+    height?: string | number;
+}
+export declare const SpectreSkeleton: React.ForwardRefExoticComponent<SpectreSkeletonProps & React.RefAttributes<HTMLDivElement>>;
+interface SpectreSkeletonAvatarProps extends Omit<SpectreSkeletonProps, "width" | "height"> {
+    size?: "sm" | "md" | "lg";
+}
+export declare const SpectreSkeletonAvatar: React.ForwardRefExoticComponent<SpectreSkeletonAvatarProps & React.RefAttributes<HTMLDivElement>>;
+interface SpectreSkeletonCardProps extends React.HTMLAttributes<HTMLDivElement> {
+    variant?: "void" | "blood";
+    lines?: number;
+}
+export declare const SpectreSkeletonCard: React.ForwardRefExoticComponent<SpectreSkeletonCardProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/dist/components/Tabs.d.ts

@@ -4,9 +4,9 @@ interface Tab {
     label: string;
     content: React.ReactNode;
 }
-interface SoulTabsProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+interface SoulTabsProps extends React.HTMLAttributes<HTMLDivElement> {
     tabs: Tab[];
     variant?: "void" | "blood";
 }
-export declare const SoulTabs: ({ tabs, variant, className, ...props }: SoulTabsProps) => import("react/jsx-runtime").JSX.Element;
+export declare const SoulTabs: React.ForwardRefExoticComponent<SoulTabsProps & React.RefAttributes<HTMLDivElement>>;
 export {};

package/dist/components/Toast.d.ts

@@ -0,0 +1,13 @@
+import { default as React } from 'react';
+export type ToastVariant = "void" | "blood";
+export type ToastType = "info" | "success" | "warning" | "error";
+export interface OmenToastProps extends React.HTMLAttributes<HTMLDivElement> {
+    id: string;
+    title: string;
+    description?: string;
+    variant?: ToastVariant;
+    type?: ToastType;
+    duration?: number;
+    onClose: (id: string) => void;
+}
+export declare const OmenToast: React.ForwardRefExoticComponent<OmenToastProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/Tooltip.d.ts

@@ -0,0 +1,9 @@
+import { default as React } from 'react';
+interface RuneTooltipProps extends React.HTMLAttributes<HTMLDivElement> {
+    content: string;
+    children: React.ReactNode;
+    variant?: "void" | "blood";
+    position?: "top" | "bottom" | "left" | "right";
+}
+export declare const RuneTooltip: React.ForwardRefExoticComponent<RuneTooltipProps & React.RefAttributes<HTMLDivElement>>;
+export {};