@etus/ui 0.1.0

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

@@ -0,0 +1,573 @@
+# ErrorPage
+
+## Visão Geral
+
+O componente **ErrorPage** exibe paginas de erro amigaveis e informativas quando ocorrem problemas na aplicacao. Fornece feedback visual claro sobre o tipo de erro, possíveis causas e acoes que o usuario pode tomar para resolver a situacao.
+
+### Classificacao Atomica
+- **Categoria**: Organisms / Templates
+- **Subcategoria**: Feedback
+
+### Casos de Uso Comuns
+- Pagina 404 (Nao encontrado)
+- Pagina 500 (Erro interno do servidor)
+- Pagina 403 (Acesso negado)
+- Pagina 401 (Nao autorizado)
+- Erro de conexao/offline
+- Erro generico de aplicacao
+- Pagina de manutencao
+
+### Relacao com Outros Componentes
+- **ErrorBoundary**: Captura erros React e renderiza ErrorPage
+- **EmptyState**: Para estados vazios (sem erro)
+- **Alert**: Para erros inline menores
+- **Button**: Para acoes de recuperacao
+
+## Design Specs
+
+### Variantes
+- **404**: Recurso nao encontrado
+- **500**: Erro interno do servidor
+- **403**: Acesso proibido
+- **401**: Nao autenticado
+- **offline**: Sem conexao com internet
+- **maintenance**: Sistema em manutencao
+- **generic**: Erro generico
+
+### Tamanhos
+- **sm**: Layout compacto para areas menores
+- **md**: Tamanho padrao
+- **lg**: Layout expandido com mais detalhes
+
+### Estados
+- **Default**: Exibe erro estatico
+- **Loading**: Tentando reconectar/recuperar
+- **Recovered**: Erro resolvido (transicao)
+
+### Tokens de Design
+
+#### Cores
+- Background: `bg-background`
+- Text Primary: `text-foreground`
+- Text Secondary: `text-muted-foreground`
+- Error Accent: `text-destructive`
+- Success Accent: `text-green-500`
+
+#### Espacamento
+- Container Padding: `p-8` / `p-12` / `p-16`
+- Gap entre elementos: `gap-4` / `gap-6`
+- Margin do icone: `mb-6`
+
+#### Tipografia
+- Codigo de erro: `text-6xl` / `text-8xl font-bold`
+- Titulo: `text-2xl font-semibold`
+- Descricao: `text-base text-muted-foreground`
+
+#### Icones
+- Tamanho padrao: `size-16` / `size-24`
+- Cor: Contextual por tipo de erro
+
+### Consideracoes de Responsividade
+- **Mobile**: Layout vertical centralizado
+- **Tablet**: Pode usar layout lado a lado
+- **Desktop**: Mais espacamento, ilustracoes maiores
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|---------|-----------|
+| `type` | `'404' \| '500' \| '403' \| '401' \| 'offline' \| 'maintenance' \| 'generic'` | `'generic'` | Tipo de erro |
+| `title` | `string` | Auto por tipo | Titulo customizado |
+| `description` | `string` | Auto por tipo | Descricao customizada |
+| `code` | `string \| number` | Auto por tipo | Codigo do erro |
+| `icon` | `ReactNode` | Auto por tipo | Icone customizado |
+| `illustration` | `ReactNode` | - | Ilustracao/imagem customizada |
+| `actions` | `ReactNode` | - | Botoes de acao |
+| `showHomeLink` | `boolean` | `true` | Exibe link para home |
+| `showBackLink` | `boolean` | `true` | Exibe link para voltar |
+| `homeHref` | `string` | `'/'` | URL do link home |
+| `onRetry` | `() => void` | - | Callback para tentar novamente |
+| `retryLabel` | `string` | `'Tentar novamente'` | Label do botao retry |
+| `className` | `string` | `''` | Classes CSS adicionais |
+| `fullScreen` | `boolean` | `false` | Ocupa tela inteira |
+
+### Interfaces TypeScript
+
+```typescript
+type ErrorType = '404' | '500' | '403' | '401' | 'offline' | 'maintenance' | 'generic'
+
+interface ErrorPageProps {
+  // Tipo e conteudo
+  type?: ErrorType
+  title?: string
+  description?: string
+  code?: string | number
+
+  // Visual
+  icon?: React.ReactNode
+  illustration?: React.ReactNode
+  className?: string
+  fullScreen?: boolean
+
+  // Navegacao
+  actions?: React.ReactNode
+  showHomeLink?: boolean
+  showBackLink?: boolean
+  homeHref?: string
+
+  // Interacao
+  onRetry?: () => void
+  retryLabel?: string
+  loading?: boolean
+}
+
+// Titulos e descricoes padrao por tipo
+const errorDefaults: Record<ErrorType, { title: string; description: string; code: string }> = {
+  '404': {
+    title: 'Pagina nao encontrada',
+    description: 'A pagina que voce esta procurando nao existe ou foi movida.',
+    code: '404'
+  },
+  '500': {
+    title: 'Erro interno',
+    description: 'Ocorreu um erro inesperado. Nossa equipe foi notificada.',
+    code: '500'
+  },
+  '403': {
+    title: 'Acesso negado',
+    description: 'Voce nao tem permissao para acessar este recurso.',
+    code: '403'
+  },
+  '401': {
+    title: 'Nao autenticado',
+    description: 'Faca login para acessar este conteudo.',
+    code: '401'
+  },
+  'offline': {
+    title: 'Sem conexao',
+    description: 'Verifique sua conexao com a internet e tente novamente.',
+    code: ''
+  },
+  'maintenance': {
+    title: 'Em manutencao',
+    description: 'Estamos realizando melhorias. Voltamos em breve!',
+    code: ''
+  },
+  'generic': {
+    title: 'Algo deu errado',
+    description: 'Ocorreu um erro. Por favor, tente novamente.',
+    code: ''
+  }
+}
+```
+
+### Comparacao com Referencias
+
+| Design System | Variantes | Ilustracoes | Retry Built-in |
+|---------------|-----------|-------------|----------------|
+| **ETUS** | 7 tipos | Customizavel | Sim |
+| Ant Design | Result component | Built-in | Manual |
+| MUI | Manual | Manual | Manual |
+| Chakra UI | Manual | Manual | Manual |
+| Mantine | Manual | Manual | Manual |
+
+## Acessibilidade (A11y)
+
+### Atributos ARIA
+- `role="alert"` ou `role="main"`: Dependendo do contexto
+- `aria-live="polite"`: Para anuncios de mudanca de estado
+- `aria-label`: Em links e botoes
+
+### Navegacao por Teclado
+- Links e botoes focaveis na ordem correta
+- `Tab`: Navega entre acoes
+- `Enter`: Ativa acao focada
+
+### Tecnologias Assistivas
+- Titulo do erro anunciado como heading
+- Descricao lida como texto complementar
+- Acoes claramente rotuladas
+
+### Conformidade WCAG
+- Nivel alvo: WCAG 2.1 AA
+- Texto legivel e com contraste adequado
+- Acoes claramente identificaveis
+
+## Exemplos
+
+### Uso Basico - 404
+
+```tsx
+import { ErrorPage } from '@etus/ui'
+
+function NotFoundPage() {
+  return (
+    <ErrorPage
+      type="404"
+      showHomeLink
+      showBackLink
+    />
+  )
+}
+```
+
+### Erro 500 com Retry
+
+```tsx
+import { ErrorPage } from '@etus/ui'
+
+function ServerErrorPage() {
+  const handleRetry = () => {
+    window.location.reload()
+  }
+
+  return (
+    <ErrorPage
+      type="500"
+      onRetry={handleRetry}
+      retryLabel="Recarregar pagina"
+    />
+  )
+}
+```
+
+### Acesso Negado (403)
+
+```tsx
+import { ErrorPage } from '@etus/ui'
+import { useRouter } from 'next/navigation'
+
+function ForbiddenPage() {
+  const router = useRouter()
+
+  return (
+    <ErrorPage
+      type="403"
+      description="Voce precisa de permissoes especiais para acessar esta area."
+      actions={
+        <div className="flex gap-2">
+          <Button variant="outline" onClick={() => router.back()}>
+            Voltar
+          </Button>
+          <Button onClick={() => router.push('/request-access')}>
+            Solicitar Acesso
+          </Button>
+        </div>
+      }
+    />
+  )
+}
+```
+
+### Nao Autenticado (401)
+
+```tsx
+import { ErrorPage, Button } from '@etus/ui'
+import { useRouter } from 'next/navigation'
+
+function UnauthorizedPage() {
+  const router = useRouter()
+
+  return (
+    <ErrorPage
+      type="401"
+      title="Sessao expirada"
+      description="Sua sessao expirou. Faca login novamente para continuar."
+      actions={
+        <Button onClick={() => router.push('/login')}>
+          Fazer Login
+        </Button>
+      }
+      showHomeLink={false}
+      showBackLink={false}
+    />
+  )
+}
+```
+
+### Modo Offline
+
+```tsx
+import { useState, useEffect } from 'react'
+import { ErrorPage } from '@etus/ui'
+import { WifiOff } from 'lucide-react'
+
+function OfflinePage() {
+  const [isOnline, setIsOnline] = useState(navigator.onLine)
+
+  useEffect(() => {
+    const handleOnline = () => setIsOnline(true)
+    const handleOffline = () => setIsOnline(false)
+
+    window.addEventListener('online', handleOnline)
+    window.addEventListener('offline', handleOffline)
+
+    return () => {
+      window.removeEventListener('online', handleOnline)
+      window.removeEventListener('offline', handleOffline)
+    }
+  }, [])
+
+  if (isOnline) return null
+
+  return (
+    <ErrorPage
+      type="offline"
+      icon={<WifiOff className="size-16 text-muted-foreground" />}
+      onRetry={() => window.location.reload()}
+      fullScreen
+    />
+  )
+}
+```
+
+### Manutencao Programada
+
+```tsx
+import { ErrorPage } from '@etus/ui'
+import { Wrench } from 'lucide-react'
+
+function MaintenancePage() {
+  return (
+    <ErrorPage
+      type="maintenance"
+      title="Sistema em manutencao"
+      description="Estamos realizando melhorias para voce. Previsao de retorno: 14:00 BRT."
+      icon={<Wrench className="size-16 text-amber-500" />}
+      showHomeLink={false}
+      showBackLink={false}
+      fullScreen
+    />
+  )
+}
+```
+
+### Com Ilustracao Customizada
+
+```tsx
+import { ErrorPage } from '@etus/ui'
+
+function CustomIllustrationError() {
+  return (
+    <ErrorPage
+      type="404"
+      illustration={
+        <img
+          src="/illustrations/404-astronaut.svg"
+          alt="Astronauta perdido"
+          className="w-64 h-64"
+        />
+      }
+      title="Oops! Voce se perdeu no espaco"
+      description="A pagina que voce procura nao existe nesta galaxia."
+    />
+  )
+}
+```
+
+### Erro Generico com Detalhes
+
+```tsx
+import { ErrorPage, Button } from '@etus/ui'
+import { CircleAlert } from 'lucide-react'
+
+function GenericErrorWithDetails({ error }: { error: Error }) {
+  const [showDetails, setShowDetails] = useState(false)
+
+  return (
+    <ErrorPage
+      type="generic"
+      icon={<CircleAlert className="size-16 text-destructive" />}
+      title="Ocorreu um erro"
+      description="Algo inesperado aconteceu. Tente novamente ou entre em contato com o suporte."
+      actions={
+        <div className="flex flex-col gap-4 items-center">
+          <div className="flex gap-2">
+            <Button variant="outline" onClick={() => window.location.reload()}>
+              Recarregar
+            </Button>
+            <Button onClick={() => window.location.href = '/support'}>
+              Contatar Suporte
+            </Button>
+          </div>
+
+          <button
+            className="text-sm text-muted-foreground underline"
+            onClick={() => setShowDetails(!showDetails)}
+          >
+            {showDetails ? 'Ocultar detalhes' : 'Ver detalhes tecnicos'}
+          </button>
+
+          {showDetails && (
+            <pre className="text-xs bg-muted p-4 rounded-md overflow-auto max-w-md">
+              {error.message}
+              {error.stack}
+            </pre>
+          )}
+        </div>
+      }
+    />
+  )
+}
+```
+
+### Tela Cheia
+
+```tsx
+import { ErrorPage } from '@etus/ui'
+
+function FullScreenError() {
+  return (
+    <ErrorPage
+      type="500"
+      fullScreen
+      className="bg-gradient-to-b from-background to-muted"
+    />
+  )
+}
+```
+
+### Integracao com Error Boundary
+
+```tsx
+import { Component } from 'react'
+import { ErrorPage } from '@etus/ui'
+
+class ErrorBoundary extends Component {
+  state = { hasError: false, error: null }
+
+  static getDerivedStateFromError(error) {
+    return { hasError: true, error }
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return (
+        <ErrorPage
+          type="generic"
+          title="Erro na aplicacao"
+          description="Um erro inesperado ocorreu nesta secao."
+          onRetry={() => this.setState({ hasError: false })}
+        />
+      )
+    }
+
+    return this.props.children
+  }
+}
+```
+
+## Testes
+
+### Estrategias de Teste
+
+#### Testes Unitarios
+- Renderizacao com diferentes tipos
+- Exibicao de titulo e descricao customizados
+- Callbacks de acao chamados
+- Links de navegacao presentes
+
+#### Testes de Integracao
+- Navegacao funcional
+- Retry recarrega conteudo
+
+### 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 { ErrorPage } from './ErrorPage'
+
+describe('ErrorPage', () => {
+  it('renders 404 with default content', () => {
+    render(<ErrorPage type="404" />)
+
+    expect(screen.getByText('404')).toBeInTheDocument()
+    expect(screen.getByText('Pagina nao encontrada')).toBeInTheDocument()
+  })
+
+  it('renders custom title and description', () => {
+    render(
+      <ErrorPage
+        type="generic"
+        title="Custom Title"
+        description="Custom description"
+      />
+    )
+
+    expect(screen.getByText('Custom Title')).toBeInTheDocument()
+    expect(screen.getByText('Custom description')).toBeInTheDocument()
+  })
+
+  it('calls onRetry when retry button is clicked', async () => {
+    const user = userEvent.setup()
+    const onRetry = vi.fn()
+
+    render(<ErrorPage type="500" onRetry={onRetry} />)
+
+    await user.click(screen.getByText('Tentar novamente'))
+
+    expect(onRetry).toHaveBeenCalledTimes(1)
+  })
+
+  it('shows home link when showHomeLink is true', () => {
+    render(<ErrorPage type="404" showHomeLink />)
+
+    expect(screen.getByRole('link', { name: /home|inicio/i })).toBeInTheDocument()
+  })
+
+  it('hides back link when showBackLink is false', () => {
+    render(<ErrorPage type="404" showBackLink={false} />)
+
+    expect(screen.queryByRole('link', { name: /voltar|back/i })).not.toBeInTheDocument()
+  })
+
+  it('renders custom actions', () => {
+    render(
+      <ErrorPage
+        type="403"
+        actions={<button>Custom Action</button>}
+      />
+    )
+
+    expect(screen.getByText('Custom Action')).toBeInTheDocument()
+  })
+
+  it('renders custom icon', () => {
+    render(
+      <ErrorPage
+        type="generic"
+        icon={<span data-testid="custom-icon">Icon</span>}
+      />
+    )
+
+    expect(screen.getByTestId('custom-icon')).toBeInTheDocument()
+  })
+
+  it('applies fullScreen class when prop is true', () => {
+    const { container } = render(<ErrorPage type="404" fullScreen />)
+
+    expect(container.firstChild).toHaveClass('min-h-screen')
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+- Conteudo padrao por tipo de erro para consistencia
+- Suporte a ilustracoes SVG e imagens
+- Layout flexivel para diferentes contextos
+- Integracao facil com roteadores (Next.js, React Router)
+- Modo fullScreen para paginas dedicadas
+
+## Referências
+
+- [HTTP Status Codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)
+- [Ant Design Result](https://ant.design/components/result)
+- [Error Page Best Practices](https://www.nngroup.com/articles/error-message-guidelines/)
+- [404 Page Examples](https://www.awwwards.com/awwwards/collections/404-error-page/)

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

@@ -0,0 +1,6 @@
+export { errorDefaults, ErrorPage } from "./ErrorPage"
+export type {
+  ErrorDefault,
+  ErrorPageProps,
+  ErrorType,
+} from "./ErrorPage.types"