@etus/ui 0.1.0

package/src/components/feedback/Modal/Modal.types.ts

@@ -0,0 +1,91 @@
+import type { ReactNode } from "react"
+
+/**
+ * Modal size variants
+ * Maps to Tailwind max-width classes
+ */
+export type ModalSize = "2xl" | "full" | "lg" | "md" | "sm" | "xl"
+
+/**
+ * Modal component props
+ *
+ * A simplified wrapper over Dialog that provides a declarative API
+ * for common modal use cases.
+ */
+export interface ModalProps {
+  /**
+   * Main content of the modal
+   */
+  children?: ReactNode
+
+  /**
+   * Additional CSS classes for the modal content
+   */
+  className?: string
+
+  /**
+   * Whether to close the modal when pressing Escape
+   * @default true
+   */
+  closeOnEscape?: boolean
+
+  /**
+   * Whether to close the modal when clicking the overlay
+   * @default true
+   */
+  closeOnOverlayClick?: boolean
+
+  /**
+   * Default open state for uncontrolled usage
+   * @default false
+   */
+  defaultOpen?: boolean
+
+  /**
+   * Optional description displayed below the title
+   */
+  description?: string
+
+  /**
+   * Footer content (typically action buttons)
+   */
+  footer?: ReactNode
+
+  /**
+   * Callback when open state changes
+   */
+  onOpenChange?: (open: boolean) => void
+
+  /**
+   * Controlled open state
+   */
+  open?: boolean
+
+  /**
+   * Additional CSS classes for the overlay
+   */
+  overlayClassName?: string
+
+  /**
+   * Whether to show the close button (X) in the top right corner
+   * @default true
+   */
+  showCloseButton?: boolean
+
+  /**
+   * Modal width size
+   * @default "md"
+   */
+  size?: ModalSize
+
+  /**
+   * Modal title displayed in the header
+   */
+  title?: string
+
+  /**
+   * Optional trigger element that opens the modal
+   * When provided, the modal will manage its own open state
+   */
+  trigger?: ReactNode
+}

package/src/components/feedback/Modal/README.md

@@ -0,0 +1,517 @@
+# Modal
+
+## Visão Geral
+
+O componente **Modal** e um wrapper semantico e simplificado sobre Dialog, fornecendo uma API mais direta para casos de uso comuns de janelas modais. Enquanto Dialog oferece controle granular via subcomponentes, Modal abstrai a complexidade em uma interface de props declarativa.
+
+### Classificacao Atomica
+- **Categoria**: Molecules / Organisms
+- **Subcategoria**: Feedback / Layout
+
+### Casos de Uso Comuns
+- Formularios de criacao/edicao rapida
+- Visualizacao de detalhes
+- Confirmacoes simples
+- Exibicao de conteudo em overlay
+- Modais de configuracao
+
+### Relacao com Outros Componentes
+- **Dialog**: Componente base com mais controle
+- **AlertDialog**: Para confirmacoes obrigatorias
+- **ConfirmModal**: Especializado para confirmacoes
+- **Sheet**: Para paineis laterais
+- **Drawer**: Para navegacao lateral
+
+## Design Specs
+
+### Tamanhos
+- **sm**: `max-w-sm` (~384px)
+- **md**: `max-w-md` (~448px) - Padrao
+- **lg**: `max-w-lg` (~512px)
+- **xl**: `max-w-xl` (~576px)
+- **2xl**: `max-w-2xl` (~672px)
+- **full**: `max-w-full` (quase toda largura)
+
+### Estados
+- **Closed**: Modal oculto
+- **Open**: Modal visivel
+- **Loading**: Conteudo em carregamento
+
+### Tokens de Design
+Herda do Dialog:
+- Background: `bg-background`
+- Overlay: `bg-black/50`
+- Border Radius: `rounded-lg`
+- Shadow: `shadow-lg`
+- Padding: `p-6`
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|---------|-----------|
+| `open` | `boolean` | - | Estado aberto/fechado |
+| `onOpenChange` | `(open: boolean) => void` | - | Callback de mudanca |
+| `title` | `string` | - | Titulo do modal |
+| `description` | `string` | - | Descricao opcional |
+| `children` | `ReactNode` | - | Conteudo principal |
+| `footer` | `ReactNode` | - | Conteudo do rodape |
+| `size` | `'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| 'full'` | `'md'` | Largura |
+| `showCloseButton` | `boolean` | `true` | Exibe botao X |
+| `closeOnEscape` | `boolean` | `true` | Fecha com Escape |
+| `closeOnOverlayClick` | `boolean` | `true` | Fecha ao clicar fora |
+| `trigger` | `ReactNode` | - | Elemento que abre o modal |
+| `className` | `string` | `''` | Classes CSS do content |
+| `overlayClassName` | `string` | `''` | Classes CSS do overlay |
+
+### Interfaces TypeScript
+
+```typescript
+interface ModalProps {
+  // Estado
+  open?: boolean
+  onOpenChange?: (open: boolean) => void
+  defaultOpen?: boolean
+
+  // Conteudo
+  title?: string
+  description?: string
+  children?: React.ReactNode
+  footer?: React.ReactNode
+
+  // Aparencia
+  size?: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full'
+  showCloseButton?: boolean
+  className?: string
+  overlayClassName?: string
+
+  // Comportamento
+  closeOnEscape?: boolean
+  closeOnOverlayClick?: boolean
+
+  // Trigger
+  trigger?: React.ReactNode
+}
+```
+
+### Comparacao Dialog vs Modal
+
+| Aspecto | Dialog | Modal |
+|---------|--------|-------|
+| API | Subcomponentes | Props declarativas |
+| Flexibilidade | Alta | Media |
+| Curva de aprendizado | Media | Baixa |
+| Customizacao | Total | Limitada |
+| Boilerplate | Mais | Menos |
+
+## Acessibilidade (A11y)
+
+Herda toda acessibilidade do Dialog:
+- `role="dialog"`
+- `aria-modal="true"`
+- `aria-labelledby` (titulo)
+- `aria-describedby` (descricao)
+- Focus trap automatico
+- Retorno de foco ao fechar
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import { useState } from 'react'
+import { Modal, Button } from '@etus/ui'
+
+function BasicModal() {
+  const [open, setOpen] = useState(false)
+
+  return (
+    <>
+      <Button onClick={() => setOpen(true)}>Abrir Modal</Button>
+
+      <Modal
+        open={open}
+        onOpenChange={setOpen}
+        title="Titulo do Modal"
+        description="Descricao opcional do modal."
+      >
+        <p>Conteudo principal do modal aqui.</p>
+      </Modal>
+    </>
+  )
+}
+```
+
+### Com Trigger Integrado
+
+```tsx
+import { Modal, Button } from '@etus/ui'
+
+function ModalWithTrigger() {
+  return (
+    <Modal
+      trigger={<Button>Abrir</Button>}
+      title="Modal com Trigger"
+    >
+      <p>O trigger abre o modal automaticamente.</p>
+    </Modal>
+  )
+}
+```
+
+### Com Footer
+
+```tsx
+import { Modal, Button } from '@etus/ui'
+
+function ModalWithFooter() {
+  const [open, setOpen] = useState(false)
+
+  return (
+    <Modal
+      open={open}
+      onOpenChange={setOpen}
+      trigger={<Button>Editar</Button>}
+      title="Editar Item"
+      footer={
+        <div className="flex justify-end gap-2">
+          <Button variant="outline" onClick={() => setOpen(false)}>
+            Cancelar
+          </Button>
+          <Button onClick={() => {
+            save()
+            setOpen(false)
+          }}>
+            Salvar
+          </Button>
+        </div>
+      }
+    >
+      <Input placeholder="Nome do item" />
+    </Modal>
+  )
+}
+```
+
+### Diferentes Tamanhos
+
+```tsx
+import { Modal, Button } from '@etus/ui'
+
+function ModalSizes() {
+  return (
+    <div className="flex gap-2">
+      <Modal trigger={<Button size="sm">SM</Button>} size="sm" title="Small">
+        Modal pequeno
+      </Modal>
+
+      <Modal trigger={<Button size="sm">MD</Button>} size="md" title="Medium">
+        Modal medio (padrao)
+      </Modal>
+
+      <Modal trigger={<Button size="sm">LG</Button>} size="lg" title="Large">
+        Modal grande
+      </Modal>
+
+      <Modal trigger={<Button size="sm">XL</Button>} size="xl" title="Extra Large">
+        Modal extra grande
+      </Modal>
+
+      <Modal trigger={<Button size="sm">2XL</Button>} size="2xl" title="2X Large">
+        Modal 2x grande
+      </Modal>
+    </div>
+  )
+}
+```
+
+### Sem Fechar ao Clicar Fora
+
+```tsx
+import { Modal, Button } from '@etus/ui'
+
+function PersistentModal() {
+  return (
+    <Modal
+      trigger={<Button>Formulario Importante</Button>}
+      title="Formulario"
+      closeOnOverlayClick={false}
+      closeOnEscape={false}
+    >
+      <p>Este modal so fecha pelo botao X ou acoes internas.</p>
+      <form>
+        <Input placeholder="Dados importantes..." />
+      </form>
+    </Modal>
+  )
+}
+```
+
+### Com Formulario Completo
+
+```tsx
+import { useState } from 'react'
+import { Modal, Button, Input, Label, Textarea } from '@etus/ui'
+
+function FormModal() {
+  const [open, setOpen] = useState(false)
+  const [loading, setLoading] = useState(false)
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault()
+    setLoading(true)
+    await saveData()
+    setLoading(false)
+    setOpen(false)
+  }
+
+  return (
+    <Modal
+      open={open}
+      onOpenChange={setOpen}
+      trigger={<Button>Criar Novo</Button>}
+      title="Criar Item"
+      description="Preencha os dados do novo item."
+      footer={
+        <div className="flex justify-end gap-2">
+          <Button
+            variant="outline"
+            onClick={() => setOpen(false)}
+            disabled={loading}
+          >
+            Cancelar
+          </Button>
+          <Button
+            type="submit"
+            form="create-form"
+            disabled={loading}
+          >
+            {loading ? 'Criando...' : 'Criar'}
+          </Button>
+        </div>
+      }
+    >
+      <form id="create-form" onSubmit={handleSubmit} className="space-y-4">
+        <div className="space-y-2">
+          <Label htmlFor="name">Nome</Label>
+          <Input id="name" required />
+        </div>
+        <div className="space-y-2">
+          <Label htmlFor="description">Descricao</Label>
+          <Textarea id="description" />
+        </div>
+      </form>
+    </Modal>
+  )
+}
+```
+
+### Modal de Confirmacao Simples
+
+```tsx
+import { Modal, Button } from '@etus/ui'
+import { TriangleAlert } from 'lucide-react'
+
+function SimpleConfirmModal() {
+  const [open, setOpen] = useState(false)
+
+  return (
+    <Modal
+      open={open}
+      onOpenChange={setOpen}
+      trigger={<Button variant="destructive">Excluir</Button>}
+      title="Confirmar Exclusao"
+      size="sm"
+      footer={
+        <div className="flex justify-end gap-2">
+          <Button variant="outline" onClick={() => setOpen(false)}>
+            Cancelar
+          </Button>
+          <Button
+            variant="destructive"
+            onClick={() => {
+              deleteItem()
+              setOpen(false)
+            }}
+          >
+            Excluir
+          </Button>
+        </div>
+      }
+    >
+      <div className="flex gap-4">
+        <TriangleAlert className="size-10 text-destructive shrink-0" />
+        <p>
+          Tem certeza que deseja excluir este item?
+          Esta acao nao pode ser desfeita.
+        </p>
+      </div>
+    </Modal>
+  )
+}
+```
+
+### Modal com Scroll
+
+```tsx
+import { Modal, Button } from '@etus/ui'
+
+function ScrollableModal() {
+  return (
+    <Modal
+      trigger={<Button>Termos de Uso</Button>}
+      title="Termos de Uso"
+      size="lg"
+      footer={
+        <div className="flex justify-end gap-2">
+          <Button variant="outline">Recusar</Button>
+          <Button>Aceitar</Button>
+        </div>
+      }
+    >
+      <div className="max-h-[60vh] overflow-y-auto">
+        {Array.from({ length: 20 }).map((_, i) => (
+          <p key={i} className="mb-4">
+            Clausula {i + 1}: Lorem ipsum dolor sit amet...
+          </p>
+        ))}
+      </div>
+    </Modal>
+  )
+}
+```
+
+### Customizacao Visual
+
+```tsx
+import { Modal, Button } from '@etus/ui'
+
+function CustomStyledModal() {
+  return (
+    <Modal
+      trigger={<Button>Modal Customizado</Button>}
+      title="Estilo Customizado"
+      className="bg-gradient-to-br from-purple-50 to-pink-50 dark:from-purple-950 dark:to-pink-950"
+      overlayClassName="bg-purple-900/30"
+    >
+      <p>Modal com cores customizadas.</p>
+    </Modal>
+  )
+}
+```
+
+## Testes
+
+### Exemplos de Codigo
+
+```typescript
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { Modal } from './Modal'
+
+describe('Modal', () => {
+  it('opens when trigger is clicked', async () => {
+    const user = userEvent.setup()
+
+    render(
+      <Modal trigger={<button>Open</button>} title="Test Modal">
+        Content
+      </Modal>
+    )
+
+    await user.click(screen.getByText('Open'))
+    expect(screen.getByRole('dialog')).toBeInTheDocument()
+    expect(screen.getByText('Test Modal')).toBeInTheDocument()
+  })
+
+  it('renders title and description', () => {
+    render(
+      <Modal
+        open={true}
+        onOpenChange={() => {}}
+        title="Title"
+        description="Description"
+      >
+        Content
+      </Modal>
+    )
+
+    expect(screen.getByText('Title')).toBeInTheDocument()
+    expect(screen.getByText('Description')).toBeInTheDocument()
+  })
+
+  it('renders footer', () => {
+    render(
+      <Modal
+        open={true}
+        onOpenChange={() => {}}
+        title="Title"
+        footer={<button>Footer Button</button>}
+      >
+        Content
+      </Modal>
+    )
+
+    expect(screen.getByText('Footer Button')).toBeInTheDocument()
+  })
+
+  it('calls onOpenChange when closed', async () => {
+    const user = userEvent.setup()
+    const onOpenChange = vi.fn()
+
+    render(
+      <Modal open={true} onOpenChange={onOpenChange} title="Title">
+        Content
+      </Modal>
+    )
+
+    await user.keyboard('{Escape}')
+    expect(onOpenChange).toHaveBeenCalledWith(false)
+  })
+
+  it('applies size class correctly', () => {
+    render(
+      <Modal open={true} onOpenChange={() => {}} title="Title" size="lg">
+        Content
+      </Modal>
+    )
+
+    const dialog = screen.getByRole('dialog')
+    expect(dialog).toHaveClass('max-w-lg')
+  })
+
+  it('hides close button when showCloseButton is false', () => {
+    render(
+      <Modal
+        open={true}
+        onOpenChange={() => {}}
+        title="Title"
+        showCloseButton={false}
+      >
+        Content
+      </Modal>
+    )
+
+    expect(screen.queryByRole('button', { name: /close/i })).not.toBeInTheDocument()
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+- Wrapper simplificado sobre Dialog
+- API declarativa para produtividade
+- Herda toda acessibilidade do Dialog
+- Sizes pre-definidos para consistencia
+- Trigger opcional para menos boilerplate
+
+## Referências
+
+- [Dialog](../Dialog/README.md) - Componente base
+- [Radix UI Dialog](https://www.radix-ui.com/primitives/docs/components/dialog)
+- [Chakra UI Modal](https://chakra-ui.com/docs/components/modal)
+- [Mantine Modal](https://mantine.dev/core/modal/)

package/src/components/feedback/Modal/index.ts

@@ -0,0 +1,2 @@
+export type { ModalProps, ModalSize } from "./Modal.types"
+export { Modal } from "./Modal"