rharuow-ds 1.8.2 → 1.10.0

package/README.md

@@ -44,7 +44,7 @@ Um Design System moderno em React com integração completa ao React Hook Form,
 ## 🌟 Características
 
 - ⚛️ **React 18+** com TypeScript
-- 🧩 **15 componentes** prontos para uso (Input, Textarea, Select, AsyncSelect, MultiSelect, MultiAsyncSelect, RadioGroup, Button, Card, Table, Tooltip, Accordion, AsideSheet, ImageInput)
+- 🧩 **17 componentes** prontos para uso (Input, Textarea, Select, AsyncSelect, MultiSelect, MultiAsyncSelect, RadioGroup, Button, Card, Table, Tooltip, Accordion, AsideSheet, Modal, Toaster, ImageInput)
 - 💡 **Filtro digitável** em componentes Select - Digite para encontrar opções rapidamente
 - 🔗 **Integração nativa** com React Hook Form
 - 🎨 **Customização via CSS Variables** - Mude o tema facilmente
@@ -112,6 +112,8 @@ npm install react-hook-form
      Tooltip,
      Accordion,
      AsideSheet,
+     Modal,
+     Toaster,
      ImageInput,
    } from "rharuow-ds";
 
@@ -199,6 +201,8 @@ npm install react-hook-form
      Tooltip,
      Accordion,
      AsideSheet,
+     Modal,
+     Toaster,
      ImageInput,
    } from "rharuow-ds";
 
@@ -582,7 +586,373 @@ Veja a story do componente no Storybook para demonstrações e variações (left
 
 [Storybook — AsideSheet](https://rharuow.github.io/rharuow-ds-docs/?path=/story/asidesheet--default)
 
-### 📷 **ImageInput**
+### 🎭 **Modal**
+
+Componente de diálogo modal para exibir conteúdo sobreposto à página principal.
+
+- ✅ Overlay com transparência configurável
+- ✅ Múltiplos tamanhos: sm, md, lg, xl, full
+- ✅ Controle de fechamento via overlay, ESC ou botão X
+- ✅ Prevenção de scroll do body quando aberto
+- ✅ Animações suaves de entrada/saída
+- ✅ Sub-componentes para estruturação: Header, Body, Footer
+- ✅ Renderização via Portal (React Portal)
+- ✅ Acessível: role="dialog", aria-modal
+
+Props principais:
+
+- `open: boolean` — controla visibilidade do modal
+- `onClose: () => void` — callback chamado ao fechar
+- `size?: 'sm' | 'md' | 'lg' | 'xl' | 'full'` — tamanho do modal (padrão: 'md')
+- `closeOnOverlayClick?: boolean` — fecha ao clicar fora (padrão: true)
+- `closeOnEscape?: boolean` — fecha ao pressionar ESC (padrão: true)
+- `showCloseButton?: boolean` — exibe botão X de fechar (padrão: true)
+- `className?: string` — classes adicionais para o container do modal
+
+Exemplo de uso básico:
+
+```tsx
+import React from 'react';
+import { Modal, Button } from 'rharuow-ds';
+
+function Example() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <div>
+      <Button onClick={() => setOpen(true)}>Abrir Modal</Button>
+
+      <Modal open={open} onClose={() => setOpen(false)}>
+        <h2>Título do Modal</h2>
+        <p>Conteúdo do modal aqui.</p>
+      </Modal>
+    </div>
+  );
+}
+```
+
+Exemplo com estrutura completa:
+
+```tsx
+import React from 'react';
+import { Modal, Button } from 'rharuow-ds';
+
+function Example() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <div>
+      <Button onClick={() => setOpen(true)}>Confirmar Ação</Button>
+
+      <Modal 
+        open={open} 
+        onClose={() => setOpen(false)}
+        size="md"
+      >
+        <Modal.Header>
+          <h2 className="text-2xl font-bold">Confirmar Exclusão</h2>
+          <p className="text-sm text-gray-500">Esta ação não pode ser desfeita</p>
+        </Modal.Header>
+
+        <Modal.Body>
+          <p className="text-gray-700">
+            Você tem certeza que deseja excluir este item? 
+            Todos os dados associados serão removidos permanentemente.
+          </p>
+        </Modal.Body>
+
+        <Modal.Footer>
+          <Button variant="outline" onClick={() => setOpen(false)}>
+            Cancelar
+          </Button>
+          <Button onClick={() => {
+            // Executar ação
+            setOpen(false);
+          }}>
+            Confirmar
+          </Button>
+        </Modal.Footer>
+      </Modal>
+    </div>
+  );
+}
+```
+
+Exemplo com formulário integrado:
+
+```tsx
+import React from 'react';
+import { Modal, Button, Input } from 'rharuow-ds';
+import { FormProvider, useForm } from 'react-hook-form';
+
+function FormModal() {
+  const [open, setOpen] = React.useState(false);
+  const methods = useForm();
+
+  const onSubmit = (data: any) => {
+    console.log('Form data:', data);
+    setOpen(false);
+    methods.reset();
+  };
+
+  return (
+    <div>
+      <Button onClick={() => setOpen(true)}>Novo Cadastro</Button>
+
+      <Modal 
+        open={open} 
+        onClose={() => setOpen(false)}
+        size="lg"
+        closeOnOverlayClick={false}
+      >
+        <FormProvider {...methods}>
+          <form onSubmit={methods.handleSubmit(onSubmit)}>
+            <Modal.Header>
+              <h2 className="text-2xl font-bold">Cadastrar Usuário</h2>
+            </Modal.Header>
+
+            <Modal.Body>
+              <div className="space-y-4">
+                <Input label="Nome completo" name="name" required />
+                <Input label="E-mail" name="email" type="email" required />
+                <Input label="Telefone" name="phone" />
+              </div>
+            </Modal.Body>
+
+            <Modal.Footer>
+              <Button 
+                type="button" 
+                variant="outline" 
+                onClick={() => setOpen(false)}
+              >
+                Cancelar
+              </Button>
+              <Button type="submit">Salvar</Button>
+            </Modal.Footer>
+          </form>
+        </FormProvider>
+      </Modal>
+    </div>
+  );
+}
+```
+
+Veja a story do componente no Storybook para mais exemplos e variações:
+
+[Storybook — Modal](https://rharuow.github.io/rharuow-ds-docs/?path=/story/components-modal--basic)
+
+### � **Toaster**
+
+Sistema completo de notificações toast para feedback ao usuário com múltiplas variantes e posicionamento flexível.
+
+- ✅ 5 variantes de toast: success, error, warning, info, default
+- ✅ 6 posições configuráveis na tela
+- ✅ Auto-dismiss com duração customizável
+- ✅ Toast permanente (duration: 0)
+- ✅ Ícones automáticos por variante
+- ✅ Animações suaves de entrada e saída
+- ✅ Limite de toasts simultâneos (padrão: 5)
+- ✅ Callbacks ao fechar
+- ✅ Hook `useToast` para uso simplificado
+- ✅ Gerenciamento via Context API
+
+**Configuração inicial:**
+
+O Toaster precisa ser configurado uma única vez no nível superior da aplicação:
+
+```tsx
+import React from 'react';
+import { ToasterProvider } from 'rharuow-ds';
+
+function App() {
+  return (
+    <ToasterProvider position="top-right" maxToasts={5}>
+      {/* Sua aplicação aqui */}
+      <YourApp />
+    </ToasterProvider>
+  );
+}
+```
+
+Props do `ToasterProvider`:
+
+- `position?: ToastPosition` - Posição dos toasts na tela (padrão: 'top-right')
+  - Opções: 'top-left', 'top-center', 'top-right', 'bottom-left', 'bottom-center', 'bottom-right'
+- `maxToasts?: number` - Número máximo de toasts simultâneos (padrão: 5)
+
+**Uso básico com hook `useToast`:**
+
+```tsx
+import React from 'react';
+import { useToast, Button } from 'rharuow-ds';
+
+function MyComponent() {
+  const toast = useToast();
+
+  return (
+    <div>
+      <Button onClick={() => toast.success('Operação realizada com sucesso!')}>
+        Success
+      </Button>
+
+      <Button onClick={() => toast.error('Erro ao processar requisição')}>
+        Error
+      </Button>
+
+      <Button onClick={() => toast.warning('Atenção: verifique os dados')}>
+        Warning
+      </Button>
+
+      <Button onClick={() => toast.info('Você tem 3 novas mensagens')}>
+        Info
+      </Button>
+    </div>
+  );
+}
+```
+
+**Toasts com duração customizada:**
+
+```tsx
+import React from 'react';
+import { useToast, Button } from 'rharuow-ds';
+
+function CustomDuration() {
+  const toast = useToast();
+
+  return (
+    <div>
+      {/* Toast rápido - 2 segundos */}
+      <Button onClick={() => toast.success('Toast rápido', 2000)}>
+        2 Segundos
+      </Button>
+
+      {/* Toast longo - 10 segundos */}
+      <Button onClick={() => toast.info('Toast longo', 10000)}>
+        10 Segundos
+      </Button>
+
+      {/* Toast permanente - não fecha automaticamente */}
+      <Button 
+        onClick={() => toast.toast('Toast permanente', { duration: 0 })}
+      >
+        Permanente
+      </Button>
+    </div>
+  );
+}
+```
+
+**Toast com callback ao fechar:**
+
+```tsx
+import React from 'react';
+import { useToaster, Button } from 'rharuow-ds';
+
+function WithCallback() {
+  const { addToast } = useToaster();
+
+  const handleAction = () => {
+    addToast({
+      message: 'Processando dados...',
+      variant: 'info',
+      duration: 3000,
+      onClose: () => {
+        console.log('Toast fechado!');
+        // Executar ação após fechamento
+        performNextAction();
+      },
+    });
+  };
+
+  return <Button onClick={handleAction}>Iniciar Processo</Button>;
+}
+```
+
+**Exemplo completo em um formulário:**
+
+```tsx
+import React from 'react';
+import { useForm, FormProvider } from 'react-hook-form';
+import { Input, Button, useToast } from 'rharuow-ds';
+
+function FormWithToast() {
+  const methods = useForm();
+  const toast = useToast();
+
+  const onSubmit = async (data: any) => {
+    try {
+      // Simular chamada à API
+      await saveData(data);
+      
+      toast.success('Dados salvos com sucesso!');
+      methods.reset();
+    } catch (error) {
+      toast.error('Erro ao salvar dados. Tente novamente.');
+      console.error(error);
+    }
+  };
+
+  return (
+    <FormProvider {...methods}>
+      <form onSubmit={methods.handleSubmit(onSubmit)}>
+        <Input label="Nome" name="name" required />
+        <Input label="E-mail" name="email" type="email" required />
+        
+        <Button type="submit">Salvar</Button>
+      </form>
+    </FormProvider>
+  );
+}
+```
+
+**API do hook `useToast`:**
+
+```typescript
+const toast = useToast();
+
+// Métodos disponíveis:
+toast.success(message: string, duration?: number)
+toast.error(message: string, duration?: number)
+toast.warning(message: string, duration?: number)
+toast.info(message: string, duration?: number)
+toast.toast(message: string, options?: ToastOptions)
+```
+
+**API avançada com `useToaster`:**
+
+```typescript
+const { addToast, removeToast, clearAll, toasts } = useToaster();
+
+// Adicionar toast com controle total
+const id = addToast({
+  message: 'Mensagem personalizada',
+  variant: 'success',
+  duration: 5000,
+  onClose: () => console.log('Fechado'),
+});
+
+// Remover toast específico
+removeToast(id);
+
+// Limpar todos os toasts
+clearAll();
+```
+
+**Dicas de uso:**
+
+- Use `success` para operações bem-sucedidas (save, delete, update)
+- Use `error` para falhas e erros
+- Use `warning` para avisos que requerem atenção
+- Use `info` para informações gerais
+- Configure `duration: 0` para toasts que precisam de ação manual do usuário
+- Posicione toasts conforme o contexto: top para notificações gerais, bottom para ações específicas
+
+Veja a story do componente no Storybook para demonstrações interativas:
+
+[Storybook — Toaster](https://rharuow.github.io/rharuow-ds-docs/?path=/story/components-toaster--top-right)
+
+### �📷 **ImageInput**
 
 Componente para seleção e upload de imagens com preview e ações de confirmação/remoção:
 
@@ -692,51 +1062,168 @@ Veja a story do componente no Storybook para demonstrações completas:
 
 ## 🎨 Customização de Tema
 
-O rharuow-ds utiliza **CSS Variables** para permitir customização fácil do tema. Você pode modificar as cores primárias do design system definindo as seguintes variáveis CSS:
+O rharuow-ds utiliza um **sistema de cores baseado em brand colors** (cores da marca) que permite criar uma experiência visual coesa em toda a sua aplicação. Todos os componentes (Card, Table, Select, Tooltip) derivam suas cores das variáveis primárias e secundárias que você define.
+
+### 🌈 Sistema de Cores
+
+#### Variáveis Principais
+
+```css
+:root {
+  /* Cores Primárias - Personalizáveis */
+  --primary: #2563eb;           /* Cor principal da marca */
+  --primary-hover: #1d4ed8;     /* Hover da cor principal */
+  --primary-light: #dbeafe;     /* Versão clara para fundos */
+  
+  /* Cores Secundárias - Personalizáveis */
+  --secondary: #64748b;         /* Cor secundária */
+  --secondary-hover: #475569;   /* Hover da cor secundária */
+  --secondary-light: #f1f5f9;   /* Versão clara para fundos */
+}
+```
+
+#### Como os Componentes Usam as Cores
+
+Os componentes **derivam automaticamente** suas cores das variáveis primárias:
+
+- **Card Header**: Mescla 5% da cor primária com fundo neutro
+- **Table Header**: Mescla 8% da cor primária com fundo neutro
+- **Table Hover**: Mescla 10% da cor primária com fundo neutro
+- **Select Selected**: Usa diretamente `--primary-light`
+- **Elementos Selecionados**: Consistentemente usam a cor primária clara
 
-### Variáveis Disponíveis
+### 💡 Como Personalizar
+
+#### Método 1: CSS Global (Recomendado)
+
+No seu arquivo CSS principal (`index.css` ou `App.css`):
 
 ```css
+/* Importar o DS primeiro */
+@import 'rharuow-ds/dist/styles.css';
+
+/* Depois sobrescrever as cores da marca */
 :root {
-  --primary: #2563eb; /* Cor primária principal */
-  --primary-hover: #dbeafe; /* Cor para hover/background */
-  --primary-text: #fff; /* Cor do texto em backgrounds primários */
-  --input-bg: #fff; /* Background dos inputs */
-  --input-text: #222; /* Cor do texto dos inputs */
+  --primary: #8b5cf6;           /* Roxo */
+  --primary-hover: #7c3aed;
+  --primary-light: #ede9fe;
+  
+  --secondary: #ec4899;         /* Rosa */
+  --secondary-hover: #db2777;
+  --secondary-light: #fce7f3;
+}
+
+/* Para dark mode, customize também */
+[data-theme="dark"], .dark {
+  --primary: #a78bfa;           /* Roxo mais claro para dark */
+  --primary-hover: #8b5cf6;
+  --primary-light: #4c1d95;
+  
+  --secondary: #f472b6;
+  --secondary-hover: #ec4899;
+  --secondary-light: #831843;
 }
 ```
 
-### Exemplo de Customização
+#### Método 2: JavaScript/React
+
+```typescript
+// App.tsx ou main.tsx
+useEffect(() => {
+  const root = document.documentElement;
+  
+  root.style.setProperty('--primary', '#f59e0b');
+  root.style.setProperty('--primary-hover', '#d97706');
+  root.style.setProperty('--primary-light', '#fef3c7');
+}, []);
+```
+
+### 🎯 Exemplos de Paletas
 
 ```css
-/* Tema vermelho */
+/* Paleta Corporativa (Azul) */
+:root {
+  --primary: #0ea5e9;
+  --primary-hover: #0284c7;
+  --primary-light: #e0f2fe;
+}
+
+/* Paleta Moderna (Roxo/Rosa) */
 :root {
-  --primary: #dc2626;
-  --primary-hover: #fecaca;
-  --primary-text: #fff;
+  --primary: #8b5cf6;
+  --primary-hover: #7c3aed;
+  --primary-light: #ede9fe;
+  --secondary: #ec4899;
 }
 
-/* Tema verde */
+/* Paleta Natureza (Verde) */
 :root {
-  --primary: #059669;
-  --primary-hover: #d1fae5;
-  --primary-text: #fff;
+  --primary: #10b981;
+  --primary-hover: #059669;
+  --primary-light: #d1fae5;
 }
 
-/* Tema roxo */
+/* Paleta Minimalista (Cinza) */
+:root {
+  --primary: #6b7280;
+  --primary-hover: #4b5563;
+  --primary-light: #f3f4f6;
+}
+```
+
+### 🔧 Customização Avançada
+
+Para controle total, você pode sobrescrever variáveis específicas:
+
+```css
 :root {
-  --primary: #7c3aed;
-  --primary-hover: #e9d5ff;
-  --primary-text: #fff;
+  /* Cores base da marca */
+  --primary: #8b5cf6;
+  
+  /* Customização específica de Card */
+  --card-header-bg: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+  --card-header-border: #8b5cf6;
+  
+  /* Customização específica de Table */
+  --table-header-bg: #f3e8ff;
+  --table-row-selected: #ede9fe;
 }
 ```
 
+### 📚 Variáveis Disponíveis por Componente
+
+#### Card
+- `--card-bg`, `--card-border`, `--card-text`
+- `--card-header-bg`, `--card-header-border`
+- `--card-footer-bg`, `--card-footer-border`
+
+#### Table
+- `--table-bg`, `--table-border`, `--table-text`
+- `--table-header-bg`, `--table-row-hover`, `--table-row-selected`
+
+#### Select/AsyncSelect/MultiSelect
+- `--select-dropdown-bg`, `--select-dropdown-border`
+- `--select-dropdown-hover`, `--select-dropdown-selected`
+
+#### Tooltip
+- `--tooltip-bg`, `--tooltip-text`
+
+### 🌓 Dark Mode
+
+O sistema ajusta automaticamente as cores no dark mode:
+
+```css
+/* Ative o dark mode adicionando o atributo */
+<html data-theme="dark">
+  <!-- ou -->
+<html class="dark">
+```
+
 ### No Storybook
 
-Na documentação do Storybook, você pode testar diferentes temas usando os controles na toolbar:
+Na [documentação do Storybook](https://rharuow.github.io/rharuow-ds-docs/), você pode testar diferentes temas na story **"Theme Customization"**.
 
-- 🎨 **Primary Color**: Muda a cor principal
-- 🌈 **Primary Hover**: Muda a cor de hover/background
+Para mais detalhes, consulte [THEME_CUSTOMIZATION.md](./THEME_CUSTOMIZATION.md).
 
 ---