@etus/ui 0.1.0

package/src/components/forms/FormValidation/README.md

@@ -0,0 +1,592 @@
+# FormValidation
+
+## Visao Geral
+
+O **FormValidation** e um componente de feedback que exibe mensagens de validacao de formularios com estilos visuais apropriados para cada estado. Suporta deteccao automatica do estado baseado na prop de mensagem fornecida.
+
+### Casos de Uso
+
+- Exibir mensagens de erro em campos de formulario
+- Mostrar confirmacao de sucesso apos validacao
+- Alertas de warning para situacoes de atencao
+- Texto de ajuda/hint para orientar o usuario
+
+### Classificacao
+
+**Categoria:** Form
+**Dependencias:** `class-variance-authority`
+
+---
+
+## Design Specs
+
+### Estados (`state`)
+
+| Estado | Uso | Token de Cor |
+|--------|-----|--------------|
+| `idle` | Texto de ajuda/hint | `text-muted-foreground` |
+| `error` | Mensagem de erro | `text-destructive` |
+| `success` | Confirmacao positiva | `text-success` |
+| `warning` | Alerta de atencao | `text-warning` |
+
+### Prioridade de Deteccao Automatica
+
+Quando `state` nao e fornecido, o componente detecta automaticamente:
+
+1. `error` (maior prioridade)
+2. `warning`
+3. `success`
+4. `idle` (fallback para `help`)
+
+### Tokens Utilizados
+
+```css
+/* Cores */
+--destructive       /* Estado error */
+--success           /* Estado success */
+--warning           /* Estado warning */
+--muted-foreground  /* Estado idle */
+
+/* Tipografia */
+text-sm             /* 14px */
+
+/* Espacamento */
+mt-1.5              /* Margin-top 6px */
+```
+
+### data-slot
+
+```html
+<div data-slot="form-validation" data-state="error">...</div>
+```
+
+---
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `state` | `"idle" \| "error" \| "success" \| "warning"` | Auto-detectado | Estado de validacao (controle explicito) |
+| `error` | `ReactNode` | - | Mensagem de erro |
+| `success` | `ReactNode` | - | Mensagem de sucesso |
+| `warning` | `ReactNode` | - | Mensagem de warning |
+| `help` | `ReactNode` | - | Texto de ajuda (estado idle) |
+| `className` | `string` | - | Classes CSS adicionais |
+
+> Herda todas as props de `React.ComponentProps<"div">`
+
+### TypeScript
+
+```typescript
+import type { FormValidationProps, FormValidationState } from "@etus/ui"
+
+// FormValidationState
+type FormValidationState = "idle" | "error" | "success" | "warning"
+
+// FormValidationProps
+interface FormValidationProps extends ComponentProps<"div"> {
+  state?: FormValidationState
+  error?: ReactNode
+  success?: ReactNode
+  warning?: ReactNode
+  help?: ReactNode
+}
+```
+
+### Comparativo com Design Systems de Referencia
+
+#### Matriz de Features (12 Design Systems)
+
+| Feature | ETUS | Shadcn | Chakra | MUI | Mantine | AntD | NextUI | Fluent | Carbon |
+|---------|:----:|:------:|:------:|:---:|:-------:|:----:|:------:|:------:|:------:|
+| **Auto-detect state** | Y | - | - | - | - | - | - | - | - |
+| **Multiple message props** | Y | - | Y | - | Y | - | - | - | - |
+| **error/success/warning** | Y | - | Y | Y | Y | Y | Y | Y | Y |
+| **help text** | Y | - | Y | Y | Y | Y | Y | Y | Y |
+| **CVA/cva** | Y | Y | - | - | - | - | Y | - | - |
+| **data-slot** | Y | Y | - | - | - | - | Y | - | - |
+| **aria roles** | Y | - | Y | Y | Y | - | Y | Y | Y |
+| **Icon support** | - | - | Y | Y | Y | Y | Y | Y | Y |
+| **Animated** | - | - | Y | - | Y | - | Y | - | - |
+
+#### Comparativo de Abordagens
+
+| Design System | Componente | Abordagem |
+|---------------|------------|-----------|
+| **ETUS** | `FormValidation` | Props individuais (error, success, warning, help) com auto-detect |
+| **Chakra UI** | `FormErrorMessage`, `FormHelperText` | Componentes separados por tipo |
+| **MUI** | `FormHelperText` | Componente unico com prop `error` |
+| **Mantine** | `Input.Error`, `Input.Description` | Subcomponentes de Input |
+| **Ant Design** | `Form.Item` | Integrado ao Form.Item via `validateStatus` |
+| **React Hook Form** | `ErrorMessage` | Componente dedicado a erros |
+| **Fluent UI** | `Field` | Integrado ao Field wrapper |
+| **Carbon** | `FormItem` | Integrado ao wrapper de form |
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo | Uso | Quando |
+|----------|-----|--------|
+| `role="alert"` | Anuncia imediatamente para screen readers | Estado `error` |
+| `role="status"` | Anuncia quando conveniente | Estado `success` |
+| `data-state` | Indica estado atual | Sempre |
+
+### Screen Readers
+
+- Mensagens de erro sao anunciadas imediatamente (`role="alert"`)
+- Mensagens de sucesso sao anunciadas quando possivel (`role="status"`)
+- Estados warning e idle nao tem role especifico
+
+### Contraste de Cores
+
+Todos os pares de cores seguem WCAG 2.1 AA (minimo 4.5:1):
+
+| Estado | Cor | Sobre Background |
+|--------|-----|------------------|
+| error | `--destructive` | >= 4.5:1 |
+| success | `--success` | >= 4.5:1 |
+| warning | `--warning` | >= 4.5:1 |
+| idle | `--muted-foreground` | >= 4.5:1 |
+
+### Associacao com Input
+
+Para associar a mensagem ao input, use `aria-describedby`:
+
+```tsx
+<Input id="email" aria-describedby="email-validation" />
+<FormValidation id="email-validation" error="Email invalido" />
+```
+
+---
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import { FormValidation } from "@etus/ui"
+
+function Example() {
+  return <FormValidation error="Este campo e obrigatorio" />
+}
+```
+
+### Deteccao Automatica de Estado
+
+```tsx
+// Estado auto-detectado como "error"
+<FormValidation error="Email invalido" />
+
+// Estado auto-detectado como "success"
+<FormValidation success="Email disponivel" />
+
+// Estado auto-detectado como "warning"
+<FormValidation warning="Senha fraca" />
+
+// Estado auto-detectado como "idle"
+<FormValidation help="Digite seu email" />
+```
+
+### Controle Explicito de Estado
+
+```tsx
+// Forcando estado especifico
+<FormValidation state="error" error="Formato invalido" />
+<FormValidation state="success" success="Verificado!" />
+```
+
+### Prioridade de Mensagens
+
+```tsx
+// Erro tem prioridade - mostra "Campo obrigatorio"
+<FormValidation
+  error="Campo obrigatorio"
+  success="Tudo certo"
+  help="Preencha este campo"
+/>
+
+// Warning tem prioridade sobre success
+<FormValidation
+  warning="Senha poderia ser mais forte"
+  success="Senha aceita"
+/>
+```
+
+### Com Formulario Condicional
+
+```tsx
+import { FormValidation } from "@etus/ui"
+
+function EmailField({ error, isValid }: { error?: string; isValid: boolean }) {
+  return (
+    <div>
+      <Input placeholder="Email" />
+      <FormValidation
+        error={error}
+        success={isValid ? "Email valido!" : undefined}
+        help="Nunca compartilharemos seu email"
+      />
+    </div>
+  )
+}
+```
+
+### Integracao com React Hook Form
+
+```tsx
+import { useForm } from "react-hook-form"
+import { Input, FormValidation } from "@etus/ui"
+
+function ContactForm() {
+  const { register, formState: { errors } } = useForm()
+
+  return (
+    <form>
+      <div>
+        <Input {...register("email", { required: true })} />
+        <FormValidation
+          error={errors.email?.message}
+          help="Digite seu email de contato"
+        />
+      </div>
+    </form>
+  )
+}
+```
+
+### Com Zod e React Hook Form
+
+```tsx
+import { useForm } from "react-hook-form"
+import { zodResolver } from "@hookform/resolvers/zod"
+import { z } from "zod"
+
+const schema = z.object({
+  password: z.string()
+    .min(8, "Minimo 8 caracteres")
+    .regex(/[A-Z]/, "Pelo menos uma maiuscula")
+})
+
+function PasswordField() {
+  const { register, formState: { errors }, watch } = useForm({
+    resolver: zodResolver(schema)
+  })
+
+  const password = watch("password")
+  const isStrong = password?.length >= 12
+
+  return (
+    <div>
+      <Input type="password" {...register("password")} />
+      <FormValidation
+        error={errors.password?.message}
+        warning={password && !isStrong ? "Senha poderia ser mais forte" : undefined}
+        success={isStrong ? "Senha forte!" : undefined}
+        help="Use letras, numeros e simbolos"
+      />
+    </div>
+  )
+}
+```
+
+### Mensagem com Conteudo Rico
+
+```tsx
+<FormValidation
+  error={
+    <span>
+      Email invalido. <a href="/help">Precisa de ajuda?</a>
+    </span>
+  }
+/>
+```
+
+### Com Acessibilidade Completa
+
+```tsx
+<div>
+  <Label htmlFor="username">Nome de usuario</Label>
+  <Input
+    id="username"
+    aria-describedby="username-validation"
+    aria-invalid={!!error}
+  />
+  <FormValidation
+    id="username-validation"
+    error={error}
+    help="Escolha um nome unico"
+  />
+</div>
+```
+
+---
+
+## Testes
+
+### Testes Unitarios
+
+```tsx
+// FormValidation.test.tsx
+import { render, screen } from "@testing-library/react"
+import { describe, expect, it } from "vitest"
+import { FormValidation } from "./FormValidation"
+
+describe("FormValidation", () => {
+  it("renders error message", () => {
+    render(<FormValidation error="Campo obrigatorio" />)
+    expect(screen.getByText("Campo obrigatorio")).toBeInTheDocument()
+  })
+
+  it("renders success message", () => {
+    render(<FormValidation success="Validado!" />)
+    expect(screen.getByText("Validado!")).toBeInTheDocument()
+  })
+
+  it("renders warning message", () => {
+    render(<FormValidation warning="Atencao" />)
+    expect(screen.getByText("Atencao")).toBeInTheDocument()
+  })
+
+  it("renders help text", () => {
+    render(<FormValidation help="Dica util" />)
+    expect(screen.getByText("Dica util")).toBeInTheDocument()
+  })
+
+  it("returns null when no message", () => {
+    const { container } = render(<FormValidation />)
+    expect(container).toBeEmptyDOMElement()
+  })
+
+  it("has data-slot attribute", () => {
+    render(<FormValidation error="Erro" />)
+    expect(screen.getByText("Erro")).toHaveAttribute("data-slot", "form-validation")
+  })
+
+  it("has data-state attribute", () => {
+    render(<FormValidation error="Erro" />)
+    expect(screen.getByText("Erro")).toHaveAttribute("data-state", "error")
+  })
+})
+```
+
+### Testes de Prioridade
+
+```tsx
+describe("FormValidation priority", () => {
+  it("error takes priority over warning", () => {
+    render(<FormValidation error="Erro" warning="Warning" />)
+    expect(screen.getByText("Erro")).toBeInTheDocument()
+    expect(screen.queryByText("Warning")).not.toBeInTheDocument()
+  })
+
+  it("warning takes priority over success", () => {
+    render(<FormValidation warning="Warning" success="Success" />)
+    expect(screen.getByText("Warning")).toBeInTheDocument()
+    expect(screen.queryByText("Success")).not.toBeInTheDocument()
+  })
+
+  it("success takes priority over help", () => {
+    render(<FormValidation success="Success" help="Help" />)
+    expect(screen.getByText("Success")).toBeInTheDocument()
+    expect(screen.queryByText("Help")).not.toBeInTheDocument()
+  })
+
+  it("explicit state overrides auto-detection", () => {
+    render(<FormValidation state="warning" error="Erro" warning="Warning" />)
+    expect(screen.getByText("Warning")).toBeInTheDocument()
+  })
+})
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"
+
+expect.extend(toHaveNoViolations)
+
+describe("FormValidation accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(<FormValidation error="Erro" />)
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("error state has role alert", () => {
+    render(<FormValidation error="Erro critico" />)
+    expect(screen.getByRole("alert")).toBeInTheDocument()
+  })
+
+  it("success state has role status", () => {
+    render(<FormValidation success="Sucesso" />)
+    expect(screen.getByRole("status")).toBeInTheDocument()
+  })
+
+  it("warning state has no role", () => {
+    render(<FormValidation warning="Aviso" />)
+    expect(screen.queryByRole("alert")).not.toBeInTheDocument()
+    expect(screen.queryByRole("status")).not.toBeInTheDocument()
+  })
+})
+```
+
+### Testes de Estilo
+
+```tsx
+describe("FormValidation styling", () => {
+  it("applies error styles", () => {
+    render(<FormValidation error="Erro" />)
+    expect(screen.getByText("Erro")).toHaveClass("text-destructive")
+  })
+
+  it("applies success styles", () => {
+    render(<FormValidation success="Ok" />)
+    expect(screen.getByText("Ok")).toHaveClass("text-success")
+  })
+
+  it("applies warning styles", () => {
+    render(<FormValidation warning="Atencao" />)
+    expect(screen.getByText("Atencao")).toHaveClass("text-warning")
+  })
+
+  it("applies idle styles", () => {
+    render(<FormValidation help="Ajuda" />)
+    expect(screen.getByText("Ajuda")).toHaveClass("text-muted-foreground")
+  })
+
+  it("merges custom className", () => {
+    render(<FormValidation error="Erro" className="custom-class" />)
+    expect(screen.getByText("Erro")).toHaveClass("custom-class")
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+### Implementado
+
+#### Auto-detect State
+
+Deteccao automatica do estado baseado na prop de mensagem fornecida.
+
+```tsx
+// Detecta automaticamente como "error"
+<FormValidation error="Mensagem de erro" />
+```
+
+#### ARIA Roles
+
+Roles de acessibilidade automaticos para error e success.
+
+```tsx
+<FormValidation error="..." /> // role="alert"
+<FormValidation success="..." /> // role="status"
+```
+
+### Prioridade Media
+
+#### Icones por Estado
+
+Adicionar icones automaticos baseados no estado.
+
+```tsx
+// Proposta de API
+interface FormValidationProps {
+  showIcon?: boolean
+}
+
+// Uso
+<FormValidation error="Erro" showIcon />
+// Renderiza: [X icon] Erro
+```
+
+**Referencias:** Chakra UI, MUI, Mantine, Ant Design
+
+#### Animacao de Entrada
+
+Animacao suave ao aparecer.
+
+```tsx
+// Proposta de API
+interface FormValidationProps {
+  animated?: boolean
+}
+```
+
+**Referencias:** Chakra UI, Mantine, NextUI
+
+### Prioridade Baixa
+
+#### Multiplas Mensagens
+
+Exibir lista de erros.
+
+```tsx
+// Proposta de API
+<FormValidation
+  errors={["Minimo 8 caracteres", "Precisa de numero"]}
+/>
+```
+
+**Referencias:** React Hook Form ErrorMessage
+
+#### Contagem de Caracteres
+
+Exibir contagem integrada.
+
+```tsx
+// Proposta de API
+<FormValidation
+  help="Digite sua bio"
+  charCount={{ current: 50, max: 200 }}
+/>
+```
+
+**Referencias:** MUI TextField, Mantine Textarea
+
+### Decisoes de Design
+
+| Feature | Recomendacao | Justificativa |
+|---------|--------------|---------------|
+| Auto-detect | Implementado | Reduz boilerplate, DX melhor |
+| ARIA roles | Implementado | Acessibilidade essencial |
+| Icons | Avaliar | Pode aumentar bundle |
+| Animation | Avaliar | CSS nativo possivel |
+| Multiple errors | Evitar | Complexidade, usar lista manual |
+| Char count | Evitar | Responsabilidade do Input |
+
+---
+
+## Referencias
+
+### Design Systems Analisados
+
+| Design System | Componente | Documentacao |
+|---------------|------------|--------------|
+| **Shadcn/ui** | Form | [Form](https://ui.shadcn.com/docs/components/form) |
+| **Chakra UI** | FormErrorMessage | [Form Control](https://chakra-ui.com/docs/components/form-control) |
+| **MUI** | FormHelperText | [Form Helper Text](https://mui.com/material-ui/api/form-helper-text/) |
+| **Mantine** | Input.Error | [Input](https://mantine.dev/core/input/) |
+| **Ant Design** | Form.Item | [Form](https://ant.design/components/form) |
+| **NextUI** | - | Integrado ao Input |
+| **Fluent UI** | Field | [Field](https://react.fluentui.dev/?path=/docs/components-field--default) |
+| **Carbon** | FormItem | [Form](https://carbondesignsystem.com/components/form/usage/) |
+| **React Hook Form** | ErrorMessage | [ErrorMessage](https://react-hook-form.com/api/useformstate/errormessage) |
+
+### Especificacoes e Padroes
+
+- [WAI-ARIA - Forms](https://www.w3.org/WAI/tutorials/forms/)
+- [ARIA Live Regions](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions)
+- [WCAG 3.3 Input Assistance](https://www.w3.org/WAI/WCAG21/quickref/#input-assistance)
+
+### Ferramentas Utilizadas
+
+- [CVA - Class Variance Authority](https://cva.style/docs)
+- [Tailwind CSS](https://tailwindcss.com/docs)

package/src/components/forms/FormValidation/index.ts

@@ -0,0 +1,4 @@
+export { FormValidation } from "./FormValidation"
+export { formValidationVariants } from "./FormValidation.variants"
+export type { FormValidationProps, FormValidationState } from "./FormValidation.types"
+export type { FormValidationVariantProps } from "./FormValidation.variants"