@etus/ui 0.1.0

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

@@ -0,0 +1,931 @@
+# Field
+
+## Visão Geral
+
+O **Field** e um conjunto de componentes compostos para estruturar campos de formulario no Design System ETUS. Fornece organizacao semantica, labels, descricoes, mensagens de erro e agrupamento de campos, garantindo acessibilidade e consistencia visual.
+
+### Casos de Uso
+
+- Estruturar campos de formulario com label, input e mensagem de erro
+- Agrupar campos relacionados (fieldsets)
+- Layouts verticais, horizontais ou responsivos
+- Campos com descricao auxiliar (helper text)
+- Validacao com exibicao de erros
+- Checkbox/Radio com labels clicaveis
+- Separadores visuais entre grupos de campos
+
+### Classificacao
+
+**Categoria:** Molecule (Form Building Block)
+**Dependencias:** `class-variance-authority`, `@/components/primitives/Label`, `@/components/primitives/Divider`
+
+### Componentes do Sistema
+
+| Componente | Funcao |
+|------------|--------|
+| `Field` | Container principal do campo |
+| `FieldSet` | Agrupa campos semanticamente (`<fieldset>`) |
+| `FieldGroup` | Agrupa multiplos campos visualmente |
+| `FieldLegend` | Titulo do fieldset (`<legend>`) |
+| `FieldLabel` | Label associado ao input |
+| `FieldTitle` | Titulo nao-label (apenas visual) |
+| `FieldContent` | Container para input + descricao |
+| `FieldDescription` | Texto auxiliar/helper |
+| `FieldError` | Mensagem de erro de validacao |
+| `FieldSeparator` | Divisor entre campos |
+
+---
+
+## Design Specs
+
+### Variantes de Orientacao (`orientation`)
+
+| Variante | Classes | Uso |
+|----------|---------|-----|
+| `vertical` | `flex-col [&>*]:w-full` | Padrao, label acima do input |
+| `horizontal` | `flex-row items-center` | Label ao lado do input |
+| `responsive` | `flex-col @md/field-group:flex-row` | Vertical em mobile, horizontal em desktop |
+
+### Espacamentos
+
+| Contexto | Gap | Classes |
+|----------|-----|---------|
+| Entre campos (FieldGroup) | `gap-7` (28px) | Espacamento vertical padrao |
+| Entre label e input (vertical) | `gap-3` (12px) | Via Field |
+| Entre input e descricao | `gap-1.5` (6px) | Via FieldContent |
+| Checkbox/Radio groups | `gap-3` (12px) | Reduzido automaticamente |
+
+### Estados Visuais
+
+| Estado | Classes/Data Attributes | Comportamento |
+|--------|-------------------------|---------------|
+| Default | - | Aparencia base |
+| Invalid | `data-[invalid=true]:text-destructive` | Texto vermelho para erros |
+| Disabled | `group-data-[disabled=true]/field:opacity-50` | 50% opacidade |
+| Checked (Checkbox/Radio) | `has-data-[state=checked]:bg-primary/5` | Background sutil no container |
+
+### Tokens Utilizados
+
+```css
+/* Cores */
+--destructive         /* Cor de erro */
+--muted-foreground    /* Descricao */
+--primary             /* Checkbox/radio checked background */
+--background          /* Fundo do separador */
+--border              /* Linha do separador */
+
+/* Tipografia */
+text-sm               /* Labels e descricoes (14px) */
+text-base             /* Legend variant=legend (16px) */
+font-medium           /* Labels e legendas */
+font-normal           /* Descricoes e erros */
+leading-snug          /* Line-height compacto */
+
+/* Espacamento */
+gap-3                 /* Field interno */
+gap-6                 /* FieldSet entre campos */
+gap-7                 /* FieldGroup entre campos */
+gap-1.5               /* FieldContent interno */
+```
+
+### Data Slots
+
+```html
+<fieldset data-slot="field-set">
+  <legend data-slot="field-legend">...</legend>
+  <div data-slot="field-group">
+    <div data-slot="field" role="group">
+      <label data-slot="field-label">...</label>
+      <div data-slot="field-content">
+        <input />
+        <p data-slot="field-description">...</p>
+      </div>
+      <div data-slot="field-error" role="alert">...</div>
+    </div>
+    <div data-slot="field-separator">...</div>
+  </div>
+</fieldset>
+```
+
+---
+
+## API
+
+### Field
+
+Container principal com suporte a orientacao.
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `orientation` | `"vertical" \| "horizontal" \| "responsive"` | `"vertical"` | Direcao do layout |
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Conteudo do campo |
+
+> Herda todas as props de `React.ComponentProps<"div">`
+
+```typescript
+import { cva, type VariantProps } from "class-variance-authority"
+
+const fieldVariants = cva(
+  "group/field flex w-full gap-3 data-[invalid=true]:text-destructive",
+  {
+    variants: {
+      orientation: {
+        vertical: ["flex-col [&>*]:w-full [&>.sr-only]:w-auto"],
+        horizontal: [
+          "flex-row items-center",
+          "[&>[data-slot=field-label]]:flex-auto",
+          "has-[>[data-slot=field-content]]:items-start"
+        ],
+        responsive: [
+          "flex-col [&>*]:w-full @md/field-group:flex-row @md/field-group:items-center"
+        ],
+      },
+    },
+    defaultVariants: { orientation: "vertical" },
+  }
+)
+
+type FieldProps = React.ComponentProps<"div"> & VariantProps<typeof fieldVariants>
+```
+
+### FieldSet
+
+Agrupamento semantico de campos (HTML `<fieldset>`).
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Campos do grupo |
+
+> Herda todas as props de `React.ComponentProps<"fieldset">`
+
+### FieldGroup
+
+Agrupamento visual de campos com container queries.
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Campos do grupo |
+
+> Herda todas as props de `React.ComponentProps<"div">`
+
+### FieldLegend
+
+Titulo para FieldSet.
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `variant` | `"legend" \| "label"` | `"legend"` | Tamanho do texto |
+| `className` | `string` | - | Classes CSS adicionais |
+
+> Herda todas as props de `React.ComponentProps<"legend">`
+
+### FieldLabel
+
+Label clicavel associado ao input.
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Texto do label |
+
+> Herda todas as props de `Label` (de `@radix-ui/react-label`)
+
+### FieldTitle
+
+Titulo visual (nao-label) para grupos.
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Texto do titulo |
+
+> Herda todas as props de `React.ComponentProps<"div">`
+
+### FieldContent
+
+Container para input com descricao.
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Input e descricao |
+
+> Herda todas as props de `React.ComponentProps<"div">`
+
+### FieldDescription
+
+Texto auxiliar/helper text.
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Texto de ajuda |
+
+> Herda todas as props de `React.ComponentProps<"p">`
+
+### FieldError
+
+Mensagem de erro de validacao.
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `errors` | `Array<{ message?: string }>` | - | Array de erros (react-hook-form compativel) |
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Mensagem customizada (sobrescreve errors) |
+
+> Herda todas as props de `React.ComponentProps<"div">`
+
+### FieldSeparator
+
+Divisor visual entre campos.
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `children` | `ReactNode` | - | Texto central (opcional) |
+| `className` | `string` | - | Classes CSS adicionais |
+
+> Herda todas as props de `React.ComponentProps<"div">`
+
+### Comparativo com Design Systems de Referencia
+
+#### Matriz de Features (14 Design Systems)
+
+| Feature | ETUS | Shadcn | Radix | Chakra | MUI | Mantine | AntD | NextUI | Headless | Ariakit | Fluent | Carbon | Blueprint | Prime |
+|---------|:----:|:------:|:-----:|:------:|:---:|:-------:|:----:|:------:|:--------:|:-------:|:------:|:------:|:---------:|:-----:|
+| **Field Container** | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Label** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Description** | ✓ | - | - | ✓ | ✓ | ✓ | - | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Error Message** | ✓ | - | - | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **FieldSet/Group** | ✓ | - | - | ✓ | - | ✓ | ✓ | - | - | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Orientation** | ✓ | - | - | - | - | - | - | - | - | - | - | ✓ | - | ✓ |
+| **Responsive** | ✓ | - | - | - | - | - | - | - | - | - | - | - | - | - |
+| **Container Queries** | ✓ | - | - | - | - | - | - | - | - | - | - | - | - | - |
+| **Compound** | ✓ | - | ✓ | ✓ | - | ✓ | ✓ | - | - | ✓ | ✓ | ✓ | - | - |
+| **data-slot** | ✓ | ✓ | - | - | - | - | - | ✓ | - | - | - | - | - | - |
+| **CVA** | ✓ | ✓ | - | - | - | - | - | ✓ | - | - | - | - | - | - |
+| **RHF Compatible** | ✓ | - | - | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | - | - | - | - |
+
+#### Nomenclatura Comparada
+
+| Conceito | ETUS | Chakra | MUI | Mantine | Carbon | Fluent |
+|----------|------|--------|-----|---------|--------|--------|
+| **Container** | `Field` | `FormControl` | `FormControl` | `Input.Wrapper` | `FormGroup` | `Field` |
+| **Label** | `FieldLabel` | `FormLabel` | `InputLabel` | `Input.Label` | `FormLabel` | `Label` |
+| **Helper** | `FieldDescription` | `FormHelperText` | `FormHelperText` | `Input.Description` | `FormHelperText` | `FieldHint` |
+| **Error** | `FieldError` | `FormErrorMessage` | `FormHelperText` | `Input.Error` | `FormHelperText` | `FieldError` |
+| **Group** | `FieldGroup` | `Stack` | - | `Fieldset` | `FormGroup` | `Fieldset` |
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo | Componente | Uso |
+|----------|------------|-----|
+| `role="group"` | Field | Agrupa elementos relacionados |
+| `role="alert"` | FieldError | Anuncia erros para screen readers |
+| `data-invalid="true"` | Field | Indica estado de erro |
+| `data-disabled="true"` | Field | Indica estado desabilitado |
+| `data-orientation` | Field | Indica orientacao do layout |
+| `aria-describedby` | Input | Referencia FieldDescription |
+| `aria-errormessage` | Input | Referencia FieldError |
+
+### Suporte a Teclado
+
+| Tecla | Acao |
+|-------|------|
+| `Tab` | Navega entre campos focaveis |
+| `Enter/Space` | Ativa checkboxes/radios dentro de FieldLabel |
+| `Arrow Keys` | Navega em radio groups |
+
+### Associacao Label-Input
+
+```tsx
+// FieldLabel automaticamente associa ao input filho
+<Field>
+  <FieldLabel htmlFor="email">Email</FieldLabel>
+  <Input id="email" />
+</Field>
+
+// Ou com labels clicaveis envolvendo o input
+<Field>
+  <FieldLabel>
+    <Checkbox />
+    Aceito os termos
+  </FieldLabel>
+</Field>
+```
+
+### Screen Readers
+
+- `FieldError` com `role="alert"` anuncia erros automaticamente
+- `FieldDescription` deve ser associada via `aria-describedby`
+- `FieldLegend` e anunciado como titulo do grupo
+- Evitar texto generico como "Campo obrigatorio"
+
+### Contraste de Cores
+
+| Elemento | Foreground | Background | Ratio |
+|----------|------------|------------|-------|
+| Label | `--foreground` | - | N/A (texto) |
+| Description | `--muted-foreground` | - | >= 4.5:1 |
+| Error | `--destructive` | - | >= 4.5:1 |
+
+### Comparativo A11y (14 Design Systems)
+
+| Feature | ETUS | React Aria | Radix | Ariakit | Chakra | MUI | Mantine | Fluent | Carbon |
+|---------|:----:|:----------:|:-----:|:-------:|:------:|:---:|:-------:|:------:|:------:|
+| **Auto ARIA** | ~ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **role="group"** | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ |
+| **role="alert"** | ✓ | ✓ | - | ✓ | ✓ | - | ✓ | ✓ | ✓ |
+| **aria-describedby** | ~ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **aria-errormessage** | ~ | ✓ | - | ✓ | ✓ | - | ✓ | ✓ | ✓ |
+| **Label association** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Required indicator** | ~ | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Error announcements** | ✓ | ✓ | - | ✓ | ✓ | - | ✓ | ✓ | ✓ |
+
+**Legenda:** ✓ = Suporte completo | ~ = Manual/Parcial | - = Nao suportado
+
+---
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import {
+  Field,
+  FieldLabel,
+  FieldDescription,
+  FieldError
+} from "@etus/ui"
+import { Input } from "@etus/ui"
+
+function BasicField() {
+  return (
+    <Field>
+      <FieldLabel htmlFor="email">Email</FieldLabel>
+      <Input id="email" type="email" placeholder="seu@email.com" />
+      <FieldDescription>Usaremos para notificacoes importantes</FieldDescription>
+    </Field>
+  )
+}
+```
+
+### Orientacoes
+
+```tsx
+// Vertical (padrao)
+<Field orientation="vertical">
+  <FieldLabel>Nome</FieldLabel>
+  <Input />
+</Field>
+
+// Horizontal
+<Field orientation="horizontal">
+  <FieldLabel>Nome</FieldLabel>
+  <Input />
+</Field>
+
+// Responsivo (vertical mobile, horizontal desktop)
+<FieldGroup>
+  <Field orientation="responsive">
+    <FieldLabel>Nome</FieldLabel>
+    <Input />
+  </Field>
+</FieldGroup>
+```
+
+### Com Validacao de Erros
+
+```tsx
+import { useForm } from "react-hook-form"
+import { zodResolver } from "@hookform/resolvers/zod"
+import { z } from "zod"
+
+const schema = z.object({
+  email: z.string().email("Email invalido"),
+  password: z.string().min(8, "Minimo 8 caracteres"),
+})
+
+function FormWithValidation() {
+  const { register, handleSubmit, formState: { errors } } = useForm({
+    resolver: zodResolver(schema),
+  })
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <FieldGroup>
+        <Field data-invalid={!!errors.email}>
+          <FieldLabel htmlFor="email">Email</FieldLabel>
+          <Input id="email" {...register("email")} />
+          <FieldError errors={[errors.email]} />
+        </Field>
+
+        <Field data-invalid={!!errors.password}>
+          <FieldLabel htmlFor="password">Senha</FieldLabel>
+          <Input id="password" type="password" {...register("password")} />
+          <FieldDescription>Minimo 8 caracteres</FieldDescription>
+          <FieldError errors={[errors.password]} />
+        </Field>
+      </FieldGroup>
+    </form>
+  )
+}
+```
+
+### FieldSet com Legend
+
+```tsx
+<FieldSet>
+  <FieldLegend>Informacoes Pessoais</FieldLegend>
+  <FieldDescription>Preencha seus dados basicos</FieldDescription>
+
+  <FieldGroup>
+    <Field>
+      <FieldLabel>Nome Completo</FieldLabel>
+      <Input />
+    </Field>
+
+    <Field>
+      <FieldLabel>Data de Nascimento</FieldLabel>
+      <Input type="date" />
+    </Field>
+  </FieldGroup>
+</FieldSet>
+```
+
+### Checkbox/Radio com Labels Clicaveis
+
+```tsx
+<FieldSet>
+  <FieldLegend variant="label">Notificacoes</FieldLegend>
+
+  <Field orientation="horizontal">
+    <FieldLabel className="cursor-pointer">
+      <Checkbox />
+      Email marketing
+    </FieldLabel>
+    <FieldDescription>Receba ofertas e novidades</FieldDescription>
+  </Field>
+
+  <Field orientation="horizontal">
+    <FieldLabel className="cursor-pointer">
+      <Checkbox />
+      SMS
+    </FieldLabel>
+    <FieldDescription>Alertas importantes</FieldDescription>
+  </Field>
+</FieldSet>
+```
+
+### Radio Group
+
+```tsx
+<FieldSet>
+  <FieldLegend>Plano de Assinatura</FieldLegend>
+
+  <RadioGroup>
+    <Field orientation="horizontal">
+      <FieldLabel className="w-full cursor-pointer rounded-lg border p-4">
+        <RadioGroupItem value="basic" />
+        <FieldContent>
+          <FieldTitle>Basico</FieldTitle>
+          <FieldDescription>R$ 29/mes - 5 usuarios</FieldDescription>
+        </FieldContent>
+      </FieldLabel>
+    </Field>
+
+    <Field orientation="horizontal">
+      <FieldLabel className="w-full cursor-pointer rounded-lg border p-4">
+        <RadioGroupItem value="pro" />
+        <FieldContent>
+          <FieldTitle>Pro</FieldTitle>
+          <FieldDescription>R$ 79/mes - Usuarios ilimitados</FieldDescription>
+        </FieldContent>
+      </FieldLabel>
+    </Field>
+  </RadioGroup>
+</FieldSet>
+```
+
+### Com Separador
+
+```tsx
+<FieldGroup>
+  <Field>
+    <FieldLabel>Email</FieldLabel>
+    <Input />
+  </Field>
+
+  <FieldSeparator>ou</FieldSeparator>
+
+  <Field>
+    <FieldLabel>Telefone</FieldLabel>
+    <Input />
+  </Field>
+</FieldGroup>
+```
+
+### Multiplos Erros
+
+```tsx
+<Field data-invalid>
+  <FieldLabel>Senha</FieldLabel>
+  <Input type="password" />
+  <FieldError
+    errors={[
+      { message: "Deve ter pelo menos 8 caracteres" },
+      { message: "Deve conter um numero" },
+      { message: "Deve conter uma letra maiuscula" },
+    ]}
+  />
+</Field>
+```
+
+### Com Content (Input + Description)
+
+```tsx
+<Field>
+  <FieldLabel>Username</FieldLabel>
+  <FieldContent>
+    <Input placeholder="@usuario" />
+    <FieldDescription>
+      Este sera seu identificador unico. <a href="/terms">Ver regras</a>
+    </FieldDescription>
+  </FieldContent>
+</Field>
+```
+
+---
+
+## Testes
+
+### Testes Unitarios
+
+```tsx
+// Field.test.tsx
+import { render, screen } from "@testing-library/react"
+import { describe, expect, it } from "vitest"
+import {
+  Field,
+  FieldLabel,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldSet,
+  FieldLegend
+} from "./Field"
+
+describe("Field", () => {
+  it("renders with correct data-slot", () => {
+    render(
+      <Field>
+        <span>Content</span>
+      </Field>
+    )
+    expect(screen.getByRole("group")).toHaveAttribute("data-slot", "field")
+  })
+
+  it("applies orientation classes", () => {
+    render(
+      <Field orientation="horizontal">
+        <span>Content</span>
+      </Field>
+    )
+    expect(screen.getByRole("group")).toHaveClass("flex-row")
+  })
+
+  it("applies data-invalid attribute", () => {
+    render(
+      <Field data-invalid={true}>
+        <span>Content</span>
+      </Field>
+    )
+    expect(screen.getByRole("group")).toHaveAttribute("data-invalid", "true")
+  })
+
+  it("merges custom className", () => {
+    render(
+      <Field className="custom-class">
+        <span>Content</span>
+      </Field>
+    )
+    expect(screen.getByRole("group")).toHaveClass("custom-class")
+  })
+})
+```
+
+### Testes de Composicao
+
+```tsx
+describe("Field compound components", () => {
+  it("renders complete field structure", () => {
+    render(
+      <Field>
+        <FieldLabel htmlFor="test">Label</FieldLabel>
+        <input id="test" data-testid="input" />
+        <FieldDescription>Helper text</FieldDescription>
+      </Field>
+    )
+
+    expect(screen.getByText("Label")).toHaveAttribute("data-slot", "field-label")
+    expect(screen.getByText("Helper text")).toHaveAttribute("data-slot", "field-description")
+    expect(screen.getByTestId("input")).toBeInTheDocument()
+  })
+
+  it("renders FieldSet with legend", () => {
+    render(
+      <FieldSet>
+        <FieldLegend>Group Title</FieldLegend>
+        <Field>
+          <span>Field content</span>
+        </Field>
+      </FieldSet>
+    )
+
+    expect(screen.getByRole("group")).toHaveAttribute("data-slot", "field-set")
+    expect(screen.getByText("Group Title")).toHaveAttribute("data-slot", "field-legend")
+  })
+})
+```
+
+### Testes de FieldError
+
+```tsx
+describe("FieldError", () => {
+  it("renders single error message", () => {
+    render(
+      <FieldError errors={[{ message: "Required field" }]} />
+    )
+
+    expect(screen.getByRole("alert")).toHaveTextContent("Required field")
+  })
+
+  it("renders multiple errors as list", () => {
+    render(
+      <FieldError
+        errors={[
+          { message: "Error 1" },
+          { message: "Error 2" },
+        ]}
+      />
+    )
+
+    expect(screen.getByRole("alert")).toContainElement(screen.getByText("Error 1"))
+    expect(screen.getByRole("alert")).toContainElement(screen.getByText("Error 2"))
+  })
+
+  it("deduplicates identical error messages", () => {
+    render(
+      <FieldError
+        errors={[
+          { message: "Same error" },
+          { message: "Same error" },
+        ]}
+      />
+    )
+
+    expect(screen.getAllByText("Same error")).toHaveLength(1)
+  })
+
+  it("renders children instead of errors when provided", () => {
+    render(
+      <FieldError errors={[{ message: "Ignored" }]}>
+        Custom error message
+      </FieldError>
+    )
+
+    expect(screen.getByRole("alert")).toHaveTextContent("Custom error message")
+    expect(screen.queryByText("Ignored")).not.toBeInTheDocument()
+  })
+
+  it("renders nothing when no errors and no children", () => {
+    const { container } = render(
+      <FieldError errors={[]} />
+    )
+
+    expect(container).toBeEmptyDOMElement()
+  })
+})
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"
+
+expect.extend(toHaveNoViolations)
+
+describe("Field accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <Field>
+        <FieldLabel htmlFor="email">Email</FieldLabel>
+        <input id="email" type="email" aria-describedby="email-desc" />
+        <FieldDescription id="email-desc">Enter your email</FieldDescription>
+      </Field>
+    )
+
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("error message has role alert", () => {
+    render(
+      <FieldError errors={[{ message: "Error" }]} />
+    )
+
+    expect(screen.getByRole("alert")).toBeInTheDocument()
+  })
+
+  it("fieldset has accessible legend", async () => {
+    const { container } = render(
+      <FieldSet>
+        <FieldLegend>Personal Info</FieldLegend>
+        <Field>
+          <FieldLabel htmlFor="name">Name</FieldLabel>
+          <input id="name" />
+        </Field>
+      </FieldSet>
+    )
+
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+})
+```
+
+### Testes de Orientacao
+
+```tsx
+describe("Field orientation", () => {
+  const orientations = ["vertical", "horizontal", "responsive"] as const
+
+  orientations.forEach((orientation) => {
+    it(`renders ${orientation} orientation`, () => {
+      render(
+        <Field orientation={orientation}>
+          <FieldLabel>Label</FieldLabel>
+          <input />
+        </Field>
+      )
+
+      expect(screen.getByRole("group")).toHaveAttribute(
+        "data-orientation",
+        orientation
+      )
+    })
+  })
+
+  it("defaults to vertical orientation", () => {
+    render(
+      <Field>
+        <span>Content</span>
+      </Field>
+    )
+
+    expect(screen.getByRole("group")).toHaveClass("flex-col")
+  })
+})
+```
+
+### Testes de Integracao com React Hook Form
+
+```tsx
+import { useForm } from "react-hook-form"
+
+describe("Field with React Hook Form", () => {
+  function TestForm({ onSubmit }: { onSubmit: (data: any) => void }) {
+    const { register, handleSubmit, formState: { errors } } = useForm()
+
+    return (
+      <form onSubmit={handleSubmit(onSubmit)}>
+        <Field data-invalid={!!errors.email}>
+          <FieldLabel htmlFor="email">Email</FieldLabel>
+          <input
+            id="email"
+            {...register("email", { required: "Email required" })}
+          />
+          <FieldError errors={[errors.email]} />
+        </Field>
+        <button type="submit">Submit</button>
+      </form>
+    )
+  }
+
+  it("displays validation errors", async () => {
+    const user = userEvent.setup()
+    const onSubmit = vi.fn()
+
+    render(<TestForm onSubmit={onSubmit} />)
+
+    await user.click(screen.getByRole("button", { name: "Submit" }))
+
+    expect(await screen.findByRole("alert")).toHaveTextContent("Email required")
+    expect(onSubmit).not.toHaveBeenCalled()
+  })
+
+  it("submits valid form", async () => {
+    const user = userEvent.setup()
+    const onSubmit = vi.fn()
+
+    render(<TestForm onSubmit={onSubmit} />)
+
+    await user.type(screen.getByLabelText("Email"), "test@email.com")
+    await user.click(screen.getByRole("button", { name: "Submit" }))
+
+    await waitFor(() => {
+      expect(onSubmit).toHaveBeenCalledWith(
+        expect.objectContaining({ email: "test@email.com" }),
+        expect.anything()
+      )
+    })
+  })
+})
+```
+
+### Cenarios Criticos
+
+```tsx
+describe("Field edge cases", () => {
+  it("handles nested Field components", () => {
+    render(
+      <Field>
+        <FieldLabel>
+          <Field>
+            <span>Nested</span>
+          </Field>
+        </FieldLabel>
+      </Field>
+    )
+
+    expect(screen.getAllByRole("group")).toHaveLength(2)
+  })
+
+  it("FieldSeparator renders with text", () => {
+    render(
+      <FieldSeparator>or</FieldSeparator>
+    )
+
+    expect(screen.getByText("or")).toBeInTheDocument()
+    expect(screen.getByText("or").closest("[data-slot]")).toHaveAttribute(
+      "data-slot",
+      "field-separator"
+    )
+  })
+
+  it("FieldDescription renders links correctly", () => {
+    render(
+      <FieldDescription>
+        Read our <a href="/terms">terms</a>
+      </FieldDescription>
+    )
+
+    expect(screen.getByRole("link")).toHaveAttribute("href", "/terms")
+    expect(screen.getByRole("link")).toHaveClass("underline")
+  })
+})
+```
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System | Documentacao | GitHub |
+|---------------|-------------|--------|
+| **Shadcn/ui** | [Form](https://ui.shadcn.com/docs/components/form) | [shadcn-ui/ui](https://github.com/shadcn-ui/ui) |
+| **Radix UI** | [Label](https://www.radix-ui.com/primitives/docs/components/label) | [radix-ui/primitives](https://github.com/radix-ui/primitives) |
+| **React Aria** | [TextField](https://react-spectrum.adobe.com/react-aria/TextField.html) | [adobe/react-spectrum](https://github.com/adobe/react-spectrum) |
+| **Chakra UI** | [Form Control](https://chakra-ui.com/docs/components/form-control) | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui) |
+| **MUI** | [Form Control](https://mui.com/material-ui/react-text-field/) | [mui/material-ui](https://github.com/mui/material-ui) |
+| **Mantine** | [Input Wrapper](https://mantine.dev/core/input/#inputwrapper-component) | [mantinedev/mantine](https://github.com/mantinedev/mantine) |
+| **Ant Design** | [Form](https://ant.design/components/form) | [ant-design/ant-design](https://github.com/ant-design/ant-design) |
+| **NextUI** | [Input](https://nextui.org/docs/components/input) | [nextui-org/nextui](https://github.com/nextui-org/nextui) |
+| **Headless UI** | [Field](https://headlessui.com/react/field) | [tailwindlabs/headlessui](https://github.com/tailwindlabs/headlessui) |
+| **Ariakit** | [Form](https://ariakit.org/components/form) | [ariakit/ariakit](https://github.com/ariakit/ariakit) |
+| **Fluent UI** | [Field](https://react.fluentui.dev/?path=/docs/components-field--default) | [microsoft/fluentui](https://github.com/microsoft/fluentui) |
+| **Carbon** | [Form](https://carbondesignsystem.com/components/form/usage/) | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+| **Blueprint** | [FormGroup](https://blueprintjs.com/docs/#core/components/form-group) | [palantir/blueprint](https://github.com/palantir/blueprint) |
+| **PrimeReact** | [FloatLabel](https://primereact.org/floatlabel/) | [primefaces/primereact](https://github.com/primefaces/primereact) |
+
+### Especificacoes e Padroes
+
+- [WAI-ARIA APG - Forms](https://www.w3.org/WAI/ARIA/apg/patterns/form/)
+- [WCAG 2.1 - Labels or Instructions](https://www.w3.org/WAI/WCAG21/Understanding/labels-or-instructions.html)
+- [MDN - Fieldset Element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/fieldset)
+- [MDN - Label Element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label)
+- [HTML Spec - Form Elements](https://html.spec.whatwg.org/multipage/form-elements.html)
+
+### Ferramentas Utilizadas
+
+- [CVA - Class Variance Authority](https://cva.style/docs)
+- [Tailwind CSS v4](https://tailwindcss.com/docs)
+- [React Hook Form](https://react-hook-form.com/)
+- [Zod](https://zod.dev/)