@etus/ui 0.1.0

package/src/components/advanced/ErrorBoundary/ErrorBoundary.variants.ts

@@ -0,0 +1,153 @@
+import { cva } from "class-variance-authority"
+
+/**
+ * ErrorBoundary fallback container variants
+ */
+export const errorBoundaryFallbackVariants = cva(
+  "flex flex-col items-center justify-center text-center",
+  {
+    variants: {
+      variant: {
+        minimal: "p-4 gap-2",
+        detailed: "p-6 gap-4",
+        action: "p-6 gap-4",
+        fullscreen: "min-h-screen p-8 gap-6",
+      },
+      severity: {
+        error: "text-destructive",
+        warning: "text-warning",
+        info: "text-muted-foreground",
+      },
+    },
+    defaultVariants: {
+      variant: "detailed",
+      severity: "error",
+    },
+  }
+)
+
+/**
+ * ErrorBoundary fallback card variants
+ */
+export const errorBoundaryCardVariants = cva(
+  "rounded-lg border bg-background p-6",
+  {
+    variants: {
+      variant: {
+        minimal: "border-border",
+        detailed: "border-destructive/50 bg-destructive/5",
+        action: "border-destructive/50 bg-destructive/5",
+        fullscreen: "border-destructive/50 bg-destructive/5 max-w-md w-full",
+      },
+    },
+    defaultVariants: {
+      variant: "detailed",
+    },
+  }
+)
+
+/**
+ * ErrorBoundary icon variants
+ */
+export const errorBoundaryIconVariants = cva(
+  "shrink-0",
+  {
+    variants: {
+      size: {
+        sm: "h-8 w-8",
+        md: "h-12 w-12",
+        lg: "h-16 w-16",
+      },
+      severity: {
+        error: "text-destructive",
+        warning: "text-warning",
+        info: "text-muted-foreground",
+      },
+    },
+    defaultVariants: {
+      size: "md",
+      severity: "error",
+    },
+  }
+)
+
+/**
+ * ErrorBoundary title variants
+ */
+export const errorBoundaryTitleVariants = cva(
+  "font-semibold",
+  {
+    variants: {
+      size: {
+        sm: "text-base",
+        md: "text-lg",
+        lg: "text-xl",
+      },
+    },
+    defaultVariants: {
+      size: "md",
+    },
+  }
+)
+
+/**
+ * ErrorBoundary message variants
+ */
+export const errorBoundaryMessageVariants = cva(
+  "text-muted-foreground",
+  {
+    variants: {
+      size: {
+        sm: "text-xs",
+        md: "text-sm",
+        lg: "text-base",
+      },
+    },
+    defaultVariants: {
+      size: "md",
+    },
+  }
+)
+
+/**
+ * ErrorBoundary stack trace variants
+ */
+export const errorBoundaryStackVariants = cva(
+  "w-full overflow-auto rounded-md bg-muted p-4 text-left font-mono text-xs text-muted-foreground",
+  {
+    variants: {
+      collapsed: {
+        true: "max-h-24",
+        false: "max-h-64",
+      },
+    },
+    defaultVariants: {
+      collapsed: true,
+    },
+  }
+)
+
+/**
+ * ErrorBoundary action button variants
+ */
+export const errorBoundaryActionVariants = cva(
+  "inline-flex items-center justify-center gap-2 rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+  {
+    variants: {
+      variant: {
+        primary: "bg-primary text-primary-foreground hover:bg-primary/90",
+        outline: "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
+        ghost: "hover:bg-accent hover:text-accent-foreground",
+      },
+      size: {
+        sm: "h-8 px-3 text-sm",
+        md: "h-9 px-4 text-sm",
+        lg: "h-10 px-6 text-base",
+      },
+    },
+    defaultVariants: {
+      variant: "primary",
+      size: "md",
+    },
+  }
+)

package/src/components/advanced/ErrorBoundary/README.md

@@ -0,0 +1,296 @@
+# ErrorBoundary
+
+## Visão Geral
+
+O ErrorBoundary e um componente utilitario que captura erros JavaScript em sua arvore de componentes filhos, registra esses erros e exibe uma UI de fallback. Essencial para prevenir que erros em uma parte da aplicacao quebrem toda a interface.
+
+### Classificacao Atomica
+- **Categoria**: Utilities
+- **Subcategoria**: Error Handling
+
+### Casos de Uso Comuns
+- Wrapper de aplicacao para erros globais
+- Isolamento de secoes criticas
+- Fallback para componentes dinamicos
+- Integracao com servicos de monitoramento (Sentry)
+- Graceful degradation de features
+
+### Relacao com Outros Componentes
+- **Alert**: Exibicao de mensagem de erro
+- **Button**: Acao de retry
+- **Card**: Container de fallback UI
+
+## Design Specs
+
+### Variantes de Fallback
+
+- **minimal**: Apenas mensagem de erro
+- **detailed**: Mensagem com stack trace (dev)
+- **action**: Mensagem com botao de retry
+- **custom**: Componente customizado
+
+### Estados
+
+- **Normal**: Renderiza children normalmente
+- **Error**: Exibe fallback UI
+- **Recovering**: Tentando recuperar
+
+### Tokens de Design
+
+#### Cores (Fallback UI)
+- Background: `bg-destructive/10`
+- Border: `border-destructive`
+- Text: `text-destructive`
+- Icon: `text-destructive`
+
+#### Espacamento
+- Container: `p-6`
+- Gap: `gap-4`
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `children` | `ReactNode` | required | Componentes a serem monitorados |
+| `fallback` | `ReactNode \| FallbackRender` | - | UI de fallback |
+| `onError` | `(error: Error, info: ErrorInfo) => void` | - | Callback de erro |
+| `onReset` | `() => void` | - | Callback ao resetar |
+| `resetKeys` | `unknown[]` | - | Keys que disparam reset |
+| `FallbackComponent` | `ComponentType<FallbackProps>` | - | Componente de fallback |
+
+### Interfaces TypeScript
+
+```typescript
+export interface ErrorBoundaryProps {
+  children: React.ReactNode
+  fallback?: React.ReactNode | FallbackRender
+  FallbackComponent?: React.ComponentType<FallbackProps>
+  onError?: (error: Error, errorInfo: React.ErrorInfo) => void
+  onReset?: () => void
+  resetKeys?: unknown[]
+}
+
+export interface FallbackProps {
+  error: Error
+  resetErrorBoundary: () => void
+}
+
+export type FallbackRender = (props: FallbackProps) => React.ReactNode
+```
+
+### Comparacao com Referencias
+
+| Design System | Caracteristicas |
+|---------------|-----------------|
+| **react-error-boundary** | Biblioteca padrao da comunidade |
+| **Sentry** | Integracao com error tracking |
+| **Next.js** | error.tsx para rotas |
+| **Remix** | ErrorBoundary por rota |
+
+## Acessibilidade (A11y)
+
+### Atributos ARIA
+- `role="alert"`: Fallback anunciado como alerta
+- `aria-live="assertive"`: Anuncio imediato
+- Focus automatico no fallback
+
+### Conformidade WCAG
+- Mensagens de erro claras e descritivas
+- Botao de acao acessivel
+- Contraste adequado
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import { ErrorBoundary } from "@etus/ui"
+
+export function App() {
+  return (
+    <ErrorBoundary fallback={<p>Something went wrong</p>}>
+      <MyComponent />
+    </ErrorBoundary>
+  )
+}
+```
+
+### Com Fallback Component
+
+```tsx
+import { ErrorBoundary } from "@etus/ui"
+import { Alert, AlertDescription, AlertTitle } from "@etus/ui"
+import { Button } from "@etus/ui"
+import { AlertCircleIcon } from "lucide-react"
+
+function ErrorFallback({ error, resetErrorBoundary }) {
+  return (
+    <Alert variant="destructive">
+      <AlertCircleIcon className="h-4 w-4" />
+      <AlertTitle>Something went wrong</AlertTitle>
+      <AlertDescription>
+        {error.message}
+      </AlertDescription>
+      <Button onClick={resetErrorBoundary} className="mt-4">
+        Try again
+      </Button>
+    </Alert>
+  )
+}
+
+export function ProtectedComponent() {
+  return (
+    <ErrorBoundary FallbackComponent={ErrorFallback}>
+      <RiskyComponent />
+    </ErrorBoundary>
+  )
+}
+```
+
+### Com Error Logging
+
+```tsx
+import { ErrorBoundary } from "@etus/ui"
+import * as Sentry from "@sentry/react"
+
+export function MonitoredApp() {
+  return (
+    <ErrorBoundary
+      onError={(error, errorInfo) => {
+        Sentry.captureException(error, {
+          extra: { componentStack: errorInfo.componentStack }
+        })
+      }}
+      fallback={<ErrorPage />}
+    >
+      <App />
+    </ErrorBoundary>
+  )
+}
+```
+
+### Com Reset Keys
+
+```tsx
+import { ErrorBoundary } from "@etus/ui"
+import { useLocation } from "react-router-dom"
+
+export function RouteErrorBoundary({ children }) {
+  const location = useLocation()
+
+  return (
+    <ErrorBoundary
+      resetKeys={[location.pathname]}
+      fallback={<div>Error loading page</div>}
+    >
+      {children}
+    </ErrorBoundary>
+  )
+}
+```
+
+### Render Prop Pattern
+
+```tsx
+import { ErrorBoundary } from "@etus/ui"
+
+export function FlexibleErrorBoundary() {
+  return (
+    <ErrorBoundary
+      fallback={({ error, resetErrorBoundary }) => (
+        <div className="p-4 border border-destructive rounded">
+          <h2>Oops! {error.message}</h2>
+          <button onClick={resetErrorBoundary}>
+            Reset
+          </button>
+        </div>
+      )}
+    >
+      <DynamicComponent />
+    </ErrorBoundary>
+  )
+}
+```
+
+## Testes
+
+### Estrategias de Teste
+
+```typescript
+describe("ErrorBoundary", () => {
+  it("renders children when no error", () => {})
+  it("catches errors and shows fallback", () => {})
+  it("calls onError callback", () => {})
+  it("resets on resetKeys change", () => {})
+  it("resets via resetErrorBoundary", () => {})
+})
+```
+
+### Exemplo de Teste
+
+```typescript
+import { render, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { ErrorBoundary } from "./ErrorBoundary"
+
+const ThrowError = () => {
+  throw new Error("Test error")
+}
+
+describe("ErrorBoundary", () => {
+  it("shows fallback on error", () => {
+    const spy = vi.spyOn(console, "error").mockImplementation(() => {})
+
+    render(
+      <ErrorBoundary fallback={<div>Error occurred</div>}>
+        <ThrowError />
+      </ErrorBoundary>
+    )
+
+    expect(screen.getByText("Error occurred")).toBeInTheDocument()
+    spy.mockRestore()
+  })
+
+  it("recovers on reset", async () => {
+    const spy = vi.spyOn(console, "error").mockImplementation(() => {})
+    let shouldThrow = true
+
+    const MaybeThrow = () => {
+      if (shouldThrow) throw new Error("Error")
+      return <div>Recovered</div>
+    }
+
+    render(
+      <ErrorBoundary
+        FallbackComponent={({ resetErrorBoundary }) => (
+          <button onClick={resetErrorBoundary}>Reset</button>
+        )}
+      >
+        <MaybeThrow />
+      </ErrorBoundary>
+    )
+
+    shouldThrow = false
+    await userEvent.click(screen.getByText("Reset"))
+
+    expect(screen.getByText("Recovered")).toBeInTheDocument()
+    spy.mockRestore()
+  })
+})
+```
+
+## Roadmap / Features Futuras
+
+- Class component necessario para componentDidCatch
+- Nao captura erros em event handlers
+- Nao captura erros em codigo assincrono
+- Nao captura erros no proprio ErrorBoundary
+- Considerar uso com Suspense para loading states
+
+## Referências
+
+- [React Error Boundaries](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary)
+- [react-error-boundary](https://github.com/bvaughn/react-error-boundary)
+- [Sentry React SDK](https://docs.sentry.io/platforms/javascript/guides/react/)

package/src/components/advanced/ErrorBoundary/index.ts

@@ -0,0 +1,18 @@
+export type {
+  ErrorBoundaryProps,
+  ErrorBoundaryState,
+  FallbackProps,
+  FallbackRender,
+} from "./ErrorBoundary.types"
+
+export { DefaultFallback, ErrorBoundary } from "./ErrorBoundary"
+
+export {
+  errorBoundaryActionVariants,
+  errorBoundaryCardVariants,
+  errorBoundaryFallbackVariants,
+  errorBoundaryIconVariants,
+  errorBoundaryMessageVariants,
+  errorBoundaryStackVariants,
+  errorBoundaryTitleVariants,
+} from "./ErrorBoundary.variants"