@etus/ui 0.1.0

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

@@ -0,0 +1,723 @@
+# AlertDialog
+
+## Visão Geral
+
+O componente **AlertDialog** exibe um dialogo modal que interrompe o fluxo do usuario para solicitar uma confirmacao ou apresentar informacoes criticas. Diferente do Dialog padrao, o AlertDialog requer uma acao explicita do usuario para ser fechado, nao podendo ser dispensado clicando fora ou pressionando Escape.
+
+### Classificacao Atomica
+- **Categoria**: Molecules
+- **Subcategoria**: Feedback
+
+### Casos de Uso Comuns
+- Confirmacao de acoes destrutivas (excluir, remover)
+- Avisos de perda de dados nao salvos
+- Confirmacao de logout ou encerramento de sessao
+- Alertas de seguranca que requerem acao
+- Confirmacao de operacoes irreversiveis
+
+### Relacao com Outros Componentes
+- **Dialog**: Para modais gerais que podem ser fechados livremente
+- **ConfirmModal**: Wrapper simplificado para confirmacoes comuns
+- **Alert**: Para mensagens nao-modais inline
+- **Button**: Usado para acoes de confirmacao e cancelamento
+
+## Design Specs
+
+### Anatomia
+O AlertDialog e composto por varios subcomponentes:
+- **AlertDialog**: Componente raiz que gerencia estado
+- **AlertDialogTrigger**: Elemento que dispara a abertura
+- **AlertDialogPortal**: Renderiza conteudo em portal
+- **AlertDialogOverlay**: Backdrop escurecido
+- **AlertDialogContent**: Container do conteudo
+- **AlertDialogHeader**: Agrupa titulo e descricao
+- **AlertDialogTitle**: Titulo do dialogo
+- **AlertDialogDescription**: Texto descritivo
+- **AlertDialogFooter**: Agrupa botoes de acao
+- **AlertDialogAction**: Botao de acao primaria
+- **AlertDialogCancel**: Botao de cancelamento
+
+### Estados
+- **Closed**: Dialogo oculto
+- **Open**: Dialogo visivel com overlay
+- **Animating In**: `data-[state=open]:animate-in`
+- **Animating Out**: `data-[state=closed]:animate-out`
+
+### Tokens de Design
+
+#### Cores
+- Overlay: `bg-black/50` (50% opacidade)
+- Content Background: `bg-background`
+- Text: cores padrao do tema
+- Border: `border` (cor padrao)
+
+#### Espacamento
+- Content Padding: `p-6`
+- Gap entre elementos: `gap-4`
+- Header Gap: `gap-2`
+- Footer Gap: `gap-2`
+
+#### Tipografia
+- Title: `text-lg font-semibold`
+- Description: `text-sm text-muted-foreground`
+
+#### Bordas e Arredondamento
+- Border Radius: `rounded-lg`
+- Shadow: `shadow-lg`
+
+#### Motion e Transicoes
+- Duration: `duration-200`
+- Animacoes: `fade-in-0`, `fade-out-0`, `zoom-in-95`, `zoom-out-95`
+
+### Consideracoes de Responsividade
+- **Mobile (< 640px)**:
+  - Largura maxima: `max-w-[calc(100%-2rem)]`
+  - Texto centralizado no header
+  - Botoes empilhados verticalmente (coluna reversa)
+- **Desktop (>= 640px)**:
+  - Largura maxima: `sm:max-w-lg`
+  - Texto alinhado a esquerda
+  - Botoes lado a lado a direita
+
+## API
+
+### Props
+
+#### AlertDialog (Root)
+| Prop | Tipo | Padrao | Descricao |
+|------|------|---------|-----------|
+| `open` | `boolean` | - | Controle do estado aberto/fechado |
+| `onOpenChange` | `(open: boolean) => void` | - | Callback quando estado muda |
+| `defaultOpen` | `boolean` | `false` | Estado inicial |
+
+#### AlertDialogContent
+| Prop | Tipo | Padrao | Descricao |
+|------|------|---------|-----------|
+| `className` | `string` | `''` | Classes CSS adicionais |
+| `forceMount` | `boolean` | - | Forca montagem mesmo quando fechado |
+
+#### AlertDialogAction / AlertDialogCancel
+| Prop | Tipo | Padrao | Descricao |
+|------|------|---------|-----------|
+| `className` | `string` | `''` | Classes CSS adicionais |
+| `asChild` | `boolean` | `false` | Renderiza como elemento filho |
+
+### Eventos
+| Evento | Payload | Descricao |
+|--------|---------|-----------|
+| `onOpenChange` | `boolean` | Disparado quando estado de abertura muda |
+| `onEscapeKeyDown` | `KeyboardEvent` | Disparado ao pressionar Escape (prevenido por padrao) |
+
+### Interfaces TypeScript
+
+```typescript
+import * as AlertDialogPrimitive from "@radix-ui/react-alert-dialog"
+
+// AlertDialog Root
+type AlertDialogProps = React.ComponentProps<typeof AlertDialogPrimitive.Root>
+
+// AlertDialogTrigger
+type AlertDialogTriggerProps = React.ComponentProps<typeof AlertDialogPrimitive.Trigger>
+
+// AlertDialogContent
+interface AlertDialogContentProps
+  extends React.ComponentProps<typeof AlertDialogPrimitive.Content> {}
+
+// AlertDialogHeader/Footer (custom)
+interface AlertDialogHeaderProps extends React.ComponentProps<"div"> {}
+interface AlertDialogFooterProps extends React.ComponentProps<"div"> {}
+
+// AlertDialogTitle
+type AlertDialogTitleProps = React.ComponentProps<typeof AlertDialogPrimitive.Title>
+
+// AlertDialogDescription
+type AlertDialogDescriptionProps = React.ComponentProps<typeof AlertDialogPrimitive.Description>
+
+// AlertDialogAction
+type AlertDialogActionProps = React.ComponentProps<typeof AlertDialogPrimitive.Action>
+
+// AlertDialogCancel
+type AlertDialogCancelProps = React.ComponentProps<typeof AlertDialogPrimitive.Cancel>
+```
+
+### Comparacao com Referencias
+
+| Design System | Escape Fecha | Click Fora Fecha | Botoes Estilizados |
+|---------------|--------------|------------------|---------------------|
+| **ETUS** | Nao | Nao | Sim (buttonVariants) |
+| Radix UI | Configuravel | Configuravel | Nao (headless) |
+| Chakra UI | Configuravel | Configuravel | Sim |
+| MUI | Configuravel | Configuravel | Sim |
+| Headless UI | Configuravel | Configuravel | Nao |
+| Ariakit | Configuravel | Configuravel | Nao |
+
+## Acessibilidade (A11y)
+
+### Atributos ARIA
+- `role="alertdialog"`: Indica dialogo que requer atencao imediata
+- `aria-modal="true"`: Indica modalidade
+- `aria-labelledby`: Referencia o titulo
+- `aria-describedby`: Referencia a descricao
+
+### Navegacao por Teclado
+- `Tab`: Navega entre elementos focaveis dentro do dialogo
+- `Shift + Tab`: Navega em direcao reversa
+- `Enter`: Ativa botao focado
+- `Space`: Ativa botao focado
+- `Escape`: Nao fecha o dialogo (diferente do Dialog)
+
+### Focus Management
+- Focus e movido para o dialogo ao abrir
+- Focus e retornado ao trigger ao fechar
+- Focus trap impede navegacao fora do dialogo
+- Primeiro elemento focavel recebe foco inicial
+
+### Contraste e Legibilidade
+- Ratio de contraste minimo: WCAG AA (4.5:1)
+- Overlay escurecido melhora foco no conteudo
+- Texto com contraste adequado contra background
+
+### Tecnologias Assistivas
+- Screen readers anunciam como "alert dialog"
+- Titulo e descricao sao anunciados automaticamente
+- Botoes sao claramente identificados por suas labels
+
+### Conformidade WCAG
+- Nivel alvo: WCAG 2.1 AA
+- Criterios especificos:
+  - 2.1.2 No Keyboard Trap (focus dentro do dialogo)
+  - 2.4.3 Focus Order
+  - 4.1.2 Name, Role, Value
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from '@etus/ui'
+
+function BasicAlertDialog() {
+  return (
+    <AlertDialog>
+      <AlertDialogTrigger asChild>
+        <Button variant="destructive">Excluir conta</Button>
+      </AlertDialogTrigger>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>Voce tem certeza?</AlertDialogTitle>
+          <AlertDialogDescription>
+            Esta acao nao pode ser desfeita. Isso excluira permanentemente
+            sua conta e removera seus dados de nossos servidores.
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel>Cancelar</AlertDialogCancel>
+          <AlertDialogAction>Continuar</AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  )
+}
+```
+
+### Controlado Externamente
+
+```tsx
+import { useState } from 'react'
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from '@etus/ui'
+
+function ControlledAlertDialog() {
+  const [open, setOpen] = useState(false)
+
+  const handleDelete = async () => {
+    // Executar acao de exclusao
+    await deleteAccount()
+    setOpen(false)
+  }
+
+  return (
+    <>
+      <Button onClick={() => setOpen(true)}>Excluir</Button>
+
+      <AlertDialog open={open} onOpenChange={setOpen}>
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>Confirmar exclusao</AlertDialogTitle>
+            <AlertDialogDescription>
+              Deseja realmente excluir este item?
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel>Cancelar</AlertDialogCancel>
+            <AlertDialogAction onClick={handleDelete}>
+              Excluir
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    </>
+  )
+}
+```
+
+### Com Acao Async
+
+```tsx
+import { useState } from 'react'
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from '@etus/ui'
+
+function AsyncAlertDialog() {
+  const [isLoading, setIsLoading] = useState(false)
+
+  const handleConfirm = async () => {
+    setIsLoading(true)
+    try {
+      await performAsyncAction()
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  return (
+    <AlertDialog>
+      <AlertDialogTrigger asChild>
+        <Button>Processar</Button>
+      </AlertDialogTrigger>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>Processar dados</AlertDialogTitle>
+          <AlertDialogDescription>
+            Esta operacao pode levar alguns segundos.
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel disabled={isLoading}>
+            Cancelar
+          </AlertDialogCancel>
+          <AlertDialogAction onClick={handleConfirm} disabled={isLoading}>
+            {isLoading ? 'Processando...' : 'Confirmar'}
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  )
+}
+```
+
+### Estilo Destructive
+
+```tsx
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from '@etus/ui'
+
+function DestructiveAlertDialog() {
+  return (
+    <AlertDialog>
+      <AlertDialogTrigger asChild>
+        <Button variant="destructive">Excluir projeto</Button>
+      </AlertDialogTrigger>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>Excluir projeto</AlertDialogTitle>
+          <AlertDialogDescription>
+            Esta acao e irreversivel. Todos os arquivos, configuracoes
+            e historico serao permanentemente removidos.
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel>Cancelar</AlertDialogCancel>
+          <AlertDialogAction className="bg-destructive text-destructive-foreground hover:bg-destructive/90">
+            Excluir permanentemente
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  )
+}
+```
+
+### Com Icone
+
+```tsx
+import { TriangleAlert } from 'lucide-react'
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from '@etus/ui'
+
+function AlertDialogWithIcon() {
+  return (
+    <AlertDialog>
+      <AlertDialogTrigger asChild>
+        <Button variant="outline">Sair sem salvar</Button>
+      </AlertDialogTrigger>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <div className="flex items-center gap-3">
+            <div className="flex size-10 items-center justify-center rounded-full bg-amber-100 text-amber-600">
+              <TriangleAlert className="size-5" />
+            </div>
+            <AlertDialogTitle>Alteracoes nao salvas</AlertDialogTitle>
+          </div>
+          <AlertDialogDescription>
+            Voce tem alteracoes que nao foram salvas. Se sair agora,
+            essas alteracoes serao perdidas.
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel>Voltar e salvar</AlertDialogCancel>
+          <AlertDialogAction>Sair sem salvar</AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  )
+}
+```
+
+### Form dentro do Dialog
+
+```tsx
+import { useState } from 'react'
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from '@etus/ui'
+
+function AlertDialogWithConfirmInput() {
+  const [confirmText, setConfirmText] = useState('')
+  const projectName = 'meu-projeto'
+
+  return (
+    <AlertDialog>
+      <AlertDialogTrigger asChild>
+        <Button variant="destructive">Excluir projeto</Button>
+      </AlertDialogTrigger>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>Confirmar exclusao</AlertDialogTitle>
+          <AlertDialogDescription>
+            Digite <strong>{projectName}</strong> para confirmar a exclusao.
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+
+        <input
+          type="text"
+          value={confirmText}
+          onChange={(e) => setConfirmText(e.target.value)}
+          placeholder={projectName}
+          className="flex h-10 w-full rounded-md border px-3 py-2 text-sm"
+        />
+
+        <AlertDialogFooter>
+          <AlertDialogCancel onClick={() => setConfirmText('')}>
+            Cancelar
+          </AlertDialogCancel>
+          <AlertDialogAction
+            disabled={confirmText !== projectName}
+            className="bg-destructive text-destructive-foreground hover:bg-destructive/90"
+          >
+            Excluir
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  )
+}
+```
+
+### Customizacao de Largura
+
+```tsx
+import {
+  AlertDialog,
+  AlertDialogContent,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogCancel,
+  AlertDialogAction,
+  AlertDialogTrigger,
+} from '@etus/ui'
+
+function WideAlertDialog() {
+  return (
+    <AlertDialog>
+      <AlertDialogTrigger asChild>
+        <Button>Abrir dialogo largo</Button>
+      </AlertDialogTrigger>
+      <AlertDialogContent className="sm:max-w-2xl">
+        <AlertDialogHeader>
+          <AlertDialogTitle>Termos de uso</AlertDialogTitle>
+          <AlertDialogDescription className="max-h-[60vh] overflow-y-auto">
+            {/* Conteudo extenso aqui */}
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit...
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel>Recusar</AlertDialogCancel>
+          <AlertDialogAction>Aceitar termos</AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  )
+}
+```
+
+## Testes
+
+### Estrategias de Teste
+
+#### Testes Unitarios
+- Renderizacao do dialogo quando aberto
+- Nao renderiza conteudo quando fechado
+- Trigger abre o dialogo
+- Botao Cancel fecha o dialogo
+- Botao Action executa callback
+
+#### Testes de Integracao
+- Fluxo completo de abertura e fechamento
+- Comportamento com acoes async
+- Interacao com formularios internos
+
+#### Testes de Acessibilidade
+- Role alertdialog presente
+- Focus management correto
+- Escape nao fecha o dialogo
+- Labels acessiveis
+
+### 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 {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from './AlertDialog'
+
+describe('AlertDialog', () => {
+  it('opens when trigger is clicked', async () => {
+    const user = userEvent.setup()
+
+    render(
+      <AlertDialog>
+        <AlertDialogTrigger>Open</AlertDialogTrigger>
+        <AlertDialogContent>
+          <AlertDialogTitle>Title</AlertDialogTitle>
+        </AlertDialogContent>
+      </AlertDialog>
+    )
+
+    expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument()
+
+    await user.click(screen.getByText('Open'))
+
+    expect(screen.getByRole('alertdialog')).toBeInTheDocument()
+  })
+
+  it('closes when cancel is clicked', async () => {
+    const user = userEvent.setup()
+
+    render(
+      <AlertDialog defaultOpen>
+        <AlertDialogContent>
+          <AlertDialogTitle>Title</AlertDialogTitle>
+          <AlertDialogFooter>
+            <AlertDialogCancel>Cancel</AlertDialogCancel>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    )
+
+    expect(screen.getByRole('alertdialog')).toBeInTheDocument()
+
+    await user.click(screen.getByText('Cancel'))
+
+    expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument()
+  })
+
+  it('calls action callback when clicked', async () => {
+    const user = userEvent.setup()
+    const onAction = vi.fn()
+
+    render(
+      <AlertDialog defaultOpen>
+        <AlertDialogContent>
+          <AlertDialogTitle>Title</AlertDialogTitle>
+          <AlertDialogFooter>
+            <AlertDialogAction onClick={onAction}>Confirm</AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    )
+
+    await user.click(screen.getByText('Confirm'))
+
+    expect(onAction).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not close on escape key', async () => {
+    const user = userEvent.setup()
+
+    render(
+      <AlertDialog defaultOpen>
+        <AlertDialogContent>
+          <AlertDialogTitle>Title</AlertDialogTitle>
+        </AlertDialogContent>
+      </AlertDialog>
+    )
+
+    await user.keyboard('{Escape}')
+
+    // AlertDialog should remain open
+    expect(screen.getByRole('alertdialog')).toBeInTheDocument()
+  })
+
+  it('does not close on overlay click', async () => {
+    const user = userEvent.setup()
+
+    render(
+      <AlertDialog defaultOpen>
+        <AlertDialogContent>
+          <AlertDialogTitle>Title</AlertDialogTitle>
+        </AlertDialogContent>
+      </AlertDialog>
+    )
+
+    // Click on overlay
+    const overlay = screen.getByRole('alertdialog').parentElement?.querySelector('[data-slot="alert-dialog-overlay"]')
+    if (overlay) {
+      await user.click(overlay)
+    }
+
+    // AlertDialog should remain open
+    expect(screen.getByRole('alertdialog')).toBeInTheDocument()
+  })
+
+  it('has correct aria attributes', () => {
+    render(
+      <AlertDialog defaultOpen>
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>Dialog Title</AlertDialogTitle>
+            <AlertDialogDescription>Dialog Description</AlertDialogDescription>
+          </AlertDialogHeader>
+        </AlertDialogContent>
+      </AlertDialog>
+    )
+
+    const dialog = screen.getByRole('alertdialog')
+    expect(dialog).toHaveAttribute('aria-modal', 'true')
+    expect(dialog).toHaveAttribute('aria-labelledby')
+    expect(dialog).toHaveAttribute('aria-describedby')
+  })
+})
+```
+
+### Testes de Acessibilidade
+
+```typescript
+import { axe, toHaveNoViolations } from 'jest-axe'
+
+expect.extend(toHaveNoViolations)
+
+describe('AlertDialog Accessibility', () => {
+  it('has no accessibility violations', async () => {
+    const { container } = render(
+      <AlertDialog defaultOpen>
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>Accessible Title</AlertDialogTitle>
+            <AlertDialogDescription>Accessible description</AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel>Cancel</AlertDialogCancel>
+            <AlertDialogAction>Confirm</AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    )
+
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+- Baseado em Radix UI AlertDialog para comportamento acessivel
+- Usa buttonVariants do Button para consistencia visual
+- Animacoes CSS nativas via Tailwind animate utilities
+- Focus trap automatico via Radix primitives
+- Portal rendering para evitar z-index issues
+
+## Referências
+
+- [Radix UI AlertDialog](https://www.radix-ui.com/primitives/docs/components/alert-dialog)
+- [WAI-ARIA Alert Dialog Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/)
+- [Shadcn/ui AlertDialog](https://ui.shadcn.com/docs/components/alert-dialog)
+- [MDN role="alertdialog"](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role)